[chopratejas]

Description

The provider routes (/v1/messages, /anthropic/v1/messages, /v1/chat/completions, /v1/responses, Bedrock/Vertex routes and the catch-all passthrough) add operator-held credentials to what they forward: *_extra_headers, the Copilot token (apply_copilot_api_auth), and the provider env key on the litellm/anyllm backends when the request carries none. Loopback callers skip HEADROOM_PROXY_TOKEN, and a page open in the user's browser reaches the proxy as a loopback caller. It can send a JSON body as Content-Type: text/plain, which needs no CORS preflight, and the proxy parses and forwards it. CORS only stops the page from reading the answer, not the proxy from sending the request. Only the WebSocket routes checked Origin.

The security gate now applies the WebSocket Origin rule to every HTTP request, before routing. A request is refused with 403 when it carries an Origin that is not:

• a loopback page (http(s)://127.0.0.1|localhost|[::1] on any port; this is the dashboard),
• an origin listed in HEADROOM_WS_ORIGINS / HEADROOM_CORS_ORIGINS (the same list _is_allowed_websocket_origin honours),
• for a non-loopback caller only, the proxy's own address (a remote dashboard behind HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS). A loopback caller gets no same-origin pass, since a non-loopback Host with a loopback peer means a page's hostname was pointed at 127.0.0.1.

A cross-site subresource load (<img>, <script>) sends no Origin on GET, so Sec-Fetch-Site: cross-site is refused too, except for a top-level navigation. Requests without Origin (Claude Code, Codex, Copilot's extension host, SDKs, curl) are unaffected.

Because the check sits in the gate, it covers every backend, including the litellm/anyllm env-key fallback, without changing how a keyless request from a local tool is authenticated.

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

• headroom/proxy/server.py: _is_refused_browser_request(request) and a step 0 in _security_gate that answers 403 before the token check and routing. The 403 comes with the usual security headers and a hint naming HEADROOM_WS_ORIGINS, and an event=proxy_browser_origin_rejected log line records the escaped Origin. An origin listed in either HEADROOM_WS_ORIGINS or HEADROOM_CORS_ORIGINS is accepted, even when both are set.
• tests/test_proxy_browser_origin.py: text/plain POSTs to /v1/messages and /v1/chat/completions from a loopback peer with a foreign / null / look-alike Origin never reach the upstream; without Origin, from a loopback page, and from a configured origin they still forward with the operator header; cross-site subresource GET refused; cross-site navigation still served; loopback peer with a re-pointed hostname refused.
• tests/test_proxy_loopback_gating.py: two existing tests that sent a foreign Origin to /stats and /metrics now expect the gate's 403 (they already asserted refusal / no metadata; the gate now refuses earlier).
• docs/content/docs/security-model.mdx: describes the rule, and lists the setups that need an explicit origin: a reverse proxy on the same host, and app-scheme desktop shells.

Testing

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

Test Output

# new test file on origin/main (before the fix)
$ pytest tests/test_proxy_browser_origin.py
FAILED ...test_foreign_page_request_is_refused_before_the_upstream[browser_headers0-/v1/chat/completions]
FAILED ...test_foreign_page_request_is_refused_before_the_upstream[browser_headers0-/v1/messages]
FAILED ...test_foreign_page_request_is_refused_before_the_upstream[browser_headers1-/v1/chat/completions]
FAILED ...test_foreign_page_request_is_refused_before_the_upstream[browser_headers1-/v1/messages]
FAILED ...test_foreign_page_request_is_refused_before_the_upstream[browser_headers2-/v1/chat/completions]
FAILED ...test_foreign_page_request_is_refused_before_the_upstream[browser_headers2-/v1/messages]
FAILED ...test_configured_origin_still_forwards
FAILED ...test_cross_site_subresource_without_origin_is_refused
========================= 8 failed, 5 passed in 11.06s =========================

# with the fix
$ pytest tests/test_proxy_browser_origin.py tests/test_proxy_loopback_gating.py tests/test_proxy_cors.py
======================= 175 passed, 5 warnings in 34.36s =======================

# wider sweep: tests/test_proxy*.py tests/test_proxy/ tests/test_header_isolation.py
#   tests/test_upstream_credential_scoping.py tests/test_openai_codex_routing.py
#   tests/test_dashboard_* tests/test_copilot* (-k "not playwright")
= 12 failed, 2368 passed, 114 skipped, 30 deselected in 483.68s =
# the 12 failures (tests/test_proxy_uds.py x11, one test_proxy_compress_endpoint lossy-inline case)
# fail identically on origin/main in this environment

$ ruff check headroom/proxy/server.py tests/test_proxy_browser_origin.py tests/test_proxy_loopback_gating.py
All checks passed!
$ mypy headroom/proxy/server.py --ignore-missing-imports
Success: no issues found in 1 source file

Real Behavior Proof

• Environment: macOS, Python 3.12. headroom proxy --host 127.0.0.1 --no-optimize --anthropic-api-url http://127.0.0.1:<L> --anthropic-extra-headers '{"x-api-key":"OPERATOR_KEY_SENTINEL"}', no proxy token, with a small HTTP listener on <L> that logs each request's x-api-key and prompt. One run on origin/main, one on this branch.
• Exact command / steps: three curl -X POST http://127.0.0.1:<port>/v1/messages -H 'Content-Type: text/plain' --data '<messages JSON>', with Origin: http://page.example, with Origin: http://127.0.0.1:<port>, and with no Origin.
• Observed result:

  == origin/main
  Origin: http://page.example -> HTTP 200
  Origin: http://127.0.0.1:18961 -> HTTP 200
  (no Origin) -> HTTP 200
  listener saw:
  {"path": "/v1/messages", "x-api-key": "OPERATOR_KEY_SENTINEL", "prompt": "request-1 (Origin: http://page.example)"}
  {"path": "/v1/messages", "x-api-key": "OPERATOR_KEY_SENTINEL", "prompt": "request-2 (Origin: http://127.0.0.1:18961)"}
  {"path": "/v1/messages", "x-api-key": "OPERATOR_KEY_SENTINEL", "prompt": "request-3 (X-No-Origin: 1)"}
  == this branch
  Origin: http://page.example -> HTTP 403
  Origin: http://127.0.0.1:18962 -> HTTP 200
  (no Origin) -> HTTP 200
  listener saw:
  {"path": "/v1/messages", "x-api-key": "OPERATOR_KEY_SENTINEL", "prompt": "request-2 (Origin: http://127.0.0.1:18962)"}
  {"path": "/v1/messages", "x-api-key": "OPERATOR_KEY_SENTINEL", "prompt": "request-3 (X-No-Origin: 1)"}
  

  Dashboard on the same branch: GET /dashboard as a cross-site navigation -> 200; same-origin POST /settings -> 200; same-origin GET /stats -> 200.
• Not tested: a real Copilot upstream (the refusal happens before any handler, so it is the same for every route).

Runtime Rollout Safety

• Rollout-managed feature(s): none
• Minimum rollout channel: n/a
• Stable/default behavior changed: HTTP requests carrying an Origin that is neither loopback, configured, nor (for a remote caller) the proxy's own address now get 403. A browser app on another origin that calls the proxy directly must be listed in HEADROOM_WS_ORIGINS (or HEADROOM_CORS_ORIGINS, which also governs CORS). Electron/webview renderers that send Origin: null or an app scheme are refused unless listed.
• Kill switch / disable path: list the origin in HEADROOM_WS_ORIGINS.
• Unsafe override required: no
• Qualification impact: none
• Rollback path: revert this commit

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 (#4846) stops a * entry in HEADROOM_WS_ORIGINS / HEADROOM_CORS_ORIGINS from accepting every Origin. Both PRs share _is_allowed_websocket_origin, so once both land * is ignored on HTTP too; until then, HEADROOM_CORS_ORIGINS=* keeps HTTP open to every Origin, as it keeps the WebSocket routes today.

🤖 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 origin gate and the fix accepting either configured HTTP origin list look consistent with the intended policy. One documentation correction: explicitly listing tauri://localhost still leaves requests with that Origin rejected, because _normalize_origin permits only HTTP(S)/WS(S). Please describe app-scheme origins as unsupported, or add explicit configured-scheme support with a regression test. Isolated helper checks reproduced this and passed 11 expected policy cases; I did not run the full application suites or live HTTP validation. Approval qualification remains held separately by the inherited workflow provenance audit.

[devin-ai-integration]

Devin Review found 1 new potential issue.

[devin-ai-integration]

🔍 Allowed origin schemes are misstated

_normalize_origin also accepts ws and wss entries in the configured origin lists. The claim that only HTTP schemes can be listed excludes supported entries.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[JerrettDavis]

The app-scheme documentation correction resolves the prior finding. Fresh isolated helper checks pass 13 policy cases; these do not replace the full application suites or live HTTP proof. Current-head hosted application checks pass, but CI run 43519922036 reports a failed commitlint job (132211435827). Please supply its diagnostic output and resolve the failure before approval; the staged check contains no error details, so its cause is unconfirmed. The inherited workflow provenance hold remains separate from this PR. The existing scheme-wording thread remains nonblocking.