nestforge-generator 0.1.0

package/templates/typeorm/src/common/guards/permissions.guard.spec.ts

@@ -0,0 +1,54 @@
+// nestforge:feature-file:rbac
+import { describe, expect, it, vi } from 'vitest';
+import { ExecutionContext } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { Role } from '../constants/role.enum';
+import { Permission } from '../constants/permissions';
+import { PermissionsGuard } from './permissions.guard';
+
+function createContext(user?: { role: Role }): ExecutionContext {
+    return {
+        switchToHttp: () => ({ getRequest: () => ({ user }) }),
+        getHandler: () => ({}),
+        getClass: () => ({}),
+    } as unknown as ExecutionContext;
+}
+
+describe('PermissionsGuard', () => {
+    it('libera acesso quando a rota não exige nenhuma permissão', () => {
+        const reflector = { getAllAndOverride: vi.fn().mockReturnValue(undefined) } as unknown as Reflector;
+        const guard = new PermissionsGuard(reflector);
+
+        expect(guard.canActivate(createContext({ role: Role.USER }))).toBe(true);
+    });
+
+    it('libera acesso quando a role do usuário tem a permissão exigida', () => {
+        const reflector = {
+            getAllAndOverride: vi.fn().mockReturnValue([Permission.UserRead]),
+        } as unknown as Reflector;
+        const guard = new PermissionsGuard(reflector);
+
+        expect(guard.canActivate(createContext({ role: Role.USER }))).toBe(true);
+    });
+
+    it('bloqueia acesso quando a role do usuário não tem a permissão exigida', () => {
+        const reflector = {
+            getAllAndOverride: vi.fn().mockReturnValue([Permission.UserDelete]),
+        } as unknown as Reflector;
+        const guard = new PermissionsGuard(reflector);
+
+        expect(guard.canActivate(createContext({ role: Role.USER }))).toBe(false);
+    });
+
+    it('exige todas as permissões quando mais de uma é requisitada', () => {
+        const reflector = {
+            getAllAndOverride: vi.fn().mockReturnValue([Permission.UserRead, Permission.UserUpdate]),
+        } as unknown as Reflector;
+        const guard = new PermissionsGuard(reflector);
+
+        // MANAGER tem user:read e user:update
+        expect(guard.canActivate(createContext({ role: Role.MANAGER }))).toBe(true);
+        // USER só tem user:read
+        expect(guard.canActivate(createContext({ role: Role.USER }))).toBe(false);
+    });
+});

package/templates/typeorm/src/common/guards/permissions.guard.ts

@@ -0,0 +1,28 @@
+// nestforge:feature-file:rbac
+import { CanActivate, ExecutionContext, Injectable } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { Role } from '../constants/role.enum';
+import { PERMISSIONS_KEY } from '../decorators/permissions.decorator';
+import { Permission } from '../constants/permissions';
+import { ROLE_PERMISSIONS } from '../constants/role-permissions';
+
+@Injectable()
+export class PermissionsGuard implements CanActivate {
+    constructor(private reflector: Reflector) { }
+
+    canActivate(context: ExecutionContext): boolean {
+        const requiredPermissions = this.reflector.getAllAndOverride<Permission[]>(
+            PERMISSIONS_KEY,
+            [context.getHandler(), context.getClass()],
+        );
+
+        if (!requiredPermissions || requiredPermissions.length === 0) {
+            return true;
+        }
+
+        const { user } = context.switchToHttp().getRequest();
+        const userPermissions = ROLE_PERMISSIONS[user?.role as Role] ?? [];
+
+        return requiredPermissions.every((permission) => userPermissions.includes(permission));
+    }
+}

package/templates/typeorm/src/common/guards/roles.guard.spec.ts

@@ -0,0 +1,37 @@
+// nestforge:feature-file:rbac
+import { describe, expect, it, vi } from 'vitest';
+import { ExecutionContext } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { Role } from '../constants/role.enum';
+import { RolesGuard } from './roles.guard';
+
+function createContext(user?: { role: Role }): ExecutionContext {
+    return {
+        switchToHttp: () => ({ getRequest: () => ({ user }) }),
+        getHandler: () => ({}),
+        getClass: () => ({}),
+    } as unknown as ExecutionContext;
+}
+
+describe('RolesGuard', () => {
+    it('libera acesso quando a rota não exige nenhuma role', () => {
+        const reflector = { getAllAndOverride: vi.fn().mockReturnValue(undefined) } as unknown as Reflector;
+        const guard = new RolesGuard(reflector);
+
+        expect(guard.canActivate(createContext({ role: Role.USER }))).toBe(true);
+    });
+
+    it('libera acesso quando o usuário tem a role exigida', () => {
+        const reflector = { getAllAndOverride: vi.fn().mockReturnValue([Role.ADMIN]) } as unknown as Reflector;
+        const guard = new RolesGuard(reflector);
+
+        expect(guard.canActivate(createContext({ role: Role.ADMIN }))).toBe(true);
+    });
+
+    it('bloqueia acesso quando o usuário não tem a role exigida', () => {
+        const reflector = { getAllAndOverride: vi.fn().mockReturnValue([Role.ADMIN]) } as unknown as Reflector;
+        const guard = new RolesGuard(reflector);
+
+        expect(guard.canActivate(createContext({ role: Role.USER }))).toBe(false);
+    });
+});

package/templates/typeorm/src/common/guards/roles.guard.ts

@@ -0,0 +1,24 @@
+// nestforge:feature-file:rbac
+import { CanActivate, ExecutionContext, Injectable } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { Role } from '../constants/role.enum';
+import { ROLES_KEY } from '../decorators/roles.decorator';
+
+@Injectable()
+export class RolesGuard implements CanActivate {
+  constructor(private reflector: Reflector) {}
+
+  canActivate(context: ExecutionContext): boolean {
+    const requiredRoles = this.reflector.getAllAndOverride<Role[]>(ROLES_KEY, [
+      context.getHandler(),
+      context.getClass(),
+    ]);
+
+    if (!requiredRoles || requiredRoles.length === 0) {
+      return true;
+    }
+
+    const { user } = context.switchToHttp().getRequest();
+    return requiredRoles.includes(user?.role);
+  }
+}

package/templates/typeorm/src/common/interceptors/logging.interceptor.ts

@@ -0,0 +1,23 @@
+import {
+  CallHandler,
+  ExecutionContext,
+  Injectable,
+  NestInterceptor,
+} from '@nestjs/common';
+import { Observable, tap } from 'rxjs';
+
+@Injectable()
+export class LoggingInterceptor implements NestInterceptor {
+  intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {
+    const request = context.switchToHttp().getRequest();
+    const { method, url } = request;
+    const start = Date.now();
+
+    return next.handle().pipe(
+      tap(() => {
+        const duration = Date.now() - start;
+        console.log(`[${method}] ${url} - ${duration}ms`);
+      }),
+    );
+  }
+}

package/templates/typeorm/src/common/middleware/csrf.middleware.spec.ts

@@ -0,0 +1,97 @@
+// nestforge:feature-file:auth:session
+import { ForbiddenException } from '@nestjs/common';
+import { NextFunction, Request, Response } from 'express';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { CsrfMiddleware } from './csrf.middleware';
+
+describe('CsrfMiddleware', () => {
+    let middleware: CsrfMiddleware;
+    let response: Response;
+    let next: ReturnType<typeof vi.fn>;
+
+    beforeEach(() => {
+        middleware = new CsrfMiddleware();
+        response = {} as Response;
+        next = vi.fn();
+    });
+
+    function createRequest(
+        method: string,
+        sessionToken?: string,
+        headerToken?: string,
+    ): Request {
+        return {
+            method,
+            session: {
+                csrfToken: sessionToken,
+            },
+            get: vi.fn((header: string) => {
+                if (header.toLowerCase() === 'x-csrf-token') {
+                    return headerToken;
+                }
+
+                return undefined;
+            }),
+        } as unknown as Request;
+    }
+
+    it.each(['GET', 'HEAD', 'OPTIONS'])(
+        'permite o método seguro %s sem token',
+        (method) => {
+            const request = createRequest(method);
+
+            middleware.use(
+                request,
+                response,
+                next as unknown as NextFunction,
+            );
+
+            expect(next).toHaveBeenCalledOnce();
+        },
+    );
+
+    it('rejeita uma requisição sem token CSRF', () => {
+        const request = createRequest('POST');
+
+        expect(() =>
+            middleware.use(
+                request,
+                response,
+                next as unknown as NextFunction,
+            ),
+        ).toThrow(ForbiddenException);
+
+        expect(next).not.toHaveBeenCalled();
+    });
+
+    it('rejeita quando o token do header é diferente da sessão', () => {
+        const request = createRequest(
+            'PATCH',
+            'session-token',
+            'invalid-token',
+        );
+
+        expect(() =>
+            middleware.use(
+                request,
+                response,
+                next as unknown as NextFunction,
+            ),
+        ).toThrow(ForbiddenException);
+
+        expect(next).not.toHaveBeenCalled();
+    });
+
+    it('permite quando o token corresponde ao valor da sessão', () => {
+        const token = 'a'.repeat(64);
+        const request = createRequest('DELETE', token, token);
+
+        middleware.use(
+            request,
+            response,
+            next as unknown as NextFunction,
+        );
+
+        expect(next).toHaveBeenCalledOnce();
+    });
+});

package/templates/typeorm/src/common/middleware/csrf.middleware.ts

@@ -0,0 +1,46 @@
+// nestforge:feature-file:auth:session
+import {
+    ForbiddenException,
+    Injectable,
+    NestMiddleware,
+} from '@nestjs/common';
+import { timingSafeEqual } from 'node:crypto';
+import { NextFunction, Request, Response } from 'express';
+
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+const CSRF_HEADER = 'x-csrf-token';
+
+@Injectable()
+export class CsrfMiddleware implements NestMiddleware {
+    use(request: Request, _response: Response, next: NextFunction) {
+        if (SAFE_METHODS.has(request.method)) {
+            next();
+            return;
+        }
+
+        const sessionToken = request.session?.csrfToken;
+        const headerToken = request.get(CSRF_HEADER);
+
+        if (
+            !sessionToken ||
+            !headerToken ||
+            !this.tokensMatch(sessionToken, headerToken)
+        ) {
+            throw new ForbiddenException(
+                'Token CSRF inválido ou ausente',
+            );
+        }
+
+        next();
+    }
+
+    private tokensMatch(expected: string, received: string): boolean {
+        const expectedBuffer = Buffer.from(expected, 'utf8');
+        const receivedBuffer = Buffer.from(received, 'utf8');
+
+        return (
+            expectedBuffer.length === receivedBuffer.length &&
+            timingSafeEqual(expectedBuffer, receivedBuffer)
+        );
+    }
+}

package/templates/typeorm/src/common/utils/avatar-storage.util.ts

@@ -0,0 +1,32 @@
+import { BadRequestException } from '@nestjs/common';
+import { randomUUID } from 'crypto';
+import { diskStorage } from 'multer';
+import { extname } from 'path';
+
+const ALLOWED_MIME_TYPES = ['image/png', 'image/jpeg', 'image/webp'];
+
+export const avatarStorage = diskStorage({
+    destination: './uploads/avatars',
+    filename: (_req, file, callback) => {
+        const uniqueName = `${randomUUID()}${extname(file.originalname)}`;
+        callback(null, uniqueName);
+    },
+});
+
+export function avatarFileFilter(
+    _req: unknown,
+    file: Express.Multer.File,
+    callback: (error: Error | null, acceptFile: boolean) => void,
+) {
+    if (!ALLOWED_MIME_TYPES.includes(file.mimetype)) {
+        callback(
+            new BadRequestException('Formato de imagem não suportado (use PNG, JPEG ou WEBP)'),
+            false,
+        );
+        return;
+    }
+
+    callback(null, true);
+}
+
+export const AVATAR_MAX_SIZE_BYTES = 2 * 1024 * 1024; // 2MB

package/templates/typeorm/src/common/utils/hash.util.ts

@@ -0,0 +1,5 @@
+import { createHash } from 'crypto';
+
+export function sha256(value: string): string {
+  return createHash('sha256').update(value).digest('hex');
+}

package/templates/typeorm/src/config/env.validation.ts

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+
+const envSchema = z.object({
+  NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),
+  PORT: z.coerce.number().default(3000),
+  APP_URL: z.string().url().default('http://localhost:3000'),
+  CORS_ORIGINS: z.string().min(1).default('http://localhost:5173'),
+  DB_TYPE: z.enum(['postgres', 'mysql', 'sqlite']).default('postgres'),
+  DATABASE_URL: z.string().url(),
+  // nestforge:feature:auth:token
+  JWT_ACCESS_SECRET: z.string().min(16),
+  JWT_ACCESS_EXPIRES_IN: z.string().default('15m'),
+  JWT_REFRESH_SECRET: z.string().min(16),
+  JWT_REFRESH_EXPIRES_IN: z.string().default('7d'),
+  // nestforge:feature:auth:token:end
+  REDIS_HOST: z.string().default('localhost'),
+  REDIS_PORT: z.coerce.number().default(6379),
+  MAIL_HOST: z.string().default('localhost'),
+  MAIL_PORT: z.coerce.number().default(1025),
+  MAIL_FROM: z.string().default('NestForge <no-reply@nestforge.dev>'),
+  GOOGLE_CLIENT_ID: z.string().optional(),
+  GOOGLE_CLIENT_SECRET: z.string().optional(),
+  GITHUB_CLIENT_ID: z.string().optional(),
+  GITHUB_CLIENT_SECRET: z.string().optional(),
+  THROTTLE_TTL: z.coerce.number().default(60),
+  THROTTLE_LIMIT: z.coerce.number().default(100),
+  // nestforge:feature:auth:session
+  ENABLE_CSRF: z
+    .enum(['true', 'false'])
+    .transform((value) => value === 'true')
+    .default('true'),
+  SESSION_SECRET: z.string().min(32),
+  SESSION_MAX_AGE: z.coerce.number().positive().default(604800000),
+  // nestforge:feature:auth:session:end
+});
+
+export type EnvConfig = z.infer<typeof envSchema>;
+
+export function validateEnv(config: Record<string, unknown>): EnvConfig {
+  const parsed = envSchema.safeParse(config);
+
+  if (!parsed.success) {
+    const issues = parsed.error.issues
+      .map((issue) => `${issue.path.join('.')}: ${issue.message}`)
+      .join('\n');
+    throw new Error(`Variáveis de ambiente inválidas:\n${issues}`);
+  }
+
+  return parsed.data;
+}

package/templates/typeorm/src/database/data-source.ts

@@ -0,0 +1,20 @@
+import 'reflect-metadata';
+import { DataSource } from 'typeorm';
+import {
+    createTypeOrmOptions,
+    DatabaseType,
+} from './typeorm-options';
+
+const databaseType = (
+    process.env.DB_TYPE ?? 'postgres'
+) as DatabaseType;
+
+const databaseUrl = process.env.DATABASE_URL;
+
+if (!databaseUrl) {
+    throw new Error('DATABASE_URL não foi definida');
+}
+
+export default new DataSource(
+    createTypeOrmOptions(databaseType, databaseUrl),
+);

package/templates/typeorm/src/database/database.module.ts

@@ -0,0 +1,39 @@
+import { Global, Module } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import {
+    TypeOrmModule,
+    TypeOrmModuleOptions,
+} from '@nestjs/typeorm';
+import {
+    createTypeOrmOptions,
+    DatabaseType,
+} from './typeorm-options';
+
+@Global()
+@Module({
+    imports: [
+        TypeOrmModule.forRootAsync({
+            inject: [ConfigService],
+            useFactory: (
+                configService: ConfigService,
+            ): TypeOrmModuleOptions => {
+                const databaseType =
+                    configService.getOrThrow<DatabaseType>(
+                        'DB_TYPE',
+                    );
+
+                const databaseUrl =
+                    configService.getOrThrow<string>(
+                        'DATABASE_URL',
+                    );
+
+                return createTypeOrmOptions(
+                    databaseType,
+                    databaseUrl,
+                );
+            },
+        }),
+    ],
+    exports: [TypeOrmModule],
+})
+export class DatabaseModule { }

package/templates/typeorm/src/database/seed.ts

@@ -0,0 +1,81 @@
+// nestforge:feature-file:auth:password
+import * as bcrypt from 'bcryptjs';
+import dataSource from './data-source';
+import { UserEntity } from '../users/entities/user.entity';
+import { Role } from '../common/constants/role.enum';
+
+interface SeedUser {
+    name: string;
+    email: string;
+    password: string;
+    role: Role;
+}
+
+const SEED_USERS: SeedUser[] = [
+    {
+        name: 'Admin',
+        email: 'admin@nestforge.dev',
+        password: 'admin123',
+        role: Role.ADMIN,
+    },
+    {
+        name: 'Manager',
+        email: 'manager@nestforge.dev',
+        password: 'manager123',
+        role: Role.MANAGER,
+    },
+    {
+        name: 'Usuário',
+        email: 'user@nestforge.dev',
+        password: 'user1234',
+        role: Role.USER,
+    },
+];
+
+async function seed() {
+    await dataSource.initialize();
+
+    try {
+        const usersRepository =
+            dataSource.getRepository(UserEntity);
+
+        for (const seedUser of SEED_USERS) {
+            const existingUser =
+                await usersRepository.findOne({
+                    where: {
+                        email: seedUser.email,
+                    },
+                });
+
+            if (!existingUser) {
+                const passwordHash = await bcrypt.hash(
+                    seedUser.password,
+                    10,
+                );
+
+                const user = usersRepository.create({
+                    name: seedUser.name,
+                    email: seedUser.email,
+                    passwordHash,
+                    role: seedUser.role,
+                    emailVerifiedAt: new Date(),
+                });
+
+                await usersRepository.save(user);
+            }
+
+            console.log(
+                `Seed: ${seedUser.email} / ${seedUser.password} (${seedUser.role})`,
+            );
+        }
+    } finally {
+        if (dataSource.isInitialized) {
+            await dataSource.destroy();
+        }
+    }
+}
+
+seed().catch((error: unknown) => {
+    console.error('Erro ao executar o seed:', error);
+    process.exitCode = 1;
+});

package/templates/typeorm/src/database/typeorm-options.ts

@@ -0,0 +1,49 @@
+import { join } from 'node:path';
+import { DataSourceOptions } from 'typeorm';
+
+export type DatabaseType = 'postgres' | 'mysql' | 'sqlite';
+
+export function createTypeOrmOptions(
+    databaseType: DatabaseType,
+    databaseUrl: string,
+): DataSourceOptions {
+    const commonOptions = {
+        entities: [
+            join(__dirname, '..', '**', '*.entity.{ts,js}'),
+        ],
+        migrations: [
+            join(__dirname, 'migrations', '*.{ts,js}'),
+        ],
+        migrationsTableName: 'typeorm_migrations',
+        synchronize: false,
+        logging: process.env.NODE_ENV === 'development',
+    };
+
+    switch (databaseType) {
+        case 'postgres':
+            return {
+                ...commonOptions,
+                type: 'postgres',
+                url: databaseUrl,
+            };
+
+        case 'mysql':
+            return {
+                ...commonOptions,
+                type: 'mysql',
+                url: databaseUrl,
+            };
+
+        case 'sqlite':
+            return {
+                ...commonOptions,
+                type: 'better-sqlite3',
+                database: databaseUrl.replace(/^file:/, ''),
+            };
+
+        default:
+            throw new Error(
+                `Banco "${databaseType}" não suportado pelo template TypeORM`,
+            );
+    }
+}

package/templates/typeorm/src/health/health.controller.ts

@@ -0,0 +1,49 @@
+import { Controller, Get } from '@nestjs/common';
+import {
+    DiskHealthIndicator,
+    HealthCheck,
+    HealthCheckService,
+    MemoryHealthIndicator,
+} from '@nestjs/terminus';
+// nestforge:feature:swagger
+import { ApiOperation, ApiTags } from '@nestjs/swagger';
+// nestforge:feature:swagger:end
+import { Public } from '../common/decorators/public.decorator';
+import { TypeOrmHealthIndicator } from './indicators/typeorm-health.indicator';
+// nestforge:feature:redis
+import { RedisHealthIndicator } from './indicators/redis-health.indicator';
+// nestforge:feature:redis:end
+
+// nestforge:feature:swagger
+@ApiTags('health')
+// nestforge:feature:swagger:end
+@Controller('health')
+export class HealthController {
+    constructor(
+        private readonly health: HealthCheckService,
+        private readonly databaseIndicator: TypeOrmHealthIndicator,
+        // nestforge:feature:redis
+        private readonly redisIndicator: RedisHealthIndicator,
+        // nestforge:feature:redis:end
+        private readonly memory: MemoryHealthIndicator,
+        private readonly disk: DiskHealthIndicator,
+    ) { }
+
+    @Public()
+    @Get()
+    @HealthCheck()
+    // nestforge:feature:swagger
+    @ApiOperation({ summary: 'Verifica a saúde da API (banco, memória, disco e demais dependências configuradas)' })
+    // nestforge:feature:swagger:end
+    check() {
+        return this.health.check([
+            () => this.databaseIndicator.isHealthy('database'),
+            // nestforge:feature:redis
+            () => this.redisIndicator.isHealthy('redis'),
+            // nestforge:feature:redis:end
+            () => this.memory.checkHeap('memory_heap', 300 * 1024 * 1024),
+            () => this.memory.checkRSS('memory_rss', 300 * 1024 * 1024),
+            () => this.disk.checkStorage('disk', { path: '/', thresholdPercent: 0.9 }),
+        ]);
+    }
+}

package/templates/typeorm/src/health/health.module.ts

@@ -0,0 +1,19 @@
+import { Module } from '@nestjs/common';
+import { TerminusModule } from '@nestjs/terminus';
+import { HealthController } from './health.controller';
+import { TypeOrmHealthIndicator } from './indicators/typeorm-health.indicator';
+// nestforge:feature:redis
+import { RedisHealthIndicator } from './indicators/redis-health.indicator';
+// nestforge:feature:redis:end
+
+@Module({
+    imports: [TerminusModule],
+    controllers: [HealthController],
+    providers: [
+        TypeOrmHealthIndicator,
+        // nestforge:feature:redis
+        RedisHealthIndicator,
+        // nestforge:feature:redis:end
+    ],
+})
+export class HealthModule { }