Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust
18.6 KB
Raw Blame
//! Destination-path safety for export and sync.
//!
//! Page paths arrive from the server as untrusted data. Every relative wiki
//! path is validated into a portable shape before it is ever joined onto the
//! destination directory, so a hostile server cannot escape `--dest`, clobber
//! dotfiles, or plant names that behave differently across filesystems.

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

use anyhow::{Context, Result, bail};

/// Longest wiki path accepted, in bytes. Stays well under the shortest
/// common filesystem limit once joined onto a repository path.
pub const MAX_PATH_BYTES: usize = 180;
/// Longest single path segment accepted, in bytes.
pub const MAX_SEGMENT_BYTES: usize = 64;
/// Deepest wiki path accepted, in segments.
pub const MAX_DEPTH: usize = 8;

/// Windows reserved device stems: `CON`, `PRN`, `AUX`, `NUL`, `COM1`-`COM9`,
/// `LPT1`-`LPT9` (the stem is the part before the first dot, so `CON.md`
/// and `con.x.md` are both refused).
const RESERVED_STEMS: &[&str] = &[
    "CON", "PRN", "AUX", "NUL", "COM1", "COM2", "COM3", "COM4", "COM5", "COM6", "COM7", "COM8",
    "COM9", "LPT1", "LPT2", "LPT3", "LPT4", "LPT5", "LPT6", "LPT7", "LPT8", "LPT9",
];

fn is_reserved_stem(segment: &str) -> bool {
    let stem = segment.split('.').next().unwrap_or_default();
    RESERVED_STEMS.contains(&stem.to_ascii_uppercase().as_str())
}

/// One portable path segment: ASCII letters, digits, dot, dash, underscore.
/// No leading dot (this also refuses `.`, `..` and `.git`), no trailing dot
/// (Windows quirk), no reserved device stem.
fn valid_segment(segment: &str) -> bool {
    !segment.is_empty()
        && segment.len() <= MAX_SEGMENT_BYTES
        && segment
            .bytes()
            .all(|b| b.is_ascii_alphanumeric() || matches!(b, b'.' | b'-' | b'_'))
        && !segment.starts_with('.')
        && !segment.ends_with('.')
        && !is_reserved_stem(segment)
}

/// Validate one `--include` family: a single top-level wiki directory name.
/// The allowlist is explicit by design, so a bare `*` (or any wildcard) is
/// refused with its own message instead of a generic charset complaint.
pub fn validate_family(raw: &str) -> Result<()> {
    if raw == "*" {
        bail!("--include '*' is refused: the family allowlist must be explicit");
    }
    if raw.contains(['*', '?', '[', ']']) {
        bail!("--include {raw}: wildcards are not allowed; name concrete families");
    }
    if !valid_segment(raw) {
        bail!(
            "--include {raw}: not a portable directory name (ASCII letters, digits, '.', '-', '_'; \
             no leading dot, no reserved Windows name)"
        );
    }
    Ok(())
}

/// The family of a wiki path is its first segment. A bare top-level page
/// (`README.md`) is its own family and only matches an identically named
/// `--include` value.
pub fn family_of(path: &str) -> &str {
    path.split('/').next().unwrap_or(path)
}

/// Validate a server-reported wiki path before anything is joined onto
/// `--dest`. Refuses traversal, absolute paths, backslashes, dotfiles,
/// non-portable characters, oversized names and non-`.md` leaves.
pub fn validate_page_path(raw: &str) -> Result<()> {
    if raw.is_empty() {
        bail!("empty page path");
    }
    if raw.len() > MAX_PATH_BYTES {
        bail!("page path longer than {MAX_PATH_BYTES} bytes: {raw}");
    }
    if raw.starts_with('/') {
        bail!("absolute page path refused: {raw}");
    }
    if raw.contains('\\') || raw.contains('\0') || raw.bytes().any(|b| !b.is_ascii()) {
        bail!("non-portable page path refused: {raw:?}");
    }
    let segments: Vec<&str> = raw.split('/').collect();
    if segments.len() > MAX_DEPTH {
        bail!("page path deeper than {MAX_DEPTH} segments: {raw}");
    }
    for segment in &segments {
        if !valid_segment(segment) {
            bail!("non-portable path segment refused in {raw}: {segment:?}");
        }
    }
    let last = segments[segments.len() - 1];
    if !last.ends_with(".md") {
        bail!("page path does not end in .md: {raw}");
    }
    Ok(())
}

/// Refuse a set of pages whose destination paths collide once case-folded.
/// Linux is case-sensitive but macOS and Windows checkouts are not, and a
/// collision would silently clobber depending on the platform.
pub fn ensure_no_case_fold_collisions(paths: &[String]) -> Result<()> {
    let mut seen: std::collections::BTreeMap<String, &str> = std::collections::BTreeMap::new();
    for path in paths {
        let folded = path.to_ascii_lowercase();
        if let Some(first) = seen.get(folded.as_str())
            && *first != path.as_str()
        {
            bail!(
                "case-fold collision between server pages {first:?} and {path:?}; \
                 refusing to export both into one destination"
            );
        }
        seen.entry(folded).or_insert(path.as_str());
    }
    Ok(())
}

/// Join a validated relative wiki path onto the destination root, refusing
/// the join if any existing component on the way is a symlink. Components
/// that do not exist yet are fine: the writer creates them as real
/// directories. An existing non-final component that is not a directory is
/// refused so a file named like a family cannot swallow writes.
pub fn secure_join(dest_root: &Path, rel: &str) -> Result<PathBuf> {
    validate_page_path(rel)?;
    let segments: Vec<&str> = rel.split('/').collect();
    let mut current = dest_root.to_path_buf();
    for (index, segment) in segments.iter().enumerate() {
        current.push(segment);
        match fs::symlink_metadata(&current) {
            Ok(meta) => {
                if meta.file_type().is_symlink() {
                    bail!("refusing path through symlink: {}", current.display());
                }
                let is_last = index + 1 == segments.len();
                if !is_last && !meta.is_dir() {
                    bail!("path component is not a directory: {}", current.display());
                }
            }
            Err(e) if e.kind() == io::ErrorKind::NotFound => {}
            Err(e) => {
                return Err(anyhow::Error::new(e))
                    .context(format!("cannot inspect {}", current.display()));
            }
        }
    }
    Ok(current)
}

/// Absolute path with `.` and `..` resolved lexically, without following
/// symlinks. Comparing this against `canonicalize` detects any symlink on
/// the way to the destination.
pub fn lexical_absolute(path: &Path) -> PathBuf {
    let absolute = if path.is_absolute() {
        path.to_path_buf()
    } else {
        match std::env::current_dir() {
            Ok(cwd) => cwd.join(path),
            Err(_) => return path.to_path_buf(),
        }
    };
    let mut normalized = PathBuf::new();
    for component in absolute.components() {
        match component {
            Component::CurDir => {}
            Component::ParentDir => {
                normalized.pop();
            }
            other => normalized.push(other.as_os_str()),
        }
    }
    normalized
}

#[cfg(not(windows))]
fn destination_paths_match(canonical: &Path, lexical: &Path) -> bool {
    canonical == lexical
}

#[cfg(windows)]
fn destination_paths_match(canonical: &Path, lexical: &Path) -> bool {
    use std::path::Prefix;

    // Windows canonicalization adds a verbatim prefix even when no link was
    // followed. Compare the remaining components without resolving lexical:
    // resolving both paths would hide junctions and ancestor symlinks.
    let mut canonical = canonical.components();
    let mut lexical = lexical.components();
    let same_prefix = match (canonical.next(), lexical.next()) {
        (Some(Component::Prefix(left)), Some(Component::Prefix(right))) => {
            match (left.kind(), right.kind()) {
                (
                    Prefix::Disk(left) | Prefix::VerbatimDisk(left),
                    Prefix::Disk(right) | Prefix::VerbatimDisk(right),
                ) => left.eq_ignore_ascii_case(&right),
                (
                    Prefix::UNC(left_server, left_share)
                    | Prefix::VerbatimUNC(left_server, left_share),
                    Prefix::UNC(right_server, right_share)
                    | Prefix::VerbatimUNC(right_server, right_share),
                ) => left_server == right_server && left_share == right_share,
                (left, right) => left == right,
            }
        }
        (left, right) => left == right,
    };
    same_prefix && canonical.eq(lexical)
}

/// Prepare the destination directory: create it when missing, then refuse
/// symlinked destinations (including any symlinked component on the way —
/// on Windows this also catches junction/reparse targets via the
/// canonical-versus-lexical comparison) and non-directories. Returns the
/// canonical root every later join is anchored to.
pub fn prepare_dest(dest: &Path) -> Result<PathBuf> {
    match fs::symlink_metadata(dest) {
        Ok(meta) => {
            if meta.file_type().is_symlink() {
                bail!("--dest is a symlink; pass the real directory instead");
            }
            if !meta.is_dir() {
                bail!("--dest exists and is not a directory");
            }
        }
        Err(e) if e.kind() == io::ErrorKind::NotFound => {
            fs::create_dir_all(dest)
                .with_context(|| format!("cannot create --dest {}", dest.display()))?;
        }
        Err(e) => {
            return Err(anyhow::Error::new(e))
                .context(format!("cannot inspect --dest {}", dest.display()));
        }
    }
    let lexical = lexical_absolute(dest);
    let canonical = fs::canonicalize(dest)
        .with_context(|| format!("cannot canonicalize --dest {}", dest.display()))?;
    if !destination_paths_match(&canonical, &lexical) {
        bail!(
            "--dest reaches through a symlink ({} -> {}); pass the resolved path instead",
            lexical.display(),
            canonical.display()
        );
    }
    Ok(canonical)
}

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

    #[test]
    fn accepts_portable_page_paths() {
        for path in [
            "decisions/0007-db.md",
            "notes/deep/nested/path/is/fine.md",
            "_rules/keep-dashes_and.dots.md",
            "README.md",
            "conduct.md",
        ] {
            validate_page_path(path).unwrap_or_else(|e| panic!("{path}: {e}"));
        }
        assert_eq!(family_of("decisions/0007-db.md"), "decisions");
        assert_eq!(family_of("README.md"), "README.md");
    }

    #[test]
    fn refuses_traversal_and_absolute_paths() {
        for path in [
            "../escape.md",
            "notes/../../escape.md",
            "/etc/passwd.md",
            "notes//double.md",
            "notes/./here.md",
            "notes/.hidden.md",
            "notes/.git/config.md",
            "",
        ] {
            assert!(validate_page_path(path).is_err(), "should refuse {path:?}");
        }
    }

    #[test]
    fn refuses_non_portable_segments() {
        for path in [
            "notes/with space.md",
            "notes/with*glob.md",
            "notes/trailing.md.",
            "notes/COM1.md",
            "notes/com2.lower.md",
            "notes/lpt9.md",
            "notes/beyond\u{e9}.md",
            "notes/readme.markdown",
            "notes/not-md.txt",
            "very/deep/path/that/goes/on/and/on/forever/here.md",
        ] {
            assert!(validate_page_path(path).is_err(), "should refuse {path:?}");
        }
        let long = format!("notes/{}.md", "a".repeat(MAX_SEGMENT_BYTES));
        assert!(validate_page_path(&long).is_err());
        let deep = format!("{}.md", ["d"; MAX_DEPTH + 1].join("/"));
        assert!(validate_page_path(&deep).is_err());
    }

    #[test]
    fn family_allowlist_is_explicit() {
        assert!(validate_family("decisions").is_ok());
        assert!(validate_family("_rules").is_ok());
        // The explicit allowlist rule: bare '*' and wildcards are refused
        // with their own message, not a generic charset error.
        let star = validate_family("*").unwrap_err().to_string();
        assert!(star.contains("must be explicit"), "{star}");
        assert!(validate_family("notes*").is_err());
        assert!(validate_family("..").is_err());
        assert!(validate_family("a/b").is_err());
        assert!(validate_family("").is_err());
    }

    #[test]
    fn detects_case_fold_collisions() {
        assert!(
            ensure_no_case_fold_collisions(&[
                "notes/a.md".to_string(),
                "decisions/b.md".to_string(),
            ])
            .is_ok()
        );
        let err =
            ensure_no_case_fold_collisions(&["Notes/a.md".to_string(), "notes/A.md".to_string()])
                .unwrap_err()
                .to_string();
        assert!(err.contains("case-fold collision"), "{err}");
    }

    #[test]
    fn prepare_dest_refuses_symlinks_and_files() {
        let tmp = tempfile::tempdir().unwrap();
        let dest = tmp.path().canonicalize().unwrap();

        assert_eq!(prepare_dest(&dest).unwrap(), dest);

        let child = dest.join("real");
        fs::create_dir_all(&child).unwrap();
        assert_eq!(prepare_dest(&child).unwrap(), child);

        #[cfg(unix)]
        {
            let link = dest.join("link");
            std::os::unix::fs::symlink(&child, &link).unwrap();
            let err = prepare_dest(&link).unwrap_err().to_string();
            assert!(err.contains("symlink"), "{err}");
            // A symlinked *component* on the way is refused too.
            let through = link.join("sub");
            let err = prepare_dest(&through).unwrap_err().to_string();
            assert!(err.contains("symlink"), "{err}");
        }

        let file = dest.join("file");
        fs::write(&file, b"x").unwrap();
        let err = prepare_dest(&file).unwrap_err().to_string();
        assert!(err.contains("not a directory"), "{err}");
    }

    #[test]
    fn prepare_dest_creates_missing_directories() {
        let tmp = tempfile::tempdir().unwrap();
        let dest = tmp.path().canonicalize().unwrap().join("a/b/c");
        let made = prepare_dest(&dest).unwrap();
        assert!(made.is_dir());
    }

    #[cfg(windows)]
    #[test]
    fn prepare_dest_accepts_plain_windows_absolute_paths() {
        // Windows TEMP may use an 8.3 alias, which exercises a different
        // canonicalization change from the verbatim prefix under test.
        let tmp = tempfile::tempdir_in(std::env::current_dir().unwrap()).unwrap();
        let dest = tmp.path().join("wiki").join("nested");
        assert_eq!(prepare_dest(&dest).unwrap(), dest.canonicalize().unwrap());
        assert_eq!(
            prepare_dest(tmp.path()).unwrap(),
            tmp.path().canonicalize().unwrap()
        );
    }

    #[cfg(windows)]
    #[test]
    fn prepare_dest_accepts_windows_relative_paths() {
        let cwd = std::env::current_dir().unwrap();
        let tmp = tempfile::tempdir_in(&cwd).unwrap();
        let relative = tmp.path().strip_prefix(&cwd).unwrap().join("wiki");
        assert!(!relative.is_absolute());
        assert_eq!(
            prepare_dest(&relative).unwrap(),
            tmp.path().join("wiki").canonicalize().unwrap()
        );
    }

    #[cfg(windows)]
    #[test]
    fn windows_destination_prefixes_do_not_hide_different_paths() {
        for (canonical, lexical) in [
            (r"\\?\C:\wiki", r"C:\wiki"),
            (r"\\?\C:\wiki", r"c:\wiki"),
            (r"\\?\UNC\server\share\wiki", r"\\server\share\wiki"),
            (r"\\?\C:\wiki", r"\\?\C:\wiki"),
        ] {
            assert!(destination_paths_match(
                Path::new(canonical),
                Path::new(lexical)
            ));
        }
        for (canonical, lexical) in [
            (r"\\?\C:\outside", r"C:\wiki"),
            (r"\\?\C:\wiki", r"D:\wiki"),
            (r"\\?\UNC\server\share\wiki", r"\\server\other\wiki"),
            (r"\\?\UNC\server\share\wiki", r"\\other\share\wiki"),
            (r"\\?\Volume{one}\wiki", r"\\?\Volume{two}\wiki"),
        ] {
            assert!(!destination_paths_match(
                Path::new(canonical),
                Path::new(lexical)
            ));
        }
    }

    #[cfg(windows)]
    #[test]
    fn prepare_dest_refuses_windows_junctions_without_touching_the_target() {
        let tmp = tempfile::tempdir_in(std::env::current_dir().unwrap()).unwrap();
        let outside = tmp.path().join("outside");
        let child = outside.join("child");
        fs::create_dir_all(&child).unwrap();
        let canary = child.join("canary.md");
        fs::write(&canary, b"untouched").unwrap();
        assert_eq!(prepare_dest(&child).unwrap(), child.canonicalize().unwrap());

        let junction = tmp.path().join("junction");
        // A junction needs no symlink privilege. Paths stay data in the
        // child environment, including shell metacharacters in a temp root.
        let output = std::process::Command::new("powershell.exe")
            .args([
                "-NoProfile",
                "-NonInteractive",
                "-Command",
                "$ErrorActionPreference = 'Stop'; New-Item -ItemType Junction -Path $env:WIKISYNC_TEST_LINK -Target $env:WIKISYNC_TEST_TARGET | Out-Null",
            ])
            .env("WIKISYNC_TEST_LINK", &junction)
            .env("WIKISYNC_TEST_TARGET", &outside)
            .output()
            .unwrap();
        assert!(
            output.status.success(),
            "{}",
            String::from_utf8_lossy(&output.stderr)
        );

        for dest in [&junction, &junction.join("child")] {
            let err = prepare_dest(dest).unwrap_err().to_string();
            assert!(err.contains("symlink"), "{err}");
        }
        assert_eq!(fs::read(&canary).unwrap(), b"untouched");
        assert_eq!(fs::read_dir(&child).unwrap().count(), 1);
        fs::remove_dir(&junction).unwrap();
        assert!(canary.is_file());
    }

    #[test]
    fn secure_join_stays_under_root_and_refuses_symlink_components() {
        let tmp = tempfile::tempdir().unwrap();
        let root = tmp.path().canonicalize().unwrap();
        let joined = secure_join(&root, "notes/page.md").unwrap();
        assert_eq!(joined, root.join("notes/page.md"));
        assert!(secure_join(&root, "../escape.md").is_err());

        #[cfg(unix)]
        {
            fs::create_dir_all(root.join("notes")).unwrap();
            std::os::unix::fs::symlink("/tmp", root.join("notes/elsewhere")).unwrap();
            let err = secure_join(&root, "notes/elsewhere/page.md")
                .unwrap_err()
                .to_string();
            assert!(err.contains("symlink"), "{err}");
        }

        // A file squatting on a family directory name is refused.
        fs::write(root.join("blob.md"), b"x").unwrap();
        assert!(secure_join(&root, "blob.md/child.md").is_err());
    }
}