url-sanitizer 0.5.5 → 0.6.0

package/README.md

@@ -49,47 +49,65 @@ Sanitize the given URL.
 Returns **[Promise][5]<[string][1]?>** Sanitized URL, `null`able.
 
 ```javascript
-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;'
+// Sanitize tags and quotes
+const res1 = await sanitizeURL('http://example.com/"onmouseover="alert(1)"?<script>alert(\'XSS\');</script>');
+// => 'http://example.com/%26quot;onmouseover=%26quot;alert(1)%26quot;?%26lt;script%26gt;alert(%26%2339;XSS%26%2339;);%26lt;/script%26gt;'
 
-const res2 = await sanitizeURL('data:text/html,<script>alert(1);</script>', {
+console.log(decodeURIComponent(res1));
+// => 'http://example.com/&quot;onmouseover=&quot;alert(1)&quot;?&lt;script&gt;alert(&#39;XSS&#39;);&lt;/script&gt;'
+
+// Parse and purify data URL
+const res2 = await sanitizeURL('data:text/html,<div><script>alert(1);</script></div><p onclick="alert(2)"></p>', {
   allow: ['data']
-}).then(res => decodeURIComponent(res));
-// => 'data:text/html,&lt;script&gt;alert(1);&lt;/script&gt;'
+})
+// -> 'data:text/html,%3Cdiv%3E%3C%2Fdiv%3E%3Cp%3E%3C%2Fp%3E'
+
+console.log(decodeURIComponent(res2));
+// => 'data:text/html,<div></div><p></p>'
 
-// Can parse and sanitize base64 encoded data
-const base64data3 = btoa('<script>alert(1);</script>');
+// Can also parse and purify base64 encoded data
+const base64data3 = btoa('<div><script>alert(1);</script></div>');
 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;'
+})
+// => 'data:text/html,%3Cdiv%3E%3C%2Fdiv%3E'
+
+console.log(decodeURIComponent(res3));
+// => 'data:text/html,<div></div>'
+
+const base64data4 = btoa('<div><iframe src="javascript:alert(1)"></iframe></div>');
+const res4 = await sanitizeURL(`data:text/html;base64,${base64data4}`);
+// => 'data:text/html,%3Cdiv%3E%3C%2Fdiv%3E'
+
+console.log(decodeURIComponent(res4));
+// => 'data:text/html,<div></div>'
 
-const res4 = await sanitizeURL('web+foo://example.com', {
+const res5 = await sanitizeURL('web+foo://example.com', {
   deny: ['web+foo']
 });
 // => null
 
-const res5 = await sanitizeURL('http://example.com', {
+const res6 = await sanitizeURL('http://example.com', {
   only: ['data', 'git', 'https']
 });
 // => null
 
-const res6 = await sanitizeURL('https://example.com/"onmouseover="alert(1)"', {
+const res7 = 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;'
+});
+// => 'https://example.com/%26quot;onmouseover=%26quot;alert(1)%26quot;'
 
-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;'
+console.log(decodeURIComponent(res7));
+// => 'https://example.com/&quot;onmouseover=&quot;alert(1)&quot;'
 
 // `only` option also allows combinations of the specified schemes
-const res8 = await sanitizeURL('git+https://example.com', {
+const res8 = await sanitizeURL('git+https://example.com/foo.git?<script>alert(1)</script>', {
   only: ['data', 'git', 'https']
-}).then(res => decodeURIComponent(res));;
-// => 'git+https://example.com'
+});
+// => 'git+https://example.com/foo.git?%26lt;script%26gt;alert(1)%26lt;/script%26gt;'
+
+console.log(decodeURIComponent(res8));
+// => 'git+https://example.com/foo.git?&lt;script&gt;alert(1)&lt;/script&gt;'
 ```
 
 
@@ -122,18 +140,18 @@ Type: [object][3]
   * `data.mime` **[string][1]** MIME type.
   * `data.base64` **[boolean][2]** `true` if base64 encoded.
   * `data.data` **[string][1]** Data part of the data URL.
-* `href` **[string][1]** Same as URL API.
-* `origin` **[string][1]** Same as URL API.
-* `protocol` **[string][1]** Same as URL API.
-* `username` **[string][1]** Same as URL API.
-* `password` **[string][1]** Same as URL API.
-* `host` **[string][1]** Same as URL API.
-* `hostname` **[string][1]** Same as URL API.
-* `port` **[string][1]** Same as URL API.
-* `pathname` **[string][1]** Same as URL API.
-* `search` **[string][1]** Same as URL API.
-* `searchParams` **[object][3]** Same as URL API.
-* `hash` **[string][1]** Same as URL API.
+* `href` **[string][1]** Sanitized URL input.
+* `origin` **[string][1]** Scheme, domain and port of the sanitized URL.
+* `protocol` **[string][1]** Protocol scheme of the sanitized URL.
+* `username` **[string][1]** Username specified before the domain name.
+* `password` **[string][1]** Password specified before the domain name.
+* `host` **[string][1]** Domain and port of the sanitized URL.
+* `hostname` **[string][1]** Domain of the sanitized URL.
+* `port` **[string][1]** Port number of the sanitized URL.
+* `pathname` **[string][1]** Path of the sanitized URL.
+* `search` **[string][1]** Query string of the sanitized URL.
+* `searchParams` **[object][3]** [URLSearchParams](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) object.
+* `hash` **[string][1]** Fragment identifier of the sanitized URL.
 
 ```javascript
 const res1 = await parseURL('javascript:alert(1)');
@@ -144,50 +162,52 @@ const res1 = await parseURL('javascript:alert(1)');
 
 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: '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 onclick="alert(1)"/></svg>'
+const res3 = await parseURL('data:image/svg+xml;base64,PHN2Zz48ZyBvbmNsaWNrPSJhbGVydCgxKSIvPjwvc3ZnPg==');
 /* => {
-  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;',
-  ...
-} */
+        input: 'data:image/svg+xml;base64,PHN2Zz48ZyBvbmNsaWNrPSJhbGVydCgxKSIvPjwvc3ZnPg==',
+        valid: true,
+        data: {
+          mime: 'image/svg+xml',
+          base64: false,
+          data: '%3Csvg%3E%3Cg%3E%3C%2Fg%3E%3C%2Fsvg%3E'
+        },
+        href: 'data:image/svg+xml,%3Csvg%3E%3Cg%3E%3C%2Fg%3E%3C%2Fsvg%3E',
+        origin: 'null',
+        protocol: 'data:',
+        pathname: 'image/svg+xml,%3Csvg%3E%3Cg%3E%3C%2Fg%3E%3C%2Fsvg%3E',
+        ...
+      } */
 
 // 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==',
-  ...
-} */
+        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==',
+        origin: 'null',
+        protocol: 'data:',
+        pathname: 'image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==',
+        ...
+      } */
 ```
 
 
@@ -211,16 +231,19 @@ Returns **[Promise][5]<[boolean][2]>** Result.
 const res1 = await isURI('https://example.com/foo');
 // => true
 
-const res2 = await isURI('mailto:foo@example.com');
+const res2 = await isURI('javascript:alert(1)');
+// => false
+
+const res3 = await isURI('mailto:foo@example.com');
 // => true
 
-const res3 = await isURI('foo:bar');
+const res4 = await isURI('foo:bar');
 // => false
 
-const res4 = await isURI('web+foo:bar');
+const res5 = await isURI('web+foo:bar');
 // => true
 
-const res5 = await isURI('web+javascript:alert(1)');
+const res6 = await isURI('web+javascript:alert(1)');
 // => false
 ```
 
@@ -237,11 +260,13 @@ Instance of the sanitizer.
 
 ### urlSanitizer.get()
 
-Get an array of URI schemes registered at [iana.org](https://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml "Uniform Resource Identifier (URI) Schemes").
-* Historical schemes omitted.
-* `moz-extension` scheme added.
+Get a list of registered URI schemes.
 
 Returns **[Array][4]<[string][1]>** Array of registered URI schemes.
+* Includes schemes registered at [iana.org](https://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml "Uniform Resource Identifier (URI) Schemes") by default.
+  * Historical schemes omitted.
+  * `moz-extension` scheme added.
+* Also includes custom schemes added via [urlSanitizer.add()](#urlsanitizeraddscheme).
 
 ```javascript
 const schemes = urlSanitizer.get();
@@ -268,7 +293,7 @@ const res2 = urlSanitizer.has('foo');
 
 ### urlSanitizer.add(scheme)
 
-Add a scheme to the list of URI schemes.
+Add a scheme to the list of registered URI schemes.
 * `javascript` and `vbscript` schemes can not be registered. It throws.
 
 #### Parameters
@@ -278,19 +303,19 @@ Add a scheme to the list of URI schemes.
 Returns **[Array][4]<[string][1]>** Array of registered URI schemes.
 
 ```javascript
-console.log(isURISync('foo'));
+console.log(urlSanitizer.has('foo'));
 // => false
 
 const res = urlSanitizer.add('foo');
 // => ['aaa', 'aaas', 'about', 'acap', ... 'foo', ...]
 
-console.log(isURISync('foo'));
+console.log(urlSanitizer.has('foo'));
 // => true
 ```
 
 ### urlSanitizer.remove(scheme)
 
-Remove a scheme from the list of URI schemes.
+Remove a scheme from the list of registered URI schemes.
 
 #### Parameters
 
@@ -300,13 +325,13 @@ Returns **[boolean][2]** Result.
 * `true` if the scheme is successfully removed, `false` otherwise.
 
 ```javascript
-console.log(isURISync('aaa'));
+console.log(urlSanitizer.has('aaa'));
 // => true
 
 const res1 = urlSanitizer.remove('aaa');
 // => true
 
-console.log(isURISync('aaa'));
+console.log(urlSanitizer.has('aaa'));
 // => false
 
 const res2 = urlSanitizer.remove('foo');
@@ -319,6 +344,7 @@ const res2 = urlSanitizer.remove('foo');
 
 The following resources have been of great help in the development of the URL Sanitizer.
 
+* [DOMPurify](https://www.npmjs.com/package/dompurify?activeTab=readme)
 * [Uniform Resource Identifier (URI) Schemes - IANA](https://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml)
 * [Encoding -- determine the character encoding of a text file. - file/file](https://github.com/file/file/blob/master/src/encoding.c)