Path Utils

Security-focused utilities for working with file paths across platforms, with built-in protection against path traversal attacks and malicious inputs.

Installation

npm install @ucdjs/path-utils

Security model

All user-supplied paths are treated as untrusted. resolveSafePath applies the following pipeline before returning a resolved path:

User input
    │
    ▼
[decodePathSafely]  ← iterative URL decode, max 10 rounds
    │                  throws: FailedToDecodePathError
    │                          MaximumDecodingIterationsExceededError
    ▼
[illegal-char check]  ← null bytes, Unicode control characters
    │                   throws: IllegalCharacterInPathError
    ▼
[normalize + resolve] ← patheNormalize, virtual-root boundary model
    │                   absolute paths outside base → treated as relative
    ▼
[isWithinBase]  ← containment check (case-sensitive on Linux,
    │              case-insensitive on Windows/macOS)
    │              throws: PathTraversalError
    ▼
Safe resolved path (platform-native string)

API Reference

Known limitations

• Case sensitivity: Containment checks use OS-level detection (isCaseSensitive = true on Linux, false on Windows/macOS). This does not account for per-filesystem configuration (e.g. a case-insensitive ext4 mount on Linux, or a case-sensitive APFS volume on macOS). This is a known, accepted limitation.
• Spaced traversal sequences: .. /etc/passwd (a space between .. and /) is not detected as a traversal attempt, as it does not normalize to a directory traversal sequence.