@dollhousemcp/mcp-server 1.5.2 → 1.6.0

package/dist/utils/SecureDownloader.d.ts

@@ -0,0 +1,241 @@
+/**
+ * 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
+ *   }
+ * );
+ */
+/**
+ * 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;
+    constructor(options?: {
+        defaultTimeout?: number;
+        defaultMaxSize?: number;
+        tempDir?: string;
+        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 FileLockManager
+     */
+    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

package/dist/utils/SecureDownloader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SecureDownloader.d.ts","sourceRoot":"","sources":["../../src/utils/SecureDownloader.ts"],"names":[],"mappings":"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"}