diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 5be2dc2..7c73bdd 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -3,6 +3,47 @@ All notable changes are recorded here. The authoritative history is `git log`; this file is the curated, human-readable summary. +## 2026-09-26 — Security and release-readiness: trust anchor, executable gates, strengthened rollback + +- **Stage3 trust anchor is fixed in code.** `release_key_path()` no longer + honors `PHOEBUS_GENTOO_RELEASE_KEY`: production always uses the provisioned + `/usr/share/openpgp-keys/gentoo-release.asc`, and test-only injection goes + through the explicit `verify_digests_with_key` helper. A regression test + proves the environment variable is ignored. The pinned path is unchanged. + Host-level mechanism check (not VM evidence): the parser fixture matches + the real current DIGESTS byte-for-byte and the real DIGESTS verifies with a + Good signature from Gentoo's weekly release key. The full VM proof (rebuilt + live ISO + default unpinned install + tamper refusal) is recorded as + blocked with its exact prerequisites. +- **Release gates are executable and truthful.** `candidate_gates()` no + longer names `serial-driver.py checks` / `desktop` modes that no harness + accepts (`no-model-recovery` uses the real `boot` mode, + `desktop-session` uses `gui-driver.py boot`). `run_gates(--execute)` runs + each gate's argv in its own process: exit 0 → Passed, nonzero → Failed, + missing harness/firmware/seat/credential → NotRun, invalid command → + Failed. New tests cover real harness modes, pass/fail/not-run reporting, + isolation, invalid-command detection, and publish refusal on any + failed/not-run gate. `gates --execute` on an unconfigured host reports 0 + passed / 0 failed / 6 NotRun; `publish` refuses. A `gui-driver.py` + SyntaxError found by the new test is fixed. +- **Strengthened rollback rerun PASSED in a disposable VM** + (`serial-rollback-20260926T034218Z-7fab51ef`, PASS=11 FAIL=0, exit 0, no + secret leak): the root-marker creation is now mandatory and asserted + present before `sys undo`, the package DB changed (`ca398d71…` → + `fda3780a…`) and was restored, the marker is absent after the detached + reboot, `/home` survives, systemd runs. The unused `SERVE` variable was + removed (`shellcheck` clean). +- **Recovery-entry boot is now a distinct manual acceptance gate** with its + own procedure and pass criteria in `docs/VM-BOOT-VERIFICATION.md`, + recorded separately from normal `sys undo` (NOT RUN: interactive BLS-menu + selection is not automated). Secure Boot/UKI stays rejected and is filed + as a separate opt-in milestone in the roadmap; seat desktop, live AI, Snap + revision change, and NVIDIA remain open with exact prerequisites. +- **Tests:** `cargo test --workspace` 717/717, `test_vmsafety.py` 18/18, + `cargo fmt --check` and `clippy -D warnings` clean, release and static-pie + builds pass. (One `assistant_bridge` test flaked once under parallel load + and passes in isolation and on rerun.) + ## 2026-09-26 — Hardening pass: fail-closed stage3, truthful boot security, rollback acceptance - **Stage3 verification is fail-closed (security defect fixed).** The unpinned diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md index bd23357..566a614 100644 --- a/docs/HANDOFF.md +++ b/docs/HANDOFF.md @@ -3,6 +3,38 @@ 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. +- **Security/readiness follow-up (2026-09-26):** trust anchor + executable + gates + strengthened rollback PASS. + 1. **Stage3 trust anchor (fixed):** `release_key_path()` ignores + `PHOEBUS_GENTOO_RELEASE_KEY`; production always uses the provisioned + key, test injection only via explicit `verify_digests_with_key`. + Host-level Good-signature check of the real DIGESTS passes (not VM + evidence). VM proof blocked: needs a rebuilt live ISO + disposable + install (exact prerequisites in `docs/VM-BOOT-VERIFICATION.md`). + 2. **Release gates executable:** invalid `checks`/`desktop` modes fixed + (real `boot` modes), `--execute` runs each argv and reports + Passed/Failed/NotRun from evidence (unconfigured host: 0/0/6, publish + refuses). Found and fixed a `gui-driver.py` SyntaxError. 6 new tests. + 3. **Strengthened rollback rerun PASSED** + (`serial-rollback-20260926T034218Z-7fab51ef`, PASS=11 FAIL=0, exit 0, + no leak, overlay `rollback-accept-8.qcow2`): mandatory + `===ROLLBACK-MARKER present===` before undo, DB `ca398d71…`→`fda3780a…` + →restored, marker absent after detached reboot, `/home` survives, + systemd running. `SERVE` shellcheck fix included. + 4. **Recovery-entry boot** is now a distinct manual gate with its own + procedure (NOT RUN). Roadmap no longer lists passed `sys undo` as + unfinished; Secure Boot filed as a separate opt-in milestone. + 5. Quality gates: `cargo fmt --check`, `clippy --workspace --all-targets + -- -D warnings`, `cargo test --workspace` 717/717 (one + `assistant_bridge` flake under parallel load, green in isolation and + on rerun), release + static-pie builds, `test_vmsafety.py` 18/18, + `shellcheck` clean. Seat desktop, live AI, Snap revision/strict, and + NVIDIA stay open with exact prerequisites (STATUS). +- **Interface contract (unchanged):** ordinary requests use AI; only explicit + `--legacy` selects deterministic handling; source flags constrain the AI and + never bypass it; a missing model stops the workflow and offers the exact + `--legacy` command without executing it. + - **Hardening pass (2026-09-26):** stage3 fail-closed + truthful boot security + rollback acceptance PASS. 1. **Stage3 (security defect, fixed):** the unpinned path warned and diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 7bf43b6..63cf5e3 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -14,11 +14,11 @@ more interesting. Status vocabulary: **Done**, **Partial**, **Next**, **Later**. | 7 | Finish Flatpak | Partial | `flatpak 1.18.1` installed, flathub configured; bounded typed `flatpak_*` actions added; no app installed yet | | 8 | Instrument source/binary policy | Done | measured compile times harvested from `emerge.log` (326 entries); resolved-effect previews added | | 9 | Background update preparation | Partial | distfile fetch VM-verified; `--buildpkgonly` skipped while deps need merging (recorded Ready); activation explicit | -| 10 | Snapshots / rollback | Partial | snapshot sets + history VM-verified on Btrfs; `sys undo` acceptance PASSED on a fresh disposable clone (`serial-rollback-20260926T030237Z-912f6386` PASS=11 FAIL=0: DB changed then restored, root marker gone, `/home` survives, boot running); retention + free-space gate unit-tested; offline recovery-entry boot remains a manual gate | +| 10 | Snapshots / rollback | Done (normal `sys undo`); recovery-entry boot manual | normal `sys undo` acceptance PASSED on a fresh disposable clone (`serial-rollback-20260926T030237Z-912f6386` PASS=11 FAIL=0: DB changed then restored, root marker gone, `/home` survives, boot running); retention + free-space gate unit-tested; selecting the Phoebus Recovery (known-good snapshot) BLS entry offline with no network/model is a distinct manual acceptance gate (see `docs/VM-BOOT-VERIFICATION.md`), separate from `sys undo` | | 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 | Done | history, enable/disable, inspect, install, prepare-updates VM-verified; target-root consistency, execution-boundary validation, truthful `ask` failure, full transaction outcomes, empty-vs-unestablished plans, start/stop/restart + flatpak/nix/snapshot commands, deterministic `--legacy` administration, audited `--broker`/`--legacy` gates, unified multi-source updates, quiet proactive assistance, shared service layer (`phoebus_installer::service`), and 23-case VM acceptance suite (`sys-acceptance.sh` 23/23 PASS) | | 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-plan tooling; release gates are executable (`gates --execute` runs each gate's real command and reports Passed/Failed/NotRun from evidence; publish refuses unless every gate passed); no CI runner has executed the VM/seat/model gates end to end | | 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) | @@ -38,9 +38,11 @@ more interesting. Status vocabulary: **Done**, **Partial**, **Next**, **Later**. in a graphical, seat-providing VM and run the gates in `docs/VM-BOOT-VERIFICATION.md`. Default promotion was an explicit owner decision; verification is still required to claim stability. -3. **Rollback VM acceptance**: deliberately break an update in the disposable - VM, run `sys undo`, reboot detached, verify package-state consistency, then - boot the recovery entry with no network or model (ADR 0007). +3. **Offline recovery-entry boot**: select the Phoebus Recovery (known-good + snapshot) BLS entry with no network and no model, verify the selected + snapshot, boot, and basic deterministic `sys` operation — recorded + separately from the passed normal `sys undo` acceptance (ADR 0007, + `docs/VM-BOOT-VERIFICATION.md`). 4. **Binary strategy**: keep the official signed binhost for packages whose USE matches and use Flatpak/Nix for other binaries; do not publish a private Gentoo binhost (ADR 0006). Verify with `emerge -pv` and record reuse. @@ -55,6 +57,12 @@ more interesting. Status vocabulary: **Done**, **Partial**, **Next**, **Later**. ## Later +- Secure Boot / UKI as a separate opt-in milestone (not enabled by default): + key ownership and enrollment, signed UKIs containing kernel, initrd and + command line, signed normal/previous/recovery entries, atomic updates and + rollback, plus OVMF positive and tamper tests. Ordinary BLS entries never + imply Secure Boot protection. Blocked until stage3 trust, recovery, and + update paths are reliable. - Full recovery environment (network, LUKS, Btrfs, Portage/kernel repair). - Automated biweekly ISO candidate build with tiered tests and atomic publish. - AI OS sandbox (systemd sandboxing / namespaces / bubblewrap / Landlock). diff --git a/docs/STATUS.md b/docs/STATUS.md index faa9615..00a98a3 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -58,6 +58,7 @@ Booting that recovery entry offline remains a manual gate. | Btrfs subvolumes + swapfile | yes | yes | yes | no | | fstab / crypttab generation | yes | yes | yes | no | | stage3 fetch + verify (pinned SHA-256 or signed DIGESTS) + extract | yes | yes (both paths; every failure branch incl. missing verifier/key/DIGESTS/entry, nonzero exit, cannot-start) | yes (pinned path; unpinned path needs the live-image key) | n/a | +| stage3 trust anchor (fixed provisioned key) | yes | yes (`release_key_path` ignores `PHOEBUS_GENTOO_RELEASE_KEY`; test-only injection only via explicit `verify_digests_with_key`) | no (unpinned VM proof needs a rebuilt live ISO + disposable install; host-level Good-signature check of the real DIGESTS noted below, not VM evidence) | n/a | | Portage config + sync + getuto | yes | yes | yes | n/a | | Signed Gentoo binary install | yes | yes | yes | n/a | | Source package compilation | yes | yes | yes | n/a | @@ -82,7 +83,7 @@ Booting that recovery entry offline remains a manual gate. | Btrfs snapshots + history | yes | yes | yes | no | | Coordinated snapshot sets (`@` + `@var`) | yes | yes | no | no | | Btrfs rollback (`sys undo`) | yes | yes | yes (rollback acceptance `serial-rollback-20260926T030237Z-912f6386` PASS=11 FAIL=0) | no | -| Recovery/known-good BLS entry | yes | yes | present + snapshot-based (asserted in the rollback run; offline boot is a manual gate) | no | +| Recovery/known-good BLS entry | yes | yes | present + snapshot-based (asserted in the rollback run; selecting it offline with no network/model is a distinct manual acceptance gate with its own procedure and evidence, see `docs/VM-BOOT-VERIFICATION.md`) | no | | Snapshot retention + free-space gate | yes | yes | no | no | | AI typed proposals + evidence review | yes | yes | fixture end-to-end | n/a | | AI guided install (DeepSeek/OpenAI) | yes | yes | fixture path only (no live call) | n/a | @@ -150,7 +151,7 @@ Booting that recovery entry offline remains a manual gate. | GUI readiness refresh / AI revalidation / keyboard nav | yes | yes (Rust) | VM harness regressions | 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 (NotRun-is-not-pass; tamper/publish-refusal exercised via host CLI) | no (no end-to-end candidate: VM/graphical/model gates need a runner) | n/a | +| Release gates + atomic publish | yes | yes (executable: every gate names a real harness mode; `--execute` runs each command in its own process and reports Passed/Failed/NotRun from evidence; invalid commands, isolation, failed-gate and publish refusal covered) | no (no end-to-end candidate: VM/graphical/model gates need a runner; unconfigured host reports 0 passed / 0 failed / 6 NotRun with exact missing prerequisites) | n/a | | `sys` verbs | yes | yes | yes | no | | OpenCode pinned bootstrap | yes | yes | no | n/a | | Release manifest/verify | yes | yes (host CLI: manifest, verify, tampered-artifact refusal) | no | n/a | @@ -160,7 +161,7 @@ Booting that recovery entry offline remains a manual gate. | NVIDIA kernel/module/initramfs update coordination (`@module-rebuild`) | yes | yes | no | no | | NVIDIA live GPU decision + real nouveau fallback | yes | yes (fixtures + CLI) | no | no | | Live GUI broker scoped sudoers (no `NOPASSWD: ALL`) | yes | yes (`visudo`) | no | n/a | -| Rollback acceptance harness mode | yes | yes (bash -n/unit + vacuous-pass guards) | yes (destructive gate `serial-rollback-20260926T030237Z-912f6386` PASS=11 FAIL=0) | no | +| Rollback acceptance harness mode | yes | yes (bash -n/unit + vacuous-pass guards) | yes (destructive gate `serial-rollback-20260926T030237Z-912f6386` PASS=11 FAIL=0; root-marker creation is mandatory and asserted present before undo, absent after the detached reboot) | no | | Desktop assistant GUI (`phoebus-assistant`) | yes | yes | yes (live VM layout) | no | | Desktop assistant JSON-RPC bridge (`sys --assistant-bridge`) | yes | yes | yes (acceptance matrix) | n/a | | AI-first administration contract (`sys install`, `please`, `ask`) | yes | yes | yes (acceptance matrix) | no | @@ -293,15 +294,18 @@ Booting that recovery entry offline remains a manual gate. 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`. A local isolated candidate run - (2026-09-26) exercised manifest generation (2 artifacts), verification, +- **Release automation** now has executable gates, a report, atomic publish + and signing command helpers, but no gate has been executed by a configured + CI runner. `gates --execute` runs each gate's real command in its own + process (exit 0 → Passed, nonzero → Failed, missing harness/firmware/seat/ + credential → NotRun) and never manufactures a pass. A local run (2026-09-26) + exercised manifest generation (2 artifacts), verification, tampered-artifact refusal, and publish refusal against a NotRun gate report; - `gates --execute` reports 0 passed / 6 NotRun because every candidate gate - requires a VM, a graphical seat, or a model. No release was published and - `latest.iso` untouched. Minimal repeatable setup: register a Forgejo Actions - runner (`act_runner`) so `.forgejo/workflows/ci.yml` executes the gates. + `gates --execute` on an unconfigured host reports 0 passed / 0 failed / + 6 NotRun with the exact missing prerequisite per gate (OVMF_CODE/OVMF_VARS + unset, no model credential). No release was published and `latest.iso` + untouched. Minimal repeatable setup: register a Forgejo Actions runner + (`act_runner`) so `.forgejo/workflows/ci.yml` executes the gates. - 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 @@ -316,3 +320,11 @@ Booting that recovery entry offline remains a manual gate. - `sys undo` is implemented with the default-subvolume, fstab, kernel-cmdline and BLS handling described in ADR 0007; its destructive VM acceptance gate passed in this session (`serial-rollback-20260926T030237Z-912f6386`). +- **Stage3 signed-DIGESTS mechanism (host-level, not VM evidence).** The + parser fixture matches the real current DIGESTS byte-for-byte, and the real + DIGESTS for `stage3-amd64-systemd-20260920T170055Z.tar.xz` verifies with a + Good signature from Gentoo's Automated Weekly Release Key at host level. + The full VM proof (rebuilt live ISO carrying the provisioned key, default + unpinned install, tampered signature/digest/archive refusal) still needs a + disposable install run and is recorded as blocked in + `docs/VM-BOOT-VERIFICATION.md`. diff --git a/docs/VM-BOOT-VERIFICATION.md b/docs/VM-BOOT-VERIFICATION.md index 07e30a8..691a3a3 100644 --- a/docs/VM-BOOT-VERIFICATION.md +++ b/docs/VM-BOOT-VERIFICATION.md @@ -763,6 +763,74 @@ detached boot verification with the live ISO removed. - Not covered by this run: the mutate group (`SYS_ACCEPTANCE_MUTATE=1`), recovery boot, strict Snap confinement, and a revision-changing Snap update. +## 2026-09-26 — Security and release-readiness follow-up (COMPLETED) + +- **Stage3 trust anchor is fixed, not VM-proven.** `release_key_path()` no + longer reads `PHOEBUS_GENTOO_RELEASE_KEY`: production always uses the + provisioned `/usr/share/openpgp-keys/gentoo-release.asc`, and test-only + injection goes through the explicit `verify_digests_with_key` helper (19 + stage3 tests pass). Host-level mechanism check (not VM evidence): the + committed parser fixture matches the real current DIGESTS byte-for-byte, + and the real DIGESTS for + `stage3-amd64-systemd-20260920T170055Z.tar.xz` verifies with a Good + signature from Gentoo's Automated Weekly Release Key. + **Blocked VM proof:** rebuild the live image (ships gnupg + the + fingerprint-checked key) and run the default unpinned stage3 install on a + disposable qcow2, verifying the real signed DIGESTS and downloaded hash + plus tampered signature/digest/archive refusal. Prerequisite: a live-ISO + rebuild (multi-GB; host has ~26 GiB free, shared with VM disks) and a full + install cycle; no ISO was rebuilt in this session. +- **Rollback gate strengthened, rerun in progress.** `rollback-guest.sh` + creation of `/etc/phoebus/rollback-broken.txt` is now mandatory + (`mkdir -p`, write, `===ROLLBACK-MARKER present===`, exit 1 if absent; + the old `|| true` could have hidden a failed break). The absent-afterward + assertion stays where it belongs: after the detached reboot + (`rollback-verify.sh` + driver `rollback-root-restored`), because `sys + undo` activates the restored generation on the next boot. The unused + `SERVE` variable was removed (`shellcheck` clean). +- **Strengthened rerun PASSED** (`serial-rollback-20260926T034218Z-7fab51ef`, + PASS=11 FAIL=0, exit 0, overlay `rollback-accept-8.qcow2` on + `fresh-install-1.qcow2`, logs under + `/var/tmp/phoebus-vm/serial-rollback-20260926T034218Z-89357549/`): known-good + DB `ca398d71…` → mandatory `===ROLLBACK-MARKER present===` → controlled + `app-misc/hello` install (DB `fda3780a…`, changed as required) → `sys undo` + rc=0 → detached reboot (DB restored to `ca398d71…`, root marker **absent**, + `/home` survives, systemd `running`, modules present, recovery entry + present, status recorded). No secret leak in either transcript + (`SECRET_LEAK_FOUND` count 0 in both). +- **Recovery-entry acceptance is a distinct manual gate** (separate from + normal `sys undo`). Procedure: on a disposable installed disk, select + "Phoebus Recovery (known-good snapshot)" in the systemd-boot menu with the + network unavailable and no model configured; verify the booted snapshot + identity (`btrfs subvolume show /`, recovery entry options), reach a + login, and run basic deterministic `sys` operation (`sys history`, + `sys rollback status --legacy`, one read-only query). Pass criteria: the + selected snapshot boots, systemd runs, `sys --legacy` works, and `sys ask` + without a model fails truthfully with the exact `--legacy` fallback + offered. Status: NOT RUN — the harness records the entry but does not + select it (interactive BLS-menu selection is not automated). +- **Release gates are executable and truthful.** `candidate_gates()` no + longer names `serial-driver.py checks` / `desktop` modes no harness + accepts: `no-model-recovery` uses the real `boot` mode (with `BOOT_CHECKS` + running `sys --legacy`), `desktop-session` uses the real graphical + harness (`gui-driver.py boot`). `run_gates(--execute)` runs each gate's + argv in its own process and reports Passed/Failed/NotRun from evidence + (missing harness/firmware/seat/credential → NotRun; nonzero exit → + Failed; invalid command → Failed). A `gui-driver.py do_boot` SyntaxError + (unclosed `assert_true(`) found by the new gate-mode test is fixed. + Evidence: `phoebus-release gates --execute` on an unconfigured host → 0 + passed / 0 failed / 6 NotRun with exact missing prerequisites, and + `publish` refuses against that report (exit 1). +- **Seat desktop, live AI, Snap revision change, NVIDIA:** unchanged and + explicitly open. Installed Mango+DMS under a seat needs a + seat-providing VM or physical VT; a live AI call needs a responsive local + model or an authorized provider credential (fixture routing/failure tests + pass; the gate is NotRun with the exact missing credential); a + revision-changing Snap refresh needs a Store snap with a newer revision + plus an AppArmor-ready guest kernel for strict confinement (existing + partial-confinement/no-op-refresh evidence stays labeled as such); NVIDIA + needs a GPU or authorized passthrough (see below). + ## Known remaining work - The graphical session was verified with the **headless** wlroots backend diff --git a/installer-rs/crates/phoebus-executor/src/stage3.rs b/installer-rs/crates/phoebus-executor/src/stage3.rs index 2acf7fd..cdf9a81 100644 --- a/installer-rs/crates/phoebus-executor/src/stage3.rs +++ b/installer-rs/crates/phoebus-executor/src/stage3.rs @@ -32,13 +32,16 @@ use crate::exec::Exec; /// fetches an unauthenticated key. pub const GENTOO_RELEASE_KEY: &str = "/usr/share/openpgp-keys/gentoo-release.asc"; -/// Path of the trusted Gentoo release key. `PHOEBUS_GENTOO_RELEASE_KEY` -/// overrides it for tests; production always uses [`GENTOO_RELEASE_KEY`]. +/// Path of the trusted Gentoo release key. +/// +/// The trust anchor is fixed at build time: production always uses +/// [`GENTOO_RELEASE_KEY`], which the live image provisions and +/// fingerprint-checks at build time. No environment variable, config value, +/// or mirror-supplied data can select a different key: key injection exists +/// only through the explicit test-only `verify_digests_with_key` helper +/// below, never through the production path. pub fn release_key_path() -> PathBuf { - match std::env::var("PHOEBUS_GENTOO_RELEASE_KEY") { - Ok(dir) if !dir.is_empty() => PathBuf::from(dir), - _ => PathBuf::from(GENTOO_RELEASE_KEY), - } + PathBuf::from(GENTOO_RELEASE_KEY) } pub fn require_tools(exec: &Exec) -> Result<()> { @@ -696,13 +699,15 @@ e6ae2b1930064878203ab8d134fc081a252c8073730628222ee1cc4a201a56ed9c64dc7b19f1fa40 } #[test] - fn release_key_path_override_is_honoured() { - // The only test that touches this variable; every other stage3 test - // passes its key explicitly, so no parallel test can observe it. + fn release_key_path_ignores_environment_injection() { + // The trust anchor is fixed: even if a caller sets the historical + // override variable, production still uses the provisioned key. + // Test-only key injection goes through `verify_digests_with_key` + // with an explicit key path, never through the environment. let dir = tempfile::tempdir().unwrap(); let custom = dir.path().join("custom.asc"); std::env::set_var("PHOEBUS_GENTOO_RELEASE_KEY", &custom); - assert_eq!(release_key_path(), custom); + assert_eq!(release_key_path(), PathBuf::from(GENTOO_RELEASE_KEY)); std::env::remove_var("PHOEBUS_GENTOO_RELEASE_KEY"); assert_eq!(release_key_path(), PathBuf::from(GENTOO_RELEASE_KEY)); } 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..d1144ca 100644 --- a/installer-rs/crates/phoebus-installer/src/bin/phoebus-release.rs +++ b/installer-rs/crates/phoebus-installer/src/bin/phoebus-release.rs @@ -51,9 +51,10 @@ 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. `--execute` runs every gate whose + /// prerequisites are met (VM firmware variables, graphical seat, model + /// credential) in its own process; missing prerequisites are recorded as + /// not run and a nonzero exit as failed. A pass is never manufactured. Gates { #[arg(long, default_value = "gate-report.json")] output: PathBuf, @@ -166,14 +167,14 @@ fn run() -> std::result::Result<(), Box> { Command::Gates { output, execute } => { let report = run_gates(execute); report.save(&output)?; + let count = |s: phoebus_installer::release::GateStatus| { + report.results.iter().filter(|r| r.status == s).count() + }; println!( - "wrote {} ({} passed, {} not run)", + "wrote {} ({} passed, {} failed, {} not run)", output.display(), - report - .results - .iter() - .filter(|r| r.status == phoebus_installer::release::GateStatus::Passed) - .count(), + count(phoebus_installer::release::GateStatus::Passed), + count(phoebus_installer::release::GateStatus::Failed), report.not_run() ); if !execute { diff --git a/installer-rs/crates/phoebus-installer/src/release.rs b/installer-rs/crates/phoebus-installer/src/release.rs index 389baf9..4658050 100644 --- a/installer-rs/crates/phoebus-installer/src/release.rs +++ b/installer-rs/crates/phoebus-installer/src/release.rs @@ -206,10 +206,24 @@ impl GateReport { } } +/// Modes the headless serial harness accepts (`serial-driver.py` `main`). +/// A gate naming any other mode would fail at runtime; the +/// `gate_commands_are_real_harness_modes` test pins this list. +pub const SERIAL_DRIVER_MODES: &[&str] = &["install", "boot", "rollback"]; +/// Modes the graphical harness accepts (`gui-driver.py` `run`). +pub const GUI_DRIVER_MODES: &[&str] = &["gui", "opencode", "gui-install", "install", "boot"]; + /// The candidate checks. Commands are the real harness invocations, not /// placeholders, so a configured runner executes exactly what is documented. +/// +/// - `no-model-recovery` reuses the real `boot` mode: the runner boots the +/// installed disk detached with the model unavailable and `BOOT_CHECKS` +/// exercising deterministic `sys --legacy` operation (see the VM record). +/// - `desktop-session` uses the real graphical harness (`gui-driver.py boot`) +/// on a seat-providing VM; there is no headless `desktop` mode. pub fn candidate_gates() -> Vec { let driver = "installer/tests/vm/serial-driver.py"; + let gui_driver = "installer/tests/vm/gui-driver.py"; vec![ Gate { name: "install".into(), @@ -225,15 +239,15 @@ pub fn candidate_gates() -> Vec { }, Gate { name: "no-model-recovery".into(), - description: "operate and recover with no model connected".into(), + description: "boot detached with no model; BOOT_CHECKS runs sys --legacy".into(), requires: GateRequirement::Vm, - command: vec!["python3".into(), driver.into(), "checks".into()], + command: vec!["python3".into(), driver.into(), "boot".into()], }, Gate { name: "desktop-session".into(), description: "graphical seat: launch, lock, suspend, log out".into(), requires: GateRequirement::GraphicalSeat, - command: vec!["python3".into(), driver.into(), "desktop".into()], + command: vec!["python3".into(), gui_driver.into(), "boot".into()], }, Gate { name: "updates-and-rollback".into(), @@ -250,10 +264,217 @@ pub fn candidate_gates() -> Vec { ] } -/// 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 { +/// A gate command is argv executed directly, never via a shell. Reject empty +/// commands and shell metacharacters so a gate definition cannot smuggle in +/// `sh -c` indirection or chained commands. +pub fn validate_gate_command(gate: &Gate) -> Result<(), String> { + if gate.command.is_empty() { + return Err(format!( + "gate '{}' declares no executable command", + gate.name + )); + } + if gate.command[0].is_empty() { + return Err(format!("gate '{}' has an empty program", gate.name)); + } + for arg in &gate.command { + if arg.contains('\0') { + return Err(format!("gate '{}' command contains NUL", gate.name)); + } + } + let prog = &gate.command[0]; + for meta in [";", "|", "&", "`", "$(", "\n"] { + if prog.contains(meta) { + return Err(format!( + "gate '{}' program must be a binary, not a shell snippet", + gate.name + )); + } + } + Ok(()) +} + +fn program_exists(prog: &str) -> bool { + if prog.contains('/') { + return Path::new(prog).is_file(); + } + std::env::var_os("PATH") + .is_some_and(|paths| std::env::split_paths(&paths).any(|d| d.join(prog).is_file())) +} + +/// The unmet prerequisite for a gate, if any. A missing prerequisite reports +/// `NotRun`, never a pass or a failure. Credential values are never included +/// in the reason. +pub fn gate_prerequisite_missing(gate: &Gate) -> Option { + match gate.requires { + GateRequirement::Host => { + if program_exists(&gate.command[0]) { + None + } else { + Some(format!( + "missing prerequisite: program '{}' not found on PATH", + gate.command[0] + )) + } + } + GateRequirement::Vm => { + if gate.command.len() >= 2 { + let driver = &gate.command[1]; + if !Path::new(driver).is_file() { + return Some(format!( + "missing prerequisite: harness '{driver}' not found" + )); + } + } + for var in ["OVMF_CODE", "OVMF_VARS"] { + if std::env::var_os(var).is_none() { + return Some(format!("missing prerequisite: {var} is not set")); + } + } + if !program_exists(&gate.command[0]) { + return Some(format!( + "missing prerequisite: program '{}' not found on PATH", + gate.command[0] + )); + } + None + } + GateRequirement::GraphicalSeat => { + if gate.command.len() >= 2 { + let driver = &gate.command[1]; + if !Path::new(driver).is_file() { + return Some(format!( + "missing prerequisite: harness '{driver}' not found" + )); + } + } + for var in ["OVMF_CODE", "OVMF_VARS"] { + if std::env::var_os(var).is_none() { + return Some(format!("missing prerequisite: {var} is not set")); + } + } + let seat = Path::new("/dev/dri").exists() + || std::env::var_os("WAYLAND_DISPLAY").is_some() + || std::env::var_os("DISPLAY").is_some() + || std::env::var_os("PHOEBUS_GRAPHICAL_SEAT").is_some(); + if !seat { + return Some( + "missing prerequisite: no graphical seat (/dev/dri, WAYLAND_DISPLAY, DISPLAY, or PHOEBUS_GRAPHICAL_SEAT)".to_string(), + ); + } + if !program_exists(&gate.command[0]) { + return Some(format!( + "missing prerequisite: program '{}' not found on PATH", + gate.command[0] + )); + } + None + } + GateRequirement::Model => { + let key_file = std::env::var_os("PHOEBUS_AI_KEY_FILE") + .map(|p| Path::new(&p).is_file()) + .unwrap_or(false); + let env_key = ["OPENAI_API_KEY", "DEEPSEEK_API_KEY"] + .iter() + .any(|v| std::env::var_os(v).is_some_and(|s| !s.is_empty())); + if !key_file && !env_key { + return Some( + "missing prerequisite: no model credential (PHOEBUS_AI_KEY_FILE or OPENAI_API_KEY/DEEPSEEK_API_KEY)".to_string(), + ); + } + if !program_exists(&gate.command[0]) { + return Some(format!( + "missing prerequisite: program '{}' not found on PATH", + gate.command[0] + )); + } + None + } + GateRequirement::CiRunner => { + Some("missing prerequisite: no configured CI runner".to_string()) + } + } +} + +fn bound_tail(text: &str, max_chars: usize) -> String { + let trimmed = text.trim(); + if trimmed.len() <= max_chars { + return trimmed.to_string(); + } + format!("…{}", &trimmed[trimmed.len() - max_chars..]) +} + +/// Execute one gate: run its argv, capture process status and output, and +/// report from evidence. Each gate runs in its own process; a failure never +/// stops the remaining gates (see the isolation test). +fn execute_gate(gate: &Gate) -> GateResult { + if let Err(problem) = validate_gate_command(gate) { + return GateResult { + name: gate.name.clone(), + status: GateStatus::Failed, + detail: format!("invalid gate command: {problem}"), + }; + } + if let Some(missing) = gate_prerequisite_missing(gate) { + return GateResult { + name: gate.name.clone(), + status: GateStatus::NotRun, + detail: missing, + }; + } + let output = std::process::Command::new(&gate.command[0]) + .args(&gate.command[1..]) + .output(); + match output { + Err(e) if e.kind() == std::io::ErrorKind::NotFound => GateResult { + name: gate.name.clone(), + status: GateStatus::NotRun, + detail: format!( + "missing prerequisite: program '{}' could not start ({e})", + gate.command[0] + ), + }, + Err(e) => GateResult { + name: gate.name.clone(), + status: GateStatus::Failed, + detail: format!("gate '{}' could not run: {e}", gate.name), + }, + Ok(out) => { + let mut combined = String::new(); + combined.push_str(&String::from_utf8_lossy(&out.stdout)); + if !out.stderr.is_empty() { + combined.push_str("\n--- stderr ---\n"); + combined.push_str(&String::from_utf8_lossy(&out.stderr)); + } + let tail = bound_tail(&combined, 2000); + if out.status.success() { + GateResult { + name: gate.name.clone(), + status: GateStatus::Passed, + detail: if tail.is_empty() { + format!("exit {}", out.status) + } else { + format!("exit {}; {tail}", out.status) + }, + } + } else { + GateResult { + name: gate.name.clone(), + status: GateStatus::Failed, + detail: if tail.is_empty() { + format!("exit {}", out.status) + } else { + format!("exit {}; {tail}", out.status) + }, + } + } + } + } +} + +/// Run a gate list, isolating each gate in its own process. Exported for +/// tests; production uses [`run_gates`]. +pub fn run_gate_list(execute: bool, gates: &[Gate]) -> GateReport { let now = std::time::SystemTime::now() .duration_since(std::time::UNIX_EPOCH) .map(|d| d.as_secs()) @@ -263,24 +484,30 @@ pub fn run_gates(execute: bool) -> GateReport { 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")) + for gate in gates { + if !execute { + report.results.push(GateResult { + name: gate.name.clone(), + status: GateStatus::NotRun, + detail: format!("not run (requires {})", gate.requires.as_str()), + }); } else { - ( - GateStatus::NotRun, - format!("not run (requires {})", gate.requires.as_str()), - ) - }; - report.results.push(GateResult { - name: gate.name, - status, - detail, - }); + report.results.push(execute_gate(gate)); + } } report } +/// Run the candidate gates. With `execute = false` every gate is recorded as +/// `NotRun`, so a report never claims a check that did not run. With +/// `execute = true` each gate's real command runs in its own process: +/// exit 0 is `Passed`, a nonzero exit is `Failed`, and a missing +/// prerequisite (harness, OVMF firmware variables, seat, or model +/// credential) is `NotRun`. A pass is never manufactured from a plan. +pub fn run_gates(execute: bool) -> GateReport { + run_gate_list(execute, &candidate_gates()) +} + // --------------------------------------------------------------------------- // Signing and atomic publication // --------------------------------------------------------------------------- @@ -397,6 +624,148 @@ mod tests { assert!(report.results.iter().all(|r| r.detail.contains("requires"))); } + #[test] + fn gate_commands_are_real_harness_modes() { + // Regression: candidate_gates once named `serial-driver.py checks`, + // `serial-driver.py desktop` (and appliance desktop), modes no + // harness accepts. Every declared gate must name a real mode. + for gate in candidate_gates() { + validate_gate_command(&gate) + .unwrap_or_else(|e| panic!("gate '{}' has no real command: {e}", gate.name)); + let argv = &gate.command; + if argv[0] == "python3" && argv.len() >= 3 { + let harness = argv[1].as_str(); + let mode = argv[2].as_str(); + if harness.ends_with("serial-driver.py") { + assert!( + SERIAL_DRIVER_MODES.contains(&mode), + "gate '{}' names serial-driver mode '{mode}', accepted: {SERIAL_DRIVER_MODES:?}", + gate.name + ); + } else if harness.ends_with("gui-driver.py") { + assert!( + GUI_DRIVER_MODES.contains(&mode), + "gate '{}' names gui-driver mode '{mode}', accepted: {GUI_DRIVER_MODES:?}", + gate.name + ); + } else { + panic!("gate '{}' names an unknown harness '{harness}'", gate.name); + } + } + } + } + + fn host_gate(name: &str, program: &str, args: &[&str]) -> Gate { + Gate { + name: name.into(), + description: "test gate".into(), + requires: GateRequirement::Host, + command: std::iter::once(program.to_string()) + .chain(args.iter().map(|a| a.to_string())) + .collect(), + } + } + + #[test] + fn execute_reports_pass_fail_and_notrun_from_evidence() { + // Exit 0 is Passed, nonzero is Failed, a missing program is NotRun, + // and an empty (non-executable) command is Failed — never a pass. + let gates = vec![ + host_gate("ok", "/bin/true", &[]), + host_gate("bad", "/bin/false", &[]), + host_gate("missing", "/nonexistent-phoebus-gate-program", &[]), + Gate { + name: "manual".into(), + description: "no executable command".into(), + requires: GateRequirement::Host, + command: vec![], + }, + ]; + let report = run_gate_list(true, &gates); + let status = |n: &str| { + report + .results + .iter() + .find(|r| r.name == n) + .unwrap_or_else(|| panic!("missing result {n}")) + .status + }; + assert_eq!(status("ok"), GateStatus::Passed); + assert_eq!(status("bad"), GateStatus::Failed); + assert_eq!(status("missing"), GateStatus::NotRun); + assert_eq!(status("manual"), GateStatus::Failed); + assert!( + !report.all_passed(), + "a mixed report must not count as passed" + ); + } + + #[test] + fn invalid_commands_are_detected_not_executed() { + let gate = Gate { + name: "shell".into(), + description: "must not run through a shell".into(), + requires: GateRequirement::Host, + command: vec!["sh; rm -rf /".into()], + }; + assert!(validate_gate_command(&gate).is_err()); + let report = run_gate_list(true, &[gate]); + assert_eq!(report.results[0].status, GateStatus::Failed); + assert!(report.results[0].detail.contains("invalid gate command")); + } + + #[test] + fn gates_are_isolated_a_failure_does_not_stop_the_rest() { + let gates = vec![ + host_gate("first-fails", "/bin/false", &[]), + host_gate("second-passes", "/bin/true", &[]), + ]; + let report = run_gate_list(true, &gates); + assert_eq!(report.results.len(), 2); + assert_eq!(report.results[0].status, GateStatus::Failed); + assert_eq!(report.results[1].status, GateStatus::Passed); + } + + #[test] + fn publish_requires_every_gate_passed() { + let passing = GateReport { + version: "test".into(), + created_unix: 0, + results: vec![GateResult { + name: "ok".into(), + status: GateStatus::Passed, + detail: "exit 0".into(), + }], + }; + assert!(passing.all_passed()); + for status in [GateStatus::Failed, GateStatus::NotRun] { + let report = GateReport { + version: "test".into(), + created_unix: 0, + results: vec![ + GateResult { + name: "ok".into(), + status: GateStatus::Passed, + detail: "exit 0".into(), + }, + GateResult { + name: "other".into(), + status, + detail: "evidence".into(), + }, + ], + }; + assert!( + !report.all_passed(), + "publish must be refused when any gate is {status:?}" + ); + } + assert!( + !GateReport::default().all_passed(), + "an empty report must not authorize publication" + ); + } + #[test] fn atomic_publish_keeps_the_previous_release() { let dir = tempfile::tempdir().unwrap(); diff --git a/installer/tests/vm/gui-driver.py b/installer/tests/vm/gui-driver.py index 857eb15..83e3a03 100644 --- a/installer/tests/vm/gui-driver.py +++ b/installer/tests/vm/gui-driver.py @@ -1378,6 +1378,8 @@ class Driver: self.results.assert_true( "boot-sys-installed", "no transactions recorded" in sys_status, + f"sys CLI check: {sys_status}", + ) self.shot("boot-desktop", "booted desktop", "boot", "graphical desktop or login screen") try: self.shell("sync; echo phoebus-user-test | sudo -S systemctl poweroff >/dev/null 2>&1 || true; echo POW", diff --git a/installer/tests/vm/rollback-guest.sh b/installer/tests/vm/rollback-guest.sh index c521a57..611fff1 100755 --- a/installer/tests/vm/rollback-guest.sh +++ b/installer/tests/vm/rollback-guest.sh @@ -20,7 +20,6 @@ if [ "$(id -u)" != "0" ]; then exit 1 fi -SERVE="${SERVE_URL:-http://10.0.2.2:8000}" if [[ -n "${SYS_BIN:-}" ]]; then SYS="$SYS_BIN" elif [[ -x /usr/local/bin/sys ]]; then @@ -73,8 +72,19 @@ fi # update: it changes both the root subvolume and /var/db/pkg, and a snapshot # can restore it. A root marker proves the root generation too. The break # must change the package database; otherwise the restore comparison below -# would pass without proving anything. -printf 'broken by rollback acceptance\n' > /etc/phoebus/rollback-broken.txt 2>/dev/null || true +# would pass without proving anything. The marker is mandatory: `sys undo` +# restores the snapshotted root on the next boot, so the marker must exist +# before undo (asserted here) and be absent after the detached reboot +# (asserted by rollback-verify.sh and the host driver, not live: the live +# root still shows the marker until the reboot activates the restored +# generation). +mkdir -p /etc/phoebus +printf 'broken by rollback acceptance\n' > /etc/phoebus/rollback-broken.txt +if [[ ! -f /etc/phoebus/rollback-broken.txt ]]; then + echo "===ROLLBACK-MARKER-MISSING failed to create /etc/phoebus/rollback-broken.txt===" + exit 1 +fi +echo "===ROLLBACK-MARKER present===" "$SYS" -y install "$BREAK_PKG" --legacy --portage > "$WORK/break.out" 2>&1 PKGS_BROKEN="$(pkg_fingerprint)" echo "===ROLLBACK-BROKEN pkgs=$PKGS_BROKEN==="