@cosmicdrift/kumiko-framework 0.386.0 → 0.388.0

package/dist/api/server-boot-checks.js

@@ -0,0 +1,157 @@
+import { EXT_FILE_PROVIDER, EXT_PRINCIPAL_STATUS } from "../engine/extension-names.js";
+import { isFileField } from "../engine/types/index.js";
+import { SHARED_INSTANCE_SENTINEL } from "../pipeline/event-consumer-state.js";
+import { generateId } from "../utils/index.js";
+// A payload-bucket handler without a resolver would answer every call with a
+// 500 at request time; fail at boot instead.
+export function assertNoPayloadRateLimitsWithoutResolver(registry) {
+    const offenders = [];
+    for (const feature of registry.features.values()) {
+        for (const [name, handler] of Object.entries(feature.writeHandlers)) {
+            if (handler.additionalRateLimits !== undefined) {
+                offenders.push(`${feature.name}:write:${name}`);
+            }
+        }
+    }
+    // skip: every handler's payload buckets are covered by the resolver
+    if (offenders.length === 0)
+        return;
+    throw new Error(`Handlers declare additionalRateLimits but no RateLimitResolver is configured: ${offenders.join(", ")}. ` +
+        "Wire a Redis client on context.redis (or pass context.rateLimit), or drop the payload buckets " +
+        "(for the waitlist: emailRateLimits: []).");
+}
+export function assertFileStorageProviderForFileFields(registry, context) {
+    // File-storage is resolved per-tenant through file-foundation: a mounted
+    // `file-provider-*` plugin (inmemory/s3/s3-env) is the single source for
+    // uploads, ctx.files and the GDPR jobs.
+    const hasFileProvider = registry.getExtensionUsages(EXT_FILE_PROVIDER).length > 0;
+    // A test/advanced caller may inject the resolver directly on the context
+    // (e.g. a static in-memory provider) instead of mounting a provider plugin.
+    const hasInjectedResolver = context._fileProviderResolver !== undefined;
+    // Hard-fail when the registry declares file/image fields but no provider
+    // plugin is mounted — uploads would otherwise fail at the first request
+    // instead of at boot. Proves a plugin is mounted, not that each tenant
+    // selected one; per-tenant misconfig surfaces via createFileProviderForTenant.
+    if (registryDeclaresFileFields(registry) && !hasFileProvider && !hasInjectedResolver) {
+        throw new Error("Features declare file/image fields but no file-storage provider is mounted — " +
+            "mount `file-foundation` + a `file-provider-*` feature (inmemory/s3/s3-env) and " +
+            "select one per tenant via the 'file-foundation:config:provider' config-key.");
+    }
+}
+export function warnSearchableScreensWithoutSearchAdapter(registry, context, bootLog) {
+    // A screen whose search box renders (kumiko-screen.tsx gates it on
+    // `screen.searchable ?? entity-has-searchable-field`, the same condition
+    // as entitiesWithSearchableScreen) sends `payload.search` on every query. Without a
+    // context.searchAdapter that throws UnprocessableError at request time
+    // — surface the misconfig at boot instead of on the first search.
+    // Warn, not throw: unlike missing file-storage (uploads always fail),
+    // list screens still work without search: only the search box is broken.
+    // Several deployed apps (offlot-app, publicstatus, kumiko-studio,
+    // kumiko-enterprise) currently run in exactly this state.
+    if (!context.searchAdapter) {
+        const unwiredEntities = entitiesWithSearchableScreen(registry);
+        if (unwiredEntities.length > 0) {
+            bootLog.warn(`${unwiredEntities.length} entit${unwiredEntities.length === 1 ? "y" : "ies"} ` +
+                `have a searchable list screen but no SearchAdapter is wired on context.searchAdapter: ` +
+                `${unwiredEntities.join(", ")}. Search requests against ${unwiredEntities.length === 1 ? "it" : "them"} will fail with a 422 (search_adapter_not_wired) at runtime. ` +
+                "Wire a SearchAdapter (e.g. createMeilisearchAdapter) on context.searchAdapter, or remove `searchable: true` from the affected fields.");
+        }
+    }
+}
+export function resolveServerInstanceId(explicitInstanceId, bootLog) {
+    // Resolve the per-process instance identifier. Prefer explicit
+    // ServerOptions.instanceId (tests, deliberate wiring), fall back to the
+    // deploy-env variable, finally a boot-time UUID. Validator rejects the
+    // sentinel — a deliberate collision attempt would silently merge this
+    // instance's per-instance cursors with the shared-row cursors and
+    // deliver events twice to one shard while starving the other.
+    const resolvedInstanceId = explicitInstanceId ?? process.env["KUMIKO_INSTANCE_ID"] ?? generateId();
+    if (resolvedInstanceId === SHARED_INSTANCE_SENTINEL) {
+        throw new Error(`ServerOptions.instanceId / KUMIKO_INSTANCE_ID cannot equal the reserved sentinel "${SHARED_INSTANCE_SENTINEL}" — ` +
+            `pick any other stable string.`);
+    }
+    // Warn when we fell back to a random UUID. The built-in SSE consumer is
+    // delivery="shared" (one cursor for all pods), so it no longer
+    // writes a row per instance. The id still labels this process in the
+    // app.started event and in per-instance consumers (opt-in delivery), where a
+    // fresh id per boot leaves an orphaned cursor-row that pins pruneEvents
+    // (retention-guard uses MIN(lastProcessedEventId) across all shards). Silent
+    // when explicitInstanceId or KUMIKO_INSTANCE_ID is explicit — those are
+    // deliberate choices (the test suite sets KUMIKO_INSTANCE_ID="test-instance").
+    const instanceIdWasRandom = explicitInstanceId === undefined && !process.env["KUMIKO_INSTANCE_ID"];
+    if (instanceIdWasRandom) {
+        bootLog.warn(`No ServerOptions.instanceId / KUMIKO_INSTANCE_ID set — generated a random UUID (${resolvedInstanceId}). ` +
+            `SSE no longer needs a per-instance cursor, but the id labels this process in the app.started event and in per-instance consumers; without a stable id each restart leaves an orphaned cursor-row behind for those and pins events-retention on its last cursor. ` +
+            `Set KUMIKO_INSTANCE_ID to the pod name (e.g. from the Kubernetes downward API metadata.name) in production.`);
+    }
+    return resolvedInstanceId;
+}
+export function warnUnlimitedSystemScopeFeatures(registry, bootLog) {
+    // The systemScope default limit only exists once a resolver does, and an app that
+    // declared no explicit rateLimit anywhere never gets one auto-wired (wantsL3 stays
+    // false) — so its cross-tenant handlers are silently unlimited.
+    const unlimitedSystemScopeFeatures = [...registry.features.values()]
+        .filter((feature) => feature.systemScope &&
+        Object.keys(feature.writeHandlers).length + Object.keys(feature.queryHandlers).length > 0)
+        .map((feature) => feature.name);
+    if (unlimitedSystemScopeFeatures.length > 0) {
+        bootLog.warn(`r.systemScope() features have handlers but no RateLimitResolver is configured, ` +
+            `so their default rate limit is not enforced: ${unlimitedSystemScopeFeatures.join(", ")}. ` +
+            "Wire a Redis client on context.redis and declare rateLimit on at least one handler (or pass " +
+            "context.rateLimit) to enable the resolver.");
+    }
+}
+export function assertSinglePrincipalStatusProvider(registry, auth) {
+    // A membershipQuery handler is registered but principalStatus is not provided by exactly
+    // one feature — surface that misconfig at boot instead of an InternalError on first login/switch-tenant.
+    if (registry.getQueryHandler(auth.membershipQuery)) {
+        const principalStatusProviders = registry.getExtensionUsages(EXT_PRINCIPAL_STATUS).length;
+        if (principalStatusProviders === 0) {
+            throw new Error(`[kumiko] auth membershipQuery "${auth.membershipQuery}" is registered but no feature ` +
+                'provides the "principalStatus" contract — mount the user feature (tenant switch and sign-in ' +
+                "need it to reject blocked principals).");
+        }
+        if (principalStatusProviders > 1) {
+            throw new Error(`[kumiko] auth membershipQuery "${auth.membershipQuery}" is registered but ` +
+                `${principalStatusProviders} features provide the "principalStatus" contract — exactly one ` +
+                "is expected (the bundled user feature already provides it).");
+        }
+    }
+}
+// Scans every feature's entities for a file/image/files/images field. Short-
+// circuits on the first hit — no need to build a full inventory, we only want
+// the yes/no answer for the boot check.
+function registryDeclaresFileFields(registry) {
+    for (const feature of registry.features.values()) {
+        for (const entity of Object.values(feature.entities ?? {})) {
+            for (const field of Object.values(entity.fields)) {
+                if (isFileField(field))
+                    return true;
+            }
+        }
+    }
+    return false;
+}
+// Entities whose entityList screen WOULD render a search box based on
+// screen/field config alone: `screen.searchable` wins when set, otherwise
+// the box shows iff the entity has ≥1 searchable field. `screen.searchable
+// === false` is excluded — the boot-validator (entity-list-screens.ts) only
+// allows that on the whitelisted download-attempt-list-style screens, which
+// never render the box. This is the config-only half of the rule; the
+// client additionally gates on FeatureSchema.searchAdapterMissing
+// (set from the same `!options.context.searchAdapter` check in mountSchemaRoute) so the
+// box is actually suppressed once this function finds a hit.
+function entitiesWithSearchableScreen(registry) {
+    const entities = new Set();
+    for (const feature of registry.features.values()) {
+        for (const screen of Object.values(feature.screens)) {
+            if (screen.type !== "entityList")
+                continue;
+            const isSearchable = screen.searchable === true ||
+                (screen.searchable === undefined && registry.getSearchableFields(screen.entity).length > 0);
+            if (isSearchable)
+                entities.add(screen.entity);
+        }
+    }
+    return [...entities];
+}

package/dist/api/server-event-dispatcher.d.ts

@@ -0,0 +1,26 @@
+import type { DbConnection } from "../db/connection.ts";
+import type { AppContext } from "../engine/types/index.ts";
+import type { Lifecycle } from "../lifecycle/index.ts";
+import type { ObservabilityProvider } from "../observability/index.ts";
+import { type EventConsumer, type EventDispatcher } from "../pipeline/event-dispatcher.ts";
+import type { ResolvedCacheSyncBus } from "../redis/cache-sync-bus.ts";
+import type { RedisSseBroker } from "./redis-sse-broker.ts";
+import type { ServerOptions } from "./server.ts";
+import type { SseBroker } from "./sse-broker.ts";
+export declare function createServerEventDispatcher(deps: {
+    readonly options: Pick<ServerOptions, "registry" | "eventDispatcher" | "dispatcherOptions" | "processLane">;
+    readonly context: AppContext;
+    readonly sseBroker: SseBroker;
+    readonly observability: ObservabilityProvider;
+    readonly fileProviderResolver: AppContext["_fileProviderResolver"];
+    readonly instanceId: string;
+}): {
+    readonly baseDb: DbConnection | undefined;
+    readonly consumers: readonly EventConsumer[];
+    readonly eventDispatcher: EventDispatcher | undefined;
+};
+export declare function registerOwnedShutdownHooks(lifecycle: Lifecycle | undefined, owned: {
+    readonly eventDispatcher: EventDispatcher | undefined;
+    readonly ownedRedisSseBroker: RedisSseBroker | undefined;
+    readonly ownedCacheSync: ResolvedCacheSyncBus["owned"];
+}): void;

package/dist/api/server-event-dispatcher.js

@@ -0,0 +1,208 @@
+import { withExecutorManagedWrites } from "../db/tenant-db.js";
+import { createDerivativesContext } from "../derivatives/derivatives-context.js";
+import { runsInLane } from "../engine/run-in.js";
+import { createTenantFileContext } from "../files/file-handle.js";
+import { createEventDispatcher, } from "../pipeline/event-dispatcher.js";
+import { createMultiStreamApplyContext } from "../pipeline/multi-stream-apply-context.js";
+import { createAccessInvalidationEventConsumer, createJobTriggerEventConsumer, createSearchEventConsumer, createSseBroadcastEventConsumer, } from "../pipeline/system-hooks.js";
+import { deriveSearchAdapterConfig } from "../search/derive-search-adapter-config.js";
+export function createServerEventDispatcher(deps) {
+    const { options, context, sseBroker, observability, fileProviderResolver, instanceId } = deps;
+    // Async event-dispatcher — the replacement for the old transactional
+    // outbox. Consumer sources:
+    //   1. System: SSE broadcast (iff sseBroker), Search index (iff
+    //      context.searchAdapter).
+    //   2. Features: every r.multiStreamProjection registered in the registry
+    //      becomes its own consumer row with an independent cursor. The MSP
+    //      apply map is routed by event.type; apply receives the raw DbRunner
+    //      of a TX-scoped, tenant-bound DB handle so per-tenant writes stay
+    //      isolated.
+    //
+    // The dispatcher is built but NOT started here. Production boot code
+    // must call `.start()`; test code typically calls `.runOnce()`.
+    const { baseDb, searchAdapter } = resolveBaseDbAndSearchAdapter(context, options.registry);
+    const systemConsumers = buildSystemEventConsumers(options, sseBroker, searchAdapter);
+    const mspConsumers = buildMultiStreamProjectionConsumers(options, {
+        baseDb,
+        context,
+        fileProviderResolver,
+    });
+    const consumers = [...systemConsumers, ...mspConsumers];
+    const { disabled: dispatcherDisabled, systemConsumers: _systemConsumersOpt, ...dispatcherTunables } = options.eventDispatcher ?? {};
+    let eventDispatcher;
+    if (consumers.length > 0 && baseDb && !dispatcherDisabled) {
+        eventDispatcher = createEventDispatcher({
+            db: baseDb,
+            consumers,
+            context,
+            tracer: observability.tracer,
+            meter: observability.meter,
+            instanceId,
+            ...dispatcherTunables,
+        });
+    }
+    return { baseDb, consumers, eventDispatcher };
+}
+function resolveBaseDbAndSearchAdapter(context, registry) {
+    // @cast-boundary engine-bridge — context.db union narrows to DbConnection here
+    const baseDb = context.db;
+    // @cast-boundary engine-bridge — searchAdapter is an optional context-extension
+    const searchAdapter = context.searchAdapter;
+    // Adapter is built before the registry exists (app boot order) — hand it
+    // the registry-derived default config here so it can lazily configure
+    // each tenant index on first access instead of requiring per-tenant app
+    // wiring.
+    const derivedSearchConfig = searchAdapter ? deriveSearchAdapterConfig(registry) : undefined;
+    if (searchAdapter && derivedSearchConfig) {
+        searchAdapter.setDefaultConfig?.(derivedSearchConfig);
+    }
+    return { baseDb, searchAdapter };
+}
+function buildSystemEventConsumers(options, sseBroker, searchAdapter) {
+    const sseConsumerEnabled = options.eventDispatcher?.systemConsumers?.sse ?? true;
+    const searchConsumerEnabled = options.eventDispatcher?.systemConsumers?.search ?? true;
+    const jobTriggerConsumerEnabled = options.eventDispatcher?.systemConsumers?.jobTrigger ?? true;
+    const jobRunnerForTriggers = options.dispatcherOptions?.jobRunner;
+    const systemConsumers = [];
+    if (sseConsumerEnabled) {
+        systemConsumers.push(createSseBroadcastEventConsumer(sseBroker));
+    }
+    if (searchConsumerEnabled && searchAdapter) {
+        systemConsumers.push(createSearchEventConsumer(searchAdapter, options.registry));
+    }
+    if (jobTriggerConsumerEnabled && jobRunnerForTriggers) {
+        systemConsumers.push(createJobTriggerEventConsumer(jobRunnerForTriggers, options.registry));
+    }
+    // Default ON (global-by-default). Tests that opt out of SSE via
+    // systemConsumers.accessInvalidation=false (test-stack mirrors sse off)
+    // skip the row so retention prune suites are not blocked by a lagging
+    // cursor=0 consumer they never drain.
+    const accessInvalidationEnabled = options.eventDispatcher?.systemConsumers?.accessInvalidation ?? true;
+    if (accessInvalidationEnabled) {
+        systemConsumers.push(createAccessInvalidationEventConsumer(sseBroker));
+    }
+    return systemConsumers;
+}
+function buildMultiStreamProjectionConsumers(options, deps) {
+    const jobRunnerForTriggers = options.dispatcherOptions?.jobRunner;
+    const mspJobs = jobRunnerForTriggers?.dispatch
+        ? {
+            dispatch: async (jobName, payload, dispatchOptions) => {
+                await jobRunnerForTriggers.dispatch?.(jobName, payload, dispatchOptions);
+            },
+        }
+        : undefined;
+    // MultiStreamProjections: one EventConsumer per MSP. Handler routes by
+    // event.type into the MSP's apply map. MSPs aggregate cross-aggregate but
+    // still within one tenant by default — the applier receives the plain
+    // baseDb DbRunner; tenant consistency comes from the triggering event's
+    // own tenantId, not a per-event TenantDb scope.
+    //
+    // Lane-filter: MSPs declare `runIn` to pin them to a
+    // deploy-lane. An MSP with `runIn: "api"` won't be wired into the
+    // worker-process dispatcher (and vice versa). `runIn: "both"` (or the
+    // legacy undefined default of "worker") runs wherever a dispatcher is
+    // started — SKIP LOCKED on the consumer-cursor handles the race between
+    // processes that both want the same event.
+    const processLane = options.processLane ?? "worker";
+    const mspDefs = [...options.registry.getAllMultiStreamProjections().values()].filter((msp) => runsInLane(msp.runIn, processLane));
+    return mspDefs.map((msp) => buildMultiStreamProjectionConsumer(msp, {
+        registry: options.registry,
+        mspJobs,
+        ...deps,
+    }));
+}
+function buildMultiStreamProjectionConsumer(msp, deps) {
+    const { registry, mspJobs, baseDb, context, fileProviderResolver } = deps;
+    return {
+        name: msp.name,
+        // Feature-toggle gating: carry the owning feature so the event-dispatcher
+        // can pause this consumer when the feature is globally disabled. Events
+        // queue up in the store and replay cleanly from the same cursor on resume.
+        ...(registry.getMultiStreamProjectionFeature(msp.name) && {
+            featureName: registry.getMultiStreamProjectionFeature(msp.name), // @cast-boundary engine-bridge
+        }),
+        // Copy the continuous-lifecycle error policy straight onto the consumer.
+        // Rebuild uses its own policy (rebuildProjection reads msp.errorMode.rebuild
+        // directly); steady-state delivery runs through this consumer.
+        ...(msp.errorMode?.continuous && { errorPolicy: msp.errorMode.continuous }),
+        // Carry the MSP's declared delivery semantic through to the consumer.
+        // Default (shared) is applied inside event-dispatcher, so omitting when
+        // the MSP didn't declare one keeps the existing behaviour.
+        ...(msp.delivery && { delivery: msp.delivery }),
+        // Carry the MSP's declared cursor-seed through to the consumer. Default
+        // (beginning) is applied inside insertConsumerIfAbsent.
+        ...(msp.startFrom && { startFrom: msp.startFrom }),
+        handler: async (event, ctx) => {
+            const applyFn = msp.apply[event.type];
+            // skip: this MSP doesn't care about this event type — fast path,
+            // every event type passes through every MSP consumer exactly once.
+            if (!applyFn)
+                return;
+            if (!baseDb) {
+                // skip: no baseDb wired — consumers.length > 0 + baseDb check in
+                // createServerEventDispatcher gates dispatcher creation, so we won't reach here in
+                // production. Defensive return for the type-narrowing path.
+                return;
+            }
+            // Saga/process-manager ctx: apply can call ctx.appendEvent to cascade
+            // a follow-up event onto another aggregate. Uses the triggering event's
+            // tenantId + userId so the causal chain stays tenant-consistent.
+            // MSP qualified names are "<feature>:projection:<short>" — the
+            // prefix before the first ":" owns the MSP. Used to reject
+            // cross-feature ctx.appendEvent calls at emit-site.
+            const mspOwner = msp.name.split(":")[0];
+            const mspFiles = fileProviderResolver
+                ? createTenantFileContext(fileProviderResolver, event.tenantId)
+                : undefined;
+            const mspDb = withExecutorManagedWrites(baseDb);
+            const applyCtx = createMultiStreamApplyContext({
+                registry,
+                db: mspDb,
+                tenantId: event.tenantId,
+                userId: event.metadata.userId,
+                ...(mspOwner && { callerFeature: mspOwner }),
+                ...(mspFiles && { files: mspFiles }),
+                ...(context.secrets && { secrets: context.secrets }),
+                ...(mspJobs && { jobs: mspJobs }),
+                ...(mspFiles && {
+                    derivatives: createDerivativesContext({
+                        files: mspFiles,
+                        registry,
+                        db: baseDb,
+                        tenantId: event.tenantId,
+                    }),
+                }),
+            });
+            await applyFn(event, mspDb, applyCtx);
+            // Keep ctx reachable to satisfy the EventConsumerHandler signature.
+            void ctx;
+        },
+    };
+}
+export function registerOwnedShutdownHooks(lifecycle, owned) {
+    const { eventDispatcher, ownedRedisSseBroker, ownedCacheSync } = owned;
+    // Wire the event-dispatcher shutdown into the lifecycle so the caller
+    // doesn't have to know the dispatcher exists. Hooks drain LIFO, so this
+    // runs before anything registered later by the caller (e.g. DB pool close).
+    if (lifecycle && eventDispatcher) {
+        const dispatcher = eventDispatcher;
+        lifecycle.registerShutdownHook("eventDispatcher", async () => {
+            await dispatcher.stop();
+        });
+    }
+    // Same reasoning, scoped to the broker this function created itself — an
+    // app-injected sseBroker (options.sseBroker) owns its own teardown.
+    if (lifecycle && ownedRedisSseBroker) {
+        const broker = ownedRedisSseBroker;
+        lifecycle.registerShutdownHook("redisSseBroker", async () => {
+            await broker.close();
+        });
+    }
+    if (lifecycle && ownedCacheSync) {
+        const bus = ownedCacheSync;
+        lifecycle.registerShutdownHook("cacheSync", async () => {
+            await bus.close();
+        });
+    }
+}

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

@@ -0,0 +1,11 @@
+import type { Context, Hono } from "hono";
+import type { WriteResult } from "../engine/types/index.ts";
+import type { Dispatcher } from "../pipeline/dispatcher.ts";
+import { type ExtraRouteDefinition, type RoleDispatchArgs, type SystemDispatchArgs } from "./extra-route.ts";
+import type { ServerWiring } from "./server-wiring.ts";
+export type PublicApiRequestMatcher = (c: Context) => boolean;
+export declare function compilePublicApiRequestMatcher(extraRoutes: readonly ExtraRouteDefinition[] | undefined): PublicApiRequestMatcher;
+export declare function mountExtraRoutes(app: Hono, wiring: Pick<ServerWiring, "options" | "dispatcher" | "context" | "clientIpResolver">): void;
+export declare function makeDispatchSystemWrite(dispatcher: Dispatcher): (args: SystemDispatchArgs) => Promise<WriteResult>;
+export declare function makeDispatchWriteAs(dispatcher: Dispatcher): (args: RoleDispatchArgs) => Promise<WriteResult>;
+export declare function makeDispatchSystemQuery(dispatcher: Dispatcher): (args: SystemDispatchArgs) => Promise<unknown>;

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

@@ -0,0 +1,203 @@
+import { ROLES } from "../auth/roles.js";
+import { createSystemUser } from "../engine/system-user.js";
+import { createFallbackLogger } from "../logging/index.js";
+import { assertUnreachable } from "../utils/index.js";
+import { NON_PUBLIC_API_PATHS, PUBLIC_API_PATHS } from "./api-constants.js";
+import { getUser } from "./auth-middleware.js";
+import { clientIpSourceFromHonoContext } from "./client-ip.js";
+import { ExtraRouteEntries, ExtraRouteRejection, } from "./extra-route.js";
+import { bodyLimitForRoutePath, DEFAULT_MAX_REQUEST_BYTES } from "./route-registrars.js";
+import { isMissingOrAnonymousUser, makeSystemQuery, mountHonoRoute, unauthenticatedResponse, } from "./server-routes.js";
+// Only entry:"signature" bypasses jwtGuard (verify() authenticates
+// itself); entry:"anonymous" still needs the anonymousAccess fallthrough
+// (tenant-by-host), entry:"user" needs c.get("user") populated.
+export function compilePublicApiRequestMatcher(extraRoutes) {
+    const matchers = (extraRoutes ?? [])
+        .filter((route) => route.entry === ExtraRouteEntries.signature)
+        .map((route) => ({ method: route.method, pattern: honoPathToRegex(route.path) }));
+    return (c) => PUBLIC_API_PATHS.has(c.req.path) ||
+        matchers.some((m) => m.method === c.req.method && m.pattern.test(c.req.path));
+}
+export function mountExtraRoutes(app, wiring) {
+    const { options, dispatcher, context, clientIpResolver } = wiring;
+    // extraRoutes — declarative HTTP-routes with a
+    // required `entry` tier. Mounted after r.httpRoute: an
+    // extraRoute dispatching through `dispatcher` builds Hono's matcher, so
+    // this must run before any seed that also dispatches (runProdApp/
+    // createKumikoServer call buildServer before seeding).
+    if (options.extraRoutes) {
+        // Boot-time validation for the whole list BEFORE mounting anything —
+        // an app with one bad route should fail loud at boot, not mount N-1
+        // routes and then throw on route N.
+        for (const route of options.extraRoutes) {
+            assertValidExtraRoute(route);
+        }
+        const dispatchSystemWrite = makeDispatchSystemWrite(dispatcher);
+        const dispatchSystemQuery = makeDispatchSystemQuery(dispatcher);
+        for (const route of options.extraRoutes) {
+            const honoHandler = buildExtraRouteHonoHandler(route, {
+                app,
+                dispatcher,
+                registry: options.registry,
+                secrets: context.secrets,
+                dispatchSystemWrite,
+                dispatchSystemQuery,
+                clientIpResolver,
+            });
+            mountHonoRoute(app, route.method, route.path, honoHandler, bodyLimitForRoutePath(route.path, options.maxRequestBytes ?? DEFAULT_MAX_REQUEST_BYTES));
+        }
+    }
+}
+function assertValidExtraRoute(route) {
+    if (!isKnownExtraRouteEntry(route.entry)) {
+        throw new Error(`[kumiko] extraRoutes: unknown entry "${String(route.entry)}" on ` +
+            `"${route.method} ${route.path}" — expected "anonymous" | "user" | "signature". ` +
+            "A JS caller without the ExtraRouteDefinition type can hit this at boot.");
+    }
+    if (route.entry === ExtraRouteEntries.user && !route.path.startsWith("/api/")) {
+        throw new Error(`[kumiko] extraRoutes: entry:"user" route "${route.method} ${route.path}" must be ` +
+            "mounted under \"/api/\" — that's the only path prefix that rides the framework's " +
+            "jwtGuard chain, which is what populates deps.user.");
+    }
+    // A signature route under /api/ skips jwtGuard/origin/csrf for every
+    // path its pattern matches — a wildcard would switch off auth for
+    // unrelated /api/* handlers (e.g. "/api/*" swallows /api/write).
+    if (route.entry === ExtraRouteEntries.signature &&
+        route.path.startsWith("/api/") &&
+        route.path.includes("*")) {
+        throw new Error(`[kumiko] extraRoutes: entry:"signature" route "${route.method} ${route.path}" must not ` +
+            'use a wildcard under "/api/" — it would bypass the auth chain for every matching path.');
+    }
+    // A `:param` segment is as broad as a wildcard, and the public matchers test
+    // the bare request path: "/:seg/write" and "/api/:hook" both match /api/write.
+    if (route.entry === ExtraRouteEntries.signature) {
+        const routePattern = honoPathToRegex(route.path);
+        const shadowedFrameworkPath = [...PUBLIC_API_PATHS, ...NON_PUBLIC_API_PATHS].find((path) => routePattern.test(path));
+        if (shadowedFrameworkPath !== undefined) {
+            throw new Error(`[kumiko] extraRoutes: entry:"signature" route "${route.method} ${route.path}" must not ` +
+                `match the framework path "${shadowedFrameworkPath}" — it would bypass the auth chain for it.`);
+        }
+    }
+}
+// SystemAdmin write/query builders shared by mountExtraRoutes
+// and server-runtime's `wire` hook (runProdApp/createKumikoServer,
+// after buildServer). Privilege-scope: SystemAdmin is the highest
+// non-tenant-scoped role — reaches ANY SystemAdmin-gated handler on ANY
+// tenant. Only safe for callers that already proved their own authenticity
+// (signature verify(), HMAC state, ...), never exposed to a raw request.
+export function makeDispatchSystemWrite(dispatcher) {
+    return ({ handlerQn, payload, tenantId }) => dispatcher.write(handlerQn, payload, createSystemUser(tenantId, [ROLES.SystemAdmin]));
+}
+// Privilege-scope: the system user gets exactly the roles the caller names —
+// no implicit SystemAdmin — so a seed can write data gated on app roles.
+// Same trust requirement as makeDispatchSystemWrite: never expose to a raw
+// request, only to code that already proved its own authenticity.
+export function makeDispatchWriteAs(dispatcher) {
+    return ({ handlerQn, payload, tenantId, roles }) => dispatcher.write(handlerQn, payload, createSystemUser(tenantId, roles));
+}
+export function makeDispatchSystemQuery(dispatcher) {
+    return ({ handlerQn, payload, tenantId }) => dispatcher.query(handlerQn, payload, createSystemUser(tenantId, [ROLES.SystemAdmin]));
+}
+// Same dispatcher.write(...) as entry:"user", but the user is getUser(c) —
+// see AnonymousExtraRouteDeps.write for the privilege/tenant contract.
+function makeAnonymousWrite(
+// biome-ignore lint/suspicious/noExplicitAny: Hono context generics are invisible at the framework boundary
+c, dispatcher) {
+    return (type, payload) => {
+        const user = getUser(c);
+        if (!user) {
+            throw new Error('[kumiko] extraRoutes: entry:"anonymous" deps.write requires this route to be mounted ' +
+                'under "/api/" with anonymousAccess wired — no request-resolved session user was found.');
+        }
+        return dispatcher.write(type, payload, user);
+    };
+}
+const extraRouteLog = createFallbackLogger("extra-route");
+function isKnownExtraRouteEntry(entry) {
+    return (entry === ExtraRouteEntries.anonymous ||
+        entry === ExtraRouteEntries.user ||
+        entry === ExtraRouteEntries.signature);
+}
+// Hono path pattern ("/api/foo/:bar", "/api/foo/*") → RegExp. Only the
+// subset extraRoutes actually uses (static segments, `:param`, trailing
+// `*`) — no inline `:param{regex}` constraints, no optional `:param?`.
+function honoPathToRegex(path) {
+    const segments = path
+        .split("/")
+        .map((segment) => {
+        if (segment.startsWith(":"))
+            return "[^/]+";
+        if (segment === "*")
+            return ".*";
+        return segment.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    })
+        .join("/");
+    return new RegExp(`^${segments}$`);
+}
+function buildExtraRouteHonoHandler(route, shared) {
+    switch (route.entry) {
+        case ExtraRouteEntries.anonymous:
+            return async (c) => route.handler(c, {
+                app: shared.app,
+                registry: shared.registry,
+                systemQuery: makeSystemQuery(c, shared.dispatcher, shared.clientIpResolver),
+                write: makeAnonymousWrite(c, shared.dispatcher),
+                clientIp: shared.clientIpResolver.resolve(clientIpSourceFromHonoContext(c)),
+            });
+        case ExtraRouteEntries.user:
+            return async (c) => {
+                const user = getUser(c);
+                if (isMissingOrAnonymousUser(user)) {
+                    return unauthenticatedResponse(c);
+                }
+                return route.handler(c, {
+                    app: shared.app,
+                    registry: shared.registry,
+                    user,
+                    query: (type, payload) => shared.dispatcher.query(type, payload, user),
+                    write: (type, payload) => shared.dispatcher.write(type, payload, user),
+                });
+            };
+        case ExtraRouteEntries.signature:
+            return async (c) => {
+                const rawBody = await c.req.text();
+                const headers = {};
+                c.req.raw.headers.forEach((value, key) => {
+                    headers[key.toLowerCase()] = value;
+                });
+                let verified;
+                try {
+                    verified = await route.verify({ rawBody, headers, params: c.req.param(), query: c.req.query() }, { registry: shared.registry, secrets: shared.secrets });
+                }
+                catch (e) {
+                    if (e instanceof ExtraRouteRejection) {
+                        if (e.retryAfterSeconds !== undefined) {
+                            return c.json(e.body, e.status, { "Retry-After": String(e.retryAfterSeconds) });
+                        }
+                        return c.json(e.body, e.status);
+                    }
+                    // The body goes to unauthenticated callers; infra errors thrown by
+                    // verify() (secrets, DB) must not leak, so the detail stays in the log.
+                    extraRouteLog.error(`signature verify() threw on ${c.req.path}`, {
+                        error: e instanceof Error ? e.message : String(e),
+                    });
+                    return c.json({
+                        error: {
+                            code: "extra_route_signature_invalid",
+                            message: "signature verification failed",
+                        },
+                    }, 401);
+                }
+                return route.handler(c, verified, {
+                    app: shared.app,
+                    registry: shared.registry,
+                    secrets: shared.secrets,
+                    systemQuery: makeSystemQuery(c, shared.dispatcher, shared.clientIpResolver),
+                    dispatchSystemWrite: shared.dispatchSystemWrite,
+                    dispatchSystemQuery: shared.dispatchSystemQuery,
+                });
+            };
+        default:
+            return assertUnreachable(route, "extra route entry");
+    }
+}

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

@@ -0,0 +1,20 @@
+import type { Hono, MiddlewareHandler } from "hono";
+import type { ObservabilityProvider } from "../observability/index.ts";
+import { type TenantLifecycleStatusResolver } from "./auth-middleware.ts";
+import type { ServerOptions } from "./server.ts";
+import type { PublicApiRequestMatcher } from "./server-extra-routes.ts";
+import type { ServerWiring } from "./server-wiring.ts";
+import { type ResolvedSessionCookies } from "./session-cookies.ts";
+export declare function installSessionCookies(app: Hono, auth: ServerOptions["auth"]): ResolvedSessionCookies;
+export declare function installRequestId(app: Hono, wiring: Pick<ServerWiring, "options" | "clientIpResolver">): void;
+export declare function installRateLimitMiddleware(app: Hono, wiring: Pick<ServerWiring, "options" | "rateLimitResolver" | "rateLimitMiddlewareRequested" | "clientIpResolver" | "observability">): MiddlewareHandler | undefined;
+export declare function installObservability(app: Hono, observability: ObservabilityProvider): void;
+export declare function installPiiLeakGuard(app: Hono): void;
+export type AuthGuardChain = {
+    readonly tenantLifecycleResolver: TenantLifecycleStatusResolver | undefined;
+    readonly sessionOnlyHttpRouteGuards: readonly MiddlewareHandler[];
+};
+export declare function installAuthGuardChain(app: Hono, wiring: Pick<ServerWiring, "options" | "jwt" | "baseDb">, scope: {
+    readonly isPublicApiRequest: PublicApiRequestMatcher;
+    readonly globalRateLimitGuard: MiddlewareHandler | undefined;
+}): AuthGuardChain;