@cosmicdrift/kumiko-server-runtime 0.290.0 → 0.291.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-server-runtime",
-  "version": "0.290.0",
+  "version": "0.291.0",
   "description": "Production server-boot runtime for Kumiko apps: connections, schema-drift-gate, seeds, lifecycle, graceful shutdown. Symmetric to kumiko-dev-server's runDevApp, without dev/scaffold/codegen tooling.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -80,9 +80,9 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.290.0",
-    "@cosmicdrift/kumiko-framework": "0.290.0",
-    "@cosmicdrift/kumiko-headless": "0.290.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.291.0",
+    "@cosmicdrift/kumiko-framework": "0.291.0",
+    "@cosmicdrift/kumiko-headless": "0.291.0",
     "temporal-polyfill": "^0.3.2"
   },
   "publishConfig": {

package/src/__tests__/pii-boot-gate.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import { InMemoryKmsAdapter } from "@cosmicdrift/kumiko-framework/crypto";
 import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
 import { assertPiiBootInvariants } from "../pii-boot-gate";
 
 const piiFeature = defineFeature("gate-pii", (r) => {
@@ -22,6 +23,17 @@ const plainFeature = defineFeature("gate-plain", (r) => {
   );
 });
 
+// Entity-free features: the gate must react to the event stance on its own,
+// not ride along on an entity annotation (fw#2776).
+const piiEventFeature = defineFeature("gate-pii-event", (r) => {
+  r.defineEvent("attempt", z.object({ userId: z.string(), email: z.string() }), {
+    piiFields: { email: { personal: { of: "userId" } } },
+  });
+});
+const noneEventFeature = defineFeature("gate-none-event", (r) => {
+  r.defineEvent("ping", z.object({ at: z.string() }), { piiFields: "none" });
+});
+
 const kms = new InMemoryKmsAdapter();
 const KEY = Buffer.alloc(32, 7).toString("base64");
 
@@ -56,6 +68,31 @@ describe("assertPiiBootInvariants — prod", () => {
   test("no PII entities → nothing to gate", () => {
     expect(() => assertPiiBootInvariants([plainFeature], { mode: "prod" })).not.toThrow();
   });
+
+  test('an entity-free feature with a non-"none" event stance aborts boot without a KMS', () => {
+    expect(() => assertPiiBootInvariants([piiEventFeature], { mode: "prod" })).toThrow(
+      /BOOT ABORTED.*gate-pii-event:event:attempt.*PLAINTEXT/s,
+    );
+  });
+
+  test('events declaring piiFields: "none" are not gated', () => {
+    expect(() => assertPiiBootInvariants([noneEventFeature], { mode: "prod" })).not.toThrow();
+  });
+
+  test("a KMS satisfies the event gate", () => {
+    expect(() =>
+      assertPiiBootInvariants([piiEventFeature], { mode: "prod", kms, blindIndexKey: KEY }),
+    ).not.toThrow();
+  });
+
+  test("allowPlaintextPii acknowledges the event gate too", () => {
+    expect(() =>
+      assertPiiBootInvariants([piiEventFeature], {
+        mode: "prod",
+        allowPlaintextPii: "kms rollout pending",
+      }),
+    ).not.toThrow();
+  });
 });
 
 describe("assertPiiBootInvariants — dev", () => {
@@ -68,4 +105,8 @@ describe("assertPiiBootInvariants — dev", () => {
       /blindIndexKey/,
     );
   });
+
+  test("a PII event without a KMS only warns in dev", () => {
+    expect(() => assertPiiBootInvariants([piiEventFeature], { mode: "dev" })).not.toThrow();
+  });
 });

package/src/__tests__/run-worker-app-boot.test.ts

@@ -3,7 +3,7 @@
 // exits BEFORE any connection, and the KMS health gate runs BEFORE
 // createDbConnection/new Redis(...) — so neither path needs real infra.
 
-import { describe, expect, test } from "bun:test";
+import { describe, expect, spyOn, test } from "bun:test";
 import type { KmsAdapter } from "@cosmicdrift/kumiko-framework/crypto";
 import { runWorkerApp } from "../run-worker-app";
 import { makeProbeFeature, withClearedBootEnv } from "./boot-probe-fixture";
@@ -96,4 +96,40 @@ describe("runWorkerApp boot-mode", () => {
     }
     expect(healthChecked).toBe(true);
   });
+
+  test("validateBootOptions reaches validateBoot — an opt-in warning fires only when passed", async () => {
+    // Reach-the-boot proof, not an acceptance proof: the probe feature's
+    // single "anonymous" handler makes warnOnUniqueAccessRoles emit a
+    // warning naming that role, and validateBoot emits it only when the
+    // option arrives (fw#3080).
+    const originalLog = console.log;
+    console.log = () => {};
+    const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+    const roleWarnings = (): string[] =>
+      warnSpy.mock.calls
+        .map((call) => String(call[0]))
+        .filter((line) => line.includes('Access role "anonymous"'));
+    try {
+      const withOption = await runWorkerApp({
+        features: [probeFeature],
+        migrations: false,
+        validateBootOptions: { warnOnUniqueAccessRoles: true },
+        envSource: { ...DUMMY_ENV, KUMIKO_DRY_RUN_ENV: "boot" },
+      });
+      await withOption.stop();
+      expect(roleWarnings().length).toBeGreaterThan(0);
+
+      warnSpy.mockClear();
+      const withoutOption = await runWorkerApp({
+        features: [probeFeature],
+        migrations: false,
+        envSource: { ...DUMMY_ENV, KUMIKO_DRY_RUN_ENV: "boot" },
+      });
+      await withoutOption.stop();
+      expect(roleWarnings()).toEqual([]);
+    } finally {
+      warnSpy.mockRestore();
+      console.log = originalLog;
+    }
+  });
 });

package/src/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.291.0",
+    "type": "fix",
+    "title": "runProdApp, runDevApp and runWorkerApp forward validateBootOptions to validateBoot (fw#3080)",
+    "detail": "All three run-app entrypoints called `validateBoot(features)` without options, so only `createApp` could pass a `navAllowlist` or `warnOnUniqueAccessRoles` through. An app could declare the option, test it against `validateBoot` directly and see green — while the process it actually boots never received it. The three option types now carry an optional `validateBootOptions`, passed straight through in the same shape `createApp` already uses. `ValidateBootOptions` is exported from `@cosmicdrift/kumiko-framework/engine` so consumers can type the value. Omitting it leaves boot behaviour unchanged."
+  },
   {
     "version": "0.289.0",
     "type": "improvement",

package/src/pii-boot-gate.ts

@@ -39,13 +39,29 @@ export function assertPiiBootInvariants(
       .filter(([, entity]) => collectPiiSubjectFields(entity).length > 0)
       .map(([name]) => name),
   );
-  // skip: no PII-annotated entities mounted — plaintext gate is moot.
-  if (piiEntities.length === 0) return;
+  // fw#2776: a declared event stance is worth as much as an entity annotation —
+  // encryptEventPayloadPii no-ops without a KMS, so a catalogued event writes
+  // plaintext PII into kumiko_events with nothing to crypto-shred later.
+  const piiEvents = features.flatMap((feature) =>
+    Object.values(feature.events ?? {})
+      .filter((event) => event.piiFields !== undefined && event.piiFields !== "none")
+      .map((event) => event.name),
+  );
+  // skip: nothing PII-annotated is mounted — plaintext gate is moot.
+  if (piiEntities.length === 0 && piiEvents.length === 0) return;
+  const carriers = [
+    ...(piiEntities.length > 0 ? [`${piiEntities.length} entities`] : []),
+    ...(piiEvents.length > 0 ? [`${piiEvents.length} events`] : []),
+  ].join(" and ");
+  const named = [
+    ...(piiEntities.length > 0 ? [`entities [${piiEntities.join(", ")}]`] : []),
+    ...(piiEvents.length > 0 ? [`events [${piiEvents.join(", ")}]`] : []),
+  ].join(" and ");
 
   if (opts.mode === "dev") {
     // biome-ignore lint/suspicious/noConsole: boot-time security warning
     console.warn(
-      `[${tag}] ${piiEntities.length} entities carry pii/userOwned/tenantOwned/recordOwned annotations but no \`kms\` adapter is configured — fields are stored in PLAINTEXT locally. Pass { kms: new InMemoryKmsAdapter() } (ephemeral DB) or createPgKmsAdapter(...) to exercise crypto-shredding in dev.`,
+      `[${tag}] ${carriers} carry pii/userOwned/tenantOwned/recordOwned annotations or a non-"none" defineEvent PII stance but no \`kms\` adapter is configured — fields are stored in PLAINTEXT locally. Pass { kms: new InMemoryKmsAdapter() } (ephemeral DB) or createPgKmsAdapter(...) to exercise crypto-shredding in dev.`,
     );
     // skip: dev mode, plaintext-PII warning already logged above
     return;
@@ -53,12 +69,12 @@ export function assertPiiBootInvariants(
   if (opts.allowPlaintextPii) {
     // biome-ignore lint/suspicious/noConsole: boot-time security warning
     console.warn(
-      `[${tag}] ${piiEntities.length} entities carry PII annotations but no \`kms\` adapter is configured — fields are stored in PLAINTEXT (allowPlaintextPii: "${opts.allowPlaintextPii}"). GDPR erasure via crypto-shredding is NOT possible until a KMS is provisioned.`,
+      `[${tag}] ${carriers} carry PII annotations but no \`kms\` adapter is configured — fields are stored in PLAINTEXT (allowPlaintextPii: "${opts.allowPlaintextPii}"). GDPR erasure via crypto-shredding is NOT possible until a KMS is provisioned.`,
     );
     // skip: operator explicitly acknowledged plaintext PII via allowPlaintextPii, warning already logged above
     return;
   }
   throw new Error(
-    `[${tag}] BOOT ABORTED — entities [${piiEntities.join(", ")}] carry pii/userOwned/tenantOwned/recordOwned annotations but no \`kms\` adapter is configured. The fields would be stored in PLAINTEXT and GDPR erasure (crypto-shredding) could not work. Pass runProdApp({ kms: createPgKmsAdapter({ databaseUrl, platformKek }) }) — or acknowledge explicitly with { allowPlaintextPii: "<reason>" } until your KMS is provisioned.`,
+    `[${tag}] BOOT ABORTED — ${named} carry pii/userOwned/tenantOwned/recordOwned annotations or a non-"none" defineEvent PII stance but no \`kms\` adapter is configured. The fields would be stored in PLAINTEXT and GDPR erasure (crypto-shredding) could not work. Pass runProdApp({ kms: createPgKmsAdapter({ databaseUrl, platformKek }) }) — or acknowledge explicitly with { allowPlaintextPii: "<reason>" } until your KMS is provisioned.`,
   );
 }

package/src/run-prod-app.ts

@@ -95,6 +95,7 @@ import {
   type FeatureDefinition,
   findTierResolverUsage,
   type TierResolverPlugin,
+  type ValidateBootOptions,
   validateAppCustomScreenWriteQns,
   validateBoot,
 } from "@cosmicdrift/kumiko-framework/engine";
@@ -443,6 +444,8 @@ export type RunProdAppOptions = {
   /** App-specific features. config/user/tenant/auth-email-password are
    *  auto-mixed when `auth:` is set — don't add them yourself. */
   readonly features: readonly FeatureDefinition[];
+  /** Opt-in boot-validator warnings — see ValidateBootOptions. */
+  readonly validateBootOptions?: ValidateBootOptions;
   /** Listen-Port. Default 3000 (or $PORT). */
   readonly port?: number;
   /** Auth-mode: standard features + routes wired, admin seeded. */
@@ -815,7 +818,7 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
     ...(composeAuthOptions && { authOptions: composeAuthOptions }),
   });
 
-  validateBoot(features);
+  validateBoot(features, options.validateBootOptions);
   warnIfNonUtcServerTimeZone();
   validateAppCustomScreenWriteQns(process.cwd(), collectWriteHandlerQns(features));
   assertPiiBootInvariants(features, {

package/src/run-worker-app.ts

@@ -33,6 +33,7 @@ import {
   findTierResolverUsage,
   type Registry,
   type TierResolverPlugin,
+  type ValidateBootOptions,
   validateBoot,
 } from "@cosmicdrift/kumiko-framework/engine";
 import {
@@ -87,6 +88,8 @@ export type RunWorkerAppOptions = {
   /** App-specific features — same array as in the API/all-in-one process,
    *  so the registry + schema stay identical across processes. */
   readonly features: readonly FeatureDefinition[];
+  /** Opt-in boot-validator warnings — see ValidateBootOptions. */
+  readonly validateBootOptions?: ValidateBootOptions;
   /** Mount the auto-mixed config/user/tenant/auth-email-password features —
    *  MUST match the API process's `includeBundled` value, otherwise API
    *  and worker run with a diverging registry topology. Also controls
@@ -177,7 +180,7 @@ export async function runWorkerApp(options: RunWorkerAppOptions): Promise<Worker
   const features = composeFeatures(options.features, {
     includeBundled: !!options.includeBundled,
   });
-  validateBoot(features);
+  validateBoot(features, options.validateBootOptions);
   warnIfNonUtcServerTimeZone();
   assertPiiBootInvariants(features, {
     kms: options.kms,