@cosmicdrift/kumiko-framework 0.200.1 → 0.202.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.200.1",
+  "version": "0.202.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>",
@@ -87,6 +87,10 @@
       "types": "./src/i18n/index.ts",
       "default": "./src/i18n/index.ts"
     },
+    "./http": {
+      "types": "./src/http/index.ts",
+      "default": "./src/http/index.ts"
+    },
     "./auth": {
       "types": "./src/auth/index.ts",
       "default": "./src/auth/index.ts"
@@ -186,7 +190,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.200.1",
+    "@cosmicdrift/kumiko-types": "0.202.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -202,7 +206,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.200.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.202.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/__tests__/entity-list-limits.integration.test.ts

@@ -0,0 +1,84 @@
+// Security regression (2026-08-13 audit, Finding 3): entityListSchema's
+// `limit`/`offset` used to accept fractional/oversized numbers, which flowed
+// unvalidated into a raw `LIMIT ${limit} OFFSET ${offset}` SQL string
+// (event-store-executor-read.ts) — a non-integer literal 500s, and an
+// unbounded limit forces a full-table materialisation.
+//
+// Bun.SQL-only setup via setupTestStack.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import {
+  createEntity,
+  createTextField,
+  defineEntityCreateHandler,
+  defineEntityListHandler,
+  defineFeature,
+  MAX_LIST_LIMIT,
+} from "../engine";
+import { setupTestStack, type TestStack, TestUsers, unsafeCreateEntityTable } from "../stack";
+
+const widgetEntity = createEntity({
+  table: "limit_widgets",
+  fields: { name: createTextField({ required: true }) },
+});
+
+const widgetFeature = defineFeature("limitwidgets", (r) => {
+  r.entity("widget", widgetEntity);
+  r.writeHandler(
+    defineEntityCreateHandler("widget", widgetEntity, { access: { roles: ["Admin"] } }),
+  );
+  r.queryHandler(defineEntityListHandler("widget", widgetEntity, { access: { roles: ["Admin"] } }));
+});
+
+describe("entity list limit/offset validation", () => {
+  let stack: TestStack;
+
+  beforeAll(async () => {
+    stack = await setupTestStack({ features: [widgetFeature] });
+    await unsafeCreateEntityTable(stack.db, widgetEntity);
+  });
+
+  afterAll(() => stack.cleanup());
+
+  test("fractional limit is rejected with 400, not a 500 from the raw SQL LIMIT", async () => {
+    const res = await stack.http.query(
+      "limitwidgets:query:widget:list",
+      { limit: 99999.5 },
+      TestUsers.admin,
+    );
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("validation_error");
+  });
+
+  test("negative offset is rejected with 400, not a 500 from the raw SQL OFFSET", async () => {
+    const res = await stack.http.query(
+      "limitwidgets:query:widget:list",
+      { offset: -1 },
+      TestUsers.admin,
+    );
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("validation_error");
+  });
+
+  test("limit above MAX_LIST_LIMIT is rejected with 400", async () => {
+    const res = await stack.http.query(
+      "limitwidgets:query:widget:list",
+      { limit: MAX_LIST_LIMIT + 1 },
+      TestUsers.admin,
+    );
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("validation_error");
+  });
+
+  test("limit at MAX_LIST_LIMIT and a valid offset succeed", async () => {
+    const res = await stack.http.query(
+      "limitwidgets:query:widget:list",
+      { limit: MAX_LIST_LIMIT, offset: 0 },
+      TestUsers.admin,
+    );
+    expect(res.status).toBe(200);
+  });
+});

package/src/api/__tests__/api-constants-completeness.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, test } from "bun:test";
+import { NON_PUBLIC_API_PATHS, PUBLIC_API_PATHS, Routes } from "../api-constants";
+
+// PUBLIC_API_PATHS is an allowlist: a missing entry (typo, forgotten route)
+// fails CLOSED — the route stays behind auth, never accidentally public.
+// But the classification itself must be total, or a route silently falls
+// into a third, unchecked state that nobody notices until it's either
+// exploited (should've been non-public) or reported broken by a client
+// (should've been public). This test forces every `Routes` entry into
+// exactly one of the two sets, in both directions:
+//   - every Routes entry has a classification (no silent gap)
+//   - every classified path still corresponds to a real Routes entry (no
+//     stale/typo'd literal drifting out of sync with Routes)
+function classifyRoutes(routes: Record<string, string>): {
+  unclassified: string[];
+  classifiedInBoth: string[];
+} {
+  const unclassified: string[] = [];
+  const classifiedInBoth: string[] = [];
+
+  for (const routePath of Object.values(routes)) {
+    const apiPath = `/api${routePath}`;
+    const isPublic = PUBLIC_API_PATHS.has(apiPath);
+    const isNonPublic = NON_PUBLIC_API_PATHS.has(apiPath);
+    if (isPublic && isNonPublic) classifiedInBoth.push(apiPath);
+    else if (!isPublic && !isNonPublic) unclassified.push(apiPath);
+  }
+
+  return { unclassified, classifiedInBoth };
+}
+
+describe("Routes / PUBLIC_API_PATHS classification completeness", () => {
+  test("every Routes entry is classified as exactly public XOR non-public", () => {
+    const { unclassified, classifiedInBoth } = classifyRoutes(Routes);
+
+    expect(unclassified).toEqual([]);
+    expect(classifiedInBoth).toEqual([]);
+  });
+
+  test("every PUBLIC_API_PATHS / NON_PUBLIC_API_PATHS entry maps back to a real Routes value", () => {
+    const knownApiPaths = new Set(Object.values(Routes).map((routePath) => `/api${routePath}`));
+
+    const stalePublic = [...PUBLIC_API_PATHS].filter((path) => !knownApiPaths.has(path));
+    const staleNonPublic = [...NON_PUBLIC_API_PATHS].filter((path) => !knownApiPaths.has(path));
+
+    expect(stalePublic).toEqual([]);
+    expect(staleNonPublic).toEqual([]);
+  });
+
+  // Regression guard for the mechanism itself: proves the completeness
+  // check actually fails when a route is added without a classification,
+  // rather than the two tests above being vacuously true by construction.
+  test("regression: an unclassified route is detected", () => {
+    const routesWithGap = {
+      ...Routes,
+      newFeature: "/new-feature-without-classification",
+    };
+
+    const { unclassified } = classifyRoutes(routesWithGap);
+
+    expect(unclassified).toEqual(["/api/new-feature-without-classification"]);
+  });
+});

package/src/api/__tests__/api.test.ts

@@ -12,7 +12,7 @@ import {
 import type { BatchResult, Dispatcher, WriteResult } from "../../pipeline/dispatcher";
 import { createTestUser, TestUsers } from "../../stack";
 import { waitFor } from "../../testing";
-import { createApiRoutes, pumpStream, StreamFrame } from "../routes";
+import { createApiRoutes, MAX_PAYLOAD_DEPTH, pumpStream, StreamFrame } from "../routes";
 import { buildServer } from "../server";
 
 const JWT_SECRET = "test-secret-at-least-32-chars-long!!";
@@ -236,6 +236,121 @@ describe("POST /api/command", () => {
   });
 });
 
+// --- Payload depth cap (security, 2026-08-13 audit Finding 1) ---
+//
+// A byte-limit on the body doesn't stop an attacker from nesting deeply
+// enough to blow the stack during recursive Zod validation — a minified
+// payload with thousands of nested wrappers stays well under 1MB. The
+// depth-cap in routes.ts walks the parsed object BEFORE it reaches any
+// handler's Zod schema, so it applies independently of what that schema
+// actually expects.
+
+function nestedPayload(depth: number): unknown {
+  let value: unknown = "leaf";
+  for (let i = 0; i < depth; i++) value = { nested: value };
+  return value;
+}
+
+describe("payload depth cap", () => {
+  test("rejects /api/write payload nested past MAX_PAYLOAD_DEPTH with 400 payload_too_deep", async () => {
+    const headers = await authHeader(adminUser);
+    const res = await req(
+      "POST",
+      "/api/write",
+      { type: "test:write:item:create", payload: nestedPayload(MAX_PAYLOAD_DEPTH + 1) },
+      headers,
+    );
+
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error.code).toBe("validation_error");
+    expect(body.error.details.fields[0]).toMatchObject({
+      path: "payload",
+      code: "too_deep",
+      i18nKey: "errors.validation.payload_too_deep",
+    });
+  });
+
+  test("a payload nested exactly at MAX_PAYLOAD_DEPTH clears the cap (fails ordinary schema validation instead)", async () => {
+    const headers = await authHeader(adminUser);
+    const res = await req(
+      "POST",
+      "/api/write",
+      { type: "test:write:item:create", payload: nestedPayload(MAX_PAYLOAD_DEPTH) },
+      headers,
+    );
+
+    // Still 400 — "name" is missing from this payload — but NOT via the
+    // depth cap. Proves the cap's boundary is exactly MAX_PAYLOAD_DEPTH.
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error.details.fields.some((f: { code: string }) => f.code === "too_deep")).toBe(
+      false,
+    );
+  });
+
+  test("rejects /api/query payload nested past MAX_PAYLOAD_DEPTH with 400", async () => {
+    const headers = await authHeader(adminUser);
+    const res = await req(
+      "POST",
+      "/api/query",
+      { type: "test:query:item:list", payload: nestedPayload(MAX_PAYLOAD_DEPTH + 1) },
+      headers,
+    );
+
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error.details.fields[0]).toMatchObject({ code: "too_deep" });
+  });
+
+  test("rejects /api/command payload nested past MAX_PAYLOAD_DEPTH with 400", async () => {
+    const headers = await authHeader(adminUser);
+    const res = await req(
+      "POST",
+      "/api/command",
+      { type: "test:write:item:create", payload: nestedPayload(MAX_PAYLOAD_DEPTH + 1) },
+      headers,
+    );
+
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error.details.fields[0]).toMatchObject({ code: "too_deep" });
+  });
+
+  test("rejects an /api/batch command payload nested past MAX_PAYLOAD_DEPTH with 400", async () => {
+    const headers = await authHeader(adminUser);
+    const res = await req(
+      "POST",
+      "/api/batch",
+      {
+        commands: [
+          { type: "test:write:item:create", payload: nestedPayload(MAX_PAYLOAD_DEPTH + 1) },
+        ],
+      },
+      headers,
+    );
+
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error.details.fields[0]).toMatchObject({ code: "too_deep" });
+  });
+
+  test("rejects /api/stream payload nested past MAX_PAYLOAD_DEPTH with 400, not an SSE error frame", async () => {
+    const headers = await authHeader(adminUser);
+    const res = await req(
+      "POST",
+      "/api/stream",
+      { type: "test:stream:item:tail", payload: nestedPayload(MAX_PAYLOAD_DEPTH + 1) },
+      headers,
+    );
+
+    expect(res.status).toBe(400);
+    expect(res.headers.get("content-type")).not.toContain("text/event-stream");
+    const body = await res.json();
+    expect(body.error.details.fields[0]).toMatchObject({ code: "too_deep" });
+  });
+});
+
 // --- pumpStream (SSE pull loop) ---
 
 function fakeSseWriter() {

package/src/api/__tests__/batch.integration.test.ts

@@ -50,6 +50,9 @@ const afterCommitHookLog: Array<{ id: EntityId; name: string }> = [];
 let afterCommitShouldThrow = false;
 const afterCommitThirdHookRan: string[] = [];
 
+// Delay injected into item:create-slow — reset per test.
+let slowHandlerDelayMs = 0;
+
 const itemFeature = defineFeature("batch", (r) => {
   const item = r.entity("item", itemEntity);
 
@@ -81,6 +84,21 @@ const itemFeature = defineFeature("batch", (r) => {
     { access: { roles: ["Admin"] } },
   );
 
+  // Handler with a controllable delay — used to simulate a slow in-flight
+  // handler for the parallel-idempotency race test.
+  r.writeHandler(
+    "item:create-slow",
+    z.object({ name: z.string().min(1) }),
+    async (event, ctx) => {
+      if (slowHandlerDelayMs > 0) {
+        await new Promise((resolve) => setTimeout(resolve, slowHandlerDelayMs));
+      }
+      const crud = createEventStoreExecutor(itemTable, itemEntity, { entityName: "item" });
+      return crud.create(event.payload, event.user, ctx.db);
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
   // Entity hook: inTransaction — records in memory
   r.hook(
     "postSave",
@@ -405,6 +423,41 @@ describe("POST /api/batch", () => {
     expect(await selectMany(stack.db, itemTable)).toHaveLength(0);
   });
 
+  test("idempotency: parallel writes with the same requestId — second waits for the first instead of re-executing", async () => {
+    slowHandlerDelayMs = 250;
+    const requestId = "batch-rid-parallel-slow";
+    const commands = [{ type: "batch:write:item:create-slow", payload: { name: "parallel-once" } }];
+
+    try {
+      const [first, second] = await Promise.all([
+        stack.http.batch(commands, admin, requestId),
+        (async () => {
+          // Give request #1 a head start so it wins the lock acquisition —
+          // the race being tested is "#2 waits", not "who acquires first".
+          await new Promise((resolve) => setTimeout(resolve, 50));
+          return stack.http.batch(commands, admin, requestId);
+        })(),
+      ]);
+
+      const firstBody = await first.json();
+      const secondBody = await second.json();
+
+      expect(firstBody.isSuccess).toBe(true);
+      expect(secondBody.isSuccess).toBe(true);
+      // Same cached response, not a fresh execution.
+      expect(secondBody.results).toEqual(firstBody.results);
+
+      // Exactly one row and one hook run — the second call did not re-run
+      // the handler and create a duplicate side effect.
+      const rows = await selectMany(stack.db, itemTable);
+      expect(rows).toHaveLength(1);
+      expect(inTxHookLog).toHaveLength(1);
+      expect(afterCommitHookLog).toHaveLength(1);
+    } finally {
+      slowHandlerDelayMs = 0;
+    }
+  });
+
   test("idempotency: corrupted cache entry is treated as miss and re-runs", async () => {
     const requestId = "batch-rid-corrupt";
     const cacheKey = `${RedisKeys.idempotency}${admin.tenantId}:${admin.id}:${requestId}`;

package/src/api/__tests__/body-limit.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import { z } from "zod";
 import { createEntity, createRegistry, createTextField, defineFeature } from "../../engine";
+import { BODY_LIMIT_OPT_OUT_PATHS, Routes } from "../api-constants";
 import { buildServer } from "../server";
 
 const JWT_SECRET = "test-secret-at-least-32-chars-long!!";
@@ -85,4 +86,93 @@ describe("request body limit", () => {
     const res = await postJson(app, "/api/write", 50_000);
     expect(res.status).toBe(401); // passes body-limit, reaches auth
   });
+
+  // Security regression (2026-08-13 audit, Finding 2): /api/stream used to be
+  // missing from the old BODY_LIMIT_PATHS allowlist, so it dispatched to the
+  // dispatcher without ever hitting the same 1MB cap /api/write enforces.
+  // Mirrors the /api/write cases above. Now covered structurally (see
+  // "default coverage sweep" below), kept as its own test for the historical
+  // regression it documents.
+  test("rejects POST /api/stream with body larger than maxRequestBytes with 413 (mirrors /api/write)", async () => {
+    const app = buildApp(1024);
+    const res = await postJson(app, "/api/stream", 2048);
+    expect(res.status).toBe(413);
+  });
+
+  test("accepts POST /api/stream with body within the limit (reaches auth layer, not 413)", async () => {
+    const app = buildApp(10_000);
+    const res = await postJson(app, "/api/stream", 100);
+    expect(res.status).toBe(401); // no JWT → 401, but size is fine
+  });
+});
+
+// fw#2145: BODY_LIMIT_PATHS inverted from an opt-in allowlist to an opt-out
+// list — registerBodyLimit now mounts on /api/* by construction, and only
+// BODY_LIMIT_OPT_OUT_PATHS (api-constants.ts) escapes it. These tests prove
+// that inversion rather than re-testing individual paths.
+describe("body-limit opt-out completeness", () => {
+  test("every opt-out entry resolves to a real Routes constant (no stale/typo'd paths)", () => {
+    for (const optOutPath of BODY_LIMIT_OPT_OUT_PATHS) {
+      const matchesKnownRoute = Object.values(Routes).some(
+        (route) => `/api${route}` === optOutPath,
+      );
+      expect(matchesKnownRoute).toBe(true);
+    }
+  });
+
+  test("the opt-out list is pinned to its reviewed members — a new exception must touch this test", () => {
+    expect([...BODY_LIMIT_OPT_OUT_PATHS]).toEqual([`/api${Routes.files}`]);
+  });
+});
+
+describe("default coverage sweep — proves the default, not a hand-maintained list", () => {
+  const OVERSIZED_BYTES = 2_000_000; // exceeds the default 1 MiB cap
+
+  // Derived from Routes itself (minus opt-out) rather than a hand-picked
+  // list — a route added to Routes tomorrow lands in this sweep
+  // automatically, with no test file to remember to update. Includes routes
+  // this test app never mounts (e.g. authLogin, no `auth` option passed to
+  // buildServer) and routes whose GET handler is mounted outside /api/*
+  // (health, healthReady, version — registerHealthRoutes/registerVersionRoute
+  // mount at the bare path, not under /api). Both still 413 on an oversized
+  // POST here: the /api/* body-limit middleware matches on path prefix
+  // before Hono resolves a handler, so it runs whether or not a route
+  // answers underneath. Verified directly: `POST /api/health` 413s even
+  // though the only real handler lives at `GET /health`.
+  const defaultLimitedRoutes = Object.values(Routes).filter(
+    (route) => !BODY_LIMIT_OPT_OUT_PATHS.has(`/api${route}`),
+  );
+
+  for (const route of defaultLimitedRoutes) {
+    test(`POST /api${route} 413s on an oversized body without needing its own list entry`, async () => {
+      const app = buildApp();
+      const res = await postJson(app, `/api${route}`, OVERSIZED_BYTES);
+      expect(res.status).toBe(413);
+    });
+  }
+
+  test("POST /api/files does not 413 on an oversized JSON body (explicit opt-out)", async () => {
+    const app = buildApp();
+    const res = await postJson(app, "/api/files", OVERSIZED_BYTES);
+    expect(res.status).not.toBe(413);
+  });
+
+  // Regression for the DoD: "neue Route ohne Eintrag in irgendeiner Liste
+  // bekommt automatisch ein Limit". Mounts a route the same way an app-owner's
+  // `extraRoutes` callback would — after buildServer, with zero Routes/
+  // opt-out entries — and proves it inherits the cap AND still serves a
+  // small body correctly (not an accidental always-413).
+  test("a route mounted after buildServer with no list entry anywhere still inherits the default limit", async () => {
+    const app = buildApp();
+    app.post("/api/totally-new-route-nobody-listed", async (c) => c.json({ ok: true }));
+
+    const oversized = await postJson(app, "/api/totally-new-route-nobody-listed", OVERSIZED_BYTES);
+    expect(oversized.status).toBe(413);
+
+    // Small body passes the size cap and reaches the auth guard (401, no
+    // JWT) — proves the 413 above is the size cap doing its job, not the
+    // route being unreachable for some unrelated reason.
+    const small = await postJson(app, "/api/totally-new-route-nobody-listed", 10);
+    expect(small.status).toBe(401);
+  });
 });

package/src/api/__tests__/server-jwt-ttl.test.ts

@@ -21,7 +21,7 @@ describe("buildServer — jwtTtl default depends on sessionChecker wiring", () =
     expect(jwt.ttlSeconds).toBe(60 * 60);
   });
 
-  test("auth with sessionChecker → session-backed default (24h)", () => {
+  test("auth with sessionChecker → session-backed default (8h)", () => {
     const { jwt } = buildServer({
       registry,
       context: {},
@@ -31,7 +31,7 @@ describe("buildServer — jwtTtl default depends on sessionChecker wiring", () =
         sessionChecker: async () => "live",
       },
     });
-    expect(jwt.ttlSeconds).toBe(24 * 60 * 60);
+    expect(jwt.ttlSeconds).toBe(8 * 60 * 60);
   });
 
   test("explicit jwtTtl wins regardless of sessionChecker wiring", () => {

package/src/api/api-constants.ts

@@ -27,10 +27,10 @@ export const Routes = {
   authConfirmAccountUnlock: "/auth/confirm-account-unlock",
   authSignupRequest: "/auth/signup-request",
   authSignupConfirm: "/auth/signup-confirm",
-  // Tenant-Invite (Magic-Link): 3 separate accept-Endpoints für klare
-  // Branch-Separation. Plus invite-info als public-readable details
-  // damit das Frontend "Du wirst eingeladen zu Tenant X als Role Y"
-  // anzeigen kann bevor der User submitted.
+  // Tenant invite (magic link): 3 separate accept endpoints for clear
+  // branch separation. Plus invite-info as public-readable details so
+  // the frontend can show "You're invited to tenant X as role Y" before
+  // the user submits.
   authInviteAccept: "/auth/invite-accept",
   authInviteAcceptWithLogin: "/auth/invite-accept-with-login",
   authInviteSignupComplete: "/auth/invite-signup-complete",
@@ -53,9 +53,9 @@ export const PUBLIC_API_PATHS: ReadonlySet<string> = new Set([
   `/api${Routes.authConfirmAccountUnlock}`,
   `/api${Routes.authSignupRequest}`,
   `/api${Routes.authSignupConfirm}`,
-  // invite-accept braucht JWT (logged-in User, Branch 1) — NICHT public.
-  // invite-accept-with-login (Branch 2) und invite-signup-complete
-  // (Branch 3) sind anonymous, brauchen public-skip.
+  // invite-accept requires a JWT (logged-in user, branch 1) — NOT public.
+  // invite-accept-with-login (branch 2) and invite-signup-complete
+  // (branch 3) are anonymous and need the public skip.
   `/api${Routes.authInviteAcceptWithLogin}`,
   `/api${Routes.authInviteSignupComplete}`,
   `/api${Routes.authInviteInfo}`,
@@ -64,6 +64,43 @@ export const PUBLIC_API_PATHS: ReadonlySet<string> = new Set([
   `/api${Routes.version}`,
 ]);
 
+// Every other route in `Routes` — explicit, so a route can never fall
+// through to "public" by simply being absent from PUBLIC_API_PATHS. A
+// completeness test checks every `Routes` entry against the union of this
+// set and PUBLIC_API_PATHS, so a new route with neither entry fails CI
+// instead of shipping open.
+export const NON_PUBLIC_API_PATHS: ReadonlySet<string> = new Set([
+  `/api${Routes.write}`,
+  `/api${Routes.batch}`,
+  `/api${Routes.query}`,
+  `/api${Routes.command}`,
+  `/api${Routes.sse}`,
+  `/api${Routes.stream}`,
+  // Namespace prefix used only for body-limit registration
+  // (`/api/auth/*` in route-registrars.ts) — never dispatched as its own
+  // route, so it carries no auth bypass either way. Classified non-public
+  // to keep the completeness check total.
+  `/api${Routes.auth}`,
+  `/api${Routes.authLogout}`,
+  `/api${Routes.authTenants}`,
+  `/api${Routes.authSwitchTenant}`,
+  // invite-accept requires a JWT (Branch 1, see PUBLIC_API_PATHS above).
+  `/api${Routes.authInviteAccept}`,
+  `/api${Routes.files}`,
+]);
+
+// Opt-out from the default request-body-size cap (registerBodyLimit applies
+// it to all of /api/* by construction — a new route needs no entry here to
+// be covered). Only routes with their own, deliberately different size
+// contract belong on this list; forgetting an entry is safe (over-limited,
+// not unlimited), so keep it as short as the actual exceptions.
+export const BODY_LIMIT_OPT_OUT_PATHS: ReadonlySet<string> = new Set([
+  // Multipart uploads validate size against `maxUploadSize`/field `maxSize`
+  // (often >1 MiB) after Hono's multipart parse, not before — the generic
+  // JSON cap would reject legitimate uploads before that check ever runs.
+  `/api${Routes.files}`,
+]);
+
 // Methods that can mutate server state. GET/HEAD/OPTIONS are safe under
 // CORS + SameSite-cookie semantics and skip the CSRF / Origin guards entirely.
 export const STATE_CHANGING_METHODS: ReadonlySet<string> = new Set([

package/src/api/auth-middleware.ts

@@ -35,6 +35,17 @@ export type AuthTransport = "cookie" | "bearer";
 // can't keep a locked account authenticated.
 export type AuthSessionStatus = "live" | "revoked" | "expired" | "missing" | "blocked";
 
+// A "live" result may additionally carry roles re-derived fresh from the DB
+// (global user roles + tenant-membership roles, composed via
+// buildSessionRoles) instead of trusting the JWT's roles claim, which was
+// frozen at login/mint time. Bare "live" (no roles) is the fail-open path —
+// a DB throw during role derivation must not turn into a lockout — and the
+// case where no sessionChecker is wired at all; the middleware falls back to
+// payload.roles in both.
+export type AuthSessionCheckResult =
+  | AuthSessionStatus
+  | { readonly status: "live"; readonly roles: readonly string[] };
+
 // Called by the middleware after JWT-verify. Gets the sid AND the expected
 // userId from the JWT's `sub` — the checker MUST confirm the session row
 // both exists + is live AND belongs to expectedUserId. Without the userId
@@ -45,7 +56,7 @@ export type AuthSessionStatus = "live" | "revoked" | "expired" | "missing" | "bl
 export type AuthSessionChecker = (
   sid: string,
   expectedUserId: string,
-) => Promise<AuthSessionStatus>;
+) => Promise<AuthSessionCheckResult>;
 
 // Resolves a raw bearer token into a SessionUser, or null when no registered
 // provider claims it (or the claiming provider rejects it as unknown/revoked/
@@ -276,12 +287,17 @@ export function authMiddleware(jwt: JwtHelper, options: AuthMiddlewareOptions =
     // token carries a sid.
     // A checker wired without a sid on the token means the token predates
     // session tracking (or the JWT was forged) — reject.
+    let derivedRoles: readonly string[] | undefined;
     if (sessionChecker) {
       if (payload.jti) {
-        const status = await sessionChecker(payload.jti, payload.sub);
+        const result = await sessionChecker(payload.jti, payload.sub);
+        const status = typeof result === "string" ? result : result.status;
         if (status !== "live") {
           return sessionInvalid(c, status);
         }
+        if (typeof result === "object") {
+          derivedRoles = result.roles;
+        }
       } else {
         return sessionInvalid(c, "no_sid");
       }
@@ -306,7 +322,7 @@ export function authMiddleware(jwt: JwtHelper, options: AuthMiddlewareOptions =
     const user: SessionUser = {
       id: payload.sub,
       tenantId: payload.tenantId,
-      roles: payload.roles,
+      roles: derivedRoles ?? payload.roles,
       ...(payload.timezone ? { timezone: payload.timezone } : {}),
       ...(payload.claims ? { claims: payload.claims } : {}),
       ...(payload.jti ? { sid: payload.jti } : {}),

package/src/api/index.ts

@@ -5,6 +5,7 @@ export type {
   AnonymousAccessResolved,
   AuthMiddlewareOptions,
   AuthSessionChecker,
+  AuthSessionCheckResult,
   AuthSessionStatus,
   TenantExists,
   TenantLifecycleStatusResolver,