@cosmicdrift/kumiko-bundled-features 0.344.0 → 0.346.0

package/dist/audit/constants.d.ts

@@ -9,6 +9,13 @@ export declare const AuditQueries: {
     readonly list: "audit:query:list";
     readonly details: "audit:query:details";
 };
+/** Read scope of the audit queries: the caller's own tenant (default) or the system tenant (SystemAdmin only). */
+export declare const AuditScopes: {
+    readonly tenant: "tenant";
+    readonly system: "system";
+};
+export type AuditScope = (typeof AuditScopes)[keyof typeof AuditScopes];
+export declare const AUDIT_SCOPE_VALUES: readonly ["tenant", "system"];
 /** Tenant-admin audit log screen. Nav: `audit:screen:audit-log`. */
 export declare const AUDIT_LOG_SCREEN_ID: "audit-log";
 /** Single-event detail screen, breadcrumb-linked to the audit-log list. */

package/dist/audit/constants.js

@@ -14,6 +14,9 @@ export const AuditQueries = {
     list: "audit:query:list",
     details: "audit:query:details",
 };
+/** 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" };
+export const AUDIT_SCOPE_VALUES = [AuditScopes.tenant, AuditScopes.system];
 /** Tenant-admin audit log screen. Nav: `audit:screen:audit-log`. */
 export const AUDIT_LOG_SCREEN_ID = "audit-log";
 /** Single-event detail screen, breadcrumb-linked to the audit-log list. */

package/dist/audit/feature.js

@@ -20,7 +20,7 @@ import { runEscapeHatchRetention } from "./run-escape-hatch-retention.js";
 // framework).
 export function createAuditFeature() {
     return defineFeature("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).");
+        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. 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",
             category: "compliance",

package/dist/audit/handlers/details.query.d.ts

@@ -1,6 +1,10 @@
 import * as z from "zod";
 export declare const detailsQuery: import("@cosmicdrift/kumiko-types/define-handler").QueryHandlerDefinition<"details", z.ZodObject<{
     id: z.ZodString;
+    scope: z.ZodOptional<z.ZodEnum<{
+        system: "system";
+        tenant: "tenant";
+    }>>;
 }, z.core.$strip>, {
     id: string;
     aggregateId: string;

package/dist/audit/handlers/details.query.js

@@ -1,19 +1,30 @@
 // 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.",
+    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. 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 rows = await selectMany(ctx.db, eventsTable, { tenantId: query.user.tenantId, id: BigInt(query.payload.id) }, { limit: 1 });
+        const scopeFilter = resolveAuditScopeFilter(query.user, query.payload.scope);
+        const rows = await selectMany(ctx.db, eventsTable, {
+            tenantId: scopeFilter.tenantId,
+            ...(scopeFilter.aggregateType !== undefined && {
+                aggregateType: scopeFilter.aggregateType,
+            }),
+            id: BigInt(query.payload.id),
+        }, { limit: 1 });
         const row = rows[0];
         if (row === undefined)
             return null;

package/dist/audit/handlers/list.query.d.ts

@@ -18,6 +18,10 @@ export declare const listQuery: import("@cosmicdrift/kumiko-types/define-handler
     }>>;
     from: z.ZodOptional<z.ZodISODateTime>;
     to: z.ZodOptional<z.ZodISODateTime>;
+    scope: z.ZodOptional<z.ZodEnum<{
+        system: "system";
+        tenant: "tenant";
+    }>>;
 }, z.core.$strip>, {
     rows: {
         id: string;

package/dist/audit/handlers/list.query.js

@@ -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
@@ -16,6 +18,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;
 function buildDateRange(from, to) {
     if (!from && !to)
@@ -52,7 +56,7 @@ function buildAuditWhere(tenantId, p) {
 }
 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.",
+    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. 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(),
@@ -67,6 +71,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`",
@@ -75,7 +80,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(ctx.db, eventsTable, where, {
             orderBy: {
                 col: query.payload.sort === "type" ? "type" : "createdAt",

package/dist/audit/handlers/resolve-audit-tenant.d.ts

@@ -0,0 +1,7 @@
+import { type SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import { type AuditScope } from "../constants.js";
+export type AuditScopeFilter = {
+    readonly tenantId: string;
+    readonly aggregateType?: string;
+};
+export declare function resolveAuditScopeFilter(user: SessionUser, scope: AuditScope | undefined): AuditScopeFilter;

package/dist/audit/handlers/resolve-audit-tenant.js

@@ -0,0 +1,14 @@
+import { crossTenantOverrideDenied } 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 { AuditScopes } from "../constants.js";
+// The system tenant also holds personal streams of other features (session
+// revocations, exports, ...); only app-instance streams are released.
+export function resolveAuditScopeFilter(user, scope) {
+    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/dist/audit/i18n.js

@@ -6,6 +6,9 @@ export const AUDIT_I18N = {
     "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/dist/audit/run-escape-hatch-retention.js

@@ -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, } from "@cosmicdrift/kumiko-framework/compliance";
 import { parseTenantId, SYSTEM_TENANT_ID, } from "@cosmicdrift/kumiko-framework/engine";
 import { eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
@@ -38,10 +38,14 @@ function targetTenantOf(payload) {
     const parsed = escapeHatchUsedSchema.safeParse(payload);
     return parsed.success ? parseTenantId(parsed.data.targetTenantId) : null;
 }
-async function pruneByTenantProfiles(db) {
-    const rows = await selectMany(db, eventsTable, {
-        aggregateType: ESCAPE_HATCH_USE_AGGREGATE_TYPE,
+async function storingTenantIds(db) {
+    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) {
     const now = getTemporal().Now.instant();
     const cutoffByTenant = new Map();
     const cutoffOf = async (tenantId) => {
@@ -52,15 +56,24 @@ async function pruneByTenantProfiles(db) {
         cutoffByTenant.set(tenantId, cutoff);
         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 = [];
-    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(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);
+            }
         }
     }
     let deletedCount = 0;

package/dist/auth-email-password/constants.d.ts

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

package/dist/auth-email-password/constants.js

@@ -44,6 +44,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",
 };
 // Qualified query names. Anonymous-readable status so the (unauthenticated)

package/dist/auth-email-password/feature.js

@@ -17,6 +17,7 @@ import { createResetPasswordHandler } from "./handlers/reset-password.write.js";
 import { selfRegistrationStatusQuery } from "./handlers/self-registration-status.query.js";
 import { createSignupConfirmHandler } from "./handlers/signup-confirm.write.js";
 import { createSignupRequestHandler, } from "./handlers/signup-request.write.js";
+import { createSwitchTenantMfaGateHandler } from "./handlers/switch-tenant-mfa-gate.write.js";
 import { createVerifyEmailHandler } from "./handlers/verify-email.write.js";
 /**
  * Env-vars contract for the `auth-email-password` feature.
@@ -101,6 +102,9 @@ export function createAuthEmailPasswordFeature(opts = {}) {
             changePassword: r.writeHandler(changePasswordWrite),
             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));
@@ -119,7 +123,7 @@ export function createAuthEmailPasswordFeature(opts = {}) {
         };
         if (opts.signup) {
             r.writeHandler(createSignupRequestHandler(opts.signup));
-            r.writeHandler(createSignupConfirmHandler());
+            r.writeHandler(createSignupConfirmHandler({ mfaStatusChecker: opts.mfaStatusChecker }));
         }
         if (opts.invite) {
             r.writeHandler(createInviteCreateHandler(opts.invite));
@@ -132,7 +136,7 @@ export function createAuthEmailPasswordFeature(opts = {}) {
                 accountLockout: opts.accountLockout,
                 strictEmailVerification: strictVerification,
             }));
-            r.writeHandler(createInviteSignupCompleteHandler());
+            r.writeHandler(createInviteSignupCompleteHandler({ mfaStatusChecker: opts.mfaStatusChecker }));
         }
         if (opts.accountUnlock) {
             r.writeHandler(createRequestAccountUnlockHandler(opts.accountUnlock));

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

@@ -1,12 +1,16 @@
 import { type SessionUser, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
+import { type LoginHandlerOptions, type LoginResult } from "./login.write.js";
 export type InviteSignupCompleteData = {
     readonly kind: "auth-session";
     readonly session: SessionUser;
     readonly tenantId: TenantId;
     readonly role: string;
-};
-export declare function createInviteSignupCompleteHandler(): import("@cosmicdrift/kumiko-types/define-handler").WriteHandlerDefinition<"invite-signup-complete", z.ZodObject<{
+} | Exclude<LoginResult, {
+    readonly kind: "auth-session";
+}>;
+export type InviteSignupCompleteOptions = Pick<LoginHandlerOptions, "mfaStatusChecker">;
+export declare function createInviteSignupCompleteHandler(opts?: InviteSignupCompleteOptions): import("@cosmicdrift/kumiko-types/define-handler").WriteHandlerDefinition<"invite-signup-complete", z.ZodObject<{
     token: z.ZodString;
     password: z.ZodString;
 }, z.core.$strip>, InviteSignupCompleteData, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;

package/dist/auth-email-password/handlers/invite-signup-complete.write.js

@@ -37,13 +37,14 @@ import { burnInviteToken, deleteInviteToken, getInvitationIdForToken, unburnInvi
 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 } from "./login.write.js";
 const InviteSignupCompleteSchema = z.object({
     token: z.string().min(1),
     password: passwordSchema,
 });
 const invitationExecutor = createEventStoreExecutor(tenantInvitationsTable, tenantInvitationEntity, { entityName: "tenant-invitation" });
 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 = {}) {
     return defineWriteHandler({
         name: "invite-signup-complete",
         schema: InviteSignupCompleteSchema,
@@ -119,13 +120,22 @@ export function createInviteSignupCompleteHandler() {
                 }, createSystemUser(invitationTenantId), invitationTdb);
                 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 = {
                     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;
                 return {

package/dist/auth-email-password/handlers/signup-confirm.write.d.ts

@@ -1,5 +1,6 @@
 import { type SessionUser } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
+import { type LoginHandlerOptions, type LoginResult } from "./login.write.js";
 export type SignupConfirmData = {
     readonly kind: "auth-session";
     readonly session: SessionUser;
@@ -8,8 +9,11 @@ export type SignupConfirmData = {
         readonly entityType: string;
         readonly id: string;
     };
-};
-export declare function createSignupConfirmHandler(): import("@cosmicdrift/kumiko-types/define-handler").WriteHandlerDefinition<"signup-confirm", z.ZodObject<{
+} | Exclude<LoginResult, {
+    readonly kind: "auth-session";
+}>;
+export type SignupConfirmOptions = Pick<LoginHandlerOptions, "mfaStatusChecker">;
+export declare function createSignupConfirmHandler(opts?: SignupConfirmOptions): import("@cosmicdrift/kumiko-types/define-handler").WriteHandlerDefinition<"signup-confirm", z.ZodObject<{
     token: z.ZodString;
     password: z.ZodString;
 }, z.core.$strip>, SignupConfirmData, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;

package/dist/auth-email-password/handlers/signup-confirm.write.js

@@ -32,6 +32,7 @@ import { passwordSchema } from "../password-policy.js";
 // kumiko-lint-ignore cross-feature-import provisioning needs cross-feature seeding helpers
 import { INITIAL_SIGNUP_ROLES, provisionSignupAccount } from "../seeding.js";
 import { burnSignupToken, deleteSignupHandover, deleteSignupToken, getEmailForSignupToken, getSignupHandover, unburnSignupToken, } from "../signup-token-store.js";
+import { gateEnforceMfa } from "./login.write.js";
 const SignupConfirmSchema = z.object({
     token: z.string().min(8),
     password: passwordSchema,
@@ -70,7 +71,7 @@ async function claimBoundHandover(ctx, session, binding) {
     });
     return undefined;
 }
-export function createSignupConfirmHandler() {
+export function createSignupConfirmHandler(opts = {}) {
     return defineWriteHandler({
         name: "signup-confirm",
         schema: SignupConfirmSchema,
@@ -158,11 +159,17 @@ export function createSignupConfirmHandler() {
                 const handover = handoverBinding
                     ? 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/dist/auth-email-password/handlers/switch-tenant-mfa-gate.write.d.ts

@@ -0,0 +1,9 @@
+import * as z from "zod";
+import { gateEnforceMfa, type LoginHandlerOptions } from "./login.write.js";
+export type SwitchTenantMfaGateData = {
+    readonly kind: "mfa-gate-clear";
+} | NonNullable<Awaited<ReturnType<typeof gateEnforceMfa>>>;
+export declare function createSwitchTenantMfaGateHandler(opts: Pick<LoginHandlerOptions, "mfaStatusChecker">): import("@cosmicdrift/kumiko-types/define-handler").WriteHandlerDefinition<"switch-tenant-mfa-gate", z.ZodObject<{
+    userId: z.ZodString;
+    tenantId: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+}, z.core.$strip>, SwitchTenantMfaGateData, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;

package/dist/auth-email-password/handlers/switch-tenant-mfa-gate.write.js

@@ -0,0 +1,39 @@
+import { buildSessionRoles, createSystemUser, defineWriteHandler, SYSTEM_ROLE, } 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 } from "./login.write.js";
+const SwitchTenantMfaGateSchema = z.object({
+    userId: z.string().min(1),
+    tenantId: z
+        .string()
+        .min(1)
+        .transform((id) => id),
+});
+// 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) {
+    return defineWriteHandler({
+        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/dist/auth-email-password/handlers/token-request-handler.js

@@ -13,6 +13,7 @@
 // spec rather than duplicated across two near-identical handler bodies.
 import { createSystemUser, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { isValidIanaTimeZone } from "@cosmicdrift/kumiko-framework/time";
 import * as z from "zod";
 import { UserQueries } from "../../user/index.js";
 import { parseAuthUserRow } from "../auth-user-row.js";
@@ -20,6 +21,11 @@ import { dispatchMagicLinkMail, resolveHandlerMailLocale } from "../magic-link-m
 const RequestTokenSchema = z.object({
     email: z.email(),
 });
+// 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, fallbackTimeZone) {
+    return user.timezone && isValidIanaTimeZone(user.timezone) ? user.timezone : fallbackTimeZone;
+}
 export function createTokenRequestHandler(spec, opts) {
     const ttl = opts.tokenTtlMinutes ?? spec.defaultTtlMinutes;
     return defineWriteHandler({
@@ -69,7 +75,7 @@ export function createTokenRequestHandler(spec, opts) {
                 token,
                 expiresAt: expiresAt.toString(),
                 issuedAt,
-                timeZone: ctx.tz.user,
+                timeZone: recipientTimeZone(user, ctx.tz.user),
                 ...(opts.appName !== undefined && { appName: opts.appName }),
                 locale,
             });

package/dist/auth-email-password/i18n.js

@@ -99,6 +99,7 @@ export const defaultTranslations = {
         "auth.signupComplete.submit": "Activate account",
         "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/dist/auth-email-password/web/auth-client.d.ts

@@ -112,9 +112,14 @@ export type SignupConfirmSuccess = {
     };
     readonly landingPath?: string;
 };
+export type SignupConfirmResult = ({
+    readonly kind: "signed-in";
+} & SignupConfirmSuccess) | {
+    readonly kind: "mfa-pending";
+};
 export declare function confirmSignup(token: string, password: string): Promise<{
     ok: true;
-    data: SignupConfirmSuccess;
+    data: SignupConfirmResult;
 } | {
     ok: false;
     error: AuthTokenFailure;

package/dist/auth-email-password/web/auth-client.js

@@ -229,8 +229,12 @@ export async function confirmSignup(token, password) {
         body: JSON.stringify({ token, password }),
     });
     if (res.ok) {
-        const body = (await res.json()); // @cast-boundary engine-payload
-        return { ok: true, data: body };
+        // @cast-boundary engine-payload
+        const body = (await res.json());
+        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) };
 }

package/dist/auth-email-password/web/signup-complete-screen.js

@@ -31,6 +31,7 @@ export function SignupCompleteScreen({ title, token: tokenProp, loggedInHref = "
     const [submitting, setSubmitting] = useState(false);
     const [error, setError] = useState(null);
     const [continueHref, setContinueHref] = useState(null);
+    const [mfaPending, setMfaPending] = useState(false);
     const doSubmit = async () => {
         setError(null);
         const issue = passwordPairIssue(password, confirmPassword);
@@ -46,6 +47,11 @@ export function SignupCompleteScreen({ title, token: tokenProp, loggedInHref = "
         const res = await confirmSignup(token, password);
         setSubmitting(false);
         if (res.ok) {
+            if (res.data.kind === "mfa-pending") {
+                setMfaPending(true);
+                setContinueHref(loginHref);
+                return;
+            }
             // Cookies are already set (auto-login). Show a confirmation with an
             // explicit continue button instead of navigating away silently —
             // the user otherwise gets no signal that activation worked.
@@ -80,7 +86,9 @@ export function SignupCompleteScreen({ title, token: tokenProp, loggedInHref = "
         return (_jsxs(AuthCard, { title: effectiveTitle, children: [_jsx("p", { className: "text-sm text-muted-foreground", children: t("auth.signupComplete.missingToken") }), _jsx(Link, { href: loginHref, variant: "muted", children: t("auth.signup.haveAccount") })] }));
     }
     if (continueHref !== null) {
-        return (_jsxs(AuthCard, { title: effectiveTitle, children: [_jsx("p", { className: "text-sm text-muted-foreground", role: "status", children: t("auth.signupComplete.activated") }), _jsx(Link, { href: continueHref, variant: "button", children: t("auth.signupComplete.continue") })] }));
+        return (_jsxs(AuthCard, { title: effectiveTitle, children: [_jsx("p", { className: "text-sm text-muted-foreground", role: "status", children: t(mfaPending
+                        ? "auth.signupComplete.activatedMfaPending"
+                        : "auth.signupComplete.activated") }), _jsx(Link, { href: continueHref, variant: "button", children: t("auth.signupComplete.continue") })] }));
     }
     return (_jsxs(AuthCard, { title: effectiveTitle, children: [_jsx("p", { className: "text-sm text-muted-foreground", children: t("auth.signupComplete.intro") }), _jsxs(Form, { onSubmit: onSubmit, children: [_jsx(Field, { id: "signup-password", label: t("auth.signupComplete.password"), required: true, children: _jsx(Input, { kind: "password", id: "signup-password", name: "signup-password", value: password, onChange: setPassword, disabled: submitting, required: true, autoComplete: "new-password" }) }), _jsx(Field, { id: "signup-confirm-password", label: t("auth.signupComplete.confirmPassword"), required: true, children: _jsx(Input, { kind: "password", id: "signup-confirm-password", name: "signup-confirm-password", value: confirmPassword, onChange: setConfirmPassword, disabled: submitting, required: true, autoComplete: "new-password" }) }), error !== null && _jsx(Banner, { variant: "error", children: error }), _jsx(Button, { type: "submit", loading: submitting, disabled: submitting, children: submitting ? t("auth.signupComplete.submitting") : t("auth.signupComplete.submit") })] })] }));
 }