243 lines
16 KiB
Markdown
243 lines
16 KiB
Markdown
# Architecture
|
|
|
|
Phoebus ships one installer implementation: the **Rust** workspace in
|
|
`installer-rs/`. It reproduces the proven encrypted UEFI VM boot path and is the
|
|
only implementation on the install path. The retired Bash prototype is kept in
|
|
git history, tagged `v0.1.0-bash-reference`; see `docs/BASH-MIGRATION.md` for
|
|
the evidence-gated retirement.
|
|
|
|
The disposable VM harness lives in `installer/tests/vm/` and drives the static
|
|
Rust binary.
|
|
|
|
## Layering
|
|
|
|
```
|
|
Desktop assistant GUI Quickshell/QML (installed; typed JSON-RPC protocol)
|
|
| phoebus-assistant
|
|
+-------------------+
|
|
|
|
|
Graphical welcome + installer Quickshell/QML (live only; typed JSON protocol)
|
|
| phoebus-welcome, phoebus-install
|
|
v v
|
|
TUI / CLI / sys front-ends (phoebus-tui, phoebus-installer)
|
|
|
|
|
v
|
|
Orchestration + plan staged execution, single source of truth
|
|
|
|
|
v
|
|
Executor commands, storage, Portage, boot, services
|
|
|
|
|
v
|
|
Core typed config, models, policy, validation
|
|
```
|
|
|
|
The graphical frontend is one of several front-ends; it never contains
|
|
installation or administrative logic:
|
|
- `phoebus-installer --gui-bridge` speaks newline-delimited JSON on stdin/stdout,
|
|
reuses the same `Installer`, plan, validation and `DestructiveAuthorization` flow,
|
|
and reports real stages through `Installer::install_observed`.
|
|
- `sys --assistant-bridge` speaks newline-delimited JSON-RPC on stdin/stdout,
|
|
providing a uniform interface for the desktop assistant (`phoebus-assistant`)
|
|
for conversational interaction, legacy actions, unified updates, proactive alerts,
|
|
and user preferences (ADR 0010, ADR 0013).
|
|
|
|
### phoebus-core
|
|
|
|
Pure, non-privileged logic with no external commands except reading `/proc`,
|
|
`/sys` and small system files:
|
|
|
|
- `config` — `InstallConfig` (nested sections, enums for closed sets); TOML and
|
|
legacy flat-format loading (format is detected structurally).
|
|
- `validate` — hostname/username/locale/timezone/keymap/password checks.
|
|
- `disk` / `hardware` — models and protection classification (pure).
|
|
- `plan` — `InstallPlan` with the canonical step order and human rendering.
|
|
- `policy` — deterministic source/binary decisions + policy context.
|
|
- `emergelog` — parses Portage `emerge.log` into measured compile times.
|
|
- `target` — `TargetRoot`, which rejects absolute paths and `..` traversal.
|
|
- `secret` — `SecretString` (redacted `Debug`, zeroized on drop) + `Redactor`.
|
|
- `snapshot` — deterministic snapshot names + TOML transaction history.
|
|
- `boot` — BLS entry parse/render and root-subvolume selection for rollback.
|
|
- `rollback` — rollback state machine, retention and mount/fstab planners.
|
|
- `effects` — parse `emerge --pretend` into resolved effects + plan digest.
|
|
- `transaction` — the user-queryable log of executed actions and outcomes.
|
|
- `action` — closed `SystemAction` schema, conversational parsing, and options.
|
|
- `selection` — hardware-aware source scoring, preference profiles (`Balanced`,
|
|
`FastInstallation`, `NativeIntegration`, `ApplicationIsolation`), project
|
|
tool environments, and candidate selection.
|
|
- `update` — unified multi-source update models across all supported package lanes.
|
|
- `fastinstall` — fast default installation with user-controlled source
|
|
builds: the prebuilt delivery set and its review rendering
|
|
(`fast_default_deliveries`, `delivery_summary`), the supported
|
|
"build from source" table (`SOURCE_CONVERSIONS`, Brave excluded with
|
|
`brave_source_status`), the opt-in tuned-kernel plan, the
|
|
preference-neutrality guard (`assert_no_installer_preference`), the
|
|
fail-closed binary check (`require_binary_capable`), and the measured
|
|
installation figures (`InstallMetrics`).
|
|
- `proactive` — quiet proactive alert models, categories, and deferred schedules.
|
|
- `brand` — the visual identity (palette tokens, sun emblem, wordmark,
|
|
wallpaper) as deterministic SVG/tokens shared by the QML frontend.
|
|
|
|
### phoebus-executor
|
|
|
|
The only crate that runs privileged commands.
|
|
|
|
- `command` — `CommandSpec`, `ProcessRunner` (real / recording / never) with
|
|
arguments always separate; there is no `sh -c`.
|
|
- `exec` — `Exec` centralises logging, redaction, dry-run, chroot mounts and
|
|
target writes.
|
|
- `log` — file + optional stderr logging; every line is redacted.
|
|
- `auth` — `DestructiveAuthorization`, issued only after ERASE + final
|
|
confirmation.
|
|
- `storage`, `encryption`, `portage`, `kernel`, `boot`, `users`, `services`,
|
|
`desktop` — the install backend, mirroring the proven order.
|
|
- `probe` — read-only hardware and disk discovery.
|
|
- `snapshot`, `update`, `admin`, `actions` — post-install foundations.
|
|
- `proactive` — quiet proactive monitors for storage, services, transactions, and reboots. Alert snooze/dismiss state is user-owned (0600/0700, bounded).
|
|
- `personal` — per-user storage resolution (`UserStorage`) and initiating-user resolution across `sudo`/`pkexec` (`PHOEBUS_UID` → `SUDO_UID` → `PKEXEC_UID` → effective uid; home from `/etc/passwd`). Personal preferences and alert state never touch `/etc` or `/var/lib`.
|
|
- `rollback` — coordinated root/`var`/fstab/BLS rollback (ADR 0007).
|
|
- `nix` — pinned Nix bootstrap, attribute evaluation probe, sandboxed build config, and lifecycle.
|
|
- `sandbox` — the hardened `systemd-run` boundary for model execution.
|
|
- `transaction` — persists the transaction log into the target.
|
|
|
|
### phoebus-ai
|
|
|
|
- Typed `AiProposal` / `SystemAction` (unknown actions fail closed; no shell).
|
|
- `assistant` — the installed conversational plan schema (`AssistantPlan`) and
|
|
its fail-closed parser; the model proposes the same actions `sys` executes.
|
|
- `privacy` — `PrivacyPolicy` + `ContextBundle`; forbidden-path checks. The
|
|
collector in `phoebus-executor::admin` only reads system sources.
|
|
|
|
### phoebus-installer
|
|
|
|
- `orchestrate` — `Installer` runs the plan stages and stops on first failure.
|
|
- `service` — shared administration service layer (`PreparedPlan`, `PlanStore`, planning, authorization, Polkit elevation, execution, and verification) shared identically by CLI and GUI. The single authoritative validation boundary (`validate_prepared_plan`) runs before elevation and is repeated in the broker after authentication; plans bind actions, effects, candidate, target root and initiating uid, are stored per-user with an integrity seal, and are atomically claimed before execution. Execution carries the *reviewed* per-step effects forward and compares freshly resolved effects against them (only changes explained by an earlier approved step are allowed), so a material change aborts with a terminal `stale plan` outcome and every started transaction reaches a terminal result.
|
|
- `approval` — broker-controlled approval ledger (`/var/lib/phoebus/approvals`, 0700/0600, ADR 0014). Records are keyed by a stable approval identity (plan id, canonical approval digest, initiating uid, target root), so at most one execution may run, replay is refused even after the user deletes every file in their own plan directory, a presentation-only edit cannot mint a fresh record, and a replacement under the same identifier is refused before the ledger is touched. Claims carry the owning process identity; terminal statuses are published atomically once and are immutable, and recovery only marks an owner that is provably gone. The approving digest travels across authentication independently of the plan file (`--approval-digest`) and is compared to a canonical digest the broker recomputes from the executable actions and reviewed effects; the initiating identity is derived from `PKEXEC_UID`.
|
|
- `ai_setup` — one provider/endpoint/model/credential resolver shared by the CLI and the desktop bridge, so their provider setup cannot diverge. Credentials load from a 0600 file (configured path, `PHOEBUS_AI_API_KEY_FILE`, or `~/.config/phoebus/ai.key`) and never travel through QML, prompts or argv.
|
|
- `conversation` — bounded, minimized conversation history and contextual follow-up resolution (tradeoff comparisons, backend switching, and plan confirmation). Raw requests are not persisted; registered secrets are redacted; history is 0600/0700, atomic, bounded and clearable.
|
|
- `assistant_bridge` — JSON-RPC stdio bridge serving the Quickshell desktop assistant. Every plan type returns the same `plan_id`/`digest` review card; `execute` runs only the referenced reviewed plan.
|
|
- `release` — `ReleaseManifest` create/verify, candidate gates, atomic publish
|
|
and signing command helpers.
|
|
- Binaries: `phoebus-installer`, `sys`, `phoebus-release`.
|
|
|
|
## Safety model and package correctness
|
|
|
|
- Every command goes through `Exec`, which logs a redacted command line, exit
|
|
status and duration, and honours dry-run centrally.
|
|
- Destructive functions take `&DestructiveAuthorization`; the token is created
|
|
only after the destructive preview and confirmations.
|
|
- All target writes go through `TargetRoot`; host-versus-target mistakes are
|
|
caught by construction and covered by tests.
|
|
- Secrets travel over stdin only and are registered with the redactor before
|
|
any logging. They never enter the config.
|
|
- The AI cannot execute; it can only propose typed changes that the backend
|
|
validates and the user approves. The assistant's model call additionally runs
|
|
inside an unprivileged, hardened `systemd-run` unit (`sandbox`), so the
|
|
boundary is enforced by the OS and not only by the schema.
|
|
- Approval is bound to the reviewed resolved plan: the reviewed per-step effects
|
|
are carried into execution, package effects are resolved again only as
|
|
evidence to compare against them, and a material change aborts. Privileged
|
|
consumption is anchored in a root-owned ledger (ADR 0014), so a user-editable
|
|
plan file cannot be replaced or replayed.
|
|
- Personal preferences and alert state are user-owned (0600/0700); system-wide
|
|
policy is root-owned and changed only through the authenticated typed action
|
|
`set_package_preference { system_wide: true }`.
|
|
- **Portage binary vs source verification**: Binary package recommendations are
|
|
verified with `emerge --pretend --usepkgonly`. If a package would compile from
|
|
source (`EffectSource::Source`), execution halts closed and demands a revised
|
|
review and approval.
|
|
- **Nix attribute verification**: Nix packages undergo evaluation probes against
|
|
`<nixpkgs>` before inclusion in recommendations or execution.
|
|
- **Cross-source ownership and data preservation**: Installed applications are
|
|
tracked across Portage, Flatpak, Snap, and AppImage. Removal preserves user
|
|
data by default.
|
|
- **Audited broker entry points**: JSON action calls (`--action`/`--action-file`)
|
|
fail closed unless passed `--legacy` or `--broker`.
|
|
|
|
## Rollback and recovery
|
|
|
|
A recovery point is a snapshot set: `@` and the separate `@var` (Portage state)
|
|
together; `/home` is excluded. Rollback creates a writable root generation,
|
|
rewrites `subvol=` in both the restored root's fstab and the BLS entry options
|
|
(the explicit argument overrides the Btrfs default), selects a kernel entry
|
|
whose modules match the restored root, and writes previous/recovery entries.
|
|
See ADR 0007.
|
|
|
|
## Desktop environment: Mango + DarkMaterial
|
|
|
|
Phoebus OS has one desktop experience only: **Mango + DarkMaterial** (`desktop.profile = "mango"`).
|
|
|
|
- **Mango + DankMaterialShell**: `gui-wm/mangowm` (a wlroots-based tiling compositor) plus the DMS shell (panel, launcher, notifications, lock, idle, audio/network/Bluetooth/display controls) from the GURU overlay.
|
|
- **Entry points**: Session entry point `/usr/local/bin/phoebus-session-mango` (with convenience wrapper `/usr/local/bin/phoebus-session`), session file `/usr/share/wayland-sessions/phoebus-mango.desktop`.
|
|
- **Display Manager**: `greetd` with `tuigreet` configured to launch the canonical session upon authentication.
|
|
- **Headless**: Systems requiring no graphical desktop can set `desktop.profile = "none"`.
|
|
|
|
`desktop.profile` selects both the Gentoo desktop/systemd profile and the package set; the plan displays the canonical desktop session before installation.
|
|
|
|
## Installation order (do not regress)
|
|
|
|
```
|
|
storage_prepare -> stage_install -> fstab_generate -> portage_configure
|
|
-> packages_base -> kernel_install -> boot_install -> users_configure
|
|
-> services_configure -> desktop_install -> finalize
|
|
```
|
|
|
|
Storage order: partition GPT, create ESP, LUKS format/open, `mkfs.btrfs`, mount
|
|
top-level, create subvolumes, unmount, mount the subvolume layout. `fstab` and
|
|
`crypttab` are generated **after** stage3 extraction (stage3 ships its own
|
|
`/etc/fstab`).
|
|
|
|
## Configuration and plan
|
|
|
|
`InstallConfig` is canonical data; the plan and all rendering derive from it.
|
|
The same plan drives the review screen, the destructive preview, dry-run and
|
|
the actual execution, so the UI cannot diverge from the backend.
|
|
|
|
## Post-install foundations
|
|
|
|
- **Snapshots**: read-only Btrfs snapshots under `/.snapshots`, recorded in a
|
|
TOML history. A snapshot set captures `@` and the separate `@var`; `/home` is
|
|
intentionally not snapshotted so user documents survive a rollback.
|
|
- **Rollback**: `sys undo` restores a committed snapshot as the next boot root
|
|
with coordinated fstab, BLS and kernel selection (ADR 0007); a persisted state
|
|
file makes an interrupted rollback resumable.
|
|
- **Background updates**: `emerge --fetchonly` then `--buildpkgonly` stage
|
|
distfiles and reusable local binary packages without installing; activation
|
|
stays explicit.
|
|
- **Kernel/boot**: `sys-kernel/gentoo-kernel-bin` (safe) or `gentoo-kernel`
|
|
(optimized), dracut initramfs, systemd-boot BLS entries, plus a snapshot-based
|
|
recovery entry that does not depend on the live root.
|
|
|
|
## Desktop assistant and administration architecture
|
|
|
|
The desktop assistant (`phoebus-assistant`) is an installed Quickshell GUI
|
|
application launched from the desktop menu, keybinding, or launcher:
|
|
|
|
- **Shared execution core**: The GUI contains no business logic. It communicates
|
|
via stdio JSON-RPC over `sys --assistant-bridge`.
|
|
- **Recommendation cards and options**: Recommends package sources with clear rationale
|
|
(e.g., "Install Firefox from Flathub. Recommended because it avoids a lengthy build
|
|
and provides application isolation"), expandable candidate comparisons, and
|
|
single-approval execution bound to the plan digest.
|
|
- **Unified multi-source updates**: Queries and displays available updates across
|
|
Portage, Flatpak, Snap, AppImage, and Nix, with reboot-required notifications.
|
|
- **Quiet proactive monitoring**: Periodically evaluates bounded deterministic health
|
|
checks (service failures, disk usage under 5 GiB, failed transactions, pending
|
|
updates), supporting deduplication, snooze, and user toggle.
|
|
- **User preferences and profiles**: Exposes inspectable preference profiles
|
|
(`Balanced`, `FastInstallation`, `NativeIntegration`, `ApplicationIsolation`),
|
|
per-project tool version mappings, and source pins.
|
|
- **Deterministic legacy panel**: Structured GUI fallback controls executing
|
|
deterministic `--legacy` commands directly through the bridge.
|
|
|
|
## Extension points
|
|
|
|
- `ProcessRunner` — swap the real runner for a recording/never runner in tests,
|
|
or for a different execution backend.
|
|
- `InstallStep` — add stages in `plan.rs` and handle them in `orchestrate.rs`.
|
|
- `SystemAction` — add closed verbs; the policy engine classifies and previews
|
|
them, and the broker executes them after approval. Recent verbs:
|
|
`ConvertToSource { app }` (reviewed rebuild of a fast-default app from
|
|
its maintained source; builds before removing; Brave refused with its
|
|
reason) and `BuildTunedKernel { make_default }` (separate BLS entry,
|
|
fallback kept, default only after a test boot).
|
|
|