@jmlq/auth 0.0.1-alpha.14 → 0.0.1-alpha.16

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

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

package/dist/application/use-cases/refresh-token.use-case.js

@@ -10,13 +10,21 @@ class RefreshTokenUseCase {
         try {
             // Refrescar la sesión
             const credential = await this.tokenSession.refreshSession(request.refreshToken);
+            // Rotación obligatoria: si no hay refreshToken nuevo, el refresh falló.
+            const newRefreshToken = credential.refreshToken;
+            if (!newRefreshToken || !newRefreshToken.trim()) {
+                // Mensaje genérico por seguridad
+                throw new errors_1.TokenExpiredError();
+            }
             return {
                 sessionId: credential.sessionId.getValue(),
                 accessToken: credential.accessToken,
-                refreshToken: credential.refreshToken,
+                refreshToken: newRefreshToken,
             };
         }
         catch (error) {
+            // Si quieres, aquí puedes mapear SOLO expiración e invalid-token a TokenExpiredError
+            // y relanzar el resto. Mantengo tu comportamiento actual para no cambiar semántica.
             throw new errors_1.TokenExpiredError();
         }
     }

package/dist/domain/entities/credential.entity.d.ts

@@ -19,7 +19,7 @@ export declare class Credential {
     /**
      * Token de refresco asociado
      */
-    private readonly _refreshToken;
+    private readonly _refreshToken?;
     /**
      * Fecha de expiración del token de acceso
      */
@@ -48,7 +48,7 @@ export declare class Credential {
     /**
      * Obtiene el token de refresco
      */
-    get refreshToken(): string;
+    get refreshToken(): string | undefined;
     /**
      * Obtiene la fecha de expiración del token de acceso
      */
@@ -73,9 +73,19 @@ export declare class Credential {
     static create(sessionId: Id, userId: Id, accessToken: string, refreshToken: string, expirationDate: Date): Credential;
     /**
      *Reconstitution method for repository
-     *Método usado por un repositorio para reconstruir la entidad desde la base de datos
-     * @param props Propiedades de las credenciales
-     * @returns Nueva instancia de Credential
+     *refreshToken puede venir undefined si en DB solo existe hash.
      */
     static reconstitute(props: ICredentialProps): Credential;
+    /**
+     * Crea una nueva credencial como resultado de una rotación de refresh token.
+     * Impone que refreshToken exista (rotación obligatoria).
+     */
+    static rotate(props: {
+        sessionId: Id;
+        userId: Id;
+        accessToken: string;
+        refreshToken: string;
+        expiresAt: Date;
+        createdAt?: Date;
+    }): Credential;
 }

package/dist/domain/entities/credential.entity.js

@@ -83,12 +83,24 @@ class Credential {
     }
     /**
      *Reconstitution method for repository
-     *Método usado por un repositorio para reconstruir la entidad desde la base de datos
-     * @param props Propiedades de las credenciales
-     * @returns Nueva instancia de Credential
+     *refreshToken puede venir undefined si en DB solo existe hash.
      */
     static reconstitute(props) {
         return new Credential(props);
     }
+    /**
+     * Crea una nueva credencial como resultado de una rotación de refresh token.
+     * Impone que refreshToken exista (rotación obligatoria).
+     */
+    static rotate(props) {
+        return new Credential({
+            sessionId: props.sessionId,
+            userId: props.userId,
+            accessToken: props.accessToken,
+            refreshToken: props.refreshToken,
+            expiresAt: props.expiresAt,
+            createdAt: props.createdAt ?? new Date(),
+        });
+    }
 }
 exports.Credential = Credential;

package/dist/domain/ports/repository/credential.repository.d.ts

@@ -45,4 +45,19 @@ export interface ICredentialRepositoryPort {
      * Elimina una sesión por refresh token (logout basado en refresh).
      */
     deleteByRefreshToken(refreshToken: string): Promise<void>;
+    /**
+     * Rotación atómica de refresh token (single-use).
+     *
+     * Debe:
+     * - “consumir” el refreshToken actual (el entrante) de forma atómica,
+     * - y persistir la credencial nueva para la MISMA sessionId.
+     *
+     * Retorna true si la rotación ocurrió (1 fila afectada),
+     * false si el refresh token ya fue usado / revocado / no existe.
+     *
+     * Nota:
+     * - El core NO sabe de hashes.
+     * - La implementación infra puede usar refreshTokenHash internamente.
+     */
+    rotateByRefreshToken(currentRefreshToken: string, nextCredential: Credential): Promise<boolean>;
 }

package/dist/domain/props/entities/credential.props.d.ts

@@ -3,7 +3,14 @@ export interface ICredentialProps {
     sessionId: Id;
     userId: Id;
     accessToken: string;
-    refreshToken: string;
+    /**
+     * Token de refresco (secreto).
+     * Nota de seguridad:
+     * - En persistencia NO debe guardarse en claro.
+     * - En reconstitución desde DB puede ser undefined (solo existe el hash).
+     * - En flujos que emiten tokens (login/refresh) debe existir.
+     */
+    refreshToken?: string;
     expiresAt: Date;
     createdAt: Date;
 }

package/dist/in-memory/in-memory-credential.repository.d.ts

@@ -5,6 +5,7 @@ import { Credential, ICredentialRepositoryPort, Id } from "../domain";
  * Soporta múltiples sesiones por usuario (multi-dispositivo) usando `sessionId`.
  */
 export declare class InMemoryCredentialRepository implements ICredentialRepositoryPort {
+    rotateByRefreshToken(currentRefreshToken: string, nextCredential: Credential): Promise<boolean>;
     /**
      * Fuente de verdad: credenciales indexadas por sessionId.
      */

package/dist/in-memory/in-memory-credential.repository.js

@@ -21,6 +21,9 @@ class InMemoryCredentialRepository {
          */
         this.refreshTokenIndex = new Map();
     }
+    rotateByRefreshToken(currentRefreshToken, nextCredential) {
+        throw new Error("Method not implemented.");
+    }
     /**
      * Guarda (upsert) una credencial por (userId, sessionId).
      * - Si existía una credencial para ese sessionId, limpia el índice de refreshToken viejo.
@@ -31,13 +34,14 @@ class InMemoryCredentialRepository {
         const userKey = credential.userId.getValue();
         // Si existía una credencial para esa sesión, limpiar refresh index anterior
         const old = this.credentialsBySessionId.get(sessionKey);
-        if (old) {
+        if (old?.refreshToken) {
             this.refreshTokenIndex.delete(old.refreshToken);
         }
         // Guardar credencial por sesión
         this.credentialsBySessionId.set(sessionKey, credential);
         // Indexar refresh -> session
-        this.refreshTokenIndex.set(credential.refreshToken, sessionKey);
+        if (credential.refreshToken)
+            this.refreshTokenIndex.set(credential.refreshToken, sessionKey);
         // Indexar user -> sessions
         const sessions = this.sessionsByUserId.get(userKey) ?? new Set();
         sessions.add(sessionKey);
@@ -97,7 +101,7 @@ class InMemoryCredentialRepository {
             return;
         for (const sid of sessionIds) {
             const c = this.credentialsBySessionId.get(sid);
-            if (c) {
+            if (c?.refreshToken) {
                 this.refreshTokenIndex.delete(c.refreshToken);
             }
             this.credentialsBySessionId.delete(sid);
@@ -113,7 +117,8 @@ class InMemoryCredentialRepository {
         if (!c)
             return;
         // limpiar refresh index
-        this.refreshTokenIndex.delete(c.refreshToken);
+        if (c.refreshToken)
+            this.refreshTokenIndex.delete(c.refreshToken);
         // limpiar relación user -> sessions
         const userKey = c.userId.getValue();
         const sessions = this.sessionsByUserId.get(userKey);

package/dist/infrastructure/services/token-session.service.d.ts

@@ -2,23 +2,45 @@ import { Credential, ICredentialRepositoryPort, Id, ITokenServicePort, ITokenSes
 /**
  * Servicio de sesiones de usuario (rotación de refresh token) con soporte multi-dispositivo.
  *
- * Responsabilidad:
- * - Orquestar generación/verificación de tokens vía ITokenServicePort
- * - Persistir credenciales por sessionId (dispositivo)
- * - Recuperar usuario
+ * Capa:
+ * - Infraestructura (orquesta ports y persistencia, no contiene reglas de negocio de Auth)
  *
- * Reglas:
+ * Responsabilidades:
+ * - Generar/verificar tokens usando ITokenServicePort (plugin: jose / etc.)
+ * - Persistir credenciales por sessionId (1 fila = 1 sesión/dispositivo)
+ * - Recuperar usuario desde IUserRepositoryPort
+ *
+ * Reglas clave (multi-dispositivo):
  * - createSession: crea sessionId nuevo (nuevo dispositivo/sesión)
  * - refreshSession: rota tokens manteniendo el MISMO sessionId (misma sesión)
- * - validateSession: valida JWT y valida sesión activa en repositorio (revocable)
+ * - validateSession: valida JWT + valida que la sesión exista (revocable) y no expirada
  */
 export declare class TokenSessionService implements ITokenSessionPort {
+    /**
+     * Puerto para operaciones JWT (generar/verificar/expiración).
+     * Implementación típica: jose (via @jmlq/auth-plugin-jose).
+     */
     private readonly tokenService;
+    /**
+     * Puerto de usuarios (fuente de verdad del usuario).
+     * Se usa para:
+     * - encontrar usuario por id (payload.sub)
+     * - validar canLogin()
+     */
     private readonly userRepository;
+    /**
+     * Puerto de credenciales/sesiones (persistencia revocable).
+     * Se usa para:
+     * - save / findBySessionId / findByRefreshToken
+     * - deleteByRefreshToken / deleteBySessionId
+     */
     private readonly credentialRepository;
     /**
      * Expiración del access token en formato humano.
      * @example "15m"
+     *
+     * Nota:
+     * - La interpretación la hace el tokenService (o un parser interno).
      */
     private readonly accessTokenExpiration;
     /**
@@ -26,10 +48,32 @@ export declare class TokenSessionService implements ITokenSessionPort {
      * @example "7d"
      */
     private readonly refreshTokenExpiration;
-    constructor(tokenService: ITokenServicePort, userRepository: IUserRepositoryPort, credentialRepository: ICredentialRepositoryPort, 
+    constructor(
+    /**
+     * Puerto para operaciones JWT (generar/verificar/expiración).
+     * Implementación típica: jose (via @jmlq/auth-plugin-jose).
+     */
+    tokenService: ITokenServicePort, 
+    /**
+     * Puerto de usuarios (fuente de verdad del usuario).
+     * Se usa para:
+     * - encontrar usuario por id (payload.sub)
+     * - validar canLogin()
+     */
+    userRepository: IUserRepositoryPort, 
+    /**
+     * Puerto de credenciales/sesiones (persistencia revocable).
+     * Se usa para:
+     * - save / findBySessionId / findByRefreshToken
+     * - deleteByRefreshToken / deleteBySessionId
+     */
+    credentialRepository: ICredentialRepositoryPort, 
     /**
      * Expiración del access token en formato humano.
      * @example "15m"
+     *
+     * Nota:
+     * - La interpretación la hace el tokenService (o un parser interno).
      */
     accessTokenExpiration?: string, 
     /**
@@ -40,6 +84,19 @@ export declare class TokenSessionService implements ITokenSessionPort {
     /**
      * Emite access/refresh tokens para un usuario y una sesión dada.
      *
+     * Este método es el “núcleo” de emisión de tokens y su claim policy.
+     *
+     * Qué hace:
+     * 1) Construye claims del usuario (id/email/roles)
+     * 2) Deriva permissions efectivas desde roles (RBAC)
+     * 3) Construye customClaims.permissions para que el API pueda autorizar (requirePermissions)
+     * 4) Genera access + refresh
+     * 5) Obtiene expiresAt desde el accessToken (fuente robusta: tokenService)
+     *
+     * Importante:
+     * - permissions vienen de roles.getValuePublic().permissions
+     *   (en el host se “pegan” desde AccessSnapshotResolver)
+     *
      * @param user Usuario autenticado.
      * @param sessionId Identificador de sesión/dispositivo.
      */
@@ -47,6 +104,15 @@ export declare class TokenSessionService implements ITokenSessionPort {
     /**
      * Crea una nueva sesión (nuevo dispositivo).
      *
+     * Flujo:
+     * 1) Genera un sessionId nuevo
+     * 2) Emite tokens atados a ese sessionId
+     * 3) Construye Credential (entidad de dominio de sesión)
+     * 4) Persiste credencial
+     *
+     * Efecto:
+     * - multi-dispositivo: un usuario puede tener N credenciales activas (N sessionId)
+     *
      * @param user Usuario autenticado.
      * @returns Credencial persistida para la nueva sesión.
      */
@@ -54,6 +120,17 @@ export declare class TokenSessionService implements ITokenSessionPort {
     /**
      * Rota refresh token manteniendo el MISMO sessionId (misma sesión/dispositivo).
      *
+     * Flujo:
+     * 1) Busca credencial por refreshToken (revocable)
+     * 2) Verifica refreshToken (firma/exp)
+     * 3) Recupera usuario (payload.sub) y valida canLogin()
+     * 4) Re-emite tokens con el MISMO sessionId
+     * 5) Reemplaza credencial persistida (delete + save)
+     *
+     * Seguridad:
+     * - Si el refreshToken no existe en repositorio => sesión revocada o token inválido => TokenExpiredError
+     * - Verificación JWT también puede lanzar => TokenExpiredError
+     *
      * @param refreshToken Refresh token actual.
      * @returns Nueva credencial rotada para la misma sesión.
      */
@@ -61,11 +138,15 @@ export declare class TokenSessionService implements ITokenSessionPort {
     /**
      * Valida una sesión a partir de access token.
      *
+     * Este método soporta “revocación” (token válido criptográficamente pero sesión eliminada en DB).
+     *
      * Reglas:
      * - JWT debe ser válido (firma/exp/issuer/aud según plugin)
      * - Debe existir `sid` en el payload
-     * - La sesión (sid) debe existir en el repositorio (revocable)
-     * - (opcional pero recomendado) el accessToken debe coincidir con el almacenado
+     * - La sesión (sid) debe existir en el repositorio
+     * - (recomendado) accessToken debe coincidir con el almacenado (solo el último token es válido)
+     * - La credencial no debe estar expirada (según su estado interno)
+     * - El usuario debe existir y poder loguearse
      *
      * @param accessToken Access token recibido.
      * @returns Usuario si sesión es válida, o null si no lo es.
@@ -74,12 +155,22 @@ export declare class TokenSessionService implements ITokenSessionPort {
     /**
      * Revoca una sesión usando refresh token.
      *
+     * Uso típico:
+     * - logout donde el cliente envía refreshToken (cookie/body)
+     *
+     * Efecto:
+     * - la sesión deja de poder refrescar tokens
+     * - si validateSession compara accessToken, también invalida el access actual cuando se borra la credencial
+     *
      * @param refreshToken Refresh token actual.
      */
     revokeSession(refreshToken: string): Promise<void>;
     /**
      * Revoca una sesión por sessionId (logout por dispositivo).
      *
+     * Uso típico:
+     * - logout selectivo (cerrar solo este dispositivo)
+     *
      * @param sessionId Identificador de sesión/dispositivo.
      */
     revokeSessionById(sessionId: Id): Promise<void>;

package/dist/infrastructure/services/token-session.service.js

@@ -1,8 +1,48 @@
 "use strict";
+// src/infrastructure/services/token-session.service.ts
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TokenSessionService = void 0;
-// src/infrastructure/services/token-session.service.ts
 const domain_1 = require("../../domain");
+/**
+ * Type guard para validar arrays de strings en runtime.
+ *
+ * Se usa para:
+ * - evitar suposiciones sobre shapes provenientes de getValuePublic()
+ * - garantizar que "permissions" sea string[] antes de usarlo en claims
+ */
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((v) => typeof v === "string");
+}
+/**
+ * Devuelve valores únicos y ordenados (estable y determinista).
+ *
+ * Por qué importa:
+ * - Evita duplicados en permissions (p.ej. permisos compartidos entre roles)
+ * - Orden estable => tokens más previsibles y facilita testing/debug
+ */
+function uniqSorted(values) {
+    return Array.from(new Set(values)).sort((a, b) => a.localeCompare(b));
+}
+/**
+ * Extrae permissions[] desde el resultado de getValuePublic() de los roles.
+ *
+ * Diseño:
+ * - No asume que permissions existe ni que tiene el tipo correcto.
+ * - Solo agrega cuando es string[].
+ * - Normaliza con uniqSorted().
+ *
+ * Resultado:
+ * - permissions finales efectivas para el usuario en ese instante.
+ */
+function extractPermissionsFromRolesPublic(rolesPublic) {
+    const perms = [];
+    for (const rp of rolesPublic) {
+        if (isStringArray(rp.permissions)) {
+            perms.push(...rp.permissions);
+        }
+    }
+    return uniqSorted(perms);
+}
 /**
  * Extrae el `sid` (sessionId) del payload de forma segura.
  *
@@ -10,30 +50,61 @@ const domain_1 = require("../../domain");
  * - En la mayoría de implementaciones, `sid` viene como claim plano.
  * - Si tu `ITokenServicePort` lo entrega de otra forma, ajusta aquí (único lugar).
  *
+ * Ventaja:
+ * - Centraliza la dependencia en el formato del payload (single source of truth).
+ *
  * @param payload Payload verificado del JWT.
- * @returns sessionId (sid) o undefined si no existe.
+ * @returns sessionId (sid).
  */
 function getSessionIdFromPayload(payload) {
+    // Aquí se asume que IJWTPayload expone "sid" como string.
+    // Si llegara a ser opcional en el tipo, este método debería retornar string | undefined
+    // y el resto del flujo ya está preparado para manejar "falsy".
     return payload.sid;
 }
 /**
  * Servicio de sesiones de usuario (rotación de refresh token) con soporte multi-dispositivo.
  *
- * Responsabilidad:
- * - Orquestar generación/verificación de tokens vía ITokenServicePort
- * - Persistir credenciales por sessionId (dispositivo)
- * - Recuperar usuario
+ * Capa:
+ * - Infraestructura (orquesta ports y persistencia, no contiene reglas de negocio de Auth)
+ *
+ * Responsabilidades:
+ * - Generar/verificar tokens usando ITokenServicePort (plugin: jose / etc.)
+ * - Persistir credenciales por sessionId (1 fila = 1 sesión/dispositivo)
+ * - Recuperar usuario desde IUserRepositoryPort
  *
- * Reglas:
+ * Reglas clave (multi-dispositivo):
  * - createSession: crea sessionId nuevo (nuevo dispositivo/sesión)
  * - refreshSession: rota tokens manteniendo el MISMO sessionId (misma sesión)
- * - validateSession: valida JWT y valida sesión activa en repositorio (revocable)
+ * - validateSession: valida JWT + valida que la sesión exista (revocable) y no expirada
  */
 class TokenSessionService {
-    constructor(tokenService, userRepository, credentialRepository, 
+    constructor(
+    /**
+     * Puerto para operaciones JWT (generar/verificar/expiración).
+     * Implementación típica: jose (via @jmlq/auth-plugin-jose).
+     */
+    tokenService, 
+    /**
+     * Puerto de usuarios (fuente de verdad del usuario).
+     * Se usa para:
+     * - encontrar usuario por id (payload.sub)
+     * - validar canLogin()
+     */
+    userRepository, 
+    /**
+     * Puerto de credenciales/sesiones (persistencia revocable).
+     * Se usa para:
+     * - save / findBySessionId / findByRefreshToken
+     * - deleteByRefreshToken / deleteBySessionId
+     */
+    credentialRepository, 
     /**
      * Expiración del access token en formato humano.
      * @example "15m"
+     *
+     * Nota:
+     * - La interpretación la hace el tokenService (o un parser interno).
      */
     accessTokenExpiration = "15m", 
     /**
@@ -50,38 +121,119 @@ class TokenSessionService {
     /**
      * Emite access/refresh tokens para un usuario y una sesión dada.
      *
+     * Este método es el “núcleo” de emisión de tokens y su claim policy.
+     *
+     * Qué hace:
+     * 1) Construye claims del usuario (id/email/roles)
+     * 2) Deriva permissions efectivas desde roles (RBAC)
+     * 3) Construye customClaims.permissions para que el API pueda autorizar (requirePermissions)
+     * 4) Genera access + refresh
+     * 5) Obtiene expiresAt desde el accessToken (fuente robusta: tokenService)
+     *
+     * Importante:
+     * - permissions vienen de roles.getValuePublic().permissions
+     *   (en el host se “pegan” desde AccessSnapshotResolver)
+     *
      * @param user Usuario autenticado.
      * @param sessionId Identificador de sesión/dispositivo.
      */
     async issueTokens(user, sessionId) {
+        /**
+         * rolesPublic:
+         * - getValuePublic() expone un shape serializable del Role
+         * - se tipa como RolePublic[] vía cast (controlado) para extraer permissions en runtime
+         *
+         * Nota:
+         * - Este cast está contenido aquí.
+         * - Las comprobaciones reales se hacen con isStringArray().
+         */
+        const rolesPublic = user.roles.map((r) => r.getValuePublic());
+        /**
+         * permissions vienen “pegadas” a los roles por el host (API REST):
+         * - AccessSnapshotResolver resuelve roles + permissions actuales
+         * - mapRolesFromSnapshot crea Role(role, Permission[]) y getValuePublic expone permissions
+         */
+        const permissions = extractPermissionsFromRolesPublic(rolesPublic);
+        /**
+         * Custom claims mínimos que necesita el API para requirePermissions().
+         *
+         * Decisión:
+         * - Si no hay permissions => customClaims vacío (JWT más limpio).
+         * - Si hay permissions => { permissions: string[] }.
+         *
+         * Esto hace que requirePermissions() pueda operar solo con JWT,
+         * sin requerir llamadas extra al resolver en cada request.
+         */
+        const customClaims = permissions.length > 0 ? { permissions } : {};
+        /**
+         * userClaims:
+         * - Shape mínimo de usuario que el tokenService necesita
+         * - Evita pasar la entidad User completa (no serializable y con lógica)
+         */
         const userClaims = {
             id: user.id.getValue(),
             email: user.email.getValue(),
             roles: user.roles.map((r) => r.getValuePublic()),
         };
+        /**
+         * Generar access token:
+         * - sessionId se coloca en "sid"
+         * - expiresIn aplica política de expiración configurada
+         * - customClaims adjunta permissions para autorización en el API
+         */
         const accessToken = await this.tokenService.generateAccessToken({
             user: userClaims,
             expiresIn: this.accessTokenExpiration,
             sessionId: sessionId.getValue(),
+            customClaims,
         });
+        /**
+         * Generar refresh token:
+         * - Mantiene mismo sid
+         * - Suele tener expiración mayor
+         * - También transporta customClaims (depende de tu política; aquí se incluye por consistencia)
+         */
         const refreshToken = await this.tokenService.generateRefreshToken({
             user: userClaims,
             expiresIn: this.refreshTokenExpiration,
             sessionId: sessionId.getValue(),
+            customClaims,
         });
-        // Obtener expiración desde el token (robusto, sin depender de parseos propios)
+        /**
+         * Expiración del access token:
+         * - Se deriva desde el token (tokenService), evitando parseos propios
+         * - Reduce riesgo de inconsistencias entre "exp" y cálculos internos
+         */
         const expiresAt = await this.tokenService.getTokenExpiration(accessToken);
         return { accessToken, refreshToken, expiresAt };
     }
     /**
      * Crea una nueva sesión (nuevo dispositivo).
      *
+     * Flujo:
+     * 1) Genera un sessionId nuevo
+     * 2) Emite tokens atados a ese sessionId
+     * 3) Construye Credential (entidad de dominio de sesión)
+     * 4) Persiste credencial
+     *
+     * Efecto:
+     * - multi-dispositivo: un usuario puede tener N credenciales activas (N sessionId)
+     *
      * @param user Usuario autenticado.
      * @returns Credencial persistida para la nueva sesión.
      */
     async createSession(user) {
         const sessionId = domain_1.Id.generate();
         const { accessToken, refreshToken, expiresAt } = await this.issueTokens(user, sessionId);
+        /**
+         * Credential representa la sesión activa.
+         * Suele incluir:
+         * - sessionId
+         * - userId
+         * - accessToken actual
+         * - refreshToken actual
+         * - expiresAt (del access)
+         */
         const credential = domain_1.Credential.create(sessionId, user.id, accessToken, refreshToken, expiresAt);
         await this.credentialRepository.save(credential);
         return credential;
@@ -89,75 +241,151 @@ class TokenSessionService {
     /**
      * Rota refresh token manteniendo el MISMO sessionId (misma sesión/dispositivo).
      *
+     * Flujo:
+     * 1) Busca credencial por refreshToken (revocable)
+     * 2) Verifica refreshToken (firma/exp)
+     * 3) Recupera usuario (payload.sub) y valida canLogin()
+     * 4) Re-emite tokens con el MISMO sessionId
+     * 5) Reemplaza credencial persistida (delete + save)
+     *
+     * Seguridad:
+     * - Si el refreshToken no existe en repositorio => sesión revocada o token inválido => TokenExpiredError
+     * - Verificación JWT también puede lanzar => TokenExpiredError
+     *
      * @param refreshToken Refresh token actual.
      * @returns Nueva credencial rotada para la misma sesión.
      */
     async refreshSession(refreshToken) {
         const existing = await this.credentialRepository.findByRefreshToken(refreshToken);
+        // Si no existe el refreshToken en DB, se considera expirado/revocado
         if (!existing)
             throw new domain_1.TokenExpiredError();
+        /**
+         * Verificación criptográfica y claims:
+         * - Si la firma o exp fallan => TokenExpiredError
+         *
+         * Nota:
+         * - Se oculta el error real por seguridad (no filtrar detalles al cliente).
+         */
         const payload = await this.tokenService
             .verifyRefreshToken(refreshToken)
             .catch(() => {
             throw new domain_1.TokenExpiredError();
         });
+        /**
+         * El sub del payload identifica al usuario.
+         * Se re-carga para:
+         * - validar existencia
+         * - validar estado (canLogin)
+         * - obtener roles/permisos actuales (si el repo resuelve RBAC en cada fetch)
+         */
         const user = await this.userRepository.findById(new domain_1.Id(payload.sub));
         if (!user)
             throw new domain_1.UserNotFoundError();
         if (!user.canLogin())
             throw new domain_1.UserDisabledError();
-        // Mantener identidad de sesión (dispositivo)
+        /**
+         * Mantener identidad de sesión:
+         * - NO se crea un sessionId nuevo
+         * - Se rota token, pero el dispositivo/sesión sigue siendo el mismo
+         */
         const sessionId = existing.sessionId;
         const { accessToken, refreshToken: newRefreshToken, expiresAt, } = await this.issueTokens(user, sessionId);
         const rotated = domain_1.Credential.create(sessionId, user.id, accessToken, newRefreshToken, expiresAt);
         /**
-         * Estrategia simple (sin sobreingeniería):
-         * - Eliminar la sesión por sessionId
-         * - Guardar la nueva credencial rotada (misma sesión)
-         *
-         * Alternativa: credentialRepository.update(rotated)
-         * (si tu implementación hace UPSERT, `save` ya cubre el caso)
+         * Rotación atómica (single-use):
+         * - Si otro request ya consumió este refreshToken, esta operación debe fallar.
+         * - Evita que el mismo refreshToken se use dos veces bajo concurrencia.
          */
-        await this.credentialRepository.deleteBySessionId(sessionId);
-        await this.credentialRepository.save(rotated);
+        const rotatedOk = await this.credentialRepository.rotateByRefreshToken(refreshToken, rotated);
+        if (!rotatedOk) {
+            // Token ya consumido/revocado/no existe (no filtramos detalle)
+            throw new domain_1.TokenExpiredError();
+        }
         return rotated;
     }
     /**
      * Valida una sesión a partir de access token.
      *
+     * Este método soporta “revocación” (token válido criptográficamente pero sesión eliminada en DB).
+     *
      * Reglas:
      * - JWT debe ser válido (firma/exp/issuer/aud según plugin)
      * - Debe existir `sid` en el payload
-     * - La sesión (sid) debe existir en el repositorio (revocable)
-     * - (opcional pero recomendado) el accessToken debe coincidir con el almacenado
+     * - La sesión (sid) debe existir en el repositorio
+     * - (recomendado) accessToken debe coincidir con el almacenado (solo el último token es válido)
+     * - La credencial no debe estar expirada (según su estado interno)
+     * - El usuario debe existir y poder loguearse
      *
      * @param accessToken Access token recibido.
      * @returns Usuario si sesión es válida, o null si no lo es.
      */
     async validateSession(accessToken) {
         try {
+            /**
+             * verifyAccessToken:
+             * - valida firma y exp y claims críticos según configuración del tokenService
+             * - retorna payload tipado como IJWTPayload
+             */
             const payload = await this.tokenService.verifyAccessToken(accessToken);
+            /**
+             * sid:
+             * - identifica la sesión/dispositivo
+             * - si no existe, no podemos validar sesión revocable => null
+             */
             const sid = getSessionIdFromPayload(payload);
             if (!sid)
                 return null;
+            /**
+             * Validación de sesión en storage:
+             * - si no existe => sesión revocada => null
+             */
             const credential = await this.credentialRepository.findBySessionId(new domain_1.Id(sid));
             if (!credential)
                 return null;
-            // Recomendado: asegura que solo el último access token de esa sesión sea válido
+            /**
+             * Validación recomendada:
+             * - asegura que solo el último accessToken emitido para esa sesión sea aceptado
+             * - previene replay de accessTokens antiguos dentro de la misma sesión
+             *
+             * Nota:
+             * - Esto exige que el repo persista accessToken actual.
+             */
             if (credential.accessToken !== accessToken)
                 return null;
+            /**
+             * Validación de expiración a nivel de credencial:
+             * - respaldo adicional (además de "exp" del JWT)
+             * - útil si tu sistema modela expiración o revocación interna
+             */
             if (credential.isExpired())
                 return null;
+            /**
+             * sub del payload identifica al usuario.
+             * Se valida existencia y estado.
+             */
             const user = await this.userRepository.findById(new domain_1.Id(payload.sub));
             return user && user.canLogin() ? user : null;
         }
         catch (e) {
+            /**
+             * SessionAuthError:
+             * - encapsula el error interno (logging/observabilidad)
+             * - evita filtrar detalles sensibles al exterior
+             */
             throw new domain_1.SessionAuthError("Session Authentication failed", e);
         }
     }
     /**
      * Revoca una sesión usando refresh token.
      *
+     * Uso típico:
+     * - logout donde el cliente envía refreshToken (cookie/body)
+     *
+     * Efecto:
+     * - la sesión deja de poder refrescar tokens
+     * - si validateSession compara accessToken, también invalida el access actual cuando se borra la credencial
+     *
      * @param refreshToken Refresh token actual.
      */
     async revokeSession(refreshToken) {
@@ -166,6 +394,9 @@ class TokenSessionService {
     /**
      * Revoca una sesión por sessionId (logout por dispositivo).
      *
+     * Uso típico:
+     * - logout selectivo (cerrar solo este dispositivo)
+     *
      * @param sessionId Identificador de sesión/dispositivo.
      */
     async revokeSessionById(sessionId) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jmlq/auth",
   "description": "JWT authentication package with clean architecture",
-  "version": "0.0.1-alpha.14",
+  "version": "0.0.1-alpha.16",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {