path-sanitizer 1.0.0 → 3.0.0

package/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - '**'
+  pull_request:
+    branches:
+      - '**'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 18
+          cache: 'pnpm'
+
+      - name: Install pnpm
+        run: npm install -g pnpm
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Run tests
+        run: pnpm test

package/README.md

@@ -1,2 +1,39 @@
 # path-sanitizer
- A simple node.js package for sanitizing paths to prevent Path Traversal
+ A simple lightweight npm package for sanitizing paths to prevent Path Traversal
+
+# Usage
+```js
+import sanitize from 'path-sanitizer'
+// or
+const sanitize = require('path-sanitizer').default
+
+console.log(sanitize('path/to/file.txt'))
+```
+
+Or here is a more complex example:
+```js
+const sanitize = require('../sanitize')
+const path = require('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\
+    // 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 usually read the file
+    // But in this case we will just print the path
+    console.log(sanitized)
+}
+
+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\\\\../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,31 @@
+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;
+export default function sanitize(pathstr: string, options?: SanitizeOptions): string;
+export {};

package/dist/index.js

@@ -0,0 +1,75 @@
+"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
+};
+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, '/');
+    return sanitizedPath;
+}

package/package.json

@@ -1,25 +1,26 @@
 {
-  "name": "path-sanitizer",
-  "version": "1.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.0",
+    "description": "A simple lightweight npm package for sanitizing paths to prevent Path Traversal",
+    "main": "dist/index.js",
+    "scripts": {
+        "test": "vitest"
+    },
+    "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,5 +0,0 @@
-function sanitize () {
-    
-}
-
-module.exports = sanitize