@kourouma/express-authkit 0.0.0-stage → 0.1.0-rc.1

package/src/adapters/express/index.js

@@ -0,0 +1,405 @@
+/**
+ * Express AuthKit — adaptateur Express.js (`@kourouma/express-authkit/express`).
+ *
+ * Ce module n’importe pas Express : il produit uniquement des middlewares
+ * standard `(req, res, next)`, compatibles avec Express 4 et 5.
+ *
+ * @module @kourouma/express-authkit/express
+ */
+
+import { assertImplements } from "../../core/contracts/assert-contract.js";
+import { normalizeAuthorizationRequirement, isAuthorized } from "../../core/authorization.js";
+import { AccessDeniedError, ConfigurationError, InvalidInputError } from "../../core/errors.js";
+import { MAX_IDENTIFIER_LENGTH } from "../../core/input-limits.js";
+import {
+  DEVELOPER_MESSAGES,
+  PUBLIC_MESSAGES,
+  fieldRequired,
+  fieldTooLong,
+  middlewareFactoryMisuse
+} from "../../core/messages.js";
+import { assertKnownKeys, assertPlainObject } from "../../config/assertions.js";
+import { extractBearerToken } from "./bearer-token.js";
+import { getClientErrorStatus, resolveClientError, sendClientError } from "./http-errors.js";
+
+/**
+ * @typedef {object} ExpressAuthOptions
+ * @property {string} [realm="api"] Domaine annoncé dans l’en-tête `WWW-Authenticate`.
+ */
+
+/**
+ * Règle d’accès pour `expressAuth.authorize()`. Un texte désigne un rôle.
+ * `check` reçoit l’utilisateur connecté et la requête Express.
+ *
+ * @typedef {string | {
+ *   anyRole?: string[],
+ *   allPermissions?: string[],
+ *   check?: (user: import("../../core/contracts/auth-principal.js").AuthPrincipal, req: import("express").Request) => boolean | Promise<boolean>
+ * }} ExpressAuthorizationRequirement
+ */
+
+/**
+ * @typedef {object} LoginHandlerOptions
+ * @property {string} [identifierField="identifier"] Champ du corps JSON contenant l’identifiant (par exemple `"email"`).
+ */
+
+/**
+ * @typedef {Readonly<{
+ *   authenticate: () => import("express").RequestHandler,
+ *   authorize: (requirement: ExpressAuthorizationRequirement) => import("express").RequestHandler,
+ *   login: (options?: LoginHandlerOptions) => import("express").RequestHandler,
+ *   refresh: () => import("express").RequestHandler,
+ *   logout: () => import("express").RequestHandler,
+ *   errorHandler: () => import("express").ErrorRequestHandler
+ * }>} ExpressAuth
+ */
+
+const DEFAULT_REALM = "api";
+/** Jeu de caractères limité : le domaine est écrit dans un en-tête de réponse. */
+const REALM_PATTERN = /^[A-Za-z0-9 ._-]{1,64}$/;
+const DEFAULT_IDENTIFIER_FIELD = "identifier";
+const FIELD_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
+
+/**
+ * Crée l’intégration Express pour un moteur construit avec `createAuthKit()`.
+ *
+ * @example
+ * const expressAuth = createExpressAuth(auth);
+ * app.post("/login", express.json(), expressAuth.login());
+ * app.get("/profile", expressAuth.authenticate(), (req, res) => {
+ *   res.json({ userId: req.auth.userId });
+ * });
+ *
+ * @param {import("../../factory/create-auth-kit.js").AuthKit} auth
+ * @param {ExpressAuthOptions} [options]
+ * @returns {ExpressAuth}
+ */
+export function createExpressAuth(auth, options = {}) {
+  assertImplements(auth, "AuthKit", ["login", "verifyAccessToken"]);
+  assertPlainObject(options, "createExpressAuth(auth, options)");
+  assertKnownKeys(options, ["realm"], "createExpressAuth(auth, options)");
+
+  const realm = options.realm ?? DEFAULT_REALM;
+
+  /**
+   * Requêtes authentifiées par cette instance. `authorize()` ne fait confiance
+   * qu’à elles : une valeur de `req.auth` posée par un autre middleware est
+   * ignorée et ne peut pas usurper une identité.
+   *
+   * @type {WeakMap<object, import("../../core/contracts/auth-principal.js").AuthPrincipal>}
+   */
+  const authenticatedRequests = new WeakMap();
+  if (typeof realm !== "string" || !REALM_PATTERN.test(realm)) {
+    throw new ConfigurationError(DEVELOPER_MESSAGES.invalidRealm);
+  }
+
+  /**
+   * Middleware exigeant un en-tête `Authorization: Bearer <token>` valide.
+   * En cas de succès, le principal figé est disponible dans `req.auth`.
+   * Les échecs d’authentification reçoivent une réponse JSON 401 ; les erreurs
+   * inattendues sont transmises à `next(error)`.
+   *
+   * @returns {import("express").RequestHandler}
+   * @param {...unknown} unexpectedArguments Doit rester vide (détecte l’oubli des parenthèses).
+   */
+  function authenticate(...unexpectedArguments) {
+    assertCalledAsFactory("authenticate", unexpectedArguments);
+    return async function authenticateRequest(req, res, next) {
+      let principal;
+      try {
+        const token = extractBearerToken(req.headers.authorization);
+        principal = await auth.verifyAccessToken(token);
+      } catch (error) {
+        const status = getClientErrorStatus(error);
+        if (status !== undefined) {
+          sendClientError(res, /** @type {import("../../core/errors.js").AuthKitError} */ (error), status, realm);
+          return;
+        }
+        next(error);
+        return;
+      }
+      setPrincipal(req, principal);
+      next();
+    };
+  }
+
+  /**
+   * Protège une route par rôle, permission ou règle personnalisée. Authentifie
+   * aussi la requête si `authenticate()` n’a pas été appelé avant : une seule
+   * ligne suffit.
+   *
+   * Réponses : 401 si l’utilisateur n’est pas connecté, 403 (`ACCESS_DENIED`)
+   * s’il est connecté mais n’a pas les droits.
+   *
+   * @example
+   * app.get("/admin", expressAuth.authorize("admin"), handler);
+   * app.post("/orders", expressAuth.authorize({ allPermissions: ["orders:write"] }), handler);
+   * app.put("/users/:id", expressAuth.authorize({ check: (user, req) => user.userId === req.params.id }), handler);
+   *
+   * @param {ExpressAuthorizationRequirement} requirement
+   * @param {...unknown} unexpectedArguments Doit rester vide (détecte l’oubli des parenthèses).
+   * @returns {import("express").RequestHandler}
+   */
+  function authorize(requirement, ...unexpectedArguments) {
+    assertCalledAsFactory("authorize", unexpectedArguments);
+    // Validée une fois, au démarrage : une règle invalide arrête l’application.
+    const rules = normalizeAuthorizationRequirement(requirement);
+
+    return async function authorizeRequest(req, res, next) {
+      try {
+        const principal = await resolvePrincipal(req);
+        if (!(await isAuthorized(principal, rules, req))) {
+          throw new AccessDeniedError();
+        }
+      } catch (error) {
+        const status = getClientErrorStatus(error);
+        if (status !== undefined) {
+          sendClientError(res, /** @type {import("../../core/errors.js").AuthKitError} */ (error), status, realm);
+          return;
+        }
+        next(error);
+        return;
+      }
+      next();
+    };
+  }
+
+  /**
+   * Réutilise l’utilisateur déjà authentifié par `authenticate()` sur cette
+   * requête, ou authentifie la requête maintenant.
+   *
+   * @param {import("express").Request} req
+   * @returns {Promise<import("../../core/contracts/auth-principal.js").AuthPrincipal>}
+   */
+  async function resolvePrincipal(req) {
+    const existing = authenticatedRequests.get(req);
+    if (existing !== undefined) {
+      return existing;
+    }
+    const principal = await auth.verifyAccessToken(extractBearerToken(req.headers.authorization));
+    setPrincipal(req, principal);
+    return principal;
+  }
+
+  /**
+   * @param {import("express").Request} req
+   * @param {import("../../core/contracts/auth-principal.js").AuthPrincipal} principal
+   */
+  function setPrincipal(req, principal) {
+    authenticatedRequests.set(req, principal);
+    /** @type {import("express").Request & { auth?: import("../../core/contracts/auth-principal.js").AuthPrincipal }} */ (
+      req
+    ).auth = principal;
+  }
+
+  /**
+   * Gestionnaire de connexion prêt à l’emploi. Ce n’est pas une route
+   * automatique : l’application choisit l’URL sur laquelle elle le monte.
+   *
+   * Lit `password` et l’identifiant (champ `identifier` par défaut) dans le
+   * corps JSON, puis répond `{ accessToken, tokenType, expiresIn }`.
+   * Les échecs reçoivent une réponse JSON 400/401 ; les erreurs inattendues
+   * sont transmises à `next(error)`.
+   *
+   * @example
+   * app.post("/login", express.json(), expressAuth.login());
+   * app.post("/login", express.json(), expressAuth.login({ identifierField: "email" }));
+   *
+   * @param {LoginHandlerOptions} [loginOptions]
+   * @returns {import("express").RequestHandler}
+   * @param {...unknown} unexpectedArguments Doit rester vide (détecte l’oubli des parenthèses).
+   */
+  function login(loginOptions = {}, ...unexpectedArguments) {
+    assertCalledAsFactory("login", unexpectedArguments);
+    const identifierField = resolveIdentifierField(loginOptions);
+
+    return async function loginRequest(req, res, next) {
+      let result;
+      try {
+        const body = readJsonBody(req);
+        // Object.hasOwn évite de lire une propriété héritée du prototype.
+        const identifier = Object.hasOwn(body, identifierField) ? body[identifierField] : undefined;
+        const password = Object.hasOwn(body, "password") ? body.password : undefined;
+        // Vérifié ici pour que le message cite le vrai nom du champ (« email »…).
+        assertIdentifierField(identifier, identifierField);
+        // Le type exact du mot de passe est vérifié par auth.login().
+        result = await auth.login({ identifier, password: /** @type {string} */ (password) });
+      } catch (error) {
+        const status = getClientErrorStatus(error);
+        if (status !== undefined) {
+          sendClientError(res, /** @type {import("../../core/errors.js").AuthKitError} */ (error), status, realm);
+          return;
+        }
+        next(error);
+        return;
+      }
+      sendSession(res, result);
+    };
+  }
+
+  /**
+   * Gestionnaire de rafraîchissement : lit `refreshToken` dans le corps JSON
+   * et répond avec une nouvelle paire de jetons (l’ancien jeton est invalidé).
+   * Nécessite l’option `refreshTokens` de `createAuthKit()`.
+   *
+   * @example
+   * app.post("/auth/refresh", express.json(), expressAuth.refresh());
+   *
+   * @returns {import("express").RequestHandler}
+   * @param {...unknown} unexpectedArguments Doit rester vide (détecte l’oubli des parenthèses).
+   */
+  function refresh(...unexpectedArguments) {
+    assertCalledAsFactory("refresh", unexpectedArguments);
+    return handleJson(async (body, res) => {
+      sendSession(res, await auth.refresh(readRefreshToken(body)));
+    });
+  }
+
+  /**
+   * Gestionnaire de déconnexion : lit `refreshToken` dans le corps JSON,
+   * révoque la session et répond 204 (sans contenu). Répond 204 aussi si la
+   * session était déjà révoquée : se déconnecter deux fois n’est pas une erreur.
+   *
+   * @example
+   * app.post("/auth/logout", express.json(), expressAuth.logout());
+   *
+   * @returns {import("express").RequestHandler}
+   * @param {...unknown} unexpectedArguments Doit rester vide (détecte l’oubli des parenthèses).
+   */
+  function logout(...unexpectedArguments) {
+    assertCalledAsFactory("logout", unexpectedArguments);
+    return handleJson(async (body, res) => {
+      await auth.logout(readRefreshToken(body));
+      res.set("Cache-Control", "no-store");
+      res.status(204).end();
+    });
+  }
+
+  /**
+   * Enveloppe commune des gestionnaires qui lisent un corps JSON : les
+   * erreurs client reçoivent une réponse JSON, les autres vont à `next()`.
+   *
+   * @param {(body: Record<string, unknown>, res: import("express").Response) => Promise<void>} handle
+   * @returns {import("express").RequestHandler}
+   */
+  function handleJson(handle) {
+    return async function jsonRequest(req, res, next) {
+      try {
+        await handle(readJsonBody(req), res);
+      } catch (error) {
+        const status = getClientErrorStatus(error);
+        if (status !== undefined && !res.headersSent) {
+          sendClientError(res, /** @type {import("../../core/errors.js").AuthKitError} */ (error), status, realm);
+          return;
+        }
+        next(error);
+      }
+    };
+  }
+
+  /**
+   * Middleware d’erreur qui convertit les erreurs d’authentification client,
+   * par exemple celles de `auth.login()`, en réponses JSON. Les autres erreurs
+   * sont transmises sans modification au gestionnaire suivant.
+   *
+   * @returns {import("express").ErrorRequestHandler}
+   * @param {...unknown} unexpectedArguments Doit rester vide (détecte l’oubli des parenthèses).
+   */
+  function errorHandler(...unexpectedArguments) {
+    assertCalledAsFactory("errorHandler", unexpectedArguments);
+    return function authErrorHandler(error, req, res, next) {
+      const clientError = resolveClientError(error);
+      if (clientError === undefined || res.headersSent) {
+        next(error);
+        return;
+      }
+      sendClientError(res, clientError.error, clientError.status, realm);
+    };
+  }
+
+  return Object.freeze({ authenticate, authorize, login, refresh, logout, errorHandler });
+}
+
+/**
+ * @param {unknown} loginOptions
+ * @returns {string}
+ */
+function resolveIdentifierField(loginOptions) {
+  assertPlainObject(loginOptions, "expressAuth.login(options)");
+  assertKnownKeys(loginOptions, ["identifierField"], "expressAuth.login(options)");
+  const field = loginOptions.identifierField ?? DEFAULT_IDENTIFIER_FIELD;
+  if (typeof field !== "string" || !FIELD_NAME_PATTERN.test(field)) {
+    throw new ConfigurationError(DEVELOPER_MESSAGES.invalidIdentifierField);
+  }
+  return field;
+}
+
+/**
+ * Détecte l’oubli des parenthèses (`expressAuth.authenticate` au lieu de
+ * `expressAuth.authenticate()`). Sans ce contrôle, Express appellerait la
+ * fabrique comme un middleware et la requête resterait bloquée sans réponse.
+ *
+ * @param {string} method
+ * @param {unknown[]} unexpectedArguments
+ */
+function assertCalledAsFactory(method, unexpectedArguments) {
+  if (unexpectedArguments.length > 0) {
+    throw new ConfigurationError(middlewareFactoryMisuse(method));
+  }
+}
+
+/**
+ * @param {unknown} identifier
+ * @param {string} field
+ * @returns {asserts identifier is string}
+ */
+function assertIdentifierField(identifier, field) {
+  if (typeof identifier !== "string" || identifier.length === 0) {
+    throw new InvalidInputError(fieldRequired(field));
+  }
+  if (identifier.length > MAX_IDENTIFIER_LENGTH) {
+    throw new InvalidInputError(fieldTooLong(field, MAX_IDENTIFIER_LENGTH));
+  }
+}
+
+/**
+ * @param {import("express").Request} req
+ * @returns {Record<string, unknown>}
+ * @throws {InvalidInputError}
+ */
+function readJsonBody(req) {
+  const body = req.body;
+  if (body === undefined || body === null || typeof body !== "object") {
+    throw new InvalidInputError(PUBLIC_MESSAGES.missingJsonBody);
+  }
+  return body;
+}
+
+/**
+ * Lit le champ sans le valider : auth.refresh() et auth.logout() vérifient
+ * eux-mêmes que c’est un texte non vide.
+ *
+ * @param {Record<string, unknown>} body
+ * @returns {string} Type annoncé ; la valeur réelle est validée par le Core.
+ */
+function readRefreshToken(body) {
+  const value = Object.hasOwn(body, "refreshToken") ? body.refreshToken : undefined;
+  return /** @type {string} */ (value);
+}
+
+/**
+ * Envoie une paire de jetons. Le principal interne n’est pas inclus.
+ *
+ * @param {import("express").Response} res
+ * @param {import("../../core/contracts/authentication-service.js").LoginResult} result
+ */
+function sendSession(res, result) {
+  /** @type {{ accessToken: string, tokenType: string, expiresIn: number, refreshToken?: string, refreshExpiresIn?: number }} */
+  const body = { accessToken: result.accessToken, tokenType: result.tokenType, expiresIn: result.expiresIn };
+  if (result.refreshToken !== undefined) {
+    body.refreshToken = result.refreshToken;
+    body.refreshExpiresIn = result.refreshExpiresIn;
+  }
+  res.set("Cache-Control", "no-store");
+  res.json(body);
+}

package/src/config/assertions.js

@@ -0,0 +1,80 @@
+import { ConfigurationError } from "../core/errors.js";
+import {
+  notPlainObject,
+  optionIntegerRange,
+  optionRequiredString,
+  optionTooLong,
+  unknownOptions
+} from "../core/messages.js";
+
+/**
+ * Petites fonctions de vérification partagées par les validateurs de configuration.
+ *
+ * @module config/assertions
+ */
+
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+export function isPlainObject(value) {
+  if (value === null || typeof value !== "object") {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} name
+ * @returns {asserts value is Record<string, unknown>}
+ */
+export function assertPlainObject(value, name) {
+  if (!isPlainObject(value)) {
+    throw new ConfigurationError(notPlainObject(name));
+  }
+}
+
+/**
+ * Refuse les clés inconnues afin qu’une faute de frappe (par exemple
+ * `expiresIn` au lieu de `expiresInSeconds`) ne passe pas inaperçue.
+ *
+ * @param {Record<string, unknown>} object
+ * @param {readonly string[]} allowedKeys
+ * @param {string} name
+ */
+export function assertKnownKeys(object, allowedKeys, name) {
+  const unknown = Object.keys(object).filter((key) => !allowedKeys.includes(key));
+  if (unknown.length > 0) {
+    throw new ConfigurationError(unknownOptions(name, unknown, allowedKeys));
+  }
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} name
+ * @param {number} maxLength
+ * @returns {asserts value is string}
+ */
+export function assertNonEmptyString(value, name, maxLength) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new ConfigurationError(optionRequiredString(name));
+  }
+  if (value.length > maxLength) {
+    throw new ConfigurationError(optionTooLong(name, maxLength));
+  }
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} name
+ * @param {number} min
+ * @param {number} max
+ * @returns {asserts value is number}
+ */
+export function assertIntegerInRange(value, name, min, max) {
+  if (typeof value !== "number" || !Number.isInteger(value) || value < min || value > max) {
+    throw new ConfigurationError(optionIntegerRange(name, min, max));
+  }
+}

package/src/config/auth-kit-options.js

@@ -0,0 +1,61 @@
+import { ConfigurationError } from "../core/errors.js";
+import { DEVELOPER_MESSAGES } from "../core/messages.js";
+import { assertKnownKeys, assertPlainObject } from "./assertions.js";
+
+/**
+ * Fournisseurs qui remplacent les implémentations intégrées.
+ *
+ * @typedef {object} ProviderOverrides
+ * @property {import("../core/contracts/password-provider.js").PasswordProvider} [password]
+ *   Remplace le fournisseur Argon2id. Les options `password` doivent alors être absentes.
+ * @property {import("../core/contracts/token-provider.js").TokenProvider} [token]
+ *   Remplace le fournisseur JWT. Les options `jwt` doivent alors être absentes.
+ */
+
+/**
+ * Options acceptées par `createAuthKit()`.
+ *
+ * @typedef {object} AuthKitOptions
+ * @property {import("../core/contracts/user-repository.js").UserRepository} users Dépôt d’utilisateurs de l’application.
+ * @property {import("./jwt-options.js").JwtOptions} [jwt] Obligatoire sans `providers.token`.
+ * @property {import("./password-options.js").PasswordOptions} [password] Paramètres de coût Argon2id.
+ * @property {import("./refresh-token-options.js").RefreshTokenOptions} [refreshTokens]
+ *   Active les jetons de rafraîchissement (désactivés par défaut).
+ * @property {ProviderOverrides} [providers] Implémentations personnalisées des fournisseurs.
+ */
+
+const ALLOWED_KEYS = Object.freeze(["users", "jwt", "password", "refreshTokens", "providers"]);
+const ALLOWED_PROVIDER_KEYS = Object.freeze(["password", "token"]);
+
+/**
+ * Valide la structure principale des options. Les valeurs imbriquées sont
+ * validées par leurs résolveurs et leurs vérifications de contrat dédiés.
+ *
+ * @param {unknown} options
+ * @returns {AuthKitOptions}
+ * @throws {ConfigurationError}
+ */
+export function validateAuthKitOptions(options) {
+  assertPlainObject(options, "createAuthKit(options)");
+  assertKnownKeys(options, ALLOWED_KEYS, "createAuthKit(options)");
+
+  if (options.users === undefined || options.users === null) {
+    throw new ConfigurationError(DEVELOPER_MESSAGES.usersRequired);
+  }
+
+  const providers = options.providers ?? {};
+  assertPlainObject(providers, "providers");
+  assertKnownKeys(providers, ALLOWED_PROVIDER_KEYS, "providers");
+
+  if (providers.token !== undefined && options.jwt !== undefined) {
+    throw new ConfigurationError(DEVELOPER_MESSAGES.jwtOrTokenProvider);
+  }
+  if (providers.token === undefined && options.jwt === undefined) {
+    throw new ConfigurationError(DEVELOPER_MESSAGES.jwtRequired);
+  }
+  if (providers.password !== undefined && options.password !== undefined) {
+    throw new ConfigurationError(DEVELOPER_MESSAGES.passwordOrPasswordProvider);
+  }
+
+  return /** @type {AuthKitOptions} */ (options);
+}

package/src/config/defaults.js

@@ -0,0 +1,66 @@
+/**
+ * Valeurs sûres par défaut et limites acceptées.
+ *
+ * @module config/defaults
+ */
+
+/**
+ * Algorithmes JWT acceptés pour une signature par secret partagé, avec la taille
+ * minimale de clé exigée par la RFC 7518 §3.2.
+ *
+ * @type {Readonly<Record<string, number>>}
+ */
+export const JWT_ALGORITHM_MIN_KEY_BYTES = Object.freeze({
+  HS256: 32,
+  HS384: 48,
+  HS512: 64
+});
+
+export const JWT_DEFAULTS = Object.freeze({
+  algorithm: "HS256",
+  /** 15 minutes : une courte durée réduit l’impact d’un jeton divulgué. */
+  expiresInSeconds: 900,
+  clockToleranceSeconds: 0
+});
+
+export const JWT_LIMITS = Object.freeze({
+  minExpiresInSeconds: 30,
+  /** Les jetons d’accès ne sont pas révocables : une durée de plus d’un jour est refusée. */
+  maxExpiresInSeconds: 86_400,
+  maxClockToleranceSeconds: 60,
+  maxClaimLength: 256
+});
+
+/**
+ * Valeurs Argon2id par défaut : « deuxième option recommandée » de la RFC 9106
+ * (64 Mio, t=3, p=4), plus forte que le minimum OWASP.
+ */
+export const ARGON2_DEFAULTS = Object.freeze({
+  memoryCost: 65_536,
+  timeCost: 3,
+  parallelism: 4
+});
+
+/**
+ * Seuils en dessous desquels Argon2id est refusé : au moins 19 Mio de mémoire
+ * et 2 itérations, selon OWASP.
+ */
+export const ARGON2_LIMITS = Object.freeze({
+  minMemoryCost: 19_456,
+  maxMemoryCost: 4_194_304,
+  minTimeCost: 2,
+  maxTimeCost: 20,
+  minParallelism: 1,
+  maxParallelism: 16
+});
+
+export const REFRESH_TOKEN_DEFAULTS = Object.freeze({
+  /** 14 jours : l’utilisateur reste connecté s’il revient au moins toutes les deux semaines. */
+  expiresInSeconds: 1_209_600
+});
+
+export const REFRESH_TOKEN_LIMITS = Object.freeze({
+  minExpiresInSeconds: 300,
+  /** 90 jours au plus : au-delà, une session oubliée reste exploitable trop longtemps. */
+  maxExpiresInSeconds: 7_776_000
+});

package/src/config/jwt-options.js

@@ -0,0 +1,86 @@
+import { ConfigurationError } from "../core/errors.js";
+import { unsupportedAlgorithm } from "../core/messages.js";
+import {
+  assertIntegerInRange,
+  assertKnownKeys,
+  assertNonEmptyString,
+  assertPlainObject
+} from "./assertions.js";
+import { JWT_ALGORITHM_MIN_KEY_BYTES, JWT_DEFAULTS, JWT_LIMITS } from "./defaults.js";
+import { assertStrongSecret } from "./secret-strength.js";
+
+/**
+ * Options acceptées dans `createAuthKit({ jwt })`.
+ *
+ * @typedef {object} JwtOptions
+ * @property {string | Uint8Array | undefined} secret Clé de signature partagée produite par un générateur sûr (≥ 32 octets pour HS256). Une valeur absente (par exemple une variable d’environnement non définie) est acceptée par les types mais arrête createAuthKit() avec un message clair.
+ * @property {string} issuer Valeur de la revendication `iss`, contrôlée à la vérification.
+ * @property {string} audience Valeur de la revendication `aud`, contrôlée à la vérification.
+ * @property {number} [expiresInSeconds=900] Durée de vie du jeton (30 à 86 400 secondes).
+ * @property {"HS256" | "HS384" | "HS512"} [algorithm="HS256"] Seul algorithme accepté à la vérification.
+ * @property {number} [clockToleranceSeconds=0] Décalage d’horloge accepté entre instances (0 à 60 secondes).
+ */
+
+/**
+ * Paramètres JWT validés. Le secret est converti une seule fois en octets.
+ *
+ * @typedef {Readonly<{
+ *   key: Uint8Array,
+ *   issuer: string,
+ *   audience: string,
+ *   expiresInSeconds: number,
+ *   algorithm: string,
+ *   clockToleranceSeconds: number
+ * }>} ResolvedJwtOptions
+ */
+
+const ALLOWED_KEYS = Object.freeze([
+  "secret",
+  "issuer",
+  "audience",
+  "expiresInSeconds",
+  "algorithm",
+  "clockToleranceSeconds"
+]);
+
+/**
+ * Valide les options JWT, applique des valeurs sûres et refuse les valeurs dangereuses.
+ *
+ * @param {unknown} options
+ * @returns {ResolvedJwtOptions}
+ * @throws {ConfigurationError}
+ */
+export function resolveJwtOptions(options) {
+  assertPlainObject(options, "jwt");
+  assertKnownKeys(options, ALLOWED_KEYS, "jwt");
+
+  const algorithm = options.algorithm ?? JWT_DEFAULTS.algorithm;
+  if (typeof algorithm !== "string" || !Object.hasOwn(JWT_ALGORITHM_MIN_KEY_BYTES, algorithm)) {
+    throw new ConfigurationError(unsupportedAlgorithm(Object.keys(JWT_ALGORITHM_MIN_KEY_BYTES)));
+  }
+
+  const key = assertStrongSecret(options.secret, JWT_ALGORITHM_MIN_KEY_BYTES[algorithm]);
+
+  assertNonEmptyString(options.issuer, "jwt.issuer", JWT_LIMITS.maxClaimLength);
+  assertNonEmptyString(options.audience, "jwt.audience", JWT_LIMITS.maxClaimLength);
+
+  const expiresInSeconds = options.expiresInSeconds ?? JWT_DEFAULTS.expiresInSeconds;
+  assertIntegerInRange(
+    expiresInSeconds,
+    "jwt.expiresInSeconds",
+    JWT_LIMITS.minExpiresInSeconds,
+    JWT_LIMITS.maxExpiresInSeconds
+  );
+
+  const clockToleranceSeconds = options.clockToleranceSeconds ?? JWT_DEFAULTS.clockToleranceSeconds;
+  assertIntegerInRange(clockToleranceSeconds, "jwt.clockToleranceSeconds", 0, JWT_LIMITS.maxClockToleranceSeconds);
+
+  return Object.freeze({
+    key,
+    issuer: options.issuer,
+    audience: options.audience,
+    expiresInSeconds,
+    algorithm,
+    clockToleranceSeconds
+  });
+}