@cosmicdrift/kumiko-bundled-features 0.1.0

package/src/auth-email-password/email-templates.ts

@@ -0,0 +1,283 @@
+// Default-HTML-Renderer für die transactional Auth-Mails (Reset-Password
+// + Verify-Email). Apps wiren die `sendResetEmail` / `sendVerificationEmail`
+// callbacks im framework-config (siehe PasswordResetConfig im
+// auth-routes.ts). Statt jede App selbst HTML zu schreiben, kann sie diese
+// Renderer als one-liner nutzen:
+//
+//   passwordReset: {
+//     sendResetEmail: ({ email, resetUrl, expiresAt }) =>
+//       mailSender.send({
+//         to: email,
+//         ...renderResetPasswordEmail({ resetUrl, expiresAt, locale: "de" }),
+//       }),
+//   }
+//
+// Apps die ihr eigenes Branding wollen, schreiben einen eigenen Renderer
+// und mischen ihn in. Die Templates hier sind bewusst plain HTML mit
+// inline-styling — kein CSS-Framework, kein bild-asset. Mail-Clients
+// rendern das verlässlich, und der Operator kann das HTML im Mailer-Log
+// problemlos lesen.
+//
+// Locale: de + en. Apps mit anderen Sprachen rendern selbst.
+
+import { Temporal } from "temporal-polyfill";
+
+export type AuthMailLocale = "de" | "en";
+
+export type RenderResetPasswordEmailArgs = {
+  readonly resetUrl: string;
+  readonly expiresAt: string;
+  readonly locale?: AuthMailLocale;
+  /** Optional: App-Name fürs Subject + Header. Default "Account". */
+  readonly appName?: string;
+};
+
+export type RenderVerifyEmailArgs = {
+  readonly verificationUrl: string;
+  readonly expiresAt: string;
+  readonly locale?: AuthMailLocale;
+  readonly appName?: string;
+};
+
+export type RenderActivationEmailArgs = {
+  readonly activationUrl: string;
+  readonly expiresAt: string;
+  readonly locale?: AuthMailLocale;
+  readonly appName?: string;
+};
+
+export type RenderInviteEmailArgs = {
+  readonly inviteUrl: string;
+  readonly expiresAt: string;
+  readonly role: string;
+  readonly locale?: AuthMailLocale;
+  readonly appName?: string;
+};
+
+export type RenderedEmail = {
+  readonly subject: string;
+  readonly html: string;
+};
+
+const STRINGS = {
+  de: {
+    resetSubject: (app: string) => `${app} — Passwort zurücksetzen`,
+    resetGreeting: "Hallo,",
+    resetIntro: (app: string) =>
+      `du hast den Reset deines Passworts für ${app} angefordert. Klicke auf den folgenden Link, um ein neues Passwort zu setzen:`,
+    resetButton: "Passwort zurücksetzen",
+    resetExpiry: (when: string) => `Der Link läuft am ${when} ab.`,
+    resetIgnore:
+      "Falls du keinen Reset angefordert hast, kannst du diese E-Mail einfach ignorieren — dein Passwort bleibt unverändert.",
+    verifySubject: (app: string) => `${app} — E-Mail bestätigen`,
+    verifyGreeting: "Willkommen,",
+    verifyIntro: (app: string) =>
+      `bitte bestätige deine E-Mail-Adresse für ${app}, um dein Konto zu aktivieren:`,
+    verifyButton: "E-Mail bestätigen",
+    verifyExpiry: (when: string) => `Der Link läuft am ${when} ab.`,
+    verifyIgnore: "Falls du dieses Konto nicht angelegt hast, kannst du diese E-Mail ignorieren.",
+    activationSubject: (app: string) => `${app} — Account aktivieren`,
+    activationGreeting: "Willkommen,",
+    activationIntro: (app: string) =>
+      `klicke auf den folgenden Link, um deinen ${app}-Account zu aktivieren. Im nächsten Schritt setzt du dein Passwort:`,
+    activationButton: "Account aktivieren",
+    activationExpiry: (when: string) => `Der Link läuft am ${when} ab.`,
+    activationIgnore:
+      "Falls du dich nicht registriert hast, kannst du diese E-Mail ignorieren — es wird kein Account erstellt, solange du den Link nicht öffnest.",
+    inviteSubject: (app: string) => `${app} — Einladung zum Workspace`,
+    inviteGreeting: "Hallo,",
+    inviteIntro: (app: string, role: string) =>
+      `du wurdest zu einem ${app}-Workspace als ${role} eingeladen. Klicke auf den folgenden Link, um die Einladung anzunehmen:`,
+    inviteButton: "Einladung annehmen",
+    inviteExpiry: (when: string) => `Der Link läuft am ${when} ab.`,
+    inviteIgnore:
+      "Falls du diese Einladung nicht erwartet hast, kannst du diese E-Mail ignorieren.",
+    fallbackUrl: "Falls der Button nicht funktioniert, kopiere diesen Link in den Browser:",
+  },
+  en: {
+    resetSubject: (app: string) => `${app} — Reset your password`,
+    resetGreeting: "Hi,",
+    resetIntro: (app: string) =>
+      `you requested a password reset for ${app}. Click the link below to set a new password:`,
+    resetButton: "Reset password",
+    resetExpiry: (when: string) => `The link expires on ${when}.`,
+    resetIgnore:
+      "If you didn't request a reset, you can safely ignore this email — your password won't change.",
+    verifySubject: (app: string) => `${app} — Verify your email`,
+    verifyGreeting: "Welcome,",
+    verifyIntro: (app: string) =>
+      `please verify your email address for ${app} to activate your account:`,
+    verifyButton: "Verify email",
+    verifyExpiry: (when: string) => `The link expires on ${when}.`,
+    verifyIgnore: "If you didn't create this account, you can ignore this email.",
+    activationSubject: (app: string) => `${app} — Activate your account`,
+    activationGreeting: "Welcome,",
+    activationIntro: (app: string) =>
+      `click the link below to activate your ${app} account. The next step is choosing your password:`,
+    activationButton: "Activate account",
+    activationExpiry: (when: string) => `The link expires on ${when}.`,
+    activationIgnore:
+      "If you didn't sign up, you can ignore this email — no account is created until you open the link.",
+    inviteSubject: (app: string) => `${app} — Workspace invitation`,
+    inviteGreeting: "Hi,",
+    inviteIntro: (app: string, role: string) =>
+      `you've been invited to a ${app} workspace as ${role}. Click the link below to accept:`,
+    inviteButton: "Accept invitation",
+    inviteExpiry: (when: string) => `The link expires on ${when}.`,
+    inviteIgnore: "If you weren't expecting this invitation, you can ignore this email.",
+    fallbackUrl: "If the button doesn't work, copy this link into your browser:",
+  },
+} as const;
+
+// Shared shape für beide Token-Mails — heading/intro/button/expiry/ignore
+// + button-Url + fallback-Url. renderResetPasswordEmail und renderVerifyEmail
+// bauen den Spec aus den lokalisierten STRINGS und delegieren ans
+// renderTokenEmail. Damit ist die Layout-Logik genau einmal definiert.
+type TokenEmailSpec = {
+  readonly subject: string;
+  readonly greeting: string;
+  readonly intro: string;
+  readonly buttonLabel: string;
+  readonly buttonUrl: string;
+  readonly expiry: string;
+  readonly ignore: string;
+  readonly fallbackUrlLabel: string;
+};
+
+function renderTokenEmail(spec: TokenEmailSpec): RenderedEmail {
+  const bodyHtml = `
+    <tr><td>
+      <p style="margin: 0 0 16px; font-size: 16px;">${escapeHtml(spec.greeting)}</p>
+      <p style="margin: 0 0 24px; font-size: 14px; line-height: 1.5;">${escapeHtml(spec.intro)}</p>
+      <p style="margin: 0 0 24px;">${renderButton({ url: spec.buttonUrl, label: spec.buttonLabel })}</p>
+      <p style="margin: 0 0 8px; font-size: 13px; color: #555;">${escapeHtml(spec.expiry)}</p>
+      <p style="margin: 0; font-size: 13px; color: #555;">${escapeHtml(spec.ignore)}</p>
+      ${renderFallbackUrl({ url: spec.buttonUrl, label: spec.fallbackUrlLabel })}
+    </td></tr>`;
+  return { subject: spec.subject, html: renderShell({ title: spec.subject, bodyHtml }) };
+}
+
+// Plain inline-styled HTML — funktioniert in Gmail/Outlook/Apple-Mail
+// ohne dass wir Tailwind oder eine HTML-mail-Lib reinziehen müssen.
+function renderShell(args: { title: string; bodyHtml: string }): string {
+  return `<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${escapeHtml(args.title)}</title>
+  </head>
+  <body style="margin: 0; padding: 0; background: #f7f7f7; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; color: #1a1a1a;">
+    <table width="100%" cellpadding="0" cellspacing="0" style="padding: 24px 0;">
+      <tr>
+        <td align="center">
+          <table width="560" cellpadding="0" cellspacing="0" style="max-width: 560px; background: #ffffff; border-radius: 8px; padding: 32px;">
+            ${args.bodyHtml}
+          </table>
+        </td>
+      </tr>
+    </table>
+  </body>
+</html>`;
+}
+
+function renderButton(args: { url: string; label: string }): string {
+  return `<a href="${escapeAttr(args.url)}" style="display: inline-block; background: #1a1a1a; color: #ffffff; padding: 12px 24px; border-radius: 6px; text-decoration: none; font-weight: 500;">${escapeHtml(args.label)}</a>`;
+}
+
+function renderFallbackUrl(args: { url: string; label: string }): string {
+  return `<p style="margin: 24px 0 0; font-size: 12px; color: #666;">${escapeHtml(args.label)}<br /><a href="${escapeAttr(args.url)}" style="color: #1a1a1a; word-break: break-all;">${escapeHtml(args.url)}</a></p>`;
+}
+
+export function renderResetPasswordEmail(args: RenderResetPasswordEmailArgs): RenderedEmail {
+  const locale = args.locale ?? "en";
+  const appName = args.appName ?? (locale === "de" ? "Konto" : "Account");
+  const t = STRINGS[locale];
+  return renderTokenEmail({
+    subject: t.resetSubject(appName),
+    greeting: t.resetGreeting,
+    intro: t.resetIntro(appName),
+    buttonLabel: t.resetButton,
+    buttonUrl: args.resetUrl,
+    expiry: t.resetExpiry(formatExpiry(args.expiresAt)),
+    ignore: t.resetIgnore,
+    fallbackUrlLabel: t.fallbackUrl,
+  });
+}
+
+export function renderVerifyEmail(args: RenderVerifyEmailArgs): RenderedEmail {
+  const locale = args.locale ?? "en";
+  const appName = args.appName ?? (locale === "de" ? "Konto" : "Account");
+  const t = STRINGS[locale];
+  return renderTokenEmail({
+    subject: t.verifySubject(appName),
+    greeting: t.verifyGreeting,
+    intro: t.verifyIntro(appName),
+    buttonLabel: t.verifyButton,
+    buttonUrl: args.verificationUrl,
+    expiry: t.verifyExpiry(formatExpiry(args.expiresAt)),
+    ignore: t.verifyIgnore,
+    fallbackUrlLabel: t.fallbackUrl,
+  });
+}
+
+export function renderActivationEmail(args: RenderActivationEmailArgs): RenderedEmail {
+  const locale = args.locale ?? "en";
+  const appName = args.appName ?? (locale === "de" ? "Konto" : "Account");
+  const t = STRINGS[locale];
+  return renderTokenEmail({
+    subject: t.activationSubject(appName),
+    greeting: t.activationGreeting,
+    intro: t.activationIntro(appName),
+    buttonLabel: t.activationButton,
+    buttonUrl: args.activationUrl,
+    expiry: t.activationExpiry(formatExpiry(args.expiresAt)),
+    ignore: t.activationIgnore,
+    fallbackUrlLabel: t.fallbackUrl,
+  });
+}
+
+export function renderInviteEmail(args: RenderInviteEmailArgs): RenderedEmail {
+  const locale = args.locale ?? "en";
+  const appName = args.appName ?? (locale === "de" ? "Workspace" : "Workspace");
+  const t = STRINGS[locale];
+  return renderTokenEmail({
+    subject: t.inviteSubject(appName),
+    greeting: t.inviteGreeting,
+    intro: t.inviteIntro(appName, args.role),
+    buttonLabel: t.inviteButton,
+    buttonUrl: args.inviteUrl,
+    expiry: t.inviteExpiry(formatExpiry(args.expiresAt)),
+    ignore: t.inviteIgnore,
+    fallbackUrlLabel: t.fallbackUrl,
+  });
+}
+
+// ISO-Timestamp aus dem Token-Handler ("2026-05-04T13:45:00.000Z") in
+// "2026-05-04 13:45 UTC" rendern. Locale-unabhängig damit der Mail-
+// Renderer keine locale-spezifischen Number-Formatter mitschleppt; UTC-
+// Suffix damit der User unabhängig von seiner Tz sieht wann der Link
+// abläuft. Bei un-parsbarem Input fällt's auf den raw-string zurück.
+function formatExpiry(iso: string): string {
+  try {
+    const z = Temporal.Instant.from(iso).toZonedDateTimeISO("UTC");
+    return `${z.year}-${pad2(z.month)}-${pad2(z.day)} ${pad2(z.hour)}:${pad2(z.minute)} UTC`;
+  } catch {
+    return iso;
+  }
+}
+
+function pad2(n: number): string {
+  return String(n).padStart(2, "0");
+}
+
+function escapeHtml(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function escapeAttr(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}

package/src/auth-email-password/feature.ts

@@ -0,0 +1,140 @@
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { changePasswordWrite } from "./handlers/change-password.write";
+import { createInviteAcceptHandler } from "./handlers/invite-accept.write";
+import { createInviteAcceptWithLoginHandler } from "./handlers/invite-accept-with-login.write";
+import {
+  createInviteCreateHandler,
+  type InviteCreateOptions,
+} from "./handlers/invite-create.write";
+import { createInviteSignupCompleteHandler } from "./handlers/invite-signup-complete.write";
+import { createLoginHandler } from "./handlers/login.write";
+import { logoutWrite } from "./handlers/logout.write";
+import { createRequestEmailVerificationHandler } from "./handlers/request-email-verification.write";
+import { createRequestPasswordResetHandler } from "./handlers/request-password-reset.write";
+import { createResetPasswordHandler } from "./handlers/reset-password.write";
+import { createSignupConfirmHandler } from "./handlers/signup-confirm.write";
+import {
+  createSignupRequestHandler,
+  type SignupRequestOptions,
+} from "./handlers/signup-request.write";
+import { createVerifyEmailHandler } from "./handlers/verify-email.write";
+
+// Opt-in configuration for the password-reset flow. When omitted the
+// request-password-reset / reset-password handlers are not registered —
+// the framework-level routes stay 404 and callers know the flow is off.
+// Keeping this at the feature level (rather than via env) means the caller
+// explicitly acknowledges that reset is wired and that they have a working
+// sendResetEmail callback on the framework side.
+export type PasswordResetOptions = {
+  readonly hmacSecret: string;
+  readonly tokenTtlMinutes?: number;
+};
+
+// Opt-in configuration for the email-verification flow. mode="strict"
+// forces login to fail with email_not_verified when the flag is false;
+// "off" registers the handlers without login-gating (useful during
+// rollout so existing accounts keep working). Default: strict — if you
+// wire verification at all, you probably want it enforced.
+export type EmailVerificationOptions = {
+  readonly hmacSecret: string;
+  readonly tokenTtlMinutes?: number;
+  readonly mode?: "strict" | "off";
+};
+
+// Brute-force protection on the login handler. Omit for the defaults
+// (5 failures → 15-minute lock). Set the dial knobs to override.
+//
+// Storage: Redis (keyed by userId). Without ctx.redis the handler skips
+// lockout entirely — login still works, but brute-force protection falls
+// back to the IP-rate-limiter. Counter is monotonic: only a successful
+// login resets it, so after a lockout expires the next wrong password
+// re-locks on attempt 1 (strict semantic — see lockout-store.ts for
+// rationale).
+export type AccountLockoutOptions = {
+  readonly maxFailedAttempts?: number;
+  readonly lockoutDurationMinutes?: number;
+};
+
+// Magic-Link Self-Signup. Wenn gesetzt, registriert das Feature die
+// signup-request + signup-confirm-Handler. Der Token-Store (Redis)
+// kommt aus ctx.redis — tokenTtlMinutes ist der einzige Knopf
+// (Token-Material ist generateToken() = 256 Bit randomBytes, fest;
+// Memory feedback_no_options_without_need: keine Knöpfe ohne Bedarf).
+// Anders als reset/verify gibt's kein hmacSecret hier, weil der Token
+// opaque random ist (Redis ist Source of Truth).
+export type SignupOptions = SignupRequestOptions;
+
+// Tenant-Invite Magic-Link. Wenn gesetzt, registriert das Feature die
+// invite-create + invite-accept-Handler. Branch 2+3 (anon-flows) kommen
+// als separate Handler in einem Folge-Schritt. tokenTtlMinutes Default
+// 7 Tage (industry standard).
+export type InviteOptions = InviteCreateOptions;
+
+export type AuthEmailPasswordOptions = {
+  readonly passwordReset?: PasswordResetOptions;
+  readonly emailVerification?: EmailVerificationOptions;
+  readonly accountLockout?: AccountLockoutOptions;
+  readonly signup?: SignupOptions;
+  readonly invite?: InviteOptions;
+};
+
+// Auth feature — email+password login. Depends on the user feature for
+// identity lookups (via ctx.queryAs) and on the tenant feature for
+// membership resolution. No direct imports of foreign tables.
+export function createAuthEmailPasswordFeature(
+  opts: AuthEmailPasswordOptions = {},
+): FeatureDefinition {
+  if (opts.passwordReset && !opts.passwordReset.hmacSecret) {
+    throw new Error(
+      "[auth-email-password] passwordReset.hmacSecret must be non-empty when passwordReset is configured",
+    );
+  }
+  if (opts.emailVerification && !opts.emailVerification.hmacSecret) {
+    throw new Error(
+      "[auth-email-password] emailVerification.hmacSecret must be non-empty when emailVerification is configured",
+    );
+  }
+
+  const strictVerification =
+    opts.emailVerification !== undefined && (opts.emailVerification.mode ?? "strict") === "strict";
+
+  return defineFeature("auth-email-password", (r) => {
+    r.requires("user");
+    r.requires("tenant");
+
+    const handlers = {
+      login: r.writeHandler(
+        createLoginHandler({
+          strictEmailVerification: strictVerification,
+          accountLockout: opts.accountLockout,
+        }),
+      ),
+      changePassword: r.writeHandler(changePasswordWrite),
+      logout: r.writeHandler(logoutWrite),
+    };
+
+    if (opts.passwordReset) {
+      r.writeHandler(createRequestPasswordResetHandler(opts.passwordReset));
+      r.writeHandler(createResetPasswordHandler(opts.passwordReset));
+    }
+
+    if (opts.emailVerification) {
+      r.writeHandler(createRequestEmailVerificationHandler(opts.emailVerification));
+      r.writeHandler(createVerifyEmailHandler(opts.emailVerification));
+    }
+
+    if (opts.signup) {
+      r.writeHandler(createSignupRequestHandler(opts.signup));
+      r.writeHandler(createSignupConfirmHandler());
+    }
+
+    if (opts.invite) {
+      r.writeHandler(createInviteCreateHandler(opts.invite));
+      r.writeHandler(createInviteAcceptHandler());
+      r.writeHandler(createInviteAcceptWithLoginHandler());
+      r.writeHandler(createInviteSignupCompleteHandler());
+    }
+
+    return { handlers };
+  });
+}

package/src/auth-email-password/handlers/change-password.write.ts

@@ -0,0 +1,58 @@
+import { access, createSystemUser, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { z } from "zod";
+import { UserHandlers, UserQueries } from "../../user";
+import { AuthErrors } from "../constants";
+import { hashPassword, verifyPassword } from "../password-hashing";
+
+function invalidCredentials() {
+  return writeFailure(
+    new UnprocessableError(AuthErrors.invalidCredentials, {
+      i18nKey: "auth.errors.invalidCredentials",
+    }),
+  );
+}
+
+// Change-password — authenticated. The user supplies their current password
+// (re-auth) and the new one. The new hash is written via ctx.writeAs(system)
+// against the user feature's update handler; field-access on passwordHash
+// (privileged-only) lets the system identity through.
+export const changePasswordWrite = defineWriteHandler({
+  name: "change-password",
+  schema: z.object({
+    oldPassword: z.string().min(1),
+    newPassword: z.string().min(8).max(200),
+  }),
+  access: { roles: access.authenticated },
+  handler: async (event, ctx) => {
+    const systemUser = createSystemUser(event.user.tenantId);
+
+    // Load self with passwordHash — only visible to the privileged caller.
+    const me = (await ctx.queryAs(systemUser, UserQueries.findForAuth, {
+      id: event.user.id,
+    })) as { id: number; passwordHash: string | null; version: number } | null;
+
+    if (!me?.passwordHash) {
+      return invalidCredentials();
+    }
+
+    const oldOk = await verifyPassword(me.passwordHash, event.payload.oldPassword);
+    if (!oldOk) {
+      return invalidCredentials();
+    }
+
+    const newHash = await hashPassword(event.payload.newPassword);
+
+    // Apply via user feature's update handler — writeAs(system) satisfies
+    // the privileged-only write rule on passwordHash. Pass the current version
+    // through so optimistic locking still applies end-to-end.
+    const writeRes = await ctx.writeAs(systemUser, UserHandlers.update, {
+      id: me.id,
+      version: me.version,
+      changes: { passwordHash: newHash },
+    });
+    if (!writeRes.isSuccess) return writeRes;
+
+    return { isSuccess: true, data: { kind: "password-changed" } };
+  },
+});

package/src/auth-email-password/handlers/confirm-token-flow.ts

@@ -0,0 +1,191 @@
+// Shared state-change pipeline for the confirm side of out-of-band token
+// flows (password-reset, email-verification). Both follow the same shape
+// once the token is verified:
+//
+//   1. Redis check + burn (single-use enforcement)
+//   2. Load user + deleted/missing/no-version guard
+//   3. Optional idempotent short-circuit (verify-email when already done)
+//   4. Resolve memberships → tenant-order for stream-matching
+//   5. Try each tenant's stream with the handler-specific `changes`
+//   6. Release the burn on ANY non-success path so a legit retry isn't
+//      locked out by a stale marker
+//
+// The top-level `runConfirmTokenFlow` orchestrates and owns the
+// try/finally burn-release. Every branch that should NOT release the
+// burn (success, already-done) flips `committed = true`; everything
+// else — including future branches a maintainer adds — releases
+// automatically.
+
+import {
+  createSystemUser,
+  type HandlerContext,
+  type SessionUser,
+  SYSTEM_TENANT_ID,
+  type TenantId,
+  type WriteResult,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  InternalError,
+  type WriteFailure,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
+import type Redis from "ioredis";
+import { UserHandlers, UserQueries } from "../../user";
+import type { AuthUserRow } from "../auth-user-row";
+import { parseAuthUserRow } from "../auth-user-row";
+import { orderTenantsByPreference } from "../stream-tenant";
+import { burnToken, unburnToken } from "../token-burn-store";
+
+export type ConfirmTokenFlowSpec<TSuccessData> = {
+  // Short purpose-tag used in the burn-store key. Must NOT overlap with
+  // other token flows — "reset" vs "verify" keeps cross-flow replay
+  // impossible at both layers (HMAC-purpose AND burn-purpose).
+  readonly purpose: string;
+  // Used verbatim in the 5xx body when ctx.redis is missing — the feature
+  // is misconfigured, not the caller's fault.
+  readonly redisRequiredMessage: string;
+  // Standard failure returned for every "token can't be consumed" path
+  // (bad state, missing memberships, every tenant rejected). The route
+  // layer returns 422 with a uniform code so the caller can't tell which
+  // branch fired.
+  readonly invalidToken: () => ReturnType<typeof writeFailure>;
+  // Handler-specific payload for user:update. Runs once per token — the
+  // result is shared across every tenant-stream attempt. Can be async
+  // (password-reset hashes here).
+  readonly buildChanges: (me: AuthUserRow) => Promise<Record<string, unknown>>;
+  // Returned verbatim on a successful write.
+  readonly successData: TSuccessData;
+  // Optional idempotent short-circuit. When `check(me)` is true, the flow
+  // skips the write entirely and returns `data` — but keeps the burn
+  // intact, because the token's job is done (state already matches what
+  // the write would have produced). A second click sees `already-used`.
+  readonly alreadyDone?: {
+    readonly check: (me: AuthUserRow) => boolean;
+    readonly data: TSuccessData;
+  };
+};
+
+export async function runConfirmTokenFlow<TSuccessData>(
+  ctx: HandlerContext,
+  userId: string,
+  expiresAtMs: number,
+  spec: ConfirmTokenFlowSpec<TSuccessData>,
+): Promise<WriteResult<TSuccessData>> {
+  if (!ctx.redis) {
+    return writeFailure(new InternalError({ message: spec.redisRequiredMessage }));
+  }
+  const redis: Redis = ctx.redis;
+
+  const burn = await burnToken(redis, spec.purpose, userId, expiresAtMs);
+  if (burn === "already-used") return spec.invalidToken();
+
+  let committed = false;
+  try {
+    // Cross-tenant queries run under a SYSTEM_TENANT-scoped identity;
+    // user-feature is r.systemScope so this bypasses the tenant filter.
+    const systemUser = createSystemUser(SYSTEM_TENANT_ID);
+
+    const me = await loadValidatedUser(ctx, systemUser, userId);
+    if (!me) return spec.invalidToken();
+
+    if (spec.alreadyDone?.check(me)) {
+      // Token job is done — keep the burn intact. A replay from another
+      // device lands cleanly on the already-used branch above.
+      committed = true;
+      return { isSuccess: true, data: spec.alreadyDone.data };
+    }
+
+    const tenantOrder = await resolveStreamTenants(ctx, systemUser, me);
+    if (tenantOrder.length === 0) return spec.invalidToken();
+
+    const changes = await spec.buildChanges(me);
+    const writeResult = await tryWriteAcrossTenants(ctx, me, tenantOrder, changes);
+    if (writeResult.isSuccess) {
+      committed = true;
+      return { isSuccess: true, data: spec.successData };
+    }
+    // `all_conflicts` = every tenant returned version_conflict → token-level
+    // failure. `hard_failure` = a real write error (DB down, access
+    // denied) that bubbles unchanged.
+    if (writeResult.reason === "all_conflicts") return spec.invalidToken();
+    return writeResult.failure;
+  } finally {
+    // committed===false covers EVERY failure path — including branches a
+    // future maintainer adds without reading this file. The original
+    // handlers had ~7 explicit unburn calls; any forgotten one would
+    // have locked the token. Flag pattern is robust-by-default.
+    if (!committed) {
+      await unburnToken(redis, spec.purpose, userId, expiresAtMs);
+    }
+  }
+}
+
+// --- Private helpers ------------------------------------------------------
+
+// Fetches the user row via the privileged findForAuth query and validates
+// it's usable for a write: not deleted, has a row.version (the version
+// column is a findForAuth contract field — absence is a schema bug, but
+// we still handle it gracefully rather than throwing past the burn).
+// Return type narrows `version` to `number` so the write-callsite doesn't
+// need a `?? 0` fallback — the guard lives here, not at every callsite.
+async function loadValidatedUser(
+  ctx: HandlerContext,
+  systemUser: SessionUser,
+  userId: string,
+): Promise<(AuthUserRow & { version: number }) | null> {
+  const me = parseAuthUserRow(
+    await ctx.queryAs(systemUser, UserQueries.findForAuth, { id: userId }),
+  );
+  if (!me || me.isDeleted || me.version === undefined) return null;
+  return { ...me, version: me.version };
+}
+
+// Loads the user's memberships and returns a prioritised tenant list.
+// Empty when the user has no memberships at all — the caller treats that
+// as invalid_token (a user without memberships can't own a usable auth
+// flow anyway, and a deterministic early-return is cleaner than
+// discovering it at write time).
+async function resolveStreamTenants(
+  ctx: HandlerContext,
+  systemUser: SessionUser,
+  me: AuthUserRow,
+): Promise<readonly TenantId[]> {
+  const memberships = (await ctx.queryAs(systemUser, "tenant:query:memberships", {
+    userId: me.id,
+  })) as Array<{ tenantId: TenantId }>;
+  return orderTenantsByPreference(memberships, me.lastActiveTenantId);
+}
+
+// Discriminated result for the write-across-tenants loop.
+//   all_conflicts → every candidate rejected with version_conflict →
+//                   token-level failure; caller returns invalidToken.
+//   hard_failure  → a non-conflict error that should bubble unchanged
+//                   (DB down, access denied, …); caller returns it as-is.
+type TenantWriteResult =
+  | { isSuccess: true }
+  | { isSuccess: false; reason: "all_conflicts" }
+  | { isSuccess: false; reason: "hard_failure"; failure: WriteFailure };
+
+// Attempts the update against each candidate stream. memberships-query
+// has no deterministic ORDER BY, so the matching stream is discovered by
+// attempt: version_conflict → try the next candidate, anything else →
+// bubble immediately so ops sees the real failure class.
+async function tryWriteAcrossTenants(
+  ctx: HandlerContext,
+  me: AuthUserRow & { version: number },
+  tenantOrder: readonly TenantId[],
+  changes: Record<string, unknown>,
+): Promise<TenantWriteResult> {
+  for (const tenantId of tenantOrder) {
+    const writeRes = await ctx.writeAs(createSystemUser(tenantId), UserHandlers.update, {
+      id: me.id,
+      version: me.version,
+      changes,
+    });
+    if (writeRes.isSuccess) return { isSuccess: true };
+    if (writeRes.error.code !== "version_conflict") {
+      return { isSuccess: false, reason: "hard_failure", failure: writeRes };
+    }
+  }
+  return { isSuccess: false, reason: "all_conflicts" };
+}