@cosmicdrift/kumiko-bundled-features 0.211.0 → 0.213.0

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

@@ -29,12 +29,14 @@ import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:tes
 import { asRawClient, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
 import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { registerMailTranslations } from "@cosmicdrift/kumiko-framework/i18n";
 import {
   setupTestStack,
   type TestStack,
   unsafeCreateEntityTable,
   unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/stack";
+import { localeDeBundle } from "@cosmicdrift/kumiko-locale-de";
 import { createChannelEmailFeature, createInMemoryTransport } from "../../channel-email";
 import { createConfigFeature } from "../../config";
 import { createConfigResolver } from "../../config/resolver";
@@ -96,6 +98,13 @@ 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
 // in-memory transport captures what would be sent; route:{email} delivers
 // directly (no jobRunner in the test stack → inline send).
@@ -177,8 +186,11 @@ beforeEach(async () => {
   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 });
+async function postSignupRequest(
+  email: string,
+  headers?: Record<string, string>,
+): Promise<Response> {
+  return stack.http.raw("POST", "/api/auth/signup-request", { email }, headers);
 }
 
 async function postSignupConfirm(token: string, password: string): Promise<Response> {
@@ -425,3 +437,164 @@ describe("POST /api/auth/signup-confirm", () => {
     expect(userRows).toHaveLength(0);
   });
 });
+
+describe("POST /api/auth/signup-request — mail locale follows the active browser language", () => {
+  // The stack config sets no `signup.locale` (see beforeAll above) — this
+  // isolates ctx.locale as the only possible source, so a German subject
+  // here can only come from the X-Locale header, never from opts.locale.
+  test("X-Locale: de → the activation mail is rendered in German", async () => {
+    const res = await postSignupRequest("locale-de@example.com", { [LOCALE_HEADER_NAME]: "de" });
+    expect(res.status).toBe(200);
+    expect(emailTransport.sent).toHaveLength(1);
+    const sent = emailTransport.sent[0];
+    if (!sent) throw new Error("no mail sent");
+    expect(sent.subject).toContain("Account aktivieren");
+  });
+
+  test("no X-Locale header → the activation mail falls back to English", async () => {
+    const res = await postSignupRequest("locale-default@example.com");
+    expect(res.status).toBe(200);
+    expect(emailTransport.sent).toHaveLength(1);
+    const sent = emailTransport.sent[0];
+    if (!sent) throw new Error("no mail sent");
+    expect(sent.subject).toContain("Activate your account");
+  });
+});
+
+describe("POST /api/auth/signup-request — opts.locale stays a real fallback", () => {
+  // Regression guard: ctx.locale is always resolved (never undefined), so a
+  // naive `ctx.locale ?? opts.locale` would make opts.locale unreachable and
+  // silently drop every app's configured mail language the moment this PR
+  // ships. This stack configures signup.locale statically (no defaultLocale
+  // on the app context either) — a request with no X-Locale header must
+  // still land in the handler's configured language, not "en".
+  const optsLocaleTransport = createInMemoryTransport();
+  let optsLocaleStack: TestStack;
+
+  beforeAll(async () => {
+    optsLocaleStack = await setupTestStack({
+      features: [
+        createConfigFeature(),
+        createUserFeature(),
+        createTenantFeature(),
+        createTemplateResolverFeature(),
+        createRendererFoundationFeature(),
+        createDeliveryFeature(),
+        createRendererSimpleFeature(),
+        createChannelEmailFeature({
+          transport: optsLocaleTransport,
+          renderer: simpleRenderer,
+          resolveEmail: async () => "unused@test.local",
+        }),
+        createAuthEmailPasswordFeature({
+          signup: { tokenTtlMinutes: 60, appUrl: APP_ACTIVATION_URL, locale: "de" },
+        }),
+      ],
+      extraContext: (deps) => ({
+        ...createDeliveryTestContext(deps),
+        configResolver: createConfigResolver(),
+      }),
+      authConfig: {
+        membershipQuery: "tenant:query:memberships",
+        loginHandler: AuthHandlers.login,
+        signup: {
+          requestHandler: AuthHandlers.signupRequest,
+          confirmHandler: AuthHandlers.signupConfirm,
+        },
+      },
+    });
+    await unsafeCreateEntityTable(optsLocaleStack.db, userEntity);
+    await unsafeCreateEntityTable(optsLocaleStack.db, tenantEntity);
+    await unsafePushTables(optsLocaleStack.db, {
+      configValuesTable,
+      tenantMembershipsTable,
+      notificationPreferencesTable,
+    });
+  });
+
+  afterAll(async () => {
+    await optsLocaleStack.cleanup();
+  });
+
+  test("no X-Locale header → falls back to the handler's configured opts.locale, not English", async () => {
+    const res = await optsLocaleStack.http.raw("POST", "/api/auth/signup-request", {
+      email: "opts-locale@example.com",
+    });
+    expect(res.status).toBe(200);
+    expect(optsLocaleTransport.sent).toHaveLength(1);
+    const sent = optsLocaleTransport.sent[0];
+    if (!sent) throw new Error("no mail sent");
+    expect(sent.subject).toContain("Account aktivieren");
+  });
+});
+
+describe("POST /api/auth/signup-request — appUrl as a function picks the activation link's locale", () => {
+  // This is the actual mechanism the whole PR exists for: an app with
+  // language-in-path routing (/de/activate, /en/activate, ...) passes a
+  // function instead of a plain string, and the resolved locale must land
+  // in the link the user actually clicks — not just the mail's language.
+  const appUrlTransport = createInMemoryTransport();
+  let appUrlStack: TestStack;
+
+  beforeAll(async () => {
+    appUrlStack = await setupTestStack({
+      features: [
+        createConfigFeature(),
+        createUserFeature(),
+        createTenantFeature(),
+        createTemplateResolverFeature(),
+        createRendererFoundationFeature(),
+        createDeliveryFeature(),
+        createRendererSimpleFeature(),
+        createChannelEmailFeature({
+          transport: appUrlTransport,
+          renderer: simpleRenderer,
+          resolveEmail: async () => "unused@test.local",
+        }),
+        createAuthEmailPasswordFeature({
+          signup: {
+            tokenTtlMinutes: 60,
+            appUrl: (locale) => `https://app.example.com/${locale}/activate`,
+          },
+        }),
+      ],
+      extraContext: (deps) => ({
+        ...createDeliveryTestContext(deps),
+        configResolver: createConfigResolver(),
+      }),
+      authConfig: {
+        membershipQuery: "tenant:query:memberships",
+        loginHandler: AuthHandlers.login,
+        signup: {
+          requestHandler: AuthHandlers.signupRequest,
+          confirmHandler: AuthHandlers.signupConfirm,
+        },
+      },
+    });
+    await unsafeCreateEntityTable(appUrlStack.db, userEntity);
+    await unsafeCreateEntityTable(appUrlStack.db, tenantEntity);
+    await unsafePushTables(appUrlStack.db, {
+      configValuesTable,
+      tenantMembershipsTable,
+      notificationPreferencesTable,
+    });
+  });
+
+  afterAll(async () => {
+    await appUrlStack.cleanup();
+  });
+
+  test("X-Locale: de → the activation link in the sent mail points at /de/activate", async () => {
+    const res = await appUrlStack.http.raw(
+      "POST",
+      "/api/auth/signup-request",
+      { email: "appurl-de@example.com" },
+      { [LOCALE_HEADER_NAME]: "de" },
+    );
+    expect(res.status).toBe(200);
+    expect(appUrlTransport.sent).toHaveLength(1);
+    const sent = appUrlTransport.sent[0];
+    if (!sent) throw new Error("no mail sent");
+    expect(sent.html).toContain("https://app.example.com/de/activate?token=");
+  });
+});

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

@@ -64,8 +64,10 @@ export type PasswordResetOptions = {
   readonly tokenTtlMinutes?: number;
   // App page that receives the magic-link; the handler appends `?token=…` and
   // sends the mail via delivery (ctx.notify). No sendResetEmail callback — the
-  // app mounts `delivery` + a mail channel instead.
-  readonly appUrl: string;
+  // app mounts `delivery` + a mail channel instead. Apps with language-in-path
+  // routing may pass a function to pick the right page for the resolved
+  // locale instead of a plain string.
+  readonly appUrl: string | ((locale: string) => string);
   readonly appName?: string;
   readonly locale?: AuthMailLocale;
 };
@@ -80,8 +82,10 @@ export type EmailVerificationOptions = {
   readonly tokenTtlMinutes?: number;
   readonly mode?: "strict" | "off";
   // App page that receives the magic-link; the handler appends `?token=…` and
-  // sends via delivery (ctx.notify). No sendVerificationEmail callback.
-  readonly appUrl: string;
+  // sends via delivery (ctx.notify). No sendVerificationEmail callback. Apps
+  // with language-in-path routing may pass a function to pick the right page
+  // for the resolved locale instead of a plain string.
+  readonly appUrl: string | ((locale: string) => string);
   readonly appName?: string;
   readonly locale?: AuthMailLocale;
 };
@@ -169,6 +173,7 @@ export function createAuthEmailPasswordFeature(
     r.describe(
       "Provides email+password authentication: the always-on handlers are `login`, `changePassword`, and `logout`; optional flows — password reset, email verification, magic-link self-signup, tenant invite, and account-unlock — are registered only when you pass their respective option objects (`passwordReset`, `emailVerification`, `signup`, `invite`, `accountUnlock`) to `createAuthEmailPasswordFeature(opts)`. All five magic-link flows dispatch their mail through the `delivery` feature via `ctx.notify`, so mounting any of them additionally requires `delivery`. Tokens are HMAC-signed (reset/verify/unlock) or opaque-random in Redis (signup/invite). `accountUnlock` is the self-service escape hatch for `accountLockout`'s monotonic failure-counter (#1266): confirming the mailed token clears the Redis lockout state without touching the user entity. Requires the `user` and `tenant` features, and declares `JWT_SECRET` (≥ 32 chars) in `authEmailPasswordEnvSchema` so a missing secret surfaces at boot validation rather than on the first login attempt.",
     );
+    // kumiko-lint-ignore i18n-ui-strings uiHints labels are feature-registry metadata for the admin feature catalog, not yet wired to the i18n system, see #2312
     r.uiHints({
       displayLabel: "Auth \u00b7 Email + Password",
       category: "identity",

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 } from "@cosmicdrift/kumiko-framework/api";
+import { generateToken, requestContext } 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";
@@ -62,9 +62,14 @@ export type InviteCreateOptions = {
   /** TTL für den Activation-Token. Default 7 Tage. */
   readonly tokenTtlMinutes?: number;
   /** App page that receives the magic-link; the handler appends `?token=…`
-   *  and dispatches the invite mail via delivery (ctx.notify). */
-  readonly appUrl: string;
+   *  and dispatches the invite mail via delivery (ctx.notify). Apps with
+   *  language-in-path routing pass a function to pick the right page for
+   *  the resolved locale; everyone else keeps a plain string. */
+  readonly appUrl: string | ((locale: string) => string);
   readonly appName?: string;
+  /** Static fallback mail locale, used only when the request itself
+   *  carries no locale signal (no X-Locale header, no usable
+   *  Accept-Language) — see the locale resolution in the handler below. */
   readonly locale?: AuthMailLocale;
   // Opt-in role-hierarchy gate. Roles are app-defined strings, not a framework
   // concept, so the hierarchy itself must live in the app — this hook lets it
@@ -154,6 +159,11 @@ 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;
+
       await dispatchMagicLinkMail(
         ctx.notify,
         {
@@ -168,7 +178,7 @@ export function createInviteCreateHandler(opts: InviteCreateOptions) {
           token,
           expiresAt: expiresAt.toString(),
           ...(opts.appName !== undefined && { appName: opts.appName }),
-          ...(opts.locale !== undefined && { locale: opts.locale }),
+          locale,
         },
       );
 

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

@@ -1,27 +1,27 @@
-// Magic-Link-Signup, Step 1 (request).
+// Magic-link signup, step 1 (request).
 //
-// User gibt Email ein → wir minten einen opaken Random-Token, speichern
-// ihn bidirektional in Redis (token↔email), und schicken die Activation-Mail
-// via delivery (ctx.notify) — wie reset/verify. Anders als die: HIER kein
-// userId-Lookup und kein HMAC-signing (es gäbe kein Subject — im Normalfall
-// existiert der User noch nicht). Ob die Email bereits ein Konto hat,
-// entscheidet bewusst der Confirm-Schritt, nicht dieser.
+// User enters an email → we mint an opaque random token, store it
+// bidirectionally in Redis (token<->email), and send the activation mail
+// via delivery (ctx.notify) — same as reset/verify. Unlike those: NO
+// userId lookup and NO HMAC signing here (there'd be no subject — normally
+// the user doesn't exist yet). Whether the email already has an account is
+// deliberately decided by the confirm step, not this one.
 //
 // Resend: if a token is still live for this email, we invalidate it and
 // mint a fresh one — the user gets a second mail with a NEW activation
 // link, and the first link stops working. Deliberate: at most one live
 // signup token per email at any time (see signup-token-store.ts).
 //
-// Always-200 (enumeration-safe): das Response sieht für jede Email gleich
-// aus, egal ob sie schon registriert ist oder nicht. Eine Email KANN bereits
-// ein Konto haben (Seeding oder früherer Signup) — die Sperre dagegen sitzt
-// bewusst im Confirm-Schritt (#365): signup-confirm lehnt eine bereits
-// registrierte Email ab statt den bestehenden User wiederzuverwenden. Hier
-// bleibt's always-200 + Resend-idempotent, damit der Request-Pfad nichts
-// leakt; ein request-seitiges Unterdrücken des Links wäre Defense-in-depth,
-// aber mit Enumeration-Risiko (separat).
+// Always-200 (enumeration-safe): the response looks the same for every
+// email, whether it's already registered or not. An email CAN already have
+// an account (seeding or an earlier signup) — the actual gate sits
+// deliberately in the confirm step (#365): signup-confirm rejects an
+// already-registered email instead of reusing the existing user. Here it
+// stays always-200 + resend-idempotent so the request path leaks nothing;
+// 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 { generateToken, requestContext } 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";
@@ -53,13 +53,18 @@ export type SignupRequestData =
   | { readonly kind: "no-op" };
 
 export type SignupRequestOptions = {
-  /** TTL für den Activation-Token. Default 24 h — lang genug damit User
-   *  "morgen aktivieren" können ohne Resend-Spam. */
+  /** TTL for the activation token. Default 24h — long enough that users
+   *  can "activate tomorrow" without resend spam. */
   readonly tokenTtlMinutes?: number;
   /** App page that receives the magic-link; the handler appends `?token=…`
-   *  and dispatches the activation mail via delivery (ctx.notify). */
-  readonly appUrl: string;
+   *  and dispatches the activation mail via delivery (ctx.notify). Apps
+   *  with language-in-path routing pass a function to pick the right page
+   *  for the resolved locale; everyone else keeps a plain string. */
+  readonly appUrl: string | ((locale: string) => string);
   readonly appName?: string;
+  /** Static fallback mail locale for this handler instance, used only when
+   *  the request itself carries no locale signal (no X-Locale header, no
+   *  usable Accept-Language) — see the locale resolution below. */
   readonly locale?: AuthMailLocale;
 };
 
@@ -101,22 +106,21 @@ export function createSignupRequestHandler(opts: SignupRequestOptions) {
         );
       }
 
-      // Email-Normalisierung lebt im Store (signup-token-store). Der
-      // Handler reicht die raw email durch — eine Quelle, kein Drift
-      // zwischen Lookup-Pfaden die unterschiedlich (oder gar nicht)
-      // lowercased haben.
+      // Email normalization lives in the store (signup-token-store). The
+      // handler passes the raw email through — one source, no drift
+      // between lookup paths that lowercase differently (or not at all).
       const email = event.payload.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 zu 43 chars. Math.random war früher ein Bug:
-      // xorshift128+ hat ~128 Bit State der nach ~5 beobachteten
-      // Outputs rekonstruierbar ist — Angreifer könnte eigene
-      // signup-requests triggern und die Tokens fremder User
-      // vorhersagen. generateToken nutzt randomBytes aus node:crypto,
-      // dieselbe Quelle wie CSRF/Session-Tokens.
+      // 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 expiresAt = Temporal.Now.instant().add({ seconds: ttlSeconds });
@@ -124,11 +128,21 @@ export function createSignupRequestHandler(opts: SignupRequestOptions) {
 
       await storeSignupToken(ctx.redis, { email, token, ttlSeconds });
 
-      // normalizeEmail aus dem Store — eine Quelle für die Normalisierungs-
-      // Verantwortung; delivery-Empfänger + Lookup-Pfad kriegen konsistent
-      // das gleiche Format.
+      // normalizeEmail from the store — one source of truth for
+      // normalization; the delivery recipient + lookup path consistently
+      // 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;
+
       await dispatchMagicLinkMail(
         ctx.notify,
         {
@@ -142,7 +156,7 @@ export function createSignupRequestHandler(opts: SignupRequestOptions) {
           token,
           expiresAt: expiresAtIso,
           ...(opts.appName !== undefined && { appName: opts.appName }),
-          ...(opts.locale !== undefined && { locale: opts.locale }),
+          locale,
         },
       );
 

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

@@ -1,5 +1,6 @@
 // Shared factory for the request-side of out-of-band token flows
-// (password-reset, email-verification). Both follow the same shape:
+// (password-reset, email-verification, account-unlock). All follow the
+// same shape:
 //
 //   POST email
 //     → resolve user (system-scoped query)
@@ -11,6 +12,7 @@
 // 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";
@@ -70,9 +72,14 @@ export type TokenRequestSpec<TName extends string, TSuccessKind extends string>
 export type TokenRequestOptions = {
   readonly hmacSecret: string;
   readonly tokenTtlMinutes?: number;
-  // App page that receives the magic-link; the handler appends `?token=…`.
-  readonly appUrl: string;
+  /** App page that receives the magic-link; the handler appends `?token=…`.
+   *  Apps with language-in-path routing pass a function to pick the right
+   *  page for the resolved locale; everyone else keeps a plain string. */
+  readonly appUrl: string | ((locale: string) => string);
   readonly appName?: string;
+  /** Static fallback mail locale, used only when the request itself
+   *  carries no locale signal (no X-Locale header, no usable
+   *  Accept-Language) — see the locale resolution in the handler below. */
   readonly locale?: AuthMailLocale;
 };
 
@@ -117,6 +124,15 @@ 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;
+
       await dispatchMagicLinkMail(
         ctx.notify,
         {
@@ -132,7 +148,7 @@ export function createTokenRequestHandler<TName extends string, TSuccessKind ext
           token,
           expiresAt: expiresAt.toString(),
           ...(opts.appName !== undefined && { appName: opts.appName }),
-          ...(opts.locale !== undefined && { locale: opts.locale }),
+          locale,
         },
       );
 

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

@@ -115,6 +115,8 @@ export const defaultTranslations: TranslationsByLocale = {
     "auth.signupComplete.submitting": "…",
     "auth.signupComplete.missingToken":
       "Activation link is missing a token. Please request a new one.",
+    "auth.signupComplete.activated": "Your account is active and you're signed in.",
+    "auth.signupComplete.continue": "Continue",
     "auth.inviteAccept.title": "Accept invitation",
     "auth.inviteAccept.intro": "You've been invited to a workspace. Click 'Accept' to join.",
     "auth.inviteAccept.loggedInAs": "Signed in as {email}",

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

@@ -21,15 +21,23 @@ export type MagicLinkMailSpec = {
 
 // Per-request values: the recipient + the app page that receives the token, plus
 // optional presentation. appUrl is the bare page URL; the token is appended here.
+// appUrl as a function lets apps with language-in-path routing (/de/activate,
+// /en/activate) pick the right page for `locale` — the mail is the only
+// channel that survives a device switch (signup on desktop, open on mobile),
+// so this is the last point where the language can still reach the link.
 export type MagicLinkMailParams = {
   readonly email: string;
-  readonly appUrl: string;
+  readonly appUrl: string | ((locale: string) => string);
   readonly token: string;
   readonly expiresAt: string;
   readonly appName?: string;
   readonly locale?: AuthMailLocale;
 };
 
+function resolveAppUrl(appUrl: string | ((locale: string) => string), locale: string): string {
+  return typeof appUrl === "function" ? appUrl(locale) : appUrl;
+}
+
 function appendToken(appUrl: string, token: string): string {
   const sep = appUrl.includes("?") ? "&" : "?";
   return `${appUrl}${sep}token=${encodeURIComponent(token)}`;
@@ -48,8 +56,9 @@ export async function dispatchMagicLinkMail(
       message: `${spec.handlerName}: ctx.notify unavailable — the delivery feature must be mounted`,
     });
   }
+  const locale = params.locale ?? "en";
   const content = spec.renderContent({
-    url: appendToken(params.appUrl, params.token),
+    url: appendToken(resolveAppUrl(params.appUrl, locale), params.token),
     expiresAt: params.expiresAt,
     ...(params.locale !== undefined && { locale: params.locale }),
     ...(params.appName !== undefined && { appName: params.appName }),

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

@@ -57,12 +57,10 @@ describe("SignupCompleteScreen", () => {
     expect(fetchMock).not.toHaveBeenCalled();
   });
 
-  test("happy path: gültiges Passwort → signup-confirm fetch + location.assign", async () => {
-    const assigned: string[] = [];
+  test("happy path: gültiges Passwort → Bestätigung statt sofortigem Redirect, Weiter-Button trifft resolveLoggedInHref-Ziel", async () => {
+    const assignMock = mock((_url: string | URL): void => {});
     const assignOrig = window.location.assign.bind(window.location);
-    window.location.assign = ((url: string | URL) => {
-      assigned.push(String(url));
-    }) as typeof window.location.assign;
+    window.location.assign = assignMock as typeof window.location.assign;
 
     const fetchMock = mock(
       async () =>
@@ -94,8 +92,16 @@ describe("SignupCompleteScreen", () => {
             body: JSON.stringify({ token: "abc-token", password: "validpass1" }),
           }),
         );
-        expect(assigned).toEqual(["/acme/"]);
+        expect(screen.getByText("Your account is active and you're signed in.")).toBeTruthy();
       });
+
+      // No automatic redirect: the form is gone, but nothing navigated us away.
+      expect(assignMock).not.toHaveBeenCalled();
+
+      // 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;
+      expect(continueLink.getAttribute("href")).toBe("/acme/");
     } finally {
       window.location.assign = assignOrig;
     }
@@ -130,5 +136,8 @@ describe("SignupCompleteScreen", () => {
     await waitFor(() => {
       expect(screen.getByRole("alert").textContent).toMatch(/invalid|expired/i);
     });
+    // Error path stays on the form — no confirmation, no continue link.
+    expect(screen.queryByRole("link", { name: "Continue" })).toBeNull();
+    expect(document.getElementById("signup-password")).toBeTruthy();
   });
 });

package/src/auth-email-password/web/auth-form-primitives.tsx

@@ -50,6 +50,7 @@ export type AuthCardProps = {
   readonly children: ReactNode;
 };
 
+// kumiko-lint-ignore no-custom-primitives Wraps usePrimitives().Card, pure domain name for the auth-screen chrome, not a primitive reimplementation
 export function AuthCard({ title, subtitle, children }: AuthCardProps): ReactNode {
   const { Card } = usePrimitives();
   const shell = useAuthShell() ?? defaultAuthShell;
@@ -98,6 +99,7 @@ export function parseUrlToken(paramName = "token"): string {
 // (server-injected token) short-circuits both the URL read and the scrub.
 export function useUrlToken(override?: string, paramName = "token"): string {
   const [token] = useState(() => override ?? parseUrlToken(paramName));
+  // kumiko-lint-ignore no-raw-hooks DOM integration: history.replaceState scrubs the token from browser history once, no framework query/mutation equivalent
   useEffect(() => {
     if (override !== undefined) return;
     if (typeof window === "undefined") return;

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

@@ -76,6 +76,7 @@ export function createLoginRoute(
       readonly accountLabel: string;
     } | null>(null);
 
+    // kumiko-lint-ignore no-raw-hooks Phase-3 conversion tracked in #2312
     useEffect(() => {
       if (status === "authenticated") onAuthenticated?.();
     }, [status]);

package/src/auth-email-password/web/confirm-account-unlock-screen.tsx

@@ -33,6 +33,7 @@ export function ConfirmAccountUnlockScreen({
   const [status, setStatus] = useState<Status>(token === "" ? "missing-token" : "verifying");
   const startedRef = useRef(false);
 
+  // kumiko-lint-ignore no-raw-hooks Phase-3 conversion tracked in #2312
   useEffect(() => {
     if (status !== "verifying") return;
     if (startedRef.current) return;

package/src/auth-email-password/web/invite-accept-screen.tsx

@@ -61,6 +61,7 @@ export function InviteAcceptScreen({
   const acceptLoggedIn = async (): Promise<void> => {
     setSubmitting(true);
     setError(null);
+    // kumiko-lint-ignore no-raw-hooks Phase-3 conversion tracked in #2312
     const res = await fetch("/api/auth/invite-accept", {
       method: "POST",
       credentials: "same-origin",
@@ -83,6 +84,7 @@ export function InviteAcceptScreen({
   const acceptAnonExisting = async (): Promise<void> => {
     setSubmitting(true);
     setError(null);
+    // kumiko-lint-ignore no-raw-hooks Phase-3 conversion tracked in #2312
     const res = await fetch("/api/auth/invite-accept-with-login", {
       method: "POST",
       credentials: "same-origin",
@@ -105,6 +107,7 @@ export function InviteAcceptScreen({
   const acceptAnonNew = async (): Promise<void> => {
     setSubmitting(true);
     setError(null);
+    // kumiko-lint-ignore no-raw-hooks Phase-3 conversion tracked in #2312
     const res = await fetch("/api/auth/invite-signup-complete", {
       method: "POST",
       credentials: "same-origin",

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

@@ -128,6 +128,7 @@ export function SessionProvider({ children }: { readonly children: ReactNode }):
     setState(next);
   }, []);
 
+  // kumiko-lint-ignore no-raw-hooks Phase-3 conversion tracked in #2312
   useEffect(() => {
     void doRefresh();
   }, [doRefresh]);