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.

40.7 KB
Raw Blame
"""Loopback-gating tests for state-mutating / content-leaking endpoints.

``/transformations/feed`` can return full prompt + completion bodies (when
``log_full_messages`` is on) and ``/cache/clear`` mutates server state. With the
default ``--host 0.0.0.0`` Docker bind, neither should be reachable by an
arbitrary network client — they are gated to the loopback interface via
``require_loopback`` (the same guard already used for ``/admin/*`` and
``/debug/*``). See #863.
"""

from __future__ import annotations

import pytest
from fastapi import FastAPI
from fastapi.testclient import TestClient

from headroom.cache.backends import InMemoryBackend
from headroom.cache.compression_feedback import CompressionHints
from headroom.cache.compression_store import get_compression_store, reset_compression_store
from headroom.proxy.loopback_guard import is_ip_literal_host_header
from headroom.proxy.server import ProxyConfig, create_app

GATED = [
    ("get", "/transformations/feed"),
    ("post", "/cache/clear"),
    ("get", "/v1/telemetry"),
    ("get", "/v1/telemetry/export"),
    ("post", "/v1/telemetry/import"),
    ("get", "/v1/telemetry/tools"),
    ("get", "/v1/telemetry/tools/example"),
    ("get", "/v1/toin/stats"),
    ("get", "/v1/toin/patterns"),
    ("get", "/v1/toin/pattern/example"),
    # #2927 guarded the eight telemetry/TOIN routes the issue enumerated but
    # left these two siblings open, and their payload carries the same raw
    # agent query text (``common_queries``, built from ``event.query``).
    ("get", "/v1/feedback"),
    ("get", "/v1/feedback/example"),
]


def _make_app() -> FastAPI:
    return 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,
        )
    )


def _loopback_client() -> TestClient:
    # A real loopback peer + a loopback Host header — passes both guard gates
    # (client-IP check and the DNS-rebinding Host-header check).
    return TestClient(_make_app(), base_url="http://127.0.0.1", client=("127.0.0.1", 12345))


def test_debug_memory_is_available_to_loopback_published_container_host(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    monkeypatch.setenv("HEADROOM_CONTAINER_HOST_GATEWAY", "172.17.0.1")
    app = create_app(ProxyConfig(optimize=False, cache_enabled=False, stateless=True))
    loopback = TestClient(app, base_url="http://127.0.0.1:8787", client=("127.0.0.1", 1))
    host = TestClient(app, base_url="http://127.0.0.1:8787", client=("172.17.0.1", 1))
    other_container = TestClient(app, base_url="http://127.0.0.1:8787", client=("172.17.0.5", 1))
    wrong_host = TestClient(app, base_url="http://attacker.example:8787", client=("172.17.0.1", 1))

    assert "/debug/memory" in host.get("/openapi.json").json()["paths"]
    assert loopback.get("/debug/memory").status_code == 200
    response = host.get("/debug/memory")

    assert response.status_code == 200, response.text
    assert "process" in response.json()
    assert other_container.get("/debug/memory").status_code == 404
    assert wrong_host.get("/debug/memory").status_code == 404


def _seed_ccr_entry() -> str:
    reset_compression_store()
    store = get_compression_store(backend=InMemoryBackend())
    return store.store(
        "seeded-ccr-content",
        "<<ccr:seeded>>",
        original_tokens=3,
        compressed_tokens=1,
        tool_name="seeded-test",
    )


@pytest.mark.parametrize("method,path", GATED)
def test_non_loopback_caller_gets_404(method: str, path: str) -> None:
    # A vanilla TestClient presents client.host="testclient", which is not a
    # loopback IP, so the guard returns 404 (invisible, not 403).
    client = TestClient(_make_app())
    resp = client.request(method, path)
    assert resp.status_code == 404, resp.text


@pytest.mark.parametrize("method,path", GATED)
def test_loopback_caller_allowed(method: str, path: str) -> None:
    client = _loopback_client()
    resp = client.request(method, path, json={} if method == "post" else None)
    # Detail routes legitimately return 404 when their test key is absent;
    # the companion non-loopback test proves the guard itself.
    assert resp.status_code in {200, 404, 422}, resp.text


def test_toin_pattern_detail_whitelists_learned_payload(monkeypatch: pytest.MonkeyPatch) -> None:
    class FakeTOIN:
        def export_patterns(self):
            return {
                "patterns": {
                    "unknown|unknown|abc123": {
                        "sample_size": 10,
                        "total_compressions": 8,
                        "total_retrievals": 2,
                        "retrieval_rate": 0.25,
                        "confidence": 0.4,
                        "skip_compression_recommended": False,
                        "optimal_max_items": 20,
                        "query_pattern_frequency": {"secret prompt": 1},
                        "common_query_patterns": ["secret prompt"],
                        "field_semantics": {"secret": "value"},
                    }
                }
            }

    monkeypatch.setattr("headroom.proxy.server.get_toin", lambda: FakeTOIN())
    client = _loopback_client()
    identifier = client.get("/v1/toin/patterns").json()[0]["hash"]
    response = client.get(f"/v1/toin/pattern/{identifier}")

    assert response.status_code == 200
    assert response.json() == {
        "compressions": 8,
        "retrievals": 2,
        "retrieval_rate": 0.25,
        "confidence": 0.4,
        "skip_recommended": False,
        "optimal_max_items": 20,
    }


@pytest.fixture
def scoped_toin(monkeypatch: pytest.MonkeyPatch, tmp_path):
    from headroom.telemetry.toin import TOINConfig, ToolIntelligenceNetwork

    toin = ToolIntelligenceNetwork(TOINConfig(storage_path=str(tmp_path / "toin.json")))
    patterns = {
        "global|unknown|unknown|abc123": 8,
        "global|unknown|unknown|abc456": 16,
        "global|payg|claude|abc123": 24,
        "other-tenant|unknown|unknown|abc123": 32,
        "tenant/alpha?scope=one#fragment|unknown|unknown|abc123": 40,
    }
    toin.import_patterns(
        {
            "instance_id": "scoped-pattern-regression",
            "patterns": {
                key: {
                    "tool_signature_hash": key.rsplit("|", 1)[-1],
                    "sample_size": count,
                    "total_compressions": count,
                    "total_retrievals": 0,
                }
                for key, count in patterns.items()
            },
        }
    )
    monkeypatch.setattr("headroom.proxy.server.get_toin", lambda: toin)
    return patterns


def test_listed_toin_identifiers_address_their_own_scoped_pattern(scoped_toin) -> None:
    from urllib.parse import quote

    client = _loopback_client()
    listed = client.get("/v1/toin/patterns").json()
    assert {item["hash"] for item in listed} == set(scoped_toin)
    for item in listed:
        response = client.get(f"/v1/toin/pattern/{quote(item['hash'], safe='')}")
        assert response.status_code == 200
        assert response.json()["compressions"] == item["compressions"]


@pytest.mark.parametrize(
    ("prefix", "status", "count"),
    [
        ("global|unknown|unknown|abc", 409, None),
        ("global|unknown|unknown|abc1", 200, 8),
        ("missing-pattern", 404, None),
    ],
)
def test_toin_prefix_lookup_is_unambiguous(scoped_toin, prefix, status, count) -> None:
    response = _loopback_client().get(f"/v1/toin/pattern/{prefix}")
    assert response.status_code == status
    if count is not None:
        assert response.json()["compressions"] == count


# Mutating routes reachable from loopback. `require_loopback` cannot stop a
# remote page from POSTing to a known 127.0.0.1 URL: a "simple" cross-origin
# request (Content-Type: text/plain carrying JSON) skips preflight, and the
# browser still sends the real loopback Host header. Only `Origin` betrays the
# attacker, and only `require_same_origin` inspects it.
CSRF_GUARDED = [
    "/stats/reset",
    "/cache/clear",
    "/v1/retrieve",
    "/v1/retrieve/tool_call",
    "/v1/telemetry/import",
    "/admin/runtime-env",
]


@pytest.mark.parametrize("path", CSRF_GUARDED)
def test_cross_origin_post_rejected(path: str) -> None:
    resp = _loopback_client().post(
        path,
        headers={"Origin": "https://attacker.example", "Content-Type": "text/plain"},
        content="{}",
    )
    assert resp.status_code == 403, resp.text


@pytest.mark.parametrize("path", CSRF_GUARDED)
def test_sandboxed_null_origin_post_rejected(path: str) -> None:
    # A sandboxed iframe or file:// page sends the opaque literal "null".
    resp = _loopback_client().post(
        path,
        headers={"Origin": "null", "Content-Type": "text/plain"},
        content="{}",
    )
    assert resp.status_code == 403, resp.text


@pytest.mark.parametrize("path", CSRF_GUARDED)
def test_loopback_origin_post_allowed(path: str) -> None:
    # The local dashboard is same-origin on loopback and must keep working.
    resp = _loopback_client().post(
        path,
        headers={"Origin": "http://127.0.0.1"},
        json={},
    )
    assert resp.status_code != 403, resp.text


@pytest.mark.parametrize("path", CSRF_GUARDED)
def test_originless_post_allowed(path: str) -> None:
    # CLI tools and the TypeScript SDK send no Origin header at all; the guard
    # must pass them through or it breaks every non-browser client.
    resp = _loopback_client().post(path, json={})
    assert resp.status_code != 403, resp.text


def _feedback_with_query_text():
    """A feedback singleton whose patterns carry raw agent query text."""

    class FakePattern:
        total_compressions = 8
        total_retrievals = 2
        retrieval_rate = 0.25
        full_retrieval_rate = 0.1
        search_rate = 0.5
        common_queries = {"find the customer api key rotation runbook": 3}
        queried_fields = {"internal_field_name": 2}

    class FakeFeedback:
        def get_stats(self):
            return {
                "total_compressions": 8,
                "total_retrievals": 2,
                "global_retrieval_rate": 0.25,
                "tools_tracked": 1,
                "tool_patterns": {
                    "Grep": {
                        "compressions": 8,
                        "retrievals": 2,
                        "retrieval_rate": 0.25,
                        "full_rate": 0.1,
                        "search_rate": 0.5,
                        "common_queries": ["find the customer api key rotation runbook"],
                        "queried_fields": ["internal_field_name"],
                    }
                },
            }

        def get_compression_hints(self, tool_name):
            # The real implementation is annotated ``-> CompressionHints`` and
            # always returns one, so the double must too.
            return CompressionHints()

        def get_all_patterns(self):
            return {"Grep": FakePattern()}

    return FakeFeedback()


def test_feedback_stats_exclude_agent_query_text(monkeypatch: pytest.MonkeyPatch) -> None:
    monkeypatch.setattr(
        "headroom.proxy.server.get_compression_feedback",
        _feedback_with_query_text,
    )
    response = _loopback_client().get("/v1/feedback")

    assert response.status_code == 200
    pattern = response.json()["feedback"]["tool_patterns"]["Grep"]
    assert "common_queries" not in pattern
    assert "queried_fields" not in pattern
    # The aggregate counters the endpoint exists to expose still survive.
    assert pattern["retrieval_rate"] == 0.25
    assert "customer api key rotation" not in response.text


def test_feedback_tool_detail_excludes_agent_query_text(monkeypatch: pytest.MonkeyPatch) -> None:
    monkeypatch.setattr(
        "headroom.proxy.server.get_compression_feedback",
        _feedback_with_query_text,
    )
    response = _loopback_client().get("/v1/feedback/Grep")

    assert response.status_code == 200
    pattern = response.json()["pattern"]
    assert "common_queries" not in pattern
    assert "queried_fields" not in pattern
    assert pattern["retrieval_rate"] == 0.25
    assert "customer api key rotation" not in response.text
    assert "internal_field_name" not in response.text


# CCR data endpoints — cached session content, gated to 404 off-loopback (#1227).
def test_stats_lifetime_route_uses_dashboard_metadata_access_policy(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    monkeypatch.setenv(
        "HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS",
        "100.90.0.5/32",
    )
    app = _make_app()
    expected = {
        "requests": {"total": 7},
        "projects": {"headroom": {"requests": 3}},
        "persistence": {
            "enabled": True,
            "healthy": False,
            "error": "D:/private/proxy_savings.json: access denied",
        },
    }
    monkeypatch.setattr(
        app.state.proxy.metrics.savings_tracker,
        "lifetime_response",
        lambda: expected,
    )

    network = TestClient(app).get("/stats-lifetime")
    assert network.status_code == 200, network.text
    assert network.json() == {
        "requests": {"total": 7},
        "persistence": {
            "enabled": True,
            "healthy": False,
            "error": None,
        },
    }

    loopback = TestClient(
        app,
        base_url="http://127.0.0.1",
        client=("127.0.0.1", 12345),
    ).get("/stats-lifetime")
    assert loopback.status_code == 200, loopback.text
    assert loopback.json() == expected

    trusted_dashboard = TestClient(
        app,
        base_url="http://100.82.0.2:8787",
        client=("100.90.0.5", 12345),
    ).get("/stats-lifetime")
    assert trusted_dashboard.status_code == 200, trusted_dashboard.text
    assert trusted_dashboard.json() == expected


CCR_GATED = [
    ("post", "/v1/retrieve"),
    ("get", "/v1/retrieve/stats"),
    ("get", "/v1/retrieve/somehash"),
    ("post", "/v1/retrieve/tool_call"),
    ("post", "/v1/compress"),
]


@pytest.mark.parametrize("method,path", CCR_GATED)
def test_ccr_non_loopback_gets_404(method: str, path: str) -> None:
    resp = TestClient(_make_app()).request(method, path, json={})
    assert resp.status_code == 404, resp.text


def test_ccr_retrieve_hash_route_blocks_valid_hash_for_non_loopback() -> None:
    ccr_hash = _seed_ccr_entry()
    try:
        loopback = _loopback_client()
        loopback_resp = loopback.get(f"/v1/retrieve/{ccr_hash}")
        assert loopback_resp.status_code == 200, loopback_resp.text
        assert loopback_resp.json()["original_content"] == "seeded-ccr-content"

        network_resp = TestClient(_make_app()).get(f"/v1/retrieve/{ccr_hash}")
        assert network_resp.status_code == 404, network_resp.text
    finally:
        reset_compression_store()


SETTINGS_GATED = [
    ("get", "/settings/schema"),
    ("get", "/settings"),
    ("get", "/dashboard/settings"),
]


@pytest.mark.parametrize("method,path", SETTINGS_GATED)
def test_settings_non_loopback_gets_404_without_trusted_cidr(method: str, path: str) -> None:
    resp = TestClient(_make_app()).request(method, path)
    assert resp.status_code == 404, resp.text


@pytest.mark.parametrize("method,path", SETTINGS_GATED)
def test_settings_loopback_caller_allowed(method: str, path: str) -> None:
    resp = _loopback_client().request(method, path)
    assert resp.status_code == 200, resp.text


@pytest.mark.parametrize("method,path", SETTINGS_GATED)
def test_settings_trusted_gateway_dashboard_client_allowed(
    monkeypatch: pytest.MonkeyPatch, method: str, path: str
) -> None:
    """Settings routes must follow the same trust chain as /stats so the
    dashboard works behind a reverse-proxy/gateway (#2466)."""
    monkeypatch.setenv("HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS", "100.90.0.5/32")
    client = TestClient(
        _make_app(),
        base_url="http://100.82.0.2:8787",
        client=("100.90.0.5", 12345),
    )
    resp = client.request(method, path)
    assert resp.status_code == 200, resp.text


def test_settings_trusted_gateway_cidr_mismatch_still_404s(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    monkeypatch.setenv("HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS", "100.90.0.5/32")
    client = TestClient(
        _make_app(),
        base_url="http://100.82.0.2:8787",
        client=("100.90.0.9", 12345),
    )
    assert client.get("/settings").status_code == 404


@pytest.mark.parametrize(
    "path,body",
    [("/settings", {"values": {}}), ("/settings/apply", None)],
)
def test_settings_post_trusted_gateway_client_same_origin_allowed(
    monkeypatch: pytest.MonkeyPatch, path: str, body: dict | None
) -> None:
    """Regression for #2491 review: a trusted-gateway dashboard client's real
    same-origin browser POST (Origin matching this Host) must not be rejected
    by the loopback-only same-origin guard."""
    monkeypatch.setenv("HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS", "100.90.0.5/32")
    client = TestClient(
        _make_app(),
        base_url="http://100.82.0.2:8787",
        client=("100.90.0.5", 12345),
    )
    resp = client.post(path, json=body, headers={"origin": "http://100.82.0.2:8787"})
    assert resp.status_code != 403, resp.text


@pytest.mark.parametrize(
    "path,body",
    [("/settings", {"values": {}}), ("/settings/apply", None)],
)
def test_settings_post_trusted_gateway_client_mismatched_origin_rejected(
    monkeypatch: pytest.MonkeyPatch, path: str, body: dict | None
) -> None:
    """A trusted-gateway peer with a foreign Origin is still CSRF-rejected.

    The mismatched Origin also fails the first (loopback-or-trusted-client)
    gate's own same-origin check, so this surfaces as 404, not 403 -- either
    way the write must not go through."""
    monkeypatch.setenv("HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS", "100.90.0.5/32")
    client = TestClient(
        _make_app(),
        base_url="http://100.82.0.2:8787",
        client=("100.90.0.5", 12345),
    )
    resp = client.post(path, json=body, headers={"origin": "http://attacker.example"})
    assert resp.status_code in (403, 404), resp.text


def test_settings_post_loopback_null_origin_still_rejected() -> None:
    """Loopback callers keep the stricter loopback-only origin check: a
    sandboxed-iframe/file:// "null" Origin must still 403, unaffected by the
    trusted-dashboard-client carve-out."""
    client = _loopback_client()
    resp = client.post("/settings", json={"values": {}}, headers={"origin": "null"})
    assert resp.status_code == 403, resp.text


def test_dns_rebinding_host_header_rejected() -> None:
    # Loopback peer IP but an attacker-controlled Host header (the DNS-rebinding
    # shape) must still be rejected by the second gate.
    client = TestClient(_make_app(), base_url="http://127.0.0.1", client=("127.0.0.1", 12345))
    resp = client.get("/transformations/feed", headers={"host": "attacker.example"})
    assert resp.status_code == 404, resp.text


@pytest.mark.parametrize(
    "host_header",
    ["100.82.0.2", "100.82.0.2:8787", "[fd7a:115c:a1e0::2]", "[fd7a:115c:a1e0::2]:8787"],
)
def test_ip_literal_host_header_accepts_ip_addresses(host_header: str) -> None:
    assert is_ip_literal_host_header(host_header) is True


@pytest.mark.parametrize(
    "host_header",
    [None, "", "attacker.example", "localhost", "[email protected]", "100.82.0.2/path", "[fd7a::1"],
)
def test_ip_literal_host_header_rejects_non_addresses(host_header: str | None) -> None:
    assert is_ip_literal_host_header(host_header) is False


def _client(*, loopback: bool) -> TestClient:
    app = _make_app()
    if loopback:
        return TestClient(app, base_url="http://127.0.0.1", client=("127.0.0.1", 12345))
    # Default TestClient presents client.host="testclient" — not loopback.
    return TestClient(app)


def test_health_config_block_is_loopback_only(monkeypatch: pytest.MonkeyPatch) -> None:
    """/health stays reachable for monitors but hides the `config` block (which
    echoes upstream API URLs + backend settings) from non-loopback callers."""
    monkeypatch.setenv("HEADROOM_SKIP_UPSTREAM_CHECK", "1")

    network = _client(loopback=False).get("/health")
    assert network.status_code == 200
    assert "config" not in network.json()
    # Basic health is still visible to monitors.
    assert network.json()["status"] in {"healthy", "unhealthy"}

    local = _client(loopback=True).get("/health")
    assert local.status_code == 200
    assert "config" in local.json()


@pytest.mark.parametrize(
    ("exclude_tools", "requested"),
    [(None, "Bash"), ({"WebSearch"}, "Bash,WebSearch")],
)
def test_protected_tool_reuse_does_not_warn_about_missing_exclusions(
    monkeypatch: pytest.MonkeyPatch,
    capsys: pytest.CaptureFixture[str],
    exclude_tools: set[str] | None,
    requested: str,
) -> None:
    from headroom.cli.wrap import _warn_proxy_mode_mismatch

    monkeypatch.setenv("HEADROOM_SKIP_UPSTREAM_CHECK", "1")
    monkeypatch.delenv("HEADROOM_MODE", raising=False)
    monkeypatch.delenv("HEADROOM_MIN_TOKENS", raising=False)
    monkeypatch.setenv("HEADROOM_EXCLUDE_TOOLS", requested)
    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,
            disable_kompress=True,
            exclude_tools=exclude_tools,
            protect_tool_results={"Bash"},
        )
    )
    client = TestClient(app, base_url="http://127.0.0.1", client=("127.0.0.1", 12345))
    response = client.get("/health")
    assert response.status_code == 200

    capsys.readouterr()
    _warn_proxy_mode_mismatch(response.json()["config"])
    assert capsys.readouterr().out == ""


def test_stats_per_request_metadata_is_loopback_only() -> None:
    """/stats keeps aggregate counters public but restricts per-request metadata
    (recent_requests / request_logs) and `config` to loopback callers."""
    network = _client(loopback=False).get("/stats")
    assert network.status_code == 200
    payload = network.json()
    assert "tokens" in payload  # aggregate counters still served
    assert "recent_requests" not in payload
    assert "request_logs" not in payload
    assert "config" not in payload

    local = _client(loopback=True).get("/stats").json()
    assert "recent_requests" in local
    assert "config" in local


def test_stats_metadata_served_to_trusted_gateway_peer(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """Containerized dashboards: a browser on the host reaches a bridge-network
    container via the gateway IP, so the peer isn't 127.0.0.1 and per-request
    metadata gets stripped. When the operator allow-lists the gateway CIDR via
    HEADROOM_PROXY_TRUSTED_GATEWAY_CIDRS, the peer is treated as
    loopback-equivalent and the metadata is served again."""
    gateway_ip = "172.18.0.1"  # typical docker/mocker bridge gateway
    app = _make_app()

    def _gateway_client() -> TestClient:
        # Loopback Host header (the operator browses http://127.0.0.1:8787) but
        # the peer IP is the container gateway, not loopback.
        return TestClient(app, base_url="http://127.0.0.1", client=(gateway_ip, 54321))

    # Without the allow-list, the gateway peer is untrusted → metadata stripped.
    monkeypatch.delenv("HEADROOM_PROXY_TRUSTED_GATEWAY_CIDRS", raising=False)
    stripped = _gateway_client().get("/stats").json()
    assert "recent_requests" not in stripped
    assert "config" not in stripped

    # Allow-list the gateway CIDR → peer trusted → metadata served.
    monkeypatch.setenv("HEADROOM_PROXY_TRUSTED_GATEWAY_CIDRS", "172.18.0.0/16")
    served = _gateway_client().get("/stats").json()
    assert "recent_requests" in served
    assert "config" in served

    # DNS-rebinding defence still applies even for a trusted gateway peer: a
    # non-loopback Host header must be rejected.
    rebind = TestClient(app, base_url="http://attacker.example", client=(gateway_ip, 54321))
    payload = rebind.get("/stats").json()
    assert "recent_requests" not in payload


@pytest.mark.parametrize("cached", [False, True])
def test_dashboard_client_cidr_grants_stats_metadata_for_ip_literal_host(
    monkeypatch: pytest.MonkeyPatch,
    cached: bool,
) -> None:
    monkeypatch.setenv("HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS", "100.90.0.5/32")
    app = _make_app()
    client = TestClient(
        app,
        base_url="http://100.82.0.2:8787",
        client=("100.90.0.5", 12345),
    )

    payload = client.get("/stats", params={"cached": int(cached)}).json()

    assert "recent_requests" in payload
    assert "request_logs" in payload
    assert "config" in payload


@pytest.mark.parametrize(
    "headers",
    [
        {"origin": "http://100.82.0.2:8787"},
        {"referer": "http://100.82.0.2:8787/dashboard"},
    ],
)
@pytest.mark.parametrize("cached", [False, True])
def test_dashboard_client_cidr_grants_stats_metadata_to_same_origin_browser(
    monkeypatch: pytest.MonkeyPatch, headers: dict[str, str], cached: bool
) -> None:
    monkeypatch.setenv("HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS", "100.90.0.5/32")
    client = TestClient(
        _make_app(),
        base_url="http://100.82.0.2:8787",
        client=("100.90.0.5", 12345),
    )

    payload = client.get("/stats", params={"cached": int(cached)}, headers=headers).json()

    assert "recent_requests" in payload
    assert "request_logs" in payload
    assert "config" in payload


@pytest.mark.parametrize(
    "headers",
    [
        {"origin": "http://attacker.example"},
        {"referer": "http://attacker.example/dashboard"},
    ],
)
@pytest.mark.parametrize("cached", [False, True])
def test_dashboard_client_cidr_hides_stats_metadata_from_cross_origin_browser(
    monkeypatch: pytest.MonkeyPatch, headers: dict[str, str], cached: bool
) -> None:
    monkeypatch.setenv("HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS", "100.90.0.5/32")
    client = TestClient(
        _make_app(),
        base_url="http://100.82.0.2:8787",
        client=("100.90.0.5", 12345),
    )

    response = client.get("/stats", params={"cached": int(cached)}, headers=headers)
    payload = response.json()

    assert response.status_code == 200
    assert "tokens" in payload
    assert "recent_requests" not in payload
    assert "request_logs" not in payload
    assert "config" not in payload


def test_dashboard_client_cidr_only_uses_forwarded_proto_from_trusted_gateway(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    monkeypatch.setenv("HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS", "100.90.0.5/32")
    monkeypatch.setenv("HEADROOM_PROXY_TRUSTED_GATEWAY_CIDRS", "172.18.0.0/16")
    client = TestClient(
        _make_app(),
        base_url="http://100.82.0.2:8787",
        client=("172.18.0.1", 12345),
    )

    payload = client.get(
        "/stats",
        headers={
            "origin": "https://100.82.0.2:8787",
            "x-forwarded-for": "100.90.0.5",
            "x-forwarded-proto": "https",
        },
    ).json()

    assert "recent_requests" in payload
    assert "request_logs" in payload
    assert "config" in payload

    spoofed = (
        TestClient(
            _make_app(),
            base_url="http://100.82.0.2:8787",
            client=("100.90.0.5", 12345),
        )
        .get(
            "/stats",
            headers={
                "origin": "https://100.82.0.2:8787",
                "x-forwarded-proto": "https",
            },
        )
        .json()
    )

    assert "recent_requests" not in spoofed
    assert "request_logs" not in spoofed
    assert "config" not in spoofed


def test_dashboard_client_cidr_rejects_unlisted_clients_and_hostname_hosts(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    monkeypatch.setenv("HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS", "100.90.0.5/32")
    app = _make_app()

    unlisted = (
        TestClient(
            app,
            base_url="http://100.82.0.2:8787",
            client=("100.90.0.6", 12345),
        )
        .get("/stats")
        .json()
    )
    hostname = (
        TestClient(
            app,
            base_url="http://100.82.0.2:8787",
            client=("100.90.0.5", 12345),
        )
        .get("/stats", headers={"host": "attacker.example"})
        .json()
    )

    for payload in (unlisted, hostname):
        assert "recent_requests" not in payload
        assert "request_logs" not in payload
        assert "config" not in payload


def test_dashboard_client_cidr_only_accepts_forwarded_client_from_trusted_gateway(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    monkeypatch.setenv("HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS", "100.90.0.5/32")
    monkeypatch.setenv("HEADROOM_PROXY_TRUSTED_GATEWAY_CIDRS", "172.18.0.0/16")
    app = _make_app()

    trusted = (
        TestClient(
            app,
            base_url="http://100.82.0.2:8787",
            client=("172.18.0.1", 12345),
        )
        .get("/stats", headers={"x-forwarded-for": "100.90.0.5"})
        .json()
    )
    forged = (
        TestClient(
            app,
            base_url="http://100.82.0.2:8787",
            client=("198.51.100.10", 12345),
        )
        .get("/stats", headers={"x-forwarded-for": "100.90.0.5"})
        .json()
    )

    assert "recent_requests" in trusted
    assert "recent_requests" not in forged


def test_dashboard_client_cidr_normalizes_ipv4_mapped_ipv6(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    monkeypatch.setenv("HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS", "100.90.0.0/24")
    app = _make_app()
    payload = (
        TestClient(
            app,
            base_url="http://100.82.0.2:8787",
            client=("::ffff:100.90.0.5", 12345),
        )
        .get("/stats")
        .json()
    )

    assert "recent_requests" in payload


def test_dashboard_client_cidr_does_not_expand_other_management_endpoints(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    monkeypatch.setenv("HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS", "100.90.0.5/32")
    client = TestClient(
        _make_app(),
        base_url="http://100.82.0.2:8787",
        client=("100.90.0.5", 12345),
    )

    health = client.get("/health")
    assert health.status_code == 200
    assert "config" not in health.json()
    assert client.get("/admin/upstream").status_code == 404
    assert client.get("/debug/tasks").status_code == 404
    assert client.post("/stats/reset").status_code == 404


# ─────────────────────── read-only telemetry routes ─────────────────────────
# These carried operator data (model/project/session labels, spend history,
# subscription utilisation, provider quota) to any network caller. They now
# share the /settings* trust chain: loopback or a trusted dashboard client
# behind a gateway; everyone else sees 404. The dashboard shell is a static
# template and stays reachable.

DASHBOARD_GATED = [
    ("get", "/stats-history"),
    ("get", "/stats-history?format=csv"),
    ("get", "/quota"),
    ("get", "/subscription-window"),
]


@pytest.mark.parametrize("method,path", DASHBOARD_GATED)
def test_dashboard_routes_non_loopback_gets_404(method: str, path: str) -> None:
    resp = TestClient(_make_app()).request(method, path)
    assert resp.status_code == 404, resp.text


@pytest.mark.parametrize("method,path", DASHBOARD_GATED)
def test_dashboard_routes_loopback_caller_allowed(method: str, path: str) -> None:
    resp = _loopback_client().request(method, path)
    # /subscription-window answers 503 when tracking is off; the point here is
    # that the *guard* let the caller through.
    assert resp.status_code != 404, resp.text


@pytest.mark.parametrize("method,path", DASHBOARD_GATED)
def test_dashboard_routes_trusted_gateway_dashboard_client_allowed(
    monkeypatch: pytest.MonkeyPatch, method: str, path: str
) -> None:
    monkeypatch.setenv("HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS", "100.90.0.5/32")
    client = TestClient(
        _make_app(),
        base_url="http://100.82.0.2:8787",
        client=("100.90.0.5", 12345),
    )
    resp = client.request(method, path)
    assert resp.status_code != 404, resp.text


@pytest.mark.parametrize("method,path", DASHBOARD_GATED)
def test_dashboard_routes_token_authenticated_operator_allowed(
    monkeypatch: pytest.MonkeyPatch, method: str, path: str
) -> None:
    """With a token configured the security gate is the control: 401 without,
    through with. Mirrors the docker-bind e2e contract (correct token → 200)."""
    monkeypatch.setenv("HEADROOM_PROXY_TOKEN", "s3cr3t-token")
    app = _make_app()
    network = TestClient(app, base_url="http://headroom.svc.internal:8787", client=("10.10.0.7", 1))
    assert network.request(method, path).status_code == 401
    wrong = network.request(method, path, headers={"Authorization": "Bearer wrong"})
    assert wrong.status_code == 401
    ok = network.request(method, path, headers={"Authorization": "Bearer s3cr3t-token"})
    assert ok.status_code not in (401, 404), ok.text


@pytest.mark.parametrize("path", ["/stats-history", "/quota", "/metrics"])
def test_token_does_not_exempt_a_loopback_peer_from_the_host_check(
    monkeypatch: pytest.MonkeyPatch, path: str
) -> None:
    """The gate waves loopback peers through without a token, so a configured
    token must not short-cut the DNS-rebinding defence for them."""
    monkeypatch.setenv("HEADROOM_PROXY_TOKEN", "s3cr3t-token")
    app = _make_app()
    local = TestClient(app, base_url="http://127.0.0.1:8787", client=("127.0.0.1", 1))
    assert local.get(path).status_code != 404
    rebound = TestClient(app, base_url="http://attacker.example", client=("127.0.0.1", 1))
    assert rebound.get(path).status_code == 404


def test_dashboard_shell_is_not_gated() -> None:
    """Static template, no operator data: a container published on host loopback
    (peer = bridge gateway, Host = localhost) must still load it."""
    client = TestClient(_make_app(), base_url="http://localhost:8787", client=("172.17.0.1", 1))
    assert client.get("/dashboard").status_code == 200
    assert client.get("/stats-history").status_code == 404


def _acknowledged_container_app(monkeypatch: pytest.MonkeyPatch) -> FastAPI:
    """A token-less 0.0.0.0 bind acknowledged as published on host loopback,
    running in a container whose bridge gateway is 172.17.0.1."""
    monkeypatch.setenv("HEADROOM_ALLOW_UNAUTHENTICATED_BIND", "1")
    monkeypatch.setenv("HEADROOM_CONTAINER_HOST_GATEWAY", "172.17.0.1")
    return create_app(
        ProxyConfig(
            host="0.0.0.0",
            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,
        )
    )


@pytest.mark.parametrize("path", ["/stats-history", "/quota", "/subscription-window"])
def test_loopback_published_container_serves_dashboard_data_to_its_host(
    monkeypatch: pytest.MonkeyPatch, path: str
) -> None:
    """Host browser -> 127.0.0.1 publication -> container sees the bridge gateway."""
    app = _acknowledged_container_app(monkeypatch)
    host = TestClient(app, base_url="http://localhost:8787", client=("172.17.0.1", 1))
    assert host.get(path).status_code != 404


@pytest.mark.parametrize(
    "client,base_url,headers",
    [
        # Another container on the same bridge is not the host.
        (("172.17.0.5", 1), "http://127.0.0.1:8787", {}),
        # The trust is the TCP peer; a forwarded header naming the gateway is ignored.
        (("172.17.0.5", 1), "http://127.0.0.1:8787", {"X-Forwarded-For": "172.17.0.1"}),
        # The DNS-rebinding defence still applies to the gateway peer.
        (("172.17.0.1", 1), "http://attacker.example:8787", {}),
    ],
)
def test_loopback_published_container_trust_is_exact(
    monkeypatch: pytest.MonkeyPatch,
    client: tuple[str, int],
    base_url: str,
    headers: dict[str, str],
) -> None:
    app = _acknowledged_container_app(monkeypatch)
    resp = TestClient(app, base_url=base_url, client=client).get("/stats-history", headers=headers)
    assert resp.status_code == 404


def test_container_gateway_needs_the_open_bind_acknowledgement(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """Without the launcher's acknowledgement nothing vouches for the publication."""
    monkeypatch.setenv("HEADROOM_CONTAINER_HOST_GATEWAY", "172.17.0.1")
    client = TestClient(_make_app(), base_url="http://localhost:8787", client=("172.17.0.1", 1))
    assert client.get("/stats-history").status_code == 404


def test_stats_history_csv_export_not_served_to_network_callers() -> None:
    """The CSV export is the whole spend/model/session history in one GET."""
    resp = TestClient(_make_app()).get("/stats-history", params={"format": "csv"})
    assert resp.status_code == 404
    assert "text/csv" not in resp.headers.get("content-type", "")


# ─────────────────────────────── /metrics ───────────────────────────────────
# A Prometheus target: it cannot demand the dashboard's IP-literal Host header,
# but it must not be a free read for every network peer either.


def test_metrics_non_loopback_gets_404_without_token_or_cidr() -> None:
    resp = TestClient(_make_app()).get("/metrics")
    assert resp.status_code == 404, resp.text


def test_metrics_loopback_allowed() -> None:
    resp = _loopback_client().get("/metrics")
    assert resp.status_code == 200, resp.text
    assert "text/plain" in resp.headers["content-type"]


def test_metrics_trusted_gateway_cidr_scraper_allowed(monkeypatch: pytest.MonkeyPatch) -> None:
    """A scraper inside HEADROOM_PROXY_TRUSTED_GATEWAY_CIDRS with a hostname Host."""
    monkeypatch.setenv("HEADROOM_PROXY_TRUSTED_GATEWAY_CIDRS", "10.9.0.0/24")
    client = TestClient(
        _make_app(),
        base_url="http://headroom.svc.internal:8787",
        client=("10.9.0.7", 40000),
    )
    assert client.get("/metrics").status_code == 200


def test_metrics_trusted_dashboard_cidr_allowed(monkeypatch: pytest.MonkeyPatch) -> None:
    monkeypatch.setenv("HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS", "100.90.0.5/32")
    client = TestClient(
        _make_app(),
        base_url="http://100.82.0.2:8787",
        client=("100.90.0.5", 12345),
    )
    assert client.get("/metrics").status_code == 200


def test_metrics_trusted_cidr_peer_outside_range_still_404s(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    monkeypatch.setenv("HEADROOM_PROXY_TRUSTED_GATEWAY_CIDRS", "10.9.0.0/24")
    client = TestClient(
        _make_app(),
        base_url="http://headroom.svc.internal:8787",
        client=("10.10.0.7", 40000),
    )
    assert client.get("/metrics").status_code == 404


def test_metrics_trusted_gateway_forwarding_an_outside_scraper_allowed(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """Gateway CIDRs vouch for the connecting peer, not the forwarded scraper."""
    monkeypatch.setenv("HEADROOM_PROXY_TRUSTED_GATEWAY_CIDRS", "10.9.0.0/24")
    client = TestClient(
        _make_app(),
        base_url="http://headroom.svc.internal:8787",
        client=("10.9.0.7", 40000),
    )
    resp = client.get("/metrics", headers={"X-Forwarded-For": "192.0.2.8"})
    assert resp.status_code == 200, resp.text


def test_metrics_forwarded_gateway_address_from_untrusted_peer_404s(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """Naming a gateway-CIDR address in X-Forwarded-For grants nothing."""
    monkeypatch.setenv("HEADROOM_PROXY_TRUSTED_GATEWAY_CIDRS", "10.9.0.0/24")
    client = TestClient(
        _make_app(),
        base_url="http://headroom.svc.internal:8787",
        client=("10.10.0.7", 40000),
    )
    resp = client.get("/metrics", headers={"X-Forwarded-For": "10.9.0.7"})
    assert resp.status_code == 404


def test_metrics_trusted_cidr_cross_origin_browser_rejected(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """Browser provenance from another origin is refused even from a trusted peer."""
    monkeypatch.setenv("HEADROOM_PROXY_TRUSTED_GATEWAY_CIDRS", "10.9.0.0/24")
    client = TestClient(
        _make_app(),
        base_url="http://headroom.svc.internal:8787",
        client=("10.9.0.7", 40000),
    )
    resp = client.get("/metrics", headers={"Origin": "http://attacker.example"})
    assert resp.status_code == 404


def test_metrics_token_authenticated_network_caller_allowed(
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    """With a token configured the security gate is the control; /metrics defers to it."""
    monkeypatch.setenv("HEADROOM_PROXY_TOKEN", "s3cr3t-token")
    app = _make_app()
    network = TestClient(app, base_url="http://headroom.svc.internal:8787", client=("10.10.0.7", 1))
    assert network.get("/metrics").status_code == 401
    ok = network.get("/metrics", headers={"Authorization": "Bearer s3cr3t-token"})
    assert ok.status_code == 200, ok.text