//! Integrity seals, approval digests, and plan validation: the authoritative //! privileged validation boundary shared by every execution path. use std::path::Path; use phoebus_core::action::SystemAction; use phoebus_core::effects::ResolvedPlan; use phoebus_core::selection::Candidate; use phoebus_executor::actions; use phoebus_executor::auth::Confirmation; use phoebus_executor::chooser; use phoebus_executor::error::{ExecError, Result}; use phoebus_executor::exec::Exec; use phoebus_executor::install::{self, InstallRequest, InstallSource}; use sha2::{Digest, Sha256}; use super::{canonical_root, is_safe_plan_id, now_unix, PlanKind, PreparedPlan}; /// Recompute the self-consistency seal over every reviewed field. The stored /// `integrity` value is deliberately excluded. A reload whose recomputation /// differs was modified after it was approved. pub(super) fn plan_integrity(plan: &PreparedPlan) -> String { let mut hasher = Sha256::new(); hasher.update(plan.id.as_bytes()); hasher.update(b"\0"); hasher.update(format!("{:?}", plan.kind).as_bytes()); hasher.update(b"\0"); hasher.update(plan.created_unix.to_le_bytes()); hasher.update(plan.expires_unix.to_le_bytes()); hasher.update(plan.digest.as_bytes()); hasher.update(b"\0"); hasher.update(plan.effects.digest.as_bytes()); hasher.update(b"\0"); if let Some(c) = &plan.candidate { hasher.update(c.backend.as_str().as_bytes()); hasher.update(b"\0"); hasher.update(c.id.as_bytes()); hasher.update(b"\0"); hasher.update(c.version.as_deref().unwrap_or("").as_bytes()); hasher.update(b"\0"); } for act in &plan.actions { hasher.update(serde_json::to_string(act).unwrap_or_default().as_bytes()); hasher.update(b"\0"); } for step in &plan.step_effects { hasher.update(step.digest.as_bytes()); hasher.update(b"\0"); } hasher.update(plan.target_root.as_bytes()); hasher.update(b"\0"); hasher.update(plan.source.as_bytes()); hasher.update(b"\0"); hasher.update(plan.initiator_uid.to_le_bytes()); hasher.update(b"\0"); hasher.update([plan.requires_root as u8]); hasher.update([plan.executed as u8]); // Everything the human reviewed is sealed, so a modified summary or // verification statement cannot pass as the approved plan. for field in [ &plan.summary, &plan.recommendation, plan.application.as_deref().unwrap_or(""), &plan.verification, ] { hasher.update(field.as_bytes()); hasher.update(b"\0"); } for line in plan.rationale.iter().chain(plan.warnings.iter()) { hasher.update(line.as_bytes()); hasher.update(b"\0"); } for alt in &plan.alternatives { hasher.update(serde_json::to_string(alt).unwrap_or_default().as_bytes()); hasher.update(b"\0"); } format!("{:x}", hasher.finalize()) } /// Compute and store the plan seal. Must be called before persistence. pub fn seal_plan(plan: &mut PreparedPlan) { plan.integrity = plan_integrity(plan); } /// The canonical digest of a single step's material effects. /// /// The digest is *recomputed* from the effect list rather than read from the /// stored `digest` field, so a plan owner cannot change a step's contents while /// leaving its stored digest (and therefore the approval) intact. fn step_effects_digest(step: &ResolvedPlan) -> String { let mut normalized = step.clone(); normalized.recompute_digest(); normalized.digest } /// The per-step reviewed effects that execution will actually trust. /// /// New plans always store one step per action. A single-action plan may fall /// back to its aggregate effects for backward compatibility; a multi-action /// plan without per-step effects cannot be bound and is refused. pub(super) fn reviewed_steps(plan: &PreparedPlan) -> Result> { if plan.step_effects.len() == plan.actions.len() && !plan.step_effects.is_empty() { Ok(plan.step_effects.clone()) } else if plan.actions.len() == 1 { Ok(vec![plan.effects.clone()]) } else { Err(ExecError::operation( "service", "validate plan", "plan is missing per-step effects; refusing to execute a multi-action plan whose \ reviewed effects are not individually bound", )) } } /// Verify that every stored per-step effect digest matches its actual contents /// and that the aggregate effects are exactly the concatenation of the steps. pub(super) fn validate_effect_bindings(plan: &PreparedPlan, steps: &[ResolvedPlan]) -> Result<()> { for (idx, step) in steps.iter().enumerate() { if step.digest != step_effects_digest(step) { return Err(ExecError::operation( "service", "validate plan", format!( "the stored effect digest for step {idx} does not match its contents; the \ plan was modified after it was reviewed" ), )); } } let mut combined = ResolvedPlan { established: true, ..Default::default() }; for step in steps { combined.effects.extend(step.effects.clone()); combined.cleanup.extend(step.cleanup.clone()); combined.updates.extend(step.updates.clone()); combined.consequences.extend(step.consequences.clone()); } combined.recompute_digest(); let mut aggregate = plan.effects.clone(); aggregate.recompute_digest(); if combined.digest != aggregate.digest { return Err(ExecError::operation( "service", "validate plan", "the aggregate effects are not consistent with the reviewed per-step effects; the \ plan was modified after it was reviewed", )); } Ok(()) } /// Compute a cryptographic digest binding the exact actions, candidate, the /// reviewed aggregate effects and every per-step effect that execution trusts. pub fn compute_plan_digest( actions: &[SystemAction], candidate: Option<&Candidate>, effects: &ResolvedPlan, step_effects: &[ResolvedPlan], ) -> String { // A single installed candidate binds through the install-specific digest. // `validate_effect_bindings` separately requires that its one step equals // the aggregate, so the step effects are bound transitively. if let (Some(cand), Some(act)) = (candidate, actions.first()) { if actions.len() == 1 { return install::approval_digest_for(cand, act, effects); } } let mut hasher = Sha256::new(); if let Some(c) = candidate { hasher.update(c.backend.as_str().as_bytes()); hasher.update(b"\0"); hasher.update(c.id.as_bytes()); hasher.update(b"\0"); hasher.update(c.version.as_deref().unwrap_or("").as_bytes()); hasher.update(b"\0"); } for act in actions { hasher.update(serde_json::to_string(act).unwrap_or_default().as_bytes()); hasher.update(b"\0"); } // Bind every material per-step effect execution will trust, recomputed from // its contents so a retained approval cannot hide a changed schedule. for step in step_effects { hasher.update(step_effects_digest(step).as_bytes()); hasher.update(b"\0"); } hasher.update(b"aggregate\0"); if effects.established { hasher.update(effects.digest.as_bytes()); } else { hasher.update(b"no-established-effects"); } format!("{:x}", hasher.finalize()) } // ----------------------------------------------------------------------------- // Privileged validation boundary // ----------------------------------------------------------------------------- pub(super) struct ServiceConfirm { pub(super) assume_yes: bool, } impl Confirmation for ServiceConfirm { fn confirm_erase(&self, _preview: &str) -> Result { Ok(self.assume_yes) } fn confirm_final(&self, _message: &str) -> Result { Ok(self.assume_yes) } } /// The single authoritative validation boundary. Runs immediately before any /// privileged mutation, in both the unprivileged pre-check and the broker after /// authentication. It binds the approval to the exact actions, effects, /// candidate, target root and initiating user, re-derives the plan seal, and /// revalidates live state. Plan files are untrusted input. pub fn validate_prepared_plan( exec: &Exec, root: &Path, plan: &PreparedPlan, expected_digest: Option<&str>, initiator_uid: u32, ) -> Result<()> { if plan.integrity.is_empty() || plan.integrity != plan_integrity(plan) { return Err(ExecError::operation( "service", "validate plan", "plan integrity check failed; the plan was modified after it was reviewed", )); } if !is_safe_plan_id(&plan.id) { return Err(ExecError::operation( "service", "validate plan", "plan has an invalid identifier", )); } if plan.executed { return Err(ExecError::operation( "service", "validate plan", "plan has already been executed; replayed plans are rejected", )); } if now_unix() > plan.expires_unix { return Err(ExecError::operation( "service", "validate plan", "plan has expired; review and approve a fresh plan", )); } if plan.actions.is_empty() { return Err(ExecError::operation( "service", "validate plan", "plan proposes no actions", )); } // Independently recompute the canonical approval digest from the exact // executable actions, candidate and reviewed material effects. The // `integrity` seal stored beside the plan is a self-consistency check the // owning user can recompute, so it is not authentication: the canonical // digest is. It must match the digest stored in the plan *and* the // independently supplied approval digest. This binds every plan kind // (Install, LegacyInstall, Removal, General, Undo) to the reviewed actions, // so retaining an old digest while swapping an action and resealing is // rejected before any mutation. // // Execution trusts the per-step effects (`step_effects`), so those must be // bound too: each stored effect digest must match its actual contents, the // aggregate must be the concatenation of the steps, and the canonical // digest must cover every step. This closes the "retain the approved digest, // change only `step_effects`, reseal" gap for General and Undo plans. let steps = reviewed_steps(plan)?; validate_effect_bindings(plan, &steps)?; let canonical = compute_plan_digest( &plan.actions, plan.candidate.as_ref(), &plan.effects, &steps, ); if plan.digest != canonical { return Err(ExecError::operation( "service", "validate plan", "plan digest does not match its reviewed actions and effects; the plan was \ substituted or resealed and is refused", )); } if let Some(digest) = expected_digest { if !digest.is_empty() && canonical != digest { return Err(ExecError::operation( "service", "validate plan", "approval digest mismatch; the plan was altered or is not the one reviewed", )); } } if plan.target_root.is_empty() { return Err(ExecError::operation( "service", "validate plan", "plan does not record a target root; refusing to guess `/`", )); } let want_root = canonical_root(root); if plan.target_root != want_root { return Err(ExecError::operation( "service", "validate plan", format!( "target root mismatch: the plan was reviewed for {} but execution targets {}", plan.target_root, want_root ), )); } if plan.initiator_uid != initiator_uid { return Err(ExecError::operation( "service", "validate plan", format!( "plan belongs to uid {} and cannot be executed by uid {initiator_uid}", plan.initiator_uid ), )); } revalidate_plan_state(exec, root, plan) } /// Revalidate a plan's material state against live metadata. A material change /// invalidates the earlier approval. fn revalidate_plan_state(exec: &Exec, root: &Path, plan: &PreparedPlan) -> Result<()> { match plan.kind { PlanKind::Install | PlanKind::LegacyInstall => { let (Some(cand), Some(act)) = (&plan.candidate, plan.actions.first()) else { return Err(ExecError::operation( "service", "revalidate", "installation plan is missing its candidate or action", )); }; let resolved = install::ResolvedInstall { request: InstallRequest::new(plan.application.as_deref().unwrap_or("")), candidate: cand.clone(), action: act.clone(), effects: plan.effects.clone(), rationale: plan.rationale.clone(), alternatives: plan.alternatives.clone(), source: match plan.kind { PlanKind::LegacyInstall => InstallSource::ExplicitBackend, _ => InstallSource::AiRecommendation, }, warnings: plan.warnings.clone(), verification: plan.verification.clone(), }; let current_digest = install::revalidate(exec, root, &resolved).map_err(|e| { ExecError::operation( "service", "revalidate", format!("the reviewed plan changed before execution ({e}); review again"), ) })?; if current_digest != plan.digest { return Err(ExecError::operation( "service", "revalidate", "system state or package metadata changed materially since review; review again", )); } } PlanKind::Removal => { let Some(app) = &plan.application else { return Err(ExecError::operation( "service", "revalidate", "removal plan has no application", )); }; let check = chooser::installed_copies(exec, root, app); if !check.copies.iter().any(|c| c.backend == plan.source) { return Err(ExecError::operation( "service", "revalidate", format!( "`{app}` is no longer installed via {}; the removal plan is stale", plan.source ), )); } if let Some(act) = plan.actions.first() { let eff = actions::resolve_effects(exec, act, root)?; if eff.established && plan.effects.established && eff.digest != plan.effects.digest { return Err(ExecError::operation( "service", "revalidate", "the removal effects changed since review; review again", )); } } } PlanKind::General | PlanKind::Undo => { if plan.step_effects.len() == plan.actions.len() && !plan.step_effects.is_empty() { // Compare each step against its own reviewed effects, never one // action against the whole plan. for (act, reviewed) in plan.actions.iter().zip(plan.step_effects.iter()) { let eff = actions::resolve_effects(exec, act, root)?; if reviewed.established && eff.established && reviewed.digest != eff.digest { return Err(ExecError::operation( "service", "revalidate", format!( "effects for `{}` changed materially since review; review again", act.describe() ), )); } } } else { // Older plans carried only the aggregate; recompute the same // aggregate and compare, rather than mixing per-action digests. let mut combined = ResolvedPlan { established: true, ..Default::default() }; for act in &plan.actions { let eff = actions::resolve_effects(exec, act, root)?; if eff.established { combined.effects.extend(eff.effects); combined.cleanup.extend(eff.cleanup); combined.updates.extend(eff.updates); combined.consequences.extend(eff.consequences); } } combined.recompute_digest(); if plan.effects.established && combined.digest != plan.effects.digest { return Err(ExecError::operation( "service", "revalidate", "system state or package effects changed materially since review; review again", )); } } } } Ok(()) }