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

package/src/webrtc-delivery-lifecycle.ts

@@ -0,0 +1,51 @@
+import type { RTCDataChannel } from 'werift';
+
+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: RTCDataChannel, 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,84 @@
+/**
+ * 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 { IWeriftModule } from './werift-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 (werift) transport (REMOTE-010). `urls` is a SINGLE string with a
+ * `turn:`/`turns:`/`stun:`/`stuns:` scheme — werift's ICE gatherer (`parseIceServers`) consumes only a single-string
+ * url and silently drops array `urls`, so the host reader (`agent-cli` `parseIceServers`) must narrow to this shape
+ * and reject what werift would drop (fail-closed). (The browser peer uses the native DOM `RTCIceServer`, which does
+ * support array urls / `turns:` — a separate, wider validator.) 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 (Stage A: no settings). */
+export interface IWebRtcTransportOptions {
+  /** 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 — and the local-interface gathering that touches the (unreachable, but
+   * belt-and-braces) `ip` code path — are never used. Requires a TURN server in `iceServers`. Mapped to werift's
+   * `iceTransportPolicy: 'relay'` (REMOTE-010) — werift IGNORES a top-level `forceTurn`, so it must NOT be passed.
+   */
+  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 (Stage-A loopback / tests), the channel is
+   * exposed immediately with no pairing (unchanged behavior).
+   */
+  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 werift module (defaults to the real lazy loader). */
+  readonly loadWerift?: () => IWeriftModule;
+}

package/src/webrtc-transport.ts

@@ -0,0 +1,328 @@
+import { 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 { RTCDataChannel, RTCPeerConnection } from 'werift';
+
+import type { IProtocolSession } from '@robota-sdk/agent-transport';
+
+import { createChannelDelivery } from './channel-delivery.js';
+import { whenRemoteCertificateVerified } from './negotiated-certificate.js';
+import { loadWerift } from './werift-loader.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;
+
+/**
+ * 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 on
+ * data-channel open wires the handler. **Stage A: `defaultEnabled: false`, no pairing/auth** — 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?: RTCPeerConnection;
+  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 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(): RTCPeerConnection {
+    const { RTCPeerConnection } = (this.options.loadWerift ?? loadWerift)();
+    const config: {
+      iceServers?: { urls: string; username?: string; credential?: string }[];
+      iceTransportPolicy?: 'all' | 'relay';
+    } = {};
+    if (this.options.iceServers)
+      config.iceServers = this.options.iceServers.map((server) => ({ ...server }));
+    if (this.options.forceTurn) config.iceTransportPolicy = 'relay';
+    return new RTCPeerConnection(Object.keys(config).length > 0 ? config : undefined);
+  }
+
+  private wireSignaling(
+    peer: RTCPeerConnection,
+    channel: RTCDataChannel,
+    session: IProtocolSession,
+    generation: number,
+  ): void {
+    const signaling = this.options.signaling;
+    peer.onIceCandidate.subscribe((candidate) => {
+      if (candidate && generation === this.generation && peer === this.peer) {
+        signaling.send({ kind: 'ice', data: candidate.toJSON() });
+      }
+    });
+    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. A later answer would add fingerprints the DTLS layer then also accepts.
+          if (this.answered) return;
+          this.answered = true;
+          const algorithm = this.remoteFingerprintAlgorithm(channel, message.data);
+          if (this.options.secret && algorithm === undefined) return;
+          await peer.setRemoteDescription(
+            message.data as Parameters<typeof peer.setRemoteDescription>[0],
+          );
+          if (algorithm !== undefined)
+            this.awaitVerifiedCertificate(peer, channel, session, algorithm, generation);
+        } else if (message.kind === 'ice') {
+          await peer.addIceCandidate(message.data as Parameters<typeof peer.addIceCandidate>[0]);
+        }
+      });
+    });
+  }
+
+  private async requireCurrentPeer(peer: RTCPeerConnection, generation: number): Promise<void> {
+    if (generation === this.generation && this.peer === peer) return;
+    await 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.pendingFrames = [];
+
+    const peer = this.createPeer();
+    this.peer = peer;
+    const signaling = this.options.signaling;
+    const channel = peer.createDataChannel('robota-session');
+    this.wireChannel(channel, session, generation);
+    this.wireSignaling(peer, channel, session, generation);
+
+    const offer = await peer.createOffer();
+    await this.requireCurrentPeer(peer, generation);
+    await peer.setLocalDescription(offer);
+    await this.requireCurrentPeer(peer, generation);
+    // Capture the local DTLS fingerprint for the pairing channel-binding (offer SDP).
+    if (this.options.secret && peer.localDescription) {
+      this.localFingerprint = extractDtlsFingerprint(peer.localDescription.sdp);
+    }
+    signaling.send({ kind: 'offer', data: peer.localDescription });
+  }
+
+  /**
+   * 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: RTCDataChannel, 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: RTCDataChannel): void {
+    try {
+      void channel.close();
+    } catch {
+      /* already closing */
+    }
+    this.options.onPairingFailed?.();
+  }
+
+  /** Build the pairing gate once the DTLS layer has verified the remote certificate. */
+  private awaitVerifiedCertificate(
+    peer: RTCPeerConnection,
+    channel: RTCDataChannel,
+    session: IProtocolSession,
+    algorithm: string,
+    generation: number,
+  ): void {
+    this.stopAwaitingCertificate = whenRemoteCertificateVerified(
+      peer,
+      algorithm,
+      (remoteFingerprint) => {
+        if (generation !== this.generation) return;
+        this.startPairing(channel, session, remoteFingerprint, generation);
+      },
+      () => {
+        if (generation === this.generation) this.failPairing(channel);
+      },
+    );
+  }
+
+  private startPairing(
+    channel: RTCDataChannel,
+    session: IProtocolSession,
+    remoteFingerprint: string,
+    generation: number,
+  ): void {
+    const secret = this.options.secret;
+    if (!secret || !this.localFingerprint) return;
+    this.pairingGate = new PairingGate({
+      channel: { send: (d) => channel.send(d), close: () => void 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',
+      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: RTCDataChannel,
+    session: IProtocolSession,
+    generation: number,
+  ): void {
+    // Subscribe eagerly: werift does not buffer a remote's first frame before a listener exists.
+    // With a secret the gate drops pre-accept non-pairing frames; otherwise the session is exposed directly.
+    if (this.options.secret) {
+      channel.onMessage.subscribe((data) => {
+        if (generation !== this.generation) return;
+        const frame = typeof data === 'string' ? data : data.toString();
+        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.stateChanged.subscribe((state) => {
+        if (generation !== this.generation) return;
+        if (state === 'closed' || state === 'closing') {
+          // 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',
+    });
+    this.cleanupHandler = cleanup;
+    channel.onMessage.subscribe((data) => {
+      if (generation !== this.generation) return;
+      onMessage(typeof data === 'string' ? data : data.toString());
+    });
+  }
+
+  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.pendingFrames = [];
+    this.stopAwaitingCertificate?.();
+    this.stopAwaitingCertificate = undefined;
+    this.deliveryLifecycle.reset(this.generation);
+    if (this.peer) {
+      await this.peer.close();
+      this.peer = undefined;
+    }
+    this.session = undefined;
+  }
+}

package/src/werift-loader.ts

@@ -0,0 +1,40 @@
+import { createRequire } from 'node:module';
+
+import type { RTCPeerConnection } from 'werift';
+
+/** The subset of the `werift` module surface this transport constructs. */
+export interface IWeriftModule {
+  RTCPeerConnection: new (configuration?: {
+    // REMOTE-010: werift's ICE gatherer consumes only a SINGLE-string `urls` (array urls / `turns:` are silently
+    // dropped by its `parseIceServers`); TURN servers carry username/credential. Relay-only comes from
+    // `iceTransportPolicy:'relay'` — werift IGNORES a top-level `forceTurn`, so this type must NOT declare it.
+    iceServers?: { urls: string; username?: string; credential?: string }[];
+    iceTransportPolicy?: 'all' | 'relay';
+  }) => RTCPeerConnection;
+}
+
+/**
+ * Lazily load the optional `werift` (pure-TypeScript WebRTC) peer dependency (REMOTE-002). `werift` is kept
+ * OUT of the transport's runtime dependency graph (peer + optional) so this package is importable without it;
+ * absence surfaces an **explicit "WebRTC transport unavailable" error at point-of-use** (a throw, mirroring
+ * `agent-cli`'s `loadReplayProvider`) — never a silent no-op or degraded path (no-fallback rule). The
+ * werift-vs-native choice is a recorded design decision, not a runtime fallback.
+ */
+/** Resolve a module by id. The default resolves the real `werift`; tests inject a throwing resolver. */
+export type TModuleResolver = (id: string) => unknown;
+
+const defaultResolver: TModuleResolver = (id) => {
+  const requireFrom = createRequire(import.meta.url);
+  // eslint-disable-next-line @typescript-eslint/no-require-imports -- optional peer; must resolve at runtime, not bundle
+  return requireFrom(id);
+};
+
+export function loadWerift(resolve: TModuleResolver = defaultResolver): IWeriftModule {
+  try {
+    return resolve('werift') as IWeriftModule;
+  } catch {
+    throw new Error(
+      'WebRTC transport unavailable — install the optional peer dependency "werift" to use @robota-sdk/agent-transport-webrtc.',
+    );
+  }
+}

package/src/ws-signaling-client.ts

@@ -0,0 +1,139 @@
+/**
+ * Production `ISignalingClient` over a WebSocket connection to the `@robota-sdk/remote-signaling` relay
+ * (REMOTE-004 Stage B2). This is the **Node host-side** client (the browser remote client, Stage D, implements
+ * `ISignalingClient` on the native `WebSocket`).
+ *
+ * On open it `join`s the rendezvous and flushes any signals produced before the socket opened (the offer is
+ * created in `WebRtcTransport.start()`, which can run before the socket connects — buffering avoids dropping it).
+ * Relay `error` frames, socket errors, and a close-before-join are surfaced through an explicit `onError`
+ * callback — **never a silent degrade** (no-fallback, mirroring `loadReplayProvider`/`loadWerift`). The relay is
+ * content-blind: this client only ever emits `join` + `signal` frames and only ever consumes `joined` / `signal`
+ * / `error` frames.
+ */
+import WebSocket from 'ws';
+
+import type { ISignalingClient, ISignalMessage, TSignalKind } from './signaling.js';
+
+/** A minimal WebSocket-like surface — so tests can inject a fake without a real socket. */
+export interface IWebSocketLike {
+  send(data: string): void;
+  close(): void;
+  readyState: number;
+  on(event: 'open' | 'message' | 'error' | 'close', handler: (arg: unknown) => void): void;
+}
+
+export interface IWsSignalingClientOptions {
+  /** Relay URL, e.g. `ws://127.0.0.1:1234`. */
+  readonly url: string;
+  /** Rendezvous id to join. */
+  readonly rendezvous: string;
+  /**
+   * Explicit error sink. Called on a relay `error` frame, a socket error, or a close-before-join — the signaling
+   * channel cannot function and the caller must know (no silent degrade).
+   */
+  readonly onError?: (error: Error) => void;
+  /** Called once the relay confirms the rendezvous `join` (the `joined` frame). */
+  readonly onReady?: () => void;
+  /** Injectable socket factory (defaults to a real `ws` WebSocket) — for tests. */
+  readonly createSocket?: (url: string) => IWebSocketLike;
+}
+
+const SIGNAL_KINDS: ReadonlySet<string> = new Set<TSignalKind>(['offer', 'answer', 'ice']);
+const WS_OPEN = 1;
+
+function defaultCreateSocket(url: string): IWebSocketLike {
+  return new WebSocket(url) as unknown as IWebSocketLike;
+}
+
+export class WsSignalingClient implements ISignalingClient {
+  private readonly socket: IWebSocketLike;
+  private readonly handlers: ((message: ISignalMessage) => void)[] = [];
+  private readonly outbox: ISignalMessage[] = [];
+  private joined = false;
+  private closed = false;
+
+  public constructor(private readonly options: IWsSignalingClientOptions) {
+    const factory = options.createSocket ?? defaultCreateSocket;
+    this.socket = factory(options.url);
+    this.socket.on('open', () => this.handleOpen());
+    this.socket.on('message', (data) => this.handleMessage(data));
+    this.socket.on('error', (err) =>
+      this.fail(err instanceof Error ? err : new Error(String(err))),
+    );
+    this.socket.on('close', () => this.handleClose());
+  }
+
+  private handleOpen(): void {
+    this.socket.send(JSON.stringify({ type: 'join', rendezvous: this.options.rendezvous }));
+    // Flush any signals produced before the socket opened (e.g. the offer from WebRtcTransport.start()).
+    for (const message of this.outbox) this.writeSignal(message);
+    this.outbox.length = 0;
+  }
+
+  private handleMessage(data: unknown): void {
+    let frame: unknown;
+    try {
+      frame = JSON.parse(typeof data === 'string' ? data : String(data));
+    } catch {
+      return; // a non-JSON frame from the relay is ignored (the relay only emits JSON)
+    }
+    if (typeof frame !== 'object' || frame === null) return;
+    const record = frame as Record<string, unknown>;
+    if (record.type === 'joined') {
+      this.joined = true;
+      this.options.onReady?.();
+      return;
+    }
+    if (record.type === 'error') {
+      this.fail(new Error(`signaling relay rejected the connection: ${String(record.reason)}`));
+      return;
+    }
+    if (
+      record.type === 'signal' &&
+      typeof record.kind === 'string' &&
+      SIGNAL_KINDS.has(record.kind)
+    ) {
+      const message: ISignalMessage = { kind: record.kind as TSignalKind, data: record.data };
+      for (const handler of this.handlers) handler(message);
+    }
+  }
+
+  private handleClose(): void {
+    if (this.closed) return; // an intentional close() is not an error
+    if (!this.joined) {
+      this.fail(new Error('signaling socket closed before the rendezvous was joined'));
+    }
+  }
+
+  private fail(error: Error): void {
+    this.options.onError?.(error);
+  }
+
+  private writeSignal(message: ISignalMessage): void {
+    this.socket.send(JSON.stringify({ type: 'signal', kind: message.kind, data: message.data }));
+  }
+
+  public send(message: ISignalMessage): void {
+    if (this.closed) return;
+    if (this.socket.readyState === WS_OPEN) {
+      this.writeSignal(message);
+    } else {
+      this.outbox.push(message); // buffer until open (see handleOpen)
+    }
+  }
+
+  public onSignal(handler: (message: ISignalMessage) => void): () => void {
+    this.handlers.push(handler);
+    return () => {
+      const index = this.handlers.indexOf(handler);
+      if (index >= 0) this.handlers.splice(index, 1);
+    };
+  }
+
+  public close(): void {
+    this.closed = true;
+    this.handlers.length = 0;
+    this.outbox.length = 0;
+    this.socket.close();
+  }
+}