@stefaninigo/security-client

Cliente SDK de Security para StefaniniGo. Proporciona guards, decorators y servicios para autenticación y autorización en servicios NestJS.

Instalación

npm install @stefaninigo/security-client

Configuración

1. Configurar npm registry

Crear .npmrc en la raíz del proyecto:

@stefaninigo:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

2. Importar módulo

import { SecurityClientModule } from '@stefaninigo/security-client';

@Module({
  imports: [
    SecurityClientModule.forRoot({
      securityServiceUrl: process.env.SECURITY_SERVICE_URL || 'http://localhost:3000',
      timeout: 5000, // opcional
    }),
  ],
})
export class AppModule {}

3. Usar en controllers

import { Controller, Get, UseGuards } from '@nestjs/common';
import { Roles, SecurityAuthGuard, RoleGuard, UserRole } from '@stefaninigo/security-client';

@Controller('clients')
@UseGuards(SecurityAuthGuard, RoleGuard)
export class ClientsController {
  @Get()
  @Roles(UserRole.ROOT, UserRole.ADMIN)
  async listClients() {
    // El usuario autenticado está disponible en request.user
  }
}

API

Guards

• SecurityAuthGuard: Valida tokens delegando al servicio Security centralizado y obtiene información del usuario
• RoleGuard: Valida que el usuario tenga uno de los roles requeridos

Nota: CognitoAuthGuard está deprecated, usa SecurityAuthGuard en su lugar.

Decorators

• @Roles(...roles): Especifica los roles requeridos para acceder a un endpoint

Types

• UserRole: Enum con los roles disponibles (ROOT, ADMIN, DISPATCHER, TECHNICIAN)
• UserStatus: Enum con los estados de usuario (ACTIVE, PENDING, BLOCKED)
• AuthUser: Interface con la información del usuario autenticado

Variables de entorno requeridas

• SECURITY_SERVICE_URL: URL del servicio Security (requerido en forRoot o como env var)

Arquitectura

┌─────────────────┐     Token     ┌─────────────────────┐
│   Tu Servicio   │ ────────────► │  Security Service   │
│  (tickets, etc) │               │  (valida Cognito)   │
└─────────────────┘               └─────────────────────┘
        │                                   │
        │ SecurityAuthGuard                 │ CognitoAuthGuard
        │ delega validación                 │ valida JWT
        ▼                                   ▼
    request.user                      request.user

El guard NO valida tokens JWT directamente. Delega al servicio Security centralizado:

1. Recibe token Bearer del request
2. Llama al endpoint /api/v1/security/users/me del servicio Security
3. El servicio Security valida el token con Cognito
4. Retorna datos del usuario al guard
5. Guard adjunta usuario al request