@cosmicdrift/kumiko-bundled-features 0.147.1 → 0.147.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.147.1",
+  "version": "0.147.2",
   "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>",
@@ -88,6 +88,9 @@
     "./presets": "./src/presets/index.ts",
     "./secrets": "./src/secrets/index.ts",
     "./sessions": "./src/sessions/index.ts",
+    "./auth-mfa": "./src/auth-mfa/index.ts",
+    "./auth-mfa-user-data": "./src/auth-mfa-user-data/index.ts",
+    "./auth-mfa/web": "./src/auth-mfa/web/index.ts",
     "./sessions/testing": "./src/sessions/testing.ts",
     "./personal-access-tokens": "./src/personal-access-tokens/index.ts",
     "./personal-access-tokens/web": "./src/personal-access-tokens/web/index.ts",
@@ -111,11 +114,11 @@
     "./step-dispatcher": "./src/step-dispatcher/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.147.1",
-    "@cosmicdrift/kumiko-framework": "0.147.1",
-    "@cosmicdrift/kumiko-headless": "0.147.1",
-    "@cosmicdrift/kumiko-renderer": "0.147.1",
-    "@cosmicdrift/kumiko-renderer-web": "0.147.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.147.2",
+    "@cosmicdrift/kumiko-framework": "0.147.2",
+    "@cosmicdrift/kumiko-headless": "0.147.2",
+    "@cosmicdrift/kumiko-renderer": "0.147.2",
+    "@cosmicdrift/kumiko-renderer-web": "0.147.2",
     "@mollie/api-client": "^4.5.0",
     "imapflow": "^1.3.3",
     "mailparser": "^3.9.8",
@@ -125,6 +128,7 @@
     "lucide-react": "^1.14.0",
     "marked": "^18.0.3",
     "nodemailer": "^9.0.1",
+    "qrcode": "^1.5.4",
     "react": "^19.2.6",
     "stripe": "^22.1.1",
     "tailwind-merge": "^3.6.0"
@@ -140,6 +144,7 @@
   ],
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
-    "@types/mailparser": "^3.4.6"
+    "@types/mailparser": "^3.4.6",
+    "@types/qrcode": "^1.5.5"
   }
 }

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

@@ -10,7 +10,7 @@ import {
   type InviteCreateOptions,
 } from "./handlers/invite-create.write";
 import { createInviteSignupCompleteHandler } from "./handlers/invite-signup-complete.write";
-import { createLoginHandler } from "./handlers/login.write";
+import { createLoginHandler, type LoginHandlerOptions } from "./handlers/login.write";
 import { logoutWrite } from "./handlers/logout.write";
 import { createRequestEmailVerificationHandler } from "./handlers/request-email-verification.write";
 import { createRequestPasswordResetHandler } from "./handlers/request-password-reset.write";
@@ -110,6 +110,10 @@ export type SignupOptions = SignupRequestOptions;
 export type InviteOptions = InviteCreateOptions;
 
 export type AuthEmailPasswordOptions = {
+  // Second-factor gate. auth-mfa (if mounted) wires this in via
+  // mfaStatusCheckerFromFeature() at app-composition time — see
+  // LoginHandlerOptions.mfaStatusChecker for the contract it must satisfy.
+  readonly mfaStatusChecker?: LoginHandlerOptions["mfaStatusChecker"];
   readonly passwordReset?: PasswordResetOptions;
   readonly emailVerification?: EmailVerificationOptions;
   readonly accountLockout?: AccountLockoutOptions;
@@ -175,6 +179,7 @@ export function createAuthEmailPasswordFeature(
         createLoginHandler({
           strictEmailVerification: strictVerification,
           accountLockout: opts.accountLockout,
+          mfaStatusChecker: opts.mfaStatusChecker,
         }),
       ),
       changePassword: r.writeHandler(changePasswordWrite),

package/src/auth-email-password/handlers/confirm-token-flow.ts

@@ -31,10 +31,10 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import type Redis from "ioredis";
+import { burnToken, unburnToken } from "../../shared";
 import { UserHandlers, UserQueries } from "../../user";
 import type { AuthUserRow } from "../auth-user-row";
 import { parseAuthUserRow } from "../auth-user-row";
-import { burnToken, unburnToken } from "../token-burn-store";
 
 export type ConfirmTokenFlowSpec<TSuccessData> = {
   // Short purpose-tag used in the burn-store key. Must NOT overlap with

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

@@ -1,9 +1,11 @@
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
 import {
   buildSessionRoles,
   createSystemUser,
   defineWriteHandler,
   type SessionUser,
   type TenantId,
+  type WriteResult,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { parseRoles } from "@cosmicdrift/kumiko-framework/utils";
 import { z } from "zod";
@@ -40,10 +42,36 @@ export type LoginHandlerOptions = {
     readonly maxFailedAttempts?: number;
     readonly lockoutDurationMinutes?: number;
   };
+  // Optional second-factor gate. auth-mfa (if mounted) wires this in at
+  // app-composition time. Deliberately generic here — auth-email-password
+  // must not import auth-mfa's config, only this shape. Called AFTER a
+  // successful password verification (never before — the point is to add
+  // a second factor to a real credential match, not to gate on identity
+  // alone).
+  readonly mfaStatusChecker?: (
+    ctx: HandlerContext,
+    userId: string,
+    tenantId: TenantId,
+    // Merged global+tenant roles, computed by this handler BEFORE the
+    // gate runs — needed for policy values like "admins" that key off role.
+    roles: readonly string[],
+  ) => Promise<
+    | { readonly required: false }
+    | { readonly required: true; readonly challengeToken: string }
+    | { readonly setupRequired: true }
+  >;
 };
 
 const SYSTEM_USER_ID = "00000000-0000-4000-8000-000000000000";
 
+// Two possible success shapes: a straight login mints a session; a login
+// gated by MFA hands back a challenge instead — auth-routes.ts branches on
+// `kind` to decide whether to mint a JWT now or wait for /auth/mfa/verify.
+type LoginResult =
+  | { readonly kind: "auth-session"; readonly session: SessionUser }
+  | { readonly kind: "mfa-challenge"; readonly challengeToken: string }
+  | { readonly kind: "mfa-setup-required" };
+
 // Login — unauthenticated entry point. The route is wired public (no JWT
 // middleware), synthesising a guest SessionUser for the handler's access
 // check. Everything inside the handler goes through ctx.queryAs(system, ...)
@@ -62,7 +90,7 @@ export function createLoginHandler(opts: LoginHandlerOptions = {}) {
       password: z.string().min(1),
     }),
     access: { roles: ["all"] },
-    handler: async (event, ctx) => {
+    handler: async (event, ctx): Promise<WriteResult<LoginResult>> => {
       const systemUser = createSystemUser(SYSTEM_USER_ID);
 
       const found = parseAuthUserRow(
@@ -110,6 +138,17 @@ export function createLoginHandler(opts: LoginHandlerOptions = {}) {
         return invalidCredentials();
       }
 
+      // Clear the lockout state as soon as the password is proven — the
+      // password itself is the thing this counter guards, and MFA (if
+      // gated below) has its own separate attempt-cap. Doing this before
+      // the MFA gate matters: without it, an MFA user who occasionally
+      // mistypes their password accumulates failures across otherwise-
+      // successful logins and eventually gets password-locked out even
+      // though every login they completed was legitimate.
+      if (ctx.redis) {
+        await clearLockoutState(ctx.redis, found.id);
+      }
+
       // Strict verification gate — runs AFTER password check so an attacker
       // probing "email_not_verified" needs valid credentials first. The
       // remaining enumeration surface is "valid-cred + unverified" → accepted
@@ -155,24 +194,42 @@ export function createLoginHandler(opts: LoginHandlerOptions = {}) {
         return noMembership();
       }
 
-      // Clear the lockout state on success. DEL is idempotent, so no need
-      // to gate on "was there a counter?" — skipping the Redis round-trip
-      // entirely for users who never failed a login would optimise the hot
-      // path, but the call is microseconds and the branch isn't free either.
-      if (ctx.redis) {
-        await clearLockoutState(ctx.redis, found.id);
-      }
-
       // Globale Rollen aus user.roles + tenant-membership-roles mergen.
       // Globale Rollen (SystemAdmin etc.) bleiben so über alle tenants
       // gleich; tenant-spezifische Rollen (Admin, User) kommen aus der
       // membership. Dedupe via Set damit eine Rolle die in beiden Quellen
       // steht nicht doppelt im Session-Roles landet.
+      //
+      // Computed BEFORE the MFA gate (moved up from its original spot below
+      // baseSession) because the gate's "admins" enforcement policy needs
+      // the MERGED set — a SystemAdmin whose admin-ness lives only in
+      // globalRoles would be missed if only chosen.roles were passed.
       const globalRoles = parseRoles(found.roles ?? null);
       // buildSessionRoles calls stripForbiddenMembershipRoles to strip reserved
       // only (globalRoles keeps SystemAdmin) — read-time backstop against a
       // rebuild-resurrected role.
       const mergedRoles = buildSessionRoles(globalRoles, chosen.roles);
+
+      // Second-factor gate. Runs AFTER password verification (correct
+      // credentials proven) and AFTER tenant resolution (need chosen.tenantId
+      // to scope the MFA-enabled check). Three outcomes: enrolled → mint a
+      // challenge instead of a session (/auth/mfa/verify completes the
+      // login); policy demands MFA but the user never enrolled → block with
+      // mfa-setup-required (no session, no challenge — see auth-mfa's
+      // config.ts for why this deliberately hard-blocks); neither → proceed.
+      if (opts.mfaStatusChecker) {
+        const mfaStatus = await opts.mfaStatusChecker(ctx, found.id, chosen.tenantId, mergedRoles);
+        if ("challengeToken" in mfaStatus) {
+          return {
+            isSuccess: true,
+            data: { kind: "mfa-challenge", challengeToken: mfaStatus.challengeToken },
+          };
+        }
+        if ("setupRequired" in mfaStatus) {
+          return { isSuccess: true, data: { kind: "mfa-setup-required" } };
+        }
+      }
+
       const baseSession: SessionUser = {
         id: found.id,
         tenantId: chosen.tenantId,

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

@@ -2,6 +2,7 @@ import { beforeEach, describe, expect, mock, test } from "bun:test";
 import { fireEvent, screen, waitFor } from "@testing-library/react";
 
 import { LoginScreen } from "../login-screen";
+import type { SessionApi } from "../session";
 import { makeSessionApi, renderWithProviders } from "./test-utils";
 
 const requestEmailVerificationMock = mock<() => Promise<unknown>>(() => Promise.resolve());
@@ -48,7 +49,10 @@ describe("LoginScreen", () => {
     const session = makeSessionApi({
       status: "unauthenticated",
       user: null,
-      login: mock(async () => ({ ok: false, error: { reason: "invalid_credentials" } })),
+      login: mock<SessionApi["login"]>(async () => ({
+        kind: "failure",
+        error: { reason: "invalid_credentials" },
+      })),
     });
     renderWithProviders(<LoginScreen />, { session });
 
@@ -70,8 +74,8 @@ describe("LoginScreen", () => {
     const session = makeSessionApi({
       status: "unauthenticated",
       user: null,
-      login: mock(async () => ({
-        ok: false,
+      login: mock<SessionApi["login"]>(async () => ({
+        kind: "failure",
         error: { reason: "account_locked", retryAfterSeconds: 540 },
       })),
     });
@@ -148,7 +152,10 @@ describe("LoginScreen", () => {
       return makeSessionApi({
         status: "unauthenticated",
         user: null,
-        login: mock(async () => ({ ok: false, error: { reason: "email_not_verified" } })),
+        login: mock<SessionApi["login"]>(async () => ({
+          kind: "failure",
+          error: { reason: "email_not_verified" },
+        })),
       });
     }
 
@@ -230,7 +237,10 @@ describe("LoginScreen", () => {
       const session = makeSessionApi({
         status: "unauthenticated",
         user: null,
-        login: mock(async () => ({ ok: false, error: { reason: "invalid_credentials" } })),
+        login: mock<SessionApi["login"]>(async () => ({
+          kind: "failure",
+          error: { reason: "invalid_credentials" },
+        })),
       });
       renderWithProviders(<LoginScreen />, { session });
       await loginUntilEmailNotVerified();

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

@@ -26,9 +26,10 @@ export type MakeSessionApiOptions = Partial<SessionState> & {
   readonly login?: SessionApi["login"];
   readonly logout?: SessionApi["logout"];
   readonly switchTenant?: SessionApi["switchTenant"];
+  readonly refresh?: SessionApi["refresh"];
 };
 export function makeSessionApi(overrides: MakeSessionApiOptions = {}): SessionApi {
-  const { login, logout, switchTenant, ...stateOverrides } = overrides;
+  const { login, logout, switchTenant, refresh, ...stateOverrides } = overrides;
   const base: SessionState = {
     status: "authenticated",
     user: {
@@ -44,9 +45,18 @@ export function makeSessionApi(overrides: MakeSessionApiOptions = {}): SessionAp
   };
   return {
     ...base,
-    login: login ?? mock<SessionApi["login"]>(async () => ({ ok: true })),
+    login:
+      login ??
+      mock<SessionApi["login"]>(async () => ({
+        kind: "success",
+        data: {
+          token: "test-token",
+          user: { id: "test-user", tenantId: "tenant-1", roles: ["Admin"] },
+        },
+      })),
     logout: logout ?? mock<SessionApi["logout"]>(async () => {}),
     switchTenant: switchTenant ?? mock<SessionApi["switchTenant"]>(async () => {}),
+    refresh: refresh ?? mock<SessionApi["refresh"]>(async () => {}),
   };
 }
 export function renderWithProviders(

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

@@ -45,13 +45,24 @@ export function csrfHeader(): Record<string, string> {
   return token !== undefined ? { [CSRF_HEADER_NAME]: token } : {};
 }
 
-// POST /api/auth/login. Erfolg → token + user; Fehler → strukturiertes
-// failure-objekt mit reason (invalid_credentials, account_locked,
-// no_membership, rate_limited). Das UI rendert darüber eine passende
-// Fehler-Meldung; der Server setzt Cookies bei 200 automatisch.
-export async function login(
-  req: LoginRequest,
-): Promise<{ ok: true; data: LoginResponse } | { ok: false; error: LoginFailure }> {
+// 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),
+// or a plain failure. One discriminated union, not `{ok}` booleans, because
+// callers branch on 4 arms.
+export type LoginResult =
+  | { readonly kind: "success"; readonly data: LoginResponse }
+  | { readonly kind: "mfa-challenge"; readonly challengeToken: string }
+  | { readonly kind: "mfa-setup-required" }
+  | { readonly kind: "failure"; readonly error: LoginFailure };
+
+// POST /api/auth/login. Success → token + user; MFA-enrolled user → a
+// challenge token the caller completes via auth-mfa's verify screen;
+// unenrolled user blocked by enforcement policy → mfa-setup-required;
+// otherwise a structured failure with reason (invalid_credentials,
+// account_locked, no_membership, rate_limited). The server sets cookies
+// automatically on any 200.
+export async function login(req: LoginRequest): Promise<LoginResult> {
   const res = await fetch("/api/auth/login", {
     method: "POST",
     credentials: "same-origin",
@@ -59,13 +70,16 @@ export async function login(
     body: JSON.stringify(req),
   });
   if (res.status === 429) {
-    return { ok: false, error: { reason: "rate_limited" } };
+    return { kind: "failure", error: { reason: "rate_limited" } };
   }
   // @cast-boundary engine-payload — HTTP-API contract, server-side schema-validated
   const body = (await res.json().catch(() => ({}))) as {
     isSuccess?: boolean;
     token?: string;
     user?: LoginResponse["user"];
+    mfaRequired?: boolean;
+    challengeToken?: string;
+    mfaSetupRequired?: boolean;
     error?:
       | {
           code?: string;
@@ -74,19 +88,27 @@ export async function login(
         }
       | string;
   };
-  if (body.isSuccess === true && body.token !== undefined && body.user !== undefined) {
-    return { ok: true, data: { token: body.token, user: body.user } };
+  if (body.isSuccess === true) {
+    if (body.mfaRequired === true && typeof body.challengeToken === "string") {
+      return { kind: "mfa-challenge", challengeToken: body.challengeToken };
+    }
+    if (body.mfaSetupRequired === true) {
+      return { kind: "mfa-setup-required" };
+    }
+    if (body.token !== undefined && body.user !== undefined) {
+      return { kind: "success", data: { token: body.token, user: body.user } };
+    }
   }
   // Der Server schickt error entweder als string ("invalid_body") oder als
   // strukturiertes Objekt. Wir ziehen uns den sprechendsten Reason raus.
   const err = body.error;
   if (typeof err === "string") {
-    return { ok: false, error: { reason: err } };
+    return { kind: "failure", error: { reason: err } };
   }
   const reason = err?.details?.reason ?? err?.code ?? "login_failed";
   const retry = err?.details?.retryAfterSeconds;
   return {
-    ok: false,
+    kind: "failure",
     error: {
       reason,
       ...(err?.message !== undefined && { message: err.message }),

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

@@ -9,23 +9,51 @@
 // (nur `{ children }`-Prop). Der Sample kann so einen eigenen Login-
 // Screen rein konfigurieren, ohne den Gate selbst ersetzen zu müssen.
 
-import type { ComponentType, ReactNode } from "react";
+import { type ComponentType, type ReactNode, useState } from "react";
 import { LoginScreen, type LoginScreenProps } from "./login-screen";
 import { SessionProvider, useSession } from "./session";
 
+// Generic — NOT auth-mfa's MfaVerifyScreenProps directly, so this feature
+// stays unaware of auth-mfa's concrete shape (same coupling direction as
+// login.write.ts's mfaStatusChecker callback on the server side). Apps
+// wire auth-mfa's MfaVerifyScreen in here via EmailPasswordClientOptions.
+export type MfaVerifyComponentProps = {
+  readonly challengeToken: string;
+  readonly onSuccess?: () => void;
+};
+
 export function makeAuthGate(
   LoginComponent: ComponentType<LoginScreenProps> = LoginScreen,
   loginProps?: LoginScreenProps,
+  MfaVerifyComponent?: ComponentType<MfaVerifyComponentProps>,
 ): ComponentType<{ children: ReactNode }> {
   function AuthGate({ children }: { readonly children: ReactNode }): ReactNode {
     const { status } = useSession();
+    // 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);
+
     if (status === "loading") {
       return (
         <div className="min-h-screen flex items-center justify-center text-muted-foreground text-sm" />
       );
     }
     if (status === "unauthenticated") {
-      return <LoginComponent {...loginProps} />;
+      if (challengeToken !== null && MfaVerifyComponent) {
+        return (
+          <MfaVerifyComponent
+            challengeToken={challengeToken}
+            onSuccess={() => setChallengeToken(null)}
+          />
+        );
+      }
+      return (
+        <LoginComponent
+          {...loginProps}
+          onMfaChallenge={MfaVerifyComponent ? setChallengeToken : loginProps?.onMfaChallenge}
+        />
+      );
     }
     return <>{children}</>;
   }
@@ -38,8 +66,9 @@ export function makeAuthGate(
 export function makeSessionAuthGate(
   LoginComponent: ComponentType<LoginScreenProps> = LoginScreen,
   loginProps?: LoginScreenProps,
+  MfaVerifyComponent?: ComponentType<MfaVerifyComponentProps>,
 ): ComponentType<{ children: ReactNode }> {
-  const AuthGate = makeAuthGate(LoginComponent, loginProps);
+  const AuthGate = makeAuthGate(LoginComponent, loginProps, MfaVerifyComponent);
   function SessionAuthGate({ children }: { readonly children: ReactNode }): ReactNode {
     return (
       <SessionProvider>

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

@@ -8,7 +8,7 @@
 import type { TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
 import type { ComponentType, ReactNode } from "react";
 import { defaultTranslations, mergeTranslations } from "../i18n";
-import { makeSessionAuthGate } from "./auth-gate";
+import { type MfaVerifyComponentProps, makeSessionAuthGate } from "./auth-gate";
 import type { LoginScreenProps } from "./login-screen";
 
 export type EmailPasswordClientOptions = {
@@ -17,6 +17,13 @@ export type EmailPasswordClientOptions = {
    *  eine eigene Komponente mit derselben Signatur reichen. */
   readonly loginScreen?: ComponentType<LoginScreenProps>;
   readonly loginScreenProps?: LoginScreenProps;
+  /** auth-mfa's MfaVerifyScreen, wired in from the app so this feature
+   *  stays unaware of auth-mfa's concrete shape. When LoginScreen's
+   *  onMfaChallenge fires, the gate swaps to this component instead of
+   *  requiring the app to own that state itself. Apps not mounting
+   *  auth-mfa simply don't pass this — LoginScreen's built-in fallback
+   *  error covers that case. */
+  readonly mfaVerifyScreen?: ComponentType<MfaVerifyComponentProps>;
   /** 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
@@ -41,7 +48,9 @@ export function emailPasswordClient(
   return {
     name: "auth-email-password",
     providers: [],
-    gates: [makeSessionAuthGate(options.loginScreen, options.loginScreenProps)],
+    gates: [
+      makeSessionAuthGate(options.loginScreen, options.loginScreenProps, options.mfaVerifyScreen),
+    ],
     translations,
   };
 }

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

@@ -11,6 +11,7 @@ export type {
   CurrentUserProfile,
   LoginFailure,
   LoginRequest,
+  LoginResponse,
   ResetPasswordFailure,
   SignupConfirmSuccess,
   TenantSummary,
@@ -24,8 +25,9 @@ export {
   resetPassword,
   verifyEmail,
 } from "./auth-client";
-export type { AuthShellRenderer } from "./auth-form-primitives";
-export { AuthShellProvider, useAuthShell } from "./auth-form-primitives";
+export type { AuthCardProps, AuthShellRenderer } from "./auth-form-primitives";
+export { AuthCard, AuthShellProvider, useAuthShell } from "./auth-form-primitives";
+export type { MfaVerifyComponentProps } from "./auth-gate";
 export { makeAuthGate, makeSessionAuthGate } from "./auth-gate";
 export type {
   EmailPasswordClientFeature,

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

@@ -50,6 +50,16 @@ export type LoginScreenProps = {
    *  Labels kommen vom Caller (typisch schon übersetzt bzw. Eigennamen
    *  wie "Impressum"). */
   readonly legalLinks?: readonly AuthLegalLink[];
+  /** Called when the server responds with an MFA challenge instead of a
+   *  session. Apps typically swap this screen out for auth-mfa's
+   *  MfaVerifyScreen(challengeToken). Without a handler, MFA-enrolled
+   *  users see a generic "not supported" error — better than a silent
+   *  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. Same fallback behavior as onMfaChallenge when unset. */
+  readonly onMfaSetupRequired?: () => void;
 };
 
 // Map vom Reason-Code des Login-Handlers auf einen i18n-Key plus
@@ -90,6 +100,8 @@ export function LoginScreen({
   forgotPasswordHref,
   signupHref,
   legalLinks,
+  onMfaChallenge,
+  onMfaSetupRequired,
 }: LoginScreenProps): ReactNode {
   const t = useTranslation();
   const { Form, Field, Input, Button, Banner, Link } = usePrimitives();
@@ -110,10 +122,27 @@ export function LoginScreen({
     setResendStatus({ kind: "idle" });
     const res = await session.login({ email, password });
     setSubmitting(false);
-    if (!res.ok) {
-      setError(res.error);
+    if (res.kind === "success") return;
+    if (res.kind === "mfa-challenge") {
+      if (onMfaChallenge) {
+        onMfaChallenge(res.challengeToken);
+        return;
+      }
+      setError({ reason: "mfa_not_supported" });
+      setFailedLoginEmail(email);
+      return;
+    }
+    if (res.kind === "mfa-setup-required") {
+      if (onMfaSetupRequired) {
+        onMfaSetupRequired();
+        return;
+      }
+      setError({ reason: "mfa_not_supported" });
       setFailedLoginEmail(email);
+      return;
     }
+    setError(res.error);
+    setFailedLoginEmail(email);
   };
 
   const onSubmit = (e?: FormEvent): void => {

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

@@ -15,8 +15,8 @@ import {
   type CurrentUserProfile,
   fetchCurrentUser,
   fetchTenants,
-  type LoginFailure,
   type LoginRequest,
+  type LoginResult,
   login as loginApi,
   logout as logoutApi,
   switchTenant as switchTenantApi,
@@ -39,9 +39,13 @@ export type SessionState = {
 };
 
 export type SessionApi = SessionState & {
-  readonly login: (req: LoginRequest) => Promise<{ ok: true } | { ok: false; error: LoginFailure }>;
+  readonly login: (req: LoginRequest) => Promise<LoginResult>;
   readonly logout: () => Promise<void>;
   readonly switchTenant: (tenantId: string) => Promise<void>;
+  /** Re-runs the /auth/tenants + user:me refresh round without a full page
+   *  reload. Used by auth-mfa's verify screen after a challenge completes
+   *  and mints cookies via a route session.tsx never calls directly. */
+  readonly refresh: () => Promise<void>;
 };
 
 // Exported so screens that render on BOTH authenticated and anonymous public
@@ -131,9 +135,10 @@ export function SessionProvider({ children }: { readonly children: ReactNode }):
   const login = useCallback<SessionApi["login"]>(
     async (req) => {
       const res = await loginApi(req);
-      if (!res.ok) return { ok: false, error: res.error };
-      await doRefresh();
-      return { ok: true };
+      if (res.kind === "success") {
+        await doRefresh();
+      }
+      return res;
     },
     [doRefresh],
   );
@@ -161,7 +166,7 @@ export function SessionProvider({ children }: { readonly children: ReactNode }):
     }
   }, []);
 
-  const api: SessionApi = { ...state, login, logout, switchTenant };
+  const api: SessionApi = { ...state, login, logout, switchTenant, refresh: doRefresh };
   return <SessionContext.Provider value={api}>{children}</SessionContext.Provider>;
 }