@cosmicdrift/kumiko-bundled-features 0.304.0 → 0.306.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.304.0",
+  "version": "0.306.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.306.0",
+    "@cosmicdrift/kumiko-framework": "0.306.0",
+    "@cosmicdrift/kumiko-headless": "0.306.0",
+    "@cosmicdrift/kumiko-renderer": "0.306.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.306.0",
+    "@cosmicdrift/kumiko-types": "0.306.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.306.0",
+    "@cosmicdrift/kumiko-locale-es": "0.306.0",
     "jsqr": "^1.4.0"
   }
 }

package/src/__tests__/extension-points-typed.test.ts

@@ -0,0 +1,135 @@
+// Ratchet: every extension point a bundled feature declares via
+// `r.extendsRegistrar` and whose options are actually read somewhere must be
+// entered into `KumikoExtensionOptionsMap` — see extension-options-map.ts.
+// New points either join TYPED_EXTENSION_POINTS (with the map augmentation)
+// or UNTYPED_BY_DESIGN (with a reason). Anything else fails this test.
+
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import type { KumikoExtensionOptionsMap } from "@cosmicdrift/kumiko-types/extension-options-map";
+import { authFoundationFeature } from "../auth-foundation/feature";
+import { billingFoundationFeature } from "../billing-foundation/feature";
+import { createCustomFieldsFeature } from "../custom-fields/feature";
+import { createDeliveryFeature } from "../delivery/feature";
+import { createFileDerivativesFeature } from "../file-derivatives/feature";
+import { fileFoundationFeature } from "../file-foundation/feature";
+import { inboundMailFoundationFeature } from "../inbound-mail-foundation/feature";
+import { mailFoundationFeature } from "../mail-foundation/feature";
+import { createRendererFoundationFeature } from "../renderer-foundation/feature";
+import { createTenantLifecycleFeature } from "../tenant-lifecycle/feature";
+import { createTierEngineFeature } from "../tier-engine/feature";
+import { createUserFeature } from "../user/feature";
+import { createUserDataRightsFeature } from "../user-data-rights/feature";
+
+const TYPED_EXTENSION_POINTS = [
+  "userData",
+  "tenantData",
+  "storageProvider",
+  "searchAdapter",
+  "externalResource",
+  "infraResource",
+  "fileProvider",
+  "derivativeRenderer",
+  "derivativeOverlayResolver",
+  "derivativePublicPredicate",
+  "principalStatus",
+  "tenantLifecycleStatus",
+  "tenantTierResolver",
+  "tokenVerifier",
+  "sessionStore",
+  "tenantResolver",
+  "tenantExistence",
+  "inboundMailProvider",
+  "renderer",
+  "deliveryChannel",
+  "subscriptionProvider",
+  "mailTransport",
+] as const satisfies readonly (keyof KumikoExtensionOptionsMap)[];
+
+const UNTYPED_BY_DESIGN: Record<string, string> = {
+  customFields: "opt-in marker only — registered options are never read",
+};
+
+// Owner-directories that declare at least one extension point via
+// `r.extendsRegistrar` — one entry per feature composed in
+// allRegistrarExtensionNames() below. Catches a new feature that starts
+// calling r.extendsRegistrar without being added to that composition list.
+const DECLARING_FEATURE_DIRS = [
+  "auth-foundation",
+  "billing-foundation",
+  "custom-fields",
+  "delivery",
+  "file-derivatives",
+  "file-foundation",
+  "inbound-mail-foundation",
+  "mail-foundation",
+  "renderer-foundation",
+  "tenant-lifecycle",
+  "tier-engine",
+  "user",
+  "user-data-rights",
+].sort();
+
+// Scans bundled-features source (excluding tests) for real `r.extendsRegistrar(`
+// call sites, ignoring occurrences inside line comments (e.g. a doc-comment
+// mentioning the call). Returns the sorted, deduped set of owning top-level
+// directories under packages/bundled-features/src.
+function scanExtendsRegistrarOwnerDirs(): readonly string[] {
+  const srcDir = new URL("..", import.meta.url).pathname;
+  const glob = new Bun.Glob("**/*.ts");
+  const owners = new Set<string>();
+  for (const relPath of glob.scanSync({ cwd: srcDir, onlyFiles: true })) {
+    if (relPath.includes("__tests__/") || relPath.endsWith(".test.ts")) continue;
+    const contents = readFileSync(`${srcDir}${relPath}`, "utf8");
+    const hasRealCall = contents
+      .split("\n")
+      .some((line) => line.split("//")[0]?.includes("r.extendsRegistrar("));
+    if (!hasRealCall) continue;
+    const topLevelDir = relPath.split("/")[0];
+    if (topLevelDir) owners.add(topLevelDir);
+  }
+  return [...owners].sort();
+}
+
+function allRegistrarExtensionNames(): readonly string[] {
+  const features = [
+    authFoundationFeature,
+    billingFoundationFeature,
+    createCustomFieldsFeature(),
+    createDeliveryFeature(),
+    createFileDerivativesFeature(),
+    fileFoundationFeature,
+    inboundMailFoundationFeature,
+    mailFoundationFeature,
+    createRendererFoundationFeature(),
+    createTenantLifecycleFeature(),
+    createTierEngineFeature(),
+    createUserFeature(),
+    createUserDataRightsFeature(),
+  ];
+  const names = new Set<string>();
+  for (const feature of features) {
+    for (const name of Object.keys(feature.registrarExtensions)) {
+      names.add(name);
+    }
+  }
+  return [...names];
+}
+
+describe("extension-points-typed ratchet", () => {
+  test("every declared extension point is either typed or explicitly untyped-by-design", () => {
+    const declared = allRegistrarExtensionNames();
+    const known = new Set<string>([...TYPED_EXTENSION_POINTS, ...Object.keys(UNTYPED_BY_DESIGN)]);
+    const unaccounted = declared.filter((name) => !known.has(name));
+    expect(unaccounted).toEqual([]);
+  });
+
+  test("TYPED_EXTENSION_POINTS and UNTYPED_BY_DESIGN don't overlap", () => {
+    const overlap = TYPED_EXTENSION_POINTS.filter((name) => name in UNTYPED_BY_DESIGN);
+    expect(overlap).toEqual([]);
+  });
+
+  test("every directory that calls r.extendsRegistrar is composed into allRegistrarExtensionNames", () => {
+    expect(scanExtendsRegistrarOwnerDirs()).toEqual(DECLARING_FEATURE_DIRS);
+  });
+});

package/src/__tests__/use-extension-options.test.ts

@@ -0,0 +1,278 @@
+// Imports only via package specifiers so the KumikoExtensionOptionsMap augmentation is proven to reach
+// consumers. Each @ts-expect-error has a positive control next to it, so an unrelated error cannot satisfy it.
+import { expect, expectTypeOf, test } from "bun:test";
+import { MAIL_TRANSPORT_EXTENSION } from "@cosmicdrift/kumiko-bundled-features/mail-foundation";
+import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import {
+  defineFeature,
+  EXT_STORAGE_PROVIDER,
+  EXT_TENANT_DATA,
+  EXT_USER_DATA,
+  type ExtensionOptionsArgs,
+  type ExtensionOptionsFor,
+  type TenantDataDestroyHook,
+  type TenantDataHookCtx,
+  type TenantId,
+  type TenantResourceDestroyHook,
+  type TenantResourceHookCtx,
+  type UserDataDeleteHook,
+  type UserDataDeleteStrategy,
+  type UserDataExportHook,
+  type UserDataHookCtx,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+test("useExtension accepts a well-typed tenantData destroy hook", () => {
+  defineFeature("probe-tenant-data-ok", (r) => {
+    r.useExtension(EXT_TENANT_DATA, "x", {
+      destroy: async (ctx: TenantDataHookCtx) => {
+        expectTypeOf(ctx.db).not.toBeAny();
+      },
+    });
+  });
+});
+
+test("useExtension rejects a tenantData destroy hook with the #3196 wrong ctx shape", () => {
+  defineFeature("probe-tenant-data-wrong-ctx", (r) => {
+    r.useExtension(EXT_TENANT_DATA, "x", {
+      // @ts-expect-error #3196: destroy ctx must be TenantDataHookCtx, not a hand-rolled { db: DbRunner; tenantId } — TenantDb is not a DbRunner.
+      destroy: async (_ctx: { readonly db: DbRunner; readonly tenantId: TenantId }) => {},
+    });
+  });
+  expectTypeOf<
+    (ctx: { readonly db: DbRunner; readonly tenantId: TenantId }) => Promise<void>
+  >().not.toExtend<TenantDataDestroyHook>();
+});
+
+test("useExtension requires options for a known extension name — omitting them is a type error", () => {
+  defineFeature("probe-tenant-data-missing-options", (r) => {
+    // @ts-expect-error tenantData's options are mandatory — a bare (name, entity) call registered no hook, silently.
+    r.useExtension(EXT_TENANT_DATA, "x");
+  });
+  expectTypeOf<[]>().not.toExtend<ExtensionOptionsArgs<typeof EXT_TENANT_DATA>>();
+});
+
+test("useExtension infers the destroy hook's ctx type from context (positional form, no annotation)", () => {
+  defineFeature("probe-tenant-data-contextual", (r) => {
+    r.useExtension(EXT_TENANT_DATA, "x", {
+      destroy: async (ctx) => {
+        expectTypeOf(ctx).toEqualTypeOf<TenantDataHookCtx>();
+      },
+    });
+  });
+});
+
+test("useExtension's object form accepts a well-typed tenantData destroy hook", () => {
+  defineFeature("probe-tenant-data-object-form-ok", (r) => {
+    r.useExtension({
+      name: EXT_TENANT_DATA,
+      entity: "x",
+      destroy: async (ctx: TenantDataHookCtx) => {
+        expectTypeOf(ctx.tenantId).toBeString();
+      },
+    });
+  });
+});
+
+test("useExtension's object form rejects the #3196 wrong ctx shape", () => {
+  defineFeature("probe-tenant-data-object-form-wrong-ctx", (r) => {
+    r.useExtension({
+      name: EXT_TENANT_DATA,
+      entity: "x",
+      // @ts-expect-error #3196: same mismatch as the positional form above.
+      destroy: async (_ctx: { readonly db: DbRunner; readonly tenantId: TenantId }) => {},
+    });
+  });
+  expectTypeOf<
+    (ctx: { readonly db: DbRunner; readonly tenantId: TenantId }) => Promise<void>
+  >().not.toExtend<TenantDataDestroyHook>();
+});
+
+test("useExtension's object form infers the destroy hook's ctx type from context (no annotation)", () => {
+  defineFeature("probe-tenant-data-object-form-contextual", (r) => {
+    r.useExtension({
+      name: EXT_TENANT_DATA,
+      entity: "x",
+      destroy: async (ctx) => {
+        expectTypeOf(ctx).toEqualTypeOf<TenantDataHookCtx>();
+      },
+    });
+  });
+});
+
+test("useExtension accepts a tenantData registration with escapeHatch", () => {
+  const feature = defineFeature("probe-tenant-data-escape-hatch", (r) => {
+    r.useExtension(EXT_TENANT_DATA, "x", {
+      destroy: async (_ctx: TenantDataHookCtx) => {},
+      escapeHatch: { reason: "needs raw SQL for a batch delete" },
+    });
+  });
+  expect(feature.extensionUsages).toContainEqual(
+    expect.objectContaining({
+      extensionName: EXT_TENANT_DATA,
+      entityName: "x",
+      options: expect.objectContaining({
+        escapeHatch: { reason: "needs raw SQL for a batch delete" },
+      }),
+    }),
+  );
+});
+
+test("useExtension accepts export-only userData registration (#972)", () => {
+  const exportHook: UserDataExportHook = async (_ctx) => null;
+  const feature = defineFeature("probe-user-data-export-only", (r) => {
+    r.useExtension(EXT_USER_DATA, "x", { export: exportHook });
+  });
+  expect(feature.extensionUsages).toContainEqual(
+    expect.objectContaining({
+      extensionName: EXT_USER_DATA,
+      entityName: "x",
+      options: expect.objectContaining({ export: exportHook }),
+    }),
+  );
+});
+
+test("useExtension rejects a userData export hook with the wrong ctx shape", () => {
+  defineFeature("probe-user-data-wrong-ctx", (r) => {
+    r.useExtension(EXT_USER_DATA, "x", {
+      // @ts-expect-error export ctx must be UserDataHookCtx (ctx.db: TenantDb), not a hand-rolled { db: DbRunner; userId }.
+      export: async (_ctx: { readonly db: DbRunner; readonly userId: string }) => null,
+    });
+  });
+  expectTypeOf<
+    (ctx: { readonly db: DbRunner; readonly userId: string }) => Promise<null>
+  >().not.toExtend<UserDataExportHook>();
+});
+
+test("useExtension accepts delete-only userData registration with order", () => {
+  const deleteHook: UserDataDeleteHook = async (_ctx, _strategy) => undefined;
+  const feature = defineFeature("probe-user-data-delete-only", (r) => {
+    r.useExtension(EXT_USER_DATA, "x", { delete: deleteHook, order: 1 });
+  });
+  expect(feature.extensionUsages).toContainEqual(
+    expect.objectContaining({
+      extensionName: EXT_USER_DATA,
+      entityName: "x",
+      options: expect.objectContaining({ delete: deleteHook, order: 1 }),
+    }),
+  );
+});
+
+test("useExtension infers the delete hook's ctx/strategy types from context (no annotation)", () => {
+  defineFeature("probe-user-data-delete-contextual", (r) => {
+    r.useExtension(EXT_USER_DATA, "x", {
+      delete: async (ctx, strategy) => {
+        expectTypeOf(ctx).toEqualTypeOf<UserDataHookCtx>();
+        expectTypeOf(strategy).toEqualTypeOf<UserDataDeleteStrategy>();
+        return undefined;
+      },
+    });
+  });
+});
+
+test("useExtension rejects an empty userData registration", () => {
+  defineFeature("probe-user-data-empty", (r) => {
+    // @ts-expect-error userData needs at least one of export/delete — an empty bag silently registered neither hook.
+    r.useExtension(EXT_USER_DATA, "x", {});
+  });
+  expectTypeOf<Record<string, never>>().not.toExtend<ExtensionOptionsFor<typeof EXT_USER_DATA>>();
+});
+
+test("useExtension rejects a userData registration with only order", () => {
+  defineFeature("probe-user-data-only-order", (r) => {
+    // @ts-expect-error same as the empty-bag case above: order alone registers no hook.
+    r.useExtension(EXT_USER_DATA, "x", { order: 1 });
+  });
+  expectTypeOf<{ readonly order: number }>().not.toExtend<
+    ExtensionOptionsFor<typeof EXT_USER_DATA>
+  >();
+});
+
+test("useExtension accepts an unknown extension name with an arbitrary options bag", () => {
+  const feature = defineFeature("probe-unknown-name", (r) => {
+    r.useExtension("someAppPoint", "x", { anything: 42, goes: "here" });
+  });
+  expect(feature.extensionUsages).toContainEqual(
+    expect.objectContaining({
+      extensionName: "someAppPoint",
+      entityName: "x",
+      options: { anything: 42, goes: "here" },
+    }),
+  );
+});
+
+test("useExtension accepts an unknown extension name with no options at all", () => {
+  const feature = defineFeature("probe-unknown-name-no-options", (r) => {
+    r.useExtension("someOtherAppPoint", "x");
+  });
+  expect(feature.extensionUsages).toContainEqual(
+    expect.objectContaining({ extensionName: "someOtherAppPoint", entityName: "x" }),
+  );
+});
+
+test("useExtension accepts a string-typed extension name with an arbitrary options bag", () => {
+  const name: string = "someAppPoint";
+  const feature = defineFeature("probe-string-typed-name", (r) => {
+    r.useExtension(name, "x", { anything: 42 });
+  });
+  expect(feature.extensionUsages).toContainEqual(
+    expect.objectContaining({
+      extensionName: "someAppPoint",
+      entityName: "x",
+      options: { anything: 42 },
+    }),
+  );
+});
+
+test("useExtension accepts a well-typed storageProvider destroyTenant hook", () => {
+  defineFeature("probe-storage-provider-ok", (r) => {
+    r.useExtension(EXT_STORAGE_PROVIDER, "x", {
+      destroyTenant: async (tenantId: TenantId, ctx: TenantResourceHookCtx) => {
+        expectTypeOf(tenantId).toBeString();
+        expectTypeOf(ctx.db).not.toBeAny();
+      },
+    });
+  });
+});
+
+test("useExtension infers the storageProvider destroyTenant hook's arg types from context", () => {
+  defineFeature("probe-storage-provider-contextual", (r) => {
+    r.useExtension(EXT_STORAGE_PROVIDER, "x", {
+      destroyTenant: async (tenantId, ctx) => {
+        expectTypeOf(tenantId).toEqualTypeOf<TenantId>();
+        expectTypeOf(ctx).toEqualTypeOf<TenantResourceHookCtx>();
+      },
+    });
+  });
+});
+
+test("useExtension rejects a storageProvider destroyTenant hook shaped like the tenantData (ctx)-only hook", () => {
+  defineFeature("probe-storage-provider-wrong-shape", (r) => {
+    r.useExtension(EXT_STORAGE_PROVIDER, "x", {
+      // @ts-expect-error storageProvider's destroyTenant takes (tenantId, ctx) — a tenantData-style (ctx)-only hook is missing the tenantId arg.
+      destroyTenant: async (_ctx: TenantDataHookCtx) => {},
+    });
+  });
+  expectTypeOf<
+    (ctx: TenantDataHookCtx) => Promise<void>
+  >().not.toExtend<TenantResourceDestroyHook>();
+});
+
+test("useExtension rejects a storageProvider registration without destroyTenant", () => {
+  defineFeature("probe-storage-provider-missing-hook", (r) => {
+    // @ts-expect-error storageProvider requires destroyTenant — an empty bag silently registered no cleanup hook.
+    r.useExtension(EXT_STORAGE_PROVIDER, "x", {});
+  });
+  expectTypeOf<Record<string, never>>().not.toExtend<
+    ExtensionOptionsFor<typeof EXT_STORAGE_PROVIDER>
+  >();
+});
+
+test("useExtension rejects a mailTransport registration without build", () => {
+  defineFeature("probe-mail-transport-missing-build", (r) => {
+    // @ts-expect-error mailTransport requires build — an empty bag silently registered no transport factory.
+    r.useExtension(MAIL_TRANSPORT_EXTENSION, "x", {});
+  });
+  expectTypeOf<Record<string, never>>().not.toExtend<
+    ExtensionOptionsFor<typeof MAIL_TRANSPORT_EXTENSION>
+  >();
+});

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", () => {