@cosmicdrift/kumiko-framework 0.327.0 → 0.328.1

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

@@ -1,149 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { randomBytes } from "node:crypto";
-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

@@ -1,137 +0,0 @@
-// 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 { KeyScope, 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. The cache key is
-  // (encryptedDek, kekVersion) — scope is only forwarded to the provider;
-  // encryptedDek bytes are unique per value, so scoped providers can't
-  // collide on the key either.
-  unwrapDek(
-    encryptedDek: Buffer,
-    kekVersion: number,
-    provider: MasterKeyProvider,
-    scope?: KeyScope,
-  ): 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;
-};
-
-// Wrap a provider so its unwrapDek goes through the cache. Callers keep the
-// full MasterKeyProvider contract without knowing about caching —
-// decryptValue handles crypto, the cache handles cost.
-export function withDekCache(provider: MasterKeyProvider, cache: DekCache): MasterKeyProvider {
-  return {
-    wrapDek: (dek, scope) => provider.wrapDek(dek, scope),
-    unwrapDek: (encryptedDek, version, scope) =>
-      cache.unwrapDek(encryptedDek, version, provider, scope),
-    currentVersion: () => provider.currentVersion(),
-    isAvailable: () => provider.isAvailable(),
-  };
-}
-
-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, scope) {
-      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, scope);
-      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/derive-purpose-secret.ts

@@ -1,17 +0,0 @@
-import { hkdfSync } from "node:crypto";
-
-// HKDF turns one master secret into an independent secret per purpose, so
-// a token-signing key for MFA setup can't forge a deletion token and
-// neither can be walked back to the master. `purpose` is a domain
-// separator, not a label — changing it invalidates every previously
-// issued token for that purpose; version it ("mfa-setup-token-v1") to
-// rotate one purpose deliberately.
-export function derivePurposeSecret(masterSecret: string, purpose: string): string {
-  if (!masterSecret) {
-    throw new Error("derivePurposeSecret: masterSecret must not be empty.");
-  }
-  if (!purpose) {
-    throw new Error("derivePurposeSecret: purpose must not be empty — it is the domain separator.");
-  }
-  return Buffer.from(hkdfSync("sha256", masterSecret, "", purpose, 32)).toString("hex");
-}

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

@@ -1,162 +0,0 @@
-// 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-cipher.ts

@@ -1,53 +0,0 @@
-// String-in/string-out envelope encryption for TEXT-column stores (config
-// values, entity fields). The stored string is JSON of StoredEnvelope; the
-// kekVersion inside makes every value rotatable via the MasterKeyProvider
-// keyring.
-
-import type { EnvelopeCipher } from "@cosmicdrift/kumiko-types/envelope-cipher-types";
-import { InternalError } from "../errors/classes";
-import type { DekCache } from "./dek-cache";
-import { createDekCache, withDekCache } from "./dek-cache";
-import { decryptValue, encryptValue } from "./envelope";
-import { decodeStoredEnvelope, encodeStoredEnvelope, isStoredEnvelope } from "./stored-envelope";
-import type { MasterKeyProvider } from "./types";
-
-export type { EnvelopeCipher } from "@cosmicdrift/kumiko-types/envelope-cipher-types";
-
-export type EnvelopeCipherOptions = {
-  // Shared DEK cache — pass the app-wide instance so config/entity reads
-  // amortise KEK unwraps together with ctx.secrets.
-  readonly dekCache?: DekCache;
-};
-
-export function createEnvelopeCipher(
-  provider: MasterKeyProvider,
-  opts: EnvelopeCipherOptions = {},
-): EnvelopeCipher {
-  const cached = withDekCache(provider, opts.dekCache ?? createDekCache());
-
-  return {
-    async encrypt(plaintext, scope) {
-      const envelope = await encryptValue(plaintext, provider, scope);
-      return JSON.stringify(encodeStoredEnvelope(envelope));
-    },
-
-    async decrypt(stored, scope) {
-      let parsed: unknown;
-      try {
-        parsed = JSON.parse(stored);
-      } catch {
-        throw new InternalError({
-          message: "[envelope-cipher] stored value is not valid JSON",
-          i18nKey: "secrets.errors.envelope_malformed",
-        });
-      }
-      if (!isStoredEnvelope(parsed)) {
-        throw new InternalError({
-          message: "[envelope-cipher] stored JSON is not a StoredEnvelope",
-          i18nKey: "secrets.errors.envelope_malformed",
-        });
-      }
-      return decryptValue(decodeStoredEnvelope(parsed), cached, scope);
-    },
-  };
-}

package/src/secrets/envelope.ts

@@ -1,57 +0,0 @@
-// 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, KeyScope, 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,
-  scope?: KeyScope,
-): 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, scope);
-    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,
-  scope?: KeyScope,
-): Promise<string> {
-  const dek = await provider.unwrapDek(envelope.encryptedDek, envelope.kekVersion, scope);
-  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

@@ -1,33 +0,0 @@
-export { createDekCache, type DekCache, type DekCacheOptions, withDekCache } from "./dek-cache";
-export { derivePurposeSecret } from "./derive-purpose-secret";
-export {
-  createEnvMasterKeyProvider,
-  type EnvMasterKeyProviderOptions,
-  type Keyring,
-} from "./env-master-key-provider";
-export { decryptValue, encryptValue } from "./envelope";
-export {
-  createEnvelopeCipher,
-  type EnvelopeCipher,
-  type EnvelopeCipherOptions,
-} from "./envelope-cipher";
-export { assertNoSecretLeak } from "./leak-guard";
-export { rewrapDek } from "./rotation";
-export {
-  decodeStoredEnvelope,
-  encodeStoredEnvelope,
-  isStoredEnvelope,
-  type StoredEnvelope,
-} from "./stored-envelope";
-export {
-  type ContainsSecret,
-  createSecret,
-  type Envelope,
-  isSecret,
-  type KeyScope,
-  type MasterKeyProvider,
-  type Secret,
-  type SecretAuditContext,
-  type SecretKeyRef,
-  type SecretsContext,
-} from "./types";