@astratra/credentials 0.2.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Astratra
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,309 @@
1
+ # @astratra/credentials
2
+
3
+ Les clés de service — paiement, e-mail, IA — rangées **chiffrées dans ta base**
4
+ plutôt que dans un `.env` sur le serveur. Elles se saisissent depuis l'interface,
5
+ prennent effet en moins d'une minute, sans redémarrage et sans session SSH.
6
+
7
+ Le `.env` garde son rôle de secours : rien ne casse tant qu'aucune clé n'a été
8
+ saisie.
9
+
10
+ Ce package ne connaît ni ta base, ni ton chiffrement, ni tes fournisseurs. Tout
11
+ est injecté : le store, le cipher, le catalogue de clés, la règle qui protège
12
+ les valeurs sensibles, et la fonction qui envoie le code de déverrouillage.
13
+
14
+ ## Le problème
15
+
16
+ Changer une clé Stripe ou une clé d'API obligeait à ouvrir une session SSH,
17
+ éditer un fichier, relancer le service. Trois occasions de se tromper, et un
18
+ secret en clair sur le disque du serveur.
19
+
20
+ ## L'ordre, qui ne change jamais
21
+
22
+ 1. une valeur **saisie dans l'interface** → déchiffrée et utilisée ;
23
+ 2. une clé **explicitement débranchée** → rien, même si le `.env` en a une ;
24
+ 3. **rien en base** → le `.env`, comme avant.
25
+
26
+ Le point 2 est le piège. Sans marqueur de débranchement, supprimer une clé la
27
+ ferait réapparaître par la variable d'environnement de secours — et on ne
28
+ saurait jamais si un service est vraiment débranché.
29
+
30
+ ## Mise en place
31
+
32
+ ```js
33
+ const { createFieldCipher } = require('@astratra/security');
34
+ const {
35
+ createCredentialCatalog,
36
+ createCredentialVault,
37
+ createEnvHydrator,
38
+ createMongoCredentialStore
39
+ } = require('@astratra/credentials');
40
+
41
+ // 1. Ce que l'interface a le droit de piloter. Jamais un champ libre :
42
+ // sans catalogue, n'importe quel nom de variable pourrait être écrit en
43
+ // base puis lu au démarrage.
44
+ const catalog = createCredentialCatalog({
45
+ spaces: [
46
+ {
47
+ id: 'ai',
48
+ label: 'Intelligence artificielle',
49
+ hint: 'Interrogés dans cet ordre.',
50
+ keys: [
51
+ {
52
+ key: 'GROQ_API_KEY',
53
+ label: 'Groq',
54
+ help: "Le premier fournisseur interrogé. Sans lui, on bascule sur le suivant.",
55
+ where: 'console.groq.com → API Keys'
56
+ }
57
+ ]
58
+ }
59
+ ],
60
+ // La serrure ne se range pas dans le coffre qu'elle ferme.
61
+ reservedKeys: ['ENCRYPTION_KEY', 'JWT_SECRET', 'MONGODB_URI']
62
+ });
63
+
64
+ // 2. Où c'est rangé, et comment c'est chiffré.
65
+ const store = createMongoCredentialStore({
66
+ collection: mongoose.connection.collection('credentials'),
67
+ isReady: () => mongoose.connection.readyState === 1
68
+ });
69
+ const cipher = createFieldCipher({ key: process.env.ENCRYPTION_KEY });
70
+
71
+ const vault = createCredentialVault({ store, catalog, cipher });
72
+
73
+ // 3. Le reste du code lit toujours process.env — il n'a rien à changer.
74
+ const hydrator = createEnvHydrator({ vault });
75
+ await hydrator.hydrate(catalog.keys());
76
+ hydrator.startRefresh(catalog.keys(), { intervalMs: 60_000 });
77
+ ```
78
+
79
+ `vault.get('GROQ_API_KEY')` répond directement, et `process.env.GROQ_API_KEY`
80
+ dit la vérité pour tout le code qui ne sait pas lire de façon asynchrone.
81
+
82
+ ## Le coffre
83
+
84
+ | Méthode | Ce qu'elle fait |
85
+ |---|---|
86
+ | `get(key)` | la base d'abord, le `.env` ensuite, `null` si débranchée |
87
+ | `getMany(keys)` | plusieurs clés en une seule lecture |
88
+ | `stored()` | ce que dit la BASE, sans repli — absente ≠ débranchée |
89
+ | `set(key, value, { updatedBy })` | chiffre et enregistre |
90
+ | `disconnect(key)` | débranche : le `.env` ne reprend PAS la main |
91
+ | `status()` | l'état de chaque clé, sûr à envoyer au navigateur |
92
+ | `forget()` | vide le cache (une minute par défaut) |
93
+
94
+ `status()` ne renvoie **jamais** une valeur secrète : seulement les quatre
95
+ derniers caractères. Une capture d'écran de la page des réglages ne doit rien
96
+ compromettre. Une valeur déclarée `secret: false` — un identifiant OAuth public,
97
+ une adresse d'expédition — est renvoyée en clair : elle existe pour être
98
+ vérifiée d'un coup d'œil.
99
+
100
+ Rien ne lève à la lecture. Pas de base, pas de cipher, une valeur abîmée : on
101
+ retombe sur le `.env`. **Un paiement ne doit pas échouer parce que la base a
102
+ hoqueté.** Une clé illisible n'emporte pas les autres.
103
+
104
+ ## Le garde-valeur
105
+
106
+ Poste de développement et production partagent souvent le même store — c'est
107
+ tout l'intérêt de centraliser les clés. C'est sans danger tant que les valeurs
108
+ sont des valeurs de test ; c'est un désastre le jour où un portable récupère une
109
+ clé de paiement réelle et encaisse pour de vrai.
110
+
111
+ Le jugement porte donc sur la **valeur**, pas seulement sur l'environnement :
112
+
113
+ ```js
114
+ const { createValueGuard } = require('@astratra/credentials');
115
+
116
+ const guard = createValueGuard({
117
+ keys: ['STRIPE_SECRET_KEY', 'STRIPE_WEBHOOK_SECRET'],
118
+ // La clé dont le préfixe décide du sort de tout le groupe : une signature de
119
+ // webhook ne dit rien d'elle-même, mais appartient au MÊME compte que la clé
120
+ // secrète et doit suivre son sort.
121
+ decidingKey: 'STRIPE_SECRET_KEY',
122
+ livePattern: /^(sk|pk|rk)_live_/,
123
+ testPattern: /^(sk|pk|rk)_test_/
124
+ });
125
+
126
+ createCredentialVault({ store, catalog, cipher, guard });
127
+ createEnvHydrator({ vault, guard });
128
+ ```
129
+
130
+ Une valeur qu'on ne sait pas classer n'est jamais traitée comme réelle : un
131
+ garde-fou qui bloque à tort finit par être contourné.
132
+
133
+ Sans `guard`, rien n'est restreint — c'est ce que renvoie `createPermissiveGuard()`,
134
+ utilisable explicitement quand on veut le dire plutôt que l'omettre. Astratra n'a
135
+ pas d'avis sur les clés qui déplacent de l'argent chez toi.
136
+
137
+ ## Le code de déverrouillage
138
+
139
+ Savoir le mot de passe du compte ne suffit pas. Remplacer une clé de paiement
140
+ par la sienne ne casse rien d'apparent — l'argent part simplement ailleurs.
141
+ C'est le genre de vol qu'on ne remarque qu'au relevé.
142
+
143
+ Ce module ne connaît pas l'e-mail : il fabrique, range et vérifie le code, et
144
+ `deliverCode` est à toi. **Envoie-le à l'adresse déjà enregistrée sur le compte,
145
+ jamais à une adresse fournie dans la requête** — ce serait offrir au voleur le
146
+ moyen de se l'envoyer à lui-même.
147
+
148
+ ```js
149
+ const { createUnlockChallenge, createMongoChallengeStore, maskEmail } =
150
+ require('@astratra/credentials');
151
+
152
+ const challenge = createUnlockChallenge({
153
+ store: createMongoChallengeStore({ collection: db.collection('credentialChallenges') }),
154
+ deliverCode: async ({ subjectId, code }) => {
155
+ const account = await Users.findById(subjectId);
156
+ await sendEmail(account.email, 'Code de modification', `Votre code : ${code}`);
157
+ return { sentTo: maskEmail(account.email) };
158
+ }
159
+ });
160
+ ```
161
+
162
+ Six chiffres tirés par `crypto.randomInt`, comparés à durée constante, jamais
163
+ conservés en clair : une fuite de cette collection ne déverrouille rien. Cinq
164
+ tentatives, dix minutes de validité, puis dix minutes de fenêtre de saisie —
165
+ sinon poser les dix clés d'un fournisseur demanderait dix e-mails, et le
166
+ garde-fou finirait contourné plutôt qu'utilisé. Demander un nouveau code
167
+ **referme** la fenêtre en cours.
168
+
169
+ ## Les routes
170
+
171
+ ```js
172
+ const { createCredentialsRoutes } = require('@astratra/credentials');
173
+ const { authorizeRoles } = require('@astratra/security');
174
+
175
+ app.use('/api/credentials', createCredentialsRoutes({
176
+ vault,
177
+ challenge,
178
+ authorize: authorizeRoles('owner')
179
+ }));
180
+ ```
181
+
182
+ | Route | Effet |
183
+ |---|---|
184
+ | `GET /` | l'état des clés + la fenêtre ouverte, le cas échéant |
185
+ | `POST /challenge` | envoie le code à l'adresse du compte |
186
+ | `POST /unlock` | vérifie le code, ouvre la fenêtre |
187
+ | `PUT /:key` | enregistre une valeur |
188
+ | `DELETE /:key` | débranche une clé |
189
+
190
+ `authorize` est **obligatoire** : ces clés engagent les paiements de toute la
191
+ plateforme, pas ceux d'un locataire, et Astratra n'a pas d'avis sur qui possède
192
+ l'argent. Sans `challenge`, les écritures passent directement — c'est ta
193
+ décision, pas un défaut.
194
+
195
+ ## Les stores
196
+
197
+ Deux contrats, minuscules :
198
+
199
+ ```
200
+ store de clés : findAll() -> rows, upsert(row)
201
+ store de challenges : find(subjectId) -> record|null, save(subjectId, record)
202
+ ```
203
+
204
+ Une ligne vaut `{ key, value, secret, updatedAt, updatedBy }`. `value` est déjà
205
+ chiffrée quand `secret` vaut `true` — le chiffrement a lieu dans le coffre, donc
206
+ un adapter ne voit jamais un secret en clair qu'il pourrait logger par accident.
207
+
208
+ Fournis : `createMemoryCredentialStore` et `createMemoryChallengeStore` (tests et
209
+ développement), `createMongoCredentialStore` et `createMongoChallengeStore`
210
+ (n'importe quelle collection du driver MongoDB, sans mongoose ni schéma).
211
+
212
+ `isReady` compte plus qu'il n'y paraît : mongoose met les requêtes en file
213
+ d'attente quand il n'est pas connecté. Sans ce garde, une lecture resterait
214
+ suspendue au lieu de retomber sur le `.env` — un paiement figé plutôt qu'un
215
+ paiement qui marche.
216
+
217
+ ## L'hydratation de `process.env`
218
+
219
+ La plupart des codebases lisent leurs secrets en `process.env.MACHIN`, à
220
+ trente-six endroits. Convertir chacun en lecture asynchrone est un chantier
221
+ risqué pour un bénéfice nul : il suffit que `process.env` **dise la vérité**.
222
+
223
+ Trois cas, et le troisième est celui qu'on oublie :
224
+
225
+ - la base a une valeur → elle remplace celle du `.env` ;
226
+ - la base dit « débranchée » → la variable est **effacée**, le `.env` ne reprend pas ;
227
+ - la base ne dit rien → la valeur **d'origine** du `.env` est restaurée.
228
+
229
+ Sans le troisième, supprimer une clé laisserait l'ancienne valeur figée dans
230
+ `process.env` jusqu'au prochain redémarrage : un service qu'on croit débranché
231
+ et qui continue de fonctionner.
232
+
233
+ Les valeurs d'origine sont capturées **une seule fois**, au premier appel. Après
234
+ la première hydratation, `process.env` ne dit plus d'où il vient.
235
+
236
+ ## Appliquer une saisie tout de suite
237
+
238
+ `onChange` est appelé après chaque écriture — branche-y l'hydratation pour que
239
+ la nouvelle valeur serve immédiatement plutôt qu'à la minute suivante :
240
+
241
+ ```js
242
+ const vault = createCredentialVault({
243
+ store, catalog, cipher, guard,
244
+ onChange: () => hydrator.hydrate(catalog.keys())
245
+ });
246
+ ```
247
+
248
+ ## Changer de clé sans rien perdre
249
+
250
+ C'est la panne silencieuse par excellence. Remplace le cipher d'un coup et rien
251
+ ne lève : le coffre attrape l'échec de déchiffrement ligne par ligne, retombe
252
+ sur le `.env`, et toutes tes clés cessent simplement d'être utilisées. Les
253
+ paiements passent par l'ancienne valeur du fichier, ou ne passent plus du tout.
254
+ Tu l'apprends par un client, pas par un log.
255
+
256
+ Une rotation, c'est donc trois gestes — et celui du milieu est tout l'intérêt :
257
+
258
+ ```js
259
+ const { createCredentialRotation } = require('@astratra/credentials');
260
+
261
+ // 1. Le coffre lit les DEUX générations. Rien n'a bougé, rien n'est cassé.
262
+ const vault = createCredentialVault({
263
+ store, catalog, cipher: nouveauCipher, previousCipher: ancienCipher
264
+ });
265
+
266
+ // 2. Migrer, valeur par valeur.
267
+ const rotation = createCredentialRotation({
268
+ store, catalog, to: nouveauCipher, from: ancienCipher
269
+ });
270
+
271
+ console.log(await rotation.plan()); // ce qui SERAIT fait — n'écrit rien
272
+ await rotation.apply(); // écrit
273
+
274
+ // 3. Vérifier AVANT de retirer l'ancien cipher.
275
+ const { complete, pending, unreadable, unreadableKeys } = await rotation.isComplete();
276
+ ```
277
+
278
+ Ne saute jamais l'étape 3. Une valeur qu'aucun des deux ciphers ne lit est déjà
279
+ perdue, et retirer l'ancien est ce qui rend cette perte définitive —
280
+ `unreadableKeys` te dit lesquelles regarder.
281
+
282
+ Les écritures utilisent **toujours** le cipher courant, jamais l'ancien : c'est
283
+ ce qui fait converger la rotation au lieu de la faire osciller.
284
+
285
+ Tout est rejouable. Une valeur déjà migrée est reconnue et laissée intacte, donc
286
+ un passage interrompu se relance simplement.
287
+
288
+ | Ce que la rotation renvoie | Sens |
289
+ |---|---|
290
+ | `rotated` | relue avec l'ancien cipher, réécrite avec le nouveau |
291
+ | `already` | déjà lisible avec le nouveau — rien à faire |
292
+ | `plain` | déclarée `secret: false`, son clair est voulu |
293
+ | `skipped` | marqueur de débranchement ou valeur vide |
294
+ | `unreadable` | **aucun des deux ciphers ne la lit** — à examiner |
295
+
296
+ ## Ce que ce package ne fait pas
297
+
298
+ - Il ne fournit **aucun catalogue** de fournisseurs. Quelles clés existent et ce
299
+ qui cesse de marcher sans chacune, c'est ton produit qui le sait.
300
+ - Il ne **chiffre** rien lui-même : passe-lui un cipher, par exemple
301
+ `createFieldCipher` de `@astratra/security`.
302
+ - Il ne décide pas **qui** a le droit d'y toucher.
303
+ - Il n'envoie **aucun e-mail**.
304
+
305
+ ## Tests
306
+
307
+ ```bash
308
+ npm test --workspace @astratra/credentials
309
+ ```
package/package.json ADDED
@@ -0,0 +1,42 @@
1
+ {
2
+ "name": "@astratra/credentials",
3
+ "version": "0.2.0",
4
+ "description": "Encrypted service keys stored in your database, editable from the interface, with no restart.",
5
+ "engines": {
6
+ "node": ">=20"
7
+ },
8
+ "main": "src/index.js",
9
+ "types": "src/index.d.ts",
10
+ "type": "commonjs",
11
+ "files": [
12
+ "src"
13
+ ],
14
+ "scripts": {
15
+ "test": "jest"
16
+ },
17
+ "jest": {
18
+ "testMatch": [
19
+ "**/__tests__/**/*.test.js"
20
+ ]
21
+ },
22
+ "keywords": [
23
+ "astratra",
24
+ "credentials",
25
+ "secrets",
26
+ "api-keys"
27
+ ],
28
+ "license": "MIT",
29
+ "publishConfig": {
30
+ "access": "public"
31
+ },
32
+ "dependencies": {
33
+ "@astratra/core": "^1.0.0",
34
+ "express": "^4.18.3",
35
+ "express-validator": "^7.3.2"
36
+ },
37
+ "devDependencies": {
38
+ "@astratra/security": "^1.8.0",
39
+ "jest": "30.4.2",
40
+ "supertest": "^7.0.0"
41
+ }
42
+ }
package/src/catalog.js ADDED
@@ -0,0 +1,83 @@
1
+ /**
2
+ * The list of keys the interface is allowed to manage.
3
+ *
4
+ * An explicit catalogue, never a free-text field: without it any environment
5
+ * variable name could be written to the store and then read at startup — an
6
+ * open door for anyone who obtains an admin account.
7
+ *
8
+ * Astratra ships no catalogue of its own. Which providers a product uses, and
9
+ * what breaks without each key, is the product's business.
10
+ */
11
+
12
+ const DEFAULT_RESERVED_KEYS = Object.freeze([]);
13
+
14
+ function normalizeEntry(entry, spaceId, seen) {
15
+ if (!entry || typeof entry.key !== 'string' || !entry.key.trim()) {
16
+ throw new Error('createCredentialCatalog requires every entry to have a non-empty key.');
17
+ }
18
+ const key = entry.key.trim();
19
+ if (seen.has(key)) {
20
+ throw new Error(`createCredentialCatalog received the key "${key}" twice.`);
21
+ }
22
+ seen.add(key);
23
+
24
+ return {
25
+ key,
26
+ label: entry.label || key,
27
+ /* A sender address or a public client id is not a secret: encrypting it
28
+ buys nothing and stops the interface from showing it back. */
29
+ secret: entry.secret !== false,
30
+ help: entry.help || null,
31
+ where: entry.where || null,
32
+ placeholder: entry.placeholder || null,
33
+ space: spaceId
34
+ };
35
+ }
36
+
37
+ /**
38
+ * @param {object} options
39
+ * @param {Array} options.spaces groups of keys: { id, label, hint, keys: [...] }
40
+ * @param {string[]} [options.reservedKeys] names that must never reach the store.
41
+ */
42
+ function createCredentialCatalog(options = {}) {
43
+ const spaces = Array.isArray(options.spaces) ? options.spaces : [];
44
+ if (!spaces.length) {
45
+ throw new Error('createCredentialCatalog requires at least one space.');
46
+ }
47
+
48
+ const seen = new Set();
49
+ const entries = new Map();
50
+ const normalizedSpaces = spaces.map((space) => {
51
+ if (!space || typeof space.id !== 'string' || !space.id.trim()) {
52
+ throw new Error('createCredentialCatalog requires every space to have an id.');
53
+ }
54
+ const keys = (Array.isArray(space.keys) ? space.keys : []).map((entry) => {
55
+ const normalized = normalizeEntry(entry, space.id, seen);
56
+ entries.set(normalized.key, normalized);
57
+ return normalized;
58
+ });
59
+ return { id: space.id, label: space.label || space.id, hint: space.hint || null, keys };
60
+ });
61
+
62
+ /* Keys that must never be stored alongside the others. Putting the master
63
+ encryption key, the session secret or the database URL in the same table
64
+ as the values they protect is leaving the lock inside the safe. */
65
+ const reserved = new Set(options.reservedKeys || DEFAULT_RESERVED_KEYS);
66
+ for (const key of reserved) {
67
+ if (entries.has(key)) {
68
+ throw new Error(`createCredentialCatalog lists "${key}" as both managed and reserved.`);
69
+ }
70
+ }
71
+
72
+ return {
73
+ spaces: normalizedSpaces,
74
+ has: (key) => entries.has(key),
75
+ describe: (key) => entries.get(key) || null,
76
+ isReserved: (key) => reserved.has(key),
77
+ /** Every managed key name, flat — what you hand to the env hydrator. */
78
+ keys: () => [...entries.keys()],
79
+ isSecret: (key) => (entries.get(key) || { secret: true }).secret
80
+ };
81
+ }
82
+
83
+ module.exports = { createCredentialCatalog };
@@ -0,0 +1,130 @@
1
+ /**
2
+ * Pours stored keys into `process.env`, and keeps them there.
3
+ *
4
+ * Most codebases read their secrets as `process.env.SOMETHING` in thirty-six
5
+ * places. Converting every one of them into an async lookup is a risky job for
6
+ * no benefit: it is enough that `process.env` TELLS THE TRUTH. That is all this
7
+ * does — at startup, then on a timer.
8
+ *
9
+ * Three cases, and the third is the one everybody forgets:
10
+ *
11
+ * the store has a value → it replaces the one from the environment;
12
+ * the store says "unplugged" → the variable is DELETED, the env does not return;
13
+ * the store says nothing → the ORIGINAL environment value is restored.
14
+ *
15
+ * Without the third, deleting a key would leave the old value frozen in
16
+ * `process.env` until the next restart — a service you believe is unplugged and
17
+ * that keeps working.
18
+ */
19
+ const { createPermissiveGuard } = require('./valueGuard');
20
+
21
+ const NOOP_LOGGER = { warn() {} };
22
+
23
+ /**
24
+ * @param {object} options
25
+ * @param {object} options.vault from createCredentialVault().
26
+ * @param {object} [options.guard] from createValueGuard(). Permissive by default.
27
+ * @param {object} [options.env] defaults to process.env.
28
+ * @param {object} [options.logger] { warn }.
29
+ */
30
+ function createEnvHydrator(options = {}) {
31
+ const vault = options.vault;
32
+ if (!vault || typeof vault.stored !== 'function') {
33
+ throw new Error('createEnvHydrator requires options.vault from createCredentialVault().');
34
+ }
35
+ const guard = options.guard || createPermissiveGuard();
36
+ const env = options.env || process.env;
37
+ const logger = options.logger || NOOP_LOGGER;
38
+
39
+ /* What the environment said BEFORE any intervention. Captured once: after
40
+ the first hydration, `process.env` no longer remembers where it started. */
41
+ let original = null;
42
+
43
+ /** Fills the environment from the store. Never throws. */
44
+ async function hydrate(keys) {
45
+ const names = Array.isArray(keys) ? keys : [];
46
+ if (!names.length) return { applied: 0, removed: 0, restored: 0 };
47
+
48
+ if (!original) {
49
+ original = new Map(names.map((name) => [name, env[name]]));
50
+ } else {
51
+ /* A later call may cover keys the first one did not. Remember those too,
52
+ or restoring them would put back `undefined` instead of their value. */
53
+ for (const name of names) {
54
+ if (!original.has(name)) original.set(name, env[name]);
55
+ }
56
+ }
57
+
58
+ let applied = 0;
59
+ let removed = 0;
60
+ let restored = 0;
61
+
62
+ try {
63
+ const stored = await vault.stored();
64
+ const decidingValue = guard.decidingKey ? stored.get(guard.decidingKey) : undefined;
65
+
66
+ for (const name of names) {
67
+ /* The guard is checked HERE rather than in the caller — a caller can
68
+ forget, and a forgotten guard means a live key on a laptop. */
69
+ if (!guard.mayRead(name, { value: stored.get(name), decidingValue })) continue;
70
+
71
+ if (!stored.has(name)) {
72
+ const before = original.get(name);
73
+ if (env[name] !== before) {
74
+ if (before === undefined) delete env[name];
75
+ else env[name] = before;
76
+ restored += 1;
77
+ }
78
+ continue;
79
+ }
80
+
81
+ const value = stored.get(name);
82
+ if (value === null) {
83
+ if (env[name] !== undefined) {
84
+ delete env[name];
85
+ removed += 1;
86
+ }
87
+ continue;
88
+ }
89
+
90
+ if (env[name] !== value) {
91
+ env[name] = value;
92
+ applied += 1;
93
+ }
94
+ }
95
+ } catch (error) {
96
+ /* Store unreachable: the environment keeps what it has. A payment must
97
+ not fail because reading the keys hiccuped. */
98
+ logger.warn(`[credentials] hydration skipped: ${error.message}`);
99
+ }
100
+
101
+ return { applied, removed, restored };
102
+ }
103
+
104
+ /**
105
+ * Keeps the environment up to date without a restart.
106
+ * @returns {Function} call it to stop — useful in tests.
107
+ */
108
+ function startRefresh(keys, refreshOptions = {}) {
109
+ const intervalMs = refreshOptions.intervalMs || 60_000;
110
+ const onChange = refreshOptions.onChange;
111
+
112
+ const timer = setInterval(async () => {
113
+ const result = await hydrate(keys);
114
+ if (onChange && (result.applied || result.removed || result.restored)) onChange(result);
115
+ }, intervalMs);
116
+
117
+ /* This timer must never be the reason a process refuses to exit. */
118
+ if (typeof timer.unref === 'function') timer.unref();
119
+ return () => clearInterval(timer);
120
+ }
121
+
122
+ /** Forget the captured originals — tests start from a blank page. */
123
+ function reset() {
124
+ original = null;
125
+ }
126
+
127
+ return { hydrate, startRefresh, reset };
128
+ }
129
+
130
+ module.exports = { createEnvHydrator };