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

package/dist/application/types/jose-token-service.options.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Opciones públicas del adapter jose que implementa ITokenServicePort.
+ *
+ * Objetivos:
+ * - Config explícita (sin magia).
+ * - Permitir configuración común + overrides por tipo (access/refresh).
+ * - Tipar keys según algoritmo (HS vs RSA/EC).
+ *
+ * NOTA: la validación de estas options se hace en la factory (Etapa 5),
+ * aquí solo se definen tipos.
+ */
+export type JoseJwtAlg = "HS256" | "RS256" | "ES256";
+/**
+ * Para HS256 se usa un secreto simétrico.
+ */
+export interface JoseHmacKeyMaterial {
+    alg: "HS256";
+    secret: string | Uint8Array;
+}
+/**
+ * Para RS256 / ES256 se usa par de claves asimétricas.
+ * Se acepta string PEM/JWK serializado o cualquier representación ya resuelta por la app.
+ *
+ * Nota: el tipo exacto de KeyLike/JWK depende de jose. Para mantener
+ * desacoplado el dominio del plugin, aquí se usa `unknown` como "KeyInput".
+ * La factory/adapters se encargan de normalizar.
+ */
+export interface JoseAsymmetricKeyMaterial {
+    alg: "RS256" | "ES256";
+    privateKey: unknown;
+    publicKey: unknown;
+}
+export type JoseKeyMaterial = JoseHmacKeyMaterial | JoseAsymmetricKeyMaterial;
+export interface JoseStandardClaimsValidationOptions {
+    /**
+     * Si se define, se exige coincidencia exacta con el claim `iss`.
+     * Si no se define, no se valida issuer.
+     */
+    issuer?: string;
+    /**
+     * Si se define, se exige coincidencia exacta con el claim `aud`.
+     * Si no se define, no se valida audience.
+     */
+    audience?: string;
+    /**
+     * Tolerancia de reloj en segundos para validación temporal (exp/nbf/iat según aplique).
+     * Default recomendado en factory: 0 o 5.
+     */
+    clockSkewSeconds?: number;
+}
+export interface JoseTokenTypeOptions extends JoseStandardClaimsValidationOptions {
+    /**
+     * Algoritmo + material de clave.
+     */
+    keys: JoseKeyMaterial;
+    /**
+     * ExpiresIn por defecto si en props.expiresIn no se envía.
+     * Formato: string estilo "15m", "7d", "3600s".
+     * La interpretación exacta se define en el parser del plugin (Etapa 2/4).
+     */
+    defaultExpiresIn?: string;
+}
+export interface JoseTokenServiceOptions extends JoseStandardClaimsValidationOptions {
+    /**
+     * Configuración específica para access tokens.
+     */
+    access: JoseTokenTypeOptions;
+    /**
+     * Configuración específica para refresh tokens.
+     */
+    refresh: JoseTokenTypeOptions;
+    /**
+     * Política para getTokenExpiration:
+     * - "verify-first": verifica firma antes de leer exp (Opción A).
+     *
+     * Este proyecto acordó Opción A.
+     */
+    getExpirationPolicy?: "verify-first";
+}
+export declare const DEFAULT_CLOCK_SKEW_SECONDS: 0;
+export declare const DEFAULT_GET_EXPIRATION_POLICY: "verify-first";

package/dist/application/types/jose-token-service.options.js

@@ -0,0 +1,9 @@
+"use strict";
+// src/application/types/jose-token-service.options.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_GET_EXPIRATION_POLICY = exports.DEFAULT_CLOCK_SKEW_SECONDS = void 0;
+// -----------------------------------------------------------------------------
+// Defaults recomendados (constantes de referencia; la factory aplica defaults)
+// -----------------------------------------------------------------------------
+exports.DEFAULT_CLOCK_SKEW_SECONDS = 0;
+exports.DEFAULT_GET_EXPIRATION_POLICY = "verify-first";

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createJoseTokenService } from "./application/factories";
+export type { JoseJwtAlg, JoseKeyMaterial, JoseHmacKeyMaterial, JoseAsymmetricKeyMaterial, JoseStandardClaimsValidationOptions, JoseTokenTypeOptions, JoseTokenServiceOptions, } from "./application/types";
+export type { ExpiresInUnit, ExpiresInString, ExpiresIn, } from "./application/types";

package/dist/index.js

@@ -0,0 +1,9 @@
+"use strict";
+// src/index.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createJoseTokenService = void 0;
+// -----------------------------------------------------------------------------
+// Public factory
+// -----------------------------------------------------------------------------
+var factories_1 = require("./application/factories");
+Object.defineProperty(exports, "createJoseTokenService", { enumerable: true, get: function () { return factories_1.createJoseTokenService; } });

package/dist/infrastructure/mappers/index.d.ts

@@ -0,0 +1 @@
+export * from "./jose-error.mapper";

package/dist/infrastructure/mappers/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("./jose-error.mapper"), exports);

package/dist/infrastructure/mappers/jose-error.mapper.d.ts

@@ -0,0 +1,35 @@
+import { JoseErrorContext, MappedAuthError } from "./types";
+/**
+ * Mapea un error técnico a un código estable del core.
+ *
+ * La estrategia es conservadora:
+ * - Primero intenta mapear por `err.name` (más estable en `jose`).
+ * - Luego usa heurísticas por `message` como fallback.
+ * - Finalmente devuelve JWT_ERROR (catch-all) si no calza con nada.
+ *
+ * @param err Error original (normalmente de `jose`, pero puede ser cualquiera).
+ * @param ctx Contexto técnico mínimo para enriquecer meta y mejorar clasificación.
+ * @returns MappedAuthError con código del core + meta segura + causa opcional.
+ */
+export declare function mapJoseErrorToAuthError(err: unknown, ctx: JoseErrorContext): MappedAuthError;
+/**
+ * Convierte un error técnico a un Error del core (AuthDomainError u otro),
+ * sin acoplar el plugin a una implementación concreta.
+ *
+ * Esta función es útil porque:
+ * - El mapper produce un objeto “agnóstico” (MappedAuthError).
+ * - La creación del Error real depende del core o de la app (inyección).
+ *
+ * @template TAuthError Tipo de error final que devuelve el core.
+ *
+ * @param createAuthError Función provista por el core/app para crear el error final.
+ * @param err Error original que proviene de `jose` u otra fuente.
+ * @param ctx Contexto técnico (operación, tokenKind, issuer, audience, alg).
+ * @returns Error del core ya construido con code/message/meta/cause.
+ */
+export declare function toAuthDomainError<TAuthError extends Error>(createAuthError: (args: {
+    code: MappedAuthError["code"];
+    message: string;
+    cause?: unknown;
+    meta?: Record<string, unknown>;
+}) => TAuthError, err: unknown, ctx: JoseErrorContext): TAuthError;

package/dist/infrastructure/mappers/jose-error.mapper.js

@@ -0,0 +1,219 @@
+"use strict";
+// src/infrastructure/mappers/jose-error.mapper.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapJoseErrorToAuthError = mapJoseErrorToAuthError;
+exports.toAuthDomainError = toAuthDomainError;
+/**
+ * Mapper de errores de `jose` → error “entendible” por el core (@jmlq/auth).
+ *
+ * Características clave:
+ * - NO lanza errores: solo traduce un error recibido a un código estable del core.
+ * - NO expone datos sensibles (no incluye token ni material de claves).
+ * - Incluye `meta` mínima para troubleshooting (issuer/audience/alg/operación).
+ *
+ * Objetivo:
+ * Evitar acoplamiento de la aplicación al detalle de `jose`.
+ */
+/**
+ * Extrae el "name" del error de forma segura.
+ * En `jose` el `name` suele identificar clases como JWTExpired, JWTInvalid, etc.
+ *
+ * @param err Error desconocido (puede ser cualquier cosa: Error, string, etc.).
+ * @returns Nombre del error o "UnknownError" si no se puede leer.
+ */
+function getErrorName(err) {
+    if (err &&
+        typeof err === "object" &&
+        "name" in err &&
+        typeof err.name === "string") {
+        return err.name;
+    }
+    return "UnknownError";
+}
+/**
+ * Extrae el "message" del error de forma segura.
+ *
+ * @param err Error desconocido.
+ * @returns Mensaje del error o un mensaje genérico si no existe.
+ */
+function getErrorMessage(err) {
+    if (err &&
+        typeof err === "object" &&
+        "message" in err &&
+        typeof err.message === "string") {
+        return err.message;
+    }
+    return "Unexpected token error";
+}
+/**
+ * Construye metadatos mínimos para debugging.
+ * Importante: no se incluyen tokens ni claves.
+ *
+ * @param joseErrorName Nombre del error (según `err.name`).
+ * @param ctx Contexto técnico (operación, tipo de token, issuer, audience, alg).
+ * @returns Meta segura para logging / troubleshooting.
+ */
+function buildSafeMeta(joseErrorName, ctx) {
+    return {
+        joseErrorName,
+        operation: ctx.operation,
+        tokenKind: ctx.tokenKind ?? "unknown",
+        issuer: ctx.issuer,
+        audience: ctx.audience,
+        alg: ctx.alg,
+    };
+}
+/**
+ * Mapea un error técnico a un código estable del core.
+ *
+ * La estrategia es conservadora:
+ * - Primero intenta mapear por `err.name` (más estable en `jose`).
+ * - Luego usa heurísticas por `message` como fallback.
+ * - Finalmente devuelve JWT_ERROR (catch-all) si no calza con nada.
+ *
+ * @param err Error original (normalmente de `jose`, pero puede ser cualquiera).
+ * @param ctx Contexto técnico mínimo para enriquecer meta y mejorar clasificación.
+ * @returns MappedAuthError con código del core + meta segura + causa opcional.
+ */
+function mapJoseErrorToAuthError(err, ctx) {
+    const name = getErrorName(err);
+    const msg = getErrorMessage(err);
+    const meta = buildSafeMeta(name, ctx);
+    // ---------------------------------------------------------------------------
+    // Mapeos preferentes por "name" (casos típicos en verificación JWT)
+    // ---------------------------------------------------------------------------
+    // Token expirado: exp < now
+    if (name === "JWTExpired") {
+        return {
+            code: "TOKEN_EXPIRED",
+            message: "Token has expired",
+            meta: { ...meta },
+            cause: err,
+        };
+    }
+    // Token aún no válido: nbf (not before) en el futuro o validación temporal similar
+    if (name === "JWTNotBefore" || name === "JWTNotYetValid") {
+        return {
+            code: "TOKEN_NOT_YET_VALID",
+            message: "Token is not yet valid",
+            meta: { ...meta },
+            cause: err,
+        };
+    }
+    // Firma inválida / verificación de firma fallida
+    // Nota: algunos nombres pueden variar según versión/caso, por eso agrupamos.
+    if (name === "JWSSignatureVerificationFailed" ||
+        name === "JWSInvalid" ||
+        name === "JWSError") {
+        return {
+            code: "SIGNATURE_INVALID",
+            message: "Token signature is invalid",
+            meta: { ...meta },
+            cause: err,
+        };
+    }
+    // Claims inválidos (issuer/audience/subject/etc.)
+    if (name === "JWTClaimValidationFailed") {
+        return {
+            code: "CLAIMS_VALIDATION_ERROR",
+            message: "Token claims validation failed",
+            meta: { ...meta },
+            cause: err,
+        };
+    }
+    // Token inválido (estructura o contenido no aceptado)
+    if (name === "JWTInvalid") {
+        return {
+            code: "TOKEN_INVALID",
+            message: "Token is invalid",
+            meta: { ...meta },
+            cause: err,
+        };
+    }
+    // Token malformado (no cumple formato compacto "header.payload.signature", etc.)
+    if (name === "JWTMalformed" ||
+        name === "JWSMalformed" ||
+        name === "JOSEError") {
+        return {
+            code: "TOKEN_MALFORMED",
+            message: "Token is malformed",
+            meta: { ...meta },
+            cause: err,
+        };
+    }
+    // Algoritmo no soportado o no permitido
+    if (name === "JOSENotSupported" || name === "JWTAlgorithmNotAllowed") {
+        return {
+            code: "ALGORITHM_UNSUPPORTED",
+            message: "Token algorithm is not supported",
+            meta: { ...meta },
+            cause: err,
+        };
+    }
+    // Material de clave inválido o incompatible con algoritmo
+    if (name === "JWKInvalid" || name === "JWKInvalidFormat") {
+        return {
+            code: "KEY_MISMATCH",
+            message: "Key material is invalid or does not match the algorithm",
+            meta: { ...meta },
+            cause: err,
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // Fallbacks por mensaje (heurísticas conservadoras)
+    // ---------------------------------------------------------------------------
+    const lower = msg.toLowerCase();
+    // Clave ausente / no encontrada
+    if (lower.includes("key") &&
+        (lower.includes("not found") || lower.includes("missing"))) {
+        return {
+            code: "KEY_NOT_FOUND",
+            message: "Key not found for token verification",
+            meta: { ...meta },
+            cause: err,
+        };
+    }
+    // Clave inválida o mismatch
+    if (lower.includes("key") &&
+        (lower.includes("mismatch") || lower.includes("invalid"))) {
+        return {
+            code: "KEY_MISMATCH",
+            message: "Key does not match token requirements",
+            meta: { ...meta },
+            cause: err,
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // Catch-all
+    // ---------------------------------------------------------------------------
+    return {
+        code: "JWT_ERROR",
+        message: "JWT operation failed",
+        meta: { ...meta },
+        cause: err,
+    };
+}
+/**
+ * Convierte un error técnico a un Error del core (AuthDomainError u otro),
+ * sin acoplar el plugin a una implementación concreta.
+ *
+ * Esta función es útil porque:
+ * - El mapper produce un objeto “agnóstico” (MappedAuthError).
+ * - La creación del Error real depende del core o de la app (inyección).
+ *
+ * @template TAuthError Tipo de error final que devuelve el core.
+ *
+ * @param createAuthError Función provista por el core/app para crear el error final.
+ * @param err Error original que proviene de `jose` u otra fuente.
+ * @param ctx Contexto técnico (operación, tokenKind, issuer, audience, alg).
+ * @returns Error del core ya construido con code/message/meta/cause.
+ */
+function toAuthDomainError(createAuthError, err, ctx) {
+    const mapped = mapJoseErrorToAuthError(err, ctx);
+    return createAuthError({
+        code: mapped.code,
+        message: mapped.message,
+        cause: mapped.cause,
+        meta: mapped.meta,
+    });
+}

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

@@ -0,0 +1,4 @@
+export * from "./jose-error-context.type";
+export * from "./mapped-auth-error.type";
+export * from "./token-kind.type";
+export * from "./token-operation.type";

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

@@ -0,0 +1,20 @@
+"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("./jose-error-context.type"), exports);
+__exportStar(require("./mapped-auth-error.type"), exports);
+__exportStar(require("./token-kind.type"), exports);
+__exportStar(require("./token-operation.type"), exports);

package/dist/infrastructure/mappers/types/jose-error-context.type.d.ts

@@ -0,0 +1,32 @@
+import { TokenKind, TokenOperation } from ".";
+/**
+ * Contexto técnico mínimo para mapear errores de `jose` a errores del core.
+ *
+ * Importante:
+ * - NO incluir tokens ni claves aquí (evitar datos sensibles).
+ * - Solo información útil para debugging y clasificación.
+ */
+export interface JoseErrorContext {
+    /**
+     * Operación que estaba ejecutándose cuando falló.
+     */
+    operation: TokenOperation;
+    /**
+     * Tipo de token esperado.
+     * Si no se conoce, usar "unknown".
+     */
+    tokenKind?: TokenKind;
+    /**
+     * Issuer esperado/configurado (si aplica).
+     * Sirve para entender fallos de validación de claims.
+     */
+    issuer?: string;
+    /**
+     * Audience esperada/configurada (si aplica).
+     */
+    audience?: string;
+    /**
+     * Algoritmo configurado/esperado (HS256/RS256/ES256...).
+     */
+    alg?: string;
+}

package/dist/infrastructure/mappers/types/jose-error-context.type.js

@@ -0,0 +1,3 @@
+"use strict";
+// src/infrastructure/mappers/types/jose-error-context.type.ts
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/infrastructure/mappers/types/mapped-auth-error.type.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Resultado agnóstico del mapper.
+ * Representa “la forma” del error que entiende el core (por código),
+ * pero sin acoplarse a una clase concreta de error.
+ */
+export interface MappedAuthError {
+    /**
+     * Código de error compatible con el core (@jmlq/auth).
+     */
+    code: "TOKEN_EXPIRED" | "TOKEN_NOT_YET_VALID" | "SIGNATURE_INVALID" | "TOKEN_MALFORMED" | "TOKEN_INVALID" | "CLAIMS_VALIDATION_ERROR" | "ALGORITHM_UNSUPPORTED" | "KEY_NOT_FOUND" | "KEY_MISMATCH" | "JWT_ERROR" | "AUTHENTICATION_FAILED";
+    /**
+     * Mensaje técnico simple (orientado a debugging).
+     * No debe incluir datos sensibles.
+     */
+    message: string;
+    /**
+     * Metadatos para troubleshooting (sin secretos).
+     */
+    meta: Record<string, unknown>;
+    /**
+     * Error original como causa, si se desea conservar.
+     */
+    cause?: unknown;
+}

package/dist/infrastructure/mappers/types/mapped-auth-error.type.js

@@ -0,0 +1,3 @@
+"use strict";
+// src/infrastructure/mappers/types/mapped-auth-error.type.ts
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/infrastructure/mappers/types/token-kind.type.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Tipo de token esperado por el core.
+ * - access: token de acceso (corto, para autorización).
+ * - refresh: token de renovación (largo, para renovar access).
+ * - unknown: se usa cuando el contexto no sabe qué tipo es (ej: lectura de exp).
+ */
+export type TokenKind = "access" | "refresh" | "unknown";

package/dist/infrastructure/mappers/types/token-kind.type.js

@@ -0,0 +1,3 @@
+"use strict";
+// src/infrastructure/mappers/types/token-kind.type.ts
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/infrastructure/mappers/types/token-operation.type.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Operaciones públicas soportadas por el servicio de tokens.
+ * Se usa principalmente para:
+ * - enriquecer meta de errores
+ * - mejorar trazabilidad
+ */
+export type TokenOperation = "generateAccessToken" | "generateRefreshToken" | "verifyAccessToken" | "verifyRefreshToken" | "getTokenExpiration";

package/dist/infrastructure/mappers/types/token-operation.type.js

@@ -0,0 +1,3 @@
+"use strict";
+// src/infrastructure/mappers/types/token-operation.type.ts
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1 @@
+export * from "./jose-token.service";

package/dist/infrastructure/services/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("./jose-token.service"), exports);

package/dist/infrastructure/services/internal/expires-in.util.d.ts

@@ -0,0 +1,21 @@
+import { TokenOperation } from "../../../infrastructure/mappers/types";
+import type { ExpiresInString } from "../../../application/types";
+/**
+ * Verifica si un valor cumple el formato de expiración humana.
+ * Formatos válidos: "15m", "7d", "3600s", "12h".
+ *
+ * @param value Valor a validar.
+ * @returns true si cumple el formato ExpiresInString.
+ */
+export declare function isExpiresInString(value: unknown): value is ExpiresInString;
+/**
+ * Resuelve el expiresIn efectivo para una operación.
+ * - Si `provided` no existe, usa `fallback`.
+ * - Si ninguno es válido, lanza error técnico (será mapeado por el wrapper).
+ *
+ * @param provided Expiración enviada en el props (puede ser undefined).
+ * @param fallback Expiración por defecto desde options.
+ * @param op Operación (para mensajes de error claros).
+ * @returns ExpiresInString válido.
+ */
+export declare function resolveExpiresIn(provided: unknown, fallback: unknown, op: TokenOperation): ExpiresInString;

package/dist/infrastructure/services/internal/expires-in.util.js

@@ -0,0 +1,35 @@
+"use strict";
+// src/infrastructure/services/internal/expires-in.util.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isExpiresInString = isExpiresInString;
+exports.resolveExpiresIn = resolveExpiresIn;
+/**
+ * Verifica si un valor cumple el formato de expiración humana.
+ * Formatos válidos: "15m", "7d", "3600s", "12h".
+ *
+ * @param value Valor a validar.
+ * @returns true si cumple el formato ExpiresInString.
+ */
+function isExpiresInString(value) {
+    return typeof value === "string" && /^[0-9]+[smhd]$/.test(value);
+}
+/**
+ * Resuelve el expiresIn efectivo para una operación.
+ * - Si `provided` no existe, usa `fallback`.
+ * - Si ninguno es válido, lanza error técnico (será mapeado por el wrapper).
+ *
+ * @param provided Expiración enviada en el props (puede ser undefined).
+ * @param fallback Expiración por defecto desde options.
+ * @param op Operación (para mensajes de error claros).
+ * @returns ExpiresInString válido.
+ */
+function resolveExpiresIn(provided, fallback, op) {
+    if (provided === undefined || provided === null) {
+        if (isExpiresInString(fallback))
+            return fallback;
+        throw new Error(`[JoseTokenService] Missing expiresIn for ${op}. Provide props.expiresIn or defaultExpiresIn.`);
+    }
+    if (isExpiresInString(provided))
+        return provided;
+    throw new Error(`[JoseTokenService] Invalid expiresIn for ${op}. Expected format like "15m", "7d", "3600s".`);
+}

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

@@ -0,0 +1,7 @@
+export * from "./expires-in.util";
+export * from "./jose-context.util";
+export * from "./jose-error.util";
+export * from "./jose-keys.normalizer";
+export * from "./jti.util";
+export * from "./jwt-expiration-reader";
+export * from "./jwt-payload.normalizer";

package/dist/infrastructure/services/internal/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("./expires-in.util"), exports);
+__exportStar(require("./jose-context.util"), exports);
+__exportStar(require("./jose-error.util"), exports);
+__exportStar(require("./jose-keys.normalizer"), exports);
+__exportStar(require("./jti.util"), exports);
+__exportStar(require("./jwt-expiration-reader"), exports);
+__exportStar(require("./jwt-payload.normalizer"), exports);

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

@@ -0,0 +1,35 @@
+import type { JoseTokenServiceOptions } from "../../../application/types";
+import type { JoseErrorContext, TokenKind, TokenOperation } from "../../mappers/types";
+/**
+ * Devuelve string si el valor es un string no vacío.
+ *
+ * @param value Valor a convertir.
+ * @returns string o undefined.
+ */
+export declare function safeString(value: unknown): string | 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.
+ */
+export declare function getEffectiveConfig(options: JoseTokenServiceOptions, kind: "access" | "refresh"): {
+    issuer: string | undefined;
+    audience: string | undefined;
+    clockSkewSeconds: number | undefined;
+    alg: "HS256" | "RS256" | "ES256";
+};
+/**
+ * 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.
+ */
+export declare function buildJoseCtx(operation: TokenOperation, tokenKind: TokenKind, opts: {
+    issuer?: string;
+    audience?: string;
+    alg?: string;
+}): JoseErrorContext;