phoebus_os/installer-rs/crates/phoebus-executor/src/ebuild.rs
Phoebus 297f3201ff
Some checks are pending
ci / test (push) Waiting to run
feat(sys): hardware-aware lane selection and new lanes
Replace the fixed category routing (ADR 0006) with a shared, inspectable,
hardware- and preference-aware selection policy over resolved candidates from
Portage (source/binary/vendor), Nix, Flatpak, Snap, AppImage and the Phoebus
overlay. The policy keeps base components under Portage, separates hard
constraints from preferences, honours and persists explicit choices, errors
instead of silently switching lanes, and reuses an already-installed lane.

- phoebus-core::selection: the pure policy (16 tests: base-system, low-memory
  vs high-core, sandbox requirement, GPU/arch/storage rejection, explicit
  preference, unavailable backend, reproducibility, render).
- phoebus-executor::chooser: resolves real metadata and hardware facts.
- phoebus-executor::{snap,appimage,ebuild}: new lanes. Snap detects daemon and
  confinement and installs app-containers/snapd through Portage; AppImage
  adopts images with a pinned SHA-256, checks the ELF architecture without
  executing, integrates a desktop entry and preserves user data on removal; the
  custom ebuild overlay binds approval to the ebuild content digest and builds
  through Portage's sandbox.
- Typed actions choose_package / set_package_preference / snap_* / appimage_* /
  custom_ebuild_* with strict validators; the assistant prompt and schema are
  reconciled (no category routing; custom ebuilds are untrusted).
- Installed sys: the installer locates the trusted static binary, copies it to
  /usr/local/bin/sys and proves it runs in the target chroot before the
  recovery snapshot, failing closed if absent; the VM harness fetches sys.
- docs/SYS.md: command/action reference and acceptance matrix; ADR 0006 revised.

Host gates pass: fmt, clippy (no new warnings), workspace tests, make test,
release and static sys builds. VM lane journeys remain pending (see HANDOFF).
2026-09-23 18:35:26 -07:00

559 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> {
let (category, package) = atom.split_once('/').ok_or_else(|| {
ExecError::operation(
"ebuild",
"resolve overlay path",
"atom must be category/package",
)
})?;
if category.is_empty() || package.is_empty() {
return Err(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"] {
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"
);
}
}