@fuzdev/fuz_app 0.15.0 → 0.16.0

package/dist/actions/register_action_ws.d.ts

@@ -0,0 +1,108 @@
+/**
+ * WebSocket JSON-RPC dispatch — the canonical WS transport binding.
+ *
+ * Symmetric to `create_rpc_endpoint` (from `actions/action_rpc.ts`):
+ * consumer supplies action specs + a handler map, the dispatcher parses the
+ * envelope, checks per-action auth, validates input, invokes the handler with
+ * a per-request context, and writes the response.
+ *
+ * Extracted from zzz's `register_websocket_actions` to converge pattern drift
+ * across consumers (zzz, tx, undying). Broadcast-style notifications remain
+ * domain-shaped today — this module only covers per-request dispatch + the
+ * socket-scoped `ctx.notify` + per-socket `ctx.signal`. See
+ * `BackendWebsocketTransport.send` for broadcast.
+ *
+ * ## Auth expectations
+ *
+ * The consumer is responsible for rejecting unauthenticated upgrades *before*
+ * routing to this handler (fuz_app's `require_auth` middleware). Inside the
+ * dispatcher, `get_request_context(c)` is treated as guaranteed non-null and
+ * per-action auth is enforced on each message.
+ *
+ * @module
+ */
+import type { Context, Hono } from 'hono';
+import type { UpgradeWebSocket } from 'hono/ws';
+import { type Logger as LoggerType } from '@fuzdev/fuz_util/log.js';
+import { type JsonrpcRequestId } from '../http/jsonrpc.js';
+import type { ActionSpecUnion } from './action_spec.js';
+import { BackendWebsocketTransport } from './transports_ws_backend.js';
+/**
+ * Minimum per-request context every handler receives.
+ *
+ * Consumers extend this with domain-specific fields via
+ * `RegisterActionWsOptions.extend_context` (e.g., a `backend` singleton
+ * or the authenticated `RequestContext`). Keeping the base minimal matches
+ * the HTTP-side `ActionContext` (from `actions/action_rpc.ts`) and mirrors
+ * Rust's `Ctx<'a>` shape (`request_id` + `NotifyFn` + `CancellationToken`).
+ */
+export interface BaseHandlerContext {
+    /** JSON-RPC envelope request id — echoed back on the response. */
+    request_id: JsonrpcRequestId;
+    /**
+     * Send a request-scoped JSON-RPC notification to the originating socket.
+     * Not a broadcast — the message only reaches the client whose request
+     * triggered this handler. Streaming handlers (e.g. `completion_progress`)
+     * route chunks through this.
+     */
+    notify: (method: string, params: unknown) => void;
+    /** Fires on socket close; streaming handlers poll for early termination. */
+    signal: AbortSignal;
+}
+/** Handler signature — receives validated input and per-request context. */
+export type WsActionHandler<TCtx extends BaseHandlerContext> = (input: unknown, ctx: TCtx) => unknown;
+/** Options for `register_action_ws`. */
+export interface RegisterActionWsOptions<TCtx extends BaseHandlerContext> {
+    /** Mount path (e.g., `/api/ws`). */
+    path: string;
+    /** The Hono app to mount on. */
+    app: Hono;
+    /** Hono's `upgradeWebSocket` helper from the runtime adapter. */
+    upgradeWebSocket: UpgradeWebSocket;
+    /** Action specs — drives method lookup, per-action auth, and input/output validation. */
+    specs: ReadonlyArray<ActionSpecUnion>;
+    /** Handler map keyed by `spec.method`. */
+    handlers: Record<string, WsActionHandler<TCtx>>;
+    /**
+     * Build the per-request context from the base and the upgrade-time Hono
+     * context. Called once per incoming message. Consumers use this to attach
+     * domain singletons (`backend`) or per-socket auth (`auth`,
+     * `credential_type`) without re-reading them from `c` inside every handler.
+     */
+    extend_context: (base: BaseHandlerContext, c: Context) => TCtx;
+    /**
+     * Existing transport to register connections with. When omitted, a fresh
+     * one is created and returned in the result. Pass your own to keep a
+     * handle for `create_ws_auth_guard` and `send_to`/`broadcast`.
+     */
+    transport?: BackendWebsocketTransport;
+    /** Optional per-message delay for testing loading states. Ignored when `0`. */
+    artificial_delay?: number;
+    /** Optional logger; defaults to `[ws]` namespace. */
+    log?: LoggerType;
+}
+/** Result of `register_action_ws`. */
+export interface RegisterActionWsResult {
+    /** The transport bound to the endpoint — supplied or freshly created. */
+    transport: BackendWebsocketTransport;
+}
+/**
+ * Mount a JSON-RPC WebSocket endpoint that dispatches to the supplied handler
+ * map. Per-request context is built from the base + consumer-provided
+ * `RegisterActionWsOptions.extend_context`.
+ *
+ * Wire behavior:
+ * - Batch JSON-RPC is rejected (single-message only).
+ * - Notifications (method + no id) are silently dropped per JSON-RPC spec.
+ * - Per-action auth: `public` / `authenticated` pass through (upgrade auth
+ *   already verified identity); `keeper` requires `daemon_token` credential
+ *   type *and* the keeper role; role-based `{role}` is currently rejected as
+ *   not-yet-supported.
+ * - DEV mode validates handler output against the spec's `output` schema and
+ *   warns on mismatches.
+ *
+ * @returns the transport (supplied or freshly created) — retain it to wire
+ *   `create_ws_auth_guard` or broadcast on audit events.
+ */
+export declare const register_action_ws: <TCtx extends BaseHandlerContext>(options: RegisterActionWsOptions<TCtx>) => RegisterActionWsResult;
+//# sourceMappingURL=register_action_ws.d.ts.map

package/dist/actions/register_action_ws.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register_action_ws.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/register_action_ws.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,KAAK,EAAC,OAAO,EAAE,IAAI,EAAC,MAAM,MAAM,CAAC;AACxC,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,SAAS,CAAC;AAE9C,OAAO,EAAS,KAAK,MAAM,IAAI,UAAU,EAAC,MAAM,yBAAyB,CAAC;AAK1E,OAAO,EAAkB,KAAK,gBAAgB,EAAC,MAAM,oBAAoB,CAAC;AAY1E,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAC,yBAAyB,EAAC,MAAM,4BAA4B,CAAC;AAErE;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAkB;IAClC,kEAAkE;IAClE,UAAU,EAAE,gBAAgB,CAAC;IAC7B;;;;;OAKG;IACH,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAClD,4EAA4E;IAC5E,MAAM,EAAE,WAAW,CAAC;CACpB;AAED,4EAA4E;AAC5E,MAAM,MAAM,eAAe,CAAC,IAAI,SAAS,kBAAkB,IAAI,CAC9D,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,IAAI,KACL,OAAO,CAAC;AAEb,wCAAwC;AACxC,MAAM,WAAW,uBAAuB,CAAC,IAAI,SAAS,kBAAkB;IACvE,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,GAAG,EAAE,IAAI,CAAC;IACV,iEAAiE;IACjE,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,yFAAyF;IACzF,KAAK,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IACtC,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC;IAChD;;;;;OAKG;IACH,cAAc,EAAE,CAAC,IAAI,EAAE,kBAAkB,EAAE,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAC/D;;;;OAIG;IACH,SAAS,CAAC,EAAE,yBAAyB,CAAC;IACtC,+EAA+E;IAC/E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qDAAqD;IACrD,GAAG,CAAC,EAAE,UAAU,CAAC;CACjB;AAED,sCAAsC;AACtC,MAAM,WAAW,sBAAsB;IACtC,yEAAyE;IACzE,SAAS,EAAE,yBAAyB,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,kBAAkB,GAAI,IAAI,SAAS,kBAAkB,EACjE,SAAS,uBAAuB,CAAC,IAAI,CAAC,KACpC,sBA0NF,CAAC"}

package/dist/actions/register_action_ws.js

@@ -0,0 +1,187 @@
+/**
+ * WebSocket JSON-RPC dispatch — the canonical WS transport binding.
+ *
+ * Symmetric to `create_rpc_endpoint` (from `actions/action_rpc.ts`):
+ * consumer supplies action specs + a handler map, the dispatcher parses the
+ * envelope, checks per-action auth, validates input, invokes the handler with
+ * a per-request context, and writes the response.
+ *
+ * Extracted from zzz's `register_websocket_actions` to converge pattern drift
+ * across consumers (zzz, tx, undying). Broadcast-style notifications remain
+ * domain-shaped today — this module only covers per-request dispatch + the
+ * socket-scoped `ctx.notify` + per-socket `ctx.signal`. See
+ * `BackendWebsocketTransport.send` for broadcast.
+ *
+ * ## Auth expectations
+ *
+ * The consumer is responsible for rejecting unauthenticated upgrades *before*
+ * routing to this handler (fuz_app's `require_auth` middleware). Inside the
+ * dispatcher, `get_request_context(c)` is treated as guaranteed non-null and
+ * per-action auth is enforced on each message.
+ *
+ * @module
+ */
+import { DEV } from 'esm-env';
+import { wait } from '@fuzdev/fuz_util/async.js';
+import { Logger } from '@fuzdev/fuz_util/log.js';
+import { get_request_context, has_role } from '../auth/request_context.js';
+import { hash_session_token } from '../auth/session_queries.js';
+import { ROLE_KEEPER } from '../auth/role_schema.js';
+import { JSONRPC_VERSION } from '../http/jsonrpc.js';
+import { jsonrpc_error_messages } from '../http/jsonrpc_errors.js';
+import { create_jsonrpc_error_response, create_jsonrpc_error_response_from_thrown, create_jsonrpc_notification, to_jsonrpc_message_id, to_jsonrpc_params, is_jsonrpc_request, } from '../http/jsonrpc_helpers.js';
+import { CREDENTIAL_TYPE_KEY, AUTH_API_TOKEN_ID_KEY } from '../hono_context.js';
+import { BackendWebsocketTransport } from './transports_ws_backend.js';
+/**
+ * Mount a JSON-RPC WebSocket endpoint that dispatches to the supplied handler
+ * map. Per-request context is built from the base + consumer-provided
+ * `RegisterActionWsOptions.extend_context`.
+ *
+ * Wire behavior:
+ * - Batch JSON-RPC is rejected (single-message only).
+ * - Notifications (method + no id) are silently dropped per JSON-RPC spec.
+ * - Per-action auth: `public` / `authenticated` pass through (upgrade auth
+ *   already verified identity); `keeper` requires `daemon_token` credential
+ *   type *and* the keeper role; role-based `{role}` is currently rejected as
+ *   not-yet-supported.
+ * - DEV mode validates handler output against the spec's `output` schema and
+ *   warns on mismatches.
+ *
+ * @returns the transport (supplied or freshly created) — retain it to wire
+ *   `create_ws_auth_guard` or broadcast on audit events.
+ */
+export const register_action_ws = (options) => {
+    const { path, app, upgradeWebSocket, specs, handlers, extend_context, transport = new BackendWebsocketTransport(), artificial_delay = 0, log = new Logger('[ws]'), } = options;
+    // Build spec lookup for per-action auth and input validation.
+    const spec_by_method = new Map(specs.map((spec) => [spec.method, spec]));
+    app.get(path, upgradeWebSocket((c) => {
+        // Upgrade-time auth extraction — `require_auth` middleware has already
+        // rejected unauthenticated requests, so request_context is guaranteed
+        // non-null by the time we get here.
+        const request_context = get_request_context(c);
+        const account_id = request_context.account.id;
+        const credential_type = c.get(CREDENTIAL_TYPE_KEY);
+        // Session-based connections have a token hash for targeted revocation.
+        // Bearer/daemon connections pass null — still reachable via
+        // `close_sockets_for_account` / `close_sockets_for_token`.
+        const token_hash = credential_type === 'session' ? hash_session_token(c.get('auth_session_id')) : null;
+        // `api_token.id` — set only for bearer connections; enables
+        // `close_sockets_for_token` to tear down just this socket on
+        // `token_revoke` without affecting the account's other sockets.
+        const api_token_id = c.get(AUTH_API_TOKEN_ID_KEY);
+        // Per-socket abort controller — fires on socket close, threaded into
+        // every in-flight handler's ctx.signal on this connection. A
+        // dedicated per-request controller linked to this is future work;
+        // a single socket-scoped signal is sufficient today since cancel
+        // granularity tracks connection lifetime, not individual requests.
+        const socket_abort_controller = new AbortController();
+        return {
+            onOpen: (event, ws) => {
+                const connection_id = transport.add_connection(ws, token_hash, account_id, api_token_id);
+                log.debug('ws opened', connection_id, event);
+            },
+            onMessage: async (event, ws) => {
+                let json;
+                try {
+                    json = JSON.parse(String(event.data)); // eslint-disable-line @typescript-eslint/no-base-to-string
+                }
+                catch (error) {
+                    log.error('JSON parse error:', error);
+                    ws.send(JSON.stringify(create_jsonrpc_error_response(null, jsonrpc_error_messages.parse_error())));
+                    return;
+                }
+                // Batch JSON-RPC is not supported on the WebSocket path.
+                if (Array.isArray(json)) {
+                    ws.send(JSON.stringify(create_jsonrpc_error_response(null, jsonrpc_error_messages.invalid_request('batch JSON-RPC requests are not supported on WebSocket'))));
+                    return;
+                }
+                // Only handle requests (method + id). Notifications (no id) are silenced per JSON-RPC spec.
+                if (!is_jsonrpc_request(json)) {
+                    if (typeof json === 'object' && json !== null && 'method' in json && !('id' in json)) {
+                        return;
+                    }
+                    ws.send(JSON.stringify(create_jsonrpc_error_response(to_jsonrpc_message_id(json), jsonrpc_error_messages.invalid_request())));
+                    return;
+                }
+                const { method, id, params } = json;
+                // Per-action auth check — enforce auth level from spec.
+                const spec = spec_by_method.get(method);
+                if (!spec) {
+                    ws.send(JSON.stringify(create_jsonrpc_error_response(id, jsonrpc_error_messages.method_not_found(method))));
+                    return;
+                }
+                const { auth } = spec;
+                if (auth === 'keeper') {
+                    if (credential_type !== 'daemon_token' || !has_role(request_context, ROLE_KEEPER)) {
+                        ws.send(JSON.stringify(create_jsonrpc_error_response(id, jsonrpc_error_messages.forbidden('keeper actions require daemon_token credential with keeper role'))));
+                        return;
+                    }
+                }
+                else if (typeof auth === 'object' && auth !== null) {
+                    ws.send(JSON.stringify(create_jsonrpc_error_response(id, jsonrpc_error_messages.internal_error('role-based action auth is not yet supported on WebSocket'))));
+                    return;
+                }
+                // Look up handler — method is validated against spec_by_method above.
+                const handler = handlers[method];
+                if (!handler) {
+                    ws.send(JSON.stringify(create_jsonrpc_error_response(id, jsonrpc_error_messages.method_not_found(method))));
+                    return;
+                }
+                // Validate input against spec schema.
+                const parsed = spec.input.safeParse(params);
+                if (!parsed.success) {
+                    ws.send(JSON.stringify(create_jsonrpc_error_response(id, jsonrpc_error_messages.invalid_params(`invalid params for ${method}`, {
+                        issues: parsed.error.issues,
+                    }))));
+                    return;
+                }
+                const validated_input = parsed.data;
+                if (artificial_delay > 0) {
+                    log.debug(`throttling ${artificial_delay}ms`);
+                    await wait(artificial_delay);
+                }
+                // Socket-scoped notification — routes to originator only, not
+                // broadcast. Future work (websockets quest Phase 3/4): other
+                // audiences — account-scoped, ACL-filtered, broadcast —
+                // likely via a transport-level policy hook.
+                const notify = (notify_method, notify_params) => {
+                    try {
+                        const notification = create_jsonrpc_notification(notify_method, to_jsonrpc_params(notify_params));
+                        ws.send(JSON.stringify(notification));
+                    }
+                    catch (error) {
+                        log.error('notify send failed:', notify_method, error);
+                    }
+                };
+                const base = {
+                    request_id: id,
+                    notify,
+                    signal: socket_abort_controller.signal,
+                };
+                const ctx = extend_context(base, c);
+                try {
+                    const output = await handler(validated_input, ctx);
+                    // DEV-only output validation — catches handler bugs during development.
+                    if (DEV) {
+                        const output_parsed = spec.output.safeParse(output);
+                        if (!output_parsed.success) {
+                            log.error(`output validation failed for ${method}:`, output_parsed.error.issues);
+                        }
+                    }
+                    // Send result directly — null stays null, matching the HTTP RPC path.
+                    ws.send(JSON.stringify({ jsonrpc: JSONRPC_VERSION, id, result: output }));
+                }
+                catch (error) {
+                    log.error('handler error:', method, error);
+                    ws.send(JSON.stringify(create_jsonrpc_error_response_from_thrown(id, error)));
+                }
+            },
+            onClose: (event, ws) => {
+                socket_abort_controller.abort();
+                transport.remove_connection(ws);
+                log.debug('ws closed', event);
+            },
+        };
+    }));
+    return { transport };
+};

package/dist/actions/transports_ws_auth_guard.d.ts

@@ -1,5 +1,5 @@
 /**
- * WebSocket auth guard — bridges audit events to {@link BackendWebsocketTransport}.
+ * WebSocket auth guard — bridges audit events to `BackendWebsocketTransport`.
  *
  * Mirror of `realtime/sse_auth_guard.ts` for the backend WebSocket transport.
  * Dispatches audit events to the right `close_sockets_for_*` method so

package/dist/actions/transports_ws_auth_guard.js

@@ -1,5 +1,5 @@
 /**
- * WebSocket auth guard — bridges audit events to {@link BackendWebsocketTransport}.
+ * WebSocket auth guard — bridges audit events to `BackendWebsocketTransport`.
  *
  * Mirror of `realtime/sse_auth_guard.ts` for the backend WebSocket transport.
  * Dispatches audit events to the right `close_sockets_for_*` method so

package/dist/actions/transports_ws_backend.d.ts

@@ -14,7 +14,7 @@ import { type Transport } from './transports.js';
  * One record per connection. `token_hash` is set for cookie-session
  * connections, `api_token_id` for bearer (`api_token`) connections, and
  * both are null for daemon-token connections (reachable only via
- * {@link BackendWebsocketTransport.close_sockets_for_account}).
+ * `BackendWebsocketTransport.close_sockets_for_account`).
  */
 export interface ConnectionIdentity {
     /** Blake3 session token hash, or null for non-session credentials. */
@@ -34,7 +34,7 @@ export declare class BackendWebsocketTransport implements Transport {
      * socket can be closed when that specific token is revoked without
      * tearing down the account's other sockets. Daemon-token connections
      * pass `null` for both — they're only reachable via
-     * {@link close_sockets_for_account}.
+     * `close_sockets_for_account`.
      */
     add_connection(ws: WSContext, token_hash: string | null, account_id: Uuid, api_token_id?: string | null): Uuid;
     /**

package/dist/actions/transports_ws_backend.js

@@ -24,7 +24,7 @@ export class BackendWebsocketTransport {
      * socket can be closed when that specific token is revoked without
      * tearing down the account's other sockets. Daemon-token connections
      * pass `null` for both — they're only reachable via
-     * {@link close_sockets_for_account}.
+     * `close_sockets_for_account`.
      */
     add_connection(ws, token_hash, account_id, api_token_id = null) {
         const connection_id = create_uuid();

package/dist/auth/keyring.d.ts

@@ -61,7 +61,7 @@ export declare const create_keyring: (env_value: string | undefined) => Keyring
  *
  * Returns an error when no keys are configured (undefined, empty string,
  * or all-separator input like `'____'`), and for each key shorter than
- * {@link MIN_KEY_LENGTH} characters.
+ * `MIN_KEY_LENGTH` characters.
  *
  * @param env_value - the SECRET_COOKIE_KEYS environment variable
  * @returns array of validation errors (empty if valid)

package/dist/auth/keyring.js

@@ -75,7 +75,7 @@ export const create_keyring = (env_value) => {
  *
  * Returns an error when no keys are configured (undefined, empty string,
  * or all-separator input like `'____'`), and for each key shorter than
- * {@link MIN_KEY_LENGTH} characters.
+ * `MIN_KEY_LENGTH` characters.
  *
  * @param env_value - the SECRET_COOKIE_KEYS environment variable
  * @returns array of validation errors (empty if valid)

package/dist/realtime/sse_auth_guard.d.ts

@@ -17,7 +17,9 @@ import type { SseStream, SseNotification, EventSpec } from './sse.js';
 /**
  * Audit event types that trigger SSE stream disconnection.
  *
- * `permit_revoke` requires the revoked role to match the guard's `required_role`.
+ * `permit_revoke` requires the revoked role to match the guard's `required_role`
+ * (or is skipped entirely when `required_role` is `null` — useful for streams
+ * not gated by any specific permit).
  * `session_revoke_all` and `password_change` close every stream for the target account.
  * `session_revoke` closes only the stream tied to the specific revoked session
  * (matched by the blake3 session hash in `event.metadata.session_id`) — closing
@@ -36,11 +38,13 @@ export declare const DISCONNECT_EVENT_TYPES: ReadonlySet<string>;
  * (passed as the third argument to `registry.subscribe()`).
  *
  * @param registry - the subscriber registry to guard
- * @param required_role - the role that grants access to the SSE endpoint
+ * @param required_role - the role that grants access to the SSE endpoint,
+ *   or `null` to skip `permit_revoke` handling entirely (for streams not gated
+ *   by a specific permit)
  * @param log - logger for disconnect events
  * @returns an `on_audit_event` callback
  */
-export declare const create_sse_auth_guard: <T>(registry: SubscriberRegistry<T>, required_role: string, log: Logger) => ((event: AuditLogEvent) => void);
+export declare const create_sse_auth_guard: <T>(registry: SubscriberRegistry<T>, required_role: string | null, log: Logger) => ((event: AuditLogEvent) => void);
 /**
  * Convenience factory result for audit log 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;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,EAAE,WAAW,CAAC,MAAM,CAKrD,CAAC;AAEH;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,qBAAqB,GAAI,CAAC,EACtC,UAAU,kBAAkB,CAAC,CAAC,CAAC,EAC/B,eAAe,MAAM,EACrB,KAAK,MAAM,KACT,CAAC,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CA2CjC,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;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,EAAE,KAAK,CAAC,SAAS,CAOlD,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAE9C,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;;;;;;;;;;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;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,EAAE,KAAK,CAAC,SAAS,CAOlD,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAE9C,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

@@ -15,7 +15,9 @@ import { SubscriberRegistry } from './subscriber_registry.js';
 /**
  * Audit event types that trigger SSE stream disconnection.
  *
- * `permit_revoke` requires the revoked role to match the guard's `required_role`.
+ * `permit_revoke` requires the revoked role to match the guard's `required_role`
+ * (or is skipped entirely when `required_role` is `null` — useful for streams
+ * not gated by any specific permit).
  * `session_revoke_all` and `password_change` close every stream for the target account.
  * `session_revoke` closes only the stream tied to the specific revoked session
  * (matched by the blake3 session hash in `event.metadata.session_id`) — closing
@@ -39,7 +41,9 @@ export const DISCONNECT_EVENT_TYPES = new Set([
  * (passed as the third argument to `registry.subscribe()`).
  *
  * @param registry - the subscriber registry to guard
- * @param required_role - the role that grants access to the SSE endpoint
+ * @param required_role - the role that grants access to the SSE endpoint,
+ *   or `null` to skip `permit_revoke` handling entirely (for streams not gated
+ *   by a specific permit)
  * @param log - logger for disconnect events
  * @returns an `on_audit_event` callback
  */
@@ -67,8 +71,11 @@ export const create_sse_auth_guard = (registry, required_role, log) => {
             }
             return;
         }
-        // permit_revoke requires matching the specific role
+        // permit_revoke requires matching the specific role. `null` means the
+        // stream isn't gated by a specific permit, so permit_revoke is a no-op.
         if (event.event_type === 'permit_revoke') {
+            if (required_role === null)
+                return;
             if (event.metadata?.role !== required_role)
                 return;
         }

package/dist/ui/form_state.svelte.d.ts

@@ -5,7 +5,7 @@
  * `attempted` state (set on submit attempt). Errors show after a field is blurred or
  * after a submit attempt, avoiding premature validation while the user is still typing.
  *
- * The {@link FormState.form | form} attachment also handles Enter key advancing
+ * The `FormState.form` attachment also handles Enter key advancing
  * between focusable elements.
  *
  * All trackable inputs must have a `name` attribute — an error is thrown in dev

package/dist/ui/form_state.svelte.js

@@ -5,7 +5,7 @@
  * `attempted` state (set on submit attempt). Errors show after a field is blurred or
  * after a submit attempt, avoiding premature validation while the user is still typing.
  *
- * The {@link FormState.form | form} attachment also handles Enter key advancing
+ * The `FormState.form` attachment also handles Enter key advancing
  * between focusable elements.
  *
  * All trackable inputs must have a `name` attribute — an error is thrown in dev

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/fuz_app",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "fullstack app library",
   "glyph": "🗝",
   "logo": "logo.svg",