@jamx-framework/auth

Descripción

Módulo de autenticación y autorización para JAMX Framework. Proporciona un sistema completo de gestión de usuarios, autenticación basada en JWT, verificación de contraseñas, control de acceso mediante RBAC (Role-Based Access Control) y middlewares para proteger rutas en aplicaciones server y API.

Cómo funciona

El módulo implementa un flujo completo de autenticación que incluye:

1. Gestión de contraseñas: Hashing seguro con PBKDF2 y comparación en tiempo constante
2. Autenticación basada en estrategias:
   • JwtStrategy: Autenticación mediante tokens JWT
   • CredentialsStrategy: Autenticación con credenciales (email/contraseña)
3. Gestión de sesiones: Tokens JWT con expiración y datos de usuario
4. RBAC: Sistema de roles y permisos con middleware de autorización
5. Middlewares de protección:
   • authGuard: Protege rutas con autenticación JWT
   • requireSession: Obtiene la sesión autenticada de forma segura
   • createGuard: Verifica roles y permisos específicos

Componentes principales

• src/password/hasher.ts: Servicio de hashing de contraseñas con PBKDF2
• src/session/jwt-session.ts: Gestión de sesiones basada en JWT
• src/strategies/jwt.ts: Estrategia de autenticación JWT
• src/strategies/credentials.ts: Estrategia de autenticación con credenciales
• src/middleware/auth-guard.ts: Middleware que protege rutas con JWT
• src/rbac/auth-rbac.ts: Integración entre JWT y RBAC
• src/rbac/guard.ts: Middleware de autorización por roles/permisos
• src/index.ts: Punto de exportación que reúne todos los componentes

Uso básico

import { 
  passwordHasher, 
  JwtSessionManager, 
  JwtStrategy, 
  CredentialsStrategy,
  authGuard,
  requireSession
} from '@jamx-framework/auth';

// Configurar gestores
const jwtManager = new JwtSessionManager({ secret: 'mi-secreto', expiresIn: 3600 });
const hasher = new PasswordHasher();

// Registrar estrategias (ejemplo con Express)
const jwtStrategy = new JwtStrategy({ secret: 'mi-secreto' });
const credentialsStrategy = new CredentialsStrategy({
  validate: async (email, password) => {
    const storedHash = await hasher.verify(password, user.passwordHash);
    return storedHash ? { email } : null;
  }
});

// Uso de middleware de protección
server.use(authGuard({ sessionManager: jwtManager }));

// Obtener sesión de forma segura
const session = requireSession(req);
console.log('Usuario autenticado:', session.user.email);

Ejemplos

Registro de usuario con hash de contraseña

import { passwordHasher } from '@jamx-framework/auth';

const hash = await passwordHasher.hash('mi-contraseña-secreta');
console.log('Hash generado:', hash);

// Verificar contraseña
const isValid = await passwordHasher.verify('mi-contraseña-secreta', hash);
console.log('¿Contraseña válida?', isValid);

Autenticación con JWT

import { JwtSessionManager, JwtStrategy } from '@jamx-framework/auth';

const sessionManager = new JwtSessionManager({ secret: 'mi-secreto' });
const jwtStrategy = new JwtStrategy({ secret: 'mi-secreto' });

// Crear sesión para un usuario
const session = sessionManager.createSession({
  id: '123',
  email: '[email protected]',
  roles: ['user', 'admin']
});

console.log('Token JWT:', session.token);
console.log('Expira en:', session.expiresAt);

// Verificar token en una request
const token = req.header('Authorization')?.replace('Bearer ', '');
const verified = sessionManager.verifyToken(token);
if (verified) {
  console.log('Usuario verificado:', verified.user.email);
}

Protección de rutas con RBAC

import { createGuard } from '@jamx-framework/auth';
import { RBAC } from '@jamx-framework/auth';

// Configurar RBAC
const rbac = new RBAC();
await rbac.addRole('admin', ['read:posts', 'write:posts']);
await rbac.addRole('editor', ['read:posts', 'write:posts', 'delete:posts']);

// Middleware que requiere rol 'admin'
const adminGuard = createGuard(rbac, {
  roles: ['admin'],
  permissions: [],
  match: 'any'
});

server.get('/admin', adminGuard, (req, res) => {
  res.json({ message: 'Acceso permitido para administradores' });
});

// Middleware que requiere permiso específico
const writeGuard = createGuard(rbac, {
  roles: [],
  permissions: ['write:posts'],
  match: 'any'
});

server.post('/posts', writeGuard, (req, res) => {
  res.json({ message: 'Publicación creada' });
});

Uso con inyección de dependencias (Core)

import { Container } from '@jamx-framework/core';
import { JwtSessionManager } from '@jamx-framework/auth';

// Registrar servicios en el contenedor
Container.registerSingleton('sessionManager', () => 
  new JwtSessionManager({ secret: 'mi-secreto' })
);

// Resolver e usar en controladores
const sessionManager = Container.resolve('sessionManager');
const session = sessionManager.createSession({ id: '1', email: '[email protected]' });

console.log('Sesión creada:', session.token);

Flujo interno

1. Registro de usuarios: Las contraseñas se almacenan como hashes seguros usando PBKDF2
2. Autenticación:
   • JwtStrategy valida tokens JWT en cada request
   • CredentialsStrategy verifica email y contraseña contra el hash almacenado
3. Gestión de sesiones: JwtSessionManager crea tokens JWT con payload que incluye información del usuario y expiración
4. Middleware de protección: authGuard verifica la presencia y validez del token JWT antes de permitir el acceso a rutas protegidas
5. RBAC:
   • Los roles y permisos se asignan a usuarios durante el registro o desde el payload JWT
   • createGuard verifica que el usuario autenticado tenga los roles/permisos requeridos
6. Acceso a sesión: requireSession permite obtener la sesión autenticada de forma tipada y segura de la request

Este módulo proporciona una base sólida para implementar autenticación y autorización en aplicaciones JAMX, con soporte para múltiples estrategias de autenticación, gestión de sesiones segura y control de acceso basado en roles/permisos.