@ultimat3/auth 30.8.0 → 31.0.0

package/src/saml-c14n.ts

@@ -0,0 +1,118 @@
+// Single responsibility: Exclusive XML Canonicalization 1.0 without comments over one element's
+// subtree — the bytes a SAML signature covers. Comments are dropped, which is why a reader taking
+// only a NameID's FIRST text node is fooled by `ada@corp.com<!---->.evil.com`: the signature
+// covers the concatenation, so `saml-xml.ts` readers concatenate too.
+
+import type { XmlAttribute, XmlElement } from './saml-xml';
+
+export interface C14nOptions {
+  /** The enveloped `ds:Signature`: it and its subtree are not part of the node set. */
+  readonly exclude?: XmlElement | undefined;
+  /** `InclusiveNamespaces PrefixList`; `#default` names the default namespace. */
+  readonly inclusivePrefixes?: readonly string[] | undefined;
+}
+
+/** `&name;` — one XML entity or character reference, as Exclusive C14N §2.3 writes it. */
+const ref = (name: string): string => `&${name};`;
+
+/**
+ * C14N's own tables, NOT core's `escapeHtml`: the spec fixes them byte for byte — `>` escaped in
+ * text but never in an attribute, `'` never, and CR/TAB/LF as `&#xD;`/`&#x9;`/`&#xA;` — and one
+ * byte off is a digest mismatch. `escapeHtml` is right for markup and wrong here.
+ */
+const TEXT_REFS: ReadonlyMap<string, string> = new Map([
+  ['&', ref('amp')],
+  ['<', ref('lt')],
+  ['>', ref('gt')],
+  ['\r', ref('#xD')],
+]);
+const ATTRIBUTE_REFS: ReadonlyMap<string, string> = new Map([
+  ['&', ref('amp')],
+  ['<', ref('lt')],
+  ['"', ref('quot')],
+  ['\t', ref('#x9')],
+  ['\n', ref('#xA')],
+  ['\r', ref('#xD')],
+]);
+
+/** A text node in canonical form. */
+export const c14nText = (value: string): string =>
+  value.replace(/[&<>\r]/g, (char) => TEXT_REFS.get(char) ?? char);
+
+/** An attribute value in canonical form, for between double quotes. */
+export const c14nAttribute = (value: string): string =>
+  value.replace(/[&<"\t\n\r]/g, (char) => ATTRIBUTE_REFS.get(char) ?? char);
+
+/** Code-unit order, which for the ASCII names SAML uses is the spec's code-point order. */
+const byKey = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
+
+/**
+ * The prefixes this element visibly utilises: its own, and its prefixed attributes' (`xml:` is
+ * never declared). An InclusiveNamespaces prefix is rendered by the inclusive rule instead — when
+ * it is in scope at all.
+ */
+function wanted(element: XmlElement, inclusive: ReadonlySet<string>): Set<string> {
+  const prefixes = new Set<string>([element.prefix ?? '']);
+  for (const attribute of element.attributes) {
+    if (attribute.prefix !== null && attribute.prefix !== 'xml') prefixes.add(attribute.prefix);
+  }
+  for (const prefix of inclusive) if (element.scope.has(prefix)) prefixes.add(prefix);
+  return prefixes;
+}
+
+function namespaces(
+  element: XmlElement,
+  rendered: Map<string, string>,
+  inclusive: ReadonlySet<string>,
+): string {
+  const out: [string, string][] = [];
+  for (const prefix of wanted(element, inclusive)) {
+    const uri = element.scope.get(prefix) ?? '';
+    // An empty default is only worth saying when an output ancestor said a non-empty one.
+    const previous = rendered.get(prefix) ?? '';
+    if (prefix === '' ? uri === previous : rendered.get(prefix) === uri) continue;
+    rendered.set(prefix, uri);
+    out.push([prefix, uri]);
+  }
+  out.sort((a, b) => byKey(a[0], b[0]));
+  return out
+    .map(
+      ([prefix, uri]) => ` ${prefix === '' ? 'xmlns' : `xmlns:${prefix}`}="${c14nAttribute(uri)}"`,
+    )
+    .join('');
+}
+
+const attributeOrder = (a: XmlAttribute, b: XmlAttribute): number =>
+  byKey(a.ns, b.ns) || byKey(a.local, b.local);
+
+function render(
+  element: XmlElement,
+  rendered: ReadonlyMap<string, string>,
+  options: C14nOptions,
+  inclusive: ReadonlySet<string>,
+  out: string[],
+): void {
+  const scope = new Map(rendered);
+  out.push(`<${element.qname}${namespaces(element, scope, inclusive)}`);
+  for (const attribute of [...element.attributes].sort(attributeOrder)) {
+    out.push(` ${attribute.qname}="${c14nAttribute(attribute.value)}"`);
+  }
+  out.push('>');
+  for (const child of element.children) {
+    if (child.kind === 'text') out.push(c14nText(child.value));
+    else if (child.kind === 'element' && child !== options.exclude) {
+      render(child, scope, options, inclusive, out);
+    }
+  }
+  out.push(`</${element.qname}>`);
+}
+
+/** The canonical form of `apex`'s subtree, as the string whose UTF-8 bytes are digested. */
+export function exclusiveC14n(apex: XmlElement, options: C14nOptions = {}): string {
+  const inclusive = new Set(
+    (options.inclusivePrefixes ?? []).map((prefix) => (prefix === '#default' ? '' : prefix)),
+  );
+  const out: string[] = [];
+  render(apex, new Map(), options, inclusive, out);
+  return out.join('');
+}

package/src/saml-certificate.ts

@@ -0,0 +1,47 @@
+// Single responsibility: an IdP's X.509 signing certificate (base64 DER, as metadata carries it)
+// → the RSA public key Web Crypto verifies with, its `subjectPublicKeyInfo` lifted by core's
+// `x509Spki` (Web Crypto takes no certificate).
+// Only the key is trusted: the certificate's dates and issuer are the metadata's business.
+
+import { x509Spki } from '@ultimat3/core';
+
+/** NIST SP 800-131A: an RSA key under 2048 bits signs nothing an SP should believe. */
+export const MIN_SAML_RSA_BITS = 2048;
+
+/** Strict base64 with the white space metadata wraps it in; `undefined` for anything else. */
+export function base64Bytes(text: string): Uint8Array<ArrayBuffer> | undefined {
+  const compact = text.replace(/[ \t\r\n]+/g, '');
+  if (compact === '' || !/^[A-Za-z0-9+/]+={0,2}$/.test(compact) || compact.length % 4 !== 0) {
+    return undefined;
+  }
+  const binary = atob(compact);
+  return Uint8Array.from(binary, (char) => char.charCodeAt(0));
+}
+
+/** The certificate's `subjectPublicKeyInfo` (core's one DER walk), or `undefined`. */
+export function certificateSpki(base64Der: string): Uint8Array<ArrayBuffer> | undefined {
+  const der = base64Bytes(base64Der);
+  return der === undefined ? undefined : x509Spki(der);
+}
+
+/**
+ * The verification key for RSA-SHA256, or `undefined` for a certificate that is unreadable, not
+ * RSA, or under `MIN_SAML_RSA_BITS`. The caller names the refusal; this file throws nothing.
+ */
+export async function samlVerifyKey(base64Der: string): Promise<CryptoKey | undefined> {
+  const spki = certificateSpki(base64Der);
+  if (spki === undefined) return undefined;
+  try {
+    const key = await crypto.subtle.importKey(
+      'spki',
+      spki,
+      { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' },
+      false,
+      ['verify'],
+    );
+    const { modulusLength } = key.algorithm as RsaHashedKeyAlgorithm;
+    return modulusLength >= MIN_SAML_RSA_BITS ? key : undefined;
+  } catch {
+    return undefined;
+  }
+}

package/src/saml-dom.ts

@@ -0,0 +1,66 @@
+// Single responsibility: reading a parsed SAML tree — the namespaces and algorithm URIs SAML
+// speaks, and the four lookups every reader needs. Matched by namespace URI and local name, never
+// by prefix: a prefix is the sender's choice, and matching `saml:` would let `evil:Assertion`
+// bound to the same URI walk past a check, or `saml:` bound to another URI walk into one.
+
+import type { XmlElement } from './saml-xml';
+
+export const SAMLP_NS = 'urn:oasis:names:tc:SAML:2.0:protocol';
+export const SAML_NS = 'urn:oasis:names:tc:SAML:2.0:assertion';
+export const MD_NS = 'urn:oasis:names:tc:SAML:2.0:metadata';
+export const DSIG_NS = 'http://www.w3.org/2000/09/xmldsig#';
+export const EXC_C14N = 'http://www.w3.org/2001/10/xml-exc-c14n#';
+export const ENVELOPED = 'http://www.w3.org/2000/09/xmldsig#enveloped-signature';
+export const RSA_SHA256 = 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256';
+export const SHA256 = 'http://www.w3.org/2001/04/xmlenc#sha256';
+export const BINDING_REDIRECT = 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect';
+export const BINDING_POST = 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST';
+export const STATUS_SUCCESS = 'urn:oasis:names:tc:SAML:2.0:status:Success';
+export const BEARER = 'urn:oasis:names:tc:SAML:2.0:cm:bearer';
+export const NAMEID_PERSISTENT = 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent';
+export const NAMEID_TRANSIENT = 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient';
+export const NAMEID_EMAIL = 'urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress';
+
+export const isElement = (element: XmlElement, ns: string, local: string): boolean =>
+  element.ns === ns && element.local === local;
+
+export function childElements(element: XmlElement, ns?: string, local?: string): XmlElement[] {
+  const out: XmlElement[] = [];
+  for (const child of element.children) {
+    if (child.kind !== 'element') continue;
+    if (ns !== undefined && local !== undefined && !isElement(child, ns, local)) continue;
+    out.push(child);
+  }
+  return out;
+}
+
+/** Every element below `element`, in document order, `element` excluded. */
+export function descendants(element: XmlElement): XmlElement[] {
+  const out: XmlElement[] = [];
+  const walk = (node: XmlElement): void => {
+    for (const child of childElements(node)) {
+      out.push(child);
+      walk(child);
+    }
+  };
+  walk(element);
+  return out;
+}
+
+/** An unqualified attribute — SAML's own attributes are never namespaced. */
+export function attribute(element: XmlElement, local: string): string | undefined {
+  return element.attributes.find((one) => one.ns === '' && one.local === local)?.value;
+}
+
+/**
+ * The element's text: EVERY text child, concatenated — what the signature covered, since c14n
+ * drops comments. `undefined` when it holds an element, which no SAML leaf value does.
+ */
+export function textOf(element: XmlElement): string | undefined {
+  let text = '';
+  for (const child of element.children) {
+    if (child.kind === 'element') return undefined;
+    if (child.kind === 'text') text += child.value;
+  }
+  return text;
+}

package/src/saml-dsig.ts

@@ -0,0 +1,165 @@
+// Single responsibility: verify the ONE enveloped XML-DSig signature that is a direct child of an
+// element, over that element alone. Wrapping makes the verifier and the reader look at two nodes;
+// here there is no lookup to fool — the caller hands in the node it will read, the Reference must
+// name THAT node's ID, and the key comes from metadata, never from the document's KeyInfo.
+
+import { exclusiveC14n } from './saml-c14n';
+import { base64Bytes } from './saml-certificate';
+import {
+  attribute,
+  childElements,
+  DSIG_NS,
+  ENVELOPED,
+  EXC_C14N,
+  isElement,
+  RSA_SHA256,
+  SHA256,
+  textOf,
+} from './saml-dom';
+import type { SamlCheck } from './saml-errors';
+import type { XmlElement } from './saml-xml';
+
+export type DsigVerdict =
+  | { readonly ok: true }
+  | { readonly ok: false; readonly check: SamlCheck; readonly detail: string };
+
+const fail = (check: SamlCheck, detail: string): DsigVerdict => ({ ok: false, check, detail });
+
+/** The ds:* element children, white space skipped; any other child is a refusal. */
+function dsChildren(element: XmlElement): XmlElement[] | undefined {
+  for (const child of element.children) {
+    if (child.kind === 'text' && child.value.trim() !== '') return undefined;
+    if (child.kind === 'element' && child.ns !== DSIG_NS) return undefined;
+  }
+  return childElements(element);
+}
+
+/** The algorithm, plus the `InclusiveNamespaces PrefixList` exc-c14n allows under it. */
+function c14nPrefixes(method: XmlElement): readonly string[] | undefined {
+  if (attribute(method, 'Algorithm') !== EXC_C14N) return undefined;
+  const inner = childElements(method);
+  if (inner.length === 0) return [];
+  const only = inner[0];
+  if (inner.length !== 1 || only === undefined || only.ns !== EXC_C14N) return undefined;
+  if (only.local !== 'InclusiveNamespaces') return undefined;
+  return (attribute(only, 'PrefixList') ?? '').split(/[ \t\n]+/).filter((p) => p !== '');
+}
+
+interface ReferenceShape {
+  readonly prefixes: readonly string[];
+  readonly digest: Uint8Array;
+}
+
+function readReference(reference: XmlElement, signed: XmlElement): ReferenceShape | DsigVerdict {
+  const id = attribute(signed, 'ID');
+  if (id === undefined || id === '') return fail('reference', 'the signed element carries no ID');
+  if (attribute(reference, 'URI') !== `#${id}`) {
+    return fail('reference', 'the Reference URI does not name the element it is enveloped in');
+  }
+  const parts = dsChildren(reference);
+  const [transforms, method, value] = parts ?? [];
+  if (
+    parts?.length !== 3 ||
+    transforms === undefined ||
+    method === undefined ||
+    value === undefined
+  ) {
+    return fail('reference', 'the Reference is not Transforms, DigestMethod, DigestValue');
+  }
+  if (!isElement(transforms, DSIG_NS, 'Transforms')) return fail('reference', 'no Transforms');
+  // Exactly enveloped-signature then exc-c14n: an XPath or XSLT transform is how a signature is
+  // made to cover a different node set than the one the reader reads.
+  const steps = dsChildren(transforms) ?? [];
+  const [first, second] = steps;
+  if (steps.length !== 2 || first === undefined || second === undefined) {
+    return fail('algorithm', 'the transforms are not enveloped-signature then exc-c14n');
+  }
+  const prefixes = c14nPrefixes(second);
+  if (attribute(first, 'Algorithm') !== ENVELOPED || childElements(first).length > 0) {
+    return fail('algorithm', 'the first transform is not enveloped-signature');
+  }
+  if (prefixes === undefined) return fail('algorithm', 'the second transform is not exc-c14n');
+  if (!isElement(method, DSIG_NS, 'DigestMethod') || attribute(method, 'Algorithm') !== SHA256) {
+    return fail('algorithm', 'the digest is not SHA-256');
+  }
+  const digest = isElement(value, DSIG_NS, 'DigestValue')
+    ? base64Bytes(textOf(value) ?? '')
+    : undefined;
+  return digest === undefined
+    ? fail('reference', 'the DigestValue is not base64')
+    : { prefixes, digest };
+}
+
+const equalBytes = (a: Uint8Array, b: Uint8Array): boolean =>
+  a.length === b.length && a.every((byte, index) => byte === b[index]);
+
+const utf8 = (text: string): Uint8Array<ArrayBuffer> => new TextEncoder().encode(text);
+
+/**
+ * Verify `signed`'s own enveloped signature against the metadata keys. `{ ok: false }` names the
+ * check; `signature-missing` when the element carries none (the caller decides if that is fatal).
+ */
+export async function verifyEnvelopedSignature(
+  signed: XmlElement,
+  keys: readonly CryptoKey[],
+): Promise<DsigVerdict> {
+  const signatures = childElements(signed, DSIG_NS, 'Signature');
+  const signature = signatures[0];
+  if (signature === undefined) return fail('signature-missing', 'the element carries no signature');
+  if (signatures.length > 1) return fail('structure', 'the element carries two signatures');
+  // SignedInfo, SignatureValue, then an optional KeyInfo that is never read. A ds:Object is where
+  // wrapping attacks hide the original assertion, so its presence alone is a refusal.
+  const parts = dsChildren(signature) ?? [];
+  const [signedInfo, signatureValue, keyInfo] = parts;
+  if (
+    signedInfo === undefined ||
+    signatureValue === undefined ||
+    !isElement(signedInfo, DSIG_NS, 'SignedInfo') ||
+    !isElement(signatureValue, DSIG_NS, 'SignatureValue') ||
+    parts.length > 3 ||
+    (keyInfo !== undefined && !isElement(keyInfo, DSIG_NS, 'KeyInfo'))
+  ) {
+    return fail('structure', 'the Signature is not SignedInfo, SignatureValue[, KeyInfo]');
+  }
+  const info = dsChildren(signedInfo) ?? [];
+  const [c14nMethod, signatureMethod, reference] = info;
+  if (
+    info.length !== 3 ||
+    c14nMethod === undefined ||
+    signatureMethod === undefined ||
+    reference === undefined
+  ) {
+    return fail('reference', 'SignedInfo must hold exactly one Reference');
+  }
+  const infoPrefixes = isElement(c14nMethod, DSIG_NS, 'CanonicalizationMethod')
+    ? c14nPrefixes(c14nMethod)
+    : undefined;
+  if (infoPrefixes === undefined) return fail('algorithm', 'SignedInfo is not exc-c14n');
+  if (
+    !isElement(signatureMethod, DSIG_NS, 'SignatureMethod') ||
+    attribute(signatureMethod, 'Algorithm') !== RSA_SHA256 ||
+    childElements(signatureMethod).length > 0
+  ) {
+    return fail('algorithm', 'the signature is not RSA-SHA256');
+  }
+  if (!isElement(reference, DSIG_NS, 'Reference')) return fail('reference', 'no Reference');
+  const shape = readReference(reference, signed);
+  if ('ok' in shape) return shape;
+
+  const value = base64Bytes(textOf(signatureValue) ?? '');
+  if (value === undefined) return fail('signature', 'the SignatureValue is not base64');
+  const canonicalInfo = utf8(exclusiveC14n(signedInfo, { inclusivePrefixes: infoPrefixes }));
+  let verified = false;
+  for (const key of keys) {
+    if (await crypto.subtle.verify('RSASSA-PKCS1-v1_5', key, value, canonicalInfo)) verified = true;
+  }
+  if (!verified) return fail('signature', 'no metadata certificate verifies the SignedInfo');
+
+  const canonical = exclusiveC14n(signed, {
+    exclude: signature,
+    inclusivePrefixes: shape.prefixes,
+  });
+  const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', utf8(canonical)));
+  if (!equalBytes(digest, shape.digest)) return fail('digest', 'the signed content was altered');
+  return { ok: true };
+}

package/src/saml-email-trust.ts

@@ -0,0 +1,49 @@
+// Single responsibility: which asserted addresses a SAML IdP may vouch for. An IdP is one tenant's
+// directory, and its admin can assert ANY address — so "trust this IdP's email" without a domain
+// is "let one customer's admin sign in as another customer's verified user" (`resolveUser` links a
+// verified provider address to the existing account). Trust is therefore per domain, exact.
+
+import { renderCauseValue } from '@ultimat3/core';
+import { AuthError } from './errors';
+
+/** The trust half of `SamlIdentityProviderConfig`: `true` cannot be written without its domains. */
+export type SamlEmailTrust =
+  | {
+      /** The IdP's addresses are never treated as verified: they cannot link or create accounts. */
+      readonly trustEmail: false;
+      readonly emailDomains?: undefined;
+    }
+  | {
+      /** Addresses in `emailDomains` are verified; any other is not, and cannot link. */
+      readonly trustEmail: true;
+      /** The domains this IdP owns, exactly — a subdomain is listed on its own. Never empty. */
+      readonly emailDomains: readonly string[];
+    };
+
+/** A DNS name: labels of letters, digits and inner hyphens. No wildcard, no trailing dot. */
+const DOMAIN = /^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z][a-z0-9-]{0,62}$/;
+
+/** The screened, lower-cased domain set; refuses at construction, never at the first login. */
+export function samlTrustedDomains(provider: string, trust: SamlEmailTrust): ReadonlySet<string> {
+  if (!trust.trustEmail) return new Set();
+  const domains = (trust.emailDomains ?? []).map((domain) => domain.trim().toLowerCase());
+  const bad = domains.find((domain) => !DOMAIN.test(domain));
+  if (domains.length === 0 || bad !== undefined) {
+    throw new AuthError({
+      code: 'X_CONFIG_INVALID',
+      cause:
+        bad === undefined
+          ? `samlIdentityProvider ${renderCauseValue(provider)} trusts asserted addresses with no emailDomains, so its admin could assert any tenant's address`
+          : `samlIdentityProvider ${renderCauseValue(provider)} lists ${renderCauseValue(bad)} in emailDomains, which is not a plain domain`,
+      fix: "samlIdentityProvider({ trustEmail: true, emailDomains: ['corp.example'] })  // the exact domains this IdP owns, or trustEmail: false",
+      meta: { provider },
+    });
+  }
+  return new Set(domains);
+}
+
+/** Whether `email`'s domain is one the IdP owns. Only the part after the LAST `@` is a domain. */
+export function isTrustedAddress(email: string, domains: ReadonlySet<string>): boolean {
+  const at = email.lastIndexOf('@');
+  return at > 0 && domains.has(email.slice(at + 1).toLowerCase());
+}

package/src/saml-errors.ts

@@ -0,0 +1,96 @@
+// Single responsibility: the SAML refusals. One code for every check a response can fail —
+// `X_SAML_RESPONSE_INVALID` with the check in `meta.check` — because the operator needs to know
+// WHICH check (an audience mismatch is the commonest setup bug there is) and the anonymous caller
+// gets none of it: the route serves the code and its title only, like the OAuth legs.
+
+import { renderCauseValue } from '@ultimat3/core';
+import { AuthError } from './errors';
+
+/** Every check a response is put through, in the order `verifySamlResponse` runs them. */
+export type SamlCheck =
+  | 'encoding'
+  | 'xml'
+  | 'structure'
+  | 'id-duplicate'
+  | 'encrypted'
+  | 'signature-missing'
+  | 'algorithm'
+  | 'reference'
+  | 'signature'
+  | 'digest'
+  | 'status'
+  | 'issuer'
+  | 'destination'
+  | 'in-response-to'
+  | 'recipient'
+  | 'audience'
+  | 'not-before'
+  | 'expired'
+  | 'subject'
+  | 'relay-state'
+  | 'replay';
+
+const SP = 'samlIdentityProvider({ id, idp: parseSamlMetadata(xml), spEntityId, trustEmail })';
+const IDP_APP = `${SP}  // unchanged here; in the IdP application:`;
+const METADATA =
+  "parseSamlMetadata(await Bun.file('idp-metadata.xml').text())  // the IdP current metadata";
+
+/**
+ * The repair per check. Each opens with the code to paste (`X_FIX_PROSE`): the SP side as a call,
+ * an IdP-side setting as that call's trailing comment, a retry as the route to start again at.
+ */
+const FIXES: Readonly<Record<SamlCheck, string>> = {
+  encoding:
+    'identityProviderRoutes(auth, { providers }).acs  // mount as-is: SAMLResponse arrives base64 and is decoded once',
+  xml: `${IDP_APP} send a plain SAML 2.0 Response, no DOCTYPE or processing instruction`,
+  structure: `${IDP_APP} one samlp:Response holding exactly one saml:Assertion`,
+  'id-duplicate':
+    'oauthStartPath(id)  // start again here; a response carrying one ID twice is a wrapping attempt, never accepted',
+  encrypted: `${IDP_APP} turn assertion encryption off (not supported)`,
+  'signature-missing': `${IDP_APP} turn on "sign assertion" (a signed response alone is refused)`,
+  algorithm: `${IDP_APP} RSA-SHA256 signatures, SHA-256 digests, exclusive c14n`,
+  reference: `${IDP_APP} sign the assertion by its ID with the enveloped-signature transform`,
+  signature: `${METADATA}, pasted into samlIdentityProvider({ idp }): its signing certificate has likely rotated`,
+  digest:
+    'oauthStartPath(id)  // start again; if it repeats, remove the proxy rewriting the POST body between the IdP and this app',
+  status: `${IDP_APP} assign this user to the application (the IdP answer is in meta.status)`,
+  issuer: `${METADATA}: its entityID must be the assertion Issuer`,
+  destination: 'oauthCallbackPath(id)  // the IdP application ACS URL is APP_URL + this path',
+  'in-response-to':
+    'oauthStartPath(id)  // start the sign-in here, not from the IdP dashboard: IdP-initiated responses are refused',
+  recipient: 'oauthCallbackPath(id)  // the IdP application ACS URL is APP_URL + this path',
+  audience:
+    'samlIdentityProvider({ spEntityId })  // equal to the audience (SP entity id) the IdP application names',
+  'not-before':
+    'samlIdentityProvider({ skewMs: 120_000 })  // or sync the server clock first: chronyc makestep',
+  expired: 'oauthStartPath(id)  // sync the server clock (chronyc makestep), then start again here',
+  subject: `${IDP_APP} NameID format persistent (or emailAddress)`,
+  'relay-state': 'oauthStartPath(id)  // start again here, in the same browser',
+  replay: 'oauthStartPath(id)  // start again here: an assertion is accepted once',
+};
+
+/**
+ * Read as a `Map` (`proto-index`): the `Record` above is what makes a missing check a compile
+ * error; the lookup never indexes a plain object.
+ */
+const FIX_BY_CHECK: ReadonlyMap<string, string> = new Map(Object.entries(FIXES));
+
+export const samlResponseInvalid = (
+  provider: string,
+  check: SamlCheck,
+  detail: string,
+  meta: Readonly<Record<string, unknown>> = {},
+): AuthError =>
+  new AuthError({
+    code: 'X_SAML_RESPONSE_INVALID',
+    cause: `the ${renderCauseValue(provider)} SAML response failed its ${check} check: ${detail}`,
+    fix: FIX_BY_CHECK.get(check) ?? FIXES.xml,
+    meta: { ...meta, provider, check },
+  });
+
+export const samlMetadataInvalid = (detail: string): AuthError =>
+  new AuthError({
+    code: 'X_SAML_METADATA_INVALID',
+    cause: `the SAML IdP metadata is unusable: ${detail}`,
+    fix: `${METADATA} XML, whole, downloaded again from its federation metadata URL`,
+  });

package/src/saml-metadata.ts

@@ -0,0 +1,80 @@
+// Single responsibility: an IdP's SAML 2.0 metadata → its `entityID`, HTTP-Redirect sign-on URL
+// and signing certificates. Parsed at boot, so a bad file fails the deploy, not the first login.
+// The metadata is the operator's pinned trust anchor; its own signature is not checked here —
+// fetch it over TLS, or paste it.
+
+import { samlVerifyKey } from './saml-certificate';
+import {
+  attribute,
+  BINDING_REDIRECT,
+  childElements,
+  DSIG_NS,
+  descendants,
+  isElement,
+  MD_NS,
+  textOf,
+} from './saml-dom';
+import { samlMetadataInvalid } from './saml-errors';
+import { parseXml } from './saml-xml';
+
+export interface SamlIdpMetadata {
+  readonly entityId: string;
+  /** The HTTP-Redirect SingleSignOnService location the AuthnRequest is sent to. */
+  readonly ssoUrl: string;
+  /** Base64 DER X.509 certificates. More than one during a key rollover: any of them verifies. */
+  readonly certificates: readonly string[];
+}
+
+function signingCertificates(descriptor: Parameters<typeof childElements>[0]): string[] {
+  const out: string[] = [];
+  for (const key of childElements(descriptor, MD_NS, 'KeyDescriptor')) {
+    const use = attribute(key, 'use');
+    if (use !== undefined && use !== 'signing') continue;
+    for (const node of descendants(key)) {
+      if (!isElement(node, DSIG_NS, 'X509Certificate')) continue;
+      const text = (textOf(node) ?? '').replace(/[ \t\n]+/g, '');
+      if (text !== '' && !out.includes(text)) out.push(text);
+    }
+  }
+  return out;
+}
+
+/** Parse metadata, or throw `X_SAML_METADATA_INVALID` naming what is missing. */
+export function parseSamlMetadata(xml: string): SamlIdpMetadata {
+  const parsed = parseXml(xml);
+  if (!parsed.ok) throw samlMetadataInvalid(`it is not readable XML (${parsed.reason})`);
+  const root = parsed.root;
+  if (!isElement(root, MD_NS, 'EntityDescriptor')) {
+    throw samlMetadataInvalid('the root is not one md:EntityDescriptor');
+  }
+  const entityId = attribute(root, 'entityID') ?? '';
+  if (entityId === '') throw samlMetadataInvalid('the EntityDescriptor has no entityID');
+  const descriptor = childElements(root, MD_NS, 'IDPSSODescriptor')[0];
+  if (descriptor === undefined) {
+    throw samlMetadataInvalid('there is no IDPSSODescriptor: this is not IdP metadata');
+  }
+  const sso = childElements(descriptor, MD_NS, 'SingleSignOnService').find(
+    (service) => attribute(service, 'Binding') === BINDING_REDIRECT,
+  );
+  const ssoUrl = sso === undefined ? '' : (attribute(sso, 'Location') ?? '');
+  if (!URL.canParse(ssoUrl)) {
+    throw samlMetadataInvalid('no HTTP-Redirect SingleSignOnService carries a Location URL');
+  }
+  const certificates = signingCertificates(descriptor);
+  if (certificates.length === 0) throw samlMetadataInvalid('no signing certificate is published');
+  return Object.freeze({ entityId, ssoUrl, certificates: Object.freeze(certificates) });
+}
+
+/** The verification keys, once per provider. A certificate that yields no RSA-2048+ key refuses. */
+export async function samlMetadataKeys(idp: SamlIdpMetadata): Promise<readonly CryptoKey[]> {
+  const keys: CryptoKey[] = [];
+  for (const certificate of idp.certificates) {
+    const key = await samlVerifyKey(certificate);
+    if (key === undefined) {
+      throw samlMetadataInvalid('a signing certificate is unreadable, not RSA, or under 2048 bits');
+    }
+    keys.push(key);
+  }
+  if (keys.length === 0) throw samlMetadataInvalid('no signing certificate is published');
+  return keys;
+}