# ADR 0014: Privileged approval ledger and user-owned personal settings - **Status:** Accepted - **Date:** 2026-09-25 ## Context Several administration defects remained after the shared-service hardening in commits `3b84b8c` and `0be3010`: 1. **The privileged boundary did not recompute the canonical digest.** For General, Undo and Removal plans it compared the independently supplied digest with the `digest` field stored in the (user-owned) plan file, without re-deriving it from the executable actions and reviewed effects. A plan could therefore retain its previously approved digest, swap an action and its effects, recompute the self-consistency seal, and pass. 2. **Replay protection was keyed by an editable seal.** The ledger keyed records by the plan's integrity seal, which includes presentation fields. Editing the summary and resealing produced a new key for the same approved digest, so the action could run twice. 3. **Crash reconciliation could mislabel a live operation.** `reconcile_interrupted` marked every `in_progress` record interrupted whenever another broker started, and could race a real `finish`. 4. **Personal settings could become root-owned.** `UserStorage::write_private` created directories and files with the process's effective uid, so a `sudo` invocation wrote root-owned files into the user's home. 5. **Personal settings wrote to protected system paths.** The desktop bridge ran unprivileged but wrote package preferences under `/etc/phoebus/` and proactive snooze/dismiss state under `/var/lib/phoebus/`. A self-consistent checksum is not proof of human approval, and user-writable files cannot anchor consumption. A presentation-only edit must not be able to mint a new approval. ## Decision ### The broker recomputes the canonical digest for every plan kind The privileged boundary independently derives the canonical approval digest from the exact executable `actions`, the `candidate` and the reviewed material `effects` (`compute_plan_digest`, the same function the planner used). It must equal both the plan's stored digest and the independently supplied `--approval-digest`. The integrity seal stored beside the plan is a self-consistency check the owner can recompute, so it is never treated as authentication. This binds Install, LegacyInstall, Removal, General and Undo plans alike; retaining an approved digest while swapping an action and resealing is rejected before any command runs or approval is consumed. ### Consumption is anchored by a stable approval identity A root-owned approval ledger (`/var/lib/phoebus/approvals`, 0700; records 0600) records every approval the broker consumes. A record is keyed by `approval_key(plan_id, canonical_digest, initiator_uid, canonical_target_root)` and published with `O_EXCL` so: - at most one execution may run under concurrent submissions; - replay is refused even when the user deletes or recreates every file in their own plan directory (the root-owned record remains); - editing presentation fields (summary, recommendation, rationale, verification) and resealing cannot mint a fresh entry for an already-consumed approval; - a replacement plan under the same identifier has a different digest and is refused before the ledger is touched; - a newly reviewed identical operation has a new random plan ID and is allowed. The digest shown on the review card is carried across authentication independently of the plan file (`--approval-digest`) and compared in the broker. The broker derives the initiating identity from the authenticated caller context (`PKEXEC_UID`), not from the untrusted `--plan-uid` alone. The user-owned claim marker remains as an optimistic early guard but is not the security anchor. ### Terminal transitions are atomic, durable and monotonic Each claim records the owning process identity (`pid`, `/proc//stat` start time and the kernel boot id). The terminal status is published exactly once by atomically hard-linking a fully written record into `.terminal`; the link fails if a terminal already exists, so a terminal status can never be overwritten or changed to another terminal status. Recovery only marks a record interrupted when its owner is provably gone (the pid is absent, the pid was reused, or the machine rebooted), so a live executor — including a second broker starting concurrently with a live operation — is never mistaken for a crashed one. ### Personal state is user-owned; system policy is privileged - Personal package preferences: `/.config/phoebus/package-preferences.toml` (0600 in 0700), written unprivileged by the invoking account. - Proactive snooze/dismiss state: `/.local/state/phoebus/proactive-state.toml` (0600 in 0700), bounded. - System defaults remain `/etc/phoebus/package-preferences.toml`, root-owned, changed only through the authenticated typed action `set_package_preference { system_wide: true }`. - The initiating user is resolved through `PHOEBUS_UID` → `SUDO_UID` → `PKEXEC_UID` → the effective uid, and the home directory from `/etc/passwd` (never `$HOME`, which `sudo` rewrites), so the CLI and GUI resolve the same user's preferences. - Ownership: directories and files are created component by component beneath the resolved home, rejecting symlinks and non-directories. When the write runs elevated (effective root on behalf of a non-root user), the created paths are chowned to the *initiating* user's uid/gid so the setting stays readable and replaceable by them; `sys` refuses to write user data as a non-root process acting for a different user. No path outside the resolved home is ever chowned. Precedence: personal explicit choices win; system defaults apply to anything the user has not overridden. A failed write is reported as a failure; the GUI never reports "saved" or "dismissed" when persistence failed. ### Reviewed effects are carried through execution Execution carries the reviewed per-step effects forward and treats freshly resolved effects as evidence to compare against the approval, never as a replacement approval. A material change aborts with a terminal `stale plan` transaction outcome. Only changes explained by an earlier approved step in the same plan are accepted. ## Consequences - Privileged execution is bound to a canonical digest recomputed at the boundary and to a root-owned consumption record; the plan file is untrusted input, and a substituted-but-resealed plan is rejected before mutation. - A presentation-only edit cannot produce a fresh approval record, while a newly reviewed identical operation with a new plan ID is allowed. - A crashed operation is recovered without ever mislabelling a live one, and a terminal status is immutable. - A normal desktop account can save personal preferences and dismiss alerts without elevation; system-wide policy stays authenticated. - Every started transaction reaches a terminal result (`ok`, `failed`, `stale plan`, `verify failed`, `interrupted`); completed steps and protective snapshots are retained. - The ledger env override (`PHOEBUS_APPROVALS_DIR`) and the plan-store override (`PHOEBUS_PLANS_DIR`) are test/relocation affordances; `pkexec` strips them from the broker environment, so they are not user-controllable on the privileged path. ## Alternatives considered - **Trust the plan's stored digest or integrity seal.** Rejected: the owner can recompute any unkeyed hash in a file they control; the canonical digest must be re-derived from the executable actions and effects, and compared to an independently supplied approval. - **Key the ledger by the integrity seal.** Rejected: it includes presentation fields, so a summary edit mints a new key and defeats replay protection. - **Reconcile every `in_progress` record at startup.** Rejected: it mislabels live concurrent operations and races a real finish. Owner liveness plus an atomic, monotonic terminal publication is required. - **A second `pkexec` to register the approval at review time.** Rejected as unnecessary: the digest carried across authentication plus the root-owned ledger satisfies the properties without a second prompt. - **Make `/etc/phoebus` and `/var/lib/phoebus` group-writable.** Rejected: it weakens system policy ownership to fix a personal-settings problem.