@cosmicdrift/kumiko-framework 0.120.0 → 0.121.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.120.0",
+  "version": "0.121.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -185,7 +185,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.120.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.121.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

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/index.ts

@@ -38,6 +38,9 @@ export {
   createPgKmsAdapter,
   PgKmsAdapter,
   type PgKmsAdapterOptions,
+  type RewrapOptions,
+  type RewrapResult,
+  rewrapSubjectKeys,
 } from "./pg-kms-adapter";
 export {
   configuredPiiSubjectKms,

package/src/crypto/pg-kms-adapter.ts

@@ -57,6 +57,7 @@ function isPgUniqueViolation(error: unknown): boolean {
 
 interface SubjectKeyRow {
   cipher_key: Uint8Array | null;
+  kek_version: number;
   erased: boolean;
 }
 
@@ -65,6 +66,13 @@ export interface PgKmsAdapterOptions {
   readonly databaseUrl: string;
   /** Base64-encoded 32-byte platform KEK (PLATFORM_KEK env var). */
   readonly platformKek: string;
+  /** Version of `platformKek` as stored in kumiko_subject_keys.kek_version.
+   *  Bump on rotation; new wraps carry this version. Default 1. */
+  readonly kekVersion?: number;
+  /** Older KEKs by version, kept ONLY during a rotation window so rows not
+   *  yet re-wrapped stay readable. Drop after rewrapSubjectKeys reports the
+   *  estate fully on the active version (runbook: kek-rotation.md). */
+  readonly previousKeks?: Readonly<Record<number, string>>;
   readonly maxConnections?: number;
 }
 
@@ -76,10 +84,24 @@ export class PgKmsAdapter implements LocalKeyKmsAdapter {
 
   private readonly sql: ReturnType<typeof postgres>;
   private readonly kek: Buffer;
+  private readonly kekVersion: number;
+  private readonly previousKeks: ReadonlyMap<number, Buffer>;
   private schemaReady: Promise<void> | undefined;
 
   constructor(options: PgKmsAdapterOptions) {
     this.kek = decodePlatformKek(options.platformKek);
+    this.kekVersion = options.kekVersion ?? 1;
+    const previous = new Map<number, Buffer>();
+    for (const [version, kek] of Object.entries(options.previousKeks ?? {})) {
+      const v = Number(version);
+      if (v >= this.kekVersion) {
+        throw new Error(
+          `PgKmsAdapter: previousKeks[${v}] must be older than the active kekVersion ${this.kekVersion}`,
+        );
+      }
+      previous.set(v, decodePlatformKek(kek));
+    }
+    this.previousKeks = previous;
     this.sql = postgres(options.databaseUrl, {
       max: options.maxConnections ?? 4,
       // The connection is exclusive to this adapter and its only DDL is
@@ -93,8 +115,8 @@ export class PgKmsAdapter implements LocalKeyKmsAdapter {
     const wrapped = wrapDek(this.kek, randomBytes(32));
     try {
       await this.sql`
-        INSERT INTO kumiko_subject_keys (subject_id, cipher_key, created_by)
-        VALUES (${subjectIdToKey(subject)}, ${wrapped}, ${ctx.userId ?? null})`;
+        INSERT INTO kumiko_subject_keys (subject_id, cipher_key, kek_version, created_by)
+        VALUES (${subjectIdToKey(subject)}, ${wrapped}, ${this.kekVersion}, ${ctx.userId ?? null})`;
     } catch (error) {
       if (isPgUniqueViolation(error)) throw new KeyAlreadyExistsError(subject);
       throw error;
@@ -104,13 +126,25 @@ export class PgKmsAdapter implements LocalKeyKmsAdapter {
   async getKey(subject: SubjectId, _ctx: KmsContext): Promise<SubjectDek> {
     await this.ensureSchema();
     const rows = await this.sql<SubjectKeyRow[]>`
-      SELECT cipher_key, (erased_at IS NOT NULL) AS erased
+      SELECT cipher_key, kek_version, (erased_at IS NOT NULL) AS erased
       FROM kumiko_subject_keys
       WHERE subject_id = ${subjectIdToKey(subject)}`;
     const row = rows[0];
     if (!row) throw new KeyNotFoundError(subject);
     if (row.erased || row.cipher_key === null) throw new KeyErasedError(subject);
-    return unwrapDek(this.kek, row.cipher_key);
+    return unwrapDek(this.kekFor(row.kek_version, subject), row.cipher_key);
+  }
+
+  // Rows keep working mid-rotation: not-yet-rewrapped DEKs name their KEK
+  // generation and unwrap with the matching previous key. A version with no
+  // configured key is a hard config error — NOT a shredded subject.
+  private kekFor(version: number, subject: SubjectId): Buffer {
+    if (version === this.kekVersion) return this.kek;
+    const previous = this.previousKeks.get(version);
+    if (previous) return previous;
+    throw new Error(
+      `PgKmsAdapter: subject ${subjectIdToKey(subject)} is wrapped with KEK version ${version} but only version ${this.kekVersion}${this.previousKeks.size > 0 ? ` (+previous ${[...this.previousKeks.keys()].join(",")})` : ""} is configured — pass previousKeks during rotation (runbook: kek-rotation.md).`,
+    );
   }
 
   async eraseKey(subject: SubjectId, ctx: KmsContext): Promise<void> {
@@ -171,3 +205,91 @@ export class PgKmsAdapter implements LocalKeyKmsAdapter {
 export function createPgKmsAdapter(options: PgKmsAdapterOptions): PgKmsAdapter {
   return new PgKmsAdapter(options);
 }
+
+export interface RewrapOptions {
+  readonly databaseUrl: string;
+  /** Older KEKs by version — every version still present in the table must be covered. */
+  readonly fromKeks: Readonly<Record<number, string>>;
+  /** The new active KEK and its version (previous active version + 1). */
+  readonly toKek: string;
+  readonly toKekVersion: number;
+  readonly batchSize?: number;
+  readonly dryRun?: boolean;
+}
+
+export interface RewrapResult {
+  readonly scanned: number;
+  readonly rewrapped: number;
+  readonly skippedErased: number;
+  readonly failures: ReadonlyArray<{ readonly subjectId: string; readonly reason: string }>;
+}
+
+// One-time KEK rotation (runbook: kek-rotation.md). Unwraps every live DEK
+// wrapped with an older KEK generation and re-wraps it under the new KEK,
+// bumping kek_version. Idempotent: rows already on toKekVersion are not
+// selected; a second run reports 0. Erased tombstones (cipher_key NULL) are
+// never touched. The UPDATE is guarded on the row's old kek_version, so a
+// concurrent app writing fresh keys on the new version is never clobbered.
+export async function rewrapSubjectKeys(options: RewrapOptions): Promise<RewrapResult> {
+  const toKek = decodePlatformKek(options.toKek);
+  const fromKeks = new Map<number, Buffer>();
+  for (const [version, kek] of Object.entries(options.fromKeks)) {
+    fromKeks.set(Number(version), decodePlatformKek(kek));
+  }
+  const batchSize = options.batchSize ?? 200;
+  const sql = postgres(options.databaseUrl, { max: 2, onnotice: () => {} });
+
+  const result = {
+    scanned: 0,
+    rewrapped: 0,
+    skippedErased: 0,
+    failures: [] as Array<{ subjectId: string; reason: string }>,
+  };
+  try {
+    let cursor = "";
+    for (;;) {
+      const rows = await sql<
+        Array<{ subject_id: string; cipher_key: Uint8Array | null; kek_version: number }>
+      >`
+        SELECT subject_id, cipher_key, kek_version
+        FROM kumiko_subject_keys
+        WHERE kek_version <> ${options.toKekVersion} AND subject_id > ${cursor}
+        ORDER BY subject_id ASC
+        LIMIT ${batchSize}`;
+      if (rows.length === 0) break;
+
+      for (const row of rows) {
+        result.scanned++;
+        if (row.cipher_key === null) {
+          result.skippedErased++;
+          continue;
+        }
+        try {
+          const fromKek = fromKeks.get(row.kek_version);
+          if (!fromKek) {
+            throw new Error(`no fromKek configured for kek_version ${row.kek_version}`);
+          }
+          const rewrapped = wrapDek(toKek, unwrapDek(fromKek, row.cipher_key));
+          if (!options.dryRun) {
+            await sql`
+              UPDATE kumiko_subject_keys
+              SET cipher_key = ${rewrapped}, kek_version = ${options.toKekVersion}
+              WHERE subject_id = ${row.subject_id} AND kek_version = ${row.kek_version}`;
+          }
+          result.rewrapped++;
+        } catch (error) {
+          result.failures.push({
+            subjectId: row.subject_id,
+            reason: error instanceof Error ? error.message : String(error),
+          });
+        }
+      }
+      const last = rows[rows.length - 1];
+      if (last === undefined) break;
+      cursor = last.subject_id;
+    }
+  } finally {
+    await sql.end();
+  }
+  return result;
+}