samlify 2.12.0 → 2.13.0

package/build/src/libsaml.js

@@ -1,9 +1,21 @@
 "use strict";
 /**
-* @file SamlLib.js
-* @author tngan
-* @desc  A simple library including some common functions
-*/
+ * @file libsaml.ts
+ * @author tngan
+ * @desc SAML primitives: templates, XML signing/verification, assertion
+ * encryption/decryption, and XPath helpers used by the higher-level flows.
+ */
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -91,29 +103,34 @@ Object.defineProperty(exports, "__esModule", { value: true });
 var utility_1 = __importStar(require("./utility"));
 var urn_1 = require("./urn");
 var xpath_1 = require("xpath");
-function toNodeArray(result) {
-    if (Array.isArray(result))
-        return result;
-    if (result != null && typeof result === 'object' && 'nodeType' in result)
-        return [result];
-    return [];
-}
 var node_rsa_1 = __importDefault(require("node-rsa"));
 var xml_crypto_1 = require("xml-crypto");
 var xmlenc = __importStar(require("@authenio/xml-encryption"));
-var utility_2 = require("./utility");
 var api_1 = require("./api");
 var xml_escape_1 = __importDefault(require("xml-escape"));
+var crypto = __importStar(require("crypto"));
 var fs = __importStar(require("fs"));
 var signatureAlgorithms = urn_1.algorithms.signature;
 var digestAlgorithms = urn_1.algorithms.digest;
 var certUse = urn_1.wording.certUse;
 var urlParams = urn_1.wording.urlParams;
+/** Coerce the heterogeneous return of `xpath.select` into a Node array. */
+function toNodeArray(result) {
+    if (Array.isArray(result))
+        return result;
+    if (result != null && typeof result === 'object' && 'nodeType' in result) {
+        return [result];
+    }
+    return [];
+}
 var libSaml = function () {
     /**
-    * @desc helper function to get back the query param for redirect binding for SLO/SSO
-    * @type {string}
-    */
+     * Map a SAML URL parameter type onto its canonical query-string key
+     * (`SAMLRequest` or `SAMLResponse`).
+     *
+     * @param type SAML URL parameter name
+     * @returns `SAMLRequest` or `SAMLResponse`
+     */
     function getQueryParamByType(type) {
         if ([urlParams.logoutRequest, urlParams.samlRequest].indexOf(type) !== -1) {
             return 'SAMLRequest';
@@ -124,114 +141,187 @@ var libSaml = function () {
         throw new Error('ERR_UNDEFINED_QUERY_PARAMS');
     }
     /**
+     * Mapping from XML-DSig signature algorithm URIs to node-rsa schemes.
      *
+     * The PSS entry covers the redirect-binding detached signature path:
+     * `node-rsa` accepts `pss-sha256` directly as a `signingScheme` value.
+     * The `xmldsig-more#sha256-rsa-MGF1` URI (W3C Note, 2007-05) is listed
+     * in `xmldsig-core §6.4.2` as the recommended successor to PKCS#1 v1.5
+     * RSA-SHA256 (`saml-sec-consider §6.5`).
      */
     var nrsaAliasMapping = {
         'http://www.w3.org/2000/09/xmldsig#rsa-sha1': 'pkcs1-sha1',
         'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256': 'pkcs1-sha256',
         'http://www.w3.org/2001/04/xmldsig-more#rsa-sha512': 'pkcs1-sha512',
+        'http://www.w3.org/2007/05/xmldsig-more#sha256-rsa-MGF1': 'pss-sha256',
+    };
+    /**
+     * RSASSA-PSS plugin class for `xml-crypto`'s `SignedXml.SignatureAlgorithms`
+     * registry (`xmldsig-core §6.4.2`).
+     *
+     * **Temporary shim.** xml-crypto already implements PSS-SHA256 on its
+     * master branch (PR node-saml/xml-crypto#488, merged 2025-10-17), but
+     * the latest published npm version (6.1.2, 2024-08) predates that
+     * commit. Once xml-crypto cuts a release containing #488, delete this
+     * class and the `registerPssAlgorithms` helper below — the URI alone
+     * in `algorithms.signature` is sufficient and the constructor will
+     * seed `SignatureAlgorithms` with the upstream implementation.
+     *
+     * `RSA_PKCS1_PSS_PADDING` with `RSA_PSS_SALTLEN_DIGEST` matches the
+     * MGF1+SHA-256 convention referenced by the `sha256-rsa-MGF1` URI
+     * (xmldsig-more, W3C Note 2007-05).
+     */
+    var pssPaddingOptions = {
+        padding: crypto.constants.RSA_PKCS1_PSS_PADDING,
+        saltLength: crypto.constants.RSA_PSS_SALTLEN_DIGEST,
     };
+    var RsaSha256Mgf1 = /** @class */ (function () {
+        function RsaSha256Mgf1() {
+            this.getSignature = function (signedInfo, privateKey) {
+                var signOpts = {
+                    key: privateKey,
+                    padding: pssPaddingOptions.padding,
+                    saltLength: pssPaddingOptions.saltLength,
+                };
+                return crypto.sign('RSA-SHA256', Buffer.from(signedInfo), signOpts).toString('base64');
+            };
+            this.verifySignature = function (material, key, signatureValue) {
+                var verifyOpts = {
+                    key: key,
+                    padding: pssPaddingOptions.padding,
+                    saltLength: pssPaddingOptions.saltLength,
+                };
+                return crypto.verify('RSA-SHA256', Buffer.from(material), verifyOpts, Buffer.from(signatureValue, 'base64'));
+            };
+            this.getAlgorithmName = function () { return 'http://www.w3.org/2007/05/xmldsig-more#sha256-rsa-MGF1'; };
+        }
+        return RsaSha256Mgf1;
+    }());
+    /**
+     * Register the RSASSA-PSS SHA-256 signature class on a fresh `SignedXml`
+     * instance so the algorithm-agility surface from `xmldsig-core §6.4` is
+     * available for both signing and verification. PKCS#1 v1.5 entries are
+     * preserved untouched.
+     */
+    function registerPssAlgorithms(sig) {
+        sig.SignatureAlgorithms = __assign(__assign({}, sig.SignatureAlgorithms), { 'http://www.w3.org/2007/05/xmldsig-more#sha256-rsa-MGF1': RsaSha256Mgf1 });
+    }
     /**
-    * @desc Default login request template
-    * @type {LoginRequestTemplate}
-    */
+     * Default AuthnRequest XML template.
+     *
+     * Per saml-core §3.4.1, `ProtocolBinding`, `AssertionConsumerServiceURL`,
+     * and `AssertionConsumerServiceIndex` are all `use="optional"` and
+     * mutually exclusive — when the index is set, neither URL nor
+     * ProtocolBinding may be present. All three are placeholders here so
+     * that `replaceTagsByValue` drops whichever the caller leaves
+     * undefined (closes #437).
+     */
     var defaultLoginRequestTemplate = {
-        context: '<samlp:AuthnRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" ID="{ID}" Version="2.0" IssueInstant="{IssueInstant}" Destination="{Destination}" ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" AssertionConsumerServiceURL="{AssertionConsumerServiceURL}"><saml:Issuer>{Issuer}</saml:Issuer><samlp:NameIDPolicy Format="{NameIDFormat}" AllowCreate="{AllowCreate}"/></samlp:AuthnRequest>',
+        context: '<samlp:AuthnRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" ID="{ID}" Version="2.0" ForceAuthn="{ForceAuthn}" IssueInstant="{IssueInstant}" Destination="{Destination}" ProtocolBinding="{ProtocolBinding}" AssertionConsumerServiceURL="{AssertionConsumerServiceURL}" AssertionConsumerServiceIndex="{AssertionConsumerServiceIndex}"><saml:Issuer>{Issuer}</saml:Issuer><samlp:NameIDPolicy Format="{NameIDFormat}" AllowCreate="{AllowCreate}"/></samlp:AuthnRequest>',
     };
     /**
-    * @desc Default logout request template
-    * @type {LogoutRequestTemplate}
-    */
+     * Default LogoutRequest XML template.
+     *
+     * The optional `<samlp:SessionIndex>` element (saml-core §3.7.1) is
+     * included with a placeholder body. When the caller leaves
+     * `user.sessionIndex` undefined, `replaceTagsByValue` drops the whole
+     * element from the rendered XML, matching the schema's
+     * `minOccurs="0"` declaration.
+     */
     var defaultLogoutRequestTemplate = {
-        context: '<samlp:LogoutRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" ID="{ID}" Version="2.0" IssueInstant="{IssueInstant}" Destination="{Destination}"><saml:Issuer>{Issuer}</saml:Issuer><saml:NameID Format="{NameIDFormat}">{NameID}</saml:NameID></samlp:LogoutRequest>',
+        context: '<samlp:LogoutRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" ID="{ID}" Version="2.0" IssueInstant="{IssueInstant}" Destination="{Destination}"><saml:Issuer>{Issuer}</saml:Issuer><saml:NameID Format="{NameIDFormat}">{NameID}</saml:NameID><samlp:SessionIndex>{SessionIndex}</samlp:SessionIndex></samlp:LogoutRequest>',
     };
-    /**
-    * @desc Default AttributeStatement template
-    * @type {AttributeStatementTemplate}
-    */
+    /** Default AttributeStatement XML fragment template. */
     var defaultAttributeStatementTemplate = {
         context: '<saml:AttributeStatement>{Attributes}</saml:AttributeStatement>',
     };
-    /**
-    * @desc Default Attribute template
-    * @type {AttributeTemplate}
-    */
+    /** Default Attribute XML fragment template. */
     var defaultAttributeTemplate = {
         context: '<saml:Attribute Name="{Name}" NameFormat="{NameFormat}"><saml:AttributeValue xmlns:xs="{ValueXmlnsXs}" xmlns:xsi="{ValueXmlnsXsi}" xsi:type="{ValueXsiType}">{Value}</saml:AttributeValue></saml:Attribute>',
     };
-    /**
-    * @desc Default login response template
-    * @type {LoginResponseTemplate}
-    */
+    /** Default LoginResponse XML template. */
     var defaultLoginResponseTemplate = {
         context: '<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" ID="{ID}" Version="2.0" IssueInstant="{IssueInstant}" Destination="{Destination}" InResponseTo="{InResponseTo}"><saml:Issuer>{Issuer}</saml:Issuer><samlp:Status><samlp:StatusCode Value="{StatusCode}"/></samlp:Status><saml:Assertion xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" ID="{AssertionID}" Version="2.0" IssueInstant="{IssueInstant}"><saml:Issuer>{Issuer}</saml:Issuer><saml:Subject><saml:NameID Format="{NameIDFormat}">{NameID}</saml:NameID><saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"><saml:SubjectConfirmationData NotOnOrAfter="{SubjectConfirmationDataNotOnOrAfter}" Recipient="{SubjectRecipient}" InResponseTo="{InResponseTo}"/></saml:SubjectConfirmation></saml:Subject><saml:Conditions NotBefore="{ConditionsNotBefore}" NotOnOrAfter="{ConditionsNotOnOrAfter}"><saml:AudienceRestriction><saml:Audience>{Audience}</saml:Audience></saml:AudienceRestriction></saml:Conditions>{AuthnStatement}{AttributeStatement}</saml:Assertion></samlp:Response>',
         attributes: [],
         additionalTemplates: {
-            'attributeStatementTemplate': defaultAttributeStatementTemplate,
-            'attributeTemplate': defaultAttributeTemplate
-        }
+            attributeStatementTemplate: defaultAttributeStatementTemplate,
+            attributeTemplate: defaultAttributeTemplate,
+        },
     };
-    /**
-    * @desc Default logout response template
-    * @type {LogoutResponseTemplate}
-    */
+    /** Default LogoutResponse XML template. */
     var defaultLogoutResponseTemplate = {
         context: '<samlp:LogoutResponse xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" ID="{ID}" Version="2.0" IssueInstant="{IssueInstant}" Destination="{Destination}" InResponseTo="{InResponseTo}"><saml:Issuer>{Issuer}</saml:Issuer><samlp:Status><samlp:StatusCode Value="{StatusCode}"/></samlp:Status></samlp:LogoutResponse>',
     };
     /**
-    * @private
-    * @desc Get the signing scheme alias by signature algorithms, used by the node-rsa module
-    * @param {string} sigAlg    signature algorithm
-    * @return {string/null} signing algorithm short-hand for the module node-rsa
-    */
+     * Map a SAML signature algorithm URI to its node-rsa signing scheme.
+     *
+     * - When `sigAlg` is omitted, the default RSA-SHA256 scheme is used
+     *   (per `saml-bindings §3.4.4.1` recommendation).
+     * - When `sigAlg` is supplied but does not match a known URI, the
+     *   function throws. Silently downgrading to RSA-SHA1 (the previous
+     *   behaviour) was a verification-time vulnerability: an attacker
+     *   could supply an unknown `SigAlg` query parameter to coerce
+     *   verification onto SHA-1, which is collision-broken
+     *   (`saml-sec-consider §6.5`, `xmldsig-core §6.4`).
+     *
+     * @param sigAlg signature algorithm URI
+     * @returns node-rsa signing scheme string
+     * @throws when `sigAlg` is supplied and does not match a supported URI
+     */
     function getSigningScheme(sigAlg) {
-        if (sigAlg) {
-            var algAlias = nrsaAliasMapping[sigAlg];
-            if (!(algAlias === undefined)) {
-                return algAlias;
-            }
+        if (sigAlg === undefined) {
+            return nrsaAliasMapping[signatureAlgorithms.RSA_SHA256];
         }
-        return nrsaAliasMapping[signatureAlgorithms.RSA_SHA1];
+        var algAlias = nrsaAliasMapping[sigAlg];
+        if (algAlias === undefined) {
+            throw new Error('ERR_UNSUPPORTED_SIGNATURE_ALGORITHM');
+        }
+        return algAlias;
     }
     /**
-    * @private
-    * @desc Get the digest algorithms by signature algorithms
-    * @param {string} sigAlg    signature algorithm
-    * @return {string/undefined} digest algorithm
-    */
+     * Return the companion digest URI for a given signature algorithm URI.
+     *
+     * @param sigAlg signature algorithm URI
+     * @returns digest algorithm URI or undefined when unsupported
+     */
     function getDigestMethod(sigAlg) {
         return digestAlgorithms[sigAlg];
     }
     /**
-    * @public
-    * @desc Create XPath
-    * @param  {string/object} local     parameters to create XPath
-    * @param  {boolean} isExtractAll    define whether returns whole content according to the XPath
-    * @return {string} xpath
-    */
+     * Build an XPath expression that matches either a named element or one of
+     * its attributes.
+     *
+     * @param local element name, or `{ name, attr }` for an attribute selector
+     * @param isExtractAll when true the element selector resolves to its text()
+     * @returns XPath expression
+     */
     function createXPath(local, isExtractAll) {
         if ((0, utility_1.isString)(local)) {
             var escaped = (0, utility_1.escapeXPathValue)(local);
-            return isExtractAll === true ? "//*[local-name(.)=" + escaped + "]/text()" : "//*[local-name(.)=" + escaped + "]";
+            return isExtractAll === true
+                ? '//*[local-name(.)=' + escaped + ']/text()'
+                : '//*[local-name(.)=' + escaped + ']';
         }
-        return "//*[local-name(.)=" + (0, utility_1.escapeXPathValue)(local.name) + "]/@" + local.attr;
+        var _a = local, name = _a.name, attr = _a.attr;
+        return '//*[local-name(.)=' + (0, utility_1.escapeXPathValue)(name) + ']/@' + attr;
     }
     /**
-     * @private
-     * @desc Tag normalization
-     * @param {string} prefix     prefix of the tag
-     * @param {content} content   normalize it to capitalized camel case
-     * @return {string}
+     * Capitalise a content string after camel-casing and optionally prefix it.
      */
     function tagging(prefix, content) {
-        var camelContent = (0, utility_2.camelCase)(content);
+        var camelContent = (0, utility_1.camelCase)(content);
         return prefix + camelContent.charAt(0).toUpperCase() + camelContent.slice(1);
     }
+    /**
+     * Replacer for {@link replaceTagsByValue}. Always XML-escapes the
+     * replacement text, in both attribute and element-text contexts, to
+     * prevent SAML attribute/element injection through user-controlled
+     * template values.
+     */
     function escapeTag(replacement) {
         return function (_match, quote) {
-            var text = (replacement === null || replacement === undefined) ? '' : String(replacement);
-            // not having a quote means this interpolation isn't for an attribute, and so does not need escaping
-            return quote ? "".concat(quote).concat((0, xml_escape_1.default)(text)) : text;
+            var text = replacement === null || replacement === undefined ? '' : String(replacement);
+            return quote ? "".concat(quote).concat((0, xml_escape_1.default)(text)) : (0, xml_escape_1.default)(text);
         };
     }
     return {
@@ -244,24 +334,55 @@ var libSaml = function () {
         defaultLogoutRequestTemplate: defaultLogoutRequestTemplate,
         defaultLogoutResponseTemplate: defaultLogoutResponseTemplate,
         /**
-        * @desc Replace the tag (e.g. {tag}) inside the raw XML
-        * @param  {string} rawXML      raw XML string used to do keyword replacement
-        * @param  {array} tagValues    tag values
-        * @return {string}
-        */
+         * Substitute `{Tag}` placeholders inside an XML template with the given
+         * replacement map. Replacement text is XML-escaped in both attribute and
+         * element-text positions to prevent SAML element/attribute injection.
+         *
+         * When a tag's value is `null` or `undefined`:
+         *   - in **attribute position** (`name="{Tag}"`) the entire attribute is
+         *     omitted from the rendered XML, per `saml-core §3.4.1` (every
+         *     `<AuthnRequest>` attribute is `use="optional"`); previously samlify
+         *     emitted `name=""` or the literal `name="undefined"`, which is
+         *     invalid for typed attributes (e.g. `AssertionConsumerServiceURL`
+         *     declared as `xs:anyURI`).
+         *   - in **element-only-body position** (`<X>{Tag}</X>` or
+         *     `<X attr="...">{Tag}</X>`) the entire element is dropped — per
+         *     `saml-core §3.7.1` for `<samlp:SessionIndex>` and any other
+         *     `minOccurs="0"` element where the body is solely a placeholder.
+         *   - in **mixed-text position** (`<X>prefix{Tag}suffix</X>`) the
+         *     placeholder is replaced with the empty string (legacy behaviour).
+         *
+         * @param rawXML template with `{Tag}` placeholders
+         * @param tagValues replacement map keyed by tag name
+         * @returns XML with placeholders resolved
+         */
         replaceTagsByValue: function (rawXML, tagValues) {
             Object.keys(tagValues).forEach(function (t) {
-                rawXML = rawXML.replace(new RegExp("(\"?)\\{".concat(t, "\\}"), 'g'), escapeTag(tagValues[t]));
+                var value = tagValues[t];
+                if (value === null || value === undefined) {
+                    // Drop the entire `\s+name="{Tag}"` (or single-quoted) attribute.
+                    rawXML = rawXML.replace(new RegExp("\\s+[A-Za-z_:][\\w:.-]*=(\"|')\\{".concat(t, "\\}\\1"), 'g'), '');
+                    // Drop the entire `<X ...>{Tag}</X>` element when the placeholder
+                    // is the only body content (allows optional elements to be omitted
+                    // rather than rendered empty).
+                    rawXML = rawXML.replace(new RegExp("<([A-Za-z_:][\\w:.-]*)((?:\\s+[^>]*)?)>\\{".concat(t, "\\}</\\1>"), 'g'), '');
+                    // Replace any remaining `{Tag}` occurrences with empty string.
+                    rawXML = rawXML.replace(new RegExp("\\{".concat(t, "\\}"), 'g'), '');
+                    return;
+                }
+                rawXML = rawXML.replace(new RegExp("(\"?)\\{".concat(t, "\\}"), 'g'), escapeTag(value));
             });
             return rawXML;
         },
         /**
-        * @desc Helper function to build the AttributeStatement tag
-        * @param  {LoginResponseAttribute} attributes    an array of attribute configuration
-        * @param  {AttributeTemplate} attributeTemplate    the attribute tag template to be used
-        * @param  {AttributeStatementTemplate} attributeStatementTemplate    the attributeStatement tag template to be used
-        * @return {string}
-        */
+         * Build a serialized `<AttributeStatement>` from attribute descriptors
+         * by applying the attribute and statement templates.
+         *
+         * @param attributes attribute descriptors (name, format, value)
+         * @param attributeTemplate per-attribute template
+         * @param attributeStatementTemplate wrapping statement template
+         * @returns serialized XML fragment
+         */
         attributeStatementBuilder: function (attributes, attributeTemplate, attributeStatementTemplate) {
             if (attributeTemplate === void 0) { attributeTemplate = defaultAttributeTemplate; }
             if (attributeStatementTemplate === void 0) { attributeStatementTemplate = defaultAttributeStatementTemplate; }
@@ -281,37 +402,37 @@ var libSaml = function () {
             return attributeStatementTemplate.context.replace('{Attributes}', attr);
         },
         /**
-        * @desc Construct the XML signature for POST binding
-        * @param  {string} rawSamlMessage      request/response xml string
-        * @param  {string} referenceTagXPath    reference uri
-        * @param  {string} privateKey           declares the private key
-        * @param  {string} passphrase           passphrase of the private key [optional]
-        * @param  {string|buffer} signingCert   signing certificate
-        * @param  {string} signatureAlgorithm   signature algorithm
-        * @param  {string[]} transformationAlgorithms   canonicalization and transformation Algorithms
-        * @return {string} base64 encoded string
-        */
+         * Compute an XML-DSig signature over the supplied SAML message. Can
+         * sign the message root (`isMessageSigned`), a referenced subtree
+         * (`referenceTagXPath`), or both.
+         *
+         * @param opts signature inputs and layout options
+         * @returns base64 (default) or raw signed XML string
+         */
         constructSAMLSignature: function (opts) {
             var rawSamlMessage = opts.rawSamlMessage, referenceTagXPath = opts.referenceTagXPath, privateKey = opts.privateKey, privateKeyPass = opts.privateKeyPass, _a = opts.signatureAlgorithm, signatureAlgorithm = _a === void 0 ? signatureAlgorithms.RSA_SHA256 : _a, _b = opts.transformationAlgorithms, transformationAlgorithms = _b === void 0 ? [
                 'http://www.w3.org/2000/09/xmldsig#enveloped-signature',
                 'http://www.w3.org/2001/10/xml-exc-c14n#',
             ] : _b, signingCert = opts.signingCert, signatureConfig = opts.signatureConfig, _c = opts.isBase64Output, isBase64Output = _c === void 0 ? true : _c, _d = opts.isMessageSigned, isMessageSigned = _d === void 0 ? false : _d;
             var sig = new xml_crypto_1.SignedXml();
-            // Add assertion sections as reference
+            // xmldsig-core §6.4.2 — make PSS variants available alongside the
+            // PKCS#1 v1.5 set built into xml-crypto v6.x. No-op for callers
+            // staying on RSA-SHA*; required when `signatureAlgorithm` is one of
+            // the `xmldsig-more 2007-05` PSS URIs.
+            registerPssAlgorithms(sig);
             var digestAlgorithm = getDigestMethod(signatureAlgorithm);
             if (referenceTagXPath) {
                 sig.addReference({
                     xpath: referenceTagXPath,
                     transforms: transformationAlgorithms,
-                    digestAlgorithm: digestAlgorithm
+                    digestAlgorithm: digestAlgorithm,
                 });
             }
             if (isMessageSigned) {
                 sig.addReference({
-                    // reference to the root node
                     xpath: '/*',
                     transforms: transformationAlgorithms,
-                    digestAlgorithm: digestAlgorithm
+                    digestAlgorithm: digestAlgorithm,
                 });
             }
             sig.signatureAlgorithm = signatureAlgorithm;
@@ -325,15 +446,20 @@ var libSaml = function () {
             else {
                 sig.computeSignature(rawSamlMessage);
             }
-            return isBase64Output !== false ? utility_1.default.base64Encode(sig.getSignedXml()) : sig.getSignedXml();
+            return isBase64Output !== false
+                ? utility_1.default.base64Encode(sig.getSignedXml())
+                : sig.getSignedXml();
         },
         /**
-        * @desc Verify the XML signature
-        * @param  {string} xml xml
-        * @param  {SignatureVerifierOptions} opts cert declares the X509 certificate
-         * @return {[boolean, string | null]} - A tuple where:
-         *   - The first element is `true` if the signature is valid, `false` otherwise.
-         *   - The second element is the cryptographically authenticated assertion node as a string, or `null` if not found.
+         * Verify an XML-DSig signature on a SAML payload and, on success, return
+         * the cryptographically authenticated assertion node.
+         *
+         * Defends against classic wrapping attacks by rejecting assertions that
+         * appear inside a `SubjectConfirmationData` subtree.
+         *
+         * @param xml SAML message XML
+         * @param opts metadata or key file plus signature algorithm
+         * @returns tuple `[verified, authenticatedAssertion | null]`
          */
         verifySignature: function (xml, opts) {
             var e_1, _a;
@@ -342,30 +468,28 @@ var libSaml = function () {
             var doc = dom.parseFromString(xml);
             var contextDom = (0, api_1.getContext)().dom;
             var docParser = contextDom;
-            // In order to avoid the wrapping attack, we have changed to use absolute xpath instead of naively fetching the signature element
-            // message signature (logout response / saml response)
+            // Absolute XPaths defend against signature-wrapping attacks.
             var messageSignatureXpath = "/*[contains(local-name(), 'Response') or contains(local-name(), 'Request')]/*[local-name(.)='Signature']";
-            // assertion signature (logout response / saml response)
             var assertionSignatureXpath = "/*[contains(local-name(), 'Response') or contains(local-name(), 'Request')]/*[local-name(.)='Assertion']/*[local-name(.)='Signature']";
-            // check if there is a potential malicious wrapping signature
             var wrappingElementsXPath = "/*[contains(local-name(), 'Response')]/*[local-name(.)='Assertion']/*[local-name(.)='Subject']/*[local-name(.)='SubjectConfirmation']/*[local-name(.)='SubjectConfirmationData']//*[local-name(.)='Assertion' or local-name(.)='Signature']";
-            // select the signature node
             var selection = [];
             var messageSignatureNode = toNodeArray((0, xpath_1.select)(messageSignatureXpath, doc));
             var assertionSignatureNode = toNodeArray((0, xpath_1.select)(assertionSignatureXpath, doc));
             var wrappingElementNode = toNodeArray((0, xpath_1.select)(wrappingElementsXPath, doc));
             selection = selection.concat(messageSignatureNode);
             selection = selection.concat(assertionSignatureNode);
-            // try to catch potential wrapping attack
             if (wrappingElementNode.length !== 0) {
                 throw new Error('ERR_POTENTIAL_WRAPPING_ATTACK');
             }
-            // guarantee to have a signature in saml response
             if (selection.length === 0) {
-                return [false, null]; // we return false now
+                return [false, null];
             }
             var _loop_1 = function (signatureNode) {
                 var sig = new xml_crypto_1.SignedXml();
+                // Register PSS plugins on the verifier instance so the algorithm
+                // declared inside the signed XML can resolve to a SignatureAlgorithm
+                // class (xmldsig-core §6.4.2; see `registerPssAlgorithms`).
+                registerPssAlgorithms(sig);
                 var verified = false;
                 sig.signatureAlgorithm = opts.signatureAlgorithm;
                 if (!opts.keyFile && !opts.metadata) {
@@ -376,79 +500,59 @@ var libSaml = function () {
                 }
                 if (opts.metadata) {
                     var certificateNode = toNodeArray((0, xpath_1.select)(".//*[local-name(.)='X509Certificate']", signatureNode));
-                    // certificate in metadata
                     var metadataCert = opts.metadata.getX509Certificate(certUse.signing);
-                    // flattens the nested array of Certificates from each KeyDescriptor
                     if (Array.isArray(metadataCert)) {
                         metadataCert = (0, utility_1.flattenDeep)(metadataCert);
                     }
                     else if (typeof metadataCert === 'string') {
                         metadataCert = [metadataCert];
                     }
-                    // normalise the certificate string
                     metadataCert = metadataCert.map(utility_1.default.normalizeCerString);
-                    // no certificate in node  response nor metadata
                     if (certificateNode.length === 0 && metadataCert.length === 0) {
                         throw new Error('NO_SELECTED_CERTIFICATE');
                     }
-                    // certificate node in response
                     if (certificateNode.length !== 0) {
                         var certEl = certificateNode[0];
                         var x509CertificateData = (_b = certEl.textContent) !== null && _b !== void 0 ? _b : '';
                         var x509Certificate_1 = utility_1.default.normalizeCerString(x509CertificateData);
                         if (metadataCert.length >= 1 &&
                             !metadataCert.find(function (cert) { return cert.trim() === x509Certificate_1.trim(); })) {
-                            // keep this restriction for rolling certificate usage
-                            // to make sure the response certificate is one of those specified in metadata
                             throw new Error('ERROR_UNMATCH_CERTIFICATE_DECLARATION_IN_METADATA');
                         }
                         sig.publicCert = this_1.getKeyInfo(x509Certificate_1).getKey();
                     }
                     else {
-                        // Select first one from metadata
                         sig.publicCert = this_1.getKeyInfo(metadataCert[0]).getKey();
                     }
                 }
                 sig.loadSignature(signatureNode);
                 verified = sig.checkSignature(doc.toString());
-                // immediately throw error when any one of the signature is failed to get verified
                 if (!verified) {
                     return "continue";
-                    // throw new Error('ERR_FAILED_TO_VERIFY_SIGNATURE');
                 }
-                // Require there to be at least one reference that was signed
                 if (!(sig.getSignedReferences().length >= 1)) {
                     throw new Error('NO_SIGNATURE_REFERENCES');
                 }
                 var signedVerifiedXML = sig.getSignedReferences()[0];
                 var rootNode = docParser.parseFromString(signedVerifiedXML, 'text/xml').documentElement;
-                // process the verified signature:
-                // case 1, rootSignedDoc is a response:
                 if (rootNode.localName === 'Response') {
-                    // try getting the Xml from the first assertion
                     var assertions = toNodeArray((0, xpath_1.select)("./*[local-name()='Assertion']", rootNode));
                     var encryptedAssertions = toNodeArray((0, xpath_1.select)("./*[local-name()='EncryptedAssertion']", rootNode));
-                    // now we can process the assertion as an assertion
                     if (assertions.length === 1) {
                         return { value: [true, assertions[0].toString()] };
                     }
                     else if (encryptedAssertions.length >= 1) {
                         return { value: [true, rootNode.toString()] };
                     }
-                    else {
-                        return { value: [true, null] };
-                    }
+                    return { value: [true, null] };
                 }
                 else if (rootNode.localName === 'Assertion') {
                     return { value: [true, rootNode.toString()] };
                 }
-                else {
-                    return { value: [true, null] };
-                }
+                return { value: [true, null] };
             };
             var this_1 = this;
             try {
-                // need to refactor later on
                 for (var selection_1 = __values(selection), selection_1_1 = selection_1.next(); !selection_1_1.done; selection_1_1 = selection_1.next()) {
                     var signatureNode = selection_1_1.value;
                     var state_1 = _loop_1(signatureNode);
@@ -463,108 +567,65 @@ var libSaml = function () {
                 }
                 finally { if (e_1) throw e_1.error; }
             }
-            ;
-            return [false, null]; // we didn't verify anything, none of the signatures are valid
-            /*
-            // response must be signed, either entire document or assertion
-            // default we will take the assertion section under root
-            if (messageSignatureNode.length === 1) {
-              const node = select("/*[contains(local-name(), 'Response') or contains(local-name(), 'Request')]/*[local-name(.)='Assertion']", doc);
-              if (node.length === 1) {
-                assertionNode = node[0].toString();
-              }
-            }
-      
-            if (assertionSignatureNode.length === 1) {
-              const verifiedAssertionInfo = extract(assertionSignatureNode[0].toString(), [{
-                key: 'refURI',
-                localPath: ['Signature', 'SignedInfo', 'Reference'],
-                attributes: ['URI']
-              }]);
-              // get the assertion supposed to be the one should be verified
-              const desiredAssertionInfo = extract(doc.toString(), [{
-                key: 'id',
-                localPath: ['~Response', 'Assertion'],
-                attributes: ['ID']
-              }]);
-              // 5.4.2 References
-              // SAML assertions and protocol messages MUST supply a value for the ID attribute on the root element of
-              // the assertion or protocol message being signed. The assertion’s or protocol message's root element may
-              // or may not be the root element of the actual XML document containing the signed assertion or protocol
-              // message (e.g., it might be contained within a SOAP envelope).
-              // Signatures MUST contain a single <ds:Reference> containing a same-document reference to the ID
-              // attribute value of the root element of the assertion or protocol message being signed. For example, if the
-              // ID attribute value is "foo", then the URI attribute in the <ds:Reference> element MUST be "#foo".
-              if (verifiedAssertionInfo.refURI !== `#${desiredAssertionInfo.id}`) {
-                throw new Error('ERR_POTENTIAL_WRAPPING_ATTACK');
-              }
-              const verifiedDoc = extract(doc.toString(), [{
-                key: 'assertion',
-                localPath: ['~Response', 'Assertion'],
-                attributes: [],
-                context: true
-              }]);
-              assertionNode = verifiedDoc.assertion.toString();
-            }
-      
-            return [verified, assertionNode];*/
+            return [false, null];
         },
         /**
-        * @desc Helper function to create the key section in metadata (abstraction for signing and encrypt use)
-        * @param  {string} use          type of certificate (e.g. signing, encrypt)
-        * @param  {string} certString    declares the certificate String
-        * @return {object} object used in xml module
-        */
+         * Build the metadata `<KeyDescriptor>` fragment for a certificate use.
+         *
+         * @param use `signing` or `encryption`
+         * @param certString PEM certificate body or Buffer
+         * @returns element tree consumable by the `xml` module
+         */
         createKeySection: function (use, certString) {
-            var _a, _b, _c;
-            return _a = {},
-                _a['KeyDescriptor'] = [
+            return {
+                KeyDescriptor: [
                     {
                         _attr: { use: use },
                     },
-                    (_b = {},
-                        _b['ds:KeyInfo'] = [
+                    {
+                        'ds:KeyInfo': [
                             {
                                 _attr: {
                                     'xmlns:ds': 'http://www.w3.org/2000/09/xmldsig#',
                                 },
                             },
-                            (_c = {},
-                                _c['ds:X509Data'] = [{
+                            {
+                                'ds:X509Data': [{
                                         'ds:X509Certificate': utility_1.default.normalizeCerString(certString),
                                     }],
-                                _c),
+                            },
                         ],
-                        _b)
+                    },
                 ],
-                _a;
+            };
         },
         /**
-        * @desc Constructs SAML message
-        * @param  {string} octetString               see "Bindings for the OASIS Security Assertion Markup Language (SAML V2.0)" P.17/46
-        * @param  {string} key                       declares the pem-formatted private key
-        * @param  {string} passphrase                passphrase of private key [optional]
-        * @param  {string} signingAlgorithm          signing algorithm
-        * @return {string} message signature
-        */
+         * Produce a detached RSA signature over a SAML redirect-binding octet
+         * string. See SAML bindings spec §3.4.4.1.
+         *
+         * @param octetString canonical query-string to sign
+         * @param key PEM private key
+         * @param passphrase optional passphrase for the key
+         * @param isBase64 when true (default), base64-encode the signature
+         * @param signingAlgorithm signature algorithm URI
+         * @returns base64 string (default) or raw Buffer signature
+         */
         constructMessageSignature: function (octetString, key, passphrase, isBase64, signingAlgorithm) {
-            // Default returning base64 encoded signature
-            // Embed with node-rsa module
             var decryptedKey = new node_rsa_1.default(utility_1.default.readPrivateKey(key, passphrase), undefined, {
                 signingScheme: getSigningScheme(signingAlgorithm),
             });
             var signature = decryptedKey.sign(octetString);
-            // Use private key to sign data
             return isBase64 !== false ? signature.toString('base64') : signature;
         },
         /**
-        * @desc Verifies message signature
-        * @param  {Metadata} metadata                 metadata object of identity provider or service provider
-        * @param  {string} octetString                see "Bindings for the OASIS Security Assertion Markup Language (SAML V2.0)" P.17/46
-        * @param  {string} signature                  context of XML signature
-        * @param  {string} verifyAlgorithm            algorithm used to verify
-        * @return {boolean} verification result
-        */
+         * Verify a detached RSA signature over a redirect-binding octet string.
+         *
+         * @param metadata peer metadata carrying the signing certificate
+         * @param octetString canonical query-string that was signed
+         * @param signature signature bytes
+         * @param verifyAlgorithm signature algorithm URI (optional)
+         * @returns true when the signature verifies
+         */
         verifyMessageSignature: function (metadata, octetString, signature, verifyAlgorithm) {
             var signCert = metadata.getX509Certificate(certUse.signing);
             var signingScheme = getSigningScheme(verifyAlgorithm);
@@ -572,10 +633,11 @@ var libSaml = function () {
             return key.verify(Buffer.from(octetString), Buffer.from(signature));
         },
         /**
-        * @desc Get the public key in string format
-        * @param  {string} x509Certificate certificate
-        * @return {string} public key
-        */
+         * Build the KeyInfo XML fragment and PEM public key for a certificate.
+         *
+         * @param x509Certificate certificate body (no PEM wrappers)
+         * @param signatureConfig optional prefix/location for the KeyInfo element
+         */
         getKeyInfo: function (x509Certificate, signatureConfig) {
             if (signatureConfig === void 0) { signatureConfig = {}; }
             var prefix = signatureConfig.prefix ? "".concat(signatureConfig.prefix, ":") : '';
@@ -589,14 +651,16 @@ var libSaml = function () {
             };
         },
         /**
-        * @desc Encrypt the assertion section in Response
-        * @param  {Entity} sourceEntity             source entity
-        * @param  {Entity} targetEntity             target entity
-        * @param  {string} xml                      response in xml string format
-        * @return {Promise} a promise to resolve the finalized xml
-        */
+         * Encrypt the `<Assertion>` inside a SAML response using the target
+         * entity's encryption certificate. Returns the base64-encoded XML
+         * containing the `<EncryptedAssertion>` element in place of the plaintext.
+         *
+         * @param sourceEntity entity initiating the encryption (its settings drive the algorithms)
+         * @param targetEntity entity whose certificate is used
+         * @param xml response XML containing a single `<Assertion>`
+         * @returns promise resolving to base64-encoded XML
+         */
         encryptAssertion: function (sourceEntity, targetEntity, xml) {
-            // Implement encryption after signature if it has
             return new Promise(function (resolve, reject) {
                 if (!xml) {
                     return reject(new Error('ERR_UNDEFINED_ASSERTION'));
@@ -613,16 +677,16 @@ var libSaml = function () {
                     throw new Error('ERR_MULTIPLE_ASSERTION');
                 }
                 var rawAssertionNode = assertions[0];
-                // Perform encryption depends on the setting, default is false
                 if (sourceEntitySetting.isAssertionEncrypted) {
-                    var publicKeyPem = utility_1.default.getPublicKeyPemFromCertificate(targetEntityMetadata.getX509Certificate(certUse.encrypt));
+                    var encryptCert = targetEntityMetadata.getX509Certificate(certUse.encrypt);
+                    var publicKeyPem = utility_1.default.getPublicKeyPemFromCertificate(encryptCert);
                     xmlenc.encrypt(rawAssertionNode.toString(), {
-                        // use xml-encryption module
-                        rsa_pub: Buffer.from(publicKeyPem), // public key from certificate
-                        pem: Buffer.from("-----BEGIN CERTIFICATE-----".concat(targetEntityMetadata.getX509Certificate(certUse.encrypt), "-----END CERTIFICATE-----")),
+                        rsa_pub: Buffer.from(publicKeyPem),
+                        pem: Buffer.from("-----BEGIN CERTIFICATE-----".concat(encryptCert, "-----END CERTIFICATE-----")),
                         encryptionAlgorithm: sourceEntitySetting.dataEncryptionAlgorithm,
                         keyEncryptionAlgorithm: sourceEntitySetting.keyEncryptionAlgorithm,
                     }, function (err, res) {
+                        /* v8 ignore start */
                         if (err) {
                             console.error(err);
                             return reject(new Error('ERR_EXCEPTION_OF_ASSERTION_ENCRYPTION'));
@@ -630,6 +694,7 @@ var libSaml = function () {
                         if (!res) {
                             return reject(new Error('ERR_UNDEFINED_ENCRYPTED_ASSERTION'));
                         }
+                        /* v8 ignore stop */
                         var encAssertionPrefix = sourceEntitySetting.tagPrefix.encryptedAssertion;
                         var encryptAssertionDoc = dom.parseFromString("<".concat(encAssertionPrefix, ":EncryptedAssertion xmlns:").concat(encAssertionPrefix, "=\"").concat(urn_1.namespace.names.assertion, "\">").concat(res, "</").concat(encAssertionPrefix, ":EncryptedAssertion>"));
                         doc.documentElement.replaceChild(encryptAssertionDoc.documentElement, rawAssertionNode);
@@ -637,25 +702,24 @@ var libSaml = function () {
                     });
                 }
                 else {
-                    return resolve(utility_1.default.base64Encode(xml)); // No need to do encryption
+                    return resolve(utility_1.default.base64Encode(xml));
                 }
             });
         },
         /**
-        * @desc Decrypt the assertion section in Response
-        * @param  {string} type             only accept SAMLResponse to proceed decryption
-        * @param  {Entity} here             this entity
-        * @param  {Entity} from             from the entity where the message is sent
-        * @param {string} entireXML         response in xml string format
-        * @return {function} a promise to get back the entire xml with decrypted assertion
-        */
+         * Decrypt the `<EncryptedAssertion>` inside a SAML response using the
+         * local entity's private key. Returns both the decrypted document XML
+         * and the raw assertion fragment for downstream extraction.
+         *
+         * @param here local entity performing decryption
+         * @param entireXML SAML response XML containing `<EncryptedAssertion>`
+         * @returns tuple `[decryptedDocumentXml, rawAssertionXml]`
+         */
         decryptAssertion: function (here, entireXML) {
             return new Promise(function (resolve, reject) {
-                // Implement decryption first then check the signature
                 if (!entireXML) {
                     return reject(new Error('ERR_UNDEFINED_ASSERTION'));
                 }
-                // Perform encryption depends on the setting of where the message is sent, default is false
                 var hereSetting = here.entitySetting;
                 var dom = (0, api_1.getContext)().dom;
                 var doc = dom.parseFromString(entireXML);
@@ -670,6 +734,7 @@ var libSaml = function () {
                 return xmlenc.decrypt(encAssertionNode.toString(), {
                     key: utility_1.default.readPrivateKey(hereSetting.encPrivateKey, hereSetting.encPrivateKeyPass),
                 }, function (err, res) {
+                    /* v8 ignore start */
                     if (err) {
                         console.error(err);
                         return reject(new Error('ERR_EXCEPTION_OF_ASSERTION_DECRYPTION'));
@@ -677,6 +742,7 @@ var libSaml = function () {
                     if (!res) {
                         return reject(new Error('ERR_UNDEFINED_ENCRYPTED_ASSERTION'));
                     }
+                    /* v8 ignore stop */
                     var rawAssertionDoc = dom.parseFromString(res);
                     doc.documentElement.replaceChild(rawAssertionDoc.documentElement, encAssertionNode);
                     return resolve([doc.toString(), res]);
@@ -684,34 +750,24 @@ var libSaml = function () {
             });
         },
         /**
-         * @desc Check if the xml string is valid and bounded
+         * Validate the SAML XML against the registered schema validator. Throws
+         * when no validator has been configured via {@link setSchemaValidator}
+         * so consumers can't silently ship without schema checks.
+         *
+         * @param input SAML XML string
          */
         isValidXml: function (input) {
             return __awaiter(this, void 0, void 0, function () {
-                var validate, e_2;
+                var validate;
                 return __generator(this, function (_a) {
                     switch (_a.label) {
                         case 0:
                             validate = (0, api_1.getContext)().validate;
-                            /**
-                             * user can write a validate function that always returns
-                             * a resolved promise and skip the validator even in
-                             * production, user will take the responsibility if
-                             * they intend to skip the validation
-                             */
                             if (!validate) {
-                                // otherwise, an error will be thrown
-                                return [2 /*return*/, Promise.reject('Your application is potentially vulnerable because no validation function found. Please read the documentation on how to setup the validator. (https://github.com/tngan/samlify#installation)')];
+                                return [2 /*return*/, Promise.reject(new Error('Your application is potentially vulnerable because no validation function found. Please read the documentation on how to setup the validator. (https://github.com/tngan/samlify#installation)'))];
                             }
-                            _a.label = 1;
-                        case 1:
-                            _a.trys.push([1, 3, , 4]);
                             return [4 /*yield*/, validate(input)];
-                        case 2: return [2 /*return*/, _a.sent()];
-                        case 3:
-                            e_2 = _a.sent();
-                            throw e_2;
-                        case 4: return [2 /*return*/];
+                        case 1: return [2 /*return*/, _a.sent()];
                     }
                 });
             });