qa360 2.3.0 → 2.3.2

package/dist/core/upload/mime-validator.js

@@ -0,0 +1,373 @@
+/**
+ * MIME Type Validator
+ *
+ * Validates file types using:
+ * - File extension (quick check)
+ * - Magic bytes (file signature)
+ * - Server-side MIME type validation
+ *
+ * Supports comprehensive file type detection for:
+ * - Images: JPEG, PNG, GIF, WebP, SVG, ICO, AVIF, HEIC
+ * - Documents: PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX
+ * - Audio: MP3, WAV, OGG, FLAC, M4A
+ * - Video: MP4, WEBM, AVI, MOV, MKV
+ * - Archives: ZIP, RAR, 7Z, TAR, GZIP
+ * - And more...
+ */
+/**
+ * Magic bytes signatures for common file types
+ */
+const MAGIC_BYTES = {
+    // Images
+    jpeg: { signature: [0xFF, 0xD8, 0xFF], offset: 0, mime: 'image/jpeg' },
+    png: { signature: [0x89, 0x50, 0x4E, 0x47], offset: 0, mime: 'image/png' },
+    gif: { signature: [0x47, 0x49, 0x46, 0x38], offset: 0, mime: 'image/gif' },
+    webp: { signature: [0x52, 0x49, 0x46, 0x46], offset: 0, mime: 'image/webp' }, // RIFF
+    bmp: { signature: [0x42, 0x4D], offset: 0, mime: 'image/bmp' },
+    ico: { signature: [0x00, 0x00, 0x01, 0x00], offset: 0, mime: 'image/x-icon' },
+    tiff: { signature: [0x49, 0x49, 0x2A, 0x00], offset: 0, mime: 'image/tiff' }, // Little-endian
+    tiff_be: { signature: [0x4D, 0x4D, 0x00, 0x2A], offset: 0, mime: 'image/tiff' }, // Big-endian
+    avif: { signature: [0x00, 0x00, 0x00, 0x20, 0x66, 0x74, 0x79, 0x70], offset: 4, mime: 'image/avif' },
+    heic: { signature: [0x00, 0x00, 0x00, 0x1C, 0x66, 0x74, 0x79, 0x70], offset: 4, mime: 'image/heic' },
+    // Documents
+    pdf: { signature: [0x25, 0x50, 0x44, 0x46], offset: 0, mime: 'application/pdf' },
+    // DOC (OLE2)
+    doc: { signature: [0xD0, 0xCF, 0x11, 0xE0, 0xA1, 0xB1, 0x1A, 0xE1], offset: 0, mime: 'application/msword' },
+    // DOCX (ZIP-based)
+    docx: { signature: [0x50, 0x4B, 0x03, 0x04], offset: 0, mime: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' },
+    xlsx: { signature: [0x50, 0x4B, 0x03, 0x04], offset: 0, mime: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' },
+    pptx: { signature: [0x50, 0x4B, 0x03, 0x04], offset: 0, mime: 'application/vnd.openxmlformats-officedocument.presentationml.presentation' },
+    odt: { signature: [0x50, 0x4B, 0x03, 0x04], offset: 0, mime: 'application/vnd.oasis.opendocument.text' },
+    ods: { signature: [0x50, 0x4B, 0x03, 0x04], offset: 0, mime: 'application/vnd.oasis.opendocument.spreadsheet' },
+    // Audio
+    mp3: { signature: [0xFF, 0xFB], offset: 0, mime: 'audio/mpeg' },
+    mp3_2: { signature: [0xFF, 0xFA], offset: 0, mime: 'audio/mpeg' },
+    mp3_id3: { signature: [0x49, 0x44, 0x33], offset: 0, mime: 'audio/mpeg' }, // ID3
+    wav: { signature: [0x52, 0x49, 0x46, 0x46], offset: 0, mime: 'audio/wav' }, // RIFF
+    ogg: { signature: [0x4F, 0x67, 0x67, 0x53], offset: 0, mime: 'audio/ogg' },
+    flac: { signature: [0x66, 0x4C, 0x61, 0x43], offset: 0, mime: 'audio/flac' },
+    m4a: { signature: [0x00, 0x00, 0x00, 0x20, 0x66, 0x74, 0x79, 0x70], offset: 4, mime: 'audio/mp4' },
+    aiff: { signature: [0x46, 0x4F, 0x52, 0x4D], offset: 0, mime: 'audio/aiff' }, // AIFF
+    aiff_2: { signature: [0x41, 0x49, 0x46, 0x46], offset: 0, mime: 'audio/aiff' }, // AIFF
+    // Video
+    mp4: { signature: [0x00, 0x00, 0x00, 0x18, 0x66, 0x74, 0x79, 0x70], offset: 4, mime: 'video/mp4' },
+    webm: { signature: [0x1A, 0x45, 0xDF, 0xA3], offset: 0, mime: 'video/webm' },
+    avi: { signature: [0x52, 0x49, 0x46, 0x46], offset: 0, mime: 'video/x-msvideo' }, // RIFF...AVI
+    mov: { signature: [0x00, 0x00, 0x00, 0x14, 0x66, 0x74, 0x79, 0x70], offset: 4, mime: 'video/quicktime' },
+    mkv: { signature: [0x1A, 0x45, 0xDF, 0xA3], offset: 0, mime: 'video/x-matroska' },
+    flv: { signature: [0x46, 0x4C, 0x56, 0x01], offset: 0, mime: 'video/x-flv' },
+    mpeg: { signature: [0x00, 0x00, 0x01, 0xBA], offset: 0, mime: 'video/mpeg' },
+    mpeg_ps: { signature: [0x00, 0x00, 0x01, 0xB3], offset: 0, mime: 'video/mpeg' },
+    // Archives
+    zip: { signature: [0x50, 0x4B, 0x03, 0x04], offset: 0, mime: 'application/zip' },
+    zip_empty: { signature: [0x50, 0x4B, 0x05, 0x06], offset: 0, mime: 'application/zip' },
+    zip_spanned: { signature: [0x50, 0x4B, 0x07, 0x08], offset: 0, mime: 'application/zip' },
+    rar: { signature: [0x52, 0x61, 0x72, 0x21], offset: 0, mime: 'application/vnd.rar' },
+    rar_5: { signature: [0x52, 0x61, 0x72, 0x21], offset: 0, mime: 'application/x-rar-compressed' },
+    _7z: { signature: [0x37, 0x7A, 0xBC, 0xAF], offset: 0, mime: 'application/x-7z-compressed' },
+    tar: { signature: [0x75, 0x73, 0x74, 0x61, 0x72], offset: 257, mime: 'application/x-tar' },
+    gzip: { signature: [0x1F, 0x8B], offset: 0, mime: 'application/gzip' },
+    bzip2: { signature: [0x42, 0x5A, 0x68], offset: 0, mime: 'application/x-bzip2' },
+    // Other
+    json: { signature: [0x7B], offset: 0, mime: 'application/json' },
+    json_array: { signature: [0x5B], offset: 0, mime: 'application/json' },
+    xml: { signature: [0x3C, 0x3F, 0x78, 0x6D, 0x6C], offset: 0, mime: 'application/xml' },
+    html: { signature: [0x3C, 0x21, 0x44, 0x4F, 0x43, 0x54, 0x59, 0x50, 0x45], offset: 0, mime: 'text/html' },
+    html_2: { signature: [0x3C, 0x68, 0x74, 0x6D, 0x6C], offset: 0, mime: 'text/html' },
+    svg: { signature: [0x3C, 0x73, 0x76, 0x67], offset: 0, mime: 'image/svg+xml' },
+};
+/**
+ * Extension to MIME type mapping
+ */
+const EXTENSION_MIME_MAP = {
+    // Images
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    png: 'image/png',
+    gif: 'image/gif',
+    webp: 'image/webp',
+    bmp: 'image/bmp',
+    ico: 'image/x-icon',
+    svg: 'image/svg+xml',
+    tif: 'image/tiff',
+    tiff: 'image/tiff',
+    avif: 'image/avif',
+    heic: 'image/heic',
+    heif: 'image/heif',
+    // Documents
+    pdf: 'application/pdf',
+    doc: 'application/msword',
+    docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    xls: 'application/vnd.ms-excel',
+    xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    ppt: 'application/vnd.ms-powerpoint',
+    pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+    odt: 'application/vnd.oasis.opendocument.text',
+    ods: 'application/vnd.oasis.opendocument.spreadsheet',
+    odp: 'application/vnd.oasis.opendocument.presentation',
+    rtf: 'application/rtf',
+    txt: 'text/plain',
+    csv: 'text/csv',
+    md: 'text/markdown',
+    // Audio
+    mp3: 'audio/mpeg',
+    wav: 'audio/wav',
+    ogg: 'audio/ogg',
+    flac: 'audio/flac',
+    m4a: 'audio/mp4',
+    aac: 'audio/aac',
+    wma: 'audio/x-ms-wma',
+    aiff: 'audio/aiff',
+    aif: 'audio/aiff',
+    // Video
+    mp4: 'video/mp4',
+    webm: 'video/webm',
+    avi: 'video/x-msvideo',
+    mov: 'video/quicktime',
+    mkv: 'video/x-matroska',
+    flv: 'video/x-flv',
+    mpeg: 'video/mpeg',
+    mpg: 'video/mpeg',
+    m4v: 'video/mp4',
+    _3gp: 'video/3gpp',
+    _3g2: 'video/3gpp2',
+    // Archives
+    zip: 'application/zip',
+    rar: 'application/vnd.rar',
+    '7z': 'application/x-7z-compressed',
+    tar: 'application/x-tar',
+    gz: 'application/gzip',
+    bz2: 'application/x-bzip2',
+    iso: 'application/x-iso9660-image',
+    // Other
+    json: 'application/json',
+    xml: 'application/xml',
+    html: 'text/html',
+    htm: 'text/html',
+    css: 'text/css',
+    js: 'application/javascript',
+    mjs: 'application/javascript',
+    ts: 'application/typescript',
+    yaml: 'application/x-yaml',
+    yml: 'application/x-yaml',
+};
+/**
+ * MIME type validator class
+ */
+export class MimeValidator {
+    config;
+    customMappings;
+    constructor(config = {}) {
+        this.config = {
+            allowedTypes: config.allowedTypes || [],
+            allowedExtensions: config.allowedExtensions || [],
+            maxSize: config.maxSize || Infinity,
+            useMagicBytes: config.useMagicBytes !== false,
+            customMappings: config.customMappings || {},
+        };
+        this.customMappings = { ...EXTENSION_MIME_MAP, ...this.config.customMappings };
+    }
+    /**
+     * Validate a file
+     */
+    async validate(file) {
+        const errors = [];
+        const warnings = [];
+        // Get file info
+        const size = file.size;
+        const declaredType = file.type;
+        const fileName = file.name || '';
+        // Extract extension
+        const extension = this.getExtension(fileName);
+        // Detect MIME type
+        const detectedType = await this.detectMimeType(file);
+        // Validate size
+        if (size > this.config.maxSize) {
+            errors.push(`File size ${(size / 1024 / 1024).toFixed(2)}MB exceeds maximum ${(this.config.maxSize / 1024 / 1024).toFixed(2)}MB`);
+        }
+        // Validate extension
+        if (this.config.allowedExtensions.length > 0) {
+            if (!extension) {
+                errors.push('No file extension found');
+            }
+            else if (!this.isAllowedExtension(extension)) {
+                errors.push(`File extension ".${extension}" is not allowed`);
+            }
+        }
+        // Validate MIME type
+        if (this.config.allowedTypes.length > 0) {
+            if (!detectedType) {
+                errors.push('Could not detect file type');
+            }
+            else if (!this.isAllowedType(detectedType)) {
+                errors.push(`File type "${detectedType}" is not allowed`);
+            }
+        }
+        // Check for extension/MIME mismatch
+        if (extension && declaredType && this.customMappings[extension]) {
+            const expectedMime = this.customMappings[extension];
+            if (declaredType !== expectedMime && declaredType !== '') {
+                warnings.push(`Declared type "${declaredType}" doesn't match extension ".${extension}" (expected "${expectedMime}")`);
+            }
+        }
+        return {
+            valid: errors.length === 0,
+            mimeType: detectedType,
+            extension,
+            size,
+            errors: errors.length > 0 ? errors : undefined,
+            warnings: warnings.length > 0 ? warnings : undefined,
+        };
+    }
+    /**
+     * Detect MIME type using magic bytes
+     */
+    async detectMimeType(file) {
+        // First try declared type
+        if (file.type && this.isValidMimeType(file.type)) {
+            return file.type;
+        }
+        // Try extension-based detection
+        const fileName = file.name;
+        if (fileName) {
+            const ext = this.getExtension(fileName);
+            if (ext && this.customMappings[ext]) {
+                return this.customMappings[ext];
+            }
+        }
+        // Try magic bytes detection
+        if (this.config.useMagicBytes) {
+            const magicType = await this.detectFromMagicBytes(file);
+            if (magicType) {
+                return magicType;
+            }
+        }
+        return file.type || undefined;
+    }
+    /**
+     * Detect MIME type from magic bytes (file signature)
+     */
+    async detectFromMagicBytes(file) {
+        const arrayBuffer = await file.slice(0, 300).arrayBuffer();
+        const bytes = new Uint8Array(arrayBuffer);
+        for (const [name, info] of Object.entries(MAGIC_BYTES)) {
+            if (this.matchesMagicBytes(bytes, info.signature, info.offset)) {
+                return info.mime;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Check if bytes match signature at offset
+     */
+    matchesMagicBytes(bytes, signature, offset) {
+        for (let i = 0; i < signature.length; i++) {
+            if (bytes[offset + i] !== signature[i]) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Check if MIME type is allowed
+     */
+    isAllowedType(mimeType) {
+        return this.config.allowedTypes.some(allowed => {
+            if (allowed.endsWith('/*')) {
+                const prefix = allowed.slice(0, -2);
+                return mimeType.startsWith(prefix);
+            }
+            return mimeType === allowed;
+        });
+    }
+    /**
+     * Check if extension is allowed
+     */
+    isAllowedExtension(extension) {
+        const normalizedExt = extension.toLowerCase().replace(/^\./, '');
+        return this.config.allowedExtensions.some(allowed => {
+            const normalizedAllowed = allowed.toLowerCase().replace(/^\./, '');
+            return normalizedAllowed === normalizedExt;
+        });
+    }
+    /**
+     * Check if a string is a valid MIME type
+     */
+    isValidMimeType(mimeType) {
+        return /^[a-z]+\/[a-z0-9+.-]+$/i.test(mimeType);
+    }
+    /**
+     * Get file extension from filename
+     */
+    getExtension(fileName) {
+        const match = fileName.toLowerCase().match(/\.([a-z0-9]+)$/);
+        return match ? match[1] : '';
+    }
+    /**
+     * Get MIME type from extension
+     */
+    getMimeTypeFromExtension(extension) {
+        const normalizedExt = extension.toLowerCase().replace(/^\./, '');
+        return this.customMappings[normalizedExt];
+    }
+    /**
+     * Get extension from MIME type
+     */
+    getExtensionFromMimeType(mimeType) {
+        for (const [ext, mime] of Object.entries(this.customMappings)) {
+            if (mime === mimeType) {
+                return ext;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Update allowed types
+     */
+    setAllowedTypes(types) {
+        this.config.allowedTypes = types;
+    }
+    /**
+     * Update allowed extensions
+     */
+    setAllowedExtensions(extensions) {
+        this.config.allowedExtensions = extensions;
+    }
+    /**
+     * Update max size
+     */
+    setMaxSize(size) {
+        this.config.maxSize = size;
+    }
+}
+/**
+ * Create a MIME validator instance
+ */
+export function createMimeValidator(config) {
+    return new MimeValidator(config);
+}
+/**
+ * Validate a file (convenience function)
+ */
+export async function validateMimeType(file, config) {
+    const validator = new MimeValidator(config);
+    return validator.validate(file);
+}
+/**
+ * Get MIME type from extension
+ */
+export function getMimeTypeFromExtension(extension) {
+    return EXTENSION_MIME_MAP[extension.toLowerCase().replace(/^\./, '')];
+}
+/**
+ * Get extension from MIME type
+ */
+export function getExtensionFromMimeType(mimeType) {
+    for (const [ext, mime] of Object.entries(EXTENSION_MIME_MAP)) {
+        if (mime === mimeType) {
+            return ext;
+        }
+    }
+    return undefined;
+}
+export default MimeValidator;

package/dist/core/upload/presigned-uploader.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Presigned URL Uploader
+ *
+ * Handles file uploads using presigned URLs for cloud storage.
+ * Supports:
+ * - AWS S3 presigned URLs
+ * - Azure Blob Storage SAS URLs
+ * - Google Cloud Storage signed URLs
+ * - Custom presigned URL providers
+ */
+export interface PresignedUrlConfig {
+    /** URL to request presigned upload URL */
+    presignedUrlEndpoint: string;
+    /** HTTP method for presigned URL request (default: POST) */
+    method?: 'GET' | 'POST';
+    /** Headers for presigned URL request */
+    headers?: Record<string, string>;
+    /** Fields to include in presigned URL request */
+    requestFields?: Record<string, string>;
+    /** Query params for presigned URL request */
+    requestParams?: Record<string, string>;
+    /** File field name (default: 'file') */
+    fileField?: string;
+    /** Additional fields to include with upload */
+    uploadFields?: Record<string, string>;
+    /** HTTP method for upload (default: PUT for S3, POST for others) */
+    uploadMethod?: 'PUT' | 'POST';
+    /** Headers to include with upload */
+    uploadHeaders?: Record<string, string>;
+    /** Progress callback */
+    onProgress?: (progress: UploadProgress) => void;
+}
+export interface PresignedUrlResponse {
+    /** The presigned URL for upload */
+    url: string;
+    /** HTTP method to use (PUT or POST) */
+    method?: 'PUT' | 'POST';
+    /** Required headers for upload */
+    headers?: Record<string, string>;
+    /** Required fields for POST upload */
+    fields?: Record<string, string>;
+    /** File ID/key from server */
+    key?: string;
+    /** Expiration timestamp */
+    expiresAt?: number;
+}
+export interface UploadProgress {
+    /** Bytes uploaded */
+    loaded: number;
+    /** Total bytes */
+    total: number;
+    /** Percentage (0-100) */
+    percentage: number;
+}
+export interface PresignedUploadResult {
+    /** Upload success status */
+    success: boolean;
+    /** File key/ID from server */
+    key?: string;
+    /** Public URL of uploaded file (if provided) */
+    url?: string;
+    /** Server response */
+    response?: any;
+    /** Error if failed */
+    error?: string;
+}
+/**
+ * Presigned URL uploader class
+ */
+export declare class PresignedUploader {
+    private config;
+    constructor(config: PresignedUrlConfig);
+    /**
+     * Upload a file using a presigned URL
+     */
+    upload(file: File | Blob, fileName?: string): Promise<PresignedUploadResult>;
+    /**
+     * Request a presigned URL from the server
+     */
+    private requestPresignedUrl;
+    /**
+     * Upload file to the presigned URL
+     */
+    private uploadToPresignedUrl;
+    /**
+     * Upload via PUT request (S3 style)
+     */
+    private uploadViaPut;
+    /**
+     * Upload via POST request (multipart/form-data style)
+     */
+    private uploadViaPost;
+    /**
+     * Upload multiple files concurrently
+     */
+    uploadMultiple(files: (File | Blob)[], concurrency?: number): Promise<PresignedUploadResult[]>;
+}
+/**
+ * Create a presigned URL uploader instance
+ */
+export declare function createPresignedUploader(config: PresignedUrlConfig): PresignedUploader;
+/**
+ * Upload a file using a presigned URL (convenience function)
+ */
+export declare function uploadWithPresignedUrl(file: File | Blob, config: PresignedUrlConfig): Promise<PresignedUploadResult>;
+/**
+ * AWS S3 specific presigned uploader
+ */
+export declare class S3PresignedUploader extends PresignedUploader {
+    constructor(config: Omit<PresignedUrlConfig, 'uploadMethod'>);
+}
+/**
+ * Azure Blob Storage specific presigned uploader
+ */
+export declare class AzurePresignedUploader extends PresignedUploader {
+    constructor(config: Omit<PresignedUrlConfig, 'uploadMethod'>);
+}
+export default PresignedUploader;