@_mustachio/openauth 0.9.2 → 0.10.0

package/src/adapters/d1/session.ts

@@ -0,0 +1,38 @@
+/**
+ * Sessions-API helper. Wraps a `D1Database` in a session pinned to the
+ * primary node for read-after-write consistency on security-critical paths.
+ *
+ * If the bundled `D1Database` lacks `withSession` (older runtime), the
+ * helper returns the plain `db` and the caller pays no Sessions-API cost
+ * (and gets eventual-consistency reads — documented in the adapter's
+ * top-level JSDoc).
+ */
+import type {
+  AnyD1Database,
+  D1DatabaseSession,
+  D1DatabaseWithSessions,
+} from "./types"
+
+export function isSessionsCapable(
+  db: AnyD1Database,
+): db is D1DatabaseWithSessions {
+  return typeof (db as D1DatabaseWithSessions).withSession === "function"
+}
+
+/**
+ * Open a Sessions-API session pinned to the primary node. All `prepare` calls
+ * inside the session see the latest writes; bookmarks may be threaded across
+ * requests by the caller if needed.
+ */
+export function primarySession(db: AnyD1Database): D1DatabaseSession {
+  if (isSessionsCapable(db)) {
+    return db.withSession("first-primary")
+  }
+  // Test shim / older runtime — fall back to the database itself, which
+  // exposes the same `prepare` / `batch` shape. `getBookmark` returns null.
+  return {
+    prepare: (q) => db.prepare(q),
+    batch: (s) => db.batch(s),
+    getBookmark: () => null,
+  }
+}

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

@@ -0,0 +1,251 @@
+/**
+ * D1 `TokenStore`. SQL-identical to the Postgres adapter except for SQLite
+ * dialect (`?N` binds, JSON-as-TEXT, BLOB) and the Sessions-API wrapping
+ * for read-after-write consistency.
+ *
+ * Every operation here is on the security-critical path and uses
+ * `primarySession(db)` so reads always see the latest write — per AD8 + the
+ * D1 read-replication caveat in `ports/CONSISTENCY.md`.
+ */
+import { AUTH_CODE_TTL_MS } from "../../domain/authorize"
+import type { KeyStore } from "../../ports/key-store"
+import type { TokenStore } from "../../ports/token-store"
+import { authError } from "../../types/error"
+import type { Result } from "../../types/result"
+import { err, ok } from "../../types/result"
+import type { TenantId } from "../../types/tenant"
+import type { RefreshTokenPayload } from "../../types/token"
+
+import { primarySession } from "./session"
+import type { AnyD1Database } from "./types"
+
+export type D1TokenStoreOptions = {
+  db: AnyD1Database
+  /**
+   * Optional — retained for API stability after M1 moved code-payload
+   * encryption to the domain layer. The adapter no longer touches it.
+   */
+  keyStore?: KeyStore
+  clock?: () => number
+}
+
+export class D1TokenStore implements TokenStore {
+  #db: AnyD1Database
+  #clock: () => number
+
+  constructor(opts: D1TokenStoreOptions) {
+    this.#db = opts.db
+    this.#clock = opts.clock ?? (() => Date.now())
+  }
+
+  async saveCode(
+    code: string,
+    ciphertext: string,
+    ttl: number,
+  ): Promise<Result<void>> {
+    if (ttl <= 0 || ttl > AUTH_CODE_TTL_MS) {
+      return err(
+        authError.internalError(
+          `saveCode: ttl ${ttl} outside (0, ${AUTH_CODE_TTL_MS}] (auth-code TTL is fixed at 60s by OAuth 2.1 BCP)`,
+        ),
+      )
+    }
+    const expiresAt = this.#clock() + ttl
+    try {
+      await primarySession(this.#db)
+        .prepare(
+          `INSERT INTO openauth_codes (code, ciphertext, expires_at) VALUES (?1, ?2, ?3)`,
+        )
+        .bind(code, ciphertext, expiresAt)
+        .run()
+    } catch (e) {
+      return err(authError.internalError("saveCode: insert failed", e))
+    }
+    return ok(undefined)
+  }
+
+  async consumeCode(code: string): Promise<Result<string>> {
+    let row: { ciphertext: string; expires_at: number } | null
+    try {
+      row = await primarySession(this.#db)
+        .prepare(
+          `DELETE FROM openauth_codes WHERE code = ?1 RETURNING ciphertext, expires_at`,
+        )
+        .bind(code)
+        .first<{ ciphertext: string; expires_at: number }>()
+    } catch (e) {
+      return err(authError.internalError("consumeCode: query failed", e))
+    }
+    if (!row) {
+      return err(
+        authError.invalidGrant("auth code unknown or already consumed"),
+      )
+    }
+    if (this.#clock() >= Number(row.expires_at)) {
+      return err(authError.invalidGrant("auth code expired"))
+    }
+    return ok(row.ciphertext)
+  }
+
+  async saveRefresh(
+    refresh: string,
+    payload: RefreshTokenPayload,
+  ): Promise<Result<void>> {
+    try {
+      await primarySession(this.#db)
+        .prepare(
+          `INSERT INTO openauth_refresh_tokens
+             (token, tenant_id, client_id, subject_id, family, expires_at, payload)
+           VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7)`,
+        )
+        .bind(
+          refresh,
+          payload.tenantId,
+          payload.clientId,
+          payload.subjectId,
+          payload.family,
+          payload.expiresAt,
+          JSON.stringify(payload),
+        )
+        .run()
+    } catch (e) {
+      return err(authError.internalError("saveRefresh: insert failed", e))
+    }
+    return ok(undefined)
+  }
+
+  async consumeRefresh(
+    refresh: string,
+    options: { reuseWindowMs?: number } = {},
+  ): Promise<Result<RefreshTokenPayload>> {
+    const reuseWindow = options.reuseWindowMs ?? 60_000
+    const now = this.#clock()
+    const session = primarySession(this.#db)
+    // Atomic claim — SQLite's UPDATE ... RETURNING is available from 3.35
+    // (D1 ships much newer). One row out means we won the race.
+    let claimed: { payload: string } | null
+    try {
+      claimed = await session
+        .prepare(
+          `UPDATE openauth_refresh_tokens
+             SET consumed_at = ?1
+           WHERE token = ?2
+             AND consumed_at IS NULL
+             AND expires_at > ?1
+           RETURNING payload`,
+        )
+        .bind(now, refresh)
+        .first<{ payload: string }>()
+    } catch (e) {
+      return err(authError.internalError("consumeRefresh: claim failed", e))
+    }
+    if (claimed) {
+      return ok(parseRefresh(claimed.payload))
+    }
+    // No claim — figure out why.
+    let existing: {
+      consumed_at: number | null
+      expires_at: number
+      payload: string
+    } | null
+    try {
+      existing = await session
+        .prepare(
+          `SELECT consumed_at, expires_at, payload
+             FROM openauth_refresh_tokens
+            WHERE token = ?1`,
+        )
+        .bind(refresh)
+        .first<{
+          consumed_at: number | null
+          expires_at: number
+          payload: string
+        }>()
+    } catch (e) {
+      return err(authError.internalError("consumeRefresh: lookup failed", e))
+    }
+    if (!existing) {
+      return err(authError.invalidGrant("refresh token unknown"))
+    }
+    if (existing.consumed_at !== null && existing.consumed_at !== undefined) {
+      const consumedAt = Number(existing.consumed_at)
+      const withinWindow = now - consumedAt <= reuseWindow
+      if (withinWindow) {
+        const payload = parseRefresh(existing.payload)
+        await this.revokeFamily(payload.family)
+        return err(
+          authError.invalidGrant(
+            `refresh token reuse detected (family=${payload.family})`,
+            {
+              family: payload.family,
+              tenantId: payload.tenantId,
+              subjectId: payload.subjectId,
+            },
+          ),
+        )
+      }
+      return err(authError.invalidGrant("refresh token already consumed"))
+    }
+    if (now >= Number(existing.expires_at)) {
+      return err(authError.invalidGrant("refresh token expired"))
+    }
+    return err(authError.internalError("consumeRefresh: unexplained miss"))
+  }
+
+  async peekRefresh(refresh: string): Promise<Result<RefreshTokenPayload>> {
+    let row: { expires_at: number; payload: string } | null
+    try {
+      row = await primarySession(this.#db)
+        .prepare(
+          `SELECT expires_at, payload
+             FROM openauth_refresh_tokens
+            WHERE token = ?1`,
+        )
+        .bind(refresh)
+        .first<{ expires_at: number; payload: string }>()
+    } catch (e) {
+      return err(authError.internalError("peekRefresh: lookup failed", e))
+    }
+    if (!row) {
+      return err(authError.invalidGrant("refresh token unknown"))
+    }
+    if (this.#clock() >= Number(row.expires_at)) {
+      return err(authError.invalidGrant("refresh token expired"))
+    }
+    return ok(parseRefresh(row.payload))
+  }
+
+  async revokeFamily(family: string): Promise<Result<void>> {
+    try {
+      await primarySession(this.#db)
+        .prepare(`DELETE FROM openauth_refresh_tokens WHERE family = ?1`)
+        .bind(family)
+        .run()
+    } catch (e) {
+      return err(authError.internalError("revokeFamily: delete failed", e))
+    }
+    return ok(undefined)
+  }
+
+  async revokeBySubject(
+    tenantId: TenantId,
+    subjectId: string,
+  ): Promise<Result<void>> {
+    try {
+      await primarySession(this.#db)
+        .prepare(
+          `DELETE FROM openauth_refresh_tokens WHERE tenant_id = ?1 AND subject_id = ?2`,
+        )
+        .bind(tenantId, subjectId)
+        .run()
+    } catch (e) {
+      return err(authError.internalError("revokeBySubject: delete failed", e))
+    }
+    return ok(undefined)
+  }
+}
+
+function parseRefresh(raw: string | RefreshTokenPayload): RefreshTokenPayload {
+  if (typeof raw === "string") return JSON.parse(raw) as RefreshTokenPayload
+  return raw
+}

package/src/adapters/d1/types.ts

@@ -0,0 +1,53 @@
+/**
+ * D1 type extensions.
+ *
+ * `@cloudflare/workers-types` < 2024-12 does not yet expose the D1 Sessions
+ * API on its `D1Database` class. We declare the augmentation locally and
+ * feature-detect at runtime: if `db.withSession` is a function the adapter
+ * uses it for read-after-write consistency on the security-critical paths;
+ * otherwise it falls back to plain `prepare`. This keeps the adapter
+ * type-safe today and forward-compatible when the workers-types release
+ * catches up.
+ */
+import type {
+  D1Database,
+  D1PreparedStatement,
+  D1Result,
+} from "@cloudflare/workers-types"
+
+/**
+ * D1 Sessions API constraints. Documented at
+ * <https://developers.cloudflare.com/d1/best-practices/read-replication/>.
+ *  - `"first-primary"` — pin the session to the primary node. All reads see
+ *    the latest write. Used for security-critical paths.
+ *  - `"first-unconstrained"` — pin to whichever node responds first. Lower
+ *    latency, eventual consistency. Used for JWKS / config reads.
+ */
+export type D1SessionConstraint = "first-primary" | "first-unconstrained"
+
+/** A session bookmark — opaque token returned by `getBookmark()`. */
+export type D1SessionBookmark = string
+
+/** Minimal shape we use from `D1DatabaseSession`. */
+export type D1DatabaseSession = {
+  prepare(query: string): D1PreparedStatement
+  batch<T = unknown>(statements: D1PreparedStatement[]): Promise<D1Result<T>[]>
+  getBookmark(): D1SessionBookmark | null
+}
+
+/**
+ * `D1Database` with the Sessions API. Use this type at the adapter boundary;
+ * the runtime feature-detects `withSession` so consumers can still pass a
+ * plain `D1Database` if Sessions is unavailable in their environment.
+ */
+export type D1DatabaseWithSessions = D1Database & {
+  withSession(
+    constraintOrBookmark?: D1SessionConstraint | D1SessionBookmark,
+  ): D1DatabaseSession
+}
+
+/**
+ * Either a real D1Database or our test shim. Feature detection happens at
+ * call time so the adapter still works against both.
+ */
+export type AnyD1Database = D1Database | D1DatabaseWithSessions

package/src/adapters/durable-object/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Cloudflare Durable Objects adapters.
+ *
+ * Durable Objects are an excellent fit for `SessionStore` (flow records)
+ * because every operation on a single DO instance is serialized — atomic
+ * delete-on-read comes for free with `storage.transaction`. Per
+ * `ports/CONSISTENCY.md`, DOs are also acceptable for `TokenStore` in
+ * deployments that don't run D1.
+ *
+ * The adapter is supplied a `DurableObjectStorage` directly (`this.ctx.storage`
+ * from inside a DO class). Users wire their own DO class around the adapter
+ * and forward RPC / fetch calls to the methods. See the JSDoc on
+ * `DurableObjectSessionStore` for the canonical wiring pattern.
+ */
+export {
+  DurableObjectSessionStore,
+  type DurableObjectSessionStoreOptions,
+} from "./session-store"
+
+export type {
+  DurableObjectStorageLike,
+  DurableObjectTransactionLike,
+} from "./types"

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

@@ -0,0 +1,227 @@
+/**
+ * Durable Objects `SessionStore`. Per `ports/CONSISTENCY.md`, DOs are an
+ * acceptable backing store for `SessionStore` (and optionally `TokenStore`)
+ * because every operation on a single DO instance is serialized — atomic
+ * delete-on-read comes for free with `storage.transaction`.
+ *
+ * Wiring pattern: the adapter accepts a `DurableObjectStorage` reference,
+ * which the user supplies from inside their own DO class (`this.ctx.storage`).
+ * The user is responsible for routing requests to the right DO instance —
+ * typically one DO per flow-id (`namespace.idFromName(flowId)`), which keeps
+ * the per-flow state co-located and serialized.
+ *
+ * @example
+ *   // Worker module export
+ *   export class IdpSessionDO {
+ *     constructor(ctx) {
+ *       this.store = new DurableObjectSessionStore({ storage: ctx.storage })
+ *     }
+ *     async fetch(req) {
+ *       const { op, args } = await req.json()
+ *       const result = await (this.store as any)[op](...args)
+ *       return Response.json(result)
+ *     }
+ *   }
+ *
+ *   // Caller — round-trips through fetch
+ *   const stub = env.IDP_SESSIONS.get(env.IDP_SESSIONS.idFromName(flowId))
+ *   await stub.fetch("https://internal/", {
+ *     method: "POST",
+ *     body: JSON.stringify({ op: "consumeFlow", args: [flowId] }),
+ *   })
+ */
+import { authError } from "../../types/error"
+import type { FlowRecord } from "../../types/flow"
+import type { SessionRecord, SessionStore } from "../../ports/session-store"
+import type { Result } from "../../types/result"
+import { err, ok } from "../../types/result"
+
+import type {
+  DurableObjectStorageLike,
+  DurableObjectTransactionLike,
+} from "./types"
+
+type StoredFlow = {
+  record: FlowRecord
+  expiresAt: number
+}
+
+type StoredSession = {
+  record: SessionRecord
+  expiresAt: number
+}
+
+export type DurableObjectSessionStoreOptions = {
+  storage: DurableObjectStorageLike
+  clock?: () => number
+}
+
+export class DurableObjectSessionStore implements SessionStore {
+  #storage: DurableObjectStorageLike
+  #clock: () => number
+
+  constructor(opts: DurableObjectSessionStoreOptions) {
+    this.#storage = opts.storage
+    this.#clock = opts.clock ?? (() => Date.now())
+  }
+
+  async saveFlow(
+    flowId: string,
+    payload: FlowRecord,
+    ttl: number,
+  ): Promise<Result<void>> {
+    if (ttl <= 0) {
+      return err(
+        authError.internalError(`saveFlow: ttl must be positive, got ${ttl}`),
+      )
+    }
+    const stored: StoredFlow = {
+      record: payload,
+      expiresAt: this.#clock() + ttl,
+    }
+    try {
+      await this.#storage.put(flowKey(flowId), stored)
+    } catch (e) {
+      return err(authError.internalError("saveFlow: put failed", e))
+    }
+    return ok(undefined)
+  }
+
+  async updateFlowMethodState(
+    flowId: string,
+    methodState: unknown,
+  ): Promise<Result<void>> {
+    const now = this.#clock()
+    try {
+      // Transaction so the read-then-write is atomic against concurrent
+      // consumers on the same DO.
+      const outcome = await this.#storage.transaction(async (txn) => {
+        const existing = await txn.get<StoredFlow>(flowKey(flowId))
+        if (!existing) return "unknown" as const
+        if (now >= existing.expiresAt) return "expired" as const
+        await txn.put(flowKey(flowId), {
+          record: { ...existing.record, methodState },
+          expiresAt: existing.expiresAt,
+        })
+        return "ok" as const
+      })
+      if (outcome === "unknown")
+        return err(authError.unknownState(`flow "${flowId}" unknown`))
+      if (outcome === "expired")
+        return err(authError.unknownState(`flow "${flowId}" expired`))
+    } catch (e) {
+      return err(
+        authError.internalError("updateFlowMethodState: transaction failed", e),
+      )
+    }
+    return ok(undefined)
+  }
+
+  async readFlow(flowId: string): Promise<Result<FlowRecord>> {
+    let stored: StoredFlow | undefined
+    try {
+      stored = await this.#storage.get<StoredFlow>(flowKey(flowId))
+    } catch (e) {
+      return err(authError.internalError("readFlow: get failed", e))
+    }
+    if (!stored) {
+      return err(authError.unknownState(`flow "${flowId}" unknown`))
+    }
+    if (this.#clock() >= stored.expiresAt) {
+      try {
+        await this.#storage.delete(flowKey(flowId))
+      } catch {}
+      return err(authError.unknownState(`flow "${flowId}" expired`))
+    }
+    return ok(stored.record)
+  }
+
+  async consumeFlow(flowId: string): Promise<Result<FlowRecord>> {
+    let result:
+      | { kind: "miss" }
+      | { kind: "expired" }
+      | { kind: "hit"; record: FlowRecord }
+    try {
+      result = await this.#storage.transaction(async (txn) => {
+        const stored = await txn.get<StoredFlow>(flowKey(flowId))
+        if (!stored) return { kind: "miss" as const }
+        // Delete first to enforce single-winner semantics — any other caller
+        // racing on the same flowId will see the key gone on its read.
+        await txn.delete(flowKey(flowId))
+        if (this.#clock() >= stored.expiresAt) {
+          return { kind: "expired" as const }
+        }
+        return { kind: "hit" as const, record: stored.record }
+      })
+    } catch (e) {
+      return err(authError.internalError("consumeFlow: transaction failed", e))
+    }
+    if (result.kind === "miss") {
+      return err(
+        authError.unknownState(`flow "${flowId}" unknown or already consumed`),
+      )
+    }
+    if (result.kind === "expired") {
+      return err(authError.unknownState(`flow "${flowId}" expired`))
+    }
+    return ok(result.record)
+  }
+
+  async createSession(
+    sessionId: string,
+    payload: SessionRecord,
+    ttl: number,
+  ): Promise<Result<void>> {
+    if (ttl <= 0) {
+      return err(
+        authError.internalError(
+          `createSession: ttl must be positive, got ${ttl}`,
+        ),
+      )
+    }
+    const stored: StoredSession = {
+      record: payload,
+      expiresAt: this.#clock() + ttl,
+    }
+    try {
+      await this.#storage.put(sessionKey(sessionId), stored)
+    } catch (e) {
+      return err(authError.internalError("createSession: put failed", e))
+    }
+    return ok(undefined)
+  }
+
+  async readSession(sessionId: string): Promise<Result<SessionRecord>> {
+    let stored: StoredSession | undefined
+    try {
+      stored = await this.#storage.get<StoredSession>(sessionKey(sessionId))
+    } catch (e) {
+      return err(authError.internalError("readSession: get failed", e))
+    }
+    if (!stored) {
+      return err(authError.invalidRequest(`session "${sessionId}" unknown`))
+    }
+    if (this.#clock() >= stored.expiresAt) {
+      try {
+        await this.#storage.delete(sessionKey(sessionId))
+      } catch {}
+      return err(authError.invalidRequest(`session "${sessionId}" expired`))
+    }
+    return ok(stored.record)
+  }
+
+  async revokeSession(sessionId: string): Promise<Result<void>> {
+    try {
+      await this.#storage.delete(sessionKey(sessionId))
+    } catch (e) {
+      return err(authError.internalError("revokeSession: delete failed", e))
+    }
+    return ok(undefined)
+  }
+}
+
+const flowKey = (flowId: string) => `flow:${flowId}`
+const sessionKey = (sessionId: string) => `session:${sessionId}`
+
+// Re-exported for adapter users wiring `storage.transaction` callbacks.
+export type { DurableObjectStorageLike, DurableObjectTransactionLike }

package/src/adapters/durable-object/types.ts

@@ -0,0 +1,25 @@
+/**
+ * Minimal `DurableObjectStorage` shape the adapter depends on. Defined
+ * locally so the adapter is testable without a real Workers runtime and so
+ * it stays compatible with both legacy and current versions of
+ * `@cloudflare/workers-types`.
+ *
+ * Real `DurableObjectStorage` instances satisfy this interface — pass
+ * `this.ctx.storage` directly.
+ */
+export type DurableObjectTransactionLike = {
+  get<T>(key: string): Promise<T | undefined>
+  put<T>(key: string, value: T): Promise<void>
+  delete(key: string): Promise<boolean>
+}
+
+export type DurableObjectStorageLike = DurableObjectTransactionLike & {
+  /**
+   * Run a closure atomically. On any DO, all operations within `closure`
+   * see a consistent snapshot of storage; the closure's return value is
+   * resolved after the writes are durable.
+   */
+  transaction<T>(
+    closure: (txn: DurableObjectTransactionLike) => Promise<T>,
+  ): Promise<T>
+}

package/src/adapters/dynamo/audit-log.ts

@@ -0,0 +1,35 @@
+/**
+ * DynamoDB `AuditLog`. `pk="audit"`, `sk="<paddedTs>:<rand>"` so a Query
+ * pulls events in insertion order. As with all `AuditLog` adapters, `log()`
+ * never throws — durability failures are swallowed so the IdP's hot paths
+ * are not gated on the log.
+ */
+import type { AuditEvent, AuditLog } from "../../ports/audit-log"
+
+import type { DynamoExecutor } from "./client"
+
+export type DynamoAuditLogOptions = {
+  exec: DynamoExecutor
+}
+
+export class DynamoAuditLog implements AuditLog {
+  #exec: DynamoExecutor
+
+  constructor(opts: DynamoAuditLogOptions) {
+    this.#exec = opts.exec
+  }
+
+  async log(event: AuditEvent & { timestamp: number }): Promise<void> {
+    const padded = String(event.timestamp).padStart(16, "0")
+    const suffix = Math.random().toString(36).slice(2, 10)
+    try {
+      await this.#exec.put({
+        item: {
+          pk: "audit",
+          sk: `${padded}:${suffix}`,
+          payload: JSON.stringify(event),
+        },
+      })
+    } catch {}
+  }
+}