@_mustachio/openauth 0.11.0 → 0.13.0

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

@@ -0,0 +1,298 @@
+/**
+ * SAML SP — public types.
+ *
+ * These types are the locked contract for the SAML SP method family and
+ * are intentionally introduced ahead of the runtime implementation so
+ * downstream callers can import them today, and so the public-API
+ * leak guard
+ * (`test/types/saml-sp-no-thirdparty-leaks.test.ts`) can verify
+ * the shapes before any `@node-saml/*` or `xml-crypto` code lands.
+ *
+ * No third-party types appear here. `@node-saml/node-saml`'s `Profile`
+ * is mapped onto `SamlSpProperties` at the wrapper boundary; consumers
+ * never see node-saml's surface.
+ *
+ * See `docs/plans/claude/saml-sp-plan.md` for the architectural
+ * decisions (SAML-AD1–AD7) backing this shape.
+ */
+
+/**
+ * Standard SAML 2.0 NameID formats we support.
+ *
+ *   - `persistent`     — opaque, stable per user/SP pair; preferred.
+ *   - `transient`      — opaque, single-session.
+ *   - `emailAddress`   — RFC 822 email; common with legacy IdPs.
+ *   - `unspecified`    — IdP picks; pass through verbatim.
+ */
+export type SamlNameIdFormat =
+  | "persistent"
+  | "transient"
+  | "emailAddress"
+  | "unspecified"
+
+/**
+ * One field's source. Either the assertion's NameID or a named
+ * attribute. `format` narrows attribute lookup when an IdP issues
+ * multiple attributes with the same `Name` but different `NameFormat`.
+ */
+export type SamlAttributeRef =
+  | { source: "nameId" }
+  | { source: "attribute"; name: string; format?: string }
+
+/**
+ * How the SAML method translates a verified assertion into the
+ * `providerSubject` + per-claim fields that flow into the host's
+ * `success` callback. Mirrors the OIDC method's claim-mapping
+ * configuration — the host owns the final `SubjectClaim`; this map
+ * just normalises the SAML side.
+ */
+export type SamlAttributeMapping = {
+  /** Which attribute becomes `providerSubject`. Defaults to NameID. */
+  subject?: SamlAttributeRef
+  email?: SamlAttributeRef
+  /** SAML assertions are typically issued only after IdP-side verification. */
+  emailVerified?: { source: "literal"; value: boolean }
+  name?: SamlAttributeRef
+  /** Multi-valued — the mapper preserves array shape. */
+  groups?: SamlAttributeRef
+  /** Pass-through map for additional claims hosts want surfaced. */
+  custom?: Record<string, SamlAttributeRef>
+}
+
+/**
+ * A single PEM-encoded IdP signing certificate, optionally bounded by a
+ * validity window. The runtime verifier accepts any cert whose window
+ * covers `now` — supports overlapping hot rotation without re-deploys.
+ */
+export type SamlIdpSigningCert = {
+  pem: string
+  /** Inclusive lower bound. Unix ms. Omit for no lower bound. */
+  notBefore?: number
+  /** Exclusive upper bound. Unix ms. Omit for no upper bound. */
+  notAfter?: number
+}
+
+/**
+ * Identity-Provider-side configuration the host paste/imports from the
+ * IdP's metadata XML (or uploads a metadata URL we fetch once). Stable
+ * across deploys — keyed by `(tenantId, methodId)` in `MethodStore`.
+ */
+export type SamlIdpConfig = {
+  entityId: string
+  /** SSO endpoint URL. HTTP-Redirect binding is the default. */
+  ssoUrl: string
+  /** Single Logout endpoint URL. Optional; Phase 3 deliverable. */
+  sloUrl?: string
+  /** Preferred NameID format requested in `AuthnRequest`. */
+  nameIdFormat?: SamlNameIdFormat
+  /** One or more IdP signing certs. ≥1 required. Hot-rotatable. */
+  signingCerts: ReadonlyArray<SamlIdpSigningCert>
+}
+
+/**
+ * IdP-initiated SSO binding. When set, the ACS endpoint accepts
+ * unsolicited SAML Responses (no `InResponseTo`) and synthesizes a
+ * flow record using these defaults so the existing
+ * `MethodResult.success` path can run end-to-end.
+ *
+ * Documented in plan SAML-AD7 — this is the one architectural carve-out
+ * SAML imposes on the framework. Omit to reject unsolicited Responses
+ * with `invalid_request` (the conservative default).
+ */
+export type SamlIdpInitiatedConfig = {
+  defaultClientId: string
+  defaultRedirectUri: string
+  defaultScopes?: string[]
+}
+
+/**
+ * Tenant-supplied configuration for a SAML SP method instance.
+ * Validated by `samlSpFactory.configSchema` (Standard Schema v1).
+ */
+export type SamlSpConfig = {
+  idp: SamlIdpConfig
+  attributeMapping: SamlAttributeMapping
+  /** Whether to sign outbound `AuthnRequest`. Default `false`. */
+  signAuthnRequest?: boolean
+  /**
+   * Per-connection SP signing keypair (SAML-AD: O3). **Decoupled from
+   * the OIDC `KeyStore` on purpose** — the SP signing cert is pinned at
+   * the IdP and rotated as an IdP-coordination event, not on the OIDC
+   * token-key schedule; this also keeps the design KMS-agnostic.
+   * `privateKeyPem` signs the `AuthnRequest`; `certPem` is what the IdP
+   * pins and what SP metadata advertises. Required iff
+   * `signAuthnRequest` is `true`. Treat `privateKeyPem` as a secret:
+   * the host should encrypt the `MethodStore` at rest (or supply it via
+   * its own resolver) — same handling as any per-tenant credential.
+   */
+  signingKey?: { privateKeyPem: string; certPem: string }
+  /**
+   * Accept `<saml:EncryptedAssertion>` responses. **Off by default** —
+   * a connection only opts in when its IdP is configured to encrypt.
+   * When `false`, an encrypted assertion is rejected (the SP advertises
+   * no decryption cert and node-saml has no `decryptionPvk`). Requires
+   * `decryptionKey` when `true` (enforced by `configSchema`).
+   */
+  allowEncryptedAssertions?: boolean
+  /**
+   * Per-connection SP **decryption** keypair — the private half the IdP
+   * encrypts assertions to. Same SAML-AD O3 rationale as `signingKey`:
+   * decoupled from the OIDC `KeyStore` (the IdP pins the matching cert
+   * via SP metadata; rotation is an IdP-coordination event;
+   * KMS-agnostic). Required iff `allowEncryptedAssertions` is `true`.
+   * Treat `privateKeyPem` as a secret: the host should encrypt the
+   * `MethodStore` at rest (or supply it via its own resolver) — same
+   * handling as `signingKey.privateKeyPem` and any per-tenant
+   * credential. `certPem` is the matching X.509 cert the IdP encrypts
+   * to; SP metadata advertises it as a `use="encryption"`
+   * `KeyDescriptor` (same advertise-only-what-we-serve invariant as
+   * `signingKey`).
+   */
+  decryptionKey?: { privateKeyPem: string; certPem: string }
+  idpInitiated?: SamlIdpInitiatedConfig
+  /** Clock skew allowance for `NotBefore` / `NotOnOrAfter`. Seconds. */
+  clockSkewSeconds?: number
+  /**
+   * Override the derived SP entityID.
+   *
+   * By default the entityID is derived as
+   * `<issuerUrl>/<tenantId>/<methodId>` (SAML-AD5) — stable, no config
+   * required, and guaranteed to match what SP metadata publishes. Set
+   * this **only** to adopt an entityID that already exists at the IdP,
+   * so an existing SAML app can be migrated without the customer
+   * editing their production SSO config.
+   *
+   * The override flows through every consumer at once — `AuthnRequest`
+   * issuer, `AudienceRestriction` validation, SP metadata, and logout
+   * messages — so the anti-drift invariant holds either way. Changing
+   * it on a live connection invalidates the IdP-side trust config;
+   * treat it as an IdP-coordination event.
+   */
+  spEntityId?: string
+  /**
+   * Set `ForceAuthn="true"` on the outbound `AuthnRequest`, asking the
+   * IdP to re-authenticate the user even if it has a live session.
+   * Default `false`.
+   *
+   * Note that this is a *request*: SAML gives the IdP no obligation to
+   * honour it, and there is no way to verify from the Response that it
+   * did. Do not treat a successful assertion as proof of fresh
+   * authentication.
+   */
+  forceAuthn?: boolean
+  /**
+   * Request specific authentication context classes (e.g. MFA) from
+   * the IdP via `<RequestedAuthnContext>`.
+   *
+   * **Omitted ⇒ no `RequestedAuthnContext` element is sent at all**,
+   * which lets the IdP apply its own sign-on policy. That is the right
+   * default for nearly every deployment: a `RequestedAuthnContext` the
+   * IdP cannot satisfy exactly is answered with `NoAuthnContext`
+   * instead of a login, and an MFA policy at the IdP is a common way
+   * to *not* satisfy `PasswordProtectedTransport` under
+   * `Comparison="exact"`.
+   *
+   * Set it only when the IdP has told you which class refs it honours.
+   * `comparison` maps to the `Comparison` attribute and defaults to
+   * `"exact"`; `"minimum"` is usually the safer choice when requesting
+   * MFA.
+   *
+   * Requesting a context does **not** verify one was used — read
+   * `SamlSpProperties.authnContextClassRef` for what the IdP actually
+   * asserted.
+   */
+  requestedAuthnContext?: {
+    /** Full URNs, e.g. `urn:oasis:names:tc:SAML:2.0:ac:classes:MultiFactorAuthn`. */
+    classRefs: ReadonlyArray<string>
+    comparison?: "exact" | "minimum" | "maximum" | "better"
+  }
+  /**
+   * Require the `<saml:Assertion>` itself to carry a valid XML-DSig.
+   * **Defaults to `true` and should stay that way** — the identity,
+   * conditions, and audience all live inside the assertion, so signing
+   * it is what actually binds them.
+   *
+   * Set `false` only for an IdP that signs the outer `<Response>` and
+   * nothing else, and only together with `requireSignedResponse: true`.
+   * The schema refuses to let both be off.
+   */
+  requireSignedAssertion?: boolean
+  /**
+   * Require the outer `<samlp:Response>` to carry a valid XML-DSig.
+   * Default `false` — requiring it is stricter than the Okta / Entra
+   * default and would reject the majority of real IdPs. Enable it for
+   * an IdP that signs the Response, either as defence in depth
+   * alongside a signed assertion or (with
+   * `requireSignedAssertion: false`) as the only signature on offer.
+   */
+  requireSignedResponse?: boolean
+}
+
+/**
+ * Method-private state stashed in `FlowRecord.methodState` for the
+ * duration of an SP-initiated flow.
+ *
+ * `InResponseTo` correlation is handled out-of-band by node-saml's
+ * `CacheProvider` (backed by `methodScratch`), so the outstanding
+ * request id does **not** live here — only the framework state
+ * envelope echoed as RelayState and the issuance timestamp.
+ */
+export type SamlSpState = {
+  relayState: string
+  issuedAt: number
+  /**
+   * SP entityID + ACS URL computed at AuthnRequest time, where the
+   * framework's dispatch context is available. The ACS dispatch has
+   * no dispatch context, so these are read back from here to validate
+   * the assertion's `AudienceRestriction` / `Recipient` against the
+   * exact values the IdP saw in the request.
+   */
+  spEntityId: string
+  acsUrl: string
+}
+
+/**
+ * Properties handed to the host's `IdPOptions.success` callback on a
+ * successful SAML authentication. The host translates these into the
+ * final `SubjectClaim` it owns.
+ *
+ * `raw.responseXml` is provided as an escape hatch for hosts that want
+ * to inspect the verified Response themselves; the wrapper has already
+ * run the full signature gauntlet by the time these properties leave
+ * the method.
+ */
+export type SamlSpProperties = {
+  nameId: {
+    value: string
+    format: SamlNameIdFormat
+  }
+  attributes: Record<string, string | string[]>
+  /** Used for Single Logout correlation (Phase 3). */
+  sessionIndex?: string
+  /** Unix ms — the assertion's `AuthnInstant`. */
+  authnInstant: number
+  /**
+   * Unix ms — the `AuthnStatement/@SessionNotOnOrAfter` the IdP
+   * asserted, when it supplied one. This is the IdP's own view of when
+   * its session for this user expires.
+   *
+   * The library does **not** act on it: token and session lifetimes are
+   * host policy, and this library owns no session. Hosts that want
+   * "when their IdP session ends, ours ends" should clamp their own
+   * session/token TTL to this value in the `success` callback.
+   */
+  sessionNotOnOrAfter?: number
+  /**
+   * The `AuthnContext/AuthnContextClassRef` the IdP actually asserted —
+   * i.e. how it says it authenticated the user. Absent when the
+   * assertion carries none.
+   *
+   * This is the value to check for step-up decisions ("was this really
+   * MFA?"). `SamlSpConfig.requestedAuthnContext` only *asks*; this is
+   * the answer, and the two can differ.
+   */
+  authnContextClassRef?: string
+  raw: {
+    responseXml: string
+  }
+}

package/src/ports/CONSISTENCY.md

@@ -15,30 +15,34 @@ overspecifies adapters that don't need that on the read-eventual paths
 
 ## Per-method consistency contracts
 
-| Port           | Method                                                              | Required                                                                                                               | Why                                                                                                                                                                                                                                                                    |
-| -------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `TokenStore`   | `saveCode(code, payload, ttl)`                                      | **Strong, atomic.** Payload **encrypted at rest** with a key from `KeyStore`; `ttl ≤ 60 s` (framework refuses larger). | Code must be created exactly once and visible to the next `consumeCode` on any node. Payload may carry upstream tokens — see _Code payload confidentiality_ in plan.                                                                                                   |
-| `TokenStore`   | `consumeCode(code)`                                                 | **Strong, CAS.** Returns the **decrypted** payload on success.                                                         | Single-use; second consumption must fail deterministically. Race with itself must resolve to one winner.                                                                                                                                                               |
-| `TokenStore`   | `saveRefresh(refresh, payload)`                                     | **Strong, atomic.**                                                                                                    | New refresh tokens issued during rotation must be immediately retrievable on the next request.                                                                                                                                                                         |
-| `TokenStore`   | `consumeRefresh(refresh, options)`                                  | **Strong, CAS with reuse-detection window** (default 60 s).                                                            | Core of refresh-token rotation security. Concurrent presentations resolve to one winner; reuse within the window triggers the revoke chain.                                                                                                                            |
-| `TokenStore`   | `peekRefresh(refresh)`                                              | **Eventual acceptable.** Non-destructive read; must never mark the token consumed.                                     | Used by `/revoke` for token-to-client binding (RFC 7009 §2.2) and by the refresh-grant for client auth + audit fields. Race losers fall through to `consumeRefresh`, which is the strong gate, so a stale peek can only delay — not bypass — single-use enforcement.   |
-| `TokenStore`   | `revokeFamily(family)`                                              | Strong preferred; eventual acceptable with documented SLA.                                                             | Reuse-detection must invalidate the whole chain. Brief lag is tolerable.                                                                                                                                                                                               |
-| `TokenStore`   | `revokeBySubject(tenant, subject)`                                  | Strong preferred; eventual acceptable with documented SLA.                                                             | Revocation must propagate quickly. A few seconds of lag is tolerable.                                                                                                                                                                                                  |
-| `SessionStore` | `saveFlow(flowId, payload, ttl)`                                    | **Strong, atomic.** `ttl == expiresAt - createdAt`.                                                                    | Flow record must be visible on the callback request to `consumeFlow`.                                                                                                                                                                                                  |
-| `SessionStore` | `updateFlowMethodState(flowId, state)`                              | **Strong, atomic.** Resolves **before** the user-agent redirect is sent.                                               | Upstream PKCE verifier / nonce must be durably persisted before the redirect, otherwise the callback cannot validate.                                                                                                                                                  |
-| `SessionStore` | `consumeFlow(flowId)`                                               | **Strong, atomic delete-on-read** that **returns the full `FlowRecord`** (`CAS` or `DELETE … RETURNING`).              | Single-use; concurrent consumption resolves to one winner. The record is returned so the framework can snapshot fields into the auth-code payload before disposal.                                                                                                     |
-| `SessionStore` | `savePar(uri, payload, ttl)` (optional)                             | **Strong, atomic.** `ttl` default 60 s.                                                                                | RFC 9126 §3 — the PAR record must be visible to the next `consumePar` on any node. One-shot read.                                                                                                                                                                      |
-| `SessionStore` | `consumePar(uri)` (optional)                                        | **Strong, atomic delete-on-read.**                                                                                     | RFC 9126 §4 — `request_uri` is single-use; concurrent presentations of the same uri resolve to one winner. Same semantics as `consumeFlow`.                                                                                                                            |
-| `SessionStore` | `createSession / readSession / revokeSession` (optional long-lived) | **Strong.**                                                                                                            | Session creation must be immediately readable on the next request.                                                                                                                                                                                                     |
-| `TokenStore`   | `recordDpopJti(jti, ttlMs)` (optional)                              | **Strong, atomic record-or-fail.**                                                                                     | RFC 9449 §11.1 — replay protection requires single-use enforcement on the jti within the TTL window. A re-presentation must return `invalid_grant` deterministically. Adapters without this method cannot satisfy DPoP and the verifier surfaces `invalid_dpop_proof`. |
-| `KeyStore`     | `currentSigningKey()` / `currentEncryptionKey()`                    | Strong.                                                                                                                | Active key must be unambiguous.                                                                                                                                                                                                                                        |
-| `KeyStore`     | `signingKeys()` (JWKS)                                              | Eventual OK (with TTL).                                                                                                | Verifiers tolerate brief JWKS lag during rotation.                                                                                                                                                                                                                     |
-| `KeyStore`     | `getEncryptionKey(kid)`                                             | Strong.                                                                                                                | Required to decrypt code payloads encrypted under non-current keys during the overlap window.                                                                                                                                                                          |
-| `ConfigStore`  | `getTenantConfig(id)`                                               | **Eventual + bounded staleness (TTL ≤ 60 s).** Invalidation hook fires on update.                                      | Read-heavy, write-rare. Aggressive caching is desirable.                                                                                                                                                                                                               |
-| `ConfigStore`  | `putTenantConfig(config)`                                           | **Strong write + immediate invalidation** of cached entries for the affected `TenantId`.                               | Subsequent `getTenantConfig` must reflect the new value once the write resolves.                                                                                                                                                                                       |
-| `MethodStore`  | `getMethodConfig` / `listMethods`                                   | Same as `ConfigStore.getTenantConfig`.                                                                                 | Subset of tenant config.                                                                                                                                                                                                                                               |
-| `MethodStore`  | `putMethodConfig` / `deleteMethodConfig`                            | Strong write + immediate invalidation.                                                                                 | Console-driven mutations must take effect on the next request.                                                                                                                                                                                                         |
-| `AuditLog`     | `log(event)`                                                        | Append-only, durable. Cross-instance ordering **not** required (consumers sort by `timestamp` + `actor`).              | Loss = audit gap; ordering is a UI / SIEM concern.                                                                                                                                                                                                                     |
+| Port            | Method                                                              | Required                                                                                                               | Why                                                                                                                                                                                                                                                                    |
+| --------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `TokenStore`    | `saveCode(code, payload, ttl)`                                      | **Strong, atomic.** Payload **encrypted at rest** with a key from `KeyStore`; `ttl ≤ 60 s` (framework refuses larger). | Code must be created exactly once and visible to the next `consumeCode` on any node. Payload may carry upstream tokens — see _Code payload confidentiality_ in plan.                                                                                                   |
+| `TokenStore`    | `consumeCode(code)`                                                 | **Strong, CAS.** Returns the **decrypted** payload on success.                                                         | Single-use; second consumption must fail deterministically. Race with itself must resolve to one winner.                                                                                                                                                               |
+| `TokenStore`    | `saveRefresh(refresh, payload)`                                     | **Strong, atomic.**                                                                                                    | New refresh tokens issued during rotation must be immediately retrievable on the next request.                                                                                                                                                                         |
+| `TokenStore`    | `consumeRefresh(refresh, options)`                                  | **Strong, CAS with reuse-detection window** (default 60 s).                                                            | Core of refresh-token rotation security. Concurrent presentations resolve to one winner; reuse within the window triggers the revoke chain.                                                                                                                            |
+| `TokenStore`    | `peekRefresh(refresh)`                                              | **Eventual acceptable.** Non-destructive read; must never mark the token consumed.                                     | Used by `/revoke` for token-to-client binding (RFC 7009 §2.2) and by the refresh-grant for client auth + audit fields. Race losers fall through to `consumeRefresh`, which is the strong gate, so a stale peek can only delay — not bypass — single-use enforcement.   |
+| `TokenStore`    | `revokeFamily(family)`                                              | Strong preferred; eventual acceptable with documented SLA.                                                             | Reuse-detection must invalidate the whole chain. Brief lag is tolerable.                                                                                                                                                                                               |
+| `TokenStore`    | `revokeBySubject(tenant, subject)`                                  | Strong preferred; eventual acceptable with documented SLA.                                                             | Revocation must propagate quickly. A few seconds of lag is tolerable.                                                                                                                                                                                                  |
+| `SessionStore`  | `saveFlow(flowId, payload, ttl)`                                    | **Strong, atomic.** `ttl == expiresAt - createdAt`.                                                                    | Flow record must be visible on the callback request to `consumeFlow`.                                                                                                                                                                                                  |
+| `SessionStore`  | `updateFlowMethodState(flowId, state)`                              | **Strong, atomic.** Resolves **before** the user-agent redirect is sent.                                               | Upstream PKCE verifier / nonce must be durably persisted before the redirect, otherwise the callback cannot validate.                                                                                                                                                  |
+| `SessionStore`  | `consumeFlow(flowId)`                                               | **Strong, atomic delete-on-read** that **returns the full `FlowRecord`** (`CAS` or `DELETE … RETURNING`).              | Single-use; concurrent consumption resolves to one winner. The record is returned so the framework can snapshot fields into the auth-code payload before disposal.                                                                                                     |
+| `SessionStore`  | `savePar(uri, payload, ttl)` (optional)                             | **Strong, atomic.** `ttl` default 60 s.                                                                                | RFC 9126 §3 — the PAR record must be visible to the next `consumePar` on any node. One-shot read.                                                                                                                                                                      |
+| `SessionStore`  | `consumePar(uri)` (optional)                                        | **Strong, atomic delete-on-read.**                                                                                     | RFC 9126 §4 — `request_uri` is single-use; concurrent presentations of the same uri resolve to one winner. Same semantics as `consumeFlow`.                                                                                                                            |
+| `SessionStore`  | `createSession / readSession / revokeSession` (optional long-lived) | **Strong.**                                                                                                            | Session creation must be immediately readable on the next request.                                                                                                                                                                                                     |
+| `SessionStore`  | `saveScratch / readScratch / deleteScratch` (optional)              | **Strong, TTL-respecting.** Implement the trio together; partial implementations are not supported.                    | Backs `MethodContext.methodScratch` for methods that need cross-flow per-instance state (e.g. SAML SP assertion-ID replay protection). Keys arrive already namespaced by `(tenantId, methodId)` — the adapter stores opaque key/value pairs.                           |
+| `TokenStore`    | `recordDpopJti(jti, ttlMs)` (optional)                              | **Strong, atomic record-or-fail.**                                                                                     | RFC 9449 §11.1 — replay protection requires single-use enforcement on the jti within the TTL window. A re-presentation must return `invalid_grant` deterministically. Adapters without this method cannot satisfy DPoP and the verifier surfaces `invalid_dpop_proof`. |
+| `KeyStore`      | `currentSigningKey()` / `currentEncryptionKey()`                    | Strong.                                                                                                                | Active key must be unambiguous.                                                                                                                                                                                                                                        |
+| `KeyStore`      | `signingKeys()` (JWKS)                                              | Eventual OK (with TTL).                                                                                                | Verifiers tolerate brief JWKS lag during rotation.                                                                                                                                                                                                                     |
+| `KeyStore`      | `getEncryptionKey(kid)`                                             | Strong.                                                                                                                | Required to decrypt code payloads encrypted under non-current keys during the overlap window.                                                                                                                                                                          |
+| `ConfigStore`   | `getTenantConfig(id)`                                               | **Eventual + bounded staleness (TTL ≤ 60 s).** Invalidation hook fires on update.                                      | Read-heavy, write-rare. Aggressive caching is desirable.                                                                                                                                                                                                               |
+| `ConfigStore`   | `putTenantConfig(config)`                                           | **Strong write + immediate invalidation** of cached entries for the affected `TenantId`.                               | Subsequent `getTenantConfig` must reflect the new value once the write resolves.                                                                                                                                                                                       |
+| `MethodStore`   | `getMethodConfig` / `listMethods`                                   | Same as `ConfigStore.getTenantConfig`.                                                                                 | Subset of tenant config.                                                                                                                                                                                                                                               |
+| `MethodStore`   | `putMethodConfig` / `deleteMethodConfig`                            | Strong write + immediate invalidation.                                                                                 | Console-driven mutations must take effect on the next request.                                                                                                                                                                                                         |
+| `AuditLog`      | `log(event)`                                                        | Append-only, durable. Cross-instance ordering **not** required (consumers sort by `timestamp` + `actor`).              | Loss = audit gap; ordering is a UI / SIEM concern.                                                                                                                                                                                                                     |
+| `ScimDirectory` | `createUser` / `replaceUser` / `patchUser` / `deleteUser`           | **Strong, read-your-writes.**                                                                                          | A SCIM client issues `GET /Users?filter=userName eq "…"` immediately after a create to confirm it; an eventually-consistent read there makes the client create the user a second time. Duplicate users are the classic SCIM failure and are painful to unpick.         |
+| `ScimDirectory` | `getUser` / `findUsers`                                             | **Read-your-writes for the tenant's own recent writes**; otherwise eventual is acceptable.                             | Same reason. Cross-tenant staleness is harmless — SCIM reads are always tenant-scoped.                                                                                                                                                                                 |
+| `ScimDirectory` | uniqueness of `userName`                                            | **Host-enforced.** Return `authError.conflict(...)` on collision.                                                      | The library stores no user rows, so it cannot enforce uniqueness. A host that checks-then-writes without a constraint will race under Okta's initial import, which is heavily concurrent.                                                                              |
 
 ## Implications for adapter choice
 
@@ -64,6 +68,12 @@ demonstrate, under simulated replication lag:
 2. `consumeRefresh` CAS resolves to exactly one winner under concurrent
    attempts on the same token.
 3. `revokeBySubject` propagates within the documented SLA.
+4. `readScratch` immediately after the matching `saveScratch` returns the
+   value. Scratch backs SAML SP InResponseTo replay protection: the
+   AuthnRequest is correlated at the ACS by a scratch read that must see
+   the write made when the request was issued. The D1 adapter pins all
+   three scratch operations to the primary via the Sessions API
+   (`primarySession`), the same path `consumeFlow` uses.
 
 Read-eventual paths (`ConfigStore.getTenantConfig`, JWKS) may use replicas
 freely.
@@ -93,6 +103,11 @@ The fixture set covers, at minimum:
   one-shot consume atomicity, expiry enforcement, ttl-0 rejection.
 - **DPoP jti (`recordDpopJti`)** — first record succeeds, replay within
   TTL fails with `invalid_grant`, post-TTL the slot is freed for reuse.
+- **Method scratch (`supportsScratch: true`)** — `saveScratch` /
+  `readScratch` / `deleteScratch` round-trip, overwrite semantics on
+  same key, expiry enforcement, idempotent `deleteScratch`, ttl-0
+  rejection. Keys are opaque to the adapter (the framework scopes them
+  upstream); a single test confirms that distinct keys are isolated.
 
 ## Optional methods and graceful degradation
 
@@ -110,6 +125,19 @@ caught up yet:
 does not support DPoP replay protection"`. Memory adapter
   implements; production adapters add it the same way `consumeRefresh`
   uses an atomic write-once primitive.
+- `SessionStore.saveScratch / readScratch / deleteScratch` — required
+  for methods that hold cross-flow per-instance state (SAML SP replay
+  protection is the first user). Without them,
+  `MethodContext.methodScratch.put/get/delete` returns an
+  `internal_error` whose description names the missing operation.
+  Memory **and all four production adapters** (Postgres, D1, DynamoDB,
+  Durable Object) implement the trio as a TTL-respecting key/value
+  store keyed by an opaque string; each is opted into the
+  `supportsScratch` conformance cases. Semantics are upsert /
+  TTL-filtered read / idempotent delete — there is no atomic
+  delete-on-read (unlike `consumeFlow`). On DynamoDB the row also
+  carries a native `ttl` attribute for backstop eviction, but reads
+  still filter on the adapter clock because native TTL is best-effort.
 
 The framework never advertises a feature in discovery that the wired
 adapters cannot actually serve: `pushed_authorization_request_endpoint`

package/src/ports/audit-log.ts

@@ -93,16 +93,29 @@ export type AuditEvent =
     }
   | {
       /**
-       * Emitted by `/end_session` (OIDC RP-Initiated Logout 1.0 §2) after
-       * processing the logout request — regardless of whether a
-       * `post_logout_redirect_uri` was supplied. `subjectId` is present
-       * when the request carried an `id_token_hint` that successfully
-       * verified; absent otherwise.
+       * Emitted after a logout is processed. Two channels, discriminated
+       * by `via`:
+       *
+       *  - `rp_initiated` (or absent — the default): `/end_session`
+       *    (OIDC RP-Initiated Logout 1.0 §2), regardless of whether a
+       *    `post_logout_redirect_uri` was supplied. `subjectId` present
+       *    when an `id_token_hint` verified; absent otherwise.
+       *  - `upstream_slo`: an upstream IdP notified us a federated
+       *    session ended (SAML front-channel Single Logout). `methodId`
+       *    / `methodKind` identify the federation connection;
+       *    `subjectId` present only when the host's `onLogout` returned
+       *    a subject to revoke.
+       *
+       * `via` is general (OIDC back-channel logout would reuse
+       * `upstream_slo`), not SAML-specific surface.
        */
       kind: "session_logout"
       tenantId: TenantId
       clientId?: string
       subjectId?: string
+      via?: "rp_initiated" | "upstream_slo"
+      methodId?: string
+      methodKind?: string
     }
   | {
       /**

package/src/ports/scim-directory.ts

@@ -0,0 +1,166 @@
+/**
+ * `ScimDirectory` — the host's user directory, as SCIM needs to see it.
+ *
+ * This is the boundary from `SCIM-AD2`: the library owns the SCIM
+ * protocol (routing, bearer auth, schema validation, PATCH
+ * normalization, error envelope, pagination, discovery docs) and the
+ * host owns every byte of persistence. The library stores no user data.
+ *
+ * That split is not a compromise — it is the same protocol-over-
+ * host-owned-state shape as `ConfigStore`, `MethodStore` and the
+ * `success` callback. The host's Users table is the host's.
+ *
+ * **Consistency:** read-your-writes is required. A SCIM client
+ * (notably Okta) will `GET /Users?filter=userName eq "…"` immediately
+ * after a `POST /Users` to confirm the create; an eventually-consistent
+ * read there produces duplicate users. See `ports/CONSISTENCY.md`.
+ *
+ * **Errors.** SCIM clients retry `5xx` and give up on `4xx`, so which
+ * error you return decides whether a failure is surfaced to an admin or
+ * retried forever:
+ *
+ *   - `authError.conflict(...)` → `409 uniqueness`. A collision only you
+ *     can detect, because only you store the rows.
+ *   - `authError.invalidRequest(...)` → `400 invalidValue`. A
+ *     **permanent** rejection — you understood the request and will
+ *     never accept it. Use it when `addMembers` names a user you do not
+ *     have (an IdP's group push can reference a member its user push
+ *     filtered out, or one deleted between operations), or when the data
+ *     violates a constraint you cannot satisfy.
+ *   - anything else → `500`, which the client retries. Correct for a
+ *     transient fault, and far better than reporting a success you did
+ *     not perform — but returning it for a permanent problem means the
+ *     IdP retries the same doomed request indefinitely.
+ *
+ * Your message is passed through on both `4xx` paths; it is what an IdP
+ * admin reads in the provisioning log, so make it specific.
+ */
+import type { Result } from "../types/result"
+import type {
+  ScimGroupPatch,
+  ScimGroupQuery,
+  ScimGroupRecord,
+  ScimGroupWrite,
+  ScimPage,
+  ScimUserPatch,
+  ScimUserQuery,
+  ScimUserRecord,
+  ScimUserWrite,
+} from "../types/scim"
+import type { TenantId } from "../types/tenant"
+
+export type ScimDirectory = {
+  /** `null` (not an error) when no user has that id in this tenant. */
+  getUser(
+    tenantId: TenantId,
+    id: string,
+  ): Promise<Result<ScimUserRecord | null>>
+
+  /**
+   * Query users. `query.startIndex` is 1-based and `query.count` is
+   * already clamped; `query.totalResults` in the response must be the
+   * full match count, not the page length.
+   */
+  findUsers(
+    tenantId: TenantId,
+    query: ScimUserQuery,
+  ): Promise<Result<ScimPage<ScimUserRecord>>>
+
+  /**
+   * Create a user. Return `conflict` if `userName` (or another
+   * uniqueness constraint of yours) is already taken — the library
+   * cannot check that for you.
+   */
+  createUser(
+    tenantId: TenantId,
+    user: ScimUserWrite,
+  ): Promise<Result<ScimUserRecord>>
+
+  /**
+   * Full replace (`PUT`). Attributes absent from `user` are cleared, per
+   * RFC 7644 §3.5.1 — this is a replace, not a merge. Use `patchUser`
+   * for partial updates.
+   */
+  replaceUser(
+    tenantId: TenantId,
+    id: string,
+    user: ScimUserWrite,
+  ): Promise<Result<ScimUserRecord>>
+
+  /**
+   * Apply a normalized delta. Present key ⇒ set; absent ⇒ leave alone;
+   * `null` ⇒ clear. The library has already resolved SCIM path
+   * expressions, so no parsing is needed here.
+   *
+   * `{ active: false }` is the ordinary deprovisioning signal and is
+   * usually the single most important operation to implement correctly.
+   */
+  patchUser(
+    tenantId: TenantId,
+    id: string,
+    patch: ScimUserPatch,
+  ): Promise<Result<ScimUserRecord>>
+
+  /**
+   * Hard delete (`DELETE`). Distinct from deactivation on purpose
+   * (`SCIM-AD8`): the library will not quietly turn a destructive
+   * request into a soft one. Hosts that do not want cascading deletes
+   * should implement this as a tombstone and say so in their runbook —
+   * but that decision is theirs to make explicitly, not the library's to
+   * make silently.
+   */
+  deleteUser(tenantId: TenantId, id: string): Promise<Result<void>>
+
+  // ─── Groups ───
+  //
+  // Optional as a set: a host that only needs user provisioning can omit
+  // all six, and `/scim/v2/Groups` then answers 501 instead of failing
+  // at runtime. Implement all of them or none — a half-implemented
+  // Groups surface fails an IdP's group push in confusing ways.
+
+  getGroup?(
+    tenantId: TenantId,
+    id: string,
+  ): Promise<Result<ScimGroupRecord | null>>
+
+  /**
+   * `query.excludeMembers` is set when the client asked for
+   * `excludedAttributes=members`. Honour it by not loading membership —
+   * Okta sets it while enumerating groups, and ignoring it turns a cheap
+   * listing into a fan-out read per group.
+   */
+  findGroups?(
+    tenantId: TenantId,
+    query: ScimGroupQuery,
+  ): Promise<Result<ScimPage<ScimGroupRecord>>>
+
+  createGroup?(
+    tenantId: TenantId,
+    group: ScimGroupWrite,
+  ): Promise<Result<ScimGroupRecord>>
+
+  /** Full replace, including membership. */
+  replaceGroup?(
+    tenantId: TenantId,
+    id: string,
+    group: ScimGroupWrite,
+  ): Promise<Result<ScimGroupRecord>>
+
+  /**
+   * Apply a normalized group delta.
+   *
+   * Exactly one membership shape arrives at a time: `members` (replace
+   * everything) or `addMembers` / `removeMembers` (incremental). The
+   * incremental form exists so a 20,000-member group does not have to be
+   * read and rewritten to add one person — see `SCIM-AD9`. Adding an
+   * existing member or removing an absent one must succeed quietly;
+   * IdPs retry and expect idempotence.
+   */
+  patchGroup?(
+    tenantId: TenantId,
+    id: string,
+    patch: ScimGroupPatch,
+  ): Promise<Result<ScimGroupRecord>>
+
+  deleteGroup?(tenantId: TenantId, id: string): Promise<Result<void>>
+}