Two-way tunnel (wire protocol v2)

[edward-rosado]

Two-way tunnel (wire protocol v2)

Stacked on ItsRiprod#152. Review that one first — this branch targets it, so the diff here is only the v2 work. If ItsRiprod#152 lands, this retargets to main cleanly.

Why

v1 is one-directional in a specific way: only the device can open a stream, and every stream goes to one hardcoded destination on the computer (btbridge.swift's targetHost/targetPort, SERVER_ADDR in the Linux helper, SERVER_PORT in the Windows one). That makes an entire class of work impossible — no remote debugging, no log retrieval, no way to reach the device at all without a USB cable.

The device's firmware has no screencap, so today there is literally no way to see what's on its screen without pointing a camera at it.

What v2 adds

Either side can open a stream, and an OPEN says what it wants to reach.

• Stream IDs split by their high bit — device keeps 0x00000001…0x7FFFFFFF, the computer takes 0x80000001…0xFFFFFFFF. Both ends allocate without coordinating, and allocation wraps inside its own half. An OPEN arriving in the wrong half is refused: an ID collision would silently cross-wire two live TCP streams, which is a correctness and a confidentiality bug.
• HELLO carries version, capability bits, and the computer's clock. The Car Thing has no RTC and nothing else on it sets the time — a wrong clock fails every TLS handshake the device ever makes, in ways that look exactly like a tunnel bug.
• OPEN target descriptors — empty (the DeskThing server, unchanged from v1), a named service, or a literal host:port (defined but not yet accepted; that's the internet-sharing follow-up).
• OPEN_ACK distinguishes refused / unreachable / unknown-service / bad-namespace. A bare CLOSE can't tell "policy denied" from "device rebooted."

Backward compatibility, by construction

Three properties make a v1 and a v2 peer interoperate:

1. An empty OPEN payload keeps its v1 meaning. The existing golden vectors are unchanged and now serve as the compatibility proof.
2. A peer that never sends HELLO is treated as v1 — no inbound, no services offered.
3. An unknown frame type is skipped, not treated as a desync. Previously the Swift helper did rxBuf.removeAll() on an unknown type, which would discard the in-flight bytes of every other stream. That's fixed here.

Verified on hardware: a v2 helper against the still-v1 device (I can't reflash it without USB) reports inbound: false, offers no services, refuses a forward with a clear message, and carries Spotify exactly as before.

What it immediately unlocks

The cdp service forwards the device's chromium debugger to a loopback port on the computer:

POST /forward/open {"service":"cdp"}  →  {"ok":true,"port":51234}

Point chrome://inspect at that port and you are debugging the Car Thing over Bluetooth with no cable — and it's the only route to a screenshot of a device with no screencap.

Security

Default deny, enforced independently on both ends. This isn't hardening, it replaces a protection being removed: the hardcoded 127.0.0.1:8891 was the only thing standing between the device and everything on the computer's loopback.

• Named services only. The device is not a router, so 127.0.0.1:5037 (adb, unauthenticated) is inexpressible, not merely filtered — there is no parser to trick with 0177.0.0.1 or [::ffff:127.0.0.1].
• The descriptor parse is treated as a trust boundary and rejects malformed input rather than guessing. The rejection cases are locked in test_protocol.py.
• Port 8891 is permanently absent from the registry and must stay that way: it's the mux's own listener, so an inbound stream there would be handed to handle_local and forwarded back over the link — an unbounded loop that eats the entire 155 KB/s.
• Forwarded listeners bind loopback only, and are torn down when the radio link drops so nothing accepts a connection it can't serve.

Tests

• v2 golden vectors + descriptor-rejection table join the cross-implementation contract.
• A new suite drives the device mux's real inbound path against a fake radio: namespace rejection, unknown/malformed services, host:port refusal, the 8891 exclusion, HELLO exchange, stream bookkeeping, and a genuine end-to-end relay from a live local service.
• 36 vitest + 59 Python, all passing. Typecheck clean.

Honest limitations

• Linux and Windows are untested on hardware. They implement the same test-locked protocol. The Windows helper is type-checked with clang against stub Win32 headers (-Wall -Wextra clean), which catches signature and type errors but is not a substitute for running it.
• No UI in this PR. The forward is drivable over IPC (window.electron.bluetooth.openForward) and the control API. A Device Inspector panel is a natural follow-up, but the tunnel is the hard part and is worth reviewing on its own.

Both directions are now hardware-verified: the device runs the v2 btmux.py, and every screenshot in this PR was captured over Bluetooth through the inbound cdp service with no cable attached. The v2-computer ↔ v1-device compatibility direction was verified earlier, before the device was reflashed.

🤖 Generated with Claude Code

---

Added since opening: internet sharing

The tunnel being two-way makes one more thing possible, and it is on this
branch now.

The Car Thing has no route to the internet. With sharing switched on, the
computer becomes its exit node:

chromium --proxy-server=socks5://127.0.0.1:1080
   │
   ▼  SOCKS5 CONNECT
btmux.py  ──►  OPEN kind 0x02 (host:port)  ──►  helper  ──►  the internet

The device resolves nothing — hostnames ride the tunnel verbatim and the
computer resolves them, because the device has no resolver at all. Chromium
always does proxy-side DNS for socks5://, so no DNS server is needed anywhere.

The computer is the policy point, since the device is now pointing a socket
at whatever it likes:

• off by default, per-session, and reset whenever the link drops — this is
  deliberately not a persisted setting
• ports 80/443 only
• loopback, private, link-local and cloud-metadata ranges refused, re-checked on
  the resolved address so a hostname aimed at a private range is refused too
• the device may still only ask for the DeskThing server or the internet; named
  services on the computer stay unreachable

superbird/setup-browser-proxy.sh configures the browser once during
provisioning and can undo it (enable / disable / status, idempotent, keeps
a pristine backup). Its bypass list is not optional: this is Chromium 69,
which predates Chrome 72's implicit localhost bypass, so without it the client's
own http://localhost:8891 traffic would be proxied and the /__bt transport
probe would stop being answered locally — the badge would silently flip to USB.
The semicolons are quoted because ; starts a comment in supervisord's INI
parser.

Verified on hardware, over Bluetooth, with the USB path removed

adb reverse for the proxy port was deleted first, so nothing could cross USB:

• HTTPS 200 from the device (559 bytes, 0.27s)
• example.com rendered in the device browser
• a network image loaded and rendered
• with sharing off, the same request is refused — the gate holds
• the client's /__bt probe still returns {"transport":"bluetooth"}

13 new tests drive the device's real SOCKS handler: framing of the host:port
OPEN, the stream-id namespace, success/refused/unreachable replies, no payload
leaking on a refused stream, BIND rejected, and ack-waiter cleanup.

What this is not for

Video does not play on this device. The browser reports codec support it
does not have — a genuine VP8+Vorbis file fails with MediaError.code 4 even
served from 127.0.0.1 with no proxy in the path, while curl on the device
downloads the same file completely. Internet sharing is for reaching the
network; it will not get you a video player. See docs/device-debugging.md.

[edward-rosado]

Now verified end-to-end on hardware — and it caught two real bugs

Deployed v2 to the device and ran the full inbound path over Bluetooth with no cable. Both bugs below were invisible to the unit tests as written; both are fixed with regression coverage.

1. The helper crash-looped with SIGTRAP the instant the device answered HELLO. applyHello runs on the state queue (drainFrames dispatches there) and was calling q.sync on that same queue — a same-queue dispatch_sync, which GCD traps. Fixed by assigning directly, matching what the neighbouring PONG handler already does. I audited the other q.sync sites: they belong to the State and ServiceForwarder queues and are reached from other threads, so they're fine.

2. Inbound streams silently dropped the peer's first payload. Opening a local service is async, but the peer sends its request immediately after OPEN — so DATA arrived while open_connection was still in flight and was thrown away. The far end then waited forever for a reply to a request the device never saw. On hardware this looked like: chromium accepts the connection, then nothing. DATA is now parked while a stream is connecting and flushed once the socket is up; an early CLOSE abandons the pending open. The new test drives exactly that interleaving.

What now works over Bluetooth, cable-free

POST /forward/open {"service":"cdp"}  →  {"ok":true,"port":60000}

$ curl http://127.0.0.1:60000/json/version
{
   "Browser": "Chrome/69.0.3497.128",
   "webSocketDebuggerUrl": "ws://127.0.0.1:60000/devtools/browser/767c0a1b-..."
}

Capability negotiation reports inbound: true with two services offered; the device log shows inbound stream 2147483649 -> cdp (0x80000001 — the computer's namespace, exactly as designed). I then drove CDP over the tunnel and captured a 150 KB screenshot of the device's screen — something previously impossible, since the firmware has no screencap.

Music kept streaming the whole time; the link stayed up and the normal client stream was unaffected.

Also confirms an assumption from the internet-sharing design: the device really is Chrome 69, which is why browsing to modern YouTube in it won't work regardless of bandwidth.

36 vitest + 62 Python, typecheck clean.