Files
headroom/tests/test_proxy_stats_network_gating.py
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

96 lines
3.0 KiB
Python

"""``/stats`` withholds from network callers what ``/stats-lifetime`` and ``/quota`` withhold."""
from __future__ import annotations
from contextlib import contextmanager
from typing import Any
import pytest
from fastapi.testclient import TestClient
from headroom.proxy.models import ProxyConfig
from headroom.proxy.server import create_app
from headroom.subscription.base import QuotaTracker, get_quota_registry
PROJECT = "private-project-name"
LOGIN = "private-account-login"
class _FakeTracker(QuotaTracker):
@property
def key(self) -> str:
return "fake_quota"
@property
def label(self) -> str:
return "Fake"
def is_available(self) -> bool:
return True
def get_stats(self) -> dict[str, Any] | None:
return {"latest": {"login": LOGIN, "plan": "business"}}
def _app():
app = create_app(
ProxyConfig(
optimize=False,
cache_enabled=False,
rate_limit_enabled=False,
cost_tracking_enabled=False,
log_requests=False,
ccr_inject_tool=False,
ccr_handle_responses=False,
ccr_context_tracking=False,
http2=False,
stateless=True,
)
)
app.state.proxy.metrics.savings_tracker.record_request(
model="gpt-4.1", input_tokens=100, tokens_saved=40, project=PROJECT
)
return app
@contextmanager
def _client(app, base_url: str, peer: str):
# Startup resets the quota registry, so the stand-in tracker goes in afterwards.
with TestClient(app, base_url=base_url, client=(peer, 12345)) as client:
get_quota_registry().register(_FakeTracker())
yield client
@pytest.mark.parametrize("path", ["/stats", "/stats?cached=1"])
def test_stats_withholds_project_names_and_quota_stats_from_network_callers(path) -> None:
with _client(_app(), "http://203.0.113.5", "203.0.113.9") as client:
response = client.get(path)
assert response.status_code == 200
payload = response.json()
assert "summary" in payload # aggregate counters stay public
assert PROJECT not in response.text
assert LOGIN not in response.text
def test_loopback_still_sees_them_after_a_network_caller_primed_the_cache() -> None:
app = _app()
with _client(app, "http://203.0.113.5", "203.0.113.9") as net:
net.get("/stats?cached=1") # primes the shared snapshot
body = (
TestClient(app, base_url="http://127.0.0.1", client=("127.0.0.1", 12345))
.get("/stats?cached=1")
.text
)
assert PROJECT in body
assert LOGIN in body
@pytest.mark.parametrize("path", ["/stats", "/stats?cached=1"])
def test_token_holder_still_sees_them(monkeypatch: pytest.MonkeyPatch, path: str) -> None:
monkeypatch.setenv("HEADROOM_PROXY_TOKEN", "s3cret-token")
monkeypatch.setenv("HEADROOM_HOST", "0.0.0.0")
with _client(_app(), "http://headroom", "10.0.4.7") as client:
body = client.get(path, headers={"x-headroom-proxy-token": "s3cret-token"}).text
assert PROJECT in body
assert LOGIN in body