@cosmicdrift/kumiko-framework 0.165.4 → 0.167.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.165.4",
+  "version": "0.167.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>",
@@ -182,9 +182,10 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
+    "@cosmicdrift/kumiko-types": "0.167.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
-    "hono": "^4.12.18",
+    "hono": "^4.12.27",
     "i18next": "^26.1.0",
     "ioredis": "^5.10.1",
     "jose": "^6.2.3",
@@ -196,11 +197,8 @@
     "uuid": "^14.0.0",
     "zod": "^4.4.3"
   },
-  "peerDependencies": {
-    "@cosmicdrift/kumiko-types": "^0.165.4"
-  },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.165.4",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.167.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

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

@@ -3,12 +3,9 @@
 // rot), Prod → redact + Error-Log, ohne KMS → kein Scan (pass-through).
 
 import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test";
+import { resetPiiSubjectKmsForTests } from "@cosmicdrift/kumiko-framework/testing";
 import { z } from "zod";
-import {
-  configurePiiSubjectKms,
-  InMemoryKmsAdapter,
-  resetPiiSubjectKmsForTests,
-} from "../../crypto";
+import { configurePiiSubjectKms, InMemoryKmsAdapter } from "../../crypto";
 import { defineFeature } from "../../engine/define-feature";
 import { defineQueryHandler } from "../../engine/define-handler";
 import { setupTestStack, type TestStack, TestUsers } from "../../stack";

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

@@ -6,14 +6,12 @@ export {
   configureBlindIndexKey,
   configuredBlindIndexKey,
   decodeBlindIndexKey,
-  resetBlindIndexKeyForTests,
 } from "./blind-index";
 export {
   configuredEventPiiCatalog,
   configureEventPiiCatalog,
   type EventPiiCatalog,
   encryptEventPayloadPii,
-  resetEventPiiCatalogForTests,
 } from "./event-pii";
 export { InMemoryKmsAdapter } from "./in-memory-kms-adapter";
 export {
@@ -34,6 +32,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,
@@ -53,7 +62,6 @@ export {
   isPiiCiphertext,
   PII_CIPHERTEXT_PREFIX,
   PII_ERASED_SENTINEL,
-  resetPiiSubjectKmsForTests,
 } from "./pii-field-encryption";
 export {
   createRequestKmsCache,

package/src/crypto/kms-adapter.ts

@@ -1,2 +1,27 @@
-// Legacy path — re-exported for callers still importing this module directly.
+import { type SubjectId, subjectIdToKey } from "@cosmicdrift/kumiko-types/kms-adapter-types";
+
 export * from "@cosmicdrift/kumiko-types/kms-adapter-types";
+
+// The KMS error classes live here and not in kumiko-types (#1629): callers
+// branch on them with `instanceof`, which needs a single copy of the class.
+
+export class KeyErasedError extends Error {
+  constructor(public readonly subject: SubjectId) {
+    super(`Subject key erased: ${subjectIdToKey(subject)}`);
+    this.name = "KeyErasedError";
+  }
+}
+
+export class KeyNotFoundError extends Error {
+  constructor(public readonly subject: SubjectId) {
+    super(`Subject key not found: ${subjectIdToKey(subject)}`);
+    this.name = "KeyNotFoundError";
+  }
+}
+
+export class KeyAlreadyExistsError extends Error {
+  constructor(public readonly subject: SubjectId) {
+    super(`Subject key already exists: ${subjectIdToKey(subject)}`);
+    this.name = "KeyAlreadyExistsError";
+  }
+}

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/db/__tests__/blind-index.integration.test.ts

@@ -4,6 +4,10 @@
 // dem Ciphertext (erased → NULL), und der Forget-Sweep nullt sofort.
 
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import {
+  resetBlindIndexKeyForTests,
+  resetPiiSubjectKmsForTests,
+} from "@cosmicdrift/kumiko-framework/testing";
 import {
   computeBlindIndex,
   configureBlindIndexKey,
@@ -11,8 +15,6 @@ import {
   decodeBlindIndexKey,
   InMemoryKmsAdapter,
   isPiiCiphertext,
-  resetBlindIndexKeyForTests,
-  resetPiiSubjectKmsForTests,
   subjectIdToKey,
 } from "../../crypto";
 import { defineFeature } from "../../engine/define-feature";

package/src/db/__tests__/implicit-projection-equivalence.integration.test.ts

@@ -227,6 +227,10 @@ describe("implicit-projection / Live==Rebuild equivalence", () => {
 // damit auch für sensitive Spalten + Blind-Index. Einzige legitime Divergenz
 // bleibt Crypto-Shredding: DEK erased → bidx NULL, Wert unlesbar.
 
+import {
+  resetBlindIndexKeyForTests,
+  resetPiiSubjectKmsForTests,
+} from "@cosmicdrift/kumiko-framework/testing";
 import {
   computeBlindIndex,
   configureBlindIndexKey,
@@ -235,8 +239,6 @@ import {
   decryptPiiFieldValues,
   InMemoryKmsAdapter,
   isPiiCiphertext,
-  resetBlindIndexKeyForTests,
-  resetPiiSubjectKmsForTests,
 } from "../../crypto";
 import { asRawClient, selectMany } from "../../db/query";
 

package/src/db/index.ts

@@ -48,7 +48,6 @@ export {
   configureEntityFieldEncryption,
   decryptEntityFieldValues,
   encryptEntityFieldValues,
-  resetEntityFieldEncryptionCacheForTests,
 } from "./entity-field-encryption";
 export type {
   BuildEntityTableMetaOptions,

package/src/event-store/__tests__/backfill-pii.integration.test.ts

@@ -7,6 +7,10 @@
 // blind-index column, so equality lookups keep working.
 
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import {
+  resetBlindIndexKeyForTests,
+  resetPiiSubjectKmsForTests,
+} from "@cosmicdrift/kumiko-framework/testing";
 import { z } from "zod";
 import {
   configureBlindIndexKey,
@@ -14,8 +18,6 @@ import {
   InMemoryKmsAdapter,
   isPiiCiphertext,
   PII_ERASED_SENTINEL,
-  resetBlindIndexKeyForTests,
-  resetPiiSubjectKmsForTests,
 } from "../../crypto";
 import { applyEntityEvent } from "../../db/apply-entity-event";
 import { backfillEventPiiEncryption } from "../../db/queries/backfill-pii";

package/src/event-store/errors.ts

@@ -1,2 +1,58 @@
-// Legacy path — re-exported for callers still importing this module directly.
-export * from "@cosmicdrift/kumiko-types/event-store-errors";
+// Failure modes of the event-store's append() path. Surfaced as typed
+// errors so the executor layer can map them to the framework's
+// WriteResult error contract (version_conflict).
+//
+// These live here and not in kumiko-types (#1629): `instanceof` needs a
+// single copy of the class, which forced kumiko-types to be a peerDependency
+// and made every minor changeset resolve to a major bump.
+
+export class VersionConflictError extends Error {
+  public readonly aggregateId: string;
+  public readonly expectedVersion: number;
+  constructor(aggregateId: string, expectedVersion: number) {
+    super(
+      `Version conflict on aggregate ${aggregateId}: expected predecessor version ${expectedVersion}`,
+    );
+    this.name = "VersionConflictError";
+    this.aggregateId = aggregateId;
+    this.expectedVersion = expectedVersion;
+  }
+}
+
+// Thrown when append() collides on the partial unique index over
+// metadata.idempotencyKey (tenant-scoped). Distinct from VersionConflictError:
+// a version conflict means two writers raced the same predecessor; this
+// means the same idempotency key was used twice, which is a caller-side
+// retry that must have already appended once. Callers that set
+// idempotencyKey should treat this as "already applied" rather than retry.
+export class IdempotentAppendConflictError extends Error {
+  public readonly tenantId: string;
+  public readonly idempotencyKey: string;
+  constructor(tenantId: string, idempotencyKey: string) {
+    super(
+      `Idempotency conflict on tenant ${tenantId}: an event with idempotencyKey "${idempotencyKey}" was already appended.`,
+    );
+    this.name = "IdempotentAppendConflictError";
+    this.tenantId = tenantId;
+    this.idempotencyKey = idempotencyKey;
+  }
+}
+
+// Thrown when ctx.appendEvent targets an archived stream. Archived aggregates
+// are read-only — restoreStream() makes them writable again. The archive
+// state is not carried on the events themselves; it lives on the sparse
+// kumiko_archived_streams table. Handlers that need to branch on archive
+// state should call ctx.isStreamArchived(id) first.
+export class ArchivedStreamError extends Error {
+  public readonly tenantId: string;
+  public readonly aggregateId: string;
+  constructor(tenantId: string, aggregateId: string) {
+    super(
+      `Aggregate ${aggregateId} on tenant ${tenantId} is archived — appendEvent is blocked. ` +
+        `Call restoreStream() to re-open the stream before writing.`,
+    );
+    this.name = "ArchivedStreamError";
+    this.tenantId = tenantId;
+    this.aggregateId = aggregateId;
+  }
+}

package/src/search/__tests__/search-pii-derived-index.integration.test.ts

@@ -2,11 +2,11 @@
 // plaintext in derived search index, purged on subject erase.
 
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { resetPiiSubjectKmsForTests } from "@cosmicdrift/kumiko-framework/testing";
 import {
   configurePiiSubjectKms,
   InMemoryKmsAdapter,
   isPiiCiphertext,
-  resetPiiSubjectKmsForTests,
   subjectIdToKey,
 } from "../../crypto";
 import { asRawClient, buildEntityTable, createEventStoreExecutor, createTenantDb } from "../../db";

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/__tests__/leak-guard.test.ts

@@ -89,4 +89,16 @@ describe("assertNoSecretLeak — walks the response tree for branded values", ()
     expect(() => assertNoSecretLeak(undefined)).not.toThrow();
     expect(() => assertNoSecretLeak(null)).not.toThrow();
   });
+
+  // Dual-package hazard: a second resolved copy of @cosmicdrift/kumiko-types
+  // brands with ITS OWN symbol. Constructing the brand from the global registry
+  // here stands in for that copy — with a plain Symbol() the guard walks past
+  // this value and serializes the plaintext (#1438-adjacent).
+  test("catches a Secret branded by another copy of the package", () => {
+    const foreign = {
+      [Symbol.for("kumiko.secret")]: true as const,
+      reveal: () => "plaintext-from-another-copy",
+    };
+    expect(() => assertNoSecretLeak({ payload: foreign })).toThrow(/leaked.*payload/);
+  });
 });

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,

package/src/testing/index.ts

@@ -1,7 +1,16 @@
-// Test-Assertions, Domain-Test-Fixtures und Vitest-spezifische Helpers.
-// Production-Code (dev-server, bin/) darf NICHTS aus diesem Sub-Path importieren —
-// die Stack-Builder leben in `@cosmicdrift/kumiko-framework/stack`, dieses Modul darf
-// vitest-Imports top-level enthalten (siehe expect-error.ts).
+// Test assertions and domain test fixtures. Production code (dev-server, bin/)
+// must import nothing from this subpath — the stack builders live in
+// `@cosmicdrift/kumiko-framework/stack`.
+
+// The four cache/injection resets stay in their own modules (they close over
+// module-private state) and are only re-exported here — they are out of /crypto
+// and /db as of #1631. A production call to resetPiiSubjectKmsForTests() silently
+// switches the PII layer off, and subject-annotated fields are written in
+// plaintext from then on: no error, no log.
+export { resetBlindIndexKeyForTests } from "../crypto/blind-index";
+export { resetEventPiiCatalogForTests } from "../crypto/event-pii";
+export { resetPiiSubjectKmsForTests } from "../crypto/pii-field-encryption";
+export { resetEntityFieldEncryptionCacheForTests } from "../db/entity-field-encryption";
 
 export { rolesOf } from "./access-assertions";
 export { expectError, expectSuccess } from "./assertions";