Files
headroom/tests/test_install/test_state.py
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

311 lines
11 KiB
Python

from __future__ import annotations
import json
import logging
import os
import stat
import sys
from pathlib import Path
import pytest
from headroom.install.models import ArtifactRecord, DeploymentManifest, ManagedMutation
from headroom.install.paths import manifest_path, profile_root
from headroom.install.state import (
ManifestError,
delete_manifest,
delete_recovery_manifest,
list_manifests,
load_manifest,
save_manifest,
save_recovery_manifest,
)
def _manifest() -> DeploymentManifest:
return DeploymentManifest(
profile="default",
preset="persistent-service",
runtime_kind="python",
supervisor_kind="service",
scope="user",
provider_mode="manual",
targets=["claude"],
port=8787,
host="127.0.0.1",
backend="anthropic",
mutations=[ManagedMutation(target="env", kind="shell-block", path="x")],
artifacts=[ArtifactRecord(kind="script", path="run-headroom.sh")],
)
def test_save_and_load_manifest_round_trip(monkeypatch, tmp_path: Path) -> None:
monkeypatch.setattr(Path, "home", lambda: tmp_path)
manifest = _manifest()
save_manifest(manifest)
loaded = load_manifest("default")
assert loaded is not None
assert loaded.profile == "default"
assert loaded.mutations[0].kind == "shell-block"
assert loaded.artifacts[0].kind == "script"
def test_load_manifest_raises_manifest_error_on_corrupt_payload(
monkeypatch, tmp_path: Path
) -> None:
monkeypatch.setattr(Path, "home", lambda: tmp_path)
# Simulate a crash mid-write: a truncated/garbage manifest left on disk.
profile_dir = tmp_path / ".headroom" / "deploy" / "default"
profile_dir.mkdir(parents=True)
(profile_dir / "manifest.json").write_text("{not json", encoding="utf-8")
# A present-but-corrupt manifest surfaces a typed ManifestError so callers can
# report cleanly or degrade, rather than a raw JSONDecodeError traceback.
with pytest.raises(ManifestError):
load_manifest("default")
def test_save_manifest_writes_atomically(monkeypatch, tmp_path: Path) -> None:
monkeypatch.setattr(Path, "home", lambda: tmp_path)
save_manifest(_manifest())
# No leftover temp file from the atomic write; only the manifest itself.
profile_dir = tmp_path / ".headroom" / "deploy" / "default"
assert sorted(p.name for p in profile_dir.iterdir()) == ["manifest.json"]
# And the persisted manifest still round-trips.
assert load_manifest("default") is not None
def test_recovery_manifest_preserves_mutations_and_artifacts(monkeypatch, tmp_path: Path) -> None:
monkeypatch.setattr(Path, "home", lambda: tmp_path)
manifest = _manifest()
save_recovery_manifest(manifest)
recovery = tmp_path / ".headroom" / "deploy" / "default.recovery.json"
assert recovery.exists()
payload = json.loads(recovery.read_text(encoding="utf-8"))
assert payload["mutations"][0]["kind"] == "shell-block"
assert payload["artifacts"][0]["kind"] == "script"
assert load_manifest("default") is None
delete_recovery_manifest("default")
assert not recovery.exists()
def test_list_manifests_ignores_invalid_payloads(monkeypatch, tmp_path: Path, caplog) -> None:
monkeypatch.setattr(Path, "home", lambda: tmp_path)
valid = _manifest()
save_manifest(valid)
broken_dir = tmp_path / ".headroom" / "deploy" / "broken"
broken_dir.mkdir(parents=True)
(broken_dir / "manifest.json").write_text("{not json", encoding="utf-8")
with caplog.at_level(logging.WARNING, logger="headroom.install.state"):
manifests = list_manifests()
assert [manifest.profile for manifest in manifests] == ["default"]
warnings = [r.getMessage() for r in caplog.records if r.levelno == logging.WARNING]
assert any(str(broken_dir / "manifest.json") in message for message in warnings)
assert not any(str(tmp_path / ".headroom" / "deploy" / "default") in m for m in warnings)
def _broken_profile(tmp_path: Path, name: str) -> Path:
path = tmp_path / ".headroom" / "deploy" / name / "manifest.json"
path.parent.mkdir(parents=True)
return path
def test_unreadable_and_malformed_manifests_get_distinct_messages(
monkeypatch, tmp_path: Path, caplog
) -> None:
"""A read failure must not be reported as corruption: the fix differs."""
monkeypatch.setattr(Path, "home", lambda: tmp_path)
malformed = _broken_profile(tmp_path, "malformed")
malformed.write_text("{not json", encoding="utf-8")
unreadable = _broken_profile(tmp_path, "unreadable")
unreadable.write_text(json.dumps({"profile": "unreadable"}), encoding="utf-8")
real_read_text = Path.read_text
def read_text(self: Path, *args, **kwargs) -> str:
if self == unreadable:
raise PermissionError(13, "Permission denied", str(self))
return real_read_text(self, *args, **kwargs)
monkeypatch.setattr(Path, "read_text", read_text)
with caplog.at_level(logging.WARNING, logger="headroom.install.state"):
assert list_manifests() == []
messages = [r.getMessage() for r in caplog.records if r.name == "headroom.install.state"]
assert len(messages) == 2
corrupt = next(m for m in messages if str(malformed) in m)
unread = next(m for m in messages if str(unreadable) in m)
assert corrupt.startswith("Skipping corrupt deployment manifest")
assert unread.startswith("Skipping unreadable deployment manifest")
assert "Permission denied" in unread and "permissions" in unread
with pytest.raises(ManifestError, match="is corrupt"):
load_manifest("malformed")
with pytest.raises(ManifestError, match="could not be read .*Permission denied"):
load_manifest("unreadable")
@pytest.mark.skipif(os.name != "posix", reason="mode bits decide access only on POSIX")
def test_save_manifest_keeps_manifest_owner_only(monkeypatch, tmp_path: Path) -> None:
monkeypatch.setattr(Path, "home", lambda: tmp_path)
save_manifest(_manifest())
path = tmp_path / ".headroom" / "deploy" / "default" / "manifest.json"
assert stat.S_IMODE(path.stat().st_mode) == 0o600
# A manifest left group/world-readable is tightened on the next save.
path.chmod(0o644)
save_manifest(_manifest())
assert stat.S_IMODE(path.stat().st_mode) == 0o600
def _write_manifest_with_image(profile_dir: Path, image: str) -> None:
profile_dir.mkdir(parents=True, exist_ok=True)
payload = {
"profile": profile_dir.name,
"preset": "persistent-docker",
"runtime_kind": "docker",
"supervisor_kind": "none",
"scope": "user",
"provider_mode": "manual",
"targets": ["claude"],
"port": 8787,
"host": "127.0.0.1",
"backend": "anthropic",
"image": image,
}
(profile_dir / "manifest.json").write_text(json.dumps(payload), encoding="utf-8")
def test_load_manifest_migrates_retired_image_repo(monkeypatch, tmp_path: Path) -> None:
monkeypatch.setattr(Path, "home", lambda: tmp_path)
profile_dir = tmp_path / ".headroom" / "deploy" / "default"
# A manifest written before the org move still pins the retired personal
# repo, which is frozen at 0.27.0. Loading it must rewrite the repo while
# preserving the tag, so the deployment tracks the current image (#2426).
_write_manifest_with_image(profile_dir, "ghcr.io/chopratejas/headroom:latest")
loaded = load_manifest("default")
assert loaded is not None
assert loaded.image == "ghcr.io/headroomlabs-ai/headroom:latest"
def test_load_manifest_leaves_unrelated_image_untouched(monkeypatch, tmp_path: Path) -> None:
monkeypatch.setattr(Path, "home", lambda: tmp_path)
profile_dir = tmp_path / ".headroom" / "deploy" / "default"
_write_manifest_with_image(profile_dir, "ghcr.io/headroomlabs-ai/headroom:0.31.0")
loaded = load_manifest("default")
assert loaded is not None
# An already-current image, and any third-party image, must pass through
# unchanged so the migration only ever rewrites the one retired repo.
assert loaded.image == "ghcr.io/headroomlabs-ai/headroom:0.31.0"
def test_list_manifests_migrates_retired_image_repo(monkeypatch, tmp_path: Path) -> None:
monkeypatch.setattr(Path, "home", lambda: tmp_path)
_write_manifest_with_image(
tmp_path / ".headroom" / "deploy" / "default",
"ghcr.io/chopratejas/headroom:0.27.0",
)
manifests = list_manifests()
assert [m.image for m in manifests] == ["ghcr.io/headroomlabs-ai/headroom:0.27.0"]
def test_delete_manifest_removes_profile_root(monkeypatch, tmp_path: Path) -> None:
monkeypatch.setattr(Path, "home", lambda: tmp_path)
manifest = _manifest()
save_manifest(manifest)
extra_file = tmp_path / ".headroom" / "deploy" / "default" / "runner.log"
extra_file.write_text("log", encoding="utf-8")
delete_manifest("default")
assert load_manifest("default") is None
assert not extra_file.parent.exists()
@pytest.mark.skipif(
sys.platform.startswith("win"),
reason="POSIX mode bits are advisory on Windows, where access is governed by ACLs",
)
def test_save_manifest_writes_owner_only(monkeypatch, tmp_path: Path) -> None:
"""`base_env` can hold a provider API key, so the manifest is 0600/0700.
`headroom install --env ANTHROPIC_API_KEY=...` is the supported way to give
a supervised proxy a credential (supervisors start from a bare
environment), and the value is serialized verbatim. At the common 022 umask
a plain write would leave a live key world-readable.
"""
monkeypatch.setattr(Path, "home", lambda: tmp_path)
manifest = _manifest()
manifest.base_env = {"ANTHROPIC_API_KEY": "sk-ant-api03-not-a-real-key"}
save_manifest(manifest)
path = manifest_path("default")
assert "sk-ant-api03-not-a-real-key" in path.read_text(encoding="utf-8")
assert path.stat().st_mode & 0o777 == 0o600
assert path.parent.stat().st_mode & 0o777 == 0o700
@pytest.mark.skipif(
sys.platform.startswith("win"),
reason="POSIX mode bits are advisory on Windows, where access is governed by ACLs",
)
def test_save_manifest_narrows_a_profile_directory_created_before_this_change(
monkeypatch, tmp_path: Path
) -> None:
"""An upgrade must fix an existing 0755 profile directory, not only new ones."""
monkeypatch.setattr(Path, "home", lambda: tmp_path)
root = profile_root("default")
root.mkdir(parents=True)
root.chmod(0o755)
save_manifest(_manifest())
assert root.stat().st_mode & 0o777 == 0o700
def test_delete_manifest_propagates_removal_failure(monkeypatch, tmp_path: Path) -> None:
monkeypatch.setattr(Path, "home", lambda: tmp_path)
root = tmp_path / ".headroom" / "deploy" / "default"
root.mkdir(parents=True)
monkeypatch.setattr(
"headroom.install.state.shutil.rmtree", lambda path: (_ for _ in ()).throw(OSError("busy"))
)
with pytest.raises(OSError, match="busy"):
delete_manifest("default")
@pytest.mark.windows_newline
def test_manifest_writes_pin_lf(monkeypatch, tmp_path: Path) -> None:
import headroom.install.state as state
monkeypatch.setattr(Path, "home", lambda: tmp_path)
calls: list[dict] = []
real_fdopen = state.os.fdopen
def fdopen(fd, *args, **kwargs):
calls.append(kwargs)
return real_fdopen(fd, *args, **kwargs)
monkeypatch.setattr(state.os, "fdopen", fdopen)
save_manifest(_manifest())
save_recovery_manifest(_manifest())
assert [call.get("newline") for call in calls] == ["\n", "\n"]