@_mustachio/openauth 0.9.2 → 0.11.0

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

@@ -0,0 +1,230 @@
+/**
+ * D1 `SessionStore`. Flow records + optional long-lived sessions.
+ *
+ * `consumeFlow` is `DELETE … RETURNING payload, expires_at` — atomic
+ * single-winner. `updateFlowMethodState` re-serializes the entire payload
+ * blob (SQLite has no `jsonb_set`); the read-then-write is wrapped inside
+ * the same `primarySession` so the bookmark advances atomically.
+ */
+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 { primarySession } from "./session"
+import type { AnyD1Database } from "./types"
+
+export type D1SessionStoreOptions = {
+  db: AnyD1Database
+  clock?: () => number
+}
+
+export class D1SessionStore implements SessionStore {
+  #db: AnyD1Database
+  #clock: () => number
+
+  constructor(opts: D1SessionStoreOptions) {
+    this.#db = opts.db
+    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 expiresAt = this.#clock() + ttl
+    try {
+      await primarySession(this.#db)
+        .prepare(
+          `INSERT INTO openauth_flows (flow_id, payload, expires_at) VALUES (?1, ?2, ?3)`,
+        )
+        .bind(flowId, JSON.stringify(payload), expiresAt)
+        .run()
+    } catch (e) {
+      return err(authError.internalError("saveFlow: insert failed", e))
+    }
+    return ok(undefined)
+  }
+
+  async updateFlowMethodState(
+    flowId: string,
+    methodState: unknown,
+  ): Promise<Result<void>> {
+    const now = this.#clock()
+    const session = primarySession(this.#db)
+    let row: { payload: string; expires_at: number } | null
+    try {
+      row = await session
+        .prepare(
+          `SELECT payload, expires_at FROM openauth_flows WHERE flow_id = ?1`,
+        )
+        .bind(flowId)
+        .first<{ payload: string; expires_at: number }>()
+    } catch (e) {
+      return err(
+        authError.internalError("updateFlowMethodState: read failed", e),
+      )
+    }
+    if (!row) {
+      return err(authError.unknownState(`flow "${flowId}" unknown`))
+    }
+    if (now >= Number(row.expires_at)) {
+      return err(authError.unknownState(`flow "${flowId}" expired`))
+    }
+    let parsed: FlowRecord
+    try {
+      parsed = JSON.parse(row.payload) as FlowRecord
+    } catch (e) {
+      return err(
+        authError.internalError("updateFlowMethodState: parse failed", e),
+      )
+    }
+    const next = { ...parsed, methodState }
+    try {
+      // Conditional write — only update if the row still exists AND has
+      // matching expiry. If a concurrent consume snuck in, the WHERE clause
+      // misses and we surface `unknown_state`.
+      const result = await session
+        .prepare(
+          `UPDATE openauth_flows SET payload = ?1
+            WHERE flow_id = ?2 AND expires_at > ?3
+            RETURNING 1 AS hit`,
+        )
+        .bind(JSON.stringify(next), flowId, now)
+        .first<{ hit: number }>()
+      if (!result) {
+        return err(
+          authError.unknownState(`flow "${flowId}" unknown or expired`),
+        )
+      }
+    } catch (e) {
+      return err(
+        authError.internalError("updateFlowMethodState: update failed", e),
+      )
+    }
+    return ok(undefined)
+  }
+
+  async readFlow(flowId: string): Promise<Result<FlowRecord>> {
+    let row: { payload: string; expires_at: number } | null
+    try {
+      row = await primarySession(this.#db)
+        .prepare(
+          `SELECT payload, expires_at FROM openauth_flows WHERE flow_id = ?1`,
+        )
+        .bind(flowId)
+        .first<{ payload: string; expires_at: number }>()
+    } catch (e) {
+      return err(authError.internalError("readFlow: query failed", e))
+    }
+    if (!row) {
+      return err(authError.unknownState(`flow "${flowId}" unknown`))
+    }
+    if (this.#clock() >= Number(row.expires_at)) {
+      try {
+        await primarySession(this.#db)
+          .prepare(`DELETE FROM openauth_flows WHERE flow_id = ?1`)
+          .bind(flowId)
+          .run()
+      } catch {}
+      return err(authError.unknownState(`flow "${flowId}" expired`))
+    }
+    return ok(JSON.parse(row.payload) as FlowRecord)
+  }
+
+  async consumeFlow(flowId: string): Promise<Result<FlowRecord>> {
+    let row: { payload: string; expires_at: number } | null
+    try {
+      row = await primarySession(this.#db)
+        .prepare(
+          `DELETE FROM openauth_flows WHERE flow_id = ?1 RETURNING payload, expires_at`,
+        )
+        .bind(flowId)
+        .first<{ payload: string; expires_at: number }>()
+    } catch (e) {
+      return err(authError.internalError("consumeFlow: query failed", e))
+    }
+    if (!row) {
+      return err(
+        authError.unknownState(`flow "${flowId}" unknown or already consumed`),
+      )
+    }
+    if (this.#clock() >= Number(row.expires_at)) {
+      return err(authError.unknownState(`flow "${flowId}" expired`))
+    }
+    return ok(JSON.parse(row.payload) as FlowRecord)
+  }
+
+  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 expiresAt = this.#clock() + ttl
+    try {
+      await primarySession(this.#db)
+        .prepare(
+          `INSERT INTO openauth_sessions (session_id, payload, expires_at) VALUES (?1, ?2, ?3)
+           ON CONFLICT(session_id) DO UPDATE SET payload = excluded.payload, expires_at = excluded.expires_at`,
+        )
+        .bind(sessionId, JSON.stringify(payload), expiresAt)
+        .run()
+    } catch (e) {
+      return err(authError.internalError("createSession: insert failed", e))
+    }
+    return ok(undefined)
+  }
+
+  async readSession(sessionId: string): Promise<Result<SessionRecord>> {
+    let row: { payload: string; expires_at: number } | null
+    try {
+      row = await primarySession(this.#db)
+        .prepare(
+          `SELECT payload, expires_at FROM openauth_sessions WHERE session_id = ?1`,
+        )
+        .bind(sessionId)
+        .first<{ payload: string; expires_at: number }>()
+    } catch (e) {
+      return err(authError.internalError("readSession: query failed", e))
+    }
+    if (!row) {
+      return err(authError.invalidRequest(`session "${sessionId}" unknown`))
+    }
+    if (this.#clock() >= Number(row.expires_at)) {
+      try {
+        await primarySession(this.#db)
+          .prepare(`DELETE FROM openauth_sessions WHERE session_id = ?1`)
+          .bind(sessionId)
+          .run()
+      } catch {}
+      return err(authError.invalidRequest(`session "${sessionId}" expired`))
+    }
+    return ok(JSON.parse(row.payload) as SessionRecord)
+  }
+
+  async revokeSession(sessionId: string): Promise<Result<void>> {
+    try {
+      await primarySession(this.#db)
+        .prepare(`DELETE FROM openauth_sessions WHERE session_id = ?1`)
+        .bind(sessionId)
+        .run()
+    } catch (e) {
+      return err(authError.internalError("revokeSession: delete failed", e))
+    }
+    return ok(undefined)
+  }
+}

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"