docs: cover detached signatures in the getOriginalXmlWithIds() deprecation

[cjbarth]

Summary

The deprecation advice for getOriginalXmlWithIds(), to place the signature with location and then read getSignedXml(), only helps callers who embed the signature. A detached signature is sent apart from the document it covers, and the only reason to fetch the original with IDs is that the library generated those IDs.

The runtime warning, the JSDoc and the README entry now also say: for a detached signature, put an ID attribute the signer recognizes on each referenced element (wsu:Id for WS-Security), sign that document, and send it alongside getSignatureXml().

• The ID has to be one the signer recognizes. With WS-Security IDs a plain Id is ignored: the signer adds its own wsu:Id and references that, so the document the caller sends does not verify. The advice names wsu:Id rather than idMode, which Add XmlDSigVerifier wrapper for SignedXml #519 plans to deprecate in favour of namespaced idAttributes.
• Adding IDs before signing can change what a reference XPath selects, because fix: preserve input references during signature creation #577 evaluates references against the document passed in. /root[not(@Id)] then throws at signing, and an XPath conditioned on another element's ID can silently drop an element from the signature. The README says to check each XPath still selects its intended element, for example by selecting on the ID.

Documentation only; no behaviour change.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Updated detached-signature guidance to require signer-recognized IDs on referenced elements.
  • Clarified that the signed document should be transmitted separately alongside the signature XML.
  • Noted that reference XPaths must continue selecting the intended elements after IDs are added.
• Bug Fixes
  • Clarified the related deprecation warning to reflect the updated detached-signature requirements.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 45b70961-4c7a-46d5-b322-72ca0485b8fb

📥 Commits

Reviewing files that changed from the base of the PR and between 5186dc5 and 8c2941b.

📒 Files selected for processing (2)

• README.md
• src/signed-xml.ts

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

• src/signed-xml.ts
• README.md

Included review availability: Your plan provides up to 2 included reviews per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The change clarifies detached-signature guidance for getOriginalXmlWithIds() in the deprecation warning, JSDoc, and README.

Changes

Detached Signature Guidance

Layer / File(s)	Summary
Update detached-signature guidance src/signed-xml.ts, README.md	The guidance requires a signer-recognized ID on each referenced element before signing. It also states that the signed document must be sent with getSignatureXml() and that reference XPaths must still resolve.

Priority: ⬇️ Low

Estimated code review effort: 1 (Trivial) | ~5 minutes

Change: Other

Merge Risk: ⚪ Minimal · up to 8c294

The change updates detached-signature guidance only, with no identified implementation or documentation-contract defect.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 1…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: updating the deprecation guidance for getOriginalXmlWithIds() to cover detached signatures.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 77.44%. Comparing base (f5c4d22) to head (8c2941b).
⚠️ Report is 9 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #578      +/-   ##
==========================================
+ Coverage   75.95%   77.44%   +1.48%     
==========================================
  Files           9        9              
  Lines        1048     1095      +47     
  Branches      273      278       +5     
==========================================
+ Hits          796      848      +52     
+ Misses        144      139       -5     
  Partials      108      108              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.