/**
 * @module @arcis/node/validation/file
 * File upload validation and filename sanitization
 */
/** File upload validation options */
export interface ValidateFileOptions {
    /** Maximum file size in bytes. Default: 5MB */
    maxSize?: number;
    /** Allowed MIME types (e.g., ['image/jpeg', 'image/png']) */
    allowedTypes?: string[];
    /** Allowed file extensions (e.g., ['.jpg', '.png']). Includes dot. */
    allowedExtensions?: string[];
    /** Block dangerous/executable extensions. Default: true */
    blockExecutables?: boolean;
    /** Validate magic bytes match the claimed MIME type. Default: true */
    validateMagicBytes?: boolean;
    /** Block files with no extension. Default: true */
    blockNoExtension?: boolean;
    /** Block double extensions (e.g., file.php.jpg). Default: true */
    blockDoubleExtensions?: boolean;
}
/** File metadata for validation */
export interface FileInput {
    /** Original filename */
    filename: string;
    /** MIME type (as claimed by client) */
    mimetype: string;
    /** File size in bytes */
    size: number;
    /** File content buffer (for magic byte validation) */
    buffer?: Buffer;
}
/** File validation result */
export interface ValidateFileResult {
    /** Whether the file passed validation */
    valid: boolean;
    /** Validation errors (empty if valid) */
    errors: string[];
    /** Sanitized filename (safe for storage) */
    sanitizedFilename: string;
}
/**
 * Sanitize a filename for safe storage.
 *
 * Strips path traversal, null bytes, control characters, and special characters.
 * Preserves the extension and converts to a filesystem-safe name.
 *
 * @param filename - The original filename
 * @returns A sanitized filename safe for storage
 *
 * @example
 * sanitizeFilename('../../etc/passwd')          // 'etc_passwd'
 * sanitizeFilename('file<name>.jpg')            // 'filename.jpg'
 * sanitizeFilename('photo (1).jpg')             // 'photo_1.jpg'
 * sanitizeFilename('.htaccess')                 // 'htaccess'
 */
export declare function sanitizeFilename(filename: string): string;
/**
 * Validate a file upload for security.
 *
 * Checks file size, MIME type, extension, magic bytes, and dangerous patterns.
 * Returns a result with validation errors and a sanitized filename.
 *
 * @param file - File metadata and optional content
 * @param options - Validation options
 * @returns Validation result
 *
 * @example
 * const result = validateFile(
 *   { filename: 'photo.jpg', mimetype: 'image/jpeg', size: 1024, buffer },
 *   { allowedTypes: ['image/jpeg', 'image/png'], maxSize: 2 * 1024 * 1024 }
 * );
 * if (!result.valid) {
 *   return res.status(400).json({ errors: result.errors });
 * }
 * // Use result.sanitizedFilename for storage
 *
 * @example
 * // Block executables only (no whitelist)
 * const result = validateFile(file, { blockExecutables: true });
 */
export declare function validateFile(file: FileInput, options?: ValidateFileOptions): ValidateFileResult;
/**
 * Check if a file extension is considered dangerous/executable.
 *
 * @param filename - Filename or extension to check
 * @returns true if the extension is dangerous
 */
export declare function isDangerousExtension(filename: string): boolean;
//# sourceMappingURL=file.d.ts.map