@cosmicdrift/kumiko-framework 0.384.0 → 0.386.0

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 });
+    });
+}

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

@@ -0,0 +1,33 @@
+import type { Context, Hono } from "hono";
+import * as z from "zod";
+import type { Dispatcher } from "../pipeline/dispatcher.ts";
+export type PublicAuthErrorStatus = 400 | 401 | 403 | 422 | 429 | 500;
+export declare const SignupRequestBody: z.ZodObject<{
+    email: z.ZodEmail;
+    handover: z.ZodOptional<z.ZodObject<{
+        entityType: z.ZodString;
+        token: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare function isUnknownHandlerError(e: unknown): boolean;
+export type PendingMfaStep = {
+    kind: "mfa-challenge";
+    challengeToken: string;
+} | {
+    kind: "mfa-setup-required";
+    preauthSetupToken: string;
+};
+export declare function pendingMfaStepResponse(c: Context, step: PendingMfaStep, landing?: {
+    readonly landingPath?: string;
+}): Response;
+export declare function registerTokenRequestRoute(opts: {
+    api: Hono;
+    dispatcher: Dispatcher;
+    path: string;
+    requestHandler: string;
+    schema?: typeof RequestTokenBody | typeof SignupRequestBody;
+}): void;
+declare const RequestTokenBody: z.ZodObject<{
+    email: z.ZodEmail;
+}, z.core.$strip>;
+export {};

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

@@ -0,0 +1,81 @@
+import * as z from "zod";
+import { createAnonymousUser } from "../engine/system-user.js";
+import { SYSTEM_TENANT_ID } from "../engine/types/index.js";
+import { NotFoundError } from "../errors/index.js";
+// 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).
+export 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(),
+});
+// 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.
+export 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";
+}
+export 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.
+export 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 });
+    });
+}
+// 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(),
+});

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

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

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

@@ -0,0 +1,75 @@
+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 { pendingMfaStepResponse, registerTokenRequestRoute, SignupRequestBody, } from "./auth-routes-shared.js";
+const SignupConfirmBody = z.object({
+    token: z.string().min(1),
+    password: z.string().min(8).max(200),
+});
+export function registerSignupRoutes(ctx) {
+    const { api, dispatcher, config, mintSessionAndRespond, landingPathFragment } = ctx;
+    // 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 for 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 for the post-signup redirect to /<tenantKey>/. Unlike the
+                // login response, which only needs `tenants[]` (the user picks in the
+                // switcher), signup knows exactly ONE membership — the frontend UI uses
+                // it directly as the 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,
+            });
+        });
+    }
+}