/**
 * Secure HTTP Client Wrapper
 *
 * Provides SSRF (Server-Side Request Forgery) protection for all external HTTP requests.
 * This module should be used instead of direct fetch() calls when making requests to
 * user-provided or configurable URLs.
 *
 * Security features:
 * - URL scheme validation (HTTPS only in production)
 * - Private IP range blocking (RFC 1918, RFC 5737, RFC 6598)
 * - Link-local address blocking (169.254.x.x)
 * - Localhost and internal DNS pattern blocking
 * - URL allowlist for known external services
 * - Request timeout limits
 * - DNS resolution validation at request time
 * - Comprehensive audit logging
 */
export interface SecureFetchConfig {
    /**
     * Allow HTTP in addition to HTTPS.
     * Should only be true in development environments.
     * Default: false (HTTPS only)
     */
    allowHttp?: boolean;
    /**
     * Request timeout in milliseconds.
     * Default: 10000 (10 seconds)
     */
    timeoutMs?: number;
    /**
     * List of allowed domains for this request.
     * If provided, only these domains are allowed.
     * If empty/undefined, allowlist is not enforced.
     */
    allowedDomains?: string[];
    /**
     * Additional blocked domains (beyond the default internal patterns).
     */
    blockedDomains?: string[];
    /**
     * Skip DNS resolution check (use with caution).
     * Only set this if you've already validated the URL.
     * Default: false
     */
    skipDnsCheck?: boolean;
    /**
     * Expected resolved IP from prior validation (DNS pinning).
     * If provided, the request will fail if DNS resolves to a different IP.
     */
    pinnedIp?: string;
    /**
     * Custom headers to include in the request.
     */
    headers?: Record<string, string>;
}
export interface UrlValidationResult {
    valid: boolean;
    reason?: string;
    resolvedIp?: string;
}
export interface SecureFetchResponse {
    ok: boolean;
    status: number;
    statusText: string;
    headers: Headers;
    text: () => Promise<string>;
    json: <T = unknown>() => Promise<T>;
    arrayBuffer: () => Promise<ArrayBuffer>;
}
/**
 * Check if an IP address is in a private/internal range.
 *
 * @param ip - The IP address to check (IPv4 or IPv6)
 * @returns true if the IP is private/internal, false otherwise
 */
export declare function isPrivateIP(ip: string): boolean;
/**
 * Check if a hostname matches internal/private patterns.
 *
 * @param hostname - The hostname to check
 * @returns true if the hostname is internal, false otherwise
 */
export declare function isInternalHostname(hostname: string): boolean;
/**
 * Validate a URL for external requests.
 *
 * Performs comprehensive validation including:
 * - URL scheme (HTTPS required in production)
 * - Hostname blocking (localhost, internal patterns)
 * - IP address validation (private ranges)
 * - Port blocking (internal service ports)
 * - Domain allowlist (if configured)
 *
 * @param url - The URL to validate
 * @param options - Validation options
 * @returns Validation result with reason if invalid
 */
export declare function validateExternalUrl(url: string, options?: {
    allowHttp?: boolean;
    allowedDomains?: string[];
    blockedDomains?: string[];
}): UrlValidationResult;
/**
 * Validate URL at runtime with DNS resolution.
 *
 * This performs actual DNS resolution to detect:
 * - DNS rebinding attacks (hostname resolves to private IP)
 * - DNS resolution failures
 * - IP pinning violations (if pinnedIp is provided)
 *
 * @param url - The URL to validate
 * @param options - Validation options including optional pinned IP
 * @returns Validation result with resolved IP
 */
export declare function validateUrlWithDns(url: string, options?: {
    allowHttp?: boolean;
    allowedDomains?: string[];
    blockedDomains?: string[];
    pinnedIp?: string;
}): Promise<UrlValidationResult>;
/**
 * Make a secure HTTP request with SSRF protection.
 *
 * This function should be used instead of direct fetch() calls when making
 * requests to user-provided or configurable URLs.
 *
 * Features:
 * - URL scheme validation (HTTPS required in production)
 * - Private IP blocking (RFC 1918, RFC 5737, RFC 6598)
 * - Internal hostname blocking
 * - DNS resolution validation
 * - DNS pinning support
 * - Request timeout
 * - Comprehensive audit logging
 *
 * @param url - The URL to fetch
 * @param options - Fetch options and security configuration
 * @returns Response object
 * @throws Error if URL validation fails or request times out
 */
export declare function secureFetch(url: string, options?: RequestInit & SecureFetchConfig): Promise<Response>;
/**
 * Convenience function for secure JSON requests.
 *
 * Makes a secure fetch request and parses the response as JSON.
 *
 * @param url - The URL to fetch
 * @param options - Fetch options and security configuration
 * @returns Parsed JSON response
 */
export declare function secureFetchJson<T = unknown>(url: string, options?: RequestInit & SecureFetchConfig): Promise<T>;
export type SecureFetchErrorCode = 'VALIDATION_FAILED' | 'TIMEOUT' | 'REQUEST_FAILED' | 'HTTP_ERROR' | 'DNS_REBINDING';
/**
 * Error thrown by secure fetch operations.
 */
export declare class SecureFetchError extends Error {
    readonly code: SecureFetchErrorCode;
    readonly details: Record<string, unknown>;
    constructor(message: string, code: SecureFetchErrorCode, details?: Record<string, unknown>);
}
/**
 * Get default secure fetch configuration from global config.
 */
export declare function getSecureFetchDefaults(): Partial<SecureFetchConfig>;
/**
 * Create a pre-configured secure fetch function with default options.
 *
 * @param defaultOptions - Default options to apply to all requests
 * @returns Configured secure fetch function
 */
export declare function createSecureFetcher(defaultOptions?: Partial<SecureFetchConfig>): (url: string, options?: RequestInit & SecureFetchConfig) => Promise<Response>;
/**
 * Default allowed domains for external services.
 * These are well-known external services that are typically safe to contact.
 */
export declare const DEFAULT_ALLOWED_DOMAINS: readonly string[];
/**
 * Get allowed domains from configuration.
 * Falls back to default allowed domains if not configured.
 */
export declare function getAllowedDomains(): string[];
//# sourceMappingURL=secure-fetch.d.ts.map