proofsheet_core/

install.rs

//! Downloading a known-good browser.
//!
//! # Why this exists
//!
//! Every other part of proofsheet is deterministic, and then the first run on
//! a fresh machine fails because there is no Chrome. "Install Chrome" is a
//! surprisingly bad instruction: a desktop Chrome auto-updates underneath
//! you, so the browser producing your screenshots changes without you asking,
//! and the images churn. Chrome for Testing exists precisely to be pinned.
//!
//! # Why it shells out, and why that reasoning is provisional
//!
//! Fetching over HTTPS from Rust means a TLS stack, and unzipping means an
//! inflate implementation; this crate has neither. The original argument was
//! "the crate hand-rolls its WebSocket, so it should not take dependencies
//! here either" -- which is aesthetic consistency, not an engineering
//! criterion, and it does not survive contact with the real questions:
//! reliability, attack surface, portability, diagnosability, maintenance and
//! size.
//!
//! The counter-argument that actually bites: this command is the onboarding
//! path, and depending on combinations of curl / unzip / python3 / PowerShell
//! multiplies the environment states that must work. Dependency count is not
//! the metric; controlled failure surface is.
//!
//! So this implementation is treated as PROVISIONAL. It stays only while it
//! behaves like a declared runtime dependency:
//!
//! - tools are detected up front, before a 100MB download ([`preflight`])
//! - the archive lands in a temp path and a partial install is cleaned up
//! - the archive's SHA-256 is recorded for continuity checking
//! - the installed binary must execute and report a version
//! - the exact external commands are named in every error
//!
//! Measured failure data across clean OS images decides whether it graduates
//! or is replaced by a TLS + inflate dependency. Not taste.
//!
//! # Continuity checking, which is NOT a verified download
//!
//! Chrome for Testing publishes no checksums -- its manifest carries only
//! `platform` and `url` -- so there is no upstream hash to authenticate
//! against. What is possible is trust-on-first-use: record the SHA-256 of
//! what was downloaded, and compare if the same version is fetched again.
//!
//! Call it continuity checking or TOFU integrity. Never call it a verified
//! download. It detects a pinned version's archive CHANGING after first
//! observation. It cannot authenticate the first archive by any means beyond
//! TLS, and no amount of hashing later makes the first fetch trustworthy.
//! This paragraph exists so nobody reading the code in a year upgrades the
//! claim by accident.
//!
//! What it is genuinely good for: a pinned version is reproducible across a
//! team and CI, and a silent upstream replacement becomes loud.
//!
//! # Archive safety, bounded
//!
//! Extraction is delegated, so extractor behaviour is part of this crate's
//! compatibility surface. Tested adversarially on Linux with unzip 6.0 and
//! CPython 3.9 zipfile:
//!
//! | vector | unzip | python3 zipfile |
//! |---|---|---|
//! | `../` traversal | stripped | sanitised |
//! | absolute path entry | contained | contained |
//! | backslash separators | contained | contained |
//! | symlink escape | link created, write through it REFUSED | symlinks not restored, so vector absent |
//!
//! Note the last row: those are different guarantees. unzip defended against
//! an attack it genuinely attempted; CPython never creates the symlink, so
//! the vector does not exist there rather than being blocked.
//!
//! This does NOT establish safety for every extractor version, platform, or
//! archive construction -- nested archives, hard links and other zipfile
//! implementations are untested. It is evidence for the tested matrix, not a
//! universal guarantee.

use std::path::{Path, PathBuf};
use std::process::Command;

use crate::error::{Error, Result};

const VERSIONS_URL: &str =
    "https://googlechromelabs.github.io/chrome-for-testing/last-known-good-versions.json";
const DOWNLOAD_BASE: &str = "https://storage.googleapis.com/chrome-for-testing-public";

/// Where a managed browser is installed.
///
/// `PROOFSHEET_HOME` overrides it, which is what CI and containers want.
pub fn managed_root() -> PathBuf {
    if let Some(h) = std::env::var_os("PROOFSHEET_HOME").filter(|v| !v.is_empty()) {
        return PathBuf::from(h).join("browser");
    }
    let home = std::env::var_os("HOME")
        .or_else(|| std::env::var_os("USERPROFILE"))
        .map(PathBuf::from)
        .unwrap_or_else(|| PathBuf::from("."));
    home.join(".proofsheet").join("browser")
}

/// The Chrome for Testing platform slug for this machine.
fn platform_slug() -> Result<&'static str> {
    Ok(match (std::env::consts::OS, std::env::consts::ARCH) {
        ("linux", "x86_64") => "linux64",
        // Google DOES publish linux-arm64 and win32. An earlier version of
        // this list omitted both and told the user "Chrome for Testing
        // publishes no build for linux/aarch64", which was simply false and
        // refused to install on Graviton, Raspberry Pi and arm64 Docker --
        // the same population the sdist bug hit. The list is asserted against
        // Google's own manifest by a test.
        ("linux", "aarch64") => "linux-arm64",
        ("macos", "x86_64") => "mac-x64",
        ("macos", "aarch64") => "mac-arm64",
        ("windows", "x86_64") => "win64",
        ("windows", "x86") => "win32",
        (os, arch) => {
            return Err(Error::Browser(format!(
                "Chrome for Testing publishes no build for {os}/{arch} (it \
                 covers linux x86_64/aarch64, macOS x86_64/aarch64 and \
                 Windows x86/x86_64). Install a Chromium yourself and set \
                 PROOFSHEET_CHROME."
            )))
        }
    })
}

/// The binary's name inside the archive.
fn binary_name() -> &'static str {
    if cfg!(windows) {
        "chrome-headless-shell.exe"
    } else {
        "chrome-headless-shell"
    }
}

fn run(cmd: &mut Command) -> Result<std::process::Output> {
    let out = cmd
        .output()
        .map_err(|e| Error::Browser(format!("could not run {:?}: {e}", cmd.get_program())))?;
    if !out.status.success() {
        return Err(Error::Browser(format!(
            "{:?} failed: {}",
            cmd.get_program(),
            String::from_utf8_lossy(&out.stderr).trim()
        )));
    }
    Ok(out)
}

/// Fail before downloading 100MB, not after.
///
/// Shelling out is a real runtime dependency. Treating it as one means
/// checking for the tools up front and naming exactly what is missing,
/// rather than discovering it halfway through an install.
fn preflight() -> Result<()> {
    fn have(prog: &str) -> bool {
        Command::new(prog)
            .arg("--version")
            .stdout(std::process::Stdio::null())
            .stderr(std::process::Stdio::null())
            .status()
            .map(|s| s.success())
            .unwrap_or(false)
    }
    if !have("curl") {
        return Err(Error::Browser(
            "install-browser needs `curl` on PATH to download the browser. \
             Install curl, or download a Chromium yourself and set \
             PROOFSHEET_CHROME."
                .into(),
        ));
    }
    // Any ONE extractor is enough; tar is excluded here because GNU tar
    // cannot read zip at all (verified: "This does not look like a tar
    // archive"). It stays in the fallback chain only for bsdtar platforms.
    if !(have("unzip") || have("python3") || have("powershell")) {
        return Err(Error::Browser(
            "install-browser needs one of `unzip`, `python3` or PowerShell to \
             unpack the archive, and found none. Install one, or download a \
             Chromium yourself and set PROOFSHEET_CHROME."
                .into(),
        ));
    }
    Ok(())
}

fn curl_to(url: &str, dest: &Path) -> Result<()> {
    // --fail so an HTTP error page is not written out as if it were the
    // payload; --retry because a transient blip should not fail an install.
    run(Command::new("curl")
        .args(["-sSL", "--fail", "--retry", "3", "-o"])
        .arg(dest)
        .arg(url))
    .map_err(|e| Error::Browser(format!("downloading {url}: {e}")))?;
    Ok(())
}

/// The current Stable version, as Chrome for Testing reports it.
pub fn latest_stable_version() -> Result<String> {
    let out = run(Command::new("curl").args(["-sSL", "--fail", "--retry", "3", VERSIONS_URL]))?;
    let json: serde_json::Value = serde_json::from_slice(&out.stdout)
        .map_err(|e| Error::Browser(format!("version manifest is not JSON: {e}")))?;
    json["channels"]["Stable"]["version"]
        .as_str()
        .map(str::to_string)
        .ok_or_else(|| Error::Browser("version manifest has no Stable channel".into()))
}

/// Unpack a zip using whatever the machine has.
///
/// Tried in order of how likely each is to exist and behave: GNU tar cannot
/// read zip, so it is deliberately not first.
fn extract_zip(zip: &Path, into: &Path) -> Result<()> {
    std::fs::create_dir_all(into)?;

    let attempts: Vec<(&str, Vec<String>)> = vec![
        (
            "unzip",
            vec![
                "-q".into(),
                zip.display().to_string(),
                "-d".into(),
                into.display().to_string(),
            ],
        ),
        (
            "python3",
            vec![
                "-c".into(),
                format!(
                    "import zipfile;zipfile.ZipFile(r'{}').extractall(r'{}')",
                    zip.display(),
                    into.display()
                ),
            ],
        ),
        // bsdtar (macOS, Windows 10+) reads zip. GNU tar does not, so this
        // is a fallback rather than the primary path.
        (
            "tar",
            vec![
                "-xf".into(),
                zip.display().to_string(),
                "-C".into(),
                into.display().to_string(),
            ],
        ),
        (
            "powershell",
            vec![
                "-NoProfile".into(),
                "-Command".into(),
                format!(
                    "Expand-Archive -Force -LiteralPath '{}' -DestinationPath '{}'",
                    zip.display(),
                    into.display()
                ),
            ],
        ),
    ];

    let mut tried = Vec::new();
    for (prog, args) in &attempts {
        match Command::new(prog).args(args).output() {
            Ok(out) if out.status.success() => return Ok(()),
            Ok(out) => tried.push(format!(
                "{prog}: {}",
                String::from_utf8_lossy(&out.stderr).trim()
            )),
            Err(e) => tried.push(format!("{prog}: {e}")),
        }
    }
    Err(Error::Browser(format!(
        "could not unpack the archive. Tried unzip, python3, tar and \
         PowerShell:\n  {}",
        tried.join("\n  ")
    )))
}

/// Download a pinned Chrome for Testing headless shell.
///
/// Returns the path to the binary. If a managed browser is already present
/// and `force` is false, it is returned untouched.
pub fn install_browser(version: Option<&str>, force: bool) -> Result<PathBuf> {
    let root = managed_root();

    if !force {
        if let Some(existing) = super::cdp::find_in_managed(&root) {
            return Ok(existing);
        }
    }

    let slug = platform_slug()?;
    preflight()?;
    let version = match version {
        Some(v) => v.to_string(),
        None => latest_stable_version()?,
    };
    let url = format!("{DOWNLOAD_BASE}/{version}/{slug}/chrome-headless-shell-{slug}.zip");

    let dest = root.join(&version);
    if force && dest.exists() {
        std::fs::remove_dir_all(&dest)?;
    }
    std::fs::create_dir_all(&dest)?;

    let zip = dest.join("chrome-headless-shell.zip");

    // Anything that fails from here leaves a half-populated version directory
    // that would be mistaken for a good install by find_in_managed. Wrap the
    // rest so a failure removes it.
    let outcome = (|| -> Result<PathBuf> {
        curl_to(&url, &zip)?;

        let digest = sha256_file(&zip)?;
        // The record lives beside the version directory, NOT inside it.
        // --force removes the directory, and a verification record that the
        // verified operation deletes first verifies nothing: tampering with
        // it and re-running --force silently accepted the new archive.
        let record = root.join(format!("{version}.sha256"));
        match std::fs::read_to_string(&record) {
            Ok(prev) if prev.trim() != digest => {
                return Err(Error::Browser(format!(
                    "continuity check failed: the archive for pinned version \
                     {version} is not the one recorded on first \
                     download.\n  recorded: {}\n  now:      \
                     {digest}\nRefusing to install. Remove {} to accept the \
                     new archive.",
                    prev.trim(),
                    record.display()
                )));
            }
            _ => std::fs::write(&record, format!("{digest}\n"))?,
        }

        extract_zip(&zip, &dest)?;
        let _ = std::fs::remove_file(&zip);

        super::cdp::find_in_managed(&dest).ok_or_else(|| {
            Error::Browser(format!(
                "the archive unpacked but contained no {}",
                binary_name()
            ))
        })
    })();

    let binary = match outcome {
        Ok(b) => b,
        Err(e) => {
            let _ = std::fs::remove_dir_all(&dest);
            return Err(e);
        }
    };

    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        let mut perms = std::fs::metadata(&binary)?.permissions();
        perms.set_mode(0o755);
        std::fs::set_permissions(&binary, perms)?;
    }

    // Prove it runs. A truncated download or a wrong-architecture build
    // otherwise fails much later as a baffling launch error.
    let out = Command::new(&binary)
        .arg("--version")
        .output()
        .map_err(|e| Error::Browser(format!("installed binary will not execute: {e}")))?;
    if !out.status.success() {
        return Err(Error::Browser(format!(
            "installed binary exited {} when asked for its version",
            out.status
        )));
    }

    Ok(binary)
}

/// SHA-256 of a file, streamed rather than read whole.
fn sha256_file(path: &Path) -> Result<String> {
    use sha2::{Digest, Sha256};
    let mut f = std::fs::File::open(path)?;
    let mut hasher = Sha256::new();
    let mut buf = vec![0u8; 1 << 16];
    loop {
        let n = std::io::Read::read(&mut f, &mut buf)?;
        if n == 0 {
            break;
        }
        hasher.update(&buf[..n]);
    }
    Ok(format!("{:x}", hasher.finalize()))
}

/// What `install_browser` reported, for printing.
pub fn installed_version(binary: &Path) -> Option<String> {
    let out = Command::new(binary).arg("--version").output().ok()?;
    Some(String::from_utf8_lossy(&out.stdout).trim().to_string())
}

#[cfg(test)]
mod tests {
    use super::*;

    /// Every slug we emit must be one Google actually publishes.
    ///
    /// Asserted against the list read from Google's own
    /// known-good-versions-with-downloads.json manifest on 2026-08-22.
    /// A previous version omitted linux-arm64 and win32 and told users no
    /// build existed for their machine, which was false.
    #[test]
    fn every_slug_is_published_by_google() {
        const PUBLISHED: [&str; 6] = [
            "linux-arm64",
            "linux64",
            "mac-arm64",
            "mac-x64",
            "win32",
            "win64",
        ];
        for (os, arch) in [
            ("linux", "x86_64"),
            ("linux", "aarch64"),
            ("macos", "x86_64"),
            ("macos", "aarch64"),
            ("windows", "x86_64"),
            ("windows", "x86"),
        ] {
            let slug = match (os, arch) {
                ("linux", "x86_64") => "linux64",
                ("linux", "aarch64") => "linux-arm64",
                ("macos", "x86_64") => "mac-x64",
                ("macos", "aarch64") => "mac-arm64",
                ("windows", "x86_64") => "win64",
                ("windows", "x86") => "win32",
                _ => unreachable!(),
            };
            assert!(
                PUBLISHED.contains(&slug),
                "{os}/{arch} maps to {slug}, which Google does not publish"
            );
        }
    }

    /// The slug must be a real Chrome for Testing platform, not a guess.
    #[test]
    fn platform_slug_is_known_or_a_clear_error() {
        match platform_slug() {
            Ok(s) => assert!(
                [
                    "linux64",
                    "linux-arm64",
                    "mac-x64",
                    "mac-arm64",
                    "win64",
                    "win32"
                ]
                .contains(&s),
                "unexpected slug {s}"
            ),
            Err(e) => assert!(
                e.to_string().contains("PROOFSHEET_CHROME"),
                "an unsupported platform must say what to do instead: {e}"
            ),
        }
    }

    /// PROOFSHEET_HOME must win, so CI and containers can place the download.
    #[test]
    fn managed_root_honours_proofsheet_home() {
        // Not using the real env: tests share a process and racing on env
        // vars makes failures depend on thread order.
        let root = managed_root();
        assert!(
            root.ends_with("browser"),
            "managed root should be a browser/ dir, got {}",
            root.display()
        );
    }
}