@cosmicdrift/kumiko-server-runtime 0.165.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-server-runtime",
-  "version": "0.165.0",
+  "version": "2.0.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>",
@@ -72,8 +72,8 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.165.0",
-    "@cosmicdrift/kumiko-framework": "0.165.0",
+    "@cosmicdrift/kumiko-bundled-features": "2.0.0",
+    "@cosmicdrift/kumiko-framework": "2.0.0",
     "temporal-polyfill": "^0.3.2"
   },
   "publishConfig": {

package/src/__tests__/boot-probe-fixture.ts

@@ -0,0 +1,63 @@
+// Shared fixture for run-prod-app-{dry-run,env-source}.test.ts — both boot
+// runProdApp against a minimal probe feature with process.env cleared so the
+// test fully controls config via envSource. Table/feature name stay
+// parametrized (never collapsed to one shared fixture): a table clash
+// between the two test files' entities would surface as flaky cross-file
+// DB state, not a compile error.
+import { afterEach, beforeEach } from "bun:test";
+import {
+  createBooleanField,
+  createEntity,
+  createTextField,
+  defineFeature,
+  type FeatureDefinition,
+  type FeatureRegistrar,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+
+export function makeProbeFeature(opts: {
+  readonly name: string;
+  readonly table: string;
+  readonly extraSetup?: (r: FeatureRegistrar<string>) => void;
+}): FeatureDefinition {
+  const probeEntity = createEntity({
+    fields: {
+      name: createTextField({ required: true }),
+      active: createBooleanField({ default: true }),
+    },
+    table: opts.table,
+  });
+  return defineFeature(opts.name, (r) => {
+    r.entity("widget", probeEntity);
+    opts.extraSetup?.(r);
+    r.queryHandler({
+      name: "ping",
+      schema: z.object({}),
+      access: { roles: ["anonymous"] },
+      handler: async () => ({ pong: true }),
+    });
+  });
+}
+
+// DATABASE_URL/REDIS_URL/JWT_SECRET are required (their read throws
+// pre-#1441-fix boot bugs); PORT is non-throwing, cleared only so ambient
+// PORT can't mask an "envSource wins" assertion.
+export const CLEARED_BOOT_VARS = ["DATABASE_URL", "REDIS_URL", "JWT_SECRET", "PORT"] as const;
+
+// Registers beforeEach/afterEach for the current describe block — call this
+// at the top of a `describe(...)` body, same as calling beforeEach directly.
+export function withClearedBootEnv(): void {
+  const saved: Record<string, string | undefined> = {};
+  beforeEach(() => {
+    for (const k of CLEARED_BOOT_VARS) {
+      saved[k] = process.env[k];
+      delete process.env[k];
+    }
+  });
+  afterEach(() => {
+    for (const k of CLEARED_BOOT_VARS) {
+      if (saved[k] === undefined) delete process.env[k];
+      else process.env[k] = saved[k];
+    }
+  });
+}

package/src/__tests__/run-prod-app-dry-run.test.ts

@@ -1,53 +1,21 @@
 // Dry-run + bootErrorReporter paths — no DB/Redis. envSource avoids process.exit(0).
 
-import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import {
-  createBooleanField,
-  createEntity,
-  createTextField,
-  defineFeature,
-} from "@cosmicdrift/kumiko-framework/engine";
+import { describe, expect, test } from "bun:test";
 import { composeEnvSchema, KumikoBootError } from "@cosmicdrift/kumiko-framework/env";
 import { z } from "zod";
 import { runProdApp } from "../run-prod-app";
+import { makeProbeFeature, withClearedBootEnv } from "./boot-probe-fixture";
 
-const probeEntity = createEntity({
-  fields: {
-    name: createTextField({ required: true }),
-    active: createBooleanField({ default: true }),
-  },
+const probeFeature = makeProbeFeature({
+  name: "dry-run-probe",
   table: "dry_run_probe",
+  extraSetup: (r) => {
+    r.envSchema(z.object({ DRY_RUN_PROBE: z.string().optional().describe("probe var") }));
+  },
 });
 
-const probeFeature = defineFeature("dry-run-probe", (r) => {
-  r.entity("widget", probeEntity);
-  r.envSchema(z.object({ DRY_RUN_PROBE: z.string().optional().describe("probe var") }));
-  r.queryHandler({
-    name: "ping",
-    schema: z.object({}),
-    access: { roles: ["anonymous"] },
-    handler: async () => ({ pong: true }),
-  });
-});
-
-const CLEARED = ["DATABASE_URL", "REDIS_URL", "JWT_SECRET", "PORT"] as const;
-
 describe("runProdApp dry-run / bootErrorReporter", () => {
-  const saved: Record<string, string | undefined> = {};
-
-  beforeEach(() => {
-    for (const k of CLEARED) {
-      saved[k] = process.env[k];
-      delete process.env[k];
-    }
-  });
-
-  afterEach(() => {
-    for (const k of CLEARED) {
-      if (saved[k] === undefined) delete process.env[k];
-      else process.env[k] = saved[k];
-    }
-  });
+  withClearedBootEnv();
 
   test("KUMIKO_DRY_RUN_ENV=human + envSource → render + dry-run handle (no exit)", async () => {
     const logs: string[] = [];
@@ -69,7 +37,7 @@ describe("runProdApp dry-run / bootErrorReporter", () => {
       console.log = originalLog;
     }
 
-    expect(logs.some((l) => l.includes("DRY_RUN_PROBE") || l.includes("Optional"))).toBe(true);
+    expect(logs.some((l) => l.includes("DRY_RUN_PROBE"))).toBe(true);
     const res = await handle!.fetch(new Request("http://test/"));
     expect(res.status).toBe(503);
     expect(await res.text()).toBe("dry-run");
@@ -95,9 +63,14 @@ describe("runProdApp dry-run / bootErrorReporter", () => {
     } finally {
       console.log = originalLog;
     }
-    const joined = logs.join("\n");
-    expect(joined).toContain("required");
-    expect(joined).toContain("optional");
+    const jsonLine = logs.find((l) => l.trimStart().startsWith("{"));
+    if (!jsonLine) throw new Error(`No JSON line in logs: ${JSON.stringify(logs)}`);
+    const parsed = JSON.parse(jsonLine) as {
+      optional: Array<{ name: string; feature: string }>;
+    };
+    expect(parsed.optional).toContainEqual(
+      expect.objectContaining({ name: "DRY_RUN_PROBE", feature: "dry-run-probe" }),
+    );
   });
 
   test("unrecognized KUMIKO_DRY_RUN_ENV warns then hits envSchema parse", async () => {
@@ -126,7 +99,11 @@ describe("runProdApp dry-run / bootErrorReporter", () => {
     } finally {
       console.warn = originalWarn;
     }
-    expect(warnings.some((w) => w.includes("unrecognized"))).toBe(true);
+    expect(
+      warnings.some(
+        (w) => w.includes('KUMIKO_DRY_RUN_ENV="not-a-real-mode"') && w.includes("unrecognized"),
+      ),
+    ).toBe(true);
   });
 
   test("bootErrorReporter receives KumikoBootError instead of process.exit", async () => {

package/src/__tests__/run-prod-app-env-source.test.ts

@@ -6,40 +6,15 @@
 // required-var test would throw "required env var DATABASE_URL is missing" and
 // the PORT test would bind the default instead of the injected port.
 
-import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import {
-  createBooleanField,
-  createEntity,
-  createTextField,
-  defineFeature,
-} from "@cosmicdrift/kumiko-framework/engine";
-import { z } from "zod";
+import { describe, expect, test } from "bun:test";
 import { runProdApp } from "../run-prod-app";
+import { makeProbeFeature, withClearedBootEnv } from "./boot-probe-fixture";
 
-const probeEntity = createEntity({
-  fields: {
-    name: createTextField({ required: true }),
-    active: createBooleanField({ default: true }),
-  },
+const probeFeature = makeProbeFeature({
+  name: "env-source-probe",
   table: "env_source_probe",
 });
 
-const probeFeature = defineFeature("env-source-probe", (r) => {
-  r.entity("widget", probeEntity);
-  r.queryHandler({
-    name: "ping",
-    schema: z.object({}),
-    access: { roles: ["anonymous"] },
-    handler: async () => ({ pong: true }),
-  });
-});
-
-// Cleared from process.env so the test fully controls config via envSource.
-// DATABASE_URL/REDIS_URL/JWT_SECRET are required (their read throws pre-fix);
-// PORT is non-throwing, cleared only so ambient PORT can't mask the second
-// test's "PORT comes from envSource" assertion.
-const CLEARED_VARS = ["DATABASE_URL", "REDIS_URL", "JWT_SECRET", "PORT"] as const;
-
 const DUMMY_ENV = {
   KUMIKO_DRY_RUN_ENV: "boot",
   DATABASE_URL: "postgres://smoke:smoke@127.0.0.1:1/smoke",
@@ -48,21 +23,7 @@ const DUMMY_ENV = {
 } as const;
 
 describe("runProdApp boot-mode env-source", () => {
-  const saved: Record<string, string | undefined> = {};
-
-  beforeEach(() => {
-    for (const k of CLEARED_VARS) {
-      saved[k] = process.env[k];
-      delete process.env[k];
-    }
-  });
-
-  afterEach(() => {
-    for (const k of CLEARED_VARS) {
-      if (saved[k] === undefined) delete process.env[k];
-      else process.env[k] = saved[k];
-    }
-  });
+  withClearedBootEnv();
 
   test("boots from injected envSource even when process.env lacks the required vars", async () => {
     const logs: string[] = [];

package/src/__tests__/run-prod-app-static-files.test.ts

@@ -63,6 +63,14 @@ describe("readStaticFile / serveDiskFile", () => {
     expect(await readStaticFile(dirPath)).toBeUndefined();
   });
 
+  test("readStaticFile through a file used as a directory segment → undefined (ENOTDIR), not a throw (#1504)", async () => {
+    const path = join(tmp, "index.html");
+    await writeFile(path, "<html/>");
+    // GET /index.html/x — "index.html" is a file, so treating it as a
+    // directory segment must fall through to the SPA fallback, not 500.
+    expect(await readStaticFile(join(path, "x"))).toBeUndefined();
+  });
+
   test("serveDiskFile sets content-type from mime", async () => {
     const path = join(tmp, "a.svg");
     await writeFile(path, "<svg/>");

package/src/__tests__/run-prod-app.integration.test.ts

@@ -280,7 +280,12 @@ describe("runProdApp", () => {
       if (original === undefined) delete process.env["KUMIKO_DRY_RUN_ENV"];
       else process.env["KUMIKO_DRY_RUN_ENV"] = original;
     }
-    expect(warnings.some((line) => line.includes("unrecognized"))).toBe(true);
+    expect(
+      warnings.some(
+        (line) =>
+          line.includes('KUMIKO_DRY_RUN_ENV="not-a-real-mode"') && line.includes("unrecognized"),
+      ),
+    ).toBe(true);
   });
 
   test("second boot against the same DB is idempotent — no crash, no duplicate tables", async () => {

package/src/run-prod-app-static-files.ts

@@ -45,10 +45,12 @@ export async function readStaticFile(
   } catch (err) {
     const code = (err as { code?: string }).code;
     // ENOENT: no such path. EISDIR: readFile() on a directory (e.g. GET
-    // /assets where "assets" is a subfolder copied verbatim from public/)
-    // — both mean "not a servable file", so fall through to the SPA
+    // /assets where "assets" is a subfolder copied verbatim from public/).
+    // ENOTDIR: a path segment that isn't a directory is used as one (e.g.
+    // GET /index.html/x — "index.html" is a file, not a directory) — all
+    // three mean "not a servable file", so fall through to the SPA
     // fallback instead of a 500.
-    if (code === "ENOENT" || code === "EISDIR") return undefined;
+    if (code === "ENOENT" || code === "EISDIR" || code === "ENOTDIR") return undefined;
     throw err;
   }
 }

package/src/run-prod-app.ts

@@ -27,6 +27,15 @@
 //   JWT_SECRET_V1=<random-32+>  (repeat _V2, _V3, ... per rotation)
 //   JWT_SECRET_CURRENT_VERSION=1  (which V<n> signs new tokens; the others
 //     still verify in-flight tokens until they expire)
+//   Adopting rotation for the first time (no JWT_SECRET_V<n> set yet): the
+//   plain JWT_SECRET above stays set and is carried into the keyring as a
+//   verify-only legacy key (loadJwtSecretOrKeyring), so sessions signed
+//   before the cutover keep verifying — no mass-logout at adoption. This
+//   legacy key never expires on its own (boot logs a warning while it's
+//   present) — once max token TTL has elapsed since cutover, unset
+//   JWT_SECRET to retire it. Check first whether an app relies on the
+//   auth.mail convenience default for passwordReset/emailVerification
+//   hmacSecret (falls back to this same JWT_SECRET) before unsetting it.
 //   PORT=3000
 //   KUMIKO_INSTANCE_ID=<stable per replica>
 
@@ -335,6 +344,13 @@ export type RunProdAppAuthOptions = {
    *  — accept the wide-cookie CSRF risk explicitly instead of setting
    *  `allowedOrigins`. */
   readonly unsafeSkipOriginCheck?: boolean;
+  /** Number of trusted reverse-proxy hops between the client and this
+   *  process for client-IP derivation (see AuthRoutesConfig.trustedProxyHops,
+   *  kumiko-framework#1539) — closes the X-Forwarded-For spoofing hole on
+   *  the auth rate-limiters. Falls back to the `KUMIKO_TRUSTED_PROXY_HOPS`
+   *  env var when unset; both unset means the pre-#1539 spoofable default
+   *  (0 hops). Set this to your real ingress hop count (typically 1). */
+  readonly trustedProxyHops?: number;
 };
 
 /** Hook for app-specific seeding — runs after the admin (when auth is
@@ -609,6 +625,22 @@ export type ProdAppHandle = {
   readonly stop: () => Promise<void>;
 };
 
+let warnedLegacyJwtSecret = false;
+function warnLegacyJwtSecretOnce(): void {
+  // skip: already warned once this process — avoid log spam on every boot path.
+  if (warnedLegacyJwtSecret) return;
+  warnedLegacyJwtSecret = true;
+  // biome-ignore lint/suspicious/noConsole: boot-time ops hint, no logger configured this early
+  console.warn(
+    "[runProdApp] JWT keyring carries a legacy (pre-rotation) verify-only key — " +
+      "it never expires on its own. JWT_SECRET remains a required env (hmacSecret " +
+      "fallback + boot requireEnv). To stop verifying with the pre-rotation secret: " +
+      "set auth.mail.hmacSecret explicitly, then rotate JWT_SECRET to a fresh value " +
+      "that is no longer present in any in-flight token (see resolveAuthMail / " +
+      "loadJwtSecretOrKeyring).",
+  );
+}
+
 export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHandle> {
   // 0. Env-Schema validation + dry-run modes. Runs FIRST so:
   //    - operators can introspect env-requirements without a real boot
@@ -679,8 +711,36 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
   // rotation of the session-JWT signing key — see loadJwtSecretOrKeyring.
   const jwtSecret = requireEnv("JWT_SECRET", envSource);
   const jwtSecretOrKeyring = loadJwtSecretOrKeyring(envSource);
+  if (typeof jwtSecretOrKeyring === "object" && Object.hasOwn(jwtSecretOrKeyring.keys, "legacy")) {
+    // Once per process — JWT_SECRET stays a required env (requireEnv above +
+    // resolveAuthMail hmacSecret fallback). Retiring the *legacy verify key*
+    // means setting auth.mail.hmacSecret explicitly and rotating JWT_SECRET
+    // to a fresh value that is no longer in any in-flight token; unsetting
+    // JWT_SECRET entirely hard-crashes boot.
+    warnLegacyJwtSecretOnce();
+  }
   const jwtIssuer = readEnv("JWT_ISSUER", envSource);
   const instanceId = readEnv("KUMIKO_INSTANCE_ID", envSource);
+  // kumiko-framework#1539 — options.auth.trustedProxyHops wins; falls back
+  // to the env var so ops can close the XFF-spoofing hole per-deployment
+  // without a code change (mirrors instanceId's env-first pattern above).
+  // Fail loud on a garbage env value rather than silently coercing to NaN:
+  // clientIpOf treats NaN like "always short chain" and returns "unknown"
+  // for every request, which collapses mfa-verify/preauth-confirm's
+  // pure-IP-keyed rate limiter into one shared bucket for the whole
+  // deployment — a self-inflicted DoS, worse than staying on the default.
+  const trustedProxyHopsFromEnv = readEnv("KUMIKO_TRUSTED_PROXY_HOPS", envSource);
+  const trustedProxyHops = ((): number | undefined => {
+    if (options.auth?.trustedProxyHops !== undefined) return options.auth.trustedProxyHops;
+    if (trustedProxyHopsFromEnv === undefined) return undefined;
+    const parsed = Number.parseInt(trustedProxyHopsFromEnv, 10);
+    if (!Number.isInteger(parsed) || parsed < 0) {
+      throw new Error(
+        `runProdApp: KUMIKO_TRUSTED_PROXY_HOPS must be a non-negative integer, got "${trustedProxyHopsFromEnv}".`,
+      );
+    }
+    return parsed;
+  })();
   const port = options.port ?? Number.parseInt(envSource["PORT"] ?? "3000", 10);
 
   // biome-ignore lint/suspicious/noConsole: boot-time progress hint, no logger configured this early
@@ -953,6 +1013,7 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
         ...(effectiveAuth.unsafeSkipOriginCheck !== undefined && {
           unsafeSkipOriginCheck: effectiveAuth.unsafeSkipOriginCheck,
         }),
+        ...(trustedProxyHops !== undefined && { trustedProxyHops }),
         ...sessionAuthFragment,
         ...patAuthFragment,
         ...tenantLifecycleAuthFragment,
@@ -966,6 +1027,12 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
             undefined,
             "mfa-verify",
           ),
+          mfaPreauthEnableStartRateLimit: createRedisLoginRateLimiter(
+            redis,
+            undefined,
+            undefined,
+            "mfa-preauth-start",
+          ),
           mfaPreauthConfirmRateLimit: createRedisLoginRateLimiter(
             redis,
             undefined,