@cosmicdrift/kumiko-bundled-features 0.220.1 → 0.221.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.220.1",
+  "version": "0.221.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>",
@@ -126,12 +126,12 @@
     "./step-dispatcher": "./src/step-dispatcher/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.220.1",
-    "@cosmicdrift/kumiko-framework": "0.220.1",
-    "@cosmicdrift/kumiko-headless": "0.220.1",
-    "@cosmicdrift/kumiko-renderer": "0.220.1",
-    "@cosmicdrift/kumiko-renderer-web": "0.220.1",
-    "@cosmicdrift/kumiko-types": "0.220.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.221.0",
+    "@cosmicdrift/kumiko-framework": "0.221.0",
+    "@cosmicdrift/kumiko-headless": "0.221.0",
+    "@cosmicdrift/kumiko-renderer": "0.221.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.221.0",
+    "@cosmicdrift/kumiko-types": "0.221.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -160,7 +160,7 @@
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
     "@types/qrcode": "^1.5.5",
-    "@cosmicdrift/kumiko-locale-de": "0.220.1",
-    "@cosmicdrift/kumiko-locale-es": "0.220.1"
+    "@cosmicdrift/kumiko-locale-de": "0.221.0",
+    "@cosmicdrift/kumiko-locale-es": "0.221.0"
   }
 }

package/src/__tests__/access-invalidation-consumer.integration.test.ts

@@ -294,7 +294,7 @@ describe("access-invalidation event consumer", () => {
       {
         id: userId,
         version: detail["version"],
-        changes: { roles: JSON.stringify(["SystemAdmin"]) },
+        changes: { roles: ["SystemAdmin"] },
       },
       admin,
     );
@@ -307,6 +307,7 @@ describe("access-invalidation event consumer", () => {
     const sessionRow = await fetchOne<{ revokedAt: unknown }>(stack.db, userSessionTable, {
       id: sid,
     });
+    expect(sessionRow).toBeTruthy();
     expect(sessionRow?.revokedAt).not.toBeNull();
   });
 });

package/src/audit/__tests__/audit-log-screen.test.tsx

@@ -21,7 +21,8 @@ import { defaultPrimitives, defaultTokens } from "@cosmicdrift/kumiko-renderer-w
 import { render, waitFor } from "@testing-library/react";
 import type { ReactNode } from "react";
 import { TenantQueries } from "../../tenant/constants";
-import { AuditQueries } from "../constants";
+import { AUDIT_LOG_DETAIL_SCREEN_ID, AuditQueries } from "../constants";
+import { AuditLogDetailScreen } from "../web/audit-log-detail-screen";
 import { AuditLogScreen } from "../web/audit-log-screen";
 import { defaultTranslations } from "../web/i18n";
 
@@ -124,14 +125,32 @@ const MEMBERS: readonly MemberRowFixture[] = [
   { userId: "user-2", email: "bob@example.com", displayName: null },
 ];
 
-function makeDispatcher(): Dispatcher {
+type AuditDetailFixture = AuditRowFixture & { readonly metadata: Record<string, unknown> };
+
+function detailFixtureFor(row: AuditRowFixture): AuditDetailFixture {
+  return { ...row, metadata: {} };
+}
+
+type MembersResult =
+  | { readonly isSuccess: true; readonly data: readonly MemberRowFixture[] }
+  | { readonly isSuccess: false; readonly error: { readonly message: string } };
+
+function makeDispatcher(
+  options: {
+    readonly detail?: AuditDetailFixture | null;
+    readonly membersResult?: MembersResult;
+  } = {},
+): Dispatcher {
   const statusStore = createStore<DispatcherStatus>("online");
   const query = (async (type: string) => {
     if (type === AuditQueries.list) {
       return { isSuccess: true, data: { rows: AUDIT_ROWS, nextBefore: null } };
     }
+    if (type === AuditQueries.details) {
+      return { isSuccess: true, data: options.detail ?? null };
+    }
     if (type === TenantQueries.members) {
-      return { isSuccess: true, data: MEMBERS };
+      return options.membersResult ?? { isSuccess: true, data: MEMBERS };
     }
     return { isSuccess: true, data: null };
   }) as unknown as Dispatcher["query"];
@@ -146,7 +165,12 @@ function makeDispatcher(): Dispatcher {
   } as unknown as Dispatcher; // @cast-boundary test-stub
 }
 
-function renderScreen(): ReturnType<typeof render> {
+function renderWithProviders(
+  ui: ReactNode,
+  options: { readonly nav?: NavApi; readonly dispatcher?: Dispatcher } = {},
+): ReturnType<typeof render> {
+  const nav = options.nav ?? stubNav;
+  const dispatcher = options.dispatcher ?? makeDispatcher();
   const wrapper = ({ children }: { readonly children: ReactNode }): ReactNode => (
     <TokensProvider value={stubTokens}>
       <LocaleProvider
@@ -154,16 +178,25 @@ function renderScreen(): ReturnType<typeof render> {
         fallbackBundles={[defaultTranslations, kumikoDefaultTranslations]}
       >
         <PrimitivesProvider value={defaultPrimitives}>
-          <NavProvider value={stubNav}>
+          <NavProvider value={nav}>
             <LiveEventsProvider value={stubLiveEvents}>
-              <DispatcherProvider dispatcher={makeDispatcher()}>{children}</DispatcherProvider>
+              <DispatcherProvider dispatcher={dispatcher}>{children}</DispatcherProvider>
             </LiveEventsProvider>
           </NavProvider>
         </PrimitivesProvider>
       </LocaleProvider>
     </TokensProvider>
   );
-  return render(<AuditLogScreen />, { wrapper });
+  return render(ui, { wrapper });
+}
+
+function renderScreen(dispatcher?: Dispatcher): ReturnType<typeof render> {
+  return renderWithProviders(<AuditLogScreen />, { dispatcher });
+}
+
+function renderDetailScreen(entityId: string, dispatcher: Dispatcher): ReturnType<typeof render> {
+  const nav: NavApi = { ...stubNav, route: { screenId: AUDIT_LOG_DETAIL_SCREEN_ID, entityId } };
+  return renderWithProviders(<AuditLogDetailScreen />, { nav, dispatcher });
 }
 
 describe("AuditLogScreen — actor name resolution", () => {
@@ -226,3 +259,44 @@ describe("AuditLogScreen — actor name resolution", () => {
     expect(view.container.textContent).not.toContain("3f2504e0-4f89-11d3-9a0c-0305e82c3301");
   });
 });
+
+describe("AuditLogScreen — members query failure", () => {
+  test("members query returns isSuccess:false → list still renders, no crash", async () => {
+    const dispatcher = makeDispatcher({
+      membersResult: { isSuccess: false, error: { message: "members unavailable" } },
+    });
+    const view = renderScreen(dispatcher);
+    await waitFor(() => {
+      const cell = view.queryByTestId("cell-1-type");
+      if (cell === null) throw new Error("table not rendered yet");
+    });
+    expect(view.getByTestId("cell-1-type").textContent).toBe("widget.created");
+    expect(view.getByTestId("cell-1-actor").textContent).toBe("");
+  });
+});
+
+describe("AuditLogDetailScreen — actor name resolution", () => {
+  test("known member with displayName → detail actor field shows the display name", async () => {
+    const row = AUDIT_ROWS[0];
+    if (row === undefined) throw new Error("fixture missing");
+    const dispatcher = makeDispatcher({ detail: detailFixtureFor(row) });
+    const view = renderDetailScreen(row.id, dispatcher);
+    await waitFor(() => {
+      const cell = view.queryByTestId("audit-detail-actor");
+      if (cell === null) throw new Error("actor field not rendered yet");
+    });
+    expect(view.getByTestId("audit-detail-actor").textContent).toBe("Alice Example");
+  });
+
+  test("known member without displayName → detail actor field falls back to email", async () => {
+    const row = AUDIT_ROWS[1];
+    if (row === undefined) throw new Error("fixture missing");
+    const dispatcher = makeDispatcher({ detail: detailFixtureFor(row) });
+    const view = renderDetailScreen(row.id, dispatcher);
+    await waitFor(() => {
+      const cell = view.queryByTestId("audit-detail-actor");
+      if (cell === null) throw new Error("actor field not rendered yet");
+    });
+    expect(view.getByTestId("audit-detail-actor").textContent).toBe("bob@example.com");
+  });
+});

package/src/audit/__tests__/constants.test.ts

@@ -0,0 +1,8 @@
+import { describe, expect, test } from "bun:test";
+import { SYSTEM_ACTOR_ID } from "../constants";
+
+describe("audit constants", () => {
+  test("SYSTEM_ACTOR_ID matches the event-store system user id", () => {
+    expect(SYSTEM_ACTOR_ID).toBe("system");
+  });
+});

package/src/audit/web/audit-log-detail-screen.tsx

@@ -34,7 +34,15 @@ type State =
   | { readonly kind: "loading" }
   | { readonly kind: "missing" }
   | { readonly kind: "error"; readonly message: string }
-  | { readonly kind: "ready"; readonly event: AuditDetail; readonly actorName: string };
+  | {
+      readonly kind: "ready";
+      readonly event: AuditDetail;
+      /** Resolved member display string, or "" if unknown. System actor is
+       *  flagged separately so the translated label is formed in render
+       *  (avoids refetch on locale change — fw#2297). */
+      readonly memberLabel: string;
+      readonly isSystemActor: boolean;
+    };
 
 export function AuditLogDetailScreen(): ReactNode {
   const t = useTranslation();
@@ -60,21 +68,24 @@ export function AuditLogDetailScreen(): ReactNode {
       return;
     }
     const event = res.data;
-    const membersRes = await dispatcher.query<readonly MemberRow[]>(TenantQueries.members, {});
+    if (event.createdBy === SYSTEM_ACTOR_ID) {
+      setState({ kind: "ready", event, memberLabel: "", isSystemActor: true });
+      return;
+    }
+    // Single-user filter — do not decrypt the whole tenant roster for one name.
+    const membersRes = await dispatcher.query<readonly MemberRow[]>(TenantQueries.members, {
+      userId: event.createdBy,
+    });
     const member = membersRes.isSuccess
       ? membersRes.data.find((m) => m.userId === event.createdBy)
       : undefined;
     setState({
       kind: "ready",
       event,
-      actorName:
-        event.createdBy === SYSTEM_ACTOR_ID
-          ? t("audit.log.actor.system")
-          : member
-            ? (member.displayName ?? member.email ?? "")
-            : "",
+      memberLabel: member ? (member.displayName ?? member.email ?? "") : "",
+      isSystemActor: false,
     });
-  }, [dispatcher, eventId, t]);
+  }, [dispatcher, eventId]);
 
   // kumiko-lint-ignore no-raw-hooks Phase-3 conversion tracked in #2312
   useEffect(() => {
@@ -83,7 +94,7 @@ export function AuditLogDetailScreen(): ReactNode {
 
   if (state.kind === "loading") {
     return (
-      <FormScreenShell testId="audit-log-detail-screen">
+      <FormScreenShell testId="audit-log-detail-screen" maxWidth="3xl">
         <Text variant="small">{t("audit.log.detail.loading")}</Text>
       </FormScreenShell>
     );
@@ -91,7 +102,7 @@ export function AuditLogDetailScreen(): ReactNode {
 
   if (state.kind === "missing") {
     return (
-      <FormScreenShell testId="audit-log-detail-screen">
+      <FormScreenShell testId="audit-log-detail-screen" maxWidth="3xl">
         <Banner variant="error">{t("audit.log.detail.missing")}</Banner>
       </FormScreenShell>
     );
@@ -99,16 +110,21 @@ export function AuditLogDetailScreen(): ReactNode {
 
   if (state.kind === "error") {
     return (
-      <FormScreenShell testId="audit-log-detail-screen">
+      <FormScreenShell testId="audit-log-detail-screen" maxWidth="3xl">
         <Banner variant="error">{state.message}</Banner>
       </FormScreenShell>
     );
   }
 
-  const { event, actorName } = state;
+  const { event, memberLabel, isSystemActor } = state;
+  const actorName = isSystemActor ? t("audit.log.actor.system") : memberLabel;
 
   return (
-    <FormScreenShell testId="audit-log-detail-screen" className="flex flex-col gap-6">
+    <FormScreenShell
+      testId="audit-log-detail-screen"
+      maxWidth="3xl"
+      className="flex flex-col gap-6"
+    >
       <Card slots={{ title: event.type }}>
         <dl className="grid gap-3 text-sm">
           <div>

package/src/audit/web/audit-log-screen.tsx

@@ -70,17 +70,31 @@ export function AuditLogScreen(): ReactNode {
   // mid-session and refetching on every "older" click is wasted work.
   const membersRef = useRef<Promise<ReadonlyMap<string, string>> | null>(null);
 
+  // Tenant/dispatcher identity can change without remounting — drop the cache.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: reset is keyed on dispatcher identity, not a read inside the effect
+  useEffect(() => {
+    membersRef.current = null;
+  }, [dispatcher]);
+
   const load = useCallback(
     async (cursor?: string, overrideFilters?: Filters): Promise<void> => {
       setState({ kind: "loading" });
       const f = overrideFilters ?? filtersRef.current;
-      membersRef.current ??= dispatcher
-        .query<readonly MemberRow[]>(TenantQueries.members, {})
-        .then((res) =>
-          res.isSuccess
-            ? new Map(res.data.map((m) => [m.userId, m.displayName ?? m.email ?? ""] as const))
-            : new Map<string, string>(),
-        );
+      if (!membersRef.current) {
+        const p = dispatcher.query<readonly MemberRow[]>(TenantQueries.members, {}).then((res) => {
+          if (!res.isSuccess) {
+            // Soft failure: clear so a later filter/page retry can refetch
+            // instead of freezing an empty actor column for the session.
+            if (membersRef.current === p) membersRef.current = null;
+            return new Map<string, string>();
+          }
+          return new Map(res.data.map((m) => [m.userId, m.displayName ?? m.email ?? ""] as const));
+        });
+        membersRef.current = p;
+        void p.catch(() => {
+          if (membersRef.current === p) membersRef.current = null;
+        });
+      }
       const [res, names] = await Promise.all([
         dispatcher.query<AuditResponse>(AuditQueries.list, {
           limit: 50,

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

@@ -78,6 +78,7 @@ async function seedLoginUser(opts: {
   password: string;
   tenantId?: TenantId;
   roles?: string[];
+  locale?: string;
 }): Promise<{ id: string; tenantId: TenantId }> {
   const hash = await hashPassword(opts.password);
   const created = await stack.http.writeOk<{ id: string }>(
@@ -86,6 +87,7 @@ async function seedLoginUser(opts: {
       email: opts.email,
       passwordHash: hash,
       displayName: opts.email.split("@")[0] ?? "user",
+      locale: opts.locale,
     },
     systemAdmin,
   );
@@ -134,6 +136,33 @@ describe("scenario 1: login success", () => {
       },
     );
     expect(meRes.status).toBe(200);
+
+    // fw#2333 — a user without a stored locale must not carry a locale
+    // claim at all (not null, not "").
+    const payload = await stack.jwt.verify(body.token as string);
+    expect(payload.locale).toBeUndefined();
+  });
+
+  test("correct credentials with a stored locale → JWT carries the locale claim", async () => {
+    const seed = await seedLoginUser({
+      email: "good-locale@example.com",
+      password: "correct-horse-battery",
+      roles: ["User"],
+      locale: "de-DE",
+    });
+
+    const res = await stack.http.raw("POST", "/api/auth/login", {
+      email: "good-locale@example.com",
+      password: "correct-horse-battery",
+    });
+
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.token).toBeTypeOf("string");
+
+    const payload = await stack.jwt.verify(body.token as string);
+    expect(payload.locale).toBe("de-DE");
+    expect(payload.sub).toBe(seed.id);
   });
 });
 

package/src/auth-email-password/__tests__/invite-accept-with-login-gates.integration.test.ts

@@ -166,6 +166,16 @@ function aliceSession(): SessionUser {
   return { id: aliceId, tenantId: TENANT_A_ID, roles: ["Admin"] };
 }
 
+// auth-mfa:write:verify runs pre-session (access: { roles: ["all"] }) —
+// dispatched here the same way the framework's /api/auth/mfa/verify route
+// would, with a guest identity. The handler derives everything it needs
+// from the challenge token, not from this actor.
+const GUEST: SessionUser = {
+  id: "00000000-0000-0000-0000-000000000000",
+  tenantId: "00000000-0000-4000-8000-000000000000" as TenantId,
+  roles: ["all"],
+};
+
 async function inviteEmail(email: string, role: string): Promise<string> {
   await stack.http.writeOk(AuthHandlers.inviteCreate, { email, role }, aliceSession());
   const sent = emailTransport.sent.at(-1);
@@ -230,6 +240,79 @@ describe("invite-accept-with-login: MFA gate", () => {
     // No session — a challenge, not a JWT.
     expect(body.token).toBeUndefined();
   });
+
+  // fw#2333 — completing the challenge via auth-mfa:write:verify must carry
+  // the invitee's locale into the minted session, same as a plain login.
+  async function acceptWithLoginThenVerifyMfa(opts: {
+    actorId: number;
+    email: string;
+    password: string;
+    locale?: string;
+  }): Promise<SessionUser> {
+    const mfaActor = createTestUser({ id: opts.actorId, tenantId: TENANT_A_ID, roles: ["User"] });
+    const start = await stack.http.writeOk<{ setupToken: string; otpauthUri: string }>(
+      AuthMfaHandlers.enableStart,
+      { accountLabel: opts.email },
+      mfaActor,
+    );
+    const secretParam = new URLSearchParams(start.otpauthUri.split("?")[1]).get("secret") ?? "";
+    const secret = base32Decode(secretParam);
+    await stack.http.writeOk(
+      AuthMfaHandlers.enableConfirm,
+      { setupToken: start.setupToken, code: currentTotpCode(secret) },
+      mfaActor,
+    );
+
+    await seedRow(stack.db, userTable, {
+      id: mfaActor.id,
+      tenantId: TENANT_A_ID,
+      email: opts.email,
+      passwordHash: await hashPassword(opts.password),
+      displayName: "MFA Invitee",
+      ...(opts.locale !== undefined && { locale: opts.locale }),
+      emailVerified: true,
+      roles: "[]",
+      status: USER_STATUS.Active,
+    });
+
+    const token = await inviteEmail(opts.email, "Editor");
+    const acceptRes = await stack.http.raw("POST", "/api/auth/invite-accept-with-login", {
+      token,
+      email: opts.email,
+      password: opts.password,
+    });
+    expect(acceptRes.status).toBe(200);
+    const acceptBody = (await acceptRes.json()) as { challengeToken?: string };
+    if (!acceptBody.challengeToken) {
+      throw new Error("invite-accept-with-login did not return a challenge token");
+    }
+
+    const verified = await stack.http.writeOk<{ session: SessionUser }>(
+      AuthMfaHandlers.verify,
+      { challengeToken: acceptBody.challengeToken, code: currentTotpCode(secret) },
+      GUEST,
+    );
+    return verified.session;
+  }
+
+  test("completing the mfa/verify challenge carries the invitee's locale into the session", async () => {
+    const session = await acceptWithLoginThenVerifyMfa({
+      actorId: 702,
+      email: "mfa-locale-invitee@example.com",
+      password: "mfa-locale-invitee-pw-1234",
+      locale: "de-DE",
+    });
+    expect(session.locale).toBe("de-DE");
+  });
+
+  test("completing the mfa/verify challenge without a stored locale omits the claim", async () => {
+    const session = await acceptWithLoginThenVerifyMfa({
+      actorId: 703,
+      email: "mfa-nolocale-invitee@example.com",
+      password: "mfa-nolocale-invitee-pw-1234",
+    });
+    expect(session.locale).toBeUndefined();
+  });
 });
 
 describe("invite-accept-with-login: account-status gate", () => {

package/src/auth-email-password/__tests__/invite-flow.integration.test.ts

@@ -369,6 +369,42 @@ describe("invite-accept-with-login (Branch 2: anon + existing email)", () => {
     // Membership added
     const memberships = await selectMany(stack.db, tenantMembershipsTable, { userId: bobId });
     expect(memberships).toHaveLength(2);
+
+    // fw#2333 — Bob has no stored locale, so the JWT must carry no locale
+    // claim at all (not null, not "").
+    const payload = await stack.jwt.verify(body.token as string);
+    expect(payload.locale).toBeUndefined();
+  });
+
+  test("Bob accepts with a locale → JWT retains the locale", async () => {
+    await asRawClient(stack.db).unsafe(
+      `UPDATE "${userTable.tableName}" SET locale = $1 WHERE id = $2`,
+      ["de-DE", bobId],
+    );
+    try {
+      const token = await inviteEmail(BOB_EMAIL, "Editor");
+
+      const res = await stack.http.raw("POST", "/api/auth/invite-accept-with-login", {
+        token,
+        email: BOB_EMAIL,
+        password: BOB_PASSWORD,
+      });
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as { token?: string };
+      expect(body.token).toBeTypeOf("string");
+      if (!body.token) throw new Error("invite acceptance did not return a token");
+
+      const payload = await stack.jwt.verify(body.token);
+      expect(payload.locale).toBe("de-DE");
+    } finally {
+      // Bob is shared across this describe block (other tests rely on his
+      // membership state persisting) — restore his locale so later tests
+      // don't silently inherit it.
+      await asRawClient(stack.db).unsafe(
+        `UPDATE "${userTable.tableName}" SET locale = NULL WHERE id = $1`,
+        [bobId],
+      );
+    }
   });
 
   test("Bob accepts with a timezone → JWT retains the timezone", async () => {

package/src/auth-email-password/__tests__/login-mfa-setup-required.integration.test.ts

@@ -7,7 +7,8 @@
 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 { configureEntityFieldEncryption } from "@cosmicdrift/kumiko-framework/db";
+import type { SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import {
   createTestUser,
   setupTestStack,
@@ -18,11 +19,14 @@ import {
 } from "@cosmicdrift/kumiko-framework/stack";
 import { createTestEnvelopeCipher } from "@cosmicdrift/kumiko-framework/testing";
 import {
+  AuthMfaHandlers,
+  base32Decode,
   createAuthMfaFeature,
   mfaRequiredConfigHandle,
   mfaStatusCheckerFromFeature,
 } from "../../auth-mfa";
 import { userMfaEntity } from "../../auth-mfa/schema/user-mfa";
+import { currentTotpCode } from "../../auth-mfa/totp";
 import { ConfigHandlers, createConfigFeature } from "../../config";
 import { createConfigResolver } from "../../config/resolver";
 import { configValuesTable } from "../../config/table";
@@ -42,8 +46,20 @@ let stack: TestStack;
 const CHALLENGE_TOKEN_SECRET = "test-mfa-challenge-secret-at-least-32-bytes!!";
 const TENANT_ID: TenantId = testTenantId(400);
 
+// auth-mfa:write:enable-start-preauth / enable-confirm-preauth both run
+// pre-session (access: { roles: ["all"] }) — dispatched here the same way
+// the framework's /api/auth/mfa/preauth-enable-start and preauth-confirm
+// routes would, with a guest identity. Both handlers derive everything they
+// need from the verified token, not from this actor.
+const GUEST: SessionUser = {
+  id: "00000000-0000-0000-0000-000000000000",
+  tenantId: "00000000-0000-4000-8000-000000000000" as TenantId,
+  roles: ["all"],
+};
+
 beforeAll(async () => {
   const encryption = createTestEnvelopeCipher(randomBytes(32).toString("base64"));
+  configureEntityFieldEncryption(encryption);
   const resolver = createConfigResolver({ cipher: encryption });
   const authMfaFeature = createAuthMfaFeature({
     setupTokenSecret: "test-mfa-setup-token-secret-at-least-32-bytes!!",
@@ -126,4 +142,76 @@ describe("login: mfa-setup-required carries a verifiable preauthSetupToken", ()
       expect(verified.payload).toEqual({ userId: created.id, tenantId: TENANT_ID });
     }
   });
+
+  // fw#2333 — completing the blocked login via auth-mfa:write:enable-start-
+  // preauth + enable-confirm-preauth must carry the user's stored locale
+  // into the session it mints, same as a plain login.
+  async function completeMfaSetupRequiredLogin(opts: {
+    actorId: number;
+    email: string;
+    locale?: string;
+  }): Promise<SessionUser> {
+    const password = "correct-horse-battery-2026";
+    const hash = await hashPassword(password);
+    const created = await stack.http.writeOk<{ id: string }>(
+      UserHandlers.create,
+      {
+        email: opts.email,
+        passwordHash: hash,
+        displayName: "Unenrolled",
+        ...(opts.locale !== undefined && { locale: opts.locale }),
+      },
+      createTestUser({ id: opts.actorId, 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: opts.actorId + 1, tenantId: TENANT_ID, roles: ["Admin"] }),
+    );
+
+    const loginRes = await stack.http.raw("POST", "/api/auth/login", {
+      email: opts.email,
+      password,
+    });
+    expect(loginRes.status).toBe(200);
+    const loginBody = await loginRes.json();
+    expect(typeof loginBody.preauthSetupToken).toBe("string");
+
+    const start = await stack.http.writeOk<{ setupToken: string; otpauthUri: string }>(
+      AuthMfaHandlers.enableStartPreauth,
+      { preauthSetupToken: loginBody.preauthSetupToken, accountLabel: opts.email },
+      GUEST,
+    );
+    const secretParam = new URLSearchParams(start.otpauthUri.split("?")[1]).get("secret") ?? "";
+    const secret = base32Decode(secretParam);
+
+    const confirmed = await stack.http.writeOk<{ session: SessionUser }>(
+      AuthMfaHandlers.enableConfirmPreauth,
+      { setupToken: start.setupToken, code: currentTotpCode(secret) },
+      GUEST,
+    );
+    return confirmed.session;
+  }
+
+  test("completing mfa-setup-required via enable-start/confirm-preauth carries the user's locale", async () => {
+    const session = await completeMfaSetupRequiredLogin({
+      actorId: 501,
+      email: "preauth-locale@example.com",
+      locale: "de-DE",
+    });
+    expect(session.locale).toBe("de-DE");
+  });
+
+  test("completing mfa-setup-required via enable-start/confirm-preauth without a stored locale omits the claim", async () => {
+    const session = await completeMfaSetupRequiredLogin({
+      actorId: 503,
+      email: "preauth-nolocale@example.com",
+    });
+    expect(session.locale).toBeUndefined();
+  });
 });