@robota-sdk/agent-transport-webrtc 3.0.0-beta.100

package/src/webrtc-delivery-lifecycle.ts

@@ -0,0 +1,54 @@
+/** The part of a data channel the lifecycle closes. */
+interface IClosableChannel {
+  close(): void;
+}
+
+interface IWebRtcDeliveryLifecycleOptions {
+  readonly cleanup: () => void;
+  readonly onDropped: () => void;
+  readonly onDeliveryError: (error: Error, event: string) => void;
+}
+
+/** Owns carrier-drop state so delivery failures cannot leak into committed session operations. */
+export class WebRtcDeliveryLifecycle {
+  private generation = 0;
+  private paired = false;
+  private dropped = false;
+
+  constructor(private readonly options: IWebRtcDeliveryLifecycleOptions) {}
+
+  reset(generation: number): void {
+    this.generation = generation;
+    this.paired = false;
+    this.dropped = false;
+  }
+
+  accept(generation: number): void {
+    if (generation === this.generation) this.paired = true;
+  }
+
+  handleDrop(generation: number): void {
+    if (generation !== this.generation || !this.paired || this.dropped) return;
+    this.dropped = true;
+    this.options.cleanup();
+    this.options.onDropped();
+  }
+
+  handleFailure(channel: IClosableChannel, generation: number, error: Error, event: string): void {
+    if (generation !== this.generation || this.dropped) return;
+    const notifyDrop = this.paired;
+    if (notifyDrop) this.dropped = true;
+    try {
+      this.options.onDeliveryError(error, event);
+    } catch {
+      // Observer failure cannot interrupt carrier cleanup or a committed session operation.
+    }
+    this.options.cleanup();
+    try {
+      channel.close();
+    } catch {
+      // already closing/closed
+    }
+    if (notifyDrop) this.options.onDropped();
+  }
+}

package/src/webrtc-transport-options.ts

@@ -0,0 +1,87 @@
+import type { IIdentityContext } from '@robota-sdk/agent-remote-pairing';
+/**
+ * What a caller CONFIGURES on the WebRTC host transport.
+ *
+ * Separated from the transport itself because "what may be set" and "what the transport does with
+ * it" are different subjects, and `webrtc-transport.ts` had reached the anti-monolith limit where
+ * the rule is to split rather than extend. Types only — no behaviour moved.
+ */
+
+import type { IConnectionApproval, IHostReconnectConfig } from './pairing-gate.js';
+import type { ILocalPeerProof } from './local-peer-proof.js';
+import type { ISignalingClient } from './signaling.js';
+import type { IDataChannelModule } from './datachannel-loader.js';
+import type { IPairingResult } from '@robota-sdk/agent-remote-pairing';
+import type {
+  ISessionMessageHandlerOptions,
+  SessionResumeBridge,
+} from '@robota-sdk/agent-transport';
+
+/**
+ * A single ICE (STUN/TURN) server for the host transport. `urls` is one `stun:`/`stuns:`/`turn:`/`turns:` url
+ * (optionally `?transport=tcp`); TURN servers carry username/credential. The browser peer uses the native DOM
+ * `RTCIceServer`, a separate, wider shape. Kept a plain interface (no DOM dependency here).
+ */
+export interface IIceServer {
+  readonly urls: string;
+  readonly username?: string;
+  readonly credential?: string;
+}
+
+/**
+ * Construction options for {@link WebRtcTransport}. The signaling client is injected; the transport declares no
+ * settings schema of its own (`optionsSchema` is empty).
+ */
+export interface IWebRtcTransportOptions {
+  readonly cryptoContext: IIdentityContext;
+  /** Host-owned usage read models, available only after admission. */
+  readonly personalUsageReporter?: ISessionMessageHandlerOptions['personalUsageReporter'];
+  readonly usageReporter?: ISessionMessageHandlerOptions['usageReporter'];
+  readonly storedSessionUsageReporter?: ISessionMessageHandlerOptions['storedSessionUsageReporter'];
+  /** Signaling port used to exchange SDP/ICE with the remote peer by rendezvous id. */
+  readonly signaling: ISignalingClient;
+  /** Optional ICE servers (STUN/TURN). Omitted → host-candidate/loopback only. */
+  readonly iceServers?: readonly IIceServer[];
+  /**
+   * REMOTE-004 defense-in-depth: when true, restrict ICE to **relay (TURN) candidates only**, so
+   * host/server-reflexive candidates are never used. Requires a TURN server in `iceServers`. Mapped to the
+   * connection's `iceTransportPolicy: 'relay'`.
+   */
+  readonly forceTurn?: boolean;
+  /**
+   * REMOTE-008 pairing secret. When set, the data channel is **pairing-gated**: it carries only pairing frames
+   * until the directional-HMAC handshake accepts (channel-bound to the DTLS fingerprints), and only THEN is the
+   * session exposed — fail closed on mismatch/timeout. When omitted, the constructor throws unless the caller
+   * explicitly opts out with `open: true` and an `openReason` (loopback / tests); only then is the channel
+   * exposed immediately with no pairing.
+   */
+  readonly secret?: string;
+  /**
+   * SEC-008: run with NO pairing gate. Requires `openReason`.
+   *
+   * Omitting `secret` used to mean this implicitly, which is how a remote peer reached the session
+   * because a field was left unset. It is still a legitimate mode — loopback, tests — but it is now
+   * a thing the host says rather than a thing that happens.
+   */
+  readonly open?: boolean;
+  /** SEC-008: why running with no pairing gate is correct here. Required when `open` is true. */
+  readonly openReason?: string;
+  /** REMOTE-008: fired when pairing accepts + the session is exposed (host lifecycle → status 'paired'). Carries the first-pair result (E4 uses its sessionKey). */
+  readonly onPaired?: (result?: IPairingResult) => void;
+  /** REMOTE-008: fired when pairing rejects/times out (host lifecycle → teardown; the channel is already closed). */
+  readonly onPairingFailed?: () => void;
+  /** REMOTE-012 E3: host reconnect/enrollment config. When set, the gate admits first-pair (with enrollment) OR a pinned-device reconnect. */
+  readonly reconnect?: IHostReconnectConfig;
+  /** SEC-010 (#1810): require a guarded-rendezvous nonce before the session is exposed. Absent → unchanged. */
+  readonly localPeer?: ILocalPeerProof;
+  /** Ask the receiving operator before each connection reaches the session. Absent → unchanged. */
+  readonly connectionApproval?: IConnectionApproval;
+  /** REMOTE-013 E4: a session-scoped resume bridge (owned by the controller across reconnects). Passed to the gate so the paired session flows through it (seq/buffer) and survives channel drops. */
+  readonly resumeBridge?: SessionResumeBridge;
+  /** REMOTE-013 E4: fired when a PAIRED data channel drops (so the controller can run the reconnect loop). Not fired for a pre-accept failure (that is `onPairingFailed`). */
+  readonly onDropped?: () => void;
+  /** Observe an outbound session-event delivery failure before the carrier drops. */
+  readonly onDeliveryError?: (error: Error, event: string) => void;
+  /** Test seam: inject the `node-datachannel` module (defaults to the real lazy loader). */
+  readonly loadDataChannel?: () => IDataChannelModule;
+}

package/src/webrtc-transport.ts

@@ -0,0 +1,368 @@
+import { HISTORY_PAGE_MAX_BYTES, createSessionMessageHandler } from '@robota-sdk/agent-transport';
+import { resolveAdmission } from '@robota-sdk/agent-transport/node';
+import {
+  extractDtlsFingerprint,
+  extractDtlsFingerprintAttribute,
+} from '@robota-sdk/agent-remote-pairing';
+import type { IConfigurableTransport } from '@robota-sdk/agent-interface-transport';
+
+import type { IProtocolSession } from '@robota-sdk/agent-transport';
+
+import { createChannelDelivery } from './channel-delivery.js';
+import { whenRemoteCertificateVerified } from './negotiated-certificate.js';
+import { RtcPeer, type IRtcCandidate, type RtcChannel } from './rtc-peer.js';
+import { PairingGate } from './pairing-gate.js';
+import { createTransportLifecycleError } from './transport-lifecycle-error.js';
+import { WebRtcDeliveryLifecycle } from './webrtc-delivery-lifecycle.js';
+import type { IWebRtcTransportOptions } from './webrtc-transport-options.js';
+
+/** Frames a peer may send before the gate exists; the pairing handshake needs only a few. */
+const MAX_PENDING_FRAMES = 16;
+/** Local ICE candidates held until the offer is out. */
+const MAX_PENDING_CANDIDATES = 64;
+
+/**
+ * WebRTC P2P transport (REMOTE-001/002): carries an `IProtocolSession` over an `RTCDataChannel` using the
+ * SAME transport-neutral session bridge as the WebSocket transport (`createSessionMessageHandler` from
+ * `@robota-sdk/agent-transport`). The host is the offerer: it creates the data channel + offer and wires the
+ * channel as soon as it is created. `defaultEnabled: false` — nothing starts it automatically. Admission is
+ * fixed at construction: a pairing `secret` gates the session behind the pairing handshake, and running
+ * without one requires `open: true` with an `openReason`. The signaling client is injected and can be an
+ * in-memory loopback for tests.
+ */
+export class WebRtcTransport implements IConfigurableTransport<IProtocolSession> {
+  public readonly name = 'webrtc';
+  public readonly lifecycle = Object.freeze({ kind: 'service' as const });
+  public readonly defaultEnabled = false;
+  public readonly optionsSchema = {} as const;
+
+  private session?: IProtocolSession;
+  private peer?: RtcPeer;
+  private unsubscribeSignal?: () => void;
+  private cleanupHandler?: () => void;
+  /** Invalidates pending async startup work and scopes pairing/drop state to one start generation. */
+  private generation = 0;
+  /** Local DTLS fingerprint captured for pairing channel binding. */
+  private localFingerprint?: string;
+  /** Pairing gate for the current channel. */
+  private pairingGate?: PairingGate;
+  /** Whether this start generation has sent its offer; local candidates wait for it. */
+  private offerSent = false;
+  private localCandidates: IRtcCandidate[] = [];
+  /** Whether this start generation has taken its one answer; any later answer is ignored. */
+  private answered = false;
+  /** Pre-gate channel frames, replayed into the gate once it exists. Bounded. */
+  private pendingFrames: string[] = [];
+  private stopAwaitingCertificate?: () => void;
+  private readonly deliveryLifecycle: WebRtcDeliveryLifecycle;
+
+  public constructor(private readonly options: IWebRtcTransportOptions) {
+    this.deliveryLifecycle = new WebRtcDeliveryLifecycle({
+      cleanup: () => {
+        this.cleanupHandler?.();
+        this.pairingGate?.cleanup();
+      },
+      onDropped: () => this.options.onDropped?.(),
+      onDeliveryError: (error, event) => this.options.onDeliveryError?.(error, event),
+    });
+    // A pairing secret and explicit open admission are contradictory, so fail before signaling.
+    if (this.options.secret && this.options.open === true) {
+      throw new Error(
+        'WebRtcTransport: `secret` and `open: true` are contradictory. A pairing secret gates the ' +
+          'data channel; `open` runs without a gate. Pass one.',
+      );
+    }
+    if (this.options.secret === undefined || this.options.secret === '') {
+      if (this.options.open !== true) {
+        throw new Error(
+          'WebRtcTransport: no pairing `secret` and no explicit `open`. Pass a `secret` to gate the ' +
+            'data channel, or `{ open: true, openReason: "…" }` to run without pairing on purpose.',
+        );
+      }
+      // WebRTC has no bearer credential; use the shared seam only to validate the open reason.
+      void resolveAdmission({
+        open: true,
+        ...(this.options.openReason !== undefined ? { openReason: this.options.openReason } : {}),
+      });
+    }
+  }
+
+  public validateOptions(): boolean {
+    return true;
+  }
+
+  public attach(session: IProtocolSession): void {
+    this.session = session;
+  }
+  private createPeer(): RtcPeer {
+    return new RtcPeer({
+      ...(this.options.iceServers ? { iceServers: this.options.iceServers } : {}),
+      ...(this.options.forceTurn ? { forceTurn: true } : {}),
+      ...(this.options.loadDataChannel ? { loadDataChannel: this.options.loadDataChannel } : {}),
+    });
+  }
+
+  private wireSignaling(
+    peer: RtcPeer,
+    channel: RtcChannel,
+    session: IProtocolSession,
+    generation: number,
+  ): void {
+    const signaling = this.options.signaling;
+    peer.onLocalCandidate((candidate) => {
+      if (generation !== this.generation || peer !== this.peer) return;
+      // A candidate can be gathered before the offer is out; it follows the offer, never precedes it.
+      if (this.offerSent) this.sendCandidate(candidate);
+      else if (this.localCandidates.length < MAX_PENDING_CANDIDATES)
+        this.localCandidates.push(candidate);
+    });
+    let signalChain: Promise<void> = Promise.resolve();
+    this.unsubscribeSignal = signaling.onSignal((message) => {
+      if (generation !== this.generation) return;
+      signalChain = signalChain
+        .then(async () => {
+          if (generation !== this.generation || peer !== this.peer) return;
+          if (message.kind === 'answer') {
+            // One answer per start: the one fingerprint checked is the one the binding names.
+            if (this.answered) return;
+            this.answered = true;
+            const algorithm = this.remoteFingerprintAlgorithm(channel, message.data);
+            if (this.options.secret && algorithm === undefined) return;
+            const sdp = (message.data as { sdp?: unknown } | null)?.sdp;
+            if (typeof sdp !== 'string') return;
+            peer.acceptAnswer(sdp);
+            if (algorithm !== undefined)
+              this.awaitVerifiedCertificate(peer, channel, session, algorithm, generation);
+          } else if (message.kind === 'ice') {
+            const candidate = toRemoteCandidate(message.data);
+            if (candidate !== undefined) peer.addRemoteCandidate(candidate);
+          }
+        })
+        .catch(() => {
+          // A description the connection refuses ends this start, never with an unhandled rejection.
+          if (generation === this.generation) this.failPairing(channel);
+        });
+    });
+  }
+
+  private sendCandidate(candidate: IRtcCandidate): void {
+    this.options.signaling.send({
+      kind: 'ice',
+      data: { candidate: candidate.candidate, sdpMid: candidate.mid, sdpMLineIndex: 0 },
+    });
+  }
+
+  private requireCurrentPeer(peer: RtcPeer, generation: number): void {
+    if (generation === this.generation && this.peer === peer) return;
+    peer.close();
+    throw new Error('WebRtcTransport startup was stopped.');
+  }
+
+  public async start(): Promise<void> {
+    const session = this.session;
+    if (!session) throw createTransportLifecycleError('not-attached');
+    if (this.peer) throw createTransportLifecycleError('already-started');
+    const generation = ++this.generation;
+    this.deliveryLifecycle.reset(generation);
+    this.answered = false;
+    this.offerSent = false;
+    this.localCandidates = [];
+    this.pendingFrames = [];
+
+    const peer = this.createPeer();
+    this.peer = peer;
+    const signaling = this.options.signaling;
+    const channel = peer.createDataChannel('agent-session');
+    this.wireChannel(channel, session, generation);
+    this.wireSignaling(peer, channel, session, generation);
+
+    const sdp = await peer.createOffer();
+    this.requireCurrentPeer(peer, generation);
+    // Capture the local DTLS fingerprint for the pairing channel-binding (offer SDP).
+    if (this.options.secret) this.localFingerprint = extractDtlsFingerprint(sdp);
+    signaling.send({ kind: 'offer', data: { type: 'offer', sdp } });
+    this.offerSent = true;
+    for (const candidate of this.localCandidates.splice(0)) this.sendCandidate(candidate);
+  }
+
+  /**
+   * With a pairing secret, the answer must advertise exactly one DTLS fingerprint; its algorithm is the one the
+   * verified certificate is hashed with. A refused answer fails pairing and closes the channel.
+   */
+  private remoteFingerprintAlgorithm(channel: RtcChannel, answer: unknown): string | undefined {
+    if (!this.options.secret) return undefined;
+    const sdp = (answer as { sdp?: unknown }).sdp;
+    try {
+      if (typeof sdp !== 'string') throw new Error('answer carries no SDP');
+      return extractDtlsFingerprintAttribute(sdp).algorithm;
+    } catch {
+      this.failPairing(channel);
+      return undefined;
+    }
+  }
+
+  private failPairing(channel: RtcChannel): void {
+    channel.close();
+    this.options.onPairingFailed?.();
+  }
+
+  /** Build the pairing gate once the DTLS layer has verified the remote certificate. */
+  private awaitVerifiedCertificate(
+    peer: RtcPeer,
+    channel: RtcChannel,
+    session: IProtocolSession,
+    algorithm: string,
+    generation: number,
+  ): void {
+    this.stopAwaitingCertificate = whenRemoteCertificateVerified(
+      peer,
+      algorithm,
+      (remoteFingerprint) => {
+        if (generation !== this.generation) return;
+        // The gate speaks first, so it starts once the channel can carry its frame.
+        if (channel.readyState === 'open') {
+          this.startPairing(channel, session, remoteFingerprint, generation);
+          return;
+        }
+        const unsubscribe = channel.onStateChange((state) => {
+          if (state !== 'open' || generation !== this.generation) return;
+          unsubscribe();
+          this.startPairing(channel, session, remoteFingerprint, generation);
+        });
+      },
+      () => {
+        if (generation === this.generation) this.failPairing(channel);
+      },
+    );
+  }
+
+  private startPairing(
+    channel: RtcChannel,
+    session: IProtocolSession,
+    remoteFingerprint: string,
+    generation: number,
+  ): void {
+    const secret = this.options.secret;
+    if (!secret || !this.localFingerprint) return;
+    this.pairingGate = new PairingGate({
+      cryptoContext: this.options.cryptoContext,
+      channel: { send: (d) => channel.send(d), close: () => channel.close() },
+      session,
+      secret,
+      role: 'initiator',
+      localFingerprint: this.localFingerprint,
+      remoteFingerprint,
+      onAccept: (result) => {
+        if (generation !== this.generation) return;
+        this.deliveryLifecycle.accept(generation);
+        this.options.onPaired?.(result);
+      },
+      ...(this.options.onPairingFailed ? { onReject: this.options.onPairingFailed } : {}),
+      ...(this.options.reconnect ? { reconnect: this.options.reconnect } : {}),
+      ...(this.options.localPeer ? { localPeer: this.options.localPeer } : {}),
+      ...(this.options.connectionApproval
+        ? { connectionApproval: this.options.connectionApproval }
+        : {}),
+      ...(this.options.resumeBridge ? { resumeBridge: this.options.resumeBridge } : {}),
+      ...(this.options.personalUsageReporter
+        ? { personalUsageReporter: this.options.personalUsageReporter }
+        : {}),
+      ...(this.options.usageReporter ? { usageReporter: this.options.usageReporter } : {}),
+      ...(this.options.storedSessionUsageReporter
+        ? { storedSessionUsageReporter: this.options.storedSessionUsageReporter }
+        : {}),
+      surface: 'remote',
+      // #3282 §4 part b-2: WebRTC proves no locality; installing a plugin refuses it.
+      commandSurfaceLocality: 'remote',
+      onDeliveryError: (error, event) =>
+        this.deliveryLifecycle.handleFailure(channel, generation, error, event),
+    });
+    const gate = this.pairingGate;
+    for (const frame of this.pendingFrames.splice(0)) gate.onInbound(frame);
+  }
+
+  private wireChannel(channel: RtcChannel, session: IProtocolSession, generation: number): void {
+    // Subscribe eagerly: a remote's first frame is not buffered before a listener exists.
+    // With a secret the gate keeps pre-accept non-pairing frames from the session; otherwise the session is exposed directly.
+    if (this.options.secret) {
+      channel.onMessage((frame) => {
+        if (generation !== this.generation) return;
+        if (this.pairingGate) this.pairingGate.onInbound(frame);
+        else if (this.pendingFrames.length < MAX_PENDING_FRAMES) this.pendingFrames.push(frame);
+      });
+      // A post-accept close detaches the resume bridge and starts reconnect without ending the session.
+      channel.onStateChange((state) => {
+        if (generation !== this.generation) return;
+        if (state === 'closed') {
+          // Before acceptance the gate must hear it too: a question still open with the operator is
+          // about a connection that no longer exists.
+          this.pairingGate?.onChannelClosed();
+          this.deliveryLifecycle.handleDrop(generation);
+        }
+      });
+      this.cleanupHandler = () => this.pairingGate?.cleanup();
+      return;
+    }
+
+    // ARCH-030: the transport is the carrier on the no-secret branch — its own sink, its own lifecycle.
+    const { onMessage, cleanup } = createSessionMessageHandler({
+      session,
+      deliver: createChannelDelivery(channel, (error, event) =>
+        this.deliveryLifecycle.handleFailure(channel, generation, error, event),
+      ),
+      ...(this.options.personalUsageReporter
+        ? { personalUsageReporter: this.options.personalUsageReporter }
+        : {}),
+      ...(this.options.usageReporter ? { usageReporter: this.options.usageReporter } : {}),
+      ...(this.options.storedSessionUsageReporter
+        ? { storedSessionUsageReporter: this.options.storedSessionUsageReporter }
+        : {}),
+      surface: 'remote',
+      // #3282 §4 part b-2: WebRTC proves no locality; installing a plugin refuses it.
+      commandSurfaceLocality: 'remote',
+      // A data channel carries a fraction of the inbound limit (see the pairing-gate branch).
+      maxFrameBytes: HISTORY_PAGE_MAX_BYTES,
+    });
+    this.cleanupHandler = cleanup;
+    channel.onMessage((frame) => {
+      if (generation !== this.generation) return;
+      onMessage(frame);
+    });
+  }
+
+  public async stop(): Promise<void> {
+    this.generation += 1;
+    this.cleanupHandler?.();
+    this.unsubscribeSignal?.();
+    this.cleanupHandler = undefined;
+    this.unsubscribeSignal = undefined;
+    this.pairingGate = undefined;
+    this.localFingerprint = undefined;
+    this.answered = false;
+    this.offerSent = false;
+    this.localCandidates = [];
+    this.pendingFrames = [];
+    this.stopAwaitingCertificate?.();
+    this.stopAwaitingCertificate = undefined;
+    this.deliveryLifecycle.reset(this.generation);
+    if (this.peer) {
+      this.peer.close();
+      this.peer = undefined;
+    }
+    this.session = undefined;
+  }
+}
+
+/** A remote ICE candidate as a browser sends it (`RTCIceCandidateInit`), or `undefined` for none. */
+function toRemoteCandidate(data: unknown): { candidate: string; mid: string } | undefined {
+  if (typeof data !== 'object' || data === null) return undefined;
+  const record = data as { candidate?: unknown; sdpMid?: unknown; sdpMLineIndex?: unknown };
+  if (typeof record.candidate !== 'string' || record.candidate.length === 0) return undefined;
+  const mid =
+    typeof record.sdpMid === 'string'
+      ? record.sdpMid
+      : typeof record.sdpMLineIndex === 'number'
+        ? String(record.sdpMLineIndex)
+        : '0';
+  return { candidate: record.candidate, mid };
+}

package/src/ws-mesh-relay-client.ts

@@ -0,0 +1,117 @@
+/**
+ * {@link IMeshRelay} over a WebSocket to the self-hosted signaling relay's `presence` / `message`
+ * frames.
+ *
+ * Frames sent before the socket opens are queued and flushed after the presence declaration, so a
+ * message is never sent from a connection the relay does not yet consider present. A refusal from the
+ * relay, a socket error, or a close the caller did not ask for goes to `onError` — never a silent
+ * degrade.
+ */
+import WebSocket from 'ws';
+
+import type { IMeshRelay } from './mesh-relay.js';
+import type { IWebSocketLike } from './ws-signaling-client.js';
+
+export interface IWsMeshRelayClientOptions {
+  /** Relay URL, e.g. `wss://relay.example`. */
+  readonly url: string;
+  readonly onError?: (error: Error) => void;
+  /** Called each time the relay confirms a presence declaration. */
+  readonly onPresent?: () => void;
+  /** Injectable socket factory (defaults to a real `ws` WebSocket) — for tests. */
+  readonly createSocket?: (url: string) => IWebSocketLike;
+}
+
+const WS_OPEN = 1;
+/** Messages queued before the socket opens; a connection attempt has a handful. */
+const MAX_OUTBOX = 256;
+
+export class WsMeshRelayClient implements IMeshRelay {
+  private readonly socket: IWebSocketLike;
+  private readonly messages = new Set<(topic: string, data: unknown) => void>();
+  private readonly absents = new Set<(topic: string) => void>();
+  private readonly outbox: string[] = [];
+  private topics: readonly string[] | undefined;
+  private closed = false;
+
+  public constructor(private readonly options: IWsMeshRelayClientOptions) {
+    const factory =
+      options.createSocket ?? ((url: string) => new WebSocket(url) as unknown as IWebSocketLike);
+    this.socket = factory(options.url);
+    this.socket.on('open', () => this.flush());
+    this.socket.on('message', (data) => this.receive(data));
+    this.socket.on('error', (error) =>
+      this.options.onError?.(error instanceof Error ? error : new Error(String(error))),
+    );
+    this.socket.on('close', () => {
+      if (!this.closed) this.options.onError?.(new Error('signaling relay connection closed'));
+    });
+  }
+
+  private flush(): void {
+    if (this.topics !== undefined) this.write({ type: 'presence', topics: this.topics });
+    for (const raw of this.outbox.splice(0)) this.socket.send(raw);
+  }
+
+  private write(frame: unknown): void {
+    this.socket.send(JSON.stringify(frame));
+  }
+
+  private receive(data: unknown): void {
+    let frame: unknown;
+    try {
+      frame = JSON.parse(typeof data === 'string' ? data : String(data));
+    } catch {
+      return; // the relay only emits JSON
+    }
+    if (typeof frame !== 'object' || frame === null) return;
+    const record = frame as Record<string, unknown>;
+    if (record.type === 'message' && typeof record.topic === 'string') {
+      for (const handler of this.messages) handler(record.topic, record.data);
+    } else if (record.type === 'absent' && typeof record.topic === 'string') {
+      for (const handler of this.absents) handler(record.topic);
+    } else if (record.type === 'present') {
+      this.options.onPresent?.();
+    } else if (record.type === 'error') {
+      this.options.onError?.(
+        new Error(`signaling relay refused a frame: ${String(record.reason)}`),
+      );
+    }
+  }
+
+  public declarePresence(topics: readonly string[]): void {
+    if (this.closed) return;
+    this.topics = [...topics];
+    if (this.socket.readyState === WS_OPEN) this.write({ type: 'presence', topics: this.topics });
+  }
+
+  public send(topic: string, data: unknown): void {
+    if (this.closed) return;
+    const raw = JSON.stringify({ type: 'message', topic, data });
+    if (this.socket.readyState === WS_OPEN) {
+      this.socket.send(raw);
+    } else if (this.outbox.length < MAX_OUTBOX) {
+      this.outbox.push(raw);
+    } else {
+      this.options.onError?.(new Error('signaling relay is not reachable; message dropped'));
+    }
+  }
+
+  public onMessage(handler: (topic: string, data: unknown) => void): () => void {
+    this.messages.add(handler);
+    return () => this.messages.delete(handler);
+  }
+
+  public onAbsent(handler: (topic: string) => void): () => void {
+    this.absents.add(handler);
+    return () => this.absents.delete(handler);
+  }
+
+  public close(): void {
+    this.closed = true;
+    this.messages.clear();
+    this.absents.clear();
+    this.outbox.length = 0;
+    this.socket.close();
+  }
+}