@dotrino/remote-agent 0.15.0 → 0.16.0

package/README.md

@@ -63,6 +63,10 @@ const ra = await startRemoteAgent({
   onRevoked () { console.log('me revocaron') }
 })
 // ra.machine, ra.machineId, ra.master, ra.close()
+// ra.reportIncident({ kind, about, tries }) → { id, approvers, blocked } (0.16.0): avisa a la
+//   bóveda de que OTRO aparato de la cuenta hizo algo (la terminal: tres claves mal seguidas).
+//   Quien aprueba lo ve y bloquea o ignora; bloqueado, no saluda a ningún agente (`code: 'blocked'`)
+//   y la lista viaja con la de revocados y queda en el enlace (`link.blocked`). ra.isBlocked(pub).
 // ra.client → el WebSocketProxyClient ya conectado e identificado bajo esta
 //   máquina. Si tu agente necesita algo más del transporte (anunciarse en un
 //   canal, por ejemplo), REUSA este: abrir una segunda conexión sería un segundo

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotrino/remote-agent",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Middleware compartido del ecosistema Dotrino para apps de agente remoto cifrado punto a punto (handshake E2E, emparejamiento SAS con vault, revocación, descubrimiento). Lo consumen dotrino-terminal (PTY) y dotrino-ia (chat con IA).",
   "type": "module",
   "main": "./index.js",

package/protocol.js

@@ -26,6 +26,10 @@ export const VMSG = {
   REVOKED: 'vault.revoked',
   RENEW: 'vault.renew',
   RENEWED: 'vault.renewed',
+  // Un INCIDENTE sobre otro aparato de la cuenta (la terminal: tres claves mal seguidas).
+  // La bóveda lo pone en la mesa del aprobador, que bloquea o ignora.
+  INCIDENT: 'vault.incident',
+  INCIDENT_RESULT: 'vault.incident.result',
   ERROR: 'vault.error'
 }
 

package/src/agent.js

@@ -26,6 +26,7 @@ import { sealersOf, memberCan, checkVaultReply } from '@dotrino/identity/acta'
 import { adoptRecord } from './record.js'
 import { installNodeGlobals } from '../node-globals.js'
 import { makeEphemeral, deriveKey, seal, open } from '../e2e.js'
+import { makeCatchUp } from './catch-up.js'
 import { HS, ACK, DATA, PING, PONG, ERROR, VMSG, SIGN_SCOPE, SESSION_TTL_MS, REVOKE_REFRESH_MS } from '../protocol.js'
 import { loadLink, saveLink, dataDir } from './link.js'
 
@@ -64,7 +65,7 @@ class AgentSession {
 }
 
 /**
- * Arranca el agente. Devuelve `{ machine, machineId, master, close }`.
+ * Arranca el agente. Devuelve `{ machine, machineId, master, client, reportIncident, isBlocked, close }`.
  *
  * @param {object} opts
  * @param {string} [opts.label]       qué agente es (`terminal-agent`, `ia-agent`…): lo contesta el pong
@@ -161,10 +162,16 @@ export async function startRemoteAgent (opts = {}) {
 
   // --- Revocación: refrescar la lista del vault por el proxy (best-effort) ---
   let revokedSet = new Set()
+  // LOS BLOQUEADOS (dueño, 2026-10-07): un aprobador bloqueó a ese aparato tras un incidente.
+  // No es una revocación —sigue en el acta, y se deshace en la bóveda—, así que va aparte y
+  // viaja con la lista de revocados. Se PERSISTE en el enlace: con la bóveda apagada, el
+  // agente tiene que seguir cerrándole la puerta a quien ya estaba bloqueado.
+  let blockedSet = new Set(Array.isArray(link.blocked) ? link.blocked : [])
   async function refreshRevocations () {
     try {
       const res = await vaultRpc(VMSG.DEVICES, VMSG.DEVICES_RESULT, { op: 'devices', publickey: myPub, ts: Date.now() })
       revokedSet = new Set((res.revoked || []).map((r) => r.nonce || r))
+      if (Array.isArray(res.blocked)) takeBlocked(res.blocked)
       // El acta viaja con la lista. Apuntar su `seq` es lo que dispara la renovación en el
       // mismo tic si el dueño nos cambió los permisos.
       await anotarActa(res.acta)
@@ -173,6 +180,35 @@ export async function startRemoteAgent (opts = {}) {
     }
   }
 
+  /** La lista nueva de bloqueados: se guarda, y a quien acaba de entrar en ella se le cierra la sesión. */
+  function takeBlocked (pubs) {
+    const next = new Set(pubs.filter((p) => typeof p === 'string'))
+    const same = next.size === blockedSet.size && [...next].every((p) => blockedSet.has(p))
+    blockedSet = next
+    if (same) return
+    link.blocked = [...next]
+    try { saveLink(dir, link) } catch (_) {}
+    for (const [sid, s] of sessions) {
+      if (!blockedSet.has(s.device)) continue
+      s.close(); sessions.delete(sid)
+      audit('session-blocked', { sid: sid.slice(0, 8) })
+      if (!opts.quiet) console.log(`[remote-agent] session ${sid.slice(0, 8)} closed: that device is blocked`)
+    }
+  }
+
+  /**
+   * REPORTAR UN INCIDENTE sobre otro aparato de la cuenta (`about`, su pubkey): la bóveda lo
+   * pone en la mesa de quien aprueba, que bloquea o ignora. Devuelve lo que contestó la
+   * bóveda: `{ id, approvers, blocked }` (`id: null` si nadie aprueba o ya está bloqueado).
+   * No decide nada aquí: un incidente es información, y el freno local es cosa de la app.
+   */
+  async function reportIncident ({ kind, about, tries = null }) {
+    if (typeof kind !== 'string' || !kind || typeof about !== 'string' || !about) throw new Error('reportIncident: kind and about are required')
+    audit('incident', { kind, device: (await pubkeyId(about).catch(() => '')).slice(0, 8).toUpperCase(), tries })
+    const res = await vaultRpc(VMSG.INCIDENT, VMSG.INCIDENT_RESULT, { op: 'incident', kind, about, tries, publickey: myPub, ts: Date.now() })
+    return { id: res.id ?? null, approvers: res.approvers ?? 0, blocked: !!res.blocked }
+  }
+
   /**
    * RENOVACIÓN del cert (`vault.renew`). YA NO ES UNA TAREA DE CALENDARIO: el papel no
    * vence, lleva el `seq` del acta con el que se emitió. Se pide uno nuevo cuando el ACTA
@@ -259,6 +295,8 @@ export async function startRemoteAgent (opts = {}) {
   }
 
   const vaultTick = async () => { await refreshRevocations(); await renewCertIfNeeded() }
+  /** Trae el acta ahora (con freno) y dice si AVANZÓ: solo entonces merece juzgar otra vez. */
+  const catchUp = makeCatchUp({ refresh: vaultTick, seq: () => link.actaSeq })
   vaultTick()
   const revTimer = setInterval(vaultTick, REVOKE_REFRESH_MS); revTimer.unref?.()
 
@@ -280,8 +318,25 @@ export async function startRemoteAgent (opts = {}) {
     // Manda el acta, no una llave fija: con varias selladoras el papel de un peer puede
     // venir firmado por otra bóveda del mismo perfil. Sin acta no se atiende — no hay con
     // qué decidir, así que no se decide que sí.
-    const chk = await verifyChain({ data, signature, cert, expectedScope: SIGN_SCOPE, ...contextoActa(), revoked: revokedSet })
-    if (!chk.ok) return send(from, { type: ERROR, error: 'no autorizado: ' + chk.reason })
+    // SE JUZGA, Y SI NO PASA SE PREGUNTA A LA BÓVEDA ANTES DE DECIR QUE NO. El acta se trae cada
+    // `REVOKE_REFRESH_MS` (5 min), así que un aparato recién emparejado era un desconocido hasta
+    // el siguiente tic: «este perfil no reconoce a ese aparato» nada más emparejar (un iPhone, el
+    // 2026-10-07). Ahora, ante un rechazo, se trae el acta EN EL MOMENTO y se juzga otra vez, una
+    // sola — y solo si el acta avanzó. Con freno (`catchUp`): cualquiera puede mandar saludos, y
+    // no por eso se le pregunta a la bóveda cada vez.
+    const judge = async () => {
+      const chk = await verifyChain({ data, signature, cert, expectedScope: SIGN_SCOPE, ...contextoActa(), revoked: revokedSet })
+      if (!chk.ok) return { error: 'no autorizado: ' + chk.reason }
+      return { chk }
+    }
+    let verdict = await judge()
+    const known = (v) => {
+      const acta = actaDeConfianza()
+      return !!acta && (acta.members || []).some((m) => m?.pub === v.chk.device) && memberCan(acta, v.chk.device, 'sign')
+    }
+    if ((verdict.error || !known(verdict)) && await catchUp()) verdict = await judge()
+    if (verdict.error) return send(from, { type: ERROR, error: verdict.error })
+    const chk = verdict.chk
     // CERT ∩ ACTA. `verifyChain` comprueba QUIÉN EMITIÓ el papel; que el APARATO siga siendo
     // isMember y pueda firmar lo dice el acta, y hay que preguntárselo aparte. Sin esto, un
     // papel bien firmado por una selladora abría sesión aunque el acta no nombrara a ese
@@ -301,6 +356,12 @@ export async function startRemoteAgent (opts = {}) {
     if (!acta || !isMember || !memberCan(acta, chk.device, 'sign')) {
       return send(from, { type: ERROR, error: 'no autorizado: acta — este perfil no reconoce a ese aparato' })
     }
+    // BLOQUEADO por un aprobador: está en el acta y su papel vale, y aun así no entra. Se le
+    // dice con su código, que no es lo mismo que un papel viejo ni que una revocación.
+    if (blockedSet.has(chk.device)) {
+      audit('session-refused', { reason: 'blocked', device: (await pubkeyId(chk.device)).slice(0, 8).toUpperCase() })
+      return send(from, { type: ERROR, code: 'blocked', error: 'no autorizado: bloqueado — un aprobador bloqueó este aparato; se desbloquea en la bóveda' })
+    }
     if (data.op !== HS || typeof data.eph !== 'string') return send(from, { type: ERROR, error: 'handshake inválido' })
 
     const eph = await makeEphemeral()
@@ -366,6 +427,10 @@ export async function startRemoteAgent (opts = {}) {
     // tiene en el acta lo pone el dueño al emparejar y no sirve para saber qué atiende.
     else if (payload.type === PING) send(from, { type: PONG, n: payload.n, kind: opts.label || null })
     else if (payload.type === VMSG.REVOKED) handleRevoked(payload).catch(() => {})
+    // Un aviso de bloqueo o desbloqueo (`vault.admin.event`) no se cree: dispara traer la
+    // lista de la bóveda, que sí va firmada. Así el bloqueo cierra la sesión en el acto, en
+    // vez de esperar al tic de cinco minutos.
+    else if (payload.type === 'vault.admin.event' && (payload.body?.ev === 'blocked' || payload.body?.ev === 'unblocked')) refreshRevocations().catch(() => {})
   })
 
   if (!opts.quiet) {
@@ -373,7 +438,7 @@ export async function startRemoteAgent (opts = {}) {
   }
   if (opts.onReady) { try { opts.onReady({ machine: myPub, machineId: myId, master }) } catch (_) {} }
 
-  return { machine: myPub, machineId: myId, master, client, close: stop }
+  return { machine: myPub, machineId: myId, master, client, reportIncident, isBlocked: (pub) => blockedSet.has(pub), close: stop }
 }
 
 export default { startRemoteAgent }

package/src/catch-up.js

@@ -0,0 +1,29 @@
+/**
+ * catch-up.js — ponerse al día con la bóveda ANTES de rechazar a alguien.
+ *
+ * El agente trae el acta cada pocos minutos. Entre un tic y el siguiente no sabe de un aparato
+ * recién emparejado, y lo rechazaba. `makeCatchUp` da una función que trae el acta en el momento
+ * y contesta si avanzó — con un freno, porque un saludo lo puede mandar cualquiera y no por eso se
+ * le pregunta a la bóveda cada vez.
+ *
+ * @param {{ refresh: () => Promise<void>, seq: () => (number|null|undefined), minGapMs?: number, now?: () => number }} o
+ * @returns {() => Promise<boolean>} true si el acta avanzó (y vale la pena juzgar otra vez).
+ */
+export const CATCH_UP_GAP_MS = 10_000
+
+export function makeCatchUp ({ refresh, seq, minGapMs = CATCH_UP_GAP_MS, now = Date.now }) {
+  let last = -Infinity
+  let running = null
+  return async () => {
+    // Uno a la vez: los saludos que lleguen mientras tanto esperan a ese mismo y usan su resultado.
+    if (running) return running
+    if (now() - last < minGapMs) return false
+    last = now()
+    const before = seq()
+    running = (async () => {
+      try { await refresh() } catch (_) { return false }
+      return seq() !== before
+    })().finally(() => { running = null })
+    return running
+  }
+}