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

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.