@_mustachio/openauth 0.9.1 → 0.10.0

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

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

@@ -0,0 +1,229 @@
+/**
+ * DynamoDB `SessionStore`. Single-table — flows under `pk="flow"`, sessions
+ * under `pk="session"`. `consumeFlow` is `DeleteItem` with `ReturnValues=ALL_OLD`
+ * (atomic delete-on-read, single-winner under concurrent presentations).
+ *
+ * `updateFlowMethodState` reads then conditionally writes the merged payload
+ * with `attribute_exists(pk) AND expires_at > :now`. If a concurrent
+ * `consumeFlow` snuck in, the condition fails and we surface
+ * `unknown_state`.
+ */
+import { authError } from "../../types/error"
+import type { FlowRecord } from "../../types/flow"
+import type { SessionRecord, SessionStore } from "../../ports/session-store"
+import type { Result } from "../../types/result"
+import { err, ok } from "../../types/result"
+
+import type { DynamoExecutor } from "./client"
+
+export type DynamoSessionStoreOptions = {
+  exec: DynamoExecutor
+  clock?: () => number
+}
+
+export class DynamoSessionStore implements SessionStore {
+  #exec: DynamoExecutor
+  #clock: () => number
+
+  constructor(opts: DynamoSessionStoreOptions) {
+    this.#exec = opts.exec
+    this.#clock = opts.clock ?? (() => Date.now())
+  }
+
+  async saveFlow(
+    flowId: string,
+    payload: FlowRecord,
+    ttl: number,
+  ): Promise<Result<void>> {
+    if (ttl <= 0) {
+      return err(
+        authError.internalError(`saveFlow: ttl must be positive, got ${ttl}`),
+      )
+    }
+    const expiresAtMs = this.#clock() + ttl
+    try {
+      await this.#exec.put({
+        item: {
+          pk: "flow",
+          sk: flowId,
+          payload: JSON.stringify(payload),
+          expires_at: expiresAtMs,
+          ttl: Math.floor(expiresAtMs / 1000),
+        },
+      })
+    } catch (e) {
+      return err(authError.internalError("saveFlow: put failed", e))
+    }
+    return ok(undefined)
+  }
+
+  async updateFlowMethodState(
+    flowId: string,
+    methodState: unknown,
+  ): Promise<Result<void>> {
+    const now = this.#clock()
+    let row: Record<string, unknown> | undefined
+    try {
+      row = await this.#exec.get({
+        key: { pk: "flow", sk: flowId },
+        consistentRead: true,
+      })
+    } catch (e) {
+      return err(
+        authError.internalError("updateFlowMethodState: get failed", e),
+      )
+    }
+    if (!row) {
+      return err(authError.unknownState(`flow "${flowId}" unknown`))
+    }
+    if (now >= Number(row.expires_at)) {
+      return err(authError.unknownState(`flow "${flowId}" expired`))
+    }
+    const parsed = parseFlowPayload(row.payload)
+    const next = { ...parsed, methodState }
+    try {
+      // `condition: "exists"` translates to `attribute_exists(pk) AND
+      // attribute_exists(sk)`. If a concurrent `consumeFlow` deleted the row
+      // between our `get` and this `put`, the put fails instead of
+      // resurrecting the deleted row — which would otherwise let the original
+      // caller re-consume and bypass flow-reuse detection.
+      await this.#exec.put({
+        item: {
+          pk: "flow",
+          sk: flowId,
+          payload: JSON.stringify(next),
+          expires_at: row.expires_at,
+          ttl: row.ttl,
+        },
+        condition: "exists",
+      })
+    } catch (e) {
+      if (isConditionalCheckFailed(e)) {
+        return err(
+          authError.unknownState(
+            `flow "${flowId}" was consumed between read and update`,
+          ),
+        )
+      }
+      return err(
+        authError.internalError("updateFlowMethodState: put failed", e),
+      )
+    }
+    return ok(undefined)
+  }
+
+  async readFlow(flowId: string): Promise<Result<FlowRecord>> {
+    let row: Record<string, unknown> | undefined
+    try {
+      row = await this.#exec.get({
+        key: { pk: "flow", sk: flowId },
+        consistentRead: true,
+      })
+    } catch (e) {
+      return err(authError.internalError("readFlow: get failed", e))
+    }
+    if (!row) {
+      return err(authError.unknownState(`flow "${flowId}" unknown`))
+    }
+    if (this.#clock() >= Number(row.expires_at)) {
+      try {
+        await this.#exec.delete({ key: { pk: "flow", sk: flowId } })
+      } catch {}
+      return err(authError.unknownState(`flow "${flowId}" expired`))
+    }
+    return ok(parseFlowPayload(row.payload))
+  }
+
+  async consumeFlow(flowId: string): Promise<Result<FlowRecord>> {
+    let row: Record<string, unknown> | undefined
+    try {
+      row = await this.#exec.delete({ key: { pk: "flow", sk: flowId } })
+    } catch (e) {
+      return err(authError.internalError("consumeFlow: delete failed", e))
+    }
+    if (!row) {
+      return err(
+        authError.unknownState(`flow "${flowId}" unknown or already consumed`),
+      )
+    }
+    if (this.#clock() >= Number(row.expires_at)) {
+      return err(authError.unknownState(`flow "${flowId}" expired`))
+    }
+    return ok(parseFlowPayload(row.payload))
+  }
+
+  async createSession(
+    sessionId: string,
+    payload: SessionRecord,
+    ttl: number,
+  ): Promise<Result<void>> {
+    if (ttl <= 0) {
+      return err(
+        authError.internalError(
+          `createSession: ttl must be positive, got ${ttl}`,
+        ),
+      )
+    }
+    const expiresAtMs = this.#clock() + ttl
+    try {
+      await this.#exec.put({
+        item: {
+          pk: "session",
+          sk: sessionId,
+          payload: JSON.stringify(payload),
+          expires_at: expiresAtMs,
+          ttl: Math.floor(expiresAtMs / 1000),
+        },
+      })
+    } catch (e) {
+      return err(authError.internalError("createSession: put failed", e))
+    }
+    return ok(undefined)
+  }
+
+  async readSession(sessionId: string): Promise<Result<SessionRecord>> {
+    let row: Record<string, unknown> | undefined
+    try {
+      row = await this.#exec.get({
+        key: { pk: "session", sk: sessionId },
+        consistentRead: true,
+      })
+    } catch (e) {
+      return err(authError.internalError("readSession: get failed", e))
+    }
+    if (!row) {
+      return err(authError.invalidRequest(`session "${sessionId}" unknown`))
+    }
+    if (this.#clock() >= Number(row.expires_at)) {
+      try {
+        await this.#exec.delete({ key: { pk: "session", sk: sessionId } })
+      } catch {}
+      return err(authError.invalidRequest(`session "${sessionId}" expired`))
+    }
+    return ok(parseSessionPayload(row.payload))
+  }
+
+  async revokeSession(sessionId: string): Promise<Result<void>> {
+    try {
+      await this.#exec.delete({ key: { pk: "session", sk: sessionId } })
+    } catch (e) {
+      return err(authError.internalError("revokeSession: delete failed", e))
+    }
+    return ok(undefined)
+  }
+}
+
+function parseFlowPayload(raw: unknown): FlowRecord {
+  if (typeof raw === "string") return JSON.parse(raw) as FlowRecord
+  return raw as FlowRecord
+}
+
+function isConditionalCheckFailed(e: unknown): boolean {
+  if (typeof e !== "object" || e === null) return false
+  return (e as { name?: string }).name === "ConditionalCheckFailedException"
+}
+
+function parseSessionPayload(raw: unknown): SessionRecord {
+  if (typeof raw === "string") return JSON.parse(raw) as SessionRecord
+  return raw as SessionRecord
+}