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

package/src/core/messages.js

@@ -0,0 +1,239 @@
+/**
+ * Tous les messages d’erreur d’Express AuthKit, au même endroit.
+ *
+ * Les messages sont rédigés en français. Les applications ne doivent pas s’y
+ * fier pour leur logique : elles utilisent le `code` stable de chaque erreur.
+ * Centraliser les textes garantit un ton cohérent et facilitera une future
+ * traduction.
+ *
+ * @module core/messages
+ */
+
+/** Commande proposée chaque fois qu’un secret JWT doit être (re)généré. */
+const GENERATE_SECRET_HINT =
+  "Générez-en un avec : npx express-authkit secret " +
+  "(ou : node -e \"console.log(require('node:crypto').randomBytes(48).toString('base64url'))\").";
+
+/**
+ * Messages publics : ils peuvent être renvoyés tels quels aux clients HTTP.
+ * Ils ne révèlent jamais d’information interne.
+ */
+export const PUBLIC_MESSAGES = Object.freeze({
+  invalidCredentials: "Identifiants invalides.",
+  tokenMissing: "Authentification requise.",
+  tokenInvalid: "Jeton d’accès invalide.",
+  tokenExpired: "Jeton d’accès expiré.",
+  refreshTokenInvalid: "Jeton de rafraîchissement invalide ou expiré. Reconnectez-vous.",
+  accessDenied: "Accès refusé : vous n’avez pas les droits nécessaires.",
+  credentialsNotObject: "Les identifiants doivent être un objet contenant « identifier » et « password ».",
+  missingJsonBody:
+    "Le corps de la requête doit être un objet JSON : envoyez l’en-tête « Content-Type: application/json ».",
+  malformedJsonBody: "Le corps de la requête n’est pas un JSON valide.",
+  payloadTooLarge: "Le corps de la requête est trop volumineux.",
+  refreshTokenMalformed: "Le champ « refreshToken » est obligatoire et doit être un texte non vide.",
+  userIdInvalid: "L’identifiant d’utilisateur doit être un texte non vide, un entier ou un ObjectId MongoDB."
+});
+
+/**
+ * @param {string} field
+ * @returns {string}
+ */
+export function fieldRequired(field) {
+  return `Le champ « ${field} » est obligatoire et doit être un texte non vide.`;
+}
+
+/**
+ * @param {string} field
+ * @param {number} maxLength
+ * @returns {string}
+ */
+export function fieldTooLong(field, maxLength) {
+  return `Le champ « ${field} » ne doit pas dépasser ${maxLength} caractères.`;
+}
+
+/**
+ * Messages destinés aux développeurs (configuration, contrats, pannes).
+ * Ils expliquent toujours comment corriger le problème.
+ */
+export const DEVELOPER_MESSAGES = Object.freeze({
+  // Mots de passe
+  unsupportedPasswordHash:
+    "Le hash de mot de passe enregistré n’est pas au format Argon2id. " +
+    "Vérifiez qu’il a été produit par auth.password.hash(), ou migrez les anciens hash (voir docs/providers-personnalises.md).",
+
+  // Options de createAuthKit()
+  usersRequired:
+    "L’option « users » est obligatoire : passez un objet qui possède les méthodes findByIdentifier() et findById().",
+  jwtOrTokenProvider:
+    "Utilisez soit l’option « jwt », soit « providers.token », mais pas les deux : l’une des deux serait ignorée.",
+  jwtRequired: "L’option « jwt » est obligatoire (secret, issuer, audience).",
+  passwordOrPasswordProvider:
+    "Utilisez soit l’option « password », soit « providers.password », mais pas les deux : l’une des deux serait ignorée.",
+
+  // Secret JWT
+  secretRequired: `L’option « jwt.secret » est obligatoire. ${GENERATE_SECRET_HINT}`,
+  secretWrongType: "L’option « jwt.secret » doit être un texte ou un Uint8Array.",
+  secretPlaceholder: `L’option « jwt.secret » ressemble à une valeur d’exemple. ${GENERATE_SECRET_HINT}`,
+  secretRepetitive: `L’option « jwt.secret » est trop répétitive pour être aléatoire. ${GENERATE_SECRET_HINT}`,
+
+  // Adaptateur Express
+  invalidRealm:
+    "L’option « realm » doit contenir de 1 à 64 caractères : lettres, chiffres, espaces, points, tirets ou soulignés.",
+  invalidIdentifierField:
+    "L’option « identifierField » doit être un simple nom de champ, par exemple \"email\" ou \"username\".",
+
+  // Contrats vérifiés pendant l’exécution
+  repositoryRecordNotObject:
+    "Le repository utilisateur doit renvoyer un objet, null ou undefined.",
+  repositoryRecordId:
+    "L’utilisateur renvoyé par le repository doit avoir un « id » : texte non vide, entier ou ObjectId MongoDB.",
+  repositoryRecordPasswordHash:
+    "L’utilisateur renvoyé par le repository doit avoir un « passwordHash » (texte non vide). " +
+    "Si votre requête ne sélectionne que certains champs, ajoutez celui du hash.",
+  repositoryRecordIsActive:
+    "L’utilisateur renvoyé par le repository doit avoir un « isActive » booléen. " +
+    "Si votre application ne permet pas de désactiver un compte, renvoyez « isActive: true ».",
+  repositoryIdMismatch:
+    "UserRepository.findById() a renvoyé un utilisateur dont l’« id » diffère de celui demandé.",
+  tokenClaimsWithoutSubject:
+    "TokenProvider.verify() doit renvoyer des informations contenant un « subject » non vide.",
+  refreshStoreConsumeInvalid:
+    "RefreshTokenStore.consume() doit renvoyer null, ou { userId, familyId, expiresAt, alreadyUsed } : " +
+    "userId et familyId sont des textes, expiresAt un nombre de secondes, alreadyUsed un booléen.",
+  refreshStoreRequired:
+    "L’option « refreshTokens.store » est obligatoire : passez votre stockage (save, consume, revokeFamily, " +
+    "revokeUser), ou createInMemoryRefreshTokenStore() pour le développement.",
+  refreshTokensDisabled:
+    "Les jetons de rafraîchissement ne sont pas activés. Ajoutez l’option « refreshTokens: { store } » " +
+    "à createAuthKit() (voir docs/refresh-tokens.md).",
+  authorizeRequirementInvalid:
+    "expressAuth.authorize() attend un rôle (\"admin\") ou un objet { anyRole, allPermissions, check } " +
+    "avec au moins une règle. anyRole et allPermissions sont des listes de textes non vides, check est une fonction.",
+  authorizationCheckNotBoolean:
+    "La fonction « check » de authorize() doit renvoyer true ou false (éventuellement via une promesse).",
+  issuedTokenInvalid:
+    "TokenProvider.issue() doit renvoyer { token, tokenId, issuedAt, expiresAt } : " +
+    "token et tokenId sont des textes, issuedAt et expiresAt des nombres de secondes."
+});
+
+/**
+ * @param {number} maxLength
+ * @returns {string}
+ */
+export function subjectInvalid(maxLength) {
+  return `Le « subject » du jeton doit être un texte non vide d’au plus ${maxLength} caractères.`;
+}
+
+/**
+ * @param {string} name Nom de l’option, par exemple « jwt » ou « createAuthKit(options) ».
+ * @returns {string}
+ */
+export function notPlainObject(name) {
+  return `« ${name} » doit être un objet simple, par exemple { … }.`;
+}
+
+/**
+ * @param {string} name
+ * @param {string[]} unknownKeys
+ * @param {readonly string[]} allowedKeys
+ * @returns {string}
+ */
+export function unknownOptions(name, unknownKeys, allowedKeys) {
+  const label = unknownKeys.length > 1 ? "Options inconnues" : "Option inconnue";
+  return `${label} dans « ${name} » : ${unknownKeys.join(", ")}. Options acceptées : ${allowedKeys.join(", ")}.`;
+}
+
+/**
+ * @param {string} name
+ * @returns {string}
+ */
+export function optionRequiredString(name) {
+  return `L’option « ${name} » doit être un texte non vide.`;
+}
+
+/**
+ * @param {string} name
+ * @param {number} maxLength
+ * @returns {string}
+ */
+export function optionTooLong(name, maxLength) {
+  return `L’option « ${name} » ne doit pas dépasser ${maxLength} caractères.`;
+}
+
+/**
+ * @param {string} name
+ * @param {number} min
+ * @param {number} max
+ * @returns {string}
+ */
+export function optionIntegerRange(name, min, max) {
+  return `L’option « ${name} » doit être un nombre entier compris entre ${min} et ${max}.`;
+}
+
+/**
+ * @param {readonly string[]} algorithms
+ * @returns {string}
+ */
+export function unsupportedAlgorithm(algorithms) {
+  return `L’option « jwt.algorithm » doit valoir l’une de ces valeurs : ${algorithms.join(", ")}.`;
+}
+
+/**
+ * @param {number} minBytes
+ * @returns {string}
+ */
+export function secretTooShort(minBytes) {
+  return `L’option « jwt.secret » doit contenir au moins ${minBytes} octets pour l’algorithme choisi. ${GENERATE_SECRET_HINT}`;
+}
+
+/**
+ * @param {string} contractName
+ * @returns {string}
+ */
+export function contractNotObject(contractName) {
+  return `${contractName} doit être un objet.`;
+}
+
+/**
+ * @param {string} contractName
+ * @param {string[]} missingMethods
+ * @returns {string}
+ */
+export function contractMissingMethods(contractName, missingMethods) {
+  const list = missingMethods.map((name) => `${name}()`).join(", ");
+  return missingMethods.length > 1
+    ? `${contractName} doit implémenter les méthodes suivantes : ${list}.`
+    : `${contractName} doit implémenter la méthode ${list}.`;
+}
+
+/**
+ * @param {string} dependency Par exemple « UserRepository.findById ».
+ * @returns {string}
+ */
+export function dependencyFailed(dependency) {
+  return `L’appel à ${dependency}() a échoué. Consultez la propriété « cause » de cette erreur pour connaître l’erreur d’origine.`;
+}
+
+/**
+ * @param {string} method Par exemple « authenticate ».
+ * @returns {string}
+ */
+export function middlewareFactoryMisuse(method) {
+  return (
+    `expressAuth.${method} doit être appelé avec des parenthèses : ` +
+    `écrivez expressAuth.${method}() et non expressAuth.${method}.`
+  );
+}
+
+/**
+ * @param {string} field « roles » ou « permissions ».
+ * @param {number} maxItems
+ * @param {number} maxLength
+ * @returns {string}
+ */
+export function repositoryRecordAuthorities(field, maxItems, maxLength) {
+  return (
+    `Le champ « ${field} » renvoyé par le repository doit être une liste de textes non vides ` +
+    `(au plus ${maxItems} éléments de ${maxLength} caractères), ou être absent.`
+  );
+}

package/src/core/refresh-token-service.js

@@ -0,0 +1,149 @@
+import { normalizeConsumedRefreshToken } from "./contracts/refresh-token-store.js";
+import { AUTH_FAILURE_REASONS, InvalidInputError, InvalidRefreshTokenError, callDependency } from "./errors.js";
+import { MAX_REFRESH_TOKEN_LENGTH } from "./input-limits.js";
+import { PUBLIC_MESSAGES } from "./messages.js";
+
+/** 256 bits d’aléa : impossible à deviner, même avec beaucoup d’essais. */
+const REFRESH_TOKEN_BYTES = 32;
+
+/**
+ * @typedef {import("./contracts/refresh-token-store.js").RefreshTokenStore} RefreshTokenStore
+ * @typedef {import("./contracts/refresh-token-store.js").ConsumedRefreshToken} ConsumedRefreshToken
+ */
+
+/**
+ * Gère le cycle de vie des jetons de rafraîchissement : émission, rotation,
+ * détection de réutilisation et révocation.
+ *
+ * Les jetons sont des valeurs aléatoires opaques (pas des JWT) : ils ne
+ * contiennent aucune information et ne valent que par leur présence dans le
+ * stockage, ce qui permet de les révoquer à tout moment.
+ *
+ * @param {object} options
+ * @param {RefreshTokenStore} options.store
+ * @param {number} options.expiresInSeconds
+ */
+export function createRefreshTokenService({ store, expiresInSeconds }) {
+  /**
+   * Émet un nouveau jeton et l’enregistre (seulement son empreinte).
+   *
+   * @param {string} userId
+   * @param {string} [familyId] Famille existante en cas de rotation ; nouvelle sinon.
+   * @returns {Promise<{ token: string, expiresIn: number }>}
+   */
+  async function issue(userId, familyId = globalThis.crypto.randomUUID()) {
+    const token = generateToken();
+    const record = {
+      tokenHash: await hashToken(token),
+      userId,
+      familyId,
+      expiresAt: nowInSeconds() + expiresInSeconds
+    };
+    await callDependency("RefreshTokenStore.save", () => store.save(record));
+    return { token, expiresIn: expiresInSeconds };
+  }
+
+  /**
+   * Consomme un jeton pour une rotation. Un jeton déjà utilisé signale un vol
+   * probable : toute sa famille est alors révoquée.
+   *
+   * @param {unknown} token
+   * @returns {Promise<ConsumedRefreshToken>}
+   * @throws {InvalidInputError | InvalidRefreshTokenError}
+   */
+  async function consume(token) {
+    const consumed = await consumeRecord(assertRefreshTokenShape(token));
+    if (consumed === null) {
+      throw new InvalidRefreshTokenError(AUTH_FAILURE_REASONS.REFRESH_TOKEN_UNKNOWN);
+    }
+    if (consumed.alreadyUsed) {
+      await revokeFamily(consumed.familyId);
+      throw new InvalidRefreshTokenError(AUTH_FAILURE_REASONS.REFRESH_TOKEN_REUSED);
+    }
+    if (consumed.expiresAt <= nowInSeconds()) {
+      throw new InvalidRefreshTokenError(AUTH_FAILURE_REASONS.REFRESH_TOKEN_EXPIRED);
+    }
+    return consumed;
+  }
+
+  /**
+   * Révoque la session à laquelle appartient le jeton. Ne lève pas d’erreur si
+   * le jeton est inconnu, expiré ou déjà révoqué : une déconnexion répétée doit
+   * réussir.
+   *
+   * @param {unknown} token
+   * @returns {Promise<void>}
+   */
+  async function revokeSessionOf(token) {
+    const consumed = await consumeRecord(assertRefreshTokenShape(token));
+    if (consumed !== null) {
+      await revokeFamily(consumed.familyId);
+    }
+  }
+
+  /**
+   * @param {string} familyId
+   * @returns {Promise<void>}
+   */
+  function revokeFamily(familyId) {
+    return callDependency("RefreshTokenStore.revokeFamily", () => store.revokeFamily(familyId));
+  }
+
+  /**
+   * @param {string} userId
+   * @returns {Promise<void>}
+   */
+  function revokeUser(userId) {
+    return callDependency("RefreshTokenStore.revokeUser", () => store.revokeUser(userId));
+  }
+
+  /**
+   * @param {string} token
+   * @returns {Promise<ConsumedRefreshToken | null>}
+   */
+  async function consumeRecord(token) {
+    const tokenHash = await hashToken(token);
+    return normalizeConsumedRefreshToken(
+      await callDependency("RefreshTokenStore.consume", () => store.consume(tokenHash))
+    );
+  }
+
+  return Object.freeze({ issue, consume, revokeSessionOf, revokeFamily, revokeUser });
+}
+
+/**
+ * @param {unknown} token
+ * @returns {string}
+ * @throws {InvalidInputError}
+ */
+function assertRefreshTokenShape(token) {
+  if (typeof token !== "string" || token.length === 0 || token.length > MAX_REFRESH_TOKEN_LENGTH) {
+    throw new InvalidInputError(PUBLIC_MESSAGES.refreshTokenMalformed);
+  }
+  return token;
+}
+
+/**
+ * @returns {string} 32 octets aléatoires encodés en base64url (43 caractères).
+ */
+function generateToken() {
+  const bytes = globalThis.crypto.getRandomValues(new Uint8Array(REFRESH_TOKEN_BYTES));
+  return Buffer.from(bytes).toString("base64url");
+}
+
+/**
+ * Empreinte SHA-256 en hexadécimal. Un hachage rapide suffit ici : le jeton a
+ * 256 bits d’aléa, il ne peut pas être retrouvé par force brute (contrairement
+ * à un mot de passe, qui exige Argon2id).
+ *
+ * @param {string} token
+ * @returns {Promise<string>}
+ */
+async function hashToken(token) {
+  const digest = await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(token));
+  return Buffer.from(digest).toString("hex");
+}
+
+function nowInSeconds() {
+  return Math.floor(Date.now() / 1000);
+}

package/src/factory/create-auth-kit.js

@@ -0,0 +1,90 @@
+import { validateAuthKitOptions } from "../config/auth-kit-options.js";
+import { resolveRefreshTokenOptions } from "../config/refresh-token-options.js";
+import { createAuthenticationService } from "../core/authentication-service.js";
+import { createRefreshTokenService } from "../core/refresh-token-service.js";
+import { callDependency } from "../core/errors.js";
+import { assertPasswordProvider } from "../core/contracts/password-provider.js";
+import { assertTokenProvider } from "../core/contracts/token-provider.js";
+import { assertUserRepository } from "../core/contracts/user-repository.js";
+import { createArgon2PasswordProvider } from "../providers/argon2-password-provider.js";
+import { createJwtTokenProvider } from "../providers/jwt-token-provider.js";
+
+/**
+ * Fonctions liées aux mots de passe, exposées dans `auth.password`.
+ *
+ * @typedef {Readonly<{
+ *   hash: (password: string) => Promise<string>,
+ *   verify: (password: string, hash: string) => Promise<boolean>
+ * }>} PasswordApi
+ */
+
+/**
+ * Moteur d’authentification renvoyé par {@link createAuthKit}.
+ *
+ * @typedef {Readonly<{
+ *   login: (credentials: import("../core/contracts/authentication-service.js").LoginCredentials) => Promise<import("../core/contracts/authentication-service.js").LoginResult>,
+ *   refresh: (refreshToken: string) => Promise<import("../core/contracts/authentication-service.js").LoginResult>,
+ *   logout: (refreshToken: string) => Promise<void>,
+ *   revokeAllSessions: (userId: import("../core/contracts/authentication-service.js").UserIdInput) => Promise<void>,
+ *   verifyAccessToken: (token: string) => Promise<import("../core/contracts/auth-principal.js").AuthPrincipal>,
+ *   password: PasswordApi
+ * }>} AuthKit
+ */
+
+/**
+ * Crée et configure un moteur d’authentification.
+ *
+ * Toutes les options et dépendances injectées sont validées ici. Une mauvaise
+ * configuration arrête donc l’application au démarrage, et non à la première
+ * requête. L’objet renvoyé ne conserve aucun état par utilisateur et peut être
+ * partagé dans tout le processus.
+ *
+ * @example
+ * const auth = createAuthKit({
+ *   users: userRepository,
+ *   jwt: { secret: process.env.AUTH_SECRET, issuer: "my-api", audience: "my-client" }
+ * });
+ *
+ * @param {import("../config/auth-kit-options.js").AuthKitOptions} options
+ * @returns {AuthKit}
+ * @throws {import("../core/errors.js").ConfigurationError} Si les options manquent ou ne sont pas sûres.
+ * @throws {import("../core/errors.js").ContractViolationError} Si une dépendance injectée ne respecte pas son contrat.
+ */
+export function createAuthKit(options) {
+  const { users, jwt, password, refreshTokens, providers = {} } = validateAuthKitOptions(options);
+
+  assertUserRepository(users);
+
+  const passwordProvider = providers.password ?? createArgon2PasswordProvider(password);
+  assertPasswordProvider(passwordProvider);
+
+  // validateAuthKitOptions() garantit que `jwt` est présent quand aucun provider de token n’est fourni.
+  const tokenProvider =
+    providers.token ?? createJwtTokenProvider(/** @type {import("../config/jwt-options.js").JwtOptions} */ (jwt));
+  assertTokenProvider(tokenProvider);
+
+  const refreshTokenService =
+    refreshTokens === undefined ? undefined : createRefreshTokenService(resolveRefreshTokenOptions(refreshTokens));
+
+  const service = createAuthenticationService({
+    users,
+    passwordProvider,
+    tokenProvider,
+    refreshTokens: refreshTokenService
+  });
+
+  return Object.freeze({
+    login: service.login,
+    refresh: service.refresh,
+    logout: service.logout,
+    revokeAllSessions: service.revokeAllSessions,
+    verifyAccessToken: service.verifyAccessToken,
+    password: Object.freeze({
+      /** @param {string} plainPassword */
+      hash: (plainPassword) => callDependency("PasswordProvider.hash", () => passwordProvider.hash(plainPassword)),
+      /** @param {string} plainPassword @param {string} passwordHash */
+      verify: (plainPassword, passwordHash) =>
+        callDependency("PasswordProvider.verify", () => passwordProvider.verify(plainPassword, passwordHash))
+    })
+  });
+}

package/src/index.js

@@ -0,0 +1,61 @@
+/**
+ * Express AuthKit — point d’entrée indépendant du framework.
+ *
+ * API publique. Les modules non réexportés ici sont internes et peuvent
+ * évoluer sans préavis.
+ *
+ * @module @kourouma/express-authkit
+ */
+
+export { createAuthKit } from "./factory/create-auth-kit.js";
+export { isAuthorized } from "./core/authorization.js";
+
+export { createArgon2PasswordProvider } from "./providers/argon2-password-provider.js";
+export { createJwtTokenProvider } from "./providers/jwt-token-provider.js";
+export { createInMemoryRefreshTokenStore } from "./providers/in-memory-refresh-token-store.js";
+
+export { assertUserRepository } from "./core/contracts/user-repository.js";
+export { assertPasswordProvider } from "./core/contracts/password-provider.js";
+export { assertTokenProvider } from "./core/contracts/token-provider.js";
+export { assertRefreshTokenStore } from "./core/contracts/refresh-token-store.js";
+
+export {
+  AUTH_ERROR_CODES,
+  AUTH_FAILURE_REASONS,
+  AccessDeniedError,
+  AuthKitError,
+  ConfigurationError,
+  ContractViolationError,
+  DependencyFailureError,
+  InvalidCredentialsError,
+  InvalidInputError,
+  InvalidPasswordHashError,
+  InvalidRefreshTokenError,
+  InvalidTokenError,
+  TokenExpiredError,
+  TokenMissingError,
+  isAuthKitError
+} from "./core/errors.js";
+
+/**
+ * @typedef {import("./factory/create-auth-kit.js").AuthKit} AuthKit
+ * @typedef {import("./config/auth-kit-options.js").AuthKitOptions} AuthKitOptions
+ * @typedef {import("./config/jwt-options.js").JwtOptions} JwtOptions
+ * @typedef {import("./config/password-options.js").PasswordOptions} PasswordOptions
+ * @typedef {import("./core/contracts/user-repository.js").UserRepository} UserRepository
+ * @typedef {import("./core/contracts/user-repository.js").AuthUserRecord} AuthUserRecord
+ * @typedef {import("./core/contracts/password-provider.js").PasswordProvider} PasswordProvider
+ * @typedef {import("./core/contracts/token-provider.js").TokenProvider} TokenProvider
+ * @typedef {import("./core/contracts/token-provider.js").IssuedToken} IssuedToken
+ * @typedef {import("./core/contracts/token-provider.js").VerifiedTokenClaims} VerifiedTokenClaims
+ * @typedef {import("./core/contracts/authentication-service.js").AuthenticationService} AuthenticationService
+ * @typedef {import("./core/contracts/authentication-service.js").LoginCredentials} LoginCredentials
+ * @typedef {import("./core/contracts/authentication-service.js").LoginResult} LoginResult
+ * @typedef {import("./core/contracts/auth-principal.js").AuthPrincipal} AuthPrincipal
+ * @typedef {import("./core/contracts/authentication-service.js").UserIdInput} UserIdInput
+ * @typedef {import("./core/authorization.js").AuthorizationRequirement} AuthorizationRequirement
+ * @typedef {import("./config/refresh-token-options.js").RefreshTokenOptions} RefreshTokenOptions
+ * @typedef {import("./core/contracts/refresh-token-store.js").RefreshTokenStore} RefreshTokenStore
+ * @typedef {import("./core/contracts/refresh-token-store.js").RefreshTokenRecord} RefreshTokenRecord
+ * @typedef {import("./core/contracts/refresh-token-store.js").ConsumedRefreshToken} ConsumedRefreshToken
+ */

package/src/providers/argon2-password-provider.js

@@ -0,0 +1,68 @@
+import { argon2id, hash as argon2Hash, verify as argon2Verify } from "argon2";
+
+import { resolvePasswordOptions } from "../config/password-options.js";
+import { InvalidInputError, InvalidPasswordHashError } from "../core/errors.js";
+import { MAX_PASSWORD_LENGTH } from "../core/input-limits.js";
+import { fieldRequired, fieldTooLong } from "../core/messages.js";
+
+/** Seuls les hash Argon2id sont acceptés : Argon2i et Argon2d ne sont pas recommandés pour les mots de passe. */
+const ARGON2ID_PREFIX = "$argon2id$";
+
+/**
+ * Crée un {@link import("../core/contracts/password-provider.js").PasswordProvider}
+ * basé sur le paquet `argon2` (implémentation C de référence, variante Argon2id).
+ *
+ * La bibliothèque génère le sel avec un générateur aléatoire sécurisé et le
+ * conserve avec les paramètres dans le hash. Modifier les coûts plus tard ne
+ * rend donc pas les hash existants invalides.
+ *
+ * @param {import("../config/password-options.js").PasswordOptions} [options]
+ * @returns {import("../core/contracts/password-provider.js").PasswordProvider}
+ * @throws {import("../core/errors.js").ConfigurationError}
+ */
+export function createArgon2PasswordProvider(options) {
+  const parameters = resolvePasswordOptions(options);
+
+  /**
+   * @param {string} password
+   * @returns {Promise<string>}
+   */
+  async function hash(password) {
+    assertPassword(password);
+    return argon2Hash(password, { type: argon2id, ...parameters });
+  }
+
+  /**
+   * @param {string} password
+   * @param {string} passwordHash
+   * @returns {Promise<boolean>}
+   */
+  async function verify(password, passwordHash) {
+    assertPassword(password);
+    if (typeof passwordHash !== "string" || !passwordHash.startsWith(ARGON2ID_PREFIX)) {
+      throw new InvalidPasswordHashError();
+    }
+    try {
+      // argon2.verify() recalcule le hash avec le sel et les paramètres
+      // stockés, puis compare les résultats en temps constant.
+      return await argon2Verify(passwordHash, password);
+    } catch (error) {
+      throw new InvalidPasswordHashError({ cause: error });
+    }
+  }
+
+  return Object.freeze({ hash, verify });
+}
+
+/**
+ * @param {unknown} password
+ * @returns {asserts password is string}
+ */
+function assertPassword(password) {
+  if (typeof password !== "string" || password.length === 0) {
+    throw new InvalidInputError(fieldRequired("password"));
+  }
+  if (password.length > MAX_PASSWORD_LENGTH) {
+    throw new InvalidInputError(fieldTooLong("password", MAX_PASSWORD_LENGTH));
+  }
+}

package/src/providers/in-memory-refresh-token-store.js

@@ -0,0 +1,51 @@
+/**
+ * Stockage des jetons de rafraîchissement en mémoire.
+ *
+ * ⚠️ Réservé au développement et aux tests : les jetons sont perdus au
+ * redémarrage et ne sont pas partagés entre plusieurs processus ou serveurs.
+ * En production, implémentez le contrat `RefreshTokenStore` avec votre base
+ * de données (voir docs/refresh-tokens.md).
+ *
+ * @returns {import("../core/contracts/refresh-token-store.js").RefreshTokenStore}
+ */
+export function createInMemoryRefreshTokenStore() {
+  /** @type {Map<string, { userId: string, familyId: string, expiresAt: number, used: boolean }>} */
+  const records = new Map();
+
+  /** @param {(record: { userId: string, familyId: string, expiresAt: number, used: boolean }) => boolean} predicate */
+  function deleteWhere(predicate) {
+    for (const [tokenHash, record] of records) {
+      if (predicate(record)) {
+        records.delete(tokenHash);
+      }
+    }
+  }
+
+  return Object.freeze({
+    async save({ tokenHash, userId, familyId, expiresAt }) {
+      // Nettoyage au fil de l’eau : la mémoire ne grossit pas indéfiniment.
+      const now = Math.floor(Date.now() / 1000);
+      deleteWhere((record) => record.expiresAt <= now);
+      records.set(tokenHash, { userId, familyId, expiresAt, used: false });
+    },
+
+    async consume(tokenHash) {
+      const record = records.get(tokenHash);
+      if (record === undefined) {
+        return null;
+      }
+      // Lecture et marquage dans le même tour de boucle : atomique en JavaScript.
+      const alreadyUsed = record.used;
+      record.used = true;
+      return { userId: record.userId, familyId: record.familyId, expiresAt: record.expiresAt, alreadyUsed };
+    },
+
+    async revokeFamily(familyId) {
+      deleteWhere((record) => record.familyId === familyId);
+    },
+
+    async revokeUser(userId) {
+      deleteWhere((record) => record.userId === userId);
+    }
+  });
+}