fix(proxy): add same-origin check to /v1/retrieve/tool_call (#3955)

## Description

`POST /v1/retrieve` checks the `Origin` header (`require_same_origin`),
so a web page you visit cannot make your browser call it. Its sibling
`POST /v1/retrieve/tool_call` only had the loopback check, so it was
missed when #3060 added the guard to the other write routes. This PR
adds the same check to it.

## Type of Change

- [x] 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`: add `Depends(_require_same_origin)` to
`/v1/retrieve/tool_call`.
- `tests/test_proxy_loopback_gating.py`: add the route to
`CSRF_GUARDED`, so it gets the existing cross-origin, `Origin: null`,
same-origin and no-`Origin` tests.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
$ pytest -q tests/test_proxy_loopback_gating.py
103 passed, 1 warning in 9.59s

$ pytest -q tests/test_proxy_loopback_gating.py -k tool_call   # without the fix
2 failed, 3 passed, 98 deselected, 1 warning in 1.71s

$ pytest -q tests/test_proxy*.py tests/test_ccr*.py tests/test_identity_resolution.py
1404 passed, 107 skipped, 3 warnings in 90.38s

$ ruff check headroom/proxy/server.py tests/test_proxy_loopback_gating.py && ruff format --check headroom/proxy/server.py tests/test_proxy_loopback_gating.py
All checks passed!
2 files already formatted
```

## Real Behavior Proof

- Environment: macOS, Python 3.12, a real `headroom proxy` on
`127.0.0.1` (not TestClient). `main` (2bc94194) on port 18788 and this
branch (fc6ebf82) on port 18787.
- Exact command / steps: `curl` POSTs to `/v1/retrieve/tool_call` with
`Content-Type: text/plain` (a CORS "simple" request, like a malicious
page would send) and different `Origin` headers.
- Observed result: on `main`, every origin gets 200. On this branch, a
foreign or `null` origin gets 403 `{"detail":"cross-origin request
rejected"}`, and loopback-origin and no-origin requests still get 200.

```text
## main (2bc94194)
Origin: https://attacker.example  -> 200
Origin: null                      -> 200
Origin: http://127.0.0.1:18788    -> 200
(no Origin)                       -> 200

## this branch (fc6ebf82)
Origin: https://attacker.example  -> 403
Origin: null                      -> 403
Origin: http://127.0.0.1:18787    -> 200
(no Origin)                       -> 200

$ curl -s -X POST http://127.0.0.1:18787/v1/retrieve/tool_call -H 'Content-Type: text/plain' -H 'Origin: https://attacker.example' -d '{}'
{"detail":"cross-origin request rejected"}

proxy log: event=proxy_inbound_response method=POST path=/v1/retrieve/tool_call status=403 duration_ms=4.79
```

- Not tested: a real browser. `curl` sends the same `Origin` header a
browser sends on a cross-origin POST, and that header is all the guard
checks.

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: n/a
- Stable/default behavior changed: only cross-origin browser requests to
this route are now rejected
- Kill switch / disable path: none
- Unsafe override required: no
- Qualification impact: none
- Rollback path: revert this PR

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] 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
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)
<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/3955"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

Co-authored-by: JD Davis <mxjerrett@gmail.com>
This commit is contained in:
Satya Bharadwaj
2026-10-05 10:00:29 -05:00
committed by GitHub
co-authored by JD Davis
parent a96154f03b
commit 2297b5059f
2 changed files with 5 additions and 1 deletions
+4 -1
View File
@@ -5928,7 +5928,10 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
)
# CCR Tool Call Handler - for agent frameworks to call when LLM uses headroom_retrieve
@app.post("/v1/retrieve/tool_call", dependencies=[Depends(_require_loopback)])
@app.post(
"/v1/retrieve/tool_call",
dependencies=[Depends(_require_loopback), Depends(_require_same_origin)],
)
async def ccr_handle_tool_call(request: Request):
"""Handle a CCR tool call from an LLM response.
+1
View File
@@ -134,6 +134,7 @@ CSRF_GUARDED = [
"/stats/reset",
"/cache/clear",
"/v1/retrieve",
"/v1/retrieve/tool_call",
"/v1/telemetry/import",
"/admin/runtime-env",
]