phoebus_os/docs/adr/0014-privileged-approval-ledger.md
2026-09-24 20:43:33 -07:00

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.