@cosmicdrift/kumiko-dev-server 0.320.0 → 0.321.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-dev-server",
-  "version": "0.320.0",
+  "version": "0.321.0",
   "description": "Dev-tooling for Kumiko apps: local dev-server bootstrap (runDevApp), scaffolding, codegen. Its compose-stacks/env-schema subpaths are consumed at prod boot too — see @cosmicdrift/kumiko-server-runtime for the prod runner itself.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -59,10 +59,10 @@
     "kumiko-upgrade": "./bin/kumiko-upgrade.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.320.0",
-    "@cosmicdrift/kumiko-framework": "0.320.0",
-    "@cosmicdrift/kumiko-headless": "0.320.0",
-    "@cosmicdrift/kumiko-server-runtime": "0.320.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.321.0",
+    "@cosmicdrift/kumiko-framework": "0.321.0",
+    "@cosmicdrift/kumiko-headless": "0.321.0",
+    "@cosmicdrift/kumiko-server-runtime": "0.321.0",
     "ts-morph": "^28.0.0"
   },
   "publishConfig": {

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

@@ -14,6 +14,7 @@ import {
   TEXT_BLOCK_KIND,
   type TemplateResolverApi,
 } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
+import type { AnonymousExtraRoute } from "@cosmicdrift/kumiko-framework/api";
 import {
   createEntity,
   createTextField,
@@ -121,6 +122,46 @@ describe("runDevApp — auth allowedOrigins forwarding (#399/1)", () => {
   });
 });
 
+describe("runDevApp — trustedProxyHops env fallback (KUMIKO_TRUSTED_PROXY_HOPS)", () => {
+  const clientIpRoute: AnonymousExtraRoute = {
+    method: "GET",
+    path: "/client-ip-probe",
+    entry: "anonymous",
+    handler: async (c, deps) => c.json({ clientIp: deps.clientIp }),
+  };
+
+  test("no trustedProxyHops option, env var set → env value reaches the server's client-ip resolver", async () => {
+    handle = await runDevApp({
+      features: [validFeature()],
+      port: 0,
+      extraRoutes: [clientIpRoute],
+      envSource: { ...process.env, KUMIKO_TRUSTED_PROXY_HOPS: "1" },
+    });
+    const res = await handle.fetch(
+      new Request("http://test/client-ip-probe", {
+        headers: { "x-forwarded-for": "203.0.113.10" },
+      }),
+    );
+    expect(await res.json()).toEqual({ clientIp: "203.0.113.10" });
+  });
+
+  test("explicit trustedProxyHops option wins over the env var", async () => {
+    handle = await runDevApp({
+      features: [validFeature()],
+      port: 0,
+      trustedProxyHops: 0,
+      extraRoutes: [clientIpRoute],
+      envSource: { ...process.env, KUMIKO_TRUSTED_PROXY_HOPS: "1" },
+    });
+    const res = await handle.fetch(
+      new Request("http://test/client-ip-probe", {
+        headers: { "x-forwarded-for": "203.0.113.10" },
+      }),
+    );
+    expect(await res.json()).toEqual({ clientIp: "unknown" });
+  });
+});
+
 describe("runDevApp — extraContext merge order: app values win over boot defaults (707/1)", () => {
   test("a caller-supplied extraContext.templateResolver wins over the auto-wired boot default", async () => {
     // runDevApp's extraContext factory does `{ ...boot, ...base }` — boot's

package/src/changes.json

@@ -1,4 +1,18 @@
 [
+  {
+    "version": "0.321.0",
+    "type": "improvement",
+    "title": "kumiko-upgrade gained --help/-h",
+    "detail": "Prints usage and exits 0 without running the upgrade report.",
+    "migration": "No action needed."
+  },
+  {
+    "version": "0.321.0",
+    "type": "improvement",
+    "title": "runDevApp now also honors KUMIKO_TRUSTED_PROXY_HOPS as an env fallback, symmetric to runProdApp",
+    "detail": "Precedence: `options.trustedProxyHops ?? effectiveAuth?.trustedProxyHops\n?? parseTrustedProxyHopsEnv(envSource[TRUSTED_PROXY_HOPS_ENV], \"runDevApp\")`.",
+    "migration": "No action needed for the default (unproxied) dev setup."
+  },
   {
     "version": "0.320.0",
     "type": "breaking",

package/src/run-dev-app.ts

@@ -49,7 +49,11 @@ import type {
   SessionMetadata,
   TokenVerifier,
 } from "@cosmicdrift/kumiko-framework/api";
-import { createInMemoryLoginRateLimiter } from "@cosmicdrift/kumiko-framework/api";
+import {
+  createInMemoryLoginRateLimiter,
+  parseTrustedProxyHopsEnv,
+  TRUSTED_PROXY_HOPS_ENV,
+} from "@cosmicdrift/kumiko-framework/api";
 import {
   configureBlindIndexKey,
   configurePiiSubjectKms,
@@ -279,8 +283,9 @@ export type RunDevAppOptions = {
   /** Forwarded to createKumikoServer → setupTestStack's top-level
    *  `trustedProxyHops` — symmetric to
    *  RunProdAppOptions.trustedProxyHops. Wins over the deprecated
-   *  `auth.trustedProxyHops`. Dev usually runs unproxied, so this is
-   *  normally left unset (default 0). */
+   *  `auth.trustedProxyHops`, which wins over the `KUMIKO_TRUSTED_PROXY_HOPS`
+   *  env var. Dev usually runs unproxied, so this is normally left unset
+   *  (default 0). */
   readonly trustedProxyHops?: number;
 };
 
@@ -486,6 +491,11 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
         }
       : {};
 
+  const trustedProxyHops =
+    options.trustedProxyHops ??
+    effectiveAuth?.trustedProxyHops ??
+    parseTrustedProxyHopsEnv(envSource[TRUSTED_PROXY_HOPS_ENV], "runDevApp");
+
   const handle = await createKumikoServer({
     features,
     ...(options.clientEntry !== undefined && { clientEntry: options.clientEntry }),
@@ -505,9 +515,7 @@ export async function runDevApp(options: RunDevAppOptions): Promise<KumikoServer
     ...(options.files !== undefined && { files: options.files }),
     ...(options.extraRoutes !== undefined && { extraRoutes: options.extraRoutes }),
     ...(options.wire !== undefined && { wire: options.wire }),
-    ...((options.trustedProxyHops ?? effectiveAuth?.trustedProxyHops) !== undefined && {
-      trustedProxyHops: options.trustedProxyHops ?? effectiveAuth?.trustedProxyHops,
-    }),
+    ...(trustedProxyHops !== undefined && { trustedProxyHops }),
     ...(finalEffectiveFeatures !== undefined && {
       effectiveFeatures: finalEffectiveFeatures,
     }),