@astratra/security 1.15.0 → 1.15.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -206,7 +206,32 @@ app.delete('/api/projects/:id', authorizeRoles('owner', 'admin'), handler);
206
206
  ```
207
207
 
208
208
  Par défaut, le middleware limite la vérification à `HS256`. Si ton application
209
- utilise un autre algorithme, configure explicitement `algorithms`.
209
+ utilise un autre algorithme, configure explicitement `algorithms`. Un jeton émis
210
+ plus d'une minute dans le futur (`clockTolerance` pour un autre écart) est refusé :
211
+ sinon il échapperait à « déconnecter partout ».
212
+
213
+ ### Les jetons eux-mêmes, sans dépendance
214
+
215
+ Depuis la 1.15.1, les jetons sont signés et vérifiés par le paquet (`signJwt`,
216
+ `verifyJwt`, `decodeJwt`), sans jsonwebtoken : même forme de jeton, mêmes options,
217
+ mêmes erreurs (`JsonWebTokenError`, `TokenExpiredError`, `NotBeforeError`),
218
+ comparés à jsonwebtoken 9 sur 120 signatures et 936 vérifications enregistrées.
219
+ HS256/384/512, RS256/384/512, PS256/384/512, ES256/384/512.
220
+
221
+ ```js
222
+ const { signJwt, verifyJwt } = require('@astratra/security');
223
+
224
+ const token = signJwt({ id: user.id, role: user.role }, process.env.JWT_SECRET, { expiresIn: '15m', issuer: 'mon-app' });
225
+ const claims = verifyJwt(token, process.env.JWT_SECRET, { algorithms: ['HS256'], issuer: 'mon-app' });
226
+ ```
227
+
228
+ Plus strict que jsonwebtoken, sans regret : `algorithms` est obligatoire et « none »
229
+ n'existe pas ; une clé ne sert qu'à sa famille (une clé publique n'est jamais un
230
+ secret HMAC, une clé EC doit être de la courbe de l'algorithme, une clé RSA d'au
231
+ moins 2 048 bits) ; chaque morceau doit être du base64url exact ; un en-tête `crit`
232
+ est refusé ; la charge doit être un objet ; un jeton de plus de 16 Kio est refusé ;
233
+ une entrée abîmée donne toujours une `JsonWebTokenError` (jsonwebtoken laissait
234
+ parfois passer une SyntaxError ou une TypeError).
210
235
 
211
236
  **Session par cookie sans `cookieParserMiddleware()` monté en amont** :
212
237
  `createAuthMiddleware` a besoin de `req.cookies` pour lire un cookie de
@@ -358,6 +383,30 @@ reproduire.
358
383
 
359
384
  Un identifiant ne doit jamais pouvoir être lu comme du contenu.
360
385
 
386
+ ## Double authentification (codes à six chiffres)
387
+
388
+ Les codes des applications d'authentification (TOTP, RFC 6238), sans otplib :
389
+ mêmes codes, mêmes vérifications et mêmes adresses `otpauth://` qu'otplib 13 sur
390
+ des vecteurs enregistrés, et les vecteurs des RFC 4226 et 6238.
391
+
392
+ ```js
393
+ const { generateTotpSecret, totpUri, verifyTotp } = require('@astratra/security');
394
+
395
+ const secret = generateTotpSecret(); // 32 caractères base32 (160 bits), à garder chiffré
396
+ const uri = totpUri({ issuer: 'Mon App', label: user.email, secret }); // à montrer en QR code
397
+
398
+ const result = verifyTotp({ secret, token: req.body.code, afterStep: user.dernierPas });
399
+ if (!result.valid) return refuser();
400
+ user.dernierPas = result.timeStep; // le même code ne sert pas deux fois
401
+ ```
402
+
403
+ - Un pas de décalage admis par défaut (`epochTolerance: 30`) ; `afterStep` refuse
404
+ un code déjà servi ; tous les pas de la fenêtre sont comparés en temps constant.
405
+ - Un code mal formé est simplement invalide (otplib levait une exception) ; un
406
+ émetteur ou un compte contenant « : » est refusé (l'adresse serait ambiguë).
407
+ - Six chiffres font un million de codes : limitez les essais de la route
408
+ (`createAccountLimiter`), sinon un robot finit par trouver.
409
+
361
410
  ## Codes uniques
362
411
 
363
412
  ```js
@@ -432,12 +481,28 @@ un corps (`content-length` non nul ou `transfer-encoding`) : avec Express 5,
432
481
  Fournir son propre `keyGenerator` contourne complètement ce point.
433
482
  ```
434
483
 
435
- ### Store Redis namespacé
484
+ ### Le limiteur, sans dépendance
436
485
 
437
- Par défaut, `redisUrl` seul suffit à activer un store Redis partagé entre
438
- tous les limiteurs. Pour isoler les compteurs par domaine (connexion,
439
- réservation, avis...) sur la même instance Redis, construis le store avec
440
- un préfixe et passe-le via `options.store` :
486
+ Depuis la 1.15.1, le limiteur est écrit dans ce paquet (`createRateLimit`), sans
487
+ express-rate-limit ni rate-limit-redis. Mêmes options, mêmes réponses (429, en-têtes
488
+ `RateLimit-*` et `Retry-After`), même clé par adresse (une adresse IPv6 compte pour
489
+ tout son bloc /56, comme avant : vérifié sur 500 adresses contre l'ancienne
490
+ bibliothèque). Un magasin en panne ne laisse jamais passer sans compter :
491
+ `next(erreur)`, sauf `passOnStoreError: true`.
492
+
493
+ ```js
494
+ const { createRateLimit, createMemoryRateLimitStore, rateLimitKeyForIp } = require('@astratra/security');
495
+
496
+ app.post('/codes', createRateLimit({ windowMs: 10 * 60 * 1000, max: 5, keyGenerator: (req) => req.body.telephone }));
497
+ ```
498
+
499
+ ### Store Redis
500
+
501
+ `redisUrl` seul suffit : chaque sorte de limiteur a alors son espace de clés
502
+ (`rl:api:`, `rl:login:`, `rl:account:`), pour que les requêtes ordinaires ne
503
+ remplissent pas le compteur de la connexion. Pour isoler les compteurs par domaine
504
+ (connexion, réservation, avis...), construis le store avec un préfixe et passe-le
505
+ via `options.store` :
441
506
 
442
507
  ```js
443
508
  const { createApiLimiter, createLoginLimiter, createRedisRateLimitStore } = require('@astratra/security');
@@ -448,19 +513,22 @@ const loginStore = createRedisRateLimitStore({
448
513
  });
449
514
  app.use('/auth', createLoginLimiter({ store: loginStore }));
450
515
 
451
- const bookingStore = createRedisRateLimitStore({
452
- redisUrl: process.env.REDIS_URL,
453
- prefix: 'mon-app:rate:reservation:'
454
- });
516
+ // Ou une connexion du projet : sendCommand (node-redis : client.sendCommand ; ioredis : (args) => client.call(...args)).
517
+ const bookingStore = createRedisRateLimitStore({ client: redisClient, prefix: 'mon-app:rate:reservation:' });
455
518
  app.use('/bookings', createApiLimiter({ store: bookingStore }));
456
519
  ```
457
520
 
458
- `prefix` est entièrement libre et défini par le projet consommateur — Astratra
459
- ne connaît aucun nom de domaine métier. Si Redis n'est pas joignable au
460
- démarrage ou perd la connexion, le store bascule automatiquement sur un
461
- store en mémoire process (mêmes garanties que le store par défaut sans
462
- `prefix`), donc aucune configuration additionnelle n'est nécessaire pour
463
- gérer l'indisponibilité de Redis.
521
+ - Le compteur et son expiration s'écrivent en une seule opération (script Lua) :
522
+ une panne entre les deux ne laisse jamais un compteur sans fin.
523
+ - Les clés sont hachées (SHA-256) : ni adresse ni e-mail en clair dans Redis.
524
+ - Tant que Redis ne répond pas (au démarrage, coupé, ou figé sans répondre), le
525
+ compte se fait en mémoire de ce serveur : la limite reste appliquée. Une
526
+ commande sans réponse au-delà de `commandTimeoutMs` (1 s) compte comme une
527
+ panne ; Redis est réessayé après `retryAfterMs` (2 s). Au retour de Redis, le
528
+ compte en mémoire et celui de Redis ne s'additionnent pas : une adresse peut
529
+ obtenir jusqu'à deux fois la limite au moment de la bascule, jamais plus.
530
+ - `prefix` est entièrement libre et défini par le projet consommateur — Astratra
531
+ ne connaît aucun nom de domaine métier.
464
532
 
465
533
  ## WAF
466
534
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@astratra/security",
3
- "version": "1.15.0",
3
+ "version": "1.15.1",
4
4
  "description": "Generic authentication and security middleware for Astratra workspaces.",
5
5
  "engines": {
6
6
  "node": ">=22"
@@ -12,7 +12,8 @@
12
12
  "src"
13
13
  ],
14
14
  "scripts": {
15
- "test": "jest"
15
+ "test": "jest",
16
+ "verify:mutations": "node scripts/verify-rate-limit-mutations.cjs && node scripts/verify-jwt-mutations.cjs && node scripts/verify-totp-mutations.cjs"
16
17
  },
17
18
  "jest": {
18
19
  "testMatch": [
@@ -30,25 +31,19 @@
30
31
  },
31
32
  "dependencies": {
32
33
  "@astratra/core": "^1.0.0",
33
- "@simplewebauthn/server": "^13.1.2",
34
- "express-rate-limit": "^8.7.4",
35
- "jsonwebtoken": "^9.0.2"
34
+ "@simplewebauthn/server": "^13.1.2"
36
35
  },
37
36
  "peerDependencies": {
38
- "rate-limit-redis": ">=4",
39
37
  "redis": ">=4"
40
38
  },
41
39
  "peerDependenciesMeta": {
42
- "rate-limit-redis": {
43
- "optional": true
44
- },
45
40
  "redis": {
46
41
  "optional": true
47
42
  }
48
43
  },
49
44
  "devDependencies": {
45
+ "@astratra/testkit": "^2.0.0",
50
46
  "jest": "30.4.2",
51
- "rate-limit-redis": "^6.0.2",
52
47
  "redis": "^6.3.1"
53
48
  }
54
49
  }
package/src/csrf.js CHANGED
@@ -73,6 +73,18 @@ const headerValue = (req, name) => {
73
73
  return headers[name.toLowerCase()] || headers[name];
74
74
  };
75
75
 
76
+ /**
77
+ * Compares the submitted header with the cookie token in constant time, so
78
+ * response timing never reveals how many leading characters were right.
79
+ * Anything but a non-empty string (a missing or repeated header) is refused.
80
+ */
81
+ const tokensMatch = (received, expected) => {
82
+ if (typeof received !== 'string' || typeof expected !== 'string' || expected.length === 0) return false;
83
+ const a = Buffer.from(received, 'utf8');
84
+ const b = Buffer.from(expected, 'utf8');
85
+ return a.length === b.length && crypto.timingSafeEqual(a, b);
86
+ };
87
+
76
88
  const setCsrfCookie = (res, token, options = {}) => {
77
89
  const parts = [
78
90
  `${options.name || DEFAULT_CSRF_COOKIE_NAME}=${token}`,
@@ -108,7 +120,7 @@ const createCsrfMiddleware = (options = {}) => {
108
120
  return next();
109
121
  }
110
122
 
111
- if (headerValue(req, headerName) !== token) {
123
+ if (!tokensMatch(headerValue(req, headerName), token)) {
112
124
  return res.status(403).json({ success: false, message: 'Invalid CSRF token.' });
113
125
  }
114
126
 
package/src/idTokens.js CHANGED
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * Vérifier un jeton d'identité OpenID Connect (Google, Apple, tout fournisseur
3
3
  * qui publie ses clés en JWKS) sans dépendance JOSE : Node transforme chaque
4
- * JWK en KeyObject, jsonwebtoken vérifie la signature, l'émetteur, l'audience
4
+ * JWK en KeyObject, verifyJwt (./jwt) vérifie la signature, l'émetteur, l'audience
5
5
  * et l'expiration.
6
6
  *
7
7
  * Ce que le module garantit, chaque point testé :
@@ -28,7 +28,7 @@
28
28
  * contient jamais le jeton.
29
29
  */
30
30
  const crypto = require('crypto');
31
- const jwt = require('jsonwebtoken');
31
+ const { decodeJwt, verifyJwt } = require('./jwt');
32
32
 
33
33
  const DEFAULT_CACHE_MS = 60 * 60 * 1000;
34
34
  const DEFAULT_MIN_REFRESH_MS = 60 * 1000;
@@ -145,7 +145,7 @@ function createIdTokenVerifier(options = {}) {
145
145
  if (typeof idToken !== 'string' || !idToken || idToken.length > MAX_TOKEN_LENGTH) {
146
146
  throw new IdTokenError('malformed');
147
147
  }
148
- const decoded = jwt.decode(idToken, { complete: true });
148
+ const decoded = decodeJwt(idToken, { complete: true });
149
149
  const header = decoded && decoded.header;
150
150
  if (!header || header.alg !== 'RS256' || typeof header.kid !== 'string' || !header.kid) {
151
151
  throw new IdTokenError('malformed');
@@ -155,7 +155,8 @@ function createIdTokenVerifier(options = {}) {
155
155
 
156
156
  let claims;
157
157
  try {
158
- claims = jwt.verify(idToken, key, {
158
+ claims = verifyJwt(idToken, key, {
159
+ maxTokenLength: MAX_TOKEN_LENGTH,
159
160
  algorithms: ['RS256'],
160
161
  issuer: issuers,
161
162
  audience: audienceList,
package/src/index.d.ts CHANGED
@@ -253,37 +253,86 @@ export function createCsrfMiddleware(options?: CsrfMiddlewareOptions): RequestHa
253
253
  export function createCsrfCookiePrimer(options?: Pick<CsrfMiddlewareOptions, 'name' | 'sameSite' | 'secure' | 'path' | 'domain' | 'skip'>): RequestHandler;
254
254
 
255
255
  export interface RateLimitStore {
256
- init?(options: unknown): unknown;
257
- increment?(...args: unknown[]): unknown;
258
- decrement?(...args: unknown[]): unknown;
259
- resetKey?(...args: unknown[]): unknown;
260
- resetAll?(...args: unknown[]): unknown;
261
- get?(...args: unknown[]): unknown;
262
- shutdown?(...args: unknown[]): unknown;
256
+ /** Reçoit la fenêtre du limiteur ({ windowMs }) à sa création. */
257
+ init?(options: { windowMs: number }): unknown;
258
+ /** Compte une requête pour la clé : le nombre dans la fenêtre et sa fin. */
259
+ increment(key: string): Awaitable<{ totalHits: number; resetTime?: Date }>;
260
+ decrement?(key: string): unknown;
261
+ resetKey?(key: string): unknown;
262
+ resetAll?(): unknown;
263
+ get?(key: string): Awaitable<{ totalHits: number; resetTime?: Date } | undefined>;
264
+ shutdown?(): unknown;
265
+ localKeys?: boolean;
266
+ prefix?: string;
263
267
  }
264
268
 
269
+ export interface RateLimitInfo { limit: number; used: number; remaining: number; resetTime: Date; key: string }
270
+
265
271
  export interface RateLimitOptions {
266
272
  windowMs?: number;
267
273
  max?: number;
268
- skip?: (req: RequestLike) => boolean | Promise<boolean>;
274
+ skip?: (req: RequestLike, res?: ResponseLike) => boolean | Promise<boolean>;
269
275
  standardHeaders?: boolean | string;
270
276
  legacyHeaders?: boolean;
277
+ /** Sans effet depuis la 1.15.1 (le limiteur n'est plus express-rate-limit) ; accepté pour ne rien casser. */
271
278
  validate?: Record<string, unknown> | boolean;
272
279
  message?: unknown;
273
280
  store?: RateLimitStore;
274
281
  redisUrl?: string;
275
282
  }
276
283
 
284
+ /** Le limiteur lui-même (sans dépendance) : fenêtre fixe par clé, magasin interchangeable, en-têtes RateLimit-*. */
285
+ export interface CreateRateLimitOptions {
286
+ windowMs?: number;
287
+ limit?: number | ((req: any, res: any) => number | Promise<number>);
288
+ max?: number | ((req: any, res: any) => number | Promise<number>);
289
+ keyGenerator?: (req: any, res: any) => string | Promise<string>;
290
+ skip?: (req: any, res: any) => boolean | Promise<boolean>;
291
+ message?: unknown | ((req: any, res: any) => unknown);
292
+ statusCode?: number;
293
+ handler?: (req: any, res: any, next: (error?: unknown) => void, options: CreateRateLimitOptions & { statusCode: number; limit: number; windowMs: number }) => unknown;
294
+ standardHeaders?: boolean;
295
+ legacyHeaders?: boolean;
296
+ store?: RateLimitStore;
297
+ /** Faux par défaut : un magasin en panne donne next(erreur), jamais un passage sans compter. */
298
+ passOnStoreError?: boolean;
299
+ requestPropertyName?: string;
300
+ skipSuccessfulRequests?: boolean;
301
+ skipFailedRequests?: boolean;
302
+ requestWasSuccessful?: (req: any, res: any) => boolean;
303
+ /** Le bloc IPv6 qui compte pour une seule adresse (56 par défaut) ; false pour l'adresse exacte. */
304
+ ipv6Subnet?: number | false;
305
+ }
306
+ export type RateLimitMiddleware = RequestHandler & {
307
+ resetKey(key: string): unknown;
308
+ getKey(key: string): unknown;
309
+ store: RateLimitStore;
310
+ };
311
+ export function createRateLimit(options?: CreateRateLimitOptions): RateLimitMiddleware;
312
+ export function createMemoryRateLimitStore(options?: { maxKeys?: number }): RateLimitStore;
313
+ /** La clé d'une adresse : IPv4 telle quelle (même écrite en IPv6), IPv6 par bloc (/56 par défaut). */
314
+ export function rateLimitKeyForIp(address: string, subnet?: number | false): string;
315
+
277
316
  export interface RedisRateLimitStoreOptions {
278
- /** URL de connexion Redis. */
317
+ /** URL de connexion Redis (le paquet `redis` doit être installé). */
279
318
  redisUrl?: string;
280
- /** Préfixe Redis librement défini par le projet consommateur. */
319
+ /** Préfixe Redis librement défini par le projet (« rl: » par défaut). */
281
320
  prefix?: string;
321
+ /** Une connexion du projet : sendCommand(['EVAL', …]) (node-redis : client.sendCommand ; ioredis : (args) => client.call(...args)). */
322
+ sendCommand?: (args: string[]) => Promise<unknown>;
323
+ /** Un client node-redis du projet. */
324
+ client?: { sendCommand(args: string[]): Promise<unknown> };
325
+ /** Clés hachées en SHA-256 (vrai par défaut) : ni adresse ni e-mail en clair dans Redis. */
326
+ hashKeys?: boolean;
327
+ /** Au-delà, une commande compte comme une panne (1 000 ms par défaut). */
328
+ commandTimeoutMs?: number;
329
+ /** Après une panne, compte en mémoire pendant ce temps avant de réessayer Redis (2 000 ms par défaut). */
330
+ retryAfterMs?: number;
282
331
  }
283
332
 
284
333
  /**
285
- * Crée un store express-rate-limit Redis avec bascule mémoire si Redis est
286
- * indisponible. Le préfixe est optionnel et entièrement défini par le projet.
334
+ * Crée un magasin Redis (compteur et expiration en une seule opération, clés hachées). Tant que Redis ne répond pas,
335
+ * le compte se fait en mémoire de ce serveur : la limite reste appliquée.
287
336
  */
288
337
  export function createRedisRateLimitStore(options?: RedisRateLimitStoreOptions): RateLimitStore | undefined;
289
338
 
@@ -994,3 +1043,63 @@ export function canonicalDeviceRequest(parts: { method: string; path: string; ti
994
1043
  /** Raw 65-byte point (base64), SPKI DER (base64) or PEM, P-256 only; returns the SPKI PEM. */
995
1044
  export function importDevicePublicKey(value: string): string;
996
1045
  export const DEVICE_SIGNATURE_HEADERS: { device: string; time: string; nonce: string; signature: string; key: string };
1046
+
1047
+ /** Les jetons JWT (JWS compact), sans jsonwebtoken. */
1048
+ export type JwtAlgorithm = 'HS256' | 'HS384' | 'HS512' | 'RS256' | 'RS384' | 'RS512' | 'PS256' | 'PS384' | 'PS512' | 'ES256' | 'ES384' | 'ES512';
1049
+ export type JwtKey = string | Buffer | import('node:crypto').KeyObject;
1050
+ export interface SignJwtOptions {
1051
+ algorithm?: JwtAlgorithm;
1052
+ /** Secondes, ou durée « 15m », « 2 days » (sans unité : millisecondes). */
1053
+ expiresIn?: number | string;
1054
+ notBefore?: number | string;
1055
+ audience?: string | string[];
1056
+ issuer?: string;
1057
+ subject?: string;
1058
+ jwtid?: string;
1059
+ keyid?: string;
1060
+ header?: Record<string, unknown>;
1061
+ noTimestamp?: boolean;
1062
+ }
1063
+ export interface VerifyJwtOptions {
1064
+ /** Obligatoire : les algorithmes acceptés. */
1065
+ algorithms: JwtAlgorithm[];
1066
+ issuer?: string | string[];
1067
+ audience?: string | RegExp | Array<string | RegExp>;
1068
+ subject?: string;
1069
+ jwtid?: string;
1070
+ clockTolerance?: number;
1071
+ clockTimestamp?: number;
1072
+ maxAge?: number | string;
1073
+ /** 16 Kio par défaut. */
1074
+ maxTokenLength?: number;
1075
+ ignoreExpiration?: boolean;
1076
+ ignoreNotBefore?: boolean;
1077
+ complete?: boolean;
1078
+ }
1079
+ export function signJwt(payload: Record<string, unknown>, key: JwtKey, options?: SignJwtOptions): string;
1080
+ export function verifyJwt<T = Record<string, unknown>>(token: string, key: JwtKey, options: VerifyJwtOptions): T;
1081
+ export function decodeJwt(token: string, options?: { complete?: boolean }): unknown;
1082
+ export class JsonWebTokenError extends Error {}
1083
+ export class TokenExpiredError extends JsonWebTokenError { expiredAt: Date }
1084
+ export class NotBeforeError extends JsonWebTokenError { date: Date }
1085
+ export const JWT_ALGORITHMS: JwtAlgorithm[];
1086
+
1087
+ /** La double authentification par code à six chiffres (TOTP, RFC 6238), sans otplib. */
1088
+ export interface TotpOptions { digits?: number; algorithm?: 'sha1' | 'sha256' | 'sha512'; period?: number }
1089
+ export function generateTotpSecret(options?: { bytes?: number }): string;
1090
+ export function hotp(secret: string | Buffer, counter: number, options?: TotpOptions): string;
1091
+ export function totp(secret: string | Buffer, options?: TotpOptions & { epoch?: number }): string;
1092
+ export function verifyTotp(options: TotpOptions & {
1093
+ secret: string | Buffer;
1094
+ token: unknown;
1095
+ /** Secondes ; maintenant par défaut. */
1096
+ epoch?: number;
1097
+ /** Secondes de décalage admises (30 par défaut : un pas avant ou après). */
1098
+ epochTolerance?: number;
1099
+ /** Le timeStep du dernier code accepté : un pas égal ou antérieur est refusé (code rejoué). */
1100
+ afterStep?: number | null;
1101
+ }): { valid: true; delta: number; timeStep: number; epoch: number } | { valid: false; reason: 'format' | 'mismatch' | 'replay'; timeStep?: number };
1102
+ export function totpUri(options: TotpOptions & { issuer: string; label: string; secret: string | Buffer }): string;
1103
+ export function base32Encode(buffer: Buffer): string;
1104
+ export function base32Decode(text: string): Buffer;
1105
+ export class TotpError extends Error {}
package/src/index.js CHANGED
@@ -2,6 +2,8 @@ module.exports = {
2
2
  ...require('./codes'),
3
3
  ...require('./cors'),
4
4
  ...require('./encryption'),
5
+ ...require('./jwt'),
6
+ ...require('./totp'),
5
7
  ...require('./jwtAuth'),
6
8
  ...require('./passwordHashing'),
7
9
  ...require('./mongoSanitize'),