@cosmicdrift/kumiko-samples 0.338.0

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

@@ -0,0 +1,269 @@
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { MIN_HMAC_SECRET_LENGTH } from "./constants.js";
+import type { AuthMailLocale } from "./email-templates.js";
+import { changePasswordWrite } from "./handlers/change-password.write.js";
+import { createConfirmAccountUnlockHandler } from "./handlers/confirm-account-unlock.write.js";
+import { createInviteAcceptHandler } from "./handlers/invite-accept.write.js";
+import { createInviteAcceptWithLoginHandler } from "./handlers/invite-accept-with-login.write.js";
+import {
+  createInviteCreateHandler,
+  type InviteCreateOptions,
+} from "./handlers/invite-create.write.js";
+import { inviteInfoQuery } from "./handlers/invite-info.query.js";
+import { createInviteSignupCompleteHandler } from "./handlers/invite-signup-complete.write.js";
+import { createLoginHandler, type LoginHandlerOptions } from "./handlers/login.write.js";
+import { logoutWrite } from "./handlers/logout.write.js";
+import {
+  createRequestAccountUnlockHandler,
+  type RequestAccountUnlockOptions,
+} from "./handlers/request-account-unlock.write.js";
+import { createRequestEmailVerificationHandler } from "./handlers/request-email-verification.write.js";
+import { createRequestPasswordResetHandler } from "./handlers/request-password-reset.write.js";
+import { createResetPasswordHandler } from "./handlers/reset-password.write.js";
+import { selfRegistrationStatusQuery } from "./handlers/self-registration-status.query.js";
+import { createSignupConfirmHandler } from "./handlers/signup-confirm.write.js";
+import {
+  createSignupRequestHandler,
+  type SignupRequestOptions,
+} from "./handlers/signup-request.write.js";
+import { createVerifyEmailHandler } from "./handlers/verify-email.write.js";
+
+/**
+ * Env-vars contract for the `auth-email-password` feature.
+ *
+ * `JWT_SECRET` is read by `runProdApp` at boot to sign session JWTs.
+ * Apps mount this feature via `createAuthEmailPasswordFeature(opts)` and
+ * pass `jwtSecret` to `runProdApp` separately — declaring it here means
+ * `composeEnvSchema({ features: [authFeature, ...] })` flags a missing
+ * or short JWT_SECRET at the aggregated boot-validation stage instead of
+ * letting it surface as a JWT-decode-failure on first login.
+ *
+ * `JWT_ISSUER` is optional (Hono-JWT pins the `iss` claim when set).
+ */
+export const authEmailPasswordEnvSchema = z.object({
+  JWT_SECRET: z
+    .string()
+    .min(32, "JWT_SECRET must be ≥32 chars (HS256 minimum)")
+    .describe("Symmetric secret for signing session JWTs (HS256).")
+    .meta({ kumiko: { pulumi: { generator: "openssl rand -base64 48", secret: true } } }),
+  JWT_ISSUER: z
+    .string()
+    .min(1)
+    .optional()
+    .describe("Optional `iss` claim pinned on every minted JWT."),
+});
+
+// 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;
+  // App page that receives the magic-link; the handler appends `?token=…` and
+  // sends the mail via delivery (ctx.notify). No sendResetEmail callback — the
+  // app mounts `delivery` + a mail channel instead. Apps with language-in-path
+  // routing may pass a function to pick the right page for the resolved
+  // locale instead of a plain string.
+  readonly appUrl: string | ((locale: string) => string);
+  readonly appName?: string;
+  readonly locale?: AuthMailLocale;
+};
+
+// 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";
+  // App page that receives the magic-link; the handler appends `?token=…` and
+  // sends via delivery (ctx.notify). No sendVerificationEmail callback. Apps
+  // with language-in-path routing may pass a function to pick the right page
+  // for the resolved locale instead of a plain string.
+  readonly appUrl: string | ((locale: string) => string);
+  readonly appName?: string;
+  readonly locale?: AuthMailLocale;
+};
+
+// 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;
+
+// Account-Unlock Magic-Link (#1266). When set, registers the
+// request-account-unlock + confirm-account-unlock handlers — the
+// self-service escape hatch for the monotonic lockout counter (see
+// lockout-store.ts). Only meaningful paired with `accountLockout`, but
+// wired independently like passwordReset/emailVerification — no implicit
+// auto-enable, so apps without lockout don't get an unasked-for new
+// public endpoint.
+export type AccountUnlockOptions = RequestAccountUnlockOptions;
+
+export type AuthEmailPasswordOptions = {
+  // Second-factor gate. auth-mfa (if mounted) wires this in via
+  // mfaStatusCheckerFromFeature() at app-composition time — see
+  // LoginHandlerOptions.mfaStatusChecker for the contract it must satisfy.
+  readonly mfaStatusChecker?: LoginHandlerOptions["mfaStatusChecker"];
+  readonly passwordReset?: PasswordResetOptions;
+  readonly emailVerification?: EmailVerificationOptions;
+  readonly accountLockout?: AccountLockoutOptions;
+  readonly signup?: SignupOptions;
+  readonly invite?: InviteOptions;
+  readonly accountUnlock?: AccountUnlockOptions;
+};
+
+// 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 {
+  // ≥32 chars, symmetric to the JWT_SECRET env check: a short HMAC secret
+  // makes reset/verify tokens forgeable — that's account takeover, so the
+  // factory fails fast instead of trusting the caller.
+  if (opts.passwordReset && opts.passwordReset.hmacSecret.length < MIN_HMAC_SECRET_LENGTH) {
+    throw new Error(
+      `[auth-email-password] passwordReset.hmacSecret must be ≥${MIN_HMAC_SECRET_LENGTH} chars (HMAC-SHA256 token signing)`,
+    );
+  }
+  if (opts.emailVerification && opts.emailVerification.hmacSecret.length < MIN_HMAC_SECRET_LENGTH) {
+    throw new Error(
+      `[auth-email-password] emailVerification.hmacSecret must be ≥${MIN_HMAC_SECRET_LENGTH} chars (HMAC-SHA256 token signing)`,
+    );
+  }
+  if (opts.accountUnlock && opts.accountUnlock.hmacSecret.length < MIN_HMAC_SECRET_LENGTH) {
+    throw new Error(
+      `[auth-email-password] accountUnlock.hmacSecret must be ≥${MIN_HMAC_SECRET_LENGTH} chars (HMAC-SHA256 token signing)`,
+    );
+  }
+
+  const strictVerification =
+    opts.emailVerification !== undefined && (opts.emailVerification.mode ?? "strict") === "strict";
+
+  return defineFeature("auth-email-password", (r) => {
+    r.describe(
+      "Provides email+password authentication: the always-on handlers are `login`, `changePassword`, and `logout`; optional flows — password reset, email verification, magic-link self-signup, tenant invite, and account-unlock — are registered only when you pass their respective option objects (`passwordReset`, `emailVerification`, `signup`, `invite`, `accountUnlock`) to `createAuthEmailPasswordFeature(opts)`. All five magic-link flows dispatch their mail through the `delivery` feature via `ctx.notify`, so mounting any of them additionally requires `delivery`. Tokens are HMAC-signed (reset/verify/unlock) or opaque-random in Redis (signup/invite). `accountUnlock` is the self-service escape hatch for `accountLockout`'s monotonic failure-counter (#1266): confirming the mailed token clears the Redis lockout state without touching the user entity. Requires the `user` and `tenant` features, and declares `JWT_SECRET` (≥ 32 chars) in `authEmailPasswordEnvSchema` so a missing secret surfaces at boot validation rather than on the first login attempt.",
+    );
+    // kumiko-lint-ignore i18n-ui-strings uiHints labels are feature-registry metadata for the admin feature catalog, not yet wired to the i18n system, see #2312
+    r.uiHints({
+      displayLabel: "Auth \u00b7 Email + Password",
+      category: "identity",
+      recommended: true,
+      configurableOptions: [
+        { key: "passwordReset", label: "Password-Reset-Flow", type: "boolean", default: true },
+        {
+          key: "emailVerification",
+          label: "Email-Verification-Flow",
+          type: "boolean",
+          default: true,
+        },
+        { key: "signup", label: "Self-Signup-Flow", type: "boolean", default: false },
+        { key: "invite", label: "Tenant-Invite-Flow", type: "boolean", default: false },
+        { key: "accountUnlock", label: "Account-Unlock-Flow", type: "boolean", default: false },
+      ],
+    });
+    r.requires("user");
+    r.requires("tenant");
+    // All five magic-link flows (reset/verify/signup/invite/unlock) dispatch
+    // via ctx.notify → delivery must be mounted. Fail closed at boot instead
+    // of silently dropping the mail.
+    if (
+      opts.passwordReset ||
+      opts.emailVerification ||
+      opts.signup ||
+      opts.invite ||
+      opts.accountUnlock
+    ) {
+      r.requires("delivery");
+    }
+    r.envSchema(authEmailPasswordEnvSchema);
+
+    const handlers = {
+      login: r.writeHandler(
+        createLoginHandler({
+          strictEmailVerification: strictVerification,
+          accountLockout: opts.accountLockout,
+          mfaStatusChecker: opts.mfaStatusChecker,
+        }),
+      ),
+      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));
+    }
+
+    const queries = {
+      ...(opts.signup && {
+        signupRegistrationStatus: r.queryHandler(selfRegistrationStatusQuery),
+      }),
+      ...(opts.invite && {
+        inviteInfo: r.queryHandler(inviteInfoQuery),
+      }),
+    };
+
+    if (opts.signup) {
+      r.writeHandler(createSignupRequestHandler(opts.signup));
+      r.writeHandler(createSignupConfirmHandler());
+    }
+
+    if (opts.invite) {
+      r.writeHandler(createInviteCreateHandler(opts.invite));
+      r.writeHandler(createInviteAcceptHandler());
+      // Same gates as the `login` handler above (lockout, password,
+      // email-verified, account-status, MFA) — see invite-accept-with-login.write.ts.
+      r.writeHandler(
+        createInviteAcceptWithLoginHandler({
+          mfaStatusChecker: opts.mfaStatusChecker,
+          accountLockout: opts.accountLockout,
+          strictEmailVerification: strictVerification,
+        }),
+      );
+      r.writeHandler(createInviteSignupCompleteHandler());
+    }
+
+    if (opts.accountUnlock) {
+      r.writeHandler(createRequestAccountUnlockHandler(opts.accountUnlock));
+      r.writeHandler(createConfirmAccountUnlockHandler(opts.accountUnlock));
+    }
+
+    return { handlers, queries };
+  });
+}

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

@@ -0,0 +1,70 @@
+import {
+  access,
+  createSystemUser,
+  defineWriteHandler,
+  SYSTEM_TENANT_ID,
+} from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { hashPassword, verifyPassword } from "../../shared/index.js";
+import { UserHandlers, UserQueries } from "../../user/index.js";
+import { invalidCredentials } from "../errors.js";
+import { passwordSchema } from "../password-policy.js";
+
+// 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: passwordSchema,
+  }),
+  access: { roles: access.authenticated },
+  escapeHatch: {
+    reason:
+      "Reads the caller's own passwordHash (privileged-only field) via ctx.queryAs(SYSTEM, ...) " +
+      "and writes the new hash via ctx.writeAs(SYSTEM, user:update) — the caller's own " +
+      "identity can't reach either, field-access on passwordHash is privileged-only.",
+  },
+  // Payload carries the old and new password.
+  agent: { expose: false },
+  description:
+    "Replaces the signed-in caller's own password after re-checking the current one; use it for a self-service password change rather than the emailed reset flow.",
+  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; // @cast-boundary db-runner
+
+    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);
+
+    // The user aggregate is systemStream (#497): its event stream lives on
+    // SYSTEM_TENANT_ID deterministically. Pre-#497 scattered streams need the
+    // one-time backfillUserStreamTenants migration (#762).
+    const writer = createSystemUser(SYSTEM_TENANT_ID);
+
+    // 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(writer, UserHandlers.update, {
+      id: me.id,
+      version: me.version,
+      changes: { passwordHash: newHash },
+    });
+    if (!writeRes.isSuccess) return writeRes;
+
+    return { isSuccess: true, data: { kind: "password-changed" } };
+  },
+});

package/packages/bundled-features/src/auth-email-password/handlers/confirm-account-unlock.write.ts

@@ -0,0 +1,61 @@
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  InternalError,
+  UnprocessableError,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { AuthErrors } from "../constants.js";
+import { invalidUnlockToken } from "../errors.js";
+import { clearLockoutState } from "../lockout-store.js";
+import { verifyUnlockToken } from "../unlock-token.js";
+
+export type ConfirmAccountUnlockOptions = {
+  readonly hmacSecret: string;
+};
+
+// Confirm step of the unlock flow. Unlike reset/verify, there's no entity
+// write: the token's HMAC signature already proves it was minted for an
+// existing, non-deleted user (see request-account-unlock.write.ts's
+// findForAuth + extraSilentSkip), so there's no user to (re-)load or
+// validate here. Clearing the Redis lockout state is naturally idempotent
+// (DEL on an already-cleared/missing key is a no-op), so a replayed unlock
+// link within its TTL just re-clears — harmless, unlike reset which sets a
+// password. That's why this skips the single-use burn-store confirm-token-
+// flow.ts needs to protect a state-changing write.
+export function createConfirmAccountUnlockHandler(opts: ConfirmAccountUnlockOptions) {
+  return defineWriteHandler({
+    name: "confirm-account-unlock",
+    schema: z.object({
+      token: z.string().min(1),
+    }),
+    access: { roles: ["anonymous"] },
+    rateLimit: { per: "ip+handler", limit: 20, windowSeconds: 60 },
+    agent: { expose: false },
+    handler: async (event, ctx) => {
+      if (!opts.hmacSecret) {
+        return writeFailure(
+          new UnprocessableError(AuthErrors.unlockNotConfigured, {
+            i18nKey: "auth.errors.unlockNotConfigured",
+          }),
+        );
+      }
+      if (!ctx.redis) {
+        return writeFailure(
+          new InternalError({
+            message: "account-unlock requires ctx.redis to clear lockout state",
+          }),
+        );
+      }
+
+      // All verify failures (malformed / bad_signature / expired) fold into
+      // the same invalid_unlock_token error — a probing caller can't
+      // distinguish tampered from stale from random-string.
+      const verify = verifyUnlockToken(event.payload.token, opts.hmacSecret);
+      if (!verify.ok) return invalidUnlockToken();
+
+      await clearLockoutState(ctx.redis, verify.userId);
+      return { isSuccess: true, data: { kind: "account-unlocked" as const } };
+    },
+  });
+}

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

@@ -0,0 +1,148 @@
+// 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. Apply the handler-specific `changes` on the user's SYSTEM stream
+//   5. 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.
+//
+// The user aggregate is systemStream (#497): its event stream lives on
+// SYSTEM_TENANT_ID deterministically, so the write targets exactly one
+// stream. The former membership-probing (`tryWriteAcrossTenants`) existed
+// for pre-#497 scattered streams; those need the one-time
+// backfillUserStreamTenants migration (#762) — probing them stopped working
+// the moment the executor's stream choke-point landed anyway.
+
+import {
+  createSystemUser,
+  declareEscapeHatch,
+  type HandlerContext,
+  type SessionUser,
+  SYSTEM_TENANT_ID,
+  type WriteResult,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import type { Redis } from "ioredis";
+import { burnToken, unburnToken } from "../../shared/index.js";
+import { UserHandlers, UserQueries } from "../../user/index.js";
+import type { AuthUserRow } from "../auth-user-row.js";
+import { parseAuthUserRow } from "../auth-user-row.js";
+
+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, version conflict on the stream). 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. 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>> {
+  declareEscapeHatch({
+    reason:
+      "writes the confirming user's row via UserHandlers.update on the caller's handler context, using a SYSTEM_TENANT-scoped identity; the calling handler declares its own escapeHatch",
+  });
+  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 changes = await spec.buildChanges(me);
+    const writeRes = await ctx.writeAs(systemUser, UserHandlers.update, {
+      id: me.id,
+      version: me.version,
+      changes,
+    });
+    if (writeRes.isSuccess) {
+      committed = true;
+      return { isSuccess: true, data: spec.successData };
+    }
+    // version_conflict = concurrent modification (or an un-migrated pre-#497
+    // stream, see header) → token-level failure. Anything else (DB down,
+    // access denied) bubbles unchanged so ops sees the real failure class.
+    if (writeRes.error.code === "version_conflict") return spec.invalidToken();
+    return writeRes;
+  } 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);
+    }
+  }
+}
+
+// Fetches the user row via the privileged findForAuth query and validates
+// it's usable for a write: not deleted, has a row.version >= 1 (a row
+// without any event stream — e.g. inserted straight into read_users — must
+// not be confirmable: the write would otherwise seed a fresh stream with a
+// bare user.updated). 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> {
+  declareEscapeHatch({
+    reason:
+      "reads the confirming user's row via UserQueries.findForAuth on the caller's handler context, using a SYSTEM_TENANT-scoped identity; the calling handler declares its own escapeHatch",
+  });
+  const me = parseAuthUserRow(
+    await ctx.queryAs(systemUser, UserQueries.findForAuth, { id: userId }),
+  );
+  if (!me || me.isDeleted || me.version === undefined || me.version < 1) return null;
+  return { ...me, version: me.version };
+}