@astratra/security 1.6.0 → 1.8.0
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 +67 -0
- package/package.json +1 -1
- package/src/codes.js +45 -0
- package/src/index.d.ts +39 -0
- package/src/index.js +1 -0
- package/src/rateLimiters.js +7 -1
package/README.md
CHANGED
|
@@ -228,6 +228,43 @@ propre store (Redis, etc.) qui implémente la même interface
|
|
|
228
228
|
(`revoke`, `isRevoked`, et optionnellement `revokeAllForUser`/
|
|
229
229
|
`isRevokedForUser`).
|
|
230
230
|
|
|
231
|
+
## Codes uniques
|
|
232
|
+
|
|
233
|
+
```js
|
|
234
|
+
const { createRandomCode, generateUniqueCodes } = require('@astratra/security');
|
|
235
|
+
|
|
236
|
+
createRandomCode(); // "A1B2C3D4E5"
|
|
237
|
+
createRandomCode({ prefix: 'ete2026' }); // "ETE2026-A1B2C3D4E5"
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
Génère un token à usage unique via `crypto.randomBytes` (jamais `Math.random`) —
|
|
241
|
+
utile pour un code promo, une invitation, une carte cadeau... Le préfixe est
|
|
242
|
+
assaini (lettres/chiffres uniquement, tronqué à 12 caractères) avant d'être
|
|
243
|
+
collé au token, pour ne jamais casser le format si le préfixe vient d'une
|
|
244
|
+
saisie admin.
|
|
245
|
+
|
|
246
|
+
Pour générer plusieurs codes garantis uniques :
|
|
247
|
+
|
|
248
|
+
```js
|
|
249
|
+
const codes = await generateUniqueCodes({
|
|
250
|
+
quantity: 20,
|
|
251
|
+
prefix: 'PROMO',
|
|
252
|
+
// Optionnel : vérifie l'unicité contre TON store avant de renvoyer quoi
|
|
253
|
+
// que ce soit — jamais après une tentative d'insertion, donc aucun risque
|
|
254
|
+
// de double insertion partielle si un nouvel essai est nécessaire.
|
|
255
|
+
isTaken: async (candidates) => {
|
|
256
|
+
const existing = await MyCodeModel.find({ code: { $in: candidates } }).select('code');
|
|
257
|
+
return new Set(existing.map((doc) => doc.code));
|
|
258
|
+
}
|
|
259
|
+
});
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
Une collision entre deux codes générés par `crypto.randomBytes(5)` (défaut,
|
|
263
|
+
~1 billion de combinaisons) est déjà astronomiquement improbable ; `isTaken`
|
|
264
|
+
ne fait que fermer ce cas rarissime proprement (régénère seulement les codes
|
|
265
|
+
rejetés, jusqu'à `maxAttempts`, défaut 5) plutôt que de laisser une erreur de
|
|
266
|
+
contrainte unique remonter au milieu d'une insertion.
|
|
267
|
+
|
|
231
268
|
## Rate limiting
|
|
232
269
|
|
|
233
270
|
```js
|
|
@@ -249,6 +286,36 @@ seule fois par processus) signale ce cas. Fournir son propre `keyGenerator`
|
|
|
249
286
|
contourne complètement ce point.
|
|
250
287
|
```
|
|
251
288
|
|
|
289
|
+
### Store Redis namespacé
|
|
290
|
+
|
|
291
|
+
Par défaut, `redisUrl` seul suffit à activer un store Redis partagé entre
|
|
292
|
+
tous les limiteurs. Pour isoler les compteurs par domaine (connexion,
|
|
293
|
+
réservation, avis...) sur la même instance Redis, construis le store avec
|
|
294
|
+
un préfixe et passe-le via `options.store` :
|
|
295
|
+
|
|
296
|
+
```js
|
|
297
|
+
const { createApiLimiter, createLoginLimiter, createRedisRateLimitStore } = require('@astratra/security');
|
|
298
|
+
|
|
299
|
+
const loginStore = createRedisRateLimitStore({
|
|
300
|
+
redisUrl: process.env.REDIS_URL,
|
|
301
|
+
prefix: 'mon-app:rate:connexion:'
|
|
302
|
+
});
|
|
303
|
+
app.use('/auth', createLoginLimiter({ store: loginStore }));
|
|
304
|
+
|
|
305
|
+
const bookingStore = createRedisRateLimitStore({
|
|
306
|
+
redisUrl: process.env.REDIS_URL,
|
|
307
|
+
prefix: 'mon-app:rate:reservation:'
|
|
308
|
+
});
|
|
309
|
+
app.use('/bookings', createApiLimiter({ store: bookingStore }));
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
`prefix` est entièrement libre et défini par le projet consommateur — Astratra
|
|
313
|
+
ne connaît aucun nom de domaine métier. Si Redis n'est pas joignable au
|
|
314
|
+
démarrage ou perd la connexion, le store bascule automatiquement sur un
|
|
315
|
+
store en mémoire process (mêmes garanties que le store par défaut sans
|
|
316
|
+
`prefix`), donc aucune configuration additionnelle n'est nécessaire pour
|
|
317
|
+
gérer l'indisponibilité de Redis.
|
|
318
|
+
|
|
252
319
|
## WAF
|
|
253
320
|
|
|
254
321
|
```js
|
package/package.json
CHANGED
package/src/codes.js
ADDED
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
const crypto = require('crypto');
|
|
2
|
+
|
|
3
|
+
const DEFAULT_TOKEN_BYTES = 5;
|
|
4
|
+
|
|
5
|
+
// Aucune notion métier ici (promo, invitation, carte cadeau...) : le préfixe
|
|
6
|
+
// et l'usage du code sont entièrement définis par le projet consommateur.
|
|
7
|
+
const createRandomCode = ({ prefix, tokenBytes = DEFAULT_TOKEN_BYTES } = {}) => {
|
|
8
|
+
const safePrefix = String(prefix || '').trim().toUpperCase().replace(/[^A-Z0-9]/g, '').slice(0, 12);
|
|
9
|
+
const token = crypto.randomBytes(tokenBytes).toString('hex').toUpperCase();
|
|
10
|
+
return safePrefix ? `${safePrefix}-${token}` : token;
|
|
11
|
+
};
|
|
12
|
+
|
|
13
|
+
/**
|
|
14
|
+
* Génère `quantity` codes garantis uniques entre eux ET, si `isTaken` est
|
|
15
|
+
* fourni, absents de ton propre store — vérifiés AVANT tout retour, jamais
|
|
16
|
+
* après une tentative d'insertion. Une collision avec `crypto.randomBytes`
|
|
17
|
+
* est déjà astronomiquement improbable ; ce garde-fou ne fait qu'éviter de
|
|
18
|
+
* planter sur ce cas rarissime plutôt que de le rendre plus probable.
|
|
19
|
+
*
|
|
20
|
+
* `isTaken(candidates)` reçoit un tableau de codes candidats et doit
|
|
21
|
+
* renvoyer une Promise<Set<string>> (ou tout ce qui expose `.has()`) des
|
|
22
|
+
* codes parmi eux déjà pris — à toi de l'implémenter contre ton propre
|
|
23
|
+
* store (Mongo, Postgres, mémoire...).
|
|
24
|
+
*/
|
|
25
|
+
const generateUniqueCodes = async ({ quantity, prefix, tokenBytes, isTaken, maxAttempts = 5 } = {}) => {
|
|
26
|
+
const unique = new Set();
|
|
27
|
+
for (let attempt = 1; attempt <= maxAttempts && unique.size < quantity; attempt++) {
|
|
28
|
+
const missing = quantity - unique.size;
|
|
29
|
+
const candidates = new Set();
|
|
30
|
+
while (candidates.size < missing) {
|
|
31
|
+
const code = createRandomCode({ prefix, tokenBytes });
|
|
32
|
+
if (!unique.has(code)) candidates.add(code);
|
|
33
|
+
}
|
|
34
|
+
const taken = isTaken ? await isTaken([...candidates]) : null;
|
|
35
|
+
for (const code of candidates) {
|
|
36
|
+
if (!taken || !taken.has(code)) unique.add(code);
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
if (unique.size < quantity) {
|
|
40
|
+
throw new Error('Unable to generate enough unique codes after multiple attempts');
|
|
41
|
+
}
|
|
42
|
+
return [...unique];
|
|
43
|
+
};
|
|
44
|
+
|
|
45
|
+
module.exports = { createRandomCode, generateUniqueCodes };
|
package/src/index.d.ts
CHANGED
|
@@ -22,6 +22,32 @@ export type NextFunction = (error?: unknown) => unknown;
|
|
|
22
22
|
export type RequestHandler = (req: RequestLike, res: ResponseLike, next: NextFunction) => unknown;
|
|
23
23
|
export type Awaitable<T> = T | Promise<T>;
|
|
24
24
|
|
|
25
|
+
export interface CreateRandomCodeOptions {
|
|
26
|
+
/** Préfixe librement défini par le projet consommateur (lettres/chiffres uniquement, tronqué à 12). */
|
|
27
|
+
prefix?: string;
|
|
28
|
+
/** Nombre d'octets aléatoires du token (hex, donc 2x plus de caractères). Défaut 5. */
|
|
29
|
+
tokenBytes?: number;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/** Génère un code à usage unique (`PREFIX-A1B2C3D4E5`), via crypto.randomBytes. */
|
|
33
|
+
export function createRandomCode(options?: CreateRandomCodeOptions): string;
|
|
34
|
+
|
|
35
|
+
export interface GenerateUniqueCodesOptions extends CreateRandomCodeOptions {
|
|
36
|
+
/** Nombre de codes à générer. */
|
|
37
|
+
quantity: number;
|
|
38
|
+
/**
|
|
39
|
+
* Reçoit les codes candidats et renvoie les codes déjà pris parmi eux
|
|
40
|
+
* (Set<string> ou équivalent avec .has()). Optionnel : sans lui, seule
|
|
41
|
+
* l'unicité au sein du lot généré est garantie.
|
|
42
|
+
*/
|
|
43
|
+
isTaken?: (candidates: string[]) => Awaitable<{ has(code: string): boolean }>;
|
|
44
|
+
/** Nombre de tentatives avant d'abandonner. Défaut 5. */
|
|
45
|
+
maxAttempts?: number;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/** Génère `quantity` codes uniques, vérifiés avant tout retour (jamais après une tentative d'insertion). */
|
|
49
|
+
export function generateUniqueCodes(options: GenerateUniqueCodesOptions): Promise<string[]>;
|
|
50
|
+
|
|
25
51
|
export interface CorsMiddlewareOptions {
|
|
26
52
|
/** Explicit list of allowed origins (exact match on the Origin header). */
|
|
27
53
|
allowedOrigins?: string[];
|
|
@@ -247,6 +273,19 @@ export interface RateLimitOptions {
|
|
|
247
273
|
redisUrl?: string;
|
|
248
274
|
}
|
|
249
275
|
|
|
276
|
+
export interface RedisRateLimitStoreOptions {
|
|
277
|
+
/** URL de connexion Redis. */
|
|
278
|
+
redisUrl?: string;
|
|
279
|
+
/** Préfixe Redis librement défini par le projet consommateur. */
|
|
280
|
+
prefix?: string;
|
|
281
|
+
}
|
|
282
|
+
|
|
283
|
+
/**
|
|
284
|
+
* Crée un store express-rate-limit Redis avec bascule mémoire si Redis est
|
|
285
|
+
* indisponible. Le préfixe est optionnel et entièrement défini par le projet.
|
|
286
|
+
*/
|
|
287
|
+
export function createRedisRateLimitStore(options?: RedisRateLimitStoreOptions): RateLimitStore | undefined;
|
|
288
|
+
|
|
250
289
|
export interface LoginBlockedContext {
|
|
251
290
|
ip: string;
|
|
252
291
|
req: RequestLike;
|
package/src/index.js
CHANGED
package/src/rateLimiters.js
CHANGED
|
@@ -98,7 +98,7 @@ const createFailoverStore = (redisStore, memoryStore, connectPromise) => {
|
|
|
98
98
|
};
|
|
99
99
|
};
|
|
100
100
|
|
|
101
|
-
const createRedisStore = (redisUrl) => {
|
|
101
|
+
const createRedisStore = (redisUrl, prefix) => {
|
|
102
102
|
if (!redisUrl) return undefined;
|
|
103
103
|
|
|
104
104
|
let RedisModule;
|
|
@@ -122,6 +122,7 @@ const createRedisStore = (redisUrl) => {
|
|
|
122
122
|
}
|
|
123
123
|
|
|
124
124
|
const redisStore = new RedisStore({
|
|
125
|
+
...(prefix ? { prefix } : {}),
|
|
125
126
|
sendCommand: (...args) => client.sendCommand(args)
|
|
126
127
|
});
|
|
127
128
|
const memoryStore = createMemoryStore();
|
|
@@ -138,6 +139,10 @@ const createRedisStore = (redisUrl) => {
|
|
|
138
139
|
}
|
|
139
140
|
};
|
|
140
141
|
|
|
142
|
+
// Store Redis générique : le namespace est choisi par le projet consommateur.
|
|
143
|
+
// Astratra ne connaît donc aucun domaine métier (auth, commandes, réservations…).
|
|
144
|
+
const createRedisRateLimitStore = ({ redisUrl, prefix } = {}) => createRedisStore(redisUrl, prefix);
|
|
145
|
+
|
|
141
146
|
const resolveStore = (options) => {
|
|
142
147
|
if (options.store) return options.store;
|
|
143
148
|
return createRedisStore(options.redisUrl);
|
|
@@ -235,6 +240,7 @@ const createAccountLimiter = (options = {}) => {
|
|
|
235
240
|
};
|
|
236
241
|
|
|
237
242
|
module.exports = {
|
|
243
|
+
createRedisRateLimitStore,
|
|
238
244
|
createApiLimiter,
|
|
239
245
|
createLoginLimiter,
|
|
240
246
|
createAccountLimiter,
|