@jmlq/auth 0.0.1-alpha.8 → 0.0.1-beta.1

package/README.es.md

@@ -0,0 +1,133 @@
+# @jmlq/auth 🧩
+
+## 🎯 Objetivo
+
+`@jmlq/auth` es un **core de autenticación** (no un framework) diseñado con **Clean Architecture** para centralizar:
+
+- Casos de uso de autenticación (registro, login, refresh, logout)
+- Flujos de seguridad de contraseña (remember/reset/change)
+- Contratos (ports) para persistencia, hashing y servicios de tokens
+
+El paquete **no expone endpoints HTTP** y está pensado para integrarse desde un host (por ejemplo Express) mediante adapters.
+
+## ⭐ Importancia
+
+- Evita “auth ad‑hoc” por cada API: el **core concentra reglas y casos de uso**.
+- Fuerza separación de responsabilidades: dominio fuerte + infraestructura intercambiable.
+- Habilita sesiones multi‑dispositivo (vía `sessionId/sid`) y rotación/revocación (refresh).
+
+## 🏗️ Arquitectura (visión rápida)
+
+- Punto de entrada: `AuthServiceFactory.create(...)` construye el contenedor de Auth y evita wiring repetido.
+- La sesión se orquesta con `TokenSessionService` (rotación/revocación).
+- El hashing de contraseñas se implementa con `BcryptPasswordHasher`.
+
+➡️ Ver detalle en: [architecture.md](./docs/es/architecture.md)
+
+## 🔧 Implementación
+
+### 5.1 Instalación
+
+```bash
+npm i @jmlq/auth
+```
+
+### 5.2 Dependencias
+
+Dependencia directa del paquete:
+
+- `bcryptjs`
+
+(El host aporta el resto: repositorios, tokens, transporte HTTP, etc.)
+
+### 5.3 Quickstart (implementación rápida)
+
+En un host, la construcción del contenedor se realiza en el composition root (ej. infrastructure/bootstrap):
+
+```ts
+import { AuthServiceFactory } from "@jmlq/auth";
+
+const auth = AuthServiceFactory.create(
+  userRepository,
+  credentialRepository,
+  tokenService,
+  passwordResetToken,
+  emailVerificationToken,
+  {
+    bcryptSaltRounds: 10,
+    accessTokenTtl: "15m",
+    refreshTokenTtl: "7d",
+    // opcional:
+    // passwordResetTokenTtl: "30m",
+    // emailVerificationTokenTtl: "1d",
+  },
+);
+```
+
+### 5.4 Variables de entorno (.env) 📦
+
+`@jmlq/auth` no usa `.env` internamente; el host (API) define su configuración y luego construye adapters.
+
+En el `host` se sugiere declarar variables relacionadas con cookies/headers y generación de links empleados en las funcionalidades de registro y autentificación, por ejemplo:
+
+```ts
+process.env.AUTH_COOKIE_NAME; // => envs.auth.COOKIE_NAME
+process.env.AUTH_FRONTEND_BASE_URL; // => envs.auth.FRONTEND_BASE_URL
+process.env.AUTH_FRONTEND_RESET_PASSWORD_PATH; // => envs.auth.FRONTEND_RESET_PASSWORD_PATH
+
+process.env.AUTH_LINK_API_BASE_URL; // => envs.auth.LINK_API_BASE_URL
+process.env.AUTH_LINK_API_VERIFY_EMAIL_PATH; // => envs.auth.LINK_API_VERIFY_EMAIL_PATH
+```
+
+> Nota: los nombres exactos de las variables `.env` dependen de tu módulo `envs` (host).
+
+### 5.5 Helpers y funcionalidades clave
+
+#### ✅ Validaciones HTTP en el host (Express)
+
+En `host` se pueden aplicar validaciones explícitas antes de delegar al core. Por ejemplo:
+
+- **change-password**: garantiza que `newPassword` sea diferente a `currentPassword` y que coincida con `confirmNewPassword`.
+- **refresh**: obtiene refresh token desde cookie y como fallback desde header.
+- **logout**: es opcional; si no hay refresh token, se limpia cookie y se responde ok.
+
+#### ✅ Headers estándar (fallback de refresh token)
+
+En `host` el header para refresh puede usar el nombre derivado de `envs.auth.COOKIE_NAME`:
+
+- `X-${envs.auth.COOKIE_NAME}`
+
+#### ✅ Generación de links de Password Reset y Verify Email
+
+El `host` genera links combinando `base + path` y parametriza el token con `URL.searchParams`:
+
+- Reset password: `{FRONTEND_BASE_URL}{FRONTEND_RESET_PASSWORD_PATH}?token=...`
+- Verify email: `{LINK_API_BASE_URL}{LINK_API_VERIFY_EMAIL_PATH}?token=...`
+
+## ✅ Checklist (pasos rápidos)
+
+- [Instalar](#51-instalación)
+- [Implementar ports en tu host](./docs/es/configuration.md#ports-que-tu-host-debe-implementar)
+- [Construir el contenedor con AuthServiceFactory](./docs/es/configuration.md#construcción-del-contenedor-authservicefactorycreate)
+- [Integrar con Express](./docs/es/integration-express.md)
+- [Configurar headers/cookies y links](./docs/es/integration-express.md#refresh-token-cookie--header-fallback)
+- [Troubleshooting](./docs/es/troubleshooting.md)
+
+## 📌 Menú
+
+- [Arquitectura](./docs/architecture.md)
+- [Configuración](./docs/es/configuration.md)
+- [Integración Express](./docs/es/integration-express.md)
+- [Troubleshooting](./docs/es/troubleshooting.md)
+
+## 🔗 Referencias
+
+- [`@jmlq/auth-plugin-jose`](../auth-plugin-jose/README.md)
+
+- [`@jmlq/auth`](https://github.com/MLahuasi/jmlq-auth#readme)
+- Plugins relacionados del ecosistema:
+  - [`@jmlq/auth-plugin-jose`](https://github.com/MLahuasi/jmlq-auth-plugin-jose#readme)
+
+## ⬅️ 🌐 Ecosistema
+
+- [`@jmlq`](https://github.com/MLahuasi/jmlq-ecosystem#readme)

package/README.md

@@ -1,259 +1,133 @@
-# @jmlq/auth
+# @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.
+## 🎯 Objective
 
-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.
+`@jmlq/auth` is an **authentication core** (not a framework) designed with **Clean Architecture** to centralize:
 
----
+- Authentication use cases (register, login, refresh, logout)
+- Password security flows (remember/reset/change)
+- Contracts (ports) for persistence, hashing, and token services
 
-## 🚀 Instalación
+This package **does not expose HTTP endpoints** and is intended to be integrated from a host (e.g., Express) via adapters.
 
-```bash
-npm install @jmlq/auth
-```
+## ⭐ Importance
 
-### Dependencias directas
+- Avoids “ad-hoc auth” per API: the **core centralizes rules and use cases**
+- Enforces separation of responsibilities: strong domain + interchangeable infrastructure
+- Enables multi-device sessions (via `sessionId/sid`) and rotation/revocation (refresh)
 
-- `bcryptjs`
+## 🏗️ Architecture (quick view)
 
----
+- Entry point: `AuthServiceFactory.create(...)` builds the Auth container and avoids repetitive wiring
+- Session orchestration via `TokenSessionService` (rotation/revocation)
+- Password hashing implemented with `BcryptPasswordHasher`
 
-## 📖 Documentación
+➡️ See details in: [architecture.md](./docs/en/architecture.md)
 
-- **[🏗️ Documentación de Arquitectura](./architecture.md)** - Clean Architecture, capas y patrones
-- **[📚 Ejemplos de Código](./examples/)** - Casos de uso reales y implementaciones
+## 🔧 Implementation
 
-- Arquitectura basada en **Clean Architecture**
-- Separación estricta:
+### 5.1 Installation
 
-```
-domain → application → infrastructure
+```bash
+    npm i @jmlq/auth
 ```
 
-- Punto de entrada del paquete: **AuthServiceFactory**
+### 5.2 Dependencies
 
----
+Direct dependency of the package:
 
-## ✨ 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
-
----
+- `bcryptjs`
 
-## 🏃‍♂️ Inicio Rápido
+(The host provides the rest: repositories, tokens, HTTP transport, etc.)
 
-### 1️⃣ Bootstrap con AuthServiceFactory
+### 5.3 Quickstart (fast implementation)
 
-La composición de dependencias se realiza fuera del paquete, en el composition root de tu aplicación.
+In a host, the container is built in the composition root (e.g., infrastructure/bootstrap):
 
 ```ts
-import {
-  AuthServiceFactory,
-  InMemoryUserRepository,
-  InMemoryCredentialRepository,
-} from "@jmlq/auth";
-import { JoseTokenService } from "@jmlq/auth/infrastructure";
+import { AuthServiceFactory } from "@jmlq/auth";
 
 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 }
+  userRepository,
+  credentialRepository,
+  tokenService,
+  passwordResetToken,
+  emailVerificationToken,
+  {
+    bcryptSaltRounds: 10,
+    accessTokenTtl: "15m",
+    refreshTokenTtl: "7d",
+    // optional:
+    // passwordResetTokenTtl: "30m",
+    // emailVerificationTokenTtl: "1d",
+  },
 );
 ```
 
-👉 AuthServiceFactory devuelve un **contenedor tipado** con:
-
-- Casos de uso
-- TokenSessionService
-- TokenService
+### 5.4 Environment variables (.env) 📦
 
----
+`@jmlq/auth` does not use `.env` internally; the host (API) defines its configuration and then builds adapters.
 
-### 🧩 Casos de Uso Disponibles
+In the `host`, it is recommended to define variables related to cookies/headers and link generation used in registration and authentication flows, for example:
 
 ```ts
-auth.registerUserUseCase;
-auth.loginWithPasswordUseCase;
-auth.refreshTokenUseCase;
-auth.logoutUseCase;
-```
-
----
-
-## 🔐 Ejemplo de Integración (Express)
+process.env.AUTH_COOKIE_NAME; // => envs.auth.COOKIE_NAME
+process.env.AUTH_FRONTEND_BASE_URL; // => envs.auth.FRONTEND_BASE_URL
+process.env.AUTH_FRONTEND_RESET_PASSWORD_PATH; // => envs.auth.FRONTEND_RESET_PASSWORD_PATH
 
-### 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 });
-  }
-});
+process.env.AUTH_LINK_API_BASE_URL; // => envs.auth.LINK_API_BASE_URL
+process.env.AUTH_LINK_API_VERIFY_EMAIL_PATH; // => envs.auth.LINK_API_VERIFY_EMAIL_PATH
 ```
 
----
+> Note: exact `.env` variable names depend on your host `envs` module.
 
-### Login
+### 5.5 Helpers and key features
 
-```ts
-router.post("/auth/login", async (req, res) => {
-  const result = await auth.loginWithPasswordUseCase.execute(req.body);
+#### ✅ HTTP validations in the host (Express)
 
-  res.cookie("refreshToken", result.refreshToken, {
-    httpOnly: true,
-    sameSite: "lax",
-    path: "/auth/refresh",
-  });
+In the `host`, explicit validations can be applied before delegating to the core. For example:
 
-  res.json({ accessToken: result.accessToken });
-});
-```
+- **change-password**: ensures `newPassword` differs from `currentPassword` and matches `confirmNewPassword`
+- **refresh**: retrieves refresh token from cookie and falls back to header
+- **logout**: optional; if no refresh token, clear cookie and respond ok
 
----
+#### ✅ Standard headers (refresh token fallback)
 
-### Refresh Token
+In the `host`, the refresh header can use the name derived from `envs.auth.COOKIE_NAME`:
 
-```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" });
-  }
-});
-```
+- `X-${envs.auth.COOKIE_NAME}`
 
----
+#### ✅ Password Reset and Verify Email link generation
 
-### Logout
+The `host` generates links by combining `base + path` and passing the token via `URL.searchParams`:
 
-```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 });
-});
-```
-
----
+- Reset password: `{FRONTEND_BASE_URL}{FRONTEND_RESET_PASSWORD_PATH}?token=...`
+- Verify email: `{LINK_API_BASE_URL}{LINK_API_VERIFY_EMAIL_PATH}?token=...`
 
-## 🛡️ Middleware de Autenticación
+## ✅ Checklist (quick steps)
 
-```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" });
-    }
-  };
-}
-```
+- [Install](#51-installation)
+- [Implement ports in your host](./docs/en/configuration.md#ports-que-tu-host-debe-implementar)
+- [Build container with AuthServiceFactory](./docs/en/configuration.md#construcción-del-contenedor-authservicefactorycreate)
+- [Integrate with Express](./docs/en/integration-express.md)
+- [Configure headers/cookies and links](./docs/en/integration-express.md#refresh-token-cookie--header-fallback)
+- [Troubleshooting](./docs/en/troubleshooting.md)
 
----
-
-## 🔒 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();
-  };
-}
-```
+## 📌 Menu
 
----
+- [Architecture](./docs/architecture.md)
+- [Configuration](./docs/en/configuration.md)
+- [Express Integration](./docs/en/integration-express.md)
+- [Troubleshooting](./docs/en/troubleshooting.md)
 
-## 🧠 Flujo de Autenticación Completo
+## 🔗 References
 
-```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
-```
+- [`@jmlq/auth-plugin-jose`](../auth-plugin-jose/README.md)
 
----
+- [`@jmlq/auth`](https://github.com/MLahuasi/jmlq-auth#readme)
+- Related ecosystem plugins:
+  - [`@jmlq/auth-plugin-jose`](https://github.com/MLahuasi/jmlq-auth-plugin-jose#readme)
 
-## 📜 Licencia
+## ⬅️ 🌐 Ecosystem
 
-MIT © MLahuasi
+- [`@jmlq`](https://github.com/MLahuasi/jmlq-ecosystem#readme)

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

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

package/dist/application/dtos/index.js

@@ -16,4 +16,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./request"), exports);
 __exportStar(require("./response"), exports);
-__exportStar(require("./type"), exports);
+__exportStar(require("./types"), exports);

package/dist/application/dtos/request/change-password.request.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Cambiar password desde formulario
+ */
+export interface ChangePasswordRequest {
+    userId: string;
+    sessionId: string;
+    currentPassword: string;
+    newPassword: string;
+    confirmNewPassword: string;
+    /**
+     * Si es true, revoca todas las sesiones del usuario.
+     * Si es false, revoca solo la sesión actual (sessionId).
+     */
+    logoutAllDevices: boolean;
+}

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

@@ -2,3 +2,8 @@ export * from "./login.request";
 export * from "./logout.request";
 export * from "./refresh-token.request";
 export * from "./register-user.request";
+export * from "./request-password-reset.request";
+export * from "./reset-password.request";
+export * from "./change-password.request";
+export * from "./verify-email.request";
+export * from "./me.request";

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

@@ -18,3 +18,8 @@ __exportStar(require("./login.request"), exports);
 __exportStar(require("./logout.request"), exports);
 __exportStar(require("./refresh-token.request"), exports);
 __exportStar(require("./register-user.request"), exports);
+__exportStar(require("./request-password-reset.request"), exports);
+__exportStar(require("./reset-password.request"), exports);
+__exportStar(require("./change-password.request"), exports);
+__exportStar(require("./verify-email.request"), exports);
+__exportStar(require("./me.request"), exports);

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

@@ -1,3 +1,4 @@
 export interface LogoutRequest {
-    refreshToken: string;
+    refreshToken?: string;
+    sessionId?: string;
 }

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

@@ -0,0 +1,3 @@
+export interface MeRequest {
+    userId: string;
+}

package/dist/application/dtos/request/me.request.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

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

package/dist/application/dtos/request/request-password-reset.request.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Solicitar un cambio de password por medio del email (inicio)
+ */
+export interface RequestPasswordResetRequest {
+    email: string;
+}

package/dist/application/dtos/request/request-password-reset.request.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/application/dtos/request/reset-password.request.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Actualizar password usando un token una vez que se envía link a email
+ */
+export interface ResetPasswordRequest {
+    resetToken: string;
+    newPassword: string;
+    confirmNewPassword: string;
+    /**
+     * Política de sesiones post-reset:
+     * - true: logout global (recomendado)
+     * - false: mantener sesiones (si lo permites)
+     */
+    logoutAllDevices?: boolean;
+}

package/dist/application/dtos/request/reset-password.request.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/application/dtos/request/verify-email.request.d.ts

@@ -0,0 +1,3 @@
+export interface VerifyEmailRequest {
+    token: string;
+}

package/dist/application/dtos/request/verify-email.request.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/application/dtos/response/change-password.response.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Respuesta cambio de password desde formulario
+ */
+export interface ChangePasswordResponse {
+    success: true;
+    message: string;
+}

package/dist/application/dtos/response/change-password.response.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -2,3 +2,8 @@ export * from "./login.response";
 export * from "./logout.response";
 export * from "./refresh-token.response";
 export * from "./register-user.response";
+export * from "./reset-password.response";
+export * from "./request-password-reset.response";
+export * from "./change-password.response";
+export * from "./verify-email.response";
+export * from "./me.response";

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

@@ -18,3 +18,8 @@ __exportStar(require("./login.response"), exports);
 __exportStar(require("./logout.response"), exports);
 __exportStar(require("./refresh-token.response"), exports);
 __exportStar(require("./register-user.response"), exports);
+__exportStar(require("./reset-password.response"), exports);
+__exportStar(require("./request-password-reset.response"), exports);
+__exportStar(require("./change-password.response"), exports);
+__exportStar(require("./verify-email.response"), exports);
+__exportStar(require("./me.response"), exports);

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

@@ -1,4 +1,5 @@
 export interface LoginResponse {
+    sessionId: string;
     accessToken: string;
-    refreshToken: string;
+    refreshToken?: string;
 }

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

@@ -0,0 +1,11 @@
+export interface MeResponse {
+    id: string;
+    email: string;
+    isActive: boolean;
+    isEmailVerified: boolean;
+    roles: {
+        role: string;
+    }[];
+    createdAt: string;
+    updatedAt: string;
+}

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

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -1,4 +1,5 @@
 export interface RefreshTokenResponse {
+    sessionId: string;
     accessToken: string;
     refreshToken: string;
 }