@cosmicdrift/kumiko-samples 0.344.0 → 0.345.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.344.0",
+  "version": "0.345.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.345.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,10 @@
 [
+  {
+    "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/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) };
 }

package/packages/bundled-features/src/auth-email-password/web/signup-complete-screen.tsx

@@ -57,6 +57,7 @@ export function SignupCompleteScreen({
   const [submitting, setSubmitting] = useState(false);
   const [error, setError] = useState<string | null>(null);
   const [continueHref, setContinueHref] = useState<string | null>(null);
+  const [mfaPending, setMfaPending] = useState(false);
 
   const doSubmit = async (): Promise<void> => {
     setError(null);
@@ -73,6 +74,11 @@ export function SignupCompleteScreen({
     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.
@@ -124,7 +130,11 @@ export function SignupCompleteScreen({
     return (
       <AuthCard title={effectiveTitle}>
         <p className="text-sm text-muted-foreground" role="status">
-          {t("auth.signupComplete.activated")}
+          {t(
+            mfaPending
+              ? "auth.signupComplete.activatedMfaPending"
+              : "auth.signupComplete.activated",
+          )}
         </p>
         <Link href={continueHref} variant="button">
           {t("auth.signupComplete.continue")}

package/packages/bundled-features/src/step-dispatcher/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.345.0",
+    "type": "improvement",
+    "title": "Webhook sends carry an Idempotency-Key header that is stable across redeliveries",
+    "detail": "Webhook sends carry an Idempotency-Key header\nEvery `r.step.webhook.send` request now has `Idempotency-Key: <dispatch stream id>`. The value stays the same when the same dispatch request is delivered again, so receivers can deduplicate. An explicit `Idempotency-Key` in `headers` (any casing) takes precedence."
+  },
   {
     "version": "0.335.0",
     "type": "fix",

package/packages/bundled-features/src/step-dispatcher/feature.ts

@@ -193,7 +193,7 @@ function buildDispatchSpec(
 export function createStepDispatcherFeature(): FeatureDefinition {
   return defineFeature("step-dispatcher", (r) => {
     r.describe(
-      "Internal system feature that drains deferred Tier-2 side-effects (currently `webhook.send` and `mail.send`) after their originating transaction commits. Listens via `r.multiStreamProjection` on the `kumiko:system:step.dispatch-requested` system event, performs the actual HTTP or mail delivery, then appends `kumiko:system:step.dispatched` or `kumiko:system:step.dispatch-failed` back onto the same stream so the outcome is recorded in the event log without a separate status table. Mount this feature explicitly via `createStepDispatcherFeature()` in your app's feature list alongside any features that use `r.step.webhook.send` or `r.step.mail.send`. Requires the `secrets` feature (`createSecretsFeature()`) to be mounted — `webhook.send` auth resolves per-tenant through it, under `step-dispatcher:webhook-auth.<name>`.",
+      "Internal system feature that drains deferred Tier-2 side-effects (currently `webhook.send` and `mail.send`) after their originating transaction commits. Listens via `r.multiStreamProjection` on the `kumiko:system:step.dispatch-requested` system event, performs the actual HTTP or mail delivery, then appends `kumiko:system:step.dispatched` or `kumiko:system:step.dispatch-failed` back onto the same stream so the outcome is recorded in the event log without a separate status table. Mount this feature explicitly via `createStepDispatcherFeature()` in your app's feature list alongside any features that use `r.step.webhook.send` or `r.step.mail.send`. Requires the `secrets` feature (`createSecretsFeature()`) to be mounted — `webhook.send` auth resolves per-tenant through it, under `step-dispatcher:webhook-auth.<name>`. Every `webhook.send` request carries `Idempotency-Key: <dispatch stream id>`, stable across redeliveries of the same dispatch request; an explicit `Idempotency-Key` in `headers` takes precedence.",
     );
     r.secretNamespace("webhook-auth", WEBHOOK_AUTH_SECRET_NAMESPACE_OPTIONS);
     r.uiHints({
@@ -270,6 +270,7 @@ export function createStepDispatcherFeature(): FeatureDefinition {
                   tenantId: event.tenantId,
                   userId: event.metadata.userId || SYSTEM_USER_ID,
                   secrets: ctx.secrets,
+                  idempotencyKey: event.aggregateId,
                 })
               : await performMailDispatch(dispatchSpec.spec);
           if (result.ok) {

package/packages/bundled-features/src/step-dispatcher/webhook-runner.ts

@@ -114,6 +114,7 @@ export type WebhookDispatchDeps = {
   readonly tenantId: TenantId;
   readonly userId: string;
   readonly secrets: SecretsContext | undefined;
+  readonly idempotencyKey: string;
 };
 
 // Never includes the secret name or value — spec.auth.secret is a
@@ -121,11 +122,20 @@ export type WebhookDispatchDeps = {
 // dispatch-failed event, so it stays generic.
 const WEBHOOK_AUTH_SECRET_UNAVAILABLE_ERROR = "webhook auth secret is not available";
 
+export const WEBHOOK_IDEMPOTENCY_KEY_HEADER = "idempotency-key";
+
+function hasIdempotencyKeyHeader(headers: Readonly<Record<string, string>>): boolean {
+  return Object.keys(headers).some((name) => name.toLowerCase() === WEBHOOK_IDEMPOTENCY_KEY_HEADER);
+}
+
 async function buildWebhookHeaders(
   spec: WebhookSpec,
   deps: WebhookDispatchDeps,
 ): Promise<{ ok: true; headers: Record<string, string> } | { ok: false; error: string }> {
   const headers: Record<string, string> = { "content-type": "application/json", ...spec.headers };
+  if (!hasIdempotencyKeyHeader(headers)) {
+    headers[WEBHOOK_IDEMPOTENCY_KEY_HEADER] = deps.idempotencyKey;
+  }
   if (!spec.auth) return { ok: true, headers };
   if (!deps.secrets) return { ok: false, error: WEBHOOK_AUTH_SECRET_UNAVAILABLE_ERROR };
   // A throwing get (corrupt envelope, rotated key, KMS error) must become a

package/samples/apps/use-all-bundled/feature-manifest.json

@@ -127,6 +127,7 @@
         "auth-email-password:write:reset-password",
         "auth-email-password:write:signup-confirm",
         "auth-email-password:write:signup-request",
+        "auth-email-password:write:switch-tenant-mfa-gate",
         "auth-email-password:write:system-invite-create",
         "auth-email-password:write:verify-email"
       ],
@@ -2301,7 +2302,7 @@
     },
     {
       "name": "step-dispatcher",
-      "description": "Internal system feature that drains deferred Tier-2 side-effects (currently `webhook.send` and `mail.send`) after their originating transaction commits. Listens via `r.multiStreamProjection` on the `kumiko:system:step.dispatch-requested` system event, performs the actual HTTP or mail delivery, then appends `kumiko:system:step.dispatched` or `kumiko:system:step.dispatch-failed` back onto the same stream so the outcome is recorded in the event log without a separate status table. Mount this feature explicitly via `createStepDispatcherFeature()` in your app's feature list alongside any features that use `r.step.webhook.send` or `r.step.mail.send`. Requires the `secrets` feature (`createSecretsFeature()`) to be mounted — `webhook.send` auth resolves per-tenant through it, under `step-dispatcher:webhook-auth.<name>`.",
+      "description": "Internal system feature that drains deferred Tier-2 side-effects (currently `webhook.send` and `mail.send`) after their originating transaction commits. Listens via `r.multiStreamProjection` on the `kumiko:system:step.dispatch-requested` system event, performs the actual HTTP or mail delivery, then appends `kumiko:system:step.dispatched` or `kumiko:system:step.dispatch-failed` back onto the same stream so the outcome is recorded in the event log without a separate status table. Mount this feature explicitly via `createStepDispatcherFeature()` in your app's feature list alongside any features that use `r.step.webhook.send` or `r.step.mail.send`. Requires the `secrets` feature (`createSecretsFeature()`) to be mounted — `webhook.send` auth resolves per-tenant through it, under `step-dispatcher:webhook-auth.<name>`. Every `webhook.send` request carries `Idempotency-Key: <dispatch stream id>`, stable across redeliveries of the same dispatch request; an explicit `Idempotency-Key` in `headers` takes precedence.",
       "toggleableDefault": null,
       "requires": [
         "secrets"

package/samples/recipes/i18n/README.md

@@ -13,7 +13,7 @@ A translation value can be a CLDR plural-forms object instead of a plain
 string. `other` is required; the rest (`zero`/`one`/`two`/`few`/`many`) only
 exist where the locale's grammar needs them:
 
-```ts
+```ts illustration
 "greeting.unread_count": {
   de: { one: "{count} ungelesene Nachricht", other: "{count} ungelesene Nachrichten" },
   en: { one: "{count} unread message", other: "{count} unread messages" },

package/samples/recipes/rate-limiting/README.md

@@ -12,7 +12,7 @@ End-to-end rate limiting: L1 global-IP + L2 auth + L3 handler opt-in.
 A public write handler that mails an address typed by the caller is also limited per
 address, so rotating IPs does not help against mail flooding. Declare it next to `rateLimit`:
 
-```ts
+```ts illustration
 r.writeHandler({
   // ...
   access: { roles: ["anonymous"] },

package/samples/recipes/webhook-step/README.md

@@ -16,7 +16,7 @@ never a process-wide env var. The `secrets` feature must be mounted
 (`createSecretsFeature()` + a `MasterKeyProvider`) alongside
 `step-dispatcher`. Set the secret per tenant before dispatching:
 
-```ts
+```ts illustration
 await stack.http.writeOk(
   "secrets:write:set",
   { key: "step-dispatcher:webhook-auth.incident-hook", value: "<token>" },
@@ -33,6 +33,13 @@ Never combine `auth.secret` with a caller-controlled `url`: the caller would
 receive the secret as the `Authorization` header. `incident:open-authenticated`
 therefore posts to a fixed URL.
 
+## Idempotency-Key
+
+Every webhook request carries `Idempotency-Key: <dispatch stream id>`. The
+value is the same when the same dispatch request is delivered again, so a
+receiver can deduplicate redelivered calls. An `Idempotency-Key` set explicitly in
+`headers` (any casing) wins.
+
 ## Source
 
 Feature entry point: `src/feature.ts`.