@cosmicdrift/kumiko-framework 0.299.0 → 0.304.0

package/package.json

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

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

@@ -851,6 +851,7 @@ describe("feature-declared HTTP routes (r.httpRoute)", () => {
         r.httpRoute({
           method: "GET",
           path: "/api/forbidden",
+          anonymous: true,
           handler: (c) => c.text("nope"),
         });
       }),
@@ -860,8 +861,8 @@ describe("feature-declared HTTP routes (r.httpRoute)", () => {
   test("Boot-Validator: doppelte method+path-Combo wird abgelehnt", () => {
     expect(() =>
       defineFeature("dup", (r) => {
-        r.httpRoute({ method: "GET", path: "/x", handler: (c) => c.text("a") });
-        r.httpRoute({ method: "GET", path: "/x", handler: (c) => c.text("b") });
+        r.httpRoute({ method: "GET", path: "/x", anonymous: true, handler: (c) => c.text("a") });
+        r.httpRoute({ method: "GET", path: "/x", anonymous: true, handler: (c) => c.text("b") });
       }),
     ).toThrow(/already registered/);
   });

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

@@ -0,0 +1,114 @@
+// kumiko-framework#2885 step 3: `HttpRouteDefinition.anonymous` now controls
+// the mount, not just docs/boot-validation. `anonymous: false` must sit
+// behind the SAME session-auth chain /api/* uses (no anonymous fallthrough,
+// PAT rate limit, origin + CSRF guards) — a request without a session gets
+// 401, never a synthesized anonymous user. `anonymous: true` stays public.
+//
+// anonymousAccess is deliberately wired on the test stack: without it, a
+// wrongly-mounted `anonymous: false` route (using jwtGuard instead of
+// sessionOnlyGuard) would ALSO 401 on a missing token, masking the bug the
+// 401 test exists to catch.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { defineFeature } from "../../engine";
+import type { TenantId } from "../../engine/types/identifiers";
+import { setupTestStack, type TestStack, TestUsers } from "../../stack";
+import { AUTH_COOKIE_NAME, CSRF_COOKIE_NAME, CSRF_HEADER_NAME, getUser } from "../auth-middleware";
+
+const TENANT_ID = "00000000-0000-4000-8000-000000000001" as TenantId;
+
+const entryFeature = defineFeature("http-route-entry", (r) => {
+  r.httpRoute({
+    method: "GET",
+    path: "/entry-public",
+    anonymous: true,
+    handler: async (c) => c.json({ ok: true }),
+  });
+  r.httpRoute({
+    method: "GET",
+    path: "/entry-private",
+    anonymous: false,
+    handler: async (c) => c.json({ id: getUser(c).id }),
+  });
+  r.httpRoute({
+    method: "POST",
+    path: "/entry-private",
+    anonymous: false,
+    handler: async (c) => c.json({ id: getUser(c).id }),
+  });
+});
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [entryFeature],
+    anonymousAccess: { defaultTenantId: TENANT_ID },
+  });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("r.httpRoute anonymous:false — session auth chain", () => {
+  test("GET without a session → 401, no anonymous fallthrough", async () => {
+    const res = await stack.app.request("/entry-private");
+    expect(res.status).toBe(401);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("missing_token");
+  });
+
+  // Hono answers HEAD through the GET route while c.req.method stays "HEAD";
+  // the guard chain must still run for it.
+  test("HEAD without a session → 401, not the GET handler unguarded", async () => {
+    const res = await stack.app.request("/entry-private", { method: "HEAD" });
+    expect(res.status).toBe(401);
+  });
+
+  test("GET with a real session → 200, handler sees the logged-in user, not anonymous", async () => {
+    const token = await stack.jwt.sign(TestUsers.user);
+    const res = await stack.app.request("/entry-private", {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { id: string };
+    expect(body.id).toBe(TestUsers.user.id);
+    expect(body.id).not.toBe("anonymous");
+  });
+
+  test("POST with cookie auth, no CSRF token → 403 csrf_token_mismatch", async () => {
+    const token = await stack.jwt.sign(TestUsers.user);
+    const res = await stack.app.request("/entry-private", {
+      method: "POST",
+      headers: { Cookie: `${AUTH_COOKIE_NAME}=${token}` },
+    });
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("csrf_token_mismatch");
+  });
+
+  test("POST with cookie auth + matching CSRF token → 200", async () => {
+    const token = await stack.jwt.sign(TestUsers.user);
+    const csrf = "csrf-fixed-http-route-entry-token";
+    const res = await stack.app.request("/entry-private", {
+      method: "POST",
+      headers: {
+        Cookie: `${AUTH_COOKIE_NAME}=${token}; ${CSRF_COOKIE_NAME}=${csrf}`,
+        [CSRF_HEADER_NAME]: csrf,
+      },
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { id: string };
+    expect(body.id).toBe(TestUsers.user.id);
+  });
+});
+
+describe("r.httpRoute anonymous:true — stays public", () => {
+  test("GET without a session → 200", async () => {
+    const res = await stack.app.request("/entry-public");
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { ok: boolean };
+    expect(body.ok).toBe(true);
+  });
+});

package/src/api/auth-routes.ts

@@ -5,7 +5,7 @@ import { deleteCookie, setCookie } from "hono/cookie";
 import type Redis from "ioredis";
 import { z } from "zod";
 import { buildSessionRoles } from "../engine/membership-roles";
-import { createSystemUser } from "../engine/system-user";
+import { createAnonymousUser, createSystemUser } from "../engine/system-user";
 import {
   type ActiveMembershipRejection,
   type ActiveMembershipResult,
@@ -197,15 +197,6 @@ type MembershipRow = {
   tenantKey?: string;
 };
 
-// Guest identity used for unauthenticated calls (e.g. login). The "all" role
-// lets framework access checks pass for handlers declared with roles: ["all"].
-// `id` is the zero-uuid so it flows through event-store columns cleanly.
-const GUEST_USER: SessionUser = {
-  id: "00000000-0000-0000-0000-000000000000",
-  tenantId: SYSTEM_TENANT_ID,
-  roles: ["all"],
-};
-
 // Pluggable rate-limiter for POST /auth/login. Returning `false` blocks the
 // request with 429 before the login handler runs — use this to slow down
 // brute-force attempts. The framework ships a default in-memory impl; apps
@@ -780,7 +771,7 @@ export function createAuthRoutes(
         }
       }
 
-      const result = await dispatcher.write(loginQn, body, GUEST_USER);
+      const result = await dispatcher.write(loginQn, body, createAnonymousUser(SYSTEM_TENANT_ID));
 
       if (!result.isSuccess) {
         // Feature-specific auth reason codes arrive via UnprocessableError.details.reason
@@ -845,7 +836,7 @@ export function createAuthRoutes(
   }
 
   // POST /auth/mfa/verify — completes a two-step login. Mirrors /auth/login
-  // structurally (public, GUEST_USER dispatch, mintSessionAndRespond on
+  // structurally (public, anonymous identity dispatch, mintSessionAndRespond on
   // success) but with its OWN rate limiter (mfaVerifyRateLimit) — this route
   // never goes through a dispatcher write-handler's own rateLimit config,
   // so without this it would have NO rate limiting at all. Per-account
@@ -877,7 +868,11 @@ export function createAuthRoutes(
         }
       }
 
-      const result = await dispatcher.write(mfaVerifyQn, body, GUEST_USER);
+      const result = await dispatcher.write(
+        mfaVerifyQn,
+        body,
+        createAnonymousUser(SYSTEM_TENANT_ID),
+      );
 
       if (!result.isSuccess) {
         // @cast-boundary error-details — KumikoError.details shape is per-error
@@ -954,7 +949,11 @@ export function createAuthRoutes(
         }
       }
 
-      const result = await dispatcher.write(mfaPreauthEnableStartQn, body, GUEST_USER);
+      const result = await dispatcher.write(
+        mfaPreauthEnableStartQn,
+        body,
+        createAnonymousUser(SYSTEM_TENANT_ID),
+      );
 
       if (!result.isSuccess) {
         // @cast-boundary error-details — KumikoError.details shape is per-error
@@ -985,7 +984,7 @@ export function createAuthRoutes(
 
   // POST /auth/mfa/preauth-confirm — completes both the enrollment started
   // by preauth-enable-start AND the login mfa-setup-required blocked.
-  // Mirrors /auth/mfa/verify structurally (public, GUEST_USER dispatch,
+  // Mirrors /auth/mfa/verify structurally (public, anonymous identity dispatch,
   // mintSessionAndRespond on success) with its OWN rate limiter
   // (mfaPreauthConfirmRateLimit) — same reasoning as mfaVerifyRateLimit.
   // Per-account brute-force protection (capping wrong-code guesses against
@@ -1016,7 +1015,11 @@ export function createAuthRoutes(
         }
       }
 
-      const result = await dispatcher.write(mfaPreauthConfirmQn, body, GUEST_USER);
+      const result = await dispatcher.write(
+        mfaPreauthConfirmQn,
+        body,
+        createAnonymousUser(SYSTEM_TENANT_ID),
+      );
 
       if (!result.isSuccess) {
         // @cast-boundary error-details — KumikoError.details shape is per-error
@@ -1128,7 +1131,11 @@ export function createAuthRoutes(
         return c.json({ isSuccess: false, error: "invalid_body" }, 400);
       }
 
-      const result = await dispatcher.write(sg.confirmHandler, parsed.data, GUEST_USER);
+      const result = await dispatcher.write(
+        sg.confirmHandler,
+        parsed.data,
+        createAnonymousUser(SYSTEM_TENANT_ID),
+      );
 
       if (!result.isSuccess) {
         // 422 für invalid_signup_token (handler-level UnprocessableError).
@@ -1210,7 +1217,11 @@ export function createAuthRoutes(
       if (!parsed.success) {
         return c.json({ isSuccess: false, error: "invalid_body" }, 400);
       }
-      const result = await dispatcher.write(inv.acceptWithLoginHandler, parsed.data, GUEST_USER);
+      const result = await dispatcher.write(
+        inv.acceptWithLoginHandler,
+        parsed.data,
+        createAnonymousUser(SYSTEM_TENANT_ID),
+      );
       if (!result.isSuccess) {
         const status = result.error.httpStatus as 400 | 401 | 403 | 422 | 500; // @cast-boundary engine-payload
         return c.json({ isSuccess: false, error: result.error }, status);
@@ -1258,7 +1269,11 @@ export function createAuthRoutes(
       if (!parsed.success) {
         return c.json({ isSuccess: false, error: "invalid_body" }, 400);
       }
-      const result = await dispatcher.write(inv.signupCompleteHandler, parsed.data, GUEST_USER);
+      const result = await dispatcher.write(
+        inv.signupCompleteHandler,
+        parsed.data,
+        createAnonymousUser(SYSTEM_TENANT_ID),
+      );
       if (!result.isSuccess) {
         const status = result.error.httpStatus as 400 | 401 | 403 | 422 | 500; // @cast-boundary engine-payload
         return c.json({ isSuccess: false, error: result.error }, status);
@@ -1457,10 +1472,20 @@ function registerTokenRequestRoute(opts: {
     if (!parsed.success) return c.json({ isSuccess: true });
 
     // The handler dispatches the magic-link mail via delivery before returning.
-    // Handler-level failures (only legitimate reason: misconfiguration) are
-    // silently swallowed — observability logs capture them for ops — so the
-    // response shape stays uniform for unknown vs. known emails.
-    await opts.dispatcher.write(opts.requestHandler, { email: parsed.data.email }, GUEST_USER);
+    // Handler-level failures (misconfiguration, e.g. no RateLimitResolver) stay
+    // out of the response so it is uniform for unknown vs. known emails, but
+    // they are logged — otherwise the mail silently never goes out. No email in
+    // the log line (PII).
+    const result = await opts.dispatcher.write(
+      opts.requestHandler,
+      { email: parsed.data.email },
+      createAnonymousUser(SYSTEM_TENANT_ID),
+    );
+    if (!result.isSuccess) {
+      console.error(
+        `[kumiko] token request handler "${opts.requestHandler}" failed: ${result.error.code}`,
+      );
+    }
 
     return c.json({ isSuccess: true });
   });
@@ -1480,7 +1505,11 @@ function registerTokenConfirmRoute(opts: {
     if (!parsed.success) {
       return c.json({ isSuccess: false, error: "invalid_body" }, 400);
     }
-    const result = await opts.dispatcher.write(opts.confirmHandler, parsed.data, GUEST_USER);
+    const result = await opts.dispatcher.write(
+      opts.confirmHandler,
+      parsed.data,
+      createAnonymousUser(SYSTEM_TENANT_ID),
+    );
     if (!result.isSuccess) {
       const status = result.error.httpStatus as 400 | 401 | 403 | 422 | 500; // @cast-boundary engine-payload
       return c.json({ isSuccess: false, error: result.error }, status);

package/src/api/server.ts

@@ -1,4 +1,4 @@
-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";
@@ -59,7 +59,7 @@ 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,
@@ -723,30 +723,24 @@ export function buildServer(options: ServerOptions): KumikoServer {
     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) || isExtraRoutePublicPath(c)) 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();
+      return patRateLimitGuard(c, next);
     });
   }
 
@@ -760,8 +754,9 @@ 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) || isExtraRoutePublicPath(c)) return next();
       return originGuard(c, next);
@@ -781,6 +776,14 @@ export function buildServer(options: ServerOptions): KumikoServer {
     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) {
@@ -845,20 +848,25 @@ export function buildServer(options: ServerOptions): KumikoServer {
       const honoHandler = async (c: import("hono").Context): Promise<Response> =>
         route.handler(c, {
           app,
-          // 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.
+          // 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),
         });
-      mountHonoRoute(app, route.method, route.path, honoHandler);
+      mountHonoRoute(
+        app,
+        route.method,
+        route.path,
+        honoHandler,
+        route.anonymous ? [] : sessionOnlyHttpRouteGuards,
+      );
     }
   }
 
@@ -958,7 +966,17 @@ function mountHonoRoute(
   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);
@@ -985,6 +1003,27 @@ function mountHonoRoute(
   }
 }
 
+// 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

package/src/changes.json

@@ -1,4 +1,30 @@
 [
+  {
+    "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",

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