@ultimat3/auth 30.8.0 → 31.0.0

package/src/saml-provider.ts

@@ -0,0 +1,179 @@
+// Single responsibility: SAML 2.0 Web SSO (SP-initiated, HTTP-Redirect out, HTTP-POST back) as an
+// `IdentityProvider`. `begin` mints the AuthnRequest; `complete` binds the answer to that request
+// (RelayState + InResponseTo), verifies it (`verifySamlResponse`), claims its assertion ID once,
+// and reads one profile out of it.
+
+import { timingSafeEqual } from '@ultimat3/core';
+import {
+  type IdentityProvider,
+  type IdentityRedirect,
+  replayStepFor,
+  type VerifiedIdentity,
+} from './identity-provider';
+import { isRecord } from './json';
+import { assertFiniteAuthCount } from './policy-numbers';
+import type { SamlAssertion } from './saml-assertion';
+import { NAMEID_EMAIL } from './saml-dom';
+import { isTrustedAddress, type SamlEmailTrust, samlTrustedDomains } from './saml-email-trust';
+import { samlResponseInvalid } from './saml-errors';
+import { type SamlIdpMetadata, samlMetadataKeys } from './saml-metadata';
+import { samlAuthnRequest } from './saml-request';
+import { verifySamlResponse } from './saml-response';
+
+/** The attribute names enterprise IdPs put an address under: Entra/ADFS, LDAP `mail`, eduPerson. */
+export const DEFAULT_SAML_EMAIL_ATTRIBUTES: readonly string[] = Object.freeze([
+  'email',
+  'mail',
+  'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress',
+  'urn:oid:0.9.2342.19200300.100.1.3',
+]);
+export const DEFAULT_SAML_NAME_ATTRIBUTES: readonly string[] = Object.freeze([
+  'displayName',
+  'name',
+  'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name',
+  'urn:oid:2.16.840.1.113730.3.1.241',
+]);
+/** One minute either way: what the major IdPs document as tolerable clock drift. */
+export const DEFAULT_SAML_SKEW_MS = 60_000;
+
+interface SamlProviderBase {
+  readonly id: string;
+  /** `parseSamlMetadata(xml)` — the trust anchor. Its certificates are the only keys believed. */
+  readonly idp: SamlIdpMetadata;
+  /** This SP's entity id: the Audience every assertion must name. */
+  readonly spEntityId: string;
+  readonly emailAttributes?: readonly string[] | undefined;
+  readonly nameAttributes?: readonly string[] | undefined;
+  /** Requested in the AuthnRequest's NameIDPolicy. Default persistent; transient is refused. */
+  readonly nameIdFormat?: string | undefined;
+  readonly skewMs?: number | undefined;
+}
+
+/**
+ * `trustEmail` is REQUIRED, never defaulted: SAML carries no `email_verified`, so the app says
+ * whether this IdP vouches for its addresses — and `true` names the exact `emailDomains` it owns.
+ * An address outside them is unverified: it neither links to an existing account nor creates one.
+ */
+export type SamlIdentityProviderConfig = SamlProviderBase & SamlEmailTrust;
+
+interface SamlState {
+  readonly requestId: string;
+  readonly relayState: string;
+}
+
+function readState(provider: string, state: string): SamlState {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(state);
+  } catch {
+    parsed = null;
+  }
+  if (
+    !isRecord(parsed) ||
+    typeof parsed['requestId'] !== 'string' ||
+    typeof parsed['relayState'] !== 'string'
+  ) {
+    throw samlResponseInvalid(provider, 'relay-state', 'the stored request is not a SAML request');
+  }
+  return { requestId: parsed['requestId'], relayState: parsed['relayState'] };
+}
+
+const firstOf = (assertion: SamlAssertion, names: readonly string[]): string | null => {
+  for (const name of names) {
+    const value = assertion.attributes[name]?.find((one) => one.trim() !== '');
+    if (value !== undefined) return value.trim();
+  }
+  return null;
+};
+
+function identityOf(
+  config: SamlIdentityProviderConfig,
+  trusted: ReadonlySet<string>,
+  assertion: SamlAssertion,
+): VerifiedIdentity {
+  const email =
+    firstOf(assertion, config.emailAttributes ?? DEFAULT_SAML_EMAIL_ATTRIBUTES) ??
+    (assertion.nameIdFormat === NAMEID_EMAIL ? assertion.nameId : null);
+  return {
+    profile: {
+      provider: config.id,
+      providerAccountId: assertion.nameId,
+      email,
+      emailVerified: email !== null && isTrustedAddress(email, trusted),
+      name: firstOf(assertion, config.nameAttributes ?? DEFAULT_SAML_NAME_ATTRIBUTES),
+    },
+    expiresAt: assertion.sessionNotOnOrAfter,
+    claims: {
+      issuer: assertion.issuer,
+      nameIdFormat: assertion.nameIdFormat,
+      sessionIndex: assertion.sessionIndex,
+      attributes: assertion.attributes,
+    },
+  };
+}
+
+export function samlIdentityProvider(config: SamlIdentityProviderConfig): IdentityProvider {
+  const skewMs = assertFiniteAuthCount(
+    'saml.skewMs',
+    config.skewMs ?? DEFAULT_SAML_SKEW_MS,
+    'every NotBefore and NotOnOrAfter comparison answers false, so an expired assertion is accepted',
+    0,
+  );
+  // Imported once, lazily, then shared: a certificate that yields no key refuses the first login
+  // with X_SAML_METADATA_INVALID rather than every login quietly failing its signature check.
+  let keys: Promise<readonly CryptoKey[]> | undefined;
+  const id = config.id;
+  const trusted = samlTrustedDomains(id, config);
+  const provider: IdentityProvider = {
+    id,
+    protocol: 'saml',
+    callbackMethod: 'POST',
+    async begin({ callbackUrl, clock }): Promise<IdentityRedirect> {
+      const request = samlAuthnRequest({
+        idp: config.idp,
+        spEntityId: config.spEntityId,
+        acsUrl: callbackUrl,
+        clock,
+        nameIdFormat: config.nameIdFormat,
+      });
+      const state: SamlState = { requestId: request.id, relayState: request.relayState };
+      return { location: request.location, state: JSON.stringify(state) };
+    },
+    answers(state, params) {
+      try {
+        return timingSafeEqual(readState(id, state).relayState, params['RelayState'] ?? '');
+      } catch {
+        return false;
+      }
+    },
+    async complete({ state, params, callbackUrl, clock, replay }): Promise<VerifiedIdentity> {
+      const stored = readState(id, state);
+      if (!timingSafeEqual(stored.relayState, params['RelayState'] ?? '')) {
+        throw samlResponseInvalid(
+          id,
+          'relay-state',
+          'RelayState is not the one this browser was sent with',
+        );
+      }
+      keys ??= samlMetadataKeys(config.idp);
+      const now = clock.now();
+      const assertion = await verifySamlResponse(params['SAMLResponse'] ?? '', {
+        provider: id,
+        idpEntityId: config.idp.entityId,
+        keys: await keys,
+        audience: config.spEntityId,
+        recipient: callbackUrl,
+        requestId: stored.requestId,
+        now,
+        skewMs,
+      });
+      const horizon = new Date(assertion.notOnOrAfter.getTime() + skewMs);
+      const subject = `saml:${config.idp.entityId}:${assertion.id}`;
+      if (!(await replay.claim(subject, replayStepFor(horizon), now))) {
+        throw samlResponseInvalid(id, 'replay', 'this assertion was already consumed');
+      }
+      return identityOf(config, trusted, assertion);
+    },
+  };
+  return Object.freeze(provider);
+}

package/src/saml-request.ts

@@ -0,0 +1,51 @@
+// Single responsibility: the SP-initiated leg — an AuthnRequest, DEFLATEd and base64'd onto the
+// IdP's HTTP-Redirect endpoint with a RelayState (SAML Bindings §3.4). Unsigned: the response is
+// what is verified, and the request's ID comes back as InResponseTo, which is the binding that
+// matters. The ID and RelayState are random and returned so the caller can seal them.
+
+import { type Clock, escapeHtml } from '@ultimat3/core';
+import { BINDING_POST, NAMEID_PERSISTENT, SAML_NS, SAMLP_NS } from './saml-dom';
+import type { SamlIdpMetadata } from './saml-metadata';
+import { randomToken } from './tokens';
+
+export interface SamlAuthnRequestInput {
+  readonly idp: SamlIdpMetadata;
+  readonly spEntityId: string;
+  /** Where the IdP POSTs the response: the callback route for this provider. */
+  readonly acsUrl: string;
+  readonly clock: Clock;
+  readonly nameIdFormat?: string | undefined;
+}
+
+export interface SamlAuthnRequest {
+  /** `ID` of the request; the response must answer it as `InResponseTo`. */
+  readonly id: string;
+  /** Echoed by the IdP; ≤ 80 bytes as Bindings §3.4.3 requires. */
+  readonly relayState: string;
+  readonly xml: string;
+  /** The IdP URL to redirect the browser to. */
+  readonly location: string;
+}
+
+/** IssueInstant is UTC by definition (SAML Core §1.3.3), without milliseconds. */
+const instant = (at: Date): string => `${at.toISOString().slice(0, 19)}Z`;
+
+export function samlAuthnRequest(input: SamlAuthnRequestInput): SamlAuthnRequest {
+  // `_` first: an xs:ID is an NCName, which may not start with a digit; base64url is NCName-safe.
+  const id = `_${randomToken(20)}`;
+  const relayState = randomToken(24);
+  const xml =
+    `<samlp:AuthnRequest xmlns:samlp="${SAMLP_NS}" xmlns:saml="${SAML_NS}"` +
+    ` ID="${id}" Version="2.0" IssueInstant="${instant(input.clock.now())}"` +
+    ` Destination="${escapeHtml(input.idp.ssoUrl)}"` +
+    ` AssertionConsumerServiceURL="${escapeHtml(input.acsUrl)}"` +
+    ` ProtocolBinding="${BINDING_POST}">` +
+    `<saml:Issuer>${escapeHtml(input.spEntityId)}</saml:Issuer>` +
+    `<samlp:NameIDPolicy Format="${escapeHtml(input.nameIdFormat ?? NAMEID_PERSISTENT)}" AllowCreate="true"/>` +
+    '</samlp:AuthnRequest>';
+  const deflated = Bun.deflateSync(new TextEncoder().encode(xml));
+  const url = new URL(input.idp.ssoUrl);
+  url.searchParams.set('SAMLRequest', btoa(String.fromCharCode(...deflated)));
+  url.searchParams.set('RelayState', relayState);
+  return { id, relayState, xml, location: url.toString() };
+}

package/src/saml-response.ts

@@ -0,0 +1,131 @@
+// Single responsibility: a posted SAMLResponse → one verified `SamlAssertion`, or
+// `X_SAML_RESPONSE_INVALID` naming the check. The shape is pinned before any signature — one
+// Response, ONE Assertion in the document as its direct child, no ID twice, nothing encrypted —
+// and the assertion's OWN signature is required; a response signature, if present, must verify.
+
+import {
+  type AssertionExpectations,
+  AssertionRefusal,
+  readAssertion,
+  type SamlAssertion,
+} from './saml-assertion';
+import { base64Bytes } from './saml-certificate';
+import {
+  attribute,
+  childElements,
+  descendants,
+  isElement,
+  SAML_NS,
+  SAMLP_NS,
+  STATUS_SUCCESS,
+  textOf,
+} from './saml-dom';
+import { verifyEnvelopedSignature } from './saml-dsig';
+import { samlResponseInvalid } from './saml-errors';
+import { parseXml, type XmlElement } from './saml-xml';
+
+export interface SamlResponseExpectations extends Omit<AssertionExpectations, 'issuer'> {
+  /** The provider id, for the refusal. */
+  readonly provider: string;
+  readonly idpEntityId: string;
+  readonly keys: readonly CryptoKey[];
+}
+
+function decodeResponse(provider: string, posted: string): XmlElement {
+  const bytes = base64Bytes(posted);
+  if (bytes === undefined)
+    throw samlResponseInvalid(provider, 'encoding', 'SAMLResponse is not base64');
+  let xml: string;
+  try {
+    xml = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+  } catch {
+    throw samlResponseInvalid(provider, 'encoding', 'SAMLResponse is not UTF-8');
+  }
+  const parsed = parseXml(xml);
+  if (!parsed.ok)
+    throw samlResponseInvalid(provider, 'xml', 'the document was refused by the reader');
+  return parsed.root;
+}
+
+/** The one assertion, after every structural refusal a wrapping attack would need to survive. */
+function soleAssertion(provider: string, response: XmlElement): XmlElement {
+  if (!isElement(response, SAMLP_NS, 'Response')) {
+    throw samlResponseInvalid(provider, 'structure', 'the root is not samlp:Response');
+  }
+  const all = descendants(response);
+  const ids = new Set<string>();
+  for (const element of [response, ...all]) {
+    const id = attribute(element, 'ID');
+    if (id === undefined) continue;
+    if (ids.has(id))
+      throw samlResponseInvalid(provider, 'id-duplicate', 'two elements share one ID');
+    ids.add(id);
+  }
+  if (all.some((el) => el.local === 'EncryptedAssertion' || el.local === 'EncryptedID')) {
+    throw samlResponseInvalid(provider, 'encrypted', 'encrypted assertions are not supported');
+  }
+  const assertions = all.filter((el) => isElement(el, SAML_NS, 'Assertion'));
+  const assertion = assertions[0];
+  if (assertions.length !== 1 || assertion === undefined || assertion.parent !== response) {
+    throw samlResponseInvalid(
+      provider,
+      'structure',
+      'the response must hold exactly one assertion, directly',
+    );
+  }
+  return assertion;
+}
+
+function responseHeader(
+  provider: string,
+  response: XmlElement,
+  expect: SamlResponseExpectations,
+): void {
+  const status = childElements(response, SAMLP_NS, 'Status')[0];
+  const code = status === undefined ? undefined : childElements(status, SAMLP_NS, 'StatusCode')[0];
+  const value = code === undefined ? undefined : attribute(code, 'Value');
+  if (value !== STATUS_SUCCESS) {
+    throw samlResponseInvalid(provider, 'status', 'the IdP did not answer Success', {
+      status: value ?? null,
+    });
+  }
+  const destination = attribute(response, 'Destination');
+  if (destination !== undefined && destination !== expect.recipient) {
+    throw samlResponseInvalid(provider, 'destination', 'the Destination is not this ACS URL');
+  }
+  const inResponseTo = attribute(response, 'InResponseTo');
+  if (inResponseTo !== expect.requestId) {
+    throw samlResponseInvalid(provider, 'in-response-to', 'the response answers another request');
+  }
+  const issuer = childElements(response, SAML_NS, 'Issuer')[0];
+  if (issuer !== undefined && textOf(issuer) !== expect.idpEntityId) {
+    throw samlResponseInvalid(
+      provider,
+      'issuer',
+      'the response Issuer is not the metadata entityID',
+    );
+  }
+}
+
+export async function verifySamlResponse(
+  posted: string,
+  expect: SamlResponseExpectations,
+): Promise<SamlAssertion> {
+  const { provider, keys } = expect;
+  const response = decodeResponse(provider, posted);
+  const assertion = soleAssertion(provider, response);
+  const outer = await verifyEnvelopedSignature(response, keys);
+  if (!outer.ok && outer.check !== 'signature-missing') {
+    throw samlResponseInvalid(provider, outer.check, `response: ${outer.detail}`);
+  }
+  const inner = await verifyEnvelopedSignature(assertion, keys);
+  if (!inner.ok) throw samlResponseInvalid(provider, inner.check, `assertion: ${inner.detail}`);
+  responseHeader(provider, response, expect);
+  try {
+    return readAssertion(assertion, { ...expect, issuer: expect.idpEntityId });
+  } catch (error) {
+    if (error instanceof AssertionRefusal)
+      throw samlResponseInvalid(provider, error.check, error.detail);
+    throw error;
+  }
+}

package/src/saml-xml.ts

@@ -0,0 +1,328 @@
+// Single responsibility: a strict, namespace-aware XML reader for the SAML subset — a tree that
+// keeps exactly what exclusive c14n and XML-DSig need (prefixes, in-scope namespaces, comments as
+// nodes) and REFUSES what SAML never needs and attackers always do: a DOCTYPE (entity expansion,
+// XXE), a processing instruction, an unknown entity, an undeclared prefix, a duplicate attribute.
+
+/** The namespace `xml:` is bound to by definition (Namespaces in XML 1.0 §3). */
+export const XML_NS = 'http://www.w3.org/XML/1998/namespace';
+
+export interface XmlAttribute {
+  readonly qname: string;
+  readonly prefix: string | null;
+  readonly local: string;
+  /** `''` for an unprefixed attribute: it is in no namespace. */
+  readonly ns: string;
+  readonly value: string;
+}
+
+export interface XmlText {
+  readonly kind: 'text';
+  readonly value: string;
+}
+
+export interface XmlComment {
+  readonly kind: 'comment';
+  readonly value: string;
+}
+
+export interface XmlElement {
+  readonly kind: 'element';
+  readonly qname: string;
+  readonly prefix: string | null;
+  readonly local: string;
+  readonly ns: string;
+  readonly attributes: readonly XmlAttribute[];
+  /** Every prefix (`''` for the default) in scope here, ancestors' declarations included. */
+  readonly scope: NamespaceScope;
+  readonly children: readonly XmlNode[];
+  readonly parent: XmlElement | null;
+}
+
+export type XmlNode = XmlElement | XmlText | XmlComment;
+
+/** A prefix lookup through the element's own declarations, then its ancestors'. */
+export interface NamespaceScope {
+  get(prefix: string): string | undefined;
+  has(prefix: string): boolean;
+}
+
+/**
+ * Each element keeps only ITS declarations and asks its parent for the rest. A copied map per
+ * declaring element was K declarations × N elements of memory — 5 GB from one 334 KB POST.
+ * Depth is capped at `MAX_DEPTH`, so a lookup walks at most that many links.
+ */
+class ScopeChain implements NamespaceScope {
+  constructor(
+    private readonly own: ReadonlyMap<string, string>,
+    private readonly parent: NamespaceScope | null,
+  ) {}
+  get(prefix: string): string | undefined {
+    return this.own.get(prefix) ?? this.parent?.get(prefix);
+  }
+  has(prefix: string): boolean {
+    return this.get(prefix) !== undefined;
+  }
+}
+
+const NO_SCOPE: NamespaceScope = { get: () => undefined, has: () => false };
+
+export type XmlParse =
+  | { readonly ok: true; readonly root: XmlElement }
+  | { readonly ok: false; readonly reason: string };
+
+/** A SAML response is a few KiB; an IdP metadata file with many certificates, tens. */
+export const MAX_XML_LENGTH = 512 * 1024;
+const MAX_DEPTH = 64;
+/** Namespace declarations per document. SAML uses a handful; every one is lookup work per element. */
+export const MAX_NAMESPACE_DECLARATIONS = 64;
+
+const NAME = /^[A-Za-z_][A-Za-z0-9._-]*(?::[A-Za-z_][A-Za-z0-9._-]*)?/;
+/** A `Map`, so an entity name from the document never reaches `Object.prototype` (`proto-index`). */
+const PREDEFINED: ReadonlyMap<string, string> = new Map([
+  ['lt', '<'],
+  ['gt', '>'],
+  ['amp', '&'],
+  ['quot', '"'],
+  ['apos', "'"],
+]);
+/** XML 1.0 `Char` minus the line breaks and tab, which are handled before this is asked. */
+const isXmlChar = (code: number): boolean =>
+  code === 0x9 ||
+  code === 0xa ||
+  code === 0xd ||
+  (code >= 0x20 && code <= 0xd7ff) ||
+  (code >= 0xe000 && code <= 0xfffd) ||
+  (code >= 0x10000 && code <= 0x10ffff);
+
+class Refusal {
+  constructor(readonly reason: string) {}
+}
+const refuse = (reason: string): never => {
+  throw new Refusal(reason);
+};
+
+/** Entity and character references, decoded; anything else after `&` is refused. */
+function decode(raw: string): string {
+  if (!raw.includes('&')) return raw;
+  return raw.replace(/&([^;&]*);|&/g, (whole, body: string | undefined) => {
+    if (body === undefined) return refuse('a bare & is not a reference');
+    const named = PREDEFINED.get(body);
+    if (named !== undefined) return named;
+    const match = /^#(?:x([0-9A-Fa-f]{1,6})|([0-9]{1,7}))$/.exec(body);
+    if (match === null)
+      return refuse(`${whole.length > 12 ? 'an' : whole} entity is not one of the five predefined`);
+    const code = match[1] === undefined ? Number(match[2]) : Number.parseInt(match[1], 16);
+    if (!isXmlChar(code)) return refuse('a character reference names no XML character');
+    return String.fromCodePoint(code);
+  });
+}
+
+function assertChars(text: string): void {
+  for (const char of text) {
+    if (!isXmlChar(char.codePointAt(0) ?? 0)) refuse('the document carries a non-XML character');
+  }
+}
+
+interface RawAttribute {
+  readonly qname: string;
+  readonly value: string;
+}
+
+class Reader {
+  at = 0;
+  /** Namespace declarations read so far, across the whole document. */
+  declarations = 0;
+  constructor(readonly text: string) {}
+
+  startsWith(marker: string): boolean {
+    return this.text.startsWith(marker, this.at);
+  }
+
+  skipSpace(): void {
+    while (/[ \t\n]/.test(this.text[this.at] ?? '')) this.at += 1;
+  }
+
+  name(): string {
+    const match = NAME.exec(this.text.slice(this.at, this.at + 256));
+    if (match === null) return refuse('a name was expected');
+    this.at += match[0].length;
+    return match[0];
+  }
+
+  until(marker: string, what: string): string {
+    const end = this.text.indexOf(marker, this.at);
+    if (end < 0) return refuse(`an unterminated ${what}`);
+    const body = this.text.slice(this.at, end);
+    this.at = end + marker.length;
+    return body;
+  }
+}
+
+function split(qname: string): { prefix: string | null; local: string } {
+  const colon = qname.indexOf(':');
+  return colon < 0
+    ? { prefix: null, local: qname }
+    : { prefix: qname.slice(0, colon), local: qname.slice(colon + 1) };
+}
+
+function readAttributes(reader: Reader): RawAttribute[] {
+  const out: RawAttribute[] = [];
+  const names = new Set<string>();
+  for (;;) {
+    const before = reader.at;
+    reader.skipSpace();
+    if (reader.startsWith('>') || reader.startsWith('/>')) return out;
+    if (reader.at === before) refuse('attributes must be separated by white space');
+    const qname = reader.name();
+    // By qname, before any namespace resolves: `xmlns:p` twice would otherwise be last-one-wins.
+    if (names.has(qname)) refuse('an element carries one attribute twice');
+    names.add(qname);
+    reader.skipSpace();
+    if (!reader.startsWith('=')) refuse('an attribute has no value');
+    reader.at += 1;
+    reader.skipSpace();
+    const quote = reader.text[reader.at];
+    if (quote !== '"' && quote !== "'") return refuse('an attribute value is not quoted');
+    reader.at += 1;
+    const raw = reader.until(quote, 'attribute value');
+    if (raw.includes('<')) refuse('an attribute value carries <');
+    // Attribute-value normalisation (XML 1.0 §3.3.3): a literal tab or line break is a space;
+    // one written as a character reference is not, which is why this runs before `decode`.
+    out.push({ qname, value: decode(raw.replace(/[\t\n]/g, ' ')) });
+  }
+}
+
+function scopeFor(reader: Reader, raw: readonly RawAttribute[], inherited: NamespaceScope) {
+  let own: Map<string, string> | null = null;
+  for (const { qname, value } of raw) {
+    if (qname !== 'xmlns' && !qname.startsWith('xmlns:')) continue;
+    const prefix = qname === 'xmlns' ? '' : qname.slice(6);
+    if (prefix === 'xml' || prefix === 'xmlns') refuse('the xml and xmlns prefixes are reserved');
+    if (prefix !== '' && value === '') refuse('a prefix may not be undeclared');
+    reader.declarations += 1;
+    if (reader.declarations > MAX_NAMESPACE_DECLARATIONS) {
+      refuse(`the document carries more than ${MAX_NAMESPACE_DECLARATIONS} namespace declarations`);
+    }
+    own ??= new Map();
+    own.set(prefix, value);
+  }
+  // An element that declares nothing shares its parent's scope object: no allocation at all.
+  return own === null ? inherited : new ScopeChain(own, inherited);
+}
+
+function resolve(prefix: string | null, scope: NamespaceScope, attr: boolean): string {
+  if (prefix === null) return attr ? '' : (scope.get('') ?? '');
+  if (prefix === 'xml') return XML_NS;
+  const ns = scope.get(prefix);
+  return ns === undefined ? refuse('a prefix is used without a declaration') : ns;
+}
+
+function element(reader: Reader, parent: XmlElement | null, depth: number): XmlElement {
+  if (depth > MAX_DEPTH) refuse('the document nests deeper than any SAML message');
+  reader.at += 1; // '<'
+  const qname = reader.name();
+  const raw = readAttributes(reader);
+  const scope = scopeFor(reader, raw, parent?.scope ?? NO_SCOPE);
+  const attributes: XmlAttribute[] = [];
+  const seen = new Set<string>();
+  for (const { qname: name, value } of raw) {
+    if (name === 'xmlns' || name.startsWith('xmlns:')) continue;
+    const { prefix, local } = split(name);
+    const ns = resolve(prefix, scope, true);
+    if (seen.has(`${ns} ${local}`)) refuse('an element carries one attribute twice');
+    seen.add(`${ns} ${local}`);
+    attributes.push({ qname: name, prefix, local, ns, value });
+  }
+  const { prefix, local } = split(qname);
+  const children: XmlNode[] = [];
+  const node: XmlElement = {
+    kind: 'element',
+    qname,
+    prefix,
+    local,
+    ns: resolve(prefix, scope, false),
+    attributes,
+    scope,
+    children,
+    parent,
+  };
+  if (reader.startsWith('/>')) {
+    reader.at += 2;
+    return node;
+  }
+  reader.at += 1; // '>'
+  content(reader, node, children, depth);
+  return node;
+}
+
+function pushText(children: XmlNode[], value: string): void {
+  if (value === '') return;
+  const last = children.at(-1);
+  if (last?.kind === 'text')
+    children[children.length - 1] = { kind: 'text', value: last.value + value };
+  else children.push({ kind: 'text', value });
+}
+
+function content(reader: Reader, node: XmlElement, children: XmlNode[], depth: number): void {
+  for (;;) {
+    const lt = reader.text.indexOf('<', reader.at);
+    if (lt < 0) refuse('an element is never closed');
+    const text = reader.text.slice(reader.at, lt);
+    if (text.includes(']]>')) refuse('text carries ]]>');
+    pushText(children, decode(text));
+    reader.at = lt;
+    if (reader.startsWith('</')) {
+      reader.at += 2;
+      if (reader.name() !== node.qname) refuse('an end tag does not match its start tag');
+      reader.skipSpace();
+      if (!reader.startsWith('>')) refuse('an end tag is not closed');
+      reader.at += 1;
+      return;
+    }
+    if (reader.startsWith('<!--')) {
+      reader.at += 4;
+      const body = reader.until('-->', 'comment');
+      if (body.includes('--') || body.endsWith('-')) refuse('a comment carries --');
+      children.push({ kind: 'comment', value: body });
+    } else if (reader.startsWith('<![CDATA[')) {
+      reader.at += 9;
+      pushText(children, reader.until(']]>', 'CDATA section'));
+    } else if (reader.startsWith('<!') || reader.startsWith('<?')) {
+      refuse('a DOCTYPE, entity declaration or processing instruction is refused');
+    } else {
+      children.push(element(reader, node, depth + 1));
+    }
+  }
+}
+
+/** Comments and white space are all that may stand outside the root. */
+function misc(reader: Reader): void {
+  for (;;) {
+    reader.skipSpace();
+    if (!reader.startsWith('<!--')) return;
+    reader.at += 4;
+    reader.until('-->', 'comment');
+  }
+}
+
+export function parseXml(input: string): XmlParse {
+  if (input.length > MAX_XML_LENGTH) return { ok: false, reason: 'the document is too large' };
+  try {
+    // Line-end normalisation (XML 1.0 §2.11) before anything else reads a character.
+    const text = input.replace(/^/, '').replace(/\r\n?/g, '\n');
+    assertChars(text);
+    const reader = new Reader(text);
+    if (/^<\?xml[ \t\n]/.test(text)) reader.until('?>', 'XML declaration');
+    misc(reader);
+    if (!reader.startsWith('<') || reader.startsWith('<!') || reader.startsWith('<?')) {
+      refuse('the document has no root element, or a DOCTYPE or processing instruction before it');
+    }
+    const root = element(reader, null, 0);
+    misc(reader);
+    if (reader.at !== text.length) refuse('content follows the root element');
+    return { ok: true, root };
+  } catch (error) {
+    if (error instanceof Refusal) return { ok: false, reason: error.reason };
+    throw error;
+  }
+}