@cosmicdrift/kumiko-samples 0.388.0 → 0.390.0

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

@@ -226,12 +226,13 @@ async function parseTokenFailure(res: Response): Promise<AuthTokenFailure> {
 // found. 429 → typed rate-limit failure. 5xx → unknown-error.
 export async function requestPasswordReset(
   email: string,
+  returnTo?: string,
 ): Promise<{ ok: true } | { ok: false; error: AuthTokenFailure }> {
   const res = await fetch("/api/auth/request-password-reset", {
     method: "POST",
     credentials: "same-origin",
     headers: { "Content-Type": "application/json", ...csrfHeader() },
-    body: JSON.stringify({ email }),
+    body: JSON.stringify({ email, ...(returnTo !== undefined && { returnTo }) }),
   });
   if (res.ok) return { ok: true };
   return { ok: false, error: await parseTokenFailure(res) };
@@ -332,12 +333,17 @@ export async function requestSignup(
   // travels any further than this request — never in the URL, the mail,
   // or the confirm response.
   handover?: { readonly entityType: string; readonly token: string },
+  returnTo?: string,
 ): Promise<{ ok: true } | { ok: false; error: AuthTokenFailure }> {
   const res = await fetch("/api/auth/signup-request", {
     method: "POST",
     credentials: "same-origin",
     headers: { "Content-Type": "application/json", ...csrfHeader() },
-    body: JSON.stringify({ email, ...(handover !== undefined && { handover }) }),
+    body: JSON.stringify({
+      email,
+      ...(handover !== undefined && { handover }),
+      ...(returnTo !== undefined && { returnTo }),
+    }),
   });
   if (res.ok) return { ok: true };
   return { ok: false, error: await parseTokenFailure(res) };

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

@@ -2,35 +2,37 @@
 // string, so anything read back from it is untrusted: only same-origin
 // root-relative paths pass (no "//host", no "/\host", no scheme).
 
-export const NEXT_QUERY_PARAM = "next";
+import { isSafeReturnPath, RETURN_TO_QUERY_PARAM, readReturnToFromSearch } from "./return-path.ts";
 
-function hasControlOrWhitespace(candidate: string): boolean {
-  for (let i = 0; i < candidate.length; i++) {
-    const code = candidate.charCodeAt(i);
-    if (code <= 0x20 || code === 0x7f) return true;
-  }
-  return false;
-}
+export const NEXT_QUERY_PARAM = "next";
 
-// The URL parse is a backstop: browsers strip tabs/newlines, so "/\t/evil.com"
-// would otherwise normalize to "//evil.com" past the leading-slash check.
-export function isSafeNextPath(candidate: unknown): candidate is string {
-  if (typeof candidate !== "string" || !candidate.startsWith("/")) return false;
-  if (candidate[1] === "/" || candidate.includes("\\")) return false;
-  if (hasControlOrWhitespace(candidate)) return false;
-  try {
-    const parsed = new URL(candidate, "https://next.invalid");
-    return parsed.origin === "https://next.invalid" && !parsed.pathname.startsWith("//");
-  } catch {
-    return false;
-  }
-}
+export const isSafeNextPath = isSafeReturnPath;
 
 export function readNextFromSearch(search: string): string | null {
   const candidate = new URLSearchParams(search).get(NEXT_QUERY_PARAM);
   return isSafeNextPath(candidate) ? candidate : null;
 }
 
+// The returnTo a mail link or sibling auth page carried in this page's own URL; null on native, where there is no window.
+export function readReturnToFromWindow(): string | null {
+  return typeof window === "undefined" ? null : readReturnToFromSearch(window.location.search);
+}
+
+// Adds returnTo to an href of a sibling auth page; a missing value leaves the href untouched.
+export function appendReturnTo(href: string, returnTo: string | null): string {
+  if (returnTo === null) return href;
+  const hashAt = href.indexOf("#");
+  const base = hashAt === -1 ? href : href.slice(0, hashAt);
+  const hash = hashAt === -1 ? "" : href.slice(hashAt);
+  const separator = base.includes("?") ? "&" : "?";
+  return `${base}${separator}${RETURN_TO_QUERY_PARAM}=${encodeURIComponent(returnTo)}${hash}`;
+}
+
+// The safe `next` of this page's URL; null on native, where there is no window.
+export function readNextFromWindow(): string | null {
+  return typeof window === "undefined" ? null : readNextFromSearch(window.location.search);
+}
+
 // loginUrl/postLogoutUrl come from app code (trusted), but a typo like
 // "javascript:" must fail at startup instead of becoming a navigation target.
 export function assertNavigableUrl(url: string, optionName: string): void {

package/packages/bundled-features/src/auth-email-password/web/default-auth-pages-gate.tsx

@@ -1,3 +1,4 @@
+import { stripBasePath, useBasePath } from "@cosmicdrift/kumiko-renderer";
 import type { ReactNode } from "react";
 import { DEFAULT_AUTH_PATHS, DEFAULT_FORGOT_PASSWORD_PATH } from "./auth-paths.ts";
 import { ConfirmAccountUnlockScreen } from "./confirm-account-unlock-screen.tsx";
@@ -9,8 +10,9 @@ function hasToken(search: string): boolean {
   return (new URLSearchParams(search).get("token") ?? "") !== "";
 }
 
-function pickDefaultAuthPage(pathname: string, search: string): ReactNode {
-  const path = pathname.length > 1 ? pathname.replace(/\/+$/, "") : pathname;
+function pickDefaultAuthPage(pathname: string, search: string, basePath: string): ReactNode {
+  const trimmed = pathname.length > 1 ? pathname.replace(/\/+$/, "") : pathname;
+  const path = stripBasePath(trimmed, basePath);
   switch (path) {
     case DEFAULT_FORGOT_PASSWORD_PATH:
       return <ForgotPasswordScreen />;
@@ -27,5 +29,6 @@ function pickDefaultAuthPage(pathname: string, search: string): ReactNode {
 // (outer) still win on the same path. The pages are public: no session needed.
 export function DefaultAuthPagesGate({ children }: { readonly children: ReactNode }): ReactNode {
   const { pathname, search } = window.location;
-  return pickDefaultAuthPage(pathname, search) ?? <>{children}</>;
+  const basePath = useBasePath();
+  return pickDefaultAuthPage(pathname, search, basePath) ?? <>{children}</>;
 }

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

@@ -12,6 +12,8 @@ import { usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
 import { type FormEvent, type ReactNode, useState } from "react";
 import { requestPasswordReset } from "./auth-client.ts";
 import { AuthCard } from "./auth-form-primitives.tsx";
+import { readReturnToFromWindow } from "./auth-redirect.ts";
+import { isSafeReturnPath } from "./return-path.ts";
 
 export type ForgotPasswordScreenProps = {
   readonly title?: string;
@@ -19,12 +21,20 @@ export type ForgotPasswordScreenProps = {
   /** href for the "Back to login" link in the success and form states. App-
    * specific — defaults to "/login". */
   readonly loginHref?: string;
+  /** Page the reset mail should lead back to after the new password is set; defaults to the
+   *  `returnTo` query parameter of this page. Unsafe values are dropped. */
+  readonly returnTo?: string;
 };
 
+function resolveReturnTo(prop: string | undefined): string | undefined {
+  return (isSafeReturnPath(prop) ? prop : readReturnToFromWindow()) ?? undefined;
+}
+
 export function ForgotPasswordScreen({
   title,
   subtitle,
   loginHref = "/login",
+  returnTo,
 }: ForgotPasswordScreenProps): ReactNode {
   const t = useTranslation();
   const { Form, Field, Input, Button, Banner, Link } = usePrimitives();
@@ -38,7 +48,7 @@ export function ForgotPasswordScreen({
     setSubmitting(true);
     setError(null);
     try {
-      const res = await requestPasswordReset(email);
+      const res = await requestPasswordReset(email, resolveReturnTo(returnTo));
       if (res.ok) {
         setDone(true);
       } else if (res.error.reason === "rate_limited") {

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

@@ -63,6 +63,11 @@ export type { RequestAccountUnlockScreenProps } from "./request-account-unlock-s
 export { RequestAccountUnlockScreen } from "./request-account-unlock-screen.tsx";
 export type { ResetPasswordScreenProps } from "./reset-password-screen.tsx";
 export { ResetPasswordScreen } from "./reset-password-screen.tsx";
+export {
+  isSafeReturnPath,
+  RETURN_TO_QUERY_PARAM,
+  readReturnToFromSearch,
+} from "./return-path.ts";
 export type {
   SessionApi,
   SessionBootstrapFailure,

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

@@ -2,6 +2,8 @@
 // reason code needs a bundle entry plus a line in that mapping.
 
 import {
+  prependBasePath,
+  useBasePath,
   useOptionalDispatcher,
   usePrimitives,
   useQuery,
@@ -15,7 +17,11 @@ import {
 } from "./auth-client.ts";
 import { AuthCard } from "./auth-form-primitives.tsx";
 import { DEFAULT_AUTH_PATHS, DEFAULT_FORGOT_PASSWORD_PATH } from "./auth-paths.ts";
-import { followNextOrLandingAfterLogin } from "./auth-redirect.ts";
+import {
+  appendReturnTo,
+  followNextOrLandingAfterLogin,
+  readNextFromWindow,
+} from "./auth-redirect.ts";
 import { AuthQueries } from "./constants.ts";
 import { useSession } from "./session.tsx";
 
@@ -128,16 +134,21 @@ function LoginScreenBody({
   // Hides the resend button once the email input changes; otherwise resend
   // would silently go to the edited, possibly mistyped address.
   const [failedLoginEmail, setFailedLoginEmail] = useState<string | null>(null);
+  const basePath = useBasePath();
+  // The page the user was sent away from rides along so the reset or signup mail leads back to it.
+  const returnTo = readNextFromWindow();
   const effectiveForgotHref =
     forgotPasswordHref === undefined
       ? loginOptions?.passwordReset === true
-        ? DEFAULT_FORGOT_PASSWORD_PATH
+        ? appendReturnTo(prependBasePath(DEFAULT_FORGOT_PASSWORD_PATH, basePath), returnTo)
         : null
-      : forgotPasswordHref;
+      : forgotPasswordHref === null
+        ? null
+        : appendReturnTo(forgotPasswordHref, returnTo);
   const effectiveUnlockHref =
     unlockAccountHref === undefined
       ? loginOptions?.accountUnlock === true
-        ? DEFAULT_AUTH_PATHS.unlockAccount
+        ? prependBasePath(DEFAULT_AUTH_PATHS.unlockAccount, basePath)
         : null
       : unlockAccountHref;
 
@@ -281,7 +292,7 @@ function LoginScreenBody({
         </Link>
       )}
       {signupHref !== undefined && (
-        <Link href={signupHref} variant="muted" className="self-center">
+        <Link href={appendReturnTo(signupHref, returnTo)} variant="muted" className="self-center">
           {t("auth.signup.title")}
         </Link>
       )}

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

@@ -13,6 +13,7 @@ import { type FormEvent, type ReactNode, useState } from "react";
 import { resetPassword } from "./auth-client.ts";
 import { passwordPairIssue } from "./auth-form-logic.ts";
 import { AuthCard, useUrlToken } from "./auth-form-primitives.tsx";
+import { buildLoginRedirectUrl, readReturnToFromWindow } from "./auth-redirect.ts";
 
 export type ResetPasswordScreenProps = {
   readonly title?: string;
@@ -37,6 +38,7 @@ export function ResetPasswordScreen({
   const [submitting, setSubmitting] = useState(false);
   const [done, setDone] = useState(false);
   const [error, setError] = useState<string | null>(null);
+  const [afterResetHref, setAfterResetHref] = useState(loginHref);
 
   const doSubmit = async (): Promise<void> => {
     setError(null);
@@ -53,6 +55,10 @@ export function ResetPasswordScreen({
     const res = await resetPassword(token, newPassword);
     setSubmitting(false);
     if (res.ok) {
+      const returnTo = readReturnToFromWindow();
+      if (returnTo !== null) {
+        setAfterResetHref(buildLoginRedirectUrl(loginHref, returnTo, window.location.origin));
+      }
       setDone(true);
       return;
     }
@@ -97,7 +103,7 @@ export function ResetPasswordScreen({
             <p className="font-medium text-foreground">{t("auth.resetPassword.successTitle")}</p>
             <p className="mt-1">{t("auth.resetPassword.successBody")}</p>
           </Banner>
-          <Link href={loginHref} variant="button">
+          <Link href={afterResetHref} variant="button">
             {t("auth.resetPassword.goToLogin")}
           </Link>
         </>

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

@@ -0,0 +1,35 @@
+// Shared by the server (mail link) and the web pages (landing page), so it is plain string logic:
+// no DOM, no window, no `new URL` (React Native's URL getters throw).
+
+export const RETURN_TO_QUERY_PARAM = "returnTo";
+export const MAX_RETURN_PATH_LENGTH = 2048;
+
+const DOT_SEGMENTS = new Set([".", "..", ".%2e", "%2e.", "%2e%2e", "%2e"]);
+
+function hasForbiddenCharacter(candidate: string): boolean {
+  for (let i = 0; i < candidate.length; i++) {
+    const code = candidate.charCodeAt(i);
+    if (code <= 0x20 || code === 0x7f || (code >= 0x80 && code <= 0x9f)) return true;
+    if (code === 0x5c) return true;
+  }
+  return false;
+}
+
+// A dot segment is resolved by URL normalization, so "/.//evil" would become "//evil".
+function hasDotSegment(candidate: string): boolean {
+  const pathEnd = candidate.search(/[?#]/);
+  const path = pathEnd === -1 ? candidate : candidate.slice(0, pathEnd);
+  return path.split("/").some((segment) => DOT_SEGMENTS.has(segment.toLowerCase()));
+}
+
+export function isSafeReturnPath(candidate: unknown): candidate is string {
+  if (typeof candidate !== "string") return false;
+  if (candidate.length < 1 || candidate.length > MAX_RETURN_PATH_LENGTH) return false;
+  if (!candidate.startsWith("/") || candidate[1] === "/") return false;
+  return !hasForbiddenCharacter(candidate) && !hasDotSegment(candidate);
+}
+
+export function readReturnToFromSearch(search: string): string | null {
+  const candidate = new URLSearchParams(search).get(RETURN_TO_QUERY_PARAM);
+  return isSafeReturnPath(candidate) ? candidate : null;
+}

package/packages/bundled-features/src/auth-email-password/web/session.tsx

@@ -14,6 +14,7 @@ import {
   useSessionEndedSignal,
 } from "@cosmicdrift/kumiko-renderer";
 import { readCsrfToken } from "@cosmicdrift/kumiko-renderer/live";
+import { clearRememberedListState } from "@cosmicdrift/kumiko-renderer/web";
 import {
   createContext,
   type ReactNode,
@@ -216,6 +217,8 @@ export function SessionProvider({
 
   const logout = useCallback<SessionApi["logout"]>(async () => {
     await logoutApi();
+    // The reload below would hide the identity change from the list-state boot.
+    clearRememberedListState();
     if (postLogoutUrl !== undefined && typeof window !== "undefined") {
       // State stays untouched: flipping to unauthenticated would let an AuthGate
       // with loginUrl race this navigation to its own redirect.
@@ -251,6 +254,7 @@ export function SessionProvider({
   const userEmail = profile?.email;
   const userDisplayName = profile?.displayName;
   const userTimeZone = profile?.effectiveTimeZone;
+  const activeTenantId = state.activeTenantId ?? undefined;
   const currentUser = useMemo<CurrentUser | undefined>(
     () =>
       userId === undefined || userEmail === undefined || userDisplayName === undefined
@@ -260,8 +264,9 @@ export function SessionProvider({
             email: userEmail,
             displayName: userDisplayName,
             ...(userTimeZone !== undefined && { timeZone: userTimeZone }),
+            ...(activeTenantId !== undefined && { tenantId: activeTenantId }),
           },
-    [userId, userEmail, userDisplayName, userTimeZone],
+    [userId, userEmail, userDisplayName, userTimeZone, activeTenantId],
   );
   return (
     <SessionContext.Provider value={api}>

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

@@ -21,7 +21,7 @@ import { type FormEvent, type ReactNode, useState } from "react";
 import { confirmSignup, type SignupConfirmSuccess } from "./auth-client.ts";
 import { passwordPairIssue, resolvePostAuthHref } from "./auth-form-logic.ts";
 import { AuthCard, useUrlToken } from "./auth-form-primitives.tsx";
-import { buildLoginRedirectUrl } from "./auth-redirect.ts";
+import { buildLoginRedirectUrl, readReturnToFromWindow } from "./auth-redirect.ts";
 
 export type SignupCompleteScreenProps = {
   readonly title?: string;
@@ -74,15 +74,23 @@ export function SignupCompleteScreen({
     const res = await confirmSignup(token, password);
     setSubmitting(false);
     if (res.ok) {
+      // The page the signup started from beats the server's landing path.
+      const returnTo = readReturnToFromWindow();
       if (res.data.kind === "mfa-pending") {
         setMfaPending(true);
+        const next = returnTo ?? res.data.landingPath;
         setContinueHref(
-          res.data.landingPath === undefined
+          next === undefined
             ? loginHref
-            : buildLoginRedirectUrl(loginHref, res.data.landingPath, window.location.origin),
+            : buildLoginRedirectUrl(loginHref, next, window.location.origin),
         );
         return;
       }
+      // A claimed handover keeps its app-defined target.
+      if (returnTo !== null && res.data.handover === undefined) {
+        setContinueHref(returnTo);
+        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.

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

@@ -16,6 +16,8 @@ import { type FormEvent, type ReactNode, useState } from "react";
 import { requestSignup } from "./auth-client.ts";
 import { retryAfterMinutes } from "./auth-form-logic.ts";
 import { AuthCard } from "./auth-form-primitives.tsx";
+import { readReturnToFromWindow } from "./auth-redirect.ts";
+import { isSafeReturnPath } from "./return-path.ts";
 
 export type SignupScreenProps = {
   readonly title?: string;
@@ -23,12 +25,20 @@ export type SignupScreenProps = {
   /** href for the "Already have an account?" link. App-specific; defaults to
    *  "/login". */
   readonly loginHref?: string;
+  /** Page the activation mail should lead to after signup; defaults to the `returnTo` query
+   *  parameter of this page. Unsafe values are dropped. */
+  readonly returnTo?: string;
 };
 
+function resolveReturnTo(prop: string | undefined): string | undefined {
+  return (isSafeReturnPath(prop) ? prop : readReturnToFromWindow()) ?? undefined;
+}
+
 export function SignupScreen({
   title,
   subtitle,
   loginHref = "/login",
+  returnTo,
 }: SignupScreenProps): ReactNode {
   const t = useTranslation();
   const { Form, Field, Input, Button, Banner, Link } = usePrimitives();
@@ -41,7 +51,7 @@ export function SignupScreen({
     setSubmitting(true);
     setError(null);
     try {
-      const res = await requestSignup(email);
+      const res = await requestSignup(email, undefined, resolveReturnTo(returnTo));
       if (res.ok) {
         setDone(true);
       } else if (res.error.reason === "rate_limited") {
@@ -73,7 +83,7 @@ export function SignupScreen({
     setSubmitting(true);
     setError(null);
     try {
-      await requestSignup(email);
+      await requestSignup(email, undefined, resolveReturnTo(returnTo));
     } finally {
       setSubmitting(false);
     }

package/packages/bundled-features/src/auth-foundation/feature.ts

@@ -12,6 +12,7 @@
 
 import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
 import { defineFeature, type Registry } from "@cosmicdrift/kumiko-framework/engine";
+import { systemScopedRunner } from "@cosmicdrift/kumiko-framework/internal/row-level-security";
 import {
   validateSessionStoreMultiplicity,
   validateTenantExistenceMultiplicity,
@@ -90,6 +91,14 @@ export function createAuthFoundationFeature() {
   );
 }
 
+// Providers run before any tenant or session exists (token verify, host to tenant), so their reads are cross-tenant by nature.
+function systemScopedDeps<T extends AuthProviderBuildDeps>(deps: T): T {
+  return {
+    ...deps,
+    db: systemScopedRunner(deps.db, "auth lookups run before a tenant is established"),
+  };
+}
+
 /**
  * Tries every registered tokenVerifier provider's shape against `rawToken`
  * in registration order and calls the first match's verifier. Returns null
@@ -104,7 +113,7 @@ export async function resolveTokenVerifier(
   for (const usage of usages) {
     if (!isAuthProviderPlugin(usage.options)) continue;
     if (!tokenShapeMatches(usage.options.shape, rawToken)) continue;
-    const verify = await usage.options.build(deps);
+    const verify = await usage.options.build(systemScopedDeps(deps));
     return verify(rawToken);
   }
   return null;
@@ -125,7 +134,7 @@ export async function resolveSessionStore(
       "[auth-foundation] no sessionStore provider registered — did the boot validator run?",
     );
   }
-  return usage.options.build(deps);
+  return usage.options.build(systemScopedDeps(deps));
 }
 
 export type ResolvedTenantResolver = {
@@ -144,7 +153,7 @@ export async function resolveTenantResolver(
       "[auth-foundation] tenantResolver provider registered without a valid TenantResolverProvider",
     );
   }
-  const resolve = await usage.options.build(deps);
+  const resolve = await usage.options.build(systemScopedDeps(deps));
   return { resolve, trust: usage.options.trust };
 }
 
@@ -159,5 +168,5 @@ export async function resolveTenantExistence(
       "[auth-foundation] tenantExistence provider registered without a valid TenantExistenceProvider",
     );
   }
-  return usage.options.build(deps);
+  return usage.options.build(systemScopedDeps(deps));
 }

package/packages/bundled-features/src/auth-mfa/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "requiredPolicy \"systemAdmins\"",
+    "detail": "The new auth-mfa:config:required value systemAdmins (between optional and admins) forces MFA enrollment only for users whose merged global and tenant roles contain SystemAdmin. TenantAdmins and other roles log in as before; enrolled users are always challenged regardless of policy. No locale labels are involved, the option list has none."
+  },
   {
     "version": "0.388.0",
     "type": "improvement",

package/packages/bundled-features/src/auth-mfa/config.ts

@@ -2,19 +2,15 @@
 // they haven't opted in themselves? Default "optional" means the feature
 // is fully opt-in (existing tenants/users unaffected — no migration step).
 //
-// ponytail: "admins"/"all" HARD-BLOCK login for an unenrolled user (see
-// mfa-status-checker.ts's setupRequired branch) — there is no in-band way
-// for a blocked user to complete enrollment yet (that flow ships in PR3's
-// UI). Flipping this away from "optional" before PR3 locks out every
-// unenrolled matching user with no recovery path. Fine for a tenant that
-// enrolls its admins out-of-band first; a footgun otherwise.
+// Every non-optional policy blocks login for an unenrolled matching user until
+// they finish the pre-auth enrollment step (mfa-status-checker.ts setupRequired).
 import {
   access,
   type ConfigKeyHandle,
   createTenantConfig,
 } from "@cosmicdrift/kumiko-framework/engine";
 
-export const MFA_REQUIRED_POLICIES = ["optional", "admins", "all"] as const;
+export const MFA_REQUIRED_POLICIES = ["optional", "systemAdmins", "admins", "all"] as const;
 export type MfaRequiredPolicy = (typeof MFA_REQUIRED_POLICIES)[number];
 
 export const mfaRequiredConfigHandle: ConfigKeyHandle<"select"> = {

package/packages/bundled-features/src/auth-mfa/handlers/disable.write.ts

@@ -45,20 +45,20 @@ export function createDisableHandler(opts: DisableOptions) {
       if (!row) return mfaNotEnabled();
 
       // Fail closed, matching verify.write.ts/enable-confirm-preauth.write.ts
-      // without ctx.redis, verifyMfaFactor's TOTP-replay burn is skipped, and
+      // without ctx.services.redis, verifyMfaFactor's TOTP-replay burn is skipped, and
       // a code observed once (phishing proxy/shoulder-surfing) could be
       // replayed within the ±1-step window to disable MFA outright.
-      // "no ctx.redis means no one gets through MFA login" doesn't cover
+      // "no ctx.services.redis means no one gets through MFA login" doesn't cover
       // this route — it's session-authed, and JWTs issued before Redis was
       // unwired stay valid until they expire.
-      if (!ctx.redis) {
+      if (!ctx.services.redis) {
         return writeFailure(
           new InternalError({
-            message: "disable (mfa) requires ctx.redis for TOTP replay protection",
+            message: "disable (mfa) requires ctx.services.redis for TOTP replay protection",
           }),
         );
       }
-      const replay = { redis: ctx.redis, userId: event.user.id };
+      const replay = { redis: ctx.services.redis, userId: event.user.id };
       const verify = await verifyMfaFactor(row, event.payload.code, replay);
       if (!verify.ok) return invalidTotpCode();
 

package/packages/bundled-features/src/auth-mfa/handlers/enable-confirm-preauth.write.ts

@@ -73,8 +73,8 @@ export function createEnableConfirmPreauthHandler(opts: EnableConfirmPreauthOpti
     escapeHatch: {
       grants: ["systemIdentity", "unsafeRaw"],
       reason:
-        "Pre-auth MFA enrollment step has no session yet — re-checks status via ctx.queryAs(SYSTEM, " +
-        "user:findForAuth) and membership via ctx.resolveActiveMembership for the setup token's user. " +
+        "Pre-auth MFA enrollment step has no session yet — re-checks status via ctx.dispatch.queryAs(SYSTEM, " +
+        "user:findForAuth) and membership via ctx.auth.resolveActiveMembership for the setup token's user. " +
         "Also reads the MFA enrollment of the tenant named in the signed login/setup token, not the " +
         "guest dispatch tenant.",
     },
@@ -96,15 +96,15 @@ export function createEnableConfirmPreauthHandler(opts: EnableConfirmPreauthOpti
       // endpoint has NO gate before it (access: { roles: ["anonymous"] }, no JWT,
       // no prior challenge-token from a successful login) — its only secret
       // is a 6-digit TOTP code. Silently skipping the brute-force cap and
-      // single-use burn when ctx.redis is absent would let the setup token
+      // single-use burn when ctx.services.redis is absent would let the setup token
       // be guessed against unboundedly until its TTL expires. The route's
       // IP rate limiter is not a substitute: it's IP-scoped and resets on
       // every success.
-      if (!ctx.redis) {
+      if (!ctx.services.redis) {
         return writeFailure(
           new InternalError({
             message:
-              "enable-confirm-preauth requires ctx.redis for the brute-force cap and single-use burn",
+              "enable-confirm-preauth requires ctx.services.redis for the brute-force cap and single-use burn",
           }),
         );
       }
@@ -112,7 +112,7 @@ export function createEnableConfirmPreauthHandler(opts: EnableConfirmPreauthOpti
       // Same guessing surface as /auth/mfa/verify (a short TOTP code) and
       // the same per-userId cap — deliberately shared counter, see
       // mfa-verify-attempts.ts.
-      const state = await getMfaVerifyLockoutState(ctx.redis, userId);
+      const state = await getMfaVerifyLockoutState(ctx.services.redis, userId);
       if (state?.lockedUntil !== null && state?.lockedUntil !== undefined) {
         const now = Date.now();
         if (state.lockedUntil > now) {
@@ -123,18 +123,28 @@ export function createEnableConfirmPreauthHandler(opts: EnableConfirmPreauthOpti
 
       const secret = base32Decode(verify.payload.totpSecretBase32);
       if (verifyTotp(secret, event.payload.code) === false) {
-        await recordFailedMfaVerifyAttempt(ctx.redis, userId, maxAttempts, lockoutMinutes);
+        await recordFailedMfaVerifyAttempt(ctx.services.redis, userId, maxAttempts, lockoutMinutes);
         return invalidTotpCode();
       }
 
       // Burn the setup token on the first successful confirm — same
       // single-use guarantee as enable-confirm.write.ts.
-      const burnResult = await burnToken(ctx.redis, "mfa-setup", userId, verify.expiresAtMs);
+      const burnResult = await burnToken(
+        ctx.services.redis,
+        "mfa-setup",
+        userId,
+        verify.expiresAtMs,
+      );
       if (burnResult === "already-used") return invalidSetupToken();
 
       // "system" mode: no session exists yet, tenantId comes from the
       // verified token, mirroring enable-start-preauth.write.ts.
-      const scopedDb = createTenantDb({ db: ctx.db.unsafeRaw(), tenantId, mode: "system" });
+      const scopedDb = createTenantDb({
+        db: ctx.db.unsafeRaw(),
+        tenantId,
+        mode: "system",
+        reason: "pre-auth MFA setup has no session, the tenant comes from the verified setup token",
+      });
       const scopedUser: SessionUser = { id: userId, tenantId, roles: ["User"] };
       const existing = await findUserMfaRow(scopedDb, scopedUser);
       if (existing) return mfaAlreadyEnabled();
@@ -154,7 +164,7 @@ export function createEnableConfirmPreauthHandler(opts: EnableConfirmPreauthOpti
       // existing userId-unique-constraint backstop between the
       // `existing` check above and executor.create() below.
       const systemUser = createSystemUser(tenantId, ["SystemAdmin"]);
-      const userRow = (await ctx.queryAs(systemUser, UserQueries.findForAuth, {
+      const userRow = (await ctx.dispatch.queryAs(systemUser, UserQueries.findForAuth, {
         id: userId,
       })) as {
         roles?: string | null;
@@ -174,7 +184,7 @@ export function createEnableConfirmPreauthHandler(opts: EnableConfirmPreauthOpti
 
       const globalRoles = parseRoles(userRow?.roles ?? null);
 
-      const active = await ctx.resolveActiveMembership(userId, tenantId);
+      const active = await ctx.auth.resolveActiveMembership(userId, tenantId);
       if (active.kind === "rejected") return invalidSetupToken();
 
       const result = await executor.create(
@@ -190,8 +200,8 @@ export function createEnableConfirmPreauthHandler(opts: EnableConfirmPreauthOpti
       );
       if (!result.isSuccess) return result;
 
-      // ctx.redis is guaranteed by the fail-closed check above.
-      await clearMfaVerifyAttempts(ctx.redis, userId);
+      // ctx.services.redis is guaranteed by the fail-closed check above.
+      await clearMfaVerifyAttempts(ctx.services.redis, userId);
 
       // Re-derive the full session the way verify.write.ts does — the
       // setupToken only proves "password + new TOTP secret", not roles;
@@ -214,7 +224,7 @@ export function createEnableConfirmPreauthHandler(opts: EnableConfirmPreauthOpti
         ...sessionTimezoneField(userRow?.timezone),
         ...sessionLocaleField(userRow?.locale),
       };
-      const claims = await ctx.resolveAuthClaims(baseSession);
+      const claims = await ctx.auth.resolveClaims(baseSession);
       const session: SessionUser =
         Object.keys(claims).length > 0 ? { ...baseSession, claims } : baseSession;