@_mustachio/openauth 0.9.2 → 0.10.0

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"

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

@@ -0,0 +1,102 @@
+/**
+ * In-memory `KeyStore`. Auto-generates ES256 signing keys and A256GCM
+ * encryption keys on first read. Suitable for tests and single-instance
+ * dev.
+ */
+import { exportJWK, generateKeyPair } from "jose"
+
+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 { generateSymmetricKey, randomId } from "../../domain/crypto"
+import type { Clock } from "./clock"
+import { realClock } from "./clock"
+
+export type MemoryKeyStoreOptions = {
+  clock?: Clock
+  /** Override default `"ES256"` (other supported: `"EdDSA"` per AD11). */
+  signingAlg?: "ES256" | "EdDSA"
+}
+
+export class MemoryKeyStore implements KeyStore {
+  #clock: Clock
+  #signingAlg: "ES256" | "EdDSA"
+  #signing: SigningKey[] = []
+  #encryption: EncryptionKey[] = []
+
+  constructor(opts: MemoryKeyStoreOptions = {}) {
+    this.#clock = opts.clock ?? realClock
+    this.#signingAlg = opts.signingAlg ?? "ES256"
+  }
+
+  async currentSigningKey(): Promise<Result<SigningKey>> {
+    await this.#ensureSigningKey()
+    const active = this.#signing.find((k) => k.status === "active")
+    if (!active) {
+      return err(
+        authError.internalError(
+          "no active signing key (should be unreachable)",
+        ),
+      )
+    }
+    return ok(active)
+  }
+
+  async signingKeys(): Promise<Result<SigningKey[]>> {
+    await this.#ensureSigningKey()
+    return ok([...this.#signing])
+  }
+
+  async currentEncryptionKey(): Promise<Result<EncryptionKey>> {
+    this.#ensureEncryptionKey()
+    const active = this.#encryption.find((k) => k.status === "active")
+    if (!active) {
+      return err(
+        authError.internalError(
+          "no active encryption key (should be unreachable)",
+        ),
+      )
+    }
+    return ok(active)
+  }
+
+  async getEncryptionKey(kid: string): Promise<Result<EncryptionKey>> {
+    this.#ensureEncryptionKey()
+    const match = this.#encryption.find((k) => k.kid === kid)
+    if (!match) {
+      return err(authError.internalError(`encryption key "${kid}" not found`))
+    }
+    return ok(match)
+  }
+
+  async #ensureSigningKey(): Promise<void> {
+    if (this.#signing.some((k) => k.status === "active")) return
+    const { publicKey, privateKey } = await generateKeyPair(this.#signingAlg, {
+      extractable: true,
+    })
+    const jwk = await exportJWK(publicKey)
+    const key: SigningKey = {
+      kid: randomId(),
+      alg: this.#signingAlg,
+      crv: jwk.crv ?? undefined,
+      publicJwk: jwk as unknown as Record<string, unknown>,
+      privateKeyRef: privateKey,
+      status: "active",
+      createdAt: this.#clock(),
+    }
+    this.#signing.push(key)
+  }
+
+  #ensureEncryptionKey(): void {
+    if (this.#encryption.some((k) => k.status === "active")) return
+    const key: EncryptionKey = {
+      kid: randomId(),
+      alg: "A256GCM",
+      keyRef: generateSymmetricKey(),
+      status: "active",
+      createdAt: this.#clock(),
+    }
+    this.#encryption.push(key)
+  }
+}

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

@@ -0,0 +1,75 @@
+/**
+ * In-memory `MethodStore`. Per-tenant `Map<methodId, MethodConfig>`. Single
+ * process so the eventual + bounded-staleness contract is trivially satisfied.
+ *
+ * `MethodStore` is optional in the IdP — when omitted, the framework falls
+ * back to slicing `MethodConfig[]` out of `ConfigStore.getTenantConfig`. The
+ * memory adapter still ships so the conformance suite has a baseline.
+ */
+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"
+
+export type MemoryMethodStoreOptions = {
+  seed?: ReadonlyArray<{
+    tenantId: TenantId
+    methods: ReadonlyArray<MethodConfig>
+  }>
+}
+
+export class MemoryMethodStore implements MethodStore {
+  #byTenant = new Map<TenantId, Map<string, MethodConfig>>()
+
+  constructor(opts: MemoryMethodStoreOptions = {}) {
+    for (const seed of opts.seed ?? []) {
+      const inner = new Map<string, MethodConfig>()
+      for (const m of seed.methods) inner.set(m.id, m)
+      this.#byTenant.set(seed.tenantId, inner)
+    }
+  }
+
+  async listMethods(tenantId: TenantId): Promise<Result<MethodConfig[]>> {
+    const inner = this.#byTenant.get(tenantId)
+    return ok(inner ? Array.from(inner.values()) : [])
+  }
+
+  async getMethodConfig(
+    tenantId: TenantId,
+    methodId: string,
+  ): Promise<Result<MethodConfig>> {
+    const inner = this.#byTenant.get(tenantId)
+    const m = inner?.get(methodId)
+    if (!m) {
+      return err(
+        authError.methodNotFound(
+          `method "${methodId}" not found for tenant "${tenantId}"`,
+          { methodId },
+        ),
+      )
+    }
+    return ok(m)
+  }
+
+  async putMethodConfig(
+    tenantId: TenantId,
+    method: MethodConfig,
+  ): Promise<Result<void>> {
+    let inner = this.#byTenant.get(tenantId)
+    if (!inner) {
+      inner = new Map<string, MethodConfig>()
+      this.#byTenant.set(tenantId, inner)
+    }
+    inner.set(method.id, method)
+    return ok(undefined)
+  }
+
+  async deleteMethodConfig(
+    tenantId: TenantId,
+    methodId: string,
+  ): Promise<Result<void>> {
+    this.#byTenant.get(tenantId)?.delete(methodId)
+    return ok(undefined)
+  }
+}

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

@@ -0,0 +1,97 @@
+/**
+ * In-memory `PasskeyCredentialStore`. Map-backed, single-process —
+ * suitable for tests and single-instance dev.
+ *
+ * Schema simplification (shared by all three reference adapters): the
+ * `userId` field is also the username lookup key. This matches the
+ * bundled `passkeyMethod`, which sets `userId = parsed.data.username`
+ * at registration time. Hosts that need a richer mapping
+ * (username ≠ userId, multi-username-per-user, etc.) implement
+ * `PasskeyCredentialStore` directly against their own data model.
+ */
+import type {
+  PasskeyCredentialStore,
+  StoredCredential,
+} from "../../methods/passkey"
+
+export type MemoryPasskeyCredentialStoreOptions = {
+  /**
+   * Optional seed list for tests / dev. Each entry is the full
+   * `StoredCredential` plus its tenant scope. The store treats the
+   * credential's `userId` as the username lookup key.
+   */
+  seed?: Array<{ tenantId: string; credential: StoredCredential }>
+}
+
+export class MemoryPasskeyCredentialStore implements PasskeyCredentialStore {
+  #items = new Map<string, StoredCredential & { tenantId: string }>()
+
+  constructor(opts: MemoryPasskeyCredentialStoreOptions = {}) {
+    for (const entry of opts.seed ?? []) {
+      this.#items.set(
+        this.#key(entry.tenantId, entry.credential.credentialId),
+        {
+          ...entry.credential,
+          tenantId: entry.tenantId,
+        },
+      )
+    }
+  }
+
+  #key(tenantId: string, credentialId: string): string {
+    return `${tenantId}|${credentialId}`
+  }
+
+  async findByUsername(
+    username: string,
+    tenantId: string,
+  ): Promise<{ userId: string; credentials: StoredCredential[] } | null> {
+    const credentials: StoredCredential[] = []
+    for (const item of this.#items.values()) {
+      if (item.tenantId !== tenantId) continue
+      if (item.userId !== username) continue
+      credentials.push(stripTenant(item))
+    }
+    if (credentials.length === 0) return null
+    return { userId: username, credentials }
+  }
+
+  async findById(
+    credentialId: string,
+    tenantId: string,
+  ): Promise<StoredCredential | null> {
+    const item = this.#items.get(this.#key(tenantId, credentialId))
+    return item ? stripTenant(item) : null
+  }
+
+  async updateCounter(input: {
+    credentialId: string
+    counter: number
+    tenantId: string
+  }): Promise<void> {
+    const k = this.#key(input.tenantId, input.credentialId)
+    const item = this.#items.get(k)
+    if (!item) return
+    this.#items.set(k, { ...item, counter: input.counter })
+  }
+
+  async create(input: {
+    userId: string
+    credential: StoredCredential
+    tenantId: string
+  }): Promise<void> {
+    this.#items.set(this.#key(input.tenantId, input.credential.credentialId), {
+      ...input.credential,
+      userId: input.userId,
+      tenantId: input.tenantId,
+    })
+  }
+}
+
+function stripTenant(
+  item: StoredCredential & { tenantId: string },
+): StoredCredential {
+  const { tenantId: _unused, ...rest } = item
+  void _unused
+  return rest
+}