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

package/src/__tests__/turn-test-client.ts

@@ -0,0 +1,256 @@
+/**
+ * A minimal TURN client over UDP for tests: it speaks just enough RFC 8656 to allocate, refresh,
+ * permit, bind channels and move data, and reports what the server answered.
+ */
+import { randomBytes } from 'node:crypto';
+import { createSocket, type Socket } from 'node:dgram';
+
+import {
+  StunAttr,
+  StunClass,
+  StunMethod,
+  attribute,
+  decodeChannelData,
+  decodeStun,
+  decodeXorAddress,
+  encodeChannelData,
+  encodeStun,
+  encodeXorAddress,
+  isChannelData,
+  longTermKey,
+  readErrorCode,
+  uint32,
+  type IStunMessage,
+  type ITransportAddress,
+} from '../stun-message.js';
+
+/** Like a real client's, it makes the first request as large as the challenge that answers it. */
+const SOFTWARE = { type: 0x8022, value: Buffer.from('agent turn test client') };
+
+export interface ITurnAnswer {
+  readonly ok: boolean;
+  readonly code?: number;
+  readonly message: IStunMessage;
+}
+
+export class TurnTestClient {
+  private realm?: string;
+  private nonce?: string;
+  private readonly waiting = new Map<string, (message: IStunMessage) => void>();
+  private readonly data: { from: ITransportAddress; payload: Buffer }[] = [];
+
+  private constructor(
+    private readonly socket: Socket,
+    private readonly server: ITransportAddress,
+    private readonly username: string,
+    private readonly password: string,
+  ) {
+    socket.on('message', (raw) => {
+      if (isChannelData(raw)) {
+        const frame = decodeChannelData(raw);
+        if (frame !== undefined) {
+          this.data.push({
+            from: { address: `channel`, port: frame.channel },
+            payload: frame.payload,
+          });
+        }
+        return;
+      }
+      const message = decodeStun(raw);
+      if (message === undefined) return;
+      if (message.cls === StunClass.Indication && message.method === StunMethod.Data) {
+        const peer = attribute(message, StunAttr.XorPeerAddress);
+        const payload = attribute(message, StunAttr.Data);
+        const from = peer && decodeXorAddress(peer, message.transactionId);
+        if (from && payload) this.data.push({ from, payload: Buffer.from(payload) });
+        return;
+      }
+      const key = message.transactionId.toString('hex');
+      this.waiting.get(key)?.(message);
+      this.waiting.delete(key);
+    });
+  }
+
+  public static async connect(
+    server: ITransportAddress,
+    username: string,
+    password: string,
+  ): Promise<TurnTestClient> {
+    const socket = createSocket('udp4');
+    await new Promise<void>((resolve) => socket.bind(0, '127.0.0.1', resolve));
+    return new TurnTestClient(socket, server, username, password);
+  }
+
+  /** Relayed data received so far. */
+  public received(): readonly { from: ITransportAddress; payload: Buffer }[] {
+    return this.data;
+  }
+
+  private exchange(message: Buffer, transactionId: Buffer): Promise<IStunMessage> {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error('no TURN answer')), 2_000);
+      this.waiting.set(transactionId.toString('hex'), (answer) => {
+        clearTimeout(timer);
+        resolve(answer);
+      });
+      this.socket.send(message, this.server.port, this.server.address);
+    });
+  }
+
+  /** Send an authenticated request, answering a 401/438 challenge once. */
+  public async request(
+    method: number,
+    attrs: { type: number; value: Buffer }[] = [],
+    transactionId: Buffer = randomBytes(12),
+    /** Attributes an on-path attacker appends after MESSAGE-INTEGRITY. */
+    appended: { type: number; value: Buffer }[] = [],
+  ): Promise<ITurnAnswer> {
+    // One transaction id throughout: the peer addresses in `attrs` are XORed with it.
+    for (let round = 0; round < 3; round += 1) {
+      const auth =
+        this.realm !== undefined && this.nonce !== undefined
+          ? [
+              { type: StunAttr.Username, value: Buffer.from(this.username) },
+              { type: StunAttr.Realm, value: Buffer.from(this.realm) },
+              { type: StunAttr.Nonce, value: Buffer.from(this.nonce) },
+            ]
+          : [];
+      const key =
+        this.realm !== undefined
+          ? longTermKey(this.username, this.realm, this.password)
+          : undefined;
+      const answer = await this.exchange(
+        withAppended(
+          encodeStun(method, StunClass.Request, transactionId, [...attrs, SOFTWARE, ...auth], {
+            ...(key !== undefined && auth.length > 0 ? { integrityKey: key } : {}),
+            fingerprint: appended.length === 0,
+          }),
+          appended,
+        ),
+        transactionId,
+      );
+      const code = readErrorCode(attribute(answer, StunAttr.ErrorCode));
+      const challenged = code === 401 || code === 438;
+      const realm = attribute(answer, StunAttr.Realm)?.toString();
+      const nonce = attribute(answer, StunAttr.Nonce)?.toString();
+      if (challenged && realm !== undefined && nonce !== undefined) {
+        const first = this.nonce === undefined || code === 438;
+        this.realm = realm;
+        this.nonce = nonce;
+        if (first) continue;
+      }
+      return {
+        ok: answer.cls === StunClass.Success,
+        ...(code !== undefined ? { code } : {}),
+        message: answer,
+      };
+    }
+    throw new Error('TURN challenge loop');
+  }
+
+  public allocate(
+    extra: { type: number; value: Buffer }[] = [],
+    transport = 17,
+  ): Promise<ITurnAnswer> {
+    return this.request(StunMethod.Allocate, [
+      { type: StunAttr.RequestedTransport, value: Buffer.from([transport, 0, 0, 0]) },
+      ...extra,
+    ]);
+  }
+
+  public refresh(lifetime: number): Promise<ITurnAnswer> {
+    return this.request(StunMethod.Refresh, [{ type: StunAttr.Lifetime, value: uint32(lifetime) }]);
+  }
+
+  /** Permit `peer`; `injected` is appended after MESSAGE-INTEGRITY, as an on-path attacker would. */
+  public permit(peer: ITransportAddress, injected?: ITransportAddress): Promise<ITurnAnswer> {
+    const transactionId = randomBytes(12);
+    return this.request(
+      StunMethod.CreatePermission,
+      [{ type: StunAttr.XorPeerAddress, value: encodeXorAddress(peer, transactionId) }],
+      transactionId,
+      injected === undefined
+        ? []
+        : [{ type: StunAttr.XorPeerAddress, value: encodeXorAddress(injected, transactionId) }],
+    );
+  }
+
+  public bindChannel(channel: number, peer: ITransportAddress): Promise<ITurnAnswer> {
+    const transactionId = randomBytes(12);
+    const number = Buffer.alloc(4);
+    number.writeUInt16BE(channel, 0);
+    return this.request(
+      StunMethod.ChannelBind,
+      [
+        { type: StunAttr.ChannelNumber, value: number },
+        { type: StunAttr.XorPeerAddress, value: encodeXorAddress(peer, transactionId) },
+      ],
+      transactionId,
+    );
+  }
+
+  /** Send data to `peer` through the relay in a Send indication. */
+  public sendTo(peer: ITransportAddress, payload: Buffer): void {
+    const transactionId = randomBytes(12);
+    this.socket.send(
+      encodeStun(StunMethod.Send, StunClass.Indication, transactionId, [
+        { type: StunAttr.XorPeerAddress, value: encodeXorAddress(peer, transactionId) },
+        { type: StunAttr.Data, value: payload },
+      ]),
+      this.server.port,
+      this.server.address,
+    );
+  }
+
+  public sendOnChannel(channel: number, payload: Buffer): void {
+    this.socket.send(encodeChannelData(channel, payload), this.server.port, this.server.address);
+  }
+
+  public close(): void {
+    this.socket.close();
+  }
+}
+
+/** `message` with `attrs` appended and its length updated. */
+function withAppended(message: Buffer, attrs: { type: number; value: Buffer }[]): Buffer {
+  if (attrs.length === 0) return message;
+  const parts = [message];
+  for (const { type, value } of attrs) {
+    const head = Buffer.alloc(4);
+    head.writeUInt16BE(type, 0);
+    head.writeUInt16BE(value.length, 2);
+    parts.push(head, value, Buffer.alloc((4 - (value.length % 4)) % 4));
+  }
+  const out = Buffer.concat(parts);
+  out.writeUInt16BE(out.length - 20, 2);
+  return out;
+}
+
+/** The relayed address in an Allocate success. */
+export function relayedAddress(answer: ITurnAnswer): ITransportAddress | undefined {
+  const value = attribute(answer.message, StunAttr.XorRelayedAddress);
+  return value && decodeXorAddress(value, answer.message.transactionId);
+}
+
+export function lifetimeOf(answer: ITurnAnswer): number | undefined {
+  return attribute(answer.message, StunAttr.Lifetime)?.readUInt32BE(0);
+}
+
+/** A plain UDP peer on loopback that records what reaches it. */
+export async function udpPeer(): Promise<{
+  readonly address: ITransportAddress;
+  readonly received: Buffer[];
+  send(to: ITransportAddress, payload: Buffer): void;
+  close(): void;
+}> {
+  const socket = createSocket('udp4');
+  await new Promise<void>((resolve) => socket.bind(0, '127.0.0.1', resolve));
+  const received: Buffer[] = [];
+  socket.on('message', (data) => received.push(data));
+  return {
+    address: { address: '127.0.0.1', port: socket.address().port },
+    received,
+    send: (to, payload) => socket.send(payload, to.port, to.address),
+    close: () => socket.close(),
+  };
+}

package/src/__tests__/webrtc-implementation.test.ts

@@ -0,0 +1,83 @@
+import { createIdentityContext } from '@robota-sdk/agent-remote-pairing';
+const testIdentity = createIdentityContext('test-product');
+/**
+ * The Node transport runs on `node-datachannel` (libdatachannel, DTLS by OpenSSL) and nothing else:
+ * where it cannot load, the transport is unavailable, never backed by another implementation.
+ */
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+
+import { describe, expect, it, vi } from 'vitest';
+
+import { loadDataChannel } from '../datachannel-loader.js';
+import { RtcPeer } from '../rtc-peer.js';
+import { createInMemorySignalingPair } from '../signaling.js';
+import { WebRtcTransport } from '../webrtc-transport.js';
+
+import type { IProtocolSession } from '@robota-sdk/agent-transport';
+
+const UNAVAILABLE = /WebRTC transport unavailable/;
+
+describe('the WebRTC implementation', () => {
+  it('is node-datachannel: the loader asks for that module only and returns it', () => {
+    const requested: string[] = [];
+    const real = createRequire(import.meta.url)('node-datachannel') as unknown;
+    const loaded = loadDataChannel((id) => {
+      requested.push(id);
+      return real;
+    });
+    expect(requested).toEqual(['node-datachannel']);
+    expect(loaded).toBe(real);
+    expect(loadDataChannel()).toBe(real);
+  });
+
+  it('is the only WebRTC implementation the package declares', () => {
+    const manifest = JSON.parse(
+      readFileSync(join(import.meta.dirname, '..', '..', 'package.json'), 'utf8'),
+    ) as {
+      dependencies?: Record<string, string>;
+      peerDependencies?: Record<string, string>;
+    };
+    expect(Object.keys(manifest.peerDependencies ?? {})).toEqual(['node-datachannel']);
+    expect(Object.keys(manifest.dependencies ?? {})).not.toContain('node-datachannel');
+  });
+
+  it('backs a real connection', () => {
+    const peer = new RtcPeer();
+    expect(peer.state).toBe('new');
+    peer.close();
+  });
+});
+
+describe('when node-datachannel cannot load', () => {
+  const missing = (): never => {
+    throw new Error("Cannot find module 'node-datachannel'");
+  };
+
+  it('the loader refuses, whether the module is absent or has no binding for this platform', () => {
+    expect(() => loadDataChannel(missing)).toThrow(UNAVAILABLE);
+    expect(() => loadDataChannel(() => ({}))).toThrow(UNAVAILABLE);
+  });
+
+  it('a connection refuses instead of being built on anything else', () => {
+    expect(() => new RtcPeer({ loadDataChannel: () => loadDataChannel(missing) })).toThrow(
+      UNAVAILABLE,
+    );
+  });
+
+  it('the transport start refuses and sends nothing', async () => {
+    const [signaling] = createInMemorySignalingPair();
+    const send = vi.spyOn(signaling, 'send');
+    const transport = new WebRtcTransport({cryptoContext: testIdentity,
+      signaling,
+      open: true,
+      openReason: 'implementation availability test',
+      loadDataChannel: () => loadDataChannel(missing),
+    });
+    transport.attach({} as IProtocolSession);
+    await expect(transport.start()).rejects.toThrow(UNAVAILABLE);
+    expect(send).not.toHaveBeenCalled();
+    await transport.stop();
+  });
+});

package/src/__tests__/webrtc-transport.test.ts

@@ -0,0 +1,349 @@
+import { createIdentityContext } from '@robota-sdk/agent-remote-pairing';
+const testIdentity = createIdentityContext('test-product');
+import { runTransportLifecycleConformance } from '@robota-sdk/agent-interface-transport/testing';
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+
+import { describe, expect, expectTypeOf, it, vi } from 'vitest';
+import type { IConfigurableTransport } from '@robota-sdk/agent-interface-transport';
+import type { IInteractiveSession } from '@robota-sdk/agent-interface-session';
+import type { IProtocolSession } from '@robota-sdk/agent-transport';
+
+import { HISTORY_PAGE_MAX_BYTES } from '@robota-sdk/agent-transport';
+import { WebRtcTransport } from '../webrtc-transport.js';
+import { createInMemorySignalingPair, type ISignalingClient } from '../signaling.js';
+import { WebRtcDeliveryLifecycle } from '../webrtc-delivery-lifecycle.js';
+import { RtcPeer } from '../rtc-peer.js';
+import { fakeDataChannel } from './fake-datachannel.js';
+
+/** Minimal stub session — only `getMessages` + no-op `on`/`off` are exercised by the get-messages round-trip. */
+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(),
+  });
+}
+
+/**
+ * The remote peer (answerer): consumes the host's offer via the injected signaling, opens the data channel,
+ * and speaks the `TClientMessage`/`TServerMessage` protocol. Resolves with the first `TServerMessage` received.
+ */
+function connectRemote(
+  signaling: ISignalingClient,
+  request: Record<string, unknown> = { type: 'get-messages' },
+): Promise<Record<string, unknown>> {
+  return new Promise((resolve, reject) => {
+    const peer = new RtcPeer();
+    peer.onLocalCandidate((c) =>
+      signaling.send({ kind: 'ice', data: { candidate: c.candidate, sdpMid: c.mid } }),
+    );
+    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') {
+            const sdp = await peer.acceptOffer(data.sdp!);
+            signaling.send({ kind: 'answer', data: { type: 'answer', sdp } });
+          } else if (message.kind === 'ice') {
+            peer.addRemoteCandidate({ candidate: data.candidate!, mid: data.sdpMid ?? '0' });
+          }
+        })
+        .catch(reject);
+    });
+    peer.onDataChannel((channel) => {
+      const ask = (): void => channel.send(JSON.stringify(request));
+      if (channel.readyState === 'open') ask();
+      else channel.onStateChange((state) => state === 'open' && ask());
+      channel.onMessage((text) => resolve(JSON.parse(text) as Record<string, unknown>));
+    });
+  });
+}
+
+describe('WebRtcTransport (REMOTE-002 Stage A — loopback)', () => {
+  it('accepts only the protocol session roles required by the carrier', () => {
+    const transport = new WebRtcTransport({cryptoContext: testIdentity,
+      signaling: createInMemorySignalingPair()[0],
+      open: true,
+      openReason: 'type compatibility test',
+    });
+    expectTypeOf(transport).toMatchTypeOf<IConfigurableTransport<IProtocolSession>>();
+    expectTypeOf(transport.attach).toEqualTypeOf<(session: IProtocolSession) => void>();
+  });
+
+  it('has the collapsed webrtc metadata and is disabled by default', () => {
+    const [sig] = createInMemorySignalingPair();
+    const t = new WebRtcTransport({cryptoContext: testIdentity,
+      signaling: sig,
+      open: true,
+      openReason: 'SEC-008: Stage-A loopback — this case is about signalling, not pairing',
+    });
+    expect(t.name).toBe('webrtc');
+    expect(t.defaultEnabled).toBe(false);
+  });
+
+  it('start() before attach() throws', async () => {
+    const [sig] = createInMemorySignalingPair();
+    const t = new WebRtcTransport({cryptoContext: testIdentity,
+      signaling: sig,
+      open: true,
+      openReason: 'SEC-008: Stage-A loopback — this case is about signalling, not pairing',
+    });
+    await expect(t.start()).rejects.toMatchObject({
+      name: 'TransportLifecycleError',
+      code: 'not-attached',
+    });
+  });
+
+  it('unpaired send failure closes the carrier and reports without escaping the session event', async () => {
+    const handlers = new Map<string, (value: unknown) => void>();
+    const session = createTestInteractiveSession({
+      on: ((event: string, handler: (value: unknown) => void) => {
+        handlers.set(event, handler);
+      }) as IInteractiveSession['on'],
+      off: ((event: string) => {
+        handlers.delete(event);
+      }) as IInteractiveSession['off'],
+    });
+    const closeChannel = vi.fn();
+    const fake = fakeDataChannel({
+      channel: {
+        sendMessage: () => {
+          throw new Error('unpaired channel closed');
+        },
+        close: closeChannel,
+      },
+    });
+    const onDeliveryError = vi.fn();
+    const onDropped = vi.fn();
+    const transport = new WebRtcTransport({cryptoContext: testIdentity,
+      signaling: { send: () => {}, onSignal: () => () => {}, close: () => {} },
+      open: true,
+      openReason: 'delivery lifecycle regression',
+      onDeliveryError,
+      onDropped,
+      loadDataChannel: () => fake.module,
+    });
+    transport.attach(session);
+    await transport.start();
+
+    expect(() =>
+      handlers.get('branch_event')?.({
+        kind: 'checkpoint_created',
+        checkpointId: 'turn-0001',
+        branchId: 'main',
+      }),
+    ).not.toThrow();
+    // The stream is reset after the channel's close grace.
+    await vi.waitFor(() => expect(closeChannel).toHaveBeenCalledTimes(1));
+    expect(onDeliveryError).toHaveBeenCalledWith(
+      expect.objectContaining({ message: 'unpaired channel closed' }),
+      'branch_event',
+    );
+    expect(onDropped).not.toHaveBeenCalled();
+    expect(handlers.size).toBe(0);
+    await transport.stop();
+  });
+
+  it('resets pairing and drop guards for every restart generation', () => {
+    const cleanup = vi.fn();
+    const onDropped = vi.fn();
+    const lifecycle = new WebRtcDeliveryLifecycle({
+      cleanup,
+      onDropped,
+      onDeliveryError: vi.fn(),
+    });
+
+    lifecycle.reset(1);
+    lifecycle.accept(1);
+    lifecycle.handleDrop(1);
+    lifecycle.handleDrop(1);
+    expect(cleanup).toHaveBeenCalledTimes(1);
+    expect(onDropped).toHaveBeenCalledTimes(1);
+
+    lifecycle.reset(2);
+    lifecycle.handleDrop(2);
+    lifecycle.accept(2);
+    lifecycle.handleDrop(1);
+    lifecycle.handleDrop(2);
+    expect(cleanup).toHaveBeenCalledTimes(2);
+    expect(onDropped).toHaveBeenCalledTimes(2);
+  });
+
+  it('ignores queued signaling, ICE, and channel callbacks from an older generation', async () => {
+    const sent: Array<{ readonly kind: string }> = [];
+    const signalHandlers: Array<(message: { kind: 'answer'; data: object }) => void> = [];
+    const setRemoteDescription = vi.fn();
+    const onDropped = vi.fn();
+    const signaling: ISignalingClient = {
+      send: (message) => sent.push(message),
+      onSignal: (handler) => {
+        signalHandlers.push(handler as (message: { kind: 'answer'; data: object }) => void);
+        return () => {};
+      },
+      close: () => {},
+    };
+    const fake = fakeDataChannel({ setRemoteDescription });
+    const transport = new WebRtcTransport({cryptoContext: testIdentity,
+      signaling,
+      secret: 'pairing-secret',
+      onDropped,
+      loadDataChannel: () => fake.module,
+    });
+    transport.attach(createStubSession());
+    await transport.start();
+    const oldSignal = signalHandlers[0]!;
+    const oldIce = fake.connections[0]!.localCandidate!;
+    const oldState = fake.connections[0]!.channelClosed!;
+
+    oldSignal({ kind: 'answer', data: { sdp: 'a=fingerprint:sha-256 BB' } });
+    await transport.stop();
+    transport.attach(createStubSession());
+    await transport.start();
+    oldIce('a=candidate:stale', '0');
+    oldState();
+    await Promise.resolve();
+
+    expect(setRemoteDescription).not.toHaveBeenCalled();
+    expect(sent.filter(({ kind }) => kind === 'ice')).toEqual([]);
+    expect(onDropped).not.toHaveBeenCalled();
+    await transport.stop();
+  });
+
+  it('invokes the shared lifecycle conformance suite', async () => {
+    const sent: Array<{ readonly kind: string }> = [];
+    const signaling: ISignalingClient = {
+      send: (message) => sent.push(message),
+      onSignal: () => () => {},
+      close: () => {},
+    };
+    const fake = fakeDataChannel();
+
+    await runTransportLifecycleConformance({
+      subjectId: '@robota-sdk/agent-transport-webrtc#WebRtcTransport',
+      kind: 'service',
+      createAdapter: () =>
+        new WebRtcTransport({cryptoContext: testIdentity,
+          signaling,
+          open: true,
+          openReason: 'ARCH-011 lifecycle conformance',
+          loadDataChannel: () => fake.module,
+        }),
+      createSession: createStubSession,
+      assertReady: () => {
+        if (!sent.some(({ kind }) => kind === 'offer')) throw new Error('offer not published');
+      },
+      assertStopped: () => {},
+    });
+  });
+
+  it('REMOTE-010: forceTurn → a relay-only connection, and a TURN url becomes a TURN server with its credentials', async () => {
+    // A fake module captures the configuration (a real relay-only peer with a dead TURN would never gather).
+    const fake = fakeDataChannel();
+    const [sig] = createInMemorySignalingPair();
+    const t = new WebRtcTransport({cryptoContext: testIdentity,
+      open: true,
+      openReason: 'SEC-008: Stage-A loopback — this case is about signalling, not pairing',
+      signaling: sig,
+      iceServers: [
+        { urls: 'turn:relay.example:3478', username: 'u', credential: 'c' },
+        { urls: 'stun:stun.example' },
+      ],
+      forceTurn: true,
+      loadDataChannel: () => fake.module,
+    });
+    t.attach(createStubSession());
+    await t.start();
+    expect(fake.connections[0]!.config).toEqual({
+      iceServers: [
+        {
+          hostname: 'relay.example',
+          port: 3478,
+          username: 'u',
+          password: 'c',
+          relayType: 'TurnUdp',
+        },
+        'stun:stun.example:3478',
+      ],
+      iceTransportPolicy: 'relay',
+      disableAutoNegotiation: true,
+    });
+    await t.stop();
+  });
+
+  it('contacts no ICE server unless one is configured', async () => {
+    const fake = fakeDataChannel();
+    const [sig] = createInMemorySignalingPair();
+    const t = new WebRtcTransport({cryptoContext: testIdentity,
+      open: true,
+      openReason: 'configuration test',
+      signaling: sig,
+      loadDataChannel: () => fake.module,
+    });
+    t.attach(createStubSession());
+    await t.start();
+    expect(fake.connections[0]!.config.iceServers).toEqual([]);
+    await t.stop();
+  });
+
+  it('TC-03: establishes an RTCDataChannel between two peers and round-trips TClient→session→TServer through the shared handler', async () => {
+    const [hostSig, remoteSig] = createInMemorySignalingPair();
+    const session = createStubSession();
+    const host = new WebRtcTransport({cryptoContext: testIdentity,
+      signaling: hostSig,
+      open: true,
+      openReason: 'SEC-008: Stage-A loopback — this case is about signalling, not pairing',
+    });
+    host.attach(session);
+
+    const remoteReply = connectRemote(remoteSig);
+    await host.start();
+
+    const reply = await remoteReply;
+    // The remote's `get-messages` reached the session via the reused handler; the host streamed back a
+    // `messages` TServerMessage carrying the stub session's messages — a full P2P round-trip, no network.
+    expect(reply.type).toBe('messages');
+    expect(reply.messages).toEqual([{ role: 'user', content: 'hi' }]);
+    expect(session.getMessages).toHaveBeenCalled();
+
+    await host.stop();
+  }, 15000);
+
+  it('refuses an app view larger than a history page on the open path, before the data channel is asked to carry it', async () => {
+    const [hostSig, remoteSig] = createInMemorySignalingPair();
+    const session = Object.assign(createStubSession(), {
+      readToolAppView: vi.fn().mockReturnValue({
+        sourceId: 'files',
+        resourceUri: 'ui://files/list',
+        mimeType: 'text/html;profile=mcp-app',
+        html: 'x'.repeat(HISTORY_PAGE_MAX_BYTES),
+        callableTools: {},
+      }),
+    });
+    const host = new WebRtcTransport({
+      cryptoContext: testIdentity,
+      signaling: hostSig,
+      open: true,
+      openReason: 'SEC-008: loopback — this case is about the frame limit, not pairing',
+    });
+    host.attach(session);
+
+    const remoteReply = connectRemote(remoteSig, {
+      type: 'read-app-view',
+      requestId: 'v1',
+      viewId: 'view-1',
+    });
+    await host.start();
+
+    expect(await remoteReply).toEqual({
+      type: 'protocol_error',
+      message: 'This app view is too large to send.',
+      requestId: 'v1',
+    });
+    await host.stop();
+  }, 15000);
+});
+