@_mustachio/openauth 0.9.1 → 0.10.0

package/src/ports/key-store.ts

@@ -0,0 +1,106 @@
+/**
+ * `KeyStore` — signing keys (JWT) and encryption keys (auth-code payload,
+ * other at-rest secrets).
+ *
+ * Per AD11, ES256 is the default signing algorithm; Ed25519 is supported.
+ *
+ * Consistency:
+ *  - `currentSigningKey` — strong (active key must be unambiguous across
+ *    the cluster).
+ *  - `signingKeys` (JWKS) — eventual OK; verifiers tolerate brief lag
+ *    during rotation.
+ *  - Encryption keys — same as signing for consistency; rotated quarterly,
+ *    old keys retained for `refreshTtl`.
+ *
+ * Note: `StateKeyRing` (HMAC keys for the `state` envelope) is **not** an
+ * abstraction over `KeyStore`. It is supplied directly via
+ * `IdPOptions.stateKeys` to avoid a bootstrap dependency on `KeyStore` for
+ * tenant resolution. A helper `loadStateKeyRingFromKeyStore` is offered
+ * for operators who choose to store the ring inside `KeyStore`.
+ */
+import type { Result } from "../types/result"
+
+/** Asymmetric signing key. Public material is JWKS-exposed; private is server-only. */
+export type SigningKey = {
+  kid: string
+  /** JOSE `alg` value, e.g. `"ES256"` or `"EdDSA"`. */
+  alg: string
+  /** JOSE `crv` for EC / OKP keys (`P-256`, `Ed25519`). Optional for other alg families. */
+  crv?: string
+  /** JWK form of the public key — published in JWKS. */
+  publicJwk: Record<string, unknown>
+  /**
+   * Opaque private-key handle. Concrete adapters interpret this:
+   *  - In-memory / Postgres: a serialized JWK.
+   *  - KMS-backed: a KMS key ARN / Cloudflare DO id.
+   */
+  privateKeyRef: unknown
+  /** Status used by JWKS rotation logic. */
+  status: "active" | "next" | "retired"
+  createdAt: number
+  /** When this key may no longer be used to sign. Verification continues until removal. */
+  rotatedAt?: number
+}
+
+/** Symmetric encryption key for the auth-code payload (and other at-rest data). */
+export type EncryptionKey = {
+  kid: string
+  /** JOSE `alg`, e.g. `"A256GCM"`. */
+  alg: string
+  /** Opaque key handle (raw bytes for in-memory; KMS ref for cloud). */
+  keyRef: unknown
+  status: "active" | "next" | "retired"
+  createdAt: number
+  rotatedAt?: number
+}
+
+/**
+ * Optional host-supplied envelope for wrapping private key material at rest.
+ *
+ * Adapters that persist signing-key private JWKs and encryption-key raw bytes
+ * to durable storage (Postgres, DynamoDB, …) accept a `KeyWrapper` so that
+ * material is encrypted with a key the database server cannot read. The
+ * canonical implementation backs `wrap` / `unwrap` with a cloud KMS
+ * (`AWS KMS Encrypt` / `Decrypt`, GCP KMS, Vault transit, etc.).
+ *
+ * Without a wrapper, `PostgresKeyStore` / `DynamoKeyStore` store private
+ * material in plaintext at rest — acceptable for dev / single-tenant
+ * operators with full-disk encryption who have accepted the trade-off, but
+ * **not** acceptable for production deployments with multi-tenant data. See
+ * `INTEGRATION.md` §4.
+ */
+export type KeyWrapper = {
+  /** Encrypt `plaintext` (≤ a few KB) under the host's master key. */
+  wrap(plaintext: Uint8Array): Promise<Uint8Array>
+  /** Decrypt a value previously returned by `wrap`. */
+  unwrap(ciphertext: Uint8Array): Promise<Uint8Array>
+}
+
+export type KeyStore = {
+  /** The unambiguous active signing key. Strong consistency. */
+  currentSigningKey(): Promise<Result<SigningKey>>
+
+  /**
+   * All keys to publish in JWKS — active + recently rotated, within the
+   * verification overlap window. Eventual consistency acceptable.
+   */
+  signingKeys(): Promise<Result<SigningKey[]>>
+
+  /** Active encryption key for at-rest payload encryption. Strong consistency. */
+  currentEncryptionKey(): Promise<Result<EncryptionKey>>
+
+  /**
+   * Look up a specific encryption key by `kid`. Used to decrypt payloads
+   * encrypted under a previous key during the overlap window.
+   */
+  getEncryptionKey(kid: string): Promise<Result<EncryptionKey>>
+
+  /**
+   * Rotate signing keys — promote `next` → `active`, retire current
+   * `active`, mint a new `next`. Phase 8 schedules this on a timer.
+   */
+  rotateSigningKeys?(): Promise<Result<void>>
+
+  /** Same as `rotateSigningKeys` for encryption keys. Quarterly cadence. */
+  rotateEncryptionKeys?(): Promise<Result<void>>
+}

package/src/ports/method-store.ts

@@ -0,0 +1,41 @@
+/**
+ * `MethodStore` — per-tenant `MethodConfig` lookup.
+ *
+ * This is a subset of `ConfigStore` exposed as a separate port for two
+ * reasons:
+ *  1. Adapters may want to back `MethodStore` with a more frequently
+ *     invalidated cache than the full tenant config.
+ *  2. The management console can update auth-method config independently
+ *     of other tenant-level fields.
+ *
+ * Consistency: same as `ConfigStore` — eventual + bounded staleness
+ * (TTL ≤ 60 s). Invalidation hook fires on update.
+ */
+import type { Result } from "../types/result"
+import type { MethodConfig, TenantId } from "../types/tenant"
+
+export type MethodStore = {
+  /** All method instances configured for a tenant (enabled and disabled). */
+  listMethods(tenantId: TenantId): Promise<Result<MethodConfig[]>>
+
+  /**
+   * Look up a single method instance by tenant-local id. Returns
+   * `method_not_found` if `methodId` does not exist in this tenant.
+   */
+  getMethodConfig(
+    tenantId: TenantId,
+    methodId: string,
+  ): Promise<Result<MethodConfig>>
+
+  /** Persist (create or update) a method instance. Triggers invalidation. */
+  putMethodConfig(
+    tenantId: TenantId,
+    method: MethodConfig,
+  ): Promise<Result<void>>
+
+  /** Delete a method instance. Tokens issued by it remain valid until expiry. */
+  deleteMethodConfig(
+    tenantId: TenantId,
+    methodId: string,
+  ): Promise<Result<void>>
+}

package/src/ports/session-store.ts

@@ -0,0 +1,98 @@
+/**
+ * `SessionStore` — flow records (required) and optional long-lived sessions.
+ *
+ * Flow records are the single server-side source of truth for an in-flight
+ * authorization. They are written at `/authorize`, updated when a method
+ * returns a `challenge` with `saveMethodState`, and consumed exactly once
+ * on the upstream callback.
+ *
+ * The framework owns flow-record I/O — methods only observe
+ * (`MethodContext.flow`) and request updates via
+ * `MethodResult.challenge.saveMethodState`. Methods MUST NOT call
+ * `saveFlow` / `consumeFlow` directly.
+ *
+ * See `ports/CONSISTENCY.md`.
+ */
+import type { FlowRecord } from "../types/flow"
+import type { Result } from "../types/result"
+
+export type SessionStore = {
+  /**
+   * Persist a new flow record under `flowId`. Strong, atomic write — the
+   * record must be visible to `consumeFlow` on any node by the time this
+   * resolves. `ttl` is in milliseconds and must equal `expiresAt -
+   * createdAt` on the supplied record (default 10 minutes).
+   */
+  saveFlow(
+    flowId: string,
+    payload: FlowRecord,
+    ttl: number,
+  ): Promise<Result<void>>
+
+  /**
+   * Merge `methodState` into an existing flow record. The framework calls
+   * this when a method handler returns
+   * `{ kind: "challenge", saveMethodState }`, **before** sending the
+   * upstream redirect response — the user agent never sees the redirect
+   * until `methodState` is durably saved.
+   *
+   * Returns `unknown_state` if `flowId` is missing or already consumed.
+   */
+  updateFlowMethodState(
+    flowId: string,
+    methodState: unknown,
+  ): Promise<Result<void>>
+
+  /**
+   * **Peek** at a flow record without consuming it. Used by the method-route
+   * mount (Phase 4) where credential POSTs may need to dispatch the
+   * method multiple times before the flow is consumed on `success`.
+   *
+   * Consistency: strong (the record must be visible to a `consumeFlow`
+   * called immediately after). Returns `unknown_state` if missing /
+   * expired.
+   *
+   * The framework is the only legitimate caller; methods should never read
+   * the flow directly — they observe via `MethodContext.flow`.
+   */
+  readFlow(flowId: string): Promise<Result<FlowRecord>>
+
+  /**
+   * Atomic delete-on-read. Returns the full `FlowRecord` on success — the
+   * framework needs every field to snapshot into the auth-code payload
+   * before the record is gone. Concurrent calls with the same `flowId`
+   * resolve to exactly one winner; losers receive `unknown_state` which
+   * the HTTP layer maps to `invalid_request` (audit
+   * `flow_replay_attempt`).
+   *
+   * This is the **only** consume; the framework does not call it twice.
+   * Methods receive the in-memory record via `MethodContext.flow` for the
+   * rest of the callback request.
+   */
+  consumeFlow(flowId: string): Promise<Result<FlowRecord>>
+
+  /**
+   * Optional: long-lived session support (cross-request remember-me beyond
+   * the OAuth flow). Adapters that don't implement this can omit it; the
+   * framework only requires the flow-record methods above.
+   */
+  createSession?(
+    sessionId: string,
+    payload: SessionRecord,
+    ttl: number,
+  ): Promise<Result<void>>
+  readSession?(sessionId: string): Promise<Result<SessionRecord>>
+  revokeSession?(sessionId: string): Promise<Result<void>>
+}
+
+/** Optional long-lived session payload (used by `createSession` family). */
+export type SessionRecord = {
+  sessionId: string
+  tenantId: string
+  subjectId: string
+  /** Wall-clock issued / expires timestamps (ms). */
+  issuedAt: number
+  expiresAt: number
+  /** Free-form metadata adapters may use (device, user agent fingerprint, etc.). */
+  metadata?: Record<string, unknown>
+}

package/src/ports/token-store.ts

@@ -0,0 +1,103 @@
+/**
+ * `TokenStore` — authorization codes + refresh tokens.
+ *
+ * All methods on this port are **security-critical** and require strong,
+ * atomic semantics. Cloudflare KV is **not** an acceptable backing store
+ * for any method here; use D1 (Sessions API w/ bookmarks), Durable Objects,
+ * Postgres (`SELECT FOR UPDATE`), or DynamoDB with conditional writes.
+ *
+ * See `ports/CONSISTENCY.md` §"Per-method consistency contracts".
+ */
+import type { RefreshTokenPayload } from "../types/token"
+import type { Result } from "../types/result"
+import type { TenantId } from "../types/tenant"
+
+export type TokenStore = {
+  /**
+   * Persist an auth-code ciphertext blob under `code`.
+   *
+   * The blob is **opaque** to the adapter — the framework encrypts the
+   * `CodePayload` at the domain boundary (`domain/authorize.ts` →
+   * `domain/crypto.encryptPayload`) before calling `saveCode`. Adapters
+   * must not parse, transform, or otherwise interpret the blob; just
+   * store it verbatim and return it on `consumeCode`.
+   *
+   * Required semantics:
+   *  - Strong, atomic write (the row must be visible to the next
+   *    `consumeCode` call on any node).
+   *  - `ttl` must be ≤ the framework's auth-code TTL (60 s).
+   *    Implementations that receive a larger value must reject.
+   */
+  saveCode(code: string, ciphertext: string, ttl: number): Promise<Result<void>>
+
+  /**
+   * Single-use, atomic compare-and-swap: return and delete the
+   * ciphertext blob in one logical operation. Concurrent calls with the
+   * same `code` must resolve to exactly one winner; losers receive
+   * `invalid_grant`. The caller (`domain/token.exchangeCode`) decrypts
+   * the returned blob.
+   */
+  consumeCode(code: string): Promise<Result<string>>
+
+  /**
+   * Persist a refresh-token payload. Strong, atomic. New tokens issued
+   * during rotation must be immediately retrievable.
+   */
+  saveRefresh(
+    refresh: string,
+    payload: RefreshTokenPayload,
+  ): Promise<Result<void>>
+
+  /**
+   * Rotate a refresh token. Strong CAS with reuse-detection window.
+   *
+   * Implementations must:
+   *  - Atomically check the token is unconsumed, mark it consumed, and
+   *    return its payload — concurrent presentations of the same token
+   *    resolve to exactly one winner.
+   *  - Within the reuse window (default 60 s), the consumed token must
+   *    still be detectable so a second presentation can trigger
+   *    revoke-the-whole-family. Outside the window the row may be GC'd.
+   *  - On reuse-detection (second consume within the window), return an
+   *    `invalid_grant` error **with a `reuseSignal` carrier** containing
+   *    the compromised refresh chain's `family`, `tenantId`, and
+   *    `subjectId`. The framework's refresh-grant handler reads
+   *    `reuseSignal` directly to emit `refresh_reuse_detected` audit
+   *    events. Adapters that omit the signal degrade audit fidelity (the
+   *    framework falls back to the peeked-payload values) but remain
+   *    behavior-compatible.
+   */
+  consumeRefresh(
+    refresh: string,
+    options?: { reuseWindowMs?: number },
+  ): Promise<Result<RefreshTokenPayload>>
+
+  /**
+   * Non-destructive lookup. Returns the refresh-token payload without
+   * marking it consumed.
+   *
+   * Used by RFC 7009 `/revoke` to enforce token-to-client binding
+   * (§2.2) before destructively consuming. Returns `invalid_grant` for
+   * unknown or expired tokens; `peekRefresh` does **not** trigger
+   * reuse-detection — a token already past `consumeRefresh` is still
+   * reported here so the caller can decide whether to escalate.
+   *
+   * Eventual consistency is acceptable: callers race `peekRefresh` then
+   * `consumeRefresh`, and the atomicity guarantees of `consumeRefresh`
+   * remain authoritative.
+   */
+  peekRefresh(refresh: string): Promise<Result<RefreshTokenPayload>>
+
+  /**
+   * Revoke all refresh tokens whose `RefreshTokenPayload.family` equals
+   * `family`. Used by reuse-detection to invalidate every descendant of a
+   * compromised refresh chain.
+   */
+  revokeFamily(family: string): Promise<Result<void>>
+
+  /**
+   * Revoke every refresh token for the given (tenant, subject) pair. Strong
+   * preferred; documented eventual lag acceptable.
+   */
+  revokeBySubject(tenantId: TenantId, subjectId: string): Promise<Result<void>>
+}

package/src/types/authorization.ts

@@ -0,0 +1,53 @@
+/**
+ * Authorization-request domain shapes. The HTTP layer parses the raw
+ * `/authorize` query into `AuthorizationRequest`; the domain operates on
+ * that.
+ */
+import type { TenantId } from "./tenant"
+
+/**
+ * Parsed `/authorize` request. The HTTP layer is responsible for schema
+ * validation (Zod) and for rejecting `response_type=token` per OAuth 2.1.
+ *
+ * `audience` and OIDC-specific fields (`prompt`, `uiLocales`, `nonce`) are
+ * optional and threaded into the `FlowRecord`.
+ */
+export type AuthorizationRequest = {
+  tenantId: TenantId
+  clientId: string
+  redirectUri: string
+  /** OAuth 2.1: `code` only. */
+  responseType: "code"
+  scopes: string[]
+  /** Relying party's CSRF state. Echoed back at success; opaque to the IdP. */
+  state: string | null
+  audience?: string
+  /** Tenant-local method instance id (`MethodConfig.id`) the RP selected, if any. */
+  methodId?: string
+  /**
+   * Relying-party PKCE challenge. Required for public clients; the framework
+   * additionally requires it for any client where `ClientConfig.pkceRequired`
+   * is true (default true).
+   */
+  codeChallenge?: string
+  codeChallengeMethod?: "S256"
+  /** Standard OIDC. */
+  prompt?: string[]
+  /** Standard OIDC. */
+  uiLocales?: string[]
+  /** Standard OIDC. */
+  nonce?: string
+}
+
+/**
+ * In-memory authorization state produced by `domain/authorize.startAuthorize`
+ * when it has not yet emitted a `Response` (e.g. method selection UI was
+ * not needed because only one method is configured, so the domain returns
+ * the chosen state directly for the next stage to act on).
+ */
+export type AuthorizationState = {
+  tenantId: TenantId
+  flowId: string
+  methodId: string
+  methodKind: string
+}

package/src/types/error.ts

@@ -0,0 +1,123 @@
+/**
+ * AuthError — the closed taxonomy returned by every domain function on failure.
+ *
+ * Codes map 1:1 to OAuth 2.0 / RFC 6749 §5.2 error identifiers, plus a handful
+ * of framework-internal codes used before the HTTP layer is reached. The HTTP
+ * layer translates `AuthError` into a response (`server_error` is the public
+ * mapping for `internal_error` at OAuth endpoints).
+ */
+export type AuthError =
+  | { code: "invalid_request"; description: string; field?: string }
+  | { code: "invalid_client"; description: string }
+  /**
+   * `invalid_grant`. `reuseSignal`, when present, is the structured
+   * reuse-detection hint `TokenStore.consumeRefresh` adapters emit on a
+   * second-use-within-the-window — used by the refresh-grant handler to
+   * audit `refresh_reuse_detected` with branded `TenantId` / `subjectId`
+   * fields rather than parsing strings out of `description`.
+   */
+  | {
+      code: "invalid_grant"
+      description: string
+      reuseSignal?: {
+        family: string
+        tenantId: string
+        subjectId: string
+      }
+    }
+  | { code: "unauthorized_client"; description: string }
+  | { code: "unsupported_grant_type"; description: string }
+  | { code: "invalid_scope"; description: string }
+  | { code: "access_denied"; description: string }
+  | { code: "unknown_state"; description: string }
+  // RFC 6749 §5.2 — token endpoint server-side failure (hook threw, downstream
+  // unavailable, etc.). Carries an optional `cause` for audit; not returned to
+  // the relying party.
+  | { code: "server_error"; description: string; cause?: unknown }
+  | { code: "tenant_not_found"; description: string; tenantId: string }
+  // RFC 8693 §2.2.2 — token-exchange "audience the subject can't reach"
+  // signal. Surfaced when the host's `exchangeAudience` hook rejects.
+  | { code: "invalid_target"; description: string }
+  // Populate whichever was requested (id from MethodConfig.id, or kind from
+  // MethodConfig.kind) so operators can find the offending config row.
+  | {
+      code: "method_not_found"
+      description: string
+      methodId?: string
+      methodKind?: string
+    }
+  // Framework-internal; the HTTP layer maps this to `server_error` at OAuth
+  // endpoints. Use for control-flow signalling that should never escape to a
+  // standards-compliant client.
+  | { code: "internal_error"; description: string; cause?: unknown }
+
+export type AuthErrorCode = AuthError["code"]
+
+/** Narrow constructor helpers — keep call sites short and types tight. */
+export const authError = {
+  invalidRequest: (description: string, field?: string): AuthError => ({
+    code: "invalid_request",
+    description,
+    ...(field !== undefined ? { field } : {}),
+  }),
+  invalidClient: (description: string): AuthError => ({
+    code: "invalid_client",
+    description,
+  }),
+  invalidGrant: (
+    description: string,
+    reuseSignal?: { family: string; tenantId: string; subjectId: string },
+  ): AuthError => ({
+    code: "invalid_grant",
+    description,
+    ...(reuseSignal !== undefined ? { reuseSignal } : {}),
+  }),
+  unauthorizedClient: (description: string): AuthError => ({
+    code: "unauthorized_client",
+    description,
+  }),
+  unsupportedGrantType: (description: string): AuthError => ({
+    code: "unsupported_grant_type",
+    description,
+  }),
+  invalidScope: (description: string): AuthError => ({
+    code: "invalid_scope",
+    description,
+  }),
+  accessDenied: (description: string): AuthError => ({
+    code: "access_denied",
+    description,
+  }),
+  unknownState: (description: string): AuthError => ({
+    code: "unknown_state",
+    description,
+  }),
+  serverError: (description: string, cause?: unknown): AuthError => ({
+    code: "server_error",
+    description,
+    ...(cause !== undefined ? { cause } : {}),
+  }),
+  tenantNotFound: (description: string, tenantId: string): AuthError => ({
+    code: "tenant_not_found",
+    description,
+    tenantId,
+  }),
+  methodNotFound: (
+    description: string,
+    refs: { methodId?: string; methodKind?: string },
+  ): AuthError => ({
+    code: "method_not_found",
+    description,
+    ...(refs.methodId !== undefined ? { methodId: refs.methodId } : {}),
+    ...(refs.methodKind !== undefined ? { methodKind: refs.methodKind } : {}),
+  }),
+  invalidTarget: (description: string): AuthError => ({
+    code: "invalid_target",
+    description,
+  }),
+  internalError: (description: string, cause?: unknown): AuthError => ({
+    code: "internal_error",
+    description,
+    ...(cause !== undefined ? { cause } : {}),
+  }),
+}

package/src/types/flow.ts

@@ -0,0 +1,89 @@
+/**
+ * `FlowRecord` — the single server-side source of truth for an in-flight
+ * authorization. Persisted in `SessionStore` between `/authorize` and the
+ * upstream provider's callback.
+ *
+ * The `state` envelope round-tripped through the upstream provider carries
+ * **only** `{ tenantId, flowId, nonce, kid }`. Sensitive data
+ * (`clientPkce`, `appRedirectUri`, scopes, audience, etc.) lives here and
+ * here only.
+ *
+ * Lifecycle:
+ *   1. Create — at `/authorize`, after schema validation + tenant resolve.
+ *   2. Update — when a method handler returns `{ kind: "challenge",
+ *      saveMethodState }`, the framework merges `saveMethodState` into
+ *      `methodState` and persists **before** sending the upstream redirect
+ *      response.
+ *   3. Consume — on callback, atomically (`consumeFlow`) — single delete-on-read.
+ *   4. Snapshot + dispose — on `success`, the framework snapshots the fields
+ *      needed at `/token` into the auth-code payload; `methodState` is
+ *      dropped.
+ */
+import type { TenantId } from "./tenant"
+
+export type FlowRecord = {
+  flowId: string
+  tenantId: TenantId
+
+  /** Tenant-local instance id (`MethodConfig.id`), e.g. `"google-workspace"`. */
+  methodId: string
+  /** Factory kind (`MethodConfig.kind`), e.g. `"google"`. */
+  methodKind: string
+
+  /** Relying party's registered client id. */
+  clientId: string
+  /** Final redirect to the relying party. */
+  appRedirectUri: string
+  /** Full expected request pathname for this specific flow on callback. */
+  callbackPath: string
+  /** Expected request host on callback. */
+  callbackHost: string
+  /** Relying party's `state` param, echoed back at success. */
+  appState: string | null
+  /** Scopes requested at `/authorize`. */
+  scopes: string[]
+  /**
+   * OAuth 2.1 — `code` only. Implicit (`response_type=token`) is removed; see
+   * plan §"OAuth 2.1 — `code` only".
+   */
+  responseType: "code"
+  audience?: string
+  /** Standard OIDC prompt values (`none`, `login`, `consent`, …). */
+  prompt?: string[]
+  uiLocales?: string[]
+  /**
+   * Per-flow CSRF nonce stamped into the `state` envelope. Distinct from
+   * `appState`. Compared at callback against the consumed record.
+   */
+  nonce: string
+  /**
+   * Relying-party → IdP PKCE. The RP generates the verifier and sends the
+   * challenge to `/authorize`. Verified at `/token`.
+   * Required for public clients.
+   */
+  clientPkce?: { challenge: string; method: "S256" }
+
+  /**
+   * Method-private state — opaque to the framework, typed via the
+   * `AuthMethod<P, S>` generic on the owning method. Examples:
+   *   - OAuth provider:  `{ upstreamPkceVerifier, upstreamState }`
+   *   - OIDC provider:   `{ upstreamPkceVerifier, upstreamNonce }`
+   *   - Passkey:         `{ challenge, allowedCredentialIds }`
+   *   - Password:        typically `null` (no upstream callback)
+   *
+   * Methods do not write this directly; they request a merge via
+   * `MethodResult.challenge.saveMethodState`.
+   */
+  methodState?: unknown
+
+  /** User's `requestContext` snapshot, if any. */
+  context?: Record<string, unknown>
+
+  createdAt: number
+  /**
+   * Pre-callback lifetime — covers upstream login, MFA, consent, mobile app
+   * switching, etc. Default 10 minutes. Distinct from the auth-code TTL
+   * (60 s) which covers the post-callback span.
+   */
+  expiresAt: number
+}