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

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

@@ -1,87 +1,340 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TokenSessionService = void 0;
-// src/infrastructure/services/token-session.service.ts
 const domain_1 = require("../../domain");
 /**
- * Servicio de sesiones de usuario (rotación de refresh token).
+ * Extrae el `sid` (sessionId) del payload de forma segura.
  *
- * Este servicio NO debe conocer detalles crypto.
- * Solo orquesta:
- * - generación/verificación de tokens vía ITokenService
- * - persistencia de credenciales
- * - recuperación de usuario
+ * Nota:
+ * - 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).
+ */
+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.
+ *
+ * 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 clave (multi-dispositivo):
+ * - createSession: crea sessionId nuevo (nuevo dispositivo/sesión)
+ * - refreshSession: rota tokens manteniendo el MISMO sessionId (misma sesión)
+ * - validateSession: valida JWT + valida que la sesión exista (revocable) y no expirada
  */
 class TokenSessionService {
-    constructor(tokenService, userRepository, credentialRepository, 
-    // Expiraciones humanas opcionales (si las quieres como string)
-    accessTokenExpiration = "15m", refreshTokenExpiration = "7d") {
+    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", 
+    /**
+     * Expiración del refresh token en formato humano.
+     * @example "7d"
+     */
+    refreshTokenExpiration = "7d") {
         this.tokenService = tokenService;
         this.userRepository = userRepository;
         this.credentialRepository = credentialRepository;
         this.accessTokenExpiration = accessTokenExpiration;
         this.refreshTokenExpiration = refreshTokenExpiration;
     }
-    // Crear una nueva sesión
-    async createSession(user) {
+    /**
+     * 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) {
+        /**
+         * Política:
+         * - JWT delgado: NO roles, NO permissions.
+         * - Authorization se resuelve en el host (BDD) por middleware/servicio.
+         */
+        const userClaims = {
+            id: user.id.getValue(),
+            // email/roles son opcionales y NO se incluyen por defecto.
+        };
+        // Custom claims: no forzamos nada desde el core.
+        // Si el host quiere customClaims, debe hacerlo en su propio flujo/política.
+        const customClaims = {};
+        /**
+         * 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: {
-                id: user.id.toString(),
-                email: user.email.toString(),
-                roles: user.roles.map((r) => r.getValuePublic()),
-            },
+            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: {
-                id: user.id.toString(),
-                email: user.email.toString(),
-                roles: user.roles.map((r) => r.getValuePublic()),
-            },
+            user: userClaims,
             expiresIn: this.refreshTokenExpiration,
+            sessionId: sessionId.getValue(),
+            customClaims,
         });
-        // Obtener expiración desde el token (más robusto)
+        /**
+         * 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);
-        const credential = domain_1.Credential.create(user.id, accessToken, refreshToken, expiresAt);
+        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;
     }
-    // Rotación de refresh token
+    /**
+     * 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.InvalidOrExpiredRefreshTokenError();
-        // Verifica refresh token (firma + exp + issuer/aud si están configurados)
+            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.InvalidOrExpiredRefreshTokenError();
+            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();
-        // Crea nueva sesión
-        const newCredential = await this.createSession(user);
-        // Borra credencial anterior (rotación)
-        await this.credentialRepository.deleteByRefreshToken(refreshToken);
-        return newCredential;
+        /**
+         * 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);
+        /**
+         * 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.
+         */
+        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;
     }
-    // Validación de sesión via access token
+    /**
+     * 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
+     * - (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;
+            /**
+             * 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 {
-            return 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);
         }
     }
-    // Revocar sesión por refresh token
+    /**
+     * 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) {
         await this.credentialRepository.deleteByRefreshToken(refreshToken);
     }
+    /**
+     * 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) {
+        await this.credentialRepository.deleteBySessionId(sessionId);
+    }
 }
 exports.TokenSessionService = TokenSessionService;

package/dist/infrastructure/types/auth-service-container.d.ts

@@ -1,5 +1,10 @@
-import { ICredentialRepositoryPort, IPasswordHasherPort, IPasswordPolicyPort, ITokenServicePort, ITokenSessionPort, IUserRepositoryPort } from "../../domain/ports";
-import { LoginWithPasswordUseCase, LogoutUseCase, RefreshTokenUseCase, RegisterUserUseCase } from "../../application/use-cases";
+import { ICredentialRepositoryPort, IPasswordHasherPort, IPasswordPolicyPort, ITokenServicePort, ITokenSessionPort, IUserRepositoryPort, IPasswordResetTokenPort, IEmailVerificationTokenPort } from "../../domain/ports";
+import { ChangePasswordUseCase, LoginWithPasswordUseCase, LogoutUseCase, MeUseCase, RefreshTokenUseCase, RegisterUserUseCase, RequestPasswordResetUseCase, ResetPasswordUseCase, VerifyEmailUseCase } from "../../application/use-cases";
+/**
+ * IAuthServiceContainer es el punto de composición del módulo de autenticación
+ * Es un contrato que agrupa todas las dependencias y casos de uso de Auth ya construidos,
+ * listos para ser consumidos por una aplicación (API REST, GraphQL, CLI, etc.).
+ */
 export interface IAuthServiceContainer {
     userRepository: IUserRepositoryPort;
     credentialRepository: ICredentialRepositoryPort;
@@ -7,8 +12,22 @@ export interface IAuthServiceContainer {
     tokenService: ITokenServicePort;
     passwordPolicy: IPasswordPolicyPort;
     tokenSession: ITokenSessionPort;
+    passwordResetToken: IPasswordResetTokenPort;
+    /**
+     * Puerto para la gestión de tokens de verificación de email.
+     *
+     * Responsabilidad:
+     * - Emitir tokens temporales (single-use) asociados a un usuario.
+     * - Validar y consumir el token cuando el usuario accede al enlace de verificación.
+     */
+    emailVerificationToken: IEmailVerificationTokenPort;
     registerUserUseCase: RegisterUserUseCase;
     loginWithPasswordUseCase: LoginWithPasswordUseCase;
     refreshTokenUseCase: RefreshTokenUseCase;
     logoutUseCase: LogoutUseCase;
+    requestPasswordResetUseCase: RequestPasswordResetUseCase;
+    resetPasswordUseCase: ResetPasswordUseCase;
+    changePasswordUseCase: ChangePasswordUseCase;
+    verifyEmailUseCase: VerifyEmailUseCase;
+    meUseCase: MeUseCase;
 }

package/dist/shared/index.d.ts

@@ -1 +1,2 @@
 export * from "./utils";
+export * from "./jwt-plugin";

package/dist/shared/index.js

@@ -15,3 +15,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./utils"), exports);
+__exportStar(require("./jwt-plugin"), exports);

package/dist/shared/jwt-plugin/create-jwt-id.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Genera un identificador único para el claim `jti`.
+ * - Usa crypto.randomUUID cuando está disponible.
+ * - Fallback no-crypto para entornos legacy/dev.
+ */
+export declare function createJwtId(): string;

package/dist/shared/jwt-plugin/create-jwt-id.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createJwtId = createJwtId;
+/**
+ * Obtiene el tiempo actual en segundos Unix.
+ *
+ * @returns Timestamp Unix (segundos).
+ */
+function nowUnixSeconds() {
+    return Math.floor(Date.now() / 1000);
+}
+/**
+ * Genera un identificador único para el claim `jti`.
+ * - Usa crypto.randomUUID cuando está disponible.
+ * - Fallback no-crypto para entornos legacy/dev.
+ */
+function createJwtId() {
+    if (hasCryptoRandomUUID(globalThis)) {
+        return globalThis.crypto.randomUUID();
+    }
+    return `jti_${nowUnixSeconds()}_${Math.random().toString(16).slice(2)}`;
+}
+function hasCryptoRandomUUID(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "crypto" in value &&
+        typeof value.crypto === "object" &&
+        typeof value.crypto
+            ?.randomUUID === "function");
+}

package/dist/shared/jwt-plugin/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./normalize-clock-skew-seconds";
+export * from "./normalize-default-expires-in";
+export * from "./read-expires-in";
+export * from "./read-custom-claims";
+export * from "./resolve-expires-in";
+export * from "./is-retryable-auth-code";
+export * from "./read-session-id";
+export * from "./to-date-from-unix-seconds";
+export * from "./create-jwt-id";

package/dist/shared/jwt-plugin/index.js

@@ -0,0 +1,25 @@
+"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("./normalize-clock-skew-seconds"), exports);
+__exportStar(require("./normalize-default-expires-in"), exports);
+__exportStar(require("./read-expires-in"), exports);
+__exportStar(require("./read-custom-claims"), exports);
+__exportStar(require("./resolve-expires-in"), exports);
+__exportStar(require("./is-retryable-auth-code"), exports);
+__exportStar(require("./read-session-id"), exports);
+__exportStar(require("./to-date-from-unix-seconds"), exports);
+__exportStar(require("./create-jwt-id"), exports);

package/dist/shared/jwt-plugin/is-retryable-auth-code.d.ts

@@ -0,0 +1,8 @@
+import type { AuthErrorCode } from "../../domain/errors";
+/**
+ * Determina si un error del core (por código) es "retryable".
+ *
+ * Responsabilidad única:
+ * - Decidir reintento SOLO por `code` (sin jose, sin message, sin heurísticas).
+ */
+export declare function isRetryableAuthCode(code: AuthErrorCode): boolean;

package/dist/shared/jwt-plugin/is-retryable-auth-code.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isRetryableAuthCode = isRetryableAuthCode;
+/**
+ * Determina si un error del core (por código) es "retryable".
+ *
+ * Responsabilidad única:
+ * - Decidir reintento SOLO por `code` (sin jose, sin message, sin heurísticas).
+ */
+function isRetryableAuthCode(code) {
+    return (code === "SIGNATURE_INVALID" ||
+        code === "ALGORITHM_UNSUPPORTED" ||
+        code === "KEY_MISMATCH" ||
+        code === "KEY_NOT_FOUND");
+}

package/dist/shared/jwt-plugin/normalize-clock-skew-seconds.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Normaliza clockSkewSeconds (en segundos).
+ *
+ * Responsabilidad única:
+ * - Aceptar únicamente números válidos
+ * - Convertir a entero (floor)
+ * - Asegurar >= 0
+ *
+ * Reglas:
+ * - no number / NaN => undefined
+ * - < 0 => 0
+ * - >== 0 => floor(value)
+ */
+export declare function normalizeClockSkewSeconds(value: number | undefined): number | undefined;

package/dist/shared/jwt-plugin/normalize-clock-skew-seconds.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeClockSkewSeconds = normalizeClockSkewSeconds;
+/**
+ * Normaliza clockSkewSeconds (en segundos).
+ *
+ * Responsabilidad única:
+ * - Aceptar únicamente números válidos
+ * - Convertir a entero (floor)
+ * - Asegurar >= 0
+ *
+ * Reglas:
+ * - no number / NaN => undefined
+ * - < 0 => 0
+ * - >== 0 => floor(value)
+ */
+function normalizeClockSkewSeconds(value) {
+    if (typeof value !== "number" || Number.isNaN(value))
+        return undefined;
+    if (value < 0)
+        return 0;
+    return Math.floor(value);
+}

package/dist/shared/jwt-plugin/normalize-default-expires-in.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Normaliza defaults de expiración usados por plugins JWT.
+ *
+ * Responsabilidad única:
+ * - Aceptar un shape compatible con { accessToken?, refreshToken? }
+ * - Trim de strings
+ * - Vacío => omitido
+ * - Si queda vacío => undefined
+ *
+ * Importante:
+ * - No depende de types de plugins para evitar acoplamiento.
+ */
+export declare function normalizeDefaultExpiresIn<T extends {
+    accessToken?: string;
+    refreshToken?: string;
+}>(value: T | undefined): T | undefined;

package/dist/shared/jwt-plugin/normalize-default-expires-in.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeDefaultExpiresIn = normalizeDefaultExpiresIn;
+/**
+ * Normaliza defaults de expiración usados por plugins JWT.
+ *
+ * Responsabilidad única:
+ * - Aceptar un shape compatible con { accessToken?, refreshToken? }
+ * - Trim de strings
+ * - Vacío => omitido
+ * - Si queda vacío => undefined
+ *
+ * Importante:
+ * - No depende de types de plugins para evitar acoplamiento.
+ */
+function normalizeDefaultExpiresIn(value) {
+    if (!value)
+        return undefined;
+    const out = {};
+    const accessToken = normalizeOptionalNonEmptyString(value.accessToken);
+    if (accessToken)
+        out.accessToken = accessToken;
+    const refreshToken = normalizeOptionalNonEmptyString(value.refreshToken);
+    if (refreshToken)
+        out.refreshToken = refreshToken;
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+/**
+ * Helper local (mínimo) para evitar dependencia circular en exports del core.
+ */
+function normalizeOptionalNonEmptyString(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const v = value.trim();
+    return v.length > 0 ? v : undefined;
+}

package/dist/shared/jwt-plugin/read-custom-claims.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Lee `customClaims` desde unknown.
+ *
+ * Responsabilidad única:
+ * - Aceptar únicamente un objeto plano serializable (Record<string, unknown>)
+ *
+ * Reglas:
+ * - undefined/null => undefined
+ * - arrays => undefined
+ * - objetos => Record<string, unknown>
+ */
+export declare function readCustomClaims(value: unknown): Record<string, unknown> | undefined;

package/dist/shared/jwt-plugin/read-custom-claims.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readCustomClaims = readCustomClaims;
+/**
+ * Lee `customClaims` desde unknown.
+ *
+ * Responsabilidad única:
+ * - Aceptar únicamente un objeto plano serializable (Record<string, unknown>)
+ *
+ * Reglas:
+ * - undefined/null => undefined
+ * - arrays => undefined
+ * - objetos => Record<string, unknown>
+ */
+function readCustomClaims(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    if (Array.isArray(value))
+        return undefined;
+    return value;
+}

package/dist/shared/jwt-plugin/read-expires-in.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Lee `expiresIn` desde unknown.
+ *
+ * Responsabilidad única:
+ * - Normalizar un valor desconocido a `string | undefined`
+ *
+ * Reglas:
+ * - no string => undefined
+ * - string vacío => undefined
+ * - string con espacios => trim()
+ */
+export declare function readExpiresIn(value: unknown): string | undefined;