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

package/src/__tests__/negotiated-certificate.test.ts

@@ -0,0 +1,80 @@
+import { extractDtlsFingerprint } from '@robota-sdk/agent-remote-pairing';
+import { describe, expect, it } from 'vitest';
+import { RTCPeerConnection } from 'werift';
+
+import { certificateFingerprint, whenRemoteCertificateVerified } from '../negotiated-certificate.js';
+
+/** Connect two real werift peers directly and return them once the offerer's DTLS is connected. */
+async function connectedPair(): Promise<{ host: RTCPeerConnection; remote: RTCPeerConnection }> {
+  const host = new RTCPeerConnection();
+  const remote = new RTCPeerConnection();
+  host.createDataChannel('robota-session');
+  host.onIceCandidate.subscribe((c) => {
+    if (c) void remote.addIceCandidate(c.toJSON());
+  });
+  remote.onIceCandidate.subscribe((c) => {
+    if (c) void host.addIceCandidate(c.toJSON());
+  });
+  await host.setLocalDescription(await host.createOffer());
+  await remote.setRemoteDescription(host.localDescription!);
+  await remote.setLocalDescription(await remote.createAnswer());
+  await host.setRemoteDescription(remote.localDescription!);
+  return { host, remote };
+}
+
+describe('negotiated certificate fingerprint', () => {
+  it('reports the fingerprint of the certificate the DTLS layer verified', async () => {
+    const { host, remote } = await connectedPair();
+    const fingerprint = await new Promise<string>((resolve, reject) => {
+      whenRemoteCertificateVerified(host, 'sha-256', resolve, (reason) => reject(new Error(reason)));
+    });
+    expect(fingerprint).toBe(extractDtlsFingerprint(remote.localDescription!.sdp));
+    await host.close();
+    await remote.close();
+  }, 15000);
+
+  it('fails on an algorithm it cannot hash', async () => {
+    const { host, remote } = await connectedPair();
+    const reason = await new Promise<string>((resolve) => {
+      whenRemoteCertificateVerified(host, 'md5', () => resolve('verified'), resolve);
+    });
+    expect(reason).toMatch(/unsupported DTLS fingerprint algorithm/);
+    await host.close();
+    await remote.close();
+  }, 15000);
+
+  it('formats a digest as upper-case colon-separated pairs', () => {
+    expect(certificateFingerprint(new Uint8Array([1, 2, 3]), 'SHA-256')).toMatch(
+      /^([0-9A-F]{2}:){31}[0-9A-F]{2}$/,
+    );
+  });
+});
+
+describe('negotiated certificate — failed handshake', () => {
+  it('reports a DTLS handshake that fails instead of waiting forever', async () => {
+    const host = new RTCPeerConnection();
+    const remote = new RTCPeerConnection();
+    host.createDataChannel('robota-session');
+    host.onIceCandidate.subscribe((c) => {
+      if (c) void remote.addIceCandidate(c.toJSON());
+    });
+    remote.onIceCandidate.subscribe((c) => {
+      if (c) void host.addIceCandidate(c.toJSON());
+    });
+    await host.setLocalDescription(await host.createOffer());
+    await remote.setRemoteDescription(host.localDescription!);
+    await remote.setLocalDescription(await remote.createAnswer());
+    // The host is told a fingerprint the remote's certificate does not have.
+    const bogus = Array.from({ length: 32 }, () => 'AA').join(':');
+    await host.setRemoteDescription({
+      type: 'answer',
+      sdp: remote.localDescription!.sdp.replace(/a=fingerprint:(\S+) (\S+)/, `a=fingerprint:$1 ${bogus}`),
+    });
+    const reason = await new Promise<string>((resolve) => {
+      whenRemoteCertificateVerified(host, 'sha-256', () => resolve('verified'), resolve);
+    });
+    expect(reason).toMatch(/DTLS handshake ended (failed|closed)/);
+    await host.close();
+    await remote.close();
+  }, 20000);
+});

package/src/__tests__/operator-approval-gate.test.ts

@@ -0,0 +1,306 @@
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+import {
+  deriveIdentityId,
+  exportPublicKey,
+  generateIdentityKeyPair,
+  importPublicKey,
+  startDeviceReconnect,
+  type TReconnectFrame,
+} from '@robota-sdk/agent-remote-pairing';
+import { describe, expect, it, vi } from 'vitest';
+
+import { nextAdmissionStep } from '../admission-steps.js';
+import {
+  PairingGate,
+  type IConnectionApproval,
+  type IConnectionApprovalContext,
+  type IHostReconnectConfig,
+  type IPairingGateOptions,
+} from '../pairing-gate.js';
+
+import type { createSessionMessageHandler } from '@robota-sdk/agent-transport';
+
+/**
+ * A connection that would drive the session is the receiving operator's to allow, every time: the
+ * handshake proves who is on the other end, and the operator decides whether that device drives now.
+ * Until they say yes nothing reaches the session, and a device they refuse is not remembered.
+ */
+
+const FP = { localFingerprint: 'HOST:FP', remoteFingerprint: 'DEV:FP' };
+
+function deferred(): { promise: Promise<boolean>; resolve: (value: boolean) => void } {
+  let resolve!: (value: boolean) => void;
+  const promise = new Promise<boolean>((res) => {
+    resolve = res;
+  });
+  return { promise, resolve };
+}
+
+function makeGate(over: Partial<IPairingGateOptions> = {}) {
+  const sent: unknown[] = [];
+  let closed = false;
+  const channel = {
+    send: (d: string) => {
+      sent.push(JSON.parse(d));
+    },
+    close: () => {
+      closed = true;
+    },
+  };
+  const sessionOnMessage = vi.fn();
+  const createHandler: typeof createSessionMessageHandler = () => ({
+    onMessage: sessionOnMessage,
+    cleanup: vi.fn(),
+  });
+  const onAccept = vi.fn();
+  const onReject = vi.fn();
+  const fakeHandshake = (() => ({
+    result: Promise.resolve({ sessionKey: 'k' }),
+    onFrame: () => {},
+  })) as never;
+  const gate = new PairingGate({
+    channel,
+    session: createTestInteractiveSession(),
+    secret: 's',
+    role: 'initiator',
+    ...FP,
+    startHandshake: fakeHandshake,
+    createHandler,
+    onAccept,
+    onReject,
+    ...over,
+  });
+  return { gate, sent, closed: () => closed, sessionOnMessage, onAccept, onReject };
+}
+
+async function flush(): Promise<void> {
+  for (let i = 0; i < 5; i += 1) await Promise.resolve();
+}
+
+describe('operator approval of a driving connection', () => {
+  it('is the last step owed, after every proof the channel owes', () => {
+    const configured = { localPeer: {}, handoffGrant: {}, connectionApproval: {} };
+    expect(nextAdmissionStep({ connectionApproval: {} }, 'pairing')).toBe('operator-approval');
+    expect(nextAdmissionStep(configured, 'pairing')).toBe('local-proof');
+    expect(nextAdmissionStep(configured, 'local-proof')).toBe('handoff-grant');
+    expect(nextAdmissionStep(configured, 'handoff-grant')).toBe('operator-approval');
+    expect(nextAdmissionStep(configured, 'operator-approval')).toBe(null);
+  });
+
+  it('exposes nothing while the operator has not answered', async () => {
+    const answer = deferred();
+    const approve = vi.fn(() => answer.promise);
+    const { gate, sessionOnMessage, onAccept } = makeGate({ connectionApproval: { approve } });
+    await flush();
+    expect(approve).toHaveBeenCalledTimes(1);
+    gate.onInbound(JSON.stringify({ type: 'submit', prompt: 'p' }));
+    expect(sessionOnMessage).not.toHaveBeenCalled();
+    expect(onAccept).not.toHaveBeenCalled();
+
+    answer.resolve(true);
+    await vi.waitFor(() => expect(onAccept).toHaveBeenCalledTimes(1));
+    // What the peer said while waiting reaches the session only now, in order, then live frames.
+    expect(sessionOnMessage).toHaveBeenCalledTimes(1);
+    gate.onInbound(JSON.stringify({ type: 'get-messages' }));
+    expect(sessionOnMessage.mock.calls.map(([frame]) => JSON.parse(frame as string).type)).toEqual([
+      'submit',
+      'get-messages',
+    ]);
+  });
+
+  it('drops what the peer said while waiting when the operator refuses', async () => {
+    const answer = deferred();
+    const { gate, sessionOnMessage, onReject } = makeGate({
+      connectionApproval: { approve: () => answer.promise },
+    });
+    await flush();
+    gate.onInbound(JSON.stringify({ type: 'submit', prompt: 'p' }));
+    answer.resolve(false);
+    await vi.waitFor(() => expect(onReject).toHaveBeenCalledTimes(1));
+    expect(sessionOnMessage).not.toHaveBeenCalled();
+  });
+
+  it('withdraws the question and admits nothing when the channel closes while the operator decides', async () => {
+    const answer = deferred();
+    let signal: AbortSignal | undefined;
+    const approve = vi.fn((context: IConnectionApprovalContext) => {
+      signal = context.signal;
+      return answer.promise;
+    });
+    const { gate, sessionOnMessage, onAccept, onReject } = makeGate({
+      connectionApproval: { approve },
+    });
+    await flush();
+    gate.onInbound(JSON.stringify({ type: 'get-messages' }));
+    expect(signal?.aborted).toBe(false);
+
+    gate.onChannelClosed();
+    expect(signal?.aborted).toBe(true);
+    expect(onReject).toHaveBeenCalledTimes(1);
+
+    answer.resolve(true);
+    await flush();
+    expect(onAccept).not.toHaveBeenCalled();
+    expect(sessionOnMessage).not.toHaveBeenCalled();
+  });
+
+  it('does not pin an enrolling device whose channel closed while the operator decided', async () => {
+    const cfg = await hostConfig();
+    const answer = deferred();
+    const approve = vi.fn(() => answer.promise);
+    const { gate, onAccept } = makeGate({ reconnect: cfg, connectionApproval: { approve } });
+    gate.onInbound(JSON.stringify({ t: 'pair-nonce', nonce: 'n' }));
+    await flush();
+    const deviceKey = await generateIdentityKeyPair(false);
+    gate.onInbound(
+      JSON.stringify({ t: 'enroll-key', spki: await exportPublicKey(deviceKey.publicKey) }),
+    );
+    await vi.waitFor(() => expect(approve).toHaveBeenCalledTimes(1));
+    gate.onChannelClosed();
+    answer.resolve(true);
+    await flush();
+    expect(cfg.onEnroll).not.toHaveBeenCalled();
+    expect(onAccept).not.toHaveBeenCalled();
+  });
+
+  it('an accepted channel closing is the transport’s drop, not a refusal', async () => {
+    const { gate, onAccept, onReject } = makeGate({
+      connectionApproval: { approve: async () => true },
+    });
+    await vi.waitFor(() => expect(onAccept).toHaveBeenCalledTimes(1));
+    gate.onChannelClosed();
+    expect(onReject).not.toHaveBeenCalled();
+  });
+
+  it('refuses a peer that floods the channel while the operator decides', async () => {
+    const answer = deferred();
+    const { gate, closed, onReject, sessionOnMessage } = makeGate({
+      connectionApproval: { approve: () => answer.promise },
+    });
+    await flush();
+    for (let i = 0; i < 100; i += 1) gate.onInbound(JSON.stringify({ type: 'get-messages' }));
+    expect(onReject).toHaveBeenCalledTimes(1);
+    expect(closed()).toBe(true);
+    answer.resolve(true);
+    await flush();
+    expect(sessionOnMessage).not.toHaveBeenCalled();
+  });
+
+  it('refuses the connection the operator declines: closed, and the session never reached', async () => {
+    const { gate, closed, sessionOnMessage, onAccept, onReject } = makeGate({
+      connectionApproval: { approve: async () => false },
+    });
+    await vi.waitFor(() => expect(onReject).toHaveBeenCalledTimes(1));
+    expect(closed()).toBe(true);
+    gate.onInbound(JSON.stringify({ type: 'submit', prompt: 'p' }));
+    expect(sessionOnMessage).not.toHaveBeenCalled();
+    expect(onAccept).not.toHaveBeenCalled();
+  });
+
+  it('refuses when asking the operator fails', async () => {
+    const { closed, onAccept, onReject } = makeGate({
+      connectionApproval: { approve: () => Promise.reject(new Error('no terminal')) },
+    });
+    await vi.waitFor(() => expect(onReject).toHaveBeenCalledTimes(1));
+    expect(closed()).toBe(true);
+    expect(onAccept).not.toHaveBeenCalled();
+  });
+
+  it('does not accept an answer that arrives after the channel was torn down', async () => {
+    const answer = deferred();
+    const { gate, sessionOnMessage, onAccept } = makeGate({
+      connectionApproval: { approve: () => answer.promise },
+    });
+    await flush();
+    gate.cleanup();
+    answer.resolve(true);
+    await flush();
+    expect(onAccept).not.toHaveBeenCalled();
+    gate.onInbound(JSON.stringify({ type: 'submit', prompt: 'p' }));
+    expect(sessionOnMessage).not.toHaveBeenCalled();
+  });
+});
+
+async function hostConfig(over: Partial<IHostReconnectConfig> = {}): Promise<IHostReconnectConfig> {
+  const hostKeyPair = await generateIdentityKeyPair(true);
+  const hostPublicSpki = await exportPublicKey(hostKeyPair.publicKey);
+  return {
+    hostIdentityId: await deriveIdentityId(hostPublicSpki),
+    hostPublicSpki,
+    hostPrivateKey: hostKeyPair.privateKey,
+    resolveDevicePublicKey: async () => undefined,
+    onEnroll: vi.fn(),
+    ...over,
+  };
+}
+
+describe('operator approval with trusted-device enrollment', () => {
+  async function enrollingGate(approval: IConnectionApproval) {
+    const cfg = await hostConfig();
+    const made = makeGate({ reconnect: cfg, connectionApproval: approval });
+    made.gate.onInbound(JSON.stringify({ t: 'pair-nonce', nonce: 'n' }));
+    await flush();
+    const deviceKey = await generateIdentityKeyPair(false);
+    const deviceSpki = await exportPublicKey(deviceKey.publicKey);
+    made.gate.onInbound(JSON.stringify({ t: 'enroll-key', spki: deviceSpki }));
+    return { ...made, cfg, deviceSpki, deviceId: await deriveIdentityId(deviceSpki) };
+  }
+
+  it('asks about the device that enrolled, and pins it only once the operator allows it', async () => {
+    const approve = vi.fn(async () => true);
+    const { cfg, onAccept, deviceId, deviceSpki } = await enrollingGate({ approve });
+    await vi.waitFor(() => expect(onAccept).toHaveBeenCalledTimes(1));
+    expect(approve).toHaveBeenCalledWith(
+      expect.objectContaining({ deviceId, viaReconnect: false }),
+    );
+    expect(cfg.onEnroll).toHaveBeenCalledWith(deviceId, deviceSpki);
+  });
+
+  it('does not pin a device the operator refuses', async () => {
+    const { cfg, onReject } = await enrollingGate({ approve: async () => false });
+    await vi.waitFor(() => expect(onReject).toHaveBeenCalledTimes(1));
+    expect(cfg.onEnroll).not.toHaveBeenCalled();
+  });
+
+  it('asks again when a trusted device reconnects, naming it', async () => {
+    const keyPair = await generateIdentityKeyPair(false);
+    const spki = await exportPublicKey(keyPair.publicKey);
+    const deviceId = await deriveIdentityId(spki);
+    const publicKey = await importPublicKey(spki);
+    const cfg = await hostConfig({
+      resolveDevicePublicKey: async (id) => (id === deviceId ? publicKey : undefined),
+    });
+    const approve = vi.fn(async () => false);
+    let deviceCtrl!: ReturnType<typeof startDeviceReconnect>;
+    const onAccept = vi.fn();
+    const onReject = vi.fn();
+    const gate = new PairingGate({
+      channel: {
+        send: (d: string) => deviceCtrl.onFrame(JSON.parse(d) as TReconnectFrame),
+        close: () => {},
+      },
+      session: createTestInteractiveSession(),
+      secret: 's',
+      role: 'initiator',
+      ...FP,
+      reconnect: cfg,
+      connectionApproval: { approve },
+      onAccept,
+      onReject,
+    });
+    deviceCtrl = startDeviceReconnect({
+      deviceId,
+      hostIdentityId: cfg.hostIdentityId,
+      localFingerprint: FP.remoteFingerprint,
+      remoteFingerprint: FP.localFingerprint,
+      devicePrivateKey: keyPair.privateKey,
+      pinnedHostPublicKey: await importPublicKey(cfg.hostPublicSpki),
+      send: (frame) => gate.onInbound(JSON.stringify(frame)),
+      timeoutMs: 1000,
+    });
+    await deviceCtrl.result;
+    await vi.waitFor(() => expect(onReject).toHaveBeenCalledTimes(1));
+    expect(approve).toHaveBeenCalledWith(expect.objectContaining({ deviceId, viaReconnect: true }));
+    expect(onAccept).not.toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,152 @@
+/**
+ * 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';
+import type { RTCDataChannel } from 'werift';
+
+/** 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 = (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 werift's does on a closed channel. */
+function createDroppableChannel(): {
+  channel: RTCDataChannel;
+  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,
+  } as unknown as RTCDataChannel;
+  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({
+    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' }]);
+  });
+});