8.2 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:
- The privileged boundary did not recompute the canonical digest. For
General, Undo and Removal plans it compared the independently supplied digest
with the
digestfield 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. - 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.
- Crash reconciliation could mislabel a live operation.
reconcile_interruptedmarked everyin_progressrecord interrupted whenever another broker started, and could race a realfinish. - Personal settings could become root-owned.
UserStorage::write_privatecreated directories and files with the process's effective uid, so asudoinvocation wrote root-owned files into the user's home. - 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/<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 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. - 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;
sysrefuses 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;pkexecstrips 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_progressrecord 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
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.