Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
Python agentagent-osaiai-agentsai-partnerchatopsclaudeclaude-codecodexdevtoolsdiscord-botlark-botllmlocal-firstlong-term-memoryopencodeslack-botvibe-codingvibeywechat
//! Verification and atomic installation of the app-private Avibe Runtime.
//!
//! Product packages carry one target-specific ZIP plus an embedded manifest.
//! Production trust comes from the desktop application's code signature; the
//! installer or first launch verifies the archive before extracting it into a
//! versioned user-data directory. The application bundle is never mutated, and an update
//! can install a successor without replacing files used by a running daemon.
use std::ffi::OsStr;
use std::fs::{self, File, OpenOptions};
use std::io::{self, Read, Write};
use std::path::{Component, Path, PathBuf};
use std::sync::atomic::{AtomicU64, Ordering};
use crate::hashing::{lower_hex, update_from_reader};
use serde::{Deserialize, Serialize};
use sha2::{Digest, Sha256};
use zip::ZipArchive;
const MANIFEST_NAME: &str = "runtime-manifest.json";
const INSTALL_MARKER_NAME: &str = ".avibe-runtime.json";
const MAX_MANIFEST_BYTES: u64 = 32 * 1024;
const MAX_ARCHIVE_BYTES: u64 = 1024 * 1024 * 1024;
const MAX_UNPACKED_BYTES: u64 = 2 * 1024 * 1024 * 1024;
const MAX_ARCHIVE_ENTRIES: u64 = 200_000;
const TREE_HASH_DOMAIN: &[u8] = b"avibe-runtime-tree-v1\0";
const REPAIR_SLOT_SUFFIX: &str = "-repair";
/// The directory inside the install root that holds every Runtime tree, and
/// the staging and discarded copies on their way in and out.
///
/// On macOS its name ends in `.noindex`, which keeps Spotlight out of the
/// whole subtree. Spotlight otherwise imports each of a new tree's ~31k files
/// for minutes after an install or update, and its importer pushes the tree
/// out of the page cache as it goes. Every launch hashes the whole tree before
/// it runs any of it, so a launch in those minutes reads the tree back from
/// disk instead of memory (#2283). macOS 26 still honours the suffix; a
/// `.metadata_never_index` file inside the directory is ignored.
///
/// Windows keeps its trees directly in the install root. The suffix means
/// nothing there, and the extra level would cost path length the tree does
/// not have: its deepest entry is 168 characters, which already brings a
/// typical profile's absolute path within about ten characters of `MAX_PATH`.
#[cfg(target_os = "macos")]
const TREES_DIR_NAME: Option<&str> = Some("trees.noindex");
#[cfg(not(target_os = "macos"))]
const TREES_DIR_NAME: Option<&str> = None;
static INSTALL_SEQUENCE: AtomicU64 = AtomicU64::new(0);
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct RuntimeBundleManifest {
pub schema_version: u32,
pub runtime_version: String,
pub os: String,
pub arch: String,
pub archive: String,
pub archive_sha256: String,
pub archive_size: u64,
pub unpacked_size: u64,
pub entry_count: u64,
pub tree_sha256: String,
pub python_entrypoint: String,
pub node_entrypoint: String,
pub npm_entrypoint: String,
pub python_distribution: RuntimeSource,
pub node_distribution: RuntimeSource,
pub npm_version: String,
pub avibe_wheel: RuntimeArtifact,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct RuntimeSource {
pub url: String,
pub sha256: String,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct RuntimeArtifact {
pub name: String,
pub sha256: String,
}
#[derive(Debug, thiserror::Error)]
pub enum PrivateRuntimeError {
#[error("the bundled Runtime manifest is unavailable")]
ManifestUnavailable(#[source] io::Error),
#[error("the bundled Runtime manifest is invalid")]
ManifestInvalid,
#[error("the bundled Runtime targets another platform")]
TargetMismatch,
#[error("the bundled Runtime archive is unavailable")]
ArchiveUnavailable(#[source] io::Error),
#[error("the bundled Runtime archive failed verification")]
ArchiveVerification,
#[error("the bundled Runtime archive is invalid")]
ArchiveInvalid,
#[error("the private Runtime could not be installed")]
Install(#[source] io::Error),
/// A link or a file where the installer needs its own directory. Replacing
/// it with a real directory is enough: the installer re-creates what the
/// directory holds.
#[error("{0} is a link or a file, not a directory the private Runtime owns")]
NotARealDirectory(PathBuf),
}
#[derive(Debug, Clone)]
pub struct InstalledPrivateRuntime {
pub root: PathBuf,
pub python: PathBuf,
pub node: PathBuf,
pub npm_cli: PathBuf,
pub runtime_id: String,
/// True when `prepare()` found this tree already installed and valid.
///
/// False means this launch paid to extract it. The distinction is invisible
/// to the user and decides how long the first Runtime call will take, so it
/// is the fact the bootstrap log exists to record: an install that reports
/// `extracted` on every launch is invalidating itself between launches.
pub reused: bool,
}
#[derive(Debug, Clone)]
pub struct PrivateRuntimeBundle {
bundle_dir: PathBuf,
install_root: PathBuf,
/// Where trees are installed: `install_root` itself, or its
/// [`TREES_DIR_NAME`] directory.
trees_root: PathBuf,
}
/// Prepare the Windows installer's adjacent bundle in the shell's app-data root.
///
/// Both paths come from the installed executable and OS directory lookup, never
/// command-line arguments. This shares the lazy launcher's verification and slot
/// lifecycle, but never prunes superseded slots or starts a Runtime.
pub fn prepare_installed_runtime(
executable: &Path,
app_local_data_dir: &Path,
) -> Result<InstalledPrivateRuntime, PrivateRuntimeError> {
let resource_dir = executable.parent().filter(|path| path.is_absolute()).ok_or_else(|| {
PrivateRuntimeError::Install(io::Error::new(
io::ErrorKind::InvalidInput,
"invalid executable directory",
))
})?;
if !app_local_data_dir.is_absolute() {
return Err(PrivateRuntimeError::Install(io::Error::new(
io::ErrorKind::InvalidInput,
"invalid application data directory",
)));
}
PrivateRuntimeBundle::new(resource_dir.join("runtime"), app_local_data_dir.join("runtime")).prepare()
}
impl PrivateRuntimeBundle {
pub fn new(bundle_dir: PathBuf, install_root: PathBuf) -> Self {
let trees_root = TREES_DIR_NAME.map_or_else(|| install_root.clone(), |name| install_root.join(name));
Self {
bundle_dir,
install_root,
trees_root,
}
}
pub fn prepare(&self) -> Result<InstalledPrivateRuntime, PrivateRuntimeError> {
let manifest = self.read_manifest()?;
validate_manifest(&manifest)?;
let digest_prefix = manifest
.archive_sha256
.get(..16)
.ok_or(PrivateRuntimeError::ManifestInvalid)?;
let version_dir = self.trees_root.join(&manifest.runtime_version);
// Everything below reads, writes and deletes inside these three, so
// none of them may be a link to somewhere else.
for directory in [&self.install_root, &self.trees_root, &version_dir] {
own_directory(directory)?;
}
let [primary_dir, repair_dir] = install_slots(&version_dir, digest_prefix);
for candidate in [&primary_dir, &repair_dir] {
if path_present(candidate) {
if let Ok(runtime) = installed_runtime(candidate, &manifest) {
return Ok(InstalledPrivateRuntime {
reused: true,
..runtime
});
}
}
}
let archive_path = self.bundle_dir.join(&manifest.archive);
verify_archive(&archive_path, &manifest)?;
// Both independently installed copies failing integrity validation is
// not a dead end: the verified archive is reinstalled over the primary
// name. A daemon may still be running from that copy, since a tree that
// fails validation may only have gained files after it started, so the
// name is freed only once its replacement is fully verified (below).
let replaces_primary = path_present(&primary_dir) && path_present(&repair_dir);
let install_dir = if !path_present(&primary_dir) || replaces_primary {
primary_dir
} else {
repair_dir
};
let sequence = INSTALL_SEQUENCE.fetch_add(1, Ordering::SeqCst);
let staging = self
.trees_root
.join(format!(".install-{}-{sequence}", std::process::id()));
if staging.exists() {
fs::remove_dir_all(&staging).map_err(PrivateRuntimeError::Install)?;
}
fs::create_dir(&staging).map_err(PrivateRuntimeError::Install)?;
let install_result = (|| {
extract_archive(&archive_path, &staging, &manifest)?;
validate_runtime_files(&staging, &manifest)?;
verify_installed_tree(&staging, &manifest)?;
write_marker(&staging, &manifest)?;
if replaces_primary {
discard_install_path(&self.trees_root, &install_dir)?;
}
match fs::rename(&staging, &install_dir) {
Ok(()) => {}
Err(error) => {
// Windows and Unix report different error kinds when
// another process wins this content-addressed install.
// Accept the race only after validating the winner.
if installed_runtime(&install_dir, &manifest).is_ok() {
fs::remove_dir_all(&staging).map_err(PrivateRuntimeError::Install)?;
} else {
return Err(PrivateRuntimeError::Install(error));
}
}
}
installed_runtime(&install_dir, &manifest)
})();
if staging.exists() {
let _ = fs::remove_dir_all(&staging);
}
install_result
}
/// Hashes a reused install slot in full and withdraws it if it no longer
/// matches the manifest.
///
/// `prepare()` reuses a slot from metadata alone, so a change metadata cannot
/// see would otherwise be served on every launch. This repeats the check a
/// launch used to run inline, meant for a background thread while the
/// Runtime starts. A failing slot loses its marker. The daemon that may be
/// running from it is untouched, because nothing it executes is removed. The
/// next `prepare()` then treats the slot as invalid and reinstalls the
/// verified archive, by the same repair path as a slot rejected inline.
pub fn audit(&self, root: &Path) -> Result<(), PrivateRuntimeError> {
let manifest = self.read_manifest()?;
validate_manifest(&manifest)?;
let digest_prefix = manifest
.archive_sha256
.get(..16)
.ok_or(PrivateRuntimeError::ManifestInvalid)?;
let version_dir = self.trees_root.join(&manifest.runtime_version);
if !install_slots(&version_dir, digest_prefix)
.iter()
.any(|slot| slot == root)
{
return Err(PrivateRuntimeError::Install(io::Error::new(
io::ErrorKind::InvalidInput,
"audited Runtime is not an install slot of the bundled manifest",
)));
}
let verified = verify_installed_tree(root, &manifest);
if verified.is_err() {
match fs::remove_file(root.join(INSTALL_MARKER_NAME)) {
Ok(()) => {}
Err(error) if error.kind() == io::ErrorKind::NotFound => {}
Err(error) => return Err(PrivateRuntimeError::Install(error)),
}
}
verified
}
/// Removes private Runtime trees that are no longer used by the active
/// desktop-managed daemon.
///
/// The caller invokes this only after `/ready` proves that the Runtime id of
/// `active_root` is the one serving the desktop shell. Cleanup is
/// deliberately outside `prepare`: an older daemon may still have its
/// executable tree open while the successor is being installed.
///
/// `/ready` proves the id, not the slot. Both slots of one id hold the same
/// archive, and `vibe start` keeps a live daemon rather than restarting it,
/// so a daemon started from the primary can still be serving after this
/// launch resolved the repair slot. Both slots of the served id are
/// therefore kept; every other version and digest is removed.
///
/// Releases before [`TREES_DIR_NAME`] installed trees directly in the
/// install root. Those are superseded by the same rule: whatever is not a
/// slot of the served id goes.
pub fn prune_superseded(&self, active_root: &Path) -> Result<(), PrivateRuntimeError> {
let outside_root = || {
PrivateRuntimeError::Install(io::Error::new(
io::ErrorKind::InvalidInput,
"active Runtime is outside the private install root",
))
};
let active_version = active_root
.parent()
.filter(|parent| parent.parent() == Some(self.trees_root.as_path()))
.and_then(Path::file_name)
.ok_or_else(outside_root)?;
let active_slot = active_root
.file_name()
.and_then(|name| name.to_str())
.ok_or_else(outside_root)?;
let digest_prefix = active_slot.strip_suffix(REPAIR_SLOT_SUFFIX).unwrap_or(active_slot);
// The trees root is reached through the install root, and a link there
// would point the deletions below at whatever it names.
if !real_directory(&self.install_root)? {
return Ok(());
}
prune_trees(&self.trees_root, active_version, digest_prefix, None)?;
if self.trees_root != self.install_root {
prune_trees(
&self.install_root,
active_version,
digest_prefix,
Some(&self.trees_root),
)?;
}
Ok(())
}
/// Removes every app-private Runtime install while leaving Avibe user state
/// untouched. The caller must first complete a graceful `vibe stop`.
pub fn remove_all(&self) -> Result<(), PrivateRuntimeError> {
if !real_directory(&self.install_root)? {
return Ok(());
}
fs::remove_dir_all(&self.install_root).map_err(PrivateRuntimeError::Install)
}
fn read_manifest(&self) -> Result<RuntimeBundleManifest, PrivateRuntimeError> {
let path = self.bundle_dir.join(MANIFEST_NAME);
let file = File::open(path).map_err(PrivateRuntimeError::ManifestUnavailable)?;
let mut bytes = Vec::new();
file.take(MAX_MANIFEST_BYTES + 1)
.read_to_end(&mut bytes)
.map_err(PrivateRuntimeError::ManifestUnavailable)?;
if bytes.len() > MAX_MANIFEST_BYTES as usize {
return Err(PrivateRuntimeError::ManifestInvalid);
}
serde_json::from_slice(&bytes).map_err(|_| PrivateRuntimeError::ManifestInvalid)
}
}
fn validate_manifest(manifest: &RuntimeBundleManifest) -> Result<(), PrivateRuntimeError> {
if manifest.schema_version != 2
|| !safe_segment(&manifest.runtime_version)
|| !safe_file_name(&manifest.archive)
|| !valid_sha256(&manifest.archive_sha256)
|| manifest.archive_size == 0
|| manifest.archive_size > MAX_ARCHIVE_BYTES
|| manifest.unpacked_size == 0
|| manifest.unpacked_size > MAX_UNPACKED_BYTES
|| manifest.entry_count == 0
|| manifest.entry_count > MAX_ARCHIVE_ENTRIES
|| !valid_sha256(&manifest.tree_sha256)
|| !valid_relative_path(&manifest.python_entrypoint)
|| !valid_relative_path(&manifest.node_entrypoint)
|| !valid_relative_path(&manifest.npm_entrypoint)
|| !valid_sha256(&manifest.python_distribution.sha256)
|| !valid_sha256(&manifest.node_distribution.sha256)
|| !valid_sha256(&manifest.avibe_wheel.sha256)
|| manifest.python_distribution.url.is_empty()
|| manifest.node_distribution.url.is_empty()
|| manifest.npm_version.is_empty()
|| !safe_file_name(&manifest.avibe_wheel.name)
{
return Err(PrivateRuntimeError::ManifestInvalid);
}
if manifest.os != current_os() || manifest.arch != current_arch() {
return Err(PrivateRuntimeError::TargetMismatch);
}
Ok(())
}
fn current_os() -> &'static str {
std::env::consts::OS
}
fn current_arch() -> &'static str {
std::env::consts::ARCH
}
fn safe_segment(value: &str) -> bool {
!value.is_empty()
&& value.len() <= 128
&& value
.bytes()
.all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'.' | b'_' | b'+' | b'-'))
}
fn safe_file_name(value: &str) -> bool {
safe_segment(value) && Path::new(value).file_name().is_some_and(|name| name == value)
}
fn valid_sha256(value: &str) -> bool {
value.len() == 64
&& value
.bytes()
.all(|byte| byte.is_ascii_hexdigit() && !byte.is_ascii_uppercase())
}
fn valid_relative_path(value: &str) -> bool {
let path = Path::new(value);
!value.is_empty()
&& !path.is_absolute()
&& path
.components()
.all(|component| matches!(component, Component::Normal(_)))
}
fn path_present(path: &Path) -> bool {
fs::symlink_metadata(path).is_ok()
}
/// The primary and repair install slots of one archive digest.
fn install_slots(version_dir: &Path, digest_prefix: &str) -> [PathBuf; 2] {
[
version_dir.join(digest_prefix),
version_dir.join(format!("{digest_prefix}{REPAIR_SLOT_SUFFIX}")),
]
}
/// Moves an installed copy aside so its name can take a verified replacement.
///
/// Deleting in place is what this avoids. `remove_dir_all` on a tree a running
/// Runtime is executing from succeeds on Unix and fails partway through on
/// Windows, where a mapped executable cannot be unlinked — and a half-deleted
/// tree under a live process is a worse state than the invalid one it replaced.
/// A rename either moves the whole thing or moves none of it. On Unix the open
/// handles a daemon holds keep working across it, and because the caller
/// renames the replacement in immediately, the daemon's later lookups by path
/// find the same verified bytes. On Windows the rename of a tree in use fails,
/// so nothing is moved or deleted and the launch reports the verification
/// failure it reported before this was recoverable.
///
/// The discarded copy is then removed on a best-effort basis: it is already
/// unreachable by name, and `prune_superseded` sweeps whatever is left after
/// the next successful launch.
fn discard_install_path(trees_root: &Path, path: &Path) -> Result<(), PrivateRuntimeError> {
let sequence = INSTALL_SEQUENCE.fetch_add(1, Ordering::SeqCst);
let discarded = trees_root.join(format!(".discard-{}-{sequence}", std::process::id()));
// A machine that cannot even rename the directory reports what it reported
// before this became recoverable, rather than pretending it installed.
fs::rename(path, &discarded).map_err(|_| PrivateRuntimeError::ArchiveVerification)?;
let _ = fs::remove_dir_all(&discarded);
Ok(())
}
/// Whether `path` is a directory itself, not a link to one. Absent is `false`;
/// anything else there is an error, so a caller about to write or delete inside
/// a directory never follows a link out of the private install.
fn real_directory(path: &Path) -> Result<bool, PrivateRuntimeError> {
match fs::symlink_metadata(path) {
Ok(metadata) if metadata.file_type().is_dir() => Ok(true),
Ok(_) => Err(PrivateRuntimeError::NotARealDirectory(path.to_owned())),
Err(error) if error.kind() == io::ErrorKind::NotFound => Ok(false),
Err(error) => Err(PrivateRuntimeError::Install(error)),
}
}
/// Creates `path` if it is absent and requires it to be a real directory.
///
/// Its ancestors are not checked: above the install root they belong to the
/// user and the system, and below it each level is owned on the way down.
fn own_directory(path: &Path) -> Result<(), PrivateRuntimeError> {
if !real_directory(path)? {
fs::create_dir_all(path).map_err(PrivateRuntimeError::Install)?;
if !real_directory(path)? {
return Err(PrivateRuntimeError::NotARealDirectory(path.to_owned()));
}
}
Ok(())
}
/// Removes every entry of `root` except the two slots of the served id and
/// `keep`.
fn prune_trees(
root: &Path,
active_version: &OsStr,
digest_prefix: &str,
keep: Option<&Path>,
) -> Result<(), PrivateRuntimeError> {
if !real_directory(root)? {
return Ok(());
}
let active_version = root.join(active_version);
let served_slots = install_slots(&active_version, digest_prefix);
for entry in fs::read_dir(root).map_err(PrivateRuntimeError::Install)? {
let path = entry.map_err(PrivateRuntimeError::Install)?.path();
if keep == Some(path.as_path()) {
continue;
}
if path == active_version {
if !real_directory(&path)? {
continue;
}
for candidate in fs::read_dir(&path).map_err(PrivateRuntimeError::Install)? {
let candidate = candidate.map_err(PrivateRuntimeError::Install)?.path();
if !served_slots.contains(&candidate) {
remove_install_path(&candidate)?;
}
}
} else {
remove_install_path(&path)?;
}
}
Ok(())
}
fn remove_install_path(path: &Path) -> Result<(), PrivateRuntimeError> {
let metadata = fs::symlink_metadata(path).map_err(PrivateRuntimeError::Install)?;
if metadata.file_type().is_dir() && !metadata.file_type().is_symlink() {
fs::remove_dir_all(path).map_err(PrivateRuntimeError::Install)
} else {
fs::remove_file(path).map_err(PrivateRuntimeError::Install)
}
}
fn verify_archive(path: &Path, manifest: &RuntimeBundleManifest) -> Result<(), PrivateRuntimeError> {
let metadata = fs::metadata(path).map_err(PrivateRuntimeError::ArchiveUnavailable)?;
if !metadata.is_file() || metadata.len() != manifest.archive_size {
return Err(PrivateRuntimeError::ArchiveVerification);
}
let mut file = File::open(path).map_err(PrivateRuntimeError::ArchiveUnavailable)?;
let mut hasher = Sha256::new();
update_from_reader(&mut hasher, &mut file).map_err(PrivateRuntimeError::ArchiveUnavailable)?;
let actual = lower_hex(&hasher.finalize());
if actual != manifest.archive_sha256 {
return Err(PrivateRuntimeError::ArchiveVerification);
}
Ok(())
}
fn extract_archive(
archive_path: &Path,
destination: &Path,
manifest: &RuntimeBundleManifest,
) -> Result<(), PrivateRuntimeError> {
let file = File::open(archive_path).map_err(PrivateRuntimeError::ArchiveUnavailable)?;
let mut archive = ZipArchive::new(file).map_err(|_| PrivateRuntimeError::ArchiveInvalid)?;
if archive.len() as u64 != manifest.entry_count {
return Err(PrivateRuntimeError::ArchiveInvalid);
}
let mut unpacked = 0_u64;
for index in 0..archive.len() {
let mut entry = archive
.by_index(index)
.map_err(|_| PrivateRuntimeError::ArchiveInvalid)?;
let entry_name = entry.name().map_err(|_| PrivateRuntimeError::ArchiveInvalid)?;
if Path::new(entry_name.as_ref()).is_absolute()
|| entry_name.starts_with('/')
|| entry_name.starts_with('\\')
|| entry_name.as_bytes().get(1) == Some(&b':')
{
return Err(PrivateRuntimeError::ArchiveInvalid);
}
unpacked = unpacked
.checked_add(entry.size())
.filter(|value| *value <= manifest.unpacked_size)
.ok_or(PrivateRuntimeError::ArchiveInvalid)?;
let relative = entry
.enclosed_name()
.filter(|path| path.components().all(|part| matches!(part, Component::Normal(_))))
.ok_or(PrivateRuntimeError::ArchiveInvalid)?;
if entry.unix_mode().is_some_and(|mode| mode & 0o170_000 == 0o120_000) {
return Err(PrivateRuntimeError::ArchiveInvalid);
}
let output = destination.join(relative);
if entry.is_dir() {
fs::create_dir_all(&output).map_err(PrivateRuntimeError::Install)?;
continue;
}
if let Some(parent) = output.parent() {
fs::create_dir_all(parent).map_err(PrivateRuntimeError::Install)?;
}
let mut target = OpenOptions::new()
.write(true)
.create_new(true)
.open(&output)
.map_err(PrivateRuntimeError::Install)?;
io::copy(&mut entry, &mut target).map_err(PrivateRuntimeError::Install)?;
target.flush().map_err(PrivateRuntimeError::Install)?;
set_entry_permissions(&output, entry.unix_mode())?;
}
if unpacked != manifest.unpacked_size {
return Err(PrivateRuntimeError::ArchiveInvalid);
}
Ok(())
}
#[cfg(unix)]
fn set_entry_permissions(path: &Path, mode: Option<u32>) -> Result<(), PrivateRuntimeError> {
use std::os::unix::fs::PermissionsExt;
let mode = mode.ok_or(PrivateRuntimeError::ArchiveInvalid)? & 0o777;
fs::set_permissions(path, fs::Permissions::from_mode(mode)).map_err(PrivateRuntimeError::Install)
}
#[cfg(not(unix))]
fn set_entry_permissions(_path: &Path, _mode: Option<u32>) -> Result<(), PrivateRuntimeError> {
Ok(())
}
fn validate_runtime_files(root: &Path, manifest: &RuntimeBundleManifest) -> Result<(), PrivateRuntimeError> {
for (relative, must_be_executable) in required_runtime_files(manifest) {
let path = root.join(relative);
let metadata = fs::symlink_metadata(path).map_err(PrivateRuntimeError::Install)?;
if !metadata.file_type().is_file() {
return Err(PrivateRuntimeError::ArchiveInvalid);
}
#[cfg(not(unix))]
let _ = must_be_executable;
#[cfg(unix)]
{
use std::os::unix::fs::PermissionsExt;
if must_be_executable && metadata.permissions().mode() & 0o111 == 0 {
return Err(PrivateRuntimeError::ArchiveInvalid);
}
}
}
Ok(())
}
fn required_runtime_files(manifest: &RuntimeBundleManifest) -> [(PathBuf, bool); 3] {
[
(PathBuf::from(&manifest.python_entrypoint), true),
(PathBuf::from(&manifest.node_entrypoint), true),
(PathBuf::from(&manifest.npm_entrypoint), false),
]
}
/// Hashes every file of a freshly extracted tree against `tree_sha256`.
///
/// This runs once per install, on the staging directory, before the marker is
/// written and the slot is published, and again by
/// [`PrivateRuntimeBundle::audit`] off the launch path. Reuse itself checks
/// only [`verify_installed_shape`].
fn verify_installed_tree(root: &Path, manifest: &RuntimeBundleManifest) -> Result<(), PrivateRuntimeError> {
let mut files = verify_installed_shape(root, manifest)?;
files.sort_by(|left, right| left.0.cmp(&right.0));
let mut hasher = Sha256::new();
hasher.update(TREE_HASH_DOMAIN);
for (relative, path, size) in &files {
update_tree_header(&mut hasher, relative, *size);
let mut file = File::open(path).map_err(PrivateRuntimeError::Install)?;
update_from_reader(&mut hasher, &mut file).map_err(PrivateRuntimeError::Install)?;
}
let actual = lower_hex(&hasher.finalize());
if actual != manifest.tree_sha256 {
return Err(PrivateRuntimeError::ArchiveVerification);
}
Ok(())
}
/// Checks a tree's file set against the manifest without reading any file.
///
/// A slot is published only by renaming a staging directory whose full hash
/// matched and whose marker was written after that, so a slot carrying the
/// manifest's marker was hashed in full when it was extracted. Re-hashing it on
/// every launch read the whole tree (about 390MB in 17k files) before the first
/// health probe: 3.5s at the median and 12.6s at p90 over 250 recorded launches.
///
/// What commonly reaches an installed tree afterwards is a process writing into
/// it (bytecode, #2273), a file being removed or truncated, or its permissions
/// changing. Each changes the regular-file count, the unpacked size, or a mode
/// this walk already reads, and a link or special file is rejected outright, so
/// none of those trees is reused. What metadata cannot see (a rename, an
/// equal-size rewrite, data lost in a crash before it reached the disk) is left
/// to [`PrivateRuntimeBundle::audit`], which repeats the full hash off the
/// launch path and withdraws a slot that fails it.
fn verify_installed_shape(
root: &Path,
manifest: &RuntimeBundleManifest,
) -> Result<Vec<(String, PathBuf, u64)>, PrivateRuntimeError> {
let root_metadata = fs::symlink_metadata(root).map_err(PrivateRuntimeError::Install)?;
if !root_metadata.file_type().is_dir() {
return Err(PrivateRuntimeError::ArchiveInvalid);
}
let mut files = Vec::new();
collect_tree_files(root, root, &mut files)?;
let mut unpacked_size = 0_u64;
for (_, _, size) in &files {
unpacked_size = unpacked_size
.checked_add(*size)
.filter(|value| *value <= manifest.unpacked_size)
.ok_or(PrivateRuntimeError::ArchiveVerification)?;
}
if files.len() as u64 != manifest.entry_count || unpacked_size != manifest.unpacked_size {
return Err(PrivateRuntimeError::ArchiveVerification);
}
Ok(files)
}
fn collect_tree_files(
root: &Path,
directory: &Path,
files: &mut Vec<(String, PathBuf, u64)>,
) -> Result<(), PrivateRuntimeError> {
for entry in fs::read_dir(directory).map_err(PrivateRuntimeError::Install)? {
let entry = entry.map_err(PrivateRuntimeError::Install)?;
let path = entry.path();
let metadata = fs::symlink_metadata(&path).map_err(PrivateRuntimeError::Install)?;
let file_type = metadata.file_type();
if file_type.is_symlink() {
return Err(PrivateRuntimeError::ArchiveVerification);
}
if file_type.is_dir() {
collect_tree_files(root, &path, files)?;
continue;
}
if !file_type.is_file() {
return Err(PrivateRuntimeError::ArchiveVerification);
}
// The install hash opened every file as this user, so a file without
// the owner read bit was changed afterwards and would fail the Runtime
// that imports it.
#[cfg(unix)]
{
use std::os::unix::fs::PermissionsExt;
if metadata.permissions().mode() & 0o400 == 0 {
return Err(PrivateRuntimeError::ArchiveVerification);
}
}
let relative_path = path
.strip_prefix(root)
.map_err(|_| PrivateRuntimeError::ArchiveVerification)?;
if relative_path == Path::new(INSTALL_MARKER_NAME) {
continue;
}
let relative = portable_relative_path(relative_path)?;
files.push((relative, path, metadata.len()));
}
Ok(())
}
fn portable_relative_path(path: &Path) -> Result<String, PrivateRuntimeError> {
path.components()
.map(|component| match component {
Component::Normal(value) => value.to_str().ok_or(PrivateRuntimeError::ArchiveVerification),
_ => Err(PrivateRuntimeError::ArchiveVerification),
})
.collect::<Result<Vec<_>, _>>()
.map(|parts| parts.join("/"))
}
fn update_tree_header(hasher: &mut Sha256, relative: &str, size: u64) {
let relative = relative.as_bytes();
hasher.update((relative.len() as u64).to_be_bytes());
hasher.update(relative);
hasher.update(size.to_be_bytes());
}
fn write_marker(root: &Path, manifest: &RuntimeBundleManifest) -> Result<(), PrivateRuntimeError> {
let bytes = serde_json::to_vec(manifest).map_err(|_| PrivateRuntimeError::ManifestInvalid)?;
let marker = root.join(INSTALL_MARKER_NAME);
let mut file = OpenOptions::new()
.write(true)
.create_new(true)
.open(marker)
.map_err(PrivateRuntimeError::Install)?;
file.write_all(&bytes).map_err(PrivateRuntimeError::Install)?;
file.sync_all().map_err(PrivateRuntimeError::Install)
}
fn installed_runtime(
root: &Path,
manifest: &RuntimeBundleManifest,
) -> Result<InstalledPrivateRuntime, PrivateRuntimeError> {
let marker = fs::read(root.join(INSTALL_MARKER_NAME)).map_err(PrivateRuntimeError::Install)?;
let installed: RuntimeBundleManifest =
serde_json::from_slice(&marker).map_err(|_| PrivateRuntimeError::ArchiveInvalid)?;
if &installed != manifest {
return Err(PrivateRuntimeError::ArchiveInvalid);
}
validate_runtime_files(root, manifest)?;
// Every caller reaches this for a published slot, whose marker proves the
// full hash already passed: a reused one, one this launch just renamed into
// place, or one another process won the rename with.
verify_installed_shape(root, manifest)?;
Ok(InstalledPrivateRuntime {
root: root.to_owned(),
python: root.join(&manifest.python_entrypoint),
node: root.join(&manifest.node_entrypoint),
npm_cli: root.join(&manifest.npm_entrypoint),
runtime_id: manifest.archive_sha256.clone(),
// Validating a tree says nothing about who put it there. Only the reuse
// scan in `prepare()` knows it did not extract this one.
reused: false,
})
}
#[cfg(test)]
mod tests {
use super::*;
use std::io::Write;
use zip::write::SimpleFileOptions;
use zip::{CompressionMethod, ZipWriter};
fn scratch(label: &str) -> PathBuf {
let sequence = INSTALL_SEQUENCE.fetch_add(1, Ordering::SeqCst);
let path = std::env::temp_dir().join(format!(
"avibe-private-runtime-{label}-{}-{sequence}",
std::process::id()
));
fs::create_dir_all(&path).expect("scratch directory");
path
}
fn entrypoints() -> (&'static str, &'static str, &'static str) {
if cfg!(windows) {
("python/python.exe", "tools/bin/node.exe", "tools/npm/bin/npm-cli.js")
} else {
("python/bin/python3", "tools/bin/node", "tools/npm/bin/npm-cli.js")
}
}
fn write_bundle(root: &Path, extra_entry: Option<&str>) -> RuntimeBundleManifest {
write_bundle_with_compression(root, extra_entry, CompressionMethod::Deflated)
}
fn write_bundle_with_compression(
root: &Path,
extra_entry: Option<&str>,
compression: CompressionMethod,
) -> RuntimeBundleManifest {
let bundle = root.join("bundle");
fs::create_dir_all(&bundle).expect("bundle directory");
let archive_path = bundle.join("runtime.zip");
let archive_file = File::create(&archive_path).expect("archive");
let mut zip = ZipWriter::new(archive_file);
let executable_options = SimpleFileOptions::default()
.compression_method(compression)
.unix_permissions(0o755);
let data_options = SimpleFileOptions::default()
.compression_method(compression)
.unix_permissions(0o644);
let (python, node, npm_cli) = entrypoints();
let mut unpacked_size = 0_u64;
let mut entry_count = 0_u64;
let entries: Vec<_> = [python, node, npm_cli].into_iter().chain(extra_entry).collect();
for name in &entries {
let options = if *name == npm_cli {
data_options
} else {
executable_options
};
zip.start_file(name, options).expect("zip entry");
zip.write_all(b"runtime").expect("zip bytes");
unpacked_size += 7;
entry_count += 1;
}
zip.finish().expect("zip finished");
let mut tree_entries = entries;
tree_entries.sort_unstable();
let mut tree_hasher = Sha256::new();
tree_hasher.update(TREE_HASH_DOMAIN);
for name in tree_entries {
update_tree_header(&mut tree_hasher, name, 7);
tree_hasher.update(b"runtime");
}
let bytes = fs::read(&archive_path).expect("archive bytes");
let manifest = RuntimeBundleManifest {
schema_version: 2,
runtime_version: "3.0.0-test".to_owned(),
os: current_os().to_owned(),
arch: current_arch().to_owned(),
archive: "runtime.zip".to_owned(),
archive_sha256: lower_hex(&Sha256::digest(&bytes)),
archive_size: bytes.len() as u64,
unpacked_size,
entry_count,
tree_sha256: lower_hex(&tree_hasher.finalize()),
python_entrypoint: python.to_owned(),
node_entrypoint: node.to_owned(),
npm_entrypoint: npm_cli.to_owned(),
python_distribution: RuntimeSource {
url: "https://example.invalid/python".to_owned(),
sha256: "a".repeat(64),
},
node_distribution: RuntimeSource {
url: "https://example.invalid/node".to_owned(),
sha256: "b".repeat(64),
},
npm_version: "10.9.8".to_owned(),
avibe_wheel: RuntimeArtifact {
name: "avibe_os-3.0.0-py3-none-any.whl".to_owned(),
sha256: "c".repeat(64),
},
};
fs::write(
bundle.join(MANIFEST_NAME),
serde_json::to_vec(&manifest).expect("manifest JSON"),
)
.expect("manifest");
manifest
}
#[test]
fn installer_preparation_and_lazy_launch_share_the_same_verified_slot() {
let root = scratch("installer-prepare");
let manifest = write_bundle(&root, None);
let installation = root.join("Program Files").join("Avibe 测试");
fs::create_dir_all(&installation).unwrap();
fs::rename(root.join("bundle"), installation.join("runtime")).unwrap();
let app_data = root.join("Local App Data").join("bot.avibe.desktop");
let executable = installation.join("avibe-desktop.exe");
let predecessor = app_data.join("runtime").join("old-version").join("old-digest");
fs::create_dir_all(&predecessor).unwrap();
fs::write(predecessor.join("running"), b"keep this Runtime").unwrap();
let prepared = prepare_installed_runtime(&executable, &app_data).unwrap();
assert!(!prepared.reused);
assert!(prepared.root.starts_with(app_data.join("runtime")));
assert!(prepared.root.ends_with(&manifest.archive_sha256[..16]));
assert!(!prepared.root.starts_with(&installation));
let again = prepare_installed_runtime(&executable, &app_data).unwrap();
let lazy = PrivateRuntimeBundle::new(installation.join("runtime"), app_data.join("runtime"))
.prepare()
.unwrap();
assert!(again.reused && lazy.reused);
assert_eq!(prepared.root, again.root);
assert_eq!(prepared.root, lazy.root);
assert_eq!(fs::read(predecessor.join("running")).unwrap(), b"keep this Runtime");
fs::remove_dir_all(root).unwrap();
}
#[test]
fn installer_preparation_fails_closed_on_invalid_paths_or_bundle() {
let root = scratch("installer-failure");
let app_data = root.join("local-data");
let executable = root.join("app").join("avibe-desktop.exe");
assert!(prepare_installed_runtime(Path::new("relative.exe"), &app_data).is_err());
assert!(prepare_installed_runtime(&executable, Path::new("relative")).is_err());
assert!(matches!(
prepare_installed_runtime(&executable, &app_data),
Err(PrivateRuntimeError::ManifestUnavailable(_))
));
write_bundle(&root, None);
fs::create_dir_all(executable.parent().unwrap()).unwrap();
fs::rename(root.join("bundle"), root.join("app/runtime")).unwrap();
fs::write(root.join("app/runtime/runtime.zip"), b"corrupt archive").unwrap();
assert!(matches!(
prepare_installed_runtime(&executable, &app_data),
Err(PrivateRuntimeError::ArchiveVerification)
));
fs::remove_dir_all(root).unwrap();
}
#[test]
fn tree_verification_keeps_the_frozen_v1_digest_and_rejects_equal_size_tampering() {
let root = scratch("frozen-tree-digest");
let mut manifest = write_bundle(&root, None);
let tree = root.join("tree");
fs::create_dir_all(tree.join("dir")).unwrap();
// Deliberately create files out of sorted order, including an empty file
// and a UTF-8 path. The v1 hash uses byte lengths, not character counts.
fs::write(tree.join("z"), b"c4").unwrap();
fs::write(tree.join("dir/测试"), b"abc").unwrap();
fs::write(tree.join("a"), b"").unwrap();
manifest.entry_count = 3;
manifest.unpacked_size = 5;
// Independent SHA-256 vector for domain + sorted length/path/size/data
// records, confirmed against the pre-upgrade sha2 0.10 implementation.
manifest.tree_sha256 = "b15f116b100c3be48b84107d8097a4874f97a7bdc0c127035bdaa702767ac411".into();
verify_installed_tree(&tree, &manifest).unwrap();
fs::write(tree.join("dir/测试"), b"abd").unwrap();
assert!(matches!(
verify_installed_tree(&tree, &manifest),
Err(PrivateRuntimeError::ArchiveVerification)
));
fs::remove_dir_all(root).unwrap();
}
#[test]
fn installs_once_into_a_versioned_content_addressed_directory() {
let root = scratch("install");
let manifest = write_bundle(&root, None);
let bundle = PrivateRuntimeBundle::new(root.join("bundle"), root.join("installs"));
let first = bundle.prepare().expect("first install");
let second = bundle.prepare().expect("existing install");
assert_eq!(first.root, second.root);
// The distinction the bootstrap log is built to record. An install that
// keeps reporting `extracted` is invalidating itself between launches,
// and every launch then pays a cold tree's start-up cost.
assert!(!first.reused, "the first launch extracted this tree");
assert!(second.reused, "the second launch must not extract it again");
assert!(first.root.ends_with(&manifest.archive_sha256[..16]));
assert!(first.python.is_file());
assert!(first.node.is_file());
assert!(first.npm_cli.is_file());
let version_dir = first.root.parent().expect("version directory");
assert!(version_dir.ends_with(&manifest.runtime_version));
assert_eq!(fs::read_dir(version_dir).expect("version directory").count(), 1);
fs::remove_dir_all(root).ok();
}
#[test]
fn rejects_an_archive_that_does_not_match_the_signed_manifest() {
let root = scratch("digest");
write_bundle(&root, None);
let archive = root.join("bundle/runtime.zip");
fs::OpenOptions::new()
.append(true)
.open(&archive)
.expect("archive")
.write_all(b"tampered")
.expect("tamper");
let bundle = PrivateRuntimeBundle::new(root.join("bundle"), root.join("installs"));
assert!(matches!(
bundle.prepare(),
Err(PrivateRuntimeError::ArchiveVerification)
));
fs::remove_dir_all(root).ok();
}
#[test]
fn a_tampered_install_is_never_reused_and_repairs_once() {
let root = scratch("installed-tamper");
let manifest = write_bundle(&root, None);
let bundle = PrivateRuntimeBundle::new(root.join("bundle"), root.join("installs"));
let first = bundle.prepare().expect("first install");
fs::write(&first.python, b"tampered").expect("tamper installed interpreter");
let repaired = bundle.prepare().expect("repair install");
assert_ne!(repaired.root, first.root);
assert!(repaired
.root
.ends_with(format!("{}-repair", &manifest.archive_sha256[..16])));
assert_eq!(fs::read(&repaired.python).expect("repaired interpreter"), b"runtime");
assert_eq!(bundle.prepare().expect("reuse repair").root, repaired.root);
fs::remove_dir_all(root).ok();
}
/// Any change to an installed tree's file set or sizes keeps it from being
/// reused, whichever file it touches.
#[test]
fn a_changed_file_set_is_never_reused() {
type Mutation = (&'static str, fn(&Path));
let mutations: [Mutation; 4] = [
("bytecode written by a Runtime process", |root| {
fs::create_dir_all(root.join("lib/__pycache__")).expect("bytecode directory");
fs::write(root.join("lib/__pycache__/data.cpython-312.pyc"), b"pyc").expect("bytecode");
}),
("file removed", |root| {
fs::remove_file(root.join("lib/data.txt")).expect("remove")
}),
("file truncated", |root| {
fs::write(root.join("lib/data.txt"), b"").expect("truncate")
}),
("file grown", |root| {
fs::write(root.join("lib/data.txt"), b"runtime+").expect("grow")
}),
];
for (label, mutate) in mutations {
let root = scratch("installed-shape");
let manifest = write_bundle(&root, Some("lib/data.txt"));
let bundle = PrivateRuntimeBundle::new(root.join("bundle"), root.join("installs"));
let first = bundle.prepare().expect("first install");
mutate(&first.root);
let next = bundle.prepare().expect("repair install");
assert!(!next.reused, "{label}: the changed tree was reused");
assert!(
next.root
.ends_with(format!("{}-repair", &manifest.archive_sha256[..16])),
"{label}: the verified archive was not reinstalled into the repair slot"
);
assert_eq!(
fs::read(next.root.join("lib/data.txt")).expect("repaired file"),
b"runtime"
);
fs::remove_dir_all(root).ok();
}
}
/// A file the Runtime can no longer read is visible from its mode, so it is
/// repaired before the launch rather than failing the Runtime that imports it.
#[cfg(unix)]
#[test]
fn an_unreadable_file_is_repaired_before_reuse() {
use std::os::unix::fs::PermissionsExt;
let root = scratch("unreadable");
let manifest = write_bundle(&root, Some("lib/data.txt"));
let bundle = PrivateRuntimeBundle::new(root.join("bundle"), root.join("installs"));
let first = bundle.prepare().expect("first install");
let data = first.root.join("lib/data.txt");
fs::set_permissions(&data, fs::Permissions::from_mode(0o000)).expect("make content unreadable");
let next = bundle.prepare().expect("repair install");
assert!(!next.reused, "the unreadable tree was reused");
assert!(next
.root
.ends_with(format!("{}-repair", &manifest.archive_sha256[..16])));
assert_eq!(
fs::read(next.root.join("lib/data.txt")).expect("repaired file"),
b"runtime"
);
fs::set_permissions(&data, fs::Permissions::from_mode(0o644)).ok();
fs::remove_dir_all(root).ok();
}
/// Reuse reads no file content, so a change that keeps every count and size
/// is served once; the audit that follows withdraws the slot and the next
/// launch reinstalls the verified archive.
#[test]
fn what_metadata_cannot_see_is_withdrawn_by_the_audit() {
type Mutation = (&'static str, fn(&Path));
let mutations: [Mutation; 2] = [
("equal-size rewrite", |root| {
fs::write(root.join("lib/data.txt"), b"RUNTIME").expect("rewrite")
}),
("rename", |root| {
fs::rename(root.join("lib/data.txt"), root.join("lib/atad.txt")).expect("rename")
}),
];
for (label, mutate) in mutations {
let root = scratch("audit");
let manifest = write_bundle(&root, Some("lib/data.txt"));
let bundle = PrivateRuntimeBundle::new(root.join("bundle"), root.join("installs"));
let first = bundle.prepare().expect("first install");
mutate(&first.root);
let reused = bundle.prepare().expect("metadata-only reuse");
assert!(reused.reused, "{label}: reuse must not read file content");
assert_eq!(reused.root, first.root);
assert!(
matches!(
bundle.audit(&reused.root),
Err(PrivateRuntimeError::ArchiveVerification)
),
"{label}: the audit accepted a changed tree"
);
assert!(
!first.root.join(INSTALL_MARKER_NAME).exists(),
"{label}: slot not withdrawn"
);
let next = bundle.prepare().expect("repair install");
assert!(!next.reused, "{label}: the withdrawn slot was reused");
assert!(
next.root
.ends_with(format!("{}-repair", &manifest.archive_sha256[..16])),
"{label}: the verified archive was not reinstalled into the repair slot"
);
assert_eq!(
fs::read(next.root.join("lib/data.txt")).expect("repaired file"),
b"runtime"
);
fs::remove_dir_all(root).ok();
}
}
#[test]
fn an_intact_slot_survives_its_audit() {
let root = scratch("audit-intact");
write_bundle(&root, Some("lib/data.txt"));
let bundle = PrivateRuntimeBundle::new(root.join("bundle"), root.join("installs"));
let first = bundle.prepare().expect("first install");
bundle.audit(&first.root).expect("an intact slot passes");
let next = bundle.prepare().expect("reuse");
assert!(next.reused);
assert_eq!(next.root, first.root);
fs::remove_dir_all(root).ok();
}
/// The audit deletes a marker, so it acts only on a slot this bundle owns.
#[test]
fn the_audit_touches_only_an_install_slot_of_the_bundle() {
let root = scratch("audit-foreign");
write_bundle(&root, None);
let bundle = PrivateRuntimeBundle::new(root.join("bundle"), root.join("installs"));
let foreign = root.join("elsewhere");
fs::create_dir_all(&foreign).expect("foreign directory");
fs::write(foreign.join(INSTALL_MARKER_NAME), b"{}").expect("foreign marker");
assert!(matches!(bundle.audit(&foreign), Err(PrivateRuntimeError::Install(_))));
assert!(foreign.join(INSTALL_MARKER_NAME).exists());
fs::remove_dir_all(root).ok();
}
#[cfg(unix)]
#[test]
fn a_runtime_with_a_non_executable_entrypoint_is_repaired() {
use std::os::unix::fs::PermissionsExt;
let root = scratch("installed-mode-tamper");
let manifest = write_bundle(&root, None);
let bundle = PrivateRuntimeBundle::new(root.join("bundle"), root.join("installs"));
let first = bundle.prepare().expect("first install");
fs::set_permissions(&first.python, fs::Permissions::from_mode(0o644)).expect("remove execute bits");
let repaired = bundle.prepare().expect("repair install");
assert_ne!(repaired.root, first.root);
assert!(repaired
.root
.ends_with(format!("{}-repair", &manifest.archive_sha256[..16])));
assert_ne!(
fs::metadata(&repaired.python)
.expect("repaired metadata")
.permissions()
.mode()
& 0o111,
0
);
fs::remove_dir_all(root).ok();
}
#[cfg(unix)]
#[test]
fn npm_cli_does_not_need_an_executable_mode() {
use std::os::unix::fs::PermissionsExt;
let root = scratch("npm-cli-mode");
write_bundle(&root, None);
let bundle = PrivateRuntimeBundle::new(root.join("bundle"), root.join("installs"));
let installed = bundle.prepare().expect("Runtime with npm CLI installs");
assert_eq!(
fs::metadata(&installed.npm_cli)
.expect("npm CLI metadata")
.permissions()
.mode()
& 0o111,
0
);
fs::remove_dir_all(root).ok();
}
#[test]
fn a_tampered_npm_cli_is_never_reused() {
let root = scratch("installed-npm-tamper");
let manifest = write_bundle(&root, None);
let bundle = PrivateRuntimeBundle::new(root.join("bundle"), root.join("installs"));
let first = bundle.prepare().expect("first install");
fs::write(&first.npm_cli, b"tampered").expect("tamper installed npm CLI");
let repaired = bundle.prepare().expect("repair install");
assert_ne!(repaired.root, first.root);
assert!(repaired
.root
.ends_with(format!("{}-repair", &manifest.archive_sha256[..16])));
assert_eq!(fs::read(&repaired.npm_cli).expect("repaired npm CLI"), b"runtime");
fs::remove_dir_all(root).ok();
}
#[test]
fn superseded_installs_are_pruned_only_after_an_active_runtime_is_selected() {
let root = scratch("prune");
write_bundle(&root, None);
let bundle = PrivateRuntimeBundle::new(root.join("bundle"), root.join("installs"));
let active = bundle.prepare().expect("active install");
let trees_root = active.root.parent().and_then(Path::parent).expect("trees root");
let other_digest = active.root.with_file_name("0123456789abcdef");
fs::create_dir_all(&other_digest).expect("other digest install");
fs::write(other_digest.join("unused"), b"unused").expect("other digest file");
let old = trees_root.join("2.9.0").join("old-digest");
fs::create_dir_all(&old).expect("old install");
fs::write(old.join("unused"), b"unused").expect("old file");
let staging = trees_root.join(".install-abandoned");
fs::create_dir_all(&staging).expect("staging install");
bundle.prune_superseded(&active.root).expect("prune succeeds");
assert!(active.root.is_dir());
assert!(!other_digest.exists());
assert!(!old.exists());
assert!(!staging.exists());
fs::remove_dir_all(root).ok();
}
/// `/ready` proves which Runtime id is serving, not which of its two slots
/// the daemon started from. `vibe start` keeps a live daemon, so after a
/// relaunch resolves the repair slot the daemon can still be running from
/// the primary, and deleting it would pull the tree out from under it.
#[test]
fn pruning_keeps_both_slots_of_the_served_runtime() {
let root = scratch("prune-served-slots");
write_bundle(&root, None);
let bundle = PrivateRuntimeBundle::new(root.join("bundle"), root.join("installs"));
let primary = bundle.prepare().expect("primary install");
let old = primary
.root
.parent()
.and_then(Path::parent)
.expect("trees root")
.join("2.9.0")
.join("old-digest");
fs::create_dir_all(&old).expect("old install");
// What a daemon running from the primary leaves behind: a file written
// into its own tree, which makes the next launch repair.
fs::write(primary.root.join("written-by-the-daemon"), b"extra").expect("tamper primary");
let repair = bundle.prepare().expect("repair install");
assert_ne!(repair.root, primary.root);
bundle
.prune_superseded(&repair.root)
.expect("prune from the repair slot");
assert_eq!(fs::read(&primary.python).expect("primary interpreter"), b"runtime");
assert!(repair.python.is_file());
assert!(!old.exists(), "another version is still superseded");
bundle
.prune_superseded(&primary.root)
.expect("prune from the primary slot");
assert!(primary.python.is_file());
assert!(repair.python.is_file());
fs::remove_dir_all(root).ok();
}
/// Spotlight skips a directory whose name ends in `.noindex`, subtree
/// included. Trees installed anywhere else get imported file by file after
/// every install, and the importer evicts them from the page cache that the
/// next launch's verification reads them from.
#[cfg(target_os = "macos")]
#[test]
fn macos_installs_trees_only_inside_a_noindex_directory() {
let root = scratch("noindex");
write_bundle(&root, None);
let install_root = root.join("installs");
let bundle = PrivateRuntimeBundle::new(root.join("bundle"), install_root.clone());
let installed = bundle.prepare().expect("install");
let entries: Vec<PathBuf> = fs::read_dir(&install_root)
.expect("install root")
.map(|entry| entry.expect("entry").path())
.collect();
assert_eq!(entries.len(), 1, "the install root holds one directory: {entries:?}");
assert!(entries[0].extension().is_some_and(|extension| extension == "noindex"));
assert!(installed.root.starts_with(&entries[0]));
fs::remove_dir_all(root).ok();
}
/// Releases before the `.noindex` directory left their trees directly in
/// the install root. Once this bundle's id is served they are superseded by
/// the same rule as any other tree: both slots of the served id are kept,
/// wherever a daemon might have started from them, and nothing else is.
#[cfg(target_os = "macos")]
#[test]
fn trees_an_earlier_release_left_in_the_install_root_are_pruned() {
let root = scratch("prune-install-root");
let manifest = write_bundle(&root, None);
let install_root = root.join("installs");
let bundle = PrivateRuntimeBundle::new(root.join("bundle"), install_root.clone());
let active = bundle.prepare().expect("active install");
let [served_primary, served_repair] = install_slots(
&install_root.join(&manifest.runtime_version),
&manifest.archive_sha256[..16],
);
let other_digest = install_root.join(&manifest.runtime_version).join("0123456789abcdef");
let old = install_root.join("2.9.0").join("old-digest");
let staging = install_root.join(".install-1-0");
for tree in [&served_primary, &served_repair, &other_digest, &old, &staging] {
fs::create_dir_all(tree).expect("earlier tree");
fs::write(tree.join("python3"), b"earlier").expect("earlier file");
}
bundle.prune_superseded(&active.root).expect("prune succeeds");
assert!(active.python.is_file());
assert!(served_primary.join("python3").is_file());
assert!(served_repair.join("python3").is_file());
assert!(!other_digest.exists());
assert!(!old.exists());
assert!(!staging.exists());
fs::remove_dir_all(root).ok();
}
/// The installer owns every directory from the install root down to a
/// version, and lists, writes and deletes inside each. A link in place of
/// any of them is refused by prepare and by prune, and whatever it names is
/// left as it was; a missing one is created as on a first install.
#[cfg(unix)]
#[test]
fn a_link_in_place_of_an_install_directory_is_refused() {
use std::os::unix::fs::symlink;
fn names(directory: &Path) -> Vec<String> {
let mut names: Vec<String> = fs::read_dir(directory)
.expect("directory")
.map(|entry| entry.expect("entry").file_name().to_string_lossy().into_owned())
.collect();
names.sort();
names
}
// An installed bundle and one of its directories, by level.
fn installed(
label: &str,
level: &str,
) -> Option<(PathBuf, PrivateRuntimeBundle, InstalledPrivateRuntime, PathBuf)> {
let root = scratch(label);
write_bundle(&root, None);
let install_root = root.join("installs");
let bundle = PrivateRuntimeBundle::new(root.join("bundle"), install_root.clone());
let active = bundle.prepare().expect("install");
let version_dir = active.root.parent().expect("version directory").to_owned();
let directory = match level {
"install root" => install_root.clone(),
"trees directory" => version_dir.parent().expect("trees directory").to_owned(),
_ => version_dir,
};
if level == "trees directory" && directory == install_root {
// Outside macOS the trees sit directly in the install root.
fs::remove_dir_all(root).ok();
return None;
}
Some((root, bundle, active, directory))
}
for level in ["install root", "trees directory", "version directory"] {
for operation in ["prepare", "prune"] {
let Some((root, bundle, active, directory)) = installed("install-link", level) else {
continue;
};
let outside = root.join("outside");
fs::create_dir_all(outside.join("documents")).expect("outside directory");
fs::write(outside.join("keep-me"), b"user file").expect("outside file");
fs::rename(&directory, root.join("moved-aside")).expect("move the directory aside");
symlink(&outside, &directory).expect("link in its place");
let result = match operation {
"prepare" => bundle.prepare().map(|_| ()),
_ => bundle.prune_superseded(&active.root),
};
assert!(
matches!(&result, Err(PrivateRuntimeError::NotARealDirectory(path)) if *path == directory),
"{level} {operation}: {result:?}"
);
assert_eq!(names(&outside), ["documents", "keep-me"], "{level} {operation}");
assert!(names(&outside.join("documents")).is_empty(), "{level} {operation}");
assert_eq!(fs::read(outside.join("keep-me")).expect("outside file"), b"user file");
fs::remove_dir_all(root).ok();
}
let Some((root, bundle, _, directory)) = installed("install-missing", level) else {
continue;
};
fs::remove_dir_all(&directory).expect("remove the directory");
let reinstalled = bundle.prepare().expect("a missing directory is created");
assert!(!reinstalled.reused, "{level}");
assert!(reinstalled.python.is_file(), "{level}");
assert!(
fs::symlink_metadata(&directory).expect("created").file_type().is_dir(),
"{level}"
);
fs::remove_dir_all(root).ok();
}
}
#[test]
fn explicit_removal_deletes_only_the_private_runtime_root() {
let root = scratch("remove-all");
let install_root = root.join("application-data").join("runtime");
let user_state = root.join(".avibe");
fs::create_dir_all(&install_root).expect("install root");
fs::create_dir_all(&user_state).expect("user state");
fs::write(install_root.join("private"), b"runtime").expect("private Runtime file");
fs::write(user_state.join("config.json"), b"user state").expect("user state file");
let bundle = PrivateRuntimeBundle::new(root.join("bundle"), install_root.clone());
bundle.remove_all().expect("private Runtime removal");
assert!(!install_root.exists());
assert_eq!(
fs::read(user_state.join("config.json")).expect("preserved user state"),
b"user state"
);
fs::remove_dir_all(root).ok();
}
/// Both slots invalid used to be terminal: the user's only way out was
/// deleting a directory by hand. Nothing here relaxes verification — a
/// tampered tree is still never executed — but the recovery is a reinstall
/// from the verified archive rather than a refusal, and it repeats.
#[test]
fn two_tampered_install_slots_are_reinstalled_rather_than_stranded() {
let root = scratch("installed-double-tamper");
let manifest = write_bundle(&root, None);
let bundle = PrivateRuntimeBundle::new(root.join("bundle"), root.join("installs"));
let primary = bundle.prepare().expect("primary install");
let version_dir = primary.root.parent().expect("version directory").to_owned();
let trees_root = version_dir.parent().expect("trees root").to_owned();
fs::write(&primary.python, b"tampered").expect("tamper primary");
let repair = bundle.prepare().expect("repair install");
fs::write(&repair.node, b"tampered").expect("tamper repair");
assert_ne!(primary.root, repair.root, "the two slots are distinct copies");
// Three rounds, because a single escape hatch that only works once is
// still a dead end for the second mutation.
for round in 0..3 {
let recovered = bundle.prepare().expect("both slots invalid still recovers");
assert!(!recovered.reused, "round {round} reused a tampered tree");
assert_eq!(
recovered.root, primary.root,
"the reinstall takes the freed primary name"
);
assert_eq!(
fs::read(&recovered.python).expect("reinstalled interpreter"),
b"runtime"
);
assert!(
bundle.prepare().expect("the recovered install is reusable").reused,
"round {round} could not reuse what it had just installed"
);
// Recovery must not grow the install by a copy per failure: the
// displaced tree is discarded, not accumulated.
let mut installed: Vec<String> = fs::read_dir(&version_dir)
.expect("version directory")
.map(|entry| entry.expect("entry").file_name().to_string_lossy().into_owned())
.collect();
installed.sort();
assert_eq!(
installed,
[
manifest.archive_sha256[..16].to_owned(),
format!("{}-repair", &manifest.archive_sha256[..16]),
],
"round {round} left more than the two install slots"
);
assert_eq!(
fs::read_dir(&trees_root)
.expect("trees root")
.filter(|entry| {
let name = entry.as_ref().expect("entry").file_name();
name.to_string_lossy().starts_with(".discard-")
})
.count(),
0,
"round {round} left a discarded copy behind"
);
// Set up the next round from the state this one produced: the repair
// slot is still tampered, so only the primary has to be re-broken.
fs::write(&recovered.python, b"tampered").expect("tamper for the next round");
}
fs::remove_dir_all(root).ok();
}
/// Reinstalling over the primary name must not leave that name empty while
/// the replacement is extracted: a daemon started from the primary may
/// still be resolving paths inside it. A replacement that never verifies
/// therefore leaves the primary exactly where it was.
#[test]
fn a_failed_reinstall_leaves_the_primary_in_place() {
let root = scratch("installed-double-tamper-failed");
let mut manifest = write_bundle(&root, None);
let bundle = PrivateRuntimeBundle::new(root.join("bundle"), root.join("installs"));
let primary = bundle.prepare().expect("primary install");
fs::write(primary.root.join("written-by-the-daemon"), b"extra").expect("tamper primary");
let repair = bundle.prepare().expect("repair install");
fs::write(repair.root.join("written-by-the-daemon"), b"extra").expect("tamper repair");
// The archive still matches, but the tree it unpacks to does not.
manifest.tree_sha256 = "0".repeat(64);
fs::write(
root.join("bundle").join(MANIFEST_NAME),
serde_json::to_vec(&manifest).expect("manifest JSON"),
)
.expect("manifest");
assert!(matches!(
bundle.prepare(),
Err(PrivateRuntimeError::ArchiveVerification)
));
assert_eq!(fs::read(&primary.python).expect("primary interpreter"), b"runtime");
assert!(primary.root.join("written-by-the-daemon").is_file());
fs::remove_dir_all(root).ok();
}
// Exercise the reader through prepare(), not just a ZipWriter round-trip:
// payload hashes, staging cleanup and publication are part of this boundary.
fn refresh_archive_identity(root: &Path, manifest: &mut RuntimeBundleManifest) {
let bytes = fs::read(root.join("bundle/runtime.zip")).expect("archive bytes");
manifest.archive_sha256 = lower_hex(&Sha256::digest(&bytes));
manifest.archive_size = bytes.len() as u64;
fs::write(
root.join("bundle").join(MANIFEST_NAME),
serde_json::to_vec(manifest).expect("manifest JSON"),
)
.expect("manifest");
}
fn assert_no_published_or_staged_files(path: &Path) {
for entry in fs::read_dir(path).expect("install directory") {
let entry = entry.expect("entry");
assert!(entry.file_type().expect("type").is_dir(), "unexpected file: {entry:?}");
assert!(!entry.file_name().to_string_lossy().starts_with(".install-"));
assert_no_published_or_staged_files(&entry.path());
}
}
#[test]
fn installs_unicode_paths_with_stored_and_deflated_entries() {
for compression in [CompressionMethod::Stored, CompressionMethod::Deflated] {
let root = scratch("zip-compression");
write_bundle_with_compression(&root, Some("资料/运行时.txt"), compression);
let bundle = PrivateRuntimeBundle::new(root.join("bundle"), root.join("installs"));
let installed = bundle.prepare().expect("install");
assert_eq!(fs::read(installed.root.join("资料/运行时.txt")).unwrap(), b"runtime");
assert!(bundle.prepare().expect("reuse").reused);
fs::remove_dir_all(root).unwrap();
}
}
#[test]
fn rejects_path_traversal_before_any_file_can_escape() {
for name in [
"../escape",
"nested/../../escape",
"absolute",
r"C:\escape",
r"\\server\share\escape",
] {
let root = scratch("traversal");
// Even the absolute-path negative fixture is test-owned if a
// regression lets it through; never point it at a real user file.
let outside = root.join("escape");
let absolute = outside.to_string_lossy().replace('\\', "/");
let name = if name == "absolute" { absolute.as_str() } else { name };
write_bundle(&root, Some(name));
let bundle = PrivateRuntimeBundle::new(root.join("bundle"), root.join("installs"));
let result = bundle.prepare();
assert!(
matches!(&result, Err(PrivateRuntimeError::ArchiveInvalid)),
"{name}: {result:?}"
);
assert!(!outside.exists());
assert_no_published_or_staged_files(&root.join("installs"));
fs::remove_dir_all(root).unwrap();
}
}
#[test]
fn rejects_invalid_zip_metadata_and_cleans_partial_extraction() {
#[cfg(not(unix))]
let cases: &[&str] = &["crc", "entry-count", "unpacked-size", "truncated"];
#[cfg(unix)]
let cases: &[&str] = &["symlink", "crc", "entry-count", "unpacked-size", "truncated"];
for &case in cases {
let root = scratch(case);
let mut manifest = write_bundle(&root, Some("last-entry"));
let archive_path = root.join("bundle/runtime.zip");
let mut bytes = fs::read(&archive_path).unwrap();
// Mutate the last central record: valid earlier entries are
// extracted first, so this also tests failure cleanup. Recompute
// the archive digest to avoid passing via the outer hash check.
let central = bytes.windows(4).rposition(|b| b == b"PK\x01\x02").unwrap();
match case {
"symlink" => {
bytes[central + 38..central + 42].copy_from_slice(&(0o120_777_u32 << 16).to_le_bytes());
}
"crc" => bytes[central + 16] ^= 0xff,
"entry-count" => manifest.entry_count += 1,
"unpacked-size" => manifest.unpacked_size -= 1,
"truncated" => bytes.truncate(12),
_ => unreachable!(),
}
fs::write(archive_path, bytes).unwrap();
refresh_archive_identity(&root, &mut manifest);
let bundle = PrivateRuntimeBundle::new(root.join("bundle"), root.join("installs"));
let failure = bundle.prepare().expect_err(case);
if case == "crc" {
assert!(
matches!(failure, PrivateRuntimeError::Install(_)),
"{case}: {failure:?}"
);
} else {
assert!(
matches!(failure, PrivateRuntimeError::ArchiveInvalid),
"{case}: {failure:?}"
);
}
assert_no_published_or_staged_files(&root.join("installs"));
fs::remove_dir_all(root).unwrap();
}
}
#[cfg(unix)]
#[test]
fn extraction_strips_privileged_permission_bits() {
use std::os::unix::fs::PermissionsExt;
let root = scratch("zip-modes");
let mut manifest = write_bundle(&root, None);
let archive_path = root.join("bundle/runtime.zip");
let mut bytes = fs::read(&archive_path).unwrap();
let central = bytes.windows(4).position(|b| b == b"PK\x01\x02").unwrap();
bytes[central + 38..central + 42].copy_from_slice(&(0o107_755_u32 << 16).to_le_bytes());
fs::write(archive_path, bytes).unwrap();
refresh_archive_identity(&root, &mut manifest);
let bundle = PrivateRuntimeBundle::new(root.join("bundle"), root.join("installs"));
let installed = bundle.prepare().expect("install");
assert_eq!(
fs::metadata(installed.python).unwrap().permissions().mode() & 0o7777,
0o755
);
fs::remove_dir_all(root).unwrap();
}
#[test]
fn rejects_a_manifest_for_another_architecture() {
let root = scratch("target");
let mut manifest = write_bundle(&root, None);
manifest.arch = if current_arch() == "aarch64" {
"x86_64".to_owned()
} else {
"aarch64".to_owned()
};
fs::write(
root.join("bundle").join(MANIFEST_NAME),
serde_json::to_vec(&manifest).expect("manifest JSON"),
)
.expect("manifest");
let bundle = PrivateRuntimeBundle::new(root.join("bundle"), root.join("installs"));
assert!(matches!(bundle.prepare(), Err(PrivateRuntimeError::TargetMismatch)));
fs::remove_dir_all(root).ok();
}
#[test]
fn rejects_the_legacy_runtime_manifest_schema() {
let root = scratch("schema-one");
let mut manifest = write_bundle(&root, None);
manifest.schema_version = 1;
fs::write(
root.join("bundle").join(MANIFEST_NAME),
serde_json::to_vec(&manifest).expect("manifest JSON"),
)
.expect("manifest");
let bundle = PrivateRuntimeBundle::new(root.join("bundle"), root.join("installs"));
assert!(matches!(bundle.prepare(), Err(PrivateRuntimeError::ManifestInvalid)));
fs::remove_dir_all(root).ok();
}
}