@fuzdev/fuz_app 0.63.0 → 0.65.0

package/dist/server/app_server.d.ts

@@ -8,6 +8,7 @@
  * @module
  */
 import { Hono, type Context } from 'hono';
+import type { UpgradeWebSocket } from 'hono/ws';
 import { z } from 'zod';
 import { type SessionOptions } from '../auth/session_cookie.js';
 import type { BootstrapAccountSuccess } from '../auth/bootstrap_account.js';
@@ -25,6 +26,8 @@ import { type AppSurfaceSpec, type RpcEndpointSpec } from '../http/surface.js';
 import { type RouteSpec } from '../http/route_spec.js';
 import type { MiddlewareSpec } from '../http/middleware_spec.js';
 import { type BootstrapStatus } from '../auth/bootstrap_routes.js';
+import type { WsEndpointSpec } from '../actions/ws_endpoint_spec.js';
+import { BackendWebsocketTransport } from '../actions/transports_ws_backend.js';
 /**
  * Context passed to `on_effect_error` when a pending effect rejects.
  */
@@ -34,6 +37,46 @@ export interface EffectErrorContext {
     /** URL path of the request that spawned the effect. */
     path: string;
 }
+/**
+ * Bootstrap configuration for `AppServerOptions.bootstrap`.
+ *
+ * Discriminated union over three deployment intents. Distinct from
+ * `BootstrapRouteOptions` in `auth/bootstrap_routes.ts` — that one is
+ * per-factory runtime state (mutable `bootstrap_status` ref, rate
+ * limiter); this one is the consumer-facing server option that
+ * `create_app_server` reads at startup to decide whether to mount the
+ * routes and where.
+ *
+ * Three modes:
+ * - `disabled` — no route mounted, nothing in `/api/surface`.
+ *   Equivalent to omitting `bootstrap` entirely; the explicit mode is
+ *   for documentation and reviewable intent at the wiring layer.
+ * - `surface_only` — route present, permanent 403 via
+ *   `check_bootstrap_status`. For tests asserting on the
+ *   disabled-but-present wire shape.
+ * - `live` — route mounted, real token verification. Success path
+ *   reachable. `token_path` is required (non-nullable).
+ */
+export type BootstrapServerOptions = BootstrapDisabledOptions | BootstrapSurfaceOnlyOptions | BootstrapLiveOptions;
+export interface BootstrapDisabledOptions {
+    mode: 'disabled';
+}
+export interface BootstrapSurfaceOnlyOptions {
+    mode: 'surface_only';
+    /** Route prefix for surface generation. Default `'/api/account'`. */
+    route_prefix?: string;
+}
+export interface BootstrapLiveOptions {
+    mode: 'live';
+    token_path: string;
+    /** Route prefix for bootstrap routes. Default `'/api/account'`. */
+    route_prefix?: string;
+    /**
+     * Called after successful bootstrap (account + session created).
+     * Use for app-specific post-bootstrap work like generating API tokens.
+     */
+    on_bootstrap?: (result: BootstrapAccountSuccess, c: Context) => Promise<void>;
+}
 /**
  * Configuration for `create_app_server()`.
  *
@@ -108,16 +151,7 @@ export interface AppServerOptions {
     /** Daemon token state for keeper auth. Omit to disable. */
     daemon_token_state?: DaemonTokenState;
     /** Bootstrap options. Omit to skip bootstrap status check and routes. */
-    bootstrap?: {
-        token_path: string | null;
-        /** Route prefix for bootstrap routes. Default `'/api/account'`. */
-        route_prefix?: string;
-        /**
-         * Called after successful bootstrap (account + session created).
-         * Use for app-specific post-bootstrap work like generating API tokens.
-         */
-        on_bootstrap?: (result: BootstrapAccountSuccess, c: Context) => Promise<void>;
-    };
+    bootstrap?: BootstrapServerOptions;
     /**
      * Set to `false` to disable the auto-created surface route (`GET /api/surface`).
      * Default: auto-created (authenticated).
@@ -163,6 +197,50 @@ export interface AppServerOptions {
      * `create_standard_rpc_actions(ctx.deps, {app_settings: ctx.app_settings})`.
      */
     rpc_endpoints?: Array<RpcEndpointSpec> | ((context: AppServerContext) => Array<RpcEndpointSpec>);
+    /**
+     * Hono adapter's `upgradeWebSocket` helper. Required whenever
+     * `ws_endpoints` resolves to a non-empty array — `create_app_server`
+     * throws at assembly otherwise. Omit (along with `ws_endpoints`)
+     * when the consumer doesn't mount any WS endpoints. The same
+     * adapter helper services every `WsEndpointSpec` mounted from
+     * `ws_endpoints` — one adapter per app.
+     *
+     * For Node, `import {upgradeWebSocket} from '@hono/node-ws'`. For
+     * Deno, `import {upgradeWebSocket} from 'hono/deno'`. Test harnesses
+     * use `create_stub_upgrade` from `$lib/testing/ws_round_trip.ts`.
+     */
+    upgradeWebSocket?: UpgradeWebSocket;
+    /**
+     * WebSocket endpoint specs — single source of truth for both surface
+     * generation *and* live dispatch. Each entry is auto-mounted via
+     * `register_ws_endpoint` against the assembled Hono app, so
+     * consumers no longer call `register_ws_endpoint` themselves.
+     *
+     * Accepts either an array (evaluated eagerly) or a factory
+     * `(ctx: AppServerContext) => ReadonlyArray<WsEndpointSpec>`
+     * (evaluated after the server context is assembled). Use the factory
+     * form when action lists depend on `ctx.deps` /
+     * `ctx.action_*_rate_limiter` — e.g. when spreading
+     * `create_standard_rpc_actions(ctx.deps, ...)` over WS.
+     *
+     * When non-empty, `upgradeWebSocket` must be supplied (throws
+     * otherwise). A factory returning `[]` does NOT trip the check —
+     * feature-flag gated WS surfaces stay safe.
+     *
+     * Duplicate `path` values across two `WsEndpointSpec`s throw at
+     * mount time (Hono would silently shadow them otherwise).
+     *
+     * Each spec's `auth_guard?` defaults to `true` — the factory
+     * composes `create_ws_auth_guard` + `create_ws_logout_closer`
+     * against the mounted transport and appends them to
+     * `deps.audit.on_event_chain`. Wiring is deduped by transport
+     * **reference identity** so two specs sharing one
+     * `BackendWebsocketTransport` instance get a single pair of
+     * listeners; wrapped / proxied transports dedupe as separate
+     * entries (set `auth_guard: false` on duplicates and compose
+     * against the underlying transport once).
+     */
+    ws_endpoints?: ReadonlyArray<WsEndpointSpec> | ((context: AppServerContext) => ReadonlyArray<WsEndpointSpec>);
     /**
      * Env schema for surface generation. Defaults to `BaseServerEnv` —
      * pass an extended schema (typically `BaseServerEnv.extend({...})`)
@@ -241,6 +319,19 @@ export interface AppServer {
      * Use `require_audit_sse(server)` to assert the invariant.
      */
     audit_sse: AuditLogSse | null;
+    /**
+     * Path-keyed map of mounted WS endpoints. Each value is the
+     * `BackendWebsocketTransport` `create_app_server` registered
+     * connections against — supplied via `WsEndpointSpec.transport` or
+     * auto-created when omitted. Retain for broadcast / fan-out:
+     *
+     * ```ts
+     * app_server.ws_endpoints['/api/ws'].send_to_account(account_id, msg);
+     * ```
+     *
+     * Empty when no `ws_endpoints` were mounted.
+     */
+    ws_endpoints: Readonly<Record<string, BackendWebsocketTransport>>;
     /** Close the database connection. Propagated from `AppBackend`. */
     close: () => Promise<void>;
 }

package/dist/server/app_server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app_server.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/app_server.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAC,IAAI,EAAE,KAAK,OAAO,EAAC,MAAM,MAAM,CAAC;AAGxC,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,EAEN,KAAK,cAAc,EAEnB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAC,uBAAuB,EAAC,MAAM,8BAA8B,CAAC;AAC1E,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAGN,KAAK,WAAW,EAChB,MAAM,+BAA+B,CAAC;AAEvC,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,gCAAgC,CAAC;AAEhE,OAAO,EAKN,KAAK,WAAW,EAChB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,yBAAyB,CAAC;AAC9D,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,iBAAiB,CAAC;AAC7C,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAGjD,OAAO,oBAAoB,CAAC;AAE5B,OAAO,EAA2B,KAAK,kBAAkB,EAAC,MAAM,aAAa,CAAC;AAE9E,OAAO,EAEN,KAAK,cAAc,EAEnB,KAAK,eAAe,EACpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAIN,KAAK,SAAS,EACd,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,4BAA4B,CAAC;AAC/D,OAAO,EAGN,KAAK,eAAe,EACpB,MAAM,6BAA6B,CAAC;AASrC;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;CACb;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAChC,2DAA2D;IAC3D,OAAO,EAAE,UAAU,CAAC;IACpB,6CAA6C;IAC7C,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACxC,sCAAsC;IACtC,eAAe,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAE/B,6BAA6B;IAC7B,KAAK,EAAE;QACN,eAAe,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;QAC/B,iBAAiB,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,CAAC;KACtD,CAAC;IAEF;;;;;OAKG;IACH,eAAe,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IACrC;;;;;OAKG;IACH,0BAA0B,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAChD;;;;;OAKG;IACH,2BAA2B,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IACjD;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC5C;;;;;;;;OAQG;IACH,sBAAsB,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC5C;;;;;;;;OAQG;IACH,2BAA2B,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IACjD;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,2DAA2D;IAC3D,kBAAkB,CAAC,EAAE,gBAAgB,CAAC;IAEtC,yEAAyE;IACzE,SAAS,CAAC,EAAE;QACX,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;QAC1B,mEAAmE;QACnE,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB;;;WAGG;QACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,uBAAuB,EAAE,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;KAC9E,CAAC;IAEF;;;OAGG;IACH,aAAa,CAAC,EAAE,KAAK,CAAC;IAEtB;;;OAGG;IACH,kBAAkB,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,KAAK,CAAC,SAAS,CAAC,CAAC;IAEpE,4DAA4D;IAC5D,oBAAoB,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,cAAc,CAAC,KAAK,KAAK,CAAC,cAAc,CAAC,CAAC;IAE/E;;;;;;;;;;;;;;OAcG;IACH,aAAa,CAAC,EAAE,IAAI,GAAG;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAC,CAAC;IAEvC,gFAAgF;IAChF,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAE/B;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,EAAE,KAAK,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,gBAAgB,KAAK,KAAK,CAAC,eAAe,CAAC,CAAC,CAAC;IAEjG;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC;IAEzB,mFAAmF;IACnF,qBAAqB,CAAC,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;IAE9C,6DAA6D;IAC7D,cAAc,CAAC,EAAE;QAChB,YAAY,EAAE,kBAAkB,CAAC;QACjC,4DAA4D;QAC5D,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,gEAAgE;QAChE,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB;;;;WAIG;QACH,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;KACzC,CAAC;IAEF;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAEhC;;;;OAIG;IACH,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,kBAAkB,KAAK,IAAI,CAAC;IAExE,8CAA8C;IAC9C,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED,8CAA8C;AAC9C,MAAM,WAAW,gBAAgB;IAChC,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,UAAU,CAAC;IACpB,gBAAgB,EAAE,eAAe,CAAC;IAClC,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACxC,yEAAyE;IACzE,eAAe,EAAE,WAAW,GAAG,IAAI,CAAC;IACpC,iFAAiF;IACjF,0BAA0B,EAAE,WAAW,GAAG,IAAI,CAAC;IAC/C,kFAAkF;IAClF,2BAA2B,EAAE,WAAW,GAAG,IAAI,CAAC;IAChD,uGAAuG;IACvG,sBAAsB,EAAE,WAAW,GAAG,IAAI,CAAC;IAC3C,0GAA0G;IAC1G,2BAA2B,EAAE,WAAW,GAAG,IAAI,CAAC;IAChD,2EAA2E;IAC3E,YAAY,EAAE,WAAW,CAAC;IAC1B;;;;OAIG;IACH,SAAS,EAAE,WAAW,GAAG,IAAI,CAAC;CAC9B;AAED,uCAAuC;AACvC,MAAM,WAAW,SAAS;IACzB,GAAG,EAAE,IAAI,CAAC;IACV,wEAAwE;IACxE,YAAY,EAAE,cAAc,CAAC;IAC7B,gBAAgB,EAAE,eAAe,CAAC;IAClC,2EAA2E;IAC3E,YAAY,EAAE,WAAW,CAAC;IAC1B,oGAAoG;IACpG,iBAAiB,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IAClD;;;;OAIG;IACH,SAAS,EAAE,WAAW,GAAG,IAAI,CAAC;IAC9B,mEAAmE;IACnE,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,iBAAiB,GAAI,QAAQ;IAAC,SAAS,EAAE,WAAW,GAAG,IAAI,CAAA;CAAC,KAAG,WAO3E,CAAC;AAEF,gDAAgD;AAChD,eAAO,MAAM,qBAAqB,QAAc,CAAC;AAEjD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,iBAAiB,GAAU,SAAS,gBAAgB,KAAG,OAAO,CAAC,SAAS,CAmRpF,CAAC"}
+{"version":3,"file":"app_server.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/app_server.ts"],"names":[],"mappings":"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"}

package/dist/server/app_server.js

@@ -32,6 +32,9 @@ import { fuz_auth_guard_resolver } from '../auth/auth_guard_resolver.js';
 import { create_fuz_authorization_handler } from '../auth/request_context.js';
 import { ERROR_PAYLOAD_TOO_LARGE } from '../http/error_schemas.js';
 import { create_rpc_endpoint } from '../actions/action_rpc.js';
+import { register_ws_endpoint } from '../actions/register_ws_endpoint.js';
+import { create_ws_auth_guard, create_ws_logout_closer, } from '../actions/transports_ws_auth_guard.js';
+import { BackendWebsocketTransport } from '../actions/transports_ws_backend.js';
 /**
  * Assert that `audit_sse` was wired by `create_app_server` and return it
  * as a non-null `AuditLogSse`. Throws a labelled error when the
@@ -121,13 +124,24 @@ export const create_app_server = async (options) => {
         middleware_specs = options.transform_middleware(middleware_specs);
     }
     // Bootstrap status + app settings
-    const bootstrap_status = options.bootstrap
+    // - undefined / 'disabled': no route mounted; placeholder status.
+    // - 'surface_only': route mounted but permanently unavailable; status placeholder.
+    // - 'live': real disk + lock check via `check_bootstrap_status`.
+    const bootstrap_status = options.bootstrap?.mode === 'live'
         ? await check_bootstrap_status(deps, { token_path: options.bootstrap.token_path })
         : { available: false, token_path: null };
     const app_settings = await query_app_settings_load({ db: deps.db });
     // Surface route ref — factory manages the circular ref
     const surface_ref = {
-        surface: { middleware: [], routes: [], rpc_endpoints: [], env: [], events: [], diagnostics: [] },
+        surface: {
+            middleware: [],
+            routes: [],
+            rpc_endpoints: [],
+            ws_endpoints: [],
+            env: [],
+            events: [],
+            diagnostics: [],
+        },
     };
     // Route specs (consumer routes + factory-managed routes)
     const context = {
@@ -146,12 +160,15 @@ export const create_app_server = async (options) => {
     const consumer_routes = options.create_route_specs(context);
     // Factory-managed routes appended after consumer routes
     const factory_routes = [];
-    // Bootstrap routes
-    if (options.bootstrap) {
+    // Bootstrap routes — mounted for 'surface_only' and 'live'; omitted for
+    // 'disabled' / undefined. The route handler short-circuits to 403 when
+    // `bootstrap_status.available === false`, which is the steady state for
+    // 'surface_only' and the post-bootstrap state for 'live'.
+    if (options.bootstrap && options.bootstrap.mode !== 'disabled') {
         const bootstrap_routes = create_bootstrap_route_specs(deps, {
             session_options: options.session_options,
             bootstrap_status,
-            on_bootstrap: options.bootstrap.on_bootstrap,
+            on_bootstrap: options.bootstrap.mode === 'live' ? options.bootstrap.on_bootstrap : undefined,
             ip_rate_limiter,
         });
         const prefix = options.bootstrap.route_prefix ?? '/api/account';
@@ -173,6 +190,15 @@ export const create_app_server = async (options) => {
             }));
         }
     }
+    // WS endpoint resolution — done here (alongside RPC) so the captured
+    // array threads into surface generation below. Actual mount happens
+    // after `apply_route_specs` because `register_ws_endpoint` mutates the
+    // live Hono `app` (origin / auth / role / authorization middleware +
+    // the `app.get(path, ...)` upgrade route), and `app` does not exist
+    // until the assembly phase below.
+    const resolved_ws_endpoints = typeof options.ws_endpoints === 'function'
+        ? options.ws_endpoints(context)
+        : options.ws_endpoints;
     // Surface route (default: enabled)
     if (options.surface_route !== false) {
         factory_routes.push(create_surface_route_spec(surface_ref));
@@ -192,6 +218,7 @@ export const create_app_server = async (options) => {
         env_schema: options.env_schema ?? BaseServerEnv,
         event_specs: all_event_specs,
         rpc_endpoints: resolved_rpc_endpoints,
+        ws_endpoints: resolved_ws_endpoints,
     });
     // Config-level diagnostics (concatenated after spec-level from generate_app_surface)
     const config_diagnostics = [];
@@ -215,7 +242,7 @@ export const create_app_server = async (options) => {
             config_diagnostics.push({
                 level: 'warning',
                 category: 'security',
-                message: 'Session cookie httpOnly=false — cookie accessible to JavaScript',
+                message: 'Session cookie httpOnly=false — cookie accessible to JS',
             });
         }
     }
@@ -291,6 +318,77 @@ export const create_app_server = async (options) => {
     apply_middleware_specs(app, middleware_specs);
     const authorize = create_fuz_authorization_handler({ db: deps.db });
     apply_route_specs(app, route_specs, fuz_auth_guard_resolver, log, deps.db, authorize);
+    // WS endpoint auto-mount — must run after `app` exists and
+    // `apply_route_specs` has registered the request routes. Each spec
+    // becomes a `register_ws_endpoint` call, plus optional `auth_guard`
+    // wiring onto the audit chain. `post_route_middleware` and static
+    // serving register after this loop, so WS upgrade routes sit
+    // adjacent to the consumer routes and ahead of the static fallback —
+    // matches the "WS mount is route registration" mental model.
+    const mounted_ws_endpoints = {};
+    if (resolved_ws_endpoints?.length) {
+        if (options.upgradeWebSocket === undefined) {
+            throw new Error('create_app_server: ws_endpoints resolved non-empty but upgradeWebSocket is missing. ' +
+                "Pass the Hono adapter's upgradeWebSocket helper as a top-level option.");
+        }
+        // Cross-surface collision: `register_ws_endpoint` mounts a `GET path`
+        // upgrade route. If a `RouteSpec` already registered `GET path`,
+        // Hono's last-wins semantics would silently shadow the consumer's
+        // GET route — fail fast instead.
+        const route_spec_get_paths = new Set();
+        for (const r of route_specs) {
+            if (r.method === 'GET')
+                route_spec_get_paths.add(r.path);
+        }
+        const seen_paths = new Set();
+        // Dedupe `auth_guard` wiring by transport reference — two specs
+        // sharing one transport instance get a single pair of listeners,
+        // otherwise revocation events would fire `close_sockets_for_*`
+        // twice per event (idempotent on the transport but log-spammy).
+        // Cross-spec OR-semantics: any spec with `auth_guard !== false`
+        // wires the guard for that transport; once wired, sibling specs
+        // (even with explicit `auth_guard: false`) cannot opt out. To
+        // disable, every spec sharing the transport must pass `auth_guard: false`.
+        const guarded_transports = new WeakSet();
+        for (const endpoint of resolved_ws_endpoints) {
+            if (seen_paths.has(endpoint.path)) {
+                throw new Error(`create_app_server: duplicate ws_endpoints path: ${endpoint.path}`);
+            }
+            if (route_spec_get_paths.has(endpoint.path)) {
+                throw new Error(`create_app_server: ws_endpoints path collides with a GET RouteSpec: ${endpoint.path}`);
+            }
+            seen_paths.add(endpoint.path);
+            const endpoint_transport = endpoint.transport ?? new BackendWebsocketTransport();
+            register_ws_endpoint({
+                app,
+                path: endpoint.path,
+                upgradeWebSocket: options.upgradeWebSocket,
+                allowed_origins: endpoint.allowed_origins,
+                db: deps.db,
+                actions: endpoint.actions,
+                transport: endpoint_transport,
+                heartbeat: endpoint.heartbeat,
+                artificial_delay: endpoint.artificial_delay,
+                on_socket_open: endpoint.on_socket_open,
+                on_socket_close: endpoint.on_socket_close,
+                log,
+                required_roles: endpoint.required_roles,
+                action_ip_rate_limiter,
+                action_account_rate_limiter,
+            });
+            mounted_ws_endpoints[endpoint.path] = endpoint_transport;
+            if (endpoint.auth_guard !== false && !guarded_transports.has(endpoint_transport)) {
+                guarded_transports.add(endpoint_transport);
+                deps.audit.on_event_chain.push(create_ws_auth_guard(endpoint_transport, log));
+                deps.audit.on_event_chain.push(create_ws_logout_closer(endpoint_transport, log));
+            }
+            if (endpoint.extra_audit_handlers?.length) {
+                for (const handler of endpoint.extra_audit_handlers) {
+                    deps.audit.on_event_chain.push(handler);
+                }
+            }
+        }
+    }
     // Post-route middleware (before static serving)
     if (options.post_route_middleware) {
         apply_middleware_specs(app, options.post_route_middleware);
@@ -309,6 +407,7 @@ export const create_app_server = async (options) => {
         app_settings,
         migration_results: backend.migration_results,
         audit_sse,
+        ws_endpoints: mounted_ws_endpoints,
         close: backend.close,
     };
 };

package/dist/server/env.d.ts

@@ -26,12 +26,12 @@ export declare const BaseServerEnv: z.ZodObject<{
     PORT: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     HOST: z.ZodDefault<z.ZodString>;
     DATABASE_URL: z.ZodString;
-    SECRET_COOKIE_KEYS: z.ZodString;
-    ALLOWED_ORIGINS: z.ZodString;
-    PUBLIC_API_URL: z.ZodDefault<z.ZodString>;
-    PUBLIC_WEBSOCKET_URL: z.ZodOptional<z.ZodString>;
-    PUBLIC_CONTACT_EMAIL: z.ZodOptional<z.ZodUnion<readonly [z.ZodEmail, z.ZodLiteral<"">]>>;
-    BOOTSTRAP_TOKEN_PATH: z.ZodOptional<z.ZodString>;
+    SECRET_FUZ_COOKIE_KEYS: z.ZodString;
+    FUZ_ALLOWED_ORIGINS: z.ZodString;
+    PUBLIC_FUZ_API_URL: z.ZodDefault<z.ZodString>;
+    PUBLIC_FUZ_WEBSOCKET_URL: z.ZodOptional<z.ZodString>;
+    PUBLIC_FUZ_CONTACT_EMAIL: z.ZodOptional<z.ZodUnion<readonly [z.ZodEmail, z.ZodLiteral<"">]>>;
+    FUZ_BOOTSTRAP_TOKEN_PATH: z.ZodOptional<z.ZodString>;
     SMTP_HOST: z.ZodOptional<z.ZodString>;
     SMTP_USER: z.ZodOptional<z.ZodUnion<readonly [z.ZodEmail, z.ZodLiteral<"">]>>;
     SMTP_PASSWORD: z.ZodOptional<z.ZodString>;
@@ -51,7 +51,7 @@ export interface ServerEnvOptions {
  */
 export interface ServerEnvOptionsError {
     ok: false;
-    field: 'SECRET_COOKIE_KEYS' | 'ALLOWED_ORIGINS';
+    field: 'SECRET_FUZ_COOKIE_KEYS' | 'FUZ_ALLOWED_ORIGINS';
     errors: Array<string>;
 }
 export type ServerEnvOptionsResult = ServerEnvOptions | ServerEnvOptionsError;

package/dist/server/env.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"env.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,EAA2B,KAAK,OAAO,EAAC,MAAM,oBAAoB,CAAC;AAG1E;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;kBAkCxB,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,EAAE,EAAE,IAAI,CAAC;IACT,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC/B,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACrC,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE,oBAAoB,GAAG,iBAAiB,CAAC;IAChD,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CACtB;AAED,MAAM,MAAM,sBAAsB,GAAG,gBAAgB,GAAG,qBAAqB,CAAC;AAE9E;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,GAAI,KAAK,aAAa,KAAG,sBA4BxD,CAAC"}
+{"version":3,"file":"env.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,EAA2B,KAAK,OAAO,EAAC,MAAM,oBAAoB,CAAC;AAG1E;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;kBAkCxB,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,EAAE,EAAE,IAAI,CAAC;IACT,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC/B,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACrC,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE,wBAAwB,GAAG,qBAAqB,CAAC;IACxD,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CACtB;AAED,MAAM,MAAM,sBAAsB,GAAG,gBAAgB,GAAG,qBAAqB,CAAC;AAE9E;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,GAAI,KAAK,aAAa,KAAG,sBA4BxD,CAAC"}

package/dist/server/env.js

@@ -27,20 +27,20 @@ export const BaseServerEnv = z.strictObject({
         description: 'Database URL (postgres://, file://, or memory://)',
         sensitivity: 'secret',
     }),
-    SECRET_COOKIE_KEYS: z.string().min(32).meta({
+    SECRET_FUZ_COOKIE_KEYS: z.string().min(32).meta({
         description: 'Cookie signing keys, separated by __ for rotation',
         sensitivity: 'secret',
     }),
-    ALLOWED_ORIGINS: z.string().min(1, 'ALLOWED_ORIGINS is required').meta({
+    FUZ_ALLOWED_ORIGINS: z.string().min(1, 'FUZ_ALLOWED_ORIGINS is required').meta({
         description: 'Comma-separated origin patterns for API verification',
     }),
-    PUBLIC_API_URL: z.string().default('/api').meta({ description: 'Public API base URL' }),
-    PUBLIC_WEBSOCKET_URL: z.string().optional().meta({ description: 'Public WebSocket URL' }),
-    PUBLIC_CONTACT_EMAIL: z
+    PUBLIC_FUZ_API_URL: z.string().default('/api').meta({ description: 'Public API base URL' }),
+    PUBLIC_FUZ_WEBSOCKET_URL: z.string().optional().meta({ description: 'Public WebSocket URL' }),
+    PUBLIC_FUZ_CONTACT_EMAIL: z
         .union([z.email(), z.literal('')])
         .optional()
         .meta({ description: 'Public contact email address' }),
-    BOOTSTRAP_TOKEN_PATH: z
+    FUZ_BOOTSTRAP_TOKEN_PATH: z
         .string()
         .optional()
         .meta({ description: 'Path to one-shot admin bootstrap token', sensitivity: 'secret' }),
@@ -64,32 +64,32 @@ export const BaseServerEnv = z.strictObject({
  * @returns `{ok: true, keyring, allowed_origins, bootstrap_token_path}` or `{ok: false, field, errors}`
  */
 export const validate_server_env = (env) => {
-    const keyring_result = create_validated_keyring(env.SECRET_COOKIE_KEYS);
+    const keyring_result = create_validated_keyring(env.SECRET_FUZ_COOKIE_KEYS);
     if (!keyring_result.ok) {
-        return { ok: false, field: 'SECRET_COOKIE_KEYS', errors: keyring_result.errors };
+        return { ok: false, field: 'SECRET_FUZ_COOKIE_KEYS', errors: keyring_result.errors };
     }
     let allowed_origins;
     try {
-        allowed_origins = parse_allowed_origins(env.ALLOWED_ORIGINS);
+        allowed_origins = parse_allowed_origins(env.FUZ_ALLOWED_ORIGINS);
     }
     catch (err) {
         return {
             ok: false,
-            field: 'ALLOWED_ORIGINS',
-            errors: [err instanceof Error ? err.message : 'Invalid ALLOWED_ORIGINS'],
+            field: 'FUZ_ALLOWED_ORIGINS',
+            errors: [err instanceof Error ? err.message : 'Invalid FUZ_ALLOWED_ORIGINS'],
         };
     }
     if (allowed_origins.length === 0) {
         return {
             ok: false,
-            field: 'ALLOWED_ORIGINS',
-            errors: ['ALLOWED_ORIGINS contains no valid patterns'],
+            field: 'FUZ_ALLOWED_ORIGINS',
+            errors: ['FUZ_ALLOWED_ORIGINS contains no valid patterns'],
         };
     }
     return {
         ok: true,
         keyring: keyring_result.keyring,
         allowed_origins,
-        bootstrap_token_path: env.BOOTSTRAP_TOKEN_PATH ?? null,
+        bootstrap_token_path: env.FUZ_BOOTSTRAP_TOKEN_PATH ?? null,
     };
 };

package/dist/server/startup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"startup.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/startup.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAGpD,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,oBAAoB,CAAC;AAEnD;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,GAC/B,SAAS,UAAU,EACnB,KAAK,MAAM,EACX,aAAa,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAClC,IAqCF,CAAC"}
+{"version":3,"file":"startup.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/startup.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAGpD,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,oBAAoB,CAAC;AAEnD;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,GAC/B,SAAS,UAAU,EACnB,KAAK,MAAM,EACX,aAAa,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAClC,IAkDF,CAAC"}

package/dist/server/startup.js

@@ -17,6 +17,18 @@ import { format_env_display_value } from '../env/mask.js';
  */
 export const log_startup_summary = (surface, log, env_values) => {
     log.info(`Surface: ${surface.routes.length} routes, ${surface.middleware.length} middleware layers`);
+    // Endpoint surfaces — logged when non-empty so operators can confirm
+    // auto-mount picked up the expected actions (and so a factory that
+    // silently returns `[]` is loud at boot instead of a method_not_found
+    // at first call).
+    if (surface.rpc_endpoints.length) {
+        const rpc_method_count = surface.rpc_endpoints.reduce((sum, ep) => sum + ep.methods.length, 0);
+        log.info(`RPC: ${surface.rpc_endpoints.length} endpoint(s), ${rpc_method_count} method(s)`);
+    }
+    if (surface.ws_endpoints.length) {
+        const ws_method_count = surface.ws_endpoints.reduce((sum, ep) => sum + ep.methods.length, 0);
+        log.info(`WS: ${surface.ws_endpoints.length} endpoint(s), ${ws_method_count} method(s)`);
+    }
     if (surface.env.length) {
         const required = surface.env.filter((e) => !e.optional);
         const secret = surface.env.filter((e) => e.sensitivity === 'secret');

package/dist/server/static.d.ts

@@ -1,10 +1,10 @@
 /**
  * Static file serving middleware for SvelteKit static builds.
  *
- * Provides multi-phase static serving:
- * - Phase 1: Exact path match (handles /, assets, images)
- * - Phase 2: `.html` fallback for clean URLs (`/about` → `/about.html`)
- * - Phase 3 (optional): SPA fallback for client-side routes
+ * Multi-step static serving:
+ * - Step 1: Exact path match (handles /, assets, images)
+ * - Step 2: `.html` fallback for clean URLs (`/about` → `/about.html`)
+ * - Step 3 (optional): SPA fallback for client-side routes
  *
  * @module
  */

package/dist/server/static.js

@@ -1,10 +1,10 @@
 /**
  * Static file serving middleware for SvelteKit static builds.
  *
- * Provides multi-phase static serving:
- * - Phase 1: Exact path match (handles /, assets, images)
- * - Phase 2: `.html` fallback for clean URLs (`/about` → `/about.html`)
- * - Phase 3 (optional): SPA fallback for client-side routes
+ * Multi-step static serving:
+ * - Step 1: Exact path match (handles /, assets, images)
+ * - Step 2: `.html` fallback for clean URLs (`/about` → `/about.html`)
+ * - Step 3 (optional): SPA fallback for client-side routes
  *
  * @module
  */
@@ -21,16 +21,16 @@ const is_spa_route_default = (path) => !path.startsWith('/api/');
 export const create_static_middleware = (serve_static, options) => {
     const root = options?.root ?? './build';
     const handlers = [];
-    // Phase 1: exact path match
+    // Step 1: exact path match
     handlers.push(serve_static({ root }));
-    // Phase 2: .html fallback for clean URLs (/about → /about.html)
+    // Step 2: .html fallback for clean URLs (/about → /about.html)
     handlers.push(async (c, next) => {
         const path = c.req.path;
         if (path === '/' || path.includes('.'))
             return next();
         return serve_static({ root, rewriteRequestPath: () => `${path}.html` })(c, next);
     });
-    // Phase 3: optional SPA fallback for client-side routes
+    // Step 3: optional SPA fallback for client-side routes
     if (options?.spa_fallback) {
         const fallback = options.spa_fallback;
         const is_spa_route = options.is_spa_route ?? is_spa_route_default;