@nodefony/redis 10.0.0-alpha.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.
Files changed (36) hide show
  1. package/LICENSE +544 -0
  2. package/README.md +110 -0
  3. package/dist/_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorate.js +9 -0
  4. package/dist/_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorateMetadata.js +6 -0
  5. package/dist/index.js +58 -0
  6. package/dist/nodefony/config/config.js +98 -0
  7. package/dist/nodefony/config/defineModuleConfig.js +90 -0
  8. package/dist/nodefony/interfaces/IRedisConfig.js +1 -0
  9. package/dist/nodefony/interfaces/index.js +1 -0
  10. package/dist/nodefony/registerStores.js +38 -0
  11. package/dist/nodefony/service/redis.js +177 -0
  12. package/dist/nodefony/src/Connection.js +111 -0
  13. package/dist/nodefony/src/RedisTokenStore.js +390 -0
  14. package/dist/nodefony/src/RedisWebAuthnCredentialStore.js +247 -0
  15. package/dist/nodefony/src/SessionStorage.js +249 -0
  16. package/dist/nodefony/src/buildClientOptions.js +63 -0
  17. package/dist/nodefony/src/keyNamespace.js +80 -0
  18. package/dist/nodefony/src/scanCursor.js +69 -0
  19. package/dist/types/index.d.ts +53 -0
  20. package/dist/types/nodefony/config/config.d.ts +41 -0
  21. package/dist/types/nodefony/config/defineModuleConfig.d.ts +26 -0
  22. package/dist/types/nodefony/interfaces/IRedisConfig.d.ts +17 -0
  23. package/dist/types/nodefony/interfaces/index.d.ts +5 -0
  24. package/dist/types/nodefony/registerStores.d.ts +5 -0
  25. package/dist/types/nodefony/service/redis.d.ts +82 -0
  26. package/dist/types/nodefony/src/Connection.d.ts +39 -0
  27. package/dist/types/nodefony/src/RedisTokenStore.d.ts +121 -0
  28. package/dist/types/nodefony/src/RedisWebAuthnCredentialStore.d.ts +108 -0
  29. package/dist/types/nodefony/src/SessionStorage.d.ts +87 -0
  30. package/dist/types/nodefony/src/buildClientOptions.d.ts +21 -0
  31. package/dist/types/nodefony/src/keyNamespace.d.ts +12 -0
  32. package/dist/types/nodefony/src/scanCursor.d.ts +50 -0
  33. package/docs/architecture.md +718 -0
  34. package/docs/configuration.md +773 -0
  35. package/docs/index.md +295 -0
  36. package/package.json +95 -0
@@ -0,0 +1,82 @@
1
+ import { Module, Service, type Severity, type Msgid, type Message, type Pci } from "nodefony";
2
+ import type { RedisClientType } from "redis";
3
+ import Connection from "../src/Connection.js";
4
+ /**
5
+ * Service Redis Nodefony — orchestre N connexions nommées (par défaut `main`,
6
+ * `publish`, `subscribe`) à partir de la config validée par Zod.
7
+ *
8
+ * La config est validée + gelée au boot du Module class (`onKernelRegister`,
9
+ * exposée au container sous `redisConfig`). Le service la consomme sans
10
+ * redupliquer la validation.
11
+ *
12
+ * Perf/mémoire : la map de connexions est en **lazy alloc** (`null` jusqu'à la
13
+ * 1ʳᵉ connexion ouverte) et toutes les connexions sont fermées au `onTerminate`
14
+ * du kernel (listeners retirés explicitement côté `Connection`).
15
+ */
16
+ declare class RedisService extends Service {
17
+ #private;
18
+ module: Module;
19
+ constructor(module: Module);
20
+ log(pci: Pci, severity?: Severity, msgid?: Msgid, msg?: Message): import("nodefony").Pdu;
21
+ /** Connexions ouvertes (vide si aucune). */
22
+ get connections(): Record<string, Connection>;
23
+ /**
24
+ * Cloison des clés de CETTE application, résolue une fois.
25
+ *
26
+ * `keyNamespace` explicite, sinon le nom de l'application. Les stores composent
27
+ * leur préfixe avec (`resolveKeyPrefix`) pour que deux applications sur un même
28
+ * Redis n'écrivent — et surtout ne BALAIENT — jamais le même espace de clés.
29
+ *
30
+ * `undefined` = aucune cloison résolue (application anonyme) → les stores
31
+ * gardent leur préfixe historique : une application seule n'a rien à séparer.
32
+ */
33
+ get keyNamespace(): string | undefined;
34
+ /**
35
+ * Préfixe de clés d'un store, cloisonné par application.
36
+ *
37
+ * @param base - préfixe historique du store (`nf:sess`, `nf:tok`, `nf:wac`).
38
+ * @returns le préfixe à utiliser pour composer les clés ET les motifs de balayage.
39
+ */
40
+ keyPrefix(base: string): string;
41
+ /**
42
+ * Ouvre toutes les connexions déclarées dans la config (si `enabled`).
43
+ * Appelé par le cycle de vie du Module. Une connexion en échec est loguée
44
+ * sans bloquer les autres (résilience boot).
45
+ */
46
+ init(): Promise<this>;
47
+ /**
48
+ * Crée et ouvre une connexion nommée.
49
+ *
50
+ * @param name - clé de la connexion dans `config.connections`.
51
+ * @returns la connexion ouverte.
52
+ * @throws si le nom est déjà ouvert ou inconnu, ou si la connexion échoue.
53
+ */
54
+ createConnection(name: string): Promise<Connection>;
55
+ /** Connexion par nom (ou `undefined`). */
56
+ getConnection(name: string): Connection | undefined;
57
+ /**
58
+ * Client redis brut d'une connexion **utilisable**, ou `null`.
59
+ *
60
+ * `null` ne veut pas dire « connexion inconnue » mais « ne prends pas la
61
+ * peine » : tous les consommateurs (stores de session, de jetons, de
62
+ * passkeys, backplane realtime, idempotence) traitent `null` comme une
63
+ * indisponibilité et dégradent. Rendre un client fermé leur ferait prendre un
64
+ * `ClientClosedError` là où leur contrat promet un repli.
65
+ *
66
+ * Pourquoi tester l'ouverture et pas seulement la présence : `createClient()`
67
+ * rend un objet AVANT `connect()` (`Connection.create()`), et une connexion
68
+ * dont l'ouverture a échoué reste inscrite dans la map — le client existe donc
69
+ * **sans jamais avoir été ouvert**. `isOpen` (et non `isReady`) est le bon
70
+ * critère : pendant une reconnexion le socket est ouvert et node-redis met les
71
+ * commandes en file, ce qui est exactement la résilience recherchée.
72
+ *
73
+ * L'indisponibilité est **journalisée à la transition** — une dégradation
74
+ * muette contredit le principe de résilience du framework (tout repli
75
+ * s'annonce), mais journaliser à chaque appel noierait le journal.
76
+ */
77
+ getClient(name: string): RedisClientType | null;
78
+ /** Ferme toutes les connexions ouvertes (idempotent). */
79
+ closeConnections(): Promise<void>;
80
+ generateId(): string;
81
+ }
82
+ export default RedisService;
@@ -0,0 +1,39 @@
1
+ import { Service, type Severity, type Msgid, type Message } from "nodefony";
2
+ import { type RedisClientType, type RedisClientOptions } from "redis";
3
+ import type RedisService from "../service/redis.js";
4
+ /**
5
+ * Une connexion Redis nommée — enveloppe un client `redis` v6 et gère son cycle
6
+ * de vie (création, écoute des événements, fermeture propre).
7
+ *
8
+ * Perf/mémoire : les handlers d'événements sont conservés en propriété et
9
+ * **explicitement retirés** à la fermeture (`removeListener`) pour éviter toute
10
+ * fuite si la connexion est recréée — règle absolue perf-mémoire du framework.
11
+ */
12
+ export default class Connection extends Service {
13
+ #private;
14
+ /** Client redis v6 — `null` tant que `create()` n'a pas réussi. */
15
+ client: RedisClientType | null;
16
+ /** Service Redis parent (accès container / kernel / événements). */
17
+ service: RedisService;
18
+ /** true entre les événements `connect` et `end`. */
19
+ connected: boolean;
20
+ /** Options `createClient` assemblées (par `buildClientOptions`). */
21
+ options: RedisClientOptions;
22
+ constructor(name: string, options: RedisClientOptions, redisService: RedisService);
23
+ log(pci: unknown, severity?: Severity, msgid?: Msgid, msg?: Message): import("nodefony").Pdu;
24
+ /**
25
+ * Crée le client, attache les listeners, ouvre la connexion.
26
+ *
27
+ * @returns le client connecté.
28
+ * @throws si la connexion échoue (propagé au service, qui logue).
29
+ */
30
+ create(): Promise<RedisClientType>;
31
+ /**
32
+ * Ferme proprement la connexion et nettoie les listeners.
33
+ *
34
+ * redis v6 : `client.close()` remplace `quit()` (déprécié, envoyait `QUIT` —
35
+ * lui-même déprécié côté Redis 7.2). Fermeture gracieuse : draine les commandes
36
+ * en vol puis ferme le socket. (`destroy()` = fermeture forcée, non souhaitée ici.)
37
+ */
38
+ close(): Promise<void>;
39
+ }
@@ -0,0 +1,121 @@
1
+ import type { IPage } from "nodefony";
2
+ import type { IAccessTokenRecord, ITokenListQuery, ITokenStore, ITokenUsage, TokenRevokeReason } from "@nodefony/security";
3
+ import type RedisService from "../service/redis.js";
4
+ /**
5
+ * Sous-ensemble structural du client `redis` v6 utilisé par le store — permet de
6
+ * tester contre un double déterministe sans serveur (le vrai `RedisClientType`
7
+ * satisfait cette forme par ses méthodes camelCase v6).
8
+ */
9
+ export interface RedisClientLike {
10
+ hSet(key: string, fields: Record<string, string>): Promise<number>;
11
+ hGetAll(key: string): Promise<Record<string, string>>;
12
+ hDel(key: string, field: string): Promise<number>;
13
+ get(key: string): Promise<string | null>;
14
+ set(key: string, value: string, options?: {
15
+ EX?: number;
16
+ }): Promise<unknown>;
17
+ del(key: string): Promise<number>;
18
+ exists(key: string): Promise<number>;
19
+ expire(key: string, seconds: number): Promise<unknown>;
20
+ sAdd(key: string, member: string): Promise<number>;
21
+ sRem(key: string, member: string): Promise<number>;
22
+ sMembers(key: string): Promise<string[]>;
23
+ scan(cursor: string, options?: {
24
+ MATCH?: string;
25
+ COUNT?: number;
26
+ }): Promise<{
27
+ cursor: string;
28
+ keys: string[];
29
+ }>;
30
+ }
31
+ /**
32
+ * Store de jetons **Redis** (node-redis v6) — implémentation d'{@link ITokenStore}
33
+ * pour le cluster (source unique cross-pod, denylist hot).
34
+ *
35
+ * **Approche B** : `@nodefony/security` n'est connu qu'en `import type` (0 dép
36
+ * runtime). L'application câble la fabrique (`registerTokenStore("redis", …)`).
37
+ *
38
+ * **Modèle de clés** (préfixe `nf:tok`) :
39
+ * - `rec:<jti>` = **HASH** du record (1 champ par colonne ; tableaux/objets en
40
+ * JSON dans le champ ; `null` = champ absent). HASH (≠ blob JSON) car `markUsed`
41
+ * écrit 1-3 champs via `HSET` **sans réécrire le record ni toucher le TTL** ;
42
+ * - `hash:<secretHash>` = `jti` (index de lookup au login) ;
43
+ * - `subj:<subjectId>` / `fam:<family>` = **SET** d'ids (index secondaires —
44
+ * les membres orphelins sont nettoyés paresseusement à la lecture) ;
45
+ * - `deny:<jti>` = `"1"` avec **`EX`** (révocation ciblée, TTL natif) ;
46
+ * - `revsub:<subjectId>` = seuil `invalidBefore` (révocation en masse).
47
+ *
48
+ * **TTL natif → `gc()` est un no-op** : un refresh expire par son `exp`
49
+ * (`EXPIRE`), un PAT **révoqué sans exp** reçoit un `EXPIRE = rétention` au moment
50
+ * du `revoke`, la denylist expire par `EX`. Redis purge seul (zéro balayage).
51
+ *
52
+ * Dégradation gracieuse : si la connexion `main` n'est pas (ou plus) ouverte, les
53
+ * lectures renvoient vide et les écritures sont des no-op (comme le session store).
54
+ */
55
+ export declare class RedisTokenStore implements ITokenStore {
56
+ #private;
57
+ /**
58
+ * @param resolveClient - résolveur **lazy** du client Redis (l'ordre de boot
59
+ * n'est pas garanti à la construction ; `null` = connexion indisponible).
60
+ * @param now - horloge (epoch ms) injectable pour les tests.
61
+ * @param retentionRevokedMs - rétention d'un PAT révoqué sans `exp` avant purge.
62
+ */
63
+ constructor(resolveClient: () => RedisClientLike | null, now?: () => number, retentionRevokedMs?: number, resolvePrefix?: () => string, notify?: (message: string) => void);
64
+ /**
65
+ * Construit le store depuis un {@link RedisService} (connexion `main`).
66
+ * Résolution **lazy** du client (boot order).
67
+ *
68
+ * @param service - service Redis fournissant `getClient("main")`.
69
+ * @param now - horloge injectable (tests).
70
+ * @param retentionRevokedMs - rétention des PAT révoqués sans `exp`.
71
+ */
72
+ static from(service: RedisService, now?: () => number, retentionRevokedMs?: number): RedisTokenStore;
73
+ put(record: IAccessTokenRecord): Promise<void>;
74
+ findById(id: string): Promise<IAccessTokenRecord | null>;
75
+ findByHash(secretHash: string): Promise<IAccessTokenRecord | null>;
76
+ findBySubject(subjectId: string): Promise<IAccessTokenRecord[]>;
77
+ /**
78
+ * Tous les jetons (PAT + refresh) — vue d'administration cross-porteur.
79
+ * Énumère les records par **SCAN** (curseur non-bloquant, `MATCH nf:tok:rec:*`).
80
+ * Opération admin RARE (cold-path, jamais sur le hot-path d'auth) ; à très
81
+ * grande échelle, préférer le système de référence SQL pour la gouvernance.
82
+ *
83
+ * Le balayage est **plafonné** à {@link MAX_SCAN} clés, comme celui des
84
+ * sessions : sans plafond, une vue d'administration lancée sur un très grand
85
+ * parc balaie tout le keyspace. Au-delà on s'arrête et on **journalise** — un
86
+ * listing partiel se dit, il ne se tronque pas en silence.
87
+ */
88
+ listAll(): Promise<IAccessTokenRecord[]>;
89
+ /**
90
+ * {@inheritDoc ITokenStore.listPage}
91
+ *
92
+ * **Curseur SCAN pur** : UN passage `SCAN` par appel (cold-path admin). Capacité
93
+ * réduite ASSUMÉE et annoncée — pas de `total`, pas d'ordre global sur `createdAt`
94
+ * (Redis n'a pas d'index secondaire ici), la page peut compter moins d'éléments
95
+ * que `limit` (le filtre s'applique au batch). Le client boucle tant que
96
+ * `hasNext` en repassant `nextCursor`. Renvoie les records BRUTS.
97
+ */
98
+ listPage(query: ITokenListQuery): Promise<IPage<IAccessTokenRecord>>;
99
+ /**
100
+ * {@inheritDoc ITokenStore.countTokens}
101
+ *
102
+ * Un comptage exact exigerait un `SCAN` complet O(N) → refusé sur le cold-path
103
+ * admin : renvoie `-1` (« inconnu », capacité réduite Redis assumée).
104
+ */
105
+ countTokens(_query: ITokenListQuery): Promise<number>;
106
+ markUsed(id: string, usage: ITokenUsage): Promise<void>;
107
+ revoke(id: string, reason: TokenRevokeReason): Promise<void>;
108
+ revokeFamily(family: string, reason: TokenRevokeReason): Promise<void>;
109
+ denyJti(jti: string, expiresAt: number): Promise<void>;
110
+ isJtiDenied(jti: string): Promise<boolean>;
111
+ revokeAllForSubject(subjectId: string, invalidBefore: number): Promise<void>;
112
+ getInvalidBefore(subjectId: string): Promise<number | null>;
113
+ /**
114
+ * **No-op** : Redis gère toute l'expiration par TTL natif (refresh par leur
115
+ * `exp`, PAT révoqués par la rétention posée au `revoke`, denylist par `EX`).
116
+ * Aucun balayage applicatif n'est nécessaire (≠ Drizzle/Mongoose).
117
+ *
118
+ * @returns toujours `0` (rien à purger côté application).
119
+ */
120
+ gc(): Promise<number>;
121
+ }
@@ -0,0 +1,108 @@
1
+ import type { IPage } from "nodefony";
2
+ import type { IWebAuthnCredential, IWebAuthnCredentialStore, IWebAuthnCredentialSummary, IWebAuthnListQuery, WebAuthnAuthUpdate } from "@nodefony/security";
3
+ import type RedisService from "../service/redis.js";
4
+ /**
5
+ * Sous-ensemble structural du client `redis` v6 utilisé par le store de
6
+ * credentials — permet de tester contre un double déterministe sans serveur (le
7
+ * vrai `RedisClientType` satisfait cette forme par ses méthodes camelCase v6).
8
+ *
9
+ * Plus restreint que celui du `RedisTokenStore` : un credential WebAuthn ne porte
10
+ * **aucun TTL** (une passkey est permanente jusqu'à révocation explicite) → ni
11
+ * `expire`/`EX`, ni `get`/`set` de chaîne. Deux structures suffisent : un HASH
12
+ * par credential, un SET d'ids par utilisateur.
13
+ */
14
+ export interface RedisClientLike {
15
+ hSet(key: string, fields: Record<string, string>): Promise<number>;
16
+ hGetAll(key: string): Promise<Record<string, string>>;
17
+ exists(key: string): Promise<number>;
18
+ del(key: string): Promise<number>;
19
+ sAdd(key: string, member: string): Promise<number>;
20
+ sRem(key: string, member: string): Promise<number>;
21
+ sMembers(key: string): Promise<string[]>;
22
+ sCard(key: string): Promise<number>;
23
+ scan(cursor: string, options?: {
24
+ MATCH?: string;
25
+ COUNT?: number;
26
+ }): Promise<{
27
+ cursor: string;
28
+ keys: string[];
29
+ }>;
30
+ }
31
+ /**
32
+ * Store de credentials WebAuthn **Redis** (node-redis v6) — implémentation
33
+ * d'{@link IWebAuthnCredentialStore} pour le cluster (source unique cross-pod,
34
+ * les passkeys survivent au redémarrage et sont partagées entre process).
35
+ *
36
+ * **Approche B** : `@nodefony/security` n'est connu qu'en `import type` (0 dép
37
+ * runtime). L'application câble la fabrique (`registerWebAuthnStore("redis", …)`).
38
+ *
39
+ * **Modèle de clés** (préfixe `nf:wac`) :
40
+ * - `cred:<credentialId>` = **HASH** du credential (1 champ par colonne ;
41
+ * `transports` en JSON ; booléens en `"1"`/`"0"` ; `lastUsedAt`/`nickname`
42
+ * absents = `null`/non défini). HASH (≠ blob JSON) car `update` réécrit 1-4
43
+ * champs via `HSET` sans relire le record ;
44
+ * - `user:<userId>` = **SET** des credentialIds de l'utilisateur (`findByUser`,
45
+ * `allowCredentials`, « mes appareils ») — les membres orphelins (credential
46
+ * supprimé hors `delete`) sont nettoyés paresseusement à la lecture.
47
+ *
48
+ * **Aucun TTL → aucun `gc`** : le contrat {@link IWebAuthnCredentialStore} n'a pas
49
+ * de maintenance (≠ `ITokenStore`) — un credential ne disparaît que sur `delete`.
50
+ *
51
+ * Dégradation gracieuse : si la connexion `main` n'est pas (ou plus) ouverte, les
52
+ * lectures renvoient vide et les écritures sont des no-op (comme le session store).
53
+ */
54
+ export declare class RedisWebAuthnCredentialStore implements IWebAuthnCredentialStore {
55
+ #private;
56
+ /**
57
+ * @param resolveClient - résolveur **lazy** du client Redis (l'ordre de boot
58
+ * n'est pas garanti à la construction ; `null` = connexion indisponible).
59
+ * @param resolvePrefix - résolveur **lazy** du préfixe cloisonné par application.
60
+ */
61
+ constructor(resolveClient: () => RedisClientLike | null, resolvePrefix?: () => string);
62
+ /**
63
+ * Construit le store depuis un {@link RedisService} (connexion `main`).
64
+ * Résolution **lazy** du client (boot order).
65
+ *
66
+ * @param service - service Redis fournissant `getClient("main")`.
67
+ */
68
+ static from(service: RedisService): RedisWebAuthnCredentialStore;
69
+ findById(credentialId: string): Promise<IWebAuthnCredential | null>;
70
+ findByUser(userId: string): Promise<IWebAuthnCredential[]>;
71
+ /**
72
+ * `SCARD` natif — O(1), aucune lecture de HASH (le plafond ne charge rien).
73
+ *
74
+ * Peut **sur-compter** les membres orphelins que {@link findByUser} nettoie
75
+ * paresseusement (credential supprimé hors `delete` — sans TTL sur les
76
+ * credentials, cas dégénéré). Écart assumé **fail-closed** : au pire un
77
+ * enrôlement de plus est refusé, jamais un de trop accepté. Client
78
+ * indisponible → `0` (cohérent avec les lectures qui renvoient vide).
79
+ */
80
+ countByUser(userId: string): Promise<number>;
81
+ save(credential: IWebAuthnCredential): Promise<void>;
82
+ update(credentialId: string, patch: WebAuthnAuthUpdate): Promise<void>;
83
+ delete(credentialId: string): Promise<void>;
84
+ /**
85
+ * {@inheritDoc IWebAuthnCredentialStore.listPage}
86
+ *
87
+ * **Curseur SCAN pur** : UN passage `SCAN` par appel (cold-path admin). Capacité
88
+ * réduite ASSUMÉE et annoncée — pas de `total`, pas d'ordre global sur
89
+ * `createdAt` (Redis n'a pas d'index secondaire ici), la page peut compter moins
90
+ * d'éléments que `limit` (le filtre s'applique au batch). Le client boucle tant
91
+ * que `hasNext` en repassant `nextCursor`.
92
+ *
93
+ * ⚠️ On SCANne les HASH de credentials, pas les Set par utilisateur : le filtre
94
+ * `userId` reste un filtre de page. Passer par `sMembers` serait plus direct
95
+ * mais donnerait deux stratégies de pagination pour un même contrat — la
96
+ * seconde sans curseur, donc incohérente dès qu'on mélange les filtres.
97
+ */
98
+ listPage(query: IWebAuthnListQuery): Promise<IPage<IWebAuthnCredentialSummary>>;
99
+ /**
100
+ * {@inheritDoc IWebAuthnCredentialStore.countCredentials}
101
+ *
102
+ * Un comptage exact exigerait un `SCAN` complet O(N) → refusé sur le cold-path
103
+ * admin : renvoie `-1` (« inconnu », capacité réduite Redis assumée).
104
+ * ⚠️ Ne pas confondre avec {@link countByUser}, qui est O(1) (`SCARD`) parce
105
+ * qu'il porte sur un index existant.
106
+ */
107
+ countCredentials(_query: IWebAuthnListQuery): Promise<number>;
108
+ }
@@ -0,0 +1,87 @@
1
+ import { SessionsService } from "@nodefony/http";
2
+ import type { ISessionStorage, ISerializedSession, ISessionRecord, ISessionListFilter, ISessionListQuery } from "@nodefony/http";
3
+ import type { IPage } from "nodefony";
4
+ /**
5
+ * Stockage de session **Redis** — branché sur la connexion `main` du
6
+ * {@link RedisService}. Implémente le contrat unifié {@link ISessionStorage}
7
+ * consommé par le `SessionsService` de `@nodefony/http`.
8
+ *
9
+ * Atout décisif vs File/SQL : l'expiration est portée par le **TTL natif**
10
+ * (`SET … EX`) → `gc()` est un **no-op** (zéro balayage, zéro requête de purge)
11
+ * et le store est **partagé cross-pod** (source unique de vérité en cluster).
12
+ *
13
+ * Dégradation gracieuse **annoncée** : si la connexion `main` n'est pas (ou
14
+ * plus) ouverte (boot, coupure, shutdown), chaque opération devient un no-op
15
+ * plutôt que de jeter — la session n'est simplement pas persistée le temps de
16
+ * l'indisponibilité. Le repli n'est pas muet : {@link RedisService.getClient}
17
+ * journalise un WARNING à la bascule et un INFO au rétablissement (une seule
18
+ * ligne par transition, pas une par requête).
19
+ */
20
+ declare class RedisSessionStorage implements ISessionStorage {
21
+ #private;
22
+ manager: SessionsService;
23
+ /** Idle timeout en secondes (= TTL Redis natif, glissant via `write`/`touch`). */
24
+ idleTimeoutS: number;
25
+ constructor(manager: SessionsService);
26
+ read(id: string): Promise<ISerializedSession>;
27
+ start(id: string): Promise<ISerializedSession>;
28
+ write(id: string, data: ISerializedSession): Promise<ISerializedSession>;
29
+ open(): Promise<number>;
30
+ close(): boolean;
31
+ destroy(id: string): Promise<boolean>;
32
+ gc(): Promise<void>;
33
+ /**
34
+ * Prolonge l'idle d'une session (timeout glissant) en repositionnant le TTL
35
+ * natif (`EXPIRE`, O(1)) — SANS réécrire la valeur (touch NIST/OWASP). C'est le
36
+ * touch le moins coûteux des stores. Clé absente / connexion fermée → no-op.
37
+ *
38
+ * @param idleSeconds - nouvel idle (défaut : l'idle configuré du store).
39
+ */
40
+ touch(id: string, idleSeconds?: number): Promise<void>;
41
+ /**
42
+ * Énumération admin (capacité optionnelle d'`ISessionStorage`) par **SCAN**
43
+ * non-bloquant (`MATCH <prefix>:*`, curseur), filtrable par `user`. Cold-path
44
+ * RARE (console admin, jamais le hot-path). `SCAN` est O(keyspace) → plafonné
45
+ * à {@link MAX_SCAN} (au-delà : listing partiel **journalisé**, pas silencieux).
46
+ * Connexion fermée → `[]`.
47
+ */
48
+ listAll(filter?: ISessionListFilter): Promise<ISessionRecord[]>;
49
+ /**
50
+ * {@inheritDoc ISessionStorage.listPage}
51
+ *
52
+ * **Curseur SCAN** : au plus UN passage `SCAN` par appel (cold-path admin).
53
+ * Capacité réduite ASSUMÉE et annoncée — pas de `total`, pas d'ordre global sur
54
+ * `updatedAt` (Redis n'a pas d'index secondaire ici), et la page peut compter
55
+ * moins d'éléments que `limit` (le filtre s'applique au batch scanné). Le client
56
+ * boucle tant que `hasNext`, en repassant `nextCursor`. La garantie qui compte
57
+ * est tenue : **le keyspace n'est jamais matérialisé** — au plus un batch.
58
+ *
59
+ * ⚠️ **`COUNT` n'est PAS un plafond** — c'est un indice d'effort par itération.
60
+ * Redis peut rendre plus de clés que demandé (typiquement un petit keyspace
61
+ * encodé en listpack : tout arrive en une fois). Sans précaution, la page
62
+ * dépasserait `limit` et violerait le contrat `IPage`. D'où le **curseur
63
+ * composite** `"<consommé>:<curseurRedis>"` : quand un batch contient plus que
64
+ * la page, on ne rend que `limit` éléments et on mémorise combien de clés du
65
+ * batch ont été consommées — la page suivante rejoue le MÊME `SCAN` et reprend
66
+ * là où on s'était arrêté. Coût : un re-scan du batch courant, payé uniquement
67
+ * sur un cold-path d'administration. Rien n'est perdu, rien ne déborde.
68
+ */
69
+ listPage(query: ISessionListQuery): Promise<IPage<ISessionRecord>>;
70
+ /**
71
+ * {@inheritDoc ISessionStorage.countSessions}
72
+ *
73
+ * Un comptage exact exigerait un `SCAN` complet O(keyspace) → refusé même sur le
74
+ * cold-path admin : renvoie **`-1`** (« inconnu », capacité réduite Redis
75
+ * assumée). L'appelant affiche l'inconnu, il ne l'invente pas.
76
+ */
77
+ countSessions(_query?: Partial<ISessionListQuery>): Promise<number>;
78
+ /**
79
+ * {@inheritDoc ISessionStorage.countDistinctUsers}
80
+ *
81
+ * Dédupliquer exige d'avoir tout vu : c'est le `SCAN` complet que
82
+ * {@link countSessions} refuse déjà, plus un ensemble à retenir en mémoire.
83
+ * Renvoie **`-1`** — la console affiche « — », elle n'invente pas un chiffre.
84
+ */
85
+ countDistinctUsers(_query?: Partial<ISessionListQuery>): Promise<number>;
86
+ }
87
+ export default RedisSessionStorage;
@@ -0,0 +1,21 @@
1
+ import type { RedisClientOptions } from "redis";
2
+ import type { IRedisConfig, IRedisConnectionConfig } from "../interfaces/IRedisConfig.js";
3
+ /**
4
+ * Assemble les options `createClient` (redis v6) d'une connexion nommée à partir
5
+ * de la config validée : `globalOptions` fusionné avec la surcharge de connexion.
6
+ *
7
+ * Précédence : `url` (si présent) > socket de connexion > `globalOptions.socket`.
8
+ * Quand `url` est fourni, host/port/auth en sont extraits par redis lui-même —
9
+ * on ne pose alors PAS de `socket.host/port` (ils seraient ignorés/conflictuels).
10
+ *
11
+ * redis v6 : RESP3 est le protocole par défaut (on l'assume — set/get/pub/sub
12
+ * inchangés côté API) mais `maintNotifications` y bascule à `"auto"` (souscrit aux
13
+ * push frames de maintenance Redis Enterprise + relâche les timeouts socket). On
14
+ * cible Redis OSS → on force `"disabled"` pour un comportement déterministe et
15
+ * zéro listener/frame superflu (règle perf-mémoire).
16
+ *
17
+ * @param config - config racine validée et gelée.
18
+ * @param connection - définition de la connexion (name/database/socket override).
19
+ * @returns options prêtes pour `createClient`.
20
+ */
21
+ export declare function buildClientOptions(config: IRedisConfig, connection: IRedisConnectionConfig): RedisClientOptions;
@@ -0,0 +1,12 @@
1
+ /**
2
+ * Compose le préfixe de clés d'un store, cloisonné par application.
3
+ *
4
+ * @param base - préfixe historique du store (`nf:sess`, `nf:tok`, `nf:wac`).
5
+ * @param namespace - cloison de l'application ; vide ou absente → pas de cloison.
6
+ * @returns `nf:<namespace>:<type>` si une cloison est posée, `base` sinon.
7
+ * @throws nodefonyError si la cloison contient autre chose que des caractères de
8
+ * mot, `.` ou `-`. Le `:` est le séparateur de clé : l'accepter permettrait de
9
+ * fabriquer un préfixe recouvrant celui d'une autre application, et un `*` de
10
+ * transformer un balayage en filet dérivant.
11
+ */
12
+ export declare function resolveKeyPrefix(base: string, namespace?: string): string;
@@ -0,0 +1,50 @@
1
+ /**
2
+ * Curseur de pagination `SCAN` — **règle unique** des trois stores Redis
3
+ * (sessions, jetons, identifiants WebAuthn).
4
+ *
5
+ * Pourquoi un fichier partagé : ces trois stores portaient chacun leur copie de
6
+ * `encodeCursor`/`decodeCursor`. La copie du store de session a été durcie (un
7
+ * curseur venu de l'extérieur y est validé) ; les deux autres ne l'ont jamais
8
+ * été — un `?cursor=` arbitraire y partait tel quel vers Redis et faisait
9
+ * **échouer une simple consultation**. Deux implémentations d'une même règle
10
+ * dérivent toujours : il n'y en a plus qu'une.
11
+ */
12
+ /**
13
+ * Plafond de sécurité d'un balayage administratif complet : au-delà, on s'arrête
14
+ * et on **journalise** (listing partiel signalé, jamais tronqué en silence).
15
+ *
16
+ * `SCAN` est O(keyspace) — un index secondaire (`SET` d'ids) serait
17
+ * l'optimisation v2 pour un très grand parc.
18
+ */
19
+ export declare const MAX_SCAN = 10000;
20
+ /**
21
+ * Curseur de page **composite** : `"<skip>:<curseurRedis>"`.
22
+ *
23
+ * Pourquoi composer plutôt que passer le curseur Redis nu : `SCAN COUNT` est un
24
+ * indice d'effort, pas un plafond — Redis peut rendre plus de clés que demandé
25
+ * (petit keyspace encodé en listpack → tout arrive d'un coup). Sans précaution
26
+ * la page dépasserait `limit` et violerait `IPage`. Le `skip` mémorise combien
27
+ * de clés du batch courant ont déjà été rendues, pour que la page suivante
28
+ * rejoue le même `SCAN` et reprenne à la bonne position. Rien n'est perdu, rien
29
+ * ne déborde.
30
+ */
31
+ export declare function encodeCursor(scanCursor: string, skip: number): string;
32
+ /**
33
+ * Inverse d'{@link encodeCursor} — tolère un curseur absent, vide ou malformé.
34
+ *
35
+ * Le jeton vient de l'extérieur (query string du data plane admin, client qui
36
+ * rejoue une page) : il n'est donc PAS digne de confiance. Un curseur `SCAN`
37
+ * Redis est toujours une suite de chiffres — tout le reste repart de `"0"`
38
+ * plutôt que d'être transmis au serveur, qui répondrait par une erreur et ferait
39
+ * échouer une simple consultation. Repartir du début est faux au pire d'une
40
+ * page ; jeter serait faux à coup sûr.
41
+ *
42
+ * Le split se fait au PREMIER `:` : le curseur Redis est opaque et reste intact
43
+ * même s'il contenait lui-même un `:`.
44
+ */
45
+ export declare function decodeCursor(cursor?: string): {
46
+ scanCursor: string;
47
+ skip: number;
48
+ };
49
+ /** Un curseur `SCAN` exploitable (chiffres) ou `"0"` — jamais du texte libre. */
50
+ export declare function scanOrZero(value: string): string;