@jmlq/auth 0.0.1-alpha.23 → 0.0.1-alpha.25

package/dist/domain/services/helpers/optional-audience.helper.d.ts

@@ -1 +1,14 @@
+/**
+ * Regla canónica de dominio para el claim estándar `aud` (audience).
+ *
+ * Propósito:
+ * - Aceptar `aud` como string o string[] (según librería/plugin).
+ * - Rechazar valores vacíos.
+ * - Si es array: normalizar de forma determinista (dedupe + sort),
+ *   útil para tests y debugging.
+ *
+ * Importante:
+ * - Esta validación es del CORE (@jmlq/auth).
+ * - Los plugins JWT NO deben validar audience; solo entregan payload verificado.
+ */
 export declare function optionalAudience(value: unknown): string | string[] | undefined;

package/dist/domain/services/helpers/optional-audience.helper.js

@@ -2,9 +2,24 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.optionalAudience = optionalAudience;
 const errors_1 = require("../../errors");
+/**
+ * Regla canónica de dominio para el claim estándar `aud` (audience).
+ *
+ * Propósito:
+ * - Aceptar `aud` como string o string[] (según librería/plugin).
+ * - Rechazar valores vacíos.
+ * - Si es array: normalizar de forma determinista (dedupe + sort),
+ *   útil para tests y debugging.
+ *
+ * Importante:
+ * - Esta validación es del CORE (@jmlq/auth).
+ * - Los plugins JWT NO deben validar audience; solo entregan payload verificado.
+ */
 function optionalAudience(value) {
+    // aud ausente => ok
     if (value == null)
         return undefined;
+    // aud como string
     if (typeof value === "string") {
         const v = value.trim();
         if (!v) {
@@ -14,19 +29,19 @@ function optionalAudience(value) {
         }
         return v;
     }
+    // aud como string[]
     if (Array.isArray(value)) {
         const items = value
             .filter((x) => typeof x === "string")
             .map((x) => x.trim())
             .filter((x) => x.length > 0);
         if (items.length === 0) {
-            throw new errors_1.InvalidJwtPayloadError("JWT payload.aud must contain at least one non-empty string", {
-                field: "aud",
-            });
+            throw new errors_1.InvalidJwtPayloadError("JWT payload.aud must contain at least one non-empty string", { field: "aud" });
         }
-        // Determinista (útil para test/debug)
+        // Determinista: sin duplicados y ordenado
         return Array.from(new Set(items)).sort((a, b) => a.localeCompare(b));
     }
+    // Tipo inválido
     throw new errors_1.InvalidJwtPayloadError("JWT payload.aud must be a string or string[]", {
         field: "aud",
         receivedType: typeof value,

package/dist/domain/services/normalize-jwt-payload.service.d.ts

@@ -4,12 +4,16 @@ import type { IJWTPayload } from "../ports";
  * --------------
  * Normaliza y valida un payload JWT según las reglas del dominio.
  *
- * - Entrada: unknown (claims verificados por infraestructura)
+ * - Entrada: unknown (claims verificados por infraestructura/plugin)
  * - Salida: IJWTPayload tipado y confiable
  *
  * Importante:
  * - NO verifica firma
  * - NO parsea JWT
  * - Define únicamente reglas de dominio
+ *
+ * Contrato:
+ * - `aud` se valida exclusivamente aquí vía `optionalAudience()`.
+ * - Cualquier error de `aud` debe provenir de `InvalidJwtPayloadError`.
  */
 export declare function normalizeJwtPayload(input: unknown): IJWTPayload;

package/dist/domain/services/normalize-jwt-payload.service.js

@@ -8,13 +8,17 @@ const helpers_1 = require("./helpers");
  * --------------
  * Normaliza y valida un payload JWT según las reglas del dominio.
  *
- * - Entrada: unknown (claims verificados por infraestructura)
+ * - Entrada: unknown (claims verificados por infraestructura/plugin)
  * - Salida: IJWTPayload tipado y confiable
  *
  * Importante:
  * - NO verifica firma
  * - NO parsea JWT
  * - Define únicamente reglas de dominio
+ *
+ * Contrato:
+ * - `aud` se valida exclusivamente aquí vía `optionalAudience()`.
+ * - Cualquier error de `aud` debe provenir de `InvalidJwtPayloadError`.
  */
 function normalizeJwtPayload(input) {
     if (input == null || typeof input !== "object") {
@@ -23,12 +27,20 @@ function normalizeJwtPayload(input) {
         });
     }
     const obj = input;
+    // Required
     const sub = (0, helpers_1.requireNonEmptyString)(obj.sub, "sub");
     const sid = (0, helpers_1.requireNonEmptyString)(obj.sid, "sid");
     const jti = (0, helpers_1.requireNonEmptyString)(obj.jti, "jti");
     const iat = (0, helpers_1.requireFiniteNumber)(obj.iat, "iat");
     const exp = (0, helpers_1.requireFiniteNumber)(obj.exp, "exp");
+    // Optional
     const iss = (0, helpers_1.optionalNonEmptyString)(obj.iss);
+    /**
+     * Canonical audience rule (core):
+     * - string | string[] | undefined
+     * - empty string or empty array => InvalidJwtPayloadError
+     * - array => dedupe + sort
+     */
     const aud = (0, helpers_1.optionalAudience)(obj.aud);
     const roles = (0, helpers_1.optionalRoles)(obj.roles);
     const customClaims = (0, helpers_1.optionalRecord)(obj.customClaims, "customClaims");

package/dist/index.d.ts

@@ -1,6 +1,17 @@
 export type { IAuthServiceContainer } from "./infrastructure/types";
 export { AuthServiceFactoryOptions } from "./application/types";
-export { normalizeJwtPayload } from "./domain/services/";
+/**
+ * Contrato público (JWT payload):
+ * - Los plugins devuelven payload verificado criptográficamente como unknown.
+ * - El core normaliza/valida y expone API estable para consumo externo.
+ */
+export { normalizeJwtPayload } from "./domain/services";
+/**
+ * Export explícito (contractual):
+ * Aunque ya se exporta vía `export * from "./domain/errors"`,
+ * se expone de forma directa para que el host/plugins lo consuman sin ambigüedad.
+ */
+export { InvalidJwtPayloadError } from "./domain/errors";
 export * from "./domain/ports";
 export * from "./domain/entities";
 export * from "./domain/object-values";
@@ -8,3 +19,4 @@ export * from "./domain/props";
 export * from "./domain/errors";
 export * from "./application/dtos";
 export * from "./application/facades";
+export * from "./shared";

package/dist/index.js

@@ -1,5 +1,4 @@
 "use strict";
-// export { BcryptPasswordHasher } from "./infrastructure/security";
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -15,23 +14,33 @@ 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 });
-exports.normalizeJwtPayload = void 0;
-var services_1 = require("./domain/services/");
+exports.InvalidJwtPayloadError = exports.normalizeJwtPayload = void 0;
+/**
+ * Contrato público (JWT payload):
+ * - Los plugins devuelven payload verificado criptográficamente como unknown.
+ * - El core normaliza/valida y expone API estable para consumo externo.
+ */
+var services_1 = require("./domain/services");
 Object.defineProperty(exports, "normalizeJwtPayload", { enumerable: true, get: function () { return services_1.normalizeJwtPayload; } });
+/**
+ * Export explícito (contractual):
+ * Aunque ya se exporta vía `export * from "./domain/errors"`,
+ * se expone de forma directa para que el host/plugins lo consuman sin ambigüedad.
+ */
+var errors_1 = require("./domain/errors");
+Object.defineProperty(exports, "InvalidJwtPayloadError", { enumerable: true, get: function () { return errors_1.InvalidJwtPayloadError; } });
 // Contratos (ports) + config
 __exportStar(require("./domain/ports"), exports);
 // Entities
 __exportStar(require("./domain/entities"), exports);
 // VOs
 __exportStar(require("./domain/object-values"), exports);
-// Contratos (ports) + config
+// Props (JWT generation inputs, etc.)
 __exportStar(require("./domain/props"), exports);
 // Errores públicos
 __exportStar(require("./domain/errors"), exports);
 // DTOs (solo types)
 __exportStar(require("./application/dtos"), exports);
-// Entry point principal
-// export * from "./application/factories";
+// Facades (entrypoint recomendado para hosts)
 __exportStar(require("./application/facades"), exports);
-// adapters útiles para tests/demos
-// export * from "./infrastructure/repositories/in-memory";
+__exportStar(require("./shared"), exports);

package/dist/shared/index.d.ts

@@ -1 +1,2 @@
 export * from "./utils";
+export * from "./jwt-plugin";

package/dist/shared/index.js

@@ -15,3 +15,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./utils"), exports);
+__exportStar(require("./jwt-plugin"), exports);

package/dist/shared/jwt-plugin/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./normalize-clock-skew-seconds";
+export * from "./normalize-default-expires-in";
+export * from "./read-expires-in";
+export * from "./read-custom-claims";
+export * from "./resolve-expires-in";
+export * from "./is-retryable-auth-code";

package/dist/shared/jwt-plugin/index.js

@@ -0,0 +1,22 @@
+"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("./normalize-clock-skew-seconds"), exports);
+__exportStar(require("./normalize-default-expires-in"), exports);
+__exportStar(require("./read-expires-in"), exports);
+__exportStar(require("./read-custom-claims"), exports);
+__exportStar(require("./resolve-expires-in"), exports);
+__exportStar(require("./is-retryable-auth-code"), exports);

package/dist/shared/jwt-plugin/is-retryable-auth-code.d.ts

@@ -0,0 +1,8 @@
+import type { AuthErrorCode } from "../../domain/errors";
+/**
+ * Determina si un error del core (por código) es "retryable".
+ *
+ * Responsabilidad única:
+ * - Decidir reintento SOLO por `code` (sin jose, sin message, sin heurísticas).
+ */
+export declare function isRetryableAuthCode(code: AuthErrorCode): boolean;

package/dist/shared/jwt-plugin/is-retryable-auth-code.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isRetryableAuthCode = isRetryableAuthCode;
+/**
+ * Determina si un error del core (por código) es "retryable".
+ *
+ * Responsabilidad única:
+ * - Decidir reintento SOLO por `code` (sin jose, sin message, sin heurísticas).
+ */
+function isRetryableAuthCode(code) {
+    return (code === "SIGNATURE_INVALID" ||
+        code === "ALGORITHM_UNSUPPORTED" ||
+        code === "KEY_MISMATCH" ||
+        code === "KEY_NOT_FOUND");
+}

package/dist/shared/jwt-plugin/normalize-clock-skew-seconds.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Normaliza clockSkewSeconds (en segundos).
+ *
+ * Responsabilidad única:
+ * - Aceptar únicamente números válidos
+ * - Convertir a entero (floor)
+ * - Asegurar >= 0
+ *
+ * Reglas:
+ * - no number / NaN => undefined
+ * - < 0 => 0
+ * - >== 0 => floor(value)
+ */
+export declare function normalizeClockSkewSeconds(value: number | undefined): number | undefined;

package/dist/shared/jwt-plugin/normalize-clock-skew-seconds.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeClockSkewSeconds = normalizeClockSkewSeconds;
+/**
+ * Normaliza clockSkewSeconds (en segundos).
+ *
+ * Responsabilidad única:
+ * - Aceptar únicamente números válidos
+ * - Convertir a entero (floor)
+ * - Asegurar >= 0
+ *
+ * Reglas:
+ * - no number / NaN => undefined
+ * - < 0 => 0
+ * - >== 0 => floor(value)
+ */
+function normalizeClockSkewSeconds(value) {
+    if (typeof value !== "number" || Number.isNaN(value))
+        return undefined;
+    if (value < 0)
+        return 0;
+    return Math.floor(value);
+}

package/dist/shared/jwt-plugin/normalize-default-expires-in.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Normaliza defaults de expiración usados por plugins JWT.
+ *
+ * Responsabilidad única:
+ * - Aceptar un shape compatible con { accessToken?, refreshToken? }
+ * - Trim de strings
+ * - Vacío => omitido
+ * - Si queda vacío => undefined
+ *
+ * Importante:
+ * - No depende de types de plugins para evitar acoplamiento.
+ */
+export declare function normalizeDefaultExpiresIn<T extends {
+    accessToken?: string;
+    refreshToken?: string;
+}>(value: T | undefined): T | undefined;

package/dist/shared/jwt-plugin/normalize-default-expires-in.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeDefaultExpiresIn = normalizeDefaultExpiresIn;
+/**
+ * Normaliza defaults de expiración usados por plugins JWT.
+ *
+ * Responsabilidad única:
+ * - Aceptar un shape compatible con { accessToken?, refreshToken? }
+ * - Trim de strings
+ * - Vacío => omitido
+ * - Si queda vacío => undefined
+ *
+ * Importante:
+ * - No depende de types de plugins para evitar acoplamiento.
+ */
+function normalizeDefaultExpiresIn(value) {
+    if (!value)
+        return undefined;
+    const out = {};
+    const accessToken = normalizeOptionalNonEmptyString(value.accessToken);
+    if (accessToken)
+        out.accessToken = accessToken;
+    const refreshToken = normalizeOptionalNonEmptyString(value.refreshToken);
+    if (refreshToken)
+        out.refreshToken = refreshToken;
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+/**
+ * Helper local (mínimo) para evitar dependencia circular en exports del core.
+ */
+function normalizeOptionalNonEmptyString(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const v = value.trim();
+    return v.length > 0 ? v : undefined;
+}

package/dist/shared/jwt-plugin/read-custom-claims.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Lee `customClaims` desde unknown.
+ *
+ * Responsabilidad única:
+ * - Aceptar únicamente un objeto plano serializable (Record<string, unknown>)
+ *
+ * Reglas:
+ * - undefined/null => undefined
+ * - arrays => undefined
+ * - objetos => Record<string, unknown>
+ */
+export declare function readCustomClaims(value: unknown): Record<string, unknown> | undefined;

package/dist/shared/jwt-plugin/read-custom-claims.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readCustomClaims = readCustomClaims;
+/**
+ * Lee `customClaims` desde unknown.
+ *
+ * Responsabilidad única:
+ * - Aceptar únicamente un objeto plano serializable (Record<string, unknown>)
+ *
+ * Reglas:
+ * - undefined/null => undefined
+ * - arrays => undefined
+ * - objetos => Record<string, unknown>
+ */
+function readCustomClaims(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    if (Array.isArray(value))
+        return undefined;
+    return value;
+}

package/dist/shared/jwt-plugin/read-expires-in.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Lee `expiresIn` desde unknown.
+ *
+ * Responsabilidad única:
+ * - Normalizar un valor desconocido a `string | undefined`
+ *
+ * Reglas:
+ * - no string => undefined
+ * - string vacío => undefined
+ * - string con espacios => trim()
+ */
+export declare function readExpiresIn(value: unknown): string | undefined;

package/dist/shared/jwt-plugin/read-expires-in.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readExpiresIn = readExpiresIn;
+/**
+ * Lee `expiresIn` desde unknown.
+ *
+ * Responsabilidad única:
+ * - Normalizar un valor desconocido a `string | undefined`
+ *
+ * Reglas:
+ * - no string => undefined
+ * - string vacío => undefined
+ * - string con espacios => trim()
+ */
+function readExpiresIn(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}

package/dist/shared/jwt-plugin/resolve-expires-in.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Resuelve `expiresIn` para generación de tokens (regla canónica para plugins).
+ *
+ * Responsabilidad única:
+ * - Aplicar precedencia:
+ *   1) expiresIn provisto por props
+ *   2) defaultExpiresIn del plugin por tokenKind
+ * - Si ninguno existe: lanzar InvalidJwtPayloadError (error canónico del core)
+ */
+export declare function resolveExpiresIn(args: {
+    expiresInFromProps?: string;
+    defaultExpiresIn?: string;
+    operation: "generateAccessToken" | "generateRefreshToken";
+}): string;

package/dist/shared/jwt-plugin/resolve-expires-in.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveExpiresIn = resolveExpiresIn;
+const errors_1 = require("../../domain/errors");
+/**
+ * Resuelve `expiresIn` para generación de tokens (regla canónica para plugins).
+ *
+ * Responsabilidad única:
+ * - Aplicar precedencia:
+ *   1) expiresIn provisto por props
+ *   2) defaultExpiresIn del plugin por tokenKind
+ * - Si ninguno existe: lanzar InvalidJwtPayloadError (error canónico del core)
+ */
+function resolveExpiresIn(args) {
+    const fromProps = normalizeOptionalNonEmptyString(args.expiresInFromProps);
+    if (fromProps)
+        return fromProps;
+    const fromDefault = normalizeOptionalNonEmptyString(args.defaultExpiresIn);
+    if (fromDefault)
+        return fromDefault;
+    throw new errors_1.InvalidJwtPayloadError("expiresIn is required", {
+        field: "expiresIn",
+        operation: args.operation,
+    });
+}
+function normalizeOptionalNonEmptyString(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const v = value.trim();
+    return v.length > 0 ? v : undefined;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jmlq/auth",
   "description": "JWT authentication package with clean architecture",
-  "version": "0.0.1-alpha.23",
+  "version": "0.0.1-alpha.25",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {