@cosmicdrift/kumiko-framework 0.296.0 → 0.299.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.296.0",
+  "version": "0.299.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>",
@@ -198,8 +198,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.296.0",
-    "@cosmicdrift/kumiko-types": "0.296.0",
+    "@cosmicdrift/kumiko-http": "0.299.0",
+    "@cosmicdrift/kumiko-types": "0.299.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -215,7 +215,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.296.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.299.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

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

@@ -164,10 +164,10 @@ describe("default coverage sweep — proves the default, not a hand-maintained l
   });
 
   // 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).
+  // bekommt automatisch ein Limit". Mounts a route directly on the app
+  // 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 }));

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

@@ -0,0 +1,584 @@
+// Full-stack proof for the declarative extraRoutes API (kumiko-framework#3050):
+// each `entry` tier gets the matching guard + deps from buildServer, driven
+// via real HTTP (setupTestStack + app.request), never createTestDispatcher.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { createHmac } from "node:crypto";
+import { z } from "zod";
+import { createRegistry, defineFeature, type TenantId } from "../../engine";
+import { RateLimitError } from "../../errors";
+import { setupTestStack, type TestStack, TestUsers } from "../../stack";
+import {
+  type AnonymousExtraRoute,
+  type ExtraRouteDefinition,
+  ExtraRouteRejection,
+  type SignatureExtraRoute,
+  signatureRoute,
+  type UserExtraRoute,
+} from "../extra-route";
+import { buildServer } from "../server";
+
+const TENANT_ID = "00000000-0000-4000-8000-000000000001" as TenantId;
+const JWT_SECRET = "test-extra-routes-secret-32-chars-min!!";
+
+const probeFeature = defineFeature("extra-route-probe", (r) => {
+  r.queryHandler({
+    name: "ping",
+    schema: z.object({}),
+    access: { roles: ["anonymous"] },
+    rateLimit: { per: "ip", limit: 2, windowSeconds: 60 },
+    handler: async () => ({ pong: true }),
+  });
+  r.writeHandler({
+    name: "self-write",
+    schema: z.object({ note: z.string() }),
+    access: { roles: ["User", "Admin"] },
+    handler: async (event) => ({
+      isSuccess: true as const,
+      data: { userId: event.user.id, note: event.payload.note },
+    }),
+  });
+  r.writeHandler({
+    name: "admin-only-write",
+    schema: z.object({}),
+    access: { roles: ["Admin"] },
+    handler: async () => ({ isSuccess: true as const, data: { ok: true as const } }),
+  });
+  r.writeHandler({
+    name: "hmac-write",
+    schema: z.object({ note: z.string() }),
+    access: { roles: ["SystemAdmin"] },
+    handler: async (event) => ({
+      isSuccess: true as const,
+      data: { tenantSeen: event.user.tenantId, note: event.payload.note },
+    }),
+  });
+});
+
+// Module-level store — proves deps.write ran via a follow-up query, no DB needed.
+const anonymousWriteStore = new Map<string, string[]>();
+
+const anonymousWriteFeature = defineFeature("anonymous-write-probe", (r) => {
+  r.writeHandler({
+    name: "anon-write",
+    schema: z.object({ note: z.string() }),
+    access: { roles: ["anonymous"] },
+    handler: async (event) => {
+      const notes = anonymousWriteStore.get(event.user.tenantId) ?? [];
+      notes.push(event.payload.note);
+      anonymousWriteStore.set(event.user.tenantId, notes);
+      return { isSuccess: true as const, data: { tenantSeen: event.user.tenantId } };
+    },
+  });
+  r.writeHandler({
+    name: "anon-gated-write",
+    schema: z.object({}),
+    access: { roles: ["Admin"] },
+    handler: async () => ({ isSuccess: true as const, data: { ok: true as const } }),
+  });
+  r.queryHandler({
+    name: "anon-notes",
+    schema: z.object({}),
+    access: { roles: ["anonymous"] },
+    handler: async (event) => ({ notes: anonymousWriteStore.get(event.user.tenantId) ?? [] }),
+  });
+});
+
+describe("extraRoutes: entry:anonymous", () => {
+  const pingRoute: AnonymousExtraRoute = {
+    method: "GET",
+    path: "/public/ping",
+    entry: "anonymous",
+    handler: async (c, deps) => {
+      try {
+        const result = await deps.systemQuery("extra-route-probe:query:ping", {}, TENANT_ID);
+        return c.json(result as { pong: boolean }); // @cast-boundary engine-payload
+      } catch (e) {
+        if (e instanceof RateLimitError) {
+          return c.json({ error: { code: e.code } }, e.httpStatus);
+        }
+        throw e;
+      }
+    },
+  };
+
+  let stack: TestStack;
+
+  beforeAll(async () => {
+    stack = await setupTestStack({ features: [probeFeature], extraRoutes: [pingRoute] });
+  });
+
+  afterAll(() => stack.cleanup());
+
+  test("reachable without any session, outside /api", async () => {
+    const res = await stack.app.request("/public/ping", {
+      headers: { "x-forwarded-for": "203.0.113.10" },
+    });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ pong: true });
+  });
+
+  test("systemQuery wraps requestContext so a handler's per-ip rateLimit actually fires", async () => {
+    const ip = "203.0.113.20";
+    for (let i = 0; i < 2; i++) {
+      const res = await stack.app.request("/public/ping", { headers: { "x-forwarded-for": ip } });
+      expect(res.status).toBe(200);
+    }
+    const limited = await stack.app.request("/public/ping", { headers: { "x-forwarded-for": ip } });
+    expect(limited.status).toBe(429);
+    const body = (await limited.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("rate_limited");
+  });
+});
+
+describe("extraRoutes: entry:anonymous under /api/* (kumiko-framework#3050 bypass fix)", () => {
+  const apiPingRoute: AnonymousExtraRoute = {
+    method: "GET",
+    path: "/api/public-ping",
+    entry: "anonymous",
+    handler: async (c) => c.json({ pong: true }),
+  };
+
+  test("without anonymousAccess wired, the jwtGuard still 401s — anonymous does NOT bypass /api/*", async () => {
+    const stack = await setupTestStack({ features: [probeFeature], extraRoutes: [apiPingRoute] });
+    try {
+      const res = await stack.app.request("/api/public-ping");
+      expect(res.status).toBe(401);
+    } finally {
+      await stack.cleanup();
+    }
+  });
+
+  test("with anonymousAccess wired, the request clears the guard exactly like any other anonymous /api/* call", async () => {
+    const stack = await setupTestStack({
+      features: [probeFeature],
+      extraRoutes: [apiPingRoute],
+      anonymousAccess: { defaultTenantId: TENANT_ID },
+    });
+    try {
+      const res = await stack.app.request("/api/public-ping");
+      expect(res.status).toBe(200);
+    } finally {
+      await stack.cleanup();
+    }
+  });
+});
+
+describe("extraRoutes: entry:anonymous deps.write (kumiko-framework#3050 anonymous write)", () => {
+  const writeRoute: AnonymousExtraRoute = {
+    method: "POST",
+    path: "/api/anon-write-probe",
+    entry: "anonymous",
+    handler: async (c, deps) => {
+      const result = await deps.write("anonymous-write-probe:write:anon-write", {
+        note: "from-anon",
+      });
+      return c.json(result);
+    },
+  };
+  const gatedWriteRoute: AnonymousExtraRoute = {
+    method: "POST",
+    path: "/api/anon-gated-write-probe",
+    entry: "anonymous",
+    handler: async (c, deps) => {
+      const result = await deps.write("anonymous-write-probe:write:anon-gated-write", {});
+      return c.json(result);
+    },
+  };
+  // Catches the thrown error itself and surfaces its message — proves what
+  // deps.write actually throws, not just that *something* threw.
+  const outsideApiWriteRoute: AnonymousExtraRoute = {
+    method: "POST",
+    path: "/public/anon-write-probe",
+    entry: "anonymous",
+    handler: async (c, deps) => {
+      try {
+        const result = await deps.write("anonymous-write-probe:write:anon-write", {
+          note: "should-not-persist",
+        });
+        return c.json(result);
+      } catch (e) {
+        return c.json({ error: { message: e instanceof Error ? e.message : String(e) } }, 500);
+      }
+    },
+  };
+
+  const OTHER_TENANT_ID = "00000000-0000-4000-8000-000000000099" as TenantId;
+  let stack: TestStack;
+
+  beforeAll(async () => {
+    anonymousWriteStore.clear();
+    stack = await setupTestStack({
+      features: [anonymousWriteFeature],
+      extraRoutes: [writeRoute, gatedWriteRoute, outsideApiWriteRoute],
+      // No defaultTenantId: X-Tenant picks the tenant per request, so the cross-tenant test below is real.
+      anonymousAccess: {
+        tenantExists: async (id) => id === TENANT_ID || id === OTHER_TENANT_ID,
+      },
+    });
+  });
+
+  afterAll(() => stack.cleanup());
+
+  test("under /api/ with anonymousAccess wired, deps.write runs against a handler allowing roles:['anonymous'] and actually persists", async () => {
+    const res = await stack.app.request("/api/anon-write-probe", {
+      method: "POST",
+      headers: { "X-Tenant": TENANT_ID },
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { isSuccess: boolean; data: { tenantSeen: string } };
+    expect(body.isSuccess).toBe(true);
+    expect(body.data.tenantSeen).toBe(TENANT_ID);
+
+    const notesRes = await stack.app.request("/api/query", {
+      method: "POST",
+      headers: { "content-type": "application/json", "X-Tenant": TENANT_ID },
+      body: JSON.stringify({ type: "anonymous-write-probe:query:anon-notes", payload: {} }),
+    });
+    expect(notesRes.status).toBe(200);
+    const notesBody = (await notesRes.json()) as { data: { notes: readonly string[] } };
+    expect(notesBody.data.notes).toContain("from-anon");
+  });
+
+  test("deps.write is access-checked as the anonymous session — a role-gated handler is denied, nothing written", async () => {
+    const before = anonymousWriteStore.get(TENANT_ID)?.length ?? 0;
+    const res = await stack.app.request("/api/anon-gated-write-probe", {
+      method: "POST",
+      headers: { "X-Tenant": TENANT_ID },
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { isSuccess: boolean; error?: { code: string } };
+    expect(body.isSuccess).toBe(false);
+    expect(body.error?.code).toBe("access_denied");
+    expect(anonymousWriteStore.get(TENANT_ID)?.length ?? 0).toBe(before);
+  });
+
+  test("deps.write parity: a Bearer token whose role clears the gate succeeds — same as calling /api/write directly (see the no-token case above, which 403s)", async () => {
+    const token = await stack.jwt.sign(TestUsers.admin);
+    const res = await stack.app.request("/api/anon-gated-write-probe", {
+      method: "POST",
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { isSuccess: boolean };
+    expect(body.isSuccess).toBe(true);
+  });
+
+  test("deps.write lands in the request-resolved tenant, not a different one", async () => {
+    // The store is module-level; earlier tests already wrote into TENANT_ID.
+    anonymousWriteStore.clear();
+    const res = await stack.app.request("/api/anon-write-probe", {
+      method: "POST",
+      headers: { "X-Tenant": OTHER_TENANT_ID },
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { data: { tenantSeen: string } };
+    expect(body.data.tenantSeen).toBe(OTHER_TENANT_ID);
+    expect(anonymousWriteStore.get(OTHER_TENANT_ID)).toContain("from-anon");
+    expect(anonymousWriteStore.has(TENANT_ID)).toBe(false);
+  });
+
+  test("outside /api/, deps.write throws with a message naming the /api/ + anonymousAccess requirement, nothing written", async () => {
+    const before = anonymousWriteStore.get(TENANT_ID)?.length ?? 0;
+    const res = await stack.app.request("/public/anon-write-probe", { method: "POST" });
+    expect(res.status).toBe(500);
+    const body = (await res.json()) as { error: { message: string } };
+    expect(body.error.message).toMatch(/mounted\s+under\s+"\/api\/"\s+with\s+anonymousAccess/);
+    expect(anonymousWriteStore.get(TENANT_ID)?.length ?? 0).toBe(before);
+  });
+});
+
+describe("extraRoutes: entry:user", () => {
+  const selfWriteRoute: UserExtraRoute = {
+    method: "POST",
+    path: "/api/user-probe",
+    entry: "user",
+    handler: async (c, deps) => {
+      const result = await deps.write("extra-route-probe:write:self-write", { note: "hi" });
+      return c.json({ userId: deps.user.id, result });
+    },
+  };
+  const adminOnlyRoute: UserExtraRoute = {
+    method: "POST",
+    path: "/api/user-admin-probe",
+    entry: "user",
+    handler: async (c, deps) => {
+      const result = await deps.write("extra-route-probe:write:admin-only-write", {});
+      return c.json(result);
+    },
+  };
+
+  let stack: TestStack;
+
+  beforeAll(async () => {
+    stack = await setupTestStack({
+      features: [probeFeature],
+      extraRoutes: [selfWriteRoute, adminOnlyRoute],
+    });
+  });
+
+  afterAll(() => stack.cleanup());
+
+  test("without a session → 401 (jwtGuard rejects before the route ever runs)", async () => {
+    const res = await stack.app.request("/api/user-probe", { method: "POST" });
+    expect(res.status).toBe(401);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("missing_token");
+  });
+
+  test("with a real session → 200, deps.user.id matches the JWT subject", async () => {
+    const token = await stack.jwt.sign(TestUsers.user);
+    const res = await stack.app.request("/api/user-probe", {
+      method: "POST",
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { userId: string; result: { isSuccess: boolean } };
+    expect(body.userId).toBe(TestUsers.user.id);
+    expect(body.result.isSuccess).toBe(true);
+  });
+
+  test("deps.write runs access-checked as the calling user — 'User' role denied on an Admin-only handler", async () => {
+    const token = await stack.jwt.sign(TestUsers.user);
+    const res = await stack.app.request("/api/user-admin-probe", {
+      method: "POST",
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { isSuccess: boolean; error?: { code: string } };
+    expect(body.isSuccess).toBe(false);
+    expect(body.error?.code).toBe("access_denied");
+  });
+
+  test("deps.write succeeds for a user whose role clears the handler's access check", async () => {
+    const token = await stack.jwt.sign(TestUsers.admin);
+    const res = await stack.app.request("/api/user-admin-probe", {
+      method: "POST",
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { isSuccess: boolean };
+    expect(body.isSuccess).toBe(true);
+  });
+});
+
+describe("extraRoutes: entry:user under an anonymousAccess-wired server", () => {
+  const selfWriteRoute: UserExtraRoute = {
+    method: "POST",
+    path: "/api/user-probe",
+    entry: "user",
+    handler: async (c, deps) => c.json({ userId: deps.user.id }),
+  };
+
+  test("no JWT: jwtGuard synthesises an anonymous user, buildExtraRouteHonoHandler's own ANONYMOUS_ROLE check still 401s", async () => {
+    const stack = await setupTestStack({
+      features: [probeFeature],
+      extraRoutes: [selfWriteRoute],
+      anonymousAccess: { defaultTenantId: TENANT_ID },
+    });
+    try {
+      const res = await stack.app.request("/api/user-probe", { method: "POST" });
+      expect(res.status).toBe(401);
+      const body = (await res.json()) as { error: { code: string } };
+      expect(body.error.code).toBe("unauthenticated");
+    } finally {
+      await stack.cleanup();
+    }
+  });
+});
+
+test("extraRoutes: entry:user route mounted outside /api throws at boot", () => {
+  const registry = createRegistry([probeFeature]);
+  expect(() =>
+    buildServer({
+      registry,
+      context: {},
+      jwtSecret: JWT_SECRET,
+      extraRoutes: [
+        {
+          method: "GET",
+          path: "/user-outside-api",
+          entry: "user",
+          handler: async (c) => c.json({}),
+        },
+      ],
+    }),
+  ).toThrow(/must be\s+mounted under "\/api\/"/);
+});
+
+test("extraRoutes: entry:signature wildcard under /api throws at boot", () => {
+  const registry = createRegistry([probeFeature]);
+  expect(() =>
+    buildServer({
+      registry,
+      context: {},
+      jwtSecret: JWT_SECRET,
+      extraRoutes: [
+        signatureRoute({
+          method: "POST",
+          path: "/api/*",
+          entry: "signature",
+          verify: async () => true,
+          handler: async (c) => c.json({}),
+        }),
+      ],
+    }),
+  ).toThrow(/must not\s+use a wildcard under "\/api\/"/);
+});
+
+test("extraRoutes: an unknown entry value throws at boot", () => {
+  const registry = createRegistry([probeFeature]);
+  // A JS caller without the ExtraRouteDefinition type can construct this at
+  // runtime — buildServer must reject it at boot, not at first request.
+  const badRoute = {
+    method: "GET",
+    path: "/whatever",
+    entry: "admin",
+    handler: async () => new Response(),
+  } as unknown as ExtraRouteDefinition; // @cast-boundary simulates an untyped JS caller passing an unknown entry
+  expect(() =>
+    buildServer({
+      registry,
+      context: {},
+      jwtSecret: JWT_SECRET,
+      extraRoutes: [badRoute],
+    }),
+  ).toThrow(/unknown entry/);
+});
+
+describe("extraRoutes: entry:signature", () => {
+  const HMAC_KEY = "shared-hmac-key";
+
+  function signHmac(rawBody: string): string {
+    return createHmac("sha256", HMAC_KEY).update(rawBody).digest("hex");
+  }
+
+  const webhookRoute: SignatureExtraRoute<{ note: string }> = {
+    method: "POST",
+    path: "/webhooks/probe",
+    entry: "signature",
+    verify: async (req) => {
+      if (req.headers["x-force-404"] === "1") {
+        throw new ExtraRouteRejection(404, { error: "unknown-provider" });
+      }
+      if (req.headers["x-hmac"] !== signHmac(req.rawBody)) {
+        throw new Error("signature mismatch");
+      }
+      return { note: (JSON.parse(req.rawBody) as { note: string }).note };
+    },
+    handler: async (c, verified, deps) => {
+      const result = await deps.dispatchSystemWrite({
+        handlerQn: "extra-route-probe:write:hmac-write",
+        payload: { note: verified.note },
+        tenantId: TENANT_ID,
+      });
+      return c.json(result);
+    },
+  };
+
+  const webhookParamRoute: SignatureExtraRoute<{ provider: string }> = {
+    method: "POST",
+    path: "/api/webhooks/:provider",
+    entry: "signature",
+    verify: async (req) => {
+      if (req.headers["x-hmac"] !== signHmac(req.rawBody)) throw new Error("signature mismatch");
+      return { provider: req.params["provider"] ?? "" };
+    },
+    handler: async (c, verified) => c.json({ provider: verified.provider }),
+  };
+
+  let stack: TestStack;
+
+  beforeAll(async () => {
+    stack = await setupTestStack({
+      features: [probeFeature],
+      extraRoutes: [signatureRoute(webhookRoute), signatureRoute(webhookParamRoute)],
+    });
+  });
+
+  afterAll(() => stack.cleanup());
+
+  test("wrong signature → 401 extra_route_signature_invalid", async () => {
+    const res = await stack.app.request("/webhooks/probe", {
+      method: "POST",
+      headers: { "x-hmac": "wrong", "content-type": "application/json" },
+      body: JSON.stringify({ note: "x" }),
+    });
+    expect(res.status).toBe(401);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("extra_route_signature_invalid");
+  });
+
+  test("right signature → 200, dispatchSystemWrite's SystemAdmin write is visible in the response", async () => {
+    const rawBody = JSON.stringify({ note: "from-webhook" });
+    const res = await stack.app.request("/webhooks/probe", {
+      method: "POST",
+      headers: { "x-hmac": signHmac(rawBody), "content-type": "application/json" },
+      body: rawBody,
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      isSuccess: boolean;
+      data?: { tenantSeen: string; note: string };
+    };
+    expect(body.isSuccess).toBe(true);
+    expect(body.data?.tenantSeen).toBe(TENANT_ID);
+    expect(body.data?.note).toBe("from-webhook");
+  });
+
+  test("verify() throwing ExtraRouteRejection(404, body) surfaces exactly that body", async () => {
+    const res = await stack.app.request("/webhooks/probe", {
+      method: "POST",
+      headers: { "x-force-404": "1", "content-type": "application/json" },
+      body: JSON.stringify({ note: "x" }),
+    });
+    expect(res.status).toBe(404);
+    expect(await res.json()).toEqual({ error: "unknown-provider" });
+  });
+
+  test("mounted under /api/:provider — no session needed, honoPathToRegex matches the :param, rawBody arrives intact through /api/*", async () => {
+    const rawBody = JSON.stringify({ event: "payment.succeeded" });
+    const res = await stack.app.request("/api/webhooks/stripe", {
+      method: "POST",
+      headers: { "x-hmac": signHmac(rawBody), "content-type": "application/json" },
+      body: rawBody,
+    });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ provider: "stripe" });
+  });
+});
+
+// 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
+// error if the constraint ever stops firing.
+function _requiresEntry(): ExtraRouteDefinition {
+  // @ts-expect-error — entry is required; a def without it must not satisfy ExtraRouteDefinition.
+  return { method: "GET", path: "/probe", handler: () => new Response() };
+}
+
+function _anonymousDepsHaveNoDispatchSystemWrite(): AnonymousExtraRoute {
+  return {
+    method: "GET",
+    path: "/probe",
+    entry: "anonymous",
+    handler: (c, deps) => {
+      // @ts-expect-error — anonymous deps expose systemQuery only, no dispatchSystemWrite.
+      void deps.dispatchSystemWrite;
+      return c.json({});
+    },
+  };
+}
+
+function _userDepsHaveNoDispatchSystemWrite(): UserExtraRoute {
+  return {
+    method: "GET",
+    path: "/api/probe",
+    entry: "user",
+    handler: (c, deps) => {
+      // @ts-expect-error — user deps expose query/write only, no dispatchSystemWrite.
+      void deps.dispatchSystemWrite;
+      return c.json({});
+    },
+  };
+}

package/src/api/extra-route.ts

@@ -0,0 +1,146 @@
+// ExtraRoute — declarative replacement for the old `extraRoutes: (app, deps)
+// => void` closure (kumiko-framework#3050). Every entry declares its access
+// tier (`entry`) up front; buildServer wires the matching guard + deps
+// instead of handing every route a raw db/redis escape hatch.
+
+import type { Context, Hono } from "hono";
+import type {
+  HttpRouteMethod,
+  Registry,
+  SessionUser,
+  TenantId,
+  WriteResult,
+} from "../engine/types";
+import type { SecretsContext } from "../secrets";
+
+export const ExtraRouteEntries = {
+  anonymous: "anonymous",
+  user: "user",
+  signature: "signature",
+} as const;
+
+export type ExtraRouteEntry = (typeof ExtraRouteEntries)[keyof typeof ExtraRouteEntries];
+
+export type AnonymousExtraRouteDeps = {
+  // biome-ignore lint/suspicious/noExplicitAny: Hono's generic-Param ist im Framework-Boundary unsichtbar
+  readonly app: Hono<any, any>;
+  readonly registry: Registry;
+  readonly systemQuery: (type: string, payload: unknown, tenantId: TenantId) => Promise<unknown>;
+  /** Runs as the session the /api chain resolved for this request —
+   *  anonymous when no token is sent, the authenticated user otherwise.
+   *  Never more than that caller could already do via /api/write: same
+   *  user, same request-resolved tenant (never overridable), only under
+   *  "/api/" (the only path that populates a session user). */
+  readonly write: (type: string, payload: unknown) => Promise<WriteResult>;
+};
+
+export type AnonymousExtraRoute = {
+  readonly method: HttpRouteMethod;
+  readonly path: string;
+  readonly entry: "anonymous";
+  readonly handler: (
+    // biome-ignore lint/suspicious/noExplicitAny: Hono context generics are invisible at the framework boundary
+    c: Context<any, any>,
+    deps: AnonymousExtraRouteDeps,
+  ) => Response | Promise<Response>;
+};
+
+export type UserExtraRouteDeps = {
+  // biome-ignore lint/suspicious/noExplicitAny: Hono's generic-Param ist im Framework-Boundary unsichtbar
+  readonly app: Hono<any, any>;
+  readonly registry: Registry;
+  readonly user: SessionUser;
+  readonly query: (type: string, payload: unknown) => Promise<unknown>;
+  readonly write: (type: string, payload: unknown) => Promise<WriteResult>;
+};
+
+export type UserExtraRoute = {
+  readonly method: HttpRouteMethod;
+  readonly path: string;
+  readonly entry: "user";
+  readonly handler: (
+    // biome-ignore lint/suspicious/noExplicitAny: Hono context generics are invisible at the framework boundary
+    c: Context<any, any>,
+    deps: UserExtraRouteDeps,
+  ) => Response | Promise<Response>;
+};
+
+export type SignatureExtraRouteVerifyRequest = {
+  readonly rawBody: string;
+  /** Lowercase header names — Hono/undici normalize incoming headers to
+   *  lowercase, verify() must not have to re-normalize per provider. */
+  readonly headers: Readonly<Record<string, string>>;
+  readonly params: Readonly<Record<string, string>>;
+  readonly query: Readonly<Record<string, string>>;
+};
+
+export type SignatureExtraRouteVerifyDeps = {
+  readonly registry: Registry;
+  readonly secrets?: SecretsContext;
+};
+
+export type SystemDispatchArgs = {
+  readonly handlerQn: string;
+  readonly payload: unknown;
+  readonly tenantId: TenantId;
+};
+
+export type SignatureExtraRouteDeps = {
+  // biome-ignore lint/suspicious/noExplicitAny: Hono's generic-Param ist im Framework-Boundary unsichtbar
+  readonly app: Hono<any, any>;
+  readonly registry: Registry;
+  readonly secrets?: SecretsContext;
+  readonly systemQuery: (type: string, payload: unknown, tenantId: TenantId) => Promise<unknown>;
+  /** Privilege scope: SystemAdmin of the target tenant, WITHOUT the route's
+   *  access check — only reachable because verify() has already proven the
+   *  caller's authenticity (signature, HMAC state, etc.). */
+  readonly dispatchSystemWrite: (args: SystemDispatchArgs) => Promise<WriteResult>;
+  readonly dispatchSystemQuery: (args: SystemDispatchArgs) => Promise<unknown>;
+};
+
+export type SignatureExtraRoute<TVerified> = {
+  readonly method: HttpRouteMethod;
+  readonly path: string;
+  readonly entry: "signature";
+  readonly verify: (
+    request: SignatureExtraRouteVerifyRequest,
+    deps: SignatureExtraRouteVerifyDeps,
+  ) => Promise<TVerified>;
+  readonly handler: (
+    // biome-ignore lint/suspicious/noExplicitAny: Hono context generics are invisible at the framework boundary
+    c: Context<any, any>,
+    verified: TVerified,
+    deps: SignatureExtraRouteDeps,
+  ) => Response | Promise<Response>;
+};
+
+export type ExtraRouteDefinition =
+  | AnonymousExtraRoute
+  | UserExtraRoute
+  | SignatureExtraRoute<unknown>;
+
+/** Narrows a `SignatureExtraRoute<T>` into the storable `ExtraRouteDefinition`
+ *  union. The single point where the verify/handler generic `T` is erased —
+ *  callers keep full type-safety between their own verify() and handler(). */
+export function signatureRoute<T>(def: SignatureExtraRoute<T>): ExtraRouteDefinition {
+  // @cast-boundary generic erasure at the public ExtraRouteDefinition boundary;
+  // verify() and handler() above stay paired through T at the call site.
+  return def as unknown as SignatureExtraRoute<unknown>;
+}
+
+export type ExtraRouteRejectionStatus = 400 | 401 | 403 | 404 | 500;
+
+/** Thrown by `verify()` to reject a signature route with a specific status +
+ *  JSON body. Any other throw from `verify()` is mapped to 401
+ *  `extra_route_signature_invalid` by the buildServer wrapper. */
+export class ExtraRouteRejection extends Error {
+  readonly status: ExtraRouteRejectionStatus;
+  readonly body: unknown;
+
+  constructor(status: ExtraRouteRejectionStatus, body: unknown, message?: string) {
+    super(message ?? `extra route rejected with status ${status}`);
+    this.name = "ExtraRouteRejection";
+    this.status = status;
+    this.body = body;
+  }
+}

package/src/api/index.ts

@@ -28,6 +28,21 @@ export {
   createInMemoryLoginRateLimiter,
   createRedisLoginRateLimiter,
 } from "./auth-routes";
+export type {
+  AnonymousExtraRoute,
+  AnonymousExtraRouteDeps,
+  ExtraRouteDefinition,
+  ExtraRouteEntry,
+  ExtraRouteRejectionStatus,
+  SignatureExtraRoute,
+  SignatureExtraRouteDeps,
+  SignatureExtraRouteVerifyDeps,
+  SignatureExtraRouteVerifyRequest,
+  SystemDispatchArgs,
+  UserExtraRoute,
+  UserExtraRouteDeps,
+} from "./extra-route";
+export { ExtraRouteEntries, ExtraRouteRejection, signatureRoute } from "./extra-route";
 export type { CachedResponseInit, CachePolicy } from "./http-cache";
 export {
   cacheControlHeader,
@@ -50,7 +65,7 @@ export {
 } from "./request-id-middleware";
 export { createApiRoutes } from "./routes";
 export type { KumikoServer, ServerOptions } from "./server";
-export { buildServer } from "./server";
+export { buildServer, makeDispatchSystemQuery, makeDispatchSystemWrite } from "./server";
 export type { SseBroker, SseClient, SseEvent } from "./sse-broker";
 export { createSseBroker } from "./sse-broker";
 export { createSseRoute, SSE_HEARTBEAT_INTERVAL_MS } from "./sse-route";

package/src/api/server.ts

@@ -1,10 +1,19 @@
 import { Hono } from "hono";
+import { ROLES } from "../auth/roles";
 import type { DbConnection, PgClient } from "../db/connection";
 import { createDerivativesContext } from "../derivatives/derivatives-context";
 import { EXT_FILE_PROVIDER, EXT_PRINCIPAL_STATUS } from "../engine/extension-names";
 import { runsInLane } from "../engine/run-in";
-import { createAnonymousUser } from "../engine/system-user";
-import { type AppContext, isFileField, type Registry, type RunIn } from "../engine/types";
+import { ANONYMOUS_ROLE, createAnonymousUser, createSystemUser } from "../engine/system-user";
+import {
+  type AppContext,
+  type HttpRouteMethod,
+  isFileField,
+  type Registry,
+  type RunIn,
+  type TenantId,
+  type WriteResult,
+} from "../engine/types";
 import { createFileContext } from "../files/file-handle";
 import type { FileRoutesOptions } from "../files/file-routes";
 import { createFileRoutes } from "../files/file-routes";
@@ -52,6 +61,13 @@ import {
 } from "./auth-middleware";
 import { type AuthRoutesConfig, createAuthRoutes } from "./auth-routes";
 import { csrfMiddleware } from "./csrf-middleware";
+import {
+  type ExtraRouteDefinition,
+  ExtraRouteEntries,
+  type ExtraRouteEntry,
+  ExtraRouteRejection,
+  type SystemDispatchArgs,
+} from "./extra-route";
 import { createJwtHelper, type JwtHelper, type JwtKeyring } from "./jwt";
 import { observabilityMiddleware } from "./observability-middleware";
 import { assertOriginGuardConfig, originMiddleware } from "./origin-middleware";
@@ -219,6 +235,13 @@ export type ServerOptions = {
   // (defaultTenantId only); run{Prod,Dev}App merge auth-foundation tenant
   // providers into AnonymousAccessResolved before calling buildServer.
   anonymousAccess?: AnonymousAccessResolved;
+  // Declarative HTTP routes outside the /api/write|query|batch pipeline that
+  // still need the framework's dispatcher (webhooks, OAuth callbacks, admin
+  // escape-hatches). Each entry declares its access tier (`entry`) up
+  // front — buildServer wires the matching guard + deps, no handler gets a
+  // raw db/redis. Mounted right after the r.httpRoute loop, before
+  // registerVersionRoute (kumiko-framework#3050).
+  extraRoutes?: readonly ExtraRouteDefinition[];
 };
 
 export type KumikoServer = {
@@ -606,6 +629,13 @@ export function buildServer(options: ServerOptions): KumikoServer {
 
   const app = new Hono();
 
+  // Only entry:"signature" bypasses jwtGuard (verify() authenticates
+  // itself); entry:"anonymous" still needs the anonymousAccess fallthrough
+  // (tenant-by-host), entry:"user" needs c.get("user") populated.
+  const extraRoutePublicMatchers = compileExtraRoutePublicMatchers(options.extraRoutes);
+  const isExtraRoutePublicPath = (c: import("hono").Context): boolean =>
+    extraRoutePublicMatchers.some((m) => m.method === c.req.method && m.pattern.test(c.req.path));
+
   const sensitiveConfig = mergeSensitiveConfig(
     options.observabilityOptions?.sensitiveFilter ?? DEFAULT_SENSITIVE_CONFIG,
   );
@@ -689,7 +719,7 @@ export function buildServer(options: ServerOptions): KumikoServer {
     ...(options.anonymousAccess ? { anonymousAccess: options.anonymousAccess } : {}),
   });
   app.use("/api/*", async (c, next) => {
-    if (PUBLIC_API_PATHS.has(c.req.path)) return next();
+    if (PUBLIC_API_PATHS.has(c.req.path) || isExtraRoutePublicPath(c)) return next();
     return jwtGuard(c, next);
   });
 
@@ -701,7 +731,7 @@ export function buildServer(options: ServerOptions): KumikoServer {
   const patRateLimiter = options.auth?.patRateLimiter;
   if (patRateLimiter) {
     app.use("/api/*", async (c, next) => {
-      if (PUBLIC_API_PATHS.has(c.req.path)) return next();
+      if (PUBLIC_API_PATHS.has(c.req.path) || isExtraRoutePublicPath(c)) return next();
       const pat = getUser(c)?.pat;
       if (pat && !(await patRateLimiter.check(pat.tokenId))) {
         return c.json(
@@ -733,7 +763,7 @@ export function buildServer(options: ServerOptions): KumikoServer {
   if (allowedOrigins && allowedOrigins.length > 0) {
     const originGuard = originMiddleware(allowedOrigins);
     app.use("/api/*", async (c, next) => {
-      if (PUBLIC_API_PATHS.has(c.req.path)) return next();
+      if (PUBLIC_API_PATHS.has(c.req.path) || isExtraRoutePublicPath(c)) return next();
       return originGuard(c, next);
     });
   }
@@ -747,7 +777,7 @@ export function buildServer(options: ServerOptions): KumikoServer {
   // are covered uniformly.
   const csrfGuard = csrfMiddleware();
   app.use("/api/*", async (c, next) => {
-    if (PUBLIC_API_PATHS.has(c.req.path)) return next();
+    if (PUBLIC_API_PATHS.has(c.req.path) || isExtraRoutePublicPath(c)) return next();
     return csrfGuard(c, next);
   });
 
@@ -815,55 +845,74 @@ export function buildServer(options: ServerOptions): KumikoServer {
       const honoHandler = async (c: import("hono").Context): Promise<Response> =>
         route.handler(c, {
           app,
-          systemQuery: (type, payload, tenantId) =>
-            // createAnonymousUser, NOT createSystemUser: httpRoute handlers
-            // using systemQuery are, by construction, `anonymous: true`
-            // public routes — the synthesized user must clear the SAME
-            // access gate a real anonymous visitor would, no more. The
-            // system role would ALSO satisfy that gate here, but it can
-            // read fields gated to "system" that "anonymous" can't
-            // (filterReadFields is a plain role-in-map check) — a future
-            // systemQuery caller reading a system-gated field would leak
-            // it into a public response. The forced tenant already comes
-            // from bypassing the HTTP layer entirely; no elevated role
-            // is needed or wanted on top of that.
-            //
-            // httpRoute handlers run OUTSIDE /api/* — requestIdMiddleware
-            // (which wraps requestContext.run with ip/requestId/
-            // correlationId) never sees this request. Without this wrap,
-            // `rateLimit: {per: "ip", ...}` on a handler invoked via
-            // systemQuery is silent dead-code: enforceRateLimit reads
-            // requestContext.get()?.ip, which is undefined here, so
-            // buildBucketKey always returns {kind: "skip"}.
-            requestContext.run(requestContext.get() ?? buildRequestContextData(c), () =>
-              dispatcher.query(type, payload, createAnonymousUser(tenantId)),
-            ),
+          // createAnonymousUser, NOT createSystemUser: httpRoute handlers
+          // using systemQuery are, by construction, `anonymous: true`
+          // public routes — the synthesized user must clear the SAME
+          // access gate a real anonymous visitor would, no more. The
+          // system role would ALSO satisfy that gate here, but it can
+          // read fields gated to "system" that "anonymous" can't
+          // (filterReadFields is a plain role-in-map check) — a future
+          // systemQuery caller reading a system-gated field would leak
+          // it into a public response. The forced tenant already comes
+          // from bypassing the HTTP layer entirely; no elevated role
+          // is needed or wanted on top of that.
+          systemQuery: makeSystemQuery(c, dispatcher),
         });
-      switch (route.method) {
-        case "GET":
-          app.get(route.path, honoHandler);
-          break;
-        case "POST":
-          app.post(route.path, honoHandler);
-          break;
-        case "PUT":
-          app.put(route.path, honoHandler);
-          break;
-        case "PATCH":
-          app.patch(route.path, honoHandler);
-          break;
-        case "DELETE":
-          app.delete(route.path, honoHandler);
-          break;
-        case "OPTIONS":
-        case "HEAD":
-          // Hono-on() für die Methoden ohne Convenience-Method.
-          app.on(route.method, route.path, honoHandler);
-          break;
-        default:
-          assertUnreachable(route.method, "http method");
+      mountHonoRoute(app, route.method, route.path, honoHandler);
+    }
+  }
+
+  // extraRoutes (kumiko-framework#3050) — declarative HTTP-routes with a
+  // Pflicht `entry` tier. Mounted after r.httpRoute for the same reason: an
+  // extraRoute dispatching through `dispatcher` builds Hono's matcher, so
+  // this must run before any seed that also dispatches (runProdApp/
+  // createKumikoServer call buildServer before seeding).
+  if (options.extraRoutes) {
+    // Boot-time validation for the whole list BEFORE mounting anything —
+    // an app with one bad route should fail loud at boot, not mount N-1
+    // routes and then throw on route N.
+    for (const route of options.extraRoutes) {
+      if (!isKnownExtraRouteEntry(route.entry)) {
+        throw new Error(
+          `[kumiko] extraRoutes: unknown entry "${String(route.entry)}" on ` +
+            `"${route.method} ${route.path}" — expected "anonymous" | "user" | "signature". ` +
+            "A JS caller without the ExtraRouteDefinition type can hit this at boot.",
+        );
+      }
+      if (route.entry === ExtraRouteEntries.user && !route.path.startsWith("/api/")) {
+        throw new Error(
+          `[kumiko] extraRoutes: entry:"user" route "${route.method} ${route.path}" must be ` +
+            "mounted under \"/api/\" — that's the only path prefix that rides the framework's " +
+            "jwtGuard chain, which is what populates deps.user.",
+        );
+      }
+      // A signature route under /api/ skips jwtGuard/origin/csrf for every
+      // path its pattern matches — a wildcard would switch off auth for
+      // unrelated /api/* handlers (e.g. "/api/*" swallows /api/write).
+      if (
+        route.entry === ExtraRouteEntries.signature &&
+        route.path.startsWith("/api/") &&
+        route.path.includes("*")
+      ) {
+        throw new Error(
+          `[kumiko] extraRoutes: entry:"signature" route "${route.method} ${route.path}" must not ` +
+            'use a wildcard under "/api/" — it would bypass the auth chain for every matching path.',
+        );
       }
     }
+    const dispatchSystemWrite = makeDispatchSystemWrite(dispatcher);
+    const dispatchSystemQuery = makeDispatchSystemQuery(dispatcher);
+    for (const route of options.extraRoutes) {
+      const honoHandler = buildExtraRouteHonoHandler(route, {
+        app,
+        dispatcher,
+        registry: options.registry,
+        secrets: contextWithObservability.secrets,
+        dispatchSystemWrite,
+        dispatchSystemQuery,
+      });
+      mountHonoRoute(app, route.method, route.path, honoHandler);
+    }
   }
 
   // /version-Default registriert NACH feature-routes — Hono "first match
@@ -900,6 +949,222 @@ export function buildServer(options: ServerOptions): KumikoServer {
   };
 }
 
+// Method-switch shared by r.httpRoute and extraRoutes — one place to keep
+// the two mounting paths from drifting on which Hono methods get a
+// convenience-call vs. app.on().
+function mountHonoRoute(
+  app: Hono,
+  method: HttpRouteMethod,
+  path: string,
+  // biome-ignore lint/suspicious/noExplicitAny: Hono context generics are invisible at the framework boundary
+  handler: (c: import("hono").Context<any, any>) => Response | Promise<Response>,
+): void {
+  switch (method) {
+    case "GET":
+      app.get(path, handler);
+      break;
+    case "POST":
+      app.post(path, handler);
+      break;
+    case "PUT":
+      app.put(path, handler);
+      break;
+    case "PATCH":
+      app.patch(path, handler);
+      break;
+    case "DELETE":
+      app.delete(path, handler);
+      break;
+    case "OPTIONS":
+    case "HEAD":
+      // Hono's on() for the methods without a convenience method.
+      app.on(method, path, handler);
+      break;
+    default:
+      assertUnreachable(method, "http method");
+  }
+}
+
+// Shared systemQuery builder for r.httpRoute and extraRoutes (anonymous +
+// signature entries). requestContext.run must wrap the dispatcher call —
+// both route kinds run outside the requestIdMiddleware chain that normally
+// populates it, and `rateLimit: {per: "ip", ...}` on a handler invoked
+// through systemQuery is otherwise silent dead-code (enforceRateLimit reads
+// requestContext.get()?.ip, undefined without this wrap).
+function makeSystemQuery(
+  // biome-ignore lint/suspicious/noExplicitAny: Hono context generics are invisible at the framework boundary
+  c: import("hono").Context<any, any>,
+  dispatcher: Dispatcher,
+): (type: string, payload: unknown, tenantId: TenantId) => Promise<unknown> {
+  return (type, payload, tenantId) =>
+    requestContext.run(requestContext.get() ?? buildRequestContextData(c), () =>
+      dispatcher.query(type, payload, createAnonymousUser(tenantId)),
+    );
+}
+
+// SystemAdmin write/query builders shared by buildServer's `extraRoutes`
+// mount and server-runtime's `wire` hook (runProdApp/createKumikoServer,
+// after buildServer). Privilege-scope: SystemAdmin is the highest
+// non-tenant-scoped role — reaches ANY SystemAdmin-gated handler on ANY
+// tenant. Only safe for callers that already proved their own authenticity
+// (signature verify(), HMAC state, ...), never exposed to a raw request.
+export function makeDispatchSystemWrite(
+  dispatcher: Dispatcher,
+): (args: SystemDispatchArgs) => Promise<WriteResult> {
+  return ({ handlerQn, payload, tenantId }) =>
+    dispatcher.write(handlerQn, payload, createSystemUser(tenantId, [ROLES.SystemAdmin]));
+}
+
+export function makeDispatchSystemQuery(
+  dispatcher: Dispatcher,
+): (args: SystemDispatchArgs) => Promise<unknown> {
+  return ({ handlerQn, payload, tenantId }) =>
+    dispatcher.query(handlerQn, payload, createSystemUser(tenantId, [ROLES.SystemAdmin]));
+}
+
+// Same dispatcher.write(...) as entry:"user", but the user is getUser(c) —
+// see AnonymousExtraRouteDeps.write for the privilege/tenant contract.
+function makeAnonymousWrite(
+  // biome-ignore lint/suspicious/noExplicitAny: Hono context generics are invisible at the framework boundary
+  c: import("hono").Context<any, any>,
+  dispatcher: Dispatcher,
+): (type: string, payload: unknown) => Promise<WriteResult> {
+  return (type, payload) => {
+    const user = getUser(c);
+    if (!user) {
+      throw new Error(
+        '[kumiko] extraRoutes: entry:"anonymous" deps.write requires this route to be mounted ' +
+          'under "/api/" with anonymousAccess wired — no request-resolved session user was found.',
+      );
+    }
+    return dispatcher.write(type, payload, user);
+  };
+}
+
+function isKnownExtraRouteEntry(entry: unknown): entry is ExtraRouteEntry {
+  return (
+    entry === ExtraRouteEntries.anonymous ||
+    entry === ExtraRouteEntries.user ||
+    entry === ExtraRouteEntries.signature
+  );
+}
+
+// Hono path pattern ("/api/foo/:bar", "/api/foo/*") → RegExp. Only the
+// subset extraRoutes actually uses (static segments, `:param`, trailing
+// `*`) — no inline `:param{regex}` constraints, no optional `:param?`.
+function honoPathToRegex(path: string): RegExp {
+  const segments = path
+    .split("/")
+    .map((segment) => {
+      if (segment.startsWith(":")) return "[^/]+";
+      if (segment === "*") return ".*";
+      return segment.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    })
+    .join("/");
+  return new RegExp(`^${segments}$`);
+}
+
+type ExtraRoutePublicMatcher = { readonly method: string; readonly pattern: RegExp };
+
+// See the bypass comment at the jwtGuard mount above — only signature
+// routes are public here.
+function compileExtraRoutePublicMatchers(
+  extraRoutes: readonly ExtraRouteDefinition[] | undefined,
+): readonly ExtraRoutePublicMatcher[] {
+  if (!extraRoutes) return [];
+  return extraRoutes
+    .filter((route) => route.entry === ExtraRouteEntries.signature)
+    .map((route) => ({ method: route.method, pattern: honoPathToRegex(route.path) }));
+}
+
+type ExtraRouteHonoHandlerDeps = {
+  readonly app: Hono;
+  readonly dispatcher: Dispatcher;
+  readonly registry: Registry;
+  readonly secrets: import("../secrets").SecretsContext | undefined;
+  readonly dispatchSystemWrite: (args: SystemDispatchArgs) => Promise<WriteResult>;
+  readonly dispatchSystemQuery: (args: SystemDispatchArgs) => Promise<unknown>;
+};
+
+function buildExtraRouteHonoHandler(
+  route: ExtraRouteDefinition,
+  shared: ExtraRouteHonoHandlerDeps,
+  // biome-ignore lint/suspicious/noExplicitAny: Hono context generics are invisible at the framework boundary
+): (c: import("hono").Context<any, any>) => Promise<Response> {
+  switch (route.entry) {
+    case ExtraRouteEntries.anonymous:
+      return async (c) =>
+        route.handler(c, {
+          app: shared.app,
+          registry: shared.registry,
+          systemQuery: makeSystemQuery(c, shared.dispatcher),
+          write: makeAnonymousWrite(c, shared.dispatcher),
+        });
+    case ExtraRouteEntries.user:
+      return async (c) => {
+        const user = getUser(c);
+        if (!user || user.roles.includes(ANONYMOUS_ROLE)) {
+          return c.json(
+            {
+              error: {
+                code: "unauthenticated",
+                httpStatus: 401,
+                message: "this route requires a signed-in user",
+                i18nKey: "auth.errors.missingToken",
+              },
+            },
+            401,
+          );
+        }
+        return route.handler(c, {
+          app: shared.app,
+          registry: shared.registry,
+          user,
+          query: (type, payload) => shared.dispatcher.query(type, payload, user),
+          write: (type, payload) => shared.dispatcher.write(type, payload, user),
+        });
+      };
+    case ExtraRouteEntries.signature:
+      return async (c) => {
+        const rawBody = await c.req.text();
+        const headers: Record<string, string> = {};
+        c.req.raw.headers.forEach((value, key) => {
+          headers[key.toLowerCase()] = value;
+        });
+        let verified: unknown;
+        try {
+          verified = await route.verify(
+            { rawBody, headers, params: c.req.param(), query: c.req.query() },
+            { registry: shared.registry, secrets: shared.secrets },
+          );
+        } catch (e) {
+          if (e instanceof ExtraRouteRejection) {
+            return c.json(e.body, e.status);
+          }
+          return c.json(
+            {
+              error: {
+                code: "extra_route_signature_invalid",
+                message: e instanceof Error ? e.message : String(e),
+              },
+            },
+            401,
+          );
+        }
+        return route.handler(c, verified, {
+          app: shared.app,
+          registry: shared.registry,
+          secrets: shared.secrets,
+          systemQuery: makeSystemQuery(c, shared.dispatcher),
+          dispatchSystemWrite: shared.dispatchSystemWrite,
+          dispatchSystemQuery: shared.dispatchSystemQuery,
+        });
+      };
+    default:
+      return assertUnreachable(route, "extra route entry");
+  }
+}
+
 function deriveTenantLifecycleResolver(
   registry: Registry,
   db: DbConnection | undefined,

package/src/changes.json

@@ -1,4 +1,15 @@
 [
+  {
+    "version": "0.298.0",
+    "type": "improvement",
+    "title": "Anonymous extraRoutes get `write`, running as the session the /api chain resolved for this request (never more than that caller could do via /api/write, request-resolved tenant, /api/ only)."
+  },
+  {
+    "version": "0.298.0",
+    "type": "breaking",
+    "title": "extraRoutes/hostDispatch move to structured route and wire definitions",
+    "migration": "extraRoutes on runProdApp/createKumikoServer/runDevApp/setupTestStack changes from (app, deps) => void to readonly ExtraRouteDefinition[]. Each entry is { method, path, entry: \"anonymous\" | \"user\" | \"signature\", handler }, built via the helpers in @cosmicdrift/kumiko-framework/api; a signature route also needs verify(request, deps) via signatureRoute<T>(). An anonymous GET route that used to call app.get(path, handler) on the raw app now receives { app, registry, systemQuery } - replace direct db/redis reads with systemQuery. A route reading user data via a raw db handle now declares entry: \"user\" (path must live under /api/, unauthenticated requests get 401 automatically) and receives { app, registry, user, query, write } instead of db/redis. A route verifying an external signature (webhooks) declares entry: \"signature\" and receives { app, registry, secrets?, systemQuery, dispatchSystemWrite, dispatchSystemQuery }; reject invalid signatures with ExtraRouteRejection(status, body) from verify. Non-route setup that used to run inside the old extraRoutes(app, deps) callback (late-binding, background seeds, starting a runner) moves to the new wire?: (deps: SystemWireDeps) => void | Promise<void> option on runProdApp/createKumikoServer, which gets { db, redis, registry, dispatchSystemWrite } but no app. hostDispatch (dev) and HostDispatchFn (runProdApp) gain a second argument { systemQuery }; an app.use middleware that read db directly for host dispatch now uses systemQuery instead."
+  },
   {
     "version": "0.296.0",
     "type": "breaking",

package/src/engine/system-user.ts

@@ -5,11 +5,11 @@ export { SYSTEM_USER_ID };
 
 export const SYSTEM_ROLE = "system" as const;
 
-// extraRoles: hasAccess kennt keinen System-Bypass — Handler gaten auf
-// explizite Rollen. Caller, die Handler mit z.B. SystemAdmin-Gate erreichen
-// müssen (extraRoutes.dispatchSystemWrite → billing-foundation
-// process-event), geben die Rolle hier zusätzlich mit; createdBy bleibt
-// SYSTEM_USER_ID, der Audit-Trail zeigt weiterhin System.
+// extraRoles: hasAccess has no system bypass — handlers gate on
+// explicit roles. Callers that must reach handlers gated e.g. on
+// SystemAdmin (dispatchSystemWrite on entry:"signature" routes or the
+// `wire` hook → billing-foundation process-event) pass the role here
+// additionally; createdBy stays SYSTEM_USER_ID, the audit trail still shows System.
 export function createSystemUser(
   tenantId: TenantId,
   extraRoles: readonly string[] = [],

package/src/entrypoint/index.ts

@@ -87,6 +87,7 @@ export type ApiEntrypointOptions = BaseEntrypointOptions & {
   readonly maxRequestBytes?: ServerOptions["maxRequestBytes"];
   readonly readiness?: ServerOptions["readiness"];
   readonly metrics?: ServerOptions["metrics"];
+  readonly extraRoutes?: ServerOptions["extraRoutes"];
   // Job-enqueue surface for the API process. Required whenever the registry
   // defines event-triggered jobs: command-dispatcher fires handleEvent as
   // an afterCommit-hook — without a jobRunner the enqueue silently drops.
@@ -236,6 +237,7 @@ function buildApiServer(
     maxRequestBytes: opts.maxRequestBytes,
     readiness: opts.readiness,
     metrics: opts.metrics,
+    extraRoutes: opts.extraRoutes,
     observability: opts.observability,
     observabilityOptions: opts.observabilityOptions,
     dispatcherOptions,

package/src/stack/test-stack.ts

@@ -42,8 +42,9 @@ export type TestStack = {
   // to assert a consumer pushed an invalidation without opening a real SSE
   // connection.
   sseBroker: SseBroker;
-  // Command-dispatcher behind the HTTP routes — for direct system-writes
-  // in tests and dev-server extraRoutes (provider-webhook wiring).
+  // Command-dispatcher behind the HTTP routes — for direct system-writes in
+  // tests and behind entry:"signature" extraRoutes / the `wire` hook
+  // (provider-webhook wiring).
   dispatcher: Dispatcher;
   // The AppContext buildServer handed the request path, incl. the fields it
   // wires itself (_fileProviderResolver). A dev-server that starts its own
@@ -105,6 +106,10 @@ export type TestStackOptions = {
    *  The resolver is auto-built from the test Redis. Mirrors
    *  buildServer's `rateLimit` option 1:1 — see there for shape. */
   rateLimit?: import("../api/server").ServerOptions["rateLimit"];
+  /** Forwarded to buildServer — Integration-Tests that exercise `extraRoutes`
+   *  MUST go through here (real HTTP via `stack.http`/`stack.app.fetch`),
+   *  never `createTestDispatcher`. */
+  extraRoutes?: import("../api/server").ServerOptions["extraRoutes"];
   /** Inject a MasterKeyProvider for secrets-backed tests. Lands typed in
    *  AppContext — set/delete/get + rotation job pick it up. Omit for
    *  suites that don't touch secrets. */
@@ -404,6 +409,7 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
       },
       eventDedup,
       sseBroker,
+      ...(options.extraRoutes && { extraRoutes: options.extraRoutes }),
       // Tests drive the dispatcher via stack.eventDispatcher.runOnce() for
       // deterministic drains — no timer-induced flakiness. pollIntervalMs
       // stays short anyway in case a test opts into `.start()`. pgClient