@cosmicdrift/kumiko-framework 0.318.0 → 0.320.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.318.0",
+  "version": "0.320.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>",
@@ -179,6 +179,10 @@
       "types": "./src/testing/handler-context.ts",
       "default": "./src/testing/handler-context.ts"
     },
+    "./testing/real-providers": {
+      "types": "./src/testing/real-providers.ts",
+      "default": "./src/testing/real-providers.ts"
+    },
     "./testing/e2e-generator": {
       "types": "./src/testing/e2e-generator.ts",
       "default": "./src/testing/e2e-generator.ts"
@@ -198,8 +202,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.318.0",
-    "@cosmicdrift/kumiko-types": "0.318.0",
+    "@cosmicdrift/kumiko-http": "0.320.0",
+    "@cosmicdrift/kumiko-types": "0.320.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -215,7 +219,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.318.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.320.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/api/__tests__/auth-routes-mfa-preauth-enable-start.test.ts

@@ -218,9 +218,15 @@ describe("POST /auth/mfa/preauth-enable-start", () => {
   // x-forwarded-for. The second check keys on a sha256 of the
   // preauthSetupToken — prove rotating IPs still hit 429 on the same
   // token, and that a different token does not share that bucket.
+  // trustedProxyHops: 1 makes the single-entry XFF values below resolve to
+  // genuinely distinct client IPs — the default
+  // hops=0 ignores x-forwarded-for outright and would collapse every
+  // request onto one shared "unknown" IP-axis bucket, masking exactly the
+  // token-axis independence this test exists to prove.
   test("preauthSetupToken rate-limit axis survives x-forwarded-for rotation", async () => {
     const { app } = await buildApp({
       mfaPreauthEnableStartRateLimit: createInMemoryLoginRateLimiter(2, 60_000),
+      trustedProxyHops: 1,
     });
     const attempt = (token: string, forwardedFor: string) =>
       app.request(

package/src/api/__tests__/auth-routes-mfa-verify.test.ts

@@ -144,6 +144,17 @@ describe("POST /auth/mfa/verify", () => {
     expect(cookies.get(CSRF_COOKIE_NAME)).toBeDefined();
   });
 
+  test("postAuthLanding wired → response carries landingPath", async () => {
+    const { app } = await buildApp({
+      postAuthLanding: (args) => (args.flow === "login" ? "/a/profile" : undefined),
+    });
+    const res = await app.request(
+      verifyRequest({ challengeToken: "opaque-challenge-token", code: "123456" }),
+    );
+    const body = (await res.json()) as { landingPath?: string };
+    expect(body.landingPath).toBe("/a/profile");
+  });
+
   test("a handler failure maps through mfaVerifyErrorStatusMap", async () => {
     const dispatcher = createStubDispatcher({
       async write(): Promise<WriteResult> {

package/src/api/__tests__/auth-routes-trusted-proxy.test.ts

@@ -112,16 +112,20 @@ describe("AuthRoutesConfig.trustedProxyHops", () => {
     expect((await clientB()).status).toBe(422);
   });
 
-  test("hops=0 (default): legacy behavior — trusts the first XFF entry unconditionally", async () => {
+  // hops=0 trusts NO proxy header at all, so a client-controlled XFF (any
+  // entry) is ignored outright and every request collapses into the shared
+  // "unknown" bucket (no socket address available via app.request()).
+  test("hops=0 (default): ignores x-forwarded-for entirely — distinct first entries share one bucket", async () => {
     const app = await buildApp();
-    // No override: two "different" first-entries mean two different buckets,
-    // even though both requests carry the same real backend hop.
     const clientA = () => app.request(verifyRequest("1.1.1.1, 9.9.9.9"));
     const clientB = () => app.request(verifyRequest("2.2.2.2, 9.9.9.9"));
     expect((await clientA()).status).toBe(422);
     expect((await clientA()).status).toBe(422);
     expect((await clientA()).status).toBe(429);
-    expect((await clientB()).status).toBe(422);
+    // client B "looks" different (different first XFF entry) but hops=0
+    // ignores XFF outright — same "unknown" bucket as client A, already
+    // exhausted above.
+    expect((await clientB()).status).toBe(429);
   });
 
   test("hops=2 with a shorter XFF chain than configured collapses distinct clients into the unknown bucket", async () => {

package/src/api/__tests__/client-ip.test.ts

@@ -0,0 +1,139 @@
+// Unit tests for the single client-IP resolver shared by requestIdMiddleware,
+// rate-limit/middleware.ts (L1/L2) and auth-routes.ts.
+// No Hono/HTTP plumbing here — see request-id-middleware.test.ts,
+// auth-routes-trusted-proxy.test.ts and rate-limit/__tests__/
+// middleware.integration.test.ts for the end-to-end behavior.
+
+import { afterEach, describe, expect, spyOn, test } from "bun:test";
+import {
+  assertValidTrustedProxyHops,
+  type ClientIpHeaderSource,
+  createClientIpResolver,
+} from "../client-ip";
+
+function sourceOf(headers: Record<string, string>, socketAddress?: string): ClientIpHeaderSource {
+  return {
+    header: (name) => headers[name],
+    ...(socketAddress !== undefined ? { socketAddress } : {}),
+  };
+}
+
+describe("createClientIpResolver", () => {
+  describe("hops = 0 (default): trust no proxy header", () => {
+    test("ignores x-forwarded-for and falls back to the socket address", () => {
+      const resolver = createClientIpResolver(0);
+      const ip = resolver.resolve(sourceOf({ "x-forwarded-for": "203.0.113.7" }, "10.1.1.1"));
+      expect(ip).toBe("10.1.1.1");
+    });
+
+    test("falls back to 'unknown' when there's no socket address either", () => {
+      const resolver = createClientIpResolver(0);
+      expect(resolver.resolve(sourceOf({ "x-forwarded-for": "203.0.113.7" }))).toBe("unknown");
+    });
+
+    test("ignores x-real-ip too — hops=0 trusts nothing but the socket", () => {
+      const resolver = createClientIpResolver(0);
+      expect(resolver.resolve(sourceOf({ "x-real-ip": "203.0.113.7" }, "10.1.1.1"))).toBe(
+        "10.1.1.1",
+      );
+    });
+
+    describe("warns exactly once per resolver instance when XFF arrives", () => {
+      let warnSpy: ReturnType<typeof spyOn>;
+
+      afterEach(() => {
+        warnSpy?.mockRestore();
+      });
+
+      test("logs a single console.warn across repeated requests with XFF", () => {
+        warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+        const resolver = createClientIpResolver(0);
+        resolver.resolve(sourceOf({ "x-forwarded-for": "203.0.113.7" }));
+        resolver.resolve(sourceOf({ "x-forwarded-for": "203.0.113.8" }));
+        resolver.resolve(sourceOf({ "x-forwarded-for": "203.0.113.9" }));
+        expect(warnSpy).toHaveBeenCalledTimes(1);
+      });
+
+      test("a fresh resolver instance warns again — the flag isn't a module singleton", () => {
+        warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+        createClientIpResolver(0).resolve(sourceOf({ "x-forwarded-for": "203.0.113.7" }));
+        createClientIpResolver(0).resolve(sourceOf({ "x-forwarded-for": "203.0.113.7" }));
+        expect(warnSpy).toHaveBeenCalledTimes(2);
+      });
+
+      test("no warning when XFF is absent or blank", () => {
+        warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+        const resolver = createClientIpResolver(0);
+        resolver.resolve(sourceOf({}));
+        resolver.resolve(sourceOf({ "x-forwarded-for": "   " }));
+        expect(warnSpy).not.toHaveBeenCalled();
+      });
+    });
+  });
+
+  describe("hops = 1: last XFF entry is the real client", () => {
+    test("picks the last entry, ignoring a spoofed leading entry", () => {
+      const resolver = createClientIpResolver(1);
+      const ip = resolver.resolve(sourceOf({ "x-forwarded-for": "attacker-claim, 9.9.9.9" }));
+      expect(ip).toBe("9.9.9.9");
+    });
+
+    test("a different spoofed leading entry doesn't change the resolved IP", () => {
+      const resolver = createClientIpResolver(1);
+      const first = resolver.resolve(sourceOf({ "x-forwarded-for": "1.2.3.4, 9.9.9.9" }));
+      const second = resolver.resolve(sourceOf({ "x-forwarded-for": "5.6.7.8, 9.9.9.9" }));
+      expect(first).toBe("9.9.9.9");
+      expect(second).toBe("9.9.9.9");
+    });
+
+    test("a single-entry chain resolves to that entry directly", () => {
+      const resolver = createClientIpResolver(1);
+      expect(resolver.resolve(sourceOf({ "x-forwarded-for": "9.9.9.9" }))).toBe("9.9.9.9");
+    });
+
+    test("no XFF: falls back to x-real-ip", () => {
+      const resolver = createClientIpResolver(1);
+      expect(resolver.resolve(sourceOf({ "x-real-ip": "203.0.113.10" }))).toBe("203.0.113.10");
+    });
+
+    test("no XFF and no x-real-ip: falls back to the socket address", () => {
+      const resolver = createClientIpResolver(1);
+      expect(resolver.resolve(sourceOf({}, "10.2.2.2"))).toBe("10.2.2.2");
+    });
+
+    test("no XFF, no x-real-ip, no socket address: falls back to 'unknown', never skips", () => {
+      const resolver = createClientIpResolver(1);
+      expect(resolver.resolve(sourceOf({}))).toBe("unknown");
+    });
+
+    test("empty/whitespace-only XFF is treated as absent, not as a blank entry", () => {
+      const resolver = createClientIpResolver(1);
+      expect(resolver.resolve(sourceOf({ "x-forwarded-for": "   " }, "10.3.3.3"))).toBe("10.3.3.3");
+    });
+  });
+
+  describe("hops = 2: chain shorter than configured hops falls back", () => {
+    test("a single-entry chain (shorter than 2 hops) falls back to x-real-ip", () => {
+      const resolver = createClientIpResolver(2);
+      expect(
+        resolver.resolve(sourceOf({ "x-forwarded-for": "9.9.9.9", "x-real-ip": "203.0.113.11" })),
+      ).toBe("203.0.113.11");
+    });
+
+    test("a two-entry chain resolves to the leftmost (first) trusted-hop entry", () => {
+      const resolver = createClientIpResolver(2);
+      expect(resolver.resolve(sourceOf({ "x-forwarded-for": "6.6.6.6, 7.7.7.7" }))).toBe("6.6.6.6");
+    });
+  });
+
+  test("assertValidTrustedProxyHops rejects negative and non-integer values", () => {
+    expect(() => assertValidTrustedProxyHops(-1, "test")).toThrow(/non-negative integer/);
+    expect(() => assertValidTrustedProxyHops(1.5, "test")).toThrow(/non-negative integer/);
+    expect(() => assertValidTrustedProxyHops(0, "test")).not.toThrow();
+    expect(() => assertValidTrustedProxyHops(undefined, "test")).not.toThrow();
+  });
+
+  test("createClientIpResolver fails loud on an invalid trustedProxyHops instead of silently degrading", () => {
+    expect(() => createClientIpResolver(-1, "test")).toThrow(/non-negative integer/);
+  });
+});

package/src/api/__tests__/extra-routes.integration.test.ts

@@ -105,7 +105,14 @@ describe("extraRoutes: entry:anonymous", () => {
   let stack: TestStack;
 
   beforeAll(async () => {
-    stack = await setupTestStack({ features: [probeFeature], extraRoutes: [pingRoute] });
+    // trustedProxyHops: 1 — the default hops=0 ignores x-forwarded-for and
+    // would collapse both tests below onto one
+    // shared "unknown" per-ip bucket, bleeding rate-limit state between them.
+    stack = await setupTestStack({
+      features: [probeFeature],
+      extraRoutes: [pingRoute],
+      trustedProxyHops: 1,
+    });
   });
 
   afterAll(() => stack.cleanup());

package/src/api/__tests__/http-route-rate-limit.integration.test.ts

@@ -4,7 +4,16 @@
 // systemQuery wiring. Proves the fix: repeated calls through the same
 // httpRoute, same client IP, DO hit the limit.
 
-import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import {
+  afterAll,
+  afterEach,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  spyOn,
+  test,
+} from "bun:test";
 import * as z from "zod";
 import { createEntity, createTextField, defineFeature } from "../../engine";
 import type { TenantId } from "../../engine/types/identifiers";
@@ -44,7 +53,10 @@ const ipLimitedFeature = defineFeature("rl-http", (r) => {
 let stack: TestStack;
 
 beforeAll(async () => {
-  stack = await setupTestStack({ features: [ipLimitedFeature] });
+  // trustedProxyHops: 1 — this suite's whole point is isolating buckets by
+  // the literal x-forwarded-for value below; the
+  // new hops=0 default ignores that header outright.
+  stack = await setupTestStack({ features: [ipLimitedFeature], trustedProxyHops: 1 });
 });
 
 afterAll(async () => {
@@ -74,4 +86,63 @@ describe("r.httpRoute → systemQuery propagates requestContext for per-ip rate
 
     expect((await callAs("9.9.9.3")).status).toBe(200);
   });
+
+  // An attacker rotating the untrusted, client-facing XFF prefix must still
+  // land in the real client's bucket — only the
+  // trusted-proxy-appended LAST entry counts at hops=1.
+  test("hops=1: different spoofed leading XFF entry, same trailing entry → same bucket", async () => {
+    const attempt = (leading: string) =>
+      stack.app.request("/ping", { headers: { "x-forwarded-for": `${leading}, 9.9.9.4` } });
+
+    expect((await attempt("attacker-claim-a")).status).toBe(200);
+    expect((await attempt("attacker-claim-b")).status).toBe(200);
+    const third = await attempt("attacker-claim-c");
+    expect(third.status).toBe(429);
+  });
+});
+
+describe("r.httpRoute → systemQuery: default trustedProxyHops=0 never fail-opens", () => {
+  let defaultHopsStack: TestStack;
+
+  beforeAll(async () => {
+    defaultHopsStack = await setupTestStack({ features: [ipLimitedFeature] });
+  });
+
+  afterAll(async () => {
+    await defaultHopsStack.cleanup();
+  });
+
+  beforeEach(async () => {
+    await defaultHopsStack.redis.flushNamespace();
+  });
+
+  test("no x-forwarded-for at all: the shared 'unknown' bucket still enforces the limit", async () => {
+    const call = () => defaultHopsStack.app.request("/ping");
+
+    expect((await call()).status).toBe(200);
+    expect((await call()).status).toBe(200);
+    expect((await call()).status).toBe(429);
+  });
+
+  describe("one-time warning when hops=0 but the client sends x-forwarded-for anyway", () => {
+    let warnSpy: ReturnType<typeof spyOn>;
+
+    afterEach(() => {
+      warnSpy?.mockRestore();
+    });
+
+    test("warns exactly once across multiple requests, not once per request", async () => {
+      warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+      const call = () =>
+        defaultHopsStack.app.request("/ping", { headers: { "x-forwarded-for": "203.0.113.50" } });
+
+      await call();
+      await call();
+
+      const proxyWarnings = warnSpy.mock.calls.filter((args: unknown[]) =>
+        String(args[0]).includes("trustedProxyHops is 0"),
+      );
+      expect(proxyWarnings.length).toBe(1);
+    });
+  });
 });

package/src/api/__tests__/pat-route-guard.integration.test.ts

@@ -0,0 +1,126 @@
+// PAT route-scoping (fail-closed): a Personal Access Token must only reach
+// the dispatcher routes (write/batch/query/command/stream) — every other
+// /api/* surface, and every non-anonymous r.httpRoute regardless of where
+// it's mounted, is off-limits no matter what the token's granted scopes are.
+// Full HTTP loop via setupTestStack (real buildServer wiring), never
+// createTestDispatcher — this proves the guard is actually mounted, not just
+// that the guard function works in isolation.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import * as z from "zod";
+import { defineFeature, type SessionUser } from "../../engine";
+import type { TenantId } from "../../engine/types/identifiers";
+import { setupTestStack, type TestStack, TestUsers } from "../../stack";
+import type { TokenVerifier } from "../auth-middleware";
+import type { UserExtraRoute } from "../extra-route";
+
+const TENANT_ID = "00000000-0000-4000-8000-000000000001" as TenantId;
+const PAT_TEST_TOKEN = "kpat_route-guard-test-token";
+
+const patTestUser: SessionUser = {
+  id: "pat-route-guard-test-user",
+  tenantId: TENANT_ID,
+  roles: [],
+  pat: {
+    tokenId: "pat-route-guard-test-token-id",
+    scopes: ["ping:read"],
+    allowedQns: ["pat-route-guard-probe:query:ping"],
+  },
+};
+
+const fakeTokenVerifier: TokenVerifier = async (raw) =>
+  raw === PAT_TEST_TOKEN ? patTestUser : null;
+
+const probeFeature = defineFeature("pat-route-guard-probe", (r) => {
+  r.queryHandler({
+    name: "ping",
+    schema: z.object({}),
+    access: { openToAll: { reason: "test handler callable by any authenticated caller" } },
+    handler: async () => ({ pong: true }),
+  });
+  r.httpRoute({
+    method: "GET",
+    path: "/pat-guard-private",
+    anonymous: false,
+    handler: async (c) => c.json({ ok: true }),
+  });
+});
+
+const userExtraRoute: UserExtraRoute = {
+  method: "GET",
+  path: "/api/pat-guard-extra",
+  entry: "user",
+  handler: async (c) => c.json({ ok: true }),
+};
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [probeFeature],
+    extraRoutes: [userExtraRoute],
+    authConfig: {
+      // Never actually dispatched in these tests (login/tenant-switch aren't
+      // exercised here) — only tokenVerifier matters for the PAT path.
+      membershipQuery: "pat-route-guard-probe:query:nonexistent",
+      tokenVerifier: fakeTokenVerifier,
+    },
+  });
+});
+
+afterAll(() => stack.cleanup());
+
+function patHeaders(): Record<string, string> {
+  return { Authorization: `Bearer ${PAT_TEST_TOKEN}` };
+}
+
+describe("PAT route guard — dispatcher routes only", () => {
+  test("PAT with a matching scope still reaches /api/query (regression)", async () => {
+    const res = await stack.app.request("/api/query", {
+      method: "POST",
+      headers: { ...patHeaders(), "Content-Type": "application/json" },
+      body: JSON.stringify({ type: "pat-route-guard-probe:query:ping", payload: {} }),
+    });
+    expect(res.status).toBe(200);
+  });
+
+  test("PAT → GET /api/sse → 403 before the stream ever opens", async () => {
+    const res = await stack.app.request("/api/sse", { headers: patHeaders() });
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as {
+      error: { code: string; details?: { reason?: string } };
+    };
+    expect(body.error.code).toBe("access_denied");
+    expect(body.error.details?.reason).toBe("pat_dispatcher_routes_only");
+  });
+
+  test("PAT → non-anonymous r.httpRoute → 403", async () => {
+    const res = await stack.app.request("/pat-guard-private", { headers: patHeaders() });
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("access_denied");
+  });
+
+  test("JWT user still reaches the same r.httpRoute (regression)", async () => {
+    const token = await stack.jwt.sign(TestUsers.user);
+    const res = await stack.app.request("/pat-guard-private", {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    expect(res.status).toBe(200);
+  });
+
+  test('PAT → entry:"user" extraRoute → 403', async () => {
+    const res = await stack.app.request("/api/pat-guard-extra", { headers: patHeaders() });
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("access_denied");
+  });
+
+  test('JWT user still reaches the entry:"user" extraRoute (regression)', async () => {
+    const token = await stack.jwt.sign(TestUsers.user);
+    const res = await stack.app.request("/api/pat-guard-extra", {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    expect(res.status).toBe(200);
+  });
+});

package/src/api/__tests__/post-auth-landing.test.ts

@@ -0,0 +1,100 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+import {
+  isSafeLandingPath,
+  type PostAuthLandingArgs,
+  type PostAuthLandingResolver,
+  resolvePostAuthLandingPath,
+} from "../post-auth-landing";
+
+describe("isSafeLandingPath", () => {
+  const rejected: unknown[] = [
+    "//evil.com",
+    "/\\evil.com",
+    "/a\\b",
+    "/\t/evil.com",
+    "/\n/evil.com",
+    " /a",
+    "https://evil.com",
+    "javascript:alert(1)",
+    "",
+    "a/b",
+    42,
+    undefined,
+    "/.//evil.com",
+  ];
+  for (const candidate of rejected) {
+    test(`rejects ${JSON.stringify(candidate)}`, () => {
+      expect(isSafeLandingPath(candidate)).toBe(false);
+    });
+  }
+
+  const accepted: string[] = ["/", "/a/profile", "/a/vehicle-detail/abc?x=1#h"];
+  for (const candidate of accepted) {
+    test(`accepts ${JSON.stringify(candidate)}`, () => {
+      expect(isSafeLandingPath(candidate)).toBe(true);
+    });
+  }
+});
+
+describe("resolvePostAuthLandingPath", () => {
+  const args: PostAuthLandingArgs = { flow: "login", roles: ["User"], tenantId: "t1" };
+  const realWarn = console.warn;
+
+  beforeEach(() => {
+    console.warn = mock(() => {});
+  });
+  afterEach(() => {
+    console.warn = realWarn;
+  });
+
+  test("undefined resolver → undefined, no warning", () => {
+    expect(resolvePostAuthLandingPath(undefined, args)).toBeUndefined();
+    expect(console.warn).not.toHaveBeenCalled();
+  });
+
+  test("resolver returns undefined → undefined, no warning", () => {
+    expect(resolvePostAuthLandingPath(() => undefined, args)).toBeUndefined();
+    expect(console.warn).not.toHaveBeenCalled();
+  });
+
+  test("throwing resolver → undefined, logs a warning without the thrown value", () => {
+    const result = resolvePostAuthLandingPath(() => {
+      throw new Error("boom");
+    }, args);
+    expect(result).toBeUndefined();
+    expect(console.warn).toHaveBeenCalledTimes(1);
+  });
+
+  test("throwing resolver → warning carries the error class, not the consumer message", () => {
+    resolvePostAuthLandingPath(() => {
+      throw new Error("secret-token-123");
+    }, args);
+    const loggedArgs = (console.warn as unknown as { mock: { calls: unknown[][] } }).mock.calls[0];
+    expect(JSON.stringify(loggedArgs)).not.toContain("secret-token-123");
+  });
+
+  test("rejecting async resolver → undefined, async warning, rejection observed", async () => {
+    // @cast-boundary test — simulates a JS consumer bypassing the sync signature
+    const asyncResolver = (async () => {
+      throw new Error("boom");
+    }) as unknown as PostAuthLandingResolver;
+    expect(resolvePostAuthLandingPath(asyncResolver, args)).toBeUndefined();
+    await Promise.resolve();
+    expect(console.warn).toHaveBeenCalledTimes(1);
+    const loggedArgs = (console.warn as unknown as { mock: { calls: unknown[][] } }).mock.calls[0];
+    expect(String(loggedArgs?.[0])).toContain("async resolver not supported");
+  });
+
+  test("unsafe path → undefined, warns without leaking the candidate", () => {
+    const result = resolvePostAuthLandingPath(() => "//evil.com", args);
+    expect(result).toBeUndefined();
+    expect(console.warn).toHaveBeenCalledTimes(1);
+    const loggedArgs = (console.warn as unknown as { mock: { calls: unknown[][] } }).mock.calls[0];
+    expect(JSON.stringify(loggedArgs)).not.toContain("evil.com");
+  });
+
+  test("valid path → the path, no warning", () => {
+    expect(resolvePostAuthLandingPath(() => "/a/profile", args)).toBe("/a/profile");
+    expect(console.warn).not.toHaveBeenCalled();
+  });
+});

package/src/api/__tests__/request-id-middleware.test.ts

@@ -71,7 +71,11 @@ describe("requestIdMiddleware — signal propagation", () => {
   });
 });
 describe("requestIdMiddleware — ip + userAgent capture (603/2)", () => {
-  test("populates ip from x-forwarded-for and userAgent from the User-Agent header", async () => {
+  // Default trustedProxyHops=0 trusts no proxy header at all — the resolver
+  // ignores x-forwarded-for outright (a
+  // spoofable, client-controlled header) and falls back to the socket
+  // address, "unknown" here since app.request() has none.
+  test("default (trustedProxyHops=0): ignores x-forwarded-for, falls back to unknown", async () => {
     let captured: { ip: string | undefined; userAgent: string | undefined } = {
       ip: undefined,
       userAgent: undefined,
@@ -96,7 +100,36 @@ describe("requestIdMiddleware — ip + userAgent capture (603/2)", () => {
     );
 
     expect(res.status).toBe(200);
-    expect(captured.ip).toBe("203.0.113.7");
+    expect(captured.ip).toBe("unknown");
+    expect(captured.userAgent).toBe("Mozilla/5.0 (probe-test)");
+  });
+
+  test("trustedProxyHops=1: populates ip from the last (trusted-proxy-appended) x-forwarded-for entry", async () => {
+    let captured: { ip: string | undefined; userAgent: string | undefined } = {
+      ip: undefined,
+      userAgent: undefined,
+    };
+
+    const app = new Hono();
+    app.use("/probe", requestIdMiddleware({ trustedProxyHops: 1 }));
+    app.get("/probe", (c) => {
+      const ctx = requestContext.get();
+      captured = { ip: ctx?.ip, userAgent: ctx?.userAgent };
+      return c.text("ok");
+    });
+
+    const res = await app.request(
+      new Request("http://test.local/probe", {
+        method: "GET",
+        headers: {
+          "x-forwarded-for": "203.0.113.7, 10.0.0.1",
+          "user-agent": "Mozilla/5.0 (probe-test)",
+        },
+      }),
+    );
+
+    expect(res.status).toBe(200);
+    expect(captured.ip).toBe("10.0.0.1");
     expect(captured.userAgent).toBe("Mozilla/5.0 (probe-test)");
   });