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

package/README.es.md

@@ -0,0 +1,197 @@
+# @jmlq/auth-plugin-jose 🧩
+
+## 🎯 Objetivo
+
+`@jmlq/auth-plugin-jose` es el plugin de infraestructura que implementa `ITokenServicePort` de `@jmlq/auth` usando la librería `jose`.
+
+Su responsabilidad real es:
+
+- generar access tokens y refresh tokens,
+- verificar tokens firmados,
+- normalizar configuración criptográfica,
+- traducir errores técnicos de `jose` a errores compatibles con el core.
+
+El punto de entrada recomendado es `createJoseTokenService(...)`.
+
+## ⭐ Importancia
+
+Este plugin permite que el core `@jmlq/auth` siga siendo independiente de la tecnología JWT concreta.
+
+En la práctica:
+
+- el core depende de `ITokenServicePort`,
+- este plugin implementa ese contrato,
+- el host decide si usa `HS256`, `RS256` o `ES256`,
+- la lógica de negocio permanece en `@jmlq/auth`.
+
+## 🏗️ Arquitectura (visión rápida)
+
+- `createJoseTokenService(...)` valida precondiciones mínimas y construye `JoseTokenService`.
+- `JoseTokenService` encapsula `SignJWT`, `jwtVerify`, `decodeJwt`, `importPKCS8` e `importSPKI`.
+- `jose-error.mapper.ts` traduce errores técnicos a códigos del core.
+- `audience` se usa **solo para emisión**; en verificación no se pasa a `jwtVerify`.
+
+➡️ Ver detalle en: [architecture.md](./docs/es/architecture.md)
+
+## 🔧 Implementación
+
+### 5.1 Instalación
+
+```bash
+npm i @jmlq/auth @jmlq/auth-plugin-jose jose
+```
+
+### 5.2 Dependencias
+
+Dependencias directas del paquete:
+
+- `@jmlq/auth`
+- `jose`
+
+### 5.3 Quickstart (implementación rápida)
+
+Uso real recomendado desde infrastructure:
+
+```ts
+import { createJoseTokenService } from "@jmlq/auth-plugin-jose";
+
+const tokenService = createJoseTokenService(
+  {
+    keyMaterial: {
+      alg: "RS256",
+      privateKey: process.env.JWT_PRIVATE_KEY!,
+      publicKey: process.env.JWT_PUBLIC_KEY!,
+    },
+    issuer: process.env.JWT_ISSUER,
+    audience: process.env.JWT_AUDIENCE,
+    clockSkewSeconds: Number(process.env.JWT_CLOCK_SKEW_SECONDS ?? 5),
+    defaultExpiresIn: {
+      accessToken: "15m",
+      refreshToken: "7d",
+    },
+  },
+  {
+    createAuthError,
+  },
+);
+```
+
+También es válido con `HS256`:
+
+```ts
+const tokenService = createJoseTokenService(
+  {
+    keyMaterial: {
+      alg: "HS256",
+      secret: process.env.JWT_SECRET!,
+    },
+    issuer: process.env.JWT_ISSUER,
+    audience: process.env.JWT_AUDIENCE,
+    defaultExpiresIn: {
+      accessToken: "15m",
+      refreshToken: "7d",
+    },
+  },
+  { createAuthError },
+);
+```
+
+### 5.4 Variables de entorno (.env) 📦
+
+El plugin **no lee `.env` directamente**.  
+El host resuelve variables y construye `JoseTokenServiceOptions`.
+
+Variables típicas y coherentes con esta integración:
+
+```ts
+process.env.JWT_SECRET;
+process.env.JWT_PRIVATE_KEY;
+process.env.JWT_PUBLIC_KEY;
+process.env.JWT_ISSUER;
+process.env.JWT_AUDIENCE;
+process.env.JWT_CLOCK_SKEW_SECONDS;
+```
+
+### 5.5 Helpers y funcionalidades clave
+
+#### `createJoseTokenService(...)`
+
+Firma real:
+
+```ts
+createJoseTokenService(
+  options: JoseTokenServiceOptions,
+  deps: { createAuthError: CreateAuthErrorFn },
+)
+```
+
+Responsabilidades reales:
+
+- validar `keyMaterial`,
+- exigir `createAuthError`,
+- construir una implementación concreta de `ITokenServicePort`.
+
+#### `JoseTokenServiceOptions`
+
+Configuración pública real:
+
+```ts
+export interface JoseTokenServiceOptions {
+  keyMaterial: JoseKeyMaterial;
+  issuer?: string;
+  audience?: string | string[];
+  clockSkewSeconds?: number;
+  defaultExpiresIn?: {
+    accessToken?: string;
+    refreshToken?: string;
+  };
+}
+```
+
+#### `JoseKeyMaterial`
+
+```ts
+type JoseKeyMaterial =
+  | { alg: "HS256"; secret: string }
+  | { alg: "RS256" | "ES256"; privateKey: string; publicKey: string };
+```
+
+#### Validación real de material criptográfico
+
+El plugin valida:
+
+- `HS256` requiere `secret`
+- `RS256` / `ES256` requieren `privateKey` y `publicKey`
+
+#### Audience: comportamiento importante
+
+Regla real implementada en el plugin:
+
+- `audience` se usa para **firmar** (`jwt.setAudience(...)`)
+- `audience` **no se pasa** a `jwtVerify(...)`
+
+Esto evita convertir `aud` en requisito obligatorio durante verificación.
+
+## ✅ Checklist (pasos rápidos)
+
+- [Instalar](#51-instalación)
+- [Definir `keyMaterial` según algoritmo](./docs/es/configuration.md#configuración-del-keymaterial)
+- [Construir el servicio con `createJoseTokenService`](./docs/configuration.md#construcción-del-token-service)
+- [Integrarlo en infrastructure del host](./docs/es/integration-express.md#integración-en-infrastructure-del-host)
+- [Verificar reglas de `audience` y clock skew](./docs/es/troubleshooting.md#1-el-token-se-firma-con-aud-pero-falla-la-verificación-esperada)
+- [Revisar troubleshooting](./docs/es/troubleshooting.md)
+
+## 📌 Menú
+
+- [Arquitectura](./docs/es/architecture.md)
+- [Configuración](./docs/es/configuration.md)
+- [Integración Express](./docs/es/integration-express.md)
+- [Troubleshooting](./docs/es/troubleshooting.md)
+
+## 🔗 Referencias
+
+- [`@jmlq/auth`](https://github.com/MLahuasi/jmlq-auth#readme)
+
+## ⬅️ 🌐 Ecosistema
+
+- [`@jmlq`](https://github.com/MLahuasi/jmlq-ecosystem#readme)

package/README.md

@@ -1,228 +1,197 @@
-# @jmlq/auth-plugin-jose
+# @jmlq/auth-plugin-jose 🧩
 
-## Introducción técnica
+## 🎯 Objective
 
-Plugin de **infraestructura JWT** basado en la librería [`jose`](https://github.com/panva/jose) para el core de autenticación [`@jmlq/auth`](https://www.npmjs.com/package/@jmlq/auth).
+`@jmlq/auth-plugin-jose` is the infrastructure plugin that implements `ITokenServicePort` from `@jmlq/auth` using the `jose` library.
 
-Este paquete **NO contiene lógica de negocio**.  
-Su única responsabilidad es **implementar los ports de tokens definidos por el core** y traducir detalles técnicos de `jose` a contratos estables del dominio.
+Its real responsibility is:
 
-El plugin se encarga de:
+- generate access tokens and refresh tokens,
+- verify signed tokens,
+- normalize cryptographic configuration,
+- translate technical errors from `jose` into core-compatible errors.
 
-- Generación y verificación de JWT
-- Soporte para algoritmos HS256, RS256 y ES256
-- Normalización y validación de claims estándar (`iss`, `aud`, `exp`, `nbf`, `iat`, `sub`, `jti`)
-- Validación de expiración y clock skew
-- Manejo de claves simétricas y asimétricas
-- Traducción de errores técnicos de `jose` a errores del core
+The recommended entry point is `createJoseTokenService(...)`.
 
----
+## ⭐ Importance
 
-## Relación con @jmlq/auth
+This plugin allows the `@jmlq/auth` core to remain independent from the specific JWT technology.
 
-- **@jmlq/auth**  
-  Core de autenticación (domain + application).  
-  Define contratos, errores y casos de uso.
+In practice:
 
-- **@jmlq/auth-plugin-jose**  
-  Plugin de **infraestructura**.  
-  Depende del core e implementa estrictamente sus ports.
+- the core depends on `ITokenServicePort`,
+- this plugin implements that contract,
+- the host decides whether to use `HS256`, `RS256`, or `ES256`,
+- business logic remains in `@jmlq/auth`.
 
-> ⚠️ Bajo ninguna circunstancia el core depende de este plugin.
+## 🏗️ Architecture (quick view)
 
----
+- `createJoseTokenService(...)` validates minimal preconditions and builds `JoseTokenService`.
+- `JoseTokenService` encapsulates `SignJWT`, `jwtVerify`, `decodeJwt`, `importPKCS8`, and `importSPKI`.
+- `jose-error.mapper.ts` translates technical errors into core error codes.
+- `audience` is used **only for issuing**; it is not passed to `jwtVerify` during verification.
 
-## Componentes principales expuestos
+➡️ See details in: [architecture.md](./docs/en/architecture.md)
 
-### Factory
+## 🔧 Implementation
 
-- **createJoseTokenService**  
-  Factory de alto nivel que construye una implementación de `ITokenServicePort`
-  compatible con `@jmlq/auth`.
-
-  Responsabilidades:
-
-  - Validar configuración técnica mínima (keys, algoritmo, opciones)
-  - Normalizar issuer, audience, expiración y clock skew
-  - Garantizar una política de expiración consistente
-  - Encapsular completamente el uso de `jose`
-
-  > Es el **único punto recomendado de entrada** para consumidores del plugin.
-
----
-
-### Tipos de configuración
-
-- **JoseTokenServiceOptions**  
-  Define la configuración necesaria para construir el servicio de tokens:
-  - `algorithm`: Algoritmo JWT (`HS256`, `RS256`, `ES256`)
-  - `keys`: Material criptográfico (secret o key pair)
-  - `issuer`: Emisor esperado (`iss`)
-  - `audience`: Audiencia permitida (`aud`)
-  - `defaultExpiresIn`: Expiración por defecto (ej: `"15m"`)
-  - `clockSkewSeconds`: Tolerancia de desajuste de reloj
-
-Estos tipos existen para **configuración explícita y tipada**, sin estado global.
-
----
-
-## Estrategia de errores (OBLIGATORIA)
-
-- El plugin **NO expone errores propios**
-
-Reglas:
-
-- Todos los errores de `jose` se traducen a `AuthDomainError`
-- No se definen nuevos códigos de error
-- El error original se conserva como `cause` o `meta`
-- La aplicación **solo maneja errores del core**
-
-Ejemplos de mapeo:
-
-| Error `jose`           | Error del core            |
-| ---------------------- | ------------------------- |
-| Token expirado         | `TOKEN_EXPIRED`           |
-| Firma inválida         | `SIGNATURE_INVALID`       |
-| Token malformado       | `TOKEN_MALFORMED`         |
-| Algoritmo no soportado | `ALGORITHM_UNSUPPORTED`   |
-| Claims inválidos       | `CLAIMS_VALIDATION_ERROR` |
-
----
-
-## 📦 Instalación
+### 5.1 Installation
 
 ```bash
-npm install @jmlq/auth @jmlq/auth-plugin-jose
+npm i @jmlq/auth @jmlq/auth-plugin-jose jose
 ```
 
-Versiones recomendadas:
+### 5.2 Dependencies
 
-- `@jmlq/auth` >= `0.1.0-alpha`
-- `jose` >= `5.x`
+Direct dependencies of the package:
 
----
+- `@jmlq/auth`
+- `jose`
 
-## Uso básico
+### 5.3 Quickstart (quick implementation)
 
-### Crear el servicio de tokens
+Recommended real usage from infrastructure:
 
 ```ts
 import { createJoseTokenService } from "@jmlq/auth-plugin-jose";
 
-const tokenService = createJoseTokenService({
-  algorithm: "HS256",
-  keys: { secret: "super-secret" },
-  issuer: "my-api",
-  audience: "my-clients",
-  defaultExpiresIn: "15m",
-  clockSkewSeconds: 5,
-});
+const tokenService = createJoseTokenService(
+  {
+    keyMaterial: {
+      alg: "RS256",
+      privateKey: process.env.JWT_PRIVATE_KEY!,
+      publicKey: process.env.JWT_PUBLIC_KEY!,
+    },
+    issuer: process.env.JWT_ISSUER,
+    audience: process.env.JWT_AUDIENCE,
+    clockSkewSeconds: Number(process.env.JWT_CLOCK_SKEW_SECONDS ?? 5),
+    defaultExpiresIn: {
+      accessToken: "15m",
+      refreshToken: "7d",
+    },
+  },
+  {
+    createAuthError,
+  },
+);
 ```
 
----
-
-### Generar un access token
+Also valid with `HS256`:
 
 ```ts
-const token = await tokenService.generateAccessToken({
-  subject: "user-123",
-  payload: {
-    scope: ["user"],
+const tokenService = createJoseTokenService(
+  {
+    keyMaterial: {
+      alg: "HS256",
+      secret: process.env.JWT_SECRET!,
+    },
+    issuer: process.env.JWT_ISSUER,
+    audience: process.env.JWT_AUDIENCE,
+    defaultExpiresIn: {
+      accessToken: "15m",
+      refreshToken: "7d",
+    },
   },
-});
+  { createAuthError },
+);
 ```
 
----
+### 5.4 Environment variables (.env) 📦
 
-### Verificar un token
+The plugin **does not read `.env` directly**.
+The host resolves variables and builds `JoseTokenServiceOptions`.
 
-```ts
-const result = await tokenService.verifyAccessToken(token);
+Typical variables consistent with this integration:
 
-console.log(result.payload.sub); // "user-123"
+```ts
+process.env.JWT_SECRET;
+process.env.JWT_PRIVATE_KEY;
+process.env.JWT_PUBLIC_KEY;
+process.env.JWT_ISSUER;
+process.env.JWT_AUDIENCE;
+process.env.JWT_CLOCK_SKEW_SECONDS;
 ```
 
-Si ocurre un error:
+### 5.5 Helpers and key functionalities
 
-- Se lanza un `AuthDomainError`
-- Nunca se lanza un error de `jose`
+#### `createJoseTokenService(...)`
 
----
+Real signature:
 
-### Ejemplo de integración en una API (Express)
+```ts
+createJoseTokenService(
+  options: JoseTokenServiceOptions,
+  deps: { createAuthError: CreateAuthErrorFn },
+)
+```
 
-Se recomienda realizar esta integración en la **capa infrastructure** de la API.
+Real responsibilities:
 
-```ts
-// src/infrastructure/auth/token-service.ts
+- validate `keyMaterial`,
+- require `createAuthError`,
+- build a concrete implementation of `ITokenServicePort`.
 
-import { createJoseTokenService } from "@jmlq/auth-plugin-jose";
+#### `JoseTokenServiceOptions`
 
-export const tokenService = createJoseTokenService({
-  algorithm: "RS256",
-  keys: {
-    publicKey: process.env.JWT_PUBLIC_KEY!,
-    privateKey: process.env.JWT_PRIVATE_KEY!,
-  },
-  issuer: "auth-api",
-  audience: "web-app",
-  defaultExpiresIn: "15m",
-});
+Real public configuration:
+
+```ts
+export interface JoseTokenServiceOptions {
+  keyMaterial: JoseKeyMaterial;
+  issuer?: string;
+  audience?: string | string[];
+  clockSkewSeconds?: number;
+  defaultExpiresIn?: {
+    accessToken?: string;
+    refreshToken?: string;
+  };
+}
 ```
 
-## Este servicio se inyecta luego en los casos de uso del core (`@jmlq/auth`).
+#### `JoseKeyMaterial`
 
----
+```ts
+type JoseKeyMaterial =
+  | { alg: "HS256"; secret: string }
+  | { alg: "RS256" | "ES256"; privateKey: string; publicKey: string };
+```
 
-## Variables de entorno (recomendadas)
+#### Real cryptographic material validation
 
-El plugin **No lee variables de entorno directamente**, pero una API típica puede definir::
+The plugin validates:
 
-```ini
-JWT_ALGORITHM=RS256
-JWT_ISSUER=auth-api
-JWT_AUDIENCE=web-app
-JWT_DEFAULT_EXPIRES_IN=15m
-JWT_CLOCK_SKEW_SECONDS=5
+- `HS256` requires `secret`
+- `RS256` / `ES256` require `privateKey` and `publicKey`
 
-JWT_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----..."
-JWT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----..."
+#### Audience: important behavior
 
-```
+Real rule implemented in the plugin:
 
-La lectura y validación de estas variables es responsabilidad de la aplicación.
+- `audience` is used for **signing** (`jwt.setAudience(...)`)
+- `audience` is **not passed** to `jwtVerify(...)`
 
----
+This prevents turning `aud` into a mandatory requirement during verification.
 
-## Estructura del proyecto
+## ✅ Checklist (quick steps)
 
-```
-src/
-├─ application/
-│  ├─ factories/
-│  │  └─ create-jose-token-service.ts
-│  ├─ types/
-│  │  └─ jose-token-service.options.ts
-│  └─ internal/
-│     └─ *.util.ts
-│
-├─ infrastructure/
-│  ├─ services/
-│  │  └─ jose-token.service.ts
-│  └─ mappers/
-│     └─ jose-error.mapper.ts
-│
-└─ index.ts
+- [Install](#51-installation)
+- [Define `keyMaterial` according to algorithm](./docs/en/configuration.md#configuring-keymaterial)
+- [Build the service with `createJoseTokenService`](./docs/en/configuration.md#building-the-token-service)
+- [Integrate it into the host infrastructure](./docs/en/integration-express.md#integration-in-host-infrastructure)
+- [Verify `audience` and clock skew rules](./docs/en/troubleshooting.md#1-token-is-signed-with-aud-but-verification-fails-as-expected)
+- [Review troubleshooting](./docs/en/troubleshooting.md)
 
-```
+## 📌 Menu
 
----
+- [Architecture](./docs/en/architecture.md)
+- [Configuration](./docs/en/configuration.md)
+- [Express Integration](./docs/en/integration-express.md)
+- [Troubleshooting](./docs/en/troubleshooting.md)
 
-## 📄 Más información
+## 🔗 References
 
-- **[🏗️ Documentación de Arquitectura](./architecture.md)** - Clean Architecture, capas y patrones
-- **[📚 Ejemplos de Código](./examples/)** - Casos de uso reales y implementaciones
+- [`@jmlq/auth`](https://github.com/MLahuasi/jmlq-auth#readme)
 
-## 📄 Licencia
+## ⬅️ 🌐 Ecosystem
 
-MIT © Mauricio Lahuasi
+- [`@jmlq`](https://github.com/MLahuasi/jmlq-ecosystem#readme)

package/dist/infrastructure/mappers/errors/ensure-auth-error-code.d.ts

@@ -0,0 +1,11 @@
+import type { AuthErrorCode } from "@jmlq/auth";
+/**
+ * Convierte un Error (posiblemente sin code) en uno con `code: AuthErrorCode`
+ * de forma segura y mínima, SIN cambiar el tipo del error original.
+ *
+ * - Si ya tiene code string, lo usa.
+ * - Si no, usa un fallback dado (por ej. "JWT_ERROR").
+ */
+export declare function ensureAuthErrorCode(err: Error, fallback: AuthErrorCode): Error & {
+    code: AuthErrorCode;
+};

package/dist/infrastructure/mappers/errors/ensure-auth-error-code.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureAuthErrorCode = ensureAuthErrorCode;
+/**
+ * Convierte un Error (posiblemente sin code) en uno con `code: AuthErrorCode`
+ * de forma segura y mínima, SIN cambiar el tipo del error original.
+ *
+ * - Si ya tiene code string, lo usa.
+ * - Si no, usa un fallback dado (por ej. "JWT_ERROR").
+ */
+function ensureAuthErrorCode(err, fallback) {
+    const e = err;
+    const code = typeof e.code === "string" ? e.code : undefined;
+    // Importante: aquí NO validamos que code pertenezca al union.
+    // Solo garantizamos que al menos sea un AuthErrorCode conocido o fallback.
+    const safeCode = code ?? fallback;
+    // Mutación mínima: añadimos code si falta
+    e.code = safeCode;
+    return e;
+}

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

@@ -0,0 +1 @@
+export * from "./ensure-auth-error-code";

package/dist/infrastructure/mappers/errors/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("./ensure-auth-error-code"), exports);

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

@@ -1,3 +1,4 @@
+import type { AuthErrorCode } from "@jmlq/auth";
 import type { JoseErrorContext, MappedAuthError } from "./types";
 export declare function mapJoseErrorToAuthError(err: unknown, ctx: JoseErrorContext): MappedAuthError;
 export declare function toAuthDomainError<TAuthError extends Error>(createAuthError: (args: {
@@ -5,4 +6,6 @@ export declare function toAuthDomainError<TAuthError extends Error>(createAuthEr
     message: string;
     cause?: unknown;
     meta?: Record<string, unknown>;
-}) => TAuthError, err: unknown, ctx: JoseErrorContext): TAuthError;
+}) => TAuthError, err: unknown, ctx: JoseErrorContext): Error & {
+    code: AuthErrorCode;
+};

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

@@ -1,9 +1,9 @@
 "use strict";
-//src/infrastructure/mappers/jose-error.mapper.ts
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.mapJoseErrorToAuthError = mapJoseErrorToAuthError;
 exports.toAuthDomainError = toAuthDomainError;
 const auth_1 = require("@jmlq/auth");
+const errors_1 = require("./errors");
 /**
  * Mapper de errores de `jose` → error “entendible” por el core (@jmlq/auth).
  *
@@ -29,20 +29,32 @@ function buildSafeMeta(joseErrorName, ctx) {
         alg: ctx.alg,
     };
 }
+/**
+ * Tabla: err.name (jose) -> AuthErrorCode (core)
+ */
 const JOSE_NAME_TO_AUTH_CODE = {
+    // Tiempo
     JWTExpired: "TOKEN_EXPIRED",
     JWTNotBefore: "TOKEN_NOT_YET_VALID",
     JWTNotYetValid: "TOKEN_NOT_YET_VALID",
+    // Firma
     JWSSignatureVerificationFailed: "SIGNATURE_INVALID",
-    JWSInvalid: "SIGNATURE_INVALID",
-    JWSError: "SIGNATURE_INVALID",
+    // Estructura/serialización JWS inválida
+    JWSInvalid: "TOKEN_MALFORMED",
+    JWSMalformed: "TOKEN_MALFORMED",
+    // Error genérico JWS (no asumir firma)
+    JWSError: "TOKEN_INVALID",
+    // Claims inválidos (issuer, exp, nbf, etc. dependiendo de jose)
     JWTClaimValidationFailed: "CLAIMS_VALIDATION_ERROR",
+    // Token inválido (pero no necesariamente “malformed”)
     JWTInvalid: "TOKEN_INVALID",
+    // Token malformado
     JWTMalformed: "TOKEN_MALFORMED",
-    JWSMalformed: "TOKEN_MALFORMED",
     JOSEError: "TOKEN_MALFORMED",
+    // Algoritmo / soporte
     JOSENotSupported: "ALGORITHM_UNSUPPORTED",
     JWTAlgorithmNotAllowed: "ALGORITHM_UNSUPPORTED",
+    // Key material
     JWKInvalid: "KEY_MISMATCH",
     JWKInvalidFormat: "KEY_MISMATCH",
 };
@@ -54,6 +66,8 @@ const JOSE_NAME_TO_AUTH_CODE = {
  * - Por eso es Partial<Record<AuthErrorCode, string>> + fallback.
  */
 const AUTH_CODE_TO_MESSAGE = {
+    JWT_EMPTY: "Invalid empty JWT",
+    JWT_MALFORMED: "JWT is malformed",
     TOKEN_INVALID: "Token is invalid",
     TOKEN_EXPIRED: "Token has expired",
     TOKEN_MALFORMED: "Token is malformed",
@@ -74,6 +88,14 @@ function mapJoseErrorToAuthError(err, ctx) {
     const message = AUTH_CODE_TO_MESSAGE[code] ??
         // fallback defensivo (no dependemos de message de jose)
         "JWT operation failed";
+    // console.log({
+    //   package: "@jmlq/auth-plugin-jose",
+    //   name,
+    //   meta,
+    //   code,
+    //   message,
+    //   err,
+    // });
     return {
         code,
         message,
@@ -82,14 +104,17 @@ function mapJoseErrorToAuthError(err, ctx) {
     };
 }
 function toAuthDomainError(createAuthError, err, ctx) {
+    // Si ya es error del core, conservarlo (NO remapear)
     if (auth_1.AuthDomainError.isAuthError(err)) {
         return err;
     }
     const mapped = mapJoseErrorToAuthError(err, ctx);
-    return createAuthError({
+    const created = createAuthError({
         code: mapped.code,
         message: mapped.message,
         cause: mapped.cause,
         meta: mapped.meta,
     });
+    // Garantizamos code usable por `isRetryableAuthCode`
+    return (0, errors_1.ensureAuthErrorCode)(created, mapped.code);
 }

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

@@ -1,5 +1,4 @@
 "use strict";
-// src/infrastructure/services/jose-token.service.ts
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.JoseTokenService = void 0;
 const jose_1 = require("jose");
@@ -103,7 +102,19 @@ class JoseTokenService {
             return await fn();
         }
         catch (err) {
-            throw (0, mappers_1.toAuthDomainError)(this.createAuthError, err, this.ctx(operation, kind));
+            // 1) Si ya viene como error del core, NO tocarlo
+            if (auth_1.AuthDomainError.isAuthError(err)) {
+                throw err;
+            }
+            // 2) Si es error de jose u otro, mapear SIEMPRE
+            const authErr = (0, mappers_1.toAuthDomainError)(this.createAuthError, err, this.ctx(operation, kind));
+            // 3) (Opcional) Si tienes retry logic, que dependa solo de code del core
+            //    y NO de códigos internos de jose.
+            //    Ej: si no quieres reintentos, elimina esto.
+            if ((0, auth_1.isRetryableAuthCode)(authErr.code)) {
+                throw authErr;
+            }
+            throw authErr;
         }
     }
     // ---------------------------------------------------------------------------
@@ -173,24 +184,47 @@ class JoseTokenService {
     }
     async verifyToken(kind, operation, token) {
         return this.withAuthError(operation, kind, async () => {
-            const keys = await this.getNormalizedKeys();
-            const key = keys.alg === "HS256" ? keys.secret : keys.publicKey;
             /**
-             * Verificación:
-             * - issuer: se aplica si está configurado (si no, se omite)
-             * - clockTolerance: ya normalizado (clock skew seguro)
+             * Validación estructural temprana (core):
+             * - JWT_EMPTY si token está vacío
+             * - JWT_MALFORMED si no tiene 3 segmentos
              *
-             * Nota: NO pasamos `audience` a jwtVerify.
-             * - La audiencia en este plugin es SOLO para emisión.
-             * - Pasarla aquí convertiría audience en una restricción (“must match”)
-             *   y rompería compatibilidad con tokens válidos sin `aud`.
+             * Nota:
+             * - Esto evita que `jose` arroje errores “ruidosos” por formato inválido.
+             * - Estos errores YA son AuthDomainError y deben conservar su code.
              */
-            const result = await (0, jose_1.jwtVerify)(token, key, {
-                issuer: this.eff.issuer,
-                clockTolerance: this.eff.clockSkewSeconds,
-            });
-            // Delegar a la regla canónica del core: valida + normaliza payload.
-            return (0, auth_1.normalizeJwtPayload)(result.payload);
+            (0, auth_1.assertJwtStructure)(token);
+            const keys = await this.getNormalizedKeys();
+            const key = keys.alg === "HS256" ? keys.secret : keys.publicKey;
+            try {
+                /**
+                 * Verificación:
+                 * - issuer: se aplica si está configurado (si no, se omite)
+                 * - clockTolerance: ya normalizado (clock skew seguro)
+                 *
+                 * Nota: NO pasamos `audience` a jwtVerify.
+                 * - La audiencia en este plugin es SOLO para emisión.
+                 * - Pasarla aquí convertiría audience en una restricción (“must match”)
+                 *   y rompería compatibilidad con tokens válidos sin `aud`.
+                 */
+                const result = await (0, jose_1.jwtVerify)(token, key, {
+                    issuer: this.eff.issuer,
+                    clockTolerance: this.eff.clockSkewSeconds,
+                });
+                // Delegar a la regla canónica del core: valida + normaliza payload.
+                return (0, auth_1.normalizeJwtPayload)(result.payload);
+            }
+            catch (err) {
+                /**
+                 * Importante:
+                 * - NO relanzar error crudo de jose.
+                 * - Convertirlo a AuthDomainError con code estable (TOKEN_INVALID, SIGNATURE_INVALID, etc.)
+                 *   usando el mapper oficial.
+                 *
+                 * Esto evita que el host termine con INTERNAL + alert emails para 401 esperados.
+                 */
+                throw (0, mappers_1.toAuthDomainError)(this.createAuthError, err, this.ctx(operation, kind));
+            }
         });
     }
     async tryGetExpirationByVerify(kind, token) {

package/package.json

@@ -1,23 +1,21 @@
 {
   "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.9",
+  "version": "0.0.1-beta.1",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MLahuasi/jmlq-auth-plugin-jose.git"
+  },
+  "homepage": "https://github.com/MLahuasi/jmlq-auth-plugin-jose#readme",
   "scripts": {
     "dev": "rimraf dist && mkdir dist && tsc -p tsconfig.json",
     "build": "rimraf dist && mkdir dist && tsc -p tsconfig.build.json",
     "prepublishOnly": "npm run build",
-    "package:script": "node scripts/package-script.mjs",
     "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"
+    "test:coverage": "jest --coverage"
   },
   "keywords": [
     "jwt",
@@ -29,7 +27,7 @@
   "author": "MLahuasi",
   "license": "MIT",
   "dependencies": {
-    "@jmlq/auth": "^0.0.1-alpha.30",
+    "@jmlq/auth": "beta",
     "jose": "^6.1.3"
   },
   "devDependencies": {