Deprecate getOriginalXmlWithIds() #516

shunkica · 2025-10-19T09:43:20Z

As per the discussion in issue #512 , this PR removes the internal usages of the getOriginalXmlWithIds() function and marks it deprecated.

Summary by CodeRabbit

Documentation
- Marked the method for retrieving original XML with ID attributes as deprecated; will be removed in a future release. Guidance added to use configuration option to control signature placement.
Public API
- Updated the primary API for obtaining signed XML; users should migrate to the newer retrieval method.
Tests
- Test coverage updated to align with the new signed-XML output and API behavior.

coderabbitai · 2025-10-19T09:43:27Z

Walkthrough

The PR deprecates SignedXml.getOriginalXmlWithIds by replacing the method with a deprecate-wrapped property, updates README documentation, and migrates tests to use getSignedXml with adjusted XPath assertions.

Changes

Cohort / File(s)	Summary
Documentation & Guidance `README.md`	Marked `getOriginalXmlWithIds()` as deprecated, notes future removal, and points to using `ComputeSignatureOptionsLocation` for signature placement
API Deprecation `src/signed-xml.ts`	Replaced the concrete `getOriginalXmlWithIds()` method with a property assigned to a `deprecate(() => string, ...)` wrapper; JSDoc updated to include deprecation note; implementation still returns the same value
Test Migration `test/signature-unit-tests.spec.ts`	Replaced calls to `getOriginalXmlWithIds()` with `getSignedXml()` and updated XPath attribute queries to target the `x` element's attributes (//[local-name(.)='x']/@); adjusted assertions accordingly
Metadata `package.json`, `manifest_file`	Included metadata updates referenced in diff (e.g., manifest/package entries)

Sequence Diagram(s)

(Skipped — changes are limited to API deprecation, docs, and test updates; no runtime control-flow changes to illustrate.)

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Potential review focus:

src/signed-xml.ts: confirm deprecate wrapper preserves behavior and typing.
Tests: ensure replacements to getSignedXml() and XPath updates correctly reflect intended assertions.
README: verify wording and links for migration guidance.

Possibly related PRs

Add support for inserting and signing Object elements inside the Signature #506 — also modifies SignedXml handling of "original XML with IDs" and related signing flow; strong code-level connection.

Suggested reviewers

cjbarth

Poem

🐰
A method once hopped through every line,
Now wrapped in deprecate, politely resigned.
Tests learn a new path, signatures in view,
Compute options guide where the mark should accrue.
Forward I nibble, a small, tidy find.

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run `@coderabbitai generate docstrings` to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The pull request title "Deprecate getOriginalXmlWithIds()" directly and accurately reflects the primary objective of the changeset. The PR explicitly aims to mark the getOriginalXmlWithIds() method as deprecated, which is evidenced across all modified files: the README.md documents it as deprecated, src/signed-xml.ts wraps the method with deprecation handling, and test files are updated to use alternative methods. The title is specific, concise, and clearly communicates the main change without vagueness or misleading information.

✨ Finishing touches

📝 Generate docstrings

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 0

🧹 Nitpick comments (1)

src/signed-xml.ts (1)
1281-1283: Consider keeping it as a method to avoid per-instance overhead.

While the current implementation maintains backward compatibility, converting the method to a class field has memory implications: each SignedXml instance now allocates its own deprecate-wrapped function. Additionally, as a property, it could be inadvertently reassigned.

Consider this alternative that preserves the method signature:
  /**
   * Returns the original xml with Id attributes added on relevant elements, must be called only after {@link computeSignature}
   *
   * @returns The original XML with IDs.
   * @deprecated This function is deprecated and will be removed in a future version. Use ComputeSignatureOptionsLocation to control where the signature will be placed in the original XML.
   */
-  getOriginalXmlWithIds = deprecate((): string => {
+  getOriginalXmlWithIds(): string {
+    this.logDeprecation();
     return this.originalXmlWithIds;
-  }, "`getOriginalXmlWithIds()` is deprecated and will be removed in a future version. Use ComputeSignatureOptionsLocation to control where the signature will be placed in the original XML.");
+  }
+
+  private logDeprecation = deprecate(() => {}, "`getOriginalXmlWithIds()` is deprecated and will be removed in a future version. Use ComputeSignatureOptionsLocation to control where the signature will be placed in the original XML.");
This approach:

Keeps it as a method (avoiding per-instance function allocation)

Prevents reassignment

Maintains TypeScript method types

Still emits the deprecation warning when called

Alternatively, if the current pattern is preferred, it's functional and the memory overhead may be acceptable depending on instance count.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 02a405a and b25ea5a.

📒 Files selected for processing (3)

README.md (1 hunks)
src/signed-xml.ts (1 hunks)
test/signature-unit-tests.spec.ts (4 hunks)

🧰 Additional context used

🧬 Code graph analysis (1)

test/signature-unit-tests.spec.ts (1)

example/example.js (4)

signedXml (39-39)

sig (9-9)

sig (22-22)

doc (17-17)

🔇 Additional comments (5)

README.md (1)

285-285: LGTM! Clear deprecation notice with migration guidance.

The deprecation documentation is well-written and provides users with a clear alternative approach using ComputeSignatureOptionsLocation.

test/signature-unit-tests.spec.ts (4)

112-113: LGTM! Correct migration to the new API.

The test correctly migrates from the deprecated getOriginalXmlWithIds() to getSignedXml().

175-180: LGTM! Correctly adjusted XPath query for the new API.

The XPath change to target only the 'x' element's attributes is appropriate since getSignedXml() returns the complete signed document including the Signature element, which has its own attributes. This prevents false positives in the attribute count.

539-549: LGTM! Verification ensures IDs are added correctly.

The new verification block properly validates that ID attributes are added to the signed elements in the output XML, maintaining test coverage for functionality previously verified through getOriginalXmlWithIds().

710-720: LGTM! Consistent ID verification pattern.

This verification block follows the same pattern as the earlier one, ensuring comprehensive test coverage for ID attribute addition.

cjbarth · 2025-10-20T18:27:04Z

Generally I'm on board with reducing code, however, I figured I'd check to see if this API were used elsewhere before I proceeded with this and I found the following (in part):

Some of these projects are very active (>500,000 downloads/week). So, it seems we might need to touch base with them to see what impact deprecating this might have on them.

shunkica · 2025-10-20T19:43:32Z

This just seems like the users are not aware how the signature location can be used within the computeSignature function.

shunkica · 2025-10-20T20:07:48Z

The biggest of these libraries vpulim/node-soap can just refactor from:

    this.signer.computeSignature(xmlWithSec, this.signerOptions);
    const originalXmlWithIds = this.signer.getOriginalXmlWithIds();
    const signatureXml = this.signer.getSignatureXml();
    return insertStr(signatureXml, originalXmlWithIds, originalXmlWithIds.indexOf('</wsse:Security>'));

to

    const computeOptions = {
      ...this.signerOptions,
      location: {
        reference: "//wsse:Security",
        action: "append"
      }
    };
    this.signer.computeSignature(xmlWithSec, computeOptions);
    return this.signer.getSignedXml();

I haven't tested if of course this is just off the cuff.

…node-saml#512

coderabbitai

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between b25ea5a and 063b976.

📒 Files selected for processing (3)

README.md (1 hunks)
src/signed-xml.ts (1 hunks)
test/signature-unit-tests.spec.ts (4 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

src/signed-xml.ts

🧰 Additional context used

🧠 Learnings (2)

📓 Common learnings

Learnt from: shunkica
PR: node-saml/xml-crypto#506
File: src/signed-xml.ts:1159-1159
Timestamp: 2025-10-22T20:36:00.734Z
Learning: In node-saml/xml-crypto PR #506, the maintainer (shunkica) prefers to address the ref.uri mutation inside addAllReferences in a separate PR; removing the in-loop assignment is the desired fix but may be treated as a breaking change. Future guidance: avoid behavioral changes to ref.uri in the current PR.

Learnt from: shunkica
PR: node-saml/xml-crypto#506
File: src/signed-xml.ts:1159-1159
Timestamp: 2025-10-22T21:03:38.309Z
Learning: In node-saml/xml-crypto PR #506, the maintainer (shunkica) requested an issue to separate the overloaded Reference interface into distinct SigningReference and ValidationReference types. Initial hypothesis: signing-only (xpath, isEmptyUri, id, type), validation-only (uri, digestValue, validationError, signedReference), shared (transforms, digestAlgorithm, inclusiveNamespacesPrefixList). This should be proposed and designed in a follow-up, not altered in the current PR.

📚 Learning: 2025-10-22T21:50:05.441Z

Learnt from: shunkica
PR: node-saml/xml-crypto#0
File: :0-0
Timestamp: 2025-10-22T21:50:05.441Z
Learning: In src/signed-xml.ts Line 1099, createReferences mutates ref.uri = id during signing. Maintain this behavior for now; remove/refactor in a separate PR as previously requested by the maintainer.

Applied to files:

test/signature-unit-tests.spec.ts

🔇 Additional comments (4)

test/signature-unit-tests.spec.ts (4)

112-113: LGTM!

The migration from getOriginalXmlWithIds() to getSignedXml() is correct. Both contain the added ID attributes, which is what this test verifies.

175-180: Excellent XPath fix with clear documentation.

The updated XPath //*[local-name(.)='x']/@* correctly isolates the 'x' element's attributes, preventing the count from including signature attributes introduced by getSignedXml(). The explanatory comment is helpful.

539-549: LGTM!

The ID verification logic correctly migrates to use getSignedXml(). The XPath queries properly locate ID attributes on the signed elements, and the assertions verify the expected incremental ID values.

710-720: LGTM!

Consistent with the earlier ID verification block at lines 539-549. The migration correctly verifies ID attributes in the signed XML for the prefixed signature test case.

README.md

shunkica · 2025-10-25T08:21:49Z

I ran some benchmarks with and without originalXmlWithIds. The speed difference is negligible, but the memory difference is significant.
I could create a separate branch for the benchmark etc. but I don't think it is necessary since it is very clear where these numbers are coming from.
The larger the XML file is the more relative impact this has.

#	File	Size	Time Impact	Abs Time Overhead	Memory Impact	Abs Mem Overhead	WITH Time	WITHOUT Time	WITH Mem	WITHOUT Mem
0	small-100kb	100KB	+15.56%	+4.56ms	+12.35%	0.09 MB	33.89ms	29.33ms	0.86 MB	0.76 MB
1	medium-1mb	1024KB	+2.08%	+2.61ms	+26.68%	1.00 MB	128.37ms	125.76ms	4.75 MB	3.75 MB
2	large-10mb	10240KB	+8.07%	+62.19ms	+31.07%	10.00 MB	832.39ms	770.20ms	42.18 MB	32.18 MB

cjbarth · 2025-10-25T11:54:33Z

Honestly, getting rid of foot-guns (must be called after...) is a really good idea. I'd like to expand the README example section a little to cover some of the cases I found already existing on GitHub.

Also, a 5% increase in speed is nothing to sneeze at either. Did you just comment out the code that calls .toString() on doc to get these numbers?

shunkica · 2025-10-25T14:06:08Z

Honestly, getting rid of foot-guns (must be called after...) is a really good idea. I'd like to expand the README example section a little to cover some of the cases I found already existing on GitHub.

Also, a 5% increase in speed is nothing to sneeze at either. Did you just comment out the code that calls .toString() on doc to get these numbers?

Basically yes. I added a options flag to skip assigning it it so I could run all the benchmarks at once.

coderabbitai bot reviewed Oct 19, 2025

View reviewed changes

deprecate: originalXmlWithIds and getOriginalXmlWithIds() as per issue …

063b976

…node-saml#512

shunkica force-pushed the deprecate-originalxmlwithids branch from b25ea5a to 063b976 Compare October 25, 2025 06:47

coderabbitai bot reviewed Oct 25, 2025

View reviewed changes

README.md Show resolved Hide resolved

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Deprecate getOriginalXmlWithIds() #516

Deprecate getOriginalXmlWithIds() #516

Uh oh!

shunkica commented Oct 19, 2025 •

edited by coderabbitai bot

Loading

Uh oh!

coderabbitai bot commented Oct 19, 2025 •

edited

Loading

Uh oh!

coderabbitai bot left a comment

Uh oh!

cjbarth commented Oct 20, 2025

Uh oh!

shunkica commented Oct 20, 2025

Uh oh!

shunkica commented Oct 20, 2025

Uh oh!

coderabbitai bot left a comment

Uh oh!

Uh oh!

shunkica commented Oct 25, 2025 •

edited

Loading

Uh oh!

cjbarth commented Oct 25, 2025

Uh oh!

shunkica commented Oct 25, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Deprecate getOriginalXmlWithIds() #516

Are you sure you want to change the base?

Deprecate getOriginalXmlWithIds() #516

Uh oh!

Conversation

shunkica commented Oct 19, 2025 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

coderabbitai bot commented Oct 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

Estimated code review effort

Possibly related PRs

Suggested reviewers

Poem

Pre-merge checks and finishing touches

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

cjbarth commented Oct 20, 2025

Uh oh!

shunkica commented Oct 20, 2025

Uh oh!

shunkica commented Oct 20, 2025

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

shunkica commented Oct 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cjbarth commented Oct 25, 2025

Uh oh!

shunkica commented Oct 25, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

shunkica commented Oct 19, 2025 •

edited by coderabbitai bot

Loading

coderabbitai bot commented Oct 19, 2025 •

edited

Loading

shunkica commented Oct 25, 2025 •

edited

Loading