@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 +21 -0
- package/README.md +309 -0
- package/package.json +42 -0
- package/src/catalog.js +83 -0
- package/src/envHydrator.js +130 -0
- package/src/index.d.ts +304 -0
- package/src/index.js +11 -0
- package/src/rotation.js +165 -0
- package/src/routes.js +102 -0
- package/src/stores.js +115 -0
- package/src/unlockChallenge.js +153 -0
- package/src/utils.js +40 -0
- package/src/valueGuard.js +115 -0
- package/src/vault.js +303 -0
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 };
|