@cosmicdrift/kumiko-samples 0.404.0 → 0.405.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.404.0",
+  "version": "0.405.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": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.404.0",
+  "version": "0.405.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -165,38 +165,38 @@
     "@cosmicdrift/kumiko-framework": "workspace:*",
     "@cosmicdrift/kumiko-renderer": "workspace:*",
     "@cosmicdrift/kumiko-types": "workspace:*",
-    "@mollie/api-client": "^4.5.0",
-    "@node-rs/argon2": "^2.0.2",
-    "@tiptap/core": "^3.31.3",
-    "@tiptap/extension-link": "^3.31.3",
-    "@tiptap/extension-list": "^3.31.3",
-    "@tiptap/extension-table": "^3.31.3",
-    "@tiptap/html": "^3.31.3",
-    "@tiptap/extensions": "^3.31.3",
-    "@tiptap/pm": "^3.31.3",
-    "@tiptap/react": "^3.31.3",
-    "@tiptap/starter-kit": "^3.31.3",
-    "@types/mailparser": "^3.4.6",
-    "@types/qrcode": "^1.5.5",
+    "@mollie/api-client": "^4.6.0",
+    "@node-rs/argon2": "^2.2.2",
+    "@tiptap/core": "^3.32.2",
+    "@tiptap/extension-link": "^3.32.2",
+    "@tiptap/extension-list": "^3.32.2",
+    "@tiptap/extension-table": "^3.32.2",
+    "@tiptap/html": "^3.32.2",
+    "@tiptap/extensions": "^3.32.2",
+    "@tiptap/pm": "^3.32.2",
+    "@tiptap/react": "^3.32.2",
+    "@tiptap/starter-kit": "^3.32.2",
+    "@types/mailparser": "^3.9.0",
+    "@types/qrcode": "^1.5.6",
     "clsx": "^2.1.1",
     "happy-dom": "^21.0.4",
     "hono": "^4.13.14",
     "imapflow": "^1.7.8",
-    "ioredis": "^5.10.1",
-    "jose": "^6.2.13",
-    "lucide-react": "^1.14.0",
-    "mailparser": "^3.12.4",
-    "marked": "^18.0.3",
-    "nodemailer": "^10.2.1",
+    "ioredis": "^5.11.1",
+    "jose": "^6.2.14",
+    "lucide-react": "^1.65.0",
+    "mailparser": "^3.14.1",
+    "marked": "^18.1.2",
+    "nodemailer": "^10.3.1",
     "pdf-lib": "^1.17.1",
     "qrcode": "^1.5.4",
-    "react": "^19.2.6",
-    "react-dom": "^19.2.6",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
     "sharp": "^0.35.5",
     "stripe": "^22.6.2",
-    "tailwind-merge": "^3.6.0",
+    "tailwind-merge": "^3.7.0",
     "temporal-polyfill": "^0.3.2",
-    "uuid": "^14.0.0",
+    "uuid": "^14.0.3",
     "zod": "^4.6.7"
   },
   "publishConfig": {
@@ -764,7 +764,7 @@
     "@cosmicdrift/kumiko-locale-it": "workspace:*",
     "@cosmicdrift/kumiko-renderer-mail-html": "workspace:*",
     "jsqr": "^1.4.0",
-    "unpdf": "^1.8.1",
+    "unpdf": "^1.9.1",
     "@cosmicdrift/kumiko-testing": "workspace:*"
   },
   "peerDependencies": {

package/packages/bundled-features/src/account-security/README.md

@@ -15,17 +15,19 @@ import { createSessionsFeature } from "@cosmicdrift/kumiko-bundled-features/sess
 
 const features = [
   createSessionsFeature(),
-  createAuthMfaFeature({ /* secrets, issuer */ }),
+  createAuthMfaFeature({
+    /* secrets, issuer */
+  }),
   createAccountSecurityFeature(),
 ];
 ```
 
 ## Options
 
-| Option | Default | Effect |
-| --- | --- | --- |
-| `access` | `openToAll` | Who may open the dashboard, e.g. `{ roles: ["Admin", "Editor"] }` |
-| `nav` | none | `{ order?, parent?, icon? }` (icon default `"user"`) adds a sidebar entry. Without it the screen is dormant and apps link it from the user menu |
+| Option   | Default     | Effect                                                                                                                                          |
+| -------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `access` | `openToAll` | Who may open the dashboard, e.g. `{ roles: ["Admin", "Editor"] }`                                                                               |
+| `nav`    | none        | `{ order?, parent?, icon? }` (icon default `"user"`) adds a sidebar entry. Without it the screen is dormant and apps link it from the user menu |
 
 The MFA panels switch on `auth-mfa:query:status` (`enabled`), exported as
 `accountSecurityMfaStatusVisibility`.

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

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.405.0",
+    "type": "improvement",
+    "title": "Login-path redirect hook and topbar without UserMenu",
+    "detail": "auth-email-password/web exports useRedirectAuthedFromLogin({ loginPath, target }), which replaces the URL with target while a signed-in user sits on the login path, also after Browser-Back, and isAuthedOnLoginPath. DefaultTopbarActions takes userMenu (default true) to hide the UserMenu and themeToggleTestId for the ThemeToggle button."
+  },
   {
     "version": "0.394.0",
     "type": "improvement",

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

@@ -1,17 +1,12 @@
 import {
-  type NotificationLocalizedTemplate,
   QnTypes,
   qn,
   type TemplateVariables,
   templateVariable,
 } from "@cosmicdrift/kumiko-framework/engine";
-import {
-  hasMailTranslationKey,
-  listMailLocales,
-  mailT,
-  resolveMailLocale,
-} from "@cosmicdrift/kumiko-framework/i18n";
+import { mailT } from "@cosmicdrift/kumiko-framework/i18n";
 import { escapeHtml, escapeHtmlAttr } from "@cosmicdrift/kumiko-renderer/headless";
+import { createMailLocaleTemplates } from "../shared/index.ts";
 import { AUTH_EMAIL_PASSWORD_FEATURE } from "./web/constants.ts";
 
 export const AUTH_MAIL_KINDS = {
@@ -62,18 +57,14 @@ const ALL_AUTH_MAIL_KINDS: readonly AuthMailKind[] = [
   "invite",
 ];
 
-const SUBJECT_KEY_BY_TYPE: ReadonlyMap<string, string> = new Map(
-  ALL_AUTH_MAIL_KINDS.map((kind) => [AuthMailNotificationTypes[kind], subjectKey(kind)]),
-);
-
-// A registered locale whose bundle lacks the subject key has no template (see
-// authMailLocalizedTemplate); the renderer has no locale fallback, so the
-// sender must pick a locale that has one or the mail would not go out at all.
-export function authMailTemplateLocale(notificationType: string, requestedLocale: string): string {
-  const locale = resolveMailLocale(requestedLocale);
-  const key = SUBJECT_KEY_BY_TYPE.get(notificationType);
-  return key !== undefined && hasMailTranslationKey(locale, key) ? locale : "en";
-}
+const mailLocaleTemplates = createMailLocaleTemplates({
+  kinds: ALL_AUTH_MAIL_KINDS,
+  notificationTypes: AuthMailNotificationTypes,
+  subjectKey,
+  bodyFor: (kind, locale) => mailBody(locale, AUTH_MAIL_KINDS[kind].translationKey),
+});
+
+export const authMailTemplateLocale = mailLocaleTemplates.templateLocale;
 
 export const AUTH_MAIL_VARIABLES: TemplateVariables = {
   appName: templateVariable.text({ required: true }),
@@ -128,31 +119,4 @@ function mailBody(locale: string, translationKey: string): string {
   ].join("");
 }
 
-// Evaluated when the registry is built, after every locale feature has
-// registered its mail translations. English always ships; another locale only
-// gets a template when it has its own subject, so a missing translation never
-// silently becomes an English mail in that locale's slot.
-export function authMailLocalizedTemplate(kind: AuthMailKind): () => NotificationLocalizedTemplate {
-  const { translationKey } = AUTH_MAIL_KINDS[kind];
-  const kindSubjectKey = subjectKey(kind);
-  return () => {
-    const locales = [
-      "en",
-      ...listMailLocales().filter(
-        (locale) => locale !== "en" && hasMailTranslationKey(locale, kindSubjectKey),
-      ),
-    ];
-    return Object.fromEntries(
-      locales.map((locale) => [
-        locale,
-        {
-          body: mailBody(locale, translationKey),
-          meta: {
-            subject: mailT(locale, kindSubjectKey, { app: "{{appName}}" }),
-            category: "transactional" as const,
-          },
-        },
-      ]),
-    );
-  };
-}
+export const authMailLocalizedTemplate = mailLocaleTemplates.localizedTemplate;

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

@@ -73,6 +73,7 @@ export function createLoginRoute(
   const MfaVerifyComponent = opts.mfaVerifyScreen;
   const MfaSetupComponent = opts.mfaSetupScreen;
 
+  // biome-ignore lint/correctness/noComponentHookFactories: setup-time factory (module scope or makeAuthGate); the route takes no props, so opts are bound here
   function LoginRoute(): ReactNode {
     const { status, refresh, bootstrapFailure, logout } = useSession();
     const { onAuthenticated } = opts;
@@ -212,6 +213,7 @@ function resolveLoginRedirectOrNull(
   try {
     return resolveLoginRedirect(loginUrl, locale, location);
   } catch (error) {
+    // biome-ignore lint/suspicious/noConsole: the browser console is the only place a broken loginUrl builder shows up, the visitor just sees the built-in login
     console.error("Auth gate: loginUrl could not be resolved, showing the built-in login", error);
     return null;
   }
@@ -223,6 +225,7 @@ export function makeAuthGate(opts: AuthGateOptions = {}): ComponentType<{
   const { loginUrl } = opts;
   if (typeof loginUrl === "string") assertNavigableUrl(loginUrl, "loginUrl");
   const LoginRoute = createLoginRoute(opts);
+  // biome-ignore lint/correctness/noComponentHookFactories: setup-time factory (makeSessionAuthGate or an app's mount function); gates only receive children, so opts are bound here
   function AuthGate({ children }: { readonly children: ReactNode }): ReactNode {
     const { status } = useSession();
     const locale = useLocale().locale();
@@ -255,6 +258,7 @@ export function makeSessionAuthGate(opts: SessionAuthGateOptions = {}): Componen
   const { postLogoutUrl } = opts;
   if (postLogoutUrl !== undefined) assertNavigableUrl(postLogoutUrl, "postLogoutUrl");
   const AuthGate = makeAuthGate(opts);
+  // biome-ignore lint/correctness/noComponentHookFactories: setup-time factory, called once per emailPasswordClient(); gates only receive children, so opts are bound here
   function SessionAuthGate({ children }: { readonly children: ReactNode }): ReactNode {
     return (
       <SessionProvider postLogoutUrl={postLogoutUrl}>

package/packages/bundled-features/src/auth-email-password/web/default-topbar-actions.tsx

@@ -24,6 +24,11 @@ export type DefaultTopbarActionsProps = {
   readonly lightIcon?: ReactNode;
   /** Dark-Mode-Icon. Default: Unicode ☾. */
   readonly darkIcon?: ReactNode;
+  /** Render the UserMenu. Default true; false for apps whose account/logout
+   *  lives elsewhere (for example a sidebar profile). */
+  readonly userMenu?: boolean;
+  /** data-testid forwarded to the ThemeToggle button. */
+  readonly themeToggleTestId?: string;
 };
 
 export function DefaultTopbarActions({
@@ -31,6 +36,8 @@ export function DefaultTopbarActions({
   extras,
   lightIcon,
   darkIcon,
+  userMenu = true,
+  themeToggleTestId,
 }: DefaultTopbarActionsProps = {}): ReactNode {
   return (
     <div className="flex items-center gap-2">
@@ -39,8 +46,9 @@ export function DefaultTopbarActions({
       <ThemeToggle
         {...(lightIcon !== undefined && { lightIcon })}
         {...(darkIcon !== undefined && { darkIcon })}
+        {...(themeToggleTestId !== undefined && { testId: themeToggleTestId })}
       />
-      <UserMenu />
+      {userMenu && <UserMenu />}
     </div>
   );
 }

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

@@ -87,6 +87,11 @@ export type { TenantMenuItemsProps } from "./tenant-menu-items.tsx";
 export { TenantMenuItems } from "./tenant-menu-items.tsx";
 export type { TenantSwitcherProps } from "./tenant-switcher.tsx";
 export { TenantSwitcher } from "./tenant-switcher.tsx";
+export type { UseRedirectAuthedFromLoginOptions } from "./use-redirect-authed-from-login.ts";
+export {
+  isAuthedOnLoginPath,
+  useRedirectAuthedFromLogin,
+} from "./use-redirect-authed-from-login.ts";
 export type { ShellUser } from "./use-shell-user.ts";
 export { useShellUser } from "./use-shell-user.ts";
 export type { UserMenuProps } from "./user-menu.tsx";

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

@@ -109,15 +109,15 @@ export function InviteAcceptScreen({
     );
   };
 
-  const acceptLoggedIn = async (): Promise<void> => {
+  const postInviteAccept = async (path: string, body: Record<string, string>): Promise<void> => {
     setSubmitting(true);
     setError(null);
     // kumiko-lint-ignore no-raw-hooks not yet converted to the framework hook set
-    const res = await fetch("/api/auth/invite-accept", {
+    const res = await fetch(path, {
       method: "POST",
       credentials: "same-origin",
       headers: { "Content-Type": "application/json", ...csrfHeader() },
-      body: JSON.stringify({ token }),
+      body: JSON.stringify(body),
     });
     setSubmitting(false);
     if (res.ok) {
@@ -129,45 +129,14 @@ export function InviteAcceptScreen({
     setError(t("auth.errors.invalidInviteToken"));
   };
 
-  const acceptAnonExisting = async (): Promise<void> => {
-    setSubmitting(true);
-    setError(null);
-    // kumiko-lint-ignore no-raw-hooks not yet converted to the framework hook set
-    const res = await fetch("/api/auth/invite-accept-with-login", {
-      method: "POST",
-      credentials: "same-origin",
-      headers: { "Content-Type": "application/json", ...csrfHeader() },
-      body: JSON.stringify({ token, email, password }),
-    });
-    setSubmitting(false);
-    if (res.ok) {
-      // @cast-boundary engine-payload — auth route JSON
-      const data = (await res.json()) as InviteAcceptResponse;
-      finishAccept(data);
-      return;
-    }
-    setError(t("auth.errors.invalidInviteToken"));
-  };
+  const acceptLoggedIn = (): Promise<void> =>
+    postInviteAccept("/api/auth/invite-accept", { token });
 
-  const acceptAnonNew = async (): Promise<void> => {
-    setSubmitting(true);
-    setError(null);
-    // kumiko-lint-ignore no-raw-hooks not yet converted to the framework hook set
-    const res = await fetch("/api/auth/invite-signup-complete", {
-      method: "POST",
-      credentials: "same-origin",
-      headers: { "Content-Type": "application/json", ...csrfHeader() },
-      body: JSON.stringify({ token, password }),
-    });
-    setSubmitting(false);
-    if (res.ok) {
-      // @cast-boundary engine-payload — auth route JSON
-      const data = (await res.json()) as InviteAcceptResponse;
-      finishAccept(data);
-      return;
-    }
-    setError(t("auth.errors.invalidInviteToken"));
-  };
+  const acceptAnonExisting = (): Promise<void> =>
+    postInviteAccept("/api/auth/invite-accept-with-login", { token, email, password });
+
+  const acceptAnonNew = (): Promise<void> =>
+    postInviteAccept("/api/auth/invite-signup-complete", { token, password });
 
   const onSubmit = (e?: FormEvent): void => {
     e?.preventDefault();

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

@@ -0,0 +1,15 @@
+import type { TenantSummary } from "./auth-client.ts";
+
+// Label priority: app-provided resolver > server-provided name/key from
+// /auth/tenants > UUID prefix. The prefix is only a last resort — it is
+// indistinguishable for seeded tenants (00000000-…).
+export function tenantLabel(
+  tenants: readonly TenantSummary[],
+  tenantId: string,
+  tenantName: ((tenantId: string) => string) | undefined,
+): string {
+  if (tenantName !== undefined) return tenantName(tenantId);
+  const membership = tenants.find((m) => m.tenantId === tenantId);
+  // || instead of ??: an empty name/key string must not be used as a label.
+  return membership?.name || membership?.key || tenantId.slice(0, 8);
+}

package/packages/bundled-features/src/auth-email-password/web/tenant-menu-items.tsx

@@ -9,6 +9,7 @@ import {
 } from "@cosmicdrift/kumiko-renderer/web";
 import type { ReactNode } from "react";
 import { useSession } from "./session.tsx";
+import { tenantLabel } from "./tenant-label.ts";
 
 export type TenantMenuItemsProps = {
   readonly tenantName?: (tenantId: string) => string;
@@ -19,12 +20,6 @@ export function TenantMenuItems({ tenantName }: TenantMenuItemsProps): ReactNode
   const { user, tenants, activeTenantId, switchTenant } = useSession();
   if (user === null || tenants.length <= 1) return null;
 
-  const nameOf = (tenantId: string): string => {
-    if (tenantName !== undefined) return tenantName(tenantId);
-    const membership = tenants.find((m) => m.tenantId === tenantId);
-    return membership?.name || membership?.key || tenantId.slice(0, 8);
-  };
-
   return (
     <>
       <DropdownMenuLabel>{t("auth.tenant.switcher.label")}</DropdownMenuLabel>
@@ -37,7 +32,7 @@ export function TenantMenuItems({ tenantName }: TenantMenuItemsProps): ReactNode
             if (membership.tenantId !== activeTenantId) void switchTenant(membership.tenantId);
           }}
         >
-          <span className="truncate">{nameOf(membership.tenantId)}</span>
+          <span className="truncate">{tenantLabel(tenants, membership.tenantId, tenantName)}</span>
         </DropdownMenuCheckboxItem>
       ))}
       <DropdownMenuSeparator />

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

@@ -24,6 +24,7 @@ import {
 import { Building2, ChevronDown } from "lucide-react";
 import { type ReactNode, useCallback, useState } from "react";
 import { useSession } from "./session.tsx";
+import { tenantLabel } from "./tenant-label.ts";
 
 export type TenantSwitcherProps = {
   /** Optional: provides a human-readable name for each tenant ID.
@@ -55,22 +56,14 @@ export function TenantSwitcher({ tenantName }: TenantSwitcherProps): ReactNode {
     [activeTenantId, switchTenant],
   );
 
-  // Label priority: app-provided resolver (prop) > server-provided
-  // name/key from /auth/tenants > UUID prefix. The latter is only a
-  // last resort — it is indistinguishable for seeded tenants (00000000-…).
-  const nameOf = (tenantId: string): string => {
-    if (tenantName !== undefined) return tenantName(tenantId);
-    const membership = tenants.find((m) => m.tenantId === tenantId);
-    // || instead of ??: an empty name/key string must not be used as a label.
-    return membership?.name || membership?.key || tenantId.slice(0, 8);
-  };
-
   // Rendering gate: no user → nothing; only one tenant → nothing as well
   // (single-tenant apps do not need a switcher).
   if (user === null || tenants.length <= 1) return null;
 
   const activeLabel =
-    activeTenantId !== null ? nameOf(activeTenantId) : t("auth.tenant.switcher.none");
+    activeTenantId !== null
+      ? tenantLabel(tenants, activeTenantId, tenantName)
+      : t("auth.tenant.switcher.none");
 
   return (
     <DropdownMenu>
@@ -105,7 +98,9 @@ export function TenantSwitcher({ tenantName }: TenantSwitcherProps): ReactNode {
               }}
             >
               <div className="flex flex-col items-start min-w-0">
-                <span className="truncate font-medium">{nameOf(membership.tenantId)}</span>
+                <span className="truncate font-medium">
+                  {tenantLabel(tenants, membership.tenantId, tenantName)}
+                </span>
                 {membership.roles.length > 0 && (
                   <span className="text-xs text-muted-foreground truncate">
                     {membership.roles.join(", ")}

package/packages/bundled-features/src/auth-email-password/web/use-redirect-authed-from-login.ts

@@ -0,0 +1,39 @@
+import { type NavTarget, useNav } from "@cosmicdrift/kumiko-renderer";
+import { useEffect, useRef } from "react";
+import { useSession } from "./session.tsx";
+
+export function isAuthedOnLoginPath(authed: boolean, pathname: string, loginPath: string): boolean {
+  return authed && pathname === loginPath;
+}
+
+export type UseRedirectAuthedFromLoginOptions = {
+  readonly loginPath: string;
+  readonly target: NavTarget;
+};
+
+// The SPA has no screen at the login path: after a login the URL stays there, and marketing
+// links land there directly. replace, not navigate: a push would make Browser-Back from the
+// target land on the login path again, which redirects forward again (history ping-pong).
+export function useRedirectAuthedFromLogin({
+  loginPath,
+  target,
+}: UseRedirectAuthedFromLoginOptions): void {
+  const session = useSession();
+  const nav = useNav();
+  const authed = session.user !== null;
+  // Callers pass an inline object; a ref keeps it out of the effect deps.
+  const targetRef = useRef(target);
+  targetRef.current = target;
+  useEffect(() => {
+    // skip: no browser location to inspect (native or server render)
+    if (typeof window === "undefined") return;
+    const redirectIfStranded = () => {
+      if (isAuthedOnLoginPath(authed, window.location.pathname, loginPath))
+        nav.replace(targetRef.current);
+    };
+    redirectIfStranded();
+    // Browser-Back to the login path changes neither authed nor nav, so the effect alone would not re-fire.
+    window.addEventListener("popstate", redirectIfStranded);
+    return () => window.removeEventListener("popstate", redirectIfStranded);
+  }, [authed, nav, loginPath]);
+}

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

@@ -58,33 +58,20 @@ export function createAuthFoundationFeature() {
         recommended: false,
       });
 
-      r.extendsRegistrar(EXT_TOKEN_VERIFIER, {
-        onRegister: () => {
-          // No side-effects at register-time — registry stores the usage,
-          // resolveTokenVerifier looks it up at request-time.
-        },
-      });
+      // Registry stores the usage, resolveTokenVerifier looks it up at request-time.
+      r.extendsRegistrar(EXT_TOKEN_VERIFIER, {});
       r.bootCheck(({ features }) => validateTokenVerifierMultiplicity(features));
 
-      r.extendsRegistrar(EXT_SESSION_STORE, {
-        onRegister: () => {
-          // No side-effects at register-time — resolveSessionStore at boot/request.
-        },
-      });
+      // resolveSessionStore looks the usage up at boot/request-time.
+      r.extendsRegistrar(EXT_SESSION_STORE, {});
       r.bootCheck(({ features }) => validateSessionStoreMultiplicity(features));
 
-      r.extendsRegistrar(EXT_TENANT_RESOLVER, {
-        onRegister: () => {
-          // Optional — zero providers is fine (single-tenant / header-cookie).
-        },
-      });
+      // Optional — zero providers is fine (single-tenant / header-cookie).
+      r.extendsRegistrar(EXT_TENANT_RESOLVER, {});
       r.bootCheck(({ features }) => validateTenantResolverMultiplicity(features));
 
-      r.extendsRegistrar(EXT_TENANT_EXISTENCE, {
-        onRegister: () => {
-          // Optional — zero providers skips the existence check.
-        },
-      });
+      // Optional — zero providers skips the existence check.
+      r.extendsRegistrar(EXT_TENANT_EXISTENCE, {});
       r.bootCheck(({ features }) => validateTenantExistenceMultiplicity(features));
     },
     { dedupeOptions: {} },

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

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.405.0",
+    "type": "improvement",
+    "title": "MFA setup token uses the shared HMAC token codec",
+    "detail": "signMfaSetupToken and verifyMfaSetupToken run on createHmacTokenCodec with the domain mfa-setup. Tokens issued before the change still verify, and new tokens are byte-identical for the same input. The challenge and preauth-setup tokens share one payload guard, and signed-token and the inbound-mail OAuth state use the same HMAC signature helper."
+  },
   {
     "version": "0.391.0",
     "type": "fix",

package/packages/bundled-features/src/auth-mfa/handlers/reencrypt.job.ts

@@ -34,7 +34,6 @@ import {
   createTenantDb,
   type DbConnection,
   selectMany,
-  type TenantDb,
 } from "@cosmicdrift/kumiko-framework/db";
 import type { JobContext, SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
@@ -42,6 +41,7 @@ import type { EnvelopeCipher } from "@cosmicdrift/kumiko-framework/secrets";
 import {
   type ChunkedMigrationStopReason,
   classifyStoredEnvelope,
+  createTenantDbCache,
   runChunkedMigration,
 } from "../../shared/index.ts";
 import { userMfaEntity, userMfaTable } from "../schema/user-mfa.ts";
@@ -105,20 +105,14 @@ export async function mfaReencryptJob(
     ? Date.now() + payload.maxDurationMs
     : Number.POSITIVE_INFINITY;
 
-  const tdbCache = new Map<TenantId, TenantDb>();
-  function tdbFor(tenantId: TenantId): TenantDb {
-    let existing = tdbCache.get(tenantId);
-    if (!existing) {
-      existing = createTenantDb({
-        db,
-        tenantId,
-        mode: "system",
-        reason: "MFA key re-encryption job rewrites enrollments of every tenant",
-      });
-      tdbCache.set(tenantId, existing);
-    }
-    return existing;
-  }
+  const tdbFor = createTenantDbCache((tenantId) =>
+    createTenantDb({
+      db,
+      tenantId,
+      mode: "system",
+      reason: "MFA key re-encryption job rewrites enrollments of every tenant",
+    }),
+  );
 
   type UserMfaRow = {
     id: string;

package/packages/bundled-features/src/auth-mfa/hmac-token-codec.ts

@@ -1,21 +1,26 @@
-import { createHmac, timingSafeEqual } from "node:crypto";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
-
-function hmacSign(input: string, secret: string): string {
-  return createHmac("sha256", secret).update(input).digest("base64url");
-}
+import { hmacSignatureMatches, signHmacSha256Base64Url } from "../shared/index.ts";
 
 export type HmacTokenVerifyResult<TPayload> =
   | { readonly ok: true; readonly payload: TPayload; readonly expiresAtMs: number }
   | { readonly ok: false; readonly reason: "malformed" | "bad_signature" | "expired" };
 
+export type UserTenantPayload = { readonly userId: string; readonly tenantId: TenantId };
+
+export function isUserTenantPayload(value: unknown): value is UserTenantPayload {
+  if (!isPlainObject(value)) return false;
+  return typeof value["userId"] === "string" && typeof value["tenantId"] === "string";
+}
+
 // `domain` is part of the signed input: it is the only thing that stops a token
 // minted for one MFA step from verifying as another (e.g. a preauth-setup token
 // replayed as a challenge token), since both share the same secret and payload shape.
-export function createHmacTokenCodec<
-  TPayload extends { readonly userId: string; readonly tenantId: string },
->(domain: string, isPayload: (value: unknown) => value is TPayload) {
+export function createHmacTokenCodec<TPayload extends { readonly userId: string }>(
+  domain: string,
+  isPayload: (value: unknown) => value is TPayload,
+) {
   type EncodedBody = TPayload & { readonly expiresAtMs: number };
 
   function splitEncodedBody(
@@ -38,7 +43,7 @@ export function createHmacTokenCodec<
       const expiresAt = now.add({ minutes: ttlMinutes });
       const body: EncodedBody = { ...payload, expiresAtMs: expiresAt.epochMilliseconds };
       const bodyB64 = Buffer.from(JSON.stringify(body)).toString("base64url");
-      const signature = hmacSign(`${domain}:${bodyB64}`, secret);
+      const signature = signHmacSha256Base64Url(`${domain}:${bodyB64}`, secret);
       return { token: `${bodyB64}.${signature}`, expiresAt };
     },
 
@@ -52,11 +57,9 @@ export function createHmacTokenCodec<
       const [bodyB64, providedSig] = parts;
       if (!bodyB64 || !providedSig) return { ok: false, reason: "malformed" };
 
-      const expected = hmacSign(`${domain}:${bodyB64}`, secret);
-      const expectedBuf = Buffer.from(expected, "base64url");
-      const providedBuf = Buffer.from(providedSig, "base64url");
-      if (expectedBuf.length !== providedBuf.length) return { ok: false, reason: "bad_signature" };
-      if (!timingSafeEqual(expectedBuf, providedBuf)) return { ok: false, reason: "bad_signature" };
+      const expected = signHmacSha256Base64Url(`${domain}:${bodyB64}`, secret);
+      if (!hmacSignatureMatches(expected, providedSig))
+        return { ok: false, reason: "bad_signature" };
 
       let parsed: unknown;
       try {