@fuzdev/fuz_app 0.63.0 → 0.64.0

package/dist/realtime/sse_auth_guard.d.ts

@@ -58,7 +58,7 @@ export interface AuditLogSse {
     subscribe: (stream: SseStream<SseNotification>, options?: SubscribeOptions) => () => void;
     /** Logger — pass as part of `stream` option to `create_audit_log_route_specs`. */
     log: Logger;
-    /** Combined broadcast + guard callback. Pass as `on_audit_event` on `CreateAppBackendOptions`. */
+    /** Combined broadcast + guard callback. Wired by `create_app_server`'s `audit_log_sse` option, or compose inside the consumer's `audit_factory` body. */
     on_audit_event: (event: AuditLogEvent) => void;
     /** The underlying registry — exposed for subscriber count monitoring. */
     registry: SubscriberRegistry<SseNotification>;
@@ -86,7 +86,15 @@ export declare const AUDIT_LOG_SSE_MAX_PER_SCOPE = 10;
  *
  * Combines `SubscriberRegistry`, `create_sse_auth_guard`, and the broadcast
  * call into a single object. The result satisfies `AuditLogRouteOptions['stream']`
- * and provides the `on_audit_event` callback for `CreateAppBackendOptions`.
+ * and provides the `on_audit_event` listener for the audit emitter's chain.
+ *
+ * Most consumers pass `audit_log_sse: true` to `create_app_server` and never
+ * touch this directly — the factory builds an `AuditLogSse`, appends
+ * `audit_sse.on_audit_event` to `backend.deps.audit.on_event_chain`, and
+ * exposes it via `AppServerContext.audit_sse`. Reach for the manual path
+ * (compose inside `audit_factory` body, or
+ * `audit.on_event_chain.push(audit_sse.on_audit_event)` post-assembly) only
+ * when wiring outside `create_app_server`.
  *
  * @param options - factory options
  * @returns audit log SSE setup (stream options + `on_audit_event` + registry)
@@ -95,8 +103,12 @@ export declare const AUDIT_LOG_SSE_MAX_PER_SCOPE = 10;
  * ```ts
  * const audit_sse = create_audit_log_sse({log});
  *
- * // In create_app_backend options:
- * on_audit_event: audit_sse.on_audit_event,
+ * // Inside the audit_factory body on CreateAppBackendOptions:
+ * audit_factory: ({db, log}) => create_audit_emitter({
+ *   db,
+ *   log,
+ *   on_audit_event: audit_sse.on_audit_event,
+ * }),
  *
  * // In create_route_specs:
  * create_audit_log_route_specs({stream: audit_sse});

package/dist/realtime/sse_auth_guard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sse_auth_guard.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/realtime/sse_auth_guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,EAGN,KAAK,aAAa,EAClB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAC,kBAAkB,EAAE,KAAK,gBAAgB,EAAC,MAAM,0BAA0B,CAAC;AACnF,OAAO,KAAK,EAAC,SAAS,EAAE,eAAe,EAAE,SAAS,EAAC,MAAM,UAAU,CAAC;AAEpE,2DAA2D;AAC3D,eAAO,MAAM,iBAAiB,cAAc,CAAC;AAE7C;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB,EAAE,WAAW,CAAC,MAAM,CAKrD,CAAC;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,qBAAqB,GAAI,CAAC,EACtC,UAAU,kBAAkB,CAAC,CAAC,CAAC,EAC/B,eAAe,MAAM,GAAG,IAAI,EAC5B,KAAK,MAAM,KACT,CAAC,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CA6CjC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC3B,8FAA8F;IAC9F,SAAS,EAAE,CAAC,MAAM,EAAE,SAAS,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC,EAAE,gBAAgB,KAAK,MAAM,IAAI,CAAC;IAC1F,kFAAkF;IAClF,GAAG,EAAE,MAAM,CAAC;IACZ,kGAAkG;IAClG,cAAc,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;IAC/C,yEAAyE;IACzE,QAAQ,EAAE,kBAAkB,CAAC,eAAe,CAAC,CAAC;CAC9C;AAED;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,EAAE,KAAK,CAAC,SAAS,CAOlD,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,oBAAoB,GAAI,SAAS;IAC7C,mEAAmE;IACnE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B,KAAG,WAgBH,CAAC"}
+{"version":3,"file":"sse_auth_guard.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/realtime/sse_auth_guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,EAGN,KAAK,aAAa,EAClB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAC,kBAAkB,EAAE,KAAK,gBAAgB,EAAC,MAAM,0BAA0B,CAAC;AACnF,OAAO,KAAK,EAAC,SAAS,EAAE,eAAe,EAAE,SAAS,EAAC,MAAM,UAAU,CAAC;AAEpE,2DAA2D;AAC3D,eAAO,MAAM,iBAAiB,cAAc,CAAC;AAE7C;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB,EAAE,WAAW,CAAC,MAAM,CAKrD,CAAC;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,qBAAqB,GAAI,CAAC,EACtC,UAAU,kBAAkB,CAAC,CAAC,CAAC,EAC/B,eAAe,MAAM,GAAG,IAAI,EAC5B,KAAK,MAAM,KACT,CAAC,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CA6CjC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC3B,8FAA8F;IAC9F,SAAS,EAAE,CAAC,MAAM,EAAE,SAAS,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC,EAAE,gBAAgB,KAAK,MAAM,IAAI,CAAC;IAC1F,kFAAkF;IAClF,GAAG,EAAE,MAAM,CAAC;IACZ,yJAAyJ;IACzJ,cAAc,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;IAC/C,yEAAyE;IACzE,QAAQ,EAAE,kBAAkB,CAAC,eAAe,CAAC,CAAC;CAC9C;AAED;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,EAAE,KAAK,CAAC,SAAS,CAOlD,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,oBAAoB,GAAI,SAAS;IAC7C,mEAAmE;IACnE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B,KAAG,WAgBH,CAAC"}

package/dist/realtime/sse_auth_guard.js

@@ -120,7 +120,15 @@ export const AUDIT_LOG_SSE_MAX_PER_SCOPE = 10;
  *
  * Combines `SubscriberRegistry`, `create_sse_auth_guard`, and the broadcast
  * call into a single object. The result satisfies `AuditLogRouteOptions['stream']`
- * and provides the `on_audit_event` callback for `CreateAppBackendOptions`.
+ * and provides the `on_audit_event` listener for the audit emitter's chain.
+ *
+ * Most consumers pass `audit_log_sse: true` to `create_app_server` and never
+ * touch this directly — the factory builds an `AuditLogSse`, appends
+ * `audit_sse.on_audit_event` to `backend.deps.audit.on_event_chain`, and
+ * exposes it via `AppServerContext.audit_sse`. Reach for the manual path
+ * (compose inside `audit_factory` body, or
+ * `audit.on_event_chain.push(audit_sse.on_audit_event)` post-assembly) only
+ * when wiring outside `create_app_server`.
  *
  * @param options - factory options
  * @returns audit log SSE setup (stream options + `on_audit_event` + registry)
@@ -129,8 +137,12 @@ export const AUDIT_LOG_SSE_MAX_PER_SCOPE = 10;
  * ```ts
  * const audit_sse = create_audit_log_sse({log});
  *
- * // In create_app_backend options:
- * on_audit_event: audit_sse.on_audit_event,
+ * // Inside the audit_factory body on CreateAppBackendOptions:
+ * audit_factory: ({db, log}) => create_audit_emitter({
+ *   db,
+ *   log,
+ *   on_audit_event: audit_sse.on_audit_event,
+ * }),
  *
  * // In create_route_specs:
  * create_audit_log_route_specs({stream: audit_sse});

package/dist/server/app_backend.d.ts

@@ -12,8 +12,8 @@
  */
 import { Logger } from '@fuzdev/fuz_util/log.js';
 import type { AppDeps } from '../auth/deps.js';
-import type { AuditLogConfig, AuditLogEvent } from '../auth/audit_log_schema.js';
-import type { DbType } from '../db/db.js';
+import { type AuditEmitter } from '../auth/audit_emitter.js';
+import type { DbType, Db } from '../db/db.js';
 import type { Keyring } from '../auth/keyring.js';
 import type { PasswordHashDeps } from '../auth/password.js';
 import type { StatResult } from '../runtime/deps.js';
@@ -33,6 +33,49 @@ export interface AppBackend {
     /** Close the database connection. Bound to the actual driver. */
     close: () => Promise<void>;
 }
+/**
+ * Callback that builds the bound `AuditEmitter` after the backend's pool
+ * `Db` and `Logger` exist. Required on `CreateAppBackendOptions` so the
+ * consumer owns subscriber-chain composition and `AuditLogConfig`
+ * selection without the factory holding a default.
+ *
+ * The factory is invoked exactly once during `create_app_backend`, after
+ * `create_db` resolves and migrations run. The emitter it returns lands
+ * on `AppDeps.audit` and is captured by every query/handler that reaches
+ * `deps.audit.emit(...)`.
+ *
+ * The canonical body is a one-liner over `create_audit_emitter`:
+ *
+ * ```ts
+ * audit_factory: ({db, log}) => create_audit_emitter({
+ *   db,
+ *   log,
+ *   on_audit_event,
+ *   audit_log_config,
+ * })
+ * ```
+ *
+ * Returning an emitter built against a different `db` than the one passed
+ * in would route audit writes to a different pool than handlers query —
+ * the callback shape exists specifically to make that mistake structurally
+ * impossible.
+ */
+export type AuditFactory = (params: {
+    db: Db;
+    log: Logger;
+}) => AuditEmitter;
+/**
+ * Trivial `AuditFactory` for consumers that don't compose `on_audit_event`
+ * or `audit_log_config`. Equivalent to
+ * `({db, log}) => create_audit_emitter({db, log})` — exported so the
+ * default case stays a single-symbol reference rather than five tokens
+ * of boilerplate at every consumer.
+ *
+ * Use the inline form when you need to thread `on_audit_event` /
+ * `audit_log_config` / `emit_decorator`; the factory composes those
+ * three fields itself so there's nothing this constant can pass through.
+ */
+export declare const default_audit_factory: AuditFactory;
 /**
  * Input for `create_app_backend()`.
  *
@@ -55,21 +98,25 @@ export interface CreateAppBackendOptions {
     /** Structured logger instance. Omit for default (`new Logger('server')`). */
     log?: Logger;
     /**
-     * Initial subscriber appended to `AppDeps.audit.on_event_chain`.
-     * Use to broadcast audit events via SSE / WS. Additional subscribers
-     * (e.g. the factory-managed audit-log SSE) are appended at server
-     * assembly via `audit.on_event_chain.push(listener)` — no shallow-copy
-     * of `AppDeps` required.
-     */
-    on_audit_event?: (event: AuditLogEvent) => void;
-    /**
-     * Audit-log config for consumer event-type extensions. Built once at
-     * startup via `create_audit_log_config({extra_events})` and captured
-     * inside `AppDeps.audit` so consumer handlers cannot silently fall
-     * back to the builtin config. Omit to use `builtin_audit_log_config`
-     * (no extra events).
+     * Build the bound `AuditEmitter` once the backend's pool `Db` + `Logger`
+     * exist. Required — the factory owns subscriber-chain composition and
+     * `AuditLogConfig` selection without `create_app_backend` holding a
+     * default. Typical body:
+     *
+     * ```ts
+     * audit_factory: ({db, log}) => create_audit_emitter({
+     *   db,
+     *   log,
+     *   on_audit_event,
+     *   audit_log_config,
+     * })
+     * ```
+     *
+     * Additional listeners (factory-managed audit SSE, per-endpoint WS
+     * auth guards) are appended at `create_app_server` time via
+     * `audit.on_event_chain.push(...)`.
      */
-    audit_log_config?: AuditLogConfig;
+    audit_factory: AuditFactory;
     /**
      * Additional migration namespaces to run after the builtin auth namespace.
      * The shared `schema_version` table records one row per applied migration
@@ -87,10 +134,10 @@ export interface CreateAppBackendOptions {
  * Initialize the backend: database + auth migrations + deps.
  *
  * Calls `create_db` → `run_migrations` (auth namespace, then any
- * `migration_namespaces` from options in order) and bundles the result
- * with the provided keyring and password deps.
+ * `migration_namespaces` from options in order) → `audit_factory({db, log})`
+ * and bundles the result with the provided keyring and password deps.
  *
- * @param options - keyring, password deps, optional database URL, and optional `migration_namespaces`
+ * @param options - keyring, password deps, `audit_factory`, optional database URL, and optional `migration_namespaces`
  * @returns app backend with deps, database metadata, and combined migration results
  * @throws Error if `migration_namespaces` contains a namespace in `reserved_migration_namespaces`
  */

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

@@ -1 +1 @@
-{"version":3,"file":"app_backend.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/app_backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAE/C,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,iBAAiB,CAAC;AAC7C,OAAO,KAAK,EAAC,cAAc,EAAE,aAAa,EAAC,MAAM,6BAA6B,CAAC;AAE/E,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,aAAa,CAAC;AACxC,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,oBAAoB,CAAC;AAChD,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAiB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAC,MAAM,kBAAkB,CAAC;AAI/F;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IAC1B,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,oIAAoI;IACpI,QAAQ,CAAC,iBAAiB,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IAC3D,iEAAiE;IACjE,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACvC,+DAA+D;IAC/D,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IACnD,2BAA2B;IAC3B,cAAc,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAClD,qBAAqB;IACrB,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;IACrB,wCAAwC;IACxC,OAAO,EAAE,OAAO,CAAC;IACjB,iFAAiF;IACjF,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,6EAA6E;IAC7E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;IAChD;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,cAAc,CAAC;IAClC;;;;;;;;;;OAUG;IACH,oBAAoB,CAAC,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAC;CACzD;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,GAAU,SAAS,uBAAuB,KAAG,OAAO,CAAC,UAAU,CAuC7F,CAAC"}
+{"version":3,"file":"app_backend.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/app_backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAE/C,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAuB,KAAK,YAAY,EAAC,MAAM,0BAA0B,CAAC;AACjF,OAAO,KAAK,EAAC,MAAM,EAAE,EAAE,EAAC,MAAM,aAAa,CAAC;AAC5C,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,oBAAoB,CAAC;AAChD,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAiB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAC,MAAM,kBAAkB,CAAC;AAI/F;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IAC1B,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,oIAAoI;IACpI,QAAQ,CAAC,iBAAiB,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IAC3D,iEAAiE;IACjE,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,MAAM,EAAE;IAAC,EAAE,EAAE,EAAE,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAC,KAAK,YAAY,CAAC;AAE3E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,EAAE,YAA6D,CAAC;AAElG;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACvC,+DAA+D;IAC/D,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IACnD,2BAA2B;IAC3B,cAAc,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAClD,qBAAqB;IACrB,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;IACrB,wCAAwC;IACxC,OAAO,EAAE,OAAO,CAAC;IACjB,iFAAiF;IACjF,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,6EAA6E;IAC7E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;;;;;;;;;;;;;;OAkBG;IACH,aAAa,EAAE,YAAY,CAAC;IAC5B;;;;;;;;;;OAUG;IACH,oBAAoB,CAAC,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAC;CACzD;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,GAAU,SAAS,uBAAuB,KAAG,OAAO,CAAC,UAAU,CAiD7F,CAAC"}

package/dist/server/app_backend.js

@@ -15,52 +15,75 @@ import { create_audit_emitter } from '../auth/audit_emitter.js';
 import { run_migrations } from '../db/migrate.js';
 import { auth_migration_ns, reserved_migration_namespaces } from '../auth/migrations.js';
 import { create_db } from '../db/create_db.js';
+/**
+ * Trivial `AuditFactory` for consumers that don't compose `on_audit_event`
+ * or `audit_log_config`. Equivalent to
+ * `({db, log}) => create_audit_emitter({db, log})` — exported so the
+ * default case stays a single-symbol reference rather than five tokens
+ * of boilerplate at every consumer.
+ *
+ * Use the inline form when you need to thread `on_audit_event` /
+ * `audit_log_config` / `emit_decorator`; the factory composes those
+ * three fields itself so there's nothing this constant can pass through.
+ */
+export const default_audit_factory = ({ db, log }) => create_audit_emitter({ db, log });
 /**
  * Initialize the backend: database + auth migrations + deps.
  *
  * Calls `create_db` → `run_migrations` (auth namespace, then any
- * `migration_namespaces` from options in order) and bundles the result
- * with the provided keyring and password deps.
+ * `migration_namespaces` from options in order) → `audit_factory({db, log})`
+ * and bundles the result with the provided keyring and password deps.
  *
- * @param options - keyring, password deps, optional database URL, and optional `migration_namespaces`
+ * @param options - keyring, password deps, `audit_factory`, optional database URL, and optional `migration_namespaces`
  * @returns app backend with deps, database metadata, and combined migration results
  * @throws Error if `migration_namespaces` contains a namespace in `reserved_migration_namespaces`
  */
 export const create_app_backend = async (options) => {
-    const { database_url, keyring, password, stat, read_text_file, delete_file } = options;
+    const { database_url, keyring, password, stat, read_text_file, delete_file, audit_factory } = options;
     const log = options.log ?? new Logger('server');
     const { db, close, db_type, db_name } = await create_db(database_url);
-    if (options.migration_namespaces?.length) {
-        for (const ns of options.migration_namespaces) {
-            if (reserved_migration_namespaces.includes(ns.namespace)) {
-                throw new Error(`Migration namespace "${ns.namespace}" is reserved by fuz_app — choose a different namespace`);
+    // Everything after `create_db` can throw — reserved-namespace check,
+    // `run_migrations` (seven MigrationError kinds), `audit_factory`.
+    // Without this guard the pool leaks because `close` is only returned
+    // on the success path. Cleanup errors are logged and swallowed so the
+    // caller sees the original failure, not a teardown-shaped one.
+    try {
+        if (options.migration_namespaces?.length) {
+            for (const ns of options.migration_namespaces) {
+                if (reserved_migration_namespaces.includes(ns.namespace)) {
+                    throw new Error(`Migration namespace "${ns.namespace}" is reserved by fuz_app — choose a different namespace`);
+                }
             }
         }
+        const migration_results = await run_migrations(db, [
+            auth_migration_ns,
+            ...(options.migration_namespaces ?? []),
+        ]);
+        const audit = audit_factory({ db, log });
+        return {
+            db_type,
+            db_name,
+            migration_results,
+            close,
+            deps: {
+                keyring,
+                password,
+                db,
+                stat,
+                read_text_file,
+                delete_file,
+                log,
+                audit,
+            },
+        };
+    }
+    catch (err) {
+        try {
+            await close();
+        }
+        catch (close_err) {
+            log.error('create_app_backend: failed to close db after init error:', close_err);
+        }
+        throw err;
     }
-    const migration_results = await run_migrations(db, [
-        auth_migration_ns,
-        ...(options.migration_namespaces ?? []),
-    ]);
-    const audit = create_audit_emitter({
-        db,
-        log,
-        on_audit_event: options.on_audit_event,
-        audit_log_config: options.audit_log_config,
-    });
-    return {
-        db_type,
-        db_name,
-        migration_results,
-        close,
-        deps: {
-            keyring,
-            password,
-            db,
-            stat,
-            read_text_file,
-            delete_file,
-            log,
-            audit,
-        },
-    };
 };

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.
  */
@@ -163,6 +166,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 +288,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":"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"}
+{"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
@@ -127,7 +130,15 @@ export const create_app_server = async (options) => {
     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 = {
@@ -173,6 +184,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 +212,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 +236,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 +312,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 +401,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/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');