@dotrino/vault 0.80.0 → 0.81.0

package/README.md

@@ -254,6 +254,34 @@ 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.
+
 ## 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.81.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,119 @@ 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 async function reportUpdated ({ 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 (!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 { 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)
+    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' })
+      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')
+    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.