@cosmicdrift/kumiko-framework 0.165.3 → 0.166.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.165.3",
+  "version": "0.166.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>",
@@ -197,10 +197,10 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@cosmicdrift/kumiko-types": "^0.165.3"
+    "@cosmicdrift/kumiko-types": "^0.166.0"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.165.3",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.166.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/crypto/__tests__/kms-wiring.test.ts

@@ -0,0 +1,175 @@
+import { describe, expect, test } from "bun:test";
+import {
+  buildPgKmsOptions,
+  type KmsWiringEnv,
+  requireKmsWiring,
+  resolveKmsWiring,
+} from "../kms-wiring";
+
+// 32 raw bytes -> base64, the shape PgKmsAdapter's decodePlatformKek demands.
+const KEK_A = Buffer.alloc(32, 1).toString("base64");
+const KEK_B = Buffer.alloc(32, 2).toString("base64");
+
+const fullTrio: KmsWiringEnv = {
+  PLATFORM_KEK: KEK_A,
+  SUBJECT_KEYS_DATABASE_URL: "postgres://localhost:5432/subject_keys",
+  KUMIKO_BLIND_INDEX_KEY: "blind-index-key",
+};
+
+const rotationEnv = {
+  PLATFORM_KEK: KEK_A,
+  SUBJECT_KEYS_DATABASE_URL: "postgres://localhost:5432/subject_keys",
+};
+
+describe("buildPgKmsOptions", () => {
+  test("defaults kekVersion to 1 and omits previousKeks entirely when no rotation is active", () => {
+    const options = buildPgKmsOptions(rotationEnv);
+
+    expect(options.kekVersion).toBe(1);
+    // Absent, not `undefined` — this is what distinguishes rotation-inactive
+    // (the normal state of every app) from a half-configured rotation.
+    expect("previousKeks" in options).toBe(false);
+  });
+
+  test("maps the previous KEK into the version slot named by the env var", () => {
+    const options = buildPgKmsOptions({
+      ...rotationEnv,
+      PLATFORM_KEK_VERSION: "3",
+      PLATFORM_KEK_PREVIOUS: KEK_B,
+      PLATFORM_KEK_PREVIOUS_VERSION: "2",
+    });
+
+    expect(options.kekVersion).toBe(3);
+    expect(options.previousKeks).toEqual({ 2: KEK_B });
+  });
+
+  // The bug this parser exists for: every one of these used to pass through
+  // Number() and produce a wrong-but-silent version, which makes the rotation
+  // slot unreachable and its rows unreadable (phronexsis#323).
+  test.each([
+    ["1e21", "scientific notation survives Number.isInteger"],
+    ["0x10", "hex coerces to 16"],
+    ["-1", "negative"],
+    ["0", "zero is not a valid version"],
+    [" 2 ", "whitespace is trimmed by Number"],
+    ["2.5", "fractional"],
+    ["abc", "not a number at all"],
+  ])("rejects PLATFORM_KEK_VERSION=%p (%s)", (raw) => {
+    expect(() => buildPgKmsOptions({ ...rotationEnv, PLATFORM_KEK_VERSION: raw })).toThrow(
+      /PLATFORM_KEK_VERSION must be a positive integer/,
+    );
+  });
+
+  // An empty env var is "unset", not "invalid" — `FOO=` in a .env file and an
+  // absent FOO are the same thing to every shell and dotenv loader. Pinned
+  // because it is the one falsy input that must NOT hit the strict parser.
+  test("treats an empty PLATFORM_KEK_VERSION as unset", () => {
+    expect(buildPgKmsOptions({ ...rotationEnv, PLATFORM_KEK_VERSION: "" }).kekVersion).toBe(1);
+  });
+
+  test("rejects a bad PLATFORM_KEK_PREVIOUS_VERSION with the same strictness", () => {
+    expect(() =>
+      buildPgKmsOptions({
+        ...rotationEnv,
+        PLATFORM_KEK_VERSION: "2",
+        PLATFORM_KEK_PREVIOUS: KEK_B,
+        PLATFORM_KEK_PREVIOUS_VERSION: "1e21",
+      }),
+    ).toThrow(/PLATFORM_KEK_PREVIOUS_VERSION must be a positive integer/);
+  });
+
+  test("rejects PLATFORM_KEK_PREVIOUS without its version", () => {
+    expect(() => buildPgKmsOptions({ ...rotationEnv, PLATFORM_KEK_PREVIOUS: KEK_B })).toThrow(
+      /PLATFORM_KEK_PREVIOUS_VERSION must be set/,
+    );
+  });
+});
+
+describe("resolveKmsWiring", () => {
+  test("falls back to plaintext PII when the trio is entirely absent", () => {
+    const wiring = resolveKmsWiring({});
+
+    expect(wiring).toEqual({ allowPlaintextPii: "local dev without subject-keys KMS (fw#818)" });
+  });
+
+  // Regression: every member being optional made TypeScript's weak-type
+  // detection reject `process.env` ("no properties in common with
+  // KmsWiringEnv"), which pushed each app toward a cast or a six-key mapping.
+  // This compiles only while the index signature is there.
+  test("accepts process.env directly, with its unrelated keys", () => {
+    const processLike: NodeJS.ProcessEnv = { PATH: "/usr/bin", HOME: "/root" };
+
+    expect(resolveKmsWiring(processLike)).toHaveProperty("allowPlaintextPii");
+  });
+
+  test("carries an app-supplied fallback reason into the boot log", () => {
+    const wiring = resolveKmsWiring({}, { plaintextReason: "solon pre-UI gate" });
+
+    expect(wiring).toEqual({ allowPlaintextPii: "solon pre-UI gate" });
+  });
+
+  // All-or-none is the core of this module: a partial trio means someone
+  // dropped one env var and would otherwise boot with unencrypted PII.
+  test.each([
+    ["PLATFORM_KEK", { PLATFORM_KEK: KEK_A }],
+    ["SUBJECT_KEYS_DATABASE_URL", { SUBJECT_KEYS_DATABASE_URL: "postgres://localhost/x" }],
+    ["KUMIKO_BLIND_INDEX_KEY", { KUMIKO_BLIND_INDEX_KEY: "key" }],
+  ])("throws when only %s is set", (_name, env) => {
+    expect(() => resolveKmsWiring(env)).toThrow(/all-or-none/);
+  });
+
+  test("prefixes the all-or-none error with the app's boot-log prefix", () => {
+    expect(() => resolveKmsWiring({ PLATFORM_KEK: KEK_A }, { logPrefix: "[solon]" })).toThrow(
+      /^\[solon\] PLATFORM_KEK/,
+    );
+  });
+
+  test.each([
+    ["PLATFORM_KEK_PREVIOUS without version", { PLATFORM_KEK_PREVIOUS: KEK_B }],
+    ["version without PLATFORM_KEK_PREVIOUS", { PLATFORM_KEK_PREVIOUS_VERSION: "1" }],
+  ])("throws on a half-configured rotation: %s", (_name, extra) => {
+    expect(() => resolveKmsWiring({ ...fullTrio, ...extra })).toThrow(/must be set together/);
+  });
+
+  test("builds the adapter when the trio is complete", () => {
+    const wiring = resolveKmsWiring(fullTrio);
+
+    expect("kms" in wiring).toBe(true);
+    if (!("kms" in wiring)) throw new Error("unreachable");
+    expect(wiring.blindIndexKey).toBe("blind-index-key");
+  });
+
+  // Ownership check: the previous-version-must-be-older rule lives in
+  // PgKmsAdapter's constructor, not here. Asserting on ITS message keeps that
+  // documented — if the adapter ever stops enforcing it, this test breaks and
+  // tells the next person the rule lost its home.
+  test("leaves previous-version ordering to PgKmsAdapter, which rejects it", () => {
+    expect(() =>
+      resolveKmsWiring({
+        ...fullTrio,
+        PLATFORM_KEK_VERSION: "2",
+        PLATFORM_KEK_PREVIOUS: KEK_B,
+        PLATFORM_KEK_PREVIOUS_VERSION: "2",
+      }),
+    ).toThrow(/PgKmsAdapter: previousKeks\[2\] must be older than the active kekVersion 2/);
+  });
+});
+
+describe("requireKmsWiring", () => {
+  test("returns the active wiring without narrowing when the trio is complete", () => {
+    // No `in` check needed at the call site — that is the point of the split.
+    const { blindIndexKey } = requireKmsWiring(fullTrio);
+
+    expect(blindIndexKey).toBe("blind-index-key");
+  });
+
+  test("throws instead of falling back when the trio is absent", () => {
+    expect(() => requireKmsWiring({}, { logPrefix: "[money-horse]" })).toThrow(
+      /no plaintext-PII opt-out on this entry point/,
+    );
+  });
+
+  test("still reports a partial trio as all-or-none", () => {
+    expect(() => requireKmsWiring({ PLATFORM_KEK: KEK_A })).toThrow(/all-or-none/);
+  });
+});

package/src/crypto/index.ts

@@ -34,6 +34,17 @@ export {
   subjectKeyForTenant,
   subjectKeyForUser,
 } from "./kms-adapter";
+export {
+  type ActiveKmsWiring,
+  buildPgKmsOptions,
+  type KmsWiring,
+  type KmsWiringEnv,
+  type KmsWiringOptions,
+  type PgKmsRotationEnv,
+  type PlaintextPiiWiring,
+  requireKmsWiring,
+  resolveKmsWiring,
+} from "./kms-wiring";
 export {
   createPgKmsAdapter,
   PgKmsAdapter,

package/src/crypto/kms-wiring.ts

@@ -0,0 +1,163 @@
+// Boot-time env validation for the subject-keys KMS, shared by every app that
+// mounts crypto-shredding. Lived copy-pasted in four apps before fw#1617; the
+// copies drifted apart in their parsers, which is the failure mode this module
+// exists to end.
+//
+// Split in two on purpose: `buildPgKmsOptions` is pure and unit-testable
+// (the rotation slot mapping is the part that silently corrupts data when it
+// is wrong), `resolveKmsWiring` is the boot entry point that also constructs
+// the adapter.
+
+import { createPgKmsAdapter, type PgKmsAdapter, type PgKmsAdapterOptions } from "./pg-kms-adapter";
+
+// The index signature is what lets callers pass `process.env` directly. Without
+// it every member is optional, so TypeScript's weak-type detection rejects
+// ProcessEnv for having "no properties in common" — and each app would need
+// either a hand-written six-key mapping or a cast. An env map genuinely does
+// carry arbitrary keys, so the signature states a fact rather than loosening
+// the type for convenience.
+export type KmsWiringEnv = {
+  readonly PLATFORM_KEK?: string | undefined;
+  readonly SUBJECT_KEYS_DATABASE_URL?: string | undefined;
+  readonly KUMIKO_BLIND_INDEX_KEY?: string | undefined;
+  readonly PLATFORM_KEK_VERSION?: string | undefined;
+  readonly PLATFORM_KEK_PREVIOUS?: string | undefined;
+  readonly PLATFORM_KEK_PREVIOUS_VERSION?: string | undefined;
+  readonly [key: string]: string | undefined;
+};
+
+/** Narrowed form for `buildPgKmsOptions` — presence of the two required
+ *  members is the caller's job (`resolveKmsWiring` does it via the trio check). */
+export type PgKmsRotationEnv = KmsWiringEnv & {
+  readonly PLATFORM_KEK: string;
+  readonly SUBJECT_KEYS_DATABASE_URL: string;
+};
+
+export type ActiveKmsWiring = {
+  readonly kms: PgKmsAdapter;
+  readonly blindIndexKey: string;
+};
+
+/** Plaintext fallback carries its reason so the boot log says WHY PII is
+ *  unencrypted — an app running like this by accident is a reportable breach. */
+export type PlaintextPiiWiring = { readonly allowPlaintextPii: string };
+
+export type KmsWiring = ActiveKmsWiring | PlaintextPiiWiring;
+
+export type KmsWiringOptions = {
+  /** Prefixes the all-or-none error. Use the app's existing boot-log prefix —
+   *  people grep for it in production logs. */
+  readonly logPrefix?: string;
+  /** Reason recorded when the trio is absent and plaintext PII is accepted. */
+  readonly plaintextReason?: string;
+};
+
+const DEFAULT_PLAINTEXT_REASON = "local dev without subject-keys KMS (fw#818)";
+
+// Number(raw) + Number.isInteger is the wrong parser for an env string:
+// Number.isInteger(1e21) is true, so "1e21" passes, and the value then
+// stringifies back to "1e+21" as a previousKeks object key — a lookup against
+// the integer kek_version column never hits that slot, silently leaving
+// rotation-window rows unreadable. Same class: "0x10" -> 16, " 2 " trimmed,
+// "-1"/"0" accepted as versions, values past MAX_SAFE_INTEGER rounded.
+// A digits-only regex closes all of these at once (phronexsis#323).
+function parseKekVersion(raw: string, fieldName: string): number {
+  if (!/^[0-9]+$/.test(raw)) {
+    throw new Error(`${fieldName} must be a positive integer, got "${raw}".`);
+  }
+  const version = Number(raw);
+  if (!Number.isSafeInteger(version) || version < 1) {
+    throw new Error(`${fieldName} must be a positive integer, got "${raw}".`);
+  }
+  return version;
+}
+
+/** Maps the KEK env vars onto adapter options, including which version slot an
+ *  old KEK lands in during a rotation window.
+ *
+ *  Does NOT check that the previous version is older than the active one —
+ *  `PgKmsAdapter`'s constructor already rejects `previousKeks[v] >= kekVersion`
+ *  and stays the single source of that rule. */
+export function buildPgKmsOptions(env: PgKmsRotationEnv): PgKmsAdapterOptions {
+  const kekVersion = env.PLATFORM_KEK_VERSION
+    ? parseKekVersion(env.PLATFORM_KEK_VERSION, "PLATFORM_KEK_VERSION")
+    : 1;
+  if (!env.PLATFORM_KEK_PREVIOUS) {
+    return {
+      databaseUrl: env.SUBJECT_KEYS_DATABASE_URL,
+      platformKek: env.PLATFORM_KEK,
+      kekVersion,
+    };
+  }
+  if (!env.PLATFORM_KEK_PREVIOUS_VERSION) {
+    throw new Error("PLATFORM_KEK_PREVIOUS_VERSION must be set when PLATFORM_KEK_PREVIOUS is set.");
+  }
+  const previousVersion = parseKekVersion(
+    env.PLATFORM_KEK_PREVIOUS_VERSION,
+    "PLATFORM_KEK_PREVIOUS_VERSION",
+  );
+  return {
+    databaseUrl: env.SUBJECT_KEYS_DATABASE_URL,
+    platformKek: env.PLATFORM_KEK,
+    kekVersion,
+    previousKeks: { [previousVersion]: env.PLATFORM_KEK_PREVIOUS },
+  };
+}
+
+function assertTrioConsistent(env: KmsWiringEnv, logPrefix: string | undefined): boolean {
+  const trio = [env.PLATFORM_KEK, env.SUBJECT_KEYS_DATABASE_URL, env.KUMIKO_BLIND_INDEX_KEY];
+  const complete = trio.every(Boolean);
+  if (!complete && trio.some(Boolean)) {
+    throw new Error(
+      `${logPrefix ? `${logPrefix} ` : ""}PLATFORM_KEK / SUBJECT_KEYS_DATABASE_URL / ` +
+        "KUMIKO_BLIND_INDEX_KEY are all-or-none — a partial set means the KMS wiring is broken.",
+    );
+  }
+  if (Boolean(env.PLATFORM_KEK_PREVIOUS) !== Boolean(env.PLATFORM_KEK_PREVIOUS_VERSION)) {
+    throw new Error(
+      "PLATFORM_KEK_PREVIOUS and PLATFORM_KEK_PREVIOUS_VERSION must be set together " +
+        "(KEK rotation, runbook kek-rotation.md).",
+    );
+  }
+  return complete;
+}
+
+/** Boot wiring for apps that may run without a KMS (dev, local): complete trio
+ *  yields the adapter, empty trio yields the plaintext fallback, partial throws.
+ *
+ *  Prod entry points that must never fall back: use `requireKmsWiring`. */
+export function resolveKmsWiring(env: KmsWiringEnv, options: KmsWiringOptions = {}): KmsWiring {
+  const complete = assertTrioConsistent(env, options.logPrefix);
+  if (complete && env.PLATFORM_KEK && env.SUBJECT_KEYS_DATABASE_URL && env.KUMIKO_BLIND_INDEX_KEY) {
+    return {
+      kms: createPgKmsAdapter(
+        buildPgKmsOptions({
+          ...env,
+          PLATFORM_KEK: env.PLATFORM_KEK,
+          SUBJECT_KEYS_DATABASE_URL: env.SUBJECT_KEYS_DATABASE_URL,
+        }),
+      ),
+      blindIndexKey: env.KUMIKO_BLIND_INDEX_KEY,
+    };
+  }
+  return { allowPlaintextPii: options.plaintextReason ?? DEFAULT_PLAINTEXT_REASON };
+}
+
+/** Same as `resolveKmsWiring` but the trio is mandatory — an absent trio throws
+ *  instead of silently accepting plaintext PII. Separate function rather than a
+ *  flag so the return type is the active wiring, with no narrowing at the call
+ *  site. */
+export function requireKmsWiring(
+  env: KmsWiringEnv,
+  options: KmsWiringOptions = {},
+): ActiveKmsWiring {
+  const wiring = resolveKmsWiring(env, options);
+  if ("allowPlaintextPii" in wiring) {
+    throw new Error(
+      `${options.logPrefix ? `${options.logPrefix} ` : ""}PLATFORM_KEK / ` +
+        "SUBJECT_KEYS_DATABASE_URL / KUMIKO_BLIND_INDEX_KEY are required here — " +
+        "no plaintext-PII opt-out on this entry point.",
+    );
+  }
+  return wiring;
+}

package/src/secrets/__tests__/derive-purpose-secret.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, test } from "bun:test";
+import { derivePurposeSecret } from "../derive-purpose-secret";
+
+const MASTER = "master-secret-for-tests-32-bytes-min";
+
+describe("derivePurposeSecret", () => {
+  test("is deterministic — same master and purpose give the same secret", () => {
+    expect(derivePurposeSecret(MASTER, "mfa-setup-token-v1")).toBe(
+      derivePurposeSecret(MASTER, "mfa-setup-token-v1"),
+    );
+  });
+
+  // The whole point: two purposes must not share a key, or a token minted for
+  // one boundary verifies at another.
+  test("separates purposes", () => {
+    expect(derivePurposeSecret(MASTER, "mfa-setup-token-v1")).not.toBe(
+      derivePurposeSecret(MASTER, "mfa-challenge-token-v1"),
+    );
+  });
+
+  test("versioning a purpose yields a different secret, so rotation is per-purpose", () => {
+    expect(derivePurposeSecret(MASTER, "deletion-token-v1")).not.toBe(
+      derivePurposeSecret(MASTER, "deletion-token-v2"),
+    );
+  });
+
+  test("rotating the master rotates every derived secret", () => {
+    expect(derivePurposeSecret(MASTER, "deletion-token-v1")).not.toBe(
+      derivePurposeSecret(`${MASTER}-rotated`, "deletion-token-v1"),
+    );
+  });
+
+  test("never returns the master itself", () => {
+    const derived = derivePurposeSecret(MASTER, "mfa-setup-token-v1");
+
+    expect(derived).not.toBe(MASTER);
+    expect(derived).not.toContain(MASTER);
+  });
+
+  test("returns 32 bytes as hex", () => {
+    expect(derivePurposeSecret(MASTER, "any-purpose-v1")).toMatch(/^[0-9a-f]{64}$/);
+  });
+
+  // An empty purpose would silently collapse every boundary onto one key —
+  // the failure mode this function exists to prevent, so it must be loud.
+  test.each([
+    ["empty master", "", "a-purpose"],
+    ["empty purpose", MASTER, ""],
+  ])("throws on %s", (_name, master, purpose) => {
+    expect(() => derivePurposeSecret(master, purpose)).toThrow(/must not be empty/);
+  });
+});

package/src/secrets/derive-purpose-secret.ts

@@ -0,0 +1,27 @@
+import { hkdfSync } from "node:crypto";
+
+// One master secret, many purposes: HKDF turns `JWT_SECRET` into an
+// independent secret per trust boundary, so a token-signing key for MFA setup
+// cannot be used to forge a deletion token — and neither can be walked back to
+// the master. Rotating the master rotates every purpose with it.
+//
+// The alternative is an env var per purpose. That is not more secure (same
+// blast radius if the deploy is compromised), it is just more operations, and
+// in practice one of them ends up unset in some environment.
+//
+// The purpose string is a domain separator and part of the contract: change it
+// and every previously issued token for that purpose stops verifying. Version
+// them ("mfa-setup-token-v1") so a single purpose can be rotated deliberately
+// without touching the master or the other purposes.
+//
+// Lived copy-pasted in four apps before fw#1623 (money-horse, kumiko-studio,
+// publicstatus, plus a stale worktree) — identical bodies, drifting comments.
+export function derivePurposeSecret(masterSecret: string, purpose: string): string {
+  if (!masterSecret) {
+    throw new Error("derivePurposeSecret: masterSecret must not be empty.");
+  }
+  if (!purpose) {
+    throw new Error("derivePurposeSecret: purpose must not be empty — it is the domain separator.");
+  }
+  return Buffer.from(hkdfSync("sha256", masterSecret, "", purpose, 32)).toString("hex");
+}

package/src/secrets/index.ts

@@ -1,4 +1,5 @@
 export { createDekCache, type DekCache, type DekCacheOptions, withDekCache } from "./dek-cache";
+export { derivePurposeSecret } from "./derive-purpose-secret";
 export {
   createEnvMasterKeyProvider,
   type EnvMasterKeyProviderOptions,