158 lines
8.7 KiB
Markdown
158 lines
8.7 KiB
Markdown
# 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.
|