@cosmicdrift/kumiko-bundled-features 0.161.0 → 0.162.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.161.0",
+  "version": "0.162.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>",
@@ -117,11 +117,11 @@
     "./step-dispatcher": "./src/step-dispatcher/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.161.0",
-    "@cosmicdrift/kumiko-framework": "0.161.0",
-    "@cosmicdrift/kumiko-headless": "0.161.0",
-    "@cosmicdrift/kumiko-renderer": "0.161.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.161.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.162.0",
+    "@cosmicdrift/kumiko-framework": "0.162.0",
+    "@cosmicdrift/kumiko-headless": "0.162.0",
+    "@cosmicdrift/kumiko-renderer": "0.162.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.162.0",
     "@mollie/api-client": "^4.5.0",
     "imapflow": "^1.3.3",
     "mailparser": "^3.9.8",

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

@@ -0,0 +1,168 @@
+// Runtime on/off switch for self-signup (#self-registration-toggle). Pins:
+//   1. Default (no override row) → signup-request works.
+//   2. runtime.apply(off) → signup-request 403 feature_disabled, no mail sent.
+//   3. runtime.apply(on) → works again.
+// Mirrors samples/recipes/feature-toggles' runtime.apply() pattern — flips the
+// in-memory snapshot directly instead of going through the set-handler/HTTP,
+// since that wiring is already covered by feature-toggles' own tests.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import {
+  createFeatureTogglesFeature,
+  GlobalFeatureToggleRuntime,
+  globalFeatureStateTable,
+} from "@cosmicdrift/kumiko-bundled-features/feature-toggles";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { createLateBoundHolder } from "@cosmicdrift/kumiko-framework/testing";
+import { createChannelEmailFeature, createInMemoryTransport } from "../../channel-email";
+import { createConfigFeature } from "../../config";
+import { createConfigResolver } from "../../config/resolver";
+import { configValuesTable } from "../../config/table";
+import { createDeliveryFeature, createDeliveryTestContext } from "../../delivery";
+import { notificationPreferencesTable } from "../../delivery/tables";
+import { createRendererFoundationFeature } from "../../renderer-foundation/feature";
+import { createRendererSimpleFeature, simpleRenderer } from "../../renderer-simple";
+import { createTemplateResolverFeature } from "../../template-resolver/feature";
+import { createTenantFeature } from "../../tenant";
+import { tenantMembershipsTable } from "../../tenant/membership-table";
+import { tenantEntity } from "../../tenant/schema/tenant";
+import { createUserFeature } from "../../user/feature";
+import { userEntity, userTable } from "../../user/schema/user";
+import { AuthHandlers } from "../constants";
+import { createAuthEmailPasswordFeature } from "../feature";
+import {
+  AUTH_SELF_REGISTRATION_FEATURE,
+  createAuthSelfRegistrationToggleFeature,
+} from "../self-registration-toggle";
+
+const APP_ACTIVATION_URL = "https://app.example.com/signup/complete";
+const emailTransport = createInMemoryTransport();
+
+let stack: TestStack;
+let runtime: GlobalFeatureToggleRuntime;
+
+beforeAll(async () => {
+  let effective: () => ReadonlySet<string> = () => new Set();
+  const runtimeHolder = createLateBoundHolder<GlobalFeatureToggleRuntime>("runtime");
+
+  stack = await setupTestStack({
+    features: [
+      createConfigFeature(),
+      createUserFeature(),
+      createTenantFeature(),
+      createTemplateResolverFeature(),
+      createRendererFoundationFeature(),
+      createDeliveryFeature(),
+      createRendererSimpleFeature(),
+      createChannelEmailFeature({
+        transport: emailTransport,
+        renderer: simpleRenderer,
+        resolveEmail: async () => "unused@test.local",
+      }),
+      createAuthEmailPasswordFeature({
+        signup: { tokenTtlMinutes: 60, appUrl: APP_ACTIVATION_URL },
+      }),
+      createAuthSelfRegistrationToggleFeature(),
+      createFeatureTogglesFeature({ getRuntime: () => runtimeHolder.get() }),
+    ],
+    effectiveFeatures: () => effective(),
+    extraContext: (deps) => ({
+      ...createDeliveryTestContext(deps),
+      configResolver: createConfigResolver(),
+    }),
+    systemHooks: [],
+    anonymousAccess: { defaultTenantId: SYSTEM_TENANT_ID },
+    authConfig: {
+      membershipQuery: "tenant:query:memberships",
+      loginHandler: AuthHandlers.login,
+      signup: {
+        requestHandler: AuthHandlers.signupRequest,
+        confirmHandler: AuthHandlers.signupConfirm,
+      },
+    },
+  });
+
+  await unsafeCreateEntityTable(stack.db, userEntity);
+  await unsafeCreateEntityTable(stack.db, tenantEntity);
+  await unsafePushTables(stack.db, {
+    configValuesTable,
+    tenantMembershipsTable,
+    notificationPreferencesTable,
+    globalFeatureStateTable,
+  });
+
+  runtime = new GlobalFeatureToggleRuntime(stack.db, stack.registry);
+  await runtime.initialize();
+  effective = runtime.effectiveFeatures;
+  runtimeHolder.set(runtime);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${userTable.tableName}"`);
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${globalFeatureStateTable.tableName}"`);
+  await runtime.refresh();
+  emailTransport.sent.length = 0;
+  const allKeys = await stack.redis.redis.keys("signup:*");
+  if (allKeys.length > 0) await stack.redis.redis.del(...allKeys);
+});
+
+async function postSignupRequest(email: string): Promise<Response> {
+  return stack.http.raw("POST", "/api/auth/signup-request", { email });
+}
+
+describe("auth-self-registration toggle", () => {
+  test("default (no override) → signup-request works", async () => {
+    const res = await postSignupRequest("alice@example.com");
+    expect(res.status).toBe(200);
+    expect(emailTransport.sent).toHaveLength(1);
+  });
+
+  test("runtime off → signup-request still 200 (anti-enumeration silent-success) but no mail sent", async () => {
+    runtime.apply(AUTH_SELF_REGISTRATION_FEATURE, false);
+
+    const res = await postSignupRequest("blocked@example.com");
+    expect(res.status).toBe(200);
+    expect(emailTransport.sent).toHaveLength(0);
+  });
+
+  test("runtime back on → mail sends again", async () => {
+    runtime.apply(AUTH_SELF_REGISTRATION_FEATURE, false);
+    await postSignupRequest("still-blocked@example.com");
+    expect(emailTransport.sent).toHaveLength(0);
+
+    runtime.apply(AUTH_SELF_REGISTRATION_FEATURE, true);
+    const res = await postSignupRequest("reenabled@example.com");
+    expect(res.status).toBe(200);
+    expect(emailTransport.sent).toHaveLength(1);
+  });
+
+  test("status query reflects the runtime flip", async () => {
+    const onRes = await stack.http.raw("POST", "/api/query", {
+      type: "auth-email-password:query:signup-registration-status",
+      payload: {},
+    });
+    expect((await onRes.json()) as { data?: { enabled: boolean } }).toMatchObject({
+      data: { enabled: true },
+    });
+
+    runtime.apply(AUTH_SELF_REGISTRATION_FEATURE, false);
+    const offRes = await stack.http.raw("POST", "/api/query", {
+      type: "auth-email-password:query:signup-registration-status",
+      payload: {},
+    });
+    expect((await offRes.json()) as { data?: { enabled: boolean } }).toMatchObject({
+      data: { enabled: false },
+    });
+  });
+});

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

@@ -46,6 +46,12 @@ export const AuthHandlers = {
   inviteCancel: "auth-email-password:write:invite-cancel",
 } as const;
 
+// Qualified query names. Anonymous-readable status so the (unauthenticated)
+// signup page can decide whether to show its own link/form.
+export const AuthQueries = {
+  signupRegistrationStatus: "auth-email-password:query:signup-registration-status",
+} as const;
+
 // Error codes — kept intentionally generic so clients can't distinguish
 // "email doesn't exist" from "password wrong". Both surface as invalid_credentials.
 // Soft-deleted users also collapse into invalid_credentials to avoid enumeration.

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

@@ -20,6 +20,7 @@ import {
 import { createRequestEmailVerificationHandler } from "./handlers/request-email-verification.write";
 import { createRequestPasswordResetHandler } from "./handlers/request-password-reset.write";
 import { createResetPasswordHandler } from "./handlers/reset-password.write";
+import { selfRegistrationStatusQuery } from "./handlers/self-registration-status.query";
 import { createSignupConfirmHandler } from "./handlers/signup-confirm.write";
 import {
   createSignupRequestHandler,
@@ -223,6 +224,12 @@ export function createAuthEmailPasswordFeature(
       r.writeHandler(createVerifyEmailHandler(opts.emailVerification));
     }
 
+    const queries = {
+      ...(opts.signup && {
+        signupRegistrationStatus: r.queryHandler(selfRegistrationStatusQuery),
+      }),
+    };
+
     if (opts.signup) {
       r.writeHandler(createSignupRequestHandler(opts.signup));
       r.writeHandler(createSignupConfirmHandler());
@@ -240,6 +247,6 @@ export function createAuthEmailPasswordFeature(
       r.writeHandler(createConfirmAccountUnlockHandler(opts.accountUnlock));
     }
 
-    return { handlers };
+    return { handlers, queries };
   });
 }

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

@@ -0,0 +1,20 @@
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { AUTH_SELF_REGISTRATION_FEATURE } from "../self-registration-toggle";
+
+// Anonymous-readable status for the (unauthenticated) signup page: lets it
+// hide its own link/form when an operator has flipped self-registration
+// off, instead of collecting an email that signup-request will silently
+// no-op on. Lives in auth-email-password itself (never toggleable) rather
+// than on the auth-self-registration companion feature — the dispatcher's
+// per-feature gate would otherwise make this query unreachable exactly when
+// the toggle is off (same split as managed-pages' branding query vs.
+// css-gate.ts).
+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),
+  }),
+});

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

@@ -31,6 +31,7 @@ import { AUTH_SIGNUP_DEFAULT_TTL_MINUTES } from "../constants";
 import type { AuthMailLocale } from "../email-templates";
 import { renderActivationEmail } from "../email-templates";
 import { dispatchMagicLinkMail } from "../magic-link-mail";
+import { AUTH_SELF_REGISTRATION_FEATURE } from "../self-registration-toggle";
 import { getTokenForSignupEmail, normalizeEmail, storeSignupToken } from "../signup-token-store";
 
 const SIGNUP_NOTIFICATION_TYPE = "auth-email-password:signup-activation";
@@ -68,6 +69,16 @@ export function createSignupRequestHandler(opts: SignupRequestOptions) {
     schema: SignupRequestSchema,
     access: { roles: ["all"] },
     handler: async (event, ctx) => {
+      // Silent no-op when off, matching the route's own always-200
+      // anti-enumeration contract (registerTokenRequestRoute swallows every
+      // handler failure into `{isSuccess:true}` regardless) — no mail goes
+      // out, but the caller can't distinguish "disabled" from "unknown
+      // 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))) {
+        return { isSuccess: true, data: { kind: "no-op" } };
+      }
       if (!ctx.redis) {
         return writeFailure(
           new InternalError({

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

@@ -7,7 +7,7 @@
 // its own changeset + deliberate deprecation window, not a silent drop.
 export { hashPassword, verifyPassword } from "../shared/password-hashing";
 export { type AuthPaths, DEFAULT_AUTH_PATHS, makeAuthPaths } from "./auth-paths";
-export { AUTH_EMAIL_PASSWORD_FEATURE, AuthErrors, AuthHandlers } from "./constants";
+export { AUTH_EMAIL_PASSWORD_FEATURE, AuthErrors, AuthHandlers, AuthQueries } from "./constants";
 // Renderers for the auth mails. All four magic-link flows (reset, verify,
 // signup-activation, invite) emit structured AuthMailContent through delivery
 // (ctx.notify).
@@ -35,6 +35,10 @@ export type {
   SignupOptions,
 } from "./feature";
 export { authEmailPasswordEnvSchema, createAuthEmailPasswordFeature } from "./feature";
+export {
+  AUTH_SELF_REGISTRATION_FEATURE,
+  createAuthSelfRegistrationToggleFeature,
+} from "./self-registration-toggle";
 // Generic HMAC-signed single-purpose token helpers. Re-exported damit
 // app-spezifische out-of-band-Flows (subscriber-confirm, magic-links,
 // invite-tokens) denselben battle-tested signer/verifier nutzen können

package/src/auth-email-password/self-registration-toggle.ts

@@ -0,0 +1,25 @@
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+
+// Companion toggle for the auth-email-password self-signup flow. Handler-less
+// (like managed-pages-css/css-gate.ts): composing it just registers
+// "auth-self-registration" as toggleable (default ON) so an operator can
+// flip it at runtime via feature-toggles, without redeploying and without
+// making the rest of auth-email-password (login/reset/verify) toggleable.
+//
+// Deliberately owns NO handlers — the dispatcher's per-feature gate blocks
+// every handler belonging to a disabled feature, and a `status` query living
+// here would become unreachable exactly when it matters most (disabled).
+// The signup-request handler and the `signupRegistrationStatus` query both
+// live in auth-email-password itself and read `ctx.hasFeature(...)` against
+// this feature name instead — same split as managed-pages/css-gate.ts vs.
+// managed-pages' branding query.
+export const AUTH_SELF_REGISTRATION_FEATURE = "auth-self-registration";
+
+export function createAuthSelfRegistrationToggleFeature(): FeatureDefinition {
+  return defineFeature(AUTH_SELF_REGISTRATION_FEATURE, (r) => {
+    r.describe(
+      'Runtime on/off switch for the auth-email-password self-signup flow. Handler-less: composing it registers "auth-self-registration" as a toggleable feature (default ON). auth-email-password\'s signup-request handler and its `signupRegistrationStatus` query both read `ctx.hasFeature("auth-self-registration")` — the query stays reachable when the toggle is off (deliberately not gated itself) so the public signup page can hide its own link/form. Only meaningful when `signup` is configured on `createAuthEmailPasswordFeature` — compose alongside it, then flip via the feature-toggles admin screen.',
+    );
+    r.toggleable({ default: true });
+  });
+}

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

@@ -70,6 +70,43 @@ describe("createLoginRoute", () => {
     return <div data-testid="mfa-verify">{challengeToken}</div>;
   }
 
+  function LoginWithMfaSetupTrigger({
+    onMfaSetupRequired,
+  }: {
+    readonly onMfaSetupRequired?: (preauthSetupToken: string, accountLabel: string) => void;
+  }): ReactNode {
+    return (
+      <button
+        type="button"
+        data-testid="trigger-mfa-setup"
+        onClick={() => onMfaSetupRequired?.("setup-token-123", "user@example.com")}
+      >
+        trigger
+      </button>
+    );
+  }
+
+  function CustomMfaSetup({
+    preauthSetupToken,
+    accountLabel,
+    onSuccess,
+  }: {
+    readonly preauthSetupToken: string;
+    readonly accountLabel: string;
+    readonly onSuccess?: () => void;
+  }): ReactNode {
+    return (
+      <div data-testid="mfa-setup">
+        <span data-testid="mfa-setup-info">
+          {preauthSetupToken}:{accountLabel}
+        </span>
+        <button type="button" data-testid="complete-mfa-setup" onClick={() => onSuccess?.()}>
+          complete
+        </button>
+      </div>
+    );
+  }
+
   test("authenticated + onAuthenticated → renders nothing, fires onAuthenticated exactly once", () => {
     const onAuthenticated = mock(() => {});
     const LoginRoute = createLoginRoute({ loginScreen: CustomLogin, onAuthenticated });
@@ -109,4 +146,46 @@ describe("createLoginRoute", () => {
     fireEvent.click(screen.getByTestId("trigger-mfa"));
     expect(screen.getByTestId("mfa-verify").textContent).toBe("token-123");
   });
+
+  test("onMfaSetupRequired → renders MfaSetupComponent with token and accountLabel", () => {
+    const LoginRoute = createLoginRoute({
+      loginScreen: LoginWithMfaSetupTrigger,
+      mfaSetupScreen: CustomMfaSetup,
+    });
+    const session = makeSessionApi({ status: "unauthenticated" });
+    renderWithProviders(<LoginRoute />, { session });
+    fireEvent.click(screen.getByTestId("trigger-mfa-setup"));
+    expect(screen.getByTestId("mfa-setup-info").textContent).toBe(
+      "setup-token-123:user@example.com",
+    );
+  });
+
+  test("MfaSetupComponent onSuccess → gate clears the request and refreshes the session", () => {
+    const LoginRoute = createLoginRoute({
+      loginScreen: LoginWithMfaSetupTrigger,
+      mfaSetupScreen: CustomMfaSetup,
+    });
+    const session = makeSessionApi({ status: "unauthenticated" });
+    renderWithProviders(<LoginRoute />, { session });
+    fireEvent.click(screen.getByTestId("trigger-mfa-setup"));
+    expect(screen.getByTestId("mfa-setup")).toBeTruthy();
+    fireEvent.click(screen.getByTestId("complete-mfa-setup"));
+    expect(session.refresh).toHaveBeenCalledTimes(1);
+    expect(screen.queryByTestId("mfa-setup")).toBeNull();
+  });
+
+  test("makeAuthGate delegates mfaSetupScreen wiring to createLoginRoute", () => {
+    const Gate = makeAuthGate(LoginWithMfaSetupTrigger, undefined, undefined, CustomMfaSetup);
+    const session = makeSessionApi({ status: "unauthenticated" });
+    renderWithProviders(
+      <Gate>
+        <div data-testid="protected">secret</div>
+      </Gate>,
+      { session },
+    );
+    fireEvent.click(screen.getByTestId("trigger-mfa-setup"));
+    expect(screen.getByTestId("mfa-setup-info").textContent).toBe(
+      "setup-token-123:user@example.com",
+    );
+  });
 });

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

@@ -336,7 +336,7 @@ describe("LoginScreen", () => {
   });
 
   test("mfa-setup-required with and without onMfaSetupRequired", async () => {
-    const onMfaSetupRequired = mock<() => void>();
+    const onMfaSetupRequired = mock<(preauthSetupToken: string, accountLabel: string) => void>();
     const sessionOk = makeSessionApi({
       status: "unauthenticated",
       user: null,
@@ -353,7 +353,7 @@ describe("LoginScreen", () => {
     fireEvent.change(screen.getByLabelText(/^Passwort/), { target: { value: "x" } });
     fireEvent.click(screen.getByRole("button", { name: "Einloggen" }));
     await waitFor(() => {
-      expect(onMfaSetupRequired).toHaveBeenCalled();
+      expect(onMfaSetupRequired).toHaveBeenCalledWith("setup-token-value", "a@b.c");
     });
     unmount();
 

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

@@ -23,10 +23,21 @@ export type MfaVerifyComponentProps = {
   readonly onCancel?: () => void;
 };
 
+// Same coupling reasoning as MfaVerifyComponentProps above — generic, not
+// auth-mfa's MfaSetupPreauthScreenProps directly. Apps wire auth-mfa's
+// MfaSetupPreauthScreen in here via EmailPasswordClientOptions.
+export type MfaSetupComponentProps = {
+  readonly preauthSetupToken: string;
+  readonly accountLabel: string;
+  readonly onSuccess?: () => void;
+  readonly onCancel?: () => void;
+};
+
 export type LoginRouteOptions = {
   readonly loginScreen?: ComponentType<LoginScreenProps>;
   readonly loginScreenProps?: LoginScreenProps;
   readonly mfaVerifyScreen?: ComponentType<MfaVerifyComponentProps>;
+  readonly mfaSetupScreen?: ComponentType<MfaSetupComponentProps>;
   /** Called once the session becomes authenticated. makeAuthGate ignores
    *  this (it renders `children` on its own authenticated branch instead);
    *  standalone routes — no parent gate, e.g. an anonymous apex/marketing
@@ -51,14 +62,19 @@ export function createLoginRoute(
 ): ComponentType<Record<string, never>> {
   const LoginComponent = opts.loginScreen ?? LoginScreen;
   const MfaVerifyComponent = opts.mfaVerifyScreen;
+  const MfaSetupComponent = opts.mfaSetupScreen;
 
   function LoginRoute(): ReactNode {
-    const { status } = useSession();
+    const { status, refresh } = 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
     // never considers this session authenticated until verify succeeds.
     const [challengeToken, setChallengeToken] = useState<string | null>(null);
+    const [setupRequest, setSetupRequest] = useState<{
+      readonly preauthSetupToken: string;
+      readonly accountLabel: string;
+    } | null>(null);
 
     useEffect(() => {
       if (status === "authenticated") onAuthenticated?.();
@@ -85,12 +101,35 @@ export function createLoginRoute(
         />
       );
     }
+    // Pending preauthSetupToken from LoginScreen's onMfaSetupRequired. Same
+    // reasoning as challengeToken — a UI-only transition, not session state.
+    if (setupRequest !== null && MfaSetupComponent) {
+      return (
+        <MfaSetupComponent
+          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();
+          }}
+          onCancel={() => setSetupRequest(null)}
+        />
+      );
+    }
     return (
       <LoginComponent
         {...opts.loginScreenProps}
         onMfaChallenge={
           MfaVerifyComponent ? setChallengeToken : opts.loginScreenProps?.onMfaChallenge
         }
+        onMfaSetupRequired={
+          MfaSetupComponent
+            ? (preauthSetupToken, accountLabel) =>
+                setSetupRequest({ preauthSetupToken, accountLabel })
+            : opts.loginScreenProps?.onMfaSetupRequired
+        }
       />
     );
   }
@@ -101,11 +140,13 @@ 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,
   });
   function AuthGate({ children }: { readonly children: ReactNode }): ReactNode {
     const { status } = useSession();
@@ -122,8 +163,9 @@ export function makeSessionAuthGate(
   LoginComponent: ComponentType<LoginScreenProps> = LoginScreen,
   loginProps?: LoginScreenProps,
   MfaVerifyComponent?: ComponentType<MfaVerifyComponentProps>,
+  MfaSetupComponent?: ComponentType<MfaSetupComponentProps>,
 ): ComponentType<{ children: ReactNode }> {
-  const AuthGate = makeAuthGate(LoginComponent, loginProps, MfaVerifyComponent);
+  const AuthGate = makeAuthGate(LoginComponent, loginProps, MfaVerifyComponent, MfaSetupComponent);
   function SessionAuthGate({ children }: { readonly children: ReactNode }): ReactNode {
     return (
       <SessionProvider>

package/src/auth-email-password/web/login-screen.tsx

@@ -64,10 +64,13 @@ export type LoginScreenProps = {
    *  hang, but apps mounting auth-mfa must wire this. */
   readonly onMfaChallenge?: (challengeToken: string) => void;
   /** Called when the tenant's enforcement policy requires MFA but this
-   *  user has no factor enrolled yet. Apps typically route to an
-   *  enrollment flow. Without a handler, the user sees a "setup required,
-   *  contact your administrator" error. */
-  readonly onMfaSetupRequired?: () => void;
+   *  user has no factor enrolled yet. Carries the preauthSetupToken the
+   *  login response issued plus the typed email (no session to derive it
+   *  from) — apps typically swap this screen out for auth-mfa's
+   *  MfaSetupPreauthScreen(preauthSetupToken, accountLabel). Without a
+   *  handler, the user sees a "setup required, contact your administrator"
+   *  error. */
+  readonly onMfaSetupRequired?: (preauthSetupToken: string, accountLabel: string) => void;
 };
 
 // Map vom Reason-Code des Login-Handlers auf einen i18n-Key plus
@@ -147,7 +150,7 @@ export function LoginScreen({
     }
     if (res.kind === "mfa-setup-required") {
       if (onMfaSetupRequired) {
-        onMfaSetupRequired();
+        onMfaSetupRequired(res.preauthSetupToken, email);
         return;
       }
       setError({ reason: "mfa_setup_required" });