fix(dashboard): serve per-request metadata to trusted-gateway peers

[KennethWKZ]

Description

The dashboard's per-request metadata — the recent_requests / request_logs tail and the config block (which echoes upstream API URLs + backend settings) — is gated to loopback callers via _request_is_loopback. It requires both a loopback peer IP (request.client.host == 127.0.0.1) and a loopback Host header.

When Headroom runs in a bridge-network container (Docker/podman, or Apple Containerization / mocker), a browser on the host reaches the proxy through the container gateway, so request.client.host is the gateway IP (e.g. 172.18.0.1, or 192.168.64.1 on macOS vmnet), not 127.0.0.1. include_sensitive is therefore False, and the "Recent Requests" table renders empty even though the operator is browsing locally at http://127.0.0.1:8787/dashboard.

curl from inside the container (real 127.0.0.1 peer) confirmed the data is present and populated — only the host-browser path was being stripped.

The fix treats a peer inside an operator-configured trusted-gateway CIDR (HEADROOM_PROXY_TRUSTED_GATEWAY_CIDRS — the same allow-list already used by forwarded_headers.py to sanitize X-Forwarded-*) as loopback-equivalent, while retaining the loopback Host-header gate as the DNS-rebinding defence. It is opt-in and empty by default, so there is no behavior change unless the operator explicitly allow-lists their container gateway.

Closes #

Type of Change

• Bug fix (non-breaking change that fixes an issue)

Changes Made

• headroom/proxy/server.py — _request_is_loopback now: (1) always enforces the loopback Host-header gate first; (2) returns True for a genuine loopback peer; (3) additionally returns True for a peer inside HEADROOM_PROXY_TRUSTED_GATEWAY_CIDRS via the existing peer_is_trusted_gateway / load_trusted_gateway_cidrs helpers.
• tests/test_proxy_loopback_gating.py — added test_stats_metadata_served_to_trusted_gateway_peer: gateway peer stripped without the allow-list, served with it, and DNS-rebinding (non-loopback Host) still rejected even for a trusted gateway peer.
• CHANGELOG.md — Unreleased → Fixed entry.

Testing

• Unit tests pass (pytest)
• Linting passes (ruff check .)
• New tests added for new functionality
• Manual testing performed

Test Output

$ pytest tests/test_proxy_loopback_gating.py -q
14 passed, 1 warning in 3.56s

$ ruff check headroom/proxy/server.py tests/test_proxy_loopback_gating.py
All checks passed!

Real Behavior Proof

• Environment: Headroom 0.29.0 in a mocker compose (Apple Containerization) bridge container on macOS; host browser at http://127.0.0.1:8787/dashboard.
• Exact command / steps: before the fix, mocker compose exec headroom-proxy sh -c 'curl -s http://127.0.0.1:8787/stats' (peer = real 127.0.0.1) returned a populated recent_requests array, while the host browser saw an empty table. After adding HEADROOM_PROXY_TRUSTED_GATEWAY_CIDRS covering the container gateway and recreating, the host browser's dashboard shows the Recent Requests table again.
• Observed result: dashboard per-request table restored for the host browser; aggregate-only view unchanged for untrusted network callers.
• Not tested: IPv6 gateway CIDRs (the underlying peer_is_trusted_gateway supports them; not exercised in this environment).

Review Readiness

• I have performed a self-review
• This PR is ready for human review

Additional Notes

Pure opt-in: HEADROOM_PROXY_TRUSTED_GATEWAY_CIDRS is empty by default, so _request_is_loopback behavior is byte-identical to today unless an operator allow-lists a gateway CIDR. Reuses the existing trusted-gateway machinery rather than introducing a new config surface. Docs/compose examples intentionally omitted — deployment-specific.

[github-actions]

PR governance

This PR follows the template and is marked ready for human review.