@devstroupe/devkit-nest 1.0.0 → 1.0.1

package/dist/auth/index.d.ts

@@ -0,0 +1,2 @@
+export * from './permissions.decorator';
+export * from './permissions.guard';

package/dist/auth/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./permissions.decorator"), exports);
+__exportStar(require("./permissions.guard"), exports);

package/dist/auth/permissions.decorator.d.ts

@@ -0,0 +1,2 @@
+export declare const PERMISSIONS_KEY = "devkit-permissions";
+export declare const Permissions: (...permissions: string[]) => import("@nestjs/common").CustomDecorator<string>;

package/dist/auth/permissions.decorator.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Permissions = exports.PERMISSIONS_KEY = void 0;
+const common_1 = require("@nestjs/common");
+exports.PERMISSIONS_KEY = 'devkit-permissions';
+const Permissions = (...permissions) => (0, common_1.SetMetadata)(exports.PERMISSIONS_KEY, permissions);
+exports.Permissions = Permissions;

package/dist/auth/permissions.guard.d.ts

@@ -0,0 +1,7 @@
+import { CanActivate, ExecutionContext } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+export declare class PermissionsGuard implements CanActivate {
+    private reflector;
+    constructor(reflector: Reflector);
+    canActivate(context: ExecutionContext): boolean;
+}

package/dist/auth/permissions.guard.js

@@ -0,0 +1,46 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PermissionsGuard = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const permissions_decorator_1 = require("./permissions.decorator");
+let PermissionsGuard = class PermissionsGuard {
+    reflector;
+    constructor(reflector) {
+        this.reflector = reflector;
+    }
+    canActivate(context) {
+        const requiredPermissions = this.reflector.getAllAndOverride(permissions_decorator_1.PERMISSIONS_KEY, [
+            context.getHandler(),
+            context.getClass(),
+        ]);
+        if (!requiredPermissions || requiredPermissions.length === 0) {
+            return true;
+        }
+        const request = context.switchToHttp().getRequest();
+        const user = request.user;
+        if (!user) {
+            return false; // Bloqueia acesso caso não esteja autenticado
+        }
+        // Atalho para super admin
+        if (user.role === 'ADMIN') {
+            return true;
+        }
+        const userPermissions = user.permissions || [];
+        return requiredPermissions.every((permission) => userPermissions.includes(permission));
+    }
+};
+exports.PermissionsGuard = PermissionsGuard;
+exports.PermissionsGuard = PermissionsGuard = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [core_1.Reflector])
+], PermissionsGuard);

package/dist/auth/permissions.guard.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/auth/permissions.guard.test.js

@@ -0,0 +1,100 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_test_1 = require("node:test");
+const assert = __importStar(require("node:assert"));
+const permissions_guard_1 = require("./permissions.guard");
+(0, node_test_1.describe)('PermissionsGuard', () => {
+    const createMockContext = (user) => {
+        return {
+            switchToHttp: () => ({
+                getRequest: () => ({ user }),
+            }),
+            getHandler: () => ({}),
+            getClass: () => ({}),
+        };
+    };
+    (0, node_test_1.test)('deve permitir acesso se não houver permissões exigidas', () => {
+        const mockReflector = {
+            getAllAndOverride: () => undefined,
+        };
+        const guard = new permissions_guard_1.PermissionsGuard(mockReflector);
+        const context = createMockContext({ role: 'USER', permissions: [] });
+        const result = guard.canActivate(context);
+        assert.strictEqual(result, true);
+    });
+    (0, node_test_1.test)('deve permitir acesso se o usuário for ADMIN (super admin)', () => {
+        const mockReflector = {
+            getAllAndOverride: () => ['create:cabin'],
+        };
+        const guard = new permissions_guard_1.PermissionsGuard(mockReflector);
+        const context = createMockContext({ role: 'ADMIN', permissions: [] });
+        const result = guard.canActivate(context);
+        assert.strictEqual(result, true);
+    });
+    (0, node_test_1.test)('deve permitir acesso se o usuário tiver todas as permissões exigidas', () => {
+        const mockReflector = {
+            getAllAndOverride: () => ['read:cabin', 'update:cabin'],
+        };
+        const guard = new permissions_guard_1.PermissionsGuard(mockReflector);
+        const context = createMockContext({
+            role: 'USER',
+            permissions: ['read:cabin', 'update:cabin', 'delete:cabin'],
+        });
+        const result = guard.canActivate(context);
+        assert.strictEqual(result, true);
+    });
+    (0, node_test_1.test)('deve negar acesso se o usuário não tiver todas as permissões exigidas', () => {
+        const mockReflector = {
+            getAllAndOverride: () => ['read:cabin', 'update:cabin'],
+        };
+        const guard = new permissions_guard_1.PermissionsGuard(mockReflector);
+        const context = createMockContext({
+            role: 'USER',
+            permissions: ['read:cabin'], // Falta 'update:cabin'
+        });
+        const result = guard.canActivate(context);
+        assert.strictEqual(result, false);
+    });
+    (0, node_test_1.test)('deve negar acesso se não houver usuário autenticado na request', () => {
+        const mockReflector = {
+            getAllAndOverride: () => ['read:cabin'],
+        };
+        const guard = new permissions_guard_1.PermissionsGuard(mockReflector);
+        const context = createMockContext(undefined);
+        const result = guard.canActivate(context);
+        assert.strictEqual(result, false);
+    });
+});

package/dist/index.d.ts

@@ -2,3 +2,5 @@ export * from './database/factory-where';
 export * from './database/base.repository';
 export * from './database/typeorm-query.builder';
 export * from './http/base-crud.controller';
+export * from './storage';
+export * from './auth';

package/dist/index.js

@@ -18,3 +18,5 @@ __exportStar(require("./database/factory-where"), exports);
 __exportStar(require("./database/base.repository"), exports);
 __exportStar(require("./database/typeorm-query.builder"), exports);
 __exportStar(require("./http/base-crud.controller"), exports);
+__exportStar(require("./storage"), exports);
+__exportStar(require("./auth"), exports);

package/dist/storage/drivers/local.storage.d.ts

@@ -0,0 +1,11 @@
+import { StorageService } from '../storage.service';
+import { StorageFile, UploadOptions, UploadResult, LocalStorageOptions } from '../storage.types';
+export declare class LocalStorageService implements StorageService {
+    private readonly storagePath;
+    private readonly baseUrl;
+    constructor(options: LocalStorageOptions);
+    upload(file: StorageFile, options?: UploadOptions): Promise<UploadResult>;
+    delete(key: string): Promise<void>;
+    getUrl(key: string): Promise<string>;
+    getSignedUrl(key: string, expiresIn?: number): Promise<string>;
+}

package/dist/storage/drivers/local.storage.js

@@ -0,0 +1,114 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalStorageService = void 0;
+const common_1 = require("@nestjs/common");
+const fs = __importStar(require("fs/promises"));
+const path = __importStar(require("path"));
+const crypto = __importStar(require("crypto"));
+let LocalStorageService = class LocalStorageService {
+    storagePath;
+    baseUrl;
+    constructor(options) {
+        this.storagePath = path.resolve(options.storagePath);
+        this.baseUrl = options.baseUrl || '';
+    }
+    async upload(file, options) {
+        // 1. Sanitizar a extensão do arquivo
+        const origExt = path.extname(file.originalname);
+        const sanitizedExt = origExt.replace(/[^a-zA-Z0-9.]/g, '');
+        // 2. Determinar nome do arquivo (UUID v4 por padrão)
+        const filename = options?.filename
+            ? options.filename.replace(/[^a-zA-Z0-9._-]/g, '')
+            : `${crypto.randomUUID()}${sanitizedExt}`;
+        // 3. Resolver caminho da subpasta e mitigar Directory Traversal
+        const subPath = options?.path ? path.normalize(options.path).replace(/^(\.\.(\/|\\|$))+/, '') : '';
+        const targetDir = path.resolve(this.storagePath, subPath);
+        // Adicionamos a barra final para segurança máxima de limite de diretório
+        const rootPrefix = this.storagePath.endsWith(path.sep) ? this.storagePath : this.storagePath + path.sep;
+        if (!targetDir.startsWith(rootPrefix) && targetDir !== this.storagePath) {
+            throw new Error('Directory traversal attempt detected');
+        }
+        const targetFile = path.resolve(targetDir, filename);
+        if (!targetFile.startsWith(rootPrefix)) {
+            throw new Error('File path resolves outside of storage boundary');
+        }
+        // 4. Garantir existência da pasta e escrever o arquivo
+        await fs.mkdir(targetDir, { recursive: true });
+        await fs.writeFile(targetFile, file.buffer);
+        const relativeKey = path.relative(this.storagePath, targetFile).replace(/\\/g, '/');
+        const url = this.baseUrl ? `${this.baseUrl.replace(/\/$/, '')}/${relativeKey}` : relativeKey;
+        return {
+            key: relativeKey,
+            url,
+            size: file.size,
+            mimetype: file.mimetype,
+        };
+    }
+    async delete(key) {
+        const targetFile = path.resolve(this.storagePath, key);
+        const rootPrefix = this.storagePath.endsWith(path.sep) ? this.storagePath : this.storagePath + path.sep;
+        if (!targetFile.startsWith(rootPrefix)) {
+            throw new Error('Directory traversal attempt detected on deletion');
+        }
+        try {
+            await fs.unlink(targetFile);
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT')
+                throw err;
+        }
+    }
+    async getUrl(key) {
+        return this.baseUrl ? `${this.baseUrl.replace(/\/$/, '')}/${key}` : key;
+    }
+    async getSignedUrl(key, expiresIn) {
+        return this.getUrl(key);
+    }
+};
+exports.LocalStorageService = LocalStorageService;
+exports.LocalStorageService = LocalStorageService = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [Object])
+], LocalStorageService);

package/dist/storage/drivers/local.storage.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/storage/drivers/local.storage.test.js

@@ -0,0 +1,106 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_test_1 = require("node:test");
+const assert = __importStar(require("node:assert"));
+const fs = __importStar(require("node:fs/promises"));
+const path = __importStar(require("node:path"));
+const local_storage_1 = require("./local.storage");
+(0, node_test_1.describe)('LocalStorageService', () => {
+    const tmpDir = path.resolve(__dirname, '../../../../tmp-storage-test');
+    let service;
+    (0, node_test_1.before)(async () => {
+        await fs.mkdir(tmpDir, { recursive: true });
+        service = new local_storage_1.LocalStorageService({
+            storagePath: tmpDir,
+            baseUrl: 'http://localhost:3000/files',
+        });
+    });
+    (0, node_test_1.after)(async () => {
+        await fs.rm(tmpDir, { recursive: true, force: true });
+    });
+    (0, node_test_1.test)('deve realizar upload de arquivo com sucesso', async () => {
+        const file = {
+            originalname: 'test-image.png',
+            mimetype: 'image/png',
+            buffer: Buffer.from('dummy content'),
+            size: 13,
+        };
+        const result = await service.upload(file, { path: 'images' });
+        assert.ok(result.key);
+        assert.ok(result.url.startsWith('http://localhost:3000/files/images/'));
+        assert.strictEqual(result.size, 13);
+        assert.strictEqual(result.mimetype, 'image/png');
+        // Verificar se o arquivo realmente foi criado no sistema de arquivos
+        const filePath = path.resolve(tmpDir, result.key);
+        const content = await fs.readFile(filePath);
+        assert.strictEqual(content.toString(), 'dummy content');
+    });
+    (0, node_test_1.test)('deve deletar arquivo com sucesso', async () => {
+        const file = {
+            originalname: 'to-delete.txt',
+            mimetype: 'text/plain',
+            buffer: Buffer.from('delete me'),
+            size: 9,
+        };
+        const uploadResult = await service.upload(file);
+        const filePath = path.resolve(tmpDir, uploadResult.key);
+        // Verificar que existe
+        await fs.access(filePath);
+        // Deletar
+        await service.delete(uploadResult.key);
+        // Verificar que não existe mais
+        await assert.rejects(async () => {
+            await fs.access(filePath);
+        });
+    });
+    (0, node_test_1.test)('deve rejeitar upload com Directory Traversal em options.path', async () => {
+        const file = {
+            originalname: 'hacker.txt',
+            mimetype: 'text/plain',
+            buffer: Buffer.from('malicious'),
+            size: 9,
+        };
+        // Tenta gravar fora da raiz
+        await assert.rejects(async () => {
+            await service.upload(file, { path: '../../' });
+        }, /Directory traversal attempt detected/);
+    });
+    (0, node_test_1.test)('deve rejeitar exclusão com Directory Traversal em key', async () => {
+        await assert.rejects(async () => {
+            await service.delete('../../../etc/passwd');
+        }, /Directory traversal attempt detected/);
+    });
+});

package/dist/storage/drivers/s3.storage.d.ts

@@ -0,0 +1,12 @@
+import { StorageService } from '../storage.service';
+import { StorageFile, UploadOptions, UploadResult, S3StorageOptions, R2StorageOptions } from '../storage.types';
+export declare class S3StorageService implements StorageService {
+    private readonly client;
+    private readonly bucket;
+    private readonly publicUrl?;
+    constructor(options: S3StorageOptions | R2StorageOptions, isR2?: boolean);
+    upload(file: StorageFile, options?: UploadOptions): Promise<UploadResult>;
+    delete(key: string): Promise<void>;
+    getUrl(key: string): Promise<string>;
+    getSignedUrl(key: string, expiresIn?: number): Promise<string>;
+}

package/dist/storage/drivers/s3.storage.js

@@ -0,0 +1,138 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.S3StorageService = void 0;
+const common_1 = require("@nestjs/common");
+const client_s3_1 = require("@aws-sdk/client-s3");
+const s3_request_presigner_1 = require("@aws-sdk/s3-request-presigner");
+const crypto = __importStar(require("crypto"));
+const path = __importStar(require("path"));
+let S3StorageService = class S3StorageService {
+    client;
+    bucket;
+    publicUrl;
+    constructor(options, isR2 = false) {
+        this.bucket = options.bucket;
+        if (isR2) {
+            const r2Opts = options;
+            this.publicUrl = r2Opts.publicUrl;
+            this.client = new client_s3_1.S3Client({
+                endpoint: `https://${r2Opts.accountId}.r2.cloudflarestorage.com`,
+                region: 'auto',
+                credentials: {
+                    accessKeyId: r2Opts.accessKeyId,
+                    secretAccessKey: r2Opts.secretAccessKey,
+                },
+                forcePathStyle: true,
+            });
+        }
+        else {
+            const s3Opts = options;
+            this.client = new client_s3_1.S3Client({
+                region: s3Opts.region || 'us-east-1',
+                credentials: {
+                    accessKeyId: s3Opts.accessKeyId,
+                    secretAccessKey: s3Opts.secretAccessKey,
+                },
+                endpoint: s3Opts.endpoint,
+                forcePathStyle: s3Opts.forcePathStyle,
+            });
+        }
+    }
+    async upload(file, options) {
+        const origExt = path.extname(file.originalname);
+        const sanitizedExt = origExt.replace(/[^a-zA-Z0-9.]/g, '');
+        const filename = options?.filename
+            ? options.filename.replace(/[^a-zA-Z0-9._-]/g, '')
+            : `${crypto.randomUUID()}${sanitizedExt}`;
+        const subPath = options?.path ? options.path.replace(/^\/+|\/+$/g, '') : '';
+        const key = subPath ? `${subPath}/${filename}` : filename;
+        await this.client.send(new client_s3_1.PutObjectCommand({
+            Bucket: this.bucket,
+            Key: key,
+            Body: file.buffer,
+            ContentType: file.mimetype,
+        }));
+        const url = await this.getUrl(key);
+        return {
+            key,
+            url,
+            size: file.size,
+            mimetype: file.mimetype,
+        };
+    }
+    async delete(key) {
+        await this.client.send(new client_s3_1.DeleteObjectCommand({
+            Bucket: this.bucket,
+            Key: key,
+        }));
+    }
+    async getUrl(key) {
+        if (this.publicUrl) {
+            return `${this.publicUrl.replace(/\/$/, '')}/${key}`;
+        }
+        const endpointFn = this.client.config.endpoint;
+        if (endpointFn && typeof endpointFn === 'function') {
+            const endpoint = await endpointFn();
+            if (endpoint) {
+                const portStr = endpoint.port ? `:${endpoint.port}` : '';
+                const baseHost = `${endpoint.protocol}//${endpoint.hostname}${portStr}`;
+                return `${baseHost}/${this.bucket}/${key}`;
+            }
+        }
+        return `https://${this.bucket}.s3.amazonaws.com/${key}`;
+    }
+    async getSignedUrl(key, expiresIn = 3600) {
+        const command = new client_s3_1.GetObjectCommand({
+            Bucket: this.bucket,
+            Key: key,
+        });
+        return (0, s3_request_presigner_1.getSignedUrl)(this.client, command, { expiresIn });
+    }
+};
+exports.S3StorageService = S3StorageService;
+exports.S3StorageService = S3StorageService = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [Object, Boolean])
+], S3StorageService);

package/dist/storage/index.d.ts

@@ -0,0 +1,5 @@
+export * from './storage.types';
+export * from './storage.service';
+export * from './storage.module';
+export * from './drivers/local.storage';
+export * from './drivers/s3.storage';

package/dist/storage/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./storage.types"), exports);
+__exportStar(require("./storage.service"), exports);
+__exportStar(require("./storage.module"), exports);
+__exportStar(require("./drivers/local.storage"), exports);
+__exportStar(require("./drivers/s3.storage"), exports);

package/dist/storage/storage.module.d.ts

@@ -0,0 +1,11 @@
+import { DynamicModule } from '@nestjs/common';
+import { StorageOptions } from './storage.types';
+export declare const STORAGE_OPTIONS_TOKEN = "STORAGE_OPTIONS_TOKEN";
+export declare class StorageModule {
+    static register(options: StorageOptions): DynamicModule;
+    static registerAsync(options: {
+        useFactory: (...args: any[]) => Promise<StorageOptions> | StorageOptions;
+        inject?: any[];
+    }): DynamicModule;
+    private static createServiceInstance;
+}

package/dist/storage/storage.module.js

@@ -0,0 +1,81 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var StorageModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StorageModule = exports.STORAGE_OPTIONS_TOKEN = void 0;
+const common_1 = require("@nestjs/common");
+const storage_service_1 = require("./storage.service");
+const local_storage_1 = require("./drivers/local.storage");
+const s3_storage_1 = require("./drivers/s3.storage");
+exports.STORAGE_OPTIONS_TOKEN = 'STORAGE_OPTIONS_TOKEN';
+let StorageModule = StorageModule_1 = class StorageModule {
+    static register(options) {
+        const storageServiceProvider = {
+            provide: storage_service_1.StorageService,
+            useFactory: () => {
+                return this.createServiceInstance(options);
+            },
+        };
+        return {
+            module: StorageModule_1,
+            providers: [
+                { provide: exports.STORAGE_OPTIONS_TOKEN, useValue: options },
+                storageServiceProvider,
+            ],
+            exports: [storage_service_1.StorageService],
+        };
+    }
+    static registerAsync(options) {
+        const storageServiceProvider = {
+            provide: storage_service_1.StorageService,
+            useFactory: async (opts) => {
+                return this.createServiceInstance(opts);
+            },
+            inject: [exports.STORAGE_OPTIONS_TOKEN],
+        };
+        return {
+            module: StorageModule_1,
+            imports: [],
+            providers: [
+                {
+                    provide: exports.STORAGE_OPTIONS_TOKEN,
+                    useFactory: options.useFactory,
+                    inject: options.inject || [],
+                },
+                storageServiceProvider,
+            ],
+            exports: [storage_service_1.StorageService],
+        };
+    }
+    static createServiceInstance(options) {
+        switch (options.driver) {
+            case 'local':
+                if (!options.local) {
+                    throw new Error('Configuração de "local" não fornecida para o driver local.');
+                }
+                return new local_storage_1.LocalStorageService(options.local);
+            case 's3':
+                if (!options.s3) {
+                    throw new Error('Configuração de "s3" não fornecida para o driver s3.');
+                }
+                return new s3_storage_1.S3StorageService(options.s3, false);
+            case 'r2':
+                if (!options.r2) {
+                    throw new Error('Configuração de "r2" não fornecida para o driver r2.');
+                }
+                return new s3_storage_1.S3StorageService(options.r2, true);
+            default:
+                throw new Error(`Driver de storage não suportado: ${options.driver}`);
+        }
+    }
+};
+exports.StorageModule = StorageModule;
+exports.StorageModule = StorageModule = StorageModule_1 = __decorate([
+    (0, common_1.Global)(),
+    (0, common_1.Module)({})
+], StorageModule);

package/dist/storage/storage.module.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/storage/storage.module.test.js

@@ -0,0 +1,113 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_test_1 = require("node:test");
+const assert = __importStar(require("node:assert"));
+const storage_module_1 = require("./storage.module");
+const storage_service_1 = require("./storage.service");
+const local_storage_1 = require("./drivers/local.storage");
+const s3_storage_1 = require("./drivers/s3.storage");
+(0, node_test_1.describe)('StorageModule', () => {
+    (0, node_test_1.test)('deve instanciar LocalStorageService quando configurado driver local', () => {
+        const dynamicModule = storage_module_1.StorageModule.register({
+            driver: 'local',
+            local: {
+                storagePath: './tmp-test-module',
+            },
+        });
+        assert.ok(dynamicModule.providers);
+        const serviceProvider = dynamicModule.exports?.find(e => e === storage_service_1.StorageService);
+        assert.ok(serviceProvider);
+        const factoryProvider = dynamicModule.providers?.find((p) => p.provide === storage_service_1.StorageService);
+        assert.ok(factoryProvider);
+        assert.ok(factoryProvider.useFactory);
+        const instance = factoryProvider.useFactory();
+        assert.ok(instance instanceof local_storage_1.LocalStorageService);
+    });
+    (0, node_test_1.test)('deve instanciar S3StorageService quando configurado driver s3', () => {
+        const dynamicModule = storage_module_1.StorageModule.register({
+            driver: 's3',
+            s3: {
+                bucket: 'test-bucket',
+                accessKeyId: 'key',
+                secretAccessKey: 'secret',
+                region: 'us-east-1',
+            },
+        });
+        const factoryProvider = dynamicModule.providers?.find((p) => p.provide === storage_service_1.StorageService);
+        assert.ok(factoryProvider);
+        const instance = factoryProvider.useFactory();
+        assert.ok(instance instanceof s3_storage_1.S3StorageService);
+    });
+    (0, node_test_1.test)('deve instanciar S3StorageService quando configurado driver r2', () => {
+        const dynamicModule = storage_module_1.StorageModule.register({
+            driver: 'r2',
+            r2: {
+                bucket: 'test-bucket',
+                accountId: 'account-id',
+                accessKeyId: 'key',
+                secretAccessKey: 'secret',
+            },
+        });
+        const factoryProvider = dynamicModule.providers?.find((p) => p.provide === storage_service_1.StorageService);
+        assert.ok(factoryProvider);
+        const instance = factoryProvider.useFactory();
+        assert.ok(instance instanceof s3_storage_1.S3StorageService);
+    });
+    (0, node_test_1.test)('deve lançar erro se configurações do driver local não forem fornecidas', () => {
+        const dynamicModule = storage_module_1.StorageModule.register({ driver: 'local' });
+        const factoryProvider = dynamicModule.providers?.find((p) => p.provide === storage_service_1.StorageService);
+        assert.ok(factoryProvider);
+        assert.throws(() => {
+            factoryProvider.useFactory();
+        }, /Configuração de "local" não fornecida/);
+    });
+    (0, node_test_1.test)('deve lançar erro se configurações do driver s3 não forem fornecidas', () => {
+        const dynamicModule = storage_module_1.StorageModule.register({ driver: 's3' });
+        const factoryProvider = dynamicModule.providers?.find((p) => p.provide === storage_service_1.StorageService);
+        assert.ok(factoryProvider);
+        assert.throws(() => {
+            factoryProvider.useFactory();
+        }, /Configuração de "s3" não fornecida/);
+    });
+    (0, node_test_1.test)('deve lançar erro se configurações do driver r2 não forem fornecidas', () => {
+        const dynamicModule = storage_module_1.StorageModule.register({ driver: 'r2' });
+        const factoryProvider = dynamicModule.providers?.find((p) => p.provide === storage_service_1.StorageService);
+        assert.ok(factoryProvider);
+        assert.throws(() => {
+            factoryProvider.useFactory();
+        }, /Configuração de "r2" não fornecida/);
+    });
+});

package/dist/storage/storage.service.d.ts

@@ -0,0 +1,7 @@
+import { StorageFile, UploadOptions, UploadResult } from './storage.types';
+export declare abstract class StorageService {
+    abstract upload(file: StorageFile, options?: UploadOptions): Promise<UploadResult>;
+    abstract delete(key: string): Promise<void>;
+    abstract getUrl(key: string): Promise<string>;
+    abstract getSignedUrl(key: string, expiresIn?: number): Promise<string>;
+}

package/dist/storage/storage.service.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StorageService = void 0;
+class StorageService {
+}
+exports.StorageService = StorageService;

package/dist/storage/storage.types.d.ts

@@ -0,0 +1,42 @@
+export type StorageDriver = 'local' | 's3' | 'r2';
+export interface LocalStorageOptions {
+    storagePath: string;
+    baseUrl?: string;
+}
+export interface S3StorageOptions {
+    bucket: string;
+    region?: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    endpoint?: string;
+    forcePathStyle?: boolean;
+}
+export interface R2StorageOptions {
+    bucket: string;
+    accountId: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    publicUrl?: string;
+}
+export interface StorageOptions {
+    driver: StorageDriver;
+    local?: LocalStorageOptions;
+    s3?: S3StorageOptions;
+    r2?: R2StorageOptions;
+}
+export interface StorageFile {
+    originalname: string;
+    mimetype: string;
+    buffer: Buffer;
+    size: number;
+}
+export interface UploadOptions {
+    path?: string;
+    filename?: string;
+}
+export interface UploadResult {
+    key: string;
+    url: string;
+    size: number;
+    mimetype: string;
+}

package/dist/storage/storage.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devstroupe/devkit-nest",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "DevsTroupe Development Kit — NestJS base classes: BaseRepository, BaseCrudController and query parsers",
   "license": "MIT",
   "keywords": [
@@ -29,7 +29,9 @@
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "dependencies": {
-    "@devstroupe/devkit-core": "^1.0.0"
+    "@devstroupe/devkit-core": "^1.0.0",
+    "@aws-sdk/client-s3": "^3.500.0",
+    "@aws-sdk/s3-request-presigner": "^3.500.0"
   },
   "peerDependencies": {
     "@nestjs/common": "^10.0.0 || ^11.0.0",