@cosmicdrift/kumiko-framework 0.384.0 → 0.386.0

package/agents/examples/i18n.md

@@ -14,6 +14,7 @@ Feature-scoped translations — 'Hallo' and 'Hello' in the same app.
 
 - `r.translations()` for multi-language feature keys
 - Plurals
+- `requiredLocales`: boot fails when a key misses one of the app's languages
 
 ## Plurals
 
@@ -32,6 +33,20 @@ exist where the locale's grammar needs them:
 `Intl.PluralRules(locale)`, then interpolates `{count}` (and any other
 `{name}` placeholder) into the chosen form.
 
+## Required locales
+
+Without further options boot only checks that each feature is consistent with
+itself. An app that ships fixed languages lists them, and boot then fails on any
+key that misses one of them, including framework keys. Locale packages such as
+`locale-de` count:
+
+```ts illustration
+runProdApp({ ...options, validateBootOptions: { requiredLocales: ["de", "en"] } });
+```
+
+Define the options once and re-export them as `VALIDATE_BOOT_OPTIONS` from
+`kumiko/schema.ts`, so `kumiko-schema validate` checks the same list in CI.
+
 ## Source
 
 Feature entry point: `src/feature.ts`.
@@ -53,7 +68,7 @@ bun test
 // Note: keys are prefixed with feature name → "featureName:key"
 
 import { describe, expect, test } from "bun:test";
-import { createRegistry } from "@cosmicdrift/kumiko-framework/engine";
+import { createRegistry, validateBoot } from "@cosmicdrift/kumiko-framework/engine";
 import { createI18n } from "@cosmicdrift/kumiko-framework/i18n";
 import { errorFeature, greetingFeature } from "../feature";
 
@@ -106,6 +121,22 @@ describe("multiple features merge translations", () => {
     expect(keys).toHaveLength(6);
   });
 });
+
+describe("requiredLocales", () => {
+  test("boot passes when every key carries the required locales", () => {
+    expect(() =>
+      validateBoot([greetingFeature, errorFeature], { requiredLocales: ["de", "en"] }),
+    ).not.toThrow();
+  });
+
+  test("boot names each key that lacks a required locale", () => {
+    expect(() =>
+      validateBoot([greetingFeature, errorFeature], { requiredLocales: ["de", "en", "fr"] }),
+    ).toThrow(
+      /Feature "errors": translation key "errors.not_found" is missing required locale\(s\) fr/,
+    );
+  });
+});
 ```
 
 ### src/feature.ts
@@ -124,20 +155,24 @@ export const greetingFeature = defineFeature("greeting", (r) => {
         de: "Willkommen",
         en: "Welcome",
         fr: "Bienvenue",
+        pl: "Witamy",
       },
       "greeting.goodbye": {
         de: "Auf Wiedersehen",
         en: "Goodbye",
         fr: "Au revoir",
+        pl: "Do widzenia",
       },
       "greeting.hello_name": {
         de: "Hallo, {name}!",
         en: "Hello, {name}!",
         fr: "Bonjour, {name}!",
+        pl: "Cześć, {name}!",
       },
       "greeting.unread_count": {
         de: { one: "{count} ungelesene Nachricht", other: "{count} ungelesene Nachrichten" },
         en: { one: "{count} unread message", other: "{count} unread messages" },
+        fr: { one: "{count} message non lu", other: "{count} messages non lus" },
         pl: {
           one: "{count} nieprzeczytana wiadomość",
           few: "{count} nieprzeczytane wiadomości",

package/agents/features.md

@@ -518,6 +518,10 @@ Requires: `user-data-rights`
 
 Optional requires: `notes-history`
 
+## pat-scope-labels
+
+German labels for the token scopes this sample app declares.
+
 ## personal-access-tokens
 
 Long-lived, revocable Personal Access Tokens for headless HTTP-API access. Stores SHA-256 token hashes in the `store_api_tokens` direct-write table; the plaintext is returned once at creation. `create`/`revoke`/`mine` manage a user's own tokens and `available-scopes` lists the app-declared scope catalog. Bearer tokens carrying the PAT prefix are resolved before jwt.verify (roles resolved live, granted scopes enforced fail-closed at the API boundary) — registered as an auth-foundation tokenVerifier provider, resolved generically by the middleware. Pass { toggleable: { default: false } } to tier-gate the whole feature.

package/dist/api/auth-rate-limiters.d.ts

@@ -0,0 +1,8 @@
+import type { Redis } from "ioredis";
+import type { LoginRateLimiter } from "./auth-routes-types.ts";
+export declare function inMemoryLoginRateLimiterFallback(): LoginRateLimiter;
+export declare function createInMemoryLoginRateLimiter(maxAttempts?: number, windowMs?: number, { maxEntries, sweepThreshold, }?: {
+    maxEntries?: number;
+    sweepThreshold?: number;
+}): LoginRateLimiter;
+export declare function createRedisLoginRateLimiter(redis: Redis, maxAttempts?: number, windowMs?: number, namespace?: string): LoginRateLimiter;

package/dist/api/auth-rate-limiters.js

@@ -0,0 +1,105 @@
+import { createFallbackLogger } from "../logging/index.js";
+let warnedInMemoryLimiterInProduction = false;
+// Without Redis-backed limiters each replica counts on its own, so the effective limit scales with replica count.
+export function inMemoryLoginRateLimiterFallback() {
+    if (process.env["NODE_ENV"] === "production" && !warnedInMemoryLimiterInProduction) {
+        warnedInMemoryLimiterInProduction = true;
+        createFallbackLogger("auth-routes").warn("login/MFA rate limiter falls back to in-memory; limits are per replica");
+    }
+    return createInMemoryLoginRateLimiter();
+}
+// Default: in-memory fixed window. Fine for a single Node process; for
+// multi-process deployments, inject a Redis-backed LoginRateLimiter instead
+// so attempts can't be spread across replicas.
+//
+// Memory management: entries expire after `windowMs` but the map entries
+// themselves linger until something touches them. To stop the map from
+// growing unbounded (a single attacker can create entries with different
+// `ip|email` buckets at ~req rate), we opportunistically sweep expired
+// entries when the map crosses `sweepThreshold` keys and hard-cap total
+// entries at `maxEntries` — oldest ones get dropped first.
+export function createInMemoryLoginRateLimiter(maxAttempts = 10, windowMs = 5 * 60_000, { maxEntries = 10_000, sweepThreshold = 1_000, } = {}) {
+    const hits = new Map();
+    function sweepExpired(now) {
+        for (const [k, entry] of hits) {
+            if (entry.resetAt <= now)
+                hits.delete(k);
+        }
+    }
+    function enforceCap() {
+        // Map iteration is insertion-order, so the oldest entries are first.
+        // Drop from the front until we're back under the cap.
+        // skip: under the cap, nothing to do
+        if (hits.size <= maxEntries)
+            return;
+        const toDrop = hits.size - maxEntries;
+        let dropped = 0;
+        for (const k of hits.keys()) {
+            if (dropped >= toDrop)
+                break;
+            hits.delete(k);
+            dropped++;
+        }
+    }
+    return {
+        async check(key) {
+            const now = Date.now();
+            if (hits.size >= sweepThreshold)
+                sweepExpired(now);
+            const entry = hits.get(key);
+            if (!entry || entry.resetAt <= now) {
+                hits.set(key, { count: 1, resetAt: now + windowMs });
+                enforceCap();
+                return true;
+            }
+            if (entry.count >= maxAttempts)
+                return false;
+            entry.count++;
+            return true;
+        },
+        async reset(key) {
+            hits.delete(key);
+        },
+    };
+}
+// Redis-backed sibling of createInMemoryLoginRateLimiter — same fixed-window
+// semantics (count <= maxAttempts allows, window anchored on first hit), but
+// shared across replicas via INCR/PEXPIRE instead of an in-process Map.
+// runProdApp defaults to this: an in-memory limiter only rate-limits within
+// a single instance, so a multi-replica prod deployment would silently give
+// each replica its own bucket. namespace separates the login-key keyspace
+// from the mfa-verify one (they share the same LoginRateLimiter shape but
+// key on different values).
+// Fail-closed on Redis outage, unlike the in-memory limiter (which never
+// throws): `check`/`reset` propagate any Redis error, so callers 500
+// instead of falling back to unlimited attempts. Deliberate — Redis is
+// already required infra for a multi-replica deployment, and for a
+// security-relevant limiter "briefly unavailable" should read as "briefly
+// down", not "briefly unlimited".
+export function createRedisLoginRateLimiter(redis, maxAttempts = 10, windowMs = 5 * 60_000, namespace = "login") {
+    const prefix = `kumiko:auth:ratelimit:${namespace}:`;
+    return {
+        async check(key) {
+            const redisKey = `${prefix}${key}`;
+            // INCR then PEXPIRE was two round-trips: a crash/network blip between
+            // them (only possible right after count===1, when the key is fresh)
+            // left the key permanently without a TTL — the window never resets,
+            // the counter only grows, and the bucket is locked out until an
+            // operator manually resets/deletes the key. One atomic eval closes
+            // the gap: the TTL is set in the same script invocation that creates
+            // the key, so no observer (including a crash) can see count===1
+            // without the expiry already applied. The `PTTL < 0` branch also
+            // heals keys that already exist without a TTL from before this fix
+            // shipped (PTTL returns -1 for "no expiry set, key exists") — without
+            // it, those pre-existing keys would grow forever with no way back to
+            // a normal window.
+            const count = (await redis.eval(`local c = redis.call('INCR', KEYS[1])
+         if c == 1 or redis.call('PTTL', KEYS[1]) < 0 then redis.call('PEXPIRE', KEYS[1], ARGV[1]) end
+         return c`, 1, redisKey, windowMs));
+            return count <= maxAttempts;
+        },
+        async reset(key) {
+            await redis.del(`${prefix}${key}`);
+        },
+    };
+}

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

@@ -0,0 +1,34 @@
+import type { Context } from "hono";
+import { Hono } from "hono";
+import type { SessionUser, TenantId } from "../engine/types/index.ts";
+import type { Dispatcher } from "../pipeline/dispatcher.ts";
+import type { AuthRoutesConfig } from "./auth-routes-types.ts";
+import type { ClientIpResolver } from "./client-ip.ts";
+import type { JwtHelper } from "./jwt.ts";
+import type { PostAuthLandingArgs } from "./post-auth-landing.ts";
+import type { ResolvedSessionCookies } from "./session-cookies.ts";
+export type AuthRouteContext = {
+    readonly api: Hono;
+    readonly dispatcher: Dispatcher;
+    readonly jwt: JwtHelper;
+    readonly config: AuthRoutesConfig;
+    readonly cookieSameSite: "lax" | "strict";
+    readonly cookieDomain: string | undefined;
+    readonly sessionCookies: ResolvedSessionCookies;
+    readonly retiredCookieDomains: readonly string[];
+    readonly clientIpResolver: ClientIpResolver;
+    readonly getClientIp: (c: Context) => string;
+    readonly switchTenantMfaGate: (c: Context, user: SessionUser, targetTenantId: TenantId) => Promise<{
+        readonly response: Response;
+    } | {
+        readonly clearedRoles: readonly string[];
+    } | undefined>;
+    readonly resolveSwitchTenantRoles: (user: SessionUser, membership: {
+        readonly roles: readonly string[];
+    }) => Promise<readonly string[]>;
+    readonly mintSessionAndRespond: (c: Context, session: SessionUser) => Promise<string>;
+    readonly landingPathFragment: (args: PostAuthLandingArgs) => {
+        readonly landingPath?: string;
+    };
+};
+export declare function createAuthRouteContext(dispatcher: Dispatcher, jwt: JwtHelper, config: AuthRoutesConfig): AuthRouteContext;

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

@@ -0,0 +1,192 @@
+import { Hono } from "hono";
+import { deleteCookie, setCookie } from "hono/cookie";
+import { buildSessionRoles } from "../engine/membership-roles.js";
+import { createSystemUser } from "../engine/system-user.js";
+import { parseRoles } from "../utils/serialization.js";
+import { isUnknownHandlerError, pendingMfaStepResponse } from "./auth-routes-shared.js";
+import { clientIpSourceFromHonoContext, createClientIpResolver } from "./client-ip.js";
+import { resolvePostAuthLandingPath } from "./post-auth-landing.js";
+import { AUTH_COOKIE_BASE, CSRF_COOKIE_BASE, expireLegacySessionCookieVariants, getSessionCookies, resolveSessionCookies, } from "./session-cookies.js";
+import { generateToken } from "./tokens.js";
+// Double-entry cookie write used at login and switch-tenant. The auth cookie is
+// the HttpOnly carrier of the JWT; the csrf cookie is the JS-readable token the
+// web client echoes in X-CSRF-Token on every state-changing request. Both
+// cookies share lifetime and SameSite so a stale auth-cookie can't outlive
+// its csrf partner (or vice versa) and leave the client in a half-logged-in
+// state that would trip the csrf-middleware on every retry.
+function setAuthCookies(c, opts) {
+    const { secure, names } = opts.cookies;
+    const sameSite = opts.sameSite === "strict" ? "Strict" : "Lax";
+    const common = {
+        secure,
+        sameSite,
+        path: "/",
+        maxAge: opts.ttlSeconds,
+        ...(opts.domain !== undefined && { domain: opts.domain }),
+    };
+    // With a Domain, expire the host-only variant first (as clearSessionCookies
+    // does): after a deploy that sets cookieDomain, the old host-only cookie
+    // would coexist with the new Domain cookie (RFC 6265 treats name+domain as
+    // distinct) and the server could bind to the stale host-only token. With
+    // __Host- names the unprefixed host-only cookie is a leftover from before
+    // the prefix and is expired too (and vice versa, see
+    // expireLegacySessionCookieVariants).
+    if (opts.domain !== undefined) {
+        deleteCookie(c, AUTH_COOKIE_BASE, { path: "/" });
+        deleteCookie(c, CSRF_COOKIE_BASE, { path: "/" });
+    }
+    expireLegacySessionCookieVariants(c, opts.cookies);
+    // Must precede the setCookie calls: browsers apply Set-Cookie in order and
+    // a retired domain equal to the new one is rejected at config time.
+    // Retired domains only ever carried unprefixed names (a __Host- cookie has no
+    // Domain), and a __Host- delete with a Domain would be ignored.
+    for (const retiredDomain of opts.retiredDomains) {
+        deleteCookie(c, AUTH_COOKIE_BASE, { path: "/", domain: retiredDomain });
+        deleteCookie(c, CSRF_COOKIE_BASE, { path: "/", domain: retiredDomain });
+    }
+    setCookie(c, names.auth, opts.token, { ...common, httpOnly: true });
+    // Intentionally NOT HttpOnly — the web client has to read this from
+    // document.cookie to include it in the X-CSRF-Token request header.
+    setCookie(c, names.csrf, opts.csrfToken, { ...common, httpOnly: false });
+}
+const INVALID_COOKIE_DOMAIN_CHARS = /[;,\s]/;
+function normalizeCookieDomain(domain) {
+    return domain.replace(/^\./, "").toLowerCase();
+}
+// A malformed entry would corrupt the Set-Cookie header; an entry equal to the
+// current cookieDomain would make login delete the cookie it just sets.
+function assertRetiredCookieDomains(retiredCookieDomains, cookieDomain) {
+    const current = cookieDomain === undefined ? undefined : normalizeCookieDomain(cookieDomain);
+    for (const entry of retiredCookieDomains ?? []) {
+        if (entry === "" || normalizeCookieDomain(entry) === "") {
+            throw new Error("createAuthRoutes: retiredCookieDomains must not contain an empty entry");
+        }
+        if (INVALID_COOKIE_DOMAIN_CHARS.test(entry)) {
+            throw new Error(`createAuthRoutes: retiredCookieDomains entry "${entry}" contains an invalid character (;, comma or whitespace)`);
+        }
+        if (normalizeCookieDomain(entry) === current) {
+            throw new Error(`createAuthRoutes: retiredCookieDomains entry "${entry}" equals cookieDomain; login would delete its own cookie`);
+        }
+    }
+}
+// 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 };
+}
+export function createAuthRouteContext(dispatcher, jwt, config) {
+    const api = new Hono();
+    // Default to "lax": CSRF control comes from the double-submit token, and
+    // "lax" keeps email deep-links (invite, magic-link, notification click)
+    // working. High-security apps can opt into "strict" — see AuthRoutesConfig.
+    const cookieSameSite = config.cookieSameSite ?? "lax";
+    const cookieDomain = config.cookieDomain;
+    const sessionCookies = resolveSessionCookies({
+        secureCookies: config.secureCookies,
+        cookieDomain,
+        retiredCookieDomains: config.retiredCookieDomains,
+    });
+    assertRetiredCookieDomains(config.retiredCookieDomains, cookieDomain);
+    if (config.mfaVerifyHandler && !config.switchTenantMfaGateHandler) {
+        throw new Error("createAuthRoutes: mfaVerifyHandler is set but switchTenantMfaGateHandler is not; " +
+            "POST /auth/switch-tenant would mint admin sessions without the second factor");
+    }
+    const retiredCookieDomains = config.retiredCookieDomains ?? [];
+    // Single hop-count-aware IP getter for every rate-limit call site below —
+    // see AuthRoutesConfig.trustedProxyHops and client-ip.ts's resolveClientIp
+    // doc comment. createClientIpResolver fails loud on a non-finite/negative
+    // value rather than letting it silently collapse every request into the
+    // shared "unknown" bucket.
+    const clientIpResolver = config.resolver ?? createClientIpResolver(config.trustedProxyHops ?? 0, "createAuthRoutes");
+    const getClientIp = (c) => clientIpResolver.resolve(clientIpSourceFromHonoContext(c));
+    // undefined = no gate wired (setup without MFA). "clearedRoles" are the roles the gate decided on,
+    // so the minted session cannot differ from what the gate checked.
+    async function switchTenantMfaGate(c, user, targetTenantId) {
+        if (!config.switchTenantMfaGateHandler)
+            return undefined;
+        const gate = await dispatcher.write(config.switchTenantMfaGateHandler, { userId: user.id, tenantId: targetTenantId }, createSystemUser(user.tenantId));
+        if (!gate.isSuccess) {
+            const status = gate.error.httpStatus; // @cast-boundary engine-payload
+            return { response: c.json({ isSuccess: false, error: gate.error }, status) };
+        }
+        // @cast-boundary engine-payload — the gate handler's three-shape result
+        const gateData = gate.data;
+        if (gateData.kind === "mfa-gate-clear")
+            return { clearedRoles: gateData.roles };
+        return { response: pendingMfaStepResponse(c, gateData) };
+    }
+    // Global roles (SystemAdmin etc.) come from the user feature when userQuery is wired, so they survive
+    // the tenant switch. buildSessionRoles calls stripForbiddenMembershipRoles on the membership side only — a backstop
+    // for a role a projection rebuild resurrected past command-time validation (engine/membership-roles).
+    async function resolveSwitchTenantRoles(user, membership) {
+        let globalRoles = [];
+        if (config.userQuery) {
+            try {
+                // @cast-boundary engine-payload — dispatcher.query returns unknown.
+                // Per the AuthUserRow contract, userQuery returns a row with a roles column.
+                const userRow = (await dispatcher.query(config.userQuery, { id: user.id }, createSystemUser(user.tenantId)));
+                // roles is jsonb string[] (multiSelect); parseRoles also accepts legacy
+                // JSON-encoded text from pre-0.217.0 rows.
+                globalRoles = parseRoles(userRow?.roles ?? null);
+            }
+            catch (e) {
+                // Non-fatal: when global roles cannot be resolved the switch continues with tenant roles
+                // only. A server error carrying just the cause would hurt the UX more than a switch without
+                // SystemAdmin, which the user notices and reports.
+                if (!isUnknownHandlerError(e))
+                    throw e;
+            }
+        }
+        return buildSessionRoles(globalRoles, membership.roles);
+    }
+    // Shared tail of every route that ends a request logged-in: create the
+    // session record (if wired), sign the JWT, set the auth+csrf cookies. Was
+    // duplicated 5x (login/signup-confirm/invite-accept-with-login/invite-
+    // signup-complete/switch-tenant) — extracted so a 6th caller (mfa-verify)
+    // doesn't grow it to 6.
+    async function mintSessionAndRespond(c, session) {
+        let sessionForJwt = session;
+        if (config.sessionCreator) {
+            const sid = await config.sessionCreator(session, requestMeta(c, clientIpResolver));
+            sessionForJwt = { ...session, sid };
+        }
+        const token = await jwt.sign(sessionForJwt);
+        const csrfToken = generateToken();
+        setAuthCookies(c, {
+            cookies: getSessionCookies(c, sessionCookies),
+            token,
+            csrfToken,
+            sameSite: cookieSameSite,
+            domain: cookieDomain,
+            retiredDomains: retiredCookieDomains,
+            ttlSeconds: jwt.ttlSeconds,
+        });
+        return token;
+    }
+    // Spreadable landingPath fragment for the 7 auth-response call sites below
+    // — absent (not `landingPath: undefined`) when unwired/invalid/throwing.
+    function landingPathFragment(args) {
+        const landingPath = resolvePostAuthLandingPath(config.postAuthLanding, args);
+        return landingPath === undefined ? {} : { landingPath };
+    }
+    return {
+        api,
+        dispatcher,
+        jwt,
+        config,
+        cookieSameSite,
+        cookieDomain,
+        sessionCookies,
+        retiredCookieDomains,
+        clientIpResolver,
+        getClientIp,
+        switchTenantMfaGate,
+        resolveSwitchTenantRoles,
+        mintSessionAndRespond,
+        landingPathFragment,
+    };
+}

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

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

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;