@dotrino/vault 0.79.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.79.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/admin.js

@@ -47,6 +47,9 @@ export const ADMIN_OPS = Object.freeze([
   // `pending`, `pair`, `approve` y `reject` NO están, y no es un olvido: agregar aparatos
   // a distancia se quitó (ver la cabecera). Lo que queda es mirar, quitar y configurar.
   'revoke', 'audit',
+  // Los BLOQUEADOS por un aprobador (`src/blocked.js`): verlos y desbloquearlos. Bloquear a
+  // distancia también, por si el administrador llega antes que el teléfono. No toca el acta.
+  'blocked', 'block', 'unblock',
   // 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.
@@ -96,6 +99,8 @@ export const ADMIN_OPS = Object.freeze([
  */
 export const ADMIN_OPS_WHILE_LOCKED = Object.freeze([
   'audit', 'vars', 'var.set', 'var.setMany', 'var.recipients',
+  // Bloquear no sella nada: la lista es de la bóveda, no del acta.
+  'blocked', 'block', 'unblock',
   // Las dos de abrir, obviamente: son las únicas que solo tienen sentido con el candado
   // echado. Que estén aquí NO las deja pasar sin más — siguen exigiendo cert, acta, nonce
   // y frescura como todas, y además la contraseña dentro del sobre.
@@ -147,6 +152,8 @@ export function createAdminDesk ({
   // este módulo es puro a propósito. `null` en una bóveda que no lo soporte: entonces la
   // operación existe y contesta que no, en vez de romper con un TypeError.
   unlockDesk = null,
+  // La lista de bloqueados, inyectada como `vars`: `{ list(), set(pub, on, { by }) }`.
+  blocked = null,
   now = () => Date.now()
 }) {
   const ops = new Set(ADMIN_OPS)
@@ -333,6 +340,14 @@ export function createAdminDesk ({
       // usarlo para quitar dejaba un miembro sin certificados al que la bóveda ya nunca le
       // mandaba el aviso de expulsión (mientras siga en el acta, un papel retirado
       // significa «renueva»). Ese era el dispositivo fantasma.
+      if (data.op === 'blocked' || data.op === 'block' || data.op === 'unblock') {
+        if (!blocked) return { ok: false, error: 'admin: this vault cannot block devices' }
+        if (data.op === 'blocked') return { ok: true, result: { items: blocked.list() } }
+        if (typeof data.sub !== 'string' || !data.sub) return { ok: false, error: `admin: ${data.op} needs the device key (sub)` }
+        const r = await blocked.set(data.sub, data.op === 'block', { by })
+        audit(`admin.${data.op}`, { by, device: await deviceIdOf(data.sub).catch(() => null) })
+        return { ok: true, result: { ok: true, was: r } }
+      }
       if (data.op === 'revoke') {
         if (data.sub) {
           const deviceId = await deviceIdOf(String(data.sub)).catch(() => null)

package/src/protocol.js

@@ -103,6 +103,13 @@ export const MSG = Object.freeze({
   // una forma de echar a alguien de su cuenta.
   LOGIN_CLOSE: 'vault.login.close',           // aparato → vault: { data:{op,user,sid,publickey,ts}, signature }
   LOGIN_CLOSED: 'vault.login.closed',         // vault → aparato: { ok }
+  // INCIDENTE: un agente de la cuenta (la terminal) avisa de que OTRO aparato de la cuenta
+  // se equivocó de clave tres veces seguidas. La bóveda lo apunta como un pedido más
+  // (`kind: 'incident'`), timbra a quien aprueba, y el aprobador bloquea o ignora. Bloquear
+  // no toca el acta: es una lista de la bóveda (`blocked.json`) que viaja a los agentes con
+  // `vault.devices.result` (`blocked`) y se deshace con `dotrino-vault unblock <ID>`.
+  INCIDENT: 'vault.incident',                 // agente → vault: { data:{op:'incident',kind,about,tries,publickey,ts}, signature, cert }
+  INCIDENT_RESULT: 'vault.incident.result',   // vault → agente: { id, approvers, blocked }
   ERROR: 'vault.error'                        // vault → dispositivo: { error }
 })
 

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.