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(proxy): F4 — trust X-Forwarded-* only behind allow-listed gateway
chopratejas665c0823d96b
diff --git a/headroom/proxy/forwarded_headers.py b/headroom/proxy/forwarded_headers.pynew file mode 100644index 000000000..c41b6ec2f--- /dev/null+++ b/headroom/proxy/forwarded_headers.py@@ -0,0 +1,309 @@+"""Trusted-gateway gate for ``X-Forwarded-*`` headers — Phase F PR-F4.++The proxy must not blindly trust ``X-Forwarded-For``,+``X-Forwarded-Proto``, or ``X-Forwarded-Host`` from arbitrary clients —+a malicious upstream client can forge any of those values and spoof+their origin IP, scheme, or host. We trust them ONLY when the+connecting peer's IP is in a configured CIDR allow-list (i.e. behind+a known reverse proxy / API gateway).++Configuration+-------------++Single env var, comma-separated CIDR blocks::++ HEADROOM_PROXY_TRUSTED_GATEWAY_CIDRS=10.0.0.0/8,172.16.0.0/12,fd00::/8++Whitespace around the commas is tolerated. Empty / unset is the+**default** and the **most secure** setting — it means *no gateway is+trusted*, so every ``X-Forwarded-*`` header is ignored regardless of+peer.++Behaviour matrix+----------------++============================ ===================== ========+Allow-list state Peer in list? Result+============================ ===================== ========+unset / empty (default) n/a headers IGNORED+configured yes headers HONORED+configured no headers IGNORED + ``forwarded_headers_rejected`` event+============================ ===================== ========++Public API+----------++* :func:`resolve_client_ip` — the IP to log / rate-limit / authorize on.+* :func:`trusted_forwarded_headers` — sanitized ``{proto, host, for}``+ dict; values are empty strings when the gate fails.++Both helpers cache their result on ``request.state`` so they run at+most once per request.++Constraints (per project memory)+--------------------------------++* configurable: env var only, no other config surface.+* no hardcodes: every CIDR comes from the env var.+* no regexes: parsing uses :mod:`ipaddress` from the stdlib.+* no silent fallbacks: a malformed CIDR raises ``ValueError`` at+ startup; every spoof rejection emits a structured log event.+"""++from __future__ import annotations++import ipaddress+import logging+import os+from typing import TYPE_CHECKING, Any++if TYPE_CHECKING:+ from fastapi import Request++logger = logging.getLogger(__name__)++__all__ = [+ "TRUSTED_GATEWAY_CIDRS_ENV",+ "load_trusted_gateway_cidrs",+ "peer_is_trusted_gateway",+ "resolve_client_ip",+ "trusted_forwarded_headers",+]+++#: Environment variable that holds the comma-separated CIDR allow-list.+TRUSTED_GATEWAY_CIDRS_ENV = "HEADROOM_PROXY_TRUSTED_GATEWAY_CIDRS"+++def _parse_cidr_list(+ raw: str,+) -> tuple[ipaddress.IPv4Network | ipaddress.IPv6Network, ...]:+ """Parse a comma-separated CIDR list. Empty / whitespace → empty tuple.++ Whitespace around commas is tolerated. Empty individual entries+ (e.g. trailing comma) are skipped. Malformed entries raise+ :class:`ValueError` — we *deliberately* do not silently skip bad+ CIDRs, because a config typo that quietly empties the allow-list+ would silently downgrade the proxy from "strict" to "more strict",+ masking the operator's intent.+ """+ if not raw or not raw.strip():+ return ()+ nets: list[ipaddress.IPv4Network | ipaddress.IPv6Network] = []+ for chunk in raw.split(","):+ entry = chunk.strip()+ if not entry:+ # Tolerate `"10.0.0.0/8,"` — trailing comma is benign.+ continue+ # ``strict=False`` so ``10.0.0.1/8`` is accepted as the network+ # ``10.0.0.0/8`` instead of rejecting host bits — operators+ # routinely paste a sample IP with a netmask and expect it to+ # mean the network.+ nets.append(ipaddress.ip_network(entry, strict=False))+ return tuple(nets)+++def load_trusted_gateway_cidrs(+ raw: str | None = None,+) -> tuple[ipaddress.IPv4Network | ipaddress.IPv6Network, ...]:+ """Load and parse the trusted-gateway CIDR allow-list.++ ``raw`` is exposed for tests and direct callers; production code+ passes nothing and we read :data:`TRUSTED_GATEWAY_CIDRS_ENV` from+ the process environment. A malformed entry raises+ :class:`ValueError` — let it propagate so the failure is loud at+ startup instead of silently disabling the gate.+ """+ if raw is None:+ raw = os.environ.get(TRUSTED_GATEWAY_CIDRS_ENV, "")+ return _parse_cidr_list(raw)+++def _normalize_ip(+ host: str,+) -> ipaddress.IPv4Address | ipaddress.IPv6Address | None:+ """Parse ``host`` into an IPv4/IPv6 address, unmapping ``::ffff:*``.++ IPv4-mapped IPv6 addresses (``::ffff:10.0.0.1``) — emitted by Linux+ dual-stack sockets — are normalized to their underlying IPv4 form+ so a CIDR allow-list of ``10.0.0.0/8`` matches them naturally.+ Returns ``None`` on malformed input; callers treat that as "not a+ trusted gateway".+ """+ try:+ addr = ipaddress.ip_address(host)+ except ValueError:+ return None+ if isinstance(addr, ipaddress.IPv6Address) and addr.ipv4_mapped is not None:+ return addr.ipv4_mapped+ return addr+++def peer_is_trusted_gateway(+ peer_host: str | None,+ cidrs: tuple[ipaddress.IPv4Network | ipaddress.IPv6Network, ...],+) -> bool:+ """Return True iff ``peer_host`` is inside any of the allow-list CIDRs.++ Empty allow-list → always False (the strict-secure default).+ ``None`` peer (TestClient / UDS) → False; we never trust a peer we+ can't even identify.+ """+ if not cidrs:+ return False+ if peer_host is None:+ return False+ addr = _normalize_ip(peer_host)+ if addr is None:+ return False+ for net in cidrs:+ # IP/network family must match; ipaddress raises TypeError if+ # we pass an IPv4 address into an IPv6 network membership test+ # in some versions, so we family-gate first.+ if isinstance(addr, ipaddress.IPv4Address) and isinstance(net, ipaddress.IPv6Network):+ continue+ if isinstance(addr, ipaddress.IPv6Address) and isinstance(net, ipaddress.IPv4Network):+ continue+ if addr in net:+ return True+ return False+++def _peer_host(request: Any) -> str | None:+ """Pull ``request.client.host`` defensively (TestClient may omit)."""+ client = getattr(request, "client", None)+ if client is None:+ return None+ return getattr(client, "host", None)+++def _header_first(value: str) -> str:+ """Return the leftmost element of a comma-separated header value.++ ``X-Forwarded-For: client, proxy1, proxy2`` → ``"client"``. Empty+ input returns ``""``. We intentionally do NOT walk the chain — the+ leftmost hop is the only one whose authenticity the immediate+ gateway can vouch for, and beyond that we have no trust signal.+ """+ if not value:+ return ""+ head, _, _ = value.partition(",")+ return head.strip()+++def _read_header(request: Any, name: str) -> str:+ """Read a header case-insensitively, ``""`` on miss."""+ headers = getattr(request, "headers", None)+ if headers is None:+ return ""+ try:+ value = headers.get(name)+ except AttributeError:+ return ""+ if value is None:+ return ""+ if isinstance(value, bytes):+ try:+ return value.decode("latin-1")+ except UnicodeDecodeError: # pragma: no cover - defensive+ return ""+ return str(value)+++def _emit_rejection_event(+ peer_host: str | None,+ fwd_for: str,+ fwd_proto: str,+ fwd_host: str,+) -> None:+ """One-line structured log for every spoof-rejection.++ Loud-by-design: an operator running a misconfigured network MUST+ see this so they can either widen their CIDR allow-list or fix the+ upstream proxy. The event name is stable for grep / Prometheus+ log-based alerts.+ """+ logger.warning(+ "forwarded_headers_rejected",+ extra={+ "event": "forwarded_headers_rejected",+ "peer_ip": peer_host or "",+ "forwarded_for": fwd_for,+ "forwarded_proto": fwd_proto,+ "forwarded_host": fwd_host,+ },+ )+++def _resolve(request: Any) -> tuple[str, dict[str, str]]:+ """Compute (client_ip, sanitized_forwarded_dict) once.++ Cached on ``request.state.client_ip`` /+ ``request.state.forwarded`` so repeated calls within a single+ request are free.+ """+ state = getattr(request, "state", None)+ if state is not None:+ cached_ip = getattr(state, "client_ip", None)+ cached_fwd = getattr(state, "forwarded", None)+ if cached_ip is not None and cached_fwd is not None:+ return cached_ip, cached_fwd++ peer_host = _peer_host(request) or ""+ fwd_for_raw = _read_header(request, "x-forwarded-for")+ fwd_proto_raw = _read_header(request, "x-forwarded-proto")+ fwd_host_raw = _read_header(request, "x-forwarded-host")++ cidrs = load_trusted_gateway_cidrs()+ trusted = peer_is_trusted_gateway(peer_host or None, cidrs)++ if trusted:+ client_ip = _header_first(fwd_for_raw) or peer_host+ forwarded = {+ "for": _header_first(fwd_for_raw),+ "proto": fwd_proto_raw.strip(),+ "host": fwd_host_raw.strip(),+ }+ else:+ # Headers may be absent (legitimate direct client). Only emit+ # the rejection event if the peer ACTUALLY tried to set one —+ # otherwise we'd spam logs for every direct request.+ if fwd_for_raw or fwd_proto_raw or fwd_host_raw:+ _emit_rejection_event(peer_host or None, fwd_for_raw, fwd_proto_raw, fwd_host_raw)+ client_ip = peer_host+ forwarded = {"for": "", "proto": "", "host": ""}++ if state is not None:+ try:+ state.client_ip = client_ip+ state.forwarded = forwarded+ except Exception: # pragma: no cover - defensive+ # Some test fakes use a frozen ``state`` namespace; don't+ # crash — the helpers still return the right value, just+ # without caching.+ pass+ return client_ip, forwarded+++def resolve_client_ip(request: Request) -> str:+ """Return the client IP to use for logging / auth / rate-limit.++ Always falls back to ``request.client.host`` when the gate fails+ or no usable forwarded value is present. Returns ``""`` only if+ even ``request.client`` is ``None`` (TestClient / UDS).+ """+ ip, _ = _resolve(request)+ return ip+++def trusted_forwarded_headers(request: Request) -> dict[str, str]:+ """Return the sanitized ``X-Forwarded-*`` triple.++ Keys: ``"for"``, ``"proto"``, ``"host"``. Every value is the empty+ string when the gateway gate fails, so callers can use simple+ truthiness checks (``if fwd["proto"]: ...``).+ """+ _, fwd = _resolve(request)+ # Defensive copy: callers writing into the dict must not poison+ # the request-state cache.+ return dict(fwd)diff --git a/headroom/proxy/handlers/anthropic.py b/headroom/proxy/handlers/anthropic.pyindex b1c2b5570..477ec8c96 100644--- a/headroom/proxy/handlers/anthropic.py+++ b/headroom/proxy/handlers/anthropic.py@@ -25,6 +25,7 @@ import httpxfrom headroom.pipeline import PipelineStage, summarize_routing_markersfrom headroom.proxy.auth_mode import classify_auth_mode+from headroom.proxy.forwarded_headers import resolve_client_iplogger = logging.getLogger("headroom.proxy")@@ -611,7 +612,12 @@ class AnthropicHandlerMixin:auth = headers.get("authorization", "")if auth.startswith("Bearer "):api_key = auth[7:]- client_ip = request.client.host if request.client else "unknown"+ # Phase F PR-F4: trust ``X-Forwarded-For`` for the rate-limit+ # key only when the connecting peer is in+ # ``HEADROOM_PROXY_TRUSTED_GATEWAY_CIDRS``; otherwise we use+ # the direct peer IP and a malicious client cannot rotate+ # rate-limit buckets by forging headers.+ client_ip = resolve_client_ip(request) or "unknown"rate_key = f"{api_key[:16]}:{client_ip}" if api_key else client_ipallowed, wait_seconds = await self.rate_limiter.check_request(rate_key)if not allowed:diff --git a/tests/test_forwarded_headers.py b/tests/test_forwarded_headers.pynew file mode 100644index 000000000..006378e80--- /dev/null+++ b/tests/test_forwarded_headers.py@@ -0,0 +1,467 @@+"""Tests for ``headroom.proxy.forwarded_headers`` — Phase F PR-F4.++Threat model: a malicious upstream client can forge any+``X-Forwarded-*`` header. The proxy must trust them ONLY when the+connecting peer's IP is in the configured CIDR allow-list. Default+(``HEADROOM_PROXY_TRUSTED_GATEWAY_CIDRS`` unset / empty) is+strict-secure: every forwarded header is ignored.+"""++from __future__ import annotations++import logging+from types import SimpleNamespace+from typing import Any++import pytest+from fastapi import FastAPI, Request+from fastapi.testclient import TestClient+from starlette.datastructures import Headers, State++from headroom.proxy.forwarded_headers import (+ TRUSTED_GATEWAY_CIDRS_ENV,+ load_trusted_gateway_cidrs,+ peer_is_trusted_gateway,+ resolve_client_ip,+ trusted_forwarded_headers,+)++# ──────────────────────────────────────────────────────────────────+# Fake-request helper+# ──────────────────────────────────────────────────────────────────+++def _fake_request(+ *,+ peer_host: str | None,+ forwarded_for: str | None = None,+ forwarded_proto: str | None = None,+ forwarded_host: str | None = None,+) -> Any:+ """Build a minimal duck-typed ``Request`` stand-in.++ Avoids spinning up a TestClient — we only need ``client.host``,+ ``headers``, and ``state`` for these helpers.+ """+ raw_headers: list[tuple[bytes, bytes]] = []+ if forwarded_for is not None:+ raw_headers.append((b"x-forwarded-for", forwarded_for.encode("latin-1")))+ if forwarded_proto is not None:+ raw_headers.append((b"x-forwarded-proto", forwarded_proto.encode("latin-1")))+ if forwarded_host is not None:+ raw_headers.append((b"x-forwarded-host", forwarded_host.encode("latin-1")))+ headers = Headers(raw=raw_headers)+ client = None if peer_host is None else SimpleNamespace(host=peer_host)+ return SimpleNamespace(client=client, headers=headers, state=State())+++# ──────────────────────────────────────────────────────────────────+# CIDR parsing+# ──────────────────────────────────────────────────────────────────+++def test_load_cidrs_unset_is_empty(monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.delenv(TRUSTED_GATEWAY_CIDRS_ENV, raising=False)+ assert load_trusted_gateway_cidrs() == ()+++def test_load_cidrs_empty_string_is_empty() -> None:+ assert load_trusted_gateway_cidrs("") == ()+ assert load_trusted_gateway_cidrs(" ") == ()+++def test_load_cidrs_single() -> None:+ cidrs = load_trusted_gateway_cidrs("10.0.0.0/8")+ assert len(cidrs) == 1+ assert str(cidrs[0]) == "10.0.0.0/8"+++def test_load_cidrs_multiple() -> None:+ cidrs = load_trusted_gateway_cidrs("10.0.0.0/8,172.16.0.0/12,fd00::/8")+ assert [str(c) for c in cidrs] == ["10.0.0.0/8", "172.16.0.0/12", "fd00::/8"]+++def test_load_cidrs_whitespace_tolerant() -> None:+ cidrs = load_trusted_gateway_cidrs(" 10.0.0.0/8 , 172.16.0.0/12 ")+ assert [str(c) for c in cidrs] == ["10.0.0.0/8", "172.16.0.0/12"]+++def test_load_cidrs_trailing_comma_tolerant() -> None:+ cidrs = load_trusted_gateway_cidrs("10.0.0.0/8,")+ assert [str(c) for c in cidrs] == ["10.0.0.0/8"]+++def test_load_cidrs_host_bits_normalized() -> None:+ """``10.0.0.1/8`` is accepted as ``10.0.0.0/8`` (operator-friendly)."""+ cidrs = load_trusted_gateway_cidrs("10.0.0.1/8")+ assert str(cidrs[0]) == "10.0.0.0/8"+++def test_load_cidrs_malformed_raises_loud() -> None:+ """Malformed CIDR must raise — silent skip would mask config typos."""+ with pytest.raises(ValueError):+ load_trusted_gateway_cidrs("not-a-cidr")+++def test_load_cidrs_partial_malformed_raises_loud() -> None:+ """One bad entry in a multi-CIDR list still raises — we don't degrade."""+ with pytest.raises(ValueError):+ load_trusted_gateway_cidrs("10.0.0.0/8,not-a-cidr,fd00::/8")+++def test_load_cidrs_reads_env_by_default(monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setenv(TRUSTED_GATEWAY_CIDRS_ENV, "10.0.0.0/8")+ cidrs = load_trusted_gateway_cidrs()+ assert [str(c) for c in cidrs] == ["10.0.0.0/8"]+++# ──────────────────────────────────────────────────────────────────+# Membership check (peer_is_trusted_gateway)+# ──────────────────────────────────────────────────────────────────+++def test_peer_membership_empty_allowlist_is_false() -> None:+ assert peer_is_trusted_gateway("10.0.0.5", ()) is False+++def test_peer_membership_none_peer_is_false() -> None:+ cidrs = load_trusted_gateway_cidrs("10.0.0.0/8")+ assert peer_is_trusted_gateway(None, cidrs) is False+++def test_peer_membership_in_v4_cidr() -> None:+ cidrs = load_trusted_gateway_cidrs("10.0.0.0/8")+ assert peer_is_trusted_gateway("10.0.0.5", cidrs) is True+++def test_peer_membership_outside_v4_cidr() -> None:+ cidrs = load_trusted_gateway_cidrs("10.0.0.0/8")+ assert peer_is_trusted_gateway("8.8.8.8", cidrs) is False+++def test_peer_membership_in_v6_cidr() -> None:+ """IPv6: ``fd00::1`` ∈ ``fd00::/8`` (allow-list parity test)."""+ cidrs = load_trusted_gateway_cidrs("fd00::/8")+ assert peer_is_trusted_gateway("fd00::1", cidrs) is True+++def test_peer_membership_v4_mapped_v6() -> None:+ """``::ffff:10.0.0.1`` resolves to IPv4 for matching."""+ cidrs = load_trusted_gateway_cidrs("10.0.0.0/8")+ assert peer_is_trusted_gateway("::ffff:10.0.0.1", cidrs) is True+++def test_peer_membership_v4_not_in_v6_only_cidr() -> None:+ cidrs = load_trusted_gateway_cidrs("fd00::/8")+ assert peer_is_trusted_gateway("10.0.0.5", cidrs) is False+++def test_peer_membership_v6_not_in_v4_only_cidr() -> None:+ cidrs = load_trusted_gateway_cidrs("10.0.0.0/8")+ assert peer_is_trusted_gateway("fd00::1", cidrs) is False+++def test_peer_membership_evaluates_all_cidrs() -> None:+ cidrs = load_trusted_gateway_cidrs("10.0.0.0/8,172.16.0.0/12,fd00::/8")+ # last-CIDR hit ensures we don't short-circuit early+ assert peer_is_trusted_gateway("172.16.5.5", cidrs) is True+ assert peer_is_trusted_gateway("fd00::beef", cidrs) is True+++def test_peer_membership_malformed_peer_is_false() -> None:+ cidrs = load_trusted_gateway_cidrs("10.0.0.0/8")+ assert peer_is_trusted_gateway("not-an-ip", cidrs) is False+++# ──────────────────────────────────────────────────────────────────+# resolve_client_ip / trusted_forwarded_headers+# ──────────────────────────────────────────────────────────────────+++def test_default_strict_ignores_forwarded(monkeypatch: pytest.MonkeyPatch) -> None:+ """Env unset → X-Forwarded-* IGNORED even from a 10.x peer."""+ monkeypatch.delenv(TRUSTED_GATEWAY_CIDRS_ENV, raising=False)+ req = _fake_request(+ peer_host="10.0.0.5",+ forwarded_for="203.0.113.7",+ forwarded_proto="https",+ forwarded_host="api.example.com",+ )+ assert resolve_client_ip(req) == "10.0.0.5"+ assert trusted_forwarded_headers(req) == {"for": "", "proto": "", "host": ""}+++def test_allowlisted_peer_honors_forwarded(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ monkeypatch.setenv(TRUSTED_GATEWAY_CIDRS_ENV, "10.0.0.0/8")+ req = _fake_request(+ peer_host="10.0.0.5",+ forwarded_for="203.0.113.7",+ forwarded_proto="https",+ forwarded_host="api.example.com",+ )+ assert resolve_client_ip(req) == "203.0.113.7"+ assert trusted_forwarded_headers(req) == {+ "for": "203.0.113.7",+ "proto": "https",+ "host": "api.example.com",+ }+++def test_non_allowlisted_peer_ignores_forwarded_and_logs(+ monkeypatch: pytest.MonkeyPatch,+ caplog: pytest.LogCaptureFixture,+) -> None:+ monkeypatch.setenv(TRUSTED_GATEWAY_CIDRS_ENV, "10.0.0.0/8")+ req = _fake_request(+ peer_host="8.8.8.8", # NOT in 10.0.0.0/8+ forwarded_for="203.0.113.7",+ forwarded_proto="https",+ forwarded_host="api.example.com",+ )+ with caplog.at_level(logging.WARNING, logger="headroom.proxy.forwarded_headers"):+ ip = resolve_client_ip(req)+ fwd = trusted_forwarded_headers(req)+ assert ip == "8.8.8.8"+ assert fwd == {"for": "", "proto": "", "host": ""}+ # Structured rejection event MUST be emitted with full context.+ rejections = [r for r in caplog.records if r.message == "forwarded_headers_rejected"]+ assert len(rejections) == 1, f"expected one rejection event, got {len(rejections)}"+ rec = rejections[0]+ # ``logging.makeLogRecord``-style: we set extras via ``extra=`` kwargs;+ # they end up as attributes on the record.+ assert getattr(rec, "event", None) == "forwarded_headers_rejected"+ assert getattr(rec, "peer_ip", None) == "8.8.8.8"+ assert getattr(rec, "forwarded_for", None) == "203.0.113.7"+ assert getattr(rec, "forwarded_proto", None) == "https"+ assert getattr(rec, "forwarded_host", None) == "api.example.com"+++def test_no_forwarded_headers_no_rejection_log(+ monkeypatch: pytest.MonkeyPatch,+ caplog: pytest.LogCaptureFixture,+) -> None:+ """Direct client (no X-Forwarded-* at all) must NOT spam rejection logs."""+ monkeypatch.setenv(TRUSTED_GATEWAY_CIDRS_ENV, "10.0.0.0/8")+ req = _fake_request(peer_host="8.8.8.8")+ with caplog.at_level(logging.WARNING, logger="headroom.proxy.forwarded_headers"):+ assert resolve_client_ip(req) == "8.8.8.8"+ assert trusted_forwarded_headers(req) == {"for": "", "proto": "", "host": ""}+ rejections = [r for r in caplog.records if r.message == "forwarded_headers_rejected"]+ assert rejections == []+++def test_empty_headers_with_allowlisted_peer(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """Allow-listed peer + no X-Forwarded-* headers → empty dict, no error."""+ monkeypatch.setenv(TRUSTED_GATEWAY_CIDRS_ENV, "10.0.0.0/8")+ req = _fake_request(peer_host="10.0.0.5")+ assert resolve_client_ip(req) == "10.0.0.5" # falls back to peer IP+ assert trusted_forwarded_headers(req) == {"for": "", "proto": "", "host": ""}+++def test_ipv6_allowlisted_peer_honors_forwarded(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ monkeypatch.setenv(TRUSTED_GATEWAY_CIDRS_ENV, "fd00::/8")+ req = _fake_request(+ peer_host="fd00::1",+ forwarded_for="2001:db8::42",+ forwarded_proto="https",+ forwarded_host="api.example.com",+ )+ assert resolve_client_ip(req) == "2001:db8::42"+ assert trusted_forwarded_headers(req) == {+ "for": "2001:db8::42",+ "proto": "https",+ "host": "api.example.com",+ }+++def test_ipv4_mapped_v6_peer_honors_forwarded(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """``::ffff:10.0.0.1`` peer matches a v4 allow-list."""+ monkeypatch.setenv(TRUSTED_GATEWAY_CIDRS_ENV, "10.0.0.0/8")+ req = _fake_request(+ peer_host="::ffff:10.0.0.1",+ forwarded_for="203.0.113.7",+ )+ assert resolve_client_ip(req) == "203.0.113.7"+++def test_multiple_cidrs_in_env_all_evaluated(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ monkeypatch.setenv(TRUSTED_GATEWAY_CIDRS_ENV, "10.0.0.0/8,172.16.0.0/12,fd00::/8")+ for peer in ("10.5.5.5", "172.16.5.5", "fd00::beef"):+ req = _fake_request(peer_host=peer, forwarded_for="203.0.113.7")+ assert resolve_client_ip(req) == "203.0.113.7", f"peer={peer}"+++def test_comma_whitespace_tolerance_in_env(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ monkeypatch.setenv(TRUSTED_GATEWAY_CIDRS_ENV, "10.0.0.0/8 , 172.16.0.0/12")+ for peer in ("10.5.5.5", "172.16.5.5"):+ req = _fake_request(peer_host=peer, forwarded_for="203.0.113.7")+ assert resolve_client_ip(req) == "203.0.113.7", f"peer={peer}"+++def test_x_forwarded_for_takes_leftmost(monkeypatch: pytest.MonkeyPatch) -> None:+ """``X-Forwarded-For: client, p1, p2`` → leftmost is the origin."""+ monkeypatch.setenv(TRUSTED_GATEWAY_CIDRS_ENV, "10.0.0.0/8")+ req = _fake_request(+ peer_host="10.0.0.5",+ forwarded_for="203.0.113.7, 10.0.0.99, 10.0.0.5",+ )+ assert resolve_client_ip(req) == "203.0.113.7"+++def test_no_client_no_forwarded_returns_empty(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """``request.client`` is None (TestClient/UDS): IP is empty string."""+ monkeypatch.delenv(TRUSTED_GATEWAY_CIDRS_ENV, raising=False)+ req = _fake_request(peer_host=None)+ assert resolve_client_ip(req) == ""+ assert trusted_forwarded_headers(req) == {"for": "", "proto": "", "host": ""}+++# ──────────────────────────────────────────────────────────────────+# Caching on request.state+# ──────────────────────────────────────────────────────────────────+++def test_resolution_cached_on_request_state(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """Repeat calls within a request must not re-parse the env var.++ We assert behaviourally: poison ``request.state.client_ip`` after the+ first call, then verify the second call returns the cached value+ (proving the second call hit the cache, not the resolver).+ """+ monkeypatch.setenv(TRUSTED_GATEWAY_CIDRS_ENV, "10.0.0.0/8")+ req = _fake_request(peer_host="10.0.0.5", forwarded_for="203.0.113.7")+ first = resolve_client_ip(req)+ assert first == "203.0.113.7"+ # Mutate the cached value; second call should observe it.+ req.state.client_ip = "SENTINEL"+ assert resolve_client_ip(req) == "SENTINEL"+++def test_trusted_forwarded_headers_returns_defensive_copy(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """Mutating the returned dict must not corrupt request-state cache."""+ monkeypatch.setenv(TRUSTED_GATEWAY_CIDRS_ENV, "10.0.0.0/8")+ req = _fake_request(+ peer_host="10.0.0.5",+ forwarded_for="203.0.113.7",+ forwarded_proto="https",+ forwarded_host="api.example.com",+ )+ fwd = trusted_forwarded_headers(req)+ fwd["proto"] = "POISONED"+ again = trusted_forwarded_headers(req)+ assert again["proto"] == "https"+++# ──────────────────────────────────────────────────────────────────+# Integration with FastAPI Request via TestClient+# ──────────────────────────────────────────────────────────────────+++def test_integration_with_real_fastapi_request(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """End-to-end: a real ``Request`` flows through helpers correctly.++ Uses Starlette's TestClient with a custom ``client=("10.0.0.5", ...)``+ so the peer IP looks like a trusted gateway. Default TestClient+ sets ``request.client.host == "testclient"``, which is not a valid+ IP literal and so always fails the gate (covered separately below).+ """+ monkeypatch.setenv(TRUSTED_GATEWAY_CIDRS_ENV, "10.0.0.0/8")+ app = FastAPI()++ @app.get("/whoami")+ def whoami(request: Request) -> dict[str, Any]:+ return {+ "client_ip": resolve_client_ip(request),+ "forwarded": trusted_forwarded_headers(request),+ }++ client = TestClient(app, client=("10.0.0.5", 50000))+ resp = client.get(+ "/whoami",+ headers={+ "X-Forwarded-For": "203.0.113.42",+ "X-Forwarded-Proto": "https",+ "X-Forwarded-Host": "api.example.com",+ },+ )+ assert resp.status_code == 200, resp.text+ body = resp.json()+ assert body["client_ip"] == "203.0.113.42"+ assert body["forwarded"] == {+ "for": "203.0.113.42",+ "proto": "https",+ "host": "api.example.com",+ }+++def test_integration_default_strict_ignores_forwarded(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ monkeypatch.delenv(TRUSTED_GATEWAY_CIDRS_ENV, raising=False)+ app = FastAPI()++ @app.get("/whoami")+ def whoami(request: Request) -> dict[str, Any]:+ return {+ "client_ip": resolve_client_ip(request),+ "forwarded": trusted_forwarded_headers(request),+ }++ client = TestClient(app, client=("10.0.0.5", 50000))+ resp = client.get(+ "/whoami",+ headers={"X-Forwarded-For": "203.0.113.42", "X-Forwarded-Proto": "https"},+ )+ body = resp.json()+ # Env unset → strict-secure: peer IP is the answer, X-Forwarded-* ignored.+ assert body["client_ip"] == "10.0.0.5"+ assert body["forwarded"] == {"for": "", "proto": "", "host": ""}+++def test_integration_non_ip_peer_fails_gate(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """Default TestClient host is the literal ``"testclient"`` — not an IP.++ Even if the operator wrote a 0.0.0.0/0 allow-list (the worst-case+ "trust everyone" config), a non-IP peer literal must still fail+ parsing and the gate must reject it. Belt-and-suspenders.+ """+ monkeypatch.setenv(TRUSTED_GATEWAY_CIDRS_ENV, "0.0.0.0/0")+ app = FastAPI()++ @app.get("/whoami")+ def whoami(request: Request) -> dict[str, Any]:+ return {+ "client_ip": resolve_client_ip(request),+ "forwarded": trusted_forwarded_headers(request),+ }++ client = TestClient(app)+ resp = client.get(+ "/whoami",+ headers={"X-Forwarded-For": "203.0.113.42"},+ )+ body = resp.json()+ assert body["client_ip"] == "testclient"+ assert body["forwarded"] == {"for": "", "proto": "", "host": ""}