@cosmicdrift/kumiko-samples 0.344.0 → 0.346.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.344.0",
+  "version": "0.346.0",
   "description": "Source trees of the Kumiko sample recipes, sample apps and bundled features in repo layout, for tooling such as few-shot corpus builds.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.344.0",
+  "version": "0.346.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>",

package/packages/bundled-features/src/audit/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.346.0",
+    "type": "improvement",
+    "title": "Audit queries can read app-instance system events with scope \"system\" (SystemAdmin only)",
+    "detail": "Audit queries accept `scope: \"system\"` for SystemAdmin\n`audit:query:list` and `audit:query:details` take an optional `scope` (`\"tenant\"` or `\"system\"`). With `\"system\"` a SystemAdmin reads the app-instance system events, e.g. `kumiko:system:app.started`; other roles are denied. Without `scope` nothing changes."
+  },
+  {
+    "version": "0.345.0",
+    "type": "fix",
+    "title": "Escape-hatch retention loads only expirable rows",
+    "detail": "Escape-hatch audit retention loads only rows that can expire\nThe retention job used to load every escapeHatchUse event to decide which ones to prune. It now reads the storing tenants with one grouped query and loads only events older than each storing tenant's cutoff. The same rows are pruned as before."
+  },
   {
     "version": "0.343.0",
     "type": "improvement",

package/packages/bundled-features/src/audit/constants.ts

@@ -19,6 +19,11 @@ export const AuditQueries = {
   details: "audit:query:details",
 } as const;
 
+/** Read scope of the audit queries: the caller's own tenant (default) or the system tenant (SystemAdmin only). */
+export const AuditScopes = { tenant: "tenant", system: "system" } as const;
+export type AuditScope = (typeof AuditScopes)[keyof typeof AuditScopes];
+export const AUDIT_SCOPE_VALUES = [AuditScopes.tenant, AuditScopes.system] as const;
+
 /** Tenant-admin audit log screen. Nav: `audit:screen:audit-log`. */
 export const AUDIT_LOG_SCREEN_ID = "audit-log" as const;
 

package/packages/bundled-features/src/audit/feature.ts

@@ -36,7 +36,7 @@ export function createAuditFeature(): FeatureDefinition {
     "audit",
     (r) => {
       r.describe(
-        "Exposes the framework's event store as a paginated, filterable audit log via the `audit:query:list` handler (accessible to `Admin` and `SystemAdmin` roles). No separate table or projection \u2014 the event store is the audit trail by construction: every entity write already records who, when, what entity, and the event payload with PII stripped. Filter by `aggregateType`, `aggregateId`, `eventType`, `userId`, or time range. Also records `audit:event:escape-hatch-used` whenever a handler uses one of the framework's escape hatches (unsafeRaw, acknowledgeCrossTenant, db.global() writes, or a granted identity switch).",
+        "Exposes the framework's event store as a paginated, filterable audit log via the `audit:query:list` handler (accessible to `Admin` and `SystemAdmin` roles). No separate table or projection \u2014 the event store is the audit trail by construction: every entity write already records who, when, what entity, and the event payload with PII stripped. A SystemAdmin can pass `scope: \"system\"` to read the app-instance system events such as `app.started`. Filter by `aggregateType`, `aggregateId`, `eventType`, `userId`, or time range. Also records `audit:event:escape-hatch-used` whenever a handler uses one of the framework's escape hatches (unsafeRaw, acknowledgeCrossTenant, db.global() writes, or a granted identity switch).",
       );
       r.uiHints({
         displayLabel: "Audit Log",

package/packages/bundled-features/src/audit/handlers/details.query.ts

@@ -1,21 +1,26 @@
 // Single audit event by its event-store id — backs the audit-log-detail
 // screen. Tenant-isolated at the WHERE level like list.query, so a caller
-// can only read events in their own tenant.
+// can only read events in their own tenant; a SystemAdmin can pass scope
+// "system" to read app-instance system events (e.g. app.started).
 
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { access, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import * as z from "zod";
+import { AUDIT_SCOPE_VALUES } from "../constants.js";
+import { resolveAuditScopeFilter } from "./resolve-audit-tenant.js";
 
 export const detailsQuery = defineQueryHandler({
   name: "details",
   description:
-    "Returns one audit-trail event of the caller's tenant by its event-store id, with full payload and metadata; use it to inspect the exact change behind a row of the audit log list.",
+    'Returns one audit-trail event of the caller\'s tenant by its event-store id, with full payload and metadata; use it to inspect the exact change behind a row of the audit log list. A SystemAdmin can set scope "system" to read an app-instance system event (e.g. app.started).',
   schema: z.object({
     id: z.string().regex(/^[1-9]\d*$/, "id must be a positive integer"),
+    scope: z.enum(AUDIT_SCOPE_VALUES).optional(),
   }),
   access: { roles: access.admin },
   handler: async (query, ctx) => {
+    const scopeFilter = resolveAuditScopeFilter(query.user, query.payload.scope);
     const rows = await selectMany<{
       id: bigint;
       aggregateId: string;
@@ -29,7 +34,13 @@ export const detailsQuery = defineQueryHandler({
     }>(
       ctx.db,
       eventsTable,
-      { tenantId: query.user.tenantId, id: BigInt(query.payload.id) },
+      {
+        tenantId: scopeFilter.tenantId,
+        ...(scopeFilter.aggregateType !== undefined && {
+          aggregateType: scopeFilter.aggregateType,
+        }),
+        id: BigInt(query.payload.id),
+      },
       { limit: 1 },
     );
     const row = rows[0];

package/packages/bundled-features/src/audit/handlers/list.query.ts

@@ -6,6 +6,8 @@
 // No projection, no separate audit table. Queryable with the same filter
 // surface any audit UI needs; tenant-isolated at the WHERE level so cross-
 // tenant peeking is structurally impossible for non-SystemAdmin callers.
+// A SystemAdmin can pass scope "system" to read the app-instance system events
+// (e.g. app.started); no other cross-tenant read exists.
 //
 // Sensitive field-values are ciphertext inside the event payload (the log
 // carries them encrypted); stripSensitive only strips the event echo. This
@@ -17,6 +19,8 @@ import { access, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine
 import { eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import { Temporal } from "temporal-polyfill";
 import * as z from "zod";
+import { AUDIT_SCOPE_VALUES } from "../constants.js";
+import { resolveAuditScopeFilter } from "./resolve-audit-tenant.js";
 
 const MAX_LIMIT = 100;
 
@@ -65,7 +69,7 @@ function buildAuditWhere(
 export const listQuery = defineQueryHandler({
   name: "list",
   description:
-    "Lists the tenant's audit-trail events newest-first with cursor paging, filterable by aggregate type, aggregate id, event type, actor and time range; use it to answer who changed what and when.",
+    'Lists the tenant\'s audit-trail events newest-first with cursor paging, filterable by aggregate type, aggregate id, event type, actor and time range; use it to answer who changed what and when. A SystemAdmin can set scope "system" to read the app-instance system events (e.g. app.started) instead of the own tenant.',
   schema: z
     .object({
       cursor: z.string().regex(/^\d+$/, "cursor must be a positive integer").optional(),
@@ -80,6 +84,7 @@ export const listQuery = defineQueryHandler({
       sortDirection: z.enum(["asc", "desc"]).optional(),
       from: z.iso.datetime().optional(),
       to: z.iso.datetime().optional(),
+      scope: z.enum(AUDIT_SCOPE_VALUES).optional(),
     })
     .refine((v) => !v.from || !v.to || v.from <= v.to, {
       message: "`from` must be less than or equal to `to`",
@@ -88,7 +93,11 @@ export const listQuery = defineQueryHandler({
   access: { roles: access.admin },
   handler: async (query, ctx) => {
     const p = query.payload;
-    const where = buildAuditWhere(query.user.tenantId, p);
+    const scopeFilter = resolveAuditScopeFilter(query.user, p.scope);
+    const where = buildAuditWhere(scopeFilter.tenantId, {
+      ...p,
+      aggregateType: scopeFilter.aggregateType ?? p.aggregateType,
+    });
 
     const rows = await selectMany<{
       id: bigint;

package/packages/bundled-features/src/audit/handlers/resolve-audit-tenant.ts

@@ -0,0 +1,22 @@
+import { crossTenantOverrideDenied, type SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import { APP_INSTANCE_STREAM_TYPE } from "@cosmicdrift/kumiko-framework/event-store";
+import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-types/identifiers";
+import { type AuditScope, AuditScopes } from "../constants.js";
+
+export type AuditScopeFilter = { readonly tenantId: string; readonly aggregateType?: string };
+
+// The system tenant also holds personal streams of other features (session
+// revocations, exports, ...); only app-instance streams are released.
+export function resolveAuditScopeFilter(
+  user: SessionUser,
+  scope: AuditScope | undefined,
+): AuditScopeFilter {
+  if (scope !== AuditScopes.system) return { tenantId: user.tenantId };
+  const denied = crossTenantOverrideDenied(
+    user,
+    SYSTEM_TENANT_ID,
+    "audit.errors.systemScopeRequiresSystemAdmin",
+  );
+  if (denied) throw denied;
+  return { tenantId: SYSTEM_TENANT_ID, aggregateType: APP_INSTANCE_STREAM_TYPE };
+}

package/packages/bundled-features/src/audit/i18n.ts

@@ -9,6 +9,9 @@ export const AUDIT_I18N: Readonly<Record<string, LocalizedString>> = {
   "audit.log.detail.subtitle": {
     en: "Read-only detail view of one audit event showing actor, timestamp, aggregate and the raw event payload and metadata; reached from a row of the audit log.",
   },
+  "audit.errors.systemScopeRequiresSystemAdmin": {
+    en: "Only SystemAdmin may read system events.",
+  },
   "audit:nav.auditLog": { en: "Audit" },
   "audit.log.col.when": { en: "When" },
   "audit.log.col.type": { en: "Event" },

package/packages/bundled-features/src/audit/run-escape-hatch-retention.ts

@@ -1,4 +1,4 @@
-import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { aggregateWhere, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   COMPLIANCE_PROFILES,
   subtractRetentionSpec,
@@ -82,10 +82,20 @@ function targetTenantOf(payload: unknown): TenantId | null {
   return parsed.success ? parseTenantId(parsed.data.targetTenantId) : null;
 }
 
-async function pruneByTenantProfiles(db: DbConnection): Promise<number> {
-  const rows = await selectMany<AuditEventRow>(db, eventsTable, {
-    aggregateType: ESCAPE_HATCH_USE_AGGREGATE_TYPE,
+async function storingTenantIds(db: DbConnection): Promise<readonly TenantId[]> {
+  const groups = await aggregateWhere(
+    db,
+    eventsTable,
+    { measure: { fn: "count" }, groupBy: [{ field: "tenantId" }] },
+    { aggregateType: ESCAPE_HATCH_USE_AGGREGATE_TYPE },
+  );
+  return groups.flatMap((group) => {
+    const tenantId = parseTenantId(group.keys[0]);
+    return tenantId ? [tenantId] : [];
   });
+}
+
+async function pruneByTenantProfiles(db: DbConnection): Promise<number> {
   const now = getTemporal().Now.instant();
   const cutoffByTenant = new Map<TenantId, Temporal.Instant>();
   const cutoffOf = async (tenantId: TenantId): Promise<Temporal.Instant> => {
@@ -96,15 +106,24 @@ async function pruneByTenantProfiles(db: DbConnection): Promise<number> {
     return cutoff;
   };
 
+  // The effective cutoff is never later than the storing tenant's, so only rows older than
+  // that one can expire; everything younger stays in the database.
   const expiredAggregateIds: string[] = [];
-  for (const row of rows) {
-    const targetTenantId = targetTenantOf(row.payload);
-    const storeCutoff = await cutoffOf(row.tenantId);
-    const cutoff = targetTenantId
-      ? earlierInstant(storeCutoff, await cutoffOf(targetTenantId))
-      : storeCutoff;
-    if (Temporal.Instant.compare(row.createdAt, cutoff) < 0) {
-      expiredAggregateIds.push(row.aggregateId);
+  for (const storingTenantId of await storingTenantIds(db)) {
+    const storeCutoff = await cutoffOf(storingTenantId);
+    const candidates = await selectMany<AuditEventRow>(db, eventsTable, {
+      aggregateType: ESCAPE_HATCH_USE_AGGREGATE_TYPE,
+      tenantId: storingTenantId,
+      createdAt: { lt: storeCutoff },
+    });
+    for (const row of candidates) {
+      const targetTenantId = targetTenantOf(row.payload);
+      const cutoff = targetTenantId
+        ? earlierInstant(storeCutoff, await cutoffOf(targetTenantId))
+        : storeCutoff;
+      if (Temporal.Instant.compare(row.createdAt, cutoff) < 0) {
+        expiredAggregateIds.push(row.aggregateId);
+      }
     }
   }
 

package/packages/bundled-features/src/auth-email-password/changes.json

@@ -1,4 +1,28 @@
 [
+  {
+    "version": "0.345.0",
+    "type": "fix",
+    "title": "invite-signup-complete enforces the MFA gate before issuing a session",
+    "detail": "`invite-signup-complete` now applies the same MFA gate as `invite-accept-with-login`. The account is still created and the invitation accepted, but an invitee whose role requires MFA (for example an admin invitation under the `admins` policy) receives the MFA step instead of a session. Member invitations keep receiving a session directly."
+  },
+  {
+    "version": "0.345.0",
+    "type": "fix",
+    "title": "signup-confirm enforces the MFA gate before issuing a session",
+    "detail": "`POST /auth/signup-confirm` now runs the login's MFA gate before it issues the first session. Self-signup makes the new user TenantAdmin of a fresh tenant, so under an MFA policy that covers admins the route used to hand out an admin session without a second factor. The account, the tenant and a bound handover claim are still created, but when the gate applies the route answers with the login contract (`mfaSetupRequired` plus `preauthSetupToken`, or `mfaRequired` plus `challengeToken`) and sets no cookies. `SignupCompleteScreen` then tells the user the account is active and sends them to sign in, where they set up the second factor. Without `mfaStatusChecker` nothing changes. Two exported types change shape: `SignupConfirmData` gains the two MFA variants, and `confirmSignup` now resolves to `SignupConfirmResult` with `kind: \"signed-in\"` (the previous `SignupConfirmSuccess` fields) or `kind: \"mfa-pending\"`. The handler and `invite-signup-complete` also run the gate before they delete the token, so an error in the MFA check leaves the link usable for a retry."
+  },
+  {
+    "version": "0.345.0",
+    "type": "fix",
+    "title": "switch-tenant enforces the MFA gate before issuing a session",
+    "detail": "`POST /auth/switch-tenant` now runs the same MFA gate as login before it issues the new session. A user who is a plain member in one tenant and an admin in another can no longer reach an admin session without a second factor by switching. When the target tenant requires MFA the route answers with the login contract (`mfaRequired` plus `challengeToken`, or `mfaSetupRequired` plus `preauthSetupToken`) and sets no cookies. The gate runs in a new system-only handler, `auth-email-password:write:switch-tenant-mfa-gate`, which resolves the membership and roles itself; `runDevApp` and `runProdApp` wire it as `switchTenantMfaGateHandler` whenever auth-mfa is mounted."
+  },
+  {
+    "version": "0.345.0",
+    "type": "fix",
+    "title": "Token mail expiry uses the recipient's profile time zone",
+    "detail": "Token mails show the expiry in the recipient's own time zone\nPassword reset, email verification and account unlock are requested anonymously, so `ctx.tz.user` only held the tenant default or UTC. These mails now use the recipient's profile time zone when it is a valid IANA zone and fall back to the previous value otherwise. Signup and invite mails keep the fallback because the recipient has no profile yet."
+  },
   {
     "version": "0.343.0",
     "type": "improvement",

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

@@ -46,6 +46,7 @@ export const AuthHandlers = {
   inviteAccept: "auth-email-password:write:invite-accept",
   inviteAcceptWithLogin: "auth-email-password:write:invite-accept-with-login",
   inviteSignupComplete: "auth-email-password:write:invite-signup-complete",
+  switchTenantMfaGate: "auth-email-password:write:switch-tenant-mfa-gate",
   inviteCancel: "auth-email-password:write:invite-cancel",
 } as const;
 

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

@@ -28,6 +28,7 @@ import {
   createSignupRequestHandler,
   type SignupRequestOptions,
 } from "./handlers/signup-request.write.js";
+import { createSwitchTenantMfaGateHandler } from "./handlers/switch-tenant-mfa-gate.write.js";
 import { createVerifyEmailHandler } from "./handlers/verify-email.write.js";
 
 /**
@@ -221,6 +222,10 @@ export function createAuthEmailPasswordFeature(
       logout: r.writeHandler(logoutWrite),
     };
 
+    if (opts.mfaStatusChecker) {
+      r.writeHandler(createSwitchTenantMfaGateHandler({ mfaStatusChecker: opts.mfaStatusChecker }));
+    }
+
     if (opts.passwordReset) {
       r.writeHandler(createRequestPasswordResetHandler(opts.passwordReset));
       r.writeHandler(createResetPasswordHandler(opts.passwordReset));
@@ -242,7 +247,7 @@ export function createAuthEmailPasswordFeature(
 
     if (opts.signup) {
       r.writeHandler(createSignupRequestHandler(opts.signup));
-      r.writeHandler(createSignupConfirmHandler());
+      r.writeHandler(createSignupConfirmHandler({ mfaStatusChecker: opts.mfaStatusChecker }));
     }
 
     if (opts.invite) {
@@ -258,7 +263,9 @@ export function createAuthEmailPasswordFeature(
           strictEmailVerification: strictVerification,
         }),
       );
-      r.writeHandler(createInviteSignupCompleteHandler());
+      r.writeHandler(
+        createInviteSignupCompleteHandler({ mfaStatusChecker: opts.mfaStatusChecker }),
+      );
     }
 
     if (opts.accountUnlock) {

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

@@ -60,18 +60,23 @@ import {
 import { passwordSchema } from "../password-policy.js";
 // kumiko-lint-ignore cross-feature-import provisioning needs cross-feature seeding helpers
 import { seedUserWithPassword } from "../seeding.js";
+import { gateEnforceMfa, type LoginHandlerOptions, type LoginResult } from "./login.write.js";
 
 const InviteSignupCompleteSchema = z.object({
   token: z.string().min(1),
   password: passwordSchema,
 });
 
-export type InviteSignupCompleteData = {
-  readonly kind: "auth-session";
-  readonly session: SessionUser;
-  readonly tenantId: TenantId;
-  readonly role: string;
-};
+export type InviteSignupCompleteData =
+  | {
+      readonly kind: "auth-session";
+      readonly session: SessionUser;
+      readonly tenantId: TenantId;
+      readonly role: string;
+    }
+  | Exclude<LoginResult, { readonly kind: "auth-session" }>;
+
+export type InviteSignupCompleteOptions = Pick<LoginHandlerOptions, "mfaStatusChecker">;
 
 const invitationExecutor = createEventStoreExecutor(
   tenantInvitationsTable,
@@ -82,7 +87,7 @@ const invitationExecutor = createEventStoreExecutor(
 const INVITE_SIGNUP_COMPLETE_ESCAPE_HATCH_REASON =
   "reads the pending invitation by id; the invitee is not yet a member of the invitation's tenant. Creates the user and adds the membership and accepts the invitation in the invitation's tenant, before any caller tenant context exists.";
 
-export function createInviteSignupCompleteHandler() {
+export function createInviteSignupCompleteHandler(opts: InviteSignupCompleteOptions = {}) {
   return defineWriteHandler<
     "invite-signup-complete",
     typeof InviteSignupCompleteSchema,
@@ -190,14 +195,32 @@ export function createInviteSignupCompleteHandler() {
         );
         if (!updateResult.isSuccess) return updateResult;
 
+        // buildSessionRoles calls stripForbiddenMembershipRoles internally —
+        // a reserved role on the invitation itself must never reach the session.
+        const mergedRoles = buildSessionRoles(invitationGlobalRoles, [invitationRole]);
+
+        // Same gate as invite-accept-with-login: the account exists after this
+        // call, but an MFA-gated role gets the MFA step instead of a session.
+        // It runs before the token is deleted so a throwing check leaves the link retryable.
+        const mfaGate = await gateEnforceMfa(
+          ctx,
+          { mfaStatusChecker: opts.mfaStatusChecker },
+          userId,
+          invitationTenantId,
+          mergedRoles,
+        );
+
         await deleteInviteToken(ctx.redis, { invitationId, token: event.payload.token });
 
+        if (mfaGate !== undefined) {
+          committed = true;
+          return { isSuccess: true, data: mfaGate };
+        }
+
         const session: SessionUser = {
           id: userId,
           tenantId: invitationTenantId,
-          // buildSessionRoles calls stripForbiddenMembershipRoles internally —
-          // a reserved role on the invitation itself must never reach the session.
-          roles: buildSessionRoles(invitationGlobalRoles, [invitationRole]),
+          roles: mergedRoles,
         };
 
         committed = true;

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

@@ -56,26 +56,29 @@ import {
   getSignupHandover,
   unburnSignupToken,
 } from "../signup-token-store.js";
+import { gateEnforceMfa, type LoginHandlerOptions, type LoginResult } from "./login.write.js";
 
 const SignupConfirmSchema = z.object({
   token: z.string().min(8),
   password: passwordSchema,
 });
 
-// Mirror der login-handler-Shape (kind: "auth-session", session: SessionUser)
-// damit die Route-Layer den signup-confirm-success genauso behandeln kann
-// wie einen erfolgreichen login: JWT-Mint, Cookies setzen, Session-Body
-// returnen. Der zusätzliche tenantKey landet als sibling am data-objekt
-// (NICHT in SessionUser — der ist generic, tenantKey ist signup-spezifisch
-// für den Post-Signup-Redirect zu /<tenantKey>/).
-export type SignupConfirmData = {
-  readonly kind: "auth-session";
-  readonly session: SessionUser;
-  readonly tenantKey: string;
-  // Present only when a bound tenant-handover grant existed AND its claim
-  // actually succeeded (see the handler body below).
-  readonly handover?: { readonly entityType: string; readonly id: string };
-};
+// Mirrors the login handler's session shape so the route treats a successful
+// confirm like a login. tenantKey stays a sibling of the session: it is only
+// for the post-signup redirect, SessionUser is generic. When the MFA gate
+// applies, the MFA step is returned instead of a session.
+export type SignupConfirmData =
+  | {
+      readonly kind: "auth-session";
+      readonly session: SessionUser;
+      readonly tenantKey: string;
+      // Present only when a bound tenant-handover grant existed AND its claim
+      // actually succeeded (see the handler body below).
+      readonly handover?: { readonly entityType: string; readonly id: string };
+    }
+  | Exclude<LoginResult, { readonly kind: "auth-session" }>;
+
+export type SignupConfirmOptions = Pick<LoginHandlerOptions, "mfaStatusChecker">;
 
 const SIGNUP_CONFIRM_PROVISION_REASON =
   "provisions a new tenant, its first user and membership before any tenant context exists";
@@ -123,7 +126,7 @@ async function claimBoundHandover(
   return undefined;
 }
 
-export function createSignupConfirmHandler() {
+export function createSignupConfirmHandler(opts: SignupConfirmOptions = {}) {
   return defineWriteHandler<"signup-confirm", typeof SignupConfirmSchema, SignupConfirmData>({
     name: "signup-confirm",
     schema: SignupConfirmSchema,
@@ -221,11 +224,25 @@ export function createSignupConfirmHandler() {
           ? await claimBoundHandover(ctx, session, handoverBinding)
           : undefined;
 
+        // Before the token keys go: a throwing MFA check must leave the link retryable.
+        const mfaGate = await gateEnforceMfa(
+          ctx,
+          { mfaStatusChecker: opts.mfaStatusChecker },
+          provisioned.userId,
+          provisioned.tenantId,
+          session.roles,
+        );
+
         // Drop both token lookup keys; the burn key stays for its remaining
         // TTL as replay protection.
         await deleteSignupToken(ctx.redis, { email, token: event.payload.token });
         if (handoverBinding) await deleteSignupHandover(ctx.redis, event.payload.token);
 
+        if (mfaGate !== undefined) {
+          committed = true;
+          return { isSuccess: true, data: mfaGate };
+        }
+
         committed = true;
         return {
           isSuccess: true,

package/packages/bundled-features/src/auth-email-password/handlers/switch-tenant-mfa-gate.write.ts

@@ -0,0 +1,60 @@
+import {
+  buildSessionRoles,
+  createSystemUser,
+  defineWriteHandler,
+  SYSTEM_ROLE,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { parseRoles } from "@cosmicdrift/kumiko-framework/utils";
+import * as z from "zod";
+import { UserQueries } from "../../user/index.js";
+import { parseAuthUserRow } from "../auth-user-row.js";
+import { noMembership } from "../errors.js";
+import { gateEnforceMfa, type LoginHandlerOptions } from "./login.write.js";
+
+const SwitchTenantMfaGateSchema = z.object({
+  userId: z.string().min(1),
+  tenantId: z
+    .string()
+    .min(1)
+    .transform((id) => id as TenantId),
+});
+
+export type SwitchTenantMfaGateData =
+  | { readonly kind: "mfa-gate-clear" }
+  | NonNullable<Awaited<ReturnType<typeof gateEnforceMfa>>>;
+
+// Dispatched by POST /auth/switch-tenant with the system identity. The handler
+// resolves membership and roles itself, so the gate never trusts caller-supplied
+// roles; system-only access keeps it out of reach of /api/write callers.
+export function createSwitchTenantMfaGateHandler(
+  opts: Pick<LoginHandlerOptions, "mfaStatusChecker">,
+) {
+  return defineWriteHandler<
+    "switch-tenant-mfa-gate",
+    typeof SwitchTenantMfaGateSchema,
+    SwitchTenantMfaGateData
+  >({
+    name: "switch-tenant-mfa-gate",
+    schema: SwitchTenantMfaGateSchema,
+    access: { roles: [SYSTEM_ROLE] },
+    escapeHatch: {
+      reason:
+        "reads the MFA enrollment of the switch target tenant, not the caller's current tenant, via the mfaStatusChecker callback (it uses ctx.db.unsafeRaw())",
+    },
+    agent: { expose: false },
+    description:
+      "Runs the MFA gate of the login for a tenant switch and answers with an MFA challenge, a setup requirement, or clearance.",
+    handler: async (event, ctx) => {
+      const { userId, tenantId } = event.payload;
+      const active = await ctx.resolveActiveMembership(userId, tenantId);
+      if (active.kind === "rejected") return noMembership();
+      const userRow = parseAuthUserRow(
+        await ctx.queryAs(createSystemUser(tenantId), UserQueries.findForAuth, { id: userId }),
+      );
+      const roles = buildSessionRoles(parseRoles(userRow?.roles ?? null), active.membership.roles);
+      const mfaGate = await gateEnforceMfa(ctx, opts, userId, tenantId, roles);
+      return { isSuccess: true, data: mfaGate ?? { kind: "mfa-gate-clear" } };
+    },
+  });
+}

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

@@ -14,6 +14,7 @@
 
 import { createSystemUser, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { isValidIanaTimeZone } from "@cosmicdrift/kumiko-framework/time";
 import type { Temporal } from "temporal-polyfill";
 import * as z from "zod";
 import { UserQueries } from "../../user/index.js";
@@ -89,6 +90,12 @@ export type TokenRequestOptions = {
   readonly locale?: AuthMailLocale;
 };
 
+// The requester is anonymous, so ctx.tz.user is only the tenant default; the recipient's
+// own profile zone is the one the expiry should be read in.
+function recipientTimeZone(user: AuthUserRow, fallbackTimeZone: string): string {
+  return user.timezone && isValidIanaTimeZone(user.timezone) ? user.timezone : fallbackTimeZone;
+}
+
 export function createTokenRequestHandler<TName extends string, TSuccessKind extends string>(
   spec: TokenRequestSpec<TName, TSuccessKind>,
   opts: TokenRequestOptions,
@@ -156,7 +163,7 @@ export function createTokenRequestHandler<TName extends string, TSuccessKind ext
           token,
           expiresAt: expiresAt.toString(),
           issuedAt,
-          timeZone: ctx.tz.user,
+          timeZone: recipientTimeZone(user, ctx.tz.user),
           ...(opts.appName !== undefined && { appName: opts.appName }),
           locale,
         },

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

@@ -116,6 +116,8 @@ export const defaultTranslations: TranslationsByLocale = {
     "auth.signupComplete.submitting": "…",
     "auth.signupComplete.missingToken":
       "Activation link is missing a token. Please request a new one.",
+    "auth.signupComplete.activatedMfaPending":
+      "Your account is active. Sign in to set up two-factor authentication.",
     "auth.signupComplete.activatedTitle": "Account activated",
     "auth.signupComplete.activated": "Your account is active and you're signed in.",
     "auth.signupComplete.continue": "Continue",

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

@@ -345,10 +345,10 @@ export async function requestSignup(
   return { ok: false, error: await parseTokenFailure(res) };
 }
 
-// POST /api/auth/signup-confirm. Token aus URL + Password. Erfolgreich:
-// Cookies (kumiko_auth + kumiko_csrf) werden gesetzt — User ist sofort
-// eingeloggt. Response liefert tenantKey für den Post-Signup-Redirect.
-// 422 invalid_signup_token bei abgelaufenem/unbekanntem Token.
+// POST /api/auth/signup-confirm. On success the server sets the auth cookies
+// (auto-login) and returns the tenantKey for the post-signup redirect, unless
+// the MFA gate applies (kind "mfa-pending", no session). 422 invalid_signup_token
+// for an expired or unknown token.
 export type SignupConfirmSuccess = {
   readonly user: { readonly id: string; readonly tenantId: string; readonly roles: string[] };
   readonly tenantKey: string;
@@ -360,10 +360,16 @@ export type SignupConfirmSuccess = {
   readonly landingPath?: string;
 };
 
+// mfa-pending: account exists but the server issued no session because the
+// new roles require a second factor — the user must sign in to enroll.
+export type SignupConfirmResult =
+  | ({ readonly kind: "signed-in" } & SignupConfirmSuccess)
+  | { readonly kind: "mfa-pending" };
+
 export async function confirmSignup(
   token: string,
   password: string,
-): Promise<{ ok: true; data: SignupConfirmSuccess } | { ok: false; error: AuthTokenFailure }> {
+): Promise<{ ok: true; data: SignupConfirmResult } | { ok: false; error: AuthTokenFailure }> {
   const res = await fetch("/api/auth/signup-confirm", {
     method: "POST",
     credentials: "same-origin",
@@ -371,8 +377,15 @@ export async function confirmSignup(
     body: JSON.stringify({ token, password }),
   });
   if (res.ok) {
-    const body = (await res.json()) as SignupConfirmSuccess; // @cast-boundary engine-payload
-    return { ok: true, data: body };
+    // @cast-boundary engine-payload
+    const body = (await res.json()) as SignupConfirmSuccess & {
+      readonly mfaRequired?: boolean;
+      readonly mfaSetupRequired?: boolean;
+    };
+    if (body.mfaRequired === true || body.mfaSetupRequired === true) {
+      return { ok: true, data: { kind: "mfa-pending" } };
+    }
+    return { ok: true, data: { kind: "signed-in", ...body } };
   }
   return { ok: false, error: await parseTokenFailure(res) };
 }