@_mustachio/openauth 0.9.2 → 0.11.0

package/src/methods/providers/linkedin.ts

@@ -0,0 +1,37 @@
+/**
+ * LinkedIn — OAuth 2.0. Default scopes: `r_liteprofile r_emailaddress`.
+ */
+import { z } from "zod"
+
+import { buildOauth2Method } from "../oauth2-generic"
+import type { Oauth2Properties, Oauth2State } from "../oauth2-generic"
+import type { AuthMethod, AuthMethodFactory } from "../../types/method"
+
+const schema = z.object({
+  clientId: z.string(),
+  clientSecret: z.string(),
+  scopes: z.array(z.string()).optional(),
+})
+
+export const linkedinFactory: AuthMethodFactory<
+  Oauth2Properties,
+  Oauth2State,
+  z.infer<typeof schema>
+> = {
+  kind: "linkedin",
+  configSchema: schema,
+  build: async ({
+    id,
+    kind,
+    config,
+  }): Promise<AuthMethod<Oauth2Properties, Oauth2State>> =>
+    buildOauth2Method({
+      id,
+      kind,
+      authorizationUrl: "https://www.linkedin.com/oauth/v2/authorization",
+      tokenUrl: "https://www.linkedin.com/oauth/v2/accessToken",
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+      scopes: config.scopes ?? ["r_liteprofile", "r_emailaddress"],
+    }),
+}

package/src/methods/providers/microsoft.ts

@@ -0,0 +1,42 @@
+/**
+ * Microsoft — OIDC, tenant-templated. The `tenant` field is `"common"`,
+ * `"organizations"`, `"consumers"`, or a specific Entra tenant id /
+ * domain.
+ *
+ * Discovery is fetched per tenant; the result is cached inside the
+ * `MethodCache` so subsequent flows skip the round trip.
+ */
+import { z } from "zod"
+
+import { buildOidcMethod } from "../oidc-generic"
+import type { Oauth2Properties, Oauth2State } from "../oauth2-generic"
+import type { AuthMethod, AuthMethodFactory } from "../../types/method"
+
+const schema = z.object({
+  clientId: z.string(),
+  clientSecret: z.string(),
+  tenant: z.string().optional(),
+  scopes: z.array(z.string()).optional(),
+})
+
+export const microsoftFactory: AuthMethodFactory<
+  Oauth2Properties,
+  Oauth2State,
+  z.infer<typeof schema>
+> = {
+  kind: "microsoft",
+  configSchema: schema,
+  build: async ({
+    id,
+    kind,
+    config,
+  }): Promise<AuthMethod<Oauth2Properties, Oauth2State>> =>
+    buildOidcMethod({
+      id,
+      kind,
+      issuer: `https://login.microsoftonline.com/${config.tenant ?? "common"}/v2.0`,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+      scopes: config.scopes ?? ["openid", "email", "profile"],
+    }),
+}

package/src/methods/providers/slack.ts

@@ -0,0 +1,42 @@
+/**
+ * Slack — Sign in with Slack (OpenID Connect on Slack's own endpoints).
+ * Slack ships an id_token at the token endpoint; we treat it as OIDC.
+ *
+ * Default scopes: `openid email profile`.
+ */
+import { z } from "zod"
+
+import { buildOauth2Method } from "../oauth2-generic"
+import type { Oauth2Properties, Oauth2State } from "../oauth2-generic"
+import type { AuthMethod, AuthMethodFactory } from "../../types/method"
+
+const schema = z.object({
+  clientId: z.string(),
+  clientSecret: z.string(),
+  scopes: z.array(z.string()).optional(),
+})
+
+export const slackFactory: AuthMethodFactory<
+  Oauth2Properties,
+  Oauth2State,
+  z.infer<typeof schema>
+> = {
+  kind: "slack",
+  configSchema: schema,
+  build: async ({
+    id,
+    kind,
+    config,
+  }): Promise<AuthMethod<Oauth2Properties, Oauth2State>> =>
+    buildOauth2Method({
+      id,
+      kind,
+      authorizationUrl: "https://slack.com/openid/connect/authorize",
+      tokenUrl: "https://slack.com/api/openid.connect.token",
+      jwksUri: "https://slack.com/openid/connect/keys",
+      expectedIssuer: "https://slack.com",
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+      scopes: config.scopes ?? ["openid", "email", "profile"],
+    }),
+}

package/src/methods/providers/spotify.ts

@@ -0,0 +1,37 @@
+/**
+ * Spotify — OAuth 2.0. Default scopes: `user-read-email user-read-private`.
+ */
+import { z } from "zod"
+
+import { buildOauth2Method } from "../oauth2-generic"
+import type { Oauth2Properties, Oauth2State } from "../oauth2-generic"
+import type { AuthMethod, AuthMethodFactory } from "../../types/method"
+
+const schema = z.object({
+  clientId: z.string(),
+  clientSecret: z.string(),
+  scopes: z.array(z.string()).optional(),
+})
+
+export const spotifyFactory: AuthMethodFactory<
+  Oauth2Properties,
+  Oauth2State,
+  z.infer<typeof schema>
+> = {
+  kind: "spotify",
+  configSchema: schema,
+  build: async ({
+    id,
+    kind,
+    config,
+  }): Promise<AuthMethod<Oauth2Properties, Oauth2State>> =>
+    buildOauth2Method({
+      id,
+      kind,
+      authorizationUrl: "https://accounts.spotify.com/authorize",
+      tokenUrl: "https://accounts.spotify.com/api/token",
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+      scopes: config.scopes ?? ["user-read-email", "user-read-private"],
+    }),
+}

package/src/methods/providers/twitch.ts

@@ -0,0 +1,38 @@
+/**
+ * Twitch — OAuth 2.0 (Twitch supports OIDC but uses OAuth flows by
+ * default). Default scopes: `user:read:email`.
+ */
+import { z } from "zod"
+
+import { buildOauth2Method } from "../oauth2-generic"
+import type { Oauth2Properties, Oauth2State } from "../oauth2-generic"
+import type { AuthMethod, AuthMethodFactory } from "../../types/method"
+
+const schema = z.object({
+  clientId: z.string(),
+  clientSecret: z.string(),
+  scopes: z.array(z.string()).optional(),
+})
+
+export const twitchFactory: AuthMethodFactory<
+  Oauth2Properties,
+  Oauth2State,
+  z.infer<typeof schema>
+> = {
+  kind: "twitch",
+  configSchema: schema,
+  build: async ({
+    id,
+    kind,
+    config,
+  }): Promise<AuthMethod<Oauth2Properties, Oauth2State>> =>
+    buildOauth2Method({
+      id,
+      kind,
+      authorizationUrl: "https://id.twitch.tv/oauth2/authorize",
+      tokenUrl: "https://id.twitch.tv/oauth2/token",
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+      scopes: config.scopes ?? ["user:read:email"],
+    }),
+}

package/src/methods/providers/x.ts

@@ -0,0 +1,40 @@
+/**
+ * X (formerly Twitter) — OAuth 2.0 with PKCE. Default scope: `tweet.read users.read`.
+ *
+ * X requires PKCE on its OAuth 2.0 endpoints; `pkce` is left at the
+ * `"S256"` default.
+ */
+import { z } from "zod"
+
+import { buildOauth2Method } from "../oauth2-generic"
+import type { Oauth2Properties, Oauth2State } from "../oauth2-generic"
+import type { AuthMethod, AuthMethodFactory } from "../../types/method"
+
+const schema = z.object({
+  clientId: z.string(),
+  clientSecret: z.string(),
+  scopes: z.array(z.string()).optional(),
+})
+
+export const xFactory: AuthMethodFactory<
+  Oauth2Properties,
+  Oauth2State,
+  z.infer<typeof schema>
+> = {
+  kind: "x",
+  configSchema: schema,
+  build: async ({
+    id,
+    kind,
+    config,
+  }): Promise<AuthMethod<Oauth2Properties, Oauth2State>> =>
+    buildOauth2Method({
+      id,
+      kind,
+      authorizationUrl: "https://twitter.com/i/oauth2/authorize",
+      tokenUrl: "https://api.x.com/2/oauth2/token",
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+      scopes: config.scopes ?? ["tweet.read", "users.read"],
+    }),
+}

package/src/methods/providers/yahoo.ts

@@ -0,0 +1,36 @@
+/**
+ * Yahoo — OIDC. Default scopes: `openid email profile`.
+ */
+import { z } from "zod"
+
+import { buildOidcMethod } from "../oidc-generic"
+import type { Oauth2Properties, Oauth2State } from "../oauth2-generic"
+import type { AuthMethod, AuthMethodFactory } from "../../types/method"
+
+const schema = z.object({
+  clientId: z.string(),
+  clientSecret: z.string(),
+  scopes: z.array(z.string()).optional(),
+})
+
+export const yahooFactory: AuthMethodFactory<
+  Oauth2Properties,
+  Oauth2State,
+  z.infer<typeof schema>
+> = {
+  kind: "yahoo",
+  configSchema: schema,
+  build: async ({
+    id,
+    kind,
+    config,
+  }): Promise<AuthMethod<Oauth2Properties, Oauth2State>> =>
+    buildOidcMethod({
+      id,
+      kind,
+      issuer: "https://api.login.yahoo.com",
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+      scopes: config.scopes ?? ["openid", "email", "profile"],
+    }),
+}

package/src/pkce.ts

@@ -1,3 +1,14 @@
+/**
+ * Client-side PKCE generator — used by `@_mustachio/openauth/client` to
+ * produce a verifier + S256 challenge pair before redirecting the user to
+ * `/authorize`.
+ *
+ * S256-only. Per OAuth 2.1 the `plain` method is prohibited; this module
+ * does not expose a verifier-comparison helper because IdP-side validation
+ * lives in `domain/pkce.ts` and runs against the stored challenge from the
+ * auth-code payload — no consumer of this file has a legitimate reason to
+ * recompute a challenge.
+ */
 import { base64url } from "jose"
 
 function generateVerifier(length: number): string {
@@ -6,35 +17,23 @@ function generateVerifier(length: number): string {
   return base64url.encode(buffer)
 }
 
-async function generateChallenge(verifier: string, method: "S256" | "plain") {
-  if (method === "plain") return verifier
-  const encoder = new TextEncoder()
-  const data = encoder.encode(verifier)
+async function s256Challenge(verifier: string): Promise<string> {
+  const data = new TextEncoder().encode(verifier)
   const hash = await crypto.subtle.digest("SHA-256", data)
   return base64url.encode(new Uint8Array(hash))
 }
 
-export async function generatePKCE(length: number = 64) {
+export async function generatePKCE(length: number = 64): Promise<{
+  verifier: string
+  challenge: string
+  method: "S256"
+}> {
   if (length < 43 || length > 128) {
     throw new Error(
       "Code verifier length must be between 43 and 128 characters",
     )
   }
   const verifier = generateVerifier(length)
-  const challenge = await generateChallenge(verifier, "S256")
-  return {
-    verifier,
-    challenge,
-    method: "S256",
-  }
-}
-
-export async function validatePKCE(
-  verifier: string,
-  challenge: string,
-  method: "S256" | "plain" = "S256",
-) {
-  const generatedChallenge = await generateChallenge(verifier, method)
-  // timing safe equals?
-  return generatedChallenge === challenge
+  const challenge = await s256Challenge(verifier)
+  return { verifier, challenge, method: "S256" }
 }

package/src/ports/CONSISTENCY.md

@@ -0,0 +1,119 @@
+# Port consistency contracts
+
+This document is **normative**. Adapter implementations that do not meet
+the per-method consistency requirement below are **not certified for
+production** and must not be wired into a deployed IdP. The phase-1 test
+fixtures and the phase-6 adapter integration suite exist to verify these
+contracts hold against real backends.
+
+Storage ports differ in their consistency needs because the security
+properties of the OAuth flows depend on specific atomicity / linearizability
+guarantees at specific points. A blanket "use a strongly consistent KV"
+overspecifies adapters that don't need that on the read-eventual paths
+(tenant config, JWKS); under-specifying any of the strong paths
+(`consumeCode`, `consumeRefresh`, `consumeFlow`) is a critical security bug.
+
+## 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.                                                                                                                                                                                                                     |
+
+## Implications for adapter choice
+
+| Backend                        | Acceptable for                                                                                                                            | NOT acceptable for                                                                                                                                                |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Cloudflare KV**              | `ConfigStore`, `MethodStore`, `KeyStore.signingKeys()` (read cache), `AuditLog` (with buffered writes).                                   | `TokenStore.saveCode` / `consumeCode` / `saveRefresh` / `consumeRefresh`, `SessionStore.saveFlow` / `consumeFlow`. Eventual consistency violates these contracts. |
+| **Cloudflare D1**              | Everything, **provided** token / code / flow operations use the **D1 Sessions API with bookmarks** (or primary-pinned reads) per AD8.     | Token / code / flow operations against non-pinned read replicas without bookmarks.                                                                                |
+| **Cloudflare Durable Objects** | `SessionStore` (flow records) and `TokenStore` (deployments without D1).                                                                  | —                                                                                                                                                                 |
+| **AWS DynamoDB**               | Everything, **provided** strong-consistency / conditional-write semantics are used (`ConsistentRead=true`, `ConditionExpression` on CAS). | Default eventual-consistency reads on token / code / flow operations.                                                                                             |
+| **Postgres**                   | Everything (row-level locking / `SELECT … FOR UPDATE` on the refresh path; `DELETE … RETURNING` on consume paths).                        | —                                                                                                                                                                 |
+| **In-memory**                  | Tests + single-instance dev. Trivially satisfies all contracts (single process).                                                          | Multi-instance production.                                                                                                                                        |
+
+### D1 read-replication caveat
+
+D1 supports asynchronous read replication. All token / code / flow methods
+above (the security-critical paths) **must** use the D1 Sessions API with
+bookmarks, or primary-pinned reads, to guarantee read-after-write
+consistency. The D1 adapter is certified only when its integration tests
+demonstrate, under simulated replication lag:
+
+1. `consumeCode` / `consumeFlow` immediately after the matching `saveCode` /
+   `saveFlow` return the row.
+2. `consumeRefresh` CAS resolves to exactly one winner under concurrent
+   attempts on the same token.
+3. `revokeBySubject` propagates within the documented SLA.
+
+Read-eventual paths (`ConfigStore.getTenantConfig`, JWKS) may use replicas
+freely.
+
+Source: <https://developers.cloudflare.com/d1/best-practices/read-replication/>.
+
+## Test fixtures
+
+Phase 2 provides parameterized port-conformance tests
+(`packages/openauth/test/ports/`) that run against any adapter. An adapter
+that fails any test in that suite is not certified. Phase 6 adapters must
+pass the full suite against a real (or close-to-real) backend.
+
+The fixture set covers, at minimum:
+
+- Single-use atomicity of `consumeCode`, `consumeRefresh`, `consumeFlow`
+  under concurrent presentations.
+- TTL enforcement (`saveCode` with `ttl > 60` rejected).
+- Encryption-at-rest verification (`consumeCode` returns plaintext only after
+  decryption — direct DB inspection shows ciphertext).
+- Refresh reuse detection within the window.
+- `revokeFamily` and `revokeBySubject` propagation.
+- `ConfigStore` invalidation hook fires within bounded staleness.
+- JWKS overlap window — keys retired during the verification window remain
+  in `signingKeys()` until removed.
+- **PAR (`supportsPar: true`)** — `savePar` / `consumePar` round-trip,
+  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.
+
+## Optional methods and graceful degradation
+
+Several recent ports are **optional** because not every adapter has
+caught up yet:
+
+- `SessionStore.savePar` / `consumePar` — required for RFC 9126 PAR.
+  Without them the framework's `/par` handler returns `invalid_request`
+  with a clear "session adapter does not support PAR" description, and
+  `/authorize?request_uri=...` returns the same. Memory adapter
+  implements; production adapters (Postgres, D1, DO, DynamoDB) follow
+  the same `consumeFlow` pattern and should add it.
+- `TokenStore.recordDpopJti` — required for RFC 9449 DPoP. Without it
+  the DPoP verifier returns `invalid_dpop_proof: "token-store adapter
+does not support DPoP replay protection"`. Memory adapter
+  implements; production adapters add it the same way `consumeRefresh`
+  uses an atomic write-once primitive.
+
+The framework never advertises a feature in discovery that the wired
+adapters cannot actually serve: `pushed_authorization_request_endpoint`
+and `dpop_signing_alg_values_supported` are advertised unconditionally,
+and clients receive the appropriate error if the adapter doesn't
+support them. Operators who do not run PAR / DPoP should communicate
+that to RPs out-of-band.

package/src/ports/audit-log.ts

@@ -0,0 +1,177 @@
+/**
+ * `AuditLog` — append-only event log for security-relevant operations.
+ *
+ * Consistency: append-only, durable. Ordering across instances is **not**
+ * required; consumers (SIEM, dashboards) sort by `timestamp` and `actor`.
+ *
+ * Retention: defined by the adapter. 90 days minimum is the documented
+ * baseline for SOC 2 readiness.
+ *
+ * Audit-event payloads must **never** contain auth-code payloads, refresh
+ * tokens, access tokens, raw cookies, or any other secret. The framework's
+ * built-in events follow this rule; custom emitters must too.
+ */
+import type { TenantId } from "../types/tenant"
+
+/**
+ * Discriminated event union. The framework emits these; user code may emit
+ * its own with `kind: "custom"`. Each event carries enough id information
+ * for operators to find the offending record without exposing secrets.
+ */
+export type AuditEvent =
+  | {
+      kind: "authorize_started"
+      tenantId: TenantId
+      clientId: string
+      methodId: string
+      methodKind: string
+      flowId: string
+    }
+  | {
+      kind: "authorize_succeeded"
+      tenantId: TenantId
+      clientId: string
+      methodId: string
+      methodKind: string
+      flowId: string
+      subjectId: string
+    }
+  | {
+      kind: "authorize_failed"
+      tenantId: TenantId | null
+      clientId: string | null
+      methodId?: string
+      methodKind?: string
+      flowId?: string
+      reason: string
+    }
+  | {
+      kind: "token_issued"
+      tenantId: TenantId
+      clientId: string
+      methodId: string
+      methodKind: string
+      subjectId: string
+      /** Hash of the issued refresh token id — never the token itself. */
+      refreshTokenIdHash?: string
+      /** OIDC Core §2 — set when the response carried an `id_token`. */
+      idTokenIssued?: boolean
+      /** RFC 9449 — set when the access token is DPoP-bound. */
+      dpopBound?: boolean
+    }
+  | {
+      kind: "token_refreshed"
+      tenantId: TenantId
+      clientId: string
+      subjectId: string
+      family: string
+    }
+  | {
+      kind: "token_exchanged"
+      /** Tenant the new tokens are scoped to. */
+      tenantId: TenantId
+      /** Tenant the subject_token was originally issued for. */
+      fromTenantId: TenantId
+      clientId: string
+      subjectId: string
+      /** Fresh refresh-token family for the issued tokens. */
+      family: string
+    }
+  | {
+      kind: "token_revoked"
+      tenantId: TenantId
+      clientId: string | null
+      subjectId?: string
+      family?: string
+      reason: string
+    }
+  | {
+      kind: "refresh_reuse_detected"
+      tenantId: TenantId
+      clientId: string
+      family: string
+    }
+  | {
+      /**
+       * 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.
+       */
+      kind: "session_logout"
+      tenantId: TenantId
+      clientId?: string
+      subjectId?: string
+    }
+  | {
+      /**
+       * Emitted when a DPoP proof's `jti` is presented within the replay
+       * window (RFC 9449 §11.1). The request was rejected with
+       * `invalid_dpop_proof`. Operators / SIEM use this to spot
+       * stolen-key replay attempts.
+       */
+      kind: "dpop_replay_detected"
+      tenantId: TenantId | null
+      /** First-half of the offending jti so logs can correlate without storing it. */
+      jtiPrefix: string
+    }
+  | {
+      kind: "flow_replay_attempt"
+      tenantId: TenantId | null
+      flowId: string
+    }
+  | {
+      kind: "flow_tenant_mismatch"
+      stateTenantId: TenantId
+      flowTenantId: TenantId
+      flowId: string
+    }
+  | {
+      kind: "flow_callback_mismatch"
+      tenantId: TenantId
+      flowId: string
+      expected: { host: string; path: string }
+      actual: { host: string; path: string }
+    }
+  | {
+      kind: "factory_id_mismatch"
+      tenantId: TenantId
+      methodId: string
+      expectedKind: string
+      actualKind: string
+    }
+  | {
+      kind: "invalid_method_config"
+      tenantId: TenantId
+      methodId: string
+      methodKind: string
+      /** Zod error path string. Never the raw config blob. */
+      errorPath: string
+    }
+  | {
+      kind: "unknown_method_kind"
+      tenantId: TenantId
+      methodId: string
+      methodKind: string
+    }
+  | {
+      kind: "unrecoverable_flow"
+      reason: string
+      host?: string
+    }
+  | {
+      kind: "custom"
+      type: string
+      tenantId?: TenantId
+      data: Record<string, unknown>
+    }
+
+export type AuditLog = {
+  /**
+   * Append a single event. Should not throw on durability failure; the
+   * adapter is responsible for buffering / retry. Returning never-rejects
+   * is acceptable so the IdP's hot paths are not gated on the log.
+   */
+  log(event: AuditEvent & { timestamp: number }): Promise<void>
+}