97 lines
4.8 KiB
Markdown
97 lines
4.8 KiB
Markdown
# 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.
|