@dotrino/vault 0.15.0 → 0.15.1

package/README.md

@@ -91,6 +91,25 @@ que los secretos estén. Si el vault no está disponible, **espera** (reintento
 backoff) — un servicio sin vault no arranca, no opera con secretos viejos ni vacíos.
 Un fallo NO transitorio (sin enrolar, cert revocado, scope equivocado) sí aborta.
 
+#### Esperar al vault es la REGLA. La excepción es una sola
+
+Un agente enrolado **espera**. No es una preferencia: arrancar igual significaría
+operar con la configuración vieja del `.env`, que es justo lo que el vault vino a
+dejar de ser. Y la espera casi nunca duele, porque estos agentes no son críticos:
+que un bot o un firmador tarden en levantar no rompe a nadie.
+
+La **única** excepción conocida es **el proxio**, y no por importancia sino por una
+razón estructural: el vault habla con sus servicios **por el proxio**. Un proxio que
+espera al vault espera a alguien que necesita que el proxio ya esté escuchando —
+abrazo mortal, y con él se cae el vault de todo el mundo. Por eso el proxio arranca
+con lo que tenga y aplica la configuración cuando llega, con `applyEnv`.
+
+> `applyEnv` existe **para ese caso**, no como alternativa cómoda al bloqueo. Si tu
+> agente no está en el camino por el que viaja el propio vault, usa
+> `import '@dotrino/vault/config'` y deja que espere. El precio de la excepción es
+> real: lo que sólo se lee al arrancar llega tarde y no toma efecto hasta reiniciar,
+> así que hay que avisarlo en el log — el proxio lo hace.
+
 Para procesos que no son Node, el CLI los inyecta en el entorno de un hijo:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotrino/vault",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "description": "Usa ESTE dispositivo (navegador) como bóveda/CA del ecosistema Dotrino: atiende enrolamientos por el proxy y firma certificados de delegación a tus máquinas. Incluye el cliente de SERVICIO (Node): un proyecto se enrola una vez y jala sus credenciales del vault en vez del .env (`import '@dotrino/vault/config'`).",
   "type": "module",
   "main": "src/index.js",

package/src/env.js

@@ -113,10 +113,19 @@ export async function loadEnv ({ ns, dir, override, wait = true, required = [],
 /**
  * Vuelca un bundle de secretos en `process.env` y cuenta qué cambió.
  *
- * Separado de `loadEnv` porque un servicio que NO puede bloquear su arranque
- * esperando al vault (el proxy: el vault le habla POR el proxy, así que
- * esperarlo sería un abrazo mortal) igual necesita aplicar el bundle cuando
- * llegue, tarde y por su cuenta.
+ * ⚠ ESTO NO ES LA FORMA NORMAL. Un agente enrolado ESPERA al vault
+ * (`loadEnv` / `import '@dotrino/vault/config'`): arrancar igual sería operar con
+ * la configuración vieja del `.env`, que es justo lo que el vault vino a dejar de
+ * ser, y la espera casi nunca duele porque estos agentes no son críticos.
+ *
+ * `applyEnv` existe para la ÚNICA excepción estructural: **el proxio**. El vault
+ * habla con sus servicios POR el proxio, así que un proxio que espera al vault
+ * espera a alguien que necesita el proxio escuchando — abrazo mortal, y con él se
+ * cae el vault de todos. Ese caso arranca con lo que tenga y aplica el bundle
+ * cuando llega, tarde y por su cuenta.
+ *
+ * Si tu agente no está en el camino por el que viaja el propio vault, no uses
+ * esto: usa `loadEnv` y deja que espere.
  *
  * @returns {{injected:string[], overridden:string[], skipped:string[]}}
  */