Move an authorized Pocket session off the Relay onto a direct WebRTC channel

[nedtwigg]

After authorization, a Pocket session moves off the Relay onto a WebRTC data
channel — the same Noise session, the same counters, the same bounds, carried by
a direct connection between the two devices instead of by a server.

What a user gets

Latency. A keystroke stops making two hops through a relay that may be in
another region. On a LAN or a tailnet it goes straight to the laptop.

A Relay that cannot see the session. Relayed, it observes ciphertext sizes,
timing, volume, and specifically inter-keystroke timing. After the switch it
sees that the session exists and each end's liveness, and nothing else.

And a new way to lose a session, which is the honest cost. Once both
directions have switched there is no relay left to fall back to, so a channel
that dies ends the session: the phone leaves the wall and returning costs a
fresh handshake and one WebAuthn prompt. Before the switch a failed channel
costs nothing and the session stays relayed. The header names the live path and,
where it stayed relayed, which of three reasons it was.

Shape

Three layers, so the hardest invariant — preserving ciphertext order across two
transports — is stated once and testable on its own:

• remote-lib-common/src/security/direct-path.ts — the four signals, their
  guard, the bounds, and DirectCutover, the per-direction state machine both
  ends run. Pure; knows nothing about RTCPeerConnection.
• lib/src/remote/direct/direct-peer.ts — the RTCPeerConnection-shaped seam
  and one negotiation. Owns no policy.
• lib/src/remote/direct/direct-endpoint.ts — one policy, two ends.

Every signal rides inside the session as a padded control message, so the
Relay never sees an SDP, a candidate, or that a direct path was attempted. No
ICE servers at either end: host candidates only, LAN and tailnet, and an
unreachable peer simply stays relayed.

Scope

The standalone Burrow answers, over node-datachannel's polyfill loaded at the
first offer and never at boot. VS Code declines — platform-targeted VSIX
builds are staged under ## Future rather than shipping ~92 MB of native
binaries in a universal package.

Review trail

This branch was compared against a competing implementation, then reviewed four
times: a four-angle quality pass, a high-effort correctness pass, an independent
Codex review, and a three-agent pass over everything the earlier reviews had
themselves produced. Findings that produced fixes, rather than notes:

• A sender had no backpressure — a cat of a large file could overrun the
  runtime's send buffer, which on a switched session is burrow loss. Now a
  bounded queue with water marks and a drain.
• A switched end waited on its peer only until the holding queue overran, which
  is a function of how chatty the session is. Now its own deadline.
• Retiring a replaced session too early destroyed a healthy one on four failure
  paths, silently — a dismissed passkey prompt among them. Now it happens
  immediately before the one request that can race it.
• A decline could be sent onto a session its own give-up had already ended.
• The failure text an attempt gives up with — a runtime's exception string
  included — was one hop from a phone's screen. It is a closed cause set now,
  with the sentences owned by Pocket.
• Two claims in the specs asserted enforcement that does not exist on the
  shipped stack. Both were measured, both are now stated accurately, and the
  measured behaviour is pinned so a future addon version is noticed.

Testing

pnpm test green: 2901 lib, 171 vscode-ext, 96 standalone, 251 website, 266
remote-lib-common, 275 relay, 123 dor, and every lint including the e2e
self-test.

The direct path is driven end to end in process through both real runtimes, and
over the real addon with a real Noise session on a real SCTP association.
scripts/direct-interop/run.mjs is a manual fixture for the one combination no
CI job can reach — a real browser negotiating against the real addon. Measured
on macOS 26.0 with Chromium and libdatachannel 0.24.3: the browser's offer was
585 characters against the 2 000-character bound, both ends reported a
262 144-byte association, and 65 535/4 096/33-byte frames crossed
browser→addon→browser byte for byte and in order.

Known gaps, deliberately not closed here

• The latency claim is unmeasured. A tailnet dogfood with keystroke
  round-trip relayed vs. direct is staged in remote-api.md → Future.
• Network transitions are untested on a real phone. The laptop ranks its LAN
  address above its tailnet address, so a session that forms on WiFi likely
  picks the LAN pair and would break on a walk to cellular; one that forms on
  cellular should survive the reverse, since the tailnet address does not move.
  Preferring tailnet candidates is the cheap fix if the walk confirms it — held
  until it does, because ICE may already fail over on its own.

🤖 Generated with Claude Code

https://claude.ai/code/session_01ViV8RRXasxC1DMdNgqTKC8

[cloudflare-workers-and-pages]

Deploying mouseterm with    Cloudflare Pages

Latest commit:	14327ef
Status:	✅  Deploy successful!
Preview URL:	https://6cafe608.mouseterm.pages.dev
Branch Preview URL:	https://pocket-webrtc-2.mouseterm.pages.dev

View logs

[dormouse-bot]

One finding. Everything else I traced held up — the per-direction cutover ordering, the disposal of the peer on every path that ends a session at both ends, the queue bounds in both directions, and the new e2e-lint rules with their self-test entries.

An abandoned attempt leaves no diagnostic anywhere, and abandonment is the outcome the design expects whenever the direct path does not form. #giveUp uses reason only on its fatal branch; on the abandon branch it is computed and thrown away, at both ends. So every cause that resolves to DirectRelayCause: 'failed' — an SDP over MAX_DIRECT_SDP_LENGTH, a negotiation that threw, a channel refused at adopt, an association under NOISE_MAX_MESSAGE_LENGTH, a channel that never opened, a signal the session refused — collapses into one sentence on the phone ("A direct connection was tried and did not work.") and nothing at all in the operator's log. The fatal branch is the only one that reaches console.warn, which is the opposite of where the ambiguity is: burrow loss has a reason, an attempt that quietly stayed relayed does not.

That asymmetry bites hardest on the SDP bound, because it is the one cause that is a property of the user's machine rather than of the network. MAX_DIRECT_SDP_LENGTH is derived from CONTROL_PAYLOAD_SIZE, so it cannot be raised without changing the padded control body, and the measurement behind it — docs/specs/remote-api.rationale.md -> "What a browser and the addon actually negotiate" — is explicitly "one host candidate on a machine with one usable interface". docs/specs/remote-security-model.md -> "Direct path" states that the addon advertises each routable interface at its port, so the Burrow's answer grows with interface count: a laptop carrying WiFi, Ethernet, a tailnet and a couple of Docker bridges, v4 and v6 apiece, is in the region where the answer stops fitting. The attempt is once per session and never retried, so for that user the direct path never forms on any session, and the evidence they can report is a sentence that reads identically to "the network would not route".

The inline suggestion is the one-line version: log the reason where it is currently discarded, so the SDP case is separable from the rest in the field. Whether the bound itself wants headroom is a separate call, but the log is what would tell you it needs one.

[dormouse-bot]

Two findings on f843ff9d. The routing consolidation itself holds up: I traced the disposed-drops rule through both #sendApp loops, the Client's new per-session {route, direct} record against every path that sets or clears #established, and the switchOutbound idempotence claim against DirectPeer.#onOpen's if (this.#closed || this.#open) return; — the switch signal is sent before the cutover moves, so the old boolean was never the thing keeping a second switch off the wire, and the peer's guard is.

assertNothingInlined can no longer fail for the reason it exists. The old assertion was a presence check — each specifier had to appear as an external: true require-call edge — so a lost external entry made it go red. The new one is an absence check over SIDECAR_RUNTIME_DEPS, and that same list is what builds external. The two can now only be wrong together: move node-datachannel into optionalDependencies — where its own six @node-datachannel/* platform packages already live, so it is not a strange edit — and it drops out of external and out of names, esbuild inlines the addon, and the loop runs zero iterations and passes. external: [] is truthy, so even an empty derivation keeps the assertion wired up and vacuous. What ships is the burrow.cjs the docstring describes: one that "loads and then cannot find the addon's .node file, which nothing before the first direct-offer on a real machine would notice." The inline suggestion restores a loud failure for the one package the check is actually about; asserting the external require-call edge is still there, alongside the new inlined-input scan, would do the same job.

Related, whichever way that goes: docs/specs/standalone.md now reads "Every runtime dependency that manifest declares stays external", but the code reads dependencies only, and the six platform packages are declared under optionalDependencies. Nothing breaks — they are resolved by the external addon and never enter the bundle graph — but the sentence claims coverage the derivation does not have, so either it wants narrowing to dependencies or the derivation wants widening.

The second finding is the RELAYED_TRANSPORT comment; it is on the line.

[nedtwigg]

Both findings taken, in 14327ef3.

assertNothingInlined was vacuous. You're right that it can no longer fail for the reason it exists — deriving the assertion's names from the same manifest key that builds external means the two are only ever wrong together, and external: [] being truthy keeps the whole thing wired up and inert. I'd convinced myself the check was sound because I tested it by emptying the derived list and watched the build go red; that red was esbuild failing to resolve node-datachannel from the entry point's tree, not my assertion firing. Accident, not coverage.

Took the suggested guard. Confirmed it fires on exactly the edit you described — moving node-datachannel into optionalDependencies beside the six platform packages now fails the build with the guard's message rather than shipping a burrow.cjs that cannot find its .node.

Also narrowed the standalone.md sentence: the derivation reads dependencies, so claiming every runtime dependency was overclaiming while the platform packages sit under optionalDependencies.

RELAYED_TRANSPORT does not spare a render. Correct, and the comment was the wrong claim rather than a wrong constant — the setOnTransportChanged effect does setTransport({ path, cause }), a fresh object every time, so Object.is never matches and there is no bail-out to get. Took the suggested wording; the constant earns its place as one value for the initial state and the default prop, which is all it was ever doing.

On the earlier finding about #giveUp discarding its reason on the abandon branch — that shipped in a4b84c7f, before this pass.

[dormouse-bot]

Both landed as suggested, and the guard is in the right place: it runs at module top level, before bundles is built, so the failure is the build refusing to start rather than a bundle step reporting a clean metafile.

On the scope — one package rather than the derived list — I traced the other two dependencies entries against burrow.cjs's actual entry tree. detect-libc is resolved by the addon from its own node_modules, so an inlined copy in the bundle would not move what the addon loads; node-pty is never reached from remote/sidecar-entry.ts (the sidecar's unbundled main.js owns the PTYs), so it cannot be inlined there whatever external says. node-datachannel is the one entry whose __dirname-relative .node load is both reachable from this bundle and silent when it breaks, so guarding it alone is the right scope, not a remaining gap.

Approval stands; nothing further from me on this pass.