@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

package/src/crypto/__tests__/kek-rotation.integration.test.ts

@@ -0,0 +1,180 @@
+// KEK rotation (#818 step 7): mid-rotation an adapter with the NEW active
+// KEK + previousKeks reads old-generation rows; rewrapSubjectKeys migrates
+// the estate to the new generation; afterwards previousKeks can be dropped.
+// Erased tombstones stay untouched, unknown generations fail loud as a
+// CONFIG error (not a shredded subject).
+
+import { afterAll, beforeEach, describe, expect, test } from "bun:test";
+import { randomUUID } from "node:crypto";
+import postgres from "postgres";
+import { createTestDb } from "../../stack/db";
+import type { KmsContext, SubjectId } from "../kms-adapter";
+import { createPgKmsAdapter, rewrapSubjectKeys } from "../pg-kms-adapter";
+
+const baseUrl = process.env["TEST_DATABASE_URL"];
+if (!baseUrl) throw new Error("Missing required env var: TEST_DATABASE_URL");
+
+const testDb = await createTestDb();
+const DB_URL = baseUrl.replace(/\/[^/]+$/, `/${testDb.dbName}`);
+
+const KEK_V1 = Buffer.alloc(32, 1).toString("base64");
+const KEK_V2 = Buffer.alloc(32, 2).toString("base64");
+const ctx: KmsContext = { requestId: "kek-rotation-test" };
+const freshUser = (): SubjectId => ({ kind: "user", userId: randomUUID() });
+
+const raw = postgres(DB_URL, { max: 1, onnotice: () => {} });
+
+afterAll(async () => {
+  await raw.end();
+  await testDb.cleanup();
+});
+
+beforeEach(async () => {
+  const boot = createPgKmsAdapter({ databaseUrl: DB_URL, platformKek: KEK_V1 });
+  await boot.health();
+  await boot.close();
+  await raw`TRUNCATE kumiko_subject_keys`;
+});
+
+async function seedV1Keys(count: number): Promise<SubjectId[]> {
+  const v1 = createPgKmsAdapter({ databaseUrl: DB_URL, platformKek: KEK_V1 });
+  const subjects: SubjectId[] = [];
+  for (let i = 0; i < count; i++) {
+    const subject = freshUser();
+    await v1.createKey(subject, ctx);
+    subjects.push(subject);
+  }
+  await v1.close();
+  return subjects;
+}
+
+describe("KEK rotation", () => {
+  test("mid-rotation adapter (new active + previousKeks) reads v1 rows; new writes carry v2", async () => {
+    const [oldSubject] = await seedV1Keys(1);
+    if (!oldSubject) throw new Error("seed failed");
+
+    const rotating = createPgKmsAdapter({
+      databaseUrl: DB_URL,
+      platformKek: KEK_V2,
+      kekVersion: 2,
+      previousKeks: { 1: KEK_V1 },
+    });
+    const dek = await rotating.getKey(oldSubject, ctx);
+    expect(dek.length).toBe(32);
+
+    const newSubject = freshUser();
+    await rotating.createKey(newSubject, ctx);
+    const versions = await raw<Array<{ kek_version: number }>>`
+      SELECT kek_version FROM kumiko_subject_keys ORDER BY kek_version`;
+    expect(versions.map((r) => r.kek_version)).toEqual([1, 2]);
+    await rotating.close();
+  });
+
+  test("unknown generation without previousKeks is a loud config error", async () => {
+    const [oldSubject] = await seedV1Keys(1);
+    if (!oldSubject) throw new Error("seed failed");
+
+    const misconfigured = createPgKmsAdapter({
+      databaseUrl: DB_URL,
+      platformKek: KEK_V2,
+      kekVersion: 2,
+    });
+    expect(misconfigured.getKey(oldSubject, ctx)).rejects.toThrow(/pass previousKeks/);
+    await misconfigured.close();
+  });
+
+  test("previousKeks newer than the active version is rejected at construction", () => {
+    expect(() =>
+      createPgKmsAdapter({
+        databaseUrl: DB_URL,
+        platformKek: KEK_V1,
+        kekVersion: 1,
+        previousKeks: { 2: KEK_V2 },
+      }),
+    ).toThrow(/must be older/);
+  });
+
+  test("rewrapSubjectKeys migrates the estate; DEKs stay identical; idempotent", async () => {
+    const subjects = await seedV1Keys(3);
+    const v1 = createPgKmsAdapter({ databaseUrl: DB_URL, platformKek: KEK_V1 });
+    const before = await Promise.all(subjects.map((s) => v1.getKey(s, ctx)));
+    await v1.close();
+
+    const result = await rewrapSubjectKeys({
+      databaseUrl: DB_URL,
+      fromKeks: { 1: KEK_V1 },
+      toKek: KEK_V2,
+      toKekVersion: 2,
+      batchSize: 2,
+    });
+    expect(result.failures).toEqual([]);
+    expect(result.rewrapped).toBe(3);
+
+    // The rotated estate is fully readable with ONLY the new KEK — and the
+    // unwrapped DEKs are byte-identical (stored ciphertext stays decryptable).
+    const v2 = createPgKmsAdapter({ databaseUrl: DB_URL, platformKek: KEK_V2, kekVersion: 2 });
+    const after = await Promise.all(subjects.map((s) => v2.getKey(s, ctx)));
+    for (const [i, dek] of after.entries()) {
+      expect(dek.equals(before[i] as Buffer)).toBe(true);
+    }
+    await v2.close();
+
+    const second = await rewrapSubjectKeys({
+      databaseUrl: DB_URL,
+      fromKeks: { 1: KEK_V1 },
+      toKek: KEK_V2,
+      toKekVersion: 2,
+    });
+    expect(second.scanned).toBe(0);
+    expect(second.rewrapped).toBe(0);
+  });
+
+  test("erased tombstones are skipped and stay erased", async () => {
+    const [gone] = await seedV1Keys(1);
+    if (!gone) throw new Error("seed failed");
+    const v1 = createPgKmsAdapter({ databaseUrl: DB_URL, platformKek: KEK_V1 });
+    await v1.eraseKey(gone, ctx);
+    await v1.close();
+
+    const result = await rewrapSubjectKeys({
+      databaseUrl: DB_URL,
+      fromKeks: { 1: KEK_V1 },
+      toKek: KEK_V2,
+      toKekVersion: 2,
+    });
+    expect(result.skippedErased).toBe(1);
+    expect(result.rewrapped).toBe(0);
+
+    const rows = await raw<Array<{ cipher_key: Uint8Array | null }>>`
+      SELECT cipher_key FROM kumiko_subject_keys`;
+    expect(rows[0]?.cipher_key).toBeNull();
+  });
+
+  test("dryRun counts but writes nothing", async () => {
+    await seedV1Keys(2);
+    const dry = await rewrapSubjectKeys({
+      databaseUrl: DB_URL,
+      fromKeks: { 1: KEK_V1 },
+      toKek: KEK_V2,
+      toKekVersion: 2,
+      dryRun: true,
+    });
+    expect(dry.rewrapped).toBe(2);
+    const versions = await raw<Array<{ kek_version: number }>>`
+      SELECT DISTINCT kek_version FROM kumiko_subject_keys`;
+    expect(versions.map((r) => r.kek_version)).toEqual([1]);
+  });
+
+  test("missing fromKek for a generation lands in failures, not a crash", async () => {
+    await seedV1Keys(1);
+    const result = await rewrapSubjectKeys({
+      databaseUrl: DB_URL,
+      fromKeks: {},
+      toKek: KEK_V2,
+      toKekVersion: 2,
+    });
+    expect(result.rewrapped).toBe(0);
+    expect(result.failures).toHaveLength(1);
+    expect(result.failures[0]?.reason).toContain("no fromKek configured");
+  });
+});

package/src/crypto/__tests__/kms-adapter-contract.ts

@@ -0,0 +1,134 @@
+import { beforeEach, describe, expect, test } from "bun:test";
+import {
+  isLocalKeyKmsAdapter,
+  KeyAlreadyExistsError,
+  KeyErasedError,
+  KeyNotFoundError,
+  type KmsAdapter,
+  type KmsContext,
+  type SubjectId,
+} from "../kms-adapter";
+
+const ctx: KmsContext = { requestId: "contract-test" };
+
+const userA: SubjectId = { kind: "user", userId: "6b2f4a0e-1c9d-4f3a-9d2e-000000000001" };
+const userB: SubjectId = { kind: "user", userId: "6b2f4a0e-1c9d-4f3a-9d2e-000000000002" };
+const tenantWithUserAId: SubjectId = {
+  kind: "tenant",
+  tenantId: "6b2f4a0e-1c9d-4f3a-9d2e-000000000001",
+};
+
+async function subjectDek(adapter: KmsAdapter, subject: SubjectId): Promise<Buffer> {
+  if (isLocalKeyKmsAdapter(adapter)) return adapter.getKey(subject, ctx);
+  // remote-crypto adapters never release keys — probe via roundtrip instead.
+  const probe = Buffer.from("contract-probe");
+  const encrypted = await adapter.encrypt(subject, probe, ctx);
+  return Buffer.from(await adapter.decrypt(subject, encrypted, ctx));
+}
+
+export function describeKmsAdapterContract(
+  name: string,
+  factory: () => KmsAdapter | Promise<KmsAdapter>,
+): void {
+  describe(`${name} — KmsAdapter contract`, () => {
+    let adapter: KmsAdapter;
+
+    beforeEach(async () => {
+      adapter = await factory();
+    });
+
+    test("createKey then getKey returns a 32-byte DEK", async () => {
+      await adapter.createKey(userA, ctx);
+      if (!isLocalKeyKmsAdapter(adapter)) return;
+      const dek = await adapter.getKey(userA, ctx);
+      expect(dek.length).toBe(32);
+    });
+
+    test("getKey is stable — same subject, same key", async () => {
+      await adapter.createKey(userA, ctx);
+      if (!isLocalKeyKmsAdapter(adapter)) return;
+      const first = await adapter.getKey(userA, ctx);
+      const second = await adapter.getKey(userA, ctx);
+      expect(first.equals(second)).toBe(true);
+    });
+
+    test("distinct subjects get distinct keys", async () => {
+      await adapter.createKey(userA, ctx);
+      await adapter.createKey(userB, ctx);
+      if (!isLocalKeyKmsAdapter(adapter)) return;
+      const a = await adapter.getKey(userA, ctx);
+      const b = await adapter.getKey(userB, ctx);
+      expect(a.equals(b)).toBe(false);
+    });
+
+    test("user and tenant subjects with the same raw id are distinct", async () => {
+      await adapter.createKey(userA, ctx);
+      await adapter.createKey(tenantWithUserAId, ctx);
+      if (!isLocalKeyKmsAdapter(adapter)) return;
+      const user = await adapter.getKey(userA, ctx);
+      const tenant = await adapter.getKey(tenantWithUserAId, ctx);
+      expect(user.equals(tenant)).toBe(false);
+    });
+
+    test("createKey twice throws KeyAlreadyExistsError", async () => {
+      await adapter.createKey(userA, ctx);
+      await expect(adapter.createKey(userA, ctx)).rejects.toBeInstanceOf(KeyAlreadyExistsError);
+    });
+
+    test("getKey for an unknown subject throws KeyNotFoundError", async () => {
+      if (!isLocalKeyKmsAdapter(adapter)) return;
+      await expect(adapter.getKey(userA, ctx)).rejects.toBeInstanceOf(KeyNotFoundError);
+    });
+
+    test("eraseKey makes getKey throw KeyErasedError", async () => {
+      await adapter.createKey(userA, ctx);
+      await adapter.eraseKey(userA, ctx);
+      if (!isLocalKeyKmsAdapter(adapter)) return;
+      await expect(adapter.getKey(userA, ctx)).rejects.toBeInstanceOf(KeyErasedError);
+    });
+
+    test("eraseKey is idempotent — second call is a no-op", async () => {
+      await adapter.createKey(userA, ctx);
+      await adapter.eraseKey(userA, ctx);
+      await adapter.eraseKey(userA, ctx);
+      if (!isLocalKeyKmsAdapter(adapter)) return;
+      await expect(adapter.getKey(userA, ctx)).rejects.toBeInstanceOf(KeyErasedError);
+    });
+
+    test("eraseKey for an unknown subject is a no-op", async () => {
+      await adapter.eraseKey(userA, ctx);
+      if (!isLocalKeyKmsAdapter(adapter)) return;
+      await expect(adapter.getKey(userA, ctx)).rejects.toBeInstanceOf(KeyNotFoundError);
+    });
+
+    test("createKey after eraseKey throws — the tombstone blocks a new key", async () => {
+      await adapter.createKey(userA, ctx);
+      await adapter.eraseKey(userA, ctx);
+      await expect(adapter.createKey(userA, ctx)).rejects.toBeInstanceOf(KeyAlreadyExistsError);
+    });
+
+    test("erasing one subject leaves other subjects intact", async () => {
+      await adapter.createKey(userA, ctx);
+      await adapter.createKey(userB, ctx);
+      await adapter.eraseKey(userA, ctx);
+      const dek = await subjectDek(adapter, userB);
+      expect(dek.length).toBeGreaterThan(0);
+    });
+
+    test("remote-crypto adapters roundtrip encrypt/decrypt", async () => {
+      if (isLocalKeyKmsAdapter(adapter)) return;
+      await adapter.createKey(userA, ctx);
+      const plaintext = Buffer.from("marc@example.com");
+      const ciphertext = await adapter.encrypt(userA, plaintext, ctx);
+      expect(Buffer.from(ciphertext).equals(plaintext)).toBe(false);
+      const roundtrip = await adapter.decrypt(userA, ciphertext, ctx);
+      expect(Buffer.from(roundtrip).equals(plaintext)).toBe(true);
+    });
+
+    test("health reports ok for a reachable adapter", async () => {
+      const health = await adapter.health();
+      expect(health.ok).toBe(true);
+      expect(health.latencyMs).toBeGreaterThanOrEqual(0);
+    });
+  });
+}

package/src/crypto/__tests__/kms-adapter.contract.test.ts

@@ -0,0 +1,4 @@
+import { InMemoryKmsAdapter } from "../in-memory-kms-adapter";
+import { describeKmsAdapterContract } from "./kms-adapter-contract";
+
+describeKmsAdapterContract("InMemoryKmsAdapter", () => new InMemoryKmsAdapter());

package/src/crypto/__tests__/pg-kms-adapter.integration.test.ts

@@ -0,0 +1,117 @@
+import { afterAll, describe, expect, test } from "bun:test";
+import { randomBytes, randomUUID } from "node:crypto";
+import postgres from "postgres";
+import { createTestDb } from "../../stack/db";
+import { type KmsContext, type SubjectId, subjectIdToKey } from "../kms-adapter";
+import { PgKmsAdapter } from "../pg-kms-adapter";
+import { describeKmsAdapterContract } from "./kms-adapter-contract";
+
+const baseUrl = process.env["TEST_DATABASE_URL"];
+if (!baseUrl) throw new Error("Missing required env var: TEST_DATABASE_URL");
+
+const testDb = await createTestDb();
+const databaseUrl = baseUrl.replace(/\/[^/]+$/, `/${testDb.dbName}`);
+const platformKek = randomBytes(32).toString("base64");
+const adapter = new PgKmsAdapter({ databaseUrl, platformKek, maxConnections: 2 });
+const raw = postgres(databaseUrl, { max: 1 });
+
+afterAll(async () => {
+  await adapter.close();
+  await raw.end();
+  await testDb.cleanup();
+});
+
+describeKmsAdapterContract("PgKmsAdapter", async () => {
+  // health() creates the schema lazily, so the truncate cannot hit a
+  // missing table on the first run; contract tests reuse fixed subject ids.
+  await adapter.health();
+  await raw`TRUNCATE kumiko_subject_keys`;
+  return adapter;
+});
+
+describe("PgKmsAdapter — pg specifics", () => {
+  const ctx: KmsContext = { requestId: "pg-kms-test" };
+  const freshUser = (): SubjectId => ({ kind: "user", userId: randomUUID() });
+
+  test("rejects a platformKek that does not decode to 32 bytes", () => {
+    expect(
+      () =>
+        new PgKmsAdapter({
+          databaseUrl,
+          platformKek: Buffer.from("too-short").toString("base64"),
+        }),
+    ).toThrow("32 bytes");
+  });
+
+  test("DEKs survive across adapter instances", async () => {
+    const user = freshUser();
+    await adapter.createKey(user, ctx);
+    const dek = await adapter.getKey(user, ctx);
+
+    const second = new PgKmsAdapter({ databaseUrl, platformKek, maxConnections: 1 });
+    try {
+      const rehydrated = await second.getKey(user, ctx);
+      expect(rehydrated.equals(dek)).toBe(true);
+    } finally {
+      await second.close();
+    }
+  });
+
+  test("a different platform KEK cannot unwrap stored DEKs", async () => {
+    const user = freshUser();
+    await adapter.createKey(user, ctx);
+
+    const wrongKek = new PgKmsAdapter({
+      databaseUrl,
+      platformKek: randomBytes(32).toString("base64"),
+      maxConnections: 1,
+    });
+    try {
+      await expect(wrongKek.getKey(user, ctx)).rejects.toThrow();
+    } finally {
+      await wrongKek.close();
+    }
+  });
+
+  test("erase leaves an audit tombstone without key material", async () => {
+    const user = freshUser();
+    await adapter.createKey(user, ctx);
+    await adapter.eraseKey(user, {
+      requestId: "pg-kms-test",
+      userId: "operator-1",
+      eraseReason: "user-forget",
+    });
+
+    const rows = await raw`
+      SELECT cipher_key, erased_at, erased_by, erase_reason
+      FROM kumiko_subject_keys
+      WHERE subject_id = ${subjectIdToKey(user)}`;
+    expect(rows.length).toBe(1);
+    expect(rows[0]?.["cipher_key"]).toBeNull();
+    expect(rows[0]?.["erased_at"]).not.toBeNull();
+    expect(rows[0]?.["erased_by"]).toBe("operator-1");
+    expect(rows[0]?.["erase_reason"]).toBe("user-forget");
+  });
+
+  test("repeat erase keeps the original tombstone audit fields", async () => {
+    const user = freshUser();
+    await adapter.createKey(user, ctx);
+    await adapter.eraseKey(user, {
+      requestId: "pg-kms-test",
+      userId: "operator-1",
+      eraseReason: "user-forget",
+    });
+    await adapter.eraseKey(user, {
+      requestId: "pg-kms-test",
+      userId: "operator-2",
+      eraseReason: "tenant-destroy",
+    });
+
+    const rows = await raw`
+      SELECT erased_by, erase_reason
+      FROM kumiko_subject_keys
+      WHERE subject_id = ${subjectIdToKey(user)}`;
+    expect(rows[0]?.["erased_by"]).toBe("operator-1");
+    expect(rows[0]?.["erase_reason"]).toBe("user-forget");
+  });
+});