Commit Graph
1 Commits
Author SHA1 Message Date
5d44855c6f fix(proxy): withhold per-project savings and quota stats from /stats network callers (#4859)
## Description

`GET /stats` removes `recent_requests` / `request_logs` for a caller
that is not loopback, not a trusted dashboard CIDR peer and has not
presented the proxy token. The same payload still carried
`savings.per_project`, `persistent_savings.projects` (project names and
per-project spend) and the provider quota sections
(`get_quota_registry().get_all_stats()`, e.g. account login and plan).
For that same caller `/stats-lifetime` already drops `projects` and
`/quota` is refused, so `/stats` was the one route that still handed
them out.

`/stats` and `/stats?cached=1` now drop those fields under the same rule
(`_request_can_view_stats_metadata`). The nested `savings` /
`persistent_savings` dicts are rebuilt rather than edited in place, so
the shared cached snapshot still serves loopback callers in full.
Token-authenticated callers keep seeing everything, as documented in
"What the proxy token unlocks"; that docs table now lists the extra
fields.

Closes #

## 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)
- [x] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- `headroom/proxy/server.py` (`/stats`): for callers without
stats-metadata access, also pop every quota tracker key and drop
`savings.per_project` and `persistent_savings.projects`; docstring
updated.
- `docs/content/docs/security-model.mdx`: the `/stats` row of "What the
proxy token unlocks" lists per-project savings and the quota sections.
- `tests/test_proxy_stats_network_gating.py`: network caller on `/stats`
and `/stats?cached=1` gets no project name / quota data; loopback still
gets them after a network caller primed the cached snapshot; a token
holder still gets them.

## Testing

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

### Test Output

```text
$ pytest -q tests/test_proxy_stats_network_gating.py
5 passed in 18.60s

# with the server.py change stashed (origin/main code)
FAILED tests/test_proxy_stats_network_gating.py::test_stats_withholds_project_names_and_quota_stats_from_network_callers[/stats]
FAILED tests/test_proxy_stats_network_gating.py::test_stats_withholds_project_names_and_quota_stats_from_network_callers[/stats?cached=1]
2 failed, 3 passed in 7.10s

$ pytest -q tests/test_proxy_loopback_gating.py tests/test_proxy_stats_recent_requests.py tests/test_stats_output_reduction_gate.py tests/test_proxy_stats_network_gating.py
174 passed, 5 warnings in 44.87s

ruff check / format --check (0.17.3): All checks passed, 2 files already formatted
mypy headroom/proxy/server.py: Success: no issues found in 1 source file
```

## Real Behavior Proof

- Environment: macOS, Python 3.12,
`create_app(ProxyConfig(stateless=True, ...))` under FastAPI
`TestClient`, one recorded request for a project.
- Exact command / steps: `GET /stats` once as a network peer
(`203.0.113.9`, Host `203.0.113.5`) and once as loopback; print whether
`savings.per_project` and `persistent_savings.projects` are present.
- Observed result:
- origin/main: network caller gets `savings.per_project` and
`persistent_savings.projects` with every project name.
- this branch: network caller gets `savings.per_project: None` and no
`persistent_savings.projects`; loopback still gets both in full.
- Not tested: a real Copilot/Codex quota tracker (the test registers a
stand-in tracker).

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: n/a
- Stable/default behavior changed: yes, for network callers without
dashboard-CIDR or token access only: `/stats` no longer includes
per-project savings or quota sections. Loopback dashboards, CIDR peers
and token holders are unchanged.
- Kill switch / disable path: configure
`HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS` or present the proxy
token, as for `/stats-lifetime` and `/quota`.
- Unsafe override required: no
- Qualification impact: none
- Rollback path: revert this commit.

## 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
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] 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)

## Additional Notes

Fix adapted from a proposal by HetCreep.
`persistent_savings.storage_path` (a local filesystem path) is still in
the network payload; left as is to keep this change to the fields the
sibling routes already withhold.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4859"
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: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-11-14 10:46:33 +05:30