@cosmicdrift/kumiko-framework 0.383.1 → 0.385.0

package/dist/api/auth-routes-invite.js

@@ -0,0 +1,171 @@
+import * as z from "zod";
+import { createAnonymousUser } from "../engine/system-user.js";
+import { SYSTEM_TENANT_ID } from "../engine/types/index.js";
+import { toKumikoError, toWriteErrorInfo } from "../errors/index.js";
+import { Routes } from "./api-constants.js";
+import { getUser } from "./auth-middleware.js";
+import { pendingMfaStepResponse } from "./auth-routes-shared.js";
+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),
+});
+export function registerInviteRoutes(ctx) {
+    const { api, dispatcher, config, mintSessionAndRespond, landingPathFragment } = ctx;
+    // Tenant-Invite magic link. 3 separate routes for 3 accept branches:
+    if (config.invite) {
+        const inv = config.invite;
+        // Branch 1: a logged-in user clicks the invite link → membership add in
+        // the invited tenant (NOT a tenant switch — the user stays in their
+        // current session and can switch later via the tenant switcher).
+        // Requires JWT (see PUBLIC_API_PATHS — invite-accept is NOT public,
+        // unlike 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: anonymous user with an existing email — login + accept in a
+        // single round trip. JWT mint analogous to 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: anonymous user with a new email — user + membership are created,
+        // NO new 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);
+                }
+            });
+        }
+    }
+}

package/dist/api/auth-routes-login.d.ts

@@ -0,0 +1,2 @@
+import type { AuthRouteContext } from "./auth-routes-context.ts";
+export declare function registerLoginRoute(ctx: AuthRouteContext): void;

package/dist/api/auth-routes-login.js

@@ -0,0 +1,103 @@
+import * as z from "zod";
+import { createAnonymousUser } from "../engine/system-user.js";
+import { SYSTEM_TENANT_ID } from "../engine/types/index.js";
+import { Routes } from "./api-constants.js";
+import { inMemoryLoginRateLimiterFallback } from "./auth-rate-limiters.js";
+// 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(),
+});
+export function registerLoginRoute(ctx) {
+    const { api, dispatcher, config, getClientIp, mintSessionAndRespond, landingPathFragment } = ctx;
+    // 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,
+            });
+        });
+    }
+}

package/dist/api/auth-routes-mfa.d.ts

@@ -0,0 +1,4 @@
+import type { AuthRouteContext } from "./auth-routes-context.ts";
+export declare function registerMfaVerifyRoute(ctx: AuthRouteContext): void;
+export declare function registerMfaPreauthEnableStartRoute(ctx: AuthRouteContext): void;
+export declare function registerMfaPreauthConfirmRoute(ctx: AuthRouteContext): void;

package/dist/api/auth-routes-mfa.js

@@ -0,0 +1,211 @@
+import { createHash } from "node:crypto";
+import * as z from "zod";
+import { createAnonymousUser } from "../engine/system-user.js";
+import { SYSTEM_TENANT_ID } from "../engine/types/index.js";
+import { Routes } from "./api-constants.js";
+import { inMemoryLoginRateLimiterFallback } from "./auth-rate-limiters.js";
+// 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),
+});
+// 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")}`;
+}
+export function registerMfaVerifyRoute(ctx) {
+    const { api, dispatcher, config, getClientIp, mintSessionAndRespond, landingPathFragment } = ctx;
+    // 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,
+            });
+        });
+    }
+}
+export function registerMfaPreauthEnableStartRoute(ctx) {
+    const { api, dispatcher, config, getClientIp } = ctx;
+    // 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 });
+        });
+    }
+}
+export function registerMfaPreauthConfirmRoute(ctx) {
+    const { api, dispatcher, config, getClientIp, mintSessionAndRespond, landingPathFragment } = ctx;
+    // 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,
+            });
+        });
+    }
+}

package/dist/api/auth-routes-session.d.ts

@@ -0,0 +1,2 @@
+import type { AuthRouteContext } from "./auth-routes-context.ts";
+export declare function registerSessionRoutes(ctx: AuthRouteContext): void;

package/dist/api/auth-routes-session.js

@@ -0,0 +1,144 @@
+import { createSystemUser } from "../engine/system-user.js";
+import { assertUnreachable } from "../utils/index.js";
+import { Routes } from "./api-constants.js";
+import { getUser } from "./auth-middleware.js";
+import { isUnknownHandlerError } from "./auth-routes-shared.js";
+import { clearSessionCookies, getSessionCookies } from "./session-cookies.js";
+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");
+    }
+}
+// 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 : {};
+}
+function tenantIndependentPrefs(user) {
+    return {
+        ...(user.timezone ? { timezone: user.timezone } : {}),
+        ...(user.locale ? { locale: user.locale } : {}),
+    };
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+export function registerSessionRoutes(ctx) {
+    const { api, dispatcher, config, sessionCookies, switchTenantMfaGate, resolveSwitchTenantRoles, mintSessionAndRespond, } = ctx;
+    // 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 });
+    });
+}