ssrf-agent-guard 0.1.6 → 0.1.7

package/dist/index.cjs.js

@@ -7,12 +7,36 @@ var https = require('https');
 var isValidDomain = require('is-valid-domain');
 var ipaddr = require('ipaddr.js');
 
-const CLOUD_METADATA_HOSTS = [
+// lib/types.ts
+/**
+ * Default cloud metadata hosts to block.
+ * Includes AWS, GCP, Azure, Oracle Cloud, DigitalOcean, and Kubernetes.
+ */
+const CLOUD_METADATA_HOSTS = new Set([
+    // AWS EC2 metadata service
     '169.254.169.254',
     '169.254.169.253',
+    // GCP metadata service
     'metadata.google.internal',
+    'metadata.goog',
+    // Azure IMDS
+    '169.254.169.254',
+    '168.63.129.16',
+    // ECS task metadata (AWS Fargate)
     '169.254.170.2',
-];
+    // Kubernetes metadata
+    'kubernetes.default',
+    'kubernetes.default.svc',
+    'kubernetes.default.svc.cluster.local',
+    // Oracle Cloud
+    '169.254.169.254',
+    // DigitalOcean
+    '169.254.169.254',
+    // Alibaba Cloud
+    '100.100.100.200',
+    // Link-local for metadata
+    '169.254.0.0',
+]);
 
 // lib/utils.ts
 /**
@@ -27,87 +51,266 @@ function isIp(input) {
 function isPublicIp(ip) {
     return ipaddr.parse(ip).range() === 'unicast';
 }
+/**
+ * Extracts the TLD from a hostname.
+ * @param hostname The hostname to extract TLD from
+ * @returns The TLD or empty string if not found
+ */
+function getTLD(hostname) {
+    const parts = hostname.toLowerCase().split('.');
+    return parts.length > 0 ? parts[parts.length - 1] : '';
+}
+/**
+ * Checks if a hostname matches a domain pattern.
+ * Supports exact match and wildcard subdomain matching.
+ * @param hostname The hostname to check
+ * @param pattern The domain pattern (e.g., 'example.com' or '*.example.com')
+ */
+function matchesDomain(hostname, pattern) {
+    const normalizedHost = hostname.toLowerCase();
+    const normalizedPattern = pattern.toLowerCase();
+    // Exact match
+    if (normalizedHost === normalizedPattern) {
+        return true;
+    }
+    // Wildcard match (*.example.com matches sub.example.com)
+    if (normalizedPattern.startsWith('*.')) {
+        const baseDomain = normalizedPattern.slice(2);
+        return normalizedHost.endsWith('.' + baseDomain) || normalizedHost === baseDomain;
+    }
+    // Subdomain match (example.com matches sub.example.com)
+    return normalizedHost.endsWith('.' + normalizedPattern);
+}
+/**
+ * Checks if a hostname matches any domain in a list.
+ */
+function matchesAnyDomain(hostname, domains) {
+    return domains.some(domain => matchesDomain(hostname, domain));
+}
+/**
+ * Validates a host against policy options.
+ * @param hostname The hostname to validate
+ * @param policy The policy options
+ * @returns ValidationResult with safe status and reason if blocked
+ */
+function validatePolicy(hostname, policy) {
+    if (!policy) {
+        return { safe: true };
+    }
+    // Check allowDomains first (explicit allowlist takes precedence)
+    if (policy.allowDomains && policy.allowDomains.length > 0) {
+        if (matchesAnyDomain(hostname, policy.allowDomains)) {
+            return { safe: true };
+        }
+        // If allowDomains is specified but host doesn't match, it's not allowed
+        return { safe: false, reason: 'not_allowed_domain' };
+    }
+    // Check denyDomains
+    if (policy.denyDomains && policy.denyDomains.length > 0) {
+        if (matchesAnyDomain(hostname, policy.denyDomains)) {
+            return { safe: false, reason: 'denied_domain' };
+        }
+    }
+    // Check denyTLD
+    if (policy.denyTLD && policy.denyTLD.length > 0) {
+        const tld = getTLD(hostname);
+        if (policy.denyTLD.map(t => t.toLowerCase()).includes(tld)) {
+            return { safe: false, reason: 'denied_tld' };
+        }
+    }
+    return { safe: true };
+}
+/**
+ * Checks if a hostname is a cloud metadata endpoint.
+ * @param hostname The hostname to check
+ * @param customHosts Additional custom metadata hosts to check
+ */
+function isCloudMetadata(hostname, customHosts) {
+    if (CLOUD_METADATA_HOSTS.has(hostname)) {
+        return true;
+    }
+    if (customHosts && customHosts.includes(hostname)) {
+        return true;
+    }
+    return false;
+}
 /**
  * High-level validation for hostnames (domains + public IPs).
+ * Returns detailed validation result with reason for blocking.
+ *
+ * @param hostname The hostname or IP to validate
+ * @param options Configuration options including policy and metadata settings
+ * @returns ValidationResult with safe status and optional reason
  */
-function isSafeHost(hostname, isValidDomainOptions) {
+function validateHost(hostname, options) {
+    const blockCloudMetadata = options?.blockCloudMetadata !== false; // default true
     // Block cloud metadata IP/domains
-    if (CLOUD_METADATA_HOSTS.indexOf(hostname) !== -1)
-        return false;
+    if (blockCloudMetadata && isCloudMetadata(hostname, options?.metadataHosts)) {
+        return { safe: false, reason: 'cloud_metadata' };
+    }
+    // Check policy-based rules (only for non-IP hostnames)
+    if (!isIp(hostname)) {
+        const policyResult = validatePolicy(hostname, options?.policy);
+        if (!policyResult.safe) {
+            return policyResult;
+        }
+    }
     // Case 1: IP address
-    if (isIp(hostname))
-        return isPublicIp(hostname);
-    // Case 2: Domain name
-    return isValidDomain(hostname, {
-        allowUnicode: false,
-        subdomain: true,
-        ...isValidDomainOptions,
-    });
+    if (isIp(hostname)) {
+        if (!isPublicIp(hostname)) {
+            return { safe: false, reason: 'private_ip' };
+        }
+        return { safe: true };
+    }
+    // Case 2: Domain name validation
+    if (!isValidDomain(hostname, { allowUnicode: false, subdomain: true })) {
+        return { safe: false, reason: 'invalid_domain' };
+    }
+    return { safe: true };
 }
 
-// Instantiate the default agents
-const httpAgent = new http.Agent();
-const httpsAgent = new https.Agent();
+// WeakMap to track patched agents without modifying the agent object
+const patchedAgents = new WeakMap();
 /**
- * Determines the correct Agent instance based on the input.
- * @param url The URL or another input to determine the agent type.
- * @returns The appropriate HttpAgent or HttpsAgent instance.
+ * Determines the correct Agent instance based on the protocol.
+ * @param url The URL or protocol hint to determine the agent type.
+ * @param options Optional options that may contain protocol hint.
+ * @returns A new HttpAgent or HttpsAgent instance.
  */
-const getAgent = (url) => {
-    // If it's a string, check if it implies HTTPS
-    if (typeof url === 'string' && url.startsWith('https')) {
-        return httpsAgent;
+const createAgent = (url, options) => {
+    const protocol = options?.protocol || url;
+    if (typeof protocol === 'string' && protocol.startsWith('https')) {
+        return new https.Agent();
     }
-    // Default to HTTP agent
-    return httpAgent;
+    return new http.Agent();
 };
-// Define a Symbol for a unique property to prevent double-patching the agent.
-const CREATE_CONNECTION = Symbol('createConnection');
 /**
- * Patches an http.Agent or https.Agent to enforce an HOST/IP check
- * before and after a DNS lookup.
+ * Creates a BlockEvent for logging.
+ */
+function createBlockEvent(url, reason, ip, hostname) {
+    return {
+        url,
+        reason,
+        ip,
+        hostname,
+        timestamp: Date.now(),
+    };
+}
+/**
+ * Handles a block action based on mode.
+ * @returns true if the request should be blocked, false if allowed
+ */
+function handleBlock(options, url, reason, ip, hostname) {
+    const mode = options?.mode || 'block';
+    const logger = options?.logger;
+    // Create event for logging
+    const event = createBlockEvent(url, reason, ip, hostname);
+    // Log based on mode
+    if (logger) {
+        if (mode === 'block') {
+            logger('error', `SSRF blocked: ${reason}`, event);
+        }
+        else if (mode === 'report') {
+            logger('warn', `SSRF detected (report mode): ${reason}`, event);
+        }
+    }
+    // Return whether to actually block
+    return mode === 'block';
+}
+/**
+ * Gets a human-readable error message for a block reason.
+ */
+function getErrorMessage(reason, target) {
+    switch (reason) {
+        case 'private_ip':
+            return `Private IP address ${target} is not allowed`;
+        case 'cloud_metadata':
+            return `Cloud metadata endpoint ${target} is not allowed`;
+        case 'invalid_domain':
+            return `Invalid domain ${target}`;
+        case 'dns_rebinding':
+            return `DNS rebinding attack detected for ${target}`;
+        case 'denied_domain':
+            return `Domain ${target} is denied by policy`;
+        case 'denied_tld':
+            return `TLD of ${target} is denied by policy`;
+        case 'not_allowed_domain':
+            return `Domain ${target} is not in the allowed list`;
+        default:
+            return `Request to ${target} is not allowed`;
+    }
+}
+/**
+ * Patches an http.Agent or https.Agent to enforce HOST/IP checks
+ * before and after DNS lookup, with full policy support.
  *
- * @param url The URL or another input to determine the agent type.
- * @param isValidDomainOptions Options for validating domain names.
+ * @param url The URL or protocol hint to determine the agent type.
+ * @param options Configuration options for SSRF protection.
  * @returns The patched CustomAgent instance.
  */
-const ssrfAgentGuard = function (url, isValidDomainOptions) {
-    const finalAgent = getAgent(url);
-    // Prevent patching the agent multiple times
-    if (finalAgent[CREATE_CONNECTION]) {
+function ssrfAgentGuard(url, options) {
+    // Create a new agent for each call to avoid shared state issues
+    const finalAgent = createAgent(url, options);
+    // If mode is 'allow', return unpatched agent
+    if (options?.mode === 'allow') {
         return finalAgent;
     }
-    finalAgent[CREATE_CONNECTION] = true;
-    // The original createConnection function from the Agent
-    const createConnection = finalAgent.createConnection;
-    // Patch the createConnection method on the agent
-    finalAgent.createConnection = function (options, fn) {
-        const { host: address } = options;
+    // Check if already patched (shouldn't happen with new agents, but safety check)
+    if (patchedAgents.get(finalAgent)) {
+        return finalAgent;
+    }
+    patchedAgents.set(finalAgent, true);
+    // Store original createConnection
+    const originalCreateConnection = finalAgent.createConnection;
+    // Whether to detect DNS rebinding (default: true)
+    const detectDnsRebinding = options?.detectDnsRebinding !== false;
+    // Patch createConnection
+    finalAgent.createConnection = function (connectionOptions, callback) {
+        const hostname = connectionOptions.host || '';
         // --- 1. Pre-DNS Check (Host/Address Check) ---
-        // If the 'host' option is an IP address, check it immediately.
-        // If it's a hostname, this check will usually pass (via defaultIpChecker).
-        if (address && !isSafeHost(address, isValidDomainOptions)) {
-            throw new Error(`DNS lookup ${address} is not allowed.`);
+        const preCheckResult = validateHost(hostname, options);
+        if (!preCheckResult.safe && preCheckResult.reason) {
+            const shouldBlock = handleBlock(options, hostname, preCheckResult.reason, undefined, hostname);
+            if (shouldBlock) {
+                throw new Error(getErrorMessage(preCheckResult.reason, hostname));
+            }
         }
         // Call the original createConnection
-        const client = createConnection.call(this, options, fn);
+        const client = originalCreateConnection.call(this, connectionOptions, callback);
         // --- 2. Post-DNS Check (Lookup Event Check) ---
-        // The 'lookup' event fires after the DNS lookup is complete
-        // and provides the resolved IP address.
-        client?.on('lookup', (err, resolvedAddress) => {
-            // Ensure resolvedAddress is a string for the check (it's typically a string for simple lookups)
-            const ipToCheck = Array.isArray(resolvedAddress) ? resolvedAddress[0] : resolvedAddress;
-            // If there was an error in lookup, or if the resolved IP is allowed, do nothing.
-            if (err || isSafeHost(ipToCheck, isValidDomainOptions)) {
-                return false;
-            }
-            // If the resolved IP is NOT allowed (e.g., a private IP), destroy the connection.
-            return client?.destroy(new Error(`DNS lookup ${ipToCheck} is not allowed.`));
-        });
+        // Only add listener if DNS rebinding detection is enabled
+        if (detectDnsRebinding && client) {
+            client.on('lookup', (err, resolvedAddress) => {
+                if (err) {
+                    return; // DNS lookup failed, let it propagate naturally
+                }
+                // Check all resolved IPs (handle both single IP and array)
+                const ipsToCheck = Array.isArray(resolvedAddress) ? resolvedAddress : [resolvedAddress];
+                for (const ip of ipsToCheck) {
+                    if (!ip)
+                        continue;
+                    const postCheckResult = validateHost(ip, options);
+                    if (!postCheckResult.safe && postCheckResult.reason) {
+                        // For post-DNS check, the reason is DNS rebinding
+                        const reason = 'dns_rebinding';
+                        const shouldBlock = handleBlock(options, hostname, reason, ip, hostname);
+                        if (shouldBlock) {
+                            client.destroy(new Error(getErrorMessage(reason, `${hostname} -> ${ip}`)));
+                            return;
+                        }
+                    }
+                }
+            });
+        }
         return client;
     };
     return finalAgent;
-};
+}
 module.exports = ssrfAgentGuard;
 
 exports.default = ssrfAgentGuard;
+exports.getTLD = getTLD;
+exports.isCloudMetadata = isCloudMetadata;
+exports.matchesDomain = matchesDomain;
+exports.validateHost = validateHost;
+exports.validatePolicy = validatePolicy;

package/dist/index.d.ts

@@ -1,14 +1,16 @@
 import { Agent as HttpAgent } from 'http';
 import { Agent as HttpsAgent } from 'https';
-import { IsValidDomainOptions } from './lib/types';
+import { Options } from './lib/types';
+export { Options, PolicyOptions, BlockEvent, BlockReason, ValidationResult } from './lib/types';
+export { validateHost, isCloudMetadata, validatePolicy, matchesDomain, getTLD } from './lib/utils';
 type CustomAgent = HttpAgent | HttpsAgent;
 /**
- * Patches an http.Agent or https.Agent to enforce an HOST/IP check
- * before and after a DNS lookup.
+ * Patches an http.Agent or https.Agent to enforce HOST/IP checks
+ * before and after DNS lookup, with full policy support.
  *
- * @param url The URL or another input to determine the agent type.
- * @param isValidDomainOptions Options for validating domain names.
+ * @param url The URL or protocol hint to determine the agent type.
+ * @param options Configuration options for SSRF protection.
  * @returns The patched CustomAgent instance.
  */
-declare const ssrfAgentGuard: (url: string, isValidDomainOptions?: IsValidDomainOptions) => CustomAgent;
+declare function ssrfAgentGuard(url: string, options?: Options): CustomAgent;
 export default ssrfAgentGuard;

package/dist/index.esm.js

@@ -1,14 +1,38 @@
-import { Agent } from 'http';
-import { Agent as Agent$1 } from 'https';
+import { Agent as Agent$1 } from 'http';
+import { Agent } from 'https';
 import isValidDomain from 'is-valid-domain';
 import ipaddr from 'ipaddr.js';
 
-const CLOUD_METADATA_HOSTS = [
+// lib/types.ts
+/**
+ * Default cloud metadata hosts to block.
+ * Includes AWS, GCP, Azure, Oracle Cloud, DigitalOcean, and Kubernetes.
+ */
+const CLOUD_METADATA_HOSTS = new Set([
+    // AWS EC2 metadata service
     '169.254.169.254',
     '169.254.169.253',
+    // GCP metadata service
     'metadata.google.internal',
+    'metadata.goog',
+    // Azure IMDS
+    '169.254.169.254',
+    '168.63.129.16',
+    // ECS task metadata (AWS Fargate)
     '169.254.170.2',
-];
+    // Kubernetes metadata
+    'kubernetes.default',
+    'kubernetes.default.svc',
+    'kubernetes.default.svc.cluster.local',
+    // Oracle Cloud
+    '169.254.169.254',
+    // DigitalOcean
+    '169.254.169.254',
+    // Alibaba Cloud
+    '100.100.100.200',
+    // Link-local for metadata
+    '169.254.0.0',
+]);
 
 // lib/utils.ts
 /**
@@ -23,87 +47,261 @@ function isIp(input) {
 function isPublicIp(ip) {
     return ipaddr.parse(ip).range() === 'unicast';
 }
+/**
+ * Extracts the TLD from a hostname.
+ * @param hostname The hostname to extract TLD from
+ * @returns The TLD or empty string if not found
+ */
+function getTLD(hostname) {
+    const parts = hostname.toLowerCase().split('.');
+    return parts.length > 0 ? parts[parts.length - 1] : '';
+}
+/**
+ * Checks if a hostname matches a domain pattern.
+ * Supports exact match and wildcard subdomain matching.
+ * @param hostname The hostname to check
+ * @param pattern The domain pattern (e.g., 'example.com' or '*.example.com')
+ */
+function matchesDomain(hostname, pattern) {
+    const normalizedHost = hostname.toLowerCase();
+    const normalizedPattern = pattern.toLowerCase();
+    // Exact match
+    if (normalizedHost === normalizedPattern) {
+        return true;
+    }
+    // Wildcard match (*.example.com matches sub.example.com)
+    if (normalizedPattern.startsWith('*.')) {
+        const baseDomain = normalizedPattern.slice(2);
+        return normalizedHost.endsWith('.' + baseDomain) || normalizedHost === baseDomain;
+    }
+    // Subdomain match (example.com matches sub.example.com)
+    return normalizedHost.endsWith('.' + normalizedPattern);
+}
+/**
+ * Checks if a hostname matches any domain in a list.
+ */
+function matchesAnyDomain(hostname, domains) {
+    return domains.some(domain => matchesDomain(hostname, domain));
+}
+/**
+ * Validates a host against policy options.
+ * @param hostname The hostname to validate
+ * @param policy The policy options
+ * @returns ValidationResult with safe status and reason if blocked
+ */
+function validatePolicy(hostname, policy) {
+    if (!policy) {
+        return { safe: true };
+    }
+    // Check allowDomains first (explicit allowlist takes precedence)
+    if (policy.allowDomains && policy.allowDomains.length > 0) {
+        if (matchesAnyDomain(hostname, policy.allowDomains)) {
+            return { safe: true };
+        }
+        // If allowDomains is specified but host doesn't match, it's not allowed
+        return { safe: false, reason: 'not_allowed_domain' };
+    }
+    // Check denyDomains
+    if (policy.denyDomains && policy.denyDomains.length > 0) {
+        if (matchesAnyDomain(hostname, policy.denyDomains)) {
+            return { safe: false, reason: 'denied_domain' };
+        }
+    }
+    // Check denyTLD
+    if (policy.denyTLD && policy.denyTLD.length > 0) {
+        const tld = getTLD(hostname);
+        if (policy.denyTLD.map(t => t.toLowerCase()).includes(tld)) {
+            return { safe: false, reason: 'denied_tld' };
+        }
+    }
+    return { safe: true };
+}
+/**
+ * Checks if a hostname is a cloud metadata endpoint.
+ * @param hostname The hostname to check
+ * @param customHosts Additional custom metadata hosts to check
+ */
+function isCloudMetadata(hostname, customHosts) {
+    if (CLOUD_METADATA_HOSTS.has(hostname)) {
+        return true;
+    }
+    if (customHosts && customHosts.includes(hostname)) {
+        return true;
+    }
+    return false;
+}
 /**
  * High-level validation for hostnames (domains + public IPs).
+ * Returns detailed validation result with reason for blocking.
+ *
+ * @param hostname The hostname or IP to validate
+ * @param options Configuration options including policy and metadata settings
+ * @returns ValidationResult with safe status and optional reason
  */
-function isSafeHost(hostname, isValidDomainOptions) {
+function validateHost(hostname, options) {
+    const blockCloudMetadata = options?.blockCloudMetadata !== false; // default true
     // Block cloud metadata IP/domains
-    if (CLOUD_METADATA_HOSTS.indexOf(hostname) !== -1)
-        return false;
+    if (blockCloudMetadata && isCloudMetadata(hostname, options?.metadataHosts)) {
+        return { safe: false, reason: 'cloud_metadata' };
+    }
+    // Check policy-based rules (only for non-IP hostnames)
+    if (!isIp(hostname)) {
+        const policyResult = validatePolicy(hostname, options?.policy);
+        if (!policyResult.safe) {
+            return policyResult;
+        }
+    }
     // Case 1: IP address
-    if (isIp(hostname))
-        return isPublicIp(hostname);
-    // Case 2: Domain name
-    return isValidDomain(hostname, {
-        allowUnicode: false,
-        subdomain: true,
-        ...isValidDomainOptions,
-    });
+    if (isIp(hostname)) {
+        if (!isPublicIp(hostname)) {
+            return { safe: false, reason: 'private_ip' };
+        }
+        return { safe: true };
+    }
+    // Case 2: Domain name validation
+    if (!isValidDomain(hostname, { allowUnicode: false, subdomain: true })) {
+        return { safe: false, reason: 'invalid_domain' };
+    }
+    return { safe: true };
 }
 
-// Instantiate the default agents
-const httpAgent = new Agent();
-const httpsAgent = new Agent$1();
+// WeakMap to track patched agents without modifying the agent object
+const patchedAgents = new WeakMap();
 /**
- * Determines the correct Agent instance based on the input.
- * @param url The URL or another input to determine the agent type.
- * @returns The appropriate HttpAgent or HttpsAgent instance.
+ * Determines the correct Agent instance based on the protocol.
+ * @param url The URL or protocol hint to determine the agent type.
+ * @param options Optional options that may contain protocol hint.
+ * @returns A new HttpAgent or HttpsAgent instance.
  */
-const getAgent = (url) => {
-    // If it's a string, check if it implies HTTPS
-    if (typeof url === 'string' && url.startsWith('https')) {
-        return httpsAgent;
+const createAgent = (url, options) => {
+    const protocol = options?.protocol || url;
+    if (typeof protocol === 'string' && protocol.startsWith('https')) {
+        return new Agent();
     }
-    // Default to HTTP agent
-    return httpAgent;
+    return new Agent$1();
 };
-// Define a Symbol for a unique property to prevent double-patching the agent.
-const CREATE_CONNECTION = Symbol('createConnection');
 /**
- * Patches an http.Agent or https.Agent to enforce an HOST/IP check
- * before and after a DNS lookup.
+ * Creates a BlockEvent for logging.
+ */
+function createBlockEvent(url, reason, ip, hostname) {
+    return {
+        url,
+        reason,
+        ip,
+        hostname,
+        timestamp: Date.now(),
+    };
+}
+/**
+ * Handles a block action based on mode.
+ * @returns true if the request should be blocked, false if allowed
+ */
+function handleBlock(options, url, reason, ip, hostname) {
+    const mode = options?.mode || 'block';
+    const logger = options?.logger;
+    // Create event for logging
+    const event = createBlockEvent(url, reason, ip, hostname);
+    // Log based on mode
+    if (logger) {
+        if (mode === 'block') {
+            logger('error', `SSRF blocked: ${reason}`, event);
+        }
+        else if (mode === 'report') {
+            logger('warn', `SSRF detected (report mode): ${reason}`, event);
+        }
+    }
+    // Return whether to actually block
+    return mode === 'block';
+}
+/**
+ * Gets a human-readable error message for a block reason.
+ */
+function getErrorMessage(reason, target) {
+    switch (reason) {
+        case 'private_ip':
+            return `Private IP address ${target} is not allowed`;
+        case 'cloud_metadata':
+            return `Cloud metadata endpoint ${target} is not allowed`;
+        case 'invalid_domain':
+            return `Invalid domain ${target}`;
+        case 'dns_rebinding':
+            return `DNS rebinding attack detected for ${target}`;
+        case 'denied_domain':
+            return `Domain ${target} is denied by policy`;
+        case 'denied_tld':
+            return `TLD of ${target} is denied by policy`;
+        case 'not_allowed_domain':
+            return `Domain ${target} is not in the allowed list`;
+        default:
+            return `Request to ${target} is not allowed`;
+    }
+}
+/**
+ * Patches an http.Agent or https.Agent to enforce HOST/IP checks
+ * before and after DNS lookup, with full policy support.
  *
- * @param url The URL or another input to determine the agent type.
- * @param isValidDomainOptions Options for validating domain names.
+ * @param url The URL or protocol hint to determine the agent type.
+ * @param options Configuration options for SSRF protection.
  * @returns The patched CustomAgent instance.
  */
-const ssrfAgentGuard = function (url, isValidDomainOptions) {
-    const finalAgent = getAgent(url);
-    // Prevent patching the agent multiple times
-    if (finalAgent[CREATE_CONNECTION]) {
+function ssrfAgentGuard(url, options) {
+    // Create a new agent for each call to avoid shared state issues
+    const finalAgent = createAgent(url, options);
+    // If mode is 'allow', return unpatched agent
+    if (options?.mode === 'allow') {
         return finalAgent;
     }
-    finalAgent[CREATE_CONNECTION] = true;
-    // The original createConnection function from the Agent
-    const createConnection = finalAgent.createConnection;
-    // Patch the createConnection method on the agent
-    finalAgent.createConnection = function (options, fn) {
-        const { host: address } = options;
+    // Check if already patched (shouldn't happen with new agents, but safety check)
+    if (patchedAgents.get(finalAgent)) {
+        return finalAgent;
+    }
+    patchedAgents.set(finalAgent, true);
+    // Store original createConnection
+    const originalCreateConnection = finalAgent.createConnection;
+    // Whether to detect DNS rebinding (default: true)
+    const detectDnsRebinding = options?.detectDnsRebinding !== false;
+    // Patch createConnection
+    finalAgent.createConnection = function (connectionOptions, callback) {
+        const hostname = connectionOptions.host || '';
         // --- 1. Pre-DNS Check (Host/Address Check) ---
-        // If the 'host' option is an IP address, check it immediately.
-        // If it's a hostname, this check will usually pass (via defaultIpChecker).
-        if (address && !isSafeHost(address, isValidDomainOptions)) {
-            throw new Error(`DNS lookup ${address} is not allowed.`);
+        const preCheckResult = validateHost(hostname, options);
+        if (!preCheckResult.safe && preCheckResult.reason) {
+            const shouldBlock = handleBlock(options, hostname, preCheckResult.reason, undefined, hostname);
+            if (shouldBlock) {
+                throw new Error(getErrorMessage(preCheckResult.reason, hostname));
+            }
         }
         // Call the original createConnection
-        const client = createConnection.call(this, options, fn);
+        const client = originalCreateConnection.call(this, connectionOptions, callback);
         // --- 2. Post-DNS Check (Lookup Event Check) ---
-        // The 'lookup' event fires after the DNS lookup is complete
-        // and provides the resolved IP address.
-        client?.on('lookup', (err, resolvedAddress) => {
-            // Ensure resolvedAddress is a string for the check (it's typically a string for simple lookups)
-            const ipToCheck = Array.isArray(resolvedAddress) ? resolvedAddress[0] : resolvedAddress;
-            // If there was an error in lookup, or if the resolved IP is allowed, do nothing.
-            if (err || isSafeHost(ipToCheck, isValidDomainOptions)) {
-                return false;
-            }
-            // If the resolved IP is NOT allowed (e.g., a private IP), destroy the connection.
-            return client?.destroy(new Error(`DNS lookup ${ipToCheck} is not allowed.`));
-        });
+        // Only add listener if DNS rebinding detection is enabled
+        if (detectDnsRebinding && client) {
+            client.on('lookup', (err, resolvedAddress) => {
+                if (err) {
+                    return; // DNS lookup failed, let it propagate naturally
+                }
+                // Check all resolved IPs (handle both single IP and array)
+                const ipsToCheck = Array.isArray(resolvedAddress) ? resolvedAddress : [resolvedAddress];
+                for (const ip of ipsToCheck) {
+                    if (!ip)
+                        continue;
+                    const postCheckResult = validateHost(ip, options);
+                    if (!postCheckResult.safe && postCheckResult.reason) {
+                        // For post-DNS check, the reason is DNS rebinding
+                        const reason = 'dns_rebinding';
+                        const shouldBlock = handleBlock(options, hostname, reason, ip, hostname);
+                        if (shouldBlock) {
+                            client.destroy(new Error(getErrorMessage(reason, `${hostname} -> ${ip}`)));
+                            return;
+                        }
+                    }
+                }
+            });
+        }
         return client;
     };
     return finalAgent;
-};
+}
 module.exports = ssrfAgentGuard;
 
-export { ssrfAgentGuard as default };
+export { ssrfAgentGuard as default, getTLD, isCloudMetadata, matchesDomain, validateHost, validatePolicy };

package/dist/lib/types.d.ts

@@ -1,27 +1,66 @@
+/**
+ * Block reasons for SSRF detection
+ */
+export type BlockReason = 'private_ip' | 'cloud_metadata' | 'invalid_domain' | 'dns_rebinding' | 'denied_domain' | 'denied_tld' | 'not_allowed_domain';
+/**
+ * Main configuration options for ssrf-agent-guard
+ */
 export interface Options {
-    protocal?: string;
+    /** Protocol hint (http or https) - typically inferred from URL */
+    protocol?: string;
+    /** Custom cloud metadata hosts to block (merged with defaults) */
     metadataHosts?: string[];
+    /**
+     * Operation mode:
+     * - 'block': Block and throw error (default)
+     * - 'report': Log but allow the request
+     * - 'allow': Disable all checks (for debugging)
+     */
     mode?: 'block' | 'report' | 'allow';
+    /** Domain/TLD policy options */
     policy?: PolicyOptions;
+    /** Whether to block cloud metadata endpoints (default: true) */
     blockCloudMetadata?: boolean;
+    /** Whether to detect DNS rebinding attacks (default: true) */
     detectDnsRebinding?: boolean;
-    logger?: (level: 'info' | 'warn' | 'error', msg: string, meta?: any) => void;
+    /** Logger callback for blocked requests and warnings */
+    logger?: (level: 'info' | 'warn' | 'error', msg: string, meta?: BlockEvent) => void;
 }
+/**
+ * Policy options for domain-based filtering
+ */
 export interface PolicyOptions {
+    /** Domains explicitly allowed (bypasses other checks) */
     allowDomains?: string[];
+    /** Domains explicitly denied */
     denyDomains?: string[];
+    /** Top-level domains to deny (e.g., ['local', 'internal']) */
     denyTLD?: string[];
 }
+/**
+ * Event data passed to logger when a request is blocked or flagged
+ */
 export interface BlockEvent {
+    /** The original URL or hostname */
     url: string;
-    reason: string;
+    /** The reason for blocking */
+    reason: BlockReason;
+    /** The resolved IP address (if available) */
     ip?: string;
+    /** Timestamp of the event */
     timestamp: number;
+    /** The original hostname before DNS resolution */
+    hostname?: string;
 }
-export interface IsValidDomainOptions {
-    subdomain?: boolean;
-    wildcard?: boolean;
-    allowUnicode?: boolean;
-    topLevel?: boolean;
+/**
+ * Default cloud metadata hosts to block.
+ * Includes AWS, GCP, Azure, Oracle Cloud, DigitalOcean, and Kubernetes.
+ */
+export declare const CLOUD_METADATA_HOSTS: Set<string>;
+/**
+ * Result of host validation check
+ */
+export interface ValidationResult {
+    safe: boolean;
+    reason?: BlockReason;
 }
-export declare const CLOUD_METADATA_HOSTS: string[];

package/dist/lib/utils.d.ts

@@ -1,5 +1,44 @@
-import { IsValidDomainOptions } from './types';
+import { Options, PolicyOptions, ValidationResult } from './types';
+/**
+ * Checks if the input is an IP address (v4/v6).
+ */
+export declare function isIp(input: string): boolean;
+/**
+ * Returns true for valid public unicast IP addresses.
+ */
+export declare function isPublicIp(ip: string): boolean;
+/**
+ * Extracts the TLD from a hostname.
+ * @param hostname The hostname to extract TLD from
+ * @returns The TLD or empty string if not found
+ */
+export declare function getTLD(hostname: string): string;
+/**
+ * Checks if a hostname matches a domain pattern.
+ * Supports exact match and wildcard subdomain matching.
+ * @param hostname The hostname to check
+ * @param pattern The domain pattern (e.g., 'example.com' or '*.example.com')
+ */
+export declare function matchesDomain(hostname: string, pattern: string): boolean;
+/**
+ * Validates a host against policy options.
+ * @param hostname The hostname to validate
+ * @param policy The policy options
+ * @returns ValidationResult with safe status and reason if blocked
+ */
+export declare function validatePolicy(hostname: string, policy?: PolicyOptions): ValidationResult;
+/**
+ * Checks if a hostname is a cloud metadata endpoint.
+ * @param hostname The hostname to check
+ * @param customHosts Additional custom metadata hosts to check
+ */
+export declare function isCloudMetadata(hostname: string, customHosts?: string[]): boolean;
 /**
  * High-level validation for hostnames (domains + public IPs).
+ * Returns detailed validation result with reason for blocking.
+ *
+ * @param hostname The hostname or IP to validate
+ * @param options Configuration options including policy and metadata settings
+ * @returns ValidationResult with safe status and optional reason
  */
-export declare function isSafeHost(hostname: string, isValidDomainOptions?: IsValidDomainOptions): boolean;
+export declare function validateHost(hostname: string, options?: Options): ValidationResult;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ssrf-agent-guard",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "A TypeScript SSRF protection library for Node.js (express/axios) with advanced policies, DNS rebinding detection and cloud metadata protection.",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",