@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 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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@astratra/security",
3
- "version": "1.6.0",
3
+ "version": "1.8.0",
4
4
  "description": "Generic authentication and security middleware for Astratra workspaces.",
5
5
  "engines": {
6
6
  "node": ">=20"
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
@@ -1,4 +1,5 @@
1
1
  module.exports = {
2
+ ...require('./codes'),
2
3
  ...require('./cors'),
3
4
  ...require('./encryption'),
4
5
  ...require('./jwtAuth'),
@@ -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,