@astratra/security 1.9.0 → 1.10.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
@@ -309,6 +309,55 @@ propre store (Redis, etc.) qui implémente la même interface
309
309
  (`revoke`, `isRevoked`, et optionnellement `revokeAllForUser`/
310
310
  `isRevokedForUser`).
311
311
 
312
+ ## Rester connecté (jetons de rafraîchissement)
313
+
314
+ Un jeton d'accès est court par choix : c'est cette brièveté qui limite les
315
+ dégâts d'un vol. Le prix, c'est qu'il faut quelque chose pour le renouveler —
316
+ et ce quelque chose est un identifiant à longue vie. Mal fait, on a remplacé un
317
+ risque d'une heure par un risque d'un mois.
318
+
319
+ ```js
320
+ const refreshTokens = createRefreshTokenService({
321
+ store: createMemoryRefreshTokenStore(),
322
+ ttlMs: 30 * 24 * 60 * 60 * 1000
323
+ });
324
+
325
+ const { token, familyId } = await refreshTokens.issue({ userId: user.id });
326
+ const next = await refreshTokens.rotate(token); // l'ancien est mort
327
+ await refreshTokens.revokeAllForUser(user.id); // mot de passe changé
328
+ ```
329
+
330
+ **Ce n'est pas un JWT.** Le jeton ne prouve rien par lui-même et ne porte aucune
331
+ information : c'est une chaîne aléatoire, qui n'a de sens que comme ligne dans
332
+ un magasin. C'est ce qui le rend **révocable** — un jeton signé reste valable
333
+ jusqu'à son expiration, quoi qu'on en pense entre-temps.
334
+
335
+ **Il est rangé en empreinte, jamais en clair.** Une base volée ne donne alors
336
+ aucune session. Le jeton a toute l'entropie voulue, donc un SHA-256 suffit : il
337
+ n'y a rien à casser par force brute, et un hachage lent à chaque renouvellement
338
+ ne serait qu'une surface de déni de service.
339
+
340
+ **Il tourne à chaque usage.** Le jeton présenté est consommé, un neuf prend sa
341
+ place. Un jeton vu deux fois est donc une anomalie, pas un cas normal.
342
+
343
+ **Un rejeu tue la famille.** Quand un jeton déjà consommé revient, quelqu'un en
344
+ a gardé une copie : le client légitime est passé à autre chose depuis. Refuser
345
+ ce seul jeton laisserait le voleur avec celui **en cours** — c'est donc toute la
346
+ chaîne issue de cette connexion qui est révoquée. La vraie personne se
347
+ reconnecte : c'est le prix correct d'une session volée.
348
+
349
+ ### L'alphabet, et le bug qui l'a imposé
350
+
351
+ Les jetons sont en **hexadécimal**, pas en base64url. Ce dernier contient `-`,
352
+ donc environ un jeton sur cent trente portait un `--` quelque part. Le WAF
353
+ (section plus bas) lit `--` dans un corps de requête comme un commentaire SQL et
354
+ répond 403 : cette session ne pouvait alors **plus jamais** être renouvelée,
355
+ puisque le client rejoue le même jeton et se fait bloquer à chaque fois.
356
+ L'utilisateur était déconnecté pour des raisons que personne ne savait
357
+ reproduire.
358
+
359
+ Un identifiant ne doit jamais pouvoir être lu comme du contenu.
360
+
312
361
  ## Codes uniques
313
362
 
314
363
  ```js
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@astratra/security",
3
- "version": "1.9.0",
3
+ "version": "1.10.0",
4
4
  "description": "Generic authentication and security middleware for Astratra workspaces.",
5
5
  "engines": {
6
6
  "node": ">=20"
package/src/index.d.ts CHANGED
@@ -507,3 +507,67 @@ export function createMemoryAuditStore(): AuditStore & {
507
507
 
508
508
  export function hashEvent(event: Record<string, unknown>): string;
509
509
  export const GENESIS_HASH: string;
510
+
511
+ /* ────────────────────────── Refresh tokens ────────────────────────── */
512
+
513
+ export type RefreshTokenErrorCode =
514
+ | 'REFRESH_TOKEN_INVALID'
515
+ | 'REFRESH_TOKEN_EXPIRED'
516
+ | 'REFRESH_TOKEN_REUSED';
517
+
518
+ export class RefreshTokenError extends Error {
519
+ name: 'RefreshTokenError';
520
+ code: RefreshTokenErrorCode;
521
+ constructor(message: string, code: RefreshTokenErrorCode);
522
+ }
523
+
524
+ export interface RefreshTokenRecord {
525
+ id: string;
526
+ familyId: string;
527
+ userId: string;
528
+ /** SHA-256 of the token. The token itself is never stored. */
529
+ hash: string;
530
+ createdAt: number;
531
+ expiresAt: number;
532
+ consumedAt: number | null;
533
+ revokedAt: number | null;
534
+ }
535
+
536
+ export interface RefreshTokenStore {
537
+ save(record: RefreshTokenRecord): Promise<unknown>;
538
+ findByHash(hash: string): Promise<RefreshTokenRecord | null>;
539
+ markConsumed(id: string, at: number): Promise<unknown>;
540
+ revokeFamily(familyId: string, at: number): Promise<unknown>;
541
+ revokeAllForUser(userId: string, at: number): Promise<unknown>;
542
+ deleteExpired?(before: number): Promise<number>;
543
+ }
544
+
545
+ export function createMemoryRefreshTokenStore(): RefreshTokenStore & {
546
+ all(): Promise<RefreshTokenRecord[]>;
547
+ };
548
+
549
+ export interface IssuedRefreshToken {
550
+ /** Hand this to the client. It is never stored, and never seen again. */
551
+ token: string;
552
+ id: string;
553
+ familyId: string;
554
+ userId: string;
555
+ expiresAt: number;
556
+ }
557
+
558
+ export interface RefreshTokenService {
559
+ issue(input: { userId: string }): Promise<IssuedRefreshToken>;
560
+ /** Spends the token and returns the next one. Replay revokes the family. */
561
+ rotate(token: string | null | undefined): Promise<IssuedRefreshToken>;
562
+ revokeFamily(familyId: string): Promise<void>;
563
+ revokeAllForUser(userId: string): Promise<void>;
564
+ prune(): Promise<number>;
565
+ fingerprint(token: string): string;
566
+ }
567
+
568
+ export function createRefreshTokenService(options: {
569
+ store: RefreshTokenStore;
570
+ ttlMs?: number;
571
+ now?: () => number;
572
+ randomToken?: () => string;
573
+ }): RefreshTokenService;
package/src/index.js CHANGED
@@ -14,6 +14,7 @@ module.exports = {
14
14
  ...require('./cookies'),
15
15
  ...require('./csrf'),
16
16
  ...require('./revocation'),
17
+ ...require('./refreshTokens'),
17
18
  ...require('./stableStringify'),
18
19
  ...require('./serviceSignature'),
19
20
  ...require('./auditChain')
@@ -121,10 +121,6 @@ const createRedisStore = (redisUrl, prefix) => {
121
121
  client.on('error', () => {});
122
122
  }
123
123
 
124
- const redisStore = new RedisStore({
125
- ...(prefix ? { prefix } : {}),
126
- sendCommand: (...args) => client.sendCommand(args)
127
- });
128
124
  const memoryStore = createMemoryStore();
129
125
  const connectPromise = Promise.resolve(client.connect()).catch(() => {
130
126
  if (client && client.isOpen && typeof client.disconnect === 'function') {
@@ -133,6 +129,29 @@ const createRedisStore = (redisUrl, prefix) => {
133
129
  throw new Error('Redis rate limit store unavailable');
134
130
  });
135
131
 
132
+ /* Une promesse qui se resout toujours : elle dit si la connexion a abouti,
133
+ elle n'echoue jamais. Sans elle, chaque commande en attente deviendrait
134
+ un second consommateur de connectPromise, et donc un second rejet. */
135
+ const connected = connectPromise.then(() => true, () => false);
136
+
137
+ /* rate-limit-redis charge son script d'increment DEPUIS son constructeur,
138
+ avant que la connexion soit ouverte, et n'attend pas la promesse qu'il
139
+ obtient. Envoyer directement rejetait donc contre un client ferme, et ce
140
+ rejet n'appartenait a personne : Node tuait le processus au demarrage,
141
+ meme avec un Redis parfaitement disponible.
142
+
143
+ Attendre ici transforme cette premiere commande en commande mise en file.
144
+ Et quand la connexion a echoue, le failover a deja bascule sur le store
145
+ memoire : ce store-ci ne sera jamais interroge, sa commande de demarrage
146
+ n'a plus rien a envoyer et se resout sans rien casser. */
147
+ const redisStore = new RedisStore({
148
+ ...(prefix ? { prefix } : {}),
149
+ sendCommand: async (...args) => {
150
+ if (!(await connected)) return undefined;
151
+ return client.sendCommand(args);
152
+ }
153
+ });
154
+
136
155
  return createFailoverStore(redisStore, memoryStore, connectPromise);
137
156
  } catch (_error) {
138
157
  return createMemoryStore() || undefined;
@@ -0,0 +1,214 @@
1
+ /**
2
+ * Staying signed in, without leaving a skeleton key lying around.
3
+ *
4
+ * An access token is deliberately short-lived — that brevity is what limits
5
+ * the damage of a theft. The price is that something has to renew it, and that
6
+ * something is a long-lived credential. Get it wrong and you have replaced a
7
+ * one-hour risk with a one-month one.
8
+ *
9
+ * Four decisions carry this module.
10
+ *
11
+ * IT IS NOT A JWT. A refresh token proves nothing by itself and carries no
12
+ * claims: it is an opaque random string, meaningful only as a row in a store.
13
+ * That is what makes it REVOCABLE — a signed token is valid until it expires,
14
+ * whatever you would prefer.
15
+ *
16
+ * IT IS STORED AS A FINGERPRINT, NEVER IN THE CLEAR. A stolen database then
17
+ * yields no sessions at all. The token has full entropy, so a plain SHA-256 is
18
+ * the right hash here: there is nothing to brute-force, and a slow hash on
19
+ * every refresh would only be a denial-of-service surface.
20
+ *
21
+ * IT ROTATES ON EVERY USE. The token presented is SPENT, and a new one takes
22
+ * its place. A token seen twice is therefore an anomaly, not a normal case —
23
+ * which is the whole point of the next rule.
24
+ *
25
+ * A REPLAY KILLS THE FAMILY. When a spent token comes back, someone kept a
26
+ * copy: the legitimate client has already moved on. Refusing just that one
27
+ * token would leave the thief holding the CURRENT one, so the entire chain
28
+ * descending from that sign-in is revoked. The real person signs in again —
29
+ * an inconvenience that is the correct price for a stolen session.
30
+ */
31
+
32
+ const crypto = require('crypto');
33
+
34
+ const DEFAULT_TTL_MS = 30 * 24 * 60 * 60 * 1000;
35
+
36
+ class RefreshTokenError extends Error {
37
+ /**
38
+ * @param {string} message
39
+ * @param {'REFRESH_TOKEN_INVALID'|'REFRESH_TOKEN_EXPIRED'|'REFRESH_TOKEN_REUSED'} code
40
+ */
41
+ constructor(message, code) {
42
+ super(message);
43
+ this.name = 'RefreshTokenError';
44
+ this.code = code;
45
+ }
46
+ }
47
+
48
+ function fingerprint(token) {
49
+ return crypto.createHash('sha256').update(String(token)).digest('hex');
50
+ }
51
+
52
+ /**
53
+ * The store contract, in memory. Dev and tests only: sessions vanish on
54
+ * restart, which means everyone is signed out by a deploy.
55
+ */
56
+ function createMemoryRefreshTokenStore() {
57
+ const records = new Map();
58
+
59
+ return {
60
+ async save(record) {
61
+ records.set(record.id, { ...record });
62
+ return { ...record };
63
+ },
64
+ async findByHash(hash) {
65
+ for (const record of records.values()) {
66
+ if (record.hash === hash) return { ...record };
67
+ }
68
+ return null;
69
+ },
70
+ async markConsumed(id, at) {
71
+ const record = records.get(id);
72
+ if (record) record.consumedAt = at;
73
+ },
74
+ async revokeFamily(familyId, at) {
75
+ for (const record of records.values()) {
76
+ if (record.familyId === familyId) record.revokedAt = record.revokedAt || at;
77
+ }
78
+ },
79
+ async revokeAllForUser(userId, at) {
80
+ for (const record of records.values()) {
81
+ if (record.userId === userId) record.revokedAt = record.revokedAt || at;
82
+ }
83
+ },
84
+ async deleteExpired(before) {
85
+ let removed = 0;
86
+ for (const [id, record] of records) {
87
+ if (record.expiresAt <= before) {
88
+ records.delete(id);
89
+ removed += 1;
90
+ }
91
+ }
92
+ return removed;
93
+ },
94
+ /** Test and inspection helper — not part of the contract adapters must meet. */
95
+ async all() {
96
+ return [...records.values()].map((record) => ({ ...record }));
97
+ }
98
+ };
99
+ }
100
+
101
+ /**
102
+ * @param {object} options
103
+ * @param {object} options.store save/findByHash/markConsumed/revokeFamily/
104
+ * revokeAllForUser/deleteExpired. The memory one above, or your database.
105
+ * @param {number} [options.ttlMs] Lifetime of each token. Default 30 days.
106
+ * @param {Function} [options.now] Clock, for tests.
107
+ * @param {Function} [options.randomToken] Token factory, for tests.
108
+ */
109
+ function createRefreshTokenService(options = {}) {
110
+ const store = options.store;
111
+ if (!store || typeof store.findByHash !== 'function' || typeof store.save !== 'function') {
112
+ throw new Error('createRefreshTokenService requires options.store.');
113
+ }
114
+
115
+ const ttlMs = options.ttlMs || DEFAULT_TTL_MS;
116
+ const now = options.now || Date.now;
117
+ /*
118
+ * HEX, not base64url — and this cost a real bug to learn.
119
+ *
120
+ * base64url contains '-', so roughly one token in 130 carried a '--'
121
+ * somewhere. The WAF reads '--' in a request body as an SQL comment and
122
+ * answers 403, so that session could NEVER be renewed: the client retries
123
+ * the same token, gets blocked again, and the person is signed out for
124
+ * reasons nobody can reproduce.
125
+ *
126
+ * A credential must never be readable as content. Hex has no character any
127
+ * filter takes an interest in, and 32 random bytes carry the same entropy
128
+ * whichever alphabet prints them.
129
+ */
130
+ const randomToken = options.randomToken || (() => crypto.randomBytes(32).toString('hex'));
131
+
132
+ async function mint({ userId, familyId }) {
133
+ const token = randomToken();
134
+ const issuedAt = now();
135
+ const record = {
136
+ id: crypto.randomUUID(),
137
+ familyId: familyId || crypto.randomUUID(),
138
+ userId: String(userId),
139
+ hash: fingerprint(token),
140
+ createdAt: issuedAt,
141
+ /* Counted from NOW on every rotation: an active session should not die
142
+ because it was first opened a month ago. */
143
+ expiresAt: issuedAt + ttlMs,
144
+ consumedAt: null,
145
+ revokedAt: null
146
+ };
147
+ await store.save(record);
148
+ return { token, id: record.id, familyId: record.familyId, userId: record.userId, expiresAt: record.expiresAt };
149
+ }
150
+
151
+ /** A fresh sign-in: a new family of its own. */
152
+ async function issue({ userId } = {}) {
153
+ if (!userId) throw new Error('issue requires userId.');
154
+ return mint({ userId });
155
+ }
156
+
157
+ /**
158
+ * Exchange a token for the next one.
159
+ * @throws {RefreshTokenError} invalid, expired, or replayed.
160
+ */
161
+ async function rotate(token) {
162
+ if (typeof token !== 'string' || !token) {
163
+ throw new RefreshTokenError('Unknown refresh token.', 'REFRESH_TOKEN_INVALID');
164
+ }
165
+
166
+ const record = await store.findByHash(fingerprint(token));
167
+ if (!record) throw new RefreshTokenError('Unknown refresh token.', 'REFRESH_TOKEN_INVALID');
168
+
169
+ if (record.revokedAt) {
170
+ throw new RefreshTokenError('This session has been revoked.', 'REFRESH_TOKEN_INVALID');
171
+ }
172
+
173
+ /* Checked BEFORE expiry: a replayed token that also happens to have
174
+ expired is still a theft, and must still kill the family. */
175
+ if (record.consumedAt) {
176
+ await store.revokeFamily(record.familyId, now());
177
+ throw new RefreshTokenError(
178
+ 'Refresh token replayed — every session from this sign-in has been revoked.',
179
+ 'REFRESH_TOKEN_REUSED'
180
+ );
181
+ }
182
+
183
+ if (record.expiresAt <= now()) {
184
+ throw new RefreshTokenError('This session has expired.', 'REFRESH_TOKEN_EXPIRED');
185
+ }
186
+
187
+ await store.markConsumed(record.id, now());
188
+ return mint({ userId: record.userId, familyId: record.familyId });
189
+ }
190
+
191
+ /** Sign out one device: that chain, and nothing else. */
192
+ async function revokeFamily(familyId) {
193
+ await store.revokeFamily(familyId, now());
194
+ }
195
+
196
+ /** Password changed, account recovered: everything this person holds dies. */
197
+ async function revokeAllForUser(userId) {
198
+ await store.revokeAllForUser(String(userId), now());
199
+ }
200
+
201
+ /** Housekeeping — call it on a timer. Returns how many rows were dropped. */
202
+ async function prune() {
203
+ if (typeof store.deleteExpired !== 'function') return 0;
204
+ return store.deleteExpired(now());
205
+ }
206
+
207
+ return { issue, rotate, revokeFamily, revokeAllForUser, prune, fingerprint };
208
+ }
209
+
210
+ module.exports = {
211
+ RefreshTokenError,
212
+ createMemoryRefreshTokenStore,
213
+ createRefreshTokenService
214
+ };