From fb4dcc5683bc17cb713c1ddf0e396cf6046c157b Mon Sep 17 00:00:00 2001 From: Phoebus Date: Mon, 21 Sep 2026 20:01:58 -0700 Subject: [PATCH] docs: record the 2026-09-22 harness, security and polish session Update the changelog, status matrix, handoff and VM boot verification with the 23/23 graphical journey, the hardened harness, the confirmed fixes and the remaining blocked/unverified gates (full GUI install past AI, rollback, installed desktop, physical second-computer OpenCode transport). --- docs/CHANGELOG.md | 59 +++++++++++++++++++++++++++++++++ docs/HANDOFF.md | 63 +++++++++++++++++++++++------------- docs/STATUS.md | 34 ++++++++++++------- docs/VM-BOOT-VERIFICATION.md | 47 +++++++++++++++++++++++++++ 4 files changed, 168 insertions(+), 35 deletions(-) diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 6b5845d..ed249ad 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -7,6 +7,65 @@ Format: Keep a Changelog. Dates are UTC. ## Unreleased +### Added +- **OpenCode connection workflow and capability probe.** New ADR 0011 and + `docs/OPENCODE.md` separate the four components (client, server, model + service, Phoebus broker) and document host-local and tunnelled remote use. + `phoebus-executor::opencode_server` probes `/global/health` and + `/config/providers` and reports a typed state (`disconnected`, + `authentication_required`, `incompatible`, `reachable_no_model`, `ready`) + instead of assuming a TCP connect or HTTP 200 means compatibility. Exposed as + `phoebus-installer --opencode-probe ` (read-only, nonzero unless a model + is available). Never returns provider credentials. Verified against the + installed `opencode 1.18.32` (ready) and a deliberate unauthenticated LAN bind + (`authentication_required`). + +### Security +- **The target disk is revalidated immediately before partitioning.** An + approval now binds to a verified device, not a name: `storage_prepare` re-probes + and refuses if the disk disappeared, became protected (mounted/read-only/live), + or changed size/model since it was selected. Regression tests cover each case. +- **The GUI bridge refuses replayed and overlapping installs.** An approval is + single-use and consumed before destructive work; a second `start_install`, a + retry or a reconnected frontend cannot start a second installation. Request + lines and secret values are length-bounded; deeply nested JSON is rejected. +- **Provider transport hardened.** Only `http(s)` endpoints are accepted, URLs + with characters that could inject curl config directives are refused, the + transfer is restricted to `http,https`, redirects stay disabled (so an + `Authorization` header cannot follow a redirect to another origin), and the + response is size-bounded (`max-filesize`). +- **`TargetRoot` refuses symlink escapes.** `write`/`ensure_dir` reject a + symlinked path component inside the target instead of following it, so a + planted symlink cannot redirect an installer write to the host. +- **Unauthenticated OpenCode endpoints are not treated as usable.** The probe + reports `authentication_required` for a passwordless LAN bind rather than + `ready`. + +### Fixed +- **Disk sizes are no longer reported as `0 B`.** `probe_disks` invoked `lsblk` + without `-b`, so human-readable sizes (`30G`) failed the byte parse and every + disk displayed `0 B`; the size-based disk-identity check was also blind. The + `-b` flag is now used and pinned by a test. +- **The welcome window's primary action is keyboard-reachable.** It now requests + activation and force-focuses "Install Phoebus OS", so Return launches the + installer (previously no focus ring was shown and Return did nothing). A + regression test also rejects the non-existent `FloatingWindow.onActiveChanged`. +- **The installer cannot be abandoned mid-install without explanation.** Escape + during the destructive phase is refused and the UI states that the operation + cannot be cancelled safely; the AI step shows its "connect and validate" + guidance inline, beside the controls. + +### Changed +- **The VM harness enforces its own safety rules and reports structured + results.** `installer/tests/vm/vmsafety.py` validates every writable drive + (qcow2, inside `PHOEBUS_VM_DISKS`, no `/dev/*`, block/char devices, raw + images, escaping symlinks or outside backing chains), gives each run its own + OVMF variable file and QMP socket, uses structured QMP and argument arrays + (no `os.system`), and returns nonzero on any failed assertion, timeout, EOF or + missing result. Statuses are `PASS`/`FAIL`/`BLOCKED`/`SKIPPED`/`NOT RUN`. + `make test` now runs the harness unit tests; `installer/tests/vm/report.py` + builds a browsable run report. + ### Added - **Graphical installation experience.** The live ISO now boots into a branded Phoebus welcome window (`phoebus-welcome`) that makes "Install Phoebus OS" the diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md index e924d36..853f900 100644 --- a/docs/HANDOFF.md +++ b/docs/HANDOFF.md @@ -3,53 +3,70 @@ 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-21), graphical installer ISO. -- **Current focus:** The ISO now boots into a branded **welcome window** and a - full **graphical installer wizard** over a typed JSON bridge - (`phoebus-installer --gui-bridge`), with the TUI/CLI as fallback. The brand - system, boot-menu identity, live-medium detection and the recovery-boot - default bug are fixed. See ADR 0010 and `docs/VM-BOOT-VERIFICATION.md`. +- **Last updated:** this session (2026-09-22), harness + security + polish. +- **Current focus:** Hardened the VM harness (enforced qcow2/`/dev`/backing-chain + safety, structured PASS/FAIL results, per-run OVMF+QMP, no `os.system`), + fixed confirmed security defects (disk revalidation before partitioning, + bridge replay/concurrency + input bounds, provider transport URL/size + hardening, `TargetRoot` symlink escapes, and the `0 B` disk-size probe bug), + added an OpenCode server capability probe + docs/ADR 0011, and fixed the + welcome focus ring and the untruthful mid-install cancellation. - **Last verified (this session):** - - `gui-driver.py gui`: welcome autostarts; DMS first-run dialogs suppressed; - installer opens; duplicate sessions prevented (`n1=n2=1`); keyboard - navigation reaches network + AI steps; the AI step blocks without a model. - - `gui-driver.py install` + `boot` on the built ISO: `INSTALL-RC=0`, - `NO_SECRET_LEAK`, and a **detached** boot with systemd `running`, - **0 failed units**, LUKS2, all Btrfs subvolumes and network, and the boot - menu defaulting to **Gentoo Linux** (not recovery). - - Rust suite: GUI bridge dry-run protocol, approval binding/invalidation, - secret non-disclosure, brand tokens/contrast, boot default pinning. + - `gui-driver.py gui` on the rebuilt ISO: **23/23 PASS**, exit 0. Welcome + autostarts; Return launches the installer (focus fixed); duplicate sessions + prevented; live medium protected; keyboard navigation reaches network + AI; + advancing without a model is refused and starts nothing. + - `make test` green (Rust + 16 harness unit tests); `cargo fmt --check`, + `cargo clippy --workspace --all-targets` (no errors), release + static + builds. + - OpenCode probe: `ready` against `opencode 1.18.32`; `authentication_required` + (exit 1) against an unauthenticated LAN bind. - ISO: `installer/live/phoebus-installer-amd64.iso` 1.6 GiB, - `sha256 2a52178c4b4a71bbc5c011b89533988ceb9aa95493160cb93c4335f03d9a1eee`. + `sha256 428dbd7547db8690596bf5c3a0d7a6fa8aee4c9f9eca1e926c216712dd050b36`; + static binary `sha256 2f9cd4b36a12e469d2b6187166acaf8b11f7f382cc19f7ad08bb2a809c855591`. - **Public repo:** (remote `origin`, SSH port 2222). ## Next actions (in order) -1. **Live AI provider call**: exercise the GUI AI step (and `sys ask`) with a - real 0600 key or a downloaded local model; the path is fixture-verified only. +1. **Complete the graphical install with a real model**: download a small local + OpenAI-compatible model (or supply a 0600 provider key), then run + `gui-driver.py gui` through disk/account/review/ERASE/install/rebooot twice + on fresh qcow2 disks and record the passing journeys. The current automated + journey passes to the AI gate only. 2. **Installed Mango desktop**: install the default profile in a graphical VM and verify the panel/launcher/terminal/audio/network/lock/idle, the dwl fallback, and the welcome/installer absence on the installed system. 3. **Rollback VM acceptance**: deliberately break an update, run `sys undo`, reboot detached, verify `/var/db/pkg` matches `/`, then boot the recovery entry with no network or model (ADR 0007). -4. **Physical-seat desktop**: run `phoebus-session` on a real VT/seat and check +4. **Narrow the live broker privilege**: replace the live-only + `NOPASSWD: ALL` rule for the GUI bridge with the smallest practical + command-scoped rule once a safe sudoers form is verified (ADR 0011 context). +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`). -5. **Release gates on a CI runner**: `phoebus-release gates --execute` and +6. **Release gates on a CI runner**: `phoebus-release gates --execute` and `publish` once a runner exists; no gate has executed. ## Known blockers / risks -- No live DeepSeek/OpenAI call has been made (no key in this environment); the - AI step is verified as a blocked prerequisite and with a fixture transport. +- 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 + verified as a blocked prerequisite and with a fixture transport. - **Installed** Mango (GURU + compiled Quickshell/DMS) is not VM-verified; nor is the dwl fallback session. - Rollback and the AI sandbox are implemented and unit-tested but not VM-verified. NVIDIA is not verified. +- A **separate physical computer** for the OpenCode transport test is not + available (BLOCKED); a forwarded-hop + unauthenticated-LAN-refusal host-local + test was done instead. - The GUI bridge reaches Quickshell via `Process` + `/usr/bin/sudo -n`; it - relies on the live user's passwordless sudo. + relies on the live user's passwordless sudo. The live sudoers rule is still + `NOPASSWD: ALL` (live-only); narrowing the broker permission is future work. +- Harness artifacts live under `/var/tmp/phoebus-vm/` (outside git): + `results.json`, `screenshot-manifest.json`, `report.html`, screenshots. ## Environment notes diff --git a/docs/STATUS.md b/docs/STATUS.md index 3a10b9c..05b417c 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -93,6 +93,13 @@ still not VM-verified. | greetd login (Mango default, dwl fallback) | yes | yes | no | no | | 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 | +| 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 | +| `TargetRoot` symlink-escape guard | yes | yes | n/a | n/a | +| OpenCode server capability probe | yes | yes | real host probe (`ready`) | n/a | | GURU packaging (scoped keywords) | yes | yes | no (build/install unverified) | no | | Release gates + atomic publish | yes | yes | no | n/a | | `sys` verbs | yes | yes | yes | no | @@ -130,18 +137,21 @@ still not VM-verified. - **The live desktop ISO** (`installer/live/build.sh`) builds a Debian testing rootfs with Mango + DMS, live-only autologin, a branded welcome window and a graphical installer frontend over the typed bridge. Its desktop-payload - guards are unit-tested, and the built ISO - (`sha256 2a52178c…`, 1.6 GiB) was booted in a graphical, seat-providing VM: - the welcome window opened automatically, the installer launched (a second - launch created no duplicate), keyboard navigation reached the network and AI - steps, and advancing without a connected model was refused. The same ISO was - then installed non-interactively (`INSTALL-RC=0`, `NO_SECRET_LEAK`) and - booted **with the ISO detached** (systemd running, 0 failed units, LUKS2, - all Btrfs subvolumes, network). A live AI provider call was **not** possible - (no key in this environment); the AI step is verified as a blocked - prerequisite and with a fixture transport in unit tests. The **installed** - Mango system (GURU + compiled Quickshell/DMS) and the dwl fallback in a VM - are not yet verified. + guards are unit-tested. The rebuilt ISO + (`sha256 428dbd75…`, 1.6 GiB, build id in `/etc/phoebus/build`) was booted in + a graphical, seat-providing VM and the automated `gui` journey passed + **23/23** checks: the welcome window opened automatically, "Install Phoebus + OS" launched the installer from the keyboard, a second launch created no + duplicate, the live medium was reported protected, keyboard navigation + reached the network and AI steps, and advancing without a connected model was + refused. An earlier appliance build of the same code path was installed + non-interactively (`INSTALL-RC=0`, `NO_SECRET_LEAK`) and booted **with the + ISO detached** (systemd running, 0 failed units, LUKS2, all Btrfs subvolumes, + network). A live AI provider call was **not** possible (no key and no local + model in this environment), so the **full graphical install past the AI step** + is not claimed; the AI step is verified as a blocked prerequisite and with a + fixture transport in unit tests. The **installed** Mango system (GURU + + compiled Quickshell/DMS) and the dwl fallback in a VM are not yet verified. - **AI sandbox** is implemented (`systemd-run` hardening properties, tested at 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 diff --git a/docs/VM-BOOT-VERIFICATION.md b/docs/VM-BOOT-VERIFICATION.md index f0e8541..0a75b60 100644 --- a/docs/VM-BOOT-VERIFICATION.md +++ b/docs/VM-BOOT-VERIFICATION.md @@ -552,6 +552,43 @@ the kernel's `sort-key`, and the specification's final filename tie-break pinning `loader.conf` to the newest real kernel entry and giving the recovery entry `sort-key zzzz-phoebus-recovery`; unit tests pin both. +## 2026-09-22 — automated graphical journey (gui-driver) and hardened harness + +The graphical live ISO was rebuilt and driven automatically by +`installer/tests/vm/gui-driver.py gui` in a graphical, seat-providing +QEMU/OVMF VM with a disposable qcow2 disk directory and a per-run OVMF variable +file. + +- Source revision: `7e9fa9c` plus uncommitted work; build id recorded in + `/etc/phoebus/build` (`7e9fa9c+dirty…`). +- Static installer: `sha256 2f9cd4b3…` (4,716,544 bytes, static-pie). +- ISO: `installer/live/phoebus-installer-amd64.iso`, + `sha256 428dbd75…`, 1.6 GiB, built with + `PHOEBUS_REUSE_ROOTFS=1` (Mango 0.17.2 + DankMaterialShell 1.6.2). +- Result: **23/23 checks PASS**, exit status 0 + (`/var/tmp/phoebus-vm/gui-gui-20260922T025537Z-69f754cf/`). + Asserted: welcome autostart; live/branding payload markers from command + output (not the echoed command); the live medium protected; "Install Phoebus + OS" launched the installer from a Return keypress; duplicate sessions + prevented (`n1=n2=1`); the frontend reported no bridge errors; keyboard + navigation reached the network and AI steps; advancing without a connected + model was refused and started no installation. +- Screenshots at every page (welcome focus, language, network, AI model, AI + blocked, final state) plus a `screenshot-manifest.json`; `report.py` builds a + browsable `report.html`. All artifacts stay under `/var/tmp/phoebus-vm/` + (outside git). + +Harness safety verified in the same work: the drivers reject `/dev/*`, block +and character devices, raw images, symlinks escaping the disposable directory, +and outside backing chains, with a nonzero exit (`make test-vm`, 16 unit +tests). Screenshots use structured QMP and argument arrays; there is no shell +interpolation. + +A host-local OpenCode transport test also ran: `phoebus-installer +--opencode-probe` returned `ready` against `opencode 1.18.32` through a +forwarded second loopback endpoint, and `authentication_required` (exit 1) +against a deliberately unauthenticated LAN bind. + ## Known remaining work - The graphical session was verified with the **headless** wlroots backend @@ -565,3 +602,13 @@ entry `sort-key zzzz-phoebus-recovery`; unit tests pin both. - Desktop USE still does not match the signed binhost, so the desktop transaction compiles a large amount from source (~26 minutes for the desktop package set on 8 vCPUs in the test VM). +- **The full graphical install past the AI step is NOT verified.** No live + provider key and no downloadable local model were available in this + environment, and normal installation requires a connected model by design; + the automated journey stops at (and verifies) the blocked AI prerequisite. + Two fresh-disk graphical installations from the final candidate remain + unrun. The deterministic noninteractive install + detached boot remains the + proven boot path. +- **A separate physical computer for the OpenCode transport test is NOT + available**; that check is BLOCKED. The forwarded-hop and + unauthenticated-LAN-refusal tests are host-local.