Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

fix(cli): TURN-first P2P stops waiting out a peer's private addresses

reinSPQR5ec452fa03aa
diff --git a/cli/src/lib/terminalP2p.spec.ts b/cli/src/lib/terminalP2p.spec.ts
index aeef757b4..732280e6f 100644
--- a/cli/src/lib/terminalP2p.spec.ts
+++ b/cli/src/lib/terminalP2p.spec.ts
@@ -2,6 +2,7 @@ import { describe, expect, it, vi } from 'vitest'
import {
isRelayedPair,
readTurn,
+ relayCanReach,
TERMINAL_P2P_DOWN_TYPES,
TERMINAL_P2P_NEGOTIATION_TIMEOUT_MS,
TERMINAL_P2P_UP_TYPES,
@@ -267,6 +268,42 @@ describe('terminal WebRTC data channel', () => {
expect(isRelayedPair('candidate:1 1 udp 1 10.0.0.1 1 typ host raddr relay.example')).toBe(false)
})
+ describe('relayCanReach', () => {
+ const pair = (local: string, remote: string) =>
+ relayCanReach({ localCandidate: { type: local }, remoteCandidate: { host: remote } })
+
+ // The 8x4090's host candidates (its LAN card, Docker and libvirt bridges): Cloudflare refuses them,
+ // and waiting each one out cost the whole TURN-first negotiation (2026-10-20).
+ it('drops our relay paired with an address no TURN server can reach', () => {
+ for (const host of [
+ '192.168.86.22', '172.17.0.1', '172.18.0.1', '192.168.122.1',
+ '10.1.2.3', '172.31.255.255', '100.64.0.1', '100.127.255.254',
+ '127.0.0.1', '169.254.10.10', '0.0.0.0',
+ '::1', '::', 'fd7a:115c:a1e0::1', 'fc00::1', 'fe80::1', 'fe80::1%en0', '::ffff:192.168.1.1',
+ ]) expect(pair('relay', host), host).toBe(false)
+ })
+
+ it('keeps our relay paired with a public address', () => {
+ // 172.168/16 and 100.128/9 sit next to private ranges but are public: an office network uses 172.168.20.x.
+ for (const host of [
+ '42.96.33.130', '104.30.147.145', '172.168.20.132', '172.15.0.1', '172.32.0.1',
+ '100.63.255.255', '100.128.0.1', '2606:4700::1', '::ffff:42.96.33.130',
+ ]) expect(pair('relay', host), host).toBe(true)
+ })
+
+ it('keeps every pair our relay is not part of, so a LAN or a tailnet still connects directly', () => {
+ for (const local of ['host', 'srflx', 'prflx']) {
+ expect(pair(local, '192.168.86.22')).toBe(true)
+ expect(pair(local, '100.101.102.103')).toBe(true)
+ expect(pair(local, '127.0.0.1')).toBe(true)
+ }
+ })
+
+ it('leaves a named candidate to ICE', () => {
+ expect(pair('relay', '4c3b2a19-0d1e-4f5a-8b6c-7d8e9f0a1b2c.local')).toBe(true)
+ })
+ })
+
// Regression: a burst of sends (a chunked upload's chunks, fired back-to-back) can cross
// TERMINAL_P2P_MAX_BUFFERED_BYTES well before the real network drains the backlog — this is the
// wait this puts to use instead of every send() in that window being mistaken for a dead channel.
diff --git a/cli/src/lib/terminalP2p.ts b/cli/src/lib/terminalP2p.ts
index c8cc51a4c..9a605e452 100644
--- a/cli/src/lib/terminalP2p.ts
+++ b/cli/src/lib/terminalP2p.ts
@@ -1,4 +1,5 @@
import { randomUUID } from 'node:crypto'
+import { BlockList, isIP } from 'node:net'
import type { RTCPeerConnection, RTCDataChannel, RTCIceCandidateInit } from 'werift'
import { env } from '../config/env.js'
import { pickTurnUrl, selectStunUrls, type StunSelector } from './stunSelect.js'
@@ -158,12 +159,55 @@ function peerConfig(stunUrls: string[], turn?: TurnChoice, relayOnly = false): C
// pair is only ever nominated once every direct pair has failed. Setting 'relay' for every session
// would force it through Cloudflare — and bill for it; `relayOnly` is only ever a machine that
// reached nothing else last time.
+ iceFilterCandidatePair: relayCanReach,
// Terminal keyframes can approach 480 KiB. SCTP fragments them, but advertise enough room so
// the peer never rejects the message at the WebRTC API boundary before fragmentation happens.
maxMessageSize: 512 * 1024,
}
}
+/** Addresses no public TURN server can send to: private, carrier-grade NAT (Tailscale), loopback, link-local. */
+const UNREACHABLE_FROM_TURN = new BlockList()
+UNREACHABLE_FROM_TURN.addSubnet('0.0.0.0', 8, 'ipv4')
+UNREACHABLE_FROM_TURN.addSubnet('10.0.0.0', 8, 'ipv4')
+UNREACHABLE_FROM_TURN.addSubnet('100.64.0.0', 10, 'ipv4')
+UNREACHABLE_FROM_TURN.addSubnet('127.0.0.0', 8, 'ipv4')
+UNREACHABLE_FROM_TURN.addSubnet('169.254.0.0', 16, 'ipv4')
+UNREACHABLE_FROM_TURN.addSubnet('172.16.0.0', 12, 'ipv4')
+UNREACHABLE_FROM_TURN.addSubnet('192.168.0.0', 16, 'ipv4')
+UNREACHABLE_FROM_TURN.addAddress('::', 'ipv6')
+UNREACHABLE_FROM_TURN.addAddress('::1', 'ipv6')
+UNREACHABLE_FROM_TURN.addSubnet('fc00::', 7, 'ipv6')
+UNREACHABLE_FROM_TURN.addSubnet('fe80::', 10, 'ipv6')
+
+/**
+ * Keeps every pair but one kind: our TURN allocation paired with a peer address that no TURN server on
+ * the internet can reach. Those pairs can never connect, and with werift they used to cost the whole
+ * negotiation.
+ *
+ * Measured 2026-10-20 against the 8x4090 (Docker and libvirt bridges, so four private host candidates):
+ * Cloudflare answers a ChannelBind to a private peer with a 401 that carries no MESSAGE-INTEGRITY.
+ * werift drops that answer as unverified and retransmits until it times out, about 6.7s per peer, and
+ * it runs ChannelBinds one at a time. Four private peers ahead of the public one outlasted the 25s
+ * negotiation timeout, so every TURN-first negotiation died in `connecting` (0 of 14 in harness.log).
+ * With these pairs dropped, the same relay-only negotiation connected in about 1s, three times of three.
+ *
+ * Host-to-host pairs are kept, so two machines on one LAN or one tailnet still connect directly. If the
+ * backend ever hands out a TURN server inside the peer's own network, this filter has to go.
+ */
+export function relayCanReach(pair: { localCandidate: { type: string }; remoteCandidate: { host: string } }): boolean {
+ if (pair.localCandidate.type !== 'relay') return true
+ // A scope id (`fe80::1%en0`) is not part of the address.
+ let host = pair.remoteCandidate.host.split('%')[0]!
+ // An IPv4 address written as IPv6 (`::ffff:10.0.0.1`) is the IPv4 address.
+ const mapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/i.exec(host)
+ if (mapped) host = mapped[1]!
+ const family = isIP(host)
+ // A name (an mDNS `.local` candidate) is left to ICE: nothing here knows where it points.
+ if (family === 0) return true
+ return !UNREACHABLE_FROM_TURN.check(host, family === 4 ? 'ipv4' : 'ipv6')
+}
+
/** Shared by both sides: same validation, same reason. Anything malformed degrades to STUN-only. */
export function readTurn(value: unknown): TerminalP2pTurn | undefined {
if (!value || typeof value !== 'object') return undefined
diff --git a/cli/src/lib/terminalP2pTurnFirst.spec.ts b/cli/src/lib/terminalP2pTurnFirst.spec.ts
index f3c809557..5f3108351 100644
--- a/cli/src/lib/terminalP2pTurnFirst.spec.ts
+++ b/cli/src/lib/terminalP2pTurnFirst.spec.ts
@@ -1,21 +1,21 @@
import { expect, it, vi } from 'vitest'
// What the initiator hands werift, without negotiating: the peer connection is refused at construction.
-const configs: Array<{ iceTransportPolicy?: string }> = []
+const configs: Array<{ iceTransportPolicy?: string; iceFilterCandidatePair?: unknown }> = []
vi.mock('werift', () => ({
RTCPeerConnection: class {
- constructor(config: { iceTransportPolicy?: string }) {
+ constructor(config: { iceTransportPolicy?: string; iceFilterCandidatePair?: unknown }) {
configs.push(config)
throw new Error('construction is all this spec reads')
}
},
}))
-const { TerminalP2pInitiator } = await import('./terminalP2p.js')
+const { relayCanReach, TerminalP2pInitiator } = await import('./terminalP2p.js')
const turn = { urls: ['turn:turn.example:3478?transport=udp'], username: 'u', credential: 'c' }
-async function gatherPolicy(relayOnly: boolean, withTurn = true): Promise<string | undefined> {
+async function gather(relayOnly: boolean, withTurn = true): Promise<(typeof configs)[number] | undefined> {
let failed!: () => void
const done = new Promise<void>((resolve) => { failed = resolve })
const peer = new TerminalP2pInitiator({
@@ -29,7 +29,11 @@ async function gatherPolicy(relayOnly: boolean, withTurn = true): Promise<string
peer.start()
await done
await peer.stop('test_complete', false)
- return configs.pop()?.iceTransportPolicy
+ return configs.pop()
+}
+
+async function gatherPolicy(relayOnly: boolean, withTurn = true): Promise<string | undefined> {
+ return (await gather(relayOnly, withTurn))?.iceTransportPolicy
}
// Seen 2026-10-16: every negotiation to a machine only TURN reaches spent 8–10s on direct pairs first.
@@ -39,3 +43,9 @@ it('a TURN-first negotiation gathers relay candidates only; every other one gath
// Nothing to gather TURN-first without a TURN credential.
expect(await gatherPolicy(true, false)).toBeUndefined()
})
+
+// Seen 2026-10-20: TURN-first died 0 of 14 times waiting out the peer's private addresses (relayCanReach).
+it('every negotiation drops the relay pairs no TURN server can reach', async () => {
+ expect((await gather(true))?.iceFilterCandidatePair).toBe(relayCanReach)
+ expect((await gather(false))?.iceFilterCandidatePair).toBe(relayCanReach)
+})