# ADR 0014: Privileged approval ledger and user-owned personal settings - **Status:** Accepted - **Date:** 2026-09-25 ## Context Two administration defects remained after the shared-service hardening in commit `3b84b8c`: 1. **Approval was bound to a user-controlled plan file.** The privileged broker (`sys --broker --execute-plan --plan-uid `) loaded the plan from the reviewing user's directory and re-derived a self-consistency seal from the plan's own contents. Because the seal is recomputable, a replacement plan under the same identifier passed. The consumption marker also lived in the same user-writable directory, so deleting it allowed a replay. 2. **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/`, which a normal account cannot write. A self-consistent checksum is not proof of human approval, and user-writable files cannot anchor consumption. ## Decision ### Approval is anchored in a broker-controlled ledger A root-owned approval ledger (`/var/lib/phoebus/approvals`, 0700; records 0600) records every approval the broker consumes. It is keyed by the plan's integrity seal — a fingerprint over the exact actions, per-step effects, candidate, target root, initiating uid and expiry — and is created 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); - a replacement plan under the same identifier has a different fingerprint and is refused before the ledger is touched. The plan 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. A plan left `in_progress` by a crash is reconciled to `interrupted` at broker startup, and a retry never repeats a consumed mutation. The user-owned claim marker remains as an optimistic early guard but is no longer the security anchor. ### 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. 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 an independently preserved approval and a root-owned consumption record; the plan file is untrusted input. - 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 caller-supplied digest alone.** Rejected: a checksum is not proof of human approval; a root-owned consumption record is required for replay resistance. - **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.