/**
 * @module @arcis/node/validation/url
 * SSRF (Server-Side Request Forgery) prevention
 *
 * Validates URLs to ensure they don't target private/internal networks,
 * localhost, cloud metadata endpoints, or use dangerous protocols.
 *
 * @example
 * import { validateUrl } from '@arcis/node';
 *
 * // Block SSRF attempts
 * validateUrl('http://169.254.169.254/latest/meta-data/')  // { safe: false, reason: 'link-local address' }
 * validateUrl('http://10.0.0.1/admin')                     // { safe: false, reason: 'private address (10.0.0.0/8)' }
 * validateUrl('http://localhost/secret')                    // { safe: false, reason: 'loopback address' }
 * validateUrl('file:///etc/passwd')                         // { safe: false, reason: 'disallowed protocol: file:' }
 *
 * // Allow safe URLs
 * validateUrl('https://api.example.com/data')               // { safe: true }
 */
/** Options for URL validation */
export interface ValidateUrlOptions {
    /** Allowed protocols. Default: ['http:', 'https:'] */
    allowedProtocols?: string[];
    /** Additional hostnames to block (e.g., internal service names) */
    blockedHosts?: string[];
    /** Additional hostnames to always allow (bypass IP checks) */
    allowedHosts?: string[];
    /** Allow localhost/loopback. Default: false */
    allowLocalhost?: boolean;
    /** Allow private/internal IPs. Default: false */
    allowPrivate?: boolean;
}
/** Result of URL validation */
export interface ValidateUrlResult {
    /** Whether the URL is safe to fetch */
    safe: boolean;
    /** Reason the URL was blocked (only set when safe=false) */
    reason?: string;
}
/**
 * Validate a URL for SSRF safety.
 *
 * Checks:
 * 1. Valid URL format
 * 2. Allowed protocol (default: http, https only)
 * 3. Not localhost/loopback (127.x.x.x, ::1, localhost)
 * 4. Not private IP (10.x, 172.16-31.x, 192.168.x)
 * 5. Not link-local (169.254.x.x — includes AWS/GCP/Azure metadata)
 * 6. Not blocked hostname
 * 7. No credentials in URL (user:pass@host)
 *
 * @param url - The URL string to validate
 * @param options - Validation options
 * @returns Validation result with safe flag and optional reason
 */
export declare function validateUrl(url: string, options?: ValidateUrlOptions): ValidateUrlResult;
/**
 * Convenience wrapper that returns true/false.
 *
 * @param url - The URL to check
 * @param options - Validation options
 * @returns true if the URL is safe to fetch
 */
export declare function isUrlSafe(url: string, options?: ValidateUrlOptions): boolean;
//# sourceMappingURL=url.d.ts.map