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

package/README.md

@@ -0,0 +1,228 @@
+# @jmlq/auth-plugin-jose
+
+## Introducción técnica
+
+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).
+
+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.
+
+El plugin se encarga de:
+
+- 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
+
+---
+
+## Relación con @jmlq/auth
+
+- **@jmlq/auth**  
+  Core de autenticación (domain + application).  
+  Define contratos, errores y casos de uso.
+
+- **@jmlq/auth-plugin-jose**  
+  Plugin de **infraestructura**.  
+  Depende del core e implementa estrictamente sus ports.
+
+> ⚠️ Bajo ninguna circunstancia el core depende de este plugin.
+
+---
+
+## Componentes principales expuestos
+
+### Factory
+
+- **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
+
+```bash
+npm install @jmlq/auth @jmlq/auth-plugin-jose
+```
+
+Versiones recomendadas:
+
+- `@jmlq/auth` >= `0.1.0-alpha`
+- `jose` >= `5.x`
+
+---
+
+## Uso básico
+
+### Crear el servicio de tokens
+
+```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,
+});
+```
+
+---
+
+### Generar un access token
+
+```ts
+const token = await tokenService.generateAccessToken({
+  subject: "user-123",
+  payload: {
+    scope: ["user"],
+  },
+});
+```
+
+---
+
+### Verificar un token
+
+```ts
+const result = await tokenService.verifyAccessToken(token);
+
+console.log(result.payload.sub); // "user-123"
+```
+
+Si ocurre un error:
+
+- Se lanza un `AuthDomainError`
+- Nunca se lanza un error de `jose`
+
+---
+
+### Ejemplo de integración en una API (Express)
+
+Se recomienda realizar esta integración en la **capa infrastructure** de la API.
+
+```ts
+// src/infrastructure/auth/token-service.ts
+
+import { createJoseTokenService } from "@jmlq/auth-plugin-jose";
+
+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",
+});
+```
+
+## Este servicio se inyecta luego en los casos de uso del core (`@jmlq/auth`).
+
+---
+
+## Variables de entorno (recomendadas)
+
+El plugin **No lee variables de entorno directamente**, pero una API típica puede definir::
+
+```ini
+JWT_ALGORITHM=RS256
+JWT_ISSUER=auth-api
+JWT_AUDIENCE=web-app
+JWT_DEFAULT_EXPIRES_IN=15m
+JWT_CLOCK_SKEW_SECONDS=5
+
+JWT_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----..."
+JWT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----..."
+
+```
+
+La lectura y validación de estas variables es responsabilidad de la aplicación.
+
+---
+
+## Estructura del proyecto
+
+```
+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
+
+```
+
+---
+
+## 📄 Más información
+
+- **[🏗️ Documentación de Arquitectura](./architecture.md)** - Clean Architecture, capas y patrones
+- **[📚 Ejemplos de Código](./examples/)** - Casos de uso reales y implementaciones
+
+## 📄 Licencia
+
+MIT © Mauricio Lahuasi

package/dist/application/factories/create-jose-token-service.d.ts

@@ -0,0 +1,28 @@
+import type { ITokenServicePort } from "@jmlq/auth";
+import type { JoseTokenServiceOptions } from "../types";
+import type { CreateAuthErrorFn } from "../../infrastructure/services/types";
+/**
+ * Factory para construir un `ITokenServicePort` basado en `jose`.
+ *
+ * Responsabilidades de esta factory:
+ * - Validar configuración mínima (keys, defaults requeridos).
+ * - Normalizar opciones (issuer/audience/clockSkew/defaultExpiresIn).
+ * - Garantizar política acordada: getExpirationPolicy = "verify-first".
+ *
+ * No hace:
+ * - importación de keys
+ * - operaciones JWT
+ * (eso es responsabilidad del adapter `JoseTokenService`).
+ *
+ * @template TAuthError Tipo de error del core que se construye mediante createAuthError.
+ *
+ * @param args Argumentos del factory.
+ * @param args.options Opciones del plugin (keys, issuer/audience, defaults, etc.).
+ * @param args.createAuthError Función para construir errores del core (no errores del plugin).
+ *
+ * @returns Instancia que cumple `ITokenServicePort`.
+ */
+export declare function createJoseTokenService<TAuthError extends Error>(args: {
+    options: JoseTokenServiceOptions;
+    createAuthError: CreateAuthErrorFn<TAuthError>;
+}): ITokenServicePort;

package/dist/application/factories/create-jose-token-service.js

@@ -0,0 +1,76 @@
+"use strict";
+// src/application/factories/create-jose-token-service.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createJoseTokenService = createJoseTokenService;
+const types_1 = require("../types");
+const services_1 = require("../../infrastructure/services");
+const internal_1 = require("./internal");
+/**
+ * Factory para construir un `ITokenServicePort` basado en `jose`.
+ *
+ * Responsabilidades de esta factory:
+ * - Validar configuración mínima (keys, defaults requeridos).
+ * - Normalizar opciones (issuer/audience/clockSkew/defaultExpiresIn).
+ * - Garantizar política acordada: getExpirationPolicy = "verify-first".
+ *
+ * No hace:
+ * - importación de keys
+ * - operaciones JWT
+ * (eso es responsabilidad del adapter `JoseTokenService`).
+ *
+ * @template TAuthError Tipo de error del core que se construye mediante createAuthError.
+ *
+ * @param args Argumentos del factory.
+ * @param args.options Opciones del plugin (keys, issuer/audience, defaults, etc.).
+ * @param args.createAuthError Función para construir errores del core (no errores del plugin).
+ *
+ * @returns Instancia que cumple `ITokenServicePort`.
+ */
+function createJoseTokenService(args) {
+    const { options, createAuthError } = args;
+    // ---------------------------------------------------------------------------
+    // Validación mínima (fail-fast)
+    // ---------------------------------------------------------------------------
+    (0, internal_1.assert)(!!options, "options is required");
+    (0, internal_1.assert)(!!options.access, "options.access is required");
+    (0, internal_1.assert)(!!options.refresh, "options.refresh is required");
+    (0, internal_1.validateKeyMaterial)("access", options.access.keys);
+    (0, internal_1.validateKeyMaterial)("refresh", options.refresh.keys);
+    // Exigir defaults de expiración (props.expiresIn es opcional)
+    const accessDefaultExpiresIn = (0, internal_1.normalizeDefaultExpiresIn)("access", options.access.defaultExpiresIn);
+    const refreshDefaultExpiresIn = (0, internal_1.normalizeDefaultExpiresIn)("refresh", options.refresh.defaultExpiresIn);
+    // ---------------------------------------------------------------------------
+    // Normalización de opciones comunes
+    // ---------------------------------------------------------------------------
+    const commonIssuer = (0, internal_1.normalizeIssuer)(options.issuer);
+    const commonAudience = (0, internal_1.normalizeAudience)(options.audience);
+    const commonClockSkewSeconds = (0, internal_1.normalizeClockSkewSeconds)(options.clockSkewSeconds);
+    // Política acordada: solo verify-first
+    const getExpirationPolicy = options.getExpirationPolicy ?? types_1.DEFAULT_GET_EXPIRATION_POLICY;
+    (0, internal_1.assert)(getExpirationPolicy === "verify-first", `getExpirationPolicy must be "verify-first"`);
+    // ---------------------------------------------------------------------------
+    // Construcción final de options (con defaults aplicados)
+    // ---------------------------------------------------------------------------
+    const normalizedOptions = {
+        issuer: commonIssuer,
+        audience: commonAudience,
+        clockSkewSeconds: commonClockSkewSeconds,
+        getExpirationPolicy,
+        access: {
+            ...options.access,
+            issuer: (0, internal_1.normalizeIssuer)(options.access.issuer) ?? commonIssuer,
+            audience: (0, internal_1.normalizeAudience)(options.access.audience) ?? commonAudience,
+            clockSkewSeconds: (0, internal_1.normalizeClockSkewSeconds)(options.access.clockSkewSeconds ?? commonClockSkewSeconds),
+            defaultExpiresIn: accessDefaultExpiresIn,
+        },
+        refresh: {
+            ...options.refresh,
+            issuer: (0, internal_1.normalizeIssuer)(options.refresh.issuer) ?? commonIssuer,
+            audience: (0, internal_1.normalizeAudience)(options.refresh.audience) ?? commonAudience,
+            clockSkewSeconds: (0, internal_1.normalizeClockSkewSeconds)(options.refresh.clockSkewSeconds ?? commonClockSkewSeconds),
+            defaultExpiresIn: refreshDefaultExpiresIn,
+        },
+    };
+    // La instancia real (JWT ops) vive en infraestructura.
+    return new services_1.JoseTokenService(normalizedOptions, createAuthError);
+}

package/dist/application/factories/index.d.ts

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

package/dist/application/factories/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-jose-token-service"), exports);

package/dist/application/factories/internal/assert.util.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Assert minimalista para validar precondiciones.
+ * Si la condición no se cumple, lanza un Error con prefijo del factory
+ * para rastrear rápidamente el origen.
+ *
+ * @param condition Expresión booleana que debe cumplirse.
+ * @param message Mensaje técnico simple (sin datos sensibles).
+ */
+export declare function assert(condition: any, message: string): asserts condition;

package/dist/application/factories/internal/assert.util.js

@@ -0,0 +1,16 @@
+"use strict";
+// src/application/factories/internal/assert.util.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assert = assert;
+/**
+ * Assert minimalista para validar precondiciones.
+ * Si la condición no se cumple, lanza un Error con prefijo del factory
+ * para rastrear rápidamente el origen.
+ *
+ * @param condition Expresión booleana que debe cumplirse.
+ * @param message Mensaje técnico simple (sin datos sensibles).
+ */
+function assert(condition, message) {
+    if (!condition)
+        throw new Error(`[createJoseTokenService] ${message}`);
+}

package/dist/application/factories/internal/clock-skew-normalizer.util.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Normaliza el clock skew (tolerancia de reloj) en segundos.
+ *
+ * ¿Para qué sirve?
+ * En sistemas distribuidos, el reloj del servidor puede diferir unos segundos.
+ * `clockSkewSeconds` permite tolerar esa diferencia al validar tokens.
+ *
+ * Reglas:
+ * - si no es número finito o es negativo -> usa default.
+ *
+ * @param value Valor recibido desde options.
+ * @returns clockSkewSeconds normalizado.
+ */
+export declare function normalizeClockSkewSeconds(value: unknown): number;

package/dist/application/factories/internal/clock-skew-normalizer.util.js

@@ -0,0 +1,24 @@
+"use strict";
+// src/application/factories/internal/clock-skew-normalizer.util.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeClockSkewSeconds = normalizeClockSkewSeconds;
+const types_1 = require("../../types");
+/**
+ * Normaliza el clock skew (tolerancia de reloj) en segundos.
+ *
+ * ¿Para qué sirve?
+ * En sistemas distribuidos, el reloj del servidor puede diferir unos segundos.
+ * `clockSkewSeconds` permite tolerar esa diferencia al validar tokens.
+ *
+ * Reglas:
+ * - si no es número finito o es negativo -> usa default.
+ *
+ * @param value Valor recibido desde options.
+ * @returns clockSkewSeconds normalizado.
+ */
+function normalizeClockSkewSeconds(value) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+        return types_1.DEFAULT_CLOCK_SKEW_SECONDS;
+    }
+    return value;
+}

package/dist/application/factories/internal/expires-in.util.d.ts

@@ -0,0 +1,21 @@
+import type { ExpiresInString } from "../../types/expires-in.types";
+/**
+ * Verifica si un valor cumple el formato ExpiresInString.
+ *
+ * Formato aceptado:
+ * - número + unidad: s (seconds), m (minutes), h (hours), d (days)
+ * Ejemplos: "15m", "7d", "3600s", "12h".
+ *
+ * @param value Valor desconocido a validar.
+ * @returns true si es ExpiresInString.
+ */
+export declare function isExpiresInString(value: unknown): value is ExpiresInString;
+/**
+ * Normaliza y exige `defaultExpiresIn` porque `props.expiresIn` es opcional.
+ * Si el valor no existe o no cumple el formato, lanza Error.
+ *
+ * @param kind Tipo de token (access/refresh) para mensajes claros.
+ * @param value Valor recibido desde options.
+ * @returns ExpiresInString válido.
+ */
+export declare function normalizeDefaultExpiresIn(kind: "access" | "refresh", value: unknown): ExpiresInString;

package/dist/application/factories/internal/expires-in.util.js

@@ -0,0 +1,31 @@
+"use strict";
+// src/application/factories/internal/expires-in.util.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isExpiresInString = isExpiresInString;
+exports.normalizeDefaultExpiresIn = normalizeDefaultExpiresIn;
+const assert_util_1 = require("./assert.util");
+/**
+ * Verifica si un valor cumple el formato ExpiresInString.
+ *
+ * Formato aceptado:
+ * - número + unidad: s (seconds), m (minutes), h (hours), d (days)
+ * Ejemplos: "15m", "7d", "3600s", "12h".
+ *
+ * @param value Valor desconocido a validar.
+ * @returns true si es ExpiresInString.
+ */
+function isExpiresInString(value) {
+    return typeof value === "string" && /^[0-9]+[smhd]$/.test(value);
+}
+/**
+ * Normaliza y exige `defaultExpiresIn` porque `props.expiresIn` es opcional.
+ * Si el valor no existe o no cumple el formato, lanza Error.
+ *
+ * @param kind Tipo de token (access/refresh) para mensajes claros.
+ * @param value Valor recibido desde options.
+ * @returns ExpiresInString válido.
+ */
+function normalizeDefaultExpiresIn(kind, value) {
+    (0, assert_util_1.assert)(isExpiresInString(value), `${kind}.defaultExpiresIn is required and must match format like "15m", "7d", "3600s"`);
+    return value;
+}

package/dist/application/factories/internal/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./assert.util";
+export * from "./clock-skew-normalizer.util";
+export * from "./expires-in.util";
+export * from "./key-material.validator";
+export * from "./string-normalizers.util";

package/dist/application/factories/internal/index.js

@@ -0,0 +1,21 @@
+"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("./assert.util"), exports);
+__exportStar(require("./clock-skew-normalizer.util"), exports);
+__exportStar(require("./expires-in.util"), exports);
+__exportStar(require("./key-material.validator"), exports);
+__exportStar(require("./string-normalizers.util"), exports);

package/dist/application/factories/internal/key-material.validator.d.ts

@@ -0,0 +1,15 @@
+import type { JoseKeyMaterial } from "../../types";
+/**
+ * Valida que el material de claves requerido exista según el algoritmo.
+ *
+ * Reglas simples:
+ * - HS256: requiere `secret` (string o Uint8Array).
+ * - RS256/ES256: requiere `privateKey` y `publicKey` (PEM string o KeyLike).
+ *
+ * Nota: esta validación NO importa/parsea keys.
+ * Solo valida presencia y tipo básico para fallar rápido.
+ *
+ * @param kind Tipo de token (access/refresh) para errores claros.
+ * @param keys Configuración de claves para ese token.
+ */
+export declare function validateKeyMaterial(kind: "access" | "refresh", keys: JoseKeyMaterial): void;

package/dist/application/factories/internal/key-material.validator.js

@@ -0,0 +1,26 @@
+"use strict";
+// src/application/factories/internal/key-material.validator.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateKeyMaterial = validateKeyMaterial;
+const assert_util_1 = require("./assert.util");
+/**
+ * Valida que el material de claves requerido exista según el algoritmo.
+ *
+ * Reglas simples:
+ * - HS256: requiere `secret` (string o Uint8Array).
+ * - RS256/ES256: requiere `privateKey` y `publicKey` (PEM string o KeyLike).
+ *
+ * Nota: esta validación NO importa/parsea keys.
+ * Solo valida presencia y tipo básico para fallar rápido.
+ *
+ * @param kind Tipo de token (access/refresh) para errores claros.
+ * @param keys Configuración de claves para ese token.
+ */
+function validateKeyMaterial(kind, keys) {
+    if (keys.alg === "HS256") {
+        (0, assert_util_1.assert)(typeof keys.secret === "string" || keys.secret instanceof Uint8Array, `${kind}.keys.secret must be string or Uint8Array for HS256`);
+        return;
+    }
+    (0, assert_util_1.assert)(keys.privateKey != null, `${kind}.keys.privateKey is required for ${keys.alg}`);
+    (0, assert_util_1.assert)(keys.publicKey != null, `${kind}.keys.publicKey is required for ${keys.alg}`);
+}

package/dist/application/factories/internal/string-normalizers.util.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Normaliza issuer:
+ * - si es string no vacío: trim()
+ * - si no: undefined
+ *
+ * @param value Valor recibido desde options.
+ * @returns issuer normalizado.
+ */
+export declare function normalizeIssuer(value: unknown): string | undefined;
+/**
+ * Normaliza audience:
+ * - si es string no vacío: trim()
+ * - si no: undefined
+ *
+ * @param value Valor recibido desde options.
+ * @returns audience normalizado.
+ */
+export declare function normalizeAudience(value: unknown): string | undefined;

package/dist/application/factories/internal/string-normalizers.util.js

@@ -0,0 +1,31 @@
+"use strict";
+// src/application/factories/internal/string-normalizers.util.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeIssuer = normalizeIssuer;
+exports.normalizeAudience = normalizeAudience;
+/**
+ * Normaliza issuer:
+ * - si es string no vacío: trim()
+ * - si no: undefined
+ *
+ * @param value Valor recibido desde options.
+ * @returns issuer normalizado.
+ */
+function normalizeIssuer(value) {
+    return typeof value === "string" && value.trim().length > 0
+        ? value.trim()
+        : undefined;
+}
+/**
+ * Normaliza audience:
+ * - si es string no vacío: trim()
+ * - si no: undefined
+ *
+ * @param value Valor recibido desde options.
+ * @returns audience normalizado.
+ */
+function normalizeAudience(value) {
+    return typeof value === "string" && value.trim().length > 0
+        ? value.trim()
+        : undefined;
+}

package/dist/application/types/expires-in.types.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Representa un valor de expiración humano para JWT.
+ *
+ * Convenciones aceptadas (a definir por el parser del plugin):
+ * - Segundos: "3600s"
+ * - Minutos:  "15m"
+ * - Horas:    "1h"
+ * - Días:     "7d"
+ *
+ * NOTA:
+ * - Este tipo NO implementa parsing.
+ * - La conversión a segundos/Date se hace en la capa infrastructure.
+ * - El core (@jmlq/auth) ya usa string para expiresIn; este archivo
+ *   solo documenta y formaliza el contrato esperado por el plugin.
+ */
+/**
+ * Unidades de tiempo soportadas para expiresIn.
+ */
+export type ExpiresInUnit = "s" | "m" | "h" | "d";
+/**
+ * Formato string esperado para expiresIn.
+ *
+ * Ejemplos válidos:
+ * - "3600s"
+ * - "15m"
+ * - "1h"
+ * - "7d"
+ */
+export type ExpiresInString = `${number}${ExpiresInUnit}`;
+/**
+ * Alias semántico para mayor claridad en options y props.
+ */
+export type ExpiresIn = ExpiresInString;

package/dist/application/types/expires-in.types.js

@@ -0,0 +1,3 @@
+"use strict";
+// src/application/types/expires-in.types.ts
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,2 @@
+export * from "./expires-in.types";
+export * from "./jose-token-service.options";

package/dist/application/types/index.js

@@ -0,0 +1,18 @@
+"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.types"), exports);
+__exportStar(require("./jose-token-service.options"), exports);