@flusys/nestjs-storage 6.0.1 → 6.1.0

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

@@ -0,0 +1,255 @@
+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('..');
+        });
+    });
+});

package/fesm/utils/image-compressor.util.spec.js

@@ -0,0 +1,162 @@
+const mockToBuffer = jest.fn();
+const mockJpeg = jest.fn();
+const mockPng = jest.fn();
+const mockWebp = jest.fn();
+const mockAvif = jest.fn();
+const mockTiff = jest.fn();
+const mockGif = jest.fn();
+const mockJp2 = jest.fn();
+const mockResize = jest.fn();
+function buildChainableImage() {
+    const image = {};
+    image.resize = mockResize.mockReturnValue(image);
+    image.jpeg = mockJpeg.mockReturnValue(image);
+    image.png = mockPng.mockReturnValue(image);
+    image.webp = mockWebp.mockReturnValue(image);
+    image.avif = mockAvif.mockReturnValue(image);
+    image.tiff = mockTiff.mockReturnValue(image);
+    image.gif = mockGif.mockReturnValue(image);
+    image.jp2 = mockJp2.mockReturnValue(image);
+    image.toBuffer = mockToBuffer;
+    return image;
+}
+const mockSharpFactory = jest.fn();
+jest.mock('sharp', ()=>{
+    const factory = (...args)=>mockSharpFactory(...args);
+    return {
+        __esModule: true,
+        default: factory
+    };
+});
+import { ImageCompressor } from './image-compressor.util';
+describe('ImageCompressor', ()=>{
+    beforeEach(()=>{
+        jest.clearAllMocks();
+        mockSharpFactory.mockImplementation(()=>buildChainableImage());
+        mockToBuffer.mockResolvedValue(Buffer.from('compressed-image-data'));
+    });
+    it('returns the buffer unchanged for image/svg+xml without invoking sharp', async ()=>{
+        const buffer = Buffer.from('<svg></svg>');
+        const result = await ImageCompressor.compress(buffer, 'image/svg+xml');
+        expect(result.buffer).toBe(buffer);
+        expect(result.format).toBe('image/svg+xml');
+        expect(mockSharpFactory).not.toHaveBeenCalled();
+    });
+    it('resizes using default maxWidth/maxHeight when no options are provided', async ()=>{
+        await ImageCompressor.compress(Buffer.from('jpeg-bytes'), 'image/jpeg');
+        expect(mockResize).toHaveBeenCalledWith(expect.objectContaining({
+            width: 1280,
+            height: 1280,
+            fit: 'inside',
+            withoutEnlargement: true
+        }));
+    });
+    it('resizes using custom maxWidth/maxHeight when provided', async ()=>{
+        await ImageCompressor.compress(Buffer.from('jpeg-bytes'), 'image/jpeg', {
+            maxWidth: 500,
+            maxHeight: 600
+        });
+        expect(mockResize).toHaveBeenCalledWith(expect.objectContaining({
+            width: 500,
+            height: 600
+        }));
+    });
+    it('preserves the original format (derived from mimetype) when format is "original"', async ()=>{
+        const result = await ImageCompressor.compress(Buffer.from('png-bytes'), 'image/png', {
+            format: 'original'
+        });
+        expect(mockPng).toHaveBeenCalled();
+        expect(result.format).toBe('image/png');
+    });
+    it('applies jpeg-specific compression options with quality', async ()=>{
+        await ImageCompressor.compress(Buffer.from('bytes'), 'image/jpeg', {
+            quality: 70
+        });
+        expect(mockJpeg).toHaveBeenCalledWith(expect.objectContaining({
+            quality: 70,
+            mozjpeg: true
+        }));
+    });
+    it('applies png-specific compression options', async ()=>{
+        await ImageCompressor.compress(Buffer.from('bytes'), 'image/png', {
+            quality: 90
+        });
+        expect(mockPng).toHaveBeenCalledWith(expect.objectContaining({
+            quality: 90,
+            colors: 256
+        }));
+    });
+    it('applies webp-specific options and sets lossless=true only when quality is 100', async ()=>{
+        await ImageCompressor.compress(Buffer.from('bytes'), 'image/webp', {
+            quality: 100,
+            format: 'webp'
+        });
+        expect(mockWebp).toHaveBeenCalledWith(expect.objectContaining({
+            quality: 100,
+            lossless: true
+        }));
+    });
+    it('applies webp-specific options with lossless=false for quality < 100', async ()=>{
+        await ImageCompressor.compress(Buffer.from('bytes'), 'image/webp', {
+            quality: 80,
+            format: 'webp'
+        });
+        expect(mockWebp).toHaveBeenCalledWith(expect.objectContaining({
+            quality: 80,
+            lossless: false
+        }));
+    });
+    it('applies avif-specific compression options', async ()=>{
+        await ImageCompressor.compress(Buffer.from('bytes'), 'image/avif', {
+            format: 'avif'
+        });
+        expect(mockAvif).toHaveBeenCalled();
+    });
+    it('applies tiff-specific compression options', async ()=>{
+        await ImageCompressor.compress(Buffer.from('bytes'), 'image/tiff', {
+            format: 'tiff'
+        });
+        expect(mockTiff).toHaveBeenCalled();
+    });
+    it('applies gif-specific compression options', async ()=>{
+        await ImageCompressor.compress(Buffer.from('bytes'), 'image/gif', {
+            format: 'gif'
+        });
+        expect(mockGif).toHaveBeenCalled();
+    });
+    it('applies jp2-specific compression options', async ()=>{
+        await ImageCompressor.compress(Buffer.from('bytes'), 'image/jp2', {
+            format: 'jp2'
+        });
+        expect(mockJp2).toHaveBeenCalled();
+    });
+    it('falls back to webp for an unrecognized target format', async ()=>{
+        const result = await ImageCompressor.compress(Buffer.from('bytes'), 'image/unknownformat', {
+            format: 'original'
+        });
+        expect(mockWebp).toHaveBeenCalled();
+        expect(result.format).toBe('image/webp');
+    });
+    it('returns the compressed buffer and content-type prefixed format on success', async ()=>{
+        mockToBuffer.mockResolvedValue(Buffer.from('final-bytes'));
+        const result = await ImageCompressor.compress(Buffer.from('bytes'), 'image/jpeg', {
+            format: 'jpeg'
+        });
+        expect(result.buffer).toEqual(Buffer.from('final-bytes'));
+        expect(result.format).toBe('image/jpeg');
+    });
+    it('falls back to the original buffer and mimetype when sharp processing throws', async ()=>{
+        const originalBuffer = Buffer.from('original-bytes');
+        mockToBuffer.mockRejectedValue(new Error('corrupt image'));
+        const result = await ImageCompressor.compress(originalBuffer, 'image/png');
+        expect(result.buffer).toBe(originalBuffer);
+        expect(result.format).toBe('image/png');
+    });
+    it('initializes sharp with failOnError=false and a density hint', async ()=>{
+        await ImageCompressor.compress(Buffer.from('bytes'), 'image/jpeg');
+        expect(mockSharpFactory).toHaveBeenCalledWith(expect.any(Buffer), expect.objectContaining({
+            failOnError: false,
+            density: 300
+        }));
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flusys/nestjs-storage",
-  "version": "6.0.1",
+  "version": "6.1.0",
   "description": "Modular storage package with optional AWS S3, Azure Blob, and SFTP providers",
   "main": "cjs/index.js",
   "module": "fesm/index.js",
@@ -129,7 +129,7 @@
     }
   },
   "dependencies": {
-    "@flusys/nestjs-core": "6.0.1",
-    "@flusys/nestjs-shared": "6.0.1"
+    "@flusys/nestjs-core": "6.1.0",
+    "@flusys/nestjs-shared": "6.1.0"
   }
 }