workspace-v1/shared/knowledge-base/modules/authentication/jwt-nestjs/USAGE.md

Guia de Uso: JWT Authentication (NestJS)

Modulo: auth-jwt-nestjs Version: 2.1.0

---

Prerequisitos

• NestJS 9+ configurado
• PostgreSQL con tabla users
• Redis (opcional, para blacklist de tokens)
• Variables de entorno configuradas

Paso 1: Instalar Dependencias

npm install @nestjs/jwt @nestjs/passport passport passport-jwt bcrypt class-validator class-transformer
npm install -D @types/passport-jwt @types/bcrypt

Paso 2: Variables de Entorno

# JWT
JWT_SECRET=your-super-secret-key-min-32-chars
JWT_EXPIRES_IN=15m
JWT_REFRESH_SECRET=your-refresh-secret-key-min-32-chars
JWT_REFRESH_EXPIRES_IN=7d

# Opcional: Multi-tenant
MULTI_TENANT_ENABLED=false

# Opcional: Redis para blacklist
REDIS_HOST=localhost
REDIS_PORT=6379

Paso 3: Copiar Modulo

# Desde gamilit (recomendado)
cp -r projects/gamilit/apps/backend/src/modules/auth \
      your-project/src/modules/

# O desde erp-core
cp -r projects/erp-core/backend/src/modules/auth \
      your-project/src/modules/

Paso 4: Integrar en AppModule

// app.module.ts
import { AuthModule } from './modules/auth/auth.module';
import { UsersModule } from './modules/users/users.module';

@Module({
  imports: [
    ConfigModule.forRoot({ isGlobal: true }),
    AuthModule,
    UsersModule,
    // ... otros modulos
  ],
})
export class AppModule {}

Paso 5: Configurar JWT Strategy

// auth/strategies/jwt.strategy.ts
import { Injectable } from '@nestjs/common';
import { PassportStrategy } from '@nestjs/passport';
import { ExtractJwt, Strategy } from 'passport-jwt';
import { ConfigService } from '@nestjs/config';

@Injectable()
export class JwtStrategy extends PassportStrategy(Strategy) {
  constructor(private configService: ConfigService) {
    super({
      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
      ignoreExpiration: false,
      secretOrKey: configService.get<string>('JWT_SECRET'),
    });
  }

  async validate(payload: any) {
    return {
      id: payload.sub,
      email: payload.email,
      roles: payload.roles,
      tenantId: payload.tenantId, // Si multi-tenant
    };
  }
}

Paso 6: Proteger Endpoints

// cualquier.controller.ts
import { Controller, Get, UseGuards } from '@nestjs/common';
import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
import { CurrentUser } from '../auth/decorators/current-user.decorator';

@Controller('protected')
@UseGuards(JwtAuthGuard)
export class ProtectedController {
  @Get()
  getProtectedData(@CurrentUser() user: any) {
    return { message: 'Protected data', userId: user.id };
  }
}

Paso 7: Endpoints Publicos

// auth.controller.ts
import { Public } from './decorators/public.decorator';

@Controller('auth')
export class AuthController {
  @Public() // Excluye de JwtAuthGuard
  @Post('login')
  async login(@Body() loginDto: LoginDto) {
    return this.authService.login(loginDto);
  }

  @Public()
  @Post('register')
  async register(@Body() registerDto: RegisterDto) {
    return this.authService.register(registerDto);
  }
}

Verificacion

Tests

# Login
curl -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"password123"}'

# Acceso protegido
curl http://localhost:3000/protected \
  -H "Authorization: Bearer YOUR_TOKEN"

Checklist

• Dependencias instaladas
• Variables de entorno configuradas
• AuthModule importado en AppModule
• JwtStrategy configurado
• Endpoints de login/register funcionan
• Endpoints protegidos requieren token

---

Personalizacion

Agregar Roles

// guards/roles.guard.ts
@Injectable()
export class RolesGuard implements CanActivate {
  constructor(private reflector: Reflector) {}

  canActivate(context: ExecutionContext): boolean {
    const requiredRoles = this.reflector.getAllAndOverride<string[]>('roles', [
      context.getHandler(),
      context.getClass(),
    ]);
    if (!requiredRoles) return true;
    const { user } = context.switchToHttp().getRequest();
    return requiredRoles.some((role) => user.roles?.includes(role));
  }
}

Multi-tenant

// jwt.strategy.ts - incluir tenantId en payload
async validate(payload: any) {
  return {
    id: payload.sub,
    email: payload.email,
    tenantId: payload.tenantId,
  };
}

// auth.service.ts - incluir en token
const payload = {
  sub: user.id,
  email: user.email,
  tenantId: user.tenantId,
};

---

Siguiente: Ver API.md para referencia completa