@flusys/nestjs-storage 7.1.0 → 8.0.0-beta.1

package/fesm/utils/file-validator.util.js

@@ -1,433 +0,0 @@
-/**
- * Result of file content validation.
- */ /**
- * Magic byte signatures for common file types.
- * Each entry maps a hex signature pattern to its MIME type.
- */ const MAGIC_BYTES = [
-    // Images
-    {
-        signature: [
-            0xff,
-            0xd8,
-            0xff
-        ],
-        offset: 0,
-        mimeType: 'image/jpeg'
-    },
-    {
-        signature: [
-            0x89,
-            0x50,
-            0x4e,
-            0x47,
-            0x0d,
-            0x0a,
-            0x1a,
-            0x0a
-        ],
-        offset: 0,
-        mimeType: 'image/png'
-    },
-    {
-        signature: [
-            0x47,
-            0x49,
-            0x46,
-            0x38,
-            0x37,
-            0x61
-        ],
-        offset: 0,
-        mimeType: 'image/gif'
-    },
-    {
-        signature: [
-            0x47,
-            0x49,
-            0x46,
-            0x38,
-            0x39,
-            0x61
-        ],
-        offset: 0,
-        mimeType: 'image/gif'
-    },
-    {
-        signature: [
-            0x42,
-            0x4d
-        ],
-        offset: 0,
-        mimeType: 'image/bmp'
-    },
-    {
-        signature: [
-            0x52,
-            0x49,
-            0x46,
-            0x46
-        ],
-        offset: 0,
-        mimeType: 'image/webp'
-    },
-    {
-        signature: [
-            0x00,
-            0x00,
-            0x01,
-            0x00
-        ],
-        offset: 0,
-        mimeType: 'image/x-icon'
-    },
-    {
-        signature: [
-            0x00,
-            0x00,
-            0x02,
-            0x00
-        ],
-        offset: 0,
-        mimeType: 'image/x-icon'
-    },
-    // Documents
-    {
-        signature: [
-            0x25,
-            0x50,
-            0x44,
-            0x46
-        ],
-        offset: 0,
-        mimeType: 'application/pdf'
-    },
-    {
-        signature: [
-            0x50,
-            0x4b,
-            0x03,
-            0x04
-        ],
-        offset: 0,
-        mimeType: 'application/zip'
-    },
-    // Audio
-    {
-        signature: [
-            0x49,
-            0x44,
-            0x33
-        ],
-        offset: 0,
-        mimeType: 'audio/mpeg'
-    },
-    {
-        signature: [
-            0xff,
-            0xfb
-        ],
-        offset: 0,
-        mimeType: 'audio/mpeg'
-    },
-    {
-        signature: [
-            0xff,
-            0xfa
-        ],
-        offset: 0,
-        mimeType: 'audio/mpeg'
-    },
-    {
-        signature: [
-            0x4f,
-            0x67,
-            0x67,
-            0x53
-        ],
-        offset: 0,
-        mimeType: 'audio/ogg'
-    },
-    {
-        signature: [
-            0x66,
-            0x4c,
-            0x61,
-            0x43
-        ],
-        offset: 0,
-        mimeType: 'audio/flac'
-    },
-    // Video
-    {
-        signature: [
-            0x00,
-            0x00,
-            0x00,
-            0x1c,
-            0x66,
-            0x74,
-            0x79,
-            0x70
-        ],
-        offset: 0,
-        mimeType: 'video/mp4'
-    },
-    {
-        signature: [
-            0x00,
-            0x00,
-            0x00,
-            0x20,
-            0x66,
-            0x74,
-            0x79,
-            0x70
-        ],
-        offset: 0,
-        mimeType: 'video/mp4'
-    },
-    {
-        signature: [
-            0x1a,
-            0x45,
-            0xdf,
-            0xa3
-        ],
-        offset: 0,
-        mimeType: 'video/webm'
-    },
-    {
-        signature: [
-            0x52,
-            0x49,
-            0x46,
-            0x46
-        ],
-        offset: 0,
-        mimeType: 'video/avi'
-    },
-    // Archives
-    {
-        signature: [
-            0x1f,
-            0x8b
-        ],
-        offset: 0,
-        mimeType: 'application/gzip'
-    },
-    {
-        signature: [
-            0x37,
-            0x7a,
-            0xbc,
-            0xaf,
-            0x27,
-            0x1c
-        ],
-        offset: 0,
-        mimeType: 'application/x-7z-compressed'
-    },
-    {
-        signature: [
-            0x52,
-            0x61,
-            0x72,
-            0x21,
-            0x1a,
-            0x07
-        ],
-        offset: 0,
-        mimeType: 'application/x-rar-compressed'
-    }
-];
-/**
- * MIME type aliases - types that are equivalent.
- */ const MIME_ALIASES = {
-    'image/jpeg': [
-        'image/jpg'
-    ],
-    'image/jpg': [
-        'image/jpeg'
-    ],
-    'video/mp4': [
-        'video/quicktime'
-    ],
-    'application/zip': [
-        'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
-        'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
-        'application/vnd.openxmlformats-officedocument.presentationml.presentation'
-    ]
-};
-/**
- * File types that are text-based and don't have magic bytes.
- * SECURITY NOTE: Dangerous types (HTML, JS, SVG) are excluded as they can contain scripts.
- * These types require explicit allowlisting and additional content scanning.
- */ const TEXT_BASED_TYPES = [
-    'text/plain',
-    'text/csv',
-    'text/markdown',
-    'application/json',
-    'application/xml',
-    'application/typescript',
-    'text/css'
-];
-/**
- * Dangerous text-based types that can execute scripts.
- * These bypass magic-bytes validation but require explicit allowlisting.
- */ const DANGEROUS_TEXT_TYPES = [
-    'text/html',
-    'application/javascript',
-    'text/javascript',
-    'image/svg+xml',
-    'application/xhtml+xml'
-];
-/**
- * ZIP-based format prefixes that are valid when detected as application/zip.
- */ const ZIP_VARIANT_PREFIXES = [
-    'application/vnd.openxmlformats-officedocument',
-    'application/x-zip',
-    'application/x-compressed'
-];
-/**
- * Utility class for validating file content using magic bytes.
- * Prevents file type spoofing by checking actual file content.
- */ export class FileValidator {
-    // Result Helpers
-    static failureResult(message, detectedType, declaredType) {
-        return {
-            valid: false,
-            detectedType,
-            declaredType,
-            message
-        };
-    }
-    static successResult(detectedType, declaredType) {
-        return {
-            valid: true,
-            detectedType,
-            declaredType
-        };
-    }
-    /**
-   * Detect file type from buffer using magic bytes.
-   * @param buffer - File buffer to analyze
-   * @returns Detected MIME type or null if unknown
-   */ static detectFileType(buffer) {
-        for (const { signature, offset, mimeType } of MAGIC_BYTES){
-            if (buffer.length < offset + signature.length) continue;
-            let matches = true;
-            for(let i = 0; i < signature.length; i++){
-                if (buffer[offset + i] !== signature[i]) {
-                    matches = false;
-                    break;
-                }
-            }
-            if (matches) {
-                return mimeType;
-            }
-        }
-        return null;
-    }
-    /**
-   * Check if a MIME type is text-based (doesn't have magic bytes).
-   */ static isTextBasedType(mimeType) {
-        return TEXT_BASED_TYPES.some((t)=>mimeType.startsWith(t) || mimeType === t);
-    }
-    /**
-   * Check if a MIME type is a dangerous text type that can execute scripts.
-   */ static isDangerousTextType(mimeType) {
-        return DANGEROUS_TEXT_TYPES.some((t)=>mimeType === t);
-    }
-    /**
-   * Check if two MIME types are compatible (exact match or aliases).
-   */ static mimeTypesMatch(detected, declared) {
-        // Exact match
-        if (detected === declared) return true;
-        // Check aliases
-        const aliases = MIME_ALIASES[detected];
-        if (aliases?.includes(declared)) return true;
-        // Check reverse aliases
-        const reverseAliases = MIME_ALIASES[declared];
-        if (reverseAliases?.includes(detected)) return true;
-        // Check if both are in same category (e.g., both images)
-        const detectedCategory = detected.split('/')[0];
-        const declaredCategory = declared.split('/')[0];
-        // For ZIP-based formats, allow any ZIP-detected file if declared is a ZIP variant
-        if (detected === 'application/zip' && ZIP_VARIANT_PREFIXES.some((v)=>declared.startsWith(v))) {
-            return true;
-        }
-        return detectedCategory === declaredCategory;
-    }
-    /**
-   * Check if a MIME type is in the allowed list.
-   */ static isTypeAllowed(mimeType, allowedTypes) {
-        // Wildcard allows all
-        if (allowedTypes.includes('*/*')) return true;
-        return allowedTypes.some((allowed)=>{
-            // Category wildcard (e.g., "image/*")
-            if (allowed.endsWith('/*')) {
-                const category = allowed.slice(0, -2);
-                return mimeType.startsWith(category);
-            }
-            return allowed === mimeType;
-        });
-    }
-    /**
-   * Validate file content matches declared MIME type using magic bytes.
-   * @param buffer - File buffer
-   * @param declaredMimeType - MIME type declared by client
-   * @param allowedTypes - List of allowed MIME types/patterns
-   * @returns Validation result
-   */ static validateFileContent(buffer, declaredMimeType, allowedTypes = [
-        '*/*'
-    ]) {
-        try {
-            const detectedType = this.detectFileType(buffer);
-            // No magic bytes detected - handle text-based types
-            if (!detectedType) {
-                return this.validateUndetectedType(declaredMimeType, allowedTypes);
-            }
-            // Verify detected type matches declared type
-            if (!this.mimeTypesMatch(detectedType, declaredMimeType)) {
-                return this.failureResult(`File content does not match declared type. Detected: ${detectedType}, Declared: ${declaredMimeType}`, detectedType, declaredMimeType);
-            }
-            // Verify type is in allowed list
-            if (!this.isTypeAllowed(detectedType, allowedTypes)) {
-                return this.failureResult(`File type "${detectedType}" is not allowed`, detectedType, declaredMimeType);
-            }
-            return this.successResult(detectedType, declaredMimeType);
-        } catch  {
-            return this.failureResult('File validation failed');
-        }
-    }
-    /**
-   * Handle validation for files without detectable magic bytes.
-   */ static validateUndetectedType(declaredMimeType, allowedTypes) {
-        // Check for dangerous text types first (HTML, JS, SVG)
-        if (this.isDangerousTextType(declaredMimeType)) {
-            const explicitlyAllowed = allowedTypes.some((t)=>t === declaredMimeType && t !== '*/*' && !t.endsWith('/*'));
-            if (!explicitlyAllowed) {
-                return this.failureResult(`File type "${declaredMimeType}" is potentially dangerous and not explicitly allowed`, declaredMimeType, declaredMimeType);
-            }
-        }
-        // Safe text-based files don't have magic bytes, trust declared type
-        if (this.isTextBasedType(declaredMimeType)) {
-            const isAllowed = this.isTypeAllowed(declaredMimeType, allowedTypes);
-            return isAllowed ? this.successResult(declaredMimeType, declaredMimeType) : this.failureResult(`File type "${declaredMimeType}" is not allowed`, declaredMimeType, declaredMimeType);
-        }
-        // Binary files without recognized signatures - be cautious
-        return this.failureResult('Unable to verify file type. File may be corrupted or unsupported.', undefined, declaredMimeType);
-    }
-    /**
-   * Sanitize filename to prevent path traversal and special character issues.
-   * @param filename - Original filename
-   * @returns Sanitized filename
-   */ static sanitizeFilename(filename) {
-        return filename// Remove path components (prevent traversal)
-        .replace(/^.*[\\\/]/, '')// Remove null bytes
-        .replace(/\0/g, '')// Replace multiple dots with single
-        .replace(/\.{2,}/g, '.')// Remove special characters except allowed ones
-        .replace(/[^a-zA-Z0-9._-]/g, '_')// Limit length
-        .substring(0, 255);
-    }
-}

package/fesm/utils/file-validator.util.spec.js

@@ -1,255 +0,0 @@
-import { FileValidator } from './file-validator.util';
-const JPEG_BYTES = Buffer.from([
-    0xff,
-    0xd8,
-    0xff,
-    0xe0,
-    0x00,
-    0x10
-]);
-const PNG_BYTES = Buffer.from([
-    0x89,
-    0x50,
-    0x4e,
-    0x47,
-    0x0d,
-    0x0a,
-    0x1a,
-    0x0a,
-    0x00,
-    0x00
-]);
-const PDF_BYTES = Buffer.from([
-    0x25,
-    0x50,
-    0x44,
-    0x46,
-    0x2d,
-    0x31,
-    0x2e,
-    0x34
-]);
-const ZIP_BYTES = Buffer.from([
-    0x50,
-    0x4b,
-    0x03,
-    0x04,
-    0x00,
-    0x00
-]);
-const GIF87_BYTES = Buffer.from([
-    0x47,
-    0x49,
-    0x46,
-    0x38,
-    0x37,
-    0x61
-]);
-const UNKNOWN_BYTES = Buffer.from([
-    0x01,
-    0x02,
-    0x03,
-    0x04
-]);
-describe('FileValidator', ()=>{
-    describe('detectFileType', ()=>{
-        it('detects JPEG from magic bytes', ()=>{
-            expect(FileValidator.detectFileType(JPEG_BYTES)).toBe('image/jpeg');
-        });
-        it('detects PNG from magic bytes', ()=>{
-            expect(FileValidator.detectFileType(PNG_BYTES)).toBe('image/png');
-        });
-        it('detects PDF from magic bytes', ()=>{
-            expect(FileValidator.detectFileType(PDF_BYTES)).toBe('application/pdf');
-        });
-        it('detects ZIP-based formats (docx/xlsx/pptx share this signature)', ()=>{
-            expect(FileValidator.detectFileType(ZIP_BYTES)).toBe('application/zip');
-        });
-        it('detects legacy GIF87a signature', ()=>{
-            expect(FileValidator.detectFileType(GIF87_BYTES)).toBe('image/gif');
-        });
-        it('returns null for unknown/unrecognized signatures', ()=>{
-            expect(FileValidator.detectFileType(UNKNOWN_BYTES)).toBeNull();
-        });
-        it('returns null for a buffer shorter than any known signature', ()=>{
-            expect(FileValidator.detectFileType(Buffer.from([
-                0xff
-            ]))).toBeNull();
-        });
-        it('returns null for an empty buffer', ()=>{
-            expect(FileValidator.detectFileType(Buffer.alloc(0))).toBeNull();
-        });
-    });
-    describe('isTextBasedType', ()=>{
-        it('recognizes plain text and structured text types', ()=>{
-            expect(FileValidator.isTextBasedType('text/plain')).toBe(true);
-            expect(FileValidator.isTextBasedType('application/json')).toBe(true);
-        });
-        it('rejects a non text-based type', ()=>{
-            expect(FileValidator.isTextBasedType('image/png')).toBe(false);
-        });
-    });
-    describe('isDangerousTextType', ()=>{
-        it('flags text/html as dangerous', ()=>{
-            expect(FileValidator.isDangerousTextType('text/html')).toBe(true);
-        });
-        it('flags image/svg+xml as dangerous (can embed scripts)', ()=>{
-            expect(FileValidator.isDangerousTextType('image/svg+xml')).toBe(true);
-        });
-        it('does not flag a safe type', ()=>{
-            expect(FileValidator.isDangerousTextType('image/png')).toBe(false);
-        });
-    });
-    describe('mimeTypesMatch', ()=>{
-        it('matches identical types', ()=>{
-            expect(FileValidator.mimeTypesMatch('image/png', 'image/png')).toBe(true);
-        });
-        it('matches known aliases (jpeg <-> jpg)', ()=>{
-            expect(FileValidator.mimeTypesMatch('image/jpeg', 'image/jpg')).toBe(true);
-            expect(FileValidator.mimeTypesMatch('image/jpg', 'image/jpeg')).toBe(true);
-        });
-        it('matches same broad category (image/* vs image/*)', ()=>{
-            expect(FileValidator.mimeTypesMatch('image/png', 'image/webp')).toBe(true);
-        });
-        it('matches ZIP-detected content against an office document declared type', ()=>{
-            expect(FileValidator.mimeTypesMatch('application/zip', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document')).toBe(true);
-        });
-        it('does not match unrelated categories', ()=>{
-            expect(FileValidator.mimeTypesMatch('image/png', 'application/pdf')).toBe(false);
-        });
-    });
-    describe('isTypeAllowed', ()=>{
-        it('allows anything when wildcard */* is present', ()=>{
-            expect(FileValidator.isTypeAllowed('application/pdf', [
-                '*/*'
-            ])).toBe(true);
-        });
-        it('allows category wildcard image/*', ()=>{
-            expect(FileValidator.isTypeAllowed('image/png', [
-                'image/*'
-            ])).toBe(true);
-        });
-        it('rejects a type outside the category wildcard', ()=>{
-            expect(FileValidator.isTypeAllowed('application/pdf', [
-                'image/*'
-            ])).toBe(false);
-        });
-        it('allows exact match', ()=>{
-            expect(FileValidator.isTypeAllowed('application/pdf', [
-                'application/pdf'
-            ])).toBe(true);
-        });
-        it('rejects when not in the explicit allow-list', ()=>{
-            expect(FileValidator.isTypeAllowed('application/pdf', [
-                'image/png',
-                'image/jpeg'
-            ])).toBe(false);
-        });
-    });
-    describe('validateFileContent', ()=>{
-        it('passes when magic bytes match declared type and type is allowed', ()=>{
-            const result = FileValidator.validateFileContent(JPEG_BYTES, 'image/jpeg', [
-                'image/*'
-            ]);
-            expect(result.valid).toBe(true);
-            expect(result.detectedType).toBe('image/jpeg');
-        });
-        it('fails when declared type does not match detected content (MIME spoofing)', ()=>{
-            const result = FileValidator.validateFileContent(PNG_BYTES, 'application/pdf', [
-                '*/*'
-            ]);
-            expect(result.valid).toBe(false);
-            expect(result.message).toContain('does not match declared type');
-        });
-        it('fails when detected type is not in the allow-list', ()=>{
-            const result = FileValidator.validateFileContent(PDF_BYTES, 'application/pdf', [
-                'image/*'
-            ]);
-            expect(result.valid).toBe(false);
-            expect(result.message).toContain('not allowed');
-        });
-        it('trusts declared type for safe text-based content without magic bytes', ()=>{
-            const result = FileValidator.validateFileContent(Buffer.from('name,age\nJohn,30'), 'text/csv', [
-                'text/*'
-            ]);
-            expect(result.valid).toBe(true);
-            expect(result.detectedType).toBe('text/csv');
-        });
-        it('rejects dangerous text/html content unless explicitly allow-listed', ()=>{
-            const result = FileValidator.validateFileContent(Buffer.from('<html><body>hi</body></html>'), 'text/html', [
-                '*/*'
-            ]);
-            expect(result.valid).toBe(false);
-            expect(result.message).toContain('potentially dangerous');
-        });
-        it('rejects image/svg+xml by default (can contain embedded scripts)', ()=>{
-            const result = FileValidator.validateFileContent(Buffer.from('<svg onload="alert(1)"></svg>'), 'image/svg+xml', [
-                '*/*'
-            ]);
-            expect(result.valid).toBe(false);
-        });
-        it('still fails text/html even when explicitly allow-listed, since it is not in TEXT_BASED_TYPES', ()=>{
-            // NOTE: validateUndetectedType() skips the "dangerous type" rejection when the type is
-            // explicitly allow-listed, but text/html is absent from TEXT_BASED_TYPES so it falls through
-            // to the generic "Unable to verify file type" failure. Documenting actual behavior here;
-            // see final report for this being flagged as a potential production logic quirk.
-            const result = FileValidator.validateFileContent(Buffer.from('<html></html>'), 'text/html', [
-                'text/html'
-            ]);
-            expect(result.valid).toBe(false);
-            expect(result.message).toContain('Unable to verify file type');
-        });
-        it('fails for binary content with no recognizable signature and no text fallback', ()=>{
-            const result = FileValidator.validateFileContent(UNKNOWN_BYTES, 'application/octet-stream', [
-                '*/*'
-            ]);
-            expect(result.valid).toBe(false);
-            expect(result.message).toContain('Unable to verify file type');
-        });
-        it('defaults allowedTypes to */* when not provided', ()=>{
-            const result = FileValidator.validateFileContent(JPEG_BYTES, 'image/jpeg');
-            expect(result.valid).toBe(true);
-        });
-        it('returns a failure result instead of throwing on unexpected internal errors', ()=>{
-            // Passing a non-buffer-like value to force detectFileType internals to misbehave gracefully
-            const brokenBuffer = {
-                length: 10
-            };
-            const result = FileValidator.validateFileContent(brokenBuffer, 'image/jpeg', [
-                '*/*'
-            ]);
-            expect(result.valid).toBe(false);
-        });
-    });
-    describe('sanitizeFilename', ()=>{
-        it('strips directory components to prevent path traversal', ()=>{
-            expect(FileValidator.sanitizeFilename('../../etc/passwd')).toBe('passwd');
-        });
-        it('strips Windows-style directory components', ()=>{
-            expect(FileValidator.sanitizeFilename('..\\..\\windows\\system32\\evil.exe')).toBe('evil.exe');
-        });
-        it('removes null bytes', ()=>{
-            expect(FileValidator.sanitizeFilename('file\0.txt')).toBe('file.txt');
-        });
-        it('collapses multiple consecutive dots into one', ()=>{
-            expect(FileValidator.sanitizeFilename('archive....tar.gz')).toBe('archive.tar.gz');
-        });
-        it('replaces special/unsafe characters with underscores', ()=>{
-            expect(FileValidator.sanitizeFilename('my file (final)!.txt')).toBe('my_file__final__.txt');
-        });
-        it('truncates filenames longer than 255 characters', ()=>{
-            const longName = `${'a'.repeat(300)}.txt`;
-            const sanitized = FileValidator.sanitizeFilename(longName);
-            expect(sanitized.length).toBeLessThanOrEqual(255);
-        });
-        it('preserves a simple safe filename unchanged', ()=>{
-            expect(FileValidator.sanitizeFilename('report-2024_final.pdf')).toBe('report-2024_final.pdf');
-        });
-        it('neutralizes an absolute-path traversal attempt embedded mid-string', ()=>{
-            const malicious = '/var/www/../../etc/passwd';
-            const sanitized = FileValidator.sanitizeFilename(malicious);
-            expect(sanitized).not.toContain('/');
-            expect(sanitized).not.toContain('..');
-        });
-    });
-});