WebSocket auth guard — bridges audit events to BackendWebsocketTransport.
Why this exists. register_action_ws captures account_id and
credential_type at upgrade time and reuses them for every message.
perform_action's per-message authorization phase reloads role_grants
from the DB, but session and token VALIDITY are not re-queried — that
trade-off keeps chatty WS connections fast. The cost: nothing in the
dispatch path notices when a session is revoked or a token is rotated.
This guard is the enforcement mechanism — it listens on the audit
chain and closes affected sockets when revocation events fire, so
revocation actually takes effect on existing connections. Without it,
session_revoke / token_revoke are no-ops for open WS connections.
Mirror of realtime/sse_auth_guard.ts for the backend WebSocket
transport. Dispatches audit events to the right close_sockets_for_*
method so consumers do not re-implement the switch themselves.
For standard WS endpoints mounted via AppServerOptions.ws_endpoints,
create_app_server composes the guard automatically per
WsEndpointSpec.auth_guard. For custom wiring, append the handler
inside the consumer's audit_factory body (or via
audit.on_event_chain.push(...) post-assembly).
4 declarations
actions/transports_ws_auth_guard.ts view source
AuditEventHandler Audit-event callback shape — the function CreateAuditEmitterOptions.on_audit_event
accepts and that the helpers in this module return.
Exported so consumers composing multiple handlers (typically
create_ws_auth_guard + create_ws_logout_closer + their own
pre-existing on_audit_event) can annotate their composed callback
without reaching for Parameters<typeof create_ws_auth_guard>[0].
actions/transports_ws_auth_guard.ts view source
(transport: BackendWebsocketTransport, log: Logger): AuditEventHandler Create an audit event handler that closes WebSocket connections on auth changes.
Ignores outcome === 'failure' events — they carry attacker-controlled
identifiers (e.g. a session_revoke that the DB rejected still records
the submitted session_id), so reacting to them would let any authenticated
user close another user's socket by guessing a session hash or token id.
transportloglogger for disconnect events (info level on non-zero closures)
LoggerAuditEventHandler an on_audit_event callback suitable for create_audit_emitter's
on_audit_event slot, or for appending onto
audit.on_event_chain post-assembly. The returned callback mutates
transport (closing matching sockets via
close_sockets_for_session / _token / _account) on every relevant event.
actions/transports_ws_auth_guard.ts view source
(transport: BackendWebsocketTransport, log: Logger): AuditEventHandler Create an audit event handler that closes WebSocket connections on user-initiated logout.
Sibling helper to create_ws_auth_guard — kept separate because
ws_disconnect_event_types deliberately omits logout (admin-initiated
revocations use session_revoke, while logout is the user-initiated
case). Multiple consumers hand-rolled this same branch before extraction.
Compose with create_ws_auth_guard to handle both kinds of disconnect:
const ws_guard = create_ws_auth_guard(transport, log);
const ws_logout_closer = create_ws_logout_closer(transport, log);
const on_audit_event = (event: AuditLogEvent): void => {
ws_guard(event);
ws_logout_closer(event);
};Ignores outcome === 'failure' events — failed logouts carry
unauthenticated identifiers (no session to close anyway), and reacting
to them would let an unauthenticated probe close the targeted account's
sockets by submitting a logout for an arbitrary account_id.
transportloglogger for disconnect events (info level on non-zero closures)
LoggerAuditEventHandler an on_audit_event callback wireable alongside create_ws_auth_guard.
The returned callback mutates transport via close_sockets_for_account
on every successful logout event with a non-empty account_id.
actions/transports_ws_auth_guard.ts view source
ReadonlySet<string> Audit event types that trigger WebSocket socket closure.
- session_revoke — close only the socket tied to the revoked session hash.
- token_revoke — close only the socket(s) authenticated with the revoked api_token.id.
- session_revoke_all / token_revoke_all / password_change — close every socket
for the affected account (all credentials invalidated).
role_grant_revoke is intentionally omitted: the WS transport does not track
per-connection role requirements, so role-scoped disconnection would
require either closing all sockets (too aggressive) or new tracking
(out of scope). Consumers that need it compose their own callback.