phoebus_os/installer-rs/crates/phoebus-executor/src/overlay.rs
Phoebus 67fddf1299
Some checks are pending
ci / test (push) Waiting to run
feat(sys): review and enable scoped external overlays
2026-10-03 15:06:34 -07:00

525 lines
17 KiB
Rust

//! Review and registration of one package from an external Portage repository.
//! GPO supplies leads; Gentoo's repository registry supplies the source URL.
//! Neither listing is an endorsement or a substitute for reviewing the ebuild.
use std::path::Path;
use phoebus_core::action::OverlayReview;
use phoebus_core::TargetRoot;
use sha2::{Digest, Sha256};
use crate::command::{CommandOutput, CommandSpec};
use crate::error::{ExecError, Result};
use crate::exec::Exec;
const REGISTRY: &str = "https://api.gentoo.org/overlays/repositories.xml";
const MAX_REGISTRY: usize = 512 * 1024;
const MAX_GPO: usize = 512 * 1024;
fn error(operation: &str, reason: impl Into<String>) -> ExecError {
ExecError::operation("overlay", operation, reason.into())
}
pub fn valid_atom(atom: &str) -> bool {
let Some((category, package)) = atom.split_once('/') else {
return false;
};
[category, package].iter().all(|part| {
!part.is_empty()
&& part.len() <= 80
&& !part.starts_with('-')
&& !part.contains("..")
&& part
.bytes()
.all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b"+_.-".contains(&b))
})
}
fn valid_repository(name: &str) -> bool {
!name.is_empty()
&& name.len() <= 80
&& !name.starts_with('-')
&& !name.contains("..")
&& name
.bytes()
.all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b"+_.-".contains(&b))
}
fn valid_source(source: &str) -> bool {
source.starts_with("https://")
&& source.len() <= 256
&& !source.contains(['@', '?', '#', '\n', '\r', ' ', '\\'])
&& !source.contains("..")
&& source[8..].contains('/')
}
fn capture(exec: &Exec, operation: &str, program: &str, args: &[&str]) -> Result<CommandOutput> {
exec.run_capture(CommandSpec::new("overlay", operation, program).args(args.iter().copied()))
}
fn fetch(exec: &Exec, url: &str, limit: usize) -> Result<String> {
let limit_text = limit.to_string();
let out = capture(
exec,
"read external overlay metadata",
"curl",
&[
"--fail",
"--silent",
"--show-error",
"--proto",
"=https",
"--proto-redir",
"=https",
"--connect-timeout",
"3",
"--max-time",
"12",
"--max-filesize",
&limit_text,
url,
],
)?;
if !out.success || out.stdout.len() > limit {
return Err(error(
"fetch",
"external metadata could not be read within limits",
));
}
String::from_utf8(out.stdout).map_err(|_| error("fetch", "external metadata is not UTF-8"))
}
fn gpo_repositories(html: &str) -> Vec<String> {
let mut names: Vec<String> = html
.split("href=\"/Overlays/")
.skip(1)
.filter_map(|part| part.split_once('"').map(|(name, _)| name.to_string()))
.filter(|name| valid_repository(name))
.collect();
names.sort();
names.dedup();
names.truncate(12);
names
}
fn registry_source(xml: &str, name: &str) -> Result<(String, String)> {
// Gentoo declares an external DTD for this file. We need no DTD features;
// remove only that exact declaration and keep entity processing disabled.
let without_dtd = xml.replace(
"<!DOCTYPE repositories SYSTEM \"https://www.gentoo.org/dtd/repositories.dtd\">",
"",
);
let document = roxmltree::Document::parse(&without_dtd)
.map_err(|e| error("parse Gentoo overlay registry", e.to_string()))?;
for repo in document.descendants().filter(|n| n.has_tag_name("repo")) {
if repo
.children()
.find(|n| n.has_tag_name("name"))
.and_then(|n| n.text())
!= Some(name)
{
continue;
}
let source = repo
.children()
.filter(|n| n.has_tag_name("source") && n.attribute("type") == Some("git"))
.filter_map(|n| n.text())
.find(|s| valid_source(s))
.ok_or_else(|| error("registry lookup", "no HTTPS Git source in registry"))?;
return Ok((
source.to_string(),
repo.attribute("quality").unwrap_or("unrated").to_string(),
));
}
Err(error(
"registry lookup",
format!("{name} is absent from Gentoo's overlay registry"),
))
}
fn git_capture(exec: &Exec, operation: &str, args: &[&str]) -> Result<String> {
let spec = CommandSpec::new("overlay", operation, "timeout")
.args(["40s", "git"])
.args(args.iter().copied())
.env("GIT_TERMINAL_PROMPT", "0")
.env("GIT_CONFIG_GLOBAL", "/dev/null")
.env("GIT_CONFIG_SYSTEM", "/dev/null")
.env("GIT_LFS_SKIP_SMUDGE", "1")
.env("GIT_HTTP_LOW_SPEED_LIMIT", "1024")
.env("GIT_HTTP_LOW_SPEED_TIME", "10");
let out = exec.run_capture(spec)?;
if !out.success || out.stdout.len() > 256 * 1024 {
return Err(error(
operation,
"Git inspection failed or returned too much data",
));
}
String::from_utf8(out.stdout).map_err(|_| error(operation, "Git output is not UTF-8"))
}
fn inspect_repository(
exec: &Exec,
atom: &str,
repository: &str,
source: &str,
quality: &str,
) -> Result<OverlayReview> {
let temporary = tempfile::tempdir().map_err(|e| error("temporary review", e.to_string()))?;
let path = temporary.path().join("repository");
let path_text = path.to_string_lossy().to_string();
git_capture(
exec,
"clone repository for review",
&[
"-c",
"protocol.file.allow=never",
"-c",
"http.followRedirects=false",
"clone",
"--quiet",
"--depth=1",
"--filter=blob:none",
"--no-checkout",
"--",
source,
&path_text,
],
)?;
let commit = git_capture(
exec,
"read repository revision",
&["-C", &path_text, "rev-parse", "HEAD"],
)?
.trim()
.to_string();
if commit.len() != 40 || !commit.bytes().all(|b| b.is_ascii_hexdigit()) {
return Err(error("read repository revision", "invalid Git commit"));
}
let repo_name = git_capture(
exec,
"check repository identity",
&["-C", &path_text, "show", "HEAD:profiles/repo_name"],
)?;
if repo_name.trim() != repository {
return Err(error(
"check repository identity",
"repository name differs from registry name",
));
}
let paths = git_capture(
exec,
"find exact package ebuilds",
&[
"-C",
&path_text,
"ls-tree",
"-r",
"--name-only",
"HEAD",
atom,
],
)?;
let prefix = format!("{atom}/");
let package = atom.rsplit('/').next().unwrap_or("");
let ebuilds: Vec<&str> = paths
.lines()
.filter(|p| p.starts_with(&prefix) && p.ends_with(".ebuild"))
.filter(|p| {
p.rsplit('/')
.next()
.unwrap_or("")
.starts_with(&format!("{package}-"))
})
.filter(|p| !p.ends_with("-9999.ebuild"))
.filter(|p| {
p.bytes()
.all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b"/+_.-".contains(&b))
})
.collect();
let sorted = exec.run_capture(
CommandSpec::new("overlay", "choose latest non-live ebuild", "sort")
.arg("-V")
.stdin(ebuilds.join("\n")),
)?;
let sorted = String::from_utf8(sorted.stdout)
.map_err(|_| error("choose ebuild", "version sort output is not UTF-8"))?;
let ebuild = sorted
.lines()
.last()
.ok_or_else(|| {
error(
"find package",
format!("{atom} has no ebuild in {repository}"),
)
})?
.to_string();
let content = git_capture(
exec,
"inspect exact ebuild",
&["-C", &path_text, "show", &format!("HEAD:{ebuild}")],
)?;
let keywords = content
.lines()
.find_map(|line| line.trim().strip_prefix("KEYWORDS="))
.map(|s| s.trim().trim_matches(['\'', '"']).to_string())
.ok_or_else(|| error("check architecture", "ebuild has no static KEYWORDS line"))?;
let supported: Vec<&str> = keywords.split_whitespace().collect();
let needs_keyword = if supported.contains(&"amd64") {
false
} else if supported.contains(&"~amd64") {
true
} else {
return Err(error("check architecture", "ebuild does not keyword amd64"));
};
let hash = format!("{:x}", Sha256::digest(content.as_bytes()));
let manifest_present = paths.lines().any(|p| p == format!("{atom}/Manifest"));
if !manifest_present {
return Err(error(
"check Manifest",
"package has no Manifest for distfile checks",
));
}
Ok(OverlayReview {
atom: atom.to_string(),
repository: repository.to_string(),
source: source.to_string(),
commit,
ebuild,
ebuild_sha256: hash,
keywords,
needs_keyword,
registry_quality: quality.to_string(),
manifest_present,
})
}
/// Discover exact, architecture-compatible options. Each repository is
/// inspected independently; one broken lead cannot hide a usable option.
pub fn discover(exec: &Exec, root: &Path, atom: &str) -> Result<Vec<OverlayReview>> {
if root != Path::new("/") {
return Err(error(
"discover",
"external overlay review requires the running system",
));
}
if !valid_atom(atom) {
return Err(error("discover", "expected an exact category/package atom"));
}
let gpo = fetch(exec, &format!("https://gpo.zugaina.org/{atom}"), MAX_GPO)?;
let names = gpo_repositories(&gpo);
if names.is_empty() {
return Err(error("discover", "GPO lists no repositories for this atom"));
}
let registry = fetch(exec, REGISTRY, MAX_REGISTRY)?;
let mut reviews = Vec::new();
let mut rejected = Vec::new();
for name in names {
match registry_source(&registry, &name)
.and_then(|(source, quality)| inspect_repository(exec, atom, &name, &source, &quality))
{
Ok(review) => reviews.push(review),
Err(reason) => rejected.push(format!("{name}: {reason}")),
}
}
if reviews.is_empty() {
return Err(error(
"discover",
format!(
"no listed repository passed identity, ebuild and amd64 checks: {}",
rejected.join("; ")
),
));
}
reviews.sort_by(|a, b| a.repository.cmp(&b.repository));
Ok(reviews)
}
/// Re-discover at the privileged boundary and refuse a changed source or
/// ebuild. The selected option is bound by the approved plan digest.
pub fn enable(
exec: &Exec,
_auth: &crate::auth::DestructiveAuthorization,
root: &Path,
selected: &OverlayReview,
) -> Result<String> {
if root != Path::new("/") {
return Err(error(
"enable",
"external overlays can only be enabled on the running system",
));
}
let current = discover(exec, root, &selected.atom)?
.into_iter()
.find(|r| r.repository == selected.repository)
.ok_or_else(|| error("enable", "reviewed repository is no longer available"))?;
if &current != selected {
return Err(error(
"enable",
"repository or ebuild changed since approval; review again",
));
}
let target = TargetRoot::new(root);
let repo_rel = format!("var/db/repos/{}", selected.repository);
let repo_path = target.resolve(&repo_rel)?;
let conf_rel = format!(
"etc/portage/repos.conf/phoebus-{}.conf",
selected.repository
);
let conf_path = target.resolve(&conf_rel)?;
if repo_path.exists() || conf_path.exists() {
return Err(error(
"enable",
"repository or Phoebus configuration already exists",
));
}
target.ensure_dir("var/db/repos")?;
let repo_path_text = repo_path.to_string_lossy().to_string();
git_capture(
exec,
"add reviewed repository",
&[
"-c",
"protocol.file.allow=never",
"-c",
"http.followRedirects=false",
"clone",
"--quiet",
"--depth=1",
"--filter=blob:none",
"--",
&selected.source,
&repo_path_text,
],
)?;
let actual = git_capture(
exec,
"verify added revision",
&["-C", &repo_path_text, "rev-parse", "HEAD"],
)?;
if actual.trim() != selected.commit {
return Err(error(
"enable",
"repository changed while cloning; configuration was not written",
));
}
write_policy(&target, selected)?;
crate::portage::normalize_config_permissions(root);
Ok(format!(
"enabled {} at {} for {} only; normal Portage syncs will update the repository. Install the package through a separate reviewed `sys install` plan.",
selected.repository, selected.commit, selected.atom
))
}
fn write_policy(target: &TargetRoot, selected: &OverlayReview) -> Result<()> {
// The entire repository is masked; only the approved atom can be selected.
// Normal Portage syncs update this repository because auto-sync is enabled.
let conf = format!(
"[{}]\nlocation = /var/db/repos/{}\nsync-type = git\nsync-uri = {}\nauto-sync = yes\n",
selected.repository, selected.repository, selected.source
);
target.write(
&format!("etc/portage/package.mask/phoebus-{}", selected.repository),
format!(
"# Only the reviewed {} may be selected from this repository.\n*/*::{}\n",
selected.atom, selected.repository
),
)?;
target.write(
&format!("etc/portage/package.unmask/phoebus-{}", selected.repository),
format!("{}::{}\n", selected.atom, selected.repository),
)?;
if selected.needs_keyword {
target.write(
&format!(
"etc/portage/package.accept_keywords/phoebus-{}",
selected.repository
),
format!("{}::{} ~amd64\n", selected.atom, selected.repository),
)?;
}
// Register last. An interruption before this write leaves inert policy
// files; it cannot expose an unrestricted external repository to Portage.
target.write(
&format!(
"etc/portage/repos.conf/phoebus-{}.conf",
selected.repository
),
conf,
)?;
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn rejects_unsafe_identity_and_source() {
assert!(valid_atom("app-misc/chatgpt-desktop"));
assert!(!valid_atom("app-misc/../../evil"));
assert!(!valid_repository("../evil"));
assert!(valid_source("https://github.com/gentoo-zh/overlay.git"));
assert!(!valid_source("https://user@host/repo.git"));
}
#[test]
fn parses_registry_and_gpo_leads() {
let xml = r#"<repositories><repo quality="experimental"><name>gentoo-zh</name><source type="git">https://github.com/gentoo-zh/overlay.git</source></repo></repositories>"#;
assert_eq!(
registry_source(xml, "gentoo-zh").unwrap(),
(
"https://github.com/gentoo-zh/overlay.git".into(),
"experimental".into()
)
);
assert_eq!(
gpo_repositories(
"<a href=\"/Overlays/gentoo-zh\">x</a><a href=\"/Overlays/../bad\">y</a>"
),
vec!["gentoo-zh"]
);
}
#[test]
fn policy_masks_the_repository_and_scopes_testing_keyword() {
let temp = tempfile::tempdir().unwrap();
let target = TargetRoot::new(temp.path());
let review = OverlayReview {
atom: "app-misc/chatgpt-desktop".into(),
repository: "gentoo-zh".into(),
source: "https://github.com/gentoo-zh/overlay.git".into(),
commit: "a".repeat(40),
ebuild: "app-misc/chatgpt-desktop/chatgpt-desktop-1.ebuild".into(),
ebuild_sha256: "b".repeat(64),
keywords: "-* ~amd64".into(),
needs_keyword: true,
registry_quality: "experimental".into(),
manifest_present: true,
};
write_policy(&target, &review).unwrap();
let mask = std::fs::read_to_string(
temp.path()
.join("etc/portage/package.mask/phoebus-gentoo-zh"),
)
.unwrap();
let unmask = std::fs::read_to_string(
temp.path()
.join("etc/portage/package.unmask/phoebus-gentoo-zh"),
)
.unwrap();
let keywords = std::fs::read_to_string(
temp.path()
.join("etc/portage/package.accept_keywords/phoebus-gentoo-zh"),
)
.unwrap();
let conf = std::fs::read_to_string(
temp.path()
.join("etc/portage/repos.conf/phoebus-gentoo-zh.conf"),
)
.unwrap();
assert!(mask.contains("*/*::gentoo-zh"));
assert_eq!(unmask, "app-misc/chatgpt-desktop::gentoo-zh\n");
assert_eq!(keywords, "app-misc/chatgpt-desktop::gentoo-zh ~amd64\n");
assert!(conf.contains("auto-sync = yes"));
}
}