📦 @lextomato/nest-users

📄 Documentation in English

✨ @lextomato/nest-users es una solución integral y lista para usar que simplifica la implementación de autenticación, gestión de usuarios, control de roles y permisos en tus proyectos NestJS. Con este paquete, podrás manejar de forma segura y eficiente todo el ciclo de autenticación (incluyendo login, logout, cambio de contraseña, y recuperación de contraseñas olvidadas), mientras que también te permite gestionar usuarios, roles, y permisos a través de un completo sistema de CRUD.

✨ Además, proporciona un robusto sistema de Control de Acceso que garantiza que cada endpoint de tu aplicación solo sea accesible por usuarios con los permisos adecuados, basados en los roles asignados. Perfecto para aplicaciones que requieren un control de acceso detallado y una administración centralizada de usuarios.

📚 Tabla de Contenidos

• Características
• Requisitos
• Instalación
• Configuración
  • Variables de Entorno
  • Integracion de Swagger
  • Configuración de Plantillas Personalizadas para el MailModule
• Uso Básico
• API
• Especificaciones
• Otras Características
• Ejemplos
  • Integracion completa
  • Protegiendo rutas con roles de un controller en general
  • Protegiendo una ruta en especifico con roles
• Contribuciones
• Licencia
• Donaciones
• Recursos Adicionales

🚀 Características

• 🔒 Autenticación Completa: Implementación de autenticación basada en JWT, incluyendo login, logout, validación de sesión, cambio y recuperación de contraseñas.
• 🧒🏻​ Gestión de Usuarios: CRUD completo para usuarios con integración de roles.
• ⚡️ Sistema de Roles y Permisos: Control de acceso basado en roles y permisos con un guardia de roles integrado.
• 📧​ Sistema de Correo: Envío de correos electrónicos para activación de cuentas y recuperación de contraseñas, con configuración dinámica de plantillas y transporte.
• 🪜​ Modularidad y Escalabilidad: Módulos independientes y bien integrados que facilitan la escalabilidad y el mantenimiento del código.
• 🛠️ Fácil Configuración y Extensión: Configuración sencilla y diseño extensible para adaptarse a diferentes necesidades de proyectos.

🧩 Requisitos

Antes de utilizar @lextomato/nest-users, asegúrate de tener instaladas las siguientes dependencias básicas en tu proyecto:

📦 Dependencias Básicas

1. NestJS - El framework principal:

   npm install @nestjs/cli @nestjs/core @nestjs/common @nestjs/config

2. TypeORM - ORM (Object-Relational Mapping) para interactuar con bases de datos:

   npm install typeorm @nestjs/typeorm

3. Swagger (Opcional) - Para la generación de documentación de API automática:

   npm install @nestjs/swagger swagger-ui-express

💡 Requisitos adicionales

• Node.js: Es necesario tener instalado Node.js (versión 20 o superior).
• Nest CLI: Aunque no es obligatorio, te recomendamos utilizar el CLI de NestJS para facilitar la gestión de tu proyecto.

  npm install -g @nestjs/cli

🗄️ Base de Datos

Este paquete está diseñado para trabajar principalmente con PostgreSQL. Asegúrate de tener un servidor PostgreSQL corriendo y configurado.

Para configurar correctamente la base de datos requerida por @lextomato/nest-users, sigue las instrucciones detalladas en el siguiente enlace:

➡️ Guía de Configuración de la Base de Datos

🛠️ Instalación

Puedes instalar el paquete usando npm o yarn:

npm install @lextomato/nest-users

O usando yarn:

yarn add @lextomato/nest-users

⚙️ Configuración

🔘 📄 Variables de Entorno

El paquete se configura a través de variables de entorno según el archivo .env en la raiz, el cual debe tener las siguientes variables de entorno:

⚠️ IMPORTANTE: este paquete fue diseñado para una base de datos basada en Postgres SQL. Se detalla la estructura de la misma para la correcta integracion con el paquete en este enlace ➡️Guía de Configuración de la Base de Datos.

| Variable | Descripción | Ejemplo | | ----------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------- | | JWT_SECRET | 🔑 Clave secreta para firmar los tokens JWT. | session-Trrs79 | | DB_HOST | 🗄️ Dirección del host de la base de datos. | localhost | | DB_PORT | 🛠️ Puerto de conexión a la base de datos. | 5432 | | DB_USER | 👤 Nombre de usuario para acceder a la base de datos. | db_user | | DB_PASS | 🔐 Contraseña del usuario de la base de datos. | db_password | | DB_NAME | 📂 Nombre de la base de datos. | db_name | | EMAIL_HOST | 📧 Servidor SMTP utilizado para el envío de correos. | smtp.gmail.com | | EMAIL_PORT | 🔌 Puerto de conexión para el servidor SMTP. | 465 | | EMAIL_USER | 👤 Dirección de correo electrónico utilizada para enviar correos. | [email protected] | | EMAIL_PASS | 🔐 Contraseña del correo electrónico utilizado. | email_password | | EMAIL_SECURE | ✅ Indicador de si se debe usar una conexión segura (SSL/TLS). | true (Obligatorio en true) | | EMAIL_FROM | ✉️ Dirección de correo "De" que aparecerá en los correos enviados. | "Your App" <[email protected]> | | APP_DOMAIN | 🌐 Dominio de la aplicación, utilizado para generar enlaces en los correos. | http://localhost:9000 o https://frontend-domain.com | | ENDPOINT_FROM_RECOVERY_PASS | 🔄 Ruta del frontend para el formulario de recuperación de contraseñas. | /#/reset-password |

🔘 📋 Integración de Swagger

Tags por Defecto

El paquete @lextomato/nest-users incluye una serie de tags predefinidos en Swagger que permiten organizar y visualizar de manera clara todas las funcionalidades del servicio, tales como autenticación, gestión de usuarios, roles y permisos. Esto facilita la navegación y el acceso a cada endpoint documentado.

Nota: Estos tags estarán disponibles automáticamente en tu documentación Swagger, previa configuración de Swagger en tu proyecto.

Configuración de Swagger

Para habilitar Swagger en tu proyecto, añade el siguiente código en el archivo main.ts de tu aplicación:

import { NestFactory } from '@nestjs/core';
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  // Configuración de Swagger
  const config = new DocumentBuilder()
    .setTitle('API de Usuarios')
    .setDescription(
      'Documentación de la API para la gestión de usuarios, roles y permisos',
    )
    .setVersion('1.0')
    .addBearerAuth()
    .build();

  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api', app, document);

  await app.listen(3000);
}
bootstrap();

Con esta configuración, podrás visualizar la documentación de tu API generada automáticamente en http://localhost:3000/api, donde se mostrarán los tags de Swagger correspondientes a las funciones principales de tu servicio.

🔘 ✉️ Configuración de Plantillas Personalizadas para el MailModule

El MailModule de este paquete permite configurar plantillas personalizadas para los correos electrónicos enviados. Estas plantillas son completamente adaptables y deben incluir ciertas variables clave que serán reemplazadas dinámicamente cuando se envíe el correo.

📝 Variables Clave

Cada plantilla debe incluir las siguientes variables en su sintaxis, las cuales serán reemplazadas automáticamente al enviar el correo:

• {{name}}: El nombre del destinatario.
• {{lastname}}: El apellido del destinatario.
• {{link}}: Un enlace dinámico que varía según el tipo de correo (activación de cuenta, recuperación de contraseña, etc.) que es generado por el sistema.

🔧 Cómo Configurar Plantillas Personalizadas

Para configurar las plantillas personalizadas, debes pasar un objeto con las plantillas deseadas al método forRoot del MailModule. A continuación, se muestra cómo definir y utilizar las plantillas en tu proyecto:

1. Definir Plantillas

Define tus propias plantillas, especificando el asunto y el cuerpo del correo. Asegúrate de incluir las variables {{name}}, {{lastname}} y {{link}}.

const customTemplates = {
  accountActivation: {
    subject: 'Activa tu cuenta en MyApp',
    body: `
      <h1>Hola, {{name}} {{lastname}}</h1>
      <p>Gracias por registrarte en nuestra aplicación. Para activar tu cuenta, haz clic en el siguiente enlace:</p>
      <a href="{{link}}">Activar Cuenta</a>
    `,
  },
  passwordRecovery: {
    subject: 'Recupera tu contraseña en MyApp',
    body: `
      <h1>Hola, {{name}} {{lastname}}</h1>
      <p>Hemos recibido una solicitud para restablecer tu contraseña. Puedes cambiarla haciendo clic en el siguiente enlace:</p>
      <a href="{{link}}">Restablecer Contraseña</a>
    `,
  },
};

2. Configurar el MailModule

Al inicializar el MailModule en tu aplicación, pasa las plantillas personalizadas que acabas de definir mediante el método forRoot.

import { Module } from '@nestjs/common';
import { MailModule } from '@lextomato/nest-users';

@Module({
  imports: [
    MailModule.forRoot({
      accountActivation: {
        subject: 'Activa tu cuenta en MyApp',
        body: `
          <h1>Hola, {{name}} {{lastname}}</h1>
          <p>Para activar tu cuenta, haz clic en el enlace:</p>
          <a href="{{link}}">Activar Cuenta</a>
        `,
      },
      passwordRecovery: {
        subject: 'Recupera tu contraseña en MyApp',
        body: `
          <h1>Hola, {{name}} {{lastname}}</h1>
          <p>Haz clic en el siguiente enlace para recuperar tu contraseña:</p>
          <a href="{{link}}">Recuperar Contraseña</a>
        `,
      },
    }),
  ],
})
export class AppModule {}

🚀 Uso Básico

Aquí tienes un ejemplo básico de cómo utilizar este paquete:

app.module

import {
  AuthModule,
  PermissionsModule,
  RolesModule,
  UsersModule,
} from '@lextomato/nest-users';
import { TypeOrmModule } from '@nestjs/typeorm';

@Module({
  imports: [
    ConfigModule.forRoot({
      envFilePath: './.env',
    }),
    TypeOrmModule.forRoot({
      type: 'postgres',
      host: process.env.DB_HOST,
      port: parseInt(process.env.DB_PORT),
      username: process.env.DB_USER,
      password: process.env.DB_PASS,
      database: process.env.DB_NAME,
      autoLoadEntities: true,
      logging: true,
    }),
    AuthModule,
    UsersModule,
    PermissionsModule,
    RolesModule,
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

📡 API

La API de @lextomato/nest-users ofrece todas las funcionalidades necesarias para gestionar usuarios, roles, permisos, y autenticación en tu aplicación NestJS.

🌟 Endpoints disponibles

Puedes explorar todos los endpoints de la API de forma interactiva a través de nuestra documentación Swagger en línea. En ella encontrarás:

• 📄 Autenticación: Login, logout, recuperación de contraseña y más.
• 👥 Usuarios: CRUD completo para la gestión de usuarios.
• 🛡️ Roles y Permisos: Gestión de roles y permisos para control de acceso.

🌐 Demo en Línea de Swagger

👉 Accede a la documentación Swagger para ver la lista completa de endpoints y probar cada uno de ellos directamente desde la interfaz interactiva.

Documentación Swagger - Demo en Línea 🌍

⚠️ Nota: Esta es una demo estática destinada únicamente para visualización. La funcionalidad interactiva está deshabilitada, por lo que no es posible realizar pruebas de solicitudes o interactuar con los endpoints.

La demo te permitirá:

• Ver ejemplos de respuestas y formatos de solicitudes.
• Entender cómo interactuar con la API utilizando diferentes métodos y parámetros.

📖 Especificaciones

🔑 AuthModule

• Autenticación con JWT: Implementación robusta de autenticación basada en JWT, que incluye validación de sesiones activas y manejo de tokens revocados para máxima seguridad.
• Endpoints de Autenticación: Soporte para login, logout, validación de sesión, cambio de contraseña y recuperación de contraseñas olvidadas.
• Estrategia JWT: Implementación de la estrategia JWT con validación de tokens en cada solicitud y soporte para revocación de tokens.

👥 UsersModule

• CRUD de Usuarios: Funcionalidad completa para la gestión de usuarios, que incluye creación, lectura, actualización y eliminación de usuarios.
• Integración con Roles: Los usuarios pueden ser asignados a roles específicos que definen sus permisos y acceso dentro de la aplicación.

🛡️ RolesModule PermissionsModule

• Roles Guard: Un guardia de roles que asegura que solo los usuarios con los roles y permisos adecuados pueden acceder a determinados recursos o endpoints.
• CRUD de Roles y Permisos: Gestión completa de roles y permisos, permitiendo definir y controlar el acceso a los diferentes módulos y acciones dentro de la aplicación.
• Integración con Módulos: Roles y permisos están integrados directamente con los módulos de autenticación y usuarios, asegurando un control de acceso centralizado.

✉️ MailModule

• Módulo de Correo: Soporte para el envío de correos electrónicos, incluyendo correos de activación de cuenta y recuperación de contraseñas.
• Configuración Dinámica: Permite configurar el transporte de correo (SMTP) y las plantillas de correo de forma dinámica, adaptándose a las necesidades del entorno.

✨ Otras Características

📊 Modularidad y Escalabilidad

• Módulos Independientes: Cada funcionalidad (auth, usuarios, roles, permisos, mail) está encapsulada en su propio módulo, lo que facilita la escalabilidad y el mantenimiento del código.
• Integración Fluida: Los módulos están diseñados para integrarse perfectamente entre sí, proporcionando una base sólida para la construcción de aplicaciones seguras y bien organizadas.

🚀 Fácil Configuración y Extensión

• Configuración Sencilla: Todos los módulos pueden ser configurados fácilmente a través de variables de entorno y opciones de configuración en NestJS.
• Extensible: Diseñado para ser extendido, permitiendo agregar nuevas funcionalidades o modificar las existentes sin romper la estructura principal.

🌟 Ejemplos

🛠️ Ejemplo de Integración Completa

import { Module } from '@nestjs/common';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { ConfigModule } from '@nestjs/config';
import {
  AuthModule,
  PermissionsModule,
  RolesModule,
  UsersModule,
} from '@lextomato/nest-users';
import { TypeOrmModule } from '@nestjs/typeorm';

@Module({
  imports: [
    ConfigModule.forRoot({
      envFilePath: './.env',
    }),
    TypeOrmModule.forRoot({
      type: 'postgres',
      host: process.env.DB_HOST,
      port: parseInt(process.env.DB_PORT),
      username: process.env.DB_USER,
      password: process.env.DB_PASS,
      database: process.env.DB_NAME,
      autoLoadEntities: true,
      logging: true,
    }),
    AuthModule,
    UsersModule,
    PermissionsModule,
    RolesModule,
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

🔐 Protegiendo Rutas con Roles de un Controller en general

import { Controller, Get, UseGuards } from '@nestjs/common';
import { RolesGuard } from '@lextomato/nest-users';
import { JwtAuthGuard, RolesGuard } from '@lextomato/nest-users';

@Controller('admin')
@UseGuards(JwtAuthGuard, RolesGuard) // <-- Usar decorador en el controller principal
export class AdminController {
  @Get('dashboard')
  getDashboard() {
    return 'This is the admin dashboard';
  }

  @Get('profile')
  getDashboard() {
    return 'This is the user profile';
  }
}

NOTA: en este caso se protege todas las rutas del controller 'admin' que incluyen las rutas @Get('dashboard') y @Get('profile').

🔐 Protegiendo una Ruta en especifico con Roles

import { Controller, Get, UseGuards } from '@nestjs/common';
import { RolesGuard } from '@lextomato/nest-users';
import { JwtAuthGuard, RolesGuard } from '@lextomato/nest-users';

@Controller('admin')
export class AdminController {
  @Get('dashboard')
  getDashboard() {
    return 'This is the admin dashboard';
  }

  @Get('profile')
  @UseGuards(JwtAuthGuard, RolesGuard) // <-- Usar decorador en Ruta especifica
  getDashboard() {
    return 'This is the user profile';
  }
}

NOTA: en este caso se protege solo las rutas del controller que tienen el decorador respectivo. Para este caso solo @Get('profile').

🧑‍💻 Contribuciones

Las contribuciones son bienvenidas. Por favor, sigue estos pasos para contribuir:

1. Haz un fork del proyecto desde aquí.
2. Crea una nueva rama (git checkout -b feature/new-function).
3. Haz commit de tus cambios (git commit -am 'Añadir nueva función').
4. Haz push a la rama (git push origin feature/new-function).
5. Crea un nuevo Pull Request.

🔑 Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo 📄LICENSE para más detalles.

💰 Donaciones

Si te gusta este proyecto y te gustaría apoyarlo, considera hacer una donación vía PayPal. Tu apoyo ayuda a mantener este proyecto y mejorar sus funcionalidades.

🔗 Recursos Adicionales

• 🛠️ Issues (Link a la página de Issues para reportar problemas o sugerir mejoras).
• 📘 Documentación de NestJS (Para obtener más información sobre cómo funciona NestJS).

🚀 ¡Gracias por usar @lextomato/nest-users Si tienes alguna pregunta o sugerencia, no dudes en abrir un issue o contribuir al proyecto.