@cosmicdrift/kumiko-bundled-features 0.220.1 → 0.222.0

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

package/src/auth-email-password/__tests__/magic-link-mail.test.ts

@@ -0,0 +1,38 @@
+import { beforeAll, describe, expect, test } from "bun:test";
+import { registerMailTranslations } from "@cosmicdrift/kumiko-framework/i18n";
+import { dispatchMagicLinkMail } from "../magic-link-mail";
+
+describe("dispatchMagicLinkMail appUrl locale negotiation", () => {
+  beforeAll(() => {
+    registerMailTranslations("de", { "test.unused": "x" });
+  });
+
+  test("negotiates de-AT down to de for language-in-path appUrl", async () => {
+    const seen: string[] = [];
+    await dispatchMagicLinkMail(
+      async () => {},
+      {
+        handlerName: "test",
+        notificationType: "test.mail",
+        renderContent: (args) => {
+          seen.push(args.url);
+          return {
+            subject: "s",
+            header: "h",
+            sections: [],
+            footer: "f",
+          };
+        },
+      },
+      {
+        email: "a@example.com",
+        appUrl: (locale) => `https://app.example.com/${locale}/activate`,
+        token: "tok",
+        expiresAt: "2099-01-01T00:00:00Z",
+        locale: "de-AT",
+      },
+    );
+    expect(seen[0]).toContain("https://app.example.com/de/activate");
+    expect(seen[0]).not.toContain("/de-AT/");
+  });
+});

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

@@ -173,7 +173,7 @@ describe("multi-roles: privilege-escalation blocked via field-level write-access
       {
         id: targetId,
         version: 1,
-        changes: { roles: JSON.stringify(["SystemAdmin"]) },
+        changes: { roles: ["SystemAdmin"] },
       },
       tenantAdminSession,
     );
@@ -201,7 +201,7 @@ describe("multi-roles: privilege-escalation blocked via field-level write-access
       {
         id: userId,
         version: 1,
-        changes: { roles: JSON.stringify(["SystemAdmin"]) },
+        changes: { roles: ["SystemAdmin"] },
       },
       userSession,
     );

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

@@ -1,6 +1,7 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { randomBytes } from "node:crypto";
 import { authFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
+import { LOCALE_HEADER_NAME } from "@cosmicdrift/kumiko-framework/api";
 import { asRawClient, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { SYSTEM_TENANT_ID, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { registerMailTranslations } from "@cosmicdrift/kumiko-framework/i18n";
@@ -41,11 +42,6 @@ import { signResetToken } from "../reset-token";
 // directly (no jobRunner in the test stack → inline send).
 const emailTransport = createInMemoryTransport();
 
-// Kept in sync with LOCALE_HEADER_NAME in api-constants.ts by hand — that
-// constant is a framework-internal implementation detail, not exported from
-// the public /api barrel (same as TENANT_HEADER_NAME).
-const LOCALE_HEADER_NAME = "X-Locale";
-
 registerMailTranslations("de", localeDeBundle);
 
 // Records the userId every time the sessions feature's auto-revoke hook

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

@@ -26,6 +26,7 @@
 //      zusammen).
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { LOCALE_HEADER_NAME } from "@cosmicdrift/kumiko-framework/api";
 import { asRawClient, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
 import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
@@ -98,11 +99,6 @@ const tenantMembershipHookVendorFeature = defineFeature(
 
 const APP_ACTIVATION_URL = "https://app.example.com/signup/complete";
 
-// Kept in sync with LOCALE_HEADER_NAME in api-constants.ts by hand — that
-// constant is a framework-internal implementation detail, not exported from
-// the public /api barrel (same as TENANT_HEADER_NAME).
-const LOCALE_HEADER_NAME = "X-Locale";
-
 registerMailTranslations("de", localeDeBundle);
 
 // Activation mails now go through delivery (ctx.notify → channel-email). The

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

@@ -39,6 +39,11 @@ import {
   tenantInvitationEntity,
   tenantInvitationsTable,
 } from "../../tenant/invitation-table";
+// kumiko-lint-ignore cross-feature-import reserved-role check owned by tenant-feature
+import {
+  findForbiddenMembershipRole,
+  reservedMembershipRoleError,
+} from "../../tenant/membership-roles";
 // kumiko-lint-ignore cross-feature-import membership-seed-helper for a privileged cross-tenant add
 import { seedTenantMembership } from "../../tenant/seeding";
 // kumiko-lint-ignore cross-feature-import login-style password-check
@@ -204,6 +209,10 @@ export function createInviteAcceptWithLoginHandler(opts: InviteAcceptWithLoginOp
         const dbConn = ctx.db.raw;
 
         if (!alreadyMember) {
+          const forbiddenInviteRole = findForbiddenMembershipRole([invitationRole]);
+          if (forbiddenInviteRole !== undefined) {
+            return writeFailure(reservedMembershipRoleError(forbiddenInviteRole));
+          }
           await seedTenantMembership(dbConn, {
             userId,
             tenantId: invitationTenantId,

package/src/auth-email-password/handlers/invite-accept.write.ts

@@ -31,6 +31,11 @@ import {
   tenantInvitationEntity,
   tenantInvitationsTable,
 } from "../../tenant/invitation-table";
+// kumiko-lint-ignore cross-feature-import reserved-role check owned by tenant-feature
+import {
+  findForbiddenMembershipRole,
+  reservedMembershipRoleError,
+} from "../../tenant/membership-roles";
 // kumiko-lint-ignore cross-feature-import direkter membership-Lookup (ungefiltert, s. alreadyMember-Kommentar)
 import { tenantMembershipsTable } from "../../tenant/membership-table";
 // kumiko-lint-ignore cross-feature-import membership-seed-helper für privilegierten cross-tenant-add (analog provisionSignupAccount)
@@ -70,6 +75,7 @@ export function createInviteAcceptHandler() {
     // nutzen `roles: ["all"]` weil dort GUEST_USER mit ["all"]-role
     // dispatched wird.
     access: { openToAll: true },
+    // kumiko-lint-ignore complexity-budget invite branches (auth/anon/burn) stay in one handler
     handler: async (event, ctx) => {
       if (!ctx.redis) {
         return writeFailure(
@@ -142,6 +148,10 @@ export function createInviteAcceptHandler() {
           // ["SystemAdmin"]-Role akzeptiert; createSystemUser produziert
           // "system"-Role die NICHT matcht. Direkt-via-Executor bypassed
           // den Access-Check für privilegierte Cross-Tenant-Operationen.
+          const forbiddenInviteRole = findForbiddenMembershipRole([invitationRole]);
+          if (forbiddenInviteRole !== undefined) {
+            return writeFailure(reservedMembershipRoleError(forbiddenInviteRole));
+          }
           await seedTenantMembership(dbConn, {
             userId: event.user.id,
             tenantId: invitationTenantId,

package/src/auth-email-password/handlers/invite-create.write.ts

@@ -17,7 +17,7 @@
 // erlaubt new-user-signup mit dem Token. Keine Enumeration durchs
 // invite-create.
 
-import { generateToken, requestContext } from "@cosmicdrift/kumiko-framework/api";
+import { generateToken } from "@cosmicdrift/kumiko-framework/api";
 import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
 import { access, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
@@ -41,7 +41,7 @@ import { AUTH_INVITE_DEFAULT_TTL_MINUTES } from "../constants";
 import type { AuthMailLocale } from "../email-templates";
 import { renderInviteEmail } from "../email-templates";
 import { invalidateExistingInviteToken, storeInviteToken } from "../invite-token-store";
-import { dispatchMagicLinkMail } from "../magic-link-mail";
+import { dispatchMagicLinkMail, resolveHandlerMailLocale } from "../magic-link-mail";
 
 const INVITE_NOTIFICATION_TYPE = "auth-email-password:invite";
 
@@ -77,6 +77,9 @@ export type InviteCreateOptions = {
   // roles, and cannot raise above the inviter's max framework rank — only
   // further restrict assignable ranked roles.
   readonly canAssignRole?: (inviterRoles: readonly string[], targetRole: string) => boolean;
+  /** Opt-in allow-list for app-defined (unranked) roles the elevation guard
+   *  would otherwise reject with unassignable_membership_role (fw#2398). */
+  readonly additionalAssignableRoles?: readonly string[];
 };
 
 const executor = createEventStoreExecutor(tenantInvitationsTable, tenantInvitationEntity, {
@@ -103,10 +106,15 @@ export function createInviteCreateHandler(opts: InviteCreateOptions) {
         return writeFailure(reservedMembershipRoleError(forbiddenRole));
       }
 
-      const elevationForbidden = findForbiddenRoleAssignment(event.user.roles, [
-        event.payload.role,
-      ]);
-      if (elevationForbidden !== undefined) {
+      const elevationForbidden = findForbiddenRoleAssignment(
+        event.user.roles,
+        [event.payload.role],
+        [],
+      );
+      if (
+        elevationForbidden !== undefined &&
+        !opts.additionalAssignableRoles?.includes(elevationForbidden)
+      ) {
         return writeFailure(unassignableMembershipRoleError(elevationForbidden));
       }
 
@@ -168,10 +176,7 @@ export function createInviteCreateHandler(opts: InviteCreateOptions) {
 
       await storeInviteToken(ctx.redis, { invitationId, token, ttlSeconds });
 
-      // Same precedence as signup/reset/verify: the inviting admin's active
-      // browser language wins when the request carries one, else the
-      // handler's static opts.locale, else ctx.locale's own default.
-      const locale = requestContext.get()?.locale ?? opts.locale ?? ctx.locale;
+      const locale = resolveHandlerMailLocale(ctx, opts.locale);
 
       await dispatchMagicLinkMail(
         ctx.notify,

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

@@ -39,6 +39,11 @@ import {
   tenantInvitationEntity,
   tenantInvitationsTable,
 } from "../../tenant/invitation-table";
+// kumiko-lint-ignore cross-feature-import reserved-role check owned by tenant-feature
+import {
+  findForbiddenMembershipRole,
+  reservedMembershipRoleError,
+} from "../../tenant/membership-roles";
 // kumiko-lint-ignore cross-feature-import membership-seed-helper für privilegierten cross-tenant-add
 import { seedTenantMembership } from "../../tenant/seeding";
 // kumiko-lint-ignore cross-feature-import existence-check
@@ -143,6 +148,10 @@ export function createInviteSignupCompleteHandler() {
         // Membership-Add via seed-helper (gleiches Pattern wie
         // provisionSignupAccount — bypassed addMember access-check
         // weil createSystemUser nicht ["SystemAdmin"] matcht).
+        const forbiddenInviteRole = findForbiddenMembershipRole([invitationRole]);
+        if (forbiddenInviteRole !== undefined) {
+          return writeFailure(reservedMembershipRoleError(forbiddenInviteRole));
+        }
         await seedTenantMembership(dbConn, {
           userId,
           tenantId: invitationTenantId,

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

@@ -21,7 +21,7 @@
 // suppressing the link on the request side would be defense-in-depth, but
 // with an enumeration risk of its own (separate concern).
 
-import { generateToken, requestContext } from "@cosmicdrift/kumiko-framework/api";
+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 "temporal-polyfill";
@@ -29,7 +29,7 @@ import { z } from "zod";
 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 { dispatchMagicLinkMail, resolveHandlerMailLocale } from "../magic-link-mail";
 import { AUTH_SELF_REGISTRATION_FEATURE } from "../self-registration-toggle";
 import {
   invalidateExistingSignupToken,
@@ -133,15 +133,7 @@ export function createSignupRequestHandler(opts: SignupRequestOptions) {
       // get the same format.
       const normalizedEmail = normalizeEmail(email);
 
-      // ctx.locale always resolves to something (falls back to the app's
-      // boot default, then "en" — dispatch-shared.ts), so it can't tell us
-      // whether THIS request actually carried a locale signal. Read the raw
-      // request-layer value instead: present → the browser's active
-      // language wins over opts.locale (this handler's static config);
-      // absent → opts.locale is the real, still-relevant fallback
-      // (backwards compatibility for callers that configured it and never
-      // send X-Locale), then ctx.locale's own resolved default.
-      const locale = requestContext.get()?.locale ?? opts.locale ?? ctx.locale;
+      const locale = resolveHandlerMailLocale(ctx, opts.locale);
 
       await dispatchMagicLinkMail(
         ctx.notify,

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

@@ -12,7 +12,6 @@
 // default TTL, extra skip condition) + two error codes — encoded on the
 // spec rather than duplicated across two near-identical handler bodies.
 
-import { requestContext } from "@cosmicdrift/kumiko-framework/api";
 import { createSystemUser, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import type { Temporal } from "temporal-polyfill";
@@ -20,7 +19,7 @@ import { z } from "zod";
 import { UserQueries } from "../../user";
 import { type AuthUserRow, parseAuthUserRow } from "../auth-user-row";
 import type { AuthMailContent, AuthMailLocale, RenderTokenContentArgs } from "../email-templates";
-import { dispatchMagicLinkMail } from "../magic-link-mail";
+import { dispatchMagicLinkMail, resolveHandlerMailLocale } from "../magic-link-mail";
 
 const RequestTokenSchema = z.object({
   email: z.email(),
@@ -124,14 +123,7 @@ export function createTokenRequestHandler<TName extends string, TSuccessKind ext
 
       const { token, expiresAt } = spec.sign(user.id, ttl, opts.hmacSecret);
 
-      // ctx.locale always resolves to something (falls back to the app's
-      // boot default, then "en"), so it can't tell us whether THIS request
-      // actually carried a locale signal. Read the raw request-layer value
-      // instead: present → the requester's active language wins over
-      // opts.locale (this handler's static config); absent → opts.locale
-      // is the real, still-relevant fallback, then ctx.locale's own
-      // resolved default.
-      const locale = requestContext.get()?.locale ?? opts.locale ?? ctx.locale;
+      const locale = resolveHandlerMailLocale(ctx, opts.locale);
 
       await dispatchMagicLinkMail(
         ctx.notify,

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

@@ -115,6 +115,7 @@ export const defaultTranslations: TranslationsByLocale = {
     "auth.signupComplete.submitting": "…",
     "auth.signupComplete.missingToken":
       "Activation link is missing a token. Please request a new one.",
+    "auth.signupComplete.activatedTitle": "Account activated",
     "auth.signupComplete.activated": "Your account is active and you're signed in.",
     "auth.signupComplete.continue": "Continue",
     "auth.inviteAccept.title": "Accept invitation",

package/src/auth-email-password/magic-link-mail.ts

@@ -6,8 +6,10 @@
 // non-unsubscribable). No r.notification is declared; buildMessage falls back
 // to the structured `data` for the renderer.
 
+import { requestContext } from "@cosmicdrift/kumiko-framework/api";
 import type { NotifyFn } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { resolveMailLocale } from "@cosmicdrift/kumiko-framework/i18n";
 import type { AuthMailContent, AuthMailLocale, RenderTokenContentArgs } from "./email-templates";
 
 // Per-flow constants: which notification type to dispatch and how to render the
@@ -43,6 +45,17 @@ function appendToken(appUrl: string, token: string): string {
   return `${appUrl}${sep}token=${encodeURIComponent(token)}`;
 }
 
+// X-Locale on the request wins over the handler's static opts.locale, then
+// ctx.locale's resolved default (always set — boot default / "en"). Reading
+// requestContext is load-bearing: ctx.locale alone cannot tell whether THIS
+// request carried a locale signal.
+export function resolveHandlerMailLocale(
+  ctx: { readonly locale?: string },
+  optsLocale: string | undefined,
+): string | undefined {
+  return requestContext.get()?.locale ?? optsLocale ?? ctx.locale;
+}
+
 export async function dispatchMagicLinkMail(
   notify: NotifyFn | undefined,
   spec: MagicLinkMailSpec,
@@ -57,8 +70,11 @@ export async function dispatchMagicLinkMail(
     });
   }
   const locale = params.locale ?? "en";
+  // mailT already root-falls-back; appUrl must use the same negotiated tag
+  // or language-in-path apps 404 on e.g. /de-AT/activate.
+  const urlLocale = resolveMailLocale(locale);
   const content = spec.renderContent({
-    url: appendToken(resolveAppUrl(params.appUrl, locale), params.token),
+    url: appendToken(resolveAppUrl(params.appUrl, urlLocale), params.token),
     expiresAt: params.expiresAt,
     ...(params.locale !== undefined && { locale: params.locale }),
     ...(params.appName !== undefined && { appName: params.appName }),

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

@@ -108,7 +108,9 @@ export async function seedUserWithPassword(
  *  (SessionUser-Konstruktion für JWT-Mint) — sonst hätten zwei
  *  Stellen unabhängig "TenantAdmin" hardcoded und würden bei einem
  *  Refactor zu role-mismatch zwischen DB und Session leiden. */
-export const INITIAL_SIGNUP_ROLES = ["TenantAdmin"] as const;
+// TenantAdmin is the canonical owner role; Admin stays for handlers that still
+// gate on the legacy literal until those call sites move to access.admin.
+export const INITIAL_SIGNUP_ROLES = ["TenantAdmin", "Admin"] as const;
 
 export type ProvisionSignupAccountOptions = {
   readonly email: string;

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

@@ -100,7 +100,7 @@ describe("SignupCompleteScreen", () => {
 
       // Continue button targets exactly what resolveLoggedInHref computes from
       // the response's tenantKey, via the app-supplied function-form prop.
-      const continueLink = screen.getByRole("link", { name: "Continue" }) as HTMLAnchorElement;
+      const continueLink = screen.getByRole("link", { name: "Continue" });
       expect(continueLink.getAttribute("href")).toBe("/acme/");
     } finally {
       window.location.assign = assignOrig;