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

package/src/__tests__/outbound-delivery-carrier.test.ts

@@ -0,0 +1,155 @@
+import { createIdentityContext } from '@robota-sdk/agent-remote-pairing';
+const testIdentity = createIdentityContext('test-product');
+/**
+ * ARCH-030 at the WebRTC carrier.
+ *
+ * The item named WebRTC as affected, and its stated reason was wrong in a way worth recording: the
+ * PAIRED-with-resume-bridge path was already guarded (the bridge routed replies through its own
+ * try/catch). The genuinely unguarded WebRTC exposure was the BARE `createSessionMessageHandler` — `PairingGate`'s
+ * no-`resumeBridge` branch, taken after the handshake accepts, and `WebRtcTransport`'s no-secret
+ * branch, which is the same construction. This suite drives the gate's branch with a stubbed
+ * handshake, the way `pairing-gate.test.ts` does, because that is the one that ships by default.
+ */
+
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+import { describe, expect, it, vi } from 'vitest';
+
+import { PairingGate } from '../pairing-gate.js';
+
+import type { startPairingHandshake, TPairingFrame } from '@robota-sdk/agent-remote-pairing';
+import type { IInteractiveSession } from '@robota-sdk/agent-interface-session';
+
+/** Collect unhandled rejections while `run` executes, then drain the queue Node reports them on. */
+async function withUnhandledRejectionCapture(run: () => void | Promise<void>): Promise<unknown[]> {
+  const captured: unknown[] = [];
+  const existing = process.listeners('unhandledRejection');
+  for (const listener of existing) process.off('unhandledRejection', listener);
+  const collect = (reason: unknown): void => {
+    captured.push(reason);
+  };
+  process.on('unhandledRejection', collect);
+  try {
+    await run();
+    await new Promise((resolve) => setTimeout(resolve, 20));
+  } finally {
+    process.off('unhandledRejection', collect);
+    for (const listener of existing)
+      process.on('unhandledRejection', listener as NodeJS.UnhandledRejectionListener);
+  }
+  return captured;
+}
+
+/** A controllable handshake stub: the test decides when pairing accepts. */
+function makeHandshakeStub(): { start: typeof startPairingHandshake; accept: () => void } {
+  let resolveResult!: (value: { sessionKey: string }) => void;
+  const start: typeof startPairingHandshake = (_cryptoContext, options) => {
+    const controller = {
+      result: new Promise<{ sessionKey: string }>((res) => {
+        resolveResult = res;
+      }),
+      onFrame: (_frame: TPairingFrame) => undefined,
+    };
+    options.send({ t: 'pair-nonce', nonce: 'stub' });
+    return controller;
+  };
+  return { start, accept: () => resolveResult({ sessionKey: 'k' }) };
+}
+
+/** A data channel whose `send` starts throwing once dropped, as a real one does once closed. */
+type TTestChannel = { send: (data: string) => void; close: () => void };
+
+function createDroppableChannel(): {
+  channel: TTestChannel;
+  close: ReturnType<typeof vi.fn>;
+  drop: () => void;
+} {
+  let open = true;
+  const close = vi.fn();
+  const channel = {
+    send: (data: string) => {
+      if (!open) throw new Error('RTCDataChannel is not open');
+      void data;
+    },
+    close,
+  };
+  return {
+    channel,
+    close,
+    drop: () => {
+      open = false;
+    },
+  };
+}
+
+/** Build an accepted gate on its bare-handler branch (no `resumeBridge`). */
+async function acceptedGate(session: IInteractiveSession): Promise<{
+  gate: PairingGate;
+  channelClose: ReturnType<typeof vi.fn>;
+  drop: () => void;
+  deliveryErrors: Array<{ message: string; event: string }>;
+}> {
+  const { channel, close, drop } = createDroppableChannel();
+  const deliveryErrors: Array<{ message: string; event: string }> = [];
+  const handshake = makeHandshakeStub();
+  const gate = new PairingGate({cryptoContext: testIdentity,
+    channel,
+    session,
+    secret: 's',
+    role: 'initiator',
+    localFingerprint: 'AA',
+    remoteFingerprint: 'BB',
+    startHandshake: handshake.start,
+    onDeliveryError: (error, event) => deliveryErrors.push({ message: error.message, event }),
+  });
+  handshake.accept();
+  await new Promise((resolve) => setTimeout(resolve, 0)); // the gate accepts on a microtask
+  return { gate, channelClose: close, drop, deliveryErrors };
+}
+
+describe('PairingGate bare-handler branch + the outbound boundary (ARCH-030)', () => {
+  it('a command resolving after the channel dropped reports once and leaks no rejection', async () => {
+    let releaseCommand: (() => void) | undefined;
+    const commandGate = new Promise<void>((resolve) => {
+      releaseCommand = resolve;
+    });
+    const executed: string[] = [];
+    const session: IInteractiveSession = createTestInteractiveSession({
+      executeCommand: (name: string) =>
+        commandGate.then(() => {
+          executed.push(name);
+          return { success: true, message: 'done' };
+        }),
+    } as Partial<IInteractiveSession>);
+    const { gate, channelClose, drop, deliveryErrors } = await acceptedGate(session);
+
+    const rejections = await withUnhandledRejectionCapture(async () => {
+      gate.onInbound(JSON.stringify({ type: 'command', name: 'status' }));
+      drop();
+      releaseCommand?.();
+    });
+
+    expect(rejections).toEqual([]);
+    expect(executed).toEqual(['status']); // the command committed regardless of delivery
+    expect(deliveryErrors).toEqual([
+      { message: 'RTCDataChannel is not open', event: 'command_result' },
+    ]);
+    // Carrier cleanup ran: the gate closed its channel on the delivery failure. Before ARCH-030 the
+    // reply threw from a Promise continuation and none of this happened.
+    expect(channelClose).toHaveBeenCalledTimes(1);
+  });
+
+  // As on the WS side, this is not the boundary latch's own proof — `PairingGate.handleSessionDeliveryError`
+  // returns early once its state is `closed`, so the single report predates ARCH-030. It pins that the
+  // boundary above it did not change what the gate observes. The latch is red-proved in the protocol suite.
+  it('reports once for a burst of replies after the drop', async () => {
+    const session = createTestInteractiveSession();
+    const { gate, drop, deliveryErrors } = await acceptedGate(session);
+    drop();
+
+    gate.onInbound(JSON.stringify({ type: 'get-executing' }));
+    gate.onInbound(JSON.stringify({ type: 'get-messages' }));
+    gate.onInbound(JSON.stringify({ type: 'get-pending' }));
+
+    expect(deliveryErrors).toEqual([{ message: 'RTCDataChannel is not open', event: 'executing' }]);
+  });
+});

package/src/__tests__/pairing-e2e.test.ts

@@ -0,0 +1,237 @@
+import { createIdentityContext } from '@robota-sdk/agent-remote-pairing';
+const testIdentity = createIdentityContext('test-product');
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+
+import { extractDtlsFingerprint, startPairingHandshake } from '@robota-sdk/agent-remote-pairing';
+import { describe, expect, it, vi } from 'vitest';
+
+import { WebRtcTransport } from '../webrtc-transport.js';
+import { RtcPeer } from '../rtc-peer.js';
+import { createInMemorySignalingPair, type ISignalingClient } from '../signaling.js';
+
+import type { TPairingFrame } from '@robota-sdk/agent-remote-pairing';
+import type { IInteractiveSession } from '@robota-sdk/agent-interface-session';
+
+/**
+ * REMOTE-008 Step 1/5 — end-to-end PAIRED handshake over a REAL data channel. The host is a
+ * `WebRtcTransport` with a `secret` (initiator ≡ offerer); the "remote device" here runs the RESPONDER
+ * side of the same pairing handshake, then speaks the session protocol only after its own accept. Proves
+ * the gate's routing switch works over a real channel: matching secrets → session exposed + round-trips;
+ * mismatched secrets → both reject, session never exposed (fail closed).
+ */
+
+function createStubSession(): IInteractiveSession {
+  return Object.assign(createTestInteractiveSession(), {
+    getMessages: vi.fn().mockReturnValue([{ role: 'user', content: 'hi' }]),
+    // ARCH-012: required. This double feeds `subscribeSessionEvents`, which calls it on every
+    // turn-authored event — omitting it throws the moment a case emits one.
+    getActiveDriverId: () => null,
+    on: vi.fn(),
+    off: vi.fn(),
+  });
+}
+
+interface IRemoteResult {
+  /** Resolves with the first session `TServerMessage` (only reachable if pairing accepted). */
+  session: Promise<Record<string, unknown>>;
+  /** Resolves true if the responder's pairing accepted, false if it rejected/closed. */
+  paired: Promise<boolean>;
+  /** Close the remote's data channel — the device going away. */
+  close: () => void;
+}
+
+/**
+ * The remote device (answerer + pairing RESPONDER). Extracts the host fingerprint from the offer and its
+ * own from the answer, runs the responder handshake over the data channel, and — on accept — sends a
+ * `get-messages` session frame. Session frames are only sent post-accept (phase separation).
+ */
+function connectRemotePaired(signaling: ISignalingClient, secret: string): IRemoteResult {
+  let resolveSession!: (v: Record<string, unknown>) => void;
+  let resolvePaired!: (v: boolean) => void;
+  const session = new Promise<Record<string, unknown>>((res) => (resolveSession = res));
+  const paired = new Promise<boolean>((res) => (resolvePaired = res));
+
+  const peer = new RtcPeer();
+  peer.onLocalCandidate((c) =>
+    signaling.send({ kind: 'ice', data: { candidate: c.candidate, sdpMid: c.mid } }),
+  );
+
+  let hostFingerprint: string | undefined;
+  let localFingerprint: string | undefined;
+  let chain: Promise<void> = Promise.resolve();
+  signaling.onSignal((message) => {
+    chain = chain.then(async () => {
+      const data = message.data as { sdp?: string; candidate?: string; sdpMid?: string };
+      if (message.kind === 'offer') {
+        hostFingerprint = extractDtlsFingerprint(data.sdp!);
+        const answer = await peer.acceptOffer(data.sdp!);
+        localFingerprint = extractDtlsFingerprint(answer);
+        signaling.send({ kind: 'answer', data: { type: 'answer', sdp: answer } });
+      } else if (message.kind === 'ice') {
+        peer.addRemoteCandidate({ candidate: data.candidate!, mid: data.sdpMid ?? '0' });
+      }
+    });
+  });
+
+  let remoteChannel: { close(): void } | undefined;
+  peer.onDataChannel((channel) => {
+    remoteChannel = channel;
+    let accepted = false;
+    const controller = startPairingHandshake(testIdentity, {
+      secret,
+      role: 'responder',
+      localFingerprint: localFingerprint!,
+      remoteFingerprint: hostFingerprint!,
+      send: (frame: TPairingFrame) => {
+        try {
+          channel.send(JSON.stringify(frame));
+        } catch {
+          /* channel closing */
+        }
+      },
+      timeoutMs: 8000,
+    });
+    controller.result.then(
+      () => {
+        accepted = true;
+        resolvePaired(true);
+        channel.send(JSON.stringify({ type: 'get-messages' }));
+      },
+      () => resolvePaired(false),
+    );
+    channel.onMessage((text) => {
+      if (!accepted) {
+        // Pre-accept only pairing frames arrive; route them to the handshake.
+        try {
+          controller.onFrame(JSON.parse(text) as TPairingFrame);
+        } catch {
+          /* ignore */
+        }
+        return;
+      }
+      resolveSession(JSON.parse(text) as Record<string, unknown>);
+    });
+  });
+
+  return { session, paired, close: () => remoteChannel?.close() };
+}
+
+describe('WebRtc pairing end-to-end (REMOTE-008)', () => {
+  it('matching secrets: both peers pair, the session is exposed, and get-messages round-trips', async () => {
+    const secret = 'shared-secret-256bit-base64url-xyz';
+    const [hostSig, remoteSig] = createInMemorySignalingPair();
+    const transport = new WebRtcTransport({cryptoContext: testIdentity,  signaling: hostSig, secret });
+    transport.attach(createStubSession());
+
+    const remote = connectRemotePaired(remoteSig, secret);
+    await transport.start();
+
+    await expect(remote.paired).resolves.toBe(true);
+    const reply = await remote.session;
+    expect(reply.type).toBe('messages');
+    await transport.stop();
+  }, 20000);
+
+  it('mismatched secrets: both reject, the session is never exposed (fail closed)', async () => {
+    const [hostSig, remoteSig] = createInMemorySignalingPair();
+    const session = createStubSession();
+    const transport = new WebRtcTransport({cryptoContext: testIdentity,  signaling: hostSig, secret: 'host-secret' });
+    transport.attach(session);
+
+    const remote = connectRemotePaired(remoteSig, 'different-secret');
+    await transport.start();
+
+    await expect(remote.paired).resolves.toBe(false);
+    // The host never built the session bridge → getMessages was never invoked over the channel.
+    expect(session.getMessages as ReturnType<typeof vi.fn>).not.toHaveBeenCalled();
+    await transport.stop();
+  }, 20000);
+
+  it('a driving connection the host operator does not approve never reaches the session', async () => {
+    const secret = 'shared-secret-256bit-base64url-xyz';
+    const [hostSig, remoteSig] = createInMemorySignalingPair();
+    const session = createStubSession();
+    const approve = vi.fn(async () => false);
+    const onPaired = vi.fn();
+    const transport = new WebRtcTransport({cryptoContext: testIdentity,
+      signaling: hostSig,
+      secret,
+      connectionApproval: { approve },
+      onPaired,
+    });
+    transport.attach(session);
+
+    const remote = connectRemotePaired(remoteSig, secret);
+    await transport.start();
+
+    // The handshake itself succeeds — the device is who it says — and the operator still decides.
+    await expect(remote.paired).resolves.toBe(true);
+    await vi.waitFor(() => expect(approve).toHaveBeenCalledTimes(1));
+    await new Promise((resolve) => setTimeout(resolve, 200));
+    expect(session.getMessages as ReturnType<typeof vi.fn>).not.toHaveBeenCalled();
+    expect(onPaired).not.toHaveBeenCalled();
+    await transport.stop();
+  }, 20000);
+
+  it('a device that goes away while the operator decides withdraws the question and is never admitted', async () => {
+    const secret = 'shared-secret-256bit-base64url-xyz';
+    const [hostSig, remoteSig] = createInMemorySignalingPair();
+    let signal: AbortSignal | undefined;
+    let answer!: (value: boolean) => void;
+    const approve = vi.fn((context: { signal: AbortSignal }) => {
+      signal = context.signal;
+      return new Promise<boolean>((resolve) => (answer = resolve));
+    });
+    const onPaired = vi.fn();
+    const onPairingFailed = vi.fn();
+    const session = createStubSession();
+    const transport = new WebRtcTransport({cryptoContext: testIdentity,
+      signaling: hostSig,
+      secret,
+      connectionApproval: { approve },
+      onPaired,
+      onPairingFailed,
+    });
+    transport.attach(session);
+
+    const remote = connectRemotePaired(remoteSig, secret);
+    await transport.start();
+    await expect(remote.paired).resolves.toBe(true);
+    await vi.waitFor(() => expect(approve).toHaveBeenCalledTimes(1));
+
+    remote.close();
+    await vi.waitFor(() => expect(signal?.aborted).toBe(true), { timeout: 5000 });
+    expect(onPairingFailed).toHaveBeenCalledTimes(1);
+    answer(true);
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    expect(onPaired).not.toHaveBeenCalled();
+    expect(session.getMessages as ReturnType<typeof vi.fn>).not.toHaveBeenCalled();
+    await transport.stop();
+  }, 20000);
+
+  it('a driving connection the host operator approves reaches the session', async () => {
+    const secret = 'shared-secret-256bit-base64url-xyz';
+    const [hostSig, remoteSig] = createInMemorySignalingPair();
+    // The operator takes a moment: the device, already paired on its side, asks for the history
+    // meanwhile, and gets its answer once the operator says yes.
+    const approve = vi.fn(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 300));
+      return true;
+    });
+    const transport = new WebRtcTransport({cryptoContext: testIdentity,
+      signaling: hostSig,
+      secret,
+      connectionApproval: { approve },
+    });
+    transport.attach(createStubSession());
+
+    const remote = connectRemotePaired(remoteSig, secret);
+    await transport.start();
+
+    await expect(remote.paired).resolves.toBe(true);
+    const reply = await remote.session;
+    expect(reply.type).toBe('messages');
+    expect(approve).toHaveBeenCalledTimes(1);
+    await transport.stop();
+  }, 20000);
+});

package/src/__tests__/pairing-gate-e3.test.ts

@@ -0,0 +1,194 @@
+import { createIdentityContext } from '@robota-sdk/agent-remote-pairing';
+const testIdentity = createIdentityContext('test-product');
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+
+import {
+  deriveIdentityId,
+  exportPublicKey,
+  generateIdentityKeyPair,
+  importPublicKey,
+  startDeviceReconnect,
+  type TReconnectFrame,
+} from '@robota-sdk/agent-remote-pairing';
+import type { IInteractiveSession } from '@robota-sdk/agent-interface-session';
+import { describe, expect, it, vi } from 'vitest';
+
+import { PairingGate, type IHostReconnectConfig } from '../pairing-gate.js';
+
+/**
+ * REMOTE-012 E3 TC-05 — the host gate's E3 admission paths, in isolation with a stub channel: first-pair
+ * ENROLLMENT (pin the device key, expose the session) and mutual RECONNECT (admit a pinned device, deny an
+ * unknown/revoked one) — all fail-closed.
+ */
+
+function stubSession(): IInteractiveSession {
+  return Object.assign(createTestInteractiveSession(), {
+    getMessages: vi.fn().mockReturnValue([]),
+    // ARCH-012: required. This double feeds `subscribeSessionEvents`, which calls it on every
+    // turn-authored event — omitting it throws the moment a case emits one.
+    getActiveDriverId: () => null,
+    on: vi.fn(),
+    off: vi.fn(),
+  });
+}
+
+/** A channel that captures sends and can route parsed frames to a sink (the counterpart controller). */
+function stubChannel(sink?: (frame: unknown) => void): {
+  channel: { send: (d: string) => void; close: () => void };
+  sent: unknown[];
+  closed: () => boolean;
+} {
+  const sent: unknown[] = [];
+  let closed = false;
+  return {
+    channel: {
+      send(d: string): void {
+        const parsed = JSON.parse(d);
+        sent.push(parsed);
+        sink?.(parsed);
+      },
+      close(): void {
+        closed = true;
+      },
+    },
+    sent,
+    closed: () => closed,
+  };
+}
+
+const FP = { localFingerprint: 'HOST:FP', remoteFingerprint: 'DEV:FP' };
+
+async function hostConfig(over: Partial<IHostReconnectConfig> = {}): Promise<{
+  cfg: IHostReconnectConfig;
+  hostKeyPair: CryptoKeyPair;
+}> {
+  const hostKeyPair = await generateIdentityKeyPair(true);
+  const hostPublicSpki = await exportPublicKey(hostKeyPair.publicKey);
+  return {
+    hostKeyPair,
+    cfg: {
+      hostIdentityId: await deriveIdentityId(hostPublicSpki),
+      hostPublicSpki,
+      hostPrivateKey: hostKeyPair.privateKey,
+      resolveDevicePublicKey: async () => undefined,
+      onEnroll: vi.fn(),
+      ...over,
+    },
+  };
+}
+
+describe('PairingGate E3 first-pair enrollment (REMOTE-012 TC-05)', () => {
+  it('after B3 accept, advertises the host key, pins the device key, and exposes the session', async () => {
+    const { cfg } = await hostConfig();
+    const onAccept = vi.fn();
+    // Fake handshake that accepts immediately (isolates the enrollment path from real B3 crypto).
+    const fakeHandshake = (() => ({
+      result: Promise.resolve({ sessionKey: 'k' }),
+      onFrame: () => {},
+    })) as never;
+
+    const { channel, sent } = stubChannel();
+    const gate = new PairingGate({cryptoContext: testIdentity,
+      channel,
+      session: stubSession(),
+      secret: 's',
+      role: 'initiator',
+      ...FP,
+      reconnect: cfg,
+      onAccept,
+      startHandshake: fakeHandshake,
+    });
+
+    // Client opens first-pair mode.
+    gate.onInbound(JSON.stringify({ t: 'pair-nonce', nonce: 'n' }));
+    await Promise.resolve();
+    await Promise.resolve();
+    // Host advertised its identity key.
+    expect(sent.some((f) => (f as { t?: string }).t === 'enroll-key')).toBe(true);
+
+    // Device replies with its public key → host pins it and exposes the session.
+    const deviceKey = await generateIdentityKeyPair(false);
+    const deviceSpki = await exportPublicKey(deviceKey.publicKey);
+    gate.onInbound(JSON.stringify({ t: 'enroll-key', spki: deviceSpki }));
+    await vi.waitFor(() => expect(onAccept).toHaveBeenCalledTimes(1));
+    expect(cfg.onEnroll).toHaveBeenCalledWith(await deriveIdentityId(deviceSpki), deviceSpki);
+  });
+});
+
+describe('PairingGate E3 reconnect (REMOTE-012 TC-05)', () => {
+  async function pinnedDevice(): Promise<{
+    keyPair: CryptoKeyPair;
+    deviceId: string;
+    publicKey: CryptoKey;
+  }> {
+    const keyPair = await generateIdentityKeyPair(false);
+    const spki = await exportPublicKey(keyPair.publicKey);
+    return {
+      keyPair,
+      deviceId: await deriveIdentityId(spki),
+      publicKey: await importPublicKey(spki),
+    };
+  }
+
+  it('admits a pinned device via mutual reconnect and exposes the session (no re-enroll)', async () => {
+    const device = await pinnedDevice();
+    const { cfg } = await hostConfig({
+      resolveDevicePublicKey: async (id) => (id === device.deviceId ? device.publicKey : undefined),
+    });
+    const hostPublicKey = await importPublicKey(cfg.hostPublicSpki);
+    const onAccept = vi.fn();
+    const onReject = vi.fn();
+
+    let gate!: PairingGate;
+    let deviceCtrl!: ReturnType<typeof startDeviceReconnect>;
+    // Route host→device frames into the device controller.
+    const { channel } = stubChannel((frame) => deviceCtrl.onFrame(frame as TReconnectFrame));
+    gate = new PairingGate({cryptoContext: testIdentity,
+      channel,
+      session: stubSession(),
+      secret: 's',
+      role: 'initiator',
+      ...FP,
+      reconnect: cfg,
+      onAccept,
+      onReject,
+    });
+    // Device drives the reconnect; its frames go into the gate.
+    deviceCtrl = startDeviceReconnect(testIdentity, {
+      deviceId: device.deviceId,
+      hostIdentityId: cfg.hostIdentityId,
+      localFingerprint: FP.remoteFingerprint,
+      remoteFingerprint: FP.localFingerprint,
+      devicePrivateKey: device.keyPair.privateKey,
+      pinnedHostPublicKey: hostPublicKey,
+      send: (frame) => gate.onInbound(JSON.stringify(frame)),
+      timeoutMs: 1000,
+    });
+
+    await deviceCtrl.result;
+    await vi.waitFor(() => expect(onAccept).toHaveBeenCalledTimes(1));
+    expect(onReject).not.toHaveBeenCalled();
+    expect(cfg.onEnroll).not.toHaveBeenCalled();
+  });
+
+  it('fail-closed: an unknown/revoked device is denied (channel closed, no session)', async () => {
+    const { cfg } = await hostConfig({ resolveDevicePublicKey: async () => undefined });
+    const onAccept = vi.fn();
+    const onReject = vi.fn();
+    const { channel, closed } = stubChannel();
+    const gate = new PairingGate({cryptoContext: testIdentity,
+      channel,
+      session: stubSession(),
+      secret: 's',
+      role: 'initiator',
+      ...FP,
+      reconnect: cfg,
+      onAccept,
+      onReject,
+    });
+    gate.onInbound(JSON.stringify({ t: 'rc-hello', deviceId: 'ghost', nonceDevice: 'ZGV2' }));
+    await vi.waitFor(() => expect(onReject).toHaveBeenCalledTimes(1));
+    expect(onAccept).not.toHaveBeenCalled();
+    expect(closed()).toBe(true);
+  });
+});