path-sanitizer 4.0.3 → 5.0.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## [5.0.0] - 2026-10-31
+
+### Fixed
+
+- [GHSA-v6jx-8m6q-xm2r](https://github.com/cabraviva/path-sanitizer/security/advisories/GHSA-v6jx-8m6q-xm2r)
+
+### Breaking Changes
+
+- Removed `SanitizeOptions.parentDirectoryRegEx`, as it's now always enforced internally

package/README.md

@@ -2,7 +2,7 @@
 
 A simple lightweight npm package for sanitizing paths to prevent Path Traversal
 
-# Usage
+## Usage
 
 ```js
 import sanitize from 'path-sanitizer'
@@ -21,11 +21,11 @@ import path from 'path'
 // Real scenario:
 function routeHandler(myPath) {
   // Lets just assume that the path was extracted from the request
-  // We want to read a file in the C:\Users\user\Desktop\myApp\ directory
-  // But the user should not be able to access C:\Users\user\Desktop\
+  // We want to read a file in the /home/user/server/static/ directory
+  // But the user should not be able to access /home/user/server/
   // So we need to sanitize the path
 
-  const APP_DIR = 'C:\\Users\\user\\Desktop\\myApp\\'
+  const APP_DIR = '/home/user/server/static/'
   const sanitized = path.join(APP_DIR, sanitize(myPath))
 
   // Now we would usually read the file
@@ -34,9 +34,17 @@ function routeHandler(myPath) {
 }
 
 routeHandler('my-video.mp4') // Just fine...
-routeHandler('../../Documents/grades.docx') // But what if we try to access a file outside the app directory?
-routeHandler('/hello.txt') // What if the path starts with a slash, and we try to use an absolute path?
+routeHandler('../../Documents/personal-file.pdf') // But what if we try to access a file outside the app directory?
+routeHandler('/home/user/hello.txt') // What if the path starts with a slash, and we try to use an absolute path?
 routeHandler('////////a\\\\../hi.txt') // What if the path is not valid?
 routeHandler(500) // What if the path is not a string?
 routeHandler('/:11^^') // What if the path contains not allowed characters (like ":")?
 ```
+
+## Note
+
+This package is optimized for linux environments. You can try to use it on Windows, and it will mostly work fine, but it is recommended to use on a linux system or inside a docker container.
+
+## Contributing
+
+If you have any issues with `path-sanitizer` or you have discovered a vulnerability / bypass, please make sure to report it. I appreciate every contribution.

package/dist/index.d.ts

@@ -3,10 +3,6 @@ export interface SanitizeOptions {
         regex: RegExp;
         replacement: string;
     }[];
-    /**
-     * RegEx that filters out stuff like \..\ or /../
-     */
-    parentDirectoryRegEx?: RegExp;
     /**
      * Characters to be removed from paths because the file system doesn't support these.
      */
@@ -17,10 +13,6 @@ interface SanitizeOptionsComplete {
         regex: RegExp;
         replacement: string;
     }[];
-    /**
-     * RegEx that filters out stuff like \..\ or /../
-     */
-    parentDirectoryRegEx: RegExp;
     /**
      * Characters to be removed from paths because the file system doesn't support these.
      */
@@ -30,5 +22,5 @@ export declare const DEFAULT_OPTIONS: SanitizeOptionsComplete;
 /**
  * Sanitizes a portion of a path to avoid Path Traversal
  */
-export default function sanitize(pathstr: string, options?: SanitizeOptions): string;
+export default function sanitize(pathString: string, options?: SanitizeOptions): string;
 export {};

package/dist/index.js

@@ -1,93 +1,113 @@
-import { normalize, join } from 'node:path';
 export const DEFAULT_OPTIONS = {
     decode: [
         {
-            regex: /%2e/g,
+            regex: /%2[eE]/g,
             replacement: '.',
         },
         {
-            regex: /%2f/g,
+            regex: /%2[fF]/g,
             replacement: '/',
         },
         {
-            regex: /%5c/g,
+            regex: /%5[cC]/g,
             replacement: '\\',
         },
     ],
-    parentDirectoryRegEx: /[\/\\]\.\.[\/\\]/g,
-    notAllowedRegEx: /:|\$|!|'|"|@|\+|`|\||=/g,
+    notAllowedRegEx: /:|\$|!|'|"|@|\+|`|\||=|\u0000/g,
 };
 /**
- * Sanitizes a portion of a path to avoid Path Traversal
+ * Internal utility function that validates the SanitizeOptions and fills them with DEFAULT_OPTIONS unless already complete.
+ * @param options (incomplete) SanitizeOptions
+ * @returns Fully valid SanitizeOptionsComplete
  */
-export default function sanitize(pathstr, options = DEFAULT_OPTIONS) {
+function validateOptions(options) {
     if (!options)
-        options = DEFAULT_OPTIONS;
-    if (typeof options !== 'object')
+        return DEFAULT_OPTIONS;
+    if (typeof options !== 'object') {
         throw new Error('options must be an object');
-    if (!Array.isArray(options.decode))
-        options.decode = DEFAULT_OPTIONS.decode;
-    if (!options.parentDirectoryRegEx)
-        options.parentDirectoryRegEx = DEFAULT_OPTIONS.parentDirectoryRegEx;
-    if (!options.notAllowedRegEx)
-        options.notAllowedRegEx = DEFAULT_OPTIONS.notAllowedRegEx;
-    if (typeof pathstr !== 'string') {
-        // Stringify the path
-        pathstr = `${pathstr}`;
     }
-    let sanitizedPath = pathstr;
-    // ################################################################################################################
-    // Decode
-    options.decode.forEach((decode) => {
-        sanitizedPath = sanitizedPath.replace(decode.regex, decode.replacement);
-    });
-    // Remove not allowed characters
-    sanitizedPath = sanitizedPath.replace(options.notAllowedRegEx, '');
-    // Replace backslashes with normal slashes
-    sanitizedPath = sanitizedPath.replace(/[\\]/g, '/');
-    // Replace /../ with /
-    sanitizedPath = sanitizedPath.replace(options.parentDirectoryRegEx, '/');
-    // Remove ../ at pos 0 and /.. at end
-    sanitizedPath = sanitizedPath.replace(/^\.\.[\/\\]/g, '/');
-    sanitizedPath = sanitizedPath.replace(/[\/\\]\.\.$/g, '/');
-    // Replace double (back)slashes with a single slash
-    sanitizedPath = sanitizedPath.replace(/[\/\\]+/g, '/');
-    // Normalize path
-    sanitizedPath = normalize(sanitizedPath);
-    // Remove / or \ in the end
-    while (sanitizedPath.endsWith('/') || sanitizedPath.endsWith('\\')) {
-        sanitizedPath = sanitizedPath.slice(0, -1);
+    return {
+        decode: Array.isArray(options.decode)
+            ? options.decode
+            : DEFAULT_OPTIONS.decode,
+        notAllowedRegEx: options.notAllowedRegEx ?? DEFAULT_OPTIONS.notAllowedRegEx,
+    };
+}
+/**
+ * Internal utility function to normalize slashes in a path (e.g. from '\' to '/')
+ * @param val path string
+ * @returns slash-normalized path
+ */
+function normalizeSlashes(val) {
+    // Replace backslashes to forward slashes
+    val = val.replaceAll('\\', '/');
+    // Replace all multi combined slashes into one
+    val = val.replace(/\/+/g, '/');
+    return val;
+}
+/**
+ * Internal utility function to apply all decode regexes from SanitizeOptions.decode to a path string
+ * @param pathstr a path string
+ * @param decodeOptions valid SanitizeOptionsComplete.decode
+ * @returns a decoded path string
+ */
+function decodePath(pathstr, decodeOptions) {
+    for (const decodeOption of decodeOptions) {
+        pathstr = pathstr.replace(decodeOption.regex, decodeOption.replacement);
     }
-    // Remove / or \ in the beginning
-    while (sanitizedPath.startsWith('/') || sanitizedPath.startsWith('\\')) {
-        sanitizedPath = sanitizedPath.slice(1);
+    return pathstr;
+}
+/**
+ * Internal utility function to ensure the specified notAllowedRegEx
+ */
+function removeInvalidCharacters(pathstr, notAllowedRegEx) {
+    return pathstr.replace(notAllowedRegEx, '');
+}
+/**
+ * Internal function which takes a path string and ensures every segment is valid
+ */
+function applyPathFilters(pathString) {
+    const filteredPath = pathString
+        .trim() // trim the whole path-string
+        .split('/') // split into path-segments
+        .filter((segment) => {
+        const trimmedSegment = segment.trim(); // trim every segment
+        return (trimmedSegment !== '' &&
+            trimmedSegment !== '.' &&
+            trimmedSegment !== '..'); // return whether the segment is a valid path-portion (no '', '.' or '..')
+        // if valid => keep; invalid => remove
+    })
+        .join('/') // reconstruct path string
+        .trim(); // trim again
+    return /^\.+$/.test(filteredPath) ? '' : filteredPath; // ensures the path string is not just dots
+}
+/**
+ * Failsafe helper function to catch all remaining absolute paths (not wanted by sanitize())
+ * works by ensuring no '/' at start or end and no '..' in a segment in-between
+ */
+function isSafeLinuxRelativePath(pathString) {
+    return (!pathString.startsWith('/') &&
+        !pathString.endsWith('/') &&
+        !pathString.split('/').some((segment) => segment === '..'));
+}
+/**
+ * Sanitizes a portion of a path to avoid Path Traversal
+ */
+export default function sanitize(pathString, options = DEFAULT_OPTIONS) {
+    // Validate options and set default options if user did not set
+    const validOptions = validateOptions(options);
+    // Validate path is a string, otherwise convert to string
+    if (typeof pathString !== 'string') {
+        pathString = `${pathString}`;
     }
-    // Validate path
-    sanitizedPath = join('', sanitizedPath);
-    // Remove not allowed characters
-    sanitizedPath = sanitizedPath.replace(options.notAllowedRegEx, '');
-    // Again change all \ to /
-    sanitizedPath = sanitizedPath.replace(/[\\]/g, '/');
-    // Replace double (back)slashes with a single slash
-    sanitizedPath = sanitizedPath.replace(/[\/\\]+/g, '/');
-    // Replace /../ with /
-    sanitizedPath = sanitizedPath.replace(options.parentDirectoryRegEx, '/');
-    // Remove ./ or / at start
-    while (sanitizedPath.startsWith('/') ||
-        sanitizedPath.startsWith('./') ||
-        sanitizedPath.endsWith('/..') ||
-        sanitizedPath.endsWith('/../') ||
-        sanitizedPath.startsWith('../') ||
-        sanitizedPath.startsWith('/../')) {
-        sanitizedPath = sanitizedPath.replace(/^\.\//g, ''); // ^./
-        sanitizedPath = sanitizedPath.replace(/^\//g, ''); // ^/
-        // Remove ../ | /../ at pos 0 and /.. | /../ at end
-        sanitizedPath = sanitizedPath.replace(/^[\/\\]\.\.[\/\\]/g, '/');
-        sanitizedPath = sanitizedPath.replace(/^\.\.[\/\\]/g, '/');
-        sanitizedPath = sanitizedPath.replace(/[\/\\]\.\.$/g, '/');
-        sanitizedPath = sanitizedPath.replace(/[\/\\]\.\.\/$/g, '/');
+    if (pathString.length > 4096) {
+        throw new Error(`filename is over - 4096 characters`);
     }
-    // Make sure out is not "." or ".." or any amount of "only dots"
-    sanitizedPath = sanitizedPath.trim().replace(/^(\.*)$/g, '');
-    return sanitizedPath.trim();
+    // Apply every configurable transformation before traversal filtering.
+    pathString = decodePath(pathString, validOptions.decode);
+    pathString = removeInvalidCharacters(pathString, validOptions.notAllowedRegEx);
+    pathString = normalizeSlashes(pathString);
+    pathString = applyPathFilters(pathString);
+    // No path transformation may happen after this final safety check.
+    return isSafeLinuxRelativePath(pathString) ? pathString : '';
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "path-sanitizer",
-  "version": "4.0.3",
+  "version": "5.0.0",
   "description": "A simple lightweight npm package for sanitizing paths to prevent Path Traversal",
   "type": "module",
   "main": "dist/index.js",
@@ -27,8 +27,8 @@
   },
   "homepage": "https://github.com/cabraviva/path-sanitizer#readme",
   "devDependencies": {
-    "@types/node": "^25.3.2",
+    "@types/node": "^25.9.9",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.18"
+    "vitest": "^4.1.12"
   }
 }