@_mustachio/openauth 0.9.1 → 0.10.0

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

@@ -0,0 +1,128 @@
+/**
+ * In-memory `SessionStore` — flow records (required) + optional long-lived
+ * sessions. Map-backed; atomic w.r.t. the JS event loop.
+ *
+ * `consumeFlow` is a strict atomic delete-on-read that returns the full
+ * `FlowRecord` — the framework needs every field to snapshot into the
+ * auth-code payload before the record is gone.
+ */
+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 { Clock } from "./clock"
+import { realClock } from "./clock"
+
+type StoredFlow = {
+  record: FlowRecord
+  expiresAt: number
+}
+
+export type MemorySessionStoreOptions = {
+  clock?: Clock
+}
+
+export class MemorySessionStore implements SessionStore {
+  #clock: Clock
+  #flows = new Map<string, StoredFlow>()
+  #sessions = new Map<string, SessionRecord>()
+
+  constructor(opts: MemorySessionStoreOptions = {}) {
+    this.#clock = opts.clock ?? realClock
+  }
+
+  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}`),
+      )
+    }
+    this.#flows.set(flowId, {
+      record: payload,
+      expiresAt: this.#clock() + ttl,
+    })
+    return ok(undefined)
+  }
+
+  async updateFlowMethodState(
+    flowId: string,
+    methodState: unknown,
+  ): Promise<Result<void>> {
+    const stored = this.#flows.get(flowId)
+    if (!stored) {
+      return err(authError.unknownState(`flow "${flowId}" unknown`))
+    }
+    if (this.#clock() >= stored.expiresAt) {
+      this.#flows.delete(flowId)
+      return err(authError.unknownState(`flow "${flowId}" expired`))
+    }
+    stored.record = { ...stored.record, methodState }
+    return ok(undefined)
+  }
+
+  async readFlow(flowId: string): Promise<Result<FlowRecord>> {
+    const stored = this.#flows.get(flowId)
+    if (!stored) {
+      return err(authError.unknownState(`flow "${flowId}" unknown`))
+    }
+    if (this.#clock() >= stored.expiresAt) {
+      this.#flows.delete(flowId)
+      return err(authError.unknownState(`flow "${flowId}" expired`))
+    }
+    return ok(stored.record)
+  }
+
+  async consumeFlow(flowId: string): Promise<Result<FlowRecord>> {
+    const stored = this.#flows.get(flowId)
+    if (!stored) {
+      return err(
+        authError.unknownState(`flow "${flowId}" unknown or already consumed`),
+      )
+    }
+    // Atomic delete-on-read — remove before observable side effects so a
+    // concurrent caller can't see the same record.
+    this.#flows.delete(flowId)
+    if (this.#clock() >= stored.expiresAt) {
+      return err(authError.unknownState(`flow "${flowId}" expired`))
+    }
+    return ok(stored.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}`,
+        ),
+      )
+    }
+    this.#sessions.set(sessionId, payload)
+    return ok(undefined)
+  }
+
+  async readSession(sessionId: string): Promise<Result<SessionRecord>> {
+    const s = this.#sessions.get(sessionId)
+    if (!s) {
+      return err(authError.invalidRequest(`session "${sessionId}" unknown`))
+    }
+    if (this.#clock() >= s.expiresAt) {
+      this.#sessions.delete(sessionId)
+      return err(authError.invalidRequest(`session "${sessionId}" expired`))
+    }
+    return ok(s)
+  }
+
+  async revokeSession(sessionId: string): Promise<Result<void>> {
+    this.#sessions.delete(sessionId)
+    return ok(undefined)
+  }
+}

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

@@ -0,0 +1,165 @@
+/**
+ * In-memory `TokenStore`. Single-process; the `Map` operations are
+ * atomic with respect to JS event-loop turns, which is enough for the
+ * strong-CAS contract here.
+ *
+ * Auth-code ciphertext is stored verbatim — encryption is the domain's
+ * job (see `domain/authorize.ts` → `encryptPayload`), so the adapter
+ * never sees plaintext. Inspecting the internal map shows whatever
+ * blob the domain saved.
+ */
+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 type { Clock } from "./clock"
+import { realClock } from "./clock"
+
+type StoredCode = {
+  ciphertext: string
+  expiresAt: number
+}
+
+type StoredRefresh = {
+  payload: RefreshTokenPayload
+  consumedAt?: number
+}
+
+export type MemoryTokenStoreOptions = {
+  /**
+   * Optional — retained for API stability after M1 moved code-payload
+   * encryption to the domain layer. The adapter no longer touches it.
+   */
+  keyStore?: KeyStore
+  clock?: Clock
+}
+
+export class MemoryTokenStore implements TokenStore {
+  #clock: Clock
+  #codes = new Map<string, StoredCode>()
+  #refresh = new Map<string, StoredRefresh>()
+
+  constructor(opts: MemoryTokenStoreOptions = {}) {
+    this.#clock = opts.clock ?? realClock
+  }
+
+  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)`,
+        ),
+      )
+    }
+    this.#codes.set(code, { ciphertext, expiresAt: this.#clock() + ttl })
+    return ok(undefined)
+  }
+
+  async consumeCode(code: string): Promise<Result<string>> {
+    const stored = this.#codes.get(code)
+    if (!stored) {
+      return err(
+        authError.invalidGrant("auth code unknown or already consumed"),
+      )
+    }
+    // Atomic delete-on-read: remove **before** returning so a concurrent
+    // caller cannot observe the same row.
+    this.#codes.delete(code)
+    if (this.#clock() >= stored.expiresAt) {
+      return err(authError.invalidGrant("auth code expired"))
+    }
+    return ok(stored.ciphertext)
+  }
+
+  async saveRefresh(
+    refresh: string,
+    payload: RefreshTokenPayload,
+  ): Promise<Result<void>> {
+    this.#refresh.set(refresh, { payload })
+    return ok(undefined)
+  }
+
+  async consumeRefresh(
+    refresh: string,
+    options: { reuseWindowMs?: number } = {},
+  ): Promise<Result<RefreshTokenPayload>> {
+    const reuseWindow = options.reuseWindowMs ?? 60_000
+    const now = this.#clock()
+    const stored = this.#refresh.get(refresh)
+    if (!stored) {
+      return err(authError.invalidGrant("refresh token unknown"))
+    }
+    if (stored.consumedAt !== undefined) {
+      const withinWindow = now - stored.consumedAt <= reuseWindow
+      if (withinWindow) {
+        // Reuse detection — auto-revoke the family so every descendant of
+        // the compromised chain is invalidated. The caller still gets
+        // `invalid_grant`; the structured `reuseSignal` carries the
+        // family / tenant / subject for audit-log enrichment (port
+        // contract per `ports/token-store.ts`).
+        const family = stored.payload.family
+        await this.revokeFamily(family)
+        return err(
+          authError.invalidGrant(
+            `refresh token reuse detected (family=${family})`,
+            {
+              family,
+              tenantId: stored.payload.tenantId,
+              subjectId: stored.payload.subjectId,
+            },
+          ),
+        )
+      }
+      return err(authError.invalidGrant("refresh token already consumed"))
+    }
+    if (now >= stored.payload.expiresAt) {
+      return err(authError.invalidGrant("refresh token expired"))
+    }
+    stored.consumedAt = now
+    return ok(stored.payload)
+  }
+
+  async peekRefresh(refresh: string): Promise<Result<RefreshTokenPayload>> {
+    const stored = this.#refresh.get(refresh)
+    if (!stored) {
+      return err(authError.invalidGrant("refresh token unknown"))
+    }
+    if (this.#clock() >= stored.payload.expiresAt) {
+      return err(authError.invalidGrant("refresh token expired"))
+    }
+    return ok(stored.payload)
+  }
+
+  async revokeFamily(family: string): Promise<Result<void>> {
+    for (const [token, stored] of this.#refresh) {
+      if (stored.payload.family === family) {
+        this.#refresh.delete(token)
+      }
+    }
+    return ok(undefined)
+  }
+
+  async revokeBySubject(
+    tenantId: TenantId,
+    subjectId: string,
+  ): Promise<Result<void>> {
+    for (const [token, stored] of this.#refresh) {
+      if (
+        stored.payload.tenantId === tenantId &&
+        stored.payload.subjectId === subjectId
+      ) {
+        this.#refresh.delete(token)
+      }
+    }
+    return ok(undefined)
+  }
+}

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

@@ -0,0 +1,34 @@
+/**
+ * Postgres `AuditLog`. Append-only `openauth_audit_events` table; indexed on
+ * `kind` and `ts` for SIEM-style queries. Writes are synchronous — adapters
+ * looking for batching can wrap this with their own buffering layer.
+ */
+import type { AuditEvent, AuditLog } from "../../ports/audit-log"
+
+import type { PostgresExecutor } from "./executor"
+
+export type PostgresAuditLogOptions = {
+  exec: PostgresExecutor
+}
+
+export class PostgresAuditLog implements AuditLog {
+  #exec: PostgresExecutor
+
+  constructor(opts: PostgresAuditLogOptions) {
+    this.#exec = opts.exec
+  }
+
+  async log(event: AuditEvent & { timestamp: number }): Promise<void> {
+    try {
+      await this.#exec.query(
+        `INSERT INTO openauth_audit_events (ts, kind, payload)
+         VALUES ($1, $2, $3::jsonb)`,
+        [event.timestamp, event.kind, JSON.stringify(event)],
+      )
+    } catch {
+      // Per `ports/audit-log.ts` JSDoc: `log` should not throw on durability
+      // failure. The IdP's hot paths must not be gated on the audit log.
+      // Future: add a buffering layer with backoff.
+    }
+  }
+}

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

@@ -0,0 +1,72 @@
+/**
+ * Postgres `ConfigStore`. JSONB blob keyed by tenant id. Invalidation hook
+ * fires on every `putTenantConfig` so any in-process cache built on top of
+ * this adapter drops the stale value before the write resolves.
+ */
+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 { PostgresExecutor } from "./executor"
+
+export type PostgresConfigStoreOptions = {
+  exec: PostgresExecutor
+  clock?: () => number
+}
+
+export class PostgresConfigStore implements ConfigStore {
+  #exec: PostgresExecutor
+  #clock: () => number
+  #listeners = new Set<(id: TenantId) => void>()
+
+  constructor(opts: PostgresConfigStoreOptions) {
+    this.#exec = opts.exec
+    this.#clock = opts.clock ?? (() => Date.now())
+  }
+
+  async getTenantConfig(id: TenantId): Promise<Result<TenantConfig>> {
+    let row: { config: unknown } | undefined
+    try {
+      const result = await this.#exec.query<{ config: unknown }>(
+        `SELECT config FROM openauth_tenants WHERE id = $1`,
+        [id],
+      )
+      row = result.rows[0]
+    } catch (e) {
+      return err(authError.internalError("getTenantConfig: query failed", e))
+    }
+    if (!row) {
+      return err(authError.tenantNotFound(`tenant "${id}" not found`, id))
+    }
+    const config =
+      typeof row.config === "string"
+        ? (JSON.parse(row.config) as TenantConfig)
+        : (row.config as TenantConfig)
+    return ok(config)
+  }
+
+  async putTenantConfig(config: TenantConfig): Promise<Result<void>> {
+    try {
+      await this.#exec.query(
+        `INSERT INTO openauth_tenants (id, config, updated_at)
+         VALUES ($1, $2::jsonb, $3)
+         ON CONFLICT (id) DO UPDATE SET config = EXCLUDED.config, updated_at = EXCLUDED.updated_at`,
+        [config.id, JSON.stringify(config), this.#clock()],
+      )
+    } catch (e) {
+      return err(authError.internalError("putTenantConfig: insert 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)
+  }
+}

package/src/adapters/postgres/executor.ts

@@ -0,0 +1,76 @@
+/**
+ * Thin SQL-executor interface the Postgres adapters depend on.
+ *
+ * Both the production `postgres` (porsager/postgres) driver and the embedded
+ * `@electric-sql/pglite` test driver fit behind this shape. Adapters never
+ * import either driver directly — users wire one of the `from*` helpers
+ * below.
+ */
+
+/** One row of a SQL result, addressed by column name. */
+export type Row = Record<string, unknown>
+
+/**
+ * Minimal Postgres-shaped executor. Positional `$1, $2` parameters; rows are
+ * column-name keyed objects.
+ */
+export type PostgresExecutor = {
+  query<T extends Row = Row>(
+    sql: string,
+    params?: ReadonlyArray<unknown>,
+  ): Promise<{ rows: T[] }>
+}
+
+/**
+ * Wrap a porsager/postgres `Sql` instance in the `PostgresExecutor` shape.
+ * The adapter calls `sql.unsafe(text, params)` so positional binds work.
+ *
+ * @example
+ *   import postgres from "postgres"
+ *   import { fromPostgresJs, PostgresTokenStore } from "@_mustachio/openauth/adapters/postgres"
+ *   const sql = postgres(process.env.DATABASE_URL!)
+ *   const exec = fromPostgresJs(sql)
+ *   const store = new PostgresTokenStore({ exec, keyStore })
+ */
+export function fromPostgresJs(sql: PostgresJsLike): PostgresExecutor {
+  return {
+    async query<T extends Row = Row>(
+      text: string,
+      params: ReadonlyArray<unknown> = [],
+    ): Promise<{ rows: T[] }> {
+      const result = await sql.unsafe(text, params as unknown[])
+      // porsager/postgres returns an array-shaped result with row objects.
+      return { rows: Array.from(result as unknown as Iterable<T>) }
+    },
+  }
+}
+
+/** Minimal shape we use from porsager/postgres — kept untyped to avoid a runtime import. */
+export type PostgresJsLike = {
+  unsafe: (text: string, params: unknown[]) => Promise<unknown>
+}
+
+/**
+ * Wrap a PGlite instance in the `PostgresExecutor` shape. Used by the
+ * port-conformance suite to run the Postgres adapters in-process without a
+ * server.
+ */
+export function fromPGlite(db: PGliteLike): PostgresExecutor {
+  return {
+    async query<T extends Row = Row>(
+      text: string,
+      params: ReadonlyArray<unknown> = [],
+    ): Promise<{ rows: T[] }> {
+      const result = await db.query<T>(text, params as unknown[])
+      return { rows: result.rows }
+    },
+  }
+}
+
+/** Minimal shape we use from @electric-sql/pglite. */
+export type PGliteLike = {
+  query: <T extends Row = Row>(
+    sql: string,
+    params?: unknown[],
+  ) => Promise<{ rows: T[] }>
+}

package/src/adapters/postgres/index.ts

@@ -0,0 +1,60 @@
+/**
+ * Postgres adapter set.
+ *
+ * Suitable for Node + Postgres deployments. Satisfies every contract in
+ * `ports/CONSISTENCY.md` — `consumeCode` / `consumeFlow` use
+ * `DELETE … RETURNING` for atomic single-winner CAS, `consumeRefresh` uses
+ * `UPDATE … WHERE consumed_at IS NULL RETURNING payload`, and `KeyStore`
+ * persists JWK material in JSONB columns.
+ *
+ * @example
+ *   import postgres from "postgres"
+ *   import {
+ *     fromPostgresJs,
+ *     migrate,
+ *     PostgresTokenStore,
+ *     PostgresSessionStore,
+ *     PostgresKeyStore,
+ *     PostgresConfigStore,
+ *     PostgresMethodStore,
+ *     PostgresAuditLog,
+ *   } from "@_mustachio/openauth/adapters/postgres"
+ *
+ *   const sql = postgres(process.env.DATABASE_URL!)
+ *   const exec = fromPostgresJs(sql)
+ *   await migrate(exec)
+ *   const keyStore = new PostgresKeyStore({ exec })
+ *   const tokenStore = new PostgresTokenStore({ exec, keyStore })
+ *   // ...
+ */
+export {
+  fromPGlite,
+  fromPostgresJs,
+  type PGliteLike,
+  type PostgresExecutor,
+  type PostgresJsLike,
+  type Row,
+} from "./executor"
+export { INITIAL_SCHEMA_SQL, migrate } from "./migrations"
+export { PostgresAuditLog, type PostgresAuditLogOptions } from "./audit-log"
+export {
+  PostgresConfigStore,
+  type PostgresConfigStoreOptions,
+} from "./config-store"
+export { PostgresKeyStore, type PostgresKeyStoreOptions } from "./key-store"
+export {
+  PostgresMethodStore,
+  type PostgresMethodStoreOptions,
+} from "./method-store"
+export {
+  PostgresSessionStore,
+  type PostgresSessionStoreOptions,
+} from "./session-store"
+export {
+  PostgresTokenStore,
+  type PostgresTokenStoreOptions,
+} from "./token-store"
+export {
+  PostgresPasskeyCredentialStore,
+  type PostgresPasskeyCredentialStoreOptions,
+} from "./passkey-credential-store"