chore: deprecate validateElementAgainstReferences()

README.md

@@ -365,6 +365,8 @@ To verify xml documents:
 - `loadSignature(signatureXml)` - loads the signature where:
   - `signatureXml` - a string or node object (like an [xmldom](https://github.com/xmldom/xmldom) node) containing the xml representation of the signature
 - `checkSignature(xml)` - validates the given xml document and returns `true` if the validation was successful
+- `getSignedReferences()` - returns the canonical XML of each reference, only after `checkSignature` succeeds
+- `validateElementAgainstReferences(elemOrXpath, doc)` - **[deprecated]** after `checkSignature` succeeds, use the XML that `getSignedReferences()` returns instead of nodes from the original document
 
 ## Customizing Algorithms
 

src/signed-xml.ts

@@ -44,6 +44,12 @@ const warnOriginalXmlWithIds = deprecate(
   "XML_CRYPTO_GET_ORIGINAL_XML_WITH_IDS",
 );
 
+const warnValidateElementAgainstReferences = deprecate(
+  () => {},
+  "`validateElementAgainstReferences()` is deprecated and will be removed in a future version. After `checkSignature()` succeeds, use the XML that `getSignedReferences()` returns instead of nodes from the original document.",
+  "XML_CRYPTO_VALIDATE_ELEMENT_AGAINST_REFERENCES",
+);
+
 export class SignedXml {
   idMode?: "wssecurity";
   idAttributes: string[];
@@ -503,7 +509,12 @@ export class SignedXml {
     }
   }
 
+  /**
+   * @deprecated Will be removed in a future version. After {@link checkSignature} succeeds, use
+   * the XML that {@link getSignedReferences} returns instead of nodes from the original document.
+   */
   validateElementAgainstReferences(elemOrXpath: Element | string, doc: Document): Reference {
+    warnValidateElementAgainstReferences();
     let elem: Element;
     if (typeof elemOrXpath === "string") {
       const firstElem = xpath.select1(elemOrXpath, doc);

test/signature-unit-tests.spec.ts

@@ -911,6 +911,7 @@ describe("Signature unit tests", function () {
 
         const firstGrandchild = doc.firstChild?.firstChild;
         isDomNode.assertIsElementNode(firstGrandchild);
+        /* eslint-disable-next-line deprecation/deprecation */
         const matchedReference = sig.validateElementAgainstReferences(firstGrandchild, doc);
         expect(matchedReference).to.not.be.false;