Commit Graph
11 Commits
Author SHA1 Message Date
9b2dec56f9 feat(proxy): show per-request /stats metadata to token-authenticated callers (#4168)
## Description

`/stats` and `/stats-lifetime` withhold the per-request tail
(`recent_requests`, `request_logs`) and project names from every
non-loopback caller, unless the request's `Host` is an IP literal
**and** the peer is inside
`HEADROOM_PROXY_TRUSTED_DASHBOARD_CLIENT_CIDRS`.

That rule cannot be met by a common deployment: the proxy runs on a
container platform with `HEADROOM_PROXY_TOKEN` set, and the dashboard
sits on its own host behind an authenticating reverse proxy (here Entra
ID sign-in in front of a small Caddy that adds `x-headroom-proxy-token`
after the user signed in). That reverse proxy reaches Headroom with a
domain `Host` (the platform routes internal calls by Host, so it cannot
be an IP) and from a peer address that is not stable enough to list. The
dashboard loads, the aggregate counters work, and the "Recent Requests"
table stays empty with no indication why.

This PR also admits callers whose proxy token the security gate has
already verified (`request.state.proxy_authenticated`, which the gate
sets only after the constant-time token comparison).

**This is a nice-to-have, not a bug fix.** The current behaviour is
documented and deliberate, and the existing trusted-CIDR path keeps
working unchanged. If you would rather not widen who sees this metadata,
closing the PR is fine; we carry the change on our fork either way.

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [x] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- `headroom/proxy/server.py`: add `_request_can_view_stats_metadata`:
true when the gate verified the proxy token, otherwise the existing
`_request_can_view_dashboard_metadata` result. `/stats` and
`/stats-lifetime` use it. The helper is deliberately not used by
`/settings*` or `/transformations/feed`, which keep their loopback /
trusted-client guards.
- `tests/test_proxy_stats_recent_requests.py`: add a regression test
(domain `Host`, non-loopback peer, token sent) for `/stats` and
`/stats?cached=1`, asserting the tail is served with the token and that
the gate still answers 401 without it or with a wrong one.
- `docs/content/docs/security-model.mdx`: new section **What the proxy
token unlocks**. It lists exactly which fields a token holder now also
sees: `recent_requests`, `request_logs` and `config` on `/stats` (and
`?cached=1`), and `projects` and `persistence.error` on
`/stats-lifetime`. It says the settings routes and the
`require_loopback` routes stay closed to a token. It also warns that the
token is one shared secret, not a per-caller identity: every holder sees
every caller's request metadata, so a deployment that hands one token to
several clients that must not see each other's metadata should run one
proxy per client. The dashboard-CIDR table row now points to the
section.
- `docs/content/docs/proxy.mdx` (the `HEADROOM_PROXY_TOKEN` row) and
`SECURITY.md` (the local-control-surfaces bullet): one line each
pointing to the same consequence.
- `headroom/proxy/server.py` docstrings: the `/stats` handler and
`_request_can_view_stats_metadata` now describe the actual access rule.
The helper no longer claims the change widens nothing.

Who gains access: holders of `HEADROOM_PROXY_TOKEN`. This does widen
what the token grants. Before, it granted inference and the read-only
operator routes. Now it also grants the request metadata of every caller
on the proxy. With no token configured, nothing changes (the flag is
never set).

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom/proxy/server.py`)
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

At `1c6666d` merged with current `main` (`4abbf07`):

```text
$ python -m pytest -q tests/test_proxy_stats_recent_requests.py tests/test_proxy_loopback_gating.py \
    tests/test_dashboard_accessibility.py tests/test_proxy_hardening.py
214 passed, 1 skipped in 44.60s

$ python -m mypy headroom/proxy/server.py
Success: no issues found in 1 source file

$ ruff check headroom/proxy/server.py tests/test_proxy_stats_recent_requests.py
All checks passed!
$ ruff format --check headroom/proxy/server.py tests/test_proxy_stats_recent_requests.py
2 files already formatted
```

## Real Behavior Proof

- Environment: Windows 11, Python 3.13, this branch at `4abbf07`
(`1c6666d` merged with current `main`). A real `headroom proxy` with a
throwaway `HEADROOM_PROXY_TOKEN`, bound to a non-loopback LAN address,
with `HEADROOM_OFFLINE=1` and `--anthropic-api-url` pointed at a local
stub that answers `/v1/messages` with a fixed Anthropic message:
  ```text
headroom proxy --host 192.168.0.48 --port 18788 --no-optimize
--anthropic-api-url http://127.0.0.1:18999
  ```
- Exact command / steps: a client on `192.168.0.48` (not loopback, in no
trusted CIDR) sends what the dashboard's reverse proxy sends. That is
`Host: headroom-dashboard.example.test` (a domain, as the platform
routes by Host) plus `x-headroom-proxy-token`. It first makes one
token-authenticated `POST /v1/messages` so there is a request to list,
then reads the stats endpoints with the token, without it, and with a
wrong one. It also tries the settings and loopback-only routes with the
token. Same script against the same build with only
`headroom/proxy/server.py` swapped back to `main`'s, for the before
column.
- Observed result: verified token holders receive shared stats metadata,
while missing or incorrect tokens are rejected; exact before/after
responses follow.

  ```text
request (domain Host, non-loopback peer) before (main) after (this PR)
POST /v1/messages token 200 200
GET /stats token 200, recent_requests/request_logs/ 200,
recent_requests=1 request_logs=1
config absent config present, first={"provider":
"anthropic","model":"claude-sonnet-5-5"}
GET /stats?cached=1 token 200, same fields absent 200, same as /stats
GET /stats-lifetime token 200, projects absent 200, projects present
GET /stats no token 401 401
GET /stats wrong token 401 401
GET /stats-lifetime no token 401 401
GET /settings token 404
GET /settings/schema token 404
GET /dashboard/settings token 404
GET /transformations/feed token 404
  ```

The proxy log shows `event=proxy_auth_rejected path=/stats …
reason=missing_token`, `… reason=bad_token` and `path=/stats-lifetime …
reason=missing_token` for the three rejections.
- Not tested: the full suite (only the four files above). The deployed
dashboard end to end: the run above reproduces its request shape against
a real proxy, without the Entra/Caddy hop in front.

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: n/a
- Stable/default behavior changed: only when `HEADROOM_PROXY_TOKEN` is
set. Token-authenticated remote callers now receive `recent_requests`,
`request_logs` and `config` from `/stats`, and `projects` and
`persistence.error` from `/stats-lifetime`, for every caller of the
proxy. Loopback and trusted-CIDR behaviour is unchanged, and the
settings and loopback-only routes are not opened to the token.
- Kill switch / disable path: unset the token (then nothing changes), or
revert the commit
- Unsafe override required: no
- Qualification impact: none
- Rollback path: revert the commit

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Additional Notes

- Documentation: done; see the security-model section above.
- A possible alternative that avoids widening the rule: an opt-in env
var (e.g. `HEADROOM_STATS_METADATA_FOR_TOKEN=1`). Happy to switch to
that if you prefer the default to stay strict.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

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

https://claude.ai/code/session_013MpfLG8sVzqPhD34teqdLD

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4168"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

### Maintainer current-main requalification

Exact head `09689b73ddeb8879a2f2c68726f9e885cd9bfdee`, upstream main
`e4a60ed72f6ef5b28569f8bfbe2163cfda32c948`.

Mechanically merged upstream/main e4a60ed7 and re-reviewed
stats-metadata authorization plus the existing security/runtime
discussion. Only callers whose proxy token authentication succeeded gain
the additional per-request stats metadata; settings and loopback-only
routes retain their separate guards. Documentation explicitly states
that token holders share every caller's traffic metadata. No contributor
production logic was rewritten.

All 260 focused stats/recent-request, loopback-gating and hardening
tests pass; Ruff lint/format and whitespace checks pass. Existing
before/after real HTTP evidence remains explicitly scoped; local tests
use the existing native extension, not a fresh native build. Applied the
shared test-only Gemini streamed-request fixture repair for
independently established main failures; all ten cases pass. Formal
approval awaits exact-head hosted qualification.


Exact-head hosted checks are being handled by maintainers. No new
finding in the reviewed scope; formal approval awaits exact-head hosted
qualification; nothing merged.


### Maintainer current-main requalification

Exact head `fa07187e666ca7895d1cc5708a9d930f38399fe1`, upstream main
`c01cf07d943d816cfd9d97e6838ed4e38f1ff9a4`.

Clean mechanical merge with upstream main
c01cf07d94. Reviewed current author
discussion and Devin runtime/documentation findings. Additional stats
metadata is allowed only after successful proxy-token authentication or
the existing dashboard authorization; settings and loopback-only routes
retain separate guards. The security documentation explicitly states
that one shared token exposes every caller's traffic metadata to every
holder. No contributor authorization policy rewritten.

Fresh focused stats/recent-request, loopback-gating and hardening
verification: 260 tests passed with six existing deprecation/OpenAPI
warnings. Changed-file Ruff lint/format and main-relative whitespace
checks pass; owned tree clean. Existing non-loopback before/after HTTP
evidence remains scoped; no fresh live replay or branch-native build is
claimed. Python tests use the current-main native DLL. No new source
blocker found; approval awaits exact-head hosted checks. Nothing merged.


Exact-head hosted checks are being handled by maintainers. No new
finding in the reviewed scope; formal approval awaits exact-head hosted
qualification; nothing merged.


### Maintainer current-main requalification

Exact head `20b62cc35f7a005b91a6c9054c41cfd51ac29c37`, upstream main
`0ddaa56c21cdc01c4774391fdcc69e987ecc4e5c`.

Clean main integration against 0ddaa56c21.
315 stats/recent-request, loopback/security gating and incoming-main
tests passed, 11 optional skips, 6 warnings. Exact incoming-main
patches, lint/format, offline lock and whitespace checks pass. Complete
recorded native input-set/hash and artifact checksum verified before
existing DLL reuse; no fresh native build claimed.

Current author discussion and both resolved Devin threads/replies
reviewed. Verified token-authenticated state expands only stats metadata
authorization; settings and require_loopback guards remain separate.
Documentation explicitly lists fields and warns that the shared token
exposes every caller's request metadata to every holder, with separate
proxies required for isolation. This is an intentional documented
shared-trust policy, not a per-user identity. Prior author's
non-loopback real-proxy before/after evidence is retained with its
scope; this refresh adds local tests, not a fresh live replay or
browser/reverse-proxy proof. No new source blocker found.

Source/test/prose delta has no
workflow/setup/dependency/CLI/install/provider/OpenClaw/SDK path
changes. Inherited flagged workflow-validation and Init/Wrap bootstrap
paths are excluded. Docs build uses unchanged-main
workflow/package/lock/config and this PR changes only prose there.
Exact-head Actions and rollup remain pending before approval. Nothing
merged.


Exact-head hosted checks are being handled by maintainers. No new
finding in the reviewed scope; formal approval awaits exact-head hosted
qualification; nothing merged.

---------

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-11-07 20:42:27 -06:00
HetCreepandJerrettDavis ee975d49c0 docs(security): sync security model with egress pollers, counts and beacon payload (#4539)
## Description

Documentation only. Brings `security-model.mdx`, `SECURITY.md`,
`architecture.mdx` and the `telemetry/session.py` docstrings back in
line with the code on main. Every item below was re-checked against
upstream main `a2d4fe72`; line numbers are that commit's.

Fixed:

1. Egress table: added `api.anthropic.com`
(`headroom/subscription/client.py:30` `_USAGE_URL`; default on,
`proxy/models.py:488-489`, 300 s; only polls when
`read_cached_oauth_token()` finds a token, `client.py:52-81`; switch
`HEADROOM_NO_SUBSCRIPTION_TRACKING`, `cli/proxy.py:568`; `guard_egress`
at `client.py:113` so `HEADROOM_OFFLINE` blocks it).
2. Egress table: added `api.github.com` Copilot quota poll
(`subscription/copilot_quota.py:6-14` token list, `:218-222` default 60
s, `:318` `guard_egress`; registered unconditionally at
`proxy/server.py:2359`). I found no dedicated disable switch, so the row
says so and names the two ways to stop it (unset the token variables, or
`HEADROOM_OFFLINE`).
3. "seven runtime knobs" is now "ten". `RUNTIME_ENV_KNOBS`
(`proxy/runtime_env.py:60`) has 10 `Knob(` entries, counted with `ast`.
The table on the same page already lists ten rows. (The issue said
eight; that was stale.)
4. "59" is now "63" in three places. `SETTINGS` (`settings_store.py:64`)
has 63 `SettingField(` entries, counted with `ast`.
5. Request log row: "Inherits umask" is now "`0600`, owner-only".
`proxy/request_logger.py:163` opens the file with
`fileperms.open_owner_only`.
6. Beacon payload: `security-model.mdx` and `SECURITY.md` now mention
the schema v2 sections and the 15-variable `config` allow-list
(`telemetry/session.py:134` `SCHEMA_VERSION = 2`; snapshot keys at
`:823-1175`; `_CONFIG_ENV_KEYS` at `:359-373`).
7. `architecture.mdx` TOIN sentence: it said nothing is "sent off the
box", but `toin.py:683` calls `record_tool_shape` before TOIN's own
enabled check, and with the beacon on (default, `beacon.py:59`) a
bucketed structural descriptor goes into `shapes.by_tool`
(`session.py:1051-1070`, `:2031-2100`). The sentence now says so and
links the beacon section.
8. `telemetry/session.py` docstrings (module docstring and the entry
points at `record_compression`, `record_content_shape`,
`record_outcome`) said the beacon is off unless `HEADROOM_TELEMETRY` is
on. `beacon.py:1-12` and `is_beacon_enabled()` say on by default.
Comment text only.

Also changed: one sentence in the beacon section that called the beacon
"the one egress path that is enabled without any action from you". The
two pollers are also on by default (token-gated), so it now says
"enabled by default whatever credentials you have".

Dropped: nothing. All seven items from the issue and its comment still
held on main. Item 3's number was corrected from eight to ten.

Not covered, noticed while reading: `docs/content/docs/proxy.mdx:33`
still describes the older, smaller beacon payload and "about 2KB";
`headroom/subscription/codex_rate_limits.py:454` is a third poller
(Codex rate limits) that is not in the egress table. I left both for a
separate change.

Refs #4422

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- `docs/content/docs/security-model.mdx`: two egress rows, three counts,
request-log permissions, beacon v2 payload bullet, one wording fix.
- `SECURITY.md`: beacon payload sentence.
- `docs/content/docs/architecture.mdx`: TOIN sentence.
- `headroom/telemetry/session.py`: docstring text only, no code change.

## Testing

- [ ] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`)
- [ ] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
$ ruff check headroom/telemetry/session.py
All checks passed!
$ ruff format --check headroom/telemetry/session.py
1 file already formatted
$ PYTHONPATH=<worktree> python -c "import headroom.telemetry.session"
import ok (SCHEMA_VERSION 2)
$ pytest -q tests/test_packaging_extras_and_security_docs.py
6 passed in 2.54s
```

Ruff was run on the one changed Python file, not the whole tree. mypy
and the full test suite were not run (docstring-only change).

## Real Behavior Proof

- Environment: WSL Ubuntu, Python venv, worktree of upstream main
a2d4fe72 plus this one commit.
- Exact command / steps: counted `Knob(` in `RUNTIME_ENV_KNOBS` and
`SettingField(` in `SETTINGS` with Python `ast`; read each cited code
path; ran `ruff check`, `ruff format --check`, the module import and
`tests/test_packaging_extras_and_security_docs.py`.
- Observed result: 10 knobs, 63 settings fields; ruff clean; module
imports; 6 tests passed.
- Not tested: the pollers were not run against the live Anthropic or
GitHub APIs, the docs site was not built, and the mdx table rendering
was not previewed.

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: n/a
- Stable/default behavior changed: no, documentation and docstring text
only
- Kill switch / disable path: n/a
- Unsafe override required: no
- Qualification impact: none
- Rollback path: revert the commit

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [ ] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Screenshots (if applicable)

n/a

## Additional Notes

Unticked checklist items are n/a for a documentation change. The counts
in the docs are still hand-maintained; a check that derives them from
`RUNTIME_ENV_KNOBS` and `SETTINGS` (option 2 in the issue, related to
#3181) would stop this drifting again, but that is a separate change.

Produced with AI assistance (Claude Code) operated by me (HetCreep);
every count and line above was checked against a clone of upstream main
a2d4fe72.

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

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4539"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

---------

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-11-04 22:56:20 -06:00
09b7e8c1e4 fix(packaging): rename the sandbox extra to lean and correct SECURITY.md claims (#3727)
**Revised 2026-10-05 after review:** tests now patch the deployment root
directly (never HOME) and assert POSIX modes only where enforced, the
supported-versions test follows the latest-release policy, and runner
scripts are recreated rather than truncated so a key is never written at
an old 0755 mode.

## Description

Security-remediation item A-10 (P-21, P-22). Renames the misleading
`sandbox` extra to `lean` (keeping `sandbox` as a deprecated alias for
one release, so `pip install "headroom-ai[sandbox]"` keeps working; not
a breaking change), corrects SECURITY.md's credential claims, and makes
the `headroom install --env` credential-persistence path owner-only and
documented. Details below.

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [x] Documentation update

## Changes Made

- `pyproject.toml`: `sandbox` extra renamed to `lean`; `sandbox =
["headroom-ai[lean]"]` deprecated alias; `uv.lock` regenerated (`uv lock
--check` clean).
- CI `python-314-wheels`, `run-all-plugins.sh` and the installation
guide now use `[lean]`.
- SECURITY.md: latest-release support policy (from main); discloses the
Copilot OAuth token and the `install --env` persistence path with its
modes.
- `headroom/install/paths.py`: `chmod_owner_only` verifies and reports
the mode it set.
- `headroom/install/state.py`: profile dir 0700 / manifest 0600 on every
save; warns if the directory cannot be narrowed.
- `headroom/install/supervisors.py`: runner scripts 0700 (`.ps1` 0600),
created fresh (old file removed first, so `O_TRUNC` cannot keep a 0755
mode while secrets are written), fail closed on POSIX if the mode cannot
be set.
- Tests: deployment writes are routed through a monkeypatched deploy
root; POSIX-mode assertions are skipped where modes are not enforced
(Windows).

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
$ LITELLM_LOCAL_MODEL_COST_MAP=True uv run --frozen --extra dev --extra proxy pytest -q \
    tests/test_packaging_extras_and_security_docs.py tests/test_install/ tests/test_optional_dependencies.py
209 passed, 7 skipped
$ ruff check / ruff format --check (touched files)   -> clean
$ uv lock --check                                    -> Resolved 251 packages
```

Fail-before (2026-10-05 revision):

```text
test_rewriting_an_old_script_never_writes_secrets_at_its_old_mode   (fix reverted) FAILED assert 493 == 448 (0755 != 0700)
test_security_policy_supports_the_latest_release_without_a_version_number
                                                     (pinned 0.39.x table restored) FAILED
test_unrestrictable_profile_dir_warns_and_still_saves with Path.home() forced to ignore $HOME (as on Windows):
  previous version wrote <fake-home>/.headroom/deploy/default/manifest.json; new version writes nothing outside tmp_path
```

## Real Behavior Proof

- Environment: macOS (Darwin 25.6), CPython 3.14 via `uv run --frozen`,
branch head after merging main.
- Exact command / steps: with `HEADROOM_WORKSPACE_DIR` pointed at a temp
dir containing a pre-existing 0755 `deploy/default/` and 0755
`run-headroom.sh` (simulating a profile from an earlier version), ran
the real `build_manifest(..., extra_env={"ANTHROPIC_API_KEY": ...})` ->
`save_manifest` -> `render_runner_scripts`, then `stat` on every file.
- Observed result: `default/` 0700, `manifest.json` 0600,
`run-headroom.sh` 0700, `ensure-headroom.sh` 0700. `uv.lock` records
`headroom-ai[lean]` under marker `extra == 'sandbox'`, so the alias
resolves.
- Not tested: Windows end-to-end (ACL behaviour; mode assertions are
skipped there by design), a real `pip install "headroom-ai[sandbox]"`
from a published wheel, supervisor registration (launchd/systemd).

## Runtime Rollout Safety

- Rollout-managed feature(s): none.
- Minimum rollout channel: n/a (install-time file modes and packaging
metadata).
- Stable/default behavior changed: yes - deployment profile dirs and
runner scripts are owner-only after the next `headroom install apply`
(see release note below). `[sandbox]` keeps installing the same
dependencies.
- Kill switch / disable path: none; re-running an older version restores
old modes.
- Unsafe override required: no.
- Qualification impact: none.
- Rollback path: revert the PR; existing files keep their narrowed
modes, which is harmless.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Additional Notes

History of the change and the earlier review rounds follows.

---

Security-remediation item **A-10** (P-21, P-22). Two documentation
defects, each of which leads a reader to a false premise about the
product.

## 1. The `sandbox` extra promises isolation it does not provide

`headroom-ai[sandbox]` is a **dependency profile** — a torch-free subset
of `[all]`. It provides no isolation, no confinement and no privilege
reduction of any kind. The name invites exactly the wrong assumption,
and "we run it in the sandbox extra" is the kind of sentence that ends
up in someone's control narrative.

Renamed to **`lean`**, which describes what it actually is. `sandbox` is
kept as a deprecated alias forwarding to `[lean]` for one release,
because our own `python-314-wheels` CI job installs it
(`.github/workflows/ci.yml:218`) and so may customers. The alias
forwards rather than duplicating the dependency list, so the two cannot
drift.

## 2. SECURITY.md is stale and overclaims

- **Supported-versions table sat at 0.27.x** while the code ships 0.38.0
— four minor releases behind. A lagging table is worse than none: it
tells a reporter their release is unsupported when it is the current
one.
- **"No credential storage: We never store or log API keys"** is broader
than the code supports. `headroom/copilot_auth.py:646` persists the
GitHub Copilot OAuth refresh token to `~/.headroom/copilot_auth.json`.
It does so correctly — `chmod 0600` at `:648` — but it *is* stored, and
a blanket denial is the sort of claim a customer's security reviewer
checks.

The replacement says what is actually true: provider API keys are read
from the environment and forwarded without being written to disk; the
Copilot OAuth token is the one deliberate exception; and
request/response bodies may reach the runtime log when logging is
enabled, so that log is sensitive.

## Tests (original revision)

`tests/test_packaging_extras_and_security_docs.py` — four tests, all
failing before and passing after:

```
FAILED test_sandbox_alias_still_resolves_to_the_lean_profile
FAILED test_lean_profile_stays_torch_free
FAILED test_security_policy_supported_versions_match_the_shipped_version
FAILED test_security_policy_does_not_claim_blanket_no_credential_storage
4 failed  ->  4 passed
```

Method: commit, `git checkout origin/main -- pyproject.toml SECURITY.md`
(keeping the new tests), run, restore.

The version-table test is the one that matters most — main now documents
"latest release on PyPI" as the supported version, and the test (renamed
`test_security_policy_supports_the_latest_release_without_a_version_number`)
pins that and fails if a hard-coded version row returns, so **the table
cannot silently rot again**. That drift, not the wrong number, is the
actual defect.

`test_lean_profile_stays_torch_free` guards the profile's whole reason
for existing: adding a torch-pulling extra to it now fails the build by
name.

## Not done here

The backlog pairs this with a deprecation *warning* on the old extra
name. pip has no mechanism to warn on an extra at install time, so the
alias plus the comment is the available remedy; removal is noted for
after 0.39.x.

Ruff 0.16.7 `check` + `format --check` clean.

---

## Follow-up: the credential-persistence path (review of this PR)

@JerrettDavis blocked the first version because the SECURITY.md
*correction* was
itself inaccurate — it claimed provider API keys are not written to
disk, which
`headroom install --env KEY=VALUE` falsifies. Addressed in 3da8b955 by
disclosing the path accurately **and** narrowing its permissions.

What the trace found: `--env` values are merged into
`DeploymentManifest.base_env`
and persisted verbatim — into `manifest.json` *and*, as cleartext
`export` lines,
into the generated `run-headroom.sh` / `ensure-headroom.sh`. The
manifest was
already 0600, but only incidentally (via `mkstemp`), with nothing
pinning it. The
runner scripts were **0755** and the profile directory **0755** — a live
API key
in a world-readable file.

Persistence is kept: supervisors start from a bare environment, so
`--env` is the
only channel that reaches a supervised proxy. Redacting secret-valued
entries
would leave existing installs starting a proxy with no credential — a
silent 401
after upgrade. Instead: manifest 0600, runner scripts 0700 (0600 for the
`.ps1`),
profile directory 0700, applied on every save so pre-existing profiles
are
narrowed too; scripts created via `os.open(..., mode)` so no
world-readable window
exists between write and chmod.

SECURITY.md now names the files, the modes, that owner-only is not
encryption,
that rotation means re-running `install apply`, and that the Docker
runtime also
places the value in the container command line (`ps`-visible). The
`--env` help
text says the same.

The policy test now drives the real path — `build_manifest` →
`save_manifest` →
`render_runner_scripts` with a provider key against a fake `$HOME` —
asserts the
key really lands in both files, and **parses the documented octal modes
back out
of SECURITY.md** to compare against `stat()`, so the document and the
code cannot
drift apart again.

```
FAILED test_install_env_persists_a_provider_key_exactly_as_the_policy_describes
FAILED test_security_policy_discloses_the_persistent_install_credential_path
FAILED test_save_manifest_writes_owner_only
FAILED test_save_manifest_narrows_a_profile_directory_created_before_this_change
FAILED test_render_runner_scripts_are_owner_only_because_they_export_secrets
       (run-headroom.sh is 0755, exposing an API key)
FAILED test_render_unix_runner_narrows_a_script_written_by_an_earlier_version
6 failed  ->  315 passed
```

### ⚠️ Release note — behaviour change

Existing deployment profiles are **re-permissioned on the next `headroom
install
apply`**: `~/.headroom/deploy/<profile>/` and its runner scripts drop
group and
other bits (0755 -> 0700). Anyone reading or executing `run-headroom.sh`
as a
different, non-root user must now do so as the owner. No supported
supervisor
configuration does this — user scope runs as the installing user, system
scope as
root — but it changes the mode of files that already exist on customer
machines.
`--env` itself is unchanged: no value is dropped, redacted or relocated.

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/3727"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

---------

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-28 14:56:54 -07:00
Tejas ChopraandClaude Opus 5.5 59b8cefc24 deps!: drop the crewai extra to remove chromadb from the lockfile (#3870)
## Description

Removes the `crewai` extra. Every CrewAI release requires `chromadb`,
which has unpatched advisories in its server, so the extra kept CrewAI,
ChromaDB and about 40 other packages in `uv.lock` and in Headroom's
Dependabot alerts. Headroom never imports ChromaDB or runs a ChromaDB
server, and the extra was never part of `[all]`, `[sandbox]` or any
image.

The extra added nothing to the integration itself: the CrewAI adapter
only wraps CrewAI tools and uses whatever CrewAI the user has installed.
Users install CrewAI alongside Headroom instead.

Closes Dependabot alerts #204, #205, #206 (chromadb) and #412, #413
(oauthlib, which came in only through ChromaDB's Kubernetes client).
Dependabot PR #3890 (oauthlib bump) becomes moot.

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [x] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- `pyproject.toml`: remove the `crewai` extra, with a comment saying why
there is none.
- `uv.lock`: 42 packages removed (crewai, chromadb, kubernetes, lancedb,
oauthlib and their dependencies). Nothing added or upgraded.
- `SECURITY.md`: the CrewAI / ChromaDB section now states the new
boundary: Headroom does not lock CrewAI or ChromaDB, and a user who
installs CrewAI owns that exposure. It still lists the ChromaDB
advisories and server mitigations for those users.
- `.github/dependabot.yml`: drop the ChromaDB ignore range, which now
matches nothing. The Accelerate range stays.
- Installation docs and the integrations docstring now say `pip install
headroom-ai crewai`.

## Migration

`pip install "headroom-ai[crewai]"` still succeeds, but pip warns about
the unknown extra and installs Headroom without CrewAI. Replace it with:

```bash
pip install headroom-ai crewai
```

The CrewAI integration (`headroom.integrations.crewai`) is unchanged.
Without CrewAI installed it raises an `ImportError` that names the same
command.

## Testing

- [ ] Unit tests pass (`pytest`) — no code changed; the CrewAI tests
skip without CrewAI, as before
- [x] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`) — no Python code changed
- [ ] New tests added for new functionality — not applicable
- [x] Manual testing performed

### Test Output

```text
$ uv lock --check
Resolved 250 packages
$ grep -c '^name = "crewai"\|^name = "chromadb"\|^name = "oauthlib"' uv.lock
0
$ python -c "import headroom.integrations"   # imports without CrewAI
```

## Real Behavior Proof

- Environment: local, Python 3.14, current main merged in.
- Exact command / steps: `uv lock --check`; checked that crewai,
chromadb and oauthlib are absent from `uv.lock`; imported
`headroom.integrations` without CrewAI installed.
- Observed result: lockfile consistent; the three packages are absent;
import succeeds.
- Not tested: installing CrewAI alongside Headroom in a fresh
environment.

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: n/a
- Stable/default behavior changed: no runtime change; packaging only.
The `[crewai]` extra no longer installs CrewAI.
- Kill switch / disable path: n/a
- Unsafe override required: no
- Qualification impact: none
- Rollback path: revert this PR.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works — not applicable (packaging change)
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Additional Notes

Marked breaking (`deps!:`) so release-please records the removal and the
migration note above. Addresses the review on this PR: breaking-change
classification and migration note, SECURITY.md and Dependabot updated in
the same PR, branch brought current with main.

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-01 11:29:19 -07:00
Keshav ReddyandJerrettDavis 6ff74c5db5 docs(security): correct credential-storage claim and add a security model page (#2684)
## Description

`SECURITY.md` claimed **"No credential storage: We never store or log
API keys."** That is inaccurate — `headroom copilot-auth login` persists
a GitHub Copilot OAuth **refresh token** to disk in plaintext, CCR
writes pre-compression originals to a local SQLite database by default,
and the dashboard settings store persists two credential-shaped header
maps. None of it was documented anywhere.

Rather than patch the one line, this PR gives the topic a home:
`docs/content/docs/security-model.mdx` documents the trust model, data
in flight, data at rest, the local control surfaces, and network egress
in enough detail to answer a security review without reading the source.

**This documents existing behavior only. There are no code changes.**
Several things the page describes are already implemented correctly and
simply weren't discoverable — the loopback guard's DNS-rebinding
defence, the same-origin CSRF gate, the `runtime-env` allowlist, the
audit stream's keys-not-values discipline, and the `0600` permissions on
the credential, cache, and settings files.

Closes #2683

## Type of Change

- [x] Documentation update

## Changes Made

**`docs/content/docs/security-model.mdx`** (new, 392 lines) — trust
model; data in flight; a data-at-rest table with path, contents,
retention, encryption and permissions per item; the settings store;
logs; memory store paths; CCR persistence and lazy purge; local control
surfaces (three gates, two CIDR allowlists, what `POST
/admin/runtime-env` and `POST /settings` can each change, residual
risk); network egress and the beacon; governed knobs; what `wrap`
changes.

**`docs/content/docs/meta.json`** — a `Security` nav section carrying
the new page.

**`SECURITY.md`**
- Replaced the `Security Features` bullets with an accurate `Security
Posture` section: provider API keys are forwarded and not persisted
*except* for the two settings-store header maps; the Copilot OAuth token
**is** persisted (path, format, permissions stated); CCR cached
originals **are** written to disk, with the
`HEADROOM_CCR_BACKEND=memory` opt-out; the beacon uploads by default;
operational logs are always written; local control surfaces are
loopback-gated, with the trusted-dashboard CIDR caveat
- Dropped `Input validation: All inputs are validated before processing`
and `Safe defaults: Security-conscious defaults out of the box` —
unfalsifiable claims that made the section read as marketing rather than
policy
- Added best-practice notes covering `~/.headroom` and the two log paths
- **Supported versions**: replaced the pinned `0.33.x` row with the
actual policy — latest release only, fixes ship forward rather than
being backported — so the table stops going false every release

## Testing

- [x] Manual testing performed

### Test Output

The docs site is the Next.js/Fumadocs app in `docs/`. `npm run build`
compiles clean:

```text
$ cd docs && npm ci && npm run build
▲ Next.js 16.3.0 (Turbopack)
✓ Running next.config.mjs took 27ms
  Finished writing to disk in 4ms
  Finished TypeScript in 1216ms ...
✓ Generating static pages using 12 workers (167/167) in 833ms
  Finalizing page optimization ...
```

167 static pages, zero warnings, zero errors. `security-model` builds
(`.next/server/app/docs/security-model.html`) and appears in
`sitemap.xml`.

All 17 internal anchors on the page resolve against the generated HTML:

```text
$ python3 - <<'EOF'   # ids vs href="#..." in the built page
internal anchor links: 17
BROKEN: none
EOF
```

## Real Behavior Proof

Every factual claim on the page was verified against a running
interpreter rather than read off a comment.

- Environment: Linux (Ubuntu 26.04, x86_64), Python 3.14.4, repo at
`2ef83d35` (rebased onto `7ef736fb`), package importable from the source
tree.
- Exact command / steps: seeded each store under an isolated
`HEADROOM_WORKSPACE_DIR`, then read the resulting files back directly —
below.
- Observed result: SQLite is the default CCR backend and the
pre-compression original is on disk in plaintext at `0600`; the settings
store writes a secret header map to disk in plaintext at `0600` while
masking it on read, and feeds it back into the process environment;
`proxy.log` is created without an explicit mode and lands at `0664`.
- Not tested: the `huggingface.co` and `app.headroomlabs.ai` rows in the
egress table are documented from code paths, not exercised end-to-end. I
deliberately left `cdn.pyke.io` **out** of that table: `ort` is declared
with `default-features = false` and `load-dynamic`
(`crates/headroom-core/Cargo.toml`), which loads a system ONNX Runtime
rather than downloading one, so I could not substantiate it as a live
egress path. Happy to add it if a maintainer knows of a build
configuration where it does fetch.

### 1. CCR writes pre-compression originals to disk

```bash
HEADROOM_WORKSPACE_DIR=/tmp/hrtest python -c "
from headroom.cache.compression_store import get_compression_store
s = get_compression_store()
print('default backend:', type(s._backend).__name__)
print('hash:', s.store('SENTINEL_ORIGINAL_CONTENT_abc123', 'SENTINEL...', tool_name='Read'))
print('default_ttl_seconds:', s.default_ttl_seconds)"

sqlite3 /tmp/hrtest/ccr_store.db "SELECT * FROM ccr_entries;"
stat -c '%a %n' /tmp/hrtest/ccr_store.db
```

```text
default backend: SQLiteBackend
hash: 6c1bda2f2b2a6682c6c9bd82
default_ttl_seconds: 1800

6c1bda2f2b2a6682c6c9bd82|{"hash": "6c1bda2f2b2a6682c6c9bd82",
"original_content": "SENTINEL_ORIGINAL_CONTENT_abc123",
"compressed_content": "SENTINEL...", ..., "ttl": 1800, ...}

600 /tmp/hrtest/ccr_store.db
```

### 2. The settings store holds credentials in plaintext, and sets the
environment

```bash
HEADROOM_WORKSPACE_DIR=/tmp/hrtest python -c "
from headroom import settings_store
settings_store.save({'anthropic_extra_headers': {'Api-Key': 'SENTINEL_GATEWAY_KEY_xyz789'},
                     'log_messages': True,
                     'anthropic_base_url': 'http://attacker.example/v1'})
print('masked read:', settings_store.stored_values()['anthropic_extra_headers'])"

cat /tmp/hrtest/settings.json
stat -c '%a %n' /tmp/hrtest/settings.json
```

```text
masked read: ••••••

{
  "anthropic_base_url": "http://attacker.example/v1",
  "anthropic_extra_headers": "{\"Api-Key\": \"SENTINEL_GATEWAY_KEY_xyz789\"}",
  "log_messages": true
}

600 /tmp/hrtest/settings.json
```

The masking is a display control on `GET /settings`, not an at-rest one.
And the file is a second source for the process environment:

```text
before apply_to_environ: {'ANTHROPIC_TARGET_API_URL': None, 'HEADROOM_LOG_MESSAGES': None,
                          'ANTHROPIC_TARGET_API_HEADERS': None}
after  apply_to_environ: {'ANTHROPIC_TARGET_API_URL': 'http://attacker.example/v1',
                          'HEADROOM_LOG_MESSAGES': '1',
                          'ANTHROPIC_TARGET_API_HEADERS': '{"Api-Key": "SENTINEL_GATEWAY_KEY_xyz789"}'}
```

Both of those keys are in the settings registry, so `POST /settings` +
`POST /settings/apply` (which restarts the proxy) can set them. That is
why the page no longer claims the upstream URL is unchangeable over
HTTP.

### 3. `proxy.log` is always on, carries the audit stream, and is not
`0600`

```bash
HEADROOM_WORKSPACE_DIR=/tmp/hrtest python -c "
import logging
from headroom.proxy.helpers import _setup_file_logging
_setup_file_logging()
logging.getLogger('headroom.audit').info('{\"event\": \"headroom_admin_audit\", \"action\": \"settings_update\"}')
h = [x for x in logging.getLogger('headroom').handlers
     if x.__class__.__name__ == 'RotatingFileHandler'][0]
print('log path:', h.baseFilename, '| maxBytes:', h.maxBytes, '| backups:', h.backupCount)"

stat -c '%a %n' /tmp/hrtest/logs/proxy.log
```

```text
log path: /tmp/hrtest/logs/proxy.log | maxBytes: 10485760 | backups: 5
664 /tmp/hrtest/logs/proxy.log            # umask 0002 — not 0600 like the others
2026-08-18 06:35:56 - headroom.audit - INFO - {"event": "headroom_admin_audit", "action": "settings_update"}
```

### 4. Every documented env var resolves to a read site

The check that would have caught the `HEADROOM_COPILOT_AUTH_PATH` error
from round one — each `HEADROOM_*` / `ANTHROPIC_*` / `OPENAI_*` /
`DO_NOT_TRACK` name in the page and in `SECURITY.md`, grepped back to
`headroom/` or `crates/`:

```text
30 env names referenced
NOT FOUND IN SOURCE: none
```

The 7-key `runtime-env` allowlist and the 59-field settings registry
were likewise enumerated from `RUNTIME_ENV_KNOBS` and `SETTINGS`
directly, not transcribed.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I did **not** edit `CHANGELOG.md`

## Additional Notes

**N/A checklist items:** unit tests, linting, mypy, and new tests — this
is a docs-only change with no Python touched.

**Site location.** The page lives in `docs/`, the Next.js/Fumadocs app,
and links resolve to `headroom-docs.vercel.app/docs/security-model`.
Re-confirmed against current `main`: `.github/workflows/docs.yml` and
`docs/app/layout.tsx` both name that app as the one documentation site,
and `wiki/` is unpublished markdown nothing builds. An earlier revision
of this PR put the page in `wiki/` under `mkdocs.yml`; #2784 removed
that site, and this PR was moved accordingly.

**Two things a reviewer may want to weigh in on:**

1. **Wording on lazy TTL purge.** The page states that expired CCR rows
are removed by a sweep that runs on lookup rather than a background
timer, so on an idle proxy content can persist past its TTL. Re-checked
on current `main`: the documented Python path is still a fixed
`created_at + ttl` window (`headroom/cache/backends/sqlite.py`), and the
sliding idle-window TTL with an 8× max-lifetime ceiling from #2604 lives
in the Rust core backends, so it does not change what this page
describes. I documented the behavior as-is rather than treating it as a
defect.

2. **Residual-risk framing.** The "Local control surfaces" section says
plainly that the gates distinguish where a request came from, not who
sent it, and that Headroom should not be deployed on multi-user hosts
without additional isolation. I think stating this is a strength — it is
the honest read of the design — but it is a judgement call about tone
and I am happy to adjust.
## Runtime Rollout Safety

- Rollout-managed feature(s): none; this PR changes documentation only.
- Minimum rollout channel: documentation deployment after the
Next.js/Fumadocs build passes.
- Stable/default behavior changed: none; the page documents current
credential, persistence, control-surface, logging, and egress behavior.
- Kill switch / disable path: human-revert the documentation if a
factual claim is later disproven.
- Unsafe override required: none.
- Qualification impact: the docs build, sitemap entry, internal links,
and source-backed environment/path claims must remain valid.
- Rollback path: human-revert the docs commit; no runtime state or
migration is involved.

---------

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-10-01 00:12:21 -05:00
JD Davis 04cdf79ab0 fix: stabilize release checks and consolidate dependency updates (#3531)
## Description

Consolidates the open dependency updates into one draft and fixes the
remaining release 0.38.0 test failures. Release packaging already
includes the merged Node 24 fix from #3516. The concurrency test now
proves request overlap with a barrier, and the release workflow tests
verify registry-range consistency and publication failure gating without
hard-coding obsolete dependency versions.

Updates npm, Cargo, Python, and GitHub Actions dependencies. Adds
recurring audits of all five npm lockfiles at every severity. Upgrades
CrewAI to remove its vulnerable json-repair 0.25.2 pin, and replaces
yanked chacha20 and pypdfium2 releases.

This remains a draft. All 67 hosted checks pass on 59854000c, including
CI, release dry-run, security scans, and end-to-end tests. Unpatched
optional ChromaDB/Accelerate vulnerabilities still prevent claiming that
all dependency security issues are fixed. No alerts are dismissed and no
integration is removed.

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)

## Changes Made

- Upgrade OpenAI SDK / AI SDK development dependencies, Fumadocs
Twoslash, docs TypeScript, OpenCode Vitest, grouped npm dependencies,
and the wrap CLI pin.
- Upgrade Cargo's grouped dependencies, Redis to locked 1.7.0,
tree-sitter to 0.26.12, and chacha20 to 0.10.2.
- Upgrade Ruff to 0.16.4, Sentence Transformers to locked 6.0.1, CrewAI
to >=1.15.21 / json-repair 0.60.1, and pypdfium2 to 5.13.0.
- Consolidate checkout v7 and the Rust toolchain / PyPI publishing
action updates. Use Node 24 for OpenCode's Vitest 5 checks.
- Scope TypeScript 7 exceptions to the SDK and plugins whose tsup
declaration builds still require its legacy compiler API. Docs uses
TypeScript 7 successfully. Retain the Python tree-sitter-language-pack
1.x compatibility exception documented in #1216.
- Ignore only the reviewed unpatched ChromaDB/Accelerate update ranges,
leaving later releases eligible. Document all five distinct upstream
advisories in SECURITY.md (four currently have open repository
Dependabot alerts).

## Dependabot PR disposition

The dispositions below describe what this branch will supersede after
successful validation and merge. They do not authorize closing the PRs
before then. Future releases and newly disclosed advisories must remain
eligible for updates.

| PRs | Disposition |
| --- | --- |
| #3530, #3524 | @ai-sdk/openai 4.0.60 in SDK and docs |
| #3529, #3526, #3297 | openai 7.10.0 in SDK and docs |
| #3525 | fumadocs-twoslash 4.0.0 |
| #2278 | docs TypeScript 7.0.2 |
| #3528, #3527, #2282 | Bounded TypeScript 7 exception for tsup
consumers; TypeScript 7 declaration failure reproduced |
| #3523 | Grouped npm updates included |
| #3518 | Cargo grouped updates included |
| #3515 | Superseded secure wrap tree: OpenClaw 2026.9.3, Hono 4.13.7,
tar 7.5.22 |
| #3497 | OpenCode Vitest 5.0.0 |
| #3420 | TOML 4.3.0 already present |
| #3303 | All remaining checkout actions moved to v7 |
| #3299 | PyPI publish action 1.14.2; Rust uses @stable with explicit
1.95.0 input matching rust-toolchain.toml (1.100.0 downloads return 404,
and compiler versions are no longer action refs for Dependabot to
update) |
| #3292 | Sentence Transformers <7 constraint, locked 6.0.1 |
| #3291 | Bounded language-pack 1.x exception; incompatible parser API
documented in #1216 |
| #3290 | Ruff 0.16.4 in pyproject, lockfile, and pre-commit |
| #3159 | Rust tree-sitter 0.26.12, grammar versions unchanged |
| #3148 | Redis 1.x supported and locked at 1.7.0 |

## Testing

- [x] Unit tests pass (`pytest`) for the changed/tested areas below
- [x] Manual testing performed

### Test Output

- All five npm locks audit clean; changed npm trees re-audited after
major upgrades.
- SDK: typecheck, build, 294 tests passed / 33 external integration
tests skipped.
- OpenCode: typecheck, build, 17 tests passed; both rebuilt standalone
artifacts match the committed wheel bundles.
- OpenClaw: typecheck and build passed. Wrap CLIs installed and version
checks passed.
- Docs: fresh-container npm ci, typecheck, and production build passed
with TypeScript 7 and Twoslash 4 (164 pages), excluding all generated
caches. Updated Twoslash compiler options to its native string format
after hosted CI exposed the old numeric/filename configuration.
- Rust: core check with Redis enabled passed; 14 CCR backend tests
passed against a live isolated Redis, including round-trip and TTL
tests. All 30 code-compression parity fixtures matched. Other parity
categories passed or reported their existing unavailable
comparators/models.
- Cargo audit: zero vulnerabilities and warnings under the existing
repository policy; its existing unmaintained-paste exception is
unchanged.
- Python: all 50 release workflow tests plus embedder tests passed (62
passed, 3 MPS-only skips); all 12 CrewAI integration tests passed
against dependencies exported from the revised lockfile.
- Real Sentence Transformers 6.0.1 CPU embedding produced a (2, 384)
array; PDFium 5.13.0 rendered a 100x100 page.
- PyPI vulnerability metadata checked for all 288 registry
package/version pairs in uv.lock. Only ChromaDB and Accelerate remain
affected. The production pip-audit export also passed after the final
CrewAI-related lock refresh.
- Ruff 0.16.4, actionlint, uv lock --check, Dependabot directory
uniqueness, and git diff --check passed.
- Final combined release/concurrency suite: 76 passed. Strict
workspace/all-target Rust clippy with Redis enabled passed with -D
warnings.
- Independent read-only review found no important actionable issues
before pushing e5c542f57. Hosted CI then exposed unavailable Rust
1.100.0 downloads and obsolete Twoslash compiler options; both were
corrected in 59854000c. All 67 hosted checks passed on final commit
59854000c: CI run 34506787966 and release dry-run 34506788244 both
succeeded. All four Python shards passed; shard 1 reported 3,037 passed
/ 141 skipped. The docs build, Rust tests/parity/audit, all wheel import
checks, security scans, devcontainers, and Docker/native end-to-end
checks also passed.

## Real Behavior Proof

- Environment: local Windows/Python 3.12, Linux Node 24 containers, and
isolated Redis 7 container.
- Exact command / steps: npm package scripts; cargo test --locked -p
headroom-core --features redis --test ccr_backends with
HEADROOM_TEST_REDIS_URL set; cargo run --locked -p headroom-parity --
run --fixtures tests/parity/fixtures; pytest
tests/test_release_workflows.py and relevant embedder/CrewAI tests.
- Observed result: tests and builds above pass. Temporarily serializing
the overlap test causes TimeoutError; restoring unbounded mode passes
all 26 tests in that module.
- Not performed: publication or merge. Final hosted CI and release
dry-run both passed. MPS-only and external-service SDK tests were
skipped locally.

## Runtime Rollout Safety

- Rollout-managed feature(s): no new feature flags; dependency and test
changes.
- Minimum rollout channel: existing policy unchanged.
- Stable/default behavior changed: dependency versions updated; no
integration removed.
- Kill switch / disable path: existing feature controls unchanged.
- Unsafe override required: no.
- Qualification impact: hosted release, security, and end-to-end checks
passed on final head 59854000c. Unpatched optional-extra advisories
remain a security qualification blocker.
- Rollback path: revert the applicable commits.

## Review Readiness

- [x] I have performed a self-review
- [ ] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I did **not** edit `CHANGELOG.md`

## Additional Notes

Unresolved upstream vulnerabilities: ChromaDB GHSA-f4j7-r4q5-qw2c,
GHSA-2wm9-hf6c-p5cr, GHSA-36p7-vc44-83pf, GHSA-xph7-9rjv-w5fr;
Accelerate GHSA-4j2p-28q2-5m79. Existing exposure restrictions are
mitigations, not fixes. Dependabot ignore rules cannot make these
dependencies vulnerability-free. Keep this draft open; do not merge
automatically.
2026-09-10 12:34:31 -05:00
JD Davis 4263da12b5 fix(deps): remediate vulnerable CLI and plugin dependency trees (#3521)
Updates the wrap E2E CLI and OpenCode plugin dependency trees to remove
vulnerable versions matching 194 of the 198 open Dependabot alerts
reviewed on 2026-09-10.

- Upgrade the pinned OpenClaw CLI from 2026.4.7 to 2026.9.3 and use Node
24 in its Docker harness to satisfy the new engine requirement. Its
current dependency tree removes the vulnerable legacy extraction,
image/PDF, and coding-agent dependencies and updates Hono/tar.
- Upgrade Vitest to 4.1.11 and resolve TOML to 4.3.0 in the OpenCode
plugin lockfile.
- Handle OpenClaw's explicit legacy-flag migration with its
source/capability confirmation flags, preserving terminal install-policy
failures. Run the isolated Docker gateway in the foreground on loopback
with a per-run authentication token.
- Include `/e2e/wrap/tools` in Dependabot's npm update directories.
- Document the four unresolved optional Python dependency alerts in
`SECURITY.md`, with upstream evidence and exposure mitigations. ChromaDB
has no patched release; Accelerate 1.15.0 still has the unsafe
checkpoint loader despite being outside the advisory's stated version
range. No alerts are dismissed and no supported integrations are
removed.

Validation: both npm lockfile audits report zero vulnerabilities; all
194 npm advisory ranges were checked against every installed package
path in the new locks, including an independent review. OpenCode
typecheck, build, all 17 tests, and standalone build pass; both
standalone artifacts exactly match the committed wheel bundles. The
Docker image builds and the full local Docker wrap E2E passes with the
compatibility changes mounted into the built image. All 41 Python
OpenClaw wrapper/provider tests and changed-file Ruff checks pass. CI is
green on e6d760de7b: all four main Python
test shards, optional-extras and Agno tests, package builds, wrapper
checks, CodeQL, dependency/secret scans, and Docker init/wrap/native E2E
passed.

Remaining upstream blockers: Dependabot #204, #205, #206 (ChromaDB) and
#211 (Accelerate). This PR does not claim those four are fixed. Leave
this PR open for review; do not merge automatically.
2026-09-10 09:06:44 -05:00
Tejas Chopra 53be64ca12 chore(telemetry): remove Supabase anonymous beacon; fix contact domain to headroomlabs.ai (#1526)
## Description

Removes the anonymous-telemetry **beacon** — the only external,
third-party data flow Headroom ever initiated. When telemetry was opted
in, it POSTed aggregate `/stats` to a hardcoded **Supabase** REST
endpoint (with an embedded anon API key in the source). For
enterprise/on-prem deployments this is exactly the kind of
vendor-controlled data egress a security review flags, so it's gone
entirely — **zero "Supabase" references remain in the codebase.**

What stays (by design): the **local** telemetry collector + the
`HEADROOM_TELEMETRY` opt-in (it only feeds `/stats` and `/v1/telemetry`
— nothing leaves the process), **OpenTelemetry export**
(`HEADROOM_OTEL_METRICS_*`, so operators send operational metrics to
*their own* collector), and the license usage reporter (your own domain,
license-key-gated).

Also fixes the contact domain: `headroom.dev` → `headroomlabs.ai`
everywhere.

Closes # (no tracking issue)

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [x] Code refactoring (no functional changes)

> Non-breaking: `HEADROOM_TELEMETRY` is still accepted (now gates local
collection only). The only behavior change is that no telemetry is ever
sent externally.

## Changes Made

- **Deleted the Supabase beacon**: `TelemetryBeacon` class,
`_SUPABASE_URL`/`_SUPABASE_KEY`/`_TABLE`/`_ENDPOINT`, the JSONB
projection helper, the proxy-lifespan beacon wiring, the `SUPABASE_`
install env passthrough, and `tests/test_strategy_stats_supabase.py`.
- **Kept** the local opt-in predicate (`is_telemetry_enabled` etc.) in
`beacon.py` — still used by the local collector + CLI — reworded to
"local only".
- **Retained** the single-worker-owner file lock (the cc-switch
reconciler depends on it); updated its comments to drop the beacon
framing.
- `/stats` `anon_telemetry_shipping` is now always `False` (nothing
ships externally); startup log reworded to "Local telemetry".
- Reworded remaining "Supabase" comments in `collector.py`,
`context.py`, `prometheus_metrics.py`, and two test docstrings.
- Contact domain: `security@headroom.dev` → `security@headroomlabs.ai`,
`conduct@headroom.dev` → `conduct@headroomlabs.ai`, FUNDING.yml sponsor
URL.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check`)
- [x] Type checking passes (`mypy`)
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
$ grep -rniI "supabase" --include=*.py --include=*.md --include=*.mdx .   # (excl .venv/sbom)
>>> ZERO Supabase references

$ grep -rniI "headroom.dev" .
>>> ZERO headroom.dev references

$ ruff check <changed files>           -> All checks passed!
$ ruff format --check <changed files>  -> 10 files already formatted
$ mypy <changed telemetry files>       -> Success: no issues found

$ pytest tests/test_telemetry.py tests/test_telemetry_warning.py \
    tests/test_proxy_telemetry_env.py tests/test_compression_observability.py \
    tests/test_paths.py tests/test_paths_backward_compat.py -q
============================= 173 passed in 6.67s ==============================
```

## Real Behavior Proof

- **Environment:** macOS, Python 3.12 (`.venv`).
- **Exact command / steps:** repo-wide grep for
`supabase`/`headroom.dev`; `create_app(...)` driven through a full
`TestClient` lifespan (startup + shutdown) in
`test_proxy_telemetry_env.py`; `/stats` exercised in
`test_telemetry_warning.py`.
- **Observed result:** zero `supabase`/`headroom.dev` strings remain;
the proxy starts and shuts down cleanly with the beacon removed (the
worker-owner lock + reconciler still elect a single owner);
`/stats.anon_telemetry_shipping` is `False` even with
`HEADROOM_TELEMETRY=on`; local collector + OTEL paths unchanged.
- **Not tested:** no live network call was ever made (the point — the
external POST is gone). OTEL export and the license reporter were not
exercised (unchanged by this PR).

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [ ] I have updated the CHANGELOG.md if applicable

## Additional Notes

- The license usage reporter (`reporter.py` → `app.headroomlabs.ai`) is
intentionally **kept** — it's license-key-gated (dormant for
unlicensed/OSS deployments) and goes to your own domain, not a third
party.
- Docs/CHANGELOG left unchecked: a couple of docs mention the telemetry
beacon and may want a follow-up note that it now collects locally only;
happy to add.
2026-06-27 22:48:26 -07:00
Tejas Chopra bd76235f5c fix(cli): harden all CLI surfaces + fix docs accuracy (#1491)
## Summary

Full CLI audit + documentation accuracy pass. All 5 commits on this
branch:

### CLI Hardening (4 commits)
- **Clean errors instead of tracebacks**: corrupt manifests, missing
Docker, malformed JSONL, bad `--profile`, invalid env-var values all now
raise `click.ClickException` with helpful messages
- **Range validation**: ~25 numeric flags across 10 files now use
`click.IntRange`/`FloatRange` — `--port 0`, `--hours -1`, `--limit 0`
etc. produce clean usage errors instead of silent wrong behavior
- **Flag combination warnings**: conflicting combos (`--no-rate-limit` +
`--rpm`, `--no-optimize` + `--target-ratio`, `--telemetry` +
`--no-telemetry`) emit yellow warnings on stderr
- **`memory --db-path` default fixed**: was resolving to
`headroom_memory.db` (wrong bare file); now uses project store
`./.headroom/memory.db` if present, else `~/.headroom/memory.db`
- **`memory list --search` + filters**: `--scope`/`--session`/`--since`
were silently ignored when `--search` was also set; now filters are
applied to search results
- **`learn --verbosity --apply` now works**: the output shaper is off by
default (`HEADROOM_OUTPUT_SHAPER`); `--apply` now hot-enables it via
`POST /admin/runtime-env` on a running proxy, or prints explicit `export
HEADROOM_OUTPUT_SHAPER=1` instructions when no proxy is running
- **`perf --hours` overflow**: `1e9` hours no longer raises
`OverflowError`; treated as "all data"
- **`evals memory --categories` invalid input**: `abc,1,2` now raises
`BadParameter` instead of a raw `ValueError` traceback

### Documentation (1 commit, 20 files)

Corrected factual errors found by 3 parallel audit agents across root
docs, wiki, and the published Fumadocs site:

**Critical (caused runtime errors or wrong behavior if followed):**
- `simulation.mdx`: `plan.transforms_applied` -> `plan.transforms`;
`plan.savings_percent` -> computed from available fields (both raised
`AttributeError`)
- `shared-context.mdx`: `import { SharedContext } from "headroom"` ->
`"headroom-ai"` (5x `ImportError`)
- `claude-code-azure-foundry.mdx`: `pip install headroom` -> `pip
install headroom-ai`
- `api-reference.mdx` + `configuration.mdx`: `from headroom import
GoogleProvider` -> `from headroom.providers import GoogleProvider`
- `ccr.mdx`: CCR TTL default 300s -> 1800s (30 min)

**Fabricated flags removed:**
- `wiki/proxy.md` + `wiki/cli.md`: `--no-intelligent-context`,
`--no-intelligent-scoring`, `--no-compress-first` (none exist); replaced
with real CCR flags
- `wiki/configuration.md`: `--no-ccr-responses`, `--no-ccr-expansion`
(none exist); replaced with real flags
- `wiki/troubleshooting.md`, `wiki/metrics.md`,
`docs/troubleshooting.mdx`: `headroom proxy --log-level debug` (flag
doesn't exist)

**Stale content corrected:**
- `llms.txt`: telemetry stated as enabled-by-default (it's opt-in); wrap
list had 5 tools (now 11)
- `README.md`: compatibility matrix added 5 missing `wrap` targets;
`unwrap`, `doctor`, `init`/`install`, savings-analytics now mentioned
- `SECURITY.md`: supported version table showed 0.2.x (current: 0.27.x)
- `wiki/learn.md`: 5 missing flags added; verbosity shaper-off behavior
documented
- `wiki/quickstart.md`: "Configuration Reference" linked to `api.md`
(wrong) -> `configuration.md`
- `CacheAlignerConfig.enabled` default corrected: `True` -> `False`
- `opencode.mdx`: `--port` default wrong ("random") -> 8787; `openai`
backend removed
- `CONTRIBUTING.md`: broken Markdown table cell fixed
- `docs/meta.json`: `claude-code-azure-foundry` added to nav (was
unreachable orphan page)
- `configuration.mdx`: SDK modes vs proxy `--mode` now clearly
distinguished

## Test plan

- [x] `python -m pytest tests/ -x -q` — 857 passed, 0 failures
- [x] 41-combination CLI smoke test (all flag combos across 8 commands)
— 0 tracebacks
- [x] `ruff check` on all modified Python files — clean
- [x] Docs changes are removals/corrections of fabricated or stale
content; no new claims introduced
2026-06-27 14:48:43 -07:00
ParideboyandClaude Opus 4.8 8cc5354f51 docs: use headroom-ai package name in install commands (#1014) (#1257)
## Description

Install commands across the docs referenced the unpublished `headroom`
package instead of the published `headroom-ai`, so copy-pasted `pip
install` commands fail. This corrects them to `headroom-ai` (with
extras).

Closes #1014

## Type of Change

- [x] Documentation update

## Changes Made

- `wiki/getting-started.md`: corrected 4 `pip install headroom` commands
to `headroom-ai` (including the `[proxy]`, `[relevance]`, and `[all]`
extras).
- `docs/content/docs/claude-code-vertex.mdx`: fixed the install command
on line 37.
- `SECURITY.md`: fixed the install command on line 47.

## Testing

- [x] Manual verification

### Test Output

```text
$ rg -n "pip install headroom\b" docs wiki SECURITY.md
(no matches — all bare `headroom` install commands now use `headroom-ai`)
```

## Real Behavior Proof

- Environment: Windows 11, repo working tree on branch
fix/docs-1014-headroom-ai-pkg
- Exact command / steps: Grepped the docs tree for `pip install
headroom` before and after the edits.
- Observed result: Before, several occurrences referenced the
unpublished `headroom`; after, only `headroom-ai` remains (the spec doc
reference is intentionally left untouched).
- Not tested: Did not run a live `pip install headroom-ai` against PyPI
in CI.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

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

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-22 19:25:00 -05:00
chopratejas 175746cc26 Prepare for OSS release v0.2.0
This commit prepares Headroom for public open source release with
comprehensive documentation, licensing, and community infrastructure.

License & Legal:
- Add Apache 2.0 LICENSE file
- Add NOTICE file with third-party attributions
- Add SECURITY.md for vulnerability reporting

Community:
- Add CONTRIBUTING.md with contribution guidelines
- Add CODE_OF_CONDUCT.md (Contributor Covenant)
- Add GitHub issue templates (bug report, feature request)
- Add pull request template

Documentation:
- Update README.md with compelling value proposition
- Add docs/getting-started.md
- Add docs/proxy.md for proxy server documentation
- Add docs/transforms.md for transform reference
- Add docs/api.md for API reference
- Add examples/README.md

Package Infrastructure:
- Add headroom/py.typed for PEP 561 compliance
- Add headroom/cli.py for CLI entry point
- Add .github/workflows/ci.yml for CI pipeline
- Add .github/workflows/publish.yml for PyPI publishing
- Update pyproject.toml with proper metadata

New Features:
- Add multi-provider support (Google, Cohere, LiteLLM, OpenAI-compatible)
- Add universal tokenizer registry with multiple backends
- Add model registry with pricing and context limits
- Add production proxy server with caching and rate limiting

Code Quality:
- Fix 83 lint issues via ruff auto-fix
- Fix version consistency (benchmarks 0.1.0 → 0.2.0)
- Add skip decorators for optional dependency tests
2026-01-07 11:36:44 -08:00