@_mustachio/openauth 0.11.0 → 0.12.0

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

@@ -0,0 +1,164 @@
+/**
+ * `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,173 @@
+/**
+ * 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}`
+}
+
+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: true,
+    wantAuthnResponseSigned: false,
+    acceptedClockSkewMs: (config.clockSkewSeconds ?? 60) * 1000,
+    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 }
+      : {}),
+  })
+}

package/src/methods/saml-sp/slo-initiate.ts

@@ -0,0 +1,177 @@
+/**
+ * SP-initiated Single Logout — the outbound half.
+ *
+ * `POST /m/<methodId>/logout` (public, gated on `idp.sloUrl` like
+ * `/sls`). The **host** invokes this from its own logout UX for the
+ * **already-authenticated** subject, supplying the subject's SAML
+ * `NameID` (and, ideally, `SessionIndex`) — the values it received in
+ * `SamlSpProperties` at login. The library does not persist the
+ * NameID↔subject↔session mapping (the host owns it; see
+ * `ARCHITECTURE.md` §"onLogout"), so the host is the only party that
+ * can name who is logging out.
+ *
+ * Host contract / security:
+ *   - This route only **propagates** logout to the upstream IdP. It
+ *     does **not** revoke library tokens — OIDC session/token
+ *     termination is `/end_session`'s job and is deliberately *not*
+ *     auto-bridged. A complete host logout flow calls both.
+ *   - It is `POST` (not `GET`) to keep a signed `LogoutRequest` off
+ *     drive-by navigations / prefetch. It is still anonymous at the
+ *     library boundary: the host MUST only render/trigger it for the
+ *     authenticated subject, behind the host's own CSRF protection,
+ *     with that subject's own `NameID`. A forced-logout via CSRF is a
+ *     DoS-class risk the host owns (it owns the session); the library
+ *     cannot authenticate the caller without owning a session it
+ *     deliberately does not.
+ *
+ * The IdP processes the `LogoutRequest` and returns a `LogoutResponse`
+ * to `/sls` (the response leg — see `sls.ts`).
+ */
+import { authError } from "../../types/error"
+import type { MethodContext, MethodResult } from "../../types/method"
+
+import {
+  buildSamlInstance,
+  deriveSpEntityId,
+  NAME_ID_FORMAT_URN,
+} from "./saml-instance"
+import type {
+  SamlNameIdFormat,
+  SamlSpConfig,
+  SamlSpProperties,
+  SamlSpState,
+} from "./types"
+
+export async function initiateSpLogout(
+  ctx: MethodContext<SamlSpState>,
+  methodId: string,
+  config: SamlSpConfig,
+): Promise<MethodResult<SamlSpProperties, SamlSpState>> {
+  if (!ctx.dispatch) {
+    return {
+      kind: "error",
+      error: authError.internalError(
+        "saml-sp: /logout dispatched without issuer context (ctx.dispatch is null)",
+      ),
+    }
+  }
+  if (!config.idp.sloUrl) {
+    // Unreachable: /logout is only public when sloUrl is set.
+    return {
+      kind: "error",
+      error: authError.internalError(
+        "saml-sp: /logout reached with no idp.sloUrl configured",
+      ),
+    }
+  }
+
+  let nameId: string | null
+  let sessionIndex: string | null
+  let relayState: string | null
+  let nameIdFormatParam: string | null
+  try {
+    const form = new URLSearchParams(await ctx.request.text())
+    nameId = form.get("nameId")
+    sessionIndex = form.get("sessionIndex")
+    relayState = form.get("relayState")
+    nameIdFormatParam = form.get("nameIdFormat")
+  } catch {
+    return {
+      kind: "error",
+      error: authError.internalError("saml-sp: /logout could not read POST body"),
+    }
+  }
+
+  if (!nameId) {
+    // The host must supply the subject's SAML NameID — the library
+    // cannot derive it (it never persisted the mapping).
+    return { kind: "denied", reason: "missing nameId" }
+  }
+
+  // NameID format: explicit param wins; else the connection's
+  // configured format; else persistent (the SSO default). The param is
+  // a friendly key (same vocabulary as `config.idp.nameIdFormat`), not
+  // a raw URN — validate it rather than passing an arbitrary
+  // host-supplied string straight into the LogoutRequest, where a
+  // typo'd format silently produces a cryptic IdP-side rejection.
+  if (
+    nameIdFormatParam !== null &&
+    !(nameIdFormatParam in NAME_ID_FORMAT_URN)
+  ) {
+    return {
+      kind: "denied",
+      reason:
+        `unrecognized nameIdFormat "${nameIdFormatParam}" — expected one ` +
+        `of: ${Object.keys(NAME_ID_FORMAT_URN).join(", ")}`,
+    }
+  }
+  const nameIDFormat =
+    nameIdFormatParam !== null
+      ? NAME_ID_FORMAT_URN[nameIdFormatParam as SamlNameIdFormat]
+      : config.idp.nameIdFormat !== undefined
+        ? NAME_ID_FORMAT_URN[config.idp.nameIdFormat]
+        : NAME_ID_FORMAT_URN.persistent
+
+  const spEntityId = deriveSpEntityId(
+    ctx.dispatch.issuerUrl,
+    ctx.tenant.id,
+    methodId,
+  )
+
+  let redirectUrl: string
+  try {
+    const saml = buildSamlInstance(
+      config,
+      {
+        spEntityId,
+        acsUrl: ctx.dispatch.callbackUrl,
+        scratch: ctx.methodScratch,
+        logoutUrl: config.idp.sloUrl,
+        logout: true,
+        // Sign the LogoutRequest whenever a per-connection SP key is
+        // configured — most IdPs require a signed SP-initiated logout.
+        ...(config.signingKey
+          ? {
+              signing: {
+                privateKeyPem: config.signingKey.privateKeyPem,
+                certPem: config.signingKey.certPem,
+              },
+            }
+          : {}),
+      },
+      Date.now(),
+    )
+    redirectUrl = await saml.getLogoutUrlAsync(
+      // node-saml's Profile shape; structurally compatible for request
+      // generation (it reads nameID / nameIDFormat / sessionIndex).
+      {
+        nameID: nameId,
+        nameIDFormat: nameIDFormat,
+        ...(sessionIndex !== null ? { sessionIndex } : {}),
+      } as never,
+      relayState ?? "",
+      {},
+    )
+  } catch (e) {
+    return {
+      kind: "error",
+      error: authError.internalError(
+        `saml-sp: failed to build LogoutRequest: ${
+          e instanceof Error ? e.message : String(e)
+        }`,
+        e,
+      ),
+    }
+  }
+
+  // Pure protocol propagation — no `logout` side effect (the host
+  // already tore down its session and, separately, calls /end_session
+  // for OIDC token revocation).
+  return {
+    kind: "challenge",
+    response: new Response(null, {
+      status: 302,
+      headers: { location: redirectUrl },
+    }),
+  }
+}