docs: record task 2 hardening verification

2026-08-04 14:55:59 +02:00
parent 2ce2e0089a
commit 01633be8f6
1 changed files with 72 additions and 0 deletions
@@ -73,3 +73,75 @@ commands can validate the required Git-remote interpolation without an operator

 None for Task 2. Git and connector secret transport remains intentionally outside this base/profile
 contract and is addressed by the next scoped task.
+
+---
+
+## Fix round 1/5 — Pi auth mount and generic LLM endpoint
+
+### Status
+
+Completed. Pi’s mutable state remains writable, while provider authentication is supplied only by
+the deterministic `PI_AUTH_FILE` host-file contract mounted read-only at Pi’s canonical
+`/home/thoth/.pi/agent/auth.json` path. The base now exposes the generic `THT_LLM_URL` contract;
+the local and server examples set only documentation endpoint values.
+
+### Changed files
+
+- `compose.yaml` — adds `THT_LLM_URL` and a read-only `PI_AUTH_FILE` bind while retaining the
+  writable `pi-state` volume for non-secret runtime state.
+- `deploy/compose.server.yaml` — retains the auth-file bind when its storage mounts override the
+  portable base.
+- `.env.example`, `deploy/env/local.env.example`, and `deploy/env/server.env.example` — document
+  the generic `https://llm.example.invalid` endpoint; profile examples also document the required
+  host auth-file path without including a secret.
+- `scripts/test-unified-compose.sh` — asserts generic LLM contract presence, no Docker
+  socket/daemon mount, and exactly one read-only Pi auth file bind in the base and both profiles.
+
+### RED evidence
+
+Before the Compose changes, this command exited 1:
+
+```text
+bash scripts/test-unified-compose.sh
+
+Error: core must expose a generic THT_LLM_URL endpoint contract
+```
+
+The failure was raised by the new structural assertion against the previous rendered base.
+
+### GREEN evidence
+
+The following focused commands completed with exit status 0 after the fix:
+
+```text
+bash scripts/test-unified-compose.sh
+# unified Compose contract passed.
+
+bash scripts/test-default-compose.sh
+# default Compose contract passed.
+
+docker compose --env-file deploy/env/local.env.example -f compose.yaml -f deploy/compose.local.yaml config --quiet
+
+docker compose --env-file deploy/env/server.env.example -f compose.yaml -f deploy/compose.server.yaml config --quiet
+
+bash scripts/verify-line-endings.sh
+git diff --check
+```
+
+### Self-review
+
+- Both rendered profile contracts carry a single `bind` mount to the Pi `auth.json` file with
+  `read_only: true`; no auth value appears in Compose or the environment examples.
+- The writable Pi-state mount does not replace the read-only auth file, and the server override
+  explicitly retains that file bind after replacing the base storage list.
+- The structural regression test rejects any Docker socket/daemon mount and validates the generic
+  LLM endpoint contract without adding provider-specific endpoints or hostnames.
+- The deferred Minor report-wording finding was not changed.
+
+### Commit
+
+`2ce2e0089a66ca508db041a71db9807f66d0bf24` — `fix: harden compose Pi auth mounts`
+
+### Concerns
+
+None for this focused round.