crates/cli/src/output.rs

GitHub
//! Filesystem output helpers for the CLI's `--unpack` writer.
//!
//! These functions translate decompiled module filenames (which originate from
//! untrusted bundle contents) into concrete on-disk paths that are guaranteed
//! to stay inside the chosen output directory, plus the write-if-changed logic
//! the writer wires around them.
//!
//! Pure path computation ([`safe_relative_module_path`], [`deduplicate_path`])
//! lives in `wakaru-core` and is reused here; this module owns the genuine
//! filesystem I/O (directory creation, symlink-resolving canonicalization, and
//! the file writes) that is an application concern rather than a decompiler
//! concern.
//!
//! Safety model: a module filename may contain `../` traversal, an absolute
//! path, a Windows drive prefix, or a path component that resolves through a
//! symlink pointing outside the output directory. Each of those must be
//! rejected. The two-stage approach is:
//!
//! 1. core's `safe_relative_module_path` performs a lexical check, rejecting any
//!    non-`Normal`/non-`CurDir` component before the path ever touches the
//!    filesystem.
//! 2. [`canonicalize_unpack_output_path`] walks the parent directories,
//!    creating or canonicalizing each one and confirming the canonical result
//!    still starts with the output directory. This catches symlink escapes that
//!    a purely lexical check cannot.

use std::collections::HashSet;
use std::fs;
use std::path::{Component, Path, PathBuf};

use anyhow::{bail, Context, Result};
use wakaru_core::{deduplicate_path, safe_relative_module_path};

/// Canonicalize the output directory so later path checks compare against a
/// fully-resolved root (symlinks resolved, `.`/`..` removed).
pub fn canonicalize_output_dir(path: &Path) -> Result<PathBuf> {
    path.canonicalize()
        .with_context(|| format!("failed to canonicalize output directory {}", path.display()))
}

/// Resolve a module `filename` to a concrete output path under `out_dir`.
///
/// Performs the lexical safety check, deduplicates against previously claimed
/// paths in `seen`, then canonicalizes parent directories (creating them as
/// needed) and confirms the result stays inside `out_dir`.
pub fn resolve_unpack_output_path(
    out_dir: &Path,
    filename: &str,
    seen: &mut HashSet<String>,
) -> Result<PathBuf> {
    let relative = safe_relative_module_path(filename)?;
    let lexical_path = deduplicate_path(&out_dir.join(relative), seen);
    canonicalize_unpack_output_path(out_dir, &lexical_path, filename)
}

/// Canonicalize `lexical_path` (already known to be under `out_dir`
/// lexically) against the real filesystem, creating missing parent
/// directories and confirming every resolved component stays inside `out_dir`.
///
/// This is what catches symlink escapes: a directory component that is a
/// symlink pointing outside `out_dir` resolves to a path that no longer starts
/// with `out_dir`, and is rejected.
pub fn canonicalize_unpack_output_path(
    out_dir: &Path,
    lexical_path: &Path,
    filename: &str,
) -> Result<PathBuf> {
    let relative = lexical_path.strip_prefix(out_dir).with_context(|| {
        format!("unsafe module filename {filename:?}: path escapes output directory")
    })?;
    let Some(file_name) = relative.file_name() else {
        bail!("unsafe module filename {filename:?}: empty output path");
    };

    let parent_relative = relative.parent().unwrap_or_else(|| Path::new(""));
    let mut current = out_dir.to_path_buf();
    for component in parent_relative.components() {
        let Component::Normal(part) = component else {
            bail!("unsafe module filename {filename:?}: path escapes output directory");
        };
        current.push(part);
        if current.exists() {
            let canonical = current.canonicalize().with_context(|| {
                format!(
                    "failed to canonicalize output directory {}",
                    current.display()
                )
            })?;
            ensure_path_inside_output_dir(out_dir, &canonical, filename)?;
            if !canonical.is_dir() {
                bail!(
                    "output path {} exists and is not a directory",
                    current.display()
                );
            }
            current = canonical;
        } else {
            fs::create_dir(&current).with_context(|| {
                format!("failed to create output directory {}", current.display())
            })?;
            let canonical = current.canonicalize().with_context(|| {
                format!(
                    "failed to canonicalize output directory {}",
                    current.display()
                )
            })?;
            ensure_path_inside_output_dir(out_dir, &canonical, filename)?;
            current = canonical;
        }
    }

    let candidate = current.join(file_name);
    let target = if candidate.exists() {
        candidate.canonicalize().with_context(|| {
            format!("failed to canonicalize output file {}", candidate.display())
        })?
    } else {
        candidate
    };
    ensure_path_inside_output_dir(out_dir, &target, filename)?;
    Ok(target)
}

fn ensure_path_inside_output_dir(out_dir: &Path, path: &Path, filename: &str) -> Result<()> {
    if path.starts_with(out_dir) {
        Ok(())
    } else {
        bail!("unsafe module filename {filename:?}: path escapes output directory");
    }
}

/// Write `content` to `path`, replacing any existing file.
pub fn write_file(path: &Path, content: &str) -> Result<()> {
    fs::write(path, content).with_context(|| format!("failed to write {}", path.display()))
}

/// Write `content` to `path` only when it differs from the existing file.
///
/// Skips the write when the on-disk file already has identical length and
/// bytes, avoiding redundant writes (and touch timestamps) when re-running
/// against an existing output directory.
pub fn write_if_changed(path: &Path, content: &str) -> Result<()> {
    if let Ok(metadata) = fs::metadata(path) {
        if metadata.len() == content.len() as u64
            && fs::read(path).is_ok_and(|existing| existing == content.as_bytes())
        {
            return Ok(());
        }
    }

    write_file(path, content)
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::time::{SystemTime, UNIX_EPOCH};

    fn temp_test_dir(name: &str) -> PathBuf {
        let nanos = SystemTime::now()
            .duration_since(UNIX_EPOCH)
            .expect("system time should be after epoch")
            .as_nanos();
        std::env::temp_dir().join(format!("wakaru-cli-output-test-{name}-{nanos}"))
    }

    #[cfg(windows)]
    fn create_dir_symlink(target: &Path, link: &Path) -> std::io::Result<()> {
        std::os::windows::fs::symlink_dir(target, link)
    }

    #[cfg(unix)]
    fn create_dir_symlink(target: &Path, link: &Path) -> std::io::Result<()> {
        std::os::unix::fs::symlink(target, link)
    }

    #[test]
    fn unpack_output_path_rejects_parent_dir_components() {
        let dir = temp_test_dir("escape");
        fs::create_dir_all(&dir).expect("create temp dir");
        let out_dir = canonicalize_output_dir(&dir).expect("canonicalize output dir");
        let mut seen = HashSet::new();

        let err = resolve_unpack_output_path(
            &out_dir,
            "../node_modules/@wakaru/cli/bin/wakaru",
            &mut seen,
        )
        .expect_err("parent path should be rejected");
        assert!(
            err.to_string().contains("path escapes output directory"),
            "unexpected error: {err}"
        );

        fs::remove_dir_all(&dir).expect("remove temp dir");
    }

    #[test]
    fn unpack_output_path_keeps_overlap_payload_inside_output_dir() {
        let dir = temp_test_dir("overlap");
        fs::create_dir_all(&dir).expect("create temp dir");
        let out_dir = canonicalize_output_dir(&dir).expect("canonicalize output dir");
        let mut seen = HashSet::new();

        let path = resolve_unpack_output_path(
            &out_dir,
            "....//node_modules/@wakaru/cli/bin/wakaru",
            &mut seen,
        )
        .expect("overlapping dots are an ordinary relative directory");
        assert!(
            path.starts_with(&out_dir),
            "resolved path should stay in output dir: {}",
            path.display()
        );
        assert!(path.ends_with("node_modules/@wakaru/cli/bin/wakaru"));

        fs::remove_dir_all(&dir).expect("remove temp dir");
    }

    #[test]
    fn unpack_output_path_rejects_absolute_paths() {
        let dir = temp_test_dir("absolute");
        fs::create_dir_all(&dir).expect("create temp dir");
        let out_dir = canonicalize_output_dir(&dir).expect("canonicalize output dir");
        let mut seen = HashSet::new();
        let absolute = format!(
            "{}tmp{}escape.js",
            std::path::MAIN_SEPARATOR,
            std::path::MAIN_SEPARATOR
        );

        let err = resolve_unpack_output_path(&out_dir, &absolute, &mut seen)
            .expect_err("absolute module path should be rejected");
        assert!(
            err.to_string().contains("path escapes output directory"),
            "unexpected error: {err}"
        );

        fs::remove_dir_all(&dir).expect("remove temp dir");
    }

    #[cfg(windows)]
    #[test]
    fn unpack_output_path_rejects_windows_drive_prefixes() {
        let dir = temp_test_dir("drive-prefix");
        fs::create_dir_all(&dir).expect("create temp dir");
        let out_dir = canonicalize_output_dir(&dir).expect("canonicalize output dir");
        let mut seen = HashSet::new();

        let err = resolve_unpack_output_path(&out_dir, r"C:\tmp\escape.js", &mut seen)
            .expect_err("drive-prefixed module path should be rejected");
        assert!(
            err.to_string().contains("path escapes output directory"),
            "unexpected error: {err}"
        );

        fs::remove_dir_all(&dir).expect("remove temp dir");
    }

    #[test]
    fn unpack_output_path_rejects_parent_directory_that_is_file() {
        let dir = temp_test_dir("file-parent");
        fs::create_dir_all(&dir).expect("create temp dir");
        fs::write(dir.join("src"), "not a directory").expect("write file parent");
        let out_dir = canonicalize_output_dir(&dir).expect("canonicalize output dir");
        let mut seen = HashSet::new();

        let err = resolve_unpack_output_path(&out_dir, "src/index.js", &mut seen)
            .expect_err("file parent should be rejected");
        assert!(
            err.to_string().contains("exists and is not a directory"),
            "unexpected error: {err}"
        );

        fs::remove_dir_all(&dir).expect("remove temp dir");
    }

    #[test]
    fn unpack_output_path_deduplicates_after_safety_checks() {
        let dir = temp_test_dir("dedup");
        fs::create_dir_all(&dir).expect("create temp dir");
        let out_dir = canonicalize_output_dir(&dir).expect("canonicalize output dir");
        let mut seen = HashSet::new();

        let first = resolve_unpack_output_path(&out_dir, "src/index.js", &mut seen)
            .expect("first path should resolve");
        let second = resolve_unpack_output_path(&out_dir, "src/index.js", &mut seen)
            .expect("second path should resolve with suffix");

        assert!(first.starts_with(&out_dir), "{}", first.display());
        assert!(second.starts_with(&out_dir), "{}", second.display());
        assert_ne!(first, second);
        assert_eq!(first.file_name().and_then(|s| s.to_str()), Some("index.js"));
        assert_eq!(
            second.file_name().and_then(|s| s.to_str()),
            Some("index_2.js")
        );

        fs::remove_dir_all(&dir).expect("remove temp dir");
    }

    #[test]
    fn unpack_output_path_rejects_symlink_parent_that_points_outside() {
        let dir = temp_test_dir("symlink-parent");
        let out_dir_raw = dir.join("out");
        let external_dir = dir.join("external");
        fs::create_dir_all(&out_dir_raw).expect("create output dir");
        fs::create_dir_all(&external_dir).expect("create external dir");
        let link_path = out_dir_raw.join("link");
        if create_dir_symlink(&external_dir, &link_path).is_err() {
            fs::remove_dir_all(&dir).expect("remove temp dir");
            return;
        }
        let out_dir = canonicalize_output_dir(&out_dir_raw).expect("canonicalize output dir");
        let mut seen = HashSet::new();

        let err = resolve_unpack_output_path(&out_dir, "link/pwn.js", &mut seen)
            .expect_err("symlink parent escaping output dir should be rejected");
        assert!(
            err.to_string().contains("path escapes output directory"),
            "unexpected error: {err}"
        );

        fs::remove_dir_all(&dir).expect("remove temp dir");
    }

    #[test]
    fn write_if_changed_skips_identical_readonly_file() {
        let dir = temp_test_dir("write-if-changed");
        fs::create_dir_all(&dir).expect("create temp dir");
        let path = dir.join("entry.js");
        fs::write(&path, "same").expect("write temp file");

        let original_permissions = fs::metadata(&path).expect("metadata").permissions();
        let mut permissions = original_permissions.clone();
        permissions.set_readonly(true);
        fs::set_permissions(&path, permissions).expect("set readonly");

        assert!(write_if_changed(&path, "same").is_ok());

        fs::set_permissions(&path, original_permissions).expect("restore permissions");
        fs::remove_dir_all(&dir).expect("remove temp dir");
    }

    #[test]
    fn write_if_changed_overwrites_different_length_file() {
        let dir = temp_test_dir("write-if-changed-length");
        fs::create_dir_all(&dir).expect("create temp dir");
        let path = dir.join("entry.js");
        fs::write(&path, "short").expect("write temp file");

        write_if_changed(&path, "longer content").expect("write changed file");

        assert_eq!(
            fs::read_to_string(&path).expect("read updated file"),
            "longer content"
        );
        fs::remove_dir_all(&dir).expect("remove temp dir");
    }

    #[test]
    fn write_file_creates_and_overwrites() {
        let dir = temp_test_dir("write-file");
        fs::create_dir_all(&dir).expect("create temp dir");
        let path = dir.join("entry.js");

        write_file(&path, "first").expect("write new file");
        assert_eq!(fs::read_to_string(&path).expect("read"), "first");

        write_file(&path, "second").expect("overwrite file");
        assert_eq!(fs::read_to_string(&path).expect("read"), "second");

        fs::remove_dir_all(&dir).expect("remove temp dir");
    }
}