#Remote access: security review

This is the security review #536 asks for before the remote-access relay is deployed for the first time. It was carried out on 2026-09-26 against three revisions, and every line reference below points at them:

• The relay: services/relay/ at commit 5325415 (#555, on main). worker.js, tunnel.js, protocol.js, auth.js and wrangler.toml refs are all under services/relay/.
• The tunnel client: crates/colonizer/src/remote.rs, plus its host_guard and /api/remote changes in crates/colonizer/src/main.rs, at commit a518798 — the #533 branch, unmerged at review time.
• Other cockpit refs (auth.rs, notify.rs, providers.rs, gateway/mod.rs, mesh.rs, util.rs, activity.rs under crates/colonizer/src/) are at main.

Method: code reading split by threat area — the relay edge, the frame protocol and tunnel, and the cockpit boundary — plus Node proof-of-concept runs against the shipped relay modules, and an independent re-check of every filed finding by a second reviewer.

Outcome: the cockpit's own fences hold for tunnelled traffic. No tunnelled request skips host_guard, nothing reaches loopback services the cockpit does not itself serve, and the Origin fence from #375 is pinned for the tunnel host rather than widened. The id, cookie and pairing design at the relay holds too. Five findings were filed as separate security issues; three of them (R1–R3) should block deployment.

#Status on main (re-checked 2026-09-27)

The tunnel client has since merged (#558, 61d4d8e), and the server was split into modules (#577): what the review cites in main.rs is now host_guard in crates/colonizer/src/server.rs:37-90 and the router in server.rs:226-236. remote.rs on main is the reviewed code with its line numbers moved by a few lines at most. The relay source is unchanged since 5325415 (only the pinned wrangler version moved, #560). The relay is still not deployed.

Every finding below is still open on main:

Since then (re-checked 2026-10-03). R1 is fixed: stripHopByHop now reads [name, value] pairs and keeps repeated set-cookie, with an end-to-end test that runs the real Rust client through the real relay (#618, PR #659). R2 is narrowed but not closed: Reset link now sends the old install a signed DELETE …/owner before replacing the key, so the old link loses its owner (reset_identity in remote.rs, #599, PR #663), but the old install stays registered at the relay, which still has no endpoint that deletes one. R3–R5 are unchanged: http_base still accepts ws:// for any host, the relay still passes Domain= through, the cockpit cookie still has no Secure (set_cookie_header in auth.rs), and ws_in and bodies are still unbounded channels.

Since then (re-checked 2026-10-05). R2, R3, R4 and R5 are fixed; each fix has tests that fail without it, and the whole link now runs end to end against the real relay code (the_whole_link_round_trips_through_the_real_relay in remote.rs, over services/relay/scripts/local-relay.mjs). The deployed Worker predates these fixes until it is redeployed.

How R3 was closed. The maintainer chose the link-scoped owner credential over the other options (pairing remote browsers as phones, which would have lost owner powers through the link; rotating the install token on reset; or accepting the relay's trust level in writing). What the relay can still see is a link credential, never the install token, and only until the next Reset link. Paired phones (cph_…) still work through the link as before: they are per-device and revocable, and remain phones.

No issue with any of the five R titles is in the public tracker as of 2026-09-27; if they were filed privately (as security advisories), this document cannot see them.

One more gap, found on the re-check and not a security finding: the mothership had no code for the relay's signed pairing endpoints. The cockpit called GET /api/remote/pairing and POST /api/remote/pairing/confirm (web/src/api.ts), but neither was a mothership route, so no install could bind an owner and the relay forwarded no one. #599 closes it: the mothership now serves the pairing routes, and confirming a code is refused through the tunnel (remote-tunnel.md). remote-tunnel.md lists every place the two halves depart from the pinned tunnel contract.

#Pairing with the pair code alone (#1086, 2026-10-06)

#1086 drops the relay's GitHub sign-in as a precondition. A new install's link now forwards a browser without any relay session when the request carries one of three things, and only these:

• a pairing invite, GET /?pair=<invite> (64 hex characters, at the root only);
• that invite page's claim poll, POST /api/phone/claim with its colonizer_pair cookie;
• a link credential (clk_…) or a paired phone's (cph_…), as the colonizer_token cookie or a bearer.

The relay recognises the shapes (services/relay/src/passthrough.js) but trusts none of them; the mothership's host_guard and phone.rs decide every one. Everything else gets the relay's own "Pair this device" page and never reaches the tunnel. The GitHub gate stays available as the require_github setting (local-only PUT /api/remote/require-github, relayed as a signed PUT /api/installs/<id>/settings): off for new installs, kept on for installs registered before the setting, and the owner binding and recovery work as before while it is on. A bound owner's GitHub session is forwarded in either mode.

R6, accepted by design: on the default setting, the mothership's own auth is the only gate on the invite and credential paths. Before #1086 the relay's owner check was a second layer in front of them (see The two boundary checks: "a second gate, not a substitute"). What carries those paths now:

Threat-model changes against the verdicts below:

The relay e2e (the_whole_link_round_trips_through_the_real_relay) now pairs a fresh browser through ?pair= and the six digits with no GitHub session, loads the cockpit and its websocket on the link credential alone, sends a forged and a revoked credential to the pair page, then switches the GitHub gate on and runs the owner flow behind it. The relay's own negative tests are in services/relay/test/pairing.test.mjs.

#Threat-model verdicts

#The two boundary checks #536 asks for

A tunnelled request cannot skip the cockpit's own auth. HTTP goes through serve_req → router.oneshot on the full router, where host_guard is layered after web_router is merged (main.rs:1634-1637; remote.rs:796). WebSockets go through an in-memory axum::serve of the same router with the Tunnelled extension layered outside it (remote.rs:605-607). Tunnelled is constructed only in remote.rs (:605, :795) and cannot come from a frame or a header; Authenticated / Via are inserted by host_guard itself, never read from headers; nothing in the crate uses ConnectInfo, so no handler trusts a peer address. The relay's GitHub sign-in is a second gate, not a substitute: the browser still needs the cockpit token.

A tunnelled request cannot reach loopback-only services the cockpit doesn't serve. The client opens TCP only to the relay — register and dial (remote.rs:288-300, :414-447); everything else is in-process. Two pre-existing settings reachable by any token holder do accept loopback URLs — the notify webhook (notify.rs:449-474) and a provider's base_url (providers.rs:512-527) — but the loopback services they could reach authenticate on their own (the gateway wants a per-colony token, gateway/mod.rs:626-641; headscale sits behind a 0700 socket and API keys, mesh.rs:245-296), so a remote token holder gains nothing a local one lacks. Blocking loopback and link-local targets there is hardening independent of remote access (sandbox-network.md covers the colony-side fence).

#Findings filed as separate security issues

The colony could file at most five issues; each finding was confirmed by code reading and re-checked independently. The titles are exact, so the issues can be found:

How each one works:

• R1. The client sends response headers as [name, value] pairs (remote.rs:800-807 at a518798); the relay's stripHopByHop iterates them as [index, pair] and throws (protocol.js:46-51), after #onRes has already cleared the head timer (tunnel.js:158-161). Every real response hangs, and after 32 the install answers 503. The relay's tests only use object-shaped headers, which is why the shipped modules pass their own suite.
• R2. reset_identity registers a new install but never retires the old one (remote.rs:245-263), and the relay has no endpoint to do so (worker.js:47-59). The old install stays owner-bound, so the phone's traffic to the old origin goes to whoever dials with the leaked key.
• R3. worker.js:224-230 forwards the colonizer_token cookie; a bearer skips the Origin fence (main.rs:961-966 at a518798); no code rotates the token (auth.rs:45-59); the ?token= sign-in path works through the tunnel (main.rs:1001-1014); and ws:// relays are accepted without a loopback restriction (remote.rs:319-327).
• R4. Installs are sibling subdomains of a domain that is not on the Public Suffix List, the relay passes Set-Cookie … Domain= through (protocol.js:23-66), and the cockpit's colonizer_token has no Secure (auth.rs:135-137). Impact is sign-in confusion or DoS on the victim's install, not takeover.
• R5. Unbounded channels (remote.rs:484, :493), default 64 MiB tungstenite messages (remote.rs:445-451), and base64 decoded before the size check (remote.rs:756-766): an authenticated browser can grow ws_in against a slow handler, and a relay can do worse.

#Lower-severity notes, not filed

Each was confirmed by code reading; L1 also by a proof-of-concept run.

• L1, Low — open redirect after sign-in. safeNext blocks // and /\ but not / followed by a tab (auth.js:81-85). next=%2F%09%2Fevil.example%2F becomes Location: /\t/evil.example/, which browsers resolve to https://evil.example/ right after a successful GitHub sign-in (auth.js:136, :152, :161). Fix: reject control characters, or resolve against the install's own origin and require it unchanged.
• L2, Low — unbounded registrations. POST /api/installs is unauthenticated beyond a per-IP limiter the code treats as optional (if (env.REGISTER_LIMITER)), and nothing ever deletes unowned installs; only pairings are purged (worker.js:61-87; auth.js:211-214). Fix: make the limiter mandatory and collect unowned, never-dialled installs.
• L3, Low — key directory mode and plaintext key. <config>/remote/ is created with a bare create_dir_all (umask, typically 0755; remote.rs:169, :275), and the key is plaintext PKCS#8 outside the COLONIZER_MASTER_KEY envelope (util.rs:109-137). The 0700 config directory protects it in the default layout, so this is defence in depth.
• L4, Low — WebSocket subprotocols cannot be negotiated. The relay keeps sec-websocket-protocol so the cockpit can negotiate (protocol.js:36-38), but the client strips every sec-websocket-* header (remote.rs:1051) and the relay accepts the browser with a bare server.accept() (tunnel.js:298).
• L5, Low — audit and error hygiene. remote.* activity entries record via: cockpit|api but not that the caller came through the tunnel, and error bodies returned through the tunnel include local filesystem paths (remote.rs:280-283).
• Also worth knowing: the short-lived __Host-colonizer_oauth cookie is forwarded to the cockpit (only the session cookie is stripped). Harmless, but unnecessary.

#Before the relay is deployed

• R1 fixed, with a relay e2e test that uses the Rust client's exact frame shape. Done in #659.
• R2 and R3 fixed, or the relay's trust level — it can read everything and act as the owner — accepted in writing. R2 is fixed (a787f94) and R3 too (7853719 and the link credential in #1030); R4 and R5 are fixed as well (8574073, 9e64ff4). The deployed Worker needs a redeploy to carry the relay-side halves.
• Deploy configuration: SESSION_SECRET set (the relay fails closed without it), REGISTER_LIMITER and DIAL_LIMITER bindings deployed, the real GITHUB_CLIENT_ID and D1 database_id in place of wrangler.toml's placeholders, and the GitHub OAuth app's wildcard callback matching enabled (services/relay/README.md, Deploy step 4).
• The tunnel-client half of this review re-run once #533 merges, since a518798 was unmerged at review time. (#533 merged as #558; the re-check above found every finding unchanged.)
• The mothership's side of pairing built, so an install can bind an owner at all (see Status on main above). Done in #599.