@mcp-abap-adt/auth-providers 3.0.0 → 4.0.0

package/dist/providers/saml2Utils.js

@@ -4,10 +4,13 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateSamlConfig = validateSamlConfig;
+exports.resolveAssertionValidator = resolveAssertionValidator;
 exports.resolveTokenUrl = resolveTokenUrl;
 exports.getSamlAssertion = getSamlAssertion;
 const saml2Auth_1 = require("../auth/saml2Auth");
+const TokenProviderErrors_1 = require("../errors/TokenProviderErrors");
 const strategies_1 = require("../strategies");
+const assertionValidator_1 = require("../validation/assertionValidator");
 /** Throw at construction rather than half-verify at runtime. */
 function validateSamlConfig(config) {
     if (config.authorizationUrl && !config.acsUrl) {
@@ -15,6 +18,48 @@ function validateSamlConfig(config) {
             'pre-built SAML request cannot be read, so it must be declared.');
     }
 }
+/**
+ * The consumer's validator when supplied, otherwise the provider's default —
+ * `createSignedAssertionValidator` for `"bearer"`, since the token endpoint
+ * receives the Assertion alone (#40) and its own signature is what that
+ * endpoint verifies; `createSignedResponseValidator` for `"pure"`, since the
+ * whole response is handed on and `Status`/`Destination` must be inside a
+ * signature. See the spec's "A bare Assertion, and which validator each
+ * provider defaults to".
+ */
+function resolveAssertionValidator(config, provider) {
+    if (config.assertionValidator) {
+        // A shipped validator fails closed without expectedIssuer, so supplying
+        // one without idpEntityId would construct fine and then refuse every
+        // login at `issuer` — after the browser step. A custom validator needs
+        // no idpEntityId: it may establish trust some other way.
+        if ((0, assertionValidator_1.isShippedValidator)(config.assertionValidator) && !config.idpEntityId) {
+            throw new TokenProviderErrors_1.ValidationError('The supplied assertionValidator is a shipped one ' +
+                '(createSignedResponseValidator or createSignedAssertionValidator), ' +
+                'which refuses every assertion without an expected issuer: missing ' +
+                'idpEntityId.', ['idpEntityId']);
+        }
+        return config.assertionValidator;
+    }
+    const missing = [];
+    if (!config.idpCertificates?.length)
+        missing.push('idpCertificates');
+    if (!config.idpEntityId)
+        missing.push('idpEntityId');
+    if (missing.length > 0) {
+        throw new TokenProviderErrors_1.ValidationError(`The default assertion validator needs the identity provider it should ` +
+            `trust: missing ${missing.join(', ')}. Supply these, or supply an ` +
+            `assertionValidator of your own.`, missing);
+    }
+    const options = {
+        idpCertificates: config.idpCertificates,
+        clockSkewMs: config.clockSkewMs,
+        replayStore: config.assertionReplayStore,
+    };
+    return provider === 'bearer'
+        ? (0, assertionValidator_1.createSignedAssertionValidator)(options)
+        : (0, assertionValidator_1.createSignedResponseValidator)(options);
+}
 function resolveTokenUrl(config) {
     if (config.tokenUrl) {
         return config.tokenUrl;
@@ -26,9 +71,21 @@ function resolveTokenUrl(config) {
 }
 async function getSamlAssertion(config) {
     const declaredAcs = config.acsUrl;
+    let mintedRequestId;
     const request = {
         logger: config.logger,
         buildAuthorizationUrl: async (redirectUri) => {
+            // An IdP-initiated login sends no AuthnRequest, and without a pre-built
+            // authorizationUrl the only URL this could produce is one carrying a
+            // freshly minted request. Refused here, before any URL exists, so the
+            // mistake surfaces before a browser opens rather than after a login.
+            if (config.idpInitiated && !config.authorizationUrl) {
+                throw new TokenProviderErrors_1.ValidationError('SAML idpInitiated is true and no authorizationUrl is configured, ' +
+                    'but the authorization strategy asked for an authorization URL: ' +
+                    'the only one this package can build carries an AuthnRequest. ' +
+                    'Configure the IdP-initiated SSO URL as authorizationUrl, or use a ' +
+                    'strategy that does not call buildAuthorizationUrl.', ['authorizationUrl']);
+            }
             // A declared ACS is registered with the IdP; the strategy must be
             // listening exactly there, and an ephemeral port cannot be.
             const acsUrl = declaredAcs ?? redirectUri;
@@ -36,13 +93,15 @@ async function getSamlAssertion(config) {
                 throw new Error(`SAML acsUrl is ${declaredAcs}, but the authorization strategy is ` +
                     `listening on ${redirectUri}. They must match.`);
             }
-            return (0, saml2Auth_1.buildSamlAuthorizationUrl)({
+            const built = (0, saml2Auth_1.buildSamlAuthorizationUrl)({
                 idpSsoUrl: config.idpSsoUrl,
                 spEntityId: config.spEntityId,
                 acsUrl,
                 relayState: config.relayState,
                 authorizationUrl: config.authorizationUrl,
             });
+            mintedRequestId = built.requestId;
+            return built.url;
         },
     };
     const supplied = config.authorization;
@@ -55,7 +114,12 @@ async function getSamlAssertion(config) {
             throw new Error(`SAML acsUrl is ${declaredAcs}, but the authorization strategy used ` +
                 `${outcome.redirectUri}. They must match.`);
         }
-        return outcome.payload;
+        const requestId = resolveExpectedRequestId(config, mintedRequestId);
+        return {
+            payload: outcome.payload,
+            requestId,
+            acsUrl: outcome.redirectUri,
+        };
     }
     finally {
         if (!supplied) {
@@ -67,3 +131,31 @@ async function getSamlAssertion(config) {
         }
     }
 }
+/**
+ * The ID `InResponseTo` must answer, from the three sources the spec allows:
+ * minted, declared, or none by explicit `idpInitiated: true`. Anything else —
+ * no ID and no declaration, or `idpInitiated` combined with an ID from either
+ * of the other two sources — is a configuration error, not a validation
+ * failure blamed on the assertion.
+ */
+function resolveExpectedRequestId(config, mintedRequestId) {
+    const declaredRequestId = config.authnRequestId;
+    if (config.idpInitiated) {
+        if (mintedRequestId || declaredRequestId) {
+            throw new TokenProviderErrors_1.ValidationError('SAML idpInitiated is true, but a request ID was also minted or ' +
+                'configured (an authorization strategy called buildAuthorizationUrl, ' +
+                'or authnRequestId is set). An IdP-initiated login sends no request, ' +
+                'so an ID means the configuration describes two different logins.', ['idpInitiated']);
+        }
+        return undefined;
+    }
+    const requestId = mintedRequestId ?? declaredRequestId;
+    if (!requestId) {
+        throw new TokenProviderErrors_1.ValidationError('Cannot validate InResponseTo: this login did not build its own AuthnRequest, ' +
+            'so authnRequestId must be configured — or, if the identity provider ' +
+            'starts this login itself, idpInitiated: true. This happens with a ' +
+            'pre-built authorizationUrl, or an authorization strategy that supplies an ' +
+            'assertion without asking for a URL.', ['authnRequestId']);
+    }
+    return requestId;
+}

package/dist/validation/assertionValidator.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The shipped assertion validator: the spec's check table, in order.
+ *
+ * Two properties matter more than any individual check. First, the signature
+ * is resolved to an element and every assertion-level field is read *from that
+ * element* — a document holding a validly signed fragment beside a forged one
+ * is the wrapping attack, and reading the wrong node is how it succeeds.
+ * Second, no two refusals share a distinguishing phrase, so a test cannot pass
+ * for a neighbouring check's reason.
+ *
+ * Three fields live on the Response rather than the assertion: Status,
+ * Response/Issuer and Destination. The signed-Response validator reads them,
+ * because there they are inside the signature. The assertion-only validator
+ * does not read them at all — not weakly. That is safe because a declined
+ * login carries no assertion, so flipping Status buys an attacker nothing they
+ * can sign, and addressing rests on Recipient inside the signed assertion.
+ */
+import type { IAssertionReplayStore, IAssertionValidator } from '@mcp-abap-adt/interfaces-auth';
+export interface ShippedValidatorOptions {
+    readonly idpCertificates: readonly string[];
+    readonly clockSkewMs?: number;
+    readonly replayStore?: IAssertionReplayStore;
+}
+/** Whether this validator came from one of the two shipped factories. */
+export declare function isShippedValidator(validator: IAssertionValidator): boolean;
+export declare const createSignedResponseValidator: (options: ShippedValidatorOptions) => IAssertionValidator;
+export declare const createSignedAssertionValidator: (options: ShippedValidatorOptions) => IAssertionValidator;
+//# sourceMappingURL=assertionValidator.d.ts.map

package/dist/validation/assertionValidator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assertionValidator.d.ts","sourceRoot":"","sources":["../../src/validation/assertionValidator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAEV,qBAAqB,EACrB,mBAAmB,EAEpB,MAAM,+BAA+B,CAAC;AAiBvC,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,CAAC,EAAE,qBAAqB,CAAC;CAC9C;AAgCD,yEAAyE;AACzE,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,mBAAmB,GAAG,OAAO,CAE1E;AAED,eAAO,MAAM,6BAA6B,GACxC,SAAS,uBAAuB,KAC/B,mBAAkE,CAAC;AAEtE,eAAO,MAAM,8BAA8B,GACzC,SAAS,uBAAuB,KAC/B,mBAAmE,CAAC"}

package/dist/validation/assertionValidator.js

@@ -0,0 +1,444 @@
+"use strict";
+/**
+ * The shipped assertion validator: the spec's check table, in order.
+ *
+ * Two properties matter more than any individual check. First, the signature
+ * is resolved to an element and every assertion-level field is read *from that
+ * element* — a document holding a validly signed fragment beside a forged one
+ * is the wrapping attack, and reading the wrong node is how it succeeds.
+ * Second, no two refusals share a distinguishing phrase, so a test cannot pass
+ * for a neighbouring check's reason.
+ *
+ * Three fields live on the Response rather than the assertion: Status,
+ * Response/Issuer and Destination. The signed-Response validator reads them,
+ * because there they are inside the signature. The assertion-only validator
+ * does not read them at all — not weakly. That is safe because a declined
+ * login carries no assertion, so flipping Status buys an attacker nothing they
+ * can sign, and addressing rests on Recipient inside the signed assertion.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSignedAssertionValidator = exports.createSignedResponseValidator = void 0;
+exports.isShippedValidator = isShippedValidator;
+const xmldom_1 = require("@xmldom/xmldom");
+const strictXml_1 = require("../auth/strictXml");
+const AssertionValidationError_1 = require("../errors/AssertionValidationError");
+const documentIds_1 = require("./documentIds");
+const inMemoryReplayStore_1 = require("./inMemoryReplayStore");
+const signedNode_1 = require("./signedNode");
+const xsdDateTime_1 = require("./xsdDateTime");
+const SAML_NS = 'urn:oasis:names:tc:SAML:2.0:assertion';
+const PROTOCOL_NS = 'urn:oasis:names:tc:SAML:2.0:protocol';
+const BEARER = 'urn:oasis:names:tc:SAML:2.0:cm:bearer';
+const SUCCESS = 'urn:oasis:names:tc:SAML:2.0:status:Success';
+/**
+ * Marks a validator as one of the two shipped here. Module-private and
+ * non-enumerable, so it is neither part of the public surface nor visible to
+ * a consumer spreading or serialising the object.
+ *
+ * It exists for one reason: a shipped validator fails closed without
+ * `expectedIssuer`, so a provider handed one must insist on `idpEntityId` at
+ * construction — otherwise the mistake surfaces only as an `issuer` refusal
+ * after a human has finished a browser login. A custom validator carries no
+ * brand and may establish trust however it likes.
+ */
+const SHIPPED = Symbol('mcp-abap-adt.shippedAssertionValidator');
+function brand(validator) {
+    Object.defineProperty(validator, SHIPPED, {
+        value: true,
+        enumerable: false,
+    });
+    return validator;
+}
+/** Whether this validator came from one of the two shipped factories. */
+function isShippedValidator(validator) {
+    return validator[SHIPPED] === true;
+}
+const createSignedResponseValidator = (options) => brand(createValidator('response', options));
+exports.createSignedResponseValidator = createSignedResponseValidator;
+const createSignedAssertionValidator = (options) => brand(createValidator('assertion', options));
+exports.createSignedAssertionValidator = createSignedAssertionValidator;
+function createValidator(require, options) {
+    const skew = options.clockSkewMs ?? 0;
+    if (!Number.isInteger(skew) || skew < 0) {
+        throw new Error(`clockSkewMs must be a finite non-negative integer, got ${String(options.clockSkewMs)}`);
+    }
+    if (options.idpCertificates.length === 0) {
+        throw new Error('idpCertificates must not be empty: nothing could be verified');
+    }
+    // Normalised and proved here, once, rather than inside verification. Three
+    // reasons, and the last bites hardest: a malformed entry standing first in
+    // the list would abort the rotation loop before a later valid certificate
+    // was tried; a constructor is where this package already refuses a bad
+    // configuration; and a login happens after a human has used a browser, so a
+    // formatting mistake found then wastes their work, not ours.
+    const certificates = options.idpCertificates.map(signedNode_1.toPem);
+    const store = options.replayStore ?? inMemoryReplayStore_1.defaultReplayStore;
+    return {
+        async validate(samlResponse, context) {
+            // 1. Parses, and the document element is a samlp:Response.
+            const xml = Buffer.from(samlResponse, 'base64').toString('utf8');
+            // No DTD, ever. A SAML message has no use for one, and a DOCTYPE is
+            // where parsers diverge — entity expansion, internal subsets — and this
+            // document is parsed twice: by @xmldom/xmldom 0.9 here and by the 0.8
+            // nested inside xml-crypto. Refused before either parse is trusted.
+            if (/<!DOCTYPE/i.test(xml)) {
+                return fail('document', 'the SAMLResponse carries a DOCTYPE declaration, which is never accepted');
+            }
+            let doc;
+            try {
+                doc = (0, strictXml_1.parseStrictXml)(xml);
+            }
+            catch {
+                return fail('document', 'the SAMLResponse did not parse as XML');
+            }
+            const root = doc.documentElement;
+            if (!root)
+                return fail('document', 'the SAMLResponse did not parse as XML');
+            const rootIsResponse = root.localName === 'Response' && root.namespaceURI === PROTOCOL_NS;
+            const rootIsAssertion = root.localName === 'Assertion' && root.namespaceURI === SAML_NS;
+            // A bare Assertion is a document only the assertion-only validator
+            // accepts: the saml2-bearer grant exchanges an Assertion, and 3.0.0
+            // already takes one as Saml2BearerProvider's payload.
+            if (!rootIsResponse && !(require === 'assertion' && rootIsAssertion)) {
+                return fail('document', require === 'assertion'
+                    ? `expected a samlp:Response or a saml:Assertion, got ${(0, signedNode_1.quoteUntrusted)(root.localName ?? '')}`
+                    : `expected the document element to be a samlp:Response, got ${(0, signedNode_1.quoteUntrusted)(root.localName ?? '')}`);
+            }
+            // 1b. Unique IDs, before any reference is resolved.
+            const duplicate = (0, documentIds_1.findDuplicateId)(doc);
+            if (duplicate) {
+                return fail('duplicateId', `the document uses the ID ${(0, signedNode_1.quoteUntrusted)(duplicate)} more than once, so which element is signed is ambiguous`);
+            }
+            // 2 + 3. Verify every signature, then take the element this validator
+            // requires from among those they cover. A response signed at both
+            // levels — as many identity providers send — satisfies either validator.
+            let covered;
+            try {
+                covered = (0, signedNode_1.resolveSignedElements)(xml, doc, certificates);
+            }
+            catch (error) {
+                return fail('signature', error.message);
+            }
+            // The element this validator reads is fixed by the document's shape,
+            // not by which signature happens to come first: the Response itself, or
+            // for the assertion-only validator the bare root Assertion or the
+            // Response's single direct-child Assertion. Taking "the first covered
+            // Assertion" instead would pick a signed assertion nested in Advice
+            // whenever its signature precedes the outer one's in document order.
+            const target = require === 'response'
+                ? root
+                : rootIsAssertion
+                    ? root
+                    : (() => {
+                        const children = directChildren(root, SAML_NS, 'Assertion');
+                        return children.length === 1 ? children[0] : null;
+                    })();
+            const signed = target
+                ? covered.find((element) => element === target)
+                : undefined;
+            // The signed element must be the Assertion, or a Response holding exactly
+            // one. Everything below is read from `assertion` and nowhere else.
+            const assertion = signed ? assertionInside(signed, root, require) : null;
+            if (!signed || !assertion) {
+                return fail('signedNode', 'the signature does not cover the assertion this response carries');
+            }
+            // 3b. Nothing assertion-shaped outside the one read. Wherever the
+            // signature sits, the payload travels on whole — Saml2PureProvider hands
+            // it to the cookie provider — so an Assertion or EncryptedAssertion in
+            // an unsigned part of it (Extensions, a sibling, a wrapper) is something
+            // a later reader may take for the real one.
+            if (!everyAssertionWithin(doc, assertion)) {
+                return fail('signedNode', 'the document carries a saml:Assertion or saml:EncryptedAssertion outside the one the signature covers');
+            }
+            // 4. Status. Only when the Response is the signed element: otherwise it
+            // lies outside the signature, and checking a field an attacker sets is
+            // worse than not checking it — it reads like verification.
+            if (require === 'response') {
+                const status = directChild(root, PROTOCOL_NS, 'Status');
+                const codeValue = status
+                    ? directChild(status, PROTOCOL_NS, 'StatusCode')?.getAttribute('Value')
+                    : null;
+                if (!codeValue)
+                    return fail('status', 'the response must carry exactly one samlp:Status holding exactly one StatusCode with a Value');
+                if (codeValue !== SUCCESS) {
+                    return fail('status', `the identity provider declined the login: ${codeValue}`);
+                }
+            }
+            // 4b. The assertion's own ID.
+            const assertionId = (0, documentIds_1.readRequiredId)(assertion);
+            if (!assertionId)
+                return fail('assertionId', 'the assertion carries no ID');
+            // 5. The assertion's Issuer — inside the signature either way, so both
+            // validators check it.
+            const issuer = directChild(assertion, SAML_NS, 'Issuer')?.textContent ?? '';
+            if (!issuer) {
+                return fail('issuer', 'the assertion must carry exactly one non-empty saml:Issuer');
+            }
+            // Fail closed: with nothing to compare against, any issuer whose key is
+            // configured would pass, which is not what this validator promises.
+            if (!context.expectedIssuer) {
+                return fail('issuer', 'no expectedIssuer was configured, so the assertion issuer cannot be trusted');
+            }
+            if (issuer !== context.expectedIssuer) {
+                return fail('issuer', `the assertion was issued by ${issuer}, not the trusted issuer`);
+            }
+            // 5b. The cross-check against the Response's Issuer belongs to the
+            // signed-Response validator alone: only there are both inside the
+            // signature.
+            if (require === 'response') {
+                // Optional, so none is fine; but two are an ambiguity, and one that is
+                // present must agree — empty included, since empty is not absent.
+                const responseIssuers = directChildren(root, SAML_NS, 'Issuer');
+                if (responseIssuers.length > 1) {
+                    return fail('issuer', 'the response must carry at most one saml:Issuer');
+                }
+                if (responseIssuers.length === 1 &&
+                    (responseIssuers[0].textContent ?? '') !== issuer) {
+                    return fail('issuer', 'the response and the assertion name different issuers');
+                }
+            }
+            // 6, 7, 8. Conditions and their window.
+            const conditions = directChild(assertion, SAML_NS, 'Conditions');
+            if (!conditions)
+                return fail('conditions', 'the assertion must carry exactly one saml:Conditions');
+            const notBeforeRaw = conditions.getAttribute('NotBefore');
+            if (notBeforeRaw) {
+                const notBefore = (0, xsdDateTime_1.parseXsdDateTime)(notBeforeRaw);
+                if (!notBefore) {
+                    return fail('notBefore', `Conditions NotBefore is not a valid xsd:dateTime: ${notBeforeRaw}`);
+                }
+                if (notBefore.getTime() - skew > Date.now()) {
+                    return fail('notBefore', 'the assertion is not valid yet');
+                }
+            }
+            const conditionsExpiry = (0, xsdDateTime_1.parseXsdDateTime)(conditions.getAttribute('NotOnOrAfter'));
+            if (!conditionsExpiry) {
+                return fail('notOnOrAfter', 'Conditions carries no usable NotOnOrAfter, so the assertion states no lifetime');
+            }
+            if (conditionsExpiry.getTime() + skew <= Date.now()) {
+                return fail('notOnOrAfter', 'the assertion has expired');
+            }
+            // 9. Every AudienceRestriction must name us; several Audience inside one
+            // are alternatives.
+            const restrictions = directChildren(conditions, SAML_NS, 'AudienceRestriction');
+            if (restrictions.length === 0) {
+                return fail('audience', 'the assertion restricts no audience');
+            }
+            for (const restriction of restrictions) {
+                const names = directChildren(restriction, SAML_NS, 'Audience').map((a) => a.textContent ?? '');
+                if (!names.includes(context.audience)) {
+                    return fail('audience', 'an AudienceRestriction on this assertion does not name us');
+                }
+            }
+            // 10. One bearer confirmation satisfying everything together.
+            const chosen = chooseBearerConfirmation(assertion, context, skew);
+            if (!chosen) {
+                return fail('bearerConfirmation', 'no single bearer SubjectConfirmation, under exactly one saml:Subject and with exactly one SubjectConfirmationData, answers our request, names our ACS and is still open');
+            }
+            // 11. Destination — the signed-Response validator only, for the same
+            // reason as Status. Addressing in the other flow rests on Recipient,
+            // which step 10 required and which sits inside the signed assertion.
+            if (require === 'response') {
+                const destination = root.getAttribute('Destination');
+                if (!destination) {
+                    return fail('destination', 'the response carries no Destination');
+                }
+                if (destination !== context.acsUrl) {
+                    return fail('destination', `the response is addressed to ${destination}, not to us`);
+                }
+            }
+            // Expiry: the earlier of the two windows.
+            const expiresAt = new Date(Math.min(conditionsExpiry.getTime(), chosen.notOnOrAfter.getTime()));
+            // 12. Replay. Retention is NOT expiresAt: it must last for as long as
+            // this validator could accept the assertion again. Conditions bound
+            // that, but so does the LATEST bearer confirmation that can qualify —
+            // with confirmations closing at +120 s and +600 s the session ends at
+            // +120 s, yet at +200 s the second one still qualifies, and an entry
+            // dropped at +120 s would let the same assertion in a second time. The
+            // skew is added on top, since inside it the assertion is still accepted.
+            const retainUntil = new Date(Math.min(conditionsExpiry.getTime(), chosen.latestNotOnOrAfter.getTime()) + skew);
+            const fresh = await store.recordIfUnseen({ issuer, assertionId }, retainUntil);
+            if (!fresh) {
+                return fail('replay', 'this assertion has been presented before');
+            }
+            return {
+                expiresAt,
+                assertionId,
+                issuer,
+                nameId: (() => {
+                    // Subject, then NameID — no `?? assertion` fallback, which would
+                    // read a NameID from outside the Subject when the Subject is absent.
+                    const subject = directChild(assertion, SAML_NS, 'Subject');
+                    return subject
+                        ? (directChild(subject, SAML_NS, 'NameID')?.textContent ??
+                            undefined)
+                        : undefined;
+                })(),
+                raw: samlResponse,
+                // The signed element, not the response: this is what a consumer may
+                // parse without re-deriving what the signature covered.
+                signedXml: new xmldom_1.XMLSerializer().serializeToString(signed),
+            };
+        },
+    };
+}
+function fail(check, message) {
+    throw new AssertionValidationError_1.AssertionValidationError(check, message);
+}
+/**
+ * Direct children with this namespace and local name — **not** descendants.
+ *
+ * `getElementsByTagNameNS` searches the whole subtree, and that is the wrong
+ * tool for a structural path. An assertion with no `Conditions` of its own but
+ * a `Conditions` buried somewhere inside it would answer the descendant search
+ * and satisfy a check it does not meet; the same trick works for `Issuer`,
+ * `Status` and `Subject`. Each segment of a SAML path is therefore walked
+ * explicitly, one level at a time.
+ */
+function directChildren(parent, ns, local) {
+    const out = [];
+    const nodes = parent.childNodes;
+    for (let i = 0; i < nodes.length; i++) {
+        const node = nodes[i];
+        // nodeType 1 is ELEMENT_NODE; the constant is unavailable without the dom
+        // lib, which this project deliberately does not use.
+        if (node.nodeType === 1 &&
+            node.namespaceURI === ns &&
+            node.localName === local) {
+            out.push(node);
+        }
+    }
+    return out;
+}
+/** The single direct child with this name, or null when there is not exactly one. */
+function directChild(parent, ns, local) {
+    const found = directChildren(parent, ns, local);
+    // Not "the first": two siblings sharing a name is an ambiguity, and
+    // resolving it silently in favour of the first is how a forged element comes
+    // to be read in preference to a real one.
+    return found.length === 1 ? found[0] : null;
+}
+/**
+ * Whether every `saml:Assertion` and `saml:EncryptedAssertion` in the
+ * document is `assertion` itself or lies inside it.
+ */
+function everyAssertionWithin(doc, assertion) {
+    for (const local of ['Assertion', 'EncryptedAssertion']) {
+        const found = doc.getElementsByTagNameNS(SAML_NS, local);
+        for (let i = 0; i < found.length; i++) {
+            let node = found[i];
+            while (node && node !== assertion) {
+                node = node.parentNode;
+            }
+            if (!node)
+                return false;
+        }
+    }
+    return true;
+}
+/**
+ * The assertion the signature covers, or null when the signed element is not
+ * one and does not contain exactly one.
+ *
+ * "Exactly one" matters: a signed Response wrapping two assertions leaves
+ * "which did we verify" ambiguous, which is the wrapping question again.
+ */
+function assertionInside(signed, root, require) {
+    // The signature must cover what this validator was built to require. A
+    // signed-Response validator handed an assertion-signed document refuses
+    // here, and vice versa — that refusal is the whole point of shipping two.
+    const signedIsResponse = signed.localName === 'Response' && signed.namespaceURI === PROTOCOL_NS;
+    const signedIsAssertion = signed.localName === 'Assertion' && signed.namespaceURI === SAML_NS;
+    if (require === 'response' && !signedIsResponse)
+        return null;
+    if (require === 'assertion' && !signedIsAssertion)
+        return null;
+    // A bare Assertion is its own document: the only assertion there is, and
+    // it must be the element signed.
+    if (root.localName === 'Assertion' && root.namespaceURI === SAML_NS) {
+        return signed === root ? root : null;
+    }
+    // Whatever was signed, the response must carry exactly one assertion.
+    //
+    // Reading only from the signed element is not enough: Saml2PureProvider
+    // hands the whole response to the cookie provider, which reads whatever is
+    // in it. (toBearerAssertion refuses a second assertion on the bearer path
+    // too, but the validator does not lean on its caller.) A forged assertion
+    // placed beside the signed one must therefore end the login, not merely be
+    // ignored here.
+    const assertions = directChildren(root, SAML_NS, 'Assertion');
+    if (assertions.length !== 1)
+        return null;
+    const only = assertions[0];
+    if (signed.localName === 'Assertion' && signed.namespaceURI === SAML_NS) {
+        return signed === only ? only : null;
+    }
+    if (signed.localName === 'Response' && signed.namespaceURI === PROTOCOL_NS) {
+        return signed === root ? only : null;
+    }
+    return null;
+}
+/**
+ * The bearer confirmation this login may rely on.
+ *
+ * Every part must hold on the **same** element: gathering `InResponseTo` from
+ * one confirmation and `Recipient` from another is how a document satisfies a
+ * check nothing in it actually satisfies. When several qualify — which a real
+ * identity provider does not produce — the earliest window wins, so the
+ * outcome is a shorter session rather than a longer one.
+ *
+ * `latestNotOnOrAfter` answers a different question: until when could some
+ * confirmation let this assertion in? It is the latest `NotOnOrAfter` among
+ * the confirmations that satisfy every non-temporal part — including one whose
+ * `NotBefore` has not arrived yet, since it qualifies once it does. Replay
+ * retention needs that bound, not the session's; see the caller.
+ */
+function chooseBearerConfirmation(assertion, context, skew) {
+    const now = Date.now();
+    let best = null;
+    let latest = null;
+    const subject = directChild(assertion, SAML_NS, 'Subject');
+    if (!subject)
+        return null;
+    for (const confirmation of directChildren(subject, SAML_NS, 'SubjectConfirmation')) {
+        if (confirmation.getAttribute('Method') !== BEARER)
+            continue;
+        const data = directChild(confirmation, SAML_NS, 'SubjectConfirmationData');
+        if (!data)
+            continue;
+        // Option B: an expected ID must be matched exactly; no expected ID — an
+        // IdP-initiated login — means the attribute must not be there at all.
+        if (context.expectedInResponseTo === undefined) {
+            if (data.hasAttribute('InResponseTo'))
+                continue;
+        }
+        else if (data.getAttribute('InResponseTo') !== context.expectedInResponseTo) {
+            continue;
+        }
+        if (data.getAttribute('Recipient') !== context.acsUrl)
+            continue;
+        const notOnOrAfter = (0, xsdDateTime_1.parseXsdDateTime)(data.getAttribute('NotOnOrAfter'));
+        if (!notOnOrAfter)
+            continue;
+        const notBeforeRaw = data.getAttribute('NotBefore');
+        const notBefore = notBeforeRaw ? (0, xsdDateTime_1.parseXsdDateTime)(notBeforeRaw) : null;
+        if (notBeforeRaw && !notBefore)
+            continue;
+        // Could qualify at some instant: counts towards how long to remember.
+        if (!latest || notOnOrAfter.getTime() > latest.getTime()) {
+            latest = notOnOrAfter;
+        }
+        // Qualifies now: a candidate for the session's window.
+        if (notOnOrAfter.getTime() + skew <= now)
+            continue;
+        if (notBefore && notBefore.getTime() - skew > now)
+            continue;
+        if (!best || notOnOrAfter.getTime() < best.getTime())
+            best = notOnOrAfter;
+    }
+    // `latest` is set whenever `best` is: every qualifying confirmation was
+    // counted towards it first.
+    return best && latest
+        ? { notOnOrAfter: best, latestNotOnOrAfter: latest }
+        : null;
+}

package/dist/validation/documentIds.d.ts

@@ -0,0 +1,15 @@
+import type { Document, Element } from '@xmldom/xmldom';
+/**
+ * The `ID` rules, which run before any signature reference is resolved.
+ *
+ * XML-DSig resolves its reference by `ID`. Two elements sharing one make
+ * "which element is signed" a question the parser answers rather than the
+ * specification, and that ambiguity is the classic lever for signature
+ * wrapping. So uniqueness is established first, across the whole document —
+ * not only across the two elements this validator happens to read.
+ */
+/** The first ID value appearing more than once, or null when all are unique. */
+export declare function findDuplicateId(doc: Document): string | null;
+/** The element's ID, or null when it is absent or empty. */
+export declare function readRequiredId(element: Element): string | null;
+//# sourceMappingURL=documentIds.d.ts.map

package/dist/validation/documentIds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"documentIds.d.ts","sourceRoot":"","sources":["../../src/validation/documentIds.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAExD;;;;;;;;GAQG;AAEH,gFAAgF;AAChF,wBAAgB,eAAe,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI,CAU5D;AAED,4DAA4D;AAC5D,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAG9D"}