fix(proxy)!: read HEADROOM_LICENSE and make usage reporting opt-in (#3857)

## Why

Core read its licence from `HEADROOM_LICENSE_KEY`, while every licensed
extension reads `HEADROOM_LICENSE`. Core's cloud usage reporter also
started whenever a key was present: it posts the licence to the Headroom
cloud for validation and then sends aggregate usage every 5 minutes.
Renaming the variable on its own would have switched the reporter on for
every deployment that already sets `HEADROOM_LICENSE` for its
extensions. So this PR renames the variable and makes reporting opt-in
in the same change.

## What changes

- New `headroom/license_env.py` holds the rules:
  - `HEADROOM_LICENSE` is the variable.
- `HEADROOM_LICENSE_KEY` is still read as a deprecated alias for one
release and logs `event=license_env_deprecated`.
- If both are set to different values, `HEADROOM_LICENSE` wins and
`event=license_env_conflict` is logged.
- `HEADROOM_USAGE_REPORTING=1` (also `true`, `yes`, `on`) is the only
way to turn reporting on.
- `ProxyConfig.usage_reporting` (default `False`) carries the opt-in.
Multi-worker children get it automatically.
- `HeadroomProxy` starts `UsageReporter` only when a licence is set,
`usage_reporting` is true and offline mode is off.
- The startup banner no longer prints the first 8 characters of the
licence. It shows `OSS (no licence)` or `LICENSED (usage reporting off |
ON | suppressed by HEADROOM_OFFLINE)`.
- Docs: two new rows in the proxy environment table. The comment in
`run-all-plugins.sh` is corrected.

Compression gating is unchanged: with no reporter running, the licence
is treated as OK, which is the current OSS behaviour.

## Behaviour change (breaking)

- A licence on its own no longer starts the cloud usage reporter.
Deployments that relied on it must set `HEADROOM_USAGE_REPORTING=1`.
- `HEADROOM_LICENSE` is the variable. `HEADROOM_LICENSE_KEY` still works
for one release with a deprecation warning; rename it. The alias is
removed in the next release.

## Tests

`tests/test_license_env_and_usage_reporting.py`:
- Variable rules: precedence, the alias warning, the conflict warning,
the same value under both names staying quiet, blank values treated as
unset.
- Opt-in values: which values count as on and off.
- The real app lifespan with every outbound `httpx.AsyncClient.send`
captured: a licence alone sends nothing; with the opt-in, the first
outbound call is `/v1/license/validate`; offline mode beats the opt-in.
The first test fails on `main`, and the other two cannot run there
because the opt-in does not exist.

Manual runs of `headroom proxy` with nothing set, with
`HEADROOM_LICENSE`, with only `HEADROOM_LICENSE_KEY`, and with licence
plus opt-in plus `HEADROOM_OFFLINE=1` all served `/livez`, showed the
expected banner, did not start the reporter and printed no licence text.

Not tested live: opted in and online against the real cloud. That path
is covered by the in-process test with the network captured.

## Follow-ups, not in this repo

Several licensed extensions still fall back to core's
`config.license_key`. It now carries the same `HEADROOM_LICENSE` token,
so the fallback is redundant and can be removed.

Revised 2026-10-01 after self-review: merged main to refresh CI; no code
change.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
This commit is contained in:
Tejas Chopra
2026-10-01 15:57:32 -05:00
committed by GitHub
co-authored by Claude Opus 5.5 JD Davis
parent 7287589d23
commit 746038991c
7 changed files with 246 additions and 11 deletions
+2
View File
@@ -341,6 +341,8 @@ with a privileged job.
| `HEADROOM_PROXY_TOKEN` | none | Require a bearer token (`X-Headroom-Proxy-Token`) from non-loopback callers. |
| `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. |
| `HEADROOM_USAGE_REPORTING` | `false` | Set `1` to let the proxy validate the licence and post aggregate usage counts (no content) to the Headroom cloud. Off unless set; `HEADROOM_OFFLINE` still overrides it. |
| `--stateless` / `HEADROOM_STATELESS` | `false` | Keep all state in memory; no filesystem writes (disables logs, memory, TOIN). |
| `HEADROOM_STRIP_INTERNAL_HEADERS` | `enabled` | Strip internal `x-headroom-*` headers before forwarding upstream. |
| `HEADROOM_TLS_STRICT` | strict | Set `0` to relax CA-constraint checks behind a corporate TLS-inspection proxy. |
+17 -4
View File
@@ -1304,8 +1304,13 @@ def proxy(
if is_stateless:
os.environ["HEADROOM_TOIN_BACKEND"] = "none"
# License key for managed/enterprise deployments (optional)
license_key = os.environ.get("HEADROOM_LICENSE_KEY")
# Licence token (HEADROOM_LICENSE; HEADROOM_LICENSE_KEY is a deprecated
# alias). Having one set never enables outbound usage reporting: that
# needs the explicit HEADROOM_USAGE_REPORTING=1 opt-in.
from headroom.license_env import resolve_license_token, usage_reporting_enabled
license_key = resolve_license_token()
usage_reporting = usage_reporting_enabled()
# Qdrant connection for the qdrant-neo4j backend. CLI flags default
# to None; when omitted we let ProxyConfig's default_factory resolve
@@ -1478,6 +1483,7 @@ def proxy(
anyllm_provider=effective_anyllm_provider,
# License / Usage Reporting (managed/enterprise)
license_key=license_key,
usage_reporting=usage_reporting,
# Stateless mode: disable all filesystem writes
stateless=is_stateless,
# Unit 4: bounded pre-upstream concurrency on the Anthropic HTTP
@@ -1503,9 +1509,16 @@ def proxy(
if config.memory_enabled:
memory_status = "ENABLED (multi-provider)"
license_status = "OSS (no license key)"
license_status = "OSS (no licence)"
if license_key:
license_status = f"MANAGED (key={license_key[:8]}...)"
# Never print licence material, not even a prefix.
if not usage_reporting:
reporting = "off"
elif config.offline:
reporting = "suppressed by HEADROOM_OFFLINE"
else:
reporting = "ON"
license_status = f"LICENSED (usage reporting {reporting})"
provider_api_targets = resolve_api_targets(config.provider_api_overrides)
anthropic_url = provider_api_targets.anthropic
+73
View File
@@ -0,0 +1,73 @@
"""One licence variable, and an explicit switch for usage reporting.
Headroom reads its licence token from ``HEADROOM_LICENSE``. Every licensed
extension reads the same variable, so core does too.
``HEADROOM_LICENSE_KEY`` was the older name read only by core's cloud usage
reporter. It is still honoured for one release as a deprecated alias, with a
warning, so existing managed deployments keep their licence while they rename.
Having a licence set never turns on outbound reporting by itself. The usage
reporter validates the licence against the Headroom cloud and posts aggregate
usage counts; it runs only when the operator also sets
``HEADROOM_USAGE_REPORTING=1``. ``HEADROOM_OFFLINE`` still suppresses it.
"""
from __future__ import annotations
import logging
import os
from collections.abc import Mapping
logger = logging.getLogger("headroom.license_env")
LICENSE_ENV = "HEADROOM_LICENSE"
DEPRECATED_LICENSE_ENV = "HEADROOM_LICENSE_KEY"
USAGE_REPORTING_ENV = "HEADROOM_USAGE_REPORTING"
_TRUE = frozenset({"1", "true", "yes", "on"})
def _clean(value: str | None) -> str | None:
if value is None:
return None
value = value.strip()
return value or None
def resolve_license_token(environ: Mapping[str, str] | None = None) -> str | None:
"""Return the licence token, preferring ``HEADROOM_LICENSE``.
Falls back to the deprecated ``HEADROOM_LICENSE_KEY`` with a warning. When
both are set to different values, ``HEADROOM_LICENSE`` wins and a warning
says so, because silently picking one would hide a misconfiguration.
"""
env = os.environ if environ is None else environ
current = _clean(env.get(LICENSE_ENV))
legacy = _clean(env.get(DEPRECATED_LICENSE_ENV))
if current and legacy and current != legacy:
logger.warning(
"event=license_env_conflict using=%s ignored=%s hint=unset_%s_it_is_deprecated",
LICENSE_ENV,
DEPRECATED_LICENSE_ENV,
DEPRECATED_LICENSE_ENV,
)
return current
if current:
return current
if legacy:
logger.warning(
"event=license_env_deprecated variable=%s replacement=%s "
"hint=rename_it_the_alias_is_removed_in_the_next_release",
DEPRECATED_LICENSE_ENV,
LICENSE_ENV,
)
return legacy
return None
def usage_reporting_enabled(environ: Mapping[str, str] | None = None) -> bool:
"""True only when the operator explicitly opted in to usage reporting."""
env = os.environ if environ is None else environ
return (env.get(USAGE_REPORTING_ENV) or "").strip().lower() in _TRUE
+4 -1
View File
@@ -466,8 +466,11 @@ class ProxyConfig:
memory_bridge_auto_import: bool = False
memory_bridge_export_path: str = ""
# License / Usage Reporting
# Licence / usage reporting. ``license_key`` holds the HEADROOM_LICENSE
# token. The cloud usage reporter runs only when ``usage_reporting`` is
# also true (HEADROOM_USAGE_REPORTING=1); a licence alone sends nothing.
license_key: str | None = None
usage_reporting: bool = False
license_cloud_url: str = "https://app.headroomlabs.ai"
license_report_interval: int = 300
+5 -3
View File
@@ -1425,11 +1425,13 @@ class HeadroomProxy(
"hint=bridge_syncs_only_the_legacy_DB_today_per-project_bridge_follow-up_planned"
)
# Usage Reporter (license validation + phone-home for managed/enterprise).
# Usage Reporter (licence validation + phone-home for managed deployments).
# Explicit opt-in only: a licence being present must not start outbound
# reporting on its own (HEADROOM_USAGE_REPORTING=1 is required).
# Suppressed entirely in offline mode — the air-gap switch must stop all
# egress, including license phone-home, even when a key is configured.
# egress, including licence phone-home, even when opted in.
self.usage_reporter: UsageReporter | None = None
if config.license_key and not (config.offline or is_offline()):
if config.license_key and config.usage_reporting and not (config.offline or is_offline()):
from headroom.telemetry.reporter import UsageReporter
self.usage_reporter = UsageReporter(
+3 -3
View File
@@ -69,9 +69,9 @@ set -a; # shellcheck disable=SC1090
source "$ENV_TXT"; set +a
# ── 4. plugin license (Ed25519, offline, wildcard) ────────────────────────────
# HEADROOM_LICENSE + HEADROOM_LICENSE_PUBKEY. This is SEPARATE from the OSS cloud
# key (HEADROOM_LICENSE_KEY) — the banner will still say "OSS (no license key)",
# but each plugin prints "license accepted". Fallback: skip verification entirely.
# HEADROOM_LICENSE + HEADROOM_LICENSE_PUBKEY. Core and every plugin read the same
# HEADROOM_LICENSE; the banner says "LICENSED (usage reporting off)" unless
# HEADROOM_USAGE_REPORTING=1 is also set. Fallback: skip verification entirely.
if [ -f "$PLUGINS_ENV" ]; then
set -a; # shellcheck disable=SC1090
source "$PLUGINS_ENV"; set +a
@@ -0,0 +1,142 @@
"""D-12: one licence variable, and usage reporting only on explicit opt-in.
Before this change core read ``HEADROOM_LICENSE_KEY`` while every extension
read ``HEADROOM_LICENSE``, and the cloud usage reporter started whenever a key
was present. Unifying the variable without the opt-in would have switched the
reporter on in every licensed enterprise deployment. These tests pin both
halves: the variable is ``HEADROOM_LICENSE`` (old name is a warned alias), and
nothing is sent to the Headroom cloud unless ``HEADROOM_USAGE_REPORTING=1``.
"""
from __future__ import annotations
import logging
import httpx
import pytest
pytest.importorskip("fastapi")
from fastapi.testclient import TestClient # noqa: E402
from headroom.license_env import ( # noqa: E402
resolve_license_token,
usage_reporting_enabled,
)
from headroom.proxy.models import ProxyConfig # noqa: E402
from headroom.proxy.server import create_app # noqa: E402
CLOUD = "https://cloud.headroom.test"
class _Capture(logging.Handler):
def __init__(self) -> None:
super().__init__(level=logging.DEBUG)
self.messages: list[str] = []
def emit(self, record: logging.LogRecord) -> None:
self.messages.append(record.getMessage())
@pytest.fixture
def license_log():
# Attach directly: headroom.* loggers are not reliably visible to caplog.
logger = logging.getLogger("headroom.license_env")
handler = _Capture()
logger.addHandler(handler)
try:
yield handler
finally:
logger.removeHandler(handler)
# --- variable resolution -------------------------------------------------
def test_headroom_license_is_the_variable(license_log):
assert resolve_license_token({"HEADROOM_LICENSE": "tok-new"}) == "tok-new"
assert license_log.messages == []
def test_legacy_name_is_an_alias_with_a_warning(license_log):
assert resolve_license_token({"HEADROOM_LICENSE_KEY": "tok-old"}) == "tok-old"
assert any("license_env_deprecated" in m for m in license_log.messages)
def test_new_name_wins_on_conflict_and_says_so(license_log):
env = {"HEADROOM_LICENSE": "tok-new", "HEADROOM_LICENSE_KEY": "tok-old"}
assert resolve_license_token(env) == "tok-new"
assert any("license_env_conflict" in m for m in license_log.messages)
def test_same_value_under_both_names_is_quiet(license_log):
env = {"HEADROOM_LICENSE": "tok", "HEADROOM_LICENSE_KEY": "tok"}
assert resolve_license_token(env) == "tok"
assert license_log.messages == []
def test_blank_values_mean_unset():
assert resolve_license_token({"HEADROOM_LICENSE": " ", "HEADROOM_LICENSE_KEY": ""}) is None
@pytest.mark.parametrize("value", ["1", "true", "YES", " on "])
def test_usage_reporting_opt_in_values(value):
assert usage_reporting_enabled({"HEADROOM_USAGE_REPORTING": value}) is True
@pytest.mark.parametrize("value", [None, "", "0", "false", "no", "off", "maybe"])
def test_usage_reporting_is_off_unless_opted_in(value):
env = {} if value is None else {"HEADROOM_USAGE_REPORTING": value}
assert usage_reporting_enabled(env) is False
# --- outbound traffic ----------------------------------------------------
@pytest.fixture
def cloud_calls(monkeypatch):
"""Record every request any httpx.AsyncClient sends to the fake cloud."""
calls: list[httpx.Request] = []
real_send = httpx.AsyncClient.send
async def send(self, request, *args, **kwargs):
if str(request.url).startswith(CLOUD):
calls.append(request)
return httpx.Response(200, json={"status": "active"}, request=request)
return await real_send(self, request, *args, **kwargs)
monkeypatch.setattr(httpx.AsyncClient, "send", send)
monkeypatch.delenv("HEADROOM_OFFLINE", raising=False)
return calls
def _config(**overrides) -> ProxyConfig:
return ProxyConfig(
license_key="tok-licensed",
license_cloud_url=CLOUD,
license_report_interval=3600,
optimize=False,
**overrides,
)
def test_licence_alone_sends_nothing(cloud_calls):
app = create_app(_config())
with TestClient(app) as client:
client.get("/livez")
assert cloud_calls == []
def test_opt_in_reports_to_the_cloud(cloud_calls):
app = create_app(_config(usage_reporting=True))
with TestClient(app) as client:
client.get("/livez")
assert [c.url.path for c in cloud_calls][:1] == ["/v1/license/validate"]
def test_offline_beats_opt_in(cloud_calls, monkeypatch):
monkeypatch.setenv("HEADROOM_OFFLINE", "1")
app = create_app(_config(usage_reporting=True))
with TestClient(app) as client:
client.get("/livez")
assert cloud_calls == []