@cosmicdrift/kumiko-framework 0.319.0 → 0.321.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.319.0",
+  "version": "0.321.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.319.0",
-    "@cosmicdrift/kumiko-types": "0.319.0",
+    "@cosmicdrift/kumiko-http": "0.321.0",
+    "@cosmicdrift/kumiko-types": "0.321.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.319.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.321.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/__tests__/schema-cli.integration.test.ts

@@ -54,6 +54,17 @@ describe("runSchemaCli — no-DB paths", () => {
     expect(cap.err).toHaveLength(0);
   });
 
+  test.each(["--help", "-h", "help"])(
+    "%s prints the same usage as no subcommand and exits 0",
+    async (helpArg) => {
+      const cap = captureOut();
+      const code = await runSchemaCli([helpArg], appCwd, cap.out);
+      expect(code).toBe(0);
+      expect(cap.log.join("\n")).toContain("Subcommands:");
+      expect(cap.err).toHaveLength(0);
+    },
+  );
+
   test("unknown subcommand exits 1 and reports it on stderr", async () => {
     const cap = captureOut();
     const code = await runSchemaCli(["cutover"], appCwd, cap.out);

package/src/__tests__/upgrade-cli.test.ts

@@ -14,8 +14,8 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import {
   findCodemodScriptsRoot,
-  findCoreChangelogFile,
   findFeaturesDirs,
+  findPackageChangelogFiles,
   resolveCodemodScript,
   runUpgradeCli,
   type UpgradeCliOut,
@@ -92,6 +92,23 @@ async function runJson(cwd: string, from: string): Promise<{ pending: Array<{ ti
   return JSON.parse(spy.logs.join("\n"));
 }
 
+describe("upgrade command — --help", () => {
+  test("--help prints usage and exits 0 without touching the filesystem", async () => {
+    const spy = makeSpyOutput();
+    const exit = await runUpgradeCli(["--help"], "/nonexistent-cwd", spy.out);
+    expect(exit).toBe(0);
+    expect(spy.logs.join("\n")).toContain("kumiko-upgrade");
+    expect(spy.errs).toEqual([]);
+  });
+
+  test("-h behaves the same as --help", async () => {
+    const spy = makeSpyOutput();
+    const exit = await runUpgradeCli(["-h"], "/nonexistent-cwd", spy.out);
+    expect(exit).toBe(0);
+    expect(spy.logs.join("\n")).toContain("--apply");
+  });
+});
+
 describe("upgrade command — framework core changelog", () => {
   test("collects core changes.json from the framework repo layout", async () => {
     const cwd = tmp({
@@ -198,6 +215,37 @@ describe("upgrade command — framework core changelog", () => {
   });
 });
 
+describe("upgrade command — every package's changelog, not just framework core", () => {
+  const SERVER_RUNTIME_ENTRY = JSON.stringify([
+    { version: "0.168.0", type: "breaking", title: "server-runtime breaking change" },
+  ]);
+
+  test("a hoisted non-framework, non-bundled-features package's changes.json shows up in pending", async () => {
+    const cwd = tmp({
+      "node_modules/@cosmicdrift/kumiko-server-runtime/src/changes.json": SERVER_RUNTIME_ENTRY,
+      "apps/web/package.json": "{}",
+    });
+
+    const result = await runJson(`${cwd}/apps/web`, "0.165.0");
+
+    expect(result.pending.map((e) => e.title)).toEqual(["server-runtime breaking change"]);
+  });
+
+  test("bundled-features is never double-counted alongside findFeaturesDirs's own collection", async () => {
+    const cwd = tmp({
+      "node_modules/@cosmicdrift/kumiko-server-runtime/src/changes.json": SERVER_RUNTIME_ENTRY,
+      "node_modules/@cosmicdrift/kumiko-bundled-features/src/user/changes.json": FEATURE_ENTRY,
+      "apps/web/package.json": "{}",
+    });
+
+    const result = await runJson(`${cwd}/apps/web`, "0.165.0");
+
+    expect(result.pending.map((e) => e.title).sort()).toEqual(
+      ["feature fix", "server-runtime breaking change"].sort(),
+    );
+  });
+});
+
 describe("upgrade command — enterprise package layout", () => {
   // Layout is detected by presence of changes.json, not an "ai-" name
   // prefix — the old heuristic silently dropped every enterprise package
@@ -641,9 +689,8 @@ describe("changes.json codemod fields resolve to real published scripts", () =>
   }
 
   test("every codemod field is a scripts/codemod/*.ts path that resolves to an existing published script", () => {
-    const coreChangelog = findCoreChangelogFile(REAL_REPO_ROOT);
     const changesJsonFiles = [
-      ...(coreChangelog ? [coreChangelog] : []),
+      ...findPackageChangelogFiles(REAL_REPO_ROOT),
       ...findFeaturesDirs(REAL_REPO_ROOT).flatMap((dir) => findChangesJsonFiles(dir)),
     ];
     expect(changesJsonFiles.length).toBeGreaterThan(0);

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,164 @@
+// 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,
+  parseTrustedProxyHopsEnv,
+} 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/);
+  });
+});
+
+describe("parseTrustedProxyHopsEnv", () => {
+  test("undefined -> undefined (no env set)", () => {
+    expect(parseTrustedProxyHopsEnv(undefined, "test")).toBeUndefined();
+  });
+
+  test("valid digits-only string -> parsed integer", () => {
+    expect(parseTrustedProxyHopsEnv("1", "test")).toBe(1);
+    expect(parseTrustedProxyHopsEnv("0", "test")).toBe(0);
+    expect(parseTrustedProxyHopsEnv("42", "test")).toBe(42);
+  });
+
+  test("hex/exponent/negative notation throws instead of silently coercing", () => {
+    expect(() => parseTrustedProxyHopsEnv("0x10", "test")).toThrow(/non-negative integer/);
+    expect(() => parseTrustedProxyHopsEnv("1e3", "test")).toThrow(/non-negative integer/);
+    expect(() => parseTrustedProxyHopsEnv("-1", "test")).toThrow(/non-negative integer/);
+  });
+
+  test("error message carries the context prefix and the raw value", () => {
+    expect(() => parseTrustedProxyHopsEnv("x", "runProdApp")).toThrow(
+      'runProdApp: KUMIKO_TRUSTED_PROXY_HOPS must be a non-negative integer, got "x".',
+    );
+  });
+});

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());
@@ -578,6 +585,48 @@ describe("extraRoutes: entry:signature", () => {
   });
 });
 
+describe("extraRoutes: entry:anonymous deps.clientIp", () => {
+  const clientIpRoute: AnonymousExtraRoute = {
+    method: "GET",
+    path: "/public/client-ip-probe",
+    entry: "anonymous",
+    handler: async (c, deps) => c.json({ clientIp: deps.clientIp }),
+  };
+
+  test("default trustedProxyHops (0): a spoofed X-Forwarded-For is ignored, socket address wins", async () => {
+    const stack = await setupTestStack({
+      features: [probeFeature],
+      extraRoutes: [clientIpRoute],
+    });
+    try {
+      const res = await stack.app.request(
+        "/public/client-ip-probe",
+        { headers: { "x-forwarded-for": "203.0.113.10" } },
+        "198.51.100.9",
+      );
+      expect(await res.json()).toEqual({ clientIp: "198.51.100.9" });
+    } finally {
+      await stack.cleanup();
+    }
+  });
+
+  test("trustedProxyHops: 1 — the rightmost X-Forwarded-For entry is trusted", async () => {
+    const stack = await setupTestStack({
+      features: [probeFeature],
+      extraRoutes: [clientIpRoute],
+      trustedProxyHops: 1,
+    });
+    try {
+      const res = await stack.app.request("/public/client-ip-probe", {
+        headers: { "x-forwarded-for": "203.0.113.10" },
+      });
+      expect(await res.json()).toEqual({ clientIp: "203.0.113.10" });
+    } finally {
+      await stack.cleanup();
+    }
+  });
+});
+
 // Type-level contract for ExtraRouteDefinition (kumiko-framework#3050): the
 // bodies below are never invoked — tsc checks them, bun:test does not run
 // them. Each `@ts-expect-error` turns into an "unused directive" compile

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);
+  });
+});