Release v0.5.5: Fix .. traversal bypass and expand test coverage (#54)

* CI: removed redundant cargo audit in JSON format

* docs: add exotic filesystem support details to README and lib.rs

* docs: update README and lib.rs with feature comparison and test count improvements

* test: add tests for graceful fallback on exotic filesystem failures

* test: add comprehensive security coverage and cross-platform tests

Add three new security test files to close identified gaps in vulnerability coverage:

1. tests/ads_cross_platform_security.rs (256 lines, 11 tests)
   - Populate previously empty file with cross-platform ADS security tests
   - Windows: ADS traversal rejection, device name in ADS, non-final colon, unicode manipulation
   - Unix: colon-as-literal-filename semantics, symlink handling with colons
   - Covers Windows-specific alternate data stream attack vectors

2. tests/security_coverage_gaps.rs (1008 lines, 22+ tests)
   - New file covering previously untested vulnerability classes:
   * Unpaired UTF-16 surrogates (Windows): 7 tests on invalid Unicode handling
   * Permission-change TOCTOU race conditions (Unix): 2 tests on symlink races
   * Special file types (Unix): 10 tests covering FIFO, sockets, block/char devices
   * Invalid UTF-8 paths (Unix): 5 tests on encoding edge cases
   * Junction discrimination (Windows): 4 tests on junction vs directory behavior
   * Anchored canonicalize edge cases: 6 tests on pseudo-root behavior
   * Component length attacks: 4 tests on path limits
   - All clippy warnings resolved (single_match conversions, needless_borrow fixes)
   - All format checks pass (blank line correction)

3. tests/macos_security.rs (1059 lines, ~50 tests)
   - New file with macOS-specific security tests (all gated with cfg gate)
   - NFD/NFC normalization attacks
   - Case-insensitive filesystem traversal
   - Symlink and mount point attacks
   - Resource fork and extended attribute handling
   - Ready for execution on macOS CI runner

Test Results:
- All 176+ unit tests passing on Windows
- All 22 new security_coverage_gaps tests passing
- All 5 Windows ADS tests in ads_cross_platform_security passing
- All clippy checks pass with -D warnings
- All format checks pass
- MSRV 1.70 compatible with no new dependencies

Addresses security audit request: comprehensive vulnerability testing across
Windows, Unix/Linux, and macOS platforms with zero-regression parity checks.

* refactor: simplify match statements in macOS security tests

* fix: skip normalized-path fast-path when `..` is present (#53)

Lexical normalization in Stage 3 collapsed `symlink/..` without
following the symlink, causing `soft_canonicalize` to resolve to a
wrong existing path. Skip the normalized fast-path when the absolute
path contains `..` components so the slow path can resolve symlinks
before applying parent-dir traversal.

Add regression tests for the non-existing and existing suffix cases.

Closes #53

* refactor: split large test files by platform/concern and extract anchored module

Split monolithic test files into focused, single-concern modules:
- src/lib.rs: extract `anchored_canonicalize` into src/anchored.rs
- src/tests: split CVE, exotic, and platform tests by OS target
- tests/: split blackbox, feature-combination, std-compat, security,
  macos, and Windows 8.3 tests into dedicated files

Also includes minor code quality improvements:
- Simplify `is_proc_magic_link` with slice pattern matching
- Remove dead `DeviceNS` payload in normalize.rs
- Avoid intermediate String allocation for drive letters
- Use safer indexing in windows.rs ADS validation
- Consolidate redundant cfg-gated symlink clamping branches
- Rewrite AGENTS.md for clarity and remove corrupted duplicate sections

* fix: gate Windows-only test imports behind #[cfg(windows)]

Imports used exclusively in #[cfg(windows)] test functions were
declared at the top level, causing unused-import errors on Linux CI
with `clippy -D warnings`.

Move the imports into the cfg-gated modules or add #[cfg(windows)]
to the use statements.

Files fixed:
- tests/security_utf16_surrogates.rs
- tests/security_junction_discrimination.rs
- src/tests/exotic_windows.rs
- src/tests/platform_windows.rs

* refactor: remove unused imports from macOS-specific test files

* fix(tests): platform-conditional assertions for issue #53 regression test

Windows resolves `symlink\..` lexically (before following the symlink),
while Unix follows the symlink first then resolves `..`. This means
`link\..\a` on Windows reaches the existing decoy `{tmp}\a` and
std::fs::canonicalize succeeds — matching that is required by the
golden rule.

Split the non-existing-suffix test assertion into #[cfg(unix)] and
#[cfg(windows)] branches:
- Unix: assert symlink-following result (nested/a)
- Windows: assert parity with std::fs::canonicalize (+ dunce guard)

* chore: update version to 0.5.5 and enhance changelog with new features and tests

Author: DK26

.github/workflows/audit.yml

@@ -3,59 +3,47 @@ name: Security Audit
 on:
   # Run on pushes to main/dev branches
   push:
-    branches: [ main, dev ]
-  
+    branches: [main, dev]
+
   # Run on pull requests to main
   pull_request:
-    branches: [ main ]
-  
+    branches: [main]
+
   # Schedule to run daily at 2 AM UTC to catch new advisories
   schedule:
-    - cron: '0 2 * * *'
-  
+    - cron: "0 2 * * *"
+
   # Allow manual triggering
   workflow_dispatch:
 
 jobs:
   security_audit:
     name: Security Audit
     runs-on: ubuntu-latest
-    
+
     steps:
-    - name: Checkout code
-      uses: actions/checkout@v4
-      with:
-        # Fetch full history for accurate dependency analysis
-        fetch-depth: 0
-    
-    - name: Install Rust toolchain
-      uses: dtolnay/rust-toolchain@stable
-    
-    - name: Cache cargo registry
-      uses: actions/cache@v4
-      with:
-        path: |
-          ~/.cargo/registry/index/
-          ~/.cargo/registry/cache/
-          ~/.cargo/git/db/
-        key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
-        restore-keys: |
-          ${{ runner.os }}-cargo-
-    
-    - name: Install cargo-audit
-      run: cargo install cargo-audit --locked
-    
-    - name: Run security audit
-      run: cargo audit
-    
-    - name: Run security audit with JSON output
-      run: cargo audit --format json --output audit-results.json
-      continue-on-error: true
-    
-    - name: Upload audit results as artifact
-      uses: actions/upload-artifact@v4
-      if: always()
-      with:
-        name: security-audit-results
-        path: audit-results.json
-        retention-days: 30
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          # Fetch full history for accurate dependency analysis
+          fetch-depth: 0
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache cargo registry
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry/index/
+            ~/.cargo/registry/cache/
+            ~/.cargo/git/db/
+          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-
+
+      - name: Install cargo-audit
+        run: cargo install cargo-audit --locked
+
+      - name: Run security audit
+        run: cargo audit

AGENTS.md

@@ -5,6 +5,27 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.5] - 2026-04-04
+
+### Fixed
+
+- **Fixed `..` traversal bypass when normalized path differs from original** ([#53](https://github.com/DK26/soft-canonicalize-rs/issues/53)): The normalized-path fast-path (`fs::canonicalize` on the normalized form) was incorrectly succeeding for paths containing `..` components that pointed to existing locations after normalization. This caused `soft_canonicalize` to return a fully-canonicalized result that silently resolved `..` through symlinks instead of applying lexical `..` resolution per the crate's symlink-first semantics. The fast-path is now skipped when `..` is present in the normalized path.
+
+### Changed
+
+- **Refactored source layout**: Extracted `anchored_canonicalize` into dedicated `src/anchored.rs` module (compiled only with `--features anchored`). Split large test files by platform and concern for better maintainability and RAG retrieval.
+- **Improved documentation**: Updated README.md and lib.rs with feature comparison tables, exotic filesystem support details, and refreshed test counts.
+- **CI**: Removed redundant `cargo audit` JSON-format step from audit workflow.
+
+### Added
+
+- **Regression test for issue #53** (`tests/issue_53_symlink_dotdot_lexical_collapse.rs`): Verifies that `..` traversal respects symlink-first lexical semantics and does not silently resolve through symlinks.
+- **Comprehensive security test coverage**: New test files for cross-platform ADS security, anchored edge cases, component length limits, invalid UTF-8 handling, junction discrimination, permission TOCTOU, rename TOCTOU, special files, UTF-16 surrogates, and Windows 8.3 components.
+- **Exotic filesystem fallback tests** (`tests/exotic_filesystem_fallback.rs`): Coverage for graceful behavior on exotic filesystem failures.
+- **Cross-platform path tests**: macOS NFD normalization, private symlinks, resource forks/firmlinks, and volumes anchored edge cases.
+- **Expanded feature combination tests**: Split into core and platform-specific test files.
+- **Compatibility test suites**: Dedicated test files for `..` traversal, existing paths, and symlink compatibility with `std::fs::canonicalize`.
+
 ## [0.5.4] - 2025-01-19
 
 ### Changed

CHANGELOG.md

@@ -1,6 +1,6 @@
 [package]
 name = "soft-canonicalize"
-version = "0.5.4"
+version = "0.5.5"
 edition = "2021"
 authors = ["David Krasnitsky <dikaveman@gmail.com>"]
 description = "Path canonicalization that works with non-existing paths."
@@ -35,6 +35,7 @@ tempfile = "=3.21" # Do not update
 # We cannot use `junction` v1.4.1 crate because that would require
 # us to bump our MSRV to Rust 1.71, and we only use this crate for testing.
 # So, we stick to the workaround `junction-verbatim`
+# Do not bump to `1.3.1` or we will get deprecation warnings about `junction-verbatim` crate.
 junction-verbatim = "=1.3.0"
 
 [features]

Cargo.toml

@@ -20,6 +20,7 @@ Rust implementation inspired by Python 3.6+ `pathlib.Path.resolve(strict=False)`
 **🔒 Robust** - 500+ comprehensive tests including symlink cycle protection, malicious stream validation, and edge case handling  
 **🛡️ Safe traversal** - Proper `..` and symlink resolution with cycle detection  
 **🌍 Cross-platform** - Windows, macOS, Linux with comprehensive UNC/symlink handling  
+**💾 Exotic filesystem support** - Works on RAM disks, network drives, Docker volumes ([rust-lang/rust#45067](https://github.com/rust-lang/rust/issues/45067), [#48249](https://github.com/rust-lang/rust/issues/48249))  
 **🔧 Zero dependencies** - Optional features may add minimal dependencies
 
 ## Lexical vs. Filesystem-Based Resolution
@@ -216,15 +217,16 @@ proc-canonicalize = "0.0"
 
 ### Feature Comparison
 
-| Feature                          | `soft_canonicalize`           | `proc_canonicalize` | `std::fs::canonicalize` | `std::path::absolute` | `dunce::canonicalize` |
-| -------------------------------- | ----------------------------- | ------------------- | ----------------------- | --------------------- | --------------------- |
-| Resolution type                  | Filesystem-based              | Filesystem-based    | Filesystem-based        | Lexical               | Filesystem-based      |
-| Works with non-existing paths    | ✅                             | ❌                   | ❌                       | ✅                     | ❌                     |
-| Resolves symlinks                | ✅                             | ✅                   | ✅                       | ❌                     | ✅                     |
-| Preserves Linux namespaces       | ✅ (default)                   | ✅                   | ❌                       | N/A                   | ❌                     |
-| Simplified Windows paths         | ✅ (opt-in `dunce` feature)    | ✅ (opt-in)          | ❌ (UNC)                 | ❌ (varies)            | ✅                     |
-| Virtual/bounded canonicalization | ✅ (opt-in `anchored` feature) | ❌                   | ❌                       | ❌                     | ❌                     |
-| Zero dependencies                | ✅ (default)                   | ✅                   | ✅                       | ✅                     | ✅                     |
+| Feature                          | `soft_canonicalize`           | `normpath` | `proc_canonicalize` | `std::fs::canonicalize` | `std::path::absolute` | `dunce::canonicalize` |
+| -------------------------------- | ----------------------------- | ---------- | ------------------- | ----------------------- | --------------------- | --------------------- |
+| Resolution type                  | Filesystem-based              | Lexical    | Filesystem-based    | Filesystem-based        | Lexical               | Filesystem-based      |
+| Works with non-existing paths    | ✅                             | ✅          | ❌                   | ❌                       | ✅                     | ❌                     |
+| Resolves symlinks                | ✅                             | ❌          | ✅                   | ✅                       | ❌                     | ✅                     |
+| RAM disk / network drive support | ✅ (graceful fallback)         | ✅ (no I/O) | ❌                   | ❌                       | ✅                     | ❌                     |
+| Preserves Linux namespaces       | ✅ (default)                   | N/A        | ✅                   | ❌                       | N/A                   | ❌                     |
+| Simplified Windows paths         | ✅ (opt-in `dunce` feature)    | ✅ (opt-in) | ✅ (opt-in)          | ❌ (UNC)                 | ❌ (varies)            | ✅                     |
+| Virtual/bounded canonicalization | ✅ (opt-in `anchored` feature) | ❌          | ❌                   | ❌                       | ❌                     | ❌                     |
+| Zero dependencies                | ✅ (default)                   | ✅          | ✅                   | ✅                       | ✅                     | ✅                     |
 
 ### When to Use Each
 
@@ -235,11 +237,11 @@ proc-canonicalize = "0.0"
 - ✅ You need simplified Windows paths for legacy apps (with `dunce` feature)
 
 **Choose alternatives when:**
+- **`normpath::normalize`** - Maximum performance needed, you can guarantee no symlinks exist, and you want pure lexical normalization (no I/O). Note: lacks symlink resolution, so not suitable when security against symlink-based attacks is required
 - **`proc_canonicalize::canonicalize`** - All paths exist and you need correct Linux namespace handling (recommended over `std::fs::canonicalize`)
 - **`std::fs::canonicalize`** - All paths exist; only when you specifically need the legacy behavior that resolves `/proc/PID/root` to `/`
 - **`std::path::absolute`** - You only need absolute paths without symlink resolution (lexical, fast)
 - **`dunce::canonicalize`** - Windows-only, all paths exist, just need UNC simplification
-- **`normpath::normalize`** - Lexical normalization only, no filesystem I/O (fast but doesn't resolve symlinks)
 - **`path_absolutize`** - Absolute path resolution without symlink following, with CWD caching optimizations
 
 ## Related Projects