phoebus_os/installer-rs/crates/phoebus-executor/src/ebuild.rs
2026-09-28 23:42:34 -07:00

569 lines
18 KiB
Rust

//! 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<PathBuf> {
// 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<PathBuf> {
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<StagedEbuild> {
// 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<PathBuf> {
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<StagedEbuild> {
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<StagedEbuild> {
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::<StagedEbuild>(&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"
);
}
}