//! Phoebus-managed custom ebuild lane. //! //! Sometimes no maintained candidate is suitable, and the honest answer is a //! local ebuild. This module owns a dedicated overlay //! (`/var/db/repos/phoebus`), records *why* each custom package exists, and //! binds approval to the exact ebuild content by SHA-256. Editing a staged //! ebuild invalidates any prior approval. //! //! Safety model: a generated ebuild and its phase functions are **executable, //! untrusted code**. The model may propose one, but it never runs it. Staging //! only writes the artifact; building happens solely through the deterministic //! broker (`CustomEbuildInstall`) whose caller must present the digest that was //! reviewed. There is no path from a proposal to a privileged shell. use std::path::{Path, PathBuf}; use serde::{Deserialize, Serialize}; use crate::error::{ExecError, Result}; use crate::exec::Exec; /// The dedicated Phoebus overlay, relative to the target root. pub const OVERLAY_REL: &str = "var/db/repos/phoebus"; /// The Portage repository configuration, relative to the target root. pub const REPOS_CONF_REL: &str = "etc/portage/repos.conf/phoebus.conf"; /// A staged custom ebuild with its approval-bound digest. #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] pub struct StagedEbuild { pub atom: String, pub version: String, /// SHA-256 of the exact ebuild content that was staged. pub digest: String, /// Why custom packaging was needed instead of an existing package. pub rationale: String, pub created_unix: u64, } impl StagedEbuild { pub fn package_name(&self) -> String { self.atom .split('/') .nth(1) .unwrap_or(&self.atom) .to_string() } } fn now_unix() -> u64 { std::time::SystemTime::now() .duration_since(std::time::UNIX_EPOCH) .map(|d| d.as_secs()) .unwrap_or(0) } fn overlay_dir(root: &Path) -> PathBuf { root.join(OVERLAY_REL) } fn package_dir(root: &Path, atom: &str) -> Result { // The path constructor is the last line of defence: never join an atom // that is not a strict `category/package` with safe components. if !phoebus_core::action::valid_ebuild_atom(atom) { return Err(ExecError::operation( "ebuild", "resolve overlay path", "atom must be category/package", )); } let (category, package) = atom.split_once('/').ok_or_else(|| { ExecError::operation( "ebuild", "resolve overlay path", "atom must be category/package", ) })?; Ok(overlay_dir(root).join(category).join(package)) } fn ebuild_path(root: &Path, atom: &str, version: &str) -> Result { let package = atom.split('/').nth(1).unwrap_or(atom); Ok(package_dir(root, atom)?.join(format!("{package}-{version}.ebuild"))) } /// Ensure the overlay is registered with Portage. Idempotent. fn ensure_overlay(exec: &Exec, root: &Path) -> Result<()> { let dir = overlay_dir(root); for sub in ["profiles", "metadata"] { std::fs::create_dir_all(dir.join(sub)).map_err(|e| ExecError::io(dir.join(sub), e))?; } let files = [ ("profiles/repo_name", "phoebus\n".to_string()), ( "metadata/layout.conf", "masters = gentoo\nthin-manifests = false\n".to_string(), ), ( "profiles/categories", // Categories are added as needed; an empty list is valid. String::new(), ), ]; for (rel, contents) in files { let path = dir.join(rel); if !path.exists() { std::fs::write(&path, contents).map_err(|e| ExecError::io(path, e))?; } } // Write the repository configuration. let conf = root.join(REPOS_CONF_REL); if let Some(parent) = conf.parent() { std::fs::create_dir_all(parent).map_err(|e| ExecError::io(parent.to_path_buf(), e))?; } let location = dir.to_string_lossy().to_string(); let contents = format!("[phoebus]\nlocation = {location}\npriority = 100\nauto-sync = no\n"); if exec.dry_run { exec.logger .info("[dry-run] would register the Phoebus overlay"); } else { std::fs::write(&conf, contents).map_err(|e| ExecError::io(conf, e))?; } Ok(()) } /// Stage an ebuild. This does **not** build or install anything; it records the /// artifact and the reason it exists, and returns its content digest. pub fn prepare( exec: &Exec, root: &Path, atom: &str, version: &str, rationale: &str, ebuild: &str, ) -> Result { // Defence in depth: even though the action validator checks these, staging // re-checks so no path traversal can reach the overlay. if !phoebus_core::action::valid_ebuild_atom(atom) || !phoebus_core::action::valid_ebuild_version(version) { return Err(ExecError::operation( "ebuild", "stage ebuild", "invalid atom or version", )); } if ebuild.contains('\0') { return Err(ExecError::operation( "ebuild", "stage ebuild", "ebuild content contains a NUL byte", )); } ensure_overlay(exec, root)?; let dir = package_dir(root, atom)?; std::fs::create_dir_all(&dir).map_err(|e| ExecError::io(dir.clone(), e))?; let path = ebuild_path(root, atom, version)?; let digest = crate::opencode::sha256_hex(ebuild.as_bytes()); if exec.dry_run { exec.logger.info(format!( "[dry-run] would stage custom ebuild {atom}-{version}" )); return Ok(StagedEbuild { atom: atom.to_string(), version: version.to_string(), digest, rationale: rationale.to_string(), created_unix: now_unix(), }); } std::fs::write(&path, ebuild).map_err(|e| ExecError::io(path.clone(), e))?; let record = StagedEbuild { atom: atom.to_string(), version: version.to_string(), digest, rationale: rationale.to_string(), created_unix: now_unix(), }; write_record(root, &record)?; exec.logger.info(format!( "staged custom ebuild {atom}-{version} (not installed)" )); Ok(record) } fn record_path(root: &Path, atom: &str) -> Result { Ok(package_dir(root, atom)?.join(".phoebus-ebuild.toml")) } fn write_record(root: &Path, record: &StagedEbuild) -> Result<()> { let path = record_path(root, &record.atom)?; let text = toml::to_string_pretty(record) .map_err(|e| ExecError::operation("ebuild", "write record", e.to_string()))?; std::fs::write(&path, text).map_err(|e| ExecError::io(path, e)) } /// Look up the staged record for an atom (newest if several). pub fn staged(root: &Path, atom: &str) -> Option { let path = record_path(root, atom).ok()?; let text = std::fs::read_to_string(path).ok()?; toml::from_str(&text).ok() } /// List every staged custom ebuild. pub fn list(root: &Path) -> Vec { let mut out = Vec::new(); let dir = overlay_dir(root); let Ok(categories) = std::fs::read_dir(&dir) else { return out; }; for category in categories.flatten() { if !category.path().is_dir() { continue; } let Ok(packages) = std::fs::read_dir(category.path()) else { continue; }; for package in packages.flatten() { let record = package.path().join(".phoebus-ebuild.toml"); if let Ok(text) = std::fs::read_to_string(record) { if let Ok(staged) = toml::from_str::(&text) { out.push(staged); } } } } out.sort_by(|a, b| { (a.atom.clone(), a.version.clone()).cmp(&(b.atom.clone(), b.version.clone())) }); out } /// Re-read the exact staged ebuild content and confirm it still matches the /// approved digest. Any change invalidates the approval. pub fn verify_digest(root: &Path, ebuild: &StagedEbuild) -> Result<()> { let current = staged(root, &ebuild.atom).ok_or_else(|| { ExecError::operation( "ebuild", "verify approval", "the ebuild is no longer staged", ) })?; if current.digest != ebuild.digest { return Err(ExecError::operation( "ebuild", "verify approval", "the staged ebuild changed since it was reviewed; re-review before installing", )); } let path = ebuild_path(root, &ebuild.atom, &ebuild.version)?; let content = std::fs::read(&path).map_err(|e| ExecError::io(path.clone(), e))?; let actual = crate::opencode::sha256_hex(&content); if actual != ebuild.digest { return Err(ExecError::operation( "ebuild", "verify approval", "the ebuild content no longer matches the approved digest", )); } Ok(()) } /// Build and install a staged ebuild through Portage. /// /// The caller must present the digest that was reviewed. The ebuild is /// untrusted code: it is built inside the target chroot with Portage's own /// build sandbox (`sandbox`, `userpriv`) and `ebuild ... manifest`, never by /// the model and never with an unrestricted shell. pub fn install(exec: &Exec, root: &Path, atom: &str, version: &str, digest: &str) -> Result<()> { if exec.dry_run { exec.logger.info(format!( "[dry-run] would build and install {atom}-{version} from the Phoebus overlay" )); return Ok(()); } let record = staged(root, atom).ok_or_else(|| { ExecError::operation( "ebuild", "install custom ebuild", format!("{atom} is not staged"), ) })?; if record.version != version || record.digest != digest { return Err(ExecError::operation( "ebuild", "install custom ebuild", "the requested version/digest does not match the staged artifact", )); } verify_digest(root, &record)?; ensure_overlay(exec, root)?; let ebuild = ebuild_path(root, atom, version)?; // Generate the Manifest (sources must already be fetchable). This runs the // ebuild's metadata phase, which is why it happens only after approval. crate::portage::chroot( exec, root, "ebuild", &[&ebuild.to_string_lossy(), "manifest"], )?; // Build and install through Portage, with its build sandbox and unprivileged // build user enabled. let features = "sandbox userpriv".to_string(); let spec = crate::portage::chroot_spec( "ebuild", &format!("emerge {atom}"), root, "emerge", &[ "--ask=n".into(), "--quiet-build=y".into(), "--noreplace".into(), atom.to_string(), ], ) .env("FEATURES", features); exec.run(spec)?; exec.logger .info(format!("installed custom ebuild {atom}-{version}")); Ok(()) } /// Unmerge a custom package and remove its ebuild from the overlay. pub fn remove(exec: &Exec, root: &Path, atom: &str) -> Result<()> { if exec.dry_run { exec.logger .info(format!("[dry-run] would remove custom ebuild {atom}")); return Ok(()); } // Unmerge through Portage; a package that is not installed is not an error. let _ = crate::portage::chroot(exec, root, "emerge", &["--unmerge", "--ask=n", atom]); let dir = package_dir(root, atom)?; if dir.is_dir() { std::fs::remove_dir_all(&dir).map_err(|e| ExecError::io(dir, e))?; } exec.logger.info(format!( "removed custom ebuild {atom} from the Phoebus overlay" )); Ok(()) } /// A deterministic command name for QA tooling; used in reviews. pub fn qa_hint() -> &'static str { "GENTOO_QA: run `pkgcheck scan` on the overlay entry before installing" } #[cfg(test)] mod tests { use super::*; use crate::command::{CommandOutput, RecordingRunner}; use crate::log::Logger; use phoebus_core::Redactor; use std::time::Duration; fn make_exec(runner: RecordingRunner, dry_run: bool) -> Exec { let path = tempfile::tempdir().unwrap().keep(); let logger = Logger::open(path.join("l.log"), Redactor::new(), false); Exec::new(Box::new(runner), logger, dry_run, path.join("root"), path) } const SAMPLE: &str = "\ EAPI=8 DESCRIPTION=\"Example\" SLOT=\"0\" "; #[test] fn prepare_stages_and_records_a_digest() { let exec = make_exec(RecordingRunner::new(), false); let root = tempfile::tempdir().unwrap(); let staged = prepare( &exec, root.path(), "app-misc/example", "1.0", "no maintained package provides the required feature", SAMPLE, ) .unwrap(); assert_eq!(staged.digest.len(), 64); assert!(ebuild_path(root.path(), "app-misc/example", "1.0") .unwrap() .is_file()); assert!(root.path().join(REPOS_CONF_REL).is_file()); let found = staged_(root.path(), "app-misc/example"); assert_eq!(found.digest, staged.digest); assert_eq!(list(root.path()).len(), 1); } fn staged_(root: &Path, atom: &str) -> StagedEbuild { staged(root, atom).expect("staged record") } #[test] fn editing_a_staged_ebuild_invalidates_the_digest() { let exec = make_exec(RecordingRunner::new(), false); let root = tempfile::tempdir().unwrap(); let staged = prepare( &exec, root.path(), "app-misc/example", "1.0", "reason", SAMPLE, ) .unwrap(); verify_digest(root.path(), &staged).unwrap(); // Tamper with the file after approval. let path = ebuild_path(root.path(), "app-misc/example", "1.0").unwrap(); std::fs::write(&path, "EAPI=8\n# changed\n").unwrap(); let err = verify_digest(root.path(), &staged).unwrap_err(); assert!(err.to_string().contains("no longer matches"), "{err}"); } #[test] fn install_requires_the_reviewed_digest() { let exec = make_exec(RecordingRunner::new(), false); let root = tempfile::tempdir().unwrap(); prepare( &exec, root.path(), "app-misc/example", "1.0", "reason", SAMPLE, ) .unwrap(); // Wrong digest is refused before any build command. let err = install( &exec, root.path(), "app-misc/example", "1.0", &"a".repeat(64), ) .unwrap_err(); assert!(err.to_string().contains("does not match"), "{err}"); } #[test] fn install_runs_manifest_then_emerge_in_the_target() { let runner = RecordingRunner::new(); let exec = make_exec(runner.clone(), false); let root = tempfile::tempdir().unwrap(); let staged = prepare( &exec, root.path(), "app-misc/example", "1.0", "reason", SAMPLE, ) .unwrap(); let mut install_exec = make_exec(runner.clone(), false); install_exec.root = root.path().to_path_buf(); install( &install_exec, root.path(), "app-misc/example", "1.0", &staged.digest, ) .unwrap(); let specs = runner.recorded(); let manifest = specs .iter() .position(|s| s.args.iter().any(|a| a == "manifest")); let emerge = specs .iter() .position(|s| s.args.iter().any(|a| a == "emerge")); assert!(manifest.is_some(), "manifest must be generated"); assert!(emerge.is_some(), "emerge must run"); assert!(manifest.unwrap() < emerge.unwrap(), "manifest before build"); // The build must enable Portage's sandbox. let build = specs .iter() .find(|s| s.args.iter().any(|a| a == "emerge")) .unwrap(); assert!(build .env .iter() .any(|(k, v)| k == "FEATURES" && v.contains("sandbox"))); } #[test] fn remove_unmerges_and_deletes_the_overlay_entry() { let exec = make_exec(RecordingRunner::new(), false); let root = tempfile::tempdir().unwrap(); prepare( &exec, root.path(), "app-misc/example", "1.0", "reason", SAMPLE, ) .unwrap(); remove(&exec, root.path(), "app-misc/example").unwrap(); assert!(!package_dir(root.path(), "app-misc/example") .unwrap() .exists()); assert!(staged(root.path(), "app-misc/example").is_none()); } #[test] fn dry_run_stages_nothing_and_runs_nothing() { let runner = RecordingRunner::new(); let exec = make_exec(runner.clone(), true); let root = tempfile::tempdir().unwrap(); let staged = prepare( &exec, root.path(), "app-misc/example", "1.0", "reason", SAMPLE, ) .unwrap(); assert!(!ebuild_path(root.path(), "app-misc/example", "1.0") .unwrap() .exists()); install( &exec, root.path(), "app-misc/example", "1.0", &staged.digest, ) .unwrap(); assert!(runner.recorded().is_empty()); } #[test] fn weird_atoms_cannot_escape_the_overlay() { let exec = make_exec(RecordingRunner::new(), false); let root = tempfile::tempdir().unwrap(); for atom in [ "../../etc/passwd", "a/b/c", "/bin/sh", "a//b", "../pkg", "app-misc/..", ".hidden/pkg", ] { assert!( prepare(&exec, root.path(), atom, "1.0", "r", SAMPLE).is_err(), "atom {atom} must be refused" ); } } #[test] fn helper_sha256_is_stable() { let _ = CommandOutput { status: 0, success: true, stdout: Vec::new(), stderr: Vec::new(), duration: Duration::ZERO, }; assert_eq!( crate::opencode::sha256_hex(b"abc"), "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad" ); } }