@cosmicdrift/kumiko-bundled-features 0.299.0 → 0.305.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.299.0",
+  "version": "0.305.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -133,12 +133,12 @@
     "./workflow-runner": "./src/workflow-runner/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.299.0",
-    "@cosmicdrift/kumiko-framework": "0.299.0",
-    "@cosmicdrift/kumiko-headless": "0.299.0",
-    "@cosmicdrift/kumiko-renderer": "0.299.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.299.0",
-    "@cosmicdrift/kumiko-types": "0.299.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.305.0",
+    "@cosmicdrift/kumiko-framework": "0.305.0",
+    "@cosmicdrift/kumiko-headless": "0.305.0",
+    "@cosmicdrift/kumiko-renderer": "0.305.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.305.0",
+    "@cosmicdrift/kumiko-types": "0.305.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -167,8 +167,8 @@
   ],
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
-    "@cosmicdrift/kumiko-locale-de": "0.299.0",
-    "@cosmicdrift/kumiko-locale-es": "0.299.0",
+    "@cosmicdrift/kumiko-locale-de": "0.305.0",
+    "@cosmicdrift/kumiko-locale-es": "0.305.0",
     "jsqr": "^1.4.0"
   }
 }

package/src/auth-email-password/__tests__/auth-tenants-rate-limit.integration.test.ts

@@ -0,0 +1,116 @@
+// GET /api/auth/tenants is exempt from the L2 auth-endpoint rate limit;
+// credential endpoints on the same /api/auth/* mount (e.g. login) keep the default limit.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { randomBytes } from "node:crypto";
+import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { createTestEnvelopeCipher } from "@cosmicdrift/kumiko-framework/testing";
+import { createConfigFeature } from "../../config";
+import { createConfigResolver } from "../../config/resolver";
+import { configValuesTable } from "../../config/table";
+import { createTenantFeature } from "../../tenant";
+import { tenantMembershipsTable } from "../../tenant/membership-table";
+import { tenantEntity } from "../../tenant/schema/tenant";
+import { seedTenantMembership } from "../../tenant/testing";
+import { UserHandlers } from "../../user";
+import { createUserFeature } from "../../user/feature";
+import { userEntity } from "../../user/schema/user";
+import { AuthHandlers } from "../constants";
+import { createAuthEmailPasswordFeature } from "../feature";
+
+let stack: TestStack;
+const encryptionKey = randomBytes(32).toString("base64");
+const membershipTenantId = "00000000-0000-4000-8000-000000000001";
+
+beforeAll(async () => {
+  const encryption = createTestEnvelopeCipher(encryptionKey);
+  const resolver = createConfigResolver({ cipher: encryption });
+
+  stack = await setupTestStack({
+    features: [
+      createConfigFeature(),
+      createUserFeature(),
+      createTenantFeature(),
+      createAuthEmailPasswordFeature(),
+    ],
+    extraContext: { configResolver: resolver, configEncryption: encryption },
+    authConfig: {
+      membershipQuery: "tenant:query:memberships",
+      loginHandler: AuthHandlers.login,
+    },
+    // No `limit` override — this proves the real framework default (5/60s)
+    // exempts GET /api/auth/tenants and still throttles POST /api/auth/login.
+    rateLimit: {
+      auth: { onFailClosed: () => {} },
+    },
+  });
+
+  await unsafeCreateEntityTable(stack.db, userEntity);
+  await unsafeCreateEntityTable(stack.db, tenantEntity);
+  await unsafePushTables(stack.db, { configValuesTable, tenantMembershipsTable });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+async function getTenants(token: string, ip: string): Promise<Response> {
+  return stack.app.request("/api/auth/tenants", {
+    method: "GET",
+    headers: { Authorization: `Bearer ${token}`, "x-forwarded-for": ip },
+  });
+}
+
+async function postLogin(ip: string, email: string): Promise<Response> {
+  return stack.app.request("/api/auth/login", {
+    method: "POST",
+    headers: { "Content-Type": "application/json", "x-forwarded-for": ip },
+    body: JSON.stringify({ email, password: "wrong-password" }),
+  });
+}
+
+describe("GET /api/auth/tenants is exempt from the L2 auth rate limit", () => {
+  test("10 GETs from the same IP all succeed — the 6th would 429 without the exemption", async () => {
+    const created = await stack.http.writeOk<{ id: string }>(
+      UserHandlers.create,
+      { email: "tenants-exempt@example.com", passwordHash: "unused", displayName: "exempt-user" },
+      TestUsers.systemAdmin,
+    );
+    await seedTenantMembership(stack.db, {
+      userId: created.id,
+      tenantId: membershipTenantId,
+      roles: ["User"],
+    });
+    const user: SessionUser = { id: created.id, tenantId: membershipTenantId, roles: ["User"] };
+    const token = await stack.jwt.sign(user);
+    const ip = "10.70.0.1";
+
+    for (let i = 0; i < 10; i++) {
+      const res = await getTenants(token, ip);
+      expect(res.status).toBe(200);
+    }
+    const body = await (await getTenants(token, ip)).json();
+    expect(body.tenants.length).toBe(1);
+  });
+});
+
+describe("POST /api/auth/login keeps the default L2 limit (5/60s)", () => {
+  test("6th login attempt from the same IP is 429 via the L2 bucket, not just the route's own limiter", async () => {
+    const ip = "10.70.0.2";
+    for (let i = 0; i < 5; i++) {
+      await postLogin(ip, `nope-${i}@example.com`);
+    }
+    const blocked = await postLogin(ip, "nope-5@example.com");
+    expect(blocked.status).toBe(429);
+    const body = (await blocked.json()) as { error: { code: string; details: { bucket: string } } };
+    expect(body.error.code).toBe("rate_limited");
+    expect(body.error.details.bucket).toBe(`l2:${ip}:/api/auth/login`);
+  });
+});

package/src/auth-email-password/__tests__/auth.integration.test.ts

@@ -393,12 +393,12 @@ describe("scenario 6: logout", () => {
   });
 
   test("unauthenticated call to logout is rejected by framework access", async () => {
-    // roles: ["all"] — no authenticated role. Handler's access is
+    // roles: ["anonymous"] — no authenticated role. Handler's access is
     // access.authenticated which requires User/Admin/SystemAdmin.
     const guest = createTestUser({
       id: 0,
       tenantId: "00000000-0000-4000-8000-000000000000",
-      roles: ["all"],
+      roles: ["anonymous"],
     });
     const error = await stack.http.writeErr(AuthHandlers.logout, {}, guest);
     expectErrorIncludes(error, "access_denied");

package/src/auth-email-password/__tests__/invite-accept-with-login-gates.integration.test.ts

@@ -166,14 +166,14 @@ function aliceSession(): SessionUser {
   return { id: aliceId, tenantId: TENANT_A_ID, roles: ["Admin"] };
 }
 
-// auth-mfa:write:verify runs pre-session (access: { roles: ["all"] }) —
+// auth-mfa:write:verify runs pre-session (access: { roles: ["anonymous"] }) —
 // dispatched here the same way the framework's /api/auth/mfa/verify route
-// would, with a guest identity. The handler derives everything it needs
-// from the challenge token, not from this actor.
+// would, with the anonymous identity. The handler derives everything it
+// needs from the challenge token, not from this actor.
 const GUEST: SessionUser = {
-  id: "00000000-0000-0000-0000-000000000000",
+  id: "anonymous",
   tenantId: "00000000-0000-4000-8000-000000000000" as TenantId,
-  roles: ["all"],
+  roles: ["anonymous"],
 };
 
 async function inviteEmail(email: string, role: string): Promise<string> {

package/src/auth-email-password/__tests__/invite-flow.integration.test.ts

@@ -82,9 +82,9 @@ function newTenantId(_suffix: string): TenantId {
 }
 
 const GUEST: SessionUser = {
-  id: "00000000-0000-0000-0000-000000000000",
+  id: "anonymous",
   tenantId: SYSTEM_TENANT_ID,
-  roles: ["all"],
+  roles: ["anonymous"],
 };
 
 function extractTokenFromMail(html: string): string {

package/src/auth-email-password/__tests__/login-anonymous-identity-rate-limit.integration.test.ts

@@ -0,0 +1,124 @@
+// login.write.ts's access.roles: ["anonymous"] carries a mandatory
+// handler-level rateLimit: { per: "ip+handler", limit: 20, windowSeconds: 60 }
+// (boot-validator's validateAnonymousRateLimit). Proves that L3 handler
+// rate-limit fires over real HTTP, and that a legitimate login still succeeds.
+//
+// loginRateLimit is disabled (null): the route's own in-memory limiter
+// buckets on "ip|email" and would trip before the handler-level "ip+handler"
+// bucket under the same IP — this isolates the handler-level rateLimit.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { randomBytes } from "node:crypto";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { createTestEnvelopeCipher } from "@cosmicdrift/kumiko-framework/testing";
+import { createConfigFeature } from "../../config";
+import { createConfigResolver } from "../../config/resolver";
+import { configValuesTable } from "../../config/table";
+import { hashPassword } from "../../shared";
+import { createTenantFeature } from "../../tenant";
+import { tenantMembershipsTable } from "../../tenant/membership-table";
+import { tenantEntity } from "../../tenant/schema/tenant";
+import { seedTenantMembership } from "../../tenant/testing";
+import { UserHandlers } from "../../user";
+import { createUserFeature } from "../../user/feature";
+import { userEntity, userTable } from "../../user/schema/user";
+import { AuthErrors, AuthHandlers } from "../constants";
+import { createAuthEmailPasswordFeature } from "../feature";
+
+let stack: TestStack;
+const encryptionKey = randomBytes(32).toString("base64");
+
+beforeAll(async () => {
+  const encryption = createTestEnvelopeCipher(encryptionKey);
+  const resolver = createConfigResolver({ cipher: encryption });
+
+  stack = await setupTestStack({
+    features: [
+      createConfigFeature(),
+      createUserFeature(),
+      createTenantFeature(),
+      createAuthEmailPasswordFeature(),
+    ],
+    extraContext: { configResolver: resolver, configEncryption: encryption },
+    authConfig: {
+      membershipQuery: "tenant:query:memberships",
+      loginHandler: AuthHandlers.login,
+      loginRateLimit: null,
+      loginErrorStatusMap: {
+        [AuthErrors.invalidCredentials]: 401,
+        [AuthErrors.noMembership]: 403,
+      },
+    },
+  });
+
+  await stack.redis.flushNamespace();
+  await unsafeCreateEntityTable(stack.db, userEntity);
+  await unsafeCreateEntityTable(stack.db, tenantEntity);
+  await unsafePushTables(stack.db, { configValuesTable, tenantMembershipsTable });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${userTable.tableName}"`);
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${tenantMembershipsTable.tableName}"`);
+  await stack.redis.flushNamespace();
+});
+
+const systemAdmin = TestUsers.systemAdmin;
+
+async function seedLoginUser(email: string, password: string): Promise<void> {
+  const hash = await hashPassword(password);
+  const created = await stack.http.writeOk<{ id: string }>(
+    UserHandlers.create,
+    { email, passwordHash: hash, displayName: email.split("@")[0] ?? "user" },
+    systemAdmin,
+  );
+  await seedTenantMembership(stack.db, {
+    userId: created.id,
+    tenantId: "00000000-0000-4000-8000-000000000001",
+    roles: ["User"],
+  });
+}
+
+async function postLogin(ip: string, email: string, password: string): Promise<Response> {
+  return await stack.app.request("/api/auth/login", {
+    method: "POST",
+    headers: { "Content-Type": "application/json", "x-forwarded-for": ip },
+    body: JSON.stringify({ email, password }),
+  });
+}
+
+describe("POST /auth/login — anonymous identity handler rateLimit (ip+handler)", () => {
+  test("21st failed login from the same IP is rejected with rate_limited (429)", async () => {
+    const ip = "10.60.0.1";
+    for (let i = 0; i < 20; i++) {
+      const res = await postLogin(ip, `nope-${i}@example.com`, "wrong-password");
+      expect(res.status).toBe(401);
+    }
+    const last = await postLogin(ip, "nope-20@example.com", "wrong-password");
+    expect(last.status).toBe(429);
+    const body = (await last.json()) as { error?: { code?: string } | string };
+    const code = typeof body.error === "string" ? body.error : body.error?.code;
+    expect(code).toBe("rate_limited");
+  });
+
+  test("a legitimate login still succeeds (anonymous dispatch identity didn't break the happy path)", async () => {
+    const ip = "10.60.0.2";
+    await seedLoginUser("legit@example.com", "correct horse battery staple");
+
+    const res = await postLogin(ip, "legit@example.com", "correct horse battery staple");
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { isSuccess: boolean };
+    expect(body.isSuccess).toBe(true);
+  });
+});

package/src/auth-email-password/__tests__/login-mfa-setup-required.integration.test.ts

@@ -47,14 +47,14 @@ const CHALLENGE_TOKEN_SECRET = "test-mfa-challenge-secret-at-least-32-bytes!!";
 const TENANT_ID: TenantId = testTenantId(400);
 
 // auth-mfa:write:enable-start-preauth / enable-confirm-preauth both run
-// pre-session (access: { roles: ["all"] }) — dispatched here the same way
-// the framework's /api/auth/mfa/preauth-enable-start and preauth-confirm
-// routes would, with a guest identity. Both handlers derive everything they
-// need from the verified token, not from this actor.
+// pre-session (access: { roles: ["anonymous"] }) — dispatched here the same
+// way the framework's /api/auth/mfa/preauth-enable-start and preauth-confirm
+// routes would, with the anonymous identity. Both handlers derive everything
+// they need from the verified token, not from this actor.
 const GUEST: SessionUser = {
-  id: "00000000-0000-0000-0000-000000000000",
+  id: "anonymous",
   tenantId: "00000000-0000-4000-8000-000000000000" as TenantId,
-  roles: ["all"],
+  roles: ["anonymous"],
 };
 
 beforeAll(async () => {

package/src/auth-email-password/__tests__/public-routes-rate-limit.integration.test.ts

@@ -10,6 +10,7 @@ import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   setupTestStack,
   type TestStack,
+  TestUsers,
   unsafeCreateEntityTable,
   unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/stack";
@@ -22,10 +23,12 @@ import { createDeliveryFeature, createDeliveryTestContext } from "../../delivery
 import { notificationPreferencesTable } from "../../delivery/tables";
 import { createRendererFoundationFeature } from "../../renderer-foundation/feature";
 import { createRendererSimpleFeature, simpleRenderer } from "../../renderer-simple";
+import { hashPassword } from "../../shared";
 import { createTemplateResolverFeature } from "../../template-resolver/feature";
 import { createTenantFeature } from "../../tenant";
 import { tenantMembershipsTable } from "../../tenant/membership-table";
 import { tenantEntity } from "../../tenant/schema/tenant";
+import { UserHandlers } from "../../user";
 import { createUserFeature } from "../../user/feature";
 import { userEntity, userTable } from "../../user/schema/user";
 import { AuthHandlers } from "../constants";
@@ -174,3 +177,28 @@ describe("L2 rate-limit covers public token routes", () => {
     expect(victimFirst.status).toBe(200);
   });
 });
+
+// The 200-for-unknown-email tests above prove nothing about the handler
+// actually running — registerTokenRequestRoute swallows every handler
+// failure into an always-200 response (anti-enumeration). Only a seeded,
+// real user distinguishes "mail sent" from "silently swallowed" — which is
+// exactly what an anonymous-dispatch switch could silently break.
+describe("request-password-reset actually dispatches mail for a real user", () => {
+  test("a seeded user gets the reset mail (anonymous dispatch didn't swallow it)", async () => {
+    const hash = await hashPassword("correct horse battery staple");
+    await stack.http.writeOk(
+      UserHandlers.create,
+      { email: "reset-target@example.com", passwordHash: hash, displayName: "reset-target" },
+      TestUsers.systemAdmin,
+    );
+
+    const before = emailTransport.sent.length;
+    const res = await postFrom("/api/auth/request-password-reset", "10.50.0.200", {
+      email: "reset-target@example.com",
+    });
+
+    expect(res.status).toBe(200);
+    expect(emailTransport.sent.length).toBe(before + 1);
+    expect(emailTransport.sent.at(-1)?.to).toBe("reset-target@example.com");
+  });
+});

package/src/auth-email-password/changes.json

@@ -1,4 +1,17 @@
 [
+  {
+    "version": "0.305.0",
+    "type": "breaking",
+    "title": "Session bootstrap failures now render a retryable error screen instead of hanging on \"loading\"",
+    "detail": "fetchTenants()/fetchCurrentUser() failures (rate limit, 5xx, network)\nused to reject out of the session bootstrap effect and leave the UI on\nthe loading placeholder forever. SessionStatus gained an \"error\" value\nand SessionState gained a bootstrapFailure field; the auth gate now\nrenders SessionBootstrapErrorScreen with a Retry-After-aware retry\nbutton for this case.",
+    "migration": "Code with an exhaustive switch over SessionStatus, or tests/stories that\nhand-build a SessionState literal, needs to add the \"error\" case and the\nbootstrapFailure field. refresh() no longer rejects on bootstrap\nfailures; it resolves and sets status to \"error\" instead."
+  },
+  {
+    "version": "0.300.0",
+    "type": "breaking",
+    "title": "auth handlers switch from GUEST_USER (roles: [\"all\"]) to the anonymous identity with a per-IP rateLimit",
+    "migration": "The auth-email-password and auth-mfa handlers reachable from unauthenticated /auth/* routes (login, invite-accept-with-login, invite-signup-complete, reset-password, signup-confirm, verify-email, confirm-account-unlock, signup-request, the token-request handlers, mfa verify, mfa enable-start-preauth, mfa enable-confirm-preauth) now declare access: { roles: [\"anonymous\"] } instead of access: { roles: [\"all\"] }, each with its own rateLimit: { per: \"ip+handler\", limit, windowSeconds }. Enforcing that rateLimit on a request that carries a client IP requires a RateLimitResolver (Redis), same as the already rate-limited self-registration-status query; without one these handlers fail with InternalError (fail-closed, #1467). The password-reset, email-verification and account-unlock request routes keep answering 200 for anti-enumeration, so there the failure shows up as a \"[kumiko] token request handler ... failed\" error log line and no mail is sent. Wire Redis (or context.rateLimit) before relying on these routes. Test fixtures that hand-roll a guest SessionUser with roles: [\"all\"] must switch to roles: [\"anonymous\"] (or createAnonymousUser from @cosmicdrift/kumiko-framework/engine)."
+  },
   {
     "version": "0.291.0",
     "type": "improvement",

package/src/auth-email-password/handlers/confirm-account-unlock.write.ts

@@ -29,7 +29,8 @@ export function createConfirmAccountUnlockHandler(opts: ConfirmAccountUnlockOpti
     schema: z.object({
       token: z.string().min(1),
     }),
-    access: { roles: ["all"] },
+    access: { roles: ["anonymous"] },
+    rateLimit: { per: "ip+handler", limit: 20, windowSeconds: 60 },
     agent: { expose: false },
     handler: async (event, ctx) => {
       if (!opts.hmacSecret) {

package/src/auth-email-password/handlers/invite-accept-with-login.write.ts

@@ -115,7 +115,8 @@ export function createInviteAcceptWithLoginHandler(opts: InviteAcceptWithLoginOp
   >({
     name: "invite-accept-with-login",
     schema: InviteAcceptWithLoginSchema,
-    access: { roles: ["all"] },
+    access: { roles: ["anonymous"] },
+    rateLimit: { per: "ip+handler", limit: 20, windowSeconds: 60 },
     escapeHatch: {
       reason:
         "Anonymous invite-accept has no session in the invited tenant yet — checks existing " +

package/src/auth-email-password/handlers/invite-accept.write.ts

@@ -78,9 +78,9 @@ export function createInviteAcceptHandler() {
   return defineWriteHandler<"invite-accept", typeof InviteAcceptSchema, InviteAcceptData>({
     name: "invite-accept",
     schema: InviteAcceptSchema,
-    // openToAll: any authenticated user (Branch 1). Branch 2+3 (anon)
-    // nutzen `roles: ["all"]` weil dort GUEST_USER mit ["all"]-role
-    // dispatched wird.
+    // openToAll: any authenticated user (Branch 1). Branch 2+3 (anon) live
+    // in the sibling invite-accept-with-login / invite-signup-complete
+    // handlers, which declare roles: ["anonymous"] instead.
     access: {
       openToAll: {
         reason:

package/src/auth-email-password/handlers/invite-signup-complete.write.ts

@@ -92,7 +92,8 @@ export function createInviteSignupCompleteHandler() {
   >({
     name: "invite-signup-complete",
     schema: InviteSignupCompleteSchema,
-    access: { roles: ["all"] },
+    access: { roles: ["anonymous"] },
+    rateLimit: { per: "ip+handler", limit: 20, windowSeconds: 60 },
     agent: { expose: false },
     escapeHatch: {
       reason: INVITE_SIGNUP_COMPLETE_ESCAPE_HATCH_REASON,

package/src/auth-email-password/handlers/login.write.ts

@@ -257,9 +257,10 @@ export async function gateBuildSession(
 }
 
 // Login — unauthenticated entry point. The route is wired public (no JWT
-// middleware), synthesising a guest SessionUser for the handler's access
-// check. Everything inside the handler goes through ctx.queryAs(system, ...)
-// so the user feature stays the single owner of its table.
+// middleware), dispatching with the framework's anonymous identity for the
+// handler's access check. Everything inside the handler goes through
+// ctx.queryAs(system, ...) so the user feature stays the single owner of its
+// table.
 export function createLoginHandler(opts: LoginHandlerOptions = {}) {
   const strictVerification = opts.strictEmailVerification === true;
   const maxFailedAttempts =
@@ -273,7 +274,8 @@ export function createLoginHandler(opts: LoginHandlerOptions = {}) {
       email: z.email(),
       password: z.string().min(1),
     }),
-    access: { roles: ["all"] },
+    access: { roles: ["anonymous"] },
+    rateLimit: { per: "ip+handler", limit: 20, windowSeconds: 60 },
     escapeHatch: {
       reason:
         "Unauthenticated login has no caller identity yet — it looks up the user row by " +

package/src/auth-email-password/handlers/reset-password.write.ts

@@ -25,7 +25,8 @@ export function createResetPasswordHandler(opts: ResetPasswordOptions) {
       token: z.string().min(1),
       newPassword: passwordSchema,
     }),
-    access: { roles: ["all"] },
+    access: { roles: ["anonymous"] },
+    rateLimit: { per: "ip+handler", limit: 20, windowSeconds: 60 },
     escapeHatch: {
       reason:
         "Anonymous token holder has no session — runConfirmTokenFlow loads and updates the " +

package/src/auth-email-password/handlers/signup-confirm.write.ts

@@ -67,7 +67,8 @@ export function createSignupConfirmHandler() {
   return defineWriteHandler<"signup-confirm", typeof SignupConfirmSchema, SignupConfirmData>({
     name: "signup-confirm",
     schema: SignupConfirmSchema,
-    access: { roles: ["all"] },
+    access: { roles: ["anonymous"] },
+    rateLimit: { per: "ip+handler", limit: 20, windowSeconds: 60 },
     agent: { expose: false },
     escapeHatch: {
       reason: SIGNUP_CONFIRM_PROVISION_REASON,

package/src/auth-email-password/handlers/signup-request.write.ts

@@ -75,7 +75,8 @@ export function createSignupRequestHandler(opts: SignupRequestOptions) {
   return defineWriteHandler<"signup-request", typeof SignupRequestSchema, SignupRequestData>({
     name: "signup-request",
     schema: SignupRequestSchema,
-    access: { roles: ["all"] },
+    access: { roles: ["anonymous"] },
+    rateLimit: { per: "ip+handler", limit: 10, windowSeconds: 60 },
     description:
       "Starts magic-link self-registration by mailing a fresh activation link to an address and invalidating any link still outstanding for it; the answer looks the same whether or not the address is already registered.",
     handler: async (event, ctx) => {

package/src/auth-email-password/handlers/token-request-handler.ts

@@ -94,7 +94,8 @@ export function createTokenRequestHandler<TName extends string, TSuccessKind ext
   return defineWriteHandler<TName, typeof RequestTokenSchema, TokenRequestData<TSuccessKind>>({
     name: spec.handlerName,
     schema: RequestTokenSchema,
-    access: { roles: ["all"] },
+    access: { roles: ["anonymous"] },
+    rateLimit: { per: "ip+handler", limit: 10, windowSeconds: 60 },
     escapeHatch: {
       reason:
         "Anonymous requester has no session — looks up the target user by email via " +

package/src/auth-email-password/handlers/verify-email.write.ts

@@ -26,7 +26,8 @@ export function createVerifyEmailHandler(opts: VerifyEmailOptions) {
   return defineWriteHandler<"verify-email", typeof VerifyEmailSchema, VerifyEmailData>({
     name: "verify-email",
     schema: VerifyEmailSchema,
-    access: { roles: ["all"] },
+    access: { roles: ["anonymous"] },
+    rateLimit: { per: "ip+handler", limit: 20, windowSeconds: 60 },
     escapeHatch: {
       reason:
         "Anonymous token holder has no session — runConfirmTokenFlow loads and updates the " +

package/src/auth-email-password/i18n.ts

@@ -131,6 +131,13 @@ export const defaultTranslations: TranslationsByLocale = {
     "auth.inviteAccept.toggleExisting": "I already have an account",
     "auth.inviteAccept.missingToken": "The invitation link is missing or invalid.",
     "auth.inviteAccept.goToLogin": "Go to sign in",
+    "auth.sessionBootstrap.errorTitle": "Couldn't load your session",
+    "auth.sessionBootstrap.errorBody":
+      "The server could not be reached or returned an error. Please try again.",
+    "auth.sessionBootstrap.rateLimitedBody":
+      "Too many requests in a short time. Please wait a moment and try again.",
+    "auth.sessionBootstrap.retry": "Try again",
+    "auth.sessionBootstrap.retrying": "Retrying…",
     "auth.user.menu.label": "Account",
     "auth.user.menu.logout": "Sign out",
     "auth.tenant.switcher.label": "Tenant",

package/src/auth-email-password/web/__tests__/auth-client.test.ts

@@ -1,6 +1,7 @@
 import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
 import { CSRF_HEADER_NAME } from "@cosmicdrift/kumiko-dispatcher-live";
 import {
+  AuthRequestError,
   confirmAccountUnlock,
   confirmSignup,
   csrfHeader,
@@ -390,6 +391,29 @@ describe("fetchTenants", () => {
 
     await expect(fetchTenants()).rejects.toThrow("auth/tenants failed: 500");
   });
+
+  test("429 with Retry-After → AuthRequestError carries status + retryAfterSeconds", async () => {
+    globalThis.fetch = mock(
+      async () => new Response(null, { status: 429, headers: { "Retry-After": "7" } }),
+    ) as unknown as typeof fetch;
+
+    const err = await fetchTenants().catch((e: unknown) => e);
+
+    expect(err).toBeInstanceOf(AuthRequestError);
+    expect((err as AuthRequestError).status).toBe(429);
+    expect((err as AuthRequestError).retryAfterSeconds).toBe(7);
+  });
+
+  test("non-ok without Retry-After header → retryAfterSeconds is undefined", async () => {
+    globalThis.fetch = mock(
+      async () => new Response(null, { status: 500 }),
+    ) as unknown as typeof fetch;
+
+    const err = await fetchTenants().catch((e: unknown) => e);
+
+    expect(err).toBeInstanceOf(AuthRequestError);
+    expect((err as AuthRequestError).retryAfterSeconds).toBeUndefined();
+  });
 });
 
 describe("switchTenant", () => {

package/src/auth-email-password/web/__tests__/auth-gate.test.tsx

@@ -1,7 +1,15 @@
-import { describe, expect, mock, test } from "bun:test";
-import { fireEvent, screen, waitFor } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+import {
+  createStaticLocaleResolver,
+  LocaleProvider,
+  PrimitivesProvider,
+} from "@cosmicdrift/kumiko-renderer";
+import { defaultPrimitives } from "@cosmicdrift/kumiko-renderer-web";
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
 import type { ReactNode } from "react";
+import { defaultTranslations } from "../../i18n";
 import { createLoginRoute, makeAuthGate } from "../auth-gate";
+import { SessionProvider } from "../session";
 import { makeSessionApi, renderWithProviders } from "./test-utils";
 
 describe("makeAuthGate", () => {
@@ -236,3 +244,117 @@ describe("createLoginRoute", () => {
     );
   });
 });
+
+// Real SessionProvider (no mocked SessionContext) — proves the actual
+// bootstrap-failure wiring end to end: hasLikelyAuthSession → fetchTenants
+// throws → doRefresh catches → "error" status → SessionBootstrapErrorScreen.
+// Uses makeAuthGate + SessionProvider directly instead of makeSessionAuthGate:
+// client-plugin.test.tsx mocks makeSessionAuthGate process-wide via bun:test's
+// shared module registry, which would silently no-op it here too.
+describe("makeSessionAuthGate — session bootstrap failure", () => {
+  const resolver = createStaticLocaleResolver({ locale: "en" });
+  const originalFetch = globalThis.fetch;
+
+  function renderRealSession(ui: ReactNode) {
+    return render(
+      <PrimitivesProvider value={defaultPrimitives}>
+        <LocaleProvider resolver={resolver} fallbackBundles={[defaultTranslations]}>
+          <SessionProvider>{ui}</SessionProvider>
+        </LocaleProvider>
+      </PrimitivesProvider>,
+    );
+  }
+
+  beforeEach(() => {
+    document.cookie = "kumiko_csrf=gate-test-token";
+  });
+
+  afterEach(() => {
+    document.cookie = "kumiko_csrf=; expires=Thu, 01 Jan 1970 00:00:00 GMT; path=/";
+    globalThis.fetch = originalFetch;
+  });
+
+  test("429 on GET /auth/tenants → error screen with data-http-status=429, children not rendered; retry recovers", async () => {
+    let tenantsCalls = 0;
+    globalThis.fetch = mock(async (input: RequestInfo | URL) => {
+      const url = typeof input === "string" ? input : input.toString();
+      if (url === "/api/auth/tenants") {
+        tenantsCalls++;
+        if (tenantsCalls === 1) return new Response(null, { status: 429 });
+        return new Response(JSON.stringify({ tenants: [], activeTenantId: "t1" }), {
+          status: 200,
+        });
+      }
+      if (url === "/api/query") {
+        return new Response(
+          JSON.stringify({
+            data: { id: "u1", email: "u@example.com", displayName: "U", roles: "[]" },
+          }),
+          { status: 200 },
+        );
+      }
+      return new Response(null, { status: 404 });
+    }) as unknown as typeof fetch;
+
+    const Gate = makeAuthGate();
+    renderRealSession(
+      <Gate>
+        <div data-testid="protected">secret</div>
+      </Gate>,
+    );
+
+    const errorScreen = await waitFor(() => screen.getByTestId("session-bootstrap-error"));
+    expect(errorScreen.getAttribute("data-http-status")).toBe("429");
+    expect(screen.queryByTestId("protected")).toBeNull();
+
+    fireEvent.click(screen.getByRole("button", { name: "Try again" }));
+
+    await waitFor(() => {
+      expect(screen.getByTestId("protected")).toBeTruthy();
+    });
+    expect(tenantsCalls).toBe(2);
+  });
+
+  test("500 on POST /api/query (user:me) → error screen with data-http-status=500, children not rendered", async () => {
+    globalThis.fetch = mock(async (input: RequestInfo | URL) => {
+      const url = typeof input === "string" ? input : input.toString();
+      if (url === "/api/auth/tenants") {
+        return new Response(JSON.stringify({ tenants: [], activeTenantId: "t1" }), {
+          status: 200,
+        });
+      }
+      if (url === "/api/query") {
+        return new Response(null, { status: 500 });
+      }
+      return new Response(null, { status: 404 });
+    }) as unknown as typeof fetch;
+
+    const Gate = makeAuthGate();
+    renderRealSession(
+      <Gate>
+        <div data-testid="protected">secret</div>
+      </Gate>,
+    );
+
+    const errorScreen = await waitFor(() => screen.getByTestId("session-bootstrap-error"));
+    expect(errorScreen.getAttribute("data-http-status")).toBe("500");
+    expect(screen.queryByTestId("protected")).toBeNull();
+  });
+
+  test("network failure on GET /auth/tenants → error screen with data-http-status=network", async () => {
+    globalThis.fetch = mock(async () => {
+      throw new TypeError("Failed to fetch");
+    }) as unknown as typeof fetch;
+
+    const Gate = makeAuthGate();
+    renderRealSession(
+      <Gate>
+        <div data-testid="protected">secret</div>
+      </Gate>,
+    );
+
+    const errorScreen = await waitFor(() => screen.getByTestId("session-bootstrap-error"));
+    expect(errorScreen.getAttribute("data-http-status")).toBe("network");
+    expect(screen.queryByTestId("protected")).toBeNull();
+  });
+});

package/src/auth-email-password/web/__tests__/session-bootstrap-error.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, test } from "bun:test";
+import type { SessionBootstrapFailure } from "../session";
+import { retryDelayMs } from "../session-bootstrap-error";
+
+describe("retryDelayMs", () => {
+  test("Retry-After not yet elapsed → remaining delay in ms", () => {
+    const failure: SessionBootstrapFailure = {
+      httpStatus: 429,
+      retryAfterSeconds: 11,
+      failedAtEpochMs: 1000,
+    };
+    expect(retryDelayMs(failure, 3000)).toBe(9000);
+  });
+
+  test("Retry-After already elapsed → 0, never negative", () => {
+    const failure: SessionBootstrapFailure = {
+      httpStatus: 429,
+      retryAfterSeconds: 11,
+      failedAtEpochMs: 1000,
+    };
+    expect(retryDelayMs(failure, 20_000)).toBe(0);
+  });
+
+  test("no retryAfterSeconds → 0 (retry immediately)", () => {
+    const failure: SessionBootstrapFailure = {
+      httpStatus: 500,
+      retryAfterSeconds: null,
+      failedAtEpochMs: 1000,
+    };
+    expect(retryDelayMs(failure, 1000)).toBe(0);
+  });
+});

package/src/auth-email-password/web/__tests__/test-utils.tsx

@@ -41,6 +41,7 @@ export function makeSessionApi(overrides: MakeSessionApiOptions = {}): SessionAp
     activeTenantId: "tenant-1",
     tenants: [{ tenantId: "tenant-1", roles: ["Admin"] }],
     roles: ["Admin"],
+    bootstrapFailure: null,
     ...stateOverrides,
   };
   return {

package/src/auth-email-password/web/auth-client.ts

@@ -62,6 +62,26 @@ export function csrfHeader(): Record<string, string> {
   return token !== undefined ? { [CSRF_HEADER_NAME]: token } : {};
 }
 
+// Thrown by fetchTenants/fetchCurrentUser on a non-401 error status, distinguishable from a plain network failure by its status field.
+export class AuthRequestError extends Error {
+  readonly status: number;
+  readonly retryAfterSeconds: number | undefined;
+
+  constructor(message: string, status: number, retryAfterSeconds: number | undefined) {
+    super(message);
+    this.name = "AuthRequestError";
+    this.status = status;
+    this.retryAfterSeconds = retryAfterSeconds;
+  }
+}
+
+// Only a non-negative integer second count is usable; anything else is treated as absent.
+export function parseRetryAfterSeconds(header: string | null): number | undefined {
+  if (header === null) return undefined;
+  if (!/^\d+$/.test(header)) return undefined;
+  return Number(header);
+}
+
 // LoginResult mirrors the two-step login contract auth-routes.ts owns: a
 // straight success, an MFA challenge (auth-mfa mints the token), an
 // MFA-setup-required block (enforcement policy blocks an unenrolled user),
@@ -344,7 +364,13 @@ export async function fetchTenants(): Promise<{
     credentials: "same-origin",
   });
   if (res.status === 401) return null;
-  if (!res.ok) throw new Error(`auth/tenants failed: ${res.status}`);
+  if (!res.ok) {
+    throw new AuthRequestError(
+      `auth/tenants failed: ${res.status}`,
+      res.status,
+      parseRetryAfterSeconds(res.headers.get("Retry-After")),
+    );
+  }
   // @cast-boundary engine-payload — HTTP-API contract, server-side schema-validated
   return (await res.json()) as {
     tenants: readonly TenantSummary[];
@@ -392,7 +418,13 @@ export async function fetchCurrentUser(): Promise<CurrentUserProfile | null> {
     body: JSON.stringify({ type: "user:query:user:me", payload: {} }),
   });
   if (res.status === 401) return null;
-  if (!res.ok) throw new Error(`user:me failed: ${res.status}`);
+  if (!res.ok) {
+    throw new AuthRequestError(
+      `user:me failed: ${res.status}`,
+      res.status,
+      parseRetryAfterSeconds(res.headers.get("Retry-After")),
+    );
+  }
   // @cast-boundary engine-payload — HTTP-API contract, server-side schema-validated
   const body = (await res.json()) as {
     data?: {

package/src/auth-email-password/web/auth-gate.tsx

@@ -12,6 +12,7 @@
 import { type ComponentType, type ReactNode, useEffect, useState } from "react";
 import { LoginScreen, type LoginScreenProps } from "./login-screen";
 import { SessionProvider, useSession } from "./session";
+import { SessionBootstrapErrorScreen } from "./session-bootstrap-error";
 
 // Generic — NOT auth-mfa's MfaVerifyScreenProps directly, so this feature
 // stays unaware of auth-mfa's concrete shape (same coupling direction as
@@ -65,7 +66,7 @@ export function createLoginRoute(
   const MfaSetupComponent = opts.mfaSetupScreen;
 
   function LoginRoute(): ReactNode {
-    const { status, refresh } = useSession();
+    const { status, refresh, bootstrapFailure } = useSession();
     const { onAuthenticated } = opts;
     // Pending challenge-token from LoginScreen's onMfaChallenge. Lives here
     // (not in SessionState) because it's a UI-only transition — the server
@@ -86,6 +87,9 @@ export function createLoginRoute(
         <div className="min-h-screen flex items-center justify-center text-muted-foreground text-sm" />
       );
     }
+    if (status === "error" && bootstrapFailure !== null) {
+      return <SessionBootstrapErrorScreen failure={bootstrapFailure} onRetry={refresh} />;
+    }
     // A standalone mount (no parent gate, no onAuthenticated wired — e.g. an
     // apex/marketing surface that just places <LoginRoute /> directly) has no
     // way to navigate away once authenticated. Blanking the page there is a

package/src/auth-email-password/web/index.ts

@@ -18,6 +18,7 @@ export type {
   VerifyEmailFailure,
 } from "./auth-client";
 export {
+  AuthRequestError,
   confirmAccountUnlock,
   confirmSignup,
   requestAccountUnlock,
@@ -54,8 +55,10 @@ export type { RequestAccountUnlockScreenProps } from "./request-account-unlock-s
 export { RequestAccountUnlockScreen } from "./request-account-unlock-screen";
 export type { ResetPasswordScreenProps } from "./reset-password-screen";
 export { ResetPasswordScreen } from "./reset-password-screen";
-export type { SessionApi, SessionState, SessionStatus } from "./session";
+export type { SessionApi, SessionBootstrapFailure, SessionState, SessionStatus } from "./session";
 export { hasLikelyAuthSession, SessionContext, SessionProvider, useSession } from "./session";
+export type { SessionBootstrapErrorScreenProps } from "./session-bootstrap-error";
+export { retryDelayMs, SessionBootstrapErrorScreen } from "./session-bootstrap-error";
 export type { SignupCompleteScreenProps } from "./signup-complete-screen";
 export { SignupCompleteScreen } from "./signup-complete-screen";
 export type { SignupScreenProps } from "./signup-screen";

package/src/auth-email-password/web/session-bootstrap-error.tsx

@@ -0,0 +1,56 @@
+// @runtime client
+// Rendered by auth-gate's LoginRoute when the session bootstrap failed for a reason other than "not logged in".
+
+import { usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { type ReactNode, useState } from "react";
+import { AuthCard } from "./auth-form-primitives";
+import type { SessionBootstrapFailure } from "./session";
+
+export type SessionBootstrapErrorScreenProps = {
+  readonly failure: SessionBootstrapFailure;
+  readonly onRetry: () => Promise<void>;
+};
+
+/** Retry delay measured from failure time, not click time. */
+export function retryDelayMs(failure: SessionBootstrapFailure, nowEpochMs: number): number {
+  const retryAfterMs = (failure.retryAfterSeconds ?? 0) * 1000;
+  return Math.max(0, failure.failedAtEpochMs + retryAfterMs - nowEpochMs);
+}
+
+function wait(ms: number): Promise<void> {
+  if (ms <= 0) return Promise.resolve();
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export function SessionBootstrapErrorScreen({
+  failure,
+  onRetry,
+}: SessionBootstrapErrorScreenProps): ReactNode {
+  const t = useTranslation();
+  const { Banner, Button } = usePrimitives();
+  const [retrying, setRetrying] = useState(false);
+
+  const handleRetry = (): void => {
+    setRetrying(true);
+    void wait(retryDelayMs(failure, Date.now()))
+      .then(onRetry)
+      .then(() => setRetrying(false));
+  };
+
+  return (
+    <div data-testid="session-bootstrap-error" data-http-status={failure.httpStatus ?? "network"}>
+      <AuthCard title={t("auth.sessionBootstrap.errorTitle")}>
+        <div className="flex flex-col gap-4 px-6 pb-4">
+          <Banner variant="error">
+            {failure.httpStatus === 429
+              ? t("auth.sessionBootstrap.rateLimitedBody")
+              : t("auth.sessionBootstrap.errorBody")}
+          </Banner>
+          <Button variant="primary" onClick={handleRetry} disabled={retrying}>
+            {retrying ? t("auth.sessionBootstrap.retrying") : t("auth.sessionBootstrap.retry")}
+          </Button>
+        </div>
+      </AuthCard>
+    </div>
+  );
+}

package/src/auth-email-password/web/session.tsx

@@ -12,6 +12,7 @@
 import { readCsrfToken } from "@cosmicdrift/kumiko-dispatcher-live";
 import { createContext, type ReactNode, useCallback, useContext, useEffect, useState } from "react";
 import {
+  AuthRequestError,
   type CurrentUserProfile,
   fetchCurrentUser,
   fetchTenants,
@@ -23,7 +24,14 @@ import {
   type TenantSummary,
 } from "./auth-client";
 
-export type SessionStatus = "loading" | "unauthenticated" | "authenticated";
+export type SessionStatus = "loading" | "unauthenticated" | "authenticated" | "error";
+
+// httpStatus null means the fetch itself threw (offline/DNS/CORS), not that the server answered.
+export type SessionBootstrapFailure = {
+  readonly httpStatus: number | null;
+  readonly retryAfterSeconds: number | null;
+  readonly failedAtEpochMs: number;
+};
 
 export type SessionState = {
   readonly status: SessionStatus;
@@ -36,6 +44,7 @@ export type SessionState = {
    *  Client computed dieselbe merge-Logik aus user.globalRoles +
    *  tenants[active].roles damit nav-filtering greift. Dedupliziert. */
   readonly roles: readonly string[];
+  readonly bootstrapFailure: SessionBootstrapFailure | null;
 };
 
 export type SessionApi = SessionState & {
@@ -58,6 +67,7 @@ export const UNAUTHENTICATED: SessionState = {
   activeTenantId: null,
   tenants: [],
   roles: [],
+  bootstrapFailure: null,
 };
 
 const INITIAL: SessionState = {
@@ -66,6 +76,7 @@ const INITIAL: SessionState = {
   activeTenantId: null,
   tenants: [],
   roles: [],
+  bootstrapFailure: null,
 };
 
 // kumiko_auth ist HttpOnly — kumiko_csrf wird beim Login gemeinsam gesetzt.
@@ -117,15 +128,33 @@ async function refresh(): Promise<SessionState> {
     activeTenantId: tenants.activeTenantId,
     tenants: tenants.tenants,
     roles: computeActiveRoles(user, tenants.activeTenantId, tenants.tenants),
+    bootstrapFailure: null,
   };
 }
 
+// Non-AuthRequestError throws (offline, DNS, CORS) have no status, so httpStatus stays null.
+function toBootstrapFailure(err: unknown): SessionBootstrapFailure {
+  if (err instanceof AuthRequestError) {
+    return {
+      httpStatus: err.status,
+      retryAfterSeconds: err.retryAfterSeconds ?? null,
+      failedAtEpochMs: Date.now(),
+    };
+  }
+  return { httpStatus: null, retryAfterSeconds: null, failedAtEpochMs: Date.now() };
+}
+
 export function SessionProvider({ children }: { readonly children: ReactNode }): ReactNode {
   const [state, setState] = useState<SessionState>(INITIAL);
 
+  // Never rejects, so bootstrap can't strand the UI on "loading" forever.
   const doRefresh = useCallback(async () => {
-    const next = await refresh();
-    setState(next);
+    try {
+      const next = await refresh();
+      setState(next);
+    } catch (err) {
+      setState({ ...UNAUTHENTICATED, status: "error", bootstrapFailure: toBootstrapFailure(err) });
+    }
   }, []);
 
   // kumiko-lint-ignore no-raw-hooks Phase-3 conversion tracked in #2312

package/src/auth-mfa/__tests__/no-redis.integration.test.ts

@@ -14,6 +14,7 @@ import {
   createTenantDb,
 } from "@cosmicdrift/kumiko-framework/db";
 import {
+  createAnonymousUser,
   type SessionUser,
   SYSTEM_TENANT_ID,
   type TenantId,
@@ -45,14 +46,10 @@ const CHALLENGE_TOKEN_SECRET = "no-redis-test-challenge-token-secret-not-real-00
 const SETUP_TOKEN_SECRET = "no-redis-test-setup-token-secret-not-real-0002";
 const TENANT_ID: TenantId = testTenantId(421);
 
-// Mirrors framework's auth-routes.ts GUEST_USER — verify/enable-confirm-preauth
-// are guest-callable (access: { roles: ["all"] }), the real identity comes
+// Mirrors framework's auth-routes.ts anonymous dispatch — verify/enable-confirm-preauth
+// are guest-callable (access: { roles: ["anonymous"] }), the real identity comes
 // entirely from the signed token, not from this dispatch-level user.
-const GUEST_USER: SessionUser = {
-  id: "00000000-0000-0000-0000-000000000000",
-  tenantId: SYSTEM_TENANT_ID,
-  roles: ["all"],
-};
+const ANONYMOUS_USER: SessionUser = createAnonymousUser(SYSTEM_TENANT_ID);
 
 beforeAll(async () => {
   const encryption = createTestEnvelopeCipher(randomBytes(32).toString("base64"));
@@ -125,7 +122,7 @@ describe("auth-mfa handlers — ctx.redis unset (#1467)", () => {
     const err = await stack.http.writeErr(
       AuthMfaHandlers.verify,
       { challengeToken: token, code: "123456" },
-      GUEST_USER,
+      ANONYMOUS_USER,
     );
     expect(err.httpStatus).toBeGreaterThanOrEqual(500);
     expect(err.code).toBe("internal_error");
@@ -148,7 +145,7 @@ describe("auth-mfa handlers — ctx.redis unset (#1467)", () => {
     const err = await stack.http.writeErr(
       AuthMfaHandlers.enableConfirmPreauth,
       { setupToken: token, code: "123456" },
-      GUEST_USER,
+      ANONYMOUS_USER,
     );
     expect(err.httpStatus).toBeGreaterThanOrEqual(500);
     expect(err.code).toBe("internal_error");

package/src/auth-mfa/__tests__/verify.integration.test.ts

@@ -44,14 +44,14 @@ let stack: TestStack;
 const SETUP_TOKEN_SECRET = "test-mfa-setup-secret-at-least-32-bytes-long!!";
 const CHALLENGE_TOKEN_SECRET = "test-mfa-challenge-secret-at-least-32-bytes!!";
 
-// Handler access is `{ roles: ["all"] }`, matching how the framework route
-// dispatches with a guest identity — a literal here is enough since the
-// handler derives everything from the challenge-token payload, not from
-// event.user.
+// Handler access is `{ roles: ["anonymous"] }`, matching how the framework
+// route dispatches with the anonymous identity — a literal here is enough
+// since the handler derives everything from the challenge-token payload,
+// not from event.user.
 const GUEST: SessionUser = {
-  id: "00000000-0000-0000-0000-000000000000",
+  id: "anonymous",
   tenantId: "00000000-0000-4000-8000-000000000001" as TenantId,
-  roles: ["all"],
+  roles: ["anonymous"],
 };
 
 beforeAll(async () => {

package/src/auth-mfa/handlers/enable-confirm-preauth.write.ts

@@ -63,7 +63,8 @@ export function createEnableConfirmPreauthHandler(opts: EnableConfirmPreauthOpti
       setupToken: z.string().min(1),
       code: z.string().length(6),
     }),
-    access: { roles: ["all"] },
+    access: { roles: ["anonymous"] },
+    rateLimit: { per: "ip+handler", limit: 20, windowSeconds: 60 },
     escapeHatch: {
       reason:
         "Pre-auth MFA enrollment step has no session yet — re-checks status via ctx.queryAs(SYSTEM, " +
@@ -86,7 +87,7 @@ export function createEnableConfirmPreauthHandler(opts: EnableConfirmPreauthOpti
       if (tenantId === undefined) return invalidSetupToken();
 
       // Fail closed: unlike verify.write.ts/enable-confirm.write.ts, this
-      // endpoint has NO gate before it (access: { roles: ["all"] }, no JWT,
+      // endpoint has NO gate before it (access: { roles: ["anonymous"] }, no JWT,
       // no prior challenge-token from a successful login) — its only secret
       // is a 6-digit TOTP code. Silently skipping the brute-force cap and
       // single-use burn when ctx.redis is absent would let the setup token

package/src/auth-mfa/handlers/enable-start-preauth.write.ts

@@ -29,7 +29,8 @@ export type EnableStartPreauthOptions = {
 // preauthSetupToken (minted by login.write.ts when enforcement policy
 // blocks an unenrolled user), not from event.user — there is no session at
 // this point. Runs pre-session the same way verify.write.ts does (dispatched
-// by the framework's /auth/mfa/preauth-enable-start route with GUEST_USER).
+// by the framework's /auth/mfa/preauth-enable-start route with the
+// anonymous identity).
 export function createEnableStartPreauthHandler(opts: EnableStartPreauthOptions) {
   return defineWriteHandler({
     name: "enable-start-preauth",
@@ -37,7 +38,8 @@ export function createEnableStartPreauthHandler(opts: EnableStartPreauthOptions)
       preauthSetupToken: z.string().min(1),
       accountLabel: z.string().min(1).max(200),
     }),
-    access: { roles: ["all"] },
+    access: { roles: ["anonymous"] },
+    rateLimit: { per: "ip+handler", limit: 10, windowSeconds: 60 },
     description:
       "Begins TOTP enrollment for a user whose sign-in was blocked because the tenant requires two-factor authentication, taking identity from the pre-auth token login issued instead of from a session.",
     // Same secret-bearing result as enable-start.

package/src/auth-mfa/handlers/verify.write.ts

@@ -35,7 +35,7 @@ const executor = createEventStoreExecutor(userMfaTable, userMfaEntity, {
 });
 
 // Completes the two-step login. Runs pre-session (dispatched by the
-// framework's /auth/mfa/verify route with a guest identity, same as
+// framework's /auth/mfa/verify route with the anonymous identity, same as
 // login.write.ts) — everything it needs (which user, which tenant) comes
 // from the challenge token, not from an authenticated caller.
 export function createMfaVerifyHandler(opts: MfaVerifyOptions) {
@@ -45,7 +45,8 @@ export function createMfaVerifyHandler(opts: MfaVerifyOptions) {
   return defineWriteHandler({
     name: "verify",
     schema: z.object({ challengeToken: z.string().min(1), code: z.string().min(6).max(9) }),
-    access: { roles: ["all"] },
+    access: { roles: ["anonymous"] },
+    rateLimit: { per: "ip+handler", limit: 20, windowSeconds: 60 },
     escapeHatch: {
       reason:
         "Pre-auth MFA step has no session yet — re-derives it via ctx.queryAs(SYSTEM, " +

package/src/auth-mfa/mfa-status-checker.ts

@@ -65,8 +65,8 @@ export function createMfaStatusChecker(opts: {
       return { required: true, challengeToken: token };
     }
 
-    // ctx.config is bound to the CALLING user's tenant (GUEST_USER for
-    // login) — wrong tenant here. ctx.configResolver takes tenantId
+    // ctx.config is bound to the CALLING user's tenant (the anonymous
+    // identity's tenant for login) — wrong tenant here. ctx.configResolver takes tenantId
     // explicitly, which is what a pre-session check against the LOGGING-IN
     // user's tenant needs.
     // @cast-boundary engine-payload — "select" config values are validated

package/src/billing-foundation/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.301.0",
+    "type": "breaking",
+    "title": "billing-foundation no longer exports SystemWriteResult (removed in 0.298.0 without a changelog note)",
+    "migration": "SystemWriteResult was exported from @cosmicdrift/kumiko-bundled-features/billing-foundation up to 0.297.0 and was dropped in 0.298.0 together with the dispatchSystemWrite dep of createSubscriptionTierSync; there is no alias. Code that still imports it fails with \"has no exported member 'SystemWriteResult'\". If the type is only used for a dispatchSystemWrite dep passed to createSubscriptionTierSync, drop that dep and the type together (see the 0.298.0 webhook-wiring migration: extraRoutes: [createSubscriptionTierSync({ ... }).createWebhookRoute()]). Where a system-write result type is still needed, import type { WriteResult } from \"@cosmicdrift/kumiko-framework/engine\" and use WriteResult<unknown>; it is a discriminated union ({ isSuccess: true; data } | WriteFailure), so narrow on isSuccess before reading data or error."
+  },
   {
     "version": "0.298.0",
     "type": "breaking",