Regcheq Auth Library

Libreria interna para estandarizar autenticacion y autorizacion en servicios NestJS. Provee middleware para validar JWT, carga de permisos via Redis y decoradores para acceder al contexto de usuario.

Que resuelve

• Verificacion de JWT con public key (local o desde servicio de auth).
• Contexto unificado en req.context y req.user.
• Guard de permisos con decorador simple.
• Cache local + Redis para permisos por rol, con invalidacion por canal.

Instalacion

npm i @regcheq/auth-library

Uso rapido en NestJS

1. Registrar el modulo global

import { Module } from '@nestjs/common';
import { AuthModule } from '@regcheq/auth-library';

@Module({
  imports: [
    AuthModule.register({
      authServiceUrl: 'https://auth.mi-dominio.com',
      // o publicKey: '-----BEGIN PUBLIC KEY-----...'
      redisOptions: { host: '127.0.0.1', port: 6379 },
      rolesUpdateChannel: 'events:roles:updated'
    }),
  ],
})
export class AppModule {}

2. Proteger rutas con permisos

import { Controller, Get, UseGuards } from '@nestjs/common';
import { PermissionsGuard, RequirePermissions } from '@regcheq/auth-library';

@Controller('reportes')
@UseGuards(PermissionsGuard)
export class ReportesController {
  @Get()
  @RequirePermissions('reports.read')
  findAll() {
    return [];
  }
}

3. Acceder al usuario actual

import { Controller, Get } from '@nestjs/common';
import { CurrentUser, Company } from '@regcheq/auth-library';

@Controller('me')
export class MeController {
  @Get()
  getMe(@CurrentUser() user, @Company() companyId: string) {
    return { user, companyId };
  }
}

Como funciona

• El middleware toma el token Authorization: Bearer <token>.
• Verifica el JWT con la public key.
• Enriquece el request con context y user.
• El guard revisa permisos declarados con @RequirePermissions.
• Si source en el token es internal, el guard permite acceso sin validar permisos.

AuthModuleOptions

Opciones disponibles al registrar el modulo:

• authServiceUrl: URL del servicio de auth para obtener la public key (GET /public-key).
• publicKey: PEM directo para verificar JWT (si existe, ignora authServiceUrl).
• redisOptions: opciones de conexion para ioredis.
• rolesUpdateChannel: canal para invalidar cache local (default events:roles:updated).
• onUnauthorized: callback para lanzar una excepcion 401 desde tu app.
• onForbidden: callback para lanzar una excepcion 403 desde tu app.

Ejemplo de callbacks:

import { UnauthorizedException, ForbiddenException } from '@nestjs/common';

AuthModule.register({
  authServiceUrl: 'https://auth.mi-dominio.com',
  redisOptions: { host: '127.0.0.1', port: 6379 },
  onUnauthorized: (message) => { throw new UnauthorizedException(message); },
  onForbidden: (message) => { throw new ForbiddenException(message); },
});

Contexto agregado al request

La libreria agrega informacion en el request para que puedas usarla en controladores y servicios:

interface AuthContext {
  companyId: string;
  user: { id: string; name: string; email: string };
  roles: string[];
  permissions: string[];
  source: 'internal' | 'external';
}

Disponibles en req.context y req.user (con permissions).

Permisos y cache

• Los permisos por rol se leen desde Redis con la llave auth:role:<role>:permissions.
• La libreria mantiene un cache local por rol y lo invalida con Pub/Sub.
• El canal de invalidacion se configura con rolesUpdateChannel.

Versionado (SemVer)

Este paquete sigue SemVer:

• PATCH: fixes internos sin cambios de API.
• MINOR: nuevas funcionalidades compatibles.
• MAJOR: cambios que rompen compatibilidad.

Commits (Conventional Commits)

El release automatico usa Conventional Commits. Ejemplos:

• feat: agrega nuevo decorador -> MINOR
• fix: corrige validacion de token -> PATCH
• feat!: cambia estructura de contexto -> MAJOR

O con breaking change explicito:

feat: agrega autenticacion

BREAKING CHANGE: cambia nombre de export en index

Tipos comunes: feat, fix, chore, docs, refactor, test.

Requisitos de desarrollo

El repo usa Node 22 (ver .nvmrc).

nvm use
npm ci

Exportaciones

export * from './auth.module';
export * from './guards/permissions.guard';
export * from './decorators/auth.decorators';
export * from './interfaces/auth-context.interface';
export * from './interfaces/auth-options.interface';