@_mustachio/openauth 0.9.1 → 0.10.0

package/src/adapters/dynamo/client.ts

@@ -0,0 +1,118 @@
+/**
+ * `DynamoExecutor` — the operation surface the adapters depend on.
+ *
+ * Keeps the AWS SDK out of the adapter's import graph. Production users
+ * wire the executor via `fromDynamoDBClient(docClient, tableName)`; tests
+ * supply an in-memory implementation (`test/helpers/dynamo-shim.ts`).
+ *
+ * All operations target a single table (the adapter is single-table by
+ * design — pk + sk + optional GSIs). The executor knows the table name; the
+ * adapter only passes keys + data.
+ */
+
+export type DynamoKey = { pk: string; sk: string }
+
+/**
+ * Strong read by primary key. `consistentRead` MUST be honoured for every
+ * security-critical read (`getCode`, `getRefresh`, `getFlow`) — DynamoDB
+ * defaults to eventually consistent reads which violate the contracts in
+ * `ports/CONSISTENCY.md`.
+ */
+export type DynamoGetInput = {
+  key: DynamoKey
+  consistentRead: boolean
+}
+
+/**
+ * Insert (`condition: "not-exists"`) or unconditional put. The adapter uses:
+ *  - `"not-exists"` for code / refresh / flow inserts so a duplicate token
+ *    never silently overwrites.
+ *  - `"exists"` for read-modify-write paths (e.g. `updateFlowMethodState`)
+ *    so the put fails if a concurrent `consumeFlow` deleted the row between
+ *    the prior `get` and this `put`. The executor surfaces a
+ *    `ConditionalCheckFailedException` that callers translate into a typed
+ *    failure.
+ */
+export type DynamoPutInput = {
+  item: Record<string, unknown> & DynamoKey
+  condition?: "not-exists" | "exists"
+}
+
+/**
+ * Atomic delete-on-read — equivalent to `DeleteItem` with
+ * `ReturnValues=ALL_OLD`. Concurrent calls resolve to exactly one winner
+ * that gets the row back; losers get `undefined`.
+ */
+export type DynamoDeleteInput = {
+  key: DynamoKey
+}
+
+/**
+ * Conditional UPDATE used for the refresh-token rotation. Sets `consumed_at`
+ * iff it is currently absent. Returns the post-update item on success;
+ * resolves with `null` if the condition failed (`ConditionalCheckFailed`).
+ */
+export type DynamoUpdateConsumeRefreshInput = {
+  key: DynamoKey
+  now: number
+}
+
+/**
+ * Query items by partition key (and optionally a sort-key prefix). Strongly
+ * consistent for the refresh-revoke paths.
+ */
+export type DynamoQueryInput = {
+  pk: string
+  /** Sort-key prefix filter — emits `begins_with(sk, prefix)`. */
+  skBeginsWith?: string
+  consistentRead: boolean
+  /** Filter by an attribute (e.g. `family = :v` for `revokeFamily` via GSI). */
+  filter?: {
+    attribute: string
+    equals: string
+  }
+}
+
+export type DynamoQueryByGsiInput = {
+  /**
+   * GSI name configured on the table. Each entry corresponds to a GSI
+   * the bundled adapters need:
+   *   - `family-index`         (refresh-token family revocation)
+   *   - `subject-index`        (revokeBySubject)
+   *   - `passkey-user-index`   (PasskeyCredentialStore.findByUsername)
+   */
+  indexName: "family-index" | "subject-index" | "passkey-user-index"
+  /** Hash key value on the GSI. */
+  hashKey: string
+}
+
+/**
+ * Update a single item's attributes — equivalent to DynamoDB's
+ * `UpdateItem` with a `SET` expression over each provided attribute.
+ *
+ * Used by passkey-counter updates today; future Phase 8 features
+ * (DPoP jti replay, etc.) may reuse it.
+ */
+export type DynamoUpdateItemInput = {
+  key: DynamoKey
+  /** Attribute name → new value. Top-level only, no nested updates. */
+  set: Record<string, unknown>
+}
+
+export type DynamoExecutor = {
+  get(input: DynamoGetInput): Promise<Record<string, unknown> | undefined>
+  put(input: DynamoPutInput): Promise<void>
+  /** Returns the deleted item if one was deleted; `undefined` otherwise. */
+  delete(input: DynamoDeleteInput): Promise<Record<string, unknown> | undefined>
+  /**
+   * Atomic refresh-token claim. Returns the post-update item on success;
+   * `null` if the condition failed (already-consumed race).
+   */
+  consumeRefresh(
+    input: DynamoUpdateConsumeRefreshInput,
+  ): Promise<Record<string, unknown> | null>
+  query(input: DynamoQueryInput): Promise<Record<string, unknown>[]>
+  queryByGsi(input: DynamoQueryByGsiInput): Promise<Record<string, unknown>[]>
+  /** Generic attribute update. No-op if the item does not exist. */
+  updateItem(input: DynamoUpdateItemInput): Promise<void>
+}

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

@@ -0,0 +1,72 @@
+/**
+ * DynamoDB `ConfigStore`. `pk="tenant"`, `sk=<tenantId>`. Read-eventual
+ * by default (config is read-heavy, write-rare); the invalidation hook
+ * fires on every `putTenantConfig` so in-process caches drop stale values
+ * immediately.
+ */
+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 { DynamoExecutor } from "./client"
+
+export type DynamoConfigStoreOptions = {
+  exec: DynamoExecutor
+}
+
+export class DynamoConfigStore implements ConfigStore {
+  #exec: DynamoExecutor
+  #listeners = new Set<(id: TenantId) => void>()
+
+  constructor(opts: DynamoConfigStoreOptions) {
+    this.#exec = opts.exec
+  }
+
+  async getTenantConfig(id: TenantId): Promise<Result<TenantConfig>> {
+    let row: Record<string, unknown> | undefined
+    try {
+      row = await this.#exec.get({
+        key: { pk: "tenant", sk: id },
+        consistentRead: false,
+      })
+    } catch (e) {
+      return err(authError.internalError("getTenantConfig: get failed", e))
+    }
+    if (!row) {
+      return err(authError.tenantNotFound(`tenant "${id}" not found`, id))
+    }
+    return ok(parseConfig(row.config))
+  }
+
+  async putTenantConfig(config: TenantConfig): Promise<Result<void>> {
+    try {
+      await this.#exec.put({
+        item: {
+          pk: "tenant",
+          sk: config.id,
+          config: JSON.stringify(config),
+          updated_at: Date.now(),
+        },
+      })
+    } catch (e) {
+      return err(authError.internalError("putTenantConfig: 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)
+  }
+}
+
+function parseConfig(raw: unknown): TenantConfig {
+  if (typeof raw === "string") return JSON.parse(raw) as TenantConfig
+  return raw as TenantConfig
+}

package/src/adapters/dynamo/index.ts

@@ -0,0 +1,81 @@
+/**
+ * AWS DynamoDB adapter set.
+ *
+ * Single-table design with `pk` / `sk` primary key plus three GSIs:
+ *
+ *   `family-index`         hash = `family`        (revokeFamily)
+ *   `subject-index`        hash = `subject_key`   (revokeBySubject) — value is `<tenantId>#<subjectId>`
+ *   `passkey-user-index`   hash = `user_key`      (PasskeyCredentialStore.findByUsername) — value is `<tenantId>#<userId>`
+ *
+ * The adapter satisfies every contract in `ports/CONSISTENCY.md` provided
+ * the underlying calls use `ConsistentRead=true` on the strong reads and
+ * `ConditionExpression` on the rotation `UpdateItem` — both are handled by
+ * `fromDynamoDBClient`.
+ *
+ * Wiring:
+ * @example
+ *   import { DynamoDBClient } from "@aws-sdk/client-dynamodb"
+ *   import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb"
+ *   import {
+ *     fromDynamoDBClient,
+ *     DynamoTokenStore,
+ *     DynamoSessionStore,
+ *     // ...
+ *   } from "@_mustachio/openauth/adapters/dynamo"
+ *
+ *   const docClient = DynamoDBDocumentClient.from(new DynamoDBClient({ region: "us-east-1" }))
+ *   const exec = fromDynamoDBClient(docClient, "openauth")
+ *   const keyStore = new DynamoKeyStore({ exec })
+ *   const tokenStore = new DynamoTokenStore({ exec, keyStore })
+ *
+ * Table creation is left to the operator (Terraform / CDK / `aws dynamodb
+ * create-table`). The schema you need:
+ *
+ *   Table: openauth (or any name you choose)
+ *     Hash key:  pk (S)
+ *     Range key: sk (S)
+ *     TTL attribute: `ttl` (epoch seconds)
+ *
+ *   GSI: family-index
+ *     Hash key: family (S)
+ *     Projection: ALL
+ *
+ *   GSI: subject-index
+ *     Hash key: subject_key (S)
+ *     Projection: ALL
+ *
+ *   GSI: passkey-user-index
+ *     Hash key: user_key (S)
+ *     Projection: ALL
+ */
+export { DynamoAuditLog, type DynamoAuditLogOptions } from "./audit-log"
+export {
+  DynamoConfigStore,
+  type DynamoConfigStoreOptions,
+} from "./config-store"
+export { DynamoKeyStore, type DynamoKeyStoreOptions } from "./key-store"
+export {
+  DynamoMethodStore,
+  type DynamoMethodStoreOptions,
+} from "./method-store"
+export {
+  DynamoSessionStore,
+  type DynamoSessionStoreOptions,
+} from "./session-store"
+export { DynamoTokenStore, type DynamoTokenStoreOptions } from "./token-store"
+export {
+  DynamoPasskeyCredentialStore,
+  type DynamoPasskeyCredentialStoreOptions,
+} from "./passkey-credential-store"
+export { fromDynamoDBClient } from "./sdk"
+export type {
+  DynamoDeleteInput,
+  DynamoExecutor,
+  DynamoGetInput,
+  DynamoKey,
+  DynamoPutInput,
+  DynamoQueryByGsiInput,
+  DynamoQueryInput,
+  DynamoUpdateConsumeRefreshInput,
+  DynamoUpdateItemInput,
+} from "./client"

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

@@ -0,0 +1,267 @@
+/**
+ * DynamoDB `KeyStore`. Single-table — signing keys under `pk="signing-key"`,
+ * encryption keys under `pk="encryption-key"`. Private JWKs are stored as
+ * JSON strings; encryption key material as base64url. Auto-generates an
+ * active key pair on first read.
+ *
+ * **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` attributes record
+ * which representation each item uses.
+ */
+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 { DynamoExecutor } from "./client"
+
+export type DynamoKeyStoreOptions = {
+  exec: DynamoExecutor
+  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 DynamoKeyStore implements KeyStore {
+  #exec: DynamoExecutor
+  #clock: () => number
+  #signingAlg: "ES256" | "EdDSA"
+  #wrapper: KeyWrapper | undefined
+  #privateKeyCache = new Map<string, unknown>()
+
+  constructor(opts: DynamoKeyStoreOptions) {
+    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 items = await this.#exec.query({
+      pk: "signing-key",
+      consistentRead: true,
+      filter: { attribute: "status", equals: "active" },
+    })
+    const row = items[0]
+    if (!row) {
+      return err(
+        authError.internalError(
+          "no active signing key (should be unreachable)",
+        ),
+      )
+    }
+    return ok(await this.#hydrateSigning(row))
+  }
+
+  async signingKeys(): Promise<Result<SigningKey[]>> {
+    await this.#ensureSigningKey()
+    const items = await this.#exec.query({
+      pk: "signing-key",
+      consistentRead: false,
+    })
+    const keys = await Promise.all(items.map((r) => this.#hydrateSigning(r)))
+    return ok(keys)
+  }
+
+  async currentEncryptionKey(): Promise<Result<EncryptionKey>> {
+    await this.#ensureEncryptionKey()
+    const items = await this.#exec.query({
+      pk: "encryption-key",
+      consistentRead: true,
+      filter: { attribute: "status", equals: "active" },
+    })
+    const row = items[0]
+    if (!row) {
+      return err(
+        authError.internalError(
+          "no active encryption key (should be unreachable)",
+        ),
+      )
+    }
+    return ok(await this.#hydrateEncryption(row))
+  }
+
+  async getEncryptionKey(kid: string): Promise<Result<EncryptionKey>> {
+    const row = await this.#exec.get({
+      key: { pk: "encryption-key", sk: kid },
+      consistentRead: true,
+    })
+    if (!row) {
+      return err(authError.internalError(`encryption key "${kid}" not found`))
+    }
+    return ok(await this.#hydrateEncryption(row))
+  }
+
+  async #ensureSigningKey(): Promise<void> {
+    const items = await this.#exec.query({
+      pk: "signing-key",
+      consistentRead: true,
+      filter: { attribute: "status", equals: "active" },
+    })
+    if (items.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 privateJwkStored = await this.#encodePrivateJwk(privateJwk)
+    try {
+      await this.#exec.put({
+        item: {
+          pk: "signing-key",
+          sk: kid,
+          alg: this.#signingAlg,
+          crv: publicJwk.crv ?? null,
+          public_jwk: JSON.stringify(publicJwk),
+          private_jwk: privateJwkStored,
+          private_jwk_wrapped: this.#wrapper !== undefined,
+          status: "active",
+          created_at: this.#clock(),
+        },
+        condition: "not-exists",
+      })
+    } catch {
+      // Lost a race against another instance — fine; their key now exists.
+    }
+  }
+
+  async #ensureEncryptionKey(): Promise<void> {
+    const items = await this.#exec.query({
+      pk: "encryption-key",
+      consistentRead: true,
+      filter: { attribute: "status", equals: "active" },
+    })
+    if (items.length > 0) return
+    const kid = randomId()
+    const raw = generateSymmetricKey()
+    // DynamoDB stores bytes as Buffer/Uint8Array; base64url-encoded string is
+    // portable, supports `aws-sdk-client-mock`, and is marshalled back the
+    // same way. Wrapped bytes are encoded the same way after KMS encrypt.
+    const stored = this.#wrapper
+      ? base64url.encode(await this.#wrapper.wrap(raw))
+      : base64url.encode(raw)
+    try {
+      await this.#exec.put({
+        item: {
+          pk: "encryption-key",
+          sk: kid,
+          alg: "A256GCM",
+          key_material: stored,
+          key_material_wrapped: this.#wrapper !== undefined,
+          status: "active",
+          created_at: this.#clock(),
+        },
+        condition: "not-exists",
+      })
+    } catch {}
+  }
+
+  async #hydrateSigning(row: Record<string, unknown>): Promise<SigningKey> {
+    const kid = String(row.sk)
+    let imported = this.#privateKeyCache.get(kid)
+    if (!imported) {
+      const privateJwk = await this.#decodePrivateJwk(
+        String(row.private_jwk),
+        row.private_jwk_wrapped === true,
+      )
+      imported = await importJWK(privateJwk, String(row.alg))
+      this.#privateKeyCache.set(kid, imported)
+    }
+    const publicJwk = JSON.parse(String(row.public_jwk)) as Record<
+      string,
+      unknown
+    >
+    return {
+      kid,
+      alg: String(row.alg),
+      ...(row.crv ? { crv: String(row.crv) } : {}),
+      publicJwk,
+      privateKeyRef: imported,
+      status: String(row.status) as SigningKey["status"],
+      createdAt: Number(row.created_at),
+      ...(row.rotated_at !== undefined && row.rotated_at !== null
+        ? { rotatedAt: Number(row.rotated_at) }
+        : {}),
+    }
+  }
+
+  async #hydrateEncryption(
+    row: Record<string, unknown>,
+  ): Promise<EncryptionKey> {
+    const stored = base64url.decode(String(row.key_material))
+    let keyRef = stored
+    if (row.key_material_wrapped === true) {
+      if (!this.#wrapper) {
+        throw new Error(
+          "DynamoKeyStore: encryption key item is wrapped but no `wrapper` was supplied — refusing to read",
+        )
+      }
+      keyRef = await this.#wrapper.unwrap(stored)
+    }
+    return {
+      kid: String(row.sk),
+      alg: String(row.alg),
+      keyRef,
+      status: String(row.status) as EncryptionKey["status"],
+      createdAt: Number(row.created_at),
+      ...(row.rotated_at !== undefined && row.rotated_at !== null
+        ? { rotatedAt: Number(row.rotated_at) }
+        : {}),
+    }
+  }
+
+  /**
+   * Encode a private JWK for the `private_jwk` attribute. With a wrapper,
+   * the JWK bytes are encrypted and stored as `{"ct": <base64url>}` —
+   * never as a recognizable JWK at rest. Without one, the JWK is JSON-
+   * stringified verbatim (legacy path).
+   */
+  async #encodePrivateJwk(jwk: JWK): Promise<string> {
+    if (!this.#wrapper) return JSON.stringify(jwk)
+    const ciphertext = await this.#wrapper.wrap(
+      utf8.encode(JSON.stringify(jwk)),
+    )
+    return JSON.stringify({ ct: base64url.encode(ciphertext) })
+  }
+
+  async #decodePrivateJwk(raw: string, wrapped: boolean): Promise<JWK> {
+    const parsed = JSON.parse(raw) as Record<string, unknown>
+    if (!wrapped) return parsed as unknown as JWK
+    if (!this.#wrapper) {
+      throw new Error(
+        "DynamoKeyStore: signing key item is wrapped but no `wrapper` was supplied — refusing to read",
+      )
+    }
+    const ct = typeof parsed.ct === "string" ? parsed.ct : ""
+    if (!ct) {
+      throw new Error("DynamoKeyStore: wrapped signing key item missing `ct`")
+    }
+    const plaintext = await this.#wrapper.unwrap(base64url.decode(ct))
+    return JSON.parse(utf8.decode(plaintext)) as JWK
+  }
+}

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

@@ -0,0 +1,105 @@
+/**
+ * DynamoDB `MethodStore`. `pk="tenant-methods:<tenantId>"`, `sk=<methodId>`.
+ * Co-locating methods per-tenant lets `listMethods` use a single Query.
+ */
+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 { DynamoExecutor } from "./client"
+
+const partitionKey = (tenantId: TenantId) => `tenant-methods:${tenantId}`
+
+export type DynamoMethodStoreOptions = {
+  exec: DynamoExecutor
+}
+
+export class DynamoMethodStore implements MethodStore {
+  #exec: DynamoExecutor
+
+  constructor(opts: DynamoMethodStoreOptions) {
+    this.#exec = opts.exec
+  }
+
+  async listMethods(tenantId: TenantId): Promise<Result<MethodConfig[]>> {
+    let items: Record<string, unknown>[]
+    try {
+      items = await this.#exec.query({
+        pk: partitionKey(tenantId),
+        consistentRead: false,
+      })
+    } catch (e) {
+      return err(authError.internalError("listMethods: query failed", e))
+    }
+    const methods = items
+      .map((r) => parseMethod(r.config))
+      .sort((a, b) => a.id.localeCompare(b.id))
+    return ok(methods)
+  }
+
+  async getMethodConfig(
+    tenantId: TenantId,
+    methodId: string,
+  ): Promise<Result<MethodConfig>> {
+    let row: Record<string, unknown> | undefined
+    try {
+      row = await this.#exec.get({
+        key: { pk: partitionKey(tenantId), sk: methodId },
+        consistentRead: false,
+      })
+    } catch (e) {
+      return err(authError.internalError("getMethodConfig: get failed", e))
+    }
+    if (!row) {
+      return err(
+        authError.methodNotFound(
+          `method "${methodId}" not found for tenant "${tenantId}"`,
+          { methodId },
+        ),
+      )
+    }
+    return ok(parseMethod(row.config))
+  }
+
+  async putMethodConfig(
+    tenantId: TenantId,
+    method: MethodConfig,
+  ): Promise<Result<void>> {
+    try {
+      await this.#exec.put({
+        item: {
+          pk: partitionKey(tenantId),
+          sk: method.id,
+          config: JSON.stringify(method),
+          updated_at: Date.now(),
+        },
+      })
+    } catch (e) {
+      return err(authError.internalError("putMethodConfig: put failed", e))
+    }
+    return ok(undefined)
+  }
+
+  async deleteMethodConfig(
+    tenantId: TenantId,
+    methodId: string,
+  ): Promise<Result<void>> {
+    try {
+      await this.#exec.delete({
+        key: { pk: partitionKey(tenantId), sk: methodId },
+      })
+    } catch (e) {
+      return err(
+        authError.internalError("deleteMethodConfig: delete failed", e),
+      )
+    }
+    return ok(undefined)
+  }
+}
+
+function parseMethod(raw: unknown): MethodConfig {
+  if (typeof raw === "string") return JSON.parse(raw) as MethodConfig
+  return raw as MethodConfig
+}