@_mustachio/openauth 0.9.2 → 0.11.0

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 {}
+  }
+}

package/src/adapters/dynamo/client.ts

@@ -0,0 +1,118 @@
+/**
+ * `DynamoExecutor` — the operation surface the adapters depend on.
+ *
+ * Keeps the AWS SDK out of the adapter's import graph. Production users
+ * wire the executor via `fromDynamoDBClient(docClient, tableName)`; tests
+ * supply an in-memory implementation (`test/helpers/dynamo-shim.ts`).
+ *
+ * All operations target a single table (the adapter is single-table by
+ * design — pk + sk + optional GSIs). The executor knows the table name; the
+ * adapter only passes keys + data.
+ */
+
+export type DynamoKey = { pk: string; sk: string }
+
+/**
+ * Strong read by primary key. `consistentRead` MUST be honoured for every
+ * security-critical read (`getCode`, `getRefresh`, `getFlow`) — DynamoDB
+ * defaults to eventually consistent reads which violate the contracts in
+ * `ports/CONSISTENCY.md`.
+ */
+export type DynamoGetInput = {
+  key: DynamoKey
+  consistentRead: boolean
+}
+
+/**
+ * Insert (`condition: "not-exists"`) or unconditional put. The adapter uses:
+ *  - `"not-exists"` for code / refresh / flow inserts so a duplicate token
+ *    never silently overwrites.
+ *  - `"exists"` for read-modify-write paths (e.g. `updateFlowMethodState`)
+ *    so the put fails if a concurrent `consumeFlow` deleted the row between
+ *    the prior `get` and this `put`. The executor surfaces a
+ *    `ConditionalCheckFailedException` that callers translate into a typed
+ *    failure.
+ */
+export type DynamoPutInput = {
+  item: Record<string, unknown> & DynamoKey
+  condition?: "not-exists" | "exists"
+}
+
+/**
+ * Atomic delete-on-read — equivalent to `DeleteItem` with
+ * `ReturnValues=ALL_OLD`. Concurrent calls resolve to exactly one winner
+ * that gets the row back; losers get `undefined`.
+ */
+export type DynamoDeleteInput = {
+  key: DynamoKey
+}
+
+/**
+ * Conditional UPDATE used for the refresh-token rotation. Sets `consumed_at`
+ * iff it is currently absent. Returns the post-update item on success;
+ * resolves with `null` if the condition failed (`ConditionalCheckFailed`).
+ */
+export type DynamoUpdateConsumeRefreshInput = {
+  key: DynamoKey
+  now: number
+}
+
+/**
+ * Query items by partition key (and optionally a sort-key prefix). Strongly
+ * consistent for the refresh-revoke paths.
+ */
+export type DynamoQueryInput = {
+  pk: string
+  /** Sort-key prefix filter — emits `begins_with(sk, prefix)`. */
+  skBeginsWith?: string
+  consistentRead: boolean
+  /** Filter by an attribute (e.g. `family = :v` for `revokeFamily` via GSI). */
+  filter?: {
+    attribute: string
+    equals: string
+  }
+}
+
+export type DynamoQueryByGsiInput = {
+  /**
+   * GSI name configured on the table. Each entry corresponds to a GSI
+   * the bundled adapters need:
+   *   - `family-index`         (refresh-token family revocation)
+   *   - `subject-index`        (revokeBySubject)
+   *   - `passkey-user-index`   (PasskeyCredentialStore.findByUsername)
+   */
+  indexName: "family-index" | "subject-index" | "passkey-user-index"
+  /** Hash key value on the GSI. */
+  hashKey: string
+}
+
+/**
+ * Update a single item's attributes — equivalent to DynamoDB's
+ * `UpdateItem` with a `SET` expression over each provided attribute.
+ *
+ * Used by passkey-counter updates today; future Phase 8 features
+ * (DPoP jti replay, etc.) may reuse it.
+ */
+export type DynamoUpdateItemInput = {
+  key: DynamoKey
+  /** Attribute name → new value. Top-level only, no nested updates. */
+  set: Record<string, unknown>
+}
+
+export type DynamoExecutor = {
+  get(input: DynamoGetInput): Promise<Record<string, unknown> | undefined>
+  put(input: DynamoPutInput): Promise<void>
+  /** Returns the deleted item if one was deleted; `undefined` otherwise. */
+  delete(input: DynamoDeleteInput): Promise<Record<string, unknown> | undefined>
+  /**
+   * Atomic refresh-token claim. Returns the post-update item on success;
+   * `null` if the condition failed (already-consumed race).
+   */
+  consumeRefresh(
+    input: DynamoUpdateConsumeRefreshInput,
+  ): Promise<Record<string, unknown> | null>
+  query(input: DynamoQueryInput): Promise<Record<string, unknown>[]>
+  queryByGsi(input: DynamoQueryByGsiInput): Promise<Record<string, unknown>[]>
+  /** Generic attribute update. No-op if the item does not exist. */
+  updateItem(input: DynamoUpdateItemInput): Promise<void>
+}

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

@@ -0,0 +1,72 @@
+/**
+ * DynamoDB `ConfigStore`. `pk="tenant"`, `sk=<tenantId>`. Read-eventual
+ * by default (config is read-heavy, write-rare); the invalidation hook
+ * fires on every `putTenantConfig` so in-process caches drop stale values
+ * immediately.
+ */
+import type { ConfigStore } from "../../ports/config-store"
+import { authError } from "../../types/error"
+import type { Result } from "../../types/result"
+import { err, ok } from "../../types/result"
+import type { TenantConfig, TenantId } from "../../types/tenant"
+
+import type { DynamoExecutor } from "./client"
+
+export type DynamoConfigStoreOptions = {
+  exec: DynamoExecutor
+}
+
+export class DynamoConfigStore implements ConfigStore {
+  #exec: DynamoExecutor
+  #listeners = new Set<(id: TenantId) => void>()
+
+  constructor(opts: DynamoConfigStoreOptions) {
+    this.#exec = opts.exec
+  }
+
+  async getTenantConfig(id: TenantId): Promise<Result<TenantConfig>> {
+    let row: Record<string, unknown> | undefined
+    try {
+      row = await this.#exec.get({
+        key: { pk: "tenant", sk: id },
+        consistentRead: false,
+      })
+    } catch (e) {
+      return err(authError.internalError("getTenantConfig: get failed", e))
+    }
+    if (!row) {
+      return err(authError.tenantNotFound(`tenant "${id}" not found`, id))
+    }
+    return ok(parseConfig(row.config))
+  }
+
+  async putTenantConfig(config: TenantConfig): Promise<Result<void>> {
+    try {
+      await this.#exec.put({
+        item: {
+          pk: "tenant",
+          sk: config.id,
+          config: JSON.stringify(config),
+          updated_at: Date.now(),
+        },
+      })
+    } catch (e) {
+      return err(authError.internalError("putTenantConfig: put failed", e))
+    }
+    for (const fn of this.#listeners) {
+      try {
+        fn(config.id)
+      } catch {}
+    }
+    return ok(undefined)
+  }
+
+  onInvalidate(handler: (id: TenantId) => void): void {
+    this.#listeners.add(handler)
+  }
+}
+
+function parseConfig(raw: unknown): TenantConfig {
+  if (typeof raw === "string") return JSON.parse(raw) as TenantConfig
+  return raw as TenantConfig
+}

package/src/adapters/dynamo/index.ts

@@ -0,0 +1,81 @@
+/**
+ * AWS DynamoDB adapter set.
+ *
+ * Single-table design with `pk` / `sk` primary key plus three GSIs:
+ *
+ *   `family-index`         hash = `family`        (revokeFamily)
+ *   `subject-index`        hash = `subject_key`   (revokeBySubject) — value is `<tenantId>#<subjectId>`
+ *   `passkey-user-index`   hash = `user_key`      (PasskeyCredentialStore.findByUsername) — value is `<tenantId>#<userId>`
+ *
+ * The adapter satisfies every contract in `ports/CONSISTENCY.md` provided
+ * the underlying calls use `ConsistentRead=true` on the strong reads and
+ * `ConditionExpression` on the rotation `UpdateItem` — both are handled by
+ * `fromDynamoDBClient`.
+ *
+ * Wiring:
+ * @example
+ *   import { DynamoDBClient } from "@aws-sdk/client-dynamodb"
+ *   import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb"
+ *   import {
+ *     fromDynamoDBClient,
+ *     DynamoTokenStore,
+ *     DynamoSessionStore,
+ *     // ...
+ *   } from "@_mustachio/openauth/adapters/dynamo"
+ *
+ *   const docClient = DynamoDBDocumentClient.from(new DynamoDBClient({ region: "us-east-1" }))
+ *   const exec = fromDynamoDBClient(docClient, "openauth")
+ *   const keyStore = new DynamoKeyStore({ exec })
+ *   const tokenStore = new DynamoTokenStore({ exec, keyStore })
+ *
+ * Table creation is left to the operator (Terraform / CDK / `aws dynamodb
+ * create-table`). The schema you need:
+ *
+ *   Table: openauth (or any name you choose)
+ *     Hash key:  pk (S)
+ *     Range key: sk (S)
+ *     TTL attribute: `ttl` (epoch seconds)
+ *
+ *   GSI: family-index
+ *     Hash key: family (S)
+ *     Projection: ALL
+ *
+ *   GSI: subject-index
+ *     Hash key: subject_key (S)
+ *     Projection: ALL
+ *
+ *   GSI: passkey-user-index
+ *     Hash key: user_key (S)
+ *     Projection: ALL
+ */
+export { DynamoAuditLog, type DynamoAuditLogOptions } from "./audit-log"
+export {
+  DynamoConfigStore,
+  type DynamoConfigStoreOptions,
+} from "./config-store"
+export { DynamoKeyStore, type DynamoKeyStoreOptions } from "./key-store"
+export {
+  DynamoMethodStore,
+  type DynamoMethodStoreOptions,
+} from "./method-store"
+export {
+  DynamoSessionStore,
+  type DynamoSessionStoreOptions,
+} from "./session-store"
+export { DynamoTokenStore, type DynamoTokenStoreOptions } from "./token-store"
+export {
+  DynamoPasskeyCredentialStore,
+  type DynamoPasskeyCredentialStoreOptions,
+} from "./passkey-credential-store"
+export { fromDynamoDBClient } from "./sdk"
+export type {
+  DynamoDeleteInput,
+  DynamoExecutor,
+  DynamoGetInput,
+  DynamoKey,
+  DynamoPutInput,
+  DynamoQueryByGsiInput,
+  DynamoQueryInput,
+  DynamoUpdateConsumeRefreshInput,
+  DynamoUpdateItemInput,
+} from "./client"