mcp-sanitizer 1.4.1 → 1.4.2

package/README.md

@@ -188,7 +188,8 @@ const sanitizer = new MCPSanitizer({
   contextSettings: {
     url: {
       allowPrivateIPs: false,
-      allowLocalhostWithoutPort: false
+      blockedDomains: ['tracker.example'], // Domain and its subdomains
+      allowedDomains: []                    // Non-empty = only these domains
     },
     filePath: {
       allowAbsolutePaths: false,
@@ -368,6 +369,24 @@ if (urlResult.blocked) {
 }
 ```
 
+`sanitize()` checks the URL string only: it blocks private/loopback/link-local IP
+literals and internal-only names (`*.internal`, `*.local`, ...), but cannot know
+that a public name such as `10.0.0.5.nip.io` resolves to a private address. Before
+fetching, resolve and pin with `resolveAndValidateURL`:
+
+```javascript
+const http = require('http');
+const { resolveAndValidateURL } = require('mcp-sanitizer');
+
+// Rejects if the hostname resolves to any restricted address
+const { url, address, family } = await resolveAndValidateURL(params.url);
+
+// Connect to the checked address so a DNS change cannot redirect the request
+const lookup = (host, opts, cb) =>
+  opts.all ? cb(null, [{ address, family }]) : cb(null, address, family);
+http.get(url, { lookup });
+```
+
 ## Contributing
 
 1. Fork the repository

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-sanitizer",
-  "version": "1.4.1",
+  "version": "1.4.2",
   "description": "Comprehensive security sanitization library for Model Context Protocol (MCP) servers with trusted security libraries",
   "main": "src/index.js",
   "files": [
@@ -39,7 +39,7 @@
     "escape-html": "^1.0.3",
     "path-is-inside": "^1.0.2",
     "sanitize-filename": "^1.6.3",
-    "shell-quote": "^1.10.0",
+    "shell-quote": "^1.12.0",
     "sqlstring": "^2.3.3",
     "unorm": "^1.6.0",
     "validator": "^13.15.22"
@@ -67,11 +67,11 @@
     "qs": ">=6.15.2",
     "flatted": ">=3.4.2",
     "form-data": ">=4.0.6",
-    "js-yaml": "4.3.1",
+    "js-yaml": "4.3.2",
     "@istanbuljs/load-nyc-config": {
-      "js-yaml": "3.15.1"
+      "js-yaml": "3.15.2"
     },
-    "brace-expansion": "1.1.18",
+    "brace-expansion": "1.1.21",
     "@babel/core": "^7.29.7"
   }
 }

package/src/index.js

@@ -116,6 +116,7 @@ module.exports.validateAgainstBlockedPatterns = utils.validateAgainstBlockedPatt
 module.exports.isDangerousKey = utils.isDangerousKey;
 module.exports.validateObjectKey = utils.validateObjectKey;
 module.exports.validateNonEmptyString = utils.validateNonEmptyString;
+module.exports.resolveAndValidateURL = utils.validationUtils.resolveAndValidateURL;
 
 // Export new security enhancement functions
 module.exports.detectDirectionalOverrides = utils.detectDirectionalOverrides;

package/src/sanitizer/mcp-sanitizer.js

@@ -696,7 +696,7 @@ class MCPSanitizer {
   _secureSanitizeURL (url) {
     // url is already decoded by _sanitizeString
     const parsedUrl = validationUtils.validateURL(url, this.options.allowedProtocols);
-    validationUtils.validateURLLocation(parsedUrl);
+    validationUtils.validateURLLocation(parsedUrl, this.options.contextSettings?.url);
     return parsedUrl.toString();
   }
 
@@ -806,7 +806,7 @@ class MCPSanitizer {
   _legacySanitizeURL (url) {
     // Legacy URL sanitization - security decoder is now integrated
     const parsedUrl = validationUtils.validateURL(url, this.options.allowedProtocols);
-    validationUtils.validateURLLocation(parsedUrl);
+    validationUtils.validateURLLocation(parsedUrl, this.options.contextSettings?.url);
     return parsedUrl.toString();
   }
 

package/src/sanitizer/validators/file-path.js

@@ -26,7 +26,7 @@
  */
 
 const path = require('path');
-// const { validationUtils } = require('../../utils') // Unused - commented to fix ESLint
+const { assertNotSensitivePath } = require('../../utils/validation-utils');
 const { detectAllPatterns, SEVERITY_LEVELS } = require('../../patterns');
 const sanitizeFilename = require('sanitize-filename');
 const pathIsInside = require('path-is-inside');
@@ -220,6 +220,15 @@ class FilePathValidator {
         return result;
       }
 
+      // GHSA-v25x-53wq-6r99 FIX: shared sensitive-path denylist.
+      try {
+        assertNotSensitivePath(normalizedPath);
+      } catch (error) {
+        result.warnings.push(error.message);
+        result.severity = this._getHigherSeverity(result.severity, SEVERITY.CRITICAL);
+        return result;
+      }
+
       // Check file extension
       const extension = path.extname(normalizedPath).toLowerCase();
       result.metadata.extension = extension;

package/src/sanitizer/validators/url.js

@@ -27,7 +27,8 @@
  */
 
 const { URL } = require('url');
-// const { validationUtils } = require('../../utils') // Unused - commented to fix ESLint
+const net = require('net');
+const { classifyHost, assertDomainAllowed, resolveHost } = require('../../utils/validation-utils');
 const { detectAllPatterns, SEVERITY_LEVELS } = require('../../patterns');
 const validator = require('validator');
 const {
@@ -249,13 +250,13 @@ class URLValidator {
       if (!hostnameResult.isValid) {
         result.warnings.push(...hostnameResult.warnings);
         result.severity = this._getHigherSeverity(result.severity, hostnameResult.severity);
-
-        if (hostnameResult.severity === SEVERITY.CRITICAL) {
-          return result;
-        }
+        return result;
       }
       result.metadata.hostname = parsedUrl.hostname;
       result.metadata.isPrivateIP = hostnameResult.isPrivateIP;
+      if (hostnameResult.resolvedAddresses) {
+        result.metadata.resolvedAddresses = hostnameResult.resolvedAddresses;
+      }
 
       // Validate port
       const portResult = this._validatePort(parsedUrl.port, parsedUrl.protocol);
@@ -473,90 +474,65 @@ class URLValidator {
       return result;
     }
 
-    // Check dangerous hostname patterns
-    for (const pattern of DANGEROUS_HOSTNAMES) {
-      if (pattern.test(hostname)) {
-        const allowanceCheck = this._checkHostnameAllowance(hostname);
-        if (!allowanceCheck.allowed) {
-          result.isValid = false;
-          result.warnings.push(`Hostname '${hostname}' is ${allowanceCheck.reason}`);
-          result.severity = SEVERITY.CRITICAL;
-          return result;
-        } else {
-          result.warnings.push(`Warning: Accessing ${allowanceCheck.reason} hostname '${hostname}'`);
-          result.severity = SEVERITY.MEDIUM;
-        }
-      }
+    // GHSA-v25x-53wq-6r99 FIX: use the shared classifier, not local regexes.
+    const locationResult = this._validateLocation(hostname);
+    result.isPrivateIP = locationResult.isPrivate;
+    if (!locationResult.isValid) {
+      result.isValid = false;
+      result.warnings.push(...locationResult.warnings);
+      result.severity = locationResult.severity;
+      return result;
+    }
+    if (locationResult.warnings.length > 0) {
+      result.warnings.push(...locationResult.warnings);
+      result.severity = this._getHigherSeverity(result.severity, locationResult.severity);
     }
 
-    // Check if hostname is an IP address
-    if (this._isIPAddress(hostname)) {
-      const ipResult = this._validateIPAddress(hostname);
-      result.isPrivateIP = ipResult.isPrivate;
-
-      if (!ipResult.isValid) {
-        result.isValid = false;
-        result.warnings.push(...ipResult.warnings);
-        result.severity = ipResult.severity;
-      }
+    const host = classifyHost(hostname).hostname;
+    try {
+      assertDomainAllowed(host, this.config);
+    } catch (error) {
+      result.isValid = false;
+      result.warnings.push(error.message);
+      result.severity = SEVERITY.CRITICAL;
+      return result;
     }
 
-    // DNS validation if enabled
-    if (this.config.validateDNS && result.isValid) {
+    // GHSA-qvp2-8q5w-gcfp FIX: when enabled, classify every resolved address,
+    // not just whether the name resolves. Fails closed on lookup errors.
+    if (this.config.validateDNS && !net.isIP(host)) {
+      let resolved;
       try {
-        const dns = require('dns').promises;
-        await dns.lookup(hostname);
+        resolved = await resolveHost(host);
       } catch (error) {
-        result.warnings.push(`DNS resolution failed for hostname '${hostname}'`);
-        result.severity = this._getHigherSeverity(result.severity, SEVERITY.MEDIUM);
+        result.isValid = false;
+        result.warnings.push(`DNS resolution failed for hostname '${host}'`);
+        result.severity = SEVERITY.HIGH;
+        return result;
       }
+      for (const { address } of resolved) {
+        const addressResult = this._validateLocation(address);
+        if (!addressResult.isValid) {
+          result.isValid = false;
+          result.isPrivateIP = true;
+          result.warnings.push(`Hostname '${host}' resolves to a restricted address`, ...addressResult.warnings);
+          result.severity = SEVERITY.CRITICAL;
+          return result;
+        }
+      }
+      result.resolvedAddresses = resolved.map(({ address, family }) => ({ address, family }));
     }
 
     return result;
   }
 
   /**
-   * Check if hostname access is allowed based on configuration
-   * @param {string} hostname - Hostname to check
-   * @returns {Object} Allowance check result
-   * @private
-   */
-  _checkHostnameAllowance (hostname) {
-    const lower = hostname.toLowerCase();
-
-    if (lower === 'localhost' || lower === '127.0.0.1' || lower === '::1') {
-      return {
-        allowed: this.config.allowLocalhost || this.config.allowLoopback,
-        reason: 'localhost/loopback'
-      };
-    }
-
-    return { allowed: true, reason: null };
-  }
-
-  /**
-   * Check if a string is an IP address
-   * @param {string} hostname - Hostname to check
-   * @returns {boolean} True if it's an IP address
-   * @private
-   */
-  _isIPAddress (hostname) {
-    // IPv4 pattern
-    const ipv4Pattern = /^(\d{1,3}\.){3}\d{1,3}$/;
-
-    // IPv6 pattern (simplified)
-    const ipv6Pattern = /^([0-9a-f]{0,4}:){2,7}[0-9a-f]{0,4}$/i;
-
-    return ipv4Pattern.test(hostname) || ipv6Pattern.test(hostname);
-  }
-
-  /**
-   * Validate IP address for private ranges and restrictions
-   * @param {string} ip - IP address to validate
+   * Apply this validator's allow* flags to the shared host classification.
+   * @param {string} hostname - `URL.hostname` (brackets allowed)
    * @returns {Object} Validation result
    * @private
    */
-  _validateIPAddress (ip) {
+  _validateLocation (hostname) {
     const result = {
       isValid: true,
       warnings: [],
@@ -564,40 +540,29 @@ class URLValidator {
       isPrivate: false
     };
 
-    // Check IPv4 private ranges
-    for (const pattern of PRIVATE_IP_RANGES.ipv4) {
-      if (pattern.test(ip)) {
-        result.isPrivate = true;
-
-        if (!this.config.allowPrivateIPs) {
-          result.isValid = false;
-          result.warnings.push(`Access to private IP address '${ip}' is not allowed`);
-          result.severity = SEVERITY.CRITICAL;
-          return result;
-        } else {
-          result.warnings.push(`Warning: Accessing private IP address '${ip}'`);
-          result.severity = SEVERITY.MEDIUM;
-        }
-        break;
-      }
+    const { hostname: host, category } = classifyHost(hostname);
+    if (!category) {
+      return result;
     }
 
-    // Check IPv6 private ranges
-    for (const pattern of PRIVATE_IP_RANGES.ipv6) {
-      if (pattern.test(ip)) {
-        result.isPrivate = true;
+    const allowedBy = {
+      localhost: this.config.allowLocalhost || this.config.allowLoopback,
+      loopback: this.config.allowLocalhost || this.config.allowLoopback,
+      unspecified: this.config.allowLocalhost || this.config.allowLoopback,
+      private: this.config.allowPrivateIPs,
+      'internal-name': this.config.allowPrivateIPs,
+      reserved: this.config.allowPrivateIPs,
+      'link-local': this.config.allowLinkLocal
+    };
 
-        if (!this.config.allowPrivateIPs) {
-          result.isValid = false;
-          result.warnings.push(`Access to private IPv6 address '${ip}' is not allowed`);
-          result.severity = SEVERITY.CRITICAL;
-          return result;
-        } else {
-          result.warnings.push(`Warning: Accessing private IPv6 address '${ip}'`);
-          result.severity = SEVERITY.MEDIUM;
-        }
-        break;
-      }
+    result.isPrivate = true;
+    if (!allowedBy[category]) {
+      result.isValid = false;
+      result.warnings.push(`Access to ${category} address '${host}' is not allowed`);
+      result.severity = SEVERITY.CRITICAL;
+    } else {
+      result.warnings.push(`Warning: Accessing ${category} address '${host}'`);
+      result.severity = SEVERITY.MEDIUM;
     }
 
     return result;

package/src/utils/validation-utils.js

@@ -10,6 +10,7 @@
 
 const path = require('path');
 const net = require('net');
+const dns = require('dns');
 const { URL } = require('url');
 // CVE-TBD-001 FIX: Import unified parser for consistent string normalization
 const { parseUnified } = require('./unified-parser');
@@ -150,19 +151,7 @@ function validateFilePath (filePath) {
     }
   }
 
-  // GHSA-7w82-6f9j-v9jp FIX: Block sensitive user-configuration files/directories
-  // regardless of where they sit (home dir, /tmp, cwd, relative paths). These hold
-  // SSH keys, cloud credentials, and tokens that must never be exposed via a tool.
-  const sensitiveFileFragments = [
-    '/.ssh/', '/.aws/', '/.gnupg/', '/.kube/', '/.config/',
-    '/.docker/', '/.npmrc', '/.netrc', '/.env', '/.git-credentials'
-  ];
-  const sensitiveCheckPath = lowerPath.replace(/\\/g, '/');
-  for (const fragment of sensitiveFileFragments) {
-    if (sensitiveCheckPath.includes(fragment)) {
-      throw new Error('Access to sensitive configuration path not allowed');
-    }
-  }
+  assertNotSensitivePath(normalizedPath);
 
   // Use path-is-inside to check if the path tries to escape a safe directory
   // Define safe root directories
@@ -219,6 +208,31 @@ function validateFilePath (filePath) {
   return safePath;
 }
 
+// Directory or file names that hold credentials; `.env.*` is matched separately.
+const SENSITIVE_PATH_SEGMENTS = new Set([
+  '.ssh', '.aws', '.gnupg', '.kube', '.config', '.docker',
+  '.npmrc', '.netrc', '.env', '.git-credentials'
+]);
+
+/**
+ * GHSA-7w82-6f9j-v9jp FIX: Block sensitive config files/dirs (SSH keys, cloud
+ * credentials, tokens) wherever they sit. Shared by every file-path entry point
+ * (GHSA-v25x-53wq-6r99 FIX: validators/file-path.js never ran this check).
+ *
+ * GHSA-6xj4-4chr-656w FIX: match whole path segments, not `/`-prefixed
+ * substrings, so a sensitive first segment (`.env`, `.ssh/id_rsa`) is caught.
+ * @param {string} normalizedPath - Path already normalized by the unified parser
+ * @throws {Error} - If the path targets a sensitive configuration location
+ */
+function assertNotSensitivePath (normalizedPath) {
+  const segments = normalizedPath.toLowerCase().split(/[\\/]+/)
+    // Windows ignores trailing dots/spaces and `:stream` suffixes (`.env.`, `.env::$DATA`).
+    .map(s => s.replace(/:.*$/, '').replace(/[. ]+$/, ''));
+  if (segments.some(s => SENSITIVE_PATH_SEGMENTS.has(s) || /^\.env\./.test(s))) {
+    throw new Error('Access to sensitive configuration path not allowed');
+  }
+}
+
 /**
  * Validate file extension against allowed list
  * @param {string} filePath - The file path to validate
@@ -314,103 +328,239 @@ function expandIPv6 (addr) {
     .join(':');
 }
 
+// Name suffixes that only resolve on private networks (RFC 6762, 8375, 6761 §6.3
+// and common unreserved internal TLDs). Includes GCP `metadata.google.internal`.
+const INTERNAL_NAME_SUFFIXES = [
+  '.internal', '.local', '.localdomain', '.home.arpa', '.lan', '.corp'
+];
+// Single-label cloud metadata aliases resolved via the DNS search path.
+const INTERNAL_NAMES = new Set(['metadata', 'instance-data']);
+
 /**
- * Validate URL against restricted locations (localhost, loopback, private and
- * link-local addresses). Blocks unconditionally — there is no escape hatch — so
- * the sanitizer fails closed for SSRF targets.
- *
- * GHSA-4mfg-r38w-w8fg FIX: previously (1) localhost was only blocked when no
- * explicit port was present, and (2) bracketed IPv6 hostnames (`[::1]`,
- * `[fe80::1]`) never matched the string checks. Both gaps allowed SSRF to
- * internal services. The hostname is now bracket-stripped and classified by
- * actual address family/range, covering IPv4-mapped IPv6 and additional
- * loopback/private encodings.
- *
- * @param {string|URL} url - The URL to validate (string or URL object)
- * @throws {Error} - If URL points to restricted location
+ * Classify a URL hostname as a restricted location. Shared by every URL entry
+ * point (GHSA-v25x-53wq-6r99 FIX: validators/url.js had its own weaker copy).
+ * @param {string} rawHostname - `URL.hostname` (brackets allowed)
+ * @returns {{hostname: string, category: (string|null)}} - 'localhost',
+ *   'loopback', 'unspecified', 'private', 'link-local', 'reserved',
+ *   'internal-name', or null
  */
-function validateURLLocation (url) {
-  let parsedUrl = url;
-
-  if (typeof url === 'string') {
-    parsedUrl = new URL(url);
-  } else if (!(url instanceof URL)) {
-    throw new Error('URL must be a string or URL object');
-  }
-
+function classifyHost (rawHostname) {
   // Normalize: strip IPv6 brackets and a trailing dot (FQDN root) before checks.
-  const hostname = parsedUrl.hostname
+  const hostname = String(rawHostname)
     .toLowerCase()
     .replace(/^\[|\]$/g, '')
     .replace(/\.$/, '');
 
-  // localhost and any *.localhost name — blocked regardless of port.
+  // localhost and any *.localhost name — regardless of port.
   if (hostname === 'localhost' || hostname.endsWith('.localhost')) {
-    throw new Error('URL points to localhost');
+    return { hostname, category: 'localhost' };
   }
 
   const ipVersion = net.isIP(hostname);
 
   // IPv4 literal — classify directly.
   if (ipVersion === 4) {
-    assertPublicIPv4(hostname.split('.').map(Number), hostname);
+    return { hostname, category: classifyIPv4(hostname.split('.').map(Number)) };
   }
 
-  // IPv6 — classify the address family, then any IPv4-mapped/compatible payload.
+  // IPv6 — classify the address family, then any embedded IPv4 payload.
   if (ipVersion === 6) {
     const canonical = expandIPv6(hostname);
-    if (canonical) {
-      // Loopback (::1) and unspecified (::).
-      if (canonical === '0000:0000:0000:0000:0000:0000:0000:0001' ||
-          canonical === '0000:0000:0000:0000:0000:0000:0000:0000') {
-        throw new Error(`URL points to private IP range: ${hostname}`);
-      }
-      const firstGroup = canonical.slice(0, 4);
-      // Link-local fe80::/10 (fe80–febf).
-      if (firstGroup >= 'fe80' && firstGroup <= 'febf') {
-        throw new Error(`URL points to link-local address: ${hostname}`);
-      }
-      // Unique-local fc00::/7 (fc00–fdff).
-      if (firstGroup >= 'fc00' && firstGroup <= 'fdff') {
-        throw new Error(`URL points to private IP range: ${hostname}`);
-      }
-      // IPv4-mapped (::ffff:a.b.c.d) and IPv4-compatible (::a.b.c.d) addresses:
-      // the first five groups are zero and the sixth is ffff or zero. Node
-      // re-encodes the trailing IPv4 as hex, so recover it from the canonical
-      // form and apply the same IPv4 range checks.
-      const groups = canonical.split(':');
-      if (groups.slice(0, 5).every(g => g === '0000') &&
-          (groups[5] === 'ffff' || groups[5] === '0000')) {
-        const hi = parseInt(groups[6], 16);
-        const lo = parseInt(groups[7], 16);
-        assertPublicIPv4([(hi >> 8) & 0xff, hi & 0xff, (lo >> 8) & 0xff, lo & 0xff], hostname);
-      }
+    if (!canonical) return { hostname, category: null };
+    if (canonical === '0000:0000:0000:0000:0000:0000:0000:0001') {
+      return { hostname, category: 'loopback' };
+    }
+    if (canonical === '0000:0000:0000:0000:0000:0000:0000:0000') {
+      return { hostname, category: 'unspecified' };
+    }
+    const groups = canonical.split(':');
+    // Link-local fe80::/10 (fe80–febf).
+    if (groups[0] >= 'fe80' && groups[0] <= 'febf') {
+      return { hostname, category: 'link-local' };
+    }
+    // Unique-local fc00::/7 and deprecated site-local fec0::/10.
+    if ((groups[0] >= 'fc00' && groups[0] <= 'fdff') ||
+        (groups[0] >= 'fec0' && groups[0] <= 'feff')) {
+      return { hostname, category: 'private' };
+    }
+    // Multicast ff00::/8.
+    if (groups[0].startsWith('ff')) {
+      return { hostname, category: 'reserved' };
     }
+    // IPv4-mapped (::ffff:a.b.c.d), IPv4-compatible (::a.b.c.d) and NAT64
+    // (64:ff9b::a.b.c.d) carry the IPv4 in the last 32 bits; 6to4
+    // (2002:aabb:ccdd::) carries it in groups 1–2. Node re-encodes the IPv4 as
+    // hex, so recover it from the canonical form and apply the IPv4 checks.
+    const zeros = (from, to) => groups.slice(from, to).every(g => g === '0000');
+    if ((zeros(0, 5) && (groups[5] === 'ffff' || groups[5] === '0000')) ||
+        (groups[0] === '0064' && groups[1] === 'ff9b' && zeros(2, 6))) {
+      return { hostname, category: classifyEmbeddedIPv4(groups[6], groups[7]) };
+    }
+    if (groups[0] === '2002') {
+      return { hostname, category: classifyEmbeddedIPv4(groups[1], groups[2]) };
+    }
+    return { hostname, category: null };
+  }
+
+  // GHSA-qvp2-8q5w-gcfp FIX: names that can only resolve internally.
+  if (INTERNAL_NAMES.has(hostname) ||
+      INTERNAL_NAME_SUFFIXES.some(suffix => hostname.endsWith(suffix))) {
+    return { hostname, category: 'internal-name' };
   }
+
+  return { hostname, category: null };
+}
+
+/**
+ * Classify an IPv4 address embedded in two IPv6 hex groups.
+ * @param {string} hiHex - Group holding octets a.b
+ * @param {string} loHex - Group holding octets c.d
+ * @returns {string|null} - Restricted category, or null if publicly routable
+ */
+function classifyEmbeddedIPv4 (hiHex, loHex) {
+  const hi = parseInt(hiHex, 16);
+  const lo = parseInt(loHex, 16);
+  return classifyIPv4([(hi >> 8) & 0xff, hi & 0xff, (lo >> 8) & 0xff, lo & 0xff]);
 }
 
 /**
- * Throw if the given IPv4 octets fall in a loopback, unspecified, RFC 1918
- * private, or link-local range. Shared by literal IPv4 and IPv4-mapped IPv6.
+ * Classify IPv4 octets; shared by literal IPv4 and embedded IPv4 in IPv6.
  * @param {number[]} o - Four octets [a, b, c, d]
- * @param {string} hostname - Original hostname, for the error message
- * @throws {Error} - If the address is not publicly routable
+ * @returns {string|null} - Restricted category, or null if publicly routable
  */
-function assertPublicIPv4 (o, hostname) {
+function classifyIPv4 (o) {
   // Loopback 127.0.0.0/8 and unspecified 0.0.0.0/8.
-  if (o[0] === 127 || o[0] === 0) {
-    throw new Error(`URL points to private IP range: ${hostname}`);
-  }
-  // RFC 1918 private ranges.
+  if (o[0] === 127) return 'loopback';
+  if (o[0] === 0) return 'unspecified';
+  // RFC 1918 private ranges and CGNAT shared space 100.64.0.0/10.
   if (o[0] === 10 ||
       (o[0] === 192 && o[1] === 168) ||
-      (o[0] === 172 && o[1] >= 16 && o[1] <= 31)) {
-    throw new Error(`URL points to private IP range: ${hostname}`);
+      (o[0] === 172 && o[1] >= 16 && o[1] <= 31) ||
+      (o[0] === 100 && o[1] >= 64 && o[1] <= 127)) {
+    return 'private';
   }
   // Link-local 169.254.0.0/16 (includes cloud metadata 169.254.169.254).
-  if (o[0] === 169 && o[1] === 254) {
+  if (o[0] === 169 && o[1] === 254) return 'link-local';
+  // IETF protocol assignments 192.0.0.0/24, benchmarking 198.18.0.0/15,
+  // multicast 224.0.0.0/4 and reserved/broadcast 240.0.0.0/4.
+  if ((o[0] === 192 && o[1] === 0 && o[2] === 0) ||
+      (o[0] === 198 && (o[1] === 18 || o[1] === 19)) ||
+      o[0] >= 224) {
+    return 'reserved';
+  }
+  return null;
+}
+
+/**
+ * Throw if a hostname is excluded by `blockedDomains` or, when `allowedDomains`
+ * is non-empty, not covered by it. An entry matches itself and its subdomains.
+ * The allowlist only narrows: it never admits a restricted `classifyHost` category.
+ * @param {string} hostname - Normalized hostname (from `classifyHost`)
+ * @param {Object} [options] - `{ blockedDomains, allowedDomains }`
+ * @throws {Error} - If the hostname is not permitted
+ */
+function assertDomainAllowed (hostname, { blockedDomains = [], allowedDomains = [] } = {}) {
+  const matches = (entry) => {
+    const domain = String(entry).toLowerCase().replace(/^\*?\./, '').replace(/\.$/, '');
+    return domain !== '' && (hostname === domain || hostname.endsWith('.' + domain));
+  };
+  if (blockedDomains.some(matches)) {
+    throw new Error(`URL host is in blockedDomains: ${hostname}`);
+  }
+  if (allowedDomains.length > 0 && !allowedDomains.some(matches)) {
+    throw new Error(`URL host is not in allowedDomains: ${hostname}`);
+  }
+}
+
+/**
+ * Validate URL against restricted locations (localhost, loopback, private,
+ * link-local, reserved addresses and internal-only names). Blocks
+ * unconditionally — there is no escape hatch — so the sanitizer fails closed
+ * for SSRF targets. String-level only: a public name that resolves to a
+ * private address needs `resolveAndValidateURL`.
+ *
+ * GHSA-4mfg-r38w-w8fg FIX: previously (1) localhost was only blocked when no
+ * explicit port was present, and (2) bracketed IPv6 hostnames (`[::1]`,
+ * `[fe80::1]`) never matched the string checks. Both gaps allowed SSRF to
+ * internal services. The hostname is now bracket-stripped and classified by
+ * actual address family/range (see `classifyHost`), covering IPv4-mapped IPv6
+ * and additional loopback/private encodings.
+ *
+ * @param {string|URL} url - The URL to validate (string or URL object)
+ * @param {Object} [options] - `{ blockedDomains, allowedDomains }`
+ * @throws {Error} - If URL points to restricted location
+ */
+function validateURLLocation (url, options = {}) {
+  let parsedUrl = url;
+
+  if (typeof url === 'string') {
+    parsedUrl = new URL(url);
+  } else if (!(url instanceof URL)) {
+    throw new Error('URL must be a string or URL object');
+  }
+
+  const { hostname, category } = classifyHost(parsedUrl.hostname);
+  if (category === 'localhost') {
+    throw new Error('URL points to localhost');
+  }
+  if (category === 'link-local') {
     throw new Error(`URL points to link-local address: ${hostname}`);
   }
+  if (category === 'reserved') {
+    throw new Error(`URL points to reserved address: ${hostname}`);
+  }
+  if (category === 'internal-name') {
+    throw new Error(`URL points to internal hostname: ${hostname}`);
+  }
+  if (category) {
+    throw new Error(`URL points to private IP range: ${hostname}`);
+  }
+  assertDomainAllowed(hostname, options);
+}
+
+/**
+ * Resolve a hostname to every address it maps to and classify each one.
+ * @param {string} hostname - Normalized, non-IP hostname
+ * @param {Function} [lookup] - `dns.promises.lookup`-compatible (for tests)
+ * @returns {Promise<Array<{address: string, family: number, category: (string|null)}>>}
+ * @throws {Error} - If resolution fails or returns no addresses
+ */
+async function resolveHost (hostname, lookup = dns.promises.lookup) {
+  const addresses = await lookup(hostname, { all: true, verbatim: true });
+  if (!addresses || addresses.length === 0) {
+    throw new Error(`DNS lookup returned no addresses for ${hostname}`);
+  }
+  return addresses.map(({ address, family }) =>
+    ({ address, family, category: classifyHost(address).category }));
+}
+
+/**
+ * GHSA-qvp2-8q5w-gcfp FIX: validate a URL and every address its hostname
+ * resolves to, so a public DNS alias for a private address (`10.0.0.5.nip.io`)
+ * is rejected. Connect to the returned `address` (e.g. via a custom `lookup`
+ * on the HTTP agent) so a later DNS change cannot redirect the request.
+ *
+ * @param {string} url - The URL to validate
+ * @param {Object} [options] - `{ allowedProtocols, blockedDomains, allowedDomains, lookup }`
+ * @returns {Promise<{url: URL, address: string, family: number}>} - Checked URL and pinned address
+ * @throws {Error} - If the URL or any resolved address is restricted
+ */
+async function resolveAndValidateURL (url, options = {}) {
+  const parsedUrl = validateURL(url, options.allowedProtocols);
+  validateURLLocation(parsedUrl, options);
+
+  const { hostname } = classifyHost(parsedUrl.hostname);
+  const family = net.isIP(hostname);
+  if (family) {
+    return { url: parsedUrl, address: hostname, family };
+  }
+
+  const resolved = await resolveHost(hostname, options.lookup);
+  const restricted = resolved.find(r => r.category);
+  if (restricted) {
+    throw new Error(`URL host ${hostname} resolves to ${restricted.category} address: ${restricted.address}`);
+  }
+  return { url: parsedUrl, address: resolved[0].address, family: resolved[0].family };
 }
 
 /**
@@ -569,9 +719,14 @@ module.exports = {
   validateFunction,
   validateRegExp,
   validateFilePath,
+  assertNotSensitivePath,
   validateFileExtension,
   validateURL,
   validateURLLocation,
+  classifyHost,
+  assertDomainAllowed,
+  resolveHost,
+  resolveAndValidateURL,
   validateCommand,
   validateOptions,
   validateRange,