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

package/src/config/password-options.js

@@ -0,0 +1,38 @@
+import { assertIntegerInRange, assertKnownKeys, assertPlainObject } from "./assertions.js";
+import { ARGON2_DEFAULTS, ARGON2_LIMITS } from "./defaults.js";
+
+/**
+ * Paramètres de coût Argon2id acceptés dans `createAuthKit({ password })`.
+ *
+ * @typedef {object} PasswordOptions
+ * @property {number} [memoryCost=65536] Mémoire en Kio (minimum 19 456, soit 19 Mio).
+ * @property {number} [timeCost=3] Nombre d’itérations (minimum 2).
+ * @property {number} [parallelism=4] Niveau de parallélisme (1 à 16).
+ */
+
+/**
+ * @typedef {Readonly<Required<PasswordOptions>>} ResolvedPasswordOptions
+ */
+
+const ALLOWED_KEYS = Object.freeze(["memoryCost", "timeCost", "parallelism"]);
+
+/**
+ * Valide les options Argon2id et refuse les paramètres sous le seuil OWASP.
+ *
+ * @param {unknown} [options]
+ * @returns {ResolvedPasswordOptions}
+ * @throws {import("../core/errors.js").ConfigurationError}
+ */
+export function resolvePasswordOptions(options = {}) {
+  assertPlainObject(options, "password");
+  assertKnownKeys(options, ALLOWED_KEYS, "password");
+
+  const memoryCost = options.memoryCost ?? ARGON2_DEFAULTS.memoryCost;
+  const timeCost = options.timeCost ?? ARGON2_DEFAULTS.timeCost;
+  const parallelism = options.parallelism ?? ARGON2_DEFAULTS.parallelism;
+  assertIntegerInRange(memoryCost, "password.memoryCost", ARGON2_LIMITS.minMemoryCost, ARGON2_LIMITS.maxMemoryCost);
+  assertIntegerInRange(timeCost, "password.timeCost", ARGON2_LIMITS.minTimeCost, ARGON2_LIMITS.maxTimeCost);
+  assertIntegerInRange(parallelism, "password.parallelism", ARGON2_LIMITS.minParallelism, ARGON2_LIMITS.maxParallelism);
+
+  return Object.freeze({ memoryCost, timeCost, parallelism });
+}

package/src/config/refresh-token-options.js

@@ -0,0 +1,49 @@
+import { assertRefreshTokenStore } from "../core/contracts/refresh-token-store.js";
+import { ConfigurationError } from "../core/errors.js";
+import { DEVELOPER_MESSAGES } from "../core/messages.js";
+import { assertIntegerInRange, assertKnownKeys, assertPlainObject } from "./assertions.js";
+import { REFRESH_TOKEN_DEFAULTS, REFRESH_TOKEN_LIMITS } from "./defaults.js";
+
+/**
+ * Options acceptées dans `createAuthKit({ refreshTokens })`.
+ *
+ * @typedef {object} RefreshTokenOptions
+ * @property {import("../core/contracts/refresh-token-store.js").RefreshTokenStore} store
+ *   Stockage des jetons (votre base de données, ou `createInMemoryRefreshTokenStore()` en développement).
+ * @property {number} [expiresInSeconds=1209600] Durée de vie d’un jeton de rafraîchissement
+ *   (14 jours par défaut, de 5 minutes à 90 jours). Chaque rotation repart de zéro.
+ */
+
+/**
+ * @typedef {Readonly<{
+ *   store: import("../core/contracts/refresh-token-store.js").RefreshTokenStore,
+ *   expiresInSeconds: number
+ * }>} ResolvedRefreshTokenOptions
+ */
+
+const ALLOWED_KEYS = Object.freeze(["store", "expiresInSeconds"]);
+
+/**
+ * @param {unknown} options
+ * @returns {ResolvedRefreshTokenOptions}
+ * @throws {ConfigurationError | import("../core/errors.js").ContractViolationError}
+ */
+export function resolveRefreshTokenOptions(options) {
+  assertPlainObject(options, "refreshTokens");
+  assertKnownKeys(options, ALLOWED_KEYS, "refreshTokens");
+
+  if (options.store === undefined || options.store === null) {
+    throw new ConfigurationError(DEVELOPER_MESSAGES.refreshStoreRequired);
+  }
+  assertRefreshTokenStore(options.store);
+
+  const expiresInSeconds = options.expiresInSeconds ?? REFRESH_TOKEN_DEFAULTS.expiresInSeconds;
+  assertIntegerInRange(
+    expiresInSeconds,
+    "refreshTokens.expiresInSeconds",
+    REFRESH_TOKEN_LIMITS.minExpiresInSeconds,
+    REFRESH_TOKEN_LIMITS.maxExpiresInSeconds
+  );
+
+  return Object.freeze({ store: options.store, expiresInSeconds });
+}

package/src/config/secret-strength.js

@@ -0,0 +1,112 @@
+import { ConfigurationError } from "../core/errors.js";
+import { DEVELOPER_MESSAGES, secretTooShort } from "../core/messages.js";
+
+/**
+ * Détection heuristique des secrets JWT manifestement faibles.
+ *
+ * Ce contrôle ne peut pas prouver qu’un secret est aléatoire : il rejette
+ * seulement les erreurs fréquentes (valeurs d’exemple, courtes ou répétées).
+ * Générez toujours les secrets avec un générateur aléatoire sûr, par exemple
+ * `npx express-authkit secret`.
+ *
+ * @module config/secret-strength
+ */
+
+/** Fragments qui signalent une valeur d’exemple copiée d’un tutoriel ou d’un `.env.example`. */
+const PLACEHOLDER_FRAGMENTS = Object.freeze([
+  "changeme",
+  "change-me",
+  "change_me",
+  "replace-me",
+  "replace_me",
+  "your-secret",
+  "your_secret",
+  "yoursecret",
+  "mysecret",
+  "my-secret",
+  "my_secret",
+  "supersecret",
+  "super-secret",
+  "super_secret",
+  "jwt-secret",
+  "jwt_secret",
+  "secretkey",
+  "secret-key",
+  "secret_key",
+  "placeholder",
+  "example",
+  "password",
+  "xxxxxxxx",
+  "12345678"
+]);
+
+const MIN_DISTINCT_CHARACTERS = 10;
+const MAX_REPEATED_UNIT_LENGTH = 16;
+
+/**
+ * @param {unknown} secret
+ * @param {number} minBytes
+ * @returns {Uint8Array} Secret encodé en octets, prêt pour le fournisseur JWT.
+ * @throws {ConfigurationError}
+ */
+export function assertStrongSecret(secret, minBytes) {
+  if (secret === undefined || secret === null || secret === "") {
+    throw new ConfigurationError(DEVELOPER_MESSAGES.secretRequired);
+  }
+
+  if (typeof secret === "string") {
+    assertStrongStringSecret(secret);
+    return checkLength(new TextEncoder().encode(secret), minBytes);
+  }
+
+  if (secret instanceof Uint8Array) {
+    if (new Set(secret).size < MIN_DISTINCT_CHARACTERS) {
+      throw new ConfigurationError(DEVELOPER_MESSAGES.secretRepetitive);
+    }
+    // Copie le tampon pour empêcher une modification ultérieure de changer la clé.
+    return checkLength(Uint8Array.from(secret), minBytes);
+  }
+
+  throw new ConfigurationError(DEVELOPER_MESSAGES.secretWrongType);
+}
+
+/**
+ * @param {Uint8Array} bytes
+ * @param {number} minBytes
+ * @returns {Uint8Array}
+ */
+function checkLength(bytes, minBytes) {
+  if (bytes.length < minBytes) {
+    throw new ConfigurationError(secretTooShort(minBytes));
+  }
+  return bytes;
+}
+
+/**
+ * @param {string} secret
+ */
+function assertStrongStringSecret(secret) {
+  const lowered = secret.toLowerCase();
+  if (PLACEHOLDER_FRAGMENTS.some((fragment) => lowered.includes(fragment))) {
+    throw new ConfigurationError(DEVELOPER_MESSAGES.secretPlaceholder);
+  }
+  if (new Set(secret).size < MIN_DISTINCT_CHARACTERS || isRepeatedPattern(secret)) {
+    throw new ConfigurationError(DEVELOPER_MESSAGES.secretRepetitive);
+  }
+}
+
+/**
+ * Détecte les valeurs telles que « abcdefghij » répétées de nombreuses fois.
+ *
+ * @param {string} value
+ * @returns {boolean}
+ */
+function isRepeatedPattern(value) {
+  for (let size = 1; size <= MAX_REPEATED_UNIT_LENGTH && size < value.length; size += 1) {
+    const unit = value.slice(0, size);
+    if (unit.repeat(Math.ceil(value.length / size)).slice(0, value.length) === value) {
+      return true;
+    }
+  }
+  return false;
+}

package/src/core/authentication-service.js

@@ -0,0 +1,278 @@
+import { createAuthPrincipal } from "./contracts/auth-principal.js";
+import { normalizeUserRecord, toUserIdString } from "./contracts/user-repository.js";
+import {
+  AUTH_FAILURE_REASONS,
+  ConfigurationError,
+  ContractViolationError,
+  InvalidCredentialsError,
+  InvalidInputError,
+  InvalidRefreshTokenError,
+  InvalidTokenError,
+  TokenMissingError,
+  callDependency
+} from "./errors.js";
+import { MAX_IDENTIFIER_LENGTH, MAX_PASSWORD_LENGTH, MAX_TOKEN_LENGTH } from "./input-limits.js";
+import { DEVELOPER_MESSAGES, PUBLIC_MESSAGES, fieldRequired, fieldTooLong } from "./messages.js";
+
+/**
+ * @typedef {import("./contracts/user-repository.js").UserRepository} UserRepository
+ * @typedef {import("./contracts/password-provider.js").PasswordProvider} PasswordProvider
+ * @typedef {import("./contracts/token-provider.js").TokenProvider} TokenProvider
+ * @typedef {import("./contracts/authentication-service.js").AuthenticationService} AuthenticationService
+ * @typedef {import("./contracts/authentication-service.js").LoginCredentials} LoginCredentials
+ * @typedef {import("./contracts/authentication-service.js").LoginResult} LoginResult
+ * @typedef {import("./contracts/auth-principal.js").AuthPrincipal} AuthPrincipal
+ */
+
+/**
+ * Crée le service d’authentification indépendant du framework.
+ *
+ * La fabrique doit avoir validé les dépendances au préalable. Ce service ne
+ * conserve aucun état utilisateur : il peut être partagé entre les requêtes
+ * et entre plusieurs processus derrière un répartiteur de charge.
+ *
+ * @param {object} dependencies
+ * @param {UserRepository} dependencies.users
+ * @param {PasswordProvider} dependencies.passwordProvider
+ * @param {TokenProvider} dependencies.tokenProvider
+ * @param {ReturnType<typeof import("./refresh-token-service.js").createRefreshTokenService>} [dependencies.refreshTokens]
+ *   Service des jetons de rafraîchissement ; absent si la fonctionnalité n’est pas activée.
+ * @returns {AuthenticationService}
+ */
+export function createAuthenticationService({ users, passwordProvider, tokenProvider, refreshTokens }) {
+  const getDummyHash = createDummyHashSource(passwordProvider);
+
+  // Chaque appel à une dépendance injectée est enveloppé : une panne (base de
+  // données indisponible, bug d’un provider) devient une DependencyFailureError
+  // avec un code stable, l’erreur d’origine restant disponible dans `cause`.
+  /** @param {string} identifier */
+  const findUserByIdentifier = (identifier) =>
+    callDependency("UserRepository.findByIdentifier", () => users.findByIdentifier(identifier));
+  /** @param {string} id */
+  const findUserById = (id) => callDependency("UserRepository.findById", () => users.findById(id));
+  /** @param {string} password @param {string} hash */
+  const verifyPassword = (password, hash) =>
+    callDependency("PasswordProvider.verify", () => passwordProvider.verify(password, hash));
+  /** @param {string} subject */
+  const issueToken = (subject) => callDependency("TokenProvider.issue", () => tokenProvider.issue({ subject }));
+  /** @param {string} token */
+  const verifyToken = (token) => callDependency("TokenProvider.verify", () => tokenProvider.verify(token));
+
+  /**
+   * @param {LoginCredentials} credentials
+   * @returns {Promise<LoginResult>}
+   */
+  async function login(credentials) {
+    const { identifier, password } = validateCredentials(credentials);
+
+    const user = normalizeUserRecord(await findUserByIdentifier(identifier));
+
+    if (user === null) {
+      // Réduit les fuites de temps : vérifie aussi un faux hash pour que les
+      // comptes inconnus coûtent autant qu’un compte existant.
+      await verifyPassword(password, await getDummyHash());
+      throw new InvalidCredentialsError(AUTH_FAILURE_REASONS.USER_NOT_FOUND);
+    }
+
+    // Vérifie volontairement le mot de passe avant le statut du compte :
+    // un compte désactivé prend alors le même temps qu’un compte actif.
+    const passwordMatches = await verifyPassword(password, user.passwordHash);
+    if (passwordMatches !== true) {
+      throw new InvalidCredentialsError(AUTH_FAILURE_REASONS.INVALID_PASSWORD);
+    }
+    if (user.isActive !== true) {
+      throw new InvalidCredentialsError(AUTH_FAILURE_REASONS.ACCOUNT_DISABLED);
+    }
+
+    return createSession(user);
+  }
+
+  /**
+   * Échange un jeton de rafraîchissement contre une nouvelle paire de jetons.
+   * L’ancien jeton devient inutilisable (rotation).
+   *
+   * @param {string} refreshToken
+   * @returns {Promise<LoginResult>}
+   */
+  async function refresh(refreshToken) {
+    const service = requireRefreshTokens();
+    const consumed = await service.consume(refreshToken);
+
+    // Le compte a pu être supprimé ou désactivé depuis la connexion.
+    const user = normalizeUserRecord(await findUserById(consumed.userId));
+    if (user === null || user.id !== consumed.userId || user.isActive !== true) {
+      await service.revokeFamily(consumed.familyId);
+      throw new InvalidRefreshTokenError(
+        user === null ? AUTH_FAILURE_REASONS.USER_NOT_FOUND : AUTH_FAILURE_REASONS.ACCOUNT_DISABLED
+      );
+    }
+
+    return createSession(user, consumed.familyId);
+  }
+
+  /**
+   * Déconnecte la session liée à ce jeton de rafraîchissement. Réussit même si
+   * le jeton est déjà révoqué ou expiré.
+   *
+   * @param {string} refreshToken
+   * @returns {Promise<void>}
+   */
+  async function logout(refreshToken) {
+    await requireRefreshTokens().revokeSessionOf(refreshToken);
+  }
+
+  /**
+   * Déconnecte toutes les sessions d’un utilisateur (par exemple après un
+   * changement de mot de passe).
+   *
+   * @param {string | number | bigint | { toHexString(): string }} userId
+   * @returns {Promise<void>}
+   */
+  async function revokeAllSessions(userId) {
+    const service = requireRefreshTokens();
+    const id = toUserIdString(userId);
+    if (id === null) {
+      throw new InvalidInputError(PUBLIC_MESSAGES.userIdInvalid);
+    }
+    await service.revokeUser(id);
+  }
+
+  /**
+   * Émet un jeton d’accès et, si la fonctionnalité est activée, un jeton de
+   * rafraîchissement (dans la famille donnée, ou une nouvelle).
+   *
+   * @param {import("./contracts/user-repository.js").NormalizedUserRecord} user
+   * @param {string} [familyId]
+   * @returns {Promise<LoginResult>}
+   */
+  async function createSession(user, familyId) {
+    const issued = assertIssuedToken(await issueToken(user.id));
+    const result = {
+      accessToken: issued.token,
+      tokenType: /** @type {const} */ ("Bearer"),
+      expiresIn: issued.expiresAt - issued.issuedAt,
+      principal: createAuthPrincipal(issued, user)
+    };
+    if (refreshTokens === undefined) {
+      return result;
+    }
+    const refreshed = await refreshTokens.issue(user.id, familyId);
+    return { ...result, refreshToken: refreshed.token, refreshExpiresIn: refreshed.expiresIn };
+  }
+
+  function requireRefreshTokens() {
+    if (refreshTokens === undefined) {
+      throw new ConfigurationError(DEVELOPER_MESSAGES.refreshTokensDisabled);
+    }
+    return refreshTokens;
+  }
+
+  /**
+   * @param {string} token
+   * @returns {Promise<AuthPrincipal>}
+   */
+  async function verifyAccessToken(token) {
+    if (token === undefined || token === null || token === "") {
+      throw new TokenMissingError();
+    }
+    if (typeof token !== "string" || token.length > MAX_TOKEN_LENGTH) {
+      throw new InvalidTokenError();
+    }
+
+    const claims = await verifyToken(token);
+    if (typeof claims?.subject !== "string" || claims.subject.length === 0) {
+      throw new ContractViolationError(DEVELOPER_MESSAGES.tokenClaimsWithoutSubject);
+    }
+
+    // Vérifier l’utilisateur à chaque requête bloque immédiatement les
+    // comptes supprimés ou désactivés, ce qu’un JWT seul ne peut pas faire.
+    const user = normalizeUserRecord(await findUserById(claims.subject));
+    if (user === null) {
+      throw new InvalidTokenError({ reason: AUTH_FAILURE_REASONS.USER_NOT_FOUND });
+    }
+    if (user.id !== claims.subject) {
+      throw new ContractViolationError(DEVELOPER_MESSAGES.repositoryIdMismatch);
+    }
+    if (user.isActive !== true) {
+      throw new InvalidTokenError({ reason: AUTH_FAILURE_REASONS.ACCOUNT_DISABLED });
+    }
+
+    return createAuthPrincipal(claims, user);
+  }
+
+  return Object.freeze({ login, refresh, logout, revokeAllSessions, verifyAccessToken });
+}
+
+/**
+ * Vérifie la forme du jeton renvoyé par un TokenProvider (utile surtout pour
+ * les providers personnalisés).
+ *
+ * @param {unknown} value
+ * @returns {import("./contracts/token-provider.js").IssuedToken}
+ * @throws {ContractViolationError}
+ */
+function assertIssuedToken(value) {
+  const issued = /** @type {Partial<import("./contracts/token-provider.js").IssuedToken> | null | undefined} */ (value);
+  const isValid =
+    typeof issued?.token === "string" &&
+    issued.token.length > 0 &&
+    typeof issued.tokenId === "string" &&
+    Number.isFinite(issued.issuedAt) &&
+    Number.isFinite(issued.expiresAt);
+  if (!isValid) {
+    throw new ContractViolationError(DEVELOPER_MESSAGES.issuedTokenInvalid);
+  }
+  return /** @type {import("./contracts/token-provider.js").IssuedToken} */ (issued);
+}
+
+/**
+ * @param {unknown} credentials
+ * @returns {LoginCredentials}
+ * @throws {InvalidInputError}
+ */
+function validateCredentials(credentials) {
+  if (credentials === null || typeof credentials !== "object") {
+    throw new InvalidInputError(PUBLIC_MESSAGES.credentialsNotObject);
+  }
+  const { identifier, password } = /** @type {Record<string, unknown>} */ (credentials);
+  assertBoundedString(identifier, "identifier", MAX_IDENTIFIER_LENGTH);
+  assertBoundedString(password, "password", MAX_PASSWORD_LENGTH);
+  return { identifier, password };
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} field
+ * @param {number} maxLength
+ * @returns {asserts value is string}
+ */
+function assertBoundedString(value, field, maxLength) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new InvalidInputError(fieldRequired(field));
+  }
+  if (value.length > maxLength) {
+    throw new InvalidInputError(fieldTooLong(field, maxLength));
+  }
+}
+
+/**
+ * Calcule puis met en cache, à la demande, le hash d’une valeur aléatoire avec
+ * le fournisseur configuré. Son coût correspond ainsi à celui d’un vrai hash.
+ * Un essai en erreur n’est pas mis en cache.
+ *
+ * @param {PasswordProvider} passwordProvider
+ * @returns {() => Promise<string>}
+ */
+function createDummyHashSource(passwordProvider) {
+  /** @type {Promise<string> | undefined} */
+  let pending;
+  return () => {
+    pending ??= callDependency("PasswordProvider.hash", () =>
+      passwordProvider.hash(globalThis.crypto.randomUUID())
+    ).catch((error) => {
+      pending = undefined;
+      throw error;
+    });
+    return pending;
+  };
+}

package/src/core/authorization.js

@@ -0,0 +1,156 @@
+import { ConfigurationError, ContractViolationError } from "./errors.js";
+import { MAX_AUTHORITY_LENGTH } from "./input-limits.js";
+import { DEVELOPER_MESSAGES } from "./messages.js";
+
+/**
+ * Règle d’accès.
+ *
+ * Un simple texte désigne un rôle : `"admin"` équivaut à `{ anyRole: ["admin"] }`.
+ * Quand plusieurs règles sont données, **toutes** doivent être respectées.
+ *
+ * @typedef {string | {
+ *   anyRole?: string[],
+ *   allPermissions?: string[],
+ *   check?: (principal: import("./contracts/auth-principal.js").AuthPrincipal, context?: unknown) => boolean | Promise<boolean>
+ * }} AuthorizationRequirement
+ */
+
+/**
+ * Règle validée, prête à être évaluée.
+ *
+ * @typedef {Readonly<{
+ *   anyRole: readonly string[],
+ *   allPermissions: readonly string[],
+ *   check: ((principal: import("./contracts/auth-principal.js").AuthPrincipal, context?: unknown) => boolean | Promise<boolean>) | undefined
+ * }>} NormalizedAuthorizationRequirement
+ */
+
+const ALLOWED_KEYS = Object.freeze(["anyRole", "allPermissions", "check"]);
+
+/**
+ * Règles produites par normalizeAuthorizationRequirement(). Un registre
+ * interne, plutôt qu’un test sur la forme de l’objet : un objet fabriqué à la
+ * main (par exemple avec une liste de rôles vide) ne peut pas se faire passer
+ * pour une règle validée et contourner la validation.
+ *
+ * @type {WeakSet<object>}
+ */
+const normalizedRequirements = new WeakSet();
+
+/**
+ * Valide une règle d’accès au démarrage, pour qu’une faute (rôle vide, clé
+ * mal orthographiée…) soit signalée avant la première requête.
+ *
+ * @param {unknown} requirement
+ * @returns {NormalizedAuthorizationRequirement}
+ * @throws {ConfigurationError}
+ */
+export function normalizeAuthorizationRequirement(requirement) {
+  if (typeof requirement === "string") {
+    return register({ anyRole: Object.freeze([assertAuthorityName(requirement)]), allPermissions: Object.freeze([]), check: undefined });
+  }
+  if (requirement === null || typeof requirement !== "object" || Array.isArray(requirement)) {
+    throw new ConfigurationError(DEVELOPER_MESSAGES.authorizeRequirementInvalid);
+  }
+
+  const rules = /** @type {Record<string, unknown>} */ (requirement);
+  const hasUnknownKey = Object.keys(rules).some((key) => !ALLOWED_KEYS.includes(key));
+  const hasAtLeastOneRule = ALLOWED_KEYS.some((key) => rules[key] !== undefined);
+  if (hasUnknownKey || !hasAtLeastOneRule) {
+    throw new ConfigurationError(DEVELOPER_MESSAGES.authorizeRequirementInvalid);
+  }
+  if (rules.check !== undefined && typeof rules.check !== "function") {
+    throw new ConfigurationError(DEVELOPER_MESSAGES.authorizeRequirementInvalid);
+  }
+
+  return register({
+    anyRole: normalizeNameList(rules.anyRole),
+    allPermissions: normalizeNameList(rules.allPermissions),
+    check: /** @type {NormalizedAuthorizationRequirement["check"]} */ (rules.check)
+  });
+}
+
+/**
+ * Indique si un utilisateur authentifié respecte une règle d’accès.
+ *
+ * - `anyRole` : l’utilisateur doit avoir **au moins un** de ces rôles ;
+ * - `allPermissions` : il doit avoir **toutes** ces permissions ;
+ * - `check` : fonction personnalisée, appelée en dernier, avec `context`
+ *   (la requête HTTP avec l’adaptateur Express).
+ *
+ * @example
+ * await isAuthorized(principal, "admin");
+ * await isAuthorized(principal, { allPermissions: ["orders:write"] });
+ * await isAuthorized(principal, { check: (user, req) => user.userId === req.params.id }, req);
+ *
+ * @param {import("./contracts/auth-principal.js").AuthPrincipal} principal
+ * @param {AuthorizationRequirement | NormalizedAuthorizationRequirement} requirement
+ * @param {unknown} [context] Information transmise à `check` (par exemple la requête).
+ * @returns {Promise<boolean>}
+ * @throws {ConfigurationError} Si la règle est invalide.
+ * @throws {ContractViolationError} Si `check` ne renvoie pas un booléen.
+ */
+export async function isAuthorized(principal, requirement, context) {
+  const rules = isNormalized(requirement) ? requirement : normalizeAuthorizationRequirement(requirement);
+
+  if (rules.anyRole.length > 0 && !rules.anyRole.some((role) => principal.roles.includes(role))) {
+    return false;
+  }
+  if (!rules.allPermissions.every((permission) => principal.permissions.includes(permission))) {
+    return false;
+  }
+  if (rules.check === undefined) {
+    return true;
+  }
+
+  const allowed = await rules.check(principal, context);
+  if (typeof allowed !== "boolean") {
+    // Refuser silencieusement masquerait un bug ; accepter une valeur « vraie »
+    // ouvrirait l’accès par erreur. On signale donc le problème.
+    throw new ContractViolationError(DEVELOPER_MESSAGES.authorizationCheckNotBoolean);
+  }
+  return allowed;
+}
+
+/**
+ * @param {NormalizedAuthorizationRequirement} rules
+ * @returns {NormalizedAuthorizationRequirement}
+ */
+function register(rules) {
+  const frozen = Object.freeze(rules);
+  normalizedRequirements.add(frozen);
+  return frozen;
+}
+
+/**
+ * @param {unknown} requirement
+ * @returns {requirement is NormalizedAuthorizationRequirement}
+ */
+function isNormalized(requirement) {
+  return typeof requirement === "object" && requirement !== null && normalizedRequirements.has(requirement);
+}
+
+/**
+ * @param {unknown} value
+ * @returns {readonly string[]}
+ */
+function normalizeNameList(value) {
+  if (value === undefined) {
+    return Object.freeze([]);
+  }
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new ConfigurationError(DEVELOPER_MESSAGES.authorizeRequirementInvalid);
+  }
+  return Object.freeze(value.map(assertAuthorityName));
+}
+
+/**
+ * @param {unknown} name
+ * @returns {string}
+ */
+function assertAuthorityName(name) {
+  if (typeof name !== "string" || name.trim().length === 0 || name.length > MAX_AUTHORITY_LENGTH) {
+    throw new ConfigurationError(DEVELOPER_MESSAGES.authorizeRequirementInvalid);
+  }
+  return name;
+}

package/src/core/contracts/assert-contract.js

@@ -0,0 +1,26 @@
+import { ContractViolationError } from "../errors.js";
+import { contractMissingMethods, contractNotObject } from "../messages.js";
+
+/**
+ * Vérifie que `candidate` expose toutes les méthodes de `methodNames`.
+ *
+ * JavaScript n’a pas d’interfaces : les contrats sont vérifiés par leur forme
+ * au démarrage afin de signaler clairement une dépendance mal configurée.
+ *
+ * @param {unknown} candidate Dépendance injectée.
+ * @param {string} contractName Nom utilisé dans les messages d’erreur.
+ * @param {readonly string[]} methodNames Méthodes exigées par le contrat.
+ * @returns {void}
+ * @throws {ContractViolationError}
+ */
+export function assertImplements(candidate, contractName, methodNames) {
+  if (candidate === null || (typeof candidate !== "object" && typeof candidate !== "function")) {
+    throw new ContractViolationError(contractNotObject(contractName));
+  }
+
+  const members = /** @type {Record<string, unknown>} */ (candidate);
+  const missing = methodNames.filter((name) => typeof members[name] !== "function");
+  if (missing.length > 0) {
+    throw new ContractViolationError(contractMissingMethods(contractName, missing));
+  }
+}