/**
 * 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).
 *
 * @module
 */
import type { Logger } from '@fuzdev/fuz_util/log.js';
import type { AuditLogEvent } from '../auth/audit_log_schema.js';
import type { BackendWebsocketTransport } from './transports_ws_backend.js';
/**
 * 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]`.
 */
export type AuditEventHandler = (event: AuditLogEvent) => void;
/**
 * 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.
 */
export declare const ws_disconnect_event_types: ReadonlySet<string>;
/**
 * 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.
 *
 * @param log - logger for disconnect events (info level on non-zero closures)
 * @returns 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.
 */
export declare const create_ws_auth_guard: (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:
 *
 * ```ts
 * 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`.
 *
 * @param log - logger for disconnect events (info level on non-zero closures)
 * @returns 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`.
 */
export declare const create_ws_logout_closer: (transport: BackendWebsocketTransport, log: Logger) => AuditEventHandler;
//# sourceMappingURL=transports_ws_auth_guard.d.ts.map