url-sanitizer

urlSanitizer

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 the source code from Releases.

Usage

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

sanitizeURL(url, opt)

Sanitize the given URL.

• data and/or file schemes must be explicitly allowed.
• javascript and/or vbscript schemes can not be allowed.

Parameters

• url string URL input
• opt object options

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;'

// Also an option if you don't want to escape tags and quotes in data URL
// But use it with care
const res4 = await sanitizeURL('data:image/svg+xml,%3Csvg%3E%3C/svg%3E', {
  allow: ['data'],
  escapeTags: false
}).then(res => decodeURIComponent(res));
// -> 'data:image/svg+xml,<svg></svg>'

const res5 = await sanitizeURL('data:text/html,%3Cscript%3Ealert(1);%3C/script%3E', {
  allow: ['data'],
  escapeTags: false
}).then(res => decodeURIComponent(res));
// WATCH OUT!!!
// -> 'data:text/html,<script>alert(1);</script>'

sanitizeURLSync

Synchronous version of the sanitizeURL().

isURI(uri)

Determines whether the given URI is valid.

Parameters

• uri string URI input

Returns Promise<boolean?> result

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

urlSanitizer.get()

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

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

Returns Array<string> array of registered URI schemes

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

urlSanitizer.has(scheme)

Check if the given scheme is registered.

Parameters

• scheme string scheme

Returns boolean result

• Always true for web+* and/or ext+* schemes

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

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

const res3 = uriSanitizer.has('web+foo');
// -> true

urlSanitizer.add(scheme)

Add a scheme to the list of URI schemes.

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

Parameters

• scheme string scheme

Returns Array<string> array of registered URI schemes

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

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.

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

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