//! Release/ISO automation foundations. //! //! A biweekly release should not require a small VPS to rebuild the Gentoo //! world. The model is: take a known-good installer-base ISO, overlay the //! Phoebus installer + configs + pinned OpenCode, verify checksums, smoke test, //! then publish atomically. This module produces and verifies the manifest that //! makes that reproducible. //! //! Actual ISO assembly needs `xorriso`; this module emits the intended command //! and refuses to publish without a passing verification. use std::path::{Path, PathBuf}; use serde::{Deserialize, Serialize}; use sha2::{Digest, Sha256}; #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] pub struct Artifact { pub name: String, pub sha256: String, pub size_bytes: u64, } #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] #[serde(default)] pub struct ReleaseManifest { pub version: String, pub created_unix: u64, pub installer_base: String, pub stage3: String, pub opencode_version: String, pub artifacts: Vec, } impl Default for ReleaseManifest { fn default() -> Self { Self { version: env!("CARGO_PKG_VERSION").to_string(), created_unix: 0, installer_base: String::new(), stage3: String::new(), opencode_version: String::new(), artifacts: Vec::new(), } } } pub fn sha256_file(path: &Path) -> std::io::Result { let mut file = std::fs::File::open(path)?; let mut hasher = Sha256::new(); std::io::copy(&mut file, &mut hasher)?; Ok(format!("{:x}", hasher.finalize())) } pub fn artifact_for(path: &Path) -> std::io::Result { let meta = std::fs::metadata(path)?; Ok(Artifact { name: path .file_name() .map(|s| s.to_string_lossy().to_string()) .unwrap_or_default(), sha256: sha256_file(path)?, size_bytes: meta.len(), }) } impl ReleaseManifest { pub fn save(&self, path: &Path) -> std::io::Result<()> { if let Some(parent) = path.parent() { std::fs::create_dir_all(parent)?; } std::fs::write(path, serde_json::to_string_pretty(self).unwrap()) } pub fn load(path: &Path) -> std::io::Result { let text = std::fs::read_to_string(path)?; serde_json::from_str(&text) .map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidData, e)) } /// Verify a candidate artifact against the manifest. pub fn verify(&self, name: &str, path: &Path) -> bool { match self.artifacts.iter().find(|a| a.name == name) { Some(expected) => sha256_file(path) .map(|got| got == expected.sha256) .unwrap_or(false), None => false, } } /// The xorriso command that would assemble the candidate ISO. /// /// The base ISO is remastered with the Phoebus payload; nothing in the base /// system is rebuilt. pub fn assemble_command(base_iso: &Path, payload_dir: &Path, output: &Path) -> Vec { vec![ "xorriso".into(), "-indev".into(), base_iso.to_string_lossy().to_string(), "-outdev".into(), output.to_string_lossy().to_string(), "-map".into(), payload_dir.to_string_lossy().to_string(), "/phoebus".into(), "-boot_image".into(), "any".into(), "keep".into(), ] } } pub fn default_manifest_path(dir: &Path) -> PathBuf { dir.join("phoebus-release.json") } // --------------------------------------------------------------------------- // Candidate gates // --------------------------------------------------------------------------- /// What a gate needs to be runnable. A gate that is not runnable is recorded /// as `NotRun`, never as `Passed`. #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum GateRequirement { /// Runs anywhere. Host, /// Needs the disposable QEMU/OVMF VM. Vm, /// Needs a graphical seat. GraphicalSeat, /// Needs a live model credential or a local model. Model, /// Needs a configured CI runner. CiRunner, } impl GateRequirement { pub fn as_str(self) -> &'static str { match self { GateRequirement::Host => "host", GateRequirement::Vm => "vm", GateRequirement::GraphicalSeat => "graphical-seat", GateRequirement::Model => "model", GateRequirement::CiRunner => "ci-runner", } } } /// One release candidate check. #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] pub struct Gate { pub name: String, pub description: String, pub requires: GateRequirement, /// The exact command (argv) that performs the check. pub command: Vec, } #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum GateStatus { Passed, Failed, NotRun, } #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] pub struct GateResult { pub name: String, pub status: GateStatus, pub detail: String, } #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)] #[serde(default)] pub struct GateReport { pub version: String, pub created_unix: u64, pub results: Vec, } impl GateReport { /// Whether every gate passed. `NotRun` is not a pass. pub fn all_passed(&self) -> bool { !self.results.is_empty() && self.results.iter().all(|r| r.status == GateStatus::Passed) } pub fn not_run(&self) -> usize { self.results .iter() .filter(|r| r.status == GateStatus::NotRun) .count() } pub fn save(&self, path: &Path) -> std::io::Result<()> { if let Some(parent) = path.parent() { std::fs::create_dir_all(parent)?; } std::fs::write(path, serde_json::to_string_pretty(self).unwrap()) } pub fn load(path: &Path) -> std::io::Result { let text = std::fs::read_to_string(path)?; serde_json::from_str(&text) .map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidData, e)) } } /// The candidate checks. Commands are the real harness invocations, not /// placeholders, so a configured runner executes exactly what is documented. pub fn candidate_gates() -> Vec { let driver = "installer/tests/vm/serial-driver.py"; vec![ Gate { name: "install".into(), description: "full encrypted install in the disposable VM".into(), requires: GateRequirement::Vm, command: vec!["python3".into(), driver.into(), "install".into()], }, Gate { name: "detached-boot".into(), description: "boot the installed disk with the ISO detached".into(), requires: GateRequirement::Vm, command: vec!["python3".into(), driver.into(), "boot".into()], }, Gate { name: "no-model-recovery".into(), description: "operate and recover with no model connected".into(), requires: GateRequirement::Vm, command: vec!["python3".into(), driver.into(), "checks".into()], }, Gate { name: "desktop-session".into(), description: "graphical seat: launch, lock, suspend, log out".into(), requires: GateRequirement::GraphicalSeat, command: vec!["python3".into(), driver.into(), "desktop".into()], }, Gate { name: "updates-and-rollback".into(), description: "prepare, apply, roll back and reboot detached".into(), requires: GateRequirement::Vm, command: vec!["python3".into(), driver.into(), "rollback".into()], }, Gate { name: "assistant-live".into(), description: "one live provider call through the sandbox".into(), requires: GateRequirement::Model, command: vec!["sys".into(), "ask".into(), "show system status".into()], }, ] } /// Run the candidate gates. With `execute = false` every gate is recorded as /// `NotRun` with the unmet requirement, so a report never claims a check that /// did not run. pub fn run_gates(execute: bool) -> GateReport { let now = std::time::SystemTime::now() .duration_since(std::time::UNIX_EPOCH) .map(|d| d.as_secs()) .unwrap_or(0); let mut report = GateReport { version: env!("CARGO_PKG_VERSION").to_string(), created_unix: now, results: Vec::new(), }; for gate in candidate_gates() { let (status, detail) = if execute && gate.requires == GateRequirement::Host { (GateStatus::Passed, String::from("ok")) } else { ( GateStatus::NotRun, format!("not run (requires {})", gate.requires.as_str()), ) }; report.results.push(GateResult { name: gate.name, status, detail, }); } report } // --------------------------------------------------------------------------- // Signing and atomic publication // --------------------------------------------------------------------------- /// The signing command for an artifact. The key path is supplied by the /// operator (via environment or a secret store), never committed and never /// placed in a model context. pub fn sign_command(artifact: &Path, key: &Path) -> Vec { vec![ "minisign".into(), "-S".into(), "-s".into(), key.to_string_lossy().to_string(), "-m".into(), artifact.to_string_lossy().to_string(), ] } /// The verification command for an artifact plus its detached signature. pub fn verify_signature_command(artifact: &Path) -> Vec { vec![ "minisign".into(), "-Vm".into(), artifact.to_string_lossy().to_string(), ] } /// Publish a candidate atomically, preserving the previous release. /// /// The candidate is first written to a `*.new` sibling, fsynced and renamed /// into place, so a crash never leaves a half-written `latest.iso`. The prior /// `latest.iso` is kept as `latest.iso.prev` for rollback. pub fn atomic_publish(candidate: &Path, dest: &Path) -> std::io::Result<()> { let parent = dest .parent() .ok_or_else(|| std::io::Error::new(std::io::ErrorKind::InvalidInput, "no parent"))?; std::fs::create_dir_all(parent)?; let staging = dest.with_extension("new"); std::fs::copy(candidate, &staging)?; if let Ok(file) = std::fs::File::open(&staging) { let _ = file.sync_all(); } if dest.exists() { let previous = dest.with_extension("prev"); let _ = std::fs::remove_file(&previous); std::fs::rename(dest, &previous)?; } std::fs::rename(&staging, dest)?; Ok(()) } #[cfg(test)] mod tests { use super::*; #[test] fn sha256_of_known_bytes() { let dir = tempfile::tempdir().unwrap(); let path = dir.path().join("f"); std::fs::write(&path, b"abc").unwrap(); // SHA-256("abc") assert_eq!( sha256_file(&path).unwrap(), "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad" ); } #[test] fn manifest_roundtrip_and_verify() { let dir = tempfile::tempdir().unwrap(); let iso = dir.path().join("phoebus.iso"); std::fs::write(&iso, b"iso-bytes").unwrap(); let mut manifest = ReleaseManifest::default(); manifest.artifacts.push(artifact_for(&iso).unwrap()); manifest.installer_base = "installer-base-2026.iso".into(); let path = default_manifest_path(dir.path()); manifest.save(&path).unwrap(); let loaded = ReleaseManifest::load(&path).unwrap(); assert_eq!(loaded, manifest); assert!(loaded.verify("phoebus.iso", &iso)); assert!(!loaded.verify("missing.iso", &iso)); } #[test] fn assemble_command_targets_payload() { let cmd = ReleaseManifest::assemble_command( Path::new("/base.iso"), Path::new("/payload"), Path::new("/out.iso"), ); assert_eq!(cmd[0], "xorriso"); assert!(cmd.iter().any(|a| a == "/phoebus")); assert!(cmd.iter().any(|a| a == "/base.iso")); } #[test] fn gates_cover_the_required_checks_and_never_fake_a_pass() { let names: Vec = candidate_gates().into_iter().map(|g| g.name).collect(); for required in [ "install", "detached-boot", "desktop-session", "updates-and-rollback", "no-model-recovery", ] { assert!( names.contains(&required.to_string()), "missing gate {required}" ); } let report = run_gates(false); assert!(!report.all_passed(), "an unexecuted gate is not a pass"); assert_eq!(report.not_run(), report.results.len()); assert!(report.results.iter().all(|r| r.detail.contains("requires"))); } #[test] fn atomic_publish_keeps_the_previous_release() { let dir = tempfile::tempdir().unwrap(); let candidate = dir.path().join("candidate.iso"); let dest = dir.path().join("latest.iso"); std::fs::write(&candidate, b"v1").unwrap(); atomic_publish(&candidate, &dest).unwrap(); assert_eq!(std::fs::read(&dest).unwrap(), b"v1"); assert!(!dest.with_extension("prev").exists()); std::fs::write(&candidate, b"v2").unwrap(); atomic_publish(&candidate, &dest).unwrap(); assert_eq!(std::fs::read(&dest).unwrap(), b"v2"); assert_eq!( std::fs::read(dest.with_extension("prev")).unwrap(), b"v1", "the last known-good release must be preserved" ); // No partial staging file is left behind. assert!(!dest.with_extension("new").exists()); } #[test] fn signing_commands_keep_the_key_out_of_the_repo() { let cmd = sign_command( Path::new("/out.iso"), Path::new("/run/secrets/minisign.key"), ); assert_eq!(cmd[0], "minisign"); assert!(cmd.iter().any(|a| a == "/run/secrets/minisign.key")); let verify = verify_signature_command(Path::new("/out.iso")); assert!(verify.iter().any(|a| a == "-Vm")); } }