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

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

@@ -0,0 +1,238 @@
+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 { RTCPeerConnection } from 'werift';
+
+import { WebRtcTransport } from '../webrtc-transport.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 werift 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 RTCPeerConnection();
+  peer.onIceCandidate.subscribe((c) => {
+    if (c) signaling.send({ kind: 'ice', data: c.toJSON() });
+  });
+
+  let hostFingerprint: string | undefined;
+  let chain: Promise<void> = Promise.resolve();
+  signaling.onSignal((message) => {
+    chain = chain.then(async () => {
+      if (message.kind === 'offer') {
+        const offer = message.data as { sdp: string } & Parameters<
+          typeof peer.setRemoteDescription
+        >[0];
+        hostFingerprint = extractDtlsFingerprint(offer.sdp);
+        await peer.setRemoteDescription(offer);
+        const answer = await peer.createAnswer();
+        await peer.setLocalDescription(answer);
+        signaling.send({ kind: 'answer', data: peer.localDescription });
+      } else if (message.kind === 'ice') {
+        await peer.addIceCandidate(message.data as Parameters<typeof peer.addIceCandidate>[0]);
+      }
+    });
+  });
+
+  let remoteChannel: { close(): void } | undefined;
+  peer.onDataChannel.subscribe((channel) => {
+    remoteChannel = channel;
+    let accepted = false;
+    const controller = startPairingHandshake({
+      secret,
+      role: 'responder',
+      localFingerprint: extractDtlsFingerprint(peer.localDescription!.sdp),
+      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.subscribe((data) => {
+      const text = typeof data === 'string' ? data : data.toString();
+      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({ 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({ 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({
+      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({
+      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({
+      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,192 @@
+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({
+      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({
+      channel,
+      session: stubSession(),
+      secret: 's',
+      role: 'initiator',
+      ...FP,
+      reconnect: cfg,
+      onAccept,
+      onReject,
+    });
+    // Device drives the reconnect; its frames go into the gate.
+    deviceCtrl = startDeviceReconnect({
+      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({
+      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);
+  });
+});

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

@@ -0,0 +1,108 @@
+import { SessionResumeBridge } from '@robota-sdk/agent-transport';
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+import type { IInteractiveSession } from '@robota-sdk/agent-interface-session';
+import { describe, expect, it, vi } from 'vitest';
+
+import { PairingGate } from '../pairing-gate.js';
+
+/**
+ * REMOTE-013 E4 — when a `resumeBridge` is supplied, the gate routes the paired session through the bridge
+ * (seq-stamped) instead of a fresh handler, and `cleanup()` DETACHES the bridge (session survives the drop).
+ */
+
+function fakeSession(): {
+  session: IInteractiveSession;
+  fire: (event: string, arg: unknown) => void;
+} {
+  const handlers = new Map<string, (arg: unknown) => void>();
+  // ARCH-012: the conformant double. The three-member partial this replaces was accepted only by a
+  // cast, so the suite ran against a session shape no implementation could have.
+  const session = createTestInteractiveSession({
+    on: ((e: string, h: (arg: unknown) => void) => {
+      handlers.set(e, h);
+    }) as IInteractiveSession['on'],
+    off: ((e: string) => {
+      handlers.delete(e);
+    }) as IInteractiveSession['off'],
+  });
+  return { session, fire: (e, a) => handlers.get(e)?.(a) };
+}
+
+describe('PairingGate E4 resume bridge (REMOTE-013)', () => {
+  it('routes the paired session through the bridge (seq-stamped) and detaches on cleanup', async () => {
+    const { session, fire } = fakeSession();
+    const bridge = new SessionResumeBridge({ session });
+    const sent: string[] = [];
+    const channel = { send: (d: string) => sent.push(d), close: () => {} };
+    // Fake handshake that accepts immediately (isolates the bridge wiring from real B3 crypto).
+    const fakeHandshake = (() => ({
+      result: Promise.resolve({ sessionKey: 'k' }),
+      onFrame: () => {},
+    })) as never;
+
+    const gate = new PairingGate({
+      channel,
+      session,
+      secret: 's',
+      role: 'initiator',
+      localFingerprint: 'A',
+      remoteFingerprint: 'B',
+      resumeBridge: bridge,
+      startHandshake: fakeHandshake,
+    });
+    // Drive to accept (the fake handshake resolves on a microtask).
+    gate.onInbound(JSON.stringify({ t: 'pair-nonce', nonce: 'n' }));
+    await Promise.resolve();
+    await Promise.resolve();
+
+    // A session event now flows through the bridge → the channel, seq-stamped.
+    fire('text_delta', 'hi');
+    expect(sent).toHaveLength(1);
+    const frame = JSON.parse(sent[0]);
+    expect(frame).toMatchObject({ type: 'text_delta', delta: 'hi', seq: 1 });
+
+    // Cleanup DETACHES (does not dispose) — a subsequent event is buffered, not sent, and the session survives.
+    gate.cleanup();
+    fire('text_delta', 'gap'); // buffered at seq 2, not sent (detached)
+    expect(sent).toHaveLength(1);
+
+    // Re-attach a new channel + resume → the gap frame replays with its ORIGINAL seq 2 (continuity).
+    const sent2: string[] = [];
+    bridge.attach((d) => sent2.push(d), { onDeliveryError: vi.fn() });
+    bridge.onClientMessage(JSON.stringify({ type: 'resume', lastSeq: 1 }));
+    expect(sent2.map((s) => JSON.parse(s).seq)).toEqual([2]);
+    bridge.dispose();
+  });
+
+  it('a resume/ack inbound frame post-accept is routed to the bridge (not the session)', async () => {
+    const { session, fire } = fakeSession();
+    const bridge = new SessionResumeBridge({ session });
+    const sent: string[] = [];
+    const channel = { send: (d: string) => sent.push(d), close: () => {} };
+    const fakeHandshake = (() => ({
+      result: Promise.resolve({ sessionKey: 'k' }),
+      onFrame: () => {},
+    })) as never;
+    const gate = new PairingGate({
+      channel,
+      session,
+      secret: 's',
+      role: 'initiator',
+      localFingerprint: 'A',
+      remoteFingerprint: 'B',
+      resumeBridge: bridge,
+      startHandshake: fakeHandshake,
+    });
+    gate.onInbound(JSON.stringify({ t: 'pair-nonce', nonce: 'n' }));
+    await Promise.resolve();
+    await Promise.resolve();
+    fire('text_delta', 'a'); // seq 1
+    fire('text_delta', 'b'); // seq 2
+    sent.length = 0;
+    // ack via the channel → bridge frees ≤1; resume lastSeq 1 → replays only seq 2.
+    gate.onInbound(JSON.stringify({ type: 'ack', seq: 1 }));
+    gate.onInbound(JSON.stringify({ type: 'resume', lastSeq: 1 }));
+    expect(sent.map((s) => JSON.parse(s).seq)).toEqual([2]);
+    bridge.dispose();
+  });
+});