@cosmicdrift/kumiko-framework 0.383.1 → 0.385.0

package/dist/api/auth-routes.js

@@ -1,179 +1,11 @@
-import { createHash } from "node:crypto";
-import { Hono } from "hono";
-import { deleteCookie, setCookie } from "hono/cookie";
-import * as z from "zod";
-import { buildSessionRoles } from "../engine/membership-roles.js";
-import { createAnonymousUser, createSystemUser } from "../engine/system-user.js";
-import { SYSTEM_TENANT_ID, } from "../engine/types/index.js";
-import { NotFoundError, toKumikoError, toWriteErrorInfo } from "../errors/index.js";
-import { createFallbackLogger } from "../logging/index.js";
-import { assertUnreachable } from "../utils/index.js";
-import { parseRoles } from "../utils/serialization.js";
-import { Routes } from "./api-constants.js";
-import { getUser, } from "./auth-middleware.js";
-import { clientIpSourceFromHonoContext, createClientIpResolver, } from "./client-ip.js";
-import { resolvePostAuthLandingPath } from "./post-auth-landing.js";
-import { AUTH_COOKIE_BASE, CSRF_COOKIE_BASE, clearSessionCookies, expireLegacySessionCookieVariants, getSessionCookies, resolveSessionCookies, } from "./session-cookies.js";
-import { generateToken } from "./tokens.js";
-// Double-entry cookie write used at login and switch-tenant. The auth cookie is
-// the HttpOnly carrier of the JWT; the csrf cookie is the JS-readable token the
-// web client echoes in X-CSRF-Token on every state-changing request. Both
-// cookies share lifetime and SameSite so a stale auth-cookie can't outlive
-// its csrf partner (or vice versa) and leave the client in a half-logged-in
-// state that would trip the csrf-middleware on every retry.
-function setAuthCookies(c, opts) {
-    const { secure, names } = opts.cookies;
-    const sameSite = opts.sameSite === "strict" ? "Strict" : "Lax";
-    const common = {
-        secure,
-        sameSite,
-        path: "/",
-        maxAge: opts.ttlSeconds,
-        ...(opts.domain !== undefined && { domain: opts.domain }),
-    };
-    // With a Domain, expire the host-only variant first (as clearSessionCookies
-    // does): after a deploy that sets cookieDomain, the old host-only cookie
-    // would coexist with the new Domain cookie (RFC 6265 treats name+domain as
-    // distinct) and the server could bind to the stale host-only token. With
-    // __Host- names the unprefixed host-only cookie is a leftover from before
-    // the prefix and is expired too (and vice versa, see
-    // expireLegacySessionCookieVariants).
-    if (opts.domain !== undefined) {
-        deleteCookie(c, AUTH_COOKIE_BASE, { path: "/" });
-        deleteCookie(c, CSRF_COOKIE_BASE, { path: "/" });
-    }
-    expireLegacySessionCookieVariants(c, opts.cookies);
-    // Must precede the setCookie calls: browsers apply Set-Cookie in order and
-    // a retired domain equal to the new one is rejected at config time.
-    // Retired domains only ever carried unprefixed names (a __Host- cookie has no
-    // Domain), and a __Host- delete with a Domain would be ignored.
-    for (const retiredDomain of opts.retiredDomains) {
-        deleteCookie(c, AUTH_COOKIE_BASE, { path: "/", domain: retiredDomain });
-        deleteCookie(c, CSRF_COOKIE_BASE, { path: "/", domain: retiredDomain });
-    }
-    setCookie(c, names.auth, opts.token, { ...common, httpOnly: true });
-    // Intentionally NOT HttpOnly — the web client has to read this from
-    // document.cookie to include it in the X-CSRF-Token request header.
-    setCookie(c, names.csrf, opts.csrfToken, { ...common, httpOnly: false });
-}
-const INVALID_COOKIE_DOMAIN_CHARS = /[;,\s]/;
-function normalizeCookieDomain(domain) {
-    return domain.replace(/^\./, "").toLowerCase();
-}
-// A malformed entry would corrupt the Set-Cookie header; an entry equal to the
-// current cookieDomain would make login delete the cookie it just sets.
-function assertRetiredCookieDomains(retiredCookieDomains, cookieDomain) {
-    const current = cookieDomain === undefined ? undefined : normalizeCookieDomain(cookieDomain);
-    for (const entry of retiredCookieDomains ?? []) {
-        if (entry === "" || normalizeCookieDomain(entry) === "") {
-            throw new Error("createAuthRoutes: retiredCookieDomains must not contain an empty entry");
-        }
-        if (INVALID_COOKIE_DOMAIN_CHARS.test(entry)) {
-            throw new Error(`createAuthRoutes: retiredCookieDomains entry "${entry}" contains an invalid character (;, comma or whitespace)`);
-        }
-        if (normalizeCookieDomain(entry) === current) {
-            throw new Error(`createAuthRoutes: retiredCookieDomains entry "${entry}" equals cookieDomain; login would delete its own cookie`);
-        }
-    }
-}
-// Body schema for POST /auth/login. Enforced BEFORE rate-limit so that a
-// malformed body (`email: 42`, missing password, …) returns 400 instead of
-// crashing on `.toLowerCase()` and leaking a 500 that never increments the
-// login counter — previous wiring let attackers spam the endpoint without
-// tripping the bucket.
-const LoginBody = z.object({
-    email: z.string().min(1),
-    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),
-});
-const VerifyEmailBody = z.object({
-    token: z.string().min(1),
-});
-const SignupConfirmBody = z.object({
-    token: z.string().min(1),
-    password: z.string().min(8).max(200),
-});
-// Cross-device try-first handover (kumiko-framework#3035 follow-up,
-// offlot-app#454): an optional tenant-handover grant the signup-request
-// route forwards to the handler for server-side verification and binding —
-// the grant itself never appears anywhere else (URL, mail, log, response).
-const SignupRequestBody = z.object({
-    email: z.email(),
-    handover: z
-        .object({
-        entityType: z.string().min(1).max(200),
-        token: z.string().min(1).max(4096),
-    })
-        .optional(),
-});
-const InviteAcceptBody = z.object({
-    token: z.string().min(1),
-});
-const InviteAcceptWithLoginBody = z.object({
-    token: z.string().min(1),
-    email: z.string().email(),
-    password: z.string().min(8).max(200),
-});
-const InviteSignupCompleteBody = z.object({
-    token: z.string().min(1),
-    password: z.string().min(8).max(200),
-});
-const InviteInfoBody = z.object({
-    token: z.string().min(1),
-});
-// Shape guard for "handler not registered" — the only legitimate reason to
-// fall back to a single-tenant reply on /auth/tenants or /auth/switch-tenant.
-// Every other error (DB down, revoker throws, access denied, …) has to
-// propagate — otherwise we'd silently paper over outages.
-function isUnknownHandlerError(e) {
-    if (!(e instanceof NotFoundError))
-        return false;
-    // @cast-boundary error-details — KumikoError.details shape is per-error
-    const details = e.details;
-    return details?.entity === "handler";
-}
-function switchTenantRejectionResponse(c, reason) {
-    switch (reason) {
-        case "not_a_member":
-            return c.json({ error: "not_a_member" }, 403);
-        case "principal_blocked":
-            return c.json({ error: "principal_blocked" }, 403);
-        case "tenant_teardown":
-            return c.json({ error: "tenant_unavailable" }, 410);
-        default:
-            return assertUnreachable(reason, "ActiveMembershipRejection");
-    }
-}
+import { createAuthRouteContext } from "./auth-routes-context.js";
+import { registerInviteRoutes } from "./auth-routes-invite.js";
+import { registerLoginRoute } from "./auth-routes-login.js";
+import { registerMfaPreauthConfirmRoute, registerMfaPreauthEnableStartRoute, registerMfaVerifyRoute, } from "./auth-routes-mfa.js";
+import { registerSessionRoutes } from "./auth-routes-session.js";
+import { registerSignupRoutes } from "./auth-routes-signup.js";
+import { registerAccountUnlockRoutes, registerEmailVerificationRoutes, registerPasswordResetRoutes, } from "./auth-routes-token-flows.js";
+export { createInMemoryLoginRateLimiter, createRedisLoginRateLimiter, inMemoryLoginRateLimiterFallback, } from "./auth-rate-limiters.js";
 // A sid minted by sessionCreator is only revocable when logout can revoke it
 // (sessionRevoker) AND every request re-checks it (sessionChecker). Wiring the
 // first without the other two would make logout look effective while the JWT
@@ -194,924 +26,17 @@ export function assertSessionCallbacksPaired(auth) {
             "feature's sessionStore provides them) or none for stateless JWTs.");
     }
 }
-// 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) {
-    return `preauth-token:${createHash("sha256").update(token).digest("hex")}`;
-}
-// Extract `ip` and `user-agent` for the sessionCreator. Client-IP resolution
-// (trustedProxyHops-aware) is the shared resolveClientIp (see client-ip.ts)
-// — createAuthRoutes builds one resolver instance below and
-// closes over it here and in getClientIp.
-function requestMeta(c, resolver) {
-    const ip = resolver.resolve(clientIpSourceFromHonoContext(c));
-    const userAgent = c.req.header("user-agent") ?? "unknown";
-    return { ip, userAgent };
-}
-let warnedInMemoryLimiterInProduction = false;
-// Without Redis-backed limiters each replica counts on its own, so the effective limit scales with replica count.
-export function inMemoryLoginRateLimiterFallback() {
-    if (process.env["NODE_ENV"] === "production" && !warnedInMemoryLimiterInProduction) {
-        warnedInMemoryLimiterInProduction = true;
-        createFallbackLogger("auth-routes").warn("login/MFA rate limiter falls back to in-memory; limits are per replica");
-    }
-    return createInMemoryLoginRateLimiter();
-}
-// Default: in-memory fixed window. Fine for a single Node process; for
-// multi-process deployments, inject a Redis-backed LoginRateLimiter instead
-// so attempts can't be spread across replicas.
-//
-// Memory management: entries expire after `windowMs` but the map entries
-// themselves linger until something touches them. To stop the map from
-// growing unbounded (a single attacker can create entries with different
-// `ip|email` buckets at ~req rate), we opportunistically sweep expired
-// entries when the map crosses `sweepThreshold` keys and hard-cap total
-// entries at `maxEntries` — oldest ones get dropped first.
-export function createInMemoryLoginRateLimiter(maxAttempts = 10, windowMs = 5 * 60_000, { maxEntries = 10_000, sweepThreshold = 1_000, } = {}) {
-    const hits = new Map();
-    function sweepExpired(now) {
-        for (const [k, entry] of hits) {
-            if (entry.resetAt <= now)
-                hits.delete(k);
-        }
-    }
-    function enforceCap() {
-        // Map iteration is insertion-order, so the oldest entries are first.
-        // Drop from the front until we're back under the cap.
-        // skip: under the cap, nothing to do
-        if (hits.size <= maxEntries)
-            return;
-        const toDrop = hits.size - maxEntries;
-        let dropped = 0;
-        for (const k of hits.keys()) {
-            if (dropped >= toDrop)
-                break;
-            hits.delete(k);
-            dropped++;
-        }
-    }
-    return {
-        async check(key) {
-            const now = Date.now();
-            if (hits.size >= sweepThreshold)
-                sweepExpired(now);
-            const entry = hits.get(key);
-            if (!entry || entry.resetAt <= now) {
-                hits.set(key, { count: 1, resetAt: now + windowMs });
-                enforceCap();
-                return true;
-            }
-            if (entry.count >= maxAttempts)
-                return false;
-            entry.count++;
-            return true;
-        },
-        async reset(key) {
-            hits.delete(key);
-        },
-    };
-}
-// 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, maxAttempts = 10, windowMs = 5 * 60_000, namespace = "login") {
-    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));
-            return count <= maxAttempts;
-        },
-        async reset(key) {
-            await redis.del(`${prefix}${key}`);
-        },
-    };
-}
-// A missing, malformed or non-object body reads as {} so callers answer with their own 400.
-async function readJsonObjectOrEmpty(req) {
-    const raw = await req.json().catch(() => null);
-    return raw !== null && typeof raw === "object" ? raw : {};
-}
 export function createAuthRoutes(dispatcher, jwt, config) {
-    const api = new Hono();
-    // Default to "lax": CSRF control comes from the double-submit token, and
-    // "lax" keeps email deep-links (invite, magic-link, notification click)
-    // working. High-security apps can opt into "strict" — see AuthRoutesConfig.
-    const cookieSameSite = config.cookieSameSite ?? "lax";
-    const cookieDomain = config.cookieDomain;
-    const sessionCookies = resolveSessionCookies({
-        secureCookies: config.secureCookies,
-        cookieDomain,
-        retiredCookieDomains: config.retiredCookieDomains,
-    });
-    assertRetiredCookieDomains(config.retiredCookieDomains, cookieDomain);
-    if (config.mfaVerifyHandler && !config.switchTenantMfaGateHandler) {
-        throw new Error("createAuthRoutes: mfaVerifyHandler is set but switchTenantMfaGateHandler is not; " +
-            "POST /auth/switch-tenant would mint admin sessions without the second factor");
-    }
-    const retiredCookieDomains = config.retiredCookieDomains ?? [];
-    // Single hop-count-aware IP getter for every rate-limit call site below —
-    // see AuthRoutesConfig.trustedProxyHops and client-ip.ts's resolveClientIp
-    // doc comment. createClientIpResolver fails loud on a non-finite/negative
-    // value rather than letting it silently collapse every request into the
-    // shared "unknown" bucket.
-    const clientIpResolver = config.resolver ?? createClientIpResolver(config.trustedProxyHops ?? 0, "createAuthRoutes");
-    const getClientIp = (c) => clientIpResolver.resolve(clientIpSourceFromHonoContext(c));
-    // undefined = no gate wired (setup without MFA). "clearedRoles" are the roles the gate decided on,
-    // so the minted session cannot differ from what the gate checked.
-    async function switchTenantMfaGate(c, user, targetTenantId) {
-        if (!config.switchTenantMfaGateHandler)
-            return undefined;
-        const gate = await dispatcher.write(config.switchTenantMfaGateHandler, { userId: user.id, tenantId: targetTenantId }, createSystemUser(user.tenantId));
-        if (!gate.isSuccess) {
-            const status = gate.error.httpStatus; // @cast-boundary engine-payload
-            return { response: c.json({ isSuccess: false, error: gate.error }, status) };
-        }
-        // @cast-boundary engine-payload — the gate handler's three-shape result
-        const gateData = gate.data;
-        if (gateData.kind === "mfa-gate-clear")
-            return { clearedRoles: gateData.roles };
-        return { response: pendingMfaStepResponse(c, gateData) };
-    }
-    // Global roles (SystemAdmin etc.) come from the user feature when userQuery is wired, so they survive
-    // the tenant switch. buildSessionRoles calls stripForbiddenMembershipRoles on the membership side only — a backstop
-    // for a role a projection rebuild resurrected past command-time validation (engine/membership-roles).
-    async function resolveSwitchTenantRoles(user, membership) {
-        let globalRoles = [];
-        if (config.userQuery) {
-            try {
-                // @cast-boundary engine-payload — dispatcher.query returnt unknown,
-                // Per the AuthUserRow contract, userQuery returns a row with a roles column.
-                const userRow = (await dispatcher.query(config.userQuery, { id: user.id }, createSystemUser(user.tenantId)));
-                // roles is jsonb string[] (multiSelect); parseRoles also accepts legacy
-                // JSON-encoded text from pre-0.217.0 rows.
-                globalRoles = parseRoles(userRow?.roles ?? null);
-            }
-            catch (e) {
-                // Non-fatal: when global roles cannot be resolved the switch continues with tenant roles
-                // only. A server error carrying just the cause would hurt the UX more than a switch without
-                // SystemAdmin, which the user notices and reports.
-                if (!isUnknownHandlerError(e))
-                    throw e;
-            }
-        }
-        return buildSessionRoles(globalRoles, membership.roles);
-    }
-    // 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, session) {
-        let sessionForJwt = session;
-        if (config.sessionCreator) {
-            const sid = await config.sessionCreator(session, requestMeta(c, clientIpResolver));
-            sessionForJwt = { ...session, sid };
-        }
-        const token = await jwt.sign(sessionForJwt);
-        const csrfToken = generateToken();
-        setAuthCookies(c, {
-            cookies: getSessionCookies(c, sessionCookies),
-            token,
-            csrfToken,
-            sameSite: cookieSameSite,
-            domain: cookieDomain,
-            retiredDomains: retiredCookieDomains,
-            ttlSeconds: jwt.ttlSeconds,
-        });
-        return token;
-    }
-    // Spreadable landingPath fragment for the 7 auth-response call sites below
-    // — absent (not `landingPath: undefined`) when unwired/invalid/throwing.
-    function landingPathFragment(args) {
-        const landingPath = resolvePostAuthLandingPath(config.postAuthLanding, args);
-        return landingPath === undefined ? {} : { landingPath };
-    }
-    // POST /auth/login — public endpoint (bypasses auth middleware via PUBLIC_API_PATHS).
-    // The configured login handler authenticates and returns a SessionUser;
-    // the route signs the JWT and hands it back to the client.
-    if (config.loginHandler) {
-        const loginQn = config.loginHandler;
-        const statusMap = config.loginErrorStatusMap ?? {};
-        // Default to in-memory limiter unless the caller opted out via null.
-        const rateLimiter = config.loginRateLimit === null
-            ? null
-            : (config.loginRateLimit ?? inMemoryLoginRateLimiterFallback());
-        api.post(Routes.authLogin, async (c) => {
-            const raw = await c.req.json().catch(() => null);
-            const parsed = LoginBody.safeParse(raw);
-            if (!parsed.success) {
-                return c.json({ isSuccess: false, error: "invalid_body" }, 400);
-            }
-            const body = parsed.data;
-            const clientIp = getClientIp(c);
-            const rateLimitKey = `${clientIp}|${body.email.toLowerCase()}`;
-            if (rateLimiter) {
-                // Bucket by both IP and email so a single guessed password can't
-                // block a real user from logging in, but also so one abuser can't
-                // just cycle emails.
-                const allowed = await rateLimiter.check(rateLimitKey);
-                if (!allowed) {
-                    return c.json({ isSuccess: false, error: "rate_limited" }, 429);
-                }
-            }
-            const result = await dispatcher.write(loginQn, body, createAnonymousUser(SYSTEM_TENANT_ID));
-            if (!result.isSuccess) {
-                // Feature-specific auth reason codes arrive via UnprocessableError.details.reason
-                // (e.g. "invalid_credentials", "user_locked"). Fall back to the KumikoError code
-                // so unmapped cases still get a sensible status.
-                // @cast-boundary error-details — KumikoError.details shape is per-error
-                const reason = result.error.details?.reason ?? result.error.code;
-                // @cast-boundary engine-payload — statusMap value union narrows to the http-status union
-                const status = (statusMap[reason] ?? result.error.httpStatus);
-                return c.json({ isSuccess: false, error: result.error }, status);
-            }
-            // @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;
-            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,
-                });
-            }
-            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);
-            const landingPath = landingPathFragment({
-                flow: "login",
-                roles: data.session.roles,
-                tenantId: data.session.tenantId,
-            });
-            if (rateLimiter) {
-                await rateLimiter.reset(rateLimitKey);
-            }
-            return c.json({
-                isSuccess: true,
-                token,
-                user: { id: data.session.id, tenantId: data.session.tenantId, roles: data.session.roles },
-                ...landingPath,
-            });
-        });
-    }
-    // POST /auth/mfa/verify — completes a two-step login. Mirrors /auth/login
-    // structurally (public, anonymous identity 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 ?? inMemoryLoginRateLimiterFallback());
-        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, createAnonymousUser(SYSTEM_TENANT_ID));
-            if (!result.isSuccess) {
-                // @cast-boundary error-details — KumikoError.details shape is per-error
-                const reason = result.error.details?.reason ?? result.error.code;
-                // @cast-boundary engine-payload — statusMap value union narrows to the http-status union
-                const status = (statusMap[reason] ?? result.error.httpStatus);
-                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;
-            const token = await mintSessionAndRespond(c, data.session);
-            const landingPath = landingPathFragment({
-                flow: "login",
-                roles: data.session.roles,
-                tenantId: data.session.tenantId,
-            });
-            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 },
-                ...landingPath,
-            });
-        });
-    }
-    // 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 ?? inMemoryLoginRateLimiterFallback());
-        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, createAnonymousUser(SYSTEM_TENANT_ID));
-            if (!result.isSuccess) {
-                // @cast-boundary error-details — KumikoError.details shape is per-error
-                const reason = result.error.details?.reason ?? result.error.code;
-                // @cast-boundary engine-payload — statusMap value union narrows to the http-status union
-                const status = (statusMap[reason] ?? result.error.httpStatus);
-                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;
-            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, anonymous identity 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 ?? inMemoryLoginRateLimiterFallback());
-        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, createAnonymousUser(SYSTEM_TENANT_ID));
-            if (!result.isSuccess) {
-                // @cast-boundary error-details — KumikoError.details shape is per-error
-                const reason = result.error.details?.reason ?? result.error.code;
-                // @cast-boundary engine-payload — statusMap value union narrows to the http-status union
-                const status = (statusMap[reason] ?? result.error.httpStatus);
-                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;
-            const token = await mintSessionAndRespond(c, data.session);
-            const landingPath = landingPathFragment({
-                flow: "login",
-                roles: data.session.roles,
-                tenantId: data.session.tenantId,
-            });
-            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 },
-                ...landingPath,
-            });
-        });
-    }
-    // POST /auth/request-password-reset + /auth/reset-password — public.
-    // Silent-success on request (no enumeration), typed failure on confirm.
-    // Rate-limit covered via config.rateLimit.auth (Sprint G.5 L2, /auth/*).
-    if (config.passwordReset) {
-        const pr = config.passwordReset;
-        registerTokenRequestRoute({
-            api,
-            dispatcher,
-            path: Routes.authRequestPasswordReset,
-            requestHandler: pr.requestHandler,
-        });
-        registerTokenConfirmRoute({
-            api,
-            dispatcher,
-            path: Routes.authResetPassword,
-            confirmHandler: pr.confirmHandler,
-            schema: ResetPasswordBody,
-        });
-    }
-    // Email-verification mirrors password-reset.
-    if (config.emailVerification) {
-        const ev = config.emailVerification;
-        registerTokenRequestRoute({
-            api,
-            dispatcher,
-            path: Routes.authRequestEmailVerification,
-            requestHandler: ev.requestHandler,
-        });
-        registerTokenConfirmRoute({
-            api,
-            dispatcher,
-            path: Routes.authVerifyEmail,
-            confirmHandler: ev.confirmHandler,
-            schema: VerifyEmailBody,
-        });
-    }
-    // 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,
-        });
-    }
-    // Signup confirm mints the session (auto-login) unless the MFA gate applies;
-    // then it answers with the MFA step only, no session or cookies.
-    if (config.signup) {
-        const sg = config.signup;
-        registerTokenRequestRoute({
-            api,
-            dispatcher,
-            path: Routes.authSignupRequest,
-            requestHandler: sg.requestHandler,
-            schema: SignupRequestBody,
-        });
-        api.post(Routes.authSignupConfirm, async (c) => {
-            const raw = await c.req.json().catch(() => null);
-            const parsed = SignupConfirmBody.safeParse(raw);
-            if (!parsed.success) {
-                return c.json({ isSuccess: false, error: "invalid_body" }, 400);
-            }
-            const result = await dispatcher.write(sg.confirmHandler, parsed.data, createAnonymousUser(SYSTEM_TENANT_ID));
-            if (!result.isSuccess) {
-                // 422 für invalid_signup_token (handler-level UnprocessableError).
-                // @cast-boundary engine-payload — KumikoError.httpStatus narrows to the http-status union
-                const status = result.error.httpStatus;
-                return c.json({ isSuccess: false, error: result.error }, status);
-            }
-            // @cast-boundary engine-payload — generic dispatcher.write result for signup-confirm
-            const data = result.data;
-            if (data.kind !== "auth-session") {
-                // No session yet, but the account and a claimed handover exist: hand
-                // the signup landing to the client so the login that follows lands
-                // where a signup without the MFA gate would have.
-                return pendingMfaStepResponse(c, data, landingPathFragment({ flow: "signup", ...data.signup }));
-            }
-            // Session creation + JWT sign + cookies — see mintSessionAndRespond.
-            const token = await mintSessionAndRespond(c, data.session);
-            const signupOutcome = {
-                roles: data.session.roles,
-                tenantId: data.session.tenantId,
-                tenantKey: data.tenantKey,
-                ...(data.handover !== undefined && { handover: data.handover }),
-            };
-            const landingPath = landingPathFragment({ flow: "signup", ...signupOutcome });
-            return c.json({
-                isSuccess: true,
-                token,
-                user: {
-                    id: data.session.id,
-                    tenantId: data.session.tenantId,
-                    roles: data.session.roles,
-                },
-                // tenantKey für Post-Signup-Redirect zu /<tenantKey>/.
-                // Anders als der login-response der nur `tenants[]` braucht
-                // (User wählt im Switcher), kennt der signup nur EINE
-                // membership — die Frontend-UI nimmt das direkt als Redirect-
-                // Target.
-                tenantKey: data.tenantKey,
-                // Cross-device try-first handover (kumiko-framework#3035 follow-up):
-                // present only when signup-confirm actually claimed a bound grant —
-                // absent, not null, so a client that doesn't know the field sees
-                // nothing unusual.
-                ...(data.handover !== undefined && { handover: data.handover }),
-                ...landingPath,
-            });
-        });
-    }
-    // Tenant-Invite Magic-Link. 3 separate Routes für 3 Accept-Branches:
-    if (config.invite) {
-        const inv = config.invite;
-        // Branch 1: logged-in User klickt Invite-Link → Membership-Add im
-        // invited Tenant (NICHT Tenant-Switch — User bleibt in seiner
-        // aktuellen Session, kann später via Tenant-Switcher wechseln).
-        // Requires JWT (siehe PUBLIC_API_PATHS — invite-accept ist NICHT
-        // public, im Gegensatz zu acceptWithLogin/signupComplete).
-        api.post(Routes.authInviteAccept, async (c) => {
-            const user = getUser(c);
-            const raw = await c.req.json().catch(() => null);
-            const parsed = InviteAcceptBody.safeParse(raw);
-            if (!parsed.success) {
-                return c.json({ isSuccess: false, error: "invalid_body" }, 400);
-            }
-            const result = await dispatcher.write(inv.acceptHandler, parsed.data, user);
-            if (!result.isSuccess) {
-                // @cast-boundary engine-payload — KumikoError.httpStatus
-                const status = result.error.httpStatus;
-                return c.json({ isSuccess: false, error: result.error }, status);
-            }
-            // @cast-boundary engine-payload — generic dispatcher.write result
-            const data = result.data;
-            const landingPath = landingPathFragment({
-                flow: "invite",
-                roles: [data.role],
-                tenantId: data.tenantId,
-            });
-            return c.json({
-                isSuccess: true,
-                tenantId: data.tenantId,
-                role: data.role,
-                alreadyMember: data.alreadyMember,
-                ...landingPath,
-            });
-        });
-        // Branch 2: anon User mit existing email — Login + Accept in einem
-        // Roundtrip. JWT-mint analog signup-confirm.
-        api.post(Routes.authInviteAcceptWithLogin, async (c) => {
-            const raw = await c.req.json().catch(() => null);
-            const parsed = InviteAcceptWithLoginBody.safeParse(raw);
-            if (!parsed.success) {
-                return c.json({ isSuccess: false, error: "invalid_body" }, 400);
-            }
-            const result = await dispatcher.write(inv.acceptWithLoginHandler, parsed.data, createAnonymousUser(SYSTEM_TENANT_ID));
-            if (!result.isSuccess) {
-                const status = result.error.httpStatus; // @cast-boundary engine-payload
-                return c.json({ isSuccess: false, error: result.error }, status);
-            }
-            // @cast-boundary engine-payload — same three-shape union as /auth/login
-            // (see gateEnforceMfa): a straight session, an MFA challenge, or a
-            // hard mfa-setup-required block. Only the auth-session branch also
-            // carries tenantId/role (invite-specific).
-            const data = result.data;
-            if (data.kind === "mfa-setup-required") {
-                return c.json({
-                    isSuccess: true,
-                    mfaSetupRequired: true,
-                    preauthSetupToken: data.preauthSetupToken,
-                });
-            }
-            if (data.kind === "mfa-challenge") {
-                return c.json({ isSuccess: true, mfaRequired: true, challengeToken: data.challengeToken });
-            }
-            const token = await mintSessionAndRespond(c, data.session);
-            const landingPath = landingPathFragment({
-                flow: "invite",
-                roles: data.session.roles,
-                tenantId: data.tenantId,
-            });
-            return c.json({
-                isSuccess: true,
-                token,
-                user: {
-                    id: data.session.id,
-                    tenantId: data.session.tenantId,
-                    roles: data.session.roles,
-                },
-                tenantId: data.tenantId,
-                role: data.role,
-                ...landingPath,
-            });
-        });
-        // Branch 3: anon User mit neuer email — User+Membership entstehen,
-        // KEIN neuer Tenant. JWT-mint.
-        api.post(Routes.authInviteSignupComplete, async (c) => {
-            const raw = await c.req.json().catch(() => null);
-            const parsed = InviteSignupCompleteBody.safeParse(raw);
-            if (!parsed.success) {
-                return c.json({ isSuccess: false, error: "invalid_body" }, 400);
-            }
-            const result = await dispatcher.write(inv.signupCompleteHandler, parsed.data, createAnonymousUser(SYSTEM_TENANT_ID));
-            if (!result.isSuccess) {
-                const status = result.error.httpStatus; // @cast-boundary engine-payload
-                return c.json({ isSuccess: false, error: result.error }, status);
-            }
-            // @cast-boundary engine-payload — same three-shape union as invite-accept-with-login
-            const data = result.data;
-            if (data.kind !== "auth-session")
-                return pendingMfaStepResponse(c, data);
-            const token = await mintSessionAndRespond(c, data.session);
-            const landingPath = landingPathFragment({
-                flow: "invite",
-                roles: data.session.roles,
-                tenantId: data.tenantId,
-            });
-            return c.json({
-                isSuccess: true,
-                token,
-                user: {
-                    id: data.session.id,
-                    tenantId: data.session.tenantId,
-                    roles: data.session.roles,
-                },
-                tenantId: data.tenantId,
-                role: data.role,
-                ...landingPath,
-            });
-        });
-        // Anonymous, read-only invite lookup for the acceptance page: pre-fill
-        // the invited email and pick Branch 2 (existing account) vs Branch 3
-        // (new account) before the user submits. Token is never consumed here.
-        if (inv.infoHandler) {
-            const infoHandler = inv.infoHandler;
-            api.post(Routes.authInviteInfo, async (c) => {
-                const raw = await c.req.json().catch(() => null);
-                const parsed = InviteInfoBody.safeParse(raw);
-                if (!parsed.success) {
-                    return c.json({ isSuccess: false, error: "invalid_body" }, 400);
-                }
-                try {
-                    // @cast-boundary engine-payload — generic dispatcher.query result
-                    const data = (await dispatcher.query(infoHandler, parsed.data, createAnonymousUser(SYSTEM_TENANT_ID)));
-                    return c.json({ isSuccess: true, ...data });
-                }
-                catch (e) {
-                    const err = toKumikoError(e);
-                    // Same body shape as the write routes' `{ isSuccess: false, error:
-                    // result.error }` (WriteErrorInfo) — this is a query, not a write,
-                    // so there's no WriteResult to read `.error` off; toWriteErrorInfo
-                    // builds the equivalent shape directly from the caught error.
-                    return c.json({ isSuccess: false, error: toWriteErrorInfo(err) }, err.httpStatus);
-                }
-            });
-        }
-    }
-    // POST /auth/logout — revokes the current session. Requires a valid JWT so
-    // the middleware has already populated `user.sid` from the `jti` claim. If
-    // the app hasn't wired a sessionRevoker, logout is effectively a no-op on
-    // the server — the client can just drop the token.
-    api.post(Routes.authLogout, async (c) => {
-        const user = getUser(c);
-        if (config.sessionRevoker && user.sid) {
-            await config.sessionRevoker(user.sid);
-        }
-        // Clear cookies on the cookie-transport path. Idempotent — clearing a
-        // missing cookie is a no-op, so bearer-only clients aren't affected.
-        clearSessionCookies(c, getSessionCookies(c, sessionCookies));
-        return c.json({ isSuccess: true });
-    });
-    // GET /auth/tenants — list tenants the current user belongs to
-    api.get(Routes.authTenants, async (c) => {
-        const user = getUser(c);
-        try {
-            // System-scoped: membershipQuery is access-locked to system-role.
-            // @cast-boundary engine-payload — generic dispatcher.query result
-            const memberships = (await dispatcher.query(config.membershipQuery, { userId: user.id }, createSystemUser(user.tenantId)));
-            return c.json({
-                tenants: memberships.map((m) => ({
-                    tenantId: m.tenantId,
-                    roles: m.roles,
-                    ...(m.tenantName !== undefined && { name: m.tenantName }),
-                    ...(m.tenantKey !== undefined && { key: m.tenantKey }),
-                })),
-                activeTenantId: user.tenantId,
-            });
-        }
-        catch (e) {
-            // Only legitimate fallback: the app hasn't wired membershipQuery at
-            // all. A DB fault or a permission failure has to bubble up so ops
-            // sees it — collapsing them into "just your current tenant" hides
-            // outages behind a UI that looks fine.
-            if (!isUnknownHandlerError(e))
-                throw e;
-            return c.json({
-                tenants: [{ tenantId: user.tenantId, roles: [...user.roles] }],
-                activeTenantId: user.tenantId,
-            });
-        }
-    });
-    // POST /auth/switch-tenant — switch to a different tenant
-    api.post(Routes.authSwitchTenant, async (c) => {
-        const user = getUser(c);
-        const body = await readJsonObjectOrEmpty(c.req);
-        // The id seeds a SYSTEM identity in resolveActiveMembership — reject anything
-        // that is not a non-empty string before it gets that far.
-        if (!isNonEmptyString(body.tenantId)) {
-            return c.json({ error: "invalid_tenant" }, 400);
-        }
-        const targetTenantId = body.tenantId; // @cast-boundary request-body
-        if (targetTenantId === user.tenantId) {
-            return c.json({ error: "already_in_tenant" }, 400);
-        }
-        // Membership + principal-blocked + tenant-teardown in one building
-        // block — trusted server code asking on the user's behalf, same trust boundary as before.
-        let activeMembership;
-        try {
-            activeMembership = await dispatcher.resolveActiveMembership(user.id, targetTenantId);
-        }
-        catch (e) {
-            // No membershipQuery wired → switching tenants is just not offered in
-            // this deployment. Any other error propagates so a broken query handler
-            // surfaces as a real 5xx instead of a misleading 400.
-            if (!isUnknownHandlerError(e))
-                throw e;
-            return c.json({ error: "tenant_switch_not_available" }, 400);
-        }
-        if (activeMembership.kind === "rejected") {
-            return switchTenantRejectionResponse(c, activeMembership.reason);
-        }
-        const membership = activeMembership.membership;
-        const gate = await switchTenantMfaGate(c, user, targetTenantId);
-        if (gate !== undefined && "response" in gate)
-            return gate.response;
-        const sessionRoles = gate !== undefined ? gate.clearedRoles : await resolveSwitchTenantRoles(user, membership);
-        // Issue new JWT with the target tenant and its roles. Claims MUST be
-        // recomputed for the new tenant — stale claims from the previous
-        // tenant would leak identity facts across tenancies (e.g. teamId from
-        // tenant A accidentally surviving into tenant B's session). The
-        // resolver runs each feature's r.authClaims() hook under the new
-        // TenantDb scope.
-        const targetSession = {
-            id: user.id,
-            tenantId: targetTenantId,
-            roles: sessionRoles,
-            // Tenant-independent prefs must survive the switch (fw#2343).
-            ...tenantIndependentPrefs(user),
-        };
-        const claims = await dispatcher.resolveAuthClaims(targetSession);
-        const sessionForJwt = Object.keys(claims).length > 0 ? { ...targetSession, claims } : targetSession;
-        // Session rotation: revoke old sid BEFORE creating the new one so a
-        // creator failure leaves the user logged-out cleanly rather than with
-        // two live sessions. Client must log in again on creator-throw. A
-        // revoker/creator that actually throws (Redis down, DB deadlock) surfaces
-        // as a 5xx — swallowing it into tenant_switch_not_available was hiding
-        // real outages.
-        if (config.sessionRevoker && user.sid) {
-            await config.sessionRevoker(user.sid);
-        }
-        // 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: sessionRoles });
-    });
-    return api;
-}
-function pendingMfaStepResponse(c, step, landing = {}) {
-    if (step.kind === "mfa-setup-required") {
-        return c.json({
-            isSuccess: true,
-            mfaSetupRequired: true,
-            preauthSetupToken: step.preauthSetupToken,
-            ...landing,
-        });
-    }
-    return c.json({
-        isSuccess: true,
-        mfaRequired: true,
-        challengeToken: step.challengeToken,
-        ...landing,
-    });
-}
-// --- shared route builders for token flows ---------------------------------
-// Password-reset, email-verification and signup share the exact same request
-// HTTP-shape: parse body → dispatch the request handler → always-200 (no
-// enumeration). The handler mints the token AND dispatches the magic-link mail
-// via delivery (ctx.notify); the route never sees the token. confirm-route
-// validates the token + does the state change → typed failure or 200. Keeping
-// the silent-success invariant in one place means changing how the framework
-// handles "invalid_body" on a public token endpoint is one edit, not three.
-function tenantIndependentPrefs(user) {
-    return {
-        ...(user.timezone ? { timezone: user.timezone } : {}),
-        ...(user.locale ? { locale: user.locale } : {}),
-    };
-}
-function isNonEmptyString(value) {
-    return typeof value === "string" && value.length > 0;
-}
-function registerTokenRequestRoute(opts) {
-    const body = opts.schema ?? RequestTokenBody;
-    opts.api.post(opts.path, async (c) => {
-        const raw = await c.req.json().catch(() => null);
-        const parsed = body.safeParse(raw);
-        // Malformed body → silent success. A probing client mustn't learn
-        // anything from the shape of their input.
-        if (!parsed.success)
-            return c.json({ isSuccess: true });
-        // The handler dispatches the magic-link mail via delivery before returning.
-        // Handler-level failures (misconfiguration, e.g. no RateLimitResolver) stay
-        // out of the response so it is uniform for unknown vs. known emails, but
-        // they are logged — otherwise the mail silently never goes out. No email in
-        // the log line (PII).
-        const result = await opts.dispatcher.write(opts.requestHandler, parsed.data, createAnonymousUser(SYSTEM_TENANT_ID));
-        // rate_limited is an expected, attacker-triggerable outcome; logging it
-        // would flood the sink and bury real misconfiguration errors.
-        if (!result.isSuccess && result.error.code !== "rate_limited") {
-            console.error(`[kumiko] token request handler "${opts.requestHandler}" failed: ${result.error.code}`);
-        }
-        return c.json({ isSuccess: true });
-    });
-}
-function registerTokenConfirmRoute(opts) {
-    opts.api.post(opts.path, async (c) => {
-        const raw = await c.req.json().catch(() => null);
-        const parsed = opts.schema.safeParse(raw);
-        if (!parsed.success) {
-            return c.json({ isSuccess: false, error: "invalid_body" }, 400);
-        }
-        const result = await opts.dispatcher.write(opts.confirmHandler, parsed.data, createAnonymousUser(SYSTEM_TENANT_ID));
-        if (!result.isSuccess) {
-            const status = result.error.httpStatus; // @cast-boundary engine-payload
-            return c.json({ isSuccess: false, error: result.error }, status);
-        }
-        return c.json({ isSuccess: true });
-    });
+    const ctx = createAuthRouteContext(dispatcher, jwt, config);
+    registerLoginRoute(ctx);
+    registerMfaVerifyRoute(ctx);
+    registerMfaPreauthEnableStartRoute(ctx);
+    registerMfaPreauthConfirmRoute(ctx);
+    registerPasswordResetRoutes(ctx);
+    registerEmailVerificationRoutes(ctx);
+    registerAccountUnlockRoutes(ctx);
+    registerSignupRoutes(ctx);
+    registerInviteRoutes(ctx);
+    registerSessionRoutes(ctx);
+    return ctx.api;
 }
-// Shared request-body shape for request-password-reset + request-email-
-// verification. Extracted so the two flows stay in sync when the schema
-// gains optional fields (locale, deviceId, …).
-const RequestTokenBody = z.object({
-    email: z.email(),
-});