@_mustachio/openauth 0.11.0 → 0.13.0

package/src/methods/saml-sp/metadata.ts

@@ -0,0 +1,215 @@
+/**
+ * SP metadata XML — the outbound half of metadata exchange
+ * (`parseSamlIdpMetadata` is the inbound half).
+ *
+ * Served anonymously at `GET /m/<methodId>/metadata` via the method's
+ * `publicRoutes` allowlist (no flow cookie). An enterprise IdP admin
+ * imports this document to register us as an SP.
+ *
+ * **Conformance invariant:** the `entityID` and ACS `Location` are
+ * derived from the *same* inputs the live AuthnRequest / ACS path uses
+ * (`resolveSpEntityId(config, issuerUrl, tenantId, methodId)` and
+ * `ctx.dispatch.callbackUrl`). The metadata therefore describes exactly
+ * what the runtime accepts — never an independently re-specified value
+ * that could drift. `metadata.test.ts` asserts this equality against
+ * `buildAuthnRequestRedirect` so drift fails CI.
+ *
+ * `KeyDescriptor` is emitted only when we actually sign AuthnRequests
+ * (advertising a cert we cannot use would be the bug);
+ * `SingleLogoutService` only when an IdP SLO endpoint is configured
+ * and the `/sls` route is therefore served (advertising an endpoint we
+ * do not serve would break interop). `AuthnRequestsSigned` and
+ * `WantAssertionsSigned` are both read from config, so they state
+ * actual runtime behaviour rather than a hardcoded assumption.
+ */
+import { authError } from "../../types/error"
+import type { MethodContext, MethodResult } from "../../types/method"
+
+import { resolveSpEntityId } from "./saml-instance"
+import type {
+  SamlNameIdFormat,
+  SamlSpConfig,
+  SamlSpProperties,
+  SamlSpState,
+} from "./types"
+
+const NAME_ID_FORMAT_URN: Record<SamlNameIdFormat, string> = {
+  persistent: "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
+  transient: "urn:oasis:names:tc:SAML:2.0:nameid-format:transient",
+  emailAddress: "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
+  unspecified: "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified",
+}
+
+const HTTP_POST = "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
+const HTTP_REDIRECT = "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
+
+/** Minimal XML attribute/text escaping for URL-shaped values. */
+function xmlEscape(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+}
+
+export type SpMetadataInput = {
+  spEntityId: string
+  acsUrl: string
+  /**
+   * The SP's own Single Logout Service URL (`/m/<methodId>/sls`).
+   * Present ⇒ front-channel SLO is served, so the metadata advertises
+   * `SingleLogoutService` for both bindings we accept. Same
+   * advertise-only-what-we-serve invariant as the ACS / signing cert.
+   */
+  slsUrl?: string
+  nameIdFormat?: SamlNameIdFormat
+  /**
+   * SP signing cert (PEM). Present ⇒ we sign AuthnRequests, so the
+   * metadata advertises `AuthnRequestsSigned="true"` and a
+   * `KeyDescriptor use="signing"`. Keeping this in lockstep with the
+   * runtime (the same `config.signingKey.certPem` that actually signs)
+   * is the same anti-drift invariant as the entityID/ACS.
+   */
+  signingCertPem?: string
+  /**
+   * SP encryption cert (PEM). Present ⇒ the connection accepts
+   * encrypted assertions, so the metadata advertises a
+   * `KeyDescriptor use="encryption"` (the cert the IdP encrypts to —
+   * `config.decryptionKey.certPem`). Same anti-drift / advertise-only-
+   * what-we-serve invariant as the signing cert.
+   */
+  encryptionCertPem?: string
+  /**
+   * Whether we actually require a signed `<saml:Assertion>`
+   * (`config.requireSignedAssertion`, default `true`). Published as
+   * `WantAssertionsSigned` — same advertise-only-what-we-serve
+   * invariant as the certs: a connection relying on a signed
+   * `<Response>` instead must not claim otherwise in its metadata.
+   */
+  wantAssertionsSigned?: boolean
+}
+
+/** PEM cert body → bare base64 (SAML metadata X509Certificate form). */
+function certBody(pem: string): string {
+  return pem
+    .replace(/-----BEGIN CERTIFICATE-----/g, "")
+    .replace(/-----END CERTIFICATE-----/g, "")
+    .replace(/\s+/g, "")
+}
+
+/**
+ * Pure SP metadata builder. Mirrors `parseSamlIdpMetadata`'s purity so
+ * it is trivially unit-testable and reusable.
+ */
+export function buildSpMetadataXml(input: SpMetadataInput): string {
+  const entityId = xmlEscape(input.spEntityId)
+  const acs = xmlEscape(input.acsUrl)
+  const signed = input.signingCertPem !== undefined
+  const wantAssertionsSigned = input.wantAssertionsSigned ?? true
+  const nameIdLine =
+    input.nameIdFormat !== undefined
+      ? `\n    <md:NameIDFormat>${NAME_ID_FORMAT_URN[input.nameIdFormat]}</md:NameIDFormat>`
+      : ""
+  const x509 = (cert: string) =>
+    `<ds:KeyInfo><ds:X509Data><ds:X509Certificate>` +
+    certBody(cert) +
+    `</ds:X509Certificate></ds:X509Data></ds:KeyInfo>`
+  const keyDescriptor =
+    (signed
+      ? `\n    <md:KeyDescriptor use="signing">` +
+        x509(input.signingCertPem as string) +
+        `</md:KeyDescriptor>`
+      : "") +
+    (input.encryptionCertPem !== undefined
+      ? `\n    <md:KeyDescriptor use="encryption">` +
+        x509(input.encryptionCertPem) +
+        `</md:KeyDescriptor>`
+      : "")
+  // Schema order: KeyDescriptor → SingleLogoutService → NameIDFormat →
+  // AssertionConsumerService. Advertise both bindings we accept at /sls.
+  const sls =
+    input.slsUrl !== undefined
+      ? `\n    <md:SingleLogoutService ` +
+        `Binding="${HTTP_REDIRECT}" Location="${xmlEscape(input.slsUrl)}"/>` +
+        `\n    <md:SingleLogoutService ` +
+        `Binding="${HTTP_POST}" Location="${xmlEscape(input.slsUrl)}"/>`
+      : ""
+
+  return (
+    `<?xml version="1.0" encoding="UTF-8"?>\n` +
+    `<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" ` +
+    `xmlns:ds="http://www.w3.org/2000/09/xmldsig#" ` +
+    `entityID="${entityId}">\n` +
+    `  <md:SPSSODescriptor AuthnRequestsSigned="${signed}" ` +
+    `WantAssertionsSigned="${wantAssertionsSigned}" ` +
+    `protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">` +
+    keyDescriptor +
+    sls +
+    nameIdLine +
+    `\n    <md:AssertionConsumerService ` +
+    `Binding="${HTTP_POST}" Location="${acs}" index="0" isDefault="true"/>` +
+    `\n  </md:SPSSODescriptor>\n` +
+    `</md:EntityDescriptor>\n`
+  )
+}
+
+/**
+ * `GET /metadata` route handler. Anonymous (declared in the method's
+ * `publicRoutes`): `ctx.flow` / `ctx.methodState` are null; everything
+ * comes from `ctx.tenant` + `ctx.dispatch` + captured config.
+ */
+export async function buildSpMetadata(
+  ctx: MethodContext<SamlSpState>,
+  methodId: string,
+  config: SamlSpConfig,
+): Promise<MethodResult<SamlSpProperties, SamlSpState>> {
+  if (!ctx.dispatch) {
+    return {
+      kind: "error",
+      error: authError.internalError(
+        "saml-sp: metadata route dispatched without issuer context " +
+          "(ctx.dispatch is null)",
+      ),
+    }
+  }
+
+  const spEntityId = resolveSpEntityId(
+    config,
+    ctx.dispatch.issuerUrl,
+    ctx.tenant.id,
+    methodId,
+  )
+  // SP SLS URL — same host as the ACS callback, at the public method
+  // mount `/m/<methodId>/sls`. Only advertised when SLO is actually
+  // served (idp.sloUrl set ⇒ /sls is in publicRoutes). Derived from the
+  // same dispatch input as the ACS so it cannot drift.
+  const cb = new URL(ctx.dispatch.callbackUrl)
+  const slsUrl = `${cb.protocol}//${cb.host}/m/${methodId}/sls`
+  const xml = buildSpMetadataXml({
+    spEntityId,
+    acsUrl: ctx.dispatch.callbackUrl,
+    ...(config.idp.sloUrl ? { slsUrl } : {}),
+    ...(config.idp.nameIdFormat !== undefined
+      ? { nameIdFormat: config.idp.nameIdFormat }
+      : {}),
+    wantAssertionsSigned: config.requireSignedAssertion ?? true,
+    // Truthful: advertise signing iff we actually sign AuthnRequests.
+    ...(config.signAuthnRequest && config.signingKey
+      ? { signingCertPem: config.signingKey.certPem }
+      : {}),
+    // Truthful: advertise an encryption cert iff we accept (and can
+    // decrypt) encrypted assertions.
+    ...(config.allowEncryptedAssertions && config.decryptionKey
+      ? { encryptionCertPem: config.decryptionKey.certPem }
+      : {}),
+  })
+
+  return {
+    kind: "challenge",
+    response: new Response(xml, {
+      status: 200,
+      headers: { "content-type": "application/samlmetadata+xml" },
+    }),
+    cache: { sMaxAge: 300 },
+  }
+}

package/src/methods/saml-sp/method.ts

@@ -0,0 +1,65 @@
+/**
+ * `buildSamlSpMethod` — assembles the `AuthMethod` for a SAML SP
+ * instance. Mirrors `buildOauth2Method`: data + handler functions, no
+ * framework imports beyond `types/`.
+ *
+ * Routes:
+ *   - `GET /authorize`  → SP-initiated AuthnRequest redirect (implemented).
+ *   - `GET /callback`   → ACS verification gauntlet (next increment).
+ *
+ * The framework's universal callback (`/cb/<methodId>`, both GET and
+ * POST) always dispatches the `"GET /callback"` route key, so the ACS
+ * lives there rather than at a bespoke `/acs` sub-path.
+ */
+import type { AuthMethod, MethodContext } from "../../types/method"
+
+import { consumeAssertion } from "./acs"
+import { buildAuthnRequestRedirect } from "./authnrequest"
+import { buildSpMetadata } from "./metadata"
+import { consumeSls } from "./sls"
+import { initiateSpLogout } from "./slo-initiate"
+import type { SamlSpConfig, SamlSpProperties, SamlSpState } from "./types"
+
+export function buildSamlSpMethod(
+  id: string,
+  kind: string,
+  config: SamlSpConfig,
+): AuthMethod<SamlSpProperties, SamlSpState> {
+  return {
+    id,
+    kind,
+    type: "custom",
+    routes: {
+      "GET /authorize": (ctx: MethodContext<SamlSpState>) =>
+        buildAuthnRequestRedirect(ctx, id, config),
+      "GET /callback": (ctx: MethodContext<SamlSpState>) =>
+        consumeAssertion(ctx, id, config),
+      "GET /metadata": (ctx: MethodContext<SamlSpState>) =>
+        buildSpMetadata(ctx, id, config),
+      // Front-channel Single Logout. `/sls` receives IdP LogoutRequest
+      // / LogoutResponse (both bindings; verified by XML-DSig, not a
+      // flow cookie — see sls.ts). `POST /logout` is the host-driven
+      // SP-initiated send (see slo-initiate.ts).
+      "GET /sls": (ctx: MethodContext<SamlSpState>) =>
+        consumeSls(ctx, id, config),
+      "POST /sls": (ctx: MethodContext<SamlSpState>) =>
+        consumeSls(ctx, id, config),
+      "POST /logout": (ctx: MethodContext<SamlSpState>) =>
+        initiateSpLogout(ctx, id, config),
+    },
+    // Anonymous, no flow cookie. `/metadata` always; the SLO routes
+    // (`/sls` receive + `/logout` send) only when an IdP SLO endpoint
+    // is configured — advertising/serving an SLO surface we cannot
+    // complete a round-trip on would break interop (same conservative
+    // gating as `unsolicitedCallback` ⇐ `idpInitiated`).
+    publicRoutes: [
+      "GET /metadata",
+      ...(config.idp.sloUrl
+        ? (["GET /sls", "POST /sls", "POST /logout"] as const)
+        : ([] as const)),
+    ],
+    // IdP-initiated SSO: only when this instance is configured for it.
+    // Absent ⇒ unsolicited Responses stay invalid_request.
+    unsolicitedCallback: config.idpInitiated !== undefined,
+  }
+}

package/src/methods/saml-sp/parse-idp-metadata.ts

@@ -0,0 +1,158 @@
+/**
+ * `parseSamlIdpMetadata` — turn an IdP's SAML 2.0 metadata XML into the
+ * `SamlIdpConfig` shape a host stores per method instance.
+ *
+ * This is a **pure** helper exposed so a host console can offer "paste
+ * the IdP metadata XML / URL" instead of making operators hand-copy
+ * entityID, SSO URL, and signing certs. It does not import node-saml —
+ * metadata parsing needs no signature verification (the document is
+ * fetched from a trusted admin, and every assertion is independently
+ * verified at the ACS regardless of what the metadata claimed).
+ *
+ * Namespace-agnostic: elements are matched by local name so prefixes
+ * (`md:`, `ds:`, none) don't matter. Returns `Result` rather than
+ * throwing, matching the library's domain convention.
+ */
+import { authError } from "../../types/error"
+import type { Result } from "../../types/result"
+import { err, ok } from "../../types/result"
+
+// CJS interop per the SAML house-style note.
+import xmldom from "@xmldom/xmldom"
+
+import type { SamlIdpConfig, SamlNameIdFormat } from "./types"
+
+const { DOMParser } = xmldom
+
+const HTTP_REDIRECT = "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
+const HTTP_POST = "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
+
+const NAME_ID_FORMAT_BY_URN: Record<string, SamlNameIdFormat> = {
+  "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent": "persistent",
+  "urn:oasis:names:tc:SAML:2.0:nameid-format:transient": "transient",
+  "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress": "emailAddress",
+  "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified": "unspecified",
+}
+
+function els(root: Document | Element, localName: string): Element[] {
+  const list = root.getElementsByTagNameNS("*", localName)
+  const out: Element[] = []
+  for (let i = 0; i < list.length; i++) {
+    const n = list[i]
+    if (n) out.push(n)
+  }
+  return out
+}
+
+/** Pick an endpoint by binding preference (Redirect → POST → first). */
+function pickEndpoint(endpoints: Element[]): string | undefined {
+  if (endpoints.length === 0) return undefined
+  const byBinding = (b: string) =>
+    endpoints.find((e) => e.getAttribute("Binding") === b)
+  const chosen =
+    byBinding(HTTP_REDIRECT) ?? byBinding(HTTP_POST) ?? endpoints[0]
+  const loc = chosen?.getAttribute("Location")
+  return loc && loc.length > 0 ? loc : undefined
+}
+
+/** Normalise a base64 cert body into a PEM block (64-col lines). */
+function toPem(rawX509: string): string {
+  const b64 = rawX509.replace(/\s+/g, "")
+  const lines = b64.match(/.{1,64}/g) ?? [b64]
+  return (
+    "-----BEGIN CERTIFICATE-----\n" +
+    lines.join("\n") +
+    "\n-----END CERTIFICATE-----"
+  )
+}
+
+export function parseSamlIdpMetadata(xml: string): Result<SamlIdpConfig> {
+  if (typeof xml !== "string" || xml.trim().length === 0) {
+    return err(authError.invalidRequest("metadata XML is empty"))
+  }
+
+  let doc: Document
+  try {
+    doc = new DOMParser().parseFromString(
+      xml,
+      "text/xml",
+    ) as unknown as Document
+  } catch (e) {
+    return err(
+      authError.invalidRequest(
+        `metadata XML is not well-formed: ${
+          e instanceof Error ? e.message : String(e)
+        }`,
+      ),
+    )
+  }
+  if (!doc?.documentElement) {
+    return err(authError.invalidRequest("metadata XML has no root element"))
+  }
+
+  const entityDescriptor = els(doc, "EntityDescriptor")[0]
+  if (!entityDescriptor) {
+    return err(authError.invalidRequest("metadata has no <EntityDescriptor>"))
+  }
+  const entityId = entityDescriptor.getAttribute("entityID")
+  if (!entityId) {
+    return err(authError.invalidRequest("EntityDescriptor has no entityID"))
+  }
+
+  const idp = els(entityDescriptor, "IDPSSODescriptor")[0]
+  if (!idp) {
+    return err(
+      authError.invalidRequest(
+        "not an IdP metadata document (no <IDPSSODescriptor>) — this looks " +
+          "like SP metadata",
+      ),
+    )
+  }
+
+  const ssoUrl = pickEndpoint(els(idp, "SingleSignOnService"))
+  if (!ssoUrl) {
+    return err(
+      authError.invalidRequest(
+        "IDPSSODescriptor has no usable <SingleSignOnService> Location",
+      ),
+    )
+  }
+  const sloUrl = pickEndpoint(els(idp, "SingleLogoutService"))
+
+  let nameIdFormat: SamlNameIdFormat | undefined
+  for (const f of els(idp, "NameIDFormat")) {
+    const mapped = NAME_ID_FORMAT_BY_URN[(f.textContent ?? "").trim()]
+    if (mapped) {
+      nameIdFormat = mapped
+      break
+    }
+  }
+
+  // Signing certs: a KeyDescriptor with use="signing", or with no `use`
+  // (per SAML metadata spec an absent `use` means the key is valid for
+  // both signing and encryption).
+  const signingCerts: { pem: string }[] = []
+  for (const kd of els(idp, "KeyDescriptor")) {
+    const use = kd.getAttribute("use")
+    if (use && use !== "signing") continue
+    for (const cert of els(kd, "X509Certificate")) {
+      const body = (cert.textContent ?? "").trim()
+      if (body.length > 0) signingCerts.push({ pem: toPem(body) })
+    }
+  }
+  if (signingCerts.length === 0) {
+    return err(
+      authError.invalidRequest(
+        "IDPSSODescriptor has no signing <X509Certificate>",
+      ),
+    )
+  }
+
+  return ok({
+    entityId,
+    ssoUrl,
+    ...(sloUrl !== undefined ? { sloUrl } : {}),
+    ...(nameIdFormat !== undefined ? { nameIdFormat } : {}),
+    signingCerts,
+  })
+}

package/src/methods/saml-sp/saml-instance.ts

@@ -0,0 +1,210 @@
+/**
+ * Construct a `@node-saml/node-saml` `SAML` instance from validated
+ * `SamlSpConfig` plus the per-request binding context (SP entityID +
+ * ACS URL, both derived at dispatch time per SAML-AD5).
+ *
+ * CJS interop: node-saml is CommonJS-only. Per the SAML house-style
+ * note, default-import then destructure rather than relying on the
+ * named-export heuristic.
+ */
+import nodeSaml from "@node-saml/node-saml"
+
+import type { MethodScratch } from "../../types/method"
+
+import { methodScratchCacheProvider } from "./cache-provider"
+import { selectActiveCertPems } from "./cert-rotation"
+import type { SamlNameIdFormat, SamlSpConfig } from "./types"
+
+const { SAML, ValidateInResponseTo } = nodeSaml
+type SamlInstance = InstanceType<typeof SAML>
+
+/** Standard SAML 2.0 NameID format URNs. */
+export const NAME_ID_FORMAT_URN: Record<SamlNameIdFormat, string> = {
+  persistent: "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
+  transient: "urn:oasis:names:tc:SAML:2.0:nameid-format:transient",
+  emailAddress: "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
+  unspecified: "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified",
+}
+
+/**
+ * Outstanding-request-id cache TTL. Must comfortably outlast the
+ * slowest realistic IdP login screen; the flow record expires on its
+ * own shorter clock, so this is just the upper bound on how long an
+ * `InResponseTo` stays accepted.
+ */
+const IN_RESPONSE_TO_TTL_MS = 60 * 60 * 1000
+
+export type SamlBindingContext = {
+  /** SP entityID — `<issuerUrl>/<tenantId>/<methodId>` (SAML-AD5). */
+  spEntityId: string
+  /** ACS URL — the framework's `/cb/<methodId>` universal callback. */
+  acsUrl: string
+  /** Per-request scratch backing the `InResponseTo` cache. */
+  scratch: MethodScratch
+  /**
+   * IdP-initiated mode. An unsolicited Response has no `InResponseTo`
+   * (there was no AuthnRequest), so `validateInResponseTo` must be
+   * `ifPresent` rather than `always` — otherwise node-saml throws
+   * "InResponseTo is missing". Signature / Issuer / Audience /
+   * Conditions are still fully enforced; assertion-ID replay dedup is
+   * layered on top by the caller (node-saml does not dedup unsolicited
+   * assertion IDs). Default `false` ⇒ SP-initiated, `always`
+   * (unchanged).
+   */
+  idpInitiated?: boolean
+  /**
+   * Logout-binding instance (the `/sls` + `/logout` paths). node-saml's
+   * `InResponseTo` machinery only reads the attribute off a `Response`
+   * root, never a `LogoutResponse`, so with the default `always` it
+   * throws "InResponseTo is missing" on every inbound `LogoutResponse`.
+   * Front-channel logout correlation is out of that scope — we
+   * replay-dedup the inbound `LogoutRequest @ID` via `methodScratch`
+   * instead — so logout instances use `never`. Overrides `idpInitiated`.
+   */
+  logout?: boolean
+  /**
+   * Per-connection SP signing material (SAML-AD: O3 — decoupled from
+   * the OIDC `KeyStore`; the IdP pins this cert, rotation is an
+   * IdP-coordination event). Present ⇒ node-saml signs the outbound
+   * `AuthnRequest` (HTTP-Redirect binding) **and** outbound logout
+   * messages (`LogoutRequest` / `LogoutResponse`) with it.
+   */
+  signing?: {
+    privateKeyPem: string
+    certPem: string
+  }
+  /**
+   * IdP Single Logout endpoint (`SamlSpConfig.idp.sloUrl`). Destination
+   * for SP-emitted `LogoutResponse` (front-channel SLO, Phase 3) and
+   * SP-initiated `LogoutRequest`. Only needed on the `/sls` path; the
+   * SSO paths leave it unset.
+   */
+  logoutUrl?: string
+  /**
+   * SP decryption private key PEM (`SamlSpConfig.decryptionKey`),
+   * passed through to node-saml's `decryptionPvk`. Present ⇒ node-saml
+   * decrypts `<saml:EncryptedAssertion>` (the decrypted assertion's
+   * XML-DSig is still fully enforced). Set only when the connection
+   * opted into `allowEncryptedAssertions`; absent ⇒ an encrypted
+   * assertion is rejected.
+   */
+  decryptionPvk?: string
+}
+
+/**
+ * Derive the per-instance SP entityID. Stable across deploys for a
+ * given `(issuerUrl, tenantId, methodId)` triple so IdP-side trust
+ * config doesn't churn.
+ */
+export function deriveSpEntityId(
+  issuerUrl: string,
+  tenantId: string,
+  methodId: string,
+): string {
+  const base = issuerUrl.endsWith("/") ? issuerUrl.slice(0, -1) : issuerUrl
+  return `${base}/${tenantId}/${methodId}`
+}
+
+/**
+ * The SP entityID this connection actually presents — the configured
+ * override if the operator set one (to adopt an entityID that already
+ * exists at the IdP), else the derived default.
+ *
+ * **Every** consumer must go through this one function: the
+ * `AuthnRequest` issuer, `AudienceRestriction` validation, SP metadata,
+ * and logout messages all have to agree, or the IdP rejects us. That
+ * shared-resolution property is what the metadata anti-drift test
+ * guards.
+ */
+export function resolveSpEntityId(
+  config: SamlSpConfig,
+  issuerUrl: string,
+  tenantId: string,
+  methodId: string,
+): string {
+  return config.spEntityId ?? deriveSpEntityId(issuerUrl, tenantId, methodId)
+}
+
+export function buildSamlInstance(
+  config: SamlSpConfig,
+  binding: SamlBindingContext,
+  nowMs: number,
+): SamlInstance {
+  const activeCerts = selectActiveCertPems(config.idp.signingCerts, nowMs)
+  if (activeCerts.length === 0) {
+    throw new Error(
+      "saml-sp: no IdP signing certificate is currently within its " +
+        "validity window — check SamlSpConfig.idp.signingCerts notBefore/notAfter.",
+    )
+  }
+
+  const identifierFormat =
+    config.idp.nameIdFormat !== undefined
+      ? NAME_ID_FORMAT_URN[config.idp.nameIdFormat]
+      : null
+
+  return new SAML({
+    // MandatorySamlOptions
+    idpCert: activeCerts,
+    issuer: binding.spEntityId,
+    callbackUrl: binding.acsUrl,
+    // IdP endpoints
+    entryPoint: config.idp.ssoUrl,
+    idpIssuer: config.idp.entityId,
+    audience: binding.spEntityId,
+    identifierFormat,
+    // Security posture. A signed *assertion* is mandatory (identity +
+    // conditions + audience all live in the signed bytes); requiring
+    // the outer Response to also be signed is stricter than the
+    // Okta/Entra default and would reject the majority of real IdPs,
+    // so it is not required here. SP-initiated requires an outstanding
+    // InResponseTo (`always`); IdP-initiated is unsolicited so it must
+    // be `ifPresent` — the caller layers explicit assertion-ID replay
+    // dedup on top for that mode.
+    validateInResponseTo: binding.logout
+      ? ValidateInResponseTo.never
+      : binding.idpInitiated
+        ? ValidateInResponseTo.ifPresent
+        : ValidateInResponseTo.always,
+    wantAssertionsSigned: config.requireSignedAssertion ?? true,
+    wantAuthnResponseSigned: config.requireSignedResponse ?? false,
+    acceptedClockSkewMs: (config.clockSkewSeconds ?? 60) * 1000,
+    // ForceAuthn — a request, never a guarantee. SAML gives the IdP no
+    // obligation to honour it and the Response carries no proof either
+    // way, so nothing downstream may treat it as freshness evidence.
+    forceAuthn: config.forceAuthn ?? false,
+    // RequestedAuthnContext. node-saml's own defaults are
+    // `disableRequestedAuthnContext: false` +
+    // `authnContext: [PasswordProtectedTransport]` +
+    // `racComparison: "exact"`, i.e. every AuthnRequest would demand
+    // exactly password-over-TLS. An IdP with an MFA sign-on policy can
+    // answer that with `NoAuthnContext` instead of a login, so we
+    // invert the default: send no RequestedAuthnContext unless the
+    // operator explicitly configured the class refs their IdP honours.
+    ...(config.requestedAuthnContext
+      ? {
+          disableRequestedAuthnContext: false,
+          authnContext: [...config.requestedAuthnContext.classRefs],
+          racComparison: config.requestedAuthnContext.comparison ?? "exact",
+        }
+      : { disableRequestedAuthnContext: true }),
+    cacheProvider: methodScratchCacheProvider(
+      binding.scratch,
+      IN_RESPONSE_TO_TTL_MS,
+    ),
+    // O3: per-connection SP signing key (opt-in). node-saml signs the
+    // HTTP-Redirect AuthnRequest / logout messages with this PEM keypair.
+    ...(binding.signing
+      ? {
+          privateKey: binding.signing.privateKeyPem,
+          publicCert: binding.signing.certPem,
+          signatureAlgorithm: "sha256" as const,
+        }
+      : {}),
+    // SP-emitted LogoutResponse / LogoutRequest destination (the IdP's
+    // SLO endpoint). node-saml's logout URL builder reads `logoutUrl`.
+    ...(binding.logoutUrl ? { logoutUrl: binding.logoutUrl } : {}),
+    // Encrypted-assertion decryption (opt-in per connection).
+    ...(binding.decryptionPvk ? { decryptionPvk: binding.decryptionPvk } : {}),
+  })
+}