@dotrino/vaultd 0.26.2 → 0.38.0

package/lib/src/service.js

@@ -20,6 +20,7 @@
  */
 import fs from 'node:fs'
 import path from 'node:path'
+import { createHash } from 'node:crypto'
 import {
   makeDeviceKey, signWithDevice, verifyDelegation, verifyDeviceSig,
   makePairingCode, commitCode, pubkeyId
@@ -58,7 +59,7 @@ function installNodeGlobals () {
     })
   }
   if (typeof globalThis.WebSocket === 'undefined') {
-    throw new Error('este entorno no tiene WebSocket global: usa Node ≥22')
+    throw new Error('this runtime has no global WebSocket: use Node >=22')
   }
 }
 
@@ -70,17 +71,17 @@ function installNodeGlobals () {
  * que esto no dice que sea TU bóveda — eso lo dice el código de 6 dígitos, que solo
  * aprende la bóveda donde tú lo tecleas.
  */
-async function verificarHola (p, sn) {
+async function verifyHello (p, sn) {
   const b = p?.body
-  if (!b?.iss || b.sn !== sn) throw new Error('la bóveda contestó a otro emparejamiento')
+  if (!b?.iss || b.sn !== sn) throw new Error('the vault answered a different pairing')
   if (!(await verifyDeviceSig({ publickey: b.iss, data: b, signature: p.signature }))) {
-    throw new Error('la respuesta de la bóveda no está bien firmada')
+    throw new Error('the vault reply is not properly signed')
   }
   // El modo también viene aquí, y aquí viene FIRMADO por la bóveda. Se comprueba
   // de nuevo aunque ya se haya mirado el del QR: en la forma corta el QR es un
   // código que pasó por manos ajenas, y esta es la primera vez que la bóveda
   // dice de su puño y letra qué se propone hacer.
-  rechazarAdopcion(b.m)
+  rejectAdoption(b.m)
   return b
 }
 
@@ -98,11 +99,11 @@ async function verificarHola (p, sn) {
  * invitación, en vez de dejar que el viaje termine en un «intent-mismatch» del
  * otro lado que no le explica nada a nadie.
  */
-function rechazarAdopcion (modo) {
-  if (modo !== 'adopt') return
+function rejectAdoption (mode) {
+  if (mode !== 'adopt') return
   throw new Error(
-    'esta invitación se abrió para ADOPTAR la cuenta del aparato, y un agente no transfiere su identidad: ' +
-    'la suya se la cede el vault. Abre el emparejamiento sin `--adopt` (`dotrino-vault pair --service <ns>`).'
+    'this invitation was opened to ADOPT the device account, and an agent does not transfer its identity: ' +
+    'the vault grants it one. Open the pairing without `--adopt` (`dotrino-vault pair --service <ns>`).'
   )
 }
 
@@ -113,14 +114,14 @@ function rechazarAdopcion (modo) {
  * siempre significa lo mismo para quien lo lee: el código ya se usó o venció, y
  * hay que pedir otro en la bóveda. Se dice así, no con el error crudo.
  */
-async function resolverCita (client, code) {
-  if (!code) throw new Error('la invitación no trae código de emparejamiento')
+async function resolveAppointment (client, code) {
+  if (!code) throw new Error('the invitation carries no pairing code')
   if (typeof client.redeemPairingCode !== 'function') {
-    throw new Error('el proxio no soporta códigos de emparejamiento (actualizá @dotrino/proxy-client)')
+    throw new Error('this proxy does not support pairing codes (update @dotrino/proxy-client)')
   }
   const r = await client.redeemPairingCode(code)
   if (!r?.ok || !r.instance) {
-    throw new Error(`ese código no sirve: ${r?.error || 'no válido'}. Pedí uno nuevo en la bóveda.`)
+    throw new Error(`that code is no good: ${r?.error || 'not valid'}. Ask the vault for a new one.`)
   }
   return r.instance
 }
@@ -135,7 +136,7 @@ async function freshClient (proxyUrl, connectTimeoutMs = 20000) {
   // para siempre y waitForSecrets no reintentaría. Le ponemos un timeout propio.
   let timer
   const timeout = new Promise((_, reject) => {
-    timer = setTimeout(() => reject(new Error('timeout conectando al proxy')), connectTimeoutMs)
+    timer = setTimeout(() => reject(new Error('timeout connecting to the proxy')), connectTimeoutMs)
   })
   try {
     await Promise.race([client.connect(), timeout])
@@ -143,8 +144,8 @@ async function freshClient (proxyUrl, connectTimeoutMs = 20000) {
     try { client.close() } catch (_) {}
     // El 'error' de transporte del cliente puede llegar como un Event sin
     // `message` → sin esto el operador ve una línea de error vacía.
-    const why = e?.message || e?.type || 'error de transporte'
-    throw new Error(`no se pudo conectar al proxy ${proxyUrl}: ${why}`)
+    const why = e?.message || e?.type || 'transport error'
+    throw new Error(`could not connect to the proxy ${proxyUrl}: ${why}`)
   } finally {
     clearTimeout(timer)
   }
@@ -163,7 +164,7 @@ function waitForMsg (client, predicate, timeoutMs = 30000) {
     const off = client.on('message', (_from, payload) => {
       if (payload && typeof payload === 'object' && predicate(payload)) { cleanup(); resolve(payload) }
     })
-    const t = setTimeout(() => { cleanup(); reject(new Error('timeout esperando respuesta del vault')) }, timeoutMs)
+    const t = setTimeout(() => { cleanup(); reject(new Error('timeout waiting for the vault reply')) }, timeoutMs)
     const cleanup = () => { off(); clearTimeout(t) }
   })
 }
@@ -231,26 +232,26 @@ export async function enrollService ({ qr, ns, dir, label, onCode, onReplace, ap
   // incluida la vieja, así que esto entiende cualquier invitación.
   if (typeof qr === 'string') {
     const o = parseInvite(qr)
-    if (!o) throw new Error('eso no parece una invitación del vault (pega la salida de `dotrino-vault pair --service <ns>`)')
+    if (!o) throw new Error('that does not look like a vault invitation (paste the output of `dotrino-vault pair --service <ns>`)')
     qr = o
   }
-  if (!qr?.sn || !(qr.iss || qr.conn)) throw new Error('qr inválido: falta la bóveda o el nonce')
-  rechazarAdopcion(qr.m)
-  if (!isValidSecretsNs(ns)) throw new Error('ns inválido (usa [a-z0-9-]{1,32}, p.ej. "proxy")')
-  if (!dir) throw new Error('falta dir (dónde persistir la identidad del servicio)')
-  label = label || 'servicio:' + ns
+  if (!qr?.sn || !(qr.iss || qr.conn)) throw new Error('invalid qr: missing the vault or the nonce')
+  rejectAdoption(qr.m)
+  if (!isValidSecretsNs(ns)) throw new Error('invalid ns (use [a-z0-9-]{1,32}, e.g. "proxy")')
+  if (!dir) throw new Error('dir required (where to persist the service identity)')
+  label = label || 'service:' + ns
 
   // La identidad que va a quedar descartada. Se avisa antes de tocar nada: para
   // el proxy, por ejemplo, esta llave es además su identidad de red, así que
   // reemplazarla le cambia el id de nodo y sus peers dejan de reconocerlo hasta
   // que se re-pineen a mano.
-  const anterior = readServiceIdentity(dir)
+  const previous = readServiceIdentity(dir)
   let replaced = null
-  if (anterior?.device?.publickey) {
+  if (previous?.device?.publickey) {
     replaced = {
-      ns: anterior.ns,
-      enrolledAt: anterior.enrolledAt,
-      deviceId: (await pubkeyId(anterior.device.publickey)).slice(0, 8).toUpperCase()
+      ns: previous.ns,
+      enrolledAt: previous.enrolledAt,
+      deviceId: (await pubkeyId(previous.device.publickey)).slice(0, 8).toUpperCase()
     }
     try { onReplace?.(replaced) } catch (_) {}
   }
@@ -262,17 +263,17 @@ export async function enrollService ({ qr, ns, dir, label, onCode, onReplace, ap
     // canjearla para saber a qué conexión apunta. El canje lo resuelve el proxio
     // que la emitió —lo dice el prefijo del propio código—, así que funciona
     // aunque la bóveda esté en otro proxio de la malla.
-    const destino = await resolverCita(client, qr.conn)
-    const hola = await new Promise((resolve, reject) => {
+    const target = await resolveAppointment(client, qr.conn)
+    const hello = await new Promise((resolve, reject) => {
       const off = client.on('message', (_f, p) => {
-        if (p?.type === MSG.HELLO_OK) { fin(); verificarHola(p, qr.sn).then(resolve, reject) }
-        else if (p?.type === MSG.ERROR) { fin(); reject(new Error(p.error)) }
+        if (p?.type === MSG.HELLO_OK) { finish(); verifyHello(p, qr.sn).then(resolve, reject) }
+        else if (p?.type === MSG.ERROR) { finish(); reject(new Error(p.error)) }
       })
-      const t = setTimeout(() => { fin(); reject(new Error('la bóveda no contestó: ese código pudo caducar')) }, 15000)
-      const fin = () => { off(); clearTimeout(t) }
-      try { client.send(destino, { type: MSG.HELLO, sn: qr.sn }) } catch (e) { fin(); reject(e) }
+      const t = setTimeout(() => { finish(); reject(new Error('the vault did not answer: that code may have expired')) }, 15000)
+      const finish = () => { off(); clearTimeout(t) }
+      try { client.send(target, { type: MSG.HELLO, sn: qr.sn }) } catch (e) { finish(); reject(e) }
     })
-    qr = { ...qr, iss: hola.iss, proxy: hola.proxy || qr.proxy }
+    qr = { ...qr, iss: hello.iss, proxy: hello.proxy || qr.proxy }
   }
   try {
     const device = await makeDeviceKey({ label })
@@ -294,11 +295,11 @@ export async function enrollService ({ qr, ns, dir, label, onCode, onReplace, ap
       const off = client.on('message', (_from, p) => {
         if (!p || typeof p !== 'object') return
         if (p.type === MSG.ENROLL_CHALLENGE) {
-          const show = onCode || (({ deviceId, code }) => console.log(`[vault-service] dispositivo ${deviceId} · aprueba en el vault:  dotrino-vault approve ${code}`))
+          const show = onCode || (({ deviceId, code }) => console.log(`[vault-service] device ${deviceId} · approve it on the vault:  dotrino-vault approve ${code}`))
           show({ deviceId, code })
         } else if (p.type === MSG.ENROLLED) { cleanup(); resolve(p) } else if (p.type === MSG.ERROR) { cleanup(); reject(new Error(p.error)) }
       })
-      const t = setTimeout(() => { cleanup(); reject(new Error('timeout esperando la aprobación en el vault')) }, approveTimeoutMs)
+      const t = setTimeout(() => { cleanup(); reject(new Error('timeout waiting for approval on the vault')) }, approveTimeoutMs)
       const cleanup = () => { off(); clearTimeout(t) }
     })
     client.sendByPubkey(qr.iss, { type: MSG.ENROLL, data, signature })
@@ -306,10 +307,10 @@ export async function enrollService ({ qr, ns, dir, label, onCode, onReplace, ap
 
     // Validación estricta (igual que un dispositivo): cert de la maestra VISTA,
     // para ESTA llave, y el código echado debe ser el nuestro (anti vault falso).
-    if (res.code !== code) throw new Error('el vault devolvió un código distinto al mostrado (posible relay malicioso)')
+    if (res.code !== code) throw new Error('the vault echoed a code other than the one shown (possible malicious relay)')
     const v = await verifyDelegation({ cert: res.cert, expectedSub: device.publickey, expectedScope: secretsScope(ns) })
-    if (!v.ok) throw new Error('cert inválido: ' + v.reason)
-    if (res.cert.iss !== qr.iss) throw new Error('cert firmado por una maestra distinta a la del QR')
+    if (!v.ok) throw new Error('invalid cert: ' + v.reason)
+    if (res.cert.iss !== qr.iss) throw new Error('cert signed by a master other than the one in the QR')
 
     // Reemplazo, no acumulación: el archivo se sobrescribe entero y la identidad
     // anterior deja de existir en este agente.
@@ -332,9 +333,9 @@ export async function fetchSecrets ({ dir, ns, proxyUrl, masterPubkey, device, c
   masterPubkey = masterPubkey || saved?.iss
   device = device || saved?.device
   cert = cert || saved?.cert
-  if (!isValidSecretsNs(ns)) throw new Error('ns inválido')
+  if (!isValidSecretsNs(ns)) throw new Error('invalid ns')
   if (!proxyUrl || !masterPubkey || !device || !cert) {
-    throw new Error('servicio sin enrolar: corre primero enrollService() (falta service-identity.json)')
+    throw new Error('service not enrolled: run enrollService() first (service-identity.json missing)')
   }
 
   const client = await freshClient(proxyUrl)
@@ -366,13 +367,13 @@ export async function fetchSecrets ({ dir, ns, proxyUrl, masterPubkey, device, c
 
     // Autenticidad: el cuerpo viene firmado por la MAESTRA pineada.
     const body = res.body
-    if (!body || body.op !== 'secrets.result' || body.ns !== ns) throw new Error('respuesta de secretos malformada')
-    if (typeof body.ts !== 'number' || Math.abs(Date.now() - body.ts) > FRESH_WINDOW_MS) throw new Error('respuesta de secretos vencida')
+    if (!body || body.op !== 'secrets.result' || body.ns !== ns) throw new Error('malformed secrets reply')
+    if (typeof body.ts !== 'number' || Math.abs(Date.now() - body.ts) > FRESH_WINDOW_MS) throw new Error('stale secrets reply')
     const ok = await verifyDeviceSig({ publickey: masterPubkey, data: body, signature: res.signature })
-    if (!ok) throw new Error('firma de la maestra inválida en la respuesta de secretos')
+    if (!ok) throw new Error('invalid master signature on the secrets reply')
 
     const payload = await openSealed({ privateKey: eph.privateKey, enc: body.enc })
-    if (!payload || typeof payload.secrets !== 'object') throw new Error('sobre de secretos malformado')
+    if (!payload || typeof payload.secrets !== 'object') throw new Error('malformed secrets envelope')
     return payload.secrets
   } finally { client.close() }
 }
@@ -388,6 +389,20 @@ export async function fetchSecrets ({ dir, ns, proxyUrl, masterPubkey, device, c
  * 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`).
  *
+ * NO SE CONFÍA SOLO EN EL AVISO: al (re)conectar, COMPARA. Un aviso es un mensaje y
+ * los mensajes se pierden — el agente pudo estar vivo pero incomunicado, y entonces
+ * el aviso se encola en el proxio (24 h), llega tarde y lo tira la ventana de
+ * frescura (5 min), o caduca en la cola y no llega nunca. En los tres casos el
+ * agente se quedaba con la configuración vieja PARA SIEMPRE, porque al reconectar
+ * solo volvía a escuchar: nunca preguntaba. Ahora, cada vez que la conexión se
+ * restablece, pide el bundle y compara su huella con la que tiene aplicada; si no
+ * coincide, reacciona igual que si hubiera llegado el aviso. El aviso es el camino
+ * rápido; esto es el que no se pierde.
+ *
+ * Y lo mismo salva al interruptor de emergencia: si el cert se revocó mientras
+ * estaba incomunicado, el `REVOKED` se perdió igual, pero la comparación recibe
+ * «unauthorized: revoked» y apaga al agente ahí mismo.
+ *
  * 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.
@@ -402,30 +417,53 @@ export async function fetchSecrets ({ dir, ns, proxyUrl, masterPubkey, device, c
  * @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:{ns:string, ts:number, via:'notice'|'reconcile'})=>void} opts.onChange
+ *   `via` dice por dónde se enteró: `notice` (llegó el aviso) o `reconcile` (nadie
+ *   avisó y la comparación al reconectar encontró otra configuración).
  * @param {(info:{nonce:string})=>void} [opts.onRevoked]  Cert revocado: apagar YA.
+ * @param {Record<string,string>} [opts.applied]  El bundle que el agente tiene EN USO.
+ *   Pasarlo es lo que permite detectar un cambio ya en la PRIMERA conexión — el que
+ *   ocurrió entre que el agente pidió su configuración y logró ponerse a escuchar. Sin
+ *   él no se pierde la protección, solo empieza una conexión más tarde: la primera se
+ *   limita a tomar la referencia.
  * @param {number} [opts.graceMs=30000]      No obedecer avisos durante los primeros N ms.
+ *   La comparación también lo respeta, pero **aplazándose** (el aviso sí se descarta):
+ *   es lo que impide que un fallo sistemático se convierta en un ciclo de reinicios,
+ *   porque acota los reinicios por comparación a uno por ventana.
  * @param {number} [opts.minIntervalMs=60000] Mínimo entre dos avisos obedecidos.
  * @param {number} [opts.jitterMs=5000]      Espera aleatoria antes de avisar.
+ * @param {number} [opts.reconcileMinMs=30000] Mínimo entre dos comparaciones. Sin él,
+ *   una conexión que va y viene cada cinco segundos le pediría el bundle a la bóveda
+ *   cada cinco segundos, y son N agentes.
  * @param {(m:string)=>void} [opts.log]
- * @returns {Promise<{stop:()=>void}>}
+ * @returns {Promise<{stop:()=>void, reconcile:()=>Promise<boolean>}>}
+ *   `reconcile()` fuerza la comparación (útil desde un chequeo de salud); devuelve si
+ *   encontró un cambio.
  */
 export async function watchSecretsChanges ({
-  dir, ns, onChange, onRevoked, graceMs = 30000, minIntervalMs = 60000, jitterMs = 5000, log = () => {}
+  dir, ns, onChange, onRevoked, applied, graceMs = 30000, minIntervalMs = 60000, jitterMs = 5000,
+  reconcileMinMs = 30000, 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')
+    throw new Error('service not enrolled: nobody to listen to')
   }
   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
+  const bornAt = Date.now()
+  let lastTs = 0
+  let lastObeyed = 0
+  const inFlight = new Set()   // avisos cuya firma se está comprobando ahora mismo
+  let stopped = false
   let client = null
-  let reintento = null
+  let retryTimer = null
+  // Huella de la configuración EN USO. Comparar huellas y no valores es lo que permite
+  // decir «esto no es lo que está corriendo» sin volver a manejar los secretos.
+  let fingerprint = applied === undefined ? null : fingerprintOf(applied)
+  let firstConnection = true
+  let lastReconcile = 0
+  let reconciling = false
+  let reconcileRetry = null
 
   /**
    * REVOCACIÓN = interruptor de emergencia. Hasta ahora revocar un cert no le
@@ -433,12 +471,12 @@ export async function watchSecretsChanges ({
    * 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.
+   * «unauthorized: 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 handleRevocation = 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.
@@ -451,69 +489,157 @@ export async function watchSecretsChanges ({
     try { onRevoked?.({ nonce: body.nonce }) } catch (e) { log('[vault] ' + e.message) }
   }
 
-  const atender = async (payload) => {
-    if (payload?.type === MSG.REVOKED) return atenderRevocacion(payload)
+  const handleMessage = async (payload) => {
+    if (payload?.type === MSG.REVOKED) return handleRevocation(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')
+      return log('[vault] change notice dated outside the window: ignored')
     }
-    if (body.ts <= ultimoTs) return log('[vault] aviso de cambio repetido: ignorado')
+    if (body.ts <= lastTs) return log('[vault] repeated change notice: ignored')
     // 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
+    // asíncrono: sin esta marca las dos pasarían el corte de `lastTs` 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
+    // La marca se pone antes del `await` y el `lastTs` 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
+    if (inFlight.has(body.ts)) return
+    inFlight.add(body.ts)
+    let valid = false
     try {
-      valida = await verifyDeviceSig({ publickey: master, data: body, signature: payload.signature })
-    } finally { enVuelo.delete(body.ts) }
-    if (!valida) return log('[vault] change notice BADLY SIGNED: ignored (not from your vault)')
-    if (body.ts <= ultimoTs) return
-    ultimoTs = body.ts
-
-    const ahora = Date.now()
-    if (ahora - nacido < graceMs) {
+      valid = await verifyDeviceSig({ publickey: master, data: body, signature: payload.signature })
+    } finally { inFlight.delete(body.ts) }
+    if (!valid) return log('[vault] change notice BADLY SIGNED: ignored (not from your vault)')
+    if (body.ts <= lastTs) return
+    lastTs = body.ts
+
+    const now = Date.now()
+    if (now - bornAt < graceMs) {
       return log('[vault] change notice right after start: ignored (avoids the restart loop)')
     }
-    if (ahora - ultimoObedecido < minIntervalMs) {
-      return log('[vault] aviso de cambio demasiado seguido del anterior: ignorado')
+    if (now - lastObeyed < minIntervalMs) {
+      return log('[vault] change notice too close to the previous one: ignored')
     }
-    ultimoObedecido = ahora
+    lastObeyed = now
 
-    const espera = Math.floor(Math.random() * jitterMs)
-    log(`[vault] the vault reports config for "${ns}" changed (in ${espera} ms)`)
-    setTimeout(() => { if (!parado) { try { onChange?.({ ns, ts: body.ts }) } catch (e) { log('[vault] ' + e.message) } } }, espera)
+    const wait = Math.floor(Math.random() * jitterMs)
+    log(`[vault] the vault reports config for "${ns}" changed (in ${wait} ms)`)
+    setTimeout(() => { if (!stopped) { try { onChange?.({ ns, ts: body.ts, via: 'notice' }) } catch (e) { log('[vault] ' + e.message) } } }, wait)
   }
 
-  const conectar = async () => {
-    if (parado) return
+  /**
+   * PREGUNTA en vez de esperar a que le cuenten: pide el bundle y lo compara con el
+   * que está en uso. Es la red que recoge todo lo que el aviso deja caer — el que se
+   * perdió mientras el agente estaba incomunicado, el que llegó fuera de la ventana de
+   * frescura, el que caducó en la cola del proxio y el que el propio agente descartó.
+   *
+   * Lo que compara son DOS BUNDLES DE LA BÓVEDA, nunca el `.env` contra el bundle. Por
+   * eso recibir la configuración por primera vez —tarde, que es como la recibe el
+   * proxio— no es un cambio: la referencia es lo que el agente recibió, no lo que tenía
+   * antes de recibir nada. Es la razón de fondo por la que esto no puede volverse un
+   * ciclo de reinicios; el tope de frecuencia de abajo es el cinturón.
+   *
+   * No pasa por el piso entre avisos, y es a propósito: ese freno existe porque un aviso
+   * es una señal que alguien podría repetir para provocar reinicios. Esto no es una
+   * señal, es el estado real firmado por la maestra — si de verdad difiere, reiniciar es
+   * siempre lo correcto, y al volver ya coincide.
+   *
+   * @returns {Promise<boolean>} si encontró (y anunció) un cambio.
+   */
+  const reconcile = async (trigger) => {
+    if (stopped || reconciling) return false
+    if (Date.now() - lastReconcile < reconcileMinMs) return false
+    // TOPE DE FRECUENCIA, que es lo único que separa esto de un ciclo de reinicios.
+    // Reiniciar por comparación no puede repetirse más de una vez por gracia de
+    // arranque: si algo hiciera que la comparación fallara SIEMPRE, el proceso saldría
+    // cada 30 s y no cada dos, que es la diferencia entre que el supervisor lo note y
+    // que la máquina se pase el día arrancando.
+    //
+    // Y a diferencia del aviso, aquí no se DESCARTA: se APLAZA. Descartarlo era el
+    // defecto que este cambio vino a cerrar, así que reintroducirlo por la puerta de
+    // atrás sería el peor final posible.
+    const sinceStart = Date.now() - bornAt
+    if (sinceStart < graceMs) {
+      clearTimeout(reconcileRetry)
+      reconcileRetry = setTimeout(() => { reconcile(trigger).catch(() => {}) }, graceMs - sinceStart + 50)
+      reconcileRetry.unref?.()
+      return false
+    }
+    reconciling = true
+    let bundle = null
+    try {
+      bundle = await fetchSecrets({ dir, ns })
+    } catch (e) {
+      // El cert revocado mientras estaba incomunicado: el `REVOKED` firmado se perdió
+      // igual que el aviso, y esta es la única otra forma de enterarse. Lo demás (la
+      // bóveda apagada, el proxio a medio levantar) es transitorio y se reintenta en la
+      // siguiente conexión: no se apaga nada por no haber podido preguntar.
+      if (/unauthorized: revoked/.test(e.message)) {
+        log('[vault] ⚠ the vault REVOKED this agent cert (noticed on ' + trigger + '): shutting down')
+        try { onRevoked?.({ nonce: saved.cert?.nonce || null }) } catch (err) { log('[vault] ' + err.message) }
+      } else {
+        log('[vault] could not check the config on ' + trigger + ': ' + e.message)
+      }
+      return false
+    } finally {
+      reconciling = false
+      lastReconcile = Date.now()
+    }
+    const current = fingerprintOf(bundle)
+    if (fingerprint === null) { fingerprint = current; return false }  // primera vez: solo tomar referencia
+    if (current === fingerprint) return false
+    fingerprint = current
+    lastObeyed = Date.now()
+    log(`[vault] the config for "${ns}" is not the one running (noticed on ${trigger}): the notice never arrived`)
+    if (!stopped) { try { onChange?.({ ns, ts: Date.now(), via: 'reconcile' }) } catch (e) { log('[vault] ' + e.message) } }
+    return true
+  }
+
+  const connect = async () => {
+    if (stopped) return
     try {
       client = await freshClient(saved.proxy)
       await identifyAsService(client, saved.device)
-      client.on('message', (_from, p) => { atender(p).catch(() => {}) })
+      client.on('message', (_from, p) => { handleMessage(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) })
+      client.on('disconnected', () => { if (!stopped) retryTimer = setTimeout(connect, 5000) })
       log('[vault] listening for config changes')
+      // Y COMPARAR, porque el rato sin conexión es justo cuando se pierde un aviso.
+      // También en la PRIMERA conexión, aunque el agente venga de pedir el bundle hace
+      // un instante: entre aquello y esto pudo pasar cualquier cosa —si el proxio estaba
+      // caído, esta primera conexión llega minutos después— y ahí ya no hay quien avise.
+      // Cuesta una consulta por arranque; el hueco que tapa no tiene límite.
+      const trigger = firstConnection ? 'startup' : 'reconnect'
+      firstConnection = false
+      reconcile(trigger).catch(() => {})
     } catch (e) {
-      if (!parado) reintento = setTimeout(conectar, 5000)
+      if (!stopped) retryTimer = setTimeout(connect, 5000)
     }
   }
-  await conectar()
+  await connect()
 
   return {
     stop () {
-      parado = true
-      clearTimeout(reintento)
+      stopped = true
+      clearTimeout(retryTimer)
+      clearTimeout(reconcileRetry)
       try { client?.close() } catch (_) {}
-    }
+    },
+    reconcile: () => reconcile('demand')
   }
 }
 
+/**
+ * Huella de un bundle. Las claves van ORDENADAS: el bundle se arma mezclando el cajón
+ * del scope con el del aparato, así que el mismo contenido puede llegar en otro orden y
+ * un cambio de orden no es un cambio de configuración.
+ */
+function fingerprintOf (secrets) {
+  const pairs = Object.entries(secrets || {}).map(([k, v]) => [k, String(v)]).sort((a, b) => (a[0] < b[0] ? -1 : 1))
+  return createHash('sha256').update(JSON.stringify(pairs)).digest('hex')
+}
+
 /**
  * Bucle de arranque de un servicio: pide los secretos y, si el vault no está
  * disponible, REINTENTA para siempre (con backoff hasta `maxRetryMs`). El
@@ -528,7 +654,7 @@ export async function waitForSecrets ({ dir, ns, proxyUrl, masterPubkey, device,
     } catch (e) {
       // Lo NO transitorio no se arregla reintentando: falta de enrolamiento,
       // cert revocado/vencido o scope equivocado exigen re-emparejar → se corta.
-      if (/sin enrolar|ns inválido|no autorizado: (revoked|expired|scope|cn|untrusted-issuer|cert-device-mismatch)/.test(e.message)) throw e
+      if (/not enrolled|invalid ns|unauthorized: (revoked|expired|scope|cn|untrusted-issuer|cert-device-mismatch)/.test(e.message)) throw e
       try { onRetry?.(e, delay) } catch (_) {}
       await new Promise((r) => setTimeout(r, delay))
       delay = Math.min(maxRetryMs, Math.round(delay * 1.6))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotrino/vaultd",
-  "version": "0.26.2",
+  "version": "0.38.0",
   "type": "module",
   "description": "Certificador personal de Dotrino: daemon headless que custodia la clave maestra y delega capacidades a tus dispositivos por el proxy. Tu CA propia.",
   "bin": {
@@ -13,7 +13,8 @@
     "start": "node bin/dotrino-vaultd.js",
     "pair": "node bin/dotrino-vaultd.js --pair",
     "tui": "node bin/dotrino-vault-tui.js",
-    "test": "node --test test/*.test.mjs"
+    "test": "node --test test/*.test.mjs",
+    "type-check": "tsc --noEmit"
   },
   "engines": {
     "node": ">=20"
@@ -37,9 +38,13 @@
     "src",
     "README.md",
     "vendor",
-    "lib/src"
+    "lib/src",
+    "!src/types.d.ts",
+    "!lib/src/types.d.ts"
   ],
   "devDependencies": {
-    "@dotrino/remote-agent": "^0.3.0"
+    "@dotrino/remote-agent": "^0.3.0",
+    "typescript": "^5.7.3",
+    "@types/node": "^22.0.0"
   }
 }