url-sanitizer 2.3.1 → 4.0.0

package/src/mjs/sanitizer.js

@@ -6,41 +6,70 @@
 import { domPurify } from './dompurify.js';
 import { getType, isString } from './common.js';
 import {
-  createDataURLFromBlob, escapeURLEncodedHTMLChars, parseBase64,
-  parseURLEncodedNumCharRef, URISchemes
+  URISchemes, createDataURLFromBlob, escapeURLEncodedHTMLChars, parseBase64,
+  parseURLEncodedNumCharRef, trimTrailingEmptyQueryAndHash
 } from './uri-util.js';
+
+/* constants */
+import { MAX_BLOB_SIZE, MAX_NEST } from './constant.js';
 import {
-  HEX, MAX_BLOB_SIZE, REG_DATA_URL, REG_DATA_URL_B64, REG_DATA_URL_G,
-  REG_MIME_DOM, REG_SCRIPT_BLOB, REG_TAG_QUOT
-} from './constant.js';
+  REG_MIME_DOM, REG_SCHEME, REG_SCRIPT, REG_SCRIPT_BLOB, REG_TAG_QUOT,
+  REG_VERIFY_RELATIVE
+} from './regexp.js';
+const URL_PROPS = Object.freeze([
+  'href',
+  'origin',
+  'protocol',
+  'username',
+  'password',
+  'host',
+  'hostname',
+  'port',
+  'pathname',
+  'search',
+  'hash'
+]);
+const INTERNAL_PURIFY_CONFIG = Object.freeze({
+  RETURN_DOM: false,
+  RETURN_DOM_FRAGMENT: false,
+  RETURN_TRUSTED_TYPE: false
+});
 
 /* typedef */
 /**
- * @typedef {object} ParsedURL - object with additional props based on URL API
- * @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] - is base64 encoded
- * @property {string} [data.data] - data part of the data URL
- * @property {string} [href] - sanitized URL input
- * @property {string} [origin] - scheme, domain and port of the sanitized URL
- * @property {string} [protocol] - protocol scheme of the sanitized URL
- * @property {string} [username] - username specified before the domain name
- * @property {string} [password] - password specified before the domain name
- * @property {string} [host] - domain and port of the sanitized URL
- * @property {string} [hostname] - domain of the sanitized URL
- * @property {string} [port] - port number of the sanitized URL
- * @property {string} [pathname] - path of the sanitized URL
- * @property {string} [search] - query string of the sanitized URL
- * @property {string} [hash] - fragment identifier of the sanitized URL
+ * The parsed result of a data URL.
+ * @typedef {object} InspectedDataURL
+ * @property {string} mime - The MIME type of the data.
+ * @property {boolean} base64 - Indicates whether the data is base64-encoded.
+ * @property {string} data - The actual data part of the data URL.
+ */
+
+/**
+ * The result of an inspected URL, extending the standard URL API.
+ * The properties except for input and valid are omitted from the object for invalid URLs.
+ * @typedef {object} InspectedURLResult
+ * @property {string} input - The original URL input.
+ * @property {boolean} valid - Indicates whether the URI is valid.
+ * @property {InspectedDataURL | null} [data] - The parsed result of a data URL. Null if not a data URL.
+ * @property {string} [href] - The sanitized URL input.
+ * @property {string} [origin] - The scheme, domain, and port.
+ * @property {string} [protocol] - The protocol scheme.
+ * @property {string} [username] - The specified username.
+ * @property {string} [password] - The specified password.
+ * @property {string} [host] - The domain and port.
+ * @property {string} [hostname] - The domain.
+ * @property {string} [port] - The port number.
+ * @property {string} [pathname] - The path.
+ * @property {string} [search] - The query string.
+ * @property {string} [hash] - The fragment identifier.
  */
 
 /**
  * Internal debug logger.
- * @param {boolean} isDebug - Debug flag.
- * @param {string} message - Output message.
- * @param {Error} [error] - Caught error object.
+ * @param {boolean} isDebug - Flag to enable or disable debug output.
+ * @param {string} message - The message to output.
+ * @param {Error} [error] - The caught error object, if any.
+ * @returns {void}
  */
 export const logDebug = (isDebug, message, error) => {
   if (isDebug) {
@@ -53,180 +82,181 @@ export const logDebug = (isDebug, message, error) => {
  */
 class URLSanitizer extends URISchemes {
   /* private fields */
-  #nest;
-  #recurse = new Set();
+  #allowedSchemes;
+
+  static #currentCtx = null;
+
+  /** @type {URLSanitizer | null} */
+  static #currentInstance = null;
 
   /**
-   * construct
+   * DOMPurify 'uponSanitizeAttribute' hook callback.
+   * @private
+   * @static
+   * @param {Node} node - The DOM node being sanitized.
+   * @param {object} e - The event object containing attribute details.
    */
+  static #uponSanitizeAttribute(node, e) {
+    if (!e.attrValue || !/^\s*data:/i.test(e.attrValue)) {
+      return;
+    }
+    /** @type {URLSanitizer | null} */
+    const sanitizer = URLSanitizer.#currentInstance;
+    const ctx = URLSanitizer.#currentCtx;
+    if (!ctx || !sanitizer) {
+      return;
+    }
+    let urlObj;
+    try {
+      urlObj = new URL(e.attrValue);
+    } catch {
+      return;
+    }
+    if (urlObj.protocol === 'data:') {
+      const originalUrl = e.attrValue;
+      if (!ctx.recurse) {
+        ctx.recurse = new Set();
+      }
+      if (ctx.recurse.has(originalUrl)) {
+        const msg = `Circular Data URL detected and skipped: ${originalUrl}`;
+        logDebug(ctx.debug, msg);
+        e.attrValue = '';
+        return;
+      }
+      ctx.nest++;
+      ctx.recurse.add(originalUrl);
+      try {
+        const sanitized = sanitizer.#process(originalUrl, {
+          allow: ['data'],
+          deny: [],
+          only: [],
+          allowRelative: false
+        }, ctx);
+        e.attrValue = sanitized || '';
+      } finally {
+        ctx.nest--;
+        ctx.recurse.delete(originalUrl);
+      }
+    }
+  }
+
+  static {
+    domPurify.setConfig(INTERNAL_PURIFY_CONFIG);
+    domPurify.addHook(
+      'uponSanitizeAttribute',
+      URLSanitizer.#uponSanitizeAttribute
+    );
+  }
+
   constructor() {
     super();
-    this.#nest = 0;
+    this.#allowedSchemes = new Set(super.get());
   }
 
   /**
-   * replace matched data URLs
-   * @param {string} data - data URL
-   * @returns {string} - replaced data URL
+   * Helper method to register schemes for the 'allow' or 'only' options.
+   * @private
+   * @param {string} item - The scheme to register.
+   * @param {string} listName - The name of the target option list.
+   * @param {Set<string>} allowedSchemes - The local set of allowed schemes.
+   * @param {Map<string, boolean>} schemeMap - The local map of schemes.
+   * @param {object} ctx - The context for state management.
+   * @returns {boolean} True if the scheme is successfully registered.
    */
-  replace(data) {
-    if (!isString(data)) {
-      throw new TypeError(`Expected String but got ${getType(data)}.`);
+  #registerScheme(item, listName, allowedSchemes, schemeMap, ctx) {
+    if (REG_SCRIPT_BLOB.test(item)) {
+      return false;
     }
-    let replacedData = data;
-    if (REG_DATA_URL.test(replacedData)) {
-      const matchedDataUrls = replacedData.matchAll(REG_DATA_URL_G);
-      const items = [...matchedDataUrls].reverse();
-      for (const item of items) {
-        let [dataUrl] = item;
-        if (REG_DATA_URL_B64.test(dataUrl)) {
-          [dataUrl] = REG_DATA_URL_B64.exec(dataUrl);
-        }
-        this.#nest++;
-        this.#recurse.add(dataUrl);
-        let parsedDataUrl;
-        try {
-          parsedDataUrl = this.sanitize(dataUrl, {
-            allow: ['data']
-          });
-        } finally {
-          this.#nest--;
-          this.#recurse.delete(dataUrl);
-        }
-        const { index } = item;
-        const [preDataUrl, postDataUrl] = [
-          replacedData.substring(0, index),
-          replacedData.substring(index + dataUrl.length)
-        ];
-        if (parsedDataUrl) {
-          replacedData = `${preDataUrl}${parsedDataUrl}${postDataUrl}`;
-        } else {
-          replacedData = `${preDataUrl}${postDataUrl}`;
-        }
-      }
+    const schemeParts = item.split('+');
+    const isScript = schemeParts.some(s => REG_SCRIPT.test(s));
+    if (isScript || !REG_SCHEME.test(item)) {
+      const msg = `Failed to add scheme '${item}' in '${listName}' list.`;
+      logDebug(ctx.debug, msg);
+      return false;
     }
-    return replacedData;
+    schemeMap.set(item, true);
+    allowedSchemes.add(item);
+    return true;
   }
 
   /**
-   * purify URL encoded DOM
-   * @param {string} dom - DOM string
-   * @returns {string} - purified DOM string
+   * Purifies a URL-encoded DOM string to prevent XSS.
+   * @private
+   * @param {string} dom - The URL-encoded DOM string.
+   * @param {object} ctx - The context for state management.
+   * @returns {string} The purified DOM string.
    */
-  purify(dom) {
-    if (!isString(dom)) {
-      throw new TypeError(`Expected String but got ${getType(dom)}.`);
-    }
+  #purify(dom, ctx) {
     let decodedDom = dom;
     try {
-      // prevent URIError caused by malformed percent-encoding
-      // e.g., a standalone '%'
       decodedDom = decodeURIComponent(dom);
-    } catch (e) {
+    } catch {
       // fall through
     }
-    let purifiedDom = domPurify.sanitize(decodedDom);
-    if (purifiedDom && REG_DATA_URL.test(purifiedDom)) {
-      purifiedDom = this.replace(purifiedDom);
+    const prevInstance = URLSanitizer.#currentInstance;
+    const prevCtx = URLSanitizer.#currentCtx;
+    URLSanitizer.#currentInstance = this;
+    URLSanitizer.#currentCtx = ctx;
+    let purifiedDom;
+    try {
+      purifiedDom = ctx.domPurify.sanitize(decodedDom);
+    } finally {
+      URLSanitizer.#currentInstance = prevInstance;
+      URLSanitizer.#currentCtx = prevCtx;
     }
-    purifiedDom = purifiedDom.replace(/(?:#|%23)$/, '')
-      .replace(/(?<!(?:#|%23).*)(?:\?|%3F)$/, '');
+    purifiedDom = trimTrailingEmptyQueryAndHash(purifiedDom);
     try {
-      // prevent URIError caused by lone surrogates
       return encodeURI(purifiedDom);
-    } catch (e) {
+    } catch {
       return purifiedDom;
     }
   }
 
   /**
-   * sanitize URL
-   * NOTE: `data` and `file` schemes must be explicitly allowed
-   * `blob` URLs should be converted to `data` URLs
-   * `javascript` and `vbscript` schemes can not be allowed
-   * @param {string} url - URL
-   * @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
-   * @param {boolean} [opt.allowRelative] - allow relative URLs
-   * @param {boolean} [opt.debug] - enable debug mode
-   * @returns {?string} - sanitized URL
+   * Internal recursive method for sanitization.
+   * @private
+   * @param {string} url - The URL string to sanitize.
+   * @param {object} rules - Normalized sanitization rules.
+   * @param {object} ctx - Internal context for state management.
+   * @returns {string|null} The sanitized URL, or null.
    */
-  sanitize(url, opt) {
-    if (this.#nest > HEX) {
+  #process(url, rules, ctx) {
+    if (ctx.nest > MAX_NEST) {
       throw new Error('Data URLs nested too deeply.');
     }
-    const {
-      allow, deny, only, allowRelative = false, debug = false
-    } = opt ?? {};
-    const schemeMap = new Map([
-      ['blob', false],
-      ['data', false],
-      ['file', false],
-      ['javascript', false],
-      ['vbscript', false]
-    ]);
-    const tempScheme = new Set();
+    const { allow, deny, only, allowRelative } = rules;
+    let allowedSchemes = this.#allowedSchemes;
     let restrictScheme = false;
-    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) {
+    const schemeMap = new Map(ctx.schemeMap);
+    if (only.length) {
+      allowedSchemes = new Set();
+      for (let item of only) {
         if (isString(item)) {
           item = item.trim();
-          if (!REG_SCRIPT_BLOB.test(item)) {
-            if (super.has(item)) {
-              schemeMap.set(item, true);
-            } else {
-              try {
-                super.add(item);
-              } catch (e) {
-                const msg = `Failed to add scheme '${item}' in 'only' list.`;
-                logDebug(debug, msg, e);
-              }
-              if (super.has(item)) {
-                schemeMap.set(item, true);
-                tempScheme.add(item);
-              }
-            }
-            if (!restrictScheme && schemeMap.has(item)) {
-              restrictScheme = schemeMap.get(item);
-            }
+          const registered =
+            this.#registerScheme(item, 'only', allowedSchemes, schemeMap, ctx);
+          if (registered && !restrictScheme) {
+            restrictScheme = true;
           }
         }
       }
     } else {
-      if (Array.isArray(allow) && allow.length) {
-        const items = Object.values(allow);
-        for (let item of items) {
+      if (allow.length) {
+        allowedSchemes = new Set(this.#allowedSchemes);
+        for (const item of allow) {
           if (isString(item)) {
-            item = item.trim();
-            if (!REG_SCRIPT_BLOB.test(item)) {
-              if (super.has(item)) {
-                schemeMap.set(item, true);
-              } else {
-                try {
-                  super.add(item);
-                } catch (e) {
-                  const msg = `Failed to add scheme '${item}' in 'allow' list.`;
-                  logDebug(debug, msg, e);
-                }
-                if (super.has(item)) {
-                  schemeMap.set(item, true);
-                  tempScheme.add(item);
-                }
-              }
-            }
+            this.#registerScheme(
+              item.trim(),
+              'allow',
+              allowedSchemes,
+              schemeMap,
+              ctx
+            );
           }
         }
       }
-      if (Array.isArray(deny) && deny.length) {
-        const items = Object.values(deny);
-        for (let item of items) {
+      if (deny.length) {
+        for (let item of deny) {
           if (isString(item)) {
             item = item.trim();
             if (item) {
@@ -237,17 +267,23 @@ class URLSanitizer extends URISchemes {
       }
     }
     let sanitizedUrl;
-    let isVerified = super.verify(url);
+    let isVerified = super.verify(url, allowedSchemes);
     let isRelative = false;
-    if (!isVerified && allowRelative) {
+    let relativeParsedPath = '';
+    if (!isVerified && allowRelative && !REG_VERIFY_RELATIVE.test(url)) {
       try {
-        const { hostname, protocol } = new URL(url, 'http://dummy.local');
-        if (protocol === 'http:' && hostname === 'dummy.local') {
+        const dummyUrl = new URL(url, 'http://dummy.local');
+        if (
+          dummyUrl.protocol === 'http:' &&
+          dummyUrl.hostname === 'dummy.local'
+        ) {
           isVerified = true;
           isRelative = true;
+          relativeParsedPath =
+            `${dummyUrl.pathname}${dummyUrl.search}${dummyUrl.hash}`;
         }
       } catch (e) {
-        logDebug(debug, 'Failed to parse relative URL.', e);
+        logDebug(ctx.debug, 'Failed to parse relative URL.', e);
       }
     }
     if (isVerified) {
@@ -276,7 +312,7 @@ class URLSanitizer extends URISchemes {
       }
       if (bool) {
         const isDataUrl = isRelative ? false : schemeParts.includes('data');
-        let urlToSanitize = isRelative ? url : href;
+        let urlToSanitize = isRelative ? relativeParsedPath : href;
         if (isDataUrl) {
           const [mediaType, ...dataParts] = pathname.split(',');
           const data = `${dataParts.join(',')}${search}${hash}`;
@@ -284,27 +320,27 @@ class URLSanitizer extends URISchemes {
           const isBase64 = mediaTypes[mediaTypes.length - 1] === 'base64';
           let parsedData = data;
           if (isBase64) {
-            parsedData = parseBase64(data);
+            try {
+              parsedData = parseBase64(data);
+            } catch (e) {
+              logDebug(ctx.debug, 'Failed to parse base64 data.', e);
+              urlToSanitize = '';
+            }
           }
           try {
             const decodedData = parseURLEncodedNumCharRef(parsedData).trim();
-            const { protocol: dataScheme } = new URL(decodedData);
+            const { protocol: dataScheme } =
+              new URL(decodedData, 'http://dummy.local');
             const dataSchemeParts = dataScheme.replace(/:$/, '').split('+');
             if (dataSchemeParts.some(s => REG_SCRIPT_BLOB.test(s))) {
               urlToSanitize = '';
             }
           } catch (e) {
             const msg = 'Failed to parse inner data URL protocol.';
-            logDebug(debug, msg, e);
-          }
-          const containsDataUrl = REG_DATA_URL.test(parsedData);
-          if (parsedData !== data || containsDataUrl) {
-            if (containsDataUrl) {
-              parsedData = this.replace(parsedData);
-            }
+            logDebug(ctx.debug, msg, e);
           }
           if (!mediaType || REG_MIME_DOM.test(mediaType)) {
-            parsedData = this.purify(parsedData);
+            parsedData = this.#purify(parsedData, ctx);
           }
           if (urlToSanitize && parsedData) {
             if (isBase64 && parsedData !== data) {
@@ -322,44 +358,89 @@ class URLSanitizer extends URISchemes {
             urlToSanitize.substring(0, index).replace(/[?&]$/, '');
         }
         if (urlToSanitize) {
-          sanitizedUrl =
-            urlToSanitize.replace(/%26/g, escapeURLEncodedHTMLChars);
+          sanitizedUrl = urlToSanitize;
         }
       }
-      if (tempScheme.size) {
-        tempScheme.forEach(item => {
-          super.remove(item);
-        });
-      }
     }
     return sanitizedUrl || null;
   }
 
   /**
-   * parse sanitized URL
-   * @param {string} url - URL
-   * @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 {ParsedURL} - result with additional props based on URL API
+   * Sanitizes the given URL.
+   * @param {string} url - The URL string to sanitize.
+   * @param {object} [opt] - Sanitization options.
+   * @param {string[]} [opt.allow] - An array of schemes to allow.
+   * @param {string[]} [opt.deny] - An array of schemes to deny.
+   * @param {string[]} [opt.only] - An array of specific schemes to allow.
+   * @param {boolean} [opt.allowRelative] - Flag to safely allow relative URLs.
+   * @param {boolean} [opt.debug] - Flag to enable debug mode.
+   * @param {number} [opt.maxBlobSize] - The maximum allowed blob size in bytes.
+   * @returns {string|null} The sanitized URL, or null.
    */
-  parse(url, opt) {
+  sanitize(url, opt) {
+    if (!url || !isString(url)) {
+      return null;
+    }
+    const hasRestrictiveRules = opt && (
+      (Array.isArray(opt.deny) && opt.deny.length > 0) ||
+      (Array.isArray(opt.only) && opt.only.length > 0) ||
+      opt.allowRelative
+    );
+    if (
+      !hasRestrictiveRules &&
+      (url.startsWith('https://') || url.startsWith('http://')) &&
+      !REG_TAG_QUOT.test(url) &&
+      !url.includes('data:')
+    ) {
+      try {
+        const { href } = new URL(url);
+        const res = href;
+        return res.replace(/%26/g, escapeURLEncodedHTMLChars);
+      } catch {
+        return null;
+      }
+    }
+    const rules = {
+      allow: Array.isArray(opt?.allow) ? opt.allow : [],
+      deny: Array.isArray(opt?.deny) ? opt.deny : [],
+      only: Array.isArray(opt?.only) ? opt.only : [],
+      allowRelative: !!opt?.allowRelative
+    };
+    const ctx = {
+      debug: !!opt?.debug,
+      domPurify,
+      nest: 0,
+      recurse: null,
+      schemeMap: new Map([
+        ['blob', false],
+        ['data', false],
+        ['file', false],
+        ['javascript', false],
+        ['vbscript', false]
+      ])
+    };
+    return this.#process(url, rules, ctx);
+  }
+
+  /**
+   * Inspects, parses, and sanitizes the given URL.
+   * NOTE: blob URLs are simply parsed, but neither decoded nor sanitized.
+   * @param {string} url - The URL string to parse.
+   * @param {object} [opt] - Sanitization options.
+   * @returns {InspectedURLResult} The object containing parsed result.
+   */
+  inspect(url, opt) {
     if (!isString(url)) {
       throw new TypeError(`Expected String but got ${getType(url)}.`);
     }
-    const parsedUrl = new Map([
-      ['input', url]
-    ]);
+    const parsedUrl = new Map([['input', url]]);
     let sanitizedUrl;
     if (this.verify(url)) {
       const { protocol } = new URL(url);
       if (protocol === 'blob:') {
         sanitizedUrl = url;
       } else {
-        sanitizedUrl = this.sanitize(url, opt ?? {
-          allow: ['data', 'file']
-        });
+        sanitizedUrl = this.sanitize(url, opt ?? { allow: ['data', 'file'] });
       }
     }
     if (sanitizedUrl) {
@@ -371,7 +452,7 @@ class URLSanitizer extends URISchemes {
       if (isDataUrl) {
         const dataUrl = new Map();
         const [mediaType, ...dataParts] = pathname.split(',');
-        const data = `${dataParts.join(',')}`;
+        const data = `${dataParts.join(',')}${urlObj.search}${urlObj.hash}`;
         const mediaTypes = mediaType.split(';');
         const isBase64 = mediaTypes[mediaTypes.length - 1] === 'base64';
         if (isBase64) {
@@ -384,7 +465,7 @@ class URLSanitizer extends URISchemes {
       } else {
         parsedUrl.set('data', null);
       }
-      for (const key in urlObj) {
+      for (const key of URL_PROPS) {
         const value = urlObj[key];
         if (isString(value)) {
           parsedUrl.set(key, value);
@@ -397,31 +478,86 @@ class URLSanitizer extends URISchemes {
   }
 
   /**
-   * reset sanitizer
+   * Gets the list of registered URI schemes.
+   * @returns {string[]} An array of registered schemes.
+   */
+  get() {
+    return [...this.#allowedSchemes];
+  }
+
+  /**
+   * Checks if the specified scheme is currently registered.
+   * @param {string} scheme - The target scheme.
+   * @returns {boolean} True if the scheme is registered.
+   */
+  has(scheme) {
+    return this.#allowedSchemes.has(scheme);
+  }
+
+  /**
+   * Adds a new scheme to the allowed list.
+   * @param {string} scheme - The scheme to add.
+   * @returns {string[]} The updated array of registered schemes.
+   */
+  add(scheme) {
+    if (!isString(scheme)) {
+      throw new TypeError(`Expected String but got ${getType(scheme)}.`);
+    }
+    const schemeParts = scheme.split('+');
+    const isScript = schemeParts.some(s => REG_SCRIPT.test(s));
+    if (isScript || !REG_SCHEME.test(scheme)) {
+      throw new Error(`Invalid scheme: ${scheme}`);
+    }
+    this.#allowedSchemes.add(scheme);
+    return [...this.#allowedSchemes];
+  }
+
+  /**
+   * Removes a scheme from the allowed list.
+   * @param {string} scheme - The scheme to remove.
+   * @returns {boolean} True if the scheme was successfully removed.
+   */
+  remove(scheme) {
+    return this.#allowedSchemes.delete(scheme);
+  }
+
+  /**
+   * Resets the registered schemes back to the default initial list.
    * @returns {void}
    */
   reset() {
-    super.reset();
-    this.#nest = 0;
-    this.#recurse.clear();
+    this.#allowedSchemes = new Set(super.get());
+  }
+
+  /**
+   * Verifies if the given URI is valid and its scheme is allowed.
+   * @param {string} uri - The URI string to verify.
+   * @param {Set<string>} [schemes] - The set of allowed schemes.
+   * @returns {boolean} True if the URI is syntactically valid and permitted.
+   */
+  verify(uri, schemes = this.#allowedSchemes) {
+    return super.verify(uri, schemes);
   }
 }
 export { URLSanitizer };
 
-/* aliases and async wrappers */
 /* instance */
 const urlSanitizer = new URLSanitizer();
 
 /**
- * sanitize URL async
- * NOTE: `blob`, `data` and `file` schemes must be explicitly allowed
- * given a `blob` URL, returns a sanitized `data` URL
+ * Asynchronously sanitizes the given URL.
+ * NOTE: `blob`, `data`, and `file` schemes must be explicitly allowed.
+ * Given a `blob` URL, it securely converts and returns a sanitized `data` URL.
  * @param {string} url - URL
  * @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 {Promise.<?string>} - sanitized URL
+ * @param {string[]} [opt.allow] - The array of schemes to allow.
+ * @param {string[]} [opt.deny] - The array of schemes to deny.
+ * @param {string[]} [opt.only] - The array of specific schemes to allow.
+ * @param {boolean} [opt.allowRelative] - Allow relative URLs.
+ * @param {boolean} [opt.debug] - Enable debug mode.
+ * @param {boolean} [opt.revokeObjectURL] - Revokes the blob URL after sanitization.
+ * @param {number} [opt.maxBlobSize] - The maximum allowed blob size in bytes.
+ * @returns {Promise<string|null>} A promise resolving to the sanitized URL, or null.
  */
 export const sanitizeURL = async (url, opt = {
   allow: [],
@@ -429,6 +565,7 @@ export const sanitizeURL = async (url, opt = {
   only: [],
   allowRelative: false,
   debug: false,
+  revokeObjectURL: false,
   maxBlobSize: MAX_BLOB_SIZE
 }) => {
   const isDebug = !!opt?.debug;
@@ -459,23 +596,25 @@ export const sanitizeURL = async (url, opt = {
           logDebug(isDebug, msg, e);
         }
         if (data) {
-          if (Array.isArray(only)) {
-            if (!only.includes('data')) {
-              only.push('data');
-            }
-          } else if (Array.isArray(allow)) {
-            if (!allow.includes('data')) {
-              allow.push('data');
-            }
-            if (Array.isArray(deny) && deny.includes('data')) {
-              const i = deny.indexOf('data');
-              deny.splice(i, 1);
+          const options = { ...opt };
+          if (Array.isArray(opt.only)) {
+            options.only = opt.only.includes('data')
+              ? opt.only
+              : [...opt.only, 'data'];
+          } else if (Array.isArray(opt.allow)) {
+            options.allow = opt.allow.includes('data')
+              ? opt.allow
+              : [...opt.allow, 'data'];
+            if (Array.isArray(opt.deny)) {
+              options.deny = opt.deny.filter(scheme => scheme !== 'data');
             }
           }
-          res = urlSanitizer.sanitize(data, opt);
+          res = urlSanitizer.sanitize(data, options);
         }
       }
-      URL.revokeObjectURL(url);
+      if (opt?.revokeObjectURL) {
+        URL.revokeObjectURL(url);
+      }
     } else if (scheme || opt.allowRelative) {
       res = urlSanitizer.sanitize(url, opt);
     }
@@ -484,17 +623,28 @@ export const sanitizeURL = async (url, opt = {
 };
 
 /**
- * sanitize URL sync
- * NOTE: `data` and `file` schemes must be explicitly allowed
- * `blob` scheme returns `null`
+ * Synchronously sanitizes the given URL.
+ * NOTE: `data` and `file` schemes must be explicitly allowed.
+ * The `blob` scheme is not supported and will return `null`.
  * @param {string} url - URL
  * @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
+ * @param {string[]} [opt.allow] - The array of schemes to allow.
+ * @param {string[]} [opt.deny] - The array of schemes to deny.
+ * @param {string[]} [opt.only] - The array of specific schemes to allow.
+ * @param {boolean} [opt.allowRelative] - Allow relative URLs.
+ * @param {boolean} [opt.debug] - Enable debug mode.
+ * @param {boolean} [opt.revokeObjectURL] - Revokes the blob URL.
+ * @returns {string|null} The sanitized URL, or null if denied.
  */
-export const sanitizeURLSync = (url, opt) => {
+export const sanitizeURLSync = (url, opt = {
+  allow: [],
+  deny: [],
+  only: [],
+  allowRelative: false,
+  debug: false,
+  revokeObjectURL: false
+}) => {
+  const isDebug = !!opt?.debug;
   let res;
   if (url && isString(url)) {
     let scheme;
@@ -502,12 +652,15 @@ export const sanitizeURLSync = (url, opt) => {
       const { protocol } = new URL(url);
       scheme = protocol.replace(/:$/, '');
     } catch (e) {
-      const msg = `Failed to parse URL: ${url}`;
-      logDebug(opt?.debug, msg, e);
+      const msg = `Invalid URL input format: ${url}`;
+      logDebug(isDebug, msg, e);
     }
     if (scheme === 'blob') {
-      URL.revokeObjectURL(url);
-    } else if (scheme || opt?.allowRelative) {
+      if (opt?.revokeObjectURL) {
+        URL.revokeObjectURL(url);
+      }
+      return null;
+    } else if (scheme || opt.allowRelative) {
       res = urlSanitizer.sanitize(url, opt);
     }
   }
@@ -515,26 +668,40 @@ export const sanitizeURLSync = (url, opt) => {
 };
 
 /**
- * parse URL async
- * @param {string} url - URL
- * @returns {Promise.<ParsedURL>} - result
+ * Inspects, parses, and sanitizes the given URL asynchronously.
+ * @param {string} url - The URL string to inspect.
+ * @returns {Promise<InspectedURLResult>} A promise resolving to the inspected URL object.
  */
-export const parseURL = async url => {
-  const res = urlSanitizer.parse(url);
+export const inspectURL = async url => {
+  const res = urlSanitizer.inspect(url);
   return res;
 };
 
 /**
- * parse URL sync
- * @param {string} url - URL
- * @returns {ParsedURL} - result
+ * @deprecated Use inspectURL instead.
+ * @param {string} url - The URL string to inspect.
+ * @returns {Promise<InspectedURLResult>} A promise resolving to the inspected URL object.
+ */
+export const parseURL = url => inspectURL(url);
+
+/**
+ * Inspects, parses, and sanitizes the given URL synchronously.
+ * @param {string} url - The URL string to inspect.
+ * @returns {InspectedURLResult} The inspected URL object.
+ */
+export const inspectURLSync = url => urlSanitizer.inspect(url);
+
+/**
+ * @deprecated Use inspectURLSync instead.
+ * @param {string} url - The URL string to inspect.
+ * @returns {InspectedURLResult} The inspected URL object.
  */
-export const parseURLSync = url => urlSanitizer.parse(url);
+export const parseURLSync = url => inspectURLSync(url);
 
 /**
- * is URI async
- * @param {string} uri - URI
- * @returns {Promise.<boolean>} - result
+ * Asynchronously checks if the given string is a valid URI and is registered.
+ * @param {string} uri - The URI string to verify.
+ * @returns {Promise<boolean>} True if valid and registered, false otherwise.
  */
 export const isURI = async uri => {
   const res = urlSanitizer.verify(uri);
@@ -542,9 +709,9 @@ export const isURI = async uri => {
 };
 
 /**
- * is URI sync
- * @param {string} uri - URI
- * @returns {boolean} - result
+ * Synchronously checks if the given string is a valid URI and is registered.
+ * @param {string} uri - The URI string to verify.
+ * @returns {boolean} True if valid and registered, false otherwise.
  */
 export const isURISync = uri => urlSanitizer.verify(uri);