@flusys/nestjs-storage 1.1.0-beta → 2.0.0-rc.0

package/fesm/modules/storage.module.js

@@ -5,9 +5,9 @@ function _ts_decorate(decorators, target, key, desc) {
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
 import { CacheModule, UtilsModule } from '@flusys/nestjs-shared/modules';
-import { Module, Logger, RequestMethod } from '@nestjs/common';
+import { Logger, Module, RequestMethod } from '@nestjs/common';
 import { FileServeMiddleware } from '../middlewares';
-import { StorageConfigService } from '../config';
+import { StorageConfigService } from '../services';
 import { STORAGE_MODULE_OPTIONS } from '../config/storage.constants';
 import { FileManagerController, FolderController, StorageConfigController, UploadController } from '../controllers';
 import { FileLocationEnum } from '../enums/file-location.enum';
@@ -15,48 +15,62 @@ import { StorageFactoryService, StorageProviderRegistry } from '../providers';
 import { LocalProvider } from '../providers/local-provider';
 import { FileManagerService, FolderService, StorageDataSourceProvider, UploadService } from '../services';
 import { StorageProviderConfigService } from '../services/storage-provider-config.service';
-// Auto-register built-in storage providers
+// ─── Module Constants ─────────────────────────────────────────────────────────
 const logger = new Logger('StorageModule');
-// Register LocalProvider (always available - uses Node.js built-in fs)
+const CONTROLLERS = [
+    FileManagerController,
+    FolderController,
+    StorageConfigController,
+    UploadController
+];
+const EXPORTED_SERVICES = [
+    StorageConfigService,
+    StorageDataSourceProvider,
+    FileManagerService,
+    FolderService,
+    StorageProviderConfigService,
+    UploadService,
+    StorageFactoryService
+];
+// ─── Provider Registration ────────────────────────────────────────────────────
 StorageProviderRegistry.register(FileLocationEnum.LOCAL, LocalProvider);
 logger.log('Registered LocalProvider');
-// Try to register optional providers (only if dependencies are installed)
-try {
-    const { S3Provider } = require('../providers/s3-provider.optional');
-    StorageProviderRegistry.register(FileLocationEnum.AWS, S3Provider);
-    logger.log('Registered S3Provider');
-} catch  {
-    logger.debug('S3Provider not available (install @aws-sdk/client-s3 to enable)');
-}
-try {
-    const { AzureProvider } = require('../providers/azure-provider.optional');
-    StorageProviderRegistry.register(FileLocationEnum.AZURE, AzureProvider);
-    logger.log('Registered AzureProvider');
-} catch  {
-    logger.debug('AzureProvider not available (install @azure/storage-blob to enable)');
-}
-try {
-    const { SftpProvider } = require('../providers/sftp-provider.optional');
-    StorageProviderRegistry.register(FileLocationEnum.SFTP, SftpProvider);
-    logger.log('Registered SftpProvider');
-} catch  {
-    logger.debug('SftpProvider not available (install ssh2-sftp-client to enable)');
+const OPTIONAL_PROVIDERS = [
+    {
+        location: FileLocationEnum.AWS,
+        path: '../providers/s3-provider.optional',
+        name: 'S3Provider',
+        dep: '@aws-sdk/client-s3'
+    },
+    {
+        location: FileLocationEnum.AZURE,
+        path: '../providers/azure-provider.optional',
+        name: 'AzureProvider',
+        dep: '@azure/storage-blob'
+    },
+    {
+        location: FileLocationEnum.SFTP,
+        path: '../providers/sftp-provider.optional',
+        name: 'SftpProvider',
+        dep: 'ssh2-sftp-client'
+    }
+];
+for (const { location, path, name, dep } of OPTIONAL_PROVIDERS){
+    try {
+        StorageProviderRegistry.register(location, require(path)[name]);
+        logger.log(`Registered ${name}`);
+    } catch  {
+        logger.debug(`${name} not available (install ${dep} to enable)`);
+    }
 }
 export class StorageModule {
-    /**
-   * Configure middleware for file serving
-   * This bypasses path-to-regexp issues with wildcard routes
-   */ configure(consumer) {
+    configure(consumer) {
         consumer.apply(FileServeMiddleware).forRoutes({
             path: 'storage/upload/file/*',
             method: RequestMethod.GET
         });
     }
-    /**
-   * Register StorageModule synchronously
-   */ static forRoot(options) {
-        const controllers = this.getControllers(options);
-        const providers = this.getProviders(options);
+    static forRoot(options) {
         return {
             module: StorageModule,
             global: options.global ?? false,
@@ -64,24 +78,12 @@ export class StorageModule {
                 CacheModule,
                 UtilsModule
             ],
-            controllers: options.includeController !== false ? controllers : [],
-            providers,
-            exports: [
-                StorageConfigService,
-                StorageDataSourceProvider,
-                FileManagerService,
-                FolderService,
-                StorageProviderConfigService,
-                UploadService,
-                StorageFactoryService
-            ]
+            controllers: options.includeController !== false ? CONTROLLERS : [],
+            providers: this.buildProviders(options),
+            exports: EXPORTED_SERVICES
         };
     }
-    /**
-   * Register StorageModule asynchronously
-   */ static forRootAsync(options) {
-        const controllers = this.getControllers(options);
-        const asyncProviders = this.createAsyncProviders(options);
+    static forRootAsync(options) {
         return {
             module: StorageModule,
             global: options.global ?? false,
@@ -90,53 +92,21 @@ export class StorageModule {
                 CacheModule,
                 UtilsModule
             ],
-            controllers: options.includeController !== false ? controllers : [],
-            // Pass false to exclude STORAGE_MODULE_OPTIONS - it's already in asyncProviders
+            controllers: options.includeController !== false ? CONTROLLERS : [],
             providers: [
-                ...asyncProviders,
-                ...this.getProviders(options, false)
+                ...this.createAsyncProviders(options),
+                ...this.buildProviders()
             ],
-            exports: [
-                StorageConfigService,
-                StorageDataSourceProvider,
-                FileManagerService,
-                FolderService,
-                StorageProviderConfigService,
-                UploadService,
-                StorageFactoryService
-            ]
+            exports: EXPORTED_SERVICES
         };
     }
-    // Private Helper Methods
-    /** Get controllers (all controllers always loaded) */ static getControllers(options) {
-        return [
-            FileManagerController,
-            FolderController,
-            StorageConfigController,
-            UploadController
-        ];
-    }
-    /**
-   * NOTE: Repository providers removed - services now use StorageDataSourceProvider directly
-   * This ensures dynamic entity loading based on runtime configuration
-   */ /**
-   * Get providers (all providers always loaded)
-   * @param options Module options
-   * @param includeOptionsProvider Whether to include the STORAGE_MODULE_OPTIONS provider (false for async registration)
-   */ static getProviders(options, includeOptionsProvider = true) {
+    // ─── Private Helpers ──────────────────────────────────────────────────────────
+    static buildProviders(options) {
         const providers = [
-            StorageConfigService,
-            StorageDataSourceProvider,
-            FileManagerService,
-            FolderService,
-            StorageProviderConfigService,
-            UploadService,
-            StorageFactoryService,
+            ...EXPORTED_SERVICES,
             FileServeMiddleware
         ];
-        // Only include options provider for sync registration
-        // For async registration, createAsyncProviders handles it
-        if (includeOptionsProvider) {
+        if (options) {
             providers.unshift({
                 provide: STORAGE_MODULE_OPTIONS,
                 useValue: options
@@ -144,63 +114,40 @@ export class StorageModule {
         }
         return providers;
     }
-    /**
-   * Create async providers for forRootAsync
-   */ static createAsyncProviders(options) {
+    static createAsyncProviders(options) {
         if (options.useFactory) {
             return [
                 {
                     provide: STORAGE_MODULE_OPTIONS,
-                    useFactory: async (...args)=>{
-                        const config = await options.useFactory(...args);
-                        return {
+                    useFactory: async (...args)=>({
                             ...options,
-                            config
-                        };
-                    },
+                            config: await options.useFactory(...args)
+                        }),
                     inject: options.inject || []
                 }
             ];
         }
+        const factoryClass = options.useClass || options.useExisting;
+        if (!factoryClass) return [];
+        const providers = [
+            {
+                provide: STORAGE_MODULE_OPTIONS,
+                useFactory: async (factory)=>({
+                        ...options,
+                        config: await factory.createStorageOptions()
+                    }),
+                inject: [
+                    factoryClass
+                ]
+            }
+        ];
         if (options.useClass) {
-            return [
-                {
-                    provide: STORAGE_MODULE_OPTIONS,
-                    useFactory: async (optionsFactory)=>{
-                        const config = await optionsFactory.createStorageOptions();
-                        return {
-                            ...options,
-                            config
-                        };
-                    },
-                    inject: [
-                        options.useClass
-                    ]
-                },
-                {
-                    provide: options.useClass,
-                    useClass: options.useClass
-                }
-            ];
-        }
-        if (options.useExisting) {
-            return [
-                {
-                    provide: STORAGE_MODULE_OPTIONS,
-                    useFactory: async (optionsFactory)=>{
-                        const config = await optionsFactory.createStorageOptions();
-                        return {
-                            ...options,
-                            config
-                        };
-                    },
-                    inject: [
-                        options.useExisting
-                    ]
-                }
-            ];
+            providers.push({
+                provide: options.useClass,
+                useClass: options.useClass
+            });
         }
-        return [];
+        return providers;
     }
 }
 StorageModule = _ts_decorate([

package/fesm/providers/azure-provider.optional.js

@@ -1,17 +1,6 @@
 /**
- * OPTIONAL Azure Blob Storage Provider
- *
- * This provider requires @azure/storage-blob package to be installed.
- * Only import this if you need Azure Blob storage.
- *
- * Installation:
- * npm install @azure/storage-blob
- *
- * Usage:
- * import { AzureProvider } from '@flusys/nestjs-storage/providers/azure-provider.optional';
- * import { StorageProviderRegistry, FileLocationEnum } from '@flusys/nestjs-storage';
- *
- * StorageProviderRegistry.register(FileLocationEnum.AZURE, AzureProvider);
+ * Optional Azure Blob Storage Provider
+ * Requires: npm install @azure/storage-blob
  */ function _define_property(obj, key, value) {
     if (key in obj) {
         Object.defineProperty(obj, key, {
@@ -25,44 +14,27 @@
     }
     return obj;
 }
-import { ImageCompressor } from '../utils/image-compressor.util';
 import { Logger } from '@nestjs/common';
 import { v4 as uuidv4 } from 'uuid';
-/**
- * Azure Blob Storage Provider
- * Requires @azure/storage-blob package to be installed
- */ export class AzureProvider {
-    /**
-   * Initialize Azure provider with configuration
-   */ async initialize(config) {
+import { ImageCompressor } from '../utils/image-compressor.util';
+export class AzureProvider {
+    async initialize(config) {
         try {
-            // Dynamic import - only loads Azure SDK if this provider is used
-            const { BlobServiceClient } = await import('@azure/storage-blob');
+            const { BlobServiceClient, StorageSharedKeyCredential } = await import('@azure/storage-blob');
             this.accountName = config.accountName;
             this.containerName = config.containerName;
-            // Create BlobServiceClient
-            if (config.connectionString) {
-                this.blobServiceClient = BlobServiceClient.fromConnectionString(config.connectionString);
-            } else {
-                const { StorageSharedKeyCredential } = await import('@azure/storage-blob');
-                const sharedKeyCredential = new StorageSharedKeyCredential(config.accountName, config.accountKey);
-                this.blobServiceClient = new BlobServiceClient(`https://${config.accountName}.blob.core.windows.net`, sharedKeyCredential);
-            }
-            // Get container client
+            this.blobServiceClient = config.connectionString ? BlobServiceClient.fromConnectionString(config.connectionString) : new BlobServiceClient(`https://${config.accountName}.blob.core.windows.net`, new StorageSharedKeyCredential(config.accountName, config.accountKey));
             this.containerClient = this.blobServiceClient.getContainerClient(config.containerName);
-            // Ensure container exists
             await this.containerClient.createIfNotExists();
             this.logger.log(`Azure Provider initialized: account=${config.accountName}, container=${config.containerName}`);
-        } catch (_error) {
-            this.logger.error('Failed to initialize AzureProvider. Make sure @azure/storage-blob is installed.');
-            throw new Error('Azure Storage SDK not found. Install it with: npm install @azure/storage-blob');
+        } catch  {
+            throw new Error('Azure Storage SDK not found. Install: npm install @azure/storage-blob');
         }
     }
     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,
@@ -74,9 +46,7 @@ import { v4 as uuidv4 } from 'uuid';
             contentType = result.format;
         }
         const blobName = options.folderPath ? `${options.folderPath}/${fileName}` : fileName;
-        const blockBlobClient = this.containerClient.getBlockBlobClient(blobName);
-        // Upload to Azure
-        await blockBlobClient.upload(processedBuffer, processedBuffer.length, {
+        await this.containerClient.getBlockBlobClient(blobName).upload(processedBuffer, processedBuffer.length, {
             blobHTTPHeaders: {
                 blobContentType: contentType
             }
@@ -92,8 +62,7 @@ import { v4 as uuidv4 } from 'uuid';
         return Promise.all(files.map((file)=>this.uploadFile(file, options)));
     }
     async deleteFile(key) {
-        const blockBlobClient = this.containerClient.getBlockBlobClient(key);
-        await blockBlobClient.deleteIfExists();
+        await this.containerClient.getBlockBlobClient(key).deleteIfExists();
         this.logger.log(`Deleted file from Azure: ${key}`);
     }
     async deleteMultipleFiles(keys) {

package/fesm/providers/local-provider.js

@@ -32,6 +32,29 @@ import { v4 as uuidv4 } from 'uuid';
  * 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) {
+            this.logger.warn(`Path traversal attempt detected: ${targetPath}`);
+            throw new Error('Invalid path: Path traversal attempt 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 Error('Invalid file key: empty or invalid');
+        }
+        if (key.includes('\0')) {
+            throw new Error('Invalid file key: contains null bytes');
+        }
+    }
+    /**
    * 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
@@ -64,7 +87,11 @@ import { v4 as uuidv4 } from 'uuid';
         }
         // 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
@@ -87,14 +114,20 @@ import { v4 as uuidv4 } from 'uuid';
     }
     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;
@@ -107,7 +140,11 @@ import { v4 as uuidv4 } from 'uuid';
             }
             await fs.unlink(filePath);
             this.logger.log(`Deleted file from local storage: ${key}`);
-        } catch (_error) {
+        } catch (error) {
+            // Re-throw security errors
+            if (error instanceof Error && error.message.includes('Invalid')) {
+                throw error;
+            }
             this.logger.warn(`Failed to delete file from local storage: ${key}`);
         }
     }
@@ -134,36 +171,6 @@ import { v4 as uuidv4 } from 'uuid';
             return false;
         }
     }
-    /**
-   * Get the absolute path for a file key
-   * Key now includes basePath, so resolve from cwd
-   */ getAbsolutePath(key) {
-        return path.resolve(key);
-    }
-    /**
-   * Check if a file exists
-   */ async fileExists(key) {
-        try {
-            // Key now includes basePath, resolve from cwd
-            const filePath = path.resolve(key);
-            await fs.access(filePath);
-            return true;
-        } catch  {
-            return false;
-        }
-    }
-    /**
-   * Get file stats
-   */ async getFileStats(key) {
-        // Key now includes basePath, resolve from cwd
-        const filePath = path.resolve(key);
-        const stats = await fs.stat(filePath);
-        return {
-            size: stats.size,
-            createdAt: stats.birthtime,
-            modifiedAt: stats.mtime
-        };
-    }
     constructor(){
         _define_property(this, "logger", new Logger(LocalProvider.name));
         _define_property(this, "basePath", '');

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

@@ -1,17 +1,6 @@
 /**
- * OPTIONAL S3 Provider
- *
- * This provider requires @aws-sdk packages to be installed.
- * Only import this if you need AWS S3 storage.
- *
- * Installation:
- * npm install @aws-sdk/client-s3 @aws-sdk/lib-storage @aws-sdk/s3-request-presigner
- *
- * Usage:
- * import { S3Provider } from '@flusys/nestjs-storage/providers/s3-provider.optional';
- * import { StorageProviderRegistry, FileLocationEnum } from '@flusys/nestjs-storage';
- *
- * StorageProviderRegistry.register(FileLocationEnum.AWS, S3Provider);
+ * Optional AWS S3 Storage Provider
+ * Requires: npm install @aws-sdk/client-s3 @aws-sdk/lib-storage @aws-sdk/s3-request-presigner
  */ function _define_property(obj, key, value) {
     if (key in obj) {
         Object.defineProperty(obj, key, {
@@ -25,33 +14,26 @@
     }
     return obj;
 }
-import { ImageCompressor } from '../utils/image-compressor.util';
 import { Logger } from '@nestjs/common';
 import { v4 as uuidv4 } from 'uuid';
-/**
- * AWS S3 Storage Provider
- * Requires @aws-sdk packages to be installed
- */ export class S3Provider {
-    /**
-   * Initialize S3 provider with configuration
-   */ async initialize(config) {
+import { ImageCompressor } from '../utils/image-compressor.util';
+export class S3Provider {
+    async initialize(config) {
         try {
-            // Dynamic import - only loads AWS SDK if this provider is used
             const { S3Client } = await import('@aws-sdk/client-s3');
             this.region = config.region;
             this.bucketName = config.bucket;
             this.s3 = new S3Client({
                 region: config.region,
+                endpoint: config.endpoint,
                 credentials: config.accessKeyId && config.secretAccessKey ? {
                     accessKeyId: config.accessKeyId,
                     secretAccessKey: config.secretAccessKey
-                } : undefined,
-                endpoint: config.endpoint
+                } : undefined
             });
             this.logger.log(`S3 Provider initialized: region=${config.region}, bucket=${config.bucket}`);
-        } catch (_error) {
-            this.logger.error('Failed to initialize S3Provider. Make sure @aws-sdk packages are installed.');
-            throw new Error('AWS SDK not found. Install it with: npm install @aws-sdk/client-s3 @aws-sdk/lib-storage @aws-sdk/s3-request-presigner');
+        } catch  {
+            throw new Error('AWS SDK not found. Install: npm install @aws-sdk/client-s3 @aws-sdk/lib-storage @aws-sdk/s3-request-presigner');
         }
     }
     async uploadFile(file, options) {
@@ -59,7 +41,6 @@ import { v4 as uuidv4 } from 'uuid';
         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,
@@ -71,7 +52,7 @@ import { v4 as uuidv4 } from 'uuid';
             contentType = result.format;
         }
         const key = options.folderPath ? `${options.folderPath}/${fileName}` : fileName;
-        const upload = new Upload({
+        await new Upload({
             client: this.s3,
             params: {
                 Bucket: this.bucketName,
@@ -79,8 +60,7 @@ import { v4 as uuidv4 } from 'uuid';
                 Body: processedBuffer,
                 ContentType: contentType
             }
-        });
-        await upload.done();
+        }).done();
         return {
             name: fileName,
             key,
@@ -93,44 +73,40 @@ import { v4 as uuidv4 } from 'uuid';
     }
     async deleteFile(key) {
         const { DeleteObjectCommand } = await import('@aws-sdk/client-s3');
-        const command = new DeleteObjectCommand({
+        await this.s3.send(new DeleteObjectCommand({
             Bucket: this.bucketName,
             Key: key
-        });
-        await this.s3.send(command);
+        }));
         this.logger.log(`Deleted file from S3: ${key}`);
     }
     async deleteMultipleFiles(keys) {
         const { DeleteObjectsCommand } = await import('@aws-sdk/client-s3');
-        const command = new DeleteObjectsCommand({
+        await this.s3.send(new DeleteObjectsCommand({
             Bucket: this.bucketName,
             Delete: {
                 Objects: keys.map((key)=>({
                         Key: key
                     }))
             }
-        });
-        await this.s3.send(command);
+        }));
         this.logger.log(`Deleted ${keys.length} files from S3`);
     }
     async generatePresignedUrl(key, expiresInSeconds = 3600) {
         const { GetObjectCommand } = await import('@aws-sdk/client-s3');
         const { getSignedUrl } = await import('@aws-sdk/s3-request-presigner');
-        const command = new GetObjectCommand({
+        return getSignedUrl(this.s3, new GetObjectCommand({
             Bucket: this.bucketName,
             Key: key
-        });
-        return getSignedUrl(this.s3, command, {
+        }), {
             expiresIn: expiresInSeconds
         });
     }
     async healthCheck() {
         try {
             const { HeadBucketCommand } = await import('@aws-sdk/client-s3');
-            const command = new HeadBucketCommand({
+            await this.s3.send(new HeadBucketCommand({
                 Bucket: this.bucketName
-            });
-            await this.s3.send(command);
+            }));
             return true;
         } catch  {
             return false;
@@ -138,7 +114,7 @@ import { v4 as uuidv4 } from 'uuid';
     }
     constructor(){
         _define_property(this, "logger", new Logger(S3Provider.name));
-        _define_property(this, "s3", void 0); // S3Client - typed as any to avoid import
+        _define_property(this, "s3", void 0);
         _define_property(this, "bucketName", '');
         _define_property(this, "region", '');
     }