@_mustachio/openauth 0.9.2 → 0.11.0

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"

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

@@ -0,0 +1,334 @@
+/**
+ * Postgres `KeyStore`.
+ *
+ * Signing keys are persisted as a pair of JWK blobs (public + private) so
+ * the framework can transparently `importJWK(privateKeyRef)` on first use.
+ * Encryption keys are stored as raw bytes in a `bytea` column.
+ *
+ * On first read, if no active signing or encryption key exists the adapter
+ * auto-generates one. This keeps the developer experience aligned with the
+ * memory adapter (no manual bootstrap step) while still respecting whatever
+ * keys an operator may have provisioned out-of-band.
+ *
+ * **At-rest protection.** Pass `wrapper: { wrap, unwrap }` to encrypt the
+ * private JWK and the encryption-key bytes under a host-controlled master
+ * key (typically a KMS Encrypt/Decrypt round trip). Without a wrapper the
+ * adapter stores private material in plaintext at rest — acceptable for
+ * dev / local use, **not** acceptable for production. See `INTEGRATION.md`
+ * §4. The `private_jwk_wrapped` / `key_material_wrapped` boolean columns
+ * record which representation each row uses, so flipping a wrapper on for
+ * an existing deployment is a (forthcoming) re-wrap migration rather than
+ * a schema change.
+ *
+ * Rotation (`rotateSigningKeys` / `rotateEncryptionKeys`) is left as a Phase
+ * 8 deliverable — schema columns exist for `status` and `rotated_at`, so the
+ * later implementation will be a series of `UPDATE` statements without
+ * needing a migration.
+ */
+import type { JWK } from "jose"
+import { exportJWK, generateKeyPair, importJWK } from "jose"
+
+import {
+  base64url,
+  generateSymmetricKey,
+  randomId,
+  utf8,
+} from "../../domain/crypto"
+import type {
+  EncryptionKey,
+  KeyStore,
+  KeyWrapper,
+  SigningKey,
+} from "../../ports/key-store"
+import { authError } from "../../types/error"
+import type { Result } from "../../types/result"
+import { err, ok } from "../../types/result"
+
+import type { PostgresExecutor } from "./executor"
+
+export type PostgresKeyStoreOptions = {
+  exec: PostgresExecutor
+  clock?: () => number
+  signingAlg?: "ES256" | "EdDSA"
+  /**
+   * Optional envelope that encrypts private JWKs and encryption-key bytes
+   * before they leave the process. STRONGLY RECOMMENDED in production.
+   * Pair with a cloud KMS or HSM-backed implementation.
+   */
+  wrapper?: KeyWrapper
+}
+
+export class PostgresKeyStore implements KeyStore {
+  #exec: PostgresExecutor
+  #clock: () => number
+  #signingAlg: "ES256" | "EdDSA"
+  #wrapper: KeyWrapper | undefined
+  // Cache imported private keys so we don't re-import on every sign.
+  #privateKeyCache = new Map<string, unknown>()
+
+  constructor(opts: PostgresKeyStoreOptions) {
+    this.#exec = opts.exec
+    this.#clock = opts.clock ?? (() => Date.now())
+    this.#signingAlg = opts.signingAlg ?? "ES256"
+    this.#wrapper = opts.wrapper
+  }
+
+  async currentSigningKey(): Promise<Result<SigningKey>> {
+    await this.#ensureSigningKey()
+    const rows = await this.#selectSigningRows(`status = 'active'`)
+    if (rows.length === 0) {
+      return err(
+        authError.internalError(
+          "no active signing key (should be unreachable)",
+        ),
+      )
+    }
+    const key = await this.#hydrateSigningKey(rows[0]!)
+    return ok(key)
+  }
+
+  async signingKeys(): Promise<Result<SigningKey[]>> {
+    await this.#ensureSigningKey()
+    const rows = await this.#selectSigningRows(
+      `status IN ('active','next','retired')`,
+    )
+    const keys = await Promise.all(rows.map((r) => this.#hydrateSigningKey(r)))
+    return ok(keys)
+  }
+
+  async currentEncryptionKey(): Promise<Result<EncryptionKey>> {
+    await this.#ensureEncryptionKey()
+    const rows = await this.#selectEncryptionRows(`status = 'active'`)
+    if (rows.length === 0) {
+      return err(
+        authError.internalError(
+          "no active encryption key (should be unreachable)",
+        ),
+      )
+    }
+    return ok(await this.#hydrateEncryptionKey(rows[0]!))
+  }
+
+  async getEncryptionKey(kid: string): Promise<Result<EncryptionKey>> {
+    let row: EncryptionKeyRow | undefined
+    try {
+      const result = await this.#exec.query<EncryptionKeyRow>(
+        `SELECT kid, alg, key_material, key_material_wrapped, status, created_at, rotated_at
+           FROM openauth_encryption_keys WHERE kid = $1`,
+        [kid],
+      )
+      row = result.rows[0]
+    } catch (e) {
+      return err(authError.internalError("getEncryptionKey: query failed", e))
+    }
+    if (!row) {
+      return err(authError.internalError(`encryption key "${kid}" not found`))
+    }
+    return ok(await this.#hydrateEncryptionKey(row))
+  }
+
+  // --- bootstrap -------------------------------------------------------
+
+  async #ensureSigningKey(): Promise<void> {
+    const rows = await this.#selectSigningRows(`status = 'active'`)
+    if (rows.length > 0) return
+    const { publicKey, privateKey } = await generateKeyPair(this.#signingAlg, {
+      extractable: true,
+    })
+    const publicJwk = await exportJWK(publicKey)
+    const privateJwk = await exportJWK(privateKey)
+    const kid = randomId()
+    const { jsonPayload, wrapped } = await this.#encodePrivateJwk(privateJwk)
+    await this.#exec.query(
+      `INSERT INTO openauth_signing_keys
+         (kid, alg, crv, public_jwk, private_jwk, private_jwk_wrapped, status, created_at)
+       VALUES ($1, $2, $3, $4::jsonb, $5::jsonb, $6, 'active', $7)
+       ON CONFLICT (kid) DO NOTHING`,
+      [
+        kid,
+        this.#signingAlg,
+        publicJwk.crv ?? null,
+        JSON.stringify(publicJwk),
+        jsonPayload,
+        wrapped,
+        this.#clock(),
+      ],
+    )
+  }
+
+  async #ensureEncryptionKey(): Promise<void> {
+    const rows = await this.#selectEncryptionRows(`status = 'active'`)
+    if (rows.length > 0) return
+    const kid = randomId()
+    const raw = generateSymmetricKey() // 32 bytes
+    const stored = this.#wrapper ? await this.#wrapper.wrap(raw) : raw
+    await this.#exec.query(
+      `INSERT INTO openauth_encryption_keys
+         (kid, alg, key_material, key_material_wrapped, status, created_at)
+       VALUES ($1, $2, $3, $4, 'active', $5)
+       ON CONFLICT (kid) DO NOTHING`,
+      [kid, "A256GCM", stored, this.#wrapper !== undefined, this.#clock()],
+    )
+  }
+
+  /**
+   * Encode a private JWK for `private_jwk jsonb` storage. With a wrapper,
+   * the plaintext JWK bytes are encrypted and stored as `{"ct": <base64url>}`
+   * — never as a recognizable JWK on disk. Without one, the JWK is stored
+   * verbatim.
+   */
+  async #encodePrivateJwk(
+    jwk: JWK,
+  ): Promise<{ jsonPayload: string; wrapped: boolean }> {
+    if (!this.#wrapper) {
+      return { jsonPayload: JSON.stringify(jwk), wrapped: false }
+    }
+    const ciphertext = await this.#wrapper.wrap(
+      utf8.encode(JSON.stringify(jwk)),
+    )
+    return {
+      jsonPayload: JSON.stringify({ ct: base64url.encode(ciphertext) }),
+      wrapped: true,
+    }
+  }
+
+  async #decodePrivateJwk(raw: unknown, wrapped: boolean): Promise<JWK> {
+    const parsed =
+      typeof raw === "string"
+        ? (JSON.parse(raw) as Record<string, unknown>)
+        : (raw as Record<string, unknown>)
+    if (!wrapped) return parsed as unknown as JWK
+    if (!this.#wrapper) {
+      throw new Error(
+        "PostgresKeyStore: signing key row is wrapped but no `wrapper` was supplied — refusing to read",
+      )
+    }
+    const ct = typeof parsed.ct === "string" ? parsed.ct : ""
+    if (!ct) {
+      throw new Error("PostgresKeyStore: wrapped signing key row missing `ct`")
+    }
+    const plaintext = await this.#wrapper.unwrap(base64url.decode(ct))
+    return JSON.parse(utf8.decode(plaintext)) as JWK
+  }
+
+  // --- helpers --------------------------------------------------------
+
+  async #selectSigningRows(where: string): Promise<SigningKeyRow[]> {
+    const result = await this.#exec.query<SigningKeyRow>(
+      `SELECT kid, alg, crv, public_jwk, private_jwk, private_jwk_wrapped,
+              status, created_at, rotated_at
+         FROM openauth_signing_keys WHERE ${where}`,
+    )
+    return result.rows
+  }
+
+  async #selectEncryptionRows(where: string): Promise<EncryptionKeyRow[]> {
+    const result = await this.#exec.query<EncryptionKeyRow>(
+      `SELECT kid, alg, key_material, key_material_wrapped, status, created_at, rotated_at
+         FROM openauth_encryption_keys WHERE ${where}`,
+    )
+    return result.rows
+  }
+
+  async #hydrateSigningKey(row: SigningKeyRow): Promise<SigningKey> {
+    let imported = this.#privateKeyCache.get(row.kid)
+    if (!imported) {
+      const privateJwk = await this.#decodePrivateJwk(
+        row.private_jwk,
+        row.private_jwk_wrapped === true,
+      )
+      imported = await importJWK(privateJwk, row.alg)
+      this.#privateKeyCache.set(row.kid, imported)
+    }
+    const publicJwk =
+      typeof row.public_jwk === "string"
+        ? (JSON.parse(row.public_jwk) as Record<string, unknown>)
+        : (row.public_jwk as Record<string, unknown>)
+    return {
+      kid: row.kid,
+      alg: row.alg,
+      ...(row.crv ? { crv: row.crv } : {}),
+      publicJwk,
+      privateKeyRef: imported,
+      status: row.status as SigningKey["status"],
+      createdAt: Number(row.created_at),
+      ...(row.rotated_at !== null && row.rotated_at !== undefined
+        ? { rotatedAt: Number(row.rotated_at) }
+        : {}),
+    }
+  }
+
+  async #hydrateEncryptionKey(row: EncryptionKeyRow): Promise<EncryptionKey> {
+    const stored = ensureBytes(row.key_material)
+    let keyRef = stored
+    if (row.key_material_wrapped === true) {
+      if (!this.#wrapper) {
+        throw new Error(
+          "PostgresKeyStore: encryption key row is wrapped but no `wrapper` was supplied — refusing to read",
+        )
+      }
+      keyRef = await this.#wrapper.unwrap(stored)
+    }
+    return {
+      kid: row.kid,
+      alg: row.alg,
+      keyRef,
+      status: row.status as EncryptionKey["status"],
+      createdAt: Number(row.created_at),
+      ...(row.rotated_at !== null && row.rotated_at !== undefined
+        ? { rotatedAt: Number(row.rotated_at) }
+        : {}),
+    }
+  }
+}
+
+type SigningKeyRow = {
+  kid: string
+  alg: string
+  crv: string | null
+  public_jwk: unknown
+  private_jwk: unknown
+  private_jwk_wrapped: boolean | number | null
+  status: string
+  created_at: string | number
+  rotated_at: string | number | null
+}
+
+type EncryptionKeyRow = {
+  kid: string
+  alg: string
+  key_material: Uint8Array | { type: string; data: number[] } | string
+  key_material_wrapped: boolean | number | null
+  status: string
+  created_at: string | number
+  rotated_at: string | number | null
+}
+
+/**
+ * Some drivers return `bytea` columns as `Uint8Array`; some return
+ * `Buffer`; some return base64-decoded strings or `{ type: "Buffer", data: [...] }`.
+ * Normalize to a plain `Uint8Array` so the encryption path is driver-agnostic.
+ */
+function ensureBytes(value: EncryptionKeyRow["key_material"]): Uint8Array {
+  if (value instanceof Uint8Array) return value
+  if (typeof value === "string") {
+    // Best-effort: hex-encoded by postgres-js default; PGlite returns Uint8Array.
+    if (/^\\x[0-9a-fA-F]+$/.test(value)) {
+      const hex = value.slice(2)
+      const out = new Uint8Array(hex.length / 2)
+      for (let i = 0; i < out.length; i++) {
+        out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16)
+      }
+      return out
+    }
+    return new TextEncoder().encode(value)
+  }
+  if (
+    value &&
+    typeof value === "object" &&
+    "data" in (value as Record<string, unknown>)
+  ) {
+    return new Uint8Array((value as { data: number[] }).data)
+  }
+  throw new Error("PostgresKeyStore: unsupported bytea representation")
+}

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

@@ -0,0 +1,104 @@
+/**
+ * Postgres `MethodStore`. `(tenant_id, method_id)` composite key, JSONB
+ * `config` column for the method-config blob.
+ */
+import type { MethodStore } from "../../ports/method-store"
+import { authError } from "../../types/error"
+import type { Result } from "../../types/result"
+import { err, ok } from "../../types/result"
+import type { MethodConfig, TenantId } from "../../types/tenant"
+
+import type { PostgresExecutor } from "./executor"
+
+export type PostgresMethodStoreOptions = {
+  exec: PostgresExecutor
+  clock?: () => number
+}
+
+export class PostgresMethodStore implements MethodStore {
+  #exec: PostgresExecutor
+  #clock: () => number
+
+  constructor(opts: PostgresMethodStoreOptions) {
+    this.#exec = opts.exec
+    this.#clock = opts.clock ?? (() => Date.now())
+  }
+
+  async listMethods(tenantId: TenantId): Promise<Result<MethodConfig[]>> {
+    try {
+      const result = await this.#exec.query<{ config: unknown }>(
+        `SELECT config FROM openauth_methods WHERE tenant_id = $1 ORDER BY method_id`,
+        [tenantId],
+      )
+      const methods = result.rows.map((r) => parseConfig(r.config))
+      return ok(methods)
+    } catch (e) {
+      return err(authError.internalError("listMethods: query failed", e))
+    }
+  }
+
+  async getMethodConfig(
+    tenantId: TenantId,
+    methodId: string,
+  ): Promise<Result<MethodConfig>> {
+    let row: { config: unknown } | undefined
+    try {
+      const result = await this.#exec.query<{ config: unknown }>(
+        `SELECT config FROM openauth_methods WHERE tenant_id = $1 AND method_id = $2`,
+        [tenantId, methodId],
+      )
+      row = result.rows[0]
+    } catch (e) {
+      return err(authError.internalError("getMethodConfig: query failed", e))
+    }
+    if (!row) {
+      return err(
+        authError.methodNotFound(
+          `method "${methodId}" not found for tenant "${tenantId}"`,
+          { methodId },
+        ),
+      )
+    }
+    return ok(parseConfig(row.config))
+  }
+
+  async putMethodConfig(
+    tenantId: TenantId,
+    method: MethodConfig,
+  ): Promise<Result<void>> {
+    try {
+      await this.#exec.query(
+        `INSERT INTO openauth_methods (tenant_id, method_id, config, updated_at)
+         VALUES ($1, $2, $3::jsonb, $4)
+         ON CONFLICT (tenant_id, method_id) DO UPDATE
+           SET config = EXCLUDED.config, updated_at = EXCLUDED.updated_at`,
+        [tenantId, method.id, JSON.stringify(method), this.#clock()],
+      )
+    } catch (e) {
+      return err(authError.internalError("putMethodConfig: insert failed", e))
+    }
+    return ok(undefined)
+  }
+
+  async deleteMethodConfig(
+    tenantId: TenantId,
+    methodId: string,
+  ): Promise<Result<void>> {
+    try {
+      await this.#exec.query(
+        `DELETE FROM openauth_methods WHERE tenant_id = $1 AND method_id = $2`,
+        [tenantId, methodId],
+      )
+    } catch (e) {
+      return err(
+        authError.internalError("deleteMethodConfig: delete failed", e),
+      )
+    }
+    return ok(undefined)
+  }
+}
+
+function parseConfig(raw: unknown): MethodConfig {
+  if (typeof raw === "string") return JSON.parse(raw) as MethodConfig
+  return raw as MethodConfig
+}