@_mustachio/openauth 0.10.0 → 0.12.0

package/dist/types/types/token.d.ts

@@ -6,6 +6,7 @@
  * Per AD9, access tokens are JWTs (ES256 by default, Ed25519 optional per
  * AD11) and refresh tokens are opaque server-side records.
  */
+import type { ClaimsRequest } from "./authorization";
 import type { SubjectClaim } from "./subject";
 import type { TenantId } from "./tenant";
 /**
@@ -39,9 +40,98 @@ export type CodePayload = {
     providerSubject: string;
     /** Typed-per-method properties from `MethodResult.success`. */
     properties: unknown;
+    /**
+     * Relying party's OIDC `nonce` (OIDC Core §3.1.2.1). Snapshotted from
+     * `FlowRecord.appNonce`. Echoed into the issued `id_token` when present.
+     */
+    appNonce?: string;
+    /**
+     * Seconds-since-epoch when end-user authentication completed
+     * (OIDC Core §2 `auth_time`). Stamped at the moment the method's
+     * `MethodResult.success` fires. Carried into the `id_token` and forward
+     * across refresh-token rotations.
+     */
+    authTime: number;
+    /** OIDC Core §5.5 — RP-requested claims; honored at id_token + /userinfo. */
+    claimsRequest?: ClaimsRequest;
     /** Auth-code TTL is 60 s — framework refuses anything longer. */
     expiresAt: number;
 };
+/**
+ * OIDC Core §5.1 `address` claim. Structured object value rather than a
+ * scalar — distinct from the rest of the profile fields.
+ */
+export type AddressClaim = {
+    formatted?: string;
+    street_address?: string;
+    locality?: string;
+    region?: string;
+    postal_code?: string;
+    country?: string;
+};
+/**
+ * OIDC Core §5.1 profile / email / phone / address claims, gated by the
+ * `profile` / `email` / `phone` / `address` scopes via §5.4. Reused by
+ * `IdTokenClaims` and the `/userinfo` response so the two surfaces share
+ * exactly one source of truth for scope→claim mapping.
+ *
+ * Every field is optional: presence depends on (a) which scopes were
+ * granted and (b) whether the host populated the matching key in
+ * `SubjectClaim.properties`.
+ */
+export type ScopedProfileClaims = {
+    name?: string;
+    given_name?: string;
+    family_name?: string;
+    middle_name?: string;
+    nickname?: string;
+    preferred_username?: string;
+    profile?: string;
+    picture?: string;
+    website?: string;
+    gender?: string;
+    birthdate?: string;
+    zoneinfo?: string;
+    locale?: string;
+    updated_at?: number;
+    email?: string;
+    email_verified?: boolean;
+    phone_number?: string;
+    phone_number_verified?: boolean;
+    address?: AddressClaim;
+};
+/**
+ * OIDC `id_token` JWT claims this IdP issues at `/token` when `openid`
+ * scope is granted (OIDC Core §2). Distinct from access-token claims:
+ *
+ *  - `aud` is the relying-party `client_id` (not the API audience).
+ *  - `nonce` echoes the RP's `/authorize` `nonce` parameter when present.
+ *  - `auth_time` is stable across refresh-token rotations (OIDC Core §12).
+ *  - `at_hash` is recommended whenever an id_token and access_token are
+ *    returned in the same response (§3.1.3.6).
+ *
+ * Standard OIDC claim names use snake_case on the wire; TypeScript field
+ * names match to keep the marshalling 1:1.
+ */
+export type IdTokenClaims = ScopedProfileClaims & {
+    iss: string;
+    sub: string;
+    aud: string;
+    exp: number;
+    iat: number;
+    /** Seconds-since-epoch when end-user auth completed. */
+    auth_time?: number;
+    /** RP-supplied OIDC nonce, when present. MUST equal the `/authorize` value. */
+    nonce?: string;
+    /** Authentication Methods References (RFC 8176). */
+    amr?: string[];
+    /** Authentication Context Class Reference. */
+    acr?: string;
+    /** Authorized party — the client_id of the party the id_token is for. */
+    azp?: string;
+    /** Access-token hash (OIDC Core §3.1.3.6). */
+    at_hash?: string;
+};
 /** Access-token JWT claims this IdP issues. */
 export type AccessTokenClaims = {
     iss: string;
@@ -56,10 +146,30 @@ export type AccessTokenClaims = {
     /** Factory kind that originated this token. */
     mkind?: string;
     scope?: string;
+    /**
+     * Seconds-since-epoch when the end-user originally authenticated
+     * (OIDC Core §2). Stable across refresh-token rotation and across
+     * RFC 8693 token-exchange (§12 — exchanging an audience does NOT
+     * re-authenticate the user). Absent on `client_credentials` grants
+     * where there is no end-user.
+     *
+     * Carried on the access token so RFC 8693 `subject_token` consumers
+     * can propagate it without needing the original id_token. Resource
+     * servers typically ignore it; it's there for the IdP's own
+     * downstream issuance.
+     */
+    auth_time?: number;
     /** DPoP confirmation claim (Phase 8). */
     cnf?: {
         jkt: string;
     };
+    /**
+     * OIDC Core §5.5 — list of claim names the RP requested for the
+     * `/userinfo` response via the `claims` parameter. The resource server
+     * surface uses this to bypass scope-gating per §5.5; it is empty /
+     * absent when the RP did not use the `claims` parameter.
+     */
+    uic?: string[];
     /** The structured subject (matches `SubjectClaim`). Inlined for resource servers. */
     claim: SubjectClaim;
 };
@@ -87,6 +197,24 @@ export type RefreshTokenPayload = {
     methodId: string;
     /** Factory kind (`MethodConfig.kind`) that originated the chain. */
     methodKind: string;
+    /**
+     * Seconds-since-epoch when end-user authentication originally completed
+     * (OIDC Core §2 `auth_time`). Stable across refresh-token rotations —
+     * `auth_time` does **not** advance on refresh, only on re-authentication.
+     */
+    authTime: number;
+    /**
+     * RFC 7638 JWK thumbprint of the client's DPoP key (RFC 9449 §6.1).
+     * Present when the original token grant was DPoP-bound. Refresh-grant
+     * rotation REQUIRES a fresh DPoP proof whose thumbprint matches; absent
+     * = the token is plain Bearer and Bearer is acceptable on refresh.
+     */
+    dpopJkt?: string;
+    /**
+     * OIDC Core §12 — the original RP-requested claims, preserved so
+     * refresh-grant id_token + /userinfo responses keep returning them.
+     */
+    claimsRequest?: ClaimsRequest;
     /** Wall-clock issuance and absolute-expiry timestamps. */
     issuedAt: number;
     expiresAt: number;

package/dist/types/types/token.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../../../src/types/token.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAC7C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAExC;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,EAAE,QAAQ,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,cAAc,EAAE,MAAM,CAAA;IACtB,6DAA6D;IAC7D,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,gFAAgF;IAChF,UAAU,CAAC,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAA;IAClD,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAA;IAChB,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAA;IAClB,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IACxC,yEAAyE;IACzE,eAAe,EAAE,MAAM,CAAA;IACvB,+DAA+D;IAC/D,UAAU,EAAE,OAAO,CAAA;IACnB,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAA;CAClB,CAAA;AAED,+CAA+C;AAC/C,MAAM,MAAM,iBAAiB,GAAG;IAC9B,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,iBAAiB;IACjB,GAAG,EAAE,QAAQ,CAAA;IACb,kEAAkE;IAClE,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,yCAAyC;IACzC,GAAG,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAA;IACrB,qFAAqF;IACrF,KAAK,EAAE,YAAY,CAAA;CACpB,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,EAAE,QAAQ,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,YAAY,CAAA;IACnB,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAA;IACd;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB,oEAAoE;IACpE,UAAU,EAAE,MAAM,CAAA;IAClB,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;CAClB,CAAA;AAED,iDAAiD;AACjD,MAAM,MAAM,aAAa,GAAG;IAC1B,YAAY,EAAE,MAAM,CAAA;IACpB,UAAU,EAAE,QAAQ,GAAG,MAAM,CAAA;IAC7B,UAAU,EAAE,MAAM,CAAA;IAClB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,CAAA"}
+{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../../../src/types/token.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@_mustachio/openauth",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -37,6 +37,12 @@
       "import": "./dist/esm/adapters/*/index.js",
       "types": "./dist/types/adapters/*/index.d.ts"
     },
+    "./methods/saml-sp": {
+      "node": {
+        "import": "./dist/esm/methods/saml-sp/index.js",
+        "types": "./dist/types/methods/saml-sp/index.d.ts"
+      }
+    },
     "./*": {
       "import": "./dist/esm/*.js",
       "types": "./dist/types/*.d.ts"
@@ -73,8 +79,10 @@
   },
   "dependencies": {
     "@noble/hashes": "2.2.0",
+    "@node-saml/node-saml": "5.1.0",
     "@simplewebauthn/server": "13.1.1",
     "@standard-schema/spec": "1.0.0-beta.3",
+    "@xmldom/xmldom": "0.8.13",
     "aws4fetch": "1.0.20",
     "jose": "5.9.6",
     "oauth4webapi": "3.8.6",

package/src/adapters/d1/migrations.ts

@@ -67,6 +67,11 @@ export const INITIAL_SCHEMA_SQL = [
     payload TEXT NOT NULL,
     expires_at INTEGER NOT NULL
   )`,
+  `CREATE TABLE IF NOT EXISTS openauth_scratch (
+    scratch_key TEXT PRIMARY KEY,
+    value TEXT NOT NULL,
+    expires_at INTEGER NOT NULL
+  )`,
   `CREATE TABLE IF NOT EXISTS openauth_audit_events (
     id INTEGER PRIMARY KEY AUTOINCREMENT,
     ts INTEGER NOT NULL,

package/src/adapters/d1/session-store.ts

@@ -227,4 +227,72 @@ export class D1SessionStore implements SessionStore {
     }
     return ok(undefined)
   }
+
+  async saveScratch(
+    key: string,
+    value: string,
+    ttlMs: number,
+  ): Promise<Result<void>> {
+    if (ttlMs <= 0) {
+      return err(
+        authError.internalError(
+          `saveScratch: ttlMs must be positive, got ${ttlMs}`,
+        ),
+      )
+    }
+    const expiresAt = this.#clock() + ttlMs
+    try {
+      // Pinned to the primary — scratch backs InResponseTo replay
+      // protection, which is read-after-write sensitive at the ACS.
+      await primarySession(this.#db)
+        .prepare(
+          `INSERT INTO openauth_scratch (scratch_key, value, expires_at) VALUES (?1, ?2, ?3)
+           ON CONFLICT(scratch_key) DO UPDATE SET value = excluded.value, expires_at = excluded.expires_at`,
+        )
+        .bind(key, value, expiresAt)
+        .run()
+    } catch (e) {
+      return err(authError.internalError("saveScratch: upsert failed", e))
+    }
+    return ok(undefined)
+  }
+
+  async readScratch(key: string): Promise<Result<string>> {
+    let row: { value: string; expires_at: number } | null
+    try {
+      row = await primarySession(this.#db)
+        .prepare(
+          `SELECT value, expires_at FROM openauth_scratch WHERE scratch_key = ?1`,
+        )
+        .bind(key)
+        .first<{ value: string; expires_at: number }>()
+    } catch (e) {
+      return err(authError.internalError("readScratch: query failed", e))
+    }
+    if (!row) {
+      return err(authError.unknownState(`scratch "${key}" unknown`))
+    }
+    if (this.#clock() >= Number(row.expires_at)) {
+      try {
+        await primarySession(this.#db)
+          .prepare(`DELETE FROM openauth_scratch WHERE scratch_key = ?1`)
+          .bind(key)
+          .run()
+      } catch {}
+      return err(authError.unknownState(`scratch "${key}" expired`))
+    }
+    return ok(row.value)
+  }
+
+  async deleteScratch(key: string): Promise<Result<void>> {
+    try {
+      await primarySession(this.#db)
+        .prepare(`DELETE FROM openauth_scratch WHERE scratch_key = ?1`)
+        .bind(key)
+        .run()
+    } catch (e) {
+      return err(authError.internalError("deleteScratch: delete failed", e))
+    }
+    return ok(undefined)
+  }
 }

package/src/adapters/durable-object/session-store.ts

@@ -51,6 +51,11 @@ type StoredSession = {
   expiresAt: number
 }
 
+type StoredScratch = {
+  value: string
+  expiresAt: number
+}
+
 export type DurableObjectSessionStoreOptions = {
   storage: DurableObjectStorageLike
   clock?: () => number
@@ -218,10 +223,66 @@ export class DurableObjectSessionStore implements SessionStore {
     }
     return ok(undefined)
   }
+
+  async saveScratch(
+    key: string,
+    value: string,
+    ttlMs: number,
+  ): Promise<Result<void>> {
+    if (ttlMs <= 0) {
+      return err(
+        authError.internalError(
+          `saveScratch: ttlMs must be positive, got ${ttlMs}`,
+        ),
+      )
+    }
+    const stored: StoredScratch = {
+      value,
+      expiresAt: this.#clock() + ttlMs,
+    }
+    try {
+      // Plain put — scratch overwrites any prior value for the key. No
+      // transaction needed: it is a single write, and the DO serializes
+      // all operations on this instance.
+      await this.#storage.put(scratchKey(key), stored)
+    } catch (e) {
+      return err(authError.internalError("saveScratch: put failed", e))
+    }
+    return ok(undefined)
+  }
+
+  async readScratch(key: string): Promise<Result<string>> {
+    let stored: StoredScratch | undefined
+    try {
+      stored = await this.#storage.get<StoredScratch>(scratchKey(key))
+    } catch (e) {
+      return err(authError.internalError("readScratch: get failed", e))
+    }
+    if (!stored) {
+      return err(authError.unknownState(`scratch "${key}" unknown`))
+    }
+    if (this.#clock() >= stored.expiresAt) {
+      try {
+        await this.#storage.delete(scratchKey(key))
+      } catch {}
+      return err(authError.unknownState(`scratch "${key}" expired`))
+    }
+    return ok(stored.value)
+  }
+
+  async deleteScratch(key: string): Promise<Result<void>> {
+    try {
+      await this.#storage.delete(scratchKey(key))
+    } catch (e) {
+      return err(authError.internalError("deleteScratch: delete failed", e))
+    }
+    return ok(undefined)
+  }
 }
 
 const flowKey = (flowId: string) => `flow:${flowId}`
 const sessionKey = (sessionId: string) => `session:${sessionId}`
+const scratchKey = (key: string) => `scratch:${key}`
 
 // Re-exported for adapter users wiring `storage.transaction` callbacks.
 export type { DurableObjectStorageLike, DurableObjectTransactionLike }

package/src/adapters/dynamo/session-store.ts

@@ -211,6 +211,69 @@ export class DynamoSessionStore implements SessionStore {
     }
     return ok(undefined)
   }
+
+  async saveScratch(
+    key: string,
+    value: string,
+    ttlMs: number,
+  ): Promise<Result<void>> {
+    if (ttlMs <= 0) {
+      return err(
+        authError.internalError(
+          `saveScratch: ttlMs must be positive, got ${ttlMs}`,
+        ),
+      )
+    }
+    const expiresAtMs = this.#clock() + ttlMs
+    try {
+      // Unconditional put — scratch overwrites any prior value for the key.
+      await this.#exec.put({
+        item: {
+          pk: "scratch",
+          sk: key,
+          value,
+          expires_at: expiresAtMs,
+          ttl: Math.floor(expiresAtMs / 1000),
+        },
+      })
+    } catch (e) {
+      return err(authError.internalError("saveScratch: put failed", e))
+    }
+    return ok(undefined)
+  }
+
+  async readScratch(key: string): Promise<Result<string>> {
+    let row: Record<string, unknown> | undefined
+    try {
+      row = await this.#exec.get({
+        key: { pk: "scratch", sk: key },
+        consistentRead: true,
+      })
+    } catch (e) {
+      return err(authError.internalError("readScratch: get failed", e))
+    }
+    if (!row) {
+      return err(authError.unknownState(`scratch "${key}" unknown`))
+    }
+    // Native DynamoDB TTL eviction is best-effort (can lag up to ~48h), so
+    // filter on the adapter clock for correctness.
+    if (this.#clock() >= Number(row.expires_at)) {
+      try {
+        await this.#exec.delete({ key: { pk: "scratch", sk: key } })
+      } catch {}
+      return err(authError.unknownState(`scratch "${key}" expired`))
+    }
+    return ok(String(row.value))
+  }
+
+  async deleteScratch(key: string): Promise<Result<void>> {
+    try {
+      await this.#exec.delete({ key: { pk: "scratch", sk: key } })
+    } catch (e) {
+      return err(authError.internalError("deleteScratch: delete failed", e))
+    }
+    return ok(undefined)
+  }
 }
 
 function parseFlowPayload(raw: unknown): FlowRecord {

package/src/adapters/memory/session-store.ts

@@ -8,7 +8,11 @@
  */
 import { authError } from "../../types/error"
 import type { FlowRecord } from "../../types/flow"
-import type { SessionRecord, SessionStore } from "../../ports/session-store"
+import type {
+  ParRecord,
+  SessionRecord,
+  SessionStore,
+} from "../../ports/session-store"
 import type { Result } from "../../types/result"
 import { err, ok } from "../../types/result"
 import type { Clock } from "./clock"
@@ -19,6 +23,16 @@ type StoredFlow = {
   expiresAt: number
 }
 
+type StoredPar = {
+  record: ParRecord
+  expiresAt: number
+}
+
+type StoredScratch = {
+  value: string
+  expiresAt: number
+}
+
 export type MemorySessionStoreOptions = {
   clock?: Clock
 }
@@ -27,6 +41,8 @@ export class MemorySessionStore implements SessionStore {
   #clock: Clock
   #flows = new Map<string, StoredFlow>()
   #sessions = new Map<string, SessionRecord>()
+  #par = new Map<string, StoredPar>()
+  #scratch = new Map<string, StoredScratch>()
 
   constructor(opts: MemorySessionStoreOptions = {}) {
     this.#clock = opts.clock ?? realClock
@@ -125,4 +141,70 @@ export class MemorySessionStore implements SessionStore {
     this.#sessions.delete(sessionId)
     return ok(undefined)
   }
+
+  async savePar(
+    requestUri: string,
+    payload: ParRecord,
+    ttl: number,
+  ): Promise<Result<void>> {
+    if (ttl <= 0) {
+      return err(
+        authError.internalError(`savePar: ttl must be positive, got ${ttl}`),
+      )
+    }
+    this.#par.set(requestUri, {
+      record: payload,
+      expiresAt: this.#clock() + ttl,
+    })
+    return ok(undefined)
+  }
+
+  async consumePar(requestUri: string): Promise<Result<ParRecord>> {
+    const stored = this.#par.get(requestUri)
+    if (!stored) {
+      return err(
+        authError.unknownState(
+          `par "${requestUri}" unknown or already consumed`,
+        ),
+      )
+    }
+    this.#par.delete(requestUri)
+    if (this.#clock() >= stored.expiresAt) {
+      return err(authError.unknownState(`par "${requestUri}" expired`))
+    }
+    return ok(stored.record)
+  }
+
+  async saveScratch(
+    key: string,
+    value: string,
+    ttlMs: number,
+  ): Promise<Result<void>> {
+    if (ttlMs <= 0) {
+      return err(
+        authError.internalError(
+          `saveScratch: ttlMs must be positive, got ${ttlMs}`,
+        ),
+      )
+    }
+    this.#scratch.set(key, { value, expiresAt: this.#clock() + ttlMs })
+    return ok(undefined)
+  }
+
+  async readScratch(key: string): Promise<Result<string>> {
+    const stored = this.#scratch.get(key)
+    if (!stored) {
+      return err(authError.unknownState(`scratch "${key}" unknown`))
+    }
+    if (this.#clock() >= stored.expiresAt) {
+      this.#scratch.delete(key)
+      return err(authError.unknownState(`scratch "${key}" expired`))
+    }
+    return ok(stored.value)
+  }
+
+  async deleteScratch(key: string): Promise<Result<void>> {
+    this.#scratch.delete(key)
+    return ok(undefined)
+  }
 }

package/src/adapters/memory/token-store.ts

@@ -43,6 +43,8 @@ export class MemoryTokenStore implements TokenStore {
   #clock: Clock
   #codes = new Map<string, StoredCode>()
   #refresh = new Map<string, StoredRefresh>()
+  /** DPoP proof `jti` replay-protection map. Value is expiry timestamp. */
+  #dpopJtis = new Map<string, number>()
 
   constructor(opts: MemoryTokenStoreOptions = {}) {
     this.#clock = opts.clock ?? realClock
@@ -162,4 +164,18 @@ export class MemoryTokenStore implements TokenStore {
     }
     return ok(undefined)
   }
+
+  async recordDpopJti(jti: string, ttlMs: number): Promise<Result<void>> {
+    const now = this.#clock()
+    // Sweep expired entries opportunistically — keeps the map bounded
+    // under sustained load without a separate GC pass.
+    for (const [k, exp] of this.#dpopJtis) {
+      if (exp <= now) this.#dpopJtis.delete(k)
+    }
+    if (this.#dpopJtis.has(jti)) {
+      return err(authError.invalidGrant(`dpop jti "${jti}" replayed`))
+    }
+    this.#dpopJtis.set(jti, now + ttlMs)
+    return ok(undefined)
+  }
 }

package/src/adapters/postgres/migrations.ts

@@ -89,6 +89,12 @@ CREATE TABLE IF NOT EXISTS openauth_sessions (
   expires_at bigint NOT NULL
 );
 
+CREATE TABLE IF NOT EXISTS openauth_scratch (
+  scratch_key text PRIMARY KEY,
+  value text NOT NULL,
+  expires_at bigint NOT NULL
+);
+
 CREATE TABLE IF NOT EXISTS openauth_audit_events (
   id bigserial PRIMARY KEY,
   ts bigint NOT NULL,

package/src/adapters/postgres/session-store.ts

@@ -203,6 +203,75 @@ export class PostgresSessionStore implements SessionStore {
     }
     return ok(undefined)
   }
+
+  async saveScratch(
+    key: string,
+    value: string,
+    ttlMs: number,
+  ): Promise<Result<void>> {
+    if (ttlMs <= 0) {
+      return err(
+        authError.internalError(
+          `saveScratch: ttlMs must be positive, got ${ttlMs}`,
+        ),
+      )
+    }
+    const expiresAt = this.#clock() + ttlMs
+    try {
+      await this.#exec.query(
+        `INSERT INTO openauth_scratch (scratch_key, value, expires_at)
+         VALUES ($1, $2, $3)
+         ON CONFLICT (scratch_key)
+         DO UPDATE SET value = EXCLUDED.value, expires_at = EXCLUDED.expires_at`,
+        [key, value, expiresAt],
+      )
+    } catch (e) {
+      return err(authError.internalError("saveScratch: upsert failed", e))
+    }
+    return ok(undefined)
+  }
+
+  async readScratch(key: string): Promise<Result<string>> {
+    let row: { value: string; expires_at: string | number } | undefined
+    try {
+      const result = await this.#exec.query<{
+        value: string
+        expires_at: string | number
+      }>(
+        `SELECT value, expires_at FROM openauth_scratch WHERE scratch_key = $1`,
+        [key],
+      )
+      row = result.rows[0]
+    } catch (e) {
+      return err(authError.internalError("readScratch: query failed", e))
+    }
+    if (!row) {
+      return err(authError.unknownState(`scratch "${key}" unknown`))
+    }
+    if (this.#clock() >= Number(row.expires_at)) {
+      // Lazy GC — best-effort, don't fail the read if the delete races.
+      try {
+        await this.#exec.query(
+          `DELETE FROM openauth_scratch WHERE scratch_key = $1`,
+          [key],
+        )
+      } catch {}
+      return err(authError.unknownState(`scratch "${key}" expired`))
+    }
+    return ok(row.value)
+  }
+
+  async deleteScratch(key: string): Promise<Result<void>> {
+    try {
+      await this.#exec.query(
+        `DELETE FROM openauth_scratch WHERE scratch_key = $1`,
+        [key],
+      )
+    } catch (e) {
+      return err(authError.internalError("deleteScratch: delete failed", e))
+    }
+    return ok(undefined)
+  }
 }
 
 function parseFlowRecord(raw: unknown): FlowRecord {