@dotrino/vault 0.22.0 → 0.24.0

package/README.md

@@ -173,7 +173,7 @@ Salir en vez de recargar, por tres razones — y la primera es la de peso:
    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
+   al arrancar `fetchSecrets` recibe «unauthorized: 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

package/bin/dotrino-env.js

@@ -58,7 +58,7 @@ Entorno: DOTRINO_NS · DOTRINO_ENV_DIR · DOTRINO_ENV_HOME · DOTRINO_ENV_QUIET
  */
 function parseInvite (raw) {
   const o = sharedParseInvite(raw)
-  if (!o) throw new Error('no parece una invitación del vault')
+  if (!o) throw new Error('that does not look like a vault invitation')
   return o
 }
 
@@ -81,7 +81,7 @@ async function cmdEnroll () {
     qr,
     ns,
     dir,
-    label: flag('label') || 'servicio:' + ns,
+    label: flag('label') || 'service:' + ns,
     // Un agente tiene UNA identidad y se la da el vault: re-enrolar REEMPLAZA,
     // no acumula. Antes había una reja (`--force`) que hacía de esto un error a
     // desbloquear; sobra, porque no existe la alternativa de "quedarse con las
@@ -130,9 +130,9 @@ async function cmdCheck () {
   console.log('ns "%s": %d secreto(s)%s', ns, keys.length, keys.length ? ':' : '')
   for (const k of keys) console.log('  ' + k)   // NUNCA los valores
   // Delata el `.env` rancio: qué claves de esta máquina el vault pisaría.
-  const chocan = keys.filter((k) => k in process.env && process.env[k] !== String(secrets[k]))
-  if (chocan.length) {
-    console.log('\nEl vault PISA estos valores del entorno de esta máquina:\n  %s', chocan.join(', '))
+  const clashing = keys.filter((k) => k in process.env && process.env[k] !== String(secrets[k]))
+  if (clashing.length) {
+    console.log('\nEl vault PISA estos valores del entorno de esta máquina:\n  %s', clashing.join(', '))
   }
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dotrino/vault",
-  "version": "0.22.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'`).",
+  "version": "0.24.0",
+  "description": "Usa ESTE dispositivo (navegador) como b\u00f3veda/CA del ecosistema Dotrino: atiende enrolamientos por el proxy y firma certificados de delegaci\u00f3n a tus m\u00e1quinas. 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",
   "module": "src/index.js",
@@ -50,5 +50,12 @@
     "type": "git",
     "url": "git+https://github.com/imdotrino/dotrino-vault.git",
     "directory": "lib"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.3",
+    "@types/node": "^22.0.0"
+  },
+  "scripts": {
+    "type-check": "tsc --noEmit"
   }
 }

package/src/admin.js

@@ -9,8 +9,16 @@
  *
  *   sí  · ver el acta y la bitácora · iniciar un emparejamiento (mostrar el QR)
  *       · APROBAR o rechazar a quien entra · REVOCAR a un miembro
+ *       · VARIABLES DE ENTORNO: crearlas y darles valor (de un scope o de un aparato),
+ *         y ver el valor de las marcadas PÚBLICAS
  *   no  · cambiar permisos · traspasar el mando · conceder `admin`
- *       · nada de los secretos de servicios
+ *       · ver el valor de una variable PRIVADA · borrar variables
+ *
+ * SOBRE LAS VARIABLES, que es la rendija más nueva: lo que cruza la frontera no es «los
+ * secretos» sino los que su dueño MARCÓ como mostrables. Una privada se puede reescribir
+ * a ciegas desde la consola, pero su valor no sale de la máquina de la bóveda ni para un
+ * aparato tuyo con `admin`. Y los valores que sí salen viajan CIFRADOS con la clave de
+ * contenido del perfil (quien llama sella y abre): el proxy transporta y no ve nada.
  *
  * La frontera no es un capricho: un admin puede **admitir y expulsar**, pero no
  * reescribir quién manda. Así un aparato con `admin` robado hace daño **acotado y
@@ -26,7 +34,15 @@
  */
 
 /** Las únicas operaciones que existen a distancia. Lista cerrada, como las capacidades. */
-export const ADMIN_OPS = Object.freeze(['pending', 'pair', 'approve', 'reject', 'revoke', 'audit'])
+export const ADMIN_OPS = Object.freeze([
+  'pending', 'pair', 'approve', 'reject', 'revoke', 'audit',
+  // Variables de entorno: verlas (nombres siempre; valor solo de las públicas) y
+  // ponerles valor (de las dos). Borrar NO está, y es a propósito: un aparato robado
+  // no debe poder dejar sin configuración a los servicios.
+  // `var.setMany` es la MISMA operación con varias variables dentro de un solo sobre: no
+  // añade permisos, quita reinicios (ver el enrutado abajo).
+  'vars', 'var.set', 'var.setMany'
+])
 
 /** Cuánto se recuerda un nonce ya usado (el doble de la ventana de frescura). */
 export const ADMIN_NONCE_TTL_MS = 10 * 60 * 1000
@@ -40,13 +56,18 @@ export const AUDIT_MAX = 500
  * @param {(scope:string[])=>Promise<any>} o.verify  verifica cadena+cert; devuelve `{ok, device, reason}`.
  * @param {(limit:number)=>any[]} o.readActivity     últimas entradas de la bitácora.
  * @param {(pub:string)=>Promise<string>} o.deviceIdOf
+ * @param {{list:(a:object)=>Promise<any>, set:(a:object)=>Promise<any>, setMany?:(a:object)=>Promise<any>}} [o.vars]
+ *   mostrador de VARIABLES DE ENTORNO. Va inyectado porque aquí no hay cripto ni disco:
+ *   quien lo implementa (la bóveda) es quien sella con la clave de contenido del perfil y
+ *   quien decide qué valor puede salir. Sin él, las ops de variables responden que esta
+ *   bóveda no las atiende, en vez de fingir que se aplicaron.
  * @param {(ev:string, info?:object)=>Promise<void>} [o.notify]  aviso a todos los miembros.
  * @param {(op:string, info?:object)=>void} [o.audit]
  * @param {string[]} [o.defaultScope]    lo que recibe un dispositivo emparejado a distancia.
  * @param {number} [o.ttlMs]             vida del cert que se emita.
  */
 export function createAdminDesk ({
-  desk, verify, readActivity = () => [], deviceIdOf,
+  desk, verify, readActivity = () => [], deviceIdOf, vars = null,
   notify = async () => {}, audit = () => {},
   defaultScope = ['vault:sign', 'vault:read', 'vault:store'],
   ttlMs, now = () => Date.now()
@@ -127,6 +148,70 @@ export function createAdminDesk ({
         return { ok: true, result: { ok: true } }
       }
 
+      // VARIABLES DE ENTORNO. El módulo solo enruta y audita: qué valor puede salir y con
+      // qué se cifra lo decide la bóveda (`vars`), que es la que tiene la clave y el disco.
+      if (data.op === 'vars' || data.op === 'var.set' || data.op === 'var.setMany') {
+        if (!vars) return { ok: false, error: 'admin: this vault does not serve environment variables' }
+        // Un destino y solo uno: o un scope, o un aparato. Sin esto, mandar los dos dejaría
+        // que quien llama adivine dónde acabó su variable.
+        // Booleanos a propósito: comparar los VALORES («proxy» vs una pubkey) nunca da
+        // igual, así que mandar los dos destinos se colaba por el hueco.
+        const toScope = typeof data.ns === 'string' && !!data.ns
+        const toDevice = typeof data.pub === 'string' && !!data.pub
+        if (data.op === 'vars') {
+          const result = await vars.list({ by })
+          audit('admin.vars', { by })
+          return { ok: true, result }
+        }
+        if (toScope === toDevice) return { ok: false, error: 'admin: var.set needs exactly one target (ns or pub)' }
+
+        // VARIAS DE UNA VEZ. Mismo permiso y misma frontera que una sola: lo que cambia es
+        // que la bóveda las guarda juntas y manda UN aviso de cambio en vez de uno por
+        // variable — o sea, el servicio se reinicia una vez, con la configuración entera,
+        // en lugar de arrancar a medias mientras quien administra sigue escribiendo.
+        // Los nombres viajan DENTRO del sobre, igual que los valores: el proxy tampoco
+        // tiene por qué aprender cómo se llaman las variables de un servicio.
+        if (data.op === 'var.setMany') {
+          // Una bóveda anterior a esto sabe guardar de una en una y nada más. Decirlo es
+          // mejor que reventar con un TypeError que no explica qué falta actualizar.
+          if (typeof vars.setMany !== 'function') return { ok: false, error: 'admin: this vault cannot save several variables at once (update it)' }
+          if (!data.enc || typeof data.enc !== 'object') {
+            return { ok: false, error: 'admin: var.setMany needs the variables sealed with the profile content key' }
+          }
+          const result = await vars.setMany({
+            ns: toScope ? data.ns : null,
+            pub: toDevice ? data.pub : null,
+            enc: data.enc,
+            public: typeof data.public === 'boolean' ? data.public : undefined,
+            by
+          })
+          const keys = result?.keys || []
+          audit('admin.var.set', { by, ns: toScope ? data.ns : null, device: toDevice ? await deviceIdOf(data.pub).catch(() => null) : null, keys })
+          await notify('vars', { by, keys, ns: toScope ? data.ns : null })
+          return { ok: true, result: result || { ok: true } }
+        }
+
+        if (typeof data.key !== 'string' || !data.key) return { ok: false, error: 'admin: var.set needs a key' }
+        if (!data.enc || typeof data.enc !== 'object') {
+          // El valor NUNCA viaja en claro: si llega sin sobre, es un error de quien llama,
+          // no algo que se pueda «arreglar» aceptándolo.
+          return { ok: false, error: 'admin: var.set needs the value sealed with the profile content key' }
+        }
+        const result = await vars.set({
+          ns: toScope ? data.ns : null,
+          pub: toDevice ? data.pub : null,
+          key: data.key,
+          enc: data.enc,
+          public: typeof data.public === 'boolean' ? data.public : undefined,
+          by
+        })
+        audit('admin.var.set', { by, ns: toScope ? data.ns : null, device: toDevice ? await deviceIdOf(data.pub).catch(() => null) : null, key: data.key })
+        // Cambiar la configuración de un servicio a distancia no puede ser invisible: es
+        // la contrapartida de delegar (F3 de docs/consola-remota.md).
+        await notify('vars', { by, key: data.key, ns: toScope ? data.ns : null })
+        return { ok: true, result: result || { ok: true } }
+      }
+
       // QUITAR UN DISPOSITIVO se hace por `sub` (su llave): sale del acta Y se le retiran
       // todos los certificados. Las dos cosas o ninguna.
       //

package/src/config.js

@@ -53,6 +53,6 @@ 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)
+    if (!quiet) console.error('[dotrino-env] no watch for changes (%s): a rotation will need a manual restart', e.message)
   }
 }

package/src/enroll.js

@@ -234,7 +234,7 @@ export function createEnrollDesk ({
     }
     if (intent !== (pend.mode || 'join')) {
       audit('rejected', { what: 'enroll', reason: 'intent-mismatch' })
-      return reply(from, { type: MSG_ERROR, error: `este emparejamiento se abrió para «${pend.mode || 'join'}» y el dispositivo pidió «${intent}»` })
+      return reply(from, { type: MSG_ERROR, error: `this pairing was opened for "${pend.mode || 'join'}" and the device asked for "${intent}"` })
     }
     if (!isFresh(d)) {
       audit('rejected', { what: 'enroll', reason: 'stale' })
@@ -332,25 +332,25 @@ export function createEnrollDesk ({
     // Aprobar un emparejamiento ES admitir al dispositivo en el perfil: el cert es la
     // credencial y el acta es la política, y no tiene sentido emitir una sin la otra.
     // Las capacidades salen del scope que se pidió al emparejar (cert ∩ acta, §2.3).
-    let acta = null
+    let record = null
     try {
       if (typeof identity.admitMember === 'function') {
         const cn = scopeToCn(pend.scope)
         const caps = cn ? ['secrets'] : scopeToCaps(pend.scope)
         if (caps.length) await identity.admitMember({ pub: pend.dpub, encPub: pend.encPub || null, label: pend.label || '', cn, caps, cert, continuity: pend.continuity || null })
       }
-      acta = (await identity.profileActa?.())?.acta || null
-    } catch (e) { log('[vault] no se pudo admitir en el acta:', e.message) }
+      record = (await identity.profileActa?.())?.acta || null
+    } catch (e) { log('[vault] could not admit into the record:', e.message) }
 
     audit('enroll', { device: pend.deviceId, label: pend.label || '', scope: pend.scope })
     // Echamos el código tipeado junto al cert: el DISPOSITIVO acepta solo si coincide
     // con el que generó → una bóveda falsa (que no lo conoce) no puede enrolarlo.
     // El acta viaja con el cert: el dispositivo ya sabe de quién es el perfil al que entra.
-    reply(pend.from, { type: MSG_ENROLLED, code, cert, iss, acta })
+    reply(pend.from, { type: MSG_ENROLLED, code, cert, iss, acta: record })
     pend.state = 'DONE'
     pending.delete(pend.token)
     fire(onPendingChange)
-    log('[vault] dispositivo aprobado: %s', pend.deviceId)
+    log('[vault] device approved: %s', pend.deviceId)
     return { ok: true, deviceId: pend.deviceId, cert }
   }
 
@@ -370,39 +370,39 @@ export function createEnrollDesk ({
    * pisar una cuenta con datos, y eso no puede pasar por accidente.
    */
   async function handleActaSealed (from, p) {
-    const acta = p?.acta
+    const record = p?.acta
     const pend = [...pending.values()].find((x) => x.state === 'AWAITING_ACTA' && (x.from === from || x.dpub))
     if (!pend) return reply(from, { type: MSG_ERROR, error: 'no adoption awaiting a record' })
-    if (!acta || typeof acta !== 'object') return reply(from, { type: MSG_ERROR, error: 'record missing or unreadable' })
-    if (acta.sealer !== iss) {
+    if (!record || typeof record !== 'object') return reply(from, { type: MSG_ERROR, error: 'record missing or unreadable' })
+    if (record.sealer !== iss) {
       audit('rejected', { what: 'adopt', reason: 'not-sealer' })
       return reply(from, { type: MSG_ERROR, error: 'that record does not name this vault as the sealer' })
     }
-    if (acta.sealedBy !== pend.dpub) {
+    if (record.sealedBy !== pend.dpub) {
       audit('rejected', { what: 'adopt', reason: 'sealed-by-other' })
       return reply(from, { type: MSG_ERROR, error: 'that record was not sealed by the device of this pairing' })
     }
-    if (pend.profileId && acta.profileId !== pend.profileId) {
+    if (pend.profileId && record.profileId !== pend.profileId) {
       audit('rejected', { what: 'adopt', reason: 'other-profile' })
       return reply(from, { type: MSG_ERROR, error: 'that record belongs to an account other than the one the device announced' })
     }
 
     try {
-      const r = await identity.joinProfile(acta)
+      const r = await identity.joinProfile(record)
       if (!r?.joined) throw new Error(r?.reason || 'could not adopt')
-      audit('adopt', { device: pend.deviceId, profile: acta.profileId, seq: acta.seq })
+      audit('adopt', { device: pend.deviceId, profile: record.profileId, seq: record.seq })
       // El acta que vuelve es la que la bóveda tiene guardada: el aparato la adopta y los
       // dos quedan en la misma versión.
-      const mia = (await identity.profileActa?.())?.acta || acta
-      reply(pend.from, { type: MSG_ACTA_ADOPTED, code: p.code, acta: mia })
+      const mine = (await identity.profileActa?.())?.acta || record
+      reply(pend.from, { type: MSG_ACTA_ADOPTED, code: p.code, acta: mine })
       pend.state = 'DONE'
       pending.delete(pend.token)
       fire(onPendingChange)
-      fire(onAdopted, { deviceId: pend.deviceId, profileId: acta.profileId, seq: mia.seq })
-      log('[vault] cuenta adoptada del dispositivo %s (perfil %s)', pend.deviceId, acta.profileId?.slice(0, 12))
-      return { ok: true, adopted: true, profileId: acta.profileId, seq: mia.seq }
+      fire(onAdopted, { deviceId: pend.deviceId, profileId: record.profileId, seq: mine.seq })
+      log('[vault] account adopted from device %s (profile %s)', pend.deviceId, record.profileId?.slice(0, 12))
+      return { ok: true, adopted: true, profileId: record.profileId, seq: mine.seq }
     } catch (e) {
-      log('[vault] no se pudo adoptar la cuenta: %s', e.message)
+      log('[vault] could not adopt the account: %s', e.message)
       reply(pend.from, { type: MSG_ERROR, error: 'the vault could not adopt the account: ' + e.message })
       return { ok: false, error: e.message }
     }
@@ -438,9 +438,9 @@ export function createEnrollDesk ({
   async function revoke (nonce) {
     audit('revoke', { nonce })
     const { issued } = await identity.listDelegations()
-    const dele = (issued || []).find((d) => d.nonce === nonce)
+    const delegation = (issued || []).find((d) => d.nonce === nonce)
     const res = await identity.revokeDelegation(nonce)
-    if (dele?.sub) await emitRevoke(dele.sub, nonce)
+    if (delegation?.sub) await emitRevoke(delegation.sub, nonce)
     return res
   }
 

package/src/env.js

@@ -32,7 +32,7 @@ export function serviceRoot () {
 /** Directorio de la identidad del servicio `ns` (`DOTRINO_ENV_DIR` lo pisa). */
 export function serviceDir (ns) {
   if (process.env.DOTRINO_ENV_DIR) return process.env.DOTRINO_ENV_DIR
-  if (!isValidSecretsNs(ns)) throw new Error('ns inválido (usa [a-z0-9-]{1,32}, p. ej. "miapp")')
+  if (!isValidSecretsNs(ns)) throw new Error('invalid ns (use [a-z0-9-]{1,32}, e.g. "myapp")')
   return path.join(serviceRoot(), ns)
 }
 
@@ -50,15 +50,15 @@ export function listEnrolled () {
 export function resolveNs (ns) {
   ns = ns || process.env.DOTRINO_NS
   if (ns) {
-    if (!isValidSecretsNs(ns)) throw new Error('ns inválido: ' + ns)
+    if (!isValidSecretsNs(ns)) throw new Error('invalid ns: ' + ns)
     return ns
   }
   const found = listEnrolled()
   if (found.length === 1) return found[0]
   if (found.length === 0) {
-    throw new Error('no hay ningún servicio enrolado en esta máquina: corre `npx dotrino-env enroll --ns <tu-app>`')
+    throw new Error('no service enrolled on this machine: run `npx dotrino-env enroll --ns <your-app>`')
   }
-  throw new Error(`hay varios servicios enrolados (${found.join(', ')}): elige uno con DOTRINO_NS=<ns> o loadEnv({ ns })`)
+  throw new Error(`several services are enrolled (${found.join(', ')}): pick one with DOTRINO_NS=<ns> or loadEnv({ ns })`)
 }
 
 /**
@@ -81,6 +81,9 @@ function overrideByDefault () {
   return process.env.DOTRINO_ENV_OVERRIDE !== '0'
 }
 
+/** El último bundle que `applyEnv` puso a correr en este proceso (ver `watchEnv`). */
+let lastApplied = null
+
 /**
  * Trae los secretos del ns desde el vault y los pone en `process.env`.
  *
@@ -104,7 +107,7 @@ export async function loadEnv ({ ns, dir, override, wait = true, required = [],
 
   const missing = required.filter((k) => !(k in secrets))
   if (missing.length) {
-    throw new Error(`faltan secretos en el ns "${ns}": ${missing.join(', ')} (agrégalos con \`dotrino-vault secret set ${ns} <CLAVE> <valor>\`)`)
+    throw new Error(`missing secrets in ns "${ns}": ${missing.join(', ')} (add them with \`dotrino-vault secret set ${ns} <KEY> <value>\`)`)
   }
 
   return { ns, secrets, ...applyEnv(secrets, override) }
@@ -130,17 +133,21 @@ export async function loadEnv ({ ns, dir, override, wait = true, required = [],
  * @returns {{injected:string[], overridden:string[], skipped:string[]}}
  */
 export function applyEnv (secrets, override = overrideByDefault()) {
+  // Lo último que este proceso puso a correr. `watchEnv` lo toma como referencia para
+  // comparar, así que cualquier agente que use `loadEnv`/`applyEnv` —o sea, todos—
+  // queda protegido del aviso perdido sin cablear nada.
+  lastApplied = { ...(secrets || {}) }
   const injected = []
   const overridden = []
   const skipped = []
   for (const [k, v] of Object.entries(secrets || {})) {
-    const previo = process.env[k]
-    const tenia = k in process.env
-    if (!override && tenia) { skipped.push(k); continue }
-    const valor = String(v)
-    process.env[k] = valor
+    const previous = process.env[k]
+    const had = k in process.env
+    if (!override && had) { skipped.push(k); continue }
+    const value = String(v)
+    process.env[k] = value
     injected.push(k)
-    if (tenia && previo !== valor) overridden.push(k)
+    if (had && previous !== value) overridden.push(k)
   }
   return { injected, overridden, skipped }
 }
@@ -169,10 +176,22 @@ export function applyEnv (secrets, override = overrideByDefault()) {
  * 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.
  *
+ * No depende solo del aviso: al conectar COMPARA su configuración con la de la bóveda
+ * (`watchSecretsChanges`), porque un agente incomunicado se pierde el aviso y antes se
+ * quedaba con lo viejo para siempre.
+ *
+ * OJO con lo que se compara: el bundle de la bóveda contra el bundle de la bóveda,
+ * nunca contra el `.env`. Recibir la configuración por primera vez —tarde, que es como
+ * la recibe el proxio— **no** es un cambio, y por eso esto no puede convertirse en un
+ * ciclo de reinicios.
+ *
  * @param {Object} [opts]
  * @param {string} [opts.ns]
  * @param {string} [opts.dir]
- * @param {(info:{ns:string, ts:number, reason:'changed'|'revoked'})=>void} [opts.onUpdate]
+ * @param {Record<string,string>} [opts.applied]  Lo que este proceso tiene EN USO. Por
+ *   defecto, lo último que pasó por `applyEnv` en este proceso — o sea, lo que puso a
+ *   correr `loadEnv`.
+ * @param {(info:{ns:string, ts:number, reason:'changed'|'revoked', via?:'notice'|'reconcile'})=>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`
@@ -180,27 +199,28 @@ export function applyEnv (secrets, override = overrideByDefault()) {
  *   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 } = {}) {
+export async function watchEnv ({ ns, dir, applied = lastApplied ?? undefined, onUpdate, exitCode = 0, quiet = false, ...rest } = {}) {
   ns = resolveNs(ns)
   dir = dir || serviceDir(ns)
   const say = (m) => { if (!quiet) console.error(m) }
 
   const exitNow = (reason) => {
     say(`[dotrino-env] ${reason === 'revoked'
-      ? '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'}`)
+      ? 'the vault REVOKED this agent: exiting (it will not start again)'
+      : 'new config in the vault: exiting so the supervisor brings it back clean'}`)
     process.exit(reason === 'revoked' ? 1 : exitCode)
   }
 
   return watchSecretsChanges({
     dir,
     ns,
+    applied,
     log: say,
-    onChange: ({ ts }) => (onUpdate ? onUpdate({ ns, ts, reason: 'changed' }) : exitNow('changed')),
+    onChange: ({ ts, via }) => (onUpdate ? onUpdate({ ns, ts, reason: 'changed', via }) : exitNow('changed')),
     // 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(), reason: 'revoked' }) : exitNow('revoked')),
-    ...resto
+    ...rest
   })
 }

package/src/envtext.js

@@ -0,0 +1,94 @@
+/**
+ * Lector de `.env` — el formato en el que la gente YA tiene la configuración de un
+ * servicio, y por lo tanto la forma natural de cargarla entera de una vez.
+ *
+ * Existe aquí, en la lib pura, porque lo usan los tres sitios desde los que se cargan
+ * variables: el CLI (`secret import`), la TUI y la consola remota (pegar el bloque en
+ * la web). Tres lectores distintos serían tres formatos distintos.
+ *
+ * POR QUÉ ESTO IMPORTA MÁS DE LO QUE PARECE: cada variable guardada suelta es, para la
+ * bóveda, un cambio de configuración, y el servicio obedece el primero —sale y lo
+ * levanta su supervisor— mientras el dueño sigue tecleando las demás. Cargarlas juntas
+ * es lo que hace que el servicio se reinicie UNA vez, con todo puesto.
+ *
+ * Los errores salen como CÓDIGOS, no como frases: quien llama los traduce (el CLI en
+ * español, la consola en los dos idiomas).
+ */
+import { isValidVarKey } from './protocol.js'
+
+/**
+ * `CLAVE=valor` — la clave no lleva espacios ni `=`; el valor puede llevar de todo. Se
+ * toleran los espacios alrededor del `=` porque un `.env` escrito a mano los trae, y
+ * rechazar un archivo entero por eso sería quisquilloso sin ganar nada.
+ */
+export const PAIR_RE = /^([^=\s]+)\s*=\s*([\s\S]*)$/
+
+/**
+ * @param {string} text
+ * @returns {{items: Array<{op:'set', key:string, value:string}>,
+ *            errors: Array<{code:'shape'|'dup'|'key'|'novalue'|'empty', line?:number, key?:string, first?:number}>}}
+ */
+export function parseEnvText (text) {
+  /** @type {Array<{op:'set', key:string, value:string}>} */
+  const items = []
+  /** @type {Array<{code:'shape'|'dup'|'key'|'novalue'|'empty', line?:number, key?:string, first?:number}>} */
+  const errors = []
+  const seen = new Map()
+  const lines = String(text || '').split(/\r?\n/)
+
+  lines.forEach((raw, idx) => {
+    const line = idx + 1
+    const trimmed = raw.trim()
+    // Línea vacía o comentario entero. Un `#` a MITAD de línea NO se corta: una
+    // contraseña puede llevarlo, y recortar el valor ahí lo estropea en silencio —que
+    // en un secreto significa un servicio que no levanta y nadie sabe por qué.
+    if (!trimmed || trimmed.startsWith('#')) return
+    const m = PAIR_RE.exec(trimmed.replace(/^export\s+/, ''))
+    if (!m) return errors.push({ code: 'shape', line })
+
+    const key = m[1]
+    const value = unquote(m[2].trim())
+    if (!isValidVarKey(key)) return errors.push({ code: 'key', line, key })
+    if (!value) return errors.push({ code: 'novalue', line, key })
+    // Repetida = casi siempre un pegado a medias. Adivinar cuál de las dos quería el
+    // dueño no es asunto de un lector de configuración.
+    if (seen.has(key)) return errors.push({ code: 'dup', line, key, first: seen.get(key) })
+    seen.set(key, line)
+    items.push({ op: 'set', key, value })
+  })
+
+  if (!items.length && !errors.length) errors.push({ code: 'empty' })
+  return { items, errors }
+}
+
+/**
+ * Lo mismo, pero aceptando que todo venga en UNA línea (`K=v K2=v2`), que es lo que se
+ * puede escribir en un campo de una sola línea como el de la TUI. Un valor con espacios
+ * va entre comillas, igual que en la shell.
+ */
+export function parseEnvInput (text) {
+  const s = String(text || '')
+  return parseEnvText(/\r?\n/.test(s) ? s : tokenize(s).join('\n'))
+}
+
+/** Parte por espacios, pero no dentro de comillas. */
+function tokenize (line) {
+  const out = []
+  let cur = ''
+  let quote = null
+  for (const ch of line) {
+    if (quote) { cur += ch; if (ch === quote) quote = null; continue }
+    if (ch === '"' || ch === "'") { quote = ch; cur += ch; continue }
+    if (/\s/.test(ch)) { if (cur) { out.push(cur); cur = '' } ; continue }
+    cur += ch
+  }
+  if (cur) out.push(cur)
+  return out
+}
+
+/** Quita las comillas de FUERA: un `.env` las usa cuando el valor lleva espacios. */
+function unquote (v) {
+  const q = v[0]
+  if (v.length > 1 && (q === '"' || q === "'") && v.endsWith(q)) return v.slice(1, -1)
+  return v
+}

package/src/index.js

@@ -52,7 +52,7 @@ export { deviceIdOf }
  */
 export async function startDeviceVault (identity, { proxyUrl, client: injectedClient } = {}) {
   const iss = identity.me?.publickey
-  if (!iss) throw new Error('sin identidad: crea/desbloquea tu identidad antes de usar el dispositivo como bóveda')
+  if (!iss) throw new Error('no identity: create/unlock your identity before using this device as a vault')
   const proxy = proxyUrl || 'wss://proxy.dotrino.com'
 
   // ----- self-cert P ← P (para que este dispositivo pueda además actuar de cliente
@@ -133,7 +133,7 @@ export async function startDeviceVault (identity, { proxyUrl, client: injectedCl
    */
   async function handleRenew (from, p) {
     const d = p?.data
-    if (!d || !p.signature || !p.cert) return send(from, { type: MSG.ERROR, error: 'petición inválida' })
+    if (!d || !p.signature || !p.cert) return send(from, { type: MSG.ERROR, error: 'invalid request' })
     if (typeof d.ts !== 'number' || Math.abs(Date.now() - d.ts) > FRESH_WINDOW_MS) {
       return send(from, { type: MSG.ERROR, error: 'stale request: ts outside the ±5 min window (possible replay, or the device clock is off)' })
     }
@@ -151,10 +151,10 @@ export async function startDeviceVault (identity, { proxyUrl, client: injectedCl
   // QUIEN consulta es una máquina ya revocada (reapareció), le re-emite el REVOKED firmado.
   async function handleDevices (from, p) {
     const d = p?.data
-    if (!d || !p.signature || !p.cert) return send(from, { type: MSG.ERROR, error: 'petición inválida' })
+    if (!d || !p.signature || !p.cert) return send(from, { type: MSG.ERROR, error: 'invalid request' })
     if (typeof d.ts !== 'number' || Math.abs(Date.now() - d.ts) > FRESH_WINDOW_MS) return
     const chk = await verifyChain({ data: d, signature: p.signature, cert: p.cert, trustedIssuer: iss })
-    if (!chk.ok) return send(from, { type: MSG.ERROR, error: 'no autorizado: ' + chk.reason })
+    if (!chk.ok) return send(from, { type: MSG.ERROR, error: 'unauthorized: ' + chk.reason })
     const { issued, revoked, revokedCerts } = await identity.listDelegations()
     const devices = await Promise.all((issued || []).map(async (x) => ({
       deviceId: x.sub ? await deviceIdOf(x.sub) : null, sub: x.sub || null,

package/src/invite.js

@@ -392,16 +392,16 @@ export function parseInvite (text) {
   // el original.
   const undoUrl = (s) => { try { return decodeURIComponent(s) } catch { return s } }
 
-  const marca = payload[0]
-  const resto = payload.slice(1)
-  if (marca === FMT_SHORT) { const o = shortDecode(resto); if (o) return o }
-  if (marca === FMT_COMPACT) { const o = compactDecode(resto); if (o) return o }
-  if (marca === FMT_JSON) { const o = parse(undoUrl(resto)) || parse(resto); if (o) return o }
-  if (marca === FMT_B64) { const s = b64urlDecodeStr(resto); const o = s && parse(s); if (o) return o }
+  const tag = payload[0]
+  const rest = payload.slice(1)
+  if (tag === FMT_SHORT) { const o = shortDecode(rest); if (o) return o }
+  if (tag === FMT_COMPACT) { const o = compactDecode(rest); if (o) return o }
+  if (tag === FMT_JSON) { const o = parse(undoUrl(rest)) || parse(rest); if (o) return o }
+  if (tag === FMT_B64) { const s = b64urlDecodeStr(rest); const o = s && parse(s); if (o) return o }
 
   // --- sin marca: formatos anteriores a la marca de formato (compatibilidad) ---
-  const crudo = undoUrl(payload)
-  if (crudo.trimStart().startsWith('{')) return parse(crudo)
+  const raw = undoUrl(payload)
+  if (raw.trimStart().startsWith('{')) return parse(raw)
   const s = b64urlDecodeStr(payload)
   return s ? parse(s) : null
 }

package/src/protocol.js

@@ -33,6 +33,11 @@ export const MSG = Object.freeze({
   ACTA_SEALED: 'vault.acta.sealed',           // dispositivo → vault: { acta, code }
   ACTA_ADOPTED: 'vault.acta.adopted',         // vault → dispositivo: { acta }
   REVOKED: 'vault.revoked',                   // vault → dispositivo: { body:{op,sub,nonce,iat,exp}, signature }
+  // «¿sigo siendo de esta casa?» — la ÚNICA pregunta que se puede hacer SIN certificado:
+  // va firmada con la llave del propio aparato, que es lo que el acta nombra. Existe para
+  // el aparato que perdió su papel: sin ella no tiene forma de enterarse de que lo echaron.
+  CHECK: 'vault.check',                       // dispositivo → vault: { data:{op:'check',publickey,ts}, signature }
+  CHECKED: 'vault.checked',                   // vault → dispositivo: { in:boolean } — y si no, el REVOKED firmado
   SIGN: 'vault.sign',                         // dispositivo → vault: { data, signature, cert }
   SIGNED: 'vault.signed',                     // vault → dispositivo: { signature, publickey, device }
   GET: 'vault.get',                           // dispositivo → vault: { data, signature, cert }
@@ -93,3 +98,10 @@ export const SCOPE = Object.freeze({
 export const SECRETS_SCOPE_PREFIX = 'vault:secrets:'
 export const secretsScope = (ns) => SECRETS_SCOPE_PREFIX + ns
 export const isValidSecretsNs = (ns) => typeof ns === 'string' && /^[a-z0-9-]{1,32}$/.test(ns)
+
+/**
+ * Nombre de una variable de entorno: `MAYUSCULAS_CON_GUION_BAJO`, hasta 64. Vive aquí
+ * —y no en el cajón que la guarda— porque la comprueban también la TUI, la consola
+ * remota y el lector de `.env`, y tres copias de una regla son tres reglas.
+ */
+export const isValidVarKey = (key) => typeof key === 'string' && /^[A-Z0-9_]{1,64}$/.test(key)

package/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/src/types.d.ts

@@ -0,0 +1,5 @@
+interface Element { [key: string]: any; }
+interface EventTarget { [key: string]: any; }
+interface HTMLElement { [key: string]: any; }
+interface Event { [key: string]: any; }
+interface Window { [key: string]: any; }