/**
 * SecureDownloader - Reusable utility for safe content downloads
 *
 * Implements the validate-before-write pattern with comprehensive security features:
 * - Content validation hooks (customizable validators)
 * - Atomic file operations with temp files
 * - Guaranteed cleanup on failure
 * - Memory-efficient streaming for large files
 * - Size limits to prevent DoS attacks
 * - Path validation to prevent traversal
 * - Timeout handling for network operations
 * - Content type validation
 *
 * Usage Examples:
 *
 * // Basic download with validation
 * const downloader = new SecureDownloader();
 * await downloader.downloadToFile(
 *   'https://example.com/file.md',
 *   './downloads/file.md',
 *   {
 *     validator: async (content) => ({
 *       isValid: !content.includes('malicious'),
 *       errorMessage: content.includes('malicious') ? 'Malicious content detected' : undefined
 *     }),
 *     maxSize: 1024 * 1024, // 1MB limit
 *     timeout: 30000 // 30 second timeout
 *   }
 * );
 *
 * // Download to memory with validation
 * const content = await downloader.downloadToMemory(
 *   'https://example.com/data.json',
 *   {
 *     validator: async (content) => {
 *       try {
 *         JSON.parse(content);
 *         return { isValid: true };
 *       } catch {
 *         return { isValid: false, errorMessage: 'Invalid JSON format' };
 *       }
 *     }
 *   }
 * );
 *
 * // Streaming download for large files
 * await downloader.downloadStream(
 *   'https://example.com/large-file.zip',
 *   './downloads/large-file.zip',
 *   {
 *     streamValidator: (chunk) => !chunk.includes(Buffer.from('VIRUS')),
 *     maxSize: 100 * 1024 * 1024, // 100MB limit
 *     timeout: 300000 // 5 minute timeout
 *   }
 * );
 */
import { FileLockManager } from '../security/fileLockManager.js';
import { IFileOperationsService } from '../services/FileOperationsService.js';
/**
 * Result of content validation
 */
export interface ValidationResult {
    /** Whether the content is valid and safe */
    isValid: boolean;
    /** Error message if validation failed */
    errorMessage?: string;
    /** Severity of any detected issues */
    severity?: 'low' | 'medium' | 'high' | 'critical';
    /** Additional metadata about validation */
    metadata?: Record<string, any>;
}
/**
 * Content validator function type
 */
export type ContentValidatorFunction = (content: string) => Promise<ValidationResult>;
/**
 * Stream chunk validator function type
 */
export type StreamValidator = (chunk: Uint8Array) => boolean;
/**
 * Options for download operations
 */
export interface DownloadOptions {
    /** Custom content validator function */
    validator?: ContentValidatorFunction;
    /** Maximum file size in bytes (default: SECURITY_LIMITS.MAX_FILE_SIZE) */
    maxSize?: number;
    /** Network timeout in milliseconds (default: 30000) */
    timeout?: number;
    /** Whether to use atomic file operations (default: true) */
    atomic?: boolean;
    /** Expected content type (for validation) */
    expectedContentType?: string;
    /** Custom HTTP headers */
    headers?: Record<string, string>;
    /** Expected SHA-256 checksum for integrity validation */
    expectedChecksum?: string;
}
/**
 * Options for streaming downloads
 */
export interface StreamDownloadOptions {
    /** Chunk-level validator for streaming validation */
    streamValidator?: StreamValidator;
    /** Maximum file size in bytes (default: SECURITY_LIMITS.MAX_FILE_SIZE) */
    maxSize?: number;
    /** Network timeout in milliseconds (default: 30000) */
    timeout?: number;
    /** Custom HTTP headers */
    headers?: Record<string, string>;
}
/**
 * Custom error types for different failure scenarios
 */
export declare class DownloadError extends Error {
    readonly code: string;
    readonly originalError?: Error | undefined;
    constructor(message: string, code: string, originalError?: Error | undefined);
    static networkError(message: string, originalError?: Error): DownloadError;
    static validationError(message: string): DownloadError;
    static securityError(message: string): DownloadError;
    static timeoutError(message: string): DownloadError;
    static filesystemError(message: string, originalError?: Error): DownloadError;
}
/**
 * SecureDownloader - Implements validate-before-write pattern for safe downloads
 *
 * Key Security Features:
 * 1. VALIDATE-BEFORE-WRITE: All content validation occurs before any disk operations
 * 2. ATOMIC OPERATIONS: Uses temporary files with atomic rename to prevent corruption
 * 3. GUARANTEED CLEANUP: Automatic cleanup of temporary files on any failure
 * 4. SIZE LIMITS: Prevents DoS attacks through large file downloads
 * 5. PATH VALIDATION: Prevents directory traversal attacks
 * 6. TIMEOUT PROTECTION: Prevents hanging network operations
 * 7. CONTENT VALIDATION: Extensible validation system for different content types
 */
export declare class SecureDownloader {
    private readonly defaultTimeout;
    private readonly defaultMaxSize;
    private readonly tempDir;
    private readonly globalRateLimiter;
    private readonly urlRateLimiters;
    private readonly fileLockManager;
    private readonly fileOperations;
    constructor(options?: {
        defaultTimeout?: number;
        defaultMaxSize?: number;
        tempDir?: string;
        fileLockManager?: FileLockManager;
        fileOperations?: IFileOperationsService;
        rateLimitOptions?: {
            maxRequestsPerUrl?: number;
            maxGlobalRequests?: number;
            windowMs?: number;
        };
    });
    /**
     * Download content to a file with validation
     *
     * SECURITY: Implements validate-before-write pattern:
     * 1. Download content to memory
     * 2. Validate all content
     * 3. Only then write to disk atomically
     *
     * @param url - URL to download from
     * @param destinationPath - Local file path to save to
     * @param options - Download and validation options
     */
    downloadToFile(url: string, destinationPath: string, options?: DownloadOptions): Promise<void>;
    /**
     * Download content to memory with validation
     *
     * @param url - URL to download from
     * @param options - Download and validation options
     * @returns Validated content as string
     */
    downloadToMemory(url: string, options?: DownloadOptions): Promise<string>;
    /**
     * Download large files using streaming with chunk-level validation
     *
     * @param url - URL to download from
     * @param destinationPath - Local file path to save to
     * @param options - Streaming download options
     */
    downloadStream(url: string, destinationPath: string, options?: StreamDownloadOptions): Promise<void>;
    /**
     * Validate URL format and security with Unicode normalization
     */
    private validateUrl;
    /**
     * Validate destination path for security
     */
    private validateDestinationPath;
    /**
     * Fetch content with size and timeout limits
     */
    private fetchWithLimits;
    /**
     * Validate content type if specified
     */
    private validateContentType;
    /**
     * Atomic file write using FileOperationsService
     */
    private atomicWriteFile;
    /**
     * Direct file write (non-atomic, for when atomic is disabled)
     */
    private directWriteFile;
    /**
     * Generate temporary file path for atomic operations
     */
    private getTempFilePath;
    /**
     * Check rate limits for downloads
     */
    private checkRateLimit;
    /**
     * Validate content checksum for integrity verification
     */
    private validateChecksum;
    /**
     * Create a content validator that combines multiple validators
     */
    static combineValidators(...validators: ContentValidatorFunction[]): ContentValidatorFunction;
    /**
     * Create a content validator for JSON content
     */
    static jsonValidator(): ContentValidatorFunction;
    /**
     * Create a content validator for YAML content
     */
    static yamlValidator(): ContentValidatorFunction;
    /**
     * Create a content validator for markdown content
     */
    static markdownValidator(): ContentValidatorFunction;
    /**
     * Create a content validator with size limits
     */
    static sizeValidator(maxSize: number): ContentValidatorFunction;
    /**
     * Create a content validator that checks for forbidden patterns
     */
    static patternValidator(forbiddenPatterns: RegExp[], errorMessage?: string): ContentValidatorFunction;
}
//# sourceMappingURL=SecureDownloader.d.ts.map