@_mustachio/openauth 0.9.2 → 0.11.0

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

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

@@ -0,0 +1,132 @@
+/**
+ * DynamoDB `PasskeyCredentialStore`.
+ *
+ * Single-table layout, one item per credential:
+ *
+ *   pk = "passkey-cred"
+ *   sk = "<tenantId>#<credentialId>"
+ *   user_key = "<tenantId>#<userId>"       // GSI hash for findByUsername
+ *   tenant_id, user_id, public_key, counter, transports, created_at
+ *
+ * Required GSI on the table (alongside `family-index` /
+ * `subject-index` from `DynamoTokenStore`):
+ *
+ *   passkey-user-index
+ *     Hash key: user_key (S)
+ *     Projection: ALL
+ *
+ * The reference adapter treats `userId` as the username lookup key —
+ * matching the bundled `passkeyMethod`. Hosts that need
+ * username ≠ userId implement `PasskeyCredentialStore` directly.
+ */
+import type {
+  PasskeyCredentialStore,
+  StoredCredential,
+} from "../../methods/passkey"
+
+import type { DynamoExecutor } from "./client"
+
+export type DynamoPasskeyCredentialStoreOptions = {
+  exec: DynamoExecutor
+  clock?: () => number
+}
+
+export class DynamoPasskeyCredentialStore implements PasskeyCredentialStore {
+  #exec: DynamoExecutor
+  #clock: () => number
+
+  constructor(opts: DynamoPasskeyCredentialStoreOptions) {
+    this.#exec = opts.exec
+    this.#clock = opts.clock ?? (() => Date.now())
+  }
+
+  async findByUsername(
+    username: string,
+    tenantId: string,
+  ): Promise<{ userId: string; credentials: StoredCredential[] } | null> {
+    let items: Record<string, unknown>[]
+    try {
+      items = await this.#exec.queryByGsi({
+        indexName: "passkey-user-index",
+        hashKey: userKey(tenantId, username),
+      })
+    } catch {
+      return null
+    }
+    if (items.length === 0) return null
+    return {
+      userId: username,
+      credentials: items.map(itemToCredential),
+    }
+  }
+
+  async findById(
+    credentialId: string,
+    tenantId: string,
+  ): Promise<StoredCredential | null> {
+    const item = await this.#exec.get({
+      key: { pk: "passkey-cred", sk: sortKey(tenantId, credentialId) },
+      consistentRead: true,
+    })
+    if (!item) return null
+    return itemToCredential(item)
+  }
+
+  async updateCounter(input: {
+    credentialId: string
+    counter: number
+    tenantId: string
+  }): Promise<void> {
+    await this.#exec.updateItem({
+      key: {
+        pk: "passkey-cred",
+        sk: sortKey(input.tenantId, input.credentialId),
+      },
+      set: { counter: input.counter },
+    })
+  }
+
+  async create(input: {
+    userId: string
+    credential: StoredCredential
+    tenantId: string
+  }): Promise<void> {
+    const item: Record<string, unknown> = {
+      pk: "passkey-cred",
+      sk: sortKey(input.tenantId, input.credential.credentialId),
+      tenant_id: input.tenantId,
+      credential_id: input.credential.credentialId,
+      user_id: input.userId,
+      user_key: userKey(input.tenantId, input.userId),
+      public_key: input.credential.publicKey,
+      counter: input.credential.counter,
+      created_at: this.#clock(),
+    }
+    if (input.credential.transports) {
+      item.transports = input.credential.transports
+    }
+    await this.#exec.put({ item: item as never })
+  }
+}
+
+function sortKey(tenantId: string, credentialId: string): string {
+  return `${tenantId}#${credentialId}`
+}
+
+function userKey(tenantId: string, userId: string): string {
+  return `${tenantId}#${userId}`
+}
+
+function itemToCredential(item: Record<string, unknown>): StoredCredential {
+  const credential: StoredCredential = {
+    credentialId: String(item.credential_id ?? ""),
+    publicKey: String(item.public_key ?? ""),
+    counter: Number(item.counter ?? 0),
+    userId: String(item.user_id ?? ""),
+  }
+  const transports = item.transports
+  if (Array.isArray(transports)) {
+    credential.transports = transports.map(String)
+  }
+  return credential
+}

package/src/adapters/dynamo/sdk.ts

@@ -0,0 +1,189 @@
+/**
+ * `fromDynamoDBClient` — wires the `DynamoExecutor` interface to a real AWS
+ * SDK `DynamoDBDocumentClient`. Adapter consumers using AWS in production
+ * call this factory once, then pass the returned executor into every store
+ * adapter.
+ *
+ * The AWS SDK is imported via `@aws-sdk/lib-dynamodb` exclusively; the bare
+ * client is the caller's concern (they can configure region, creds, retries,
+ * etc.). This file is the **only** place in the package that imports the
+ * AWS SDK at runtime — keeping the adapter surface clean and the bundle
+ * lean for non-AWS consumers.
+ *
+ * @example
+ *   import { DynamoDBClient } from "@aws-sdk/client-dynamodb"
+ *   import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb"
+ *   const docClient = DynamoDBDocumentClient.from(new DynamoDBClient({}))
+ *   const exec = fromDynamoDBClient(docClient, "openauth")
+ *   const tokenStore = new DynamoTokenStore({ exec, keyStore })
+ */
+import type { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb"
+import {
+  DeleteCommand,
+  GetCommand,
+  PutCommand,
+  QueryCommand,
+  UpdateCommand,
+} from "@aws-sdk/lib-dynamodb"
+
+import type {
+  DynamoDeleteInput,
+  DynamoExecutor,
+  DynamoGetInput,
+  DynamoPutInput,
+  DynamoQueryByGsiInput,
+  DynamoQueryInput,
+  DynamoUpdateConsumeRefreshInput,
+  DynamoUpdateItemInput,
+} from "./client"
+
+export function fromDynamoDBClient(
+  client: DynamoDBDocumentClient,
+  tableName: string,
+): DynamoExecutor {
+  return {
+    async get(input: DynamoGetInput) {
+      const result = await client.send(
+        new GetCommand({
+          TableName: tableName,
+          Key: input.key,
+          ConsistentRead: input.consistentRead,
+        }),
+      )
+      return (result.Item as Record<string, unknown> | undefined) ?? undefined
+    },
+    async put(input: DynamoPutInput) {
+      const condition =
+        input.condition === "not-exists"
+          ? "attribute_not_exists(pk) AND attribute_not_exists(sk)"
+          : input.condition === "exists"
+            ? "attribute_exists(pk) AND attribute_exists(sk)"
+            : undefined
+      await client.send(
+        new PutCommand({
+          TableName: tableName,
+          Item: input.item,
+          ...(condition ? { ConditionExpression: condition } : {}),
+        }),
+      )
+    },
+    async delete(input: DynamoDeleteInput) {
+      const result = await client.send(
+        new DeleteCommand({
+          TableName: tableName,
+          Key: input.key,
+          ReturnValues: "ALL_OLD",
+        }),
+      )
+      return (
+        (result.Attributes as Record<string, unknown> | undefined) ?? undefined
+      )
+    },
+    async consumeRefresh(input: DynamoUpdateConsumeRefreshInput) {
+      try {
+        const result = await client.send(
+          new UpdateCommand({
+            TableName: tableName,
+            Key: input.key,
+            UpdateExpression: "SET consumed_at = :now",
+            ConditionExpression:
+              "attribute_exists(pk) AND attribute_not_exists(consumed_at) AND expires_at > :now",
+            ExpressionAttributeValues: { ":now": input.now },
+            ReturnValues: "ALL_NEW",
+          }),
+        )
+        return (
+          (result.Attributes as Record<string, unknown> | undefined) ?? null
+        )
+      } catch (e) {
+        if (isConditionalCheckFailed(e)) return null
+        throw e
+      }
+    },
+    async query(input: DynamoQueryInput) {
+      const exprAttrValues: Record<string, unknown> = { ":pk": input.pk }
+      let keyExpr = "pk = :pk"
+      if (input.skBeginsWith) {
+        keyExpr += " AND begins_with(sk, :skp)"
+        exprAttrValues[":skp"] = input.skBeginsWith
+      }
+      let filterExpr: string | undefined
+      if (input.filter) {
+        const k = ":fv"
+        filterExpr = `#attr = ${k}`
+        exprAttrValues[k] = input.filter.equals
+      }
+      const result = await client.send(
+        new QueryCommand({
+          TableName: tableName,
+          KeyConditionExpression: keyExpr,
+          ConsistentRead: input.consistentRead,
+          ExpressionAttributeValues: exprAttrValues,
+          ...(filterExpr
+            ? {
+                FilterExpression: filterExpr,
+                ExpressionAttributeNames: { "#attr": input.filter!.attribute },
+              }
+            : {}),
+        }),
+      )
+      return (result.Items as Record<string, unknown>[] | undefined) ?? []
+    },
+    async queryByGsi(input: DynamoQueryByGsiInput) {
+      const result = await client.send(
+        new QueryCommand({
+          TableName: tableName,
+          IndexName: input.indexName,
+          KeyConditionExpression: "#hk = :v",
+          ExpressionAttributeNames: {
+            "#hk":
+              input.indexName === "family-index"
+                ? "family"
+                : input.indexName === "subject-index"
+                  ? "subject_key"
+                  : "user_key",
+          },
+          ExpressionAttributeValues: { ":v": input.hashKey },
+        }),
+      )
+      return (result.Items as Record<string, unknown>[] | undefined) ?? []
+    },
+    async updateItem(input: DynamoUpdateItemInput) {
+      const names: Record<string, string> = {}
+      const values: Record<string, unknown> = {}
+      const sets: string[] = []
+      let i = 0
+      for (const [attr, value] of Object.entries(input.set)) {
+        const nameRef = `#a${i}`
+        const valueRef = `:v${i}`
+        names[nameRef] = attr
+        values[valueRef] = value
+        sets.push(`${nameRef} = ${valueRef}`)
+        i += 1
+      }
+      if (sets.length === 0) return
+      try {
+        await client.send(
+          new UpdateCommand({
+            TableName: tableName,
+            Key: input.key,
+            UpdateExpression: `SET ${sets.join(", ")}`,
+            ConditionExpression:
+              "attribute_exists(pk) AND attribute_exists(sk)",
+            ExpressionAttributeNames: names,
+            ExpressionAttributeValues: values,
+          }),
+        )
+      } catch (e) {
+        // Item-missing is a no-op per the executor contract.
+        if (!isConditionalCheckFailed(e)) throw e
+      }
+    },
+  }
+}
+
+function isConditionalCheckFailed(e: unknown): boolean {
+  if (typeof e !== "object" || e === null) return false
+  const name = (e as { name?: string }).name
+  return name === "ConditionalCheckFailedException"
+}