@cosmicdrift/kumiko-framework 0.387.0 → 0.388.0

package/dist/api/server-middleware.js

@@ -0,0 +1,211 @@
+import { resolveTenantLifecyclePlugin } from "../pipeline/active-membership.js";
+import { authEndpointRateLimit, globalIpRateLimit } from "../rate-limit/index.js";
+import { authMiddleware, getUser } from "./auth-middleware.js";
+import { assertSessionCallbacksPaired } from "./auth-routes.js";
+import { csrfMiddleware } from "./csrf-middleware.js";
+import { observabilityMiddleware } from "./observability-middleware.js";
+import { assertOriginGuardConfig, normalizeOrigin, resolveOriginGuard, } from "./origin-middleware.js";
+import { patRouteGuard } from "./pat-route-guard.js";
+import { piiCiphertextResponseGuard } from "./pii-leak-guard.js";
+import { requestIdMiddleware } from "./request-id-middleware.js";
+import { resolveSessionCookies, sessionCookiesMiddleware, } from "./session-cookies.js";
+export function installSessionCookies(app, auth) {
+    // Resolved once; auth routes, auth/csrf middleware and the tenant-cookie
+    // helpers read the cookie names from the request context.
+    const sessionCookies = resolveSessionCookies({
+        secureCookies: auth?.secureCookies,
+        cookieDomain: auth?.cookieDomain,
+        retiredCookieDomains: auth?.retiredCookieDomains,
+    });
+    app.use("*", sessionCookiesMiddleware(sessionCookies));
+    return sessionCookies;
+}
+export function installRequestId(app, wiring) {
+    const { options, clientIpResolver } = wiring;
+    app.use("/api/*", requestIdMiddleware({
+        resolver: clientIpResolver,
+        ...(options.errorDocs && { errorDocs: options.errorDocs }),
+    }));
+}
+export function installRateLimitMiddleware(app, wiring) {
+    const { options, rateLimitResolver, clientIpResolver, observability } = wiring;
+    // L1/L2 rate-limit middleware run BEFORE auth so an unauthenticated
+    // flood can't even reach the JWT-verify code path. Wired only when
+    // the caller passed `rateLimit.global` or `rateLimit.auth`. The
+    // resolver is the auto-wired one (or `context.rateLimit` if set);
+    // boot-fails loudly when the caller asked for middleware without a
+    // working Redis to back it.
+    let globalRateLimitGuard;
+    if (wiring.rateLimitMiddlewareRequested) {
+        if (!rateLimitResolver) {
+            throw new Error("rateLimit middleware requested but no resolver available — pass `context.redis` " +
+                "or `context.rateLimit` so the resolver can be built.");
+        }
+        if (options.rateLimit?.global) {
+            globalRateLimitGuard = globalIpRateLimit({
+                ...options.rateLimit.global,
+                resolver: rateLimitResolver,
+                clientIpResolver,
+                meter: observability.meter,
+            });
+            app.use("/api/*", globalRateLimitGuard);
+        }
+        if (options.rateLimit?.auth) {
+            const { path: l2Path = "/api/auth/*", ...l2Opts } = options.rateLimit.auth;
+            app.use(l2Path, authEndpointRateLimit({ ...l2Opts, resolver: rateLimitResolver, clientIpResolver }));
+        }
+    }
+    return globalRateLimitGuard;
+}
+export function installObservability(app, observability) {
+    // Observability span wraps everything that follows (auth, routes).
+    // Must come AFTER request-id (so span can carry the id) and BEFORE auth
+    // (so auth-verify can be a child span once we instrument it in v2).
+    app.use("/api/*", observabilityMiddleware({
+        tracer: observability.tracer,
+        meter: observability.meter,
+    }));
+}
+export function installPiiLeakGuard(app) {
+    // Tripwire: a kumiko-pii: ciphertext in a JSON response is always a bug
+    // (raw read leaked past a decrypt) — dev fails loud, prod redacts.
+    app.use("/api/*", piiCiphertextResponseGuard());
+}
+export function installAuthGuardChain(app, wiring, scope) {
+    const { options, jwt, baseDb } = wiring;
+    const { isPublicApiRequest, globalRateLimitGuard } = scope;
+    // Auth middleware skips public paths (login, health) — those routes need
+    // to be callable without a valid JWT. Every other /api/* request requires
+    // a token (or, when anonymousAccess is wired, falls through as anonymous).
+    // A session-checker is forwarded when the auth-config wires one, so the
+    // middleware can reject revoked sids on every request.
+    // Mounting a tenantLifecycleStatus provider is what turns the 410 on, so no
+    // entrypoint can forget the wiring; `??` short-circuits, so an explicit
+    // auth.resolveTenantLifecycleStatus remains the override.
+    const tenantLifecycleResolver = options.auth?.resolveTenantLifecycleStatus ??
+        deriveTenantLifecycleResolver(options.registry, baseDb);
+    // sessionOnlyGuard deliberately does NOT get this — its callers have no
+    // anonymousAccess fallback, so a foreign-origin cookie there must keep
+    // failing through the sibling originMiddleware 403.
+    const normalizedForeignCookieOrigins = options.auth?.allowedOrigins?.length
+        ? new Set(options.auth.allowedOrigins.map(normalizeOrigin))
+        : undefined;
+    const jwtGuard = buildJwtGuard(options, jwt, tenantLifecycleResolver, normalizedForeignCookieOrigins);
+    useOnProtectedApiPaths(app, isPublicApiRequest, jwtGuard);
+    // Fail-closed PAT scoping: a PAT-authenticated caller (user.pat set by
+    // jwtGuard's tokenVerifier above) may only reach the dispatcher routes —
+    // everywhere else on /api/* is off-limits regardless of granted scopes.
+    const patRouteGuardMiddleware = patRouteGuard();
+    useOnProtectedApiPaths(app, isPublicApiRequest, patRouteGuardMiddleware);
+    // Without anonymousAccess a missing token 401s instead of falling through as anonymous.
+    const sessionOnlyGuard = buildSessionOnlyGuard(options, jwt, tenantLifecycleResolver);
+    // PAT rate limiting — runs AFTER the auth guard so the resolved principal is
+    // available. Only PAT-authenticated requests are counted (keyed by token id);
+    // cookie/JWT users pass through untouched. In-memory limiter is per-instance
+    // (see run-prod-app) — a multi-node deployment wanting a shared counter swaps
+    // in a Redis-backed LoginRateLimiter.
+    const patRateLimiter = options.auth?.patRateLimiter;
+    const patRateLimitGuard = patRateLimiter ? buildPatRateLimitGuard(patRateLimiter) : undefined;
+    if (patRateLimitGuard) {
+        useOnProtectedApiPaths(app, isPublicApiRequest, patRateLimitGuard);
+    }
+    // Origin-allowlist guard — additional CSRF-hardening for deployments that
+    // widen the auth cookie across subdomains (auth.cookieDomain). Registered
+    // when allowedOrigins is non-empty, or with host-only cookies when
+    // auth.publicOrigin is known (see resolveOriginGuard), with the same /api/* + public-skip
+    // scope as the CSRF guard and BEFORE it, so a disallowed cross-site POST
+    // surfaces as `origin_not_allowed` rather than `csrf_token_mismatch`. Fails
+    // closed (assertOriginGuardConfig throws) when a wide cookieDomain is set
+    // without an allowlist and without an explicit opt-out — that config is the
+    // unguarded-subdomain-XSS footgun, not a warn-and-continue case.
+    assertOriginGuardConfig(options.auth);
+    assertSessionCallbacksPaired(options.auth);
+    const originGuard = resolveOriginGuard(options.auth);
+    if (originGuard) {
+        useOnProtectedApiPaths(app, isPublicApiRequest, originGuard);
+    }
+    // Double-submit CSRF guard — runs only on cookie-authenticated,
+    // state-changing requests (POST/PUT/PATCH/DELETE). The guard reads the
+    // authTransport flag set by authMiddleware, so public paths (no auth)
+    // and bearer-authenticated paths (no cookie vector) fall straight
+    // through. Must be registered AFTER the auth middleware above so the
+    // flag is populated; registered for the same scope so /api/* routes
+    // are covered uniformly.
+    const csrfGuard = csrfMiddleware();
+    useOnProtectedApiPaths(app, isPublicApiRequest, csrfGuard);
+    // No PAT rate-limit here: patRouteGuardMiddleware rejects every PAT on httpRoutes before it could count.
+    // httpRoutes sit outside /api/*, so the pre-auth /api/* middlewares do not run for them: the
+    // global IP limit (an unauthenticated flood must not reach JWT verify / session checks) and the
+    // PII ciphertext tripwire are re-attached here. requestId, body limit and observability are not.
+    const sessionOnlyHttpRouteGuards = [
+        ...(globalRateLimitGuard ? [globalRateLimitGuard] : []),
+        piiCiphertextResponseGuard(),
+        sessionOnlyGuard,
+        patRouteGuardMiddleware,
+        ...(originGuard ? [originGuard] : []),
+        csrfGuard,
+    ];
+    return { tenantLifecycleResolver, sessionOnlyHttpRouteGuards };
+}
+function useOnProtectedApiPaths(app, isPublicApiRequest, guard) {
+    app.use("/api/*", async (c, next) => {
+        if (isPublicApiRequest(c))
+            return next();
+        return guard(c, next);
+    });
+}
+function collectTenantlessAnonymousWriteQns(registry) {
+    return new Set([...registry.getAllWriteHandlers()]
+        .filter(([, handler]) => handler.tenantlessAnonymous === true)
+        .map(([qn]) => qn));
+}
+function buildJwtGuard(options, jwt, tenantLifecycleResolver, normalizedForeignCookieOrigins) {
+    const tenantlessAnonymousQns = collectTenantlessAnonymousWriteQns(options.registry);
+    return authMiddleware(jwt, {
+        ...(tenantlessAnonymousQns.size > 0
+            ? { isTenantlessAnonymousWrite: (qn) => tenantlessAnonymousQns.has(qn) }
+            : {}),
+        ...(options.auth?.sessionChecker ? { sessionChecker: options.auth.sessionChecker } : {}),
+        ...(options.auth?.tokenVerifier ? { tokenVerifier: options.auth.tokenVerifier } : {}),
+        ...(tenantLifecycleResolver ? { resolveTenantLifecycleStatus: tenantLifecycleResolver } : {}),
+        ...(options.anonymousAccess ? { anonymousAccess: options.anonymousAccess } : {}),
+        ...(normalizedForeignCookieOrigins
+            ? { foreignCookieOrigins: normalizedForeignCookieOrigins }
+            : {}),
+    });
+}
+function buildSessionOnlyGuard(options, jwt, tenantLifecycleResolver) {
+    return authMiddleware(jwt, {
+        ...(options.auth?.sessionChecker ? { sessionChecker: options.auth.sessionChecker } : {}),
+        ...(options.auth?.tokenVerifier ? { tokenVerifier: options.auth.tokenVerifier } : {}),
+        ...(tenantLifecycleResolver ? { resolveTenantLifecycleStatus: tenantLifecycleResolver } : {}),
+    });
+}
+// Must run after the auth guard so getUser(c) carries the PAT.
+function buildPatRateLimitGuard(patRateLimiter) {
+    return async (c, next) => {
+        const pat = getUser(c)?.pat;
+        if (pat && !(await patRateLimiter.check(pat.tokenId))) {
+            return c.json({
+                error: {
+                    code: "pat_rate_limited",
+                    httpStatus: 429,
+                    message: "personal access token rate limit exceeded",
+                    i18nKey: "auth.errors.patRateLimited",
+                },
+            }, 429);
+        }
+        return next();
+    };
+}
+function deriveTenantLifecycleResolver(registry, db) {
+    const plugin = resolveTenantLifecyclePlugin(registry, "buildServer");
+    if (!plugin)
+        return undefined;
+    if (!db) {
+        throw new Error("[kumiko] a tenantLifecycleStatus provider is mounted (tenant-lifecycle) but context.db is " +
+            "missing — the request-level teardown gate needs a DbConnection. Pass context.db, or wire " +
+            "auth.resolveTenantLifecycleStatus explicitly.");
+    }
+    return (tenantId) => plugin.resolveStatus(tenantId, { db });
+}

package/dist/api/server-routes.d.ts

@@ -0,0 +1,19 @@
+import type { Hono, MiddlewareHandler } from "hono";
+import type { HttpRouteMethod, SessionUser, TenantId } from "../engine/types/index.ts";
+import type { Dispatcher } from "../pipeline/dispatcher.ts";
+import { type ClientIpResolver } from "./client-ip.ts";
+import type { ServerOptions } from "./server.ts";
+import type { ServerWiring } from "./server-wiring.ts";
+import type { ResolvedSessionCookies } from "./session-cookies.ts";
+export declare function mountOperationalRoutes(app: Hono, wiring: Pick<ServerWiring, "options" | "baseDb" | "eventConsumers" | "observability" | "bootLog">): void;
+export declare function mountAuthRoutes(app: Hono, wiring: Pick<ServerWiring, "options" | "dispatcher" | "jwt" | "clientIpResolver">, sessionCookies: ResolvedSessionCookies): void;
+export declare function mountClientErrorRoute(app: Hono, wiring: Pick<ServerWiring, "rateLimitResolver" | "tracedRedis" | "clientIpResolver" | "observability" | "jwt">): void;
+export declare function mountDispatcherRoutes(app: Hono, wiring: Pick<ServerWiring, "options" | "dispatcher" | "sseBroker">): void;
+export declare function mountSchemaRoute(app: Hono, options: Pick<ServerOptions, "registry" | "dispatcherOptions" | "context">): void;
+export declare function mountFileRoutes(app: Hono, wiring: Pick<ServerWiring, "options" | "dispatcher" | "fileProviderResolver">): void;
+export declare function mountFeatureHttpRoutes(app: Hono, wiring: Pick<ServerWiring, "options" | "dispatcher" | "clientIpResolver" | "rateLimitResolver" | "observability">, sessionOnlyHttpRouteGuards: readonly MiddlewareHandler[]): void;
+export declare function installNoRouteMatchMarker(app: Hono): void;
+export declare function mountHonoRoute(app: Hono, method: HttpRouteMethod, path: string, handler: (c: import("hono").Context<any, any>) => Response | Promise<Response>, middlewares?: readonly MiddlewareHandler[]): void;
+export declare function makeSystemQuery(c: import("hono").Context<any, any>, dispatcher: Dispatcher, clientIpResolver?: ClientIpResolver): (type: string, payload: unknown, tenantId: TenantId) => Promise<unknown>;
+export declare function isMissingOrAnonymousUser(user: SessionUser | undefined): boolean;
+export declare function unauthenticatedResponse(c: import("hono").Context): Response;

package/dist/api/server-routes.js

@@ -0,0 +1,293 @@
+import { createProjectingTenantDb } from "../db/tenant-db.js";
+import { buildAppSchema } from "../engine/build-app-schema.js";
+import { projectAppSchemaForRoles } from "../engine/project-app-schema-for-roles.js";
+import { resolveDisabledFeatureNames, stripDisabledFeaturesFromAppSchema, } from "../engine/strip-disabled-features-from-app-schema.js";
+import { createAnonymousUser, isAnonymousSessionUser } from "../engine/system-user.js";
+import { createFileRoutes, readFilesRouteOptions } from "../files/file-routes.js";
+import { createRecordReadCheck } from "../files/record-read-check.js";
+import { createRecordWriteCheck } from "../files/record-write-check.js";
+import { createRateLimitResolver, httpRouteRateLimit } from "../rate-limit/index.js";
+import { assertUnreachable } from "../utils/index.js";
+import { collectAnonymousLiveEntities } from "./anonymous-live-entities.js";
+import { NO_ROUTE_MATCH_HEADER_NAME, Routes } from "./api-constants.js";
+import { getUser, identifyOptionalSession } from "./auth-middleware.js";
+import { createAuthRoutes } from "./auth-routes.js";
+import { createClientErrorRoute } from "./client-error-route.js";
+import { clientIpSourceFromHonoContext } from "./client-ip.js";
+import { collectEntityReadAccess } from "./entity-read-access.js";
+import { computeStrongEtag, etagMatches } from "./http-cache.js";
+import { requestContext } from "./request-context.js";
+import { buildRequestContextData } from "./request-id-middleware.js";
+import { registerHealthRoutes, registerMetricsRoute } from "./route-registrars.js";
+import { createApiRoutes } from "./routes.js";
+import { assertSinglePrincipalStatusProvider } from "./server-boot-checks.js";
+import { createSseRoute } from "./sse-route.js";
+export function mountOperationalRoutes(app, wiring) {
+    const { options, baseDb, eventConsumers, observability, bootLog } = wiring;
+    registerHealthRoutes(app, {
+        lifecycle: options.lifecycle,
+        readiness: {
+            db: baseDb,
+            redis: options.context.redis,
+            consumers: eventConsumers,
+            ...(options.readiness ?? {}),
+        },
+    });
+    if (options.metrics) {
+        registerMetricsRoute(app, observability.meter, options.metrics);
+    }
+    else if (process.env["NODE_ENV"] === "production") {
+        bootLog.warn("/metrics is off: no `metrics` option, so nothing is measured or scraped. " +
+            "Set PROMETHEUS_METRICS_TOKEN (min 32 chars) and spread resolveObservabilityWiring(token) into the server options.");
+    }
+}
+export function mountAuthRoutes(app, wiring, sessionCookies) {
+    const { options, dispatcher, jwt, clientIpResolver } = wiring;
+    if (options.auth) {
+        assertSinglePrincipalStatusProvider(options.registry, options.auth);
+        app.route("/api", createAuthRoutes(dispatcher, jwt, {
+            ...options.auth,
+            secureCookies: sessionCookies.secure,
+            resolver: clientIpResolver,
+        }));
+    }
+}
+export function mountClientErrorRoute(app, wiring) {
+    const { rateLimitResolver, tracedRedis, clientIpResolver, observability, jwt } = wiring;
+    app.route("/api", createClientErrorRoute({
+        resolver: rateLimitResolver ??
+            (tracedRedis ? createRateLimitResolver({ redis: tracedRedis }) : undefined),
+        clientIpResolver,
+        meter: observability.meter,
+        identifySession: (c) => identifyOptionalSession(c, jwt),
+    }));
+}
+export function mountDispatcherRoutes(app, wiring) {
+    const { options, dispatcher, sseBroker } = wiring;
+    app.route("/api", createApiRoutes(dispatcher, {
+        ...(options.sseHeartbeatMs !== undefined ? { sseHeartbeatMs: options.sseHeartbeatMs } : {}),
+    }));
+    app.route("/api", createSseRoute(sseBroker, {
+        anonymousLiveEntities: collectAnonymousLiveEntities(options.registry),
+        entityReadAccess: collectEntityReadAccess(options.registry),
+    }));
+}
+export function mountSchemaRoute(app, options) {
+    // GET /api/schema — the only way a client obtains the AppSchema. Behind
+    // jwtGuard (NON_PUBLIC_API_PATHS), so anonymousAccess's synthesised user
+    // also gets rejected below — the schema never reaches an unauthenticated
+    // caller. The FULL schema is built lazily once — the registry is
+    // immutable for this server's lifetime, so it's the same on every
+    // request — then projected per caller-role-set (a role only
+    // sees the screens/navs/workspaces/content-collections it may reach,
+    // not the whole app's schema) and cached per role key. Tenant is
+    // deliberately NOT part of the key: the projection depends only on
+    // roles, and per-tenant caching would grow unboundedly across tenants
+    // that share the same role set. What IS part of the key: the sorted set of
+    // features the caller's tenant has switched off (r.toggleable) — few
+    // distinct sets, so the cache stays small. The resolver is read per request
+    // because run{Dev,Prod}App fill it in after the server is built.
+    let fullSchema;
+    const projectedSchemaCache = new Map();
+    app.get(`/api${Routes.schema}`, async (c) => {
+        const user = getUser(c);
+        if (isMissingOrAnonymousUser(user)) {
+            return unauthenticatedResponse(c);
+        }
+        const effectiveFeatures = options.dispatcherOptions?.effectiveFeatures;
+        const disabledFeatureNames = effectiveFeatures === undefined
+            ? []
+            : await resolveDisabledFeatureNames(options.registry, effectiveFeatures, user.tenantId);
+        const roleKey = JSON.stringify([[...new Set(user?.roles ?? [])].sort(), disabledFeatureNames]);
+        let cached = projectedSchemaCache.get(roleKey);
+        if (cached === undefined) {
+            if (fullSchema === undefined) {
+                fullSchema = buildAppSchema(options.registry, {
+                    searchAdapterMissing: !options.context.searchAdapter,
+                });
+            }
+            const projected = projectAppSchemaForRoles(stripDisabledFeaturesFromAppSchema(fullSchema, options.registry, disabledFeatureNames), user?.roles ?? []);
+            const json = JSON.stringify(projected);
+            cached = { json, etag: computeStrongEtag(json) };
+            projectedSchemaCache.set(roleKey, cached);
+        }
+        const cacheHeaders = { "Cache-Control": "private, no-cache", ETag: cached.etag };
+        if (etagMatches(c.req.header("If-None-Match") ?? null, cached.etag)) {
+            return c.body(null, 304, cacheHeaders);
+        }
+        return c.body(cached.json, 200, {
+            "Content-Type": "application/json; charset=utf-8",
+            ...cacheHeaders,
+        });
+    });
+}
+export function mountFileRoutes(app, wiring) {
+    const { options, dispatcher, fileProviderResolver } = wiring;
+    // Mount upload/download routes whenever a file provider is resolvable (a
+    // file-provider plugin is mounted, or a resolver was injected). They resolve
+    // the provider per-tenant through file-foundation — no `files` option; route
+    // policy comes from createFilesFeature(opts?). Gating on the resolver (not on
+    // declared file fields) keeps unattached uploads working and matches the old
+    // "files option present → routes" behavior.
+    if (fileProviderResolver) {
+        const fileDb = options.context.db; // @cast-boundary engine-bridge
+        if (!fileDb)
+            throw new Error("file routes require db in context");
+        const routeOptions = readFilesRouteOptions(options.registry);
+        const canReadRecord = createRecordReadCheck(options.registry, dispatcher.query);
+        app.route("/api", createFileRoutes({
+            db: fileDb,
+            registry: options.registry,
+            resolveProvider: fileProviderResolver,
+            canReadRecord,
+            canWriteRecord: createRecordWriteCheck({
+                registry: options.registry,
+                canReadRecord,
+                tenantDbFor: (tenantId) => createProjectingTenantDb(fileDb, tenantId, options.registry),
+            }),
+            ...(routeOptions.accessGuard ? { accessGuard: routeOptions.accessGuard } : {}),
+            ...(routeOptions.privilegedRoles ? { privilegedRoles: routeOptions.privilegedRoles } : {}),
+            ...(routeOptions.unclaimedUploadReaders
+                ? { unclaimedUploadReaders: routeOptions.unclaimedUploadReaders }
+                : {}),
+            ...(routeOptions.maxUploadSize ? { maxUploadSize: routeOptions.maxUploadSize } : {}),
+        }));
+    }
+}
+export function mountFeatureHttpRoutes(app, wiring, sessionOnlyHttpRouteGuards) {
+    // Feature-declared HTTP routes (r.httpRoute). Mount after /api/* so /api/* always
+    // takes precedence; feature routes must be outside that prefix (the boot validator
+    // enforces this). deps.app is the outer app, so the handler can call /api/query
+    // internally through app.fetch(...) and use the same auth path as a real HTTP call.
+    // deps.systemQuery deliberately bypasses that path for routes that must enforce a
+    // FIXED tenant (for example, legal-pages always uses SYSTEM_TENANT_ID), rather than
+    // spoofing it through the X-Tenant header. That header looks like a normal client
+    // header to anonymousAccess resolution, so resolverTrust: "authoritative" configs
+    // correctly reject it as a tenant override.
+    for (const feature of wiring.options.registry.features.values()) {
+        for (const route of Object.values(feature.httpRoutes)) {
+            mountFeatureHttpRoute(app, route, wiring, sessionOnlyHttpRouteGuards);
+        }
+    }
+}
+function mountFeatureHttpRoute(app, route, wiring, sessionOnlyHttpRouteGuards) {
+    const { dispatcher, clientIpResolver, rateLimitResolver, observability } = wiring;
+    // @wrapper-known semantic-alias
+    const honoHandler = async (c) => route.handler(c, {
+        app,
+        // createAnonymousUser, NOT createSystemUser: systemQuery's
+        // synthesized user must clear the SAME access gate a real
+        // anonymous visitor would, no more — regardless of the route's
+        // own `anonymous` mode. The system role would ALSO satisfy that
+        // gate here, but it can read fields gated to "system" that
+        // "anonymous" can't (filterReadFields is a plain role-in-map
+        // check) — a systemQuery caller reading a system-gated field
+        // would leak it into the response. The forced tenant already
+        // comes from bypassing the HTTP layer entirely; no elevated
+        // role is needed or wanted on top of that.
+        systemQuery: makeSystemQuery(c, dispatcher, clientIpResolver),
+        clientIp: clientIpResolver.resolve(clientIpSourceFromHonoContext(c)),
+    });
+    // Without a resolver (no Redis in the context — dev/test stacks) the
+    // declared limit is skipped rather than failing the boot of every app
+    // that mounts a bundled feature whose routes carry a default limit.
+    const routeLimit = route.rateLimit && rateLimitResolver
+        ? [
+            httpRouteRateLimit({
+                resolver: rateLimitResolver,
+                rateLimit: route.rateLimit,
+                routeKey: `${route.method} ${route.path}`,
+                clientIpResolver,
+                meter: observability.meter,
+            }),
+        ]
+        : [];
+    mountHonoRoute(app, route.method, route.path, honoHandler, [
+        ...routeLimit,
+        ...(route.anonymous ? [] : sessionOnlyHttpRouteGuards),
+    ]);
+}
+export function installNoRouteMatchMarker(app) {
+    // Marks "no route matched this path" so tryHonoFirst (server-runtime)
+    // can tell it apart from a matched route's OWN deliberate 404 (e.g.
+    // default-deny reads like file-derivatives' public-variant route) —
+    // without this, tryHonoFirst's only signal was the status code, and a
+    // matched route answering 404 got silently rewritten to the SPA shell
+    // with status 200. Must be the LAST thing wired
+    // on `app`: this only fires when the router found no handler at all, so
+    // a route's own `c.text(..., 404)` never passes through here. A handler
+    // that calls `c.notFound()` instead of building its own Response DOES
+    // route through this same handler and stays indistinguishable from a
+    // routing miss — pre-existing Hono semantics, not something this fix
+    // changes; deliberate 404s must build their own Response.
+    // The header is an internal signal only — tryHonoFirst and every direct
+    // app.fetch() passthrough strip it before a response reaches a client.
+    app.notFound((c) => c.text("Not Found", 404, { [NO_ROUTE_MATCH_HEADER_NAME]: "1" }));
+}
+// Method-switch shared by r.httpRoute and extraRoutes — one place to keep
+// the two mounting paths from drifting on which Hono methods get a
+// convenience-call vs. app.on().
+export function mountHonoRoute(app, method, path, 
+// biome-ignore lint/suspicious/noExplicitAny: Hono context generics are invisible at the framework boundary
+handler, middlewares = []) {
+    // Guards go into the route's own handler chain, never a method-gated
+    // app.use: Hono serves HEAD through the GET route with c.req.method still
+    // "HEAD", so a `method === c.req.method` gate would skip them for HEAD.
+    if (middlewares.length > 0) {
+        // [path]: only Hono's array-path overload accepts a variable-length handler spread.
+        app.on(method, [path], ...middlewares, handler);
+        // skip: guarded route already mounted with its guard chain
+        return;
+    }
+    switch (method) {
+        case "GET":
+            app.get(path, handler);
+            break;
+        case "POST":
+            app.post(path, handler);
+            break;
+        case "PUT":
+            app.put(path, handler);
+            break;
+        case "PATCH":
+            app.patch(path, handler);
+            break;
+        case "DELETE":
+            app.delete(path, handler);
+            break;
+        case "OPTIONS":
+        case "HEAD":
+            // Hono's on() for the methods without a convenience method.
+            app.on(method, path, handler);
+            break;
+        default:
+            assertUnreachable(method, "http method");
+    }
+}
+// Shared systemQuery builder for r.httpRoute and extraRoutes (anonymous +
+// signature entries). requestContext.run must wrap the dispatcher call —
+// both route kinds run outside the requestIdMiddleware chain that normally
+// populates it, and `rateLimit: {per: "ip", ...}` on a handler invoked
+// through systemQuery is otherwise silent dead-code (enforceRateLimit reads
+// requestContext.get()?.ip, undefined without this wrap).
+export function makeSystemQuery(
+// biome-ignore lint/suspicious/noExplicitAny: Hono context generics are invisible at the framework boundary
+c, dispatcher, clientIpResolver) {
+    return (type, payload, tenantId) => requestContext.run(requestContext.get() ?? buildRequestContextData(c, clientIpResolver), () => dispatcher.query(type, payload, createAnonymousUser(tenantId)));
+}
+// Shared by entry:"user" extra routes and GET /api/schema — both require a
+// real, signed-in principal and reject the synthesised anonymousAccess user
+// (SessionUser.roles includes ANONYMOUS_ROLE) the same way.
+export function isMissingOrAnonymousUser(user) {
+    return !user || isAnonymousSessionUser(user);
+}
+export function unauthenticatedResponse(c) {
+    return c.json({
+        error: {
+            code: "unauthenticated",
+            httpStatus: 401,
+            message: "this route requires a signed-in user",
+            i18nKey: "auth.errors.missingToken",
+        },
+    }, 401);
+}

package/dist/api/server-websocket-routes.d.ts

@@ -0,0 +1,4 @@
+import type { Hono } from "hono";
+import { type TenantLifecycleStatusResolver } from "./auth-middleware.ts";
+import type { ServerWiring } from "./server-wiring.ts";
+export declare function mountWebSocketRoutes(app: Hono, wiring: Pick<ServerWiring, "options" | "dispatcher" | "clientIpResolver">, tenantLifecycleResolver: TenantLifecycleStatusResolver | undefined): void;

package/dist/api/server-websocket-routes.js

@@ -0,0 +1,108 @@
+import { createFallbackLogger } from "../logging/index.js";
+import { getAuthTokenExpiry, getUser, } from "./auth-middleware.js";
+import { clientIpSourceFromHonoContext } from "./client-ip.js";
+import { isWebSocketOriginAllowed, normalizeOrigin, rejectOrigin } from "./origin-middleware.js";
+import { requestContext } from "./request-context.js";
+import { isMissingOrAnonymousUser, unauthenticatedResponse } from "./server-routes.js";
+import { buildWebSocketSessionRevalidator, createWebSocketConnectionLimiter, hasWebSocketUpgradeServer, isWebSocketUpgradeRequest, WEBSOCKET_DEFAULT_MAX_CONNECTIONS_PER_USER, WEBSOCKET_DEFAULT_MAX_MESSAGE_BYTES, } from "./websocket-route.js";
+export function mountWebSocketRoutes(app, wiring, tenantLifecycleResolver) {
+    const { options, dispatcher, clientIpResolver } = wiring;
+    // r.webSocketRoute — GET routes under /api/ws/*, so the jwt/pat/rate-limit
+    // chain above already ran. Origin/CSRF guards skip GETs, hence the own check.
+    const webSocketOriginAllowlist = options.auth?.allowedOrigins?.length
+        ? new Set(options.auth.allowedOrigins.map(normalizeOrigin))
+        : undefined;
+    const webSocketRoutePaths = new Map();
+    const webSocketConnectionLimiter = createWebSocketConnectionLimiter();
+    for (const feature of options.registry.features.values()) {
+        for (const route of Object.values(feature.webSocketRoutes)) {
+            const owner = webSocketRoutePaths.get(route.path);
+            if (owner !== undefined) {
+                throw new Error(`[kumiko] WebSocket route "${route.path}" is declared by both feature "${owner}" and ` +
+                    `"${feature.name}" — paths must be unique across features.`);
+            }
+            webSocketRoutePaths.set(route.path, feature.name);
+            app.get(route.path, buildWebSocketRouteHandler(route, {
+                dispatcher,
+                clientIpResolver,
+                originAllowlist: webSocketOriginAllowlist,
+                ...(options.auth?.sessionChecker ? { sessionChecker: options.auth.sessionChecker } : {}),
+                ...(tenantLifecycleResolver
+                    ? { resolveTenantLifecycleStatus: tenantLifecycleResolver }
+                    : {}),
+                connectionLimiter: webSocketConnectionLimiter,
+            }));
+        }
+    }
+}
+const webSocketLog = createFallbackLogger("websocket");
+function webSocketErrorResponse(c, status, code, message) {
+    return c.json({ error: { code, httpStatus: status, message } }, status);
+}
+function buildWebSocketRouteHandler(route, shared) {
+    return async (c) => {
+        if (!isWebSocketOriginAllowed(c, shared.originAllowlist))
+            return rejectOrigin(c);
+        const user = getUser(c);
+        if (isMissingOrAnonymousUser(user))
+            return unauthenticatedResponse(c);
+        if (!isWebSocketUpgradeRequest(c.req.raw)) {
+            return webSocketErrorResponse(c, 426, "websocket_upgrade_required", "this route only accepts WebSocket upgrade requests");
+        }
+        const honoEnv = c.env;
+        if (!hasWebSocketUpgradeServer(honoEnv)) {
+            const message = "webSocketUpgradeFetch not wired: pass it to buildBunServeOptions";
+            webSocketLog.error(message, { path: route.path });
+            return webSocketErrorResponse(c, 501, "websocket_upgrade_not_wired", message);
+        }
+        // The slot is taken before connect (a refused attempt must not run it) and stays synchronous with
+        // the check, so concurrent upgrades can't overshoot the cap. Every path without a live socket frees it.
+        const releaseConnectionSlot = shared.connectionLimiter.tryAcquire(`${route.path}\n${user.tenantId}\n${user.id}`, route.maxConnectionsPerUser ?? WEBSOCKET_DEFAULT_MAX_CONNECTIONS_PER_USER);
+        if (!releaseConnectionSlot) {
+            return webSocketErrorResponse(c, 429, "websocket_connection_limit", "too many open WebSocket connections for this user");
+        }
+        let upgraded = false;
+        try {
+            const handlers = await route.connect(c, {
+                user,
+                query: (type, payload) => shared.dispatcher.query(type, payload, user),
+                write: (type, payload) => shared.dispatcher.write(type, payload, user),
+                clientIp: shared.clientIpResolver.resolve(clientIpSourceFromHonoContext(c)),
+            });
+            if (handlers instanceof Response)
+                return handlers;
+            const captured = requestContext.get();
+            const requestContextData = captured ? withoutAbortSignal(captured) : undefined;
+            const revalidateSession = buildWebSocketSessionRevalidator({
+                user,
+                sessionChecker: shared.sessionChecker,
+                resolveTenantLifecycleStatus: shared.resolveTenantLifecycleStatus,
+                tokenExpiresAtSec: getAuthTokenExpiry(c),
+            });
+            upgraded = honoEnv.server.upgrade(c.req.raw, {
+                data: {
+                    handlers,
+                    maxMessageBytes: route.maxMessageBytes ?? WEBSOCKET_DEFAULT_MAX_MESSAGE_BYTES,
+                    requestContextData,
+                    revalidateSession,
+                    releaseConnectionSlot,
+                },
+            });
+            if (!upgraded) {
+                return webSocketErrorResponse(c, 400, "websocket_upgrade_failed", "the WebSocket upgrade was rejected");
+            }
+            // Bun ignores the returned Response after a successful upgrade.
+            return new Response(null);
+        }
+        finally {
+            if (!upgraded)
+                releaseConnectionSlot();
+        }
+    };
+}
+// The request's AbortSignal fires when the upgrade request ends, which would
+// abort every later handler running under the captured context.
+function withoutAbortSignal(data) {
+    const { signal: _signal, ...rest } = data;
+    return rest;
+}