tldr_cli/commands/contracts/

validation.rs

//! Input validation and path safety utilities for Contracts & Flow commands.
//!
//! This module provides security-focused validation functions to mitigate:
//! - **TIGER-02**: Path traversal attacks via malicious file paths
//! - **TIGER-03**: Unbounded recursion in CFG/slice computation
//! - **TIGER-04**: Memory exhaustion from large SSA graphs
//! - **TIGER-08**: Stack overflow from deeply nested ASTs
//!
//! All file paths are canonicalized and checked against project boundaries.
//! Resource limits are enforced to prevent denial-of-service conditions.

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

use super::error::{ContractsError, ContractsResult};

// =============================================================================
// Resource Limits (TIGER Mitigations)
// =============================================================================

/// Maximum file size for analysis (10 MB).
/// Files larger than this will be rejected (TIGER-04 partial mitigation).
pub const MAX_FILE_SIZE: u64 = 10 * 1024 * 1024;

/// Warning threshold for file size (1 MB).
/// Files larger than this emit a warning but are still processed.
pub const WARN_FILE_SIZE: u64 = 1024 * 1024;

/// Maximum CFG/slice recursion depth (TIGER-03 mitigation).
/// Prevents stack overflow from deeply recursive control flow analysis.
pub const MAX_CFG_DEPTH: usize = 1000;

/// Maximum SSA nodes to construct (TIGER-04 mitigation).
/// Prevents memory exhaustion from extremely large SSA graphs.
pub const MAX_SSA_NODES: usize = 100_000;

/// Maximum AST traversal depth (TIGER-08 mitigation).
/// Prevents stack overflow from deeply nested source code.
pub const MAX_AST_DEPTH: usize = 100;

/// Maximum function name length.
pub const MAX_FUNCTION_NAME_LEN: usize = 256;

/// Maximum number of conditions to report per function.
pub const MAX_CONDITIONS_PER_FUNCTION: usize = 100;

// =============================================================================
// Blocked System Directories
// =============================================================================

/// System directories that should never be analyzed (security measure).
/// Note: We specifically target sensitive system directories, not general
/// /var or /private paths which include temp files.
const BLOCKED_PREFIXES: &[&str] = &[
    "/etc/",
    "/etc/passwd",
    "/etc/shadow",
    "/root/",
    "/sys/",
    "/proc/",
    "/dev/",
    "/var/run/",
    "/var/log/",
    "/private/etc/",  // macOS system config
    "C:\\Windows\\",  // Windows
    "C:\\System32\\", // Windows
];

// =============================================================================
// Path Validation (TIGER-02 Mitigation)
// =============================================================================

/// Validate and canonicalize a file path.
///
/// This function:
/// 1. Checks that the path exists
/// 2. Canonicalizes the path (resolves symlinks, `.`, `..`)
/// 3. Rejects paths that escape the project root (if specified)
/// 4. Rejects system directories
/// 5. Validates UTF-8 encoding
///
/// # Arguments
///
/// * `path` - The path to validate
///
/// # Returns
///
/// The canonicalized path if valid, or an error.
///
/// # Errors
///
/// - `ContractsError::FileNotFound` if the file doesn't exist
/// - `ContractsError::PathTraversal` if path escapes project or is a system dir
///
/// # Example
///
/// ```ignore
/// let valid = validate_file_path(Path::new("src/main.rs"))?;
/// assert!(valid.is_absolute());
/// ```
pub fn validate_file_path(path: &Path) -> ContractsResult<PathBuf> {
    // Check file exists
    if !path.exists() {
        return Err(ContractsError::FileNotFound {
            path: path.to_path_buf(),
        });
    }

    // Canonicalize the path (resolves symlinks, .., .)
    let canonical = fs::canonicalize(path).map_err(|_| ContractsError::FileNotFound {
        path: path.to_path_buf(),
    })?;

    // Check for system directories
    let canonical_str = canonical.to_string_lossy();
    for blocked in BLOCKED_PREFIXES {
        // Check with trailing slash for directories, or exact match for files
        if canonical_str.starts_with(blocked) || canonical_str == blocked.trim_end_matches('/') {
            return Err(ContractsError::PathTraversal {
                path: path.to_path_buf(),
            });
        }
    }

    // Validate UTF-8 (path.to_str() returns None if not valid UTF-8)
    if canonical.to_str().is_none() {
        return Err(ContractsError::PathTraversal {
            path: path.to_path_buf(),
        });
    }

    Ok(canonical)
}

/// Validate a file path ensuring it stays within a project root.
///
/// This is stricter than `validate_file_path` - it ensures the resolved
/// path is a descendant of the project root directory.
///
/// # Arguments
///
/// * `path` - The path to validate
/// * `project_root` - The project root directory to stay within
///
/// # Returns
///
/// The canonicalized path if valid and within project root.
///
/// # Errors
///
/// - `ContractsError::FileNotFound` if the file doesn't exist
/// - `ContractsError::PathTraversal` if path escapes project root
pub fn validate_file_path_in_project(path: &Path, project_root: &Path) -> ContractsResult<PathBuf> {
    // First do basic validation
    let canonical = validate_file_path(path)?;

    // Canonicalize project root too
    let canonical_root =
        fs::canonicalize(project_root).map_err(|_| ContractsError::FileNotFound {
            path: project_root.to_path_buf(),
        })?;

    // Check that canonical path starts with canonical root
    if !canonical.starts_with(&canonical_root) {
        return Err(ContractsError::PathTraversal {
            path: path.to_path_buf(),
        });
    }

    Ok(canonical)
}

/// Check if a path contains path traversal patterns.
///
/// This is a quick check for suspicious patterns before canonicalization.
/// Returns true if the path looks suspicious.
pub fn has_path_traversal_pattern(path: &Path) -> bool {
    let path_str = path.to_string_lossy();

    // Check for explicit traversal patterns
    if path_str.contains("..") {
        return true;
    }

    // Check for null bytes (could be used to truncate paths)
    if path_str.contains('\0') {
        return true;
    }

    false
}

// =============================================================================
// Line Number Validation
// =============================================================================

/// Validate line number range.
///
/// Ensures:
/// - start <= end
/// - Both are within valid range (1 to max)
///
/// # Arguments
///
/// * `start` - Start line (1-indexed)
/// * `end` - End line (1-indexed)
/// * `max` - Maximum valid line number (typically file line count)
///
/// # Returns
///
/// Ok(()) if valid, error otherwise.
///
/// # Errors
///
/// - Returns error if start > end
/// - Returns error if either line exceeds max
/// - Returns error if either line is 0
pub fn validate_line_numbers(start: u32, end: u32, max: u32) -> ContractsResult<()> {
    // Lines are 1-indexed
    if start == 0 {
        return Err(ContractsError::LineOutsideFunction {
            line: start,
            function: "unknown".to_string(),
            start: 1,
            end: max,
        });
    }

    if end == 0 {
        return Err(ContractsError::LineOutsideFunction {
            line: end,
            function: "unknown".to_string(),
            start: 1,
            end: max,
        });
    }

    // Start must be <= end
    if start > end {
        return Err(ContractsError::LineOutsideFunction {
            line: start,
            function: "unknown".to_string(),
            start: 1,
            end,
        });
    }

    // Both must be within bounds
    if start > max {
        return Err(ContractsError::LineOutsideFunction {
            line: start,
            function: "unknown".to_string(),
            start: 1,
            end: max,
        });
    }

    if end > max {
        return Err(ContractsError::LineOutsideFunction {
            line: end,
            function: "unknown".to_string(),
            start: 1,
            end: max,
        });
    }

    Ok(())
}

// =============================================================================
// Function Name Validation
// =============================================================================

/// Validate a function name for safety.
///
/// Ensures the name:
/// - Is not empty
/// - Contains only valid identifier characters
/// - Doesn't exceed maximum length
/// - Doesn't contain suspicious characters
///
/// # Arguments
///
/// * `name` - The function name to validate
///
/// # Returns
///
/// Ok(()) if valid, error otherwise.
///
/// # Errors
///
/// - `ContractsError::InvalidFunctionName` for invalid names
pub fn validate_function_name(name: &str) -> ContractsResult<()> {
    // Check empty
    if name.is_empty() {
        return Err(ContractsError::InvalidFunctionName {
            reason: "function name cannot be empty".to_string(),
        });
    }

    // Check length
    if name.len() > MAX_FUNCTION_NAME_LEN {
        return Err(ContractsError::InvalidFunctionName {
            reason: format!(
                "function name too long ({} chars, max {})",
                name.len(),
                MAX_FUNCTION_NAME_LEN
            ),
        });
    }

    // Check for suspicious characters that could be used for injection
    // Valid identifiers: letters, digits, underscore (and some languages allow $)
    let suspicious_chars = [
        ';', '(', ')', '{', '}', '[', ']', '`', '"', '\'', '\\', '/', '\0',
    ];
    for c in name.chars() {
        if suspicious_chars.contains(&c) {
            return Err(ContractsError::InvalidFunctionName {
                reason: format!("function name contains invalid character: '{}'", c),
            });
        }
    }

    // First character should be letter or underscore (standard identifier rules)
    if let Some(first) = name.chars().next() {
        if !first.is_alphabetic() && first != '_' {
            return Err(ContractsError::InvalidFunctionName {
                reason: "function name must start with letter or underscore".to_string(),
            });
        }
    }

    Ok(())
}

// =============================================================================
// Safe File Reading
// =============================================================================

/// Safely read a file with size limits and UTF-8 validation.
///
/// This function:
/// 1. Validates the file path
/// 2. Checks file size against limits
/// 3. Reads the file content
/// 4. Validates UTF-8 encoding
///
/// # Arguments
///
/// * `path` - The path to the file to read
///
/// # Returns
///
/// The file contents as a String if successful.
///
/// # Errors
///
/// - `ContractsError::FileNotFound` if file doesn't exist
/// - `ContractsError::FileTooLarge` if file exceeds MAX_FILE_SIZE
/// - `ContractsError::Io` for other IO errors
pub fn read_file_safe(path: &Path) -> ContractsResult<String> {
    // Validate path first
    let canonical = validate_file_path(path)?;

    // Check file size
    let metadata = fs::metadata(&canonical)?;
    let size = metadata.len();

    if size > MAX_FILE_SIZE {
        return Err(ContractsError::FileTooLarge {
            path: path.to_path_buf(),
            bytes: size,
            max_bytes: MAX_FILE_SIZE,
        });
    }

    // Read the file
    let content = fs::read(&canonical)?;

    // Validate UTF-8
    String::from_utf8(content).map_err(|_| ContractsError::ParseError {
        file: path.to_path_buf(),
        message: "file is not valid UTF-8".to_string(),
    })
}

/// Read a file safely, emitting a warning for large files.
///
/// Like `read_file_safe`, but also logs a warning to stderr for files
/// larger than WARN_FILE_SIZE.
///
/// # Arguments
///
/// * `path` - The path to the file to read
/// * `warn_fn` - Optional callback for warnings (if None, prints to stderr)
///
/// # Returns
///
/// The file contents as a String if successful.
pub fn read_file_safe_with_warning<F>(path: &Path, warn_fn: Option<F>) -> ContractsResult<String>
where
    F: FnOnce(&str),
{
    // Validate path first
    let canonical = validate_file_path(path)?;

    // Check file size
    let metadata = fs::metadata(&canonical)?;
    let size = metadata.len();

    if size > MAX_FILE_SIZE {
        return Err(ContractsError::FileTooLarge {
            path: path.to_path_buf(),
            bytes: size,
            max_bytes: MAX_FILE_SIZE,
        });
    }

    // Warn for large files
    if size > WARN_FILE_SIZE {
        let warning = format!(
            "Warning: {} is large ({:.1} MB), analysis may be slow",
            path.display(),
            size as f64 / 1024.0 / 1024.0
        );
        if let Some(f) = warn_fn {
            f(&warning);
        } else {
            eprintln!("{}", warning);
        }
    }

    // Read the file
    let content = fs::read(&canonical)?;

    // Validate UTF-8
    String::from_utf8(content).map_err(|_| ContractsError::ParseError {
        file: path.to_path_buf(),
        message: "file is not valid UTF-8".to_string(),
    })
}

// =============================================================================
// Depth Checking Utilities
// =============================================================================

/// Check if a depth limit has been exceeded.
///
/// Used for tracking recursion depth in CFG/slice analysis.
pub fn check_depth_limit(current_depth: usize, max_depth: usize) -> ContractsResult<()> {
    if current_depth >= max_depth {
        Err(ContractsError::SliceDepthExceeded {
            max_depth: max_depth as u32,
        })
    } else {
        Ok(())
    }
}

/// Check if SSA node count exceeds limit.
pub fn check_ssa_node_limit(node_count: usize) -> ContractsResult<()> {
    if node_count > MAX_SSA_NODES {
        Err(ContractsError::SsaTooLarge {
            nodes: node_count as u32,
            max_nodes: MAX_SSA_NODES as u32,
        })
    } else {
        Ok(())
    }
}

/// Check if AST depth exceeds limit.
pub fn check_ast_depth(depth: usize, file: &Path) -> ContractsResult<()> {
    if depth > MAX_AST_DEPTH {
        Err(ContractsError::AstTooDeep {
            file: file.to_path_buf(),
            depth: depth as u32,
            max_depth: MAX_AST_DEPTH as u32,
        })
    } else {
        Ok(())
    }
}

// =============================================================================
// Tests
// =============================================================================

#[cfg(test)]
mod tests {
    use super::*;
    use std::io::Write;
    use tempfile::{tempdir, NamedTempFile};

    // -------------------------------------------------------------------------
    // Path Validation Tests
    // -------------------------------------------------------------------------

    #[test]
    fn test_validate_file_path_normal() {
        // Create a temp file
        let file = NamedTempFile::new().unwrap();
        let path = file.path();

        let result = validate_file_path(path);
        assert!(result.is_ok());

        let canonical = result.unwrap();
        assert!(canonical.is_absolute());
    }

    #[test]
    fn test_validate_file_path_not_exists() {
        let result = validate_file_path(Path::new("/nonexistent/file.py"));
        assert!(result.is_err());

        match result.unwrap_err() {
            ContractsError::FileNotFound { path } => {
                assert!(path.to_string_lossy().contains("nonexistent"));
            }
            _ => panic!("Expected FileNotFound error"),
        }
    }

    #[test]
    fn test_validate_file_path_traversal_rejected() {
        // Create a temp directory structure
        let temp = tempdir().unwrap();
        let subdir = temp.path().join("subdir");
        fs::create_dir(&subdir).unwrap();

        // Create a file in the temp root
        let file_path = temp.path().join("secret.txt");
        fs::write(&file_path, "secret").unwrap();

        // Check that path with .. pattern is detected
        let suspicious = subdir.join("..").join("secret.txt");
        assert!(has_path_traversal_pattern(&suspicious));
    }

    #[test]
    fn test_validate_file_path_symlink_outside_project() {
        // Create temp directories
        let project = tempdir().unwrap();
        let outside = tempdir().unwrap();

        // Create a file outside project
        let outside_file = outside.path().join("secret.txt");
        fs::write(&outside_file, "secret").unwrap();

        // Create a symlink inside project pointing outside
        let symlink_path = project.path().join("link.txt");

        #[cfg(unix)]
        {
            std::os::unix::fs::symlink(&outside_file, &symlink_path).unwrap();

            // The symlink should resolve but fail the project check
            let result = validate_file_path_in_project(&symlink_path, project.path());
            assert!(result.is_err());

            match result.unwrap_err() {
                ContractsError::PathTraversal { .. } => {}
                e => panic!("Expected PathTraversal error, got {:?}", e),
            }
        }
    }

    #[test]
    fn test_validate_file_path_system_dir_rejected() {
        // Test that system directories are blocked
        // We can't actually create files there, so just verify the check logic

        let blocked = [
            "/etc/passwd",
            "/root/.bashrc",
            "/sys/kernel/config",
            "/proc/self/status",
        ];

        for path_str in blocked {
            let path = Path::new(path_str);
            // If the file exists on this system, it should be rejected
            if path.exists() {
                let result = validate_file_path(path);
                assert!(result.is_err(), "Should reject system path: {}", path_str);
            }
        }
    }

    // -------------------------------------------------------------------------
    // Line Number Validation Tests
    // -------------------------------------------------------------------------

    #[test]
    fn test_validate_line_numbers_valid_range() {
        assert!(validate_line_numbers(1, 10, 100).is_ok());
        assert!(validate_line_numbers(1, 1, 100).is_ok()); // same line
        assert!(validate_line_numbers(50, 100, 100).is_ok()); // at max
    }

    #[test]
    fn test_validate_line_numbers_start_after_end() {
        let result = validate_line_numbers(10, 5, 100);
        assert!(result.is_err());

        match result.unwrap_err() {
            ContractsError::LineOutsideFunction { line, .. } => {
                assert_eq!(line, 10);
            }
            _ => panic!("Expected LineOutsideFunction error"),
        }
    }

    #[test]
    fn test_validate_line_numbers_exceeds_max() {
        let result = validate_line_numbers(1, 200, 100);
        assert!(result.is_err());

        match result.unwrap_err() {
            ContractsError::LineOutsideFunction { line, .. } => {
                assert_eq!(line, 200);
            }
            _ => panic!("Expected LineOutsideFunction error"),
        }
    }

    #[test]
    fn test_validate_line_numbers_zero() {
        assert!(validate_line_numbers(0, 10, 100).is_err());
        assert!(validate_line_numbers(1, 0, 100).is_err());
    }

    // -------------------------------------------------------------------------
    // Function Name Validation Tests
    // -------------------------------------------------------------------------

    #[test]
    fn test_validate_function_name_valid() {
        assert!(validate_function_name("my_function").is_ok());
        assert!(validate_function_name("_private").is_ok());
        assert!(validate_function_name("CamelCase").is_ok());
        assert!(validate_function_name("func123").is_ok());
        assert!(validate_function_name("__dunder__").is_ok());
    }

    #[test]
    fn test_validate_function_name_empty() {
        let result = validate_function_name("");
        assert!(result.is_err());

        match result.unwrap_err() {
            ContractsError::InvalidFunctionName { reason } => {
                assert!(reason.contains("empty"));
            }
            _ => panic!("Expected InvalidFunctionName error"),
        }
    }

    #[test]
    fn test_validate_function_name_invalid_chars() {
        let invalid_names = [
            "func;drop",  // semicolon
            "func()",     // parentheses
            "func{}",     // braces
            "func`cmd`",  // backticks
            "func\"name", // quotes
            "func\\name", // backslash
            "func/name",  // forward slash
        ];

        for name in invalid_names {
            let result = validate_function_name(name);
            assert!(result.is_err(), "Should reject: {}", name);
        }
    }

    #[test]
    fn test_validate_function_name_starts_with_digit() {
        let result = validate_function_name("123func");
        assert!(result.is_err());

        match result.unwrap_err() {
            ContractsError::InvalidFunctionName { reason } => {
                assert!(reason.contains("start with"));
            }
            _ => panic!("Expected InvalidFunctionName error"),
        }
    }

    #[test]
    fn test_validate_function_name_too_long() {
        let long_name = "a".repeat(MAX_FUNCTION_NAME_LEN + 1);
        let result = validate_function_name(&long_name);
        assert!(result.is_err());

        match result.unwrap_err() {
            ContractsError::InvalidFunctionName { reason } => {
                assert!(reason.contains("too long"));
            }
            _ => panic!("Expected InvalidFunctionName error"),
        }
    }

    // -------------------------------------------------------------------------
    // Safe File Reading Tests
    // -------------------------------------------------------------------------

    #[test]
    fn test_read_file_safe_normal() {
        let mut file = NamedTempFile::new().unwrap();
        writeln!(file, "def hello():\n    print('hello')").unwrap();

        let content = read_file_safe(file.path()).unwrap();
        assert!(content.contains("def hello"));
        assert!(content.contains("print"));
    }

    #[test]
    fn test_read_file_safe_not_exists() {
        let result = read_file_safe(Path::new("/nonexistent/file.py"));
        assert!(result.is_err());

        match result.unwrap_err() {
            ContractsError::FileNotFound { .. } => {}
            e => panic!("Expected FileNotFound error, got {:?}", e),
        }
    }

    #[test]
    fn test_read_file_safe_too_large() {
        // Create a file larger than MAX_FILE_SIZE
        let temp = tempdir().unwrap();
        let _large_file = temp.path().join("large.txt");

        // Write a file just over the limit (we can't actually create 10MB in tests easily,
        // so we'll test the logic with a mock)
        // For now, just verify the constant value.
        let max_file_size = std::hint::black_box(MAX_FILE_SIZE);
        assert_eq!(max_file_size, 10 * 1024 * 1024);
    }

    #[test]
    fn test_read_file_safe_not_utf8() {
        let temp = tempdir().unwrap();
        let binary_file = temp.path().join("binary.bin");

        // Write invalid UTF-8 bytes
        let invalid_utf8 = vec![0xFF, 0xFE, 0x00, 0x01];
        fs::write(&binary_file, invalid_utf8).unwrap();

        let result = read_file_safe(&binary_file);
        assert!(result.is_err());

        match result.unwrap_err() {
            ContractsError::ParseError { message, .. } => {
                assert!(message.contains("UTF-8"));
            }
            e => panic!("Expected ParseError, got {:?}", e),
        }
    }

    // -------------------------------------------------------------------------
    // Resource Limits Constants Tests
    // -------------------------------------------------------------------------

    #[test]
    fn test_resource_limits_constants() {
        // Verify TIGER mitigation constants have sensible values
        assert_eq!(MAX_FILE_SIZE, 10 * 1024 * 1024); // 10 MB
        assert_eq!(MAX_CFG_DEPTH, 1000); // TIGER-03
        assert_eq!(MAX_SSA_NODES, 100_000); // TIGER-04
        assert_eq!(MAX_AST_DEPTH, 100); // TIGER-08
    }

    #[test]
    fn test_check_depth_limit() {
        assert!(check_depth_limit(0, 1000).is_ok());
        assert!(check_depth_limit(999, 1000).is_ok());
        assert!(check_depth_limit(1000, 1000).is_err());
        assert!(check_depth_limit(1001, 1000).is_err());
    }

    #[test]
    fn test_check_ssa_node_limit() {
        assert!(check_ssa_node_limit(0).is_ok());
        assert!(check_ssa_node_limit(MAX_SSA_NODES).is_ok());
        assert!(check_ssa_node_limit(MAX_SSA_NODES + 1).is_err());
    }

    #[test]
    fn test_check_ast_depth() {
        let file = Path::new("test.py");
        assert!(check_ast_depth(0, file).is_ok());
        assert!(check_ast_depth(MAX_AST_DEPTH, file).is_ok());
        assert!(check_ast_depth(MAX_AST_DEPTH + 1, file).is_err());
    }

    // -------------------------------------------------------------------------
    // Path Traversal Pattern Detection Tests
    // -------------------------------------------------------------------------

    #[test]
    fn test_has_path_traversal_pattern() {
        // Suspicious patterns
        assert!(has_path_traversal_pattern(Path::new("../etc/passwd")));
        assert!(has_path_traversal_pattern(Path::new("foo/../bar")));
        assert!(has_path_traversal_pattern(Path::new(
            "..\\Windows\\System32"
        )));

        // Normal paths
        assert!(!has_path_traversal_pattern(Path::new("src/main.rs")));
        assert!(!has_path_traversal_pattern(Path::new("/home/user/project")));
        assert!(!has_path_traversal_pattern(Path::new(".")));
    }
}