@_mustachio/openauth 0.11.0 → 0.13.0

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

@@ -0,0 +1,146 @@
+/**
+ * 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>
+  /** `AuthnStatement/@AuthnInstant`, raw XSD dateTime. */
+  authnInstant?: string
+  /** `AuthnStatement/@SessionNotOnOrAfter`, already parsed to Unix ms. */
+  sessionNotOnOrAfter?: number
+  /** `AuthnContext/AuthnContextClassRef` — what the IdP actually asserted. */
+  authnContextClassRef?: 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,
+      ...(profile.sessionNotOnOrAfter !== undefined
+        ? { sessionNotOnOrAfter: profile.sessionNotOnOrAfter }
+        : {}),
+      ...(profile.authnContextClassRef !== undefined
+        ? { authnContextClassRef: profile.authnContextClassRef }
+        : {}),
+      raw: { responseXml: profile.responseXml },
+    },
+  }
+}

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

@@ -0,0 +1,129 @@
+/**
+ * `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, resolveSpEntityId } 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 = resolveSpEntityId(
+    config,
+    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,
+    },
+  }
+}

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,139 @@
+/**
+ * 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(),
+    spEntityId: z.string().min(1).optional(),
+    forceAuthn: z.boolean().optional(),
+    requestedAuthnContext: z
+      .object({
+        classRefs: z.array(z.string().min(1)).min(1),
+        comparison: z
+          .enum(["exact", "minimum", "maximum", "better"])
+          .optional(),
+      })
+      .optional(),
+    requireSignedAssertion: z.boolean().optional(),
+    requireSignedResponse: z.boolean().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"],
+  })
+  // An assertion nobody signed, inside a Response nobody signed, is
+  // unauthenticated XML. Refuse the combination outright rather than
+  // let a connection be configured into accepting anything.
+  .refine(
+    (c) =>
+      (c.requireSignedAssertion ?? true) || c.requireSignedResponse === true,
+    {
+      message:
+        "requireSignedAssertion may only be false when requireSignedResponse " +
+        "is true — at least one signature is mandatory",
+      path: ["requireSignedAssertion"],
+    },
+  )
+
+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"