Caddy reverse_proxy silently overwrites X-Forwarded-Proto unless the peer is in trusted_proxies

Symptom: an app behind Caddy renders http:// URLs even though the request arrived from an upstream TLS terminator that sent X-Forwarded-Proto: https. Nothing errors. The wrong scheme just propagates into whatever the app builds from that header -- redirects, absolute URLs, OAuth callbacks, or (in my case) a generated install script handed to every user.

Cause: Caddy 2's reverse_proxy SETS X-Forwarded-Proto (and -For, -Host) from the connection Caddy itself terminated. It preserves an INBOUND X-Forwarded-* only when the immediate peer appears in trusted_proxies, and the default for trusted_proxies is EMPTY. So with auto_https off -- a plain HTTP listener sitting behind someone else's TLS -- Caddy always stamps X-Forwarded-Proto: http over whatever the client sent.

How to prove it in 30 seconds instead of reading docs: replace the upstream with a tiny HTTP echo server on the same docker network using --network-alias <upstream-name>, then curl through Caddy and print the headers the upstream actually received. Sending the identical request straight at the real upstream (bypassing Caddy) is what tells you the app is fine and the proxy is the problem. That before/after pair is the whole diagnosis.

Fix, scheme only:

reverse_proxy upstream:8000 { header_up X-Forwarded-Proto {http.request.header.X-Forwarded-Proto} }

Measured after: inbound https -> https; inbound http -> http; header absent -> EMPTY header, so the app must treat empty as "fall back to the connection scheme" (e.g. hdr or request.url.scheme); a nonsense value like gopher is passed through unchanged, so keep the allow-list in the app rather than adding a second place that decides what a valid scheme is.

Why NOT trusted_proxies static private_ranges, which is the idiomatic answer: it also makes X-Forwarded-For appendable by any client in a private range. If your app resolves the real client IP by indexing from the RIGHT of XFF under a fixed hop count (common pattern: entries[-2] for a 2-proxy CDN->LB chain), a client that pre-seeds X-Forwarded-For: 203.0.113.9 lands in exactly that slot -- spoofable audit IPs and a bypassable per-IP rate limit. On a LAN-facing deployment every client IS in a private range, so this is not a theoretical trade-off. Verified that stock Caddy REPLACES an inbound XFF with the real peer, which is the safe default; fixing only the scheme by hand keeps it.

Side lesson: handle/handle_path blocks that each declare their own reverse_proxy will drift. Put the upstream in a Caddyfile snippet and import it from every route, so there is exactly one definition and the two paths cannot disagree.