/**
 * URL Safety Module - SSRF Protection
 *
 * Provides URL validation to prevent Server-Side Request Forgery (SSRF) attacks.
 * Blocks access to:
 * - Private IP ranges (RFC1918)
 * - Localhost and loopback addresses
 * - Link-local addresses
 * - Cloud metadata endpoints
 * - Dangerous protocols (file://, javascript:, data:, etc.)
 *
 * Security is enabled by default and can be disabled via configuration
 * for legitimate testing scenarios.
 */
/**
 * URL Safety configuration
 */
export interface UrlSafetyConfig {
    /** Enable SSRF protection (default: true) */
    enabled: boolean;
    /** Allow private IP ranges (RFC1918) - DANGEROUS if true */
    allowPrivateIPs: boolean;
    /** Allow localhost/loopback - DANGEROUS if true */
    allowLocalhost: boolean;
    /** Allow link-local addresses - DANGEROUS if true */
    allowLinkLocal: boolean;
    /** Allow cloud metadata endpoints - DANGEROUS if true */
    allowMetadataEndpoints: boolean;
    /** Additional blocked hostnames (e.g., internal services) */
    blockedHostnames: string[];
    /** Additional allowed hostnames (overrides blocks) */
    allowedHostnames: string[];
}
/**
 * Default secure configuration - blocks all dangerous URLs
 */
export declare const DEFAULT_URL_SAFETY_CONFIG: UrlSafetyConfig;
/**
 * Result of URL safety validation
 */
export interface UrlSafetyResult {
    /** Whether the URL is safe to access */
    safe: boolean;
    /** Reason for blocking (if not safe) */
    reason?: string;
    /** Category of the block */
    category?: 'private_ip' | 'localhost' | 'link_local' | 'metadata' | 'protocol' | 'blocked_hostname';
    /** The parsed URL components (if valid URL) */
    parsed?: {
        protocol: string;
        hostname: string;
        port: string;
        pathname: string;
    };
}
/**
 * URL Safety validator class
 */
export declare class UrlSafetyValidator {
    private config;
    constructor(config?: Partial<UrlSafetyConfig>);
    /**
     * Update configuration
     */
    setConfig(config: Partial<UrlSafetyConfig>): void;
    /**
     * Get current configuration
     */
    getConfig(): UrlSafetyConfig;
    /**
     * Validate a URL for safety
     */
    validate(url: string): UrlSafetyResult;
    /**
     * Validate URL and throw if unsafe
     */
    validateOrThrow(url: string): void;
}
/**
 * Custom error for URL safety violations
 */
export declare class UrlSafetyError extends Error {
    readonly category?: string;
    constructor(message: string, category?: string);
}
/**
 * Global URL safety validator instance with default secure config
 */
export declare const urlSafetyValidator: UrlSafetyValidator;
/**
 * Convenience function to validate URL
 */
export declare function validateUrl(url: string): UrlSafetyResult;
/**
 * Convenience function to validate URL and throw if unsafe
 */
export declare function validateUrlOrThrow(url: string): void;
/**
 * Configure the global URL safety validator
 */
export declare function configureUrlSafety(config: Partial<UrlSafetyConfig>): void;
/**
 * Extract domain (hostname) from a URL string
 * Returns 'unknown' for invalid URLs or errors
 */
export declare function extractDomain(url: string): string;
//# sourceMappingURL=url-safety.d.ts.map