@dotrino/vault 0.81.0 → 0.82.0

package/README.md

@@ -282,6 +282,27 @@ await reportUpdated({ product: '@dotrino/terminal-agent', version: '1.3.0', from
   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.81.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

@@ -707,28 +707,82 @@ export async function askUpdateApproval ({ product, version, from = null, dir, p
  * @param {object} o  `product`, `version`, `from` y la conexión, como en `askUpdateApproval`
  * @returns {Promise<{ ok: true }>}
  */
-export async function reportUpdated ({ product, version, from = null, dir, proxyUrl, masterPubkey, device, cert, timeoutMs = 30000 } = {}) {
+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('reportUpdated: needs product and version')
+  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: 'update-done', product, version, ...(typeof from === 'string' && from ? { from } : {}), publickey: device.publickey, ts: Date.now() }
+    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 === 'update-done' && p.body.product === product && p.body.version === version), timeoutMs)
+    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('update-done: the vault did not answer'), { code: 'vault-no-reply' })
+      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 update-done reply')
+    if (res.body.ok !== true) throw new Error(`malformed ${op} reply`)
     return { ok: true }
   } finally { client.close() }
 }