@_mustachio/openauth 0.11.0 → 0.12.0

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

@@ -0,0 +1,306 @@
+/**
+ * Single Logout Service — the inbound front-channel logout half.
+ *
+ * Mounted as a **public** (anonymous, flowless) route at
+ * `GET|POST /m/<methodId>/sls` (declared in `AuthMethod.publicRoutes`
+ * only when `SamlSpConfig.idp.sloUrl` is configured — advertising an
+ * SLS we cannot complete would break interop, mirroring how
+ * `unsolicitedCallback` is gated on `idpInitiated`).
+ *
+ * Authenticity here is **cryptographic, not cookie-based** — exactly
+ * the SAML front-channel SLO model. node-saml verifies the inbound
+ * message's XML-DSig against the pinned IdP cert (`SAML-AD1` — we do
+ * not reimplement signature checking):
+ *
+ *   - **`SAMLRequest`** = an IdP-initiated `LogoutRequest`. Verify it,
+ *     emit a signed `LogoutResponse` redirect back to the IdP's SLO
+ *     endpoint, and return `MethodResult.challenge` carrying the
+ *     verified `logout` intent so the framework fires
+ *     `IdPOptions.onLogout` (host session teardown + optional
+ *     `revokeAllForSubject`). The method stays port-free; the
+ *     privileged side effect runs in the framework's public-route
+ *     pipeline (see `ARCHITECTURE.md` §"onLogout + challenge.logout").
+ *   - **`SAMLResponse`** = the IdP's `LogoutResponse` to an
+ *     SP-initiated `LogoutRequest`. Validated and acknowledged here;
+ *     the SP-initiated *send* path + post-logout redirect lands in the
+ *     next increment.
+ *
+ * Verification failures are controlled `denied` (bad/absent signature,
+ * unknown issuer, malformed message) — the same classification
+ * `acs.ts` uses. Misconfiguration / infra faults are `error`.
+ */
+import { authError } from "../../types/error"
+import type { MethodContext, MethodResult } from "../../types/method"
+import { isErr } from "../../types/result"
+
+import { buildSamlInstance, deriveSpEntityId } from "./saml-instance"
+import type { SamlSpConfig, SamlSpProperties, SamlSpState } from "./types"
+
+/** Minimal view of node-saml's `Profile` — never leaked publicly. */
+type NodeSamlProfile = {
+  nameID?: string
+  sessionIndex?: string
+  /** The inbound message's `ID` — used for front-channel replay dedup. */
+  ID?: string
+}
+
+/**
+ * Replay-dedup horizon for a verified `LogoutRequest`. A SAML
+ * `LogoutRequest` usually carries no `NotOnOrAfter`, so unlike the
+ * assertion path there is no message-supplied expiry to track — a
+ * fixed, clamped window is sufficient (logout is idempotent; this only
+ * suppresses a signed-message replay storm).
+ */
+const SLO_REPLAY_HORIZON_MS = 10 * 60_000
+
+export async function consumeSls(
+  ctx: MethodContext<SamlSpState>,
+  methodId: string,
+  config: SamlSpConfig,
+): Promise<MethodResult<SamlSpProperties, SamlSpState>> {
+  // Public route: no flow, but the HTTP layer supplies dispatch so we
+  // can derive the stable SP entityID (same derivation as AuthnRequest
+  // / ACS / metadata — no drift).
+  if (!ctx.dispatch) {
+    return {
+      kind: "error",
+      error: authError.internalError(
+        "saml-sp: /sls dispatched without issuer context (ctx.dispatch is null)",
+      ),
+    }
+  }
+  if (!config.idp.sloUrl) {
+    // Should be unreachable: /sls is only public when sloUrl is set.
+    return {
+      kind: "error",
+      error: authError.internalError(
+        "saml-sp: /sls reached with no idp.sloUrl configured",
+      ),
+    }
+  }
+
+  const spEntityId = deriveSpEntityId(
+    ctx.dispatch.issuerUrl,
+    ctx.tenant.id,
+    methodId,
+  )
+
+  // Read both bindings: HTTP-Redirect (GET, signed query string) and
+  // HTTP-POST (form body). The raw query string is required to verify a
+  // redirect-binding signature (it is computed over the exact bytes).
+  const url = new URL(ctx.request.url)
+  const originalQuery = url.search.replace(/^\?/, "")
+  let samlRequest: string | null
+  let samlResponse: string | null
+  let relayState: string | null
+  const isPost = ctx.request.method.toUpperCase() === "POST"
+  let postForm: URLSearchParams | null = null
+  try {
+    if (isPost) {
+      postForm = new URLSearchParams(await ctx.request.text())
+      samlRequest = postForm.get("SAMLRequest")
+      samlResponse = postForm.get("SAMLResponse")
+      relayState = postForm.get("RelayState")
+    } else {
+      samlRequest = url.searchParams.get("SAMLRequest")
+      samlResponse = url.searchParams.get("SAMLResponse")
+      relayState = url.searchParams.get("RelayState")
+    }
+  } catch {
+    return {
+      kind: "error",
+      error: authError.internalError("saml-sp: /sls could not read request"),
+    }
+  }
+
+  if (!samlRequest && !samlResponse) {
+    return { kind: "denied", reason: "missing SAMLRequest / SAMLResponse" }
+  }
+
+  // Building the verifier is a configuration concern (e.g. no IdP
+  // signing cert within its validity window) — an operator fault, not a
+  // per-user auth failure. Sign logout messages whenever a per-
+  // connection SP key is configured (decoupled from `signAuthnRequest`,
+  // which is specifically about the AuthnRequest).
+  let saml: ReturnType<typeof buildSamlInstance>
+  try {
+    saml = buildSamlInstance(
+      config,
+      {
+        spEntityId,
+        acsUrl: ctx.dispatch.callbackUrl,
+        scratch: ctx.methodScratch,
+        logoutUrl: config.idp.sloUrl,
+        logout: true,
+        ...(config.signingKey
+          ? {
+              signing: {
+                privateKeyPem: config.signingKey.privateKeyPem,
+                certPem: config.signingKey.certPem,
+              },
+            }
+          : {}),
+      },
+      Date.now(),
+    )
+  } catch (e) {
+    return {
+      kind: "error",
+      error: authError.internalError(
+        `saml-sp: cannot construct logout verifier: ${
+          e instanceof Error ? e.message : String(e)
+        }`,
+        e,
+      ),
+    }
+  }
+
+  // ---- IdP-initiated LogoutRequest (the Phase 3 deliverable) --------
+  if (samlRequest) {
+    let profile: NodeSamlProfile | null
+    try {
+      const res = isPost
+        ? await saml.validatePostRequestAsync({
+            SAMLRequest: samlRequest,
+            ...(relayState !== null ? { RelayState: relayState } : {}),
+          })
+        : await saml.validateRedirectAsync(
+            Object.fromEntries(url.searchParams) as Record<string, string>,
+            originalQuery,
+          )
+      profile = res.profile as NodeSamlProfile | null
+    } catch (e) {
+      // Bad/absent signature, unknown issuer, malformed LogoutRequest —
+      // controlled, not a server fault. Same posture as the ACS.
+      return {
+        kind: "denied",
+        reason: `logout request rejected: ${
+          e instanceof Error ? e.message : String(e)
+        }`,
+      }
+    }
+    if (!profile) {
+      return { kind: "denied", reason: "logout request produced no profile" }
+    }
+    // Fail-closed: the replay guard below is load-bearing (it stops a
+    // captured validly-signed LogoutRequest from repeatedly driving
+    // onLogout/revokeAllForSubject). node-saml v5.1.0 already throws
+    // before returning a profile when `@ID` is absent, so this is
+    // unreachable for a conformant message — but asserting it here
+    // makes the documented fail-closed posture true in code rather
+    // than silently dependent on an upstream library invariant
+    // (mirrors the IdP-init assertion-replay handling in acs.ts).
+    if (!profile.ID) {
+      return {
+        kind: "error",
+        error: authError.internalError(
+          "saml-sp: LogoutRequest carries no @ID — front-channel replay " +
+            "protection cannot be established. Refusing to process.",
+        ),
+      }
+    }
+
+    // Front-channel replay dedup on the verified LogoutRequest @ID.
+    // Logout is idempotent so the blast radius is low, but a replayed
+    // signed message should not repeatedly drive revocation.
+    {
+      const key = `slo-replay:${profile.ID}`
+      const seen = await ctx.methodScratch.get(key)
+      if (seen.ok) {
+        return {
+          kind: "denied",
+          reason: "logout request replay detected (request ID already seen)",
+        }
+      }
+      const recorded = await ctx.methodScratch.put(
+        key,
+        "1",
+        SLO_REPLAY_HORIZON_MS,
+      )
+      if (isErr(recorded)) {
+        return {
+          kind: "error",
+          error: authError.internalError(
+            "saml-sp: could not record LogoutRequest ID for replay protection",
+          ),
+        }
+      }
+    }
+
+    // Emit the signed LogoutResponse redirect back to the IdP's SLO
+    // endpoint (success status — we always honour a validly-signed
+    // logout). node-saml uses `logoutUrl` (set above) as the target and
+    // echoes `InResponseTo` from the request profile.
+    let logoutResponseUrl: string
+    try {
+      logoutResponseUrl = await saml.getLogoutResponseUrlAsync(
+        // node-saml's Profile shape; our minimal view is structurally
+        // compatible for response generation (it reads ID / issuer).
+        profile as never,
+        relayState ?? "",
+        {},
+        true,
+      )
+    } catch (e) {
+      return {
+        kind: "error",
+        error: authError.internalError(
+          `saml-sp: failed to build LogoutResponse: ${
+            e instanceof Error ? e.message : String(e)
+          }`,
+          e,
+        ),
+      }
+    }
+
+    return {
+      kind: "challenge",
+      response: new Response(null, {
+        status: 302,
+        headers: { location: logoutResponseUrl },
+      }),
+      // Triggers the framework's onLogout side effect (host teardown +
+      // optional revokeAllForSubject) before the redirect is returned.
+      logout: {
+        ...(profile.nameID !== undefined ? { nameId: profile.nameID } : {}),
+        ...(profile.sessionIndex !== undefined
+          ? { sessionIndex: profile.sessionIndex }
+          : {}),
+      },
+    }
+  }
+
+  // ---- IdP LogoutResponse (SP-initiated completion) ----------------
+  // The SP-initiated *send* path + post-logout redirect lands in the
+  // next increment; here we validate the IdP confirmed logout and
+  // acknowledge. No `logout` side effect — SP-initiated revocation
+  // happens at the trigger, not on the return leg.
+  try {
+    if (isPost) {
+      await saml.validatePostResponseAsync({
+        SAMLResponse: samlResponse as string,
+        ...(relayState !== null ? { RelayState: relayState } : {}),
+      })
+    } else {
+      await saml.validateRedirectAsync(
+        Object.fromEntries(url.searchParams) as Record<string, string>,
+        originalQuery,
+      )
+    }
+  } catch (e) {
+    return {
+      kind: "denied",
+      reason: `logout response rejected: ${
+        e instanceof Error ? e.message : String(e)
+      }`,
+    }
+  }
+
+  return {
+    kind: "challenge",
+    response: new Response("Logged out.", {
+      status: 200,
+      headers: { "content-type": "text/plain" },
+    }),
+  }
+}

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

@@ -0,0 +1,203 @@
+/**
+ * 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
+}
+
+/**
+ * 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
+  raw: {
+    responseXml: string
+  }
+}

package/src/ports/CONSISTENCY.md

@@ -30,6 +30,7 @@ overspecifies adapters that don't need that on the read-eventual paths
 | `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.                                                                                                                                                                                                                     |
@@ -64,6 +65,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 +100,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 +122,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/session-store.ts

@@ -101,6 +101,34 @@ export type SessionStore = {
     ttl: number,
   ): Promise<Result<void>>
   consumePar?(requestUri: string): Promise<Result<ParRecord>>
+
+  /**
+   * Optional: per-method-instance scratch storage. Survives across flows
+   * (unlike `methodState`, which is per-flow). Use cases include cross-flow
+   * deduplication state — e.g., a SAML SP method remembering recently-seen
+   * assertion IDs for replay protection.
+   *
+   * The framework scopes keys per `(tenantId, methodId)` before calling
+   * these — adapters see opaque, already-namespaced keys and store the
+   * UTF-8 string value verbatim. Methods JSON-encode if they want object
+   * state.
+   *
+   * Strong consistency + TTL respect (same semantics as flow records).
+   * `readScratch` returns `unknown_state` if the key is missing or
+   * expired. `deleteScratch` is idempotent.
+   *
+   * Adapters without these methods cannot host methods that depend on
+   * scratch; the framework surfaces a clear `unsupported` error through
+   * `MethodContext.methodScratch` at call time. Implement all three
+   * methods together — partial implementations are not supported.
+   */
+  saveScratch?(
+    key: string,
+    value: string,
+    ttlMs: number,
+  ): Promise<Result<void>>
+  readScratch?(key: string): Promise<Result<string>>
+  deleteScratch?(key: string): Promise<Result<void>>
 }
 
 /**