@_mustachio/openauth 0.10.0 → 0.12.0

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

@@ -0,0 +1,399 @@
+/**
+ * Assertion Consumer Service — the inbound, security-critical half.
+ *
+ * Mounted at the `"GET /callback"` route key (the framework's
+ * universal `/cb/<methodId>` callback, GET+POST). By the time this
+ * runs, `handleCallback` has already MAC-verified the state envelope
+ * (carried as `RelayState`) and consumed the flow; `ctx.flow` is the
+ * consumed record and `ctx.methodState` carries the SP entityID + ACS
+ * URL we committed to at AuthnRequest time.
+ *
+ * The cryptographic gauntlet (XML-DSig verification on signed
+ * references only, XSW/XXE resistance, issuer/audience,
+ * NotBefore/NotOnOrAfter, InResponseTo single-use) is delegated to
+ * `@node-saml/node-saml`'s `validatePostResponseAsync` — the
+ * CVE-2025-54369/54419-hardened path (SAML-AD1). We do not
+ * reimplement XML-DSig. Any verification failure surfaces as a thrown
+ * error which we map to a controlled `denied`; only infrastructure /
+ * misconfiguration faults become `error`.
+ *
+ * `SubjectConfirmationData/@Recipient` (gauntlet item 6) is **not**
+ * enforced by node-saml, so it is checked here explicitly against the
+ * signed assertion — see `checkRecipient`.
+ *
+ * Two modes, discriminated by `ctx.flow`:
+ *
+ *   - **SP-initiated** (`ctx.flow` set): `handleCallback` MAC-verified
+ *     the state envelope and consumed the flow; binding (SP entityID +
+ *     ACS) comes from `ctx.methodState` committed at AuthnRequest time.
+ *     `InResponseTo` is single-use (`always` + the scratch cache), so a
+ *     replayed Response fails on its already-consumed request id.
+ *   - **IdP-initiated** (`ctx.flow === null`): an unsolicited Response,
+ *     no AuthnRequest, no state envelope, no flow. Allowed only when
+ *     the instance configured `idpInitiated` (the framework gates this
+ *     via `AuthMethod.unsolicitedCallback`). Binding is *derived* from
+ *     `ctx.dispatch` (issuer/ACS — same derivation as AuthnRequest /
+ *     metadata, so no drift). `InResponseTo` is `ifPresent` (none
+ *     exists), so single-use no longer covers replay — we add explicit
+ *     **assertion-ID dedup** via `methodScratch` (TTL = the assertion's
+ *     `NotOnOrAfter` + skew). Success carries `unsolicitedBinding` from
+ *     `config.idpInitiated` for the framework to mint the code.
+ */
+// CJS interop per the SAML house-style note — default-import then
+// destructure rather than relying on the named-export heuristic.
+import xmldom from "@xmldom/xmldom"
+
+import { authError } from "../../types/error"
+import type { MethodContext, MethodResult } from "../../types/method"
+
+import { mapProfile, type VerifiedProfile } from "./attributes"
+import { buildSamlInstance, deriveSpEntityId } from "./saml-instance"
+import type { SamlSpConfig, SamlSpProperties, SamlSpState } from "./types"
+
+const { DOMParser } = xmldom
+
+type NodeSamlProfile = {
+  nameID?: string
+  nameIDFormat?: string
+  sessionIndex?: string
+  attributes?: Record<string, unknown>
+  getSamlResponseXml?: () => string
+  /** The signed assertion XML — the bytes xml-crypto verified. */
+  getAssertionXml?: () => string
+}
+
+/**
+ * Gauntlet item 6 — `SubjectConfirmationData/@Recipient`.
+ *
+ * node-saml enforces Issuer, AudienceRestriction,
+ * Conditions/SubjectConfirmation timestamps and `InResponseTo`, but it
+ * does **not** validate `@Recipient`. The SAML 2.0 Web Browser SSO
+ * profile (§4.1.4.3) requires a bearer `SubjectConfirmationData` whose
+ * `Recipient` is the ACS the assertion was delivered to. We read it
+ * from the **signed** assertion (`getAssertionXml()` — the verified
+ * bytes, never the unsigned outer Response) and compare to the exact
+ * ACS URL committed at AuthnRequest time. A real xml-crypto-verified
+ * DOM parse, not an xml2js-shape walk (which the plan rejected as more
+ * fragile than the documented gap).
+ *
+ * Returns `null` when the check passes; otherwise a non-`success`
+ * `MethodResult` (`denied` for a binding failure, `error` for a
+ * library/infra fault — matching the rest of this handler's
+ * classification).
+ */
+function checkRecipient(
+  profile: NodeSamlProfile,
+  acsUrl: string,
+): MethodResult<SamlSpProperties, SamlSpState> | null {
+  if (typeof profile.getAssertionXml !== "function") {
+    // node-saml v5.1 populates this on a successful verify. Its
+    // absence means the library contract changed under us — fail loud
+    // rather than skip a security check we now promise.
+    return {
+      kind: "error",
+      error: authError.internalError(
+        "saml-sp: node-saml profile exposes no getAssertionXml(); cannot " +
+          "perform the Recipient binding check. Refusing to authenticate.",
+      ),
+    }
+  }
+
+  let doc: Document
+  try {
+    doc = new DOMParser().parseFromString(
+      profile.getAssertionXml(),
+      "text/xml",
+    ) as unknown as Document
+  } catch (e) {
+    return {
+      kind: "error",
+      error: authError.internalError(
+        "saml-sp: failed to parse the verified assertion for the " +
+          "Recipient check",
+        e,
+      ),
+    }
+  }
+
+  // Namespace-agnostic: match by local name regardless of prefix.
+  const nodes = doc.getElementsByTagNameNS(
+    "*",
+    "SubjectConfirmationData",
+  )
+  const recipients: string[] = []
+  for (let i = 0; i < nodes.length; i++) {
+    const r = nodes[i]?.getAttribute("Recipient")
+    if (r) recipients.push(r)
+  }
+
+  if (recipients.length === 0) {
+    return {
+      kind: "denied",
+      reason:
+        "assertion has no SubjectConfirmationData/@Recipient binding it " +
+        "to this ACS",
+    }
+  }
+  if (!recipients.includes(acsUrl)) {
+    return {
+      kind: "denied",
+      reason: "recipient mismatch: assertion not addressed to this ACS",
+    }
+  }
+  return null
+}
+
+/**
+ * For IdP-initiated replay dedup: pull the assertion `@ID` and the
+ * tightest `NotOnOrAfter` from the **verified** assertion XML (the same
+ * bytes `checkRecipient` reads). Returns `null` if the assertion XML is
+ * unavailable (caller treats that as a fail-loud error — we will not
+ * skip replay protection we promised).
+ */
+function extractReplayInfo(
+  profile: NodeSamlProfile,
+): { assertionId: string; notOnOrAfterMs: number | null } | null {
+  if (typeof profile.getAssertionXml !== "function") return null
+  let doc: Document
+  try {
+    doc = new DOMParser().parseFromString(
+      profile.getAssertionXml(),
+      "text/xml",
+    ) as unknown as Document
+  } catch {
+    return null
+  }
+  const root = doc.documentElement
+  const assertionId = root?.getAttribute("ID") ?? ""
+  if (!assertionId) return null
+  let earliest: number | null = null
+  for (const tag of ["Conditions", "SubjectConfirmationData"]) {
+    const els = doc.getElementsByTagNameNS("*", tag)
+    for (let i = 0; i < els.length; i++) {
+      const v = els[i]?.getAttribute("NotOnOrAfter")
+      if (!v) continue
+      const ms = Date.parse(v)
+      if (!Number.isNaN(ms)) earliest = earliest === null ? ms : Math.min(earliest, ms)
+    }
+  }
+  return { assertionId, notOnOrAfterMs: earliest }
+}
+
+export async function consumeAssertion(
+  ctx: MethodContext<SamlSpState>,
+  methodId: string,
+  config: SamlSpConfig,
+): Promise<MethodResult<SamlSpProperties, SamlSpState>> {
+  // Discriminator: a consumed flow ⇒ SP-initiated; no flow ⇒ an
+  // unsolicited IdP-initiated POST (the framework only routes one here
+  // when this instance opted in via `unsolicitedCallback`).
+  const idpInitiated = ctx.flow === null
+
+  let spEntityId: string
+  let acsUrl: string
+  if (idpInitiated) {
+    if (!config.idpInitiated) {
+      // Fail-closed: should be unreachable (the framework gates on
+      // `unsolicitedCallback`, set only when idpInitiated is config'd).
+      return {
+        kind: "error",
+        error: authError.internalError(
+          "saml-sp: unsolicited Response reached a method with no " +
+            "idpInitiated config",
+        ),
+      }
+    }
+    if (!ctx.dispatch) {
+      return {
+        kind: "error",
+        error: authError.internalError(
+          "saml-sp: IdP-initiated ACS dispatched without issuer context",
+        ),
+      }
+    }
+    // Same derivation as AuthnRequest / metadata — no drift.
+    spEntityId = deriveSpEntityId(
+      ctx.dispatch.issuerUrl,
+      ctx.tenant.id,
+      methodId,
+    )
+    acsUrl = ctx.dispatch.callbackUrl
+  } else {
+    const state = ctx.methodState
+    if (!state || !state.spEntityId || !state.acsUrl) {
+      return {
+        kind: "error",
+        error: authError.internalError(
+          "saml-sp: ACS reached without AuthnRequest method state " +
+            "(spEntityId / acsUrl). The flow did not originate from this method.",
+        ),
+      }
+    }
+    spEntityId = state.spEntityId
+    acsUrl = state.acsUrl
+  }
+
+  let samlResponse: string | null
+  let relayState: string | null
+  try {
+    const form = new URLSearchParams(await ctx.request.text())
+    samlResponse = form.get("SAMLResponse")
+    relayState = form.get("RelayState")
+  } catch {
+    return {
+      kind: "error",
+      error: authError.internalError("saml-sp: ACS could not read POST body"),
+    }
+  }
+  if (!samlResponse) {
+    return { kind: "denied", reason: "missing SAMLResponse" }
+  }
+
+  // Build is a configuration concern (e.g. no signing cert within its
+  // validity window, or a rotation gap). A throw here is an operator
+  // fault, NOT a user auth failure — surfacing it as `denied` would
+  // hide a misconfiguration behind per-user "access denied" noise.
+  let saml: ReturnType<typeof buildSamlInstance>
+  try {
+    saml = buildSamlInstance(
+      config,
+      {
+        spEntityId,
+        acsUrl,
+        scratch: ctx.methodScratch,
+        ...(idpInitiated ? { idpInitiated: true } : {}),
+        // Encrypted assertions are opt-in per connection. Absent ⇒ no
+        // decryptionPvk ⇒ node-saml rejects an EncryptedAssertion.
+        ...(config.allowEncryptedAssertions && config.decryptionKey
+          ? { decryptionPvk: config.decryptionKey.privateKeyPem }
+          : {}),
+      },
+      Date.now(),
+    )
+  } catch (e) {
+    return {
+      kind: "error",
+      error: authError.internalError(
+        `saml-sp: cannot construct verifier: ${
+          e instanceof Error ? e.message : String(e)
+        }`,
+        e,
+      ),
+    }
+  }
+
+  let profile: NodeSamlProfile | null
+  try {
+    const result = await saml.validatePostResponseAsync({
+      SAMLResponse: samlResponse,
+      ...(relayState !== null ? { RelayState: relayState } : {}),
+    })
+    profile = result.profile as NodeSamlProfile | null
+  } catch (e) {
+    // Every node-saml verification failure (bad/absent signature,
+    // signature-wrapping, issuer/audience mismatch, expired
+    // conditions, unknown InResponseTo) throws here. These are
+    // controlled auth failures, not server faults.
+    const msg = e instanceof Error ? e.message : String(e)
+    // node-saml throws this exact message when an EncryptedAssertion
+    // arrives but no decryptionPvk is configured. Give the operator a
+    // signal that the *connection* is mis/under-configured rather than
+    // a generic "assertion rejected".
+    if (
+      !config.allowEncryptedAssertions &&
+      msg.includes("No decryption key")
+    ) {
+      return {
+        kind: "denied",
+        reason:
+          "encrypted assertion received but encrypted assertions are not " +
+          "enabled for this SAML connection (set allowEncryptedAssertions " +
+          "+ decryptionKey)",
+      }
+    }
+    return { kind: "denied", reason: `assertion rejected: ${msg}` }
+  }
+
+  if (!profile || !profile.nameID) {
+    return { kind: "denied", reason: "assertion produced no usable subject" }
+  }
+
+  // Gauntlet item 6 — node-saml does not enforce @Recipient; we do,
+  // against the exact ACS URL the IdP saw (committed for SP-init,
+  // derived for IdP-init — identical value either way).
+  const recipientFailure = checkRecipient(profile, acsUrl)
+  if (recipientFailure) return recipientFailure
+
+  // IdP-init replay: no InResponseTo single-use to lean on, so dedup
+  // the signed assertion's @ID. SP-init does not need this (the
+  // request id is already single-use).
+  if (idpInitiated) {
+    const replay = extractReplayInfo(profile)
+    if (!replay) {
+      return {
+        kind: "error",
+        error: authError.internalError(
+          "saml-sp: cannot read assertion @ID for IdP-initiated replay " +
+            "protection. Refusing to authenticate.",
+        ),
+      }
+    }
+    const key = `idp-replay:${replay.assertionId}`
+    const seen = await ctx.methodScratch.get(key)
+    if (seen.ok) {
+      return {
+        kind: "denied",
+        reason: "assertion replay detected (assertion ID already seen)",
+      }
+    }
+    const skewMs = (config.clockSkewSeconds ?? 60) * 1000
+    const now = Date.now()
+    const horizon =
+      replay.notOnOrAfterMs !== null
+        ? replay.notOnOrAfterMs - now + skewMs
+        : 10 * 60_000
+    // Clamp: never below the skew window, never an unbounded entry.
+    const ttlMs = Math.min(Math.max(horizon, skewMs, 60_000), 24 * 60 * 60_000)
+    const recorded = await ctx.methodScratch.put(key, "1", ttlMs)
+    if (!recorded.ok) {
+      // The dedup store is unavailable — failing open would allow
+      // replay. Fail closed.
+      return {
+        kind: "error",
+        error: authError.internalError(
+          "saml-sp: could not record assertion ID for replay protection",
+        ),
+      }
+    }
+  }
+
+  const verified: VerifiedProfile = {
+    nameID: profile.nameID,
+    nameIDFormat: profile.nameIDFormat ?? "",
+    ...(profile.sessionIndex !== undefined
+      ? { sessionIndex: profile.sessionIndex }
+      : {}),
+    attributes: profile.attributes ?? {},
+    responseXml: profile.getSamlResponseXml?.() ?? "",
+  }
+
+  const mapped = mapProfile(verified, config.attributeMapping)
+  if ("error" in mapped) {
+    return { kind: "denied", reason: mapped.error }
+  }
+
+  return {
+    kind: "success",
+    providerSubject: mapped.providerSubject,
+    properties: mapped.properties,
+    ...(idpInitiated && config.idpInitiated
+      ? {
+          unsolicitedBinding: {
+            clientId: config.idpInitiated.defaultClientId,
+            redirectUri: config.idpInitiated.defaultRedirectUri,
+            scopes: config.idpInitiated.defaultScopes ?? [],
+          },
+        }
+      : {}),
+  }
+}

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

@@ -0,0 +1,137 @@
+/**
+ * Attribute mapping — translate a node-saml `Profile` (already
+ * cryptographically verified by the time it reaches here) into our
+ * `SamlSpProperties`.
+ *
+ * node-saml flattens the assertion's `AttributeStatement` onto the
+ * `Profile` object as arbitrary top-level keys (single value → string,
+ * multi-valued → array), plus the structural `nameID` /
+ * `nameIDFormat` / `sessionIndex`. The host's `success` callback owns
+ * the final `SubjectClaim`; this layer just normalises the SAML side
+ * per the tenant's configured `SamlAttributeMapping`.
+ *
+ * Pure: no node-saml import, no I/O. `Profile` is modelled here as the
+ * minimal structural shape we read, so this file stays free of the
+ * third-party type (the public-API leak guard depends on that).
+ */
+import type {
+  SamlAttributeMapping,
+  SamlAttributeRef,
+  SamlNameIdFormat,
+  SamlSpProperties,
+} from "./types"
+
+/** The slice of node-saml's `Profile` we actually consume. */
+export type VerifiedProfile = {
+  nameID: string
+  nameIDFormat: string
+  sessionIndex?: string
+  attributes: Record<string, unknown>
+  authnInstant?: string
+  responseXml: string
+}
+
+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 normalizeNameIdFormat(urn: string): SamlNameIdFormat {
+  return NAME_ID_FORMAT_BY_URN[urn] ?? "unspecified"
+}
+
+/** First value if array, the value if scalar, else undefined. */
+function scalar(v: unknown): string | undefined {
+  if (typeof v === "string") return v
+  if (Array.isArray(v) && v.length > 0 && typeof v[0] === "string") {
+    return v[0]
+  }
+  return undefined
+}
+
+/** Preserve array shape for multi-valued attributes (e.g. groups). */
+function multi(v: unknown): string | string[] | undefined {
+  if (typeof v === "string") return v
+  if (Array.isArray(v)) {
+    const strs = v.filter((x): x is string => typeof x === "string")
+    return strs.length > 0 ? strs : undefined
+  }
+  return undefined
+}
+
+function resolveRef(
+  ref: SamlAttributeRef,
+  profile: VerifiedProfile,
+): string | string[] | undefined {
+  if (ref.source === "nameId") return profile.nameID
+  return multi(profile.attributes[ref.name])
+}
+
+export type MappedSubject = {
+  providerSubject: string
+  properties: SamlSpProperties
+}
+
+/**
+ * Build `(providerSubject, properties)` from a verified profile.
+ * Returns a string describing the failure when the configured subject
+ * source resolves to nothing — the caller turns that into a `denied`
+ * result rather than minting a subject-less success.
+ */
+export function mapProfile(
+  profile: VerifiedProfile,
+  mapping: SamlAttributeMapping,
+): MappedSubject | { error: string } {
+  const subjectRef: SamlAttributeRef = mapping.subject ?? { source: "nameId" }
+  const subjectVal = scalar(resolveRef(subjectRef, profile))
+  if (!subjectVal) {
+    return {
+      error:
+        subjectRef.source === "nameId"
+          ? "assertion NameID is empty; cannot derive subject"
+          : `subject attribute "${subjectRef.name}" missing from assertion`,
+    }
+  }
+
+  const attributes: Record<string, string | string[]> = {}
+
+  const put = (key: string, ref: SamlAttributeRef | undefined): void => {
+    if (!ref) return
+    const v = resolveRef(ref, profile)
+    if (v !== undefined) attributes[key] = v
+  }
+
+  put("email", mapping.email)
+  put("name", mapping.name)
+  put("groups", mapping.groups)
+  if (mapping.emailVerified) {
+    attributes["emailVerified"] = mapping.emailVerified.value
+      ? "true"
+      : "false"
+  }
+  for (const [key, ref] of Object.entries(mapping.custom ?? {})) {
+    put(key, ref)
+  }
+
+  const authnInstant = profile.authnInstant
+    ? Date.parse(profile.authnInstant)
+    : Date.now()
+
+  return {
+    providerSubject: subjectVal,
+    properties: {
+      nameId: {
+        value: profile.nameID,
+        format: normalizeNameIdFormat(profile.nameIDFormat),
+      },
+      attributes,
+      ...(profile.sessionIndex !== undefined
+        ? { sessionIndex: profile.sessionIndex }
+        : {}),
+      authnInstant: Number.isNaN(authnInstant) ? Date.now() : authnInstant,
+      raw: { responseXml: profile.responseXml },
+    },
+  }
+}

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

@@ -0,0 +1,128 @@
+/**
+ * `GET /authorize` — SP-initiated SSO. Builds a SAML `AuthnRequest`
+ * via node-saml and redirects the user agent to the IdP's SSO
+ * endpoint (HTTP-Redirect binding).
+ *
+ * The framework state envelope (`ctx.dispatch.state`) is carried as
+ * RelayState; the IdP echoes it back on the ACS POST so the standard
+ * callback machinery can recover the tenant + flow. node-saml records
+ * the generated request id in the `methodScratch`-backed cache for
+ * `InResponseTo` enforcement at the ACS.
+ */
+import { authError } from "../../types/error"
+import type { MethodContext, MethodResult } from "../../types/method"
+import { isErr } from "../../types/result"
+
+import { buildSamlInstance, deriveSpEntityId } from "./saml-instance"
+import type { SamlSpConfig, SamlSpProperties, SamlSpState } from "./types"
+
+export async function buildAuthnRequestRedirect(
+  ctx: MethodContext<SamlSpState>,
+  methodId: string,
+  config: SamlSpConfig,
+): Promise<MethodResult<SamlSpProperties, SamlSpState>> {
+  if (!ctx.dispatch) {
+    return {
+      kind: "error",
+      error: authError.internalError("saml-sp: dispatch missing on /authorize"),
+    }
+  }
+
+  // O3: signed AuthnRequest uses a per-connection SP keypair from
+  // config (decoupled from the OIDC KeyStore). The Zod schema already
+  // enforces `signAuthnRequest ⇒ signingKey`; guard defensively so a
+  // schema regression can never silently emit an unsigned request when
+  // the operator asked for a signed one.
+  if (config.signAuthnRequest && !config.signingKey) {
+    return {
+      kind: "error",
+      error: authError.internalError(
+        "saml-sp: signAuthnRequest is true but signingKey is missing " +
+          "(config schema should have rejected this).",
+      ),
+    }
+  }
+
+  const spEntityId = deriveSpEntityId(
+    ctx.dispatch.issuerUrl,
+    ctx.tenant.id,
+    methodId,
+  )
+
+  const acsUrl = ctx.dispatch.callbackUrl
+
+  // Fail fast if the SessionStore adapter doesn't implement the
+  // scratch trio. node-saml ignores its CacheProvider.saveAsync
+  // return value, so without this probe we would issue an
+  // AuthnRequest whose request id is never cached — every assertion
+  // would then be rejected at the ACS with an opaque
+  // "InResponseTo not valid", and the operator would have no signal
+  // that the real problem is an unsupported adapter. Mirrors the
+  // explicit signAuthnRequest guard above.
+  const probe = await ctx.methodScratch.put(
+    "authnrequest-scratch-probe",
+    "1",
+    1000,
+  )
+  if (isErr(probe)) {
+    return {
+      kind: "error",
+      error: authError.internalError(
+        "saml-sp: the configured SessionStore adapter does not support " +
+          "methodScratch (saveScratch/readScratch/deleteScratch), which " +
+          "SAML SP requires for InResponseTo replay protection. Deploy " +
+          "SAML against an adapter that implements the scratch trio.",
+      ),
+    }
+  }
+
+  let redirectUrl: string
+  try {
+    const saml = buildSamlInstance(
+      config,
+      {
+        spEntityId,
+        acsUrl,
+        scratch: ctx.methodScratch,
+        ...(config.signAuthnRequest && config.signingKey
+          ? {
+              signing: {
+                privateKeyPem: config.signingKey.privateKeyPem,
+                certPem: config.signingKey.certPem,
+              },
+            }
+          : {}),
+      },
+      Date.now(),
+    )
+    redirectUrl = await saml.getAuthorizeUrlAsync(
+      ctx.dispatch.state,
+      undefined,
+      {},
+    )
+  } catch (e) {
+    return {
+      kind: "error",
+      error: authError.internalError(
+        `saml-sp: failed to build AuthnRequest: ${
+          e instanceof Error ? e.message : String(e)
+        }`,
+        e,
+      ),
+    }
+  }
+
+  return {
+    kind: "challenge",
+    response: new Response(null, {
+      status: 302,
+      headers: { location: redirectUrl },
+    }),
+    saveMethodState: {
+      relayState: ctx.dispatch.state,
+      issuedAt: Date.now(),
+      spEntityId,
+      acsUrl,
+    },
+  }
+}