@cosmicdrift/kumiko-framework 0.261.0 → 0.262.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.261.0",
+  "version": "0.262.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>",
@@ -198,7 +198,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.261.0",
+    "@cosmicdrift/kumiko-types": "0.262.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -214,7 +214,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.261.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.262.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.262.0",
+    "type": "improvement",
+    "title": "Boot validator warns when NODE_ENV=production boots without the security baseline (fw#2857).",
+    "detail": "`SECURITY_BASELINE_FEATURE_NAMES` (`@cosmicdrift/kumiko-framework/engine`) names the four security-relevant feature names the boot validator expects in a production app: `sessions`, `crypto-shredding`, `rate-limiting`, `audit`. `validateBoot` now calls `warnOnMissingSecurityBaseline(features)` (`engine/boot-validator/security-baseline.ts`) after every other check; when `process.env.NODE_ENV === \"production\"` and one or more of those feature names is absent from the mounted feature list (matched by exact `FeatureDefinition.name`, not by require-chain inference), it logs one `console.warn` naming the missing feature(s) and pointing at `securityBaselineFeatures()`. It never throws and is a no-op for any other `NODE_ENV` value (including `undefined`). Mount `securityBaselineFeatures()` from `@cosmicdrift/kumiko-bundled-features/presets` to silence it.",
+    "migration": "No action required for existing apps outside production. Apps that boot with `NODE_ENV=production` and don't already mount `sessions`/`crypto-shredding`/`rate-limiting`/`audit` will see a new boot-time `console.warn` — mount the missing feature(s) individually or via `securityBaselineFeatures()` to remove it."
+  },
   {
     "version": "0.261.0",
     "type": "breaking",

package/src/engine/boot-validator/__tests__/security-baseline.test.ts

@@ -0,0 +1,107 @@
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import { defineFeature } from "../../define-feature";
+import type { FeatureDefinition } from "../../types";
+import { validateBoot } from "../index";
+import {
+  SECURITY_BASELINE_FEATURE_NAMES,
+  warnOnMissingSecurityBaseline,
+} from "../security-baseline";
+
+function stubFeature(name: string): FeatureDefinition {
+  return defineFeature(name, () => {});
+}
+
+describe("warnOnMissingSecurityBaseline", () => {
+  let warnSpy: ReturnType<typeof spyOn<Console, "warn">>;
+
+  beforeEach(() => {
+    warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    warnSpy.mockRestore();
+  });
+
+  test("production + no baseline features → warns once, naming all four", () => {
+    warnOnMissingSecurityBaseline([], "production");
+
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    const msg = String(warnSpy.mock.calls[0]?.[0]);
+    for (const name of SECURITY_BASELINE_FEATURE_NAMES) {
+      expect(msg).toContain(name);
+    }
+  });
+
+  test("production + only sessions/audit mounted → warns about the missing two only", () => {
+    const features = [stubFeature("sessions"), stubFeature("audit")];
+
+    warnOnMissingSecurityBaseline(features, "production");
+
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    const msg = String(warnSpy.mock.calls[0]?.[0]);
+    expect(msg).toContain("crypto-shredding");
+    expect(msg).toContain("rate-limiting");
+    expect(msg).not.toContain("missing feature(s): sessions");
+  });
+
+  test("production + all four baseline features mounted → no warning", () => {
+    const features = SECURITY_BASELINE_FEATURE_NAMES.map((name) => stubFeature(name));
+
+    warnOnMissingSecurityBaseline(features, "production");
+
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  test.each(["development", "test", undefined])(
+    "nodeEnv=%p + no baseline features → no warning",
+    (nodeEnv) => {
+      warnOnMissingSecurityBaseline([], nodeEnv);
+
+      expect(warnSpy).not.toHaveBeenCalled();
+    },
+  );
+
+  test("never throws, regardless of nodeEnv or mounted features", () => {
+    expect(() => warnOnMissingSecurityBaseline([], "production")).not.toThrow();
+    expect(() => warnOnMissingSecurityBaseline([], "development")).not.toThrow();
+    expect(() =>
+      warnOnMissingSecurityBaseline(
+        SECURITY_BASELINE_FEATURE_NAMES.map((name) => stubFeature(name)),
+        "production",
+      ),
+    ).not.toThrow();
+  });
+});
+
+describe("validateBoot + security baseline warning", () => {
+  const originalNodeEnv = process.env["NODE_ENV"];
+  let warnSpy: ReturnType<typeof spyOn<Console, "warn">>;
+
+  beforeEach(() => {
+    warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    warnSpy.mockRestore();
+    if (originalNodeEnv === undefined) {
+      delete process.env["NODE_ENV"];
+    } else {
+      process.env["NODE_ENV"] = originalNodeEnv;
+    }
+  });
+
+  test("production boot with all four baseline stubs mounted does not throw and does not warn", () => {
+    process.env["NODE_ENV"] = "production";
+    const features = SECURITY_BASELINE_FEATURE_NAMES.map((name) => stubFeature(name));
+
+    expect(() => validateBoot(features)).not.toThrow();
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  test("production boot with no baseline features mounted warns but does not throw", () => {
+    process.env["NODE_ENV"] = "production";
+
+    expect(() => validateBoot([])).not.toThrow();
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+  });
+});

package/src/engine/boot-validator/index.ts

@@ -61,6 +61,7 @@ import {
   validateScreenShortIdCollisions,
   validateScreens,
 } from "./screens";
+import { warnOnMissingSecurityBaseline } from "./security-baseline";
 import {
   collectWorkspaceQns,
   validateDefaultWorkspaceUniqueness,
@@ -72,6 +73,7 @@ export { validateAppCustomScreenWriteQns } from "./custom-screen-write-qns";
 // an den Codegen zu übergeben. Nicht Teil von validateBoot, aber
 // dieselbe Extraktionslogik.
 export { collectWriteHandlerQns } from "./nav";
+export { SECURITY_BASELINE_FEATURE_NAMES } from "./security-baseline";
 
 export type ValidateBootOptions = {
   /** Warn when an access role is used by exactly one handler/config-key/
@@ -254,6 +256,7 @@ export function validateBoot(
 
   validateConfigReads(features, allConfigKeys);
   warnOnToggleableDependencies(features, featureMap);
+  warnOnMissingSecurityBaseline(features);
   if (options?.warnOnUniqueAccessRoles === true) {
     warnOnUniqueAccessRoles(features);
   }

package/src/engine/boot-validator/security-baseline.ts

@@ -0,0 +1,26 @@
+import type { FeatureDefinition } from "../types";
+
+export const SECURITY_BASELINE_FEATURE_NAMES = [
+  "sessions",
+  "crypto-shredding",
+  "rate-limiting",
+  "audit",
+] as const;
+
+export function warnOnMissingSecurityBaseline(
+  features: readonly FeatureDefinition[],
+  nodeEnv: string | undefined = process.env["NODE_ENV"],
+): void {
+  // skip: baseline is only enforced for production boots
+  if (nodeEnv !== "production") return;
+
+  const mountedNames = new Set(features.map((f) => f.name));
+  const missing = SECURITY_BASELINE_FEATURE_NAMES.filter((name) => !mountedNames.has(name));
+  // skip: every baseline feature is mounted
+  if (missing.length === 0) return;
+
+  // biome-ignore lint/suspicious/noConsole: boot-time hint, no logger available yet
+  console.warn(
+    `[kumiko:boot] NODE_ENV=production but the security baseline is incomplete — missing feature(s): ${missing.join(", ")}. Mount securityBaselineFeatures() from @cosmicdrift/kumiko-bundled-features/presets (or the missing features individually).`,
+  );
+}

package/src/engine/boot-validator.ts

@@ -1,5 +1,6 @@
 export {
   collectWriteHandlerQns,
+  SECURITY_BASELINE_FEATURE_NAMES,
   type ValidateBootOptions,
   validateAppCustomScreenWriteQns,
   validateBoot,

package/src/engine/index.ts

@@ -3,6 +3,7 @@
 export { hasAccess } from "./access";
 export {
   collectWriteHandlerQns,
+  SECURITY_BASELINE_FEATURE_NAMES,
   validateAppCustomScreenWriteQns,
   validateBoot,
 } from "./boot-validator";