@_mustachio/openauth 0.9.1 → 0.10.0

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

@@ -0,0 +1,248 @@
+/**
+ * DynamoDB `TokenStore`. Single-table design (`pk` / `sk` primary key,
+ * `family-index` and `subject-index` GSIs).
+ *
+ * Per `ports/CONSISTENCY.md`:
+ *   - All `get`s use `consistentRead: true` — the default eventual-read
+ *     would violate the auth-code / refresh-token contracts.
+ *   - All `delete`s use `ReturnValues=ALL_OLD` so atomic delete-on-read is
+ *     a single round trip.
+ *   - `consumeRefresh` uses a conditional `UpdateItem` with
+ *     `attribute_not_exists(consumed_at)` so concurrent presentations
+ *     resolve to one winner.
+ *
+ * Layout:
+ *   - `pk="code"`,    `sk=<code>`    — auth-code ciphertext blob (the
+ *       domain encrypts before saveCode; the adapter stores verbatim).
+ *   - `pk="refresh"`, `sk=<token>`   — refresh token + JSON payload.
+ *       GSI `family-index`:  hash = `family`
+ *       GSI `subject-index`: hash = `subject_key` (`<tenant>#<subject>`)
+ */
+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 { DynamoExecutor } from "./client"
+
+export type DynamoTokenStoreOptions = {
+  exec: DynamoExecutor
+  /**
+   * Optional — retained for API stability after M1 moved code-payload
+   * encryption to the domain layer. The adapter no longer touches it.
+   */
+  keyStore?: KeyStore
+  clock?: () => number
+}
+
+export class DynamoTokenStore implements TokenStore {
+  #exec: DynamoExecutor
+  #clock: () => number
+
+  constructor(opts: DynamoTokenStoreOptions) {
+    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 expiresAtMs = this.#clock() + ttl
+    try {
+      await this.#exec.put({
+        item: {
+          pk: "code",
+          sk: code,
+          ciphertext,
+          expires_at: expiresAtMs,
+          // DynamoDB native TTL is in seconds, named conventionally `ttl`.
+          // The adapter writes both so operators can enable TTL on the table.
+          ttl: Math.floor(expiresAtMs / 1000),
+        },
+      })
+    } catch (e) {
+      return err(authError.internalError("saveCode: put failed", e))
+    }
+    return ok(undefined)
+  }
+
+  async consumeCode(code: string): Promise<Result<string>> {
+    let row: Record<string, unknown> | undefined
+    try {
+      row = await this.#exec.delete({ key: { pk: "code", sk: code } })
+    } catch (e) {
+      return err(authError.internalError("consumeCode: delete 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(String(row.ciphertext))
+  }
+
+  async saveRefresh(
+    refresh: string,
+    payload: RefreshTokenPayload,
+  ): Promise<Result<void>> {
+    try {
+      await this.#exec.put({
+        item: {
+          pk: "refresh",
+          sk: refresh,
+          payload: JSON.stringify(payload),
+          family: payload.family,
+          subject_key: `${payload.tenantId}#${payload.subjectId}`,
+          tenant_id: payload.tenantId,
+          subject_id: payload.subjectId,
+          expires_at: payload.expiresAt,
+          ttl: Math.floor(payload.expiresAt / 1000),
+        },
+      })
+    } catch (e) {
+      return err(authError.internalError("saveRefresh: put 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()
+    let claimed: Record<string, unknown> | null
+    try {
+      claimed = await this.#exec.consumeRefresh({
+        key: { pk: "refresh", sk: refresh },
+        now,
+      })
+    } catch (e) {
+      return err(authError.internalError("consumeRefresh: claim failed", e))
+    }
+    if (claimed) {
+      return ok(parseRefresh(claimed.payload))
+    }
+    // No claim. Look up to disambiguate unknown vs already-consumed vs expired.
+    let existing: Record<string, unknown> | undefined
+    try {
+      existing = await this.#exec.get({
+        key: { pk: "refresh", sk: refresh },
+        consistentRead: true,
+      })
+    } catch (e) {
+      return err(authError.internalError("consumeRefresh: lookup failed", e))
+    }
+    if (!existing) {
+      return err(authError.invalidGrant("refresh token unknown"))
+    }
+    if (existing.consumed_at !== undefined && existing.consumed_at !== null) {
+      const consumedAt = Number(existing.consumed_at)
+      const withinWindow = now - consumedAt <= reuseWindow
+      if (withinWindow) {
+        const payload = parseRefresh(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"))
+    }
+    return err(authError.internalError("consumeRefresh: unexplained miss"))
+  }
+
+  async peekRefresh(refresh: string): Promise<Result<RefreshTokenPayload>> {
+    let existing: Record<string, unknown> | undefined
+    try {
+      existing = await this.#exec.get({
+        key: { pk: "refresh", sk: refresh },
+        consistentRead: true,
+      })
+    } catch (e) {
+      return err(authError.internalError("peekRefresh: lookup failed", e))
+    }
+    if (!existing) {
+      return err(authError.invalidGrant("refresh token unknown"))
+    }
+    if (this.#clock() >= Number(existing.expires_at)) {
+      return err(authError.invalidGrant("refresh token expired"))
+    }
+    return ok(parseRefresh(existing.payload))
+  }
+
+  async revokeFamily(family: string): Promise<Result<void>> {
+    let items: Record<string, unknown>[]
+    try {
+      items = await this.#exec.queryByGsi({
+        indexName: "family-index",
+        hashKey: family,
+      })
+    } catch (e) {
+      return err(authError.internalError("revokeFamily: query failed", e))
+    }
+    for (const item of items) {
+      try {
+        await this.#exec.delete({
+          key: { pk: String(item.pk), sk: String(item.sk) },
+        })
+      } catch {
+        // Best-effort — a deletion losing a race is acceptable.
+      }
+    }
+    return ok(undefined)
+  }
+
+  async revokeBySubject(
+    tenantId: TenantId,
+    subjectId: string,
+  ): Promise<Result<void>> {
+    let items: Record<string, unknown>[]
+    try {
+      items = await this.#exec.queryByGsi({
+        indexName: "subject-index",
+        hashKey: `${tenantId}#${subjectId}`,
+      })
+    } catch (e) {
+      return err(authError.internalError("revokeBySubject: query failed", e))
+    }
+    for (const item of items) {
+      try {
+        await this.#exec.delete({
+          key: { pk: String(item.pk), sk: String(item.sk) },
+        })
+      } catch {}
+    }
+    return ok(undefined)
+  }
+}
+
+function parseRefresh(raw: unknown): RefreshTokenPayload {
+  if (typeof raw === "string") return JSON.parse(raw) as RefreshTokenPayload
+  return raw as RefreshTokenPayload
+}

package/src/adapters/kms/in-memory-backing.ts

@@ -0,0 +1,36 @@
+/**
+ * In-memory `KmsBackingStore`. Used by the KMS adapter conformance test and
+ * for single-instance dev. Production deployments pass a real backing store
+ * (Postgres, DynamoDB, S3-with-versioning, etc.) so KMS-wrapped key
+ * envelopes survive process restarts.
+ */
+import type {
+  KmsBackingStore,
+  WrappedEncryptionKey,
+  WrappedSigningKey,
+} from "./types"
+
+export function inMemoryKmsBackingStore(): KmsBackingStore {
+  const signing = new Map<string, WrappedSigningKey>()
+  const encryption = new Map<string, WrappedEncryptionKey>()
+  return {
+    async putSigningKey(row) {
+      signing.set(row.kid, row)
+    },
+    async getSigningKey(kid) {
+      return signing.get(kid)
+    },
+    async listSigningKeys() {
+      return Array.from(signing.values())
+    },
+    async putEncryptionKey(row) {
+      encryption.set(row.kid, row)
+    },
+    async getEncryptionKey(kid) {
+      return encryption.get(kid)
+    },
+    async listEncryptionKeys() {
+      return Array.from(encryption.values())
+    },
+  }
+}

package/src/adapters/kms/index.ts

@@ -0,0 +1,39 @@
+/**
+ * KMS-backed `KeyStore` adapter set.
+ *
+ * Envelope encryption: private JWK material is wrapped under an AWS KMS
+ * master key and stored in a pluggable backing store (`KmsBackingStore`).
+ * KMS Encrypt / Decrypt are the only KMS operations on the hot path; the
+ * framework still receives a real `CryptoKey` for JWT signing so no surgery
+ * in `domain/jwt.ts` is needed.
+ *
+ * @example
+ *   import { KMSClient } from "@aws-sdk/client-kms"
+ *   import {
+ *     fromKmsClient,
+ *     inMemoryKmsBackingStore,
+ *     KmsKeyStore,
+ *   } from "@_mustachio/openauth/adapters/kms"
+ *
+ *   const kms = fromKmsClient(
+ *     new KMSClient({ region: "us-east-1" }),
+ *     process.env.IDP_KMS_KEY_ARN!,
+ *   )
+ *   // For production, swap in a persistent KmsBackingStore (Postgres,
+ *   // DynamoDB, etc.). The in-memory store is appropriate for single-instance
+ *   // dev only.
+ *   const keyStore = new KmsKeyStore({ kms, backing: inMemoryKmsBackingStore() })
+ *
+ * Operators with strict no-plaintext-cache requirements can disable the
+ * unwrapped-key cache via `cacheUnwrappedKeys: false` — every read then
+ * round-trips to KMS.
+ */
+export { inMemoryKmsBackingStore } from "./in-memory-backing"
+export { KmsKeyStore, type KmsKeyStoreOptions } from "./key-store"
+export { fromKmsClient } from "./sdk"
+export type {
+  KmsBackingStore,
+  KmsClientLike,
+  WrappedEncryptionKey,
+  WrappedSigningKey,
+} from "./types"

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 {}
+  }
+}