@crewhaus/audit-encryption 0.1.1 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewhaus/audit-encryption",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "description": "Envelope encryption for hash-chained audit records: per-tenant DEK wrapped by KEK from @crewhaus/secrets-manager (Section 39)",
   "main": "src/index.ts",
@@ -12,15 +12,15 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/audit-log": "0.1.1",
-    "@crewhaus/errors": "0.1.1",
-    "@crewhaus/secrets-manager": "0.1.1"
+    "@crewhaus/audit-log": "0.1.3",
+    "@crewhaus/errors": "0.1.3",
+    "@crewhaus/secrets-manager": "0.1.3"
   },
   "license": "Apache-2.0",
   "author": {
     "name": "Max Meier",
-    "email": "max@studiomax.io",
-    "url": "https://studiomax.io"
+    "email": "max@crewhaus.ai",
+    "url": "https://crewhaus.ai"
   },
   "repository": {
     "type": "git",
@@ -32,12 +32,7 @@
     "url": "https://github.com/crewhaus/factory/issues"
   },
   "publishConfig": {
-    "access": "restricted"
+    "access": "public"
   },
-  "files": [
-    "src",
-    "README.md",
-    "LICENSE",
-    "NOTICE"
-  ]
+  "files": ["src", "README.md", "LICENSE", "NOTICE"]
 }

package/src/index.test.ts

@@ -1,6 +1,21 @@
-import { describe, expect, test } from "bun:test";
+import { afterAll, describe, expect, test } from "bun:test";
+import { createCipheriv, createHash, randomBytes } from "node:crypto";
+import { existsSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { createEnvVarBackend, createSecrets } from "@crewhaus/secrets-manager";
-import { AuditEncryptionError, InMemoryDekStore, createAuditEncryption } from "./index";
+import {
+  AuditEncryptionError,
+  type EncryptedRecord,
+  InMemoryDekStore,
+  _decryptBytesForTest,
+  _deriveKekKeyForTest,
+  _deriveKekKeyLegacyForTest,
+  _encryptBytesForTest,
+  createAuditEncryption,
+  createFileDekStore,
+  staticKekProvider,
+} from "./index";
 
 function setKek(name: string, value: string): void {
   process.env[name] = value;
@@ -164,3 +179,653 @@ describe("DekStore plumbing", () => {
     expect(out?.length).toBe(32);
   });
 });
+
+describe("#163 — salted, stretched KEK derivation (CWE-916)", () => {
+  test("records carry a persisted scrypt salt and decrypt using it", async () => {
+    const enc = await buildEncryption("passphrase-shaped-kek");
+    const record = await enc.encryptPayload({ x: 1 }, "tenant-a");
+    // Salt is persisted on the record (16 bytes => 32 hex chars).
+    expect(record.kekSalt).toMatch(/^[a-f0-9]{32}$/);
+    // The wrapping key is NOT a bare SHA-256 of the KEK: tampering with
+    // the persisted salt must break unwrapping (proves the salt feeds
+    // the derivation rather than being decorative).
+    const wrongSalt = { ...record, kekSalt: "00".repeat(16) };
+    await expect(enc.decryptPayload(wrongSalt)).rejects.toThrow();
+    // With the genuine salt, the record round-trips.
+    expect(await enc.decryptPayload(record)).toEqual({ x: 1 });
+  });
+
+  test("salt is fresh per record", async () => {
+    const enc = await buildEncryption();
+    const a = await enc.encryptPayload({ x: 1 }, "tenant-a");
+    const b = await enc.encryptPayload({ x: 1 }, "tenant-a");
+    expect(a.kekSalt).not.toBe(b.kekSalt);
+  });
+
+  test("legacy unsalted-SHA-256 records still decrypt (back-compat)", async () => {
+    // Hand-build a record in the pre-migration format: DEK wrapped under a
+    // bare SHA-256 of the KEK, with no `kekSalt` field.
+    const kekValue = "legacy-kek-value-123456";
+    setKek("KEK_TEST", kekValue);
+    const secrets = createSecrets({ backend: createEnvVarBackend() });
+    const store = new InMemoryDekStore();
+    const dek = randomBytes(32);
+    await store.set("tenant-legacy", dek);
+    const legacyKekKey = createHash("sha256").update(kekValue).digest();
+
+    const payloadIv = randomBytes(12);
+    const pc = createCipheriv("aes-256-gcm", dek, payloadIv);
+    const encryptedPayload = Buffer.concat([
+      pc.update(Buffer.from(JSON.stringify({ legacy: true }), "utf8")),
+      pc.final(),
+    ]);
+    const payloadTag = pc.getAuthTag();
+
+    const dekIv = randomBytes(12);
+    const wc = createCipheriv("aes-256-gcm", legacyKekKey, dekIv);
+    const wrappedDek = Buffer.concat([wc.update(dek), wc.final()]);
+    const wrappedTag = wc.getAuthTag();
+
+    const legacyRecord: EncryptedRecord = {
+      tenantId: "tenant-legacy",
+      kekRef: "kek:KEK_TEST:v1", // the ref createAuditEncryption assigns at init
+      dekRef: "dek:tenant-legacy:v1",
+      // no kekSalt — the migration's tell-tale that legacy derivation applies
+      iv: payloadIv.toString("hex"),
+      tag: payloadTag.toString("hex"),
+      encryptedPayload: encryptedPayload.toString("hex"),
+      wrappedDek: wrappedDek.toString("hex"),
+      wrappedDekIv: dekIv.toString("hex"),
+      wrappedDekTag: wrappedTag.toString("hex"),
+    };
+
+    const enc = await createAuditEncryption({ secrets, kekName: "KEK_TEST", dekStore: store });
+    expect(await enc.decryptPayload(legacyRecord)).toEqual({ legacy: true });
+  });
+});
+
+describe("#164 — DEK versioning + rotation re-keys (CWE-323)", () => {
+  test("a record encrypted before rotateKek still decrypts after", async () => {
+    const store = new InMemoryDekStore();
+    setKek("KEK_TEST", "kek-v1-secret-12345678");
+    const secrets = createSecrets({ backend: createEnvVarBackend() });
+    const enc = await createAuditEncryption({ secrets, kekName: "KEK_TEST", dekStore: store });
+
+    const before = await enc.encryptPayload({ era: "v1" }, "tenant-a");
+    expect(before.kekRef).toBe("kek:KEK_TEST:v1");
+
+    await enc.rotateKek("kek-v2-secret-87654321", "kek:KEK_TEST:v2");
+    expect(enc.kekRef).toBe("kek:KEK_TEST:v2");
+
+    // Historical record (sealed under the now-superseded KEK) still decrypts.
+    expect(await enc.decryptPayload(before)).toEqual({ era: "v1" });
+
+    // And new writes use the new KEK + a freshly-minted DEK version.
+    const after = await enc.encryptPayload({ era: "v2" }, "tenant-a");
+    expect(after.kekRef).toBe("kek:KEK_TEST:v2");
+    expect(await enc.decryptPayload(after)).toEqual({ era: "v2" });
+  });
+
+  test("rotateKek mints a fresh DEK version per tenant", async () => {
+    const store = new InMemoryDekStore();
+    setKek("KEK_TEST", "kek-v1-secret-12345678");
+    const secrets = createSecrets({ backend: createEnvVarBackend() });
+    const enc = await createAuditEncryption({ secrets, kekName: "KEK_TEST", dekStore: store });
+
+    const v1a = await enc.encryptPayload({ x: 1 }, "tenant-a");
+    const v1b = await enc.encryptPayload({ x: 1 }, "tenant-b");
+    expect(v1a.dekRef).toBe("dek:tenant-a:v1");
+    expect(v1b.dekRef).toBe("dek:tenant-b:v1");
+
+    await enc.rotateKek("kek-v2-secret-87654321", "kek:KEK_TEST:v2");
+
+    const v2a = await enc.encryptPayload({ x: 1 }, "tenant-a");
+    const v2b = await enc.encryptPayload({ x: 1 }, "tenant-b");
+    expect(v2a.dekRef).toBe("dek:tenant-a:v2");
+    expect(v2b.dekRef).toBe("dek:tenant-b:v2");
+
+    // The new DEK is genuinely different material (different wrapped DEK
+    // even accounting for the fresh salt).
+    expect(v2a.wrappedDek).not.toBe(v1a.wrappedDek);
+  });
+
+  test("DEK rolls to a new version once the per-DEK record threshold is hit", async () => {
+    const store = new InMemoryDekStore();
+    setKek("KEK_TEST", "kek-secret-12345678");
+    const secrets = createSecrets({ backend: createEnvVarBackend() });
+    const enc = await createAuditEncryption({
+      secrets,
+      kekName: "KEK_TEST",
+      dekStore: store,
+      maxRecordsPerDek: 2,
+    });
+
+    const r1 = await enc.encryptPayload({ n: 1 }, "tenant-a");
+    const r2 = await enc.encryptPayload({ n: 2 }, "tenant-a");
+    const r3 = await enc.encryptPayload({ n: 3 }, "tenant-a");
+    // First two records share DEK v1; the third rolls to v2.
+    expect(r1.dekRef).toBe("dek:tenant-a:v1");
+    expect(r2.dekRef).toBe("dek:tenant-a:v1");
+    expect(r3.dekRef).toBe("dek:tenant-a:v2");
+    // All three still decrypt.
+    expect(await enc.decryptPayload(r1)).toEqual({ n: 1 });
+    expect(await enc.decryptPayload(r2)).toEqual({ n: 2 });
+    expect(await enc.decryptPayload(r3)).toEqual({ n: 3 });
+  });
+
+  test("decrypt throws if no KEK material is retained for the record's kekRef", async () => {
+    const enc = await buildEncryption();
+    const record = await enc.encryptPayload({ x: 1 }, "tenant-a");
+    const orphaned = { ...record, kekRef: "kek:KEK_TEST:unknown-9999" };
+    await expect(enc.decryptPayload(orphaned)).rejects.toThrow(/no KEK material retained/);
+  });
+});
+
+describe("#163/#164 follow-up — persistent FileDekStore across restart", () => {
+  const tmpDirs: string[] = [];
+  function freshDir(): string {
+    const d = mkdtempSync(join(tmpdir(), "audit-enc-dek-"));
+    tmpDirs.push(d);
+    return d;
+  }
+  afterAll(() => {
+    for (const d of tmpDirs) rmSync(d, { recursive: true, force: true });
+  });
+
+  const V1 = "kek-v1-secret-12345678";
+  const V2 = "kek-v2-secret-87654321";
+  const V1_REF = "kek:KEK_TEST:v1";
+  const V2_REF = "kek:KEK_TEST:v2";
+
+  test("FileDekStore is a drop-in DekStore: encrypt + decrypt round-trip", async () => {
+    const dir = freshDir();
+    setKek("KEK_TEST", V1);
+    const secrets = createSecrets({ backend: createEnvVarBackend() });
+    const store = createFileDekStore(dir, staticKekProvider({ kekRef: V1_REF, kekValue: V1 }));
+    const enc = await createAuditEncryption({ secrets, kekName: "KEK_TEST", dekStore: store });
+    const rec = await enc.encryptPayload({ event: "x" }, "tenant-a");
+    expect(await enc.decryptPayload(rec)).toEqual({ event: "x" });
+    // The tenant's DEK file exists on disk after the first write.
+    expect(existsSync(join(dir, "dek-tenant-a.json"))).toBe(true);
+  });
+
+  test("persisted DEK file is wrapped (no raw key bytes, no KEK value) and 0o600", async () => {
+    const dir = freshDir();
+    setKek("KEK_TEST", V1);
+    const secrets = createSecrets({ backend: createEnvVarBackend() });
+    const store = createFileDekStore(dir, staticKekProvider({ kekRef: V1_REF, kekValue: V1 }));
+    const enc = await createAuditEncryption({ secrets, kekName: "KEK_TEST", dekStore: store });
+    await enc.encryptPayload({ event: "x" }, "tenant-a");
+
+    const file = join(dir, "dek-tenant-a.json");
+    // File is owner-read/write only (0o600). Mask to the permission bits.
+    expect(statSync(file).mode & 0o777).toBe(0o600);
+
+    const raw = readFileSync(file, "utf8");
+    const parsed = JSON.parse(raw);
+    // Persists ONLY the wrapped DEK + binding metadata — never the KEK value.
+    expect(parsed).toMatchObject({
+      version: 1,
+      uses: 1,
+      kekRef: V1_REF,
+      kekSalt: expect.stringMatching(/^[a-f0-9]{32}$/),
+      wrappedDek: expect.stringMatching(/^[a-f0-9]+$/),
+      wrappedDekIv: expect.stringMatching(/^[a-f0-9]{24}$/),
+      wrappedDekTag: expect.stringMatching(/^[a-f0-9]{32}$/),
+    });
+    expect(parsed).not.toHaveProperty("dek");
+    // The operator KEK value must not appear anywhere in the file.
+    expect(raw).not.toContain(V1);
+  });
+
+  test("FRESH engine on the same file store decrypts a pre-rotation record after restart", async () => {
+    const dir = freshDir();
+
+    // --- Process 1: boot under v1, encrypt, then rotate to v2. ---
+    setKek("KEK_TEST", V1);
+    const secrets1 = createSecrets({ backend: createEnvVarBackend() });
+    const store1 = createFileDekStore(dir, staticKekProvider({ kekRef: V1_REF, kekValue: V1 }));
+    const enc1 = await createAuditEncryption({
+      secrets: secrets1,
+      kekName: "KEK_TEST",
+      dekStore: store1,
+    });
+
+    const before = await enc1.encryptPayload({ era: "v1" }, "tenant-a");
+    expect(before.kekRef).toBe(V1_REF);
+    expect(before.dekRef).toBe("dek:tenant-a:v1");
+
+    await enc1.rotateKek(V2, V2_REF);
+    expect(enc1.kekRef).toBe(V2_REF);
+
+    // --- Simulate a restart: brand-new engine + store, same dir. The
+    // operator re-provides the current (post-rotation) KEK as the boot
+    // value and re-supplies the prior KEK as retained material. Nothing
+    // from process 1's in-memory state carries over. ---
+    setKek("KEK_TEST", V2); // backend now returns the rotated value
+    const secrets2 = createSecrets({ backend: createEnvVarBackend() });
+    const store2 = createFileDekStore(
+      dir,
+      staticKekProvider({ kekRef: V2_REF, kekValue: V2 }, [{ kekRef: V1_REF, kekValue: V1 }]),
+    );
+    const enc2 = await createAuditEncryption({
+      secrets: secrets2,
+      kekName: "KEK_TEST",
+      kekRef: V2_REF, // boot value is the v2 material; pin its true ref
+      retainedKeks: [{ kekRef: V1_REF, kekValue: V1 }],
+      dekStore: store2,
+    });
+
+    // The pre-rotation record (sealed under v1) still decrypts.
+    expect(await enc2.decryptPayload(before)).toEqual({ era: "v1" });
+
+    // The DEK use-count + version survived the restart: the rotation in
+    // process 1 re-minted tenant-a to v2, and the fresh engine sees that
+    // (it does NOT reset to a fresh v1 DEK).
+    const after = await enc2.encryptPayload({ era: "v2" }, "tenant-a");
+    expect(after.kekRef).toBe(V2_REF);
+    expect(after.dekRef).toBe("dek:tenant-a:v2");
+    expect(await enc2.decryptPayload(after)).toEqual({ era: "v2" });
+  }, 20_000);
+
+  test("use-count survives restart (DEK does not roll prematurely)", async () => {
+    const dir = freshDir();
+    setKek("KEK_TEST", V1);
+
+    // Process 1: two writes against a maxRecordsPerDek of 3 (uses -> 2).
+    const secrets1 = createSecrets({ backend: createEnvVarBackend() });
+    const store1 = createFileDekStore(dir, staticKekProvider({ kekRef: V1_REF, kekValue: V1 }));
+    const enc1 = await createAuditEncryption({
+      secrets: secrets1,
+      kekName: "KEK_TEST",
+      dekStore: store1,
+      maxRecordsPerDek: 3,
+    });
+    const r1 = await enc1.encryptPayload({ n: 1 }, "tenant-a");
+    const r2 = await enc1.encryptPayload({ n: 2 }, "tenant-a");
+    expect(r1.dekRef).toBe("dek:tenant-a:v1");
+    expect(r2.dekRef).toBe("dek:tenant-a:v1");
+
+    // Restart: fresh engine + store on the same dir, same KEK. The use
+    // counter is read from disk (=2), so the 3rd write stays on v1 and the
+    // 4th rolls to v2 — proving the counter was not reset to 0.
+    const secrets2 = createSecrets({ backend: createEnvVarBackend() });
+    const store2 = createFileDekStore(dir, staticKekProvider({ kekRef: V1_REF, kekValue: V1 }));
+    const enc2 = await createAuditEncryption({
+      secrets: secrets2,
+      kekName: "KEK_TEST",
+      dekStore: store2,
+      maxRecordsPerDek: 3,
+    });
+    const r3 = await enc2.encryptPayload({ n: 3 }, "tenant-a");
+    const r4 = await enc2.encryptPayload({ n: 4 }, "tenant-a");
+    expect(r3.dekRef).toBe("dek:tenant-a:v1"); // 3rd use still fits v1
+    expect(r4.dekRef).toBe("dek:tenant-a:v2"); // 4th rolls — counter persisted
+
+    // All four records still decrypt under the persisted DEKs.
+    expect(await enc2.decryptPayload(r1)).toEqual({ n: 1 });
+    expect(await enc2.decryptPayload(r3)).toEqual({ n: 3 });
+    expect(await enc2.decryptPayload(r4)).toEqual({ n: 4 });
+  });
+
+  test("reading a DEK file without its KEK material throws a clear error", async () => {
+    const dir = freshDir();
+    setKek("KEK_TEST", V1);
+    const secrets = createSecrets({ backend: createEnvVarBackend() });
+    // Persist a DEK wrapped under v1...
+    const writeStore = createFileDekStore(dir, staticKekProvider({ kekRef: V1_REF, kekValue: V1 }));
+    const enc = await createAuditEncryption({
+      secrets,
+      kekName: "KEK_TEST",
+      dekStore: writeStore,
+    });
+    await enc.encryptPayload({ x: 1 }, "tenant-a");
+
+    // ...then try to read it with a provider that lacks v1 entirely.
+    const blindStore = createFileDekStore(dir, staticKekProvider({ kekRef: V2_REF, kekValue: V2 }));
+    await expect(blindStore.getEntry?.("tenant-a")).rejects.toThrow(/no KEK material for kekRef/);
+  });
+
+  test("createFileDekStore rejects an empty rootDir", () => {
+    expect(() =>
+      createFileDekStore("", staticKekProvider({ kekRef: V1_REF, kekValue: V1 })),
+    ).toThrow(/rootDir is required/);
+  });
+
+  test("FileDekStore.tenants lists persisted tenants for rotation", async () => {
+    const dir = freshDir();
+    setKek("KEK_TEST", V1);
+    const secrets = createSecrets({ backend: createEnvVarBackend() });
+    const store = createFileDekStore(dir, staticKekProvider({ kekRef: V1_REF, kekValue: V1 }));
+    const enc = await createAuditEncryption({ secrets, kekName: "KEK_TEST", dekStore: store });
+    await enc.encryptPayload({ x: 1 }, "tenant-a");
+    await enc.encryptPayload({ x: 1 }, "tenant-b");
+    const tenants = await store.tenants?.();
+    expect([...(tenants ?? [])].sort()).toEqual(["tenant-a", "tenant-b"]);
+  });
+});
+
+describe("FileDekStore get/set (non-versioned DekStore surface)", () => {
+  const tmpDirs: string[] = [];
+  function freshDir(): string {
+    const d = mkdtempSync(join(tmpdir(), "audit-enc-getset-"));
+    tmpDirs.push(d);
+    return d;
+  }
+  afterAll(() => {
+    for (const d of tmpDirs) rmSync(d, { recursive: true, force: true });
+  });
+
+  const V1 = "kek-v1-secret-12345678";
+  const V1_REF = "kek:KEK_TEST:v1";
+
+  test("get returns undefined for an unknown tenant", async () => {
+    const dir = freshDir();
+    const store = createFileDekStore(dir, staticKekProvider({ kekRef: V1_REF, kekValue: V1 }));
+    expect(await store.get("nobody")).toBeUndefined();
+  });
+
+  test("set then get round-trips the raw DEK through wrap/unwrap", async () => {
+    const dir = freshDir();
+    const store = createFileDekStore(dir, staticKekProvider({ kekRef: V1_REF, kekValue: V1 }));
+    const dek = randomBytes(32);
+    await store.set("tenant-a", dek);
+    const got = await store.get("tenant-a");
+    expect(got).toBeDefined();
+    // The plain get/set surface persists+restores the exact DEK bytes.
+    expect(Buffer.from(got as Buffer).equals(dek)).toBe(true);
+    // Persisted as version 1 with a reset use-count.
+    const entry = await store.getEntry?.("tenant-a");
+    expect(entry?.version).toBe(1);
+    expect(entry?.uses).toBe(0);
+  });
+
+  test("set preserves the existing version on overwrite (prev.version branch)", async () => {
+    const dir = freshDir();
+    const store = createFileDekStore(dir, staticKekProvider({ kekRef: V1_REF, kekValue: V1 }));
+    // Seed a v3 entry via the versioned surface...
+    await store.setEntry?.("tenant-a", { dek: randomBytes(32), version: 3, uses: 7 });
+    // ...then a plain set must keep version 3 (prev?.version ?? 1 -> 3) and
+    // reset uses to 0.
+    const replacement = randomBytes(32);
+    await store.set("tenant-a", replacement);
+    const entry = await store.getEntry?.("tenant-a");
+    expect(entry?.version).toBe(3);
+    expect(entry?.uses).toBe(0);
+    expect(Buffer.from(entry?.dek as Buffer).equals(replacement)).toBe(true);
+  });
+});
+
+describe("get/set-only DekStore (engine fallback to non-versioned surface)", () => {
+  // A store exposing ONLY get/set — no getEntry/setEntry/tenants. Exercises
+  // the engine's readEntry/writeEntry fallbacks and the rotateKek no-op when
+  // the store cannot iterate tenants.
+  class MinimalDekStore {
+    readonly map = new Map<string, Buffer>();
+    async get(tenantId: string): Promise<Buffer | undefined> {
+      const v = this.map.get(tenantId);
+      return v === undefined ? undefined : Buffer.from(v);
+    }
+    async set(tenantId: string, dek: Buffer): Promise<void> {
+      this.map.set(tenantId, Buffer.from(dek));
+    }
+  }
+
+  test("encrypt+decrypt round-trips and the DEK is treated as version 1", async () => {
+    setKek("KEK_TEST", "kek-secret-12345678");
+    const secrets = createSecrets({ backend: createEnvVarBackend() });
+    const store = new MinimalDekStore();
+    const enc = await createAuditEncryption({ secrets, kekName: "KEK_TEST", dekStore: store });
+    const rec = await enc.encryptPayload({ x: 1 }, "tenant-a");
+    expect(rec.dekRef).toBe("dek:tenant-a:v1");
+    expect(await enc.decryptPayload(rec)).toEqual({ x: 1 });
+    // The engine persisted a 32-byte DEK via the plain set surface.
+    expect((await store.get("tenant-a"))?.length).toBe(32);
+  });
+
+  test("a stored DEK of the wrong length is treated as missing and re-minted", async () => {
+    setKek("KEK_TEST", "kek-secret-12345678");
+    const secrets = createSecrets({ backend: createEnvVarBackend() });
+    const store = new MinimalDekStore();
+    // Pre-seed a malformed (too-short) DEK: readEntry must reject it.
+    store.map.set("tenant-a", Buffer.from("short"));
+    const enc = await createAuditEncryption({ secrets, kekName: "KEK_TEST", dekStore: store });
+    const rec = await enc.encryptPayload({ x: 1 }, "tenant-a");
+    expect(rec.dekRef).toBe("dek:tenant-a:v1");
+    // It overwrote the malformed value with a real 32-byte DEK.
+    expect((await store.get("tenant-a"))?.length).toBe(32);
+    expect(await enc.decryptPayload(rec)).toEqual({ x: 1 });
+  });
+
+  test("rotateKek is a no-op on the store when tenants() is unavailable", async () => {
+    setKek("KEK_TEST", "kek-v1-secret-12345678");
+    const secrets = createSecrets({ backend: createEnvVarBackend() });
+    const store = new MinimalDekStore();
+    const enc = await createAuditEncryption({ secrets, kekName: "KEK_TEST", dekStore: store });
+    const before = await enc.encryptPayload({ era: "v1" }, "tenant-a");
+    // No tenants() -> rotation cannot re-mint per tenant, but must not throw
+    // and historical records must still decrypt.
+    await enc.rotateKek("kek-v2-secret-87654321", "kek:KEK_TEST:v2");
+    expect(enc.kekRef).toBe("kek:KEK_TEST:v2");
+    expect(await enc.decryptPayload(before)).toEqual({ era: "v1" });
+    const after = await enc.encryptPayload({ era: "v2" }, "tenant-a");
+    expect(after.kekRef).toBe("kek:KEK_TEST:v2");
+    expect(await enc.decryptPayload(after)).toEqual({ era: "v2" });
+  });
+});
+
+describe("auto-subscribed rotation via secrets.onRotation", () => {
+  test("a rotation event for the configured KEK re-keys and stays decryptable", async () => {
+    setKek("KEK_TEST", "kek-v1-secret-12345678");
+    const store = new InMemoryDekStore();
+    const secrets = createSecrets({ backend: createEnvVarBackend() });
+    const enc = await createAuditEncryption({ secrets, kekName: "KEK_TEST", dekStore: store });
+
+    const before = await enc.encryptPayload({ era: "v1" }, "tenant-a");
+    expect(before.kekRef).toBe("kek:KEK_TEST:v1");
+
+    // Firing the backend rotation drives the engine's onRotation handler
+    // (no direct rotateKek call). Await it so the async handler settles.
+    await secrets.rotate("KEK_TEST", { newValue: "kek-v2-secret-87654321" });
+
+    // The engine adopted the rotated value: its kekRef now carries the
+    // `kek:KEK_TEST:<rotatedAt>` shape the handler mints.
+    expect(enc.kekRef).toMatch(/^kek:KEK_TEST:\d+$/);
+    expect(enc.kekRef).not.toBe("kek:KEK_TEST:v1");
+
+    // Pre-rotation record still decrypts; new writes use the rotated KEK.
+    expect(await enc.decryptPayload(before)).toEqual({ era: "v1" });
+    const after = await enc.encryptPayload({ era: "v2" }, "tenant-a");
+    expect(after.kekRef).toBe(enc.kekRef);
+    expect(await enc.decryptPayload(after)).toEqual({ era: "v2" });
+  });
+
+  test("a failing event-driven rotation does not surface an unhandled rejection", async () => {
+    // Regression: the onRotation handler used to fire-and-forget the re-key
+    // with a bare `void rotateInternal(...)`. If that promise rejected
+    // (e.g. a DEK-store failure mid-rotation), the rejection escaped as an
+    // unhandledRejection and could crash the host process. The handler now
+    // contains the rejection with `.catch`.
+    class ExplodingTenantsStore extends InMemoryDekStore {
+      override async tenants(): Promise<ReadonlyArray<string>> {
+        throw new Error("boom: tenants() unavailable during rotation");
+      }
+    }
+    setKek("KEK_TEST", "kek-v1-secret-12345678");
+    const secrets = createSecrets({ backend: createEnvVarBackend() });
+    const store = new ExplodingTenantsStore();
+    const enc = await createAuditEncryption({ secrets, kekName: "KEK_TEST", dekStore: store });
+    const before = await enc.encryptPayload({ era: "v1" }, "tenant-a");
+
+    const rejections: unknown[] = [];
+    const onUnhandled = (reason: unknown): void => {
+      rejections.push(reason);
+    };
+    process.on("unhandledRejection", onUnhandled);
+    try {
+      // Drive the event-rotation; rotateInternal will reject inside tenants().
+      await secrets.rotate("KEK_TEST", { newValue: "kek-v2-secret-87654321" });
+      // Let any unhandled rejection surface on the macrotask queue.
+      await new Promise((r) => setTimeout(r, 10));
+    } finally {
+      process.off("unhandledRejection", onUnhandled);
+    }
+
+    expect(rejections).toHaveLength(0);
+    // The synchronous half of the rotation still adopted the new KEK, and
+    // the pre-rotation record remains decryptable.
+    expect(enc.kekRef).toMatch(/^kek:KEK_TEST:\d+$/);
+    expect(await enc.decryptPayload(before)).toEqual({ era: "v1" });
+  });
+
+  test("a rotation event for a different secret name is ignored", async () => {
+    setKek("KEK_TEST", "kek-v1-secret-12345678");
+    setKek("OTHER_SECRET", "unrelated-value-000000");
+    const secrets = createSecrets({ backend: createEnvVarBackend() });
+    const enc = await createAuditEncryption({ secrets, kekName: "KEK_TEST" });
+    const refBefore = enc.kekRef;
+    // Rotating a secret this engine does not care about must not change its
+    // KEK (exercises the name-guard early return in the handler).
+    await secrets.rotate("OTHER_SECRET", { newValue: "rotated-unrelated-1111" });
+    expect(enc.kekRef).toBe(refBefore);
+    const rec = await enc.encryptPayload({ x: 1 }, "tenant-a");
+    expect(rec.kekRef).toBe(refBefore);
+    expect(await enc.decryptPayload(rec)).toEqual({ x: 1 });
+  });
+});
+
+describe("maxRecordsPerDek guard", () => {
+  test("a non-positive maxRecordsPerDek falls back to the default (no premature roll)", async () => {
+    setKek("KEK_TEST", "kek-secret-12345678");
+    const secrets = createSecrets({ backend: createEnvVarBackend() });
+    const store = new InMemoryDekStore();
+    // 0 is not > 0, so the default threshold applies and the DEK does not
+    // roll on every record.
+    const enc = await createAuditEncryption({
+      secrets,
+      kekName: "KEK_TEST",
+      dekStore: store,
+      maxRecordsPerDek: 0,
+    });
+    const a = await enc.encryptPayload({ n: 1 }, "tenant-a");
+    const b = await enc.encryptPayload({ n: 2 }, "tenant-a");
+    expect(a.dekRef).toBe("dek:tenant-a:v1");
+    expect(b.dekRef).toBe("dek:tenant-a:v1");
+  });
+});
+
+describe("explicit kekRef option", () => {
+  test("a custom boot kekRef is stamped on records and used for decrypt", async () => {
+    setKek("KEK_TEST", "kek-secret-12345678");
+    const secrets = createSecrets({ backend: createEnvVarBackend() });
+    const enc = await createAuditEncryption({
+      secrets,
+      kekName: "KEK_TEST",
+      kekRef: "kek:KEK_TEST:custom-boot",
+    });
+    expect(enc.kekRef).toBe("kek:KEK_TEST:custom-boot");
+    const rec = await enc.encryptPayload({ x: 1 }, "tenant-a");
+    expect(rec.kekRef).toBe("kek:KEK_TEST:custom-boot");
+    expect(await enc.decryptPayload(rec)).toEqual({ x: 1 });
+  });
+
+  test("a retained KEK under the boot ref does not shadow the boot value", async () => {
+    // Boot KEK occupies kek:KEK_TEST:v1; a stale retained entry under the
+    // same ref must be ignored (the !has guard in createAuditEncryption).
+    setKek("KEK_TEST", "real-boot-kek-12345678");
+    const secrets = createSecrets({ backend: createEnvVarBackend() });
+    const enc = await createAuditEncryption({
+      secrets,
+      kekName: "KEK_TEST",
+      retainedKeks: [{ kekRef: "kek:KEK_TEST:v1", kekValue: "stale-shadow-value-000" }],
+    });
+    // If the stale value had shadowed the boot value, decrypt would fail
+    // (different scrypt key). It round-trips because the boot value wins.
+    const rec = await enc.encryptPayload({ x: 1 }, "tenant-a");
+    expect(await enc.decryptPayload(rec)).toEqual({ x: 1 });
+  });
+});
+
+describe("decryptPayload — non-JSON plaintext", () => {
+  test("a record whose decrypted plaintext is not JSON throws AuditEncryptionError", async () => {
+    setKek("KEK_TEST", "kek-secret-12345678");
+    const secrets = createSecrets({ backend: createEnvVarBackend() });
+    const store = new InMemoryDekStore();
+    const enc = await createAuditEncryption({ secrets, kekName: "KEK_TEST", dekStore: store });
+
+    // Encrypt a real record to obtain a valid wrapped DEK + kekSalt, then
+    // hand-build a payload ciphertext over NON-JSON bytes under the same DEK
+    // so unwrap succeeds but JSON.parse fails.
+    const seed = await enc.encryptPayload({ ok: true }, "tenant-a");
+    const dek = (await store.get("tenant-a")) as Buffer;
+    const badIv = randomBytes(12);
+    const c = createCipheriv("aes-256-gcm", dek, badIv);
+    const ct = Buffer.concat([c.update(Buffer.from("not-json{", "utf8")), c.final()]);
+    const tag = c.getAuthTag();
+    const bad: EncryptedRecord = {
+      ...seed,
+      iv: badIv.toString("hex"),
+      tag: tag.toString("hex"),
+      encryptedPayload: ct.toString("hex"),
+    };
+    await expect(enc.decryptPayload(bad)).rejects.toThrow(/not valid JSON/);
+  });
+});
+
+describe("corrupt persisted DEK file", () => {
+  const tmpDirs: string[] = [];
+  function freshDir(): string {
+    const d = mkdtempSync(join(tmpdir(), "audit-enc-corrupt-"));
+    tmpDirs.push(d);
+    return d;
+  }
+  afterAll(() => {
+    for (const d of tmpDirs) rmSync(d, { recursive: true, force: true });
+  });
+
+  test("a non-JSON DEK file surfaces a clear AuditEncryptionError", async () => {
+    const dir = freshDir();
+    const V1 = "kek-v1-secret-12345678";
+    const V1_REF = "kek:KEK_TEST:v1";
+    const store = createFileDekStore(dir, staticKekProvider({ kekRef: V1_REF, kekValue: V1 }));
+    // Hand-write garbage into the tenant's DEK file.
+    writeFileSync(join(dir, "dek-tenant-a.json"), "{ this is not json", "utf8");
+    await expect(store.get("tenant-a")).rejects.toThrow(/corrupt DEK file/);
+    await expect(store.getEntry?.("tenant-a")).rejects.toThrow(/corrupt DEK file/);
+  });
+});
+
+describe("low-level crypto test seams", () => {
+  test("encryptBytes/decryptBytes round-trip", () => {
+    const key = randomBytes(32);
+    const iv = randomBytes(12);
+    const { ciphertext, tag } = _encryptBytesForTest(Buffer.from("hello world"), key, iv);
+    const out = _decryptBytesForTest(ciphertext, key, iv, tag);
+    expect(out.toString("utf8")).toBe("hello world");
+  });
+
+  test("deriveKekKey is salt-dependent and 32 bytes; legacy derivation is bare SHA-256", () => {
+    const salt = randomBytes(16);
+    const k1 = _deriveKekKeyForTest("kek-value", salt);
+    const k2 = _deriveKekKeyForTest("kek-value", randomBytes(16));
+    expect(k1.length).toBe(32);
+    // Different salt => different derived key.
+    expect(k1.equals(k2)).toBe(false);
+    const legacy = _deriveKekKeyLegacyForTest("kek-value");
+    expect(legacy.equals(createHash("sha256").update("kek-value").digest())).toBe(true);
+  });
+});
+
+describe("staticKekProvider", () => {
+  test("resolves current + retained, current wins on ref collision", () => {
+    const p = staticKekProvider({ kekRef: "kek:a:v2", kekValue: "current-value" }, [
+      { kekRef: "kek:a:v1", kekValue: "old-value" },
+      // A stale retained entry under the current ref must not shadow it.
+      { kekRef: "kek:a:v2", kekValue: "stale-value" },
+    ]);
+    expect(p.current()).toEqual({ kekRef: "kek:a:v2", kekValue: "current-value" });
+    expect(p.resolve("kek:a:v1")).toBe("old-value");
+    expect(p.resolve("kek:a:v2")).toBe("current-value");
+    expect(p.resolve("kek:a:unknown")).toBeUndefined();
+  });
+});

package/src/index.ts

@@ -5,7 +5,17 @@ import {
   createDecipheriv,
   createHash,
   randomBytes,
+  scryptSync,
 } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
 import { CrewhausError } from "@crewhaus/errors";
 import type { Secrets } from "@crewhaus/secrets-manager";
 
@@ -17,7 +27,7 @@ import type { Secrets } from "@crewhaus/secrets-manager";
  * Encryption Key (DEK); the DEK itself is encrypted ("wrapped") with
  * a Key Encryption Key (KEK) sourced from §27 `secrets-manager`. The
  * resulting record carries
- *   { tenantId, kekRef, dekRef, iv, tag, encryptedPayload }
+ *   { tenantId, kekRef, dekRef, kekSalt, iv, tag, encryptedPayload, ... }
  * and is verifiable + decryptable by any caller with the same KEK.
  *
  * Algorithms:
@@ -25,13 +35,25 @@ import type { Secrets } from "@crewhaus/secrets-manager";
  *     authenticated, so tampering with `encryptedPayload`, `iv`, or
  *     `tag` causes `decrypt` to throw — satisfies the §39 T8
  *     ciphertext-integrity requirement.
+ *   - The 32-byte AES wrapping key is derived from the KEK string via
+ *     scrypt (a salted, memory-hard KDF) with a per-record random salt.
+ *     This holds even when the KEK is a low-entropy passphrase: scrypt
+ *     stretches it and the persisted salt defeats precomputation
+ *     (CWE-916 — a bare unsalted hash would not). The salt is stored on
+ *     the record (`kekSalt`) so the same key can be re-derived at
+ *     unwrap time.
  *   - 12-byte (96-bit) IVs randomly generated per record.
  *
  * Key rotation:
- *   `secrets.onRotation(...)` triggers `rotateKek()` which re-wraps
- *   every cached DEK with the new KEK. Already-written records keep
- *   their `kekRef`, so old records still verify against the previous
- *   KEK if the secret backend retains it.
+ *   `secrets.onRotation(...)` triggers `rotateKek()` which mints a fresh
+ *   DEK version (`dek:<tenant>:vN+1`) for every tenant in the DEK store
+ *   and adopts the new KEK as current. The prior KEK *value* is retained
+ *   in-process keyed by its `kekRef`, so `decryptPayload` can re-derive
+ *   the wrapping key for historical records (which keep their original
+ *   `kekRef` + `kekSalt`) and still unwrap them (CWE-323 — without
+ *   retaining prior material, rotation would strand old records).
+ *   DEKs also roll automatically once a single version has wrapped more
+ *   than `maxRecordsPerDek` records.
  *
  * Layer R17. Pairs with `audit-log` (R-infra — wraps `append` /
  * `read`) and `secrets-manager` (§27 — KEK source).
@@ -51,6 +73,12 @@ export type EncryptedRecord = {
   readonly kekRef: string;
   /** Stable identifier for the DEK used to encrypt the payload. */
   readonly dekRef: string;
+  /**
+   * Per-record salt (hex) fed to the scrypt KEK-key derivation. Absent on
+   * legacy records written before the KDF migration; those fall back to
+   * the legacy unsalted-SHA-256 derivation for back-compat.
+   */
+  readonly kekSalt?: string;
   /** 96-bit GCM IV (24 hex chars). */
   readonly iv: string;
   /** 128-bit GCM auth tag (32 hex chars). */
@@ -69,40 +97,309 @@ export type AuditEncryptionOptions = {
   readonly secrets: Secrets;
   /** Name of the KEK in §27 secrets-manager. */
   readonly kekName: string;
+  /**
+   * Stable identifier for the *boot* KEK value. Defaults to
+   * `kek:<kekName>:v1`. This is the `kekRef` stamped on records sealed
+   * before the first in-process rotation, and the key under which the
+   * boot KEK is held in the retain-for-decrypt registry. After one or
+   * more rotations, a restarted process boots with the *latest* KEK
+   * value; pass that rotation's ref here so historical refs stay stable
+   * and the boot value is not mistaken for the original `:v1` material.
+   */
+  readonly kekRef?: string;
   /**
    * Optional persistent DEK store. If omitted, DEKs live in-memory
    * (process-local). Production should plug a tenant-scoped key store
-   * here (HSM, KMS, vault path).
+   * here (HSM, KMS, vault path) — see {@link createFileDekStore} for a
+   * file-backed implementation that survives restart.
    */
   readonly dekStore?: DekStore;
-  /** Test seam: deterministic IV generator. */
+  /**
+   * Prior KEK material to re-seed at boot, keyed by the `kekRef` it was
+   * minted under. The in-process KEK registry that {@link rotateKek}
+   * populates does not survive a restart, so a freshly-constructed engine
+   * can only unwrap records sealed under the *boot* KEK. Operators that
+   * have rotated must re-provide each superseded KEK here so historical
+   * records (which embed their original `kekRef`) keep decrypting after a
+   * restart (CWE-323). Values are never persisted by this package; the
+   * operator re-supplies them from the secret backend's history.
+   */
+  readonly retainedKeks?: ReadonlyArray<{ readonly kekRef: string; readonly kekValue: string }>;
+  /**
+   * Roll a tenant's DEK to a fresh version once it has wrapped this many
+   * records. Bounds the blast radius of any single DEK. Defaults to
+   * {@link DEFAULT_MAX_RECORDS_PER_DEK}.
+   */
+  readonly maxRecordsPerDek?: number;
+  /** Test seam: deterministic IV/salt generator. */
   readonly randomBytesImpl?: (n: number) => Buffer;
   /** Test seam: synthetic Date.now. */
   readonly now?: () => number;
 };
 
+/**
+ * Versioned DEK entry. `version` is the integer N behind the
+ * `dek:<tenant>:vN` ref; `uses` counts records encrypted under it so we
+ * can roll on the {@link AuditEncryptionOptions.maxRecordsPerDek}
+ * threshold.
+ */
+export type DekEntry = {
+  readonly dek: Buffer;
+  readonly version: number;
+  readonly uses: number;
+};
+
 export interface DekStore {
   get(tenantId: string): Promise<Buffer | undefined>;
   set(tenantId: string, dek: Buffer): Promise<void>;
+  /**
+   * Optional versioned read. When present it is preferred over `get`, and
+   * carries the version + usage counter needed for rotation. Stores that
+   * implement only `get`/`set` are treated as version 1 with no usage
+   * tracking (rotation still re-mints; the threshold is a no-op).
+   */
+  getEntry?(tenantId: string): Promise<DekEntry | undefined>;
+  /** Optional versioned write. Required for DEK versioning to take effect. */
+  setEntry?(tenantId: string, entry: DekEntry): Promise<void>;
+  /** Optional iteration over tenants holding a DEK. Required by `rotateKek`. */
+  tenants?(): Promise<ReadonlyArray<string>>;
 }
 
 export class InMemoryDekStore implements DekStore {
-  private readonly map = new Map<string, Buffer>();
+  private readonly map: Map<string, DekEntry>;
+  constructor() {
+    this.map = new Map<string, DekEntry>();
+  }
   async get(tenantId: string): Promise<Buffer | undefined> {
-    return this.map.get(tenantId);
+    return this.map.get(tenantId)?.dek;
   }
   async set(tenantId: string, dek: Buffer): Promise<void> {
-    this.map.set(tenantId, Buffer.from(dek));
+    const prev = this.map.get(tenantId);
+    this.map.set(tenantId, {
+      dek: Buffer.from(dek),
+      version: prev?.version ?? 1,
+      uses: 0,
+    });
+  }
+  async getEntry(tenantId: string): Promise<DekEntry | undefined> {
+    const entry = this.map.get(tenantId);
+    return entry === undefined ? undefined : { ...entry, dek: Buffer.from(entry.dek) };
+  }
+  async setEntry(tenantId: string, entry: DekEntry): Promise<void> {
+    this.map.set(tenantId, { ...entry, dek: Buffer.from(entry.dek) });
   }
+  async tenants(): Promise<ReadonlyArray<string>> {
+    return [...this.map.keys()];
+  }
+}
+
+/**
+ * Source of KEK material for {@link createFileDekStore}. The store wraps
+ * each DEK before it touches disk and unwraps on read, so it needs the
+ * *current* KEK to seal new writes and any *superseded* KEK (keyed by the
+ * `kekRef` recorded alongside the wrapped DEK) to open older files after
+ * a rotation. Operators construct this at boot from the same KEK(s) they
+ * re-provide to the engine — the store never persists the KEK value
+ * itself, only the wrapped DEK plus its `kekRef`.
+ */
+export interface KekProvider {
+  /** KEK used to wrap DEKs on write. */
+  current(): { readonly kekRef: string; readonly kekValue: string };
+  /** Resolve the KEK value a stored DEK was wrapped under, by `kekRef`. */
+  resolve(kekRef: string): string | undefined;
+}
+
+/**
+ * Build a {@link KekProvider} from a current KEK plus zero or more
+ * superseded KEKs (keyed by their original `kekRef`). After a rotation,
+ * the operator re-supplies the prior KEK(s) here so the file store can
+ * unwrap DEK files sealed under them.
+ */
+export function staticKekProvider(
+  current: { readonly kekRef: string; readonly kekValue: string },
+  retained: ReadonlyArray<{ readonly kekRef: string; readonly kekValue: string }> = [],
+): KekProvider {
+  const byRef = new Map<string, string>();
+  for (const { kekRef, kekValue } of retained) byRef.set(kekRef, kekValue);
+  // The current KEK takes precedence over any same-ref retained entry.
+  byRef.set(current.kekRef, current.kekValue);
+  return {
+    current: () => ({ kekRef: current.kekRef, kekValue: current.kekValue }),
+    resolve: (kekRef) => byRef.get(kekRef),
+  };
+}
+
+/** On-disk shape of a persisted DEK file. Never contains the raw DEK. */
+type PersistedDek = {
+  readonly version: number;
+  readonly uses: number;
+  /** KEK ref the DEK is wrapped under — selects the unwrap key on read. */
+  readonly kekRef: string;
+  /** Per-file scrypt salt (hex) for the wrapping-key derivation. */
+  readonly kekSalt: string;
+  /** Wrapped (encrypted) DEK + GCM IV/tag, all hex. */
+  readonly wrappedDek: string;
+  readonly wrappedDekIv: string;
+  readonly wrappedDekTag: string;
+};
+
+export type FileDekStoreOptions = {
+  /**
+   * Test seam: deterministic IV/salt generator for the wrapping step.
+   * Defaults to {@link randomBytes}.
+   */
+  readonly randomBytesImpl?: (n: number) => Buffer;
+};
+
+/**
+ * File-backed {@link DekStore} that persists DEKs so they (and their
+ * version + use-count) survive a restart. Each tenant's DEK lives in
+ * `<rootDir>/dek-<tenant>.json` written at mode `0o600`.
+ *
+ * SECURITY: the raw DEK is **never** written to disk. It is wrapped with
+ * the {@link KekProvider}'s current KEK (scrypt-derived AES-256-GCM key,
+ * the same scheme the engine uses for records) and only the *wrapped*
+ * bytes — together with the `kekRef` and salt needed to re-derive the
+ * unwrapping key — are persisted. The KEK *value* is supplied by the
+ * operator at boot and is never persisted (CWE-312/CWE-256): an attacker
+ * with read access to `rootDir` gets only ciphertext.
+ *
+ * After a rotation the operator must keep providing the prior KEK(s) via
+ * {@link staticKekProvider}'s `retained` list until every tenant's file
+ * has been rewritten under the new KEK (which happens on the next write
+ * for that tenant, including the re-mint that `rotateKek` performs).
+ */
+export function createFileDekStore(
+  rootDir: string,
+  kek: KekProvider,
+  opts: FileDekStoreOptions = {},
+): DekStore {
+  if (typeof rootDir !== "string" || rootDir.length === 0) {
+    throw new AuditEncryptionError("createFileDekStore: rootDir is required");
+  }
+  const rng = opts.randomBytesImpl ?? randomBytes;
+  mkdirSync(rootDir, { recursive: true, mode: 0o700 });
+
+  const FILE_PREFIX = "dek-";
+  const FILE_SUFFIX = ".json";
+
+  function pathFor(tenantId: string): string {
+    if (!/^[A-Za-z0-9_.-]+$/.test(tenantId)) {
+      throw new AuditEncryptionError(
+        `createFileDekStore: invalid tenantId "${tenantId}" (must match [A-Za-z0-9_.-]+)`,
+      );
+    }
+    return join(rootDir, `${FILE_PREFIX}${tenantId}${FILE_SUFFIX}`);
+  }
+
+  /** Wrap a raw DEK under the current KEK for persistence. */
+  function wrap(dek: Buffer): Omit<PersistedDek, "version" | "uses"> {
+    const { kekRef, kekValue } = kek.current();
+    const salt = rng(SALT_BYTES);
+    const kekKey = deriveKekKey(kekValue, salt);
+    const iv = rng(IV_BYTES);
+    const { ciphertext, tag } = encryptBytes(dek, kekKey, iv);
+    return {
+      kekRef,
+      kekSalt: salt.toString("hex"),
+      wrappedDek: ciphertext.toString("hex"),
+      wrappedDekIv: iv.toString("hex"),
+      wrappedDekTag: tag.toString("hex"),
+    };
+  }
+
+  /** Unwrap a persisted DEK using the KEK its `kekRef` selects. */
+  function unwrap(p: PersistedDek): Buffer {
+    const kekValue = kek.resolve(p.kekRef);
+    if (kekValue === undefined) {
+      throw new AuditEncryptionError(
+        `createFileDekStore: no KEK material for kekRef ${p.kekRef}; cannot unwrap persisted DEK (re-provide the prior KEK via staticKekProvider's retained list)`,
+      );
+    }
+    const kekKey = deriveKekKey(kekValue, Buffer.from(p.kekSalt, "hex"));
+    return decryptBytes(
+      Buffer.from(p.wrappedDek, "hex"),
+      kekKey,
+      Buffer.from(p.wrappedDekIv, "hex"),
+      Buffer.from(p.wrappedDekTag, "hex"),
+    );
+  }
+
+  function readPersisted(tenantId: string): PersistedDek | undefined {
+    const p = pathFor(tenantId);
+    if (!existsSync(p)) return undefined;
+    const raw = readFileSync(p, "utf8");
+    let parsed: PersistedDek;
+    try {
+      parsed = JSON.parse(raw) as PersistedDek;
+    } catch (err) {
+      throw new AuditEncryptionError(`createFileDekStore: corrupt DEK file at ${p}`, err);
+    }
+    return parsed;
+  }
+
+  /** Atomic write at 0o600: write `.tmp`, then rename into place. */
+  function writePersisted(tenantId: string, value: PersistedDek): void {
+    const p = pathFor(tenantId);
+    const tmp = `${p}.tmp`;
+    writeFileSync(tmp, JSON.stringify(value), { encoding: "utf8", mode: 0o600 });
+    renameSync(tmp, p);
+  }
+
+  return {
+    async get(tenantId: string): Promise<Buffer | undefined> {
+      const p = readPersisted(tenantId);
+      return p === undefined ? undefined : unwrap(p);
+    },
+    async set(tenantId: string, dek: Buffer): Promise<void> {
+      const prev = readPersisted(tenantId);
+      writePersisted(tenantId, { ...wrap(dek), version: prev?.version ?? 1, uses: 0 });
+    },
+    async getEntry(tenantId: string): Promise<DekEntry | undefined> {
+      const p = readPersisted(tenantId);
+      if (p === undefined) return undefined;
+      return { dek: unwrap(p), version: p.version, uses: p.uses };
+    },
+    async setEntry(tenantId: string, entry: DekEntry): Promise<void> {
+      writePersisted(tenantId, {
+        ...wrap(entry.dek),
+        version: entry.version,
+        uses: entry.uses,
+      });
+    },
+    async tenants(): Promise<ReadonlyArray<string>> {
+      if (!existsSync(rootDir)) return [];
+      return readdirSync(rootDir)
+        .filter((f) => f.startsWith(FILE_PREFIX) && f.endsWith(FILE_SUFFIX))
+        .map((f) => f.slice(FILE_PREFIX.length, f.length - FILE_SUFFIX.length));
+    },
+  };
 }
 
 const KEY_BYTES = 32; // AES-256
 const IV_BYTES = 12; // GCM standard
+const SALT_BYTES = 16; // scrypt salt
+/** scrypt cost params: N=2^15 keeps derivation well under a frame budget. */
+const SCRYPT_PARAMS = { N: 32768, r: 8, p: 1, maxmem: 64 * 1024 * 1024 } as const;
+/** Default DEK roll threshold. */
+export const DEFAULT_MAX_RECORDS_PER_DEK = 100_000;
 
-function deriveKekKey(kekValue: string): Buffer {
-  // KEK comes back from secrets-manager as a string. Derive a 32-byte
-  // AES key via SHA-256 — same shape regardless of whether the secret
-  // backend stores raw bytes, base64, or a passphrase.
+/**
+ * Derive the 32-byte AES wrapping key from the KEK string using scrypt
+ * with the supplied salt. scrypt is salted + memory-hard, so this is
+ * sound even when `kekValue` is a low-entropy passphrase (CWE-916). The
+ * salt must be persisted (`EncryptedRecord.kekSalt`) to re-derive.
+ */
+function deriveKekKey(kekValue: string, salt: Buffer): Buffer {
+  return scryptSync(kekValue, salt, KEY_BYTES, SCRYPT_PARAMS);
+}
+
+/**
+ * Legacy unsalted-SHA-256 derivation. Retained only to unwrap records
+ * written before the scrypt migration (those carry no `kekSalt`). Never
+ * used for new records.
+ */
+function deriveKekKeyLegacy(kekValue: string): Buffer {
   return createHash("sha256").update(kekValue).digest();
 }
 
@@ -129,8 +426,11 @@ export interface AuditEncryption {
   /** Decrypt and parse a previously encrypted record. */
   decryptPayload(record: EncryptedRecord): Promise<unknown>;
   /**
-   * Re-wrap every cached DEK with the new KEK value. Production callers
-   * subscribe via `secrets.onRotation(handler)` and forward to this.
+   * Adopt a new KEK and re-key every tenant's DEK to a fresh version.
+   * Production callers subscribe via `secrets.onRotation(handler)` and
+   * forward to this. The prior KEK value is retained in-process so
+   * historical records (which keep their original `kekRef`) still
+   * decrypt.
    */
   rotateKek(newKekValue: string, newKekRef: string): Promise<void>;
   /** Current KEK ref. */
@@ -148,35 +448,112 @@ export async function createAuditEncryption(
   }
   const dekStore = opts.dekStore ?? new InMemoryDekStore();
   const rng = opts.randomBytesImpl ?? randomBytes;
+  const maxRecordsPerDek =
+    opts.maxRecordsPerDek !== undefined && opts.maxRecordsPerDek > 0
+      ? opts.maxRecordsPerDek
+      : DEFAULT_MAX_RECORDS_PER_DEK;
   const initialKekValue = await opts.secrets.get(opts.kekName);
-  let currentKekRef = `kek:${opts.kekName}:v1`;
-  let currentKekKey = deriveKekKey(initialKekValue);
+  let currentKekRef =
+    typeof opts.kekRef === "string" && opts.kekRef.length > 0
+      ? opts.kekRef
+      : `kek:${opts.kekName}:v1`;
+  let currentKekValue = initialKekValue;
+  // Retain every KEK value we have ever held, keyed by its ref, so
+  // `decryptPayload` can re-derive the wrapping key for records sealed
+  // under a now-superseded KEK (CWE-323). Production deployments that
+  // restart rehydrate the superseded entries from `retainedKeks` (the
+  // secret backend's history), since the registry is otherwise
+  // process-local and lost across restarts.
+  const kekValuesByRef = new Map<string, string>([[currentKekRef, currentKekValue]]);
+  for (const { kekRef, kekValue } of opts.retainedKeks ?? []) {
+    // The boot KEK already occupies `currentKekRef`; don't let a stale
+    // retained entry shadow it.
+    if (!kekValuesByRef.has(kekRef)) {
+      kekValuesByRef.set(kekRef, kekValue);
+    }
+  }
 
-  // Auto-subscribe to rotation events.
+  // Auto-subscribe to rotation events. The re-key runs fire-and-forget, but
+  // its rejection is contained locally: a failed event-driven rotation must
+  // never escape as an unhandled rejection (which could crash the host
+  // process). The engine simply keeps its last-good KEK state and historical
+  // records still decrypt.
   const unsubscribeRotation = opts.secrets.onRotation((event) => {
     if (event.name !== opts.kekName) return;
-    void rotateInternal(event.newValue, `kek:${opts.kekName}:${event.rotatedAt}`);
+    void rotateInternal(event.newValue, `kek:${opts.kekName}:${event.rotatedAt}`).catch(() => {
+      /* contained — see comment above */
+    });
   });
   // Suppress unused-variable warning — unsubscribeRotation is intended
   // for future shutdown plumbing; tests can ignore it.
   void unsubscribeRotation;
 
+  async function readEntry(tenantId: string): Promise<DekEntry | undefined> {
+    if (dekStore.getEntry !== undefined) {
+      return dekStore.getEntry(tenantId);
+    }
+    const dek = await dekStore.get(tenantId);
+    if (dek === undefined || dek.length !== KEY_BYTES) return undefined;
+    return { dek, version: 1, uses: 0 };
+  }
+
+  async function writeEntry(tenantId: string, entry: DekEntry): Promise<void> {
+    if (dekStore.setEntry !== undefined) {
+      await dekStore.setEntry(tenantId, entry);
+      return;
+    }
+    await dekStore.set(tenantId, entry.dek);
+  }
+
+  function mintDek(tenantId: string, version: number): DekEntry {
+    return { dek: rng(KEY_BYTES), version, uses: 0 };
+  }
+
   async function getOrCreateDek(tenantId: string): Promise<{ dek: Buffer; dekRef: string }> {
-    const existing = await dekStore.get(tenantId);
-    if (existing !== undefined && existing.length === KEY_BYTES) {
-      return { dek: existing, dekRef: `dek:${tenantId}:v1` };
+    let entry = await readEntry(tenantId);
+    if (entry === undefined) {
+      entry = mintDek(tenantId, 1);
+    } else if (entry.uses >= maxRecordsPerDek) {
+      // Roll to a fresh DEK version once the current one is exhausted.
+      entry = mintDek(tenantId, entry.version + 1);
     }
-    const dek = rng(KEY_BYTES);
-    await dekStore.set(tenantId, dek);
-    return { dek, dekRef: `dek:${tenantId}:v1` };
+    const next: DekEntry = { dek: entry.dek, version: entry.version, uses: entry.uses + 1 };
+    await writeEntry(tenantId, next);
+    return { dek: next.dek, dekRef: `dek:${tenantId}:v${next.version}` };
   }
 
   async function rotateInternal(newKekValue: string, newKekRef: string): Promise<void> {
-    // For now we just swap the active KEK; old records still verify
-    // against the previous KEK if the secret backend retains it. Cached
-    // DEKs are wrapped lazily on the next encryptPayload call.
-    currentKekKey = deriveKekKey(newKekValue);
+    // Retain the prior KEK value so historical records keep decrypting,
+    // then adopt the new one as current.
+    kekValuesByRef.set(newKekRef, newKekValue);
+    currentKekValue = newKekValue;
     currentKekRef = newKekRef;
+    // Re-key every tenant's DEK to a fresh version. Records already on
+    // disk keep their old `dekRef`/`kekRef`; subsequent writes use the
+    // new DEK version wrapped under the new KEK.
+    if (dekStore.tenants !== undefined) {
+      const tenants = await dekStore.tenants();
+      for (const tenantId of tenants) {
+        const entry = await readEntry(tenantId);
+        if (entry === undefined) continue;
+        await writeEntry(tenantId, mintDek(tenantId, entry.version + 1));
+      }
+    }
+  }
+
+  function deriveForRef(kekRef: string, kekSalt: string | undefined): Buffer {
+    const kekValue = kekValuesByRef.get(kekRef);
+    if (kekValue === undefined) {
+      throw new AuditEncryptionError(
+        `no KEK material retained for kekRef ${kekRef}; cannot unwrap DEK`,
+      );
+    }
+    // Legacy records (pre-KDF migration) carry no salt — fall back to the
+    // unsalted derivation that originally sealed them.
+    if (kekSalt === undefined) {
+      return deriveKekKeyLegacy(kekValue);
+    }
+    return deriveKekKey(kekValue, Buffer.from(kekSalt, "hex"));
   }
 
   return {
@@ -191,16 +568,20 @@ export async function createAuditEncryption(
       const plaintext = Buffer.from(JSON.stringify(payload), "utf8");
       const iv = rng(IV_BYTES);
       const { ciphertext, tag } = encryptBytes(plaintext, dek, iv);
-      // Wrap the DEK with the KEK so we can persist the wrapped form
-      // alongside the record (production callers may store the
-      // wrapped DEK out-of-band; we include it here for self-contained
+      // Derive the wrapping key with a fresh per-record salt, then wrap
+      // the DEK with the current KEK so we can persist the wrapped form
+      // alongside the record (production callers may store the wrapped
+      // DEK out-of-band; we include it here for self-contained
       // round-trip).
+      const salt = rng(SALT_BYTES);
+      const kekKey = deriveKekKey(currentKekValue, salt);
       const dekIv = rng(IV_BYTES);
-      const { ciphertext: wrappedDek, tag: wrappedTag } = encryptBytes(dek, currentKekKey, dekIv);
+      const { ciphertext: wrappedDek, tag: wrappedTag } = encryptBytes(dek, kekKey, dekIv);
       return {
         tenantId,
         kekRef: currentKekRef,
         dekRef,
+        kekSalt: salt.toString("hex"),
         iv: iv.toString("hex"),
         tag: tag.toString("hex"),
         encryptedPayload: ciphertext.toString("hex"),
@@ -210,10 +591,12 @@ export async function createAuditEncryption(
       };
     },
     async decryptPayload(record: EncryptedRecord): Promise<unknown> {
-      // Unwrap the DEK first.
+      // Select the unwrapping KEK by the record's own `kekRef` so records
+      // sealed under a superseded KEK still decrypt after rotation.
+      const kekKey = deriveForRef(record.kekRef, record.kekSalt);
       const dek = decryptBytes(
         Buffer.from(record.wrappedDek, "hex"),
-        currentKekKey,
+        kekKey,
         Buffer.from(record.wrappedDekIv, "hex"),
         Buffer.from(record.wrappedDekTag, "hex"),
       );
@@ -239,4 +622,5 @@ export {
   encryptBytes as _encryptBytesForTest,
   decryptBytes as _decryptBytesForTest,
   deriveKekKey as _deriveKekKeyForTest,
+  deriveKekKeyLegacy as _deriveKekKeyLegacyForTest,
 };