@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

package/src/api/auth-routes.ts

@@ -1,8 +1,10 @@
+import { createHash } from "node:crypto";
 import type { Context } from "hono";
 import { Hono } from "hono";
 import { deleteCookie, setCookie } from "hono/cookie";
+import type Redis from "ioredis";
 import { z } from "zod";
-import { stripForbiddenMembershipRoles } from "../engine/membership-roles";
+import { buildSessionRoles } from "../engine/membership-roles";
 import { createSystemUser } from "../engine/system-user";
 import { type SessionUser, SYSTEM_TENANT_ID, type TenantId } from "../engine/types";
 import { NotFoundError } from "../errors";
@@ -15,16 +17,11 @@ import {
   type AuthSessionStatus,
   CSRF_COOKIE_NAME,
   getUser,
+  type TokenVerifier,
 } from "./auth-middleware";
 import type { JwtHelper } from "./jwt";
 import { generateToken } from "./tokens";
 
-// Cookie lifetime must track the JWT's exp claim — both are issued together,
-// both reference the same session. jwt.ts's createJwtHelper hardcodes
-// setExpirationTime("24h"); if that ever becomes configurable this constant
-// follows it.
-const JWT_TTL_SECONDS = 24 * 60 * 60;
-
 // Resolves the Secure cookie flag. Locked off in dev/test so Playwright
 // against http://localhost:… can actually receive the cookie. Production
 // flips it on — browsers drop Secure cookies on http, so a misconfigured
@@ -46,6 +43,10 @@ function setAuthCookies(
     csrfToken: string;
     sameSite: "lax" | "strict";
     domain?: string | undefined;
+    // Cookie lifetime must track the JWT's exp claim — both are issued
+    // together, both reference the same session. Callers pass jwt.ttlSeconds
+    // so the two never drift apart.
+    ttlSeconds: number;
   },
 ): void {
   const sameSite = opts.sameSite === "strict" ? "Strict" : "Lax";
@@ -53,7 +54,7 @@ function setAuthCookies(
     secure: cookieSecure(),
     sameSite,
     path: "/",
-    maxAge: JWT_TTL_SECONDS,
+    maxAge: opts.ttlSeconds,
     ...(opts.domain !== undefined && { domain: opts.domain }),
   } as const;
 
@@ -96,6 +97,36 @@ const LoginBody = z.object({
   password: z.string(),
 });
 
+// Body schema for POST /auth/mfa/verify. challengeToken is opaque to the
+// framework — it's minted and verified entirely by the mfaVerifyHandler
+// (auth-mfa owns the token format, TOTP/recovery-code check, and the
+// brute-force cap). code covers both 6-digit TOTP and XXXX-XXXX recovery
+// codes (9 chars incl. the dash).
+const MfaVerifyBody = z.object({
+  challengeToken: z.string().min(1),
+  code: z.string().min(6).max(9),
+});
+
+// Body schema for POST /auth/mfa/preauth-enable-start. preauthSetupToken is
+// opaque to the framework — minted by login.write.ts's mfaStatusChecker
+// (auth-mfa) when enforcement policy blocks an unenrolled user, verified
+// entirely by the mfaPreauthEnableStartHandler. accountLabel is
+// client-supplied (the email the user just typed at login) for the
+// otpauth:// URI, mirroring auth-mfa's own enable-start.write.ts.
+const MfaPreauthEnableStartBody = z.object({
+  preauthSetupToken: z.string().min(1),
+  accountLabel: z.string().min(1).max(200),
+});
+
+// Body schema for POST /auth/mfa/preauth-confirm. setupToken is opaque to
+// the framework — minted by the mfaPreauthEnableStartHandler, verified
+// entirely by the mfaPreauthConfirmHandler. code is TOTP-only (no recovery
+// codes at enrollment time), mirroring auth-mfa's own enable-confirm.write.ts.
+const MfaPreauthConfirmBody = z.object({
+  setupToken: z.string().min(1),
+  code: z.string().length(6),
+});
+
 const ResetPasswordBody = z.object({
   token: z.string().min(1),
   newPassword: z.string().min(8).max(200),
@@ -187,6 +218,12 @@ export type SessionCreator = (user: SessionUser, meta: SessionMetadata) => Promi
 // there's nothing to revoke.
 export type SessionRevoker = (sid: string) => Promise<void>;
 
+// Mass-revoke every live session for a user. Used by password-change and
+// "sign out everywhere" (sessions feature) and by auth-foundation's
+// SessionStore extension point — canonical home so both can re-export
+// the same type instead of restating it.
+export type SessionMassRevoker = (userId: string) => Promise<number>;
+
 // Status reported by the session-store to the auth-middleware. The concrete
 // type lives on auth-middleware to keep the tight coupling visible there;
 // auth-routes just re-uses the alias for the AuthRoutesConfig surface.
@@ -216,6 +253,70 @@ export type AuthRoutesConfig = {
   // Rate-limit for POST /auth/login. Defaults to in-memory 10/5min per
   // (ip + email) bucket. Pass `null` to disable (tests, trusted networks).
   loginRateLimit?: LoginRateLimiter | null;
+  // Optional: qualified write handler completing a two-step (password +
+  // TOTP/recovery-code) login. When set, POST /auth/mfa/verify dispatches
+  // { challengeToken, code } to this handler with a guest identity. On
+  // success the handler must return { kind: "mfa-verify-success", session:
+  // SessionUser } and the route mints a JWT exactly like /auth/login.
+  // Everything MFA-specific (challenge-token format, TOTP/recovery check,
+  // the per-account brute-force cap) is owned by the handler — the
+  // framework stays as agnostic about it as it is about password hashing.
+  mfaVerifyHandler?: string;
+  // Maps mfaVerifyHandler error codes to HTTP status codes, same pattern as
+  // loginErrorStatusMap. Unknown errors default to the error's own httpStatus.
+  mfaVerifyErrorStatusMap?: Readonly<Record<string, number>>;
+  // Rate-limit for POST /auth/mfa/verify, keyed by client IP. Defaults to
+  // in-memory 10/5min. Pass `null` to disable. This is DELIBERATELY separate
+  // from loginRateLimit: unlike /auth/login (a dispatcher write-handler
+  // route that could inherit a handler-level rateLimit), this is a
+  // framework route with no handler.rateLimit to fall back on — and it's
+  // also separate from any per-account brute-force cap the mfaVerifyHandler
+  // enforces itself (see its own doc comment) — IP-scoped abuse protection
+  // and per-account guessing protection are different threats, neither
+  // substitutes for the other.
+  mfaVerifyRateLimit?: LoginRateLimiter | null;
+  // Optional: qualified write handler generating a TOTP secret + QR for a
+  // user blocked at login by MFA enforcement but not yet enrolled (see
+  // mfaStatusChecker's setupRequired branch, auth-mfa). When set, POST
+  // /auth/mfa/preauth-enable-start dispatches { preauthSetupToken,
+  // accountLabel } to this handler with a guest identity — no session is
+  // minted, the response is just { setupToken, otpauthUri, recoveryCodes }
+  // (same shape as auth-mfa's own enable-start.write.ts).
+  mfaPreauthEnableStartHandler?: string;
+  // Maps mfaPreauthEnableStartHandler error codes to HTTP status codes,
+  // same pattern as mfaVerifyErrorStatusMap.
+  mfaPreauthEnableStartErrorStatusMap?: Readonly<Record<string, number>>;
+  // Rate-limit for POST /auth/mfa/preauth-enable-start, keyed by client IP.
+  // Defaults to in-memory 10/5min. Pass `null` to disable. This route does
+  // NOT inherit the generic L2 authEndpointRateLimit on /api/auth/* by
+  // default (that's opt-in per-app via runProdApp's rateLimit.auth), and a
+  // preauthSetupToken is valid for the full setup-token TTL and not
+  // single-use until preauth-confirm burns it — an unrate-limited replay
+  // means every hit re-derives a fresh TOTP secret + 8 argon2id recovery-
+  // code hashes (recovery-codes.ts, Promise.all), a memory-hard CPU
+  // amplifier reachable from a single stolen/leaked token.
+  mfaPreauthEnableStartRateLimit?: LoginRateLimiter | null;
+  // Optional: qualified write handler completing the enrollment started by
+  // mfaPreauthEnableStartHandler — takes the secret-carrying setupToken
+  // from that step plus a TOTP code. When set, POST /auth/mfa/preauth-
+  // confirm dispatches { setupToken, code } to this handler with a guest
+  // identity. On success the handler must return { kind: "mfa-preauth-
+  // confirm-success", session: SessionUser } and the route mints a JWT
+  // exactly like /auth/mfa/verify — this call both finishes enrollment AND
+  // completes the login that was blocked by mfa-setup-required. Unlike
+  // mfaPreauthEnableStartHandler, THIS is the per-account TOTP-guessing
+  // surface the enable-start doc comment refers to — the handler owns its
+  // own brute-force cap (mirroring mfaVerifyHandler's), and this route adds
+  // its own IP-scoped rate limiter for the same reason mfaVerifyRateLimit
+  // exists separately from loginRateLimit.
+  mfaPreauthConfirmHandler?: string;
+  // Maps mfaPreauthConfirmHandler error codes to HTTP status codes, same
+  // pattern as mfaVerifyErrorStatusMap.
+  mfaPreauthConfirmErrorStatusMap?: Readonly<Record<string, number>>;
+  // Rate-limit for POST /auth/mfa/preauth-confirm, keyed by client IP. Same
+  // reasoning as mfaVerifyRateLimit — defaults to in-memory 10/5min, pass
+  // `null` to disable.
+  mfaPreauthConfirmRateLimit?: LoginRateLimiter | null;
   // Session-lifecycle callbacks. When both are wired the JWT carries a `jti`
   // (sid) and the server can revoke individual sessions (logout, compromise,
   // password-change). When unwired the framework issues plain stateless JWTs.
@@ -228,10 +329,19 @@ export type AuthRoutesConfig = {
   // at login, check it here on every request. Leaving this empty disables
   // the revocation path — old JWTs stay valid until they expire naturally.
   sessionChecker?: SessionChecker;
-  // When true, a JWT WITHOUT a sid is rejected. Use during deploy-rollouts
-  // once all fresh JWTs emit a sid and the legacy stateless tokens are
-  // expected to have expired. Default false keeps old tokens working.
-  sessionStrictMode?: boolean;
+  // Resolves bearer tokens (any registered auth-foundation `tokenVerifier`
+  // provider — PAT today, future JWT-provider), consulted BEFORE jwt.verify.
+  // Wired by run-prod-app/run-dev-app when at least one provider feature is
+  // mounted; unwired = no non-JWT bearer auth.
+  tokenVerifier?: TokenVerifier;
+  // Per-token request-rate limiter for PAT-authenticated requests, keyed by
+  // the token id (SessionUser.pat.tokenId). Cookie/JWT requests are unaffected.
+  // Reuses the LoginRateLimiter shape (a generic keyed check/reset limiter).
+  // Wired by run-prod-app when the PAT feature is mounted; unwired = no PAT
+  // rate limiting.
+  patRateLimiter?: LoginRateLimiter;
+  // Tenant-lifecycle 410 gate — wired by tenant-lifecycle / run-prod-app.
+  resolveTenantLifecycleStatus?: import("./auth-middleware").TenantLifecycleStatusResolver;
   // Password-reset flow. When wired, POST /auth/request-password-reset and
   // POST /auth/reset-password are mounted as public routes. The framework
   // dispatches to the feature-level handlers (authoring QNs typically come
@@ -242,6 +352,12 @@ export type AuthRoutesConfig = {
   passwordReset?: PasswordResetConfig;
   // Email-verification flow. Symmetric to passwordReset.
   emailVerification?: EmailVerificationConfig;
+  // Account-unlock flow (#1266). When wired, POST
+  // /auth/request-account-unlock + /auth/confirm-account-unlock are
+  // mounted as public routes. Confirm needs no extra body field
+  // (token-only, like email-verification) — the handler only clears the
+  // Redis lockout state, no entity write.
+  accountUnlock?: AccountUnlockConfig;
   // Self-Signup (Magic-Link). Wenn wired, mountet POST
   // /auth/signup-request + /auth/signup-confirm. Confirm returnt JWT-
   // Cookie + Session-Body wie login.
@@ -295,6 +411,20 @@ export type AuthRoutesConfig = {
   // subdomain can then forge authenticated state-changing requests. Prefer
   // setting `allowedOrigins`.
   unsafeSkipOriginCheck?: boolean;
+  // Number of trusted reverse-proxy hops between the client and this
+  // process that APPEND (not overwrite) their peer address to
+  // `x-forwarded-for` (e.g. nginx `$proxy_add_x_forwarded_for`). Used to
+  // derive the client IP for every auth rate-limiter (login, mfa-verify,
+  // preauth-enable-start, preauth-confirm) and for requestMeta's session
+  // IP — kumiko-framework#1539. Default 0 = legacy behavior, trust the
+  // first XFF entry (or x-real-ip) unconditionally; spoofable by design,
+  // kept as the default so unconfigured deployments don't regress into a
+  // shared "unknown" bucket (mfa-verify/preauth-confirm key on bare IP, no
+  // email composite — collapsing everyone into one bucket is a DoS worse
+  // than the spoofing hole). Set this to your real proxy hop count (1 for
+  // a single ingress/reverse-proxy, 2 for edge-LB + ingress, etc.) to close
+  // the hole; see clientIpOf's doc comment for the extraction algorithm.
+  trustedProxyHops?: number;
 };
 
 export type PasswordResetConfig = {
@@ -312,6 +442,13 @@ export type EmailVerificationConfig = {
   confirmHandler: string;
 };
 
+export type AccountUnlockConfig = {
+  requestHandler: string;
+  // Token-only body (mirrors EmailVerificationConfig) — no entity write, so
+  // there's no newPassword-equivalent field.
+  confirmHandler: string;
+};
+
 // Tenant-Invite Magic-Link. Drei Accept-Branches für klare Separation:
 //   - acceptHandler: logged-in User akzeptiert via JWT (Branch 1)
 //   - acceptWithLoginHandler: anon User mit existing email (Branch 2)
@@ -342,15 +479,73 @@ export type SignupConfig = {
   confirmHandler: string;
 };
 
+// Derives the caller IP from proxy headers, single source for the
+// rate-limiter keys below and requestMeta. kumiko-framework#1523/#1522/#1539:
+// `x-forwarded-for` is attacker-controlled unless we know how many trusted
+// proxy hops sit between the client and this process — `trustedProxyHops`
+// (AuthRoutesConfig) is that count.
+//
+//   hops === 0 (default): legacy behavior — trust the first XFF entry (or
+//   x-real-ip) at face value. Kept as the default so unconfigured
+//   deployments don't regress: collapsing everyone into a single "unknown"
+//   bucket would turn mfa-verify/preauth-confirm's pure-IP-keyed limiter
+//   into a one-request-locks-out-everyone DoS, which is worse than the
+//   spoofing hole this issue is about. Apps behind a proxy MUST set this to
+//   close the hole — see AuthRoutesConfig.trustedProxyHops.
+//
+//   hops >= 1: each trusted proxy appends (not overwrites) its peer address
+//   to XFF (e.g. nginx `$proxy_add_x_forwarded_for`), so the last `hops`
+//   entries are proxy-supplied and everything before them — including the
+//   real client — sits at `entries[length - hops]`. Anything the client
+//   itself prepended lands further left and is ignored. If the header has
+//   fewer entries than `hops`, the proxy chain is shorter than configured
+//   (misconfiguration or a bypassed hop) — fall back to "unknown" rather
+//   than trusting a shorter, potentially attacker-controlled chain.
+//   x-real-ip is NOT consulted in this branch: unlike XFF it has no
+//   standardized hop-count semantics, so there's no safe way to validate it
+//   against a configured hop count.
+//
+// Callers that need a hard boundary regardless of this config
+// (preauth-enable-start) additionally key on something the caller can't
+// freely choose (see preauthTokenKeyOf below).
+function clientIpOf(
+  c: { req: { header(name: string): string | undefined } },
+  trustedProxyHops = 0,
+): string {
+  if (trustedProxyHops <= 0) {
+    return (
+      c.req.header("x-forwarded-for")?.split(",")[0]?.trim() ??
+      c.req.header("x-real-ip") ??
+      "unknown"
+    );
+  }
+  const entries = (c.req.header("x-forwarded-for") ?? "")
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+  if (entries.length < trustedProxyHops) {
+    return "unknown";
+  }
+  return entries[entries.length - trustedProxyHops] ?? "unknown";
+}
+
+// Second rate-limit axis for preauth-enable-start: unlike the IP, a
+// preauthSetupToken isn't freely choosable by the attacker (it's minted by
+// login.write.ts), so hashing it into a bucket key still caps the replay
+// even when the IP-based bucket is bypassed via header rotation.
+function preauthTokenKeyOf(token: string): string {
+  return `preauth-token:${createHash("sha256").update(token).digest("hex")}`;
+}
+
 // Extract `ip` and `user-agent` for the sessionCreator.
 // Hono's `c.req.header(...)` returns undefined for missing headers; we coerce
 // them to "unknown" rather than throwing because auth-routes are a public
 // surface and we don't want header-sniffing bugs to break login.
-function requestMeta(c: { req: { header(name: string): string | undefined } }): SessionMetadata {
-  const ip =
-    c.req.header("x-forwarded-for")?.split(",")[0]?.trim() ??
-    c.req.header("x-real-ip") ??
-    "unknown";
+function requestMeta(
+  c: { req: { header(name: string): string | undefined } },
+  trustedProxyHops = 0,
+): SessionMetadata {
+  const ip = clientIpOf(c, trustedProxyHops);
   const userAgent = c.req.header("user-agent") ?? "unknown";
   return { ip, userAgent };
 }
@@ -416,6 +611,59 @@ export function createInMemoryLoginRateLimiter(
   };
 }
 
+// Redis-backed sibling of createInMemoryLoginRateLimiter — same fixed-window
+// semantics (count <= maxAttempts allows, window anchored on first hit), but
+// shared across replicas via INCR/PEXPIRE instead of an in-process Map.
+// runProdApp defaults to this: an in-memory limiter only rate-limits within
+// a single instance, so a multi-replica prod deployment would silently give
+// each replica its own bucket. namespace separates the login-key keyspace
+// from the mfa-verify one (they share the same LoginRateLimiter shape but
+// key on different values).
+// Fail-closed on Redis outage, unlike the in-memory limiter (which never
+// throws): `check`/`reset` propagate any Redis error, so callers 500
+// instead of falling back to unlimited attempts. Deliberate — Redis is
+// already required infra for a multi-replica deployment, and for a
+// security-relevant limiter "briefly unavailable" should read as "briefly
+// down", not "briefly unlimited".
+export function createRedisLoginRateLimiter(
+  redis: Redis,
+  maxAttempts = 10,
+  windowMs = 5 * 60_000,
+  namespace = "login",
+): LoginRateLimiter {
+  const prefix = `kumiko:auth:ratelimit:${namespace}:`;
+
+  return {
+    async check(key) {
+      const redisKey = `${prefix}${key}`;
+      // INCR then PEXPIRE was two round-trips: a crash/network blip between
+      // them (only possible right after count===1, when the key is fresh)
+      // left the key permanently without a TTL — the window never resets,
+      // the counter only grows, and the bucket is locked out until an
+      // operator manually resets/deletes the key. One atomic eval closes
+      // the gap: the TTL is set in the same script invocation that creates
+      // the key, so no observer (including a crash) can see count===1
+      // without the expiry already applied. The `PTTL < 0` branch also
+      // heals keys that already exist without a TTL from before this fix
+      // shipped (PTTL returns -1 for "no expiry set, key exists") — without
+      // it, those pre-existing keys would grow forever with no way back to
+      // a normal window.
+      const count = (await redis.eval(
+        `local c = redis.call('INCR', KEYS[1])
+         if c == 1 or redis.call('PTTL', KEYS[1]) < 0 then redis.call('PEXPIRE', KEYS[1], ARGV[1]) end
+         return c`,
+        1,
+        redisKey,
+        windowMs,
+      )) as number;
+      return count <= maxAttempts;
+    },
+    async reset(key) {
+      await redis.del(`${prefix}${key}`);
+    },
+  };
+}
+
 export function createAuthRoutes(
   dispatcher: Dispatcher,
   jwt: JwtHelper,
@@ -427,6 +675,44 @@ export function createAuthRoutes(
   // working. High-security apps can opt into "strict" — see AuthRoutesConfig.
   const cookieSameSite = config.cookieSameSite ?? "lax";
   const cookieDomain = config.cookieDomain;
+  // Single hop-count-aware IP getter for every rate-limit call site below —
+  // see AuthRoutesConfig.trustedProxyHops / clientIpOf's doc comment. Fail
+  // loud on a non-finite/negative value rather than letting it silently
+  // reach clientIpOf, where NaN/negative behaves like "chain too short"
+  // and collapses every request into the shared "unknown" bucket.
+  if (
+    config.trustedProxyHops !== undefined &&
+    (!Number.isInteger(config.trustedProxyHops) || config.trustedProxyHops < 0)
+  ) {
+    throw new Error(
+      `createAuthRoutes: trustedProxyHops must be a non-negative integer, got ${config.trustedProxyHops}.`,
+    );
+  }
+  const trustedProxyHops = config.trustedProxyHops ?? 0;
+  const getClientIp = (c: Context): string => clientIpOf(c, trustedProxyHops);
+
+  // Shared tail of every route that ends a request logged-in: create the
+  // session record (if wired), sign the JWT, set the auth+csrf cookies. Was
+  // duplicated 5x (login/signup-confirm/invite-accept-with-login/invite-
+  // signup-complete/switch-tenant) — extracted so a 6th caller (mfa-verify)
+  // doesn't grow it to 6.
+  async function mintSessionAndRespond(c: Context, session: SessionUser): Promise<string> {
+    let sessionForJwt = session;
+    if (config.sessionCreator) {
+      const sid = await config.sessionCreator(session, requestMeta(c, trustedProxyHops));
+      sessionForJwt = { ...session, sid };
+    }
+    const token = await jwt.sign(sessionForJwt);
+    const csrfToken = generateToken();
+    setAuthCookies(c, {
+      token,
+      csrfToken,
+      sameSite: cookieSameSite,
+      domain: cookieDomain,
+      ttlSeconds: jwt.ttlSeconds,
+    });
+    return token;
+  }
 
   // POST /auth/login — public endpoint (bypasses auth middleware via PUBLIC_API_PATHS).
   // The configured login handler authenticates and returns a SessionUser;
@@ -448,13 +734,7 @@ export function createAuthRoutes(
       }
       const body = parsed.data;
 
-      // Client IP derivation is shared between rate-limit check and reset,
-      // so compute once. Falls back to "unknown" when no proxy header is
-      // present — consistent bucket for direct-to-server test setups.
-      const clientIp =
-        c.req.header("x-forwarded-for")?.split(",")[0]?.trim() ??
-        c.req.header("x-real-ip") ??
-        "unknown";
+      const clientIp = getClientIp(c);
       const rateLimitKey = `${clientIp}|${body.email.toLowerCase()}`;
 
       if (rateLimiter) {
@@ -481,32 +761,253 @@ export function createAuthRoutes(
         return c.json({ isSuccess: false, error: result.error }, status);
       }
 
-      // @cast-boundary engine-payload — generic dispatcher.write result for auth-session handler
-      const data = result.data as { kind: "auth-session"; session: SessionUser };
-
-      // Session creation (optional). Creating the session BEFORE signing the
-      // JWT is load-bearing: the sid must exist on the server before the
-      // token that references it can be handed out, otherwise a fast client
-      // could arrive at an auth-middleware check before the insert commits.
-      let sessionForJwt: SessionUser = data.session;
-      if (config.sessionCreator) {
-        const sid = await config.sessionCreator(data.session, requestMeta(c));
-        sessionForJwt = { ...data.session, sid };
+      // @cast-boundary engine-payload — generic dispatcher.write result for
+      // login. Three possible shapes: a straight session, an MFA challenge
+      // when the loginHandler is wired with a second-factor gate, or a hard
+      // block when enforcement policy demands MFA but the user never
+      // enrolled (see auth-mfa's config.ts for why this has no in-band
+      // recovery yet).
+      const data = result.data as
+        | { kind: "auth-session"; session: SessionUser }
+        | { kind: "mfa-challenge"; challengeToken: string }
+        | { kind: "mfa-setup-required"; preauthSetupToken: string };
+
+      if (data.kind === "mfa-setup-required") {
+        // No session, no challenge — the client must show an
+        // enrollment-required message. No rate-limit reset (same reasoning
+        // as the mfa-challenge branch below).
+        return c.json({
+          isSuccess: true,
+          mfaSetupRequired: true,
+          preauthSetupToken: data.preauthSetupToken,
+        });
       }
 
-      const token = await jwt.sign(sessionForJwt);
+      if (data.kind === "mfa-challenge") {
+        // No session minted yet — no cookies, no token. The client must
+        // complete /auth/mfa/verify with this token before it gets either.
+        // Rate-limit counter is NOT reset here: a "correct password, wrong/
+        // no TOTP yet" outcome hasn't proven the caller owns the account any
+        // more than a wrong password did.
+        return c.json({ isSuccess: true, mfaRequired: true, challengeToken: data.challengeToken });
+      }
+
+      // Session creation (optional) + JWT sign + cookies — see
+      // mintSessionAndRespond. Creating the session BEFORE signing the JWT
+      // is load-bearing: the sid must exist on the server before the token
+      // that references it can be handed out, otherwise a fast client could
+      // arrive at an auth-middleware check before the insert commits.
+      const token = await mintSessionAndRespond(c, data.session);
 
       if (rateLimiter) {
         await rateLimiter.reset(rateLimitKey);
       }
 
-      // Cookie transport (web): set HttpOnly auth cookie + JS-readable csrf
-      // cookie. Bearer transport (native) reads the token from the body
-      // below — the token is returned for both, so a Bearer client that
-      // ignores Set-Cookie keeps working without any server-side knowledge
-      // of which transport this client will use next.
-      const csrfToken = generateToken();
-      setAuthCookies(c, { token, csrfToken, sameSite: cookieSameSite, domain: cookieDomain });
+      return c.json({
+        isSuccess: true,
+        token,
+        user: { id: data.session.id, tenantId: data.session.tenantId, roles: data.session.roles },
+      });
+    });
+  }
+
+  // POST /auth/mfa/verify — completes a two-step login. Mirrors /auth/login
+  // structurally (public, GUEST_USER dispatch, mintSessionAndRespond on
+  // success) but with its OWN rate limiter (mfaVerifyRateLimit) — this route
+  // never goes through a dispatcher write-handler's own rateLimit config,
+  // so without this it would have NO rate limiting at all. Per-account
+  // brute-force protection (capping wrong-code guesses against one
+  // still-valid challenge token) is a separate mechanism the handler itself
+  // owns — see AuthRoutesConfig.mfaVerifyHandler's doc comment.
+  if (config.mfaVerifyHandler) {
+    const mfaVerifyQn = config.mfaVerifyHandler;
+    const statusMap = config.mfaVerifyErrorStatusMap ?? {};
+    const rateLimiter =
+      config.mfaVerifyRateLimit === null
+        ? null
+        : (config.mfaVerifyRateLimit ?? createInMemoryLoginRateLimiter());
+
+    api.post(Routes.authMfaVerify, async (c) => {
+      const raw = await c.req.json().catch(() => null);
+      const parsed = MfaVerifyBody.safeParse(raw);
+      if (!parsed.success) {
+        return c.json({ isSuccess: false, error: "invalid_body" }, 400);
+      }
+      const body = parsed.data;
+
+      const clientIp = getClientIp(c);
+
+      if (rateLimiter) {
+        const allowed = await rateLimiter.check(clientIp);
+        if (!allowed) {
+          return c.json({ isSuccess: false, error: "rate_limited" }, 429);
+        }
+      }
+
+      const result = await dispatcher.write(mfaVerifyQn, body, GUEST_USER);
+
+      if (!result.isSuccess) {
+        // @cast-boundary error-details — KumikoError.details shape is per-error
+        const reason =
+          (result.error.details as { reason?: string } | undefined)?.reason ?? result.error.code;
+        // @cast-boundary engine-payload — statusMap value union narrows to the http-status union
+        const status = (statusMap[reason] ?? result.error.httpStatus) as
+          | 400
+          | 401
+          | 403
+          | 422
+          | 429
+          | 500;
+        return c.json({ isSuccess: false, error: result.error }, status);
+      }
+
+      // @cast-boundary engine-payload — generic dispatcher.write result for mfa-verify handler
+      const data = result.data as { kind: "mfa-verify-success"; session: SessionUser };
+
+      const token = await mintSessionAndRespond(c, data.session);
+
+      if (rateLimiter) {
+        await rateLimiter.reset(clientIp);
+      }
+
+      return c.json({
+        isSuccess: true,
+        token,
+        user: { id: data.session.id, tenantId: data.session.tenantId, roles: data.session.roles },
+      });
+    });
+  }
+
+  // POST /auth/mfa/preauth-enable-start — lets a user blocked at login by
+  // MFA enforcement (mfa-setup-required) generate a TOTP secret + QR
+  // without a session, using the preauthSetupToken login.write.ts issued.
+  // No JWT is minted here (unlike /auth/login and /auth/mfa/verify) — the
+  // handler's response carries a secret-bearing setupToken that a later
+  // pre-auth confirm step (the same shape auth-mfa's own enable-confirm
+  // consumes) verifies. Rate-limited like mfaVerifyRateLimit/
+  // mfaPreauthConfirmRateLimit — a preauthSetupToken is valid and
+  // not-single-use for its whole TTL, so without this cap a replay is a
+  // memory-hard CPU amplifier (see AuthRoutesConfig doc comment).
+  if (config.mfaPreauthEnableStartHandler) {
+    const mfaPreauthEnableStartQn = config.mfaPreauthEnableStartHandler;
+    const statusMap = config.mfaPreauthEnableStartErrorStatusMap ?? {};
+    const rateLimiter =
+      config.mfaPreauthEnableStartRateLimit === null
+        ? null
+        : (config.mfaPreauthEnableStartRateLimit ?? createInMemoryLoginRateLimiter());
+
+    api.post(Routes.authMfaPreauthEnableStart, async (c) => {
+      const raw = await c.req.json().catch(() => null);
+      const parsed = MfaPreauthEnableStartBody.safeParse(raw);
+      if (!parsed.success) {
+        return c.json({ isSuccess: false, error: "invalid_body" }, 400);
+      }
+      const body = parsed.data;
+
+      const clientIp = getClientIp(c);
+
+      if (rateLimiter) {
+        const allowed = await rateLimiter.check(clientIp);
+        if (!allowed) {
+          return c.json({ isSuccess: false, error: "rate_limited" }, 429);
+        }
+        // Second axis, independent of the IP-derived bucket above: the
+        // preauthSetupToken is minted by login.write.ts and not freely
+        // choosable, so this cap survives an attacker rotating
+        // x-forwarded-for to bypass the IP bucket (kumiko-framework#1522).
+        const tokenAllowed = await rateLimiter.check(preauthTokenKeyOf(body.preauthSetupToken));
+        if (!tokenAllowed) {
+          return c.json({ isSuccess: false, error: "rate_limited" }, 429);
+        }
+      }
+
+      const result = await dispatcher.write(mfaPreauthEnableStartQn, body, GUEST_USER);
+
+      if (!result.isSuccess) {
+        // @cast-boundary error-details — KumikoError.details shape is per-error
+        const reason =
+          (result.error.details as { reason?: string } | undefined)?.reason ?? result.error.code;
+        // @cast-boundary engine-payload — statusMap value union narrows to the http-status union
+        const status = (statusMap[reason] ?? result.error.httpStatus) as
+          | 400
+          | 401
+          | 403
+          | 422
+          | 429
+          | 500;
+        return c.json({ isSuccess: false, error: result.error }, status);
+      }
+
+      // @cast-boundary engine-payload — generic dispatcher.write result for
+      // the preauth-enable-start handler
+      const data = result.data as {
+        setupToken: string;
+        otpauthUri: string;
+        recoveryCodes: readonly string[];
+      };
+
+      return c.json({ isSuccess: true, ...data });
+    });
+  }
+
+  // POST /auth/mfa/preauth-confirm — completes both the enrollment started
+  // by preauth-enable-start AND the login mfa-setup-required blocked.
+  // Mirrors /auth/mfa/verify structurally (public, GUEST_USER dispatch,
+  // mintSessionAndRespond on success) with its OWN rate limiter
+  // (mfaPreauthConfirmRateLimit) — same reasoning as mfaVerifyRateLimit.
+  // Per-account brute-force protection (capping wrong-code guesses against
+  // one still-valid setupToken) is owned by the handler itself — see
+  // AuthRoutesConfig.mfaPreauthConfirmHandler's doc comment.
+  if (config.mfaPreauthConfirmHandler) {
+    const mfaPreauthConfirmQn = config.mfaPreauthConfirmHandler;
+    const statusMap = config.mfaPreauthConfirmErrorStatusMap ?? {};
+    const rateLimiter =
+      config.mfaPreauthConfirmRateLimit === null
+        ? null
+        : (config.mfaPreauthConfirmRateLimit ?? createInMemoryLoginRateLimiter());
+
+    api.post(Routes.authMfaPreauthConfirm, async (c) => {
+      const raw = await c.req.json().catch(() => null);
+      const parsed = MfaPreauthConfirmBody.safeParse(raw);
+      if (!parsed.success) {
+        return c.json({ isSuccess: false, error: "invalid_body" }, 400);
+      }
+      const body = parsed.data;
+
+      const clientIp = getClientIp(c);
+
+      if (rateLimiter) {
+        const allowed = await rateLimiter.check(clientIp);
+        if (!allowed) {
+          return c.json({ isSuccess: false, error: "rate_limited" }, 429);
+        }
+      }
+
+      const result = await dispatcher.write(mfaPreauthConfirmQn, body, GUEST_USER);
+
+      if (!result.isSuccess) {
+        // @cast-boundary error-details — KumikoError.details shape is per-error
+        const reason =
+          (result.error.details as { reason?: string } | undefined)?.reason ?? result.error.code;
+        // @cast-boundary engine-payload — statusMap value union narrows to the http-status union
+        const status = (statusMap[reason] ?? result.error.httpStatus) as
+          | 400
+          | 401
+          | 403
+          | 422
+          | 429
+          | 500;
+        return c.json({ isSuccess: false, error: result.error }, status);
+      }
+
+      // @cast-boundary engine-payload — generic dispatcher.write result for mfa-preauth-confirm handler
+      const data = result.data as { kind: "mfa-preauth-confirm-success"; session: SessionUser };
+
+      const token = await mintSessionAndRespond(c, data.session);
+
+      if (rateLimiter) {
+        await rateLimiter.reset(clientIp);
+      }
 
       return c.json({
         isSuccess: true,
@@ -554,6 +1055,26 @@ export function createAuthRoutes(
     });
   }
 
+  // Account-unlock mirrors email-verification (token-only confirm body) —
+  // clears the Redis lockout state instead of an entity field, see
+  // confirm-account-unlock.write.ts.
+  if (config.accountUnlock) {
+    const au = config.accountUnlock;
+    registerTokenRequestRoute({
+      api,
+      dispatcher,
+      path: Routes.authRequestAccountUnlock,
+      requestHandler: au.requestHandler,
+    });
+    registerTokenConfirmRoute({
+      api,
+      dispatcher,
+      path: Routes.authConfirmAccountUnlock,
+      confirmHandler: au.confirmHandler,
+      schema: VerifyEmailBody,
+    });
+  }
+
   // Self-Signup (Magic-Link). Request mountet wie reset/verify den
   // silent-success-Pfad mit Token-Mail. Confirm ist anders: returnt
   // SessionUser → die Route mintet JWT + setzt Cookies (Auto-Login
@@ -590,18 +1111,8 @@ export function createAuthRoutes(
         tenantKey: string;
       };
 
-      // Session-Creator analog login — wenn wired, sid wird im JWT
-      // platziert und der Server kann später den Session revoken
-      // (Logout, Compromise).
-      let sessionForJwt: SessionUser = data.session;
-      if (config.sessionCreator) {
-        const sid = await config.sessionCreator(data.session, requestMeta(c));
-        sessionForJwt = { ...data.session, sid };
-      }
-
-      const token = await jwt.sign(sessionForJwt);
-      const csrfToken = generateToken();
-      setAuthCookies(c, { token, csrfToken, sameSite: cookieSameSite, domain: cookieDomain });
+      // Session creation + JWT sign + cookies — see mintSessionAndRespond.
+      const token = await mintSessionAndRespond(c, data.session);
 
       return c.json({
         isSuccess: true,
@@ -677,14 +1188,7 @@ export function createAuthRoutes(
         tenantId: TenantId;
         role: string;
       }; // @cast-boundary engine-payload
-      let sessionForJwt: SessionUser = data.session;
-      if (config.sessionCreator) {
-        const sid = await config.sessionCreator(data.session, requestMeta(c));
-        sessionForJwt = { ...data.session, sid };
-      }
-      const token = await jwt.sign(sessionForJwt);
-      const csrfToken = generateToken();
-      setAuthCookies(c, { token, csrfToken, sameSite: cookieSameSite, domain: cookieDomain });
+      const token = await mintSessionAndRespond(c, data.session);
       return c.json({
         isSuccess: true,
         token,
@@ -717,14 +1221,7 @@ export function createAuthRoutes(
         tenantId: TenantId;
         role: string;
       }; // @cast-boundary engine-payload
-      let sessionForJwt: SessionUser = data.session;
-      if (config.sessionCreator) {
-        const sid = await config.sessionCreator(data.session, requestMeta(c));
-        sessionForJwt = { ...data.session, sid };
-      }
-      const token = await jwt.sign(sessionForJwt);
-      const csrfToken = generateToken();
-      setAuthCookies(c, { token, csrfToken, sameSite: cookieSameSite, domain: cookieDomain });
+      const token = await mintSessionAndRespond(c, data.session);
       return c.json({
         isSuccess: true,
         token,
@@ -857,20 +1354,19 @@ export function createAuthRoutes(
     // tenant A accidentally surviving into tenant B's session). The
     // resolver runs each feature's r.authClaims() hook under the new
     // TenantDb scope.
-    // Strip reserved roles from the membership portion only — globalRoles
+    // buildSessionRoles calls stripForbiddenMembershipRoles internally and
+    // strips reserved roles from the membership side only — globalRoles
     // (where SystemAdmin legitimately lives) is never filtered. Backstop for a
     // membership role that a projection rebuild resurrected past command-time
     // validation (see engine/membership-roles).
-    const mergedRoles = Array.from(
-      new Set([...globalRoles, ...stripForbiddenMembershipRoles(membership.roles)]),
-    );
+    const mergedRoles = buildSessionRoles(globalRoles, membership.roles);
     const targetSession: SessionUser = {
       id: user.id,
       tenantId: targetTenantId,
       roles: mergedRoles,
     };
     const claims = await dispatcher.resolveAuthClaims(targetSession);
-    let sessionForJwt: SessionUser =
+    const sessionForJwt: SessionUser =
       Object.keys(claims).length > 0 ? { ...targetSession, claims } : targetSession;
 
     // Session rotation: revoke old sid BEFORE creating the new one so a
@@ -882,25 +1378,10 @@ export function createAuthRoutes(
     if (config.sessionRevoker && user.sid) {
       await config.sessionRevoker(user.sid);
     }
-    if (config.sessionCreator) {
-      const sid = await config.sessionCreator(sessionForJwt, requestMeta(c));
-      sessionForJwt = { ...sessionForJwt, sid };
-    }
-
-    const newToken = await jwt.sign(sessionForJwt);
-
-    // Rotate both cookies in lock-step with the new JWT. A fresh csrfToken
-    // is minted so a compromised csrf-value (e.g. leaked via a bug in the
-    // app's JS) can't cross a tenant boundary. Bearer-only clients get
-    // the new token in the body below — their Set-Cookie is a no-op
-    // because the browser never sent cookies.
-    const csrfToken = generateToken();
-    setAuthCookies(c, {
-      token: newToken,
-      csrfToken,
-      sameSite: cookieSameSite,
-      domain: cookieDomain,
-    });
+    // Session creation + JWT sign + cookies — see mintSessionAndRespond. A
+    // fresh csrfToken is minted (inside the helper) so a compromised csrf-
+    // value can't cross a tenant boundary.
+    const newToken = await mintSessionAndRespond(c, sessionForJwt);
 
     return c.json({ token: newToken, tenantId: targetTenantId, roles: mergedRoles });
   });