@dotrino/remote-agent 0.22.0 → 0.22.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotrino/remote-agent",
-  "version": "0.22.0",
+  "version": "0.22.2",
   "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/src/agent.js

@@ -130,7 +130,7 @@ export async function startRemoteAgent (opts = {}) {
   const dir = opts.dir || dataDir()
   const link = opts.link || loadLink(dir)
   if (!link?.device?.privateJwk || !link?.cert || !link?.iss) {
-    throw new Error('esta máquina no está enlazada. Ejecuta primero el enrolamiento (enroll) de tu agente.')
+    throw new Error('this machine is not linked: enroll your agent first')
   }
   const master = link.iss
   const myPub = link.device.publickey
@@ -214,7 +214,7 @@ export async function startRemoteAgent (opts = {}) {
       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)
+      await recordActa(res.acta)
     } catch (e) {
       if (!opts.quiet) console.error('[remote-agent] could not refresh revocations (using cache):', e.message)
     }
@@ -270,10 +270,10 @@ export async function startRemoteAgent (opts = {}) {
     //     máquina. Sin esta rama la migración no terminaba nunca — el disparador comparaba
     //     `seq` y un papel viejo no tiene, así que nunca saltaba.
     //   · o el acta que hemos visto va por delante del papel: el dueño cambió permisos.
-    const legado = typeof link.cert?.seq !== 'number'
-    const visto = link.actaSeq
-    const atrasado = typeof visto === 'number' && typeof link.cert?.seq === 'number' && visto > link.cert.seq
-    if (!legado && !atrasado) return
+    const legacy = typeof link.cert?.seq !== 'number'
+    const seenSeq = link.actaSeq
+    const behind = typeof seenSeq === 'number' && typeof link.cert?.seq === 'number' && seenSeq > link.cert.seq
+    if (!legacy && !behind) return
     try {
       const res = await vaultRpc(VMSG.RENEW, VMSG.RENEWED, { op: 'renew', publickey: myPub, ts: Date.now() })
       const cert = res?.cert
@@ -308,7 +308,7 @@ export async function startRemoteAgent (opts = {}) {
    * mandar un acta inventada y nombrarse miembro. Ahora el acta tiene que encadenar desde la
    * que ya se dio por buena, o venir firmada por la bóveda con la que se enroló.
    */
-  async function anotarActa (acta) {
+  async function recordActa (acta) {
     if (typeof acta?.seq !== 'number') return
     const r = await adoptRecord({ link, candidate: acta, me: myPub })
     if (!r.adopt) {
@@ -328,9 +328,9 @@ export async function startRemoteAgent (opts = {}) {
    * El acta con la que se juzga un papel. Sin ella no se atiende a nadie — y un acta que
    * nunca se comprobó (la que guardó una versión anterior) cuenta como no tenerla.
    */
-  const actaDeConfianza = () => (link.actaTrusted === true && link.acta ? link.acta : null)
-  const contextoActa = () => {
-    const acta = actaDeConfianza()
+  const trustedActa = () => (link.actaTrusted === true && link.acta ? link.acta : null)
+  const actaContext = () => {
+    const acta = trustedActa()
     return acta ? { actaSeq: acta.seq, sealers: sealersOf(acta) } : { actaSeq: null, sealers: null }
   }
 
@@ -349,11 +349,11 @@ export async function startRemoteAgent (opts = {}) {
 
   async function handleHandshake (from, p) {
     const { data, signature, cert } = p
-    if (!data || !signature || !cert) return send(from, { type: ERROR, error: 'handshake incompleto' })
+    if (!data || !signature || !cert) return send(from, { type: ERROR, error: 'incomplete handshake' })
     // FRESCURA anti-replay: el HS debe ser reciente (±5 min); sin esto un relay
     // malicioso podía reproducir handshakes viejos (sesiones huérfanas / DoS).
     if (typeof data.ts !== 'number' || Math.abs(Date.now() - data.ts) > 5 * 60 * 1000) {
-      return send(from, { type: ERROR, error: 'handshake vencido (posible replay, o el reloj del dispositivo está desfasado)' })
+      return send(from, { type: ERROR, error: 'stale handshake (possible replay, or the device clock is off)' })
     }
     // 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
@@ -365,17 +365,17 @@ export async function startRemoteAgent (opts = {}) {
     // 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 }
+      const chk = await verifyChain({ data, signature, cert, expectedScope: SIGN_SCOPE, ...actaContext(), revoked: revokedSet })
+      if (!chk.ok) return { code: 'unauthorized', reason: chk.reason, error: 'unauthorized: ' + chk.reason }
       return { chk }
     }
     let verdict = await judge()
     const known = (v) => {
-      const acta = actaDeConfianza()
+      const acta = trustedActa()
       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 })
+    if (verdict.error) return send(from, { type: ERROR, code: verdict.code, reason: verdict.reason, 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
@@ -391,18 +391,18 @@ export async function startRemoteAgent (opts = {}) {
     // abrir sesión con otro agente. El bot social se pasó así el 1 de septiembre, con un
     // node de contenido encendido a su lado que le contestaba «ese aparato no firma por este
     // perfil». Se le pide lo que corresponde: que el acta lo nombre y le reconozca `sign`.
-    const acta = actaDeConfianza()
+    const acta = trustedActa()
     const isMember = (acta?.members || []).some((m) => m?.pub === chk.device)
     if (!acta || !isMember || !memberCan(acta, chk.device, 'sign')) {
-      return send(from, { type: ERROR, error: 'no autorizado: acta — este perfil no reconoce a ese aparato' })
+      return send(from, { type: ERROR, code: 'unauthorized', reason: 'not-in-record', error: 'unauthorized: not-in-record' })
     }
     // 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' })
+      return send(from, { type: ERROR, code: 'blocked', reason: 'blocked', error: 'unauthorized: blocked' })
     }
-    if (data.op !== HS || typeof data.eph !== 'string') return send(from, { type: ERROR, error: 'handshake inválido' })
+    if (data.op !== HS || typeof data.eph !== 'string') return send(from, { type: ERROR, error: 'invalid handshake' })
 
     const eph = await makeEphemeral()
     const sid = [...crypto.getRandomValues(new Uint8Array(16))].map((x) => x.toString(16).padStart(2, '0')).join('')
@@ -419,7 +419,7 @@ export async function startRemoteAgent (opts = {}) {
     sessions.set(sid, session)
     audit('session-open', { sid: sid.slice(0, 8), device: (await pubkeyId(chk.device)).slice(0, 8).toUpperCase() })
     send(from, { type: ACK, sid, ack, signature: ackSig, cert: link.cert })
-    if (!opts.quiet) console.log(`[remote-agent] sesión ${sid.slice(0, 8)} autorizada (device ${chk.device?.slice?.(0, 8) || '?'})`)
+    if (!opts.quiet) console.log(`[remote-agent] session ${sid.slice(0, 8)} authorized (device ${chk.device?.slice?.(0, 8) || '?'})`)
     if (opts.onSession) { try { opts.onSession(session) } catch (e) { if (!opts.quiet) console.error('[remote-agent] onSession:', e.message) } }
   }
 
@@ -428,11 +428,11 @@ export async function startRemoteAgent (opts = {}) {
     // Con `code` y el `sid`: así el cliente sabe que es SU sesión la que se perdió (el agente
     // se reinició, o venció) y vuelve a saludar solo, en vez de quedarse con un error. Se
     // comprueba por el código, no por la frase.
-    if (!s) return send(from, { type: ERROR, code: 'unknown-session', sid: p.sid, error: 'sesión desconocida o expirada' })
+    if (!s) return send(from, { type: ERROR, code: 'unknown-session', sid: p.sid, error: 'unknown or expired session' })
     s._exp = Date.now() + SESSION_TTL_MS
     s.from = from
     if (s._gone) { clearTimeout(s._gone); s._gone = null }
-    s._ingest(p.env).catch(() => send(from, { type: ERROR, error: 'sobre inválido' }))
+    s._ingest(p.env).catch(() => send(from, { type: ERROR, error: 'invalid envelope' }))
   }
 
   // LA CONEXIÓN DEL CLIENTE SE FUE: su sesión no se queda 30 minutos. El proxio avisa de que ese
@@ -479,7 +479,7 @@ export async function startRemoteAgent (opts = {}) {
     if (typeof b.exp === 'number' && Date.now() > b.exp) return
     if (!await verifyDeviceSig({ publickey: master, data: b, signature: p.signature })) return
     audit('revoked', { nonce: b.nonce })
-    if (!opts.quiet) console.log('\n[remote-agent] tu bóveda REVOCÓ esta máquina → borro el enlace y salgo.')
+    if (!opts.quiet) console.log('\n[remote-agent] your vault REVOKED this machine → deleting the link and exiting.')
     try { fs.rmSync(path.join(dir, 'link.json'), { force: true }) } catch (_) {}
     stop()
     if (opts.onRevoked) { try { opts.onRevoked() } catch (_) {} }
@@ -502,7 +502,7 @@ export async function startRemoteAgent (opts = {}) {
   })
 
   if (!opts.quiet) {
-    console.log(`[remote-agent] agente activo · máquina ${myId} · vault ${(await pubkeyId(master)).slice(0, 16)} · proxy ${proxyUrl}`)
+    console.log(`[remote-agent] agent running · machine ${myId} · vault ${(await pubkeyId(master)).slice(0, 16)} · proxy ${proxyUrl}`)
   }
   if (opts.onReady) { try { opts.onReady({ machine: myPub, machineId: myId, master }) } catch (_) {} }
 

package/src/client.js

@@ -92,7 +92,7 @@ export class RemoteAgentClient {
   }
 
   async connect () {
-    if (!this.agentPubkey) throw new Error('falta la dirección del agente destino')
+    if (!this.agentPubkey) throw new Error('the target agent address is missing')
     const { WebSocketProxyClient } = await import('@dotrino/proxy-client')
     // SIEMPRE EL CAMINO MÁS DIRECTO: WebRTC encendido. Estuvo en `false` desde el 0.1.0
     // porque entonces Node no tenía con qué; se quedó así cuando ya lo tuvo, y dos equipos
@@ -139,7 +139,7 @@ export class RemoteAgentClient {
    * de antes de volver a saludar) no dice nada nuevo y se ignora.
    */
   _onAgentError (p) {
-    if (p.code !== 'unknown-session') { this._emit('error', Object.assign(new Error(p.error), { code: p.code })); return }
+    if (p.code !== 'unknown-session') { this._emit('error', Object.assign(new Error(p.error), { code: p.code, reason: p.reason })); return }
     if (p.sid !== this.sid) return
     this._resume()
   }
@@ -177,9 +177,9 @@ export class RemoteAgentClient {
         // El token se apunta AQUÍ, en el mismo tic: si el agente es quien abre el canal
         // directo, su oferta llega justo detrás del ack y tiene que encontrarlo ya.
         if (p.type === ACK && p.ack && p.ack.ceph === eph.pub) { off(); if (from) this._directPeers.add(from); resolve({ ...p, from }) }
-        else if (p.type === ERROR) { off(); reject(new Error(p.error)) }
+        else if (p.type === ERROR) { off(); reject(Object.assign(new Error(p.error), { code: p.code, reason: p.reason })) }
       })
-      setTimeout(() => { off(); reject(new Error('el agente no respondió (¿está corriendo allí?)')) }, 20000)
+      setTimeout(() => { off(); reject(new Error('the agent did not reply (is it running there?)')) }, 20000)
     })
     this.client.sendByPubkey(this.agentPubkey, { type: HS, data, signature, cert })
     const res = await acked
@@ -205,9 +205,9 @@ export class RemoteAgentClient {
       data: res.ack, signature: res.signature, cert: res.cert, trustedIssuer: this.link.iss,
       actaSeq: acta?.seq ?? null, sealers: acta ? sealersOf(acta) : null
     })
-    if (!chk.ok) throw new Error('el agente no está certificado por tu vault: ' + chk.reason)
-    if (res.ack.machine !== this.agentPubkey) throw new Error('el ack vino de otro agente')
-    if (res.ack.ceph !== eph.pub || res.ack.sid !== res.sid) throw new Error('ack no corresponde a este handshake')
+    if (!chk.ok) throw new Error('the agent is not certified by your vault: ' + chk.reason)
+    if (res.ack.machine !== this.agentPubkey) throw new Error('the ack came from another agent')
+    if (res.ack.ceph !== eph.pub || res.ack.sid !== res.sid) throw new Error('the ack does not match this handshake')
 
     this.sid = res.sid
     this.key = await deriveKey(eph.privateKey, res.ack.seph, res.sid)

package/src/link.js

@@ -117,12 +117,12 @@ export function identityFromLink (link, { dir = dataDir() } = {}) {
   return {
     me: { publickey: device.publickey },
     async signData (data) {
-      const firmado = await signWithDevice({ privateJwk: device.privateJwk, publickey: device.publickey, data })
+      const signed = await signWithDevice({ privateJwk: device.privateJwk, publickey: device.publickey, data })
       // A NOMBRE DE QUIÉN VA, igual que en el navegador: el `profileId` y la cadena de
       // selladores que lo prueba (`refreshChain`). Sin cadena la firma vale ante la bóveda
       // (que conoce el papel) pero no ante un extraño que use `verifySignedFor`.
       const chain = Array.isArray(link.sealerChain) && link.sealerChain.length ? link.sealerChain : null
-      return { ...firmado, profileId: chain ? chain[0].profileId : null, chain }
+      return { ...signed, profileId: chain ? chain[0].profileId : null, chain }
     },
     async getVaultCert () { return { cert: link.cert } },
     async vaultStatus () {
@@ -167,12 +167,12 @@ export async function renewLink (link, { dir = dataDir(), force = false } = {})
   // EL PAPEL DEL MODELO VIEJO SE CAMBIA SÍ O SÍ. Lleva `exp` y no `seq`; se acepta por el
   // repliegue de migración pero muere en su fecha, y con él la máquina. Los demás se
   // renuevan cuando el acta va por delante — nunca por calendario, que el papel no vence.
-  const legado = typeof link.cert.seq !== 'number'
-  if (legado && typeof link.cert.exp === 'number' && link.cert.exp <= Date.now()) {
+  const legacy = typeof link.cert.seq !== 'number'
+  if (legacy && typeof link.cert.exp === 'number' && link.cert.exp <= Date.now()) {
     return { renewed: false, reason: 'expired: enroll again' }
   }
-  const atrasado = typeof link.actaSeq === 'number' && typeof link.cert.seq === 'number' && link.actaSeq > link.cert.seq
-  if (!force && !legado && !atrasado) return { renewed: false, seq: link.cert.seq, reason: 'not due' }
+  const behind = typeof link.actaSeq === 'number' && typeof link.cert.seq === 'number' && link.actaSeq > link.cert.seq
+  if (!force && !legacy && !behind) return { renewed: false, seq: link.cert.seq, reason: 'not due' }
   installNodeGlobals(dir)
   try {
     // `requestRenew` ya JUZGA lo que devuelve (`checkVaultReply` del pilar: acta bien