Files
headroom/tests/test_cache_breakpoint_diagnostics.py
Radhakrishnan PachyappanandJerrettDavis 125a703a65 fix(security): restrict the Windows runtime log via NTFS ACL, not just warn (#4135)
## Description

Windows never got the owner-only guarantee POSIX mode bits give the
proxy log, its rotated backups, and the JSONL request log — `os.chmod`
there only toggles the read-only attribute and leaves the real access
control (the ACL) untouched. The prior fix (#3728) correctly scoped that
gap and warned about it, but the warning text read as cryptic to at
least one user (reported here and on Discord), and closing the gap was
explicitly left as a follow-up pending a Windows CI runner to verify
against.

This implements that follow-up.

Closes #4058

## Type of Change

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

## Changes Made

- `headroom/_fileperms_windows.py` (new): the NTFS ACL implementation
via `ctypes` (no `pywin32` dependency) — a DACL with exactly one entry,
the calling user with full control, built fresh rather than merged with
the inherited entries that made the file readable in the first place,
applied with `PROTECTED_DACL_SECURITY_INFORMATION` so those inherited
entries are dropped.
- `headroom/fileperms.py`:
`restrict_fd_to_owner`/`restrict_path_to_owner` go through the new
module on Windows instead of giving up immediately; added
`verify_owner_only(path)`, which re-reads the actual DACL rather than
trusting a static platform flag — the ACL call can fail for reasons
unrelated to this code (a non-NTFS volume, a missing privilege).
- `headroom/proxy/helpers.py`: the startup warning now fires only when
`verify_owner_only` reports failure (not unconditionally on Windows),
and the wording says plainly that other accounts may be able to read the
file instead of the more technical original phrasing.
- `tests/test_cache_breakpoint_diagnostics.py`: new Windows-specific
tests exercising the ACL path directly (mirroring the existing POSIX
mode-bit tests), plus updates to the two tests whose assumption
("Windows protection is impossible") this PR deliberately changes.
- `docs/content/docs/proxy.mdx`: updated the "Who can read the logs"
section to describe the ACL instead of "Headroom does not restrict the
log file."
- `.github/workflows/ci.yml`: added a `windows-file-permissions` job
(same lightweight pattern as the existing
`windows-tool-result-interceptors` job) so this is exercised on a real
Windows runner going forward, addressing the maintainer's own "I'd want
a Windows runner in CI first" from #3728's review thread.

Deliberately **not** extended to the sqlite-backed memory/CCR stores
(`ensure_private_file`/`connect_private_sqlite`) or `private_dir` —
those remain unenforced on Windows, same as before this change, to keep
this PR scoped to what #4058 is actually about.

## Testing

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

### Test Output

```text
$ pytest tests/test_cache_breakpoint_diagnostics.py tests/test_private_state_files.py tests/test_proxy_handler_helpers.py -q
99 passed, 49 skipped in 13.50s

$ ruff check headroom/fileperms.py headroom/_fileperms_windows.py headroom/proxy/helpers.py tests/test_cache_breakpoint_diagnostics.py
All checks passed!

$ ruff format --check <same files>
4 files already formatted

$ mypy headroom/fileperms.py headroom/_fileperms_windows.py --ignore-missing-imports --platform linux
Found 1 error in 1 file (checked 2 source files)
# that 1 error is in headroom/providers/model_metadata.py, pre-existing and
# unrelated -- confirmed via `git stash` against main before these changes.

$ actionlint .github/workflows/ci.yml
# clean, no output
```

## Real Behavior Proof

- Environment: actual Windows 11 machine (not simulated/mocked) — this
is the one part of #3728 the original author explicitly could not do ("I
cannot execute or test on this machine")
- Exact command / steps: created a file, called the new
`restrict_handle`/`restrict_path`, then independently verified the
result with `icacls <path>` (a separate tool, not my own code checking
its own work)
- Observed result:
  ```
  C:\Users\...\Temp\acl_proto_test.txt LAPTOP-...\<user>:(F)
  Successfully processed 1 files; Failed processing 0 files
  ```
Exactly one ACE, granting the current user full control — no `Everyone`,
no `Users`, no leftover inherited entries. Also ran the full
`test_cache_breakpoint_diagnostics.py` suite on this same machine,
including the new Windows-specific tests
(`test_runtime_log_is_owner_only_via_acl_with_previews_off`,
`test_rotated_backups_are_owner_only_via_acl`) which were previously
impossible to exercise without a Windows box.
- Not tested: a non-NTFS volume or a locked-down-privilege environment
(the failure paths `verify_owner_only` is meant to catch) — those fall
back to the warning, covered by the existing simulated test, but I don't
have a non-NTFS Windows volume handy to exercise for real.

## Runtime Rollout Safety

- Rollout-managed feature(s): N/A
- Minimum rollout channel: N/A
- Stable/default behavior changed: Only on Windows — the runtime log is
now actually restricted instead of warned-about; POSIX behavior is
unchanged.
- Kill switch / disable path: None needed — this only adds protection
where there was none; a failure falls back to the pre-existing
warning-only behavior automatically via `verify_owner_only`.
- Unsafe override required: No
- Qualification impact: None
- Rollback path: Revert; Windows returns to warn-only, same as before
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
- [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`

## Additional Notes

Scope boundary, stated explicitly rather than left implicit: this does
not touch `ensure_private_file`/`connect_private_sqlite`/`private_dir`,
which stay unenforced on Windows as before. Extending ACL protection
there would be a reasonable follow-up but is a separate, larger piece of
surface (sqlite main file + `-wal`/`-shm`/`-journal` sidecars) than what
#4058 asked about.
<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4135"
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-10-24 08:39:05 -07:00

711 lines
28 KiB
Python

"""Tests for cache_control breakpoint diagnostics and log-privacy switches.
Covers the three pieces added for the uncached-tail investigation:
- ``count_cache_breakpoints`` / ``log_cache_breakpoints`` (proxy helpers)
- the ``HEADROOM_LOG_PAYLOAD_PREVIEW`` kill switch (compression store)
- the injection guard that keeps proactive expansion out of breakpointed blocks
"""
from __future__ import annotations
import logging
import os
import stat
from contextlib import contextmanager
from pathlib import Path
import pytest
from headroom import fileperms
from headroom import paths as _paths
from headroom.cache.compression_store import _payload_for_retrieval_log
from headroom.proxy.handlers.anthropic import AnthropicHandlerMixin
from headroom.proxy.helpers import (
_OwnerOnlyRotatingFileHandler,
count_cache_breakpoints,
log_cache_breakpoints,
)
_CC = {"cache_control": {"type": "ephemeral"}}
def _claude_code_style_request() -> tuple[list[dict], list[dict], list[dict]]:
"""System/messages/tools shaped like a real Claude Code request."""
system = [
{"type": "text", "text": "You are Claude Code."},
{"type": "text", "text": "project instructions", **_CC},
]
tools = [
{"name": "Bash", "input_schema": {}},
{"name": "Read", "input_schema": {}, **_CC},
]
messages = [
{"role": "user", "content": [{"type": "text", "text": "hi", **_CC}]},
{"role": "assistant", "content": [{"type": "text", "text": "ack"}]},
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "t1",
"content": [{"type": "text", "text": "big output"}],
**_CC,
}
],
},
]
return system, messages, tools
def test_count_cache_breakpoints_counts_all_sections() -> None:
system, messages, tools = _claude_code_style_request()
stats = count_cache_breakpoints(system, messages, tools)
assert stats["system"] == 1
assert stats["tools"] == 1
assert stats["messages"] == 2
assert stats["total"] == 4
assert stats["message_count"] == 3
assert stats["last_marker_tail"] == 0 # last message carries a marker
def test_count_cache_breakpoints_counts_nested_tool_result_markers() -> None:
messages = [
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "t1",
"content": [{"type": "text", "text": "out", **_CC}],
}
],
}
]
stats = count_cache_breakpoints("plain system string", messages, None)
assert stats["system"] == 0
assert stats["tools"] == 0
assert stats["messages"] == 1
assert stats["last_marker_tail"] == 0
def test_count_cache_breakpoints_tail_tracks_last_marker() -> None:
messages = [
{"role": "user", "content": [{"type": "text", "text": "a", **_CC}]},
{"role": "assistant", "content": [{"type": "text", "text": "b"}]},
{"role": "user", "content": [{"type": "text", "text": "c"}]},
]
stats = count_cache_breakpoints(None, messages, None)
assert stats["last_marker_tail"] == 2
assert count_cache_breakpoints(None, [], None)["last_marker_tail"] == -1
def test_log_cache_breakpoints_warns_on_dropped_marker(caplog) -> None:
system, messages, tools = _claude_code_style_request()
inbound = count_cache_breakpoints(system, messages, tools)
# Transform "lost" the final breakpoint: strip it from the last message.
stripped = [dict(m) for m in messages]
stripped[2] = {
"role": "user",
"content": [{"type": "tool_result", "tool_use_id": "t1", "content": "compressed"}],
}
outbound = count_cache_breakpoints(system, stripped, tools)
with caplog.at_level(logging.INFO, logger="headroom.proxy"):
log_cache_breakpoints(request_id="r1", inbound=inbound, outbound=outbound)
[record] = caplog.records
assert record.levelno == logging.WARNING
assert "dropped=true" in record.getMessage()
assert "tail_grew=true" in record.getMessage()
def test_log_cache_breakpoints_info_when_preserved(caplog) -> None:
system, messages, tools = _claude_code_style_request()
stats = count_cache_breakpoints(system, messages, tools)
with caplog.at_level(logging.INFO, logger="headroom.proxy"):
log_cache_breakpoints(request_id="r1", inbound=stats, outbound=stats)
[record] = caplog.records
assert record.levelno == logging.INFO
assert "dropped=false" in record.getMessage()
def test_payload_preview_disabled_omits_content(monkeypatch) -> None:
monkeypatch.setenv("HEADROOM_LOG_PAYLOAD_PREVIEW", "0")
payload = "secret file contents: api_key=sk-abcdefghijklmnop"
event = _payload_for_retrieval_log(payload)
assert event["payload_preview"] == ""
assert event["payload_preview_chars"] == 0
assert event["payload_chars"] == len(payload)
assert event["payload_truncated"] is True
def test_payload_preview_disabled_by_default(monkeypatch) -> None:
"""Unset means off: the log gets byte counts, never the content."""
monkeypatch.delenv("HEADROOM_LOG_PAYLOAD_PREVIEW", raising=False)
event = _payload_for_retrieval_log("hello world")
assert event["payload_preview"] == ""
assert event["payload_preview_chars"] == 0
assert event["payload_chars"] == len("hello world")
@pytest.mark.parametrize("value", ["1", "true", "TRUE", "yes", "on"])
def test_payload_preview_opt_in_values(monkeypatch, value: str) -> None:
monkeypatch.setenv("HEADROOM_LOG_PAYLOAD_PREVIEW", value)
assert _payload_for_retrieval_log("hello world")["payload_preview"] == "hello world"
@pytest.mark.parametrize("value", ["", "0", "off", "no", "maybe", " "])
def test_payload_preview_stays_off_for_anything_else(monkeypatch, value: str) -> None:
"""Only an explicit opt-in turns previews on — a typo must not."""
monkeypatch.setenv("HEADROOM_LOG_PAYLOAD_PREVIEW", value)
assert _payload_for_retrieval_log("hello world")["payload_preview"] == ""
def test_append_context_skips_breakpointed_text_block() -> None:
messages = [
{
"role": "user",
"content": [
{"type": "text", "text": "breakpointed", **_CC},
{"type": "text", "text": "free"},
],
}
]
result = AnthropicHandlerMixin._append_context_to_latest_non_frozen_user_turn(
messages, "CTX", frozen_message_count=0
)
blocks = result[0]["content"]
assert blocks[0]["text"] == "breakpointed" # untouched
assert blocks[1]["text"].endswith("CTX")
def test_append_context_no_eligible_block_returns_unchanged() -> None:
messages = [
{
"role": "user",
"content": [{"type": "text", "text": "breakpointed", **_CC}],
}
]
result = AnthropicHandlerMixin._append_context_to_latest_non_frozen_user_turn(
messages, "CTX", frozen_message_count=0
)
assert result == messages
def test_count_cache_breakpoints_tolerates_malformed_shapes() -> None:
messages = [
"not-a-dict",
{"role": "user", "content": ["scalar-block", {"type": "text", "text": "x", **_CC}]},
{"role": "user", "content": "plain string"},
]
stats = count_cache_breakpoints("system-as-string", messages, "tools-as-string")
assert stats["system"] == 0
assert stats["tools"] == 0
assert stats["messages"] == 1
assert stats["message_count"] == 3
assert stats["last_marker_tail"] == 1
empty = count_cache_breakpoints(None, None, None)
assert empty["total"] == 0
assert empty["message_count"] == 0
# --- the runtime log file itself -------------------------------------------
#
# _payload_for_retrieval_log decides what goes into the record;
# _setup_file_logging decides who can read the file it lands in. Both halves
# of the default-off guarantee are checked against a real log on disk.
@contextmanager
def _proxy_log(tmp_path, monkeypatch, port: int):
"""Point the workspace at *tmp_path*, install the real proxy log handler."""
from headroom.proxy.helpers import _PROXY_LOG_HANDLER_NAME, _setup_file_logging
monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
headroom_logger = logging.getLogger("headroom")
before = list(headroom_logger.handlers)
propagate = headroom_logger.propagate
try:
_setup_file_logging(port)
[handler] = [h for h in headroom_logger.handlers if h.name == _PROXY_LOG_HANDLER_NAME]
yield Path(handler.baseFilename)
finally:
for handler in list(headroom_logger.handlers):
if handler not in before:
headroom_logger.removeHandler(handler)
handler.close()
headroom_logger.propagate = propagate
def test_runtime_log_holds_no_payload_text_at_default_settings(tmp_path, monkeypatch) -> None:
"""A retrieval on default settings leaves byte counts in the log, not content."""
from headroom.cache.compression_store import CompressionStore
monkeypatch.delenv("HEADROOM_LOG_PAYLOAD_PREVIEW", raising=False)
secret = "BEGIN-CUSTOMER-DATA ssn=123-45-6789 def sekrit(): pass END-CUSTOMER-DATA"
with _proxy_log(tmp_path, monkeypatch, 18801) as log_path:
store = CompressionStore(enable_feedback=False)
assert store.retrieve(store.store(original=secret, compressed="[compressed]")) is not None
logging.getLogger("headroom").handlers[-1].flush()
text = log_path.read_text(encoding="utf-8")
assert "event=headroom_retrieve" in text, "the retrieval was not logged at all"
assert secret not in text
assert "123-45-6789" not in text
assert f'"payload_chars":{len(secret)}' in text
assert '"payload_preview":""' in text
_posix_only = pytest.mark.skipif(
not fileperms.OWNER_ONLY_SUPPORTED,
reason=(
"asserts POSIX mode bits, which do not control read access on this platform; "
"the scope of the guarantee is asserted instead by "
"test_owner_only_support_matches_what_the_platform_can_enforce and "
"test_no_owner_only_claim_is_made_off_posix"
),
)
@pytest.fixture
def predictable_umask():
"""Pin the umask so "would have been world-readable" is not luck.
Without this the fail-before evidence for these tests depends on whatever
umask the runner happens to have; 0o022 is the stock developer value that
makes an unhardened log 0644.
"""
previous = os.umask(0o022)
try:
yield
finally:
os.umask(previous)
@_posix_only
def test_runtime_log_is_owner_only_with_previews_off(
tmp_path, monkeypatch, predictable_umask
) -> None:
"""The file's permissions are not keyed off the payload-preview switch.
Previews are one of several sources of request content in this file:
``--log-messages`` bodies, wire-debug dumps and query logging land here
too, each behind its own switch. Hardening only when previews are on left
every other combination creating a sensitive log at the umask.
"""
monkeypatch.delenv("HEADROOM_LOG_PAYLOAD_PREVIEW", raising=False)
with _proxy_log(tmp_path, monkeypatch, 18804) as log_path:
assert log_path.exists()
assert stat.S_IMODE(log_path.stat().st_mode) == 0o600
@_posix_only
def test_runtime_log_is_owner_only_when_preview_enabled(tmp_path, monkeypatch) -> None:
"""Opting in to previews hardens the log the previews land in."""
monkeypatch.setenv("HEADROOM_LOG_PAYLOAD_PREVIEW", "1")
with _proxy_log(tmp_path, monkeypatch, 18802) as log_path:
assert log_path.exists()
assert stat.S_IMODE(log_path.stat().st_mode) == 0o600
@_posix_only
def test_runtime_log_hardening_survives_a_pre_existing_world_readable_log(
tmp_path, monkeypatch, predictable_umask
) -> None:
"""O_CREAT's mode does not apply to an existing file; the fchmod must."""
monkeypatch.delenv("HEADROOM_LOG_PAYLOAD_PREVIEW", raising=False)
monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
stale = _paths.proxy_log_path(18803)
stale.parent.mkdir(parents=True, exist_ok=True)
stale.write_text("from an older, unhardened run\n", encoding="utf-8")
stale.chmod(0o644)
with _proxy_log(tmp_path, monkeypatch, 18803) as log_path:
assert stat.S_IMODE(log_path.stat().st_mode) == 0o600
@_posix_only
def test_rotated_backups_are_owner_only(tmp_path, monkeypatch, predictable_umask) -> None:
"""Rotation must not launder the mode away.
``doRollover`` renames the base file and opens a fresh one; a backup that
ends up 0644 exposes exactly the content the base file was protecting, and
keeps exposing it for ``backupCount`` rotations. Exercised through the real
handler the proxy installs (with ``maxBytes`` shrunk so a rollover is
reachable in a test), not a hand-built one, so the handler *selection* is
part of what is asserted.
"""
monkeypatch.delenv("HEADROOM_LOG_PAYLOAD_PREVIEW", raising=False)
with _proxy_log(tmp_path, monkeypatch, 18805) as log_path:
handler = next(
h for h in logging.getLogger("headroom").handlers if h.name == "headroom.proxy.file"
)
handler.maxBytes = 256
for i in range(60):
handler.emit(
logging.LogRecord("headroom", logging.INFO, __file__, i, "x" * 64, None, None)
)
handler.flush()
backups = sorted(log_path.parent.glob(f"{log_path.name}.*"))
assert backups, "no rollover happened — the test did not exercise the path it claims to"
for path in [log_path, *backups]:
assert stat.S_IMODE(path.stat().st_mode) == 0o600, path
@_posix_only
def test_pre_existing_backups_are_tightened_when_the_handler_opens(
tmp_path, predictable_umask
) -> None:
"""Backups written by an older, unhardened build are still on disk."""
log_path = tmp_path / "proxy-18806.log"
stale = tmp_path / "proxy-18806.log.2"
stale.write_text("payload from before the fix\n", encoding="utf-8")
stale.chmod(0o644)
handler = _OwnerOnlyRotatingFileHandler(
log_path, maxBytes=1024, backupCount=5, encoding="utf-8"
)
handler.close()
assert stat.S_IMODE(stale.stat().st_mode) == 0o600
_windows_only = pytest.mark.skipif(
os.name != "nt",
reason="exercises the Windows ACL path specifically",
)
@_windows_only
def test_runtime_log_is_owner_only_via_acl_with_previews_off(tmp_path, monkeypatch) -> None:
"""Windows counterpart of test_runtime_log_is_owner_only_with_previews_off.
Same scenario, checked with verify_owner_only (the DACL) instead of
stat.S_IMODE (mode bits do not apply on Windows either way).
"""
monkeypatch.delenv("HEADROOM_LOG_PAYLOAD_PREVIEW", raising=False)
with _proxy_log(tmp_path, monkeypatch, 18812) as log_path:
assert log_path.exists()
assert fileperms.verify_owner_only(log_path) is True
@_windows_only
def test_rotated_backups_are_owner_only_via_acl(tmp_path, monkeypatch) -> None:
"""Windows counterpart of test_rotated_backups_are_owner_only.
Rotation must not launder the restriction away there either: doRollover
renames the base file (the DACL moves with the rename, same as a POSIX
rename preserves mode bits) and opens a fresh one that must be
independently restricted.
"""
monkeypatch.delenv("HEADROOM_LOG_PAYLOAD_PREVIEW", raising=False)
with _proxy_log(tmp_path, monkeypatch, 18813) as log_path:
handler = next(
h for h in logging.getLogger("headroom").handlers if h.name == "headroom.proxy.file"
)
handler.maxBytes = 256
for i in range(60):
handler.emit(
logging.LogRecord("headroom", logging.INFO, __file__, i, "x" * 64, None, None)
)
handler.flush()
backups = sorted(log_path.parent.glob(f"{log_path.name}.*"))
assert backups, "no rollover happened — the test did not exercise the path it claims to"
for path in [log_path, *backups]:
assert fileperms.verify_owner_only(path) is True, path
@pytest.mark.skipif(
os.name != "posix",
reason="creating a symlink needs elevation on Windows, and O_NOFOLLOW does not exist there",
)
def test_runtime_log_refuses_a_symlinked_path(tmp_path, monkeypatch) -> None:
"""A planted symlink must not redirect the log — or the mode we set on it."""
from headroom.proxy.helpers import _PROXY_LOG_HANDLER_NAME, _setup_file_logging
monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
log_path = _paths.proxy_log_path(18807)
log_path.parent.mkdir(parents=True, exist_ok=True)
elsewhere = tmp_path / "attacker-readable.log"
elsewhere.write_text("", encoding="utf-8")
elsewhere.chmod(0o666)
log_path.symlink_to(elsewhere)
headroom_logger = logging.getLogger("headroom")
before = list(headroom_logger.handlers)
try:
_setup_file_logging(18807)
attached = [h for h in headroom_logger.handlers if h.name == _PROXY_LOG_HANDLER_NAME]
assert not attached, "logging was wired up through the symlink"
logging.getLogger("headroom").info("a record that must not be written")
finally:
for handler in list(headroom_logger.handlers):
if handler not in before:
headroom_logger.removeHandler(handler)
handler.close()
assert elsewhere.read_text(encoding="utf-8") == ""
assert stat.S_IMODE(elsewhere.stat().st_mode) == 0o666, "the symlink target was chmodded"
class _ListHandler(logging.Handler):
def __init__(self) -> None:
super().__init__(logging.DEBUG)
self.records: list[logging.LogRecord] = []
def emit(self, record: logging.LogRecord) -> None:
self.records.append(record)
def _runtime_log_warnings(port: int) -> list[str]:
"""Run ``_setup_file_logging`` and return the 'runtime log disabled' warnings.
The handler sits on ``headroom.proxy`` directly: caplog does not see
``headroom.*`` records once a proxy app has configured logging.
"""
from headroom.proxy.helpers import _setup_file_logging
proxy_logger = logging.getLogger("headroom.proxy")
headroom_logger = logging.getLogger("headroom")
before = list(headroom_logger.handlers)
capture = _ListHandler()
proxy_logger.addHandler(capture)
try:
_setup_file_logging(port)
finally:
proxy_logger.removeHandler(capture)
for handler in list(headroom_logger.handlers):
if handler not in before:
headroom_logger.removeHandler(handler)
handler.close()
return [
r.getMessage()
for r in capture.records
if r.levelno == logging.WARNING and "runtime log disabled" in r.getMessage()
]
def test_runtime_log_says_why_it_is_missing(tmp_path, monkeypatch) -> None:
"""An unwritable log directory used to disable proxy.log without a word."""
monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
# A regular file where the logs directory belongs: mkdir raises OSError.
_paths.log_dir().write_text("", encoding="utf-8")
warnings = _runtime_log_warnings(18808)
assert len(warnings) == 1
assert str(_paths.log_dir()) in warnings[0]
assert "HEADROOM_WORKSPACE_DIR" in warnings[0]
def test_runtime_log_stays_quiet_when_writable(tmp_path, monkeypatch) -> None:
monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
assert _runtime_log_warnings(18809) == []
assert _paths.proxy_log_path(18809).exists()
@pytest.mark.skipif(
os.name != "posix",
reason="creating a symlink needs elevation on Windows, and O_NOFOLLOW does not exist there",
)
def test_open_owner_only_fails_closed_on_a_symlink(tmp_path) -> None:
"""The kernel-enforced half of the same refusal, at the open() itself."""
target = tmp_path / "target"
target.write_text("", encoding="utf-8")
link = tmp_path / "link"
link.symlink_to(target)
with pytest.raises(OSError):
fileperms.open_owner_only(link).close()
def _try_symlink(link: Path, target: Path) -> None:
"""Create a real symlink, or skip with an explicit reason.
Unprivileged symlink creation on Windows needs Developer Mode; a CI
runner without it would otherwise either silently skip this test's
actual point or crash on the OSError from symlink_to itself. Skipping
explicitly, with the reason, is the point: a runner that cannot create
symlinks must say so rather than have this look covered by the ACL
assertions elsewhere in this file, which exercise a different thing.
"""
try:
link.symlink_to(target)
except OSError as exc:
pytest.skip(
f"cannot create a symlink on this runner ({exc}); needs Developer Mode on Windows"
)
@_windows_only
def test_open_owner_only_redirect_blocker_regression(tmp_path) -> None:
"""Regression for a real Windows finding: open_owner_only followed a
planted symlink to its target instead of refusing it.
Plain os.open() on Windows has no O_NOFOLLOW equivalent, so it silently
followed the link; a DACL applied afterward (restrict_fd_to_owner) then
landed on the target, not the intended file, and content written
through the "log" landed there too -- a real redirect, independently
reproduced, not a theoretical one. open_owner_only now opens through
headroom._fileperms_windows.open_no_follow instead, which refuses a
reparse point outright. Covers both modes open_owner_only supports:
append (what the proxy log actually uses) and truncate.
"""
target = tmp_path / "ORIGINAL"
target.write_text("ORIGINAL", encoding="utf-8")
link = tmp_path / "log.txt"
_try_symlink(link, target)
with pytest.raises(OSError):
fileperms.open_owner_only(link, "a").close()
assert target.read_text(encoding="utf-8") == "ORIGINAL", "append mode wrote through the symlink"
with pytest.raises(OSError):
fileperms.open_owner_only(link, "w").close()
assert target.read_text(encoding="utf-8") == "ORIGINAL", (
"truncate mode wrote through the symlink"
)
@_windows_only
def test_runtime_log_refuses_a_symlinked_path_on_windows(tmp_path, monkeypatch) -> None:
"""Windows counterpart of test_runtime_log_refuses_a_symlinked_path."""
from headroom.proxy.helpers import _PROXY_LOG_HANDLER_NAME, _setup_file_logging
monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
log_path = _paths.proxy_log_path(18814)
log_path.parent.mkdir(parents=True, exist_ok=True)
elsewhere = tmp_path / "attacker-readable.log"
elsewhere.write_text("", encoding="utf-8")
_try_symlink(log_path, elsewhere)
headroom_logger = logging.getLogger("headroom")
before = list(headroom_logger.handlers)
try:
_setup_file_logging(18814)
attached = [h for h in headroom_logger.handlers if h.name == _PROXY_LOG_HANDLER_NAME]
assert not attached, "logging was wired up through the symlink"
logging.getLogger("headroom").info("a record that must not be written")
finally:
for handler in list(headroom_logger.handlers):
if handler not in before:
headroom_logger.removeHandler(handler)
handler.close()
assert elsewhere.read_text(encoding="utf-8") == ""
@_posix_only
def test_jsonl_request_log_is_owner_only(tmp_path, predictable_umask) -> None:
"""``--log-file`` with ``--log-messages`` writes whole bodies to this file."""
from headroom.proxy.models import RequestLog
from headroom.proxy.request_logger import RequestLogger
log_file = tmp_path / "requests.jsonl"
entry = RequestLog(
request_id="r1",
timestamp="2026-09-23T00:00:00Z",
provider="anthropic",
model="claude-opus-4-20250514",
input_tokens_original=10,
input_tokens_optimized=8,
output_tokens=2,
tokens_saved=2,
savings_percent=20.0,
optimization_latency_ms=1.0,
total_latency_ms=2.0,
tags={},
cache_hit=False,
transforms_applied=[],
request_messages=[{"role": "user", "content": "ssn=123-45-6789"}],
)
RequestLogger(log_file=str(log_file), log_full_messages=True).log(entry)
assert "123-45-6789" in log_file.read_text(encoding="utf-8")
assert stat.S_IMODE(log_file.stat().st_mode) == 0o600
# --- what the guarantee is, and is not, on Windows -------------------------
def test_owner_only_support_matches_what_the_platform_can_enforce() -> None:
"""The scope is a value in the code, not a claim in a comment.
POSIX mode bits decide read access; on Windows an NTFS ACL does, and
``os.chmod`` there only flips the read-only attribute — a
``chmod(0o600)`` succeeds while ``stat.S_IMODE`` still reports ``0666``.
Python ships no ACL API, so Headroom reports that it cannot make the
promise instead of making it and not keeping it.
"""
assert fileperms.OWNER_ONLY_SUPPORTED is (os.name == "posix")
@pytest.mark.skipif(
fileperms.OWNER_ONLY_SUPPORTED,
reason="exercises the non-mode-bits path; only meaningful off POSIX",
)
def test_windows_acl_restricts_even_though_mode_bits_do_not(tmp_path) -> None:
"""On Windows the handler still logs, and is restricted by ACL, not mode.
``OWNER_ONLY_SUPPORTED`` (mode bits decide access) stays ``False`` here —
that is still true, Windows mode bits never controlled read access. What
changed is that :func:`restrict_path_to_owner` no longer gives up just
because mode bits do not apply: it restricts the DACL instead, and
:func:`verify_owner_only` confirms it by re-reading that DACL rather than
trusting the call's own return value.
"""
log_path = tmp_path / "proxy-18808.log"
handler = _OwnerOnlyRotatingFileHandler(
log_path, maxBytes=1024, backupCount=1, encoding="utf-8"
)
handler.close()
assert log_path.exists(), "logging must keep working regardless of the ACL outcome"
assert fileperms.restrict_path_to_owner(log_path) is True
assert fileperms.verify_owner_only(log_path) is True
def test_unsupported_platform_says_so_rather_than_silently_not_protecting(
tmp_path, monkeypatch
) -> None:
"""Covers the case where no protection mechanism works at all — mode bits
don't apply (as on Windows) and, simulated here via ``verify_owner_only``,
neither does the ACL call (a non-NTFS volume, a missing privilege). Runs
on every platform: POSIX gets there because ``verify_owner_only`` is
forced to report failure directly; Windows can get there for real.
A control that quietly does nothing is the thing to avoid, so the
operator is told once per process.
"""
from headroom.proxy import helpers as _helpers
monkeypatch.setattr(fileperms, "OWNER_ONLY_SUPPORTED", False)
monkeypatch.setattr(fileperms, "verify_owner_only", lambda path: False)
monkeypatch.setattr(_helpers, "_owner_only_warning_emitted", False)
monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path))
records: list[logging.LogRecord] = []
sink = logging.Handler()
sink.emit = records.append # type: ignore[method-assign]
emitter = logging.getLogger(_helpers.logger.name)
emitter.addHandler(sink)
headroom_logger = logging.getLogger("headroom")
before = list(headroom_logger.handlers)
try:
_helpers._setup_file_logging(18809)
finally:
emitter.removeHandler(sink)
for handler in list(headroom_logger.handlers):
if handler not in before:
headroom_logger.removeHandler(handler)
handler.close()
warnings = [r for r in records if r.levelno == logging.WARNING]
assert warnings, "the unprotected file was not reported at all"
message = warnings[0].getMessage()
assert "could not restrict" in message
assert "proxy-18809.log" in message
# And only once per process, so it is a notice and not a per-worker flood.
assert _helpers._owner_only_warning_emitted is True