roma_core/

path.rs

//! Safe path resolution helpers.
//!
//! [`safe_resolve`] takes a user-supplied path and a trusted base directory,
//! and returns an absolute path that is guaranteed to live under `base`.
//! It refuses:
//!
//! 1. Any lexical `..` component (`Component::ParentDir`).
//! 2. Absolute paths (`Component::RootDir` / `Component::Prefix`).
//! 3. Paths that, after symlink resolution of the existing prefix,
//!    escape the canonicalized `base`.
//!
//! The function is designed to be safe for callers that want to create a
//! file that does not yet exist: only the longest existing ancestor is
//! canonicalized (which resolves symlinks), while the non-existent tail
//! is appended lexically.

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

/// Errors returned by [`safe_resolve`].
#[derive(Debug, thiserror::Error)]
pub enum PathError {
    /// The user path contains a `..` component.
    #[error("path traversal denied: {0}")]
    Traversal(String),
    /// The user path is absolute (starts with `/` or a drive prefix).
    #[error("absolute path not allowed: {0}")]
    AbsolutePath(String),
    /// The resolved path lies outside the canonicalized base.
    #[error("path escapes base directory: {0}")]
    EscapesBase(String),
    /// I/O error while canonicalizing the base or an existing ancestor.
    #[error("io error: {0}")]
    Io(#[from] std::io::Error),
}

/// Resolve `user_path` relative to `base`, refusing absolute paths,
/// `..` traversal, and (after canonicalization) any path that escapes
/// `base`.
///
/// `base` must already exist on disk; it is canonicalized once per call.
/// `user_path` may reference a not-yet-existing file: the longest
/// existing ancestor is canonicalized and the remaining components are
/// appended lexically, so a later `create_dir_all` / `write` will create
/// the new entries under the canonicalized base without a TOCTOU on the
/// non-existent tail.
///
/// Empty `user_path` resolves to the canonicalized `base`.
pub fn safe_resolve(base: &Path, user_path: &Path) -> Result<PathBuf, PathError> {
    // 1. Lexical checks: no absolute root, no parent-dir components.
    for comp in user_path.components() {
        match comp {
            Component::ParentDir => {
                return Err(PathError::Traversal(user_path.display().to_string()));
            }
            Component::RootDir | Component::Prefix(_) => {
                return Err(PathError::AbsolutePath(user_path.display().to_string()));
            }
            _ => {}
        }
    }

    let base_canon = base.canonicalize()?;

    // 2. Accumulate components onto the canonicalized base. Walk the
    //    existing prefix greedily — canonicalizing after each push so
    //    symlinks are resolved — and append the remaining (non-existent)
    //    tail lexically.
    let mut resolved = base_canon.clone();
    let mut tail_started = false;
    for comp in user_path.components() {
        match comp {
            Component::Normal(seg) => {
                if tail_started {
                    resolved.push(seg);
                    continue;
                }
                let candidate = resolved.join(seg);
                match candidate.canonicalize() {
                    Ok(c) => {
                        resolved = c;
                    }
                    Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
                        // Entry does not exist yet: append lexically from
                        // here on and stop canonicalizing.
                        resolved.push(seg);
                        tail_started = true;
                    }
                    Err(e) => return Err(PathError::Io(e)),
                }
            }
            // CurDir components are harmless (`.`); skip.
            Component::CurDir => {}
            // Filtered above.
            Component::ParentDir | Component::RootDir | Component::Prefix(_) => {
                return Err(PathError::Traversal(user_path.display().to_string()));
            }
        }
    }

    // 3. Boundary check: every step above either kept us inside
    //    `base_canon` (canonicalize of existing ancestor) or appended a
    //    lexical component after we were already inside. Still verify
    //    explicitly — cheap and defensive.
    if !resolved.starts_with(&base_canon) {
        return Err(PathError::EscapesBase(resolved.display().to_string()));
    }

    Ok(resolved)
}

#[cfg(test)]
#[allow(clippy::expect_used, clippy::unwrap_used)]
mod tests {
    use super::*;
    use tempfile::TempDir;

    #[test]
    fn accepts_simple_relative_path() {
        let base = TempDir::new().unwrap();
        std::fs::write(base.path().join("a.txt"), "x").unwrap();
        let resolved = safe_resolve(base.path(), Path::new("a.txt")).unwrap();
        assert_eq!(resolved, base.path().canonicalize().unwrap().join("a.txt"));
    }

    #[test]
    fn accepts_nested_relative_path() {
        let base = TempDir::new().unwrap();
        std::fs::create_dir_all(base.path().join("sub")).unwrap();
        std::fs::write(base.path().join("sub/a.txt"), "x").unwrap();
        let resolved = safe_resolve(base.path(), Path::new("sub/a.txt")).unwrap();
        let expected = base
            .path()
            .canonicalize()
            .unwrap()
            .join("sub")
            .join("a.txt");
        assert_eq!(resolved, expected);
    }

    #[test]
    fn accepts_nonexistent_leaf_under_base() {
        let base = TempDir::new().unwrap();
        let resolved = safe_resolve(base.path(), Path::new("new.txt")).unwrap();
        assert_eq!(
            resolved,
            base.path().canonicalize().unwrap().join("new.txt")
        );
    }

    #[test]
    fn accepts_nonexistent_nested_leaf() {
        let base = TempDir::new().unwrap();
        let resolved = safe_resolve(base.path(), Path::new("a/b/c.txt")).unwrap();
        let expected = base
            .path()
            .canonicalize()
            .unwrap()
            .join("a")
            .join("b")
            .join("c.txt");
        assert_eq!(resolved, expected);
    }

    #[test]
    fn accepts_curdir_components() {
        let base = TempDir::new().unwrap();
        let resolved = safe_resolve(base.path(), Path::new("./x.txt")).unwrap();
        assert_eq!(resolved, base.path().canonicalize().unwrap().join("x.txt"));
    }

    #[test]
    fn rejects_parent_dir_component() {
        let base = TempDir::new().unwrap();
        let err = safe_resolve(base.path(), Path::new("../escape.txt")).unwrap_err();
        assert!(matches!(err, PathError::Traversal(_)));
    }

    #[test]
    fn rejects_embedded_parent_dir() {
        let base = TempDir::new().unwrap();
        let err = safe_resolve(base.path(), Path::new("a/../../etc/passwd")).unwrap_err();
        assert!(matches!(err, PathError::Traversal(_)));
    }

    #[test]
    fn rejects_absolute_path() {
        let base = TempDir::new().unwrap();
        let err = safe_resolve(base.path(), Path::new("/etc/passwd")).unwrap_err();
        assert!(matches!(err, PathError::AbsolutePath(_)));
    }

    #[test]
    fn rejects_missing_base() {
        let base = TempDir::new().unwrap();
        let missing = base.path().join("does_not_exist");
        let err = safe_resolve(&missing, Path::new("x")).unwrap_err();
        assert!(matches!(err, PathError::Io(_)));
    }

    #[cfg(unix)]
    #[test]
    fn rejects_symlink_escaping_base() {
        let outside = TempDir::new().unwrap();
        std::fs::write(outside.path().join("secret"), "top-secret").unwrap();

        let base = TempDir::new().unwrap();
        // base/link -> outside
        std::os::unix::fs::symlink(outside.path(), base.path().join("link")).unwrap();

        let err = safe_resolve(base.path(), Path::new("link/secret")).unwrap_err();
        assert!(
            matches!(err, PathError::EscapesBase(_)),
            "expected EscapesBase, got {err:?}"
        );
    }

    #[cfg(unix)]
    #[test]
    fn accepts_symlink_pointing_inside_base() {
        let base = TempDir::new().unwrap();
        std::fs::create_dir_all(base.path().join("real")).unwrap();
        std::fs::write(base.path().join("real/data"), "ok").unwrap();
        std::os::unix::fs::symlink(base.path().join("real"), base.path().join("alias")).unwrap();

        let resolved = safe_resolve(base.path(), Path::new("alias/data")).unwrap();
        // Must be inside the canonical base.
        assert!(resolved.starts_with(base.path().canonicalize().unwrap()));
    }

    #[cfg(unix)]
    #[test]
    fn rejects_symlink_parent_with_nonexistent_leaf() {
        // base/link -> /tmp/elsewhere; then user asks for `link/new.txt`.
        // The leaf doesn't exist, but the parent resolves outside — must reject.
        let outside = TempDir::new().unwrap();
        let base = TempDir::new().unwrap();
        std::os::unix::fs::symlink(outside.path(), base.path().join("link")).unwrap();

        let err = safe_resolve(base.path(), Path::new("link/new.txt")).unwrap_err();
        assert!(
            matches!(err, PathError::EscapesBase(_)),
            "expected EscapesBase, got {err:?}"
        );
    }

    #[test]
    fn empty_path_resolves_to_base() {
        let base = TempDir::new().unwrap();
        let resolved = safe_resolve(base.path(), Path::new("")).unwrap();
        assert_eq!(resolved, base.path().canonicalize().unwrap());
    }
}