nuxt-authenticate-module 1.0.0

package/README.md

@@ -0,0 +1,332 @@
+# 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](/CHANGELOG.md)
+
+---
+
+## 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:
+
+```bash
+npm install authenticate-module
+```
+
+Si está en un repositorio interno:
+
+```bash
+git submodule add <repository-url> modules/authenticate-module
+```
+
+---
+
+## Configuración
+
+### 1. Configuración de Nuxt
+
+Agrega el módulo a tu configuración de Nuxt en `nuxt.config.ts`:
+
+```typescript
+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.
+
+```env
+# Base de datos (SQL Server) — Opcional si provees repositorios
+DATABASE_URL="sqlserver://servidor:puerto;database=nombre_db;user=usuario;password=contraseña;encrypt=true"
+
+# Clave secreta para JWT — Requerida
+JWT_SECRET="tu_clave_secreta_super_segura"
+```
+
+### 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.
+
+Ejemplo (inyección en `nuxt.config.ts`):
+
+```ts
+export default defineNuxtConfig({
+  modules: ['./modules/authenticate-module/src/module'],
+  authenticateModule: {
+    providers: {
+      userRepository: () => createMyUserRepository(),
+      sessionRepository: () => createMySessionRepository(),
+    }
+  }
+})
+```
+
+Si no se proporcionan proveedores, el módulo puede usar la implementación incluida (Prisma) si está disponible.
+
+### 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):
+
+```ts
+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.
+
+### 3. Configuración de Prisma
+
+Si decides usar la implementación incluida basada en Prisma, ejecuta las migraciones de la base de datos:
+
+```bash
+npx prisma migrate deploy
+npx prisma generate
+```
+
+Si en su lugar inyectas repositorios personalizados (p. ej. el microservicio comparte su propio cliente), no es necesario ejecutar estas migraciones para que el módulo funcione.
+
+---
+
+## 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
+
+```typescript
+// 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
+
+```typescript
+// 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**:
+
+```bash
+# 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
+
+```prisma
+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
+
+```prisma
+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
+- **Tokens JWT**: Firmados con clave secreta robusta
+- **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:
+   ```bash
+   npx prisma migrate deploy
+   ```
+3. **Regenerar el cliente** Prisma:
+   ```bash
+   npx prisma generate
+   ```
+4. **Ejecutar pruebas** para validar la integración:
+   ```bash
+   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.
+

package/dist/module.d.mts

@@ -0,0 +1,10 @@
+import * as _nuxt_schema from '@nuxt/schema';
+
+interface ModuleOptions {
+    enabled: boolean;
+    prefix?: string;
+}
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { ModuleOptions };

package/dist/module.json

@@ -0,0 +1,9 @@
+{
+  "name": "authenticate-module",
+  "configKey": "authenticateModule",
+  "version": "1.0.0",
+  "builder": {
+    "@nuxt/module-builder": "1.0.2",
+    "unbuild": "3.6.1"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,79 @@
+import { defineNuxtModule, createResolver, addComponentsDir, addImportsDir, addServerHandler, addRouteMiddleware, addTypeTemplate } from '@nuxt/kit';
+
+const apiRoutes = [
+  { route: "/api/auth/login", handler: "auth/login.post" },
+  { route: "/api/auth/register", handler: "auth/register.post" },
+  { route: "/api/auth/closeSession", handler: "auth/closeSession.post" }
+];
+
+const pageRoutes = [
+  { name: "user-login", path: "/login", file: "UserLogin.vue" },
+  { name: "user-register", path: "/register", file: "UserRegister.vue" }
+];
+
+function nuxtConfigAlias(nuxt, alias) {
+  nuxt.options.alias = nuxt.options.alias || {};
+  nuxt.options.alias = nuxt.options.alias || {};
+  nuxt.options.alias = {
+    ...nuxt.options.alias,
+    ...alias
+  };
+}
+
+const module$1 = defineNuxtModule({
+  meta: {
+    name: "authenticate-module",
+    configKey: "authenticateModule"
+  },
+  // Configuración por defecto del módulo de autenticación
+  defaults: {
+    enabled: true
+  },
+  async setup(options, nuxt) {
+    if (!options.enabled) return;
+    const { resolve } = createResolver(import.meta.url);
+    nuxtConfigAlias(nuxt, {
+      modules: resolve("./runtime/server/modules"),
+      utility: resolve("./runtime/server/utility"),
+      service: resolve("./runtime/server/service")
+    });
+    addComponentsDir({
+      path: resolve("./runtime/components"),
+      prefix: options.prefix || "Auth"
+    });
+    addImportsDir(resolve("./runtime/composable"));
+    addServerHandler({
+      handler: resolve("./runtime/server/middleware/session.ts"),
+      middleware: true
+    });
+    apiRoutes.forEach(({ route, handler }) => {
+      addServerHandler({
+        route,
+        handler: resolve(`./runtime/server/api/${handler}`)
+      });
+    });
+    addRouteMiddleware({
+      name: "protected",
+      path: resolve("./runtime/middleware/protected.ts"),
+      global: false
+    });
+    nuxt.hook("pages:extend", (pages) => {
+      pageRoutes.forEach(({ name, path, file }) => {
+        pages.push({
+          name,
+          // Nombre de la ruta
+          path,
+          // Ruta de la página en la aplicación
+          file: resolve(`./runtime/page/${file}`)
+          // Componente asociado
+        });
+      });
+    });
+    addTypeTemplate({
+      filename: "types/auth.d.ts",
+      src: resolve("./runtime/server/types/auth.d.ts")
+    });
+  }
+});
+
+export { module$1 as default };

package/dist/runtime/assets/main.css

@@ -0,0 +1 @@
+@import "tailwindcss";@import "@nuxt/ui";

package/dist/runtime/components/UserInfo.d.vue.ts

@@ -0,0 +1,2 @@
+declare const _default: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+export default _default;

package/dist/runtime/components/UserInfo.vue

@@ -0,0 +1,29 @@
+<script setup>
+import { useUserSession } from "#imports";
+const { closeSession } = useCloseSession();
+const { user } = useUserSession();
+</script>
+
+<template>
+  <div class="flex items-center gap-4">
+    <UUser
+      :name="user?.name"
+      :description="`Id de sesi\xF3n: ${user?.sessionId}`"
+      :avatar="{
+  icon: 'material-symbols:account-circle'
+}"
+      chip
+      size="xl"
+    />
+    <UTooltip
+      text="Cerrar sesión"
+    >
+      <UButton
+        class="cursor-pointer"
+        icon="majesticons:logout"
+        color="error"
+        @click="closeSession"
+      />
+    </UTooltip>
+  </div>
+</template>

package/dist/runtime/components/UserInfo.vue.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+export default _default;

package/dist/runtime/composable/closeSession.d.ts

@@ -0,0 +1,3 @@
+export declare function useCloseSession(): {
+    closeSession: () => Promise<void>;
+};

package/dist/runtime/composable/closeSession.js

@@ -0,0 +1,13 @@
+export function useCloseSession() {
+  async function closeSession() {
+    const response = await $fetch("/api/auth/closeSession", {
+      method: "POST"
+    });
+    useToast().add({
+      title: "Sesi\xF3n cerrada con \xE9xito",
+      description: response.message
+    });
+    await navigateTo("/login");
+  }
+  return { closeSession };
+}

package/dist/runtime/middleware/protected.d.ts

@@ -0,0 +1,2 @@
+declare const _default: any;
+export default _default;

package/dist/runtime/middleware/protected.js

@@ -0,0 +1,6 @@
+export default defineNuxtRouteMiddleware(() => {
+  const { loggedIn } = useUserSession();
+  if (!loggedIn.value) {
+    return navigateTo("/login");
+  }
+});

package/dist/runtime/page/UserLogin.d.vue.ts

@@ -0,0 +1,2 @@
+declare const _default: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+export default _default;

package/dist/runtime/page/UserLogin.vue

@@ -0,0 +1,112 @@
+<script setup>
+import * as z from "zod";
+import { useFetchError } from "../utility";
+const { fetch: refreshSession } = useUserSession();
+function getDefaultUser() {
+  const userName = useCookie("rememberedUserName");
+  return userName.value || "";
+}
+const fields = [{
+  name: "userName",
+  type: "text",
+  label: "Nombre de usuario",
+  placeholder: "Ingresa tu nombre de usuario",
+  required: true,
+  defaultValue: getDefaultUser()
+}, {
+  name: "password",
+  label: "Contrase\xF1a",
+  type: "password",
+  placeholder: "Ingresa tu contrase\xF1a",
+  required: true
+}, {
+  name: "remember",
+  label: "Recu\xE9rdame",
+  type: "checkbox",
+  defaultValue: !!getDefaultUser()
+}];
+const schema = z.object({
+  userName: z.string("Nombre de usuario requerido para iniciar sesi\xF3n"),
+  password: z.string("Debe introducir su contrase\xF1a para iniciar sesi\xF3n"),
+  remember: z.boolean().optional()
+});
+const errorRef = useFetchError();
+async function onSubmit(payload) {
+  try {
+    const { user } = await $fetch("/api/auth/login", {
+      method: "POST",
+      body: {
+        userName: payload.data.userName,
+        password: payload.data.password
+      }
+    });
+    await refreshSession();
+    useToast().add({
+      title: "Inicio de sesi\xF3n exitoso",
+      icon: "material-symbols:bookmark-check-rounded",
+      description: `Bienvenido ${user}`
+    });
+    const userName = useCookie("rememberedUserName");
+    if (payload.data.remember) {
+      userName.value = payload.data.userName;
+    } else {
+      userName.value = "";
+    }
+    await navigateTo("/");
+  } catch (error) {
+    const fetchError = error;
+    errorRef.value = fetchError;
+  }
+}
+</script>
+
+<template>
+  <div
+    class="flex items-center justify-center"
+    :style="{ height: '100vh' }"
+  >
+    <UPageCard class="w-full max-w-md">
+      <UAuthForm
+        :schema="schema"
+        :fields="fields"
+        title="Iniciar sesión"
+        icon="i-lucide-lock"
+        :submit="{
+  label: 'Iniciar Sesion',
+  class: 'cursor-pointer'
+}"
+        @submit="onSubmit"
+      >
+        <template #description>
+          Inicio de sesión, sistema de Salva Mar SA
+        </template>
+        <template #validation>
+          <UAlert
+            v-if="errorRef"
+            color="error"
+            icon="i-lucide-info"
+            :title="`Error ${errorRef.statusCode}`"
+            :description="errorRef.data.message"
+          />
+        </template>
+        <template #footer>
+          <div class="flex flex-col gap-1">
+            <ULink
+              to="/register"
+              class="text-primary font-medium"
+            >Registrar usuario</ULink>.
+            <UBadge
+              variant="subtle"
+              color="warning"
+              size="lg"
+            >
+              <span class="text-center">
+                Si olvidó la contraseña contacte al administrador del sistema
+              </span>
+            </UBadge>
+          </div>
+        </template>
+      </UAuthForm>
+    </UPageCard>
+  </div>
+</template>

package/dist/runtime/page/UserLogin.vue.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+export default _default;

package/dist/runtime/page/UserRegister.d.vue.ts

@@ -0,0 +1,2 @@
+declare const _default: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+export default _default;