@jmlq/auth 0.0.1-alpha.1 → 0.0.1-alpha.3

package/README.md

@@ -1,306 +1,259 @@
-# @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/).
+# @jmlq/auth
+
+🔐 **Core de autenticación JWT** basado en **Arquitectura Limpia**, diseñado como **librería npm agnóstica de framework** para aplicaciones TypeScript/Node.js.
+
+Este paquete **no expone endpoints HTTP**, **no depende de Express/Nest/Fastify** y **no usa `.env` internamente**.  
+Proporciona **casos de uso, servicios y contratos** listos para integrarse en APIs reales.
+
+---
+
+## 🚀 Instalación
+
+```bash
+npm install @jmlq/auth
+```
+
+### Dependencias directas
+
+- `bcryptjs`
+
+---
+
+## 📖 Documentación
+
+- **[🏗️ Documentación de Arquitectura](./architecture.md)** - Clean Architecture, capas y patrones
+- **[📚 Ejemplos de Código](./examples/)** - Casos de uso reales y implementaciones
+
+- Arquitectura basada en **Clean Architecture**
+- Separación estricta:
+
+```
+domain → application → infrastructure
+```
+
+- Punto de entrada del paquete: **AuthServiceFactory**
+
+---
+
+## ✨ Características Principales
+
+- ✅ Clean Architecture real
+- ✅ Framework agnostic
+- ✅ Access Token + Refresh Token
+- ✅ Rotación de refresh tokens
+- ✅ Logout por revocación
+- ✅ Autorización por Roles y Permissions
+- ✅ Password hashing con bcrypt
+- ✅ Repositorios in-memory para testing
+- ✅ TypeScript first
+
+---
+
+## 🏃‍♂️ Inicio Rápido
+
+### 1️⃣ Bootstrap con AuthServiceFactory
+
+La composición de dependencias se realiza fuera del paquete, en el composition root de tu aplicación.
+
+```ts
+import {
+  AuthServiceFactory,
+  InMemoryUserRepository,
+  InMemoryCredentialRepository,
+} from "@jmlq/auth";
+import { JoseTokenService } from "@jmlq/auth/infrastructure";
+
+const auth = AuthServiceFactory.create(
+  new InMemoryUserRepository(),
+  new InMemoryCredentialRepository(),
+  new JoseTokenService({
+    issuer: "my-api",
+    audience: "my-api-clients",
+    algorithm: "HS256",
+    accessTokenSecret: "dev-access-secret",
+    refreshTokenSecret: "dev-refresh-secret",
+    accessTokenExpiration: "15m",
+    refreshTokenExpiration: "7d",
+  }),
+  { bcryptSaltRounds: 10 }
+);
+```
+
+👉 AuthServiceFactory devuelve un **contenedor tipado** con:
+
+- Casos de uso
+- TokenSessionService
+- TokenService
+
+---
+
+### 🧩 Casos de Uso Disponibles
+
+```ts
+auth.registerUserUseCase;
+auth.loginWithPasswordUseCase;
+auth.refreshTokenUseCase;
+auth.logoutUseCase;
+```
+
+---
+
+## 🔐 Ejemplo de Integración (Express)
+
+### Registro
+
+```ts
+router.post("/auth/register", async (req, res) => {
+  try {
+    const result = await auth.registerUserUseCase.execute(req.body);
+    return res.status(201).json(result);
+  } catch (err) {
+    return res.status(400).json({ error: err.message });
+  }
+});
+```
+
+---
+
+### Login
+
+```ts
+router.post("/auth/login", async (req, res) => {
+  const result = await auth.loginWithPasswordUseCase.execute(req.body);
+
+  res.cookie("refreshToken", result.refreshToken, {
+    httpOnly: true,
+    sameSite: "lax",
+    path: "/auth/refresh",
+  });
+
+  res.json({ accessToken: result.accessToken });
+});
+```
+
+---
+
+### Refresh Token
+
+```ts
+router.post("/auth/refresh", async (req, res) => {
+  try {
+    const result = await auth.refreshTokenUseCase.execute({
+      refreshToken: req.cookies.refreshToken,
+    });
+
+    res.cookie("refreshToken", result.refreshToken, {
+      httpOnly: true,
+      sameSite: "lax",
+      path: "/auth/refresh",
+    });
+
+    return res.json({ accessToken: result.accessToken });
+  } catch {
+    return res.status(401).json({ error: "INVALID_REFRESH_TOKEN" });
+  }
+});
+```
+
+---
+
+### Logout
+
+```ts
+router.post("/auth/logout", async (req, res) => {
+  await auth.logoutUseCase.execute({
+    refreshToken: req.cookies.refreshToken,
+  });
+
+  res.clearCookie("refreshToken", { path: "/auth/refresh" });
+  return res.json({ ok: true });
+});
+```
+
+---
+
+## 🛡️ Middleware de Autenticación
+
+```ts
+export function authenticate(tokenService) {
+  return async (req, res, next) => {
+    const header = req.headers.authorization ?? "";
+    const token = header.startsWith("Bearer ") ? header.slice(7) : null;
+
+    if (!token) {
+      return res.status(401).json({ error: "UNAUTHORIZED" });
+    }
+
+    try {
+      req.auth = await tokenService.verifyAccessToken(token);
+      next();
+    } catch {
+      return res.status(401).json({ error: "INVALID_TOKEN" });
+    }
+  };
+}
+```
+
+---
+
+## 🔒 Middleware de Autorización por Permission
+
+```ts
+import { Permission, Id } from "@jmlq/auth";
+
+export function requirePermission(userRepository, permission: string) {
+  return async (req, res, next) => {
+    const userId = req.auth?.sub;
+    if (!userId) {
+      return res.status(401).json({ error: "UNAUTHENTICATED" });
+    }
+
+    const user = await userRepository.findById(new Id(userId));
+    const allowed = user.roles.some((r) =>
+      r.hasPermission(new Permission(permission))
+    );
+
+    if (!allowed) {
+      return res.status(403).json({ error: "FORBIDDEN" });
+    }
+
+    next();
+  };
+}
+```
+
+---
+
+## 🧠 Flujo de Autenticación Completo
+
+```pgsql
+Register → Login → Access → Refresh → Logout → Authorization
+
+```
+
+- **Register**: crea el agregado User
+- **Login**: valida credenciales y crea sesión
+- **Access**: access token por request
+- **Refresh**: rotación de refresh token
+- **Logout**: revocación de sesión
+- **Authorization**: permisos evaluados en dominio
+
+---
+
+## 🔧 Variables de Entorno Recomendadas
+
+```bash
+JWT_ACCESS_SECRET=super-secret
+JWT_REFRESH_SECRET=super-refresh-secret
+JWT_ACCESS_TTL=15m
+JWT_REFRESH_TTL=7d
+JWT_ISSUER=my-api
+JWT_AUDIENCE=my-api-clients
+BCRYPT_SALT_ROUNDS=10
+```
+
+---
+
+## 📜 Licencia
+
+MIT © MLahuasi

package/dist/application/dtos/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./request";
+export * from "./response";
+export * from "./type";

package/dist/application/dtos/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./request"), exports);
+__exportStar(require("./response"), exports);
+__exportStar(require("./type"), exports);

package/dist/application/dtos/request/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./login.request";
+export * from "./logout.request";
+export * from "./refresh-token.request";
+export * from "./register-user.request";

package/dist/{src/application/dtos → application/dtos/request}/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./login.dto"), exports);
-__exportStar(require("./logout.dto"), exports);
-__exportStar(require("./refresh-token.dto"), exports);
-__exportStar(require("./register-user.dto"), exports);
+__exportStar(require("./login.request"), exports);
+__exportStar(require("./logout.request"), exports);
+__exportStar(require("./refresh-token.request"), exports);
+__exportStar(require("./register-user.request"), exports);

package/dist/{src/application/dtos/login.dto.d.ts → application/dtos/request/login.request.d.ts}

@@ -3,7 +3,3 @@ export interface LoginRequest {
     password: string;
     rememberMe?: boolean;
 }
-export interface LoginResponse {
-    accessToken: string;
-    refreshToken: string;
-}

package/dist/application/dtos/request/logout.request.d.ts

@@ -0,0 +1,3 @@
+export interface LogoutRequest {
+    refreshToken: string;
+}

package/dist/application/dtos/request/refresh-token.request.d.ts

@@ -0,0 +1,3 @@
+export interface RefreshTokenRequest {
+    refreshToken: string;
+}

package/dist/application/dtos/request/register-user.request.d.ts

@@ -0,0 +1,6 @@
+import { UserRole } from "../type";
+export interface RegisterUserRequest {
+    email: string;
+    password: string;
+    roles: UserRole[];
+}

package/dist/application/dtos/response/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./login.response";
+export * from "./logout.response";
+export * from "./refresh-token.response";
+export * from "./register-user.response";

package/dist/application/dtos/response/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./login.response"), exports);
+__exportStar(require("./logout.response"), exports);
+__exportStar(require("./refresh-token.response"), exports);
+__exportStar(require("./register-user.response"), exports);