phoebus_os/docs/adr/0014-privileged-approval-ledger.md
2026-09-24 19:14:16 -07:00

4.8 KiB

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 <id> --plan-uid <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: <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.

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.