vtcode_commons/

paths.rs

use anyhow::{Context, Result, anyhow, bail};
use std::path::{Component, Path, PathBuf};
use tracing::warn;

/// Normalize a path by resolving `.` and `..` components lexically.
pub fn normalize_path(path: &Path) -> PathBuf {
    let mut normalized = PathBuf::new();
    for component in path.components() {
        match component {
            Component::ParentDir => {
                normalized.pop();
            }
            Component::CurDir => {}
            Component::Prefix(prefix) => normalized.push(prefix.as_os_str()),
            Component::RootDir => normalized.push(component.as_os_str()),
            Component::Normal(part) => normalized.push(part),
        }
    }
    normalized
}

/// Expand a leading `~` or `~/` to the user's home directory. The function is
/// intentionally forgiving: paths that don't start with `~` are returned as-is,
/// and when the home directory cannot be determined the original path is
/// preserved so callers can surface a downstream error rather than panicking.
///
/// This is the canonical implementation used by the tool registry and the
/// sandbox runtime; both call sites previously carried near-identical copies.
pub fn expand_tilde(path: &str) -> PathBuf {
    if path == "~" {
        return dirs::home_dir().unwrap_or_else(|| PathBuf::from(path));
    }
    if let Some(rest) = path.strip_prefix("~/")
        && let Some(home) = dirs::home_dir()
    {
        return home.join(rest);
    }
    PathBuf::from(path)
}

/// Canonicalize a path with fallback to the original path if canonicalization fails.
pub fn canonicalize_workspace(workspace_root: &Path) -> PathBuf {
    std::fs::canonicalize(workspace_root).unwrap_or_else(|error| {
        warn!(
            path = %workspace_root.display(),
            %error,
            "Failed to canonicalize workspace root; falling back to provided path"
        );
        workspace_root.to_path_buf()
    })
}

/// Resolve a path relative to a workspace root and ensure it stays within it.
pub fn resolve_workspace_path(workspace_root: &Path, user_path: &Path) -> Result<PathBuf> {
    let candidate = if user_path.is_absolute() {
        user_path.to_path_buf()
    } else {
        workspace_root.join(user_path)
    };

    let canonical = std::fs::canonicalize(&candidate)
        .with_context(|| format!("Failed to canonicalize path {}", candidate.display()))?;

    let workspace_canonical = std::fs::canonicalize(workspace_root).with_context(|| {
        format!("Failed to canonicalize workspace root {}", workspace_root.display())
    })?;

    if !canonical.starts_with(&workspace_canonical) {
        return Err(anyhow!(
            "Path {} escapes workspace root {}",
            canonical.display(),
            workspace_canonical.display()
        ));
    }

    Ok(canonical)
}

/// Return a canonicalised absolute path that is guaranteed to reside inside the
/// provided `workspace_root`.  If the path is outside the workspace an error is
/// returned.
pub fn secure_path(workspace_root: &Path, user_path: &Path) -> Result<PathBuf> {
    // Resolve relative paths against the workspace root.
    resolve_workspace_path(workspace_root, user_path)
}

/// Ensure a candidate path is inside the workspace root after lexical
/// normalization.
///
/// This is the cheap, filesystem-free tier of workspace containment: it
/// resolves `.`/`..` components lexically but does not follow symlinks. Use
/// [`ensure_path_within_workspace_resolved`] when the candidate may traverse
/// symlinks that point outside the workspace.
///
/// Returns the normalized candidate path on success.
pub fn ensure_path_within_workspace(candidate: &Path, workspace_root: &Path) -> Result<PathBuf> {
    let normalized_candidate = normalize_path(candidate);
    let normalized_workspace = normalize_path(workspace_root);

    if !normalized_candidate.starts_with(&normalized_workspace) {
        bail!("Path '{}' escapes workspace '{}'", candidate.display(), workspace_root.display());
    }

    Ok(normalized_candidate)
}

/// Ensure a candidate path is inside the workspace root, resolving symlinks
/// component by component.
///
/// This is the strict, filesystem-aware tier of workspace containment. On top
/// of the lexical check performed by [`ensure_path_within_workspace`], it
/// walks each component of the candidate below the workspace root and:
///
/// - canonicalizes every existing component and verifies the resolved path
///   still starts with the canonical workspace root (catches symlinks that
///   point outside the workspace);
/// - tolerates nonexistent tail components (paths about to be created);
/// - rejects traversal through a file component (e.g. `file.txt/child`).
///
/// The candidate must already be lexically inside `workspace_root` (both
/// sides are normalized before comparison).
///
/// Returns the normalized candidate path on success.
pub async fn ensure_path_within_workspace_resolved(
    candidate: &Path,
    workspace_root: &Path,
) -> Result<PathBuf> {
    let normalized_root = normalize_path(workspace_root);
    let normalized_candidate = normalize_path(candidate);

    let canonical_root = match tokio::fs::canonicalize(&normalized_root).await {
        Ok(resolved) => resolved,
        Err(error) => {
            warn!(
                path = %normalized_root.display(),
                %error,
                "Failed to canonicalize workspace root; falling back to provided path"
            );
            normalized_root.clone()
        }
    };

    if normalized_root == normalized_candidate {
        return Ok(normalized_candidate);
    }

    let relative = normalized_candidate
        .strip_prefix(&normalized_root)
        .map_err(|_error| anyhow!("path '{}' escapes the workspace root", candidate.display()))?
        .to_path_buf();

    let mut prefix = normalized_root.clone();
    let mut components = relative.components().peekable();

    while let Some(component) = components.next() {
        prefix.push(component.as_os_str());

        let metadata = match tokio::fs::symlink_metadata(&prefix).await {
            Ok(metadata) => metadata,
            Err(error) => {
                if error.kind() == std::io::ErrorKind::NotFound {
                    break;
                }
                return Err(error).with_context(|| {
                    format!("failed to inspect path component '{}'", prefix.display())
                });
            }
        };

        let resolved = tokio::fs::canonicalize(&prefix).await.with_context(|| {
            format!("failed to canonicalize path component '{}'", prefix.display())
        })?;

        if metadata.file_type().is_symlink() {
            if !resolved.starts_with(&canonical_root) {
                return Err(anyhow!(
                    "path '{}' escapes the workspace root via symlink '{}'",
                    candidate.display(),
                    prefix.display()
                ));
            }
        } else {
            if !resolved.starts_with(&canonical_root) {
                return Err(anyhow!(
                    "path '{}' escapes the workspace root via component '{}'",
                    candidate.display(),
                    prefix.display()
                ));
            }

            if metadata.is_file() && components.peek().is_some() {
                return Err(anyhow!(
                    "path '{}' traverses through file component '{}'",
                    candidate.display(),
                    prefix.display()
                ));
            }
        }
    }

    Ok(normalized_candidate)
}

/// Normalize identifiers to ASCII alphanumerics with lowercase output.
pub fn normalize_ascii_identifier(value: &str) -> String {
    let mut normalized = String::new();
    for ch in value.chars() {
        if ch.is_ascii_alphanumeric() {
            normalized.push(ch.to_ascii_lowercase());
        }
    }
    normalized
}

/// Check if a path string is a safe relative path (no traversal, no absolute).
pub fn is_safe_relative_path(path: &str) -> bool {
    let path = path.trim();
    if path.is_empty() {
        return false;
    }

    // Check for path traversal attempts
    if path.contains("..") {
        return false;
    }

    // Block absolute paths for security
    if path.starts_with('/') || path.contains(':') {
        return false;
    }

    true
}

/// Validates that a path is safe to use.
/// Preventing traversal, absolute system paths, and dangerous characters.
///
/// Optimization: Uses early returns and byte-level checks for common patterns
pub fn validate_path_safety(path: &str) -> Result<()> {
    // Optimization: Fast path for empty or very short paths
    if path.is_empty() {
        return Ok(());
    }

    // Reject path traversal attempts
    // Optimization: Use contains on bytes for simple patterns
    if path.contains("..") {
        bail!("Path traversal attempt detected ('..')");
    }

    // Additional traversal patterns
    if path.contains("~/../") || path.contains("/.../") {
        bail!("Advanced path traversal detected");
    }

    // Optimization: Only check Unix critical paths if path starts with '/'
    if path.starts_with('/') {
        // Reject absolute paths outside workspace
        // Note: We can't strictly block all absolute paths as the agent might need to access
        // explicitly allowed directories, but we can block obvious system critical paths.
        static UNIX_CRITICAL: &[&str] = &[
            "/etc", "/usr", "/bin", "/sbin", "/var", "/boot", "/root", "/dev",
        ];
        for prefix in UNIX_CRITICAL {
            let is_var_temp_exception = *prefix == "/var"
                && (path.starts_with("/var/folders/")
                    || path == "/var/folders"
                    || path.starts_with("/var/tmp/")
                    || path == "/var/tmp");

            if !is_var_temp_exception && matches_critical_prefix(path, prefix) {
                bail!("Access to system directory denied: {prefix}");
            }
        }
    }

    // Windows critical paths
    #[cfg(windows)]
    {
        let path_lower = path.to_lowercase();
        static WIN_CRITICAL: &[&str] = &["c:\\windows", "c:\\program files", "c:\\system32"];
        for prefix in WIN_CRITICAL {
            if path_lower.starts_with(prefix) {
                bail!("Access to Windows system directory denied");
            }
        }
    }

    // Reject dangerous shell characters in paths (including null byte)
    // Optimization: Check bytes directly for faster character detection
    static DANGEROUS_CHARS: &[u8] = b"$`|;&\n\r><\0";
    for &c in path.as_bytes() {
        if DANGEROUS_CHARS.contains(&c) {
            bail!("Path contains dangerous shell characters");
        }
    }

    Ok(())
}

fn matches_critical_prefix(path: &str, prefix: &str) -> bool {
    path == prefix || path.strip_prefix(prefix).is_some_and(|rest| rest.starts_with('/'))
}

/// Extract the filename from a path, with fallback to the full path.
pub fn file_name_from_path(path: &str) -> String {
    Path::new(path)
        .file_name()
        .and_then(|name| name.to_str())
        .map(|s| s.to_string())
        .unwrap_or_else(|| path.to_string())
}

/// Canonicalize a path, walking up to find the nearest existing ancestor for new files.
///
/// This function handles paths to files that may not yet exist by finding the
/// nearest existing parent directory, canonicalizing that, and then appending
/// the remaining path components.
///
/// # Security
/// This function is critical for security. It prevents symlink escapes by:
/// 1. Finding the nearest existing ancestor directory
/// 2. Canonicalizing that directory (resolves symlinks)
/// 3. Appending the remaining path components
///
/// # Arguments
/// * `normalized` - A normalized path (output from `normalize_path`)
///
/// # Returns
/// The canonical path, or the normalized path if no parent exists
pub async fn canonicalize_allow_missing(normalized: &Path) -> Result<PathBuf> {
    // If the path exists, canonicalize it directly
    if tokio::fs::try_exists(normalized).await.unwrap_or(false) {
        return tokio::fs::canonicalize(normalized).await.map_err(|e| {
            anyhow!("Failed to resolve canonical path for '{}': {}", normalized.display(), e)
        });
    }

    // Walk up the directory tree to find the nearest existing ancestor
    let mut current = normalized.to_path_buf();
    while let Some(parent) = current.parent() {
        if tokio::fs::try_exists(parent).await.unwrap_or(false) {
            // Canonicalize the existing parent
            let canonical_parent = tokio::fs::canonicalize(parent).await.map_err(|e| {
                anyhow!("Failed to resolve canonical path for '{}': {}", parent.display(), e)
            })?;

            // Get the remaining path components
            let remainder = normalized.strip_prefix(parent).unwrap_or_else(|_| Path::new(""));

            // Return the canonical parent + remaining components
            return if remainder.as_os_str().is_empty() {
                Ok(canonical_parent)
            } else {
                Ok(canonical_parent.join(remainder))
            };
        }
        current = parent.to_path_buf();
    }

    // No existing parent found, return normalized path as-is
    Ok(normalized.to_path_buf())
}

/// Provides the root directories an application uses to store data.
pub trait WorkspacePaths: Send + Sync {
    /// Absolute path to the application's workspace root.
    fn workspace_root(&self) -> &Path;

    /// Returns the directory where configuration files should be stored.
    fn config_dir(&self) -> PathBuf;

    /// Returns an optional cache directory for transient data.
    fn cache_dir(&self) -> Option<PathBuf> {
        None
    }

    /// Returns an optional directory for telemetry or log artifacts.
    fn telemetry_dir(&self) -> Option<PathBuf> {
        None
    }

    /// Determine the [`PathScope`] for a given path based on workspace directories.
    ///
    /// Returns the most specific scope matching the path:
    /// - `Workspace` if under `workspace_root()`
    /// - `Config` if under `config_dir()`
    /// - `Cache` if under `cache_dir()`
    /// - `Telemetry` if under `telemetry_dir()`
    /// - Falls back to `Cache` if no match
    fn scope_for_path(&self, path: &Path) -> PathScope {
        if path.starts_with(self.workspace_root()) {
            return PathScope::Workspace;
        }

        let config_dir = self.config_dir();
        if path.starts_with(&config_dir) {
            return PathScope::Config;
        }

        if let Some(cache_dir) = self.cache_dir()
            && path.starts_with(&cache_dir)
        {
            return PathScope::Cache;
        }

        if let Some(telemetry_dir) = self.telemetry_dir()
            && path.starts_with(&telemetry_dir)
        {
            return PathScope::Telemetry;
        }

        PathScope::Cache
    }
}

/// Helper trait that adds path resolution helpers on top of [`WorkspacePaths`].
pub trait PathResolver: WorkspacePaths {
    /// Resolve a path relative to the workspace root.
    fn resolve<P>(&self, relative: P) -> PathBuf
    where
        P: AsRef<Path>,
    {
        self.workspace_root().join(relative)
    }

    /// Resolve a path within the configuration directory.
    fn resolve_config<P>(&self, relative: P) -> PathBuf
    where
        P: AsRef<Path>,
    {
        self.config_dir().join(relative)
    }
}

impl<T> PathResolver for T where T: WorkspacePaths + ?Sized {}

/// Enumeration describing the conceptual scope of a file path.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PathScope {
    Workspace,
    Config,
    Cache,
    Telemetry,
}

impl PathScope {
    /// Returns a human-readable description used in error messages.
    pub fn description(self) -> &'static str {
        match self {
            Self::Workspace => "workspace",
            Self::Config => "configuration",
            Self::Cache => "cache",
            Self::Telemetry => "telemetry",
        }
    }
}

// ============================================================================
// Extension Traits (Pattern 3: Extension Traits)
// ============================================================================

/// Extension trait that adds path normalization and safety methods to `Path`.
///
/// Delegates to the existing free functions in this module, providing a more
/// ergonomic call-site syntax:
///
/// ```rust
/// use vtcode_commons::paths::PathExt;
/// use std::path::Path;
///
/// let normalized = Path::new("/tmp/project/src/../src/lib.rs").normalize();
/// ```
pub trait PathExt {
    /// Normalize a path by resolving `.` and `..` components lexically.
    fn normalize(&self) -> PathBuf;

    /// Canonicalize with fallback to the original path if canonicalization fails.
    fn canonicalize_or_self(&self) -> PathBuf;

    /// Extract the filename from a path as a `String`, with fallback to the
    /// full path when no filename component exists.
    ///
    /// Unlike [`Path::file_name`] which returns `Option<&OsStr>`, this method
    /// always returns a `String` and falls back gracefully.
    fn file_name_str(&self) -> String;
}

impl PathExt for Path {
    fn normalize(&self) -> PathBuf {
        normalize_path(self)
    }

    fn canonicalize_or_self(&self) -> PathBuf {
        canonicalize_workspace(self)
    }

    fn file_name_str(&self) -> String {
        self.file_name()
            .and_then(|name| name.to_str())
            .map(|s| s.to_string())
            .unwrap_or_else(|| self.to_string_lossy().into_owned())
    }
}

/// Extension trait that adds path-related methods to `str`.
///
/// Provides ergonomic access to tilde expansion and path safety checks:
///
/// ```rust
/// use vtcode_commons::paths::StrPathExt;
///
/// let expanded = "~/projects/vtcode".expand_tilde();
/// assert!(StrPathExt::is_safe_path("src/main.rs"));
/// ```
pub trait StrPathExt {
    /// Expand a leading `~` or `~/` to the user's home directory.
    fn expand_tilde(&self) -> PathBuf;

    /// Check if this path string is a safe relative path (no traversal, no absolute).
    fn is_safe_path(&self) -> bool;

    /// Validate that this path is safe to use (no traversal, no dangerous characters).
    fn validate_safety(&self) -> Result<()>;

    /// Extract the filename from this path string.
    fn file_name_str(&self) -> String;
}

impl StrPathExt for str {
    fn expand_tilde(&self) -> PathBuf {
        expand_tilde(self)
    }

    fn is_safe_path(&self) -> bool {
        is_safe_relative_path(self)
    }

    fn validate_safety(&self) -> Result<()> {
        validate_path_safety(self)
    }

    fn file_name_str(&self) -> String {
        file_name_from_path(self)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::path::{Path, PathBuf};

    struct StaticPaths {
        root: PathBuf,
        config: PathBuf,
    }

    impl WorkspacePaths for StaticPaths {
        fn workspace_root(&self) -> &Path {
            &self.root
        }

        fn config_dir(&self) -> PathBuf {
            self.config.clone()
        }

        fn cache_dir(&self) -> Option<PathBuf> {
            Some(self.root.join("cache"))
        }
    }

    #[test]
    fn resolves_relative_paths() {
        let paths = StaticPaths {
            root: PathBuf::from("/tmp/project"),
            config: PathBuf::from("/tmp/project/config"),
        };

        assert_eq!(
            PathResolver::resolve(&paths, "subdir/file.txt"),
            PathBuf::from("/tmp/project/subdir/file.txt")
        );
        assert_eq!(
            PathResolver::resolve_config(&paths, "settings.toml"),
            PathBuf::from("/tmp/project/config/settings.toml")
        );
        assert_eq!(paths.cache_dir(), Some(PathBuf::from("/tmp/project/cache")));
    }

    #[test]
    fn ensures_path_within_workspace_accepts_nested_path() {
        let workspace = Path::new("/tmp/project");
        let candidate = Path::new("/tmp/project/src/../src/lib.rs");
        let normalized = ensure_path_within_workspace(candidate, workspace).unwrap();
        assert_eq!(normalized, PathBuf::from("/tmp/project/src/lib.rs"));
    }

    #[test]
    fn ensures_path_within_workspace_rejects_escape() {
        let workspace = Path::new("/tmp/project");
        let candidate = Path::new("/tmp/project/../../etc/passwd");
        assert!(ensure_path_within_workspace(candidate, workspace).is_err());
    }

    #[tokio::test]
    async fn resolved_check_accepts_nested_existing_path() {
        let workspace = tempfile::tempdir().unwrap();
        let root = workspace.path().canonicalize().unwrap();
        let nested = root.join("src");
        tokio::fs::create_dir_all(&nested).await.unwrap();
        let file = nested.join("lib.rs");
        tokio::fs::write(&file, b"test").await.unwrap();

        let result = ensure_path_within_workspace_resolved(&file, &root).await;
        assert_eq!(result.unwrap(), file);
    }

    #[tokio::test]
    async fn resolved_check_accepts_missing_tail_components() {
        let workspace = tempfile::tempdir().unwrap();
        let root = workspace.path().canonicalize().unwrap();
        let missing = root.join("new_dir/new_file.txt");

        let result = ensure_path_within_workspace_resolved(&missing, &root).await;
        assert_eq!(result.unwrap(), missing);
    }

    #[tokio::test]
    async fn resolved_check_rejects_lexical_escape() {
        let workspace = tempfile::tempdir().unwrap();
        let root = workspace.path().canonicalize().unwrap();
        let escape = root.join("../outside.txt");

        assert!(ensure_path_within_workspace_resolved(&escape, &root).await.is_err());
    }

    #[cfg(unix)]
    #[tokio::test]
    async fn resolved_check_rejects_symlink_escape() {
        let workspace = tempfile::tempdir().unwrap();
        let outside = tempfile::tempdir().unwrap();
        let root = workspace.path().canonicalize().unwrap();
        let outside_dir = outside.path().canonicalize().unwrap();

        let link = root.join("escape");
        tokio::fs::symlink(&outside_dir, &link).await.unwrap();

        let candidate = link.join("secret.txt");
        assert!(ensure_path_within_workspace_resolved(&candidate, &root).await.is_err());
    }

    #[cfg(unix)]
    #[tokio::test]
    async fn resolved_check_accepts_symlink_within_workspace() {
        let workspace = tempfile::tempdir().unwrap();
        let root = workspace.path().canonicalize().unwrap();
        let target = root.join("real");
        tokio::fs::create_dir_all(&target).await.unwrap();
        let link = root.join("alias");
        tokio::fs::symlink(&target, &link).await.unwrap();

        let candidate = link.join("file.txt");
        assert!(ensure_path_within_workspace_resolved(&candidate, &root).await.is_ok());
    }

    #[tokio::test]
    async fn resolved_check_rejects_traversal_through_file() {
        let workspace = tempfile::tempdir().unwrap();
        let root = workspace.path().canonicalize().unwrap();
        let file = root.join("data.txt");
        tokio::fs::write(&file, b"test").await.unwrap();

        let candidate = file.join("child.txt");
        assert!(ensure_path_within_workspace_resolved(&candidate, &root).await.is_err());
    }

    #[tokio::test]
    async fn test_canonicalize_existing_file() {
        // Create a temporary directory and file
        let temp_dir = std::env::temp_dir();
        let test_file = temp_dir.join("vtcode_test_existing.txt");
        tokio::fs::write(&test_file, b"test").await.unwrap();

        let canonical = canonicalize_allow_missing(&test_file).await.unwrap();

        // Should get the canonical path
        assert!(canonical.is_absolute());
        assert!(canonical.exists());

        // Cleanup
        tokio::fs::remove_file(&test_file).await.ok();
    }

    #[tokio::test]
    async fn test_canonicalize_missing_file() {
        // Use a path that doesn't exist but has an existing parent
        let temp_dir = std::env::temp_dir();
        let missing_file = temp_dir.join("vtcode_test_missing_dir/missing_file.txt");

        let canonical = canonicalize_allow_missing(&missing_file).await.unwrap();

        // Should get canonical parent + missing components
        assert!(canonical.is_absolute());
        assert!(canonical.to_string_lossy().contains("missing_file.txt"));
    }

    #[tokio::test]
    async fn test_canonicalize_deeply_missing_path() {
        // Use a path with multiple missing parent directories
        let temp_dir = std::env::temp_dir();
        let deep_missing = temp_dir.join("vtcode_test_a/b/c/d/file.txt");

        let canonical = canonicalize_allow_missing(&deep_missing).await.unwrap();

        // Should get canonical temp_dir + missing components
        assert!(canonical.is_absolute());
        assert!(canonical.to_string_lossy().contains("vtcode_test_a"));
    }

    #[tokio::test]
    async fn test_canonicalize_missing_file_with_existing_parent() {
        // Create a parent directory
        let temp_dir = std::env::temp_dir();
        let test_dir = temp_dir.join("vtcode_test_parent");
        tokio::fs::create_dir_all(&test_dir).await.unwrap();

        let missing_file = test_dir.join("missing.txt");
        let canonical = canonicalize_allow_missing(&missing_file).await.unwrap();

        // Should get canonical parent + missing filename
        assert!(canonical.is_absolute());
        assert!(canonical.to_string_lossy().ends_with("missing.txt"));

        // Cleanup
        tokio::fs::remove_dir(&test_dir).await.ok();
    }

    #[test]
    fn expand_tilde_passes_through_absolute_paths() {
        let absolute = "/etc/hosts";
        assert_eq!(expand_tilde(absolute), PathBuf::from(absolute));
    }

    #[test]
    fn expand_tilde_passes_through_relative_paths() {
        let relative = "src/main.rs";
        assert_eq!(expand_tilde(relative), PathBuf::from(relative));
    }

    #[test]
    fn expand_tilde_resolves_bare_tilde_to_home() {
        if let Some(home) = dirs::home_dir() {
            assert_eq!(expand_tilde("~"), home);
        }
    }

    #[test]
    fn expand_tilde_resolves_tilde_slash_prefix() {
        if let Some(home) = dirs::home_dir() {
            let resolved = expand_tilde("~/projects/vtcode");
            assert_eq!(resolved, home.join("projects/vtcode"));
        }
    }
}