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

package/dist/infrastructure/services/internal/jose-context.util.js

@@ -0,0 +1,51 @@
+"use strict";
+// src/infrastructure/services/internal/jose-context.util.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.safeString = safeString;
+exports.getEffectiveConfig = getEffectiveConfig;
+exports.buildJoseCtx = buildJoseCtx;
+/**
+ * Devuelve string si el valor es un string no vacío.
+ *
+ * @param value Valor a convertir.
+ * @returns string o undefined.
+ */
+function safeString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+/**
+ * Calcula configuración efectiva por tipo de token (access/refresh).
+ *
+ * @param options Options del JoseTokenService.
+ * @param kind Tipo de token.
+ * @returns issuer/audience/clockSkewSeconds/alg normalizados.
+ */
+function getEffectiveConfig(options, kind) {
+    const issuer = safeString(options[kind].issuer ?? options.issuer);
+    const audience = safeString(options[kind].audience ?? options.audience);
+    const clockSkewRaw = options[kind].clockSkewSeconds ?? options.clockSkewSeconds;
+    const clockSkewSeconds = typeof clockSkewRaw === "number" &&
+        Number.isFinite(clockSkewRaw) &&
+        clockSkewRaw >= 0
+        ? clockSkewRaw
+        : undefined;
+    const alg = options[kind].keys.alg;
+    return { issuer, audience, clockSkewSeconds, alg };
+}
+/**
+ * Construye un contexto técnico para mapear errores de jose a errores del core.
+ *
+ * @param operation Operación (generate/verify/getExpiration).
+ * @param tokenKind Tipo de token (access/refresh/unknown).
+ * @param opts issuer/audience/alg ya calculados.
+ * @returns JoseErrorContext.
+ */
+function buildJoseCtx(operation, tokenKind, opts) {
+    return {
+        operation,
+        tokenKind,
+        issuer: opts.issuer,
+        audience: opts.audience,
+        alg: opts.alg,
+    };
+}

package/dist/infrastructure/services/internal/jose-error.util.d.ts

@@ -0,0 +1,16 @@
+import { mapJoseErrorToAuthError } from "../../mappers/jose-error.mapper";
+/**
+ * Determina si un error mapeado es "retryable" para intentar verificar
+ * con otro set de keys (ej: access -> refresh).
+ *
+ * @param code Código de error del core (resultado del mapper).
+ * @returns true si vale la pena reintentar.
+ */
+export declare function isRetryableMappedCode(code: ReturnType<typeof mapJoseErrorToAuthError>["code"]): boolean;
+/**
+ * Convierte segundos Unix a Date.
+ *
+ * @param expSeconds `exp` en segundos Unix.
+ * @returns Date correspondiente.
+ */
+export declare function toDateFromUnixSeconds(expSeconds: number): Date;

package/dist/infrastructure/services/internal/jose-error.util.js

@@ -0,0 +1,27 @@
+"use strict";
+// src/infrastructure/services/internal/jose-error.util.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isRetryableMappedCode = isRetryableMappedCode;
+exports.toDateFromUnixSeconds = toDateFromUnixSeconds;
+/**
+ * Determina si un error mapeado es "retryable" para intentar verificar
+ * con otro set de keys (ej: access -> refresh).
+ *
+ * @param code Código de error del core (resultado del mapper).
+ * @returns true si vale la pena reintentar.
+ */
+function isRetryableMappedCode(code) {
+    return (code === "SIGNATURE_INVALID" ||
+        code === "ALGORITHM_UNSUPPORTED" ||
+        code === "KEY_MISMATCH" ||
+        code === "KEY_NOT_FOUND");
+}
+/**
+ * Convierte segundos Unix a Date.
+ *
+ * @param expSeconds `exp` en segundos Unix.
+ * @returns Date correspondiente.
+ */
+function toDateFromUnixSeconds(expSeconds) {
+    return new Date(expSeconds * 1000);
+}

package/dist/infrastructure/services/internal/jose-keys.normalizer.d.ts

@@ -0,0 +1,25 @@
+import type { JoseKeyMaterial } from "../../../application/types";
+/**
+ * Keys normalizadas listas para firmar/verificar.
+ */
+export type NormalizedKeys = {
+    alg: JoseKeyMaterial["alg"];
+    privateKey?: any;
+    publicKey?: any;
+    secret?: Uint8Array;
+};
+/**
+ * Normaliza el material de claves para uso con `jose`.
+ *
+ * Reglas:
+ * - HS256: convierte secret string a Uint8Array (TextEncoder).
+ * - RS256/ES256:
+ *   - Soporta PEM string:
+ *     - privateKey: PKCS8
+ *     - publicKey: SPKI
+ *   - Soporta keys ya importadas (KeyLike)
+ *
+ * @param keys Configuración de claves del plugin.
+ * @returns Objeto NormalizedKeys.
+ */
+export declare function normalizeKeyMaterial(keys: JoseKeyMaterial): Promise<NormalizedKeys>;

package/dist/infrastructure/services/internal/jose-keys.normalizer.js

@@ -0,0 +1,35 @@
+"use strict";
+// src/infrastructure/services/internal/jose-keys.normalizer.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeKeyMaterial = normalizeKeyMaterial;
+const jose_1 = require("jose");
+/**
+ * Normaliza el material de claves para uso con `jose`.
+ *
+ * Reglas:
+ * - HS256: convierte secret string a Uint8Array (TextEncoder).
+ * - RS256/ES256:
+ *   - Soporta PEM string:
+ *     - privateKey: PKCS8
+ *     - publicKey: SPKI
+ *   - Soporta keys ya importadas (KeyLike)
+ *
+ * @param keys Configuración de claves del plugin.
+ * @returns Objeto NormalizedKeys.
+ */
+async function normalizeKeyMaterial(keys) {
+    if (keys.alg === "HS256") {
+        const secret = typeof keys.secret === "string"
+            ? new TextEncoder().encode(keys.secret)
+            : keys.secret;
+        return { alg: "HS256", secret };
+    }
+    const alg = keys.alg;
+    const privateKey = typeof keys.privateKey === "string"
+        ? await (0, jose_1.importPKCS8)(keys.privateKey, alg)
+        : keys.privateKey;
+    const publicKey = typeof keys.publicKey === "string"
+        ? await (0, jose_1.importSPKI)(keys.publicKey, alg)
+        : keys.publicKey;
+    return { alg, privateKey, publicKey };
+}

package/dist/infrastructure/services/internal/jti.util.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Genera un identificador único para el claim `jti`.
+ * - Preferencia: crypto.randomUUID (cuando está disponible).
+ * - Fallback: string con timestamp + random (no crypto-strong, útil en dev).
+ *
+ * @returns jti como string.
+ */
+export declare function createJti(): string;

package/dist/infrastructure/services/internal/jti.util.js

@@ -0,0 +1,25 @@
+"use strict";
+// src/infrastructure/services/internal/jti.util.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createJti = createJti;
+/**
+ * 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`.
+ * - Preferencia: crypto.randomUUID (cuando está disponible).
+ * - Fallback: string con timestamp + random (no crypto-strong, útil en dev).
+ *
+ * @returns jti como string.
+ */
+function createJti() {
+    const anyCrypto = globalThis.crypto;
+    if (anyCrypto?.randomUUID)
+        return anyCrypto.randomUUID();
+    return `jti_${nowUnixSeconds()}_${Math.random().toString(16).slice(2)}`;
+}

package/dist/infrastructure/services/internal/jwt-expiration-reader.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Intenta leer `exp` sin verificar firma (solo decode).
+ * Se usa como fallback cuando el token está expirado y el verify falla,
+ * pero aún queremos devolver la fecha de expiración.
+ *
+ * @param token JWT compact (string "header.payload.signature").
+ * @returns exp (segundos Unix) o null si no existe / no se puede leer.
+ */
+export declare function tryReadExpByDecode(token: string): number | null;

package/dist/infrastructure/services/internal/jwt-expiration-reader.js

@@ -0,0 +1,23 @@
+"use strict";
+// src/infrastructure/services/internal/jwt-expiration-reader.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tryReadExpByDecode = tryReadExpByDecode;
+const jose_1 = require("jose");
+/**
+ * Intenta leer `exp` sin verificar firma (solo decode).
+ * Se usa como fallback cuando el token está expirado y el verify falla,
+ * pero aún queremos devolver la fecha de expiración.
+ *
+ * @param token JWT compact (string "header.payload.signature").
+ * @returns exp (segundos Unix) o null si no existe / no se puede leer.
+ */
+function tryReadExpByDecode(token) {
+    try {
+        const decoded = (0, jose_1.decodeJwt)(token);
+        const exp = decoded?.exp;
+        return typeof exp === "number" ? exp : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/infrastructure/services/internal/jwt-payload.normalizer.d.ts

@@ -0,0 +1,11 @@
+import type { IJWTPayload } from "@jmlq/auth";
+/**
+ * Normaliza el payload verificado por `jose` a `IJWTPayload` del core.
+ * Esta función asegura presencia y tipos de claims mínimos para tu plataforma.
+ *
+ * @param payload Payload retornado por jose (Record).
+ * @param issuer Issuer efectivo (si el claim iss no está presente).
+ * @param audience Audience efectivo (si el claim aud no está presente).
+ * @returns IJWTPayload listo para consumo por el core/aplicación.
+ */
+export declare function normalizeJwtPayload(payload: Record<string, any>, issuer?: string, audience?: string): IJWTPayload;

package/dist/infrastructure/services/internal/jwt-payload.normalizer.js

@@ -0,0 +1,56 @@
+"use strict";
+// src/infrastructure/services/internal/jwt-payload.normalizer.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeJwtPayload = normalizeJwtPayload;
+const jose_context_util_1 = require("./jose-context.util");
+/**
+ * Valida que el claim roles sea un arreglo de objetos { role: string }.
+ *
+ * @param value Claim roles.
+ * @returns true si cumple el formato.
+ */
+function isRoleArray(value) {
+    return (Array.isArray(value) &&
+        value.every((x) => x && typeof x === "object" && typeof x.role === "string"));
+}
+/**
+ * Valida que el claim sea un objeto plano (no null, no array).
+ *
+ * @param value Valor a validar.
+ * @returns true si es objeto plano.
+ */
+function isPlainObject(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * Normaliza el payload verificado por `jose` a `IJWTPayload` del core.
+ * Esta función asegura presencia y tipos de claims mínimos para tu plataforma.
+ *
+ * @param payload Payload retornado por jose (Record).
+ * @param issuer Issuer efectivo (si el claim iss no está presente).
+ * @param audience Audience efectivo (si el claim aud no está presente).
+ * @returns IJWTPayload listo para consumo por el core/aplicación.
+ */
+function normalizeJwtPayload(payload, issuer, audience) {
+    const sub = (0, jose_context_util_1.safeString)(payload.sub);
+    const jti = (0, jose_context_util_1.safeString)(payload.jti);
+    const roles = payload.roles;
+    const customClaims = payload.customClaims;
+    const iat = payload.iat;
+    const exp = payload.exp;
+    const iss = (0, jose_context_util_1.safeString)(payload.iss) ?? issuer;
+    const aud = (0, jose_context_util_1.safeString)(payload.aud) ?? audience;
+    if (!sub || !jti) {
+        throw new Error("[JoseTokenService] Missing required claims: sub/jti");
+    }
+    if (!isRoleArray(roles)) {
+        throw new Error("[JoseTokenService] Invalid roles claim");
+    }
+    if (!isPlainObject(customClaims)) {
+        throw new Error("[JoseTokenService] Invalid customClaims claim");
+    }
+    if (typeof iat !== "number" || typeof exp !== "number") {
+        throw new Error("[JoseTokenService] Missing required numeric claims: iat/exp");
+    }
+    return { sub, roles, customClaims, jti, iss, aud, iat, exp };
+}

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

@@ -0,0 +1,192 @@
+import type { ITokenServicePort, IJWTPayload, IGenerateAccessTokenProps, IGenerateRefreshTokenProps } from "@jmlq/auth";
+import type { JoseTokenServiceOptions } from "../../application/types";
+import { CreateAuthErrorFn } from "./types";
+/**
+ * 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.
+ */
+export declare class JoseTokenService<TAuthError extends Error> implements ITokenServicePort {
+    /**
+     * Configuración técnica del plugin:
+     * - keys por tipo de token (access/refresh)
+     * - issuer/audience
+     * - clockSkew
+     * - defaultExpiresIn
+     */
+    private readonly options;
+    /**
+     * Factory de error del core. El plugin no crea errores propios.
+     */
+    private readonly createAuthError;
+    /**
+     * Cache (lazy) de keys normalizadas para access.
+     * Se resuelve una sola vez y se reutiliza.
+     */
+    private accessKeysPromise?;
+    /**
+     * Cache (lazy) de keys normalizadas para refresh.
+     * Se resuelve una sola vez y se reutiliza.
+     */
+    private refreshKeysPromise?;
+    /**
+     * Crea el servicio.
+     *
+     * @param options Configuración del plugin (keys/issuer/audience/clockSkew).
+     * @param createAuthError Función para construir errores del core.
+     */
+    constructor(options: JoseTokenServiceOptions, createAuthError: CreateAuthErrorFn<TAuthError>);
+    /**
+     * 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")
+     */
+    generateAccessToken(props: IGenerateAccessTokenProps): Promise<string>;
+    /**
+     * 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")
+     */
+    generateRefreshToken(props: IGenerateRefreshTokenProps): Promise<string>;
+    /**
+     * 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.
+     */
+    verifyAccessToken(token: string): Promise<IJWTPayload>;
+    /**
+     * Verifica un Refresh Token.
+     *
+     * @param token JWT compacto (string).
+     * @returns Payload normalizado al tipo `IJWTPayload` del core.
+     */
+    verifyRefreshToken(token: string): Promise<IJWTPayload>;
+    /**
+     * 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.
+     */
+    getTokenExpiration(token: string): Promise<Date>;
+    /**
+     * 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.
+     */
+    private ctx;
+    /**
+     * 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.
+     */
+    private withAuthError;
+    /**
+     * 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.
+     */
+    private getNormalizedKeys;
+    /**
+     * 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.
+     */
+    private generateToken;
+    /**
+     * 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).
+     */
+    private verifyToken;
+}