@jmlq/auth 0.0.1-alpha.1

package/README.md

@@ -0,0 +1,306 @@
+# @ml-dev-core/jwt.auth
+
+🔐 **Paquete de autenticación JWT** con **Arquitectura Limpia** para aplicaciones TypeScript.
+
+## 🚀 Instalación Rápida
+
+```bash
+npm install @ml-dev-core/jwt.auth bcryptjs
+npm install --save-dev @types/bcryptjs
+```
+
+## 📖 Documentación
+
+- **[📋 Instalación y Configuración](./install.md)** - Guías detalladas para Express.js, NestJS y más
+- **[🏗️ Documentación de Arquitectura](./architecture.md)** - Clean Architecture, capas y patrones
+- **[📚 Ejemplos de Código](./examples/)** - Casos de uso reales y implementaciones
+
+## ✨ Características Principales
+
+- ✅ **Clean Architecture**: Separación clara de responsabilidades
+- ✅ **Framework Agnostic**: Compatible con Express, NestJS, Fastify, etc.
+- ✅ **Database Independent**: Repositorios como interfaces
+- ✅ **TypeScript Native**: Tipado fuerte y autocompletado
+- ✅ **JWT Completo**: Access + Refresh tokens con rotación
+- ✅ **Multi-Algorithm**: HS256, RS256, ES256 y más
+- ✅ **Password Security**: Bcrypt con políticas configurables
+- ✅ **Testing Ready**: Repositorios in-memory incluidos
+- ✅ **Production Ready**: Manejo de errores y validaciones
+
+## 🏃‍♂️ Inicio Rápido
+
+### 1. Configuración Básica
+
+```typescript
+import {
+  AuthServiceFactory,
+  IAuthConfig,
+  InMemoryUserRepository,
+  InMemoryCredentialRepository,
+} from "@ml-dev-core/jwt.auth";
+
+const config: IAuthConfig = {
+  jwt: {
+    accessTokenSecret: process.env.JWT_ACCESS_SECRET!,
+    refreshTokenSecret: process.env.JWT_REFRESH_SECRET!,
+    accessTokenExpirationMs: 15 * 60 * 1000, // 15 minutos
+    refreshTokenExpirationMs: 7 * 24 * 60 * 60 * 1000, // 7 días
+    accessTokenExpiration: "15m",
+    refreshTokenExpiration: "7d",
+  },
+  bcrypt: { saltRounds: 12 },
+  algorithm: "HS256",
+  info: {
+    issuer: "your-app",
+    audience: "your-client",
+  },
+};
+
+const authServices = AuthServiceFactory.create(
+  config,
+  new InMemoryUserRepository(),
+  new InMemoryCredentialRepository()
+);
+```
+
+### 2. Casos de Uso
+
+```typescript
+// Registro
+const registerResult = await authServices.registerUserUseCase.execute({
+  email: "user@example.com",
+  password: "SecurePassword123!",
+  confirmPassword: "SecurePassword123!",
+});
+
+// Login
+const loginResult = await authServices.loginWithPasswordUseCase.execute({
+  email: "user@example.com",
+  password: "SecurePassword123!",
+});
+
+console.log("Access Token:", loginResult.accessToken);
+console.log("Refresh Token:", loginResult.refreshToken);
+
+// Refresh
+const refreshResult = await authServices.refreshTokenUseCase.execute({
+  refreshToken: loginResult.refreshToken,
+});
+
+// Logout
+await authServices.logoutUseCase.execute({
+  refreshToken: refreshResult.refreshToken,
+});
+```
+
+### 3. Middleware (Express)
+
+```typescript
+import { JwtTokenVerifier } from "@ml-dev-core/jwt.auth";
+
+export const authMiddleware = async (req, res, next) => {
+  try {
+    const token = req.headers.authorization?.substring(7);
+    const verifier = new JwtTokenVerifier();
+
+    const isValid = await verifier.verify(
+      token,
+      config.jwt.accessTokenSecret,
+      config.algorithm
+    );
+
+    if (!isValid) {
+      return res.status(401).json({ error: "Token inválido" });
+    }
+
+    const payload = await verifier.parsePayload(token);
+    req.user = payload;
+    next();
+  } catch (error) {
+    res.status(401).json({ error: "Error de autenticación" });
+  }
+};
+```
+
+## 🏗️ Arquitectura
+
+```
+┌─────────────────────────────────────────┐
+│           APPLICATION LAYER             │
+│  (Use Cases, DTOs, Factories)           │
+├─────────────────────────────────────────┤
+│            DOMAIN LAYER                 │
+│  (Entities, Value Objects, Ports)       │
+├─────────────────────────────────────────┤
+│         INFRASTRUCTURE LAYER            │
+│  (JWT, Repositories, Security)          │
+├─────────────────────────────────────────┤
+│            SHARED LAYER                 │
+│  (Types, Constants, Utils)              │
+└─────────────────────────────────────────┘
+```
+
+### Capas y Responsabilidades
+
+- **Domain**: Lógica de negocio pura (entities, value objects, interfaces)
+- **Application**: Orquestación de casos de uso y DTOs
+- **Infrastructure**: Implementaciones concretas (JWT, bcrypt, repositorios)
+- **Shared**: Utilidades y tipos compartidos
+
+## 📦 Exports Principales
+
+```typescript
+// Factory principal
+import { AuthServiceFactory } from "@ml-dev-core/jwt.auth";
+
+// Casos de uso
+import {
+  LoginWithPasswordUseCase,
+  RegisterUserUseCase,
+  RefreshTokenUseCase,
+  LogoutUseCase,
+} from "@ml-dev-core/jwt.auth";
+
+// DTOs
+import {
+  LoginRequest,
+  LoginResponse,
+  RegisterUserRequest,
+  RefreshTokenRequest,
+} from "@ml-dev-core/jwt.auth";
+
+// Entidades del dominio
+import { User, Credential } from "@ml-dev-core/jwt.auth";
+
+// Value Objects
+import { Email, HashedPassword, Role, Id } from "@ml-dev-core/jwt.auth";
+
+// Componentes JWT
+import { JwtTokenGenerator, JwtTokenVerifier } from "@ml-dev-core/jwt.auth";
+
+// Implementaciones de seguridad
+import { BcryptPasswordHasher } from "@ml-dev-core/jwt.auth";
+
+// Repositorios in-memory (testing)
+import {
+  InMemoryUserRepository,
+  InMemoryCredentialRepository,
+} from "@ml-dev-core/jwt.auth";
+
+// Interfaces
+import {
+  IUserRepository,
+  ICredentialRepository,
+  IAuthConfig,
+} from "@ml-dev-core/jwt.auth";
+```
+
+## 🔧 Configuración de Variables de Entorno
+
+```bash
+# JWT Secrets
+JWT_ACCESS_SECRET=your_super_secret_access_key_here
+JWT_REFRESH_SECRET=your_super_secret_refresh_key_here
+
+# JWT Timing
+JWT_ACCESS_EXPIRATION=15m
+JWT_REFRESH_EXPIRATION=7d
+
+# JWT Info
+JWT_ISSUER=your-app-name
+JWT_AUDIENCE=your-client-app
+JWT_ALGORITHM=HS256
+
+# Security
+BCRYPT_SALT_ROUNDS=12
+```
+
+## 🧪 Testing
+
+```typescript
+import {
+  AuthServiceFactory,
+  InMemoryUserRepository,
+  InMemoryCredentialRepository,
+} from "@ml-dev-core/jwt.auth";
+
+describe("Auth Tests", () => {
+  let authServices;
+
+  beforeEach(() => {
+    authServices = AuthServiceFactory.create(
+      testConfig,
+      new InMemoryUserRepository(),
+      new InMemoryCredentialRepository()
+    );
+  });
+
+  it("should register and login user", async () => {
+    // Test implementation
+  });
+});
+```
+
+## 📱 Frameworks Soportados
+
+### Express.js
+
+```typescript
+app.use("/auth", authRoutes);
+app.use("/api", authMiddleware);
+```
+
+### NestJS
+
+```typescript
+@UseGuards(JwtAuthGuard)
+@Controller("protected")
+export class ProtectedController {}
+```
+
+### Fastify
+
+```typescript
+fastify.addHook("onRequest", authMiddleware);
+```
+
+## 🔐 Algoritmos JWT Soportados
+
+- **HMAC**: HS256, HS384, HS512 (clave simétrica)
+- **RSA**: RS256, RS384, RS512 (clave asimétrica)
+- **ECDSA**: ES256, ES384, ES512 (curva elíptica)
+
+## 📄 Scripts Disponibles
+
+```bash
+# Construcción
+npm run build
+
+# Testing
+npm test
+npm run test:coverage
+npm run test:watch
+
+# Ejemplos
+npm run example:help          # Ver todos los comandos
+npm run example:all           # Ejecutar todos los ejemplos
+npm run example:use-cases     # Ejemplos de casos de uso
+npm run example:jwt           # Ejemplos de JWT
+npm run example:factories     # Ejemplos de factories
+```
+
+## 📋 Roadmap
+
+- [ ] Integración con Prisma ORM
+- [ ] Soporte para OAuth2
+- [ ] Rate limiting integrado
+- [ ] Audit logging
+- [ ] Multi-tenancy support
+
+## 📜 Licencia
+
+MIT © MLahuasi
+
+---
+
+**¿Necesitas ayuda?** Consulta la [documentación completa](./install.md) o revisa los [ejemplos](./examples/).

package/dist/examples/bcrypt-password-hasher.example.d.ts

@@ -0,0 +1,3 @@
+export declare class BcryptPasswordHasherExample {
+    static Main(): Promise<void>;
+}

package/dist/examples/bcrypt-password-hasher.example.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BcryptPasswordHasherExample = void 0;
+const bcrypt_password_hasher_1 = require("../src/infrastructure/security/bcrypt-password-hasher");
+class BcryptPasswordHasherExample {
+    static async Main() {
+        console.log("=== 🔐 Ejemplo de uso: BcryptPasswordHasher ===\n");
+        // 1️⃣ Contraseñas de prueba
+        const realPassword = "MyStrongPass#123";
+        const wrongPassword = "NotTheRightPass!";
+        const anotherWrong = "123456";
+        console.log("🧾 Password real de prueba:", realPassword);
+        console.log("🧾 Password equivocada 1:", wrongPassword);
+        console.log("🧾 Password equivocada 2:", anotherWrong, "\n");
+        // 2️⃣ Instanciamos el hasher
+        const hasher = new bcrypt_password_hasher_1.BcryptPasswordHasher();
+        // 3️⃣ Generar hash bcrypt desde el password real
+        const hash = await hasher.hash(realPassword);
+        console.log("🔑 Hash generado (bcrypt):");
+        console.log(hash, "\n");
+        // 4️⃣ Verificar el hash con la contraseña correcta
+        const isValid = await hasher.compare(realPassword, hash);
+        console.log("✅ ¿La contraseña REAL coincide con el hash?");
+        console.log("   Resultado:", isValid, "\n");
+        // 5️⃣ Verificar el hash con contraseñas incorrectas
+        const isValidWrong1 = await hasher.compare(wrongPassword, hash);
+        const isValidWrong2 = await hasher.compare(anotherWrong, hash);
+        console.log("❌ ¿Una contraseña equivocada coincide con el hash?");
+        console.log(`   "${wrongPassword}" ->`, isValidWrong1);
+        console.log(`   "${anotherWrong}" ->`, isValidWrong2, "\n");
+        // 6️⃣ Demostrar que NO se puede obtener el password original desde el hash
+        console.log("=== 🔒 Demostración: el hash es unidireccional ===");
+        console.log("Intentando 'recuperar' la contraseña solo a partir del hash...\n");
+        console.log("⚠️ Importante: no existe ninguna función como hasher.reverse(hash).");
+        console.log("Solo podemos PROBAR contraseñas candidatas y comparar.\n");
+        // Simulamos un pequeño ataque por diccionario
+        const candidatePasswords = [
+            "password",
+            "admin",
+            "qwerty",
+            "123456",
+            wrongPassword,
+            anotherWrong,
+            // Nota: aquí a propósito NO incluimos realPassword
+        ];
+        console.log("📚 Diccionario de prueba:");
+        console.log(candidatePasswords, "\n");
+        let recovered = null;
+        let attempts = 0;
+        for (const candidate of candidatePasswords) {
+            attempts++;
+            const matches = await hasher.compare(candidate, hash);
+            console.log(`   🔎 Probando candidato #${attempts}: "${candidate}" -> ${matches ? "COINCIDE" : "no coincide"}`);
+            if (matches) {
+                recovered = candidate;
+                break;
+            }
+        }
+        console.log("");
+        if (recovered) {
+            console.log("⚠️ El diccionario CONTENÍA la contraseña real.");
+            console.log("Se pudo descubrir porque estaba en la lista de candidatos.\n");
+        }
+        else {
+            console.log("✅ El diccionario NO contenía la contraseña real.");
+            console.log("No fue posible recuperar el valor original solo con el hash y este conjunto de candidatos.\n");
+        }
+        console.log("💡 Conclusión:");
+        console.log("- Bcrypt es una función de hash unidireccional: no se puede 'deshashear' para obtener el texto plano.");
+        console.log("- Lo único que se puede hacer es probar contraseñas candidatas con compare(password, hash).");
+        console.log("- Si la contraseña no está en el conjunto que pruebas (diccionario/fuerza bruta), no hay forma práctica de conocerla.");
+    }
+}
+exports.BcryptPasswordHasherExample = BcryptPasswordHasherExample;
+// Para ejecutar este ejemplo directamente con Node (compilado a JS):
+// (async () => {
+//   await BcryptPasswordHasherExample.Main();
+// })();

package/dist/examples/entity-object.example.d.ts

@@ -0,0 +1,39 @@
+export declare class EntityObjectExamples {
+    static Main(): Promise<void>;
+    /**
+     * Ejemplo demostrativo de uso de la clase Email.
+     * Muestra validaciones, comparaciones y manejo de errores.
+     */
+    static RunEmailExample(): Promise<void>;
+    /**
+     * Ejemplo demostrativo de uso de la clase HashedPassword.
+     * Muestra validación de formato, comparación de hashes y manejo de errores.
+     */
+    static RunHashedPasswordExample(): Promise<void>;
+    /**
+     * Ejemplo demostrativo de uso de la clase Id.
+     * Muestra generación, comparación e instanciación manual de identificadores.
+     */
+    static RunIdExample(): Promise<void>;
+    /**
+     * Ejemplo demostrativo de uso de la clase Permission.
+     * Muestra creación, comparación, coincidencias y manejo de errores.
+     */
+    static RunPermissionExample(): Promise<void>;
+    /**
+     * Ejemplo demostrativo de uso de la clase Role.
+     * Muestra creación de roles, validación de roles permitidos, manejo de permisos,
+     * uso de comodines, y verificación de acciones específicas.
+     */
+    static RunRoleExample(): Promise<void>;
+    /**
+     * Ejemplo demostrativo de uso de la entidad User.
+     * Muestra la creación, activación, desactivación y verificación de login.
+     */
+    static RunUserExample(): Promise<void>;
+    /**
+     * Ejemplo demostrativo de uso de la entidad Credential.
+     * Muestra cómo crear, validar y reconstruir credenciales dentro del dominio.
+     */
+    static RunCredentialExample(): Promise<void>;
+}