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

package/src/pairing-gate-options.ts

@@ -0,0 +1,129 @@
+/**
+ * The contract a `PairingGate` is constructed with (REMOTE-008 / -012 / -013, SEC-010, SEC-011).
+ *
+ * Separated from the gate itself because they are different responsibilities: this file says what a
+ * caller must supply, and `pairing-gate.ts` says what the machine does with it. Keeping them
+ * together made one file that had to be read in full to answer either question.
+ *
+ * Re-exported from `pairing-gate.ts`, so every existing import keeps working — the split is a
+ * reading change, not a migration.
+ */
+
+import type {
+  IPairingResult,
+  startPairingHandshake,
+  TPairingRole,
+} from '@robota-sdk/agent-remote-pairing';
+import type {
+  IProtocolSession,
+  ISessionMessageHandlerOptions,
+  SessionResumeBridge,
+  createSessionMessageHandler,
+} from '@robota-sdk/agent-transport';
+
+import type { IHandoffGrantProof } from './handoff-grant-gate.js';
+import type { ILocalPeerProof } from './local-peer-proof.js';
+
+/** The minimal data-channel surface the gate drives (a werift `RTCDataChannel` satisfies it). */
+export interface IPairingChannel {
+  send(data: string): void;
+  close(): void;
+  /**
+   * ARCH-030 / issue #1734: this channel's own count of what it has accepted and not yet written.
+   *
+   * Optional for the same reason `IDataChannelSink.bufferedAmount` is — the slice is structural and a
+   * test double may omit it — while a real `RTCDataChannel` always has it. It is here so the resume
+   * bridge's outbound boundary gets a reading: without one the replay path has no backpressure
+   * budget, which is a capability that exists and is never reached.
+   */
+  readonly bufferedAmount?: number;
+}
+
+/** E3 host reconnect/enrollment config. When present, the gate runs reactive (first-frame) mode detection. */
+export interface IHostReconnectConfig {
+  readonly hostIdentityId: string;
+  /** base64url SPKI advertised to a device at first-pair enrollment. */
+  readonly hostPublicSpki: string;
+  /** The host identity private key (signs reconnect challenges). */
+  readonly hostPrivateKey: CryptoKey;
+  /** Resolve a pinned device public key by id (undefined → unknown/revoked → fail closed). */
+  readonly resolveDevicePublicKey: (deviceId: string) => Promise<CryptoKey | undefined>;
+  /** Pin a device's public key on first-pair enrollment (deviceId, base64url SPKI). */
+  readonly onEnroll: (deviceId: string, deviceSpki: string) => void;
+}
+
+/** What the receiving operator is told about a connection that would drive the session. */
+export interface IConnectionApprovalContext {
+  /** The device the handshake proved, when the carrier has a stable id for it. */
+  readonly deviceId?: string;
+  /** A trusted device coming back, rather than one pairing now. */
+  readonly viaReconnect: boolean;
+  /** Aborted when the connection goes away before an answer: withdraw the question. */
+  readonly signal: AbortSignal;
+}
+
+/**
+ * The receiving operator's say over one connection. `approve` resolves `true` only on the operator's
+ * explicit yes; `false` or a rejection refuses the connection.
+ */
+export interface IConnectionApproval {
+  approve(context: IConnectionApprovalContext): Promise<boolean>;
+}
+
+export interface IPairingGateOptions {
+  readonly channel: IPairingChannel;
+  readonly session: IProtocolSession;
+  readonly secret: string;
+  readonly role: TPairingRole;
+  readonly localFingerprint: string;
+  readonly remoteFingerprint: string;
+  /** Handshake timeout (ms); fail closed on expiry. */
+  readonly timeoutMs?: number;
+  /** REMOTE-008: fired once admission accepts + the session is exposed. Carries the first-pair result (E4). */
+  readonly onAccept?: (result?: IPairingResult) => void;
+  /** REMOTE-008: fired once admission rejects/times out + the channel closes (host lifecycle → teardown). */
+  readonly onReject?: () => void;
+  /** REMOTE-012 E3: host reconnect/enrollment config. Absent → B4 first-pair-only behavior (unchanged). */
+  readonly reconnect?: IHostReconnectConfig;
+  /**
+   * REMOTE-013 E4: a session-scoped {@link SessionResumeBridge}. When set, the paired session flows through the
+   * bridge (seq-stamped + buffered) instead of a fresh `createSessionMessageHandler`, so the session survives a channel
+   * drop and can replay on reconnect. Accept ATTACHES the channel as the bridge's sink; cleanup DETACHES it
+   * (never disposes — the bridge is owned by the transport across reconnects).
+   */
+  readonly resumeBridge?: SessionResumeBridge;
+  /** Host-owned usage read models exposed only after this gate accepts. */
+  readonly personalUsageReporter?: ISessionMessageHandlerOptions['personalUsageReporter'];
+  readonly usageReporter?: ISessionMessageHandlerOptions['usageReporter'];
+  readonly storedSessionUsageReporter?: ISessionMessageHandlerOptions['storedSessionUsageReporter'];
+  /** Trusted carrier-owned surface; WebRTC assigns `remote`. */
+  readonly surface?: ISessionMessageHandlerOptions['surface'];
+  /**
+   * Post-accept session-frame delivery failure; owning transport performs drop cleanup.
+   *
+   * ARCH-030: was `TServerMessage['type'] | string`, which is just `string` — a union that reads as a
+   * narrowing and is not one. Stated as what it is.
+   */
+  readonly onDeliveryError?: (error: Error, event: string) => void;
+  /** SEC-010: require a rendezvous nonce before exposing the session. Absent → unchanged behavior. */
+  readonly localPeer?: ILocalPeerProof;
+  /**
+   * SEC-011 (issue #1865): require a verified cross-device hand-off grant before exposing the
+   * session. Absent → unchanged behavior.
+   *
+   * Independent of `localPeer` rather than exclusive with it, and demanded AFTER it when both are
+   * set. They answer different questions — the rendezvous binds the environment, the grant binds the
+   * transfer — and a hand-off between two sessions on ONE machine legitimately has both. Requiring
+   * both is strictly more restrictive than requiring either, which is the safe direction.
+   */
+  readonly handoffGrant?: IHandoffGrantProof;
+  /**
+   * Ask the receiving operator before exposing the session, after every proof above has run. Absent →
+   * unchanged behavior. A device first pairing is not pinned for reconnect until the operator allows
+   * it, so a refused device is not remembered.
+   */
+  readonly connectionApproval?: IConnectionApproval;
+  /** Injection seams (default to the real implementations). */
+  readonly startHandshake?: typeof startPairingHandshake;
+  readonly createHandler?: typeof createSessionMessageHandler;
+}

package/src/pairing-gate.ts

@@ -0,0 +1,376 @@
+/**
+ * Pairing gate for the WebRTC data channel (REMOTE-008 Stage B4-2b; extended for REMOTE-012 Stage E3 TOFU
+ * reconnect).
+ *
+ * The data channel is phase-separated: pre-accept it carries pairing/reconnect frames, post-accept only
+ * session messages. An eager subscription feeds {@link PairingGate.onInbound}; the session bridge is not
+ * built until acceptance, so no pre-accept peer frame can reach the live session.
+ *
+ * E3 selects first-pair (`pair-nonce`, then identity-key enrollment) or reconnect (`rc-hello`, pinned
+ * identities) from the client's first frame and exposes the session only after mutual acceptance.
+ *
+ * Fail-closed: a non-admission frame pre-accept is DROPPED; the handshake `result` is the ONLY accept signal;
+ * on reject/timeout the channel is closed and no session bridge is ever created; a post-close frame is ignored.
+ *
+ * When no E3 `reconnect` config is supplied the gate is **exactly** the B4 first-pair-only gate (eager host
+ * `pair-nonce`, no enrollment, no reconnect) — preserving existing behavior.
+ *
+ * SEC-010 adds an optional `local-proof` step between handshake acceptance and session exposure; see
+ * `local-peer-proof.ts` for why both of those edges are load-bearing.
+ */
+
+import {
+  deriveIdentityId,
+  importPublicKey,
+  startPairingHandshake,
+  type IPairingResult,
+} from '@robota-sdk/agent-remote-pairing';
+
+import { nextAdmissionStep } from './admission-steps.js';
+import type {
+  IConnectionApproval,
+  IConnectionApprovalContext,
+  IHostReconnectConfig,
+  IPairingChannel,
+  IPairingGateOptions,
+} from './pairing-gate-options.js';
+
+// Re-exported so every existing import of these names keeps working: the split moved where they are
+// DECLARED, and moving where they are imported from would be a migration this change is not.
+export type {
+  IConnectionApproval,
+  IConnectionApprovalContext,
+  IHostReconnectConfig,
+  IPairingChannel,
+  IPairingGateOptions,
+};
+import { judgeHandoffGrant } from './handoff-grant-gate.js';
+import { judgeLocalProof } from './local-peer-proof.js';
+import { pairingChannel } from './pairing-channel-lifecycle.js';
+import { startFirstPairController, startReconnectController } from './pairing-controllers.js';
+import { isEnrollFrame, isPairingFrame, isReconnectFrame } from './pairing-frames.js';
+import { attachSession } from './session-attachment.js';
+
+import type { IEnrollFrame } from './pairing-frames.js';
+
+/** How much a peer may say while the operator decides: a client's opening requests, not a stream. */
+const HELD_FRAMES_MAX = 32;
+const HELD_CHARS_MAX = 256 * 1024;
+
+type TGateState =
+  | 'awaiting-mode'
+  | 'pairing'
+  | 'enrolling'
+  | 'reconnecting'
+  | 'local-proof'
+  | 'handoff-grant'
+  | 'operator-approval'
+  | 'accepted'
+  | 'closed';
+
+export class PairingGate {
+  private state: TGateState;
+  /** Session message router — built ONLY on accept (nothing reaches the session before). */
+  private onSessionMessage?: (data: string) => void;
+  private handlerCleanup?: () => void;
+  private pairingController?: ReturnType<typeof startPairingHandshake>;
+  private reconnectController?: ReturnType<typeof startReconnectController>;
+  /** The first-pair result, held so it can be surfaced on accept (E4 uses its sessionKey). */
+  private pendingResult?: IPairingResult;
+  /** Held across the local-proof step so the reconnect ordering rule survives the detour. */
+  private pendingViaReconnect = false;
+  /** The device the handshake proved, for the operator's question. */
+  private pendingDeviceId?: string;
+  /** A first-pair device key, pinned only once every step has admitted the channel. */
+  private pendingEnrollment?: { readonly deviceId: string; readonly spki: string };
+  /**
+   * Session frames the peer sent while the operator was deciding. The peer's own handshake has
+   * already accepted, so it starts talking (a resume, a history request) at once; dropping those
+   * would leave an approved device waiting on answers to questions the host never saw. They reach
+   * the session only after a yes, and a peer that sends more than a bounded amount is refused.
+   */
+  private heldFrames: string[] = [];
+  private heldChars = 0;
+  /** Withdraws the question put to the operator when the connection goes away first. */
+  private approvalAbort?: AbortController;
+
+  constructor(private readonly options: IPairingGateOptions) {
+    if (options.reconnect) {
+      // E3 mode: stay reactive — the client's first frame selects first-pair vs reconnect.
+      this.state = 'awaiting-mode';
+    } else {
+      // Legacy B4 mode: eagerly start the first-pair handshake (host sends pair-nonce immediately).
+      this.state = 'pairing';
+      this.startFirstPair();
+    }
+  }
+
+  /**
+   * Route one inbound channel frame. Pre-accept: admission frames → the active controller, everything else
+   * DROPPED. Post-accept: session messages → the session bridge. Post-close: ignored.
+   */
+  onInbound(data: string): void {
+    if (this.state === 'closed') return;
+    if (this.state === 'accepted') {
+      this.onSessionMessage?.(data);
+      return;
+    }
+    if (this.state === 'operator-approval') {
+      this.holdForApproval(data);
+      return;
+    }
+
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(data);
+    } catch {
+      return; // undecodable pre-accept frame → drop
+    }
+
+    if (this.state === 'awaiting-mode') {
+      // First frame selects the mode (E3).
+      if (isReconnectFrame(parsed) && parsed.t === 'rc-hello') {
+        this.state = 'reconnecting';
+        this.startReconnect();
+        this.reconnectController?.onFrame(parsed);
+      } else if (isPairingFrame(parsed) && parsed.t === 'pair-nonce') {
+        this.state = 'pairing';
+        this.startFirstPair();
+        this.pairingController?.onFrame(parsed);
+      }
+      // anything else pre-mode → drop
+      return;
+    }
+
+    if (this.state === 'pairing') {
+      if (isPairingFrame(parsed)) this.pairingController?.onFrame(parsed);
+      return;
+    }
+
+    if (this.state === 'reconnecting') {
+      if (isReconnectFrame(parsed)) this.reconnectController?.onFrame(parsed);
+      return;
+    }
+
+    if (this.state === 'local-proof') {
+      const admission = judgeLocalProof(parsed, this.options.localPeer);
+      this.options.localPeer?.onAdmission?.(admission);
+      if (admission.admitted) this.accept(this.pendingResult, this.pendingViaReconnect);
+      else this.rejectAndClose();
+      return;
+    }
+
+    if (this.state === 'handoff-grant') {
+      // Verifying a signature is async, and this handler is not. The promise is consumed here rather
+      // than returned so a rejection cannot escape into the channel's message subscription — an
+      // unhandled rejection would leave the gate parked in this state with the channel open, which
+      // is a hang. `judgeHandoffGrant` already converts a throw into a refusal; this is the second
+      // layer, because a gate that can hang is a gate that fails open by waiting.
+      void this.judgeGrantFrame(parsed);
+      return;
+    }
+
+    if (this.state === 'enrolling') {
+      // Awaiting the peer's identity public key to pin, then expose the session.
+      if (isEnrollFrame(parsed)) this.completeEnrollment(parsed.spki);
+      return;
+    }
+  }
+
+  /** Tear down: cleanup the session bridge (if built) and mark closed. Idempotent. */
+  cleanup(): void {
+    this.state = 'closed';
+    this.withdrawApproval();
+    this.handlerCleanup?.();
+    this.handlerCleanup = undefined;
+    this.onSessionMessage = undefined;
+  }
+
+  /**
+   * The channel closed. Before acceptance that is a refusal: nobody is left to admit, so a question
+   * still open with the operator is withdrawn and a later answer admits nothing. After acceptance the
+   * owning transport handles the drop.
+   */
+  onChannelClosed(): void {
+    if (this.state === 'accepted' || this.state === 'closed') return;
+    this.rejectAndClose();
+  }
+
+  private withdrawApproval(): void {
+    this.heldFrames = [];
+    this.heldChars = 0;
+    this.approvalAbort?.abort();
+    this.approvalAbort = undefined;
+  }
+
+  private startFirstPair(): void {
+    // `IPairingGateOptions` already carries every field `IControllerContext` asks for, so it is
+    // passed straight through — projecting it field by field would be a copy to keep in step.
+    this.pairingController = startFirstPairController(
+      this.options,
+      this.options.secret,
+      this.options.role,
+      (result) => this.onFirstPairAccepted(result),
+      () => this.rejectAndClose(),
+      this.options.startHandshake ?? startPairingHandshake,
+    );
+  }
+
+  private startReconnect(): void {
+    const cfg = this.options.reconnect;
+    if (!cfg) {
+      this.rejectAndClose();
+      return;
+    }
+    this.reconnectController = startReconnectController(
+      this.options,
+      cfg,
+      // reconnect → hold live forwarding until the client's resume replays
+      (result) => {
+        this.pendingDeviceId = result.deviceId;
+        this.accept(undefined, true);
+      },
+      () => this.rejectAndClose(),
+    );
+  }
+
+  /** B3 handshake accepted. Without E3: expose immediately. With E3: run first-pair enrollment first. */
+  private onFirstPairAccepted(result: IPairingResult): void {
+    if (this.state !== 'pairing') return;
+    this.pendingResult = result;
+    const cfg = this.options.reconnect;
+    if (!cfg) {
+      this.accept(result);
+      return;
+    }
+    // E3 enrollment: advertise the host public key; the peer's `enroll-key` completes it (then expose).
+    this.state = 'enrolling';
+    pairingChannel.send(
+      this.options.channel,
+      JSON.stringify({ t: 'enroll-key', spki: cfg.hostPublicSpki } satisfies IEnrollFrame),
+    );
+  }
+
+  private completeEnrollment(deviceSpki: string): void {
+    if (this.state !== 'enrolling') return;
+    const cfg = this.options.reconnect;
+    if (!cfg) {
+      this.rejectAndClose();
+      return;
+    }
+    void (async (): Promise<void> => {
+      try {
+        // Validate the SPKI parses as a public key before pinning (fail closed on garbage).
+        await importPublicKey(deviceSpki);
+        const deviceId = await deriveIdentityId(deviceSpki);
+        if (this.state !== 'enrolling') return;
+        this.pendingDeviceId = deviceId;
+        this.pendingEnrollment = { deviceId, spki: deviceSpki };
+        this.accept(this.pendingResult);
+      } catch {
+        this.rejectAndClose();
+      }
+    })();
+  }
+
+  private accept(result?: IPairingResult, viaReconnect = false): void {
+    if (this.state === 'closed' || this.state === 'accepted') return;
+    // The steps this channel still owes. Demanded here rather than earlier because the handshake
+    // must already have bound the channel, and before anything below because that is where the
+    // session becomes reachable. The ordering argument lives in `admission-steps.ts`.
+    const owed = nextAdmissionStep(this.options, this.state);
+    if (owed !== null) {
+      this.pendingResult = result ?? this.pendingResult;
+      this.pendingViaReconnect = viaReconnect;
+      this.state = owed;
+      if (owed === 'operator-approval') void this.askOperator();
+      return;
+    }
+    // Pin a first-pair device only now: a device a later step refused is not remembered.
+    const enrollment = this.pendingEnrollment;
+    this.pendingEnrollment = undefined;
+    if (enrollment !== undefined) {
+      try {
+        this.options.reconnect?.onEnroll(enrollment.deviceId, enrollment.spki);
+      } catch {
+        this.rejectAndClose();
+        return;
+      }
+    }
+    const attached = attachSession(this.options, viaReconnect, (error, event) =>
+      this.handleSessionDeliveryError(error, event),
+    );
+    this.onSessionMessage = attached.onSessionMessage;
+    this.handlerCleanup = attached.cleanup;
+    this.state = 'accepted';
+    this.options.onAccept?.(result);
+    const held = this.heldFrames;
+    this.heldFrames = [];
+    this.heldChars = 0;
+    for (const frame of held) {
+      if (this.state !== 'accepted') return;
+      this.onSessionMessage?.(frame);
+    }
+  }
+
+  private holdForApproval(data: string): void {
+    this.heldChars += data.length;
+    this.heldFrames.push(data);
+    if (this.heldFrames.length > HELD_FRAMES_MAX || this.heldChars > HELD_CHARS_MAX) {
+      this.rejectAndClose();
+    }
+  }
+
+  /**
+   * The `operator-approval` state: ask, then admit only on an explicit yes. A failure to ask is a no,
+   * and an answer that arrives after the channel was torn down admits nothing.
+   */
+  private async askOperator(): Promise<void> {
+    const abort = new AbortController();
+    this.approvalAbort = abort;
+    const context: IConnectionApprovalContext = {
+      ...(this.pendingDeviceId !== undefined ? { deviceId: this.pendingDeviceId } : {}),
+      viaReconnect: this.pendingViaReconnect,
+      signal: abort.signal,
+    };
+    let allowed = false;
+    try {
+      allowed = (await this.options.connectionApproval?.approve(context)) === true;
+    } catch {
+      allowed = false;
+    }
+    if (this.state !== 'operator-approval' || abort.signal.aborted) return;
+    this.approvalAbort = undefined;
+    if (allowed) this.accept(this.pendingResult, this.pendingViaReconnect);
+    else this.rejectAndClose();
+  }
+
+  /** The async half of the `handoff-grant` state, kept off the synchronous message path. */
+  private async judgeGrantFrame(parsed: unknown): Promise<void> {
+    const admission = await judgeHandoffGrant(parsed, this.options.handoffGrant);
+    // A channel torn down while the signature was being checked must not be re-accepted by a verdict
+    // that arrives afterwards. Checked after the await, because that is the window it exists for.
+    if (this.state !== 'handoff-grant') return;
+    this.options.handoffGrant?.onAdmission?.(admission);
+    if (admission.admitted) this.accept(this.pendingResult, this.pendingViaReconnect);
+    else this.rejectAndClose();
+  }
+
+  private rejectAndClose(): void {
+    if (this.state === 'closed') return;
+    this.state = 'closed';
+    this.withdrawApproval();
+    pairingChannel.close(this.options.channel);
+    this.options.onReject?.();
+  }
+
+  private handleSessionDeliveryError(error: Error, event: string): void {
+    if (this.state === 'closed') return;
+    this.state = 'closed';
+    this.handlerCleanup?.();
+    this.handlerCleanup = undefined;
+    this.onSessionMessage = undefined;
+    pairingChannel.reportDeliveryError(this.options.onDeliveryError, error, event);
+    pairingChannel.close(this.options.channel);
+  }
+}

package/src/session-attachment.ts

@@ -0,0 +1,88 @@
+/**
+ * Wiring an admitted channel to the session — the step immediately after the gate says yes.
+ *
+ * "How session frames travel once admission is settled" is a different subject from "what may reach
+ * the session at all", which is the gate's. Split out for the same reason the frame vocabulary and
+ * the controllers already were: `pairing-gate.ts` is at its size limit, and the rule there is to
+ * split rather than extend.
+ *
+ * Two carriers, chosen by whether a resume bridge exists. Neither decides anything about admission —
+ * by the time either runs, that question is closed.
+ */
+
+import {
+  createSessionMessageHandler,
+  type ISessionMessageHandlerOptions,
+  type SessionResumeBridge,
+} from '@robota-sdk/agent-transport';
+
+import { createChannelDelivery } from './channel-delivery.js';
+
+import type { IPairingChannel } from './pairing-gate-options.js';
+import type { IProtocolSession } from '@robota-sdk/agent-transport';
+
+export interface IAttachSessionOptions {
+  readonly channel: IPairingChannel;
+  readonly session: IProtocolSession;
+  readonly resumeBridge?: SessionResumeBridge;
+  readonly createHandler?: typeof createSessionMessageHandler;
+  readonly personalUsageReporter?: ISessionMessageHandlerOptions['personalUsageReporter'];
+  readonly usageReporter?: ISessionMessageHandlerOptions['usageReporter'];
+  readonly storedSessionUsageReporter?: ISessionMessageHandlerOptions['storedSessionUsageReporter'];
+  readonly surface?: ISessionMessageHandlerOptions['surface'];
+}
+
+export interface IAttachedSession {
+  /** Where post-accept inbound frames go. */
+  readonly onSessionMessage: (data: string) => void;
+  /** Detach (bridge) or dispose (handler). The gate calls this on teardown. */
+  readonly cleanup: () => void;
+}
+
+/**
+ * Attach the admitted channel to the session.
+ *
+ * `viaReconnect` is threaded through rather than inferred: on a reconnect the bridge must hold live
+ * forwarding until the client's `resume` replays the buffered tail, and getting that backwards
+ * delivers new frames ahead of the replay — an ordering bug that looks like data loss.
+ */
+export function attachSession(
+  options: IAttachSessionOptions,
+  viaReconnect: boolean,
+  onDeliveryError: (error: Error, event: string) => void,
+): IAttachedSession {
+  const bridge = options.resumeBridge;
+  if (bridge) {
+    // REMOTE-013 E4: route the session through the persistent bridge. Attach this channel as the
+    // sink; post-accept inbound frames (incl. resume/ack) go to the bridge; cleanup DETACHES it
+    // (never disposes — the bridge is owned by the transport across reconnects).
+    bridge.attach((data) => options.channel.send(data), {
+      awaitResume: viaReconnect,
+      onDeliveryError,
+      // ARCH-030: without this the bridge's boundary has no backpressure reading, so the replay
+      // path — the burst this budget exists for — runs unbudgeted while every other outbound path
+      // on the same connection is guarded. Read at call time; `bufferedAmount` is live.
+      pendingBytes: () => options.channel.bufferedAmount,
+    });
+    return {
+      onSessionMessage: (data) => bridge.onClientMessage(data),
+      cleanup: () => bridge.detach(),
+    };
+  }
+
+  const create = options.createHandler ?? createSessionMessageHandler;
+  // ARCH-030: the gate is the carrier on this branch — its own channel sink, its own failure policy.
+  const { onMessage, cleanup } = create({
+    session: options.session,
+    deliver: createChannelDelivery(options.channel, onDeliveryError),
+    ...(options.personalUsageReporter
+      ? { personalUsageReporter: options.personalUsageReporter }
+      : {}),
+    ...(options.usageReporter ? { usageReporter: options.usageReporter } : {}),
+    ...(options.storedSessionUsageReporter
+      ? { storedSessionUsageReporter: options.storedSessionUsageReporter }
+      : {}),
+    ...(options.surface ? { surface: options.surface } : {}),
+  });
+  return { onSessionMessage: onMessage, cleanup };
+}

package/src/signaling.ts

@@ -0,0 +1,62 @@
+/**
+ * Signaling port (REMOTE-002). The WebRTC transport is decoupled from any concrete signaling server via this
+ * port: it exchanges opaque SDP/ICE blobs by rendezvous id. The port carries **only** SDP offers/answers + ICE
+ * candidates — never session content — so a signaling server (or the in-memory test pair) is content-blind.
+ */
+
+/** The kinds of signal a peer exchanges through the relay. */
+export type TSignalKind = 'offer' | 'answer' | 'ice';
+
+/** An opaque signaling message relayed by rendezvous id. `data` is an SDP description or an ICE candidate. */
+export interface ISignalMessage {
+  readonly kind: TSignalKind;
+  /** Opaque payload (serialized SDP or ICE candidate). The signaling layer never inspects it. */
+  readonly data: unknown;
+}
+
+/** Port a WebRTC peer uses to reach its counterpart at a rendezvous id. */
+export interface ISignalingClient {
+  /** Send a signal to the counterpart at the rendezvous. */
+  send(message: ISignalMessage): void;
+  /** Subscribe to signals from the counterpart. Returns an unsubscribe function. */
+  onSignal(handler: (message: ISignalMessage) => void): () => void;
+  /** Tear down the signaling channel. */
+  close(): void;
+}
+
+/**
+ * An in-process pair of {@link ISignalingClient}s wired directly to each other — for tests + loopback only
+ * (no server, no network). Each side's `send` is delivered to the other side's handlers on a microtask.
+ */
+export function createInMemorySignalingPair(): [ISignalingClient, ISignalingClient] {
+  const handlersA: ((m: ISignalMessage) => void)[] = [];
+  const handlersB: ((m: ISignalMessage) => void)[] = [];
+  let open = true;
+
+  function make(
+    ownHandlers: ((m: ISignalMessage) => void)[],
+    peerHandlers: ((m: ISignalMessage) => void)[],
+  ): ISignalingClient {
+    return {
+      send(message) {
+        if (!open) return;
+        queueMicrotask(() => {
+          for (const h of peerHandlers) h(message);
+        });
+      },
+      onSignal(handler) {
+        ownHandlers.push(handler);
+        return () => {
+          const i = ownHandlers.indexOf(handler);
+          if (i >= 0) ownHandlers.splice(i, 1);
+        };
+      },
+      close() {
+        open = false;
+        ownHandlers.length = 0;
+      },
+    };
+  }
+
+  return [make(handlersA, handlersB), make(handlersB, handlersA)];
+}

package/src/transport-lifecycle-error.ts

@@ -0,0 +1,11 @@
+import type { ITransportLifecycleError } from '@robota-sdk/agent-interface-transport';
+
+export function createTransportLifecycleError(
+  code: ITransportLifecycleError['code'],
+): ITransportLifecycleError {
+  return Object.assign(new Error(`WebRtcTransport ${code}.`), {
+    name: 'TransportLifecycleError' as const,
+    code,
+    transportName: 'webrtc',
+  });
+}