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

package/src/core/contracts/auth-principal.js

@@ -0,0 +1,36 @@
+/**
+ * Identité validée d’un utilisateur authentifié.
+ *
+ * Le principal ne contient que des données non sensibles issues d’un jeton
+ * vérifié. Il ne contient jamais le hash du mot de passe ni le jeton brut.
+ * Il est figé pour empêcher les middlewares suivants de le modifier.
+ *
+ * Les rôles et permissions viennent du repository, relu à chaque requête :
+ * ils ne sont jamais écrits dans le jeton, et un changement de rôle
+ * s’applique immédiatement.
+ *
+ * @typedef {Readonly<{
+ *   userId: string,
+ *   tokenId: string,
+ *   issuedAt: number,
+ *   expiresAt: number,
+ *   roles: readonly string[],
+ *   permissions: readonly string[]
+ * }>} AuthPrincipal
+ */
+
+/**
+ * @param {import("./token-provider.js").VerifiedTokenClaims | import("./token-provider.js").IssuedToken} claims
+ * @param {{ id: string, roles: readonly string[], permissions: readonly string[] }} user
+ * @returns {AuthPrincipal}
+ */
+export function createAuthPrincipal(claims, user) {
+  return Object.freeze({
+    userId: user.id,
+    tokenId: claims.tokenId,
+    issuedAt: claims.issuedAt,
+    expiresAt: claims.expiresAt,
+    roles: user.roles,
+    permissions: user.permissions
+  });
+}

package/src/core/contracts/authentication-service.js

@@ -0,0 +1,44 @@
+/**
+ * Identifiants transmis par un client.
+ *
+ * @typedef {object} LoginCredentials
+ * @property {string} identifier Identifiant de connexion (e-mail, nom d’utilisateur…).
+ * @property {string} password Mot de passe en clair. Il n’est ni journalisé ni stocké.
+ */
+
+/**
+ * Résultat d’une connexion réussie, envoyable tel quel dans une réponse HTTP.
+ *
+ * @typedef {object} LoginResult
+ * @property {string} accessToken Jeton d’accès JWT signé.
+ * @property {"Bearer"} tokenType Toujours `"Bearer"`.
+ * @property {number} expiresIn Durée de vie du jeton, en secondes.
+ * @property {import("./auth-principal.js").AuthPrincipal} principal Identité authentifiée.
+ * @property {string} [refreshToken] Jeton de rafraîchissement (présent si `refreshTokens` est activé).
+ * @property {number} [refreshExpiresIn] Durée de vie du jeton de rafraîchissement, en secondes.
+ */
+
+/**
+ * Forme acceptée pour un identifiant d’utilisateur : texte, entier, BigInt ou ObjectId MongoDB.
+ *
+ * @typedef {string | number | bigint | { toHexString(): string }} UserIdInput
+ */
+
+/**
+ * Cas d’usage d’authentification indépendants du framework.
+ *
+ * @typedef {object} AuthenticationService
+ * @property {(credentials: LoginCredentials) => Promise<LoginResult>} login
+ *   Authentifie un utilisateur. Renvoie `InvalidCredentialsError` pour un
+ *   utilisateur inconnu, un mauvais mot de passe ou un compte désactivé.
+ * @property {(refreshToken: string) => Promise<LoginResult>} refresh
+ *   Échange un jeton de rafraîchissement contre une nouvelle paire de jetons (rotation).
+ * @property {(refreshToken: string) => Promise<void>} logout
+ *   Révoque la session liée au jeton de rafraîchissement.
+ * @property {(userId: UserIdInput) => Promise<void>} revokeAllSessions
+ *   Révoque toutes les sessions d’un utilisateur.
+ * @property {(token: string) => Promise<import("./auth-principal.js").AuthPrincipal>} verifyAccessToken
+ *   Vérifie un jeton et contrôle que son utilisateur existe et est toujours actif.
+ */
+
+export {};

package/src/core/contracts/password-provider.js

@@ -0,0 +1,27 @@
+import { assertImplements } from "./assert-contract.js";
+
+/**
+ * Contrat de hachage des mots de passe.
+ *
+ * Les implémentations doivent employer un algorithme éprouvé (le fournisseur
+ * par défaut utilise Argon2id) et ne jamais programmer la cryptographie elles-mêmes.
+ *
+ * @typedef {object} PasswordProvider
+ * @property {(password: string) => Promise<string>} hash
+ *   Renvoie un hash autonome (algorithme, paramètres et sel encodés dans la chaîne).
+ * @property {(password: string, hash: string) => Promise<boolean>} verify
+ *   Renvoie `true` si le mot de passe correspond. La comparaison doit être en
+ *   temps constant et lever `InvalidPasswordHashError` si `hash` est illisible.
+ */
+
+/** @type {readonly string[]} */
+export const PASSWORD_PROVIDER_METHODS = Object.freeze(["hash", "verify"]);
+
+/**
+ * @param {unknown} provider
+ * @returns {asserts provider is PasswordProvider}
+ * @throws {import("../errors.js").ContractViolationError}
+ */
+export function assertPasswordProvider(provider) {
+  assertImplements(provider, "PasswordProvider", PASSWORD_PROVIDER_METHODS);
+}

package/src/core/contracts/refresh-token-store.js

@@ -0,0 +1,80 @@
+import { ContractViolationError } from "../errors.js";
+import { DEVELOPER_MESSAGES } from "../messages.js";
+import { assertImplements } from "./assert-contract.js";
+
+/**
+ * Jeton de rafraîchissement tel qu’il est enregistré. Le jeton lui-même n’est
+ * jamais stocké : seule son empreinte SHA-256 l’est. Une fuite de la base ne
+ * donne donc aucun jeton utilisable.
+ *
+ * @typedef {object} RefreshTokenRecord
+ * @property {string} tokenHash Empreinte SHA-256 du jeton (64 caractères hexadécimaux). Clé unique.
+ * @property {string} userId Identifiant de l’utilisateur.
+ * @property {string} familyId Identifiant de la « famille » : tous les jetons issus d’une même connexion.
+ * @property {number} expiresAt Date d’expiration, en secondes depuis l’époque Unix.
+ */
+
+/**
+ * Résultat de {@link RefreshTokenStore.consume}.
+ *
+ * @typedef {object} ConsumedRefreshToken
+ * @property {string} userId
+ * @property {string} familyId
+ * @property {number} expiresAt Secondes depuis l’époque Unix.
+ * @property {boolean} alreadyUsed `true` si le jeton avait déjà été consommé avant cet appel.
+ */
+
+/**
+ * Stockage des jetons de rafraîchissement, implémenté par l’application.
+ *
+ * @typedef {object} RefreshTokenStore
+ * @property {(record: RefreshTokenRecord) => Promise<void>} save
+ *   Enregistre un nouveau jeton.
+ * @property {(tokenHash: string) => Promise<ConsumedRefreshToken | null | undefined>} consume
+ *   Marque le jeton comme utilisé et renvoie son état précédent, ou `null` s’il
+ *   est inconnu. Doit être **atomique** : si deux requêtes consomment le même
+ *   jeton en même temps, une seule doit obtenir `alreadyUsed: false`.
+ *   Les jetons utilisés doivent être conservés jusqu’à leur expiration, pour
+ *   détecter une réutilisation.
+ * @property {(familyId: string) => Promise<void>} revokeFamily
+ *   Supprime (ou invalide) tous les jetons d’une famille.
+ * @property {(userId: string) => Promise<void>} revokeUser
+ *   Supprime (ou invalide) tous les jetons d’un utilisateur.
+ */
+
+/** @type {readonly string[]} */
+export const REFRESH_TOKEN_STORE_METHODS = Object.freeze(["save", "consume", "revokeFamily", "revokeUser"]);
+
+/**
+ * @param {unknown} store
+ * @returns {asserts store is RefreshTokenStore}
+ * @throws {ContractViolationError}
+ */
+export function assertRefreshTokenStore(store) {
+  assertImplements(store, "RefreshTokenStore", REFRESH_TOKEN_STORE_METHODS);
+}
+
+/**
+ * Valide à l’exécution la valeur renvoyée par `consume()`.
+ *
+ * @param {unknown} result
+ * @returns {ConsumedRefreshToken | null}
+ * @throws {ContractViolationError}
+ */
+export function normalizeConsumedRefreshToken(result) {
+  if (result === null || result === undefined) {
+    return null;
+  }
+  const { userId, familyId, expiresAt, alreadyUsed } = /** @type {Record<string, unknown>} */ (result);
+  const isValid =
+    typeof userId === "string" &&
+    userId.length > 0 &&
+    typeof familyId === "string" &&
+    familyId.length > 0 &&
+    Number.isFinite(expiresAt) &&
+    typeof alreadyUsed === "boolean";
+  if (!isValid) {
+    throw new ContractViolationError(DEVELOPER_MESSAGES.refreshStoreConsumeInvalid);
+  }
+  return { userId, familyId, expiresAt: /** @type {number} */ (expiresAt), alreadyUsed };
+}

package/src/core/contracts/token-provider.js

@@ -0,0 +1,45 @@
+import { assertImplements } from "./assert-contract.js";
+
+/**
+ * Résultat de l’émission d’un jeton d’accès.
+ *
+ * @typedef {object} IssuedToken
+ * @property {string} token Jeton sérialisé.
+ * @property {string} tokenId Identifiant unique du jeton (`jti`).
+ * @property {number} issuedAt Date d’émission, en secondes depuis l’époque Unix.
+ * @property {number} expiresAt Date d’expiration, en secondes depuis l’époque Unix.
+ */
+
+/**
+ * Revendications extraites d’un jeton d’accès vérifié.
+ *
+ * @typedef {object} VerifiedTokenClaims
+ * @property {string} subject Identifiant utilisateur (`sub`).
+ * @property {string} tokenId Identifiant du jeton (`jti`).
+ * @property {number} issuedAt `iat`, en secondes depuis l’époque Unix.
+ * @property {number} expiresAt `exp`, en secondes depuis l’époque Unix.
+ */
+
+/**
+ * Contrat de gestion des jetons d’accès.
+ *
+ * `verify()` doit contrôler la signature, les algorithmes autorisés, l’expiration,
+ * l’émetteur, l’audience et le sujet. Elle lève `TokenExpiredError` pour un jeton
+ * expiré et `InvalidTokenError` pour tout autre rejet.
+ *
+ * @typedef {object} TokenProvider
+ * @property {(input: { subject: string }) => Promise<IssuedToken>} issue
+ * @property {(token: string) => Promise<VerifiedTokenClaims>} verify
+ */
+
+/** @type {readonly string[]} */
+export const TOKEN_PROVIDER_METHODS = Object.freeze(["issue", "verify"]);
+
+/**
+ * @param {unknown} provider
+ * @returns {asserts provider is TokenProvider}
+ * @throws {import("../errors.js").ContractViolationError}
+ */
+export function assertTokenProvider(provider) {
+  assertImplements(provider, "TokenProvider", TOKEN_PROVIDER_METHODS);
+}

package/src/core/contracts/user-repository.js

@@ -0,0 +1,157 @@
+import { ContractViolationError } from "../errors.js";
+import { MAX_AUTHORITIES, MAX_AUTHORITY_LENGTH } from "../input-limits.js";
+import { DEVELOPER_MESSAGES, repositoryRecordAuthorities } from "../messages.js";
+import { assertImplements } from "./assert-contract.js";
+
+/**
+ * Données utilisateur minimales attendues par le moteur. Le dépôt transforme
+ * son modèle (ligne SQL, document Mongo, réponse d’API…) dans ce format.
+ *
+ * Les propriétés supplémentaires sont autorisées et ignorées. Elles ne sont
+ * jamais copiées dans les jetons ni dans le principal authentifié.
+ *
+ * @typedef {object} AuthUserRecord
+ * @property {string | number | bigint | { toHexString(): string }} id Identifiant stable, unique et non secret (chaîne, entier ou ObjectId MongoDB) ; converti en chaîne, il devient la revendication JWT `sub`.
+ * @property {string} passwordHash Hash Argon2id produit par `auth.password.hash()`.
+ * @property {boolean} isActive Doit valoir exactement `true` pour autoriser la connexion.
+ * @property {string[]} [roles] Rôles de l’utilisateur (par exemple `["admin"]`). Facultatif.
+ * @property {string[]} [permissions] Permissions de l’utilisateur (par exemple `["orders:write"]`). Facultatif.
+ */
+
+/**
+ * Enregistrement validé et normalisé, utilisé par le moteur.
+ *
+ * @typedef {{
+ *   id: string,
+ *   passwordHash: string,
+ *   isActive: boolean,
+ *   roles: readonly string[],
+ *   permissions: readonly string[]
+ * }} NormalizedUserRecord
+ */
+
+/**
+ * Contrat de persistance implémenté par l’application.
+ *
+ * Les deux méthodes doivent renvoyer `null` (ou `undefined`) lorsqu’aucun
+ * utilisateur ne correspond. Elles ne doivent pas lever d’erreur dans ce cas ;
+ * les erreurs sont réservées aux problèmes d’infrastructure.
+ *
+ * @typedef {object} UserRepository
+ * @property {(identifier: string) => Promise<AuthUserRecord | null | undefined>} findByIdentifier
+ *   Cherche un utilisateur par identifiant de connexion (e-mail, nom…). La
+ *   normalisation (minuscules, espaces) relève de la responsabilité du dépôt.
+ * @property {(id: string) => Promise<AuthUserRecord | null | undefined>} findById
+ *   Cherche un utilisateur par l’identifiant contenu dans la revendication `sub`.
+ */
+
+/** @type {readonly string[]} */
+export const USER_REPOSITORY_METHODS = Object.freeze(["findByIdentifier", "findById"]);
+
+/**
+ * Vérifie qu’un dépôt injecté respecte le contrat {@link UserRepository}.
+ *
+ * @param {unknown} repository
+ * @returns {asserts repository is UserRepository}
+ * @throws {ContractViolationError}
+ */
+export function assertUserRepository(repository) {
+  assertImplements(repository, "UserRepository", USER_REPOSITORY_METHODS);
+}
+
+/**
+ * Valide à l’exécution une donnée renvoyée par le dépôt.
+ *
+ * Une donnée mal formée est une erreur de programmation. Elle lève donc
+ * {@link ContractViolationError} au lieu d’être traitée comme un échec de
+ * connexion, ce qui masquerait le problème.
+ *
+ * @param {unknown} record
+ * @returns {NormalizedUserRecord | null} Enregistrement avec un `id` toujours en texte.
+ * @throws {ContractViolationError}
+ */
+export function normalizeUserRecord(record) {
+  if (record === null || record === undefined) {
+    return null;
+  }
+  if (typeof record !== "object") {
+    throw new ContractViolationError(DEVELOPER_MESSAGES.repositoryRecordNotObject);
+  }
+
+  const { passwordHash, isActive, roles, permissions } = /** @type {Record<string, unknown>} */ (record);
+  const id = normalizeUserId(/** @type {Record<string, unknown>} */ (record).id);
+  if (typeof passwordHash !== "string" || passwordHash.length === 0) {
+    throw new ContractViolationError(DEVELOPER_MESSAGES.repositoryRecordPasswordHash);
+  }
+  if (typeof isActive !== "boolean") {
+    throw new ContractViolationError(DEVELOPER_MESSAGES.repositoryRecordIsActive);
+  }
+
+  return {
+    id,
+    passwordHash,
+    isActive,
+    roles: normalizeAuthorities(roles, "roles"),
+    permissions: normalizeAuthorities(permissions, "permissions")
+  };
+}
+
+/**
+ * Valide une liste de rôles ou de permissions. Absente, elle vaut une liste
+ * vide : un utilisateur sans rôle n’obtient aucun accès protégé par rôle.
+ *
+ * @param {unknown} value
+ * @param {string} field
+ * @returns {readonly string[]} Liste figée, sans doublons.
+ * @throws {ContractViolationError}
+ */
+function normalizeAuthorities(value, field) {
+  if (value === undefined || value === null) {
+    return Object.freeze([]);
+  }
+  const isValid =
+    Array.isArray(value) &&
+    value.length <= MAX_AUTHORITIES &&
+    value.every((item) => typeof item === "string" && item.length > 0 && item.length <= MAX_AUTHORITY_LENGTH);
+  if (!isValid) {
+    throw new ContractViolationError(repositoryRecordAuthorities(field, MAX_AUTHORITIES, MAX_AUTHORITY_LENGTH));
+  }
+  return Object.freeze([...new Set(/** @type {string[]} */ (value))]);
+}
+
+/**
+ * Accepte les formes d’identifiant les plus courantes et les convertit en
+ * chaîne : texte, entier auto-incrémenté (SQL), BigInt et ObjectId MongoDB.
+ * La conversion est sans perte, ce qui évite aux applications de l’écrire.
+ *
+ * @param {unknown} id
+ * @returns {string | null} L’identifiant en texte, ou `null` si sa forme n’est pas prise en charge.
+ */
+export function toUserIdString(id) {
+  if (typeof id === "string" && id.length > 0) {
+    return id;
+  }
+  if ((typeof id === "number" && Number.isSafeInteger(id)) || typeof id === "bigint") {
+    return String(id);
+  }
+  if (id !== null && typeof id === "object") {
+    const { toHexString } = /** @type {{ toHexString?: unknown }} */ (id);
+    if (typeof toHexString === "function") {
+      return String(toHexString.call(id));
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {unknown} id
+ * @returns {string}
+ * @throws {ContractViolationError}
+ */
+function normalizeUserId(id) {
+  const normalized = toUserIdString(id);
+  if (normalized === null) {
+    throw new ContractViolationError(DEVELOPER_MESSAGES.repositoryRecordId);
+  }
+  return normalized;
+}

package/src/core/errors.js

@@ -0,0 +1,258 @@
+/**
+ * Types d’erreurs structurées pour Express AuthKit.
+ *
+ * Chaque erreur expose un `code` stable, utilisable par les applications.
+ * Ces codes font partie de l’API publique. Le cœur n’associe jamais les
+ * erreurs à des statuts HTTP : c’est le rôle des adaptateurs.
+ *
+ * @module core/errors
+ */
+
+import { DEVELOPER_MESSAGES, PUBLIC_MESSAGES, dependencyFailed } from "./messages.js";
+
+/**
+ * Codes d’erreur stables exposés par la bibliothèque.
+ *
+ * @readonly
+ * @enum {string}
+ */
+export const AUTH_ERROR_CODES = Object.freeze({
+  /** Échec de connexion, volontairement générique pour éviter l’énumération des comptes. */
+  INVALID_CREDENTIALS: "INVALID_CREDENTIALS",
+  /** Donnée invalide (mauvais type, vide ou trop longue). */
+  INVALID_INPUT: "INVALID_INPUT",
+  /** Aucun jeton d’accès n’a été fourni. */
+  TOKEN_MISSING: "TOKEN_MISSING",
+  /** Le jeton est mal formé, altéré, signé avec une autre clé ou contient des revendications invalides. */
+  TOKEN_INVALID: "TOKEN_INVALID",
+  /** La signature du jeton est valide, mais le jeton a expiré. */
+  TOKEN_EXPIRED: "TOKEN_EXPIRED",
+  /** Le moteur est configuré avec des options manquantes ou non sûres. */
+  INVALID_CONFIGURATION: "INVALID_CONFIGURATION",
+  /** Une dépendance injectée ne respecte pas son contrat. */
+  CONTRACT_VIOLATION: "CONTRACT_VIOLATION",
+  /** Le fournisseur de mots de passe ne peut pas lire un hash stocké. */
+  INVALID_PASSWORD_HASH: "INVALID_PASSWORD_HASH",
+  /** L’utilisateur est authentifié mais n’a pas les rôles ou permissions requis. */
+  ACCESS_DENIED: "ACCESS_DENIED",
+  /** Le jeton de rafraîchissement est inconnu, expiré, déjà utilisé ou révoqué. */
+  REFRESH_TOKEN_INVALID: "REFRESH_TOKEN_INVALID",
+  /** Une dépendance injectée (repository, provider) a échoué de façon inattendue. */
+  DEPENDENCY_FAILURE: "DEPENDENCY_FAILURE"
+});
+
+/**
+ * Raisons internes associées aux échecs d’authentification.
+ *
+ * Elles servent uniquement à l’audit côté serveur et ne doivent jamais être
+ * envoyées au client, car elles révéleraient l’existence d’un compte.
+ *
+ * @readonly
+ * @enum {string}
+ */
+export const AUTH_FAILURE_REASONS = Object.freeze({
+  USER_NOT_FOUND: "USER_NOT_FOUND",
+  INVALID_PASSWORD: "INVALID_PASSWORD",
+  ACCOUNT_DISABLED: "ACCOUNT_DISABLED",
+  /** Jeton de rafraîchissement absent du stockage (jamais émis, ou révoqué). */
+  REFRESH_TOKEN_UNKNOWN: "REFRESH_TOKEN_UNKNOWN",
+  /** Jeton de rafraîchissement expiré. */
+  REFRESH_TOKEN_EXPIRED: "REFRESH_TOKEN_EXPIRED",
+  /** Jeton de rafraîchissement déjà utilisé : vol probable, toute la famille est révoquée. */
+  REFRESH_TOKEN_REUSED: "REFRESH_TOKEN_REUSED"
+});
+
+/**
+ * Classe de base de toutes les erreurs levées par Express AuthKit.
+ */
+export class AuthKitError extends Error {
+  /**
+   * @param {string} code Code d’erreur stable (voir {@link AUTH_ERROR_CODES}).
+   * @param {string} message Message pouvant être exposé aux clients de l’API.
+   * @param {{ cause?: unknown }} [options]
+   */
+  constructor(code, message, options = {}) {
+    super(message, options.cause === undefined ? undefined : { cause: options.cause });
+    this.name = new.target.name;
+    /** @type {string} */
+    this.code = code;
+  }
+
+  /**
+   * Représentation sûre pour les journaux et `JSON.stringify()` : ni pile
+   * d’appels, ni cause, ni raison interne.
+   *
+   * @returns {{ name: string, code: string, message: string }}
+   */
+  toJSON() {
+    return { name: this.name, code: this.code, message: this.message };
+  }
+}
+
+/**
+ * Échec de connexion. Le message public ne précise jamais la cause.
+ */
+export class InvalidCredentialsError extends AuthKitError {
+  /**
+   * @param {string} [reason] Raison d’audit interne (voir {@link AUTH_FAILURE_REASONS}).
+   */
+  constructor(reason) {
+    super(AUTH_ERROR_CODES.INVALID_CREDENTIALS, PUBLIC_MESSAGES.invalidCredentials);
+    // Non énumérable pour éviter une fuite accidentelle dans une réponse HTTP.
+    Object.defineProperty(this, "reason", { value: reason, enumerable: false });
+  }
+}
+
+/**
+ * Donnée structurellement invalide reçue à une frontière de confiance.
+ */
+export class InvalidInputError extends AuthKitError {
+  /**
+   * @param {string} message
+   */
+  constructor(message) {
+    super(AUTH_ERROR_CODES.INVALID_INPUT, message);
+  }
+}
+
+/**
+ * Jeton d’accès absent de la requête.
+ */
+export class TokenMissingError extends AuthKitError {
+  constructor() {
+    super(AUTH_ERROR_CODES.TOKEN_MISSING, PUBLIC_MESSAGES.tokenMissing);
+  }
+}
+
+/**
+ * Jeton d’accès rejeté (mal formé, altéré, mauvais émetteur ou audience, utilisateur inconnu ou désactivé…).
+ */
+export class InvalidTokenError extends AuthKitError {
+  /**
+   * @param {{ cause?: unknown, reason?: string }} [options]
+   */
+  constructor(options = {}) {
+    super(AUTH_ERROR_CODES.TOKEN_INVALID, PUBLIC_MESSAGES.tokenInvalid, { cause: options.cause });
+    Object.defineProperty(this, "reason", { value: options.reason, enumerable: false });
+  }
+}
+
+/**
+ * Jeton d’accès dont la signature est valide, mais qui a expiré.
+ */
+export class TokenExpiredError extends AuthKitError {
+  /**
+   * @param {{ cause?: unknown }} [options]
+   */
+  constructor(options = {}) {
+    super(AUTH_ERROR_CODES.TOKEN_EXPIRED, PUBLIC_MESSAGES.tokenExpired, options);
+  }
+}
+
+/**
+ * Utilisateur authentifié, mais sans les droits demandés (rôle, permission ou
+ * règle personnalisée). Le message ne dit pas quel droit manque.
+ */
+export class AccessDeniedError extends AuthKitError {
+  constructor() {
+    super(AUTH_ERROR_CODES.ACCESS_DENIED, PUBLIC_MESSAGES.accessDenied);
+  }
+}
+
+/**
+ * Jeton de rafraîchissement refusé. Le message public est toujours le même ;
+ * la cause précise est dans `reason` (non énumérable), pour les journaux.
+ */
+export class InvalidRefreshTokenError extends AuthKitError {
+  /**
+   * @param {string} [reason] Raison d’audit interne (voir {@link AUTH_FAILURE_REASONS}).
+   */
+  constructor(reason) {
+    super(AUTH_ERROR_CODES.REFRESH_TOKEN_INVALID, PUBLIC_MESSAGES.refreshTokenInvalid);
+    Object.defineProperty(this, "reason", { value: reason, enumerable: false });
+  }
+}
+
+/**
+ * Configuration manquante, mal formée ou non sûre, levée à l’initialisation.
+ */
+export class ConfigurationError extends AuthKitError {
+  /**
+   * @param {string} message
+   */
+  constructor(message) {
+    super(AUTH_ERROR_CODES.INVALID_CONFIGURATION, message);
+  }
+}
+
+/**
+ * Dépendance injectée qui n’implémente pas son contrat.
+ */
+export class ContractViolationError extends AuthKitError {
+  /**
+   * @param {string} message
+   */
+  constructor(message) {
+    super(AUTH_ERROR_CODES.CONTRACT_VIOLATION, message);
+  }
+}
+
+/**
+ * Hash de mot de passe stocké que le fournisseur ne peut pas lire. Cela vient
+ * généralement d’une migration de données (par exemple bcrypt avec Argon2).
+ */
+export class InvalidPasswordHashError extends AuthKitError {
+  /**
+   * @param {{ cause?: unknown }} [options]
+   */
+  constructor(options = {}) {
+    super(AUTH_ERROR_CODES.INVALID_PASSWORD_HASH, DEVELOPER_MESSAGES.unsupportedPasswordHash, options);
+  }
+}
+
+/**
+ * Échec inattendu d’une dépendance injectée : base de données indisponible,
+ * service distant en panne, bug dans un provider personnalisé…
+ *
+ * L’erreur d’origine est conservée dans `cause` pour le diagnostic. Elle n’est
+ * jamais exposée aux clients HTTP par l’adaptateur Express.
+ */
+export class DependencyFailureError extends AuthKitError {
+  /**
+   * @param {string} dependency Nom de l’appel qui a échoué, par exemple « UserRepository.findById ».
+   * @param {unknown} cause Erreur d’origine.
+   */
+  constructor(dependency, cause) {
+    super(AUTH_ERROR_CODES.DEPENDENCY_FAILURE, dependencyFailed(dependency), { cause });
+    /** @type {string} */
+    this.dependency = dependency;
+  }
+}
+
+/**
+ * Exécute l’appel à une dépendance injectée. Les erreurs de la bibliothèque
+ * (jeton expiré, hash illisible…) sont transmises telles quelles ; toute autre
+ * erreur est enveloppée dans une {@link DependencyFailureError}.
+ *
+ * @template T
+ * @param {string} dependency
+ * @param {() => Promise<T> | T} call
+ * @returns {Promise<T>}
+ */
+export async function callDependency(dependency, call) {
+  try {
+    return await call();
+  } catch (error) {
+    throw isAuthKitError(error) ? error : new DependencyFailureError(dependency, error);
+  }
+}
+
+/**
+ * Garde de type pour les erreurs levées par Express AuthKit.
+ *
+ * @param {unknown} error
+ * @returns {error is AuthKitError}
+ */
+export function isAuthKitError(error) {
+  return error instanceof AuthKitError;
+}

package/src/core/input-limits.js

@@ -0,0 +1,26 @@
+/**
+ * Limites appliquées aux données non fiables avant tout traitement coûteux.
+ *
+ * Elles évitent l’épuisement des ressources par des valeurs trop longues tout
+ * en restant largement au-dessus des besoins légitimes.
+ *
+ * @module core/input-limits
+ */
+
+/** Longueur maximale d’un e-mail selon la RFC 5321, suffisante aussi pour un nom d’utilisateur. */
+export const MAX_IDENTIFIER_LENGTH = 320;
+
+/** Suffisante pour les phrases de passe, tout en limitant le coût du hachage. */
+export const MAX_PASSWORD_LENGTH = 1024;
+
+/** Les jetons d’accès produits par cette bibliothèque font quelques centaines de caractères. */
+export const MAX_TOKEN_LENGTH = 8192;
+
+/** Les jetons de rafraîchissement émis font 43 caractères ; la marge couvre d’autres formats. */
+export const MAX_REFRESH_TOKEN_LENGTH = 512;
+
+/** Nombre maximal de rôles (ou de permissions) par utilisateur : borne le coût des vérifications. */
+export const MAX_AUTHORITIES = 256;
+
+/** Longueur maximale d’un nom de rôle ou de permission (par exemple « orders:write »). */
+export const MAX_AUTHORITY_LENGTH = 128;