url-sanitizer 4.2.2 → 5.0.1

package/src/mjs/text-chars.js

@@ -4,7 +4,7 @@
 
 /* shared */
 import textChars from '../lib/file/text-chars.json' with { type: 'json' };
-import { HEX } from './constant.js';
+import { BYTE_RANGE, HEX } from './constant.js';
 
 /**
  * A set of valid text character codes.
@@ -47,13 +47,13 @@ export const WINDOWS1252_TO_UNICODE = new Map([
 ]);
 
 /**
- * Generates control character codes in hex.
+ * Generates hexadecimal escape strings for non-text characters.
  * @private
  * @returns {Map<number, string>} Generated control char codes.
  */
-const generateCtrlCharCodes = () => {
+const generateNonTextCharCodes = () => {
   const charCodes = new Map();
-  for (let i = 0; i < HEX * HEX; i++) {
+  for (let i = 0; i < BYTE_RANGE; i++) {
     if (!TEXT_CHAR_CODES.has(i) && !WINDOWS1252_TO_UNICODE.has(i)) {
       charCodes.set(i, `\\x${i.toString(HEX).padStart(2, '0').toUpperCase()}`);
     }
@@ -62,7 +62,7 @@ const generateCtrlCharCodes = () => {
 };
 
 /**
- * A mapping of control character codes to their hexadecimal escape strings.
+ * A mapping of non-text character codes to their hexadecimal escape strings.
  * @type {Map<number, string>}
  */
-export const CTRL_CHAR_CODES = generateCtrlCharCodes();
+export const NON_TEXT_CHAR_CODES = generateNonTextCharCodes();

package/src/mjs/uri-util.js

@@ -7,8 +7,15 @@ import uriSchemes from '../lib/iana/uri-schemes.json' with { type: 'json' };
 import { getType, isString } from './common.js';
 
 /* constants */
-import { CHUNK_SIZE, DECI, HEX, MAX_BLOB_SIZE, MAX_NEST } from './constant.js';
 import {
+  BYTE_RANGE,
+  DECI,
+  HEX,
+  MAX_NEST,
+  TRUNCATE_LENGTH
+} from './constant.js';
+import {
+  REG_AMP,
   REG_HASH,
   REG_NUM_REF,
   REG_PCT_ENC,
@@ -18,7 +25,7 @@ import {
   REG_URL_ENC
 } from './regexp.js';
 import {
-  CTRL_CHAR_CODES,
+  NON_TEXT_CHAR_CODES,
   TEXT_CHAR_CODES,
   WINDOWS1252_TO_UNICODE
 } from './text-chars.js';
@@ -38,15 +45,13 @@ const ESCAPE_MAP = {
   [ENC_APOS]: `${ENC_AMP}${ENC_NUM}39;`
 };
 const HEX_TABLE = Array.from(
-  { length: HEX * HEX },
+  { length: BYTE_RANGE },
   (_, i) => `%${i.toString(HEX).padStart(2, '0').toUpperCase()}`
 );
 const IS_NODE = globalThis.process?.versions?.node !== undefined;
-const REG_BINARY = new RegExp(`[${[...CTRL_CHAR_CODES.values()].join('')}]`);
-const REG_CTRL_CHARS = new RegExp(
-  `[${[...CTRL_CHAR_CODES.values()].join('')}]`,
-  'g'
-);
+const NON_TEXT_PATTERN = `[${[...NON_TEXT_CHAR_CODES.values()].join('')}]`;
+const REG_NON_TEXT = new RegExp(NON_TEXT_PATTERN);
+const REG_NON_TEXT_G = new RegExp(NON_TEXT_PATTERN, 'g');
 
 /* encoder / decoder */
 const encoder = new TextEncoder();
@@ -70,43 +75,128 @@ export class URISchemes {
     return [...this.#schemes];
   }
 
+  /**
+   * Extracts the scheme from URI.
+   * @param {string} uri - The URI string.
+   * @returns {string|null} The extracted scheme, or null.
+   */
+  getScheme(uri) {
+    if (!isString(uri)) {
+      return null;
+    }
+    const parsed = this.parse(uri);
+    if (parsed) {
+      return parsed.protocol.replace(/:$/, '');
+    }
+    return null;
+  }
+
   /**
    * Checks if the specified scheme is currently registered.
    * @param {string} scheme - The target scheme.
    * @returns {boolean} True if the scheme is registered.
    */
   has(scheme) {
-    if (!isString(scheme)) {
-      return false;
+    const normalized = this.normalize(scheme, true);
+    if (normalized) {
+      return this.#schemes.has(normalized);
+    }
+    return false;
+  }
+
+  /**
+   * Normalizes the URI string using NFKC.
+   * @param {string} uri - The URL to normalize.
+   * @param {boolean} [isScheme] - True if uri is a scheme.
+   * @returns {string|null} The normalized URI string, or null.
+   */
+  normalize(uri, isScheme = false) {
+    if (!isString(uri)) {
+      return null;
     }
-    return this.#schemes.has(scheme.trim().toLowerCase());
+    const normalized = uri.normalize('NFKC');
+    if (isScheme) {
+      return normalized.trim().toLowerCase();
+    }
+    return normalized;
+  }
+
+  /**
+   * Parse the URI string.
+   * @param {string} uri - The URI string.
+   * @param {string} [base] - The base URI string.
+   * @returns {URL|null} The parsed URL object, or null.
+   */
+  parse(uri, base) {
+    if (!isString(uri)) {
+      return null;
+    }
+    const normalized = this.normalize(uri);
+    if (base && isString(base)) {
+      return URL.parse(normalized, this.normalize(base));
+    }
+    return URL.parse(normalized);
   }
 
   /**
    * 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.
+   * @returns {boolean} True if the URI is valid and permitted.
    */
-  verify(uri, schemes = this.#schemes) {
+  verify(uri, schemes) {
     if (!isString(uri)) {
       return false;
     }
-    const normalizedUri = uri.normalize('NFKC');
-    const parsedUrl = URL.parse(normalizedUri);
-    if (!parsedUrl) {
+    const parsedUrl = this.parse(uri);
+    return this.verifyParsed(parsedUrl, schemes, true);
+  }
+
+  /**
+   * Verifies if the pre-parsed URL object is valid and its scheme is allowed.
+   * @param {URL} parsedUrl - The parsed URL object to verify.
+   * @param {Set<string>} [schemes] - The set of allowed schemes.
+   * @param {boolean} [allowCustom] - True if web+*, ext+* schemes are allowed.
+   * @returns {boolean} True if the parsed URL is valid and permitted.
+   */
+  verifyParsed(parsedUrl, schemes, allowCustom = false) {
+    if (!parsedUrl || !parsedUrl.protocol) {
       return false;
     }
-    const scheme = parsedUrl.protocol.replace(/:$/, '');
+    const scheme = parsedUrl.protocol.toLowerCase().replace(/:$/, '');
     const parts = scheme.split('+');
     const isScript = parts.some(s => REG_SCRIPT.test(s));
     if (isScript) {
       return false;
     }
-    return REG_SCHEME_EXT.test(scheme) || parts.every(s => schemes.has(s));
+    if (!schemes) {
+      schemes = this.#schemes;
+    }
+    if (schemes.has(scheme)) {
+      return true;
+    }
+    if (parts.length > 1) {
+      return (
+        (allowCustom && REG_SCHEME_EXT.test(scheme)) ||
+        parts.every(s => schemes.has(s))
+      );
+    }
+    return false;
   }
 }
 
+/**
+ * Extracts an array of schemes.
+ * @param {string} protocol - The URL protocol (e.g., "data:", "git+https:").
+ * @returns {string[]} An array of scheme parts.
+ */
+export const getSchemeParts = protocol => {
+  if (!isString(protocol)) {
+    return [];
+  }
+  return protocol.replace(/:$/, '').split('+');
+};
+
 /**
  * Gets the URL-encoded representation of a given string.
  * @param {string} str - The target string.
@@ -117,11 +207,11 @@ export const getURLEncodedString = str => {
     throw new TypeError(`Expected String but got ${getType(str)}.`);
   }
   const bytes = encoder.encode(str);
-  let encoded = '';
+  const encoded = new Array(bytes.length);
   for (let i = 0; i < bytes.length; i++) {
-    encoded += HEX_TABLE[bytes[i]];
+    encoded[i] = HEX_TABLE[bytes[i]];
   }
-  return encoded;
+  return encoded.join('');
 };
 
 /**
@@ -129,7 +219,6 @@ export const getURLEncodedString = str => {
  * @param {string} ch - A URL-encoded (percent-encoded) character.
  * @returns {string} The escaped HTML special character, or the given character.
  */
-
 export const escapeURLEncodedHTMLChars = ch => {
   if (!isString(ch)) {
     return ch;
@@ -139,65 +228,15 @@ export const escapeURLEncodedHTMLChars = ch => {
 };
 
 /**
- * Parses base64-encoded data.
- * @param {string} data - The base64-encoded string.
- * @returns {string} The parsed text, or the original base64 if binary.
- */
-export const parseBase64 = data => {
-  if (!isString(data)) {
-    throw new TypeError(`Expected String but got ${getType(data)}.`);
-  }
-  const cleanData = data.replace(/\s/g, '');
-  let binStr;
-  try {
-    binStr = atob(cleanData);
-  } catch {
-    throw new Error(`Invalid base64 data: ${data}`);
-  }
-  let bytes;
-  if (IS_NODE && globalThis.Buffer) {
-    // Use 'latin1' to correctly map the binary string directly to bytes.
-    // @see https://nodejs.org/docs/latest/api/buffer.html#buffers-and-character-encodings
-    bytes = globalThis.Buffer.from(binStr, 'latin1');
-  } else {
-    const len = binStr.length;
-    bytes = new Uint8Array(len);
-    for (let i = 0; i < len; i++) {
-      bytes[i] = binStr.charCodeAt(i);
-    }
-  }
-  try {
-    const text = decoder.decode(bytes);
-    if (REG_BINARY.test(text)) {
-      return cleanData;
-    }
-    return text;
-  } catch {
-    return cleanData;
-  }
-};
-
-/**
- * Replaces URL-encoded numeric character references.
- * @param {string} match - The matched substring.
- * @param {string} value - The captured numeric value.
- * @returns {string} The resolved character or the original match.
+ * Truncate URL string.
+ * @param {string|unknown} url - A URL string
+ * @returns {string} - The truncated string
  */
-export const replaceNumCharRef = (match, value) => {
-  const num = /x/i.test(value[0])
-    ? parseInt(value.substring(1), HEX)
-    : parseInt(value, DECI);
-  if (Number.isInteger(num)) {
-    if (TEXT_CHAR_CODES.has(num)) {
-      return String.fromCharCode(num);
-    } else if (WINDOWS1252_TO_UNICODE.has(num)) {
-      const codePoint = WINDOWS1252_TO_UNICODE.get(num);
-      return String.fromCodePoint(codePoint);
-    } else if (CTRL_CHAR_CODES.has(num)) {
-      return '';
-    }
-  }
-  return match;
+export const truncateURL = url => {
+  const str = isString(url) ? url : String(url);
+  const truncated =
+    str.length > TRUNCATE_LENGTH ? `${str.slice(0, TRUNCATE_LENGTH)}...` : str;
+  return truncated;
 };
 
 /**
@@ -213,7 +252,30 @@ export const trimTrailingEmptyQueryAndHash = url => {
 };
 
 /**
- * Parses URL-encoded numeric character references in the range 0x00 to 0xFF.
+ * Replaces URL-encoded numeric character references.
+ * @param {string} match - The matched substring.
+ * @param {string} value - The captured numeric value.
+ * @returns {string} The resolved character or the original match.
+ */
+export const replaceNumCharRef = (match, value) => {
+  const num = /^x/i.test(value)
+    ? Number.parseInt(value.slice(1), HEX)
+    : Number.parseInt(value, DECI);
+  if (!Number.isInteger(num) || num < 0 || num >= BYTE_RANGE) {
+    return match;
+  }
+  if (NON_TEXT_CHAR_CODES.has(num)) {
+    return '';
+  }
+  if (TEXT_CHAR_CODES.has(num)) {
+    return String.fromCharCode(num);
+  }
+  const codePoint = WINDOWS1252_TO_UNICODE.get(num);
+  return String.fromCodePoint(codePoint);
+};
+
+/**
+ * Parses URL-encoded numeric character references.
  * @param {string} str - The target string to parse.
  * @param {number} [nest] - The current nesting depth for recursive parsing.
  * @returns {string} The decoded and parsed string.
@@ -238,84 +300,84 @@ export const parseURLEncodedNumCharRef = (str, nest = 0) => {
       }
     });
   }
-  res = res.replace(REG_CTRL_CHARS, '');
+  res = res.replace(REG_NON_TEXT_G, '');
   let depth = 0;
-  for (; depth + nest <= MAX_NEST; depth++) {
+  for (; depth + nest < MAX_NEST; depth++) {
     const previousRes = res;
     // Decode '&amp;' before decoding numeric references.
-    res = res.replace(/&amp;/gi, '&').replace(REG_NUM_REF, replaceNumCharRef);
+    res = res.replace(REG_AMP, '&').replace(REG_NUM_REF, replaceNumCharRef);
     if (res === previousRes) {
       break;
     }
   }
-  if (depth + nest > MAX_NEST && /&#/.test(res)) {
+  if (depth + nest >= MAX_NEST && /&#/.test(res)) {
     throw new Error('Character references nested too deeply.');
   }
   return res;
 };
 
 /**
- * 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.
+ * Extracts the components of a parsed Data URL.
+ * @param {string} pathname - The pathname of the URL.
+ * @param {string} [search] - The search (query) string of the URL.
+ * @param {string} [hash] - The hash (fragment) of the URL.
+ * @returns {object} An object containing the media type, parsed media types array, data string, and a boolean indicating if it is base64-encoded.
  */
-const convertFromFileReader = blob =>
-  new Promise((resolve, reject) => {
-    const reader = new globalThis.FileReader();
-    reader.addEventListener('error', () => reject(reader.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)));
+export const extractDataUrlComponents = (pathname, search = '', hash = '') => {
+  if (!isString(pathname)) {
+    return { mediaType: '', mediaTypes: [], data: '', isBase64: false };
+  }
+  const comma = pathname.indexOf(',');
+  if (comma === -1) {
+    return {
+      mediaType: pathname,
+      mediaTypes: pathname.split(';'),
+      data: '',
+      isBase64: false
+    };
   }
-  return `data:${mimeStr},${btoa(chunks.join(''))}`;
+  const mediaType = pathname.slice(0, comma);
+  const data = `${pathname.slice(comma + 1)}${search}${hash}`;
+  const mediaTypes = mediaType.split(';');
+  const isBase64 = /^base64$/i.test(mediaTypes.at(-1));
+  return { mediaType, mediaTypes, data, isBase64 };
 };
 
 /**
- * Converts a Blob to a data URL.
- * @param {Blob} blob - The target Blob object.
- * @param {number} [maxSize] - The maximum allowed blob size.
- * @returns {Promise<string|null>} A promise resolving to the data URL, or null.
+ * Parses base64-encoded data.
+ * @param {string} data - The base64-encoded string.
+ * @returns {string} The parsed text, or the original base64 if binary.
  */
-export const convertBlobToDataURL = async (blob, maxSize = MAX_BLOB_SIZE) => {
-  if (!Number.isInteger(blob?.size)) {
-    return null;
-  } else if (Number.isInteger(maxSize) && blob.size > maxSize) {
-    const msg = `Blob size (${blob.size} bytes) exceeds max (${maxSize} bytes).`;
-    throw new DOMException(msg, 'NotReadableError');
+export const parseBase64 = data => {
+  if (!isString(data)) {
+    throw new TypeError(`Expected String but got ${getType(data)}.`);
   }
+  const cleanData = data.replace(/\s/g, '');
+  let binStr;
+  try {
+    binStr = atob(cleanData);
+  } catch {
+    throw new Error(`Invalid base64 data: ${truncateURL(data)}`);
+  }
+  let bytes;
   if (IS_NODE && globalThis.Buffer) {
-    return convertFromBuffer(blob);
-  } else if (globalThis.FileReader) {
-    return convertFromFileReader(blob);
+    // Use 'latin1' to correctly map the binary string directly to bytes.
+    // @see https://nodejs.org/docs/latest/api/buffer.html#buffers-and-character-encodings
+    bytes = globalThis.Buffer.from(binStr, 'latin1');
+  } else {
+    const len = binStr.length;
+    bytes = new Uint8Array(len);
+    for (let i = 0; i < len; i++) {
+      bytes[i] = binStr.charCodeAt(i);
+    }
+  }
+  try {
+    const text = decoder.decode(bytes);
+    if (REG_NON_TEXT.test(text)) {
+      return cleanData;
+    }
+    return text;
+  } catch {
+    return cleanData;
   }
-  return convertFromBtoa(blob);
 };

package/types/index.d.ts

@@ -5,4 +5,4 @@
  * @copyright asamuzaK (Kazz)
  * @see {@link https://github.com/asamuzaK/urlSanitizer/blob/main/LICENSE}
  */
-export { default, inspectURL, inspectURLSync, isURI, isURISync, parseURL, parseURLSync, sanitizeURL, sanitizeURLSync } from './mjs/sanitizer.js';
+export { default, inspectURL, isURISync, isValidURI, sanitizeURL, sanitizeURLSync } from './mjs/sanitizer.js';

package/types/mjs/constant.d.ts

@@ -1,7 +1,10 @@
+export declare const BYTE_RANGE: number;
 export declare const CHUNK_SIZE: number;
 export declare const DECI: number;
 export declare const HEX: number;
 export declare const MAX_BLOB_SIZE: number;
 export declare const MAX_NEST: number;
+export declare const MAX_URL_LENGTH: number;
+export declare const TRUNCATE_LENGTH: number;
 export declare const TYPE_FROM: number;
 export declare const TYPE_TO: number;

package/types/mjs/regexp.d.ts

@@ -7,9 +7,10 @@ export declare const REG_QUERY: RegExp;
 export declare const REG_SCHEME: RegExp;
 export declare const REG_SCHEME_EXT: RegExp;
 export declare const REG_SCRIPT: RegExp;
-export declare const REG_SCRIPT_BLOB: RegExp;
+export declare const REG_SCRIPT_OR_BLOB: RegExp;
 export declare const REG_TAG_QUOT: RegExp;
 export declare const REG_URL_ENC: RegExp;
-export declare const REG_AMP_ENC: RegExp;
 export declare const REG_PCT_ENC: RegExp;
+export declare const REG_AMP: RegExp;
+export declare const REG_AMP_ENC: RegExp;
 export declare const REG_VERIFY_RELATIVE: RegExp;

package/types/mjs/sanitizer.d.ts

@@ -7,6 +7,7 @@ export type InspectedDataURL = {
 export type InspectedURLResult = {
     input: string;
     valid: boolean;
+    relative?: boolean;
     reason?: string;
     data?: InspectedDataURL | null;
     href?: string;
@@ -21,18 +22,30 @@ export type InspectedURLResult = {
     search?: string;
     hash?: string;
 };
-export declare const logDebug: (isDebug: boolean, message: string, error?: Error) => void;
-declare class URLSanitizer extends URISchemes {
+export declare const logDebug: (message: string, error?: Error) => void;
+export declare class SanitizeContext {
+    debug: boolean;
+    domPurify: object;
+    nest: number;
+    recurse: Set<any>;
+    schemeMap: Map<string, boolean>;
+    constructor(opt: object, domPurifyInstance: object);
+    enter(url: string): boolean;
+    leave(url: string): void;
+}
+export declare class URLSanitizer extends URISchemes {
     #private;
-    private static #uponSanitizeAttribute;
     constructor();
-    private #registerScheme;
-    private #purify;
+    private #executeSanitize;
     private #process;
     private #resolveSchemeRules;
+    private #registerScheme;
+    private #isValidScheme;
     private #parseAndVerifyURL;
     private #isSchemeAllowed;
     private #sanitizeDataURL;
+    private #purify;
+    private #handleSanitizeAttribute;
     private #sanitizeStandardURL;
     sanitize(url: string, opt?: {
         allow?: string[];
@@ -43,7 +56,7 @@ declare class URLSanitizer extends URISchemes {
         maxBlobSize?: number;
         maxLength?: number;
     }): string | null;
-    inspect(url: string, opt?: object): InspectedURLResult;
+    inspect(url: string): InspectedURLResult;
     get(): string[];
     has(scheme: string): boolean;
     add(scheme: string): string[];
@@ -51,7 +64,6 @@ declare class URLSanitizer extends URISchemes {
     reset(): void;
     verify(uri: string, schemes?: Set<string>): boolean;
 }
-export { URLSanitizer };
 declare const urlSanitizer: URLSanitizer;
 export declare const sanitizeURL: (url: string, opt?: {
     allow?: string[];
@@ -73,9 +85,6 @@ export declare const sanitizeURLSync: (url: string, opt?: {
     maxLength?: number;
 }) => string | null;
 export declare const inspectURL: (url: string) => Promise<InspectedURLResult>;
-export declare const parseURL: (url: string) => Promise<InspectedURLResult>;
-export declare const inspectURLSync: (url: string) => InspectedURLResult;
-export declare const parseURLSync: (url: string) => InspectedURLResult;
-export declare const isURI: (uri: string) => Promise<boolean>;
+export declare const isValidURI: (uri: string) => boolean;
 export declare const isURISync: (uri: string) => boolean;
 export default urlSanitizer;

package/types/mjs/text-chars.d.ts

@@ -1,3 +1,3 @@
 export declare const TEXT_CHAR_CODES: Set<number>;
 export declare const WINDOWS1252_TO_UNICODE: Map<number, number>;
-export declare const CTRL_CHAR_CODES: Map<number, string>;
+export declare const NON_TEXT_CHAR_CODES: Map<number, string>;

package/types/mjs/uri-util.d.ts

@@ -1,13 +1,19 @@
 export declare class URISchemes {
     #private;
     get(): string[];
+    getScheme(uri: string): string | null;
     has(scheme: string): boolean;
+    normalize(uri: string, isScheme?: boolean): string | null;
+    parse(uri: string, base?: string): URL | null;
     verify(uri: string, schemes?: Set<string>): boolean;
+    verifyParsed(parsedUrl: URL, schemes?: Set<string>, allowCustom?: boolean): boolean;
 }
+export declare const getSchemeParts: (protocol: string) => string[];
 export declare const getURLEncodedString: (str: string) => string;
 export declare const escapeURLEncodedHTMLChars: (ch: string) => string;
-export declare const parseBase64: (data: string) => string;
-export declare const replaceNumCharRef: (match: string, value: string) => string;
+export declare const truncateURL: (url: string | unknown) => string;
 export declare const trimTrailingEmptyQueryAndHash: (url: string) => string;
+export declare const replaceNumCharRef: (match: string, value: string) => string;
 export declare const parseURLEncodedNumCharRef: (str: string, nest?: number) => string;
-export declare const convertBlobToDataURL: (blob: Blob, maxSize?: number) => Promise<string | null>;
+export declare const extractDataUrlComponents: (pathname: string, search?: string, hash?: string) => object;
+export declare const parseBase64: (data: string) => string;