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
refactor(proxy): isolate auth classification policy (#1945)
JD Davis5a7265daa80d
diff --git a/headroom/proxy/auth_mode.py b/headroom/proxy/auth_mode.pyindex 4999ac6f7..2c7e97021 100644--- a/headroom/proxy/auth_mode.py+++ b/headroom/proxy/auth_mode.py@@ -18,56 +18,23 @@ spot bad clients without taking the proxy down.from __future__ import annotations-import enumimport loggingfrom collections.abc import Mappingfrom typing import Any-logger = logging.getLogger(__name__)---class AuthMode(str, enum.Enum):- """Three auth-mode classes Headroom routes compression policy through.-- Subclasses :class:`str` so the enum members serialize transparently- into structured logs / metric labels / TOIN aggregation keys. The- string form matches the Rust ``AuthMode::as_str()`` output exactly.- """-- #: Pay-as-you-go API key. Aggressive live-zone compression OK.- PAYG = "payg"-- #: OAuth bearer / Bedrock IAM / Vertex ADC. Passthrough-prefer:- #: no auto-cache_control, no auto-prompt_cache_key, no lossy- #: compressors. Lossless-only path.- OAUTH = "oauth"-- #: Subscription-bound CLI / IDE. Stealth: same as OAuth + preserve- #: ``accept-encoding``, never strip; never inject ``X-Headroom-*``;- #: never mutate ``User-Agent``.- SUBSCRIPTION = "subscription"---# User-Agent prefixes that identify a UX-bound CLI / IDE.-#-# Lives at module scope (not inside :func:`classify_auth_mode`) so:-# 1. A future PR can swap this for a configurable list (Phase F-# follow-up) without touching the function body.-# 2. Adding a new client = one-line edit here, no logic change.-#-# Match is ``str.__contains__`` against a lowercased copy of the UA —-# so the prefix can appear anywhere in the value.-SUBSCRIPTION_UA_PREFIXES: tuple[str, ...] = (- "claude-cli/",- "claude-code/",- "codex-cli/",- "cursor/",- "claude-vscode/",- "github-copilot/",- "anthropic-cli/",- "antigravity/",+from headroom.proxy.auth_policy import (+ CLIENT_UA_MAP,+ CODEX_RESPONSES_PATH,+ SUBSCRIPTION_UA_PREFIXES,+ AuthMode,+ AuthSignals,+ classify_auth_signals,+ classify_client_signals,+ should_stamp_codex_client_signals,)+logger = logging.getLogger(__name__)+def _header_get(headers: Mapping[str, Any] | Any, name: str) -> str:"""Read a single header, case-insensitively, returning ``""`` on miss.@@ -108,6 +75,17 @@ def _header_get(headers: Mapping[str, Any] | Any, name: str) -> str:return str(value)+def _auth_signals(headers: Mapping[str, Any] | Any) -> AuthSignals:+ """Adapt a header mapping into pure auth policy inputs."""+ return AuthSignals(+ user_agent=_header_get(headers, "user-agent"),+ authorization=_header_get(headers, "authorization"),+ x_api_key=_header_get(headers, "x-api-key"),+ x_goog_api_key=_header_get(headers, "x-goog-api-key"),+ x_client=_header_get(headers, "x-client"),+ )++def classify_auth_mode(headers: Mapping[str, Any] | Any) -> AuthMode:"""Classify the auth mode of an inbound request from its headers.@@ -140,85 +118,7 @@ def classify_auth_mode(headers: Mapping[str, Any] | Any) -> AuthMode:other matches are zero-allocation ``startswith`` / ``in`` /``str.split('.')``. Target: <10us per call."""- # ── User-Agent ────────────────────────────────────────────────- ua_lower = _header_get(headers, "user-agent").lower()- for prefix in SUBSCRIPTION_UA_PREFIXES:- if prefix in ua_lower:- return AuthMode.SUBSCRIPTION-- # ── Authorization header ──────────────────────────────────────- auth = _header_get(headers, "authorization")-- if auth.startswith("Bearer "):- token = auth[len("Bearer ") :]- # Order matters: `sk-ant-oat*` shares a prefix with- # `sk-ant-api*` only at `sk-ant-`, so check OAuth first.- # Real Anthropic OAuth access tokens are `sk-ant-oat01-...`- # (a version number, no dash after `oat`), so match on the- # dash-less `sk-ant-oat` prefix — matching on `sk-ant-oat-`- # missed every real token and let it fall through to PAYG.- if token.startswith("sk-ant-oat"):- return AuthMode.OAUTH- if token.startswith("sk-ant-api") or token.startswith("sk-"):- return AuthMode.PAYG- # JWT: classic three-segment `header.payload.signature`.- # We don't validate the JWT — just count dot-separated- # segments. Catches Codex / Cursor / Copilot OAuth.- if len(token.split(".")) >= 3:- return AuthMode.OAUTH- # Unknown bearer shape — fall through.- elif auth:- # Authorization is present but NOT `Bearer ...` — most- # commonly AWS SigV4 (`AWS4-HMAC-SHA256 ...`) on a Bedrock- # request, or a `Basic ...` from a custom proxy chain. We- # treat all such non-Bearer schemes as passthrough-prefer.- return AuthMode.OAUTH-- # ── Vendor-specific API-key headers ───────────────────────────- if _header_get(headers, "x-api-key"):- return AuthMode.PAYG- if _header_get(headers, "x-goog-api-key"):- return AuthMode.PAYG-- # ── Default ───────────────────────────────────────────────────- return AuthMode.PAYG---# Client (harness) identification — maps a User-Agent substring to a-# short normalized client name. The dashboard / `headroom perf` use-# this to slice traffic by harness ("aider is 30% of cache writes",-# "codex p99 latency vs claude-code", etc).-#-# Adding a new client: one line. Same surface as-# :data:`SUBSCRIPTION_UA_PREFIXES`. The classifier is intentionally-# substring-based (not regex) so a tuple of literals stays the-# extension point.-CLIENT_UA_MAP: tuple[tuple[str, str], ...] = (- # Anthropic ecosystem- ("claude-code/", "claude-code"),- ("claude-cli/", "claude-code"),- ("claude-vscode/", "claude-vscode"),- ("anthropic-cli/", "anthropic-cli"),- # OpenAI ecosystem- ("codex-cli/", "codex"),- # Editors / IDEs- ("cursor/", "cursor"),- ("zed/", "zed"),- # Other AI coding harnesses- ("aider/", "aider"),- ("droid/", "droid"),- ("opencode/", "opencode"),- ("github-copilot/", "copilot"),- # Google's experimental harness- ("antigravity/", "antigravity"),- # AWS Strands Agents SDK. The default openai-python User-Agent- # is `OpenAI/Python <ver>` which does not embed any Strands- # signal, so production callers should set `X-Client: strands`- # explicitly (see `headroom/integrations/strands/README.md`).- # The UA prefix below covers any Strands runtime that injects- # its own segment ahead of the openai-python UA.- ("strands-agents/", "strands"),-)+ return classify_auth_signals(_auth_signals(headers))def classify_client(headers: Mapping[str, Any] | Any, *, default: str | None = None) -> str | None:@@ -243,25 +143,7 @@ def classify_client(headers: Mapping[str, Any] | Any, *, default: str | None = Nempty string". The :class:`RequestOutcome` field has the sametype for the same reason."""- # 1. Explicit override- explicit = _header_get(headers, "x-client").strip().lower()- if explicit:- return explicit- # 2. User-Agent substring match- ua_lower = _header_get(headers, "user-agent").lower()- if not ua_lower:- return None- for needle, name in CLIENT_UA_MAP:- if needle in ua_lower:- return name- return default---# OpenAI's Responses API endpoint. In practice this is Codex's endpoint, but a-# proxy can't assume every caller here is Codex — hence-# :func:`should_stamp_codex_client` only stamps callers that don't already-# classify.-CODEX_RESPONSES_PATH = "/v1/responses"+ return classify_client_signals(_auth_signals(headers), default=default)def should_stamp_codex_client(path: str, headers: Mapping[str, Any] | Any) -> bool:@@ -277,9 +159,7 @@ def should_stamp_codex_client(path: str, headers: Mapping[str, Any] | Any) -> borecognized User-Agent) on the Responses endpoint. A caller that alreadyclassifies is left untouched."""- if path != CODEX_RESPONSES_PATH and not path.startswith(CODEX_RESPONSES_PATH + "/"):- return False- return classify_client(headers) is None+ return should_stamp_codex_client_signals(path, _auth_signals(headers))__all__ = [diff --git a/headroom/proxy/auth_policy.py b/headroom/proxy/auth_policy.pynew file mode 100644index 000000000..0c3cc9d4a--- /dev/null+++ b/headroom/proxy/auth_policy.py@@ -0,0 +1,111 @@+"""Pure auth-mode and client classification policy."""++from __future__ import annotations++import enum+from dataclasses import dataclass+++class AuthMode(str, enum.Enum):+ """Auth-mode classes Headroom routes compression policy through."""++ PAYG = "payg"+ OAUTH = "oauth"+ SUBSCRIPTION = "subscription"+++SUBSCRIPTION_UA_PREFIXES: tuple[str, ...] = (+ "claude-cli/",+ "claude-code/",+ "codex-cli/",+ "cursor/",+ "claude-vscode/",+ "github-copilot/",+ "anthropic-cli/",+ "antigravity/",+)+++CLIENT_UA_MAP: tuple[tuple[str, str], ...] = (+ ("claude-code/", "claude-code"),+ ("claude-cli/", "claude-code"),+ ("claude-vscode/", "claude-vscode"),+ ("anthropic-cli/", "anthropic-cli"),+ ("codex-cli/", "codex"),+ ("cursor/", "cursor"),+ ("zed/", "zed"),+ ("aider/", "aider"),+ ("droid/", "droid"),+ ("opencode/", "opencode"),+ ("github-copilot/", "copilot"),+ ("antigravity/", "antigravity"),+ ("strands-agents/", "strands"),+)+++CODEX_RESPONSES_PATH = "/v1/responses"+++@dataclass(frozen=True)+class AuthSignals:+ """Normalized header signals used by pure auth/client classifiers."""++ user_agent: str = ""+ authorization: str = ""+ x_api_key: str = ""+ x_goog_api_key: str = ""+ x_client: str = ""++ @property+ def user_agent_lower(self) -> str:+ return self.user_agent.lower()+++def classify_auth_signals(signals: AuthSignals) -> AuthMode:+ """Classify auth mode from normalized header values."""+ ua_lower = signals.user_agent_lower+ for prefix in SUBSCRIPTION_UA_PREFIXES:+ if prefix in ua_lower:+ return AuthMode.SUBSCRIPTION++ auth = signals.authorization+ if auth.startswith("Bearer "):+ token = auth[len("Bearer ") :]+ if token.startswith("sk-ant-oat"):+ return AuthMode.OAUTH+ if token.startswith("sk-ant-api") or token.startswith("sk-"):+ return AuthMode.PAYG+ if len(token.split(".")) >= 3:+ return AuthMode.OAUTH+ elif auth:+ return AuthMode.OAUTH++ if signals.x_api_key:+ return AuthMode.PAYG+ if signals.x_goog_api_key:+ return AuthMode.PAYG+ return AuthMode.PAYG+++def classify_client_signals(signals: AuthSignals, *, default: str | None = None) -> str | None:+ """Identify the client harness from normalized client signals."""+ explicit = signals.x_client.strip().lower()+ if explicit:+ return explicit+ ua_lower = signals.user_agent_lower+ if not ua_lower:+ return None+ for needle, name in CLIENT_UA_MAP:+ if needle in ua_lower:+ return name+ return default+++def is_codex_responses_path(path: str) -> bool:+ """Return True for the OpenAI Responses endpoint and its subpaths."""+ return path == CODEX_RESPONSES_PATH or path.startswith(CODEX_RESPONSES_PATH + "/")+++def should_stamp_codex_client_signals(path: str, signals: AuthSignals) -> bool:+ """Whether an unidentified Responses caller should be stamped as Codex."""+ return is_codex_responses_path(path) and classify_client_signals(signals) is Nonediff --git a/tests/test_auth_policy.py b/tests/test_auth_policy.pynew file mode 100644index 000000000..02ae27a63--- /dev/null+++ b/tests/test_auth_policy.py@@ -0,0 +1,55 @@+"""Tests for pure auth and client classification policy."""++from __future__ import annotations++from headroom.proxy.auth_policy import (+ AuthMode,+ AuthSignals,+ classify_auth_signals,+ classify_client_signals,+ should_stamp_codex_client_signals,+)+++def test_subscription_user_agent_wins_over_oauth_token() -> None:+ signals = AuthSignals(+ user_agent="claude-code/1.5.0 (linux; x86_64)",+ authorization="Bearer sk-ant-oat01-abc123",+ )++ assert classify_auth_signals(signals) is AuthMode.SUBSCRIPTION+++def test_oauth_bearer_token_shapes_are_oauth() -> None:+ jwt = "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0In0.signature"++ assert classify_auth_signals(AuthSignals(authorization="Bearer sk-ant-oat01-abc")) is (+ AuthMode.OAUTH+ )+ assert classify_auth_signals(AuthSignals(authorization=f"Bearer {jwt}")) is AuthMode.OAUTH+++def test_payg_key_shapes_are_payg() -> None:+ assert classify_auth_signals(AuthSignals(authorization="Bearer sk-ant-api03-abc")) is (+ AuthMode.PAYG+ )+ assert classify_auth_signals(AuthSignals(x_api_key="sk-ant-api03-abc")) is AuthMode.PAYG+ assert classify_auth_signals(AuthSignals(x_goog_api_key="AIzaSyDUMMY")) is AuthMode.PAYG+++def test_client_explicit_override_wins_over_user_agent() -> None:+ signals = AuthSignals(user_agent="claude-code/1.2.3", x_client=" AIDER ")++ assert classify_client_signals(signals) == "aider"+++def test_codex_stamp_only_for_unidentified_responses_callers() -> None:+ assert should_stamp_codex_client_signals("/v1/responses", AuthSignals()) is True+ assert (+ should_stamp_codex_client_signals(+ "/v1/responses/foo",+ AuthSignals(user_agent="codex-cli/0.5"),+ )+ is False+ )+ assert should_stamp_codex_client_signals("/v1/chat/completions", AuthSignals()) is False