@cosmicdrift/kumiko-framework 0.299.0 → 0.305.0

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,
@@ -160,14 +160,17 @@ export type ServerOptions = {
   //     of the app process.
   //   - `auth`: gates a single path-pattern (default `/api/auth/*`)
   //     with tighter limits. Typically `limit: 5, windowSeconds: 60`
-  //     to slow brute-force without breaking real users.
+  //     to slow brute-force without breaking real users. GET /api/auth/tenants
+  //     (session read, called on every page load) is always exempt — see
+  //     AUTH_RATE_LIMIT_EXEMPT_ROUTES in api-constants.ts.
   // Both omitted → no L1/L2 wired and no resolver auto-built unless an
   // L3 handler declared `rateLimit:`. This keeps zero-cost when unused.
   rateLimit?: {
     readonly global?: Omit<GlobalIpRateLimitOptions, "resolver">;
     readonly auth?: Omit<AuthEndpointRateLimitOptions, "resolver"> & {
       // Path-pattern the L2 middleware applies to. Default `/api/auth/*`.
-      // Override for apps with a different auth route layout.
+      // Override for apps with a different auth route layout. The
+      // GET /api/auth/tenants exemption above applies regardless of `path`.
       readonly path?: string;
     };
   };
@@ -723,30 +726,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 +757,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 +779,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 +851,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 +969,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 +1006,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
@@ -1139,6 +1181,9 @@ function buildExtraRouteHonoHandler(
           );
         } catch (e) {
           if (e instanceof ExtraRouteRejection) {
+            if (e.retryAfterSeconds !== undefined) {
+              return c.json(e.body, e.status, { "Retry-After": String(e.retryAfterSeconds) });
+            }
             return c.json(e.body, e.status);
           }
           return c.json(

package/src/changes.json

@@ -1,4 +1,72 @@
 [
+  {
+    "version": "0.305.0",
+    "type": "breaking",
+    "title": "rateLimit.auth (L2) no longer throttles GET /api/auth/tenants",
+    "detail": "The SPA's own session bootstrap called GET /api/auth/tenants on every\npage load, which counted against the L2 auth-endpoint bucket and threw\n429 on the 6th page load within a minute. This route is now exempted\nfrom rateLimit.auth by exact method+path match; all other auth routes\n(including POST on the same path, if ever added) are unaffected.",
+    "migration": "Apps using the default rateLimit.auth need no changes. Apps that want\nto keep throttling GET /api/auth/tenants should rely on rateLimit.global\n(L1, IP-based) instead. Credential-submitting POST routes are unaffected\neven when rateLimit.auth's `path` option is customized."
+  },
+  {
+    "version": "0.305.0",
+    "type": "fix",
+    "title": "KUMIKO_DRY_RUN_ENV=pulumi and =k8s now list optional env keys (e.g. PROMETHEUS_METRICS_TOKEN) as commented-out lines under an \"Optional\" header, with secret flag, generator and description; defaulted keys stay omitted",
+    "migration": "No action needed. Uncomment and set an optional line only when you want to enable that feature."
+  },
+  {
+    "version": "0.305.0",
+    "type": "improvement",
+    "title": "ExtraRouteRejection supports 503 + Retry-After for signature routes whose verify() is temporarily unable to run"
+  },
+  {
+    "version": "0.305.0",
+    "type": "fix",
+    "title": "Job backoff now waits between retries: backoff defaults to a 1000 ms base delay and accepts { type, delayMs } (fw#3167)",
+    "detail": "Previously, jobs with backoff set retried immediately: BullMQ received only { type } with no delay, and its fixed/exponential strategies compute NaN/undefined without one (falsy, so no wait). Now \"fixed\" waits a constant 1000 ms and \"exponential\" waits 1000/2000/4000 ms... between attempts by default. Jobs with a high retries count will therefore take noticeably longer to reach their final failure. A new object form, backoff: { type, delayMs }, lets a job configure its own base delay instead of the 1000 ms default."
+  },
+  {
+    "version": "0.305.0",
+    "type": "breaking",
+    "title": "Writes under an anonymous root need access.personalData: \"public-intake\" at runtime, across feature boundaries (fw#3165)",
+    "detail": "The boot check from fw#2885 only sees personal-data keys in an anonymous write handler's own input schema, for entities of its own feature. Every public dispatch (write, batch command, query, stream) now computes a WriteOrigin (root handler, anonymous root, public-intake declared) once. Every nested call inherits it: ctx.write, ctx.writeAs, ctx.query, ctx.queryAs, nested writes and afterCommit hooks. When the root is anonymous and does not declare public-intake, a write that touches a personal-data field (pii / userOwned / recordOwned) of any registered entity fails with AccessDeniedError, details.reason \"public_intake_required\". The error details name the root handler, the table and the fields, never the values. The check runs in TenantDb.insertOne/updateMany, in db.global().insertOne/updateMany and in the event-sourced create/update executor, after preSave and before the event append. It also covers rebound TenantDbs (acknowledgeCrossTenant, hook re-gating). Authenticated sessions are not affected. Not gated: ctx.db.unsafeRaw (covered by escapeHatch plus audit); ctx.appendEvent on a feature's own events (foreign events are already rejected); tables outside the registered entities; jobs and event subscribers queued from an anonymous root; and TenantDbs that handler code builds directly with createTenantDb. The last two are tracked in fw#3185, which also lists the bundled auth-email-password and user-data-rights flows that go through unsafeRaw or createTenantDb.",
+    "migration": "A write handler that anonymous callers can reach (roles include \"anonymous\") and that writes a personal-data field (pii / userOwned / recordOwned) of any entity must declare access: { roles: [..., \"anonymous\"], personalData: \"public-intake\" }. This applies whether the handler writes the field itself or through ctx.db, the CRUD executor, ctx.write, ctx.writeAs/queryAs or a postSave/afterCommit hook, and it applies across features. Without the declaration the write now fails with AccessDeniedError (details.reason \"public_intake_required\"). A failing afterCommit hook is only logged, and its write does not happen. Known consumer handlers, measured on 23.09.2026: offlot-app waitlist:submit, vehicle-enquiry:submit and try-first:set-contact; publicstatus email-subscriber:subscribe; show-pony rsvp:submit. Add the declaration if the anonymous intake is intended (the handler's rateLimit is then the only protection). Otherwise stop writing the field from the anonymous path."
+  },
+  {
+    "version": "0.305.0",
+    "type": "improvement",
+    "title": "setupTestStack accepts a metrics option, forwarded to buildServer like runProdApp (fw#3182)",
+    "detail": "TestStackOptions gains an optional metrics field forwarded to buildServer, same as runProdApp. Spread resolveObservabilityWiring(token) into setupTestStack/setupTestStackFromFeatures/setupAppTestStack to get /metrics mounted in integration tests with the same token-gated PrometheusMeter-backed behavior as prod."
+  },
+  {
+    "version": "0.305.0",
+    "type": "fix",
+    "title": "Write-path 5xx logs now include the original cause chain"
+  },
+  {
+    "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/db/event-store-executor-write.ts

@@ -31,6 +31,7 @@ import {
   tryMapUniqueViolation,
 } from "./event-store-executor-context";
 import { runInSavepointIfSupported } from "./query";
+import { assertPersonalDataWrite, tableNameOf } from "./tenant-db";
 import { tenantDbRunner } from "./tenant-db-runner";
 
 // Art. 17 erasure runs as the framework operator, not as a row owner; a
@@ -145,6 +146,9 @@ export function createWriteVerbs(
       if ("failure" in preSaveResult) return preSaveResult.failure;
       const data = preSaveResult.data;
 
+      // After preSave so derived fields count, before the event append so nothing persists.
+      assertPersonalDataWrite(db, tableNameOf(table), Object.keys(data), entity);
+
       // H.2 — entity-level write-ownership on create. No oldRow exists, so
       // only the new row is checked. No Straddle concern for creates.
       if (!userCanCreateFieldRow(user, entity.access?.write, data)) {
@@ -334,6 +338,9 @@ export function createWriteVerbs(
       if ("failure" in preSaveResult) return preSaveResult.failure;
       const changes = preSaveResult.data;
 
+      // After preSave so derived fields count, before the event append so nothing persists.
+      assertPersonalDataWrite(db, tableNameOf(table), Object.keys(changes), entity);
+
       // H.2 — entity-level write-ownership on update. Load old row (already
       // done above), build post-change row via shallow merge. Straddle-safe
       // multi-role check: at least one role must accept BOTH old and new —

package/src/db/tenant-db.ts

@@ -24,6 +24,7 @@ import {
   type SelectOptions,
   type WhereObject,
 } from "../db/query";
+import type { EntityDefinition } from "../engine/types/fields";
 import { SYSTEM_TENANT_ID, type TenantId } from "../engine/types/identifiers";
 import { AccessDeniedError, InternalError, memberResolutionReadOnlyDenied } from "../errors";
 import { emitDbQuery, type Meter, registerStandardMetrics, type Tracer } from "../observability";
@@ -45,6 +46,21 @@ const declaredUnsafeRawRunners = new WeakMap<
   (reason: string) => DbRunner
 >();
 
+// The CRUD executor writes through tenantDbRunner, not insertOne, so it asks the
+// TenantDb it was handed for its gate. Bound inside createTenantDb so rebound instances
+// (withUnsafeRawGrant, acknowledgeConventionCrossTenant) carry it too.
+const personalDataGates = new WeakMap<TenantDb, PersonalDataGate>();
+
+// The executor passes its entity so the check does not depend on the table-name lookup.
+export function assertPersonalDataWrite(
+  db: TenantDb,
+  tableName: string,
+  keys: readonly string[],
+  entity: EntityDefinition,
+): void {
+  personalDataGates.get(db)?.(tableName, keys, entity);
+}
+
 // Framework-private (not re-exported from db/index.ts): same grant check + audit as unsafeRaw, for engine forwarding.
 export function unsafeRawForDeclaredStep(
   holder: TenantDb | UncheckedSystemDb,
@@ -170,7 +186,7 @@ export function castTenantRows<T>(rows: readonly Record<string, unknown>[]): rea
   return rows as unknown as readonly T[];
 }
 
-function tableNameOf(table: Table | EntityTableMeta): string {
+export function tableNameOf(table: Table | EntityTableMeta): string {
   const sym = (table as Record<symbol, unknown>)[KUMIKO_NAME_SYMBOL];
   if (typeof sym === "string") return sym;
   return asEntityTableMeta(table)?.tableName ?? "<unknown>";
@@ -205,8 +221,16 @@ export type TenantDbGrants = {
   // Set for a resolved member principal (ctx.queryAsMember): no raw DbRunner leaves
   // this TenantDb, so no handler can COMMIT/RELEASE SAVEPOINT out of the READ ONLY scope.
   readonly memberReadOnly?: boolean;
+  // Set only for an anonymous root without personalData: "public-intake" (write-origin.ts).
+  readonly personalDataGate?: PersonalDataGate;
 };
 
+export type PersonalDataGate = (
+  tableName: string,
+  keys: readonly string[],
+  entity?: EntityDefinition,
+) => void;
+
 const unsafeRawRebinders = new WeakMap<
   TenantDb,
   (grant: EscapeHatchDeclaration | undefined) => TenantDb
@@ -347,6 +371,20 @@ export function createTenantDb(
     return grants?.globalWrites?.reason ?? "";
   }
 
+  function personalDataDenied(
+    table: Table | EntityTableMeta,
+    keys: readonly string[],
+  ): AccessDeniedError | undefined {
+    if (!grants?.personalDataGate) return undefined;
+    try {
+      grants.personalDataGate(tableNameOf(table), keys);
+      return undefined;
+    } catch (e) {
+      if (e instanceof AccessDeniedError) return e;
+      throw e;
+    }
+  }
+
   function foreignTenantOnGlobalWrite(
     table: Table | EntityTableMeta,
     tenantIdValue: unknown,
@@ -379,7 +417,9 @@ export function createTenantDb(
         values: Record<string, unknown>,
       ): Promise<T | undefined> {
         const denied =
-          missingEscapeHatch(table) ?? foreignTenantOnGlobalWrite(table, values["tenantId"]);
+          missingEscapeHatch(table) ??
+          foreignTenantOnGlobalWrite(table, values["tenantId"]) ??
+          personalDataDenied(table, Object.keys(values));
         if (denied) return Promise.reject(denied);
         report("global-write", globalWriteReason());
         return withDbSpan("insert", table, async () => bunInsertOne<T>(db, table, values));
@@ -389,7 +429,9 @@ export function createTenantDb(
         where: WhereObject,
       ): Promise<readonly T[]> {
         const denied =
-          missingEscapeHatch(table) ?? foreignTenantOnGlobalWrite(table, set["tenantId"]);
+          missingEscapeHatch(table) ??
+          foreignTenantOnGlobalWrite(table, set["tenantId"]) ??
+          personalDataDenied(table, Object.keys(set));
         if (denied) return Promise.reject(denied);
         if (!where || Object.keys(where).length === 0) {
           return Promise.reject(
@@ -483,6 +525,8 @@ export function createTenantDb(
         );
         if (denied) return Promise.reject(denied);
       }
+      const personalDenied = personalDataDenied(table, Object.keys(values));
+      if (personalDenied) return Promise.reject(personalDenied);
       const data = insertValues(table, values);
       return withDbSpan("insert", table, async () => bunInsertOne<T>(db, table, data));
     },
@@ -499,6 +543,8 @@ export function createTenantDb(
           ),
         );
       }
+      const personalDenied = personalDataDenied(table, Object.keys(set));
+      if (personalDenied) return Promise.reject(personalDenied);
       const filter = writeWhere(table, where);
       return withDbSpan("update", table, async () => bunUpdateMany<T>(db, table, set, filter));
     },
@@ -525,6 +571,7 @@ export function createTenantDb(
     return createTenantDb(db, tenantId, "system", tracer, meter, signal, grants);
   });
   bindTenantDbRunner(tenantDb, db);
+  if (grants?.personalDataGate) personalDataGates.set(tenantDb, grants.personalDataGate);
   return tenantDb;
 }
 

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

package/src/engine/boot-validator/__tests__/access-declarations.test.ts

@@ -578,3 +578,130 @@ describe("validateAccessDeclarations — self-bound personal-data fields", () =>
     expect(() => validateAccessDeclarations(feature)).toThrow(/"displayName"/);
   });
 });
+
+describe("validateAccessDeclarations — anonymous (roles-form) personal-data intake", () => {
+  test("an anonymous write handler accepting a personal-data field without personalData throws", () => {
+    const feature = defineFeature("notes", (r) => {
+      r.entity("note", noteEntity);
+      r.writeHandler(
+        "note:signup",
+        z.object({ email: z.string() }),
+        async () => ({ isSuccess: true as const, data: {} }),
+        { access: { roles: ["anonymous"] } },
+      );
+    });
+    expect(() => validateAccessDeclarations(feature)).toThrow(/Feature notes/);
+    expect(() => validateAccessDeclarations(feature)).toThrow(/"note:signup"/);
+    expect(() => validateAccessDeclarations(feature)).toThrow(/"email"/);
+    expect(() => validateAccessDeclarations(feature)).toThrow(/personalData: "public-intake"/);
+  });
+
+  test('the same handler WITH personalData: "public-intake" boots fine', () => {
+    const feature = defineFeature("notes", (r) => {
+      r.entity("note", noteEntity);
+      r.writeHandler(
+        "note:signup",
+        z.object({ email: z.string() }),
+        async () => ({ isSuccess: true as const, data: {} }),
+        { access: { roles: ["anonymous"], personalData: "public-intake" } },
+      );
+    });
+    expect(() => validateAccessDeclarations(feature)).not.toThrow();
+  });
+
+  test('an owner-bound personal-data field is not exempted for an anonymous handler — anonymous callers share one user.id, so from("user:id", ...) binds no one', () => {
+    const ownedByCaller: OwnershipMap = { Member: from("user:id", "ownerUserId") };
+    const entity = createEntity({
+      table: "fw2885_guard_anon_owned",
+      fields: {
+        name: createTextField({ personal: { of: "ownerUserId" }, find: "none" }),
+        ownerUserId: createTextField({ required: false, personal: "ref" }),
+      },
+      access: { write: ownedByCaller },
+    });
+    const schema = z.object({ name: z.string() });
+    const anonymousFeature = defineFeature("notes", (r) => {
+      r.entity("note", entity);
+      r.writeHandler("note:signup", schema, async () => ({ isSuccess: true as const, data: {} }), {
+        access: { roles: ["anonymous"] },
+      });
+    });
+    expect(anonymousFeature.handlerEntityMappings["note:signup"]).toBe("note");
+    expect(() => validateAccessDeclarations(anonymousFeature)).toThrow(/"name"/);
+
+    // Control: the same owner-bound entity/schema via openToAll IS exempted, so the throw above is override-specific.
+    const openToAllFeature = defineFeature("notes", (r) => {
+      r.entity("note", entity);
+      r.writeHandler("note:signup", schema, async () => ({ isSuccess: true as const, data: {} }), {
+        access: { openToAll: { reason: "members share contacts" } },
+      });
+    });
+    expect(() => validateAccessDeclarations(openToAllFeature)).not.toThrow();
+  });
+
+  test('personalData: "public-intake" on roles without "anonymous" throws', () => {
+    const feature = defineFeature("notes", (r) => {
+      r.entity("note", noteEntity);
+      r.writeHandler(
+        "note:create",
+        z.object({ title: z.string() }),
+        async () => ({ isSuccess: true as const, data: {} }),
+        { access: { roles: ["Admin"], personalData: "public-intake" } },
+      );
+    });
+    expect(() => validateAccessDeclarations(feature)).toThrow(/"note:create"/);
+    expect(() => validateAccessDeclarations(feature)).toThrow(/anonymous/);
+  });
+
+  test('personalData: "tenant-members" on the roles form throws', () => {
+    const feature = defineFeature("notes", (r) => {
+      r.entity("note", noteEntity);
+      r.writeHandler(
+        "note:create",
+        z.object({ title: z.string() }),
+        async () => ({ isSuccess: true as const, data: {} }),
+        {
+          // @cast-boundary test — simulates JSON/Designer input that doesn't match the static union
+          access: { roles: ["anonymous"], personalData: "tenant-members" } as unknown as AccessRule,
+        },
+      );
+    });
+    expect(() => validateAccessDeclarations(feature)).toThrow(/"tenant-members"/);
+  });
+
+  test("personalData on the roles form of a query handler throws", () => {
+    const feature = defineFeature("notes", (r) => {
+      r.entity("note", noteEntity);
+      r.queryHandler("note:list", z.object({}), async () => [], {
+        access: { roles: ["anonymous"], personalData: "public-intake" },
+      });
+    });
+    expect(() => validateAccessDeclarations(feature)).toThrow(/"note:list"/);
+    expect(() => validateAccessDeclarations(feature)).toThrow(/access\.personalData/);
+  });
+
+  test("a non-anonymous roles handler accepting a personal-data field does not throw", () => {
+    const feature = defineFeature("notes", (r) => {
+      r.entity("note", noteEntity);
+      r.writeHandler(
+        "note:create",
+        z.object({ email: z.string() }),
+        async () => ({ isSuccess: true as const, data: {} }),
+        { access: { roles: ["Admin"] } },
+      );
+    });
+    expect(() => validateAccessDeclarations(feature)).not.toThrow();
+  });
+
+  test('personalData: "tenant-members" no longer type-checks on the roles form', () => {
+    // @ts-expect-error "tenant-members" is only valid on openToAll, not the roles form
+    const access: AccessRule = { roles: ["anonymous"], personalData: "tenant-members" };
+    expect(access).toBeDefined();
+  });
+
+  test("an unrecognised personalData string does not type-check on the roles form", () => {
+    // @ts-expect-error only "public-intake" is a valid roles-form personalData value
+    const access: AccessRule = { roles: ["anonymous"], personalData: "whatever" };
+    expect(access).toBeDefined();
+  });
+});