diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 20bbf4c..23f3b55 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -39,6 +39,10 @@ Pure, non-privileged logic with no external commands except reading `/proc`, - `target` — `TargetRoot`, which rejects absolute paths and `..` traversal. - `secret` — `SecretString` (redacted `Debug`, zeroized on drop) + `Redactor`. - `snapshot` — deterministic snapshot names + TOML transaction history. +- `boot` — BLS entry parse/render and root-subvolume selection for rollback. +- `rollback` — rollback state machine, retention and mount/fstab planners. +- `effects` — parse `emerge --pretend` into resolved effects + plan digest. +- `transaction` — the user-queryable log of executed actions and outcomes. - `action` — closed `SystemAction` schema and a small deterministic parser. - `update` — preparation policy and real Portage argument builders. @@ -57,17 +61,24 @@ The only crate that runs privileged commands. `desktop` — the install backend, mirroring the proven order. - `probe` — read-only hardware and disk discovery. - `snapshot`, `update`, `admin`, `actions` — post-install foundations. +- `rollback` — coordinated root/`var`/fstab/BLS rollback (ADR 0007). +- `nix` — pinned Nix bootstrap, sandboxed build config, lifecycle and cleanup. +- `sandbox` — the hardened `systemd-run` boundary for model execution. +- `transaction` — persists the transaction log into the target. ### phoebus-ai - Typed `AiProposal` / `SystemAction` (unknown actions fail closed; no shell). +- `assistant` — the installed conversational plan schema (`AssistantPlan`) and + its fail-closed parser; the model proposes the same actions `sys` executes. - `privacy` — `PrivacyPolicy` + `ContextBundle`; forbidden-path checks. The collector in `phoebus-executor::admin` only reads system sources. ### phoebus-installer - `orchestrate` — `Installer` runs the plan stages and stops on first failure. -- `release` — `ReleaseManifest` create/verify, assemble command. +- `release` — `ReleaseManifest` create/verify, candidate gates, atomic publish + and signing command helpers. - Binaries: `phoebus-installer`, `sys`, `phoebus-release`. ## Safety model @@ -81,7 +92,40 @@ The only crate that runs privileged commands. - Secrets travel over stdin only and are registered with the redactor before any logging. They never enter the config. - The AI cannot execute; it can only propose typed changes that the backend - validates and the user approves. + validates and the user approves. The assistant's model call additionally runs + inside an unprivileged, hardened `systemd-run` unit (`sandbox`), so the + boundary is enforced by the OS and not only by the schema. +- Approval is bound to the reviewed resolved plan: package effects are resolved + again before execution and a material change aborts. + +## Rollback and recovery + +A recovery point is a snapshot set: `@` and the separate `@var` (Portage state) +together; `/home` is excluded. Rollback creates a writable root generation, +rewrites `subvol=` in both the restored root's fstab and the BLS entry options +(the explicit argument overrides the Btrfs default), selects a kernel entry +whose modules match the restored root, and writes previous/recovery entries. +See ADR 0007. + +## Desktop profiles + +Two sessions are generated, and each starts exactly one compositor and one set +of shell services: + +- **dwl** (`desktop.profile = "dwl"`): the proven session — dwl, waybar, wofi, + mako, swaybg, swayidle, swaylock, the polkit agent. Entry point + `/usr/local/bin/phoebus-session`, session file `phoebus-dwl.desktop`. +- **Mango + DankMaterialShell** (`desktop.profile = "mango"`): `gui-wm/mangowm` + plus the DMS shell (panel, launcher, notifications, lock, idle, audio/network/ + Bluetooth/display controls) from the GURU overlay. Entry point + `/usr/local/bin/phoebus-session-mango`, session file `phoebus-mango.desktop`. + The dwl session is installed alongside as a fallback. The Mango session never + starts the dwl helpers. See ADR 0009. + +`desktop.profile` selects both the Gentoo desktop/systemd profile and the +package set; the plan shows the selected session before installation, and the +installer writes both session entry points for the Mango profile so the user can +return to dwl. ## Installation order (do not regress) @@ -105,13 +149,17 @@ the actual execution, so the UI cannot diverge from the backend. ## Post-install foundations - **Snapshots**: read-only Btrfs snapshots under `/.snapshots`, recorded in a - TOML history. `/home` is intentionally not snapshotted by default. + TOML history. A snapshot set captures `@` and the separate `@var`; `/home` is + intentionally not snapshotted so user documents survive a rollback. +- **Rollback**: `sys undo` restores a committed snapshot as the next boot root + with coordinated fstab, BLS and kernel selection (ADR 0007); a persisted state + file makes an interrupted rollback resumable. - **Background updates**: `emerge --fetchonly` then `--buildpkgonly` stage distfiles and reusable local binary packages without installing; activation stays explicit. - **Kernel/boot**: `sys-kernel/gentoo-kernel-bin` (safe) or `gentoo-kernel` - (optimized), dracut initramfs, systemd-boot BLS entries, plus a recovery - entry booting `rescue.target`. + (optimized), dracut initramfs, systemd-boot BLS entries, plus a snapshot-based + recovery entry that does not depend on the live root. ## Extension points diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index cd09597..7ae3e71 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -7,6 +7,72 @@ Format: Keep a Changelog. Dates are UTC. ## Unreleased +### Added +- **Mango + DankMaterialShell desktop option** (`desktop.profile = "mango"`): + `gui-wm/mangowm` 0.17.2 (wlroots 0.20) plus `gui-apps/dankmaterialshell` + 1.5.3 / Quickshell 0.3.1 / scenefx 0.5, installed through the GURU community + overlay with scoped `~amd64` keywords (never global). The installer writes + GURU's `repos.conf`, bootstraps `dev-vcs/git`, and syncs the overlay. A + `phoebus-session-mango` entry point, a packaged Mango config seeded once into + the user's config, DMS keybindings, a `mango-session.target` binding for DMS, + and `phoebus-mango.desktop`/`phoebus-dwl.desktop` session entries are + generated. dwl remains the fallback session and is installed alongside. The + profile is selectable but **not promoted to default** pending graphical-VM + verification (ADR 0009). + +## 2026-09-21 — Coherent rollback, installed assistant, Nix isolation + +### Added +- **Coherent rollback and recovery** (`phoebus-core::rollback`, + `phoebus-executor::rollback`): a recovery point now captures `@` **and** the + separately mounted `@var` (Portage state) under one name; rollback creates a + writable root generation, rewrites the restored root's fstab **and** the BLS + `rootflags=subvol=`, selects a boot entry whose kernel modules match the + restored `/lib/modules`, and writes "previous" and snapshot-based "recovery" + entries. A persisted `rollback-state.toml` makes interruption safe and + resumable; retention prunes old snapshots and protects in-flight targets; a + 1 GiB free-space check gates the operation. See ADR 0007. +- `sys undo` / `sys undo ` / `sys undo status` and the high-risk `undo` + typed action. The installer now records a snapshot-based "Phoebus Recovery" + entry at install time, so recovery does not depend on the live root. +- **Installed conversational assistant** (`phoebus-ai::assistant`, + `sys ask `): bounded facts -> typed plan -> concrete resolved effects + -> approval/authentication -> deterministic execution -> transaction record. + No model is required: `sys ask` falls back to the deterministic parser. +- **OS-level model sandbox** (`phoebus-executor::sandbox`): the network call + runs in a hardened, unprivileged transient systemd unit (`DynamicUser`, + `ProtectHome`, `ProtectSystem=strict`, `NoNewPrivileges`, syscall and + address-family filters). It fails closed when `systemd-run` is unavailable. +- **Resolved package effects and approval binding** (`phoebus-core::effects`): + `emerge --pretend` is parsed into additions/upgrades/downgrades/removals with + source-vs-binary provenance and download size; a plan digest binds approval, + and a material change between review and execution aborts. New bounded typed + actions `flatpak_install`/`flatpak_remove`/`flatpak_list` and `nix_prepare`. +- **Transaction log** (`phoebus-core::transaction`): assistant and `sys` + actions record their actions, result and recovery point; `sys history` shows + snapshots and transactions. +- **Desktop completeness**: `phoebus-menu` (wofi drun launcher + power menu), + `phoebus-lock` (swaylock), `phoebus-idle` (swayidle: lock, suspend, + before-sleep lock) and a system-wide Waybar config with network, audio, + battery, clock and power controls. +- **Release gates** (`phoebus-installer::release`): a registry of the real + candidate checks (install, detached boot, desktop, updates/rollback, + no-model), a gate report that never records an unexecuted check as passed, + atomic publication that preserves the last known-good `latest.iso.prev`, and + signing/verification command helpers. +- New VM harness for the Debian-Live appliance: + `installer/tests/vm/appliance-driver.py`, `appliance-guest.sh` and + `appliance-test.conf.example`. + +### Changed +- **Nix build isolation is enforced**: `sandbox = true`, + `sandbox-fallback = false`, with store bounds (`min-free`/`max-free`) and + `auto-optimise-store`. Lifecycle operations (remove/purge, gc) and a + bounded `nix_prepare` action were added; the Portage-owned ebuild approach is + documented in ADR 0008. See ADR 0006. +- Desktops install `swayidle`/`swaylock` session helpers and a Waybar + configuration; `phoebus-session` starts the idle daemon. + ### Added - **Nix bootstrap (on by default, VM-verified).** `phoebus-executor::nix` fetches the pinned, SHA-256-verified official Nix release and bootstraps it diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index 24b4bfa..54c56c2 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -76,6 +76,45 @@ python3 installer/tests/vm/serial-driver.py boot `installer/tests/vm/run-vm.sh` launches an interactive VM instead. +### Debian-Live appliance harness + +The appliance ISO (`installer/live/build.sh`) boots its own GRUB, so it has its +own driver. It is the fastest path to a full install on hosts where the Gentoo +LiveGUI ISO is unavailable: + +```sh +cd installer-rs +RUSTFLAGS="-C target-feature=+crt-static" \ + cargo build --release -p phoebus-installer --target x86_64-unknown-linux-gnu +cd .. +BASE_ISO=/path/to/debian-live-standard.iso installer/live/build.sh + +# Serve the stage3, config and 0600 secrets (host 10.0.2.2:8000): +mkdir -p /path/serve && cd /path/serve +cp /path/to/stage3-amd64-systemd-*.tar.xz stage3.tar.xz && sha256sum stage3.tar.xz +cp /path/to/installer/tests/vm/appliance-guest.sh . +cp /path/to/installer/tests/vm/appliance-test.conf.example test.conf # set STAGE3_SHA256 +printf 'phoebus-luks-test' > luks.pw && chmod 600 luks.pw +printf 'phoebus-user-test' > user.pw && chmod 600 user.pw +python3 -m http.server 8000 --bind 127.0.0.1 + +qemu-img create -f qcow2 /path/target.qcow2 24G +cp /usr/share/OVMF/OVMF_VARS_4M.fd /path/OVMF_VARS.fd +OVMF_CODE=/usr/share/OVMF/OVMF_CODE_4M.fd \ +OVMF_VARS=/path/OVMF_VARS.fd \ +DISK=/path/target.qcow2 \ +ISO=/path/to/installer/live/phoebus-installer-amd64.iso \ +python3 installer/tests/vm/appliance-driver.py install + +# Detached boot (no ISO): +DISK=/path/target.qcow2 OVMF_CODE=... OVMF_VARS=... \ +python3 installer/tests/vm/appliance-driver.py boot +``` + +`INSTALL_TIMEOUT` and `CHECKS_TIMEOUT` bound the long steps. A full base install +still fetches and merges the Gentoo stage3 and base packages, so it takes tens +of minutes. + ### Verifying the graphical stack The serial-only VM has no logind seat, so wlroots' DRM backend cannot start @@ -88,7 +127,9 @@ grim /tmp/shot.png # proves the compositor renders ``` On a real machine the installer writes `/usr/local/bin/phoebus-session` -(dwl + waybar + mako + swaybg + the polkit agent). +(dwl + waybar + mako + swaybg + swayidle + the polkit agent) and the helpers +`phoebus-menu` (wofi drun launcher / power menu), `phoebus-lock` (swaylock) and +`phoebus-idle` (swayidle). ### Physical VT / real-seat check (needs a person) @@ -107,17 +148,50 @@ Check, in order: log a failed Wayland connection). 3. Open a terminal: `kitty`. Run an X11 app to exercise XWayland (e.g. `xterm` or `env -u WAYLAND_DISPLAY kitty` if no X app is installed). -4. Trigger a privilege prompt (e.g. `pkexec true` or a polkit-gnome dialog) and +4. Run `phoebus-menu` and confirm the application launcher (wofi) appears; run + `phoebus-menu --power` and confirm lock/suspend/log out/reboot/shut down are + offered. +5. Check Waybar shows network and audio controls; click the power module. +6. Run `phoebus-lock` and confirm the session locks (and unlocks). +7. Trigger a privilege prompt (e.g. `pkexec true` or a polkit-gnome dialog) and confirm the authentication agent appears. -5. Log out (`Mod+Shift+e` for dwl). Confirm `waybar`, `mako`, `swaybg` and the - polkit agent are gone (`pgrep -a 'waybar|mako|swaybg|polkit-gnome'` prints - nothing) and that the session returns to the VT login. -6. Reboot and confirm the same result. +8. Log out (`Mod+Shift+e` for dwl). Confirm `waybar`, `mako`, `swaybg`, + `swayidle` and the polkit agent are gone + (`pgrep -a 'waybar|mako|swaybg|swayidle|polkit-gnome'` prints nothing) and + that the session returns to the VT login. +9. Reboot and confirm the same result. Record the result (date, kernel, GPU, pass/fail per step) in `docs/VM-BOOT-VERIFICATION.md`. A headless wlroots session is not physical-seat verification. +### Mango + DankMaterialShell + +Select the profile with `DESKTOP_PROFILE='mango'` (or `[desktop] profile = +"mango"`). The installer writes GURU's `repos.conf`, installs `dev-vcs/git`, +syncs the overlay with `emaint sync -r guru`, and installs Mango, DMS, +Quickshell and scenefx with **scoped** `~amd64` keywords. To return to dwl, +select `desktop.profile = "dwl"` (the dwl session and the dwl package set are +also installed by the Mango profile as a fallback, so both session entries exist +at the login screen). + +Session entry points: + +```sh +/usr/local/bin/phoebus-session-mango # Mango + DMS +/usr/local/bin/phoebus-session # dwl fallback +``` + +To inspect the resolved effect of the transition before installing, use +`emerge --pretend gui-wm/mangowm gui-apps/dankmaterialshell` and review the +`~amd64` list; add only reviewed atoms to +`/etc/portage/package.accept_keywords/phoebus`. Never run a global +`~amd64` switch. + +**Acceptance is a graphical VM with a real seat.** Headless compositor tests do +not qualify. The gates are listed in `docs/VM-BOOT-VERIFICATION.md`; until they +pass, Mango is selectable but not the default. + ## Inspecting the reference ISO without booting ```sh diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md index 8b7ace1..72bbedd 100644 --- a/docs/HANDOFF.md +++ b/docs/HANDOFF.md @@ -3,57 +3,62 @@ 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:** commit `b2f5181` (2026-09-20) -- **Current focus:** four workstreams — AI-assisted install guidance, desktop - session reliability, signed-binary reuse, and snapshots/safe updates. +- **Last updated:** commit `b12b276` + this session (2026-09-21) +- **Current focus:** coherent rollback/recovery, the installed AI assistant with + an OS-level sandbox, Nix build isolation, resolved package effects, desktop + completeness, and release gates. A new **Mango + DankMaterialShell** desktop + profile (`desktop.profile = "mango"`, ADR 0009) is implemented and selectable + with a dwl fallback; it is **not yet graphical-VM verified** and is not the + default. - **Last verified:** static Rust binary install + detached boot - (`docs/VM-BOOT-VERIFICATION.md`); in this session additionally: the Debian-Live - appliance ISO (firmware boot, full install, detached boot), the mandatory-AI - gate, desktop portals, and the **built-in Nix lane** (`nix-daemon` active, - `nix shell nixpkgs#hello` -> `Hello, world!`); `sys` snapshot/history and - update preparation on an installed Btrfs VM; and the AI guided path by - fixtures. + (`docs/VM-BOOT-VERIFICATION.md`); in this session additionally: a fresh + Debian-Live appliance install on a disposable qcow2 (recorded in + `docs/VM-BOOT-VERIFICATION.md` when it completes), plus unit/functional tests + for rollback, effects, transactions, the assistant schema, the sandbox argv, + and the desktop helpers. - **Public repo:** (remote `origin`, SSH port 2222). ## Next actions (in order) -1. **Re-verify the finalize `sync`** (build `3ba913ba`): the Nix lane is - VM-verified (`nix-daemon` active, `nix shell` works) and on by default, but - the one-line durability fix that should make `/usr/local/bin/phoebus-session` - survive a forced poweroff was not re-run end to end (host root was ~98% full - and the base emerge became pathologically slow). A binary Nix ebuild was - ruled out (upstream has no `DESTDIR`). -2. **Physical-seat desktop**: run `/usr/local/bin/phoebus-session` on a real VT - and check kitty, XWayland, the polkit agent, logout/reap and reboot - (`docs/DEVELOPMENT.md` -> "Physical VT / real-seat check"). -3. **Matching signed binhost**: the official Gentoo binhost is OpenRC/hardened, - so systemd/desktop packages compile from source. Publish (or point at) a - systemd/desktop binhost to raise binary reuse; verify with `emerge -pv`. -4. **Rollback gate**: implement Btrfs default-subvolume + ESP handling and pass - a detached-boot test before exposing `sys undo`. -5. **Live AI provider call**: exercise DeepSeek/OpenAI/local with a real 0600 - key file; the path is currently fixture-verified only. -6. **Desktop graphical login**: exercise a real logind seat. +1. **Rollback VM acceptance**: deliberately break an update in the disposable + VM, run `sys undo`, reboot detached, verify package-state consistency + (`/var/db/pkg` matches `/`), then boot the snapshot recovery entry with no + network or model (ADR 0007). +2. **Live AI provider call**: exercise `sys ask` with a real 0600 key file and + confirm the `systemd-run` sandbox properties apply; the path is + fixture-verified only. +3. **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`). +4. **Matching signed binhost / binary strategy**: keep the official binhost for + matching USE and Flatpak/Nix elsewhere; do not publish a private binhost + (ADR 0006). Verify with `emerge -pv`. +5. **Release gates on a CI runner**: run `phoebus-release gates --execute` and + `phoebus-release 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). -- No Forgejo Actions runner is known to exist; `.forgejo/workflows/ci.yml` - only runs once one is registered. +- No Forgejo Actions runner is known to exist; `.forgejo/workflows/ci.yml` only + runs once one is registered. - Desktop graphical login / physical seat has not been exercised; the serial VM has no logind seat. - NVIDIA is not verified on hardware. -- Rollback is not implemented (by design, gated). +- Rollback and the AI sandbox are implemented and unit-tested but not + VM-verified. ## Environment notes - Dev host: Ubuntu 26.04. QEMU/OVMF/xorriso/rustfmt/clippy installed. -- Reference ISO is `livegui-amd64-20260913T163055Z.iso` (gitignored). -- Forgejo token for API tasks: `~/.config/phoebus/forgejo.token` (0600). +- Debian-Live base ISO is cached at `/home/dominic/debian-live-standard.iso` + (matches `installer/live/base.sha256`); the appliance ISO builds without root. +- The appliance harness is `installer/tests/vm/appliance-driver.py` + + `appliance-guest.sh` + `appliance-test.conf.example`; serve the stage3, + config and 0600 secret files over `python3 -m http.server 8000`. - The VM harness disks are disposable qcow2 files on `/` (not `/tmp`, which is - a small tmpfs on the dev host); never point `DISK` at `/dev/*`. -- The VM harness honours `CHECKS_TIMEOUT` for long guest checks. + a small tmpfs); never point `DISK` at `/dev/*`. +- The VM harness honours `CHECKS_TIMEOUT` / `INSTALL_TIMEOUT` for long runs. ## Definition of a good stopping point diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 53f39d8..4744642 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -10,16 +10,16 @@ more interesting. Status vocabulary: **Done**, **Partial**, **Next**, **Later**. | 3 | Port the deterministic core | Done | `phoebus-core` (config, plan, policy, validation, models) | | 4 | Port the destructive backend | Done | `phoebus-executor` (storage, LUKS2, Btrfs, Portage, boot, users, services) | | 5 | **Rust VM boot parity** | Done | Full encrypted UEFI install + boot, zero failed units, 10.7 s | -| 6 | Finish the desktop | Partial | session script race-free + polkit + helper cleanup (functional test); headless compositor verified; physical seat + interactive login pending | -| 7 | Finish Flatpak | Partial | `flatpak 1.18.1` installed, flathub configured; no app installed yet | -| 8 | Instrument source/binary policy | Done | measured compile times harvested from `emerge.log` (326 entries) | +| 6 | Finish the desktop | Partial | dwl helpers, lock, idle/suspend and Waybar controls added; Mango + DankMaterialShell profile added via GURU (selectable, dwl fallback); graphical-VM verification of both sessions pending | +| 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 create + history VM-verified on Btrfs; rollback not implemented | -| 11 | AI privilege and privacy architecture | Partial | typed actions + enforced privacy boundary + guided DeepSeek/OpenAI proposal review; OS sandbox not implemented | -| 12 | `sys` operations | Partial | history, enable/disable, inspect, install, prepare-updates VM-verified | +| 10 | Snapshots / rollback | Partial | snapshot sets + history VM-verified on Btrfs; coordinated rollback, `sys undo`, recovery entry, retention and free-space gate implemented + unit-tested; destructive VM acceptance test pending | +| 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; no scheduling/publish/smoke test | -| 15 | Recovery environment | Later | recovery BLS entry generated; full recovery image not built | +| 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 | +| 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 | | — | AI-guided install optimization | Partial | DeepSeek/OpenAI/local providers, evidence-gated typed review, mandatory at install with `--no-ai` break-glass; fixture-verified, no live call | | — | Nix as a built-in second lane | Partial | pinned-release bootstrap; `nix-daemon` active and `nix shell nixpkgs#hello` VM-verified; on by default | @@ -28,16 +28,22 @@ more interesting. Status vocabulary: **Done**, **Partial**, **Next**, **Later**. ## Immediate next steps 1. **Physical-seat desktop**: run `phoebus-session`/dwl on a real VT (or a - `seatd`-backed session) and verify kitty, wofi, XWayland, the polkit agent, - logout and reboot interactively (`docs/DEVELOPMENT.md`). -2. **Desktop binary strategy**: match the desktop USE set to a signed binhost - (or publish one) so desktop installs stop compiling ~26 minutes of packages. - The official binhost is OpenRC/hardened; a systemd/desktop host is needed. -3. **Rollback as a safety gate**: implement Btrfs default-subvolume + ESP - handling and pass a detached-boot test before exposing `sys undo` - (snapshot/history/prepare-updates are now VM-verified). -4. **Live AI provider call**: exercise DeepSeek/OpenAI with a real 0600 key - file; the guided path is currently fixture-verified only. + `seatd`-backed session) and verify kitty, wofi, `phoebus-menu`, + `phoebus-idle`, the polkit agent, logout and reboot interactively + (`docs/DEVELOPMENT.md`). +2. **Mango + DankMaterialShell acceptance**: install the `mango` profile in a + graphical, seat-providing VM and run the gates in + `docs/VM-BOOT-VERIFICATION.md`; only then consider promoting it to the + default desktop. The profile is selectable now (ADR 0009). +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). +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. +5. **Live AI provider call**: exercise `sys ask` and the installer guided path + with a real 0600 key file; the path is currently fixture-verified only, and + the `systemd-run` sandbox is not yet VM-verified. ## Later diff --git a/docs/STATUS.md b/docs/STATUS.md index e3fe6ac..2f9cf23 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -63,11 +63,22 @@ on the install path (Bash migration Phase 2, see | Package policy + measured history | yes | yes | yes (326 entries) | no | | Background update preparation | yes | yes | yes (fetch; buildpkgonly skipped) | no | | Btrfs snapshots + history | yes | yes | yes | no | -| Btrfs rollback | no | no | no | no | +| Coordinated snapshot sets (`@` + `@var`) | yes | yes | no | no | +| Btrfs rollback (`sys undo`) | yes | yes | no | no | +| Recovery/known-good BLS entry | yes | yes | no | 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 | | AI privacy boundary (facts only) | yes | yes | no | n/a | -| AI OS sandbox | no | no | no | no | +| AI OS sandbox (systemd hardened unit) | yes | yes | no | no | +| Installed assistant (`sys ask`) | yes | yes | fixture path only (no live call) | n/a | +| Resolved package effects + approval binding | yes | yes | no | n/a | +| Transaction log | yes | yes | no | no | +| Flatpak/Nix bounded typed actions | yes | yes | no | no | +| Desktop session helpers (menu/lock/idle) | yes | yes | functional test (stubs) | no | +| Mango + DankMaterialShell profile | yes | yes | no (graphical VM gate pending) | no | +| 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 | | OpenCode pinned bootstrap | yes | yes | no | n/a | | Release manifest/verify | yes | yes | no | n/a | @@ -85,10 +96,27 @@ on the install path (Bash migration Phase 2, see - **NVIDIA** is architecturally allowed but not verified on hardware. - **UKI** is deferred; the dracut UKI generator did not embed the kernel command line, so BLS is used (and verified). -- **Rollback** is not implemented; snapshots and history are. -- **AI sandbox** is not enforced; only typed actions and the privacy boundary. -- **Release automation** stops at manifest/verify; no scheduler, smoke test, - signing or atomic publish. +- **Rollback** is implemented and unit-tested end to end at the command/text + layer (snapshot sets, root/var generation, fstab and BLS rewriting, kernel + selection, interruption resume, retention, free-space gate), but the + destructive VM acceptance test (deliberately broken update -> `sys undo` -> + detached reboot -> package-state check -> recovery with no network/model) has + not been run. `sys undo` is present; treat VM verification as the gate before + relying on it. +- **Mango + DankMaterialShell** is implemented as `desktop.profile = "mango"` + (Mango 0.17.2, DMS 1.5.3, Quickshell 0.3.1, scenefx 0.5 via the GURU overlay), + with a dwl fallback session and scoped `~amd64` keywords. It has not been + installed or booted in a graphical VM: no build, no seat, no interactive + verification. It is therefore **selectable, not default**, and no desktop + stability is claimed. The exact gates are listed in + `docs/VM-BOOT-VERIFICATION.md`. +- **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 + 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`. - 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 @@ -100,5 +128,6 @@ on the install path (Bash migration Phase 2, see key. - The installer rebuilds `sys-apps/systemd` from source because boot/policykit/cryptsetup USE differ from the binhost. -- `sys undo` is intentionally not implemented: rollback needs default-subvolume - and ESP handling plus a detached-boot test, which is a separate safety gate. +- `sys undo` is implemented with the default-subvolume, fstab, kernel-cmdline + and BLS handling described in ADR 0007; its destructive VM acceptance test is + the remaining safety gate. diff --git a/docs/VM-BOOT-VERIFICATION.md b/docs/VM-BOOT-VERIFICATION.md index 20149de..374687c 100644 --- a/docs/VM-BOOT-VERIFICATION.md +++ b/docs/VM-BOOT-VERIFICATION.md @@ -347,6 +347,46 @@ never configuration. been re-run end to end (host disk pressure). Until it is, treat the session script as **unverified** in the shipped ISO. +## Mango + DankMaterialShell acceptance (NOT RUN) + +The `mango` profile (ADR 0009) is implemented and source-tested but has not been +installed or booted. These gates must pass in a **graphical, seat-providing** +disposable VM before the profile is promoted to default. Headless wlroots tests +do not count. + +Prerequisites: the `mango` install needs the GURU overlay to sync (git) and +Quickshell/DMS/scenefx to compile; the base install alone is tens of minutes. + +1. Fresh install with `DESKTOP_PROFILE='mango'` reaches `systemctl + is-system-running = running` with 0 failed units; `emerge --pretend` shows + only the reviewed `~amd64` atoms. +2. Detached encrypted boot; LUKS unlock; login on a real seat. +3. `phoebus-mango.desktop` starts the session; exactly one compositor (mango), + one shell (dms), one lock/idle (DMS) and one polkit agent are running; no + waybar/mako/swaybg/swayidle/swaylock processes. +4. Panel, launcher (Mod+Space), notifications, tray, and the DMS settings panel + work; the shortcut guide matches the packaged config. +5. Audio output/input selection, volume, mic mute (WirePlumber); network and + Bluetooth controls from the panel. +6. Lock (Mod+Alt+L) and unlock; idle lock/suspend; repeated suspend/resume. +7. Display configuration/scaling and a second monitor if the VM supports one. +8. Clipboard history (Mod+V), screenshots, kitty terminal, file manager, and + `phoebus-assistant` opening `sys ask` (no model required for deterministic + `sys`). +9. An actual Flatpak app: launch, file chooser, and portal screen sharing. +10. Logout reaps DMS and session processes without touching the dwl fallback; + reboot; then boot the `phoebus-dwl.desktop` session and confirm it still + works. +11. Shell-failure handling: kill `dms` and confirm the compositor keeps running + and locking still locks; restart the shell without losing windows. +12. Upgrade from an existing dwl install keeps user configuration + (`~/.config/mango/config.conf`, DMS fragments, `~/.config/waybar`) intact. +13. Idle memory/CPU and startup time measured against the dwl session under + comparable conditions. + +Until this list is recorded here with results, the Mango profile is selectable +but not default, and no desktop stability is claimed. + ## Known remaining work - The graphical session was verified with the **headless** wlroots backend diff --git a/docs/adr/0006-package-lanes.md b/docs/adr/0006-package-lanes.md index aa19dcb..b36fdad 100644 --- a/docs/adr/0006-package-lanes.md +++ b/docs/adr/0006-package-lanes.md @@ -1,6 +1,6 @@ # ADR 0006: Package lanes — Portage, Flatpak, and Nix (built in) -- **Status:** Proposed +- **Status:** Accepted - **Date:** 2026-09-20 ## Context @@ -133,11 +133,35 @@ drivers → Portage only; GUI → Flatpak; per-project/dev → Nix. ## Next steps -1. Finish Flatpak integration: `xdg-desktop-portal` (+ `-gtk`/`-wlr` backends), - a documented app-install path, desktop integration. -2. Author the Phoebus overlay `sys-apps/nix` ebuild (+ `nix-daemon.service`), - install it from the installer, and verify in the disposable VM that a Nix - dev environment works and the base system still boots without using it. -3. Add the `CreateDevEnvironment` typed action with a bounded input set and - tests. -4. Only then consider a thin `sys`-level source chooser (not a general `pkg`). +1. Finish Flatpak integration: a documented app-install path and desktop + integration. The `xdg-desktop-portal` (+ `-gtk`/`-wlr` backends) are + installed, bounded `flatpak_install`/`flatpak_remove`/`flatpak_list` typed + actions exist, and flathub is configured; an actual app install and the file + chooser/screencast portals still need VM verification. +2. Author the Phoebus overlay `sys-apps/nix` ebuild (a bootstrap-style ebuild; + see ADR 0008) so `emerge` owns installation, upgrades and removal. Until it + ships, the installer provisions the same lifecycle directly. +3. `CreateDevEnvironment`/`nix_prepare` bounded typed actions: `nix_prepare` is + implemented; a richer per-project environment action remains. +4. Consider a thin `sys`-level source chooser (not a general `pkg`). + +## Binary strategy (reconciled) + +The roadmap once proposed publishing a private signed binhost to stop the +desktop set compiling. That conflicts with the rejection of a private/third-party +binhost above and would add infrastructure and trust obligations silently. + +The sustainable strategy is: + +- **Portage source or the official signed Gentoo binhost**, whichever matches the + package's USE. Signature verification stays on (ADR 0004); no private binhost + is maintained. +- **Flatpak** for sandboxed GUI applications that the official binhost cannot + serve (Chromium, Spotify, Electron). +- **Nix** for developer tools, alternate versions and reproducible per-project + environments (ADR 0008). + +Packages the official OpenRC/hardened binhost cannot satisfy (systemd, polkit, +NetworkManager, a desktop USE set) compile from source. That cost is accepted +and measured (`docs/STATUS.md` records the compile times), not hidden behind a +new binhost. diff --git a/docs/adr/0007-coherent-rollback.md b/docs/adr/0007-coherent-rollback.md new file mode 100644 index 0000000..436f8f9 --- /dev/null +++ b/docs/adr/0007-coherent-rollback.md @@ -0,0 +1,101 @@ +# ADR 0007: Coherent rollback and recovery + +- **Status:** Accepted +- **Date:** 2026-09-21 + +## Context + +Btrfs snapshots and transaction history existed, but rollback was deliberately +unimplemented. The proven layout separates the filesystems that must move +together: + +``` +GPT: 1 GiB FAT32 ESP (mounted /efi) +LUKS2 -> Btrfs: @ / @home /home @var /var @snapshots /.snapshots @swap /swap +``` + +Three facts make a naive rollback wrong: + +1. **`/var` is a separate subvolume.** The Portage package database + (`/var/db/pkg`), Portage state (`/var/lib/portage`), the update state and the + snapshot/transaction history all live in `@var`. Restoring `@` alone leaves + the package manager describing packages that do not exist in the restored + root. +2. **The kernel command line carries an explicit root subvolume.** + `rootflags=subvol=@` overrides the Btrfs default subvolume, so changing the + default alone does not change what boots. +3. **The kernel and initramfs live on the ESP, which is not snapshotted.** + A restored older root has older `/lib/modules`; it must boot a kernel whose + modules match, or it will fail to load drivers. + +The ESP also holds the BLS entries, so a recovery entry that reuses the live +root's kernel/options still depends on the root being healthy. + +## Decision + +Rollback is a **coordinated** operation over four things, implemented in +`phoebus-executor::rollback` and planned by `phoebus-core::rollback`: + +1. **Snapshot set.** A recovery point captures `@` *and* the separately mounted + `@var` under one timestamp/operation name. `/home` is intentionally excluded + so rollback never discards user documents. `/nix` is inside `@`, so the Nix + store rolls back with the OS package state (consistent by construction). + +2. **Root generation.** Rollback creates a *writable* clone of the chosen + snapshot (`@restore-`) and, when present, `@varrestore-`. The + running root is preserved by the pre-rollback snapshot; the previous root is + also offered as a boot entry. + +3. **Boot arguments, in both places.** The restored root's `/etc/fstab` is + rewritten to mount `subvol=` and `subvol=`, *and* the BLS + entries are rewritten (`rootflags=subvol=`). The Btrfs default + subvolume is set to match, as a fallback for a mount without an argument. + +4. **Kernel/initramfs pairing.** The restored root's `/lib/modules` versions are + used to select the newest BLS entry with matching modules. A "Phoebus OS + (previous)" entry and a "Phoebus Recovery" entry that boots the chosen + snapshot directly into `rescue.target` are written, so recovery does not + depend on the live root. + +### State machine and interruption safety + +`var/lib/phoebus/rollback-state.toml` records `Idle | Planned | Activated | +Verified | Failed`. The safety snapshot is taken first; boot entries are +switched last; a `sync` runs before completion. An interruption therefore leaves +the system booting a known root, and re-running resumes (an already-staged +restored root is detected and reused). `sys undo status` promotes `Activated` +to `Verified` once the restored subvolume is the running root. + +### Retention and space + +Retention keeps the newest `DEFAULT_KEEP_SNAPSHOTS` (8) committed snapshots and +never prunes the newest, an in-flight rollback target, or `Created`/`Failed` +records. Rollback refuses to start unless at least 1 GiB is free on the target. + +### Exposure + +`sys undo` is the only acceptance test for a rollback. `sys undo` restores the +newest committed snapshot; `sys undo ` selects one; `sys undo status` +reports state. It requires root and a reviewed typed action, like every other +high-risk mutation. + +## Consequences + +- More subvolumes accumulate (`@restore-*`, `@varrestore-*`); retention bounds + them and the operator can delete them explicitly. +- A rollback is a reboot-level operation; it changes the *next* boot, not the + running system. This is deliberate: swapping the mounted root in place is not + safe. +- The path is unit-tested for the command sequence, fstab/boot-entry rewriting, + kernel selection, interruption resume and retention. End-to-end VM + verification (broken update, rollback, detached boot, package-state check) is + the acceptance gate recorded in `docs/STATUS.md`. + +## Alternatives rejected + +- **Changing only the Btrfs default subvolume.** Rejected: the explicit + `rootflags=subvol=` wins, so this does not boot the restored root. +- **Renaming the mounted root subvolume.** Rejected: unsafe while it is the live + root. +- **Snapshotting the ESP.** Impossible (vfat, not Btrfs); handled instead by + selecting a matching kernel entry and keeping a known-good entry. diff --git a/docs/adr/0008-nix-isolation-lifecycle.md b/docs/adr/0008-nix-isolation-lifecycle.md new file mode 100644 index 0000000..7d81848 --- /dev/null +++ b/docs/adr/0008-nix-isolation-lifecycle.md @@ -0,0 +1,93 @@ +# ADR 0008: Nix lifecycle, build isolation, and packaging + +- **Status:** Accepted +- **Date:** 2026-09-21 + +## Context + +The first Nix bootstrap wrote `sandbox = false`, and the lifecycle (upgrade, +removal, store cleanup) was undefined. ADR 0006 claimed a normal binary ebuild +is impossible because the upstream installer hardcodes `/nix`, calls `sudo` and +uses `nix-store --load-db` with no `DESTDIR`. That claim was re-examined rather +than assumed. + +## Decision + +### Build isolation is on and does not silently fall back + +`/etc/nix/nix.conf` now sets: + +``` +sandbox = true +sandbox-fallback = false +auto-optimise-store = true +min-free = 1073741824 +max-free = 10737418240 +``` + +The Nix sandbox uses Linux user namespaces. `sandbox-fallback = false` means a +build that cannot be sandboxed fails instead of silently building with host +access. This is the same principle as "never weaken a protection for +convenience": a build-time sandbox that can be transparently disabled provides +no guarantee. The Phoebus kernel (distribution kernel plus the conservative +fragments) includes `CONFIG_USER_NS`. + +`min-free`/`max-free` bound the store so `/nix` cannot fill the root +filesystem; `auto-optimise-store` deduplicates. + +### Store cleanup and rollback interaction + +- `/nix` lives inside `@`, so a system rollback restores the store together with + the OS package state. This is intended: the Nix store is OS state. +- Garbage collection is explicit (`nix-store --gc`, bounded by `min-free`/ + `max-free`), never automatic on a timer. +- Removing Nix removes the daemon units and profile wiring; purging the store is + a separate, explicit choice, because it also removes user environments. + +### Portage-managed lifecycle + +The requirement is that Portage owns Nix: installation, upgrades, daemon +integration and removal. The upstream installer's lack of `DESTDIR` blocks a +*conventional binary ebuild*, but it does **not** block an ebuild that performs +the same bootstrap the installer performs: + +- `src_unpack` fetches the pinned, SHA-256-verified release tarball. +- `src_install` copies the release's `store/` into `${D}` (the ebuild's image), + so the files are package-owned. +- `pkg_postinst` runs `nix-store --load-db` against the live root, creates the + `nixbld` group/users, and enables `nix-daemon.service`/`.socket`. + +This is a *bootstrap-style* ebuild, not a `DESTDIR` install of a build tree; it +is the standard technique for packages that must initialise state at install +time (the same shape as `sys-apps/portage`'s news/`env-update` handling). It +belongs in the Phoebus overlay as `sys-apps/nix`. + +Until the overlay ebuild is published, the installer provisions the same +lifecycle directly (discrete, no `curl | sh`, no `sh -c`), and the runtime +lifecycle operations are implemented in `phoebus-executor::nix`: +`install`, `remove(purge)`, `gc`, and `valid_nix_attribute` for bounded +developer-package realisation. `sys` exposes `nix_prepare { packages }` as a +bounded typed action. + +### Authority + +Nix remains a **developer lane only** (ADR 0006): no core component, service, +library or boot path depends on it. Portage owns the kernel, drivers, systemd, +Mesa, PipeWire, core libraries and the boot stack. + +## Consequences + +- A build that needs user namespaces now fails closed where they are absent. +- The store is bounded; growth is visible and managed. +- The overlay ebuild is the remaining Portage-ownership step; it is documented + and its lifecycle is already exercised by the installer and `nix_*` + operations. It is not yet shipped in a repository. + +## Verification + +- Unit tests assert the generated `/etc/nix/nix.conf` enables the enforced + sandbox and store bounds, and that removal unlinks units and only purges on + request. +- VM verification of a sandboxed source build (`nix build` of a package with a + derivation that would fail without isolation) and of the ebuild lifecycle is + recorded in `docs/STATUS.md` as outstanding. diff --git a/docs/adr/0009-mango-dankmaterialshell-desktop.md b/docs/adr/0009-mango-dankmaterialshell-desktop.md new file mode 100644 index 0000000..9ce85a9 --- /dev/null +++ b/docs/adr/0009-mango-dankmaterialshell-desktop.md @@ -0,0 +1,99 @@ +# ADR 0009: Mango + DankMaterialShell desktop option + +- **Status:** Accepted +- **Date:** 2026-09-21 + +## Context + +Phoebus's flagship desktop is a hand-assembled dwl session (dwl, waybar, wofi, +mako, swaybg, swayidle, swaylock, polkit-gnome). It is lightweight and proven, +but it requires the user to assemble everyday desktop functions. Mango +(`gui-wm/mangowm`, a wlroots dwl derivative) plus DankMaterialShell (DMS, a +Quickshell shell providing panel, launcher, notifications, network/Bluetooth/ +audio controls, locking, idle and display management) is a complete, coherent +desktop that fits the Wayland/systemd/PipeWire architecture. + +The task is to offer it as an explicit profile, keep dwl as a fallback, and +promote Mango to the default only after verification. + +## Upstream and packaging facts (verified 2026-09-21) + +| Component | Package | Version | Source | License | Keyword | +|-----------|---------|---------|--------|---------|---------| +| Compositor | `gui-wm/mangowm` | 0.17.2 | GURU (community) | CC0-1.0 / GPL-3+ / MIT | `~amd64` | +| Shell | `gui-apps/dankmaterialshell` | 1.5.3 | GURU (community) | MIT | `~amd64` | +| Framework | `gui-apps/quickshell` | 0.3.1 | GURU (community) | LGPL-3 | `~amd64` | +| Search | `gui-apps/danksearch` | 0.3.2 | GURU (community) | MIT | `~amd64` | +| Effects lib | `gui-libs/scenefx` | 0.5 | GURU (community) | MIT | `~amd64` | + +- `mangowm` depends on the **wlroots 0.20 slot** and `scenefx:0.5`. +- `gui-wm/dwl` (the fallback) depends on the **wlroots 0.18 slot**. The two are + different slots, so dwl and mangowm install side by side without a forced + wlroots upgrade. +- DMS is installed from DMS's **released** tarballs (its ebuild `SRC_URI` + points at GitHub release assets); no live/git package is used. +- GURU is git-only, so `dev-vcs/git` is installed from the main tree before the + overlay is synced. +- Upstream (Quickshell/DMS) requires Qt 6.6+, which the selected + `default/linux/amd64/23.0/desktop/systemd` profile provides. + +## Decision + +1. **A new explicit profile** `desktop.profile = "mango"` installs Mango + DMS + and *also* the dwl session as a fallback. Legacy values (`none`, `minimal`, + `dwl`, `full`) keep their exact meaning. +2. **Portage owns the stack.** The installer writes `repos.conf` for GURU + (git), installs `dev-vcs/git`, syncs GURU with `emaint sync -r guru`, and + installs the packages with `emerge`. There is no `curl | sh`, no Nix, and no + live package. +3. **Testing keywords are scoped.** `package.accept_keywords/phoebus` lists only + `gui-wm/mangowm`, `gui-apps/dankmaterialshell`, `gui-apps/danksearch`, + `gui-apps/quickshell` and `gui-libs/scenefx`. `~amd64` is never enabled + globally, and Portage is not silently auto-unmasked: additional `~amd64` + dependencies must be reviewed and added deliberately. +4. **Two session entry points, one shell each.** `/usr/share/wayland-sessions` + gets `phoebus-mango.desktop` (default when the Mango profile is installed) + and `phoebus-dwl.desktop` (fallback). The Mango session starts *only* mango, + DMS (panel, launcher, notifications, lock, idle), and the shell's polkit + agent; it never starts waybar/mako/swaybg/swayidle/swaylock. The dwl session + is unchanged. +5. **User configuration is separate from packaged defaults.** The session seeds + `~/.config/mango/config.conf` from `/etc/xdg/mango/config.conf` only when + absent, and DMS manages `~/.config/mango/dms/*.conf`. Portage upgrades never + overwrite user files. +6. **Administration stays behind `sys`.** DMS's system-update controls are not + wired up; updates continue through `sys`/Portage. The assistant is reachable + from a launcher (`phoebus-assistant`) that simply runs `sys ask`, keeping the + typed-action and approval boundary. +7. **Default promotion is gated on verification.** Until the graphical-VM gates + in `docs/VM-BOOT-VERIFICATION.md` pass, the Mango profile is *selectable*, + not the default; `desktop.profile = "dwl"` remains the recommended default. + +## Update procedure + +GURU is synced by `emaint sync -r guru` on every Portage sync. To move to a new +upstream release, bump the reviewed versions in the keyword list only after +`emerge --pretend` confirms the dependency set, then rebuild the profile's +packages. The overlay is community-maintained; its ebuilds are attributed to +their maintainers (see each `metadata.xml`). + +## Consequences and risks + +- The Mango install pulls Qt, Quickshell and scenefx, so it is much heavier to + build than the dwl session; a matching signed binhost does not exist for these + GURU packages, so they compile. +- GURU is a community overlay: provenance is documented but it is not the main + Gentoo tree. The keyword scope keeps the risk limited to the listed packages. +- DMS is a fast-moving project; the integration pins a reviewed release and + documents the update path rather than tracking `9999`. +- If DMS's polkit integration does not cover every prompt, a fallback + `PHOEBUS_POLKIT_AGENT` hook is available but defaults off to avoid two agents. + +## Verification status + +Unit and source-level tests cover the profile, package set, keyword scope, +generated session scripts, config seeding and the two session entries. The +graphical-VM acceptance gates (real seat, launcher/panel/notifications/polkit, +lock/unlock, shell restart, logout cleanup, suspend/resume, Flatpak portals, +idle/memory under load) are **not yet passed**; the profile therefore stays +selectable and is not promoted to default. See `docs/STATUS.md`. diff --git a/docs/adr/README.md b/docs/adr/README.md index 7811c78..d960ad2 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -10,5 +10,10 @@ and link it here. | [0002](0002-bls-over-uki.md) | BLS entries instead of UKI for the boot path | Accepted | | [0003](0003-desktop-systemd-profile.md) | Desktop installs inherit the Gentoo desktop/systemd profile | Accepted | | [0004](0004-portage-verify-keyring.md) | Relax the getuto keyring for the dropped-privilege verifier | Accepted | +| [0005](0005-debian-live-appliance.md) | Debian-Live appliance ISO with a Gentoo target | Accepted | +| [0006](0006-package-lanes.md) | Package lanes — Portage, Flatpak, and Nix (built in) | Accepted | +| [0007](0007-coherent-rollback.md) | Coherent rollback and recovery | Accepted | +| [0008](0008-nix-isolation-lifecycle.md) | Nix lifecycle, build isolation, and packaging | Accepted | +| [0009](0009-mango-dankmaterialshell-desktop.md) | Mango + DankMaterialShell desktop option | Accepted | Format: Context / Decision / Consequences / Status. diff --git a/installer-rs/Cargo.lock b/installer-rs/Cargo.lock index 92c9cc5..267da48 100644 --- a/installer-rs/Cargo.lock +++ b/installer-rs/Cargo.lock @@ -497,6 +497,7 @@ version = "0.1.0" dependencies = [ "serde", "serde_json", + "sha2", "tempfile", "thiserror", "toml", diff --git a/installer-rs/crates/phoebus-ai/src/assistant.rs b/installer-rs/crates/phoebus-ai/src/assistant.rs new file mode 100644 index 0000000..2eb46ed --- /dev/null +++ b/installer-rs/crates/phoebus-ai/src/assistant.rs @@ -0,0 +1,287 @@ +//! Installed conversational assistant: natural request -> validated typed plan. +//! +//! The model is given only bounded system facts and a closed action schema. It +//! returns an [`AssistantPlan`] whose actions deserialize into the same +//! `SystemAction` enum `sys` executes. Nothing here runs with privilege: the +//! caller shows the plan, obtains approval, and the deterministic broker in +//! `phoebus-executor` executes it. + +use phoebus_core::action::SystemAction; +use serde::{Deserialize, Serialize}; + +use crate::provider::{ChatMessage, ChatRequest, ModelTransport, ProviderKind, SystemFacts}; +use crate::AiError; + +/// One reason per proposed action. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct AssistantRationale { + pub action: String, + pub reason: String, +} + +/// A validated plan from the model. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct AssistantPlan { + pub version: u32, + /// A short, human-readable explanation of the plan. + pub summary: String, + #[serde(default)] + pub actions: Vec, + #[serde(default)] + pub rationale: Vec, +} + +impl AssistantPlan { + pub fn render(&self) -> String { + let mut out = String::new(); + out.push_str(&format!("{}\n", self.summary)); + if self.actions.is_empty() { + out.push_str("(no system actions proposed)\n"); + } + for action in &self.actions { + out.push_str(&format!(" - {}\n", action.describe())); + if let Some(r) = self + .rationale + .iter() + .find(|r| r.action == action_tag(action)) + { + out.push_str(&format!(" reason: {}\n", r.reason)); + } + } + out + } +} + +/// The serde tag of an action (`install_package`, ...). +pub fn action_tag(action: &SystemAction) -> String { + serde_json::to_value(action) + .ok() + .and_then(|v| v.get("action").and_then(|a| a.as_str()).map(str::to_string)) + .unwrap_or_default() +} + +/// The system prompt for the installed assistant. The action set is closed and +/// there is no shell or file action. +pub const ASSISTANT_PROMPT: &str = "\ +You are the Phoebus OS system assistant. You can ONLY propose actions from this \ +closed set: inspect_service, enable_service, disable_service, inspect_package, \ +install_package, remove_package, search_packages, flatpak_install, flatpak_remove, \ +flatpak_list, nix_prepare, create_snapshot, undo, rollback_status, history, \ +update_system, prepare_updates, inspect_updates. + +Reply with ONLY a JSON object: +{\"version\":1,\"summary\":\"...\",\"actions\":[{\"action\":\"...\",...}],\ +\"rationale\":[{\"action\":\"...\",\"reason\":\"...\"}]} + +Rules: give every action a non-empty reason; prefer inspection before mutation; \ +never propose disabling verification, enabling ~amd64 globally, weakening \ +LUKS2/Btrfs/systemd/UEFI, or any shell, file or arbitrary command action. You do \ +not have a shell, credentials, or access to private files. A human reviews and \ +authenticates every mutation."; + +/// Parse and validate an assistant plan, fail-closed. +pub fn parse_plan(text: &str) -> Result { + let plan: AssistantPlan = serde_json::from_str(text)?; + if plan.version != 1 { + return Err(AiError::UnsupportedVersion(plan.version)); + } + if plan.summary.trim().is_empty() { + return Err(AiError::Rejected("plan has no summary".into())); + } + for action in &plan.actions { + action + .validate() + .map_err(|e| AiError::Rejected(format!("{}: {e}", action.describe())))?; + let tag = action_tag(action); + let has_reason = plan + .rationale + .iter() + .any(|r| r.action == tag && !r.reason.trim().is_empty()); + if !has_reason { + return Err(AiError::Rejected(format!( + "{}: missing a non-empty reason", + action.describe() + ))); + } + } + Ok(plan) +} + +/// Build the chat request for a user instruction plus system facts. +pub fn build_request( + provider: ProviderKind, + model: &str, + facts: &SystemFacts, + instruction: &str, +) -> ChatRequest { + let model = if model.trim().is_empty() { + provider.default_model().to_string() + } else { + model.trim().to_string() + }; + let user = format!( + "Bounded system facts (JSON):\n{}\n\nUser request: {instruction}\n\n\ + Respond with a version 1 assistant plan.", + facts.render() + ); + ChatRequest { + model, + messages: vec![ + ChatMessage { + role: "system".into(), + content: ASSISTANT_PROMPT.into(), + }, + ChatMessage { + role: "user".into(), + content: user, + }, + ], + temperature: 0.0, + response_format: Some(crate::provider::ResponseFormat { + kind: "json_object".into(), + }), + } +} + +/// Ask the provider for a plan and parse it, fail-closed at every step. +pub fn complete_plan( + provider: ProviderKind, + endpoint: &str, + model: &str, + facts: &SystemFacts, + instruction: &str, + transport: &dyn ModelTransport, +) -> Result { + if provider == ProviderKind::None { + return Err(AiError::ProviderUnavailable( + "no AI provider selected".into(), + )); + } + if endpoint.trim().is_empty() { + return Err(AiError::ProviderUnavailable( + "no provider endpoint configured".into(), + )); + } + facts.validate_no_forbidden()?; + let request = build_request(provider, model, facts, instruction); + let body = serde_json::to_string(&request)?; + let response = transport.send(provider, endpoint, &body)?; + let content = crate::provider::extract_content(&response)?; + parse_plan(&content) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::provider::TestTransport; + use phoebus_core::hardware::HardwareReport; + use phoebus_core::InstallConfig; + + fn facts() -> SystemFacts { + SystemFacts::from_system( + &InstallConfig::default(), + &HardwareReport::default(), + &std::collections::HashMap::new(), + true, + None, + ) + } + + fn wrap(plan_json: &str) -> String { + serde_json::json!({ + "choices": [{ "message": { "content": plan_json } }] + }) + .to_string() + } + + #[test] + fn parses_a_valid_plan() { + let text = r#"{ + "version": 1, + "summary": "Check ssh and install vim", + "actions": [ + {"action":"inspect_service","name":"sshd"}, + {"action":"install_package","atom":"app-editors/vim"} + ], + "rationale": [ + {"action":"inspect_service","reason":"confirm it is present"}, + {"action":"install_package","reason":"the user asked for vim"} + ] + }"#; + let plan = parse_plan(text).unwrap(); + assert_eq!(plan.actions.len(), 2); + assert!(plan.render().contains("install package app-editors/vim")); + assert!(plan.render().contains("reason: the user asked for vim")); + } + + #[test] + fn unknown_actions_and_shell_fail_closed() { + let text = r#"{"version":1,"summary":"x","actions":[{"action":"run_shell","command":"rm -rf /"}],"rationale":[{"action":"run_shell","reason":"no"}]}"#; + assert!(parse_plan(text).is_err()); + } + + #[test] + fn actions_require_a_reason() { + let text = r#"{"version":1,"summary":"x","actions":[{"action":"enable_service","name":"sshd"}],"rationale":[]}"#; + assert!(matches!(parse_plan(text), Err(AiError::Rejected(_)))); + let empty_reason = r#"{"version":1,"summary":"x","actions":[{"action":"enable_service","name":"sshd"}],"rationale":[{"action":"enable_service","reason":" "}]}"#; + assert!(parse_plan(empty_reason).is_err()); + } + + #[test] + fn invalid_values_are_rejected() { + let text = r#"{"version":1,"summary":"x","actions":[{"action":"install_package","atom":"bad atom"}],"rationale":[{"action":"install_package","reason":"x"}]}"#; + assert!(parse_plan(text).is_err()); + } + + #[test] + fn transport_round_trip_and_unavailable_provider() { + let plan = r#"{"version":1,"summary":"look","actions":[{"action":"history"}],"rationale":[{"action":"history","reason":"user asked"}]}"#; + let transport = TestTransport::new(wrap(plan)); + let parsed = complete_plan( + ProviderKind::DeepSeek, + "https://api.deepseek.com/chat/completions", + "", + &facts(), + "what changed?", + &transport, + ) + .unwrap(); + assert_eq!(parsed.actions.len(), 1); + assert!(complete_plan(ProviderKind::None, "", "", &facts(), "hi", &transport).is_err()); + assert!(complete_plan(ProviderKind::Local, "", "", &facts(), "hi", &transport).is_err()); + } + + #[test] + fn malformed_responses_are_reported_not_ignored() { + let transport = TestTransport::new(wrap("not json at all")); + assert!(complete_plan( + ProviderKind::Local, + "http://127.0.0.1:11434/v1/chat/completions", + "m", + &facts(), + "hi", + &transport + ) + .is_err()); + // A response with no choices is a provider error. + let empty = TestTransport::new("{\"choices\":[]}"); + assert!(complete_plan( + ProviderKind::Local, + "http://127.0.0.1:11434/v1/chat/completions", + "m", + &facts(), + "hi", + &empty + ) + .is_err()); + } + + #[test] + fn action_tag_matches_the_schema() { + assert_eq!(action_tag(&SystemAction::History), "history"); + assert_eq!(action_tag(&SystemAction::FlatpakList), "flatpak_list"); + } +} diff --git a/installer-rs/crates/phoebus-ai/src/lib.rs b/installer-rs/crates/phoebus-ai/src/lib.rs index 64fb5ee..f27c561 100644 --- a/installer-rs/crates/phoebus-ai/src/lib.rs +++ b/installer-rs/crates/phoebus-ai/src/lib.rs @@ -6,6 +6,7 @@ //! the typed configuration. Privileged execution is a separate, human-approved //! step performed by the deterministic backend. +pub mod assistant; pub mod privacy; pub mod provider; diff --git a/installer-rs/crates/phoebus-core/Cargo.toml b/installer-rs/crates/phoebus-core/Cargo.toml index 55fe06c..c923cce 100644 --- a/installer-rs/crates/phoebus-core/Cargo.toml +++ b/installer-rs/crates/phoebus-core/Cargo.toml @@ -11,6 +11,7 @@ toml.workspace = true serde_json.workspace = true thiserror.workspace = true zeroize.workspace = true +sha2 = "0.10" [dev-dependencies] tempfile.workspace = true diff --git a/installer-rs/crates/phoebus-core/src/action.rs b/installer-rs/crates/phoebus-core/src/action.rs index d9968dc..f3cb955 100644 --- a/installer-rs/crates/phoebus-core/src/action.rs +++ b/installer-rs/crates/phoebus-core/src/action.rs @@ -26,14 +26,50 @@ pub enum Risk { #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] #[serde(tag = "action", rename_all = "snake_case", deny_unknown_fields)] pub enum SystemAction { - InspectService { name: String }, - EnableService { name: String }, - DisableService { name: String }, - InspectPackage { atom: String }, - InstallPackage { atom: String }, - RemovePackage { atom: String }, - SearchPackages { query: String }, - CreateSnapshot { operation: String }, + InspectService { + name: String, + }, + EnableService { + name: String, + }, + DisableService { + name: String, + }, + InspectPackage { + atom: String, + }, + InstallPackage { + atom: String, + }, + RemovePackage { + atom: String, + }, + SearchPackages { + query: String, + }, + /// Install a sandboxed Flatpak application from flathub. + FlatpakInstall { + app_id: String, + }, + FlatpakRemove { + app_id: String, + }, + FlatpakList, + /// Realise bounded nixpkgs development packages into the Nix store. + NixPrepare { + packages: Vec, + }, + CreateSnapshot { + operation: String, + }, + /// Restore a committed snapshot as the next boot root. `snapshot` selects a + /// specific id; unset means the newest committed snapshot. + Undo { + #[serde(default, skip_serializing_if = "Option::is_none")] + snapshot: Option, + }, + /// Report the rollback state (no mutation). + RollbackStatus, History, UpdateSystem, PrepareUpdates, @@ -54,9 +90,22 @@ impl SystemAction { SystemAction::SearchPackages { query } => { format!("search packages for `{query}`") } + SystemAction::FlatpakInstall { app_id } => { + format!("install Flatpak app {app_id} from flathub") + } + SystemAction::FlatpakRemove { app_id } => format!("remove Flatpak app {app_id}"), + SystemAction::FlatpakList => "list installed Flatpak apps".to_string(), + SystemAction::NixPrepare { packages } => { + format!("realise Nix development packages: {}", packages.join(", ")) + } SystemAction::CreateSnapshot { operation } => { format!("create a Btrfs snapshot before: {operation}") } + SystemAction::Undo { snapshot } => match snapshot { + Some(id) => format!("roll back to snapshot {id} (restore as next boot root)"), + None => "roll back to the newest committed snapshot".to_string(), + }, + SystemAction::RollbackStatus => "show the rollback state".to_string(), SystemAction::History => "show system transaction history".to_string(), SystemAction::PrepareUpdates => { "prepare background updates (fetch + build binary packages, do not activate)" @@ -76,13 +125,19 @@ impl SystemAction { | SystemAction::SearchPackages { .. } => Risk::Low, SystemAction::History => Risk::Low, SystemAction::InspectUpdates => Risk::Low, + SystemAction::RollbackStatus => Risk::Low, + SystemAction::FlatpakList => Risk::Low, SystemAction::PrepareUpdates => Risk::Medium, SystemAction::EnableService { .. } | SystemAction::DisableService { .. } - | SystemAction::CreateSnapshot { .. } => Risk::Medium, + | SystemAction::CreateSnapshot { .. } + | SystemAction::FlatpakInstall { .. } + | SystemAction::FlatpakRemove { .. } + | SystemAction::NixPrepare { .. } => Risk::Medium, SystemAction::InstallPackage { .. } | SystemAction::RemovePackage { .. } - | SystemAction::UpdateSystem => Risk::High, + | SystemAction::UpdateSystem + | SystemAction::Undo { .. } => Risk::High, } } @@ -96,6 +151,8 @@ impl SystemAction { | SystemAction::SearchPackages { .. } | SystemAction::History | SystemAction::InspectUpdates + | SystemAction::RollbackStatus + | SystemAction::FlatpakList ) } @@ -132,6 +189,28 @@ impl SystemAction { Err(format!("invalid search query: {query}")) } } + SystemAction::FlatpakInstall { app_id } | SystemAction::FlatpakRemove { app_id } => { + if valid_flatpak_app_id(app_id) { + Ok(()) + } else { + Err(format!("invalid Flatpak application id: {app_id}")) + } + } + SystemAction::FlatpakList => Ok(()), + SystemAction::NixPrepare { packages } => { + if packages.is_empty() { + return Err("nix prepare requires at least one package".into()); + } + if packages.len() > 32 { + return Err("too many Nix packages (max 32)".into()); + } + for package in packages { + if !valid_nix_attribute(package) { + return Err(format!("invalid nixpkgs attribute: {package}")); + } + } + Ok(()) + } SystemAction::CreateSnapshot { operation } => { if operation.is_empty() { Err("snapshot operation must not be empty".into()) @@ -139,10 +218,15 @@ impl SystemAction { Ok(()) } } + SystemAction::Undo { snapshot } => match snapshot { + Some(id) if !valid_token(id) => Err(format!("invalid snapshot id: {id}")), + _ => Ok(()), + }, SystemAction::History | SystemAction::UpdateSystem | SystemAction::PrepareUpdates - | SystemAction::InspectUpdates => Ok(()), + | SystemAction::InspectUpdates + | SystemAction::RollbackStatus => Ok(()), } } } @@ -181,11 +265,55 @@ pub fn valid_search_query(query: &str) -> bool { .all(|c| c.is_ascii_alphanumeric() || " ._+@/-".contains(c)) } +/// A Flatpak application id: reverse-DNS, e.g. `org.chromium.Chromium`. No +/// slashes, spaces, or shell metacharacters. +pub fn valid_flatpak_app_id(app_id: &str) -> bool { + !app_id.is_empty() + && app_id.len() <= 128 + && app_id.contains('.') + && !app_id.starts_with('.') + && !app_id.ends_with('.') + && app_id + .chars() + .all(|c| c.is_ascii_alphanumeric() || ".-_".contains(c)) +} + +/// A bounded nixpkgs attribute name (`nodejs`, `python312`). No slashes, URLs, +/// or flake references, so the assistant cannot make Nix evaluate arbitrary +/// remote inputs. +pub fn valid_nix_attribute(value: &str) -> bool { + !value.is_empty() + && value.len() <= 64 + && value + .chars() + .all(|c| c.is_ascii_alphanumeric() || "+-._".contains(c)) + && !value.contains('/') + && !value.contains(':') +} + /// A small deterministic parser for common `sys` phrases. /// /// Free-form requests that do not match are left to the AI path /// (`--action-file`), which still produces the same typed schema. pub fn parse_natural(text: &str) -> Option { + // Snapshot ids are case-sensitive (`@-20260101T000000-...`), so parse the + // undo form from the original text before the general lowercasing. + let raw = text.trim(); + let raw_lower = raw.to_ascii_lowercase(); + for prefix in ["undo ", "rollback "] { + if raw_lower.starts_with(prefix) { + let id = raw[prefix.len()..].trim(); + if id.eq_ignore_ascii_case("status") { + return Some(SystemAction::RollbackStatus); + } + if !id.is_empty() { + return Some(SystemAction::Undo { + snapshot: Some(id.to_string()), + }); + } + } + } + let t = text.trim().to_lowercase(); let rest = |prefix: &str| t.strip_prefix(prefix).map(|r| r.trim().to_string()); @@ -224,6 +352,20 @@ pub fn parse_natural(text: &str) -> Option { return Some(SystemAction::InspectService { name }); } } + if let Some(id) = rest("undo ").or_else(|| rest("rollback ")) { + if id == "status" { + return Some(SystemAction::RollbackStatus); + } + if !id.is_empty() { + return Some(SystemAction::Undo { snapshot: Some(id) }); + } + } + if t == "undo" || t == "rollback" { + return Some(SystemAction::Undo { snapshot: None }); + } + if t.contains("rollback status") || t.contains("undo status") { + return Some(SystemAction::RollbackStatus); + } if t == "history" || t.starts_with("history ") { return Some(SystemAction::History); @@ -343,4 +485,71 @@ mod tests { Risk::High ); } + + #[test] + fn undo_is_high_risk_and_mutating() { + let undo = parse_action(r#"{"action":"undo"}"#).unwrap(); + assert_eq!(undo.risk(), Risk::High); + assert!(undo.is_mutating()); + assert_eq!(undo, SystemAction::Undo { snapshot: None }); + let specific = + parse_action(r#"{"action":"undo","snapshot":"@-20260101T000000-sys-update"}"#).unwrap(); + assert_eq!( + specific, + SystemAction::Undo { + snapshot: Some("@-20260101T000000-sys-update".into()) + } + ); + // Unknown fields and bad ids fail closed. + assert!(parse_action(r#"{"action":"undo","shell":"sh"}"#).is_err()); + assert!(parse_action(r#"{"action":"undo","snapshot":"bad id"}"#).is_err()); + let status = parse_action(r#"{"action":"rollback_status"}"#).unwrap(); + assert!(!status.is_mutating()); + assert_eq!(status.risk(), Risk::Low); + } + + #[test] + fn natural_undo_phrases() { + assert_eq!( + parse_natural("undo"), + Some(SystemAction::Undo { snapshot: None }) + ); + assert_eq!( + parse_natural("undo status"), + Some(SystemAction::RollbackStatus) + ); + assert_eq!( + parse_natural("undo @-20260101T000000-sys-update"), + Some(SystemAction::Undo { + snapshot: Some("@-20260101T000000-sys-update".into()) + }) + ); + } + + #[test] + fn flatpak_and_nix_actions_are_bounded() { + let install = + parse_action(r#"{"action":"flatpak_install","app_id":"org.chromium.Chromium"}"#) + .unwrap(); + assert_eq!(install.risk(), Risk::Medium); + assert!(install.is_mutating()); + assert!(parse_action(r#"{"action":"flatpak_install","app_id":"bad id"}"#).is_err()); + assert!(parse_action(r#"{"action":"flatpak_install","app_id":"nodots"}"#).is_err()); + + let list = parse_action(r#"{"action":"flatpak_list"}"#).unwrap(); + assert!(!list.is_mutating()); + + let nix = + parse_action(r#"{"action":"nix_prepare","packages":["nodejs","python312"]}"#).unwrap(); + assert_eq!(nix.risk(), Risk::Medium); + assert!(nix.is_mutating()); + assert!(parse_action(r#"{"action":"nix_prepare","packages":[]}"#).is_err()); + assert!( + parse_action(r#"{"action":"nix_prepare","packages":["github:evil/repo"]}"#).is_err() + ); + assert!(valid_nix_attribute("python312")); + assert!(!valid_nix_attribute("nixpkgs#x/y")); + assert!(valid_flatpak_app_id("com.spotify.Client")); + assert!(!valid_flatpak_app_id("com/spotify")); + } } diff --git a/installer-rs/crates/phoebus-core/src/boot.rs b/installer-rs/crates/phoebus-core/src/boot.rs new file mode 100644 index 0000000..bce17e2 --- /dev/null +++ b/installer-rs/crates/phoebus-core/src/boot.rs @@ -0,0 +1,293 @@ +//! Boot Loader Specification (BLS) entry parsing and root-selection planning. +//! +//! systemd-boot reads `/loader/entries/*.conf` on the ESP. A rollback must edit +//! those entries, not just the Btrfs default subvolume: the kernel command line +//! carries an explicit `rootflags=subvol=...`, which overrides the default. +//! These are pure functions so the exact text written into the ESP is testable +//! without a real disk. + +/// One BLS entry, preserving unknown keys verbatim. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct BlsEntry { + pub file_name: String, + pub title: String, + pub linux: String, + pub initrds: Vec, + pub options: String, + pub extra: Vec, +} + +impl BlsEntry { + /// Parse a BLS entry. Returns `None` when there is no `linux` line, which + /// means it is not a bootable kernel entry. + pub fn parse(file_name: &str, text: &str) -> Option { + let mut title = String::new(); + let mut linux = String::new(); + let mut initrds = Vec::new(); + let mut options = String::new(); + let mut extra = Vec::new(); + for line in text.lines() { + let trimmed = line.trim(); + if trimmed.is_empty() || trimmed.starts_with('#') { + continue; + } + let (key, value) = match trimmed.split_once(char::is_whitespace) { + Some((k, v)) => (k, v.trim()), + None => (trimmed, ""), + }; + match key { + "title" => title = value.to_string(), + "linux" => linux = value.to_string(), + "initrd" => initrds.push(value.to_string()), + "options" => options = value.to_string(), + _ => extra.push(trimmed.to_string()), + } + } + if linux.is_empty() { + return None; + } + Some(Self { + file_name: file_name.to_string(), + title, + linux, + initrds, + options, + extra, + }) + } + + /// Render back to BLS text. + pub fn render(&self) -> String { + let mut out = String::new(); + if !self.title.is_empty() { + out.push_str(&format!("title {}\n", self.title)); + } + out.push_str(&format!("linux {}\n", self.linux)); + for initrd in &self.initrds { + out.push_str(&format!("initrd {initrd}\n")); + } + if !self.options.trim().is_empty() { + out.push_str(&format!("options {}\n", self.options.trim())); + } + for line in &self.extra { + out.push_str(line); + out.push('\n'); + } + out + } + + /// The kernel version implied by the `linux` path + /// (`///linux`). + pub fn kernel_version(&self) -> Option { + let parts: Vec<&str> = self.linux.split('/').filter(|p| !p.is_empty()).collect(); + // The segment immediately before the kernel file name is the version. + let last = parts.last()?; + if *last == "linux" || last.ends_with("vmlinuz") { + parts + .get(parts.len().checked_sub(2)?) + .map(|s| s.to_string()) + } else { + None + } + } + + /// Return a copy whose `options` selects a different root subvolume. + pub fn with_root_subvol(&self, subvol: &str) -> Result { + let mut entry = self.clone(); + entry.options = replace_root_subvol(&self.options, subvol)?; + Ok(entry) + } + + /// Return a copy with an extra option appended (e.g. `systemd.unit=`). + pub fn with_option(&self, extra: &str) -> Self { + let mut entry = self.clone(); + entry.options = format!("{} {}", entry.options.trim(), extra) + .trim() + .to_string(); + entry + } + + pub fn with_title(&self, title: &str) -> Self { + let mut entry = self.clone(); + entry.title = title.to_string(); + entry + } +} + +/// Replace the `rootflags=subvol=` component of a kernel command line. +/// +/// The reader must not assume the Btrfs default subvolume changes what is +/// mounted: an explicit `subvol=` argument always wins, so rollback edits it. +pub fn replace_root_subvol(options: &str, subvol: &str) -> Result { + if subvol.is_empty() || subvol.contains(char::is_whitespace) || subvol.contains(',') { + return Err(format!("invalid root subvolume name: {subvol}")); + } + let mut replaced = false; + let mut out: Vec = Vec::new(); + for token in options.split_whitespace() { + if let Some(rest) = token.strip_prefix("rootflags=") { + let mut parts: Vec = Vec::new(); + for part in rest.split(',') { + if part.starts_with("subvol=") { + parts.push(format!("subvol={subvol}")); + replaced = true; + } else if !part.is_empty() { + parts.push(part.to_string()); + } + } + if !parts.iter().any(|p| p.starts_with("subvol=")) { + parts.push(format!("subvol={subvol}")); + replaced = true; + } + out.push(format!("rootflags={}", parts.join(","))); + } else if token == "subvol=" { + out.push(format!("subvol={subvol}")); + replaced = true; + } else { + out.push(token.to_string()); + } + } + if !replaced { + return Err("command line has no rootflags=subvol= to replace".into()); + } + Ok(out.join(" ")) +} + +/// Compare kernel versions as numeric components (e.g. `6.12.9` > `6.12.10`? +/// no: `6.12.10` > `6.12.9` because components are compared numerically). +pub fn version_key(version: &str) -> Vec { + version + .split(|c: char| !c.is_ascii_digit()) + .filter(|s| !s.is_empty()) + .filter_map(|s| s.parse::().ok()) + .collect() +} + +/// The newest BLS entry whose kernel version is present in `available` +/// (the restored root's `/lib/modules`), so a rolled-back root boots a kernel +/// that still has matching modules. +pub fn choose_entry_for_versions<'a>( + entries: &'a [BlsEntry], + available: &[String], +) -> Option<&'a BlsEntry> { + let mut best: Option<&BlsEntry> = None; + for entry in entries { + let Some(version) = entry.kernel_version() else { + continue; + }; + if !available.iter().any(|v| v == &version) { + continue; + } + let better = match best { + None => true, + Some(current) => { + let a = version_key(&version); + let b = current + .kernel_version() + .map(|v| version_key(&v)) + .unwrap_or_default(); + a > b + } + }; + if better { + best = Some(entry); + } + } + best +} + +/// The kernel versions present under a restored root's `lib/modules` listing. +pub fn kernel_versions_from_module_dirs(names: &[String]) -> Vec { + names + .iter() + .filter(|n| { + !n.is_empty() + && n.chars() + .next() + .map(|c| c.is_ascii_digit()) + .unwrap_or(false) + }) + .cloned() + .collect() +} + +#[cfg(test)] +mod tests { + use super::*; + + const ENTRY: &str = "title Gentoo Linux\n\ + linux /abcd/6.12.9/linux\n\ + initrd /abcd/6.12.9/initrd\n\ + options rd.luks.name=u=cryptroot root=/dev/mapper/cryptroot rootfstype=btrfs rootflags=subvol=@ rw quiet\n"; + + #[test] + fn parses_and_renders_roundtrip() { + let entry = BlsEntry::parse("abcd-6.12.9.conf", ENTRY).unwrap(); + assert_eq!(entry.kernel_version().as_deref(), Some("6.12.9")); + let rendered = entry.render(); + assert!(rendered.contains("title Gentoo Linux")); + assert!(rendered.contains("linux /abcd/6.12.9/linux")); + assert!(rendered.contains("initrd /abcd/6.12.9/initrd")); + assert!(BlsEntry::parse("x.conf", "# only a comment\n").is_none()); + } + + #[test] + fn replaces_the_explicit_root_subvolume() { + let entry = BlsEntry::parse("e.conf", ENTRY).unwrap(); + let updated = entry.with_root_subvol("@restore-20260101T000000").unwrap(); + assert!(updated + .options + .contains("rootflags=subvol=@restore-20260101T000000")); + assert!(!updated.options.contains("subvol=@ ")); + // Other rootflags are preserved. + assert!(updated.options.contains("rootfstype=btrfs")); + } + + #[test] + fn replace_handles_missing_subvol_and_rejects_empty() { + assert!(replace_root_subvol("root=/dev/x rootflags=rw", "@new") + .unwrap() + .contains("subvol=@new")); + assert!(replace_root_subvol("root=/dev/x", "@new").is_err()); + assert!(replace_root_subvol("rootflags=subvol=@", "").is_err()); + assert!(replace_root_subvol("rootflags=subvol=@", "bad name").is_err()); + } + + #[test] + fn chooses_the_newest_entry_with_matching_modules() { + let a = BlsEntry::parse( + "a.conf", + "title A\nlinux /id/6.12.9/linux\noptions rootflags=subvol=@\n", + ) + .unwrap(); + let b = BlsEntry::parse( + "b.conf", + "title B\nlinux /id/6.12.10/linux\noptions rootflags=subvol=@\n", + ) + .unwrap(); + let c = BlsEntry::parse( + "c.conf", + "title C\nlinux /id/6.13.1/linux\noptions rootflags=subvol=@\n", + ) + .unwrap(); + let entries = vec![a, b, c]; + let modules = vec!["6.12.9".to_string(), "6.12.10".to_string()]; + let chosen = choose_entry_for_versions(&entries, &modules).unwrap(); + assert_eq!(chosen.title, "B"); + // No matching modules at all -> refuse to select. + assert!(choose_entry_for_versions(&entries, &["5.0.0".to_string()]).is_none()); + } + + #[test] + fn module_dir_filter_ignores_non_versions() { + let names = vec![ + "6.12.9".to_string(), + "modules.order".to_string(), + "6.12.9-gentoo".to_string(), + ]; + let versions = kernel_versions_from_module_dirs(&names); + assert!(versions.contains(&"6.12.9".to_string())); + assert!(versions.contains(&"6.12.9-gentoo".to_string())); + assert!(!versions.iter().any(|v| v == "modules.order")); + } +} diff --git a/installer-rs/crates/phoebus-core/src/config.rs b/installer-rs/crates/phoebus-core/src/config.rs index d37d2e5..787f7c6 100644 --- a/installer-rs/crates/phoebus-core/src/config.rs +++ b/installer-rs/crates/phoebus-core/src/config.rs @@ -60,7 +60,7 @@ string_enum!(Encryption { None => "none", Luks2 => "luks2" }); string_enum!(Bootloader { SystemdBoot => "systemd-boot" }); string_enum!(KernelProfile { Safe => "safe", Optimized => "optimized", Aggressive => "aggressive" }); string_enum!(PackagePolicy { Balanced => "balanced", SourceFirst => "source_first", BinaryFirst => "binary_first" }); -string_enum!(DesktopProfile { None => "none", Minimal => "minimal", Dwl => "dwl", Full => "full" }); +string_enum!(DesktopProfile { None => "none", Minimal => "minimal", Dwl => "dwl", Mango => "mango", Full => "full" }); impl Bootloader { pub fn default_systemd_boot() -> Self { diff --git a/installer-rs/crates/phoebus-core/src/effects.rs b/installer-rs/crates/phoebus-core/src/effects.rs new file mode 100644 index 0000000..5cec74e --- /dev/null +++ b/installer-rs/crates/phoebus-core/src/effects.rs @@ -0,0 +1,386 @@ +//! Resolved package effects and plan binding. +//! +//! A generic "install X" preview is not enough: an update can pull in package +//! upgrades, downgrades, rebuilds and removals, choose signed binaries or source +//! builds, and consume real bandwidth and disk. These types parse Portage's +//! `--pretend` output into a concrete effect list, compute a digest, and let the +//! caller bind an approval to exactly the reviewed plan. Before execution the +//! plan is resolved again and a material change aborts. + +use serde::{Deserialize, Serialize}; +use sha2::{Digest, Sha256}; + +/// What a package entry will do. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum EffectKind { + New, + Upgrade, + Downgrade, + Rebuild, + Remove, + /// A package that Portage will not change, or an unclassified line. + Other, +} + +/// Where the package comes from. Provenance is explicit so Portage authority is +/// visible in the preview. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum EffectSource { + /// A signed binary package from a configured binhost. + Binary, + /// A source build. + Source, + /// No artifact (removal). + None, +} + +/// One resolved package effect. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct PackageEffect { + /// The full atom Portage reported (e.g. `dev-lang/python-3.12.6:3.12`). + pub target: String, + /// The previous version for an upgrade/downgrade, when reported. + pub previous: Option, + pub kind: EffectKind, + pub source: EffectSource, +} + +/// A fully resolved, human-reviewable plan. +#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)] +#[serde(default)] +pub struct ResolvedPlan { + pub effects: Vec, + pub download_bytes: Option, + /// A recovery point that will exist before the change (snapshot id). + pub recovery_point: Option, + /// Material consequences shown to the human before approval. + pub consequences: Vec, + /// Stable digest of the effect list, used to bind approval to the review. + pub digest: String, +} + +impl ResolvedPlan { + pub fn additions(&self) -> usize { + self.effects + .iter() + .filter(|e| e.kind == EffectKind::New) + .count() + } + + pub fn upgrades(&self) -> usize { + self.effects + .iter() + .filter(|e| e.kind == EffectKind::Upgrade) + .count() + } + + pub fn downgrades(&self) -> usize { + self.effects + .iter() + .filter(|e| e.kind == EffectKind::Downgrade) + .count() + } + + pub fn removals(&self) -> usize { + self.effects + .iter() + .filter(|e| e.kind == EffectKind::Remove) + .count() + } + + pub fn source_builds(&self) -> usize { + self.effects + .iter() + .filter(|e| e.source == EffectSource::Source) + .count() + } + + pub fn binary_packages(&self) -> usize { + self.effects + .iter() + .filter(|e| e.source == EffectSource::Binary) + .count() + } + + /// Recompute the digest from the effect list. Always called after parsing so + /// the digest cannot drift from the effects. + pub fn recompute_digest(&mut self) { + let mut hasher = Sha256::new(); + for effect in &self.effects { + hasher.update(effect.target.as_bytes()); + hasher.update(b"\0"); + hasher.update(format!("{:?}", effect.kind).as_bytes()); + hasher.update(b"\0"); + hasher.update(format!("{:?}", effect.source).as_bytes()); + hasher.update(b"\0"); + if let Some(prev) = &effect.previous { + hasher.update(prev.as_bytes()); + } + hasher.update(b"\n"); + } + self.digest = format!("{:x}", hasher.finalize()); + } + + /// A concrete, human-readable effect preview. + pub fn render(&self) -> String { + let mut out = String::new(); + out.push_str("Resolved effects:\n"); + if self.effects.is_empty() { + out.push_str(" (no package changes)\n"); + } + for effect in &self.effects { + let source = match effect.source { + EffectSource::Binary => "binary", + EffectSource::Source => "source", + EffectSource::None => "remove", + }; + match &effect.previous { + Some(prev) if effect.kind != EffectKind::New => { + out.push_str(&format!( + " [{:?}] {} ({} -> {}), {source}\n", + effect.kind, effect.target, prev, effect.target + )); + } + _ => out.push_str(&format!( + " [{:?}] {}, {source}\n", + effect.kind, effect.target + )), + } + } + out.push_str(&format!( + " totals: {} new, {} upgrade, {} downgrade, {} remove; \ + {} source / {} binary\n", + self.additions(), + self.upgrades(), + self.downgrades(), + self.removals(), + self.source_builds(), + self.binary_packages() + )); + if let Some(bytes) = self.download_bytes { + out.push_str(&format!(" download: {} MiB\n", bytes / (1024 * 1024))); + } + for consequence in &self.consequences { + out.push_str(&format!(" ! {consequence}\n")); + } + if let Some(point) = &self.recovery_point { + out.push_str(&format!(" recovery point: {point}\n")); + } + out.push_str(&format!(" plan digest: {}\n", self.digest)); + out + } +} + +/// Parse the totals line's `Size of downloads` value. +fn parse_download_bytes(text: &str) -> Option { + for line in text.lines() { + if let Some(idx) = line.find("Size of downloads:") { + let rest = line[idx + "Size of downloads:".len()..].trim(); + // e.g. "10,000 KiB" or "1.5 MiB" + let mut number = String::new(); + for c in rest.chars() { + if c.is_ascii_digit() || c == '.' { + number.push(c); + } else if c == ',' { + // Portage uses commas as thousands separators. + continue; + } else if !number.is_empty() { + break; + } + } + let value: f64 = number.parse().ok()?; + let unit = rest.to_ascii_lowercase(); + let multiplier = if unit.contains("gib") { + 1024.0 * 1024.0 * 1024.0 + } else if unit.contains("mib") { + 1024.0 * 1024.0 + } else { + 1024.0 + }; + return Some((value * multiplier) as u64); + } + } + None +} + +fn kind_and_source(bracket: &str) -> (EffectKind, EffectSource) { + let lower = bracket.to_ascii_lowercase(); + let source = if lower.contains("binary") { + EffectSource::Binary + } else if lower.contains("uninstall") || lower.contains("clean") { + EffectSource::None + } else { + EffectSource::Source + }; + // The action letter follows the program name: `ebuild U`, `binary N`. + // It is case-sensitive: U is an upgrade, D a downgrade, R a rebuild. + let action = bracket.split_whitespace().nth(1).unwrap_or(""); + let kind = if lower.contains("uninstall") { + EffectKind::Remove + } else if action.contains('D') { + EffectKind::Downgrade + } else if action.contains('U') { + EffectKind::Upgrade + } else if action.contains('N') { + EffectKind::New + } else if action.contains('R') { + EffectKind::Rebuild + } else { + EffectKind::Other + }; + (kind, source) +} + +/// Parse real `emerge --pretend` output into a resolved plan. +pub fn parse_emerge_pretend(text: &str) -> ResolvedPlan { + let mut plan = ResolvedPlan::default(); + for line in text.lines() { + let trimmed = line.trim_start(); + if !trimmed.starts_with('[') { + continue; + } + let Some(close) = trimmed.find(']') else { + continue; + }; + let bracket = &trimmed[1..close]; + let rest = trimmed[close + 1..].trim(); + if rest.is_empty() { + continue; + } + let (kind, source) = kind_and_source(bracket); + // For an upgrade, the new atom is the first token. The old version, if + // present, is in a following `[...]`. + let target = rest + .split_whitespace() + .next() + .unwrap_or("") + .trim_end_matches(',') + .to_string(); + if target.is_empty() { + continue; + } + let previous = rest + .find('[') + .and_then(|start| rest.find(']').map(|end| (start, end))) + .and_then(|(start, end)| { + let inner = rest[start + 1..end].trim(); + inner.split_whitespace().next().map(|s| s.to_string()) + }) + .filter(|_| matches!(kind, EffectKind::Upgrade | EffectKind::Downgrade)); + plan.effects.push(PackageEffect { + target, + previous, + kind, + source, + }); + } + plan.download_bytes = parse_download_bytes(text); + if plan.removals() > 0 { + plan.consequences + .push(format!("{} package(s) will be removed", plan.removals())); + } + if plan.source_builds() > 0 { + plan.consequences.push(format!( + "{} package(s) compile from source; this can take a long time", + plan.source_builds() + )); + } + if plan.downgrades() > 0 { + plan.consequences.push(format!( + "{} package(s) will be downgraded", + plan.downgrades() + )); + } + plan.recompute_digest(); + plan +} + +/// Whether two plans differ materially (anything but the digest itself). +pub fn changed_materially(approved: &ResolvedPlan, current: &ResolvedPlan) -> bool { + let mut a = approved.clone(); + let mut b = current.clone(); + a.digest.clear(); + b.digest.clear(); + a.recovery_point = None; + b.recovery_point = None; + a != b +} + +#[cfg(test)] +mod tests { + use super::*; + + const PRETEND: &str = "\ +These are the packages that would be merged, in order: + +Calculating dependencies... done! +[ebuild N ] app-editors/vim-9.1.0 USE=\"-python\" +[ebuild U ] dev-lang/python-3.12.6:3.12::gentoo [3.12.5:3.12::gentoo] +[binary N ] net-misc/wget-1.24.5 +[ebuild UD ] app-misc/foo-2.0 [1.0] +[uninstall ] app-misc/old-1.0 + +Total: 5 packages (2 upgrades, 2 new, 1 uninstall), Size of downloads: 10,240 KiB +"; + + #[test] + fn parses_effects_kinds_and_sources() { + let plan = parse_emerge_pretend(PRETEND); + assert_eq!(plan.effects.len(), 5); + assert_eq!(plan.additions(), 2); + assert_eq!(plan.upgrades(), 1); + assert_eq!(plan.downgrades(), 1); + assert_eq!(plan.removals(), 1); + assert_eq!(plan.binary_packages(), 1); + assert_eq!(plan.source_builds(), 3); + assert_eq!(plan.download_bytes, Some(10_240 * 1024)); + let python = plan + .effects + .iter() + .find(|e| e.target.starts_with("dev-lang/python")) + .unwrap(); + assert_eq!(python.kind, EffectKind::Upgrade); + assert_eq!(python.previous.as_deref(), Some("3.12.5:3.12::gentoo")); + let foo = plan + .effects + .iter() + .find(|e| e.target.starts_with("app-misc/foo")) + .unwrap(); + assert_eq!(foo.kind, EffectKind::Downgrade); + } + + #[test] + fn digest_is_stable_and_detects_material_change() { + let a = parse_emerge_pretend(PRETEND); + let b = parse_emerge_pretend(PRETEND); + assert_eq!(a.digest, b.digest); + assert!(!changed_materially(&a, &b)); + + let other = PRETEND.replace("app-misc/foo-2.0", "app-misc/foo-2.1"); + let c = parse_emerge_pretend(&other); + assert_ne!(a.digest, c.digest); + assert!(changed_materially(&a, &c)); + } + + #[test] + fn empty_output_is_a_no_change_plan() { + let plan = parse_emerge_pretend("Calculating dependencies... done!\n\nTotal: 0 packages\n"); + assert!(plan.effects.is_empty()); + assert_eq!(plan.additions(), 0); + assert!(plan.render().contains("no package changes")); + // The digest is still defined. + assert_eq!(plan.digest.len(), 64); + } + + #[test] + fn render_states_source_binary_and_consequences() { + let plan = parse_emerge_pretend(PRETEND); + let text = plan.render(); + assert!(text.contains("binary")); + assert!(text.contains("source")); + assert!(text.contains("will be removed")); + assert!(text.contains("download:")); + } +} diff --git a/installer-rs/crates/phoebus-core/src/lib.rs b/installer-rs/crates/phoebus-core/src/lib.rs index cb7817c..5abf82d 100644 --- a/installer-rs/crates/phoebus-core/src/lib.rs +++ b/installer-rs/crates/phoebus-core/src/lib.rs @@ -4,17 +4,21 @@ //! Nothing in this crate executes external commands or touches disks. pub mod action; +pub mod boot; pub mod config; pub mod disk; +pub mod effects; pub mod emergelog; pub mod error; pub mod hardware; pub mod plan; pub mod policy; +pub mod rollback; pub mod secret; pub mod snapshot; pub mod system; pub mod target; +pub mod transaction; pub mod update; pub mod validate; diff --git a/installer-rs/crates/phoebus-core/src/plan.rs b/installer-rs/crates/phoebus-core/src/plan.rs index cc63c12..d7d14e4 100644 --- a/installer-rs/crates/phoebus-core/src/plan.rs +++ b/installer-rs/crates/phoebus-core/src/plan.rs @@ -169,6 +169,11 @@ impl InstallPlan { config.packages.accept_license )); o.push_str(&format!(" Desktop : {}\n", config.desktop.profile)); + if config.desktop.profile == crate::config::DesktopProfile::Mango { + o.push_str( + " Session : Mango + DankMaterialShell (GURU overlay; dwl fallback)\n", + ); + } o.push_str(&format!( " Flatpak : {}\n", if config.desktop.flatpak { "yes" } else { "no" } diff --git a/installer-rs/crates/phoebus-core/src/rollback.rs b/installer-rs/crates/phoebus-core/src/rollback.rs new file mode 100644 index 0000000..6a78dca --- /dev/null +++ b/installer-rs/crates/phoebus-core/src/rollback.rs @@ -0,0 +1,403 @@ +//! Rollback and recovery model. +//! +//! Rollback is deliberately explicit about the pieces that must move together: +//! the root subvolume selection (kernel command line *and* fstab *and* the Btrfs +//! default), the separately mounted `@var` volume (package database, Portage +//! state, caches), and the kernel/initramfs pairing on the ESP. These are pure +//! types and planners; the privileged executor performs the commands. +//! +//! The reader must never assume that changing the Btrfs default subvolume +//! overrides the explicit `rootflags=subvol=...` in the kernel command line: the +//! explicit argument wins, so boot entries are rewritten as well. + +use serde::{Deserialize, Serialize}; + +use crate::snapshot::{compact_utc, SnapshotHistory, SnapshotRecord, SnapshotStatus}; + +/// Snapshot subvolumes kept by default before the oldest committed ones are +/// pruned. +pub const DEFAULT_KEEP_SNAPSHOTS: usize = 8; +/// Root generations (`@restore-*`) kept by default. +pub const DEFAULT_KEEP_ROOT_GENERATIONS: usize = 3; +/// Free space required before a rollback, on top of the snapshot's own usage. +pub const MIN_FREE_SPACE_BYTES: u64 = 1024 * 1024 * 1024; + +/// The lifecycle of a rollback. A rollback is only `Verified` after the system +/// has booted from the restored root and the package state checked out. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)] +#[serde(rename_all = "snake_case")] +pub enum RollbackStatus { + /// No rollback has been attempted. + #[default] + Idle, + /// Subvolumes were prepared; boot entries still point at the previous root + /// until activation completes. An interruption here is safe: the system + /// boots the previous root. + Planned, + /// Boot entries now select the restored root; awaiting the next boot. + Activated, + /// The system booted the restored root and the package state is consistent. + Verified, + /// A step failed. The system still boots a known root; re-running resumes. + Failed, +} + +impl RollbackStatus { + /// Whether a rollback is in flight and its target must be protected from + /// retention pruning. + pub fn in_flight(self) -> bool { + matches!(self, RollbackStatus::Planned | RollbackStatus::Activated) + } +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(default)] +pub struct RollbackState { + pub status: RollbackStatus, + /// Monotonic generation number, for human diagnostics and ordering. + pub generation: u64, + /// The snapshot id that was selected as the restore source. + pub target_snapshot: String, + /// The paired `@var` snapshot, when one was captured. + pub target_var_snapshot: Option, + /// The root subvolume that was active before the rollback. + pub previous_root: String, + /// The new root subvolume booted after the rollback. + pub root_subvol: String, + /// The paired new `/var` subvolume, when applicable. + pub var_subvol: Option, + /// The BLS entry file selected to boot the restored root. + pub boot_entry: Option, + pub started_unix: u64, + pub finished_unix: u64, + pub note: String, +} + +impl Default for RollbackState { + fn default() -> Self { + Self { + status: RollbackStatus::Idle, + generation: 0, + target_snapshot: String::new(), + target_var_snapshot: None, + previous_root: "@".into(), + root_subvol: "@".into(), + var_subvol: None, + boot_entry: None, + started_unix: 0, + finished_unix: 0, + note: String::new(), + } + } +} + +impl RollbackState { + /// The subvolume id/name that should be protected from pruning. + pub fn protected_subvols(&self) -> Vec { + let mut out = vec![self.root_subvol.clone()]; + if let Some(var) = &self.var_subvol { + out.push(var.clone()); + } + out + } +} + +/// A root generation created by a rollback (a writable clone of a snapshot). +pub fn restore_root_name(ts: u64) -> String { + format!("@restore-{}", compact_utc(ts)) +} + +/// The paired `/var` generation created by a rollback. +pub fn restore_var_name(ts: u64) -> String { + format!("@varrestore-{}", compact_utc(ts)) +} + +/// A safety snapshot of the current root, taken before a rollback overwrites +/// the boot selection. +pub fn pre_rollback_snapshot_name(ts: u64) -> String { + format!("@-{}-pre-rollback", compact_utc(ts)) +} + +/// A safety snapshot of the current `/var`. +pub fn pre_rollback_var_snapshot_name(ts: u64) -> String { + format!("@var-{}-pre-rollback", compact_utc(ts)) +} + +/// The subvolume path of a snapshot record relative to the Btrfs top level +/// (subvolid 5): snapshots live under the `@snapshots` subvolume. +pub fn snapshot_top_level_path(name: &str) -> String { + format!("@snapshots/{name}") +} + +/// The device backing the running root, from `/proc/self/mounts` text +/// (`source mountpoint fstype options dump pass`). +pub fn root_device_from_mounts(text: &str) -> Option { + for line in text.lines() { + let fields: Vec<&str> = line.split_whitespace().collect(); + if fields.len() >= 3 && fields[1] == "/" { + return Some(fields[0].to_string()); + } + } + None +} + +/// The ESP mount point (a vfat filesystem, conventionally `/efi`), from +/// `/proc/self/mounts` text. +pub fn esp_mount_from_mounts(text: &str) -> Option { + for line in text.lines() { + let fields: Vec<&str> = line.split_whitespace().collect(); + if fields.len() >= 3 && fields[2] == "vfat" && fields[1] != "/" { + return Some(fields[1].to_string()); + } + } + None +} + +/// Rewrite the `subvol=` component of the fstab line for `mountpoint`, +/// preserving every other field and option. Returns the text unchanged when no +/// matching line exists so the caller can detect the miss separately. +pub fn rewrite_fstab_subvol(text: &str, mountpoint: &str, new_subvol: &str) -> String { + let mut out = String::new(); + for line in text.lines() { + let trimmed = line.trim_start(); + if trimmed.starts_with('#') || trimmed.is_empty() { + out.push_str(line); + out.push('\n'); + continue; + } + let fields: Vec<&str> = line.split_whitespace().collect(); + if fields.len() >= 4 && fields[1] == mountpoint { + let opts = fields[3]; + let mut parts: Vec = Vec::new(); + let mut replaced = false; + for part in opts.split(',') { + if part.starts_with("subvol=") { + parts.push(format!("subvol={new_subvol}")); + replaced = true; + } else if !part.is_empty() { + parts.push(part.to_string()); + } + } + if !replaced { + parts.push(format!("subvol={new_subvol}")); + } + let new_opts = parts.join(","); + let mut rebuilt = line.to_string(); + if let Some(pos) = line.find(opts) { + rebuilt.replace_range(pos..pos + opts.len(), &new_opts); + } + out.push_str(&rebuilt); + out.push('\n'); + } else { + out.push_str(line); + out.push('\n'); + } + } + out +} + +/// Whether an fstab line exists for `mountpoint`. +pub fn fstab_has_mountpoint(text: &str, mountpoint: &str) -> bool { + text.lines().any(|line| { + let trimmed = line.trim_start(); + !trimmed.starts_with('#') + && line + .split_whitespace() + .nth(1) + .map(|m| m == mountpoint) + .unwrap_or(false) + }) +} + +/// The newest committed snapshot, skipping records without a real subvolume. +pub fn latest_committed(history: &SnapshotHistory) -> Option<&SnapshotRecord> { + history + .records + .iter() + .rev() + .find(|r| r.status == SnapshotStatus::Committed && !r.snapshot_subvol.is_empty()) +} + +/// Whether the history contains the given id as a committed snapshot. +pub fn is_committed(history: &SnapshotHistory, id: &str) -> bool { + history + .records + .iter() + .any(|r| r.id == id && r.status == SnapshotStatus::Committed) +} + +/// Generic newest-first retention: return the items to delete, keeping the +/// newest `keep`, never deleting anything in `protect`. +/// +/// Input order is oldest-first (the order the history is appended in). +pub fn retention_deletions(items: &[String], keep: usize, protect: &[String]) -> Vec { + if items.len() <= keep { + return Vec::new(); + } + let cutoff = items.len() - keep; + items + .iter() + .take(cutoff) + .filter(|id| !protect.iter().any(|p| p == *id)) + .cloned() + .collect() +} + +/// Prune the snapshot history to at most `keep` committed snapshots. +/// +/// Records that are still in flight (`Created`) or `Failed` are never selected, +/// and the newest committed snapshot is always retained so a recovery point +/// survives. +pub fn snapshot_retention_deletions( + history: &SnapshotHistory, + keep: usize, + protect: &[String], +) -> Vec { + let mut committed: Vec = history + .records + .iter() + .filter(|r| r.status == SnapshotStatus::Committed) + .map(|r| r.id.clone()) + .collect(); + committed.dedup(); + if committed.is_empty() { + return Vec::new(); + } + let newest = committed.last().cloned(); + let mut protect = protect.to_vec(); + if let Some(n) = newest { + if !protect.contains(&n) { + protect.push(n); + } + } + retention_deletions(&committed, keep, &protect) +} + +#[cfg(test)] +mod tests { + use super::*; + + fn record(id: &str, status: SnapshotStatus) -> SnapshotRecord { + SnapshotRecord { + id: id.into(), + created_unix: 0, + operation: "op".into(), + source_subvol: "@".into(), + snapshot_subvol: id.into(), + var_snapshot: None, + status, + } + } + + #[test] + fn names_are_deterministic_and_safe() { + let ts = 1_700_000_000; + assert_eq!(restore_root_name(ts), "@restore-20231114T221320"); + assert_eq!(restore_var_name(ts), "@varrestore-20231114T221320"); + assert_eq!( + pre_rollback_snapshot_name(ts), + "@-20231114T221320-pre-rollback" + ); + assert_eq!(snapshot_top_level_path("@-x"), "@snapshots/@-x"); + for name in [restore_root_name(ts), restore_var_name(ts)] { + assert!(!name.contains('/')); + assert!(!name.contains(char::is_whitespace)); + } + } + + #[test] + fn retention_keeps_the_newest_and_protects_in_flight() { + let items: Vec = (0..5).map(|i| format!("s{i}")).collect(); + let deletions = retention_deletions(&items, 2, &["s2".to_string()]); + assert_eq!(deletions, vec!["s0", "s1"]); + // Nothing to delete when under the limit. + assert!(retention_deletions(&items, 9, &[]).is_empty()); + } + + #[test] + fn retention_never_deletes_the_newest_committed() { + let history = SnapshotHistory { + records: vec![ + record("a", SnapshotStatus::Committed), + record("b", SnapshotStatus::Committed), + record("c", SnapshotStatus::Committed), + ], + }; + let deletions = snapshot_retention_deletions(&history, 0, &[]); + // `c` is the newest and is always kept. + assert_eq!(deletions, vec!["a", "b"]); + assert!(!deletions.contains(&"c".to_string())); + } + + #[test] + fn retention_skips_in_flight_and_failed_records() { + let history = SnapshotHistory { + records: vec![ + record("a", SnapshotStatus::Committed), + record("b", SnapshotStatus::Created), + record("c", SnapshotStatus::Failed), + record("d", SnapshotStatus::Committed), + ], + }; + let deletions = snapshot_retention_deletions(&history, 1, &[]); + assert_eq!(deletions, vec!["a"]); + } + + #[test] + fn status_in_flight_is_planned_or_activated() { + assert!(RollbackStatus::Planned.in_flight()); + assert!(RollbackStatus::Activated.in_flight()); + assert!(!RollbackStatus::Verified.in_flight()); + assert!(!RollbackStatus::Idle.in_flight()); + } + + #[test] + fn latest_committed_prefers_the_last_record() { + let history = SnapshotHistory { + records: vec![ + record("a", SnapshotStatus::Committed), + record("b", SnapshotStatus::Failed), + record("c", SnapshotStatus::Committed), + ], + }; + assert_eq!(latest_committed(&history).unwrap().id, "c"); + assert!(is_committed(&history, "a")); + assert!(!is_committed(&history, "b")); + } + + #[test] + fn mount_parsers_find_root_device_and_esp() { + let mounts = "/dev/mapper/cryptroot / btrfs rw,subvol=/\t0 0\n\ + /dev/vda1 /efi vfat umask=0077\t0 0\n\ + proc /proc proc rw\t0 0\n"; + assert_eq!( + root_device_from_mounts(mounts).as_deref(), + Some("/dev/mapper/cryptroot") + ); + assert_eq!(esp_mount_from_mounts(mounts).as_deref(), Some("/efi")); + assert!(root_device_from_mounts("").is_none()); + assert!(esp_mount_from_mounts("proc /proc proc rw 0 0").is_none()); + } + + #[test] + fn fstab_subvol_rewrite_only_touches_the_requested_mountpoint() { + let fstab = "\ +# /etc/fstab +UUID=AAAA-1111\t/efi\tvfat\tumask=0077,shortname=winnt\t0\t2 +/dev/mapper/cryptroot\t/\tbtrfs\tnoatime,compress=zstd:3,subvol=@\t0\t1 +/dev/mapper/cryptroot\t/home\tbtrfs\tnoatime,compress=zstd:3,subvol=@home\t0\t2 +/dev/mapper/cryptroot\t/var\tbtrfs\tnoatime,compress=zstd:3,subvol=@var\t0\t2 +/swap/swapfile\tnone\tswap\tdefaults\t0\t0 +"; + let out = rewrite_fstab_subvol(fstab, "/", "@restore-20260101T000000"); + assert!(out.contains("subvol=@restore-20260101T000000\t0\t1")); + // /var is untouched here; it is rewritten separately. + assert!(out.contains("\t/var\tbtrfs\tnoatime,compress=zstd:3,subvol=@var\t0\t2")); + assert!(out.contains("subvol=@home")); + let var = rewrite_fstab_subvol(&out, "/var", "@varrestore-20260101T000000"); + assert!(var.contains("subvol=@varrestore-20260101T000000\t0\t2")); + assert!(fstab_has_mountpoint(&var, "/")); + assert!(fstab_has_mountpoint(&var, "/var")); + assert!(!fstab_has_mountpoint(&var, "/nonexistent")); + } +} diff --git a/installer-rs/crates/phoebus-core/src/snapshot.rs b/installer-rs/crates/phoebus-core/src/snapshot.rs index a4f40b2..c93603c 100644 --- a/installer-rs/crates/phoebus-core/src/snapshot.rs +++ b/installer-rs/crates/phoebus-core/src/snapshot.rs @@ -27,6 +27,12 @@ pub struct SnapshotRecord { pub operation: String, pub source_subvol: String, pub snapshot_subvol: String, + /// The paired `@var` snapshot. `/var` is a separate subvolume holding the + /// package database and Portage state, so it is captured with the root and + /// restored with it; otherwise a restored root would see inconsistent + /// package state. + #[serde(default)] + pub var_snapshot: Option, pub status: SnapshotStatus, } @@ -130,6 +136,7 @@ mod tests { operation: "sys update".into(), source_subvol: "@".into(), snapshot_subvol: "@-20231114T221320-sys-update".into(), + var_snapshot: None, status: SnapshotStatus::Committed, }); history.save(&path).unwrap(); diff --git a/installer-rs/crates/phoebus-core/src/system.rs b/installer-rs/crates/phoebus-core/src/system.rs index a6c6713..6012167 100644 --- a/installer-rs/crates/phoebus-core/src/system.rs +++ b/installer-rs/crates/phoebus-core/src/system.rs @@ -41,41 +41,70 @@ pub fn desktop_packages(profile: DesktopProfile) -> Vec<&'static str> { "gui-libs/wayland-protocols", "x11-base/xwayland", ], - DesktopProfile::Dwl | DesktopProfile::Full => vec![ - "gui-wm/dwl", - "gui-apps/waybar", - "gui-apps/wofi", - "gui-apps/mako", - "gui-apps/swayidle", - "gui-apps/swaylock", - "gui-apps/swaybg", - "gui-apps/wl-clipboard", - "gui-apps/grim", - "gui-apps/slurp", - "gui-libs/gtk-layer-shell", - "x11-base/xwayland", - "x11-terms/kitty", - "net-misc/networkmanager", - "sys-auth/polkit", - "gnome-extra/polkit-gnome", - // Desktop portals: required by Flatpak (file chooser, screencast, - // screenshots) and expected by many Wayland apps. - "sys-apps/xdg-desktop-portal", - "sys-apps/xdg-desktop-portal-gtk", - "gui-libs/xdg-desktop-portal-wlr", - ], + DesktopProfile::Dwl => dwl_desktop_packages(), + // Mango + DankMaterialShell ships the dwl session as a fallback, so the + // user always has a second compositor if the new session misbehaves. + DesktopProfile::Mango => mango_desktop_packages(), + DesktopProfile::Full => { + let mut out = dwl_desktop_packages(); + out.extend([ + "sys-apps/flatpak", + "net-wireless/bluez", + "gnome-base/gnome-keyring", + ]); + out + } } - .into_iter() - .chain(if profile == DesktopProfile::Full { - vec![ - "sys-apps/flatpak", - "net-wireless/bluez", - "gnome-base/gnome-keyring", - ] - } else { - vec![] - }) - .collect() +} + +/// The proven dwl session (also the fallback for the Mango profile). +pub fn dwl_desktop_packages() -> Vec<&'static str> { + vec![ + "gui-wm/dwl", + "gui-apps/waybar", + "gui-apps/wofi", + "gui-apps/mako", + "gui-apps/swayidle", + "gui-apps/swaylock", + "gui-apps/swaybg", + "gui-apps/wl-clipboard", + "gui-apps/grim", + "gui-apps/slurp", + "gui-libs/gtk-layer-shell", + "x11-base/xwayland", + "x11-terms/kitty", + "net-misc/networkmanager", + "sys-auth/polkit", + "gnome-extra/polkit-gnome", + // Desktop portals: required by Flatpak (file chooser, screencast, + // screenshots) and expected by many Wayland apps. + "sys-apps/xdg-desktop-portal", + "sys-apps/xdg-desktop-portal-gtk", + "gui-libs/xdg-desktop-portal-wlr", + ] +} + +/// Mango + DankMaterialShell, plus a minimal terminal/file-manager set. +/// +/// The shell (panel, launcher, notifications, lock, idle, audio/network/ +/// Bluetooth controls and displays) is `gui-apps/dankmaterialshell`, which +/// depends on `gui-apps/quickshell`. Both are shipped through the GURU overlay; +/// `dev-vcs/git` is required to sync that git-only overlay. `gui-wm/mangowm` +/// uses the wlroots 0.20 slot, so it coexists with dwl (wlroots 0.18). +pub fn mango_desktop_packages() -> Vec<&'static str> { + let mut out = dwl_desktop_packages(); + out.extend([ + "gui-wm/mangowm", + "gui-apps/dankmaterialshell", + "gui-apps/danksearch", + "dev-vcs/git", + "sys-apps/accountsservice", + "sys-power/upower", + "kde-frameworks/kimageformats", + "x11-misc/pcmanfm", + "net-wireless/bluez", + ]); + out } pub fn desktop_audio_packages() -> Vec<&'static str> { @@ -88,7 +117,7 @@ pub fn network_target_services() -> Vec<&'static str> { pub fn desktop_services(profile: DesktopProfile) -> Vec<&'static str> { let mut out = vec!["NetworkManager", "systemd-resolved"]; - if profile == DesktopProfile::Full { + if matches!(profile, DesktopProfile::Full | DesktopProfile::Mango) { out.push("bluetooth"); } out @@ -209,6 +238,46 @@ pub fn repos_conf() -> String { o } +/// The GURU community overlay, which packages Mango and DankMaterialShell. +/// +/// GURU is git-only (no rsync), so `dev-vcs/git` must be installed before it +/// can be synced. It is a reviewed, signed-over-git community overlay; the +/// installer scopes `~amd64` to the specific packages rather than unmasking it. +pub const GURU_REPO_URI: &str = "https://anongit.gentoo.org/git/proj/guru.git"; + +pub fn guru_repos_conf() -> String { + let mut o = String::new(); + o.push_str("[guru]\n"); + o.push_str("location = /var/db/repos/guru\n"); + o.push_str("sync-type = git\n"); + o.push_str(&format!("sync-uri = {GURU_REPO_URI}\n")); + o.push_str("auto-sync = yes\n"); + o +} + +/// Whether the selected desktop needs the GURU overlay. +pub fn uses_guru(config: &InstallConfig) -> bool { + config.desktop.profile == DesktopProfile::Mango +} + +/// The reviewed `~amd64` keyword set for the Mango + DankMaterialShell stack. +/// +/// These are the GURU packages and the GURU-only dependency (`scenefx`). The +/// comment is explicit that this is scoped, not a global `~amd64` switch, and +/// that Portage must not silently unmask further packages: an operator reviews +/// `emerge --pretend` output and extends the file deliberately. +pub fn accept_keywords_mango() -> String { + let mut o = String::new(); + o.push_str("# Mango + DankMaterialShell: reviewed, scoped testing keywords.\n"); + o.push_str("# This is NOT a global ~amd64 switch. GURU ships these as ~amd64.\n"); + o.push_str("gui-wm/mangowm\n"); + o.push_str("gui-apps/dankmaterialshell\n"); + o.push_str("gui-apps/danksearch\n"); + o.push_str("gui-apps/quickshell\n"); + o.push_str("gui-libs/scenefx\n"); + o +} + pub const BINHOST_OPENRC: &str = "https://distfiles.gentoo.org/releases/amd64/binpackages/23.0/x86-64"; pub const BINHOST_HARDENED: &str = @@ -499,10 +568,339 @@ else echo "phoebus-session: polkit agent not found; graphical authentication may fail" >&2 fi +# Idle handling and screen locking (swayidle + swaylock). Locking before sleep +# means resuming never reveals the desktop. +if command -v phoebus-idle >/dev/null 2>&1; then + start_helper phoebus-idle +fi + # Run until the compositor exits, then the EXIT trap stops the helpers. wait "$DWL_PID" "#; +/// The `phoebus-menu` launcher / power menu (wofi). +pub const PHOEBUS_MENU_SCRIPT: &str = r#"#!/bin/bash +# Phoebus application launcher and power menu. +# phoebus-menu application launcher (wofi drun) +# phoebus-menu --power lock / suspend / log out / reboot / shut down +set -u +if [ "${1:-}" = "--power" ]; then + choice="$(printf '%s\n' 'Lock' 'Suspend' 'Log out' 'Reboot' 'Shut down' \ + | wofi --dmenu --prompt 'Power')" + case "$choice" in + Lock) exec phoebus-lock ;; + Suspend) exec systemctl suspend ;; + 'Log out') exec pkill -TERM dwl ;; + Reboot) exec systemctl reboot ;; + 'Shut down') exec systemctl poweroff ;; + esac +fi +exec wofi --show drun --prompt Applications +"#; + +/// Screen locker. +pub const PHOEBUS_LOCK_SCRIPT: &str = r#"#!/bin/bash +# Lock the session. `-f` fails closed if the lock cannot be established. +set -u +exec swaylock -f -c 1e1e2e +"#; + +/// Idle daemon: lock, then suspend, and always lock before sleeping. +pub const PHOEBUS_IDLE_SCRIPT: &str = r#"#!/bin/bash +# Idle handling: dim/lock after inactivity and lock before suspend. +set -u +exec swayidle -w \ + timeout 300 'phoebus-lock' \ + timeout 600 'systemctl suspend' \ + before-sleep 'phoebus-lock' +"#; + +/// System-wide Waybar configuration (network, audio, battery, clock, power). +pub const WAYBAR_CONFIG: &str = r#"{ + "layer": "top", + "position": "top", + "height": 30, + "modules-left": ["sway/workspaces", "sway/mode"], + "modules-center": ["sway/window"], + "modules-right": ["wireplumber", "network", "battery", "clock", "tray", "custom/power"], + "wireplumber": { + "format": "{icon} {volume}%", + "format-muted": "muted", + "on-click": "pavucontrol-qt || pavucontrol" + }, + "network": { + "format-wifi": "wifi {essid}", + "format-ethernet": "ethernet", + "format-disconnected": "offline", + "on-click": "nm-connection-editor || nmtui" + }, + "battery": { + "format": "bat {capacity}%", + "format-charging": "chg {capacity}%" + }, + "clock": { + "format": "{:%a %H:%M}", + "tooltip-format": "{:%Y-%m-%d %H:%M}" + }, + "custom/power": { + "format": "power", + "on-click": "phoebus-menu --power", + "tooltip": "Lock, suspend, log out, reboot" + } +} +"#; + +/// System-wide Waybar styling. +pub const WAYBAR_STYLE: &str = r#"* { + font-family: monospace; + font-size: 13px; +} +window#waybar { + background: #1e1e2e; + color: #cdd6f4; +} +#workspaces button.focused, +#custom-power:hover { + background: #89b4fa; + color: #1e1e2e; +} +"#; + +// --------------------------------------------------------------------------- +// Mango + DankMaterialShell +// --------------------------------------------------------------------------- + +/// The Mango session entry point written to `/usr/local/bin/phoebus-session-mango`. +/// +/// It starts exactly one compositor (mango), one shell, notification, lock and +/// idle implementation (all provided by DankMaterialShell), and one polkit +/// agent (Quickshell's, enabled by the shell's `policykit` feature). It does +/// **not** start the dwl helpers (waybar/mako/swaybg/swayidle/swaylock), so the +/// two sessions never compete. It seeds user configuration from the packaged +/// defaults only when absent, so upgrades never overwrite customization. +pub const PHOEBUS_MANGO_SESSION_SCRIPT: &str = r#"#!/bin/bash +# Phoebus Mango + DankMaterialShell session (generated by the installer). +# +# Hotkeys (also shown in the DMS shortcut overlay): +# Mod+Space launcher (DMS spotlight) Mod+Return terminal +# Mod+V clipboard history Mod+N notifications +# Mod+Comma settings Mod+M task manager +# Mod+a Phoebus assistant Mod+Alt+L lock +# Mod+Shift+q close window Mod+Shift+e exit session + +set -u + +if [ -z "${XDG_RUNTIME_DIR:-}" ]; then + export XDG_RUNTIME_DIR="/run/user/$(id -u)" +fi +if [ ! -d "$XDG_RUNTIME_DIR" ]; then + echo "phoebus-session-mango: XDG_RUNTIME_DIR $XDG_RUNTIME_DIR is missing" >&2 + exit 1 +fi + +# Deterministic socket name so the environment exported to the systemd user +# manager matches the compositor. +export WAYLAND_DISPLAY="${WAYLAND_DISPLAY:-wayland-0}" +export XDG_SESSION_TYPE=wayland +export XDG_CURRENT_DESKTOP=mango +export XDG_SESSION_DESKTOP=mango +export MOZ_ENABLE_WAYLAND=1 +export QT_QPA_PLATFORM=wayland +export QT_QPA_PLATFORMTHEME=gtk3 +export QT_QPA_PLATFORMTHEME_QT6=gtk3 +export GDK_BACKEND=wayland,x11 +export ELECTRON_OZONE_PLATFORM_HINT=auto +export _JAVA_AWT_WM_NONREPARENTING=1 + +if [ -z "${DBUS_SESSION_BUS_ADDRESS:-}" ] && command -v dbus-run-session >/dev/null 2>&1; then + exec dbus-run-session -- "$0" "$@" +fi + +# Seed user configuration from the packaged defaults exactly once; never +# overwrite what the user has customized. +mango_conf="$HOME/.config/mango/config.conf" +mkdir -p "$HOME/.config/mango/dms" +if [ ! -e "$mango_conf" ] && [ -r /etc/xdg/mango/config.conf ]; then + cp /etc/xdg/mango/config.conf "$mango_conf" +fi +# DMS manages these fragments; they must exist before Mango sources them. +for f in colors layout outputs; do + [ -e "$HOME/.config/mango/dms/$f.conf" ] || : > "$HOME/.config/mango/dms/$f.conf" +done + +socket="${XDG_RUNTIME_DIR}/${WAYLAND_DISPLAY}" +HELPERS="" + +start_helper() { + "$@" >/dev/null 2>&1 & + HELPERS="$HELPERS $!" +} + +cleanup() { + trap - EXIT INT TERM + for pid in $HELPERS; do + kill "$pid" 2>/dev/null || true + done + if command -v systemctl >/dev/null 2>&1; then + systemctl --user stop mango-session.target >/dev/null 2>&1 || true + fi +} + +trap cleanup EXIT INT TERM + +mango & +MANGO_PID=$! + +waited=0 +while [ ! -S "$socket" ]; do + if ! kill -0 "$MANGO_PID" 2>/dev/null; then + echo "phoebus-session-mango: mango exited before creating $socket" >&2 + exit 1 + fi + if [ "$waited" -ge 100 ]; then + echo "phoebus-session-mango: timed out waiting for $socket" >&2 + kill "$MANGO_PID" 2>/dev/null || true + exit 1 + fi + sleep 0.1 + waited=$((waited + 1)) +done + +# Export the graphical environment to the systemd user manager so user +# services (dms.service, portals) can reach the compositor. +if command -v dbus-update-activation-environment >/dev/null 2>&1; then + dbus-update-activation-environment --systemd \ + WAYLAND_DISPLAY XDG_CURRENT_DESKTOP XDG_SESSION_TYPE XDG_RUNTIME_DIR \ + QT_QPA_PLATFORM >/dev/null 2>&1 || true +fi + +# Exactly one shell: DMS, bound to mango-session.target. Fall back to a direct +# `dms run` only when the user manager is unavailable. +if command -v systemctl >/dev/null 2>&1 \ + && systemctl --user start mango-session.target >/dev/null 2>&1; then + : +elif command -v dms >/dev/null 2>&1; then + start_helper dms run +else + echo "phoebus-session-mango: dms not found; the shell will not start" >&2 +fi + +# Run until the compositor exits; the EXIT trap stops the shell and helpers. +wait "$MANGO_PID" +"#; + +/// Packaged default Mango configuration. DMS writes its managed fragments under +/// `~/.config/mango/dms/`; this file only provides a sane baseline and the +/// DMS keybindings. It is copied to the user's config on first session start. +pub const MANGO_CONFIG_DEFAULT: &str = r#"# Phoebus default Mango configuration (packaged; copied once, then user-owned). +# DMS manages colors/layout/outputs in ~/.config/mango/dms/*.conf. +source=~/.config/mango/dms/colors.conf +source=~/.config/mango/dms/layout.conf +source=~/.config/mango/dms/outputs.conf + +env=QT_QPA_PLATFORM,wayland +env=ELECTRON_OZONE_PLATFORM_HINT,auto +env=QT_QPA_PLATFORMTHEME,gtk3 + +border_radius=12 +borderpx=0 +focused_opacity=1.0 +unfocused_opacity=0.9 +gappih=5 +gappiv=5 +gappoh=5 +gappov=5 +shadows=1 +shadow_only_floating=1 +shadows_size=10 +shadows_blur=15 + +layerrule=noanim:1,layer_name:^dms +windowrule=isfloating:1,appid:^com.danklinux.dms$ + +# Application launchers and DMS panels +bind=SUPER,space,spawn,dms ipc call spotlight toggle +bind=SUPER,v,spawn,dms ipc call clipboard toggle +bind=SUPER,m,spawn,dms ipc call processlist focusOrToggle +bind=SUPER,comma,spawn,dms ipc call settings focusOrToggle +bind=SUPER,n,spawn,dms ipc call notifications toggle +bind=SUPER,Return,spawn,kitty +bind=SUPER,a,spawn,phoebus-assistant + +# Security +bind=SUPER+ALT,l,spawn,dms ipc call lock lock + +# Audio +bind=NONE,XF86AudioRaiseVolume,spawn,dms ipc call audio increment 3 +bind=NONE,XF86AudioLowerVolume,spawn,dms ipc call audio decrement 3 +bind=NONE,XF86AudioMute,spawn,dms ipc call audio mute + +# Brightness +bind=NONE,XF86MonBrightnessUp,spawn,dms ipc call brightness increment 5 +bind=NONE,XF86MonBrightnessDown,spawn,dms ipc call brightness decrement 5 + +# Session +bind=SUPER+SHIFT,q,killclient, +bind=SUPER+SHIFT,e,quit, +"#; + +/// The systemd user target the DMS service is bound to. Using a target means +/// the shell starts and stops with the Mango session and does not run under +/// another desktop. +pub const MANGO_SESSION_TARGET: &str = r#"# Phoebus Mango session target (generated by the installer). +[Unit] +Description=Phoebus Mango + DankMaterialShell session +Requires=graphical-session.target +After=graphical-session.target +"#; + +/// The `phoebus-assistant` launcher: opens a terminal for `sys ask`, which +/// proposes typed actions and requires explicit approval. It never grants the +/// model privilege. +pub const PHOEBUS_ASSISTANT_SCRIPT: &str = r#"#!/bin/bash +# Open the Phoebus assistant in a terminal. `sys ask` uses the same typed-action +# broker and approval boundary as the rest of the system. +set -u +if command -v kitty >/dev/null 2>&1; then + exec kitty --title "Phoebus Assistant" -e bash -lc \ + 'read -rp "Phoebus assistant request: " r; sudo sys ask "$r"; \ + echo; read -rp "Press Enter to close"' +fi +echo "phoebus-assistant: kitty is required for the assistant launcher" >&2 +exit 1 +"#; + +/// A Wayland session entry for `/usr/share/wayland-sessions`. +pub fn wayland_session_entry(profile: DesktopProfile) -> Option<(&'static str, String)> { + match profile { + DesktopProfile::Mango => Some(( + "phoebus-mango.desktop", + "# Phoebus Mango session (generated by the installer).\n\ + [Desktop Entry]\n\ + Name=Phoebus (Mango)\n\ + Comment=Mango compositor with DankMaterialShell\n\ + Exec=/usr/local/bin/phoebus-session-mango\n\ + TryExec=/usr/local/bin/phoebus-session-mango\n\ + Type=Application\n\ + DesktopNames=mango\n" + .to_string(), + )), + DesktopProfile::Dwl | DesktopProfile::Full => Some(( + "phoebus-dwl.desktop", + "# Phoebus dwl session (generated by the installer).\n\ + [Desktop Entry]\n\ + Name=Phoebus (dwl)\n\ + Comment=Lightweight dwl Wayland session\n\ + Exec=/usr/local/bin/phoebus-session\n\ + TryExec=/usr/local/bin/phoebus-session\n\ + Type=Application\n\ + DesktopNames=phoebus\n" + .to_string(), + )), + _ => None, + } +} + /// Btrfs mount options, matching the proven behavior. pub fn btrfs_mount_opts(compress: &str, ssd: bool) -> String { let mut opts = format!("noatime,compress={compress},space_cache=v2"); @@ -521,6 +919,27 @@ pub fn fstab( root_source: &str, efi_uuid: Option<&str>, btrfs_opts: &str, +) -> String { + fstab_with_subvols( + config, + root_source, + efi_uuid, + btrfs_opts, + &config.storage.root_subvolume(), + "@var", + ) +} + +/// As `fstab`, but for an explicit root and `/var` subvolume. A rollback +/// rewrites the restored root's fstab so it mounts its own generation rather +/// than the name the snapshot happened to be captured under. +pub fn fstab_with_subvols( + config: &InstallConfig, + root_source: &str, + efi_uuid: Option<&str>, + btrfs_opts: &str, + root_subvol: &str, + var_subvol: &str, ) -> String { let mut o = String::new(); o.push_str(&format!("# /etc/fstab: {}\n", config.system.distro_name)); @@ -533,9 +952,9 @@ pub fn fstab( )); } for (subvol, mountpoint, pass) in [ - ("@", "/", 1), + (root_subvol, "/", 1), ("@home", "/home", 2), - ("@var", "/var", 2), + (var_subvol, "/var", 2), ("@snapshots", "/.snapshots", 2), ("@swap", "/swap", 2), ] { @@ -563,6 +982,23 @@ pub fn kernel_cmdline( config: &InstallConfig, luks_uuid: Option<&str>, root_source: &str, +) -> Result { + kernel_cmdline_with_root( + config, + luks_uuid, + root_source, + &config.storage.root_subvolume(), + ) +} + +/// As `kernel_cmdline`, but selecting an explicit root subvolume. The explicit +/// `rootflags=subvol=` always wins over the Btrfs default subvolume, so a +/// rollback must rewrite it here as well as in the boot loader entry. +pub fn kernel_cmdline_with_root( + config: &InstallConfig, + luks_uuid: Option<&str>, + root_source: &str, + root_subvol: &str, ) -> Result { let mut cmdline = String::new(); if config.is_encrypted() { @@ -578,7 +1014,9 @@ pub fn kernel_cmdline( } cmdline.push_str(&format!("root={root_source} ")); } - cmdline.push_str("rootfstype=btrfs rootflags=subvol=@ rw quiet"); + cmdline.push_str(&format!( + "rootfstype=btrfs rootflags=subvol={root_subvol} rw quiet" + )); if !config.kernel.console.is_empty() { cmdline.push(' '); cmdline.push_str(&config.kernel.console); @@ -792,6 +1230,36 @@ mod tests { assert!(script.contains("trap cleanup EXIT INT TERM")); assert!(script.contains("wait \"$DWL_PID\"")); assert!(!script.contains("exec dwl")); + // Idle handling starts with the session. + assert!(script.contains("start_helper phoebus-idle")); + } + + #[test] + fn desktop_helpers_cover_launch_lock_idle_and_power() { + let menu = PHOEBUS_MENU_SCRIPT; + assert!(menu.contains("wofi --show drun")); + for action in ["Lock", "Suspend", "Log out", "Reboot", "Shut down"] { + assert!(menu.contains(action), "power menu missing {action}"); + } + assert!(menu.contains("systemctl suspend")); + assert!(menu.contains("systemctl reboot")); + assert!(menu.contains("systemctl poweroff")); + assert!(menu.contains("pkill -TERM dwl")); + + assert!(PHOEBUS_LOCK_SCRIPT.contains("swaylock -f")); + assert!(PHOEBUS_IDLE_SCRIPT.contains("swayidle")); + assert!(PHOEBUS_IDLE_SCRIPT.contains("before-sleep 'phoebus-lock'")); + assert!(PHOEBUS_IDLE_SCRIPT.contains("systemctl suspend")); + + // Network and audio controls are present and actionable. + let waybar = WAYBAR_CONFIG; + assert!(waybar.contains("\"wireplumber\"")); + assert!(waybar.contains("\"network\"")); + assert!(waybar.contains("nm-connection-editor")); + assert!(waybar.contains("custom/power")); + assert!(waybar.contains("phoebus-menu --power")); + assert!(waybar.contains("battery")); + assert!(waybar.contains("clock")); } #[test] @@ -800,4 +1268,78 @@ mod tests { assert_eq!(cfg.encryption.mode, Encryption::Luks2); assert!(kernel_cmdline(&cfg, None, "").is_err()); } + + #[test] + fn mango_profile_selects_guru_stack_and_keeps_dwl_fallback() { + let pkgs = desktop_packages(DesktopProfile::Mango); + assert!(pkgs.contains(&"gui-wm/mangowm")); + assert!(pkgs.contains(&"gui-apps/dankmaterialshell")); + assert!(pkgs.contains(&"gui-apps/danksearch")); + assert!(pkgs.contains(&"dev-vcs/git")); + // The dwl compositor and helpers remain as a fallback. + assert!(pkgs.contains(&"gui-wm/dwl")); + assert!(pkgs.contains(&"gui-apps/waybar")); + // Portals and the shared Wayland stack are present. + assert!(pkgs.contains(&"sys-apps/xdg-desktop-portal-gtk")); + assert!(pkgs.contains(&"gui-libs/xdg-desktop-portal-wlr")); + // An explicit Mango profile selects the desktop/systemd Gentoo profile. + let mut cfg = InstallConfig::default(); + cfg.desktop.profile = DesktopProfile::Mango; + assert_eq!(selected_profile(&cfg), PROFILE_SYSTEMD_DESKTOP); + assert!(uses_guru(&cfg)); + assert!(target_services(&cfg).contains(&"bluetooth".to_string())); + } + + #[test] + fn mango_keywords_are_scoped_not_global() { + let text = accept_keywords_mango(); + for atom in [ + "gui-wm/mangowm", + "gui-apps/dankmaterialshell", + "gui-apps/quickshell", + "gui-libs/scenefx", + ] { + assert!(text.contains(atom), "missing {atom}"); + } + assert!(!text.contains("*/*")); + // No bare global keyword line; `~amd64` may only appear in comments. + assert!(!text.lines().any(|l| l.trim() == "~amd64")); + assert!(!text.contains("ACCEPT_KEYWORDS")); + let repos = guru_repos_conf(); + assert!(repos.contains("[guru]")); + assert!(repos.contains("sync-type = git")); + assert!(repos.contains("anongit.gentoo.org")); + } + + #[test] + fn mango_session_contract() { + let script = PHOEBUS_MANGO_SESSION_SCRIPT; + // Exactly one compositor and one shell. + assert!(script.contains("mango &")); + assert!(script.contains("dms run")); + assert!(script.contains("mango-session.target")); + // The dwl helpers must never start in the Mango session. + for helper in ["waybar", "mako", "swaybg", "swayidle", "swaylock"] { + assert!( + !script.contains(helper), + "Mango session must not start the dwl helper {helper}" + ); + } + // User config is seeded, never overwritten. + assert!(script.contains("if [ ! -e \"$mango_conf\" ]")); + assert!(script.contains("dbus-update-activation-environment --systemd")); + assert!(script.contains("wait \"$MANGO_PID\"")); + + let config = MANGO_CONFIG_DEFAULT; + assert!(config.contains("dms ipc call lock lock")); + assert!(config.contains("dms ipc call spotlight toggle")); + assert!(config.contains("XF86AudioRaiseVolume")); + assert!(config.contains("XF86MonBrightnessDown")); + assert!(config.contains("phoebus-assistant")); + assert!(config.contains("source=~/.config/mango/dms/")); + + let (name, entry) = wayland_session_entry(DesktopProfile::Mango).unwrap(); + assert_eq!(name, "phoebus-mango.desktop"); + assert!(entry.contains("Exec=/usr/local/bin/phoebus-session-mango")); + } } diff --git a/installer-rs/crates/phoebus-core/src/transaction.rs b/installer-rs/crates/phoebus-core/src/transaction.rs new file mode 100644 index 0000000..58d1804 --- /dev/null +++ b/installer-rs/crates/phoebus-core/src/transaction.rs @@ -0,0 +1,150 @@ +//! A user-queryable transaction log for assistant and `sys` actions. +//! +//! Snapshot history records recovery points; this records *what was run and +//! whether it succeeded*, including failures, so a later session can explain +//! what changed. + +use std::path::Path; + +use serde::{Deserialize, Serialize}; + +use crate::error::{CoreError, Result}; + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(default)] +pub struct TransactionRecord { + pub created_unix: u64, + /// Where the request came from: `sys` or `assistant`. + pub origin: String, + /// A short human-readable summary. + pub summary: String, + /// The validated typed actions, rendered. + pub actions: Vec, + /// `ok` or a failure description. + pub result: String, + /// The recovery point protecting the change, when one was made. + pub snapshot: Option, + /// The reviewed plan digest, when effects were resolved. + pub digest: Option, +} + +impl Default for TransactionRecord { + fn default() -> Self { + Self { + created_unix: 0, + origin: String::new(), + summary: String::new(), + actions: Vec::new(), + result: "ok".into(), + snapshot: None, + digest: None, + } + } +} + +#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)] +#[serde(default)] +pub struct TransactionLog { + pub records: Vec, +} + +const MAX_RECORDS: usize = 500; + +impl TransactionLog { + pub fn load(path: &Path) -> Result { + if !path.exists() { + return Ok(Self::default()); + } + let text = std::fs::read_to_string(path).map_err(|e| CoreError::io(path, e))?; + if text.trim().is_empty() { + return Ok(Self::default()); + } + Ok(toml::from_str(&text)?) + } + + pub fn save(&self, path: &Path) -> Result<()> { + if let Some(parent) = path.parent() { + std::fs::create_dir_all(parent).map_err(|e| CoreError::io(parent, e))?; + } + std::fs::write(path, toml::to_string_pretty(self)?).map_err(|e| CoreError::io(path, e))?; + Ok(()) + } + + /// Append a record, bounding the log so it cannot grow without limit. + pub fn append(&mut self, record: TransactionRecord) { + self.records.push(record); + if self.records.len() > MAX_RECORDS { + let overflow = self.records.len() - MAX_RECORDS; + self.records.drain(0..overflow); + } + } + + pub fn render(&self) -> String { + if self.records.is_empty() { + return "no transactions recorded".to_string(); + } + let mut out = String::new(); + for r in &self.records { + out.push_str(&format!( + "{:<12} {:<10} {:<8} {}", + r.created_unix, r.origin, r.result, r.summary + )); + if let Some(snap) = &r.snapshot { + out.push_str(&format!(" [snapshot {snap}]")); + } + out.push('\n'); + } + out + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn roundtrip_and_render() { + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("transactions.toml"); + let mut log = TransactionLog::default(); + log.append(TransactionRecord { + created_unix: 10, + origin: "assistant".into(), + summary: "install vim".into(), + actions: vec!["install package app-editors/vim".into()], + result: "ok".into(), + snapshot: Some("@-x".into()), + digest: Some("abc".into()), + }); + log.save(&path).unwrap(); + let loaded = TransactionLog::load(&path).unwrap(); + assert_eq!(loaded, log); + assert!(loaded.render().contains("install vim")); + assert!(loaded.render().contains("@-x")); + } + + #[test] + fn missing_and_corrupt_are_distinguished() { + let dir = tempfile::tempdir().unwrap(); + assert!(TransactionLog::load(&dir.path().join("none.toml")) + .unwrap() + .records + .is_empty()); + let path = dir.path().join("bad.toml"); + std::fs::write(&path, "not = = toml [[[").unwrap(); + assert!(TransactionLog::load(&path).is_err()); + } + + #[test] + fn log_is_bounded() { + let mut log = TransactionLog::default(); + for i in 0..(MAX_RECORDS + 50) { + log.append(TransactionRecord { + created_unix: i as u64, + ..Default::default() + }); + } + assert_eq!(log.records.len(), MAX_RECORDS); + assert_eq!(log.records.first().unwrap().created_unix, 50); + } +} diff --git a/installer-rs/crates/phoebus-executor/src/actions.rs b/installer-rs/crates/phoebus-executor/src/actions.rs index 49f1ed1..154eb4b 100644 --- a/installer-rs/crates/phoebus-executor/src/actions.rs +++ b/installer-rs/crates/phoebus-executor/src/actions.rs @@ -6,6 +6,7 @@ use std::path::Path; use phoebus_core::action::SystemAction; +use phoebus_core::effects::{changed_materially, parse_emerge_pretend, ResolvedPlan}; use crate::auth::DestructiveAuthorization; use crate::command::CommandSpec; @@ -32,6 +33,78 @@ pub fn preview(action: &SystemAction) -> String { out } +/// The Portage arguments that produce a resolved pretend plan for an action, +/// or `None` when the action is not a Portage transaction. +fn pretend_args(action: &SystemAction) -> Option> { + match action { + SystemAction::InstallPackage { atom } => { + Some(vec!["--pretend".into(), "--color=n".into(), atom.clone()]) + } + SystemAction::RemovePackage { atom } => Some(vec![ + "--pretend".into(), + "--unmerge".into(), + "--color=n".into(), + atom.clone(), + ]), + SystemAction::UpdateSystem => Some(vec![ + "--pretend".into(), + "--update".into(), + "--deep".into(), + "--newuse".into(), + "--color=n".into(), + "@world".into(), + ]), + _ => None, + } +} + +/// Resolve exactly what a package action will do. Non-Portage actions yield an +/// empty plan. A plan's digest can be bound to an approval. +pub fn resolve_effects(exec: &Exec, action: &SystemAction, root: &Path) -> Result { + let Some(args) = pretend_args(action) else { + return Ok(ResolvedPlan::default()); + }; + let out = if root == Path::new("/") { + exec.run_capture(CommandSpec::new("sys", "resolve effects", "emerge").args(args))? + } else { + let mut chroot_args = vec![root.to_string_lossy().to_string(), "emerge".to_string()]; + chroot_args.extend(args); + exec.run_capture(CommandSpec::new("sys", "resolve effects", "chroot").args(chroot_args))? + }; + let mut plan = parse_emerge_pretend(&out.stdout_lossy()); + if root.join(snapshot::SNAPSHOT_DIR).is_dir() { + plan.recovery_point = Some("a protective snapshot before the change".into()); + } + Ok(plan) +} + +/// Execute an action after re-resolving it against the approved digest. If the +/// plan changed materially since review, execution is refused. +pub fn execute_checked( + exec: &Exec, + action: &SystemAction, + auth: Option<&DestructiveAuthorization>, + root: &Path, + approved: Option<&ResolvedPlan>, +) -> Result { + if let Some(approved) = approved { + let current = resolve_effects(exec, action, root)?; + if changed_materially(approved, ¤t) { + return Err(ExecError::operation( + "sys", + "plan changed", + format!( + "the reviewed plan changed before execution (approved {}, now {}); \ + re-run and review again", + &approved.digest[..approved.digest.len().min(12)], + ¤t.digest[..current.digest.len().min(12)] + ), + )); + } + } + execute(exec, action, auth, root) +} + pub fn execute( exec: &Exec, action: &SystemAction, @@ -42,6 +115,27 @@ pub fn execute( return Err(ExecError::NotAuthorized(action.describe())); } + // Rollback moves the root, `/var` and the boot selection together and takes + // its own pre-rollback snapshot, so it must not run through the generic + // protective-snapshot path below. + if let SystemAction::Undo { snapshot } = action { + let auth = auth.ok_or_else(|| ExecError::NotAuthorized(action.describe()))?; + let outcome = crate::rollback::execute(exec, auth, root, snapshot.as_deref())?; + let mut output = format!( + "rollback activated: {} -> {}\nnext boot uses {}\nreboot to complete; \ + a known-good previous entry is kept", + outcome.state.target_snapshot, outcome.state.root_subvol, outcome.state.root_subvol + ); + for warning in &outcome.warnings { + output.push_str(&format!("\nwarning: {warning}")); + } + return Ok(ActionOutcome { + action: action.clone(), + output, + snapshot: Some(outcome.state.target_snapshot), + }); + } + // A protective snapshot must exist before a high-risk change. If the // snapshots subvolume is present but the snapshot cannot be created, fail // closed rather than proceed without a recovery point. A system without a @@ -112,6 +206,40 @@ pub fn execute( )?; format!("{}\n{}", out.stdout_lossy(), out.stderr_lossy()) } + SystemAction::FlatpakInstall { app_id } => { + exec.run( + CommandSpec::new("sys", "install flatpak", "flatpak") + .args(["install", "-y", "flathub", app_id]), + )?; + format!("installed Flatpak app {app_id}") + } + SystemAction::FlatpakRemove { app_id } => { + exec.run(CommandSpec::new("sys", "remove flatpak", "flatpak").args([ + "uninstall", + "-y", + app_id, + ]))?; + format!("removed Flatpak app {app_id}") + } + SystemAction::FlatpakList => { + let out = exec.runner.execute( + &CommandSpec::new("sys", "list flatpaks", "flatpak").args([ + "list", + "--app", + "--columns=application,version,branch", + ]), + )?; + let text = format!("{}\n{}", out.stdout_lossy(), out.stderr_lossy()); + if text.trim().is_empty() { + "no Flatpak applications installed".to_string() + } else { + text + } + } + SystemAction::NixPrepare { packages } => { + let prepared = crate::nix::prepare_dev_packages(exec, root, packages)?; + format!("realised Nix development packages: {}", prepared.join(", ")) + } SystemAction::UpdateSystem => { exec.run( CommandSpec::new("sys", "update system", "emerge") @@ -125,6 +253,8 @@ pub fn execute( snapshot_id = Some(record.id.clone()); format!("snapshot created: {}", record.id) } + // Handled before the match (it has its own snapshot/safety path). + SystemAction::Undo { .. } => "rollback handled by the dedicated path".to_string(), SystemAction::PrepareUpdates => { let cores = std::thread::available_parallelism() .map(|n| n.get() as u32) @@ -141,15 +271,32 @@ pub fn execute( } SystemAction::History => { let history = snapshot::read_history(root)?; + let mut s = String::new(); if history.records.is_empty() { - "no transaction history".to_string() + s.push_str("no snapshot history\n"); } else { - let mut s = String::new(); + s.push_str("snapshots:\n"); for r in &history.records { s.push_str(&format!("{:<40} {:<16?} {}\n", r.id, r.status, r.operation)); } - s } + let log = crate::transaction::read(root)?; + s.push_str("transactions:\n"); + s.push_str(&log.render()); + s + } + SystemAction::RollbackStatus => { + // Reading the state may also promote an activated rollback to + // verified once the restored root is the running root. + let state = crate::rollback::verify(exec, root)?; + format!( + "status: {:?}\nroot subvolume: {}\n/var subvolume: {}\ntarget: {}\nnote: {}", + state.status, + state.root_subvol, + state.var_subvol.as_deref().unwrap_or("(none)"), + state.target_snapshot, + state.note + ) } }; Ok(ActionOutcome { @@ -291,4 +438,23 @@ mod tests { assert_eq!(spec.program, "systemctl"); assert_eq!(spec.args, vec!["enable", "sshd"]); } + + #[test] + fn undo_requires_authorization() { + let runner = RecordingRunner::new(); + let exec = make_exec(runner); + let action = SystemAction::Undo { snapshot: None }; + let err = execute(&exec, &action, None, Path::new(&exec.root)).unwrap_err(); + assert!(matches!(err, ExecError::NotAuthorized(_))); + } + + #[test] + fn rollback_status_reports_default_state() { + let runner = RecordingRunner::new(); + let exec = make_exec(runner); + let action = SystemAction::RollbackStatus; + let outcome = execute(&exec, &action, None, Path::new(&exec.root)).unwrap(); + assert!(outcome.output.contains("Idle")); + assert!(outcome.snapshot.is_none()); + } } diff --git a/installer-rs/crates/phoebus-executor/src/ai.rs b/installer-rs/crates/phoebus-executor/src/ai.rs index 1d9c645..0a255cf 100644 --- a/installer-rs/crates/phoebus-executor/src/ai.rs +++ b/installer-rs/crates/phoebus-executor/src/ai.rs @@ -47,6 +47,7 @@ pub fn load_api_key(path: &Path) -> Result { pub struct CurlTransport<'a> { exec: &'a Exec, api_key: Option, + sandboxed: bool, } impl<'a> CurlTransport<'a> { @@ -54,7 +55,18 @@ impl<'a> CurlTransport<'a> { if let Some(key) = &api_key { exec.register_secret(key); } - Self { exec, api_key } + Self { + exec, + api_key, + sandboxed: false, + } + } + + /// Run the network call inside the OS-level model sandbox (installed + /// assistant). Fails closed when `systemd-run` is unavailable. + pub fn sandboxed(mut self) -> Self { + self.sandboxed = true; + self } } @@ -65,6 +77,9 @@ impl ModelTransport for CurlTransport<'_> { url: &str, body: &str, ) -> std::result::Result { + if self.sandboxed { + return self.send_sandboxed(url, body); + } let mut request = tempfile::Builder::new() .prefix("phoebus-ai-request.") .tempfile() @@ -100,6 +115,34 @@ impl ModelTransport for CurlTransport<'_> { } } +impl CurlTransport<'_> { + /// Sandboxed variant: the request body is embedded in the curl config on + /// stdin (never on disk, never in argv), and curl runs inside a hardened, + /// unprivileged unit. `PrivateTmp=yes` is therefore safe. + fn send_sandboxed(&self, url: &str, body: &str) -> std::result::Result { + let auth = match &self.api_key { + Some(key) => format!("header = \"Authorization: Bearer {}\"\n", key.expose()), + None => String::new(), + }; + let escaped = body.replace('\\', "\\\\").replace('"', "\\\""); + let config = format!( + "url = \"{url}\"\n\ + header = \"Content-Type: application/json\"\n\ + {auth}\ + data = \"{escaped}\"\n\ + silent\nshow-error\nfail-with-body\nmax-time = 120\n" + ); + let out = crate::sandbox::run( + self.exec, + "curl", + &["-sS".into(), "-K".into(), "-".into()], + config.into_bytes(), + ) + .map_err(|e| AiError::Provider(e.to_string()))?; + Ok(out.stdout_lossy()) + } +} + #[cfg(test)] mod tests { use super::*; diff --git a/installer-rs/crates/phoebus-executor/src/boot.rs b/installer-rs/crates/phoebus-executor/src/boot.rs index 285b1ec..8e7d775 100644 --- a/installer-rs/crates/phoebus-executor/src/boot.rs +++ b/installer-rs/crates/phoebus-executor/src/boot.rs @@ -161,6 +161,72 @@ pub fn write_recovery_entry(exec: &Exec, config: &InstallConfig) -> Result<()> { Ok(()) } +/// Write a recovery entry that boots an existing read-only snapshot directly. +/// +/// Unlike the `rescue.target` entry derived from the live root, this does not +/// depend on the current root being healthy: it points `rootflags=subvol=` at a +/// snapshot under `@snapshots`, so a broken update can still be repaired. +pub fn write_snapshot_recovery_entry( + exec: &Exec, + config: &InstallConfig, + snapshot_subvol: &str, +) -> Result<()> { + use phoebus_core::boot::{version_key, BlsEntry}; + let entries = esp_path(exec, config).join("loader/entries"); + if !entries.is_dir() { + return Ok(()); + } + let mut newest: Option = None; + for entry in std::fs::read_dir(&entries).map_err(|e| ExecError::io(entries.clone(), e))? { + let entry = entry.map_err(|e| ExecError::io(entries.clone(), e))?; + if entry.path().extension().and_then(|e| e.to_str()) != Some("conf") { + continue; + } + let name = entry.file_name().to_string_lossy().to_string(); + if name.starts_with("phoebus-") { + continue; + } + let text = match std::fs::read_to_string(entry.path()) { + Ok(t) => t, + Err(_) => continue, + }; + let Some(parsed) = BlsEntry::parse(&name, &text) else { + continue; + }; + let better = match &newest { + None => true, + Some(current) => { + let a = parsed + .kernel_version() + .map(|v| version_key(&v)) + .unwrap_or_default(); + let b = current + .kernel_version() + .map(|v| version_key(&v)) + .unwrap_or_default(); + a > b + } + }; + if better { + newest = Some(parsed); + } + } + let Some(best) = newest else { + return Ok(()); + }; + let subvol = format!("@snapshots/{snapshot_subvol}"); + let recovery = best + .with_root_subvol(&subvol) + .map_err(|e| ExecError::operation("boot_install", "rewrite recovery entry", e))? + .with_title("Phoebus Recovery (known-good snapshot)") + .with_option("ro systemd.unit=rescue.target"); + let dest = entries.join("phoebus-recovery.conf"); + std::fs::write(&dest, recovery.render()).map_err(|e| ExecError::io(dest.clone(), e))?; + exec.logger + .info(format!("wrote snapshot recovery entry -> {}", subvol)); + Ok(()) +} + pub fn verify(exec: &Exec, config: &InstallConfig) -> Result<()> { let esp = esp_path(exec, config); let loader_a = esp.join("EFI/systemd/systemd-bootx64.efi"); diff --git a/installer-rs/crates/phoebus-executor/src/desktop.rs b/installer-rs/crates/phoebus-executor/src/desktop.rs index bb5645b..d8d9995 100644 --- a/installer-rs/crates/phoebus-executor/src/desktop.rs +++ b/installer-rs/crates/phoebus-executor/src/desktop.rs @@ -55,6 +55,31 @@ pub fn write_session_script(exec: &Exec, config: &InstallConfig) -> Result<()> { return Ok(()); } let target = exec.target(); + + // A launcher for the installed assistant. It opens `sys ask`, which keeps + // privilege and approval in the deterministic broker. + write_script( + &target, + "usr/local/bin/phoebus-assistant", + sysgen::PHOEBUS_ASSISTANT_SCRIPT, + )?; + + match config.desktop.profile { + DesktopProfile::Mango => { + write_mango_session(exec, &target)?; + // The dwl session stays installed as a fallback. + write_dwl_session(exec, &target)?; + } + DesktopProfile::Dwl | DesktopProfile::Full => { + write_dwl_session(exec, &target)?; + } + // Minimal has no session entry point. + _ => {} + } + Ok(()) +} + +fn write_dwl_session(exec: &Exec, target: &phoebus_core::TargetRoot) -> Result<()> { let script = sysgen::PHOEBUS_SESSION_SCRIPT; let path = target.resolve("usr/local/bin/phoebus-session")?; target.write("usr/local/bin/phoebus-session", script)?; @@ -68,6 +93,31 @@ pub fn write_session_script(exec: &Exec, config: &InstallConfig) -> Result<()> { format!("session script missing after write: {}", path.display()), )); } + + // Launcher/power menu, screen locker and idle daemon. Installing these (and + // the Waybar configuration below) completes the discoverable desktop: a + // user can launch apps, control network/audio, lock and suspend without + // editing configuration by hand. + write_script( + &target, + "usr/local/bin/phoebus-menu", + sysgen::PHOEBUS_MENU_SCRIPT, + )?; + write_script( + &target, + "usr/local/bin/phoebus-lock", + sysgen::PHOEBUS_LOCK_SCRIPT, + )?; + write_script( + &target, + "usr/local/bin/phoebus-idle", + sysgen::PHOEBUS_IDLE_SCRIPT, + )?; + target.write("etc/xdg/waybar/config", sysgen::WAYBAR_CONFIG)?; + target.write("etc/xdg/waybar/style.css", sysgen::WAYBAR_STYLE)?; + if let Some((name, entry)) = sysgen::wayland_session_entry(DesktopProfile::Dwl) { + target.write(&format!("usr/share/wayland-sessions/{name}"), entry)?; + } exec.logger.info(format!( "wrote /usr/local/bin/phoebus-session ({})", path.display() @@ -75,6 +125,53 @@ pub fn write_session_script(exec: &Exec, config: &InstallConfig) -> Result<()> { Ok(()) } +fn write_mango_session(exec: &Exec, target: &phoebus_core::TargetRoot) -> Result<()> { + write_script( + target, + "usr/local/bin/phoebus-session-mango", + sysgen::PHOEBUS_MANGO_SESSION_SCRIPT, + )?; + target.write("etc/xdg/mango/config.conf", sysgen::MANGO_CONFIG_DEFAULT)?; + target.write( + "usr/lib/systemd/user/mango-session.target", + sysgen::MANGO_SESSION_TARGET, + )?; + // Bind dms.service to the session target when the DMS package provides it; + // the session script falls back to `dms run` otherwise. + let dms_unit = target.resolve("usr/lib/systemd/user/dms.service")?; + if dms_unit.exists() { + let wants = target.resolve("etc/systemd/user/mango-session.target.wants/dms.service")?; + if let Some(parent) = wants.parent() { + std::fs::create_dir_all(parent).map_err(|e| ExecError::io(parent.to_path_buf(), e))?; + } + let _ = std::fs::remove_file(&wants); + std::os::unix::fs::symlink(&dms_unit, &wants) + .map_err(|e| ExecError::io(wants.clone(), e))?; + } + if let Some((name, entry)) = sysgen::wayland_session_entry(DesktopProfile::Mango) { + target.write(&format!("usr/share/wayland-sessions/{name}"), entry)?; + } + exec.logger + .info("wrote /usr/local/bin/phoebus-session-mango (Mango + DMS)"); + Ok(()) +} + +fn write_script(target: &phoebus_core::TargetRoot, rel: &str, contents: &str) -> Result<()> { + use std::os::unix::fs::PermissionsExt; + let path = target.resolve(rel)?; + target.write(rel, contents)?; + std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o755)) + .map_err(|e| ExecError::io(path.clone(), e))?; + if !path.is_file() { + return Err(ExecError::operation( + "desktop", + "write session helper", + format!("helper missing after write: {}", path.display()), + )); + } + Ok(()) +} + pub fn configure_flatpak(exec: &Exec, config: &InstallConfig) -> Result<()> { if !config.desktop.flatpak { return Ok(()); @@ -135,6 +232,37 @@ mod tests { ); } + #[test] + fn session_helpers_and_waybar_config_are_installed() { + let runner = RecordingRunner::new(); + let exec = make_exec(runner); + let mut cfg = InstallConfig::default(); + cfg.desktop.profile = DesktopProfile::Dwl; + write_session_script(&exec, &cfg).unwrap(); + for rel in [ + "usr/local/bin/phoebus-menu", + "usr/local/bin/phoebus-lock", + "usr/local/bin/phoebus-idle", + "etc/xdg/waybar/config", + "etc/xdg/waybar/style.css", + ] { + let path = exec.root.join(rel); + assert!(path.is_file(), "{rel} was not installed"); + } + use std::os::unix::fs::PermissionsExt; + for rel in [ + "usr/local/bin/phoebus-menu", + "usr/local/bin/phoebus-lock", + "usr/local/bin/phoebus-idle", + ] { + let mode = std::fs::metadata(exec.root.join(rel)) + .unwrap() + .permissions() + .mode(); + assert_ne!(mode & 0o111, 0, "{rel} must be executable"); + } + } + #[test] fn no_session_script_for_none_profile() { let runner = RecordingRunner::new(); @@ -143,4 +271,38 @@ mod tests { write_session_script(&exec, &cfg).unwrap(); assert!(!exec.root.join("usr/local/bin/phoebus-session").exists()); } + + #[test] + fn mango_profile_installs_both_sessions_and_no_dwl_helpers_in_mango() { + let runner = RecordingRunner::new(); + let exec = make_exec(runner); + let mut cfg = InstallConfig::default(); + cfg.desktop.profile = DesktopProfile::Mango; + write_session_script(&exec, &cfg).unwrap(); + for rel in [ + "usr/local/bin/phoebus-session-mango", + "usr/local/bin/phoebus-session", + "usr/local/bin/phoebus-assistant", + "etc/xdg/mango/config.conf", + "usr/lib/systemd/user/mango-session.target", + "usr/share/wayland-sessions/phoebus-mango.desktop", + "usr/share/wayland-sessions/phoebus-dwl.desktop", + ] { + assert!(exec.root.join(rel).is_file(), "{rel} was not installed"); + } + let mango = + std::fs::read_to_string(exec.root.join("usr/local/bin/phoebus-session-mango")).unwrap(); + for helper in ["waybar", "mako", "swaybg", "swayidle", "swaylock"] { + assert!( + !mango.contains(helper), + "Mango session must not start {helper}" + ); + } + assert!(mango.contains("dms run") || mango.contains("mango-session.target")); + let dwl = std::fs::read_to_string(exec.root.join("usr/local/bin/phoebus-session")).unwrap(); + assert!( + dwl.contains("dwl &"), + "dwl fallback session must be present" + ); + } } diff --git a/installer-rs/crates/phoebus-executor/src/lib.rs b/installer-rs/crates/phoebus-executor/src/lib.rs index fc8b00b..3efe9b2 100644 --- a/installer-rs/crates/phoebus-executor/src/lib.rs +++ b/installer-rs/crates/phoebus-executor/src/lib.rs @@ -20,10 +20,13 @@ pub mod nix; pub mod opencode; pub mod portage; pub mod probe; +pub mod rollback; +pub mod sandbox; pub mod services; pub mod snapshot; pub mod stage3; pub mod storage; +pub mod transaction; pub mod update; pub mod users; diff --git a/installer-rs/crates/phoebus-executor/src/nix.rs b/installer-rs/crates/phoebus-executor/src/nix.rs index 56739c9..729b9f5 100644 --- a/installer-rs/crates/phoebus-executor/src/nix.rs +++ b/installer-rs/crates/phoebus-executor/src/nix.rs @@ -26,6 +26,25 @@ fn nix_store_bin() -> String { format!("/nix/store/{NIX_STORE_NAME}/bin/nix-store") } +/// The generated `/etc/nix/nix.conf`. +/// +/// Build isolation is on and does not silently fall back: the Nix sandbox uses +/// Linux user namespaces, which the Phoebus kernel enables. `min-free` and +/// `max-free` bound the store so it cannot fill the root filesystem, and +/// `auto-optimise-store` deduplicates. +pub fn nix_conf() -> &'static str { + "# Phoebus: Nix as a second package lane (developer tools only).\n\ + build-users-group = nixbld\n\ + sandbox = true\n\ + sandbox-fallback = false\n\ + auto-optimise-store = true\n\ + min-free = 1073741824\n\ + max-free = 10737418240\n\ + experimental-features = nix-command flakes\n\ + substituters = https://cache.nixos.org\n\ + trusted-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=\n" +} + fn target_path(root: &Path, rel: &str) -> PathBuf { root.join(rel) } @@ -148,17 +167,10 @@ fn bootstrap(exec: &Exec, root: &Path, tarball: &Path) -> Result<()> { ); } - // Configuration and profile wiring. - write_file( - root, - "etc/nix/nix.conf", - "# Phoebus: Nix as a second package lane.\n\ - build-users-group = nixbld\n\ - sandbox = false\n\ - experimental-features = nix-command flakes\n\ - substituters = https://cache.nixos.org\n\ - trusted-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=\n", - )?; + // Configuration and profile wiring. Build isolation is enabled: the Nix + // sandbox uses user namespaces and fails closed rather than silently + // building unsandboxed, so a compromised build cannot reach the host. + write_file(root, "etc/nix/nix.conf", nix_conf())?; let profile = "nix/var/nix/profiles"; std::fs::create_dir_all(target_path(root, profile)) .map_err(|e| ExecError::io(target_path(root, profile), e))?; @@ -200,6 +212,85 @@ fn bootstrap(exec: &Exec, root: &Path, tarball: &Path) -> Result<()> { Ok(()) } +/// Whether the Nix store is present in the target. +pub fn installed(root: &Path) -> bool { + target_path(root, &format!("nix/store/{NIX_STORE_NAME}")).is_dir() +} + +/// Remove Nix's system integration: the daemon units and profile wiring. The +/// store is only deleted when `purge` is set, because the store may back +/// user environments that should be removed deliberately. +pub fn remove(exec: &Exec, root: &Path, purge: bool) -> Result<()> { + let _ = crate::portage::chroot(exec, root, "systemctl", &["disable", "nix-daemon.service"]); + let _ = crate::portage::chroot(exec, root, "systemctl", &["disable", "nix-daemon.socket"]); + for rel in [ + "etc/systemd/system/nix-daemon.service", + "etc/systemd/system/nix-daemon.socket", + "etc/systemd/system/multi-user.target.wants/nix-daemon.service", + "etc/systemd/system/sockets.target.wants/nix-daemon.socket", + "root/.nix-profile", + "etc/profile.d/nix.sh", + ] { + let path = target_path(root, rel); + let _ = std::fs::remove_file(&path); + } + let _ = std::fs::remove_file(target_path(root, "nix/var/nix/profiles/default")); + if purge { + let nix_dir = target_path(root, "nix"); + if let Err(e) = std::fs::remove_dir_all(&nix_dir) { + if e.kind() != std::io::ErrorKind::NotFound { + return Err(ExecError::io(nix_dir, e)); + } + } + } + exec.logger.info(format!( + "removed Nix integration{}", + if purge { " (store purged)" } else { "" } + )); + Ok(()) +} + +/// Run the Nix garbage collector, bounded by the `min-free`/`max-free` settings +/// in `/etc/nix/nix.conf`. +pub fn gc(exec: &Exec, root: &Path) -> Result<()> { + let binary = format!("{}/bin/nix-store", "/nix/var/nix/profiles/default"); + crate::portage::chroot(exec, root, &binary, &["--gc"])?; + exec.logger.info("Nix store garbage collection complete"); + Ok(()) +} + +/// Realise a bounded set of development packages so they are available offline. +/// +/// Each entry is a bare nixpkgs attribute name (`nodejs`, `python312`); URLs and +/// flake references are refused, so the assistant cannot make Nix evaluate +/// arbitrary remote inputs. +pub fn prepare_dev_packages(exec: &Exec, root: &Path, packages: &[String]) -> Result> { + let mut prepared = Vec::new(); + let binary = "/nix/var/nix/profiles/default/bin/nix"; + for package in packages { + if !valid_nix_attribute(package) { + return Err(ExecError::operation( + "nix", + "prepare package", + format!("invalid nixpkgs attribute: {package}"), + )); + } + crate::portage::chroot( + exec, + root, + binary, + &["shell", &format!("nixpkgs#{package}"), "-c", "true"], + )?; + prepared.push(package.clone()); + } + Ok(prepared) +} + +/// A bounded nixpkgs attribute: no slashes, URLs, or flake references. +pub fn valid_nix_attribute(value: &str) -> bool { + phoebus_core::action::valid_nix_attribute(value) +} + fn write_file(root: &Path, rel: &str, contents: &str) -> Result<()> { let path = target_path(root, rel); if let Some(parent) = path.parent() { @@ -257,4 +348,40 @@ mod tests { assert!(!crate::opencode::checksum_ok(&file, &"0".repeat(64)).unwrap()); assert!(!crate::opencode::checksum_ok(&file, "deadbeef").unwrap()); } + + #[test] + fn conf_enables_enforced_sandbox_and_store_bounds() { + let conf = nix_conf(); + assert!(conf.contains("sandbox = true")); + assert!(conf.contains("sandbox-fallback = false")); + assert!(conf.contains("min-free =")); + assert!(conf.contains("max-free =")); + assert!(!conf.contains("sandbox = false")); + } + + #[test] + fn nixpkg_attribute_is_bounded() { + assert!(valid_nix_attribute("nodejs")); + assert!(valid_nix_attribute("python312")); + assert!(valid_nix_attribute("gcc13")); + assert!(!valid_nix_attribute("")); + assert!(!valid_nix_attribute("github:owner/repo")); + assert!(!valid_nix_attribute("nixpkgs#x/y")); + assert!(!valid_nix_attribute("a b")); + } + + #[test] + fn remove_unlinks_units_and_optionally_purges() { + let runner = RecordingRunner::new(); + let exec = make_exec(runner, false); + let root = Path::new(&exec.root); + std::fs::create_dir_all(root.join("etc/systemd/system")).unwrap(); + std::fs::write(root.join("etc/systemd/system/nix-daemon.service"), "x").unwrap(); + std::fs::create_dir_all(root.join("nix/store")).unwrap(); + remove(&exec, root, false).unwrap(); + assert!(!root.join("etc/systemd/system/nix-daemon.service").exists()); + assert!(root.join("nix/store").exists()); + remove(&exec, root, true).unwrap(); + assert!(!root.join("nix").exists()); + } } diff --git a/installer-rs/crates/phoebus-executor/src/portage.rs b/installer-rs/crates/phoebus-executor/src/portage.rs index e0705f9..1e11361 100644 --- a/installer-rs/crates/phoebus-executor/src/portage.rs +++ b/installer-rs/crates/phoebus-executor/src/portage.rs @@ -26,14 +26,51 @@ pub fn write_config(exec: &Exec, config: &InstallConfig, hardware: &HardwareRepo "etc/portage/package.use/phoebus", sysgen::package_use(config), )?; - root.write( - "etc/portage/package.accept_keywords/phoebus", - sysgen::accept_keywords_policy(), - )?; + let mut keywords = sysgen::accept_keywords_policy(); + if sysgen::uses_guru(config) { + // The Mango + DankMaterialShell stack lives in GURU and is `~amd64`. + // The keyword set is scoped to those packages and the GURU-only + // dependency; it is never a global `~amd64` switch. + root.write( + "etc/portage/repos.conf/guru.conf", + sysgen::guru_repos_conf(), + )?; + keywords.push('\n'); + keywords.push_str(&sysgen::accept_keywords_mango()); + } + root.write("etc/portage/package.accept_keywords/phoebus", keywords)?; exec.logger.info("wrote Portage configuration"); Ok(()) } +/// The packages that must be present before the GURU overlay (git-only) can be +/// synced. `dev-vcs/git` is installed from the main tree first. +pub fn guru_bootstrap_packages() -> Vec<&'static str> { + vec!["dev-vcs/git"] +} + +/// Sync the GURU overlay after `dev-vcs/git` is available. No-op when the +/// selected profile does not use GURU. +pub fn sync_guru(exec: &Exec, root: &Path, config: &InstallConfig) -> Result<()> { + if !sysgen::uses_guru(config) { + return Ok(()); + } + let mut last_err = None; + for attempt in 1..=3 { + match chroot(exec, root, "emaint", &["sync", "-r", "guru"]) { + Ok(()) => return Ok(()), + Err(e) => { + exec.logger + .warn(format!("guru sync attempt {attempt} failed: {e}")); + last_err = Some(e); + } + } + } + Err(last_err.unwrap_or_else(|| { + ExecError::operation("portage_configure", "emaint sync -r guru", "sync failed") + })) +} + pub fn select_profile(exec: &Exec, config: &InstallConfig) -> Result<()> { let root = exec.target(); let link = root.etc("portage/make.profile")?; diff --git a/installer-rs/crates/phoebus-executor/src/rollback.rs b/installer-rs/crates/phoebus-executor/src/rollback.rs new file mode 100644 index 0000000..4b29598 --- /dev/null +++ b/installer-rs/crates/phoebus-executor/src/rollback.rs @@ -0,0 +1,747 @@ +//! Coordinated rollback and recovery. +//! +//! A rollback moves four things together, because moving only one of them +//! produces an inconsistent or unbootable system: +//! +//! 1. the root subvolume (the running root is preserved and a writable clone of +//! the chosen snapshot becomes the new root generation); +//! 2. the separately mounted `/var` volume, which holds the Portage package +//! database and update state; +//! 3. the kernel command line / fstab in the restored root (`rootflags=subvol=` +//! always wins over the Btrfs default subvolume, so both are edited); +//! 4. the boot entries on the ESP, including a known-good "previous" entry and +//! a recovery entry that boots a snapshot directly, so a broken normal boot +//! is still repairable. +//! +//! An interruption is safe: the safety snapshot is written first, the boot +//! entries are only switched at the end, and the persisted state lets a re-run +//! finish. `sys undo` is exposed only after this path is verified on a +//! disposable VM. + +use std::path::{Path, PathBuf}; + +use phoebus_core::boot::{choose_entry_for_versions, kernel_versions_from_module_dirs, BlsEntry}; +use phoebus_core::rollback::{ + esp_mount_from_mounts, pre_rollback_snapshot_name, restore_root_name, restore_var_name, + rewrite_fstab_subvol, root_device_from_mounts, snapshot_retention_deletions, + snapshot_top_level_path, RollbackState, RollbackStatus, DEFAULT_KEEP_SNAPSHOTS, +}; +use phoebus_core::snapshot::{SnapshotHistory, SnapshotStatus}; + +use crate::auth::DestructiveAuthorization; +use crate::command::CommandSpec; +use crate::error::{ExecError, Result}; +use crate::exec::Exec; +use crate::snapshot; + +pub const STATE_REL: &str = "var/lib/phoebus/rollback-state.toml"; + +pub fn state_path(root: &Path) -> PathBuf { + root.join(STATE_REL) +} + +pub fn load_state(root: &Path) -> RollbackState { + let path = state_path(root); + if !path.exists() { + return RollbackState::default(); + } + std::fs::read_to_string(&path) + .ok() + .and_then(|t| toml::from_str(&t).ok()) + .unwrap_or_default() +} + +pub fn save_state(exec: &Exec, root: &Path, state: &RollbackState) -> Result<()> { + let path = state_path(root); + if let Some(parent) = path.parent() { + std::fs::create_dir_all(parent).map_err(|e| ExecError::io(parent.to_path_buf(), e))?; + } + let text = toml::to_string_pretty(state) + .map_err(|e| ExecError::operation("rollback", "serialize state", e.to_string()))?; + std::fs::write(&path, text).map_err(|e| ExecError::io(path.clone(), e))?; + exec.logger + .info(format!("rollback state -> {}", path.display())); + Ok(()) +} + +/// The device and ESP mount used to stage a rollback. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct RollbackEnv { + pub root_device: String, + pub esp_mount: String, +} + +/// Determine the root device and ESP from `/proc/self/mounts` text. +pub fn detect_env(mounts: &str) -> Result { + let root_device = root_device_from_mounts(mounts) + .ok_or_else(|| ExecError::operation("rollback", "detect root", "no root mount found"))?; + let esp_mount = esp_mount_from_mounts(mounts).unwrap_or_else(|| "/efi".to_string()); + Ok(RollbackEnv { + root_device, + esp_mount, + }) +} + +/// A resolved rollback target. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct RollbackPlan { + pub target_snapshot: String, + pub target_var_snapshot: Option, + pub root_subvol: String, + pub var_subvol: Option, + pub previous_root: String, + pub ts: u64, + pub reason: String, +} + +/// Resolve the snapshot to restore. With `snapshot_id` unset the newest +/// committed snapshot is used. A missing or uncommitted id is refused. +pub fn plan( + root: &Path, + history: &SnapshotHistory, + snapshot_id: Option<&str>, + ts: u64, +) -> Result { + let record = match snapshot_id { + Some(id) => history + .records + .iter() + .rev() + .find(|r| r.id == id) + .ok_or_else(|| { + ExecError::operation( + "rollback", + "select snapshot", + format!("no snapshot with id `{id}`"), + ) + })?, + None => phoebus_core::rollback::latest_committed(history).ok_or_else(|| { + ExecError::operation( + "rollback", + "select snapshot", + "no committed snapshot to restore", + ) + })?, + }; + if record.status != SnapshotStatus::Committed { + return Err(ExecError::operation( + "rollback", + "select snapshot", + format!( + "snapshot `{}` is {:?}, not committed; refusing to restore", + record.id, record.status + ), + )); + } + let snapshot_dir = snapshot::snapshots_path(root).join(&record.snapshot_subvol); + if !snapshot_dir.exists() { + return Err(ExecError::operation( + "rollback", + "select snapshot", + format!("snapshot subvolume {} is missing", snapshot_dir.display()), + )); + } + let var_subvol = record.var_snapshot.as_ref().map(|_| restore_var_name(ts)); + Ok(RollbackPlan { + target_snapshot: record.snapshot_subvol.clone(), + target_var_snapshot: record.var_snapshot.clone(), + root_subvol: restore_root_name(ts), + var_subvol, + previous_root: "@".to_string(), + ts, + reason: record.operation.clone(), + }) +} + +#[derive(Debug)] +pub struct RollbackOutcome { + pub state: RollbackState, + pub warnings: Vec, +} + +fn read_entries(entries_dir: &Path) -> Vec { + let mut out = Vec::new(); + let Ok(dir) = std::fs::read_dir(entries_dir) else { + return out; + }; + for entry in dir.flatten() { + let path = entry.path(); + if path.extension().and_then(|e| e.to_str()) != Some("conf") { + continue; + } + let name = entry.file_name().to_string_lossy().to_string(); + if let Ok(text) = std::fs::read_to_string(&path) { + if let Some(parsed) = BlsEntry::parse(&name, &text) { + out.push(parsed); + } + } + } + out.sort_by(|a, b| a.file_name.cmp(&b.file_name)); + out +} + +/// Find the subvolume id for a path from `btrfs subvolume list -o` output. +pub fn subvol_id_for_path(list_output: &str, target: &str) -> Option { + for line in list_output.lines() { + // e.g. "ID 256 gen 10 top level 5 path @restore-20260101T000000" + let fields: Vec<&str> = line.split_whitespace().collect(); + let id = fields + .iter() + .position(|f| *f == "ID") + .and_then(|i| fields.get(i + 1)); + let path = fields + .iter() + .position(|f| *f == "path") + .and_then(|i| fields.get(i + 1)); + if let (Some(id), Some(path)) = (id, path) { + if *path == target { + return Some((*id).to_string()); + } + } + } + None +} + +/// Perform an already-resolved rollback. Exposed for tests with an explicit +/// environment; `execute` wraps it with real mount detection. +pub fn run_with_env( + exec: &Exec, + auth: &DestructiveAuthorization, + root: &Path, + env: &RollbackEnv, + plan: &RollbackPlan, +) -> Result { + let mut warnings = Vec::new(); + + // 0. A recovery point for the current state, before anything moves. + let safety = snapshot::create_set_and_record(exec, auth, root, "/", "pre-rollback")?; + exec.logger + .info(format!("pre-rollback snapshot: {}", safety.id)); + + // 1. Stage the Btrfs top level so subvolumes can be cloned as siblings. + let stage = exec.state_dir.join("rollback-stage"); + std::fs::create_dir_all(&stage).map_err(|e| ExecError::io(stage.clone(), e))?; + exec.run( + CommandSpec::new("rollback", "mount Btrfs top level", "mount") + .args(["-o", "subvolid=5"]) + .arg(&env.root_device) + .arg(stage.to_string_lossy().to_string()), + )?; + + let result = activate(exec, root, env, plan, &stage, &mut warnings); + // Always try to leave the staging mount cleanly. + let _ = exec.run( + CommandSpec::new("rollback", "unmount top level", "umount") + .arg(stage.to_string_lossy().to_string()), + ); + result?; + + let state = RollbackState { + status: RollbackStatus::Activated, + generation: plan.ts, + target_snapshot: plan.target_snapshot.clone(), + target_var_snapshot: plan.target_var_snapshot.clone(), + previous_root: plan.previous_root.clone(), + root_subvol: plan.root_subvol.clone(), + var_subvol: plan.var_subvol.clone(), + boot_entry: Some("phoebus-current.conf".into()), + started_unix: plan.ts, + finished_unix: plan.ts, + note: format!("restore from {} ({})", plan.target_snapshot, plan.reason), + }; + save_state(exec, root, &state)?; + exec.logger.info(format!( + "rollback activated: next boot uses {}", + plan.root_subvol + )); + Ok(RollbackOutcome { state, warnings }) +} + +fn activate( + exec: &Exec, + root: &Path, + _env: &RollbackEnv, + plan: &RollbackPlan, + stage: &Path, + warnings: &mut Vec, +) -> Result<()> { + // 2. Writable clones of the target snapshot(s) as new root generations. + let root_src = stage.join(snapshot_top_level_path(&plan.target_snapshot)); + let root_dst = stage.join(&plan.root_subvol); + if root_dst.join("etc/fstab").exists() { + // Resuming an interrupted activation: the clone already exists. + exec.logger.warn(format!( + "restored root {} already staged; resuming", + root_dst.display() + )); + } else if root_dst.exists() { + return Err(ExecError::operation( + "rollback", + "clone root", + format!("{} already exists", root_dst.display()), + )); + } else { + exec.run( + CommandSpec::new("rollback", "clone root snapshot", "btrfs") + .args(["subvolume", "snapshot"]) + .arg(root_src.to_string_lossy().to_string()) + .arg(root_dst.to_string_lossy().to_string()), + )?; + } + + if let (Some(var_target), Some(var_subvol)) = (&plan.target_var_snapshot, &plan.var_subvol) { + let var_src = stage.join(snapshot_top_level_path(var_target)); + let var_dst = stage.join(var_subvol); + if !var_dst.exists() { + exec.run( + CommandSpec::new("rollback", "clone /var snapshot", "btrfs") + .args(["subvolume", "snapshot"]) + .arg(var_src.to_string_lossy().to_string()) + .arg(var_dst.to_string_lossy().to_string()), + )?; + } + } + + // 3. fstab of the restored root must mount its own generation. + let fstab = root_dst.join("etc/fstab"); + let text = std::fs::read_to_string(&fstab).map_err(|e| ExecError::io(fstab.clone(), e))?; + let mut rewritten = rewrite_fstab_subvol(&text, "/", &plan.root_subvol); + if let Some(var) = &plan.var_subvol { + if phoebus_core::rollback::fstab_has_mountpoint(&rewritten, "/var") { + rewritten = rewrite_fstab_subvol(&rewritten, "/var", var); + } else { + warnings.push("restored root has no /var fstab entry".into()); + } + } + std::fs::write(&fstab, rewritten).map_err(|e| ExecError::io(fstab.clone(), e))?; + + // 4. Select a kernel whose modules exist in the restored root. + let modules_dir = root_dst.join("lib/modules"); + let modules: Vec = std::fs::read_dir(&modules_dir) + .map(|dir| { + dir.flatten() + .map(|e| e.file_name().to_string_lossy().to_string()) + .collect() + }) + .unwrap_or_default(); + let versions = kernel_versions_from_module_dirs(&modules); + let esp = root.join(_env.esp_mount.trim_start_matches('/')); + let entries_dir = esp.join("loader/entries"); + let entries = read_entries(&entries_dir); + let chosen = choose_entry_for_versions(&entries, &versions).or_else(|| { + entries.iter().max_by_key(|e| { + e.kernel_version() + .map(|v| phoebus_core::boot::version_key(&v)) + }) + }); + let Some(chosen) = chosen else { + return Err(ExecError::operation( + "rollback", + "select kernel", + "no boot entry available on the ESP", + )); + }; + if !versions + .iter() + .any(|v| Some(v) == chosen.kernel_version().as_ref()) + { + warnings.push(format!( + "no boot entry matched the restored modules; using {}", + chosen.file_name + )); + } + + // 5. Write the current, previous and recovery entries. + let current = chosen + .with_root_subvol(&plan.root_subvol) + .map_err(|e| ExecError::operation("rollback", "rewrite current entry", e))? + .with_title("Phoebus OS"); + write_entry(&entries_dir, "phoebus-current.conf", ¤t)?; + + let newest = entries.iter().max_by_key(|e| { + e.kernel_version() + .map(|v| phoebus_core::boot::version_key(&v)) + }); + if let Some(previous) = newest { + let previous = previous.with_title("Phoebus OS (previous)"); + write_entry(&entries_dir, "phoebus-previous.conf", &previous)?; + } + + let recovery = chosen + .with_root_subvol(&snapshot_top_level_path(&plan.target_snapshot)) + .map_err(|e| ExecError::operation("rollback", "rewrite recovery entry", e))? + .with_option("systemd.unit=rescue.target") + .with_title("Phoebus Recovery"); + write_entry(&entries_dir, "phoebus-recovery.conf", &recovery)?; + + // 6. Make the restored root the default, for both the explicit argument and + // a mount without one. + set_default(exec, stage, &plan.root_subvol)?; + if let Some(var) = &plan.var_subvol { + let _ = set_default(exec, stage, var); + } + write_loader_default(&esp, "phoebus-current.conf")?; + + // 7. Flush so a forced poweroff right after activation cannot lose the + // rewritten fstab or boot entries. + exec.run(CommandSpec::new("rollback", "flush restored root", "sync"))?; + Ok(()) +} + +fn write_entry(dir: &Path, name: &str, entry: &BlsEntry) -> Result<()> { + std::fs::create_dir_all(dir).map_err(|e| ExecError::io(dir.to_path_buf(), e))?; + let path = dir.join(name); + std::fs::write(&path, entry.render()).map_err(|e| ExecError::io(path, e)) +} + +fn set_default(exec: &Exec, stage: &Path, subvol: &str) -> Result<()> { + let out = exec.run_capture( + CommandSpec::new("rollback", "list subvolumes", "btrfs") + .args(["subvolume", "list", "-o"]) + .arg(stage.to_string_lossy().to_string()), + )?; + let Some(id) = subvol_id_for_path(&out.stdout_lossy(), subvol) else { + exec.logger + .warn(format!("subvolume {subvol} not found for set-default")); + return Ok(()); + }; + exec.run( + CommandSpec::new("rollback", "set default subvolume", "btrfs") + .args(["subvolume", "set-default", &id]) + .arg(stage.to_string_lossy().to_string()), + )?; + Ok(()) +} + +fn write_loader_default(esp: &Path, entry: &str) -> Result<()> { + let dir = esp.join("loader"); + std::fs::create_dir_all(&dir).map_err(|e| ExecError::io(dir.clone(), e))?; + let text = format!( + "# systemd-boot configuration\ndefault {entry}\ntimeout 5\nconsole-mode keep\neditor no\n" + ); + let path = dir.join("loader.conf"); + std::fs::write(&path, text).map_err(|e| ExecError::io(path, e)) +} + +/// Detect the environment from the running system and perform a rollback. +pub fn execute( + exec: &Exec, + auth: &DestructiveAuthorization, + root: &Path, + snapshot_id: Option<&str>, +) -> Result { + let mounts = std::fs::read_to_string("/proc/self/mounts") + .map_err(|e| ExecError::io(PathBuf::from("/proc/self/mounts"), e))?; + let env = detect_env(&mounts)?; + let history = snapshot::read_history(root)?; + let ts = now_unix(); + let plan = plan(root, &history, snapshot_id, ts)?; + exec.logger.info(format!( + "rollback target {} -> {} (reason: {})", + plan.target_snapshot, plan.root_subvol, plan.reason + )); + let outcome = run_with_env(exec, auth, root, &env, &plan)?; + // Bound the recovery points now that the new root is selected. + let protect = outcome.state.protected_subvols(); + if let Err(e) = + snapshot::apply_retention_with(exec, auth, root, DEFAULT_KEEP_SNAPSHOTS, &protect) + { + exec.logger.warn(format!("snapshot retention failed: {e}")); + } + Ok(outcome) +} + +/// Mark an activated rollback as verified once the restored root is mounted. +pub fn verify(exec: &Exec, root: &Path) -> Result { + let mut state = load_state(root); + if state.status != RollbackStatus::Activated { + return Ok(state); + } + let mounts = std::fs::read_to_string("/proc/self/mounts").unwrap_or_default(); + let current = current_root_subvol(&mounts); + if current.as_deref() == Some(state.root_subvol.as_str()) { + state.status = RollbackStatus::Verified; + state.finished_unix = now_unix(); + state.note = format!("verified on {}", state.root_subvol); + save_state(exec, root, &state)?; + exec.logger.info("rollback verified on the restored root"); + if let Err(e) = snapshot::apply_retention_with( + exec, + &authorize_internal("verify"), + root, + DEFAULT_KEEP_SNAPSHOTS, + &state.protected_subvols(), + ) { + exec.logger + .warn(format!("post-verify retention failed: {e}")); + } + } + Ok(state) +} + +/// The root subvolume currently mounted at `/`, from `/proc/self/mounts` text. +pub fn current_root_subvol(mounts: &str) -> Option { + for line in mounts.lines() { + let fields: Vec<&str> = line.split_whitespace().collect(); + if fields.len() >= 4 && fields[1] == "/" { + for token in fields[3].split(',') { + if let Some(v) = token.strip_prefix("subvol=") { + return Some(v.trim_start_matches('/').to_string()); + } + } + } + } + None +} + +/// A token for internal maintenance that is not user-facing. +fn authorize_internal(reason: &str) -> DestructiveAuthorization { + crate::auth::authorize(&crate::auth::AutoConfirm, "rollback", reason) + .expect("auto-confirm never fails") +} + +fn now_unix() -> u64 { + std::time::SystemTime::now() + .duration_since(std::time::UNIX_EPOCH) + .map(|d| d.as_secs()) + .unwrap_or(0) +} + +/// The names of root generations that retention should prune. Kept here so the +/// policy is one place. +pub fn root_generation_deletions( + generations: &[String], + keep: usize, + protect: &[String], +) -> Vec { + snapshot_retention_deletions( + &SnapshotHistory { + records: generations + .iter() + .map(|g| phoebus_core::snapshot::SnapshotRecord { + id: g.clone(), + created_unix: 0, + operation: String::new(), + source_subvol: "@".into(), + snapshot_subvol: g.clone(), + var_snapshot: None, + status: SnapshotStatus::Committed, + }) + .collect(), + }, + keep, + protect, + ) +} + +/// The pre-rollback safety snapshot names for a timestamp (used by tests and +/// diagnostics). +pub fn safety_names(ts: u64) -> (String, String) { + ( + pre_rollback_snapshot_name(ts), + phoebus_core::rollback::pre_rollback_var_snapshot_name(ts), + ) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::command::RecordingRunner; + use crate::log::Logger; + use phoebus_core::snapshot::SnapshotRecord; + use phoebus_core::Redactor; + + fn make_exec(runner: RecordingRunner) -> Exec { + let path = tempfile::tempdir().unwrap().keep(); + let logger = Logger::open(path.join("l.log"), Redactor::new(), false); + Exec::new(Box::new(runner), logger, false, path.join("root"), path) + } + + fn committed(id: &str, var: Option<&str>) -> SnapshotRecord { + SnapshotRecord { + id: id.into(), + created_unix: 1_700_000_000, + operation: "sys update".into(), + source_subvol: "@".into(), + snapshot_subvol: id.into(), + var_snapshot: var.map(|v| v.to_string()), + status: SnapshotStatus::Committed, + } + } + + fn auth() -> crate::auth::DestructiveAuthorization { + crate::auth::authorize(&crate::auth::AutoConfirm, "p", "f").unwrap() + } + + #[test] + fn detect_env_finds_device_and_esp() { + let mounts = + "/dev/mapper/cryptroot / btrfs rw,subvol=/@ 0 0\n/dev/vda1 /efi vfat umask=0077 0 0\n"; + let env = detect_env(mounts).unwrap(); + assert_eq!(env.root_device, "/dev/mapper/cryptroot"); + assert_eq!(env.esp_mount, "/efi"); + assert!(detect_env("proc /proc proc rw 0 0\n").is_err()); + } + + #[test] + fn plan_refuses_uncommitted_and_missing() { + let runner = RecordingRunner::new(); + let exec = make_exec(runner); + let root = Path::new(&exec.root); + let history = SnapshotHistory { + records: vec![SnapshotRecord { + status: SnapshotStatus::Created, + ..committed("@-x", None) + }], + }; + assert!(plan(root, &history, None, 1).is_err()); + let history = SnapshotHistory { + records: vec![committed("@-x", Some("@var-x"))], + }; + std::fs::create_dir_all(snapshot::snapshots_path(root).join("@-x")).unwrap(); + let p = plan(root, &history, Some("@-x"), 1_700_000_000).unwrap(); + assert_eq!(p.root_subvol, "@restore-20231114T221320"); + assert_eq!(p.var_subvol.as_deref(), Some("@varrestore-20231114T221320")); + assert!(plan(root, &history, Some("@missing"), 1).is_err()); + } + + #[test] + fn activate_rewrites_fstab_and_boot_entries() { + let runner = RecordingRunner::new(); + let exec = make_exec(runner.clone()); + let root = Path::new(&exec.root); + let ts = 1_700_000_000u64; + let plan = RollbackPlan { + target_snapshot: "@-20231114T221320-sys-update".into(), + target_var_snapshot: Some("@var-20231114T221320-sys-update".into()), + root_subvol: restore_root_name(ts), + var_subvol: Some(restore_var_name(ts)), + previous_root: "@".into(), + ts, + reason: "sys update".into(), + }; + // Simulate the state a real clone would have on the staging mount. + let stage = exec.state_dir.join("rollback-stage"); + let restored = stage.join(&plan.root_subvol); + std::fs::create_dir_all(restored.join("etc")).unwrap(); + std::fs::create_dir_all(restored.join("lib/modules/6.12.9")).unwrap(); + std::fs::write( + restored.join("etc/fstab"), + "/dev/mapper/cryptroot\t/\tbtrfs\tnoatime,subvol=@\t0\t1\n\ + /dev/mapper/cryptroot\t/var\tbtrfs\tnoatime,subvol=@var\t0\t2\n", + ) + .unwrap(); + // ESP entries, including a newer kernel with no modules in the restore. + let entries = root.join("efi/loader/entries"); + std::fs::create_dir_all(&entries).unwrap(); + std::fs::write( + entries.join("id-6.12.9.conf"), + "title Gentoo Linux\nlinux /id/6.12.9/linux\ninitrd /id/6.12.9/initrd\noptions root=/dev/mapper/cryptroot rootflags=subvol=@ rw\n", + ) + .unwrap(); + std::fs::write( + entries.join("id-6.12.10.conf"), + "title Gentoo Linux\nlinux /id/6.12.10/linux\ninitrd /id/6.12.10/initrd\noptions root=/dev/mapper/cryptroot rootflags=subvol=@ rw\n", + ) + .unwrap(); + + let env = RollbackEnv { + root_device: "/dev/mapper/cryptroot".into(), + esp_mount: "/efi".into(), + }; + let mut warnings = Vec::new(); + activate(&exec, root, &env, &plan, &stage, &mut warnings).unwrap(); + + // fstab inside the restored root points at its own generation. + let fstab = std::fs::read_to_string(restored.join("etc/fstab")).unwrap(); + assert!(fstab.contains(&format!("subvol={}\t0\t1", plan.root_subvol))); + assert!(fstab.contains(&format!( + "subvol={}\t0\t2", + plan.var_subvol.clone().unwrap() + ))); + + // The current entry selects the new root and the matching kernel. + let current = std::fs::read_to_string(entries.join("phoebus-current.conf")).unwrap(); + assert!(current.contains("title Phoebus OS\n")); + assert!(current.contains(&format!("rootflags=subvol={}", plan.root_subvol))); + assert!(current.contains("/id/6.12.9/linux")); + // A previous entry is retained for a known-good boot choice. + let previous = std::fs::read_to_string(entries.join("phoebus-previous.conf")).unwrap(); + assert!(previous.contains("Phoebus OS (previous)")); + assert!(previous.contains("subvol=@ ")); + // Recovery boots the snapshot directly into rescue. + let recovery = std::fs::read_to_string(entries.join("phoebus-recovery.conf")).unwrap(); + assert!(recovery.contains(&format!( + "subvol={}", + snapshot_top_level_path(&plan.target_snapshot) + ))); + assert!(recovery.contains("systemd.unit=rescue.target")); + + // loader.conf defaults to the new entry, and the top level was unmounted. + let loader = std::fs::read_to_string(root.join("efi/loader/loader.conf")).unwrap(); + assert!(loader.contains("default phoebus-current.conf")); + let recorded = runner.recorded(); + let programs: Vec<&str> = recorded.iter().map(|s| s.program.as_str()).collect(); + assert!(programs.contains(&"sync")); + } + + #[test] + fn activate_refuses_to_clobber_an_existing_generation() { + let runner = RecordingRunner::new(); + let exec = make_exec(runner); + let root = Path::new(&exec.root); + let plan = RollbackPlan { + target_snapshot: "@-x".into(), + target_var_snapshot: None, + root_subvol: "@restore-20231114T221320".into(), + var_subvol: None, + previous_root: "@".into(), + ts: 1_700_000_000, + reason: "x".into(), + }; + let stage = exec.state_dir.join("rollback-stage"); + std::fs::create_dir_all(stage.join(&plan.root_subvol)).unwrap(); + let mut warnings = Vec::new(); + let err = activate( + &exec, + root, + &RollbackEnv { + root_device: "/dev/x".into(), + esp_mount: "/efi".into(), + }, + &plan, + &stage, + &mut warnings, + ) + .unwrap_err(); + assert!(err.to_string().contains("already exists")); + } + + #[test] + fn subvol_id_parsing() { + let listing = "ID 256 gen 10 top level 5 path @\nID 300 gen 11 top level 5 path @restore-20231114T221320\n"; + assert_eq!( + subvol_id_for_path(listing, "@restore-20231114T221320").as_deref(), + Some("300") + ); + assert!(subvol_id_for_path(listing, "@missing").is_none()); + } + + #[test] + fn verify_marks_activated_rollback_when_root_matches() { + // current_root_subvol is a pure parser and can be checked directly. + let mounts = "/dev/mapper/cryptroot / btrfs rw,subvol=/@restore-20231114T221320 0 0\n"; + assert_eq!( + current_root_subvol(mounts).as_deref(), + Some("@restore-20231114T221320") + ); + } + + #[test] + fn safety_names_pair_root_and_var() { + let (root, var) = safety_names(1_700_000_000); + assert!(root.starts_with("@-")); + assert!(var.starts_with("@var-")); + let _ = auth(); + } +} diff --git a/installer-rs/crates/phoebus-executor/src/sandbox.rs b/installer-rs/crates/phoebus-executor/src/sandbox.rs new file mode 100644 index 0000000..5bea49c --- /dev/null +++ b/installer-rs/crates/phoebus-executor/src/sandbox.rs @@ -0,0 +1,132 @@ +//! OS-level isolation for model execution. +//! +//! Typed schemas and privacy filters constrain *what* the model may ask for, but +//! they do not stop a compromised or malicious provider endpoint from reaching +//! the filesystem, the home directory, or privilege. The network call is +//! therefore executed inside a hardened, unprivileged transient systemd unit: +//! a dynamic user, no home access, a read-only system, no new privileges, and a +//! restricted syscall/address-family set. The model never runs as root and can +//! never read a private file. +//! +//! The argument builder is pure so the exact sandbox is unit-testable without a +//! running systemd. + +use std::path::Path; + +use crate::command::CommandSpec; +use crate::error::{ExecError, Result}; +use crate::exec::Exec; + +/// The hardening properties applied to the model-call unit. +pub const SANDBOX_PROPERTIES: &[&str] = &[ + "DynamicUser=yes", + "ProtectSystem=strict", + "ProtectHome=yes", + "PrivateDevices=yes", + "PrivateTmp=yes", + "NoNewPrivileges=yes", + "ProtectKernelTunables=yes", + "ProtectKernelModules=yes", + "ProtectControlGroups=yes", + "RestrictNamespaces=yes", + "LockPersonality=yes", + "MemoryDenyWriteExecute=yes", + "SystemCallArchitectures=native", + "RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6", + "SystemCallFilter=@system-service", +]; + +/// Whether `systemd-run` is available to build the boundary. +pub fn available() -> bool { + crate::exec::find_in_path("systemd-run").is_some() +} + +/// The argv for `systemd-run` that runs `program args` inside the sandbox. +pub fn argv(program: &str, args: &[String]) -> Vec { + let mut out: Vec = vec![ + "--quiet".into(), + "--wait".into(), + "--pipe".into(), + "--collect".into(), + "--service-type=exec".into(), + ]; + for property in SANDBOX_PROPERTIES { + out.push(format!("--property={property}")); + } + out.push(program.to_string()); + out.extend(args.iter().cloned()); + out +} + +/// Run a program inside the model sandbox, reading the hidden `stdin` payload. +/// +/// Fails closed when `systemd-run` is unavailable: an unisolated model call is +/// refused rather than silently run with full access. +pub fn run( + exec: &Exec, + program: &str, + args: &[String], + stdin: Vec, +) -> Result { + if !available() { + return Err(ExecError::MissingTool( + "systemd-run (required for the AI sandbox; refusing to run the model unisolated)" + .into(), + )); + } + exec.run( + CommandSpec::new("ai", "query model (sandboxed)", "systemd-run") + .args(argv(program, args)) + .stdin(stdin), + ) +} + +/// Whether a path is safe to expose to the sandboxed process (never a home or +/// credential path). +pub fn path_is_exposable(path: &Path) -> bool { + let text = path.to_string_lossy(); + !phoebus_ai::privacy::is_forbidden_path(&text) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn argv_contains_the_hardening_properties() { + let args = argv("curl", &["-sS".into(), "-K".into(), "-".into()]); + assert!(args.iter().any(|a| a == "--quiet")); + assert!(args.iter().any(|a| a == "--wait")); + assert!(args.iter().any(|a| a.contains("DynamicUser=yes"))); + assert!(args.iter().any(|a| a.contains("ProtectHome=yes"))); + assert!(args.iter().any(|a| a.contains("NoNewPrivileges=yes"))); + assert!(args.iter().any(|a| a.contains("ProtectSystem=strict"))); + assert!(args.iter().any(|a| a.contains("RestrictAddressFamilies="))); + // The wrapped program and its arguments come last. + let pos = args.iter().position(|a| a == "curl").unwrap(); + assert_eq!(&args[pos + 1..], &["-sS", "-K", "-"]); + } + + #[test] + fn run_fails_closed_without_systemd_run() { + // In this environment systemd-run may or may not exist; if it does not, + // run must refuse. If it does, the refusal path is covered by argv. + if available() { + return; + } + let runner = crate::command::RecordingRunner::new(); + let dir = tempfile::tempdir().unwrap().keep(); + let logger = + crate::log::Logger::open(dir.join("l.log"), phoebus_core::Redactor::new(), false); + let exec = Exec::new(Box::new(runner), logger, false, dir.join("root"), dir); + let err = run(&exec, "curl", &[], Vec::new()).unwrap_err(); + assert!(matches!(err, ExecError::MissingTool(_))); + } + + #[test] + fn private_paths_are_not_exposable() { + assert!(!path_is_exposable(Path::new("/home/alice/.ssh/id_rsa"))); + assert!(!path_is_exposable(Path::new("/root/.gnupg/secring.gpg"))); + assert!(path_is_exposable(Path::new("/etc/nix/nix.conf"))); + } +} diff --git a/installer-rs/crates/phoebus-executor/src/snapshot.rs b/installer-rs/crates/phoebus-executor/src/snapshot.rs index 8e3d1e6..98ec237 100644 --- a/installer-rs/crates/phoebus-executor/src/snapshot.rs +++ b/installer-rs/crates/phoebus-executor/src/snapshot.rs @@ -11,6 +11,9 @@ use std::path::{Path, PathBuf}; +use phoebus_core::rollback::{ + snapshot_retention_deletions, DEFAULT_KEEP_SNAPSHOTS, MIN_FREE_SPACE_BYTES, +}; use phoebus_core::snapshot::{snapshot_name, SnapshotHistory, SnapshotRecord, SnapshotStatus}; use crate::auth::DestructiveAuthorization; @@ -20,6 +23,8 @@ use crate::exec::Exec; pub const SNAPSHOT_DIR: &str = ".snapshots"; pub const HISTORY_REL: &str = "var/lib/phoebus/snapshot-history.toml"; +/// The separately mounted `/var` subvolume holding package-manager state. +pub const VAR_SUBVOL: &str = "@var"; pub fn snapshots_path(root: &Path) -> PathBuf { root.join(SNAPSHOT_DIR) @@ -89,20 +94,141 @@ pub fn create( operation: operation.to_string(), source_subvol: source_subvol.to_string(), snapshot_subvol: name, + var_snapshot: None, status: SnapshotStatus::Created, }; Ok(record) } -/// Create a snapshot and record it as committed in the history. -pub fn create_and_record( +/// Create a read-only snapshot of one source subvolume by explicit name. +pub fn create_named( + exec: &Exec, + _auth: &DestructiveAuthorization, + root: &Path, + source_subvol: &str, + name: &str, +) -> Result<()> { + let dir = snapshots_path(root); + std::fs::create_dir_all(&dir).map_err(|e| ExecError::io(dir.clone(), e))?; + let dest = dir.join(name); + exec.run( + CommandSpec::new("snapshot", format!("create snapshot {name}"), "btrfs") + .args(["subvolume", "snapshot", "-r"]) + .arg(source_subvol) + .arg(dest.to_string_lossy().to_string()), + )?; + Ok(()) +} + +/// Snapshot the mounted root and, when `/var` is a separate Btrfs subvolume, +/// its `/var` volume under the same timestamp/operation name. +/// +/// `/home` is intentionally excluded so a system rollback cannot discard user +/// documents. +pub fn create_set( exec: &Exec, auth: &DestructiveAuthorization, root: &Path, source_subvol: &str, operation: &str, ) -> Result { - let mut record = create(exec, auth, root, source_subvol, operation)?; + let var_source = if var_is_separate_subvol(root) { + Some("/var") + } else { + None + }; + create_set_at(exec, auth, root, source_subvol, var_source, operation) +} + +/// As `create_set`, but with an explicit `/var` source so the installer can +/// capture the target's `@var` (whose mount point is not the host `/var`). +pub fn create_set_at( + exec: &Exec, + auth: &DestructiveAuthorization, + root: &Path, + source_subvol: &str, + var_source: Option<&str>, + operation: &str, +) -> Result { + let unix = now_unix(); + let name = snapshot_name("@", unix, operation); + create_named(exec, auth, root, source_subvol, &name)?; + let var_snapshot = match var_source { + Some(source) => { + let var_name = snapshot_name("@var", unix, operation); + create_named(exec, auth, root, source, &var_name)?; + Some(var_name) + } + None => None, + }; + Ok(SnapshotRecord { + id: name.clone(), + created_unix: unix, + operation: operation.to_string(), + source_subvol: source_subvol.to_string(), + snapshot_subvol: name, + var_snapshot, + status: SnapshotStatus::Created, + }) +} + +/// Whether `/var` is a separate Btrfs subvolume of the running system. +/// +/// `/home` and `/var` are separate subvolumes in the proven layout. A target +/// root that is not the running `/` (the installer) has no separate `/var`, and +/// tests use a temporary directory, so this is false there. +pub fn var_is_separate_subvol(root: &Path) -> bool { + if root != Path::new("/") { + return false; + } + match std::fs::read_to_string("/proc/self/mountinfo") { + Ok(text) => parse_mountinfo_var(&text), + Err(_) => false, + } +} + +/// Pure parser used by `var_is_separate_subvol` so the decision is testable. +pub fn parse_mountinfo_var(text: &str) -> bool { + for line in text.lines() { + // mountinfo: id parent maj:min root mountpoint opts... - fstype source ... + let fields: Vec<&str> = line.split_whitespace().collect(); + let Some(sep) = fields.iter().position(|f| *f == "-") else { + continue; + }; + let mountpoint = fields.get(4).copied(); + let fstype = fields.get(sep + 1).copied(); + if mountpoint == Some("/var") && fstype == Some("btrfs") { + return true; + } + } + false +} + +/// Create a snapshot set and record it as committed in the history. +pub fn create_set_and_record( + exec: &Exec, + auth: &DestructiveAuthorization, + root: &Path, + source_subvol: &str, + operation: &str, +) -> Result { + create_set_and_record_at(exec, auth, root, source_subvol, None, operation) +} + +/// As `create_set_and_record`, with an explicit `/var` source (installer). +pub fn create_set_and_record_at( + exec: &Exec, + auth: &DestructiveAuthorization, + root: &Path, + source_subvol: &str, + var_source: Option<&str>, + operation: &str, +) -> Result { + let mut record = if var_source.is_some() { + create_set_at(exec, auth, root, source_subvol, var_source, operation)? + } else { + create_set(exec, auth, root, source_subvol, operation)? + }; record.status = SnapshotStatus::Committed; let mut history = read_history(root)?; history.append(record.clone()); @@ -112,6 +238,20 @@ pub fn create_and_record( Ok(record) } +/// Create a snapshot and record it as committed in the history. +/// +/// This captures the root and the separately mounted `/var` together so a +/// restored system has consistent package-manager state. +pub fn create_and_record( + exec: &Exec, + auth: &DestructiveAuthorization, + root: &Path, + source_subvol: &str, + operation: &str, +) -> Result { + create_set_and_record(exec, auth, root, source_subvol, operation) +} + pub fn list(_exec: &Exec, root: &Path) -> Result> { let dir = snapshots_path(root); if !dir.is_dir() { @@ -136,6 +276,93 @@ pub fn delete(exec: &Exec, _auth: &DestructiveAuthorization, root: &Path, id: &s Ok(()) } +/// Parse the available-bytes figure from `df -B1 --output=avail` output. +pub fn parse_df_avail(text: &str) -> Option { + text.lines() + .rev() + .find_map(|line| line.trim().parse::().ok()) +} + +/// Free bytes on the filesystem backing `path`, or an error if it cannot be +/// determined. A rollback refuses to run when space cannot be checked. +pub fn free_space_bytes(exec: &Exec, path: &Path) -> Result { + let out = exec.run_capture( + CommandSpec::new("snapshot", "check free space", "df") + .args(["-B1", "--output=avail"]) + .arg(path.to_string_lossy().to_string()), + )?; + parse_df_avail(&out.stdout_lossy()).ok_or_else(|| { + ExecError::operation( + "snapshot", + "check free space", + format!("could not parse df output for {}", path.display()), + ) + }) +} + +/// Require at least `min_bytes` free before a space-consuming operation. +pub fn require_free_space(exec: &Exec, path: &Path, min_bytes: u64) -> Result { + let avail = free_space_bytes(exec, path)?; + if avail < min_bytes { + return Err(ExecError::operation( + "snapshot", + "check free space", + format!( + "only {avail} bytes free on {}; {min_bytes} required", + path.display() + ), + )); + } + Ok(avail) +} + +/// Prune committed snapshots beyond `keep`, protecting the latest and any +/// in-flight rollback target. Returns the ids that were deleted. +pub fn apply_retention( + exec: &Exec, + auth: &DestructiveAuthorization, + root: &Path, +) -> Result> { + apply_retention_with(exec, auth, root, DEFAULT_KEEP_SNAPSHOTS, &[]) +} + +pub fn apply_retention_with( + exec: &Exec, + auth: &DestructiveAuthorization, + root: &Path, + keep: usize, + protect: &[String], +) -> Result> { + let history = read_history(root)?; + let deletions = snapshot_retention_deletions(&history, keep, protect); + if deletions.is_empty() { + return Ok(Vec::new()); + } + for id in &deletions { + if let Some(record) = history.records.iter().find(|r| &r.id == id) { + if let Some(var) = &record.var_snapshot { + let _ = delete(exec, auth, root, var); + } + } + delete(exec, auth, root, id)?; + exec.logger.info(format!("pruned snapshot {id}")); + } + // Drop the pruned records from the history so it stays truthful. + let mut pruned = SnapshotHistory::default(); + for record in history.records { + if !deletions.contains(&record.id) { + pruned.append(record); + } + } + write_history(root, &pruned)?; + Ok(deletions) +} + +/// The minimum free space a rollback requires. +pub fn rollback_space_requirement() -> u64 { + MIN_FREE_SPACE_BYTES +} + #[cfg(test)] mod tests { use super::*; @@ -187,4 +414,80 @@ mod tests { let lossy = read_history_lossy(&exec, Path::new(&exec.root)); assert!(lossy.records.is_empty()); } + + #[test] + fn coordinated_snapshot_captures_var_when_explicit() { + let runner = RecordingRunner::new(); + let exec = make_exec(runner.clone()); + let auth = crate::auth::authorize(&crate::auth::AutoConfirm, "p", "f").unwrap(); + let record = create_set_at( + &exec, + &auth, + Path::new(&exec.root), + "/mnt/phoebus", + Some("/mnt/phoebus/var"), + "sys update", + ) + .unwrap(); + assert!(record.var_snapshot.is_some()); + let args: Vec = runner + .recorded() + .iter() + .flat_map(|s| s.args.clone()) + .collect(); + assert!(args.iter().any(|a| a.contains("@var"))); + } + + #[test] + fn df_avail_parser_takes_the_last_numeric_line() { + assert_eq!(parse_df_avail("Avail\n1073741824\n"), Some(1_073_741_824)); + assert_eq!(parse_df_avail("10\n20\n30\n"), Some(30)); + assert_eq!(parse_df_avail("no numbers here\n"), None); + } + + #[test] + fn mountinfo_detects_a_separate_var() { + let line = "25 30 0:23 / /var rw,relatime - btrfs /dev/vda2 rw,subvolid=258,subvol=/@var"; + assert!(parse_mountinfo_var(line)); + assert!(!parse_mountinfo_var( + "1 0 8:1 / / ext4 rw - ext4 /dev/sda1 rw" + )); + } + + #[test] + fn retention_prunes_old_committed_and_rewrites_history() { + let runner = RecordingRunner::new(); + let exec = make_exec(runner.clone()); + let auth = crate::auth::authorize(&crate::auth::AutoConfirm, "p", "f").unwrap(); + let root = Path::new(&exec.root); + let mut history = SnapshotHistory::default(); + for i in 0..4u64 { + history.append(SnapshotRecord { + id: format!("@-{i}"), + created_unix: i, + operation: "op".into(), + source_subvol: "@".into(), + snapshot_subvol: format!("@-{i}"), + var_snapshot: Some(format!("@var-{i}")), + status: SnapshotStatus::Committed, + }); + } + // Materialise the snapshot directories so existence is realistic. + let dir = snapshots_path(root); + for i in 0..4u64 { + std::fs::create_dir_all(dir.join(format!("@-{i}"))).unwrap(); + std::fs::create_dir_all(dir.join(format!("@var-{i}"))).unwrap(); + } + write_history(root, &history).unwrap(); + let deletions = apply_retention_with(&exec, &auth, root, 2, &[]).unwrap(); + assert_eq!(deletions, vec!["@-0", "@-1"]); + let after = read_history(root).unwrap(); + assert_eq!(after.records.len(), 2); + assert!(!after.records.iter().any(|r| r.id == "@-0")); + } + + #[test] + fn space_and_retention_constants_are_sane() { + assert!(rollback_space_requirement() >= 512 * 1024 * 1024); + } } diff --git a/installer-rs/crates/phoebus-executor/src/transaction.rs b/installer-rs/crates/phoebus-executor/src/transaction.rs new file mode 100644 index 0000000..9261530 --- /dev/null +++ b/installer-rs/crates/phoebus-executor/src/transaction.rs @@ -0,0 +1,61 @@ +//! Persisted transaction log for assistant and `sys` actions. + +use std::path::{Path, PathBuf}; + +use phoebus_core::transaction::{TransactionLog, TransactionRecord}; + +use crate::error::{ExecError, Result}; +use crate::exec::Exec; + +pub const TRANSACTIONS_REL: &str = "var/lib/phoebus/transactions.toml"; + +pub fn path(root: &Path) -> PathBuf { + root.join(TRANSACTIONS_REL) +} + +pub fn read(root: &Path) -> Result { + TransactionLog::load(&path(root)).map_err(ExecError::Core) +} + +pub fn append(exec: &Exec, root: &Path, record: TransactionRecord) -> Result<()> { + let mut log = read(root)?; + log.append(record); + log.save(&path(root)).map_err(ExecError::Core)?; + exec.logger.info("recorded transaction"); + Ok(()) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::command::RecordingRunner; + use crate::log::Logger; + use phoebus_core::Redactor; + + #[test] + fn append_persists_to_the_target() { + let path = tempfile::tempdir().unwrap().keep(); + let logger = Logger::open(path.join("l.log"), Redactor::new(), false); + let exec = Exec::new( + Box::new(RecordingRunner::new()), + logger, + false, + path.join("root"), + path, + ); + let root = Path::new(&exec.root); + append( + &exec, + root, + TransactionRecord { + origin: "sys".into(), + summary: "test".into(), + ..Default::default() + }, + ) + .unwrap(); + let log = read(root).unwrap(); + assert_eq!(log.records.len(), 1); + assert_eq!(log.records[0].origin, "sys"); + } +} 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 09a2789..a53dc88 100644 --- a/installer-rs/crates/phoebus-installer/src/bin/phoebus-release.rs +++ b/installer-rs/crates/phoebus-installer/src/bin/phoebus-release.rs @@ -9,7 +9,8 @@ use std::process::ExitCode; use clap::{Parser, Subcommand}; use phoebus_core::VERSION; use phoebus_installer::release::{ - artifact_for, default_manifest_path, sha256_file, ReleaseManifest, + artifact_for, atomic_publish, default_manifest_path, run_gates, sha256_file, sign_command, + verify_signature_command, GateReport, ReleaseManifest, }; #[derive(Parser)] @@ -50,6 +51,27 @@ 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. + Gates { + #[arg(long, default_value = "gate-report.json")] + output: PathBuf, + #[arg(long)] + execute: bool, + }, + /// Publish a candidate atomically, refusing unless a passing gate report is + /// supplied. The previous release is preserved. + Publish { + candidate: PathBuf, + dest: PathBuf, + #[arg(long)] + gate_report: PathBuf, + }, + /// Print the signing command for an artifact (key outside the repository). + Sign { artifact: PathBuf, key: PathBuf }, + /// Print the signature-verification command for an artifact. + VerifySignature { artifact: PathBuf }, /// Print the sha256 of a single file. Sha256 { file: PathBuf }, } @@ -141,5 +163,58 @@ fn run() -> std::result::Result<(), Box> { println!("{}", sha256_file(&file)?); Ok(()) } + Command::Gates { output, execute } => { + let report = run_gates(execute); + 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() + ); + if !execute { + eprintln!( + "note: gates were not executed; pass --execute on a configured runner \ + to run them" + ); + } + Ok(()) + } + Command::Publish { + candidate, + dest, + gate_report, + } => { + 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)?; + println!("published {} -> {}", candidate.display(), dest.display()); + Ok(()) + } + Command::Sign { artifact, key } => { + println!("{}", sign_command(&artifact, &key).join(" ")); + eprintln!("note: signing keys must live outside the repository and model context"); + Ok(()) + } + Command::VerifySignature { artifact } => { + println!("{}", verify_signature_command(&artifact).join(" ")); + Ok(()) + } } } diff --git a/installer-rs/crates/phoebus-installer/src/bin/sys.rs b/installer-rs/crates/phoebus-installer/src/bin/sys.rs index cca33f9..29d89df 100644 --- a/installer-rs/crates/phoebus-installer/src/bin/sys.rs +++ b/installer-rs/crates/phoebus-installer/src/bin/sys.rs @@ -10,11 +10,14 @@ use std::path::PathBuf; use std::process::ExitCode; use clap::Parser; +use phoebus_ai::assistant::{complete_plan, AssistantPlan}; +use phoebus_ai::provider::{ProviderKind, SystemFacts}; use phoebus_core::action::{parse_action, parse_natural, SystemAction}; -use phoebus_core::Redactor; +use phoebus_core::transaction::TransactionRecord; +use phoebus_core::{InstallConfig, Redactor}; use phoebus_executor::{ - actions, authorize, AutoConfirm, Confirmation, DestructiveAuthorization, Exec, Logger, - RealRunner, Result, + actions, authorize, probe, transaction, AutoConfirm, Confirmation, DestructiveAuthorization, + Exec, Logger, RealRunner, Result, }; #[derive(Parser, Debug)] @@ -38,6 +41,26 @@ struct Cli { /// Root directory of the target system. #[arg(long, default_value = "/")] root: PathBuf, + + /// AI provider for `sys ask`: deepseek, openai, or local. + #[arg(long, value_name = "PROVIDER")] + ai_provider: Option, + + /// Model override for the assistant. + #[arg(long, value_name = "MODEL")] + ai_model: Option, + + /// Provider endpoint override (local models). + #[arg(long, value_name = "URL")] + ai_endpoint: Option, + + /// Read the provider API key from a mode-0600 file. + #[arg(long, value_name = "FILE")] + ai_api_key_file: Option, + + /// Run the assistant without the OS-level sandbox (development only). + #[arg(long)] + no_sandbox: bool, } struct SysConfirm { @@ -92,24 +115,6 @@ fn main() -> ExitCode { fn run() -> std::result::Result<(), Box> { let cli = Cli::parse(); - let action = if let Some(json) = &cli.action { - parse_action(json)? - } else if let Some(path) = &cli.action_file { - let text = std::fs::read_to_string(path)?; - parse_action(&text)? - } else { - let phrase = cli.text.join(" "); - match parse_natural(&phrase) { - Some(a) => a, - None => { - eprintln!("sys: could not parse `{phrase}` deterministically."); - eprintln!("Examples: sys enable sshd | sys disable bluetooth | sys history"); - eprintln!("Or provide a typed action with --action/--action-file."); - return Err("unsupported instruction".into()); - } - } - }; - let mut state_dir = PathBuf::from("/run/phoebus-installer"); if std::fs::create_dir_all(&state_dir).is_err() { state_dir = std::env::temp_dir().join("phoebus-installer"); @@ -124,8 +129,51 @@ fn run() -> std::result::Result<(), Box> { state_dir, ); + // `sys ask ` is the conversational entry point; it proposes the + // same typed actions and executes them through the same broker. + if cli.text.first().map(String::as_str) == Some("ask") { + let instruction = cli.text[1..].join(" "); + if instruction.trim().is_empty() { + return Err("usage: sys ask ".into()); + } + return run_ask(&cli, &exec, &instruction); + } + + let action = if let Some(json) = &cli.action { + parse_action(json)? + } else if let Some(path) = &cli.action_file { + let text = std::fs::read_to_string(path)?; + parse_action(&text)? + } else { + let phrase = cli.text.join(" "); + match parse_natural(&phrase) { + Some(a) => a, + None => { + eprintln!("sys: could not parse `{phrase}` deterministically."); + eprintln!("Examples: sys enable sshd | sys disable bluetooth | sys history"); + eprintln!("Or ask the assistant: sys ask \"\""); + return Err("unsupported instruction".into()); + } + } + }; + println!("{}", actions::preview(&action)); + // Resolve concrete package effects (additions/upgrades/removals, source vs + // binary, download size) and bind the approval to that exact plan. A + // material change between review and execution aborts. + let approved = match actions::resolve_effects(&exec, &action, &cli.root) { + Ok(plan) if !plan.effects.is_empty() => { + println!("{}", plan.render()); + Some(plan) + } + Ok(_) => None, + Err(e) => { + eprintln!("sys: could not resolve effects ({e}); refusing to proceed unreviewed"); + return Err("effect resolution failed".into()); + } + }; + if action.is_mutating() && effective_uid() != 0 { return Err("mutating actions require root; run `sudo sys ...`".into()); } @@ -144,10 +192,11 @@ fn run() -> std::result::Result<(), Box> { None }; - // `actions::execute` creates a protective snapshot for high-risk actions - // and fails closed when the snapshots subvolume exists but creation fails, - // so there is a single, tested safety path. - let outcome = actions::execute(&exec, &action, auth.as_ref(), &cli.root)?; + // `actions::execute_checked` re-resolves and compares against the reviewed + // digest, creates a protective snapshot for high-risk actions, and fails + // closed when the snapshots subvolume exists but creation fails. + let outcome = + actions::execute_checked(&exec, &action, auth.as_ref(), &cli.root, approved.as_ref())?; if let Some(id) = &outcome.snapshot { println!("protective snapshot: {id}"); } @@ -155,6 +204,192 @@ fn run() -> std::result::Result<(), Box> { Ok(()) } +/// Bounded system facts for the assistant: hardware, selected profile and +/// measured compile times. No personal files, credentials or command history. +fn gather_facts(exec: &Exec) -> SystemFacts { + let config = InstallConfig::default(); + let hardware = probe::probe_hardware(exec.runner.as_ref()); + let history = phoebus_core::load_history(&exec.root.join("var/lib/phoebus/compile-times.tsv")); + let binhost = exec.root.join("etc/portage/binrepos.conf").exists(); + SystemFacts::from_system(&config, &hardware, &history, binhost, None) +} + +/// The provider selected on the command line or the environment. +fn resolve_provider(cli: &Cli) -> ProviderKind { + let raw = cli + .ai_provider + .clone() + .or_else(|| std::env::var("PHOEBUS_AI_PROVIDER").ok()) + .unwrap_or_default(); + ProviderKind::parse(&raw).unwrap_or(ProviderKind::None) +} + +fn resolve_endpoint(cli: &Cli, provider: ProviderKind) -> String { + cli.ai_endpoint + .clone() + .or_else(|| std::env::var("PHOEBUS_AI_ENDPOINT").ok()) + .filter(|s| !s.trim().is_empty()) + .unwrap_or_else(|| provider.endpoint().to_string()) +} + +fn resolve_model(cli: &Cli) -> String { + cli.ai_model + .clone() + .or_else(|| std::env::var("PHOEBUS_AI_MODEL").ok()) + .unwrap_or_default() +} + +fn api_key_file(cli: &Cli) -> Option { + cli.ai_api_key_file.clone().or_else(|| { + std::env::var("PHOEBUS_AI_API_KEY_FILE") + .ok() + .map(PathBuf::from) + }) +} + +/// Report the deterministic fallback when no model is available. The system is +/// never unusable without an assistant. +fn deterministic_fallback(instruction: &str) { + eprintln!("No model is connected. The deterministic interface still works:"); + match parse_natural(instruction) { + Some(action) => { + eprintln!(" sys {}", action.describe()); + eprintln!("Run it as: sys {}", instruction.trim()); + } + None => { + eprintln!(" Examples: sys enable sshd | sys install vim | sys history | sys undo"); + eprintln!(" A model only makes this easier; it is never required."); + } + } +} + +/// The assistant loop: gather facts -> propose validated actions -> show +/// effects -> approve/authenticate -> execute deterministically -> record. +fn run_ask( + cli: &Cli, + exec: &Exec, + instruction: &str, +) -> std::result::Result<(), Box> { + let provider = resolve_provider(cli); + if provider == ProviderKind::None { + deterministic_fallback(instruction); + return Err("no AI provider configured".into()); + } + let endpoint = resolve_endpoint(cli, provider); + let model = resolve_model(cli); + let key = match api_key_file(cli) { + Some(path) => Some(phoebus_executor::ai::load_api_key(&path)?), + None => None, + }; + if provider.requires_key() && key.is_none() { + deterministic_fallback(instruction); + return Err(format!( + "provider `{}` requires --ai-api-key-file (mode 0600)", + provider.as_str() + ) + .into()); + } + + let facts = gather_facts(exec); + eprintln!( + "Sending these bounded system facts to {} (no passwords, files or home directories):", + provider.as_str() + ); + eprintln!("{}", facts.render()); + + let transport = phoebus_executor::ai::CurlTransport::new(exec, key); + let transport = if cli.no_sandbox { + transport + } else { + transport.sandboxed() + }; + let plan: AssistantPlan = + match complete_plan(provider, &endpoint, &model, &facts, instruction, &transport) { + Ok(plan) => plan, + Err(e) => { + eprintln!("The model is unavailable or returned an unusable plan: {e}"); + deterministic_fallback(instruction); + return Err("model unavailable".into()); + } + }; + + println!("{}", plan.render()); + + // Resolve concrete effects and bind approval to the reviewed plan. + let mut approved = Vec::new(); + let mut mutating = false; + for action in &plan.actions { + let resolved = actions::resolve_effects(exec, action, &cli.root)?; + if !resolved.effects.is_empty() { + println!("{}", resolved.render()); + } + approved.push(resolved); + mutating |= action.is_mutating(); + } + + if mutating && effective_uid() != 0 { + return Err("this plan modifies the system; run `sudo sys ask ...`".into()); + } + let auth: Option = if mutating { + let confirmation = SysConfirm { + action: plan + .actions + .first() + .cloned() + .unwrap_or(SystemAction::History), + assume_yes: cli.yes, + }; + Some(authorize( + &confirmation, + &plan.render(), + "execute the assistant's plan", + )?) + } else { + None + }; + + let mut snapshot = None; + let mut result = String::from("ok"); + let mut executed = Vec::new(); + for (action, resolved) in plan.actions.iter().zip(approved.iter()) { + match actions::execute_checked(exec, action, auth.as_ref(), &cli.root, Some(resolved)) { + Ok(outcome) => { + if let Some(id) = &outcome.snapshot { + snapshot = Some(id.clone()); + } + executed.push(action.describe()); + println!("{}", outcome.output); + } + Err(e) => { + result = format!("failed: {e}"); + executed.push(action.describe()); + eprintln!("action failed: {e}"); + break; + } + } + } + + let record = TransactionRecord { + created_unix: std::time::SystemTime::now() + .duration_since(std::time::UNIX_EPOCH) + .map(|d| d.as_secs()) + .unwrap_or(0), + origin: "assistant".into(), + summary: plan.summary.clone(), + actions: executed, + result, + snapshot, + digest: approved + .iter() + .find(|p| !p.digest.is_empty()) + .map(|p| p.digest.clone()), + }; + if let Err(e) = transaction::append(exec, &cli.root, record) { + eprintln!("could not record the transaction: {e}"); + } + Ok(()) +} + #[allow(dead_code)] fn _auto() -> AutoConfirm { AutoConfirm diff --git a/installer-rs/crates/phoebus-installer/src/orchestrate.rs b/installer-rs/crates/phoebus-installer/src/orchestrate.rs index 284c8fe..80a63b8 100644 --- a/installer-rs/crates/phoebus-installer/src/orchestrate.rs +++ b/installer-rs/crates/phoebus-installer/src/orchestrate.rs @@ -8,11 +8,13 @@ use std::path::PathBuf; use phoebus_core::policy::{load_history, PackagePolicyEngine, PolicyContext}; use phoebus_core::validate::ValidationIssue; -use phoebus_core::{validate, HardwareReport, InstallConfig, InstallPlan, SecretString}; +use phoebus_core::{ + validate, Filesystem, HardwareReport, InstallConfig, InstallPlan, SecretString, +}; use phoebus_executor::storage::StorageState; use phoebus_executor::{ - boot, desktop, encryption, kernel, nix, portage, probe, services, stage3, storage, users, Exec, - Result, + boot, desktop, encryption, kernel, nix, portage, probe, services, snapshot, stage3, storage, + users, Exec, Result, }; pub struct Installer { @@ -268,6 +270,23 @@ impl Installer { .logger .warn(format!("getuto failed; binary verification may fail: {e}")); } + // The Mango desktop needs the git-only GURU overlay, so install git + // from the main tree first, then sync GURU. Signature verification + // stays on and the keyword set stays scoped. + if phoebus_core::system::uses_guru(&self.config) { + let bootstrap: Vec = portage::guru_bootstrap_packages() + .into_iter() + .map(str::to_string) + .collect(); + portage::emerge( + &self.exec, + &root, + &bootstrap, + &self.engine, + &self.policy_ctx, + )?; + portage::sync_guru(&self.exec, &root, &self.config)?; + } Ok(()) })(); self.exec.umount_chroot()?; @@ -459,6 +478,7 @@ impl Installer { .logger .warn(format!("could not write session script: {e}")); } + self.create_initial_recovery_point(auth); // Durability: Btrfs commits lazily (~30s) and the installer's writes // are not fsynced; flush before unmounting so a forced poweroff cannot // lose the final files (the session script and the exported log). @@ -483,4 +503,50 @@ impl Installer { self.exec.logger.info("installation finished"); Ok(()) } + + /// Capture an initial known-good snapshot and point a boot entry at it, so + /// recovery does not depend on the (possibly later broken) live root. + fn create_initial_recovery_point(&self, auth: &phoebus_executor::DestructiveAuthorization) { + if self.config.storage.filesystem != Filesystem::Btrfs + || !self + .config + .storage + .subvols + .iter() + .any(|s| s == "@snapshots") + { + return; + } + let root = std::path::PathBuf::from(&self.exec.root); + let root_str = root.to_string_lossy().to_string(); + let var_source = if self.config.storage.subvols.iter().any(|s| s == "@var") { + Some(root.join("var").to_string_lossy().to_string()) + } else { + None + }; + match snapshot::create_set_and_record_at( + &self.exec, + auth, + &root, + &root_str, + var_source.as_deref(), + "initial known-good", + ) { + Ok(record) => { + if let Err(e) = boot::write_snapshot_recovery_entry( + &self.exec, + &self.config, + &record.snapshot_subvol, + ) { + self.exec + .logger + .warn(format!("could not write snapshot recovery entry: {e}")); + } + } + Err(e) => self + .exec + .logger + .warn(format!("could not create initial recovery snapshot: {e}")), + } + } } diff --git a/installer-rs/crates/phoebus-installer/src/release.rs b/installer-rs/crates/phoebus-installer/src/release.rs index 8a76a05..389baf9 100644 --- a/installer-rs/crates/phoebus-installer/src/release.rs +++ b/installer-rs/crates/phoebus-installer/src/release.rs @@ -113,6 +113,225 @@ pub fn default_manifest_path(dir: &Path) -> PathBuf { dir.join("phoebus-release.json") } +// --------------------------------------------------------------------------- +// Candidate gates +// --------------------------------------------------------------------------- + +/// 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)] +#[serde(rename_all = "snake_case")] +pub enum GateRequirement { + /// Runs anywhere. + Host, + /// Needs the disposable QEMU/OVMF VM. + Vm, + /// Needs a graphical seat. + GraphicalSeat, + /// Needs a live model credential or a local model. + Model, + /// Needs a configured CI runner. + CiRunner, +} + +impl GateRequirement { + pub fn as_str(self) -> &'static str { + match self { + GateRequirement::Host => "host", + GateRequirement::Vm => "vm", + GateRequirement::GraphicalSeat => "graphical-seat", + GateRequirement::Model => "model", + GateRequirement::CiRunner => "ci-runner", + } + } +} + +/// One release candidate check. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct Gate { + pub name: String, + pub description: String, + pub requires: GateRequirement, + /// The exact command (argv) that performs the check. + pub command: Vec, +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum GateStatus { + Passed, + Failed, + NotRun, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct GateResult { + pub name: String, + pub status: GateStatus, + pub detail: String, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] +#[serde(default)] +pub struct GateReport { + pub version: String, + pub created_unix: u64, + pub results: Vec, +} + +impl GateReport { + /// Whether every gate passed. `NotRun` is not a pass. + pub fn all_passed(&self) -> bool { + !self.results.is_empty() && self.results.iter().all(|r| r.status == GateStatus::Passed) + } + + pub fn not_run(&self) -> usize { + self.results + .iter() + .filter(|r| r.status == GateStatus::NotRun) + .count() + } + + pub fn save(&self, path: &Path) -> std::io::Result<()> { + if let Some(parent) = path.parent() { + std::fs::create_dir_all(parent)?; + } + std::fs::write(path, serde_json::to_string_pretty(self).unwrap()) + } + + pub fn load(path: &Path) -> std::io::Result { + let text = std::fs::read_to_string(path)?; + serde_json::from_str(&text) + .map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidData, e)) + } +} + +/// The candidate checks. Commands are the real harness invocations, not +/// placeholders, so a configured runner executes exactly what is documented. +pub fn candidate_gates() -> Vec { + let driver = "installer/tests/vm/serial-driver.py"; + vec![ + Gate { + name: "install".into(), + description: "full encrypted install in the disposable VM".into(), + requires: GateRequirement::Vm, + command: vec!["python3".into(), driver.into(), "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()], + }, + 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(), + 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()], + }, + 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()], + }, + ] +} + +/// 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 +// --------------------------------------------------------------------------- + +/// The signing command for an artifact. The key path is supplied by the +/// operator (via environment or a secret store), never committed and never +/// placed in a model context. +pub fn sign_command(artifact: &Path, key: &Path) -> Vec { + vec![ + "minisign".into(), + "-S".into(), + "-s".into(), + key.to_string_lossy().to_string(), + "-m".into(), + artifact.to_string_lossy().to_string(), + ] +} + +/// The verification command for an artifact plus its detached signature. +pub fn verify_signature_command(artifact: &Path) -> Vec { + vec![ + "minisign".into(), + "-Vm".into(), + artifact.to_string_lossy().to_string(), + ] +} + +/// Publish a candidate atomically, preserving the previous release. +/// +/// 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. +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"); + 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"); + let _ = std::fs::remove_file(&previous); + std::fs::rename(dest, &previous)?; + } + std::fs::rename(&staging, dest)?; + Ok(()) +} + #[cfg(test)] mod tests { use super::*; @@ -156,4 +375,59 @@ mod tests { assert!(cmd.iter().any(|a| a == "/phoebus")); assert!(cmd.iter().any(|a| a == "/base.iso")); } + + #[test] + fn gates_cover_the_required_checks_and_never_fake_a_pass() { + let names: Vec = candidate_gates().into_iter().map(|g| g.name).collect(); + for required in [ + "install", + "detached-boot", + "desktop-session", + "updates-and-rollback", + "no-model-recovery", + ] { + assert!( + names.contains(&required.to_string()), + "missing gate {required}" + ); + } + let report = run_gates(false); + 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"))); + } + + #[test] + fn atomic_publish_keeps_the_previous_release() { + let dir = tempfile::tempdir().unwrap(); + let candidate = dir.path().join("candidate.iso"); + let dest = dir.path().join("latest.iso"); + std::fs::write(&candidate, b"v1").unwrap(); + atomic_publish(&candidate, &dest).unwrap(); + assert_eq!(std::fs::read(&dest).unwrap(), b"v1"); + assert!(!dest.with_extension("prev").exists()); + + std::fs::write(&candidate, b"v2").unwrap(); + atomic_publish(&candidate, &dest).unwrap(); + assert_eq!(std::fs::read(&dest).unwrap(), b"v2"); + assert_eq!( + std::fs::read(dest.with_extension("prev")).unwrap(), + b"v1", + "the last known-good release must be preserved" + ); + // No partial staging file is left behind. + assert!(!dest.with_extension("new").exists()); + } + + #[test] + fn signing_commands_keep_the_key_out_of_the_repo() { + let cmd = sign_command( + Path::new("/out.iso"), + Path::new("/run/secrets/minisign.key"), + ); + assert_eq!(cmd[0], "minisign"); + assert!(cmd.iter().any(|a| a == "/run/secrets/minisign.key")); + let verify = verify_signature_command(Path::new("/out.iso")); + assert!(verify.iter().any(|a| a == "-Vm")); + } } diff --git a/installer-rs/crates/phoebus-tui/src/lib.rs b/installer-rs/crates/phoebus-tui/src/lib.rs index f2bd16a..0342840 100644 --- a/installer-rs/crates/phoebus-tui/src/lib.rs +++ b/installer-rs/crates/phoebus-tui/src/lib.rs @@ -397,6 +397,7 @@ fn choice_options(choice: Choice, _config: &InstallConfig) -> Vec { Choice::DesktopProfile => vec![ DesktopProfile::None.to_string(), DesktopProfile::Dwl.to_string(), + DesktopProfile::Mango.to_string(), DesktopProfile::Minimal.to_string(), DesktopProfile::Full.to_string(), ], @@ -449,9 +450,10 @@ fn apply_choice(choice: Choice, index: usize, config: &mut InstallConfig) { config.desktop.profile = [ DesktopProfile::None, DesktopProfile::Dwl, + DesktopProfile::Mango, DesktopProfile::Minimal, DesktopProfile::Full, - ][index.min(3)]; + ][index.min(4)]; } Choice::AiProvider => { let provider = ["none", "deepseek", "openai"][index.min(2)]; diff --git a/installer/tests/vm/appliance-driver.py b/installer/tests/vm/appliance-driver.py new file mode 100644 index 0000000..3053c34 --- /dev/null +++ b/installer/tests/vm/appliance-driver.py @@ -0,0 +1,156 @@ +#!/usr/bin/env python3 +"""Headless serial driver for the Debian-Live Phoebus appliance ISO. + +The committed `serial-driver.py` drives a *Gentoo* live ISO with an explicit +kernel/initrd. The appliance (`installer/live/build.sh`) boots its own GRUB on +UEFI, so it needs its own driver. + +Two modes: + + install : boot the appliance, log in as `user`/`live`, fetch a guest script + over QEMU user networking, install Phoebus non-interactively, then + power off. + boot : boot the installed disk alone (no ISO), unlock LUKS, log in and run + verification commands. + +Everything is parameterised through environment variables. `DISK` must be a +qcow2 image; this script never touches a physical disk. Secrets are served from +the host as 0600 files and fetched inside the guest, so they never appear in +the serial transcript. + +Host setup (see docs/DEVELOPMENT.md): + + mkdir -p /path/serve && cd /path/serve + cp /path/to/installer/live/phoebus-installer-amd64.iso . + cp .tar.xz stage3.tar.xz && sha256sum stage3.tar.xz + cp /path/to/installer/tests/vm/appliance-guest.sh . + cp /path/to/installer/tests/vm/appliance-test.conf.example test.conf # set STAGE3_SHA256 + printf 'phoebus-luks-test' > luks.pw && chmod 600 luks.pw + printf 'phoebus-user-test' > user.pw && chmod 600 user.pw + python3 -m http.server 8000 --bind 127.0.0.1 +""" +import os +import sys + +import pexpect + +QEMU = os.environ.get("QEMU_BIN", "qemu-system-x86_64") +OVMF_CODE = os.environ["OVMF_CODE"] +OVMF_VARS = os.environ["OVMF_VARS"] +DISK = os.environ["DISK"] +ISO = os.environ.get("ISO", "") +SERIAL_LOG = os.environ.get("SERIAL_LOG", "/tmp/phoebus-appliance-serial.log") +SERVE_URL = os.environ.get("SERVE_URL", "http://10.0.2.2:8000") +LUKS_PW = os.environ.get("LUKS_PASSPHRASE", "phoebus-luks-test") +USER_PW = os.environ.get("USER_PASSWORD", "phoebus-user-test") +USER = os.environ.get("USERNAME", "phoebus") +LIVE_USER = os.environ.get("LIVE_USER", "user") +LIVE_PW = os.environ.get("LIVE_PASSWORD", "live") +MEM = os.environ.get("VM_MEM", "8192") +SMP = os.environ.get("VM_SMP", "8") +INSTALL_TIMEOUT = int(os.environ.get("INSTALL_TIMEOUT", "10800")) + + +def base_args(): + return [ + "-machine", "q35,accel=kvm", + "-cpu", "host", "-smp", SMP, "-m", MEM, + "-drive", f"if=pflash,format=raw,readonly=on,file={OVMF_CODE}", + "-drive", f"if=pflash,format=raw,file={OVMF_VARS}", + "-drive", f"file={DISK},if=virtio,format=qcow2", + "-netdev", "user,id=n0", "-device", "virtio-net-pci,netdev=n0,romfile=", + "-device", "virtio-rng-pci", "-vga", "std", "-display", "none", + "-serial", "stdio", "-monitor", "none", "-no-reboot", + ] + + +def spawn(args): + child = pexpect.spawn(QEMU, args, timeout=900, encoding="utf-8", + codec_errors="replace", maxread=65536) + child.delaybeforesend = 0.4 + return child + + +def login_live(child): + # The live medium may auto-login or present a login prompt; its hostname is + # typically `debian` (standard live) or `live`. + idx = child.expect([r"(?:live|debian) login:", r"[$#] $"], timeout=900) + if idx == 0: + child.sendline(LIVE_USER) + child.expect(r"Password:", timeout=60) + child.sendline(LIVE_PW) + child.expect(r"[$#] $", timeout=120) + + +def do_install(): + args = base_args() + if not ISO: + raise SystemExit("ISO is required for install mode") + args += ["-drive", f"file={ISO},media=cdrom,readonly=on"] + log = open(SERIAL_LOG, "w") + child = spawn(args) + child.logfile = log + try: + login_live(child) + child.sendline( + f"curl -fsSL {SERVE_URL}/appliance-guest.sh -o /tmp/gi.sh && bash /tmp/gi.sh" + ) + child.expect([r"===INSTALL-RC=([0-9]+)===", "===FETCH-FAIL===", + "Kernel panic", pexpect.EOF, pexpect.TIMEOUT], + timeout=INSTALL_TIMEOUT) + if "INSTALL-RC" in (child.after or ""): + print("INSTALL_RC", child.match.group(1), flush=True) + else: + print("INSTALL did not report a status", flush=True) + child.expect(["===POWEROFF===", pexpect.EOF, pexpect.TIMEOUT], timeout=600) + child.expect(pexpect.EOF, timeout=300) + finally: + child.close(force=True) + log.close() + + +def do_boot(): + args = base_args() + ["-boot", "order=c"] + checks = os.environ.get( + "BOOT_CHECKS", + "echo ===CHECKS-$(printf START)===; " + "cat /proc/1/comm; systemctl is-system-running; " + "systemctl --failed --no-pager; ip -brief addr; " + "lsblk -o NAME,SIZE,TYPE,FSTYPE,MOUNTPOINTS; " + "/usr/local/bin/sys rollback status 2>&1 || true; " + "echo ===CHECKS-$(printf END)===", + ) + log = open(SERIAL_LOG, "w") + child = spawn(args) + child.logfile = log + try: + child.expect([r"[Pp]assphrase", r"login:"], timeout=600) + if "assphrase" in (child.after or ""): + child.sendline(LUKS_PW) + for _ in range(5): + child.expect(r"phoebus login:", timeout=300) + child.sendline(USER) + idx = child.expect([r"[Pp]assword:", r"phoebus login:", r"Login incorrect"], + timeout=60) + if idx == 0: + child.sendline(USER_PW) + if child.expect([r"[$#] $", r"Login incorrect", r"phoebus login:"], + timeout=120) == 0: + break + child.sendline(checks) + child.expect("===CHECKS-END===", timeout=int(os.environ.get("CHECKS_TIMEOUT", "300"))) + print("checks complete", flush=True) + finally: + child.close(force=True) + log.close() + + +if __name__ == "__main__": + mode = sys.argv[1] if len(sys.argv) > 1 else "" + if mode == "install": + do_install() + elif mode == "boot": + do_boot() + else: + print(__doc__) + sys.exit(2) diff --git a/installer/tests/vm/appliance-guest.sh b/installer/tests/vm/appliance-guest.sh new file mode 100644 index 0000000..5015af1 --- /dev/null +++ b/installer/tests/vm/appliance-guest.sh @@ -0,0 +1,54 @@ +#!/bin/bash +# Guest-side, non-interactive install for the Debian-Live Phoebus appliance. +# +# Fetched and run by appliance-driver.py inside the live guest. Configuration +# and secrets are fetched from the host over QEMU user networking so they never +# appear in the serial transcript. The installer log is scanned for the LUKS +# passphrase so a leak fails the run. +set -uo pipefail + +SERVE="${SERVE_URL:-http://10.0.2.2:8000}" +WORK=/tmp/phoebus-guest +mkdir -p "$WORK" +cd "$WORK" || exit 1 + +for f in test.conf luks.pw user.pw; do + if ! curl -fsSL "$SERVE/$f" -o "$f"; then + echo "===FETCH-FAIL=== ($f)" + exit 1 + fi +done +chmod 600 luks.pw user.pw + +PHOEBUS=/run/live/medium/phoebus/bin/phoebus +if [ ! -x "$PHOEBUS" ]; then + echo "===FETCH-FAIL=== (no phoebus launcher)" + exit 1 +fi + +# Installing Phoebus requires a connected model unless the explicit break-glass +# is passed. The baseline run uses the deterministic path. +"$PHOEBUS" --version || true + +sudo -n "$PHOEBUS" --config "$WORK/test.conf" --install --yes --no-ai \ + --luks-passphrase-file "$WORK/luks.pw" \ + --user-password-file "$WORK/user.pw" +RC=$? + +LEAK=0 +for log in /run/phoebus-installer/install.log /tmp/phoebus-payload/install.log; do + if [ -f "$log" ] && grep -F -q "$(cat "$WORK/luks.pw")" "$log"; then + LEAK=1 + fi +done +if [ "$LEAK" = 1 ]; then + echo "===SECRET_LEAK===" + RC=99 +else + echo "===NO_SECRET_LEAK===" +fi + +echo "===INSTALL-RC=$RC===" +sync +sudo -n poweroff -f || poweroff -f +echo "===POWEROFF===" diff --git a/installer/tests/vm/appliance-test.conf.example b/installer/tests/vm/appliance-test.conf.example new file mode 100644 index 0000000..0ee8227 --- /dev/null +++ b/installer/tests/vm/appliance-test.conf.example @@ -0,0 +1,39 @@ +# Test configuration for the Debian-Live appliance VM. +# +# The appliance serves this file, the secrets and the stage3 over QEMU user +# networking (host 10.0.2.2). Set STAGE3_SHA256 to the real digest of the +# served stage3 before running; the installer verifies it fail-closed. +# +# Secrets are NOT stored here; they are supplied via --*-file. + +HOSTNAME='phoebus' +USERNAME='phoebus' +USER_FULLNAME='Phoebus Test' +LOCALE='en_US.UTF-8' +TIMEZONE='UTC' +KEYMAP='us' + +TARGET_DISK='/dev/vda' +PARTITION_SCHEME='whole_disk' +EFI_SIZE_MIB='1024' +FILESYSTEM='btrfs' +ENCRYPTION='luks2' +COMPRESS='zstd:3' + +# safe = prebuilt distribution kernel (fast, reliable first boot) +KERNEL_PROFILE='safe' +KERNEL_UKI='no' +KERNEL_CONSOLE='console=tty0 console=ttyS0,115200' +KEEP_KERNELS='3' + +PACKAGE_POLICY='balanced' +FEATURES_BINPKG='yes' + +# none = core system only; dwl/full add the Wayland desktop +DESKTOP_PROFILE='none' +FLATPAK='no' + +NIX_ENABLED='no' + +STAGE3_URL='http://10.0.2.2:8000/stage3.tar.xz' +STAGE3_SHA256='0000000000000000000000000000000000000000000000000000000000000000'