@_mustachio/openauth 0.9.2 → 0.11.0

package/src/types/method.ts

@@ -0,0 +1,270 @@
+/**
+ * `AuthMethod` — the core pluggable authentication abstraction.
+ *
+ * AD2: methods are **data + handler functions**, not framework modules. They
+ * depend on Web Fetch `Request`/`Response` (Web standards available on every
+ * runtime) and on a small `MethodContext` of plain data. The full allowed
+ * import set for files under `src/methods/` is `src/types/`,
+ * `src/domain/crypto`, `src/ui/forms`, sibling `src/methods/*`, and
+ * method-specific third-party libraries (e.g. `zod`,
+ * `@simplewebauthn/server`); methods MUST NOT import from `src/http/`,
+ * `src/adapters/`, or `src/ports/`, and never from Hono or any other HTTP
+ * framework. This `types/method.ts` file in particular is enforced
+ * framework-import-free by CI lint. See ARCHITECTURE.md §"Methods plug
+ * in alongside this stack" for the full contract.
+ *
+ * Cookies and other policy-sensitive response headers are returned as data
+ * (`SetCookie[]`, `CachePolicy`) and applied to the final `Response` by the
+ * HTTP layer. The HTTP layer also strips a fixed allowlist-violating set of
+ * headers from method-returned `Response` instances (`Set-Cookie`, security
+ * headers, `Cache-Control`) so methods cannot bypass framework policy. See
+ * `ARCHITECTURE.md` §"Response sanitization".
+ */
+import type { v1 } from "@standard-schema/spec"
+
+import type { AuthError } from "./error"
+import type { FlowRecord } from "./flow"
+import type { Result } from "./result"
+import type { MethodType, TenantContext, TenantId } from "./tenant"
+
+/**
+ * A built, ready-to-dispatch auth method instance for a particular tenant.
+ *
+ * Generics:
+ *   - `P`: properties type emitted to the user's `success` callback on a
+ *     successful authentication. Typed per method.
+ *   - `S`: method-private state stashed in `FlowRecord.methodState`. Opaque
+ *     to the framework; the method reads and writes it through
+ *     `MethodContext.methodState` and `MethodResult.challenge.saveMethodState`.
+ */
+export type AuthMethod<P = unknown, S = unknown> = {
+  /**
+   * Tenant-local instance id. Populated by the factory from
+   * `MethodConfig.id`. The framework dispatches URL routes by this value.
+   */
+  id: string
+  /**
+   * Factory kind. Populated by the factory from `MethodConfig.kind`. Used to
+   * tell the user's `success` callback which provider produced the result.
+   */
+  kind: string
+  type: MethodType
+  /**
+   * Routes the method declares. Key format: `"GET /authorize"`,
+   * `"POST /callback"`, etc. The HTTP layer mounts these under
+   * `/<AuthMethod.id>/*` (tenant-local instance id, so two instances of the
+   * same factory get distinct URL spaces).
+   */
+  routes: Record<string, MethodHandler<P, S>>
+  /**
+   * Token-exchange function for the `/token` endpoint when the method
+   * participates in client-credentials-style flows (e.g. `m2m`). Most
+   * redirect-based methods do not set this.
+   */
+  client?: ClientFn<P>
+}
+
+export type MethodHandler<P, S> = (
+  ctx: MethodContext<S>,
+) => Promise<MethodResult<P, S>>
+
+/**
+ * Per-request context handed to a method handler.
+ *
+ * Methods **do not** receive raw `MethodConfig.config`. The factory captured
+ * the validated config via closure in `build`, so the handler only sees
+ * request-scoped data here.
+ *
+ * `cookies` is `ReadonlyMap` because methods don't get to mutate the
+ * incoming cookie jar — they return `SetCookie[]` instructions and the
+ * framework applies them.
+ */
+export type MethodContext<S = unknown> = {
+  /** The raw Web Fetch `Request`. Web standard, not Hono `Context`. */
+  request: Request
+  /** Path within the method's mount, e.g. `"/callback"` (without the `/<id>` prefix). */
+  subPath: string
+  tenant: TenantContext
+  /** `null` while `/authorize` is being initiated; populated on callback. */
+  flow: FlowRecord | null
+  /**
+   * Shortcut to `flow?.methodState`, narrowed to this method's `S` generic.
+   * `null` when there is no flow yet or no state has been written.
+   */
+  methodState: S | null
+  /** Parsed cookies from the incoming `Request`. Read-only. */
+  cookies: ReadonlyMap<string, string>
+  /**
+   * Framework-supplied dispatch data. Populated for the `GET /authorize`
+   * initiation so the method can build an upstream redirect carrying the
+   * framework-minted state envelope; `null` for callback handlers (the
+   * framework has already verified `state` and the flow record by then,
+   * and the relevant data is on `flow`).
+   */
+  dispatch: MethodDispatchData | null
+}
+
+/** Framework-supplied data available to the method at `/authorize` time. */
+export type MethodDispatchData = {
+  /**
+   * The MAC-signed state envelope the method must include in any upstream
+   * redirect. Opaque to the method.
+   */
+  state: string
+  /**
+   * Fully qualified callback URL the upstream provider should redirect to.
+   * Methods include this as `redirect_uri` (OAuth) or its equivalent.
+   */
+  callbackUrl: string
+  /** The issuer URL of this IdP. Methods may include in upstream OIDC requests. */
+  issuerUrl: string
+}
+
+/**
+ * Discriminated union returned by a `MethodHandler`. The HTTP layer applies
+ * the result: rendering the challenge response, kicking off token issuance
+ * on success, or surfacing the error.
+ */
+export type MethodResult<P = unknown, S = unknown> =
+  /**
+   * Render UI / redirect to upstream / otherwise pause the flow waiting for
+   * the user agent. `setCookies` is applied via the framework's serializer
+   * (which enforces `Secure`, `SameSite`, `HttpOnly` defaults).
+   * `saveMethodState` is merged into `FlowRecord.methodState` and persisted
+   * **before** the response is sent — the user agent never sees the
+   * upstream redirect until the upstream verifier / nonce / state is
+   * durably saved.
+   */
+  | {
+      kind: "challenge"
+      /** Body + non-policy headers. Policy-sensitive headers are stripped. */
+      response: Response
+      setCookies?: SetCookie[]
+      saveMethodState?: S
+      /** Serialized into a `Cache-Control` header by the framework. */
+      cache?: CachePolicy
+    }
+  /**
+   * Authentication succeeded. The HTTP layer hands `providerSubject` +
+   * `properties` to the user's `IdPOptions.success` callback to mint the
+   * final `SubjectClaim`. Methods never construct the final subject.
+   */
+  | {
+      kind: "success"
+      /** Upstream system's stable identifier for the authenticated principal. */
+      providerSubject: string
+      properties: P
+      setCookies?: SetCookie[]
+    }
+  /** User refused / failed auth in a non-error way (e.g. consent declined). */
+  | { kind: "denied"; reason: string; setCookies?: SetCookie[] }
+  /** Method hit an error. The HTTP layer maps to a standards-compliant response. */
+  | { kind: "error"; error: AuthError }
+
+/**
+ * Cache policy for `MethodResult.challenge`. Methods do **not** set
+ * `Cache-Control` directly — the framework strips that header from any
+ * method-returned `Response`. Opt in to caching via this typed field; the
+ * framework serializes it.
+ */
+export type CachePolicy = {
+  /** Seconds. `0` ≡ `no-store`. Default for auth UI. */
+  maxAge?: number
+  /** Shared (CDN) cache TTL. */
+  sMaxAge?: number
+  /** Adds `Cache-Control: private`. */
+  isPrivate?: boolean
+  /** For static assets only. */
+  immutable?: boolean
+}
+
+/**
+ * Cookie instruction returned from a method, applied by the framework's
+ * cookie serializer. Defaults enforced: `Secure` in production, `SameSite`
+ * defaults to `Lax`, `HttpOnly` defaults to true for any cookie name in the
+ * framework's reserved namespace (`auth.*` / `idp.*`).
+ */
+export type SetCookie = {
+  name: string
+  /** `null` clears the cookie (`Max-Age=0`). */
+  value: string | null
+  maxAge?: number
+  path?: string
+  domain?: string
+  httpOnly?: boolean
+  secure?: boolean
+  sameSite?: "lax" | "strict" | "none"
+}
+
+/**
+ * Token-exchange function for methods that participate in `/token`
+ * (currently just `m2m`). Returns the same `P` properties shape as a
+ * `MethodResult.success`.
+ */
+export type ClientFn<P> = (input: {
+  clientID: string
+  clientSecret: string
+  params: Record<string, string>
+}) => Promise<Result<P, AuthError>>
+
+/**
+ * Factory that turns a tenant's per-method config into an `AuthMethod`.
+ *
+ * The factory owns config validation. The framework validates
+ * `MethodConfig.config` against `configSchema` before calling `build`;
+ * methods never observe `Record<string, unknown>` at runtime.
+ *
+ * `build` may be async (e.g. to fetch an OIDC discovery doc / JWKS). The
+ * result is cached per `(tenantId, MethodConfig.id)` — TTL matches the
+ * `ConfigStore` cache TTL; invalidation fires when tenant config changes.
+ *
+ * The framework verifies the returned `AuthMethod.id` and `AuthMethod.kind`
+ * match the `input.id` / `input.kind` passed into `build`. Mismatch fails
+ * the load with audit `factory_id_mismatch`.
+ */
+// `AnyAuthMethodFactory` is the variance-permissive form used by
+// `IdPOptions.methods` and `MethodCache.factories`. Each entry in such a
+// map may be a `AuthMethodFactory<P, S, Cfg>` with concrete generics —
+// the `any` defaults keep the map type assignable without losing strict
+// typing inside individual factories.
+export type AnyAuthMethodFactory = AuthMethodFactory<
+  any, // P — properties emitted to success callback
+  any, // S — method-private state
+  any // Cfg — tenant-supplied config (validated by configSchema)
+>
+
+export type AuthMethodFactory<P = unknown, S = unknown, Cfg = unknown> = {
+  /** Matches `MethodConfig.kind`. Multiple `MethodConfig` rows may share the same `kind`. */
+  kind: string
+
+  /**
+   * Standard Schema for the tenant-supplied config blob. The framework
+   * runs this after `ConfigStore` returns a tenant's `MethodConfig.config`
+   * and rejects loads that don't validate (audit + log). The validated
+   * value is threaded into `build`.
+   *
+   * Any validation library implementing [Standard Schema v1] satisfies
+   * this contract — Zod 3.24+, Valibot 1.0+, Arktype 2.0+, Effect Schema,
+   * etc. This decouples the library from any one validator's version
+   * choices.
+   *
+   * [Standard Schema v1]: https://github.com/standard-schema/standard-schema
+   */
+  configSchema: v1.StandardSchema<unknown, Cfg>
+
+  /**
+   * Build a concrete `AuthMethod` from validated config plus the binding
+   * context. The factory **must** set `AuthMethod.id` to `input.id` and
+   * `AuthMethod.kind` to `input.kind` — the framework verifies and audits
+   * on mismatch (`factory_id_mismatch`).
+   */
+  build: (input: {
+    /** `MethodConfig.id` — tenant-local instance id, becomes `AuthMethod.id`. */
+    id: string
+    /** `MethodConfig.kind` — factory id, becomes `AuthMethod.kind`. */
+    kind: string
+    tenantId: TenantId
+    /** Validated against `configSchema`. */
+    config: Cfg
+  }) => Promise<AuthMethod<P, S>>
+}

package/src/types/picker.ts

@@ -0,0 +1,32 @@
+/**
+ * Public-surface types for the default provider picker and any
+ * host-supplied override (`IdPOptions.renderPicker`). Kept under `types/`
+ * — separate from `ui/picker.ts` which holds the default renderer — so
+ * the public-API layer doesn't depend on the UI implementation file.
+ */
+
+/** Minimal shape of a method as seen by the picker. */
+export type PickerMethod = {
+  /** Tenant-local id (e.g. "google-workspace"). Goes into method_id. */
+  id: string
+  /** Factory kind (e.g. "google"). Identifies the provider family. */
+  kind: string
+  /** "redirect" for upstream OAuth/OIDC, "credential" for password/code/passkey. */
+  type: string
+  /** Optional human-readable label provided by tenant config. */
+  displayName?: string
+}
+
+/** Query params propagated into each picker option's link. */
+export type PickerContext = {
+  clientId: string
+  redirectUri: string
+  state?: string | null
+  scope?: string | null
+  nonce?: string | null
+  codeChallenge?: string | null
+  codeChallengeMethod?: string | null
+  audience?: string | null
+  prompt?: string | null
+  uiLocales?: string | null
+}

package/src/types/result.ts

@@ -0,0 +1,23 @@
+/**
+ * Result<T, E> — explicit success / failure encoding used throughout the domain.
+ *
+ * Domain functions return `Result` instead of throwing. The HTTP layer is the
+ * one place that converts `AuthError` into an HTTP response. Keeping the domain
+ * throw-free makes composition (chaining validators, branching on error code)
+ * straightforward and avoids hidden control flow.
+ *
+ * AD5 in `docs/plans/claude/idp-rebuild-plan.md`.
+ */
+import type { AuthError } from "./error"
+
+export type Result<T, E = AuthError> =
+  | { ok: true; value: T }
+  | { ok: false; error: E }
+
+export const ok = <T>(value: T): Result<T, never> => ({ ok: true, value })
+export const err = <E>(error: E): Result<never, E> => ({ ok: false, error })
+
+export const isOk = <T, E>(r: Result<T, E>): r is { ok: true; value: T } =>
+  r.ok === true
+export const isErr = <T, E>(r: Result<T, E>): r is { ok: false; error: E } =>
+  r.ok === false

package/src/types/subject.ts

@@ -0,0 +1,50 @@
+/**
+ * Subject — the typed principal the IdP issues at the end of an auth flow.
+ *
+ * Per AD4 / plan §"Subject", Zod is the canonical schema library. The
+ * subject schema type is library-agnostic at the boundary (any schema that
+ * implements the [Standard Schema v1] spec — including Zod 3.24+, Valibot,
+ * and Arktype) so existing consumers can migrate from Valibot/Arktype
+ * without rewriting subject definitions.
+ *
+ * [Standard Schema v1]: https://github.com/standard-schema/standard-schema
+ */
+import type { v1 } from "@standard-schema/spec"
+
+/**
+ * Map of subject-type id → schema for that subject's `properties`.
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod"
+ *
+ * const subjects: SubjectSchema = {
+ *   user:  z.object({ userId: z.string(), email: z.string().email() }),
+ *   admin: z.object({ adminId: z.string(), roles: z.array(z.string()) }),
+ * }
+ * ```
+ */
+export type SubjectSchema = Record<string, v1.StandardSchema>
+
+/**
+ * Helper that infers the discriminated-union `{ type, properties }` shape
+ * from a `SubjectSchema`. Used to type the IdP's `success` callback return
+ * and the access-token `claim` payload.
+ */
+export type SubjectPayload<T extends SubjectSchema> = {
+  [type in keyof T & string]: {
+    type: type
+    properties: v1.InferOutput<T[type]>
+  }
+}[keyof T & string]
+
+/**
+ * Generic typed-subject claim — what the user's `IdPOptions.success`
+ * callback returns and what is inlined as `claim` on the access token.
+ *
+ * Domain / port signatures keep the generic open (`SubjectClaim`) so the
+ * framework doesn't need to know each consumer's subject schema. Concrete
+ * call sites narrow `T extends SubjectSchema` for type safety.
+ */
+export type SubjectClaim<T extends SubjectSchema = SubjectSchema> =
+  SubjectPayload<T>

package/src/types/tenant.ts

@@ -0,0 +1,285 @@
+/**
+ * Tenant model + tenant-resolution / callback-recovery types.
+ *
+ * Per AD1, tenancy is **not** a URL concept. A tenant is whatever the
+ * user-supplied `resolveTenant(req)` says it is for an incoming request, plus
+ * a deterministic callback-recovery chain (MAC-bound state, partitioned host,
+ * or `flowId`-in-URI) for the post-redirect leg where the original tenant
+ * signal may no longer be available.
+ *
+ * The minimal state envelope MACed and round-tripped through upstream
+ * providers carries only `{ tenantId, flowId, nonce, kid }`. Everything else
+ * lives in the server-side `FlowRecord` (see `./flow.ts`).
+ */
+
+/**
+ * Branded tenant id — **opaque to the framework**.
+ *
+ * The framework treats `TenantId` as a comparable string and nothing more.
+ * It never parses it, never assumes a hierarchy or naming convention, never
+ * imposes uniqueness rules, never knows the lifecycle of a tenant. The
+ * embedding application decides what a tenant *is* (an organization, a
+ * workspace, an App-Tenant tuple, a customer, …) and supplies a
+ * `resolveTenant(req)` that maps incoming requests to the right key.
+ *
+ * Common embedding pattern when the host application has two levels of
+ * scoping (e.g. `App` ⇒ `App-Tenant`): encode the tuple into the key.
+ *
+ * ```ts
+ * // Inside the host application's resolveTenant:
+ * return ok(`${app.id}:${appTenant?.id ?? "__default__"}` as TenantId)
+ *
+ * // Inside the host application's ConfigStore.getTenantConfig:
+ * const [appId, subId] = (id as string).split(":")
+ * // merge App defaults + App-Tenant overrides from your own DB ...
+ * ```
+ *
+ * The brand exists to keep arbitrary `string` values from being passed
+ * where a `TenantId` is expected; the *meaning* of the string is the host
+ * application's concern.
+ */
+export type TenantId = string & { readonly __brand: "TenantId" }
+
+/**
+ * Cast helper for code that mints `TenantId` from a validated string. The
+ * framework imposes no validation on the value — callers ensure their key
+ * is non-empty and stable per partition.
+ */
+export const asTenantId = (value: string): TenantId => value as TenantId
+
+/** OAuth 2.1 grant types in scope for this IdP. Implicit is intentionally absent. */
+export type GrantType =
+  | "authorization_code"
+  | "refresh_token"
+  | "client_credentials"
+
+/**
+ * `MethodType` is the canonical discriminator for an `AuthMethod`. It mirrors
+ * the existing provider taxonomy. The UI uses it to decide which selection /
+ * form to render; the framework uses it as a routing / dispatch hint.
+ */
+export type MethodType =
+  | "oauth2"
+  | "oidc"
+  | "password"
+  | "code"
+  | "m2m"
+  | "passkey"
+  | "custom"
+
+/**
+ * Per-tenant configuration for a single auth method **instance**.
+ *
+ * `id` is the **tenant-local instance id** — the value that ends up in URLs
+ * (`/<id>/*`) and that the framework dispatches by.
+ *
+ * `kind` is the **factory id** — the value that selects which
+ * `AuthMethodFactory` builds this instance. A tenant may register multiple
+ * instances of the same factory (e.g. one Google Workspace SSO and one
+ * consumer Google Sign-In) by giving each instance a unique `id` while
+ * sharing a `kind`.
+ *
+ * `type` is the `MethodType` discriminator the UI uses. The framework
+ * verifies it agrees with the factory's declared type at load time.
+ *
+ * `config` is the tenant-supplied configuration blob. The framework validates
+ * it against the factory's Zod `configSchema` before any handler runs.
+ */
+export type MethodConfig = {
+  id: string
+  kind: string
+  type: MethodType
+  enabled: boolean
+  config: Record<string, unknown>
+}
+
+/** Optional theme metadata. Schema expanded in later phases. */
+export type ThemeConfig = {
+  primary?: string
+  logo?: string
+  favicon?: string
+  background?: string
+  font?: string
+}
+
+/**
+ * Registered OAuth client of this IdP (an app, SPA, mobile, M2M).
+ *
+ * Phase 8: split into a discriminated union so misconfiguration is a type
+ * error, not a runtime check. The runtime in `domain/authorize.ts` still
+ * enforces PKCE for public clients defensively, but hosts will see the
+ * problem at compile time.
+ *
+ * - **Public clients** (SPAs, mobile apps, native apps): no client secret;
+ *   `pkceRequired` is the literal `true`. PKCE is non-negotiable per
+ *   OAuth 2.1 BCP §2.1.1.
+ * - **Confidential clients** (server-side apps, M2M): `secretHash` is
+ *   required (this used to be optional, in practice always set). PKCE
+ *   recommended but may be disabled by the host.
+ */
+export type ClientConfig = PublicClientConfig | ConfidentialClientConfig
+
+export type PublicClientConfig = {
+  id: string
+  name: string
+  type: "public"
+  redirectUris: string[]
+  grantTypes: GrantType[]
+  scopes: string[]
+  /** Must be `true` for public clients per OAuth 2.1 §2.1.1. */
+  pkceRequired: true
+  /**
+   * Registered URIs to which `/end_session` may redirect after RP-initiated
+   * logout (OIDC RP-Initiated Logout 1.0 §2). Exact-match. If absent, the
+   * `/end_session` endpoint refuses any `post_logout_redirect_uri`.
+   */
+  postLogoutRedirectUris?: string[]
+  /**
+   * RFC 9126 §2: when `true`, the client MUST use Pushed Authorization
+   * Requests; a direct `GET /authorize` call without `request_uri` is
+   * rejected with `invalid_request`.
+   */
+  requirePushedAuthorizationRequests?: boolean
+  /**
+   * OIDC Core §8.1 — when set, the subject identifier (`sub`) is derived
+   * as a pairwise pseudonym keyed by this string. Two clients sharing
+   * the same `sectorIdentifier` will see the same `sub`; different
+   * values yield different `sub`s for the same end user. Absent =
+   * public subject (sub is identical across all RPs).
+   */
+  sectorIdentifier?: string
+  /** Phase 8. */
+  dpopRequired?: boolean
+}
+
+export type ConfidentialClientConfig = {
+  id: string
+  name: string
+  type: "confidential"
+  /** Hash of the client secret. Required for confidential clients. */
+  secretHash: string
+  redirectUris: string[]
+  grantTypes: GrantType[]
+  scopes: string[]
+  /**
+   * Default true. Disabling it is permitted for confidential clients but
+   * strongly discouraged; OAuth 2.1 §2.1.1 recommends PKCE for every client.
+   */
+  pkceRequired: boolean
+  /**
+   * Registered URIs to which `/end_session` may redirect after RP-initiated
+   * logout (OIDC RP-Initiated Logout 1.0 §2). Exact-match.
+   */
+  postLogoutRedirectUris?: string[]
+  /**
+   * RFC 9126 §2: when `true`, the client MUST use Pushed Authorization
+   * Requests; a direct `GET /authorize` call without `request_uri` is
+   * rejected with `invalid_request`.
+   */
+  requirePushedAuthorizationRequests?: boolean
+  /**
+   * OIDC Core §8.1 — see `PublicClientConfig.sectorIdentifier` for
+   * semantics. Same field; duplicated on each branch because the
+   * `ClientConfig` discriminated union doesn't share optional fields.
+   */
+  sectorIdentifier?: string
+  /** Phase 8. */
+  dpopRequired?: boolean
+}
+
+export type TenantConfig = {
+  id: TenantId
+  displayName: string
+  clients: ClientConfig[]
+  methods: MethodConfig[]
+  theme?: ThemeConfig
+  /** Set when the tenant needs cross-subdomain SSO. */
+  cookieDomain?: string
+  /** Override default refresh-token TTL (seconds). */
+  refreshTtl?: number
+  /** Override default access-token TTL (seconds). */
+  accessTtl?: number
+}
+
+/**
+ * Per-request tenant context handed to methods and the user-supplied
+ * `success` callback. `request.raw` is the Web Fetch `Request` the framework
+ * received; `request.custom` is whatever the host returned from the
+ * `IdPOptions.buildCustomContext` hook (request id, decoded JWT claims, mTLS
+ * cert info, geo hints — anything per-request that methods or `success`
+ * should see). Without the hook the blob is `{}`. The same blob is also
+ * persisted on the `FlowRecord` at `/authorize` time so it survives the
+ * upstream redirect and re-presents on the callback side.
+ */
+export type TenantContext = {
+  id: TenantId
+  config: TenantConfig
+  request: {
+    raw: Request
+    custom: Record<string, unknown>
+  }
+}
+
+/**
+ * Outcome of the framework's tenant-recovery chain, evaluated **before**
+ * `resolveTenant` runs on the incoming request. Each non-`fresh-request`
+ * variant carries a `flowId`; the framework consumes the matching
+ * `FlowRecord` and dispatches without consulting `resolveTenant`.
+ *
+ * Order of evaluation (see plan §"Tenant Recovery Across Redirects"):
+ *   1. If `callbackHostFor` configured AND host matches a known tenant:
+ *        a. `state` MAC-verifies → host-plus-mac
+ *        b. `flowId` in URI       → host-plus-uri
+ *        c. otherwise              → invalid_request, audit unrecoverable_flow
+ *   2. Else if `state` MAC-verifies → mac-state
+ *   3. Else if `flowId` in registered URI path/query → flow-id-in-uri
+ *   4. Else → fresh-request → call user's `resolveTenant(req)`
+ */
+export type TenantRecovery =
+  | { kind: "mac-state"; tenantId: TenantId; flowId: string }
+  | { kind: "host-plus-uri"; tenantId: TenantId; flowId: string }
+  | { kind: "host-plus-mac"; tenantId: TenantId; flowId: string }
+  | { kind: "flow-id-in-uri"; tenantId: TenantId; flowId: string }
+  | { kind: "fresh-request" }
+
+/**
+ * Minimal envelope MACed into the `state` query parameter. Intentionally
+ * tiny — under 256 base64url bytes — so it stays clear of provider URL
+ * limits. **No sensitive data must ever be added here.** Everything else
+ * lives in the server-side `FlowRecord`.
+ */
+export type StateEnvelope = {
+  tenantId: TenantId
+  flowId: string
+  /** Per-flow nonce. Distinct from the relying party's `state` param. */
+  nonce: string
+  /** Key id of the HMAC key used to mint this envelope (`StateKeyRing` lookup). */
+  kid: string
+}
+
+/**
+ * HMAC-SHA-256 key entry used to mint / verify the `state` envelope MAC.
+ * The 32-byte key is global (shared across IdP instances) — recovery has to
+ * work before tenant config is loaded, so per-tenant keys would create a
+ * bootstrap problem.
+ */
+export type StateKey = {
+  kid: string
+  /** 32 raw bytes. */
+  key: Uint8Array
+}
+
+/**
+ * State-MAC key ring with overlap-based rotation. `active` mints new state;
+ * any key in `verify` accepts existing state during its overlap window.
+ *
+ * Rotation cadence: monthly. The overlap window must be at least as long as
+ * the flow-record TTL (default 10 minutes); a 1-hour overlap is the
+ * recommended default. New keys are added to `verify` first, promoted to
+ * `active` on the next rotation, then dropped from `verify` after overlap.
+ */
+export type StateKeyRing = {
+  active: StateKey
+  /** Includes `active` plus any previous keys still inside their overlap window. */
+  verify: ReadonlyArray<StateKey>
+}