diff --git a/.forgejo/workflows/ci.yml b/.forgejo/workflows/ci.yml index 2c7b43b..971806c 100644 --- a/.forgejo/workflows/ci.yml +++ b/.forgejo/workflows/ci.yml @@ -1,5 +1,13 @@ -# Forgejo Actions CI. Runs only once an Actions runner is registered with this -# label (see docs/DEVELOPMENT.md). It mirrors the local quality gates. +# Forgejo Actions CI. +# +# This workflow mirrors the local quality gates exactly and is deliberately +# fail-closed: a required check that cannot run because a tool is missing fails +# the job rather than printing "skipping". A green job therefore means every +# listed check actually executed. +# +# The Rust toolchain is pinned in `installer-rs/rust-toolchain.toml`. The runner +# must provide either `rustup` (which installs the pin) or a cargo/rustfmt/clippy +# toolchain; the preflight below fails clearly otherwise. # # If your runner uses different labels, change `runs-on` accordingly. name: ci @@ -9,32 +17,35 @@ on: branches: [main] pull_request: +concurrency: + group: ci-${{ github.ref }} + cancel-in-progress: true + jobs: - test: + quality-gates: runs-on: ubuntu-latest + timeout-minutes: 60 steps: - uses: actions/checkout@v4 - - name: Rust format + - name: Provision the pinned Rust toolchain run: | - if command -v cargo >/dev/null 2>&1; then - cd installer-rs && cargo fmt --all -- --check + set -euo pipefail + if command -v rustup >/dev/null 2>&1; then + rustup show active-toolchain + rustup component add rustfmt clippy + rustup target add x86_64-unknown-linux-gnu + elif command -v cargo >/dev/null 2>&1; then + cargo --version + cargo fmt --version + cargo clippy --version else - echo "cargo not installed on this runner; skipping" + echo "ERROR: no Rust toolchain on this runner." >&2 + echo "Install rustup (recommended, honours the pinned toolchain) or" >&2 + echo "provide cargo with the rustfmt and clippy components, then retry." >&2 + exit 1 fi - - name: Rust clippy - run: | - if command -v cargo >/dev/null 2>&1; then - cd installer-rs && cargo clippy --workspace --all-targets - else - echo "cargo not installed on this runner; skipping" - fi - - - name: Rust test suite - run: | - if command -v cargo >/dev/null 2>&1; then - cd installer-rs && cargo test --workspace - else - echo "cargo not installed on this runner; skipping" - fi + # One command for the whole gate set, identical to local development. + - name: Quality gates (fmt, clippy, tests, harness tests, builds) + run: make ci diff --git a/.gitignore b/.gitignore index 82cf140..98c1b0c 100644 --- a/.gitignore +++ b/.gitignore @@ -38,3 +38,8 @@ credentials installer/live/build/ installer/live/*.iso installer/live/*.iso.sha256 + +# --- Release verification reports and logs (regenerated; not source) -------- +gate-report*.json +gate-logs/ +*.minisig diff --git a/Makefile b/Makefile index b3a11d2..871bcdf 100644 --- a/Makefile +++ b/Makefile @@ -8,7 +8,10 @@ SHELL := /bin/bash -.PHONY: help context doctor test test-rust test-vm opencode-acceptance fmt fmt-check clippy check build static vm hooks commit publish backup forgejo-init public private protect release clean +# The release tool produced by `make build`, used by `make release-gates`. +RELEASE ?= installer-rs/target/release/phoebus-release + +.PHONY: help context doctor test test-rust test-vm ci opencode-acceptance fmt fmt-check clippy check build static release-gates vm hooks commit publish backup forgejo-init public private protect release clean help: @printf 'Phoebus OS targets:\n' @@ -17,6 +20,8 @@ help: @printf ' make test run the Rust and VM-harness test suites\n' @printf ' make test-rust cargo test --workspace\n' @printf ' make test-vm python3 installer/tests/vm/test_vmsafety.py\n' + @printf ' make ci every CI quality gate (fmt, clippy, tests, builds)\n' + @printf ' make release-gates run the executable release gates (evidence report)\n' @printf ' make opencode-acceptance live-model acceptance (needs PHOEBUS_OPENCODE_LIVE_*)\n' @printf ' make fmt cargo fmt --all\n' @printf ' make check fmt-check + clippy + tests\n' @@ -40,11 +45,15 @@ doctor: test: test-rust test-vm test-rust: - cd installer-rs && cargo test --workspace + cd installer-rs && cargo test --workspace --locked test-vm: python3 installer/tests/vm/test_vmsafety.py +# The complete set of required CI gates. Every target here must actually run; +# the workflow fails the job if a prerequisite is missing rather than skipping. +ci: fmt-check clippy test-rust test-vm build static + # A real-model acceptance run. Fails (BLOCKED) when the live server is not # configured, so it can never pass by silently not running. opencode-acceptance: @@ -53,7 +62,7 @@ opencode-acceptance: exit 2; \ fi cd installer-rs && PHOEBUS_OPENCODE_REQUIRE_LIVE=1 \ - cargo test -p phoebus-executor --test opencode_live -- --nocapture + cargo test -p phoebus-executor --test opencode_live --locked -- --nocapture fmt: cd installer-rs && cargo fmt --all @@ -62,16 +71,22 @@ fmt-check: cd installer-rs && cargo fmt --all -- --check clippy: - cd installer-rs && cargo clippy --workspace --all-targets + cd installer-rs && cargo clippy --workspace --all-targets --locked check: fmt-check clippy test build: - cd installer-rs && cargo build --release -p phoebus-installer + cd installer-rs && cargo build --release -p phoebus-installer --locked static: cd installer-rs && RUSTFLAGS="-C target-feature=+crt-static" \ - cargo build --release -p phoebus-installer --target x86_64-unknown-linux-gnu + cargo build --release -p phoebus-installer --target x86_64-unknown-linux-gnu --locked + +# Run the executable release gates and write an evidence-bound report. Host +# gates run here; VM/seat/model gates require their environment and are +# recorded as blocked, never silently passed. +release-gates: build + $(RELEASE) gates --execute --output gate-report.json hooks: scripts/setup-hooks.sh diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index fd67700..06ff35e 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -8,6 +8,27 @@ Format: Keep a Changelog. Dates are UTC. ## Unreleased ### Added +- **Fail-closed CI with a full gate set.** `.forgejo/workflows/ci.yml` now runs + one command, `make ci` (fmt-check, clippy, workspace tests, VM-harness safety + tests, release build, static installer build). It provisions the pinned + toolchain or fails with a clear message; a missing Cargo/rustfmt/clippy is + never reported as a pass. The toolchain is pinned in + `installer-rs/rust-toolchain.toml` and dependencies are checked with + `--locked`. See ADR 0012. +- **Executable, evidence-bound release gates.** `phoebus-release gates` now + records `passed`/`failed`/`blocked`/`skipped`/`not_run` (only `passed` is a + pass), actually runs host gates, and imports evidence from the existing VM + harness `results.json` (`--harness-results`) instead of a competing harness. + `--candidate` binds the report to an artifact digest, and the harness records + the digest it verified from `PHOEBUS_VM_ARTIFACT[_SHA256]`, so stale evidence + is refused. Gates without automation (`no-model-recovery`, + `updates-and-rollback`, `desktop-session`) are always `blocked`. +- **Publication authorization.** `phoebus-release publish` refuses unless the + report is bound to the exact candidate digest, every gate passed, the + candidate matches its manifest, and a detached signature verifies. Check + failures happen before the destination is touched, and `atomic_publish` + restores the previous release if the final rename fails. + - **Real OpenCode agent-server adapter.** `phoebus-executor::opencode_client` implements the OpenCode session/message protocol over the project's curl transport and the `ModelTransport` trait, so the strict proposal parser, @@ -34,6 +55,10 @@ Format: Keep a Changelog. Dates are UTC. selection (`ai.backend`) in canonical configuration. ### Security +- **Release evidence cannot be replayed across builds.** A gate report and + imported harness evidence are bound to a candidate name and SHA-256; a report + for a different digest (or unbound evidence) fails rather than authorizing a + publication. - **The mandatory-AI gate now requires a validated interaction.** Both the GUI bridge and the installer CLI refuse to install when only a provider name is configured; a successful, validated model interaction bound to the current diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index 7cc1f39..db0fafd 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -230,10 +230,48 @@ prerequisites, and `make test`, `make check`, `make build`, `make static`, ## Continuous integration -`.forgejo/workflows/ci.yml` mirrors the local gates (`cargo fmt`, `cargo clippy`, -`cargo test`). It runs only once a Forgejo Actions runner is registered for the -repository; see Forgejo's documentation for `act_runner`. Until then, run -`make test` before pushing. +`.forgejo/workflows/ci.yml` runs the same checks as `make ci`: + +```sh +make ci # fmt-check, clippy, test-rust, test-vm, build, static +``` + +The workflow is **fail-closed**: it provisions the pinned toolchain +(`installer-rs/rust-toolchain.toml`) or fails with a clear message, so a missing +Cargo/rustfmt/clippy is never reported as a pass. Dependencies are checked +against the committed `Cargo.lock` (`--locked`). + +It runs only once a Forgejo Actions runner is registered for the repository; see +Forgejo's documentation for `act_runner`. Until then, run `make ci` before +pushing. A runner that uses different labels needs its `runs-on` value updated. + +## Release verification + +`phoebus-release` writes an evidence-bound gate report and refuses to publish +without one (ADR 0012): + +```sh +# Host gates run here; VM/seat/model gates are imported from existing harness +# results and are `blocked` without evidence. +make release-gates +installer-rs/target/release/phoebus-release gates --execute \ + --candidate /path/phoebus-installer-amd64.iso \ + --harness-results /var/tmp/phoebus-vm + +# Publication requires: a candidate-bound all-passed report, a matching +# manifest, and a verified detached signature. +installer-rs/target/release/phoebus-release publish \ + /path/phoebus-installer-amd64.iso /srv/releases/latest.iso \ + --gate-report gate-report.json --manifest /path/phoebus-release.json \ + --signature /path/phoebus-installer-amd64.iso.minisig +``` + +Gate outcomes are `passed`, `failed`, `blocked`, `skipped` and `not_run`; only +`passed` is a pass. A report for one artifact digest cannot authorize another +(`--candidate` binds the report; the harness records the digest it verified from +`PHOEBUS_VM_ARTIFACT[_SHA256]`). `no-model-recovery`, `updates-and-rollback` and +`desktop-session` have no automated harness yet, so they stay explicitly +`blocked` until one exists. ## Backups @@ -247,7 +285,6 @@ Restore with `git clone /path/to/phoebus-.bundle phoebus_os`. ## Quality gates before commit -1. `make test` (`cd installer-rs && cargo test --workspace`) -2. `cargo fmt --all -- --check` and `cargo clippy --workspace --all-targets` -3. Update `docs/CHANGELOG.md` and `docs/STATUS.md` when behavior changes. -4. Commit (see `docs/GIT-WORKFLOW.md`). +1. `make ci` (the complete gate set the CI workflow runs) +2. Update `docs/CHANGELOG.md` and `docs/STATUS.md` when behavior changes. +3. Commit (see `docs/GIT-WORKFLOW.md`). diff --git a/docs/GIT-WORKFLOW.md b/docs/GIT-WORKFLOW.md index ed23857..b25c10d 100644 --- a/docs/GIT-WORKFLOW.md +++ b/docs/GIT-WORKFLOW.md @@ -117,11 +117,10 @@ a staged file is too large, then runs the fast tests. 1. scans staged files for secrets (`scripts/check-secrets.sh`); 2. blocks staged `*.iso`, `*.qcow2` and files larger than 5 MiB; -3. runs the fast Bash test suite. +3. optionally runs the Rust suite (set `PHOEBUS_PRECOMMIT_RUST=1` to enable). Bypass for a genuine emergency with `git commit --no-verify`, or set -`SKIP_PHOEBUS_HOOKS=1`. Set `PHOEBUS_PRECOMMIT_RUST=1` to also run -`cargo test --workspace` in the hook. +`SKIP_PHOEBUS_HOOKS=1`. ## Repository settings and hardening @@ -136,13 +135,17 @@ Current state: `enable DEST` at a synced/remote folder for a genuinely off-box copy, since the only git remote is one VPS. -### CI runner (optional) +### CI runner (recommended) -`.forgejo/workflows/ci.yml` mirrors the local gates but only runs once a -Forgejo Actions runner is registered. Install `act_runner` on a machine, +`.forgejo/workflows/ci.yml` runs `make ci` (fmt, clippy, workspace tests, +VM-harness safety tests, release build, static installer build). It is +fail-closed: if the runner lacks a Rust toolchain it fails the job rather than +skipping checks, so a green result always means the checks ran. It runs once a +Forgejo Actions runner is registered; install `act_runner` on a machine, register it (Site Administration -> Actions -> Runners, or `act_runner register --instance https://git.phoebus.club --token `), and -run it as a service. Until then, run `make test` before pushing. +run it with a `rustup`-provisioned toolchain (or cargo + rustfmt + clippy). +Until then, run `make ci` before pushing. ### Commit signing (optional) diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md index 4a7a7a9..e3a7ed2 100644 --- a/docs/HANDOFF.md +++ b/docs/HANDOFF.md @@ -3,36 +3,43 @@ Rolling note between work sessions. **Update this file before you finish**, then commit it. It should be short and current; use `git log` for detail. -- **Last updated:** this session (2026-09-22), OpenCode adapter. -- **Current focus:** Implemented a real OpenCode agent-server adapter - (`phoebus-executor::opencode_client`) that speaks the session/message protocol - over curl and implements `ModelTransport`, wired into canonical config - (`ai.backend = "opencode"`), the GUI ("OpenCode agent" + Test connection), - the installer CLI (`--ai-backend opencode`, `--opencode-test`) and `sys ask`. - The mandatory-AI gate now requires a validated interaction with invalidated - state. The probe/transport were hardened (loopback/TLS policy, DNS pinning, - status checks, auth), and the GUI harness gained exact-session and - frontend-state assertions. +- **Last updated:** this session (2026-09-22), CI and release verification + hardening (branch `codex/harden-ci-release-verification`). +- **Current focus:** Made CI and release verification mean what they claim. + (1) `.forgejo/workflows/ci.yml` is fail-closed: it provisions the pinned + toolchain or fails, and runs one `make ci` (fmt-check, clippy, workspace + tests, VM-harness safety tests, release build, static installer build). + `installer-rs/rust-toolchain.toml` pins stable 1.93.1; all cargo gates use + `--locked`. (2) `phoebus-release` gate statuses are now + `passed`/`failed`/`blocked`/`skipped`/`not_run` (only `passed` is a pass); + host gates execute real commands; VM/seat/model gates import the existing VM + harness `results.json` (`--harness-results`). (3) Gate reports and harness + evidence are bound to a candidate name+SHA-256 (`--candidate`; + `PHOEBUS_VM_ARTIFACT[_SHA256]`), so stale evidence cannot authorize another + build. (4) `publish` refuses unless the report is candidate-bound and + all-passed, the manifest verifies the artifact and a detached signature + verifies; `atomic_publish` restores the previous release on failure. - **Last verified (this session):** - - 336 Rust tests + 16 harness tests green; fmt/clippy clean. - - Real inference through `opencode 1.18.32` with `deepseek-v4-flash`; - `--opencode-test` → `{"phoebus":"ok"}`; the GUI bridge `ai_check` applied 8 - reviewed changes; `sys ask` proposed and ran a read-only action. - - Auth: none → `authentication_required`, wrong → `authentication_rejected`, - correct → `model_catalog` + successful inference. Plain http to a LAN host - → `insecure_transport`, exit 1, no request sent. - - 7 real-HTTP integration tests (status, chunked multibyte, oversize, - redirect, disconnect, auth) and 2 env-gated live tests. - - GUI acceptance in a disposable VM: `gui-driver.py opencode` passed 17/17 - (selected OpenCode, entered the endpoint/model through the UI, real model - response + validated proposal); `gui-driver.py gui` passed 25/25. - ISO `sha256 4db98db3…`, static binary `sha256 72c2dcd0…`. -- **Not yet verified this session:** the full graphical **installation** through - OpenCode past the AI gate (disk/account/review/ERASE/install/detached boot), - and a separate physical computer. The pinned manifest is `v1.18.31` while the - tested binary is `1.18.32`. On this server use `deepseek-flash`; the model - must match the server's catalog (the GUI default `deepseek-chat` does not - exist on it). + - 364 Rust tests + 19 harness tests green; `cargo fmt --all -- --check` and + `cargo clippy --workspace --all-targets` clean (exit 0); `make ci` exit 0. + - Release build and static installer build succeed; the static binary is + `static-pie linked` (4.99 MB). + - New regression tests (20 Rust + 3 Python) cover: absent prerequisites are + `blocked`; a failed host gate is `failed` with diagnostics; explicit skips + and `--only` are never passes; manual gates are `blocked`; stale or + unbound harness evidence is `failed`; `publish` refuses on not-run gates, + unbound/stale reports, missing manifest, manifest mismatch, missing or + failing signature, and a failed publication leaves the previous release + intact. + - CLI smoke: `gates` (all `not_run`), `gates --execute --only rust-fmt` + (executes and reports `passed`), harness-evidence import (`install` + `passed`), and `publish` refusal on an unbound report. +- **Not yet verified this session:** no Forgejo Actions runner is registered, + so the workflow is unexecuted. The VM, graphical-seat and live-model gates + are `blocked` here (no disposable VM/model in this environment). + `no-model-recovery`, `updates-and-rollback` and `desktop-session` have no + automated harness yet and are always `blocked`, so a full publication is not + possible until they are automated (intentional: no false pass). - **Public repo:** (remote `origin`, SSH port 2222). @@ -55,11 +62,24 @@ commit it. It should be short and current; use `git log` for detail. 5. **Physical-seat desktop**: run `phoebus-session` on a real VT/seat and check `phoebus-menu`, `phoebus-lock`, `phoebus-idle`, kitty, XWayland, the polkit agent, logout/reap and reboot (`docs/DEVELOPMENT.md`). -6. **Release gates on a CI runner**: `phoebus-release gates --execute` and - `publish` once a runner exists; no gate has executed. +6. **Register a Forgejo Actions runner** and confirm `make ci` runs green + there; no runner is registered, so `.forgejo/workflows/ci.yml` is + unexecuted. `make ci` passes locally, but that is not CI verification. +7. **Automate the three blocked release gates**: `no-model-recovery`, + `updates-and-rollback` and `desktop-session` have no harness scenario yet, + so they are always `blocked` and a full publication is impossible. Add + harness modes (or reviewed manual evidence) and re-run + `make release-gates`. ## Known blockers / risks +- **No Forgejo Actions runner is registered**, so `.forgejo/workflows/ci.yml` + is unexecuted; `make ci` is green locally only. Registering an `act_runner` + with a rustup toolchain is the external prerequisite (ADR 0012). +- **A full release cannot be authorized yet**: `no-model-recovery`, + `updates-and-rollback` and `desktop-session` have no automated harness, so + the gate report is never all-passed. This is deliberate until they are + automated. - No live DeepSeek/OpenAI key and no local model are available; the **full GUI install past the AI step** and two fresh-disk graphical installs are NOT verified (normal installation requires a connected model). The AI step is diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index e7fc626..ed58260 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -18,7 +18,7 @@ more interesting. Status vocabulary: **Done**, **Partial**, **Next**, **Later**. | 11 | AI privilege and privacy architecture | Partial | typed actions + enforced privacy boundary + guided proposal review + OS-level sandbox (systemd-run hardening) + approval-bound resolved effects; live call/sandbox not VM-verified | | 12 | `sys` operations | Partial | history, enable/disable, inspect, install, prepare-updates VM-verified; `undo`, `undo status`, `ask` added (unit-tested, VM gate pending) | | 13 | Kernel optimization policy | Later | conservative fragments only; SAFE/OPTIMIZED/AGGRESSIVE selection exists | -| 14 | ISO / release pipeline | Partial | manifest/verify/assemble-plan tooling; release gates, atomic publish and signing helpers added; no CI runner has executed a gate | +| 14 | ISO / release pipeline | Partial | manifest/verify/assemble tooling; executable evidence-bound gates + publication authorization (ADR 0012); no CI runner has executed a gate | | 15 | Recovery environment | Later | recovery BLS entry generated; snapshot-based recovery entry written at install; full recovery image not built | | — | Rust TUI | Partial | ratatui UI with plan/ERASE and AI provider selection; not yet the default on all paths | | — | Graphical installer (welcome + wizard) | Partial | Quickshell/QML over the typed `--gui-bridge`; live graphical VM verified, including a detached install+boot; live AI call pending (ADR 0010) | diff --git a/docs/STATUS.md b/docs/STATUS.md index 359d1d7..ac2ea0f 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -94,7 +94,7 @@ still not VM-verified. | Live desktop ISO (Mango + DMS) | yes | guards tested | graphical VM + GUI journey + detached boot | no | | Live welcome autostart + duplicate prevention | yes | guards tested | live graphical VM | no | | Welcome primary action keyboard-focus | yes | guards tested | live graphical VM | no | -| VM harness disk safety + structured results | yes | yes (16 tests) | n/a | n/a | +| VM harness disk safety + structured results + artifact binding | yes | yes (19 tests) | n/a | n/a | | Target disk revalidation before partition | yes | yes | no | n/a | | Bridge replay/concurrency + input bounds | yes | yes | no | n/a | | Provider transport endpoint/size hardening | yes | yes | no | n/a | @@ -105,7 +105,10 @@ still not VM-verified. | OpenCode full graphical install | yes | yes | AI gate passed; install not run | n/a | | Mandatory AI requires a validated interaction | yes | yes | bridge + CLI | n/a | | GURU packaging (scoped keywords) | yes | yes | no (build/install unverified) | no | -| Release gates + atomic publish | yes | yes | no | n/a | +| Fail-closed CI (`make ci`, pinned toolchain) | yes | yes (`make ci` green locally) | no runner registered | n/a | +| Executable release gates + evidence-bound publish | yes | yes | no (no VM/model here) | n/a | +| Harness evidence import + stale-evidence refusal | yes | yes | no | n/a | +| Atomic publish + previous-release preservation | yes | yes | no | n/a | | `sys` verbs | yes | yes | yes | no | | OpenCode pinned bootstrap | yes | yes | no | n/a | | Release manifest/verify | yes | yes | no | n/a | @@ -160,9 +163,19 @@ still not VM-verified. the argv level) and fails closed without `systemd-run`; it has not been exercised in a VM. Only typed actions and the privacy boundary were previously enforced. -- **Release automation** now has gates, a report, atomic publish and signing - command helpers, but no gate has been executed by a configured CI runner; the - report records unexecuted gates as `NotRun`. +- **Release gates are executable and evidence-bound (ADR 0012).** `make ci` + runs fmt/clippy/tests/harness-tests/builds and is fail-closed. `phoebus-release + gates --execute` runs host gates and imports VM/seat/model evidence from the + existing harness `results.json`; unexecuted, blocked or skipped gates are + never passes. `publish` refuses unless the report is bound to the exact + candidate digest, every gate passed, the manifest verifies the artifact and a + detached signature verifies. **No CI runner is registered**, so the workflow + itself is unexecuted; the VM, graphical-seat and live-model gates are + **blocked** here (no disposable VM or model in this environment). + `no-model-recovery`, `updates-and-rollback` and `desktop-session` have no + automated harness yet and are always `blocked`, so a full release cannot be + authorized until they are automated (or given reviewed manual evidence). That + is intentional: no false pass. - The desktop transaction compiles heavily because desktop USE does not match the signed binhost (~26 min for the desktop set on 8 vCPUs in the test VM). The official Gentoo binhost is OpenRC/hardened, so a systemd system can only diff --git a/docs/adr/0012-release-verification-and-publication.md b/docs/adr/0012-release-verification-and-publication.md new file mode 100644 index 0000000..045e6b2 --- /dev/null +++ b/docs/adr/0012-release-verification-and-publication.md @@ -0,0 +1,78 @@ +# ADR 0012: Release verification evidence and publication authorization + +- **Status:** Accepted +- **Date:** 2026-09-22 + +## Context + +Two failure modes made a passing result meaningless: + +1. **CI skipped required checks.** `.forgejo/workflows/ci.yml` wrapped every + Rust step in `if command -v cargo; then ...; else echo "skipping"; fi`. A + runner without Cargo reported green while running nothing. +2. **Release gates did not execute and were not bound to an artifact.** + `phoebus-release gates --execute` ran no command (there were no host gates, + and every non-host gate was recorded `not_run`). `publish` accepted any + report whose results were all `passed`, without checking that the report + described the artifact being published, that the artifact matched its + manifest, or that a signature had been verified. A stale report for an old + build could therefore authorize a different one. + +The project already has a disposable VM harness (`installer/tests/vm/*.py`) +that writes structured `results.json`. A second, competing harness is not +wanted. + +## Decision + +1. **CI is fail-closed.** The workflow provisions the pinned toolchain or fails + with a clear message; it never treats a missing prerequisite as a pass. The + whole required set is one command, `make ci`, so CI and local development run + the same checks (fmt, clippy, workspace tests, VM-harness safety tests, + release build, static installer build). The toolchain is pinned in + `installer-rs/rust-toolchain.toml` and dependencies use the committed + `Cargo.lock` (`--locked`). +2. **Gate outcomes are distinct.** A gate is `passed`, `failed`, `blocked`, + `skipped` or `not_run`; **only `passed` is a pass**. `blocked` means a + prerequisite (VM, graphical seat, model, CI runner, or an automated command) + is missing; `skipped` means an operator excluded it; `not_run` means + execution was not requested. +3. **Gates perform their advertised check.** Host gates run their real command + through the command layer and record the exit status. VM/seat/model gates + name the real harness scenario and are resolved from that harness's + `results.json` (reusing the existing harness); with no evidence they are + `blocked`. Gates whose automation does not exist yet have an empty command + and can only ever be `blocked`. +4. **Evidence is bound to the artifact.** `phoebus-release gates --candidate + ` records the candidate's name and SHA-256 in the report; the harness + records the digest it verified from `PHOEBUS_VM_ARTIFACT[_SHA256]`. Imported + evidence whose digest differs from the candidate is reported as `failed` + ("stale evidence"), never passed. +5. **Publication is authorized, not assumed.** `phoebus-release publish` + refuses unless the report is bound to the exact candidate digest, every gate + passed, the candidate matches its manifest entry, and a detached signature + verifies. Check failures happen before the destination is touched. + `atomic_publish` keeps `latest.iso.prev` and restores it if the final rename + fails, so a failed or interrupted publication never removes the working + release. + +## Consequences + +- A green CI job means the listed checks actually ran. There is no "skipping" + path for a required check. +- `make release-gates` writes a report that reflects reality. Because + `no-model-recovery`, `updates-and-rollback` and `desktop-session` have no + automated harness yet, they are always `blocked`, so a full release cannot be + authorized until those checks are automated (or given reviewed manual + evidence). This is deliberate: it is preferable to be unable to publish than + to publish on a false pass. +- The release report and per-gate logs are diagnostics, not source; they are + gitignored, redacted with the environment redactor, and bounded in size. +- The remaining external prerequisite is a registered Forgejo Actions runner; + until one exists the workflow is unexecuted and is recorded as such. + +## Status + +Accepted and implemented. The gate engine, harness-evidence import, artifact +binding and publication refusals are covered by unit tests; `make ci` passes +locally. CI execution and VM/model gates remain unverified here (no runner, no +disposable VM or model in this environment). diff --git a/docs/adr/README.md b/docs/adr/README.md index 14e5c30..8b1c8b6 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -17,5 +17,6 @@ and link it here. | [0009](0009-mango-dankmaterialshell-desktop.md) | Mango + DankMaterialShell desktop option | Accepted | | [0010](0010-graphical-installer-frontend.md) | Graphical installer frontend and typed bridge | Accepted | | [0011](0011-opencode-connection-boundary.md) | OpenCode connection boundary | Accepted | +| [0012](0012-release-verification-and-publication.md) | Release verification evidence and publication authorization | Accepted | Format: Context / Decision / Consequences / Status. diff --git a/installer-rs/crates/phoebus-installer/src/bin/phoebus-release.rs b/installer-rs/crates/phoebus-installer/src/bin/phoebus-release.rs index a53dc88..6ad79c6 100644 --- a/installer-rs/crates/phoebus-installer/src/bin/phoebus-release.rs +++ b/installer-rs/crates/phoebus-installer/src/bin/phoebus-release.rs @@ -8,9 +8,11 @@ use std::process::ExitCode; use clap::{Parser, Subcommand}; use phoebus_core::VERSION; +use phoebus_executor::{CommandSpec, ProcessRunner, RealRunner}; use phoebus_installer::release::{ - artifact_for, atomic_publish, default_manifest_path, run_gates, sha256_file, sign_command, - verify_signature_command, GateReport, ReleaseManifest, + artifact_for, candidate_ref, default_manifest_path, publish_release, run_gates, sha256_file, + sign_command, verify_signature_command, GateOptions, GateReport, HarnessEvidenceSet, + MinisignVerifier, PublishRequest, ReleaseManifest, SystemGateExecutor, }; #[derive(Parser)] @@ -51,22 +53,49 @@ enum Command { #[arg(long)] output: PathBuf, }, - /// Write the candidate gate report. `--execute` runs host gates; VM, - /// graphical-seat and model gates need their environment and are recorded - /// as not run otherwise. + /// Write the candidate gate report. + /// + /// Without `--execute` every gate is recorded as `not_run` and never as a + /// pass. With `--execute`, host gates run their real commands; VM, seat and + /// model gates are resolved from `--harness-results` when supplied, and are + /// otherwise recorded as `blocked` (never silently passed). Gates { #[arg(long, default_value = "gate-report.json")] output: PathBuf, #[arg(long)] execute: bool, + /// Bind the report to this candidate artifact's digest. + #[arg(long)] + candidate: Option, + /// Import VM-harness `results.json` files from this file or directory. + #[arg(long)] + harness_results: Option, + /// Record a gate as `skipped` (repeatable). A skipped gate is never a + /// pass, so this cannot be used to authorize a publication. + #[arg(long = "skip")] + skip: Vec, + /// Run only these gates (repeatable); the rest are `skipped`. + #[arg(long = "only")] + only: Vec, + /// Directory for redacted per-gate failure logs. + #[arg(long)] + log_dir: Option, }, - /// Publish a candidate atomically, refusing unless a passing gate report is - /// supplied. The previous release is preserved. + /// Publish a candidate atomically. Refuses unless the gate report is bound + /// to the exact candidate digest, every gate passed, the manifest verifies + /// the artifact and a detached signature verifies. The previous release is + /// preserved. Publish { candidate: PathBuf, dest: PathBuf, #[arg(long)] gate_report: PathBuf, + /// The manifest the candidate is verified against. + #[arg(long)] + manifest: Option, + /// The detached signature (`*.minisig`) for the candidate. + #[arg(long)] + signature: Option, }, /// Print the signing command for an artifact (key outside the repository). Sign { artifact: PathBuf, key: PathBuf }, @@ -86,6 +115,20 @@ fn main() -> ExitCode { } } +/// The short source commit the tool is running against, for evidence binding. +fn git_commit() -> String { + let spec = CommandSpec::new("release", "git-rev-parse", "git") + .arg("rev-parse") + .arg("--short") + .arg("HEAD"); + RealRunner + .execute(&spec) + .ok() + .filter(|output| output.success) + .map(|output| output.stdout_lossy().trim().to_string()) + .unwrap_or_default() +} + fn run() -> std::result::Result<(), Box> { match Cli::parse().command { Command::Manifest { @@ -163,24 +206,65 @@ fn run() -> std::result::Result<(), Box> { println!("{}", sha256_file(&file)?); Ok(()) } - Command::Gates { output, execute } => { - let report = run_gates(execute); + Command::Gates { + output, + execute, + candidate, + harness_results, + skip, + only, + log_dir, + } => { + let bound = match &candidate { + Some(path) => Some(candidate_ref(path)?), + None => None, + }; + let evidence = match &harness_results { + Some(path) => Some(HarnessEvidenceSet::from_path(path)?), + None => None, + }; + let log_dir = log_dir.or_else(|| { + Some( + output + .parent() + .unwrap_or_else(|| std::path::Path::new(".")) + .join("gate-logs"), + ) + }); + let options = GateOptions { + execute, + skip, + only, + candidate: bound, + evidence: evidence.as_ref(), + log_dir, + git_commit: git_commit(), + build_id: std::env::var("PHOEBUS_BUILD_ID").unwrap_or_default(), + }; + let report = run_gates(&SystemGateExecutor, &options); report.save(&output)?; - println!( - "wrote {} ({} passed, {} not run)", - output.display(), - report - .results - .iter() - .filter(|r| r.status == phoebus_installer::release::GateStatus::Passed) - .count(), - report.not_run() - ); + println!("wrote {} ({})", output.display(), report.summary_line()); + for result in &report.results { + println!( + " {:<18} {:<8} {}", + result.name, + result.status.as_str(), + result.detail + ); + } if !execute { eprintln!( "note: gates were not executed; pass --execute on a configured runner \ - to run them" + to run them. An unexecuted gate is never a pass." ); + return Ok(()); + } + if !report.all_passed() { + return Err(format!( + "candidate checks did not all pass ({})", + report.summary_line() + ) + .into()); } Ok(()) } @@ -188,22 +272,22 @@ fn run() -> std::result::Result<(), Box> { candidate, dest, gate_report, + manifest, + signature, } => { let report = GateReport::load(&gate_report)?; - if !report.all_passed() { - return Err(format!( - "refusing to publish: {} gate(s) passed, {} not run \ - (run the gates on a configured runner and supply a passing report)", - report - .results - .iter() - .filter(|r| r.status == phoebus_installer::release::GateStatus::Passed) - .count(), - report.not_run() - ) - .into()); - } - atomic_publish(&candidate, &dest)?; + let manifest = match &manifest { + Some(path) => Some(ReleaseManifest::load(path)?), + None => None, + }; + let request = PublishRequest { + candidate: &candidate, + dest: &dest, + report: &report, + manifest: manifest.as_ref(), + signature: signature.as_deref(), + }; + publish_release(&request, &MinisignVerifier)?; println!("published {} -> {}", candidate.display(), dest.display()); Ok(()) } diff --git a/installer-rs/crates/phoebus-installer/src/release.rs b/installer-rs/crates/phoebus-installer/src/release.rs index 389baf9..438e408 100644 --- a/installer-rs/crates/phoebus-installer/src/release.rs +++ b/installer-rs/crates/phoebus-installer/src/release.rs @@ -9,8 +9,12 @@ //! Actual ISO assembly needs `xorriso`; this module emits the intended command //! and refuses to publish without a passing verification. +use std::collections::BTreeMap; use std::path::{Path, PathBuf}; +use phoebus_core::Redactor; +use phoebus_executor::exec::find_in_path; +use phoebus_executor::{CommandOutput, CommandSpec, ProcessRunner, RealRunner}; use serde::{Deserialize, Serialize}; use sha2::{Digest, Sha256}; @@ -64,6 +68,32 @@ pub fn artifact_for(path: &Path) -> std::io::Result { }) } +/// A concrete candidate artifact (ISO or installer binary) with its digest. +/// +/// Gate evidence is bound to this reference: a report produced for one digest +/// can never authorize a different build. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct CandidateRef { + pub name: String, + pub sha256: String, + pub size_bytes: u64, +} + +/// Hash a candidate file into a [`CandidateRef`]. +pub fn candidate_ref(path: &Path) -> std::io::Result { + let artifact = artifact_for(path)?; + Ok(CandidateRef { + name: artifact.name, + sha256: artifact.sha256, + size_bytes: artifact.size_bytes, + }) +} + +/// A short, human-readable digest prefix for diagnostics. +pub fn short_digest(sha256: &str) -> String { + sha256.get(..12).unwrap_or(sha256).to_string() +} + impl ReleaseManifest { pub fn save(&self, path: &Path) -> std::io::Result<()> { if let Some(parent) = path.parent() { @@ -119,7 +149,7 @@ pub fn default_manifest_path(dir: &Path) -> PathBuf { /// What a gate needs to be runnable. A gate that is not runnable is recorded /// as `NotRun`, never as `Passed`. -#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum GateRequirement { /// Runs anywhere. @@ -152,23 +182,61 @@ pub struct Gate { pub name: String, pub description: String, pub requires: GateRequirement, - /// The exact command (argv) that performs the check. + /// The exact command (argv) that performs the check. Empty means there is + /// no automated command yet; such a gate can only ever be `Blocked`, never + /// silently passed. pub command: Vec, + /// The VM-harness scenario whose `results.json` is the evidence for this + /// gate, when the check is produced by a harness run rather than by the + /// host command above. + #[serde(default)] + pub scenario: Option, } +/// The outcome of a candidate check. +/// +/// * `Passed` / `Failed` — the command (or imported harness scenario) ran and +/// its exit status was zero / nonzero. +/// * `Blocked` — the check could not run because its prerequisite (VM, seat, +/// model, CI runner, or an automated command) is missing. +/// * `Skipped` — an operator explicitly excluded the gate; it is never a pass. +/// * `NotRun` — execution was not requested; the check is unexecuted. #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum GateStatus { Passed, Failed, + Blocked, + Skipped, NotRun, } +impl GateStatus { + pub fn as_str(self) -> &'static str { + match self { + GateStatus::Passed => "passed", + GateStatus::Failed => "failed", + GateStatus::Blocked => "blocked", + GateStatus::Skipped => "skipped", + GateStatus::NotRun => "not_run", + } + } + + /// Only `Passed` counts as a pass; every other state is not. + pub fn is_pass(self) -> bool { + matches!(self, GateStatus::Passed) + } +} + #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] pub struct GateResult { pub name: String, pub status: GateStatus, pub detail: String, + /// Redacted, bounded log retained for a failed or blocked gate, when one + /// was written. Paths are absolute or relative to the report directory. + #[serde(default)] + pub log: Option, } #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] @@ -176,20 +244,55 @@ pub struct GateResult { pub struct GateReport { pub version: String, pub created_unix: u64, + /// The tool that produced the report. + pub tool: String, + /// The source commit the gates ran against, when known. + pub git_commit: String, + /// An operator-supplied build identifier (e.g. `$PHOEBUS_BUILD_ID`). + pub build_id: String, + /// The exact artifact these results are bound to. Publication refuses when + /// this is absent or does not match the candidate. + pub candidate: Option, pub results: Vec, } impl GateReport { - /// Whether every gate passed. `NotRun` is not a pass. + /// Whether every gate passed. Any Failed, Blocked, Skipped or NotRun result + /// means the report is not a pass. pub fn all_passed(&self) -> bool { - !self.results.is_empty() && self.results.iter().all(|r| r.status == GateStatus::Passed) + !self.results.is_empty() && self.results.iter().all(|r| r.status.is_pass()) } - pub fn not_run(&self) -> usize { - self.results - .iter() - .filter(|r| r.status == GateStatus::NotRun) - .count() + pub fn count(&self, status: GateStatus) -> usize { + self.results.iter().filter(|r| r.status == status).count() + } + + /// Checks that did not yield a pass (failed, blocked, skipped or unrun). + pub fn unexecuted(&self) -> usize { + self.results.iter().filter(|r| !r.status.is_pass()).count() + } + + /// `0` when everything passed, `1` when a check failed, `2` otherwise + /// (blocked/skipped/unrun). Never `0` unless every gate actually passed. + pub fn exit_code(&self) -> i32 { + if self.all_passed() { + 0 + } else if self.count(GateStatus::Failed) > 0 { + 1 + } else { + 2 + } + } + + pub fn summary_line(&self) -> String { + format!( + "passed={} failed={} blocked={} skipped={} not_run={}", + self.count(GateStatus::Passed), + self.count(GateStatus::Failed), + self.count(GateStatus::Blocked), + self.count(GateStatus::Skipped), + self.count(GateStatus::NotRun), + ) } pub fn save(&self, path: &Path) -> std::io::Result<()> { @@ -206,81 +309,656 @@ impl GateReport { } } -/// The candidate checks. Commands are the real harness invocations, not -/// placeholders, so a configured runner executes exactly what is documented. +// --------------------------------------------------------------------------- +// Harness evidence +// --------------------------------------------------------------------------- + +/// The artifact a harness run was executed against, recorded by the harness. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct HarnessArtifact { + #[serde(default)] + pub name: Option, + #[serde(default)] + pub sha256: Option, +} + +/// One imported VM-harness run (`results.json`). This is how a candidate runner +/// consumes the existing harness rather than inventing a second one. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct HarnessEvidence { + pub scenario: String, + #[serde(default)] + pub run_id: String, + #[serde(default)] + pub exit_code: i32, + #[serde(default)] + pub counts: BTreeMap, + #[serde(default)] + pub artifact: Option, +} + +impl HarnessEvidence { + pub fn artifact_sha256(&self) -> Option<&str> { + self.artifact + .as_ref() + .and_then(|a| a.sha256.as_deref()) + .filter(|s| !s.is_empty()) + } + + pub fn from_json_str(text: &str) -> std::result::Result { + let value: serde_json::Value = + serde_json::from_str(text).map_err(|e| format!("invalid harness JSON: {e}"))?; + let scenario = value + .get("scenario") + .and_then(|v| v.as_str()) + .ok_or_else(|| "harness result is missing a scenario".to_string())? + .to_string(); + let run_id = value + .get("run_id") + .and_then(|v| v.as_str()) + .unwrap_or_default() + .to_string(); + let exit_code = value + .get("exit_code") + .and_then(|v| v.as_i64()) + .unwrap_or(-1) as i32; + let counts = value + .get("counts") + .and_then(|v| v.as_object()) + .map(|map| { + map.iter() + .filter_map(|(k, v)| v.as_u64().map(|n| (k.clone(), n))) + .collect() + }) + .unwrap_or_default(); + let artifact = value + .get("artifact") + .and_then(|a| serde_json::from_value::(a.clone()).ok()); + Ok(Self { + scenario, + run_id, + exit_code, + counts, + artifact, + }) + } + + pub fn load(path: &Path) -> std::result::Result { + let text = std::fs::read_to_string(path) + .map_err(|e| format!("cannot read {}: {e}", path.display()))?; + Self::from_json_str(&text) + } +} + +/// A collection of imported harness runs, resolved by scenario and candidate. +#[derive(Debug, Clone, Default, PartialEq, Eq)] +pub struct HarnessEvidenceSet { + entries: Vec, +} + +impl HarnessEvidenceSet { + pub fn new() -> Self { + Self::default() + } + + pub fn push(&mut self, evidence: HarnessEvidence) { + self.entries.push(evidence); + } + + pub fn len(&self) -> usize { + self.entries.len() + } + + pub fn is_empty(&self) -> bool { + self.entries.is_empty() + } + + /// Load every `results.json` under `path` (a file or a directory tree). + pub fn from_path(path: &Path) -> std::result::Result { + let mut set = Self::new(); + if path.is_file() { + set.push(HarnessEvidence::load(path)?); + return Ok(set); + } + if !path.is_dir() { + return Err(format!( + "harness results path does not exist: {}", + path.display() + )); + } + let mut files = Vec::new(); + collect_results_files(path, 0, &mut files)?; + files.sort(); + for file in files { + set.push(HarnessEvidence::load(&file)?); + } + Ok(set) + } + + /// Resolve the evidence for a scenario. When a candidate digest is given, + /// evidence that was executed against that exact digest is preferred; + /// otherwise the most recent run for the scenario is used so that a stale + /// or unbound result is surfaced as a failure rather than a pass. + pub fn resolve(&self, scenario: &str, candidate_sha: Option<&str>) -> Option<&HarnessEvidence> { + let matching: Vec<&HarnessEvidence> = self + .entries + .iter() + .filter(|e| e.scenario == scenario) + .collect(); + if matching.is_empty() { + return None; + } + if let Some(sha) = candidate_sha { + if let Some(found) = matching.iter().find(|e| e.artifact_sha256() == Some(sha)) { + return Some(found); + } + } + matching.into_iter().max_by(|a, b| a.run_id.cmp(&b.run_id)) + } +} + +fn collect_results_files( + dir: &Path, + depth: usize, + out: &mut Vec, +) -> std::result::Result<(), String> { + if depth > 6 { + return Ok(()); + } + let entries = + std::fs::read_dir(dir).map_err(|e| format!("cannot read {}: {e}", dir.display()))?; + for entry in entries { + let entry = entry.map_err(|e| e.to_string())?; + let path = entry.path(); + let file_type = entry.file_type().map_err(|e| e.to_string())?; + if file_type.is_dir() { + collect_results_files(&path, depth + 1, out)?; + } else if file_type.is_file() && path.file_name().is_some_and(|n| n == "results.json") { + out.push(path); + } + } + Ok(()) +} + +// --------------------------------------------------------------------------- +// Gate execution +// --------------------------------------------------------------------------- + +/// A prerequisite for running a gate. A missing prerequisite must produce a +/// `Blocked` result, never a pass. +pub trait GateExecutor { + fn prerequisite(&self, requirement: GateRequirement) -> std::result::Result<(), String>; + fn run( + &self, + gate: &Gate, + env: &[(String, String)], + ) -> std::result::Result; +} + +/// Executes host gates with the real command runner and detects whether the +/// VM / seat / model / CI prerequisites are present in the environment. +#[derive(Debug, Default, Clone, Copy)] +pub struct SystemGateExecutor; + +impl SystemGateExecutor { + fn env_present(key: &str) -> bool { + std::env::var(key) + .map(|v| !v.trim().is_empty()) + .unwrap_or(false) + } +} + +impl GateExecutor for SystemGateExecutor { + fn prerequisite(&self, requirement: GateRequirement) -> std::result::Result<(), String> { + match requirement { + GateRequirement::Host => Ok(()), + GateRequirement::Vm => { + if !Self::env_present("OVMF_CODE") { + return Err("OVMF_CODE is not set (no disposable VM configured)".into()); + } + if !Self::env_present("OVMF_VARS") { + return Err("OVMF_VARS is not set (no disposable VM configured)".into()); + } + let qemu = + std::env::var("QEMU_BIN").unwrap_or_else(|_| "qemu-system-x86_64".into()); + if find_in_path(&qemu).is_none() { + return Err(format!("QEMU binary not found: {qemu}")); + } + Ok(()) + } + GateRequirement::GraphicalSeat => { + self.prerequisite(GateRequirement::Vm)?; + if !Self::env_present("PHOEBUS_GRAPHICAL_SEAT") { + return Err( + "no graphical seat (set PHOEBUS_GRAPHICAL_SEAT=1 on a seat host)".into(), + ); + } + Ok(()) + } + GateRequirement::Model => { + for key in [ + "PHOEBUS_OPENCODE_LIVE_URL", + "PHOEBUS_OPENCODE_LIVE_PROVIDER", + "PHOEBUS_OPENCODE_LIVE_MODEL", + ] { + if !Self::env_present(key) { + return Err(format!("{key} is not set (no live model configured)")); + } + } + Ok(()) + } + GateRequirement::CiRunner => { + if Self::env_present("CI") || Self::env_present("FORGEJO_ACTIONS") { + Ok(()) + } else { + Err("not running on a CI runner".into()) + } + } + } + } + + fn run( + &self, + gate: &Gate, + env: &[(String, String)], + ) -> std::result::Result { + let (program, args) = gate + .command + .split_first() + .ok_or_else(|| "no command to run".to_string())?; + let mut spec = CommandSpec::new("release-gate", gate.name.clone(), program.clone()); + spec = spec.args(args.iter().cloned()); + for (key, value) in env { + spec = spec.env(key.clone(), value.clone()); + } + RealRunner + .execute(&spec) + .map_err(|e| format!("could not run {}: {e}", gate.command.join(" "))) + } +} + +/// Options controlling a gate run. +#[derive(Debug, Default)] +pub struct GateOptions<'a> { + /// Actually execute the gates (and import harness evidence). Without this, + /// every gate is `NotRun`. + pub execute: bool, + /// Gates the operator explicitly excludes; recorded as `Skipped`. + pub skip: Vec, + /// When non-empty, only these gates are executed; the rest are `Skipped`. + pub only: Vec, + /// The artifact the run is bound to. + pub candidate: Option, + /// Imported harness evidence; when present, VM/seat/model gates with a + /// scenario are resolved from it instead of launching QEMU. + pub evidence: Option<&'a HarnessEvidenceSet>, + /// Directory for redacted, bounded per-gate logs. Defaults to no log files. + pub log_dir: Option, + pub git_commit: String, + pub build_id: String, +} + +/// Build a redactor seeded from environment values whose names look secret. +fn environment_redactor() -> Redactor { + let redactor = Redactor::new(); + for (key, value) in std::env::vars() { + let upper = key.to_ascii_uppercase(); + let sensitive = upper.contains("SECRET") + || upper.contains("TOKEN") + || upper.contains("PASSWORD") + || upper.contains("PASSWD") + || upper.contains("API_KEY") + || upper.ends_with("_KEY"); + if sensitive && value.len() >= 6 { + redactor.register_plain(&value); + } + } + redactor +} + +/// The last few non-empty lines of output, redacted and length-bounded. +fn bounded_excerpt(output: &CommandOutput, redactor: &Redactor) -> String { + let stderr = output.stderr_lossy(); + let source = if !stderr.trim().is_empty() { + stderr + } else { + output.stdout_lossy() + }; + let cleaned = redactor.redact(&source); + let mut lines: Vec<&str> = cleaned + .lines() + .map(str::trim) + .filter(|line| !line.is_empty()) + .collect(); + let start = lines.len().saturating_sub(6); + lines = lines.split_off(start); + let mut text = lines.join(" | "); + if text.len() > 500 { + text.truncate(500); + text.push('…'); + } + text +} + +fn write_gate_log( + log_dir: &Path, + gate: &Gate, + output: &CommandOutput, + redactor: &Redactor, +) -> Option { + let redacted = redactor.redact(&format!( + "{}\n--- stdout ---\n{}\n--- stderr ---\n{}", + gate.command.join(" "), + output.stdout_lossy(), + output.stderr_lossy() + )); + let max = 256 * 1024; + let mut bytes = redacted.into_bytes(); + if bytes.len() > max { + bytes.truncate(max); + bytes.extend_from_slice(b"\n[truncated]\n"); + } + std::fs::create_dir_all(log_dir).ok()?; + let safe: String = gate + .name + .chars() + .map(|c| { + if c.is_ascii_alphanumeric() || c == '-' || c == '_' { + c + } else { + '-' + } + }) + .collect(); + let path = log_dir.join(format!("{safe}.log")); + std::fs::write(&path, bytes).ok()?; + Some(path.to_string_lossy().to_string()) +} + +/// Run the candidate gates and return a report that never claims a check it +/// did not execute. +pub fn run_gates(executor: &dyn GateExecutor, options: &GateOptions) -> GateReport { + let now = std::time::SystemTime::now() + .duration_since(std::time::UNIX_EPOCH) + .map(|d| d.as_secs()) + .unwrap_or(0); + let redactor = environment_redactor(); + let candidate_sha = options.candidate.as_ref().map(|c| c.sha256.as_str()); + let mut results = Vec::new(); + + for gate in candidate_gates() { + let result = if options.skip.iter().any(|s| s == &gate.name) { + GateResult { + name: gate.name.clone(), + status: GateStatus::Skipped, + detail: "explicitly skipped by the operator".into(), + log: None, + } + } else if !options.execute { + GateResult { + name: gate.name.clone(), + status: GateStatus::NotRun, + detail: "not executed (pass --execute on a configured runner)".into(), + log: None, + } + } else if !options.only.is_empty() && !options.only.iter().any(|n| n == &gate.name) { + GateResult { + name: gate.name.clone(), + status: GateStatus::Skipped, + detail: "not selected by --only".into(), + log: None, + } + } else if let (Some(evidence), Some(scenario)) = + (options.evidence, gate.scenario.as_deref()) + { + evidence_result_for(&gate, scenario, evidence, candidate_sha) + } else if gate.command.is_empty() { + GateResult { + name: gate.name.clone(), + status: GateStatus::Blocked, + detail: format!( + "no automated command for this check; manual {} verification required", + gate.requires.as_str() + ), + log: None, + } + } else { + match executor.prerequisite(gate.requires) { + Err(missing) => GateResult { + name: gate.name.clone(), + status: GateStatus::Blocked, + detail: missing, + log: None, + }, + Ok(()) => { + let env = candidate_env(options.candidate.as_ref()); + match executor.run(&gate, &env) { + Ok(output) => { + let status = if output.success { + GateStatus::Passed + } else { + GateStatus::Failed + }; + let excerpt = bounded_excerpt(&output, &redactor); + let detail = if output.success { + format!( + "exit 0{}", + if excerpt.is_empty() { + String::new() + } else { + format!(": {excerpt}") + } + ) + } else { + format!("exit {}: {excerpt}", output.status) + }; + let log = if status.is_pass() { + None + } else { + options + .log_dir + .as_deref() + .and_then(|dir| write_gate_log(dir, &gate, &output, &redactor)) + }; + GateResult { + name: gate.name.clone(), + status, + detail, + log, + } + } + Err(error) => GateResult { + name: gate.name.clone(), + status: GateStatus::Failed, + detail: error, + log: None, + }, + } + } + } + }; + results.push(result); + } + + GateReport { + version: env!("CARGO_PKG_VERSION").to_string(), + created_unix: now, + tool: "phoebus-release".into(), + git_commit: options.git_commit.clone(), + build_id: options.build_id.clone(), + candidate: options.candidate.clone(), + results, + } +} + +fn candidate_env(candidate: Option<&CandidateRef>) -> Vec<(String, String)> { + match candidate { + Some(c) => vec![ + ("PHOEBUS_VM_ARTIFACT".to_string(), c.name.clone()), + ("PHOEBUS_VM_ARTIFACT_SHA256".to_string(), c.sha256.clone()), + ], + None => Vec::new(), + } +} + +fn evidence_result_for( + gate: &Gate, + scenario: &str, + evidence: &HarnessEvidenceSet, + candidate_sha: Option<&str>, +) -> GateResult { + match evidence.resolve(scenario, candidate_sha) { + None => GateResult { + name: gate.name.clone(), + status: GateStatus::Blocked, + detail: format!("no harness evidence found for scenario '{scenario}'"), + log: None, + }, + Some(found) => match (candidate_sha, found.artifact_sha256()) { + (Some(bound), Some(ev)) if bound != ev => GateResult { + name: gate.name.clone(), + status: GateStatus::Failed, + detail: format!( + "stale evidence: scenario '{scenario}' ran against {} but the candidate is {}", + short_digest(ev), + short_digest(bound) + ), + log: None, + }, + (Some(_), None) => GateResult { + name: gate.name.clone(), + status: GateStatus::Failed, + detail: format!( + "harness evidence for scenario '{scenario}' is not bound to an artifact; \ + re-run the harness with PHOEBUS_VM_ARTIFACT[_SHA256] set" + ), + log: None, + }, + _ if found.exit_code == 0 => GateResult { + name: gate.name.clone(), + status: GateStatus::Passed, + detail: format!("harness scenario '{scenario}' passed ({})", found.run_id), + log: None, + }, + _ => GateResult { + name: gate.name.clone(), + status: GateStatus::Failed, + detail: format!( + "harness scenario '{scenario}' failed (exit {})", + found.exit_code + ), + log: None, + }, + }, + } +} + +/// The candidate checks. +/// +/// Host gates run the real project commands. VM/seat/model gates name the real +/// harness scenario that produces their evidence. Gates whose automation does +/// not exist yet have an empty command and are always recorded as `Blocked`, so +/// they can never be mistaken for a pass. pub fn candidate_gates() -> Vec { - let driver = "installer/tests/vm/serial-driver.py"; + let serial = "installer/tests/vm/serial-driver.py"; + let gui = "installer/tests/vm/gui-driver.py"; vec![ + Gate { + name: "rust-fmt".into(), + description: "rustfmt over the workspace".into(), + requires: GateRequirement::Host, + command: vec!["make".into(), "fmt-check".into()], + scenario: None, + }, + Gate { + name: "rust-clippy".into(), + description: "clippy over the workspace".into(), + requires: GateRequirement::Host, + command: vec!["make".into(), "clippy".into()], + scenario: None, + }, + Gate { + name: "rust-tests".into(), + description: "workspace test suite".into(), + requires: GateRequirement::Host, + command: vec!["make".into(), "test-rust".into()], + scenario: None, + }, + Gate { + name: "harness-safety".into(), + description: "host-side VM harness safety tests".into(), + requires: GateRequirement::Host, + command: vec!["make".into(), "test-vm".into()], + scenario: None, + }, + Gate { + name: "release-build".into(), + description: "release installer build".into(), + requires: GateRequirement::Host, + command: vec!["make".into(), "build".into()], + scenario: None, + }, + Gate { + name: "static-build".into(), + description: "static installer build for the live environment".into(), + requires: GateRequirement::Host, + command: vec!["make".into(), "static".into()], + scenario: None, + }, Gate { name: "install".into(), description: "full encrypted install in the disposable VM".into(), requires: GateRequirement::Vm, - command: vec!["python3".into(), driver.into(), "install".into()], + command: vec!["python3".into(), serial.into(), "install".into()], + scenario: Some("serial-install".into()), }, Gate { name: "detached-boot".into(), description: "boot the installed disk with the ISO detached".into(), requires: GateRequirement::Vm, - command: vec!["python3".into(), driver.into(), "boot".into()], + command: vec!["python3".into(), serial.into(), "boot".into()], + scenario: Some("serial-boot".into()), }, Gate { - name: "no-model-recovery".into(), - description: "operate and recover with no model connected".into(), - requires: GateRequirement::Vm, - command: vec!["python3".into(), driver.into(), "checks".into()], - }, - Gate { - name: "desktop-session".into(), - description: "graphical seat: launch, lock, suspend, log out".into(), + name: "graphical-install".into(), + description: "graphical install in a seat-providing VM".into(), requires: GateRequirement::GraphicalSeat, - command: vec!["python3".into(), driver.into(), "desktop".into()], - }, - Gate { - name: "updates-and-rollback".into(), - description: "prepare, apply, roll back and reboot detached".into(), - requires: GateRequirement::Vm, - command: vec!["python3".into(), driver.into(), "rollback".into()], + command: vec!["python3".into(), gui.into(), "install".into()], + scenario: Some("gui-install".into()), }, Gate { name: "assistant-live".into(), description: "one live provider call through the sandbox".into(), requires: GateRequirement::Model, - command: vec!["sys".into(), "ask".into(), "show system status".into()], + command: vec!["python3".into(), gui.into(), "opencode".into()], + scenario: Some("gui-opencode".into()), + }, + // No automated harness exists for these yet. They stay explicitly + // blocked until one does; an empty command can never be a pass. + Gate { + name: "no-model-recovery".into(), + description: "operate and recover with no model connected".into(), + requires: GateRequirement::Vm, + command: Vec::new(), + scenario: None, + }, + Gate { + name: "updates-and-rollback".into(), + description: "prepare, apply, roll back and reboot detached".into(), + requires: GateRequirement::Vm, + command: Vec::new(), + scenario: None, + }, + Gate { + name: "desktop-session".into(), + description: "graphical seat: launch, lock, suspend, log out".into(), + requires: GateRequirement::GraphicalSeat, + command: Vec::new(), + scenario: None, }, ] } -/// Run the candidate gates. With `execute = false` every gate is recorded as -/// `NotRun` with the unmet requirement, so a report never claims a check that -/// did not run. -pub fn run_gates(execute: bool) -> GateReport { - let now = std::time::SystemTime::now() - .duration_since(std::time::UNIX_EPOCH) - .map(|d| d.as_secs()) - .unwrap_or(0); - let mut report = GateReport { - version: env!("CARGO_PKG_VERSION").to_string(), - created_unix: now, - results: Vec::new(), - }; - for gate in candidate_gates() { - let (status, detail) = if execute && gate.requires == GateRequirement::Host { - (GateStatus::Passed, String::from("ok")) - } else { - ( - GateStatus::NotRun, - format!("not run (requires {})", gate.requires.as_str()), - ) - }; - report.results.push(GateResult { - name: gate.name, - status, - detail, - }); - } - report -} - // --------------------------------------------------------------------------- // Signing and atomic publication // --------------------------------------------------------------------------- @@ -312,29 +990,319 @@ pub fn verify_signature_command(artifact: &Path) -> Vec { /// /// The candidate is first written to a `*.new` sibling, fsynced and renamed /// into place, so a crash never leaves a half-written `latest.iso`. The prior -/// `latest.iso` is kept as `latest.iso.prev` for rollback. +/// `latest.iso` is kept as `latest.iso.prev` for rollback. If the final rename +/// fails after the previous release was moved aside, the previous release is +/// restored, so a failed publication never removes the working artifact. pub fn atomic_publish(candidate: &Path, dest: &Path) -> std::io::Result<()> { let parent = dest .parent() .ok_or_else(|| std::io::Error::new(std::io::ErrorKind::InvalidInput, "no parent"))?; std::fs::create_dir_all(parent)?; let staging = dest.with_extension("new"); + let previous = dest.with_extension("prev"); + // Never inherit a partial staging file from an interrupted run. + let _ = std::fs::remove_file(&staging); std::fs::copy(candidate, &staging)?; if let Ok(file) = std::fs::File::open(&staging) { let _ = file.sync_all(); } - if dest.exists() { - let previous = dest.with_extension("prev"); + sync_dir(parent); + + let had_previous = dest.exists(); + if had_previous { let _ = std::fs::remove_file(&previous); std::fs::rename(dest, &previous)?; } - std::fs::rename(&staging, dest)?; + match std::fs::rename(&staging, dest) { + Ok(()) => { + sync_dir(parent); + Ok(()) + } + Err(error) => { + // Restore the last known-good release; otherwise a failure here + // would leave no `latest.iso` at all. + if had_previous { + let _ = std::fs::rename(&previous, dest); + } + let _ = std::fs::remove_file(&staging); + Err(error) + } + } +} + +fn sync_dir(dir: &Path) { + if let Ok(handle) = std::fs::File::open(dir) { + let _ = handle.sync_all(); + } +} + +// --------------------------------------------------------------------------- +// Publication authorization +// --------------------------------------------------------------------------- + +/// Verifies a detached signature. Injectable so publication refusal can be +/// tested without a signing key. +pub trait SignatureVerifier { + fn verify(&self, artifact: &Path, signature: &Path) -> std::result::Result<(), String>; +} + +/// The real verifier: `minisign -Vm -x `. +#[derive(Debug, Default, Clone, Copy)] +pub struct MinisignVerifier; + +impl SignatureVerifier for MinisignVerifier { + fn verify(&self, artifact: &Path, signature: &Path) -> std::result::Result<(), String> { + if find_in_path("minisign").is_none() { + return Err("minisign is not installed; cannot verify the release signature".into()); + } + let spec = CommandSpec::new("release", "verify-signature", "minisign") + .arg("-Vm") + .arg(artifact.to_string_lossy().to_string()) + .arg("-x") + .arg(signature.to_string_lossy().to_string()); + let output = RealRunner + .execute(&spec) + .map_err(|e| format!("signature verification could not run: {e}"))?; + if output.success { + Ok(()) + } else { + let redactor = environment_redactor(); + let detail = redactor.redact(&output.stderr_lossy()); + let detail = detail.trim(); + Err(format!( + "signature verification failed (exit {}){}", + output.status, + if detail.is_empty() { + String::new() + } else { + format!(": {detail}") + } + )) + } + } +} + +/// Everything needed to authorize a publication. +pub struct PublishRequest<'a> { + pub candidate: &'a Path, + pub dest: &'a Path, + pub report: &'a GateReport, + pub manifest: Option<&'a ReleaseManifest>, + pub signature: Option<&'a Path>, +} + +/// Authorize and atomically publish a candidate. +/// +/// Refuses before touching the destination when any required precondition is +/// unmet: the gate report must be bound to the exact candidate digest, every +/// gate must have passed, the manifest must verify the candidate, and a valid +/// detached signature must be supplied. +pub fn publish_release( + request: &PublishRequest, + verifier: &dyn SignatureVerifier, +) -> std::result::Result<(), String> { + let bound = request.report.candidate.as_ref().ok_or_else(|| { + "refusing to publish: the gate report is not bound to a candidate artifact".to_string() + })?; + let actual = sha256_file(request.candidate) + .map_err(|e| format!("refusing to publish: cannot hash the candidate: {e}"))?; + let candidate_name = request + .candidate + .file_name() + .map(|n| n.to_string_lossy().to_string()) + .ok_or_else(|| "refusing to publish: candidate has no file name".to_string())?; + + if actual != bound.sha256 { + return Err(format!( + "refusing to publish: stale gate report; it is bound to {} ({}) but the candidate is {}", + bound.name, + short_digest(&bound.sha256), + short_digest(&actual) + )); + } + if bound.name != candidate_name { + return Err(format!( + "refusing to publish: stale gate report; it names {} but the candidate is {}", + bound.name, candidate_name + )); + } + if !request.report.all_passed() { + return Err(format!( + "refusing to publish: not every gate passed ({})", + request.report.summary_line() + )); + } + let manifest = request.manifest.ok_or_else(|| { + "refusing to publish: no release manifest supplied for artifact integrity".to_string() + })?; + let entry = manifest + .artifacts + .iter() + .find(|a| a.name == candidate_name) + .ok_or_else(|| { + format!("refusing to publish: the manifest does not contain {candidate_name}") + })?; + if entry.sha256 != actual { + return Err( + "refusing to publish: the manifest digest does not match the candidate".to_string(), + ); + } + if !manifest.verify(&candidate_name, request.candidate) { + return Err("refusing to publish: artifact integrity check failed".to_string()); + } + + let signature = request.signature.ok_or_else(|| { + "refusing to publish: no detached signature supplied; signature verification is required" + .to_string() + })?; + if !signature.is_file() { + return Err(format!( + "refusing to publish: signature file not found: {}", + signature.display() + )); + } + verifier.verify(request.candidate, signature)?; + + atomic_publish(request.candidate, request.dest) + .map_err(|e| format!("publication failed: {e}"))?; Ok(()) } #[cfg(test)] mod tests { use super::*; + use std::collections::HashMap; + use std::time::Duration; + + struct FakeExecutor { + prereq: HashMap>, + responses: HashMap, + } + + impl FakeExecutor { + fn new() -> Self { + Self { + prereq: HashMap::new(), + responses: HashMap::new(), + } + } + + fn fail_gate(mut self, gate: &str, status: i32) -> Self { + self.responses.insert( + gate.to_string(), + CommandOutput { + status, + success: status == 0, + stdout: Vec::new(), + stderr: format!("diagnostic for {gate}").into_bytes(), + duration: Duration::from_millis(1), + }, + ); + self + } + } + + impl GateExecutor for FakeExecutor { + fn prerequisite(&self, requirement: GateRequirement) -> std::result::Result<(), String> { + if let Some(result) = self.prereq.get(&requirement) { + return result.clone(); + } + // Host gates run; every special environment is absent by default so + // a fake test can never accidentally mark a VM/model gate passed. + if requirement == GateRequirement::Host { + Ok(()) + } else { + Err(format!( + "fake: prerequisite {} unavailable", + requirement.as_str() + )) + } + } + + fn run( + &self, + gate: &Gate, + _env: &[(String, String)], + ) -> std::result::Result { + Ok(self + .responses + .get(&gate.name) + .cloned() + .unwrap_or(CommandOutput { + status: 0, + success: true, + stdout: Vec::new(), + stderr: Vec::new(), + duration: Duration::ZERO, + })) + } + } + + struct FakeVerifier { + ok: bool, + } + + impl SignatureVerifier for FakeVerifier { + fn verify(&self, _artifact: &Path, _signature: &Path) -> std::result::Result<(), String> { + if self.ok { + Ok(()) + } else { + Err("bad signature".into()) + } + } + } + + fn bind(dir: &Path, name: &str, bytes: &[u8]) -> (PathBuf, CandidateRef) { + let path = dir.join(name); + std::fs::write(&path, bytes).unwrap(); + let reference = candidate_ref(&path).unwrap(); + (path, reference) + } + + fn passed_report(candidate: &CandidateRef) -> GateReport { + GateReport { + version: "test".into(), + created_unix: 0, + tool: "test".into(), + git_commit: "abc123".into(), + build_id: "build-1".into(), + candidate: Some(candidate.clone()), + results: candidate_gates() + .into_iter() + .map(|gate| GateResult { + name: gate.name, + status: GateStatus::Passed, + detail: "ok".into(), + log: None, + }) + .collect(), + } + } + + fn manifest_for(candidate: &CandidateRef) -> ReleaseManifest { + let mut manifest = ReleaseManifest::default(); + manifest.artifacts.push(Artifact { + name: candidate.name.clone(), + sha256: candidate.sha256.clone(), + size_bytes: candidate.size_bytes, + }); + manifest + } + + fn result<'a>(report: &'a GateReport, name: &str) -> &'a GateResult { + report + .results + .iter() + .find(|r| r.name == name) + .unwrap_or_else(|| panic!("no gate named {name}")) + } + + fn execution_opts<'a>() -> GateOptions<'a> { + GateOptions { + execute: true, + ..Default::default() + } + } #[test] fn sha256_of_known_bytes() { @@ -377,11 +1345,19 @@ mod tests { } #[test] - fn gates_cover_the_required_checks_and_never_fake_a_pass() { + fn gates_cover_the_required_checks() { let names: Vec = candidate_gates().into_iter().map(|g| g.name).collect(); for required in [ + "rust-fmt", + "rust-clippy", + "rust-tests", + "harness-safety", + "release-build", + "static-build", "install", "detached-boot", + "graphical-install", + "assistant-live", "desktop-session", "updates-and-rollback", "no-model-recovery", @@ -391,10 +1367,415 @@ mod tests { "missing gate {required}" ); } - let report = run_gates(false); + } + + #[test] + fn gate_statuses_are_distinct_and_serialize_unambiguously() { + for (status, expected) in [ + (GateStatus::Passed, "passed"), + (GateStatus::Failed, "failed"), + (GateStatus::Blocked, "blocked"), + (GateStatus::Skipped, "skipped"), + (GateStatus::NotRun, "not_run"), + ] { + let json = serde_json::to_string(&status).unwrap(); + assert_eq!(json, format!("\"{expected}\"")); + let back: GateStatus = serde_json::from_str(&json).unwrap(); + assert_eq!(back, status); + } + assert!(GateStatus::Passed.is_pass()); + for status in [ + GateStatus::Failed, + GateStatus::Blocked, + GateStatus::Skipped, + GateStatus::NotRun, + ] { + assert!(!status.is_pass(), "{status:?} must not count as a pass"); + } + } + + #[test] + fn unexecuted_gates_are_never_a_pass() { + let report = run_gates(&FakeExecutor::new(), &GateOptions::default()); assert!(!report.all_passed(), "an unexecuted gate is not a pass"); - assert_eq!(report.not_run(), report.results.len()); - assert!(report.results.iter().all(|r| r.detail.contains("requires"))); + assert_eq!(report.count(GateStatus::NotRun), report.results.len()); + assert!(report + .results + .iter() + .all(|r| r.detail.contains("not executed"))); + assert_eq!(report.exit_code(), 2); + } + + #[test] + fn host_gate_failure_fails_the_report_with_diagnostics() { + let executor = FakeExecutor::new().fail_gate("rust-clippy", 101); + let report = run_gates(&executor, &execution_opts()); + let clippy = result(&report, "rust-clippy"); + assert_eq!(clippy.status, GateStatus::Failed); + assert!( + clippy.detail.contains("exit 101"), + "detail: {}", + clippy.detail + ); + assert!(clippy.detail.contains("diagnostic for rust-clippy")); + assert_eq!(report.count(GateStatus::Passed), 5); + assert_eq!(report.exit_code(), 1); + assert!(!report.all_passed()); + } + + #[test] + fn missing_prerequisite_is_blocked_never_passed() { + let report = run_gates(&FakeExecutor::new(), &execution_opts()); + let install = result(&report, "install"); + assert_eq!(install.status, GateStatus::Blocked); + assert!(install.detail.contains("unavailable")); + assert_eq!( + result(&report, "desktop-session").status, + GateStatus::Blocked + ); + assert!(!report.all_passed()); + } + + #[test] + fn explicit_skips_are_recorded_and_never_pass() { + let mut opts = execution_opts(); + opts.skip = vec!["install".into(), "rust-fmt".into()]; + let report = run_gates(&FakeExecutor::new(), &opts); + assert_eq!(result(&report, "install").status, GateStatus::Skipped); + assert_eq!(result(&report, "rust-fmt").status, GateStatus::Skipped); + assert_eq!(report.count(GateStatus::Skipped), 2); + assert!(!report.all_passed()); + } + + #[test] + fn manual_gate_without_automation_is_blocked() { + let report = run_gates(&FakeExecutor::new(), &execution_opts()); + for name in [ + "no-model-recovery", + "updates-and-rollback", + "desktop-session", + ] { + let gate = result(&report, name); + assert_eq!(gate.status, GateStatus::Blocked, "{name}"); + assert!( + gate.detail.contains("no automated command"), + "{name}: {}", + gate.detail + ); + } + } + + #[test] + fn harness_evidence_parses_artifact_binding_and_counts() { + let json = r#"{ + "scenario": "serial-install", + "run_id": "serial-install-20260101T000000Z-abcd1234", + "exit_code": 0, + "counts": {"PASS": 3, "FAIL": 0}, + "artifact": {"name": "phoebus.iso", "sha256": "abc123"} + }"#; + let evidence = HarnessEvidence::from_json_str(json).unwrap(); + assert_eq!(evidence.scenario, "serial-install"); + assert_eq!(evidence.exit_code, 0); + assert_eq!(evidence.counts.get("PASS"), Some(&3)); + assert_eq!(evidence.artifact_sha256(), Some("abc123")); + } + + #[test] + fn harness_evidence_set_loads_nested_results_files() { + let dir = tempfile::tempdir().unwrap(); + let run_a = dir.path().join("run-a"); + let run_b = dir.path().join("nested/run-b"); + std::fs::create_dir_all(&run_a).unwrap(); + std::fs::create_dir_all(&run_b).unwrap(); + std::fs::write( + run_a.join("results.json"), + r#"{"scenario":"serial-install","run_id":"r1","exit_code":0}"#, + ) + .unwrap(); + std::fs::write( + run_b.join("results.json"), + r#"{"scenario":"serial-boot","run_id":"r2","exit_code":1}"#, + ) + .unwrap(); + let set = HarnessEvidenceSet::from_path(dir.path()).unwrap(); + assert_eq!(set.len(), 2); + assert_eq!(set.resolve("serial-boot", None).unwrap().run_id, "r2"); + } + + #[test] + fn matching_harness_evidence_passes_a_vm_gate() { + let dir = tempfile::tempdir().unwrap(); + let (_, candidate) = bind(dir.path(), "phoebus.iso", b"candidate"); + let mut set = HarnessEvidenceSet::new(); + set.push(HarnessEvidence { + scenario: "serial-install".into(), + run_id: "r1".into(), + exit_code: 0, + counts: BTreeMap::new(), + artifact: Some(HarnessArtifact { + name: Some("phoebus.iso".into()), + sha256: Some(candidate.sha256.clone()), + }), + }); + let mut opts = execution_opts(); + opts.evidence = Some(&set); + opts.candidate = Some(candidate); + let report = run_gates(&FakeExecutor::new(), &opts); + assert_eq!(result(&report, "install").status, GateStatus::Passed); + // A scenario with no evidence is blocked, not passed. + assert_eq!(result(&report, "detached-boot").status, GateStatus::Blocked); + } + + #[test] + fn stale_harness_evidence_cannot_authorize_a_candidate() { + let dir = tempfile::tempdir().unwrap(); + let (_, candidate) = bind(dir.path(), "phoebus.iso", b"candidate"); + let mut set = HarnessEvidenceSet::new(); + set.push(HarnessEvidence { + scenario: "serial-install".into(), + run_id: "old-run".into(), + exit_code: 0, + counts: BTreeMap::new(), + artifact: Some(HarnessArtifact { + name: Some("phoebus.iso".into()), + sha256: Some( + "0000000000000000000000000000000000000000000000000000000000000000".into(), + ), + }), + }); + let mut opts = execution_opts(); + opts.evidence = Some(&set); + opts.candidate = Some(candidate); + let report = run_gates(&FakeExecutor::new(), &opts); + let install = result(&report, "install"); + assert_eq!(install.status, GateStatus::Failed); + assert!( + install.detail.contains("stale evidence"), + "detail: {}", + install.detail + ); + assert_eq!(report.exit_code(), 1); + } + + #[test] + fn unbound_harness_evidence_is_refused_when_a_candidate_is_bound() { + let dir = tempfile::tempdir().unwrap(); + let (_, candidate) = bind(dir.path(), "phoebus.iso", b"candidate"); + let mut set = HarnessEvidenceSet::new(); + set.push(HarnessEvidence { + scenario: "serial-install".into(), + run_id: "r1".into(), + exit_code: 0, + counts: BTreeMap::new(), + artifact: None, + }); + let mut opts = execution_opts(); + opts.evidence = Some(&set); + opts.candidate = Some(candidate); + let report = run_gates(&FakeExecutor::new(), &opts); + let install = result(&report, "install"); + assert_eq!(install.status, GateStatus::Failed); + assert!( + install.detail.contains("not bound"), + "detail: {}", + install.detail + ); + } + + #[test] + fn failed_harness_scenario_is_failed() { + let dir = tempfile::tempdir().unwrap(); + let (_, candidate) = bind(dir.path(), "phoebus.iso", b"candidate"); + let mut set = HarnessEvidenceSet::new(); + set.push(HarnessEvidence { + scenario: "serial-boot".into(), + run_id: "r1".into(), + exit_code: 1, + counts: BTreeMap::new(), + artifact: Some(HarnessArtifact { + name: Some("phoebus.iso".into()), + sha256: Some(candidate.sha256.clone()), + }), + }); + let mut opts = execution_opts(); + opts.evidence = Some(&set); + opts.candidate = Some(candidate); + let report = run_gates(&FakeExecutor::new(), &opts); + assert_eq!(result(&report, "detached-boot").status, GateStatus::Failed); + } + + fn publish_fixture( + reverse: bool, + ) -> ( + tempfile::TempDir, + PathBuf, + PathBuf, + GateReport, + ReleaseManifest, + PathBuf, + ) { + let dir = tempfile::tempdir().unwrap(); + let (candidate, reference) = bind(dir.path(), "phoebus.iso", b"candidate-bytes"); + let dest = dir.path().join("latest.iso"); + std::fs::write(&dest, b"previous-release").unwrap(); + let report = passed_report(&reference); + let manifest = manifest_for(&reference); + let signature = dir.path().join("phoebus.iso.minisig"); + std::fs::write(&signature, b"signature").unwrap(); + if reverse { + let mut report = report; + report.candidate = None; + return (dir, candidate, dest, report, manifest, signature); + } + (dir, candidate, dest, report, manifest, signature) + } + + #[test] + fn publish_refuses_when_a_gate_is_not_run() { + let (_dir, candidate, dest, mut report, manifest, signature) = publish_fixture(false); + report.results[0].status = GateStatus::NotRun; + let request = PublishRequest { + candidate: &candidate, + dest: &dest, + report: &report, + manifest: Some(&manifest), + signature: Some(&signature), + }; + let error = publish_release(&request, &FakeVerifier { ok: true }).unwrap_err(); + assert!(error.contains("not every gate passed"), "error: {error}"); + assert_eq!(std::fs::read(&dest).unwrap(), b"previous-release"); + assert!(!dest.with_extension("prev").exists()); + } + + #[test] + fn publish_refuses_an_unbound_report() { + let (_dir, candidate, dest, report, manifest, signature) = publish_fixture(true); + let request = PublishRequest { + candidate: &candidate, + dest: &dest, + report: &report, + manifest: Some(&manifest), + signature: Some(&signature), + }; + let error = publish_release(&request, &FakeVerifier { ok: true }).unwrap_err(); + assert!(error.contains("not bound to a candidate"), "error: {error}"); + } + + #[test] + fn publish_refuses_stale_evidence_for_a_different_build() { + let dir = tempfile::tempdir().unwrap(); + let (candidate, _) = bind(dir.path(), "phoebus.iso", b"new-build"); + // A report bound to a *different* build's digest. + let stale_digest = "2".repeat(64); + let other = CandidateRef { + name: "phoebus.iso".into(), + sha256: stale_digest.clone(), + size_bytes: 1, + }; + let report = passed_report(&other); + let mut manifest = ReleaseManifest::default(); + manifest.artifacts.push(Artifact { + name: "phoebus.iso".into(), + sha256: stale_digest, + size_bytes: 1, + }); + let signature = dir.path().join("phoebus.iso.minisig"); + std::fs::write(&signature, b"sig").unwrap(); + let dest = dir.path().join("latest.iso"); + let request = PublishRequest { + candidate: &candidate, + dest: &dest, + report: &report, + manifest: Some(&manifest), + signature: Some(&signature), + }; + let error = publish_release(&request, &FakeVerifier { ok: true }).unwrap_err(); + assert!(error.contains("stale gate report"), "error: {error}"); + assert!(!dest.exists()); + } + + #[test] + fn publish_refuses_a_missing_signature() { + let (_dir, candidate, dest, report, manifest, _sig) = publish_fixture(false); + let request = PublishRequest { + candidate: &candidate, + dest: &dest, + report: &report, + manifest: Some(&manifest), + signature: None, + }; + let error = publish_release(&request, &FakeVerifier { ok: true }).unwrap_err(); + assert!(error.contains("signature"), "error: {error}"); + assert_eq!(std::fs::read(&dest).unwrap(), b"previous-release"); + } + + #[test] + fn publish_refuses_a_missing_manifest() { + let (_dir, candidate, dest, report, _manifest, signature) = publish_fixture(false); + let request = PublishRequest { + candidate: &candidate, + dest: &dest, + report: &report, + manifest: None, + signature: Some(&signature), + }; + let error = publish_release(&request, &FakeVerifier { ok: true }).unwrap_err(); + assert!(error.contains("manifest"), "error: {error}"); + } + + #[test] + fn publish_refuses_manifest_integrity_mismatch() { + let (_dir, candidate, dest, report, mut manifest, signature) = publish_fixture(false); + manifest.artifacts[0].sha256 = "3".repeat(64); + let request = PublishRequest { + candidate: &candidate, + dest: &dest, + report: &report, + manifest: Some(&manifest), + signature: Some(&signature), + }; + let error = publish_release(&request, &FakeVerifier { ok: true }).unwrap_err(); + assert!( + error.contains("manifest digest does not match"), + "error: {error}" + ); + assert_eq!(std::fs::read(&dest).unwrap(), b"previous-release"); + } + + #[test] + fn publish_refuses_a_failed_signature_and_keeps_the_previous_release() { + let (_dir, candidate, dest, report, manifest, signature) = publish_fixture(false); + let request = PublishRequest { + candidate: &candidate, + dest: &dest, + report: &report, + manifest: Some(&manifest), + signature: Some(&signature), + }; + let error = publish_release(&request, &FakeVerifier { ok: false }).unwrap_err(); + assert!(error.contains("bad signature"), "error: {error}"); + assert_eq!(std::fs::read(&dest).unwrap(), b"previous-release"); + assert!(!dest.with_extension("prev").exists()); + } + + #[test] + fn publish_replaces_the_release_and_preserves_the_previous() { + let (_dir, candidate, dest, report, manifest, signature) = publish_fixture(false); + let request = PublishRequest { + candidate: &candidate, + dest: &dest, + report: &report, + manifest: Some(&manifest), + signature: Some(&signature), + }; + publish_release(&request, &FakeVerifier { ok: true }).unwrap(); + assert_eq!(std::fs::read(&dest).unwrap(), b"candidate-bytes"); + assert_eq!( + std::fs::read(dest.with_extension("prev")).unwrap(), + b"previous-release" + ); + assert!(!dest.with_extension("new").exists()); } #[test] diff --git a/installer-rs/rust-toolchain.toml b/installer-rs/rust-toolchain.toml new file mode 100644 index 0000000..82e741c --- /dev/null +++ b/installer-rs/rust-toolchain.toml @@ -0,0 +1,10 @@ +# Pinned stable Rust toolchain for reproducible builds and CI. +# +# This is a stable release, not a nightly: the project's stability policy +# forbids release candidates and unstable defaults. Rustup-managed hosts will +# use this automatically; the distribution toolchain ignores the file. +[toolchain] +channel = "1.93.1" +profile = "minimal" +components = ["rustfmt", "clippy"] +targets = ["x86_64-unknown-linux-gnu"] diff --git a/installer/tests/vm/test_vmsafety.py b/installer/tests/vm/test_vmsafety.py index 6c8b8c4..6ec1b7f 100644 --- a/installer/tests/vm/test_vmsafety.py +++ b/installer/tests/vm/test_vmsafety.py @@ -9,6 +9,7 @@ in CI, not only during a live install: from __future__ import annotations +import json import os import socket import subprocess @@ -16,9 +17,12 @@ import tempfile import threading import unittest from pathlib import Path +from unittest import mock import vmsafety from vmsafety import ( + ARTIFACT_ENV_NAME, + ARTIFACT_ENV_SHA256, BLOCKED, FAIL, PASS, @@ -166,6 +170,53 @@ class ResultsTests(unittest.TestCase): return Path(tmp.name) +class ArtifactBindingTests(unittest.TestCase): + """The release tool binds evidence to a candidate digest; a harness run + must record the artifact it verified, or a stale pass could be replayed.""" + + def _tmp_results(self): + tmp = tempfile.NamedTemporaryFile(delete=False, suffix=".json") + tmp.close() + self.addCleanup(os.unlink, tmp.name) + return Path(tmp.name) + + def test_artifact_from_env_is_written(self): + with mock.patch.dict( + os.environ, + {ARTIFACT_ENV_NAME: "phoebus.iso", ARTIFACT_ENV_SHA256: "abc123"}, + ): + results = Results("unit") + results.pass_("one") + # write() is what records the binding, so exercise it directly. + path = results.write(self._tmp_results()) + data = json.loads(path.read_text()) + self.assertEqual(data["artifact"], {"name": "phoebus.iso", "sha256": "abc123"}) + + def test_artifact_absent_is_null(self): + clean = { + k: v + for k, v in os.environ.items() + if k not in (ARTIFACT_ENV_NAME, ARTIFACT_ENV_SHA256) + } + with mock.patch.dict(os.environ, clean, clear=True): + results = Results("unit") + results.pass_("one") + data = json.loads(results.write(self._tmp_results()).read_text()) + self.assertIsNone(data["artifact"]) + + def test_explicit_binding_is_not_overridden_by_env(self): + with mock.patch.dict( + os.environ, + {ARTIFACT_ENV_NAME: "env.iso", ARTIFACT_ENV_SHA256: "env-digest"}, + ): + results = Results("unit") + results.bind_artifact("explicit.iso", "explicit-digest") + data = json.loads(results.write(self._tmp_results()).read_text()) + self.assertEqual( + data["artifact"], {"name": "explicit.iso", "sha256": "explicit-digest"} + ) + + class FakeQmpServer(threading.Thread): """A tiny QMP server that records HMP commands and answers them.""" diff --git a/installer/tests/vm/vmsafety.py b/installer/tests/vm/vmsafety.py index beb8e8d..32b56a9 100644 --- a/installer/tests/vm/vmsafety.py +++ b/installer/tests/vm/vmsafety.py @@ -45,6 +45,12 @@ NOT_RUN = "NOT RUN" _TERMINAL = (PASS, FAIL, BLOCKED, SKIPPED) +# The candidate artifact a harness run is executed against. The release tool +# binds a gate report to a specific digest; recording it here is what lets a +# later verification step refuse stale evidence rather than trust any pass. +ARTIFACT_ENV_NAME = "PHOEBUS_VM_ARTIFACT" +ARTIFACT_ENV_SHA256 = "PHOEBUS_VM_ARTIFACT_SHA256" + class UnsafeDiskError(Exception): """A writable target violated the disposable-disk rules.""" @@ -81,10 +87,30 @@ class Results: self.scenario = scenario self.run_id = run_id or new_run_id(scenario) self.checks: list[Check] = [] + # The candidate artifact this run verifies (name + sha256), if known. + self.artifact: dict | None = None if strict is None: strict = os.environ.get("PHOEBUS_VM_STRICT", "").lower() in ("1", "yes", "true") self.strict = bool(strict) + # -- candidate artifact binding --------------------------------------- + def bind_artifact(self, name: str, sha256: str) -> dict: + """Record the candidate artifact (name + digest) this run verified.""" + self.artifact = {"name": name, "sha256": sha256} + return self.artifact + + def bind_artifact_from_env(self) -> dict | None: + """Bind from ``PHOEBUS_VM_ARTIFACT[_SHA256]`` when both are present. + + The drivers call this through :meth:`write`, so a run always records the + digest of the candidate it exercised (when the launcher supplied it). + """ + name = os.environ.get(ARTIFACT_ENV_NAME) + sha256 = os.environ.get(ARTIFACT_ENV_SHA256) + if name and sha256: + return self.bind_artifact(name, sha256) + return self.artifact + # -- recording --------------------------------------------------------- def _add(self, name: str, status: str, detail: str) -> Check: if status not in _TERMINAL: @@ -148,12 +174,15 @@ class Results: def write(self, path: str | Path) -> Path: path = Path(path) path.parent.mkdir(parents=True, exist_ok=True) + if self.artifact is None: + self.bind_artifact_from_env() payload = { "scenario": self.scenario, "run_id": self.run_id, "strict": self.strict, "exit_code": self.exit_code(), "counts": self.counts(), + "artifact": self.artifact, "checks": [c.to_dict() for c in self.checks], } path.write_text(json.dumps(payload, indent=2) + "\n")