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

package/src/__tests__/rtc-peer-candidates.test.ts

@@ -0,0 +1,61 @@
+/**
+ * An offering peer hands out its ICE candidates only once the answer is applied. With them earlier,
+ * the answerer can reach this side and start DTLS while the answer is still being applied, and the
+ * DTLS layer then refuses the peer's certificate for want of a fingerprint to check it against.
+ */
+import { describe, expect, it } from 'vitest';
+
+import { RtcPeer } from '../rtc-peer.js';
+
+import { fakeDataChannel } from './fake-datachannel.js';
+
+describe('RtcPeer local candidates', () => {
+  it('an offerer holds its candidates until the answer is applied, then hands them out in order', async () => {
+    const fake = fakeDataChannel();
+    const peer = new RtcPeer({ loadDataChannel: () => fake.module });
+    const handedOut: string[] = [];
+    peer.onLocalCandidate(({ candidate }) => handedOut.push(candidate));
+    peer.createDataChannel('x');
+    await peer.createOffer();
+    const native = fake.connections[0]!;
+
+    native.localCandidate!('a=candidate:1 1 UDP 1 10.0.0.1 1000 typ host', '0');
+    native.localCandidate!('a=candidate:2 1 UDP 1 10.0.0.2 2000 typ host', '0');
+    expect(handedOut).toEqual([]);
+
+    peer.acceptAnswer('a=fingerprint:sha-256 BB');
+    expect(handedOut).toEqual([
+      'candidate:1 1 UDP 1 10.0.0.1 1000 typ host',
+      'candidate:2 1 UDP 1 10.0.0.2 2000 typ host',
+    ]);
+
+    native.localCandidate!('a=candidate:3 1 UDP 1 10.0.0.3 3000 typ host', '0');
+    expect(handedOut).toHaveLength(3);
+    expect(peer.diagnostics().localCandidates).toBe(3);
+    peer.close();
+  });
+
+  it('an answerer hands out its candidates as they come, the offer being applied already', async () => {
+    const fake = fakeDataChannel();
+    const peer = new RtcPeer({ loadDataChannel: () => fake.module });
+    const handedOut: string[] = [];
+    peer.onLocalCandidate(({ candidate }) => handedOut.push(candidate));
+    await peer.acceptOffer('a=fingerprint:sha-256 AA');
+
+    fake.connections[0]!.localCandidate!('a=candidate:1 1 UDP 1 10.0.0.1 1000 typ host', '0');
+    expect(handedOut).toEqual(['candidate:1 1 UDP 1 10.0.0.1 1000 typ host']);
+    peer.close();
+  });
+
+  it('a closed peer never hands out the candidates it held', async () => {
+    const fake = fakeDataChannel();
+    const peer = new RtcPeer({ loadDataChannel: () => fake.module });
+    const handedOut: string[] = [];
+    peer.onLocalCandidate(({ candidate }) => handedOut.push(candidate));
+    await peer.createOffer();
+    fake.connections[0]!.localCandidate!('a=candidate:1 1 UDP 1 10.0.0.1 1000 typ host', '0');
+    peer.close();
+    peer.acceptAnswer('a=fingerprint:sha-256 BB');
+    expect(handedOut).toEqual([]);
+  });
+});

package/src/__tests__/session-attachment-app-view.test.ts

@@ -0,0 +1,66 @@
+/**
+ * A data channel carries a fraction of the inbound frame limit, and `channel.send` throws and closes
+ * the channel on a frame it cannot carry. An app view or app tool result is the one reply a session
+ * can make arbitrarily large, so the direct-handler path refuses one over a history page's worth
+ * before it reaches the channel.
+ */
+import { HISTORY_PAGE_MAX_BYTES } from '@robota-sdk/agent-transport';
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+import { describe, expect, it, vi } from 'vitest';
+
+import { attachSession } from '../session-attachment.js';
+
+import type { IPairingChannel } from '../pairing-gate-options.js';
+
+const view = {
+  sourceId: 'files',
+  resourceUri: 'ui://files/list',
+  mimeType: 'text/html;profile=mcp-app',
+  html: '<main>rows</main>',
+  callableTools: { list_files: 'mcp__files__list_files' },
+};
+
+function channel(): IPairingChannel & { sent: string[] } {
+  const sent: string[] = [];
+  return { sent, send: (data: string) => void sent.push(data), close: () => undefined };
+}
+
+function attachWith(readToolAppView: () => unknown) {
+  const target = channel();
+  const session = createTestInteractiveSession({
+    readToolAppView: vi.fn(readToolAppView) as never,
+  });
+  const attached = attachSession({ channel: target, session }, false, () => undefined);
+  return { target, attached };
+}
+
+describe('attachSession and the data channel frame limit', () => {
+  it('refuses an app view larger than a history page instead of sending it to the channel', () => {
+    const { target, attached } = attachWith(() => ({
+      ...view,
+      html: 'x'.repeat(HISTORY_PAGE_MAX_BYTES),
+    }));
+
+    attached.onSessionMessage(
+      JSON.stringify({ type: 'read-app-view', requestId: 'v1', viewId: 'view-1' }),
+    );
+
+    expect(target.sent.map((frame) => JSON.parse(frame))).toEqual([
+      { type: 'protocol_error', message: 'This app view is too large to send.', requestId: 'v1' },
+    ]);
+    attached.cleanup();
+  });
+
+  it('still sends an app view that fits', () => {
+    const { target, attached } = attachWith(() => view);
+
+    attached.onSessionMessage(
+      JSON.stringify({ type: 'read-app-view', requestId: 'v1', viewId: 'view-1' }),
+    );
+
+    expect(target.sent.map((frame) => JSON.parse(frame))).toEqual([
+      { type: 'app_view', requestId: 'v1', view },
+    ]);
+    attached.cleanup();
+  });
+});

package/src/__tests__/session-attachment-budget.test.ts

@@ -0,0 +1,136 @@
+/**
+ * ARCH-030 / issue #1734 — the replay path's backpressure budget REACHES production.
+ *
+ * `IAttachOptions.pendingBytes` existed with zero production callers: the bridge could take a
+ * carrier's backpressure reading and nothing gave it one, so the replay burst — the case the
+ * reopened scope names — ran unbudgeted while every other outbound path on the same connection was
+ * guarded.
+ *
+ * This case asserts the BEHAVIOUR, not the wiring. A test that checked the option reaches
+ * `bridge.attach` would have passed on the day the defect existed, because the option was reaching
+ * nothing on the way in. What can fail is a peer over budget going unclosed.
+ */
+import { DEFAULT_MAX_PENDING_BYTES, SessionResumeBridge } from '@robota-sdk/agent-transport';
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+import { describe, expect, it, vi } from 'vitest';
+
+import { attachSession } from '../session-attachment.js';
+
+import type { IPairingChannel } from '../pairing-gate-options.js';
+import type { IInteractiveSession } from '@robota-sdk/agent-interface-session';
+
+function fakeSession(): {
+  session: IInteractiveSession;
+  fire: (event: string, arg: unknown) => void;
+} {
+  const handlers = new Map<string, (arg: unknown) => void>();
+  const session = createTestInteractiveSession({
+    on: ((event: string, handler: (arg: unknown) => void) =>
+      handlers.set(event, handler)) as IInteractiveSession['on'],
+    off: ((event: string) => {
+      handlers.delete(event);
+    }) as IInteractiveSession['off'],
+  });
+  return { session, fire: (event, arg) => handlers.get(event)?.(arg) };
+}
+
+/** A channel whose backpressure the case controls, matching the optional structural slice. */
+function channelHolding(bytes: () => number): IPairingChannel & { sent: string[] } {
+  const sent: string[] = [];
+  return {
+    sent,
+    send: (data: string) => void sent.push(data),
+    close: () => undefined,
+    get bufferedAmount(): number {
+      return bytes();
+    },
+  };
+}
+
+describe('attachSession + the replay budget (ARCH-030)', () => {
+  it('attributes direct admitted WebRTC submissions to the remote surface', async () => {
+    const base = fakeSession().session;
+    const submit = vi.fn().mockResolvedValue(undefined);
+    const session = Object.assign(base, { submit });
+    const channel = channelHolding(() => 0);
+    const attached = attachSession({ channel, session, surface: 'remote' }, false, () => undefined);
+
+    attached.onSessionMessage(JSON.stringify({ type: 'submit', prompt: 'remote turn' }));
+    await vi.waitFor(() => expect(submit).toHaveBeenCalled());
+
+    expect(submit).toHaveBeenCalledWith('remote turn', undefined, undefined, {
+      surface: 'remote',
+    });
+    attached.cleanup();
+  });
+
+  it('exposes host usage reporting on the admitted direct handler path', async () => {
+    const { session } = fakeSession();
+    const channel = channelHolding(() => 0);
+    const report = { schemaVersion: 1 } as never;
+    const attached = attachSession(
+      { channel, session, personalUsageReporter: async () => report },
+      false,
+      () => undefined,
+    );
+
+    attached.onSessionMessage(
+      JSON.stringify({
+        type: 'get-personal-usage-report',
+        requestId: 'direct-usage',
+        period: '30d',
+        timezone: 'UTC',
+      }),
+    );
+    await expect.poll(() => channel.sent.length).toBeGreaterThan(0);
+
+    expect(channel.sent.map((frame) => JSON.parse(frame))).toContainEqual({
+      type: 'personal_usage_report',
+      requestId: 'direct-usage',
+      report,
+    });
+    attached.cleanup();
+  });
+
+  it('closes a peer that is over budget when the replay burst is attempted', () => {
+    const { session, fire } = fakeSession();
+    const bridge = new SessionResumeBridge({ session });
+    for (const delta of ['a', 'b', 'c']) fire('text_delta', delta);
+
+    let pending = 0;
+    const channel = channelHolding(() => pending);
+    const failures: string[] = [];
+    const attached = attachSession({ channel, session, resumeBridge: bridge }, true, (error) =>
+      failures.push(error.message),
+    );
+
+    // The peer has accepted a backlog it is not reading.
+    pending = DEFAULT_MAX_PENDING_BYTES + 1;
+    attached.onSessionMessage(JSON.stringify({ type: 'resume', lastSeq: 0 }));
+
+    expect(channel.sent).toHaveLength(0);
+    expect(failures).toHaveLength(1);
+    expect(failures[0]).toContain('pending');
+    attached.cleanup();
+    bridge.dispose();
+  });
+
+  it('replays normally while the peer is reading', () => {
+    // The companion the case above needs: without it, a budget that refused everything would pass.
+    const { session, fire } = fakeSession();
+    const bridge = new SessionResumeBridge({ session });
+    for (const delta of ['a', 'b', 'c']) fire('text_delta', delta);
+
+    const channel = channelHolding(() => 0);
+    const failures: string[] = [];
+    const attached = attachSession({ channel, session, resumeBridge: bridge }, true, (error) =>
+      failures.push(error.message),
+    );
+    attached.onSessionMessage(JSON.stringify({ type: 'resume', lastSeq: 0 }));
+
+    expect(channel.sent).toHaveLength(3);
+    expect(failures).toHaveLength(0);
+    attached.cleanup();
+    bridge.dispose();
+  });
+});

package/src/__tests__/turn-server-bind.test.ts

@@ -0,0 +1,59 @@
+/**
+ * Why the relay could not listen decides what the user changes, so a failed bind says its cause.
+ * The causes a test machine cannot reliably produce are injected here.
+ */
+import { EventEmitter } from 'node:events';
+
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+const bindErrors: NodeJS.ErrnoException[] = [];
+
+vi.mock('node:dgram', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('node:dgram')>();
+  return {
+    ...actual,
+    createSocket: (type: 'udp4') => {
+      const failure = bindErrors.shift();
+      if (failure === undefined) return actual.createSocket(type);
+      const fake = new EventEmitter() as EventEmitter & {
+        bind: (port: number, host: string, done: () => void) => void;
+        close: () => void;
+      };
+      fake.bind = () => {
+        setImmediate(() => fake.emit('error', failure));
+      };
+      fake.close = () => undefined;
+      return fake;
+    },
+  };
+});
+
+const { TurnServer } = await import('../turn-server.js');
+
+function errno(code: string): NodeJS.ErrnoException {
+  return Object.assign(new Error(`bind ${code}`), { code, syscall: 'bind' });
+}
+
+afterEach(() => {
+  bindErrors.length = 0;
+});
+
+describe('a relay that cannot listen', () => {
+  const authorize = (): Promise<undefined> => Promise.resolve(undefined);
+
+  it('says a privileged port needs privileges, keeping the error as its cause', async () => {
+    const failure = errno('EACCES');
+    bindErrors.push(failure);
+    const started = TurnServer.start({ host: '127.0.0.1', port: 80, authorize });
+    await expect(started).rejects.toThrow(/UDP 127\.0\.0\.1:80: .*privilege/);
+    await expect(started).rejects.toHaveProperty('cause', failure);
+  });
+
+  it('passes on a cause it has no words for', async () => {
+    const failure = errno('EPERM');
+    bindErrors.push(failure);
+    const started = TurnServer.start({ host: '127.0.0.1', port: 3478, authorize });
+    await expect(started).rejects.toThrow(/UDP 127\.0\.0\.1:3478: bind EPERM/);
+    await expect(started).rejects.toHaveProperty('cause', failure);
+  });
+});

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

@@ -0,0 +1,335 @@
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { randomBytes } from 'node:crypto';
+import { createSocket } from 'node:dgram';
+
+import {
+  StunAttr,
+  StunClass,
+  StunMethod,
+  attribute,
+  decodeStun,
+  encodeStun,
+  readErrorCode,
+} from '../stun-message.js';
+import { TurnServer, type ITurnServerOptions } from '../turn-server.js';
+import { TurnTestClient, lifetimeOf, relayedAddress, udpPeer } from './turn-test-client.js';
+
+const servers: TurnServer[] = [];
+const closers: (() => void)[] = [];
+
+afterEach(async () => {
+  for (const close of closers.splice(0)) close();
+  for (const server of servers.splice(0)) await server.close();
+});
+
+async function serve(over: Partial<ITurnServerOptions> = {}): Promise<TurnServer> {
+  const server = await TurnServer.start({
+    host: '127.0.0.1',
+    port: 0,
+    authorize: (username) =>
+      Promise.resolve(
+        username.startsWith('user-') ? { owner: username.slice(5, 6), password: 'pw' } : undefined,
+      ),
+    ...over,
+  });
+  servers.push(server);
+  return server;
+}
+
+async function client(
+  server: TurnServer,
+  username: string,
+  password = 'pw',
+): Promise<TurnTestClient> {
+  const created = await TurnTestClient.connect(server.address, username, password);
+  closers.push(() => created.close());
+  return created;
+}
+
+async function peer(): Promise<Awaited<ReturnType<typeof udpPeer>>> {
+  const created = await udpPeer();
+  closers.push(() => created.close());
+  return created;
+}
+
+describe('TURN server (RFC 8656 over UDP)', () => {
+  it('relays both ways: Send/Data indications, then ChannelData once a channel is bound', async () => {
+    const server = await serve();
+    const turn = await client(server, 'user-a1');
+    const allocated = await turn.allocate();
+    expect(allocated.ok).toBe(true);
+    const relayed = relayedAddress(allocated)!;
+    expect(relayed.address).toBe('127.0.0.1');
+    const remote = await peer();
+
+    // Nothing is relayed to or from a peer without a permission.
+    turn.sendTo(remote.address, Buffer.from('early'));
+    remote.send(relayed, Buffer.from('unasked'));
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    expect(remote.received).toEqual([]);
+    expect(turn.received()).toEqual([]);
+
+    expect((await turn.permit(remote.address)).ok).toBe(true);
+    turn.sendTo(remote.address, Buffer.from('to peer'));
+    await expect.poll(() => remote.received.map(String)).toEqual(['to peer']);
+    remote.send(relayed, Buffer.from('to client'));
+    await expect.poll(() => turn.received().map((d) => String(d.payload))).toEqual(['to client']);
+    expect(turn.received()[0]!.from).toEqual(remote.address);
+
+    expect((await turn.bindChannel(0x4001, remote.address)).ok).toBe(true);
+    turn.sendOnChannel(0x4001, Buffer.from('channel out'));
+    await expect.poll(() => remote.received.map(String)).toContain('channel out');
+    remote.send(relayed, Buffer.from('channel in'));
+    await expect
+      .poll(() => turn.received().map((d) => `${d.from.port}:${String(d.payload)}`))
+      .toContain(`${0x4001}:channel in`);
+  });
+
+  it('refuses what it does not do rather than half-doing it', async () => {
+    const server = await serve();
+    const turn = await client(server, 'user-a1');
+    expect((await turn.allocate([], 6)).code).toBe(442); // TCP relaying
+    expect(
+      (await turn.allocate([{ type: StunAttr.EvenPort, value: Buffer.from([0x80, 0, 0, 0]) }]))
+        .code,
+    ).toBe(420);
+    expect(
+      (
+        await turn.allocate([
+          { type: StunAttr.RequestedAddressFamily, value: Buffer.from([2, 0, 0, 0]) },
+        ])
+      ).code,
+    ).toBe(440);
+    expect((await turn.allocate()).ok).toBe(true);
+    // One allocation per 5-tuple.
+    expect((await turn.allocate()).code).toBe(437);
+    // Multicast is never a peer; loopback is only because this relay is on loopback.
+    expect((await turn.permit({ address: '224.0.0.251', port: 5353 })).code).toBe(403);
+    expect((await turn.bindChannel(0x3fff, { address: '127.0.0.1', port: 9 })).code).toBe(400);
+  });
+
+  it('attributes appended after MESSAGE-INTEGRITY count for nothing', async () => {
+    const server = await serve();
+    const turn = await client(server, 'user-a1');
+    expect((await turn.allocate()).ok).toBe(true);
+    // A genuine Refresh asks for the default lifetime; an attacker on the path appends LIFETIME 0.
+    const refreshed = await turn.request(StunMethod.Refresh, [], undefined, [
+      { type: StunAttr.Lifetime, value: Buffer.alloc(4) },
+    ]);
+    expect(refreshed.ok).toBe(true);
+    expect(lifetimeOf(refreshed)).toBe(600);
+    expect(server.allocationCount()).toBe(1);
+  });
+
+  it("never relays into the server's own port", async () => {
+    // A relay on loopback would otherwise let a client loop TURN into the server itself.
+    const server = await serve();
+    const turn = await client(server, 'user-a1');
+    expect((await turn.allocate()).ok).toBe(true);
+    expect((await turn.permit(server.address)).ok).toBe(true);
+    const before = server.allocationCount();
+    turn.sendTo(
+      server.address,
+      Buffer.from([0x00, 0x03, 0x00, 0x00, 0x21, 0x12, 0xa4, 0x42, ...Array<number>(12).fill(7)]),
+    );
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    // The server's answer to itself would have come back as data from the server's own address.
+    expect(turn.received()).toEqual([]);
+    expect(server.allocationCount()).toBe(before);
+  });
+
+  it('takes relayed ports from the configured range, and refuses once it is used up', async () => {
+    const probe = await udpPeer();
+    const min = probe.address.port;
+    probe.close();
+    const server = await serve({ relayPorts: { min, max: min + 1 } });
+    const ports: number[] = [];
+    for (const name of ['user-a1', 'user-b1']) {
+      const answer = await (await client(server, name)).allocate();
+      expect(answer.ok).toBe(true);
+      ports.push(relayedAddress(answer)!.port);
+    }
+    expect(ports.sort()).toEqual([min, min + 1]);
+    expect((await (await client(server, 'user-c1')).allocate()).code).toBe(508);
+  });
+
+  it('private and link-local peers can be ruled out; they are allowed by default', async () => {
+    const lan = { address: '192.168.1.20', port: 5000 };
+    const open = await client(await serve(), 'user-a1');
+    expect((await open.allocate()).ok).toBe(true);
+    expect((await open.permit(lan)).ok).toBe(true);
+
+    const closed = await client(await serve({ allowPrivatePeers: false }), 'user-a1');
+    expect((await closed.allocate()).ok).toBe(true);
+    for (const address of ['10.0.0.5', '172.16.4.4', '192.168.1.20', '169.254.1.1', '100.64.0.9']) {
+      expect((await closed.permit({ address, port: 5000 })).code).toBe(403);
+      expect((await closed.bindChannel(0x4002, { address, port: 5000 })).code).toBe(403);
+    }
+    expect((await closed.permit({ address: '203.0.113.9', port: 5000 })).ok).toBe(true);
+  });
+
+  it('an unknown username or a wrong password gets no allocation', async () => {
+    const server = await serve();
+    expect((await (await client(server, 'nobody')).allocate()).code).toBe(401);
+    expect((await (await client(server, 'user-a1', 'wrong')).allocate()).code).toBe(401);
+    expect(server.allocationCount()).toBe(0);
+  });
+});
+
+describe('TURN server — requests nobody authenticated', () => {
+  /** A raw datagram from a socket of its own; resolves with the answers it got. */
+  async function probe(
+    server: TurnServer,
+    datagrams: readonly Buffer[],
+  ): Promise<{ readonly answers: Buffer[] }> {
+    const socket = createSocket('udp4');
+    await new Promise<void>((resolve) => socket.bind(0, '127.0.0.1', resolve));
+    closers.push(() => socket.close());
+    const answers: Buffer[] = [];
+    socket.on('message', (data) => answers.push(data));
+    for (const datagram of datagrams) {
+      socket.send(datagram, server.address.port, server.address.address);
+    }
+    await new Promise((resolve) => setTimeout(resolve, 150));
+    return { answers };
+  }
+
+  function allocateRequest(padding: number): Buffer {
+    return encodeStun(StunMethod.Allocate, StunClass.Request, randomBytes(12), [
+      { type: StunAttr.RequestedTransport, value: Buffer.from([17, 0, 0, 0]) },
+      ...(padding > 0 ? [{ type: 0x8022, value: Buffer.alloc(padding, 0x61) }] : []),
+    ]);
+  }
+
+  it('are never answered with more than they carry: the relay cannot amplify a forged source', async () => {
+    const server = await serve();
+    // A bare request is smaller than any challenge: it goes unanswered.
+    const bare = allocateRequest(0);
+    expect((await probe(server, [bare])).answers).toEqual([]);
+    const bareBinding = encodeStun(StunMethod.Binding, StunClass.Request, randomBytes(12), [], {
+      fingerprint: false,
+    });
+    expect((await probe(server, [bareBinding])).answers).toEqual([]);
+
+    // One the size a WebRTC client sends gets its challenge, no larger than itself.
+    const sized = allocateRequest(20);
+    const { answers } = await probe(server, [sized]);
+    expect(answers).toHaveLength(1);
+    expect(answers[0]!.length).toBeLessThanOrEqual(sized.length);
+    expect(readErrorCode(attribute(decodeStun(answers[0]!)!, StunAttr.ErrorCode))).toBe(401);
+  });
+
+  it('are answered at a limited rate per source address and in all; the rest are dropped', async () => {
+    const burst = Array.from({ length: 10 }, () => allocateRequest(40));
+    // Every probe here comes from 127.0.0.1, one source address whatever its port; the clock
+    // stands still, so no budget refills between probes.
+    const now = Date.now();
+    const perSource = await serve({
+      now: () => now,
+      unauthenticatedLimits: { perSourcePerSecond: 3, totalPerSecond: 100 },
+    });
+    expect((await probe(perSource, burst)).answers).toHaveLength(3);
+    expect((await probe(perSource, burst)).answers).toHaveLength(0);
+
+    const inAll = await serve({
+      now: () => now,
+      unauthenticatedLimits: { perSourcePerSecond: 100, totalPerSecond: 4 },
+    });
+    expect((await probe(inAll, burst)).answers).toHaveLength(4);
+  });
+});
+
+describe('TURN server — a clock that steps back', () => {
+  it('drains no budget: unauthenticated answers and relayed data go on', async () => {
+    let now = Date.now();
+    const server = await serve({
+      now: () => now,
+      quotas: { bytesPerSecondPerOwner: 1_000 },
+      unauthenticatedLimits: { perSourcePerSecond: 3, totalPerSecond: 3 },
+    });
+    const turn = await client(server, 'user-a1');
+    expect((await turn.allocate()).ok).toBe(true);
+    const remote = await peer();
+    expect((await turn.permit(remote.address)).ok).toBe(true);
+
+    now -= 60 * 60 * 1000;
+    turn.sendTo(remote.address, Buffer.alloc(400, 1));
+    await expect.poll(() => remote.received.length).toBe(1);
+    now += 2_000;
+    // A new client still gets its challenge, and so an allocation.
+    expect((await (await client(server, 'user-b1')).allocate()).ok).toBe(true);
+  });
+});
+
+describe('TURN server — quotas', () => {
+  it('allocations per owner, and in all', async () => {
+    const server = await serve({ quotas: { allocationsPerOwner: 2, totalAllocations: 3 } });
+    for (const name of ['user-a1', 'user-a2']) {
+      expect((await (await client(server, name)).allocate()).ok).toBe(true);
+    }
+    expect((await (await client(server, 'user-a3')).allocate()).code).toBe(486);
+    expect((await (await client(server, 'user-b1')).allocate()).ok).toBe(true);
+    expect((await (await client(server, 'user-c1')).allocate()).code).toBe(508);
+    expect(server.allocationCount('a')).toBe(2);
+  });
+
+  it('relayed bytes per owner per second: what exceeds the budget is dropped', async () => {
+    const server = await serve({ quotas: { bytesPerSecondPerOwner: 1_000 } });
+    const turn = await client(server, 'user-a1');
+    expect((await turn.allocate()).ok).toBe(true);
+    const remote = await peer();
+    expect((await turn.permit(remote.address)).ok).toBe(true);
+    for (let i = 0; i < 10; i += 1) turn.sendTo(remote.address, Buffer.alloc(400, i));
+    await new Promise((resolve) => setTimeout(resolve, 200));
+    expect(remote.received).toHaveLength(2);
+  });
+
+  it('lifetime: a grant never exceeds the quota, and an allocation never outlives its age limit', async () => {
+    let now = Date.now();
+    const server = await serve({
+      now: () => now,
+      quotas: { maxLifetimeSeconds: 60, maxAllocationAgeMs: 90_000 },
+    });
+    const turn = await client(server, 'user-a1');
+    const allocated = await turn.allocate([
+      { type: StunAttr.Lifetime, value: Buffer.from([0, 0, 0x0e, 0x10]) },
+    ]);
+    expect(lifetimeOf(allocated)).toBe(60);
+    now += 50_000;
+    // 40 s of age are left; the refresh grants no more.
+    expect(lifetimeOf(await turn.refresh(3600))).toBe(40);
+    now += 41_000;
+    // Expired: refreshing now finds nothing of its own.
+    expect((await turn.refresh(3600)).ok).toBe(false);
+    expect(server.allocationCount()).toBe(0);
+  });
+
+  it('retain: an owner no longer named loses its allocations and cannot allocate again', async () => {
+    const server = await serve();
+    const turn = await client(server, 'user-a1');
+    expect((await turn.allocate()).ok).toBe(true);
+    server.retain(new Set(['b']));
+    expect(server.allocationCount()).toBe(0);
+    expect((await (await client(server, 'user-a2')).allocate()).code).toBe(403);
+  });
+});
+
+describe('TURN server — a bind that fails says why', () => {
+  it('the port is taken', async () => {
+    const holder = createSocket('udp4');
+    closers.push(() => holder.close());
+    await new Promise<void>((resolve) => holder.bind(0, '127.0.0.1', resolve));
+    const { port } = holder.address();
+    const started = serve({ port });
+    await expect(started).rejects.toThrow(`UDP 127.0.0.1:${port}: the port is taken`);
+    await expect(started).rejects.toHaveProperty('cause.code', 'EADDRINUSE');
+  });
+
+  it('the host is not an address of this machine', async () => {
+    // 192.0.2.0/24 is reserved for documentation (RFC 5737); no machine running this has it.
+    const started = serve({ host: '192.0.2.1' });
+    await expect(started).rejects.toThrow(/192\.0\.2\.1 is not an address of this machine/);
+    await expect(started).rejects.toHaveProperty('cause.code', 'EADDRNOTAVAIL');
+  });
+});