@flusys/nestjs-storage 7.1.0 → 8.0.0

package/fesm/providers/local-provider.js

@@ -1,182 +0,0 @@
-function _define_property(obj, key, value) {
-    if (key in obj) {
-        Object.defineProperty(obj, key, {
-            value: value,
-            enumerable: true,
-            configurable: true,
-            writable: true
-        });
-    } else {
-        obj[key] = value;
-    }
-    return obj;
-}
-/**
- * LOCAL File System Provider
- *
- * This provider uses Node.js built-in 'fs' module - NO external dependencies required!
- * Perfect for same-server storage scenarios.
- *
- * Usage:
- * import { LocalProvider } from '@flusys/nestjs-storage/providers/local-provider';
- * import { StorageProviderRegistry, FileLocationEnum } from '@flusys/nestjs-storage';
- *
- * StorageProviderRegistry.register(FileLocationEnum.LOCAL, LocalProvider);
- */ import { BadRequestException } from '@nestjs/common';
-import { SYSTEM_MESSAGES } from '@flusys/nestjs-shared/constants';
-import { ImageCompressor } from '../utils/image-compressor.util';
-import * as fs from 'fs/promises';
-import * as path from 'path';
-import { v4 as uuidv4 } from 'uuid';
-/**
- * Local File System Storage Provider
- * Uses Node.js built-in fs module - no external dependencies
- */ export class LocalProvider {
-    /**
-   * SECURITY: Validates that a target path does not escape the base directory
-   * Prevents path traversal attacks using ../ sequences
-   * @throws Error if path traversal is detected
-   */ validatePathWithinBase(targetPath) {
-        const normalizedBasePath = path.resolve(this.basePath);
-        const normalizedTargetPath = path.resolve(targetPath);
-        if (!normalizedTargetPath.startsWith(normalizedBasePath + path.sep) && normalizedTargetPath !== normalizedBasePath) {
-            throw new BadRequestException({
-                message: 'Invalid path: Path traversal attempt detected',
-                messageKey: SYSTEM_MESSAGES.PATH_TRAVERSAL_DETECTED
-            });
-        }
-    }
-    /**
-   * SECURITY: Validates file key format to prevent malicious input
-   * @throws Error if key contains suspicious patterns
-   */ validateKeyFormat(key) {
-        if (!key || typeof key !== 'string' || key.trim().length === 0) {
-            throw new BadRequestException({
-                message: 'Invalid file key: empty or invalid',
-                messageKey: SYSTEM_MESSAGES.INVALID_FILE_KEY
-            });
-        }
-        if (key.includes('\0')) {
-            throw new BadRequestException({
-                message: 'Invalid file key: contains null bytes',
-                messageKey: SYSTEM_MESSAGES.INVALID_FILE_KEY
-            });
-        }
-    }
-    /**
-   * Initialize Local File System provider with configuration
-   * @param config.basePath - Base path for file storage (default: './uploads')
-   * @param config.baseUrl - Optional base URL for generating file URLs
-   */ async initialize(config) {
-        // Store original relative path for key generation
-        this.relativeBasePath = config?.basePath || './uploads';
-        // Resolve to absolute path for file operations
-        this.basePath = path.resolve(this.relativeBasePath);
-        this.baseUrl = config?.baseUrl || '';
-        // Ensure base directory exists
-        await fs.mkdir(this.basePath, {
-            recursive: true
-        });
-    }
-    async uploadFile(file, options) {
-        let processedBuffer = file.buffer;
-        let contentType = file.mimetype;
-        const fileName = `${uuidv4()}-${file.originalname}`;
-        // Compress image if needed
-        if (options.compress && file.mimetype.startsWith('image/')) {
-            const result = await ImageCompressor.compress(file.buffer, file.mimetype, {
-                maxWidth: options.maxWidth,
-                maxHeight: options.maxHeight,
-                quality: options.quality,
-                format: options.format
-            });
-            processedBuffer = result.buffer;
-            contentType = result.format;
-        }
-        // Build file path
-        const folderPath = options.folderPath ? path.join(this.basePath, options.folderPath) : this.basePath;
-        // SECURITY: Validate path does not escape base directory
-        this.validatePathWithinBase(folderPath);
-        const filePath = path.join(folderPath, fileName);
-        // SECURITY: Double-check final file path
-        this.validatePathWithinBase(filePath);
-        // Ensure directory exists
-        await fs.mkdir(folderPath, {
-            recursive: true
-        });
-        // Write file to disk
-        await fs.writeFile(filePath, processedBuffer);
-        // Generate key that includes the base path (relative to cwd)
-        // This makes the key self-contained for serving files
-        const relativeKey = path.join(this.relativeBasePath, options.folderPath || '', fileName).replace(/\\/g, '/'); // Normalize path separators
-        return {
-            name: fileName,
-            key: relativeKey,
-            size: processedBuffer.length,
-            contentType
-        };
-    }
-    async uploadMultipleFiles(files, options) {
-        return Promise.all(files.map((file)=>this.uploadFile(file, options)));
-    }
-    async deleteFile(key) {
-        try {
-            // SECURITY: Validate key format first
-            this.validateKeyFormat(key);
-            // Key now includes the basePath, resolve from cwd
-            let filePath = path.resolve(key);
-            // SECURITY: Validate resolved path is within base directory
-            this.validatePathWithinBase(filePath);
-            // Check if file exists at the resolved path
-            try {
-                await fs.access(filePath);
-            } catch  {
-                // Fallback: try with basePath prefix (for old keys without basePath)
-                const fallbackPath = path.join(this.basePath, key);
-                // SECURITY: Validate fallback path as well
-                this.validatePathWithinBase(fallbackPath);
-                try {
-                    await fs.access(fallbackPath);
-                    filePath = fallbackPath;
-                } catch  {
-                    // File doesn't exist at either location - silent return
-                    return;
-                }
-            }
-            await fs.unlink(filePath);
-        } catch (error) {
-            // Re-throw security errors
-            if (error instanceof Error && error.message.includes('Invalid')) {
-                throw error;
-            }
-        // Silent failure for other errors
-        }
-    }
-    async deleteMultipleFiles(keys) {
-        await Promise.all(keys.map((key)=>this.deleteFile(key)));
-    }
-    async generatePresignedUrl(key, _expiresInSeconds) {
-        // Return public URL or relative path
-        // Note: Local storage doesn't support true presigned URLs
-        // If baseUrl is provided, return full URL with file serving endpoint, otherwise return relative path
-        if (this.baseUrl) {
-            // Construct URL with the file serving endpoint
-            const baseUrlWithoutTrailingSlash = this.baseUrl.replace(/\/$/, '');
-            return `${baseUrlWithoutTrailingSlash}/storage/upload/file/${key}`;
-        }
-        return `/storage/upload/file/${key}`;
-    }
-    async healthCheck() {
-        try {
-            await fs.access(this.basePath);
-            return true;
-        } catch  {
-            return false;
-        }
-    }
-    constructor(){
-        _define_property(this, "basePath", '');
-        _define_property(this, "baseUrl", '');
-        _define_property(this, "relativeBasePath", ''); // Path relative to cwd for key generation
-    }
-}

package/fesm/providers/local-provider.spec.js

@@ -1,194 +0,0 @@
-const mockMkdir = jest.fn();
-const mockWriteFile = jest.fn();
-const mockAccess = jest.fn();
-const mockUnlink = jest.fn();
-jest.mock('fs/promises', ()=>({
-        mkdir: (...args)=>mockMkdir(...args),
-        writeFile: (...args)=>mockWriteFile(...args),
-        access: (...args)=>mockAccess(...args),
-        unlink: (...args)=>mockUnlink(...args)
-    }));
-jest.mock('../utils/image-compressor.util', ()=>({
-        ImageCompressor: {
-            compress: jest.fn()
-        }
-    }));
-import * as path from 'path';
-import { LocalProvider } from './local-provider';
-import { ImageCompressor } from '../utils/image-compressor.util';
-function buildMulterFile(overrides = {}) {
-    return {
-        fieldname: 'file',
-        originalname: 'photo.jpg',
-        encoding: '7bit',
-        mimetype: 'image/jpeg',
-        buffer: Buffer.from('file-bytes'),
-        size: 10,
-        stream: undefined,
-        destination: '',
-        filename: '',
-        path: '',
-        ...overrides
-    };
-}
-describe('LocalProvider', ()=>{
-    let provider;
-    beforeEach(async ()=>{
-        jest.clearAllMocks();
-        mockMkdir.mockResolvedValue(undefined);
-        mockWriteFile.mockResolvedValue(undefined);
-        mockAccess.mockResolvedValue(undefined);
-        mockUnlink.mockResolvedValue(undefined);
-        provider = new LocalProvider();
-        await provider.initialize({
-            basePath: './uploads-test',
-            baseUrl: 'http://localhost:2002'
-        });
-    });
-    describe('initialize', ()=>{
-        it('resolves the base path and ensures the directory exists', async ()=>{
-            expect(mockMkdir).toHaveBeenCalledWith(path.resolve('./uploads-test'), expect.objectContaining({
-                recursive: true
-            }));
-        });
-        it('defaults basePath to ./uploads when not provided', async ()=>{
-            mockMkdir.mockClear();
-            const defaultProvider = new LocalProvider();
-            await defaultProvider.initialize({});
-            expect(mockMkdir).toHaveBeenCalledWith(path.resolve('./uploads'), expect.objectContaining({
-                recursive: true
-            }));
-        });
-    });
-    describe('uploadFile', ()=>{
-        it('writes the file to disk and returns metadata with a self-contained key', async ()=>{
-            const file = buildMulterFile();
-            const result = await provider.uploadFile(file, {});
-            expect(mockWriteFile).toHaveBeenCalled();
-            expect(result.name).toMatch(/photo\.jpg$/);
-            expect(result.key).toContain('uploads-test');
-            expect(result.size).toBe(file.buffer.length);
-            expect(result.contentType).toBe('image/jpeg');
-        });
-        it('nests the file under folderPath when provided', async ()=>{
-            const file = buildMulterFile();
-            const result = await provider.uploadFile(file, {
-                folderPath: 'avatars'
-            });
-            expect(result.key).toContain('avatars');
-            expect(mockMkdir).toHaveBeenCalledWith(expect.stringContaining('avatars'), expect.objectContaining({
-                recursive: true
-            }));
-        });
-        it('compresses image files when options.compress is true', async ()=>{
-            ImageCompressor.compress.mockResolvedValue({
-                buffer: Buffer.from('compressed'),
-                format: 'image/webp'
-            });
-            const file = buildMulterFile();
-            const result = await provider.uploadFile(file, {
-                compress: true,
-                maxWidth: 800,
-                maxHeight: 600,
-                quality: 70
-            });
-            expect(ImageCompressor.compress).toHaveBeenCalledWith(file.buffer, 'image/jpeg', expect.objectContaining({
-                maxWidth: 800,
-                maxHeight: 600,
-                quality: 70
-            }));
-            expect(result.contentType).toBe('image/webp');
-            expect(result.size).toBe(Buffer.from('compressed').length);
-        });
-        it('does not compress non-image mimetypes even when compress=true', async ()=>{
-            const file = buildMulterFile({
-                mimetype: 'application/pdf',
-                originalname: 'doc.pdf'
-            });
-            await provider.uploadFile(file, {
-                compress: true
-            });
-            expect(ImageCompressor.compress).not.toHaveBeenCalled();
-        });
-        it('rejects a folderPath that attempts to escape the base directory via path traversal', async ()=>{
-            const file = buildMulterFile();
-            await expect(provider.uploadFile(file, {
-                folderPath: '../../../etc'
-            })).rejects.toThrow();
-        });
-    });
-    describe('uploadMultipleFiles', ()=>{
-        it('uploads all files and returns their metadata', async ()=>{
-            const files = [
-                buildMulterFile({
-                    originalname: 'a.jpg'
-                }),
-                buildMulterFile({
-                    originalname: 'b.jpg'
-                })
-            ];
-            const results = await provider.uploadMultipleFiles(files, {});
-            expect(results).toHaveLength(2);
-            expect(mockWriteFile).toHaveBeenCalledTimes(2);
-        });
-    });
-    describe('deleteFile', ()=>{
-        it('deletes a file that exists at the resolved key path', async ()=>{
-            const key = path.join('uploads-test', 'some-uuid-photo.jpg');
-            await provider.deleteFile(key);
-            expect(mockUnlink).toHaveBeenCalled();
-        });
-        it('falls back to basePath-prefixed lookup when the direct key path does not exist', async ()=>{
-            mockAccess.mockRejectedValueOnce(new Error('ENOENT')).mockResolvedValueOnce(undefined);
-            await provider.deleteFile('uploads-test/some-uuid-photo.jpg');
-            expect(mockUnlink).toHaveBeenCalled();
-        });
-        it('silently returns (no throw, no unlink) when the file does not exist at either location', async ()=>{
-            mockAccess.mockRejectedValue(new Error('ENOENT'));
-            await expect(provider.deleteFile('uploads-test/missing-file.jpg')).resolves.toBeUndefined();
-            expect(mockUnlink).not.toHaveBeenCalled();
-        });
-        it('rejects an empty key', async ()=>{
-            await expect(provider.deleteFile('')).rejects.toThrow();
-        });
-        it('rejects a key containing a null byte', async ()=>{
-            await expect(provider.deleteFile('evil\0.txt')).rejects.toThrow();
-        });
-        it('re-throws path traversal security errors rather than silently swallowing them', async ()=>{
-            await expect(provider.deleteFile('../../../etc/passwd')).rejects.toThrow(/Invalid/);
-        });
-    });
-    describe('deleteMultipleFiles', ()=>{
-        it('deletes every provided key', async ()=>{
-            await provider.deleteMultipleFiles([
-                'uploads-test/a.jpg',
-                'uploads-test/b.jpg'
-            ]);
-            expect(mockUnlink).toHaveBeenCalledTimes(2);
-        });
-    });
-    describe('generatePresignedUrl', ()=>{
-        it('builds a full URL using the configured baseUrl', async ()=>{
-            const url = await provider.generatePresignedUrl('uploads-test/photo.jpg');
-            expect(url).toBe('http://localhost:2002/storage/upload/file/uploads-test/photo.jpg');
-        });
-        it('returns a relative path when no baseUrl was configured', async ()=>{
-            const noUrlProvider = new LocalProvider();
-            await noUrlProvider.initialize({
-                basePath: './uploads-test2'
-            });
-            const url = await noUrlProvider.generatePresignedUrl('uploads-test2/photo.jpg');
-            expect(url).toBe('/storage/upload/file/uploads-test2/photo.jpg');
-        });
-    });
-    describe('healthCheck', ()=>{
-        it('returns true when the base path is accessible', async ()=>{
-            mockAccess.mockResolvedValue(undefined);
-            await expect(provider.healthCheck()).resolves.toBe(true);
-        });
-        it('returns false when the base path is not accessible', async ()=>{
-            mockAccess.mockRejectedValue(new Error('ENOENT'));
-            await expect(provider.healthCheck()).resolves.toBe(false);
-        });
-    });
-});

package/fesm/providers/s3-provider.optional.spec.js

@@ -1,239 +0,0 @@
-function _define_property(obj, key, value) {
-    if (key in obj) {
-        Object.defineProperty(obj, key, {
-            value: value,
-            enumerable: true,
-            configurable: true,
-            writable: true
-        });
-    } else {
-        obj[key] = value;
-    }
-    return obj;
-}
-const mockS3ClientSend = jest.fn();
-const mockS3ClientCtor = jest.fn().mockImplementation(()=>({
-        send: mockS3ClientSend
-    }));
-let MockDeleteObjectCommand = class MockDeleteObjectCommand {
-    constructor(input){
-        _define_property(this, "input", void 0);
-        this.input = input;
-    }
-};
-let MockDeleteObjectsCommand = class MockDeleteObjectsCommand {
-    constructor(input){
-        _define_property(this, "input", void 0);
-        this.input = input;
-    }
-};
-let MockGetObjectCommand = class MockGetObjectCommand {
-    constructor(input){
-        _define_property(this, "input", void 0);
-        this.input = input;
-    }
-};
-let MockHeadBucketCommand = class MockHeadBucketCommand {
-    constructor(input){
-        _define_property(this, "input", void 0);
-        this.input = input;
-    }
-};
-jest.mock('@aws-sdk/client-s3', ()=>({
-        S3Client: mockS3ClientCtor,
-        DeleteObjectCommand: MockDeleteObjectCommand,
-        DeleteObjectsCommand: MockDeleteObjectsCommand,
-        GetObjectCommand: MockGetObjectCommand,
-        HeadBucketCommand: MockHeadBucketCommand
-    }));
-const mockUploadDone = jest.fn();
-const mockUploadCtor = jest.fn().mockImplementation(()=>({
-        done: mockUploadDone
-    }));
-jest.mock('@aws-sdk/lib-storage', ()=>({
-        Upload: mockUploadCtor
-    }));
-const mockGetSignedUrl = jest.fn();
-jest.mock('@aws-sdk/s3-request-presigner', ()=>({
-        getSignedUrl: (...args)=>mockGetSignedUrl(...args)
-    }));
-jest.mock('../utils/image-compressor.util', ()=>({
-        ImageCompressor: {
-            compress: jest.fn()
-        }
-    }));
-import { S3Provider } from './s3-provider.optional';
-import { ImageCompressor } from '../utils/image-compressor.util';
-function buildMulterFile(overrides = {}) {
-    return {
-        fieldname: 'file',
-        originalname: 'photo.jpg',
-        encoding: '7bit',
-        mimetype: 'image/jpeg',
-        buffer: Buffer.from('file-bytes'),
-        size: 10,
-        stream: undefined,
-        destination: '',
-        filename: '',
-        path: '',
-        ...overrides
-    };
-}
-describe('S3Provider', ()=>{
-    let provider;
-    beforeEach(async ()=>{
-        jest.clearAllMocks();
-        mockUploadDone.mockResolvedValue(undefined);
-        provider = new S3Provider();
-        await provider.initialize({
-            region: 'us-east-1',
-            bucket: 'my-bucket'
-        });
-    });
-    describe('initialize', ()=>{
-        it('creates an S3Client with region/endpoint/credentials', async ()=>{
-            jest.clearAllMocks();
-            const p = new S3Provider();
-            await p.initialize({
-                region: 'eu-west-1',
-                bucket: 'bucket-2',
-                accessKeyId: 'AKIA...',
-                secretAccessKey: 'secret',
-                endpoint: 'https://s3.custom.example.com'
-            });
-            expect(mockS3ClientCtor).toHaveBeenCalledWith(expect.objectContaining({
-                region: 'eu-west-1',
-                endpoint: 'https://s3.custom.example.com',
-                credentials: {
-                    accessKeyId: 'AKIA...',
-                    secretAccessKey: 'secret'
-                }
-            }));
-        });
-        it('omits credentials when access key / secret are not provided', async ()=>{
-            jest.clearAllMocks();
-            const p = new S3Provider();
-            await p.initialize({
-                region: 'us-east-1',
-                bucket: 'bucket-3'
-            });
-            expect(mockS3ClientCtor).toHaveBeenCalledWith(expect.objectContaining({
-                credentials: undefined
-            }));
-        });
-        it('throws InternalServerErrorException when the AWS SDK cannot be initialized', async ()=>{
-            mockS3ClientCtor.mockImplementationOnce(()=>{
-                throw new Error('module not found');
-            });
-            const brokenProvider = new S3Provider();
-            await expect(brokenProvider.initialize({
-                region: 'us-east-1',
-                bucket: 'x'
-            })).rejects.toThrow('AWS SDK not found');
-        });
-    });
-    describe('uploadFile', ()=>{
-        it('uploads via the S3 Upload helper and returns file metadata', async ()=>{
-            const file = buildMulterFile();
-            const result = await provider.uploadFile(file, {});
-            expect(mockUploadCtor).toHaveBeenCalledWith(expect.objectContaining({
-                params: expect.objectContaining({
-                    Bucket: 'my-bucket',
-                    ContentType: 'image/jpeg'
-                })
-            }));
-            expect(mockUploadDone).toHaveBeenCalled();
-            expect(result.name).toMatch(/photo\.jpg$/);
-            expect(result.key).toBe(result.name);
-        });
-        it('prefixes the key with folderPath when provided', async ()=>{
-            const file = buildMulterFile();
-            const result = await provider.uploadFile(file, {
-                folderPath: 'avatars'
-            });
-            expect(result.key).toMatch(/^avatars\//);
-        });
-        it('compresses image files before upload when options.compress is true', async ()=>{
-            ImageCompressor.compress.mockResolvedValue({
-                buffer: Buffer.from('compressed'),
-                format: 'image/webp'
-            });
-            const file = buildMulterFile();
-            const result = await provider.uploadFile(file, {
-                compress: true
-            });
-            expect(ImageCompressor.compress).toHaveBeenCalled();
-            expect(result.contentType).toBe('image/webp');
-        });
-    });
-    describe('uploadMultipleFiles', ()=>{
-        it('uploads each file and returns metadata for all', async ()=>{
-            const files = [
-                buildMulterFile({
-                    originalname: 'a.jpg'
-                }),
-                buildMulterFile({
-                    originalname: 'b.jpg'
-                })
-            ];
-            const results = await provider.uploadMultipleFiles(files, {});
-            expect(results).toHaveLength(2);
-            expect(mockUploadCtor).toHaveBeenCalledTimes(2);
-        });
-    });
-    describe('deleteFile', ()=>{
-        it('sends a DeleteObjectCommand with bucket and key', async ()=>{
-            await provider.deleteFile('some/key.jpg');
-            expect(mockS3ClientSend).toHaveBeenCalledWith(expect.any(MockDeleteObjectCommand));
-            const sentCommand = mockS3ClientSend.mock.calls[0][0];
-            expect(sentCommand.input).toEqual({
-                Bucket: 'my-bucket',
-                Key: 'some/key.jpg'
-            });
-        });
-    });
-    describe('deleteMultipleFiles', ()=>{
-        it('sends a DeleteObjectsCommand containing all keys', async ()=>{
-            await provider.deleteMultipleFiles([
-                'a.jpg',
-                'b.jpg'
-            ]);
-            const sentCommand = mockS3ClientSend.mock.calls[0][0];
-            expect(sentCommand.input.Delete.Objects).toEqual([
-                {
-                    Key: 'a.jpg'
-                },
-                {
-                    Key: 'b.jpg'
-                }
-            ]);
-        });
-    });
-    describe('generatePresignedUrl', ()=>{
-        it('delegates to getSignedUrl with the configured expiry', async ()=>{
-            mockGetSignedUrl.mockResolvedValue('https://signed.example.com/some/key.jpg');
-            const url = await provider.generatePresignedUrl('some/key.jpg', 900);
-            expect(mockGetSignedUrl).toHaveBeenCalledWith(expect.anything(), expect.any(MockGetObjectCommand), {
-                expiresIn: 900
-            });
-            expect(url).toBe('https://signed.example.com/some/key.jpg');
-        });
-        it('defaults expiry to 3600 seconds when not provided', async ()=>{
-            mockGetSignedUrl.mockResolvedValue('https://signed.example.com/x');
-            await provider.generatePresignedUrl('x');
-            expect(mockGetSignedUrl).toHaveBeenCalledWith(expect.anything(), expect.anything(), {
-                expiresIn: 3600
-            });
-        });
-    });
-    describe('healthCheck', ()=>{
-        it('returns true when HeadBucketCommand succeeds', async ()=>{
-            mockS3ClientSend.mockResolvedValue({});
-            await expect(provider.healthCheck()).resolves.toBe(true);
-        });
-        it('returns false when HeadBucketCommand rejects (bucket missing/unauthorized)', async ()=>{
-            mockS3ClientSend.mockRejectedValue(new Error('Forbidden'));
-            await expect(provider.healthCheck()).resolves.toBe(false);
-        });
-    });
-});