@makaio/framework 1.0.0-dev-1779046984397

package/dist/node/transports/index.d.mts

@@ -0,0 +1,1752 @@
+import { PayloadFilter, TransportReceiveContext } from "@makaio/framework/core";
+import { BusBroadcastMessage, BusEventMessage, BusMessage, BusReceiveHandler, BusRequestMessage, BusTransport, BusTransportError } from "@makaio/framework/bus";
+
+//#region transports/ws/src/auth/interface.d.ts
+/**
+ * Transport authentication strategy.
+ *
+ * Implementations authenticate WebSocket connections and manage auth lifecycle.
+ * Auth messages are handled during a pre-connect phase before normal message flow begins.
+ */
+interface TransportAuth {
+  /**
+   * Authenticate a client connection.
+   *
+   * Called during the pre-connect phase after the WebSocket is open but before
+   * normal message handling begins. Auth messages flow through handleAuthMessage().
+   * @param send - Function to send auth messages to the server
+   * @throws Error if authentication fails
+   */
+  authenticateClient(send: (message: unknown) => void): Promise<void>;
+  /**
+   * Authenticate a server connection with a specific client socket.
+   *
+   * Called when a new client connects to the server, during the pre-connect phase.
+   * @param socket - The client WebSocket connection to authenticate
+   * @param send - Function to send auth messages to the client
+   * @throws Error if authentication fails
+   */
+  authenticateServer(socket: WebSocketLike, send: (message: unknown) => void): Promise<void>;
+  /**
+   * Handle incoming message during authentication phase.
+   *
+   * This is called by the transport's message handler to route auth messages
+   * to the auth implementation during the pre-connect phase.
+   * @param message - Parsed message object
+   * @param socket - Optional socket identifier for server-side multi-client scenarios
+   * @returns true if the message was an auth message and was handled, false otherwise
+   */
+  handleAuthMessage(message: unknown, socket?: WebSocketLike): boolean;
+  /**
+   * Return trusted receive context for a socket after authentication.
+   *
+   * Server transports call this when routing inbound bus messages from the
+   * socket. Undefined means the auth strategy has no context to expose.
+   * @param socket - Optional socket for server-side multi-client transports
+   * @returns Trusted local receive context, or undefined
+   */
+  getReceiveContext?(socket?: WebSocketLike): TransportReceiveContext | undefined;
+  /**
+   * Clean up authentication resources for a specific socket.
+   *
+   * Called when a socket disconnects to immediately release per-socket resources like:
+   * - Pending authentication state
+   * - Authentication timers for that socket
+   * - Socket-specific auth data
+   *
+   * This prevents memory leaks when sockets disconnect during authentication.
+   * @param socket - The socket to clean up auth resources for
+   */
+  cleanupSocket(socket: WebSocketLike): void;
+  /**
+   * Clean up authentication resources.
+   *
+   * Called during disconnect() to release resources like:
+   * - Authentication timers
+   * - Token refresh intervals
+   * - Event listeners
+   * - Cached credentials
+   */
+  cleanup(): void;
+}
+//#endregion
+//#region transports/ws/src/auth/hmac-auth.d.ts
+/**
+ * HMAC authentication configuration.
+ */
+interface HmacAuthOptions {
+  /**
+   * Shared secret for HMAC computation.
+   *
+   * IMPORTANT: This should be a strong, randomly-generated secret.
+   * Both client and server must use the same secret.
+   */
+  secret: string;
+  /**
+   * HMAC algorithm to use.
+   * @defaultValue 'sha256'
+   */
+  algorithm?: string;
+  /**
+   * Timeout for authentication challenge in milliseconds.
+   *
+   * If client doesn't respond within this time, authentication fails.
+   * @defaultValue 5000
+   */
+  challengeTimeout?: number;
+}
+/**
+ * HMAC challenge/response authentication implementation.
+ * @example
+ * ```typescript
+ * const auth = new HmacAuth({
+ *   secret: process.env.WEBSOCKET_SECRET,
+ *   algorithm: 'sha256',
+ *   challengeTimeout: 5000,
+ * });
+ *
+ * const transport = createClientTransport({
+ *   websocket: ws,
+ *   auth,
+ * });
+ * ```
+ */
+declare class HmacAuth implements TransportAuth {
+  private readonly secret;
+  private readonly algorithm;
+  private readonly challengeTimeout;
+  private pendingChallenge?;
+  private pendingResult?;
+  private queuedChallengeNonce;
+  private queuedResult;
+  private clientAuthComplete;
+  private serverPendingResponses;
+  constructor(options: HmacAuthOptions);
+  /**
+   * Server-side authentication flow.
+   *
+   * 1. Generate random nonce
+   * 2. Send auth-challenge to client
+   * 3. Wait for auth-response with signature (via handleAuthMessage)
+   * 4. Verify signature matches HMAC(secret, nonce)
+   * 5. Send auth-result
+   * @param socket - The client WebSocket connection to authenticate
+   * @param send - Function to send auth messages to the client
+   * @throws Error if authentication fails
+   */
+  authenticateServer(socket: WebSocketLike, send: (message: unknown) => void): Promise<void>;
+  /**
+   * Client-side authentication flow.
+   *
+   * 1. Wait for auth-challenge from server (via handleAuthMessage)
+   * 2. Compute signature = HMAC(secret, nonce)
+   * 3. Send auth-response with signature
+   * 4. Wait for auth-result (via handleAuthMessage)
+   * 5. Throw if authentication failed
+   * @param send - Function to send auth messages to the server
+   * @throws Error if authentication fails
+   */
+  authenticateClient(send: (message: unknown) => void): Promise<void>;
+  /**
+   * Handle incoming message during authentication phase.
+   *
+   * Routes auth messages to the appropriate pending operation.
+   * ALWAYS consumes auth message types to prevent them from leaking to regular handlers.
+   * @param message - Parsed message object
+   * @param socket - Optional socket identifier for server-side multi-client scenarios
+   * @returns true if the message was an auth message (consumed regardless of pending state)
+   */
+  handleAuthMessage(message: unknown, socket?: WebSocketLike): boolean;
+  /**
+   * Wait for auth-challenge message from server.
+   *
+   * Message will be delivered via handleAuthMessage().
+   * @returns The nonce from the challenge
+   * @throws Error if timeout
+   */
+  private waitForAuthChallenge;
+  /**
+   * Wait for auth-response message from client.
+   *
+   * Message will be delivered via handleAuthMessage().
+   * @param socket - The client socket to track
+   * @returns The signature from the response
+   * @throws Error if timeout
+   */
+  private waitForAuthResponse;
+  /**
+   * Wait for auth-result message from server.
+   *
+   * Message will be delivered via handleAuthMessage().
+   * @returns The authentication result
+   * @throws Error if timeout
+   */
+  private waitForAuthResult;
+  /**
+   * Compute HMAC signature for a nonce using Web Crypto API.
+   * @param nonce - The nonce to sign
+   * @returns Promise resolving to hex-encoded HMAC signature
+   */
+  private computeHmac;
+  /**
+   * Send auth result messages without masking the original auth error.
+   *
+   * Disconnect races can make `send` throw after auth already failed; callers
+   * should still observe the original failure reason.
+   * @param send - Transport send function
+   * @param message - Auth result message payload
+   */
+  private sendAuthResultBestEffort;
+  /**
+   * Clean up authentication resources for a specific socket.
+   *
+   * Called when a socket disconnects to immediately release resources
+   * and prevent memory leaks during the authentication timeout window.
+   * @param socket - The socket to clean up
+   */
+  cleanupSocket(socket: WebSocketLike): void;
+  /**
+   * Clean up authentication resources.
+   *
+   * Clears any pending authentication operations and their timeouts.
+   */
+  cleanup(): void;
+}
+//#endregion
+//#region transports/ws/src/auth/e2e-auth.d.ts
+/**
+ * E2E authentication configuration.
+ */
+interface E2EAuthOptions {
+  /** Our static identity keypair for signing (ECDSA P-256) */
+  signingKeyPair: CryptoKeyPair;
+  /** Our identifier (deviceId for browser, machineId for server) */
+  identityId: string;
+  /** Expected peer identifier (required for browser connections; machineId from QR payload) */
+  peerId?: string;
+  /** Lookup peer's signing public key by their identity */
+  getPeerSigningKey: (peerId: string) => Promise<CryptoKey | null>;
+  /** Auth timeout in milliseconds. @defaultValue 10000 */
+  timeout?: number;
+}
+/**
+ * E2E authenticated encryption implementation.
+ */
+declare class E2EAuth implements TransportAuth {
+  private readonly signingKeyPair;
+  private readonly identityId;
+  private readonly peerId?;
+  private readonly getPeerSigningKey;
+  private readonly timeout;
+  private pendingKeyExchange?;
+  private pendingResult?;
+  private clientSession?;
+  private clientEphemeralKeyPair?;
+  private serverPendingKeyExchange;
+  private serverSessions;
+  private serverEphemeralKeyPairs;
+  constructor(options: E2EAuthOptions);
+  /**
+   * Client-side authentication flow.
+   *
+   * If an error occurs after pending promises are created, they are cleaned up
+   * before rethrowing to prevent unhandled rejections from lingering timeouts.
+   * @param send - Function to send auth messages to the server
+   */
+  authenticateClient(send: (message: unknown) => void): Promise<void>;
+  /**
+   * Server-side authentication flow.
+   * @param socket - The client WebSocket connection to authenticate
+   * @param send - Function to send auth messages to the client
+   */
+  authenticateServer(socket: WebSocketLike, send: (message: unknown) => void): Promise<void>;
+  /**
+   * Handle incoming message during authentication phase.
+   * @param message - Parsed message object
+   * @param socket - Optional socket identifier for server-side
+   * @returns true if the message was an E2E auth message
+   */
+  handleAuthMessage(message: unknown, socket?: WebSocketLike): boolean;
+  private waitForKeyExchangeResponse;
+  private waitForAuthResult;
+  private waitForClientKeyExchange;
+  /**
+   * Get the derived AES-256-GCM session key for encrypting/decrypting payloads.
+   * @param socket - Optional socket (server-side only)
+   * @returns Session key if authenticated, null otherwise
+   */
+  getSessionKey(socket?: WebSocketLike): CryptoKey | null;
+  /**
+   * Get the peer's identity ID authenticated during handshake.
+   * @param socket - Optional socket (server-side only)
+   * @returns Peer ID if authenticated, null otherwise
+   */
+  getPeerId(socket?: WebSocketLike): string | null;
+  /**
+   * Clean up authentication resources for a specific socket.
+   * @param socket - The socket to clean up
+   */
+  cleanupSocket(socket: WebSocketLike): void;
+  /**
+   * Clean up authentication resources.
+   */
+  cleanup(): void;
+}
+//#endregion
+//#region transports/ws/src/auth/e2e-relay-auth.d.ts
+type RelayAuthMode = 'initiator' | 'responder';
+/**
+ * Configuration for relay-mode E2E authentication.
+ */
+interface E2ERelayAuthOptions {
+  /** Static ECDSA signing keypair */
+  signingKeyPair: CryptoKeyPair;
+  /** Local identity ID */
+  identityId: string;
+  /** Lookup peer signing key by identity */
+  getPeerSigningKey: (peerId: string) => Promise<CryptoKey | null>;
+  /** Auth timeout in milliseconds. @defaultValue 10000 */
+  timeout?: number;
+  /**
+   * Relay handshake mode.
+   * - initiator: sends exchange immediately (browser)
+   * - responder: waits for peer exchange before responding (machine)
+   * @defaultValue "initiator"
+   */
+  mode?: RelayAuthMode;
+  /**
+   * Whether authenticateClient should block until handshake completes.
+   * Use false for machine-side relay connections to avoid startup stalls
+   * when no browser is connected.
+   * @defaultValue true
+   */
+  blocking?: boolean;
+}
+/**
+ * Relay-mode E2E authentication implementation.
+ */
+declare class E2ERelayAuth implements TransportAuth {
+  private readonly signingKeyPair;
+  private readonly identityId;
+  private readonly getPeerSigningKey;
+  private readonly timeout;
+  private readonly mode;
+  private readonly blocking;
+  private pendingPeer?;
+  private sessionKey?;
+  private peerId?;
+  private localEphemeral?;
+  private localExchangeMessage?;
+  private sentLocalExchange;
+  private earlyPeer?;
+  private sendAuthMessage?;
+  /**
+   * Monotonically increasing counter to invalidate stale async
+   * `processPeerExchange` tasks from previous sessions.
+   */
+  private authGeneration;
+  /**
+   * True while a non-blocking `processPeerExchange` is in flight.
+   * Prevents duplicate dispatches when the initiator sends its exchange
+   * twice (initial + confirmation after deriving its own key).
+   */
+  private processingExchange;
+  constructor(options: E2ERelayAuthOptions);
+  /**
+   * Client-side authentication flow (relay mode).
+   *
+   * Resets all derived session state before starting a fresh handshake so that
+   * this instance can be reused across WebSocketClientTransport reconnections.
+   * Constructor-time config (`signingKeyPair`, `identityId`, `getPeerSigningKey`,
+   * `mode`, `blocking`) is intentionally preserved by `cleanup()`.
+   * @param send - Function to send auth messages to peer via relay
+   */
+  authenticateClient(send: (message: unknown) => void): Promise<void>;
+  /**
+   * Server-side auth is not used in relay mode.
+   *
+   * No `cleanup()` call is needed here: this method throws unconditionally
+   * before setting any session state, so there is nothing to reset.
+   * @param _socket - WebSocket connection (unused)
+   * @param _send - Auth send function (unused)
+   */
+  authenticateServer(_socket: WebSocketLike, _send: (message: unknown) => void): Promise<void>;
+  /**
+   * Handle incoming message during authentication phase.
+   * @param message - Parsed message
+   * @returns true if handled
+   */
+  handleAuthMessage(message: unknown): boolean;
+  cleanupSocket(_socket: WebSocketLike): void;
+  cleanup(): void;
+  /**
+   * Fire-and-forget `processPeerExchange` with `processingExchange` tracking
+   * and generation-guarded cleanup.
+   * @param peer - Peer key-exchange message
+   * @param generation - Auth generation at dispatch time
+   */
+  private dispatchPeerExchange;
+  /**
+   * Get derived session key after handshake.
+   * @returns Session key or null
+   */
+  getSessionKey(): CryptoKey | null;
+  /**
+   * Get peer identity ID after handshake.
+   * @returns Peer identity ID or null
+   */
+  getPeerId(): string | null;
+  private waitForPeerExchange;
+  private ensureLocalExchangeMessage;
+  private sendLocalExchange;
+  /**
+   * Retry the latest queued peer exchange after an in-flight attempt settles.
+   *
+   * Non-blocking relay auth can receive a newer peer exchange while the current
+   * one is still deriving keys. WebSocketClientTransport reconnects are already
+   * generation-scoped; this helper only re-dispatches messages queued within the
+   * same live auth session so newer exchanges are not stranded behind a failure.
+   * @param generation - Auth generation that just finished processing
+   */
+  private retryQueuedPeerExchange;
+  /**
+   * Verify the peer's exchange, derive the shared session key, and store it.
+   *
+   * The `generation` parameter prevents stale async tasks from a previous
+   * session from overwriting the current session's keys. Each call to
+   * `authenticateClient` increments `authGeneration`; if a task's generation
+   * no longer matches, it silently aborts before writing any state.
+   * @param peer - Peer key-exchange message
+   * @param generation - Auth generation at dispatch time
+   */
+  private processPeerExchange;
+}
+//#endregion
+//#region transports/ws/src/auth/dispatching-auth.d.ts
+/**
+ * Options for creating a dispatching auth strategy.
+ */
+interface DispatchingAuthOptions {
+  /** Auth strategy for HMAC challenge/response clients. */
+  hmac?: TransportAuth;
+  /** Auth strategy for E2E key-exchange clients. */
+  e2e?: TransportAuth;
+}
+/**
+ * Auth dispatcher that routes to the appropriate strategy based on the first
+ * auth message type received from the client.
+ *
+ * Enables a single bus server port to accept both HMAC-authenticated
+ * connections (e.g., Electron) and E2E-authenticated connections (e.g., mobile).
+ *
+ * ### How it works
+ *
+ * HMAC auth is server-initiated (the server sends a challenge before any client
+ * message arrives). E2E auth is client-initiated (the client sends `e2e-key-exchange`
+ * as its first message). This creates a dispatch ordering problem: the dispatcher
+ * cannot wait for the client's first message before deciding which strategy to use,
+ * because HMAC requires the server to act first.
+ *
+ * The solution:
+ *
+ * **Single strategy**: If only one strategy is configured, `authenticateServer`
+ * delegates immediately — no dispatch needed, no ordering constraint.
+ *
+ * **Both strategies**: `authenticateServer` calls `hmac.authenticateServer()`
+ * eagerly so HMAC can send its challenge right away. It then waits for the
+ * client's first message to determine the winner:
+ * - `auth-response` → HMAC is already running; forward and let it complete.
+ * - `e2e-key-exchange` → E2E wins; cancel HMAC (its pending promise is
+ *   rejected via `cleanupSocket`), start `e2e.authenticateServer()`, and
+ *   forward the message to E2E.
+ *
+ * A cancellation flag on the `send` wrapper given to HMAC prevents HMAC's
+ * error path from sending spurious `auth-result: false` to E2E clients.
+ * @example
+ * ```typescript
+ * const auth = new DispatchingAuth({
+ *   hmac: new HmacAuth({ secret: process.env.BUS_SECRET! }),
+ *   e2e: new E2EAuth({ ... }),
+ * });
+ *
+ * const server = createBusServer({ websocket: wss, auth });
+ * ```
+ */
+declare class DispatchingAuth implements TransportAuth {
+  private readonly hmac;
+  private e2e;
+  /** Maps each socket to its resolved auth strategy after the first message. */
+  private readonly socketStrategy;
+  /**
+   * Maps each socket to its pending server-auth state while we wait for the
+   * first client message to determine the appropriate strategy.
+   */
+  private readonly pendingServerAuth;
+  /**
+   * Per-socket cancellation flags for eagerly-started HMAC auth.
+   *
+   * When E2E wins the dispatch race, the flag is set to `true` so the `send`
+   * wrapper passed to HMAC becomes a no-op, preventing spurious `auth-result`
+   * failure messages from reaching the E2E client.
+   */
+  private readonly hmacCancelled;
+  /**
+   * @param options - Auth strategies to dispatch between
+   */
+  constructor(options: DispatchingAuthOptions);
+  /**
+   * Set or replace the E2E authentication strategy after construction.
+   *
+   * Used in transport-first boot sequences where the bus server starts with
+   * HMAC-only auth and E2E auth is wired in later, once machine identity
+   * (e.g. LAN keypair) becomes available. Only affects new connection
+   * handshakes — in-flight authentications are unaffected.
+   * @param e2e - The E2E auth strategy to register
+   */
+  setE2EAuth(e2e: TransportAuth): void;
+  /**
+   * Authenticate a client connection.
+   *
+   * The dispatcher is a server-side concern; clients always know which strategy
+   * they are using. This method delegates to the first configured strategy as a
+   * fallback, or throws if no strategy is configured.
+   * @param send - Function to send auth messages to the server
+   * @returns Promise that resolves when client authentication is complete
+   * @throws Error if no auth strategy is configured
+   */
+  authenticateClient(send: (message: unknown) => void): Promise<void>;
+  /**
+   * Authenticate a server connection with a specific client socket.
+   *
+   * **Single strategy**: delegates immediately to the configured strategy.
+   *
+   * **Both strategies**: starts HMAC eagerly (so it can send its challenge),
+   * then parks a pending promise that resolves or rejects once
+   * `handleAuthMessage` receives the first client message and determines the
+   * winner. If E2E wins, HMAC is cancelled via `cleanupSocket`.
+   * @param socket - The client WebSocket connection to authenticate
+   * @param send - Function to send auth messages to the client
+   * @returns Promise that resolves when server authentication is complete
+   * @throws Error if no strategy matches the client's auth type, or if the
+   *   delegated strategy rejects authentication
+   */
+  authenticateServer(socket: WebSocketLike, send: (message: unknown) => void): Promise<void>;
+  /**
+   * Handle incoming message during authentication phase.
+   *
+   * On the first message for an unknown socket, peeks at `message.type` to
+   * select a strategy, then delegates `authenticateServer` and this message
+   * to the selected strategy. Subsequent messages for the same socket are
+   * forwarded directly.
+   * @param message - Parsed message object
+   * @param socket - Optional socket identifier for server-side multi-client scenarios
+   * @returns true if the message was handled as an auth message, false otherwise
+   */
+  handleAuthMessage(message: unknown, socket?: WebSocketLike): boolean;
+  /**
+   * Clean up authentication resources for a specific socket.
+   *
+   * Delegates to the resolved strategy if one was selected, then removes
+   * all per-socket state held by the dispatcher itself.
+   * @param socket - The socket to clean up auth resources for
+   */
+  cleanupSocket(socket: WebSocketLike): void;
+  /**
+   * Clean up all authentication resources.
+   *
+   * Calls `cleanup` on both configured strategies (if present) and clears
+   * all internal maps.
+   */
+  cleanup(): void;
+  /**
+   * Peek at the `type` field of an unknown message without a full parse.
+   * @param message - Raw parsed message object
+   * @returns The string value of `message.type`, or `undefined`
+   */
+  private peekType;
+  /**
+   * Returns the single configured strategy, or `undefined` if both or neither
+   * are configured.
+   *
+   * Used by `authenticateServer` to short-circuit dispatch when only one
+   * strategy is present.
+   * @returns The sole configured strategy, or `undefined`
+   */
+  private resolveSingleStrategy;
+  /**
+   * Select the appropriate strategy based on the first auth message type.
+   *
+   * HMAC clients send `auth-response` as their first message (the server
+   * already sent `auth-challenge` eagerly). E2E clients send `e2e-key-exchange`.
+   * @param message - The first auth message received from the client
+   * @returns The matching strategy, or `undefined` if none matches
+   */
+  private resolveStrategy;
+  /**
+   * Cancel the eagerly-started HMAC authentication for a socket.
+   *
+   * Sets the cancellation flag (preventing spurious `send` calls from HMAC's
+   * error path) and calls `hmac.cleanupSocket` to reject HMAC's pending
+   * response promise and release its resources.
+   * @param socket - The socket whose HMAC auth should be cancelled
+   */
+  private cancelHmac;
+}
+//#endregion
+//#region transports/ws/src/types.d.ts
+/**
+ * Transport-level close event shape.
+ *
+ * Browser `CloseEvent` is not available in every runtime that implements this
+ * duck-typed WebSocket contract (for example Bun server handlers running under
+ * Node-based test runners), but transport consumers only rely on the close
+ * code and reason.
+ */
+interface WebSocketCloseEvent extends Event {
+  /**
+   * WebSocket close status code.
+   */
+  readonly code: number;
+  /**
+   * Human-readable close reason.
+   */
+  readonly reason: string;
+}
+/**
+ * Create a transport-level close event without depending on the browser-only
+ * `CloseEvent` global.
+ * @param code - WebSocket close code.
+ * @param reason - Human-readable close reason.
+ * @returns Portable close event for {@link WebSocketLike} listeners.
+ */
+declare function createWebSocketCloseEvent(code?: number, reason?: string): WebSocketCloseEvent;
+/**
+ * Client-side WebSocket interface.
+ *
+ * Compatible with browser WebSocket API and ws.WebSocket.
+ */
+interface WebSocketLike {
+  /**
+   * Send data over the WebSocket connection.
+   * @param data - Data to send (string, binary buffer, or Blob)
+   */
+  send(data: string | BufferSource | Blob): void;
+  /**
+   * Close the WebSocket connection.
+   * @param code - Close code (optional)
+   * @param reason - Close reason (optional)
+   */
+  close(code?: number, reason?: string): void;
+  /**
+   * Add an event listener.
+   * @param event - Event type
+   * @param listener - Event listener function
+   */
+  addEventListener(event: 'message', listener: (event: MessageEvent) => void): void;
+  addEventListener(event: 'error', listener: (event: Event) => void): void;
+  addEventListener(event: 'close', listener: (event: WebSocketCloseEvent) => void): void;
+  addEventListener(event: 'open', listener: (event: Event) => void): void;
+  /**
+   * Remove an event listener.
+   * @param event - Event type
+   * @param listener - Event listener function
+   */
+  removeEventListener(event: 'message', listener: (event: MessageEvent) => void): void;
+  removeEventListener(event: 'error', listener: (event: Event) => void): void;
+  removeEventListener(event: 'close', listener: (event: WebSocketCloseEvent) => void): void;
+  removeEventListener(event: 'open', listener: (event: Event) => void): void;
+  /**
+   * Current connection state.
+   */
+  readonly readyState: number;
+}
+/**
+ * Server-side WebSocketServer interface.
+ *
+ * Compatible with ws.WebSocketServer.
+ */
+interface WebSocketServerLike {
+  /**
+   * Register a connection handler.
+   * @param event - Event type
+   * @param listener - Event listener function
+   */
+  on(event: 'connection', listener: (socket: WebSocketLike) => void): void;
+  on(event: 'error', listener: (error: Error) => void): void;
+  on(event: 'close', listener: () => void): void;
+  /**
+   * Remove an event listener.
+   * @param event - Event type
+   * @param listener - Event listener function
+   */
+  off(event: 'connection', listener: (socket: WebSocketLike) => void): void;
+  off(event: 'error', listener: (error: Error) => void): void;
+  off(event: 'close', listener: () => void): void;
+  /**
+   * Close the WebSocket server.
+   * @param callback - Callback when server is closed
+   */
+  close(callback?: (err?: Error) => void): void;
+}
+/**
+ * Shared WebSocket transport configuration.
+ */
+interface WebSocketTransportOptionsBase {
+  /**
+   * Optional authentication strategy.
+   */
+  auth?: TransportAuth;
+  /**
+   * Enable debug logging.
+   */
+  debug?: boolean;
+}
+/**
+ * Client-mode WebSocket transport configuration.
+ */
+interface WebSocketClientTransportOptions$1 extends WebSocketTransportOptionsBase {
+  /**
+   * Transport mode: client.
+   */
+  mode: 'client';
+  /**
+   * WebSocket instance for client mode.
+   */
+  websocket: WebSocketLike;
+}
+/**
+ * Server-mode WebSocket transport configuration.
+ */
+interface WebSocketServerTransportOptions extends WebSocketTransportOptionsBase {
+  /**
+   * Transport mode: server.
+   */
+  mode: 'server';
+  /**
+   * WebSocketServer instance for server mode.
+   */
+  websocket: WebSocketServerLike;
+}
+/**
+ * WebSocket transport configuration (discriminated union).
+ */
+type WebSocketTransportOptions = WebSocketClientTransportOptions$1 | WebSocketServerTransportOptions;
+/**
+ * Codec for encoding and decoding bus messages on the wire.
+ *
+ * Implement this interface to add transport-level encryption, custom framing,
+ * or any other wire-format transformation. Both client transports
+ * (`createClientTransport` and `WebSocketClientTransport`) accept an optional
+ * codec and fall back to a plain JSON codec when none is provided.
+ */
+interface ClientTransportCodec {
+  /**
+   * Encode a bus message for transmission.
+   * @param message - Bus message to encode
+   * @returns Encoded payload to send over the socket
+   */
+  encode(message: BusMessage): Promise<string | BufferSource>;
+  /**
+   * Decode a parsed wire message into a bus message.
+   * @param message - Parsed message object
+   * @returns Bus message
+   */
+  decode(message: unknown): Promise<BusMessage>;
+}
+//#endregion
+//#region transports/ws/src/ws-client-reconnect.d.ts
+/**
+ * Reconnection utilities for `WebSocketClientTransport`.
+ *
+ * Pure helpers for exponential-backoff timing used by the reconnect loop
+ * inside `WebSocketClientTransport`. Kept separate so the main transport
+ * module stays focused on the `BusTransport` contract.
+ */
+/**
+ * Reconnection configuration for `WebSocketClientTransport`.
+ *
+ * Controls exponential-backoff timing. Pass `false` to the parent options to
+ * disable automatic reconnection entirely.
+ */
+interface WebSocketClientTransportReconnectOptions {
+  /**
+   * Base delay in milliseconds for the first reconnect attempt.
+   * The effective minimum is 100 ms regardless of the value specified.
+   * @defaultValue 1000
+   */
+  baseMs?: number;
+  /**
+   * Maximum delay cap in milliseconds.
+   * @defaultValue 10000
+   */
+  maxMs?: number;
+}
+//#endregion
+//#region transports/ws/src/ws-client-options.d.ts
+/**
+ * Configuration options for `WebSocketClientTransport`.
+ */
+interface WebSocketClientTransportOptions {
+  /**
+   * WebSocket server URL.
+   *
+   * The transport creates and recreates the WebSocket internally — callers
+   * never pass a `WebSocket` instance directly.
+   * @example 'ws://localhost:8080/bus'
+   */
+  url: string;
+  /**
+   * Transport identity used for registration in the bus transport registry.
+   * @defaultValue 'ws-client'
+   */
+  name?: string;
+  /**
+   * Authentication strategy for HMAC or E2E handshakes.
+   */
+  auth?: TransportAuth;
+  /**
+   * Wire codec for encryption or custom framing.
+   *
+   * Defaults to a plain JSON codec with no transformation.
+   */
+  codec?: ClientTransportCodec;
+  /**
+   * Optional async transform applied to every incoming message after codec
+   * decoding, before correlation tracking and handler dispatch.
+   *
+   * Use this to inject E2E decryption or message normalization.
+   * @param message - Decoded bus message from the wire
+   * @returns Transformed message (may be the same reference if unchanged)
+   */
+  messageTransform?: (message: BusMessage) => Promise<BusMessage>;
+  /**
+   * Automatic reconnection configuration. Defaults to exponential backoff
+   * starting at 1 s and capped at 10 s. Pass `false` to disable automatic
+   * reconnection.
+   *
+   * Note: this configures the reconnection *policy* and is distinct from the
+   * imperative {@link WebSocketClientTransport.reconnect} method, which triggers
+   * an immediate reconnect attempt.
+   * @defaultValue `{ baseMs: 1000, maxMs: 10000 }`
+   */
+  autoReconnect?: WebSocketClientTransportReconnectOptions | false;
+  /**
+   * WebSocket constructor factory.
+   *
+   * Defaults to the `ws` package's `WebSocket` loaded via dynamic import.
+   * Override this to provide a browser `WebSocket`, a mock for testing, or any
+   * other `WebSocketLike` implementation. The factory may be async so that
+   * callers can defer module loading until the first connection attempt.
+   * @param url - WebSocket server URL
+   * @returns A `WebSocketLike` instance (not yet opened), or a Promise thereof
+   */
+  createWebSocket?: (url: string) => WebSocketLike | Promise<WebSocketLike>;
+  /**
+   * Called each time the transport establishes a connection (initial or reconnect).
+   *
+   * Fired after the socket is open, authentication is complete, and subscriptions
+   * have been replayed. Use this to trigger application-level reconnect recovery.
+   */
+  onConnected?: () => void;
+  /**
+   * Called each time the transport loses its connection.
+   *
+   * Fired when the socket closes unexpectedly (not on a clean `disconnect()` call).
+   * Use this to activate application-level disconnect recovery logic.
+   */
+  onDisconnected?: () => void;
+  /**
+   * Enable verbose debug logging to the console.
+   * @defaultValue false
+   */
+  debug?: boolean;
+}
+//#endregion
+//#region transports/ws/src/ws-client-transport.d.ts
+/**
+ * URL-based WebSocket client transport with built-in reconnection.
+ *
+ * Takes a URL and owns the full connection lifecycle — socket creation,
+ * authentication, subscription replay, and exponential-backoff reconnection.
+ * Callers never create or pass a `WebSocket` directly.
+ * @example
+ * ```typescript
+ * const transport = new WebSocketClientTransport({ url: 'ws://localhost:8080/bus' });
+ * await transport.connect();
+ * await transport.subscribe('adapter.*');
+ * ```
+ */
+declare class WebSocketClientTransport implements BusTransport {
+  /** Transport identity for the bus registry. */
+  readonly name: string;
+  private readonly url;
+  private readonly auth;
+  private readonly codec;
+  private readonly messageTransform;
+  private readonly autoReconnectConfig;
+  private readonly wsFactory;
+  private readonly debug;
+  private readonly onConnectedCallback;
+  private readonly onDisconnectedCallback;
+  private socket;
+  private authComplete;
+  private readonly correlations;
+  private readonly handlers;
+  private readonly localSubscriptions;
+  private messageListener;
+  private closeListener;
+  /** AbortController for the active reconnect loop; `null` when not connected. */
+  private reconnectAbort;
+  /** AbortController for the current backoff sleep; aborting wakes the sleep early. */
+  private backoffWakeAbort;
+  /**
+   * Whether `runReconnectLoop` is currently executing.
+   * Used by `reconnect()` to distinguish mid-attempt (no-op) from loop-never-started (retry).
+   */
+  private reconnectLoopRunning;
+  /** Resolver for the current ready promise; `null` once resolved. */
+  private readyResolve;
+  /** Resolves when the subscribe-sync-complete handshake is received; reset on each reconnect. */
+  ready: Promise<void>;
+  /** Set by the transport registry to track each session's ready promise for dispatch gating. */
+  onNewReadySession: ((promise: Promise<void>) => void) | undefined;
+  /** Set by the transport registry; called after auth + subscription replay on each connect. */
+  onConnected: (() => void) | undefined;
+  /** Set by the transport registry; called when the connection drops unexpectedly. */
+  onDisconnected: (() => void) | undefined;
+  /**
+   * Create a new `WebSocketClientTransport`.
+   * @param options - Transport configuration
+   */
+  constructor(options: WebSocketClientTransportOptions);
+  /**
+   * Connect to the bus server, authenticate, replay subscriptions, and start
+   * the reconnect loop if enabled.
+   * @returns Promise that resolves when the initial connection is established
+   */
+  connect(): Promise<void>;
+  /**
+   * Disconnect and clean up: stops the reconnect loop, closes the socket,
+   * and releases auth, correlation, and handler state.
+   * @returns Promise that resolves when the transport is fully disconnected
+   */
+  disconnect(): Promise<void>;
+  /**
+   * Send a message over the WebSocket connection.
+   * @param message - Bus message to send
+   * @param timeout - Correlation timeout in milliseconds; `0` means no automatic timeout
+   * @returns Promise resolving to response (requests), results array (broadcasts), or boolean (events)
+   */
+  send<TMessage extends BusMessage>(message: TMessage, timeout?: number): Promise<TMessage extends BusRequestMessage ? unknown : TMessage extends BusBroadcastMessage ? Array<{
+    nodeId: string;
+    payload: unknown;
+  }> : boolean>;
+  /**
+   * Register a handler for all inbound messages.
+   * @param handler - Invoked for each decoded inbound message
+   * @returns Unsubscribe function
+   */
+  onReceive(handler: (message: BusMessage) => Promise<void>): () => void;
+  /**
+   * Subscribe to a subject on the server with an optional payload filter.
+   *
+   * Buffers the subscription for reconnect replay. Sends immediately when the
+   * socket is open. See {@link addSubscription} for full semantics.
+   * @param subject - Subject pattern (supports wildcards like `'adapter.*'`)
+   * @param filter - Optional payload filter for server-side smart-routing
+   * @param priorities - Handler priorities registered for this subject
+   * @returns Promise that resolves when buffering (and optional send) is complete
+   */
+  subscribe(subject: string, filter?: PayloadFilter, priorities?: number[]): Promise<void>;
+  /**
+   * Unsubscribe from a subject on the server.
+   *
+   * Removes the subject from the replay buffer. Sends immediately when the
+   * socket is open. See {@link removeSubscription} for full semantics.
+   * @param subject - Subject to unsubscribe from
+   * @returns Promise that resolves when the removal (and optional send) is complete
+   */
+  unsubscribe(subject: string): Promise<void>;
+  /** @returns Set of subject patterns currently subscribed. */
+  getSubscriptions(): Set<string>;
+  /**
+   * Cancel a pending correlated request.
+   * @param correlationId - Correlation ID to cancel
+   * @param error - Optional cancellation error
+   */
+  cancelRequest(correlationId: string, error?: Error): void;
+  /**
+   * Returns `true` when the socket is open (`readyState === 1`) and auth has completed.
+   * @returns `true` if the transport can send messages
+   */
+  isReady(): boolean;
+  /**
+   * Trigger an immediate reconnection attempt.
+   *
+   * Cancels an active backoff wait, starts the reconnect loop if it stalled,
+   * or performs a one-shot connect when auto-reconnect is disabled.
+   * @returns Promise that resolves when the attempt is initiated (loop) or completes (one-shot)
+   */
+  reconnect(): Promise<void>;
+  /**
+   * Start the background reconnect loop; thin wrapper around `runReconnectLoop`.
+   * @param signal - AbortSignal that stops the loop (fires on `disconnect()`)
+   * @returns Promise that resolves when the loop exits (signal aborted)
+   */
+  private startReconnectLoop;
+  /**
+   * Build a `SubscriptionDeps` snapshot for the subscription helpers.
+   * @returns Subscription dependency context bound to this transport instance
+   */
+  private subscriptionDeps;
+  /**
+   * Build the `ConnectionDeps` context for connection lifecycle helpers.
+   * @returns Connection dependency context bound to this transport instance
+   */
+  private connectionDeps;
+  /**
+   * Default `ws`-package WebSocket factory (dynamic import avoids bundling in browsers).
+   * @param url - WebSocket server URL
+   * @returns Promise resolving to a `WebSocketLike` instance
+   */
+  private readonly defaultWsFactory;
+  /**
+   * Wire the no-reconnect close listener; resets `reconnectAbort` on close
+   * so `connect()` can be called again.
+   * @param ws - The connected socket to watch for closure
+   */
+  private wireNoReconnectClose;
+}
+//#endregion
+//#region transports/ws/src/server-transport.d.ts
+interface ServerTransportOptions {
+  websocket: WebSocketServerLike;
+  /**
+   * Transport identity used as the registry key when registered on a bus.
+   * @defaultValue 'websocket'
+   */
+  name?: string;
+  auth?: TransportAuth;
+  debug?: boolean;
+}
+/**
+ * Server-mode WebSocket transport.
+ *
+ * Manages multiple client connections and broadcasts messages to all connected clients.
+ * @example
+ * ```typescript
+ * import { WebSocketServer } from 'ws';
+ *
+ * const wss = new WebSocketServer({ port: 8080 });
+ * const transport = new ServerTransport({
+ *   websocket: wss,
+ * });
+ *
+ * await transport.connect();
+ * ```
+ */
+declare class ServerTransport implements BusTransport {
+  /** Transport identity used as the registry key when registered on a bus. */
+  readonly name: string;
+  private readonly wss;
+  private readonly auth;
+  private readonly debug;
+  private readonly handlers;
+  private readonly registry;
+  /** Server-local handler subjects + priorities, advertised to connected clients. */
+  private readonly serverSubscriptions;
+  private readonly broadcastAggregator;
+  private readonly correlations;
+  private connectionListener;
+  /**
+   * @param options - Server transport configuration
+   */
+  constructor(options: ServerTransportOptions);
+  /**
+   * Send serialized data to a client without letting one socket failure disrupt fan-out.
+   * @param client - Target client socket
+   * @param data - Serialized message payload
+   */
+  private sendToClientSafely;
+  /**
+   * Start listening for client connections.
+   * @throws Error when called while the transport is already connected
+   */
+  connect(): Promise<void>;
+  /**
+   * Stop listening and disconnect all clients.
+   */
+  disconnect(): Promise<void>;
+  /**
+   * Send a broadcast message to all interested clients and aggregate responses.
+   * @param message - Broadcast message to fan out
+   * @param timeout - Broadcast response aggregation timeout in milliseconds. Use `0` to disable automatic timeout and
+   * finalization, which can leave the returned promise pending until every target client responds or disconnects
+   * @returns Promise resolving to aggregated results from all responding handlers
+   */
+  send(message: BusBroadcastMessage, timeout?: number): Promise<Array<{
+    nodeId: string;
+    payload: unknown;
+  }>>;
+  /**
+   * Send a request to connected clients and return the first response.
+   * @param message - Request message
+   * @param timeout - Correlation timeout in milliseconds; `0` means no automatic timeout
+   * @returns Promise resolving to the handler response payload
+   */
+  send(message: BusRequestMessage, timeout?: number): Promise<unknown>;
+  /**
+   * Send an event or other message to all interested clients.
+   * @param message - Bus message to deliver
+   * @param timeout - Correlation timeout in milliseconds; `0` means no automatic timeout
+   * @returns Promise resolving to `true` if delivered to at least one client, `false` otherwise
+   */
+  send(message: BusMessage, timeout?: number): Promise<boolean>;
+  /**
+   * Register a handler for incoming messages from clients.
+   * @param handler - Handler function for incoming messages
+   * @returns Unsubscribe function
+   */
+  onReceive(handler: BusReceiveHandler): () => void;
+  /**
+   * Cancel a pending correlated server-initiated request.
+   * @param correlationId - Correlation ID to cancel
+   * @param error - Optional cancellation error
+   */
+  cancelRequest(correlationId: string, error?: Error): void;
+  /**
+   * Receive aggregated broadcast results from the transport registry.
+   *
+   * Called directly by the transport registry after executing local handlers
+   * and relay transports for a client-initiated broadcast, replacing the
+   * legacy send() side-channel.
+   * @param correlationId - Correlation ID of the originating broadcast
+   * @param results - Aggregated results from local handlers and relay transports
+   * @param error - Optional structured error propagated to the originator
+   */
+  onBroadcastResults(correlationId: string, results: ReadonlyArray<{
+    nodeId: string;
+    payload: unknown;
+  }>, error?: BusTransportError): void;
+  /**
+   * Advertise a server-local handler to all connected WebSocket clients.
+   *
+   * Called by the transport registry when a handler registers on this bus via
+   * `bus.on()`. The full accumulated priority set for the subject is received
+   * (replace semantics, not incremental).
+   * @param subject - Subject pattern
+   * @param filter - Optional payload filter
+   * @param priorities - Handler priorities for priority-based dispatch
+   */
+  subscribe(subject: string, filter?: PayloadFilter, priorities?: number[]): Promise<void>;
+  /**
+   * Return the number of currently authenticated and connected clients.
+   *
+   * Clients that are still in the authentication phase are not counted.
+   * @returns Number of fully connected clients
+   */
+  getConnectionCount(): number;
+  /**
+   * Remove a server-local handler advertisement from all connected clients.
+   * @param subject - Subject pattern to unsubscribe
+   */
+  unsubscribe(subject: string): Promise<void>;
+}
+//#endregion
+//#region transports/ws/src/transport-helpers.d.ts
+/**
+ * Extract an error message from a WebSocket error event.
+ *
+ * Node `ws` fires `ErrorEvent` (has `.message`), browsers fire a plain `Event`
+ * without it. This helper normalises both shapes into a string.
+ * @param event - The error event from a WebSocket `error` listener
+ * @param fallback - Fallback message when no `.message` property exists
+ * @returns Human-readable error message
+ */
+declare function extractSocketErrorMessage(event: Event, fallback?: string): string;
+//#endregion
+//#region transports/ws/src/create-e2e-transport.d.ts
+/**
+ * E2E transport configuration.
+ *
+ * The `e2eAuth` instance serves as both the TransportAuth (for the handshake)
+ * and the session key provider (for message encryption/decryption).
+ *
+ * Provide a pre-created `websocket` to wrap a caller-owned socket. All other
+ * options are forwarded to `WebSocketClientTransport` (excluding `auth`,
+ * `messageTransform`, `url`, `createWebSocket`, and `autoReconnect`, which
+ * are managed internally by this factory).
+ */
+interface E2ETransportOptions extends Omit<WebSocketClientTransportOptions, 'auth' | 'messageTransform' | 'url' | 'createWebSocket' | 'autoReconnect'> {
+  /**
+   * Pre-created WebSocket instance to wrap.
+   *
+   * The factory treats this socket as caller-owned and disables
+   * auto-reconnect. When reconnect is needed, the caller is responsible for
+   * creating new sockets.
+   */
+  websocket: WebSocketLike;
+  /**
+   * E2E auth instance used for both handshake and encryption.
+   */
+  e2eAuth: E2EAuth;
+}
+//#endregion
+//#region transports/ws/src/e2e-client-transport.d.ts
+/**
+ * E2E client transport configuration.
+ *
+ * The `e2eAuth` instance serves as both the TransportAuth (for the handshake)
+ * and the session key provider (for message encryption/decryption).
+ */
+type E2EClientTransportOptions = E2ETransportOptions;
+/**
+ * Create an E2E encrypted client transport.
+ *
+ * Wraps a `WebSocketClientTransport` to transparently encrypt/decrypt
+ * application payload/result/error fields using the session key established
+ * during E2E auth.
+ *
+ * Decryption runs in the `messageTransform` pipeline, so response
+ * correlation sees decrypted results and errors.
+ * @param options - E2E client transport configuration
+ * @returns BusTransport with E2E encryption
+ * @example
+ * ```typescript
+ * const e2eAuth = new E2EAuth({
+ *   signingKeyPair,
+ *   identityId: deviceId,
+ *   peerId: machineId,
+ *   getPeerSigningKey: async () => machinePublicKey,
+ * });
+ *
+ * const transport = createE2EClientTransport({
+ *   websocket: ws,
+ *   e2eAuth,
+ * });
+ *
+ * await transport.connect(); // Runs E2E handshake
+ * // Subsequent application payload/result/error fields are encrypted automatically.
+ * ```
+ */
+declare function createE2EClientTransport(options: E2EClientTransportOptions): BusTransport;
+//#endregion
+//#region transports/ws/src/relay-control-registry.d.ts
+/**
+ * Registry for relay control subjects.
+ *
+ * Maps namespace/subject pairs to their plaintext (control-plane) classification.
+ * Host code registers control subjects at boot time before freezing the
+ * registry. Once frozen, no further registrations are allowed — this enforces
+ * the security invariant that the plaintext subject set cannot change after the
+ * transport handshake begins.
+ */
+/**
+ * Mutable-then-frozen registry mapping relay control namespaces and subjects.
+ *
+ * Callers register event subjects and request namespaces before calling
+ * {@link RelayControlRegistry.freeze}. After freezing, all `register*` methods
+ * throw so the set cannot be widened post-handshake.
+ */
+interface RelayControlRegistry {
+  /**
+   * Register a set of plaintext event subjects for a namespace.
+   *
+   * May be called multiple times for the same namespace — subjects accumulate.
+   * @param namespace - Bus namespace (e.g. `'relay'`)
+   * @param subjects - Subject names to classify as control events
+   * @throws When called after {@link freeze}
+   */
+  registerEventSubjects(namespace: string, subjects: readonly string[]): void;
+  /**
+   * Register an explicit allowlist of plaintext request subjects for a namespace.
+   *
+   * Only the listed subjects will be classified as control-plane (plaintext)
+   * traffic for the given namespace. An explicit allowlist is required — there
+   * is no allow-all mode — to enforce least-privilege classification.
+   * @param namespace - Bus namespace (e.g. `'tunnel'`)
+   * @param subjects - Explicit subject allowlist; must be non-empty
+   * @throws When called after {@link freeze}
+   */
+  registerRequestNamespace(namespace: string, subjects: readonly string[]): void;
+  /**
+   * Freeze the registry.
+   *
+   * After freezing, `registerEventSubjects` and `registerRequestNamespace`
+   * throw on any call. Must be called before passing the registry to the
+   * transport so the security invariant (no post-handshake plaintext injection)
+   * is enforced.
+   */
+  freeze(): void;
+  /**
+   * Check whether the registry has been frozen.
+   *
+   * The transport asserts this is `true` inside `connect()` to guarantee
+   * the plaintext subject set cannot be widened after the handshake begins.
+   * @returns `true` after {@link freeze} has been called
+   */
+  isFrozen(): boolean;
+  /**
+   * Check whether an event message on the given namespace/subject is a control event.
+   * @param namespace - Bus namespace of the event
+   * @param subject - Subject of the event
+   * @returns `true` when this namespace/subject pair is registered as a control event
+   */
+  isControlEvent(namespace: string, subject: string): boolean;
+  /**
+   * Check whether a request on the given namespace/subject is a control request.
+   * @param namespace - Bus namespace of the request
+   * @param subject - Subject of the request
+   * @returns `true` when this namespace/subject pair is registered as a control request
+   */
+  isControlRequest(namespace: string, subject: string): boolean;
+}
+/**
+ * Create a new mutable relay control registry.
+ *
+ * The registry starts unfrozen. Call `registerEventSubjects` and
+ * `registerRequestNamespace` to populate it, then call `freeze()` before
+ * passing it to the transport.
+ * @returns A fresh, unfrozen {@link RelayControlRegistry}
+ */
+declare function createRelayControlRegistry(): RelayControlRegistry;
+//#endregion
+//#region transports/ws/src/e2e-relay-client-transport.d.ts
+/**
+ * E2E relay client transport configuration.
+ *
+ * Provide a pre-created `websocket` to wrap a caller-owned socket. All other
+ * options are forwarded to `WebSocketClientTransport` (excluding `auth`,
+ * `messageTransform`, `url`, `codec`, `createWebSocket`, and `autoReconnect`,
+ * which are managed internally by this factory).
+ */
+interface E2ERelayClientTransportOptions extends Omit<WebSocketClientTransportOptions, 'auth' | 'messageTransform' | 'url' | 'createWebSocket' | 'codec' | 'autoReconnect'> {
+  /**
+   * Pre-created WebSocket instance to wrap.
+   *
+   * The factory treats this socket as caller-owned and disables
+   * auto-reconnect. When reconnect is needed, the caller is responsible for
+   * creating new sockets.
+   */
+  websocket: WebSocketLike;
+  /**
+   * Relay-mode E2E auth instance.
+   */
+  e2eAuth: E2ERelayAuth;
+  /**
+   * Frozen relay control registry that classifies plaintext control subjects.
+   *
+   * Must be frozen before the transport begins connecting. Determines which
+   * namespace/subject pairs are routed as relay-control envelopes rather than
+   * E2E encrypted messages.
+   */
+  registry: RelayControlRegistry;
+}
+/**
+ * Return value of {@link createE2ERelayCodec}.
+ *
+ * The `reset` method clears all tracked relay-control correlation IDs so that
+ * stale IDs from a previous WebSocket session do not bleed into the next E2E
+ * session when the codec is reused across reconnections.
+ */
+interface E2ERelayCodecHandle {
+  /** Wire codec for E2E relay encryption. */
+  codec: ClientTransportCodec;
+  /**
+   * Clear all relay-control correlation IDs.
+   *
+   * Must be called at the start of each new connection attempt when the same
+   * codec instance is reused across {@link WebSocketClientTransport}
+   * reconnections (e.g. inside `authenticateClient`).
+   */
+  reset: () => void;
+}
+/**
+ * Create the wire codec for an E2E encrypted relay transport.
+ *
+ * The codec handles message encryption/decryption and relay-control envelope
+ * routing. Use this when constructing a `WebSocketClientTransport` with E2E
+ * relay encryption instead of the lower-level `createE2ERelayClientTransport`.
+ *
+ * The returned `reset()` method **must** be called at the start of each new
+ * connection attempt when the codec is reused across reconnections. Failing to
+ * reset allows relay-control correlation IDs from a previous session to
+ * influence routing decisions in the new E2E session.
+ * @param e2eAuth - Relay-mode E2E auth instance
+ * @param registry - Frozen relay control registry for subject classification
+ * @param debug - Enable diagnostic logging
+ * @returns Codec handle containing the wire codec and a session-reset function
+ */
+declare function createE2ERelayCodec(e2eAuth: E2ERelayAuth, registry: RelayControlRegistry, debug?: boolean): E2ERelayCodecHandle;
+/**
+ * Create an E2E encrypted relay client transport.
+ * @param options - Transport configuration
+ * @returns BusTransport with relay-mode E2E encryption
+ */
+declare function createE2ERelayClientTransport(options: E2ERelayClientTransportOptions): BusTransport;
+//#endregion
+//#region transports/ws/src/relay-control-envelope.d.ts
+/**
+ * Relay control envelope message shape used on the wire.
+ */
+interface RelayControlEnvelopeMessage {
+  type: 'relay-control';
+  payload: RelayControlBusMessage;
+  v: 1;
+}
+/** Bus message type that may be wrapped in a relay control envelope. */
+type RelayControlBusMessage = BusEventMessage | BusRequestMessage;
+/**
+ * Return value of {@link createRelayControlHelpers}.
+ *
+ * All three helpers share the same {@link RelayControlRegistry} captured in
+ * their common closure.
+ */
+interface RelayControlHelpers {
+  /**
+   * Create a relay control envelope for a relay-owned bus message.
+   *
+   * Throws when the message is not classified as a control message by the
+   * registry (i.e. would not pass {@link isRelayControlBusMessage}).
+   * @param message - Relay bus message to wrap
+   * @returns Relay control envelope message
+   */
+  createRelayControlEnvelope(message: RelayControlBusMessage): RelayControlEnvelopeMessage;
+  /**
+   * Check whether a parsed wire value is a relay control envelope.
+   * @param message - Parsed message candidate
+   * @returns `true` if the value is a relay control envelope
+   */
+  isRelayControlEnvelopeMessage(message: unknown): message is RelayControlEnvelopeMessage;
+  /**
+   * Check whether a bus message is a relay control event or request.
+   * @param message - Bus message candidate
+   * @returns `true` when the message is classified as a relay control message
+   */
+  isRelayControlBusMessage(message: unknown): message is RelayControlBusMessage;
+}
+/**
+ * Create relay control envelope helpers bound to a specific registry.
+ *
+ * The registry must be {@link RelayControlRegistry.freeze | frozen} before
+ * calling this function — or at minimum before the transport begins
+ * processing messages — so the security invariant (no post-handshake
+ * plaintext injection) is upheld.
+ * @param registry - Frozen relay control registry
+ * @returns Helper functions with the registry captured in their closure
+ */
+declare function createRelayControlHelpers(registry: RelayControlRegistry): RelayControlHelpers;
+//#endregion
+//#region transports/ws/src/crypto/ecdh.d.ts
+/**
+ * ECDH (Elliptic Curve Diffie-Hellman) key management using Web Crypto API.
+ *
+ * Implements ECDH P-256 for secure key exchange in E2E encryption.
+ * Uses Web Crypto API for browser and Node.js compatibility.
+ */
+/**
+ * Generate an ECDH P-256 keypair.
+ *
+ * Creates a new elliptic curve keypair for ECDH key exchange.
+ * The P-256 curve is universally supported by Web Crypto API.
+ * @param extractable - Whether the private key can be exported. Set to false for browser device keys (security), true for Node.js server keys (persistence).
+ * @returns Promise resolving to CryptoKeyPair
+ */
+declare function generateECDHKeyPair(extractable?: boolean): Promise<CryptoKeyPair>;
+/**
+ * Export public key to base64url (SPKI format).
+ * @param key - Public CryptoKey to export
+ * @returns Promise resolving to base64url-encoded public key
+ */
+declare function exportPublicKey(key: CryptoKey): Promise<string>;
+/**
+ * Export ECDH public key to base64url (raw format).
+ * @param key - Public CryptoKey to export
+ * @returns Base64url-encoded raw public key
+ */
+declare function exportPublicKeyRaw(key: CryptoKey): Promise<string>;
+/**
+ * Import ECDH public key from base64url raw format.
+ * @param base64url - Base64url-encoded raw public key
+ * @returns Imported CryptoKey for ECDH operations
+ */
+declare function importPublicKeyRaw(base64url: string): Promise<CryptoKey>;
+/**
+ * Import public key from base64url (SPKI format).
+ * @param base64url - Base64url-encoded public key (SPKI format)
+ * @param usages - Key usages (default: empty for public keys used only in deriveBits)
+ * @returns Promise resolving to imported CryptoKey
+ */
+declare function importPublicKey(base64url: string, usages?: KeyUsage[]): Promise<CryptoKey>;
+/**
+ * Export private key to PKCS8 PEM format (for Node.js file storage).
+ * @param key - Private CryptoKey to export
+ * @returns Promise resolving to PEM string
+ * @throws Error if key is non-extractable
+ */
+declare function exportPrivateKeyPEM(key: CryptoKey): Promise<string>;
+/**
+ * Import private key from PKCS8 PEM format.
+ * @param pem - PEM-encoded private key string
+ * @returns Promise resolving to imported CryptoKey
+ */
+declare function importPrivateKeyPEM(pem: string): Promise<CryptoKey>;
+/**
+ * Derive shared secret via ECDH.
+ *
+ * Performs ECDH key agreement: combines own private key with peer's public key
+ * to derive a shared secret. Both parties derive the same secret.
+ * @param privateKey - Own private key
+ * @param publicKey - Peer's public key
+ * @returns Promise resolving to raw shared secret as ArrayBuffer
+ */
+declare function deriveSharedSecret(privateKey: CryptoKey, publicKey: CryptoKey): Promise<ArrayBuffer>;
+//#endregion
+//#region transports/ws/src/crypto/aes-gcm.d.ts
+/**
+ * AES-256-GCM encryption and decryption using Web Crypto API.
+ *
+ * AES-GCM provides authenticated encryption: both confidentiality
+ * and integrity protection in a single operation.
+ */
+/**
+ * Encrypt plaintext with AES-256-GCM.
+ *
+ * Generates a random 12-byte nonce and encrypts data.
+ * The nonce must be transmitted alongside the ciphertext for decryption.
+ * @param key - AES-256 CryptoKey
+ * @param plaintext - Data to encrypt (Uint8Array)
+ * @returns Promise resolving to object with ciphertext and nonce
+ * @example
+ * ```typescript
+ * const sessionKey = await deriveSessionKey(...);
+ * const plaintext = encodeText(JSON.stringify(payload));
+ * const { ciphertext, nonce } = await encrypt(sessionKey, plaintext);
+ * // Send both ciphertext and nonce to peer
+ * ```
+ */
+declare function encrypt(key: CryptoKey, plaintext: Uint8Array): Promise<{
+  ciphertext: Uint8Array;
+  nonce: Uint8Array;
+}>;
+/**
+ * Decrypt ciphertext with AES-256-GCM.
+ *
+ * Decrypts data using the same nonce that was used for encryption.
+ * Automatically verifies the authentication tag - throws if data was tampered with.
+ * @param key - AES-256 CryptoKey
+ * @param ciphertext - Encrypted data
+ * @param nonce - 12-byte nonce used during encryption
+ * @returns Promise resolving to decrypted Uint8Array
+ * @throws Error if authentication fails (data tampered with)
+ * @example
+ * ```typescript
+ * const plaintext = await decrypt(sessionKey, ciphertext, nonce);
+ * const payload = JSON.parse(decodeText(plaintext));
+ * ```
+ */
+declare function decrypt(key: CryptoKey, ciphertext: Uint8Array, nonce: Uint8Array): Promise<Uint8Array>;
+/**
+ * Import raw AES-256-GCM key.
+ *
+ * Converts raw key material (from HKDF) into a CryptoKey for encryption/decryption.
+ * @param rawKey - 32-byte raw key material (256 bits)
+ * @returns Promise resolving to AES-256 CryptoKey
+ * @example
+ * ```typescript
+ * const rawSessionKey = await deriveSessionKeyRaw(...);
+ * const sessionKey = await importAESKey(rawSessionKey);
+ * ```
+ */
+declare function importAESKey(rawKey: ArrayBuffer): Promise<CryptoKey>;
+//#endregion
+//#region transports/ws/src/crypto/hkdf.d.ts
+/**
+ * HKDF (HMAC-based Key Derivation Function) using Web Crypto API.
+ *
+ * Derives a session encryption key from ECDH shared secret.
+ * HKDF provides key stretching and domain separation.
+ */
+/**
+ * Derive AES-256 key from shared secret using HKDF-SHA256.
+ *
+ * Performs HKDF key derivation to convert raw ECDH shared secret
+ * into a proper AES-256 session key. Uses salt for randomness
+ * and info for domain separation.
+ * @param sharedSecret - Raw shared secret from ECDH (ArrayBuffer)
+ * @param salt - Salt bytes (can be random or fixed context). Recommended: 16+ bytes of randomness.
+ * @param info - Context string for domain separation (e.g., "makaio-e2e-session-v1")
+ * @returns Promise resolving to AES-256 CryptoKey
+ * @example
+ * ```typescript
+ * const sharedSecret = await deriveSharedSecret(myPrivateKey, peerPublicKey);
+ * const salt = crypto.getRandomValues(new Uint8Array(16));
+ * const sessionKey = await deriveSessionKey(sharedSecret, salt, "makaio-e2e-session-v1");
+ * ```
+ */
+declare function deriveSessionKey(sharedSecret: ArrayBuffer, salt: Uint8Array, info: string): Promise<CryptoKey>;
+//#endregion
+//#region transports/ws/src/crypto/ecdsa.d.ts
+/**
+ * ECDSA (Elliptic Curve Digital Signature Algorithm) using Web Crypto API.
+ *
+ * Implements ECDSA P-256 SHA-256 for signing ephemeral public keys
+ * during E2E authentication handshake.
+ */
+/**
+ * Generate an ECDSA P-256 signing keypair.
+ *
+ * Creates a new elliptic curve keypair for digital signatures.
+ * The P-256 curve with SHA-256 is universally supported by Web Crypto API.
+ * @param extractable - Whether the private key can be exported. Set to false for browser device keys (security), true for Node.js server keys (persistence).
+ * @returns Promise resolving to CryptoKeyPair
+ */
+declare function generateSigningKeyPair(extractable?: boolean): Promise<CryptoKeyPair>;
+/**
+ * Sign data with ECDSA P-256 SHA-256.
+ *
+ * Creates a digital signature over the data using the private key.
+ * @param privateKey - Signing private key
+ * @param data - Data to sign (Uint8Array)
+ * @returns Promise resolving to signature as Uint8Array
+ */
+declare function sign(privateKey: CryptoKey, data: Uint8Array): Promise<Uint8Array>;
+/**
+ * Verify ECDSA P-256 SHA-256 signature.
+ *
+ * Verifies that the signature was created by the holder of the private key
+ * corresponding to the public key.
+ * @param publicKey - Verification public key
+ * @param signature - Signature to verify
+ * @param data - Original data that was signed
+ * @returns Promise resolving to true if signature is valid, false otherwise
+ */
+declare function verify(publicKey: CryptoKey, signature: Uint8Array, data: Uint8Array): Promise<boolean>;
+/**
+ * Export signing public key to base64url (SPKI format).
+ * @param key - Public CryptoKey to export
+ * @returns Promise resolving to base64url-encoded public key
+ */
+declare function exportSigningPublicKey(key: CryptoKey): Promise<string>;
+/**
+ * Import signing public key from base64url for verification.
+ * @param base64url - Base64url-encoded public key (SPKI format)
+ * @returns Promise resolving to imported CryptoKey for verification
+ */
+declare function importSigningPublicKey(base64url: string): Promise<CryptoKey>;
+/**
+ * Export signing public key to base64url (raw format).
+ * @param key - Public CryptoKey to export
+ * @returns Base64url-encoded raw public key
+ */
+declare function exportSigningPublicKeyRaw(key: CryptoKey): Promise<string>;
+/**
+ * Import signing public key from base64url raw format.
+ * @param base64url - Base64url-encoded raw public key
+ * @returns Imported CryptoKey for verification
+ */
+declare function importSigningPublicKeyRaw(base64url: string): Promise<CryptoKey>;
+/**
+ * Export signing private key to PKCS8 PEM format (for Node.js file storage).
+ * @param key - Private CryptoKey to export
+ * @returns Promise resolving to PEM string
+ * @throws Error if key is non-extractable
+ */
+declare function exportSigningPrivateKeyPEM(key: CryptoKey): Promise<string>;
+/**
+ * Import signing private key from PKCS8 PEM format.
+ * @param pem - PEM-encoded private key string
+ * @returns Promise resolving to imported CryptoKey
+ */
+declare function importSigningPrivateKeyPEM(pem: string): Promise<CryptoKey>;
+//#endregion
+//#region transports/ws/src/crypto/encoding.d.ts
+/**
+ * Base64url encoding utilities for cryptographic data.
+ *
+ * Uses URL-safe base64 encoding (RFC 4648) without padding.
+ * Standard for encoding binary crypto material in JSON/URLs.
+ */
+/**
+ * Encode Uint8Array to base64url string.
+ *
+ * Converts binary data to URL-safe base64 string without padding.
+ * Uses chunked approach to avoid call stack overflow on large payloads.
+ * @param data - Binary data to encode
+ * @returns Base64url-encoded string
+ * @example
+ * ```typescript
+ * const nonce = crypto.getRandomValues(new Uint8Array(12));
+ * const encoded = toBase64Url(nonce); // "Zj4Qr..." (no padding)
+ * ```
+ */
+declare function toBase64Url(data: Uint8Array): string;
+/**
+ * Decode base64url string to Uint8Array.
+ *
+ * Converts URL-safe base64 string back to binary data.
+ * @param base64url - Base64url-encoded string
+ * @returns Binary data as Uint8Array
+ * @throws Error if input is not valid base64url
+ * @example
+ * ```typescript
+ * const data = fromBase64Url("Zj4Qr...");
+ * ```
+ */
+declare function fromBase64Url(base64url: string): Uint8Array;
+/**
+ * Encode string to Uint8Array (UTF-8).
+ *
+ * Converts text to binary using UTF-8 encoding.
+ * @param text - String to encode
+ * @returns UTF-8 encoded bytes
+ * @example
+ * ```typescript
+ * const data = encodeText("Hello, world!");
+ * ```
+ */
+declare function encodeText(text: string): Uint8Array;
+/**
+ * Decode Uint8Array to string (UTF-8).
+ *
+ * Converts binary data to text using UTF-8 decoding.
+ * @param data - Binary data to decode
+ * @returns Decoded string
+ * @example
+ * ```typescript
+ * const text = decodeText(data);
+ * ```
+ */
+declare function decodeText(data: Uint8Array): string;
+declare namespace index_d_exports {
+  export { decodeText, decrypt, deriveSessionKey, deriveSharedSecret, encodeText, encrypt, exportPrivateKeyPEM, exportPublicKey, exportPublicKeyRaw, exportSigningPrivateKeyPEM, exportSigningPublicKey, exportSigningPublicKeyRaw, fromBase64Url, generateECDHKeyPair, generateSigningKeyPair, importAESKey, importPrivateKeyPEM, importPublicKey, importPublicKeyRaw, importSigningPrivateKeyPEM, importSigningPublicKey, importSigningPublicKeyRaw, sign, toBase64Url, verify };
+}
+//#endregion
+//#region transports/ws/src/index.d.ts
+/**
+ * Create a WebSocket transport for the specified mode.
+ *
+ * For client mode the transport wraps a pre-created `WebSocket` via
+ * `WebSocketClientTransport`. Because this factory accepts an already-created
+ * socket, caller-supplied dial-time `connectionOptions` cannot be honored here;
+ * use `WebSocketClientTransport` directly when you need reconnect or socket
+ * creation options.
+ * @param options - Transport configuration
+ * @returns BusTransport instance
+ */
+declare function createWebSocketTransport(options: WebSocketTransportOptions): BusTransport;
+/**
+ * Module augmentation for BusTransportRegistry.
+ *
+ * This enables type-safe access to the WebSocket transport:
+ * ```typescript
+ * const transport = getTransport('websocket'); // Type: BusTransport
+ * ```
+ */
+declare module '@makaio/framework/bus' {
+  interface BusTransportRegistry {
+    websocket: BusTransport;
+  }
+}
+//#endregion
+export { type ClientTransportCodec, DispatchingAuth, E2EAuth, E2ERelayAuth, type E2ERelayAuthOptions, HmacAuth, type RelayControlBusMessage, type RelayControlEnvelopeMessage, type RelayControlHelpers, type RelayControlRegistry, ServerTransport, type TransportAuth, WebSocketClientTransport, type WebSocketClientTransportOptions, type WebSocketClientTransportReconnectOptions, type WebSocketCloseEvent, type WebSocketLike, type WebSocketServerLike, createE2EClientTransport, createE2ERelayClientTransport, createE2ERelayCodec, createRelayControlHelpers, createRelayControlRegistry, createWebSocketCloseEvent, createWebSocketTransport, index_d_exports as crypto, extractSocketErrorMessage };