backup_suite/core/

validation.rs

/// Input validation module
///
/// Provides comprehensive input validation and sanitization functions
/// to prevent security vulnerabilities:
/// - Command injection
/// - Path traversal attacks
/// - Null byte injection
/// - Excessively long inputs (DoS prevention)
use anyhow::{bail, Context, Result};
use regex::Regex;
use std::path::{Path, PathBuf};

/// Maximum allowed input length to prevent DoS attacks
const MAX_INPUT_LENGTH: usize = 1000;

/// Maximum path component length
const MAX_PATH_COMPONENT_LENGTH: usize = 255;

/// Validate and sanitize general user input
///
/// Applies whitelist-based validation allowing only safe characters:
/// - Alphanumeric characters (a-zA-Z0-9)
/// - Whitespace
/// - Common safe punctuation: . _ / -
///
/// # Security Considerations
/// - Prevents command injection by rejecting shell metacharacters
/// - Blocks null bytes
/// - Limits input length to prevent DoS
///
/// # Errors
/// Returns error if input contains disallowed characters or exceeds length limit
///
/// # Examples
/// ```
/// use backup_suite::core::validation::validate_input;
///
/// // Valid inputs
/// assert!(validate_input("backup_2024-01-15").is_ok());
/// assert!(validate_input("user/documents").is_ok());
///
/// // Invalid inputs (shell metacharacters)
/// assert!(validate_input("test; rm -rf /").is_err());
/// assert!(validate_input("test | cat /etc/passwd").is_err());
/// assert!(validate_input("test && malicious").is_err());
/// ```
pub fn validate_input(input: &str) -> Result<()> {
    // Check for null bytes first (critical security check)
    if input.contains('\0') {
        bail!("Invalid input: null byte detected");
    }

    // Length limit to prevent DoS
    if input.len() > MAX_INPUT_LENGTH {
        bail!(
            "Input too long: {} characters (max: {} characters)",
            input.len(),
            MAX_INPUT_LENGTH
        );
    }

    // Whitelist of allowed characters (alphanumeric, whitespace, and safe punctuation)
    let allowed_chars = Regex::new(r"^[a-zA-Z0-9\s._/-]+$")?;

    if !allowed_chars.is_match(input) {
        bail!("Invalid input: contains disallowed characters (only alphanumeric, spaces, '.', '_', '/', '-' are allowed)");
    }

    Ok(())
}

/// Sanitize string by removing control characters
///
/// Removes all control characters except whitespace (space, tab, newline).
/// This provides defense-in-depth even when used after `validate_input`.
///
/// # Security Considerations
/// - Removes null bytes
/// - Removes other control characters that could interfere with terminal output
/// - Preserves legitimate whitespace
///
/// # Errors
/// Returns error if null byte is detected (fail-fast for security)
///
/// # Examples
/// ```
/// use backup_suite::core::validation::sanitize_string;
///
/// // Normal text passes through
/// assert_eq!(sanitize_string("Hello World").unwrap(), "Hello World");
///
/// // Null bytes are rejected
/// assert!(sanitize_string("test\0malicious").is_err());
///
/// // Control characters are removed
/// assert_eq!(sanitize_string("test\x01\x02data").unwrap(), "testdata");
/// ```
pub fn sanitize_string(input: &str) -> Result<String> {
    // Null byte check (critical security validation)
    if input.contains('\0') {
        bail!("Null byte detected in input");
    }

    // Remove control characters except whitespace
    let sanitized: String = input
        .chars()
        .filter(|c| !c.is_control() || c.is_whitespace())
        .collect();

    Ok(sanitized)
}

/// Validate file path and prevent path traversal attacks
///
/// Performs comprehensive path validation:
/// 1. Canonicalizes path (resolves symlinks, relative components)
/// 2. Validates against allowed base directory
/// 3. Checks component lengths
/// 4. Validates file name characters
///
/// # Security Considerations
/// - Prevents path traversal (../ attacks)
/// - Protects against symlink attacks
/// - Validates path components
/// - Ensures path stays within allowed directory
///
/// # Errors
/// Returns error if:
/// - Path does not exist (canonicalize fails)
/// - Path escapes allowed base directory
/// - Path components exceed length limits
/// - Path contains invalid characters
///
/// # Examples
/// ```no_run
/// use backup_suite::core::validation::validate_path;
/// use std::path::PathBuf;
/// use std::env;
///
/// let current_dir = env::current_dir().unwrap();
/// let safe_path = current_dir.join("backup/data.txt");
///
/// // Valid path within current directory
/// assert!(validate_path(&safe_path, &current_dir).is_ok());
///
/// // Invalid: path traversal attempt
/// let malicious = PathBuf::from("/tmp/../../etc/passwd");
/// assert!(validate_path(&malicious, &current_dir).is_err());
/// ```
pub fn validate_path(path: &Path, allowed_base: &Path) -> Result<PathBuf> {
    // Canonicalize both paths (resolves symlinks and relative components)
    let canonical_path = path
        .canonicalize()
        .with_context(|| format!("Invalid path: {}", path.display()))?;

    let canonical_base = allowed_base
        .canonicalize()
        .with_context(|| format!("Invalid base directory: {}", allowed_base.display()))?;

    // Ensure path is within allowed base directory
    if !canonical_path.starts_with(&canonical_base) {
        bail!(
            "Path traversal detected: {} is outside allowed directory {}",
            canonical_path.display(),
            canonical_base.display()
        );
    }

    // Validate each path component
    for component in canonical_path.components() {
        if let Some(component_str) = component.as_os_str().to_str() {
            // Check component length
            if component_str.len() > MAX_PATH_COMPONENT_LENGTH {
                bail!(
                    "Path component too long: {} (max: {})",
                    component_str.len(),
                    MAX_PATH_COMPONENT_LENGTH
                );
            }

            // Check for null bytes in path component
            if component_str.contains('\0') {
                bail!("Null byte detected in path component");
            }
        }
    }

    Ok(canonical_path)
}

/// Validate file name (without directory components)
///
/// Ensures file name contains only safe characters and is not empty.
///
/// # Security Considerations
/// - Prevents shell metacharacters in file names
/// - Blocks null bytes
/// - Rejects overly long names
///
/// # Errors
/// Returns error if:
/// - Name is empty
/// - Name is too long (>255 characters)
/// - Name contains disallowed characters
///
/// # Examples
/// ```
/// use backup_suite::core::validation::validate_filename;
///
/// // Valid file names
/// assert!(validate_filename("backup_2024-01-15.tar.gz").is_ok());
/// assert!(validate_filename("user_data.txt").is_ok());
///
/// // Invalid file names
/// assert!(validate_filename("").is_err());
/// assert!(validate_filename("test;rm -rf").is_err());
/// assert!(validate_filename("file\0malicious").is_err());
/// ```
pub fn validate_filename(name: &str) -> Result<()> {
    // Check for empty name
    if name.is_empty() {
        bail!("File name cannot be empty");
    }

    // Length check
    if name.len() > MAX_PATH_COMPONENT_LENGTH {
        bail!(
            "File name too long: {} characters (max: {})",
            name.len(),
            MAX_PATH_COMPONENT_LENGTH
        );
    }

    // Null byte check
    if name.contains('\0') {
        bail!("Null byte detected in file name");
    }

    // Whitelist: alphanumeric, dots, underscores, hyphens
    let allowed_chars = Regex::new(r"^[a-zA-Z0-9._-]+$")?;

    if !allowed_chars.is_match(name) {
        bail!("Invalid file name: contains disallowed characters (only alphanumeric, '.', '_', '-' are allowed)");
    }

    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::env;
    use tempfile::TempDir;

    // ═══════════════════════════════════════════════════════════════
    // validate_input tests
    // ═══════════════════════════════════════════════════════════════

    #[test]
    fn test_validate_input_valid() {
        assert!(validate_input("backup_2024-01-15").is_ok());
        assert!(validate_input("user documents").is_ok());
        assert!(validate_input("path/to/file").is_ok());
        assert!(validate_input("123-456_789.txt").is_ok());
    }

    #[test]
    fn test_validate_input_shell_metacharacters() {
        assert!(validate_input("test; rm -rf /").is_err());
        assert!(validate_input("test | cat /etc/passwd").is_err());
        assert!(validate_input("test && malicious").is_err());
        assert!(validate_input("test $(whoami)").is_err());
        assert!(validate_input("test `whoami`").is_err());
        assert!(validate_input("test > output").is_err());
        assert!(validate_input("test < input").is_err());
    }

    #[test]
    fn test_validate_input_null_byte() {
        assert!(validate_input("test\0malicious").is_err());
        assert!(validate_input("\0").is_err());
    }

    #[test]
    fn test_validate_input_too_long() {
        let long_input = "a".repeat(MAX_INPUT_LENGTH + 1);
        assert!(validate_input(&long_input).is_err());
    }

    #[test]
    fn test_validate_input_max_length_ok() {
        let max_input = "a".repeat(MAX_INPUT_LENGTH);
        assert!(validate_input(&max_input).is_ok());
    }

    // ═══════════════════════════════════════════════════════════════
    // sanitize_string tests
    // ═══════════════════════════════════════════════════════════════

    #[test]
    fn test_sanitize_string_normal() {
        assert_eq!(sanitize_string("Hello World").unwrap(), "Hello World");
        assert_eq!(sanitize_string("test 123").unwrap(), "test 123");
    }

    #[test]
    fn test_sanitize_string_null_byte() {
        assert!(sanitize_string("test\0malicious").is_err());
        assert!(sanitize_string("\0").is_err());
    }

    #[test]
    fn test_sanitize_string_control_characters() {
        // Control characters (except whitespace) should be removed
        assert_eq!(sanitize_string("test\x01\x02data").unwrap(), "testdata");
        assert_eq!(
            sanitize_string("hello\x1b[31mworld").unwrap(),
            "hello[31mworld"
        );
    }

    #[test]
    fn test_sanitize_string_preserve_whitespace() {
        assert_eq!(sanitize_string("hello\nworld").unwrap(), "hello\nworld");
        assert_eq!(sanitize_string("tab\there").unwrap(), "tab\there");
    }

    // ═══════════════════════════════════════════════════════════════
    // validate_path tests
    // ═══════════════════════════════════════════════════════════════

    #[test]
    fn test_validate_path_within_base() {
        let temp_dir = TempDir::new().unwrap();
        let base = temp_dir.path();

        // Create test file
        let test_file = base.join("test.txt");
        std::fs::write(&test_file, "test").unwrap();

        // Should succeed - file within base directory
        assert!(validate_path(&test_file, base).is_ok());
    }

    #[test]
    fn test_validate_path_nonexistent() {
        let temp_dir = TempDir::new().unwrap();
        let base = temp_dir.path();
        let nonexistent = base.join("nonexistent");

        // Should fail - file doesn't exist (canonicalize fails)
        assert!(validate_path(&nonexistent, base).is_err());
    }

    #[test]
    fn test_validate_path_escape_attempt() {
        let current_dir = env::current_dir().unwrap();

        // Try to escape to parent directory
        let escape_path = current_dir.join("../../../etc/passwd");

        // Should fail if trying to access outside current directory
        // NOTE: This test might succeed on some systems if /etc/passwd
        // happens to be a descendant of current_dir. The test demonstrates
        // the validation logic.
        if escape_path.exists() && escape_path.canonicalize().is_ok() {
            let result = validate_path(&escape_path, &current_dir);
            // Either error or success is acceptable depending on actual path relationship
            let _ = result;
        }
    }

    #[test]
    fn test_validate_path_long_component() {
        let temp_dir = TempDir::new().unwrap();
        let base = temp_dir.path();

        // Create file with very long name
        let long_name = "a".repeat(MAX_PATH_COMPONENT_LENGTH + 1);
        let long_path = base.join(&long_name);

        // Try to create file (might fail on some filesystems)
        if std::fs::write(&long_path, "test").is_ok() {
            assert!(validate_path(&long_path, base).is_err());
        }
    }

    // ═══════════════════════════════════════════════════════════════
    // validate_filename tests
    // ═══════════════════════════════════════════════════════════════

    #[test]
    fn test_validate_filename_valid() {
        assert!(validate_filename("backup.tar.gz").is_ok());
        assert!(validate_filename("data_2024-01-15.txt").is_ok());
        assert!(validate_filename("file-123.zip").is_ok());
    }

    #[test]
    fn test_validate_filename_empty() {
        assert!(validate_filename("").is_err());
    }

    #[test]
    fn test_validate_filename_too_long() {
        let long_name = "a".repeat(MAX_PATH_COMPONENT_LENGTH + 1);
        assert!(validate_filename(&long_name).is_err());
    }

    #[test]
    fn test_validate_filename_null_byte() {
        assert!(validate_filename("test\0.txt").is_err());
    }

    #[test]
    fn test_validate_filename_shell_metacharacters() {
        assert!(validate_filename("test;rm").is_err());
        assert!(validate_filename("file|pipe").is_err());
        assert!(validate_filename("data&&cmd").is_err());
        assert!(validate_filename("test>out").is_err());
    }

    #[test]
    fn test_validate_filename_path_separators() {
        // File names should not contain path separators
        assert!(validate_filename("dir/file.txt").is_err());
        assert!(validate_filename("../escape").is_err());
    }

    #[test]
    fn test_validate_filename_spaces() {
        // Spaces not allowed in our strict file name validation
        assert!(validate_filename("file name.txt").is_err());
    }
}