@cosmicdrift/kumiko-framework 0.387.0 → 0.389.0

package/dist/api/server-routes.js

@@ -0,0 +1,299 @@
+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, collectEntityRowReadMaps } from "./entity-read-access.js";
+import { createExportRoutes } from "./export/export-route.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", createExportRoutes(dispatcher, options.registry));
+    app.route("/api", createSseRoute(sseBroker, {
+        anonymousLiveEntities: collectAnonymousLiveEntities(options.registry),
+        entityReadAccess: collectEntityReadAccess(options.registry),
+        entityRowReadMaps: collectEntityRowReadMaps(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, rateLimitResolver, tracedRedis } = wiring;
+    const metaBatchRateLimitResolver = rateLimitResolver ??
+        (tracedRedis ? createRateLimitResolver({ redis: tracedRedis }) : undefined);
+    // 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,
+            ...(metaBatchRateLimitResolver ? { metaBatchRateLimitResolver } : {}),
+            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;
+}

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

@@ -0,0 +1,32 @@
+import type { CacheSyncBus } from "@cosmicdrift/kumiko-types/cache-sync-types";
+import type { DbConnection } from "../db/connection.ts";
+import type { AppContext, Registry } from "../engine/types/index.ts";
+import { type ObservabilityProvider } from "../observability/index.ts";
+import { type Dispatcher } from "../pipeline/dispatcher.ts";
+import type { EventConsumer, EventDispatcher } from "../pipeline/event-dispatcher.ts";
+import { type LifecycleHooks } from "../pipeline/lifecycle-pipeline.ts";
+import { type ClientIpResolver } from "./client-ip.ts";
+import { type JwtHelper } from "./jwt.ts";
+import type { ServerOptions } from "./server.ts";
+import { type BootLogger } from "./server-boot-checks.ts";
+import type { SseBroker } from "./sse-broker.ts";
+export declare function withFileProviderResolver(registry: Registry, context: AppContext, cacheSync?: CacheSyncBus): AppContext;
+export type ServerWiring = {
+    readonly options: ServerOptions;
+    readonly bootLog: BootLogger;
+    readonly clientIpResolver: ClientIpResolver;
+    readonly jwt: JwtHelper;
+    readonly sseBroker: SseBroker;
+    readonly observability: ObservabilityProvider;
+    readonly tracedRedis: AppContext["redis"];
+    readonly rateLimitResolver: AppContext["rateLimit"];
+    readonly rateLimitMiddlewareRequested: boolean;
+    readonly context: AppContext;
+    readonly fileProviderResolver: AppContext["_fileProviderResolver"];
+    readonly dispatcher: Dispatcher;
+    readonly lifecycleHooks: LifecycleHooks;
+    readonly baseDb: DbConnection | undefined;
+    readonly eventConsumers: readonly EventConsumer[];
+    readonly eventDispatcher: EventDispatcher | undefined;
+};
+export declare function resolveServerWiring(options: ServerOptions): ServerWiring;