url-sanitizer

URL Sanitizer

URL sanitizer for Node.js (>=18), browsers and web sites. Experimental

Install

npm i url-sanitizer

For browsers and web sites, standalone ESM builds are available in dist/ directory.

• node_modules/url-sanitizer/dist/url-sanitizer.js
• node_modules/url-sanitizer/dist/url-sanitizer.min.js

Or, download them from Releases.

Usage

import urlSanitizer, {
  isURI, isURISync, sanitizeURL, sanitizeURLSync
} from 'url-sanitizer';

sanitizeURL(url, opt)

Sanitize the given URL.

• data and file schemes must be explicitly allowed.

Parameters

• url string URL input.
• opt object Options.
• opt.allow Array<string> Array of allowed schemes, e.g. ['data'].
• opt.deny Array<string> Array of denied schemes, e.g. ['web+foo'].

Returns Promise<string?> Sanitized URL, nullable.

const res1 = await sanitizeURL('http://example.com/?<script>alert(1);</script>')
  .then(res => decodeURIComponent(res));
// -> 'http://example.com/?&lt;script&gt;alert(1);&lt;/script&gt;'

const res2 = await sanitizeURL('data:text/html,<script>alert(1);</script>', {
  allow: ['data']
}).then(res => decodeURIComponent(res));
// -> 'data:text/html,&lt;script&gt;alert(1);&lt;/script&gt;'

// Can parse and sanitize base64 encoded data
const base64data3 = btoa('<script>alert(1);</script>');
const res3 = await sanitizeURL(`data:text/html;base64,${base64data3}`, {
  allow: ['data']
}).then(res => decodeURIComponent(res));
// -> 'data:text/html,&lt;script&gt;alert(1);&lt;/script&gt;'

const res4 = await sanitizeURL('web+foo://example.com', {
  deny: ['web+foo']
});
// -> null

sanitizeURLSync

Synchronous version of the sanitizeURL().

isURI(uri)

Determines whether the given URI is valid.

Parameters

• uri string URI input.

Returns Promise<boolean> Result.

• Always true for web+* and ext+* schemes.

const res1 = await isURI('https://example.com/foo');
// -> true

const res2 = await isURI('mailto:[e-mail]');
// -> true

const res3 = await isURI('foo:bar');
// -> false

const res4 = await isURI('web+foo:bar');
// -> true

isURISync(uri)

Synchronous version of the isURI().

urlSanitizer

Instance of the sanitizer.

urlSanitizer.get()

Get an array of URI schemes registered at iana.org.

• Historical schemes omitted.
• moz-extension scheme added.

Returns Array<string> Array of registered URI schemes.

const schemes = urlSanitizer.get();
// -> ['aaa', 'aaas', 'about', 'acap', 'acct', ...];

urlSanitizer.has(scheme)

Check if the given scheme is registered.

Parameters

• scheme string Scheme.

Returns boolean Result.

const res1 = urlSanitizer.has('https');
// -> true

const res2 = urlSanitizer.has('foo');
// -> false

urlSanitizer.add(scheme)

Add a scheme to the list of URI schemes.

• javascript and vbscript schemes can not be registered. It throws.

Parameters

• scheme string Scheme.

Returns Array<string> Array of registered URI schemes.

console.log(isURISync('foo'));
// -> false;

const res = urlSanitizer.add('foo');
// -> ['aaa', 'aaas', 'about', 'acap', ... 'foo', ...];

console.log(isURISync('foo'));
// -> true;

urlSanitizer.remove(scheme)

Remove a scheme from the list of URI schemes.

Parameters

• scheme string Scheme.

Returns boolean Result.

• true if the scheme is successfully removed, false otherwise.

console.log(isURISync('aaa'));
// -> true;

const res1 = urlSanitizer.remove('aaa');
// -> true

console.log(isURISync('aaa'));
// -> false;

const res2 = urlSanitizer.remove('foo');
// -> false