phoebus_os/installer-rs/crates/phoebus-installer/src/release.rs
Phoebus 25f7381b4a
Some checks are pending
ci / test (push) Waiting to run
feat(desktop): add Mango + DankMaterialShell profile with rollback, assistant and release foundations
- Mango + DankMaterialShell desktop option (desktop.profile = "mango") through
  the GURU overlay with scoped ~amd64 keywords, a sealed session entry point and
  a dwl fallback session (ADR 0009).
- Coherent rollback/recovery: coordinated @ + @var snapshots, fstab and BLS
  root-subvolume rewriting, matching-kernel selection, snapshot recovery entry,
  retention/space gates and sys undo (ADR 0007).
- Installed assistant (sys ask) with an OS-level systemd sandbox boundary and
  fail-closed typed plans; resolved package effects bound to approval.
- Nix build isolation enforced (sandbox, no fallback) plus lifecycle/cleanup.
- Desktop helpers (menu/lock/idle), transaction log, release gates with atomic
  publish and signing helpers, and a Debian-Live appliance VM harness.
2026-09-21 03:46:52 -07:00

433 lines
14 KiB
Rust

//! 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<Artifact>,
}
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<String> {
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<Artifact> {
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<Self> {
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<String> {
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<String>,
}
#[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<GateResult>,
}
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<Self> {
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<Gate> {
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<String> {
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<String> {
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<String> = 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"));
}
}