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

package/types/core/messages.d.ts

@@ -0,0 +1,141 @@
+/**
+ * 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
+ */
+/**
+ * Messages publics : ils peuvent être renvoyés tels quels aux clients HTTP.
+ * Ils ne révèlent jamais d’information interne.
+ */
+export declare const PUBLIC_MESSAGES: Readonly<{
+    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 declare function fieldRequired(field: string): string;
+/**
+ * @param {string} field
+ * @param {number} maxLength
+ * @returns {string}
+ */
+export declare function fieldTooLong(field: string, maxLength: number): string;
+/**
+ * Messages destinés aux développeurs (configuration, contrats, pannes).
+ * Ils expliquent toujours comment corriger le problème.
+ */
+export declare const DEVELOPER_MESSAGES: Readonly<{
+    unsupportedPasswordHash: string;
+    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.";
+    secretRequired: "L’option « jwt.secret » est obligatoire. Générez-en un avec : npx express-authkit secret (ou : node -e \"console.log(require('node:crypto').randomBytes(48).toString('base64url'))\").";
+    secretWrongType: "L’option « jwt.secret » doit être un texte ou un Uint8Array.";
+    secretPlaceholder: "L’option « jwt.secret » ressemble à une valeur d’exemple. Générez-en un avec : npx express-authkit secret (ou : node -e \"console.log(require('node:crypto').randomBytes(48).toString('base64url'))\").";
+    secretRepetitive: "L’option « jwt.secret » est trop répétitive pour être aléatoire. Générez-en un avec : npx express-authkit secret (ou : node -e \"console.log(require('node:crypto').randomBytes(48).toString('base64url'))\").";
+    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\".";
+    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: string;
+    repositoryRecordIsActive: string;
+    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: string;
+    refreshStoreRequired: string;
+    refreshTokensDisabled: string;
+    authorizeRequirementInvalid: string;
+    authorizationCheckNotBoolean: "La fonction « check » de authorize() doit renvoyer true ou false (éventuellement via une promesse).";
+    issuedTokenInvalid: string;
+}>;
+/**
+ * @param {number} maxLength
+ * @returns {string}
+ */
+export declare function subjectInvalid(maxLength: number): string;
+/**
+ * @param {string} name Nom de l’option, par exemple « jwt » ou « createAuthKit(options) ».
+ * @returns {string}
+ */
+export declare function notPlainObject(name: string): string;
+/**
+ * @param {string} name
+ * @param {string[]} unknownKeys
+ * @param {readonly string[]} allowedKeys
+ * @returns {string}
+ */
+export declare function unknownOptions(name: string, unknownKeys: string[], allowedKeys: readonly string[]): string;
+/**
+ * @param {string} name
+ * @returns {string}
+ */
+export declare function optionRequiredString(name: string): string;
+/**
+ * @param {string} name
+ * @param {number} maxLength
+ * @returns {string}
+ */
+export declare function optionTooLong(name: string, maxLength: number): string;
+/**
+ * @param {string} name
+ * @param {number} min
+ * @param {number} max
+ * @returns {string}
+ */
+export declare function optionIntegerRange(name: string, min: number, max: number): string;
+/**
+ * @param {readonly string[]} algorithms
+ * @returns {string}
+ */
+export declare function unsupportedAlgorithm(algorithms: readonly string[]): string;
+/**
+ * @param {number} minBytes
+ * @returns {string}
+ */
+export declare function secretTooShort(minBytes: number): string;
+/**
+ * @param {string} contractName
+ * @returns {string}
+ */
+export declare function contractNotObject(contractName: string): string;
+/**
+ * @param {string} contractName
+ * @param {string[]} missingMethods
+ * @returns {string}
+ */
+export declare function contractMissingMethods(contractName: string, missingMethods: string[]): string;
+/**
+ * @param {string} dependency Par exemple « UserRepository.findById ».
+ * @returns {string}
+ */
+export declare function dependencyFailed(dependency: string): string;
+/**
+ * @param {string} method Par exemple « authenticate ».
+ * @returns {string}
+ */
+export declare function middlewareFactoryMisuse(method: string): string;
+/**
+ * @param {string} field « roles » ou « permissions ».
+ * @param {number} maxItems
+ * @param {number} maxLength
+ * @returns {string}
+ */
+export declare function repositoryRecordAuthorities(field: string, maxItems: number, maxLength: number): string;

package/types/core/refresh-token-service.d.ts

@@ -0,0 +1,31 @@
+export type RefreshTokenStore = import("./contracts/refresh-token-store.js").RefreshTokenStore;
+export type ConsumedRefreshToken = import("./contracts/refresh-token-store.js").ConsumedRefreshToken;
+/**
+ * @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 declare function createRefreshTokenService({ store, expiresInSeconds }: {
+    store: RefreshTokenStore;
+    expiresInSeconds: number;
+}): Readonly<{
+    issue: (userId: string, familyId?: string) => Promise<{
+        token: string;
+        expiresIn: number;
+    }>;
+    consume: (token: unknown) => Promise<ConsumedRefreshToken>;
+    revokeSessionOf: (token: unknown) => Promise<void>;
+    revokeFamily: (familyId: string) => Promise<void>;
+    revokeUser: (userId: string) => Promise<void>;
+}>;

package/types/factory/create-auth-kit.d.ts

@@ -0,0 +1,52 @@
+export type PasswordApi = Readonly<{
+    hash: (password: string) => Promise<string>;
+    verify: (password: string, hash: string) => Promise<boolean>;
+}>;
+export type AuthKit = 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;
+}>;
+/**
+ * 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 declare function createAuthKit(options: import("../config/auth-kit-options.js").AuthKitOptions): AuthKit;

package/types/index.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 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";
+export type AuthKit = import("./factory/create-auth-kit.js").AuthKit;
+export type AuthKitOptions = import("./config/auth-kit-options.js").AuthKitOptions;
+export type JwtOptions = import("./config/jwt-options.js").JwtOptions;
+export type PasswordOptions = import("./config/password-options.js").PasswordOptions;
+export type UserRepository = import("./core/contracts/user-repository.js").UserRepository;
+export type AuthUserRecord = import("./core/contracts/user-repository.js").AuthUserRecord;
+export type PasswordProvider = import("./core/contracts/password-provider.js").PasswordProvider;
+export type TokenProvider = import("./core/contracts/token-provider.js").TokenProvider;
+export type IssuedToken = import("./core/contracts/token-provider.js").IssuedToken;
+export type VerifiedTokenClaims = import("./core/contracts/token-provider.js").VerifiedTokenClaims;
+export type AuthenticationService = import("./core/contracts/authentication-service.js").AuthenticationService;
+export type LoginCredentials = import("./core/contracts/authentication-service.js").LoginCredentials;
+export type LoginResult = import("./core/contracts/authentication-service.js").LoginResult;
+export type AuthPrincipal = import("./core/contracts/auth-principal.js").AuthPrincipal;
+export type UserIdInput = import("./core/contracts/authentication-service.js").UserIdInput;
+export type AuthorizationRequirement = import("./core/authorization.js").AuthorizationRequirement;
+export type RefreshTokenOptions = import("./config/refresh-token-options.js").RefreshTokenOptions;
+export type RefreshTokenStore = import("./core/contracts/refresh-token-store.js").RefreshTokenStore;
+export type RefreshTokenRecord = import("./core/contracts/refresh-token-store.js").RefreshTokenRecord;
+export type ConsumedRefreshToken = import("./core/contracts/refresh-token-store.js").ConsumedRefreshToken;
+/**
+ * @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/types/providers/argon2-password-provider.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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 declare function createArgon2PasswordProvider(options?: import("../config/password-options.js").PasswordOptions): import("../core/contracts/password-provider.js").PasswordProvider;

package/types/providers/in-memory-refresh-token-store.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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 declare function createInMemoryRefreshTokenStore(): import("../core/contracts/refresh-token-store.js").RefreshTokenStore;

package/types/providers/jwt-token-provider.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Crée un {@link import("../core/contracts/token-provider.js").TokenProvider}
+ * qui émet et vérifie des jetons d’accès JWT signés en HMAC avec `jose`.
+ *
+ * Les jetons ne contiennent que des revendications standard (`sub`, `iss`,
+ * `aud`, `iat`, `exp`, `jti`) : aucune donnée personnelle ou sensible n’est
+ * placée dans la charge utile, qui est encodée mais non chiffrée.
+ *
+ * @param {import("../config/jwt-options.js").JwtOptions} options
+ * @returns {import("../core/contracts/token-provider.js").TokenProvider}
+ * @throws {import("../core/errors.js").ConfigurationError}
+ */
+export declare function createJwtTokenProvider(options: import("../config/jwt-options.js").JwtOptions): import("../core/contracts/token-provider.js").TokenProvider;