@_mustachio/openauth 0.10.0 → 0.12.0

package/src/methods/saml-sp/cache-provider.ts

@@ -0,0 +1,76 @@
+/**
+ * `@node-saml/node-saml` `CacheProvider` backed by `methodScratch`.
+ *
+ * node-saml tracks outstanding `AuthnRequest` IDs through a
+ * `CacheProvider`: `saveAsync(requestId, marker)` when the request is
+ * generated, then `getAsync` + `removeAsync` during response
+ * validation to enforce `InResponseTo` (defeats unsolicited /
+ * replayed Responses on the SP-initiated path).
+ *
+ * The default in-memory provider is single-process only. We back it
+ * with `MethodContext.methodScratch`, which is already scoped per
+ * `(tenantId, methodId)` and shared across instances via the
+ * `SessionStore` adapter — so an AuthnRequest minted on one node
+ * validates on another.
+ *
+ * `methodScratch.get` returning `unknown_state` (missing / expired)
+ * maps to `null`, which is exactly node-saml's "unknown request id"
+ * signal.
+ */
+import type { MethodScratch } from "../../types/method"
+
+import { isOk } from "../../types/result"
+
+type CacheItem = { value: string; createdAt: number }
+type NodeSamlCacheProvider = {
+  saveAsync(key: string, value: string): Promise<CacheItem | null>
+  getAsync(key: string): Promise<string | null>
+  removeAsync(key: string | null): Promise<string | null>
+}
+
+/** Key namespace inside the (already tenant/method-scoped) scratch. */
+const KEY_PREFIX = "saml-inresponseto:"
+
+/**
+ * @param scratch  Per-request `MethodContext.methodScratch`.
+ * @param ttlMs    How long an outstanding request id stays valid. Should
+ *                  comfortably exceed the slowest realistic IdP login
+ *                  (the flow record itself expires independently).
+ */
+export function methodScratchCacheProvider(
+  scratch: MethodScratch,
+  ttlMs: number,
+): NodeSamlCacheProvider {
+  return {
+    async saveAsync(key, value) {
+      const createdAt = Date.now()
+      const item: CacheItem = { value, createdAt }
+      const r = await scratch.put(
+        `${KEY_PREFIX}${key}`,
+        JSON.stringify(item),
+        ttlMs,
+      )
+      // node-saml treats a null return as "could not cache" and fails
+      // the request generation loudly — which is what we want if the
+      // backing store is unavailable.
+      return isOk(r) ? item : null
+    },
+
+    async getAsync(key) {
+      const r = await scratch.get(`${KEY_PREFIX}${key}`)
+      if (!isOk(r)) return null
+      try {
+        const item = JSON.parse(r.value) as CacheItem
+        return item.value
+      } catch {
+        return null
+      }
+    },
+
+    async removeAsync(key) {
+      if (key === null) return null
+      const r = await scratch.delete(`${KEY_PREFIX}${key}`)
+      return isOk(r) ? key : null
+    },
+  }
+}

package/src/methods/saml-sp/cert-rotation.ts

@@ -0,0 +1,34 @@
+/**
+ * Cert-rotation shim.
+ *
+ * `@node-saml/node-saml`'s `idpCert` accepts a single PEM, an array of
+ * PEMs, or a callback. Our config models hot rotation as an array of
+ * `{ pem, notBefore?, notAfter? }`. This pure function filters that
+ * array to the certs whose validity window covers `now`, producing the
+ * PEM list node-saml verifies against.
+ *
+ * A cert with no `notBefore` has no lower bound; no `notAfter` has no
+ * upper bound. `notBefore` is inclusive, `notAfter` is exclusive — a
+ * cert is active while `notBefore <= now < notAfter`. Overlapping
+ * windows are the whole point: during rotation both the outgoing and
+ * incoming cert are active so in-flight assertions from either key
+ * still verify.
+ *
+ * Returns `[]` when nothing is in window — the caller surfaces a
+ * configuration error rather than handing node-saml an empty cert set
+ * (which it would treat as "accept nothing").
+ */
+import type { SamlIdpSigningCert } from "./types"
+
+export function selectActiveCertPems(
+  certs: ReadonlyArray<SamlIdpSigningCert>,
+  nowMs: number,
+): string[] {
+  return certs
+    .filter((c) => {
+      if (c.notBefore !== undefined && nowMs < c.notBefore) return false
+      if (c.notAfter !== undefined && nowMs >= c.notAfter) return false
+      return true
+    })
+    .map((c) => c.pem)
+}

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

@@ -0,0 +1,118 @@
+/**
+ * SAML SP factory — `kind: "saml-sp"`.
+ *
+ * Parallels `oauth2Factory` / `oidcFactory`: a Zod `configSchema`
+ * validates the tenant-supplied `SamlSpConfig` blob (Zod 3.24+ is
+ * Standard Schema v1 conformant, so it satisfies
+ * `AuthMethodFactory.configSchema` directly), and `build` delegates to
+ * `buildSamlSpMethod`.
+ *
+ * No `@node-saml/*` import appears here — node-saml is reached only at
+ * request time inside the route handlers, so importing the factory
+ * type surface stays cheap and the public-API leak guard stays green.
+ */
+import { z } from "zod"
+
+import type { AuthMethod, AuthMethodFactory } from "../../types/method"
+
+import { buildSamlSpMethod } from "./method"
+import type { SamlSpConfig, SamlSpProperties, SamlSpState } from "./types"
+
+const attributeRefSchema = z.union([
+  z.object({ source: z.literal("nameId") }),
+  z.object({
+    source: z.literal("attribute"),
+    name: z.string().min(1),
+    format: z.string().optional(),
+  }),
+])
+
+const attributeMappingSchema = z.object({
+  subject: attributeRefSchema.optional(),
+  email: attributeRefSchema.optional(),
+  emailVerified: z
+    .object({ source: z.literal("literal"), value: z.boolean() })
+    .optional(),
+  name: attributeRefSchema.optional(),
+  groups: attributeRefSchema.optional(),
+  custom: z.record(attributeRefSchema).optional(),
+})
+
+const signingCertSchema = z.object({
+  pem: z.string().min(1),
+  notBefore: z.number().optional(),
+  notAfter: z.number().optional(),
+})
+
+const idpSchema = z.object({
+  entityId: z.string().min(1),
+  ssoUrl: z.string().url(),
+  sloUrl: z.string().url().optional(),
+  nameIdFormat: z
+    .enum(["persistent", "transient", "emailAddress", "unspecified"])
+    .optional(),
+  signingCerts: z.array(signingCertSchema).min(1),
+})
+
+const idpInitiatedSchema = z.object({
+  defaultClientId: z.string().min(1),
+  defaultRedirectUri: z.string().url(),
+  defaultScopes: z.array(z.string()).optional(),
+})
+
+const samlSpConfigSchema = z
+  .object({
+    idp: idpSchema,
+    attributeMapping: attributeMappingSchema,
+    signAuthnRequest: z.boolean().optional(),
+    signingKey: z
+      .object({
+        privateKeyPem: z.string().min(1),
+        certPem: z.string().min(1),
+      })
+      .optional(),
+    allowEncryptedAssertions: z.boolean().optional(),
+    decryptionKey: z
+      .object({
+        privateKeyPem: z.string().min(1),
+        certPem: z.string().min(1),
+      })
+      .optional(),
+    idpInitiated: idpInitiatedSchema.optional(),
+    clockSkewSeconds: z.number().int().nonnegative().optional(),
+  })
+  .refine((c) => !c.signAuthnRequest || c.signingKey !== undefined, {
+    message: "signingKey is required when signAuthnRequest is true",
+    path: ["signingKey"],
+  })
+  .refine(
+    (c) => !c.allowEncryptedAssertions || c.decryptionKey !== undefined,
+    {
+      message:
+        "decryptionKey is required when allowEncryptedAssertions is true",
+      path: ["decryptionKey"],
+    },
+  )
+
+export type SamlSpFactoryConfig = z.infer<typeof samlSpConfigSchema>
+
+/**
+ * Generic SAML 2.0 Service Provider factory.
+ *
+ * `kind: "saml-sp"`. Use a distinct `MethodConfig.id` per upstream IdP
+ * to register multiple SAML connections against a single tenant.
+ */
+export const samlSpFactory: AuthMethodFactory<
+  SamlSpProperties,
+  SamlSpState,
+  SamlSpConfig
+> = {
+  kind: "saml-sp",
+  configSchema: samlSpConfigSchema,
+  build: async ({
+    id,
+    kind,
+    config,
+  }): Promise<AuthMethod<SamlSpProperties, SamlSpState>> =>
+    buildSamlSpMethod(id, kind, config),
+}

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

@@ -0,0 +1,34 @@
+/**
+ * `@_mustachio/openauth/methods/saml-sp` — SAML 2.0 Service Provider
+ * method family.
+ *
+ * **Node-only.** This entry depends transitively on
+ * `@node-saml/node-saml` and `xml-crypto`, which require `node:crypto`
+ * and the `@xmldom/xmldom` DOM. Cloudflare Workers, browsers, and
+ * other edge runtimes cannot load this module; use the root
+ * `@_mustachio/openauth` entry (OIDC / OAuth methods) on those
+ * platforms.
+ *
+ * The library's root entry is verified edge-clean by
+ * `test/types/public-api-no-thirdparty-leaks.test.ts` and the
+ * complementary `saml-sp-no-thirdparty-leaks.test.ts` — neither this
+ * subpath's third-party deps nor its public types are reachable from
+ * `@_mustachio/openauth`.
+ *
+ * See `docs/plans/claude/saml-sp-plan.md` for the architectural
+ * decisions backing this surface (SAML-AD1–AD7) and the phase plan.
+ */
+export { samlSpFactory } from "./factory"
+export { parseSamlIdpMetadata } from "./parse-idp-metadata"
+
+export type {
+  SamlAttributeMapping,
+  SamlAttributeRef,
+  SamlIdpConfig,
+  SamlIdpInitiatedConfig,
+  SamlIdpSigningCert,
+  SamlNameIdFormat,
+  SamlSpConfig,
+  SamlSpProperties,
+  SamlSpState,
+} from "./types"

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

@@ -0,0 +1,204 @@
+/**
+ * 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
+ * (`deriveSpEntityId(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` /
+ * `WantAssertionsSigned="true"` truthfully state actual behaviour.
+ */
+import { authError } from "../../types/error"
+import type { MethodContext, MethodResult } from "../../types/method"
+
+import { deriveSpEntityId } 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
+}
+
+/** 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 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="true" ` +
+    `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 = deriveSpEntityId(
+    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 }
+      : {}),
+    // 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,
+  }
+}