@_mustachio/openauth 0.9.2 → 0.11.0

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

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"