Authenticate Module

Módulo interno de autenticación para microservicios Nuxt de la empresa. Proporciona una solución unificada para el manejo de autenticación de usuarios, sesiones y tokens a través de múltiples microservicios.

[![npm version][npm-version-src]][npm-version-href] [![npm downloads][npm-downloads-src]][npm-downloads-href] [![License][license-src]][license-href] [![Nuxt][nuxt-src]][nuxt-href]

Objetivo

Un módulo para Nuxt que facilita la autenticación de usuarios en tus aplicaciones, con un enfoque de inversión de dependencias: el módulo no obliga a una conexión directa a una base de datos. En lugar de ello, expone contratos (repositorios y proveedores) que la aplicación anfitriona puede inyectar (por ejemplo: getUserRepository, getSessionRepository). Esto permite reemplazar la implementación de almacenamiento (Prisma, MSSQL, in-memory, etc.) sin modificar el módulo.

El diseño busca estandarizar la autenticación entre microservicios manteniendo independencia de la infraestructura de datos, facilitando pruebas y despliegues.

• ✨  Notas de Lanzamiento

Características

• 🔐 Autenticación unificada: Sistema de registro e inicio de sesión consistente entre microservicios.
• 🛡️ Protección de rutas: Middleware para asegurar endpoints y rutas protegidas.
• 🔑 Gestión de tokens JWT: Generación, validación y manejo centralizado de tokens.
• 👤 Manejo de sesiones: Control de sesiones activas y cierre seguro de sesión.
• 🏗️ Arquitectura modular: Diseñado para ser reutilizado en múltiples microservicios.
• 📊 Historial de usuarios: Seguimiento de cambios y auditoría de usuarios.

Instalación

Instala el módulo en tu aplicación Nuxt con el siguiente comando:

npm install nuxt-authenticate-module

Configuración

1. Configuración de Nuxt

Agrega el módulo a tu configuración de Nuxt en nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['./modules/authenticate-module/src/module'],
  authenticateModule: {
    enabled: true, // Habilita o deshabilita el módulo
  },
})

2. Variables de Entorno

Configura las siguientes variables en tu archivo .env. Nota: DATABASE_URL es opcional si proporcionas repositorios personalizados; el módulo no requiere una conexión a la base de datos por defecto.

# Base de datos (SQL Server) — Opcional si provees repositorios
DATABASE_URL="sqlserver://servidor:puerto;database=nombre_db;user=usuario;password=contraseña;encrypt=true"

Inversión de Dependencias

El módulo está diseñado para recibir implementaciones de repositorios y proveedores desde la aplicación que lo usa. Proporciona utilidades en runtime/utility (getUserRepository, getSessionRepository) como contratos por defecto. Puedes inyectar tus implementaciones en la configuración del módulo o a través de composables/servicios en runtime.

Inyección vía Middleware

La inyección de dependencias en este módulo se realiza típicamente desde un middleware que adjunta las implementaciones de repositorios al contexto de los eventos. En el playground existe un ejemplo en playground/server/middleware/auth/inject-repository.ts que muestra cómo resolver proveedores y exponerlos en event.context.

Ejemplo de middleware (simplificado):

export default defineEventHandler(async (event) => {
  const cfg = useRuntimeConfig().authenticateModule || {}
  const providers = cfg.providers || {}

  const userRepository = typeof providers.userRepository === 'function'
    ? providers.userRepository()
    : providers.userRepository

  const sessionRepository = typeof providers.sessionRepository === 'function'
    ? providers.sessionRepository()
    : providers.sessionRepository

  event.context.userRepository = userRepository
  event.context.sessionRepository = sessionRepository
})

Los controladores y servicios del módulo pueden entonces obtener los repositorios desde event.context o usando los helpers del runtime (getUserRepository, getSessionRepository) que consultan ese contexto.

Uso

Rutas de Autenticación

El módulo registra automáticamente las siguientes rutas en tu servidor:

• POST /api/auth/register: Registro de nuevos usuarios.
• POST /api/auth/login: Inicio de sesión y generación de tokens.
• POST /api/auth/session: Validación de sesiones activas.
• POST /api/auth/closeSession: Cierre de sesión.

Ejemplo de Uso en Microservicio

// Ejemplo de registro de usuario desde el frontend
const registrarUsuario = async () => {
  const userData = {
    userName: 'empleado123',
    password: 'contraseñaSegura123',
  }

  try {
    const response = await $fetch('/api/auth/register', {
      method: 'POST',
      body: userData,
    })
    console.log('Usuario registrado:', response)
  } catch (error) {
    console.error('Error en registro:', error)
  }
}

// Ejemplo de inicio de sesión
const iniciarSesion = async () => {
  const loginData = {
    userName: 'empleado123',
    password: 'contraseñaSegura123',
  }

  try {
    const response = await $fetch('/api/auth/login', {
      method: 'POST',
      body: loginData,
    })
    const token = response.token
    console.log('Token recibido:', token)
  } catch (error) {
    console.error('Error en login:', error)
  }
}

Integración entre Microservicios

Validación de Tokens entre Servicios

// Middleware para validar tokens en rutas protegidas
export default defineEventHandler(async (event) => {
  const token = getCookie(event, 'auth-token') || getHeader(event, 'authorization')

  try {
    // `authToken` puede ser la implementación incluida o una función que use
    // `event.context.sessionRepository`/`userRepository` inyectados por middleware.
    const isValid = await authToken(token)
    if (!isValid) {
      throw createError({
        statusCode: 401,
        statusMessage: 'Token inválido'
      })
    }
  } catch (error) {
    throw createError({
      statusCode: 401,
      statusMessage: 'No autorizado'
    })
  }
})

Desarrollo y Pruebas

El módulo incluye un conjunto completo de pruebas unitarias utilizando Vitest:

# Ejecutar todas las pruebas
npm run test

# Ejecutar pruebas en modo watch
npm run test:watch

# Ejecutar pruebas con coverage
npm run test:coverage

Estructura del Proyecto

authenticate-module/
├── src/
│   ├── module.ts                    # Configuración principal del módulo
│   └── runtime/
│       └── server/
│           ├── api/auth/            # Endpoints de autenticación
│           ├── middleware/          # Middleware de validación
│           └── modules/             # Lógica de negocio modular
├── test/                            # Pruebas unitarias completas
├── prisma/                          # Esquemas y migraciones de BD
├── playground/                      # Ejemplo de implementación
└── README.md                        # Esta documentación

Esquema de Base de Datos

El módulo incluye un esquema de ejemplo para Prisma (SQL Server). Estos modelos son parte de la implementación opcional con Prisma; si inyectas tus propios repositorios, puedes adaptar el esquema a tu almacenamiento. Los modelos principales incluyen:

Modelo User

model User {
  id          Int           @id @default(autoincrement())
  userName    String        @unique @db.VarChar(50)
  password    String        // Encriptada con bcrypt
  createdAt   DateTime      @default(now())
  updatedAt   DateTime      @updatedAt
  enable      Boolean       @default(true)

  sessions    Session[]     // Sesiones activas
  userHistory UserHistory[] // Historial de cambios
}

Modelo Session

model Session {
  id        Int       @id @default(autoincrement())
  userId    Int
  token     String    @unique @db.VarChar(255)
  ipAddress String?   // IP de origen
  userAgent String?   // Navegador/dispositivo
  createdAt DateTime  @default(now())
  expiresAt DateTime? // Expiración del token

  user      User      @relation(fields: [userId], references: [id], onDelete: Cascade)
}

Seguridad

• Encriptación de contraseñas: Uso de bcrypt con salt rounds configurables
• Validación de entrada: Sanitización de datos de usuario
• Auditoría: Registro de cambios en UserHistory
• Expiración de sesiones: Control de tiempo de vida de tokens

Mantenimiento

Actualizaciones del Módulo

Para actualizar el módulo en tus microservicios:

1. Hacer pull de los cambios más recientes
2. Ejecutar migraciones si hay cambios en la BD:

   npx prisma migrate deploy

3. Regenerar el cliente Prisma:

   npx prisma generate

4. Ejecutar pruebas para validar la integración:

   npm run test

Soporte y Documentación

Para dudas sobre la implementación o problemas con el módulo:

• Revisar los tests para ejemplos de uso
• Consultar la documentación del código
• Contactar al equipo de desarrollo interno

Desarrollado para uso interno empresarial - Este módulo está diseñado específicamente para la arquitectura de microservicios de la empresa y no está destinado para distribución pública.