@cosmicdrift/kumiko-samples 0.353.0 → 0.354.0

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

@@ -21,26 +21,15 @@
 // suppressing the link on the request side would be defense-in-depth, but
 // with an enumeration risk of its own (separate concern).
 
-import { generateToken } from "@cosmicdrift/kumiko-framework/api";
 import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
-import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import * as z from "zod";
 import { findSignupHandoverProvider, type SignupHandoverBinding } from "../../shared/index.js";
-import { AUTH_SIGNUP_DEFAULT_TTL_MINUTES } from "../constants.js";
 import type { AuthMailLocale } from "../email-templates.js";
-import { renderActivationEmail } from "../email-templates.js";
-import { dispatchMagicLinkMail, resolveHandlerMailLocale } from "../magic-link-mail.js";
+import { resolveHandlerMailLocale } from "../magic-link-mail.js";
 import { AUTH_SELF_REGISTRATION_FEATURE } from "../self-registration-toggle.js";
-import {
-  invalidateExistingSignupToken,
-  normalizeEmail,
-  storeSignupHandover,
-  storeSignupToken,
-  takeOverSignupHandoverForResend,
-} from "../signup-token-store.js";
-
-const SIGNUP_NOTIFICATION_TYPE = "auth-email-password:signup-activation";
+import { issueSignupActivation } from "../signup-activation.js";
+import { storeSignupHandover, takeOverSignupHandoverForResend } from "../signup-token-store.js";
 
 const SignupRequestSchema = z.object({
   email: z.email(),
@@ -85,9 +74,6 @@ export type SignupRequestOptions = {
 };
 
 export function createSignupRequestHandler(opts: SignupRequestOptions) {
-  const ttlMinutes = opts.tokenTtlMinutes ?? AUTH_SIGNUP_DEFAULT_TTL_MINUTES;
-  const ttlSeconds = ttlMinutes * 60;
-
   return defineWriteHandler<"signup-request", typeof SignupRequestSchema, SignupRequestData>({
     name: "signup-request",
     schema: SignupRequestSchema,
@@ -138,94 +124,65 @@ export function createSignupRequestHandler(opts: SignupRequestOptions) {
       // verified grant over to the new token instead of silently dropping it.
       const priorBinding = await takeOverSignupHandoverForResend(ctx.redis, email);
 
-      // At most one live signup token per email: invalidate whatever's
-      // there before minting the new one (see signup-token-store.ts).
-      await invalidateExistingSignupToken(ctx.redis, email);
-      // 32 random bytes = 256 bits unguessable randomness, base64url
-      // encoded to 43 chars. Math.random used to be a bug here:
-      // xorshift128+ has ~128 bits of state that's reconstructible after
-      // ~5 observed outputs — an attacker could trigger their own
-      // signup-requests and predict other users' tokens. generateToken
-      // uses randomBytes from node:crypto, the same source as CSRF/
-      // session tokens.
-      const token = generateToken();
-
-      const issuedAt = Temporal.Now.instant();
-      const expiresAt = issuedAt.add({ seconds: ttlSeconds });
-      const expiresAtIso = expiresAt.toString();
-
-      await storeSignupToken(ctx.redis, { email, token, ttlSeconds });
-
-      // A handover grant in this request re-verifies and replaces the prior
-      // binding; anything short of a fresh, verified grant (no provider
-      // mounted, or verification failed) falls back to it instead —
-      // dropping a still-live binding on a bad request would strand the
-      // visitor's run. A throw here must never skip the mail below, or the
-      // signup itself silently breaks for a bug in a provider this handler
-      // doesn't own.
-      let binding: SignupHandoverBinding | null = priorBinding;
-      if (event.payload.handover) {
-        const { entityType, token: grantToken } = event.payload.handover;
-        const provider = findSignupHandoverProvider(ctx.registry);
-        if (!provider) {
-          ctx.log?.warn(
-            "signup-request: handover payload present but no signupHandover provider mounted",
-          );
-        } else {
-          try {
-            const verified = await provider.verifyGrant({
-              db: ctx.db.unsafeRaw(),
-              registry: ctx.registry,
-              entityType,
-              token: grantToken,
-            });
-            if (verified) {
-              binding = verified;
+      const locale = resolveHandlerMailLocale(ctx, opts.locale);
+      const redis = ctx.redis;
+
+      const issued = await issueSignupActivation({
+        redis,
+        notify: ctx.notify,
+        email,
+        appUrl: opts.appUrl,
+        timeZone: ctx.tz.user,
+        ...(opts.tokenTtlMinutes !== undefined && { tokenTtlMinutes: opts.tokenTtlMinutes }),
+        ...(opts.appName !== undefined && { appName: opts.appName }),
+        ...(locale !== undefined && { locale }),
+        // A handover grant in this request re-verifies and replaces the prior
+        // binding; anything short of a fresh, verified grant (no provider
+        // mounted, or verification failed) falls back to it instead —
+        // dropping a still-live binding on a bad request would strand the
+        // visitor's run. A throw here must never skip the mail, or the
+        // signup itself silently breaks for a bug in a provider this handler
+        // doesn't own.
+        onTokenStored: async ({ token, ttlSeconds }) => {
+          let binding: SignupHandoverBinding | null = priorBinding;
+          if (event.payload.handover) {
+            const { entityType, token: grantToken } = event.payload.handover;
+            const provider = findSignupHandoverProvider(ctx.registry);
+            if (!provider) {
+              ctx.log?.warn(
+                "signup-request: handover payload present but no signupHandover provider mounted",
+              );
             } else {
-              ctx.log?.warn("signup-request: handover grant did not verify", { entityType });
+              try {
+                const verified = await provider.verifyGrant({
+                  db: ctx.db.unsafeRaw(),
+                  registry: ctx.registry,
+                  entityType,
+                  token: grantToken,
+                });
+                if (verified) {
+                  binding = verified;
+                } else {
+                  ctx.log?.warn("signup-request: handover grant did not verify", { entityType });
+                }
+              } catch {
+                ctx.log?.warn("signup-request: handover grant verification threw", { entityType });
+              }
             }
-          } catch {
-            ctx.log?.warn("signup-request: handover grant verification threw", { entityType });
           }
-        }
-      }
-      if (binding) {
-        await storeSignupHandover(ctx.redis, { token, binding, ttlSeconds });
-      }
-
-      // normalizeEmail from the store — one source of truth for
-      // normalization; the delivery recipient + lookup path consistently
-      // get the same format.
-      const normalizedEmail = normalizeEmail(email);
-
-      const locale = resolveHandlerMailLocale(ctx, opts.locale);
-
-      await dispatchMagicLinkMail(
-        ctx.notify,
-        {
-          handlerName: "signup-request",
-          notificationType: SIGNUP_NOTIFICATION_TYPE,
-          renderContent: renderActivationEmail,
-        },
-        {
-          email: normalizedEmail,
-          appUrl: opts.appUrl,
-          token,
-          expiresAt: expiresAtIso,
-          issuedAt: issuedAt.toString(),
-          timeZone: ctx.tz.user,
-          ...(opts.appName !== undefined && { appName: opts.appName }),
-          locale,
+          if (binding) {
+            await storeSignupHandover(redis, { token, binding, ttlSeconds });
+          }
         },
-      );
+      });
 
       return {
         isSuccess: true,
         data: {
           kind: "signup-requested",
-          email: normalizedEmail,
-          token,
-          expiresAt: expiresAtIso,
+          email: issued.email,
+          token: issued.token,
+          expiresAt: issued.expiresAt,
         },
       };
     },

package/packages/bundled-features/src/auth-email-password/handlers/token-request-handler.ts

@@ -109,6 +109,7 @@ export function createTokenRequestHandler<TName extends string, TSuccessKind ext
     rateLimit: { per: "ip+handler", limit: 10, windowSeconds: 60 },
     additionalRateLimits: [{ per: { payloadField: "email" }, limit: 5, windowSeconds: 86400 }],
     escapeHatch: {
+      grants: ["systemIdentity"],
       reason:
         "Anonymous requester has no session — looks up the target user by email via " +
         "ctx.queryAs(SYSTEM, user:findForAuth) to mint the out-of-band token.",

package/packages/bundled-features/src/auth-email-password/handlers/verify-email.write.ts

@@ -29,6 +29,7 @@ export function createVerifyEmailHandler(opts: VerifyEmailOptions) {
     access: { roles: ["anonymous"] },
     rateLimit: { per: "ip+handler", limit: 20, windowSeconds: 60 },
     escapeHatch: {
+      grants: ["systemIdentity"],
       reason:
         "Anonymous token holder has no session — runConfirmTokenFlow loads and updates the " +
         "target user via ctx.writeAs(SYSTEM, user:update) to set emailVerified.",

package/packages/bundled-features/src/auth-email-password/index.ts

@@ -58,3 +58,15 @@ export {
 // statt eigene HMAC-Logik zu duplizieren. Purpose-string diskriminiert
 // Cross-Replay zwischen Flows.
 export { signToken, TokenPurpose, type VerifyResult, verifyToken } from "./signed-token.js";
+export {
+  type IssuedSignupActivation,
+  type IssueSignupActivationArgs,
+  issueSignupActivation,
+  SIGNUP_ACTIVATION_NOTIFICATION_TYPE,
+} from "./signup-activation.js";
+export {
+  invalidateExistingSignupToken,
+  normalizeEmail,
+  SIGNUP_TOKEN_KEY_PREFIXES,
+  storeSignupToken,
+} from "./signup-token-store.js";

package/packages/bundled-features/src/auth-email-password/seeding.ts

@@ -22,6 +22,7 @@ import {
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import type { SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { ConflictError } from "@cosmicdrift/kumiko-framework/errors";
+import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
 import { TestUsers } from "@cosmicdrift/kumiko-framework/stack";
 import { hashPassword } from "../shared/index.js";
 // kumiko-lint-ignore cross-feature-import auth-tests need user+tenant seed-helpers
@@ -29,7 +30,13 @@ import { type SeedTenantHooks, seedTenant, seedTenantMembership } from "../tenan
 // kumiko-lint-ignore cross-feature-import signup create-only guard reads the user projection by email
 import { USER_STATUS, userTable } from "../user/schema/user.js";
 // kumiko-lint-ignore cross-feature-import auth-tests need user+tenant seed-helpers
-import { reconcileSeededUserEmailVerified, seedUser } from "../user/seeding.js";
+import {
+  reconcileSeededUserEmailVerified,
+  rewriteSeededUserEmail,
+  seedUser,
+} from "../user/seeding.js";
+
+const log = createFallbackLogger("auth-email-password-seeding");
 
 // Re-export für ergonomische Single-Import-Site in tests/seed-scripts.
 // Das Auth-Feature ist der natürliche Aufrufer für "seed admin user mit
@@ -126,6 +133,8 @@ export type ProvisionSignupAccountOptions = {
   readonly tenantName: string;
   readonly tenantId: TenantId;
   readonly memberRoles?: readonly string[];
+  /** Stored on the new user row so the first session already carries the locale claim. */
+  readonly locale?: string;
 };
 
 export async function provisionSignupAccount(
@@ -166,6 +175,7 @@ export async function provisionSignupAccount(
       password: options.password,
       displayName: options.displayName,
       emailVerified: true,
+      ...(options.locale !== undefined && { locale: options.locale }),
     },
     hooks,
   );
@@ -306,15 +316,30 @@ async function findExistingUserIdForEmail(
     status: { ne: USER_STATUS.Deleted },
   });
   const matches: ActiveUserRow[] = [];
+  let undecryptableRows = 0;
   for (const row of rows) {
     // Compared byte-exact, deliberately not case-folded: email_bidx is an
     // HMAC over the raw value and login matches case-sensitively, so a case
     // variant is a different account to every other code path.
-    const decrypted = await decryptPiiFieldValues({ email: row.email }, ["email"], kms, {
-      requestId: "seed-admin-guarded",
-    });
+    // One undecryptable foreign row (missing key row, ciphertext from another
+    // KMS store) must not abort the boot seed: the account we look for is
+    // decryptable by definition.
+    let decrypted: Record<string, unknown>;
+    try {
+      decrypted = await decryptPiiFieldValues({ email: row.email }, ["email"], kms, {
+        requestId: "seed-admin-guarded",
+      });
+    } catch {
+      undecryptableRows += 1;
+      continue;
+    }
     if (decrypted["email"] === email) matches.push(row);
   }
+  if (undecryptableRows > 0) {
+    log.warn(
+      `seedAdminGuarded: skipped ${undecryptableRows} user row(s) whose email could not be decrypted`,
+    );
+  }
   return matches.length === 0 ? undefined : pickCanonicalUserId(matches);
 }
 
@@ -351,9 +376,15 @@ export async function seedAdminGuarded(
   if (existingId === undefined) return seedAdmin(db, options);
 
   const by = options.by ?? TestUsers.systemAdmin;
-  if (options.emailVerified === true) {
-    const existingRow = await fetchOne(db, userTable, { id: existingId });
-    if (existingRow) await reconcileSeededUserEmailVerified(db, existingRow, by);
+  const existingRow = await fetchOne(db, userTable, { id: existingId });
+  if (existingRow) {
+    // Re-write the email so email_bidx is recomputed; without it the account
+    // stays unfindable for login and every boot re-scans the whole table.
+    await rewriteSeededUserEmail(db, existingRow, options.email, by);
+    if (options.emailVerified === true) {
+      const refreshed = (await fetchOne(db, userTable, { id: existingId })) ?? existingRow;
+      await reconcileSeededUserEmailVerified(db, refreshed, by);
+    }
   }
   for (const m of options.memberships) {
     await seedTenant(db, { id: m.tenantId, key: m.tenantKey, name: m.tenantName, by });

package/packages/bundled-features/src/auth-email-password/signup-activation.ts

@@ -0,0 +1,83 @@
+// Mints a signup activation link: invalidates any live token for the email,
+// stores a fresh one and mails the activation link. Shared by the
+// signup-request handler and by apps that issue the same link from their own
+// flow (e.g. a waitlist invite), so TTL, store keys and notification type
+// cannot drift between the two.
+
+import { generateToken } from "@cosmicdrift/kumiko-framework/api";
+import type { NotifyFn } from "@cosmicdrift/kumiko-framework/engine";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import type { Redis } from "ioredis";
+import { AUTH_SIGNUP_DEFAULT_TTL_MINUTES } from "./constants.js";
+import { renderActivationEmail } from "./email-templates.js";
+import { dispatchMagicLinkMail } from "./magic-link-mail.js";
+import {
+  invalidateExistingSignupToken,
+  normalizeEmail,
+  storeSignupToken,
+} from "./signup-token-store.js";
+
+export const SIGNUP_ACTIVATION_NOTIFICATION_TYPE = "auth-email-password:signup-activation";
+
+export type IssueSignupActivationArgs = {
+  readonly redis: Redis;
+  readonly notify: NotifyFn | undefined;
+  readonly email: string;
+  readonly appUrl: string | ((locale: string) => string);
+  readonly appName?: string;
+  readonly locale?: string;
+  readonly timeZone?: string;
+  readonly tokenTtlMinutes?: number;
+  /** Runs after the token is stored and before the mail goes out. */
+  readonly onTokenStored?: (stored: {
+    readonly token: string;
+    readonly ttlSeconds: number;
+  }) => Promise<void>;
+};
+
+export type IssuedSignupActivation = {
+  readonly email: string;
+  readonly token: string;
+  readonly expiresAt: string;
+};
+
+export async function issueSignupActivation(
+  args: IssueSignupActivationArgs,
+): Promise<IssuedSignupActivation> {
+  const ttlSeconds = (args.tokenTtlMinutes ?? AUTH_SIGNUP_DEFAULT_TTL_MINUTES) * 60;
+
+  // At most one live signup token per email.
+  await invalidateExistingSignupToken(args.redis, args.email);
+  // 256 bits from node:crypto — never Math.random: xorshift128+ state is
+  // reconstructible from a few observed outputs, which would let an attacker
+  // predict other users' tokens.
+  const token = generateToken();
+
+  const issuedAt = Temporal.Now.instant();
+  const expiresAt = issuedAt.add({ seconds: ttlSeconds }).toString();
+
+  await storeSignupToken(args.redis, { email: args.email, token, ttlSeconds });
+  await args.onTokenStored?.({ token, ttlSeconds });
+
+  const email = normalizeEmail(args.email);
+  await dispatchMagicLinkMail(
+    args.notify,
+    {
+      handlerName: "signup-request",
+      notificationType: SIGNUP_ACTIVATION_NOTIFICATION_TYPE,
+      renderContent: renderActivationEmail,
+    },
+    {
+      email,
+      appUrl: args.appUrl,
+      token,
+      expiresAt,
+      issuedAt: issuedAt.toString(),
+      ...(args.timeZone !== undefined && { timeZone: args.timeZone }),
+      ...(args.appName !== undefined && { appName: args.appName }),
+      ...(args.locale !== undefined && { locale: args.locale }),
+    },
+  );
+
+  return { email, token, expiresAt };
+}

package/packages/bundled-features/src/auth-email-password/signup-token-store.ts

@@ -26,10 +26,16 @@ export function normalizeEmail(email: string): string {
   return email.toLowerCase();
 }
 
+export const SIGNUP_TOKEN_KEY_PREFIXES = {
+  token: "signup:by-token:",
+  email: "signup:by-email:",
+  burn: "signup:burn:",
+} as const;
+
 const store = createSingleUseTokenStore({
-  tokenPrefix: "signup:by-token:",
-  subjectPrefix: "signup:by-email:",
-  burnPrefix: "signup:burn:",
+  tokenPrefix: SIGNUP_TOKEN_KEY_PREFIXES.token,
+  subjectPrefix: SIGNUP_TOKEN_KEY_PREFIXES.email,
+  burnPrefix: SIGNUP_TOKEN_KEY_PREFIXES.burn,
 });
 
 /** Stores the pair bidirectionally and sets TTL on both keys.

package/packages/bundled-features/src/auth-email-password/web/auth-gate.tsx

@@ -14,7 +14,7 @@ import { type ComponentType, type ReactNode, useEffect, useState } from "react";
 import {
   assertNavigableUrl,
   buildLoginRedirectUrl,
-  followNextAfterLogin,
+  followNextOrLandingAfterLogin,
 } from "./auth-redirect.js";
 import { LoginScreen, type LoginScreenProps } from "./login-screen.js";
 import { SessionProvider, useSession } from "./session.js";
@@ -26,7 +26,7 @@ import { SessionBootstrapErrorScreen } from "./session-bootstrap-error.js";
 // wire auth-mfa's MfaVerifyScreen in here via EmailPasswordClientOptions.
 export type MfaVerifyComponentProps = {
   readonly challengeToken: string;
-  readonly onSuccess?: () => void;
+  readonly onSuccess?: (landingPath?: string) => void;
   readonly onCancel?: () => void;
 };
 
@@ -36,7 +36,7 @@ export type MfaVerifyComponentProps = {
 export type MfaSetupComponentProps = {
   readonly preauthSetupToken: string;
   readonly accountLabel: string;
-  readonly onSuccess?: () => void;
+  readonly onSuccess?: (landingPath?: string) => void;
   readonly onCancel?: () => void;
 };
 
@@ -113,9 +113,9 @@ export function createLoginRoute(
       return (
         <MfaVerifyComponent
           challengeToken={challengeToken}
-          onSuccess={() => {
+          onSuccess={(landingPath) => {
             setChallengeToken(null);
-            followNextAfterLogin();
+            followNextOrLandingAfterLogin(landingPath);
           }}
           onCancel={() => setChallengeToken(null)}
         />
@@ -128,7 +128,7 @@ export function createLoginRoute(
         <MfaSetupComponent
           preauthSetupToken={setupRequest.preauthSetupToken}
           accountLabel={setupRequest.accountLabel}
-          onSuccess={() => {
+          onSuccess={(landingPath) => {
             // MfaSetupPreauthScreen has no session to refresh itself with
             // (it runs pre-auth) — the gate owns the session, so it refreshes.
             // refresh() never rejects: a failed refresh surfaces as status
@@ -136,7 +136,7 @@ export function createLoginRoute(
             // success path needs to clear setupRequest.
             void refresh().then(() => {
               setSetupRequest(null);
-              followNextAfterLogin();
+              followNextOrLandingAfterLogin(landingPath);
             });
           }}
           onCancel={() => setSetupRequest(null)}

package/packages/bundled-features/src/auth-email-password/web/auth-redirect.ts

@@ -72,3 +72,18 @@ export function followNextAfterLogin(
   location.replace(next);
   return true;
 }
+
+// An explicit `next` (the page the user was sent away from) beats the server's
+// landingPath (auth.postAuthLanding); without either the caller keeps its own
+// client-side routing. landingPath is re-validated like `next`, so a
+// misconfigured resolver cannot turn the login into an open redirect.
+export function followNextOrLandingAfterLogin(
+  landingPath: string | undefined,
+  location: Pick<Location, "search" | "pathname" | "replace"> = window.location,
+): boolean {
+  if (followNextAfterLogin(location)) return true;
+  if (landingPath === undefined || !isSafeNextPath(landingPath)) return false;
+  if (new URL(landingPath, "https://next.invalid").pathname === location.pathname) return false;
+  location.replace(landingPath);
+  return true;
+}

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

@@ -17,7 +17,7 @@ import {
   requestEmailVerification,
 } from "./auth-client.js";
 import { AuthCard } from "./auth-form-primitives.js";
-import { followNextAfterLogin } from "./auth-redirect.js";
+import { followNextOrLandingAfterLogin } from "./auth-redirect.js";
 import { useSession } from "./session.js";
 
 // Resend-Status für den "Bestätigungs-Mail erneut senden"-Flow, der bei
@@ -144,7 +144,7 @@ export function LoginScreen({
     const res = await session.login({ email, password });
     setSubmitting(false);
     if (res.kind === "success") {
-      followNextAfterLogin();
+      followNextOrLandingAfterLogin(res.data.landingPath);
       return;
     }
     if (res.kind === "mfa-challenge") {

package/packages/bundled-features/src/auth-email-password/web/user-menu.tsx

@@ -78,7 +78,7 @@ export function UserMenu({ children, variant = "pill" }: UserMenuProps): ReactNo
           <DropdownMenuSeparator />
         </>
       )}
-      <DropdownMenuItem onSelect={() => void logout()}>
+      <DropdownMenuItem data-testid="user-menu-logout" onSelect={() => void logout()}>
         <LogOut className="h-4 w-4" />
         <span>{t("auth.user.menu.logout")}</span>
       </DropdownMenuItem>

package/packages/bundled-features/src/auth-mfa/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.354.0",
+    "type": "breaking",
+    "title": "auth-mfa declares the master-key env slots, so composeEnvSchema requires KUMIKO_SECRETS_MASTER_KEY_V1 when auth-mfa is mounted",
+    "detail": "Review batch H1: framework parts of consumer-app findings.\n- `auth-email-password` exports `issueSignupActivation` (invalidate, mint, store and mail an activation link; the signup-request handler now runs on it), `SIGNUP_ACTIVATION_NOTIFICATION_TYPE`, `storeSignupToken`, `invalidateExistingSignupToken`, `normalizeEmail` and `SIGNUP_TOKEN_KEY_PREFIXES`.\n- `auth-mfa` declares the master-key env slots (`KUMIKO_SECRETS_MASTER_KEY_V1`, `_CURRENT_VERSION`, the `_CIPHERTEXT` twin) as a shared fragment with `secrets`, so a rotated `V<n>` slot is unpacked even without `secrets` mounted.\n- `user-data-rights` exports `TENANT_MODEL_CONFIG_KEY`; `createTemplateResolverApi` takes a `DbRunner`.\n- The user menu's logout item carries `data-testid=\"user-menu-logout\"`.\n- renderer-web: a `Field` description is linked to its text input via `aria-describedby`; the facet filter dropdown is capped to the available viewport height and scrolls; `createBrowserLocaleResolver` takes `normalizeLocale` and the default storage key is exported as `BROWSER_LOCALE_STORAGE_KEY`.\n- testing: `loginViaApi(request, credentials, { bucketKey })`, `CLIENT_IP_HEADER` from `@cosmicdrift/kumiko-testing/e2e`, and a Playwright-free `@cosmicdrift/kumiko-testing/e2e/constants` subpath (`KUMIKO_SECRETS_MASTER_KEY_V1`).",
+    "migration": "Apps that bring their own masterKey provider instead of the env KEK add \"auth-mfa\" to composeEnvSchema's optionalFeatures, like they already do for \"secrets\". Required wins as soon as auth-mfa is not in optionalFeatures, even when `secrets` is listed there."
+  },
   {
     "version": "0.341.0",
     "type": "breaking",

package/packages/bundled-features/src/auth-mfa/feature.ts

@@ -1,5 +1,6 @@
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { secretsEnvSchema } from "../secrets/index.js";
 import { type MfaRequiredPolicy, mfaRequiredConfigKey } from "./config.js";
 import { createDisableHandler } from "./handlers/disable.write.js";
 import { createEnableConfirmHandler } from "./handlers/enable-confirm.write.js";
@@ -125,6 +126,10 @@ export function createAuthMfaFeature(opts: AuthMfaFeatureOptions): FeatureDefini
       category: "identity",
       recommended: true,
     });
+    // Same field instances as `secrets`, so composeEnvSchema treats them as one
+    // shared variable; an app mounting auth-mfa without `secrets` still gets the
+    // KEK slot (and its _CIPHERTEXT twin) declared.
+    r.envSchema(secretsEnvSchema);
     r.requires("user");
     r.requires("config");
     // verify.write.ts dispatches "tenant:query:memberships" — without this

package/packages/bundled-features/src/auth-mfa/handlers/enable-confirm-preauth.write.ts

@@ -71,6 +71,7 @@ export function createEnableConfirmPreauthHandler(opts: EnableConfirmPreauthOpti
     access: { roles: ["anonymous"], personalData: "public-intake" },
     rateLimit: { per: "ip+handler", limit: 20, windowSeconds: 60 },
     escapeHatch: {
+      grants: ["systemIdentity", "unsafeRaw"],
       reason:
         "Pre-auth MFA enrollment step has no session yet — re-checks status via ctx.queryAs(SYSTEM, " +
         "user:findForAuth) and membership via ctx.resolveActiveMembership for the setup token's user. " +

package/packages/bundled-features/src/auth-mfa/handlers/verify.write.ts

@@ -48,6 +48,7 @@ export function createMfaVerifyHandler(opts: MfaVerifyOptions) {
     access: { roles: ["anonymous"], personalData: "public-intake" },
     rateLimit: { per: "ip+handler", limit: 20, windowSeconds: 60 },
     escapeHatch: {
+      grants: ["systemIdentity", "unsafeRaw"],
       reason:
         "Pre-auth MFA step has no session yet — re-derives it via ctx.queryAs(SYSTEM, " +
         "user:findForAuth) and ctx.resolveActiveMembership for the user the challenge token names. " +

package/packages/bundled-features/src/auth-mfa/web/mfa-recovery-codes-reveal.tsx

@@ -22,14 +22,7 @@ export function MfaRecoveryCodesReveal({
   const [acknowledged, setAcknowledged] = useState(false);
 
   return (
-    <Section
-      testId="mfa-regenerate-reveal"
-      actions={
-        <Button variant="primary" onClick={onDismiss} disabled={!acknowledged}>
-          {t("auth.mfa.regenerate.done")}
-        </Button>
-      }
-    >
+    <Section testId="mfa-regenerate-reveal">
       <div className="flex flex-col items-center gap-2 text-center">
         <span className="text-sm font-semibold">{t("auth.mfa.regenerate.newCodesTitle")}</span>
         <span className="text-xs text-muted-foreground">
@@ -48,6 +41,11 @@ export function MfaRecoveryCodesReveal({
           onChange={setAcknowledged}
         />
       </Field>
+      <div className="flex justify-end">
+        <Button variant="primary" onClick={onDismiss} disabled={!acknowledged}>
+          {t("auth.mfa.regenerate.done")}
+        </Button>
+      </div>
     </Section>
   );
 }