@xapp/arachne-utils/lib/ssrfProtection.d.ts

/*! Copyright (c) 2025, XAPP AI */
/**
 * Check if an IP address (v4 or v6) is private or reserved
 *
 * This includes:
 * - Loopback addresses (127.0.0.1, ::1)
 * - Private network ranges (10.x.x.x, 192.168.x.x, 172.16-31.x.x)
 * - Link-local addresses (169.254.x.x, fe80::)
 * - Other reserved ranges
 *
 * @param ip - The IP address to check
 * @returns true if the IP is private/reserved, false otherwise
 */
export declare function isPrivateIP(ip: string): boolean;
/**
 * Check if a URL is safe to fetch (not vulnerable to SSRF attacks)
 *
 * This function blocks:
 * - localhost and 127.0.0.1
 * - Private IP ranges (10.x.x.x, 192.168.x.x, 172.16-31.x.x)
 * - AWS metadata endpoint (169.254.169.254)
 * - IPv6 local addresses (::1, fe80::, etc.)
 * - Cloud provider metadata endpoints
 *
 * **Security Limitation**: This function only checks the URL at the time of the call.
 * It does not protect against DNS rebinding attacks, where a malicious domain could
 * resolve to a public IP during this check but then resolve to a private IP (e.g., 127.0.0.1)
 * during the actual fetch. For high-security environments, consider implementing additional
 * DNS resolution validation or using a network-level SSRF protection solution.
 *
 * @param url - The URL to validate
 * @returns true if the URL is safe to fetch, false if it should be blocked
 *
 * @example
 * ```typescript
 * if (!isSafeURL('http://localhost/file.pdf')) {
 *   throw new Error('SSRF protection: Cannot fetch from localhost');
 * }
 * ```
 */
export declare function isSafeURL(url: string | URL): boolean;