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
consumers do not re-implement the switch themselves.
Consumers wire it as on_audit_event on their AppBackend (or compose
it with other callbacks via create_app_server's audit_log_sse path).
4 declarations
actions/transports_ws_auth_guard.ts view source
AuditEventHandler Audit-event callback shape — the function CreateAppBackendOptions.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 CreateAppBackendOptions.
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). Three consumers (tx, undying, zzz) 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).
permit_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.