Skip to content

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.

refactor(proxy): isolate auth classification policy (#1945)

JD Davis5a7265daa80d
diff --git a/headroom/proxy/auth_mode.py b/headroom/proxy/auth_mode.py
index 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 enum
import logging
from collections.abc import Mapping
from 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 = N
empty string". The :class:`RequestOutcome` field has the same
type 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) -> bo
recognized User-Agent) on the Responses endpoint. A caller that already
classifies 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.py
new file mode 100644
index 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 None
diff --git a/tests/test_auth_policy.py b/tests/test_auth_policy.py
new file mode 100644
index 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