@cosmicdrift/kumiko-framework 0.297.0 → 0.304.0

package/src/api/server.ts

@@ -1,10 +1,19 @@
-import { Hono } from "hono";
+import { Hono, type MiddlewareHandler } 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";
@@ -50,8 +59,15 @@ import {
   getUser,
   type TenantLifecycleStatusResolver,
 } from "./auth-middleware";
-import { type AuthRoutesConfig, createAuthRoutes } from "./auth-routes";
+import { type AuthRoutesConfig, createAuthRoutes, type LoginRateLimiter } 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,34 +719,28 @@ 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);
   });
 
+  // Without anonymousAccess a missing token 401s instead of falling through as anonymous.
+  const sessionOnlyGuard = authMiddleware(jwt, {
+    ...(options.auth?.sessionChecker ? { sessionChecker: options.auth.sessionChecker } : {}),
+    ...(options.auth?.tokenVerifier ? { tokenVerifier: options.auth.tokenVerifier } : {}),
+    ...(tenantLifecycleResolver ? { resolveTenantLifecycleStatus: tenantLifecycleResolver } : {}),
+  });
+
   // PAT rate limiting — runs AFTER the auth guard so the resolved principal is
   // available. Only PAT-authenticated requests are counted (keyed by token id);
   // cookie/JWT users pass through untouched. In-memory limiter is per-instance
   // (see run-prod-app) — a multi-node deployment wanting a shared counter swaps
   // in a Redis-backed LoginRateLimiter.
   const patRateLimiter = options.auth?.patRateLimiter;
-  if (patRateLimiter) {
+  const patRateLimitGuard = patRateLimiter ? buildPatRateLimitGuard(patRateLimiter) : undefined;
+  if (patRateLimitGuard) {
     app.use("/api/*", async (c, next) => {
-      if (PUBLIC_API_PATHS.has(c.req.path)) return next();
-      const pat = getUser(c)?.pat;
-      if (pat && !(await patRateLimiter.check(pat.tokenId))) {
-        return c.json(
-          {
-            error: {
-              code: "pat_rate_limited",
-              httpStatus: 429,
-              message: "personal access token rate limit exceeded",
-              i18nKey: "auth.errors.patRateLimited",
-            },
-          },
-          429,
-        );
-      }
-      return next();
+      if (PUBLIC_API_PATHS.has(c.req.path) || isExtraRoutePublicPath(c)) return next();
+      return patRateLimitGuard(c, next);
     });
   }
 
@@ -730,10 +754,11 @@ export function buildServer(options: ServerOptions): KumikoServer {
   // unguarded-subdomain-XSS footgun, not a warn-and-continue case.
   assertOriginGuardConfig(options.auth);
   const allowedOrigins = options.auth?.allowedOrigins;
-  if (allowedOrigins && allowedOrigins.length > 0) {
-    const originGuard = originMiddleware(allowedOrigins);
+  const originGuard =
+    allowedOrigins && allowedOrigins.length > 0 ? originMiddleware(allowedOrigins) : undefined;
+  if (originGuard) {
     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,10 +772,18 @@ 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);
   });
 
+  // Same order as /api/* above: auth → PAT → origin → CSRF.
+  const sessionOnlyHttpRouteGuards: readonly MiddlewareHandler[] = [
+    sessionOnlyGuard,
+    ...(patRateLimitGuard ? [patRateLimitGuard] : []),
+    ...(originGuard ? [originGuard] : []),
+    csrfGuard,
+  ];
+
   // Public auth routes (login) need to be registered BEFORE the generic
   // api routes so Hono matches them first.
   if (options.auth) {
@@ -815,55 +848,79 @@ 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: systemQuery's
+          // synthesized user must clear the SAME access gate a real
+          // anonymous visitor would, no more — regardless of the route's
+          // own `anonymous` mode. 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 systemQuery caller reading a system-gated field
+          // would leak it into the 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,
+        route.anonymous ? [] : sessionOnlyHttpRouteGuards,
+      );
+    }
+  }
+
+  // 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 +957,253 @@ 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>,
+  middlewares: readonly MiddlewareHandler[] = [],
+): void {
+  // Guards go into the route's own handler chain, never a method-gated
+  // app.use: Hono serves HEAD through the GET route with c.req.method still
+  // "HEAD", so a `method === c.req.method` gate would skip them for HEAD.
+  if (middlewares.length > 0) {
+    // [path]: only Hono's array-path overload accepts a variable-length handler spread.
+    app.on(method, [path], ...middlewares, handler);
+    // skip: guarded route already mounted with its guard chain
+    return;
+  }
+  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");
+  }
+}
+
+// Must run after the auth guard so getUser(c) carries the PAT.
+function buildPatRateLimitGuard(patRateLimiter: LoginRateLimiter): MiddlewareHandler {
+  return async (c, next) => {
+    const pat = getUser(c)?.pat;
+    if (pat && !(await patRateLimiter.check(pat.tokenId))) {
+      return c.json(
+        {
+          error: {
+            code: "pat_rate_limited",
+            httpStatus: 429,
+            message: "personal access token rate limit exceeded",
+            i18nKey: "auth.errors.patRateLimited",
+          },
+        },
+        429,
+      );
+    }
+    return next();
+  };
+}
+
+// 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,41 @@
 [
+  {
+    "version": "0.303.0",
+    "type": "breaking",
+    "title": "r.httpRoute's `anonymous` field is now required and controls the mount, not just docs (fw#2885)",
+    "detail": "HttpRouteDefinition.anonymous changes from an optional, purely-documentary boolean to a required one that drives buildServer's mount. `anonymous: true` stays public, unchanged. `anonymous: false` now mounts the route behind the same session-auth chain /api/* uses: no anonymous fallthrough (a request without a session gets 401, never a synthesized anonymous user), the same PAT rate-limit guard, origin-allowlist guard and double-submit CSRF guard as /api/*, in the same order (auth → PAT → origin → CSRF). The handler reads the caller via getUser(c). feature-ui-extensions' httpRoute() now throws at feature-setup time when `anonymous` is missing or not a boolean (catches JS callers without the TypeScript type). The feature-AST (patterns/render/patcher/extractor/pattern-library) mirrors the field as required; a source file parsed before this change (missing `anonymous`) reads as `anonymous: false` — the safe side — and round-trip rendering always emits the field explicitly.",
+    "migration": "Every r.httpRoute({...}) call site must declare anonymous: true | false. Routes that were implicitly public (no field, or anonymous: true) keep working unchanged once anonymous: true is added explicitly — feature-ui-extensions now throws at boot for a route missing the field. Routes meant to require a session must set anonymous: false; a request without a session then gets 401 instead of running (there is no anonymous fallthrough on those routes any more), and a cookie-authenticated state-changing request needs the same X-CSRF-Token as /api/* or gets 403. Feature-AST round-trips: a saved feature file that predates this change parses `anonymous` as false (not true) — audit any httpRoute that was implicitly public and add `anonymous: true` before re-saving through the Designer/AI editor, or the next render will lock it behind the session-auth chain."
+  },
+  {
+    "version": "0.302.0",
+    "type": "breaking",
+    "title": "Anonymous write handlers whose input accepts a personal-data field must declare access.personalData: \"public-intake\" (fw#2885)",
+    "detail": "RoleAccessRule ({ roles, personalData? }) gains an optional personalData?: RoleAccessPersonalData (currently only \"public-intake\"), exported from @cosmicdrift/kumiko-framework/engine and /ui-types alongside OpenToAllPersonalData. validateAccessDeclarations now requires personalData: \"public-intake\" on a write handler whose access.roles includes \"anonymous\" and whose input schema accepts a personal-data field (pii / userOwned / recordOwned) of an entity in the same feature; declaring personalData on the roles form of a query or stream handler is rejected, \"public-intake\" on roles without \"anonymous\" is rejected, and \"tenant-members\" on the roles form is rejected (openToAll keeps accepting only \"tenant-members\"). Unlike the existing openToAll owner-binding exemption, an anonymous handler is never exempted by an owner-bound access.write map: every anonymous caller shares one user.id (\"anonymous\"), so from(\"user:id\", ...) binds no one specific. The feature-AST extractor (readOptionalAccessRule) reads roles.personalData the same way it already reads openToAll.personalData.",
+    "migration": "A write handler with \"anonymous\" in access.roles whose input schema accepts a personal-data field of an entity in the same feature now fails boot until it declares access: { roles: [..., \"anonymous\"], personalData: \"public-intake\" }. Owner-binding via from(\"user:id\", \"<column>\") on the entity access.write does not exempt an anonymous handler (it does exempt an openToAll handler) — anonymous requests share a single caller identity, so rely on the handler's required rateLimit (per ip) instead. personalData: \"public-intake\" is only valid on the roles form and only with \"anonymous\" in roles; openToAll keeps accepting only personalData: \"tenant-members\". The check only sees entities of the handler's own feature; anonymous intake into another feature's entity is covered by the follow-up runtime gate (kumiko-framework#3165). No known bundled-feature handler is affected."
+  },
+  {
+    "version": "0.301.0",
+    "type": "improvement",
+    "title": "Add shared /metrics wiring: prometheusMetricsEnvSchema and resolveObservabilityWiring under @cosmicdrift/kumiko-framework/observability",
+    "detail": "Apps that expose a Prometheus /metrics endpoint no longer need to hand-roll the fail-closed wiring. Compose prometheusMetricsEnvSchema.shape into your app's env extend block (extend: appSchema.extend(prometheusMetricsEnvSchema.shape)) and spread resolveObservabilityWiring(env.PROMETHEUS_METRICS_TOKEN) into runProdApp. Without a token the endpoint stays off; publicstatus can now drop its local copy of this wiring (publicstatus#479)."
+  },
+  {
+    "version": "0.300.0",
+    "type": "breaking",
+    "title": "Remove the guest-identity all-role: unauthenticated handlers must declare roles: [\"anonymous\"] with a rateLimit",
+    "migration": "Handlers declared with access: { roles: [\"all\"] } now fail boot — no session ever carries the role \"all\", so this is unreachable dead config, not a wildcard. Switch to access: { roles: [\"anonymous\"] } plus rateLimit: { per: \"ip\" | \"ip+handler\", limit: N, windowSeconds: N } for unauthenticated callers, or access: { openToAll: { reason: \"...\" } } for any signed-in user. Test fixtures that hand-roll a SessionUser with roles: [\"all\"] (bridgeStub, hand-rolled guest literals) must switch to createAnonymousUser(tenantId) or roles: [\"anonymous\"]. buildSessionRoles now also strips \"anonymous\" and \"all\" out of globalRoles at every JWT mint (membership roles were already stripped). auth-routes.ts now dispatches every public /auth/* write with createAnonymousUser(SYSTEM_TENANT_ID) instead of the removed GUEST_USER constant."
+  },
+  {
+    "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/__tests__/http-route-anonymous-required.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, test } from "bun:test";
+import { defineFeature } from "../define-feature";
+
+describe("r.httpRoute — anonymous is required", () => {
+  test("missing anonymous → throws (JS caller without HttpRouteDefinition's type)", () => {
+    expect(() =>
+      defineFeature("feed", (r) => {
+        r.httpRoute({
+          method: "GET",
+          path: "/feed.xml",
+          handler: async () => new Response("ok"),
+          // biome-ignore lint/suspicious/noExplicitAny: intentional type violation under test
+        } as any);
+      }),
+    ).toThrow(/must declare anonymous: true \| false/);
+  });
+
+  test("anonymous: true → accepted", () => {
+    expect(() =>
+      defineFeature("feed", (r) => {
+        r.httpRoute({
+          method: "GET",
+          path: "/feed.xml",
+          anonymous: true,
+          handler: async () => new Response("ok"),
+        });
+      }),
+    ).not.toThrow();
+  });
+
+  test("anonymous: false → accepted", () => {
+    expect(() =>
+      defineFeature("feed", (r) => {
+        r.httpRoute({
+          method: "GET",
+          path: "/feed.xml",
+          anonymous: false,
+          handler: async () => new Response("ok"),
+        });
+      }),
+    ).not.toThrow();
+  });
+});

package/src/engine/__tests__/membership-roles.test.ts

@@ -38,10 +38,9 @@ describe("forbidden membership roles", () => {
   });
 });
 
-// The two cases that discriminate the fix at every JWT mint: the strip wraps
-// ONLY the membership portion, never the merged result — so a legitimate
-// SystemAdmin in globalRoles survives, a resurrected one in membership does not.
-describe("merge semantics (globalRoles never filtered)", () => {
+// globalRoles keeps SystemAdmin/system but loses anonymous/all; membershipRoles
+// strips all forbidden roles (SystemAdmin, system, anonymous, all).
+describe("merge semantics (globalRoles: SystemAdmin/system kept, anonymous/all stripped)", () => {
   test("global SystemAdmin survives (no regression for real admins)", () => {
     expect(buildSessionRoles(["SystemAdmin"], [])).toContain("SystemAdmin");
   });
@@ -55,4 +54,14 @@ describe("merge semantics (globalRoles never filtered)", () => {
       ["Admin", "SystemAdmin"].sort(),
     );
   });
+
+  test("anonymous/all in globalRoles are stripped, SystemAdmin stays", () => {
+    expect([...buildSessionRoles(["anonymous", "all", "SystemAdmin"], [])].sort()).toEqual([
+      "SystemAdmin",
+    ]);
+  });
+
+  test("anonymous/all in membershipRoles are stripped too", () => {
+    expect(buildSessionRoles([], ["anonymous", "all", "Admin"])).toEqual(["Admin"]);
+  });
 });