@dotrino/vaultd 0.11.0 → 0.13.0

package/lib/src/service.js

@@ -26,6 +26,8 @@ import {
 } from '@dotrino/identity/capabilities'
 import { MSG, secretsScope, isValidSecretsNs } from './protocol.js'
 import { makeEphemeralKey, openSealed } from './sealed.js'
+import { parseInvite } from './invite.js'
+import { atRestFor } from './atrest.js'
 
 const IDENTITY_FILE = 'service-identity.json'
 const FRESH_WINDOW_MS = 5 * 60 * 1000
@@ -74,9 +76,55 @@ async function verificarHola (p, sn) {
   if (!(await verifyDeviceSig({ publickey: b.iss, data: b, signature: p.signature }))) {
     throw new Error('la respuesta de la bóveda no está bien firmada')
   }
+  // 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)
   return b
 }
 
+/**
+ * UN AGENTE NUNCA TRANSFIERE SU IDENTIDAD: el vault propone, el agente acepta.
+ *
+ * El emparejamiento tiene dos modos y los declara la bóveda en la invitación:
+ * `join` (el que se enrola entra a la cuenta de la bóveda) y `adopt` (la bóveda
+ * se queda con la cuenta que trae el aparato). El segundo existe para APARATOS,
+ * que llegan con una cuenta propia y una historia que conservar.
+ *
+ * Un agente no tiene nada de eso: es un servicio, su identidad se la da el vault
+ * y no hay caso en que quiera empujar la suya hacia arriba. Así que este camino
+ * no se negocia, se rechaza — y se rechaza ACÁ, cuando el humano pega la
+ * 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
+  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>`).'
+  )
+}
+
+/**
+ * Canjea la cita del QR y devuelve la instancia a la que apunta.
+ *
+ * Una cita se quema al usarse y caduca en minutos, así que un error acá casi
+ * 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')
+  if (typeof client.redeemPairingCode !== 'function') {
+    throw new Error('el proxio no soporta códigos de emparejamiento (actualizá @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.`)
+  }
+  return r.instance
+}
+
 async function freshClient (proxyUrl, connectTimeoutMs = 20000) {
   installNodeGlobals()
   const { WebSocketProxyClient } = await import('@dotrino/proxy-client')
@@ -122,41 +170,99 @@ function waitForMsg (client, predicate, timeoutMs = 30000) {
 
 const identityFileOf = (dir) => path.join(dir, IDENTITY_FILE)
 
-/** Lee la identidad persistida del servicio ({device, cert, iss, proxy, ns}) o null. */
+/**
+ * Lee la identidad persistida del servicio ({device, cert, iss, proxy, ns}) o null.
+ *
+ * CIFRADA EN REPOSO (`atrest.js`) con una clave ligada a ESTA máquina: el archivo
+ * lleva la llave privada del dispositivo, así que copiarlo a otro equipo no sirve.
+ * Un archivo de una versión anterior (en claro) se lee igual y queda cifrado en la
+ * primera escritura.
+ */
 export function readServiceIdentity (dir) {
-  try { return JSON.parse(fs.readFileSync(identityFileOf(dir), 'utf8')) } catch (_) { return null }
+  try {
+    const text = fs.readFileSync(identityFileOf(dir), 'utf8')
+    return JSON.parse(atRestFor(dir).decrypt(text))
+  } catch (_) { return null }
 }
 
 function writeServiceIdentity (dir, obj) {
   fs.mkdirSync(dir, { recursive: true, mode: 0o700 })
   const f = identityFileOf(dir)
-  fs.writeFileSync(f, JSON.stringify(obj, null, 2), { mode: 0o600 })
+  const blob = atRestFor(dir).encrypt(JSON.stringify(obj, null, 2))
+  fs.writeFileSync(f, blob, { mode: 0o600 })
 }
 
 /**
- * Enrola ESTE servicio contra el vault (una sola vez; persiste la identidad).
- * En el vault se corre antes `dotrino-vault pair --service <ns>`; el QR/payload
- * de ese comando es el `qr` de aquí. Muestra un código por `onCode` (o stdout):
- * el dueño lo tipea en el vault (`dotrino-vault approve <código>`).
+ * Enrola ESTE servicio contra el vault y persiste su identidad.
+ *
+ * UN AGENTE TIENE UNA SOLA IDENTIDAD, Y SE LA DA EL VAULT. A diferencia de un
+ * aparato —que puede llevar varios perfiles y hasta meter su cuenta al vault por
+ * adopción—, un agente no acumula identidades ni transfiere la suya: se enrola,
+ * el vault le cede una (llave propia + cert de la maestra) y **la anterior, si
+ * había, se descarta**. No hay fusión ni convivencia, y no hace falta: un agente
+ * es un servicio, no una persona; no tiene por qué "ser varios".
+ *
+ * Enrolar dos veces, entonces, no es un error a bloquear sino un REEMPLAZO — que
+ * es además la forma de rotar la identidad de un agente comprometido. Lo que sí
+ * hace falta es que se vea: se avisa por `onReplace` qué identidad se tira.
+ *
+ * En el vault se corre antes `dotrino-vault pair --service <ns>`; la invitación
+ * que imprime ese comando es el `qr` de aquí (en cualquiera de sus formas).
+ * Muestra un código por `onCode`: el dueño lo tipea en el vault
+ * (`dotrino-vault approve <código>`).
  *
  * @param {Object} opts
- * @param {{v:number, iss:string, proxy:string, token:string, sn:string}|string} opts.qr  QR v2 (objeto o JSON string).
+ * @param {object|string} opts.qr  La invitación: objeto, URL del QR o código pegado.
  * @param {string} opts.ns     Namespace de secretos del servicio (el mismo del pair).
  * @param {string} opts.dir    Dónde persistir `service-identity.json`.
  * @param {string} [opts.label]
  * @param {(c:{deviceId:string, code:string})=>void} [opts.onCode]
- * @returns {Promise<{device, cert, iss:string}>}
+ * @param {(prev:{ns:string, enrolledAt:number, deviceId:string})=>void} [opts.onReplace]
+ *   Se llama ANTES de enrolar si ya había una identidad: la que va a descartarse.
+ * @returns {Promise<{device, cert, iss:string, replaced:object|null}>}
  */
-export async function enrollService ({ qr, ns, dir, label, onCode, approveTimeoutMs = 180000 } = {}) {
-  if (typeof qr === 'string') { try { qr = JSON.parse(qr) } catch (_) { throw new Error('qr inválido: no es JSON') } }
+export async function enrollService ({ qr, ns, dir, label, onCode, onReplace, approveTimeoutMs = 180000 } = {}) {
+  // `parseInvite` y NO `JSON.parse`: el vault no imprime JSON desde hace rato.
+  // `dotrino-vault pair --service` emite la URL del QR y el código compacto
+  // (`c…`/`t…`, ver invite.js), así que un `JSON.parse` fallaba SIEMPRE con
+  // «qr inválido: no es JSON» y el enrolamiento de un servicio era imposible por
+  // este camino. Lo tapaba que el único servicio enrolado del ecosistema lo hizo
+  // cuando el formato todavía era JSON. `parseInvite` acepta todas las formas,
+  // 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>`)')
+    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
 
+  // 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)
+  let replaced = null
+  if (anterior?.device?.publickey) {
+    replaced = {
+      ns: anterior.ns,
+      enrolledAt: anterior.enrolledAt,
+      deviceId: (await pubkeyId(anterior.device.publickey)).slice(0, 8).toUpperCase()
+    }
+    try { onReplace?.(replaced) } catch (_) {}
+  }
+
   const client = await freshClient(qr.proxy || 'wss://proxy.dotrino.com')
   // QR CORTO: se le pregunta a la bóveda quién es, punto a punto, presentando el `sn`.
   if (!qr.iss) {
+    // `qr.conn` es una CITA (código de 6 caracteres, un solo uso): hay que
+    // 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 off = client.on('message', (_f, p) => {
         if (p?.type === MSG.HELLO_OK) { fin(); verificarHola(p, qr.sn).then(resolve, reject) }
@@ -164,7 +270,7 @@ export async function enrollService ({ qr, ns, dir, label, onCode, approveTimeou
       })
       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(qr.conn, { type: MSG.HELLO, sn: qr.sn }) } catch (e) { fin(); reject(e) }
+      try { client.send(destino, { type: MSG.HELLO, sn: qr.sn }) } catch (e) { fin(); reject(e) }
     })
     qr = { ...qr, iss: hola.iss, proxy: hola.proxy || qr.proxy }
   }
@@ -177,7 +283,11 @@ export async function enrollService ({ qr, ns, dir, label, onCode, approveTimeou
     // El COMPROMISO del código (nunca el código): la bóveda lo recompone con lo que
     // tipeas y solo entonces firma el cert → aprobar exige haber leído esta pantalla.
     const commit = await commitCode({ code, dpub: device.publickey, sn: qr.sn })
-    const data = { op: 'enroll', dpub: device.publickey, token: qr.token || qr.sn, sn: qr.sn, commit, label, ts: Date.now() }
+    // `intent: 'join'` EXPLÍCITO. La bóveda lo compara con el modo que abrió y,
+    // si falta, asume `join` — pero un agente no debe apoyarse en un default
+    // para algo que decide de quién es la cuenta. Yendo dentro de `data`, viaja
+    // firmado: nadie en el medio puede convertirlo en una adopción.
+    const data = { op: 'enroll', intent: 'join', dpub: device.publickey, token: qr.token || qr.sn, sn: qr.sn, commit, label, ts: Date.now() }
     const { signature } = await signWithDevice({ privateJwk: device.privateJwk, data })
 
     const enrolled = new Promise((resolve, reject) => {
@@ -201,8 +311,10 @@ export async function enrollService ({ qr, ns, dir, label, onCode, approveTimeou
     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')
 
+    // Reemplazo, no acumulación: el archivo se sobrescribe entero y la identidad
+    // anterior deja de existir en este agente.
     writeServiceIdentity(dir, { v: 1, ns, iss: qr.iss, proxy: qr.proxy, device, cert: res.cert, enrolledAt: Date.now() })
-    return { device, cert: res.cert, iss: qr.iss }
+    return { device, cert: res.cert, iss: qr.iss, replaced }
   } finally { client.close() }
 }
 
@@ -265,6 +377,143 @@ export async function fetchSecrets ({ dir, ns, proxyUrl, masterPubkey, device, c
   } finally { client.close() }
 }
 
+/**
+ * Escucha los avisos de cambio de configuración de la bóveda.
+ *
+ * A diferencia de `fetchSecrets` —que abre, pide y cierra—, esto mantiene la
+ * conexión ABIERTA e identificada con la llave del servicio: es la dirección a la
+ * que la bóveda le habla. Por eso un agente que quiera enterarse de una rotación
+ * deja de ser un cliente de paso y pasa a ser uno permanente.
+ *
+ * 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`).
+ *
+ * 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.
+ * · **Frescura y anti-replay**: `ts` dentro de la ventana y estrictamente mayor
+ *   que el último obedecido. Un aviso viejo reproducido no vuelve a disparar.
+ * · **Gracia de arranque y piso entre avisos**: no se obedece recién arrancado ni
+ *   dos veces seguidas. Si la configuración nueva rompe el arranque, sin esto el
+ *   servicio entra en un ciclo de reinicios.
+ * · **Jitter**: diez agentes del mismo ns no pueden salir todos en el mismo
+ *   segundo.
+ *
+ * @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:{nonce:string})=>void} [opts.onRevoked]  Cert revocado: apagar YA.
+ * @param {number} [opts.graceMs=30000]      No obedecer avisos durante los primeros N ms.
+ * @param {number} [opts.minIntervalMs=60000] Mínimo entre dos avisos obedecidos.
+ * @param {number} [opts.jitterMs=5000]      Espera aleatoria antes de avisar.
+ * @param {(m:string)=>void} [opts.log]
+ * @returns {Promise<{stop:()=>void}>}
+ */
+export async function watchSecretsChanges ({
+  dir, ns, onChange, onRevoked, graceMs = 30000, minIntervalMs = 60000, jitterMs = 5000, 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')
+  }
+  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
+  let client = null
+  let reintento = null
+
+  /**
+   * REVOCACIÓN = interruptor de emergencia. Hasta ahora revocar un cert no le
+   * quitaba nada a un servicio YA CORRIENDO: seguía operando con los secretos en
+   * 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.
+   *
+   * 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 body = payload.body
+    if (!body || body.op !== 'revoke') return
+    // Que sea MI revocación y no la de otro dispositivo del mismo dueño.
+    if (body.sub !== saved.device.publickey) return
+    if (saved.cert?.nonce && body.nonce !== saved.cert.nonce) return
+    if (!(await verifyDeviceSig({ publickey: master, data: body, signature: payload.signature }))) {
+      return log('[vault] revocation notice BADLY SIGNED: ignored')
+    }
+    log('[vault] ⚠ the vault REVOKED this agent cert: shutting down')
+    try { onRevoked?.({ nonce: body.nonce }) } catch (e) { log('[vault] ' + e.message) }
+  }
+
+  const atender = async (payload) => {
+    if (payload?.type === MSG.REVOKED) return atenderRevocacion(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')
+    }
+    if (body.ts <= ultimoTs) return log('[vault] aviso de cambio repetido: ignorado')
+    // 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
+    // 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
+    // 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
+    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) {
+      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')
+    }
+    ultimoObedecido = ahora
+
+    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 conectar = async () => {
+    if (parado) return
+    try {
+      client = await freshClient(saved.proxy)
+      await identifyAsService(client, saved.device)
+      client.on('message', (_from, p) => { atender(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) })
+      log('[vault] listening for config changes')
+    } catch (e) {
+      if (!parado) reintento = setTimeout(conectar, 5000)
+    }
+  }
+  await conectar()
+
+  return {
+    stop () {
+      parado = true
+      clearTimeout(reintento)
+      try { client?.close() } catch (_) {}
+    }
+  }
+}
+
 /**
  * Bucle de arranque de un servicio: pide los secretos y, si el vault no está
  * disponible, REINTENTA para siempre (con backoff hasta `maxRetryMs`). El

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotrino/vaultd",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "type": "module",
   "description": "Certificador personal de Dotrino: daemon headless que custodia la clave maestra y delega capacidades a tus dispositivos por el proxy. Tu CA propia.",
   "bin": {
@@ -19,8 +19,8 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@dotrino/identity": "^0.36.0",
-    "@dotrino/proxy-client": "0.8.0",
+    "@dotrino/identity": "^0.38.0",
+    "@dotrino/proxy-client": "^0.10.0",
     "ws": "^8.18.0"
   },
   "license": "MIT",
@@ -38,5 +38,8 @@
     "README.md",
     "vendor",
     "lib/src"
-  ]
+  ],
+  "devDependencies": {
+    "@dotrino/remote-agent": "^0.3.0"
+  }
 }

package/src/client.js

@@ -36,7 +36,7 @@ function waitFor (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 response')) }, timeoutMs)
     const cleanup = () => { off(); clearTimeout(t) }
   })
 }
@@ -51,7 +51,7 @@ function waitFor (client, predicate, timeoutMs = 30000) {
  * @returns {Promise<{ device, cert, iss:string }>}  GUARDAR `device` (incluye la privada) + `cert`. `iss` = qr.iss verificado.
  */
 export async function enroll ({ qr, label = '', dir, onChallenge, approveTimeoutMs = 180000 } = {}) {
-  if (!qr?.iss || !qr?.proxy || !qr?.token || !qr?.sn) throw new Error('qr inválido (v2): faltan iss/proxy/token/sn')
+  if (!qr?.iss || !qr?.proxy || !qr?.token || !qr?.sn) throw new Error('invalid qr (v2): missing iss/proxy/token/sn')
   const client = await freshClient({ proxyUrl: qr.proxy, dir })
   try {
     const device = await makeDeviceKey({ label })
@@ -77,7 +77,7 @@ export async function enroll ({ qr, label = '', dir, onChallenge, approveTimeout
           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 at the vault')) }, approveTimeoutMs)
       const cleanup = () => { off(); clearTimeout(t) }
     })
     client.sendByPubkey(qr.iss, { type: MSG.ENROLL, data, signature })
@@ -85,9 +85,9 @@ export async function enroll ({ qr, label = '', dir, onChallenge, approveTimeout
 
     // VALIDACIÓN ESTRICTA antes de persistir (cierra inyección de cert / sustitución de maestra).
     const v = await verifyDelegation({ cert: res.cert, expectedSub: device.publickey })
-    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 que viste (posible proxy malicioso)')
-    if (res.cert.sub !== device.publickey) throw new Error('cert emitido para otro dispositivo')
+    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 you saw (possible malicious proxy)')
+    if (res.cert.sub !== device.publickey) throw new Error('cert issued for a different device')
     // OJO: devolvemos qr.iss (la maestra que el usuario VIO), NO res.iss.
     return { device, cert: res.cert, iss: qr.iss }
   } finally { client.close() }
@@ -132,6 +132,32 @@ export async function requestGet ({ masterPubkey, proxyUrl, device, cert, id = '
   } finally { client.close() }
 }
 
+/**
+ * RENUEVA el cert de este dispositivo (sigue siendo el mismo: no hay QR ni aprobación).
+ *
+ * No es solo estirar la fecha: el scope del cert nuevo lo decide **el acta**, así que
+ * renovar es también como llega a un dispositivo un permiso que el dueño le concedió
+ * después de emparejarlo —y como se le cae uno que le quitaron—. Un cert vencido o
+ * revocado no se renueva: ahí toca volver a emparejar.
+ */
+export async function requestRenew ({ masterPubkey, proxyUrl, device, cert, dir } = {}) {
+  const client = await freshClient({ proxyUrl, dir })
+  try {
+    const data = { op: 'renew', publickey: device.publickey, ts: Date.now() }
+    const { signature } = await signWithDevice({ privateJwk: device.privateJwk, data })
+    const pending = waitFor(client, (p) => p.type === MSG.RENEWED || p.type === MSG.ERROR)
+    client.sendByPubkey(masterPubkey, { type: MSG.RENEW, data, signature, cert })
+    const res = await pending
+    if (res.type === MSG.ERROR) throw new Error(res.error)
+    // Se valida antes de devolverlo, igual que en el enrolamiento: un cert que no está
+    // firmado por la maestra que ya conocemos, o que no es para esta llave, no se guarda.
+    const v = await verifyDelegation({ cert: res.cert, expectedSub: device.publickey })
+    if (!v.ok) throw new Error('invalid cert: ' + v.reason)
+    if (res.cert.iss !== masterPubkey) throw new Error('cert signed by a master other than the pinned one')
+    return { cert: res.cert }
+  } finally { client.close() }
+}
+
 /** Llama un método del store de hilos/aperturas del vault (scope vault:store). */
 export async function requestStore ({ masterPubkey, proxyUrl, device, cert, method, args, dir } = {}) {
   const client = await freshClient({ proxyUrl, dir })
@@ -146,4 +172,36 @@ export async function requestStore ({ masterPubkey, proxyUrl, device, cert, meth
   } finally { client.close() }
 }
 
+/**
+ * CONSOLA REMOTA (scope `vault:admin`, docs/consola-remota.md): administrar el perfil
+ * desde un dispositivo, sin venir al PC. `op`: pending · pair · approve · reject ·
+ * revoke · audit.
+ *
+ * El `nonce` de un solo uso NO es decorativo: `approve` y `revoke` cambian estado, así
+ * que la ventana de frescura de ±5 min no basta para descartar un replay.
+ */
+export async function requestAdmin ({ masterPubkey, proxyUrl, device, cert, op, dir, ...rest } = {}) {
+  const client = await freshClient({ proxyUrl, dir })
+  try {
+    const nonce = [...crypto.getRandomValues(new Uint8Array(16))].map((b) => b.toString(16).padStart(2, '0')).join('')
+    const data = { op, ...rest, publickey: device.publickey, ts: Date.now(), nonce }
+    const { signature } = await signWithDevice({ privateJwk: device.privateJwk, data })
+    const pending = waitFor(client, (p) => p.type === MSG.ADMIN_RESULT || p.type === MSG.ERROR)
+    client.sendByPubkey(masterPubkey, { type: MSG.ADMIN, data, signature, cert })
+    const res = await pending
+    if (res.type === MSG.ERROR) throw new Error(res.error)
+    return res.result
+  } finally { client.close() }
+}
+
+/**
+ * Verifica que un `vault.admin.event` (entró o salió alguien del perfil) viene
+ * FIRMADO por la maestra pineada. Un aviso sin firma no se muestra: si no, cualquiera
+ * podría llenar de alarmas falsas los dispositivos del usuario.
+ */
+export async function verifyAdminEvent ({ body, signature, master }) {
+  if (!body || typeof body.ev !== 'string') return false
+  return verifyDeviceSig({ publickey: master, data: body, signature })
+}
+
 export { identifyAsDevice }

package/src/ctl.js

@@ -264,7 +264,7 @@ async function cmdMembers () {
   if (!acta) { console.error('El daemon no respondió.'); process.exit(1) }
   if (!acta.members?.length) { console.log('Este perfil todavía no tiene acta.'); return }
 
-  const CAP = { sign: 'firma', store: 'guarda', read: 'lee', secrets: 'lee sus claves' }
+  const CAP = { sign: 'firma', store: 'guarda', read: 'lee', secrets: 'lee sus claves', admin: `${B}administra el perfil${Z}` }
   // El nombre del perfil es una pubkey JWK. Recortarla no la hace legible: la deja
   // pareciendo un error (`{"key_ops":["verify"],"e…`). Se muestra su huella corta, la
   // misma que se enseña al emparejar y en la lista de miembros.
@@ -280,7 +280,9 @@ async function cmdMembers () {
     const caps = m.caps.length ? m.caps.map((c) => CAP[c] || c).join(', ') : '(sin permisos)'
     console.log('  %s  %s%s\n      %s', m.id, quien, marcas.length ? '  [' + marcas.join(' · ') + ']' : '', caps)
   }
-  console.log('\n  Cambiar permisos:  dotrino-vault caps <ID> +firma | -firma | +guarda | -guarda | +lee | -lee')
+  console.log('\n  Cambiar permisos:  dotrino-vault caps <ID> +firma | -firma | +guarda | -guarda | +lee | -lee | +administra')
+  console.log('  «Administra» deja conectar y quitar dispositivos desde ese aparato, sin venir aquí.')
+  console.log('  No deja cambiar permisos ni traspasar el mando: eso solo se hace en esta máquina.')
   console.log('  Los servicios solo pueden abrir las claves de su propio nombre; eso no se cambia aquí.\n')
 }
 
@@ -288,10 +290,13 @@ async function cmdMembers () {
 async function cmdCaps (args = []) {
   const [id, ...cambios] = args
   if (!id || !cambios.length) {
-    console.error('uso: dotrino-vault caps <ID> +firma|-firma|+guarda|-guarda|+lee|-lee')
+    console.error('uso: dotrino-vault caps <ID> +firma|-firma|+guarda|-guarda|+lee|-lee|+administra|-administra')
     process.exit(2)
   }
-  const NOMBRE = { firma: 'sign', guarda: 'store', lee: 'read', sign: 'sign', store: 'store', read: 'read' }
+  const NOMBRE = {
+    firma: 'sign', guarda: 'store', lee: 'read', administra: 'admin',
+    sign: 'sign', store: 'store', read: 'read', admin: 'admin'
+  }
   const s = requireDaemon()
   const actaFile = path.join(dataDir(), 'acta.json')
   try { fs.rmSync(actaFile, { force: true }) } catch (_) {}
@@ -580,7 +585,7 @@ function help () {
   reject <deviceId>   rechaza un dispositivo pendiente
   devices             lista dispositivos enrolados / revocados
   members             el acta del perfil: quién es tuyo y qué puede hacer
-  caps <ID> ±permiso  cambia permisos (+firma -guarda …)
+  caps <ID> ±permiso  cambia permisos (+firma -guarda +administra …)
   revoke <nonce>      revoca un dispositivo (le ordena autoborrarse)
   activity [n]        bitácora de seguridad: firmas, renovaciones, enrolados, rechazos
   logs                últimos logs del servicio