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, parseURL, parseURLSync, 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'].
  • opt.only Array<string> Array of specific schemes to allow, e.g. ['git', 'https']. only takes precedence over allow and deny.

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

const res5 = await sanitizeURL('http://example.com', {
  only: ['data', 'git', 'https']
});
// => null

const res6 = await sanitizeURL('https://example.com/"onmouseover="alert(1)"', {
  only: ['data', 'git', 'https']
}).then(res => decodeURIComponent(res));
// => 'https://example.com/&quot;onmouseover=&quot;alert(1)&quot;'

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

// `only` option also allows combinations of the specified schemes
const res8 = await sanitizeURL('git+https://example.com', {
  only: ['data', 'git', 'https']
}).then(res => decodeURIComponent(res));;
// => 'git+https://example.com'

sanitizeURLSync

Synchronous version of the sanitizeURL().

parseURL(url)

Parse the given URL.

Parameters

• url string URL input.

Returns Promise<ParsedURL> Result.

ParsedURL

Object with extended properties based on URL API.

Type: object

Properties

• input string URL input.
• valid boolean Is valid URI.
• data object Parsed result of data URL, nullable.
  • data.mime string MIME type.
  • data.base64 boolean true if base64 encoded.
  • data.data string Data part of the data URL.
• href string Same as URL API.
• origin string Same as URL API.
• protocol string Same as URL API.
• username string Same as URL API.
• password string Same as URL API.
• host string Same as URL API.
• hostname string Same as URL API.
• port string Same as URL API.
• pathname string Same as URL API.
• search string Same as URL API.
• searchParams object Same as URL API.
• hash string Same as URL API.

const res1 = await parseURL('javascript:alert(1)');
/* => {
  input: 'javascript:alert(1)',
  valid: false
} */

const res2 = await parseURL('https://example.com/?foo=bar#baz');
/* => {
  input: 'https://www.example.com/?foo=bar#baz',
  valid: true,
  data: null,
  href: 'https://www.example.com/?foo=bar#baz',
  origin: 'https://www.example.com',
  protocol: 'https:',
  hostname: 'www.example.com',
  pathname: '/',
  search: '?foo=bar',
  hash: '#baz',
  ...
} */

// base64 encoded svg '<svg><g onload="alert(1)"/></svg>'
const res3 = await parseURL('data:image/svg+xml;base64,PHN2Zz48ZyBvbmxvYWQ9ImFsZXJ0KDEpIi8+PC9zdmc+');
/* => {
  input: 'data:image/svg+xml;base64,PHN2Zz48ZyBvbmxvYWQ9ImFsZXJ0KDEpIi8+PC9zdmc+',
  valid: true,
  data: {
    mime: 'image/svg+xml',
    base64: false,
    data: '%26lt;svg%26gt;%26lt;g%20onload=%26quot;alert(1)%26quot;/%26gt;%26lt;/svg%26gt;'
  },
  href: 'data:image/svg+xml,%26lt;svg%26gt;%26lt;g%20onload=%26quot;alert(1)%26quot;/%26gt;%26lt;/svg%26gt;',
  protocol: 'data:',
  pathname: 'image/svg+xml,%26lt;svg%26gt;%26lt;g%20onload=%26quot;alert(1)%26quot;/%26gt;%26lt;/svg%26gt;',
  ...
} */

// base64 encoded png
const res4 = await parseURL('data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==');
/* => {
  input: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==',
  valid: true,
  data: {
    mime: 'image/png',
    base64: true,
    data: 'iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg=='
  },
  href: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==',
  protocol: 'data:',
  pathname: 'image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==',
  ...
} */

parseURLSync(url)

Synchronous version of the parseURL().

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, except web+javascript, web+vbscript, ext+javascript, ext+vbscript.

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

const res5 = await isURI('web+javascript:alert(1)');
// => false

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

---

Acknowledgments

The following resources have been of great help in the development of the URL Sanitizer.

• Uniform Resource Identifier (URI) Schemes - IANA
• Encoding -- determine the character encoding of a text file. - file/file

---

Copyright (c) 2023 asamuzaK (Kazz)