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): refuse token-less non-loopback binds, gate operator routes (#3852)
Tejas Chopraee731d7ea845
diff --git a/docker-compose.yml b/docker-compose.ymlindex 5036ed7b2..394e99d6f 100644--- a/docker-compose.yml+++ b/docker-compose.yml@@ -10,7 +10,9 @@# 3. point your LLM client at http://localhost:8787 (proxy)## Just want the proxy without the memory features? You can run the proxy image-# on its own (`docker run --rm -p 127.0.0.1:8787:8787 ghcr.io/headroomlabs-ai/headroom --host 0.0.0.0 --port 8787`); the two+# on its own (`docker run --rm -p 127.0.0.1:8787:8787 -e HEADROOM_ALLOW_UNAUTHENTICATED_BIND=1+# ghcr.io/headroomlabs-ai/headroom --host 0.0.0.0 --port 8787`; the env var acknowledges that the+# 127.0.0.1 publication, not a token, is what keeps the port private); the two# database services below are only required for the memory/relevance features.## Ports published on the host — all bound to 127.0.0.1 (this machine only):diff --git a/docker/docker-compose.native.yml b/docker/docker-compose.native.ymlindex 0995c3d79..aeac66f18 100644--- a/docker/docker-compose.native.yml+++ b/docker/docker-compose.native.yml@@ -30,6 +30,11 @@ services:HOME: /tmp/headroom-homeHEADROOM_HOST: 0.0.0.0HEADROOM_PROXY_TOKEN: ${HEADROOM_PROXY_TOKEN:-}+ # The container binds 0.0.0.0 so the loopback publication below can reach+ # it; the proxy refuses that bind without a token unless the operator+ # acknowledges it. This file always publishes on 127.0.0.1, so it does.+ # Irrelevant (and harmless) once HEADROOM_PROXY_TOKEN is set.+ HEADROOM_ALLOW_UNAUTHENTICATED_BIND: "1"# Canonical Headroom filesystem contract (issue #175). See `cli` service# above for rationale.HEADROOM_WORKSPACE_DIR: /tmp/headroom-home/.headroomdiff --git a/docs/content/docs/docker-install.mdx b/docs/content/docs/docker-install.mdxindex 511bcae64..a25812c0a 100644--- a/docs/content/docs/docker-install.mdx+++ b/docs/content/docs/docker-install.mdx@@ -62,17 +62,24 @@ headroom memory listFor `proxy`, the maintained wrapper always publishes the selected host port onloopback. It passes `--host 0.0.0.0` inside the container so that the loopbackpublication can reach the container, and it has no public-publication override.-For local-only use, no token is required:+For local-only use no token is needed, but the proxy refuses to start on a+non-loopback bind without one unless you acknowledge that the runtime already+restricts who can reach the port (here: the `127.0.0.1` publication):```bashdocker run --rm -it \-p 127.0.0.1:8787:8787 \+ -e HEADROOM_ALLOW_UNAUTHENTICATED_BIND=1 \-v "$PWD:/workspace" \-w /workspace \ghcr.io/headroomlabs-ai/headroom:latest \--host 0.0.0.0 --port 8787```+The maintained wrappers (`headroom install`, the `install.sh` / `install.ps1`+native wrappers, and `docker/docker-compose.native.yml`) set that acknowledgement+themselves, and only together with the `127.0.0.1` publication it depends on.+For deliberate public access, publish on an explicit public address and set`HEADROOM_PROXY_TOKEN`:diff --git a/docs/content/docs/proxy.mdx b/docs/content/docs/proxy.mdxindex b83fb3a0b..f9812a82e 100644--- a/docs/content/docs/proxy.mdx+++ b/docs/content/docs/proxy.mdx@@ -338,7 +338,8 @@ with a privileged job.| Flag / env | Default | Effect ||---|---|---|-| `HEADROOM_PROXY_TOKEN` | none | Require a token from non-loopback callers, as `X-Headroom-Proxy-Token: <token>` or `Authorization: Bearer <token>`. The token is removed from the request before it is forwarded upstream; clients that also send a provider credential should use `X-Headroom-Proxy-Token` and keep `Authorization` for the provider. |+| `HEADROOM_PROXY_TOKEN` | none | Require a token from non-loopback callers, as `X-Headroom-Proxy-Token: <token>` or `Authorization: Bearer <token>`. The token is removed from the request before it is forwarded upstream; clients that also send a provider credential should use `X-Headroom-Proxy-Token` and keep `Authorization` for the provider. Also gates the read-only operator routes (`/stats-history`, `/quota`, `/subscription-window`, `/metrics`), which otherwise answer loopback and trusted-CIDR callers only. |+| `HEADROOM_ALLOW_UNAUTHENTICATED_BIND` | `false` | Acknowledge a non-loopback bind (`--host 0.0.0.0`, `::`, a LAN address) with **no** `HEADROOM_PROXY_TOKEN`. Without a token or this flag the proxy refuses to start, because `/v1/*` would relay upstream with the operator's credentials for every peer that can reach the port. Only set it when the runtime already restricts reachability (a container published on `127.0.0.1`). || `HEADROOM_COMPRESS_ALLOW_REMOTE` | `false` | Allow non-loopback callers to reach [`POST /v1/compress`](#post-v1compress) and `POST /v1/usage`. Required to run Headroom as a remote gateway/sidecar; without it remote callers get `404`. || `--offline` / `HEADROOM_OFFLINE` | `false` | Air-gap mode: hard-disable **all** egress (telemetry, update checks, license reporting, model downloads). || `HEADROOM_LICENSE` | unset | Licence token, read by core and every licensed extension. `HEADROOM_LICENSE_KEY` is a deprecated alias for one release and logs a warning. A licence on its own sends nothing to Headroom. |diff --git a/e2e/docker-bind-security.sh b/e2e/docker-bind-security.shindex f9e17a879..a3af571d7 100644--- a/e2e/docker-bind-security.sh+++ b/e2e/docker-bind-security.sh@@ -116,9 +116,18 @@ docker run -d --rm --name "$base_container" --network "$network" -p "0.0.0.0:187-e "OPENAI_TARGET_API_URL=http://${mock_container}:8080" -e OPENAI_API_KEY=upstream-secret \"$base_image" >/dev/nulldocker run -d --rm --name "$head_container" --network "$network" -p "0.0.0.0:18784:8787" "$head_image" >/dev/null+# Loopback-published container that binds 0.0.0.0 inside: the proxy cannot see+# the host publication, so the operator acknowledges the token-less open bind.docker run -d --rm --name "$local_container" --network "$network" -p "127.0.0.1:18786:8787" \+ -e HEADROOM_ALLOW_UNAUTHENTICATED_BIND=1 \-e "OPENAI_TARGET_API_URL=http://${mock_container}:8080" -e OPENAI_API_KEY=upstream-secret \"$head_image" --host 0.0.0.0 --port 8787 >/dev/null+# Without the acknowledgement or a token, the same launch must refuse to start+# and name both ways out.+refused_output="$(docker run --rm --network "$network" "$head_image" --host 0.0.0.0 --port 8787 2>&1)" \+ && { echo "token-less 0.0.0.0 bind started without acknowledgement" >&2; exit 1; }+grep -Fq HEADROOM_PROXY_TOKEN <<<"$refused_output"+grep -Fq HEADROOM_ALLOW_UNAUTHENTICATED_BIND <<<"$refused_output"docker image inspect --format '{{range .Config.Env}}{{println .}}{{end}}' "$slim_image" \| grep -Fxq 'HEADROOM_HOST=127.0.0.1'docker run --rm --entrypoint python3 "$slim_image" -c 'import headroom._core; print("rust_core=loaded")'@@ -182,4 +191,4 @@ ws_key="$(printf '%s' 'the sample nonce' | base64 | tr -d '\n')"ws_status="$(docker run --rm --name "$attacker_container" --network "$network" curlimages/curl:8.12.1 --silent --output /dev/null --write-out '%{http_code}' --http1.1 -H 'Connection: Upgrade' -H 'Upgrade: websocket' -H 'Sec-WebSocket-Version: 13' -H "Sec-WebSocket-Key: ${ws_key}" "http://${host_ip}:18785/v1/live")"test "$ws_status" = "$ws_status_expected"printf 'base_ref=%s base_digest=%s head_digest=%s slim_digest=%s runtime_slim_config=loopback rust_core=loaded local_completion=200 attacker_loopback=000 ws_status=%s\n' "$base_ref" "$(docker image inspect --format='{{.Id}}' "$base_image")" "$(docker image inspect --format='{{.Id}}' "$head_image")" "$(docker image inspect --format='{{.Id}}' "$slim_image")" "$ws_status"-echo "docker bind security: fixture forwarding, loopback isolation, built-image health, slim-image loopback config, and token controls passed"+echo "docker bind security: fixture forwarding, loopback isolation, open-bind refusal, built-image health, slim-image loopback config, and token controls passed"diff --git a/headroom/cli/proxy.py b/headroom/cli/proxy.pyindex 2045f45da..e9ca230cb 100644--- a/headroom/cli/proxy.py+++ b/headroom/cli/proxy.py@@ -1640,21 +1640,33 @@ Memory (Multi-Provider):f"(available: {','.join(_ext_available)})")- # Security posture line: inbound auth token + air-gap mode, and a loud- # flag for the open-bind case (non-loopback host with no token).- from headroom.proxy.loopback_guard import is_loopback_host-- _auth_on = bool(config.proxy_token or os.environ.get("HEADROOM_PROXY_TOKEN"))+ # Security posture line: inbound auth token + air-gap mode. An open bind+ # (non-loopback host, no token) is refused here, before the banner, unless+ # the operator acknowledged it explicitly; see headroom/proxy/bind_policy.py.+ from headroom.proxy.bind_policy import OPEN_BIND_ACK_ENV, evaluate_bind_policy++ _bind = evaluate_bind_policy(config.host, config.proxy_token)+ if _bind.refused:+ raise click.ClickException(_bind.message())+ _auth_on = _bind.token_configured+ _open_bind_note = (+ f" · WARNING open bind, /v1/* UNAUTHENTICATED (acknowledged via {OPEN_BIND_ACK_ENV}=1)"+ if _bind.open_bind+ else ""+ )if config.offline:- _security_status = "OFFLINE (all egress disabled)" + (- " · inbound token REQUIRED (non-loopback)" if _auth_on else ""+ # Offline masks nothing: an acknowledged open bind is still an open bind.+ _security_status = (+ "OFFLINE (all egress disabled)"+ + (" · inbound token REQUIRED (non-loopback)" if _auth_on else "")+ + _open_bind_note)elif _auth_on:_security_status = "inbound token REQUIRED for non-loopback callers"- elif not is_loopback_host(config.host):+ elif _bind.open_bind:_security_status = ("WARNING non-loopback bind with NO token — /v1/* is UNAUTHENTICATED "- "(set HEADROOM_PROXY_TOKEN)"+ f"(acknowledged via {OPEN_BIND_ACK_ENV}=1; set HEADROOM_PROXY_TOKEN instead)")else:_security_status = "loopback-only (no inbound token)"diff --git a/headroom/install/runtime.py b/headroom/install/runtime.pyindex dd40104da..ce2bc5424 100644--- a/headroom/install/runtime.py+++ b/headroom/install/runtime.py@@ -15,13 +15,18 @@ from typing import Any, castfrom headroom._subprocess import pid_alive, run+from ..proxy.bind_policy import OPEN_BIND_ACK_ENVfrom .health import probe_readyfrom .models import DeploymentManifest, InstallPreset, RuntimeKind, SupervisorKindfrom .paths import log_path, pid_path, profile_rootfrom .state import load_manifest# Inside the container the proxy must listen on every interface so the-# host-side published port (127.0.0.1:<port>) can reach it.+# host-side published port (127.0.0.1:<port>) can reach it. The proxy refuses+# a non-loopback bind with no HEADROOM_PROXY_TOKEN unless it is acknowledged;+# this launcher always publishes on 127.0.0.1, so it acknowledges (see+# build_runtime_command). A token in the host env still flows through the+# HEADROOM_ passthrough and takes precedence over the acknowledgement.CONTAINER_BIND_HOST = "0.0.0.0" # noqa: S104 — container-internal bind, published only on 127.0.0.1# proxy_args always starts with the host flag/value pair (see planner.py); we# drop it and substitute CONTAINER_BIND_HOST for the in-container bind.@@ -136,6 +141,10 @@ def build_runtime_command(manifest: DeploymentManifest) -> list[str]:manifest.container_name,"-p",f"127.0.0.1:{manifest.port}:{manifest.port}",+ # Loopback-only publication is what makes the in-container 0.0.0.0+ # bind acceptable without a token; say so explicitly to the proxy.+ "--env",+ f"{OPEN_BIND_ACK_ENV}=1","--workdir",container_home,"--env",diff --git a/headroom/proxy/bind_policy.py b/headroom/proxy/bind_policy.pynew file mode 100644index 000000000..49258c6d3--- /dev/null+++ b/headroom/proxy/bind_policy.py@@ -0,0 +1,178 @@+"""Startup policy for the listener bind: no unauthenticated non-loopback bind.++The proxy's inbound trust model has two legs. Loopback callers are trusted+(same boundary as the ``/admin`` and ``/debug`` routes); everyone else must+present ``HEADROOM_PROXY_TOKEN``. That model has a hole when the token is not+configured *and* the listener is bound to a non-loopback interface: every+``/v1/*`` data-plane route -- which relays to the upstream provider with the+operator's own credentials where ``*_extra_headers`` or a subscription token+is configured -- answers any peer that can reach the port.++Until 0.40 the proxy only logged a warning for that shape. A warning is not a+control: launchers that set ``HEADROOM_HOST=0.0.0.0`` (systemd units, the+enterprise bundle's own start script, any ``docker run -p 8787:8787``) start+successfully and serve an unauthenticated relay. This module makes the+decision explicit and refuses to start unless the operator either configures+a token or *acknowledges* the open bind with+:data:`OPEN_BIND_ACK_ENV` -- the documented shape for a container that binds+``0.0.0.0`` internally but is published on ``127.0.0.1`` by the runtime, which+the process itself cannot observe.++The policy is evaluated in one place (:func:`evaluate_bind_policy`) and+enforced from three: :func:`headroom.proxy.server.create_app` (covers every+programmatic embedding and the multi-worker factory), :func:`run_server`+(before uvicorn forks workers, so a refusal is one clean error and not a+crash loop) and the ``headroom proxy`` CLI (before the banner, so the+operator sees the reason and not a traceback).+"""++from __future__ import annotations++import logging+import os+from collections.abc import Mapping+from dataclasses import dataclass++from headroom.exceptions import ConfigurationError+from headroom.proxy.loopback_guard import is_loopback_host++__all__ = [+ "DEFAULT_BIND_HOST",+ "OPEN_BIND_ACK_ENV",+ "PROXY_TOKEN_ENV",+ "BindPolicyDecision",+ "OpenBindRefused",+ "enforce_bind_policy",+ "evaluate_bind_policy",+]++logger = logging.getLogger(__name__)++#: Explicit operator acknowledgement that an unauthenticated non-loopback bind+#: is intended (for example a container published on a loopback port by the+#: runtime). Any of ``1``, ``true``, ``yes``, ``on`` (case-insensitive) enables it.+OPEN_BIND_ACK_ENV = "HEADROOM_ALLOW_UNAUTHENTICATED_BIND"++#: The inbound credential the policy is looking for. Named here so the error+#: text and the gate cannot drift on the variable name.+PROXY_TOKEN_ENV = "HEADROOM_PROXY_TOKEN"++#: uvicorn's default when no host is configured at all.+DEFAULT_BIND_HOST = "127.0.0.1"++_TRUE_VALUES = frozenset({"1", "true", "yes", "on"})+++class OpenBindRefused(ConfigurationError):+ """The proxy was asked to bind a non-loopback interface with no inbound token.++ Raised by :func:`enforce_bind_policy`. Callers that own a process (the CLI,+ :func:`run_server`) turn it into a clean non-zero exit; embedders see a+ :class:`~headroom.exceptions.ConfigurationError` they can handle.+ """++ def __init__(self, decision: BindPolicyDecision) -> None:+ self.decision = decision+ super().__init__(decision.message())+++@dataclass(frozen=True)+class BindPolicyDecision:+ """Outcome of evaluating the listener bind against the inbound auth config."""++ host: str+ token_configured: bool+ loopback: bool+ acknowledged: bool++ @property+ def open_bind(self) -> bool:+ """True when non-loopback callers can reach ``/v1/*`` with no credential."""+ return not self.token_configured and not self.loopback++ @property+ def refused(self) -> bool:+ """True when the proxy must not start: open bind, no acknowledgement."""+ return self.open_bind and not self.acknowledged++ def message(self) -> str:+ """Operator-facing explanation. Names both remedies explicitly."""+ if not self.open_bind:+ return f"bind {self.host}: inbound auth OK"+ if self.acknowledged:+ return (+ f"bind {self.host}: non-loopback bind with NO {PROXY_TOKEN_ENV} — "+ f"/v1/* is UNAUTHENTICATED; acknowledged via {OPEN_BIND_ACK_ENV}=1"+ )+ return (+ f"Refusing to bind {self.host!r}: the proxy would serve its /v1/* data-plane "+ f"routes to every peer on the network without authentication, relaying "+ f"requests with the operator's upstream credentials. Either set "+ f"{PROXY_TOKEN_ENV} (e.g. `openssl rand -hex 32`) so non-loopback callers "+ f"must present a bearer token, bind a loopback address (--host 127.0.0.1), "+ f"or — only when the runtime already restricts who can reach the port, such "+ f"as a container published on 127.0.0.1 — set {OPEN_BIND_ACK_ENV}=1 to "+ f"acknowledge the open bind explicitly."+ )+++def _env_flag(environ: Mapping[str, str], name: str) -> bool:+ value = environ.get(name)+ if value is None:+ return False+ return value.strip().lower() in _TRUE_VALUES+++def evaluate_bind_policy(+ host: str | None,+ proxy_token: str | None,+ *,+ environ: Mapping[str, str] | None = None,+) -> BindPolicyDecision:+ """Decide whether ``host`` may be bound with the given inbound token.++ ``host`` ``None``/empty means "not configured", which uvicorn resolves to+ :data:`DEFAULT_BIND_HOST`; it is resolved the same way here so an absent+ host is never mistaken for a non-loopback one. ``proxy_token`` ``None``+ falls back to :data:`PROXY_TOKEN_ENV`, matching the security gate.+ ``environ`` is injectable for tests; production passes nothing.+ """+ env = os.environ if environ is None else environ+ resolved_host = (host or "").strip() or DEFAULT_BIND_HOST+ token = (proxy_token or env.get(PROXY_TOKEN_ENV) or "").strip()+ return BindPolicyDecision(+ host=resolved_host,+ token_configured=bool(token),+ loopback=is_loopback_host(resolved_host),+ acknowledged=_env_flag(env, OPEN_BIND_ACK_ENV),+ )+++def enforce_bind_policy(+ host: str | None,+ proxy_token: str | None,+ *,+ environ: Mapping[str, str] | None = None,+) -> BindPolicyDecision:+ """Evaluate the bind policy and refuse an unacknowledged open bind.++ Raises :class:`OpenBindRefused` when the bind must not proceed. When the+ open bind is acknowledged, emits the ``proxy_open_bind`` warning (kept from+ the pre-0.40 behaviour so log-based monitoring keeps working) and returns.+ """+ decision = evaluate_bind_policy(host, proxy_token, environ=environ)+ if decision.refused:+ logger.error("event=proxy_open_bind_refused host=%s", decision.host)+ raise OpenBindRefused(decision)+ if decision.open_bind:+ logger.warning(+ "event=proxy_open_bind host=%s — proxy is bound to a non-loopback "+ "interface with no %s set; the /v1/* data-plane routes are reachable "+ "WITHOUT authentication. This was acknowledged via %s=1; set %s to "+ "require a bearer token from non-loopback callers instead.",+ decision.host,+ PROXY_TOKEN_ENV,+ OPEN_BIND_ACK_ENV,+ PROXY_TOKEN_ENV,+ )+ return decisiondiff --git a/headroom/proxy/loopback_guard.py b/headroom/proxy/loopback_guard.pyindex d7283aaec..428ad825d 100644--- a/headroom/proxy/loopback_guard.py+++ b/headroom/proxy/loopback_guard.py@@ -76,9 +76,15 @@ LOOPBACK_HOSTS: frozenset[str] = frozenset({"127.0.0.1", "::1", "localhost"})def is_loopback_host(host: str | None) -> bool:"""Return True if ``host`` represents a loopback interface.- ``None`` is treated as loopback — this covers ``TestClient`` /- UDS-style requests where FastAPI does not populate- ``request.client``.+ ``None`` is **not** loopback. A missing peer address (a Unix-domain+ socket, an ASGI adapter that leaves ``scope["client"]`` unset, a+ hand-built request double) is no evidence that the caller is local, and+ every guard built on this helper -- the inbound token gate, the+ ``/admin`` and ``/debug`` 404 guards, the WebSocket gate -- must fail+ closed on it rather than silently disable itself. ``identity.py`` has+ always treated it that way; this makes the rest of the proxy agree.+ Tests that need a local caller set an explicit loopback peer+ (``TestClient(app, client=("127.0.0.1", 12345))``).``"localhost"`` is special-cased as a string since it is not avalid IP literal. The comparison is case-insensitive because@@ -89,7 +95,7 @@ def is_loopback_host(host: str | None) -> bool:default. Malformed input returns ``False``."""if host is None:- return True+ return Falseif host.lower() == "localhost":return Truetry:diff --git a/headroom/proxy/server.py b/headroom/proxy/server.pyindex a20400748..27e4b4164 100644--- a/headroom/proxy/server.py+++ b/headroom/proxy/server.py@@ -148,7 +148,7 @@ from headroom.proxy.helpers import (retry_after_ms,)from headroom.proxy.loop_callback_failure_policy import is_known_websocket_callback_failure-from headroom.proxy.loopback_guard import is_loopback_host+from headroom.proxy.loopback_guard import is_loopback_host, is_loopback_host_headerfrom headroom.proxy.malloc_trim import trim_periodicallyfrom headroom.proxy.memory_handler import MemoryConfig, MemoryHandler@@ -2979,13 +2979,6 @@ class WebSocketAuthMiddleware:await self.app(scope, receive, send)return- client = scope.get("client")- client_host = client[0] if client else None- if is_loopback_host(client_host):- scrub_proxy_token_headers(scope, self.token_bytes)- await self.app(scope, receive, send)- return-# Starlette's own Headers rather than a hand-built dict: on a repeated# header it returns the FIRST occurrence, which is what the HTTP gate# sees. Building a dict here instead took the LAST one, so the two@@ -2993,7 +2986,22 @@ class WebSocketAuthMiddleware:# drift the shared reader below exists to prevent.from starlette.datastructures import Headers- provided = read_proxy_token(Headers(scope=scope))+ headers = Headers(scope=scope)+ client = scope.get("client")+ client_host = client[0] if client else None+ # Loopback exemption needs both gates the HTTP admin guards apply: a+ # loopback peer *and* a loopback ``Host:`` header. The Host check is+ # the DNS-rebinding defence — a browser on this machine coerced into+ # opening a socket to 127.0.0.1 still sends ``Host: attacker.com``. A+ # missing peer address (UDS, adapters) is not loopback (fails closed).+ if is_loopback_host(client_host) and is_loopback_host_header(headers.get("host")):+ # Exempt from the token, not from the scrub: a loopback client that+ # sends the token anyway must not have it forwarded upstream.+ scrub_proxy_token_headers(scope, self.token_bytes)+ await self.app(scope, receive, send)+ return++ provided = read_proxy_token(headers)if provided is not None and hmac.compare_digest(provided.encode("utf-8", "replace"), self.token_bytes):@@ -3983,17 +3991,15 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:# orchestrators can check a container that binds non-loopback._AUTH_EXEMPT_PATHS = frozenset({"/health", "/healthz", "/livez", "/readyz"})- # Loud warning when a non-loopback bind has no token configured: that is the- # exact shape (e.g. the Docker 0.0.0.0 image) that exposes unauthenticated- # /v1/* routes to the surrounding network.- if not _proxy_token and not is_loopback_host(getattr(config, "host", None)):- logger.warning(- "event=proxy_open_bind host=%s — proxy is bound to a non-loopback "- "interface with no HEADROOM_PROXY_TOKEN set; the /v1/* data-plane "- "routes are reachable WITHOUT authentication. Set HEADROOM_PROXY_TOKEN "- "to require a bearer token from non-loopback callers.",- getattr(config, "host", None),- )+ # A non-loopback bind with no token is the exact shape (``--host 0.0.0.0``+ # from any launcher) that exposes the unauthenticated /v1/* relay to the+ # surrounding network. It used to be a warning; it is now refused unless+ # the operator acknowledges it explicitly (see bind_policy.py). Enforced+ # here, not only in run_server, so programmatic embeddings and the+ # multi-worker factory get the same guarantee.+ from headroom.proxy.bind_policy import enforce_bind_policy++ _bind_decision = enforce_bind_policy(getattr(config, "host", None), _proxy_token)def _apply_security_headers(response) -> None:# setdefault: never clobber a header an upstream/handler already set.@@ -4128,6 +4134,9 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:from headroom.proxy.debug_introspection import (collect_tasks as _collect_tasks,)+ from headroom.proxy.loopback_guard import (+ is_container_host_gateway,+ )from headroom.proxy.loopback_guard import (require_loopback as _require_loopback,)@@ -4148,6 +4157,86 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:if not _request_can_view_dashboard_metadata(request, trusted_dashboard_client_cidrs):raise HTTPException(status_code=404)+ def _authenticated_at_gate(request: Request) -> bool:+ """True when the security gate verified this request's proxy token.++ The gate exempts loopback peers without checking the ``Host`` header,+ so only a *non-loopback* request that reached a handler while a token+ is configured has proven it holds the token. A loopback peer must+ still pass the loopback (peer + Host) check: the DNS-rebinding defence.+ """+ client = getattr(request, "client", None)+ return bool(_proxy_token) and not is_loopback_host(getattr(client, "host", None))++ def _is_host_of_loopback_published_container(request: Request) -> bool:+ """True for the host's own dashboard reaching a loopback-published container.++ Docker relays a ``127.0.0.1:<port>`` publication into the container from+ the bridge gateway, so the host browser's TCP peer is that gateway, not+ 127.0.0.1. The shipped launchers acknowledge their token-less 0.0.0.0+ bind only together with that loopback publication, so under the+ acknowledgement the gateway peer can only be a process on the host.+ Matches the exact TCP peer (never a forwarded header, never another+ container on the bridge) and keeps the loopback Host check.+ """+ if not (_bind_decision.open_bind and _bind_decision.acknowledged):+ return False+ client = getattr(request, "client", None)+ peer = getattr(client, "host", None) if client is not None else None+ return is_container_host_gateway(peer) and is_loopback_host_header(+ request.headers.get("host")+ )++ def _require_operator_read_client(request: Request) -> None:+ """Gate the read-only operator routes (history, quota, subscription window).++ A token-authenticated operator on a public bind is entitled to them, as+ is the host of a loopback-published container. Everyone else falls back+ to the /settings* trust chain: loopback, or a trusted dashboard client+ behind a gateway. Settings *writes* deliberately do not get either+ short-cut.+ """+ if _authenticated_at_gate(request) or _is_host_of_loopback_published_container(request):+ return+ _require_loopback_or_trusted_dashboard_client(request)++ def _require_metrics_scrape_client(request: Request) -> None:+ """Gate ``/metrics`` for scrapers without demanding a dashboard's browser shape.++ ``/metrics`` is a Prometheus target, so unlike the dashboard routes it+ cannot require an IP-literal ``Host`` header. Allowed callers:++ * a non-loopback caller that authenticated at the security gate;+ * loopback (peer *and* Host header, the usual two gates);+ * a connecting peer inside ``HEADROOM_PROXY_TRUSTED_GATEWAY_CIDRS``+ (whatever it forwards), or a resolved client inside the+ dashboard-client CIDRs, provided any browser provenance it carries+ is same-origin (a scraper sends neither Origin nor Referer).++ Everyone else gets the same 404 the other operator routes return.+ """+ if _authenticated_at_gate(request):+ return+ if _request_is_loopback(request):+ return+ from headroom.proxy.forwarded_headers import (+ load_trusted_gateway_cidrs,+ peer_is_trusted_gateway,+ resolve_client_ip,+ )++ # Gateway CIDRs describe the TCP peer itself, never a forwarded address;+ # only the dashboard-client CIDRs apply to the resolved client.+ client = getattr(request, "client", None)+ peer = getattr(client, "host", None) if client is not None else None+ if peer_is_trusted_gateway(peer, load_trusted_gateway_cidrs()) or peer_is_trusted_gateway(+ resolve_client_ip(request), trusted_dashboard_client_cidrs+ ):+ host_header = request.headers.get("host")+ if host_header and _request_has_same_origin_or_no_provenance(request, host_header):+ return+ raise HTTPException(status_code=404)+def _require_same_origin_or_trusted_dashboard_client(request: Request) -> None:"""Same-origin CSRF guard for settings writes, trusted-dashboard aware.@@ -4327,6 +4416,15 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:name="dashboard-static",)+ # The read-only telemetry routes below carry operator data (model/project/+ # session labels, spend history, subscription utilisation, provider quota)+ # and were served to any network caller. They now answer token-authenticated+ # operators, loopback, or a trusted dashboard client behind a gateway; other+ # network callers get 404. The dashboard shell itself is a static template+ # (like its /dashboard/static assets) and stays reachable, so a container+ # published on host loopback, whose peer is the bridge gateway, still loads.+ _dashboard_gate = [Depends(_require_operator_read_client)]+@app.get("/dashboard", response_class=HTMLResponse)@app.get("/dashboard/", response_class=HTMLResponse, include_in_schema=False)async def dashboard():@@ -5292,7 +5390,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:_stats_snapshot["expires_at"] = 0.0return JSONResponse(status_code=200, content={"status": "reset"})- @app.get("/stats-history")+ @app.get("/stats-history", dependencies=_dashboard_gate)async def stats_history(format: Literal["json", "csv"] = "json",series: Literal["history", "hourly", "daily", "weekly", "monthly"] = "history",@@ -5369,7 +5467,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:return {"transformations": transformations, "log_full_messages": log_full_messages}- @app.get("/subscription-window")+ @app.get("/subscription-window", dependencies=_dashboard_gate)async def subscription_window():"""Current Anthropic subscription window utilisation and Headroom contribution.@@ -5394,14 +5492,14 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:await tracker.maybe_poll_on_demand()return JSONResponse(content=tracker.render_state())- @app.get("/quota")+ @app.get("/quota", dependencies=_dashboard_gate)async def quota():"""Unified quota/rate-limit stats for all registered providers (Anthropic, Codex, Copilot)."""return JSONResponse(content=get_quota_registry().get_all_stats())- @app.get("/metrics")+ @app.get("/metrics", dependencies=[Depends(_require_metrics_scrape_client)])async def metrics():- """Prometheus metrics endpoint."""+ """Prometheus metrics endpoint (loopback, trusted CIDR, or token-authenticated)."""return PlainTextResponse(await proxy.metrics.export(),media_type="text/plain; version=0.0.4",@@ -6233,6 +6331,16 @@ def run_server(config.profile_seeded_env_keys = frozenset(set(config.profile_seeded_env_keys) | set(seeded_env_keys))++ # Refuse an unacknowledged open bind here, before uvicorn forks, so the+ # operator gets one error and an exit code instead of N workers crashing+ # in create_app. create_app enforces the same policy for embedders.+ from headroom.proxy.bind_policy import evaluate_bind_policy++ _bind = evaluate_bind_policy(config.host, config.proxy_token)+ if _bind.refused:+ print(f"ERROR: {_bind.message()}", file=sys.stderr)+ sys.exit(2)if workers < 1:raise ValueError("workers must be >= 1")config.worker_processes = workersdiff --git a/scripts/install.ps1 b/scripts/install.ps1index 86fed772c..ccc05aaef 100644--- a/scripts/install.ps1+++ b/scripts/install.ps1@@ -159,6 +159,18 @@ function Get-PassthroughEnvArgs {return ,$args.ToArray()}+# Publish the proxy on host loopback only. The container itself must bind+# 0.0.0.0 for Docker port forwarding to reach it, and the proxy refuses a+# token-less non-loopback bind unless the operator states that the runtime+# already confines the port. This is the only place that statement is made,+# and it is always made together with the 127.0.0.1 publication it relies on.+function Get-LoopbackPublishArgs {+ param([int]$Port)+ # Leading comma: return the array as one object so AddRange receives a+ # string[] rather than an unrolled object[] (same as Get-SharedDockerArgs).+ return ,[string[]]@('-p',"127.0.0.1`:$Port`:$Port",'--env','HEADROOM_ALLOW_UNAUTHENTICATED_BIND=1')+}+function Get-SharedDockerArgs {Ensure-HostDirs$args = New-Object System.Collections.Generic.List[string]@@ -253,7 +265,8 @@ function Start-ProxyContainer {$containerName = "headroom-proxy-$Port-$PID"$dockerArgs = New-Object System.Collections.Generic.List[string]- $dockerArgs.AddRange([string[]]@('run','-d','--rm','--name',$containerName,'-p',"127.0.0.1`:$Port`:$Port"))+ $dockerArgs.AddRange([string[]]@('run','-d','--rm','--name',$containerName))+ $dockerArgs.AddRange((Get-LoopbackPublishArgs -Port $Port))$dockerArgs.AddRange((Get-SharedDockerArgs))$dockerArgs.Add($HeadroomImage)$dockerArgs.Add('--host')@@ -548,7 +561,8 @@ function Start-PersistentDockerInstall {docker rm -f $containerName | Out-Null 2>$null$dockerArgs = New-Object System.Collections.Generic.List[string]- $dockerArgs.AddRange([string[]]@('run','-d','--restart','unless-stopped','--name',$containerName,'-p',"127.0.0.1`:$Port`:$Port"))+ $dockerArgs.AddRange([string[]]@('run','-d','--restart','unless-stopped','--name',$containerName))+ $dockerArgs.AddRange((Get-LoopbackPublishArgs -Port $Port))$dockerArgs.AddRange((Get-PersistentDockerArgs))Add-DashboardGatewayEnv -ArgsList $dockerArgs$dockerArgs.AddRange([string[]]@(@@ -1739,7 +1753,7 @@ switch ($args[0]) {$dockerArgs = New-Object System.Collections.Generic.List[string]$dockerArgs.AddRange([string[]]@('run','--rm'))Add-TtyArgs -ArgsList $dockerArgs- $dockerArgs.AddRange([string[]]@('-p',"127.0.0.1`:$port`:$port"))+ $dockerArgs.AddRange((Get-LoopbackPublishArgs -Port $port))$dockerArgs.AddRange((Get-SharedDockerArgs))$dockerArgs.Add('--entrypoint')$dockerArgs.Add('headroom')diff --git a/scripts/install.sh b/scripts/install.shindex 890fd3dca..bbd10bb36 100644--- a/scripts/install.sh+++ b/scripts/install.sh@@ -104,6 +104,18 @@ append_passthrough_envs() {done}+# Publish the proxy on host loopback only. The container itself must bind+# 0.0.0.0 for Docker port forwarding to reach it, and the proxy refuses a+# token-less non-loopback bind unless the operator states that the runtime+# already confines the port. This helper is the only place that statement is+# made, and it is made together with the 127.0.0.1 publication it relies on,+# so the acknowledgement can never be added without the loopback restriction.+append_loopback_publish_args() {+ local -n _target="$1"+ local port="$2"+ _target+=(-p "127.0.0.1:${port}:${port}" --env "HEADROOM_ALLOW_UNAUTHENTICATED_BIND=1")+}+append_common_container_args() {local -n ref=$1@@ -186,7 +198,8 @@ start_proxy_container() {local container_name="headroom-proxy-${port}-$$"local args=()- args=(docker run -d --rm --name "${container_name}" -p "127.0.0.1:${port}:${port}")+ args=(docker run -d --rm --name "${container_name}")+ append_loopback_publish_args args "${port}"append_common_container_args argsargs+=("${HEADROOM_IMAGE}" --host 0.0.0.0 --port "${port}" "$@")"${args[@]}" >/dev/null@@ -491,7 +504,8 @@ start_persistent_docker_install() {docker rm -f "${container_name}" >/dev/null 2>&1 || true- args=(docker run -d --restart unless-stopped --name "${container_name}" -p "127.0.0.1:${port}:${port}")+ args=(docker run -d --restart unless-stopped --name "${container_name}")+ append_loopback_publish_args args "${port}"append_persistent_container_args argsappend_dashboard_gateway_env argsargs+=(@@ -1571,7 +1585,7 @@ EOFrun_args=(docker run --rm)append_tty_args run_argsappend_common_container_args run_args- run_args+=(-p "127.0.0.1:${port}:${port}")+ append_loopback_publish_args run_args "${port}"run_args+=(--entrypoint headroom "${HEADROOM_IMAGE}" proxy --host 0.0.0.0 --port "${port}" "${args[@]:1}")"${run_args[@]}";;diff --git a/tests/gateway/test_kong_integration.py b/tests/gateway/test_kong_integration.pyindex 64ae60c81..78c99b717 100644--- a/tests/gateway/test_kong_integration.py+++ b/tests/gateway/test_kong_integration.py@@ -98,6 +98,10 @@ class HeadroomServer:# The loopback guard on /v1/compress is decided when the app is built.os.environ["HEADROOM_COMPRESS_ALLOW_REMOTE"] = "1"+ # This harness deliberately binds 0.0.0.0 with no inbound token so the+ # Kong container can reach it; acknowledge the open bind explicitly+ # (create_app refuses it otherwise).+ os.environ["HEADROOM_ALLOW_UNAUTHENTICATED_BIND"] = "1"self.app = create_app(ProxyConfig(host="0.0.0.0",diff --git a/tests/test_cli_proxy_env.py b/tests/test_cli_proxy_env.pyindex 0c611cc05..c0d50e86d 100644--- a/tests/test_cli_proxy_env.py+++ b/tests/test_cli_proxy_env.py@@ -248,7 +248,10 @@ class TestCLIProxyEnvVars:result = runner.invoke(main,["proxy"],- env={"HEADROOM_HOST": "0.0.0.0"},+ # 0.0.0.0 with no token is refused at startup since the bind+ # policy landed (tests/test_proxy_bind_policy.py); this test is+ # about env→config plumbing, so authenticate the bind.+ env={"HEADROOM_HOST": "0.0.0.0", "HEADROOM_PROXY_TOKEN": "env-test-token"},catch_exceptions=False,)diff --git a/tests/test_docker_compose_persistence.py b/tests/test_docker_compose_persistence.pyindex 07407e9cb..f6f1e05b2 100644--- a/tests/test_docker_compose_persistence.py+++ b/tests/test_docker_compose_persistence.py@@ -77,6 +77,34 @@ def test_native_compose_keeps_host_publication_loopback_and_optional_token() ->assert proxy["command"] == ["--host", "0.0.0.0", "--port", "${HEADROOM_PORT:-8787}"]+def test_native_compose_lets_the_host_dashboard_read_its_data(monkeypatch) -> None:+ """The compose proxy must serve /stats-history to the host browser, which+ reaches the 127.0.0.1 publication as the compose network's gateway."""+ from fastapi.testclient import TestClient++ from headroom.proxy.server import ProxyConfig, create_app++ compose = yaml.safe_load(+ (ROOT / "docker" / "docker-compose.native.yml").read_text(encoding="utf-8")+ )+ proxy = compose["services"]["proxy"]+ assert proxy["ports"][0].startswith("127.0.0.1:")++ for name, value in proxy["environment"].items():+ if name != "HOME" and not name.endswith("_DIR"):+ # "${VAR:-default}" with VAR unset, as compose resolves it.+ value = value.split(":-", 1)[1].rstrip("}") if value.startswith("${") else value+ monkeypatch.setenv(name, value)+ monkeypatch.setenv("HEADROOM_CONTAINER_HOST_GATEWAY", "172.18.0.1")+ host = proxy["command"][proxy["command"].index("--host") + 1]+ app = create_app(ProxyConfig(host=host, optimize=False, cache_enabled=False))++ browser = TestClient(app, base_url="http://127.0.0.1:8787", client=("172.18.0.1", 1))+ assert browser.get("/stats-history").status_code == 200+ other_container = TestClient(app, base_url="http://127.0.0.1:8787", client=("172.18.0.5", 1))+ assert other_container.get("/stats-history").status_code == 404++def test_differential_capture_compose_keeps_proxy_internal_and_host_ports_loopback() -> None:compose = yaml.safe_load((ROOT / "docker" / "differential-network-capture" / "docker-compose.yml").read_text(diff --git a/tests/test_install/test_native_installers.py b/tests/test_install/test_native_installers.pyindex 477bced3c..80e678172 100644--- a/tests/test_install/test_native_installers.py+++ b/tests/test_install/test_native_installers.py@@ -417,6 +417,43 @@ def test_generated_wrappers_explicitly_override_image_host_for_container_access(assert "dockerArgs.Add('0.0.0.0')" in powershell_source+def test_wrappers_acknowledge_open_bind_only_with_loopback_publication() -> None:+ """Every container launch that binds 0.0.0.0 inside the container must+ publish on host loopback *and* acknowledge the token-less open bind, and+ the acknowledgement must never appear without that publication.++ The proxy refuses a token-less non-loopback bind unless+ HEADROOM_ALLOW_UNAUTHENTICATED_BIND=1 is set; the wrappers make that+ statement only through one helper that also adds ``-p 127.0.0.1:...``.+ """+ ack = "HEADROOM_ALLOW_UNAUTHENTICATED_BIND=1"+ bash_source = (REPO_ROOT / "scripts" / "install.sh").read_text(encoding="utf-8")+ powershell_source = (REPO_ROOT / "scripts" / "install.ps1").read_text(encoding="utf-8")++ # Bash: the publish flag and the acknowledgement live only in the helper.+ helper = bash_source.split("append_loopback_publish_args() {", 1)[1].split("\n}\n", 1)[0]+ assert '-p "127.0.0.1:${port}:${port}"' in helper and ack in helper+ outside = bash_source.replace(helper, "")+ assert '-p "127.0.0.1:' not in outside+ assert outside.count(ack) == 0+ # Three launch sites, three helper calls.+ assert bash_source.count("--host 0.0.0.0") == 3+ assert bash_source.count("append_loopback_publish_args ") == 3++ # PowerShell: same shape.+ ps_helper = powershell_source.split("function Get-LoopbackPublishArgs {", 1)[1].split(+ "\n}\n", 1+ )[0]+ assert "127.0.0.1`:$Port`:$Port" in ps_helper and ack in ps_helper+ # Without the unary comma PowerShell unrolls the array to object[], and+ # List[string].AddRange rejects it at runtime.+ assert "return ,[string[]]@(" in ps_helper+ ps_outside = powershell_source.replace(ps_helper, "")+ assert "'-p'," not in ps_outside.replace("Get-LoopbackPublishArgs", "")+ assert ps_outside.count(ack) == 0+ assert powershell_source.count("Get-LoopbackPublishArgs -Port") == 3++@pytest.mark.skipif(os.name == "nt" or shutil.which("bash") is None or not _bash_supports_4_3(),reason="installer requires bash >= 4.3 (macOS system bash is 3.2)",diff --git a/tests/test_install/test_runtime.py b/tests/test_install/test_runtime.pyindex 1c684506c..046b6a090 100644--- a/tests/test_install/test_runtime.py+++ b/tests/test_install/test_runtime.py@@ -100,12 +100,63 @@ def test_build_runtime_command_for_docker_includes_deployment_env(assert "HEADROOM_DEPLOYMENT_PRESET=persistent-docker" in joinedassert "127.0.0.1:8787:8787" in joinedassert "ghcr.io/headroomlabs-ai/headroom:latest" in command+ # The container binds 0.0.0.0 behind a loopback-only publication; the+ # proxy refuses that bind without a token unless acknowledged, and this+ # launcher is the canonical case for the acknowledgement.+ assert "--host 0.0.0.0" in joined+ assert "HEADROOM_ALLOW_UNAUTHENTICATED_BIND=1" in command+ assert command[command.index("HEADROOM_ALLOW_UNAUTHENTICATED_BIND=1") - 1] == "--env"# Canonical Headroom filesystem contract (issue #175) forwarded into# the container.assert "HEADROOM_WORKSPACE_DIR=/tmp/headroom-home/.headroom" in commandassert "HEADROOM_CONFIG_DIR=/tmp/headroom-home/.headroom/config" in command+def test_build_runtime_command_lets_the_host_dashboard_read_its_data(+ monkeypatch, tmp_path: Path+) -> None:+ """The container this command starts must serve /stats-history to the host+ browser, which reaches the 127.0.0.1 publication as the bridge gateway."""+ from fastapi.testclient import TestClient++ from headroom.proxy.server import ProxyConfig, create_app++ monkeypatch.setattr(Path, "home", lambda: tmp_path)+ manifest = DeploymentManifest(+ profile="default",+ preset="persistent-docker",+ runtime_kind="docker",+ supervisor_kind="none",+ scope="user",+ provider_mode="manual",+ targets=["claude"],+ port=8787,+ host="127.0.0.1",+ backend="anthropic",+ image="ghcr.io/headroomlabs-ai/headroom:latest",+ base_env={"HEADROOM_PORT": "8787"},+ proxy_args=["--host", "127.0.0.1", "--port", "8787"],+ )+ command = build_runtime_command(manifest)+ assert "127.0.0.1:8787:8787" in command++ # Recreate the container's environment (minus its filesystem paths) and+ # the container's view of its bridge gateway.+ for index, arg in enumerate(command):+ if arg == "--env" and "=" in command[index + 1]:+ name, value = command[index + 1].split("=", 1)+ if name != "HOME" and not name.endswith("_DIR"):+ monkeypatch.setenv(name, value)+ monkeypatch.setenv("HEADROOM_CONTAINER_HOST_GATEWAY", "172.17.0.1")+ host = command[command.index(manifest.image) + 2]+ app = create_app(ProxyConfig(host=host, optimize=False, cache_enabled=False))++ browser = TestClient(app, base_url="http://127.0.0.1:8787", client=("172.17.0.1", 1))+ assert browser.get("/stats-history").status_code == 200+ other_container = TestClient(app, base_url="http://127.0.0.1:8787", client=("172.17.0.5", 1))+ assert other_container.get("/stats-history").status_code == 404++def test_build_runtime_command_preserves_non_ascii_ambient_token(monkeypatch, tmp_path: Path) -> None:diff --git a/tests/test_proxy_bind_policy.py b/tests/test_proxy_bind_policy.pynew file mode 100644index 000000000..a3c70e7b1--- /dev/null+++ b/tests/test_proxy_bind_policy.py@@ -0,0 +1,257 @@+"""Bind policy: a non-loopback bind with no inbound token is refused, not warned about.++Before this change the proxy logged ``proxy_open_bind`` and started anyway,+so any launcher that set ``--host 0.0.0.0`` / ``HEADROOM_HOST=0.0.0.0`` without+``HEADROOM_PROXY_TOKEN`` served the ``/v1/*`` relay to every peer on the+network. The policy is evaluated in :mod:`headroom.proxy.bind_policy` and+enforced at three layers -- ``create_app``, ``run_server`` and the CLI -- each+of which is covered here, plus the explicit operator acknowledgement+(``HEADROOM_ALLOW_UNAUTHENTICATED_BIND=1``) that keeps the documented+"container binds 0.0.0.0, runtime publishes on 127.0.0.1" shape working.+"""++from __future__ import annotations++import logging+from unittest.mock import patch++import pytest++pytest.importorskip("fastapi")++from click.testing import CliRunner # noqa: E402++from headroom.cli.main import main # noqa: E402+from headroom.exceptions import ConfigurationError # noqa: E402+from headroom.proxy.bind_policy import ( # noqa: E402+ OPEN_BIND_ACK_ENV,+ PROXY_TOKEN_ENV,+ OpenBindRefused,+ enforce_bind_policy,+ evaluate_bind_policy,+)+from headroom.proxy.models import ProxyConfig # noqa: E402+from headroom.proxy.server import create_app, run_server # noqa: E402++[email protected](autouse=True)+def _clean_bind_env(monkeypatch: pytest.MonkeyPatch):+ """The policy reads the process env; never let the developer's shell leak in."""+ monkeypatch.delenv(PROXY_TOKEN_ENV, raising=False)+ monkeypatch.delenv(OPEN_BIND_ACK_ENV, raising=False)+++# ───────────────────────────── evaluate ────────────────────────────────────++[email protected]("host", ["0.0.0.0", "::", "192.168.1.20", "myhost.internal", "[::]"])+def test_non_loopback_bind_without_token_is_refused(host: str) -> None:+ decision = evaluate_bind_policy(host, None, environ={})+ assert decision.open_bind is True+ assert decision.refused is True+ # The message must name both remedies so the operator can act on it.+ assert PROXY_TOKEN_ENV in decision.message()+ assert OPEN_BIND_ACK_ENV in decision.message()++[email protected]("host", ["127.0.0.1", "localhost", "::1", "127.5.5.5", "::ffff:127.0.0.1"])+def test_loopback_bind_without_token_is_fine(host: str) -> None:+ decision = evaluate_bind_policy(host, None, environ={})+ assert decision.loopback is True+ assert decision.open_bind is False+ assert decision.refused is False++[email protected]("host", [None, "", " "])+def test_unset_host_means_uvicorn_default_loopback(host: str | None) -> None:+ """An absent host is uvicorn's 127.0.0.1, never 'unknown therefore public'."""+ decision = evaluate_bind_policy(host, None, environ={})+ assert decision.host == "127.0.0.1"+ assert decision.refused is False+++def test_token_makes_any_bind_acceptable() -> None:+ assert evaluate_bind_policy("0.0.0.0", "s3cr3t", environ={}).refused is False+ # Same rule the security gate uses: the env var is the fallback source.+ assert (+ evaluate_bind_policy("0.0.0.0", None, environ={PROXY_TOKEN_ENV: "s3cr3t"}).refused is False+ )+ # Whitespace-only is not a token.+ assert evaluate_bind_policy("0.0.0.0", " ", environ={}).refused is True++[email protected]("value", ["1", "true", "TRUE", "yes", "on", " On "])+def test_acknowledgement_env_allows_the_open_bind(value: str) -> None:+ decision = evaluate_bind_policy("0.0.0.0", None, environ={OPEN_BIND_ACK_ENV: value})+ assert decision.open_bind is True+ assert decision.acknowledged is True+ assert decision.refused is False++[email protected]("value", ["0", "false", "no", "", "maybe"])+def test_non_truthy_acknowledgement_still_refuses(value: str) -> None:+ assert evaluate_bind_policy("0.0.0.0", None, environ={OPEN_BIND_ACK_ENV: value}).refused+++# ───────────────────────────── enforce ─────────────────────────────────────+++def test_enforce_raises_a_configuration_error_subclass() -> None:+ with pytest.raises(OpenBindRefused) as exc_info:+ enforce_bind_policy("0.0.0.0", None, environ={})+ assert isinstance(exc_info.value, ConfigurationError)+ assert exc_info.value.decision.host == "0.0.0.0"+++def test_enforce_keeps_the_open_bind_warning_when_acknowledged() -> None:+ """Log-based monitoring keyed on ``proxy_open_bind`` must keep working."""+ records: list[logging.LogRecord] = []+ handler = logging.Handler()+ handler.emit = records.append # type: ignore[method-assign]+ log = logging.getLogger("headroom.proxy.bind_policy")+ log.addHandler(handler)+ previous = log.level+ log.setLevel(logging.DEBUG)+ try:+ decision = enforce_bind_policy("0.0.0.0", None, environ={OPEN_BIND_ACK_ENV: "1"})+ finally:+ log.removeHandler(handler)+ log.setLevel(previous)+ assert decision.acknowledged is True+ messages = [r.getMessage() for r in records]+ assert any("event=proxy_open_bind " in m for m in messages), messages+ assert not any("proxy_open_bind_refused" in m for m in messages)+++# ───────────────────────────── create_app ──────────────────────────────────+++def _config(**overrides) -> ProxyConfig:+ return ProxyConfig(+ optimize=False,+ cache_enabled=False,+ rate_limit_enabled=False,+ cost_tracking_enabled=False,+ **overrides,+ )+++def test_create_app_refuses_open_bind() -> None:+ with pytest.raises(OpenBindRefused):+ create_app(_config(host="0.0.0.0", proxy_token=None))+++def test_create_app_accepts_open_bind_with_token() -> None:+ assert create_app(_config(host="0.0.0.0", proxy_token="s3cr3t")) is not None+++def test_create_app_accepts_acknowledged_open_bind(monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setenv(OPEN_BIND_ACK_ENV, "1")+ assert create_app(_config(host="0.0.0.0", proxy_token=None)) is not None+++def test_create_app_default_loopback_bind_needs_nothing() -> None:+ assert create_app(_config()) is not None+++# ───────────────────────────── run_server ──────────────────────────────────+++def test_run_server_exits_before_uvicorn_on_open_bind(capsys: pytest.CaptureFixture[str]) -> None:+ """One clean exit code, not N workers dying in create_app."""+ called = []+ with (+ patch("headroom.proxy.server.uvicorn.run", lambda *a, **k: called.append(1)),+ pytest.raises(SystemExit) as exc_info,+ ):+ run_server(_config(host="0.0.0.0", proxy_token=None), print_banner=False)+ assert exc_info.value.code == 2+ assert called == []+ err = capsys.readouterr().err+ assert "Refusing to bind '0.0.0.0'" in err+ assert PROXY_TOKEN_ENV in err and OPEN_BIND_ACK_ENV in err+++def test_run_server_proceeds_with_token() -> None:+ called = []+ with patch("headroom.proxy.server.uvicorn.run", lambda *a, **k: called.append(k)):+ run_server(_config(host="0.0.0.0", proxy_token="s3cr3t"), print_banner=False)+ assert len(called) == 1+ assert called[0]["host"] == "0.0.0.0"+++# ───────────────────────────── CLI ─────────────────────────────────────────+++def test_cli_refuses_open_bind_with_actionable_error() -> None:+ runner = CliRunner()+ called = []+ with patch("headroom.proxy.server.run_server", lambda config, **kw: called.append(config)):+ result = runner.invoke(main, ["proxy", "--host", "0.0.0.0"])+ assert result.exit_code != 0, result.output+ assert called == []+ assert "Refusing to bind '0.0.0.0'" in result.output+ assert PROXY_TOKEN_ENV in result.output+ assert OPEN_BIND_ACK_ENV in result.output+ # A refusal is an error message, never a traceback.+ assert "Traceback" not in result.output+++def test_cli_env_host_is_refused_too() -> None:+ """``HEADROOM_HOST=0.0.0.0`` in a systemd unit is the common real-world shape."""+ runner = CliRunner()+ with patch("headroom.proxy.server.run_server", lambda config, **kw: None):+ result = runner.invoke(main, ["proxy"], env={"HEADROOM_HOST": "0.0.0.0"})+ assert result.exit_code != 0, result.output+ assert "Refusing to bind '0.0.0.0'" in result.output+++def test_cli_acknowledged_open_bind_starts_and_says_so() -> None:+ runner = CliRunner()+ captured = {}+ with patch(+ "headroom.proxy.server.run_server",+ lambda config, **kw: captured.setdefault("config", config),+ ):+ result = runner.invoke(+ main,+ ["proxy", "--host", "0.0.0.0"],+ env={OPEN_BIND_ACK_ENV: "1"},+ catch_exceptions=False,+ )+ assert result.exit_code == 0, result.output+ assert captured["config"].host == "0.0.0.0"+ assert "UNAUTHENTICATED" in result.output+ assert OPEN_BIND_ACK_ENV in result.output+++def test_cli_offline_banner_still_flags_acknowledged_open_bind() -> None:+ """Offline mode must not hide that /v1/* is unauthenticated."""+ runner = CliRunner()+ with patch("headroom.proxy.server.run_server", lambda config, **kw: None):+ result = runner.invoke(+ main,+ ["proxy", "--host", "0.0.0.0"],+ env={OPEN_BIND_ACK_ENV: "1", "HEADROOM_OFFLINE": "1"},+ catch_exceptions=False,+ )+ assert result.exit_code == 0, result.output+ assert "OFFLINE" in result.output+ assert "UNAUTHENTICATED" in result.output+++def test_cli_open_bind_with_token_starts() -> None:+ runner = CliRunner()+ captured = {}+ with patch(+ "headroom.proxy.server.run_server",+ lambda config, **kw: captured.setdefault("config", config),+ ):+ result = runner.invoke(+ main,+ ["proxy", "--host", "0.0.0.0"],+ env={PROXY_TOKEN_ENV: "s3cr3t"},+ catch_exceptions=False,+ )+ assert result.exit_code == 0, result.output+ assert "inbound token REQUIRED" in result.outputdiff --git a/tests/test_proxy_debug_endpoints.py b/tests/test_proxy_debug_endpoints.pyindex fe1fdd239..27d819a7f 100644--- a/tests/test_proxy_debug_endpoints.py+++ b/tests/test_proxy_debug_endpoints.py@@ -127,8 +127,9 @@ def app_and_rebinding_client():def test_is_loopback_host_accepts_canonical_hosts():for host in LOOPBACK_HOSTS:assert is_loopback_host(host) is True- # None (TestClient with no client info) is treated as loopback.- assert is_loopback_host(None) is True+ # None (no peer address: UDS, adapters, bare request doubles) is NOT+ # loopback — every guard built on this must fail closed, not open.+ assert is_loopback_host(None) is Falsedef test_is_loopback_host_rejects_external_hosts():diff --git a/tests/test_proxy_hardening.py b/tests/test_proxy_hardening.pyindex efe277946..212efc638 100644--- a/tests/test_proxy_hardening.py+++ b/tests/test_proxy_hardening.py@@ -44,7 +44,13 @@ def _make_app(**overrides):return create_app(config)-def test_create_app_accepts_test_net_host_without_transport_validation() -> None:+def test_create_app_accepts_test_net_host_without_transport_validation(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ # No transport-level validation of the host string — but a non-loopback+ # bind with no token is an *acknowledged* open bind, never a silent one+ # (see test_proxy_bind_policy.py for the refusal path).+ monkeypatch.setenv("HEADROOM_ALLOW_UNAUTHENTICATED_BIND", "1")app = _make_app(host="203.0.113.5", proxy_token=None)assert app is not None@@ -102,6 +108,18 @@ class TestInboundAuthToken:with TestClient(app, base_url="http://127.0.0.1", client=LOOPBACK) as c:assert c.get("/stats").status_code != 401+ def test_missing_peer_address_is_not_loopback(self):+ """No ``scope["client"]`` (UDS, adapters) must fail closed, not open.++ ``is_loopback_host(None)`` used to return True, which silently switched+ the token gate off for any transport that leaves the peer unset.+ """+ app = _make_app(proxy_token="s3cr3t-token")+ with TestClient(app, base_url="http://127.0.0.1", client=None) as c: # type: ignore[arg-type]+ assert c.get("/stats").status_code == 401+ ok = c.get("/stats", headers={"Authorization": "Bearer s3cr3t-token"})+ assert ok.status_code != 401+def test_health_endpoints_exempt_even_nonloopback(self):"""Orchestrator health probes must work without the token."""app = _make_app(proxy_token="s3cr3t-token")@@ -218,25 +236,64 @@ class TestWebSocketAuthMiddleware:assert not _closed_with_policy_violation(sent)async def test_loopback_is_exempt(self):- """Same trust boundary the HTTP gate already grants loopback."""+ """Same trust boundary the HTTP gate already grants loopback.++ Both gates the HTTP admin guards apply: loopback peer *and* loopback+ ``Host`` header (a real handshake always carries one).+ """downstream = _SpyApp()mw = WebSocketAuthMiddleware(downstream, proxy_token="s3cr3t-token")- sent = await _drive(mw, _ws_scope(client=LOOPBACK))+ sent = await _drive(mw, _ws_scope(client=LOOPBACK, headers=[("host", "127.0.0.1:8787")]))assert downstream.called is Trueassert not _closed_with_policy_violation(sent)- async def test_unknown_client_is_treated_as_loopback(self):- """Mirrors is_loopback_host(None) -> True, as the HTTP gate does."""+ async def test_loopback_peer_with_foreign_host_header_is_not_exempt(self):+ """DNS rebinding: a local browser reaching 127.0.0.1 still says Host: attacker.++ The HTTP admin routes have checked Host since the loopback guard was+ written; the WebSocket gate checked the peer only. Same rule now.+ """+ downstream = _SpyApp()+ mw = WebSocketAuthMiddleware(downstream, proxy_token="s3cr3t-token")++ sent = await _drive(+ mw, _ws_scope(client=LOOPBACK, headers=[("host", "attacker.example:8787")])+ )++ assert downstream.called is False+ assert _closed_with_policy_violation(sent)++ async def test_loopback_peer_with_foreign_host_but_valid_token_passes(self):+ """The Host check only decides the *exemption*; the token still works."""downstream = _SpyApp()mw = WebSocketAuthMiddleware(downstream, proxy_token="s3cr3t-token")- sent = await _drive(mw, _ws_scope(client=None))+ sent = await _drive(+ mw,+ _ws_scope(+ client=LOOPBACK,+ headers=[+ ("host", "attacker.example:8787"),+ ("authorization", "Bearer s3cr3t-token"),+ ],+ ),+ )assert downstream.called is Trueassert not _closed_with_policy_violation(sent)+ async def test_unknown_client_is_not_loopback(self):+ """Mirrors is_loopback_host(None) -> False: fail closed, like the HTTP gate."""+ downstream = _SpyApp()+ mw = WebSocketAuthMiddleware(downstream, proxy_token="s3cr3t-token")++ sent = await _drive(mw, _ws_scope(client=None, headers=[("host", "127.0.0.1")]))++ assert downstream.called is False+ assert _closed_with_policy_violation(sent)+async def test_repeated_header_resolves_like_the_http_gate(self):"""A duplicated Authorization must mean the same thing on both transports.@@ -573,6 +630,29 @@ class TestWebSocketScrubsProxyToken:assert downstream.headers == [(b"x-api-key", b"sk-ant")]+ @pytest.mark.parametrize("token_header", ["authorization", "x-headroom-proxy-token"])+ async def test_loopback_exempt_handshake_is_still_scrubbed(self, token_header):+ # Loopback peer *and* loopback Host takes the token exemption; the+ # exemption must not skip the scrub, or a local client that sends the+ # token anyway has it forwarded upstream.+ downstream = _HeaderSpyApp()+ mw = WebSocketAuthMiddleware(downstream, proxy_token=TOKEN)+ value = f"Bearer {TOKEN}" if token_header == "authorization" else TOKEN++ await _drive(+ mw,+ _ws_scope(+ client=LOOPBACK,+ headers=[+ ("host", "127.0.0.1:8787"),+ (token_header, value),+ ("x-api-key", "sk-ant"),+ ],+ ),+ )++ assert downstream.headers == [(b"host", b"127.0.0.1:8787"), (b"x-api-key", b"sk-ant")]+async def test_custom_header_removed_provider_bearer_kept(self):downstream = _HeaderSpyApp()mw = WebSocketAuthMiddleware(downstream, proxy_token=TOKEN)@@ -707,3 +787,37 @@ class TestOfflineSwitch:assert os.environ.get("HF_HUB_OFFLINE") == "1"assert os.environ.get("TRANSFORMERS_OFFLINE") == "1"+++# ─────────────────── missing peer address fails closed everywhere ───────────+++def test_is_loopback_host_none_is_not_loopback() -> None:+ from headroom.proxy.loopback_guard import is_loopback_host++ assert is_loopback_host(None) is False+ # Sanity: the genuine loopback literals are unaffected.+ assert is_loopback_host("127.0.0.1") is True+ assert is_loopback_host("::1") is True+ assert is_loopback_host("localhost") is True+++def test_require_loopback_404s_a_request_with_no_peer() -> None:+ """Admin/debug guards must not open up when ``request.client`` is None."""+ from fastapi import HTTPException++ from headroom.proxy.loopback_guard import require_loopback++ class _NoPeerRequest:+ client = None+ headers = {"host": "127.0.0.1:8787"}++ with pytest.raises(HTTPException) as exc_info:+ require_loopback(_NoPeerRequest()) # type: ignore[arg-type]+ assert exc_info.value.status_code == 404+++def test_debug_route_404s_for_request_with_no_peer() -> None:+ app = _make_app()+ with TestClient(app, base_url="http://127.0.0.1", client=None) as c: # type: ignore[arg-type]+ assert c.get("/debug/tasks").status_code == 404diff --git a/tests/test_proxy_loopback_gating.py b/tests/test_proxy_loopback_gating.pyindex 49381d1ef..9db086a0b 100644--- a/tests/test_proxy_loopback_gating.py+++ b/tests/test_proxy_loopback_gating.py@@ -745,3 +745,256 @@ def test_dashboard_client_cidr_does_not_expand_other_management_endpoints(assert client.get("/admin/upstream").status_code == 404assert client.get("/debug/tasks").status_code == 404assert 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"),+]++[email protected]("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++[email protected]("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++[email protected]("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++[email protected]("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++[email protected]("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,+ )+ )++[email protected]("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+++ "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.textdiff --git a/tests/test_proxy_openai_cache_stability.py b/tests/test_proxy_openai_cache_stability.pyindex 655bc2230..802960601 100644--- a/tests/test_proxy_openai_cache_stability.py+++ b/tests/test_proxy_openai_cache_stability.py@@ -1379,7 +1379,11 @@ def test_openai_chat_custom_base_flood_cannot_grow_the_provider_set(assert lifetime["rate_limited_by_source"] == {"headroom": 250, "upstream": 250}# Prometheus export: every provider series is from the fixed set.- export = client.get("/metrics").text+ # /metrics is an operator route: read it as the local operator does.+ operator = TestClient(+ client.app, base_url="http://127.0.0.1", client=("127.0.0.1", 12345)+ )+ export = operator.get("/metrics").textassert set(re.findall(r'provider="([^"]+)"', export)) <= fixed_providers | {"unknown"}assert 'headroom_requests_by_provider{provider="zai"} 10' in exportassert 'headroom_requests_by_provider{provider="custom"} 250' in exportdiff --git a/tests/test_proxy_project_savings.py b/tests/test_proxy_project_savings.pyindex 1327d871a..522e66a2c 100644--- a/tests/test_proxy_project_savings.py+++ b/tests/test_proxy_project_savings.py@@ -237,7 +237,9 @@ def test_funnel_attributes_savings_from_context_and_stats_exposes_them(tmp_path,monkeypatch.setenv("HEADROOM_SAVINGS_PATH", str(tmp_path / "savings.json"))config = ProxyConfig(cache_enabled=False, rate_limit_enabled=False, log_requests=False)- with TestClient(create_app(config)) as client:+ with TestClient(+ create_app(config), base_url="http://127.0.0.1", client=("127.0.0.1", 12345)+ ) as client:proxy = client.app.state.proxyset_current_project("ctx-project")@@ -290,7 +292,9 @@ def test_stats_payload_keeps_legacy_shape(tmp_path, monkeypatch):monkeypatch.setenv("HEADROOM_SAVINGS_PATH", str(tmp_path / "savings.json"))config = ProxyConfig(cache_enabled=False, rate_limit_enabled=False, log_requests=False)- with TestClient(create_app(config)) as client:+ with TestClient(+ create_app(config), base_url="http://127.0.0.1", client=("127.0.0.1", 12345)+ ) as client:proxy = client.app.state.proxy_emit_outcome(proxy) # unattributed: no header, no context, no field@@ -310,7 +314,9 @@ def test_metrics_record_request_works_without_project_kwarg(tmp_path, monkeypatcmonkeypatch.setenv("HEADROOM_SAVINGS_PATH", str(tmp_path / "savings.json"))config = ProxyConfig(cache_enabled=False, rate_limit_enabled=False, log_requests=False)- with TestClient(create_app(config)) as client:+ with TestClient(+ create_app(config), base_url="http://127.0.0.1", client=("127.0.0.1", 12345)+ ) as client:proxy = client.app.state.proxyasyncio.run(proxy.metrics.record_request(@@ -341,7 +347,9 @@ def test_middleware_binds_project_header_to_context(tmp_path, monkeypatch):monkeypatch.setattr(server_module, "set_current_project", _capture)- with TestClient(create_app(config)) as client:+ with TestClient(+ create_app(config), base_url="http://127.0.0.1", client=("127.0.0.1", 12345)+ ) as client:assert client.get("/health", headers={"X-Headroom-Project": " my repo "}).status_code == 200assert client.get("/health").status_code == 200# /p/<name> base-URL prefix (aider/copilot/cursor wraps): strippeddiff --git a/tests/test_proxy_savings_history.py b/tests/test_proxy_savings_history.pyindex ff8bf6298..6bc09a99a 100644--- a/tests/test_proxy_savings_history.py+++ b/tests/test_proxy_savings_history.py@@ -1223,7 +1223,9 @@ def test_stats_history_persists_across_restarts_and_stats_stays_compatible(tmp_plog_requests=False,)- with TestClient(create_app(config)) as client:+ with TestClient(+ create_app(config), base_url="http://127.0.0.1", client=("127.0.0.1", 12345)+ ) as client:_record_request(client, model="gpt-4o", tokens_saved=40)stats = client.get("/stats")@@ -1276,7 +1278,9 @@ def test_stats_history_persists_across_restarts_and_stats_stays_compatible(tmp_pstats_data["persistent_savings"]["display_session"] == history_data["display_session"])- with TestClient(create_app(config)) as client:+ with TestClient(+ create_app(config), base_url="http://127.0.0.1", client=("127.0.0.1", 12345)+ ) as client:history = client.get("/stats-history")assert history.status_code == 200assert history.json()["lifetime"]["tokens_saved"] == 40@@ -1428,7 +1432,9 @@ def test_stats_history_csv_export_is_frontend_friendly(tmp_path, monkeypatch):log_requests=False,)- with TestClient(create_app(config)) as client:+ with TestClient(+ create_app(config), base_url="http://127.0.0.1", client=("127.0.0.1", 12345)+ ) as client:_record_request(client, model="gpt-4o", tokens_saved=40)_record_request(client, model="gpt-4o", tokens_saved=10)@@ -1464,7 +1470,9 @@ def test_malformed_savings_state_is_ignored_safely(tmp_path, monkeypatch):log_requests=False,)- with TestClient(create_app(config)) as client:+ with TestClient(+ create_app(config), base_url="http://127.0.0.1", client=("127.0.0.1", 12345)+ ) as client:response = client.get("/stats-history")assert response.status_code == 200data = response.json()@@ -1482,7 +1490,9 @@ def test_dashboard_includes_history_toggle_and_endpoint(tmp_path, monkeypatch):log_requests=False,)- with TestClient(create_app(config)) as client:+ with TestClient(+ create_app(config), base_url="http://127.0.0.1", client=("127.0.0.1", 12345)+ ) as client:response = client.get("/dashboard")assert response.status_code == 200html = response.textdiff --git a/tests/test_proxy_scalability.py b/tests/test_proxy_scalability.pyindex f03528cbd..33cdbe3ca 100644--- a/tests/test_proxy_scalability.py+++ b/tests/test_proxy_scalability.py@@ -251,6 +251,10 @@ class TestWorkerConfiguration:from headroom.proxy.server import _MULTI_WORKER_CONFIG_ENV, run_servercaptured = {}+ # A non-loopback bind needs an inbound token (or an explicit+ # acknowledgement) since the bind policy landed; this test is about+ # the multi-worker plumbing, so give it the token.+ monkeypatch.setenv("HEADROOM_PROXY_TOKEN", "multi-worker-test-token")config = ProxyConfig(host="0.0.0.0",port=8787,diff --git a/wiki/docker-install.md b/wiki/docker-install.mdindex 3441a4a89..5f38075dd 100644--- a/wiki/docker-install.md+++ b/wiki/docker-install.md@@ -59,17 +59,24 @@ headroom memory listFor `proxy`, the maintained wrapper always publishes the selected host port onloopback. It passes `--host 0.0.0.0` inside the container so that the loopbackpublication can reach the container, and it has no public-publication override.-For local-only use, no token is required:+For local-only use no token is needed, but the proxy refuses to start on a+non-loopback bind without one unless you acknowledge that the runtime already+restricts who can reach the port (here: the `127.0.0.1` publication):```bashdocker run --rm -it \-p 127.0.0.1:8787:8787 \+ -e HEADROOM_ALLOW_UNAUTHENTICATED_BIND=1 \-v "$PWD:/workspace" \-w /workspace \ghcr.io/headroomlabs-ai/headroom:latest \--host 0.0.0.0 --port 8787```+The maintained wrappers (`headroom install`, the `install.sh` / `install.ps1`+native wrappers, and `docker/docker-compose.native.yml`) set that acknowledgement+themselves, and only together with the `127.0.0.1` publication it depends on.+For deliberate public access, publish on an explicit public address and set`HEADROOM_PROXY_TOKEN`: