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

package/dist/domain/ports/auth/index.js

@@ -16,3 +16,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./password-hasher.port"), exports);
 __exportStar(require("./password-policy.port"), exports);
+__exportStar(require("./password-reset-token.port"), exports);
+__exportStar(require("./email-verification-token.port"), exports);

package/dist/domain/ports/auth/password-reset-token.port.d.ts

@@ -0,0 +1,36 @@
+import type { Id } from "../../object-values";
+/**
+ * Contrato para emitir/verificar/consumir tokens de reseteo de contraseña.
+ *
+ * - No usa JWT de access/refresh (separación de responsabilidades).
+ * - Debe soportar TTL y "single-use" (consumir token).
+ * - La implementación vive fuera del core (API REST: DB/Redis/etc).
+ */
+export interface IPasswordResetTokenPort {
+    /**
+     * Emite un token para permitir reset de password.
+     *
+     * @param userId Usuario destino del reset.
+     * @param ttlMs Tiempo de vida en milisegundos.
+     */
+    issue(userId: Id, ttlMs: number): Promise<{
+        token: string;
+        expiresAt: Date;
+    }>;
+    /**
+     * Verifica token sin consumirlo.
+     * Útil para validaciones previas si la implementación lo requiere.
+     */
+    verify(token: string): Promise<{
+        userId: Id;
+        expiresAt: Date;
+    }>;
+    /**
+     * Consume el token (single-use). Si ya fue usado o es inválido, debe fallar.
+     * Recomendación: consumo atómico (transacción) en implementaciones con DB/Redis.
+     */
+    consume(token: string): Promise<{
+        userId: Id;
+        expiresAt: Date;
+    }>;
+}

package/dist/domain/ports/auth/password-reset-token.port.js

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

package/dist/domain/ports/jwt/payload/jwt-payload.port.d.ts

@@ -1,12 +1,34 @@
+/**
+ * Payload canónico del core (@jmlq/auth).
+ *
+ * Importante:
+ * - NO depende de librerías (jose, jsonwebtoken, etc.)
+ * - El runtime del plugin entrega "claims" como unknown => el core normaliza/valida.
+ */
 export interface IJWTPayload {
+    /** Subject (user ID) */
     sub: string;
-    roles: Array<{
+    /**
+     * Roles embebidos en token (opcional).
+     * Nota: en escenarios más estrictos, el host puede NO incluir roles en el JWT.
+     */
+    roles?: Array<{
         role: string;
     }>;
-    customClaims: Record<string, any>;
     jti: string;
     iss?: string;
-    aud?: string;
+    /**
+     * Audience puede venir como string o string[] (dependiendo de la lib).
+     * El core lo acepta y valida.
+     */
+    aud?: string | string[];
     iat: number;
     exp: number;
+    /** claim de sesión (dispositivo) */
+    sid: string;
+    /**
+     * Custom claims del token (opcional).
+     * Evitar `any`: los consumers deben castear explícitamente si requieren shape.
+     */
+    customClaims?: Record<string, unknown>;
 }

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

@@ -1,10 +1,63 @@
 import { Credential } from "../../entities";
 import { Id } from "../../object-values";
+/**
+ * Repositorio de credenciales (sesiones) por usuario/dispositivo.
+ *
+ * - Un usuario puede tener múltiples credenciales activas (una por sessionId).
+ * - Las operaciones deben permitir revocar por sessionId (logout dispositivo)
+ *   y por userId (logout global).
+ */
 export interface ICredentialRepositoryPort {
+    /**
+     * Guarda una credencial.
+     * Recomendación: tratarlo como UPSERT por (userId, sessionId).
+     */
     save(credential: Credential): Promise<void>;
-    findByUserId(userId: Id): Promise<Credential | null>;
+    /**
+     * Devuelve todas las sesiones activas del usuario.
+     * Antes era 1 credencial; ahora debe ser colección.
+     */
+    findByUserId(userId: Id): Promise<Credential[]>;
+    /**
+     * Busca una sesión específica por su identificador (dispositivo).
+     */
+    findBySessionId(sessionId: Id): Promise<Credential | null>;
+    /**
+     * Busca credencial por refresh token (para rotación).
+     * Debe ser único.
+     */
     findByRefreshToken(refreshToken: string): Promise<Credential | null>;
+    /**
+     * Actualiza una credencial existente.
+     * (Opcional si `save` es UPSERT, pero se mantiene para compatibilidad).
+     */
     update(credential: Credential): Promise<void>;
-    delete(userId: Id): Promise<void>;
+    /**
+     * Elimina todas las sesiones del usuario (logout global).
+     * Reemplaza al anterior `delete(userId)` para evitar ambigüedad.
+     */
+    deleteByUserId(userId: Id): Promise<void>;
+    /**
+     * Elimina una sesión por su sessionId (logout por dispositivo).
+     */
+    deleteBySessionId(sessionId: Id): Promise<void>;
+    /**
+     * 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/ports/token/token-session.port.d.ts

@@ -1,7 +1,9 @@
+import { Id } from "../../object-values";
 import { Credential, User } from "../../entities";
 export interface ITokenSessionPort {
     createSession(user: User): Promise<Credential>;
     refreshSession(refreshToken: string): Promise<Credential>;
     validateSession(accessToken: string): Promise<User | null>;
     revokeSession(refreshToken: string): Promise<void>;
+    revokeSessionById(sessionId: Id): Promise<void>;
 }

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

@@ -1,8 +1,16 @@
 import { Id } from "../../object-values";
 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/domain/props/entities/user.props.d.ts

@@ -5,6 +5,7 @@ export interface IUserProps {
     roles: Role[];
     password: HashedPassword;
     isActive: boolean;
+    isEmailVerified: boolean;
     createdAt: Date;
     updatedAt: Date;
 }

package/dist/domain/props/jwt/generate-access-token.props.d.ts

@@ -1,6 +1,7 @@
-import { JwtUser } from ".";
+import { JwtUser } from "./jwt-user";
 export interface IGenerateAccessTokenProps {
     user: JwtUser;
+    sessionId: string;
     expiresIn?: string;
-    customClaims?: Record<string, any>;
+    customClaims?: Record<string, unknown>;
 }

package/dist/domain/props/jwt/generate-refresh-token.props.d.ts

@@ -1,6 +1,7 @@
-import { JwtUser } from ".";
+import { JwtUser } from "./jwt-user";
 export interface IGenerateRefreshTokenProps {
     user: JwtUser;
+    sessionId: string;
     expiresIn?: string;
-    customClaims?: Record<string, any>;
+    customClaims?: Record<string, unknown>;
 }

package/dist/domain/props/jwt/jwt-user.d.ts

@@ -1,7 +1,16 @@
 export interface JwtUser {
+    /**
+     * Identificador único del usuario (claim `sub`).
+     */
     id: string;
-    email: string;
-    roles: {
+    /**
+     * Opcional: algunas apps pueden incluirlo, pero no es requerido por el core.
+     */
+    email?: string;
+    /**
+     * Opcional: JWT delgado (RBAC en BDD).
+     */
+    roles?: {
         role: string;
     }[];
 }

package/dist/domain/services/helpers/assert-jwt-structure.helper.d.ts

@@ -0,0 +1 @@
+export declare function assertJwtStructure(token: string): void;

package/dist/domain/services/helpers/assert-jwt-structure.helper.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertJwtStructure = assertJwtStructure;
+const errors_1 = require("../../../domain/errors");
+function assertJwtStructure(token) {
+    if (typeof token !== "string" || token.trim().length === 0) {
+        throw new errors_1.InvalidJwtEmptyError();
+    }
+    const parts = token.split(".");
+    if (parts.length !== 3) {
+        throw new errors_1.InvalidJwtMalformedError();
+    }
+}

package/dist/domain/services/helpers/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./optional-non-empty-string.helper";
+export * from "./require-non-empty-string.helper";
+export * from "./require-finite-number.helper";
+export * from "./optional-audience.helper";
+export * from "./optional-roles.helper";
+export * from "./optional-record.helper";
+export * from "./assert-jwt-structure.helper";

package/dist/domain/services/helpers/index.js

@@ -0,0 +1,23 @@
+"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("./optional-non-empty-string.helper"), exports);
+__exportStar(require("./require-non-empty-string.helper"), exports);
+__exportStar(require("./require-finite-number.helper"), exports);
+__exportStar(require("./optional-audience.helper"), exports);
+__exportStar(require("./optional-roles.helper"), exports);
+__exportStar(require("./optional-record.helper"), exports);
+__exportStar(require("./assert-jwt-structure.helper"), exports);

package/dist/domain/services/helpers/optional-audience.helper.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Regla canónica de dominio para el claim estándar `aud` (audience).
+ *
+ * Propósito:
+ * - Aceptar `aud` como string o string[] (según librería/plugin).
+ * - Rechazar valores vacíos.
+ * - Si es array: normalizar de forma determinista (dedupe + sort),
+ *   útil para tests y debugging.
+ *
+ * Importante:
+ * - Esta validación es del CORE (@jmlq/auth).
+ * - Los plugins JWT NO deben validar audience; solo entregan payload verificado.
+ */
+export declare function optionalAudience(value: unknown): string | string[] | undefined;

package/dist/domain/services/helpers/optional-audience.helper.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.optionalAudience = optionalAudience;
+const errors_1 = require("../../errors");
+/**
+ * Regla canónica de dominio para el claim estándar `aud` (audience).
+ *
+ * Propósito:
+ * - Aceptar `aud` como string o string[] (según librería/plugin).
+ * - Rechazar valores vacíos.
+ * - Si es array: normalizar de forma determinista (dedupe + sort),
+ *   útil para tests y debugging.
+ *
+ * Importante:
+ * - Esta validación es del CORE (@jmlq/auth).
+ * - Los plugins JWT NO deben validar audience; solo entregan payload verificado.
+ */
+function optionalAudience(value) {
+    // aud ausente => ok
+    if (value == null)
+        return undefined;
+    // aud como string
+    if (typeof value === "string") {
+        const v = value.trim();
+        if (!v) {
+            throw new errors_1.InvalidJwtPayloadError("JWT payload.aud must not be empty", {
+                field: "aud",
+            });
+        }
+        return v;
+    }
+    // aud como string[]
+    if (Array.isArray(value)) {
+        const items = value
+            .filter((x) => typeof x === "string")
+            .map((x) => x.trim())
+            .filter((x) => x.length > 0);
+        if (items.length === 0) {
+            throw new errors_1.InvalidJwtPayloadError("JWT payload.aud must contain at least one non-empty string", { field: "aud" });
+        }
+        // Determinista: sin duplicados y ordenado
+        return Array.from(new Set(items)).sort((a, b) => a.localeCompare(b));
+    }
+    // Tipo inválido
+    throw new errors_1.InvalidJwtPayloadError("JWT payload.aud must be a string or string[]", {
+        field: "aud",
+        receivedType: typeof value,
+    });
+}

package/dist/domain/services/helpers/optional-non-empty-string.helper.d.ts

@@ -0,0 +1 @@
+export declare function readNonEmptyString(value: unknown): string | undefined;

package/dist/domain/services/helpers/optional-non-empty-string.helper.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readNonEmptyString = readNonEmptyString;
+function readNonEmptyString(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const v = value.trim();
+    return v.length > 0 ? v : undefined;
+}

package/dist/domain/services/helpers/optional-record.helper.d.ts

@@ -0,0 +1 @@
+export declare function optionalRecord(value: unknown, field: string): Record<string, unknown> | undefined;

package/dist/domain/services/helpers/optional-record.helper.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.optionalRecord = optionalRecord;
+const errors_1 = require("../../errors");
+function optionalRecord(value, field) {
+    if (value == null)
+        return undefined;
+    if (typeof value !== "object" || Array.isArray(value)) {
+        throw new errors_1.InvalidJwtPayloadError(`JWT payload.${field} must be an object`, {
+            field,
+            receivedType: typeof value,
+        });
+    }
+    return value;
+}

package/dist/domain/services/helpers/optional-roles.helper.d.ts

@@ -0,0 +1,3 @@
+export declare function optionalRoles(value: unknown): Array<{
+    role: string;
+}> | undefined;

package/dist/domain/services/helpers/optional-roles.helper.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.optionalRoles = optionalRoles;
+const errors_1 = require("../../errors");
+function optionalRoles(value) {
+    if (value == null)
+        return undefined;
+    if (!Array.isArray(value)) {
+        throw new errors_1.InvalidJwtPayloadError("JWT payload.roles must be an array", {
+            field: "roles",
+            receivedType: typeof value,
+        });
+    }
+    const out = [];
+    for (const item of value) {
+        if (item == null || typeof item !== "object") {
+            throw new errors_1.InvalidJwtPayloadError("JWT payload.roles items must be objects", {
+                field: "roles",
+            });
+        }
+        const obj = item;
+        const role = obj.role;
+        if (typeof role !== "string" || !role.trim()) {
+            throw new errors_1.InvalidJwtPayloadError("JWT payload.roles[].role must be a non-empty string", {
+                field: "roles.role",
+            });
+        }
+        out.push({ role: role.trim() });
+    }
+    // Si vino array vacío, lo retornamos como [] (válido).
+    return out;
+}

package/dist/domain/services/helpers/require-finite-number.helper.d.ts

@@ -0,0 +1 @@
+export declare function requireFiniteNumber(value: unknown, field: string): number;

package/dist/domain/services/helpers/require-finite-number.helper.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireFiniteNumber = requireFiniteNumber;
+const errors_1 = require("../../errors");
+function requireFiniteNumber(value, field) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new errors_1.InvalidJwtPayloadError(`JWT payload.${field} must be a finite number`, {
+            field,
+        });
+    }
+    return value;
+}

package/dist/domain/services/helpers/require-non-empty-string.helper.d.ts

@@ -0,0 +1 @@
+export declare function requireNonEmptyString(value: unknown, field: string): string;

package/dist/domain/services/helpers/require-non-empty-string.helper.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireNonEmptyString = requireNonEmptyString;
+const errors_1 = require("../../errors");
+function requireNonEmptyString(value, field) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new errors_1.InvalidJwtPayloadError(`JWT payload.${field} must be a non-empty string`, {
+            field,
+        });
+    }
+    return value.trim();
+}

package/dist/domain/services/index.d.ts

@@ -1 +1,2 @@
 export * from "./password-policy.service";
+export * from "./normalize-jwt-payload.service";

package/dist/domain/services/index.js

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

package/dist/domain/services/normalize-jwt-payload.service.d.ts

@@ -0,0 +1,19 @@
+import type { IJWTPayload } from "../ports";
+/**
+ * Domain Service
+ * --------------
+ * Normaliza y valida un payload JWT según las reglas del dominio.
+ *
+ * - Entrada: unknown (claims verificados por infraestructura/plugin)
+ * - Salida: IJWTPayload tipado y confiable
+ *
+ * Importante:
+ * - NO verifica firma
+ * - NO parsea JWT
+ * - Define únicamente reglas de dominio
+ *
+ * Contrato:
+ * - `aud` se valida exclusivamente aquí vía `optionalAudience()`.
+ * - Cualquier error de `aud` debe provenir de `InvalidJwtPayloadError`.
+ */
+export declare function normalizeJwtPayload(input: unknown): IJWTPayload;

package/dist/domain/services/normalize-jwt-payload.service.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeJwtPayload = normalizeJwtPayload;
+const errors_1 = require("../errors");
+const helpers_1 = require("./helpers");
+/**
+ * Domain Service
+ * --------------
+ * Normaliza y valida un payload JWT según las reglas del dominio.
+ *
+ * - Entrada: unknown (claims verificados por infraestructura/plugin)
+ * - Salida: IJWTPayload tipado y confiable
+ *
+ * Importante:
+ * - NO verifica firma
+ * - NO parsea JWT
+ * - Define únicamente reglas de dominio
+ *
+ * Contrato:
+ * - `aud` se valida exclusivamente aquí vía `optionalAudience()`.
+ * - Cualquier error de `aud` debe provenir de `InvalidJwtPayloadError`.
+ */
+function normalizeJwtPayload(input) {
+    if (input == null || typeof input !== "object") {
+        throw new errors_1.InvalidJwtPayloadError("JWT payload must be an object", {
+            receivedType: typeof input,
+        });
+    }
+    const obj = input;
+    // Required
+    const sub = (0, helpers_1.requireNonEmptyString)(obj.sub, "sub");
+    const sid = (0, helpers_1.requireNonEmptyString)(obj.sid, "sid");
+    const jti = (0, helpers_1.requireNonEmptyString)(obj.jti, "jti");
+    const iat = (0, helpers_1.requireFiniteNumber)(obj.iat, "iat");
+    const exp = (0, helpers_1.requireFiniteNumber)(obj.exp, "exp");
+    // Optional
+    const iss = (0, helpers_1.readNonEmptyString)(obj.iss);
+    /**
+     * Canonical audience rule (core):
+     * - string | string[] | undefined
+     * - empty string or empty array => InvalidJwtPayloadError
+     * - array => dedupe + sort
+     */
+    const aud = (0, helpers_1.optionalAudience)(obj.aud);
+    const roles = (0, helpers_1.optionalRoles)(obj.roles);
+    const customClaims = (0, helpers_1.optionalRecord)(obj.customClaims, "customClaims");
+    return {
+        sub,
+        sid,
+        jti,
+        iat,
+        exp,
+        ...(iss ? { iss } : {}),
+        ...(aud ? { aud } : {}),
+        ...(roles ? { roles } : {}),
+        ...(customClaims ? { customClaims } : {}),
+    };
+}

package/dist/domain/types/access-snapshot.type.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Snapshot de acceso “en este instante”.
+ *
+ * “Snapshot” porque representa una fotografía de roles/permisos efectivos
+ * en un momento dado (por ejemplo: al momento de emitir el token o responder /me).
+ *
+ * Importante:
+ * - No implica que sea la "fuente de verdad" para siempre.
+ * - La fuente de verdad real es la BDD (y se revalida por middleware en el host).
+ */
+export type AccessSnapshot = Readonly<{
+    userId: string;
+    roles: readonly string[];
+    permissions: readonly string[];
+}>;

package/dist/domain/types/access-snapshot.type.js

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

package/dist/domain/types/index.d.ts

@@ -0,0 +1 @@
+export type { AccessSnapshot } from "./access-snapshot.type";

package/dist/domain/types/index.js

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

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

@@ -1,12 +1,75 @@
 import { Credential, ICredentialRepositoryPort, Id } from "../domain";
+/**
+ * Implementación en memoria del repositorio de credenciales.
+ *
+ * Soporta múltiples sesiones por usuario (multi-dispositivo) usando `sessionId`.
+ */
 export declare class InMemoryCredentialRepository implements ICredentialRepositoryPort {
-    private credentials;
+    /**
+     * Fuente de verdad: credenciales indexadas por sessionId.
+     */
+    private credentialsBySessionId;
+    /**
+     * Índice: userId -> sessionIds (para obtener todas las sesiones del usuario).
+     */
+    private sessionsByUserId;
+    /**
+     * Índice: refreshToken -> sessionId (para refresh rotation).
+     *
+     * Regla:
+     * - Si un refresh token rota, el anterior se “consume” (se elimina del índice).
+     * - Esto permite emular la semántica single-use de una rotación atómica en DB.
+     */
     private refreshTokenIndex;
+    /**
+     * Rotación atómica de refresh token (single-use).
+     *
+     * Retorna:
+     * - true: si `currentRefreshToken` existía y coincidía con la credencial actual de la sesión,
+     *         y se reemplazó por `nextCredential`.
+     * - false: si el refresh token no existe, ya fue consumido, o no coincide con la credencial actual.
+     *
+     * Invariante:
+     * - `nextCredential.sessionId` debe ser el mismo sessionId de la credencial actual.
+     */
+    rotateByRefreshToken(currentRefreshToken: string, nextCredential: Credential): Promise<boolean>;
+    /**
+     * Guarda (upsert) una credencial por (userId, sessionId).
+     * - Si existía una credencial para ese sessionId, limpia el índice de refreshToken viejo.
+     * - Actualiza el índice userId -> sessionIds.
+     */
     save(credential: Credential): Promise<void>;
-    findByUserId(userId: Id): Promise<Credential | null>;
+    /**
+     * Devuelve todas las credenciales (sesiones) del usuario.
+     */
+    findByUserId(userId: Id): Promise<Credential[]>;
+    /**
+     * Busca una credencial por sessionId.
+     */
+    findBySessionId(sessionId: Id): Promise<Credential | null>;
+    /**
+     * Busca una credencial por refresh token.
+     */
     findByRefreshToken(refreshToken: string): Promise<Credential | null>;
+    /**
+     * Actualiza una credencial existente.
+     * (Mantiene compatibilidad con el port; internamente equivale a save + validación).
+     */
     update(credential: Credential): Promise<void>;
-    delete(userId: Id): Promise<void>;
+    /**
+     * Elimina todas las sesiones del usuario (logout global).
+     */
+    deleteByUserId(userId: Id): Promise<void>;
+    /**
+     * Elimina una sesión por sessionId (logout por dispositivo).
+     */
+    deleteBySessionId(sessionId: Id): Promise<void>;
+    /**
+     * Elimina una sesión por refresh token.
+     */
     deleteByRefreshToken(refreshToken: string): Promise<void>;
+    /**
+     * Método auxiliar para tests.
+     */
     clear(): void;
 }