@aventii/security (1.4.0)

Published 2026-10-20 10:55:52 +00:00 by Valentin

Installation

@aventii:registry=
npm install @aventii/security@1.4.0
"@aventii/security": "1.4.0"

About this package

@aventii/security

Primitives de sécurité communes aux services Aventii.

Ce package regroupe des mécanismes génériques destinés à plusieurs microservices et produits. Il ne contient aucune logique métier et ne dépend ni d'une base de données particulière, ni d'une topologie réseau, ni d'un service Aventii spécifique.

Installation

Le package est distribué sur le registre npm privé Aventii :

npm install @aventii/security

L'accès au registre nécessite une configuration npm Aventii valide.

Principes

Le package fournit des primitives configurables. Le service consommateur reste responsable de sa politique de sécurité et injecte les dépendances propres à son environnement. La vérification des tokens ne suppose pas MongoDB ; la vérification du Proof of Work ne présume pas des routes protégées.

Tokens internes

createInternalTokenUtils fournit les mécanismes d'authentification des communications internes entre services.

const { createInternalTokenUtils } = require('@aventii/security');

const { getAuthToken, isValidToken, checkAuthTokenValidity } = createInternalTokenUtils({
    secret: process.env.AUTH_TOKEN,
    toleranceHours: 1
});

Le token est dérivé par HMAC-SHA256 à partir du secret injecté et d'une période UTC au format YYYYMMDDHH. La tolérance horaire permet d'accepter les périodes adjacentes. Le mécanisme ne fournit pas, à lui seul, de protection contre le rejeu pendant la fenêtre acceptée.

Tokens utilisateur

Signature

createUserTokenSigner produit un token signé par HMAC-SHA256, selon le format propre au package : base64(JSON.stringify(payload)).signatureHex.

const { createUserTokenSigner } = require('@aventii/security');
const { signToken } = createUserTokenSigner({ secret: process.env.HMAC_SECRET });
const signedToken = signToken(payload);

Le payload est encodé, pas chiffré : il ne doit pas contenir de secret ou de donnée confidentielle.

Vérification

createUserTokenVerifier vérifie les tokens utilisateur sans dépendre de leur mécanisme de stockage.

const { createUserTokenVerifier } = require('@aventii/security');

const { verifyToken } = createUserTokenVerifier({
    secret: process.env.HMAC_SECRET,
    findToken: async payload => tokenRepository.findById(payload._id)
});

Le package prend en charge :

  • le format du token et le décodage du payload ;
  • la signature HMAC-SHA256 ;
  • la recherche du document persistant via findToken ;
  • l'expiration du payload signé et du document persistant ;
  • le refus d'un document persistant marqué valid: false ;
  • le contrôle optionnel du fingerprint ;
  • l'instrumentation optionnelle des erreurs.

Un document absent, expiré ou explicitement révoqué entraîne le refus du token. Modifier l'expiration persistée permet donc de raccourcir sa validité sans modifier le payload signé. Les champs expiresAt sont des timestamps numériques en millisecondes depuis l'époque Unix. L'expiration est atteinte dès Date.now() >= expiresAt.

Le renouvellement automatique des access tokens, la gestion des refresh tokens, les cookies et la politique de session appartiennent au consommateur (par exemple @aventii/auth), pas à @aventii/security.

Fingerprint utilisateur

Le contrôle du fingerprint est optionnel.

const { generateFingerprintFromRequest, createUserTokenVerifier } = require('@aventii/security');
const { verifyToken } = createUserTokenVerifier({
    secret,
    findToken,
    enforceFingerprint: true,
    generateFingerprint: req => generateFingerprintFromRequest(req)
});

Lorsque enforceFingerprint vaut true, generateFingerprint doit être fourni. Le fingerprint est une mesure complémentaire et non une preuve cryptographique d'identité.

Fingerprint

generateDeviceFingerprint produit une empreinte SHA-256 déterministe à partir de données explicites.

const { generateDeviceFingerprint } = require('@aventii/security');
const fingerprint = generateDeviceFingerprint({
    userAgent: 'Mozilla/5.0',
    ip: '127.0.0.1',
    timezone: 'Europe/Paris'
});

generateFingerprintFromRequest adapte le calcul à une requête HTTP.

const { generateFingerprintFromRequest } = require('@aventii/security');
const fingerprint = generateFingerprintFromRequest(req, {
    timezoneHeader: 'x-timezone'
});

Par défaut, le header de fuseau horaire est timezone. Une variation d'IP, de User-Agent ou de fuseau horaire peut modifier l'empreinte.

Proof of Work

createProofOfWork fournit un mécanisme générique de vérification de Proof of Work HTTP.

const { createProofOfWork } = require('@aventii/security');
const { verifyProof, proofOfWorkMiddleware, maybePow } = createProofOfWork({
    difficulty: 3,
    timestampToleranceMs: 15000
});

La difficulté peut être fixe (difficulty: 3) ou dynamique (difficulty: () => getCurrentPowLevel()). Le package ne décide pas quand le PoW doit être activé ; le consommateur peut injecter une fonction skip.

createProofOfWork({
    difficulty: 3,
    skip: req => req.path.startsWith('/public/')
});

verifyProof permet de tester le mécanisme indépendamment d'Express. Le PoW ne comporte pas de mécanisme anti-rejeu autonome ; une preuve valide peut être réutilisée pendant sa fenêtre de validité si le consommateur ne prévoit pas d'autres protections.

Whitelist IP

createIpWhitelistMiddleware crée un middleware de restriction par adresse IP.

const { createIpWhitelistMiddleware } = require('@aventii/security');
const ipWhitelist = createIpWhitelistMiddleware({
    allowedIps: ['127.0.0.1', '10.0.0.10']
});

Une normalisation peut être injectée :

createIpWhitelistMiddleware({
    allowedIps,
    normalizeIp: ip => ip.replace(/^::ffff:/, '')
});

Les comparaisons portent sur des adresses exactes normalisées, pas sur des plages CIDR. La fiabilité de req.ip dépend de la configuration des proxies du consommateur.

Chiffrement

createCryptoService fournit un chiffrement de données indépendant du stockage et du service de distribution des clés. Il utilise X25519, HKDF-SHA256 et AES-256-GCM. Les clés sont récupérées à l'initialisation par une fonction injectée.

const { createCryptoService } = require('@aventii/security');

const security = createCryptoService({
    serviceId: 'my-service',
    additionalServices: ['other-service'],
    getKeys: async serviceId => ({
        publicKey: await getPublicKey(serviceId),
        privateKey: await getPrivateKey(serviceId),
        keyVersion: 1
    })
});

await security.init();
const encrypted = security.encrypt('Donnée confidentielle');
const decrypted = security.decrypt(encrypted);

getKeys est implémenté par le consommateur. Le package ne contacte aucun service distant. Après init(), encrypt() et decrypt() sont synchrones, sans accès réseau.

Le résultat est un objet compatible JSON contenant le destinataire, la version de clé et les métadonnées authentifiées nécessaires au déchiffrement. Le déchiffrement sélectionne la clé privée correspondant au destinataire de l'enveloppe, parmi les clés chargées.

Limites actuelles :

  • Seules les chaînes de caractères sont acceptées.
  • Une seule version de clé est chargée par service.
  • Le chiffrement est non déterministe : deux valeurs identiques produisent des résultats différents.
  • Le chiffrement ne permet pas de rechercher directement une valeur par égalité en base de données.
  • Les autorisations d'accès aux clés relèvent du consommateur.
  • Les services supplémentaires déclarés via additionalServices chargent également leurs clés privées : cette configuration doit être limitée aux services que le processus est autorisé à déchiffrer.

Instrumentation

Les primitives acceptent une instrumentation optionnelle, injectée par le consommateur.

createUserTokenVerifier({ secret, findToken, recordError, incrementIpError });
createProofOfWork({ recordError, incrementIpError });

L'absence d'instrumentation n'empêche pas leur fonctionnement. Les catégories d'erreurs peuvent notamment distinguer les tokens manquants, malformés, à signature invalide, absents du stockage, expirés ou révoqués, selon la version effective du vérificateur.

API

Le package expose :

createInternalTokenUtils
createUserTokenSigner
createUserTokenVerifier
generateDeviceFingerprint
generateFingerprintFromRequest
createProofOfWork
createIpWhitelistMiddleware
createCryptoService

Les fonctions de création retournent des instances configurées pour le service consommateur.

Hors périmètre

@aventii/security ne décide pas :

  • quelles routes sont publiques, privées ou réservées aux administrateurs ;
  • où sont stockés les tokens et comment sont renouvelées les sessions ;
  • comment sont obtenus ou renouvelés les secrets ;
  • quels microservices sont exposés sur le réseau ;
  • quand le PoW doit être activé ;
  • comment les événements de sécurité sont persistés.

Ces décisions appartiennent au produit ou au service consommateur.

Tests

npm test

Les tests doivent couvrir séparément les contrats des primitives :

  • tokens internes et utilisateur, dont expiration et révocation persistées ;
  • signatures invalides et altérations ;
  • fingerprints ;
  • Proof of Work ;
  • whitelist IP ;
  • chiffrement X25519 / HKDF-SHA256 / AES-256-GCM ;
  • altération des enveloppes, mauvaise clé et incohérence des paires ;
  • initialisation, concurrence, échecs et reprises de createCryptoService.

Les dépendances propres aux applications consommatrices sont injectées et testées dans ces applications. La liste ci-dessus définit la couverture attendue et ne certifie pas que chaque scénario dispose déjà d'un test automatisé.

Dependencies

Development Dependencies

ID Version
jest ^30.0.0
Details
npm
2026-10-20 10:55:52 +00:00
25
UNLICENSED
9.5 KiB
Assets (1)
Versions (9) View all
1.5.1 2026-11-04
1.5.0 2026-11-04
1.4.0 2026-10-20
1.3.0 2026-10-14
1.2.0 2026-08-18