url-sanitizer 0.4.3 → 0.5.1

package/README.md

@@ -8,6 +8,7 @@
 URL sanitizer for Node.js (>=18), browsers and web sites.
 **Experimental**
 
+
 ## Install
 
 ```shell
@@ -20,14 +21,16 @@ For browsers and web sites, standalone ESM builds are available in `dist/` direc
 
 Or, download them from [Releases](https://github.com/asamuzaK/urlSanitizer/releases).
 
+
 ## Usage
 
 ```javascript
 import urlSanitizer, {
-  isURI, isURISync, sanitizeURL, sanitizeURLSync
+  isURI, isURISync, parseURL, parseURLSync, sanitizeURL, sanitizeURLSync
 } from 'url-sanitizer';
 ```
 
+
 ## sanitizeURL(url, opt)
 
 Sanitize the given URL.
@@ -35,69 +38,198 @@ Sanitize the given URL.
 
 ### Parameters
 
-* `url` **[string][1]** URL input
-* `opt` **[object][3]** Options
-* `opt.allow` **[Array][4]<[string][1]>** Array of allowed schemes, e.g. `['data']`
-* `opt.deny` **[Array][4]<[string][1]>** Array of denied schemes, e.g. `['web+foo']`
+* `url` **[string][1]** URL input.
+* `opt` **[object][3]** Options.
+  * `opt.allow` **[Array][4]<[string][1]>** Array of allowed schemes, e.g. `['data']`.
+  * `opt.deny` **[Array][4]<[string][1]>** Array of denied schemes, e.g. `['web+foo']`.
+  * `opt.only` **[Array][4]<[string][1]>** Array of specific schemes to allow, e.g. `['git', 'https']`.
+    `only` takes precedence over `allow` and `deny`.
 
-Returns **[Promise][5]<[string][1]?>** Sanitized URL, `null`able
+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;'
+// => '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;'
+// => '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;'
+// => 'data:text/html,&lt;script&gt;alert(1);&lt;/script&gt;'
 
 const res4 = await sanitizeURL('web+foo://example.com', {
   deny: ['web+foo']
 });
-// -> null
+// => 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()](#sanitizeurlurl-opt).
 
+
+## parseURL(url)
+
+Parse the given URL.
+
+### Parameters
+
+* `url` **[string][1]** URL input.
+
+Returns **[Promise][5]<[ParsedURL](#parsedurl)>** Result.
+
+### ParsedURL
+
+Object with extended properties based on [URL](https://developer.mozilla.org/ja/docs/Web/API/URL) API.
+
+Type: [object][3]
+
+#### Properties
+
+* `input` **[string][1]** URL input.
+* `valid` **[boolean][2]** Is valid URI.
+* `data` **[object][3]** Parsed result of data URL, `null`able.
+  * `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.
+
+```javascript
+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()](#parseURL).
+
+
 ## isURI(uri)
 
 Determines whether the given URI is valid.
 
 ### Parameters
 
-* `uri` **[string][1]** URI input
+* `uri` **[string][1]** URI input.
 
-Returns **[Promise][5]<[boolean][2]>** Result
-* Always `true` for `web+*` and `ext+*` schemes
+Returns **[Promise][5]<[boolean][2]>** Result.
+* Always `true` for `web+*` and `ext+*` schemes, except `web+javascript`, `web+vbscript`, `ext+javascript`, `ext+vbscript`.
 
 ```javascript
 const res1 = await isURI('https://example.com/foo');
-// -> true
+// => true
 
 const res2 = await isURI('mailto:foo@example.com');
-// -> true
+// => true
 
 const res3 = await isURI('foo:bar');
-// -> false
+// => false
 
 const res4 = await isURI('web+foo:bar');
-// -> true
+// => true
+
+const res5 = await isURI('web+javascript:alert(1)');
+// => false
 ```
 
+
 ## isURISync(uri)
 
 Synchronous version of the [isURI()](#isuriuri).
 
+---
+
 ## urlSanitizer
 
 Instance of the sanitizer.
@@ -108,11 +240,11 @@ Get an array of URI schemes registered at [iana.org](https://www.iana.org/assign
 * Historical schemes omitted.
 * `moz-extension` scheme added.
 
-Returns **[Array][4]<[string][1]>** Array of registered URI schemes
+Returns **[Array][4]<[string][1]>** Array of registered URI schemes.
 
 ```javascript
 const schemes = urlSanitizer.get();
-// -> ['aaa', 'aaas', 'about', 'acap', 'acct', 'acd', 'acr', ...];
+// => ['aaa', 'aaas', 'about', 'acap', 'acct', ...];
 ```
 
 ### urlSanitizer.has(scheme)
@@ -121,16 +253,16 @@ Check if the given scheme is registered.
 
 #### Parameters
 
-* `scheme` **[string][1]** Scheme
+* `scheme` **[string][1]** Scheme.
 
-Returns **[boolean][2]** Result
+Returns **[boolean][2]** Result.
 
 ```javascript
 const res1 = urlSanitizer.has('https');
-// -> true
+// => true
 
 const res2 = urlSanitizer.has('foo');
-// -> false
+// => false
 ```
 
 ### urlSanitizer.add(scheme)
@@ -140,19 +272,19 @@ Add a scheme to the list of URI schemes.
 
 #### Parameters
 
-* `scheme` **[string][1]** Scheme
+* `scheme` **[string][1]** Scheme.
 
-Returns **[Array][4]<[string][1]>** Array of registered URI schemes
+Returns **[Array][4]<[string][1]>** Array of registered URI schemes.
 
 ```javascript
 console.log(isURISync('foo'));
-// -> false;
+// => false;
 
 const res = urlSanitizer.add('foo');
-// -> ['aaa', 'aaas', 'about', 'acap', 'acct', 'acd', ... 'foo', ...];
+// => ['aaa', 'aaas', 'about', 'acap', ... 'foo', ...];
 
 console.log(isURISync('foo'));
-// -> true;
+// => true;
 ```
 
 ### urlSanitizer.remove(scheme)
@@ -161,23 +293,23 @@ Remove a scheme from the list of URI schemes.
 
 #### Parameters
 
-* `scheme` **[string][1]** Scheme
+* `scheme` **[string][1]** Scheme.
 
-Returns **[boolean][2]** Result
+Returns **[boolean][2]** Result.
 * `true` if the scheme is successfully removed, `false` otherwise.
 
 ```javascript
 console.log(isURISync('aaa'));
-// -> true;
+// => true;
 
 const res1 = urlSanitizer.remove('aaa');
-// -> true
+// => true
 
 console.log(isURISync('aaa'));
-// -> false;
+// => false;
 
 const res2 = urlSanitizer.remove('foo');
-// -> false
+// => false
 ```
 
 [1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String

package/dist/url-sanitizer.js

@@ -591,14 +591,17 @@ var uri_schemes_default = [
 
 // src/mjs/uri-util.js
 var HEX = 16;
-var REG_CHARS = /[<>"'\s]/g;
+var REG_BASE64 = /^[\da-z+/\-_=]+$/i;
 var REG_DATA_URL = /data:[^,]*,[^"]+/g;
-var REG_DATA_URL_BASE64 = /data:[^,]*;?base64,[\dA-Za-z+/\-_=]+/;
-var REG_DATA_URL_HEADER = /data:[^,]*,/;
+var REG_DATA_URL_BASE64 = /data:[^,]*;?base64,[\da-z+/\-_=]+/i;
+var REG_HTML_SP = /[<>"'\s]/g;
+var REG_HTML_SP_URL_ENC = /%(?:2(?:2|7)|3(?:C|E))/g;
 var REG_NUM_REF = /&#(x(?:00)?[\dA-F]{2}|0?\d{1,3});?/ig;
-var REG_SCHEME = /^[a-z][a-z0-9+\-.]*$/;
+var REG_SCHEME = /^[a-z][\da-z+\-.]*$/;
 var REG_SCHEME_CUSTOM = /^(?:ext|web)\+[a-z]+$/;
 var REG_SCRIPT = /(?:java|vb)script/;
+var REG_URL_ENC = /^%[\dA-F]{2}$/i;
+var REG_URL_ENC_AMP = /%26/g;
 var getUrlEncodedString = (str) => {
   if (!isString(str)) {
     throw new TypeError(`Expected String but got ${getType(str)}.`);
@@ -611,7 +614,7 @@ var getUrlEncodedString = (str) => {
 };
 var escapeUrlEncodedHtmlChars = (ch) => {
   if (isString(ch)) {
-    if (/^%[\dA-F]{2}$/i.test(ch)) {
+    if (REG_URL_ENC.test(ch)) {
       ch = ch.toUpperCase();
     } else {
       throw new Error(`Invalid URL encoded character: ${ch}`);
@@ -639,14 +642,14 @@ var escapeUrlEncodedHtmlChars = (ch) => {
 var parseBase64 = (data) => {
   if (!isString(data)) {
     throw new TypeError(`Expected String but got ${getType(data)}.`);
-  } else if (!/^[\dA-Za-z+/\-_=]+$/.test(data)) {
+  } else if (!REG_BASE64.test(data)) {
     throw new Error(`Invalid base64 data: ${data}`);
   }
   const bin = atob(data);
   const uint8arr = Uint8Array.from([...bin].map((c) => c.charCodeAt(0)));
-  const textChars = new Set(text_chars_default);
+  const textCharCodes = new Set(text_chars_default);
   let parsedData;
-  if (uint8arr.every((c) => textChars.has(c))) {
+  if (uint8arr.every((c) => textCharCodes.has(c))) {
     parsedData = bin.replace(/\s/g, getUrlEncodedString);
   } else {
     parsedData = data;
@@ -664,7 +667,7 @@ var parseUrlEncodedNumCharRef = (str, nest = 0) => {
   }
   let res = decodeURIComponent(str);
   if (/&#/.test(res)) {
-    const textChars = new Set(text_chars_default);
+    const textCharCodes = new Set(text_chars_default);
     const items = [...res.matchAll(REG_NUM_REF)].reverse();
     for (const item of items) {
       const [numCharRef, value] = item;
@@ -680,9 +683,9 @@ var parseUrlEncodedNumCharRef = (str, nest = 0) => {
           res.substring(0, index),
           res.substring(index + numCharRef.length)
         ];
-        if (textChars.has(num)) {
+        if (textCharCodes.has(num)) {
           res = `${preNum}${String.fromCharCode(num)}${postNum}`;
-          if (/#x?$/.test(preNum) || /^#x?[\d]+/.test(postNum)) {
+          if (/#x?$/.test(preNum) || /^#(?:x(?:00)?[2-7]|\d)/.test(postNum)) {
             res = parseUrlEncodedNumCharRef(res, ++nest);
           }
         } else if (num < HEX * HEX) {
@@ -789,16 +792,17 @@ var URLSanitizer = class extends URISchemes {
    * @param {object} opt - options
    * @param {Array.<string>} opt.allow - array of allowed schemes
    * @param {Array.<string>} opt.deny - array of denied schemes
+   * @param {Array.<string>} opt.only - array of specific schemes to allow
    * @returns {?string} - sanitized URL
    */
-  sanitize(url, opt = { allow: [], deny: [] }) {
+  sanitize(url, opt = { allow: [], deny: [], only: [] }) {
     if (this.#nest > HEX) {
       this.#nest = 0;
       throw new Error("Data URLs nested too deeply.");
     }
     let sanitizedUrl;
     if (super.isURI(url)) {
-      const { allow, deny } = opt ?? {};
+      const { allow, deny, only } = opt ?? {};
       const { hash, href, pathname, protocol, search } = new URL(url);
       const scheme = protocol.replace(/:$/, "");
       const schemeParts = scheme.split("+");
@@ -808,8 +812,12 @@ var URLSanitizer = class extends URISchemes {
         ["javascrpt", false],
         ["vbscript", false]
       ]);
-      if (Array.isArray(allow) && allow.length) {
-        const items = Object.values(allow);
+      if (Array.isArray(only) && only.length) {
+        const schemes = super.get();
+        for (const item of schemes) {
+          schemeMap.set(item, false);
+        }
+        const items = Object.values(only);
         for (let item of items) {
           if (isString(item)) {
             item = item.trim();
@@ -818,14 +826,26 @@ var URLSanitizer = class extends URISchemes {
             }
           }
         }
-      }
-      if (Array.isArray(deny) && deny.length) {
-        const items = Object.values(deny);
-        for (let item of items) {
-          if (isString(item)) {
-            item = item.trim();
-            if (item) {
-              schemeMap.set(item, false);
+      } else {
+        if (Array.isArray(allow) && allow.length) {
+          const items = Object.values(allow);
+          for (let item of items) {
+            if (isString(item)) {
+              item = item.trim();
+              if (!REG_SCRIPT.test(item)) {
+                schemeMap.set(item, true);
+              }
+            }
+          }
+        }
+        if (Array.isArray(deny) && deny.length) {
+          const items = Object.values(deny);
+          for (let item of items) {
+            if (isString(item)) {
+              item = item.trim();
+              if (item) {
+                schemeMap.set(item, false);
+              }
             }
           }
         }
@@ -838,15 +858,12 @@ var URLSanitizer = class extends URISchemes {
         }
       }
       if (bool) {
-        const [amp, lt, gt, quot, apos] = ["&", "<", ">", '"', "'"].map(getUrlEncodedString);
-        const regAmp = new RegExp(amp, "g");
-        const regEncodedChars = new RegExp(`(${lt}|${gt}|${quot}|${apos})`, "g");
         let escapeHtml;
         let urlToSanitize = href;
         if (schemeParts.includes("data")) {
-          const [header, ...body] = pathname.split(",");
+          const [head, ...body] = pathname.split(",");
           const data = `${body.join(",")}${search}${hash}`;
-          const mediaType = header.split(";");
+          const mediaType = head.split(";");
           let parsedData = data;
           if (mediaType[mediaType.length - 1] === "base64") {
             mediaType.pop();
@@ -862,7 +879,7 @@ var URLSanitizer = class extends URISchemes {
             } catch (e) {
             }
           }
-          const containsDataUrl = REG_DATA_URL_HEADER.test(parsedData);
+          const containsDataUrl = /data:[^,]*,/.test(parsedData);
           if (parsedData !== data || containsDataUrl) {
             if (containsDataUrl) {
               const matchedDataUrls = parsedData.matchAll(REG_DATA_URL);
@@ -906,9 +923,9 @@ var URLSanitizer = class extends URISchemes {
           escapeHtml = true;
         }
         if (urlToSanitize) {
-          sanitizedUrl = urlToSanitize.replace(REG_CHARS, getUrlEncodedString).replace(regAmp, escapeUrlEncodedHtmlChars);
+          sanitizedUrl = urlToSanitize.replace(REG_HTML_SP, getUrlEncodedString).replace(REG_URL_ENC_AMP, escapeUrlEncodedHtmlChars);
           if (escapeHtml) {
-            sanitizedUrl = sanitizedUrl.replace(regEncodedChars, escapeUrlEncodedHtmlChars);
+            sanitizedUrl = sanitizedUrl.replace(REG_HTML_SP_URL_ENC, escapeUrlEncodedHtmlChars);
             this.#nest = 0;
           }
         } else {
@@ -919,6 +936,77 @@ var URLSanitizer = class extends URISchemes {
     }
     return sanitizedUrl || null;
   }
+  /**
+   * object with extended props based on URL API
+   *
+   * @typedef {object} ParsedURL
+   * @property {string} input - URL input
+   * @property {boolean} valid - is valid URI
+   * @property {object} data - parsed result of data URL, `null`able
+   * @property {string} data.mime - MIME type
+   * @property {boolean} data.base64 - `true` if base64 encoded
+   * @property {string} data.data - data part of the data URL
+   * @property {string} href - same as URL API
+   * @property {string} origin - same as URL API
+   * @property {string} protocol - same as URL API
+   * @property {string} username - same as URL API
+   * @property {string} password - same as URL API
+   * @property {string} host - same as URL API
+   * @property {string} hostname - same as URL API
+   * @property {string} port - same as URL API
+   * @property {string} pathname - same as URL API
+   * @property {string} search - same as URL API
+   * @property {object} searchParams - same as URL API
+   * @property {string} hash - same as URL API
+   */
+  /**
+   * parse sanitized URL
+   *
+   * @param {string} url - URL input
+   * @returns {ParsedURL} - result with extended props based on URL API
+   */
+  parse(url) {
+    if (!isString(url)) {
+      throw new TypeError(`Expected String but got ${getType(url)}.`);
+    }
+    const sanitizedUrl = this.sanitize(url, {
+      allow: ["data", "file"]
+    });
+    const parsedUrl = /* @__PURE__ */ new Map([
+      ["input", url]
+    ]);
+    if (sanitizedUrl) {
+      const urlObj = new URL(sanitizedUrl);
+      const { pathname, protocol } = urlObj;
+      const schemeParts = protocol.replace(/:$/, "").split("+");
+      parsedUrl.set("valid", true);
+      if (schemeParts.includes("data")) {
+        const dataUrl = /* @__PURE__ */ new Map();
+        const [head, ...body] = pathname.split(",");
+        const data = `${body.join(",")}`;
+        const mediaType = head.split(";");
+        const isBase64 = mediaType[mediaType.length - 1] === "base64";
+        if (isBase64) {
+          mediaType.pop();
+        }
+        dataUrl.set("mime", mediaType.join(";"));
+        dataUrl.set("base64", isBase64);
+        dataUrl.set("data", data);
+        parsedUrl.set("data", Object.fromEntries(dataUrl));
+      } else {
+        parsedUrl.set("data", null);
+      }
+      for (const key in urlObj) {
+        const value = urlObj[key];
+        if (typeof value !== "function") {
+          parsedUrl.set(key, value);
+        }
+      }
+    } else {
+      parsedUrl.set("valid", false);
+    }
+    return Object.fromEntries(parsedUrl);
+  }
 };
 var urlSanitizer = new URLSanitizer();
 var isUri = (uri) => urlSanitizer.isURI(uri);
@@ -928,7 +1016,8 @@ var isURI = async (uri) => {
 };
 var sanitizeUrl = (url, opt) => urlSanitizer.sanitize(url, opt ?? {
   allow: [],
-  deny: []
+  deny: [],
+  only: []
 });
 var sanitizeURL = async (url, opt) => {
   const res = await sanitizeUrl(url, opt);