Plugin routes: only trust X-Forwarded-Host/-Proto when a trusted-proxy setting is on

[michielbdejong]

Raised while combining the server-plugin host branches (fediverse auth: atomic takes the URL from the Host header; atproto adds request.host).

Problem: a plugin handler's request.url / request.base follows X-Forwarded-Host. Any client can send that header, so a handler (or a signature check bound to the URL) can be pointed at a host the server doesn't serve.

Decision (engineering call, Claude atomic-server worker):

• Add a --trusted-proxies / ATOMIC_TRUSTED_PROXIES setting: the peer addresses or CIDRs whose X-Forwarded-* headers are honoured.
• Plugin routes and auth: atomic / dpop URL binding only use forwarded headers from a trusted proxy. Otherwise they use the dispatched Host, lowercased and without the port, and only hosts this server serves.
• The rest of the server keeps its current behaviour for now, because self-hosters behind a reverse proxy depend on it (see Server broken behind reverse-proxy #1318). Moving everything to the same rule is a follow-up, and it needs release notes.

Related: claude/plugin-atproto-host (request.host) and claude/plugin-fediverse-host (auth: atomic URL from Host). Both are being combined into candidate16.

[michielbdejong]

Setting format, to be documented with the change: ATOMIC_TRUSTED_PROXIES (flag --trusted-proxies) is a comma-separated list of IP addresses and/or CIDR ranges of the direct peer (the reverse proxy's address as the server sees it), e.g. 127.0.0.1, 127.0.0.1,::1 or 172.17.0.0/16. Unset means no proxy is trusted.

Known consumer: the user-testing droplet runs the e2e image behind Caddy on the host, publishing 127.0.0.1:8080. Inside Docker, Caddy's requests arrive from the bridge gateway (usually 172.17.0.1), not from 127.0.0.1, so usertest/server.sh should set ATOMIC_TRUSTED_PROXIES=172.17.0.1 (or 172.17.0.0/16). Use 127.0.0.1 only if the container runs with host networking. A log line at startup and a 400 with a clear message on refused forwarded headers will make a misconfiguration obvious.

[michielbdejong]

Implemented on claude/atomic-plugins-pin-candidate16 in 3830675 ("Plugin routes: believe X-Forwarded-Host/-Proto only from --trusted-proxies (#1903)").

Setting: --trusted-proxies / ATOMIC_TRUSTED_PROXIES. It takes comma-separated IP addresses or CIDR ranges of the direct peer, for example 127.0.0.1,10.0.0.0/8,fd00::/8. An IPv4-mapped IPv6 peer matches its IPv4 range. If it is unset, no peer is trusted. The server logs the list at startup, and a malformed entry stops it.

Plugin routes: request.url, request.base and request.host, and the URL that an auth: atomic or auth: dpop signature is bound to, all come from one function (route_exec::reached):

• X-Forwarded-Host and X-Forwarded-Proto count only from a trusted peer, and only their first value.
• From any other peer they are ignored. The dispatched Host counts instead, lowercased, with the configured scheme: the routes origin's scheme on an installation's own origin, the server's own scheme otherwise.
• A request with no Host at all uses the server's own origin.
• Forwarded is never read.
• Either way, the host has to be one this server serves: the routes origin and its installations, the API origin, or a drive's host name. Anything else gets a 400 route-host-refused before the plugin runs. The detail message points at --trusted-proxies.

The URL keeps the port the client used. request.host has no port.

This closes a hole in auth: atomic: before, it bound the URL to whatever Host arrived on a /_routes/ path. A proof made for another server could then be replayed here. auth: dpop now uses the same rule instead of the URL from config, so all of a drive's host names work.

The rest of the server is unchanged (#1318). Moving every endpoint to this rule is still a follow-up, with release notes.

Tests (in server/src/trusted_proxies.rs and server/src/plugins/route_crypto_test.rs):

• CIDR parsing and matching.
• Forwarded headers are ignored from an untrusted peer and honoured from a trusted one.
• An unserved host is refused: from a trusted proxy's X-Forwarded-Host, and in Host itself.
• An auth: atomic proof for another server is refused.

Docs: docs/src/atomicserver/installation.md, the "Plugin routes behind a reverse proxy" section.