@jmlq/auth-plugin-jose 0.0.1-alpha.1

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

@@ -0,0 +1,309 @@
+"use strict";
+// src/infrastructure/services/jose-token.service.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JoseTokenService = void 0;
+const jose_1 = require("jose");
+const mappers_1 = require("../mappers");
+const internal_1 = require("./internal");
+// -----------------------------------------------------------------------------
+// Class
+// -----------------------------------------------------------------------------
+/**
+ * Implementación de `ITokenServicePort` usando la librería `jose`.
+ *
+ * ### ¿Qué hace esta clase?
+ * Orquesta operaciones de JWT para el core:
+ * - Generar tokens (access/refresh)
+ * - Verificar tokens (access/refresh)
+ * - Obtener expiración (exp) con política "verify-first"
+ *
+ * ### ¿Qué NO hace esta clase?
+ * - No contiene lógica de negocio (usuarios, sesiones, permisos, etc.)
+ * - No define errores propios del plugin
+ *
+ * ### Claims relevantes (explicación simple)
+ * - `sub`: Subject. Aquí se usa como `user.id`.
+ * - `jti`: Token ID. Identificador único del token.
+ * - `iat`: Issued At. Momento de creación del token (segundos Unix).
+ * - `exp`: Expiration. Momento de expiración (segundos Unix).
+ * - `iss`: Issuer. Emisor (opcional, configurable).
+ * - `aud`: Audience. Audiencia (opcional, configurable).
+ *
+ * ### Manejo de errores
+ * Cualquier error técnico de `jose` se captura y traduce a un error del core
+ * mediante `createAuthError` + el mapper `toAuthDomainError`.
+ *
+ * @template TAuthError Tipo concreto de Error del core.
+ */
+class JoseTokenService {
+    /**
+     * Crea el servicio.
+     *
+     * @param options Configuración del plugin (keys/issuer/audience/clockSkew).
+     * @param createAuthError Función para construir errores del core.
+     */
+    constructor(options, createAuthError) {
+        this.options = options;
+        this.createAuthError = createAuthError;
+    }
+    // ---------------------------------------------------------------------------
+    // Public API
+    // ---------------------------------------------------------------------------
+    /**
+     * Genera un Access Token.
+     *
+     * @param props Props definidos por el core:
+     * - user.id se asigna al claim `sub`
+     * - user.roles se incluye en el payload
+     * - customClaims opcional en payload (si el core lo define en props)
+     * - expiresIn opcional (si se incluye, sobreescribe defaultExpiresIn)
+     * @returns JWT compacto (string: "header.payload.signature")
+     */
+    async generateAccessToken(props) {
+        return this.generateToken("access", "generateAccessToken", props);
+    }
+    /**
+     * Genera un Refresh Token.
+     *
+     * @param props Props definidos por el core:
+     * - user.id se asigna al claim `sub`
+     * - user.roles se incluye en el payload
+     * - customClaims opcional en payload (si el core lo define en props)
+     * - expiresIn opcional (si se incluye, sobreescribe defaultExpiresIn)
+     * @returns JWT compacto (string: "header.payload.signature")
+     */
+    async generateRefreshToken(props) {
+        return this.generateToken("refresh", "generateRefreshToken", props);
+    }
+    /**
+     * Verifica un Access Token.
+     *
+     * Verificación incluye:
+     * - Firma válida según keys + algoritmo
+     * - `iss` y `aud` si están configurados
+     * - `exp` y `nbf` (si existe) considerando clockSkew
+     *
+     * @param token JWT compacto (string).
+     * @returns Payload normalizado al tipo `IJWTPayload` del core.
+     */
+    async verifyAccessToken(token) {
+        return this.verifyToken("access", "verifyAccessToken", token);
+    }
+    /**
+     * Verifica un Refresh Token.
+     *
+     * @param token JWT compacto (string).
+     * @returns Payload normalizado al tipo `IJWTPayload` del core.
+     */
+    async verifyRefreshToken(token) {
+        return this.verifyToken("refresh", "verifyRefreshToken", token);
+    }
+    /**
+     * Devuelve la fecha de expiración (`exp`) del token.
+     *
+     * Política aplicada: **verify-first** (obligatoria en este proyecto)
+     *
+     * Estrategia práctica:
+     * 1) Intenta verificar como access:
+     *    - Si verifica, devuelve `payload.exp`.
+     *    - Si falla y el error es "retryable", intenta refresh.
+     *    - Si falla por expiración, intenta leer `exp` por decode (sin verificar firma).
+     *
+     * 2) Intenta verificar como refresh:
+     *    - Mismo comportamiento para el caso expirado.
+     *
+     * @param token JWT compacto (string).
+     * @returns Date correspondiente a `exp`.
+     * @throws Error del core (TAuthError) cuando no se puede determinar la expiración.
+     */
+    async getTokenExpiration(token) {
+        const policy = this.options.getExpirationPolicy ?? "verify-first";
+        // Contrato del proyecto: solo soportamos verify-first en el plugin.
+        if (policy !== "verify-first") {
+            throw this.createAuthError({
+                code: "JWT_ERROR",
+                message: "Unsupported expiration policy",
+                meta: { operation: "getTokenExpiration", tokenKind: "unknown" },
+            });
+        }
+        // A1: Intentar access primero (por convención suele ser lo más común).
+        try {
+            const payload = await this.verifyToken("access", "getTokenExpiration", token);
+            return (0, internal_1.toDateFromUnixSeconds)(payload.exp);
+        }
+        catch (e) {
+            // Cuando el token expiró, el verify falla. Aun así, exp está dentro del token.
+            // Decodificar (sin verificar) permite devolver la fecha de expiración.
+            const exp = (0, internal_1.tryReadExpByDecode)(token);
+            const mapped = (0, mappers_1.mapJoseErrorToAuthError)(e, this.ctx("getTokenExpiration", "access"));
+            // Caso especial: token expirado y exp disponible por decode.
+            if (mapped.code === "TOKEN_EXPIRED" && exp !== null) {
+                return (0, internal_1.toDateFromUnixSeconds)(exp);
+            }
+            // Si el error no es "retryable", no tiene sentido probar refresh.
+            if (!(0, internal_1.isRetryableMappedCode)(mapped.code)) {
+                throw e;
+            }
+        }
+        // Fallback: intentar refresh
+        try {
+            const payload = await this.verifyToken("refresh", "getTokenExpiration", token);
+            return (0, internal_1.toDateFromUnixSeconds)(payload.exp);
+        }
+        catch (e) {
+            const exp = (0, internal_1.tryReadExpByDecode)(token);
+            const mapped = (0, mappers_1.mapJoseErrorToAuthError)(e, this.ctx("getTokenExpiration", "refresh"));
+            if (mapped.code === "TOKEN_EXPIRED" && exp !== null) {
+                return (0, internal_1.toDateFromUnixSeconds)(exp);
+            }
+            throw e;
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Internals - ctx + error wrapper
+    // ---------------------------------------------------------------------------
+    /**
+     * Construye un contexto técnico para mapear errores.
+     *
+     * El contexto agrega información útil:
+     * - operación (generate/verify/getExpiration)
+     * - tipo de token (access/refresh)
+     * - issuer/audience/alg efectivos
+     *
+     * Esto permite que el mapper traduzca un error de `jose` a un código del core.
+     *
+     * @param operation Operación que se está ejecutando.
+     * @param kind Tipo de token al que aplica la operación.
+     * @returns Contexto técnico para el mapper de errores.
+     */
+    ctx(operation, kind) {
+        if (kind === "unknown") {
+            return (0, internal_1.buildJoseCtx)(operation, "unknown", {
+                issuer: undefined,
+                audience: undefined,
+                alg: undefined,
+            });
+        }
+        const eff = (0, internal_1.getEffectiveConfig)(this.options, kind);
+        return (0, internal_1.buildJoseCtx)(operation, kind, eff);
+    }
+    /**
+     * Wrapper de errores: captura errores técnicos y los convierte a errores del core.
+     *
+     * Esta función garantiza que la API pública del plugin nunca “escape” errores de jose.
+     *
+     * @param operation Operación actual (para el contexto de error).
+     * @param kind Tipo de token (access/refresh).
+     * @param fn Función async que ejecuta la operación real.
+     * @returns Resultado de la operación si todo sale bien.
+     * @throws Error del core (TAuthError) si algo falla.
+     */
+    async withAuthError(operation, kind, fn) {
+        try {
+            return await fn();
+        }
+        catch (e) {
+            // Convierte el error técnico a un AuthDomainError (core) usando el mapper.
+            throw (0, mappers_1.toAuthDomainError)(this.createAuthError, e, this.ctx(operation, kind));
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Internals - keys
+    // ---------------------------------------------------------------------------
+    /**
+     * Obtiene las keys normalizadas para firmar/verificar tokens.
+     *
+     * La normalización sucede una sola vez (lazy) para evitar:
+     * - importación repetida de PEM
+     * - creación repetida de Uint8Array para HS256
+     *
+     * @param kind Tipo de token (access/refresh).
+     * @returns Keys normalizadas según algoritmo.
+     */
+    getNormalizedKeys(kind) {
+        if (kind === "access") {
+            // Cache lazy: la primera vez normaliza, luego reutiliza.
+            this.accessKeysPromise ?? (this.accessKeysPromise = (0, internal_1.normalizeKeyMaterial)(this.options.access.keys));
+            return this.accessKeysPromise;
+        }
+        this.refreshKeysPromise ?? (this.refreshKeysPromise = (0, internal_1.normalizeKeyMaterial)(this.options.refresh.keys));
+        return this.refreshKeysPromise;
+    }
+    // ---------------------------------------------------------------------------
+    // Internals - token ops
+    // ---------------------------------------------------------------------------
+    /**
+     * Genera un token JWT (access o refresh).
+     *
+     * Qué hace internamente (explicación simple):
+     * - Calcula config efectiva (issuer/audience/clockSkew/alg)
+     * - Resuelve expiresIn (props o default)
+     * - Construye payload con roles + customClaims
+     * - Establece claims estándar: sub, jti, iat, exp, iss, aud
+     * - Firma el token con:
+     *   - HS256: secret
+     *   - RS256/ES256: privateKey
+     *
+     * @param kind Tipo de token a generar.
+     * @param operation Nombre lógico de operación (para errores).
+     * @param props Props del core para generación de token.
+     * @returns JWT compacto firmado.
+     */
+    async generateToken(kind, operation, props) {
+        return this.withAuthError(operation, kind, async () => {
+            const eff = (0, internal_1.getEffectiveConfig)(this.options, kind);
+            // expiresIn puede venir en props o en defaultExpiresIn de options.
+            const expiresIn = (0, internal_1.resolveExpiresIn)(props.expiresIn, this.options[kind].defaultExpiresIn, operation);
+            const { alg, secret, privateKey } = await this.getNormalizedKeys(kind);
+            // roles y customClaims se guardan en el payload (cuerpo) del token.
+            const roles = props.user.roles ?? [];
+            const customClaims = props.customClaims ?? {};
+            // SignJWT crea un JWT y lo firma.
+            const jwt = new jose_1.SignJWT({ roles, customClaims })
+                .setProtectedHeader({ alg }) // cabecera: define algoritmo
+                .setSubject(props.user.id) // claim sub
+                .setJti((0, internal_1.createJti)()) // claim jti (id único)
+                .setIssuedAt() // claim iat (ahora)
+                .setExpirationTime(expiresIn); // claim exp basado en expiresIn
+            // iss/aud solo se establecen si están configurados.
+            if (eff.issuer)
+                jwt.setIssuer(eff.issuer);
+            if (eff.audience)
+                jwt.setAudience(eff.audience);
+            // Firma según algoritmo.
+            return alg === "HS256" ? jwt.sign(secret) : jwt.sign(privateKey);
+        });
+    }
+    /**
+     * Verifica un token JWT (access o refresh) y normaliza el payload al tipo del core.
+     *
+     * Qué valida `jwtVerify`:
+     * - Firma correcta según key + algoritmo
+     * - exp/nbf/iat (según reglas estándar)
+     * - issuer/audience si se configuran
+     * - clockTolerance para tolerar pequeños desajustes de reloj
+     *
+     * @param kind Tipo de token esperado (access/refresh).
+     * @param operation Operación lógica (para contexto de error).
+     * @param token JWT compacto (string).
+     * @returns Payload normalizado (IJWTPayload).
+     */
+    async verifyToken(kind, operation, token) {
+        return this.withAuthError(operation, kind, async () => {
+            const eff = (0, internal_1.getEffectiveConfig)(this.options, kind);
+            const { alg, secret, publicKey } = await this.getNormalizedKeys(kind);
+            // Key según algoritmo:
+            // - HS256 usa secret
+            // - RS256/ES256 usan publicKey
+            const key = alg === "HS256" ? secret : publicKey;
+            const result = await (0, jose_1.jwtVerify)(token, key, {
+                issuer: eff.issuer,
+                audience: eff.audience,
+                clockTolerance: eff.clockSkewSeconds,
+            });
+            // Normalización: asegura claims mínimos y tipos esperados por el core.
+            return (0, internal_1.normalizeJwtPayload)(result.payload, eff.issuer, eff.audience);
+        });
+    }
+}
+exports.JoseTokenService = JoseTokenService;

package/dist/infrastructure/services/types/create-auth-error-fn.type.d.ts

@@ -0,0 +1,27 @@
+import { mapJoseErrorToAuthError } from "src/infrastructure/mappers";
+/**
+ * Función que crea errores del dominio (core) a partir de datos técnicos.
+ *
+ * Esto permite que el plugin NO exponga errores propios, y siempre entregue
+ * errores consistentes definidos por el core (@jmlq/auth).
+ *
+ * @template TAuthError Tipo concreto de Error del core.
+ */
+export type CreateAuthErrorFn<TAuthError extends Error> = (args: {
+    /**
+     * Código de error del core. Se obtiene mapeando el error original de jose.
+     */
+    code: ReturnType<typeof mapJoseErrorToAuthError>["code"];
+    /**
+     * Mensaje humano y útil para debugging / logging.
+     */
+    message: string;
+    /**
+     * Error original (de jose u otro). Se conserva para trazabilidad.
+     */
+    cause?: unknown;
+    /**
+     * Metadatos técnicos opcionales para depuración (issuer, audience, alg, etc.).
+     */
+    meta?: Record<string, unknown>;
+}) => TAuthError;

package/dist/infrastructure/services/types/create-auth-error-fn.type.js

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

package/dist/infrastructure/services/types/index.d.ts

@@ -0,0 +1 @@
+export * from "./create-auth-error-fn.type";

package/dist/infrastructure/services/types/index.js

@@ -0,0 +1,17 @@
+"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("./create-auth-error-fn.type"), exports);

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@jmlq/auth-plugin-jose",
+  "description": "Infrastructure plugin that integrates the jose library with @jmlq/auth, providing JWT token generation and verification following Clean Architecture principles.",
+  "version": "0.0.1-alpha.1",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "dev": "rimraf dist && mkdir dist && tsc -p tsconfig.json",
+    "build": "rimraf dist && mkdir dist && tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build",
+    "test": "jest --passWithNoTests",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "example:services": "tsx examples/index.example.ts services",
+    "example:service-helpers": "tsx examples/index.example.ts service-helpers",
+    "example:factories": "tsx examples/index.example.ts factories",
+    "example:factory-helpers": "tsx examples/index.example.ts factory-helpers",
+    "example:help": "tsx examples/index.example.ts help",
+    "example:all": "tsx examples/index.example.ts"
+  },
+  "keywords": [
+    "jwt",
+    "jose",
+    "authentication",
+    "clean-architecture",
+    "typescript"
+  ],
+  "author": "MLahuasi",
+  "license": "MIT",
+  "dependencies": {
+    "@jmlq/auth": "^0.0.1-alpha.2",
+    "jose": "^6.1.3",
+    "rimraf": "^6.1.2"
+  },
+  "devDependencies": {
+    "@swc/core": "^1.3.95",
+    "@swc/jest": "^0.2.29",
+    "@types/bcryptjs": "^2.4.5",
+    "@types/jest": "^29.5.8",
+    "@types/node": "^20.8.10",
+    "jest": "^29.7.0",
+    "tsx": "^4.1.4",
+    "typescript": "^5.2.2"
+  },
+  "files": [
+    "dist"
+  ]
+}