archy/.planning/APP-PORT-AUTH-GATE.md

App-port authentication gate — design

Item 1 of RELEASE-1.7.121-TASKS.md. Opened 2026-08-04.

"if I'm logged out I can reach every app port on tailscale and LAN, this can not be allowed… it must present the login to access the app with an app icon of what you're accessing to confirm, and 2FA if present" — operator, 2026-08-03

"make sure we fix FIPS, Tor, everything … umbrel definitely shows a port when you go to tailscale IP or other + port but demands the node login and 2FA if activated" — operator, 2026-08-04

---

What we already built, and why it did not close this

The operator's recollection that FIPS and Tor were "done" is correct — but that work was about reachability, and about restricting the daemon's own API. Neither one ever authenticated an app port. Read together, each transport got a door and none got a lock:

Layer	What exists today	What it protects
server.rs:1271 is_peer_allowed_path	Federated peers hitting the daemon port may only reach /health, /rpc/v1, /content, /blob/, /dwn/, /transport/inbox, /archipelago/*	The daemon's API surface. Not app ports.
fips/app_ports.rs APP_LAUNCH_PORTS	35 app ports allowed through the fips0 firewall	Nothing — it opens them
server.rs:1130 app_port_v6_relay_loop	Daemon relays mesh v6 → v4 loopback for those same ports	Nothing — it bridges them
api/rpc/tor/mod.rs:243	Per-app HiddenServicePort 80 → 127.0.0.1:<app port>	Nothing — it publishes them to an onion
container/quadlet.rs:261	PublishPort=0.0.0.0:{host}:{container}	Nothing — it binds every interface

So the app ports are reachable, by construction, over LAN, Tailscale, FIPS mesh and Tor, and nothing on any of those paths checks a session. This is the same bug class as the v1.7.120 /lnd-connect-info + /bitcoin-rpc/ leaks, but structural rather than per-endpoint.

The rule this design is built on

You cannot gate a socket you do not own. Every previous fix added a check beside the listener, which is why each one only covered the transport it was written for. The gate has to be the listener.

Design

Port numbers do not change. For an app whose UI port is P:

• The app binds 127.0.0.1:P only (PublishPort=127.0.0.1:P:<container>), so it is no longer reachable from any interface.
• The gate binds P on every external address — LAN IP, Tailscale IP, fips0 ULA — and on 127.0.0.2:P for Tor. 127.0.0.2 is a distinct loopback address, so it does not collide with the app on 127.0.0.1:P, and it means no app needs a second port number. torrc changes to HiddenServicePort 80 127.0.0.2:P.
• Upstream for the gate is always 127.0.0.1:P.

Because the gate owns the socket, LAN / Tailscale / FIPS / Tor are one code path. There is no per-transport work, and therefore no transport to forget.

Request handling

1. Read the session cookie. Cookies are host-scoped and port-agnostic, so the session minted on the dashboard is presented to <host>:P automatically — this is the same mechanism umbrel's "proxy token" relies on. (Scheme still matters: a Secure cookie will not travel to a plain-HTTP app port. See open questions.)
2. Valid session → proxy to 127.0.0.1:P, passing through Upgrade so WebSockets work.
3. No/invalid session → serve the login page on the app port itself, naming the app and showing its icon, POSTing back to the same origin. The gate verifies the password, enforces TOTP when enabled, and sets the session cookie — so logging in at <tailscale-ip>:P also logs you into the dashboard, exactly as umbrel behaves.
4. Non-browser clients get 401 with a JSON body rather than an HTML page.

What must NOT be gated

Non-HTTP ports cannot carry a cookie and must be declared, not discovered: electrum 50002, bitcoin p2p 8333, LND gRPC 10009/9735. These need an explicit manifest field (auth: none + rationale) so the exception list is a grep, and they are a firewall/allowlist question, tracked separately.

Note api/rpc/tor/mod.rs:238-240 already special-cases lnd's 9735/10009 as is_protocol_service — that distinction is the seed of the manifest field.

Deploy traps this walks into

• Three copies of every container spec — apps/<id>/manifest.yml, scripts/container-specs.sh, scripts/first-boot-containers.sh. Changing PublishPort in one leaves fresh installs broken while the node looks fixed. This is exactly what bit lnd-ui (item 4). Deduplicating these is arguably a prerequisite, not a follow-up.
• Changing PublishPort drifts every app → one-time recreate fleet-wide.
• The gate must rebind when addresses change (Tailscale up/down, DHCP, fips0 re-key). Precedent exists: peer_late_bind_loop in server.rs already does this for fips0.
• Verify on the node, not from source. v1.7.120's headline bug was a fix that shipped in the binary and never reached the running container.

Open questions for the operator

1. Machine clients. Umbrel's real-world failure mode: Home Assistant (or any API client) hitting an app's API has no cookie and breaks. Browser-only, or do we mint per-app long-lived tokens?
2. TLS/scheme. The daemon serves plain HTTP with nginx terminating TLS in front. If the dashboard is HTTPS and app ports are HTTP, a Secure session cookie will not be sent — the gate would prompt for login every time. Either the gate serves TLS on app ports too, or app ports are HTTP-only on such nodes.

Sequencing

1. Gate module + login page + proxy, behind an env opt-in.
2. Prove on one HTTP app on .228, across all four transports.
3. Dedupe the container-spec declarations.
4. Roll to all HTTP apps; declare the non-HTTP exceptions.
5. Repoint torrc at 127.0.0.2.