@tokenoftrust/storefront-runner 4.11.0 → 4.11.1

package/apps/storefront/src/lib/customers/contactVault/dataKeys.ts

@@ -0,0 +1,256 @@
+/**
+ * Per-tenant data keys: one active key per (tenant, stage, purpose), generated by KMS
+ * GenerateDataKey and stored only as its wrapped CiphertextBlob in `contact_vault_data_keys`.
+ * Unwrapped keys are held as non-extractable CryptoKeys in a module-scope LRU (512 entries) keyed by
+ * tenant, stage, purpose, kid and the SHA-256 of the wrapped bytes; the plaintext buffer is zeroed
+ * right after import. Every lookup reads the key row from D1 first, so a deleted or replaced
+ * wrapped key stops opening even in a warm isolate.
+ *
+ * Seal protocol. A new key is never persisted on its own. When {@link activeKey} finds no active
+ * row it returns the new key with `pending` statements, and the caller's sealing batch is:
+ *   1. `...pending` — INSERT the key row WHERE NOT EXISTS an active key for that tenant/stage/purpose;
+ *   2. the record insert, which itself requires EXISTS the key row with this kid;
+ *   3. the caller's other writes;
+ *   4. {@link cleanupStatement} — DELETE this kid WHERE NOT EXISTS a row referencing it.
+ * A refused or losing batch therefore commits no key row; the loser re-reads the winner's key and
+ * re-seals. Rotation is the only other writer of key rows.
+ */
+
+/** One statement of a D1 batch. */
+export interface QueryStatement {
+  sql: string;
+  params?: readonly unknown[];
+}
+
+/** The SQL surface data keys need; D1's `fromD1` and the sqlite test harness both satisfy it. */
+export interface Queryable {
+  all<T = Record<string, unknown>>(sql: string, ...params: unknown[]): Promise<T[]>;
+  first<T = Record<string, unknown>>(sql: string, ...params: unknown[]): Promise<T | null>;
+  batch?(statements: readonly QueryStatement[]): Promise<void>;
+}
+import { noteKmsCall } from "./isolateMetrics.js";
+import {
+  sha256Hex,
+  VaultKeyUnavailableError,
+  type DataKeyPurpose,
+  type EncryptionContext,
+  type KmsClient,
+} from "./kms.js";
+
+export interface ActiveDataKey {
+  kid: string;
+  key: CryptoKey;
+  /** Statements the caller puts FIRST in its sealing batch; empty when the key row already exists. */
+  pending: QueryStatement[];
+}
+
+const CACHE_LIMIT = 512;
+const DATA_KEY_BYTES = 32;
+const PURPOSES: readonly DataKeyPurpose[] = ["order-contact", "contact-message", "blind-index"];
+const cache = new Map<string, CryptoKey>();
+const inflight = new Map<string, Promise<CryptoKey>>();
+const counts = { decrypt: 0, generate: 0 };
+
+/** KMS calls made by this isolate, for measurement. Carries no tenant data. */
+export function kmsCallCounts(): { decrypt: number; generate: number } {
+  return { ...counts };
+}
+
+/** Drop every cached key (isolate recycle, tests). */
+export function clearDataKeyCache(): void {
+  cache.clear();
+  inflight.clear();
+}
+
+function remember(cacheKey: string, key: CryptoKey): void {
+  cache.delete(cacheKey);
+  cache.set(cacheKey, key);
+  while (cache.size > CACHE_LIMIT) {
+    const oldest = cache.keys().next().value;
+    if (oldest === undefined) break;
+    cache.delete(oldest);
+  }
+}
+
+async function cacheKeyFor(ctx: EncryptionContext, kid: string, wrapped: string): Promise<string> {
+  return `${ctx.tenantId}|${ctx.stage}|${ctx.purpose}|${kid}|${await sha256Hex(wrapped)}`;
+}
+
+/** Import 32 key bytes as a non-extractable key for the purpose, zeroing the bytes in every case. */
+async function importDataKey(purpose: DataKeyPurpose, plaintext: Uint8Array): Promise<CryptoKey> {
+  try {
+    if (plaintext.length !== DATA_KEY_BYTES) throw new VaultKeyUnavailableError();
+    return purpose === "blind-index"
+      ? await crypto.subtle.importKey("raw", plaintext as BufferSource, { name: "HMAC", hash: "SHA-256" }, false, ["sign", "verify"])
+      : await crypto.subtle.importKey("raw", plaintext as BufferSource, { name: "AES-GCM" }, false, ["encrypt", "decrypt"]);
+  } finally {
+    plaintext.fill(0);
+  }
+}
+
+function newKid(): string {
+  return [...crypto.getRandomValues(new Uint8Array(16))].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+async function unwrap(kms: KmsClient, ctx: EncryptionContext, kid: string, wrapped: string, keyArn: string): Promise<CryptoKey> {
+  const cacheKey = await cacheKeyFor(ctx, kid, wrapped);
+  const hit = cache.get(cacheKey);
+  if (hit) {
+    remember(cacheKey, hit);
+    return hit;
+  }
+  const pendingUnwrap = inflight.get(cacheKey);
+  if (pendingUnwrap) return pendingUnwrap;
+  const work = (async () => {
+    counts.decrypt++;
+    noteKmsCall("decrypt");
+    const key = await importDataKey(ctx.purpose, await kms.decrypt(wrapped, ctx, keyArn));
+    remember(cacheKey, key);
+    return key;
+  })();
+  inflight.set(cacheKey, work);
+  try {
+    return await work;
+  } finally {
+    inflight.delete(cacheKey);
+  }
+}
+
+interface KeyRow {
+  kid: string;
+  wrapped_key: string;
+  kms_key_arn: string;
+}
+
+function insertKeyStatement(ctx: EncryptionContext, kid: string, wrapped: string, keyArn: string, now: Date): QueryStatement {
+  return {
+    sql: `INSERT INTO contact_vault_data_keys (tenant_id, stage, purpose, kid, wrapped_key, kms_key_arn, created_at, retired_at)
+          SELECT ?, ?, ?, ?, ?, ?, ?, NULL
+          WHERE NOT EXISTS (
+            SELECT 1 FROM contact_vault_data_keys
+            WHERE tenant_id = ? AND stage = ? AND purpose = ? AND retired_at IS NULL
+          )`,
+    params: [ctx.tenantId, ctx.stage, ctx.purpose, kid, wrapped, keyArn, now.toISOString(), ctx.tenantId, ctx.stage, ctx.purpose],
+  };
+}
+
+/** Generate a key, cache its CryptoKey and return the row-insert statement for it. */
+async function generate(kms: KmsClient, ctx: EncryptionContext, now: Date): Promise<ActiveDataKey> {
+  counts.generate++;
+  noteKmsCall("generate");
+  const generated = await kms.generateDataKey(ctx);
+  const kid = newKid();
+  const key = await importDataKey(ctx.purpose, generated.plaintext);
+  remember(await cacheKeyFor(ctx, kid, generated.ciphertextBlob), key);
+  return { kid, key, pending: [insertKeyStatement(ctx, kid, generated.ciphertextBlob, generated.keyArn, now)] };
+}
+
+/**
+ * The active key for sealing. When none exists a new one is generated and returned with `pending`;
+ * see the seal protocol above.
+ */
+export async function activeKey(db: Queryable, kms: KmsClient, ctx: EncryptionContext, now: Date): Promise<ActiveDataKey> {
+  const row = await db.first<KeyRow>(
+    `SELECT kid, wrapped_key, kms_key_arn FROM contact_vault_data_keys
+     WHERE tenant_id = ? AND stage = ? AND purpose = ? AND retired_at IS NULL`,
+    ctx.tenantId, ctx.stage, ctx.purpose,
+  );
+  if (row) return { kid: row.kid, key: await unwrap(kms, ctx, row.kid, row.wrapped_key, row.kms_key_arn), pending: [] };
+  return generate(kms, ctx, now);
+}
+
+/**
+ * The final statement of a sealing batch that carried `pending`: removes this kid when no row
+ * references it, so a batch whose record insert did nothing commits no key. `referencedSql` is a
+ * SELECT over the caller's records naming this kid (with `referencedParams`). Only for a kid that
+ * {@link activeKey} returned with non-empty `pending`.
+ */
+export function cleanupStatement(
+  ctx: EncryptionContext,
+  kid: string,
+  referencedSql: string,
+  referencedParams: readonly unknown[] = [],
+): QueryStatement {
+  return {
+    sql: `DELETE FROM contact_vault_data_keys
+          WHERE tenant_id = ? AND stage = ? AND purpose = ? AND kid = ? AND NOT EXISTS (${referencedSql})`,
+    params: [ctx.tenantId, ctx.stage, ctx.purpose, kid, ...referencedParams],
+  };
+}
+
+/**
+ * The key for opening a record sealed under `kid`, active or retired. Reads the row on every call;
+ * null when it is absent, so a deleted wrapped key stops opening immediately.
+ */
+export async function keyForKid(db: Queryable, kms: KmsClient, ctx: EncryptionContext, kid: string): Promise<CryptoKey | null> {
+  const row = await db.first<KeyRow>(
+    `SELECT kid, wrapped_key, kms_key_arn FROM contact_vault_data_keys
+     WHERE tenant_id = ? AND stage = ? AND purpose = ? AND kid = ?`,
+    ctx.tenantId, ctx.stage, ctx.purpose, kid,
+  );
+  if (!row) return null;
+  return unwrap(kms, ctx, row.kid, row.wrapped_key, row.kms_key_arn);
+}
+
+function requireBatch(db: Queryable): (statements: readonly QueryStatement[]) => Promise<void> {
+  if (!db.batch) throw new Error("D1 batch is unavailable");
+  return db.batch.bind(db);
+}
+
+/**
+ * Retire each active key created at or before `now - maxAgeDays` and install a fresh active key in
+ * the same batch (up to `limit` keys per run). The retired kid stays until no row references it.
+ */
+export async function rotateDueKeys(
+  db: Queryable,
+  kms: KmsClient,
+  now: Date,
+  maxAgeDays = 365,
+  limit = 50,
+): Promise<{ rotated: number }> {
+  const batch = requireBatch(db);
+  const cutoff = new Date(now.getTime() - maxAgeDays * 86_400_000).toISOString();
+  const due = await db.all<{ tenant_id: string; stage: EncryptionContext["stage"]; purpose: DataKeyPurpose; kid: string }>(
+    `SELECT tenant_id, stage, purpose, kid FROM contact_vault_data_keys
+     WHERE retired_at IS NULL AND created_at <= ?
+     ORDER BY created_at, tenant_id, stage, purpose
+     LIMIT ?`,
+    cutoff, limit,
+  );
+  let rotated = 0;
+  for (const row of due) {
+    const ctx: EncryptionContext = { tenantId: row.tenant_id, stage: row.stage, purpose: row.purpose };
+    const fresh = await generate(kms, ctx, now);
+    // Retire first: the partial unique index admits one active key, and the insert only lands when
+    // this batch's retire left none (a concurrent rotation that already ran makes both no-ops).
+    await batch([
+      {
+        sql: `UPDATE contact_vault_data_keys SET retired_at = ?
+              WHERE tenant_id = ? AND stage = ? AND purpose = ? AND kid = ? AND retired_at IS NULL`,
+        params: [now.toISOString(), ctx.tenantId, ctx.stage, ctx.purpose, row.kid],
+      },
+      ...fresh.pending,
+    ]);
+    rotated++;
+  }
+  return { rotated };
+}
+
+/**
+ * Delete retired keys no record references. `referencedByPurpose[purpose]` is a correlated SELECT
+ * that refers to the key row as `contact_vault_data_keys` (its tenant_id, stage and kid columns),
+ * e.g. `SELECT 1 FROM order_contact_vault v WHERE v.tenant_id = contact_vault_data_keys.tenant_id
+ * AND v.stage = contact_vault_data_keys.stage AND v.order_kid = contact_vault_data_keys.kid`.
+ * Active keys are never deleted here.
+ */
+export async function deleteUnreferencedRetiredKeys(
+  db: Queryable,
+  referencedByPurpose: Readonly<Record<DataKeyPurpose, string>>,
+): Promise<void> {
+  const batch = requireBatch(db);
+  await batch(PURPOSES.map((purpose) => ({
+    sql: `DELETE FROM contact_vault_data_keys
+          WHERE purpose = ? AND retired_at IS NOT NULL AND NOT EXISTS (${referencedByPurpose[purpose]})`,
+    params: [purpose],
+  })));
+}

package/apps/storefront/src/lib/customers/contactVault/fieldEnvelope.ts

@@ -0,0 +1,88 @@
+/**
+ * Field-level envelope: each personal field is its own AES-256-GCM ciphertext under the tenant's
+ * data key, stored as base64(nonce(12) || ciphertext). The AAD binds purpose, field, tenant, stage,
+ * record id, key id and the group's immutable ceiling (`notAfter`), so a ciphertext moved to another
+ * field, row, tenant or stage fails its tag and reads as absent.
+ *
+ * Errors carry fixed codes only — never a key, nonce, ciphertext or plaintext value.
+ */
+import { base64ToBytes, bytesToBase64 } from "./kms.js";
+
+export type FieldPurpose = "order-contact" | "contact-message";
+
+export interface FieldBinding {
+  purpose: FieldPurpose;
+  field: string;
+  tenantId: string;
+  stage: string;
+  recordId: string;
+  kid: string;
+  notAfter: string;
+}
+
+const NONCE_BYTES = 12;
+const TAG_BYTES = 16;
+const BINDING_KEYS = ["purpose", "field", "tenantId", "stage", "recordId", "kid", "notAfter"] as const;
+const encoder = new TextEncoder();
+const decoder = new TextDecoder("utf-8", { fatal: true });
+
+/**
+ * Canonical AAD bytes: `{v:2, purpose, field, tenantId, stage, recordId, kid, notAfter}` in exactly
+ * that order. Every binding value must be a non-empty string, so no member can silently drop out.
+ */
+export function fieldAad(binding: FieldBinding): Uint8Array {
+  for (const name of BINDING_KEYS) {
+    const value: unknown = binding[name];
+    if (typeof value !== "string" || value === "") throw new TypeError("vault-binding-invalid");
+  }
+  return encoder.encode(JSON.stringify({
+    v: 2,
+    purpose: binding.purpose,
+    field: binding.field,
+    tenantId: binding.tenantId,
+    stage: binding.stage,
+    recordId: binding.recordId,
+    kid: binding.kid,
+    notAfter: binding.notAfter,
+  }));
+}
+
+/** Seal one field value under an AES-GCM data key. */
+export async function sealField(key: CryptoKey, binding: FieldBinding, value: string): Promise<string> {
+  const aad = fieldAad(binding);
+  const nonce = crypto.getRandomValues(new Uint8Array(NONCE_BYTES));
+  const sealed = new Uint8Array(await crypto.subtle.encrypt(
+    { name: "AES-GCM", iv: nonce, additionalData: aad as BufferSource },
+    key,
+    encoder.encode(value) as BufferSource,
+  ));
+  const out = new Uint8Array(NONCE_BYTES + sealed.length);
+  out.set(nonce, 0);
+  out.set(sealed, NONCE_BYTES);
+  return bytesToBase64(out);
+}
+
+/** Open one sealed field. Null when it is malformed or does not authenticate under this binding. */
+export async function openField(key: CryptoKey, binding: FieldBinding, sealed: string): Promise<string | null> {
+  const aad = fieldAad(binding);
+  const bytes = typeof sealed === "string" ? base64ToBytes(sealed) : null;
+  if (!bytes || bytes.length < NONCE_BYTES + TAG_BYTES) return null;
+  let plain: ArrayBuffer;
+  try {
+    plain = await crypto.subtle.decrypt(
+      { name: "AES-GCM", iv: bytes.subarray(0, NONCE_BYTES) as BufferSource, additionalData: aad as BufferSource },
+      key,
+      bytes.subarray(NONCE_BYTES) as BufferSource,
+    );
+  } catch (error) {
+    // AES-GCM reports a failed tag (wrong binding, key or bytes) as OperationError; anything else is a fault.
+    if (error instanceof DOMException && error.name === "OperationError") return null;
+    throw error;
+  }
+  try {
+    return decoder.decode(plain);
+  } catch (error) {
+    if (error instanceof TypeError) return null;
+    throw error;
+  }
+}

package/apps/storefront/src/lib/customers/contactVault/isolateMetrics.ts

@@ -0,0 +1,37 @@
+/**
+ * Isolate-level measurement of the vault's KMS cost: one log line when an isolate serves its first
+ * request, and one per KMS call, each tagged with a random per-isolate id. KMS calls per isolate
+ * start = distinct ids on kms lines / distinct ids on start lines. Lines carry no tenant, record,
+ * key or request data. The id is drawn lazily because Workers refuse random values at global scope.
+ */
+export const ISOLATE_START_EVENT = "isolate-start";
+export const KMS_CALL_EVENT = "contact-vault-kms";
+
+let isolateId: string | null = null;
+let started = false;
+let kmsCalls = 0;
+
+function id(): string {
+  isolateId ??= [...crypto.getRandomValues(new Uint8Array(6))].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+  return isolateId;
+}
+
+/** Log the isolate's first request once. */
+export function noteIsolateStart(log: (line: string) => void = (line) => console.log(line)): void {
+  if (started) return;
+  started = true;
+  log(JSON.stringify({ event: ISOLATE_START_EVENT, isolate: id() }));
+}
+
+/** Log one KMS call with this isolate's running count. */
+export function noteKmsCall(op: "decrypt" | "generate", log: (line: string) => void = (line) => console.log(line)): void {
+  kmsCalls++;
+  log(JSON.stringify({ event: KMS_CALL_EVENT, isolate: id(), op, isolateCalls: kmsCalls }));
+}
+
+/** Reset for tests. */
+export function resetIsolateMetrics(): void {
+  isolateId = null;
+  started = false;
+  kmsCalls = 0;
+}

package/apps/storefront/src/lib/customers/contactVault/kms.ts

@@ -0,0 +1,292 @@
+/**
+ * AWS KMS client for the contact vault: GenerateDataKey and Decrypt over fetch, signed with SigV4
+ * through Web Crypto (no SDK). Every call carries the EncryptionContext {tenantId, stage, purpose}
+ * the environment key's IAM policy requires, and Decrypt pins KeyId to the ARN recorded with the
+ * wrapped key.
+ *
+ * The credential is the `CONTACT_VAULT_KMS` Worker secret: JSON
+ * `{ accessKeyId, secretAccessKey, sessionToken?, region, keyArn }`. Any non-2xx answer, timeout,
+ * network error or malformed response throws {@link VaultKeyUnavailableError}. Errors carry the
+ * fixed code only — never a credential, key byte, blob or response body.
+ */
+
+export type DataKeyPurpose = "order-contact" | "contact-message" | "blind-index";
+export type VaultStage = "preview" | "publication";
+
+export interface EncryptionContext {
+  tenantId: string;
+  stage: VaultStage;
+  purpose: DataKeyPurpose;
+}
+
+export interface KmsCredential {
+  accessKeyId: string;
+  secretAccessKey: string;
+  sessionToken?: string;
+  region: string;
+  keyArn: string;
+}
+
+export interface GeneratedDataKey {
+  /** 32 plaintext key bytes. The caller imports and then zeroes them. */
+  plaintext: Uint8Array;
+  /** Base64 CiphertextBlob: the only form that is stored. */
+  ciphertextBlob: string;
+  keyArn: string;
+}
+
+export interface KmsClient {
+  generateDataKey(ctx: EncryptionContext): Promise<GeneratedDataKey>;
+  decrypt(ciphertextBlob: string, ctx: EncryptionContext, keyArn: string): Promise<Uint8Array>;
+}
+
+export class VaultKeyUnavailableError extends Error {
+  readonly code = "vault-key-unavailable";
+  constructor() {
+    super("vault-key-unavailable");
+    this.name = "VaultKeyUnavailableError";
+  }
+}
+
+const PURPOSES: ReadonlySet<string> = new Set(["order-contact", "contact-message", "blind-index"]);
+const STAGES: ReadonlySet<string> = new Set(["preview", "publication"]);
+const CREDENTIAL_KEYS: ReadonlySet<string> = new Set(["accessKeyId", "secretAccessKey", "sessionToken", "region", "keyArn"]);
+const ACCESS_KEY_ID = /^[A-Z0-9]{16,128}$/;
+const SECRET = /^[\x21-\x7e]{16,256}$/;
+const SESSION_TOKEN = /^[\x21-\x7e]{16,4096}$/;
+const REGION = /^[a-z]{2}(-[a-z]+)+-\d{1,2}$/;
+const KEY_ARN = /^arn:aws(-[a-z]+)*:kms:([a-z]{2}(-[a-z]+)+-\d{1,2}):\d{12}:key\/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|mrk-[0-9a-f]{32})$/;
+const BASE64 = /^[A-Za-z0-9+/]+={0,2}$/;
+const DATA_KEY_BYTES = 32;
+const encoder = new TextEncoder();
+
+export function base64ToBytes(value: string): Uint8Array | null {
+  if (value.length % 4 !== 0 || !BASE64.test(value)) return null;
+  let binary: string;
+  try {
+    binary = atob(value);
+  } catch (error) {
+    if (error instanceof DOMException && error.name === "InvalidCharacterError") return null;
+    throw error;
+  }
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
+  return out;
+}
+
+export function bytesToBase64(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+
+function hex(bytes: ArrayBuffer | Uint8Array): string {
+  return [...new Uint8Array(bytes)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+/** Lowercase hex SHA-256 of a UTF-8 string. */
+export async function sha256Hex(value: string): Promise<string> {
+  return hex(await crypto.subtle.digest("SHA-256", encoder.encode(value) as BufferSource));
+}
+
+async function hmac(key: Uint8Array, data: string): Promise<Uint8Array> {
+  const imported = await crypto.subtle.importKey("raw", key as BufferSource, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  return new Uint8Array(await crypto.subtle.sign("HMAC", imported, encoder.encode(data) as BufferSource));
+}
+
+/** The KMS key's region, read from its ARN, or null when the ARN is not a KMS key ARN. */
+function keyArnRegion(arn: string): string | null {
+  const match = KEY_ARN.exec(arn);
+  return match ? match[2] ?? null : null;
+}
+
+/** Parse the credential secret, or null when it is absent or malformed in any way. */
+export function parseKmsCredential(raw: string | undefined | null): KmsCredential | null {
+  if (typeof raw !== "string" || raw.trim() === "") return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    if (error instanceof SyntaxError) return null;
+    throw error;
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+  const record = parsed as Record<string, unknown>;
+  if (Object.keys(record).some((key) => !CREDENTIAL_KEYS.has(key))) return null;
+  const { accessKeyId, secretAccessKey, sessionToken, region, keyArn } = record;
+  if (typeof accessKeyId !== "string" || !ACCESS_KEY_ID.test(accessKeyId)) return null;
+  if (typeof secretAccessKey !== "string" || !SECRET.test(secretAccessKey)) return null;
+  if (sessionToken !== undefined && (typeof sessionToken !== "string" || !SESSION_TOKEN.test(sessionToken))) return null;
+  if (typeof region !== "string" || !REGION.test(region)) return null;
+  if (typeof keyArn !== "string" || keyArnRegion(keyArn) !== region) return null;
+  return {
+    accessKeyId,
+    secretAccessKey,
+    ...(sessionToken === undefined ? {} : { sessionToken }),
+    region,
+    keyArn,
+  };
+}
+
+export interface SignatureV4Input {
+  method: string;
+  /** Absolute URL. Its path must already be in canonical form (KMS always uses "/"). */
+  url: string;
+  /** Headers to sign; `host` is derived from the URL. Names are matched case-insensitively. */
+  headers: Readonly<Record<string, string>>;
+  body: string;
+  region: string;
+  service: string;
+  accessKeyId: string;
+  secretAccessKey: string;
+  sessionToken?: string;
+  /** ISO basic UTC timestamp, `YYYYMMDDTHHMMSSZ`. */
+  amzDate: string;
+}
+
+export interface SignatureV4Result {
+  /** Every signed header (lowercase names), `host` included, plus `authorization`. */
+  headers: Record<string, string>;
+  canonicalRequest: string;
+  stringToSign: string;
+}
+
+function rfc3986(value: string): string {
+  return encodeURIComponent(value).replace(/[!'()*]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+
+/** Pure SigV4 signer (AWS Signature Version 4, header form). */
+export async function signRequestV4(input: SignatureV4Input): Promise<SignatureV4Result> {
+  const url = new URL(input.url);
+  const date = input.amzDate.slice(0, 8);
+  const headers: Record<string, string> = {};
+  for (const [name, value] of Object.entries(input.headers)) headers[name.toLowerCase()] = value.trim().replace(/\s+/g, " ");
+  headers.host = url.host;
+  headers["x-amz-date"] = input.amzDate;
+  if (input.sessionToken !== undefined) headers["x-amz-security-token"] = input.sessionToken;
+  const names = Object.keys(headers).sort();
+  const signedHeaders = names.join(";");
+  const query = [...url.searchParams.entries()]
+    .map(([name, value]) => [rfc3986(name), rfc3986(value)] as const)
+    .sort(([a, av], [b, bv]) => (a < b ? -1 : a > b ? 1 : av < bv ? -1 : av > bv ? 1 : 0))
+    .map(([name, value]) => `${name}=${value}`)
+    .join("&");
+  const canonicalRequest = [
+    input.method.toUpperCase(),
+    url.pathname || "/",
+    query,
+    names.map((name) => `${name}:${headers[name]}\n`).join(""),
+    signedHeaders,
+    await sha256Hex(input.body),
+  ].join("\n");
+  const scope = `${date}/${input.region}/${input.service}/aws4_request`;
+  const stringToSign = ["AWS4-HMAC-SHA256", input.amzDate, scope, await sha256Hex(canonicalRequest)].join("\n");
+  const kDate = await hmac(encoder.encode(`AWS4${input.secretAccessKey}`), date);
+  const kRegion = await hmac(kDate, input.region);
+  const kService = await hmac(kRegion, input.service);
+  const kSigning = await hmac(kService, "aws4_request");
+  const signature = hex(await hmac(kSigning, stringToSign));
+  headers.authorization = `AWS4-HMAC-SHA256 Credential=${input.accessKeyId}/${scope}, SignedHeaders=${signedHeaders}, Signature=${signature}`;
+  return { headers, canonicalRequest, stringToSign };
+}
+
+function amzDate(now: Date): string {
+  return now.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}/, "");
+}
+
+function validContext(ctx: EncryptionContext): boolean {
+  return typeof ctx.tenantId === "string" && ctx.tenantId !== ""
+    && STAGES.has(ctx.stage) && PURPOSES.has(ctx.purpose);
+}
+
+/** Decode a response's Plaintext as exactly one 32-byte data key, or throw. */
+function dataKeyBytes(value: unknown): Uint8Array {
+  const bytes = typeof value === "string" ? base64ToBytes(value) : null;
+  if (!bytes || bytes.length !== DATA_KEY_BYTES) {
+    bytes?.fill(0);
+    throw new VaultKeyUnavailableError();
+  }
+  return bytes;
+}
+
+/**
+ * A KMS client bound to one credential. `now` is injectable so tests can pin the signing date.
+ */
+export function createKmsClient(
+  cred: KmsCredential | null,
+  fetchImpl: typeof fetch = fetch,
+  timeoutMs = 3000,
+  now: () => Date = () => new Date(),
+): KmsClient {
+  async function call(target: "GenerateDataKey" | "Decrypt", payload: Record<string, unknown>): Promise<Record<string, unknown>> {
+    if (!cred) throw new VaultKeyUnavailableError();
+    const url = `https://kms.${cred.region}.amazonaws.com/`;
+    const body = JSON.stringify(payload);
+    const signed = await signRequestV4({
+      method: "POST",
+      url,
+      headers: { "content-type": "application/x-amz-json-1.1", "x-amz-target": `TrentService.${target}` },
+      body,
+      region: cred.region,
+      service: "kms",
+      accessKeyId: cred.accessKeyId,
+      secretAccessKey: cred.secretAccessKey,
+      ...(cred.sessionToken === undefined ? {} : { sessionToken: cred.sessionToken }),
+      amzDate: amzDate(now()),
+    });
+    // fetch derives Host from the URL; it was signed with that same value.
+    const sendHeaders = { ...signed.headers };
+    delete sendHeaders.host;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const response = await fetchImpl(url, { method: "POST", headers: sendHeaders, body, signal: controller.signal });
+      if (!response.ok) {
+        await response.body?.cancel();
+        throw new VaultKeyUnavailableError();
+      }
+      const parsed: unknown = JSON.parse(await response.text());
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new VaultKeyUnavailableError();
+      return parsed as Record<string, unknown>;
+    } catch {
+      // Network failure, abort, unreadable body or malformed JSON: one fixed code, no detail.
+      throw new VaultKeyUnavailableError();
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  return {
+    async generateDataKey(ctx) {
+      if (!cred || !validContext(ctx)) throw new VaultKeyUnavailableError();
+      const result = await call("GenerateDataKey", {
+        KeyId: cred.keyArn,
+        KeySpec: "AES_256",
+        EncryptionContext: { tenantId: ctx.tenantId, stage: ctx.stage, purpose: ctx.purpose },
+      });
+      const plaintext = dataKeyBytes(result.Plaintext);
+      const blob = result.CiphertextBlob;
+      if (typeof blob !== "string" || !base64ToBytes(blob) || result.KeyId !== cred.keyArn) {
+        plaintext.fill(0);
+        throw new VaultKeyUnavailableError();
+      }
+      return { plaintext, ciphertextBlob: blob, keyArn: cred.keyArn };
+    },
+    async decrypt(ciphertextBlob, ctx, keyArn) {
+      if (!cred || !validContext(ctx) || keyArnRegion(keyArn) !== cred.region ||!base64ToBytes(ciphertextBlob)) {
+        throw new VaultKeyUnavailableError();
+      }
+      const result = await call("Decrypt", {
+        CiphertextBlob: ciphertextBlob,
+        KeyId: keyArn,
+        EncryptionContext: { tenantId: ctx.tenantId, stage: ctx.stage, purpose: ctx.purpose },
+      });
+      const plaintext = dataKeyBytes(result.Plaintext);
+      if (result.KeyId !== keyArn) {
+        plaintext.fill(0);
+        throw new VaultKeyUnavailableError();
+      }
+      return plaintext;
+    },
+  };
+}