@cosmicdrift/kumiko-bundled-features 0.304.0 → 0.305.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.304.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.304.0",
-    "@cosmicdrift/kumiko-framework": "0.304.0",
-    "@cosmicdrift/kumiko-headless": "0.304.0",
-    "@cosmicdrift/kumiko-renderer": "0.304.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.304.0",
-    "@cosmicdrift/kumiko-types": "0.304.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.304.0",
-    "@cosmicdrift/kumiko-locale-es": "0.304.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/changes.json

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

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