@cosmicdrift/kumiko-bundled-features 0.160.0 → 0.162.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.160.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.160.0",
-    "@cosmicdrift/kumiko-framework": "0.160.0",
-    "@cosmicdrift/kumiko-headless": "0.160.0",
-    "@cosmicdrift/kumiko-renderer": "0.160.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.160.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__/login-mfa-setup-required.integration.test.ts

@@ -0,0 +1,129 @@
+// #1455: enforcement policy blocks an unenrolled user at login
+// (mfa-setup-required) — the response must carry a preauthSetupToken so a
+// later pre-auth enroll step (#1231) can look the user back up without a
+// session. Real HTTP through setupTestStack, both auth-mfa and
+// auth-email-password mounted together (mirrors auth.integration.test.ts).
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { randomBytes } from "node:crypto";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { createTestEnvelopeCipher } from "@cosmicdrift/kumiko-framework/testing";
+import {
+  createAuthMfaFeature,
+  mfaRequiredConfigHandle,
+  mfaStatusCheckerFromFeature,
+} from "../../auth-mfa";
+import { userMfaEntity } from "../../auth-mfa/schema/user-mfa";
+import { ConfigHandlers, createConfigFeature } from "../../config";
+import { createConfigResolver } from "../../config/resolver";
+import { configValuesTable } from "../../config/table";
+import { hashPassword } from "../../shared";
+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, userTable } from "../../user/schema/user";
+import { AuthErrors, AuthHandlers } from "../constants";
+import { createAuthEmailPasswordFeature } from "../feature";
+
+let stack: TestStack;
+
+const CHALLENGE_TOKEN_SECRET = "test-mfa-challenge-secret-at-least-32-bytes!!";
+const TENANT_ID: TenantId = testTenantId(400);
+
+beforeAll(async () => {
+  const encryption = createTestEnvelopeCipher(randomBytes(32).toString("base64"));
+  const resolver = createConfigResolver({ cipher: encryption });
+  const authMfaFeature = createAuthMfaFeature({
+    setupTokenSecret: "test-mfa-setup-token-secret-at-least-32-bytes!!",
+    issuer: "Kumiko Test",
+    challengeTokenSecret: CHALLENGE_TOKEN_SECRET,
+  });
+
+  stack = await setupTestStack({
+    features: [
+      createConfigFeature(),
+      createUserFeature(),
+      createTenantFeature(),
+      authMfaFeature,
+      createAuthEmailPasswordFeature({
+        mfaStatusChecker: mfaStatusCheckerFromFeature(authMfaFeature),
+      }),
+    ],
+    extraContext: { configResolver: resolver, configEncryption: encryption },
+    authConfig: {
+      membershipQuery: "tenant:query:memberships",
+      loginHandler: AuthHandlers.login,
+      loginErrorStatusMap: {
+        [AuthErrors.invalidCredentials]: 401,
+        [AuthErrors.noMembership]: 403,
+      },
+    },
+  });
+
+  await unsafeCreateEntityTable(stack.db, userEntity);
+  await unsafeCreateEntityTable(stack.db, tenantEntity);
+  await unsafeCreateEntityTable(stack.db, userMfaEntity);
+  await unsafePushTables(stack.db, { configValuesTable, tenantMembershipsTable });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${userTable.tableName}"`);
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${tenantMembershipsTable.tableName}"`);
+});
+
+describe("login: mfa-setup-required carries a verifiable preauthSetupToken", () => {
+  test("unenrolled user blocked by 'all' policy gets a token instead of a session", async () => {
+    const password = "correct-horse-battery-2026";
+    const hash = await hashPassword(password);
+    const created = await stack.http.writeOk<{ id: string }>(
+      UserHandlers.create,
+      { email: "unenrolled@example.com", passwordHash: hash, displayName: "Unenrolled" },
+      createTestUser({ id: 401, tenantId: TENANT_ID, roles: ["SystemAdmin"] }),
+    );
+    await seedTenantMembership(stack.db, {
+      userId: created.id,
+      tenantId: TENANT_ID,
+      roles: ["User"],
+    });
+    await stack.http.writeOk(
+      ConfigHandlers.set,
+      { key: mfaRequiredConfigHandle.name, value: "all" },
+      createTestUser({ id: 402, tenantId: TENANT_ID, roles: ["Admin"] }),
+    );
+
+    const res = await stack.http.raw("POST", "/api/auth/login", {
+      email: "unenrolled@example.com",
+      password,
+    });
+
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.isSuccess).toBe(true);
+    expect(body.mfaSetupRequired).toBe(true);
+    expect(body.token).toBeUndefined();
+    expect(typeof body.preauthSetupToken).toBe("string");
+
+    const { verifyMfaPreauthSetupToken } = await import("../../auth-mfa/mfa-preauth-setup-token");
+    const verified = verifyMfaPreauthSetupToken(body.preauthSetupToken, CHALLENGE_TOKEN_SECRET);
+    expect(verified.ok).toBe(true);
+    if (verified.ok) {
+      expect(verified.payload).toEqual({ userId: created.id, tenantId: TENANT_ID });
+    }
+  });
+});

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/__tests__/session-callbacks.integration.test.ts

@@ -158,6 +158,11 @@ async function seedUser(opts: {
       roles: t.roles,
     });
   }
+  // request-helper mints a sid for systemAdmin when sessionCreator is wired
+  // (#1372) — that is seed plumbing, not the auth-route behavior under test.
+  store.live.clear();
+  store.created.length = 0;
+  store.revoked.length = 0;
   return { userId: created.id };
 }
 

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/login.write.ts

@@ -58,7 +58,7 @@ export type LoginHandlerOptions = {
   ) => Promise<
     | { readonly required: false }
     | { readonly required: true; readonly challengeToken: string }
-    | { readonly setupRequired: true }
+    | { readonly setupRequired: true; readonly preauthSetupToken: string }
   >;
 };
 
@@ -70,7 +70,7 @@ const SYSTEM_USER_ID = "00000000-0000-4000-8000-000000000000";
 type LoginResult =
   | { readonly kind: "auth-session"; readonly session: SessionUser }
   | { readonly kind: "mfa-challenge"; readonly challengeToken: string }
-  | { readonly kind: "mfa-setup-required" };
+  | { readonly kind: "mfa-setup-required"; readonly preauthSetupToken: string };
 
 // Login — unauthenticated entry point. The route is wired public (no JWT
 // middleware), synthesising a guest SessionUser for the handler's access
@@ -226,7 +226,10 @@ export function createLoginHandler(opts: LoginHandlerOptions = {}) {
           };
         }
         if ("setupRequired" in mfaStatus) {
-          return { isSuccess: true, data: { kind: "mfa-setup-required" } };
+          return {
+            isSuccess: true,
+            data: { kind: "mfa-setup-required", preauthSetupToken: mfaStatus.preauthSetupToken },
+          };
         }
       }
 

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/i18n.ts

@@ -35,6 +35,8 @@ export const defaultTranslations: TranslationsByLocale = {
     "auth.errors.loginFailed": "Login fehlgeschlagen.",
     "auth.errors.mfaNotSupported":
       "Diese App unterstützt keine Zwei-Faktor-Bestätigung. Bitte an den Support wenden.",
+    "auth.errors.mfaSetupRequired":
+      "Zwei-Faktor-Authentifizierung erforderlich. Bitte an den Administrator wenden.",
     "auth.errors.invalidResetToken":
       "Der Link ist ungültig oder abgelaufen. Bitte fordere einen neuen an.",
     "auth.errors.invalidVerificationToken": "Der Bestätigungs-Link ist ungültig oder abgelaufen.",
@@ -161,6 +163,8 @@ export const defaultTranslations: TranslationsByLocale = {
     "auth.errors.loginFailed": "Login failed.",
     "auth.errors.mfaNotSupported":
       "This app doesn't support two-factor verification. Please contact support.",
+    "auth.errors.mfaSetupRequired":
+      "Two-factor authentication required. Please contact your administrator.",
     "auth.errors.invalidResetToken": "Link is invalid or expired. Please request a new one.",
     "auth.errors.invalidVerificationToken": "Verification link is invalid or expired.",
     "auth.errors.invalidUnlockToken":

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-client.test.ts

@@ -95,12 +95,16 @@ describe("login", () => {
 
   test("MFA enforcement blocks unenrolled user → kind:mfa-setup-required", async () => {
     globalThis.fetch = mock(async () =>
-      jsonResponse({ isSuccess: true, mfaSetupRequired: true }),
+      jsonResponse({
+        isSuccess: true,
+        mfaSetupRequired: true,
+        preauthSetupToken: "setup-token-value",
+      }),
     ) as unknown as typeof fetch;
 
     const res = await login({ email: "a@b.c", password: "secret" });
 
-    expect(res).toEqual({ kind: "mfa-setup-required" });
+    expect(res).toEqual({ kind: "mfa-setup-required", preauthSetupToken: "setup-token-value" });
   });
 
   test("string error → kind:failure with reason from string", async () => {

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",
+    );
+  });
 });