path-sanitizer 2.0.0 → 3.0.1

package/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - '**'
+  pull_request:
+    branches:
+      - '**'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        name: Install pnpm
+        with:
+          version: 9
+          run_install: false
+
+      - name: Install Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Run tests
+        run: pnpm test

package/README.md

@@ -1,9 +1,11 @@
 # path-sanitizer
- A simple leightweight node.js package for sanitizing paths to prevent Path Traversal
+ A simple lightweight npm package for sanitizing paths to prevent Path Traversal
 
 # Usage
 ```js
-const sanitize = require('path-sanitizer')
+import sanitize from 'path-sanitizer'
+// or
+const sanitize = require('path-sanitizer').default
 
 console.log(sanitize('path/to/file.txt'))
 ```
@@ -17,21 +19,21 @@ const path = require('path')
 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 be able to access C:\Users\user\Desktop\
+    // But the user should not be able to access C:\Users\user\Desktop\
     // So we need to sanitize the path
 
     const APP_DIR = 'C:\\Users\\user\\Desktop\\myApp\\'
     const sanitized = path.join(APP_DIR, sanitize(myPath))
 
-    // Now we would usally read the file
-    // But in this case we just gonna print the path
+    // Now we would usually read the file
+    // But in this case we will just print the path
     console.log(sanitized)
 }
 
-routeHandler('myvideo.mp4') // Just fine...
+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('////////a\\\\../hhuio.txt') // What if the path is not valid?
+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 ":")?
 ```

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+export interface SanitizeOptions {
+    decode?: ({
+        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.
+     */
+    notAllowedRegEx?: RegExp;
+}
+interface SanitizeOptionsComplete {
+    decode: ({
+        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.
+     */
+    notAllowedRegEx: RegExp;
+}
+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 {};

package/dist/index.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_OPTIONS = void 0;
+exports.default = sanitize;
+const node_path_1 = require("node:path");
+exports.DEFAULT_OPTIONS = {
+    decode: [
+        {
+            regex: /%2e/g,
+            replacement: '.'
+        },
+        {
+            regex: /%2f/g,
+            replacement: '/'
+        },
+        {
+            regex: /%5c/g,
+            replacement: '\\'
+        }
+    ],
+    parentDirectoryRegEx: /[\/\\]\.\.[\/\\]/g,
+    notAllowedRegEx: /:|\$|!|'|"|@|\+|`|\||=/g
+};
+/**
+ * Sanitizes a portion of a path to avoid Path Traversal
+ */
+function sanitize(pathstr, options = exports.DEFAULT_OPTIONS) {
+    if (!options)
+        options = exports.DEFAULT_OPTIONS;
+    if (typeof options !== 'object')
+        throw new Error('options must be an object');
+    if (!Array.isArray(options.decode))
+        options.decode = exports.DEFAULT_OPTIONS.decode;
+    if (!options.parentDirectoryRegEx)
+        options.parentDirectoryRegEx = exports.DEFAULT_OPTIONS.parentDirectoryRegEx;
+    if (!options.notAllowedRegEx)
+        options.notAllowedRegEx = exports.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 = (0, node_path_1.normalize)(sanitizedPath);
+    // Remove / or \ in the end
+    while (sanitizedPath.endsWith('/') || sanitizedPath.endsWith('\\')) {
+        sanitizedPath = sanitizedPath.slice(0, -1);
+    }
+    // Remove / or \ in the beginning
+    while (sanitizedPath.startsWith('/') || sanitizedPath.startsWith('\\')) {
+        sanitizedPath = sanitizedPath.slice(1);
+    }
+    // Validate path
+    sanitizedPath = (0, node_path_1.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, '/');
+    // Make sure out is not "."
+    sanitizedPath = sanitizedPath.trim() === '.' ? '' : sanitizedPath;
+    return sanitizedPath.trim();
+}

package/package.json

@@ -1,25 +1,27 @@
-{
-  "name": "path-sanitizer",
-  "version": "2.0.0",
-  "description": "A simple node.js package for sanitizing paths to prevent Path Traversal",
-  "main": "sanitize.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/greencoder001/path-sanitizer.git"
-  },
-  "keywords": [
-    "path",
-    "sanitize",
-    "sanitizer",
-    "path-sanitizer"
-  ],
-  "author": "greencoder001",
-  "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/greencoder001/path-sanitizer/issues"
-  },
-  "homepage": "https://github.com/greencoder001/path-sanitizer#readme"
-}
+{
+    "name": "path-sanitizer",
+    "version": "3.0.1",
+    "description": "A simple lightweight npm package for sanitizing paths to prevent Path Traversal",
+    "main": "dist/index.js",
+    "scripts": {
+        "test": "vitest",
+        "build": "tsc"
+    },
+    "keywords": [],
+    "author": "Cabra (https://github.com/cabraviva)",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/cabraviva/path-sanitizer.git"
+    },
+    "bugs": {
+        "url": "https://github.com/cabraviva/path-sanitizer/issues"
+    },
+    "homepage": "https://github.com/cabraviva/path-sanitizer#readme",
+    "types": "dist/index.d.ts",
+    "devDependencies": {
+        "@types/node": "^22.9.3",
+        "typescript": "^5.7.2",
+        "vitest": "^2.1.5"
+    }
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+    "compilerOptions": {
+        "target": "ESNEXT",
+        "module": "commonjs",
+        "declaration": true,
+        "outDir": "./dist",
+        "strict": true
+    },
+    "include": [
+        "lib/*.ts"
+    ],
+    "exclude": [
+        "lib/*.test.ts"
+    ]
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2022 Green_Lab
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/sanitize.js

@@ -1,72 +0,0 @@
-const path = require('path')
-
-const DEFAULT_OPTIONS = {
-    decode: [
-        {
-            regex: /%2e/g,
-            replacement: '.'
-        },
-        {
-            regex: /%2f/g,
-            replacement: '/'
-        },
-        {
-            regex: /%5c/g,
-            replacement: '\\'
-        }
-    ],
-    parentDirectoryRegEx: /[\/\\]\.\.[\/\\]/g,
-    notAllowedRegEx: /:|\$|!|'|"|@|\+|`|\||=/g
-}
-
-function sanitize (pathToSanitize, options = DEFAULT_OPTIONS) {
-    if (!options) options = DEFAULT_OPTIONS
-    if (typeof options !== 'object') throw new Error('options must be an object')
-    if (!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 pathToSanitize !== 'string') {
-        // Stringify the path
-        pathToSanitize = `${pathToSanitize}`
-    }
-
-    let sanitizedPath = pathToSanitize
-
-    // Decode
-    options.decode.forEach(decode => {
-        sanitizedPath = sanitizedPath.replace(decode.regex, decode.replacement)
-    })
-
-    // Replace first (back)slash with a normal slash
-    sanitizedPath = sanitizedPath.replace(/^[\/\\]?/, '/')
-
-    // Replace /../ with /
-    sanitizedPath = sanitizedPath.replace(options.parentDirectoryRegEx, '/')
-
-    // Replace double (back)slashes with a single slash
-    sanitizedPath = sanitizedPath.replace(/[\/\\]+/g, '/')
-
-    // Normalize path
-    sanitizedPath = path.normalize(sanitizedPath)
-
-    // Remove / or \ in the end
-    while (sanitizedPath.endsWith('/') || sanitizedPath.endsWith('\\')) {
-        sanitizedPath = sanitizedPath.slice(0, -1)
-    }
-
-    // Remove / or \ in the beginning
-    while (sanitizedPath.startsWith('/') || sanitizedPath.startsWith('\\')) {
-        sanitizedPath = sanitizedPath.slice(1)
-    }
-
-    // Validate path
-    sanitizedPath = path.join('', sanitizedPath)
-
-    // Remove not allowed characters
-    sanitizedPath = sanitizedPath.replace(options.notAllowedRegEx, '')
-
-    return sanitizedPath
-}
-
-module.exports = sanitize