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

package/types/core/contracts/authentication-service.d.ts

@@ -0,0 +1,102 @@
+/**
+ * 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é.
+ */
+export type LoginCredentials = {
+    /**
+     * Identifiant de connexion (e-mail, nom d’utilisateur…).
+     */
+    identifier: string;
+    /**
+     * Mot de passe en clair. Il n’est ni journalisé ni stocké.
+     */
+    password: string;
+};
+export type LoginResult = {
+    /**
+     * Jeton d’accès JWT signé.
+     */
+    accessToken: string;
+    /**
+     * Toujours `"Bearer"`.
+     */
+    tokenType: "Bearer";
+    /**
+     * Durée de vie du jeton, en secondes.
+     */
+    expiresIn: number;
+    /**
+     * Identité authentifiée.
+     */
+    principal: import("./auth-principal.js").AuthPrincipal;
+    /**
+     * Jeton de rafraîchissement (présent si `refreshTokens` est activé).
+     */
+    refreshToken?: string;
+    /**
+     * Durée de vie du jeton de rafraîchissement, en secondes.
+     */
+    refreshExpiresIn?: number;
+};
+export type UserIdInput = string | number | bigint | {
+    toHexString(): string;
+};
+export type AuthenticationService = {
+    /**
+     *   Authentifie un utilisateur. Renvoie `InvalidCredentialsError` pour un
+     *   utilisateur inconnu, un mauvais mot de passe ou un compte désactivé.
+     */
+    login: (credentials: LoginCredentials) => Promise<LoginResult>;
+    /**
+     *   Échange un jeton de rafraîchissement contre une nouvelle paire de jetons (rotation).
+     */
+    refresh: (refreshToken: string) => Promise<LoginResult>;
+    /**
+     *   Révoque la session liée au jeton de rafraîchissement.
+     */
+    logout: (refreshToken: string) => Promise<void>;
+    /**
+     *   Révoque toutes les sessions d’un utilisateur.
+     */
+    revokeAllSessions: (userId: UserIdInput) => Promise<void>;
+    /**
+     *   Vérifie un jeton et contrôle que son utilisateur existe et est toujours actif.
+     */
+    verifyAccessToken: (token: string) => Promise<import("./auth-principal.js").AuthPrincipal>;
+};
+/**
+ * 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/types/core/contracts/password-provider.d.ts

@@ -0,0 +1,32 @@
+export type PasswordProvider = {
+    /**
+     *   Renvoie un hash autonome (algorithme, paramètres et sel encodés dans la chaîne).
+     */
+    hash: (password: string) => Promise<string>;
+    /**
+     *   Renvoie `true` si le mot de passe correspond. La comparaison doit être en
+     *   temps constant et lever `InvalidPasswordHashError` si `hash` est illisible.
+     */
+    verify: (password: string, hash: string) => Promise<boolean>;
+};
+/**
+ * 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 declare const PASSWORD_PROVIDER_METHODS: readonly string[];
+/**
+ * @param {unknown} provider
+ * @returns {asserts provider is PasswordProvider}
+ * @throws {import("../errors.js").ContractViolationError}
+ */
+export declare function assertPasswordProvider(provider: unknown): asserts provider is PasswordProvider;

package/types/core/contracts/refresh-token-store.d.ts

@@ -0,0 +1,105 @@
+export type RefreshTokenRecord = {
+    /**
+     * Empreinte SHA-256 du jeton (64 caractères hexadécimaux). Clé unique.
+     */
+    tokenHash: string;
+    /**
+     * Identifiant de l’utilisateur.
+     */
+    userId: string;
+    /**
+     * Identifiant de la « famille » : tous les jetons issus d’une même connexion.
+     */
+    familyId: string;
+    /**
+     * Date d’expiration, en secondes depuis l’époque Unix.
+     */
+    expiresAt: number;
+};
+export type ConsumedRefreshToken = {
+    userId: string;
+    familyId: string;
+    /**
+     * Secondes depuis l’époque Unix.
+     */
+    expiresAt: number;
+    /**
+     * `true` si le jeton avait déjà été consommé avant cet appel.
+     */
+    alreadyUsed: boolean;
+};
+export type RefreshTokenStore = {
+    /**
+     *   Enregistre un nouveau jeton.
+     */
+    save: (record: RefreshTokenRecord) => Promise<void>;
+    /**
+     *   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.
+     */
+    consume: (tokenHash: string) => Promise<ConsumedRefreshToken | null | undefined>;
+    /**
+     *   Supprime (ou invalide) tous les jetons d’une famille.
+     */
+    revokeFamily: (familyId: string) => Promise<void>;
+    /**
+     *   Supprime (ou invalide) tous les jetons d’un utilisateur.
+     */
+    revokeUser: (userId: string) => Promise<void>;
+};
+/**
+ * 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 declare const REFRESH_TOKEN_STORE_METHODS: readonly string[];
+/**
+ * @param {unknown} store
+ * @returns {asserts store is RefreshTokenStore}
+ * @throws {ContractViolationError}
+ */
+export declare function assertRefreshTokenStore(store: unknown): asserts store is RefreshTokenStore;
+/**
+ * Valide à l’exécution la valeur renvoyée par `consume()`.
+ *
+ * @param {unknown} result
+ * @returns {ConsumedRefreshToken | null}
+ * @throws {ContractViolationError}
+ */
+export declare function normalizeConsumedRefreshToken(result: unknown): ConsumedRefreshToken | null;

package/types/core/contracts/token-provider.d.ts

@@ -0,0 +1,79 @@
+export type IssuedToken = {
+    /**
+     * Jeton sérialisé.
+     */
+    token: string;
+    /**
+     * Identifiant unique du jeton (`jti`).
+     */
+    tokenId: string;
+    /**
+     * Date d’émission, en secondes depuis l’époque Unix.
+     */
+    issuedAt: number;
+    /**
+     * Date d’expiration, en secondes depuis l’époque Unix.
+     */
+    expiresAt: number;
+};
+export type VerifiedTokenClaims = {
+    /**
+     * Identifiant utilisateur (`sub`).
+     */
+    subject: string;
+    /**
+     * Identifiant du jeton (`jti`).
+     */
+    tokenId: string;
+    /**
+     * `iat`, en secondes depuis l’époque Unix.
+     */
+    issuedAt: number;
+    /**
+     * `exp`, en secondes depuis l’époque Unix.
+     */
+    expiresAt: number;
+};
+export type TokenProvider = {
+    issue: (input: {
+        subject: string;
+    }) => Promise<IssuedToken>;
+    verify: (token: string) => Promise<VerifiedTokenClaims>;
+};
+/**
+ * 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 declare const TOKEN_PROVIDER_METHODS: readonly string[];
+/**
+ * @param {unknown} provider
+ * @returns {asserts provider is TokenProvider}
+ * @throws {import("../errors.js").ContractViolationError}
+ */
+export declare function assertTokenProvider(provider: unknown): asserts provider is TokenProvider;

package/types/core/contracts/user-repository.d.ts

@@ -0,0 +1,112 @@
+export type AuthUserRecord = {
+    /**
+     * Identifiant stable, unique et non secret (chaîne, entier ou ObjectId MongoDB) ; converti en chaîne, il devient la revendication JWT `sub`.
+     */
+    id: string | number | bigint | {
+        toHexString(): string;
+    };
+    /**
+     * Hash Argon2id produit par `auth.password.hash()`.
+     */
+    passwordHash: string;
+    /**
+     * Doit valoir exactement `true` pour autoriser la connexion.
+     */
+    isActive: boolean;
+    /**
+     * Rôles de l’utilisateur (par exemple `["admin"]`). Facultatif.
+     */
+    roles?: string[];
+    /**
+     * Permissions de l’utilisateur (par exemple `["orders:write"]`). Facultatif.
+     */
+    permissions?: string[];
+};
+export type NormalizedUserRecord = {
+    id: string;
+    passwordHash: string;
+    isActive: boolean;
+    roles: readonly string[];
+    permissions: readonly string[];
+};
+export type UserRepository = {
+    /**
+     *   Cherche un utilisateur par identifiant de connexion (e-mail, nom…). La
+     *   normalisation (minuscules, espaces) relève de la responsabilité du dépôt.
+     */
+    findByIdentifier: (identifier: string) => Promise<AuthUserRecord | null | undefined>;
+    /**
+     *   Cherche un utilisateur par l’identifiant contenu dans la revendication `sub`.
+     */
+    findById: (id: string) => Promise<AuthUserRecord | null | undefined>;
+};
+/**
+ * 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 declare const USER_REPOSITORY_METHODS: readonly string[];
+/**
+ * Vérifie qu’un dépôt injecté respecte le contrat {@link UserRepository}.
+ *
+ * @param {unknown} repository
+ * @returns {asserts repository is UserRepository}
+ * @throws {ContractViolationError}
+ */
+export declare function assertUserRepository(repository: unknown): asserts repository is UserRepository;
+/**
+ * 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 declare function normalizeUserRecord(record: unknown): NormalizedUserRecord | null;
+/**
+ * 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 declare function toUserIdString(id: unknown): string | null;

package/types/core/errors.d.ts

@@ -0,0 +1,213 @@
+/**
+ * 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
+ */
+/**
+ * Codes d’erreur stables exposés par la bibliothèque.
+ *
+ * @readonly
+ * @enum {string}
+ */
+export declare const AUTH_ERROR_CODES: Readonly<{
+    /** É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 declare const AUTH_FAILURE_REASONS: Readonly<{
+    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 declare class AuthKitError extends Error {
+    /** @type {string} */
+    code: string;
+    /**
+     * @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: string, message: string, options?: {
+        cause?: unknown;
+    });
+    /**
+     * 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(): {
+        name: string;
+        code: string;
+        message: string;
+    };
+}
+/**
+ * Échec de connexion. Le message public ne précise jamais la cause.
+ */
+export declare class InvalidCredentialsError extends AuthKitError {
+    /**
+     * @param {string} [reason] Raison d’audit interne (voir {@link AUTH_FAILURE_REASONS}).
+     */
+    constructor(reason?: string);
+}
+/**
+ * Donnée structurellement invalide reçue à une frontière de confiance.
+ */
+export declare class InvalidInputError extends AuthKitError {
+    /**
+     * @param {string} message
+     */
+    constructor(message: string);
+}
+/**
+ * Jeton d’accès absent de la requête.
+ */
+export declare class TokenMissingError extends AuthKitError {
+    constructor();
+}
+/**
+ * Jeton d’accès rejeté (mal formé, altéré, mauvais émetteur ou audience, utilisateur inconnu ou désactivé…).
+ */
+export declare class InvalidTokenError extends AuthKitError {
+    /**
+     * @param {{ cause?: unknown, reason?: string }} [options]
+     */
+    constructor(options?: {
+        cause?: unknown;
+        reason?: string;
+    });
+}
+/**
+ * Jeton d’accès dont la signature est valide, mais qui a expiré.
+ */
+export declare class TokenExpiredError extends AuthKitError {
+    /**
+     * @param {{ cause?: unknown }} [options]
+     */
+    constructor(options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * 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 declare class AccessDeniedError extends AuthKitError {
+    constructor();
+}
+/**
+ * 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 declare class InvalidRefreshTokenError extends AuthKitError {
+    /**
+     * @param {string} [reason] Raison d’audit interne (voir {@link AUTH_FAILURE_REASONS}).
+     */
+    constructor(reason?: string);
+}
+/**
+ * Configuration manquante, mal formée ou non sûre, levée à l’initialisation.
+ */
+export declare class ConfigurationError extends AuthKitError {
+    /**
+     * @param {string} message
+     */
+    constructor(message: string);
+}
+/**
+ * Dépendance injectée qui n’implémente pas son contrat.
+ */
+export declare class ContractViolationError extends AuthKitError {
+    /**
+     * @param {string} message
+     */
+    constructor(message: string);
+}
+/**
+ * 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 declare class InvalidPasswordHashError extends AuthKitError {
+    /**
+     * @param {{ cause?: unknown }} [options]
+     */
+    constructor(options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * É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 declare class DependencyFailureError extends AuthKitError {
+    /** @type {string} */
+    dependency: string;
+    /**
+     * @param {string} dependency Nom de l’appel qui a échoué, par exemple « UserRepository.findById ».
+     * @param {unknown} cause Erreur d’origine.
+     */
+    constructor(dependency: string, cause: unknown);
+}
+/**
+ * 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 declare function callDependency<T>(dependency: string, call: () => Promise<T> | T): Promise<T>;
+/**
+ * Garde de type pour les erreurs levées par Express AuthKit.
+ *
+ * @param {unknown} error
+ * @returns {error is AuthKitError}
+ */
+export declare function isAuthKitError(error: unknown): error is AuthKitError;

package/types/core/input-limits.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 declare const MAX_IDENTIFIER_LENGTH = 320;
+/** Suffisante pour les phrases de passe, tout en limitant le coût du hachage. */
+export declare const MAX_PASSWORD_LENGTH = 1024;
+/** Les jetons d’accès produits par cette bibliothèque font quelques centaines de caractères. */
+export declare const MAX_TOKEN_LENGTH = 8192;
+/** Les jetons de rafraîchissement émis font 43 caractères ; la marge couvre d’autres formats. */
+export declare const MAX_REFRESH_TOKEN_LENGTH = 512;
+/** Nombre maximal de rôles (ou de permissions) par utilisateur : borne le coût des vérifications. */
+export declare const MAX_AUTHORITIES = 256;
+/** Longueur maximale d’un nom de rôle ou de permission (par exemple « orders:write »). */
+export declare const MAX_AUTHORITY_LENGTH = 128;