@fuzdev/fuz_app 0.15.0 → 0.17.0

package/dist/actions/broadcast_api.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Backend-initiated broadcast notification plumbing — generic across consumers.
+ *
+ * Builds a typed `{method_name: (input) => Promise<void>}` object from a list
+ * of action specs. Each call validates input against the spec, wraps it in a
+ * JSON-RPC notification, and either broadcasts to every connection or
+ * fans out with a per-connection ACL predicate.
+ *
+ * Counterpart to `register_action_ws`: that handles request-scoped dispatch
+ * (frontend-initiated), this handles broadcast (backend-initiated). Together
+ * they cover the two primitives fuz_app consumers share. Request-scoped
+ * streaming (`completion_progress`, `tx_apply` events) stays on
+ * `ctx.notify` inside a handler — it's socket-scoped, not broadcast.
+ *
+ * Extracted from zzz's `backend_actions_api.ts` as part of the websockets
+ * quest (Phase 3) to stop the pattern from drifting across zzz, tx, and
+ * undying.
+ *
+ * @module
+ */
+import { type Logger as LoggerType } from '@fuzdev/fuz_util/log.js';
+import type { ActionPeer } from './action_peer.js';
+import type { ActionSpecUnion } from './action_spec.js';
+import { type ConnectionIdentity } from './transports_ws_backend.js';
+/**
+ * Per-connection delivery predicate for subscription ACLs.
+ *
+ * Called once per connection for every broadcast send. Returning `false`
+ * skips that connection. Keep it fast — this runs in the broadcast hot path.
+ *
+ * `input` is the already-validated payload (matches the spec's input schema);
+ * `method` is the action method name.
+ */
+export type ShouldDeliverFn = (connection: ConnectionIdentity, method: string, input: unknown) => boolean;
+/** Options for `create_broadcast_api`. */
+export interface CreateBroadcastApiOptions {
+    /** The peer holding the transport registry used for sends. */
+    peer: ActionPeer;
+    /**
+     * Notification specs to expose as broadcast methods. Typically the
+     * `remote_notification` specs whose initiator is `backend` (or `both`).
+     * Other kinds are accepted — the helper only uses `spec.method` and
+     * `spec.input` — but the typical use is notifications.
+     */
+    specs: ReadonlyArray<ActionSpecUnion>;
+    /** Logger for validation/send errors. Defaults to a `[broadcast]` namespace. */
+    log?: LoggerType | null;
+    /**
+     * Optional per-connection ACL predicate. When set, the broadcast fans out
+     * via the transport's `broadcast_filtered` (feature-detected) — each
+     * connection's identity is checked before the message is sent. When
+     * unset, the transport broadcasts unfiltered via `transport.send`.
+     *
+     * Requires a transport that implements `FilterableBroadcastTransport`
+     * (today: only `BackendWebsocketTransport`). If set and the active
+     * transport is not filterable, the send is skipped and an error logged.
+     */
+    should_deliver?: ShouldDeliverFn;
+}
+/**
+ * Loose base shape for a broadcast API. Consumers typically declare a
+ * stricter per-method interface (e.g. `BackendActionsApi`) and pin it via
+ * the type parameter on `create_broadcast_api`.
+ */
+export type BroadcastApi = Record<string, (input: never) => Promise<void>>;
+/**
+ * Builds a typed broadcast API from a set of action specs.
+ *
+ * For each spec, adds a method keyed by `spec.method` that:
+ * - Validates `input` against the spec's Zod schema (logs and returns on failure)
+ * - Creates a JSON-RPC notification from the validated input
+ * - Broadcasts via the peer (filtered by `should_deliver` when supplied)
+ *
+ * Silently returns when no transport is ready (e.g. before any clients
+ * connect). Errors during send are logged but never thrown — broadcasts are
+ * fire-and-forget from the handler's perspective.
+ *
+ * ## Typed consumer surface
+ *
+ * Consumers declare an explicit interface and pin it via the type parameter:
+ *
+ * ```ts
+ * export interface BackendActionsApi {
+ *   filer_change: (input: ActionInputs['filer_change']) => Promise<void>;
+ *   workspace_changed: (input: ActionInputs['workspace_changed']) => Promise<void>;
+ * }
+ *
+ * const api = create_broadcast_api<BackendActionsApi>({
+ *   peer: backend.peer,
+ *   specs: [filer_change_action_spec, workspace_changed_action_spec],
+ * });
+ * ```
+ *
+ * The cast is unchecked — callers must keep the interface and the `specs`
+ * array in sync. Codegen (`action_collections.gen.ts`) is a natural fit
+ * if the consumer already generates per-method type maps.
+ */
+export declare const create_broadcast_api: <TApi = BroadcastApi>(options: CreateBroadcastApiOptions) => TApi;
+//# sourceMappingURL=broadcast_api.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"broadcast_api.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/broadcast_api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAS,KAAK,MAAM,IAAI,UAAU,EAAC,MAAM,yBAAyB,CAAC;AAG1E,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAEN,KAAK,kBAAkB,EACvB,MAAM,4BAA4B,CAAC;AAEpC;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG,CAC7B,UAAU,EAAE,kBAAkB,EAC9B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,KACV,OAAO,CAAC;AAEb,0CAA0C;AAC1C,MAAM,WAAW,yBAAyB;IACzC,8DAA8D;IAC9D,IAAI,EAAE,UAAU,CAAC;IACjB;;;;;OAKG;IACH,KAAK,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IACtC,gFAAgF;IAChF,GAAG,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IACxB;;;;;;;;;OASG;IACH,cAAc,CAAC,EAAE,eAAe,CAAC;CACjC;AAED;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;AAE3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,oBAAoB,GAAI,IAAI,GAAG,YAAY,EACvD,SAAS,yBAAyB,KAChC,IAoDF,CAAC"}

package/dist/actions/broadcast_api.js

@@ -0,0 +1,99 @@
+/**
+ * Backend-initiated broadcast notification plumbing — generic across consumers.
+ *
+ * Builds a typed `{method_name: (input) => Promise<void>}` object from a list
+ * of action specs. Each call validates input against the spec, wraps it in a
+ * JSON-RPC notification, and either broadcasts to every connection or
+ * fans out with a per-connection ACL predicate.
+ *
+ * Counterpart to `register_action_ws`: that handles request-scoped dispatch
+ * (frontend-initiated), this handles broadcast (backend-initiated). Together
+ * they cover the two primitives fuz_app consumers share. Request-scoped
+ * streaming (`completion_progress`, `tx_apply` events) stays on
+ * `ctx.notify` inside a handler — it's socket-scoped, not broadcast.
+ *
+ * Extracted from zzz's `backend_actions_api.ts` as part of the websockets
+ * quest (Phase 3) to stop the pattern from drifting across zzz, tx, and
+ * undying.
+ *
+ * @module
+ */
+import { Logger } from '@fuzdev/fuz_util/log.js';
+import { create_jsonrpc_notification, to_jsonrpc_params } from '../http/jsonrpc_helpers.js';
+import { is_filterable_broadcast_transport, } from './transports_ws_backend.js';
+/**
+ * Builds a typed broadcast API from a set of action specs.
+ *
+ * For each spec, adds a method keyed by `spec.method` that:
+ * - Validates `input` against the spec's Zod schema (logs and returns on failure)
+ * - Creates a JSON-RPC notification from the validated input
+ * - Broadcasts via the peer (filtered by `should_deliver` when supplied)
+ *
+ * Silently returns when no transport is ready (e.g. before any clients
+ * connect). Errors during send are logged but never thrown — broadcasts are
+ * fire-and-forget from the handler's perspective.
+ *
+ * ## Typed consumer surface
+ *
+ * Consumers declare an explicit interface and pin it via the type parameter:
+ *
+ * ```ts
+ * export interface BackendActionsApi {
+ *   filer_change: (input: ActionInputs['filer_change']) => Promise<void>;
+ *   workspace_changed: (input: ActionInputs['workspace_changed']) => Promise<void>;
+ * }
+ *
+ * const api = create_broadcast_api<BackendActionsApi>({
+ *   peer: backend.peer,
+ *   specs: [filer_change_action_spec, workspace_changed_action_spec],
+ * });
+ * ```
+ *
+ * The cast is unchecked — callers must keep the interface and the `specs`
+ * array in sync. Codegen (`action_collections.gen.ts`) is a natural fit
+ * if the consumer already generates per-method type maps.
+ */
+export const create_broadcast_api = (options) => {
+    const { peer, specs, should_deliver } = options;
+    const log = options.log === undefined ? new Logger('[broadcast]') : options.log;
+    const api = {};
+    for (const spec of specs) {
+        const { method } = spec;
+        api[method] = async (input) => {
+            const parsed = spec.input.safeParse(input);
+            if (!parsed.success) {
+                log?.error(`[${method}] input validation failed:`, parsed.error.issues);
+                return;
+            }
+            // Resolve the broadcast target deterministically — no fallback.
+            // Broadcast is 1→N over a specific primary transport; falling through
+            // to "any ready transport" would send to an unexpected audience.
+            // Silent skip when no ready transport (e.g. before any clients connect).
+            const transport_name = peer.default_send_options.transport_name;
+            const transport = transport_name
+                ? peer.transports.get_transport_by_name(transport_name)
+                : peer.transports.get_current_transport();
+            if (!transport?.is_ready())
+                return;
+            const notification = create_jsonrpc_notification(method, to_jsonrpc_params(parsed.data));
+            try {
+                if (should_deliver) {
+                    if (!is_filterable_broadcast_transport(transport)) {
+                        log?.error(`[${method}] should_deliver set but transport ${transport.transport_name} does not support per-connection filtering`);
+                        return;
+                    }
+                    transport.broadcast_filtered(notification, (identity) => should_deliver(identity, method, parsed.data));
+                    return;
+                }
+                const result = await transport.send(notification);
+                if (result !== null) {
+                    log?.error(`[${method}] failed to send notification:`, result.error);
+                }
+            }
+            catch (error) {
+                log?.error(`[${method}] unexpected error:`, error);
+            }
+        };
+    }
+    return api;
+};

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

@@ -5,7 +5,7 @@
  * @module
  */
 import type { WSContext } from 'hono/ws';
-import type { JsonrpcNotification, JsonrpcRequest, JsonrpcResponseOrError, JsonrpcErrorResponse } from '../http/jsonrpc.js';
+import type { JsonrpcMessageFromServerToClient, JsonrpcNotification, JsonrpcRequest, JsonrpcResponseOrError, JsonrpcErrorResponse } from '../http/jsonrpc.js';
 import { type Uuid } from '../uuid.js';
 import { type Transport } from './transports.js';
 /**
@@ -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. */
@@ -24,7 +24,21 @@ export interface ConnectionIdentity {
     /** `api_token.id` for bearer-authenticated connections, else null. */
     api_token_id: string | null;
 }
-export declare class BackendWebsocketTransport implements Transport {
+/**
+ * Structural capability for transports that can broadcast with a
+ * per-connection ACL predicate. Named separately from `Transport` so the
+ * broadcast API can feature-detect without importing a concrete class.
+ *
+ * `ConnectionIdentity` is the auth-gated identity shape used today. When a
+ * second implementation (e.g. SSE backend transport) lands with a
+ * different identity, consider parameterizing on `TIdentity`.
+ */
+export interface FilterableBroadcastTransport extends Transport {
+    broadcast_filtered: (message: JsonrpcMessageFromServerToClient, predicate: (identity: ConnectionIdentity) => boolean) => number;
+}
+/** Type guard for `FilterableBroadcastTransport`. */
+export declare const is_filterable_broadcast_transport: (transport: Transport) => transport is FilterableBroadcastTransport;
+export declare class BackendWebsocketTransport implements FilterableBroadcastTransport {
     #private;
     readonly transport_name: "backend_websocket_rpc";
     /**
@@ -34,7 +48,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;
     /**
@@ -66,6 +80,17 @@ export declare class BackendWebsocketTransport implements Transport {
     close_sockets_for_token(api_token_id: string): number;
     send(message: JsonrpcRequest): Promise<JsonrpcResponseOrError>;
     send(message: JsonrpcNotification): Promise<JsonrpcErrorResponse | null>;
+    /**
+     * Broadcast to connections whose identity satisfies a predicate.
+     *
+     * Used by the broadcast API when a consumer supplies a subscription ACL hook
+     * (e.g. tx's `tx_run_created` only reaches the account that owns the run).
+     * When no ACL is needed, callers should prefer `send(message)` / `#broadcast`
+     * to skip the per-connection predicate overhead.
+     *
+     * @returns the number of sockets the message was sent to
+     */
+    broadcast_filtered(message: JsonrpcMessageFromServerToClient, predicate: (identity: ConnectionIdentity) => boolean): number;
     is_ready(): boolean;
 }
 //# sourceMappingURL=transports_ws_backend.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"transports_ws_backend.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/transports_ws_backend.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,SAAS,CAAC;AAEvC,OAAO,KAAK,EAGX,mBAAmB,EACnB,cAAc,EACd,sBAAsB,EACtB,oBAAoB,EACpB,MAAM,oBAAoB,CAAC;AAO5B,OAAO,EAAc,KAAK,IAAI,EAAC,MAAM,YAAY,CAAC;AAClD,OAAO,EAA2B,KAAK,SAAS,EAAC,MAAM,iBAAiB,CAAC;AAIzE;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IAClC,sEAAsE;IACtE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,4CAA4C;IAC5C,UAAU,EAAE,IAAI,CAAC;IACjB,sEAAsE;IACtE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,qBAAa,yBAA0B,YAAW,SAAS;;IAC1D,QAAQ,CAAC,cAAc,EAAG,uBAAuB,CAAU;IAY3D;;;;;;;;OAQG;IACH,cAAc,CACb,EAAE,EAAE,SAAS,EACb,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,UAAU,EAAE,IAAI,EAChB,YAAY,GAAE,MAAM,GAAG,IAAW,GAChC,IAAI;IAQP;;;OAGG;IACH,iBAAiB,CAAC,EAAE,EAAE,SAAS,GAAG,IAAI;IA0BtC;;;;OAIG;IACH,yBAAyB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM;IAIrD;;;;OAIG;IACH,yBAAyB,CAAC,UAAU,EAAE,IAAI,GAAG,MAAM;IAInD;;;;;;;;OAQG;IACH,uBAAuB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM;IAsB/C,IAAI,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAC9D,IAAI,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IA4C9E,QAAQ,IAAI,OAAO;CAGnB"}
+{"version":3,"file":"transports_ws_backend.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/transports_ws_backend.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,SAAS,CAAC;AAEvC,OAAO,KAAK,EAEX,gCAAgC,EAChC,mBAAmB,EACnB,cAAc,EACd,sBAAsB,EACtB,oBAAoB,EACpB,MAAM,oBAAoB,CAAC;AAO5B,OAAO,EAAc,KAAK,IAAI,EAAC,MAAM,YAAY,CAAC;AAClD,OAAO,EAA2B,KAAK,SAAS,EAAC,MAAM,iBAAiB,CAAC;AAIzE;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IAClC,sEAAsE;IACtE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,4CAA4C;IAC5C,UAAU,EAAE,IAAI,CAAC;IACjB,sEAAsE;IACtE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,4BAA6B,SAAQ,SAAS;IAC9D,kBAAkB,EAAE,CACnB,OAAO,EAAE,gCAAgC,EACzC,SAAS,EAAE,CAAC,QAAQ,EAAE,kBAAkB,KAAK,OAAO,KAChD,MAAM,CAAC;CACZ;AAED,qDAAqD;AACrD,eAAO,MAAM,iCAAiC,GAC7C,WAAW,SAAS,KAClB,SAAS,IAAI,4BAEqE,CAAC;AAEtF,qBAAa,yBAA0B,YAAW,4BAA4B;;IAC7E,QAAQ,CAAC,cAAc,EAAG,uBAAuB,CAAU;IAY3D;;;;;;;;OAQG;IACH,cAAc,CACb,EAAE,EAAE,SAAS,EACb,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,UAAU,EAAE,IAAI,EAChB,YAAY,GAAE,MAAM,GAAG,IAAW,GAChC,IAAI;IAQP;;;OAGG;IACH,iBAAiB,CAAC,EAAE,EAAE,SAAS,GAAG,IAAI;IA0BtC;;;;OAIG;IACH,yBAAyB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM;IAIrD;;;;OAIG;IACH,yBAAyB,CAAC,UAAU,EAAE,IAAI,GAAG,MAAM;IAInD;;;;;;;;OAQG;IACH,uBAAuB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM;IAsB/C,IAAI,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAC9D,IAAI,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IA4C9E;;;;;;;;;OASG;IACH,kBAAkB,CACjB,OAAO,EAAE,gCAAgC,EACzC,SAAS,EAAE,CAAC,QAAQ,EAAE,kBAAkB,KAAK,OAAO,GAClD,MAAM;IAoBT,QAAQ,IAAI,OAAO;CAGnB"}

package/dist/actions/transports_ws_backend.js

@@ -8,6 +8,9 @@ import { jsonrpc_error_messages } from '../http/jsonrpc_errors.js';
 import { create_jsonrpc_error_response, to_jsonrpc_message_id, is_jsonrpc_request, } from '../http/jsonrpc_helpers.js';
 import { create_uuid } from '../uuid.js';
 import { WS_CLOSE_SESSION_REVOKED } from './transports.js';
+/** Type guard for `FilterableBroadcastTransport`. */
+export const is_filterable_broadcast_transport = (transport) => 'broadcast_filtered' in transport &&
+    typeof transport.broadcast_filtered === 'function';
 export class BackendWebsocketTransport {
     transport_name = 'backend_websocket_rpc';
     // Map connection IDs to WebSocket contexts
@@ -24,7 +27,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();
@@ -135,6 +138,35 @@ export class BackendWebsocketTransport {
         // TODO hack - remove if not ever needed, I assume this will need to be async so let's hold that assumption
         return Promise.resolve();
     }
+    /**
+     * Broadcast to connections whose identity satisfies a predicate.
+     *
+     * Used by the broadcast API when a consumer supplies a subscription ACL hook
+     * (e.g. tx's `tx_run_created` only reaches the account that owns the run).
+     * When no ACL is needed, callers should prefer `send(message)` / `#broadcast`
+     * to skip the per-connection predicate overhead.
+     *
+     * @returns the number of sockets the message was sent to
+     */
+    broadcast_filtered(message, predicate) {
+        const serialized = JSON.stringify(message);
+        let count = 0;
+        for (const [connection_id, identity] of this.#connection_identities) {
+            if (!predicate(identity))
+                continue;
+            const ws = this.#connections.get(connection_id);
+            if (!ws)
+                continue;
+            try {
+                ws.send(serialized);
+                count++;
+            }
+            catch (error) {
+                console.error('[backend websocket transport] Error broadcasting filtered to client:', error);
+            }
+        }
+        return count;
+    }
     is_ready() {
         return this.#connections.size > 0;
     }

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.17.0",
   "description": "fullstack app library",
   "glyph": "🗝",
   "logo": "logo.svg",