@cosmicdrift/kumiko-server-runtime 0.320.0 → 0.322.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-server-runtime",
-  "version": "0.320.0",
+  "version": "0.322.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>",
@@ -76,9 +76,9 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.320.0",
-    "@cosmicdrift/kumiko-framework": "0.320.0",
-    "@cosmicdrift/kumiko-headless": "0.320.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.322.0",
+    "@cosmicdrift/kumiko-framework": "0.322.0",
+    "@cosmicdrift/kumiko-headless": "0.322.0",
     "temporal-polyfill": "^0.3.2"
   },
   "publishConfig": {

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

@@ -359,6 +359,27 @@ describe("runProdApp", () => {
     expect(body).toContain('<probe ok="true" />');
   });
 
+  test("handle.fetch threads the socket address into deps.clientIp, ignoring a spoofed X-Forwarded-For at the default trustedProxyHops (0)", async () => {
+    const handle = await boot(undefined, {
+      extraRoutes: [
+        {
+          method: "GET",
+          path: "/client-ip-probe",
+          entry: "anonymous",
+          handler: (c, deps) => c.body(deps.clientIp, 200),
+        },
+      ],
+    });
+    const req = () =>
+      new Request("http://test/client-ip-probe", { headers: { "x-forwarded-for": "1.2.3.4" } });
+
+    const withSocket = await handle.fetch(req(), "198.51.100.7");
+    expect(await withSocket.text()).toBe("198.51.100.7");
+
+    const withoutSocket = await handle.fetch(req());
+    expect(await withoutSocket.text()).toBe("unknown");
+  });
+
   test("extraRoutes: entry:signature dispatchSystemWrite schreibt als SystemAdmin des Ziel-Tenants, registry verfügbar", async () => {
     // Wiring for provider webhook routes (billing-foundation
     // createSubscriptionWebhookRoute): the route authenticates via

package/src/changes.json

@@ -1,4 +1,18 @@
 [
+  {
+    "version": "0.321.0",
+    "type": "improvement",
+    "title": "runProdApp's KUMIKO_TRUSTED_PROXY_HOPS parsing now shares framework's parseTrustedProxyHopsEnv",
+    "detail": "The inline digits-only + non-negative-integer validation moved out of\n`run-prod-app.ts` into `parseTrustedProxyHopsEnv`\n(`@cosmicdrift/kumiko-framework/api`); same validation and error message\nas before, no behavioral change.",
+    "migration": "No action needed."
+  },
+  {
+    "version": "0.321.0",
+    "type": "improvement",
+    "title": "ProdAppHandle.fetch's type now declares its optional socket-address parameter",
+    "detail": "`fetch: (req: Request, socketAddress?: string) => Promise<Response> |\nResponse`. The doc comment now explains that an app with `autoListen:\nfalse` running its own `Bun.serve` must pass\n`server.requestIP(req)?.address`, extracted at the outermost Bun fetch\ncallback — `requestIP()` only resolves for Bun's original Request\ninstance, not a cloned/rebuilt one. `RunProdAppAuthOptions\n.trustedProxyHops`'s doc comment also dropped the stale \"pre-#1539\nspoofable default\" wording; 0 hops is the safe socket-only default.",
+    "migration": "No action needed for the default `autoListen: true` boot. Apps with\n`autoListen: false` can now type-check passing the socket address to\n`handle.fetch`; passing nothing keeps the previous (unresolved) behavior."
+  },
   {
     "version": "0.320.0",
     "type": "breaking",

package/src/run-prod-app.ts

@@ -76,8 +76,10 @@ import {
   type LoginRateLimiter,
   loadJwtSecretOrKeyring,
   type PostAuthLandingResolver,
+  parseTrustedProxyHopsEnv,
   type SseBroker,
   type TokenVerifier,
+  TRUSTED_PROXY_HOPS_ENV,
 } from "@cosmicdrift/kumiko-framework/api";
 import {
   configureBlindIndexKey,
@@ -380,8 +382,10 @@ export type RunProdAppAuthOptions = {
    *  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). */
+   *  env var when unset; both unset means 0 hops, the safe socket-only
+   *  default (only the socket address counts, XFF ignored). Deprecated in
+   *  favor of the top-level `trustedProxyHops` option, which wins over
+   *  this and the env var. */
   readonly trustedProxyHops?: number;
   /** Server-computed post-auth redirect (see AuthRoutesConfig.postAuthLanding).
    *  Result lands in the login/signup/invite response as `landingPath`; an
@@ -700,8 +704,12 @@ export type ProdAppHandle = {
    *  `process.exit(0)` before returning a handle. */
   readonly entrypoint: ApiEntrypoint | AllInOneEntrypoint;
   /** The fetch-handler — wired into Bun.serve in production, called
-   *  directly in tests. Composes Hono + static-fallback. */
-  readonly fetch: (req: Request) => Promise<Response> | Response;
+   *  directly in tests. Composes Hono + static-fallback. Apps with
+   *  `autoListen: false` that call `Bun.serve` themselves must pass the
+   *  2nd arg from `server.requestIP(req)?.address`, extracted in their
+   *  outermost Bun fetch callback — `requestIP` only resolves for Bun's
+   *  original Request instance, never a cloned/rebuilt one. */
+  readonly fetch: (req: Request, socketAddress?: string) => Promise<Response> | Response;
   /** Active Bun-server (only set when listen() was called — tests skip
    *  listen() because Bun.serve isn't available under vitest/node). */
   server?: ReturnType<typeof Bun.serve>;
@@ -818,31 +826,10 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
   // 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.trustedProxyHops !== undefined) return options.trustedProxyHops;
-    if (options.auth?.trustedProxyHops !== undefined) return options.auth.trustedProxyHops;
-    if (trustedProxyHopsFromEnv === undefined) return undefined;
-    // Digits-only — parseInt("0x10")/("1e3")/("2x") would silently coerce
-    // and land on the spoofable hops=0 path for values like "0x10".
-    if (!/^\d+$/.test(trustedProxyHopsFromEnv)) {
-      throw new Error(
-        `runProdApp: KUMIKO_TRUSTED_PROXY_HOPS must be a non-negative integer, got "${trustedProxyHopsFromEnv}".`,
-      );
-    }
-    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 trustedProxyHops =
+    options.trustedProxyHops ??
+    options.auth?.trustedProxyHops ??
+    parseTrustedProxyHopsEnv(readEnv(TRUSTED_PROXY_HOPS_ENV, envSource), "runProdApp");
   const port = options.port ?? Number.parseInt(envSource["PORT"] ?? "3000", 10);
 
   // biome-ignore lint/suspicious/noConsole: boot-time progress hint, no logger configured this early