@fuzdev/fuz_app 0.62.0 → 0.64.0

package/dist/http/proxy.js

@@ -8,24 +8,25 @@
  * @module
  */
 import { convertIPv4ToBinary, convertIPv6ToBinary, distinctRemoteAddr } from 'hono/utils/ipaddr';
+import { canonicalize_ip, IP_LITERAL_CHARS } from './ip_canonical.js';
 /**
  * Normalize an IP address for consistent matching and storage.
  *
- * - Strips `::ffff:` prefix from IPv4-mapped IPv6 addresses
- *   (e.g. `::ffff:127.0.0.1` → `127.0.0.1`)
- * - Lowercases for case-insensitive IPv6 comparison
- * - Idempotent: calling twice produces the same result
- * - Safe on non-IP strings: `normalize_ip('unknown')` returns `'unknown'`
+ * Delegates to `canonicalize_ip` from `ip_canonical.ts` — collapses
+ * RFC 5952-equivalent IPv6 forms (`::1`, `::0001`, `0:0:0:0:0:0:0:1`)
+ * into a single key, emits IPv4-mapped IPv6 in dotted form, and
+ * strips the `::ffff:` prefix from dotted IPv4-mapped values so the
+ * bucket collapses to plain IPv4.
+ *
+ * - Lowercases for case-insensitive IPv6 comparison.
+ * - Idempotent: calling twice produces the same result.
+ * - Safe on non-IP strings: `normalize_ip('unknown')` returns `'unknown'`.
+ *   Malformed inputs (`'attacker:controlled'`, `'::1\n'`,
+ *   `'203.0.113.1:8080'`) pass through unchanged so downstream
+ *   `validate_ip_strict` can still reject them — canonicalization
+ *   never erases the malformed-form signal.
  */
-export const normalize_ip = (ip) => {
-    const lowered = ip.toLowerCase();
-    // Strip ::ffff: prefix only when remainder contains a dot (IPv4-mapped IPv6).
-    // This distinguishes ::ffff:127.0.0.1 (IPv4-mapped) from ::ffff:1 (pure IPv6).
-    if (lowered.startsWith('::ffff:') && lowered.substring(7).includes('.')) {
-        return lowered.substring(7);
-    }
-    return lowered;
-};
+export const normalize_ip = (ip) => canonicalize_ip(ip);
 /**
  * Parse a trusted proxy entry string into a structured form.
  *
@@ -91,15 +92,6 @@ const cidr_contains = (ip_binary, network, prefix, total_bits) => {
     const shift = BigInt(total_bits - prefix);
     return ip_binary >> shift === network >> shift;
 };
-/**
- * Allowed character set for a bare IP literal.
- *
- * Covers the union of IPv4 (digits + `.`), IPv6 (hex digits + `:`), and
- * IPv4-mapped IPv6 forms (`::ffff:127.0.0.1`). Anything outside this
- * set — brackets, whitespace, control bytes, letters g-z — disqualifies
- * the input regardless of what Hono's parser does with it.
- */
-const IP_LITERAL_CHARS = /^[0-9a-fA-F.:]+$/;
 /**
  * Strict IP validity check.
  *

package/dist/http/surface.d.ts

@@ -13,6 +13,8 @@ import type { RouteSpec } from './route_spec.js';
 import type { RouteAuth } from './auth_shape.js';
 import type { RateLimitKey, RouteErrorSchemas } from './error_schemas.js';
 import type { RpcAction } from '../actions/action_rpc.js';
+import type { ActionKind } from '../actions/action_spec.js';
+import type { WsEndpointSpec } from '../actions/ws_endpoint_spec.js';
 import type { Sensitivity } from '../sensitivity.js';
 /** A route in the generated attack surface (JSON-serializable). */
 export interface AppSurfaceRoute {
@@ -79,6 +81,45 @@ export interface AppSurfaceRpcEndpoint {
     path: string;
     methods: Array<AppSurfaceRpcMethod>;
 }
+/** A method within a WebSocket endpoint in the generated attack surface (JSON-serializable). */
+export interface AppSurfaceWsMethod {
+    name: string;
+    /** `request_response` (inbound dispatch) or `remote_notification` (server → client). */
+    kind: ActionKind;
+    /**
+     * Per-action auth shape. `null` for `remote_notification` (server →
+     * client) — notifications have no inbound dispatch and therefore no
+     * auth axis. `request_response` always carries a `RouteAuth`.
+     */
+    auth: RouteAuth | null;
+    /** JSON Schema of the input schema. `null` for nullary inputs. */
+    input_schema: unknown;
+    /** JSON Schema of the output schema. */
+    output_schema: unknown;
+    description: string;
+    side_effects: boolean;
+    /** Rate limit key declared on the action spec. `null` when not rate-limited. */
+    rate_limit_key: RateLimitKey | null;
+}
+/** A WebSocket endpoint in the generated attack surface (JSON-serializable). */
+export interface AppSurfaceWsEndpoint {
+    path: string;
+    /**
+     * Upgrade-time origin allowlist, one entry per `WsEndpointSpec.allowed_origins`
+     * regex stringified via `RegExp.prototype.toString()` (`'/<source>/<flags>'`).
+     * Empty array when no origins were declared (any-origin); reviewers read this
+     * as the exact pattern matched at the upgrade gate, not a wildcard
+     * approximation. Reconstruct via `new RegExp(source, flags)` if needed.
+     */
+    allowed_origins: ReadonlyArray<string>;
+    /**
+     * Upgrade-time role gate — empty array when no `required_roles` was
+     * declared (any-authenticated). Documents the coarse gate; per-action
+     * `auth` on each method covers per-message authorization.
+     */
+    required_roles: ReadonlyArray<string>;
+    methods: Array<AppSurfaceWsMethod>;
+}
 /** Assembly-time diagnostic collected during surface generation or server assembly. */
 export interface AppSurfaceDiagnostic {
     level: 'warning' | 'info';
@@ -91,6 +132,7 @@ export interface AppSurface {
     middleware: Array<AppSurfaceMiddleware>;
     routes: Array<AppSurfaceRoute>;
     rpc_endpoints: Array<AppSurfaceRpcEndpoint>;
+    ws_endpoints: Array<AppSurfaceWsEndpoint>;
     env: Array<AppSurfaceEnv>;
     events: Array<AppSurfaceEvent>;
     diagnostics: Array<AppSurfaceDiagnostic>;
@@ -106,6 +148,7 @@ export interface AppSurfaceSpec {
     route_specs: Array<RouteSpec>;
     middleware_specs: Array<MiddlewareSpec>;
     rpc_endpoints: Array<RpcEndpointSpec>;
+    ws_endpoints: Array<WsEndpointSpec>;
 }
 /** An RPC endpoint definition for surface generation. */
 export interface RpcEndpointSpec {
@@ -119,6 +162,13 @@ export interface GenerateAppSurfaceOptions {
     env_schema?: z.ZodObject;
     event_specs?: Array<EventSpec>;
     rpc_endpoints?: Array<RpcEndpointSpec>;
+    /**
+     * Mounted WS endpoints (the same array `create_app_server.ws_endpoints`
+     * auto-mounts). Each entry's actions surface into
+     * `AppSurface.ws_endpoints[i].methods` for attack-surface tests +
+     * startup logging.
+     */
+    ws_endpoints?: ReadonlyArray<WsEndpointSpec>;
 }
 /**
  * Collect error schemas from all middleware that applies to a route path.

package/dist/http/surface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"surface.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/surface.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"surface.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/surface.ts"],"names":[],"mappings":"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"}

package/dist/http/surface.js

@@ -60,7 +60,7 @@ export const events_to_surface = (event_specs) => {
  * and optional env/event metadata.
  */
 export const generate_app_surface = (options) => {
-    const { route_specs, middleware_specs, env_schema, event_specs, rpc_endpoints } = options;
+    const { route_specs, middleware_specs, env_schema, event_specs, rpc_endpoints, ws_endpoints } = options;
     const diagnostics = [];
     // Spec-level diagnostics: check for non-strict input schemas
     for (const r of route_specs) {
@@ -141,6 +141,31 @@ export const generate_app_surface = (options) => {
                 })),
             }))
             : [],
+        ws_endpoints: ws_endpoints?.length
+            ? ws_endpoints.map((ep) => ({
+                path: ep.path,
+                allowed_origins: ep.allowed_origins.map((re) => re.toString()),
+                required_roles: ep.required_roles ?? [],
+                // `local_call` specs are frontend-side helpers — registry-only
+                // on the backend, never dispatched over WS. Drop them from the
+                // surface so attack-surface tests reflect dispatchable methods
+                // only. Notifications are kept (server → client emit).
+                methods: ep.actions
+                    .filter((a) => a.spec.kind !== 'local_call')
+                    .map((a) => ({
+                    name: a.spec.method,
+                    kind: a.spec.kind,
+                    // `request_response` carries a `RouteAuth`; notifications
+                    // have `auth: null` (server-pushed, no inbound dispatch).
+                    auth: a.spec.auth,
+                    input_schema: schema_to_surface(a.spec.input),
+                    output_schema: schema_to_surface(a.spec.output),
+                    description: a.spec.description,
+                    side_effects: a.spec.side_effects,
+                    rate_limit_key: a.spec.kind === 'request_response' ? (a.spec.rate_limit ?? null) : null,
+                })),
+            }))
+            : [],
         env: env_schema ? env_schema_to_surface(env_schema) : [],
         events: event_specs?.length ? events_to_surface(event_specs) : [],
     };
@@ -155,5 +180,6 @@ export const create_app_surface_spec = (options) => {
         route_specs: options.route_specs,
         middleware_specs: options.middleware_specs,
         rpc_endpoints: options.rpc_endpoints ?? [],
+        ws_endpoints: options.ws_endpoints ? [...options.ws_endpoints] : [],
     };
 };

package/dist/primitive_schemas.d.ts

@@ -21,11 +21,27 @@ export declare const USERNAME_LENGTH_MIN = 3;
 export declare const USERNAME_LENGTH_MAX = 39;
 /** Maximum length for username input on login/lookup — more permissive than `USERNAME_LENGTH_MAX` for forward-compatibility if the creation limit is raised. */
 export declare const USERNAME_PROVIDED_LENGTH_MAX = 255;
-/** Username for account creation — starts with letter, alphanumeric/dash/underscore middle, ends with alphanumeric. No @ or . allowed. */
-export declare const Username: z.ZodString;
+/**
+ * Username for account creation — starts with letter, alphanumeric/dash/underscore middle, ends with alphanumeric. No @ or . allowed.
+ *
+ * Canonicalized to lowercase at parse time. The regex rejects whitespace
+ * outright, so `.trim()` is unnecessary here. Storage is canonical across
+ * every creation site (bootstrap, signup, admin-create, invite acceptance)
+ * because the schema is the single source of truth — eliminates the
+ * per-caller `trim().toLowerCase()` ritual and keeps the
+ * `LOWER(username) = LOWER($1)` lookup contract simple.
+ */
+export declare const Username: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
 export type Username = z.infer<typeof Username>;
-/** Username submitted for login or lookup — minimal validation for forward-compatibility if format rules change. */
-export declare const UsernameProvided: z.ZodString;
+/**
+ * Username submitted for login or lookup — minimal validation for forward-compatibility if format rules change.
+ *
+ * Canonicalized via `.trim().toLowerCase()` at parse time so login's
+ * per-account rate-limit key and DB lookup see a uniform value
+ * regardless of casing or surrounding whitespace. Mirrors the storage
+ * canonicalization on `Username` so submission and storage agree.
+ */
+export declare const UsernameProvided: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
 export type UsernameProvided = z.infer<typeof UsernameProvided>;
 /**
  * Email validation. Lives here rather than `@fuzdev/fuz_util` because every

package/dist/primitive_schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"primitive_schemas.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/primitive_schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAItB,2EAA2E;AAC3E,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC,wDAAwD;AACxD,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC,gKAAgK;AAChK,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAEhD,0IAA0I;AAC1I,eAAO,MAAM,QAAQ,aAIyB,CAAC;AAC/C,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAC;AAEhD,oHAAoH;AACpH,eAAO,MAAM,gBAAgB,aAAsD,CAAC;AACpF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,YAAY,CAAC;AAC/B,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,KAAK,CAAC,CAAC"}
+{"version":3,"file":"primitive_schemas.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/primitive_schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAItB,2EAA2E;AAC3E,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC,wDAAwD;AACxD,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC,gKAAgK;AAChK,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAEhD;;;;;;;;;GASG;AACH,eAAO,MAAM,QAAQ,wDAKc,CAAC;AACpC,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAC;AAEhD;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,wDAIa,CAAC;AAC3C,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,YAAY,CAAC;AAC/B,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,KAAK,CAAC,CAAC"}

package/dist/primitive_schemas.js

@@ -22,14 +22,35 @@ export const USERNAME_LENGTH_MIN = 3;
 export const USERNAME_LENGTH_MAX = 39;
 /** Maximum length for username input on login/lookup — more permissive than `USERNAME_LENGTH_MAX` for forward-compatibility if the creation limit is raised. */
 export const USERNAME_PROVIDED_LENGTH_MAX = 255;
-/** Username for account creation — starts with letter, alphanumeric/dash/underscore middle, ends with alphanumeric. No @ or . allowed. */
+/**
+ * Username for account creation — starts with letter, alphanumeric/dash/underscore middle, ends with alphanumeric. No @ or . allowed.
+ *
+ * Canonicalized to lowercase at parse time. The regex rejects whitespace
+ * outright, so `.trim()` is unnecessary here. Storage is canonical across
+ * every creation site (bootstrap, signup, admin-create, invite acceptance)
+ * because the schema is the single source of truth — eliminates the
+ * per-caller `trim().toLowerCase()` ritual and keeps the
+ * `LOWER(username) = LOWER($1)` lookup contract simple.
+ */
 export const Username = z
     .string()
     .min(USERNAME_LENGTH_MIN)
     .max(USERNAME_LENGTH_MAX)
-    .regex(/^[a-zA-Z][0-9a-zA-Z_-]*[0-9a-zA-Z]$/);
-/** Username submitted for login or lookup — minimal validation for forward-compatibility if format rules change. */
-export const UsernameProvided = z.string().min(1).max(USERNAME_PROVIDED_LENGTH_MAX);
+    .regex(/^[a-zA-Z][0-9a-zA-Z_-]*[0-9a-zA-Z]$/)
+    .transform((s) => s.toLowerCase());
+/**
+ * Username submitted for login or lookup — minimal validation for forward-compatibility if format rules change.
+ *
+ * Canonicalized via `.trim().toLowerCase()` at parse time so login's
+ * per-account rate-limit key and DB lookup see a uniform value
+ * regardless of casing or surrounding whitespace. Mirrors the storage
+ * canonicalization on `Username` so submission and storage agree.
+ */
+export const UsernameProvided = z
+    .string()
+    .min(1)
+    .max(USERNAME_PROVIDED_LENGTH_MAX)
+    .transform((s) => s.trim().toLowerCase());
 /**
  * Email validation. Lives here rather than `@fuzdev/fuz_util` because every
  * current consumer pairs it with `Username` (signup, invites, audit log) —

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,
-        },
-    };
 };