@_mustachio/openauth 0.9.2 → 0.11.0

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

@@ -0,0 +1,176 @@
+/**
+ * KMS-backed `KeyStore`.
+ *
+ * Envelope encryption: generate a JWK key pair (or AES key) locally, wrap
+ * the private material with AWS KMS `Encrypt`, store the ciphertext in the
+ * supplied `KmsBackingStore`. On read, unwrap with KMS `Decrypt` and
+ * `importJWK` so the framework receives a normal `CryptoKey` for JWT signing
+ * — no surgery in `domain/jwt.ts`.
+ *
+ * Hot-path KMS calls are cached: signing keys are imported once per
+ * `kid` and re-used (a `CryptoKey` is safe to share across signs). Encryption
+ * keys are cached in plaintext bytes per `kid` so `consumeCode` doesn't make
+ * a KMS call per request.
+ *
+ * Operators with strict no-cache-of-plaintext requirements can disable the
+ * cache via `cacheUnwrappedKeys: false` — every read then round-trips to
+ * KMS.
+ */
+import type { JWK } from "jose"
+import { exportJWK, generateKeyPair, importJWK } from "jose"
+
+import { generateSymmetricKey, randomId, utf8 } from "../../domain/crypto"
+import type { EncryptionKey, KeyStore, SigningKey } from "../../ports/key-store"
+import { authError } from "../../types/error"
+import type { Result } from "../../types/result"
+import { err, ok } from "../../types/result"
+
+import type {
+  KmsBackingStore,
+  KmsClientLike,
+  WrappedEncryptionKey,
+  WrappedSigningKey,
+} from "./types"
+
+export type KmsKeyStoreOptions = {
+  kms: KmsClientLike
+  backing: KmsBackingStore
+  clock?: () => number
+  signingAlg?: "ES256" | "EdDSA"
+  /** Default `true`. Set false for strict no-plaintext-cache deployments. */
+  cacheUnwrappedKeys?: boolean
+}
+
+export class KmsKeyStore implements KeyStore {
+  #kms: KmsClientLike
+  #backing: KmsBackingStore
+  #clock: () => number
+  #signingAlg: "ES256" | "EdDSA"
+  #cacheUnwrapped: boolean
+  #signingCache = new Map<string, unknown>()
+  #encryptionCache = new Map<string, Uint8Array>()
+
+  constructor(opts: KmsKeyStoreOptions) {
+    this.#kms = opts.kms
+    this.#backing = opts.backing
+    this.#clock = opts.clock ?? (() => Date.now())
+    this.#signingAlg = opts.signingAlg ?? "ES256"
+    this.#cacheUnwrapped = opts.cacheUnwrappedKeys ?? true
+  }
+
+  async currentSigningKey(): Promise<Result<SigningKey>> {
+    await this.#ensureSigningKey()
+    const all = await this.#backing.listSigningKeys()
+    const active = all.find((k) => k.status === "active")
+    if (!active) {
+      return err(
+        authError.internalError(
+          "no active signing key (should be unreachable)",
+        ),
+      )
+    }
+    return ok(await this.#hydrateSigning(active))
+  }
+
+  async signingKeys(): Promise<Result<SigningKey[]>> {
+    await this.#ensureSigningKey()
+    const all = await this.#backing.listSigningKeys()
+    const keys = await Promise.all(all.map((row) => this.#hydrateSigning(row)))
+    return ok(keys)
+  }
+
+  async currentEncryptionKey(): Promise<Result<EncryptionKey>> {
+    await this.#ensureEncryptionKey()
+    const all = await this.#backing.listEncryptionKeys()
+    const active = all.find((k) => k.status === "active")
+    if (!active) {
+      return err(
+        authError.internalError(
+          "no active encryption key (should be unreachable)",
+        ),
+      )
+    }
+    return ok(await this.#hydrateEncryption(active))
+  }
+
+  async getEncryptionKey(kid: string): Promise<Result<EncryptionKey>> {
+    const row = await this.#backing.getEncryptionKey(kid)
+    if (!row) {
+      return err(authError.internalError(`encryption key "${kid}" not found`))
+    }
+    return ok(await this.#hydrateEncryption(row))
+  }
+
+  async #ensureSigningKey(): Promise<void> {
+    const all = await this.#backing.listSigningKeys()
+    if (all.some((k) => k.status === "active")) return
+    const { publicKey, privateKey } = await generateKeyPair(this.#signingAlg, {
+      extractable: true,
+    })
+    const publicJwk = await exportJWK(publicKey)
+    const privateJwk = await exportJWK(privateKey)
+    const plaintext = utf8.encode(JSON.stringify(privateJwk))
+    const wrapped = await this.#kms.encrypt(plaintext)
+    const row: WrappedSigningKey = {
+      kid: randomId(),
+      alg: this.#signingAlg,
+      ...(publicJwk.crv ? { crv: publicJwk.crv } : {}),
+      publicJwk: publicJwk as unknown as Record<string, unknown>,
+      wrappedPrivate: wrapped,
+      status: "active",
+      createdAt: this.#clock(),
+    }
+    await this.#backing.putSigningKey(row)
+  }
+
+  async #ensureEncryptionKey(): Promise<void> {
+    const all = await this.#backing.listEncryptionKeys()
+    if (all.some((k) => k.status === "active")) return
+    const raw = generateSymmetricKey()
+    const wrapped = await this.#kms.encrypt(raw)
+    const row: WrappedEncryptionKey = {
+      kid: randomId(),
+      alg: "A256GCM",
+      wrappedKey: wrapped,
+      status: "active",
+      createdAt: this.#clock(),
+    }
+    await this.#backing.putEncryptionKey(row)
+  }
+
+  async #hydrateSigning(row: WrappedSigningKey): Promise<SigningKey> {
+    let imported = this.#signingCache.get(row.kid)
+    if (!imported) {
+      const plaintext = await this.#kms.decrypt(row.wrappedPrivate)
+      const jwk = JSON.parse(utf8.decode(plaintext)) as JWK
+      imported = await importJWK(jwk, row.alg)
+      if (this.#cacheUnwrapped) this.#signingCache.set(row.kid, imported)
+    }
+    return {
+      kid: row.kid,
+      alg: row.alg,
+      ...(row.crv ? { crv: row.crv } : {}),
+      publicJwk: row.publicJwk,
+      privateKeyRef: imported,
+      status: row.status,
+      createdAt: row.createdAt,
+      ...(row.rotatedAt !== undefined ? { rotatedAt: row.rotatedAt } : {}),
+    }
+  }
+
+  async #hydrateEncryption(row: WrappedEncryptionKey): Promise<EncryptionKey> {
+    let bytes = this.#encryptionCache.get(row.kid)
+    if (!bytes) {
+      bytes = await this.#kms.decrypt(row.wrappedKey)
+      if (this.#cacheUnwrapped) this.#encryptionCache.set(row.kid, bytes)
+    }
+    return {
+      kid: row.kid,
+      alg: row.alg,
+      keyRef: bytes,
+      status: row.status,
+      createdAt: row.createdAt,
+      ...(row.rotatedAt !== undefined ? { rotatedAt: row.rotatedAt } : {}),
+    }
+  }
+}

package/src/adapters/kms/sdk.ts

@@ -0,0 +1,39 @@
+/**
+ * `fromKmsClient` — wires the `KmsClientLike` interface to a real AWS KMS
+ * client. The KMS SDK is imported only from this file to keep the rest of
+ * the adapter bundle KMS-agnostic.
+ *
+ * @example
+ *   import { KMSClient } from "@aws-sdk/client-kms"
+ *   const kmsClient = new KMSClient({ region: "us-east-1" })
+ *   const kms = fromKmsClient(kmsClient, process.env.IDP_KMS_KEY_ARN!)
+ *   const backing = new PostgresKmsBackingStore({ exec })
+ *   const keyStore = new KmsKeyStore({ kms, backing })
+ */
+import type { KMSClient } from "@aws-sdk/client-kms"
+import { DecryptCommand, EncryptCommand } from "@aws-sdk/client-kms"
+
+import type { KmsClientLike } from "./types"
+
+export function fromKmsClient(client: KMSClient, keyId: string): KmsClientLike {
+  return {
+    async encrypt(plaintext: Uint8Array): Promise<Uint8Array> {
+      const result = await client.send(
+        new EncryptCommand({ KeyId: keyId, Plaintext: plaintext }),
+      )
+      if (!result.CiphertextBlob) {
+        throw new Error("KMS Encrypt returned no ciphertext")
+      }
+      return new Uint8Array(result.CiphertextBlob)
+    },
+    async decrypt(ciphertext: Uint8Array): Promise<Uint8Array> {
+      const result = await client.send(
+        new DecryptCommand({ KeyId: keyId, CiphertextBlob: ciphertext }),
+      )
+      if (!result.Plaintext) {
+        throw new Error("KMS Decrypt returned no plaintext")
+      }
+      return new Uint8Array(result.Plaintext)
+    },
+  }
+}

package/src/adapters/kms/types.ts

@@ -0,0 +1,61 @@
+/**
+ * KMS adapter interfaces.
+ *
+ * The KMS-backed `KeyStore` uses **envelope encryption** for private key
+ * material: the JWK private bytes (signing) and the raw AES key bytes
+ * (encryption) are wrapped under a KMS master key. The ciphertext blob is
+ * stored in a pluggable backing store; KMS Encrypt / Decrypt are the only
+ * KMS operations on the hot path.
+ *
+ * This shape keeps private material out of plaintext at rest while
+ * preserving the JWT signing path: the framework still receives a real
+ * `CryptoKey` (`importJWK` of the unwrapped JWK) so `domain/jwt.ts` doesn't
+ * need to know KMS exists.
+ */
+
+/** Minimal KMS surface the adapter depends on. */
+export type KmsClientLike = {
+  /** Encrypt up to ~4 KB of plaintext under the master key. */
+  encrypt(plaintext: Uint8Array): Promise<Uint8Array>
+  /** Decrypt a previously-issued ciphertext under the master key. */
+  decrypt(ciphertext: Uint8Array): Promise<Uint8Array>
+}
+
+/**
+ * Persistent storage for KMS-wrapped key envelopes. Adapters provide their
+ * own (Postgres, DynamoDB, file), or pass `inMemoryKmsBackingStore()` for
+ * tests / single-instance dev.
+ *
+ * `wrappedPrivate` is the KMS-wrapped private material (JWK bytes for
+ * signing keys, raw AES key bytes for encryption keys). `publicJwk` is the
+ * public material (never sensitive); it's kept plaintext alongside the
+ * ciphertext so JWKS lookups don't need a KMS round trip.
+ */
+export type KmsBackingStore = {
+  putSigningKey(row: WrappedSigningKey): Promise<void>
+  getSigningKey(kid: string): Promise<WrappedSigningKey | undefined>
+  listSigningKeys(): Promise<WrappedSigningKey[]>
+  putEncryptionKey(row: WrappedEncryptionKey): Promise<void>
+  getEncryptionKey(kid: string): Promise<WrappedEncryptionKey | undefined>
+  listEncryptionKeys(): Promise<WrappedEncryptionKey[]>
+}
+
+export type WrappedSigningKey = {
+  kid: string
+  alg: string
+  crv?: string
+  publicJwk: Record<string, unknown>
+  wrappedPrivate: Uint8Array
+  status: "active" | "next" | "retired"
+  createdAt: number
+  rotatedAt?: number
+}
+
+export type WrappedEncryptionKey = {
+  kid: string
+  alg: string
+  wrappedKey: Uint8Array
+  status: "active" | "next" | "retired"
+  createdAt: number
+  rotatedAt?: number
+}

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

@@ -0,0 +1,40 @@
+/**
+ * Cloudflare KV `AuditLog`. Append-only with per-event keys of the shape
+ * `audit:<paddedTs>:<rand>` so KV's lexicographic list returns events in
+ * insertion order. Suitable for low-volume audit (the IdP) where reads are
+ * SIEM-style after-the-fact, not hot-path. High-volume deployments should
+ * ship events out-of-band to a real append-log.
+ */
+import type { AuditEvent, AuditLog } from "../../ports/audit-log"
+
+import type { KVNamespaceLike } from "./types"
+
+const PREFIX = "audit:"
+
+export type KvAuditLogOptions = {
+  kv: KVNamespaceLike
+  /** Optional TTL (seconds). 90 days minimum per CONSISTENCY.md SOC 2 baseline. */
+  expirationTtl?: number
+}
+
+export class KvAuditLog implements AuditLog {
+  #kv: KVNamespaceLike
+  #ttl: number | undefined
+
+  constructor(opts: KvAuditLogOptions) {
+    this.#kv = opts.kv
+    this.#ttl = opts.expirationTtl
+  }
+
+  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.#kv.put(
+        `${PREFIX}${padded}:${suffix}`,
+        JSON.stringify(event),
+        this.#ttl ? { expirationTtl: this.#ttl } : undefined,
+      )
+    } catch {}
+  }
+}

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

@@ -0,0 +1,63 @@
+/**
+ * Cloudflare KV `ConfigStore`. JSON-serialized tenant config under
+ * `tenant:<id>`. Per `ports/CONSISTENCY.md`, KV is **only** acceptable for
+ * read-eventual paths — tenant config qualifies (read-heavy, write-rare,
+ * 60s bounded staleness is fine). Invalidation hook fires on every
+ * `putTenantConfig`.
+ *
+ * KV reads honor the cache hint via `cacheTtl` in the get options. The
+ * 60-second default matches the bounded-staleness contract.
+ */
+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 { KVNamespaceLike } from "./types"
+
+const TENANT_PREFIX = "tenant:"
+
+export type KvConfigStoreOptions = {
+  kv: KVNamespaceLike
+}
+
+export class KvConfigStore implements ConfigStore {
+  #kv: KVNamespaceLike
+  #listeners = new Set<(id: TenantId) => void>()
+
+  constructor(opts: KvConfigStoreOptions) {
+    this.#kv = opts.kv
+  }
+
+  async getTenantConfig(id: TenantId): Promise<Result<TenantConfig>> {
+    let raw: string | null
+    try {
+      raw = await this.#kv.get(TENANT_PREFIX + id)
+    } catch (e) {
+      return err(authError.internalError("getTenantConfig: kv.get failed", e))
+    }
+    if (!raw) {
+      return err(authError.tenantNotFound(`tenant "${id}" not found`, id))
+    }
+    return ok(JSON.parse(raw) as TenantConfig)
+  }
+
+  async putTenantConfig(config: TenantConfig): Promise<Result<void>> {
+    try {
+      await this.#kv.put(TENANT_PREFIX + config.id, JSON.stringify(config))
+    } catch (e) {
+      return err(authError.internalError("putTenantConfig: kv.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)
+  }
+}

package/src/adapters/kv/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Cloudflare KV adapters — **restricted use only**.
+ *
+ * Per `ports/CONSISTENCY.md`, KV's eventual consistency disqualifies it as
+ * a backing store for `TokenStore` (auth codes, refresh tokens) and
+ * `SessionStore` (flow records). Use D1 / Durable Objects / Postgres /
+ * DynamoDB for those. KV remains a great fit for the read-eventual paths
+ * exposed in this package:
+ *
+ *  - `KvConfigStore` — tenant config blob keyed by id
+ *  - `KvMethodStore` — per-tenant method configs
+ *  - `KvAuditLog` — append-only audit events (low-volume only)
+ *
+ * Production users typically mix-and-match: KV for config + D1 for tokens
+ * + Durable Objects for sessions.
+ */
+export { KvAuditLog, type KvAuditLogOptions } from "./audit-log"
+export { KvConfigStore, type KvConfigStoreOptions } from "./config-store"
+export { KvMethodStore, type KvMethodStoreOptions } from "./method-store"
+export type { KVNamespaceLike } from "./types"

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

@@ -0,0 +1,98 @@
+/**
+ * Cloudflare KV `MethodStore`. Per-method JSON under
+ * `method:<tenantId>:<methodId>`. `listMethods` uses the KV `list` cursor +
+ * follow-up `get` per key — fine for the read-rare console workflow but
+ * not for hot per-request paths (the IdP framework caches `MethodConfig`
+ * via `MethodCache` in-process).
+ */
+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 { KVNamespaceLike } from "./types"
+
+const methodKey = (tenantId: TenantId, methodId: string) =>
+  `method:${tenantId}:${methodId}`
+const methodPrefix = (tenantId: TenantId) => `method:${tenantId}:`
+
+export type KvMethodStoreOptions = {
+  kv: KVNamespaceLike
+}
+
+export class KvMethodStore implements MethodStore {
+  #kv: KVNamespaceLike
+
+  constructor(opts: KvMethodStoreOptions) {
+    this.#kv = opts.kv
+  }
+
+  async listMethods(tenantId: TenantId): Promise<Result<MethodConfig[]>> {
+    const prefix = methodPrefix(tenantId)
+    const methods: MethodConfig[] = []
+    let cursor: string | null | undefined
+    try {
+      do {
+        const page = await this.#kv.list({ prefix, cursor: cursor ?? null })
+        for (const k of page.keys) {
+          const value = await this.#kv.get(k.name)
+          if (value) methods.push(JSON.parse(value) as MethodConfig)
+        }
+        cursor = page.list_complete ? undefined : page.cursor
+      } while (cursor)
+    } catch (e) {
+      return err(authError.internalError("listMethods: kv.list failed", e))
+    }
+    // KV doesn't guarantee list order; the conformance suite sorts by id.
+    methods.sort((a, b) => a.id.localeCompare(b.id))
+    return ok(methods)
+  }
+
+  async getMethodConfig(
+    tenantId: TenantId,
+    methodId: string,
+  ): Promise<Result<MethodConfig>> {
+    let raw: string | null
+    try {
+      raw = await this.#kv.get(methodKey(tenantId, methodId))
+    } catch (e) {
+      return err(authError.internalError("getMethodConfig: kv.get failed", e))
+    }
+    if (!raw) {
+      return err(
+        authError.methodNotFound(
+          `method "${methodId}" not found for tenant "${tenantId}"`,
+          { methodId },
+        ),
+      )
+    }
+    return ok(JSON.parse(raw) as MethodConfig)
+  }
+
+  async putMethodConfig(
+    tenantId: TenantId,
+    method: MethodConfig,
+  ): Promise<Result<void>> {
+    try {
+      await this.#kv.put(methodKey(tenantId, method.id), JSON.stringify(method))
+    } catch (e) {
+      return err(authError.internalError("putMethodConfig: kv.put failed", e))
+    }
+    return ok(undefined)
+  }
+
+  async deleteMethodConfig(
+    tenantId: TenantId,
+    methodId: string,
+  ): Promise<Result<void>> {
+    try {
+      await this.#kv.delete(methodKey(tenantId, methodId))
+    } catch (e) {
+      return err(
+        authError.internalError("deleteMethodConfig: kv.delete failed", e),
+      )
+    }
+    return ok(undefined)
+  }
+}

package/src/adapters/kv/types.ts

@@ -0,0 +1,26 @@
+/**
+ * Minimal `KVNamespace` shape the adapter depends on. Pinned locally so the
+ * adapter is testable without a real Workers runtime.
+ *
+ * Real `KVNamespace` instances satisfy this interface — pass `env.AUTH_KV`
+ * directly.
+ */
+export type KVNamespaceLike = {
+  get(key: string): Promise<string | null>
+  get<T>(key: string, type: "json"): Promise<T | null>
+  put(
+    key: string,
+    value: string,
+    options?: { expirationTtl?: number; expiration?: number },
+  ): Promise<void>
+  delete(key: string): Promise<void>
+  list(options?: {
+    prefix?: string
+    cursor?: string | null
+    limit?: number
+  }): Promise<{
+    keys: Array<{ name: string }>
+    list_complete: boolean
+    cursor?: string
+  }>
+}

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

@@ -0,0 +1,28 @@
+/**
+ * In-memory `AuditLog`. Stores events in an array that tests can inspect.
+ * Production deployments use a real backend (Clickhouse, OTEL, etc.).
+ */
+import type { AuditEvent, AuditLog } from "../../ports/audit-log"
+
+export type StoredAuditEvent = AuditEvent & { timestamp: number }
+
+export class MemoryAuditLog implements AuditLog {
+  events: StoredAuditEvent[] = []
+
+  async log(event: StoredAuditEvent): Promise<void> {
+    this.events.push(event)
+  }
+
+  /** Test helper — find events of a given kind. */
+  byKind<K extends AuditEvent["kind"]>(
+    kind: K,
+  ): Array<Extract<StoredAuditEvent, { kind: K }>> {
+    return this.events.filter((e) => e.kind === kind) as Array<
+      Extract<StoredAuditEvent, { kind: K }>
+    >
+  }
+
+  clear(): void {
+    this.events = []
+  }
+}

package/src/adapters/memory/clock.ts

@@ -0,0 +1,7 @@
+/**
+ * Tiny injectable clock used by every memory adapter so tests can advance
+ * time deterministically.
+ */
+export type Clock = () => number
+
+export const realClock: Clock = () => Date.now()

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

@@ -0,0 +1,41 @@
+/**
+ * In-memory `ConfigStore`. Single-process; trivially satisfies the
+ * eventual + bounded-staleness contract (it's strong, which is a superset).
+ */
+import type { ConfigStore } from "../../ports/config-store"
+import type { Result } from "../../types/result"
+import { err, ok } from "../../types/result"
+import { authError } from "../../types/error"
+import type { TenantConfig, TenantId } from "../../types/tenant"
+
+export type MemoryConfigStoreOptions = {
+  /** Seed tenants — useful for tests. */
+  seed?: ReadonlyArray<TenantConfig>
+}
+
+export class MemoryConfigStore implements ConfigStore {
+  #tenants = new Map<TenantId, TenantConfig>()
+  #listeners = new Set<(id: TenantId) => void>()
+
+  constructor(opts: MemoryConfigStoreOptions = {}) {
+    for (const t of opts.seed ?? []) this.#tenants.set(t.id, t)
+  }
+
+  async getTenantConfig(id: TenantId): Promise<Result<TenantConfig>> {
+    const t = this.#tenants.get(id)
+    if (!t) {
+      return err(authError.tenantNotFound(`tenant "${id}" not found`, id))
+    }
+    return ok(t)
+  }
+
+  async putTenantConfig(config: TenantConfig): Promise<Result<void>> {
+    this.#tenants.set(config.id, config)
+    for (const fn of this.#listeners) fn(config.id)
+    return ok(undefined)
+  }
+
+  onInvalidate(handler: (id: TenantId) => void): void {
+    this.#listeners.add(handler)
+  }
+}

package/src/adapters/memory/index.ts

@@ -0,0 +1,26 @@
+/**
+ * In-memory adapter set. Map-backed. Suitable for tests and single-instance
+ * dev. Trivially satisfies all consistency contracts in
+ * `ports/CONSISTENCY.md` because there's no concurrent process / replica
+ * lag.
+ */
+export { MemoryAuditLog, type StoredAuditEvent } from "./audit-log"
+export {
+  MemoryConfigStore,
+  type MemoryConfigStoreOptions,
+} from "./config-store"
+export { MemoryKeyStore, type MemoryKeyStoreOptions } from "./key-store"
+export {
+  MemoryMethodStore,
+  type MemoryMethodStoreOptions,
+} from "./method-store"
+export {
+  MemorySessionStore,
+  type MemorySessionStoreOptions,
+} from "./session-store"
+export { MemoryTokenStore, type MemoryTokenStoreOptions } from "./token-store"
+export {
+  MemoryPasskeyCredentialStore,
+  type MemoryPasskeyCredentialStoreOptions,
+} from "./passkey-credential-store"
+export { realClock, type Clock } from "./clock"