@astratra/security 1.7.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 +37 -0
- package/package.json +1 -1
- package/src/codes.js +45 -0
- package/src/index.d.ts +26 -0
- package/src/index.js +1 -0
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
|
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[];
|