@cosmicdrift/kumiko-framework 0.328.0 → 0.329.0

package/dist/api/auth-routes.js

@@ -0,0 +1,1003 @@
+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 { assertUnreachable } from "../utils/index.js";
+import { parseRoles } from "../utils/serialization.js";
+import { Routes } from "./api-constants.js";
+import { AUTH_COOKIE_NAME, CSRF_COOKIE_NAME, getUser, } from "./auth-middleware.js";
+import { clientIpSourceFromHonoContext, createClientIpResolver, } from "./client-ip.js";
+import { resolvePostAuthLandingPath } from "./post-auth-landing.js";
+import { generateToken } from "./tokens.js";
+// 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
+// prod deploy would silently break login rather than fail loud.
+function cookieSecure() {
+    return process.env["NODE_ENV"] === "production";
+}
+// Double-entry cookie write used at login and switch-tenant. kumiko_auth is
+// the HttpOnly carrier of the JWT; kumiko_csrf 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 sameSite = opts.sameSite === "strict" ? "Strict" : "Lax";
+    const common = {
+        secure: cookieSecure(),
+        sameSite,
+        path: "/",
+        maxAge: opts.ttlSeconds,
+        ...(opts.domain !== undefined && { domain: opts.domain }),
+    };
+    // Bei gesetzter Domain zuerst die host-only-Variante invalidieren (analog
+    // clearAuthCookies): sonst koexistiert nach einem Deploy mit neuem
+    // cookieDomain das alte host-only-Cookie mit dem neuen Domain-Cookie
+    // (RFC 6265: name+domain ist distinct) und der Server bindet
+    // umgebungsabhängig potenziell ans veraltete host-only-Token.
+    if (opts.domain !== undefined) {
+        deleteCookie(c, AUTH_COOKIE_NAME, { path: "/" });
+        deleteCookie(c, CSRF_COOKIE_NAME, { path: "/" });
+    }
+    setCookie(c, AUTH_COOKIE_NAME, 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, CSRF_COOKIE_NAME, opts.csrfToken, { ...common, httpOnly: false });
+}
+function clearAuthCookies(c, domain) {
+    // Beide Varianten löschen: mit Domain (aktuelle Cookies) UND host-only
+    // (Bestand aus der Zeit vor cookieDomain) — sonst bleibt nach einem
+    // Deploy mit neu gesetztem cookieDomain der alte Cookie liegen und der
+    // Logout wirkt nur scheinbar.
+    deleteCookie(c, AUTH_COOKIE_NAME, { path: "/" });
+    deleteCookie(c, CSRF_COOKIE_NAME, { path: "/" });
+    if (domain !== undefined) {
+        deleteCookie(c, AUTH_COOKIE_NAME, { path: "/", domain });
+        deleteCookie(c, CSRF_COOKIE_NAME, { path: "/", domain });
+    }
+}
+// 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");
+    }
+}
+// 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 };
+}
+// 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}`);
+        },
+    };
+}
+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;
+    // 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));
+    // 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, {
+            token,
+            csrfToken,
+            sameSite: cookieSameSite,
+            domain: cookieDomain,
+            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 ?? createInMemoryLoginRateLimiter());
+        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 ?? 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, 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 ?? 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, 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 ?? 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, 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,
+        });
+    }
+    // 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
+    // direkt nach Activation, kein zweiter Login-Roundtrip nötig).
+    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;
+            // Session creation + JWT sign + cookies — see mintSessionAndRespond.
+            const token = await mintSessionAndRespond(c, data.session);
+            const landingPath = landingPathFragment({
+                flow: "signup",
+                roles: data.session.roles,
+                tenantId: data.session.tenantId,
+                tenantKey: data.tenantKey,
+                ...(data.handover !== undefined && { handover: data.handover }),
+            });
+            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);
+            }
+            const data = result.data; // @cast-boundary engine-payload
+            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.
+        clearAuthCookies(c, cookieDomain);
+        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 c.req.json();
+        const targetTenantId = body.tenantId;
+        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;
+        // Globale Rollen aus user-feature lesen wenn userQuery wired —
+        // tenant-unabhängige Rollen (SystemAdmin etc.) überleben so den
+        // tenant-switch. `parseRoles` liegt utils-side, hier inline-deserialize
+        // damit das Framework keine bundled-features-Imports kriegt.
+        let globalRoles = [];
+        if (config.userQuery) {
+            try {
+                // @cast-boundary engine-payload — dispatcher.query returnt unknown,
+                // userQuery liefert per AuthUserRow-Contract eine row mit roles-spalte.
+                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: globale Rollen kann nicht aufgelöst werden → switch
+                // läuft weiter mit nur tenant-rollen. Server-error mit nur dem
+                // Cause ohne Stack hochwerfen wäre für die UX schlimmer als ein
+                // Tenant-Switch ohne SystemAdmin (User merkt's und meldet's). Log
+                // it via the dispatcher so Ops sieht's.
+                if (!isUnknownHandlerError(e))
+                    throw e;
+            }
+        }
+        // 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.
+        // 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 = buildSessionRoles(globalRoles, membership.roles);
+        const targetSession = {
+            id: user.id,
+            tenantId: targetTenantId,
+            roles: mergedRoles,
+            // Tenant-independent prefs must survive the switch (fw#2343).
+            ...(user.timezone ? { timezone: user.timezone } : {}),
+            ...(user.locale ? { locale: user.locale } : {}),
+        };
+        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: mergedRoles });
+    });
+    return api;
+}
+// --- 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 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));
+        if (!result.isSuccess) {
+            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 });
+    });
+}
+// 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(),
+});