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:
- 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. - 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 actionset_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, whichsudorewrites), 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;pkexecstrips 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
pkexecto 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/phoebusand/var/lib/phoebusgroup-writable. Rejected: it weakens system policy ownership to fix a personal-settings problem.