@cosmicdrift/kumiko-framework 0.118.0 → 0.119.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.118.0",
+  "version": "0.119.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.118.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.119.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/api/__tests__/pii-leak-guard.integration.test.ts

@@ -0,0 +1,103 @@
+// Response-Tripwire (#820): ein kumiko-pii:-Ciphertext in einer JSON-Response
+// ist immer ein Bug (raw-Read am Decrypt vorbei). Dev/Test → 500 (Test wird
+// rot), Prod → redact + Error-Log, ohne KMS → kein Scan (pass-through).
+
+import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test";
+import { z } from "zod";
+import {
+  configurePiiSubjectKms,
+  InMemoryKmsAdapter,
+  resetPiiSubjectKmsForTests,
+} from "../../crypto";
+import { defineFeature } from "../../engine/define-feature";
+import { defineQueryHandler } from "../../engine/define-handler";
+import { setupTestStack, type TestStack, TestUsers } from "../../stack";
+
+const CIPHERTEXT = "kumiko-pii:v1:user:6b2f4a0e-1c9d-4f3a-9d2e-00000000000a:8e2Rkjj+ww==";
+
+const leakyFeature = defineFeature("leaky", (r) => {
+  r.queryHandler(
+    defineQueryHandler({
+      name: "raw",
+      schema: z.object({}),
+      access: { openToAll: true },
+      handler: async () => ({ email: CIPHERTEXT, note: "plain" }),
+    }),
+  );
+  r.queryHandler(
+    defineQueryHandler({
+      name: "clean",
+      schema: z.object({}),
+      access: { openToAll: true },
+      handler: async () => ({ email: "marc@example.com" }),
+    }),
+  );
+});
+
+let stack: TestStack;
+const originalNodeEnv = process.env["NODE_ENV"];
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [leakyFeature] });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+afterEach(() => {
+  resetPiiSubjectKmsForTests();
+  if (originalNodeEnv === undefined) delete process.env["NODE_ENV"];
+  else process.env["NODE_ENV"] = originalNodeEnv;
+});
+
+async function callLeakyQuery(): Promise<Response> {
+  const token = await stack.jwt.sign(TestUsers.admin);
+  return stack.http.raw(
+    "POST",
+    "/api/query",
+    { type: "leaky:query:raw", payload: {} },
+    { Authorization: `Bearer ${token}` },
+  );
+}
+
+describe("piiCiphertextResponseGuard", () => {
+  test("no KMS configured → response passes through unscanned", async () => {
+    const res = await callLeakyQuery();
+    expect(res.status).toBe(200);
+    expect(await res.text()).toContain(CIPHERTEXT);
+  });
+
+  test("KMS active, dev: leaking response becomes a loud 500", async () => {
+    configurePiiSubjectKms(new InMemoryKmsAdapter());
+    const res = await callLeakyQuery();
+    expect(res.status).toBe(500);
+    const body = (await res.json()) as { error?: { code?: string; message?: string } };
+    expect(body.error?.code).toBe("pii_ciphertext_leak");
+    expect(body.error?.message).toContain("/api/query");
+  });
+
+  test("KMS active, production: leak is redacted, request succeeds", async () => {
+    configurePiiSubjectKms(new InMemoryKmsAdapter());
+    process.env["NODE_ENV"] = "production";
+    const res = await callLeakyQuery();
+    expect(res.status).toBe(200);
+    const text = await res.text();
+    expect(text).not.toContain("kumiko-pii:");
+    expect(text).toContain("[pii-redacted]");
+    expect(text).toContain("plain");
+  });
+
+  test("KMS active, clean response stays untouched", async () => {
+    configurePiiSubjectKms(new InMemoryKmsAdapter());
+    const token = await stack.jwt.sign(TestUsers.admin);
+    const res = await stack.http.raw(
+      "POST",
+      "/api/query",
+      { type: "leaky:query:clean", payload: {} },
+      { Authorization: `Bearer ${token}` },
+    );
+    expect(res.status).toBe(200);
+    expect(await res.text()).toContain("marc@example.com");
+  });
+});

package/src/api/pii-leak-guard.ts

@@ -0,0 +1,45 @@
+import type { MiddlewareHandler } from "hono";
+import { configuredPiiSubjectKms, PII_CIPHERTEXT_PREFIX } from "../crypto";
+
+const isProductionEnv = () => process.env["NODE_ENV"] === "production";
+const CIPHERTEXT_RE = /kumiko-pii:v1:[^"\s<>\\]*/g;
+
+// A PII subject ciphertext never belongs in an API response — its presence
+// means a raw DB read (fetchOne/selectMany) leaked to the surface. Dev/test
+// fail loud (500) so a forgotten decrypt turns the first integration test
+// red; prod redacts + logs instead of shipping the blob. Skipped entirely
+// when no subject KMS is configured (no ciphertexts can exist).
+export function piiCiphertextResponseGuard(): MiddlewareHandler {
+  return async (c, next) => {
+    await next();
+    // skip: no subject KMS configured — no ciphertexts can exist, nothing to scan
+    if (configuredPiiSubjectKms() === undefined) return;
+    const contentType = c.res.headers.get("content-type") ?? "";
+    // skip: only JSON bodies carry handler data — streams/zips stay untouched
+    if (!contentType.includes("application/json")) return;
+    const text = await c.res.clone().text();
+    // skip: clean response — the common case
+    if (!text.includes(PII_CIPHERTEXT_PREFIX)) return;
+
+    const detail =
+      `[api] JSON response for ${c.req.method} ${c.req.path} contains a PII ciphertext ` +
+      `("${PII_CIPHERTEXT_PREFIX}…") — a raw DB read leaked to the API surface. ` +
+      `Decrypt before returning (decryptStoredPii / executor read path).`;
+    if (!isProductionEnv()) {
+      c.res = Response.json(
+        { error: { code: "pii_ciphertext_leak", httpStatus: 500, message: detail } },
+        { status: 500 },
+      );
+      // skip: response replaced with the loud 500 above — nothing left to do
+      return;
+    }
+    // biome-ignore lint/suspicious/noConsole: operator-visibility for a redacted prod leak
+    console.error(detail);
+    const headers = new Headers(c.res.headers);
+    headers.delete("content-length");
+    c.res = new Response(text.replace(CIPHERTEXT_RE, "[pii-redacted]"), {
+      status: c.res.status,
+      headers,
+    });
+  };
+}

package/src/api/server.ts

@@ -52,6 +52,7 @@ import { csrfMiddleware } from "./csrf-middleware";
 import { createJwtHelper, type JwtHelper } from "./jwt";
 import { observabilityMiddleware } from "./observability-middleware";
 import { assertOriginGuardConfig, originMiddleware } from "./origin-middleware";
+import { piiCiphertextResponseGuard } from "./pii-leak-guard";
 import { requestIdMiddleware } from "./request-id-middleware";
 import {
   DEFAULT_MAX_REQUEST_BYTES,
@@ -553,6 +554,10 @@ export function buildServer(options: ServerOptions): KumikoServer {
     }),
   );
 
+  // Tripwire: a kumiko-pii: ciphertext in a JSON response is always a bug
+  // (raw read leaked past a decrypt) — dev fails loud, prod redacts (#820).
+  app.use("/api/*", piiCiphertextResponseGuard());
+
   // Auth middleware skips public paths (login, health) — those routes need
   // to be callable without a valid JWT. Every other /api/* request requires
   // a token (or, when anonymousAccess is wired, falls through as anonymous).

package/src/bun-db/query.ts

@@ -19,6 +19,7 @@
 //     drizzle's getTableName + getTableColumns (drizzle weiterhin als type-
 //     reference, NICHT als runtime-API-call)
 
+import { computeBlindIndex, configuredBlindIndexKey } from "../crypto/blind-index";
 import type { EntityTableMeta } from "../db/entity-table-meta";
 import { type NotExecutorOnly, toSnakeCase } from "../db/table-builder";
 import { camelCase as envCamelCase } from "../env";
@@ -355,6 +356,12 @@ export function coerceRow<T extends Record<string, unknown>>(row: T, info: Table
   const out: Record<string, unknown> = {};
   let changed = false;
   for (const key of Object.keys(row)) {
+    // Blind-Index-Spalten (#818) sind reine Lookup-Artefakte — der
+    // deterministische HMAC darf nie an Caller/API-Responses leaken.
+    if ((key.endsWith("_bidx") || key.endsWith("Bidx")) && info.hasColumn(key)) {
+      changed = true;
+      continue;
+    }
     const pgType = info.pgTypeOf(key);
     const value = row[key];
     let coerced: unknown = value;
@@ -529,8 +536,26 @@ function buildWhereClause(
       if (p.kind === "literal") {
         conditions.push(`${quoteIdent(col)} = ${p.literal}`);
       } else {
-        conditions.push(`${quoteIdent(col)} = $${idx++}${p.sql}`);
-        values.push(p.bound);
+        // Blind-Index-OR-Rewrite (#818): existiert zur Spalte ein bidx-
+        // Pendant (Suffix-Konvention `<col>_bidx`, framework-reserviert)
+        // und ist ein Key konfiguriert, matcht Equality beide Arme —
+        // Klartext-Alt-Rows über den Plaintext-Arm, verschlüsselte Rows
+        // über den HMAC. Der `kumiko-pii:`-Prefix der Ciphertexte macht
+        // einen Zufalls-Match des Plaintext-Arms praktisch unmöglich.
+        const bidxKey = configuredBlindIndexKey();
+        const bidxCol = `${col}_bidx`;
+        if (
+          bidxKey !== undefined &&
+          typeof value === "string" &&
+          !col.endsWith("_bidx") &&
+          info.hasColumn(bidxCol)
+        ) {
+          conditions.push(`(${quoteIdent(col)} = $${idx++} OR ${quoteIdent(bidxCol)} = $${idx++})`);
+          values.push(p.bound, computeBlindIndex(bidxKey, value));
+        } else {
+          conditions.push(`${quoteIdent(col)} = $${idx++}${p.sql}`);
+          values.push(p.bound);
+        }
       }
     }
   }

package/src/crypto/__tests__/blind-index.test.ts

@@ -0,0 +1,130 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { createEntity, createTextField } from "../../engine/factories";
+import {
+  blindIndexFieldName,
+  collectLookupableFields,
+  computeBlindIndex,
+  computeBlindIndexValues,
+  configureBlindIndexKey,
+  configuredBlindIndexKey,
+  decodeBlindIndexKey,
+  resetBlindIndexKeyForTests,
+} from "../blind-index";
+import { InMemoryKmsAdapter } from "../in-memory-kms-adapter";
+import {
+  configurePiiSubjectKms,
+  encryptPiiFieldValues,
+  PII_ERASED_SENTINEL,
+  resetPiiSubjectKmsForTests,
+} from "../pii-field-encryption";
+
+const UUID_A = "6b2f4a0e-1c9d-4f3a-9d2e-00000000000a";
+const TEST_KEY_B64 = Buffer.alloc(32, 7).toString("base64");
+const TEST_KEY = decodeBlindIndexKey(TEST_KEY_B64);
+
+const userLikeEntity = createEntity({
+  fields: {
+    email: createTextField({ required: true, pii: true, lookupable: true }),
+    role: createTextField(),
+  },
+  table: "bidx_users",
+});
+
+afterEach(() => {
+  resetBlindIndexKeyForTests();
+  resetPiiSubjectKmsForTests();
+});
+
+describe("computeBlindIndex", () => {
+  test("deterministic, prefixed, byte-exact (no normalization)", () => {
+    const a = computeBlindIndex(TEST_KEY, "marc@example.com");
+    expect(a).toStartWith("kumiko-bidx:v1:");
+    expect(computeBlindIndex(TEST_KEY, "marc@example.com")).toBe(a);
+    expect(computeBlindIndex(TEST_KEY, "Marc@example.com")).not.toBe(a);
+  });
+
+  test("different keys produce different indexes", () => {
+    const otherKey = decodeBlindIndexKey(Buffer.alloc(32, 9).toString("base64"));
+    expect(computeBlindIndex(otherKey, "x")).not.toBe(computeBlindIndex(TEST_KEY, "x"));
+  });
+});
+
+describe("configureBlindIndexKey", () => {
+  test("rejects keys that are not 32 bytes", () => {
+    expect(() => configureBlindIndexKey(Buffer.alloc(16, 1).toString("base64"))).toThrow(
+      /32 bytes/,
+    );
+    expect(configuredBlindIndexKey()).toBeUndefined();
+  });
+
+  test("undefined clears the key", () => {
+    configureBlindIndexKey(TEST_KEY_B64);
+    expect(configuredBlindIndexKey()).toBeDefined();
+    configureBlindIndexKey(undefined);
+    expect(configuredBlindIndexKey()).toBeUndefined();
+  });
+});
+
+describe("collectLookupableFields", () => {
+  test("only text fields with lookupable: true", () => {
+    expect(collectLookupableFields(userLikeEntity)).toEqual(["email"]);
+  });
+});
+
+describe("computeBlindIndexValues", () => {
+  test("no key configured → empty (blind-indexing off)", async () => {
+    const out = await computeBlindIndexValues({ email: "a@b.c" }, ["email"]);
+    expect(out).toEqual({});
+  });
+
+  test("plaintext value → HMAC over the value itself", async () => {
+    configureBlindIndexKey(TEST_KEY_B64);
+    const out = await computeBlindIndexValues({ email: "a@b.c" }, ["email"]);
+    expect(out[blindIndexFieldName("email")]).toBe(computeBlindIndex(TEST_KEY, "a@b.c"));
+  });
+
+  test("absent field stays untouched, null value → NULL bidx", async () => {
+    configureBlindIndexKey(TEST_KEY_B64);
+    expect(await computeBlindIndexValues({ role: "admin" }, ["email"])).toEqual({});
+    expect(await computeBlindIndexValues({ email: null }, ["email"])).toEqual({
+      emailBidx: null,
+    });
+  });
+
+  test("ciphertext value → decrypt via configured KMS, HMAC over plaintext", async () => {
+    const kms = new InMemoryKmsAdapter();
+    configurePiiSubjectKms(kms);
+    configureBlindIndexKey(TEST_KEY_B64);
+    const stored = await encryptPiiFieldValues(
+      { id: UUID_A, email: "marc@example.com" },
+      userLikeEntity,
+      ["email"],
+      kms,
+      { requestId: "test" },
+    );
+    const out = await computeBlindIndexValues({ email: stored["email"] }, ["email"]);
+    expect(out["emailBidx"]).toBe(computeBlindIndex(TEST_KEY, "marc@example.com"));
+  });
+
+  test("erased subject → NULL bidx (lookup stops matching)", async () => {
+    const kms = new InMemoryKmsAdapter();
+    configurePiiSubjectKms(kms);
+    configureBlindIndexKey(TEST_KEY_B64);
+    const stored = await encryptPiiFieldValues(
+      { id: UUID_A, email: "marc@example.com" },
+      userLikeEntity,
+      ["email"],
+      kms,
+      { requestId: "test" },
+    );
+    await kms.eraseKey({ kind: "user", userId: UUID_A });
+    const out = await computeBlindIndexValues({ email: stored["email"] }, ["email"]);
+    expect(out["emailBidx"]).toBeNull();
+  });
+
+  test("erased sentinel → NULL bidx", async () => {
+    configureBlindIndexKey(TEST_KEY_B64);
+    const out = await computeBlindIndexValues({ email: PII_ERASED_SENTINEL }, ["email"]);
+    expect(out["emailBidx"]).toBeNull();
+  });
+});

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");
+  });
+});