@_mustachio/openauth 0.9.2 → 0.10.0

package/src/adapters/postgres/passkey-credential-store.ts

@@ -0,0 +1,150 @@
+/**
+ * Postgres `PasskeyCredentialStore`.
+ *
+ * Schema (created by `migrate()` in `./migrations.ts`):
+ *
+ *   openauth_passkey_credentials
+ *     tenant_id   text  NOT NULL
+ *     credential_id text NOT NULL
+ *     user_id     text  NOT NULL
+ *     public_key  text  NOT NULL
+ *     counter     bigint NOT NULL DEFAULT 0
+ *     transports  jsonb
+ *     created_at  bigint NOT NULL
+ *     PRIMARY KEY (tenant_id, credential_id)
+ *     INDEX (tenant_id, user_id)   -- findByUsername path
+ *
+ * The reference adapter treats `userId` as the username lookup key —
+ * matching the bundled `passkeyMethod` which sets `userId =
+ * parsed.data.username` at registration. Hosts that want a separate
+ * username dimension implement `PasskeyCredentialStore` directly
+ * against their own user table.
+ */
+import type {
+  PasskeyCredentialStore,
+  StoredCredential,
+} from "../../methods/passkey"
+
+import type { PostgresExecutor } from "./executor"
+
+export type PostgresPasskeyCredentialStoreOptions = {
+  exec: PostgresExecutor
+  clock?: () => number
+}
+
+type Row = {
+  credential_id: string
+  user_id: string
+  public_key: string
+  counter: string | number
+  transports: unknown
+}
+
+export class PostgresPasskeyCredentialStore implements PasskeyCredentialStore {
+  #exec: PostgresExecutor
+  #clock: () => number
+
+  constructor(opts: PostgresPasskeyCredentialStoreOptions) {
+    this.#exec = opts.exec
+    this.#clock = opts.clock ?? (() => Date.now())
+  }
+
+  async findByUsername(
+    username: string,
+    tenantId: string,
+  ): Promise<{ userId: string; credentials: StoredCredential[] } | null> {
+    const result = await this.#exec.query<Row>(
+      `SELECT credential_id, user_id, public_key, counter, transports
+         FROM openauth_passkey_credentials
+        WHERE tenant_id = $1 AND user_id = $2`,
+      [tenantId, username],
+    )
+    if (result.rows.length === 0) return null
+    return {
+      userId: username,
+      credentials: result.rows.map(rowToCredential),
+    }
+  }
+
+  async findById(
+    credentialId: string,
+    tenantId: string,
+  ): Promise<StoredCredential | null> {
+    const result = await this.#exec.query<Row>(
+      `SELECT credential_id, user_id, public_key, counter, transports
+         FROM openauth_passkey_credentials
+        WHERE tenant_id = $1 AND credential_id = $2`,
+      [tenantId, credentialId],
+    )
+    const row = result.rows[0]
+    if (!row) return null
+    return rowToCredential(row)
+  }
+
+  async updateCounter(input: {
+    credentialId: string
+    counter: number
+    tenantId: string
+  }): Promise<void> {
+    await this.#exec.query(
+      `UPDATE openauth_passkey_credentials
+          SET counter = $1
+        WHERE tenant_id = $2 AND credential_id = $3`,
+      [input.counter, input.tenantId, input.credentialId],
+    )
+  }
+
+  async create(input: {
+    userId: string
+    credential: StoredCredential
+    tenantId: string
+  }): Promise<void> {
+    await this.#exec.query(
+      `INSERT INTO openauth_passkey_credentials
+         (tenant_id, credential_id, user_id, public_key, counter, transports, created_at)
+       VALUES ($1, $2, $3, $4, $5, $6::jsonb, $7)
+       ON CONFLICT (tenant_id, credential_id) DO UPDATE
+         SET public_key = EXCLUDED.public_key,
+             counter = EXCLUDED.counter,
+             transports = EXCLUDED.transports,
+             user_id = EXCLUDED.user_id`,
+      [
+        input.tenantId,
+        input.credential.credentialId,
+        input.userId,
+        input.credential.publicKey,
+        input.credential.counter,
+        input.credential.transports
+          ? JSON.stringify(input.credential.transports)
+          : null,
+        this.#clock(),
+      ],
+    )
+  }
+}
+
+function rowToCredential(row: Row): StoredCredential {
+  const credential: StoredCredential = {
+    credentialId: row.credential_id,
+    publicKey: row.public_key,
+    counter: Number(row.counter),
+    userId: row.user_id,
+  }
+  if (row.transports != null) {
+    credential.transports = parseTransports(row.transports)
+  }
+  return credential
+}
+
+function parseTransports(raw: unknown): string[] {
+  if (Array.isArray(raw)) return raw.map(String)
+  if (typeof raw === "string") {
+    try {
+      const parsed: unknown = JSON.parse(raw)
+      return Array.isArray(parsed) ? parsed.map(String) : []
+    } catch {
+      return []
+    }
+  }
+  return []
+}

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

@@ -0,0 +1,216 @@
+/**
+ * Postgres `SessionStore` — flow records + optional long-lived sessions.
+ *
+ * `consumeFlow` is `DELETE … RETURNING payload, expires_at` — atomic
+ * single-winner, returns the full record so the framework can snapshot
+ * fields into the auth-code payload before disposal.
+ *
+ * `updateFlowMethodState` merges new state into the existing JSONB blob via
+ * a single UPDATE (no read-modify-write race).
+ */
+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 { PostgresExecutor } from "./executor"
+
+export type PostgresSessionStoreOptions = {
+  exec: PostgresExecutor
+  clock?: () => number
+}
+
+export class PostgresSessionStore implements SessionStore {
+  #exec: PostgresExecutor
+  #clock: () => number
+
+  constructor(opts: PostgresSessionStoreOptions) {
+    this.#exec = opts.exec
+    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 this.#exec.query(
+        `INSERT INTO openauth_flows (flow_id, payload, expires_at)
+         VALUES ($1, $2::jsonb, $3)`,
+        [flowId, JSON.stringify(payload), expiresAt],
+      )
+    } 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()
+    let row: { exists: boolean } | undefined
+    try {
+      // jsonb_set patches the nested key without a read-modify-write race.
+      const result = await this.#exec.query<{ exists: boolean }>(
+        `UPDATE openauth_flows
+            SET payload = jsonb_set(payload, '{methodState}', $1::jsonb, true)
+          WHERE flow_id = $2 AND expires_at > $3
+          RETURNING true AS exists`,
+        [JSON.stringify(methodState), flowId, now],
+      )
+      row = result.rows[0]
+    } catch (e) {
+      return err(
+        authError.internalError("updateFlowMethodState: update failed", e),
+      )
+    }
+    if (!row) {
+      return err(authError.unknownState(`flow "${flowId}" unknown or expired`))
+    }
+    return ok(undefined)
+  }
+
+  async readFlow(flowId: string): Promise<Result<FlowRecord>> {
+    let row: { payload: unknown; expires_at: string | number } | undefined
+    try {
+      const result = await this.#exec.query<{
+        payload: unknown
+        expires_at: string | number
+      }>(`SELECT payload, expires_at FROM openauth_flows WHERE flow_id = $1`, [
+        flowId,
+      ])
+      row = result.rows[0]
+    } 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)) {
+      // Lazy GC — best-effort delete, don't fail the read if the delete races.
+      try {
+        await this.#exec.query(
+          `DELETE FROM openauth_flows WHERE flow_id = $1`,
+          [flowId],
+        )
+      } catch {}
+      return err(authError.unknownState(`flow "${flowId}" expired`))
+    }
+    return ok(parseFlowRecord(row.payload))
+  }
+
+  async consumeFlow(flowId: string): Promise<Result<FlowRecord>> {
+    let row: { payload: unknown; expires_at: string | number } | undefined
+    try {
+      // Atomic delete-on-read — single-winner under concurrent presentations.
+      const result = await this.#exec.query<{
+        payload: unknown
+        expires_at: string | number
+      }>(
+        `DELETE FROM openauth_flows
+          WHERE flow_id = $1
+          RETURNING payload, expires_at`,
+        [flowId],
+      )
+      row = result.rows[0]
+    } 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(parseFlowRecord(row.payload))
+  }
+
+  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 this.#exec.query(
+        `INSERT INTO openauth_sessions (session_id, payload, expires_at)
+         VALUES ($1, $2::jsonb, $3)
+         ON CONFLICT (session_id) DO UPDATE SET payload = EXCLUDED.payload, expires_at = EXCLUDED.expires_at`,
+        [sessionId, JSON.stringify(payload), expiresAt],
+      )
+    } catch (e) {
+      return err(authError.internalError("createSession: insert failed", e))
+    }
+    return ok(undefined)
+  }
+
+  async readSession(sessionId: string): Promise<Result<SessionRecord>> {
+    let row: { payload: unknown; expires_at: string | number } | undefined
+    try {
+      const result = await this.#exec.query<{
+        payload: unknown
+        expires_at: string | number
+      }>(
+        `SELECT payload, expires_at FROM openauth_sessions WHERE session_id = $1`,
+        [sessionId],
+      )
+      row = result.rows[0]
+    } 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 this.#exec.query(
+          `DELETE FROM openauth_sessions WHERE session_id = $1`,
+          [sessionId],
+        )
+      } catch {}
+      return err(authError.invalidRequest(`session "${sessionId}" expired`))
+    }
+    return ok(parseSession(row.payload))
+  }
+
+  async revokeSession(sessionId: string): Promise<Result<void>> {
+    try {
+      await this.#exec.query(
+        `DELETE FROM openauth_sessions WHERE session_id = $1`,
+        [sessionId],
+      )
+    } catch (e) {
+      return err(authError.internalError("revokeSession: delete failed", e))
+    }
+    return ok(undefined)
+  }
+}
+
+function parseFlowRecord(raw: unknown): FlowRecord {
+  if (typeof raw === "string") return JSON.parse(raw) as FlowRecord
+  return raw as FlowRecord
+}
+
+function parseSession(raw: unknown): SessionRecord {
+  if (typeof raw === "string") return JSON.parse(raw) as SessionRecord
+  return raw as SessionRecord
+}

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

@@ -0,0 +1,263 @@
+/**
+ * Postgres `TokenStore`.
+ *
+ * - `consumeCode` is an atomic `DELETE … RETURNING` so concurrent
+ *   presentations of the same code resolve to exactly one winner. The
+ *   ciphertext blob is stored verbatim — `domain/authorize.ts` encrypts
+ *   payloads before they reach the adapter (M1), and `domain/token.ts`
+ *   decrypts after consume. The DB never sees plaintext.
+ * - `consumeRefresh` does an atomic `UPDATE … WHERE consumed_at IS NULL
+ *   RETURNING payload` so a refresh chain has a single live winner per
+ *   generation. Reuse-detection within the configurable window auto-revokes
+ *   the family.
+ *
+ * On reuse-detection the adapter returns `invalid_grant` and populates
+ * the structured `reuseSignal` carrier on the error (family / tenantId /
+ * subjectId), per the `TokenStore` port contract. The domain's audit
+ * emission consumes the typed signal directly — no string parsing.
+ */
+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 { PostgresExecutor } from "./executor"
+
+export type PostgresTokenStoreOptions = {
+  exec: PostgresExecutor
+  /**
+   * Optional — retained for API stability after M1 moved code-payload
+   * encryption to the domain layer. The adapter no longer touches it.
+   */
+  keyStore?: KeyStore
+  /** Injectable clock — defaults to `Date.now`. Tests advance it. */
+  clock?: () => number
+}
+
+export class PostgresTokenStore implements TokenStore {
+  #exec: PostgresExecutor
+  #clock: () => number
+
+  constructor(opts: PostgresTokenStoreOptions) {
+    this.#exec = opts.exec
+    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 this.#exec.query(
+        `INSERT INTO openauth_codes (code, ciphertext, expires_at) VALUES ($1, $2, $3)`,
+        [code, ciphertext, expiresAt],
+      )
+    } 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: string | number } | undefined
+    try {
+      const result = await this.#exec.query<{
+        ciphertext: string
+        expires_at: string | number
+      }>(
+        `DELETE FROM openauth_codes WHERE code = $1 RETURNING ciphertext, expires_at`,
+        [code],
+      )
+      row = result.rows[0]
+    } 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 this.#exec.query(
+        `INSERT INTO openauth_refresh_tokens
+           (token, tenant_id, client_id, subject_id, family, expires_at, payload)
+         VALUES ($1, $2, $3, $4, $5, $6, $7::jsonb)`,
+        [
+          refresh,
+          payload.tenantId,
+          payload.clientId,
+          payload.subjectId,
+          payload.family,
+          payload.expiresAt,
+          JSON.stringify(payload),
+        ],
+      )
+    } 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()
+    // First try to atomically claim the token — exactly one concurrent caller
+    // gets a row back. The UPDATE bounds-checks expiry under the same row
+    // lock so an expired token won't be marked consumed under us.
+    let claimed: { payload: unknown } | undefined
+    try {
+      const result = await this.#exec.query<{ payload: unknown }>(
+        `UPDATE openauth_refresh_tokens
+           SET consumed_at = $1
+         WHERE token = $2
+           AND consumed_at IS NULL
+           AND expires_at > $1
+         RETURNING payload`,
+        [now, refresh],
+      )
+      claimed = result.rows[0]
+    } catch (e) {
+      return err(authError.internalError("consumeRefresh: claim failed", e))
+    }
+    if (claimed) {
+      return ok(parseRefreshPayload(claimed.payload))
+    }
+    // No row claimed. Find out why — unknown, expired, or already consumed.
+    let existing:
+      | {
+          consumed_at: string | number | null
+          expires_at: string | number
+          payload: unknown
+        }
+      | undefined
+    try {
+      const result = await this.#exec.query<{
+        consumed_at: string | number | null
+        expires_at: string | number
+        payload: unknown
+      }>(
+        `SELECT consumed_at, expires_at, payload
+           FROM openauth_refresh_tokens
+          WHERE token = $1`,
+        [refresh],
+      )
+      existing = result.rows[0]
+    } 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 = parseRefreshPayload(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"))
+    }
+    // Should be unreachable — the UPDATE matched neither, but the row is
+    // unconsumed and unexpired. Surface as internal so we notice.
+    return err(authError.internalError("consumeRefresh: unexplained miss"))
+  }
+
+  async peekRefresh(refresh: string): Promise<Result<RefreshTokenPayload>> {
+    let row: { expires_at: string | number; payload: unknown } | undefined
+    try {
+      const result = await this.#exec.query<{
+        expires_at: string | number
+        payload: unknown
+      }>(
+        `SELECT expires_at, payload
+           FROM openauth_refresh_tokens
+          WHERE token = $1`,
+        [refresh],
+      )
+      row = result.rows[0]
+    } 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(parseRefreshPayload(row.payload))
+  }
+
+  async revokeFamily(family: string): Promise<Result<void>> {
+    try {
+      await this.#exec.query(
+        `DELETE FROM openauth_refresh_tokens WHERE family = $1`,
+        [family],
+      )
+    } catch (e) {
+      return err(authError.internalError("revokeFamily: delete failed", e))
+    }
+    return ok(undefined)
+  }
+
+  async revokeBySubject(
+    tenantId: TenantId,
+    subjectId: string,
+  ): Promise<Result<void>> {
+    try {
+      await this.#exec.query(
+        `DELETE FROM openauth_refresh_tokens
+          WHERE tenant_id = $1 AND subject_id = $2`,
+        [tenantId, subjectId],
+      )
+    } catch (e) {
+      return err(authError.internalError("revokeBySubject: delete failed", e))
+    }
+    return ok(undefined)
+  }
+}
+
+function parseRefreshPayload(raw: unknown): RefreshTokenPayload {
+  // PGlite returns parsed JSON; postgres-js may return a string depending on
+  // pool config. Be tolerant of both.
+  if (typeof raw === "string") return JSON.parse(raw) as RefreshTokenPayload
+  return raw as RefreshTokenPayload
+}