path_security/lib.rs
1//! # Path Security
2//!
3//! A comprehensive path validation and sanitization library to prevent path traversal attacks.
4//!
5//! ## Features
6//!
7//! - **Path Traversal Prevention**: Validates paths to ensure they don't escape base directories
8//! - **Encoding Attack Protection**: Detects URL, UTF-8, Unicode, and other encoding tricks
9//! - **Project Name Validation**: Ensures project names are safe for filesystem use
10//! - **Filename Sanitization**: Validates filenames for suspicious patterns
11//! - **Cross-Platform**: Handles both Unix and Windows path conventions including NTFS streams, UNC paths
12//! - **Zero Dependencies**: Only depends on `anyhow` for error handling
13//!
14//! ## Usage
15//!
16//! ```rust
17//! use path_security::{validate_path, validate_project_name, validate_filename};
18//! use std::path::Path;
19//!
20//! # fn main() -> anyhow::Result<()> {
21//! # use tempfile::TempDir;
22//! # let temp_dir = TempDir::new()?;
23//! # let base_dir = temp_dir.path();
24//! // Validate a path against a base directory
25//! let user_path = Path::new("user/document.pdf");
26//! // Note: In production, base_dir would be your actual upload directory
27//! # std::fs::create_dir(base_dir.join("user"))?;
28//! let safe_path = validate_path(user_path, base_dir)?;
29//!
30//! // Validate a project name
31//! let project_name = validate_project_name("my-awesome-project")?;
32//!
33//! // Validate a filename
34//! let filename = validate_filename("report.pdf")?;
35//! # Ok(())
36//! # }
37//! ```
38//!
39//! ## Security Guarantees
40//!
41//! - Blocks `..` directory traversal sequences (including encoded variants)
42//! - Rejects absolute paths
43//! - Prevents null byte injection
44//! - Blocks environment variable expansion patterns
45//! - Validates against OS reserved names (Windows)
46//! - Detects URL encoding attacks (single and double encoding)
47//! - Prevents UTF-8 overlong encoding attacks
48//! - Blocks Unicode homoglyphs and zero-width characters
49//! - Detects Windows-specific attacks (NTFS streams, UNC paths, trailing dots/spaces)
50//! - Validates path separator variations and mixed separators
51//! - Ensures paths resolve within base directory using canonicalization
52
53pub mod attacks;
54pub mod constants;
55pub mod encoding;
56pub mod validation;
57
58// Re-export main functions
59pub use validation::*;
60
61// Re-export constants for advanced usage
62pub use constants::*;