@dotrino/vault 0.80.0 → 0.82.0

package/README.md

@@ -254,6 +254,55 @@ firmada por la llave del servicio + cert, respuesta **sellada** (ECDH efímero +
 el proxy no ve los valores) y **firmada por la maestra**, verificada contra la `iss`
 pineada en el enrolamiento.
 
+### Actualizarse: preguntar y avisar (`@dotrino/vault/service`)
+
+Un aparato enrolado se actualiza solo (CONVENCIONES §15). Si tiene encendido **su propio**
+interruptor de «pedir aprobación», le pregunta a su bóveda antes de instalar; si tiene
+encendido el de avisos, se lo cuenta después. Son interruptores de cada pieza, independientes
+del de la bóveda (`dotrino-vault update --approval`, que vale solo para ella).
+
+```js
+import { askUpdateApproval, reportUpdated } from '@dotrino/vault/service'
+
+// Antes de instalar. Con `dir` (identidad de enrollService) o con
+// { proxyUrl, masterPubkey, device, cert }, como el resto de helpers.
+const r = await askUpdateApproval({ product: '@dotrino/terminal-agent', version: '1.3.0', from: '1.2.9', dir })
+// → { ok: true,  asked: false }   nadie aprueba en la cuenta: adelante
+// → { ok: true,  asked: true }    alguien lo aprobó
+// → { ok: false, asked: true }    lo denegaron, o pasó un día sin respuesta
+if (r.ok) { /* instalar */ }
+
+// Después de instalar: la bóveda avisa a quien aprueba, y dice qué aparato fue.
+await reportUpdated({ product: '@dotrino/terminal-agent', version: '1.3.0', from: '1.2.9', dir })  // → { ok: true }
+```
+
+- El pedido dura **un día**. Mientras vive, volver a preguntar por lo mismo no vuelve a
+  timbrar. No repetir la pregunta por una versión ya denegada es cosa de quien llama.
+- `askUpdateApproval` **lanza** si la bóveda no contesta (`code: 'vault-no-reply'`) o si quedó
+  pendiente y el resultado no llegó (`code: 'unanswered'`). Que nadie conteste nunca es un sí.
+- `reportUpdated` lanza con `code: 'vault-no-reply'` si la bóveda no contesta.
+
+**La receta completa**, para un agente que usa `watchSelfUpdateNpm` de `@dotrino/update/npm`:
+`vaultUpdateHooks` devuelve los tres ganchos ya armados (preguntar, avisar que se actualizó,
+avisar que necesita permisos de administrador).
+
+```js
+import { vaultUpdateHooks } from '@dotrino/vault/service'
+watchSelfUpdateNpm({ name: '@dotrino/terminal-agent', /* … */ ...vaultUpdateHooks({ product: '@dotrino/terminal-agent', dir, log }) })
+```
+
+**Si el servicio no puede instalarse solo** porque necesita permisos de administrador (está
+instalado para todo el sistema y no como usuario), no instala ni pregunta: avisa.
+
+```js
+import { reportUpdateNeedsRoot } from '@dotrino/vault/service'
+await reportUpdateNeedsRoot({ product: '@dotrino/terminal-agent', version: '1.3.0', from: '1.2.9', dir })  // → { ok: true }
+```
+
+La bóveda se lo cuenta a quien aprueba («tiene una actualización pendiente: instálala a mano
+en esa máquina»). Mismos errores que `reportUpdated`; avisar una vez por versión es cosa de
+quien llama. Lo preferible es instalar los servicios como usuario, que no necesita nada de esto.
+
 ## Modelo de aprobación (seguro por diseño)
 
 - El **dispositivo** que se enrola genera un **código aleatorio** (`makePairingCode`) y

package/package.json

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

package/src/service.js

@@ -620,6 +620,173 @@ export async function fetchDigest ({ dir, ns, proxyUrl, masterPubkey, device, ce
   } finally { client.close() }
 }
 
+/** Cuánto espera un aparato a que alguien apruebe su actualización (el pedido vive un día). */
+export const UPDATE_APPROVAL_TIMEOUT_MS = 24 * 60 * 60 * 1000 + 10 * 1000
+
+/**
+ * ¿PUEDO ACTUALIZARME? Lo pregunta un aparato a su bóveda ANTES de instalar una versión
+ * nueva, y SOLO si tiene encendido su propio interruptor de «pedir aprobación» (CONVENCIONES
+ * §15, dueño 2026-10-08: todo se actualiza solo; pedir aprobación es un ajuste de cada pieza,
+ * independiente del de la bóveda). Quien no lo tiene encendido no llama a esto.
+ *
+ *   · nadie aprueba en la cuenta → `{ ok: true, asked: false }`, ya.
+ *   · hay aprobadores → la bóveda contesta «pendiente», timbra a quien aprueba y el resultado
+ *     llega por esta misma conexión cuando alguien decide: `{ ok, asked: true }`. El pedido
+ *     dura un día; vencido es no.
+ *
+ * LANZA si la bóveda no contesta (`code: 'vault-no-reply'`) o si quedó «pendiente» y el
+ * resultado no llegó (`code: 'unanswered'`): quien llama decide qué hacer. Que nadie conteste
+ * NUNCA es un sí. Preguntar otra vez por lo mismo mientras el pedido vive no vuelve a timbrar;
+ * no repetir la pregunta por la misma versión es cosa de quien llama.
+ *
+ * @param {object} o
+ * @param {string} o.product  nombre npm de lo que se actualiza, p. ej. `@dotrino/terminal-agent`
+ * @param {string} o.version  la versión que se quiere instalar
+ * @param {string} [o.from]   la que corre ahora
+ * @param {string} [o.dir]    identidad guardada por `enrollService`; o, en su lugar, la
+ *   identidad por parámetros (`proxyUrl`, `masterPubkey`, `device`, `cert`), como en los demás.
+ * @param {(p: { id: string, exp: number }) => void} [o.onPending]
+ * @returns {Promise<{ ok: boolean, asked: boolean }>}
+ */
+export async function askUpdateApproval ({ product, version, from = null, dir, proxyUrl, masterPubkey, device, cert, timeoutMs = 30000, approvalTimeoutMs = UPDATE_APPROVAL_TIMEOUT_MS, onPending } = {}) {
+  const saved = dir ? readServiceIdentity(dir) : null
+  proxyUrl = proxyUrl || saved?.proxy
+  masterPubkey = masterPubkey || saved?.iss
+  device = device || saved?.device
+  cert = cert || saved?.cert
+  if (typeof product !== 'string' || !product || typeof version !== 'string' || !version) throw new Error('askUpdateApproval: needs product and version')
+  if (!proxyUrl || !masterPubkey || !device || !cert) throw new Error('service not enrolled')
+  const client = await freshClient(proxyUrl, 20000, masterPubkey)
+  try {
+    await identifyAsService(client, device)
+    const data = { op: 'update-ask', product, version, ...(typeof from === 'string' && from ? { from } : {}), publickey: device.publickey, ts: Date.now() }
+    const { signature } = await signWithDevice({ privateJwk: device.privateJwk, data })
+    const mine = (p) => p.type === MSG.ERROR || (p.type === MSG.SECRETS_RESULT && p.body?.op === 'update-ask' && p.body.product === product && p.body.version === version)
+    const check = async (res) => {
+      if (res.type === MSG.ERROR) throw vaultError(res)
+      await verifyResponder({ body: res.body, seal: res.seal, acta: res.acta, masterPubkey, knownSeq: saved?.actaSeq ?? null })
+      if (typeof res.body.ts !== 'number' || Math.abs(Date.now() - res.body.ts) > FRESH_WINDOW_MS) throw new Error('stale update-ask reply')
+      return res.body
+    }
+    // UNA COLA, no dos esperas seguidas: el resultado puede llegar mientras todavía se
+    // comprueba el «pendiente», y una escucha puesta después lo perdería (y se esperaría un
+    // día por algo que ya se contestó).
+    const queue = []
+    let wake = null
+    const off = client.on('message', (_from, p) => { if (p && typeof p === 'object' && mine(p)) { queue.push(p); wake?.() } })
+    const next = (ms, code, message) => new Promise((resolve, reject) => {
+      if (queue.length) return resolve(queue.shift())
+      const t = setTimeout(() => { wake = null; reject(Object.assign(new Error(message), { code })) }, ms)
+      wake = () => { clearTimeout(t); wake = null; resolve(queue.shift()) }
+    })
+    let body
+    try {
+      client.sendByPubkey(masterPubkey, { type: MSG.SECRETS, data, signature, cert })
+      body = await check(await next(timeoutMs, 'vault-no-reply', 'update-ask: the vault did not answer'))
+      if (body.pending === true) {
+        try { onPending?.({ id: body.id, exp: body.exp }) } catch (_) {}
+        const until = typeof body.exp === 'number' ? Math.max(5000, body.exp - Date.now() + 5000) : approvalTimeoutMs
+        do {
+          body = await check(await next(Math.min(until, approvalTimeoutMs), 'unanswered', 'update-ask: nobody answered the request in time'))
+        } while (body.pending === true)
+      }
+    } finally { off() }
+    if (typeof body.ok !== 'boolean') throw new Error('malformed update-ask reply')
+    return { ok: body.ok, asked: body.asked === true }
+  } finally { client.close() }
+}
+
+/**
+ * ME ACTUALICÉ: un aparato se lo dice a su bóveda DESPUÉS de instalar, y ella se lo cuenta a
+ * quien aprueba en la cuenta (un aviso, y queda 24 h en la lista de avisos). Se llama solo
+ * si el aparato tiene encendido su interruptor de avisos de actualización.
+ *
+ * Quién es el aparato lo pone la bóveda desde el acta, no lo que él diga.
+ * LANZA si la bóveda no contesta (`code: 'vault-no-reply'`) o no pudo avisar.
+ *
+ * @param {object} o  `product`, `version`, `from` y la conexión, como en `askUpdateApproval`
+ * @returns {Promise<{ ok: true }>}
+ */
+export function reportUpdated (o = {}) { return reportToVault('update-done', o) }
+
+/**
+ * HAY VERSIÓN NUEVA Y NO PUEDO INSTALARLA SOLO: necesita permisos de administrador (el
+ * servicio está instalado para todo el sistema, no como usuario). El aparato se lo dice a su
+ * bóveda y ella avisa a quien aprueba, que es quien puede ir a esa máquina e instalarla a
+ * mano (dueño, 2026-10-08). No instala nada ni pide permiso: solo avisa.
+ *
+ * Mismos parámetros y errores que `reportUpdated`. Avisar una sola vez por versión es cosa
+ * de quien llama.
+ * @returns {Promise<{ ok: true }>}
+ */
+export function reportUpdateNeedsRoot (o = {}) { return reportToVault('update-needs-root', o) }
+
+/**
+ * LOS TRES GANCHOS DE ACTUALIZACIÓN, YA ARMADOS para pasárselos a `watchSelfUpdateNpm` de
+ * `@dotrino/update/npm`: una pieza, para que cada agente no lo escriba por su cuenta. No
+ * depende de ese paquete: solo devuelve funciones con la forma que él espera.
+ *
+ *   · `mayUpdate({ version, from })` → pregunta a la bóveda y devuelve si se puede. Si la
+ *     bóveda NO CONTESTA, lanza: para quien llama eso es «no pude preguntar» y se reintenta.
+ *     Si el pedido VENCE sin respuesta devuelve `false`: vencido es no, y no se repite.
+ *   · `onUpdated({ version, from })` → le dice a la bóveda que se actualizó. Deja pasar el
+ *     error, para que quien llama conserve su marcador y lo reintente.
+ *   · `onNeedsRoot({ version, from })` → le dice que hay versión nueva y necesita permisos de
+ *     administrador. Igual.
+ *
+ * @param {object} o
+ * @param {string} o.product  nombre npm de la pieza
+ * @param {(m: string) => void} [o.log]
+ *   …y la conexión como en los demás: `dir`, o `proxyUrl` + `masterPubkey` + `device` + `cert`.
+ * @returns {{ mayUpdate: (u: { version: string, from?: string }) => Promise<boolean>,
+ *   onUpdated: (u: { version: string, from?: string }) => Promise<void>,
+ *   onNeedsRoot: (u: { version: string, from?: string }) => Promise<void> }}
+ */
+export function vaultUpdateHooks ({ product, log = () => {}, dir, proxyUrl, masterPubkey, device, cert, _ask = askUpdateApproval, _done = reportUpdated, _root = reportUpdateNeedsRoot } = {}) {
+  if (typeof product !== 'string' || !product) throw new Error('vaultUpdateHooks: needs product')
+  const conn = { dir, proxyUrl, masterPubkey, device, cert }
+  return {
+    async mayUpdate ({ version, from = null } = {}) {
+      let r
+      try { r = await _ask({ ...conn, product, version, from, onPending: () => log(`[update] ${product} ${version}: waiting for approval on your vault`) }) } catch (e) {
+        if (e?.code === 'unanswered') { log(`[update] ${product} ${version}: nobody answered in time, so it is a no`); return false }
+        throw e
+      }
+      log(`[update] ${product} ${version}: ${r.ok ? (r.asked ? 'approved' : 'no approval needed') : 'not approved'}`)
+      return r.ok === true
+    },
+    async onUpdated ({ version, from = null } = {}) { await _done({ ...conn, product, version, from }) },
+    async onNeedsRoot ({ version, from = null } = {}) { await _root({ ...conn, product, version, from }) }
+  }
+}
+
+/** Lo común de los dos avisos: firmar, mandar, y comprobar quién contesta. */
+async function reportToVault (op, { product, version, from = null, dir, proxyUrl, masterPubkey, device, cert, timeoutMs = 30000 } = {}) {
+  const saved = dir ? readServiceIdentity(dir) : null
+  proxyUrl = proxyUrl || saved?.proxy
+  masterPubkey = masterPubkey || saved?.iss
+  device = device || saved?.device
+  cert = cert || saved?.cert
+  if (typeof product !== 'string' || !product || typeof version !== 'string' || !version) throw new Error(`${op}: needs product and version`)
+  if (!proxyUrl || !masterPubkey || !device || !cert) throw new Error('service not enrolled')
+  const client = await freshClient(proxyUrl, 20000, masterPubkey)
+  try {
+    await identifyAsService(client, device)
+    const data = { op, product, version, ...(typeof from === 'string' && from ? { from } : {}), publickey: device.publickey, ts: Date.now() }
+    const { signature } = await signWithDevice({ privateJwk: device.privateJwk, data })
+    const pending = waitForMsg(client, (p) => p.type === MSG.ERROR || (p.type === MSG.SECRETS_RESULT && p.body?.op === op && p.body.product === product && p.body.version === version), timeoutMs)
+    client.sendByPubkey(masterPubkey, { type: MSG.SECRETS, data, signature, cert })
+    const res = await pending.catch((e) => {
+      if (/timeout/.test(e.message)) throw Object.assign(new Error(`${op}: the vault did not answer`), { code: 'vault-no-reply' })
+      throw e
+    })
+    if (res.type === MSG.ERROR) throw vaultError(res)
+    await verifyResponder({ body: res.body, seal: res.seal, acta: res.acta, masterPubkey, knownSeq: saved?.actaSeq ?? null })
+    if (res.body.ok !== true) throw new Error(`malformed ${op} reply`)
+    return { ok: true }
+  } finally { client.close() }
+}
+
 /**
  * Pide los secretos del ns al vault (una petición puntual; lanza si falla).
  * Usa la identidad persistida por `enrollService` salvo que se pase explícita.