als-normalize-urlpath

als-normalize-urlpath is a library designed for normalizing URL paths in both Node.js and browser environments. It's especially useful for sanitizing and standardizing relative URL paths.

Installation

Node.js

Node.js version 10 or higher is required, as the library utilizes the URL class, which is not available in older versions of Node.js.

To install als-normalize-urlpath, use npm:

npm install als-normalize-urlpath

Browser

For browser usage, include the library script in your HTML. Ensure you have a browser-compatible version of the library.

<script src="path_to_als-normalize-urlpath.js"></script>

Usage

Node.js

After installation, you can require and use the als-normalize-urlpath in your Node.js application:

const normalizeUrlPath = require('als-normalize-urlpath');

const result = normalizeUrlPath('/some/path');
console.log(result);

Browser

In the browser, the normalizeUrlPath function will be available after including the script:

const result = normalizeUrlPath('/some/path');
console.log(result);

Functionality

The normalizeUrlPath function processes and normalizes relative URL paths. It performs the following operations:

• Checks if the input is a string.
• Validates that the URL is not a full URL (e.g., starting with 'http:', 'mailto:', etc.) or a special URL (e.g., 'data:', 'blob:').
• Limits the URL length to a maximum of 2000 characters.
• Removes dot segments to prevent directory traversal attacks.
• Replaces backslashes with forward slashes and removes redundant slashes.
• Decodes URL-encoded characters.
• Converts the pathname to lowercase.
• Adds a leading slash if absent and removes a trailing slash if present (except for the root /).
• Parses query parameters into an object and retains the hash fragment.

Returns an object with pathname, query, and hash, or an object with pathname set to null in case of errors or invalid input.

Function Signature

function normalizeUrlPath(urlPath,toLowerCase=false) {
    // Function implementation...
}

Parameters

• urlPath (String): The URL path to be normalized. This should be a relative URL.

Return Value

• Object: An object containing the following properties:
  • pathname (String): The normalized pathname of the URL.
  • query (Object): An object representing the query parameters of the URL.
  • hash (String): The hash fragment of the URL.

If the URL path is invalid or cannot be processed, the function returns an object with pathname set to null.

Corrections and Normalizations

1. Relative Path Only: The function accepts only relative paths and rejects full URLs (e.g., those starting with 'http:', 'mailto:', etc.).

   normalizeUrlPath('http://example.com/test'); // Returns { pathname: null }

2. Slash Normalization: Converts backslashes (\) to forward slashes (/) and reduces multiple slashes to a single slash.

   normalizeUrlPath('\\test\\path'); // Returns { pathname: '/test/path' }

3. Removing Dot Segments: Dot segments (../ or /..) are removed to prevent directory traversal attacks.

   normalizeUrlPath('/../test'); // Returns { pathname: '/test' }

4. URL Decoding: Decodes URL-encoded characters.

   normalizeUrlPath('/test%20url'); // Returns { pathname: '/test url' }

5. Lowercase Conversion: Converts the pathname to lowercase.

   normalizeUrlPath('/Test/Path',true); // Returns { pathname: '/test/path' }

6. Leading and Trailing Slashes: Ensures that the pathname starts with a slash and does not end with a slash (unless it's the root /).

   normalizeUrlPath('test/'); // Returns { pathname: '/test' }

7. Length Check: Rejects URL paths exceeding 2000 characters.

   normalizeUrlPath('/'.repeat(2001)); // Returns { pathname: null }

8. Query Parsing: Parses query parameters into an object.

   normalizeUrlPath('/test?param=value'); // Returns { pathname: '/test', query: { param: 'value' } }

9. Restricted Characters: Rejects paths containing certain restricted characters (&, =, @, +, ?, %, #).

   normalizeUrlPath('/test&path'); // Returns { pathname: null }

Example Usage

const result = normalizeUrlPath('/test/path?param=value#section');
// result: { pathname: '/test/path', query: { param: 'value' }, hash: '#section' }

This function is essential for handling and sanitizing relative URL paths in web applications, ensuring they conform to a standard format and mitigating common security risks.