url-sanitizer 4.2.2 → 5.0.1

package/src/mjs/sanitizer.js

@@ -7,24 +7,34 @@ import { domPurify } from './dompurify.js';
 import { getType, isString } from './common.js';
 import {
   URISchemes,
-  convertBlobToDataURL,
   escapeURLEncodedHTMLChars,
+  extractDataUrlComponents,
+  getSchemeParts,
   parseBase64,
   parseURLEncodedNumCharRef,
-  trimTrailingEmptyQueryAndHash
+  trimTrailingEmptyQueryAndHash,
+  truncateURL
 } from './uri-util.js';
 
 /* constants */
-import { MAX_BLOB_SIZE, MAX_NEST } from './constant.js';
+import {
+  CHUNK_SIZE,
+  DECI,
+  MAX_BLOB_SIZE,
+  MAX_NEST,
+  MAX_URL_LENGTH
+} from './constant.js';
 import {
   REG_AMP_ENC,
   REG_MIME_DOM,
   REG_SCHEME,
   REG_SCRIPT,
-  REG_SCRIPT_BLOB,
+  REG_SCRIPT_OR_BLOB,
   REG_TAG_QUOT,
   REG_VERIFY_RELATIVE
 } from './regexp.js';
+const DUMMY_BASE = 'http://dummy.local';
+const IS_NODE = globalThis.process?.versions?.node !== undefined;
 const URL_PROPS = Object.freeze([
   'href',
   'origin',
@@ -38,10 +48,15 @@ const URL_PROPS = Object.freeze([
   'search',
   'hash'
 ]);
-const INTERNAL_PURIFY_CONFIG = Object.freeze({
-  RETURN_DOM: false,
-  RETURN_DOM_FRAGMENT: false,
-  RETURN_TRUSTED_TYPE: false
+const DEFAULT_OPTS = Object.freeze({
+  allow: Object.freeze([]),
+  deny: Object.freeze([]),
+  only: Object.freeze([]),
+  allowRelative: false,
+  debug: false,
+  revokeObjectURL: false,
+  maxBlobSize: MAX_BLOB_SIZE,
+  maxLength: MAX_URL_LENGTH
 });
 
 /* typedef */
@@ -58,7 +73,8 @@ const INTERNAL_PURIFY_CONFIG = Object.freeze({
  * The properties except for input and valid are omitted for invalid URLs.
  * @typedef {object} InspectedURLResult
  * @property {string} input - The original URL input.
- * @property {boolean} valid - Indicates whether the URI is valid.
+ * @property {boolean} valid - Indicates whether the URL passed sanitization rules.
+ * @property {boolean} [relative] - Indicates whether the input is a valid relative URL.
  * @property {string} [reason] - The reason why the URL is invalid.
  * @property {InspectedDataURL | null} [data] - The parsed result of a data URL. Null if not a data URL.
  * @property {string} [href] - The sanitized URL input.
@@ -76,99 +92,71 @@ const INTERNAL_PURIFY_CONFIG = Object.freeze({
 
 /**
  * Internal debug logger.
- * @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) {
-    console.warn(`[URLSanitizer Debug] ${message}`, error);
-  }
+export const logDebug = (message, error) => {
+  console.warn(`[URLSanitizer Debug] ${message}`, error);
 };
 
 /**
- * URL sanitizer
+ * Context manager for the sanitization process.
  */
-class URLSanitizer extends URISchemes {
-  /* private fields */
-  #allowedSchemes;
-
+export class SanitizeContext {
   /**
-   * NOTE: Global Context Pattern for DOMPurify Hooks
-   * - DOMPurify hooks (e.g., 'uponSanitizeAttribute') are registered globally
-   * and do not accept custom arguments (like `this` or `ctx`).
-   * To pass the current sanitization context into the hook, we temporarily
-   * store it in static fields (#currentInstance and #currentCtx).
-   * - This is entirely safe and immune to race conditions because JavaScript
-   * runs on a single thread and DOMPurify's sanitize() is synchronous.
-   * The context is safely restored via try/finally block in #purify() even
-   * during recursive calls.
+   * @param {object} opt - Sanitization options.
+   * @param {object} domPurifyInstance - The DOMPurify instance.
    */
-  /** @type {URLSanitizer | null} */
-  static #currentInstance = null;
-  static #currentCtx = null;
+  constructor(opt, domPurifyInstance) {
+    this.debug = !!opt?.debug;
+    this.domPurify = domPurifyInstance;
+    this.nest = 0;
+    this.recurse = new Set();
+    this.schemeMap = new Map([
+      ['blob', false],
+      ['data', false],
+      ['file', false],
+      ['javascript', false],
+      ['vbscript', false]
+    ]);
+  }
 
   /**
-   * DOMPurify 'uponSanitizeAttribute' hook callback.
-   * @private
-   * @static
-   * @param {Node} node - The DOM node being sanitized.
-   * @param {object} evt - The event object containing attribute details.
+   * Enters a new level of nested URL sanitization.
+   * Tracks the URL to prevent circular references.
+   * @param {string} url - The URL being processed.
+   * @returns {boolean} True if it is safe to proceed, false if circular reference detected.
    */
-  static #uponSanitizeAttribute(node, evt) {
-    if (!evt.attrValue || !/^\s*data:/i.test(evt.attrValue)) {
-      return;
-    }
-    /** @type {URLSanitizer | null} */
-    const sanitizer = URLSanitizer.#currentInstance;
-    const ctx = URLSanitizer.#currentCtx;
-    if (!sanitizer || !ctx) {
-      return;
-    }
-    const urlObj = URL.parse(evt.attrValue);
-    if (!urlObj) {
-      return;
-    }
-    if (urlObj.protocol === 'data:') {
-      const originalUrl = evt.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);
-        evt.attrValue = '';
-        return;
-      }
-      ctx.nest++;
-      ctx.recurse.add(originalUrl);
-      try {
-        const sanitized = sanitizer.#process(
-          originalUrl,
-          {
-            allow: ['data'],
-            deny: [],
-            only: [],
-            allowRelative: false
-          },
-          ctx
-        );
-        evt.attrValue = sanitized || '';
-      } finally {
-        ctx.nest--;
-        ctx.recurse.delete(originalUrl);
+  enter(url) {
+    if (this.recurse.has(url)) {
+      if (this.debug) {
+        logDebug(`Circular Data URL detected and skipped: ${truncateURL(url)}`);
       }
+      return false;
     }
+    this.nest++;
+    this.recurse.add(url);
+    return true;
   }
 
-  static {
-    domPurify.setConfig(INTERNAL_PURIFY_CONFIG);
-    domPurify.addHook(
-      'uponSanitizeAttribute',
-      URLSanitizer.#uponSanitizeAttribute
-    );
+  /**
+   * Leaves the current level of nested URL sanitization.
+   * Cleans up the tracking state after processing the URL.
+   * @param {string} url - The URL that finished processing.
+   */
+  leave(url) {
+    this.nest--;
+    this.recurse.delete(url);
   }
+}
+
+/**
+ * URL sanitizer
+ */
+export class URLSanitizer extends URISchemes {
+  /* private fields */
+  #allowedSchemes;
 
   constructor() {
     super();
@@ -176,79 +164,61 @@ class URLSanitizer extends URISchemes {
   }
 
   /**
-   * Helper method to register schemes for the 'allow' or 'only' options.
+   * Executes the core sanitization logic.
    * @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.
-   */
-  #registerScheme(item, listName, allowedSchemes, schemeMap, ctx) {
-    if (REG_SCRIPT_BLOB.test(item)) {
-      return false;
-    }
-    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;
-    }
-    schemeMap.set(item, true);
-    allowedSchemes.add(item);
-    return true;
-  }
-
-  /**
-   * 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.
+   * @param {string} url - The URL string to sanitize.
+   * @param {object} opt - Sanitization options.
+   * @returns {string|null} The sanitized URL, or null.
    */
-  #purify(dom, ctx) {
-    let decodedDom = dom;
-    try {
-      decodedDom = decodeURIComponent(dom);
-    } catch {
-      // fall through
+  #executeSanitize(url, opt) {
+    if (!url || !isString(url)) {
+      return null;
     }
-    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;
+    const { allow, allowRelative, deny, maxLength, only } = opt;
+    if (Number.isInteger(maxLength) && url.length > maxLength) {
+      const msg = `URL length ${url.length} exceeds max length ${maxLength}.`;
+      throw new RangeError(msg);
     }
-    purifiedDom = trimTrailingEmptyQueryAndHash(purifiedDom);
-    try {
-      return encodeURI(purifiedDom);
-    } catch {
-      return purifiedDom;
+    const hasRestrictiveRules =
+      (Array.isArray(deny) && deny.length) ||
+      (Array.isArray(only) && only.length) ||
+      allowRelative;
+    // Early return for standard HTTP/HTTPS URLs without restrictive rules.
+    if (
+      !hasRestrictiveRules &&
+      (url.startsWith('https://') || url.startsWith('http://')) &&
+      !REG_TAG_QUOT.test(url) &&
+      !url.includes('data:')
+    ) {
+      const urlObj = this.parse(url);
+      if (urlObj) {
+        return urlObj.href.replace(/%26/g, escapeURLEncodedHTMLChars);
+      }
+      return null;
     }
+    const ctx = new SanitizeContext(opt, domPurify);
+    return this.#process(url, { allow, allowRelative, deny, only }, ctx);
   }
 
   /**
    * 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.
+   * @param {object} rules - The sanitization rules.
+   * @param {string[]} rules.allow - Allowed schemes.
+   * @param {boolean} rules.allowRelative - Allow relative URLs.
+   * @param {string[]} rules.deny - Denied schemes.
+   * @param {string[]} rules.only - Exclusively allowed schemes.
+   * @param {SanitizeContext} ctx - Internal context for state.
    * @returns {string|null} The sanitized URL, or null.
    */
-  #process(url, rules, ctx) {
+  #process(url, { allow, allowRelative, deny, only }, ctx) {
     if (ctx.nest > MAX_NEST) {
       throw new Error('Data URLs nested too deeply.');
     }
     // Resolve allowed/denied schemes
     const { allowedSchemes, restrictScheme, schemeMap } =
-      this.#resolveSchemeRules(rules, ctx);
+      this.#resolveSchemeRules({ allow, deny, only }, ctx);
     // Parse and verify the URL
     const {
       isDataUrl,
@@ -258,7 +228,7 @@ class URLSanitizer extends URISchemes {
       schemeParts,
       urlObj,
       urlToSanitize
-    } = this.#parseAndVerifyURL(url, rules.allowRelative, allowedSchemes, ctx);
+    } = this.#parseAndVerifyURL(url, allowRelative, allowedSchemes, ctx);
     if (!isVerified) {
       return null;
     }
@@ -288,50 +258,36 @@ class URLSanitizer extends URISchemes {
    * @param {string[]} rules.allow - Allowed schemes.
    * @param {string[]} rules.deny - Denied schemes.
    * @param {string[]} rules.only - Exclusively allowed schemes.
-   * @param {object} ctx - Context for state management.
+   * @param {SanitizeContext} ctx - Context for state management.
    * @returns {object} Resolved scheme objects and flags.
    */
   #resolveSchemeRules({ allow, deny, only }, ctx) {
     let allowedSchemes = this.#allowedSchemes;
     let restrictScheme = false;
     const schemeMap = new Map(ctx.schemeMap);
-    if (only.length) {
+    if (Array.isArray(only) && only.length) {
       allowedSchemes = new Set();
+      restrictScheme = true;
       for (const item of only) {
         if (isString(item)) {
-          const registered = this.#registerScheme(
-            item.trim(),
-            'only',
-            allowedSchemes,
-            schemeMap,
-            ctx
-          );
-          if (registered && !restrictScheme) {
-            restrictScheme = true;
-          }
+          this.#registerScheme(item, 'only', allowedSchemes, schemeMap, ctx);
         }
       }
     } else {
-      if (allow.length) {
+      if (Array.isArray(allow) && allow.length) {
         allowedSchemes = new Set(this.#allowedSchemes);
         for (const item of allow) {
           if (isString(item)) {
-            this.#registerScheme(
-              item.trim(),
-              'allow',
-              allowedSchemes,
-              schemeMap,
-              ctx
-            );
+            this.#registerScheme(item, 'allow', allowedSchemes, schemeMap, ctx);
           }
         }
       }
-      if (deny.length) {
-        for (let item of deny) {
+      if (Array.isArray(deny) && deny.length) {
+        for (const item of deny) {
           if (isString(item)) {
-            item = item.trim();
-            if (item) {
-              schemeMap.set(item, false);
+            const normalized = this.normalize(item, true);
+            if (normalized) {
+              schemeMap.set(normalized, false);
             }
           }
         }
@@ -340,36 +296,67 @@ class URLSanitizer extends URISchemes {
     return { allowedSchemes, restrictScheme, schemeMap };
   }
 
+  /**
+   * 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 {SanitizeContext} ctx - The context for state management.
+   * @returns {boolean} True if the scheme is successfully registered.
+   */
+  #registerScheme(item, listName, allowedSchemes, schemeMap, ctx) {
+    const normalizedScheme = this.normalize(item, true);
+    if (!this.#isValidScheme(normalizedScheme)) {
+      return false;
+    }
+    schemeMap.set(normalizedScheme, true);
+    allowedSchemes.add(normalizedScheme);
+    return true;
+  }
+
+  /**
+   * Validates if a normalized URI scheme is syntactically correct.
+   * @private
+   * @param {string} normalizedScheme - The normalized URI scheme to validate.
+   * @returns {boolean} True if the scheme satisfies the syntax and security requirements.
+   */
+  #isValidScheme(normalizedScheme) {
+    if (REG_SCRIPT_OR_BLOB.test(normalizedScheme)) {
+      return false;
+    }
+    const schemeParts = normalizedScheme.split('+');
+    const isScript = schemeParts.some(s => REG_SCRIPT.test(s));
+    return !isScript && REG_SCHEME.test(normalizedScheme);
+  }
+
   /**
    * Parses and verifies absolute and relative URLs.
    * @private
    * @param {string} url - The URL to parse.
-   * @param {boolean} allowRelative - If relative URLs are OK.
+   * @param {boolean} allowRelative - Allow relative URLs.
    * @param {Set<string>} allowedSchemes - Permitted schemes.
-   * @param {object} ctx - Context for logging and state.
+   * @param {SanitizeContext} ctx - Context for logging and state.
    * @returns {object} Parsed URL properties and flags.
    */
   #parseAndVerifyURL(url, allowRelative, allowedSchemes, ctx) {
-    let isVerified = super.verify(url, allowedSchemes);
+    const urlObj = this.parse(url);
+    let isVerified = this.verifyParsed(urlObj, allowedSchemes);
     let isRelative = false;
-    let relativeParsedPath = '';
+    let relativePath = '';
     // Handle Relative URLs
     if (!isVerified && allowRelative && !REG_VERIFY_RELATIVE.test(url)) {
-      const normUrl = url.normalize('NFKC');
-      const dummyUrl = URL.parse(url, 'http://dummy.local');
-      const dummyUrlNormalized = URL.parse(normUrl, 'http://dummy.local');
-      if (dummyUrl && dummyUrlNormalized) {
+      const dummyUrl = this.parse(url, DUMMY_BASE);
+      if (dummyUrl) {
         if (
           dummyUrl.protocol === 'http:' &&
-          dummyUrl.hostname === 'dummy.local' &&
-          dummyUrlNormalized.protocol === 'http:'
+          dummyUrl.hostname === 'dummy.local'
         ) {
           isVerified = true;
           isRelative = true;
-          relativeParsedPath = `${dummyUrl.pathname}${dummyUrl.search}${dummyUrl.hash}`;
+          relativePath = `${dummyUrl.pathname}${dummyUrl.search}${dummyUrl.hash}`;
         }
-      } else {
-        logDebug(ctx.debug, 'Failed to parse relative URL.');
       }
     }
     if (!isVerified) {
@@ -383,11 +370,10 @@ class URLSanitizer extends URISchemes {
         isDataUrl: false,
         scheme: '',
         schemeParts: [],
-        urlToSanitize: relativeParsedPath
+        urlToSanitize: relativePath
       };
     }
-    const urlObj = URL.parse(url);
-    const scheme = urlObj.protocol.replace(/:$/, '').normalize('NFKC');
+    const scheme = urlObj.protocol.replace(/:$/, '');
     const schemeParts = scheme.split('+');
     return {
       isRelative,
@@ -395,7 +381,7 @@ class URLSanitizer extends URISchemes {
       scheme,
       schemeParts,
       urlObj,
-      isDataUrl: schemeParts.includes('data'),
+      isDataUrl: scheme === 'data',
       urlToSanitize: urlObj.href
     };
   }
@@ -415,7 +401,7 @@ class URLSanitizer extends URISchemes {
       return true;
     }
     if (restrictScheme) {
-      return schemeParts.every(s => schemeMap.get(s));
+      return schemeMap.has(scheme) || schemeParts.every(s => schemeMap.get(s));
     }
     for (const [key, value] of schemeMap.entries()) {
       const bool =
@@ -432,39 +418,41 @@ class URLSanitizer extends URISchemes {
    * @private
    * @param {object} urlObj - The URL object.
    * @param {string} scheme - The URL scheme.
-   * @param {object} ctx - Context for DOMPurify sanitization.
+   * @param {SanitizeContext} ctx - Context for DOMPurify sanitization.
    * @returns {string|null} Sanitized data URL or null.
    */
   #sanitizeDataURL(urlObj, scheme, ctx) {
-    const [mediaType, ...dataParts] = urlObj.pathname.split(',');
-    const data = `${dataParts.join(',')}${urlObj.search}${urlObj.hash}`;
-    const mediaTypes = mediaType.split(';');
-    const isBase64 = mediaTypes[mediaTypes.length - 1] === 'base64';
+    const { mediaType, mediaTypes, data, isBase64 } = extractDataUrlComponents(
+      urlObj.pathname,
+      urlObj.search,
+      urlObj.hash
+    );
     let parsedData = data;
     if (isBase64) {
       try {
         parsedData = parseBase64(data);
       } catch (e) {
-        logDebug(ctx.debug, 'Failed to parse base64 data.', e);
+        if (ctx.debug) {
+          logDebug('Failed to parse base64 data.', e);
+        }
         return null;
       }
     }
     try {
       const decodedData = parseURLEncodedNumCharRef(parsedData).trim();
-      const normalizedData = decodedData.normalize('NFKC');
-      const dummy = 'http://dummy.local';
-      const parsedUrl = URL.parse(normalizedData, dummy);
+      const parsedUrl = this.parse(decodedData, DUMMY_BASE);
       if (!parsedUrl) {
-        logDebug(ctx.debug, 'Failed to parse inner data URL protocol.');
         return null;
       }
       const dataScheme = parsedUrl.protocol;
-      const dataSchemeParts = dataScheme.replace(/:$/, '').split('+');
-      if (dataSchemeParts.some(s => REG_SCRIPT_BLOB.test(s))) {
+      const dataSchemeParts = getSchemeParts(dataScheme);
+      if (dataSchemeParts.some(s => REG_SCRIPT_OR_BLOB.test(s))) {
         return null;
       }
     } catch (e) {
-      logDebug(ctx.debug, 'Failed to parse inner data URL protocol.', e);
+      if (ctx.debug) {
+        logDebug('Failed to parse inner data URL protocol.', e);
+      }
       return null;
     }
     if (!mediaType || REG_MIME_DOM.test(mediaType)) {
@@ -479,6 +467,69 @@ class URLSanitizer extends URISchemes {
     return null;
   }
 
+  /**
+   * Purifies a URL-encoded DOM string to prevent XSS.
+   * @private
+   * @param {string} dom - The URL-encoded DOM string.
+   * @param {SanitizeContext} ctx - The context for state management.
+   * @returns {string} The purified DOM string.
+   */
+  #purify(dom, ctx) {
+    let decodedDom = dom;
+    try {
+      decodedDom = decodeURIComponent(dom);
+    } catch {
+      // fall through
+    }
+    let purifiedDom;
+    const tempHook = (node, evt) =>
+      this.#handleSanitizeAttribute(node, evt, ctx);
+    ctx.domPurify.addHook('uponSanitizeAttribute', tempHook);
+    try {
+      purifiedDom = ctx.domPurify.sanitize(decodedDom);
+    } finally {
+      ctx.domPurify.removeHook('uponSanitizeAttribute');
+    }
+    purifiedDom = trimTrailingEmptyQueryAndHash(purifiedDom);
+    try {
+      return encodeURI(purifiedDom);
+    } catch {
+      return purifiedDom;
+    }
+  }
+
+  /**
+   * Internal handler for the DOMPurify hook.
+   * @private
+   * @param {Node} node - The DOM node.
+   * @param {object} evt - The event object.
+   * @param {SanitizeContext} ctx - The sanitization context.
+   */
+  #handleSanitizeAttribute(node, evt, ctx) {
+    if (!evt.attrValue || !/^\s*data:/i.test(evt.attrValue)) {
+      return;
+    }
+    const urlObj = this.parse(evt.attrValue);
+    if (!urlObj || urlObj.protocol !== 'data:') {
+      return;
+    }
+    const originalUrl = evt.attrValue;
+    if (!ctx.enter(originalUrl)) {
+      evt.attrValue = '';
+      return;
+    }
+    try {
+      const sanitized = this.#process(
+        originalUrl,
+        { allow: ['data'], deny: [], only: [], allowRelative: false },
+        ctx
+      );
+      evt.attrValue = sanitized || '';
+    } finally {
+      ctx.leave(originalUrl);
+    }
+  }
+
   /**
    * Applies regex cleanups to standard non-data URLs.
    * Strips out trailing queries or problematic characters.
@@ -488,13 +539,12 @@ class URLSanitizer extends URISchemes {
    */
   #sanitizeStandardURL(urlToSanitize) {
     let sanitized = urlToSanitize;
-    if (REG_TAG_QUOT.test(sanitized)) {
-      const { index } = REG_TAG_QUOT.exec(sanitized);
-      sanitized = sanitized.substring(0, index).replace(/[?&]$/, '');
-    }
-    if (REG_AMP_ENC.test(sanitized)) {
-      const { index } = REG_AMP_ENC.exec(sanitized);
-      sanitized = sanitized.substring(0, index).replace(/[?&]$/, '');
+    const patterns = [REG_TAG_QUOT, REG_AMP_ENC];
+    for (const pattern of patterns) {
+      const match = pattern.exec(sanitized);
+      if (match) {
+        sanitized = sanitized.substring(0, match.index).replace(/[?&]$/, '');
+      }
     }
     return sanitized;
   }
@@ -506,136 +556,94 @@ class URLSanitizer extends URISchemes {
    * @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.allowRelative] - Allow relative URLs.
    * @param {boolean} [opt.debug] - Flag to enable debug mode.
    * @param {number} [opt.maxBlobSize] - The maximum allowed blob size in bytes.
    * @param {number} [opt.maxLength] - The maximum allowed URL length.
    * @returns {string|null} The sanitized URL, or null.
    */
-  sanitize(url, opt) {
-    if (!url || !isString(url)) {
-      return null;
-    }
-    const maxLength =
-      Number.isInteger(opt?.maxLength) && opt.maxLength ? opt.maxLength : 0;
-    if (maxLength && url.length > maxLength) {
-      const msg = `URL length ${url.length} exceeds maxLength ${maxLength}.`;
-      throw new RangeError(msg);
-    }
-    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:')
-    ) {
-      const parsedUrl = URL.parse(url);
-      if (parsedUrl) {
-        return parsedUrl.href.replace(/%26/g, escapeURLEncodedHTMLChars);
-      } else {
-        logDebug(opt?.debug, `Failed to parse URL.`);
-        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
+  sanitize(url, opt = {}) {
+    const options = {
+      ...DEFAULT_OPTS,
+      ...opt
     };
-    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);
+    return this.#executeSanitize(url, options);
   }
 
   /**
    * 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 result of an inspected URL.
    */
-  inspect(url, opt) {
-    if (!isString(url)) {
-      throw new TypeError(`Expected String but got ${getType(url)}.`);
-    }
+  inspect(url) {
     const inspectedURL = {
       input: url,
       valid: false
     };
+    if (!isString(url)) {
+      inspectedURL.reason = `Invalid URL input: ${truncateURL(url)}`;
+      return inspectedURL;
+    }
+    if (url === '') {
+      inspectedURL.reason = 'Invalid URL input: (empty string)';
+      return inspectedURL;
+    }
     let sanitizedUrl;
     let invalidReason = null;
-    const maxLength =
-      Number.isInteger(opt?.maxLength) && opt.maxLength ? opt.maxLength : 0;
-    const urlLength = url.length;
-    if (maxLength && urlLength > maxLength) {
-      invalidReason = `URL length ${urlLength} exceeds maxLength ${maxLength}.`;
-    } else if (this.verify(url)) {
-      const { protocol } = new URL(url);
-      if (protocol === 'blob:') {
-        sanitizedUrl = url;
-      } else {
-        try {
-          sanitizedUrl = this.sanitize(url, opt ?? { allow: ['data'] });
-          if (!sanitizedUrl) {
-            invalidReason =
-              'Sanitization failed (blocked by allowed schemes or rules).';
-          }
-        } catch (e) {
-          invalidReason = e.message;
-        }
+    try {
+      sanitizedUrl = this.#executeSanitize(url, {
+        ...DEFAULT_OPTS,
+        allow: ['data'],
+        allowRelative: true
+      });
+      if (!sanitizedUrl) {
+        invalidReason =
+          'Sanitization failed (blocked by allowed schemes or rules).';
       }
-    } else {
-      invalidReason = 'Invalid URI syntax or scheme is not registered.';
+    } catch (e) {
+      invalidReason = e.message;
     }
     if (sanitizedUrl) {
-      const urlObj = new URL(sanitizedUrl);
-      const { pathname, protocol } = urlObj;
-      const schemeParts = protocol.replace(/:$/, '').split('+');
-      const isDataUrl = schemeParts.includes('data');
+      // Reparse the sanitized string to safely extract updated properties.
+      const urlObj = this.parse(sanitizedUrl);
       inspectedURL.valid = true;
-      if (isDataUrl) {
-        const [mediaType, ...dataParts] = pathname.split(',');
-        const data = `${dataParts.join(',')}${urlObj.search}${urlObj.hash}`;
-        const mediaTypes = mediaType.split(';');
-        const isBase64 = mediaTypes[mediaTypes.length - 1] === 'base64';
-        if (isBase64) {
-          mediaTypes.pop();
+      if (urlObj) {
+        const schemeParts = getSchemeParts(urlObj.protocol);
+        const isDataUrl = schemeParts.includes('data');
+        if (isDataUrl) {
+          const { mediaTypes, data, isBase64 } = extractDataUrlComponents(
+            urlObj.pathname,
+            urlObj.search,
+            urlObj.hash
+          );
+          if (isBase64) {
+            mediaTypes.pop();
+          }
+          inspectedURL.data = {
+            mime: mediaTypes.join(';'),
+            base64: isBase64,
+            data
+          };
+        } else {
+          inspectedURL.data = null;
         }
-        inspectedURL.data = {
-          mime: mediaTypes.join(';'),
-          base64: isBase64,
-          data
-        };
-      } else {
-        inspectedURL.data = null;
-      }
-      for (const key of URL_PROPS) {
-        const value = urlObj[key];
-        if (isString(value)) {
-          inspectedURL[key] = value;
+        for (const key of URL_PROPS) {
+          const value = urlObj[key];
+          if (isString(value)) {
+            inspectedURL[key] = value;
+          }
         }
+      } else {
+        // Fallback for the valid relative URL without a base URL.
+        inspectedURL.valid = false;
+        inspectedURL.relative = true;
+        inspectedURL.href = sanitizedUrl;
+        inspectedURL.reason =
+          'Invalid as an absolute URL, but valid as a relative URL.';
       }
     } else {
       inspectedURL.valid = false;
-      if (invalidReason) {
-        inspectedURL.reason = invalidReason;
-      }
+      inspectedURL.reason = invalidReason;
     }
     return inspectedURL;
   }
@@ -654,10 +662,11 @@ class URLSanitizer extends URISchemes {
    * @returns {boolean} True if the scheme is registered.
    */
   has(scheme) {
-    if (!isString(scheme)) {
-      return false;
+    const normalizedScheme = this.normalize(scheme, true);
+    if (normalizedScheme) {
+      return this.#allowedSchemes.has(normalizedScheme);
     }
-    return this.#allowedSchemes.has(scheme.trim().toLowerCase());
+    return false;
   }
 
   /**
@@ -666,18 +675,14 @@ class URLSanitizer extends URISchemes {
    * @returns {string[]} The updated array of registered schemes.
    */
   add(scheme) {
-    let loweredScheme;
-    if (isString(scheme)) {
-      loweredScheme = scheme.trim().toLowerCase();
-    } else {
+    if (!isString(scheme)) {
       throw new TypeError(`Expected String but got ${getType(scheme)}.`);
     }
-    const schemeParts = loweredScheme.split('+');
-    const isScript = schemeParts.some(s => REG_SCRIPT.test(s));
-    if (isScript || !REG_SCHEME.test(loweredScheme)) {
+    const normalizedScheme = this.normalize(scheme, true);
+    if (!this.#isValidScheme(normalizedScheme)) {
       throw new Error(`Invalid scheme: ${scheme}`);
     }
-    this.#allowedSchemes.add(loweredScheme);
+    this.#allowedSchemes.add(normalizedScheme);
     return [...this.#allowedSchemes];
   }
 
@@ -690,7 +695,8 @@ class URLSanitizer extends URISchemes {
     if (!isString(scheme)) {
       return false;
     }
-    return this.#allowedSchemes.delete(scheme.trim().toLowerCase());
+    const normalizedScheme = this.normalize(scheme, true);
+    return this.#allowedSchemes.delete(normalizedScheme);
   }
 
   /**
@@ -707,13 +713,159 @@ class URLSanitizer extends URISchemes {
    * @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);
+  verify(uri, schemes) {
+    return super.verify(uri, schemes ?? this.#allowedSchemes);
   }
 }
-export { URLSanitizer };
 
-/* instance */
+/* blob handlers */
+/**
+ * Converts Blob to data URL from Buffer.
+ * @private
+ * @param {Blob} blob - The target Blob object.
+ * @returns {Promise<string|null>} A promise resolving to the data URL, or null.
+ */
+const convertFromBuffer = async blob => {
+  const mimeStr = blob.type ? `${blob.type};base64` : 'base64';
+  const buffer = await blob.arrayBuffer();
+  const base64 = globalThis.Buffer.from(buffer).toString('base64');
+  return `data:${mimeStr},${base64}`;
+};
+
+/**
+ * Converts Blob to data URL from FileReader.
+ * @private
+ * @param {Blob} blob - The target Blob object.
+ * @returns {Promise<string|null>} A promise resolving to the data URL, or null.
+ */
+const convertFromFileReader = blob =>
+  new Promise((resolve, reject) => {
+    const reader = new globalThis.FileReader();
+    reader.addEventListener('error', () => {
+      const error =
+        reader.error ||
+        new DOMException(
+          'Failed to read Blob via FileReader.',
+          'NotReadableError'
+        );
+      reject(error);
+    });
+    reader.addEventListener('abort', () => resolve(null));
+    reader.addEventListener('load', () => resolve(reader.result));
+    reader.readAsDataURL(blob);
+  });
+
+/**
+ * Converts Blob to data URL from btoa.
+ * @private
+ * @param {Blob} blob - The target Blob object.
+ * @returns {Promise<string|null>} A promise resolving to the data URL, or null.
+ */
+const convertFromBtoa = async blob => {
+  const mimeStr = blob.type ? `${blob.type};base64` : 'base64';
+  const buffer = await blob.arrayBuffer();
+  const uint8arr = new Uint8Array(buffer);
+  const chunks = [];
+  for (let i = 0; i < uint8arr.length; i += CHUNK_SIZE) {
+    chunks.push(String.fromCharCode(...uint8arr.subarray(i, i + CHUNK_SIZE)));
+  }
+  return `data:${mimeStr},${btoa(chunks.join(''))}`;
+};
+
+/**
+ * Reads a stream in chunks and validates its size.
+ * @private
+ * @param {ReadableStreamDefaultReader} reader - The stream reader.
+ * @param {number} maxSize - The maximum allowed size in bytes.
+ * @param {Uint8Array[]} chunks - The array to store chunks.
+ * @param {number} [accumulatedSize] - The currently accumulated size.
+ * @returns {Promise<void>}
+ */
+const readStreamInChunks = async (
+  reader,
+  maxSize,
+  chunks,
+  accumulatedSize = 0
+) => {
+  const { done, value } = await reader.read();
+  if (done) {
+    return;
+  }
+  const newSize = accumulatedSize + value.byteLength;
+  if (newSize > maxSize) {
+    await reader.cancel('Size limit exceeded');
+    const msg = `Payload (${newSize} bytes) exceeds max (${maxSize} bytes).`;
+    throw new DOMException(msg, 'NotReadableError');
+  }
+  chunks.push(value);
+  return readStreamInChunks(reader, maxSize, chunks, newSize);
+};
+
+/**
+ * Fetches a blob URL and converts it to a data URL.
+ * @param {string} url - The blob URL to fetch.
+ * @param {number} [maxBlobSize] - The maximum allowed blob size in bytes.
+ * @returns {Promise<string>} A promise resolving to the data URL.
+ */
+const fetchBlobAsDataURL = async (url, maxBlobSize) => {
+  let maxSize = MAX_BLOB_SIZE;
+  if (Number.isInteger(maxBlobSize) && maxBlobSize > 0) {
+    maxSize = maxBlobSize;
+  }
+  const response = await fetch(url);
+  if (!response.ok) {
+    const truncatedUrl = truncateURL(url);
+    let msg = `Failed to fetch ${truncatedUrl}`;
+    if (Number.isInteger(response.status)) {
+      if (response.statusText) {
+        msg += `: ${response.status} ${response.statusText}`;
+      } else {
+        msg += `: ${response.status}`;
+      }
+    }
+    throw new Error(msg);
+  }
+  // Check content length if available.
+  const contentLength = response.headers.get('content-length');
+  if (contentLength) {
+    const parsedLength = Number.parseInt(contentLength, DECI);
+    if (Number.isInteger(parsedLength) && parsedLength > maxSize) {
+      const msg = `Payload (${parsedLength} bytes) exceeds max (${maxSize} bytes).`;
+      throw new DOMException(msg, 'NotReadableError');
+    }
+  }
+  let blob;
+  // Use ReadableStream.
+  if (response.body) {
+    const reader = response.body.getReader();
+    const chunks = [];
+    try {
+      await readStreamInChunks(reader, maxSize, chunks, 0);
+    } finally {
+      reader.releaseLock();
+    }
+    const type = response.headers.get('content-type');
+    if (type) {
+      blob = new Blob(chunks, { type });
+    } else {
+      blob = new Blob(chunks);
+    }
+  } else {
+    blob = await response.blob();
+    if (blob.size > maxSize) {
+      const msg = `Payload (${blob.size} bytes) exceeds max (${maxSize} bytes).`;
+      throw new DOMException(msg, 'NotReadableError');
+    }
+  }
+  if (IS_NODE && globalThis.Buffer) {
+    return convertFromBuffer(blob);
+  } else if (globalThis.FileReader) {
+    return convertFromFileReader(blob);
+  }
+  return convertFromBtoa(blob);
+};
+
+/* URLSanitizer instance */
 const urlSanitizer = new URLSanitizer();
 
 /**
@@ -729,77 +881,62 @@ const urlSanitizer = new URLSanitizer();
  * @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.
- * @param {number} [opt.maxLength] - The maximum allowed URL length
+ * @param {number} [opt.maxLength] - The maximum allowed URL length.
  * @returns {Promise<string|null>} A promise resolving to the sanitized URL, or null.
  */
-export const sanitizeURL = async (
-  url,
-  opt = {
-    allow: [],
-    deny: [],
-    only: [],
-    allowRelative: false,
-    debug: false,
-    revokeObjectURL: false,
-    maxBlobSize: MAX_BLOB_SIZE
+export const sanitizeURL = async (url, opt = {}) => {
+  if (!url || !isString(url)) {
+    return null;
   }
-) => {
-  const isDebug = !!opt?.debug;
-  const maxBlobSize =
-    Number.isInteger(opt?.maxBlobSize) && opt.maxBlobSize > 0
-      ? opt.maxBlobSize
-      : MAX_BLOB_SIZE;
-  let res;
-  if (url && isString(url)) {
-    let scheme;
-    const parsedUrl = URL.parse(url);
-    if (parsedUrl) {
-      scheme = parsedUrl.protocol.replace(/:$/, '');
-    } else {
-      logDebug(isDebug, `Invalid URL input format: ${url}`);
-    }
-    if (scheme === 'blob') {
-      const { allow, deny, only } = opt;
-      if (
-        (Array.isArray(allow) &&
-          allow.includes('blob') &&
-          !(Array.isArray(deny) && deny.includes('blob'))) ||
-        (Array.isArray(only) && only.includes('blob'))
-      ) {
-        let data;
-        try {
-          data = await fetch(url)
-            .then(r => r.blob())
-            .then(b => convertBlobToDataURL(b, maxBlobSize));
-        } catch (e) {
-          const msg = `Failed to fetch and convert blob URL: ${url}`;
-          logDebug(isDebug, msg, e);
+  const options = {
+    ...DEFAULT_OPTS,
+    ...opt
+  };
+  const scheme = urlSanitizer.getScheme(url);
+  if (scheme === null) {
+    if (options.allowRelative) {
+      return urlSanitizer.sanitize(url, options);
+    }
+    return null;
+  }
+  if (scheme === 'blob') {
+    const { allow, deny, only } = options;
+    let res = null;
+    if (
+      (allow.includes('blob') && !deny.includes('blob')) ||
+      only.includes('blob')
+    ) {
+      let data;
+      try {
+        data = await fetchBlobAsDataURL(url, options.maxBlobSize);
+      } catch (e) {
+        if (options.debug) {
+          logDebug(
+            `Failed to fetch and convert blob URL: ${truncateURL(url)}`,
+            e
+          );
         }
-        if (data) {
-          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');
-            }
+      }
+      if (data) {
+        if (only.length) {
+          if (!only.includes('data')) {
+            options.only = [...only, 'data'];
+          }
+        } else {
+          if (!allow.includes('data')) {
+            options.allow = [...allow, 'data'];
           }
-          res = urlSanitizer.sanitize(data, options);
+          options.deny = options.deny.filter(s => s !== 'data');
         }
+        res = urlSanitizer.sanitize(data, options);
       }
-      if (opt?.revokeObjectURL) {
-        URL.revokeObjectURL(url);
-      }
-    } else if (scheme || opt.allowRelative) {
-      res = urlSanitizer.sanitize(url, opt);
     }
+    if (options.revokeObjectURL) {
+      URL.revokeObjectURL(url);
+    }
+    return res;
   }
-  return res || null;
+  return urlSanitizer.sanitize(url, options);
 };
 
 /**
@@ -817,86 +954,66 @@ export const sanitizeURL = async (
  * @param {number} [opt.maxLength] - The maximum allowed URL length.
  * @returns {string|null} The sanitized URL, or null if denied.
  */
-export const sanitizeURLSync = (
-  url,
-  opt = {
-    allow: [],
-    deny: [],
-    only: [],
-    allowRelative: false,
-    debug: false,
-    revokeObjectURL: false
+export const sanitizeURLSync = (url, opt = {}) => {
+  if (!url || !isString(url)) {
+    return null;
   }
-) => {
-  const isDebug = !!opt?.debug;
-  let res;
-  if (url && isString(url)) {
-    let scheme;
-    const parsedUrl = URL.parse(url);
-    if (parsedUrl) {
-      scheme = parsedUrl.protocol.replace(/:$/, '');
-    } else {
-      logDebug(isDebug, `Invalid URL input format: ${url}`);
+  const options = {
+    ...DEFAULT_OPTS,
+    ...opt
+  };
+  const scheme = urlSanitizer.getScheme(url);
+  if (scheme === null) {
+    if (options.allowRelative) {
+      return urlSanitizer.sanitize(url, options);
     }
-    if (scheme === 'blob') {
-      if (opt?.revokeObjectURL) {
-        URL.revokeObjectURL(url);
-      }
-      return null;
-    } else if (scheme || opt.allowRelative) {
-      res = urlSanitizer.sanitize(url, opt);
+    return null;
+  }
+  if (scheme === 'blob') {
+    if (options.revokeObjectURL) {
+      URL.revokeObjectURL(url);
     }
+    return null;
   }
-  return res || null;
+  return urlSanitizer.sanitize(url, options);
 };
 
 /**
- * Inspects, parses, and sanitizes the given URL asynchronously.
+ * Sanitizes the given URL and returns its parsed components.
+ * NOTE: blob URLs are not revoked after inspection.
  * @param {string} url - The URL string to inspect.
  * @returns {Promise<InspectedURLResult>} A promise resolving to the inspected URL result.
  */
 export const inspectURL = async url => {
-  const res = urlSanitizer.inspect(url);
-  return res;
+  if (isString(url)) {
+    const parsedUrl = urlSanitizer.parse(url);
+    if (parsedUrl?.protocol === 'blob:') {
+      try {
+        const dataUrl = await fetchBlobAsDataURL(parsedUrl.href);
+        const inspectedURLResult = urlSanitizer.inspect(dataUrl);
+        inspectedURLResult.input = url;
+        return inspectedURLResult;
+      } catch (e) {
+        return { input: url, valid: false, reason: e.message };
+      }
+    }
+  }
+  return urlSanitizer.inspect(url);
 };
 
 /**
- * @deprecated Use {@link inspectURL} instead.
- * @param {string} url - The URL string to inspect.
- * @returns {Promise<InspectedURLResult>} A promise resolving to the inspected URL result.
- */
-export const parseURL = async url => inspectURL(url);
-
-/**
- * Inspects, parses, and sanitizes the given URL synchronously.
- * @param {string} url - The URL string to inspect.
- * @returns {InspectedURLResult} The inspected URL result.
- */
-export const inspectURLSync = url => urlSanitizer.inspect(url);
-
-/**
- * @deprecated Use {@link inspectURLSync} instead.
- * @param {string} url - The URL string to inspect.
- * @returns {InspectedURLResult} The inspected URL result.
- */
-export const parseURLSync = url => inspectURLSync(url);
-
-/**
- * Asynchronously checks if the given string is a valid URI and is registered.
+ * 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.
+ * @returns {boolean} True if valid and registered, false otherwise.
  */
-export const isURI = async uri => {
-  const res = urlSanitizer.verify(uri);
-  return res;
-};
+export const isValidURI = uri => urlSanitizer.verify(uri);
 
 /**
- * Synchronously checks if the given string is a valid URI and is registered.
+ * @deprecated Use {@link isValidURI} instead.
  * @param {string} uri - The URI string to verify.
  * @returns {boolean} True if valid and registered, false otherwise.
  */
-export const isURISync = uri => urlSanitizer.verify(uri);
+export const isURISync = uri => isValidURI(uri);
 
 /* export instance */
 export default urlSanitizer;