mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 18:41:07 +08:00
feat/https-compose-caddy
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
|
||
|
|
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 |
||
|
|
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
|
||
|
|
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> |
||
|
|
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> |
||
|
|
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 |
||
|
|
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
|
||
|
|
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. |
||
|
|
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
|
||
|
|
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> |
||
|
|
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 |