Module path

rawzip

Module path 

Source
Expand description

Path handling for ZIP archives with type-safe raw and normalized paths.

This module provides a comprehensive system for handling file paths from ZIP archives with strong safety guarantees against path traversal attacks (zip slip vulnerabilities).

§Path Types

The main type is ZipFilePath, which is generic over three possible path types with different safety levels:

§Raw Paths

Raw paths provide direct access to the original bytes from the ZIP file without any validation.

May contain the following:

  • Directory traversal: ../, ..\\, .. sequences
  • Absolute paths: /etc/passwd, C:\\Windows\\system32
  • Invalid UTF-8: Arbitrary byte sequences that aren’t valid text

§Normalized Paths

Normalized paths have been validated and sanitized according to these rules:

  • Assumed to be UTF-8 (zip file names aren’t always UTF-8)
  • Path separators: All backslashes (\) converted to forward slashes (/)
  • Redundant slashes: Multiple consecutive slashes (//) reduced to single slash
  • Relative components: Current directory (.) and parent directory (..) resolved
  • Leading separators: Absolute paths made relative (/foo → foo)
  • Drive letters: Windows drive prefixes removed (C:\\foo → foo)
  • Escape prevention: Paths cannot escape the archive root directory

§Usage Examples

use rawzip::path::ZipFilePath;

// From raw bytes
let raw_path = ZipFilePath::from_bytes(b"../../../etc/passwd");
let safe_path = raw_path.try_normalize()?; // Returns error if invalid UTF-8
assert_eq!(safe_path.as_str(), "etc/passwd");

// From string
let normalized_path = ZipFilePath::from_str("dir\\file.txt");
assert_eq!(normalized_path.as_str(), "dir/file.txt");
assert_eq!(String::from(normalized_path), "dir/file.txt");

// Backslashes to forward slashes
let path = ZipFilePath::from_str("dir\\subdir\\file.txt");
assert_eq!(path.as_str(), "dir/subdir/file.txt");

// Remove redundant slashes
let path = ZipFilePath::from_str("dir//subdir///file.txt");
assert_eq!(path.as_str(), "dir/subdir/file.txt");

// Resolve relative components
let path = ZipFilePath::from_str("dir/../file.txt");
assert_eq!(path.as_str(), "file.txt");

// Remove leading slashes (absolute → relative)
let path = ZipFilePath::from_str("/etc/passwd");
assert_eq!(path.as_str(), "etc/passwd");

// Prevent directory traversal
let path = ZipFilePath::from_str("../../../etc/passwd");
assert_eq!(path.as_str(), "etc/passwd");

// Get string from normalized path
let path = ZipFilePath::from_str("dir/file.txt");
let my_str = String::from(path.into_owned());
assert_eq!(my_str, String::from("dir/file.txt"));

§UTF-8 Encoding Detection

The library automatically detects when paths contain characters that require UTF-8 encoding in ZIP files (beyond the default CP-437 encoding). This information is used internally when creating ZIP archives.

Structs§

NormalizedPath
A normalized and sanitized path from a ZIP archive.
NormalizedPathBuf
An owned, normalized path from a ZIP archive.
RawPath
Raw path data directly from a ZIP archive.
ZipFilePath
Type-safe wrapper for ZIP archive file paths.