@dotrino/vault 0.15.0 → 0.16.0

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
@@ -120,6 +139,48 @@ suya hacia arriba. De ahí tres reglas, que el paquete aplica solas:
 > instancias y citas vivas dejan de resolver y los peers que lo tenían pineado lo
 > rechazan hasta re-pinearlo. Es a propósito: así se echa a un nodo comprometido.
 
+### Rotar: la bóveda avisa y el agente SE REINICIA
+
+Cambiar un secreto en la bóveda no sirve de nada si quien lo usa no se entera. Al
+guardar, la bóveda manda un **aviso firmado** a los agentes de ese `ns` (sin
+valores: sólo dice que cambió), **agrupando** las escrituras seguidas para que
+cargar cinco valores no provoque cinco reinicios.
+
+El agente **no recarga en caliente: termina**, y lo levanta su supervisor (pm2,
+systemd `Restart=always`). Con `import '@dotrino/vault/config'` ya viene puesto.
+
+Salir en vez de recargar, por tres razones — y la primera es la de peso:
+
+1. **Borra de memoria el valor viejo.** En JavaScript un secreto no se puede
+   borrar: los strings son inmutables, no hay `zeroize`, y el valor sigue en el
+   heap hasta que al recolector le apetezca, más lo que capturó cada *closure* y
+   cada caché derivada. Una llave se rota casi siempre **porque se filtró**, así
+   que dejarla viva en el proceso anula el motivo de rotarla. Un proceso nuevo
+   empieza con el heap limpio.
+2. **Lee todo fresco.** Recargar en caliente exige que cada sitio que leyó una
+   variable sepa releerla; esa lista hay que mantenerla para siempre y, cuando se
+   queda corta, falla en silencio.
+3. **Es un interruptor de emergencia.** Revocar el cert de un agente ya no espera a
+   que alguien se acuerde de reiniciarlo: recibe el `REVOKED` firmado, se apaga, y
+   al arrancar `fetchSecrets` recibe «no autorizado: revoked», que no se arregla
+   reintentando. Antes, revocar no le quitaba nada a un proceso ya corriendo.
+
+Defensas, porque una señal que provoca reinicios es un arma si se descuida: firma
+de la maestra pineada, `ns` que coincida, frescura y anti-replay, **gracia de
+arranque** y **piso entre avisos** (si la configuración nueva rompe el arranque, sin
+eso el servicio entra en ciclo) y **jitter** (diez agentes del mismo `ns` no salen
+todos en el mismo segundo).
+
+```js
+import { watchEnv } from '@dotrino/vault/env'
+await watchEnv({ ns: 'miapp' })                       // termina el proceso al cambiar
+await watchEnv({ ns: 'proxy', onUpdate: (i) => … })   // o decide tú (ver abajo)
+```
+
+`onUpdate` es para cuando terminar **no es una opción**. El caso real es el proxio:
+reiniciarlo corta el transporte de todo el ecosistema, así que anota el aviso, lo
+publica en su `GET /peers` y deja el momento a un humano.
+
 ### Precedencia: el vault MANDA
 
 Los valores del vault **pisan** los del `.env` y los del entorno. El vault no

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotrino/vault",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "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/config.js

@@ -11,13 +11,21 @@
  * EL VAULT MANDA: lo que venga de aquí PISA lo que ya hubiera en el entorno
  * (incluido un `.env` cargado antes). Ver `env.js` para el porqué.
  *
+ * Y queda A LA ESCUCHA: cuando el dueño cambia la configuración en la bóveda, el
+ * proceso TERMINA para que su supervisor lo levante limpio. No se recarga en
+ * caliente a propósito — salir borra de la memoria el valor viejo, que en
+ * JavaScript no hay forma de borrar de otra manera, y una llave se rota casi
+ * siempre porque se filtró. Requiere correr bajo pm2 o systemd `Restart=always`.
+ * Se apaga con `DOTRINO_ENV_WATCH=0`.
+ *
  * Config por entorno:
  *   DOTRINO_NS            namespace de secretos (si no, el único enrolado en la máquina)
  *   DOTRINO_ENV_DIR       directorio de la identidad del servicio (si no, ~/.dotrino/service/<ns>)
  *   DOTRINO_ENV_QUIET     '1' para no imprimir la línea de arranque
  *   DOTRINO_ENV_OVERRIDE  '0' para NO pisar el entorno en esta corrida (depuración)
+ *   DOTRINO_ENV_WATCH     '0' para no escuchar avisos de cambio (no terminar solo)
  */
-import { loadEnv } from './env.js'
+import { loadEnv, watchEnv } from './env.js'
 
 const quiet = process.env.DOTRINO_ENV_QUIET === '1'
 
@@ -36,3 +44,15 @@ if (!quiet) {
     console.error('[dotrino-env] pisaron un valor previo del entorno: %s', overridden.join(', '))
   }
 }
+
+// La escucha no debe impedir que el proceso termine por su cuenta si no tiene
+// nada más que hacer, así que si falla (agente sin enrolar del todo, proxio
+// caído) se avisa y se sigue: el servicio ya tiene su configuración; lo único
+// que pierde es enterarse del próximo cambio.
+if (process.env.DOTRINO_ENV_WATCH !== '0') {
+  try {
+    await watchEnv({ ns, quiet })
+  } catch (e) {
+    if (!quiet) console.error('[dotrino-env] sin escucha de cambios (%s): habrá que reiniciar a mano al rotar', e.message)
+  }
+}

package/src/env.js

@@ -21,7 +21,7 @@
 import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
-import { fetchSecrets, waitForSecrets, readServiceIdentity } from './service.js'
+import { fetchSecrets, waitForSecrets, readServiceIdentity, watchSecretsChanges } from './service.js'
 import { isValidSecretsNs } from './protocol.js'
 
 /** Raíz donde viven las identidades de servicio de esta máquina/usuario. */
@@ -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[]}}
  */
@@ -135,3 +144,63 @@ export function applyEnv (secrets, override = overrideByDefault()) {
   }
   return { injected, overridden, skipped }
 }
+
+/**
+ * Queda a la escucha de la bóveda y, cuando avisa que la configuración cambió,
+ * TERMINA EL PROCESO para que el supervisor lo levante con todo fresco.
+ *
+ * Por qué salir en vez de recargar en caliente:
+ *
+ * 1. **Borra de memoria el valor viejo.** Es la razón de peso. En JavaScript un
+ *    secreto no se puede borrar: los strings son inmutables, no hay `zeroize`, y
+ *    el valor sigue en el heap hasta que al recolector le apetezca — más lo que
+ *    capturó cada closure y cada caché derivada. Y una llave se rota casi siempre
+ *    PORQUE SE FILTRÓ, así que dejarla viva en el proceso anula el motivo de
+ *    rotarla. Un proceso nuevo empieza con el heap limpio.
+ * 2. **Lee todo fresco.** Recargar en caliente exige que cada sitio que leyó una
+ *    variable sepa releerla; esa lista hay que mantenerla para siempre y cuando se
+ *    queda corta falla en silencio.
+ * 3. **Sirve de interruptor de emergencia.** Revocar el cert de un agente ya no
+ *    espera a que alguien se acuerde de reiniciarlo: se apaga, y al arrancar
+ *    `fetchSecrets` recibe «no autorizado: revoked» y no vuelve.
+ *
+ * NO se reinicia solo: sale, y lo levanta quien lo supervisa (pm2, systemd con
+ * `Restart=always`). Un proceso no puede reiniciarse a sí mismo de forma fiable, y
+ * el supervisor ya trae backoff y tope de intentos, que es justo lo que evita que
+ * una configuración rota se convierta en un ciclo.
+ *
+ * @param {Object} [opts]
+ * @param {string} [opts.ns]
+ * @param {string} [opts.dir]
+ * @param {(info:{ns:string, ts:number, motivo:'cambio'|'revocado'})=>void} [opts.onUpdate]
+ *   Reemplaza la salida por defecto. Úsalo cuando terminar el proceso no sea una
+ *   opción — el caso del proxio, cuyo reinicio corta el transporte de todos.
+ * @param {number} [opts.exitCode=0]  Salida LIMPIA: systemd con `Restart=on-failure`
+ *   no levantaría un servicio que sale con 0, pero `Restart=always` sí, y pm2
+ *   también. Se elige 0 porque salir a propósito no es un fallo.
+ * @returns {Promise<{stop:()=>void}>}
+ */
+export async function watchEnv ({ ns, dir, onUpdate, exitCode = 0, quiet = false, ...resto } = {}) {
+  ns = resolveNs(ns)
+  dir = dir || serviceDir(ns)
+  const decir = (m) => { if (!quiet) console.error(m) }
+
+  const salir = (motivo) => {
+    decir(`[dotrino-env] ${motivo === 'revocado'
+      ? 'la bóveda REVOCÓ este agente: terminando (no volverá a arrancar)'
+      : 'configuración nueva en la bóveda: terminando para que el supervisor lo levante limpio'}`)
+    process.exit(motivo === 'revocado' ? 1 : exitCode)
+  }
+
+  return watchSecretsChanges({
+    dir,
+    ns,
+    log: decir,
+    onChange: ({ ts }) => (onUpdate ? onUpdate({ ns, ts, motivo: 'cambio' }) : salir('cambio')),
+    // Un cert revocado sale con código de FALLO a propósito: si el supervisor lo
+    // levanta, va a morir otra vez al no poder leer sus secretos, y el contador de
+    // reinicios fallidos es lo que hace que se note en vez de girar en silencio.
+    onRevoked: () => (onUpdate ? onUpdate({ ns, ts: Date.now(), motivo: 'revocado' }) : salir('revocado')),
+    ...resto
+  })
+}

package/src/protocol.js

@@ -45,6 +45,20 @@ export const MSG = Object.freeze({
   RENEWED: 'vault.renewed',                   // vault → dispositivo: { cert }  (cert fresco, misma sub-clave/scope)
   SECRETS: 'vault.secrets',                   // servicio → vault: { data:{op,ns,ek,publickey,ts}, signature, cert }
   SECRETS_RESULT: 'vault.secrets.result',     // vault → servicio: { body:{op,ns,enc,ts}, signature } (enc SELLADO a ek; body firmado por la maestra)
+  // AVISO DE CAMBIO (no lleva valores): la bóveda dice «la configuración del ns
+  // cambió». El agente no la recarga en caliente — SALE limpio y su supervisor lo
+  // levanta. Dos razones, y la segunda es la de peso:
+  //   · Lee todo fresco. Recargar en caliente exige que cada sitio que leyó una
+  //     variable sepa releerla, y esa lista hay que mantenerla para siempre.
+  //   · BORRA DE MEMORIA EL VALOR VIEJO. En JavaScript un secreto no se puede
+  //     borrar: los strings son inmutables, no hay zeroize, y el valor queda en el
+  //     heap hasta que al recolector le apetezca — más lo que capturó cada closure
+  //     y cada caché derivada. Una llave se rota casi siempre PORQUE SE FILTRÓ, así
+  //     que dejarla viva en el proceso anula la razón de rotarla. Un proceso nuevo
+  //     empieza con el heap limpio.
+  // Va FIRMADO por la maestra y el agente lo verifica contra su `iss` pineada: un
+  // aviso de reinicio sin autenticar ES un ataque de denegación.
+  SECRETS_CHANGED: 'vault.secrets.changed',   // vault → servicio: { body:{op,ns,ts}, signature }
   ERROR: 'vault.error'                        // vault → dispositivo: { error }
 })
 

package/src/service.js

@@ -365,6 +365,143 @@ export async function fetchSecrets ({ dir, ns, proxyUrl, masterPubkey, device, c
   } finally { client.close() }
 }
 
+/**
+ * Escucha los avisos de cambio de configuración de la bóveda.
+ *
+ * A diferencia de `fetchSecrets` —que abre, pide y cierra—, esto mantiene la
+ * conexión ABIERTA e identificada con la llave del servicio: es la dirección a la
+ * que la bóveda le habla. Por eso un agente que quiera enterarse de una rotación
+ * deja de ser un cliente de paso y pasa a ser uno permanente.
+ *
+ * Lo que NO hace: recargar nada. El aviso no trae valores, y la reacción correcta
+ * es que el proceso termine y lo levante su supervisor (ver `watchEnv`).
+ *
+ * Defensas, porque una señal que provoca reinicios es un arma si se descuida:
+ * · **Firma de la maestra pineada** y `ns` que coincida. Sin esto, cualquiera
+ *   reinicia la flota ajena cuando quiera.
+ * · **Frescura y anti-replay**: `ts` dentro de la ventana y estrictamente mayor
+ *   que el último obedecido. Un aviso viejo reproducido no vuelve a disparar.
+ * · **Gracia de arranque y piso entre avisos**: no se obedece recién arrancado ni
+ *   dos veces seguidas. Si la configuración nueva rompe el arranque, sin esto el
+ *   servicio entra en un ciclo de reinicios.
+ * · **Jitter**: diez agentes del mismo ns no pueden salir todos en el mismo
+ *   segundo.
+ *
+ * @param {Object} opts
+ * @param {string} opts.dir            Identidad del servicio (`service-identity.json`).
+ * @param {string} [opts.ns]
+ * @param {(info:{ns:string, ts:number})=>void} opts.onChange
+ * @param {(info:{nonce:string})=>void} [opts.onRevoked]  Cert revocado: apagar YA.
+ * @param {number} [opts.graceMs=30000]      No obedecer avisos durante los primeros N ms.
+ * @param {number} [opts.minIntervalMs=60000] Mínimo entre dos avisos obedecidos.
+ * @param {number} [opts.jitterMs=5000]      Espera aleatoria antes de avisar.
+ * @param {(m:string)=>void} [opts.log]
+ * @returns {Promise<{stop:()=>void}>}
+ */
+export async function watchSecretsChanges ({
+  dir, ns, onChange, onRevoked, graceMs = 30000, minIntervalMs = 60000, jitterMs = 5000, log = () => {}
+} = {}) {
+  const saved = dir ? readServiceIdentity(dir) : null
+  ns = ns || saved?.ns
+  if (!saved?.device || !saved?.cert || !saved?.iss || !saved?.proxy) {
+    throw new Error('servicio sin enrolar: no hay a quién escuchar')
+  }
+  const master = saved.iss
+  const nacido = Date.now()
+  let ultimoTs = 0
+  let ultimoObedecido = 0
+  const enVuelo = new Set()   // avisos cuya firma se está comprobando ahora mismo
+  let parado = false
+  let client = null
+  let reintento = null
+
+  /**
+   * REVOCACIÓN = interruptor de emergencia. Hasta ahora revocar un cert no le
+   * quitaba nada a un servicio YA CORRIENDO: seguía operando con los secretos en
+   * memoria hasta que alguien se acordara de reiniciarlo (el README decía lo
+   * contrario). Teniendo la conexión abierta, el aviso llega y el agente se apaga
+   * en el acto — y no vuelve, porque al arrancar `fetchSecrets` recibe
+   * «no autorizado: revoked», que no se arregla reintentando.
+   *
+   * Sin gracia, sin piso y sin jitter, al revés que un cambio de configuración:
+   * apagar algo comprometido es justo lo que no debe esperar su turno.
+   */
+  const atenderRevocacion = async (payload) => {
+    const body = payload.body
+    if (!body || body.op !== 'revoke') return
+    // Que sea MI revocación y no la de otro dispositivo del mismo dueño.
+    if (body.sub !== saved.device.publickey) return
+    if (saved.cert?.nonce && body.nonce !== saved.cert.nonce) return
+    if (!(await verifyDeviceSig({ publickey: master, data: body, signature: payload.signature }))) {
+      return log('[vault] aviso de revocación MAL FIRMADO: ignorado')
+    }
+    log('[vault] ⚠ la bóveda REVOCÓ el cert de este agente: apagando')
+    try { onRevoked?.({ nonce: body.nonce }) } catch (e) { log('[vault] ' + e.message) }
+  }
+
+  const atender = async (payload) => {
+    if (payload?.type === MSG.REVOKED) return atenderRevocacion(payload)
+    if (payload?.type !== MSG.SECRETS_CHANGED) return
+    const body = payload.body
+    if (!body || body.op !== 'secrets.changed' || body.ns !== ns) return
+    if (typeof body.ts !== 'number' || Math.abs(Date.now() - body.ts) > FRESH_WINDOW_MS) {
+      return log('[vault] aviso de cambio con fecha fuera de ventana: ignorado')
+    }
+    if (body.ts <= ultimoTs) return log('[vault] aviso de cambio repetido: ignorado')
+    // Dos copias del MISMO aviso pueden llegar a la vez, y comprobar la firma es
+    // asíncrono: sin esta marca las dos pasarían el corte de `ultimoTs` antes de
+    // que ninguna lo actualizara, y el agente se reiniciaría por partida doble.
+    // La marca se pone antes del `await` y el `ultimoTs` DESPUÉS de verificar, para
+    // que un aviso falso con fecha lejana no pueda dejar fuera a los de verdad.
+    if (enVuelo.has(body.ts)) return
+    enVuelo.add(body.ts)
+    let valida = false
+    try {
+      valida = await verifyDeviceSig({ publickey: master, data: body, signature: payload.signature })
+    } finally { enVuelo.delete(body.ts) }
+    if (!valida) return log('[vault] aviso de cambio MAL FIRMADO: ignorado (no viene de tu bóveda)')
+    if (body.ts <= ultimoTs) return
+    ultimoTs = body.ts
+
+    const ahora = Date.now()
+    if (ahora - nacido < graceMs) {
+      return log('[vault] aviso de cambio recién arrancado: ignorado (evita el ciclo de reinicios)')
+    }
+    if (ahora - ultimoObedecido < minIntervalMs) {
+      return log('[vault] aviso de cambio demasiado seguido del anterior: ignorado')
+    }
+    ultimoObedecido = ahora
+
+    const espera = Math.floor(Math.random() * jitterMs)
+    log(`[vault] la bóveda avisa que la configuración de «${ns}» cambió (en ${espera} ms)`)
+    setTimeout(() => { if (!parado) { try { onChange?.({ ns, ts: body.ts }) } catch (e) { log('[vault] ' + e.message) } } }, espera)
+  }
+
+  const conectar = async () => {
+    if (parado) return
+    try {
+      client = await freshClient(saved.proxy)
+      await identifyAsService(client, saved.device)
+      client.on('message', (_from, p) => { atender(p).catch(() => {}) })
+      // Reconectar solo: si se cae el proxio, el agente deja de ser avisable, y
+      // eso es exactamente el momento en que uno querría enterarse de una rotación.
+      client.on('disconnected', () => { if (!parado) reintento = setTimeout(conectar, 5000) })
+      log('[vault] a la escucha de cambios de configuración')
+    } catch (e) {
+      if (!parado) reintento = setTimeout(conectar, 5000)
+    }
+  }
+  await conectar()
+
+  return {
+    stop () {
+      parado = true
+      clearTimeout(reintento)
+      try { client?.close() } catch (_) {}
+    }
+  }
+}
+
 /**
  * Bucle de arranque de un servicio: pide los secretos y, si el vault no está
  * disponible, REINTENTA para siempre (con backoff hasta `maxRetryMs`). El