@cosmicdrift/kumiko-framework 0.1.0

package/src/secrets/__tests__/leak-guard.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, test } from "vitest";
+import { assertNoSecretLeak } from "../leak-guard";
+import { createSecret } from "../types";
+
+describe("assertNoSecretLeak — walks the response tree for branded values", () => {
+  test("plain data passes through silently", () => {
+    expect(() =>
+      assertNoSecretLeak({
+        id: "42",
+        title: "foo",
+        tags: ["a", "b"],
+        nested: { deep: { value: 12 } },
+      }),
+    ).not.toThrow();
+  });
+
+  test("throws when Secret<> sits at the root", () => {
+    const s = createSecret("plaintext-api-key");
+    expect(() => assertNoSecretLeak(s)).toThrow(/leaked.*at \$/);
+  });
+
+  test("throws when Secret<> is nested in an object", () => {
+    const payload = {
+      id: "42",
+      apiKey: createSecret("leak-me"),
+    };
+    expect(() => assertNoSecretLeak(payload)).toThrow(/leaked.*at \$\.apiKey/);
+  });
+
+  test("throws when Secret<> is inside an array", () => {
+    const payload = {
+      keys: [createSecret("one"), "two"],
+    };
+    expect(() => assertNoSecretLeak(payload)).toThrow(/leaked.*at \$\.keys\[0\]/);
+  });
+
+  test("reports path to the first offending node", () => {
+    const payload = {
+      outer: {
+        middle: [null, { deeper: createSecret("gotcha") }],
+      },
+    };
+    expect(() => assertNoSecretLeak(payload)).toThrow(/leaked.*at \$\.outer\.middle\[1\]\.deeper/);
+  });
+
+  test("skips opaque class instances (Date, Buffer) so they don't false-positive", () => {
+    // Date and Buffer have internal slots the walker can't introspect — non-
+    // plain prototype, no entry-iterator we trust. Stopping here is the
+    // conservative call. Map and Set are NOT in this list (see next two tests):
+    // they have well-defined iteration and a toJSON-via-custom-serializer can
+    // expand them onto the wire, so we walk them.
+    const payload = {
+      createdAt: new Date("2024-01-01"),
+      binary: Buffer.from("hello"),
+    };
+    expect(() => assertNoSecretLeak(payload)).not.toThrow();
+  });
+
+  test("walks Set entries and throws when Secret<> sits inside", () => {
+    const payload = {
+      keys: new Set([createSecret("hidden")]),
+    };
+    expect(() => assertNoSecretLeak(payload)).toThrow(/leaked.*at \$\.keys\.<set\[0\]>/);
+  });
+
+  test("walks Map values and throws when Secret<> sits inside", () => {
+    const payload = {
+      registry: new Map([["api", createSecret("hidden")]]),
+    };
+    expect(() => assertNoSecretLeak(payload)).toThrow(/leaked.*at \$\.registry\.<map\[0\]\.val>/);
+  });
+
+  test("Set of plain values stays silent — walking doesn't false-positive", () => {
+    const payload = {
+      ids: new Set(["a", "b"]),
+      tags: new Map([["env", "prod"]]),
+    };
+    expect(() => assertNoSecretLeak(payload)).not.toThrow();
+  });
+
+  test("stops at MAX_DEPTH so cyclic or pathologically-deep input can't hang", () => {
+    // Build a cyclic object — without the depth cap this would recurse forever.
+    const root: Record<string, unknown> = { id: "root" };
+    root["self"] = root;
+    expect(() => assertNoSecretLeak(root)).not.toThrow();
+  });
+
+  test("undefined and null are no-ops", () => {
+    expect(() => assertNoSecretLeak(undefined)).not.toThrow();
+    expect(() => assertNoSecretLeak(null)).not.toThrow();
+  });
+});

package/src/secrets/__tests__/rotation.test.ts

@@ -0,0 +1,149 @@
+import { randomBytes } from "node:crypto";
+import { describe, expect, test } from "vitest";
+import { createEnvMasterKeyProvider } from "../env-master-key-provider";
+import { decryptValue, encryptValue } from "../envelope";
+import { rewrapDek } from "../rotation";
+
+// Shared KEK bytes across provider reconstructions — mimics ops setting
+// the same env var across deploys. This is how we model "the KEK didn't
+// change but CURRENT_VERSION did" in a single test process.
+const KEK_V1 = randomBytes(32);
+const KEK_V2 = randomBytes(32);
+
+function providerWithCurrent(
+  v: number,
+  extraKeys: boolean = true,
+): ReturnType<typeof createEnvMasterKeyProvider> {
+  const envVars: Record<string, string> = {
+    KUMIKO_SECRETS_MASTER_KEY_V1: KEK_V1.toString("base64"),
+    KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: String(v),
+  };
+  if (extraKeys) {
+    envVars["KUMIKO_SECRETS_MASTER_KEY_V2"] = KEK_V2.toString("base64");
+  }
+  return createEnvMasterKeyProvider({ env: envVars });
+}
+
+describe("rotation — the whole point of the multi-version keyring", () => {
+  test("a value encrypted with V1 stays readable after CURRENT flips to V2", async () => {
+    // Day 1: ops has only V1 deployed, current=1. We encrypt a secret.
+    const day1 = providerWithCurrent(1, /* extraKeys */ false);
+    const envelope = await encryptValue("my-stripe-key", day1);
+    expect(envelope.kekVersion).toBe(1);
+
+    // Day 3: ops deployed V2 ENV too, and has now flipped current=2.
+    // The keyring still contains V1 so old rows must keep reading.
+    const day3 = providerWithCurrent(2);
+    const back = await decryptValue(envelope, day3);
+    expect(back).toBe("my-stripe-key");
+  });
+
+  test("after rotation, new writes land on the new version", async () => {
+    const day3 = providerWithCurrent(2);
+    const envelope = await encryptValue("fresh secret", day3);
+    // The point: without touching rewrap logic at all, simply having
+    // flipped CURRENT_VERSION means new values use V2.
+    expect(envelope.kekVersion).toBe(2);
+  });
+
+  test("rewrapDek migrates a V1-envelope to V2 without touching ciphertext", async () => {
+    // Encrypt under V1 (no V2 yet) so we have a pure V1 row.
+    const day1 = providerWithCurrent(1, /* extraKeys */ false);
+    const originalEnvelope = await encryptValue("sensitive", day1);
+    expect(originalEnvelope.kekVersion).toBe(1);
+
+    // Later, ops has rolled V2 and flipped current.
+    const day3 = providerWithCurrent(2);
+    const rotated = await rewrapDek(originalEnvelope, day3);
+
+    // Key property: DEK got re-wrapped, ciphertext untouched. This is
+    // WHY envelope rotation is cheap — we only rewrite a ~60-byte blob
+    // per row, never the potentially large ciphertext.
+    expect(rotated.kekVersion).toBe(2);
+    expect(rotated.ciphertext.equals(originalEnvelope.ciphertext)).toBe(true);
+    expect(rotated.iv.equals(originalEnvelope.iv)).toBe(true);
+    expect(rotated.authTag.equals(originalEnvelope.authTag)).toBe(true);
+    // The wrapped DEK DID change — it's now wrapped with KEK V2.
+    expect(rotated.encryptedDek.equals(originalEnvelope.encryptedDek)).toBe(false);
+
+    // Most important: the rotated envelope still decrypts correctly.
+    expect(await decryptValue(rotated, day3)).toBe("sensitive");
+  });
+
+  test("rewrapDek is a no-op when the envelope is already current", async () => {
+    const day3 = providerWithCurrent(2);
+    const envelope = await encryptValue("already-v2", day3);
+    expect(envelope.kekVersion).toBe(2);
+
+    const rotated = await rewrapDek(envelope, day3);
+    // Same reference — no work was done.
+    expect(rotated).toBe(envelope);
+  });
+
+  test("rewrap requires the OLD version to still be in the keyring", async () => {
+    // Encrypt under V1
+    const day1 = providerWithCurrent(1, /* extraKeys */ false);
+    const envelope = await encryptValue("stranded", day1);
+
+    // Day 5: ops RETIRED V1 — env no longer has KUMIKO_SECRETS_MASTER_KEY_V1,
+    // only V2. An old row with kekVersion=1 is now unreadable.
+    const dayRetired = createEnvMasterKeyProvider({
+      env: {
+        KUMIKO_SECRETS_MASTER_KEY_V2: KEK_V2.toString("base64"),
+        KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "2",
+      },
+    });
+    await expect(rewrapDek(envelope, dayRetired)).rejects.toThrow(/no KEK for version 1/);
+    // Lesson: ops MUST rotate all rows off V1 before deleting V1 from env.
+  });
+
+  test("full rotation drill: encrypt V1 → staging V1+V2 → promote to V2 → rewrap → retire V1", async () => {
+    // Simulates the canonical rotation sequence end-to-end.
+
+    // --- Day 1: only V1, CURRENT=1 ---
+    const day1 = providerWithCurrent(1, /* extraKeys */ false);
+    const envA = await encryptValue("value-A", day1);
+    const envB = await encryptValue("value-B", day1);
+    expect(envA.kekVersion).toBe(1);
+    expect(envB.kekVersion).toBe(1);
+
+    // --- Day 2: V1+V2 deployed, CURRENT still 1 (staging) ---
+    const day2 = providerWithCurrent(1, /* extraKeys */ true);
+    // Both old rows still read
+    expect(await decryptValue(envA, day2)).toBe("value-A");
+    expect(await decryptValue(envB, day2)).toBe("value-B");
+    // New writes: still V1 — crucial! CURRENT hasn't flipped.
+    const envC = await encryptValue("value-C", day2);
+    expect(envC.kekVersion).toBe(1);
+
+    // --- Day 3: CURRENT flipped to 2 ---
+    const day3 = providerWithCurrent(2, /* extraKeys */ true);
+    // Old rows still readable
+    expect(await decryptValue(envA, day3)).toBe("value-A");
+    // New writes now land on V2
+    const envD = await encryptValue("value-D", day3);
+    expect(envD.kekVersion).toBe(2);
+
+    // --- Day 4: rotation job migrates all V1 rows ---
+    const rotA = await rewrapDek(envA, day3);
+    const rotB = await rewrapDek(envB, day3);
+    const rotC = await rewrapDek(envC, day3);
+    expect(rotA.kekVersion).toBe(2);
+    expect(rotB.kekVersion).toBe(2);
+    expect(rotC.kekVersion).toBe(2);
+    expect(await decryptValue(rotA, day3)).toBe("value-A");
+
+    // --- Day 5: V1 retired from env ---
+    const day5 = createEnvMasterKeyProvider({
+      env: {
+        KUMIKO_SECRETS_MASTER_KEY_V2: KEK_V2.toString("base64"),
+        KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "2",
+      },
+    });
+    // All rotated rows still decrypt
+    expect(await decryptValue(rotA, day5)).toBe("value-A");
+    expect(await decryptValue(rotB, day5)).toBe("value-B");
+    expect(await decryptValue(rotC, day5)).toBe("value-C");
+    expect(await decryptValue(envD, day5)).toBe("value-D");
+  });
+});

package/src/secrets/dek-cache.ts

@@ -0,0 +1,116 @@
+// In-memory cache for unwrapped DEKs. Cloud-KMS unwrap calls are expensive
+// ($ + network). Caching for a short TTL amortises the cost across reads
+// of the same secret. The TTL bounds the time plaintext DEKs live in the
+// process — shorter is safer, longer is cheaper.
+//
+// Two bounds are enforced so the cache can't leak memory under adversarial
+// or skewed workloads:
+//   - TTL per entry (default 5min): old DEKs expire even if never reused.
+//   - maxEntries (default 1000): LRU eviction kicks in on insert when full.
+
+import { createHash } from "node:crypto";
+import type { MasterKeyProvider } from "./types";
+
+const DEFAULT_TTL_MS = 5 * 60 * 1000; // 5 minutes
+const DEFAULT_MAX_ENTRIES = 1000;
+
+export type DekCacheOptions = {
+  readonly ttlMs?: number;
+  // Cap on the number of cached DEKs. On overflow, least-recently-used
+  // entries are evicted (their bytes zeroed).
+  readonly maxEntries?: number;
+  // Injectable clock for deterministic tests.
+  readonly now?: () => number;
+};
+
+export type DekCache = {
+  // Unwrap via the provider, caching the result. Second call within TTL
+  // returns the cached DEK without hitting the provider.
+  unwrapDek(encryptedDek: Buffer, kekVersion: number, provider: MasterKeyProvider): Promise<Buffer>;
+
+  // Drop every entry. Call after KEK rotation so old cached DEKs (still
+  // valid, but referencing the old kekVersion) don't serve reads that
+  // could otherwise detect the version change.
+  clear(): void;
+
+  // Observability: how many entries are live right now (pre-TTL-prune).
+  size(): number;
+};
+
+export function createDekCache(opts: DekCacheOptions = {}): DekCache {
+  const ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
+  const maxEntries = opts.maxEntries ?? DEFAULT_MAX_ENTRIES;
+  const now = opts.now ?? (() => Date.now());
+  // Key is a SHA-256 hash of (encryptedDek || kekVersion). Hashing avoids
+  // keeping the raw wrapped bytes as the Map key (which would pin them
+  // in memory) and ensures version is part of the identity — same
+  // encryptedDek at different versions cannot collide.
+  //
+  // JS Map keeps insertion order — we exploit that for LRU: on hit we
+  // delete+re-insert the entry, which moves it to the "most recent" end.
+  // On overflow the first key (oldest) gets evicted.
+  const entries = new Map<string, { dek: Buffer; expiresAt: number }>();
+
+  function cacheKey(encryptedDek: Buffer, kekVersion: number): string {
+    // kekVersion as 4 bytes — handles realistic rotation counts without
+    // truncating (1-byte would wrap at 256, which IS achievable over a
+    // decade of weekly rotations).
+    const versionBuf = Buffer.alloc(4);
+    versionBuf.writeUInt32BE(kekVersion);
+    return createHash("sha256").update(encryptedDek).update(versionBuf).digest("hex");
+  }
+
+  function evictOldestIfFull(): void {
+    // skip: under cap, no eviction needed.
+    if (entries.size < maxEntries) return;
+    // First key is the least-recently-inserted / least-recently-touched
+    // thanks to the delete+set dance below. iterator().next() is O(1).
+    const oldestKey = entries.keys().next().value;
+    // skip: Map was empty mid-check — no entry to evict.
+    if (oldestKey === undefined) return;
+    const oldest = entries.get(oldestKey);
+    if (oldest) oldest.dek.fill(0);
+    entries.delete(oldestKey);
+  }
+
+  return {
+    async unwrapDek(encryptedDek, kekVersion, provider) {
+      const key = cacheKey(encryptedDek, kekVersion);
+      const hit = entries.get(key);
+      if (hit && hit.expiresAt > now()) {
+        // Touch: re-insert to move to the "most recent" end of the Map.
+        // Without this the LRU would collapse into FIFO.
+        entries.delete(key);
+        entries.set(key, hit);
+        // Return a copy so callers that .fill(0) after use don't wipe the
+        // cached buffer for everyone else.
+        return Buffer.from(hit.dek);
+      }
+      // Prune the expired entry on miss to bound memory.
+      if (hit) {
+        hit.dek.fill(0);
+        entries.delete(key);
+      }
+
+      const dek = await provider.unwrapDek(encryptedDek, kekVersion);
+      evictOldestIfFull();
+      // Store a copy — caller can zero its own buffer after use.
+      entries.set(key, { dek: Buffer.from(dek), expiresAt: now() + ttlMs });
+      return dek;
+    },
+
+    clear() {
+      // Zero the DEK bytes before dropping references. Best-effort —
+      // Node can't guarantee secure erase, but clearing now prevents
+      // stale key material from lingering in heap snapshots.
+      for (const { dek } of entries.values()) {
+        dek.fill(0);
+      }
+      entries.clear();
+    },
+
+    size() {
+      return entries.size;
+    },
+  };
+}

package/src/secrets/env-master-key-provider.ts

@@ -0,0 +1,162 @@
+// Default MasterKeyProvider for deployments without a dedicated KMS. Reads
+// KEK material from env, supports a multi-version keyring so rotation runs
+// without a maintenance window. See loadKeyring + resolveCurrentVersion at
+// the bottom for the env contract.
+
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+import { InternalError } from "../errors";
+import type { MasterKeyProvider } from "./types";
+
+const ALGORITHM = "aes-256-gcm";
+const KEK_LENGTH = 32; // AES-256
+const IV_LENGTH = 12;
+const TAG_LENGTH = 16;
+
+export type EnvMasterKeyProviderOptions = {
+  // Env accessor (injectable for tests). Defaults to process.env.
+  readonly env?: Readonly<Record<string, string | undefined>>;
+};
+
+// A parsed keyring: version number → raw KEK bytes. Kept separate from
+// the provider closure so loadKeyring is unit-testable in isolation.
+export type Keyring = ReadonlyMap<number, Buffer>;
+
+export function createEnvMasterKeyProvider(
+  opts: EnvMasterKeyProviderOptions = {},
+): MasterKeyProvider {
+  const env = opts.env ?? process.env;
+
+  const keyring = loadKeyring(env);
+  const current = resolveCurrentVersion(env);
+
+  // --- Boot validation (after keyring + current are known) -------------
+  if (!keyring.has(current)) {
+    throw new InternalError({
+      message:
+        `[secrets] currentVersion=${current} not present in keyring ` +
+        `(have versions: ${[...keyring.keys()].sort().join(",")}). ` +
+        `Check KUMIKO_SECRETS_MASTER_KEY_V${current} is set.`,
+    });
+  }
+
+  // --- KEK-wrap / unwrap boilerplate (AES-256-GCM) ---------------------
+  // The DEK is the plaintext here; we encrypt it with the KEK. Same
+  // algorithm as the value encryption, just a different role.
+
+  return {
+    async wrapDek(dek) {
+      const kek = keyring.get(current);
+      if (!kek) {
+        // Should never reach here — boot validation above guarantees the
+        // current KEK exists. Defensive throw so a surprise at runtime is
+        // surfaceable instead of silently coercing to zero-bytes.
+        throw new InternalError({
+          message: `[secrets] missing KEK for current version ${current}`,
+        });
+      }
+      const iv = randomBytes(IV_LENGTH);
+      const cipher = createCipheriv(ALGORITHM, kek, iv);
+      const wrapped = Buffer.concat([cipher.update(dek), cipher.final()]);
+      const tag = cipher.getAuthTag();
+      // Pack into a single buffer: iv || tag || ciphertext. The kekVersion
+      // is returned separately — it lives on the Envelope row, not inside
+      // encryptedDek, so ops can inspect it with `SELECT kekVersion FROM …`.
+      return {
+        encryptedDek: Buffer.concat([iv, tag, wrapped]),
+        kekVersion: current,
+      };
+    },
+
+    async unwrapDek(encryptedDek, kekVersion) {
+      const kek = keyring.get(kekVersion);
+      if (!kek) {
+        throw new InternalError({
+          message:
+            `[secrets] no KEK for version ${kekVersion} — ` +
+            `keyring has [${[...keyring.keys()].sort().join(",")}]. ` +
+            `If you retired an old version, you must rotate rows off it first.`,
+        });
+      }
+      const iv = encryptedDek.subarray(0, IV_LENGTH);
+      const tag = encryptedDek.subarray(IV_LENGTH, IV_LENGTH + TAG_LENGTH);
+      const ciphertext = encryptedDek.subarray(IV_LENGTH + TAG_LENGTH);
+      const decipher = createDecipheriv(ALGORITHM, kek, iv);
+      decipher.setAuthTag(tag);
+      return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+    },
+
+    currentVersion() {
+      return current;
+    },
+
+    async isAvailable() {
+      // Env-backed provider is always "available" once boot passed — the
+      // check already verified keyring presence. Real KMS providers would
+      // ping the service here.
+      return true;
+    },
+  };
+}
+
+// ENV schema (Decision 1 — per-version variables):
+//   KUMIKO_SECRETS_MASTER_KEY_V1=<base64 32 bytes>
+//   KUMIKO_SECRETS_MASTER_KEY_V2=<base64 32 bytes>
+//   ...
+// Rationale: k8s secrets map 1:1 per env var, so ops rotate single versions
+// without rewriting a JSON blob. A typo blasts only one key, not the ring.
+const KEY_VAR_PATTERN = /^KUMIKO_SECRETS_MASTER_KEY_V(\d+)$/;
+
+function loadKeyring(env: Readonly<Record<string, string | undefined>>): Keyring {
+  const keyring = new Map<number, Buffer>();
+  for (const [name, value] of Object.entries(env)) {
+    const match = name.match(KEY_VAR_PATTERN);
+    if (!match || !value) continue;
+    // biome-ignore lint/style/noNonNullAssertion: regex group 1 always present
+    const version = Number.parseInt(match[1]!, 10);
+    if (!Number.isFinite(version) || version < 1) {
+      throw new InternalError({
+        message: `[secrets] invalid KEK version in ${name} (must be positive integer)`,
+      });
+    }
+    const kek = Buffer.from(value, "base64");
+    if (kek.length !== KEK_LENGTH) {
+      throw new InternalError({
+        message: `[secrets] ${name}: KEK must decode to exactly ${KEK_LENGTH} bytes (got ${kek.length})`,
+      });
+    }
+    keyring.set(version, kek);
+  }
+  if (keyring.size === 0) {
+    throw new InternalError({
+      message: "[secrets] no KEK found in environment — set at least KUMIKO_SECRETS_MASTER_KEY_V1",
+    });
+  }
+  return keyring;
+}
+
+// currentVersion resolution (Decision 2 — explicit env var):
+//   KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION=2
+// Rationale: adding a new KEK to the keyring must NOT auto-promote it to
+// "wrap with this one". Staging window — ops deploys V2 alongside V1, runs
+// a canary rotation job, then flips CURRENT_VERSION only after validation.
+// AWS KMS, GCP KMS, Azure Key Vault all separate "known-keys" from
+// "active-key-id" for the same reason.
+const CURRENT_VERSION_VAR = "KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION";
+
+function resolveCurrentVersion(env: Readonly<Record<string, string | undefined>>): number {
+  const raw = env[CURRENT_VERSION_VAR];
+  if (!raw) {
+    throw new InternalError({
+      message:
+        `[secrets] ${CURRENT_VERSION_VAR} not set — explicit current-version ` +
+        "required so adding a new KEK to the env doesn't auto-promote it",
+    });
+  }
+  const version = Number.parseInt(raw, 10);
+  if (!Number.isFinite(version) || version < 1 || String(version) !== raw.trim()) {
+    throw new InternalError({
+      message: `[secrets] ${CURRENT_VERSION_VAR}="${raw}" must be a positive integer`,
+    });
+  }
+  return version;
+}

package/src/secrets/envelope.ts

@@ -0,0 +1,55 @@
+// Envelope encryption primitives. Combines a freshly-generated DEK + the
+// central KEK (via MasterKeyProvider) into a self-contained Envelope that
+// carries everything needed to decrypt later.
+
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+import type { Envelope, MasterKeyProvider } from "./types";
+
+const ALGORITHM = "aes-256-gcm";
+const DEK_LENGTH = 32; // AES-256
+const IV_LENGTH = 12; // GCM standard nonce length
+
+// Encrypts plaintext with a new random DEK, then wraps the DEK with the
+// current KEK. The returned Envelope is safe to store at rest.
+export async function encryptValue(
+  plaintext: string,
+  provider: MasterKeyProvider,
+): Promise<Envelope> {
+  // Fresh DEK per value. Reusing DEKs across rows would break forward
+  // secrecy (one compromised ciphertext-IV pair leaks information about
+  // others encrypted with the same DEK).
+  const dek = randomBytes(DEK_LENGTH);
+  try {
+    const iv = randomBytes(IV_LENGTH);
+
+    const cipher = createCipheriv(ALGORITHM, dek, iv);
+    const ciphertext = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+    const authTag = cipher.getAuthTag();
+
+    const { encryptedDek, kekVersion } = await provider.wrapDek(dek);
+    return { ciphertext, iv, authTag, encryptedDek, kekVersion };
+  } finally {
+    // Zero the DEK on best effort regardless of success — if provider.wrapDek
+    // threw, the plaintext DEK must still not linger in the heap waiting
+    // for GC. Node can't guarantee secure erase, but clearing the bytes
+    // removes the obvious window.
+    dek.fill(0);
+  }
+}
+
+// Decrypts an Envelope. Throws if the authTag doesn't match — tampered
+// ciphertexts cannot round-trip.
+export async function decryptValue(
+  envelope: Envelope,
+  provider: MasterKeyProvider,
+): Promise<string> {
+  const dek = await provider.unwrapDek(envelope.encryptedDek, envelope.kekVersion);
+  try {
+    const decipher = createDecipheriv(ALGORITHM, dek, envelope.iv);
+    decipher.setAuthTag(envelope.authTag);
+    const plaintext = Buffer.concat([decipher.update(envelope.ciphertext), decipher.final()]);
+    return plaintext.toString("utf8");
+  } finally {
+    dek.fill(0);
+  }
+}

package/src/secrets/index.ts

@@ -0,0 +1,19 @@
+export { createDekCache, type DekCache, type DekCacheOptions } from "./dek-cache";
+export {
+  createEnvMasterKeyProvider,
+  type EnvMasterKeyProviderOptions,
+  type Keyring,
+} from "./env-master-key-provider";
+export { decryptValue, encryptValue } from "./envelope";
+export { assertNoSecretLeak } from "./leak-guard";
+export { rewrapDek } from "./rotation";
+export {
+  createSecret,
+  type Envelope,
+  isSecret,
+  type MasterKeyProvider,
+  type Secret,
+  type SecretAuditContext,
+  type SecretKeyRef,
+  type SecretsContext,
+} from "./types";

package/src/secrets/leak-guard.ts

@@ -0,0 +1,87 @@
+// Response-leak guard. Walks a handler-result tree and throws the moment it
+// finds a Secret<> branded value — the dispatcher calls this after every
+// handler returns, so accidentally including a plaintext secret in the
+// response body becomes a runtime error at the handler boundary rather
+// than a silent exfiltration to the client.
+
+import { InternalError } from "../errors";
+import { isSecret } from "./types";
+
+// Maximum depth the walker descends. A legitimate result tree is rarely
+// deeper than a few levels; the cap is a safety net against cyclic or
+// pathologically-deep user input smuggled into a response.
+const MAX_DEPTH = 12;
+
+export function assertNoSecretLeak(value: unknown, path = "$", depth = 0): void {
+  // skip: nothing to walk at null/undefined leaves.
+  if (value === null || value === undefined) return;
+
+  if (isSecret(value)) {
+    throw new InternalError({
+      message:
+        `[secrets] Secret<> leaked into response at ${path}. ` +
+        "Feature code must call .reveal() and use the plaintext in an " +
+        "external call (SMTP, HTTP header, etc.) — never return the branded " +
+        "value, even unwrapped, unless you've stripped it from the response first.",
+    });
+  }
+
+  // skip: hit the recursion cap. Cyclic or pathologically-deep input is
+  // more likely than a legitimate 12-level-deep secret — trade coverage
+  // for termination guarantees.
+  if (depth >= MAX_DEPTH) return;
+
+  const t = typeof value;
+  // skip: primitives already handled by the isSecret check above — strings,
+  // numbers, booleans can't hold a brand.
+  if (t !== "object") return;
+
+  // Map and Set get walked through their entries — a feature could legitimately
+  // build either, and a custom toJSON could expand them onto the wire.
+  // JSON.stringify-by-default produces "{}" for both, which would mask the
+  // leak silently; we'd rather throw at the boundary than rely on that
+  // accident.
+  if (value instanceof Map) {
+    let i = 0;
+    for (const [k, v] of value) {
+      assertNoSecretLeak(k, `${path}.<map[${i}].key>`, depth + 1);
+      assertNoSecretLeak(v, `${path}.<map[${i}].val>`, depth + 1);
+      i++;
+    }
+    // skip: map fully walked, nothing else at this level.
+    return;
+  }
+  if (value instanceof Set) {
+    let i = 0;
+    for (const v of value) {
+      assertNoSecretLeak(v, `${path}.<set[${i}]>`, depth + 1);
+      i++;
+    }
+    // skip: set fully walked, nothing else at this level.
+    return;
+  }
+
+  // Skip remaining class instances we can't introspect safely (Date, Buffer,
+  // Temporal.Instant, custom domain classes, etc.). Plain objects have
+  // Object.prototype or null prototype — that's what handler responses
+  // serialize to JSON from.
+  const proto = Object.getPrototypeOf(value);
+  // skip: non-plain object (class instance). Brand check at entry already
+  // verified it's not a Secret<>; anything else is opaque to us.
+  if (proto !== null && proto !== Object.prototype && !Array.isArray(value)) {
+    return;
+  }
+
+  if (Array.isArray(value)) {
+    for (let i = 0; i < value.length; i++) {
+      assertNoSecretLeak(value[i], `${path}[${i}]`, depth + 1);
+    }
+    // skip: array fully walked, nothing else at this level.
+    return;
+  }
+
+  for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+    // @cast-boundary recursive-walk
+    assertNoSecretLeak(v, `${path}.${k}`, depth + 1);
+  }
+}