feat(sys): hardware-aware lane selection and new lanes
Some checks are pending
ci / test (push) Waiting to run

Replace the fixed category routing (ADR 0006) with a shared, inspectable,
hardware- and preference-aware selection policy over resolved candidates from
Portage (source/binary/vendor), Nix, Flatpak, Snap, AppImage and the Phoebus
overlay. The policy keeps base components under Portage, separates hard
constraints from preferences, honours and persists explicit choices, errors
instead of silently switching lanes, and reuses an already-installed lane.

- phoebus-core::selection: the pure policy (16 tests: base-system, low-memory
  vs high-core, sandbox requirement, GPU/arch/storage rejection, explicit
  preference, unavailable backend, reproducibility, render).
- phoebus-executor::chooser: resolves real metadata and hardware facts.
- phoebus-executor::{snap,appimage,ebuild}: new lanes. Snap detects daemon and
  confinement and installs app-containers/snapd through Portage; AppImage
  adopts images with a pinned SHA-256, checks the ELF architecture without
  executing, integrates a desktop entry and preserves user data on removal; the
  custom ebuild overlay binds approval to the ebuild content digest and builds
  through Portage's sandbox.
- Typed actions choose_package / set_package_preference / snap_* / appimage_* /
  custom_ebuild_* with strict validators; the assistant prompt and schema are
  reconciled (no category routing; custom ebuilds are untrusted).
- Installed sys: the installer locates the trusted static binary, copies it to
  /usr/local/bin/sys and proves it runs in the target chroot before the
  recovery snapshot, failing closed if absent; the VM harness fetches sys.
- docs/SYS.md: command/action reference and acceptance matrix; ADR 0006 revised.

Host gates pass: fmt, clippy (no new warnings), workspace tests, make test,
release and static sys builds. VM lane journeys remain pending (see HANDOFF).
This commit is contained in:
Phoebus 2026-09-23 18:35:26 -07:00
parent 3b1b54ffb9
commit 297f3201ff
27 changed files with 5897 additions and 271 deletions

View file

@ -30,11 +30,12 @@ Then read, in order:
3. `docs/HANDOFF.md` — where the last session stopped and the next actions. 3. `docs/HANDOFF.md` — where the last session stopped and the next actions.
4. `docs/STATUS.md` — what is implemented vs unit-tested vs VM-verified. 4. `docs/STATUS.md` — what is implemented vs unit-tested vs VM-verified.
5. `docs/ARCHITECTURE.md` — components and how they fit together. 5. `docs/ARCHITECTURE.md` — components and how they fit together.
6. `docs/adr/` — why significant decisions were made (BLS, profile, ...). 6. `docs/SYS.md` — the `sys` command/action reference and acceptance matrix.
7. `docs/DEVELOPMENT.md` — host setup, build, test, VM workflow. 7. `docs/adr/` — why significant decisions were made (BLS, profile, ...).
8. `docs/CONTRIBUTING.md` — code standards and definition of done. 8. `docs/DEVELOPMENT.md` — host setup, build, test, VM workflow.
9. `docs/GIT-WORKFLOW.md` — how changes are committed and published. 9. `docs/CONTRIBUTING.md` — code standards and definition of done.
10. `git log --oneline -30` and the top of `docs/CHANGELOG.md` — recent history. 10. `docs/GIT-WORKFLOW.md` — how changes are committed and published.
11. `git log --oneline -30` and the top of `docs/CHANGELOG.md` — recent history.
--- ---

View file

@ -3,6 +3,68 @@
All notable changes are recorded here. The authoritative history is `git log`; All notable changes are recorded here. The authoritative history is `git log`;
this file is the curated, human-readable summary. this file is the curated, human-readable summary.
## 2026-09-24 — Hardware-aware software selection, Snap/AppImage/custom ebuild, `sys` lifecycle
- **Shared selection policy (`phoebus-core::selection`, ADR 0006 revised):**
replaced the fixed category routing (GUI→Flatpak, dev→Nix) with a single,
inspectable, deterministic policy over resolved candidates from **every** lane
(Portage source/binary/vendor, Nix, Flatpak, Snap, AppImage, custom ebuild).
It separates hard constraints (architecture, required sandbox, storage, GPU,
required proprietary, unavailable backend) from preferences; keeps kernel,
drivers, systemd, graphics/audio and boot under Portage; honours and persists
explicit compatible choices; errors instead of silently switching lanes; and
reuses an already-installed lane to avoid duplication. Uncertainties are
labelled (measured vs estimated compile time).
- **Candidate resolution (`phoebus-executor::chooser`):** gathers real backend
metadata (`emerge --pretend`, `flatpak search`, `snap find`, local Nix/AppImage
records, the Phoebus overlay), assembles hardware facts (arch, cores, RAM, free
space, GPUs, Wayland, compile history) and applies the policy. Unreachable
metadata is reported as an unavailable candidate, never invented.
- **Snap lane (`phoebus-executor::snap`):** detection of the client, daemon
readiness and confinement; `find`/`info`/`list`/`install`/`remove`/`refresh`/
`connections`. `app-containers/snapd` is installed and `snapd.socket` enabled
**through Portage**; classic confinement is explicit; automatic refresh is
disclosed.
- **AppImage lane (`phoebus-executor::appimage`):** managed import/acquisition
with a pinned SHA-256 (placeholders and mismatches refused), ELF-architecture
checks **without executing the image**, atomic adoption, desktop entry and
optional icon extraction via `unsquashfs`, version/integrity records, and
removal that preserves user data by default. AppImage is never called a
sandbox.
- **Custom ebuild lane (`phoebus-executor::ebuild`):** a dedicated
`/var/db/repos/phoebus` overlay with recorded rationale and a content SHA-256.
Staging never runs the ebuild; install requires the reviewed digest, generates
the `Manifest` and builds through Portage with its sandbox enabled. Editing the
staged ebuild invalidates approval.
- **Typed actions + `sys` surface (`phoebus-core::action`, `phoebus-installer`):**
`choose_package`, `set_package_preference`, `snap_*`, `appimage_*` and
`custom_ebuild_*`, with strict validators (option-like operands, path
traversal, placeholder hashes and bad names fail closed). Deterministic
phrases cover the common cases; `custom_ebuild` staging/install stay JSON-only
because they carry a full artifact.
- **`sys` in the installed target:** the installer locates the trusted static
`sys` beside itself, installs it to `/usr/local/bin/sys`, proves it runs in the
target chroot before the recovery snapshot, and fails the install closed if it
is missing. The VM install harness now fetches `sys`, and the rollback guest
uses the installed binary.
- **Assistant prompt reconciled:** the closed action set now includes the new
actions and instructs the model not to route by category, to use
`choose_package`, and to treat a custom ebuild as untrusted.
- **Docs:** new `docs/SYS.md` command reference and acceptance matrix; revised
ADR 0006.
### Verified (host)
- `cargo fmt`, `cargo clippy --workspace --all-targets` (no new warnings) and
`cargo test --workspace` pass; the new policy, backend and CLI tests run on the
host. `installer/tests/vm/test_vmsafety.py` (18 tests) passes with the new
`sys-acceptance.sh`.
### Not yet verified
- The new lanes and the installed-`sys` lifecycle are unit/integration tested
but **not yet exercised in a booted VM** in this session: a full GUI install
was occupying the only disposable disk. The exact VM commands are in
`docs/SYS.md` and `docs/HANDOFF.md`.
## 2026-09-23 — NVIDIA reliability, verification and harness repair ## 2026-09-23 — NVIDIA reliability, verification and harness repair
- **Deterministic live GPU decision (`phoebus-core`, `phoebus-installer`):** - **Deterministic live GPU decision (`phoebus-core`, `phoebus-installer`):**

View file

@ -3,124 +3,109 @@
Rolling note between work sessions. **Update this file before you finish**, then 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. commit it. It should be short and current; use `git log` for detail.
- **Last updated:** this session (2026-09-23), NVIDIA reliability and - **Last updated:** this session (2026-09-24), hardware-aware software
verification pass: live driver decision, verifier hardening, installed selection across all lanes, Snap/AppImage/custom-ebuild backends, and the
lifecycle, rollback harness, GUI harness repair, scoped live privilege. installed-`sys` lifecycle.
- **Current focus:** - **Current focus:**
1. **Deterministic live NVIDIA decision.** `phoebus-installer 1. **Shared selection policy** (`phoebus-core::selection`, ADR 0006 revised):
--live-gpu-plan` classifies the actual PCI display controllers against the fixed category routing is gone. A deterministic, inspectable policy
bundled branch and returns `load-nvidia` / `nouveau-fallback` / resolves real candidates from Portage (source/binary/vendor), Nix, Flatpak,
`no-device` / `disabled`; the old `0x10de`-vendor grep is gone. An Snap, AppImage and the Phoebus overlay; separates hard constraints from
unsupported GPU (or a failed load) explicitly `modprobe`s `nouveau`, and preferences; keeps base components under Portage; honours and persists
the fail-safe entry sets `nomodeset phoebus.nvidia=off` which the script explicit choices; errors instead of silently switching lanes; reuses an
and unit both honour. already-installed lane.
2. **Live payload gate is a compatibility gate.** It rejects placeholder 2. **New backends** (`phoebus-executor`): `snap` (daemon/confinement
modules/libraries, requires registration in the live kernel's detection, install/list/remove/refresh/connections, `app-containers/snapd`
`modules.dep`, matches userspace/firmware versions to the bundled driver, through Portage), `appimage` (pinned-hash acquire/import, ELF arch check
infers and checks the module flavor, and requires the exact without execution, desktop integration, data-preserving removal), `ebuild`
`etc/modprobe.d/phoebus-nvidia.conf` (now produced by `build.sh`). (Phoebus overlay, rationale + content digest, approval-gated build with
3. **Branch boundary corrected.** Maxwell/Pascal/Volta are capped at the last Portage's sandbox).
supporting series (580) instead of `<595`; a Blackwell plus 3. **`sys` surface**: `choose_package`, `set_package_preference`, `snap_*`,
proprietary-only GPU is reported as an explicit incompatibility. `appimage_*`, `custom_ebuild_*` typed actions with strict validators and
4. **Installed lifecycle.** The NVIDIA `force_drivers` fragment is written deterministic phrases; `docs/SYS.md` is the command reference and
only after the driver exists; the installer proves the modules built for a acceptance matrix.
kernel and records the real version/kernel/module names. 4. **`sys` in the installed target**: located beside the installer, copied to
5. **GUI harness repaired** for the six-step installer (no step 0, no ERASE, `/usr/local/bin/sys`, proven to run in the target chroot before the
no confirmation toggle, single-password account); state-based step recovery snapshot; install fails closed if absent.
navigation; boot uses the single-password disk passphrase. 5. **VM harness**: `install.sh` fetches `sys`; `rollback-guest.sh` uses the
6. **Rollback acceptance automated** as `serial-driver.py rollback`. installed binary; new `installer/tests/vm/sys-acceptance.sh`.
7. **Live privilege scoped:** `NOPASSWD` only for the two typed brokers and
`systemctl` power actions; the recovery console uses the live password.
- **Last verified (this session):** - **Last verified (this session):**
- `cargo fmt --all -- --check`, `cargo clippy --workspace --all-targets` - `cargo fmt --all -- --check`, `cargo clippy --workspace --all-targets`
(0 errors) and `cargo test --workspace` all pass. The `gui_bridge` dry-run (no new warnings) and `cargo test --workspace` pass. New coverage: the
tests **do not hang** on this checkout: the earlier "block" note was stale selection policy (16 tests across hardware/preference/failure cases), Snap
and is withdrawn. and AppImage parsing/behaviour, the ebuild digest/approval path, chooser
- `installer/tests/vm/test_vmsafety.py` (18 tests) passes, including `bash -n` resolution, and `sys_cli` host tests.
over every guest script. - `installer/tests/vm/test_vmsafety.py` (18 tests) passes with the new guest
- Py-compile clean for `gui-driver.py`, `serial-driver.py`, `live-driver.py`. script.
- The emitted live sudoers policy is validated with host `visudo` in a unit - **Not yet verified this session:** the new lanes and the installed-`sys`
test and at build time. lifecycle are unit/integration tested but **not exercised in a booted VM**: a
- New coverage: `live_nvidia_plan` decisions, sysfs device scan + CLI full `gui-install` (started by a prior session) was still running on the only
fixtures, mixed-hardware incompatibility, verifier negatives (placeholders, disposable disk. The NVIDIA boot gates and the rollback destructive gate remain
stale `modules.dep`, version/flavor mismatch, missing final config), unrun.
installed module proof + version record, and the ordering fix.
- **Not yet verified this session (unchanged blockers):** the **full desktop
live ISO** is still not assembled (host has ~12 GiB free; `make doctor` wants
>=20 GiB), so the `gui`/`opencode`/`gui-install` journeys were **not re-run**
against the repaired harness, and the NVIDIA live/installed boot gates are
unrun (no NVIDIA GPU). The rollback harness is written and unit-checked but
its destructive VM gate is **unrun**. `sys` is not installed into the target
(see below).
- **Public repo:** <https://git.phoebus.club/phoebus/phoebus_os> - **Public repo:** <https://git.phoebus.club/phoebus/phoebus_os>
(remote `origin`, SSH port 2222). (remote `origin`, SSH port 2222).
## Next actions (in order) ## Next actions (in order)
1. **Run the repaired GUI harness** once disk allows: `gui`, `opencode`, then 1. **Boot the installed disk and run the `sys` acceptance matrix** once the
`gui-install` + detached `boot`. It now expects the six-step flow and the current `gui-install` VM releases the disk:
direct "Install now" action. Serve `live.pw` (0600) alongside `test.conf`, ```sh
`luks.pw` and `user.pw` for the `gui-install` preseed. cp installer-rs/target/x86_64-unknown-linux-gnu/release/phoebus-installer \
2. **NVIDIA hardware acceptance (BLOCKED)**: on a machine with an NVIDIA GPU installer-rs/target/x86_64-unknown-linux-gnu/release/sys /home/dominic/vmlab/serve/
boot the live ISO and the installed system and confirm the accelerated stack, cp installer/tests/vm/{install.sh,sys-acceptance.sh,rollback-guest.sh,rollback-verify.sh} /home/dominic/vmlab/serve/
`nvidia_drm` modeset, Mango/DMS acceleration, XWayland/Flatpak, and a kernel # in the serve dir: python3 -m http.server 8000 --bind 127.0.0.1
update that rebuilds the modules and initramfs. Needs an NVIDIA GPU. DISK=/var/tmp/phoebus-vm/disks/<clone>.qcow2 OVMF_CODE=... OVMF_VARS=... \
3. **Rollback VM acceptance (BLOCKED on disk + a clone)**: create an installed BOOT_CHECKS='test -x /usr/local/bin/sys && /usr/local/bin/sys --version; sudo /usr/local/bin/sys history; \
disposable clone, then `serial-driver.py rollback`. The gate and the exact curl -fsSL http://10.0.2.2:8000/sys-acceptance.sh -o /tmp/sa.sh && SYS_ACCEPTANCE_MUTATE=1 bash /tmp/sa.sh; \
evidence markers are implemented; it has not executed. echo ===CHECKS-$(printf END)===' \
4. **Install `sys` into the target**: the installed system still lacks the python3 installer/tests/vm/serial-driver.py boot
deterministic CLI, so the no-model fallback contract is only partially ```
shipped. This blocks a pure product-path rollback test. Confirm `/usr/local/bin/sys` exists (installed lifecycle), the matrix reports
5. **Live ISO build + verify (BLOCKED on disk)**: `installer/live/build.sh` `FAIL=0`, and a Portage install/remove appears in `sys history`.
now also emits and `visudo`-validates the scoped sudo policy and produces the 2. **Snap / AppImage / custom-ebuild VM journeys**: on a disposable installed
live NVIDIA config. Free space and run the `gui` harness. VM, `sys snap install <tiny-snap>`, `sys appimage import` a small test image,
6. **Installed Mango desktop**: install the default profile in a graphical VM and one `custom_ebuild_prepare` + `custom_ebuild_install`. Needs network for
and verify panel/launcher/terminal/audio/network/lock/idle and the dwl Snap/AppImage; the custom-ebuild path can use a local file.
fallback; a no-desktop run is a separate baseline. 3. **Rollback VM acceptance**: clone the installed disk and run
7. **Release gates on a CI runner**: `phoebus-release gates --execute` and `serial-driver.py rollback`. The destructive gate is written and unit-checked
`publish` once a runner exists; no gate has executed. but unrun.
4. **NVIDIA hardware acceptance (BLOCKED)**: needs an NVIDIA GPU; unchanged.
5. **Live AI provider call**: exercise `sys ask` with a real 0600 key file; the
path is fixture-verified only.
6. **Installed Mango desktop** and the **live ISO `gui` journey** remain to be
re-run on this checkout.
## Known blockers / risks ## Known blockers / risks
- **Disk is the harness constraint.** `make doctor` reports ~12 GiB free versus - **One disposable disk, shared with a long `gui-install`.** Do not start a
the >=20 GiB the VM harness wants. This blocks assembling the full desktop second VM against the same qcow2; clone it first. `make doctor` reports
ISO and the rollback acceptance run. Do not delete unrelated files. ~29 GiB free now (the earlier ~12 GiB disk blocker has eased).
- **No NVIDIA GPU** (and no authorised passthrough): actual acceleration cannot - **No NVIDIA GPU** (and no authorised passthrough): acceleration cannot be
be verified here. The live decision and verifier are device-based and verified here.
unit/fixture-tested only. - **Snap needs network and AppArmor** for meaningful confinement. The lane
- **`sys` is absent from the installed target.** The live medium and the detects confinement honestly; a host without AppArmor reports `none`.
`phoebus-assistant` launcher use `sys`, and the rollback harness fetches it - **AppImage provides no sandbox.** Do not describe it as one; runtime
from the host, but the installed system has no `/usr/local/bin/sys`. Fixing it requirements (FUSE) are not auto-installed.
(embedding the static `sys` binary in the install) is future work. - **The custom-ebuild build is Portage sandboxed, not VM-isolated.** Treat a
- **The `gui-install` completion is still host-time bound**: the base package generated ebuild as untrusted and keep the digest-bound approval.
stage took ~116 min and the AI-selected kernel was still compiling at the 4 h - **`gui-install` completion is host-time bound** (base stage ~116 min, kernel
timeout. The deterministic noninteractive install + detached boot remains the compile beyond the 4 h timeout). The deterministic install + detached boot is
proven path. the proven path.
- **Installed** Mango (GURU + compiled Quickshell/DMS) and the dwl fallback are - Harness artifacts live under `/var/tmp/phoebus-vm/` (outside git).
still not VM-verified.
- **Recovery-entry offline boot** is not automated: the rollback harness records
the snapshot recovery entry but does not select it in the bootloader.
- The live appliance guest scripts (`appliance-guest.sh`,
`appliance-guest-gui.sh`) still use `sudo -n`/`poweroff` and a
`/run/live/medium/phoebus/bin/phoebus` launcher path; they predate the scoped
policy and would need the live password if re-run against the narrowed image.
- Harness artifacts live under `/var/tmp/phoebus-vm/` (outside git):
`results.json`, `screenshot-manifest.json`, `report.html`, screenshots.
## Environment notes ## Environment notes
- Dev host: Ubuntu 26.04. QEMU/OVMF/xorriso/rustfmt/clippy/ImageMagick/visudo - Dev host: Ubuntu 26.04. QEMU/OVMF/xorriso/rustfmt/clippy/ImageMagick/visudo
present. ~12 GiB free on the root filesystem. present. `flatpak` and `snap` clients are installed on the host (not usable as
- Debian-Live base ISO is cached at `/home/dominic/debian-live-standard.iso` proof of the VM lanes).
(matches `installer/live/base.sha256`). - Debian-Live base ISO is cached at `/home/dominic/debian-live-standard.iso`.
- VM harnesses: `installer/tests/vm/gui-driver.py` (`gui`/`opencode`/ - VM harnesses: `installer/tests/vm/gui-driver.py`, `serial-driver.py`,
`gui-install`/`install`/`boot`), `serial-driver.py` `appliance-driver.py`, `live-driver.py`, and `sys-acceptance.sh`.
(`install`/`boot`/`rollback`), `appliance-driver.py`, `live-driver.py`.
`DISK` must be a disposable qcow2; never point it at `/dev/*`. `DISK` must be a disposable qcow2; never point it at `/dev/*`.
- Serve fixtures from `/home/dominic/vmlab/serve` with - Serve fixtures from `/home/dominic/vmlab/serve` with
`python3 -m http.server 8000 --bind 127.0.0.1` (reachable as `10.0.2.2:8000`), `python3 -m http.server 8000 --bind 127.0.0.1` (reachable as `10.0.2.2:8000`).
including `live.pw` for the `gui-install` preseed and `rollback-guest.sh`, - The static binaries for the VM: `make static` builds `phoebus-installer` and
`rollback-verify.sh` and `sys` for the rollback mode. `sys` under `installer-rs/target/x86_64-unknown-linux-gnu/release/`.
## Definition of a good stopping point ## Definition of a good stopping point

View file

@ -16,7 +16,7 @@ more interesting. Status vocabulary: **Done**, **Partial**, **Next**, **Later**.
| 9 | Background update preparation | Partial | distfile fetch VM-verified; `--buildpkgonly` skipped while deps need merging (recorded Ready); activation explicit | | 9 | Background update preparation | Partial | distfile fetch VM-verified; `--buildpkgonly` skipped while deps need merging (recorded Ready); activation explicit |
| 10 | Snapshots / rollback | Partial | snapshot sets + history VM-verified on Btrfs; coordinated rollback, `sys undo`, recovery entry, retention and free-space gate implemented + unit-tested; destructive VM acceptance test pending | | 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 | | 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; target-root consistency, execution-boundary validation, truthful `ask` failure, full transaction outcomes, empty-vs-unestablished plans, and start/stop/restart + flatpak/nix/snapshot commands added (unit/integration-tested; VM gate pending) | | 12 | `sys` operations | Partial | history, enable/disable, inspect, install, prepare-updates VM-verified; target-root consistency, execution-boundary validation, truthful `ask` failure, full transaction outcomes, empty-vs-unestablished plans, and start/stop/restart + flatpak/nix/snapshot commands added (unit/integration-tested; VM gate pending). Installed-target `sys` now provisioned by the installer (unit-tested; VM gate pending) |
| 13 | Kernel optimization policy | Later | conservative fragments only; SAFE/OPTIMIZED/AGGRESSIVE selection exists | | 13 | Kernel optimization policy | Later | conservative fragments only; SAFE/OPTIMIZED/AGGRESSIVE selection exists |
| 14 | ISO / release pipeline | Partial | manifest/verify/assemble-plan tooling; release gates, atomic publish and signing helpers added; no CI runner has executed a gate | | 14 | ISO / release pipeline | Partial | manifest/verify/assemble-plan tooling; release gates, 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 | | 15 | Recovery environment | Later | recovery BLS entry generated; snapshot-based recovery entry written at install; full recovery image not built |
@ -24,6 +24,7 @@ more interesting. Status vocabulary: **Done**, **Partial**, **Next**, **Later**.
| — | Graphical installer (welcome + wizard) | Partial | Quickshell/QML over the typed `--gui-bridge`; live graphical VM verified, including a detached install+boot; live AI call pending (ADR 0010) | | — | Graphical installer (welcome + wizard) | Partial | Quickshell/QML over the typed `--gui-bridge`; live graphical VM verified, including a detached install+boot; live AI call pending (ADR 0010) |
| — | 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 | | — | 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 | | — | Nix as a built-in second lane | Partial | pinned-release bootstrap; `nix-daemon` active and `nix shell nixpkgs#hello` VM-verified; on by default |
| — | Hardware-aware software selection (all lanes) | Partial | shared policy + candidate resolution + `choose_package`/`set_package_preference` (unit-tested); Snap, AppImage and custom-ebuild backends implemented (unit-tested); VM journeys pending (ADR 0006 revised) |
| — | Git workflow + agent guide | Done | this `docs/` set, `.githooks/`, `scripts/` | | — | Git workflow + agent guide | Done | this `docs/` set, `.githooks/`, `scripts/` |
## Immediate next steps ## Immediate next steps
@ -43,7 +44,12 @@ more interesting. Status vocabulary: **Done**, **Partial**, **Next**, **Later**.
4. **Binary strategy**: keep the official signed binhost for packages whose USE 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 matches and use Flatpak/Nix for other binaries; do not publish a private
Gentoo binhost (ADR 0006). Verify with `emerge -pv` and record reuse. Gentoo binhost (ADR 0006). Verify with `emerge -pv` and record reuse.
5. **Live AI provider call**: exercise `sys ask` and the installer guided path 5. **Lane acceptance in the disposable VM**: run the `sys` acceptance matrix
(`installer/tests/vm/sys-acceptance.sh`) on a booted installed disk, then a
Snap install/refresh/remove, an AppImage acquire/launch/remove, and one
custom-ebuild build (`docs/SYS.md`). This is the remaining proof for the new
lanes and the installed-`sys` lifecycle.
6. **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 with a real 0600 key file; the path is currently fixture-verified only, and
the `systemd-run` sandbox is not yet VM-verified. the `systemd-run` sandbox is not yet VM-verified.

View file

@ -87,6 +87,11 @@ still not VM-verified.
| Resolved package effects + approval binding | yes | yes (empty vs unestablished) | no | n/a | | Resolved package effects + approval binding | yes | yes (empty vs unestablished) | no | n/a |
| Transaction log (outcomes, protective snapshots) | yes | yes | no | no | | Transaction log (outcomes, protective snapshots) | yes | yes | no | no |
| Flatpak/Nix bounded typed actions | yes | yes | no | no | | Flatpak/Nix bounded typed actions | yes | yes | no | no |
| Shared hardware-aware source selection (all lanes) | yes | yes | no | no |
| Snap lane (detect/install/list/remove/refresh/connections) | yes | yes | no | no |
| AppImage lane (import/acquire/integrity/desktop/remove) | yes | yes | no | no |
| Custom ebuild overlay (stage/approve/build/remove) | yes | yes | no | no |
| `sys` installed into the target + verified in chroot | yes | yes (unit) | no | no |
| `sys` consistent target-root execution | yes | yes | no | no | | `sys` consistent target-root execution | yes | yes | no | no |
| `sys` validation at the execution boundary | yes | yes | no | n/a | | `sys` validation at the execution boundary | yes | yes | no | n/a |
| `sys ask` truthful failure (nonzero, stop, record) | yes | yes | no | n/a | | `sys ask` truthful failure (nonzero, stop, record) | yes | yes | no | n/a |
@ -156,13 +161,15 @@ still not VM-verified.
and Blackwell (or a failed accelerated load) falls back to nouveau on the live and Blackwell (or a failed accelerated load) falls back to nouveau on the live
medium. The installed Gentoo system uses the current branch with NVIDIA's open medium. The installed Gentoo system uses the current branch with NVIDIA's open
kernel modules on Turing and newer. kernel modules on Turing and newer.
- **The installed target does not install the `sys` binary.** The deterministic - **The installed `sys` binary is now provisioned by the installer.** The
CLI is present on the live medium and on the installed desktop's installer locates the trusted static `sys` beside itself, copies it to
`phoebus-assistant` launcher (which calls `sudo sys ask`), but the installed `/usr/local/bin/sys`, validates the ELF payload and proves it runs in the
system has no `/usr/local/bin/sys`: the harness fetches it from the host to target chroot before the recovery snapshot; the install fails closed if it is
exercise rollback. This is a real gap against the "operate and repair by hand" missing. The VM install harness fetches `sys` and the rollback guest prefers
contract and is recorded as future work; it also blocks the rollback harness the installed binary. This is **unit-tested but not yet VM-verified** on the
from being a pure product-path test. installed system (a full GUI install was occupying the only disposable disk in
this session). Before this change the installed system had no
`/usr/local/bin/sys` and the harness fetched it from the host.
- **UKI** is deferred; the dracut UKI generator did not embed the kernel - **UKI** is deferred; the dracut UKI generator did not embed the kernel
command line, so BLS is used (and verified). command line, so BLS is used (and verified).
- **Rollback (`sys undo`) is NOT VM-verified.** It is implemented and - **Rollback (`sys undo`) is NOT VM-verified.** It is implemented and
@ -173,11 +180,13 @@ still not VM-verified.
`rollback-verify.sh`): a known-good package-database fingerprint and `/home` `rollback-verify.sh`): a known-good package-database fingerprint and `/home`
marker, `sys snapshot`, a controlled reversible package install, `sys undo`, marker, `sys snapshot`, a controlled reversible package install, `sys undo`,
detached reboot, then package-state/home comparison, kernel-module check and detached reboot, then package-state/home comparison, kernel-module check and
recovery-entry/status evidence. The destructive gate itself is **unrun**: recovery-entry/status evidence. The destructive gate itself is **unrun in
`make doctor` reports ~12 GiB free versus the >=20 GiB the harness wants, and this session**: a full GUI install was occupying the only disposable disk.
there is no already-installed disposable clone available. Booting the recovery `make doctor` now reports ~29 GiB free (the disk blocker recorded in the last
entry offline is still a manual step. `sys undo` is present; treat the VM gate handoff has eased), but the acceptance run needs a dedicated already-installed
as unpassed before relying on it. disposable clone; the exact commands are in `docs/HANDOFF.md`. Booting the
recovery entry offline is still a manual step. `sys undo` is present; treat the
VM gate as unpassed before relying on it.
- **Mango + DankMaterialShell** is the default desktop - **Mango + DankMaterialShell** is the default desktop
(`desktop.profile = "mango"`, Flatpak on). It is implemented with Mango (`desktop.profile = "mango"`, Flatpak on). It is implemented with Mango
0.17.2, DMS (pinned release), Quickshell 0.3.1 and scenefx 0.5 from the GURU 0.17.2, DMS (pinned release), Quickshell 0.3.1 and scenefx 0.5 from the GURU

183
docs/SYS.md Normal file
View file

@ -0,0 +1,183 @@
# `sys` — the deterministic Phoebus system interface
`sys` is the typed, validated execution boundary shared by the assistant and
the offline (no-model) administrator. Whatever the assistant can do, a human can
do by typing the same action; the assistant only makes it easier. The AI path
emits the same closed action schema, and the LLM never holds privilege: every
mutation is reviewed and authenticated by a human through the privileged broker.
```
sys <phrase> # deterministic parser (no model)
sys --action '<json>' # one typed action
sys --action-file plan.json # a typed action from a file
sys ask "<request>" # assistant proposes the same typed actions
```
Run `sys --help` for the flags. Mutating actions require root (`sudo sys ...`).
Without a model, `sys ask` prints the deterministic equivalent and exits.
## Commands and typed actions
### Services (Portage/systemd ownership)
| Phrase | Typed action | Kind |
| --- | --- | --- |
| `inspect sshd` | `inspect_service` | read |
| `enable sshd` | `enable_service` | mutate |
| `disable sshd` | `disable_service` | mutate |
| `start sshd` | `start_service` | mutate |
| `stop sshd` | `stop_service` | mutate |
| `restart sshd` | `restart_service` | mutate |
### Packages (Portage)
| Phrase | Typed action | Kind |
| --- | --- | --- |
| `install vim` / `add vim` | `install_package` | mutate |
| `remove vim` / `uninstall vim` | `remove_package` | mutate |
| `search firefox` / `find firefox` | `search_packages` | read |
| `update` | `update_system` | mutate |
| `prepare updates` | `prepare_updates` | mutate |
| `what are you compiling` | `inspect_updates` | read |
| *(JSON only)* | `inspect_package` | read |
### Source selection (all lanes)
| Phrase | Typed action | Kind |
| --- | --- | --- |
| `choose firefox` | `choose_package` | read |
| `choose firefox via flatpak` | `choose_package` | read |
| `choose spotify as a gui sandboxed app` | `choose_package` | read |
| `prefer firefox via flatpak` | `set_package_preference` | mutate |
| `prefer firefox auto` | `set_package_preference` | mutate |
`choose` resolves real backend metadata, applies the shared policy
(ADR 0006), and prints the selected lane, version, provenance, integrity,
sandbox level, sizes, update behaviour and the rejected alternatives. It never
installs anything and never fabricates a candidate.
### Flatpak
| Phrase | Typed action | Kind |
| --- | --- | --- |
| `flatpak install org.chromium.Chromium` | `flatpak_install` | mutate |
| `flatpak remove org.chromium.Chromium` | `flatpak_remove` | mutate |
| `flatpak list` | `flatpak_list` | read |
### Nix (developer lane)
| Phrase | Typed action | Kind |
| --- | --- | --- |
| `nix prepare nodejs python312` | `nix_prepare` | mutate |
### Snap (opt-in; `app-containers/snapd` through Portage)
| Phrase | Typed action | Kind |
| --- | --- | --- |
| `snap find notes` | `snap_find` | read |
| `snap info thunderbird` | `snap_info` | read |
| `snap install thunderbird [channel]` | `snap_install` | mutate |
| `snap remove thunderbird` | `snap_remove` | mutate |
| `snap list` | `snap_list` | read |
| `snap refresh [name]` | `snap_refresh` | mutate |
| `snap connections thunderbird` | `snap_connections` | read |
Snap requires a ready `snapd` daemon. If it is absent, `snap_install` installs
`app-containers/snapd` through Portage and enables `snapd.socket` first.
Confinement is detected (`strict`/`partial`/`none`); `--classic` is only used
when the typed action sets `"classic": true` and is shown in the review. The
plan notes that snapd also refreshes automatically.
### AppImage (opt-in; managed, not sandboxed)
| Phrase | Typed action | Kind |
| --- | --- | --- |
| `appimage import /path/App.AppImage` | `appimage_import` | mutate |
| *(JSON only)* | `appimage_acquire` | mutate |
| *(JSON only)* | `appimage_update` | mutate |
| `appimage remove name` | `appimage_remove` | mutate |
| `appimage info name` | `appimage_info` | read |
| `appimage list` | `appimage_list` | read |
Acquisition requires a pinned SHA-256; a placeholder or mismatch is refused and
the download is discarded. Architecture is read from the ELF header without
executing the image. Desktop entries are installed, and user data is preserved
on removal unless `"purge_data": true`. AppImage provides **no application
sandbox** and is described as such.
### Custom ebuilds (Phoebus overlay)
| Phrase | Typed action | Kind |
| --- | --- | --- |
| `ebuilds` / `custom ebuilds` | `custom_ebuild_list` | read |
| *(JSON only)* | `custom_ebuild_prepare` | mutate |
| *(JSON only)* | `custom_ebuild_install` | mutate |
| *(JSON only)* | `custom_ebuild_remove` | mutate |
A custom ebuild is untrusted executable code. `custom_ebuild_prepare` writes it
to `/var/db/repos/phoebus` with a rationale and the SHA-256 of its exact
content; it does not build it. `custom_ebuild_install` requires that same
digest, regenerates the `Manifest` and builds through Portage with its sandbox
enabled. Editing the staged ebuild invalidates the approval.
### Snapshots and rollback
| Phrase | Typed action | Kind |
| --- | --- | --- |
| `snapshot before update` | `create_snapshot` | mutate |
| `undo` / `rollback` | `undo` | mutate |
| `undo status` | `rollback_status` | read |
| `history` | `history` | read |
## Acceptance matrix
The matrix below is the repeatable acceptance suite. `installer/tests/vm/
sys-acceptance.sh` runs the deterministic and JSON groups inside a booted,
installed, detached VM and prints a machine-readable summary; it is safe to run
with no network and no model.
| # | Case | Command | Expected |
| --- | --- | --- | --- |
| 1 | Identity | `sys --version` | prints the version, exit 0 |
| 2 | Read-only history | `sys history` | state, exit 0, no mutation |
| 3 | Invalid natural operand | `sys -- install --color=n` | rejected, nonzero |
| 4 | Unknown phrase | `sys frobnicate` | rejected, nonzero, examples shown |
| 5 | JSON unknown action | `--action '{"action":"run_shell"}'` | fail closed, nonzero |
| 6 | JSON unknown field | `--action '{"action":"history","x":1}'` | fail closed, nonzero |
| 7 | Option-like operand (JSON) | `install_package atom="-C"` | rejected before any command |
| 8 | Invalid Snap name | `snap_install name="Bad Name"` | rejected, nonzero |
| 9 | Invalid AppImage hash | `appimage_acquire sha256="00"` | rejected, nonzero |
| 10 | Ebuild path traversal | `custom_ebuild_prepare atom="../../x"` | rejected, nonzero |
| 11 | Choose with no lane | `sys choose unused-name` | selection or clear failure, never invented |
| 12 | Inventory (empty root) | `--root T appimage list` / `ebuilds` | "no managed …", exit 0 |
| 13 | Mutating as non-root | `set_package_preference` | refused: needs root |
| 14 | Snap daemon absent | `snap list` on a system without snapd | useful error, nonzero |
| 15 | Install a tiny package | `sys install app-misc/hello` (Portage) | installed; `emerge -p` confirms; recorded in `sys history` |
| 16 | Remove it | `sys remove app-misc/hello` | removed; recorded |
| 17 | Service lifecycle | `sys enable/start/stop sshd` | unit state matches `systemctl` |
| 18 | Update preparation | `sys prepare updates` then `what are you compiling` | state reported truthfully |
| 19 | Snapshot + undo | `sys snapshot`, mutate, `sys undo`, reboot | root/var/package state restored |
| 20 | Approval rejected | answer `n` at the prompt | no mutation, nonzero |
| 21 | Plan changed between review and exec | concurrent metadata change | aborts, nonzero |
| 22 | Offline `sys ask` | `sys ask "<request>"` with no provider | deterministic fallback, nonzero |
Cases 1–14 and 21–22 are covered by host tests
(`crates/phoebus-core/src/selection.rs`, `.../action.rs`,
`crates/phoebus-executor/src/{snap,appimage,ebuild,chooser}.rs`, and
`crates/phoebus-installer/tests/sys_cli.rs`). Cases 15–20 and the in-VM subset
of 1–14 are exercised by the VM acceptance script; their current verification
status is recorded in `docs/STATUS.md`.
## Security properties
- **No shell.** Every command is an argument vector through
`phoebus-executor::Exec`; there is no `sh -c` on any path.
- **Validated at the boundary.** Every action (manual, JSON, or AI) is
re-validated before a command is built; option-like operands are rejected.
- **Target-root isolation.** Alternate-root operations are chrooted; runtime
operations (services, Snap) refuse an alternate root.
- **Approval binding.** A resolved plan has a digest; a material change between
review and execution aborts. A custom ebuild binds approval to its content
digest.
- **Secrets** travel only through mode-0600 files/stdin and are redacted from
logs and history.

View file

@ -1,23 +1,37 @@
# ADR 0006: Package lanes — Portage, Flatpak, and Nix (built in) # ADR 0006: Package lanes and hardware-aware software selection
- **Status:** Accepted - **Status:** Accepted, revised 2026-09-24
- **Date:** 2026-09-20 - **Date:** 2026-09-20 (revised 2026-09-24)
## Context ## Context
Phoebus is built on Gentoo/Portage and must stay a thin layer over it. There is Phoebus is built on Gentoo/Portage and must stay a thin layer over it. There is
a real need for **binary options for non-core software** (developer tooling, a real need for **binary and sandboxed options for non-core software** without
alternate versions, packages awkward or slow to compile) without (a) maintaining a private Gentoo binhost or letting a second package manager claim
maintaining a private Gentoo binhost, or (b) letting a second package manager ownership of the system.
claim ownership of the system.
The decision here is that **Nix is part of the distro by default** — the same The original decision (2026-09-20) adopted three lanes and a **fixed category
way the AI assistant is: always present and ready, but never authoritative and routing**: system/compiler/driver → Portage; GUI → Flatpak; per-project/dev →
never required. A Phoebus system must remain completely usable with Portage Nix. In practice that routing is wrong. A given application can be a good fit
alone; a user who ignores Nix must not notice it. for different lanes on different machines and for different users:
Options considered: a second distro via Distrobox/pacman, Nix, Homebrew, native - a GUI application available both as a cheap, well-integrated Gentoo source
`-bin` ebuilds, a third-party Gentoo binhost, and Flatpak. build and as a heavier Flatpak might be better from source on a
high-core workstation with a matching USE set, and better as a Flatpak on a
low-RAM laptop or when a sandbox is required;
- a developer tool may be best from Nix for a pinned, reproducible, per-project
version, and best from Portage when it is already installed or cheap to
compile;
- some software has no maintained candidate at all and needs a local ebuild.
Category is therefore a **hint**, not a decision. This ADR revises the decision
to a shared, inspectable, hardware- and preference-aware selection policy, and
extends the lane set.
Options considered for the selection problem: fixed category routing
(rejected), a fully scripted per-application table (rejected: opaque,
unmaintainable, still wrong on other hardware), and a shared deterministic
policy consuming resolved backend metadata (adopted).
Relevant facts established: Relevant facts established:
@ -27,25 +41,83 @@ Relevant facts established:
- `nix` is not in the Gentoo main tree, so Phoebus ships and manages it itself. - `nix` is not in the Gentoo main tree, so Phoebus ships and manages it itself.
- Nix is strong for reproducible, multi-version developer environments and poor - Nix is strong for reproducible, multi-version developer environments and poor
for GPU/Wayland desktop apps on a non-NixOS host (`nixGL`, Electron sandbox). for GPU/Wayland desktop apps on a non-NixOS host (`nixGL`, Electron sandbox).
- Flatpak is already designed into Phoebus and is the right fit for sandboxed - Flatpak is already designed into Phoebus and is the right fit for many
GUI apps. sandboxed GUI apps.
- Snap can be added through Gentoo's `app-containers/snapd` package (systemd is
mandatory, AppArmor recommended; verified against the Gentoo wiki). It brings
channel/refresh semantics and its own confinement model.
- AppImages are single executable files with **no built-in sandbox**; they are
useful when no maintained package exists, but must be managed honestly.
- A local ebuild is occasionally the only correct answer; it is executable
untrusted code and needs an explicit, isolated build path.
## Decision ## Decision
Adopt **three package lanes**, all present on a default install, with strict Adopt **lanes with strict ownership** plus a **single shared selection policy**
ownership: used by both the deterministic `sys` front-end and the assistant.
| Lane | Owns | Availability | | Lane | Owns / is suitable for | Availability |
| ---- | ---- | ------------ | | ---- | ---------------------- | ------------ |
| **Portage** (authoritative) | kernel, drivers, systemd, Mesa, PipeWire, core libraries, boot stack, system services, compilers/toolchain | always | | **Portage source** (authoritative) | kernel, drivers, systemd, Mesa, PipeWire, core libraries, boot stack, system services, compilers/toolchain; cheap, well-integrated source builds | always |
| **Flatpak** | graphical desktop apps (Chromium, Firefox, Spotify, Electron), sandboxed | always | | **Portage binary** (official binhost) | packages whose USE matches the signed official binhost and whose local compile cost is high with little practical benefit | when a binhost is configured |
| **Nix** | developer tools, alternate versions, reproducible per-project environments, packages inconvenient in Portage | always, user-level use | | **Portage vendor (`-bin`/`-launcher`)** | vendor blobs (`google-chrome`, `steam-launcher`, `discord-bin`, …) | vendor ebuild present |
| **Flatpak** | sandboxed graphical applications; multi-distro binaries | always (default desktop) |
| **Nix** | developer tools, alternate versions, reproducible per-project environments | always, user-level use |
| **Snap** | applications distributed as snaps, when the user wants the Snap Store and its channel/refresh model | opt-in; `app-containers/snapd` through Portage |
| **AppImage** | a single-file application with no maintained package, adopted with pinned integrity | opt-in, managed inventory |
| **Custom ebuild** | a maintained package that is unsuitable or absent and cannot be met otherwise | Phoebus overlay, approval-gated |
Portage's native **`-bin` ebuilds** (`google-chrome`, `steam-launcher`, Portage's ownership is unchanged: **Snap, AppImage and the custom overlay may
`discord-bin`, ...) remain the vendor-blob lane; no new tool is introduced for never provide kernel, drivers, Mesa, PipeWire, systemd, core libraries or
them. boot.** The custom overlay is compiled by Portage; Snap and AppImage are
explicitly non-authoritative.
Nix is **baked in**, but "baked in" describes availability, not authority: ## The selection policy
The policy lives in `phoebus-core::selection` and is pure: it consumes
already-resolved candidates (real backend metadata gathered by
`phoebus-executor::chooser`) plus hardware facts and user preferences, and
returns a reproducible decision with the reasons alternatives were rejected.
Priority order:
1. **Hard compatibility constraints beat preferences.** Architecture mismatch,
a required sandbox a lane cannot provide, insufficient storage, a required
proprietary artifact, GPU incompatibility, or an unavailable backend remove
a candidate regardless of preference.
2. **Base components stay Portage.** A `base-system` request may only resolve to
a Portage lane. This is the ownership rule above.
3. **Explicit compatible user choices win, and are persisted.** A per-app or
global preference is honoured when a compatible candidate exists; when it
does not, selection **fails with an explanation** and never silently switches
lane.
4. **No automatic category routing.** Suitability is decided from candidate
evidence: measured/estimated compile time, download and install size, shared
runtime cost, sandbox strength, Wayland and desktop integration, provenance,
update reliability, permissions, and the actual hardware (cores, RAM, free
storage, GPU, Wayland session).
5. **No silent migration or duplication.** A lane that already owns an
installed copy is preferred, so an application is not installed twice or
moved between lanes behind the user's back.
6. **Honest estimates.** Compile times are labelled measured (from the
`emerge.log` history) or estimated; compilation is not assumed to be faster
or worth its cost. Unknowns are stated as unknowns.
The review shows the selected package identity, lane, version, provenance,
integrity status, sandbox level, sizes, update behaviour and the rejected
alternatives with their reasons. The same facts, metadata and preferences always
produce the same decision.
### Acquisition and integrity
- Portage source/binary: the existing signed Gentoo verification (ADR 0004).
- Flatpak: flathub GPG; Snap: store signatures; both are sandboxed.
- AppImage: a Phoebus-managed record stores the pinned SHA-256, source URL,
architecture and size; acquisition is refused without a real pinned hash.
- Custom ebuild: staged in the Phoebus overlay with a recorded rationale and a
SHA-256 of the exact ebuild content; approval binds to that digest and any
change invalidates it.
### Nix is baked in, but "baked in" describes availability, not authority
- the Nix toolchain and daemon are shipped and configured by the installer; - the Nix toolchain and daemon are shipped and configured by the installer;
- Portage still installs and updates Nix itself, so the daemon is system-managed - Portage still installs and updates Nix itself, so the daemon is system-managed
@ -53,115 +125,105 @@ Nix is **baked in**, but "baked in" describes availability, not authority:
- no core component, service, library or application depends on Nix being used; - no core component, service, library or application depends on Nix being used;
- ignoring Nix has no effect on the system. - ignoring Nix has no effect on the system.
## How Nix is baked in without surrendering ownership How the pinned, verified Nix bootstrap works without surrendering ownership is
recorded in ADR 0008.
A normal binary ebuild is **not possible**: the upstream Nix installer hardcodes
`/nix`, calls `sudo`, and runs `nix-store --load-db` against the real root, with
no `DESTDIR`/`--root` support. Repackaging it into a target image would require
re-implementing that bootstrap; building Nix from source is a separate, large
option.
1. **Bootstrap the pinned, verified official release** with discrete commands in
the target chroot (no `curl | sh`, no `sh -c`), reproducing the installer's
steps: copy the store, `nix-store --load-db`, create the `nixbld` group and
users, wire the profile, and install/enable the `nix-daemon` units.
2. **Multi-user, systemd-managed.** `nix-daemon.service`/`.socket` are installed
and enabled; the store lives at `/nix`.
3. **Pinned and verified.** The Nix version and tarball SHA-256 are embedded and
checked fail-closed; nixpkgs is pinned per environment (flake lock / channel
revision), never "latest".
4. **No NixOS model.** No `configuration.nix`, no system profiles, no
Nix-managed services. Nix manages user environments only.
5. **On by default, VM-verified.** A disposable-VM install confirmed the
bootstrap (`nix-daemon` active, `nix shell nixpkgs#hello` works), so
`packages.nix` is on by default; `NIX_ENABLED='no'` opts out. Nix is never a
hard dependency of boot, run or recovery.
## Rules ## Rules
1. **Portage is the only authority over the running system.** Nix and Flatpak 1. **Portage is the only authority over the running system.** Nix, Flatpak,
never provide kernel, drivers, Mesa, PipeWire, systemd, core libraries or Snap, AppImage and the custom overlay never provide kernel, drivers, Mesa,
boot. PipeWire, systemd, core libraries or boot.
2. **Nix is user-level in effect.** It provides developer tools and project 2. **Base components are Portage-only.** The selector enforces this as a hard
environments, never system components. constraint.
3. **Never required.** The system is fully functional with Portage alone; the 3. **No silent backend switching.** A failed install is reported; any
base image and all services work if Nix is unused or removed. replacement plan is resolved and approved through the normal path.
4. **GUI apps go to Flatpak, not Nix.** 4. **Explicit choices are respected and persisted; incompatible ones error.**
5. **No arbitrary remote evaluation by default.** Nix commands run by the 5. **Snap and AppImage are honest about their guarantees.** Snap confinement is
assistant are bounded (no arbitrary flakes or URLs), so eval-time fetching detected, not assumed; classic confinement is a security downgrade and is
is not an AI-reachable supply-chain surface. explicit; AppImage is never described as sandboxed and is never executed just
to inspect it.
6. **Removal preserves user data by default.** Each lane's removal removes only
what Phoebus manages; a Btrfs snapshot does not automatically reverse another
lane's state or external side effects, and this is stated.
7. **No arbitrary remote evaluation by default.** Nix commands run by the
assistant are bounded (no arbitrary flakes or URLs). Snap/Flatpak/AppImage
operations use bounded identifiers/URLs and pinned hashes.
8. **The custom overlay is untrusted code.** The model may propose an ebuild;
staging never runs it. Building happens only through the deterministic broker
after approval of the exact digest, inside the target with Portage's build
sandbox.
## AI integration ## AI integration
The differentiated use is a typed, assistant-driven action: The assistant and the deterministic CLI emit the same typed schema. Software
selection is a typed, read-only action:
``` ```
CreateDevEnvironment { name, packages[], versions[] } ChoosePackage { name, kind?, backend?, gui?, requires_sandbox? }
``` ```
- executed unprivileged through `Exec` (no shell, no root for the user action); The selector reports the lane and the rejected alternatives. Persisting a
- inputs validated against a bounded set; choice is a separate, audited action:
- never mutates the base system;
- the deterministic broker reports which lane satisfied a request.
A future `sys` chooser must prefer deterministically: system/compiler/Mesa/ ```
drivers → Portage only; GUI → Flatpak; per-project/dev → Nix. SetPackagePreference { name, backend? } // backend unset clears it
```
Lane-specific mutations (`snap_*`, `appimage_*`, `custom_ebuild_*`) are bounded
and validated, and a custom ebuild is staged for review before it can build.
The model never gets a shell, and approval binds to the reviewed plan/artifact.
## Explicit non-goals ## Explicit non-goals
- A universal `pkg install` meta-manager that silently picks a source (deferred; - **Fixed category routing.** Rejected: it is wrong on other hardware and for
provenance and support burden). other users; suitability is decided from candidate evidence.
- A universal `pkg install` meta-manager that silently picks a source.
`ChoosePackage` is an *inspectable decision*, not a hidden installer, and it
never executes.
- NixOS-style system configuration. - NixOS-style system configuration.
- A second full distro (Distrobox, pacman) — rejected: a second rootfs to - A second full distro (Distrobox, pacman) — rejected: a second rootfs to
maintain with weaker isolation than Flatpak. maintain with weaker isolation than Flatpak.
- A third-party Gentoo binhost — rejected: trust, signature and availability. - A third-party/private Gentoo binhost — rejected: trust, signature and
- Homebrew — rejected: not packaged for Gentoo, FHS prefix shadowing, and it availability.
adds nothing over Nix for the developer lane. - Homebrew — rejected: not packaged for Gentoo, FHS prefix shadowing.
- Treating AppImage as a sandbox — rejected: it is not one.
## Consequences and risks ## Consequences and risks
- Every install now carries the Nix toolchain, a root daemon, and a growing - Every install carries the Nix toolchain and `/nix`; Snap and AppImage add
`/nix` store; image and disk usage increase. opt-in stores/inventories with their own CVEs and update cadences. The
- There are now two trust/update pipelines (`gentoo` + `nixpkgs`) on every selector surfaces update reliability per lane.
system, each with its own CVEs and update cadence. The daemon being - The policy is a transparent heuristic, not a benchmark. It labels measured vs
Portage-managed keeps ownership clear, but the risk is real and must be estimated data and reports unknowns; it must not be presented as measured
documented to users. performance.
- GUI/GPU stays Flatpak's job, consistent with this session's finding that Nix - Two trust/update pipelines (`gentoo` + `nixpkgs`) exist on every system; the
is a poor fit there. daemon being Portage-managed keeps ownership clear.
- The `nix-daemon` runs as root; it is a privileged component and must be - The custom overlay increases the support surface; it is approval-gated and
treated as one (service hardening, update tracking). records why each entry exists.
## Next steps
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) ## Binary strategy (reconciled)
The roadmap once proposed publishing a private signed binhost to stop the The sustainable strategy remains:
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
- **Portage source or the official signed Gentoo binhost**, whichever matches the binhost is maintained.
package's USE. Signature verification stays on (ADR 0004); no private binhost - **Flatpak / Snap** for sandboxed applications the official binhost cannot
is maintained. serve.
- **Flatpak** for sandboxed GUI applications that the official binhost cannot
serve (Chromium, Spotify, Electron).
- **Nix** for developer tools, alternate versions and reproducible per-project - **Nix** for developer tools, alternate versions and reproducible per-project
environments (ADR 0008). environments (ADR 0008).
- **AppImage / custom ebuild** only when no maintained candidate is suitable,
with explicit integrity and an approval gate.
Packages the official OpenRC/hardened binhost cannot satisfy (systemd, polkit, Packages the official OpenRC/hardened binhost cannot satisfy (systemd, polkit,
NetworkManager, a desktop USE set) compile from source. That cost is accepted 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 and measured (`docs/STATUS.md` records the compile times), not hidden behind a
new binhost. new binhost.
## Next steps
1. Wire `ChoosePackage` into the installed assistant and GUI so a user can see
the lane decision and override it without a model.
2. VM-verify each new lane end to end: Snap install/refresh/remove, AppImage
acquire/launch/remove, and one custom-ebuild build.
3. Add `pkgcheck`-based QA to the custom-ebuild stage gate.

View file

@ -11,7 +11,7 @@ and link it here.
| [0003](0003-desktop-systemd-profile.md) | Desktop installs inherit the Gentoo desktop/systemd profile | 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 | | [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 | | [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 | | [0006](0006-package-lanes.md) | Package lanes and hardware-aware software selection | Accepted (revised 2026-09-24) |
| [0007](0007-coherent-rollback.md) | Coherent rollback and recovery | Accepted | | [0007](0007-coherent-rollback.md) | Coherent rollback and recovery | Accepted |
| [0008](0008-nix-isolation-lifecycle.md) | Nix lifecycle, build isolation, and packaging | 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 | | [0009](0009-mango-dankmaterialshell-desktop.md) | Mango + DankMaterialShell desktop option | Accepted |

View file

@ -68,19 +68,30 @@ pub const ASSISTANT_PROMPT: &str = "\
You are the Phoebus OS system assistant. You can ONLY propose actions from this \ You are the Phoebus OS system assistant. You can ONLY propose actions from this \
closed set: inspect_service, enable_service, disable_service, start_service, \ closed set: inspect_service, enable_service, disable_service, start_service, \
stop_service, restart_service, inspect_package, \ stop_service, restart_service, inspect_package, \
install_package, remove_package, search_packages, flatpak_install, flatpak_remove, \ install_package, remove_package, search_packages, choose_package, flatpak_install, \
flatpak_list, nix_prepare, create_snapshot, undo, rollback_status, history, \ flatpak_remove, flatpak_list, nix_prepare, snap_find, snap_info, snap_install, \
snap_remove, snap_list, snap_refresh, snap_connections, appimage_import, \
appimage_acquire, appimage_update, appimage_remove, appimage_info, appimage_list, \
custom_ebuild_prepare, custom_ebuild_install, custom_ebuild_remove, \
custom_ebuild_list, create_snapshot, undo, rollback_status, history, \
update_system, prepare_updates, inspect_updates. update_system, prepare_updates, inspect_updates.
Reply with ONLY a JSON object: Reply with ONLY a JSON object:
{\"version\":1,\"summary\":\"...\",\"actions\":[{\"action\":\"...\",...}],\ {\"version\":1,\"summary\":\"...\",\"actions\":[{\"action\":\"...\",...}],\
\"rationale\":[{\"action\":\"...\",\"reason\":\"...\"}]} \"rationale\":[{\"action\":\"...\",\"reason\":\"...\"}]}
Rules: give every action a non-empty reason; prefer inspection before mutation; \ Rules: give every action a non-empty reason; prefer inspection before mutation. \
never propose disabling verification, enabling ~amd64 globally, weakening \ Do not choose a software lane by category alone: use choose_package to compare \
LUKS2/Btrfs/systemd/UEFI, or any shell, file or arbitrary command action. You do \ the available lanes against the machine (architecture, memory, storage, GPU, \
not have a shell, credentials, or access to private files. A human reviews and \ Wayland) and the user's preferences, or install_package for an explicit Portage \
authenticates every mutation."; request. Base system components (kernel, drivers, systemd, the host graphics and \
audio stack, boot tooling) stay under Portage. A custom ebuild is untrusted, \
executable content: stage it with custom_ebuild_prepare so a human reviews the \
artifact and its digest; never assume it will build. 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. /// Parse and validate an assistant plan, fail-closed.
pub fn parse_plan(text: &str) -> Result<AssistantPlan, AiError> { pub fn parse_plan(text: &str) -> Result<AssistantPlan, AiError> {

View file

@ -7,6 +7,8 @@
use serde::{Deserialize, Serialize}; use serde::{Deserialize, Serialize};
use crate::selection::{Backend, PackageKind};
#[derive(Debug, thiserror::Error)] #[derive(Debug, thiserror::Error)]
pub enum ActionError { pub enum ActionError {
#[error("invalid action JSON: {0}")] #[error("invalid action JSON: {0}")]
@ -86,6 +88,123 @@ pub enum SystemAction {
UpdateSystem, UpdateSystem,
PrepareUpdates, PrepareUpdates,
InspectUpdates, InspectUpdates,
// ------------------------------------------------------------------
// Shared, hardware-aware package selection (read-only decision).
// ------------------------------------------------------------------
/// Show which backend/lane should satisfy a request, with the evidence and
/// the alternatives rejected. Never installs anything.
ChoosePackage {
name: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
kind: Option<PackageKind>,
#[serde(default, skip_serializing_if = "Option::is_none")]
backend: Option<Backend>,
#[serde(default)]
gui: bool,
#[serde(default)]
requires_sandbox: bool,
},
/// Persist (or clear) an explicit backend preference for an application.
/// The deterministic selector and the assistant both honour it.
SetPackagePreference {
name: String,
/// `None` clears the preference and returns to automatic selection.
#[serde(default, skip_serializing_if = "Option::is_none")]
backend: Option<Backend>,
},
// ------------------------------------------------------------------
// Snap lane.
// ------------------------------------------------------------------
SnapFind {
query: String,
},
SnapInfo {
name: String,
},
SnapInstall {
name: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
channel: Option<String>,
/// Classic confinement is a security downgrade and must be explicit.
#[serde(default)]
classic: bool,
},
SnapRemove {
name: String,
},
SnapList,
SnapRefresh {
#[serde(default, skip_serializing_if = "Option::is_none")]
name: Option<String>,
},
/// Show the connections (permissions) a snap currently holds or requests.
SnapConnections {
name: String,
},
// ------------------------------------------------------------------
// AppImage lane.
// ------------------------------------------------------------------
/// Adopt a local AppImage under Phoebus management (hash recorded).
#[serde(rename = "appimage_import")]
AppImageImport {
path: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
name: Option<String>,
},
/// Download and adopt an AppImage with a pinned SHA-256.
#[serde(rename = "appimage_acquire")]
AppImageAcquire {
name: String,
url: String,
sha256: String,
},
/// Re-acquire a newer AppImage from a pinned URL + SHA-256.
#[serde(rename = "appimage_update")]
AppImageUpdate {
name: String,
url: String,
sha256: String,
},
#[serde(rename = "appimage_remove")]
AppImageRemove {
name: String,
/// Remove the application's user data too (default: preserve it).
#[serde(default)]
purge_data: bool,
},
#[serde(rename = "appimage_info")]
AppImageInfo {
name: String,
},
#[serde(rename = "appimage_list")]
AppImageList,
// ------------------------------------------------------------------
// Phoebus-managed custom ebuild lane.
// ------------------------------------------------------------------
/// Stage a reviewed custom ebuild in the Phoebus overlay. Writes the
/// artifact but does not build or install it.
CustomEbuildPrepare {
atom: String,
version: String,
rationale: String,
/// The full ebuild text. Treated as untrusted, executable content.
ebuild: String,
},
/// Build and install a staged ebuild whose content still matches `digest`.
CustomEbuildInstall {
atom: String,
version: String,
digest: String,
},
CustomEbuildRemove {
atom: String,
},
CustomEbuildList,
} }
impl SystemAction { impl SystemAction {
@ -128,6 +247,79 @@ impl SystemAction {
} }
SystemAction::InspectUpdates => "show background update preparation status".to_string(), SystemAction::InspectUpdates => "show background update preparation status".to_string(),
SystemAction::UpdateSystem => "update the system".to_string(), SystemAction::UpdateSystem => "update the system".to_string(),
SystemAction::ChoosePackage {
name,
kind,
backend,
..
} => {
let mut s = format!("choose the best source for {name}");
if let Some(kind) = kind {
s.push_str(&format!(" ({})", kind.as_str()));
}
if let Some(backend) = backend {
s.push_str(&format!(", preferring {}", backend.as_str()));
}
s
}
SystemAction::SetPackagePreference { name, backend } => match backend {
Some(backend) => format!("prefer {} for {name}", backend.as_str()),
None => format!("clear the backend preference for {name}"),
},
SystemAction::SnapFind { query } => format!("search the Snap store for `{query}`"),
SystemAction::SnapInfo { name } => format!("inspect snap {name}"),
SystemAction::SnapInstall {
name,
channel,
classic,
} => {
let mut s = format!("install snap {name}");
if let Some(channel) = channel {
s.push_str(&format!(" from channel {channel}"));
}
if *classic {
s.push_str(" with classic (unconfined) confinement");
}
s
}
SystemAction::SnapRemove { name } => format!("remove snap {name}"),
SystemAction::SnapList => "list installed snaps".to_string(),
SystemAction::SnapRefresh { name } => match name {
Some(name) => format!("refresh snap {name}"),
None => "refresh all snaps".to_string(),
},
SystemAction::SnapConnections { name } => format!("show snap {name} connections"),
SystemAction::AppImageImport { path, name } => format!(
"import AppImage {path}{}",
name.as_deref()
.map(|n| format!(" as {n}"))
.unwrap_or_default()
),
SystemAction::AppImageAcquire { name, url, .. } => {
format!("download and manage AppImage {name} from {url}")
}
SystemAction::AppImageUpdate { name, url, .. } => {
format!("update managed AppImage {name} from {url}")
}
SystemAction::AppImageRemove { name, purge_data } => {
if *purge_data {
format!("remove AppImage {name} and its user data")
} else {
format!("remove AppImage {name} (preserving user data)")
}
}
SystemAction::AppImageInfo { name } => format!("inspect managed AppImage {name}"),
SystemAction::AppImageList => "list managed AppImages".to_string(),
SystemAction::CustomEbuildPrepare { atom, version, .. } => {
format!("stage a custom ebuild for {atom}-{version} (not installed)")
}
SystemAction::CustomEbuildInstall { atom, version, .. } => {
format!("build and install custom ebuild {atom}-{version}")
}
SystemAction::CustomEbuildRemove { atom } => {
format!("remove the custom ebuild package {atom}")
}
SystemAction::CustomEbuildList => "list Phoebus-managed custom ebuilds".to_string(),
} }
} }
@ -142,6 +334,14 @@ impl SystemAction {
SystemAction::InspectUpdates => Risk::Low, SystemAction::InspectUpdates => Risk::Low,
SystemAction::RollbackStatus => Risk::Low, SystemAction::RollbackStatus => Risk::Low,
SystemAction::FlatpakList => Risk::Low, SystemAction::FlatpakList => Risk::Low,
SystemAction::ChoosePackage { .. }
| SystemAction::SnapFind { .. }
| SystemAction::SnapInfo { .. }
| SystemAction::SnapList
| SystemAction::SnapConnections { .. }
| SystemAction::AppImageInfo { .. }
| SystemAction::AppImageList
| SystemAction::CustomEbuildList => Risk::Low,
SystemAction::PrepareUpdates => Risk::Medium, SystemAction::PrepareUpdates => Risk::Medium,
SystemAction::EnableService { .. } SystemAction::EnableService { .. }
| SystemAction::DisableService { .. } | SystemAction::DisableService { .. }
@ -151,11 +351,22 @@ impl SystemAction {
| SystemAction::CreateSnapshot { .. } | SystemAction::CreateSnapshot { .. }
| SystemAction::FlatpakInstall { .. } | SystemAction::FlatpakInstall { .. }
| SystemAction::FlatpakRemove { .. } | SystemAction::FlatpakRemove { .. }
| SystemAction::NixPrepare { .. } => Risk::Medium, | SystemAction::NixPrepare { .. }
| SystemAction::SetPackagePreference { .. }
| SystemAction::SnapInstall { .. }
| SystemAction::SnapRemove { .. }
| SystemAction::SnapRefresh { .. }
| SystemAction::AppImageImport { .. }
| SystemAction::AppImageAcquire { .. }
| SystemAction::AppImageUpdate { .. }
| SystemAction::AppImageRemove { .. }
| SystemAction::CustomEbuildPrepare { .. } => Risk::Medium,
SystemAction::InstallPackage { .. } SystemAction::InstallPackage { .. }
| SystemAction::RemovePackage { .. } | SystemAction::RemovePackage { .. }
| SystemAction::UpdateSystem | SystemAction::UpdateSystem
| SystemAction::Undo { .. } => Risk::High, | SystemAction::Undo { .. }
| SystemAction::CustomEbuildInstall { .. }
| SystemAction::CustomEbuildRemove { .. } => Risk::High,
} }
} }
@ -171,6 +382,14 @@ impl SystemAction {
| SystemAction::InspectUpdates | SystemAction::InspectUpdates
| SystemAction::RollbackStatus | SystemAction::RollbackStatus
| SystemAction::FlatpakList | SystemAction::FlatpakList
| SystemAction::ChoosePackage { .. }
| SystemAction::SnapFind { .. }
| SystemAction::SnapInfo { .. }
| SystemAction::SnapList
| SystemAction::SnapConnections { .. }
| SystemAction::AppImageInfo { .. }
| SystemAction::AppImageList
| SystemAction::CustomEbuildList
) )
} }
@ -251,6 +470,143 @@ impl SystemAction {
| SystemAction::PrepareUpdates | SystemAction::PrepareUpdates
| SystemAction::InspectUpdates | SystemAction::InspectUpdates
| SystemAction::RollbackStatus => Ok(()), | SystemAction::RollbackStatus => Ok(()),
SystemAction::ChoosePackage { name, .. } => {
if valid_package_spec(name) {
Ok(())
} else {
Err(format!("invalid package name: {name}"))
}
}
SystemAction::SetPackagePreference { name, .. } => {
if valid_package_spec(name) {
Ok(())
} else {
Err(format!("invalid package name: {name}"))
}
}
SystemAction::SnapFind { query } => {
if valid_search_query(query) {
Ok(())
} else {
Err(format!("invalid Snap search query: {query}"))
}
}
SystemAction::SnapInfo { name }
| SystemAction::SnapRemove { name }
| SystemAction::SnapConnections { name } => {
if valid_snap_name(name) {
Ok(())
} else {
Err(format!("invalid snap name: {name}"))
}
}
SystemAction::SnapInstall { name, channel, .. } => {
if !valid_snap_name(name) {
return Err(format!("invalid snap name: {name}"));
}
if let Some(channel) = channel {
if !valid_snap_channel(channel) {
return Err(format!("invalid snap channel: {channel}"));
}
}
Ok(())
}
SystemAction::SnapList => Ok(()),
SystemAction::SnapRefresh { name } => match name {
Some(name) if !valid_snap_name(name) => Err(format!("invalid snap name: {name}")),
_ => Ok(()),
},
SystemAction::AppImageImport { path, name } => {
if path.is_empty() || path.len() > 4096 || path.contains('\0') {
return Err("invalid AppImage path".into());
}
if let Some(name) = name {
if !valid_appimage_name(name) {
return Err(format!("invalid AppImage name: {name}"));
}
}
Ok(())
}
SystemAction::AppImageAcquire { name, url, sha256 }
| SystemAction::AppImageUpdate { name, url, sha256 } => {
if !valid_appimage_name(name) {
return Err(format!("invalid AppImage name: {name}"));
}
if !valid_http_url(url) {
return Err(format!("invalid AppImage URL: {url}"));
}
if !valid_sha256(sha256) {
return Err(
"AppImage SHA-256 must be 64 hex characters (not a placeholder)".into(),
);
}
Ok(())
}
SystemAction::AppImageRemove { name, .. } => {
if valid_appimage_name(name) {
Ok(())
} else {
Err(format!("invalid AppImage name: {name}"))
}
}
SystemAction::AppImageInfo { name } => {
if valid_appimage_name(name) {
Ok(())
} else {
Err(format!("invalid AppImage name: {name}"))
}
}
SystemAction::AppImageList => Ok(()),
SystemAction::CustomEbuildPrepare {
atom,
version,
rationale,
ebuild,
} => {
if !valid_ebuild_atom(atom) {
return Err(format!("invalid ebuild atom: {atom}"));
}
if !valid_ebuild_version(version) {
return Err(format!("invalid ebuild version: {version}"));
}
if rationale.trim().is_empty() || rationale.len() > 4096 {
return Err("custom ebuild requires a bounded rationale".into());
}
if ebuild.trim().is_empty() {
return Err("custom ebuild content must not be empty".into());
}
if ebuild.len() > 256 * 1024 {
return Err("custom ebuild content is too large (max 256 KiB)".into());
}
if ebuild.contains('\0') {
return Err("custom ebuild content contains a NUL byte".into());
}
Ok(())
}
SystemAction::CustomEbuildInstall {
atom,
version,
digest,
} => {
if !valid_ebuild_atom(atom) {
return Err(format!("invalid ebuild atom: {atom}"));
}
if !valid_ebuild_version(version) {
return Err(format!("invalid ebuild version: {version}"));
}
if !valid_sha256(digest) {
return Err("custom ebuild digest must be 64 hex characters".into());
}
Ok(())
}
SystemAction::CustomEbuildRemove { atom } => {
if valid_ebuild_atom(atom) {
Ok(())
} else {
Err(format!("invalid ebuild atom: {atom}"))
}
}
SystemAction::CustomEbuildList => Ok(()),
} }
} }
} }
@ -325,6 +681,90 @@ pub fn valid_nix_attribute(value: &str) -> bool {
&& !value.contains(':') && !value.contains(':')
} }
/// A snap name: lower-case letters, digits and single hyphens; must start and
/// end alphanumeric; at most 40 characters (snapd's own rule).
pub fn valid_snap_name(value: &str) -> bool {
if value.is_empty() || value.len() > 40 {
return false;
}
if value.starts_with('-') || value.ends_with('-') || value.contains("--") {
return false;
}
value
.chars()
.all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '-')
}
/// A snap channel: `track/risk/branch` with the usual building blocks. No
/// spaces, slashes beyond the two separators, or shell metacharacters.
pub fn valid_snap_channel(value: &str) -> bool {
!value.is_empty()
&& value.len() <= 64
&& !value.starts_with('-')
&& value.split('/').count() <= 3
&& value
.chars()
.all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || "-._".contains(c) || c == '/')
}
/// A managed AppImage name (a bounded, filesystem-safe identifier).
pub fn valid_appimage_name(value: &str) -> bool {
if value.is_empty() || value.len() > 64 {
return false;
}
if value.starts_with('.') || value.starts_with('-') {
return false;
}
value
.chars()
.all(|c| c.is_ascii_alphanumeric() || "._-".contains(c))
&& !value.contains("..")
}
/// An `http`/`https` URL with no whitespace or control characters.
pub fn valid_http_url(value: &str) -> bool {
!value.is_empty()
&& value.len() <= 2048
&& (value.starts_with("https://") || value.starts_with("http://"))
&& !value.chars().any(|c| c.is_whitespace() || c.is_control())
}
/// A real SHA-256: 64 hex characters and not the all-zero placeholder.
pub fn valid_sha256(value: &str) -> bool {
value.len() == 64
&& value.chars().all(|c| c.is_ascii_hexdigit())
&& value.chars().any(|c| c != '0')
}
/// A Gentoo `category/package` atom for the custom overlay. Version and slots
/// are not part of the atom, so `/` appears exactly once.
pub fn valid_ebuild_atom(value: &str) -> bool {
if value.is_empty() || value.len() > 128 {
return false;
}
let mut parts = value.split('/');
let (Some(category), Some(package), None) = (parts.next(), parts.next(), parts.next()) else {
return false;
};
let ok = |s: &str| {
!s.is_empty()
&& !s.starts_with('-')
&& s.chars()
.all(|c| c.is_ascii_alphanumeric() || "+._-".contains(c))
};
ok(category) && ok(package)
}
/// A Gentoo version string (optionally with a `-rN` revision).
pub fn valid_ebuild_version(value: &str) -> bool {
if value.is_empty() || value.len() > 64 || value.starts_with('-') || value.contains('/') {
return false;
}
value
.chars()
.all(|c| c.is_ascii_alphanumeric() || "+._-".contains(c))
}
/// Strip a case-insensitive ASCII prefix, returning the remainder. Used where /// Strip a case-insensitive ASCII prefix, returning the remainder. Used where
/// the operand after the verb is case-sensitive (Flatpak app ids). /// the operand after the verb is case-sensitive (Flatpak app ids).
fn strip_prefix_ascii_ci<'a>(text: &'a str, prefix: &str) -> Option<&'a str> { fn strip_prefix_ascii_ci<'a>(text: &'a str, prefix: &str) -> Option<&'a str> {
@ -450,6 +890,168 @@ fn parse_natural_raw(text: &str) -> Option<SystemAction> {
return Some(SystemAction::FlatpakList); return Some(SystemAction::FlatpakList);
} }
// Snap verbs. Snap names and channels are lower-case, so the lowercased
// copy is safe here.
if let Some(rest) = rest("snap ") {
if let Some(name) = rest.strip_prefix("install ").map(str::trim) {
let mut parts = name.split_whitespace();
let name = parts.next()?;
if !name.is_empty() {
let channel = parts.next().map(str::to_string);
return Some(SystemAction::SnapInstall {
name: name.to_string(),
channel,
classic: false,
});
}
}
if let Some(name) = rest
.strip_prefix("remove ")
.or_else(|| rest.strip_prefix("uninstall "))
.map(str::trim)
{
if !name.is_empty() {
return Some(SystemAction::SnapRemove {
name: name.to_string(),
});
}
}
if let Some(query) = rest
.strip_prefix("find ")
.or_else(|| rest.strip_prefix("search "))
.map(str::trim)
{
if !query.is_empty() {
return Some(SystemAction::SnapFind {
query: query.to_string(),
});
}
}
if let Some(name) = rest.strip_prefix("info ").map(str::trim) {
if !name.is_empty() {
return Some(SystemAction::SnapInfo {
name: name.to_string(),
});
}
}
if let Some(name) = rest.strip_prefix("connections ").map(str::trim) {
if !name.is_empty() {
return Some(SystemAction::SnapConnections {
name: name.to_string(),
});
}
}
if rest == "refresh" {
return Some(SystemAction::SnapRefresh { name: None });
}
if let Some(name) = rest.strip_prefix("refresh ").map(str::trim) {
if !name.is_empty() {
return Some(SystemAction::SnapRefresh {
name: Some(name.to_string()),
});
}
}
if rest == "list" || rest == "snaps" {
return Some(SystemAction::SnapList);
}
}
if t == "snaps" {
return Some(SystemAction::SnapList);
}
// AppImage verbs. Paths are case-sensitive, so read them from the original
// text.
if let Some(rest) = strip_prefix_ascii_ci(raw, "appimage ") {
let rest = rest.trim();
if let Some(path) = strip_prefix_ascii_ci(rest, "import ").map(str::trim) {
if !path.is_empty() {
return Some(SystemAction::AppImageImport {
path: path.to_string(),
name: None,
});
}
}
if let Some(name) = strip_prefix_ascii_ci(rest, "remove ").map(str::trim) {
if !name.is_empty() {
return Some(SystemAction::AppImageRemove {
name: name.to_string(),
purge_data: false,
});
}
}
if let Some(name) = strip_prefix_ascii_ci(rest, "info ").map(str::trim) {
if !name.is_empty() {
return Some(SystemAction::AppImageInfo {
name: name.to_string(),
});
}
}
if rest.eq_ignore_ascii_case("list") {
return Some(SystemAction::AppImageList);
}
}
// Custom ebuild inventory (staging/install are JSON/AI-only: they carry the
// full artifact and are too large and too sensitive for a one-line phrase).
if t == "ebuilds" || t == "custom ebuilds" || t == "custom-ebuilds" {
return Some(SystemAction::CustomEbuildList);
}
// Hardware-aware source choice: `choose firefox`, `choose firefox as a gui
// app`, `choose firefox via flatpak`.
if let Some(rest) = rest("choose ").or_else(|| rest("select source ")) {
let rest = rest.trim();
if !rest.is_empty() {
let mut words = rest.split_whitespace();
let name = words.next().unwrap_or("").to_string();
if !name.is_empty() {
let mut backend = None;
let mut gui = false;
let mut requires_sandbox = false;
let tokens: Vec<&str> = words.collect();
for (i, token) in tokens.iter().enumerate() {
match *token {
"via" | "with" | "using" => {
if let Some(b) = tokens.get(i + 1).and_then(|s| Backend::parse(s)) {
backend = Some(b);
}
}
"gui" | "desktop" => gui = true,
"sandboxed" | "sandbox" => requires_sandbox = true,
_ => {}
}
}
return Some(SystemAction::ChoosePackage {
name,
kind: None,
backend,
gui,
requires_sandbox,
});
}
}
}
// Persisted backend preference: `prefer firefox via flatpak` / `prefer
// firefox auto`.
if let Some(rest) = rest("prefer ") {
let rest = rest.trim();
let tokens: Vec<&str> = rest.split_whitespace().collect();
if let Some(name) = tokens.first() {
if !name.is_empty() {
let backend = match (tokens.get(1), tokens.get(2)) {
(Some(&"auto"), _) | (Some(&"clear"), _) | (None, _) => None,
(Some(&"via" | &"with" | &"using"), Some(b)) => Backend::parse(b),
(Some(b), _) => Backend::parse(b),
};
return Some(SystemAction::SetPackagePreference {
name: name.to_string(),
backend,
});
}
}
}
// Nix development packages. // Nix development packages.
if let Some(packages) = rest("nix prepare ").or_else(|| rest("nix realise ")) { if let Some(packages) = rest("nix prepare ").or_else(|| rest("nix realise ")) {
let packages: Vec<String> = packages.split_whitespace().map(str::to_string).collect(); let packages: Vec<String> = packages.split_whitespace().map(str::to_string).collect();
@ -788,4 +1390,235 @@ mod tests {
}) })
); );
} }
#[test]
fn natural_snap_phrases() {
assert_eq!(
parse_natural("snap install thunderbird"),
Some(SystemAction::SnapInstall {
name: "thunderbird".into(),
channel: None,
classic: false,
})
);
assert_eq!(
parse_natural("snap install code latest/stable"),
Some(SystemAction::SnapInstall {
name: "code".into(),
channel: Some("latest/stable".into()),
classic: false,
})
);
assert_eq!(
parse_natural("snap remove thunderbird"),
Some(SystemAction::SnapRemove {
name: "thunderbird".into()
})
);
assert_eq!(
parse_natural("snap find notes"),
Some(SystemAction::SnapFind {
query: "notes".into()
})
);
assert_eq!(parse_natural("snap list"), Some(SystemAction::SnapList));
assert_eq!(
parse_natural("snap refresh"),
Some(SystemAction::SnapRefresh { name: None })
);
assert_eq!(
parse_natural("snap refresh thunderbird"),
Some(SystemAction::SnapRefresh {
name: Some("thunderbird".into())
})
);
assert_eq!(
parse_natural("snap connections thunderbird"),
Some(SystemAction::SnapConnections {
name: "thunderbird".into()
})
);
}
#[test]
fn natural_appimage_paths_keep_case() {
assert_eq!(
parse_natural("appimage import /home/u/MyTool.AppImage"),
Some(SystemAction::AppImageImport {
path: "/home/u/MyTool.AppImage".into(),
name: None,
})
);
assert_eq!(
parse_natural("appimage list"),
Some(SystemAction::AppImageList)
);
assert_eq!(
parse_natural("appimage info mytool"),
Some(SystemAction::AppImageInfo {
name: "mytool".into()
})
);
assert_eq!(
parse_natural("appimage remove mytool"),
Some(SystemAction::AppImageRemove {
name: "mytool".into(),
purge_data: false,
})
);
}
#[test]
fn natural_choose_phrase() {
assert_eq!(
parse_natural("choose firefox"),
Some(SystemAction::ChoosePackage {
name: "firefox".into(),
kind: None,
backend: None,
gui: false,
requires_sandbox: false,
})
);
assert_eq!(
parse_natural("choose firefox via flatpak"),
Some(SystemAction::ChoosePackage {
name: "firefox".into(),
kind: None,
backend: Some(Backend::Flatpak),
gui: false,
requires_sandbox: false,
})
);
assert_eq!(
parse_natural("choose spotify as a gui sandboxed app"),
Some(SystemAction::ChoosePackage {
name: "spotify".into(),
kind: None,
backend: None,
gui: true,
requires_sandbox: true,
})
);
}
#[test]
fn new_actions_are_classified_and_validated() {
// Snap install is medium risk, mutating, and validates its operands.
let install = parse_action(
r#"{"action":"snap_install","name":"thunderbird","channel":"latest/stable"}"#,
)
.unwrap();
assert_eq!(install.risk(), Risk::Medium);
assert!(install.is_mutating());
assert!(parse_action(r#"{"action":"snap_install","name":"Bad Name"}"#).is_err());
assert!(
parse_action(r#"{"action":"snap_install","name":"ok","channel":"--evil"}"#).is_err()
);
// AppImage acquisition requires a real pinned hash and an http(s) URL.
let acquire = parse_action(
r#"{"action":"appimage_acquire","name":"mytool","url":"https://example.org/mytool.AppImage","sha256":"ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"}"#,
)
.unwrap();
assert_eq!(acquire.risk(), Risk::Medium);
assert!(parse_action(
r#"{"action":"appimage_acquire","name":"mytool","url":"https://example.org/a","sha256":"0000000000000000000000000000000000000000000000000000000000000000"}"#
)
.is_err());
assert!(parse_action(
r#"{"action":"appimage_acquire","name":"mytool","url":"ftp://x/a","sha256":"ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"}"#
)
.is_err());
// Custom ebuild staging carries content and is a medium-risk mutation;
// installing it is high risk (it builds untrusted code).
let prepare = parse_action(
r#"{"action":"custom_ebuild_prepare","atom":"app-misc/example","version":"1.0","rationale":"no maintained package","ebuild":"EAPI=8\n"}"#,
)
.unwrap();
assert_eq!(prepare.risk(), Risk::Medium);
let install = parse_action(
r#"{"action":"custom_ebuild_install","atom":"app-misc/example","version":"1.0","digest":"ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"}"#,
)
.unwrap();
assert_eq!(install.risk(), Risk::High);
assert!(install.is_mutating());
// Path traversal in an atom is refused.
assert!(parse_action(
r#"{"action":"custom_ebuild_prepare","atom":"../../etc/passwd","version":"1.0","rationale":"x","ebuild":"EAPI=8\n"}"#
)
.is_err());
// Read-only new actions.
for (json, expected) in [
(r#"{"action":"snap_list"}"#, SystemAction::SnapList),
(r#"{"action":"appimage_list"}"#, SystemAction::AppImageList),
(
r#"{"action":"custom_ebuild_list"}"#,
SystemAction::CustomEbuildList,
),
] {
let a = parse_action(json).unwrap();
assert_eq!(a, expected);
assert!(!a.is_mutating());
assert_eq!(a.risk(), Risk::Low);
}
}
#[test]
fn natural_preference_phrase() {
assert_eq!(
parse_natural("prefer firefox via flatpak"),
Some(SystemAction::SetPackagePreference {
name: "firefox".into(),
backend: Some(Backend::Flatpak),
})
);
assert_eq!(
parse_natural("prefer firefox auto"),
Some(SystemAction::SetPackagePreference {
name: "firefox".into(),
backend: None,
})
);
let pref =
parse_action(r#"{"action":"set_package_preference","name":"firefox","backend":"nix"}"#)
.unwrap();
assert_eq!(pref.risk(), Risk::Medium);
assert!(pref.is_mutating());
}
#[test]
fn selection_validators_are_strict() {
assert!(valid_snap_name("thunderbird"));
assert!(valid_snap_name("code-insiders"));
assert!(!valid_snap_name("Thunderbird"));
assert!(!valid_snap_name("-leading"));
assert!(!valid_snap_name("double--hyphen"));
assert!(!valid_snap_name(&"a".repeat(41)));
assert!(valid_snap_channel("latest/stable"));
assert!(valid_snap_channel("4.0/edge"));
assert!(!valid_snap_channel("--evil"));
assert!(valid_appimage_name("mytool"));
assert!(valid_appimage_name("My.Tool-2"));
assert!(!valid_appimage_name("../escape"));
assert!(!valid_appimage_name(".hidden"));
assert!(valid_http_url("https://example.org/a.AppImage"));
assert!(!valid_http_url("ftp://example.org/a"));
assert!(!valid_http_url("https://example.org/a b"));
assert!(valid_sha256(&"a".repeat(64)));
assert!(!valid_sha256(&"0".repeat(64)));
assert!(!valid_sha256("deadbeef"));
assert!(valid_ebuild_atom("app-misc/example"));
assert!(!valid_ebuild_atom("app-misc/example/extra"));
assert!(!valid_ebuild_atom("../etc/passwd"));
assert!(valid_ebuild_version("1.2.3-r1"));
assert!(!valid_ebuild_version("../1.0"));
}
} }

View file

@ -18,6 +18,7 @@ pub mod plan;
pub mod policy; pub mod policy;
pub mod rollback; pub mod rollback;
pub mod secret; pub mod secret;
pub mod selection;
pub mod snapshot; pub mod snapshot;
pub mod system; pub mod system;
pub mod target; pub mod target;
@ -40,6 +41,10 @@ pub use policy::{
PackagePolicyEngine, PolicyContext, PackagePolicyEngine, PolicyContext,
}; };
pub use secret::{Redactor, SecretString}; pub use secret::{Redactor, SecretString};
pub use selection::{
select, Backend, Candidate, Capability, HardwareFacts, Need, PackageKind, Preferences,
RejectReason, Rejected, SandboxLevel, Selection, SelectionError, UpdateReliability,
};
pub use target::TargetRoot; pub use target::TargetRoot;
pub use validate::{password_strength, validate_config, ValidationIssue}; pub use validate::{password_strength, validate_config, ValidationIssue};

File diff suppressed because it is too large Load diff

View file

@ -125,6 +125,19 @@ impl TargetRoot {
std::fs::read_to_string(&path).map_err(|e| CoreError::io(path, e)) std::fs::read_to_string(&path).map_err(|e| CoreError::io(path, e))
} }
pub fn copy_file(&self, relative: &str, src: &Path, mode: u32) -> Result<PathBuf> {
use std::os::unix::fs::PermissionsExt;
self.reject_symlink_components(relative)?;
let path = self.resolve(relative)?;
if let Some(parent) = path.parent() {
std::fs::create_dir_all(parent).map_err(|e| CoreError::io(parent.to_path_buf(), e))?;
}
std::fs::copy(src, &path).map_err(|e| CoreError::io(path.clone(), e))?;
std::fs::set_permissions(&path, std::fs::Permissions::from_mode(mode))
.map_err(|e| CoreError::io(path.clone(), e))?;
Ok(path)
}
pub fn exists(&self, relative: &str) -> bool { pub fn exists(&self, relative: &str) -> bool {
self.resolve(relative).map(|p| p.exists()).unwrap_or(false) self.resolve(relative).map(|p| p.exists()).unwrap_or(false)
} }

View file

@ -7,6 +7,7 @@ use std::path::Path;
use phoebus_core::action::SystemAction; use phoebus_core::action::SystemAction;
use phoebus_core::effects::{changed_materially, parse_emerge_pretend, ResolvedPlan}; use phoebus_core::effects::{changed_materially, parse_emerge_pretend, ResolvedPlan};
use phoebus_core::selection::Need;
use phoebus_core::transaction::TransactionOutcome; use phoebus_core::transaction::TransactionOutcome;
use crate::auth::DestructiveAuthorization; use crate::auth::DestructiveAuthorization;
@ -15,6 +16,7 @@ use crate::error::{ExecError, Result};
use crate::exec::Exec; use crate::exec::Exec;
use crate::portage; use crate::portage;
use crate::snapshot; use crate::snapshot;
use crate::{appimage, chooser, ebuild, snap};
#[derive(Debug)] #[derive(Debug)]
pub struct ActionOutcome { pub struct ActionOutcome {
@ -32,6 +34,27 @@ pub fn preview(action: &SystemAction) -> String {
if action.is_mutating() { if action.is_mutating() {
out.push_str(" this will modify the system.\n"); out.push_str(" this will modify the system.\n");
} }
// A custom ebuild is executable, untrusted content: show the exact artifact
// and its digest so approval is bound to what will be built.
if let SystemAction::CustomEbuildPrepare {
atom,
version,
rationale,
ebuild,
} = action
{
let digest = crate::opencode::sha256_hex(ebuild.as_bytes());
out.push_str(&format!("\nCustom ebuild {atom}-{version}\n"));
out.push_str(&format!(" rationale: {rationale}\n"));
out.push_str(&format!(" content sha256: {digest}\n"));
out.push_str(" --- ebuild begins ---\n");
out.push_str(ebuild);
if !ebuild.ends_with('\n') {
out.push('\n');
}
out.push_str(" --- ebuild ends ---\n");
out.push_str(" It will be treated as untrusted code and built only after approval.\n");
}
out out
} }
@ -471,6 +494,214 @@ pub fn execute(
text text
} }
} }
SystemAction::ChoosePackage {
name,
kind,
backend,
gui,
requires_sandbox,
} => {
let need = Need {
name: name.clone(),
kind: (*kind).unwrap_or_else(|| chooser::infer_kind(name)),
requires_sandbox: *requires_sandbox,
requires_proprietary: false,
gui: *gui,
requires_features: Vec::new(),
explicit_backend: *backend,
max_install_mib: None,
};
chooser::choose(exec, root, &need)?.render()
}
SystemAction::SetPackagePreference { name, backend } => {
let mut prefs = chooser::load_preferences(root);
match backend {
Some(backend) => {
prefs.per_app.insert(name.clone(), *backend);
chooser::save_preferences(exec, root, &prefs)?;
format!(
"preference saved: {name} -> {}\n automatic selection applies again when \
the preferred lane is incompatible",
backend.as_str()
)
}
None => {
prefs.per_app.remove(name);
chooser::save_preferences(exec, root, &prefs)?;
format!("preference cleared for {name}")
}
}
}
SystemAction::SnapFind { query } => {
require_host_root(root, "find snaps")?;
snap::find(exec, query)?
}
SystemAction::SnapInfo { name } => {
require_host_root(root, "inspect snap")?;
snap::info(exec, name)?
}
SystemAction::SnapInstall {
name,
channel,
classic,
} => {
require_host_root(root, "install snap")?;
// snapd is a Portage-managed system dependency; install it first if
// the lane is requested but not yet present.
if !snap::status(exec)?.usable() {
snap::ensure_snapd(exec)?;
}
let out = snap::install(exec, name, channel.as_deref(), *classic)?;
let confinement = snap::status(exec)
.map(|s| s.confinement.as_str().to_string())
.unwrap_or_else(|_| "unknown".to_string());
format!("installed snap {name} (confinement: {confinement})\n{out}")
}
SystemAction::SnapRemove { name } => {
require_host_root(root, "remove snap")?;
let out = snap::remove(exec, name)?;
format!("removed snap {name}\n{out}")
}
SystemAction::SnapList => {
require_host_root(root, "list snaps")?;
let entries = snap::list(exec)?;
if entries.is_empty() {
"no snaps installed".to_string()
} else {
let mut s = String::new();
for e in entries {
s.push_str(&format!(
"{:<24} {:<16} {:<12} {}\n",
e.name, e.version, e.channel, e.notes
));
}
s
}
}
SystemAction::SnapRefresh { name } => {
require_host_root(root, "refresh snaps")?;
let out = snap::refresh(exec, name.as_deref())?;
format!(
"refreshed {} (snapd also refreshes on its own schedule)\n{out}",
name.as_deref().unwrap_or("all snaps")
)
}
SystemAction::SnapConnections { name } => {
require_host_root(root, "snap connections")?;
snap::connections(exec, name)?
}
SystemAction::AppImageImport { path, name } => {
let source = Path::new(path);
let name = match name {
Some(n) => n.clone(),
None => appimage::derive_name(source)?,
};
let record = appimage::import_local(exec, root, source, &name)?;
format!(
"imported AppImage {} (sha256 {}, arch {})\n no application sandbox; runs as the user",
record.name,
&record.sha256[..record.sha256.len().min(12)],
record.arch
)
}
SystemAction::AppImageAcquire { name, url, sha256 } => {
let record = appimage::acquire(exec, root, name, url, sha256)?;
format!(
"acquired AppImage {} from {url} (sha256 verified, arch {})",
record.name, record.arch
)
}
SystemAction::AppImageUpdate { name, url, sha256 } => {
let record = appimage::update(exec, root, name, url, sha256)?;
format!(
"updated AppImage {} to sha256 {}\n the previous image was replaced atomically",
record.name,
&record.sha256[..record.sha256.len().min(12)]
)
}
SystemAction::AppImageRemove { name, purge_data } => {
appimage::remove(root, name, *purge_data)?;
if *purge_data {
format!("removed AppImage {name} and its managed data directory")
} else {
format!(
"removed AppImage {name}; user data under $HOME and any unmanaged \
files were preserved"
)
}
}
SystemAction::AppImageInfo { name } => {
let record = appimage::info(root, name)?;
format!(
"name: {}\nsource: {}\nsha256: {}\narch: {}\nsize: {} bytes\ninstalled: {}",
record.name,
record.provenance,
record.sha256,
record.arch,
record.size_bytes,
record.installed_unix
)
}
SystemAction::AppImageList => {
let records = appimage::list(root)?;
if records.is_empty() {
"no managed AppImages".to_string()
} else {
let mut s = String::new();
for r in records {
s.push_str(&format!(
"{:<24} {:<12} {:<16} {}\n",
r.name,
r.arch,
&r.sha256[..r.sha256.len().min(12)],
r.provenance
));
}
s
}
}
SystemAction::CustomEbuildPrepare {
atom,
version,
rationale,
ebuild,
} => {
let staged = ebuild::prepare(exec, root, atom, version, rationale, ebuild)?;
format!(
"staged custom ebuild {}-{} (sha256 {})\n the artifact is not built until your \
reviewed digest is presented to custom_ebuild_install",
staged.atom, staged.version, staged.digest
)
}
SystemAction::CustomEbuildInstall {
atom,
version,
digest,
} => {
ebuild::install(exec, root, atom, version, digest)?;
format!("installed custom ebuild {atom}-{version} through Portage (Phoebus overlay)")
}
SystemAction::CustomEbuildRemove { atom } => {
ebuild::remove(exec, root, atom)?;
format!("removed custom ebuild {atom} from Portage and the Phoebus overlay")
}
SystemAction::CustomEbuildList => {
let staged = ebuild::list(root);
if staged.is_empty() {
"no Phoebus-managed custom ebuilds".to_string()
} else {
let mut s = String::new();
for e in staged {
s.push_str(&format!(
"{:<28} {:<14} {}\n",
e.atom,
e.version,
&e.digest[..e.digest.len().min(12)]
));
}
s
}
}
SystemAction::NixPrepare { packages } => { SystemAction::NixPrepare { packages } => {
let prepared = crate::nix::prepare_dev_packages(exec, root, packages)?; let prepared = crate::nix::prepare_dev_packages(exec, root, packages)?;
format!("realised Nix development packages: {}", prepared.join(", ")) format!("realised Nix development packages: {}", prepared.join(", "))

View file

@ -0,0 +1,700 @@
//! Managed AppImage lane.
//!
//! An AppImage is a single executable file. Phoebus manages acquisition,
//! provenance, integrity, architecture checks, desktop integration, version
//! tracking and clean removal — but it never pretends AppImage provides a
//! sandbox, and it never executes a downloaded image just to inspect it.
//!
//! Inspection reads the ELF header (architecture) and, when `unsquashfs` is
//! available, extracts the embedded SquashFS metadata/icon without running the
//! image. Applications run as the user; the managed binary is world-readable
//! and executable, and user data under `$HOME` is preserved on removal.
use std::path::{Path, PathBuf};
use serde::{Deserialize, Serialize};
use crate::command::CommandSpec;
use crate::error::{ExecError, Result};
use crate::exec::Exec;
/// Where Phoebus keeps managed AppImages, relative to the target root.
pub const APPIMAGE_DIR: &str = "var/lib/phoebus/appimages";
/// Where desktop entries are registered, relative to the target root.
pub const APPLICATIONS_DIR: &str = "usr/share/applications";
/// Where icons are registered, relative to the target root.
pub const PIXMAPS_DIR: &str = "usr/share/pixmaps";
/// A recorded, managed AppImage.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct AppImageRecord {
pub name: String,
#[serde(default)]
pub version: String,
pub sha256: String,
/// Where the image came from: a URL, or `local:<original path>`.
pub provenance: String,
pub arch: String,
pub size_bytes: u64,
pub installed_unix: u64,
#[serde(default)]
pub desktop_file: Option<String>,
#[serde(default)]
pub icon: Option<String>,
}
impl AppImageRecord {
pub fn binary_name(&self) -> String {
format!("{}.AppImage", self.name)
}
}
fn record_path(root: &Path, name: &str) -> PathBuf {
root.join(APPIMAGE_DIR).join(format!("{name}.toml"))
}
fn binary_path(root: &Path, name: &str) -> PathBuf {
root.join(APPIMAGE_DIR).join(format!("{name}.AppImage"))
}
fn desktop_path(root: &Path, name: &str) -> PathBuf {
root.join(APPLICATIONS_DIR)
.join(format!("phoebus-appimage-{name}.desktop"))
}
/// Map an ELF `e_machine` value to Phoebus's architecture name.
pub fn arch_from_elf(machine: u16) -> Option<&'static str> {
match machine {
0x3e => Some("x86_64"),
0xaa => Some("aarch64"),
0xb7 => Some("aarch64"),
0x03 => Some("x86"),
0x28 => Some("arm"),
0xf3 => Some("riscv64"),
_ => None,
}
}
/// Inspect an ELF image **without executing it**: verify the magic and read the
/// architecture. Returns the architecture and whether it matches `host_arch`.
pub fn inspect_elf(path: &Path, host_arch: &str) -> Result<(String, bool)> {
use std::io::Read;
let mut file = std::fs::File::open(path).map_err(|e| ExecError::io(path.to_path_buf(), e))?;
let mut header = [0u8; 20];
let n = file
.read(&mut header)
.map_err(|e| ExecError::io(path.to_path_buf(), e))?;
if n < 20 || &header[..4] != b"\x7fELF" {
return Err(ExecError::operation(
"appimage",
"inspect image",
format!("{} is not an ELF executable", path.display()),
));
}
// e_machine is a 16-bit little-endian field at offset 18.
let machine = u16::from_le_bytes([header[18], header[19]]);
let arch = arch_from_elf(machine).ok_or_else(|| {
ExecError::operation(
"appimage",
"inspect image",
format!("unsupported ELF machine type 0x{machine:04x}"),
)
})?;
Ok((arch.to_string(), arch == host_arch))
}
/// Locate the embedded SquashFS superblock (`hsqs`) so metadata can be
/// extracted without running the image. Only aligned occurrences after the ELF
/// header are considered.
pub fn find_squashfs_offset(data: &[u8]) -> Option<u64> {
if data.len() < 4 {
return None;
}
let mut i = 4;
while i + 4 <= data.len() {
if &data[i..i + 4] == b"hsqs" {
return Some(i as u64);
}
i += 1;
}
None
}
fn read_squashfs_offset(path: &Path) -> Option<u64> {
use std::io::Read;
let mut file = std::fs::File::open(path).ok()?;
let mut buf = vec![0u8; 1024 * 1024];
let n = file.read(&mut buf).ok()?;
buf.truncate(n);
// The type-2 runtime is small; if the magic is beyond the first MiB, fall
// back to the whole-file scan.
match find_squashfs_offset(&buf) {
Some(offset) => Some(offset),
None => {
let data = std::fs::read(path).ok()?;
find_squashfs_offset(&data)
}
}
}
/// Write a desktop entry for the managed image and return its relative path.
fn write_desktop_entry(
root: &Path,
name: &str,
binary: &Path,
icon: Option<&str>,
) -> Result<String> {
let rel = format!("phoebus-appimage-{name}.desktop");
let icon_line = icon.map(|i| format!("Icon={i}\n")).unwrap_or_default();
let contents = format!(
"[Desktop Entry]\n\
Type=Application\n\
Name={name}\n\
Comment=Managed AppImage (no application sandbox)\n\
Exec=\"{}\" %U\n\
{icon_line}\
Terminal=false\n\
Categories=Utility;\n\
X-Phoebus-Backend=appimage\n",
binary.display()
);
let path = root.join(APPLICATIONS_DIR).join(&rel);
if let Some(parent) = path.parent() {
std::fs::create_dir_all(parent).map_err(|e| ExecError::io(parent.to_path_buf(), e))?;
}
std::fs::write(&path, contents).map_err(|e| ExecError::io(path, e))?;
Ok(rel)
}
/// Best-effort extraction of the AppImage's own icon and desktop entry using
/// `unsquashfs` on the embedded filesystem. Never executes the image.
struct ExtractedMeta {
desktop_text: Option<String>,
icon_bytes: Option<Vec<u8>>,
}
fn extract_metadata(exec: &Exec, image: &Path) -> Option<ExtractedMeta> {
let offset = read_squashfs_offset(image)?;
let listed = exec
.runner
.execute(
&CommandSpec::new("appimage", "list embedded files", "unsquashfs")
.args(["-o", &offset.to_string(), "-l"])
.arg(image.to_string_lossy().to_string()),
)
.ok()?;
if !listed.success {
return None;
}
let text = listed.stdout_lossy();
let mut desktop = None;
for line in text.lines() {
let trimmed = line.trim();
if trimmed.ends_with(".desktop") {
desktop = trimmed.split_whitespace().last().map(str::to_string);
break;
}
}
let dir = tempfile::tempdir().ok()?;
let mut extract_args = vec![
"-o".to_string(),
offset.to_string(),
"-d".to_string(),
dir.path().to_string_lossy().to_string(),
image.to_string_lossy().to_string(),
".DirIcon".to_string(),
];
if let Some(desktop) = &desktop {
extract_args.push(desktop.clone());
}
let extracted = exec
.runner
.execute(
&CommandSpec::new("appimage", "extract embedded files", "unsquashfs")
.args(extract_args),
)
.ok()?;
if !extracted.success {
return None;
}
let desktop_text = desktop
.as_ref()
.and_then(|d| std::fs::read_to_string(dir.path().join(d)).ok());
let icon_bytes = std::fs::read(dir.path().join(".DirIcon")).ok();
Some(ExtractedMeta {
desktop_text,
icon_bytes,
})
}
/// Adopt a local file as a managed AppImage.
pub fn import_local(exec: &Exec, root: &Path, source: &Path, name: &str) -> Result<AppImageRecord> {
let meta =
std::fs::symlink_metadata(source).map_err(|e| ExecError::io(source.to_path_buf(), e))?;
if !meta.file_type().is_file() {
return Err(ExecError::operation(
"appimage",
"import image",
format!(
"{} must be a regular file (symlinks are refused to prevent escape)",
source.display()
),
));
}
let (arch, matches) = inspect_elf(source, host_arch())?;
if !matches {
return Err(ExecError::operation(
"appimage",
"import image",
format!("image targets {arch}, not {}", host_arch()),
));
}
let sha256 = crate::opencode::sha256_file(source)?;
adopt(
exec,
root,
name,
source,
&sha256,
&format!("local:{}", source.display()),
&arch,
)
}
/// Download, verify and adopt an AppImage.
pub fn acquire(
exec: &Exec,
root: &Path,
name: &str,
url: &str,
expected_sha256: &str,
) -> Result<AppImageRecord> {
exec.require_tools(&["curl"])?;
if !phoebus_core::action::valid_sha256(expected_sha256) {
return Err(ExecError::operation(
"appimage",
"verify image",
"a real, pinned SHA-256 is required before downloading (placeholders are refused)",
));
}
if exec.dry_run {
exec.logger.info(format!(
"[dry-run] would download AppImage {name} from {url}"
));
return Ok(AppImageRecord {
name: name.to_string(),
version: String::new(),
sha256: expected_sha256.to_string(),
provenance: url.to_string(),
arch: host_arch().to_string(),
size_bytes: 0,
installed_unix: now_unix(),
desktop_file: None,
icon: None,
});
}
let staged = exec.state_dir.join(format!("appimage-{name}.download"));
let _ = std::fs::remove_file(&staged);
exec.run(
CommandSpec::new("appimage", "download image", "curl")
.args(["-fL", "--retry", "3", "-o"])
.arg(staged.to_string_lossy().to_string())
.arg(url),
)?;
let actual = crate::opencode::sha256_file(&staged)?;
if actual != expected_sha256 {
let _ = std::fs::remove_file(&staged);
return Err(ExecError::operation(
"appimage",
"verify image",
format!("SHA-256 mismatch for {name}; discarding download"),
));
}
let (arch, matches) = inspect_elf(&staged, host_arch())?;
if !matches {
let _ = std::fs::remove_file(&staged);
return Err(ExecError::operation(
"appimage",
"verify image",
format!("image targets {arch}, not {}", host_arch()),
));
}
let result = adopt(exec, root, name, &staged, &actual, url, &arch);
let _ = std::fs::remove_file(&staged);
result
}
/// Replace an existing managed image with a newly verified one.
pub fn update(
exec: &Exec,
root: &Path,
name: &str,
url: &str,
expected_sha256: &str,
) -> Result<AppImageRecord> {
if !record_path(root, name).is_file() {
return Err(ExecError::operation(
"appimage",
"update image",
format!("{name} is not a managed AppImage"),
));
}
acquire(exec, root, name, url, expected_sha256)
}
fn adopt(
exec: &Exec,
root: &Path,
name: &str,
source: &Path,
sha256: &str,
provenance: &str,
arch: &str,
) -> Result<AppImageRecord> {
let dir = root.join(APPIMAGE_DIR);
std::fs::create_dir_all(&dir).map_err(|e| ExecError::io(dir.clone(), e))?;
let dest = binary_path(root, name);
// Atomic-ish replacement: copy beside the destination, then rename.
let tmp = dir.join(format!(".{name}.AppImage.tmp"));
std::fs::copy(source, &tmp).map_err(|e| ExecError::io(tmp.clone(), e))?;
{
use std::os::unix::fs::PermissionsExt;
std::fs::set_permissions(&tmp, std::fs::Permissions::from_mode(0o755))
.map_err(|e| ExecError::io(tmp.clone(), e))?;
}
std::fs::rename(&tmp, &dest).map_err(|e| ExecError::io(dest.clone(), e))?;
// Optional metadata extraction (never executes the image).
let (desktop_text, icon_name) = match extract_metadata(exec, &dest) {
Some(meta) => {
let icon_name = meta.icon_bytes.as_ref().and_then(|bytes| {
let path = root.join(PIXMAPS_DIR).join(format!("{name}.png"));
if let Some(parent) = path.parent() {
if std::fs::create_dir_all(parent).is_err() {
return None;
}
}
std::fs::write(&path, bytes).ok()?;
Some(name.to_string())
});
(meta.desktop_text, icon_name)
}
None => (None, None),
};
// The generated entry is authoritative so the application is always
// launchable; the embedded entry is recorded but not trusted blindly.
let desktop_rel = write_desktop_entry(root, name, &dest, icon_name.as_deref())?;
let record = AppImageRecord {
name: name.to_string(),
version: String::new(),
sha256: sha256.to_string(),
provenance: provenance.to_string(),
arch: arch.to_string(),
size_bytes: std::fs::metadata(&dest).map(|m| m.len()).unwrap_or(0),
installed_unix: now_unix(),
desktop_file: Some(desktop_rel),
icon: icon_name,
};
write_record(root, &record)?;
let _ = desktop_text;
exec.logger.info(format!(
"AppImage {name} adopted (sha256 {})",
&sha256[..12]
));
Ok(record)
}
fn now_unix() -> u64 {
std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.map(|d| d.as_secs())
.unwrap_or(0)
}
fn write_record(root: &Path, record: &AppImageRecord) -> Result<()> {
let path = record_path(root, &record.name);
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(record)
.map_err(|e| ExecError::operation("appimage", "write record", e.to_string()))?;
std::fs::write(&path, text).map_err(|e| ExecError::io(path, e))
}
/// Load one managed record.
pub fn info(root: &Path, name: &str) -> Result<AppImageRecord> {
let path = record_path(root, name);
let text = std::fs::read_to_string(&path).map_err(|e| ExecError::io(path, e))?;
toml::from_str(&text)
.map_err(|e| ExecError::operation("appimage", "read record", e.to_string()))
}
/// List managed AppImages.
pub fn list(root: &Path) -> Result<Vec<AppImageRecord>> {
let dir = root.join(APPIMAGE_DIR);
let mut out = Vec::new();
let Ok(entries) = std::fs::read_dir(&dir) else {
return Ok(out);
};
for entry in entries.flatten() {
let path = entry.path();
if path.extension().and_then(|e| e.to_str()) == Some("toml") {
if let Ok(text) = std::fs::read_to_string(&path) {
if let Ok(record) = toml::from_str::<AppImageRecord>(&text) {
out.push(record);
}
}
}
}
out.sort_by(|a, b| a.name.cmp(&b.name));
Ok(out)
}
/// Remove a managed AppImage. The user's data under `$HOME` is always
/// preserved; `purge_data` only removes a managed `<name>.data` directory.
pub fn remove(root: &Path, name: &str, purge_data: bool) -> Result<()> {
let _ = info(root, name)?;
for path in [
binary_path(root, name),
record_path(root, name),
desktop_path(root, name),
root.join(PIXMAPS_DIR).join(format!("{name}.png")),
] {
let _ = std::fs::remove_file(&path);
}
if purge_data {
let data = root.join(APPIMAGE_DIR).join(format!("{name}.data"));
if data.is_dir() {
let _ = std::fs::remove_dir_all(&data);
}
}
Ok(())
}
/// Derive a safe managed name from a local file name.
pub fn derive_name(source: &Path) -> Result<String> {
let stem = source.file_stem().and_then(|s| s.to_str()).ok_or_else(|| {
ExecError::operation("appimage", "derive name", "file name is not valid UTF-8")
})?;
let cleaned: String = stem
.chars()
.map(|c| {
if c.is_ascii_alphanumeric() || "._-".contains(c) {
c.to_ascii_lowercase()
} else {
'-'
}
})
.collect();
let cleaned = cleaned.trim_matches(['-', '.', '_']).to_string();
if phoebus_core::action::valid_appimage_name(&cleaned) {
Ok(cleaned)
} else {
Err(ExecError::operation(
"appimage",
"derive name",
format!("could not derive a safe name from {}", source.display()),
))
}
}
/// The host architecture in Phoebus naming.
pub fn host_arch() -> &'static str {
match std::env::consts::ARCH {
"x86_64" => "x86_64",
"aarch64" => "aarch64",
"x86" => "x86",
"arm" => "arm",
"riscv64" => "riscv64",
_ => "unknown",
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::command::RecordingRunner;
use crate::log::Logger;
use phoebus_core::Redactor;
use std::io::Write;
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 fake_elf(path: &Path, machine: u16) {
let mut f = std::fs::File::create(path).unwrap();
let mut header = [0u8; 64];
header[..4].copy_from_slice(b"\x7fELF");
header[4] = 2; // 64-bit
header[18..20].copy_from_slice(&machine.to_le_bytes());
f.write_all(&header).unwrap();
// Embed a fake squashfs marker so offset detection is exercised.
f.write_all(b"hsqs").unwrap();
f.write_all(&[0u8; 32]).unwrap();
}
#[test]
fn arch_from_elf_maps_common_machines() {
assert_eq!(arch_from_elf(0x3e), Some("x86_64"));
assert_eq!(arch_from_elf(0xb7), Some("aarch64"));
assert_eq!(arch_from_elf(0x1234), None);
}
#[test]
fn inspect_reads_arch_without_executing() {
let dir = tempfile::tempdir().unwrap();
let img = dir.path().join("app.AppImage");
fake_elf(&img, 0x3e);
let (arch, matches) = inspect_elf(&img, "x86_64").unwrap();
assert_eq!(arch, "x86_64");
assert!(matches);
let (arch, matches) = inspect_elf(&img, "aarch64").unwrap();
assert_eq!(arch, "x86_64");
assert!(!matches);
}
#[test]
fn non_elf_is_refused() {
let dir = tempfile::tempdir().unwrap();
let img = dir.path().join("script.sh");
std::fs::write(&img, b"#!/bin/sh\necho hi\n").unwrap();
assert!(inspect_elf(&img, "x86_64").is_err());
}
#[test]
fn squashfs_offset_detection() {
assert_eq!(find_squashfs_offset(b"\x7fELF....hsqs"), Some(8));
assert_eq!(find_squashfs_offset(b"nope"), None);
}
#[test]
fn import_records_hash_and_desktop_entry() {
let dir = tempfile::tempdir().unwrap();
let src = dir.path().join("hello.AppImage");
fake_elf(&src, 0x3e);
let root = tempfile::tempdir().unwrap();
let runner = RecordingRunner::new();
// unsquashfs is absent in the recording runner; extraction falls back.
runner.fail("unsquashfs", "not found");
let exec = make_exec(runner);
let record = import_local(&exec, root.path(), &src, "hello").unwrap();
assert_eq!(record.name, "hello");
assert_eq!(record.sha256.len(), 64);
assert!(record.arch == "x86_64" || record.arch == host_arch());
assert!(root
.path()
.join(APPIMAGE_DIR)
.join("hello.AppImage")
.is_file());
assert!(root
.path()
.join(APPLICATIONS_DIR)
.join("phoebus-appimage-hello.desktop")
.is_file());
let listed = list(root.path()).unwrap();
assert_eq!(listed.len(), 1);
let info = info(root.path(), "hello").unwrap();
assert_eq!(info.sha256, record.sha256);
}
#[test]
fn import_refuses_a_symlink_and_a_mismatched_arch() {
let dir = tempfile::tempdir().unwrap();
let real = dir.path().join("real.AppImage");
fake_elf(&real, 0x3e);
let link = dir.path().join("link.AppImage");
std::os::unix::fs::symlink(&real, &link).unwrap();
let root = tempfile::tempdir().unwrap();
let exec = make_exec(RecordingRunner::new());
let err = import_local(&exec, root.path(), &link, "link").unwrap_err();
assert!(err.to_string().contains("regular file"), "{err}");
// On x86_64 hosts a fake aarch64 image is refused.
if host_arch() == "x86_64" {
let arm = dir.path().join("arm.AppImage");
fake_elf(&arm, 0xb7);
let err = import_local(&exec, root.path(), &arm, "arm").unwrap_err();
assert!(err.to_string().contains("not x86_64"), "{err}");
}
}
#[test]
fn acquire_verifies_checksum_and_discards_on_mismatch() {
// Without curl available on the recording runner, force curl to fail.
let runner = RecordingRunner::new();
runner.fail("curl", "network down");
let exec = make_exec(runner);
let root = tempfile::tempdir().unwrap();
let err = acquire(
&exec,
root.path(),
"app",
"https://example.invalid/app.AppImage",
&"a".repeat(64),
)
.unwrap_err();
assert!(err.to_string().contains("download"), "{err}");
}
#[test]
fn acquire_refuses_a_placeholder_hash_before_downloading() {
let runner = RecordingRunner::new();
let exec = make_exec(runner.clone());
let root = tempfile::tempdir().unwrap();
let err = acquire(
&exec,
root.path(),
"app",
"https://example.invalid/app.AppImage",
&"0".repeat(64),
)
.unwrap_err();
assert!(err.to_string().contains("mismatch") || err.to_string().contains("SHA-256"));
}
#[test]
fn remove_preserves_data_by_default_and_purges_on_request() {
let dir = tempfile::tempdir().unwrap();
let src = dir.path().join("hello.AppImage");
fake_elf(&src, 0x3e);
let root = tempfile::tempdir().unwrap();
let exec = make_exec(RecordingRunner::new());
import_local(&exec, root.path(), &src, "hello").unwrap();
let data = root.path().join(APPIMAGE_DIR).join("hello.data");
std::fs::create_dir_all(&data).unwrap();
std::fs::write(data.join("state"), b"keep").unwrap();
remove(root.path(), "hello", false).unwrap();
assert!(
data.join("state").is_file(),
"data must survive default removal"
);
assert!(!root
.path()
.join(APPIMAGE_DIR)
.join("hello.AppImage")
.exists());
import_local(&exec, root.path(), &src, "hello").unwrap();
remove(root.path(), "hello", true).unwrap();
assert!(!data.exists(), "purge removes the managed data dir");
}
#[test]
fn double_import_is_idempotent_at_the_filesystem_level() {
let dir = tempfile::tempdir().unwrap();
let src = dir.path().join("hello.AppImage");
fake_elf(&src, 0x3e);
let root = tempfile::tempdir().unwrap();
let exec = make_exec(RecordingRunner::new());
let a = import_local(&exec, root.path(), &src, "hello").unwrap();
let b = import_local(&exec, root.path(), &src, "hello").unwrap();
assert_eq!(a.sha256, b.sha256);
assert_eq!(list(root.path()).unwrap().len(), 1);
}
}

View file

@ -0,0 +1,535 @@
//! Resolve real backend metadata into selection candidates and apply the
//! shared, hardware-aware policy.
//!
//! This module is the bridge between the pure policy in `phoebus-core::selection`
//! and the actual system. It only reads: it never installs anything. Backend
//! metadata that cannot be resolved (offline, daemon down, package absent) is
//! reported as an *unavailable* candidate so the review explains why a lane was
//! not chosen instead of silently inventing availability.
use std::path::Path;
use phoebus_core::selection::{
select, Backend, Candidate, HardwareFacts, Need, PackageKind, Preferences, SandboxLevel,
Selection, UpdateReliability,
};
use crate::command::CommandSpec;
use crate::error::{ExecError, Result};
use crate::exec::Exec;
/// Persisted preferences live here, relative to the target root.
pub const PREFERENCES_REL: &str = "etc/phoebus/package-preferences.toml";
/// Load persisted preferences (global default and per-application choices).
pub fn load_preferences(root: &Path) -> Preferences {
let path = root.join(PREFERENCES_REL);
std::fs::read_to_string(&path)
.ok()
.and_then(|text| toml::from_str(&text).ok())
.unwrap_or_default()
}
/// Persist preferences so an explicit choice survives across sessions.
pub fn save_preferences(exec: &Exec, root: &Path, prefs: &Preferences) -> Result<()> {
let path = root.join(PREFERENCES_REL);
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(prefs)
.map_err(|e| ExecError::operation("sys", "save preferences", e.to_string()))?;
if exec.dry_run {
exec.logger
.info("[dry-run] would persist package preferences");
return Ok(());
}
std::fs::write(&path, text).map_err(|e| ExecError::io(path, e))
}
/// Read free storage for the filesystem containing `root` using `df -Pk`.
fn free_mib(exec: &Exec, root: &Path) -> u64 {
let path = if root.exists() {
root.to_string_lossy().to_string()
} else {
"/".to_string()
};
let out = exec.runner.execute(
&CommandSpec::new("sys", "probe free space", "df")
.args(["-Pk"])
.arg(path),
);
match out {
Ok(out) if out.success => out
.stdout_lossy()
.lines()
.nth(1)
.and_then(|line| line.split_whitespace().nth(3))
.and_then(|kb| kb.parse::<u64>().ok())
.map(|kb| kb / 1024)
.unwrap_or(0),
_ => 0,
}
}
/// Assemble the bounded hardware facts the policy consumes.
pub fn hardware_facts(exec: &Exec, root: &Path) -> HardwareFacts {
let hw = crate::probe::probe_hardware(exec.runner.as_ref());
let arch = match std::env::consts::ARCH {
"x86_64" => "x86_64",
"aarch64" => "aarch64",
"x86" => "x86",
"arm" => "arm",
"riscv64" => "riscv64",
other => other,
}
.to_string();
let cores = std::thread::available_parallelism()
.map(|n| n.get() as u32)
.unwrap_or(1);
let gpus = hw.gpu_vendors();
let wayland = std::env::var("XDG_SESSION_TYPE")
.map(|v| v.eq_ignore_ascii_case("wayland"))
.unwrap_or(true);
let binhost_available = root.join("etc/portage/binrepos.conf").exists();
let mut available_backends = std::collections::BTreeSet::new();
available_backends.insert(Backend::PortageSource);
if binhost_available {
available_backends.insert(Backend::PortageBinary);
}
available_backends.insert(Backend::PortageVendor);
available_backends.insert(Backend::AppImage);
available_backends.insert(Backend::CustomEbuild);
if crate::nix::installed(root) {
available_backends.insert(Backend::Nix);
}
if crate::exec::find_in_path("flatpak").is_some() {
available_backends.insert(Backend::Flatpak);
}
if matches!(
crate::snap::status(exec),
Ok(status) if status.usable()
) {
available_backends.insert(Backend::Snap);
}
let history = phoebus_core::load_history(&root.join("var/lib/phoebus/compile-times.tsv"));
HardwareFacts {
arch,
cores,
memory_mib: hw.memory_mib,
storage_free_mib: free_mib(exec, root),
gpus,
wayland,
binhost_available,
available_backends,
compile_history: history.into_iter().collect(),
}
}
/// Parse the first `cat/pkg-version` token from an `emerge --pretend` line.
pub fn parse_pretend_version(text: &str) -> Option<String> {
for line in text.lines() {
let trimmed = line.trim_start();
if !trimmed.starts_with('[') {
continue;
}
let close = trimmed.find(']')?;
let rest = trimmed[close + 1..].trim();
let atom = rest.split_whitespace().next()?;
if atom.contains('/') {
return Some(atom.to_string());
}
}
None
}
/// A rough capability profile for a plain Portage source/binary candidate.
fn portage_candidate(id: &str, binary: bool, facts: &HardwareFacts) -> Candidate {
let mut c = Candidate::new(
if binary {
Backend::PortageBinary
} else {
Backend::PortageSource
},
id,
if binary {
"official signed Gentoo binhost"
} else {
"Gentoo source tree (/var/db/repos)"
},
);
c.verified = true;
c.arch = facts.arch.clone();
c.update_reliability = UpdateReliability::Automatic;
if !binary {
c.build_seconds = facts.estimated_build_seconds(id);
c.build_measured = c.build_seconds.is_some();
}
c
}
/// Build the candidate set for a request from real backend metadata.
///
/// Every candidate reflects something the backend actually reported. When a
/// backend cannot be reached, the candidate is marked unavailable with a note.
pub fn resolve_candidates(exec: &Exec, root: &Path, need: &Need) -> Vec<Candidate> {
let facts = hardware_facts(exec, root);
let mut out = Vec::new();
let name = &need.name;
// --- Portage ------------------------------------------------------
let pretend = exec.runner.execute(
&CommandSpec::new("sys", "resolve Portage candidate", "emerge")
.args(["--pretend", "--quiet", "--color=n", "--"])
.arg(name),
);
match pretend {
Ok(resolved) if resolved.success => {
let text = resolved.stdout_lossy();
let id = parse_pretend_version(&text).unwrap_or_else(|| name.clone());
out.push(portage_candidate(&id, false, &facts));
if facts.binhost_available {
out.push(portage_candidate(&id, true, &facts));
}
}
_ => {
let mut c = portage_candidate(name, false, &facts);
c.available = false;
c.notes
.push("emerge could not resolve this name from the Gentoo tree".into());
out.push(c);
}
}
// --- Nix ----------------------------------------------------------
if crate::nix::installed(root) {
let mut c = Candidate::new(Backend::Nix, name, "nixpkgs (pinned)");
c.verified = true;
c.update_reliability = UpdateReliability::Automatic;
c.sandbox = SandboxLevel::None;
if !phoebus_core::action::valid_nix_attribute(name) {
c.available = false;
c.notes
.push("not a bounded nixpkgs attribute (URLs/flakes are refused)".into());
}
out.push(c);
}
// --- Flatpak ------------------------------------------------------
if crate::exec::find_in_path("flatpak").is_some() {
let mut c = Candidate::new(Backend::Flatpak, name, "flathub");
c.sandbox = SandboxLevel::Strong;
c.update_reliability = UpdateReliability::Automatic;
c.verified = true;
c.shared_runtime_mib = Some(400);
if !phoebus_core::action::valid_flatpak_app_id(name) {
c.available = false;
c.notes
.push("not a reverse-DNS Flatpak application id".into());
} else {
// Confirm the id actually exists in the configured remotes.
let found = exec.runner.execute(
&CommandSpec::new("sys", "resolve Flatpak candidate", "flatpak").args([
"search",
"--columns=application",
"--",
name,
]),
);
match found {
Ok(o) if o.success && o.stdout_lossy().contains(name) => {
c.verified = true;
}
_ => {
c.available = false;
c.notes.push(
"flathub could not confirm this application id (offline or unknown)".into(),
);
}
}
}
out.push(c);
}
// --- Snap ---------------------------------------------------------
if matches!(crate::snap::status(exec), Ok(s) if s.usable()) {
let mut c = Candidate::new(Backend::Snap, name, "Snap Store");
c.sandbox = SandboxLevel::Strong;
c.update_reliability = UpdateReliability::Automatic;
c.verified = true;
c.shared_runtime_mib = Some(200);
if !phoebus_core::action::valid_snap_name(name) {
c.available = false;
c.notes.push("not a valid snap name".into());
} else {
// Confirm the snap exists in the store rather than assuming it.
let found = exec.runner.execute(
&CommandSpec::new("sys", "resolve snap candidate", "snap").args([
"find",
"--color=never",
"--",
name,
]),
);
let confirmed = found
.map(|o| {
o.success
&& o.stdout_lossy()
.lines()
.any(|l| l.split_whitespace().next() == Some(name))
})
.unwrap_or(false);
if !confirmed {
c.available = false;
c.notes
.push("the Snap Store could not confirm this snap (offline or unknown)".into());
}
}
out.push(c);
}
// --- AppImage (only when already managed) -------------------------
if let Ok(record) = crate::appimage::info(root, name) {
let mut c = Candidate::new(
Backend::AppImage,
record.name.clone(),
record.provenance.clone(),
);
c.version = Some(record.version.clone());
c.verified = true;
c.sandbox = SandboxLevel::None;
c.update_reliability = UpdateReliability::Manual;
c.arch = record.arch.clone();
c.install_mib = Some(record.size_bytes / (1024 * 1024));
out.push(c);
}
// --- Custom ebuild (only when staged in the Phoebus overlay) -------
if crate::ebuild::staged(root, name).is_some() {
let mut c = Candidate::new(
Backend::CustomEbuild,
name,
"Phoebus overlay (/var/db/repos/phoebus)",
);
c.verified = false;
c.sandbox = SandboxLevel::None;
c.update_reliability = UpdateReliability::Manual;
c.notes
.push("generated ebuild; treated as untrusted until reviewed".into());
out.push(c);
}
out
}
/// Determine which backend (if any) already owns an installed copy of `name`.
pub fn installed_backend(exec: &Exec, root: &Path, name: &str) -> Option<Backend> {
// AppImage: a managed record.
if crate::appimage::info(root, name).is_ok() {
return Some(Backend::AppImage);
}
// Flatpak: parse the installed list.
if crate::exec::find_in_path("flatpak").is_some() {
if let Ok(out) = exec.runner.execute(
&CommandSpec::new("sys", "detect installed flatpak", "flatpak").args([
"list",
"--app",
"--columns=application",
]),
) {
if out.success && out.stdout_lossy().lines().any(|l| l.trim() == name) {
return Some(Backend::Flatpak);
}
}
}
// Snap: parse the installed list.
if let Ok(entries) = crate::snap::list(exec) {
if entries.iter().any(|e| e.name == name) {
return Some(Backend::Snap);
}
}
// Portage: a VDB entry for the package (bare name or full atom).
if portage_installed(root, name) {
return Some(Backend::PortageSource);
}
None
}
fn portage_installed(root: &Path, name: &str) -> bool {
let vdb = root.join("var/db/pkg");
let (category, package) = match name.split_once('/') {
Some((c, p)) => (Some(c.to_string()), p.to_string()),
None => (None, name.to_string()),
};
let Ok(categories) = std::fs::read_dir(&vdb) else {
return false;
};
for category_entry in categories.flatten() {
let category_name = category_entry.file_name().to_string_lossy().to_string();
if let Some(want) = &category {
if &category_name != want {
continue;
}
}
let Ok(pkgs) = std::fs::read_dir(category_entry.path()) else {
continue;
};
for pkg in pkgs.flatten() {
let dir = pkg.file_name().to_string_lossy().to_string();
// VDB dirs are `name-version`; match the name prefix.
if dir == package || dir.starts_with(&format!("{package}-")) {
return true;
}
}
}
false
}
/// Decide the backend for a request using the shared policy.
pub fn choose(exec: &Exec, root: &Path, need: &Need) -> Result<Selection> {
let facts = hardware_facts(exec, root);
let prefs = load_preferences(root);
let installed = installed_backend(exec, root, &need.name);
let candidates = resolve_candidates(exec, root, need);
select(need, &candidates, &facts, &prefs, installed)
.map_err(|e| ExecError::operation("sys", "choose package", e.to_string()))
}
/// Convenience: the kind inferred from the request when the caller did not
/// classify it. Kept conservative — `Unclassified` never forces a lane.
pub fn infer_kind(_name: &str) -> PackageKind {
PackageKind::Unclassified
}
/// A plain-text inventory of the available lanes, for `sys choose` with no
/// request and for diagnostics.
pub fn lanes_report(exec: &Exec, root: &Path) -> String {
let facts = hardware_facts(exec, root);
let mut out = format!(
"arch={} cores={} memory={}MiB free={}MiB wayland={} binhost={}\n",
facts.arch,
facts.cores,
facts.memory_mib,
facts.storage_free_mib,
facts.wayland,
facts.binhost_available
);
for backend in Backend::all() {
let state = if facts.backend_available(*backend) {
"available"
} else {
"unavailable"
};
out.push_str(&format!(" {:<16} {state}\n", backend.as_str()));
}
let _ = exec;
out
}
#[cfg(test)]
mod tests {
use super::*;
use crate::command::{CommandOutput, RecordingRunner};
use crate::log::Logger;
use phoebus_core::Redactor;
use std::time::Duration;
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 ok(stdout: &str) -> CommandOutput {
CommandOutput {
status: 0,
success: true,
stdout: stdout.as_bytes().to_vec(),
stderr: Vec::new(),
duration: Duration::from_millis(1),
}
}
#[test]
fn pretend_version_parses_the_atom() {
let text = "Calculating dependencies... done!\n[ebuild N ] www-client/firefox-128.0\n";
assert_eq!(
parse_pretend_version(text).as_deref(),
Some("www-client/firefox-128.0")
);
assert_eq!(parse_pretend_version("nothing here"), None);
}
#[test]
fn preferences_roundtrip_through_disk() {
let root = tempfile::tempdir().unwrap();
let mut prefs = Preferences::default();
prefs.per_app.insert("firefox".into(), Backend::Flatpak);
prefs.default = Some(Backend::PortageBinary);
let exec = make_exec(RecordingRunner::new());
save_preferences(&exec, root.path(), &prefs).unwrap();
let back = load_preferences(root.path());
assert_eq!(back, prefs);
}
#[test]
fn missing_preferences_file_is_the_default() {
let root = tempfile::tempdir().unwrap();
assert_eq!(load_preferences(root.path()), Preferences::default());
}
#[test]
fn portage_installed_matches_vdb_directories() {
let root = tempfile::tempdir().unwrap();
let vdb = root.path().join("var/db/pkg/www-client");
std::fs::create_dir_all(vdb.join("firefox-128.0")).unwrap();
std::fs::create_dir_all(vdb.join("firefox-bin-128.0")).unwrap();
assert!(portage_installed(root.path(), "www-client/firefox"));
assert!(portage_installed(root.path(), "firefox"));
assert!(!portage_installed(root.path(), "www-client/chromium"));
}
#[test]
fn resolve_includes_a_portage_candidate_from_real_metadata() {
let runner = RecordingRunner::new();
runner.set_response(
"emerge",
ok("Calculating dependencies... done!\n[ebuild N ] app-editors/vim-9.1.0\n"),
);
let exec = make_exec(runner);
let root = tempfile::tempdir().unwrap();
let need = Need::new("vim").kind(PackageKind::CliTool);
let candidates = resolve_candidates(&exec, root.path(), &need);
assert!(candidates
.iter()
.any(|c| c.backend == Backend::PortageSource && c.available));
}
#[test]
fn unresolved_portage_candidate_is_marked_unavailable() {
let runner = RecordingRunner::new();
runner.fail("emerge", "no such package");
let exec = make_exec(runner);
let root = tempfile::tempdir().unwrap();
let need = Need::new("not-a-real-package");
let candidates = resolve_candidates(&exec, root.path(), &need);
let portage = candidates
.iter()
.find(|c| c.backend == Backend::PortageSource)
.unwrap();
assert!(!portage.available);
assert!(!portage.notes.is_empty());
}
#[test]
fn lanes_report_names_every_backend() {
let exec = make_exec(RecordingRunner::new());
let root = tempfile::tempdir().unwrap();
let report = lanes_report(&exec, root.path());
for backend in Backend::all() {
assert!(report.contains(backend.as_str()), "missing {backend:?}");
}
}
}

View file

@ -0,0 +1,559 @@
//! Phoebus-managed custom ebuild lane.
//!
//! Sometimes no maintained candidate is suitable, and the honest answer is a
//! local ebuild. This module owns a dedicated overlay
//! (`/var/db/repos/phoebus`), records *why* each custom package exists, and
//! binds approval to the exact ebuild content by SHA-256. Editing a staged
//! ebuild invalidates any prior approval.
//!
//! Safety model: a generated ebuild and its phase functions are **executable,
//! untrusted code**. The model may propose one, but it never runs it. Staging
//! only writes the artifact; building happens solely through the deterministic
//! broker (`CustomEbuildInstall`) whose caller must present the digest that was
//! reviewed. There is no path from a proposal to a privileged shell.
use std::path::{Path, PathBuf};
use serde::{Deserialize, Serialize};
use crate::error::{ExecError, Result};
use crate::exec::Exec;
/// The dedicated Phoebus overlay, relative to the target root.
pub const OVERLAY_REL: &str = "var/db/repos/phoebus";
/// The Portage repository configuration, relative to the target root.
pub const REPOS_CONF_REL: &str = "etc/portage/repos.conf/phoebus.conf";
/// A staged custom ebuild with its approval-bound digest.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct StagedEbuild {
pub atom: String,
pub version: String,
/// SHA-256 of the exact ebuild content that was staged.
pub digest: String,
/// Why custom packaging was needed instead of an existing package.
pub rationale: String,
pub created_unix: u64,
}
impl StagedEbuild {
pub fn package_name(&self) -> String {
self.atom
.split('/')
.nth(1)
.unwrap_or(&self.atom)
.to_string()
}
}
fn now_unix() -> u64 {
std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.map(|d| d.as_secs())
.unwrap_or(0)
}
fn overlay_dir(root: &Path) -> PathBuf {
root.join(OVERLAY_REL)
}
fn package_dir(root: &Path, atom: &str) -> Result<PathBuf> {
let (category, package) = atom.split_once('/').ok_or_else(|| {
ExecError::operation(
"ebuild",
"resolve overlay path",
"atom must be category/package",
)
})?;
if category.is_empty() || package.is_empty() {
return Err(ExecError::operation(
"ebuild",
"resolve overlay path",
"atom must be category/package",
));
}
Ok(overlay_dir(root).join(category).join(package))
}
fn ebuild_path(root: &Path, atom: &str, version: &str) -> Result<PathBuf> {
let package = atom.split('/').nth(1).unwrap_or(atom);
Ok(package_dir(root, atom)?.join(format!("{package}-{version}.ebuild")))
}
/// Ensure the overlay is registered with Portage. Idempotent.
fn ensure_overlay(exec: &Exec, root: &Path) -> Result<()> {
let dir = overlay_dir(root);
for sub in ["profiles", "metadata"] {
std::fs::create_dir_all(dir.join(sub)).map_err(|e| ExecError::io(dir.join(sub), e))?;
}
let files = [
("profiles/repo_name", "phoebus\n".to_string()),
(
"metadata/layout.conf",
"masters = gentoo\nthin-manifests = false\n".to_string(),
),
(
"profiles/categories",
// Categories are added as needed; an empty list is valid.
String::new(),
),
];
for (rel, contents) in files {
let path = dir.join(rel);
if !path.exists() {
std::fs::write(&path, contents).map_err(|e| ExecError::io(path, e))?;
}
}
// Write the repository configuration.
let conf = root.join(REPOS_CONF_REL);
if let Some(parent) = conf.parent() {
std::fs::create_dir_all(parent).map_err(|e| ExecError::io(parent.to_path_buf(), e))?;
}
let location = dir.to_string_lossy().to_string();
let contents = format!("[phoebus]\nlocation = {location}\npriority = 100\nauto-sync = no\n");
if exec.dry_run {
exec.logger
.info("[dry-run] would register the Phoebus overlay");
} else {
std::fs::write(&conf, contents).map_err(|e| ExecError::io(conf, e))?;
}
Ok(())
}
/// Stage an ebuild. This does **not** build or install anything; it records the
/// artifact and the reason it exists, and returns its content digest.
pub fn prepare(
exec: &Exec,
root: &Path,
atom: &str,
version: &str,
rationale: &str,
ebuild: &str,
) -> Result<StagedEbuild> {
// Defence in depth: even though the action validator checks these, staging
// re-checks so no path traversal can reach the overlay.
if !phoebus_core::action::valid_ebuild_atom(atom)
|| !phoebus_core::action::valid_ebuild_version(version)
{
return Err(ExecError::operation(
"ebuild",
"stage ebuild",
"invalid atom or version",
));
}
if ebuild.contains('\0') {
return Err(ExecError::operation(
"ebuild",
"stage ebuild",
"ebuild content contains a NUL byte",
));
}
ensure_overlay(exec, root)?;
let dir = package_dir(root, atom)?;
std::fs::create_dir_all(&dir).map_err(|e| ExecError::io(dir.clone(), e))?;
let path = ebuild_path(root, atom, version)?;
let digest = crate::opencode::sha256_hex(ebuild.as_bytes());
if exec.dry_run {
exec.logger.info(format!(
"[dry-run] would stage custom ebuild {atom}-{version}"
));
return Ok(StagedEbuild {
atom: atom.to_string(),
version: version.to_string(),
digest,
rationale: rationale.to_string(),
created_unix: now_unix(),
});
}
std::fs::write(&path, ebuild).map_err(|e| ExecError::io(path.clone(), e))?;
let record = StagedEbuild {
atom: atom.to_string(),
version: version.to_string(),
digest,
rationale: rationale.to_string(),
created_unix: now_unix(),
};
write_record(root, &record)?;
exec.logger.info(format!(
"staged custom ebuild {atom}-{version} (not installed)"
));
Ok(record)
}
fn record_path(root: &Path, atom: &str) -> Result<PathBuf> {
Ok(package_dir(root, atom)?.join(".phoebus-ebuild.toml"))
}
fn write_record(root: &Path, record: &StagedEbuild) -> Result<()> {
let path = record_path(root, &record.atom)?;
let text = toml::to_string_pretty(record)
.map_err(|e| ExecError::operation("ebuild", "write record", e.to_string()))?;
std::fs::write(&path, text).map_err(|e| ExecError::io(path, e))
}
/// Look up the staged record for an atom (newest if several).
pub fn staged(root: &Path, atom: &str) -> Option<StagedEbuild> {
let path = record_path(root, atom).ok()?;
let text = std::fs::read_to_string(path).ok()?;
toml::from_str(&text).ok()
}
/// List every staged custom ebuild.
pub fn list(root: &Path) -> Vec<StagedEbuild> {
let mut out = Vec::new();
let dir = overlay_dir(root);
let Ok(categories) = std::fs::read_dir(&dir) else {
return out;
};
for category in categories.flatten() {
if !category.path().is_dir() {
continue;
}
let Ok(packages) = std::fs::read_dir(category.path()) else {
continue;
};
for package in packages.flatten() {
let record = package.path().join(".phoebus-ebuild.toml");
if let Ok(text) = std::fs::read_to_string(record) {
if let Ok(staged) = toml::from_str::<StagedEbuild>(&text) {
out.push(staged);
}
}
}
}
out.sort_by(|a, b| {
(a.atom.clone(), a.version.clone()).cmp(&(b.atom.clone(), b.version.clone()))
});
out
}
/// Re-read the exact staged ebuild content and confirm it still matches the
/// approved digest. Any change invalidates the approval.
pub fn verify_digest(root: &Path, ebuild: &StagedEbuild) -> Result<()> {
let current = staged(root, &ebuild.atom).ok_or_else(|| {
ExecError::operation(
"ebuild",
"verify approval",
"the ebuild is no longer staged",
)
})?;
if current.digest != ebuild.digest {
return Err(ExecError::operation(
"ebuild",
"verify approval",
"the staged ebuild changed since it was reviewed; re-review before installing",
));
}
let path = ebuild_path(root, &ebuild.atom, &ebuild.version)?;
let content = std::fs::read(&path).map_err(|e| ExecError::io(path.clone(), e))?;
let actual = crate::opencode::sha256_hex(&content);
if actual != ebuild.digest {
return Err(ExecError::operation(
"ebuild",
"verify approval",
"the ebuild content no longer matches the approved digest",
));
}
Ok(())
}
/// Build and install a staged ebuild through Portage.
///
/// The caller must present the digest that was reviewed. The ebuild is
/// untrusted code: it is built inside the target chroot with Portage's own
/// build sandbox (`sandbox`, `userpriv`) and `ebuild ... manifest`, never by
/// the model and never with an unrestricted shell.
pub fn install(exec: &Exec, root: &Path, atom: &str, version: &str, digest: &str) -> Result<()> {
if exec.dry_run {
exec.logger.info(format!(
"[dry-run] would build and install {atom}-{version} from the Phoebus overlay"
));
return Ok(());
}
let record = staged(root, atom).ok_or_else(|| {
ExecError::operation(
"ebuild",
"install custom ebuild",
format!("{atom} is not staged"),
)
})?;
if record.version != version || record.digest != digest {
return Err(ExecError::operation(
"ebuild",
"install custom ebuild",
"the requested version/digest does not match the staged artifact",
));
}
verify_digest(root, &record)?;
ensure_overlay(exec, root)?;
let ebuild = ebuild_path(root, atom, version)?;
// Generate the Manifest (sources must already be fetchable). This runs the
// ebuild's metadata phase, which is why it happens only after approval.
crate::portage::chroot(
exec,
root,
"ebuild",
&[&ebuild.to_string_lossy(), "manifest"],
)?;
// Build and install through Portage, with its build sandbox and unprivileged
// build user enabled.
let features = "sandbox userpriv".to_string();
let spec = crate::portage::chroot_spec(
"ebuild",
&format!("emerge {atom}"),
root,
"emerge",
&[
"--ask=n".into(),
"--quiet-build=y".into(),
"--noreplace".into(),
atom.to_string(),
],
)
.env("FEATURES", features);
exec.run(spec)?;
exec.logger
.info(format!("installed custom ebuild {atom}-{version}"));
Ok(())
}
/// Unmerge a custom package and remove its ebuild from the overlay.
pub fn remove(exec: &Exec, root: &Path, atom: &str) -> Result<()> {
if exec.dry_run {
exec.logger
.info(format!("[dry-run] would remove custom ebuild {atom}"));
return Ok(());
}
// Unmerge through Portage; a package that is not installed is not an error.
let _ = crate::portage::chroot(exec, root, "emerge", &["--unmerge", "--ask=n", atom]);
let dir = package_dir(root, atom)?;
if dir.is_dir() {
std::fs::remove_dir_all(&dir).map_err(|e| ExecError::io(dir, e))?;
}
exec.logger.info(format!(
"removed custom ebuild {atom} from the Phoebus overlay"
));
Ok(())
}
/// A deterministic command name for QA tooling; used in reviews.
pub fn qa_hint() -> &'static str {
"GENTOO_QA: run `pkgcheck scan` on the overlay entry before installing"
}
#[cfg(test)]
mod tests {
use super::*;
use crate::command::{CommandOutput, RecordingRunner};
use crate::log::Logger;
use phoebus_core::Redactor;
use std::time::Duration;
fn make_exec(runner: RecordingRunner, dry_run: bool) -> Exec {
let path = tempfile::tempdir().unwrap().keep();
let logger = Logger::open(path.join("l.log"), Redactor::new(), false);
Exec::new(Box::new(runner), logger, dry_run, path.join("root"), path)
}
const SAMPLE: &str = "\
EAPI=8
DESCRIPTION=\"Example\"
SLOT=\"0\"
";
#[test]
fn prepare_stages_and_records_a_digest() {
let exec = make_exec(RecordingRunner::new(), false);
let root = tempfile::tempdir().unwrap();
let staged = prepare(
&exec,
root.path(),
"app-misc/example",
"1.0",
"no maintained package provides the required feature",
SAMPLE,
)
.unwrap();
assert_eq!(staged.digest.len(), 64);
assert!(ebuild_path(root.path(), "app-misc/example", "1.0")
.unwrap()
.is_file());
assert!(root.path().join(REPOS_CONF_REL).is_file());
let found = staged_(root.path(), "app-misc/example");
assert_eq!(found.digest, staged.digest);
assert_eq!(list(root.path()).len(), 1);
}
fn staged_(root: &Path, atom: &str) -> StagedEbuild {
staged(root, atom).expect("staged record")
}
#[test]
fn editing_a_staged_ebuild_invalidates_the_digest() {
let exec = make_exec(RecordingRunner::new(), false);
let root = tempfile::tempdir().unwrap();
let staged = prepare(
&exec,
root.path(),
"app-misc/example",
"1.0",
"reason",
SAMPLE,
)
.unwrap();
verify_digest(root.path(), &staged).unwrap();
// Tamper with the file after approval.
let path = ebuild_path(root.path(), "app-misc/example", "1.0").unwrap();
std::fs::write(&path, "EAPI=8\n# changed\n").unwrap();
let err = verify_digest(root.path(), &staged).unwrap_err();
assert!(err.to_string().contains("no longer matches"), "{err}");
}
#[test]
fn install_requires_the_reviewed_digest() {
let exec = make_exec(RecordingRunner::new(), false);
let root = tempfile::tempdir().unwrap();
prepare(
&exec,
root.path(),
"app-misc/example",
"1.0",
"reason",
SAMPLE,
)
.unwrap();
// Wrong digest is refused before any build command.
let err = install(
&exec,
root.path(),
"app-misc/example",
"1.0",
&"a".repeat(64),
)
.unwrap_err();
assert!(err.to_string().contains("does not match"), "{err}");
}
#[test]
fn install_runs_manifest_then_emerge_in_the_target() {
let runner = RecordingRunner::new();
let exec = make_exec(runner.clone(), false);
let root = tempfile::tempdir().unwrap();
let staged = prepare(
&exec,
root.path(),
"app-misc/example",
"1.0",
"reason",
SAMPLE,
)
.unwrap();
let mut install_exec = make_exec(runner.clone(), false);
install_exec.root = root.path().to_path_buf();
install(
&install_exec,
root.path(),
"app-misc/example",
"1.0",
&staged.digest,
)
.unwrap();
let specs = runner.recorded();
let manifest = specs
.iter()
.position(|s| s.args.iter().any(|a| a == "manifest"));
let emerge = specs
.iter()
.position(|s| s.args.iter().any(|a| a == "emerge"));
assert!(manifest.is_some(), "manifest must be generated");
assert!(emerge.is_some(), "emerge must run");
assert!(manifest.unwrap() < emerge.unwrap(), "manifest before build");
// The build must enable Portage's sandbox.
let build = specs
.iter()
.find(|s| s.args.iter().any(|a| a == "emerge"))
.unwrap();
assert!(build
.env
.iter()
.any(|(k, v)| k == "FEATURES" && v.contains("sandbox")));
}
#[test]
fn remove_unmerges_and_deletes_the_overlay_entry() {
let exec = make_exec(RecordingRunner::new(), false);
let root = tempfile::tempdir().unwrap();
prepare(
&exec,
root.path(),
"app-misc/example",
"1.0",
"reason",
SAMPLE,
)
.unwrap();
remove(&exec, root.path(), "app-misc/example").unwrap();
assert!(!package_dir(root.path(), "app-misc/example")
.unwrap()
.exists());
assert!(staged(root.path(), "app-misc/example").is_none());
}
#[test]
fn dry_run_stages_nothing_and_runs_nothing() {
let runner = RecordingRunner::new();
let exec = make_exec(runner.clone(), true);
let root = tempfile::tempdir().unwrap();
let staged = prepare(
&exec,
root.path(),
"app-misc/example",
"1.0",
"reason",
SAMPLE,
)
.unwrap();
assert!(!ebuild_path(root.path(), "app-misc/example", "1.0")
.unwrap()
.exists());
install(
&exec,
root.path(),
"app-misc/example",
"1.0",
&staged.digest,
)
.unwrap();
assert!(runner.recorded().is_empty());
}
#[test]
fn weird_atoms_cannot_escape_the_overlay() {
let exec = make_exec(RecordingRunner::new(), false);
let root = tempfile::tempdir().unwrap();
for atom in ["../../etc/passwd", "a/b/c", "/bin/sh", "a//b"] {
assert!(
prepare(&exec, root.path(), atom, "1.0", "r", SAMPLE).is_err(),
"atom {atom} must be refused"
);
}
}
#[test]
fn helper_sha256_is_stable() {
let _ = CommandOutput {
status: 0,
success: true,
stdout: Vec::new(),
stderr: Vec::new(),
duration: Duration::ZERO,
};
assert_eq!(
crate::opencode::sha256_hex(b"abc"),
"ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
);
}
}

View file

@ -7,10 +7,13 @@
pub mod actions; pub mod actions;
pub mod admin; pub mod admin;
pub mod ai; pub mod ai;
pub mod appimage;
pub mod auth; pub mod auth;
pub mod boot; pub mod boot;
pub mod chooser;
pub mod command; pub mod command;
pub mod desktop; pub mod desktop;
pub mod ebuild;
pub mod encryption; pub mod encryption;
pub mod error; pub mod error;
pub mod exec; pub mod exec;
@ -26,9 +29,11 @@ pub mod probe;
pub mod rollback; pub mod rollback;
pub mod sandbox; pub mod sandbox;
pub mod services; pub mod services;
pub mod snap;
pub mod snapshot; pub mod snapshot;
pub mod stage3; pub mod stage3;
pub mod storage; pub mod storage;
pub mod sys_runtime;
pub mod transaction; pub mod transaction;
pub mod update; pub mod update;
pub mod users; pub mod users;

View file

@ -0,0 +1,473 @@
//! Snap as an optional sandboxed application lane.
//!
//! Snap is not part of a default Phoebus install. When the user chooses it, the
//! `app-containers/snapd` package is installed **through Portage** (systemd USE
//! is mandatory and AppArmor is recommended — see the Gentoo wiki), the
//! `snapd.socket` unit is enabled, and snaps are managed through the `snap`
//! client.
//!
//! The lane is honest about its capabilities: the daemon must actually be ready,
//! application confinement is detected rather than assumed, and the classic
//! (unconfined) mode is a security downgrade that must be requested explicitly.
//! Long-lived access (connections) and the automatic refresh schedule are
//! surfaced so the reviewed plan reflects the real system.
use crate::command::CommandSpec;
use crate::error::{ExecError, Result};
use crate::exec::Exec;
/// The Gentoo package that provides snapd (verified against the Gentoo wiki).
pub const SNAPD_ATOM: &str = "app-containers/snapd";
/// The unit that must be active for the daemon to answer.
pub const SNAPD_SOCKET: &str = "snapd.socket";
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Confinement {
/// Full AppArmor confinement.
Strict,
/// Some interfaces are unconfined (older kernels or devmode).
Partial,
/// Confinement is disabled (e.g. forced-devmode, or no LSM).
None,
}
impl Confinement {
pub fn as_str(self) -> &'static str {
match self {
Confinement::Strict => "strict",
Confinement::Partial => "partial",
Confinement::None => "none",
}
}
/// Whether application confinement is actually enforced.
pub fn enforced(self) -> bool {
self == Confinement::Strict
}
}
/// The detected state of the Snap lane.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SnapdStatus {
pub client_present: bool,
pub daemon_ready: bool,
pub confinement: Confinement,
}
impl SnapdStatus {
pub fn usable(&self) -> bool {
self.client_present && self.daemon_ready
}
}
/// One installed snap.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SnapEntry {
pub name: String,
pub version: String,
pub revision: String,
pub channel: String,
pub publisher: String,
pub notes: String,
}
/// A search result from `snap find`.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SnapCandidate {
pub name: String,
pub version: String,
pub publisher: String,
pub summary: String,
}
/// Parse `snap debug confinement` output (`strict`, `partial`, `none`).
pub fn parse_confinement(text: &str) -> Confinement {
let t = text.trim().to_ascii_lowercase();
if t.contains("strict") {
Confinement::Strict
} else if t.contains("partial") {
Confinement::Partial
} else {
Confinement::None
}
}
/// Detect whether snapd is installed and its daemon is actually answering.
pub fn status(exec: &Exec) -> Result<SnapdStatus> {
let client = exec
.runner
.execute(&CommandSpec::new("snap", "snap client version", "snap").arg("--version"));
let client_present = client.map(|o| o.success).unwrap_or(false);
if !client_present {
return Ok(SnapdStatus {
client_present: false,
daemon_ready: false,
confinement: Confinement::None,
});
}
let daemon = exec.runner.execute(
&CommandSpec::new("snap", "snapd socket state", "systemctl")
.args(["is-active", SNAPD_SOCKET]),
);
let daemon_ready = daemon
.map(|o| o.success && o.stdout_lossy().trim() == "active")
.unwrap_or(false);
let confinement = if daemon_ready {
exec.runner
.execute(
&CommandSpec::new("snap", "snap confinement", "snap")
.args(["debug", "confinement"]),
)
.map(|o| parse_confinement(&o.stdout_lossy()))
.unwrap_or(Confinement::None)
} else {
Confinement::None
};
Ok(SnapdStatus {
client_present,
daemon_ready,
confinement,
})
}
/// Install snapd through Portage and enable its socket on the running system.
///
/// This is the only supported way to introduce the lane: snapd must be a
/// Portage-managed system component, never a `curl | sh` artifact.
pub fn ensure_snapd(exec: &Exec) -> Result<()> {
exec.logger
.info(format!("installing {SNAPD_ATOM} through Portage (systemd)"));
exec.run(
CommandSpec::new("snap", "install snapd", "emerge")
.args(["--ask=n", "--quiet-build=y", "--noreplace"])
.arg(SNAPD_ATOM),
)?;
exec.run(
CommandSpec::new("snap", "enable snapd socket", "systemctl").args([
"enable",
"--now",
SNAPD_SOCKET,
]),
)?;
Ok(())
}
/// Whether a usable snapd is present; install it first when missing.
fn require_ready(exec: &Exec) -> Result<SnapdStatus> {
let status = status(exec)?;
if !status.usable() {
return Err(ExecError::operation(
"snap",
"use snap",
format!(
"snapd is not ready (client present: {}, daemon active: {}); \
install {SNAPD_ATOM} and enable {SNAPD_SOCKET} through Portage first",
status.client_present, status.daemon_ready
),
));
}
Ok(status)
}
fn snap_spec(operation: &str, args: &[String]) -> CommandSpec {
CommandSpec::new("snap", operation, "snap").args(args.iter().cloned())
}
/// `snap find <query>` captured output.
pub fn find(exec: &Exec, query: &str) -> Result<String> {
require_ready(exec)?;
let out = exec.runner.execute(&snap_spec(
"find snaps",
&["find".into(), query.to_string(), "--color=never".into()],
))?;
Ok(out.stdout_lossy())
}
/// `snap info <name>` captured output (channel map, confinement, publisher).
pub fn info(exec: &Exec, name: &str) -> Result<String> {
require_ready(exec)?;
let out = exec.runner.execute(&snap_spec(
"snap info",
&["info".into(), name.to_string(), "--color=never".into()],
))?;
Ok(out.stdout_lossy())
}
/// `snap connections <name>` captured output (the permissions a snap holds).
pub fn connections(exec: &Exec, name: &str) -> Result<String> {
require_ready(exec)?;
let out = exec.runner.execute(&snap_spec(
"snap connections",
&[
"connections".into(),
name.to_string(),
"--color=never".into(),
],
))?;
Ok(out.stdout_lossy())
}
/// `snap list` parsed into entries.
pub fn list(exec: &Exec) -> Result<Vec<SnapEntry>> {
require_ready(exec)?;
let out = exec
.runner
.execute(&snap_spec("list snaps", &["list".into()]))?;
Ok(parse_list(&out.stdout_lossy()))
}
/// Install a snap. Classic confinement must be requested explicitly by the
/// caller and is surfaced in the reviewed plan.
pub fn install(exec: &Exec, name: &str, channel: Option<&str>, classic: bool) -> Result<String> {
let _ = require_ready(exec)?;
let mut args = vec!["install".to_string(), name.to_string()];
if let Some(channel) = channel {
args.push(format!("--channel={channel}"));
}
if classic {
args.push("--classic".into());
}
let out = exec.run(snap_spec("install snap", &args))?;
Ok(out.stdout_lossy())
}
/// Remove a snap. Snap data under `/var/snap` is snapd's to manage.
pub fn remove(exec: &Exec, name: &str) -> Result<String> {
require_ready(exec)?;
let out = exec.run(snap_spec(
"remove snap",
&["remove".into(), name.to_string()],
))?;
Ok(out.stdout_lossy())
}
/// Refresh one snap, or all snaps when `name` is `None`.
///
/// Note: snapd refreshes automatically on its own schedule, so an explicit
/// refresh is an acceleration, not the only update path. The reviewed plan
/// says so.
pub fn refresh(exec: &Exec, name: Option<&str>) -> Result<String> {
require_ready(exec)?;
let mut args = vec!["refresh".to_string()];
if let Some(name) = name {
args.push(name.to_string());
}
let out = exec.run(snap_spec("refresh snaps", &args))?;
Ok(out.stdout_lossy())
}
/// Parse `snap list` output. The first line is a header. The `Notes` column is
/// last and may contain spaces, so it is treated as the remainder.
pub fn parse_list(text: &str) -> Vec<SnapEntry> {
let mut entries = Vec::new();
for (i, line) in text.lines().enumerate() {
if i == 0 || line.trim().is_empty() {
continue;
}
let cols: Vec<&str> = line.split_whitespace().collect();
if cols.len() < 5 {
continue;
}
let notes = cols[5..].join(" ");
entries.push(SnapEntry {
name: cols[0].to_string(),
version: cols[1].to_string(),
revision: cols[2].to_string(),
channel: cols[3].to_string(),
publisher: cols[4].to_string(),
notes,
});
}
entries
}
/// The stable channel/revision line from `snap info`, used to record version
/// and confinement in the reviewed plan and the AppImage-style manifest.
pub fn parse_info_summary(text: &str) -> (Option<String>, Option<String>, Confinement) {
let mut version = None;
let mut channel = None;
let mut confinement = Confinement::Strict;
for line in text.lines() {
let trimmed = line.trim();
if let Some(rest) = trimmed.strip_prefix("latest/stable:") {
let mut parts = rest.split_whitespace();
version = parts.next().map(str::to_string);
channel = Some("latest/stable".to_string());
}
if let Some(rest) = trimmed.strip_prefix("confinement:") {
confinement = parse_confinement(rest);
}
}
(version, channel, confinement)
}
/// Parse `snap find` output (header + rows of `name version publisher summary`).
pub fn parse_find(text: &str) -> Vec<SnapCandidate> {
let mut out = Vec::new();
for (i, line) in text.lines().enumerate() {
if i == 0 || line.trim().is_empty() {
continue;
}
// Guard against a dashed separator row.
if line.trim().chars().all(|c| c == '-' || c.is_whitespace()) {
continue;
}
let cols: Vec<&str> = line.split_whitespace().collect();
if cols.len() < 3 {
continue;
}
let summary = cols[3..].join(" ");
out.push(SnapCandidate {
name: cols[0].to_string(),
version: cols[1].to_string(),
publisher: cols[2].to_string(),
summary,
});
}
out
}
#[cfg(test)]
mod tests {
use super::*;
use crate::command::{CommandOutput, RecordingRunner};
use crate::log::Logger;
use phoebus_core::Redactor;
use std::time::Duration;
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 ok(stdout: &str) -> CommandOutput {
CommandOutput {
status: 0,
success: true,
stdout: stdout.as_bytes().to_vec(),
stderr: Vec::new(),
duration: Duration::from_millis(1),
}
}
#[test]
fn confinement_parsing_is_explicit() {
assert_eq!(parse_confinement("strict\n"), Confinement::Strict);
assert_eq!(parse_confinement("partial\n"), Confinement::Partial);
assert_eq!(parse_confinement("none\n"), Confinement::None);
assert_eq!(parse_confinement(""), Confinement::None);
assert!(Confinement::Strict.enforced());
assert!(!Confinement::None.enforced());
}
#[test]
fn status_requires_both_client_and_daemon() {
let runner = RecordingRunner::new();
runner.set_response("snap", ok("snap 2.63\n"));
runner.set_response("systemctl", ok("inactive\n"));
let exec = make_exec(runner);
let status = status(&exec).unwrap();
assert!(status.client_present);
assert!(!status.daemon_ready);
assert!(!status.usable());
}
#[test]
fn status_reports_confinement_when_ready() {
let runner = RecordingRunner::new();
runner.set_response("snap", ok("snap 2.63\n"));
// `systemctl is-active` and `snap debug confinement` share the `snap`
// program only for the latter; the systemctl call is separate.
runner.set_response("systemctl", ok("active\n"));
// The second `snap` invocation returns confinement. Because the runner
// keys by program, use a default that returns `strict` for snap info
// style output but `--version` was already consumed above; this test
// simply proves the readiness gate.
let exec = make_exec(runner);
let status = status(&exec).unwrap();
assert!(status.usable());
}
#[test]
fn install_refuses_when_daemon_is_not_ready() {
let runner = RecordingRunner::new();
runner.set_response("snap", ok("snap 2.63\n"));
runner.set_response("systemctl", ok("inactive\n"));
let exec = make_exec(runner.clone());
let err = install(&exec, "hello-world", None, false).unwrap_err();
assert!(err.to_string().contains("not ready"), "{err}");
// No install command may be attempted.
assert!(!runner
.recorded()
.iter()
.any(|s| s.args.iter().any(|a| a == "install")));
}
#[test]
fn classic_is_only_added_when_requested() {
let runner = RecordingRunner::new();
runner.set_response("snap", ok("snap 2.63\n"));
runner.set_response("systemctl", ok("active\n"));
let exec = make_exec(runner.clone());
let _ = install(&exec, "code", Some("latest/stable"), false);
let normal = runner.recorded();
assert!(!normal
.iter()
.any(|s| s.args.iter().any(|a| a == "--classic")));
assert!(normal
.iter()
.any(|s| s.args.iter().any(|a| a == "--channel=latest/stable")));
let runner2 = RecordingRunner::new();
runner2.set_response("snap", ok("snap 2.63\n"));
runner2.set_response("systemctl", ok("active\n"));
let exec2 = make_exec(runner2.clone());
let _ = install(&exec2, "code", None, true);
assert!(runner2
.recorded()
.iter()
.any(|s| s.args.iter().any(|a| a == "--classic")));
}
#[test]
fn list_and_find_parse_real_shapes() {
let list = "\
Name Version Rev Tracking Publisher Notes
core22 2024 1381 latest/stable canonical✓ base
hello 2.10 29 latest/stable canonical✓ -
";
let entries = parse_list(list);
assert_eq!(entries.len(), 2);
assert_eq!(entries[1].name, "hello");
assert_eq!(entries[1].version, "2.10");
assert_eq!(entries[1].channel, "latest/stable");
let find = "\
Name Version Publisher Notes Summary
hello 2.10 canonical✓ - GNU Hello, the \"hello world\" snap
snap-store 41.3 canonical✓ - Snap Store
";
let found = parse_find(find);
assert_eq!(found.len(), 2);
assert_eq!(found[0].name, "hello");
assert!(found[0].summary.contains("GNU Hello"));
}
#[test]
fn info_summary_records_confinement() {
let info = "\
name: code
confinement: classic
channels:
latest/stable: 1.90.0 2024-01-01 (123) 100MB -
";
let (version, channel, confinement) = parse_info_summary(info);
assert_eq!(version.as_deref(), Some("1.90.0"));
assert_eq!(channel.as_deref(), Some("latest/stable"));
assert_eq!(confinement, Confinement::None);
}
}

View file

@ -0,0 +1,262 @@
//! Trusted discovery, installation, and verification of the `sys` deterministic CLI runtime
//! in the installed target system.
//!
//! The `sys` CLI is an essential, defining subsystem of Phoebus OS: it provides the typed,
//! validated execution boundary for both the AI assistant and the deterministic, network-free
//! recovery fallback. It must be present in the target root before the initial recovery snapshot
//! is taken.
use std::path::{Path, PathBuf};
use crate::error::{ExecError, Result};
use crate::exec::Exec;
use crate::portage;
/// Known trusted system locations where the installer / live medium places the static `sys` binary.
/// Notice that arbitrary user-controlled PATH entries are NOT searched.
const TRUSTED_SYS_PATHS: &[&str] = &[
"/usr/local/bin/sys",
"/run/live/medium/phoebus/bin/sys",
"/usr/bin/sys",
];
/// Validate that a candidate path points to a usable, executable ELF binary.
pub fn validate_sys_payload(path: &Path) -> Result<()> {
if !path.is_file() {
return Err(ExecError::operation(
"sys_runtime",
"validate sys binary",
format!("path is not a regular file: {}", path.display()),
));
}
use std::io::Read;
let mut file = std::fs::File::open(path).map_err(|e| ExecError::io(path.to_path_buf(), e))?;
let mut magic = [0u8; 4];
let n = file
.read(&mut magic)
.map_err(|e| ExecError::io(path.to_path_buf(), e))?;
if n < 4 || &magic != b"\x7fELF" {
return Err(ExecError::operation(
"sys_runtime",
"validate sys binary",
format!(
"{} is not a valid ELF executable (bad magic)",
path.display()
),
));
}
use std::os::unix::fs::PermissionsExt;
let meta = file
.metadata()
.map_err(|e| ExecError::io(path.to_path_buf(), e))?;
if meta.permissions().mode() & 0o111 == 0 {
return Err(ExecError::operation(
"sys_runtime",
"validate sys binary",
format!("{} is not executable", path.display()),
));
}
Ok(())
}
/// Locate a trusted `sys` executable from the installer distribution.
///
/// Order of discovery:
/// 1. Explicit environment override `PHOEBUS_SYS_PATH`.
/// 2. Sibling binary in the same directory as the current running executable.
/// 3. Well-known trusted distribution paths on the live system.
pub fn find_trusted_sys_binary() -> Result<PathBuf> {
if let Some(explicit) = std::env::var_os("PHOEBUS_SYS_PATH") {
let p = PathBuf::from(explicit);
validate_sys_payload(&p).map_err(|e| {
ExecError::operation(
"sys_runtime",
"find sys runtime",
format!("PHOEBUS_SYS_PATH invalid: {e}"),
)
})?;
return Ok(p);
}
if let Ok(current) = std::env::current_exe() {
if let Some(parent) = current.parent() {
let candidate = parent.join("sys");
if candidate.is_file() && validate_sys_payload(&candidate).is_ok() {
return Ok(candidate);
}
}
}
for path_str in TRUSTED_SYS_PATHS {
let candidate = Path::new(path_str);
if candidate.is_file() && validate_sys_payload(candidate).is_ok() {
return Ok(candidate.to_path_buf());
}
}
Err(ExecError::operation(
"sys_runtime",
"find sys runtime",
format!(
"trusted sys binary not found; checked current_exe sibling and [{}]",
TRUSTED_SYS_PATHS.join(", ")
),
))
}
/// Install the `sys` binary into the target filesystem and verify it executes properly.
pub fn install_sys_to_target(exec: &Exec) -> Result<PathBuf> {
let target = exec.target();
if exec.dry_run {
exec.logger
.info("[dry-run] would install sys runtime to /usr/local/bin/sys");
return target.resolve("usr/local/bin/sys").map_err(|e| {
ExecError::operation("sys_runtime", "resolve target path", e.to_string())
});
}
let source_path = find_trusted_sys_binary()?;
exec.logger.info(format!(
"installing sys runtime from {} to /usr/local/bin/sys in target",
source_path.display()
));
let dest = target
.copy_file("usr/local/bin/sys", &source_path, 0o755)
.map_err(|e| {
ExecError::operation(
"sys_runtime",
"copy sys to target",
format!("failed to install sys binary: {e}"),
)
})?;
// Verify target binary exists and is executable
validate_sys_payload(&dest).map_err(|e| {
ExecError::operation(
"sys_runtime",
"verify installed sys",
format!("installed target binary invalid: {e}"),
)
})?;
// Verify execution inside target chroot: run harmless deterministic `sys history`
let root = Path::new(&exec.root);
portage::chroot(exec, root, "/usr/local/bin/sys", &["history"]).map_err(|e| {
ExecError::operation(
"sys_runtime",
"verify sys in chroot",
format!("running sys history in target chroot failed: {e}"),
)
})?;
exec.logger
.info("verified installed sys CLI execution in target");
Ok(dest)
}
#[cfg(test)]
mod tests {
use super::*;
use crate::command::RecordingRunner;
use crate::log::Logger;
use phoebus_core::Redactor;
use std::io::Write;
use std::os::unix::fs::PermissionsExt;
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 create_mock_elf(dir: &Path, name: &str, executable: bool) -> PathBuf {
let path = dir.join(name);
let mut f = std::fs::File::create(&path).unwrap();
// ELF header magic + minimal dummy payload
f.write_all(b"\x7fELF\x02\x01\x01\x00dummy-payload-content")
.unwrap();
f.flush().unwrap();
let mode = if executable { 0o755 } else { 0o644 };
std::fs::set_permissions(&path, std::fs::Permissions::from_mode(mode)).unwrap();
path
}
#[test]
fn validates_valid_elf_executable() {
let tmp = tempfile::tempdir().unwrap();
let elf = create_mock_elf(tmp.path(), "sys", true);
assert!(validate_sys_payload(&elf).is_ok());
}
#[test]
fn rejects_non_elf_file() {
let tmp = tempfile::tempdir().unwrap();
let path = tmp.path().join("fake_sys");
std::fs::write(&path, b"#!/bin/sh\necho hi\n").unwrap();
std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o755)).unwrap();
let err = validate_sys_payload(&path).unwrap_err();
assert!(err.to_string().contains("bad magic"));
}
#[test]
fn rejects_non_executable_elf() {
let tmp = tempfile::tempdir().unwrap();
let elf = create_mock_elf(tmp.path(), "sys_non_exec", false);
let err = validate_sys_payload(&elf).unwrap_err();
assert!(err.to_string().contains("not executable"));
}
struct EnvGuard {
key: &'static str,
original: Option<std::ffi::OsString>,
}
impl EnvGuard {
fn set(key: &'static str, val: &std::ffi::OsStr) -> Self {
let original = std::env::var_os(key);
std::env::set_var(key, val);
Self { key, original }
}
}
impl Drop for EnvGuard {
fn drop(&mut self) {
if let Some(orig) = &self.original {
std::env::set_var(self.key, orig);
} else {
std::env::remove_var(self.key);
}
}
}
#[test]
fn honors_phoebus_sys_path_override() {
let tmp = tempfile::tempdir().unwrap();
let elf = create_mock_elf(tmp.path(), "custom_sys", true);
let _guard = EnvGuard::set("PHOEBUS_SYS_PATH", elf.as_os_str());
let found = find_trusted_sys_binary().expect("must find via PHOEBUS_SYS_PATH");
assert_eq!(found, elf);
}
#[test]
fn install_sys_copies_and_chroots() {
let runner = RecordingRunner::new();
let exec = make_exec(runner);
let tmp = tempfile::tempdir().unwrap();
let mock_elf = create_mock_elf(tmp.path(), "sys", true);
let _guard = EnvGuard::set("PHOEBUS_SYS_PATH", mock_elf.as_os_str());
let installed = install_sys_to_target(&exec).unwrap();
assert!(installed.is_file());
assert_eq!(installed, Path::new(&exec.root).join("usr/local/bin/sys"));
let meta = std::fs::metadata(&installed).unwrap();
assert_ne!(meta.permissions().mode() & 0o111, 0);
}
}

View file

@ -22,7 +22,7 @@ use phoebus_executor::{
}; };
#[derive(Parser, Debug)] #[derive(Parser, Debug)]
#[command(name = "sys", about = "Phoebus system interface")] #[command(name = "sys", about = "Phoebus system interface", version)]
struct Cli { struct Cli {
/// Natural-language instruction, e.g. `enable sshd`. /// Natural-language instruction, e.g. `enable sshd`.
text: Vec<String>, text: Vec<String>,
@ -191,7 +191,10 @@ fn run() -> std::result::Result<(), Box<dyn std::error::Error>> {
Some(a) => a, Some(a) => a,
None => { None => {
eprintln!("sys: could not parse `{phrase}` deterministically."); eprintln!("sys: could not parse `{phrase}` deterministically.");
eprintln!("Examples: sys enable sshd | sys disable bluetooth | sys history"); eprintln!(
"Examples: sys enable sshd | sys install vim | sys choose firefox | \
sys history"
);
eprintln!("Or ask the assistant: sys ask \"<request>\""); eprintln!("Or ask the assistant: sys ask \"<request>\"");
return Err("unsupported instruction".into()); return Err("unsupported instruction".into());
} }
@ -272,38 +275,60 @@ fn gather_facts(exec: &Exec) -> SystemFacts {
SystemFacts::from_system(&config, &hardware, &history, binhost, None) SystemFacts::from_system(&config, &hardware, &history, binhost, None)
} }
fn load_installed_ai_config(root: &Path) -> Option<phoebus_core::AiConfig> {
let conf_path = root.join("etc/phoebus/assistant.conf");
let text = std::fs::read_to_string(&conf_path).ok()?;
toml::from_str(&text).ok()
}
/// The AI backend selected on the command line or the environment. /// The AI backend selected on the command line or the environment.
fn resolve_backend(cli: &Cli) -> AiBackend { fn resolve_backend(cli: &Cli, conf: Option<&phoebus_core::AiConfig>) -> AiBackend {
let raw = cli let raw = cli
.ai_backend .ai_backend
.clone() .clone()
.or_else(|| std::env::var("PHOEBUS_AI_BACKEND").ok()) .or_else(|| std::env::var("PHOEBUS_AI_BACKEND").ok())
.or_else(|| conf.map(|c| c.backend.as_str().to_string()))
.unwrap_or_default(); .unwrap_or_default();
AiBackend::parse(&raw).unwrap_or(AiBackend::Direct) AiBackend::parse(&raw).unwrap_or(AiBackend::Direct)
} }
/// The provider selected on the command line or the environment. /// The provider selected on the command line or the environment.
fn resolve_provider(cli: &Cli) -> ProviderKind { fn resolve_provider(cli: &Cli, conf: Option<&phoebus_core::AiConfig>) -> ProviderKind {
let raw = cli let raw = cli
.ai_provider .ai_provider
.clone() .clone()
.or_else(|| std::env::var("PHOEBUS_AI_PROVIDER").ok()) .or_else(|| std::env::var("PHOEBUS_AI_PROVIDER").ok())
.or_else(|| conf.map(|c| c.provider.clone()))
.unwrap_or_default(); .unwrap_or_default();
ProviderKind::parse(&raw).unwrap_or(ProviderKind::None) ProviderKind::parse(&raw).unwrap_or(ProviderKind::None)
} }
fn resolve_endpoint(cli: &Cli, provider: ProviderKind) -> String { fn resolve_endpoint(
cli: &Cli,
provider: ProviderKind,
conf: Option<&phoebus_core::AiConfig>,
) -> String {
cli.ai_endpoint cli.ai_endpoint
.clone() .clone()
.or_else(|| std::env::var("PHOEBUS_AI_ENDPOINT").ok()) .or_else(|| std::env::var("PHOEBUS_AI_ENDPOINT").ok())
.or_else(|| {
conf.and_then(|c| {
if c.endpoint.is_empty() {
None
} else {
Some(c.endpoint.clone())
}
})
})
.filter(|s| !s.trim().is_empty()) .filter(|s| !s.trim().is_empty())
.unwrap_or_else(|| provider.endpoint().to_string()) .unwrap_or_else(|| provider.endpoint().to_string())
} }
fn resolve_model(cli: &Cli) -> String { fn resolve_model(cli: &Cli, conf: Option<&phoebus_core::AiConfig>) -> String {
cli.ai_model cli.ai_model
.clone() .clone()
.or_else(|| std::env::var("PHOEBUS_AI_MODEL").ok()) .or_else(|| std::env::var("PHOEBUS_AI_MODEL").ok())
.or_else(|| conf.map(|c| c.model.clone()))
.unwrap_or_default() .unwrap_or_default()
} }
@ -325,7 +350,10 @@ fn deterministic_fallback(instruction: &str) {
eprintln!("Run it as: sys {}", instruction.trim()); eprintln!("Run it as: sys {}", instruction.trim());
} }
None => { None => {
eprintln!(" Examples: sys enable sshd | sys install vim | sys history | sys undo"); eprintln!(
" Examples: sys enable sshd | sys install vim | sys choose firefox | \
sys history | sys undo"
);
eprintln!(" A model only makes this easier; it is never required."); eprintln!(" A model only makes this easier; it is never required.");
} }
} }
@ -339,7 +367,8 @@ fn run_ask(
instruction: &str, instruction: &str,
) -> std::result::Result<(), Box<dyn std::error::Error>> { ) -> std::result::Result<(), Box<dyn std::error::Error>> {
let facts = gather_facts(exec); let facts = gather_facts(exec);
let backend = resolve_backend(cli); let conf = load_installed_ai_config(&cli.root);
let backend = resolve_backend(cli, conf.as_ref());
let (provider, endpoint, model); let (provider, endpoint, model);
let transport: Box<dyn ModelTransport + '_>; let transport: Box<dyn ModelTransport + '_>;
@ -349,16 +378,19 @@ fn run_ask(
.opencode_server .opencode_server
.clone() .clone()
.or_else(|| std::env::var("PHOEBUS_OPENCODE_SERVER").ok()) .or_else(|| std::env::var("PHOEBUS_OPENCODE_SERVER").ok())
.or_else(|| conf.as_ref().map(|c| c.opencode_server.clone()))
.unwrap_or_default(); .unwrap_or_default();
let opencode_provider = cli let opencode_provider = cli
.opencode_provider .opencode_provider
.clone() .clone()
.or_else(|| std::env::var("PHOEBUS_OPENCODE_PROVIDER").ok()) .or_else(|| std::env::var("PHOEBUS_OPENCODE_PROVIDER").ok())
.or_else(|| conf.as_ref().map(|c| c.opencode_provider.clone()))
.unwrap_or_default(); .unwrap_or_default();
let opencode_model = cli let opencode_model = cli
.opencode_model .opencode_model
.clone() .clone()
.or_else(|| std::env::var("PHOEBUS_OPENCODE_MODEL").ok()) .or_else(|| std::env::var("PHOEBUS_OPENCODE_MODEL").ok())
.or_else(|| conf.as_ref().map(|c| c.opencode_model.clone()))
.unwrap_or_default(); .unwrap_or_default();
if server.trim().is_empty() if server.trim().is_empty()
|| opencode_provider.trim().is_empty() || opencode_provider.trim().is_empty()
@ -394,7 +426,7 @@ fn run_ask(
); );
} }
AiBackend::Direct => { AiBackend::Direct => {
let resolved = resolve_provider(cli); let resolved = resolve_provider(cli, conf.as_ref());
if resolved == ProviderKind::None { if resolved == ProviderKind::None {
deterministic_fallback(instruction); deterministic_fallback(instruction);
return Err("no AI provider configured".into()); return Err("no AI provider configured".into());
@ -418,8 +450,8 @@ fn run_ask(
); );
eprintln!("{}", facts.render()); eprintln!("{}", facts.render());
provider = resolved; provider = resolved;
endpoint = resolve_endpoint(cli, resolved); endpoint = resolve_endpoint(cli, resolved, conf.as_ref());
model = resolve_model(cli); model = resolve_model(cli, conf.as_ref());
let direct = phoebus_executor::ai::CurlTransport::new(exec, key); let direct = phoebus_executor::ai::CurlTransport::new(exec, key);
transport = if cli.no_sandbox { transport = if cli.no_sandbox {
Box::new(direct) Box::new(direct)

View file

@ -9,7 +9,7 @@ use std::path::PathBuf;
use phoebus_core::policy::{load_history, PackagePolicyEngine, PolicyContext}; use phoebus_core::policy::{load_history, PackagePolicyEngine, PolicyContext};
use phoebus_core::validate::ValidationIssue; use phoebus_core::validate::ValidationIssue;
use phoebus_core::{ use phoebus_core::{
validate, Filesystem, HardwareReport, InstallConfig, InstallPlan, SecretString, validate, DesktopProfile, Filesystem, HardwareReport, InstallConfig, InstallPlan, SecretString,
}; };
use phoebus_executor::storage::StorageState; use phoebus_executor::storage::StorageState;
use phoebus_executor::{ use phoebus_executor::{
@ -326,6 +326,29 @@ impl Installer {
return Ok(()); return Ok(());
} }
self.revalidate_target_disk()?; self.revalidate_target_disk()?;
storage::require_tools(&self.exec)?;
if self.config.is_encrypted() {
self.exec.require_tools(&["cryptsetup"])?;
if luks_passphrase.is_none()
|| luks_passphrase
.map(|p| p.expose().is_empty())
.unwrap_or(true)
{
return Err(phoebus_executor::ExecError::operation(
"storage_prepare",
"validate secrets",
"encryption is enabled but no LUKS passphrase was supplied",
));
}
}
if let Err(e) = phoebus_executor::sys_runtime::find_trusted_sys_binary() {
return Err(phoebus_executor::ExecError::operation(
"storage_prepare",
"check sys runtime",
format!("required sys runtime is missing or unusable: {e}"),
));
}
storage::prepare( storage::prepare(
&self.exec, &self.exec,
&self.config, &self.config,
@ -696,28 +719,47 @@ impl Installer {
return Ok(()); return Ok(());
} }
let _ = self.exec.export_log(); let _ = self.exec.export_log();
// Rewrite the desktop entry point last so it cannot be shadowed by an
// earlier stage; a no-op for non-desktop profiles. // 1. Install matching sys runtime into target before recovery snapshot.
if let Err(e) = desktop::write_session_script(&self.exec, &self.config) { phoebus_executor::sys_runtime::install_sys_to_target(&self.exec)?;
self.exec
.logger // 2. Persist non-secret assistant configuration so `sudo sys ask` keeps its settings.
.warn(format!("could not write session script: {e}")); if self.config.ai.enabled
|| !self.config.ai.provider.is_empty()
|| !self.config.ai.opencode_server.is_empty()
{
if let Ok(toml_str) = toml::to_string(&self.config.ai) {
let _ = self
.exec
.target()
.write("etc/phoebus/assistant.conf", toml_str);
}
} }
// 3. Rewrite the desktop entry point last so it cannot be shadowed by an
// earlier stage; a no-op for non-desktop profiles.
desktop::write_session_script(&self.exec, &self.config)?;
// 4. Verify target integrity before snapshotting and unmounting.
self.verify_installed_system()?;
// 5. Initial known-good recovery point snapshot and boot entry.
self.create_initial_recovery_point(auth); 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 // 6. Durability flush before unmounting.
// lose the final files (the session script and the exported log). self.exec.run(phoebus_executor::command::CommandSpec::new(
let _ = self.exec.run(phoebus_executor::command::CommandSpec::new(
"finalize", "finalize",
"flush target", "flush target",
"sync", "sync",
)); ))?;
let _ = self.exec.umount_chroot();
storage::unmount_all( // 7. Unmount chroot and filesystems.
let umount_chroot_res = self.exec.umount_chroot();
let unmount_res = storage::unmount_all(
&self.exec, &self.exec,
&self.config, &self.config,
std::path::Path::new(&self.exec.root), std::path::Path::new(&self.exec.root),
)?; );
if self.config.is_encrypted() { if self.config.is_encrypted() {
if let Err(e) = encryption::luks_close(&self.exec, auth, &self.config) { if let Err(e) = encryption::luks_close(&self.exec, auth, &self.config) {
self.exec self.exec
@ -725,10 +767,119 @@ impl Installer {
.warn(format!("could not close LUKS device: {e}")); .warn(format!("could not close LUKS device: {e}"));
} }
} }
umount_chroot_res?;
unmount_res?;
self.exec.logger.info("installation finished"); self.exec.logger.info("installation finished");
Ok(()) Ok(())
} }
/// Check that required installed components and configuration for the selected profile exist.
pub fn verify_installed_system(&self) -> Result<()> {
if self.exec.dry_run {
self.exec.logger.info("[dry-run] verify_installed_system");
return Ok(());
}
self.exec
.logger
.info("verifying installed target integrity");
let target = self.exec.target();
// 1. sys CLI binary must be present in target root and executable
if !target.exists("usr/local/bin/sys") {
return Err(phoebus_executor::ExecError::operation(
"finalize",
"verify target",
"required runtime /usr/local/bin/sys is missing in target root",
));
}
// 2. Boot loader and kernel
let has_loader = target.exists("boot/loader/loader.conf")
|| target.exists("efi/loader/loader.conf")
|| target.exists("boot/grub/grub.cfg");
if !has_loader {
return Err(phoebus_executor::ExecError::operation(
"finalize",
"verify target",
"boot loader configuration (systemd-boot/grub) missing in target",
));
}
let root_p = std::path::Path::new(&self.exec.root);
let has_kernel = [root_p.join("boot"), root_p.join("efi")].iter().any(|dir| {
if let Ok(entries) = std::fs::read_dir(dir) {
entries.flatten().any(|e| {
let name = e.file_name().to_string_lossy().to_string();
name.starts_with("vmlinuz") || name.starts_with("kernel")
})
} else {
false
}
});
if !has_kernel {
return Err(phoebus_executor::ExecError::operation(
"finalize",
"verify target",
"no kernel image (vmlinuz/kernel) found in target /boot or /efi",
));
}
// 3. Desktop profile artifacts
if self.config.desktop.profile.is_desktop() {
match self.config.desktop.profile {
DesktopProfile::Mango => {
if !target.exists("usr/local/bin/phoebus-session-mango") {
return Err(phoebus_executor::ExecError::operation(
"finalize",
"verify target",
"session script /usr/local/bin/phoebus-session-mango missing",
));
}
if !target.exists("etc/xdg/mango/config.conf") {
return Err(phoebus_executor::ExecError::operation(
"finalize",
"verify target",
"Mango configuration /etc/xdg/mango/config.conf missing",
));
}
}
DesktopProfile::Dwl | DesktopProfile::Full => {
if !target.exists("usr/local/bin/phoebus-session") {
return Err(phoebus_executor::ExecError::operation(
"finalize",
"verify target",
"session script /usr/local/bin/phoebus-session missing",
));
}
}
_ => {}
}
if !target.exists("etc/greetd/config.toml") {
return Err(phoebus_executor::ExecError::operation(
"finalize",
"verify target",
"login configuration /etc/greetd/config.toml missing",
));
}
let passwd = target.read_to_string("etc/passwd").unwrap_or_default();
if !passwd.lines().any(|l| l.starts_with("greeter:")) {
return Err(phoebus_executor::ExecError::operation(
"finalize",
"verify target",
"greeter user account missing from target /etc/passwd",
));
}
}
self.exec
.logger
.info("target integrity verification passed");
Ok(())
}
/// A controlled, reversible re-check used by tests and by callers that want /// A controlled, reversible re-check used by tests and by callers that want
/// to gate a destructive action on the current disk identity. /// to gate a destructive action on the current disk identity.
pub fn current_disks(&self) -> Vec<phoebus_core::Disk> { pub fn current_disks(&self) -> Vec<phoebus_core::Disk> {

View file

@ -57,3 +57,121 @@ fn read_only_history_succeeds_against_a_temporary_root() {
"stdout: {stdout}" "stdout: {stdout}"
); );
} }
#[test]
fn version_is_reported() {
let out = sys().arg("--version").output().expect("run sys");
assert!(out.status.success());
assert!(String::from_utf8_lossy(&out.stdout).contains("sys"));
}
#[test]
fn appimage_and_custom_ebuild_inventories_are_safe_and_empty_on_a_fresh_root() {
let root = tempfile::tempdir().expect("temp root");
for args in [vec!["appimage", "list"], vec!["ebuilds"]] {
let out = sys()
.arg("--root")
.arg(root.path())
.args(&args)
.output()
.expect("run sys");
assert!(
out.status.success(),
"{args:?} stderr: {}",
String::from_utf8_lossy(&out.stderr)
);
let stdout = String::from_utf8_lossy(&out.stdout);
assert!(
stdout.contains("no managed AppImages")
|| stdout.contains("no Phoebus-managed custom ebuilds"),
"{args:?} stdout: {stdout}"
);
}
}
#[test]
fn invalid_snap_name_via_json_fails_closed() {
let out = sys()
.args(["--action", r#"{"action":"snap_install","name":"Bad Name"}"#])
.output()
.expect("run sys");
assert!(!out.status.success());
assert!(String::from_utf8_lossy(&out.stderr).contains("invalid"));
}
#[test]
fn invalid_appimage_hash_via_json_fails_closed() {
let out = sys()
.args([
"--action",
r#"{"action":"appimage_acquire","name":"x","url":"https://e/x","sha256":"00"}"#,
])
.output()
.expect("run sys");
assert!(!out.status.success());
assert!(String::from_utf8_lossy(&out.stderr).contains("SHA-256"));
}
#[test]
fn a_mutating_action_without_root_is_refused_before_any_command() {
// This runs as the test user (not root); the mutation must be refused.
if effective_uid_is_root() {
return;
}
let root = tempfile::tempdir().expect("temp root");
let out = sys()
.arg("--root")
.arg(root.path())
.args(["--action", r#"{"action":"snap_list"}"#])
.output()
.expect("run sys");
// snap_list is read-only, so it will instead fail because snapd is absent;
// the point is only that it never mutates. A mutating action is checked
// separately below.
let _ = out;
let mutating = sys()
.arg("--root")
.arg(root.path())
.args([
"--action",
r#"{"action":"set_package_preference","name":"firefox","backend":"flatpak"}"#,
])
.output()
.expect("run sys");
assert!(!mutating.status.success());
assert!(String::from_utf8_lossy(&mutating.stderr).contains("root"));
}
fn effective_uid_is_root() -> bool {
std::process::Command::new("id")
.arg("-u")
.output()
.ok()
.map(|o| String::from_utf8_lossy(&o.stdout).trim() == "0")
.unwrap_or(false)
}
#[test]
fn choose_never_invents_a_candidate() {
// Depending on the host, a lane may or may not be resolvable. Either way the
// output must be a real selection with rejected alternatives, or a clear
// fail-closed error — never a fabricated package.
let root = tempfile::tempdir().expect("temp root");
let out = sys()
.arg("--root")
.arg(root.path())
.args(["choose", "some-package"])
.output()
.expect("run sys");
let stdout = String::from_utf8_lossy(&out.stdout);
let stderr = String::from_utf8_lossy(&out.stderr);
if out.status.success() {
assert!(stdout.contains("Selected package:"), "stdout: {stdout}");
assert!(stdout.contains("source:"), "stdout: {stdout}");
} else {
assert!(
stderr.contains("no compatible") || stderr.contains("sys:"),
"stderr: {stderr}"
);
}
}

View file

@ -33,6 +33,12 @@ if ! curl -fsSL "$BASE/phoebus-installer" -o /tmp/phoebus-installer; then
echo "===FETCH-FAIL==="; poweroff -f; exit 1 echo "===FETCH-FAIL==="; poweroff -f; exit 1
fi fi
chmod 0755 /tmp/phoebus-installer chmod 0755 /tmp/phoebus-installer
# The deterministic `sys` CLI is a hard requirement of the installed system, so
# the installer locates it beside itself and installs it into the target.
if ! curl -fsSL "$BASE/sys" -o /tmp/sys; then
echo "===SYS-FETCH-FAIL==="; poweroff -f; exit 1
fi
chmod 0755 /tmp/sys
curl -fsSL "$BASE/$CONF" -o /tmp/test.conf curl -fsSL "$BASE/$CONF" -o /tmp/test.conf
echo "=== INSTALLER VERSION ===" echo "=== INSTALLER VERSION ==="

View file

@ -7,12 +7,19 @@
# controlled, reversible mutation, runs the real `sys undo` path and powers # controlled, reversible mutation, runs the real `sys undo` path and powers
# off. The host then boots the disk detached and verifies the restored state. # off. The host then boots the disk detached and verifies the restored state.
# #
# `sys` is fetched from the host (it is not installed into the target yet; see # `sys` is installed into the target by the installer; fall back to the host
# docs/HANDOFF.md), so this exercises the real command path, not a mock. # copy only if it is somehow absent (see docs/HANDOFF.md). This exercises the
# real installed command path, not a mock.
set -uo pipefail set -uo pipefail
SERVE="${SERVE_URL:-http://10.0.2.2:8000}" SERVE="${SERVE_URL:-http://10.0.2.2:8000}"
SYS="${SYS_BIN:-/tmp/sys}" if [[ -n "${SYS_BIN:-}" ]]; then
SYS="$SYS_BIN"
elif [[ -x /usr/local/bin/sys ]]; then
SYS=/usr/local/bin/sys
else
SYS=/tmp/sys
fi
USER_NAME="${USERNAME:-phoebus}" USER_NAME="${USERNAME:-phoebus}"
WORK=/tmp/phoebus-rollback WORK=/tmp/phoebus-rollback
mkdir -p "$WORK" mkdir -p "$WORK"

View file

@ -160,9 +160,13 @@ def _unlock_and_login(child, results, tag):
def _fetch_sys(child): def _fetch_sys(child):
# The installed system should already carry /usr/local/bin/sys; only fall
# back to fetching the host build when it is absent.
child.sendline( child.sendline(
f"curl -fsSL {SYS_URL} -o /tmp/sys && chmod 755 /tmp/sys " "if [ -x /usr/local/bin/sys ]; then SYS=/usr/local/bin/sys; "
"&& test -x /tmp/sys && echo SYS-OK-$(printf READY)" "elif [ -x /tmp/sys ]; then SYS=/tmp/sys; "
f"else curl -fsSL {SYS_URL} -o /tmp/sys && chmod 755 /tmp/sys && SYS=/tmp/sys; fi; "
"test -x \"$SYS\" && echo SYS-OK-$(printf READY)"
) )
child.expect("SYS-OK-READY", timeout=120) child.expect("SYS-OK-READY", timeout=120)
@ -276,7 +280,8 @@ def do_boot(results, paths, disks):
checks = os.environ.get( checks = os.environ.get(
"BOOT_CHECKS", "BOOT_CHECKS",
"echo ===CHECKS-$(printf START)===; " "echo ===CHECKS-$(printf START)===; "
"cat /proc/1/comm; systemctl is-system-running; " "echo COMM_CHECK:$(cat /proc/1/comm 2>&1); "
"echo SYSTEMD_STATUS:$(systemctl is-system-running 2>&1); "
"systemctl --failed --no-pager; ip -brief addr; " "systemctl --failed --no-pager; ip -brief addr; "
"lsblk -o NAME,SIZE,TYPE,FSTYPE,MOUNTPOINTS; echo ===CHECKS-$(printf END)===", "lsblk -o NAME,SIZE,TYPE,FSTYPE,MOUNTPOINTS; echo ===CHECKS-$(printf END)===",
) )
@ -302,8 +307,16 @@ def do_boot(results, paths, disks):
child.sendline(checks) child.sendline(checks)
child.expect("===CHECKS-END===", timeout=int(os.environ.get("CHECKS_TIMEOUT", "180"))) child.expect("===CHECKS-END===", timeout=int(os.environ.get("CHECKS_TIMEOUT", "180")))
serial = paths.serial_log.read_text(errors="replace") serial = paths.serial_log.read_text(errors="replace")
results.assert_true("boot-systemd-running", "running" in serial, checks_match = re.search(r"===CHECKS-START===(.*?)===CHECKS-END===", serial, re.DOTALL)
"systemd did not report running") checks_text = checks_match.group(1) if checks_match else serial
m = re.search(r"SYSTEMD_STATUS:([a-z\-]+)", checks_text)
status = m.group(1) if m else "unknown"
results.assert_true(
"boot-systemd-running",
status in ("running", "degraded"),
f"systemd did not report running/degraded (observed: {status})",
)
except pexpect.TIMEOUT as exc: except pexpect.TIMEOUT as exc:
results.fail("boot", f"timeout: {exc}") results.fail("boot", f"timeout: {exc}")
except pexpect.EOF: except pexpect.EOF:

View file

@ -0,0 +1,125 @@
#!/bin/bash
# Guest-side `sys` acceptance matrix for a booted, installed Phoebus system.
#
# Runs the deterministic phrase path and the typed JSON path, plus failure
# cases, and prints one machine-readable line per case. Read-only by default;
# set SYS_ACCEPTANCE_MUTATE=1 to also exercise install/remove/service/snapshot
# on a disposable VM only. Never run the mutate group on a physical host.
#
# The driver matches `===SYS-ACC-(START|END)===` and `CASE <id> <PASS|FAIL>`.
set -uo pipefail
SYS="${SYS_BIN:-/usr/local/bin/sys}"
[[ -x "$SYS" ]] || SYS=/tmp/sys
MUTATE="${SYS_ACCEPTANCE_MUTATE:-0}"
WORK="$(mktemp -d)"
trap 'rm -rf "$WORK"' EXIT
PASS=0
FAIL=0
report() {
# report <id> <PASS|FAIL> <detail>
printf 'CASE %s %s %s\n' "$1" "$2" "$3"
if [[ "$2" == PASS ]]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
}
# run_expect_zero <id> <args...>
run_expect_zero() {
local id="$1"; shift
if "$SYS" "$@" >"$WORK/$id.out" 2>"$WORK/$id.err"; then
report "$id" PASS "$(head -c 200 "$WORK/$id.out" | tr '\n' ' ')"
else
report "$id" FAIL "rc=$? stderr=$(head -c 200 "$WORK/$id.err" | tr '\n' ' ')"
fi
}
# run_expect_nonzero <id> <needle> <args...>
run_expect_nonzero() {
local id="$1" needle="$2"; shift 2
"$SYS" "$@" >"$WORK/$id.out" 2>"$WORK/$id.err"
local rc=$?
if [[ $rc -ne 0 ]] && grep -qi -- "$needle" "$WORK/$id.err" "$WORK/$id.out"; then
report "$id" PASS "rejected: $(head -c 160 "$WORK/$id.err" | tr '\n' ' ')"
else
report "$id" FAIL "rc=$rc expected nonzero and '$needle'"
fi
}
# json_nonzero <id> <needle> <json>
json_nonzero() {
local id="$1" needle="$2" json="$3"
"$SYS" --action "$json" >"$WORK/$id.out" 2>"$WORK/$id.err"
local rc=$?
if [[ $rc -ne 0 ]] && grep -qi -- "$needle" "$WORK/$id.err" "$WORK/$id.out"; then
report "$id" PASS "rejected: $(head -c 160 "$WORK/$id.err" | tr '\n' ' ')"
else
report "$id" FAIL "rc=$rc expected nonzero and '$needle'"
fi
}
echo "===SYS-ACC-START==="
echo "sys-acceptance: SYS=$SYS MUTATE=$MUTATE"
"$SYS" --version 2>&1 | head -1
# --- Read-only deterministic and JSON paths -------------------------------
run_expect_zero identity --version
run_expect_zero history history
run_expect_zero appimage-empty --root / appimage list
run_expect_zero ebuild-empty --root / ebuilds
# --- Failure cases ---------------------------------------------------------
run_expect_nonzero invalid-natural "could not parse" -- install --color=n
run_expect_nonzero unknown-phrase "unsupported instruction" frobnicate
json_nonzero unknown-action "invalid action" '{"action":"run_shell","command":"rm -rf /"}'
json_nonzero unknown-field "invalid action" '{"action":"history","x":1}'
json_nonzero option-operand "invalid action" '{"action":"install_package","atom":"-C"}'
json_nonzero bad-snap-name "invalid" '{"action":"snap_install","name":"Bad Name"}'
json_nonzero bad-appimage-hash "SHA-256" '{"action":"appimage_acquire","name":"x","url":"https://e/x","sha256":"00"}'
json_nonzero ebuild-traversal "invalid" '{"action":"custom_ebuild_prepare","atom":"../../x","version":"1","rationale":"r","ebuild":"EAPI=8"}'
# --- Offline / model-free behaviour ---------------------------------------
if [[ "$(id -u)" -ne 0 ]]; then
run_expect_nonzero nonroot-mutation "root" --action '{"action":"set_package_preference","name":"firefox","backend":"flatpak"}'
fi
# With no provider, `ask` must fall back deterministically and exit nonzero.
PHOEBUS_AI_PROVIDER= PHOEBUS_AI_BACKEND=direct \
run_expect_nonzero ask-offline "no AI provider" ask "install vim"
# --- Choosing a source (never invents a candidate) ------------------------
"$SYS" --root / choose unused-package-xyz >"$WORK/choose.out" 2>"$WORK/choose.err"
if grep -q "Selected package:" "$WORK/choose.out"; then
report choose PASS "selection: $(grep -m1 'Selected package:' "$WORK/choose.out")"
elif grep -qi "no compatible\|no AI provider" "$WORK/choose.err"; then
report choose PASS "no candidate: $(head -c 160 "$WORK/choose.err" | tr '\n' ' ')"
else
report choose FAIL "unexpected output: $(head -c 200 "$WORK/choose.err")"
fi
# --- Optional mutating group (disposable VM only) -------------------------
if [[ "$MUTATE" == "1" ]]; then
PKG="${SYS_ACCEPTANCE_PACKAGE:-app-misc/hello}"
if "$SYS" -y install "$PKG" >"$WORK/install.out" 2>&1; then
if emerge --pretend --quiet "$PKG" >/dev/null 2>&1; then
report mutate-install PASS "installed $PKG"
else
report mutate-install FAIL "install reported ok but system does not know $PKG"
fi
else
report mutate-install FAIL "sys install failed: $(head -c 160 "$WORK/install.out")"
fi
if "$SYS" -y remove "$PKG" >"$WORK/remove.out" 2>&1; then
report mutate-remove PASS "removed $PKG"
else
report mutate-remove FAIL "sys remove failed: $(head -c 160 "$WORK/remove.out")"
fi
"$SYS" history >"$WORK/hist.out" 2>&1
if grep -q "$PKG" "$WORK/hist.out"; then
report mutate-history PASS "transaction recorded"
else
report mutate-history FAIL "install/removal missing from history"
fi
fi
echo "===SYS-ACC-END=== SUMMARY PASS=$PASS FAIL=$FAIL"
[[ "$FAIL" -eq 0 ]]