phoebus_os/docs/adr/0014-privileged-approval-ledger.md
2026-09-24 20:43:33 -07:00

8.7 KiB

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, the reviewed aggregate effects and every per-step effect execution trusts (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.

Execution trusts step_effects, so those are bound too: each stored per-step effect digest is recomputed from its contents and must match, the aggregate must be exactly the concatenation of the steps, and the canonical digest covers every step. 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 binds Install, LegacyInstall, Removal, General and Undo alike; retaining an approved digest while swapping an action or a step's effects and resealing is rejected before any command runs or approval is consumed. The earlier-approved-step allowance used during execution is unchanged.

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/<pid>/stat start time and the kernel boot id). The terminal status is published exactly once by atomically hard-linking a fully written record into <key>.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: <home>/.config/phoebus/package-preferences.toml (0600 in 0700), written unprivileged by the invoking account.
  • Proactive snooze/dismiss state: <home>/.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.