npm package: @jamx-framework/auth
Description: JAMX Framework â€” Authentication
Author: Stiven-21
Latest version: 1.0.0

# @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
```typescript
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
```typescript
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
```typescript
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: 'usuario@example.com',
  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
```typescript
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)
```typescript
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: 'user@example.com' });

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.