@cosmicdrift/kumiko-bundled-features 0.165.0 → 0.165.2

package/src/auth-email-password/handlers/self-registration-status.query.ts

@@ -14,7 +14,10 @@ export const selfRegistrationStatusQuery = defineQueryHandler({
   name: "signup-registration-status",
   schema: z.object({}),
   access: { roles: ["anonymous", "User", "TenantAdmin", "SystemAdmin"] },
-  handler: async (_query, ctx) => ({
-    enabled: await ctx.hasFeature(AUTH_SELF_REGISTRATION_FEATURE),
-  }),
+  handler: async (_query, ctx) => {
+    // Same fail-open reasoning as signup-request.write.ts (#1468): only
+    // report disabled when the toggle feature is actually composed.
+    const gated = ctx.registry.getFeature(AUTH_SELF_REGISTRATION_FEATURE) !== undefined;
+    return { enabled: gated ? await ctx.hasFeature(AUTH_SELF_REGISTRATION_FEATURE) : true };
+  },
 });

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

@@ -76,7 +76,18 @@ export function createSignupRequestHandler(opts: SignupRequestOptions) {
       // email" either way. The client-visible signal is the `status` query
       // on auth-self-registration, which the signup page uses to hide its
       // own link/form instead of collecting input that silently no-ops.
-      if (!(await ctx.hasFeature(AUTH_SELF_REGISTRATION_FEATURE))) {
+      // Fail-open when the companion toggle feature isn't composed at all —
+      // ctx.hasFeature() is fail-closed for *unregistered* names the moment
+      // feature-toggles/tier-engine is wired, which silently kills
+      // self-signup for every existing app that mounts auth-email-password
+      // without also composing createAuthSelfRegistrationToggleFeature()
+      // (#1468). Only gate when the toggle actually exists.
+      const gated = ctx.registry.getFeature(AUTH_SELF_REGISTRATION_FEATURE) !== undefined;
+      if (gated && !(await ctx.hasFeature(AUTH_SELF_REGISTRATION_FEATURE))) {
+        // No email address here — this fires on every no-op request, PII
+        // must not accumulate in logs just for the "was this toggled off"
+        // signal a support ticket needs.
+        ctx.log?.info("signup-request skipped: self-registration disabled");
         return { isSuccess: true, data: { kind: "no-op" } };
       }
       if (!ctx.redis) {

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

@@ -89,6 +89,7 @@ export const defaultTranslations: TranslationsByLocale = {
     "auth.requestUnlock.successBody":
       "Falls die E-Mail in unserem System existiert und gesperrt ist, ist eine Nachricht mit einem Entsperren-Link unterwegs. Bitte schau in deinen Posteingang.",
     "auth.requestUnlock.backToLogin": "Zurück zum Login",
+    "auth.requestUnlock.rateLimited": "Zu viele Anfragen. Neuer Versuch in {minutes} Minuten.",
     "auth.unlockAccount.verifying": "Konto wird entsperrt …",
     "auth.unlockAccount.successTitle": "Konto entsperrt",
     "auth.unlockAccount.successBody":
@@ -215,6 +216,7 @@ export const defaultTranslations: TranslationsByLocale = {
     "auth.requestUnlock.successBody":
       "If that email exists in our system and is locked, a message with an unlock link is on its way. Please check your inbox.",
     "auth.requestUnlock.backToLogin": "Back to sign in",
+    "auth.requestUnlock.rateLimited": "Too many requests. Try again in {minutes} minutes.",
     "auth.unlockAccount.verifying": "Unlocking account …",
     "auth.unlockAccount.successTitle": "Account unlocked",
     "auth.unlockAccount.successBody": "Your account is unlocked again. You can sign in now.",

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

@@ -55,17 +55,25 @@ export type SeedUserWithPasswordOptions = {
 export async function seedUserWithPassword(
   db: DbConnection,
   options: SeedUserWithPasswordOptions,
+  // Optional, append-only — same rationale as provisionSignupAccount's
+  // hooks param (#1478): the self-signup path passes it through so `user`'s
+  // postSave hooks fire on self-signup same as on the regular create path.
+  hooks?: SeedTenantHooks,
 ): Promise<{ id: string }> {
   const passwordHash = await hashPassword(options.password);
-  return seedUser(db, {
-    email: options.email,
-    displayName: options.displayName,
-    passwordHash,
-    ...(options.locale !== undefined && { locale: options.locale }),
-    ...(options.roles !== undefined && { roles: options.roles }),
-    ...(options.emailVerified !== undefined && { emailVerified: options.emailVerified }),
-    ...(options.by !== undefined && { by: options.by }),
-  });
+  return seedUser(
+    db,
+    {
+      email: options.email,
+      displayName: options.displayName,
+      passwordHash,
+      ...(options.locale !== undefined && { locale: options.locale }),
+      ...(options.roles !== undefined && { roles: options.roles }),
+      ...(options.emailVerified !== undefined && { emailVerified: options.emailVerified }),
+      ...(options.by !== undefined && { by: options.by }),
+    },
+    hooks,
+  );
 }
 
 /** Provisioning-Helper für Self-Signup-Confirm. Legt einen frischen
@@ -117,9 +125,11 @@ export async function provisionSignupAccount(
   options: ProvisionSignupAccountOptions,
   // Optional, append-only — existing callers (tests, seed scripts) that
   // don't pass hooks keep today's behavior. The real signup-confirm
-  // handler DOES pass it (#1463) so seedTenant's postSave hooks
-  // (tier-engine's auto-default-tier, app auto-default-compliance) fire
-  // on self-signup, same as they do on the regular tenant-create path.
+  // handler DOES pass it (#1463) so seedTenant/seedUserWithPassword/
+  // seedTenantMembership's postSave hooks (tier-engine's auto-default-tier,
+  // app auto-default-compliance, a Welcome-notification hook, ...) fire on
+  // self-signup for all three entities, same as they do on the regular
+  // create paths (#1478 — this was only wired for tenant before).
   hooks?: SeedTenantHooks,
 ): Promise<{ readonly userId: string; readonly tenantId: TenantId }> {
   // Create-only-Guard VOR seedTenant: bei bereits registrierter Email hart
@@ -139,17 +149,25 @@ export async function provisionSignupAccount(
     },
     hooks,
   );
-  const { id: userId } = await seedUserWithPassword(db, {
-    email: options.email,
-    password: options.password,
-    displayName: options.displayName,
-    emailVerified: true,
-  });
-  await seedTenantMembership(db, {
-    userId,
-    tenantId: options.tenantId,
-    roles: options.memberRoles ?? INITIAL_SIGNUP_ROLES,
-  });
+  const { id: userId } = await seedUserWithPassword(
+    db,
+    {
+      email: options.email,
+      password: options.password,
+      displayName: options.displayName,
+      emailVerified: true,
+    },
+    hooks,
+  );
+  await seedTenantMembership(
+    db,
+    {
+      userId,
+      tenantId: options.tenantId,
+      roles: options.memberRoles ?? INITIAL_SIGNUP_ROLES,
+    },
+    hooks,
+  );
   return { userId, tenantId: options.tenantId };
 }
 

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

@@ -33,6 +33,8 @@ function withoutCsrfDocument(): void {
   delete (globalThis as { document?: { cookie: string } }).document;
 }
 
+const originalFetch = globalThis.fetch;
+
 beforeEach(() => {
   globalThis.fetch = mock(
     async () => new Response(null, { status: 200 }),
@@ -41,6 +43,7 @@ beforeEach(() => {
 
 afterEach(() => {
   withoutCsrfDocument();
+  globalThis.fetch = originalFetch;
 });
 
 describe("csrfHeader", () => {
@@ -107,6 +110,16 @@ describe("login", () => {
     expect(res).toEqual({ kind: "mfa-setup-required", preauthSetupToken: "setup-token-value" });
   });
 
+  test("mfaSetupRequired without preauthSetupToken → explicit mfa_setup_required failure", async () => {
+    globalThis.fetch = mock(async () =>
+      jsonResponse({ isSuccess: true, mfaSetupRequired: true }),
+    ) as unknown as typeof fetch;
+
+    const res = await login({ email: "a@b.c", password: "secret" });
+
+    expect(res).toEqual({ kind: "failure", error: { reason: "mfa_setup_required" } });
+  });
+
   test("string error → kind:failure with reason from string", async () => {
     globalThis.fetch = mock(async () =>
       jsonResponse({ isSuccess: false, error: "invalid_credentials" }),

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

@@ -1,5 +1,5 @@
 import { describe, expect, mock, test } from "bun:test";
-import { fireEvent, screen } from "@testing-library/react";
+import { fireEvent, screen, waitFor } from "@testing-library/react";
 import type { ReactNode } from "react";
 import { createLoginRoute, makeAuthGate } from "../auth-gate";
 import { makeSessionApi, renderWithProviders } from "./test-utils";
@@ -10,7 +10,7 @@ describe("makeAuthGate", () => {
   }
 
   test("loading → renders placeholder, not children, not login", () => {
-    const Gate = makeAuthGate(CustomLogin);
+    const Gate = makeAuthGate({ loginScreen: CustomLogin });
     const session = makeSessionApi({ status: "loading", user: null });
     const { container } = renderWithProviders(
       <Gate>
@@ -25,7 +25,7 @@ describe("makeAuthGate", () => {
   });
 
   test("unauthenticated → renders LoginComponent, not children", () => {
-    const Gate = makeAuthGate(CustomLogin);
+    const Gate = makeAuthGate({ loginScreen: CustomLogin });
     const session = makeSessionApi({ status: "unauthenticated", user: null });
     renderWithProviders(
       <Gate>
@@ -38,7 +38,7 @@ describe("makeAuthGate", () => {
   });
 
   test("authenticated → renders children, not login", () => {
-    const Gate = makeAuthGate(CustomLogin);
+    const Gate = makeAuthGate({ loginScreen: CustomLogin });
     renderWithProviders(
       <Gate>
         <div data-testid="protected">secret</div>
@@ -134,8 +134,30 @@ describe("createLoginRoute", () => {
     expect(screen.getByTestId("mfa-verify").textContent).toBe("token-123");
   });
 
+  test("no mfaVerifyScreen → onMfaChallenge passes through to loginScreenProps.onMfaChallenge (#266 footgun)", () => {
+    // The silent-no-MFA-fallback path: an app that wires its own
+    // onMfaChallenge via loginScreenProps but forgets mfaVerifyScreen still
+    // gets that callback invoked (createLoginRoute can't detect the
+    // omission) instead of the internal setChallengeToken/MfaVerifyComponent
+    // machinery kicking in. Covered here so a future refactor of that
+    // ternary can't silently swap the fallback direction.
+    const onMfaChallenge = mock<(challengeToken: string) => void>();
+    const LoginRoute = createLoginRoute({
+      loginScreen: LoginWithMfaTrigger,
+      loginScreenProps: { onMfaChallenge },
+    });
+    const session = makeSessionApi({ status: "unauthenticated" });
+    renderWithProviders(<LoginRoute />, { session });
+    fireEvent.click(screen.getByTestId("trigger-mfa"));
+    expect(onMfaChallenge).toHaveBeenCalledWith("token-123");
+    expect(screen.queryByTestId("mfa-verify")).toBeNull();
+  });
+
   test("makeAuthGate delegates mfaVerifyScreen wiring to createLoginRoute", () => {
-    const Gate = makeAuthGate(LoginWithMfaTrigger, undefined, CustomMfaVerify);
+    const Gate = makeAuthGate({
+      loginScreen: LoginWithMfaTrigger,
+      mfaVerifyScreen: CustomMfaVerify,
+    });
     const session = makeSessionApi({ status: "unauthenticated" });
     renderWithProviders(
       <Gate>
@@ -160,7 +182,7 @@ describe("createLoginRoute", () => {
     );
   });
 
-  test("MfaSetupComponent onSuccess → gate clears the request and refreshes the session", () => {
+  test("MfaSetupComponent onSuccess → gate clears the request and refreshes the session", async () => {
     const LoginRoute = createLoginRoute({
       loginScreen: LoginWithMfaSetupTrigger,
       mfaSetupScreen: CustomMfaSetup,
@@ -171,11 +193,36 @@ describe("createLoginRoute", () => {
     expect(screen.getByTestId("mfa-setup")).toBeTruthy();
     fireEvent.click(screen.getByTestId("complete-mfa-setup"));
     expect(session.refresh).toHaveBeenCalledTimes(1);
-    expect(screen.queryByTestId("mfa-setup")).toBeNull();
+    await waitFor(() => {
+      expect(screen.queryByTestId("mfa-setup")).toBeNull();
+    });
+  });
+
+  test("MfaSetupComponent onSuccess → keeps setup screen when refresh rejects", async () => {
+    const LoginRoute = createLoginRoute({
+      loginScreen: LoginWithMfaSetupTrigger,
+      mfaSetupScreen: CustomMfaSetup,
+    });
+    const session = makeSessionApi({
+      status: "unauthenticated",
+      refresh: mock(async () => {
+        throw new Error("refresh failed");
+      }),
+    });
+    renderWithProviders(<LoginRoute />, { session });
+    fireEvent.click(screen.getByTestId("trigger-mfa-setup"));
+    fireEvent.click(screen.getByTestId("complete-mfa-setup"));
+    expect(session.refresh).toHaveBeenCalledTimes(1);
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(screen.getByTestId("mfa-setup")).toBeTruthy();
   });
 
   test("makeAuthGate delegates mfaSetupScreen wiring to createLoginRoute", () => {
-    const Gate = makeAuthGate(LoginWithMfaSetupTrigger, undefined, undefined, CustomMfaSetup);
+    const Gate = makeAuthGate({
+      loginScreen: LoginWithMfaSetupTrigger,
+      mfaSetupScreen: CustomMfaSetup,
+    });
     const session = makeSessionApi({ status: "unauthenticated" });
     renderWithProviders(
       <Gate>

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

@@ -0,0 +1,34 @@
+import { describe, expect, mock, test } from "bun:test";
+
+// #1472: emailPasswordClient() built the session gate without threading
+// options.mfaSetupScreen through to makeSessionAuthGate — the option was
+// typed and documented but silently dropped on the standard mount path.
+// makeSessionAuthGate wraps its own real SessionProvider (unlike
+// makeAuthGate, which auth-gate.test.tsx exercises directly), so the
+// cheapest live check is spying on the call args instead of rendering
+// through a real session fetch.
+const makeSessionAuthGateCalls: unknown[][] = [];
+mock.module("../auth-gate", () => ({
+  makeSessionAuthGate: (...args: unknown[]) => {
+    makeSessionAuthGateCalls.push(args);
+    return () => null;
+  },
+}));
+
+const { emailPasswordClient } = await import("../client-plugin");
+
+describe("emailPasswordClient — mfaSetupScreen wiring", () => {
+  test("passes options.mfaSetupScreen through to makeSessionAuthGate", () => {
+    makeSessionAuthGateCalls.length = 0;
+    function CustomMfaSetup() {
+      return null;
+    }
+
+    emailPasswordClient({ mfaSetupScreen: CustomMfaSetup });
+
+    expect(makeSessionAuthGateCalls).toHaveLength(1);
+    expect((makeSessionAuthGateCalls[0]?.[0] as { mfaSetupScreen?: unknown })?.mfaSetupScreen).toBe(
+      CustomMfaSetup,
+    );
+  });
+});

package/src/auth-email-password/web/__tests__/confirm-account-unlock-screen.test.tsx

@@ -3,12 +3,16 @@ import { screen, waitFor } from "@testing-library/react";
 import { ConfirmAccountUnlockScreen } from "../confirm-account-unlock-screen";
 import { renderWithProviders } from "./test-utils";
 
+const originalFetch = globalThis.fetch;
+
 beforeEach(() => {
   globalThis.fetch = mock(
     async () => new Response(null, { status: 200 }),
   ) as unknown as typeof fetch;
 });
-afterEach(() => {});
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
 
 describe("ConfirmAccountUnlockScreen", () => {
   test("ohne Token → missing-token page", () => {
@@ -28,6 +32,8 @@ describe("ConfirmAccountUnlockScreen", () => {
         "/api/auth/confirm-account-unlock",
         expect.objectContaining({
           method: "POST",
+          headers: expect.objectContaining({ "Content-Type": "application/json" }),
+          credentials: "same-origin",
           body: JSON.stringify({ token: "unlock-tok" }),
         }),
       );
@@ -53,5 +59,6 @@ describe("ConfirmAccountUnlockScreen", () => {
   test("custom title on missing-token uses errorTitle slot only when set", () => {
     renderWithProviders(<ConfirmAccountUnlockScreen title="Unlock kaputt" />);
     expect(screen.getByText("Unlock kaputt")).toBeTruthy();
+    expect(screen.queryByText("Entsperren fehlgeschlagen")).toBeNull();
   });
 });

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

@@ -3,12 +3,16 @@ import { fireEvent, screen, waitFor } from "@testing-library/react";
 import { ForgotPasswordScreen } from "../forgot-password-screen";
 import { renderWithProviders } from "./test-utils";
 
+const originalFetch = globalThis.fetch;
+
 beforeEach(() => {
   globalThis.fetch = mock(
     async () => new Response(null, { status: 200 }),
   ) as unknown as typeof fetch;
 });
-afterEach(() => {});
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
 
 describe("ForgotPasswordScreen", () => {
   test("rendert title + email-input + submit-button (de)", () => {

package/src/auth-email-password/web/__tests__/invite-accept-screen.test.tsx

@@ -27,6 +27,8 @@ function renderWithoutSessionProvider(token: string) {
   );
 }
 
+const originalFetch = globalThis.fetch;
+
 beforeEach(() => {
   globalThis.fetch = mock(
     async () => new Response(JSON.stringify({ tenantId: "tenant-new" }), { status: 200 }),
@@ -43,6 +45,7 @@ afterEach(() => {
     writable: true,
     value: originalLocation,
   });
+  globalThis.fetch = originalFetch;
 });
 
 describe("InviteAcceptScreen — no <SessionProvider> ancestor (632/1)", () => {

package/src/auth-email-password/web/__tests__/request-account-unlock-screen.test.tsx

@@ -3,12 +3,16 @@ import { fireEvent, screen, waitFor } from "@testing-library/react";
 import { RequestAccountUnlockScreen } from "../request-account-unlock-screen";
 import { renderWithProviders } from "./test-utils";
 
+const originalFetch = globalThis.fetch;
+
 beforeEach(() => {
   globalThis.fetch = mock(
     async () => new Response(null, { status: 200 }),
   ) as unknown as typeof fetch;
 });
-afterEach(() => {});
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
 
 describe("RequestAccountUnlockScreen", () => {
   test("renders title + email input + submit (de)", () => {
@@ -33,6 +37,8 @@ describe("RequestAccountUnlockScreen", () => {
         "/api/auth/request-account-unlock",
         expect.objectContaining({
           method: "POST",
+          headers: expect.objectContaining({ "Content-Type": "application/json" }),
+          credentials: "same-origin",
           body: JSON.stringify({ email: "user@example.com" }),
         }),
       );
@@ -54,7 +60,7 @@ describe("RequestAccountUnlockScreen", () => {
     );
   });
 
-  test("429 with retryAfterSeconds → accountLockedRetry banner", async () => {
+  test("429 with retryAfterSeconds → requestUnlock.rateLimited banner (#1333)", async () => {
     globalThis.fetch = mock(
       async () =>
         new Response(JSON.stringify({ error: { details: { retryAfterSeconds: 180 } } }), {

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

@@ -3,12 +3,16 @@ import { fireEvent, screen, waitFor } from "@testing-library/react";
 import { ResetPasswordScreen } from "../reset-password-screen";
 import { renderWithProviders } from "./test-utils";
 
+const originalFetch = globalThis.fetch;
+
 beforeEach(() => {
   globalThis.fetch = mock(
     async () => new Response(null, { status: 200 }),
   ) as unknown as typeof fetch;
 });
-afterEach(() => {});
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
 
 describe("ResetPasswordScreen", () => {
   test("ohne Token in URL UND ohne token-Prop → missing-token-Page", () => {

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

@@ -3,12 +3,16 @@ import { screen, waitFor } from "@testing-library/react";
 import { VerifyEmailScreen } from "../verify-email-screen";
 import { renderWithProviders } from "./test-utils";
 
+const originalFetch = globalThis.fetch;
+
 beforeEach(() => {
   globalThis.fetch = mock(
     async () => new Response(null, { status: 200 }),
   ) as unknown as typeof fetch;
 });
-afterEach(() => {});
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
 
 describe("VerifyEmailScreen", () => {
   test("ohne Token → missing-token-Page", () => {

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

@@ -34,8 +34,24 @@ export type LoginResponse = {
   };
 };
 
+// Reason codes the login-handler is known to emit today (login-screen.tsx's
+// reasonToKey maps every one of these to an i18n key). The server can also
+// send a reason this client doesn't know about yet (rolling deploys, a new
+// enforcement policy) — `string & {}` keeps that open while still giving
+// autocomplete/typo-checking on the known set, instead of collapsing both
+// to plain `string` (coding-standards: no magic strings without a union).
+export type KnownLoginFailureReason =
+  | "invalid_credentials"
+  | "no_membership"
+  | "account_locked"
+  | "email_not_verified"
+  | "rate_limited"
+  | "invalid_body"
+  | "mfa_not_supported"
+  | "mfa_setup_required";
+
 export type LoginFailure = {
-  readonly reason: string;
+  readonly reason: KnownLoginFailureReason | (string & {});
   readonly message?: string;
   readonly retryAfterSeconds?: number;
 };
@@ -93,8 +109,14 @@ export async function login(req: LoginRequest): Promise<LoginResult> {
     if (body.mfaRequired === true && typeof body.challengeToken === "string") {
       return { kind: "mfa-challenge", challengeToken: body.challengeToken };
     }
-    if (body.mfaSetupRequired === true && typeof body.preauthSetupToken === "string") {
-      return { kind: "mfa-setup-required", preauthSetupToken: body.preauthSetupToken };
+    if (body.mfaSetupRequired === true) {
+      // Older servers / mounts may set the flag without minting a preauth token —
+      // surface an explicit failure (login-screen maps mfa_setup_required) instead
+      // of falling through to generic login_failed.
+      if (typeof body.preauthSetupToken === "string") {
+        return { kind: "mfa-setup-required", preauthSetupToken: body.preauthSetupToken };
+      }
+      return { kind: "failure", error: { reason: "mfa_setup_required" } };
     }
     if (body.token !== undefined && body.user !== undefined) {
       return { kind: "success", data: { token: body.token, user: body.user } };
@@ -167,10 +189,10 @@ async function parseTokenFailure(res: Response): Promise<AuthTokenFailure> {
   return { reason };
 }
 
-// POST /api/auth/request-password-reset. 200 silent-success: auch wenn
-// die Email nicht existiert, sieht der caller `{ ok: true }` — kein
-// account-enumeration. Server triggert Mail nur intern wenn user
-// gefunden. 429 → typed rate-limit-Failure. 5xx → unknown-error.
+// POST /api/auth/request-password-reset. 200 silent-success: even if the
+// email doesn't exist, the caller sees `{ ok: true }` — no account
+// enumeration. Server only triggers the mail internally when a user is
+// found. 429 → typed rate-limit failure. 5xx → unknown-error.
 export async function requestPasswordReset(
   email: string,
 ): Promise<{ ok: true } | { ok: false; error: AuthTokenFailure }> {
@@ -204,7 +226,7 @@ export async function resetPassword(
 }
 
 // POST /api/auth/request-email-verification. Same silent-success
-// semantik wie request-password-reset. 429 → rate-limit-Failure.
+// semantics as request-password-reset. 429 → rate-limit failure.
 export async function requestEmailVerification(
   email: string,
 ): Promise<{ ok: true } | { ok: false; error: AuthTokenFailure }> {
@@ -234,8 +256,8 @@ export async function verifyEmail(
   return { ok: false, error: await parseTokenFailure(res) };
 }
 
-// POST /api/auth/request-account-unlock. Same silent-success semantik wie
-// request-password-reset. 429 → rate-limit-Failure.
+// POST /api/auth/request-account-unlock. Same silent-success semantics as
+// request-password-reset. 429 → rate-limit failure.
 export async function requestAccountUnlock(
   email: string,
 ): Promise<{ ok: true } | { ok: false; error: AuthTokenFailure }> {

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

@@ -109,10 +109,17 @@ export function createLoginRoute(
           preauthSetupToken={setupRequest.preauthSetupToken}
           accountLabel={setupRequest.accountLabel}
           onSuccess={() => {
-            setSetupRequest(null);
             // MfaSetupPreauthScreen has no session to refresh itself with
             // (it runs pre-auth) — the gate owns the session, so it refreshes.
-            void refresh();
+            // Keep setupRequest until refresh settles: clearing first would
+            // dump the user back on the login form with no retry if refresh
+            // rejects (cookie+JWT already minted server-side).
+            void refresh().then(
+              () => setSetupRequest(null),
+              () => {
+                // leave setupRequest set so the user can cancel/retry
+              },
+            );
           }}
           onCancel={() => setSetupRequest(null)}
         />
@@ -136,18 +143,10 @@ export function createLoginRoute(
   return LoginRoute;
 }
 
-export function makeAuthGate(
-  LoginComponent: ComponentType<LoginScreenProps> = LoginScreen,
-  loginProps?: LoginScreenProps,
-  MfaVerifyComponent?: ComponentType<MfaVerifyComponentProps>,
-  MfaSetupComponent?: ComponentType<MfaSetupComponentProps>,
-): ComponentType<{ children: ReactNode }> {
-  const LoginRoute = createLoginRoute({
-    loginScreen: LoginComponent,
-    loginScreenProps: loginProps,
-    mfaVerifyScreen: MfaVerifyComponent,
-    mfaSetupScreen: MfaSetupComponent,
-  });
+export function makeAuthGate(opts: LoginRouteOptions = {}): ComponentType<{
+  children: ReactNode;
+}> {
+  const LoginRoute = createLoginRoute(opts);
   function AuthGate({ children }: { readonly children: ReactNode }): ReactNode {
     const { status } = useSession();
     if (status === "authenticated") return <>{children}</>;
@@ -159,13 +158,10 @@ export function makeAuthGate(
 // SessionProvider + AuthGate as one gate, so a public gate in front (e.g.
 // /calculator) doesn't mount the session bootstrap — createKumikoApp stacks
 // providers outside all gates, so SessionProvider can't be a provider anymore.
-export function makeSessionAuthGate(
-  LoginComponent: ComponentType<LoginScreenProps> = LoginScreen,
-  loginProps?: LoginScreenProps,
-  MfaVerifyComponent?: ComponentType<MfaVerifyComponentProps>,
-  MfaSetupComponent?: ComponentType<MfaSetupComponentProps>,
-): ComponentType<{ children: ReactNode }> {
-  const AuthGate = makeAuthGate(LoginComponent, loginProps, MfaVerifyComponent, MfaSetupComponent);
+export function makeSessionAuthGate(opts: LoginRouteOptions = {}): ComponentType<{
+  children: ReactNode;
+}> {
+  const AuthGate = makeAuthGate(opts);
   function SessionAuthGate({ children }: { readonly children: ReactNode }): ReactNode {
     return (
       <SessionProvider>

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

@@ -8,7 +8,11 @@
 import type { TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
 import type { ComponentType, ReactNode } from "react";
 import { defaultTranslations, mergeTranslations } from "../i18n";
-import { type MfaVerifyComponentProps, makeSessionAuthGate } from "./auth-gate";
+import {
+  type MfaSetupComponentProps,
+  type MfaVerifyComponentProps,
+  makeSessionAuthGate,
+} from "./auth-gate";
 import type { LoginScreenProps } from "./login-screen";
 
 export type EmailPasswordClientOptions = {
@@ -24,6 +28,10 @@ export type EmailPasswordClientOptions = {
    *  auth-mfa simply don't pass this — LoginScreen's built-in fallback
    *  error covers that case. */
   readonly mfaVerifyScreen?: ComponentType<MfaVerifyComponentProps>;
+  /** auth-mfa's MfaSetupPreauthScreen, wired in from the app the same way
+   *  as mfaVerifyScreen above. Apps not mounting auth-mfa simply don't
+   *  pass this. */
+  readonly mfaSetupScreen?: ComponentType<MfaSetupComponentProps>;
   /** Key-Overrides pro Locale. Wird mit den Default-Bundles (de/en)
    *  aus `translations.ts` gemerged — jeder hier gesetzte Key gewinnt.
    *  Für Branding ("Sign in" → "Login to Acme") oder weitere Sprachen
@@ -49,7 +57,12 @@ export function emailPasswordClient(
     name: "auth-email-password",
     providers: [],
     gates: [
-      makeSessionAuthGate(options.loginScreen, options.loginScreenProps, options.mfaVerifyScreen),
+      makeSessionAuthGate({
+        loginScreen: options.loginScreen,
+        loginScreenProps: options.loginScreenProps,
+        mfaVerifyScreen: options.mfaVerifyScreen,
+        mfaSetupScreen: options.mfaSetupScreen,
+      }),
     ],
     translations,
   };

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

@@ -29,7 +29,11 @@ export {
 } from "./auth-client";
 export type { AuthCardProps, AuthShellRenderer } from "./auth-form-primitives";
 export { AuthCard, AuthShellProvider, useAuthShell } from "./auth-form-primitives";
-export type { LoginRouteOptions, MfaVerifyComponentProps } from "./auth-gate";
+export type {
+  LoginRouteOptions,
+  MfaSetupComponentProps,
+  MfaVerifyComponentProps,
+} from "./auth-gate";
 export { createLoginRoute, makeAuthGate, makeSessionAuthGate } from "./auth-gate";
 export type {
   EmailPasswordClientFeature,