@quadcore-lib/auth-server

Módulo NestJS que resuelve autenticación via Auth0 JWT y autorización por roles almacenados en DB propia.

Instalación

npm install @quadcore-lib/auth-server

Requisitos

Peer dependencies que la app consumidora debe tener instaladas:

npm install @nestjs/common @nestjs/core @nestjs/typeorm typeorm reflect-metadata

Tu app también necesita TypeOrmModule.forRoot() configurado con una DB que incluya la tabla users.

Uso

1. Registrar el módulo

// app.module.ts
import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { QuadcoreAuthModule } from '@quadcore-lib/auth-server';

@Module({
  imports: [
    TypeOrmModule.forRoot({
      type: 'postgres',
      url: process.env.DATABASE_URL,
      autoLoadEntities: true,
    }),
    QuadcoreAuthModule.forRoot({
      domain: 'mi-tenant.auth0.com',
      audience: 'https://api.miapp.com',
    }),
  ],
})
export class AppModule {}

2. Proteger rutas con JWT

import { Controller, Get, UseGuards } from '@nestjs/common';
import { JwtAuthGuard, CurrentUser } from '@quadcore-lib/auth-server';

@Controller('perfil')
export class PerfilController {
  @UseGuards(JwtAuthGuard)
  @Get()
  getPerfil(@CurrentUser() user: Record<string, unknown>) {
    return user; // payload del JWT de Auth0
  }
}

3. Restringir por rol

import { Controller, Delete, Param, UseGuards } from '@nestjs/common';
import { JwtAuthGuard, RolesGuard, Roles } from '@quadcore-lib/auth-server';

@Controller('usuarios')
export class UsuariosController {
  @UseGuards(JwtAuthGuard, RolesGuard)
  @Roles('admin')
  @Delete(':id')
  eliminar(@Param('id') id: string) {
    return { eliminado: id };
  }
}

RolesGuard lee el rol desde la tabla users en tu DB, no desde el token.

4. Crear o sincronizar usuarios desde Auth0

import { Injectable } from '@nestjs/common';
import { AuthService } from '@quadcore-lib/auth-server';

@Injectable()
export class OnboardingService {
  constructor(private readonly authService: AuthService) {}

  async sincronizar(auth0Id: string, email: string) {
    return this.authService.findOrCreate(auth0Id, email);
  }
}

API

QuadcoreAuthModule

| Método | Descripción | |---|---| | forRoot(options) | Registra el módulo globalmente con la configuración de Auth0 |

AuthModuleOptions

| Campo | Tipo | Requerido | Descripción | |---|---|---|---| | domain | string | sí | Dominio Auth0, ej: mi-tenant.auth0.com | | audience | string | sí | Audience del API en Auth0 | | roleField | string | no | Reservado para uso futuro |

Guards

| Export | Tipo | Descripción | |---|---|---| | JwtAuthGuard | Guard | Valida el JWT de Auth0 via JWKS. Rechaza con 401 si el token es inválido o expiró | | RolesGuard | Guard | Verifica el rol del usuario contra la DB. Usar siempre junto a JwtAuthGuard |

Decoradores

| Export | Uso | Descripción | |---|---|---| | @CurrentUser() | Param decorator | Inyecta el payload del JWT en el parámetro del handler | | @Roles(...roles) | Method/Class decorator | Define los roles requeridos para acceder al endpoint |

Servicios

| Export | Método | Descripción | |---|---|---| | AuthService | findOrCreate(auth0Id, email) | Busca o crea el usuario en DB | | AuthService | findByAuth0Id(auth0Id) | Devuelve el usuario por su ID de Auth0 o null |

Entidades

| Export | Tabla | Columnas | |---|---|---| | UserEntity | users | id (uuid), email, role (default: "user"), auth0Id, createdAt, updatedAt |

Flujo de autenticación

Request → JwtAuthGuard
            ↓ GET https://{domain}/.well-known/jwks.json
            ↓ valida firma RS256 + audience + issuer
            ↓ setea request.user = payload del JWT
         RolesGuard (si se usa)
            ↓ lee user.sub del payload
            ↓ consulta SELECT * FROM users WHERE auth0Id = sub
            ↓ compara user.role con @Roles(...)
         Handler