[chopratejas]

Description

The Rust front (crates/headroom-proxy) relays every request to the Python proxy from 127.0.0.1. The Python proxy treats a loopback caller as local: it skips the HEADROOM_PROXY_TOKEN check and serves /admin, /debug and /settings to it. The front had no inbound check of its own, listened on 0.0.0.0:8787 by default, and dropped x-headroom-proxy-token (as an x-headroom-* header), so a token set on the Python side neither protected the stack nor could be presented through the front.

This PR makes the Rust front apply the same token model as the Python proxy (read_proxy_token / scrub_proxy_token_headers in headroom/proxy/server.py, headroom/proxy/bind_policy.py) before anything is forwarded, and makes its default listen address loopback.

Fix adapted from a proposal by HetCreep.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update
• Performance improvement
• Code refactoring (no functional changes)

Changes Made

• New crates/headroom-proxy/src/inbound_auth.rs, installed as a router-wide layer (all routes, the catch-all and WebSocket upgrades) when HEADROOM_PROXY_TOKEN / --proxy-token is set:
  • a non-loopback peer (or one with no peer address) must send the token as X-Headroom-Proxy-Token or Authorization: Bearer; the explicit header wins, as in Python. Constant-time compare. Otherwise 401 {"error":"unauthorized"} and no upstream contact; a proxy_auth_rejected warning is logged (no credential values).
  • loopback peers are exempt (same as Python); GET /healthz, /healthz/upstream, /health, /livez, /readyz stay open; GET/HEAD /api/hello (also under /p/<project>) is answered locally with an empty 200, as Python does, instead of being relayed.
  • the token is removed before forwarding: x-headroom-proxy-token always, Authorization only when it carries the token (a provider credential is left alone).
  • the token is redacted from Debug output of Config.
• main.rs: startup bind policy, same rule and variable as Python: a non-loopback --listen with no token exits with code 2 and a message naming both remedies, unless HEADROOM_ALLOW_UNAUTHENTICATED_BIND=1 (then a warning is logged).
• config.rs: --listen / HEADROOM_PROXY_LISTEN default changes from 0.0.0.0:8787 to 127.0.0.1:8787; new --proxy-token (env HEADROOM_PROXY_TOKEN, value hidden from --help).
• RUST_DEV.md: runbook exports a token for the 0.0.0.0 cutover, flag table updated, new "Inbound authentication" section.

Behaviour change for operators: a Rust front started with --listen 0.0.0.0:... (or relying on the old default to be reachable from other hosts) now needs HEADROOM_PROXY_TOKEN set, and clients on other hosts must send it. Setups that front the port with something else that restricts access can set HEADROOM_ALLOW_UNAUTHENTICATED_BIND=1. Loopback clients (Claude Code, Codex, SDKs on the same host) are unaffected. The Docker image's entrypoint is the Python proxy, so it is unaffected.

Testing

• cargo test -p headroom-proxy (46 test binaries, 608 tests pass)
• cargo clippy -p headroom-proxy --all-targets -- -D warnings and cargo fmt --all -- --check clean
• New tests added for new functionality
• Manual testing performed
• pytest / ruff / mypy: N/A, no Python changes

New tests:

• tests/integration_inbound_auth.rs (11 tests, oneshot with an injected ConnectInfo so a non-loopback peer can be simulated, wiremock upstream): missing/wrong token is 401 and the upstream sees nothing; correct token via header or Bearer is forwarded without the token; provider Authorization kept when the header carries the token; loopback and IPv4-mapped loopback peers pass; missing peer address fails closed; health probes open but POST /readyz is 401; /api/hello answered locally; no token configured keeps passthrough.
• tests/integration_bind_policy.rs (3 tests, real binary): 0.0.0.0 with no token refuses to start; loopback starts; default --listen is loopback.
• unit tests in inbound_auth.rs for token parsing, constant-time compare, bind policy and exemptions.

Test Output

Before (the bind-policy test file copied onto a clean origin/main worktree; integration_inbound_auth.rs does not compile there since main has no token setting at all):

test default_listen_address_is_loopback ... FAILED
test loopback_listen_without_token_still_starts ... ok
test non_loopback_listen_without_token_refuses_to_start ... FAILED
test result: FAILED. 1 passed; 2 failed; 0 ignored; 0 measured; 0 filtered out; finished in 20.01s

After:

$ cargo test -p headroom-proxy --test integration_inbound_auth --test integration_bind_policy
test default_listen_address_is_loopback ... ok
test non_loopback_listen_without_token_refuses_to_start ... ok
test loopback_listen_without_token_still_starts ... ok
test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 2.01s
test missing_peer_address_fails_closed ... ok
test remote_peer_with_bearer_token_is_forwarded_without_it ... ok
test remote_peer_without_token_gets_401_and_upstream_is_not_contacted ... ok
test token_header_wins_over_a_provider_bearer ... ok
test no_token_configured_keeps_todays_passthrough ... ok
test loopback_peer_without_token_is_still_forwarded ... ok
test ipv4_mapped_loopback_peer_counts_as_loopback ... ok
test remote_peer_with_token_header_is_forwarded_without_it ... ok
test hello_probe_is_answered_locally_without_token ... ok
test remote_peer_with_wrong_token_gets_401 ... ok
test health_probes_stay_reachable_without_token ... ok
test result: ok. 11 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 1.74s

Real Behavior Proof

• Environment: macOS (Darwin 27.2), debug builds of headroom-proxy from origin/main (c21b081) and from this branch. Upstream is a small Python HTTP recorder on 127.0.0.1:18788 that prints each request it receives. Requests are sent with curl to the machine's LAN address (non-loopback peer) and to 127.0.0.1.
• Exact command / steps: HEADROOM_PROXY_TOKEN=s3cret HEADROOM_PROXY_STATS=false headroom-proxy --listen 0.0.0.0:18787 --upstream http://127.0.0.1:18788, then curl http://<lan-ip>:18787/admin/upstream with no token, a wrong token and the right token in x-headroom-proxy-token, GET /readyz with no token from the LAN address, and GET /v1/models from 127.0.0.1 with no token.
• Observed result:

== origin/main
GET /admin/upstream (no token)                     -> 200
GET /admin/upstream -H x-headroom-proxy-token:wrong -> 200
GET /admin/upstream -H x-headroom-proxy-token:s3cret -> 200
GET /readyz (no token)                             -> 200
GET /v1/models from 127.0.0.1 (no token)           -> 200
UPSTREAM SAW {"path": "/admin/upstream", "peer": "127.0.0.1", "token_hdr": null, "authorization": null}   (x3)
UPSTREAM SAW {"path": "/readyz", ...}
UPSTREAM SAW {"path": "/v1/models", ...}

== this branch
GET /admin/upstream (no token)                     -> 401
GET /admin/upstream -H x-headroom-proxy-token:wrong -> 401
GET /admin/upstream -H x-headroom-proxy-token:s3cret -> 200
GET /readyz (no token)                             -> 200
GET /v1/models from 127.0.0.1 (no token)           -> 200
UPSTREAM SAW {"path": "/admin/upstream", "peer": "127.0.0.1", "token_hdr": null, "authorization": null}   (only the authenticated one)
UPSTREAM SAW {"path": "/readyz", ...}
UPSTREAM SAW {"path": "/v1/models", ...}

$ headroom-proxy --listen 0.0.0.0:18787 --upstream http://127.0.0.1:18788   # no token
headroom-proxy: Refusing to listen on 0.0.0.0:18787: with no HEADROOM_PROXY_TOKEN this proxy would relay every network peer to the upstream Headroom proxy from 127.0.0.1, where it is treated as a trusted local caller. Either set HEADROOM_PROXY_TOKEN ... or ... set HEADROOM_ALLOW_UNAUTHENTICATED_BIND=1 to acknowledge the open bind.
(exit 2)

• Not tested: a full chain with the real Python proxy behind the Rust front (the recorder stands in for it); WebSocket upgrades through the gate are covered only by the layer wrapping the catch-all, not by a dedicated test.

Runtime Rollout Safety

• Rollout-managed feature(s): none
• Minimum rollout channel: N/A
• Stable/default behavior changed: yes, default listen address is now loopback, and a non-loopback listen needs a token or the acknowledgement variable
• Kill switch / disable path: HEADROOM_ALLOW_UNAUTHENTICATED_BIND=1 restores starting on a non-loopback address without a token; --listen 0.0.0.0:8787 restores the old address
• Unsafe override required: no
• Qualification impact: none (qualification scripts already pass --listen 127.0.0.1:<port>)
• Rollback path: revert this PR

Review Readiness

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

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• I did not edit CHANGELOG.md — it is generated by release-please from my Conventional Commit PR title (a CI guard enforces this)

Additional Notes

A companion PR makes the Rust front's native Bedrock and Vertex routes opt-in; it relies on this token gate for callers on those routes.

🤖 Generated with Claude Code

[github-actions]

PR governance

This PR does not yet satisfy the required template fields:

• Fill in Real Behavior Proof → Observed result.

Please update the PR body, or move the PR back to draft while it is still in progress.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[JerrettDavis]

The unresolved security findings need resolution before approval. With HEADROOM_PROXY_TOKEN set and the default Host rewrite, (1) a loopback request with Host: attacker.example and no token passes the Rust gate, and (2) a remote request with a valid token can reach /admin/upstream. Both are relayed to Python as a loopback peer with a loopback Host, so Python's local-only guard admits requests it would reject directly. Please preserve the original peer/Host trust boundary for local-only routes and add regression coverage with the real Python upstream, including foreign-Host loopback and authenticated remote admin requests. Expected: these requests cannot obtain local-only data; ordinary authenticated provider traffic still works. These are the existing unresolved discussion findings, not new regressions introduced by this patch. Please also qualify the statement that monitoring aggregates are available to anyone.

Validation: staged Rust CI reports success, but I could not independently run the integration tests because cargo is unavailable. The submitted real behavior proof uses a recorder and explicitly excludes the Python chain. Inherited workflow provenance holds are tracked separately and are not contributor defects.

[JerrettDavis]

The previous ordinary Host cases and monitoring docs are addressed, but the local-only boundary still has a scoped-IPv6 bypass. With a loopback Python upstream, a remote token holder can request GET /admin/upstream using Host: [::1%lo]:8787. Rust rejects the scoped literal as IpAddr and preserves it as supposedly non-loopback; Python accepts that Host as loopback, so its admin guard passes. I reproduced the actual Python guard: evil.example and headroom-remote.invalid return 404, while [::1%lo]:8787 is admitted, on both head and recorded main. The full Rust-to-Python chain was not executed. Please use the reserved non-loopback Host for every NonLocalCaller (or make classification conservatively cover Python forms), and add a scoped-IPv6 regression exercising Python denial. Expected: non-local callers cannot obtain local-only data even with a valid token. Rust tests could not run here because cargo is absent; head Rust CI was still running in the snapshot. Inherited workflow provenance holds are tracked separately.

[JerrettDavis]

The alias fix addresses the latest Devin finding, but the previously requested scoped-IPv6 repair remains unresolved. With a loopback Python upstream, a remote token holder can send GET /admin/upstream with Host: [::1%lo]:8787. The current helper still preserves that Host because Rust rejects the scoped literal; Python accepts it as loopback. The new effective-Host check also leaves it intact with --no-rewrite-host. Please conservatively prevent every non-local caller from being forwarded with a Python-loopback Host and add scoped-IPv6 regression coverage against the Python guard. Expected: a valid proxy token never grants local-only administration. Earlier review reproduced the Python guard admission; no full Rust/Python chain is claimed. Hosted Rust checks pass at this head; local cargo is unavailable. Inherited workflow provenance issues are tracked separately.