@aventii/auth (1.1.0)

Published 2026-11-01 12:55:51 +00:00 by Valentin

Installation

@aventii:registry=
npm install @aventii/auth@1.1.0
"@aventii/auth": "1.1.0"

About this package

@aventii/auth

Noyau générique d'inscription, d'authentification, de gestion des identifiants et des sessions pour les microservices Node.js Aventii.

Le package sait créer et authentifier un compte. Il ne sait pas ce que ce compte fait dans le produit.

Le package est issu du mécanisme Access/PMC, sans intégrer les règles métier propres à Rapidoo.

Installation

npm install @aventii/auth
npm install mongoose  # repository Mongoose
# ou : npm install mongodb  # repository MongoDB natif
npm install express   # uniquement pour le routeur HTTP

Node.js >= 22, CommonJS. express, mongodb et mongoose sont des dépendances peer optionnelles : installer celles correspondant à l'utilisation réelle.

Périmètre

Inscription en deux étapes, salt anti-énumération, validation mail et téléphone, login, access/refresh tokens persistants, rotation des refresh tokens, logout, oubli/réinitialisation de mot de passe, validation de token, middleware et routeur HTTP, désactivation de compte, nettoyage des documents expirés.

Hors périmètre : profil métier, balance, transactions, fichiers, documents d'identité, notifications concrètes, pays, âge, CGU, devises, Mobile Money, rôles prédéfinis, audit persistant, récupération de secrets, CORS, rate limiting et Proof of Work.

API publique

const {
  createAuth,
  createAuthRouter,
  createAuthMiddleware,
  createMongoAuthRepository,
  createMongooseAuthRepository,
  accessTokenSchema,
  refreshTokenSchema,
  createVersionedPepperProvider,
  AUTH_ACCOUNT_STATUS,
  AuthError,
  normalizeMail,
  generateRegistrationToken,
  hashOpaqueToken,
  generatePhoneValidationCode
} = require('@aventii/auth');

Attention à l'optionalité de Mongoose : l'entrée principale du package doit pouvoir être chargée sans mongoose installé pour les consommateurs MongoDB natifs. Les exports Mongoose doivent donc être chargés de façon différée, ou par un point d'entrée distinct. Une déclaration peerDependenciesMeta.optional ne suffit pas à garantir cela.

Architecture et responsabilités

Le cœur d'authentification ne dépend d'aucun moteur de persistance. Le microservice fournit un repository, les secrets, le fingerprint et les règles métier. @aventii/db peut gérer les connexions et leur renouvellement ; @aventii/security fournit les primitives de signature/vérification ; @aventii/link peut être utilisé pour les envois mail. Aucune de ces intégrations métier n'est imposée par le repository.

Statuts de compte : active, waitingForMailValidation, disabled, exposés par AUTH_ACCOUNT_STATUS. Les identifiants techniques restent des _id: ObjectId MongoDB ; aucun UUID n'est introduit.

const auth = createAuth({
  repository,
  tokenSecret,
  fakeSaltSecret,
  pepperProvider,
  generateFingerprint
});

Options d'extension : policies, actions, hooks, buildAccessTokenClaims, normalizeMail, timing, enforceFingerprint. Le package ne lit pas lui-même process.env et ne contacte pas de service de secrets.

Contrat repository

Les deux repositories exposent le même contrat :

findUserByMail · findUserById · createUser · updateUser
completeRegistration · prepareMailValidation · consumeMailValidationToken
consumePhoneValidationCode · disableUser
createAccessToken · findAccessTokenById · findReusableAccessToken
invalidateAccessToken · deleteExpiredAccessTokens
createRefreshToken · findReusableRefreshToken · findValidRefreshTokenById
extendRefreshToken · revokeRefreshToken · revokeRefreshTokensByUserId
 deleteExpiredRefreshTokens · deleteExpiredIncompleteRegistrations
 deleteExpiredUnverifiedMailRegistrations

MongoDB natif

const repository = createMongoAuthRepository({
  getUsersCollection: () => database.getDb('Auth').collection('Users'),
  getAccessTokensCollection: () => database.getDb('Auth').collection('Tokens'),
  getRefreshTokensCollection: () => database.getDb('Auth').collection('RefreshTokens')
});

Mongoose

const {
  createMongooseAuthRepository,
  accessTokenSchema,
  refreshTokenSchema
} = require('@aventii/auth');
const userSchema = require('./userSchema');

// Retourne la connexion Mongoose courante vers la base Auth.
function getAuthConnection() {
  return database.getDb('Auth');
}

function getModel(name, schema) {
  const connection = getAuthConnection();
  return connection.models[name] || connection.model(name, schema);
}

const repository = createMongooseAuthRepository({
  getUserModel: () => getModel('User', userSchema),
  getAccessTokenModel: () => getModel('AccessToken', accessTokenSchema),
  getRefreshTokenModel: () => getModel('RefreshToken', refreshTokenSchema)
});

Cet exemple suppose que database.getDb('Auth') retourne une connexion Mongoose (par exemple avec l'adapter Mongoose de @aventii/db), et non un objet Db du driver natif.

Les getters sont évalués à chaque opération : aucun modèle associé à une connexion remplacée ne doit être conservé par le repository. Les lectures utilisent lean() et les créations sont converties en objets simples. Les schémas accessTokenSchema et refreshTokenSchema ciblent respectivement les collections Tokens et RefreshTokens ; ils utilisent strict: false, versionKey: false, timestamps: false et minimize: false. Le schéma utilisateur appartient au microservice.

Pour les tokens, userId reste une chaîne, expiresAt un timestamp numérique en millisecondes et deleteAt une Date. Les deux repositories préservent volontairement l'absence de filtre valid dans findReusableAccessToken et findAccessTokenById, par compatibilité historique. Les transitions de complétion d'inscription et de validation mail sont atomiques.

Les champs de validation du courriel sont mailValidationTokenHash, mailValidationExpiresAt et mailValidatedAt. Les anciens champs emailValidation*, s'ils existent en base, nécessitent une migration gérée par le consommateur.

Normalisation mail et salt

normalizeMail('John+promo@Example.com'); // 'john@example.com'

Le normaliseur supprime les espaces périphériques, met en minuscules et retire le +tag du local-part. Il peut être remplacé via createAuth({ normalizeMail }).

register() génère un salt aléatoire de 16 octets (32 caractères hexadécimaux). getSalt(mail) renvoie le salt réel si le compte existe ; sinon, un faux salt stable : les 32 premiers caractères hexadécimaux de HMAC-SHA256(fakeSaltSecret, mail brut).

Inscription

const result = await auth.register({
  mail: 'alice@example.com',
  accountData: { firstName: 'Alice', nationality: 'CM' }
});

await auth.completeRegistration({ mail, clientHash, registrationToken });

accountData reste opaque. Le cœur contrôle mail, salt, status, registrationTokenHash, registrationTokenExpiresAt et registrationTokenAttempts. Le token d'inscription brut contient 32 octets aléatoires ; seul son SHA-256 est persisté. Un compte déjà existant entraîne ACCOUNT_ALREADY_EXISTS.

Par défaut : token valable 60 s, 5 tentatives maximum ; dès la deuxième erreur, expiration raccourcie à 3 s ; à la cinquième, token neutralisé. L'échec de la mise à jour secondaire des tentatives est ignoré par compatibilité.

completeRegistration exige un clientHash hexadécimal de 64 caractères, vérifie le token et son expiration, puis calcule bcrypt(clientHash + pepper courant) avec un work factor de 12 par défaut. Le repository effectue une mise à jour conditionnelle atomique, renseigne registrationCompletedAt, hash et pepperVersion, puis supprime les champs du token d'inscription.

Le produit reste responsable de la validation de firstName, lastName, date de naissance, nationalité, téléphone, CGU, balance initiale, devise, etc., avant register().

Pepper versionné

const pepperProvider = createVersionedPepperProvider({
  currentVersion: () => Number(config.PASSWORD_PEPPER_CURRENT),
  sources: [
    version => config[`PASSWORD_PEPPER_V${version}`],
    version => keyService.get(`SERVER_PEPPER_V${version}`),
    () => hsm.getSecret('AUTH_PEPPER')
  ]
});

sources est une liste ordonnée non vide de fonctions recevant chacune la version demandée. Elles retournent une chaîne non vide, directement ou via une promesse, et sont résolues en parallèle. Le pepper final est SHA-256 des composantes préfixées par leur longueur en octets UTF-8, dans l'ordre déclaré. Aucun cache, mécanisme « local/remote » ou clearRemoteCache() n'est intégré : les sources gèrent elles-mêmes leur cache.

Lors d'un login réussi avec une ancienne pepperVersion, le hash peut être recalculé avec la version courante. Attention : cette dérivation par préfixage de longueur n'est pas compatible avec une ancienne dérivation par concaténation directe. Les comptes historiques nécessitent une stratégie de vérification de l'ancien pepper avant migration ; le seul changement de version ne suffit pas.

Validation mail et téléphone

Par défaut, mailVerificationRequired: true : le compte est créé avec le statut waitingForMailValidation. Après complétion, un token mail aléatoire de 32 octets est généré, son SHA-256 est stocké pour 24 h, et actions.deliverMailValidation est appelé en best-effort. Une panne de livraison ne défait pas la complétion.

await auth.validateMail(token);
await auth.validatePhone({ userId, code });

La validation mail consomme atomiquement le token non expiré, active le compte, supprime les champs du token et déclenche onMailValidated en best-effort. Si la validation mail est désactivée, le compte est directement active et la complétion déclenche onRegistrationCompleted.

Pour le téléphone, les chemins par défaut sont phoneValidationToken et verification.verifiedPhone, configurables par phoneTokenField et phoneVerifiedField. generatePhoneValidationCode() produit xxxx-xxxx. La livraison du code appartient au produit.

Login, policies et audit

const result = await auth.login({ mail, password, request, context });

Le cœur recherche le compte normalisé, appelle éventuellement policies.login en phase beforeCredential, vérifie le hash avec bcrypt et le pepper versionné, contrôle le statut, appelle la phase afterCredential, calcule le fingerprint, puis émet les access et refresh tokens. password représente la valeur de credential reçue du client, indépendamment de sa dérivation côté frontend.

Les politiques métier (pays, portail admin, rôles) sont injectées par le produit. hooks.onAuthEvent est best-effort ; les raisons possibles incluent USER_NOT_FOUND, ACCOUNT_NOT_VALIDATED, WRONG_PASSWORD, MAIL_NOT_VALIDATED, ACCOUNT_DISABLED. La persistance de l'audit n'est pas fournie.

Access tokens

Signature et vérification via @aventii/security. Champs réservés : userId, issuedAt, expiresAt, deleteAt, deviceFingerprint, passwordVersion. Durée par défaut : 1 h ; conservation pour purge : 7 j. Les claims supplémentaires sont injectés par buildAccessTokenClaims({ user, context }).

Un access token non expiré peut être réutilisé pour le même utilisateur et le même fingerprint. Compatibilité historique : les repositories ne filtrent pas valid dans les recherches d'access tokens. enforceFingerprint vaut true par défaut et peut être désactivé explicitement.

Refresh tokens et logout

Les refresh tokens sont référencés par leur _id MongoDB, transmis dans le cookie. Champs : userId, deviceFingerprint, passwordVersion, issuedAt, expiresAt, deleteAt, valid.

Durée par défaut : 15 j ; conservation pour purge : 45 j. Au login, un refresh token valide et non expiré du même utilisateur/fingerprint/version peut être réutilisé et prolongé.

await auth.refresh({ refreshTokenId, request, context });
await auth.logout(refreshTokenId);

Le refresh exige valid: true, un fingerprint correspondant, une expiration future, un compte admissible et une passwordVersion identique. En succès, l'ancien refresh est révoqué puis une nouvelle paire est émise. Un identifiant mal formé est traduit en REFRESH_TOKEN_INVALID (401). Une révocation positionne valid: false, expiresAt à maintenant et deleteAt à maintenant + 30 j. Le logout est best-effort, pour permettre le nettoyage des cookies même en cas d'échec de persistance.

Mot de passe oublié et réinitialisation

await auth.requestPasswordReset(mail);
await auth.resetPassword({ mail, token, newHash });

Pour un compte absent ou désactivé, la demande est acceptée sans divulguer son existence. Pour un compte actif, un token aléatoire de 32 octets est généré ; seul son SHA-256 est enregistré pour 15 min, avant la livraison. deliverPasswordReset, si fourni, est bloquant : une erreur de livraison peut remonter après persistance.

La réinitialisation vérifie statut, expiration et token avec timingSafeEqual, remplace le hash par bcrypt(newHash + pepper courant), met à jour pepperVersion, incrémente passwordVersion et neutralise resetToken et resetExpires. Les refresh tokens portant une ancienne version du mot de passe sont rejetés.

Vérification de token et désactivation

const payload = await auth.verifyAccessToken(token, request);
const { payload: claims, user } = await auth.authenticate(token, request);
await auth.validateToken({ token, request, context });

await auth.disableAccount({ actorUserId, targetUserId, password, context });

validateToken applique éventuellement policies.token (issuer, origine, portail, etc.). La désactivation est limitée à soi-même par défaut, sauf autorisation via policies.disableAccount. Le credential de l'acteur est vérifié ; le compte cible passe à disabled, disabledAt est renseigné et ses refresh tokens sont invalidés. Les access tokens ne sont pas invalidés en masse, conformément au comportement historique.

Nettoyage

await auth.cleanupExpired();
await auth.cleanupExpired({ unverifiedMailBefore: new Date('2026-01-01') });

Aucun scheduler n'est installé. Le nettoyage supprime les access/refresh tokens expirés, les inscriptions initiales incomplètes et, sur demande, les comptes dont la validation mail est en attente depuis avant la date indiquée.

Hooks et actions

Hooks best-effort : onRegistrationCompleted, onMailValidated, onAccountDisabled, onAuthEvent, onHookError.

Actions : deliverMailValidation (best-effort), deliverPasswordReset (bloquante). Les services concrets d'envoi sont injectés par le microservice.

Middleware HTTP

const authMiddleware = createAuthMiddleware({ auth });

Le token est lu par défaut dans req.cookies.token. Après succès, req.user et req.auth = { user, payload } sont définis. Un bypass externe peut être injecté pour les appels internes ; le package ne connaît pas leur protocole.

Routeur Express

const router = createAuthRouter({
  auth,
  resolveRegistration: async req => {
    const accountData = validateMyProductRegistration(req);
    return { mail: accountData.mail, accountData };
  },
  cookieOptionsResolver: req => ({
    httpOnly: true,
    secure: true,
    sameSite: 'none',
    domain: resolveDomain(req),
    path: '/'
  })
});

Routes relatives :

GET    /salt
POST   /register
POST   /register/complete
POST   /mail/validate
POST   /login
POST   /refresh
POST   /logout
POST   /phone/validate/:id
POST   /password/forgot
POST   /password/reset
POST   /token/validate
PATCH  /account/disable/:id

Cookies par défaut : token (1 h) et refresh_token (15 j). Les tokens privés de validation mail et de réinitialisation ne sont jamais exposés dans les réponses HTTP. La validation de token n'impose aucune notion d'origine propre au produit.

Erreurs

AuthError expose code, status, userId, details, cause. Les erreurs de construction de contrat utilisent TypeError. Les identifiants techniques invalides produisent INVALID_ID (400), sauf traduction spécifique des refresh tokens en erreur 401.

Tests

npm test

La suite utilise node:test et node:assert/strict, sans base MongoDB, Express réel ni service distant. Les tests couvrent le cœur, les cas d'échec, les politiques, les tokens, les repositories Mongo natif et Mongoose (modèles simulés), la résolution dynamique des modèles, le pepper versionné, le routeur et le middleware.

Évolution de la persistance

Deux implémentations existent : MongoDB natif et Mongoose. Le contrat repository permettrait d'ajouter un moteur SQL à l'avenir, mais aucun adapter SQL n'est fourni aujourd'hui.

Intégration dans Rapidoo

Le microservice fournit principalement resolveRegistration, policies.login, policies.token, policies.disableAccount, buildAccessTokenClaims, les actions de livraison mail, les hooks d'audit et de cycle de vie, cookieOptionsResolver et le bypass éventuel du middleware. Le protocole d'authentification reste dans @aventii/auth.

Auth prouve qu'un compte peut accéder au système. Le microservice compose cette capacité avec le métier du produit.

Dependencies

Dependencies

ID Version
@aventii/security ^1.2.0
bcrypt ^6.0.0

Peer Dependencies

ID Version
express >=5
mongodb >=6
mongoose >=8
Details
npm
2026-11-01 12:55:51 +00:00
14
UNLICENSED
latest
23 KiB
Assets (1)
Versions (2) View all
1.1.0 2026-11-01
1.0.0 2026-08-25