Crate soft_canonicalize 

soft-canonicalize

Path canonicalization that works with non-existing paths.

Rust implementation inspired by Python 3.6+ pathlib.Path.resolve(strict=False), providing the same functionality as std::fs::canonicalize (Rust’s equivalent to Unix realpath()) but extended to handle non-existing paths, with optional features for simplified Windows output (dunce) and virtual filesystem semantics (anchored).

Why Use This?

• 🚀 Works with non-existing paths - Plan file locations before creating them
• ⚡ Fast - Optimized performance with minimal allocations and syscalls
• ✅ Compatible - 100% behavioral match with std::fs::canonicalize for existing paths, with optional UNC simplification via dunce feature (Windows)
• 🎯 Virtual filesystem support - Optional anchored feature for bounded canonicalization within directory boundaries
• 🔒 Robust - 495 comprehensive tests covering edge cases and security scenarios
• 🛡️ Safe traversal - Proper .. and symlink resolution with cycle detection
• 🌍 Cross-platform - Windows, macOS, Linux with comprehensive UNC/symlink handling
• 🔧 Zero dependencies - Optional features may add minimal dependencies

Lexical vs. Filesystem-Based Resolution

Path resolution libraries fall into two categories:

Lexical Resolution (no I/O):

• Performance: Fast - no filesystem access
• Accuracy: Incorrect if symlinks are present (doesn’t resolve them)
• Use when: You’re 100% certain no symlinks exist and need maximum performance
• Examples: std::path::absolute, normpath::normalize

Filesystem-Based Resolution (performs I/O):

• Performance: Slower - requires filesystem syscalls to resolve symlinks
• Accuracy: Correct - follows symlinks to their targets
• Use when: Safety is priority over performance, or symlinks may be present
• Examples: std::fs::canonicalize, soft_canonicalize, dunce::canonicalize

Rule of thumb: If you cannot guarantee symlinks won’t be introduced, or if correctness is critical, use filesystem-based resolution.

Use Cases

Path Comparison

• Equality: Determine if two different path strings point to the same location
• Containment: Check if one path is inside another directory

Common Applications

• Build Systems: Resolve output paths during build planning before directories exist
• Configuration Validation: Ensure user-provided paths stay within allowed boundaries
• Deduplication: Detect when different path strings refer to the same planned location
• Cross-Platform Normalization: Handle Windows UNC paths and symlinks consistently

Quick Start

[dependencies]
soft-canonicalize = "0.5"

Basic Example

use soft_canonicalize::soft_canonicalize;

let non_existing_path = r"C:\Users\user\documents\..\non\existing\config.json";

// Using Rust's own std canonicalize function:
let result = std::fs::canonicalize(non_existing_path);
assert!(result.is_err());

// Using our crate's function:
let result = soft_canonicalize(non_existing_path);
assert!(result.is_ok());

// Shows the UNC path conversion and path normalization
assert_eq!(
    result.unwrap().to_string_lossy(),
    r"\\?\C:\Users\user\non\existing\config.json"
);

// With `dunce` feature enabled, paths are simplified when safe
assert_eq!(
    result.unwrap().to_string_lossy(),
    r"C:\Users\user\non\existing\config.json"
);

Optional Features

Anchored Canonicalization (anchored feature)

For correct symlink resolution within virtual/constrained directory spaces, use anchored_canonicalize. This function implements true virtual filesystem semantics by clamping ALL paths (including absolute symlink targets) to the anchor directory:

[dependencies]
soft-canonicalize = { version = "0.5", features = ["anchored"] }

use soft_canonicalize::anchored_canonicalize;
use std::fs;

// Set up an anchor/root directory (no need to pre-canonicalize)
let anchor = std::env::temp_dir().join("workspace_root");
fs::create_dir_all(&anchor)?;

// Canonicalize paths relative to the anchor (anchor is soft-canonicalized internally)
let resolved_path = anchored_canonicalize(&anchor, "../../../etc/passwd")?;
// Result: /tmp/workspace_root/etc/passwd (lexical .. clamped to anchor)

// Absolute symlinks are also clamped to the anchor
// If there's a symlink: workspace_root/config -> /etc/config
// It resolves to: workspace_root/etc/config (clamped to anchor)
let symlink_path = anchored_canonicalize(&anchor, "config")?;
// Safe: always stays within workspace_root, even if symlink points to /etc/config

Key features:

• Virtual filesystem semantics: All absolute paths (including symlink targets) are clamped to anchor
• Anchor-relative canonicalization: Resolves paths relative to a specific anchor directory
• Complete symlink clamping: Follows symlink chains with clamping at each step
• Component-by-component: Processes path components in proper order
• Absolute results: Always returns absolute canonical paths within the anchor boundary

For a complete multi-tenant security example, run:

cargo run --example virtual_filesystem_demo --features anchored

Simplified Path Output (dunce feature, Windows-only)

By default, soft_canonicalize returns Windows paths in extended-length UNC format (\\?\C:\foo) for maximum robustness and compatibility with long paths, reserved names, and other Windows filesystem edge cases.

If you need simplified paths (C:\foo) for compatibility with legacy applications or user-facing output, enable the dunce feature:

[dependencies]
soft-canonicalize = { version = "0.5", features = ["dunce"] }

Example:

use soft_canonicalize::soft_canonicalize;
let path = soft_canonicalize(r"C:\Users\user\documents\..\config.json")?;

// Without dunce feature (default):
// Returns: \\?\C:\Users\user\config.json (extended-length UNC)

// With dunce feature enabled:
// Returns: C:\Users\user\config.json (simplified when safe)

When to use:

• ✅ Legacy applications that don’t support UNC paths
• ✅ User-facing output requiring familiar path format
• ✅ Tools expecting traditional Windows path format

How it works:

The dunce crate intelligently simplifies Windows UNC paths (\\?\C:\foo → C:\foo) only when safe:

• Automatically keeps UNC for paths >260 chars
• Automatically keeps UNC for reserved names (CON, PRN, NUL, COM1-9, LPT1-9)
• Automatically keeps UNC for paths with trailing spaces/dots
• Automatically keeps UNC for paths containing .. (literal interpretation)

When Paths Must Exist: proc-canonicalize

Since v0.5.0, soft_canonicalize uses proc-canonicalize by default for existing-path canonicalization instead of std::fs::canonicalize. This fixes a critical issue with Linux namespace boundaries.

The Problem: On Linux, std::fs::canonicalize resolves “magic symlinks” like /proc/PID/root to their targets, losing the namespace boundary:

// /proc/self/root is a "magic symlink" pointing to the current process's root filesystem
// std::fs::canonicalize incorrectly resolves it to "/"
let std_result = std::fs::canonicalize("/proc/self/root")?;
assert_eq!(std_result.to_string_lossy(), "/"); // Wrong! Namespace boundary lost

// proc_canonicalize preserves the namespace boundary
let proc_result = proc_canonicalize::canonicalize("/proc/self/root")?;
assert_eq!(proc_result.to_string_lossy(), "/proc/self/root"); // Correct!

Recommendation: If you need to canonicalize paths that must exist (and would previously use std::fs::canonicalize), use proc_canonicalize::canonicalize for correct Linux namespace handling:

[dependencies]
proc-canonicalize = "0.0"

Security & CVE Coverage

Security does not depend on enabling features. The core API is secure-by-default; the optional anchored feature is a convenience for virtual roots. We test all modes (no features; --features anchored; --features anchored,dunce).

Built-in protections include:

• NTFS Alternate Data Stream (ADS) validation - Blocks malicious stream placements and traversal attempts
• Symlink cycle detection - Bounded depth tracking prevents infinite loops
• Path traversal clamping - Never ascends past root/share/device boundaries
• Null byte rejection - Early validation prevents injection attacks
• UNC/device semantics - Preserves Windows extended-length and device namespace integrity
• TOCTOU race resistance - Tested against time-of-check-time-of-use attacks

See docs/SECURITY.md for detailed analysis, attack scenarios, and test references.

Cross-Platform Notes

• Windows: returns extended-length verbatim paths for absolute results (\\?\C:\…, \\?\UNC\…)
  • With dunce feature: returns simplified paths (C:\…) when safe
• Unix-like systems: standard absolute and relative path semantics
• UNC floors and device namespaces are preserved and respected

Testing

495 tests including:

• std::fs::canonicalize compatibility tests (existing paths)
• Path traversal and robustness tests
• Python pathlib-inspired behavior checks
• Platform-specific cases (Windows/macOS/Linux)
• Symlink semantics and cycle detection
• Windows-specific UNC, 8.3, and ADS validation
• Anchored canonicalization tests (with anchored feature)

Known Limitation (Windows 8.3)

On Windows, for non-existing paths we cannot determine equivalence between a short (8.3) name and its long form. Existing paths are canonicalized to the same result.

use soft_canonicalize::soft_canonicalize;
let short_form = soft_canonicalize("C:/PROGRA~1/MyApp/config.json")?;
let long_form  = soft_canonicalize("C:/Program Files/MyApp/config.json")?;
assert_ne!(short_form, long_form); // for non-existing suffixes

How It Works

For those interested in the implementation details, here’s how soft_canonicalize processes paths:

1. Input validation (empty path, platform pre-checks)
2. Convert to absolute path (preserving drive/root semantics)
3. Fast-path: try fs::canonicalize on the original absolute path
4. Lexically normalize . and .. (fast-path optimization for whole-path existence check)
5. Fast-path: try fs::canonicalize on the normalized path when different
6. Validate null bytes (platform-specific)
7. Discover deepest existing prefix with symlink-first semantics: resolve symlinks incrementally, then process . and .. relative to resolved targets
8. Optionally canonicalize the anchor (if symlinks seen) and rebuild
9. Append non-existing suffix lexically, then normalize if needed
10. Windows: ensure extended-length prefix for absolute paths
11. Optional: simplify Windows paths when dunce feature enabled

Structs

SoftCanonicalizeError

Error payload used by this crate to attach the offending path to I/O errors.

Constants

MAX_SYMLINK_DEPTH

Maximum number of symlinks to follow before giving up. This matches the behavior of std::fs::canonicalize and OS limits:

Traits

IoErrorPathExt

Extension to extract our path-aware payload from io::Error.

Functions

soft_canonicalize

Performs “soft” canonicalization on a path.