#201

docs: choose a named Cloudflare tunnel for remote access

Opencalledforthwants to merge intofrom

Records the remote-route decision for the first release.

Decision: a named Cloudflare tunnel, set up by the environment's owner (a tunnel token and a public hostname on their own Cloudflare zone). Quick tunnels (trycloudflare.com) are not built. Later, managed provisioning through the account service supplies the same two inputs, so the server runtime stays the same.

Why: a quick tunnel's hostname changes on every cloudflared restart. A phone away from the laptop has no way to learn the new address before the Wave 7 control plane exists, so every restart would mean sending each device a new address and running the route-merge consent prompt again. A Worker on workers.dev in front of the tunnel is ruled out because it would sit on the credential/terminal data path.

The new record, docs/decisions/cloudflare-tunnel.md, covers:

  • the personal setup steps and what the server does with the token and hostname: Host allowlist, the token kept as a secret file and passed by TUNNEL_TOKEN, a recurring check that a fresh single-use value sent to the hostname arrives at this process (and what that check cannot prove), failed-attempt budgets keyed by CF-Connecting-IP for tunnel traffic
  • implications for the pairing payload: no format change, a link for another device carries the tunnel route, the trust rules are unchanged, the server reporting the tunnel route so links don't fall back to loopback
  • implications for route merge: merged once at pairing, a hostname change is an owner action, server-reported routes stay on the authenticated handshake, the failure reasons already fit

docs/environment-routes.md now links to it from the server-reported routes section.

  • conditions managed provisioning must meet before it ships: on-machine ingress pinning, stopping the connector on unlink, and a threat-model update for the account service's added reach

Reviewed by gpt-6.1-sol and Fable. Their findings (an impostor could pass a self-check that compares environmentId, managed provisioning reaching beyond D6, the shared budget, the token as an interception secret, Access/Host header/allowed-origin setup, unreadable Cloudflare error pages) are fixed in the last two commits. One gpt-6.1-sol re-review followed, and its two remaining notes are fixed too.

Docs only, no code change.

🤖 Generated with Claude Code

Activity

15
greptile-apps[bot]24d ago


[Low risk] Documents a decision about Cloudflare tunnel setup.

This documentation-only PR appears safe to merge.

Summary

Records the decision to use an owner-managed, named Cloudflare tunnel for remote access.

  • Covers setup, token storage and leak recovery, reachability checks, pairing, and route merge.
  • Sets requirements for later managed provisioning.
  • Both prior findings are addressed: leak recovery includes device and owner credential rotation, and browser error handling now explains unreadable Cloudflare responses.
  • No new actionable issues found in the changes since the previous review.

Reviews (5) · Last reviewed commit: "docs: leave the routes doc to the tunnel..." · Reviewed by Greptile

greptile-apps[bot]reviewed24d ago
greptile-apps[bot]reviewed24d ago
calledforthreviewed23d ago
calledforthreviewed23d ago
greptile-apps[bot]reviewed23d ago
greptile-apps[bot]reviewed23d ago
calledforthreviewed23d ago
calledforthreviewed23d ago