@nifrajs/core 2.14.1 → 3.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nifrajs/core",
-  "version": "2.14.1",
+  "version": "3.2.0",
   "description": "Bun-native, contract-first HTTP framework - the router, server, and route descriptor.",
   "keywords": [
     "bun",
@@ -37,6 +37,11 @@
       "types": "./dist/ws.d.ts",
       "default": "./dist/ws.js"
     },
+    "./edge-kit": {
+      "bun": "./src/edge-kit.ts",
+      "types": "./dist/edge-kit.d.ts",
+      "default": "./dist/edge-kit.js"
+    },
     "./wire": {
       "bun": "./src/wire.ts",
       "types": "./dist/wire.d.ts",
@@ -212,6 +217,11 @@
       "types": "./dist/router/router.d.ts",
       "default": "./dist/router/router.js"
     },
+    "./edge": {
+      "bun": "./src/server/edge.ts",
+      "types": "./dist/server/edge.d.ts",
+      "default": "./dist/server/edge.js"
+    },
     "./schema": {
       "bun": "./src/schema/standard.ts",
       "types": "./dist/schema/standard.d.ts",
@@ -237,6 +247,11 @@
       "types": "./dist/server/response-contract-lane.d.ts",
       "default": "./dist/server/response-contract-lane.js"
     },
+    "./response-observer": {
+      "bun": "./src/response-observer.ts",
+      "types": "./dist/response-observer.d.ts",
+      "default": "./dist/response-observer.js"
+    },
     "./tool-contract": {
       "bun": "./src/tool-contract.ts",
       "types": "./dist/tool-contract.d.ts",
@@ -251,6 +266,16 @@
       "bun": "./src/execution-policy.ts",
       "types": "./dist/execution-policy.d.ts",
       "default": "./dist/execution-policy.js"
+    },
+    "./single-copy": {
+      "bun": "./src/single-copy.ts",
+      "types": "./dist/single-copy.d.ts",
+      "default": "./dist/single-copy.js"
+    },
+    "./single-copy/register": {
+      "bun": "./src/single-copy-register.ts",
+      "types": "./dist/single-copy-register.d.ts",
+      "default": "./dist/single-copy-register.js"
     }
   },
   "files": [
@@ -264,8 +289,8 @@
     "./dist/server/sse.js",
     "./src/node-direct.ts",
     "./dist/node-direct.js",
-    "./src/mcp-runtime.ts",
-    "./dist/mcp-runtime.js"
+    "./src/single-copy-register.ts",
+    "./dist/single-copy-register.js"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json && bun run ../../scripts/fix-dts.ts dist"

package/src/assurance.ts

@@ -36,6 +36,11 @@ import type { NifraManifestSigner } from "./manifest.ts"
 import { type ReflectedRoute, reflectRoutes } from "./reflection.ts"
 import type { Method } from "./router/router.ts"
 
+export {
+  type SecurityBaselineLevel,
+  type SecurityBaselineOptions,
+  securityBaseline,
+} from "./security/baseline.ts"
 export type { AssuranceAttachment, AssuranceDeclaration, AssuranceEvidence, AssuranceScope }
 export { withRouteAssurance }
 
@@ -135,6 +140,20 @@ export interface AssuranceRouteSelector {
   readonly zone?: CapabilityZone
   /** Match routes whose response classification is at least this sensitivity. */
   readonly classificationAtLeast?: DataClassification
+  /**
+   * Match routes by whether they declare a request-body schema. `true` selects routes that parse a
+   * body (the buffered-read surface F-001 is about); `false` selects bodyless routes. Reflection
+   * already carries `schema.body`, so this reads what the route declared, not where it lives.
+   */
+  readonly hasBody?: boolean
+  /**
+   * Match routes by their effective transport body policy. `"unlimited"` is the explicit
+   * streaming/upload exemption; `"bounded"` is any finite cap (an explicit number or the inherited
+   * server default); `"unset"` is a route that declared no `bodyLimit` at all. Lets a baseline say
+   * "a body-schema route may never be unlimited" as a first-class, movable invariant rather than a
+   * path list. A route with no schema reports `"unset"` unless it names a limit.
+   */
+  readonly bodyLimit?: "bounded" | "unlimited" | "unset"
 }
 
 /** Extra inputs an assurance evaluation needs beyond the routes themselves. */
@@ -337,6 +356,8 @@ export function defineAssurancePolicy(policy: AssurancePolicy): AssurancePolicy
           "capabilities",
           ...CLASS_SELECTOR_KEYS,
           "classificationAtLeast",
+          "hasBody",
+          "bodyLimit",
         ].includes(key),
     )
     if (unknown.length > 0) {
@@ -351,6 +372,21 @@ export function defineAssurancePolicy(policy: AssurancePolicy): AssurancePolicy
         `route assurance: rule ${JSON.stringify(name)} tools selector must be boolean`,
       )
     }
+    if (rule.match.hasBody !== undefined && typeof rule.match.hasBody !== "boolean") {
+      throw new Error(
+        `route assurance: rule ${JSON.stringify(name)} hasBody selector must be boolean`,
+      )
+    }
+    if (
+      rule.match.bodyLimit !== undefined &&
+      rule.match.bodyLimit !== "bounded" &&
+      rule.match.bodyLimit !== "unlimited" &&
+      rule.match.bodyLimit !== "unset"
+    ) {
+      throw new Error(
+        `route assurance: rule ${JSON.stringify(name)} bodyLimit selector must be "bounded", "unlimited", or "unset"`,
+      )
+    }
     const methods = rule.match.methods?.map((method) => method.toUpperCase())
     for (const method of methods ?? []) {
       if (!validMethod(method)) {
@@ -431,6 +467,8 @@ export function defineAssurancePolicy(policy: AssurancePolicy): AssurancePolicy
         ...(rule.match.classificationAtLeast !== undefined
           ? { classificationAtLeast: rule.match.classificationAtLeast }
           : {}),
+        ...(rule.match.hasBody !== undefined ? { hasBody: rule.match.hasBody } : {}),
+        ...(rule.match.bodyLimit !== undefined ? { bodyLimit: rule.match.bodyLimit } : {}),
       }),
       require: required,
       forbid: forbidden,
@@ -558,16 +596,35 @@ export function defineAssuranceConfig(config: AssuranceConfig): AssuranceConfig
  * reflection alone. A caller that omits it while the selector needs it gets no match, so callers that
  * accept user policy must reject that combination up front - `defineAssuranceConfig` does.
  */
+/**
+ * The effective transport body policy a `bodyLimit` selector matches on. A route that named no limit
+ * reports `"unset"` (it inherits the server default, which a policy that cares about explicit caps
+ * should treat distinctly); a finite number is `"bounded"`; the streaming/upload exemption is
+ * `"unlimited"`. Kept total so a future `bodyLimit` shape cannot fall through to a silent match.
+ */
+function effectiveBodyLimit(schema: ReflectedRoute["schema"]): "bounded" | "unlimited" | "unset" {
+  const limit = schema?.bodyLimit
+  if (limit === "unlimited") return "unlimited"
+  if (typeof limit === "number") return "bounded"
+  return "unset"
+}
+
 export function matchesAssuranceSelector(
-  route: Pick<ReflectedRoute, "method" | "path" | "tool" | "capabilities" | "classification">,
+  route: Pick<
+    ReflectedRoute,
+    "method" | "path" | "tool" | "capabilities" | "classification" | "schema"
+  >,
   selector: AssuranceRouteSelector,
   definitions?: ReadonlyMap<string, CapabilityDefinition>,
 ): boolean {
   const { methods, paths, tools, capabilities, access, zone, classificationAtLeast } = selector
+  const { hasBody, bodyLimit } = selector
   if (methods !== undefined && !methods.includes(route.method as Method)) return false
   if (paths !== undefined && !paths.some((pattern) => routeGlob(pattern).test(route.path)))
     return false
   if (tools !== undefined && (route.tool !== undefined) !== tools) return false
+  if (hasBody !== undefined && (route.schema?.body !== undefined) !== hasBody) return false
+  if (bodyLimit !== undefined && effectiveBodyLimit(route.schema) !== bodyLimit) return false
   if (
     classificationAtLeast !== undefined &&
     (route.classification === undefined ||

package/src/durable-adapters.ts

@@ -480,12 +480,15 @@ export class PostgresDurableRecordBackend implements DurableRecordBackend {
   }
 
   async migrate(): Promise<void> {
+    // nifra-expect sql-dynamic: interpolates a validated sqlIdentifier table name, which SQL cannot bind as a parameter
     await this.client.query(
       sqlIdentifiers`CREATE TABLE IF NOT EXISTS ${this.recordsTable} (kind TEXT NOT NULL, id TEXT NOT NULL, state TEXT NOT NULL, updated_at BIGINT NOT NULL, version BIGINT NOT NULL, payload JSONB NOT NULL, PRIMARY KEY (kind, id))`,
     )
+    // nifra-expect sql-dynamic: interpolates a validated sqlIdentifier table name, which SQL cannot bind as a parameter
     await this.client.query(
       sqlIdentifiers`CREATE INDEX IF NOT EXISTS ${this.recordsTable}_reconcile ON ${this.recordsTable} (kind, state, updated_at, id)`,
     )
+    // nifra-expect sql-dynamic: interpolates a validated sqlIdentifier table name, which SQL cannot bind as a parameter
     await this.client.query(
       sqlIdentifiers`CREATE TABLE IF NOT EXISTS ${this.leasesTable} (name TEXT PRIMARY KEY, owner TEXT, token TEXT, expires_at BIGINT NOT NULL DEFAULT 0, cursor TEXT)`,
     )
@@ -496,6 +499,7 @@ export class PostgresDurableRecordBackend implements DurableRecordBackend {
     id: string,
     record: { readonly version: number; readonly state?: string; readonly updatedAt?: number },
   ): Promise<boolean> {
+    // nifra-expect sql-dynamic: interpolates a validated sqlIdentifier table name, which SQL cannot bind as a parameter
     const result = await this.client.query(
       sqlIdentifiers`INSERT INTO ${this.recordsTable} (kind,id,state,updated_at,version,payload) VALUES ($1,$2,$3,$4,$5,$6::jsonb) ON CONFLICT DO NOTHING RETURNING id`,
       [
@@ -513,6 +517,7 @@ export class PostgresDurableRecordBackend implements DurableRecordBackend {
     kind: DurableRecordKind,
     id: string,
   ): Promise<T | undefined> {
+    // nifra-expect sql-dynamic: interpolates a validated sqlIdentifier table name, which SQL cannot bind as a parameter
     const result = await this.client.query(
       sqlIdentifiers`SELECT payload FROM ${this.recordsTable} WHERE kind=$1 AND id=$2`,
       [kind, id],
@@ -526,6 +531,7 @@ export class PostgresDurableRecordBackend implements DurableRecordBackend {
     record: { readonly version: number; readonly state?: string; readonly updatedAt?: number },
   ): Promise<boolean> {
     if (record.version !== expectedVersion + 1) return false
+    // nifra-expect sql-dynamic: interpolates a validated sqlIdentifier table name, which SQL cannot bind as a parameter
     const result = await this.client.query(
       sqlIdentifiers`UPDATE ${this.recordsTable} SET state=$4,updated_at=$5,version=$6,payload=$7::jsonb WHERE kind=$1 AND id=$2 AND version=$3 RETURNING id`,
       [
@@ -544,6 +550,7 @@ export class PostgresDurableRecordBackend implements DurableRecordBackend {
     kind: DurableRecordKind,
     input: ReconciliationScanOptions<string>,
   ): Promise<ReconciliationScanPage<T>> {
+    // nifra-expect sql-dynamic: interpolates a validated sqlIdentifier table name, which SQL cannot bind as a parameter
     const result = await this.client.query(
       sqlIdentifiers`SELECT id,payload FROM ${this.recordsTable} WHERE kind=$1 AND state = ANY($2::text[]) AND ($3::bigint IS NULL OR updated_at <= $3) AND ($4::text IS NULL OR id > $4) ORDER BY id LIMIT $5`,
       [kind, input.states, input.updatedBefore ?? null, input.cursor ?? null, input.limit + 1],
@@ -560,6 +567,7 @@ export class PostgresDurableRecordBackend implements DurableRecordBackend {
   ): Promise<ReconciliationLease | undefined> {
     const token = crypto.randomUUID()
     const expiresAt = input.now + input.leaseMs
+    // nifra-expect sql-dynamic: interpolates a validated sqlIdentifier table name, which SQL cannot bind as a parameter
     const result = await this.client.query(
       sqlIdentifiers`INSERT INTO ${this.leasesTable} (name,owner,token,expires_at) VALUES ($1,$2,$3,$4) ON CONFLICT (name) DO UPDATE SET owner=EXCLUDED.owner,token=EXCLUDED.token,expires_at=EXCLUDED.expires_at WHERE ${this.leasesTable}.expires_at <= $5 RETURNING name,owner,token,expires_at,cursor`,
       [input.name, input.owner, token, expiresAt, input.now],
@@ -575,6 +583,7 @@ export class PostgresDurableRecordBackend implements DurableRecordBackend {
     })
   }
   async renewLease(input: Parameters<DurableRecordBackend["renewLease"]>[0]): Promise<boolean> {
+    // nifra-expect sql-dynamic: interpolates a validated sqlIdentifier table name, which SQL cannot bind as a parameter
     const result = await this.client.query(
       sqlIdentifiers`UPDATE ${this.leasesTable} SET expires_at=$4 WHERE name=$1 AND owner=$2 AND token=$3 AND expires_at>$5 RETURNING name`,
       [input.name, input.owner, input.token, input.now + input.leaseMs, input.now],
@@ -584,6 +593,7 @@ export class PostgresDurableRecordBackend implements DurableRecordBackend {
   async checkpointLease(
     input: Parameters<DurableRecordBackend["checkpointLease"]>[0],
   ): Promise<boolean> {
+    // nifra-expect sql-dynamic: interpolates a validated sqlIdentifier table name, which SQL cannot bind as a parameter
     const result = await this.client.query(
       sqlIdentifiers`UPDATE ${this.leasesTable} SET cursor=$4 WHERE name=$1 AND owner=$2 AND token=$3 RETURNING name`,
       [input.name, input.owner, input.token, input.cursor ?? null],
@@ -591,6 +601,7 @@ export class PostgresDurableRecordBackend implements DurableRecordBackend {
     return result.rows.length === 1
   }
   async releaseLease(input: Parameters<DurableRecordBackend["releaseLease"]>[0]): Promise<boolean> {
+    // nifra-expect sql-dynamic: interpolates a validated sqlIdentifier table name, which SQL cannot bind as a parameter
     const result = await this.client.query(
       sqlIdentifiers`UPDATE ${this.leasesTable} SET owner=NULL,token=NULL,expires_at=0 WHERE name=$1 AND owner=$2 AND token=$3 RETURNING name`,
       [input.name, input.owner, input.token],
@@ -646,6 +657,7 @@ export class SQLiteDurableRecordBackend implements DurableRecordBackend {
     this.leasesTable = `${prefix}_leases`
   }
   migrate(): void {
+    // nifra-expect sql-dynamic: interpolates a validated sqlIdentifier table name, which SQL cannot bind as a parameter
     this.client.exec(
       sqlIdentifiers`CREATE TABLE IF NOT EXISTS ${this.recordsTable} (kind TEXT NOT NULL, id TEXT NOT NULL, state TEXT NOT NULL, updated_at INTEGER NOT NULL, version INTEGER NOT NULL, payload TEXT NOT NULL, PRIMARY KEY (kind,id));CREATE INDEX IF NOT EXISTS ${this.recordsTable}_reconcile ON ${this.recordsTable} (kind,state,updated_at,id);CREATE TABLE IF NOT EXISTS ${this.leasesTable} (name TEXT PRIMARY KEY, owner TEXT, token TEXT, expires_at INTEGER NOT NULL DEFAULT 0, cursor TEXT);`,
     )
@@ -655,6 +667,7 @@ export class SQLiteDurableRecordBackend implements DurableRecordBackend {
     id: string,
     record: { readonly version: number; readonly state?: string; readonly updatedAt?: number },
   ): Promise<boolean> {
+    // nifra-expect sql-dynamic: interpolates a validated sqlIdentifier table name, which SQL cannot bind as a parameter
     const result = this.client
       .query(
         sqlIdentifiers`INSERT OR IGNORE INTO ${this.recordsTable} (kind,id,state,updated_at,version,payload) VALUES (?,?,?,?,?,?)`,
@@ -673,6 +686,7 @@ export class SQLiteDurableRecordBackend implements DurableRecordBackend {
     kind: DurableRecordKind,
     id: string,
   ): Promise<T | undefined> {
+    // nifra-expect sql-dynamic: interpolates a validated sqlIdentifier table name, which SQL cannot bind as a parameter
     const row = this.client
       .query(sqlIdentifiers`SELECT payload FROM ${this.recordsTable} WHERE kind=? AND id=?`)
       .get(kind, id)
@@ -685,6 +699,7 @@ export class SQLiteDurableRecordBackend implements DurableRecordBackend {
     record: { readonly version: number; readonly state?: string; readonly updatedAt?: number },
   ): Promise<boolean> {
     if (record.version !== expectedVersion + 1) return false
+    // nifra-expect sql-dynamic: interpolates a validated sqlIdentifier table name, which SQL cannot bind as a parameter
     const result = this.client
       .query(
         sqlIdentifiers`UPDATE ${this.recordsTable} SET state=?,updated_at=?,version=?,payload=? WHERE kind=? AND id=? AND version=?`,
@@ -706,6 +721,7 @@ export class SQLiteDurableRecordBackend implements DurableRecordBackend {
   ): Promise<ReconciliationScanPage<T>> {
     if (input.states.length === 0) return { records: [] }
     const placeholders = sqlPlaceholders(input.states.length)
+    // nifra-expect sql-dynamic: interpolates a validated sqlIdentifier table name (and static ?-placeholders), which SQL cannot bind as a parameter
     const rows = this.client
       .query(
         sqlIdentifiers`SELECT id,payload FROM ${this.recordsTable} WHERE kind=? AND state IN (${placeholders}) AND (? IS NULL OR updated_at <= ?) AND (? IS NULL OR id > ?) ORDER BY id LIMIT ?`,
@@ -732,6 +748,7 @@ export class SQLiteDurableRecordBackend implements DurableRecordBackend {
   ): Promise<ReconciliationLease | undefined> {
     const token = crypto.randomUUID()
     const expiresAt = input.now + input.leaseMs
+    // nifra-expect sql-dynamic: interpolates a validated sqlIdentifier table name, which SQL cannot bind as a parameter
     const row = this.client
       .query(
         sqlIdentifiers`INSERT INTO ${this.leasesTable} (name,owner,token,expires_at) VALUES (?,?,?,?) ON CONFLICT(name) DO UPDATE SET owner=excluded.owner,token=excluded.token,expires_at=excluded.expires_at WHERE ${this.leasesTable}.expires_at <= ? RETURNING name,owner,token,expires_at,cursor`,
@@ -748,6 +765,7 @@ export class SQLiteDurableRecordBackend implements DurableRecordBackend {
   }
   async renewLease(input: Parameters<DurableRecordBackend["renewLease"]>[0]): Promise<boolean> {
     return (
+      // nifra-expect sql-dynamic: interpolates a validated sqlIdentifier table name, which SQL cannot bind as a parameter
       this.client
         .query(
           sqlIdentifiers`UPDATE ${this.leasesTable} SET expires_at=? WHERE name=? AND owner=? AND token=? AND expires_at>?`,
@@ -760,6 +778,7 @@ export class SQLiteDurableRecordBackend implements DurableRecordBackend {
     input: Parameters<DurableRecordBackend["checkpointLease"]>[0],
   ): Promise<boolean> {
     return (
+      // nifra-expect sql-dynamic: interpolates a validated sqlIdentifier table name, which SQL cannot bind as a parameter
       this.client
         .query(
           sqlIdentifiers`UPDATE ${this.leasesTable} SET cursor=? WHERE name=? AND owner=? AND token=?`,
@@ -769,6 +788,7 @@ export class SQLiteDurableRecordBackend implements DurableRecordBackend {
   }
   async releaseLease(input: Parameters<DurableRecordBackend["releaseLease"]>[0]): Promise<boolean> {
     return (
+      // nifra-expect sql-dynamic: interpolates a validated sqlIdentifier table name, which SQL cannot bind as a parameter
       this.client
         .query(
           sqlIdentifiers`UPDATE ${this.leasesTable} SET owner=NULL,token=NULL,expires_at=0 WHERE name=? AND owner=? AND token=?`,

package/src/durable-approval.ts

@@ -0,0 +1,281 @@
+import type { CapabilityApprovalGate } from "./internal/capability-runtime.ts"
+import { durableApprovalProtocol } from "./internal/durable-approval-protocol.ts"
+import {
+  addDuration,
+  assertPositiveMs,
+  assertToken,
+  bytesToBase64Url,
+  cloneValue,
+  encoder,
+  readClock,
+  sha256,
+} from "./internal/durable-shared.ts"
+import type {
+  ApprovalConsumeResult,
+  ApprovalRecord,
+  ApprovalStore,
+} from "./internal/durable-types.ts"
+
+const decoder = new TextDecoder()
+
+function base64UrlToBytes(value: string): Uint8Array {
+  if (!/^[A-Za-z0-9_-]+$/u.test(value)) throw new ApprovalTokenInvalidError()
+  const padded = value
+    .replaceAll("-", "+")
+    .replaceAll("_", "/")
+    .padEnd(Math.ceil(value.length / 4) * 4, "=")
+  let binary: string
+  try {
+    binary = atob(padded)
+  } catch {
+    throw new ApprovalTokenInvalidError()
+  }
+  return Uint8Array.from(binary, (character) => character.charCodeAt(0))
+}
+// Durable human approval with signed, single-use resume tokens
+
+export class ApprovalRequiredError extends Error {
+  readonly approvalId: string
+  readonly effectId: string
+  readonly resumeToken!: string
+  readonly expiresAt: number
+
+  constructor(approvalId: string, effectId: string, resumeToken: string, expiresAt: number) {
+    super("capability approval is required")
+    this.approvalId = approvalId
+    this.effectId = effectId
+    this.expiresAt = expiresAt
+    Object.defineProperty(this, "resumeToken", {
+      value: resumeToken,
+      enumerable: false,
+      configurable: false,
+      writable: false,
+    })
+    this.name = "ApprovalRequiredError"
+  }
+}
+
+export class ApprovalTokenInvalidError extends Error {
+  constructor() {
+    super("approval resume token is invalid")
+    this.name = "ApprovalTokenInvalidError"
+  }
+}
+export class ApprovalTokenExpiredError extends Error {
+  constructor() {
+    super("approval resume token has expired")
+    this.name = "ApprovalTokenExpiredError"
+  }
+}
+export class ApprovalTokenReplayError extends Error {
+  constructor() {
+    super("approval resume token has already been consumed")
+    this.name = "ApprovalTokenReplayError"
+  }
+}
+export class ApprovalBindingError extends Error {
+  constructor() {
+    super("approval resume token is bound to another tenant or principal")
+    this.name = "ApprovalBindingError"
+  }
+}
+export class ApprovalPendingError extends Error {
+  constructor() {
+    super("capability approval is still pending")
+    this.name = "ApprovalPendingError"
+  }
+}
+export class ApprovalDeniedError extends Error {
+  constructor() {
+    super("capability approval was denied")
+    this.name = "ApprovalDeniedError"
+  }
+}
+
+interface ResumeClaims {
+  readonly v: 1
+  readonly id: string
+  readonly nonce: string
+  readonly exp: number
+}
+
+export interface ApprovalCoordinator extends CapabilityApprovalGate {
+  decide(input: {
+    readonly approvalId: string
+    readonly tenantId: string
+    readonly decision: "approved" | "denied"
+    readonly decidedBy: string
+  }): Promise<void>
+  get(approvalId: string): Promise<ApprovalRecord | undefined>
+}
+
+export interface ApprovalCoordinatorOptions {
+  readonly store: ApprovalStore
+  /** At least 32 random bytes, kept separately from the approval store. */
+  readonly secret: Uint8Array
+  readonly ttlMs?: number
+  readonly now?: () => number
+  /** Tests/local development only. Production approval records require a durable store. */
+  readonly allowMemoryStore?: boolean
+}
+
+export function createApprovalCoordinator(
+  options: ApprovalCoordinatorOptions,
+): ApprovalCoordinator {
+  if (options.store.durability !== "durable" && options.allowMemoryStore !== true) {
+    throw new TypeError('approval coordinator requires store.durability === "durable"')
+  }
+  if (!(options.secret instanceof Uint8Array) || options.secret.byteLength < 32) {
+    throw new TypeError("approval secret must contain at least 32 random bytes")
+  }
+  const secret = new Uint8Array(options.secret)
+  const ttlMs = options.ttlMs ?? 15 * 60_000
+  assertPositiveMs(ttlMs, "approval ttlMs")
+  const clock = options.now ?? Date.now
+  const now = (): number => readClock(clock, "approval clock")
+  const key = crypto.subtle.importKey("raw", secret, { name: "HMAC", hash: "SHA-256" }, false, [
+    "sign",
+    "verify",
+  ])
+
+  const sign = async (claims: ResumeClaims): Promise<string> => {
+    const payload = bytesToBase64Url(encoder.encode(JSON.stringify(claims)))
+    const signature = new Uint8Array(
+      await crypto.subtle.sign("HMAC", await key, encoder.encode(payload)),
+    )
+    return `v1.${payload}.${bytesToBase64Url(signature)}`
+  }
+  const verify = async (token: string): Promise<ResumeClaims> => {
+    if (typeof token !== "string" || token.length > 2048) throw new ApprovalTokenInvalidError()
+    const parts = token.split(".")
+    if (parts.length !== 3 || parts[0] !== "v1") throw new ApprovalTokenInvalidError()
+    const payload = parts[1] as string
+    const valid = await crypto.subtle.verify(
+      "HMAC",
+      await key,
+      base64UrlToBytes(parts[2] as string).buffer as ArrayBuffer,
+      encoder.encode(payload),
+    )
+    if (!valid) throw new ApprovalTokenInvalidError()
+    let claims: unknown
+    try {
+      claims = JSON.parse(decoder.decode(base64UrlToBytes(payload)))
+    } catch {
+      throw new ApprovalTokenInvalidError()
+    }
+    if (typeof claims !== "object" || claims === null) throw new ApprovalTokenInvalidError()
+    const candidate = claims as Partial<ResumeClaims>
+    if (
+      candidate.v !== 1 ||
+      typeof candidate.id !== "string" ||
+      typeof candidate.nonce !== "string" ||
+      !Number.isSafeInteger(candidate.exp)
+    ) {
+      throw new ApprovalTokenInvalidError()
+    }
+    assertToken(candidate.id, "approval id", 128)
+    assertToken(candidate.nonce, "approval nonce", 128)
+    if ((candidate.exp as number) <= now()) throw new ApprovalTokenExpiredError()
+    return candidate as ResumeClaims
+  }
+
+  const coordinator: ApprovalCoordinator = {
+    async authorize(input: Parameters<CapabilityApprovalGate["authorize"]>[0]) {
+      if (input.signal.aborted) throw input.signal.reason
+      assertToken(input.identity.tenantId, "approval tenantId")
+      assertToken(input.identity.principalId, "approval principalId")
+      if (input.resumeToken === undefined) {
+        const approvalId = crypto.randomUUID()
+        const nonce = bytesToBase64Url(crypto.getRandomValues(new Uint8Array(18)))
+        const issuedAt = now()
+        const expiresAt = addDuration(issuedAt, ttlMs, "approval expiry")
+        const resumeToken = await sign({ v: 1, id: approvalId, nonce, exp: expiresAt })
+        const accepted = await options.store.create(
+          Object.freeze({
+            approvalId,
+            effectId: input.effectId,
+            capability: input.capability,
+            ...(input.target === undefined ? {} : { target: input.target }),
+            ...(input.digest === undefined ? {} : { digest: input.digest }),
+            tenantId: input.identity.tenantId,
+            principalId: input.identity.principalId,
+            tokenHash: await sha256(resumeToken),
+            state: "pending" as const,
+            createdAt: issuedAt,
+            expiresAt,
+            updatedAt: issuedAt,
+            version: 1,
+          }),
+        )
+        if (!accepted) throw new Error("approval store rejected a unique approval id")
+        throw new ApprovalRequiredError(approvalId, input.effectId, resumeToken, expiresAt)
+      }
+      const claims = await verify(input.resumeToken)
+      const consumed = await options.store.consume({
+        approvalId: claims.id,
+        tenantId: input.identity.tenantId,
+        principalId: input.identity.principalId,
+        capability: input.capability,
+        ...(input.target === undefined ? {} : { target: input.target }),
+        ...(input.digest === undefined ? {} : { digest: input.digest }),
+        tokenHash: await sha256(input.resumeToken),
+        now: now(),
+      })
+      if (consumed.state === "consumed") return
+      if (consumed.state === "replay") throw new ApprovalTokenReplayError()
+      if (consumed.state === "binding") throw new ApprovalBindingError()
+      if (consumed.state === "expired") throw new ApprovalTokenExpiredError()
+      if (consumed.state === "pending") throw new ApprovalPendingError()
+      if (consumed.state === "denied") throw new ApprovalDeniedError()
+      throw new ApprovalTokenInvalidError()
+    },
+    async decide(input: Parameters<ApprovalCoordinator["decide"]>[0]) {
+      assertToken(input.approvalId, "approval id", 128)
+      assertToken(input.tenantId, "approval tenantId")
+      assertToken(input.decidedBy, "approval decidedBy")
+      const accepted = await options.store.decide({ ...input, now: now() })
+      if (!accepted) throw new Error("approval decision rejected")
+    },
+    async get(approvalId: string) {
+      assertToken(approvalId, "approval id", 128)
+      return await options.store.get(approvalId)
+    },
+  }
+  return Object.freeze(coordinator)
+}
+
+export class MemoryApprovalStore implements ApprovalStore {
+  readonly durability = "memory" as const
+  private readonly records = new Map<string, ApprovalRecord>()
+
+  create(record: ApprovalRecord): boolean {
+    if (this.records.has(record.approvalId)) return false
+    this.records.set(record.approvalId, Object.freeze(cloneValue(record)))
+    return true
+  }
+  get(approvalId: string): ApprovalRecord | undefined {
+    const record = this.records.get(approvalId)
+    return record === undefined ? undefined : Object.freeze(cloneValue(record))
+  }
+  decide(input: Parameters<ApprovalStore["decide"]>[0]): boolean {
+    const record = this.records.get(input.approvalId)
+    const next = durableApprovalProtocol.decide(record, input)
+    if (next === undefined) return false
+    this.records.set(input.approvalId, Object.freeze(next))
+    return true
+  }
+  consume(input: Parameters<ApprovalStore["consume"]>[0]): ApprovalConsumeResult {
+    const record = this.records.get(input.approvalId)
+    const transition = durableApprovalProtocol.consume(record, input)
+    if (transition.next !== undefined)
+      this.records.set(input.approvalId, Object.freeze(transition.next))
+    return transition.result
+  }
+  list(): readonly ApprovalRecord[] {
+    return Object.freeze(
+      [...this.records.values()].map((record) => Object.freeze(cloneValue(record))),
+    )
+  }
+}
+
+// -------------------------------------------------------------------------------------------------