phoebus_os/docs/HANDOFF.md
2026-09-24 22:24:13 -07:00

10 KiB

Handoff

Rolling note between work sessions. Update this file before you finish, then commit it. It should be short and current; use git log for detail.

  • Last updated: this session (2026-09-25), adversarial hardening of the privileged approval boundary: (1) the broker recomputes the canonical approval digest for every plan kind, (2) the ledger uses a stable approval identity instead of the editable integrity seal, (3) crash recovery is live-safe and terminal transitions are atomic/monotonic, and (4) personal writes are owned by the initiating user. See ADR 0014. Supersedes the 0be3010 approval design; that commit's UX/docs changes are preserved.
  • Current focus:
    1. Canonical digest at the privileged boundary (service::validate_prepared_plan):
      • Independently re-derives compute_plan_digest(actions, candidate, effects, step_effects) and requires it to equal both plan.digest and the supplied --approval-digest. Covers Install, LegacyInstall, Removal, General and Undo. The stored integrity seal is only a self-consistency check and is never treated as authentication.
      • Per-step effect binding: execution trusts step_effects, so the canonical digest now hashes every step (contents recomputed, not read from the stored digest); each stored step digest must match its contents, and the aggregate must be the concatenation of the steps. A multi-action plan without per-step effects is refused. Install/LegacyInstall keep the install-specific digest with the single step required to equal the aggregate. This closes the "retain the approved digest, change only step_effects, recompute the seal" gap; rejected before any command runs or approval is consumed. The earlier-step allowance in approval_holds is unchanged.
    2. Stable approval identity (phoebus_installer::approval, ADR 0014):
      • Ledger + .claim key = approval_key(plan_id, canonical_digest, initiator_uid, target_root). Presentation fields (summary, rationale, verification) are excluded, so editing them and resealing cannot mint a fresh record for a consumed approval; a newly reviewed identical operation with a new plan id is allowed.
      • Claims record the owning process (pid, /proc/<pid>/stat start ticks, boot id). Terminal status is published once via an atomic hard link into <key>.terminal and is immutable. reconcile_interrupted only marks a record interrupted when the owner is provably gone, so a live operation (or a second broker starting concurrently) is never mislabelled, and it cannot race a real finish.
    3. Personal write ownership (phoebus_executor::personal):
      • write_private creates the config/state path one component at a time under the resolved home, rejecting symlinks and non-directories.
      • Elevated writes (effective root on behalf of a non-root user) chown the created paths to the initiating user's uid/gid (via a standard-library chown behind an injectable OwnerFixer). A non-root process acting for a different user is refused. Proactive state now routes through the same path.
    4. Reviewed effects + terminal transactions (service::execute_prepared, unchanged this session): reviewed per-step effects are carried forward and freshly resolved effects are evidence compared with phoebus_core::effects::approval_holds; every path after transaction::begin reaches a terminal result.
  • Last verified (this session):
    • cargo fmt --all -- --check clean.
    • cargo test --workspace: 602 passed, 0 failed. New per-step binding adversarial tests: single-action and multi-action General plans with step_effects swapped (with and without a matching aggregate) while the approved digest is retained are rejected before any command, ledger claim or transaction; a legitimate bound multi-step plan still validates. New CLI regression: a personal preference succeeds when the system transaction directory is read-only. The prior session's adversarial tests all still pass.
    • cargo clippy --workspace --all-targets exits 0 (only the pre-existing result_large_err, one arg-count and one DiskPhase lints remain).
    • cargo build --release -p phoebus-installer clean.
    • Disposable installed VM, clean install (verify-disk2.qcow2, qcow2, detached boot): the fixed installer completes with ===INSTALL-RC=0===, installation finished, stage complete: finalize, and NO_SECRET_LEAK. Detached boot: LUKS unlock + login; PID 1 systemd, systemd is-system-running = running; sys 0.1.0; sys history --legacy exit 0; installer/tests/vm/sys-acceptance.sh with the fixed sys reports SUMMARY PASS=24 FAIL=0, including personal-preference PASS saved to user config and nonroot-systemwide correctly refused.
    • Two defects found and fixed by the VM runs: (a) the installer finalize sys probe ran the AI-first sys history and aborted a --no-ai install with INSTALL-RC=1; it now runs sys history --legacy (phoebus-executor::sys_runtime, unit-tested) and the clean install completed; (b) a personal preference wrote the preference but then failed recording it in the root-owned /var/lib/phoebus/transactions.toml; personal preferences are now excluded from the system transaction history (CLI regression with a read-only transaction directory).
  • Not yet verified (BLOCKED):
    • The privileged sys --broker --execute-plan path and replay rejection were not exercised end-to-end in the VM: the serial console has no root access and no Polkit agent (sudo -n denied), so pkexec elevation cannot complete. These paths remain unit-tested at the execute_plan_privileged entry point (replacement, recomputed digest, step_effects tampering, replay, concurrency, interruption). A graphical/seat-providing VM or a passwordless-sudo test image is required for the end-to-end run.
    • The pre-existing test-disk.qcow2 still cannot be unlocked (unknown passphrase); do not guess or brute-force.
    • No AI provider credential is present; do not invent one.
    • A real privileged chown (running as root) could not be exercised on this unprivileged host; verified through the injectable fixer seam and the cross-uid refusal test.
  • Public repo: https://git.phoebus.club/phoebus/phoebus_os (remote origin, SSH port 2222).

Next actions (in order)

  1. Privileged --broker acceptance in a seat-providing VM. The read-only acceptance and personal preferences are verified on the clean install (verify-disk2.qcow2, 24/24). The remaining unverified path is the actual pkexec elevation into sys --broker --execute-plan (replacement during authentication, replay after deleting user plan state, cancellation, a real privileged chown). It needs a graphical Polkit agent or a passwordless-sudo disposable test image; the serial console cannot elevate.
  2. Installed sys acceptance on the booted disk:
    # serve the static sys first:
    cp installer-rs/target/x86_64-unknown-linux-gnu/release/sys /home/dominic/vmlab/serve/
    env DISK=/var/tmp/phoebus-vm/disks/<clone>.qcow2 \
      OVMF_CODE=/usr/share/OVMF/OVMF_CODE_4M.fd \
      OVMF_VARS=/var/tmp/phoebus-vm/OVMF_VARS.fd \
      BOOT_CHECKS='... curl .../sys ...; SYS_BIN=/tmp/sys bash .../sys-acceptance.sh ...' \
      python3 installer/tests/vm/serial-driver.py boot
    
    The new broker behaviour (replacement during authentication, replay after deleting user plan state, cancellation) is already covered by phoebus-installer unit tests; the installed run confirms the sealed elevation path and the personal-preference acceptance case.
  3. AI-selected install journey (needs an authorised provider): boot the installed disk, serve the built sys and a 0600 key file, then:
    sudo sys --ai-provider deepseek --ai-api-key-file /run/phoebus/ai.key \
      install <application>
    # and the no-model control in the same run:
    PHOEBUS_AI_PROVIDER= sudo sys install <application>
    
    Confirm the model requests evidence, the resolver confirms the candidate, the plan is presented before approval, and the transaction is recorded. No credential is available here; do not invent one.
  4. Rollback VM acceptance (serial-driver.py rollback) on a cloned disposable image of the installed system.
  5. NVIDIA hardware acceptance (BLOCKED): needs an NVIDIA GPU.
  6. Interactive graphical user session login into Mango / DankMaterialShell under a physical seat or nested Wayland compositor.

Known blockers / risks

  • A full VM install still takes hours (base stage ~116 min). Use the already installed disposable disk (clone it) for sys install journeys rather than a fresh install.
  • No NVIDIA GPU (and no authorised passthrough).
  • Snap needs network and AppArmor for meaningful confinement; the lane detects confinement honestly.
  • AppImage provides no sandbox; do not describe it as one.
  • Custom ebuilds remain separately reviewed, untrusted artifacts; the install workflow never builds one during investigation.
  • OpenCode transport concatenates messages, so multi-turn investigation is best-effort there; the direct providers carry the full conversation.
  • Harness artifacts live under /var/tmp/phoebus-vm/ (outside git).

Environment notes

  • Dev host: Ubuntu 26.04. QEMU/OVMF/xorriso/rustfmt/clippy/ImageMagick/visudo present. flatpak and snap clients are present on the host (not proof of the VM lanes).
  • VM harnesses: installer/tests/vm/{gui-driver,serial-driver,appliance-driver,live-driver}.py and sys-acceptance.sh. DISK must be a disposable qcow2; never /dev/*.
  • 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).
  • The static binaries for the VM: make static builds phoebus-installer and sys under installer-rs/target/x86_64-unknown-linux-gnu/release/.

Definition of a good stopping point

  • make test passes; docs/STATUS.md and docs/CHANGELOG.md updated; docs/HANDOFF.md updated; committed (via scripts/agent-commit.sh) and pushed (scripts/publish.sh).