diff --git a/docs/install.md b/docs/install.md index fbd8bfda..aa336da5 100644 --- a/docs/install.md +++ b/docs/install.md @@ -88,11 +88,13 @@ one; it does not touch that binary. | Service | Default | Flag | | --- | --- | --- | -| Web proxy (sign-in, web app, `/updates/`) | `0.0.0.0:8082` | `--web-port`, `--web-host` | +| Web proxy (sign-in, web app, `/updates/`) | port 8082, loopback + tailnet only | `--web-port`, `--web-host`, `--web-lan` | | Server API (no auth) | `127.0.0.1:8080` | `--port`, `--bind-address` | | ntfy | `:8090` | `--ntfy-port`, `--ntfy-url` | -Expose only the web proxy. A reinstall keeps the saved ports and bind +Expose only the web proxy. It listens on loopback and this machine's Tailscale +addresses unless you opt into the LAN; see +[network defaults](notes/network-and-update-signing.md). A reinstall keeps the saved ports and bind addresses unless you pass the flag again, so an installation set up with `--web-port 8083` stays on 8083. @@ -101,7 +103,8 @@ so the phone app's "Find servers on this network" lists it. The advertised port is the web proxy's (when it listens beyond loopback; the supervisor passes `-mdns-port`), or the server's own `-addr` port when that is a LAN address. TXT records: `v` (version), `name` (host), `path=/connect`, `tls=0`, -`auth=password|none`. Set `PIPELINES_MDNS=off` (or `-mdns=false`) to disable +`auth=password|none`, plus `ts=`/`public=` routes; without `--web-lan` the +advert carries no LAN route (`lan=0`, address records are the tailnet IPs). Set `PIPELINES_MDNS=off` (or `-mdns=false`) to disable it; a failure to advertise is logged and never stops the server. `PIPELINES_WEB_PUBLIC_URL` is the address phones and notification links use. @@ -111,7 +114,8 @@ Set it once; reinstalls keep it: PIPELINES_WEB_PUBLIC_URL=https://mymac.tailnet-name.ts.net ./install ``` -Without it the installer records `http://:`. Use HTTPS or a +Without it the installer records the tailnet IP (or `127.0.0.1`), or +`http://:` where LAN sign-in is allowed. Use HTTPS or a VPN for remote access; plain HTTP does not protect the password. ## Flags @@ -124,7 +128,9 @@ From `arguments()` in `scripts/setup-native.py`: | `--port N` | server API port (default 8080) | | `--bind-address IP` | server API bind (default `127.0.0.1`) | | `--web-port N` | web proxy port (default 8082) | -| `--web-host IP` | web proxy bind (default `0.0.0.0`) | +| `--web-host tailnet\|IP` | web proxy access: `tailnet` (default for new installs: loopback and Tailscale addresses only) or a literal IPv4 bind such as `0.0.0.0`; existing installs keep theirs and get a warning | +| `--web-lan` | also accept plain-HTTP LAN connections; sign-in over them stays refused | +| `--web-lan-plain-login` | allow sign-in over plain-HTTP LAN (unencrypted password and cookie; trusted networks only) | | `--ntfy-port N` | ntfy port (default 8090) | | `--ntfy-url URL` | ntfy address given to phones (default `http://:`) | | `--timezone TZ` | override the detected timezone (fallback UTC) | diff --git a/docs/notes/network-and-update-signing.md b/docs/notes/network-and-update-signing.md index 3034f20c..11d7ea29 100644 --- a/docs/notes/network-and-update-signing.md +++ b/docs/notes/network-and-update-signing.md @@ -1,5 +1,132 @@ # Network defaults and update-feed signing +## Where the web proxy listens + +Before this change `./install` bound the web proxy to `0.0.0.0` over plain +HTTP. With the macOS firewall off, anyone on the same café or hotel Wi-Fi could +reach the sign-in page, and the password and the 30-day session cookie crossed +that network unencrypted. The operator reaches the Mac over Tailscale +(`https://.ts.net:8443` through `tailscale serve` to `127.0.0.1:8083`, +and `ws://100.x:8083` from tank), so the LAN listener was not needed. + +### Defaults and opt-ins + +`web.host` in `pipelines-install.json` takes one of two forms: + +| `web.host` | Proxy flags (`manage.web_listen_args`) | Who can connect | +| --- | --- | --- | +| `tailnet` (new installs) | `--host :: --allow loopback,tailnet` | loopback and this machine's Tailscale IPv4/IPv6 addresses | +| `tailnet` with `web.lan: true` | `... --allow loopback,tailnet,lan` | also the LAN, but no sign-in or signed-in pages over plain HTTP | +| `tailnet` with `web.lan: true`, `web.lan_plain_login: true` | `... --lan-plain-login` | the LAN, with plain-HTTP sign-in (the old behaviour) | +| an IPv4 address, e.g. `0.0.0.0` | `--host 0.0.0.0` | whatever the bind reaches, unfiltered (the old behaviour) | + +Installer flags: `--web-host tailnet|IPv4`, `--web-lan` / `--no-web-lan`, +`--web-lan-plain-login` / `--no-web-lan-plain-login`. A reinstall keeps the +saved values unless you pass the flag again. `--web-lan` on an install that +still has a literal host moves it to `tailnet`. `--web-lan` together with an +explicit IPv4 `--web-host` is refused. + +On an opted-in LAN without `lan_plain_login`, a plain-HTTP LAN connection gets +`403` with an explanation for `POST /login`, `GET /login`, every signed-in +page, `/updates/`, `/api/*` and websocket upgrades. Only the public icons and +manifest are served. **Risk of `web.lan_plain_login`:** anyone on that network +who can watch the traffic sees the password and session cookie, and the cookie +works for 30 days. Use it only on a network you trust. `X-Forwarded-Proto` is +not trusted from the LAN, because a client can set it to anything. + +### Why the proxy binds the wildcard and filters each connection + +Tailscale often starts after the proxy (both start at login), and its address +can change. Binding the tailnet IP itself would fail at boot, and keeping it +working would need retry and rebind logic. Instead the proxy binds `::`, which +on macOS and Linux also accepts IPv4 (it falls back to `0.0.0.0` on a host +without IPv6). On every `connection` it drops the socket, before any HTTP is +read, unless **both** ends are loopback (`127/8`, `::1`) or **both** are +tailnet (`100.64.0.0/10`, `fd7a:115c:a1e0::/48`); see +`web/src/listenPolicy.js`. + +Both ends are checked because macOS uses the weak host model: it accepts a +packet addressed to its tailnet IP on any interface. A LAN host that spoofs a +tailnet source address cannot finish the TCP handshake, because the reply is +routed into the tunnel. + +The cost: a LAN scan sees the port open and immediately reset, and no HTTP is +served. One edge case is not handled: Tailscale subnet routes without SNAT +deliver peers with non-tailnet source addresses, and those are treated as LAN. + +### Discovery (mDNS) + +`manage.mdns_args` passes `-mdns-lan=false` when `web.host` is `tailnet` +without `web.lan`. `discovery.Plan` with `NoLAN` then makes these changes: + +- The A records are the tailnet IPv4 addresses, not the LAN ones. +- TXT gains `lan=0`, and `ts=` and `public=` stay. +- The port is still the proxy's, which answers on the tailnet. +- With no tailnet address, nothing is published (`ErrNotReachable`). + +The advert is still multicast on the LAN, so a tailnet client on the same Wi-Fi +finds the machine. `Browse` (Go, also behind `/api/discovery`) and the app's +`DiscoveredServer.fromRecord` drop the LAN route when `lan=0`, so the endpoint +becomes the first tailnet or public route. An older client still sees a "LAN" +route, but it points at the tailnet IP, which works from the tailnet. + +### Firewall + +The installer turns nothing on at the OS level. It only reads +`socketfilterfw --getglobalstate` and prints a recommendation when the firewall +is off. On this Mac on 2026-11-10 it reported `Firewall is disabled. +(State = 0)`. Recommendation: turn it on (System Settings > Network > +Firewall). The proxy no longer depends on it, but other local services +(ntfy on `:8090`, development servers) do. + +### Migration + +- **Live Mac** (`web.host: 0.0.0.0`, port 8083, public URL + `https://alans-macbook-pro.tail6bf4dc.ts.net:8443`): a plain `./install` + keeps `0.0.0.0` and prints + `WARNING: the web proxy listens on 0.0.0.0 over plain HTTP ... Recommended: ./install --web-host tailnet ...`. + To switch, run `./install --web-host tailnet` while no run or chat is active + (the install restarts the services). `tailscale serve` still reaches + `127.0.0.1:8083`, and tank's `ws://100.85.25.33:8083` is a tailnet + connection, so both keep working. Phones on the home Wi-Fi that saved + `ws://10.0.0.x:8083` must switch to the tailnet route (rediscover, or pick + the Tailscale address). +- **tank:** the same `./install --web-host tailnet`. Check first that every + client reaches it through Tailscale. +- An install whose recorded `PIPELINES_WEB_PUBLIC_URL` is a plain-HTTP LAN + address gets a warning to set it to the tailnet HTTPS address. + +### Verification (network) + +- `cd web && node --test test/`: `tests 24, pass 24, fail 0`. This includes + `listenPolicy.test.mjs`, which uses real sockets on this Mac's LAN (10.0.0.x) + and tailnet (100.85.25.33) addresses. +- `umask 022 && go test ./internal/discovery ./cmd/pipelines-server ./internal/server`: + all `ok`. This includes `TestPlanWithoutLANAdvertisesOnlyTailnetAndPublicRoutes` + and `TestBrowseOmitsTheLANRouteWhenTheAdvertSaysLan0`. +- `cd scripts && python3 -m unittest`: `Ran 229 tests ... OK (skipped=1)`. + This includes `test_web_access` and + `test_upgrade_keeps_an_all_interfaces_web_host_with_a_warning_and_lan_is_opt_in`. +- App: `tool/memwatch/full.sh 'test/features/updates test/features/onboarding test/features/settings'` + gave `PASS: 212 passed, 0 failed`, and `tool/analyze.sh` was clean. +- Scratch end-to-end: an isolated `HOME`, an OS-chosen port, real sign-in, and + the proxy started with `manage.web_listen_args` output: + +``` +== default loopback + tailnet: serve.mjs --port 53780 --host :: --allow loopback,tailnet +GET http://127.0.0.1:53780/login -> 200 POST -> 303 +GET http://100.85.25.33:53780/login -> 200 POST -> 303 +GET http://10.0.0.249:53780/login -> 000 (connection reset, curl exit 56) +== LAN opted in, no plain login: ... --allow loopback,tailnet,lan +GET/POST via 127.0.0.1 and 100.85.25.33 -> 200/303; via 10.0.0.249 -> 403/403 +== LAN with lan_plain_login: ... --lan-plain-login +GET/POST via 10.0.0.249 -> 200/303 +``` + +The live mDNS advert was not exercised, because a scratch server would publish +the same `Pipelines-` instance name as the live one. The records are +covered by `Plan`/`Zone` tests. + ## Update feed signing Before this change the app trusted whatever `/updates/` served: the Linux