Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
fix(security): poll usage only with the operator's own credential (#3863)
Tejas Chopra65e63c088354
diff --git a/headroom/proxy/handlers/anthropic.py b/headroom/proxy/handlers/anthropic.pyindex 84a46989b..06e138bac 100644--- a/headroom/proxy/handlers/anthropic.py+++ b/headroom/proxy/handlers/anthropic.py@@ -1264,7 +1264,16 @@ class AnthropicHandlerMixin:_sub_tracker = _get_sub_tracker()if _sub_tracker is not None:- _sub_tracker.notify_active(_auth_header)+ from headroom.subscription.credential_policy import (+ is_local_operator_connection,+ )++ # Only the local operator's bearer may become the polled+ # account; a network caller only marks activity (01-F16).+ _sub_tracker.notify_active(+ _auth_header,+ from_local_operator=is_local_operator_connection(request),+ )# Rate limitingif self.rate_limiter:diff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.pyindex 23d9ea4c4..d14a283fe 100644--- a/headroom/proxy/handlers/openai.py+++ b/headroom/proxy/handlers/openai.py@@ -7598,8 +7598,16 @@ class OpenAIHandlerMixin:from headroom.subscription.codex_rate_limits import (maybe_schedule_usage_poll,)+ from headroom.subscription.credential_policy import (+ is_local_operator_connection,+ )- maybe_schedule_usage_poll(ws_headers)+ # The poll spends the caller's own bearer: local operator only+ # (01-F16).+ maybe_schedule_usage_poll(+ ws_headers,+ from_local_operator=is_local_operator_connection(websocket),+ )try:# ChatGPT-auth sessions no longer need upstream x-codex-* headers ondiff --git a/headroom/subscription/codex_rate_limits.py b/headroom/subscription/codex_rate_limits.pyindex c6c054942..311510a92 100644--- a/headroom/subscription/codex_rate_limits.py+++ b/headroom/subscription/codex_rate_limits.py@@ -463,6 +463,7 @@ async def _fetch_and_store_usage(url: str, headers: dict[str, str]) -> None:def maybe_schedule_usage_poll(request_headers: dict[str, str],*,+ from_local_operator: bool = False,url: str = CODEX_USAGE_URL,min_interval_s: float = USAGE_POLL_MIN_INTERVAL_S,) -> bool:@@ -471,7 +472,14 @@ def maybe_schedule_usage_poll(Safe to call on every Codex request: scoped to ChatGPT-session traffic via:func:`_build_usage_headers` and internally throttled to at most one livepoll per ``min_interval_s``. Returns ``True`` when a poll was scheduled.++ The poll spends the *caller's* bearer, so it runs only when+ ``from_local_operator`` is true (the handler passes+ :func:`headroom.subscription.credential_policy.is_local_operator_connection`).+ A network caller on a shared proxy never drives it (VAPT 01-F16)."""+ if not from_local_operator:+ return Falseheaders = _build_usage_headers(request_headers)if headers is None:return Falsediff --git a/headroom/subscription/credential_policy.py b/headroom/subscription/credential_policy.pynew file mode 100644index 000000000..6b9d914fc--- /dev/null+++ b/headroom/subscription/credential_policy.py@@ -0,0 +1,53 @@+"""Which credential a background usage poller may use (VAPT 01-F16).++Usage pollers (the Claude subscription tracker, the Codex ``/wham/usage``+refresher) call a provider on the proxy's behalf and show the result on the+operator's dashboard. The account they poll must be the **operator's**, so a+credential *learned from traffic* is adopted only from the **local operator**: a+loopback peer whose request was not forwarded by another hop. On a shared proxy (several principals behind one Headroom), a network caller's+``Authorization`` bearer must never become the polled account — that would spend+the caller's credential on a request they never made and publish their usage on+someone else's dashboard. Without a learned token the pollers fall back to the+operator-configured credential (``CLAUDE_CODE_OAUTH_TOKEN`` or the proxy user's+own Claude Code credentials file), as before.++This keeps the single-developer experience: Claude Code on the same machine,+where the OAuth token often lives in the OS keychain rather than a file, still+gets its subscription window without extra setup.+"""++from __future__ import annotations++from typing import Any++from headroom.proxy.loopback_guard import is_loopback_host++# Any of these means the request crossed another hop (a gateway or reverse+# proxy on the same host), so the loopback peer is not the end caller. The+# whole ``X-Forwarded-*`` family counts (``-For``, ``-Proto``, ``-Host``, and+# any added later), so a gateway that sends only one of them still fails closed.+_FORWARDING_HEADERS = frozenset({"forwarded", "x-real-ip"})+_FORWARDING_HEADER_PREFIX = "x-forwarded-"+++def is_local_operator_connection(conn: Any) -> bool:+ """True only for a direct loopback caller (HTTP request or WebSocket).++ Fails closed: a missing peer address, a non-loopback peer, or any+ forwarding header returns ``False``. Trusted-gateway CIDRs deliberately do+ not count — a gateway fronts other principals by definition.+ """+ client = getattr(conn, "client", None)+ host = getattr(client, "host", None) if client is not None else None+ if not isinstance(host, str) or not is_loopback_host(host):+ return False+ headers = getattr(conn, "headers", None)+ if headers is not None:+ try:+ for name in headers.keys():+ name = name.lower()+ if name in _FORWARDING_HEADERS or name.startswith(_FORWARDING_HEADER_PREFIX):+ return False+ except Exception:+ return False+ return Truediff --git a/headroom/subscription/tracker.py b/headroom/subscription/tracker.pyindex dc802d22b..818ae6880 100644--- a/headroom/subscription/tracker.py+++ b/headroom/subscription/tracker.py@@ -179,11 +179,15 @@ class SubscriptionTracker(QuotaTracker):# Proxy integration hooks# ------------------------------------------------------------------- def notify_active(self, token: str) -> None:+ def notify_active(self, token: str, *, from_local_operator: bool = False) -> None:"""Called by the proxy handler when an OAuth request comes through.- Stores the token for polling and marks the tracker as recently active.- Only processes Bearer tokens that look like OAuth (not API keys).+ Marks the tracker as recently active. The caller's bearer is remembered+ for polling **only** when ``from_local_operator`` is true — the handler+ passes :func:`headroom.subscription.credential_policy.is_local_operator_connection`.+ A network caller on a shared proxy never becomes the polled account+ (VAPT 01-F16). Only Bearer tokens that look like OAuth (not API keys)+ are considered."""if not token or not token.startswith("Bearer "):return@@ -192,8 +196,10 @@ class SubscriptionTracker(QuotaTracker):if raw.startswith("sk-ant-api"):returnwith self._lock:- self._current_token = rawself._state.last_active_at = _utc_now()+ if not from_local_operator:+ return+ self._current_token = rawprefix = raw[:8]self._full_tokens[prefix] = self._full_tokens.get(prefix, 0) + 1diff --git a/tests/test_codex_rate_limits.py b/tests/test_codex_rate_limits.pyindex 1778e4015..417254862 100644--- a/tests/test_codex_rate_limits.py+++ b/tests/test_codex_rate_limits.py@@ -383,14 +383,17 @@ class TestUsagePollGating:# No running event loop -> cannot schedule.assert (maybe_schedule_usage_poll(- {"authorization": "Bearer a.b.c", "chatgpt-account-id": "acct"}+ {"authorization": "Bearer a.b.c", "chatgpt-account-id": "acct"},+ from_local_operator=True,)is False)def test_maybe_schedule_skips_non_codex(self):async def run():- return maybe_schedule_usage_poll({"authorization": "Bearer a.b.c"})+ return maybe_schedule_usage_poll(+ {"authorization": "Bearer a.b.c"}, from_local_operator=True+ )assert asyncio.run(run()) is False@@ -409,8 +412,8 @@ class TestUsagePollGating:async def run():req = {"authorization": "Bearer a.b.c", "chatgpt-account-id": "acct"}- first = maybe_schedule_usage_poll(req, min_interval_s=60.0)- second = maybe_schedule_usage_poll(req, min_interval_s=60.0)+ first = maybe_schedule_usage_poll(req, from_local_operator=True, min_interval_s=60.0)+ second = maybe_schedule_usage_poll(req, from_local_operator=True, min_interval_s=60.0)# Let the scheduled task run.await asyncio.sleep(0)return first, seconddiff --git a/tests/test_subscription_poll_credential_policy.py b/tests/test_subscription_poll_credential_policy.pynew file mode 100644index 000000000..790245754--- /dev/null+++ b/tests/test_subscription_poll_credential_policy.py@@ -0,0 +1,202 @@+"""01-F16: a caller's bearer must never become the account a usage poller polls.++On a shared proxy, the subscription tracker used to adopt *any* caller's OAuth+bearer as the account to poll, and the Codex ``/wham/usage`` refresher polled+with any caller's bearer + ChatGPT account id. The result was published on the+operator's dashboard and the caller's credential was spent on a request they+never made. Now only a bearer from the local operator (direct loopback, not+forwarded) may be adopted; otherwise the operator-configured credential is used.+"""++from __future__ import annotations++import asyncio+from types import SimpleNamespace++import httpx+import pytest+from starlette.datastructures import Headers++from headroom.subscription import codex_rate_limits+from headroom.subscription.credential_policy import is_local_operator_connection+from headroom.subscription.tracker import SubscriptionTracker+++def _conn(host: str | None, headers: dict[str, str] | Headers | None = None) -> SimpleNamespace:+ client = SimpleNamespace(host=host) if host is not None else None+ return SimpleNamespace(client=client, headers=headers or {})+++# ---------------------------------------------------------------------------+# Policy+# ---------------------------------------------------------------------------++[email protected]("host", ["127.0.0.1", "::1"])+def test_direct_loopback_caller_is_the_local_operator(host: str) -> None:+ assert is_local_operator_connection(_conn(host)) is True+++ "conn",+ [+ _conn("10.0.0.7"),+ _conn("192.168.1.20"),+ _conn(None),+ _conn("127.0.0.1", {"x-forwarded-for": "203.0.113.9"}),+ _conn("127.0.0.1", {"forwarded": "for=203.0.113.9"}),+ _conn("127.0.0.1", {"x-real-ip": "203.0.113.9"}),+ _conn("127.0.0.1", {"x-forwarded-proto": "https"}),+ _conn("127.0.0.1", {"x-forwarded-host": "public.example"}),+ _conn("127.0.0.1", {"X-Forwarded-Port": "443"}),+ _conn("127.0.0.1", Headers({"X-Forwarded-Proto": "https"})),+ ],+ ids=[+ "lan",+ "lan2",+ "no-peer",+ "xff",+ "forwarded",+ "x-real-ip",+ "xfp-only",+ "xfh-only",+ "xf-port",+ "starlette-xfp",+ ],+)+def test_network_forwarded_or_unknown_callers_are_not(conn) -> None: # noqa: ANN001+ assert is_local_operator_connection(conn) is False+++# ---------------------------------------------------------------------------+# Subscription tracker+# ---------------------------------------------------------------------------+++def _tracker(tmp_path) -> SubscriptionTracker: # noqa: ANN001+ return SubscriptionTracker(persist_path=tmp_path / "sub.json")+++def test_network_caller_marks_activity_but_is_never_adopted(tmp_path) -> None: # noqa: ANN001+ tracker = _tracker(tmp_path)+ tracker.notify_active("Bearer tenant-b-oauth-token")+ assert tracker._current_token is None+ assert tracker.is_active() is True+++def test_local_operator_bearer_is_adopted(tmp_path) -> None: # noqa: ANN001+ tracker = _tracker(tmp_path)+ tracker.notify_active("Bearer operator-oauth-token", from_local_operator=True)+ assert tracker._current_token == "operator-oauth-token"+++def test_foreign_bearer_never_reaches_the_usage_poll(tmp_path, monkeypatch) -> None: # noqa: ANN001+ monkeypatch.delenv("CLAUDE_CODE_OAUTH_TOKEN", raising=False)+ monkeypatch.setenv("CLAUDE_CONFIG_DIR", str(tmp_path / "no-claude"))+ tracker = _tracker(tmp_path)+ tracker.notify_active("Bearer tenant-b-oauth-token") # network caller+ polled: list[str | None] = []++ async def fetch(token: str | None): # noqa: ANN202+ polled.append(token)+ return None++ tracker._client.fetch = fetch # type: ignore[method-assign]+ asyncio.run(tracker._maybe_poll())+ # The poll ran (the caller marked activity) but with no adopted token, so+ # the client falls back to the operator's own credential.+ assert polled == [None]+++# ---------------------------------------------------------------------------+# Codex /wham/usage refresher+# ---------------------------------------------------------------------------+++CODEX_HEADERS = {"authorization": "Bearer tenant-b.jwt", "chatgpt-account-id": "acct-b"}+++def test_codex_poll_is_not_driven_by_a_network_caller(monkeypatch) -> None: # noqa: ANN001+ fetched: list[dict] = []++ async def _fake_fetch(url, headers): # noqa: ANN001+ fetched.append(headers)++ monkeypatch.setattr(codex_rate_limits, "_fetch_and_store_usage", _fake_fetch)+ codex_rate_limits.get_codex_rate_limit_state()._last_poll_monotonic = 0.0++ async def run() -> bool:+ scheduled = codex_rate_limits.maybe_schedule_usage_poll(CODEX_HEADERS, min_interval_s=0.0)+ await asyncio.sleep(0)+ return scheduled++ assert asyncio.run(run()) is False+ assert fetched == []+++# ---------------------------------------------------------------------------+# End to end through the real Anthropic handler+# ---------------------------------------------------------------------------+++def _drive_handler(client_host: str, monkeypatch, tmp_path) -> SubscriptionTracker: # noqa: ANN001+ pytest.importorskip("fastapi")+ from fastapi.testclient import TestClient++ from headroom.proxy.server import ProxyConfig, create_app+ from headroom.subscription import tracker as tracker_mod++ tracker = _tracker(tmp_path)+ monkeypatch.setattr(tracker_mod, "get_subscription_tracker", lambda: tracker)+ 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,+ image_optimize=False,+ )+ )+ with TestClient(app, client=(client_host, 50000)) as client:++ async def _fake_retry(method, url, headers, body, stream=False, **kwargs): # noqa: ANN001+ return httpx.Response(+ 200,+ json={+ "id": "msg_1",+ "type": "message",+ "role": "assistant",+ "content": [{"type": "text", "text": "ok"}],+ "usage": {"input_tokens": 1, "output_tokens": 1},+ },+ )++ client.app.state.proxy._retry_request = _fake_retry+ resp = client.post(+ "/v1/messages",+ headers={+ "authorization": "Bearer tenant-oauth-token",+ "anthropic-version": "2023-06-01",+ },+ json={+ "model": "claude-haiku-4-5",+ "max_tokens": 8,+ "messages": [{"role": "user", "content": "hi"}],+ },+ )+ assert resp.status_code == 200, resp.text+ return tracker+++def test_handler_never_adopts_a_network_callers_bearer(monkeypatch, tmp_path) -> None: # noqa: ANN001+ tracker = _drive_handler("127.0.0.1", monkeypatch, tmp_path)+ # Sanity: a direct loopback caller is still adopted (single-developer case).+ assert tracker._current_token == "tenant-oauth-token"++ monkeypatch.setenv("HEADROOM_ALLOW_UNAUTHENTICATED_BIND", "1")+ tracker = _drive_handler("10.1.2.3", monkeypatch, tmp_path / "net")+ assert tracker._current_token is Nonediff --git a/tests/test_subscription_tracker.py b/tests/test_subscription_tracker.pyindex e9b5906b1..1ae4267f9 100644--- a/tests/test_subscription_tracker.py+++ b/tests/test_subscription_tracker.py@@ -57,7 +57,7 @@ def test_tracker_notify_active_update_and_basic_state(monkeypatch: pytest.Monkeytracker.notify_active("Bearer sk-ant-api-key")assert tracker._current_token is None- tracker.notify_active("Bearer oauth-token-123")+ tracker.notify_active("Bearer oauth-token-123", from_local_operator=True)assert tracker._current_token == "oauth-token-123"assert tracker._full_tokens["oauth-to"] == 1assert tracker.is_active() is True@@ -180,7 +180,7 @@ async def test_maybe_poll_success_updates_state_and_metrics() -> None:monkeypatch.setattr(SubscriptionTracker, "_load_persisted_state", lambda self: None)tracker = SubscriptionTracker()- tracker.notify_active("Bearer live-oauth-token")+ tracker.notify_active("Bearer live-oauth-token", from_local_operator=True)snapshot = _make_snapshot()discrepancies = [WindowDiscrepancy(kind="cache_miss", description="miss", severity="warning")]@@ -226,7 +226,7 @@ async def test_maybe_poll_runs_transcript_scan_off_event_loop(multi-second ~/.claude/projects scan wedges the proxy every poll interval."""monkeypatch.setattr(SubscriptionTracker, "_load_persisted_state", lambda self: None)tracker = SubscriptionTracker()- tracker.notify_active("Bearer live-oauth-token")+ tracker.notify_active("Bearer live-oauth-token", from_local_operator=True)snapshot = _make_snapshot()