@dotrino/remote-agent 0.22.5 → 0.24.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -67,6 +67,11 @@ const ra = await startRemoteAgent({
67
67
  // bóveda de que OTRO aparato de la cuenta hizo algo (la terminal: tres claves mal seguidas).
68
68
  // Quien aprueba lo ve y bloquea o ignora; bloqueado, no saluda a ningún agente (`code: 'blocked'`)
69
69
  // y la lista viaja con la de revocados y queda en el enlace (`link.blocked`). ra.isBlocked(pub).
70
+ // ra.checkCap(session.device, 'admin') → { ok: true, seq } | { ok: false, code } (0.23.1): ¿ese
71
+ // aparato tiene ese permiso en el acta? Se pregunta en CADA petición contra el acta de confianza
72
+ // del agente, nunca contra lo que diga el cliente. Si no pasa, trae el acta en el momento (con
73
+ // freno) y vuelve a juzgar. Códigos: `no-record` (no hay acta de confianza: no se sabe),
74
+ // `not-in-record`, `missing-cap`. ra.record() → esa acta (o null).
70
75
  // ra.client → el WebSocketProxyClient ya conectado e identificado bajo esta
71
76
  // máquina. Si tu agente necesita algo más del transporte (anunciarse en un
72
77
  // canal, por ejemplo), REUSA este: abrir una segunda conexión sería un segundo
@@ -178,8 +183,17 @@ extraerlo luego a este paquete.
178
183
 
179
184
  ## Seguridad
180
185
 
181
- - **Autorización = estar vinculado al vault.** El agente solo atiende dispositivos
182
- cuya cadena certifica la maestra pineada (`verifyChain` con `trustedIssuer`).
186
+ - **Autorización = el ACTA, en las dos puntas** (0.24.0). El papel (`cert`) prueba quién
187
+ lo emitió —una selladora del acta— pero no caduca, así que el de un aparato quitado sigue
188
+ bien firmado. Lo que decide es `canGreet(acta, pub)` (`src/membership.js`): el acta
189
+ vigente lo nombra y le da `sign`.
190
+ - El **agente** lo exige a quien saluda, y **cierra la sesión abierta** de quien sale del
191
+ acta en cuanto se entera (el aviso `vault.admin.event` de la bóveda trae el acta, que
192
+ solo se adopta si encadena), con `ra.error` `unauthorized` / `not-in-record` o `revoked`.
193
+ - El **cliente** lo exige a la máquina: quien firma el ack tiene que ser la pedida
194
+ (`wrong-agent`), y seguir en el acta (`not-in-record`). El acta se pide en cada saludo.
195
+ - El acta que devuelve `listVaultDevices` es una **comprobada** (identity ≥ 0.126.2 en el
196
+ navegador; `identityFromLink` en Node), nunca la que llegó por la red.
183
197
  - **Emparejamiento con código SAS** que no viaja (anti aprobación a ciegas / vault impostor).
184
198
  - **Anti-replay** en el handshake (`ts` ±5 min).
185
199
  - **Auto-borrado** del `link.json` al recibir un `revoke` firmado por la maestra.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dotrino/remote-agent",
3
- "version": "0.22.5",
3
+ "version": "0.24.0",
4
4
  "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).",
5
5
  "type": "module",
6
6
  "main": "./index.js",
package/src/agent.js CHANGED
@@ -24,6 +24,7 @@ import path from 'node:path'
24
24
  import { verifyChain, signWithDevice, verifyDeviceSig, pubkeyId, keyLabel } from '@dotrino/identity/capabilities'
25
25
  import { sealersOf, memberCan, checkVaultReply } from '@dotrino/identity/acta'
26
26
  import { adoptRecord } from './record.js'
27
+ import { canGreet } from './membership.js'
27
28
  import { installNodeGlobals } from '../node-globals.js'
28
29
  import { makeEphemeral, deriveKey, seal, open } from '../e2e.js'
29
30
  import { makeCatchUp } from './catch-up.js'
@@ -103,7 +104,7 @@ export class AgentSession {
103
104
  }
104
105
 
105
106
  /**
106
- * Arranca el agente. Devuelve `{ machine, machineId, master, client, reportIncident, isBlocked, close }`.
107
+ * Arranca el agente. Devuelve `{ machine, machineId, master, client, reportIncident, isBlocked, checkCap, record, close }`.
107
108
  *
108
109
  * @param {object} opts
109
110
  * @param {string} [opts.label] qué agente es (`terminal-agent`, `ia-agent`…): lo contesta el pong
@@ -215,6 +216,7 @@ export async function startRemoteAgent (opts = {}) {
215
216
  // El acta viaja con la lista. Apuntar su `seq` es lo que dispara la renovación en el
216
217
  // mismo tic si el dueño nos cambió los permisos.
217
218
  await recordActa(res.acta)
219
+ evictOutsiders()
218
220
  } catch (e) {
219
221
  if (!opts.quiet) console.error('[remote-agent] could not refresh revocations (using cache):', e.message)
220
222
  }
@@ -299,19 +301,40 @@ export async function startRemoteAgent (opts = {}) {
299
301
  * que ya se dio por buena, o venir firmada por la bóveda con la que se enroló.
300
302
  */
301
303
  async function recordActa (acta) {
302
- if (typeof acta?.seq !== 'number') return
304
+ if (typeof acta?.seq !== 'number') return false
303
305
  const r = await adoptRecord({ link, candidate: acta, me: myPub })
304
306
  if (!r.adopt) {
305
307
  if (r.reason !== 'same-record') {
306
308
  audit('record-rejected', { seq: acta.seq, reason: r.reason })
307
309
  if (!opts.quiet) console.error(`[remote-agent] record #${acta.seq} rejected (${r.reason}); keeping the one already trusted`)
308
310
  }
309
- return
311
+ return false
310
312
  }
311
313
  link.acta = acta
312
314
  link.actaSeq = acta.seq
313
315
  link.actaTrusted = true
314
316
  try { saveLink(dir, link) } catch (_) {}
317
+ evictOutsiders()
318
+ return true
319
+ }
320
+
321
+ /**
322
+ * CIERRA LAS SESIONES DE QUIEN YA NO PUEDE ESTAR: el acta de confianza ya no lo nombra (o
323
+ * le quitó `sign`), o su papel se retiró. Se juzgaba solo al saludar, así que un aparato
324
+ * quitado del acta conservaba su consola mientras siguiera escribiendo (cada mensaje
325
+ * renueva la sesión). Se le avisa con el mismo error que recibiría al saludar.
326
+ */
327
+ function evictOutsiders () {
328
+ const acta = trustedActa()
329
+ for (const [sid, s] of sessions) {
330
+ const reason = !canGreet(acta, s.device) ? 'not-in-record'
331
+ : (s._certNonce && revokedSet.has(s._certNonce)) ? 'revoked' : null
332
+ if (!reason) continue
333
+ send(s.from, { type: ERROR, code: 'unauthorized', reason, sid, error: 'unauthorized: ' + reason })
334
+ s.close(); sessions.delete(sid)
335
+ audit('session-evicted', { sid: sid.slice(0, 8), reason })
336
+ if (!opts.quiet) console.log(`[remote-agent] session ${sid.slice(0, 8)} closed: ${reason}`)
337
+ }
315
338
  }
316
339
 
317
340
  /**
@@ -360,10 +383,7 @@ export async function startRemoteAgent (opts = {}) {
360
383
  return { chk }
361
384
  }
362
385
  let verdict = await judge()
363
- const known = (v) => {
364
- const acta = trustedActa()
365
- return !!acta && (acta.members || []).some((m) => m?.pub === v.chk.device) && memberCan(acta, v.chk.device, 'sign')
366
- }
386
+ const known = (v) => canGreet(trustedActa(), v.chk.device)
367
387
  if ((verdict.error || !known(verdict)) && await catchUp()) verdict = await judge()
368
388
  if (verdict.error) return send(from, { type: ERROR, code: verdict.code, reason: verdict.reason, error: verdict.error })
369
389
  const chk = verdict.chk
@@ -381,9 +401,7 @@ export async function startRemoteAgent (opts = {}) {
381
401
  // abrir sesión con otro agente. El bot social se pasó así el 1 de septiembre, con un
382
402
  // node de contenido encendido a su lado que le contestaba «ese aparato no firma por este
383
403
  // perfil». Se le pide lo que corresponde: que el acta lo nombre y le reconozca `sign`.
384
- const acta = trustedActa()
385
- const isMember = (acta?.members || []).some((m) => m?.pub === chk.device)
386
- if (!acta || !isMember || !memberCan(acta, chk.device, 'sign')) {
404
+ if (!canGreet(trustedActa(), chk.device)) {
387
405
  return send(from, { type: ERROR, code: 'unauthorized', reason: 'not-in-record', error: 'unauthorized: not-in-record' })
388
406
  }
389
407
  // BLOQUEADO por un aprobador: está en el acta y su papel vale, y aun así no entra. Se le
@@ -406,6 +424,8 @@ export async function startRemoteAgent (opts = {}) {
406
424
 
407
425
  const session = new AgentSession({ sid, key, from, device: chk.device, send, isDirect: typeof client.isWebRTCOpen === 'function' ? (t) => client.isWebRTCOpen(t) : null })
408
426
  session._exp = Date.now() + SESSION_TTL_MS
427
+ // El papel con que entró: si después se retira (`revoked`), la sesión se cierra.
428
+ session._certNonce = cert.nonce || null
409
429
  sessions.set(sid, session)
410
430
  audit('session-open', { sid: sid.slice(0, 8), device: (await pubkeyId(chk.device)).slice(0, 8).toUpperCase() })
411
431
  send(from, { type: ACK, sid, ack, signature: ackSig, cert: link.cert })
@@ -475,6 +495,20 @@ export async function startRemoteAgent (opts = {}) {
475
495
  if (opts.onRevoked) { try { opts.onRevoked() } catch (_) {} }
476
496
  }
477
497
 
498
+ /**
499
+ * LA BÓVEDA AVISA DE QUE EL PERFIL CAMBIÓ (`vault.admin.event`, con el acta nueva). El aviso
500
+ * no se cree: el acta que trae solo se adopta si encadena desde la de confianza
501
+ * (`recordActa`), y si no encadena (faltan eslabones) se trae de la bóveda, con freno. Así
502
+ * quitar un aparato le cierra la consola en el acto, sin esperar al tic de cinco minutos.
503
+ * Un bloqueo no cambia el acta: va en la lista, que sí se pide.
504
+ */
505
+ async function onAdminEvent (payload) {
506
+ const ev = payload.body?.ev
507
+ if (ev === 'blocked' || ev === 'unblocked') return refreshRevocations()
508
+ if (payload.acta && await recordActa(payload.acta)) return
509
+ if (typeof payload.acta?.seq === 'number' && payload.acta.seq > (link.actaSeq ?? -1)) await catchUp()
510
+ }
511
+
478
512
  client.on('message', (from, payload) => {
479
513
  if (!payload || typeof payload !== 'object') return
480
514
  if (payload.type === HS) handleHandshake(from, payload).catch((e) => send(from, { type: ERROR, error: e.message }))
@@ -488,15 +522,41 @@ export async function startRemoteAgent (opts = {}) {
488
522
  // Un aviso de bloqueo o desbloqueo (`vault.admin.event`) no se cree: dispara traer la
489
523
  // lista de la bóveda, que sí va firmada. Así el bloqueo cierra la sesión en el acto, en
490
524
  // vez de esperar al tic de cinco minutos.
491
- else if (payload.type === 'vault.admin.event' && (payload.body?.ev === 'blocked' || payload.body?.ev === 'unblocked')) refreshRevocations().catch(() => {})
525
+ else if (payload.type === 'vault.admin.event') onAdminEvent(payload).catch(() => {})
492
526
  })
493
527
 
528
+ /**
529
+ * ¿PUEDE ESTE APARATO `cap` según el acta? Para la app que atiende la sesión y tiene que
530
+ * decidir algo más que «abrir sesión» (un servicio que solo deja administrar a quien tiene
531
+ * `admin`). Se pregunta en CADA petición contra el acta de confianza del agente —la misma
532
+ * con la que se juzga el saludo—, nunca contra lo que diga el cliente.
533
+ *
534
+ * Si no pasa, se trae el acta en el momento y se juzga otra vez (con el freno de `catchUp`):
535
+ * un permiso recién concedido no espera al tic de cinco minutos.
536
+ *
537
+ * Sin repliegue: sin acta no se sabe, y se dice con su código.
538
+ * @returns {Promise<{ ok: true, seq: number } | { ok: false, code: 'no-record'|'not-in-record'|'missing-cap' }>}
539
+ */
540
+ async function checkCap (pub, cap) {
541
+ if (typeof pub !== 'string' || !pub || typeof cap !== 'string' || !cap) throw Object.assign(new Error('checkCap: pub and cap are required'), { code: 'bad-request' })
542
+ const look = () => {
543
+ const acta = trustedActa()
544
+ if (!acta) return { ok: false, code: 'no-record' }
545
+ if (!(acta.members || []).some((m) => m?.pub === pub)) return { ok: false, code: 'not-in-record' }
546
+ if (!memberCan(acta, pub, cap)) return { ok: false, code: 'missing-cap' }
547
+ return { ok: true, seq: acta.seq }
548
+ }
549
+ let r = look()
550
+ if (!r.ok && await catchUp()) r = look()
551
+ return r
552
+ }
553
+
494
554
  if (!opts.quiet) {
495
555
  console.log(`[remote-agent] agent running · machine ${myId} · vault ${(await pubkeyId(master)).slice(0, 16)} · proxy ${proxyUrl}`)
496
556
  }
497
557
  if (opts.onReady) { try { opts.onReady({ machine: myPub, machineId: myId, master }) } catch (_) {} }
498
558
 
499
- return { machine: myPub, machineId: myId, master, client, reportIncident, isBlocked: (pub) => blockedSet.has(pub), close: stop }
559
+ return { machine: myPub, machineId: myId, master, client, reportIncident, isBlocked: (pub) => blockedSet.has(pub), checkCap, record: trustedActa, close: stop }
500
560
  }
501
561
 
502
562
  export default { startRemoteAgent }
package/src/client.js CHANGED
@@ -21,8 +21,9 @@
21
21
  * `on('message', cb)` recibe los payloads del agente, ya descifrados.
22
22
  */
23
23
  import { verifyChain } from '@dotrino/identity/capabilities'
24
- import { sealersOf } from '@dotrino/identity/acta'
24
+ import { sealersOf, samePubkey } from '@dotrino/identity/acta'
25
25
  import { makeEphemeral, deriveKey, seal, open } from '../e2e.js'
26
+ import { canGreet } from './membership.js'
26
27
  import { HS, ACK, DATA, PING, PONG, ERROR, DEFAULT_PROXY } from '../protocol.js'
27
28
 
28
29
  export class RemoteAgentClient {
@@ -59,19 +60,22 @@ export class RemoteAgentClient {
59
60
  _emit (ev, ...args) { for (const h of (this._h[ev] || [])) { try { h(...args) } catch (_) {} } }
60
61
 
61
62
  /**
62
- * El acta con la que se juzga el papel del agente. Se pide UNA vez por cliente y se
63
- * guarda: es la política vigente del perfil, no cambia a mitad de una sesión.
63
+ * El acta con la que se juzga al agente. Se pide EN CADA SALUDO, no una vez por cliente:
64
+ * una pestaña vive días, y volver a saludar a una máquina que el dueño quitó entretanto
65
+ * tiene que fallar. `listVaultDevices` devuelve el acta ya COMPROBADA (la adoptada, no la
66
+ * que llegó por la red: identity ≥ 0.126.2, y `identityFromLink` en Node).
64
67
  *
65
- * Si no se puede traer, se devuelve `null` a propósito y `verifyChain` corta con
66
- * `no-record`. No hay repliegue: sin acta no hay con qué decidir, y no decidir es que no.
68
+ * Si la bóveda no contesta vale la que este aparato ya adoptó (`profileActa`): está
69
+ * comprobada, igual que la que guarda el agente. Es lo mismo que hace `listAgentsByLabel`.
70
+ * Si no hay ninguna, `null` y se corta con `no-record`: sin acta no hay con qué decidir, y
71
+ * no decidir es que no.
67
72
  */
68
73
  async _acta () {
69
- if (this._actaCache !== undefined) return this._actaCache
70
- let acta = this.link.acta || null
71
- if (!acta) {
72
- try { acta = (await this.link.id?.listVaultDevices?.())?.acta || null } catch (_) { acta = null }
73
- }
74
- this._actaCache = acta
74
+ if (this.link.acta) return this.link.acta
75
+ const id = this.link.id
76
+ let acta = null
77
+ try { acta = (await id?.listVaultDevices?.())?.acta || null } catch (_) {}
78
+ if (!acta) { try { acta = (await id?.profileActa?.())?.acta || null } catch (_) {} }
75
79
  return acta
76
80
  }
77
81
 
@@ -202,11 +206,22 @@ export class RemoteAgentClient {
202
206
  // `clientLink` no trae el acta, así que se le pide a la bóveda una vez y se guarda.
203
207
  const acta = await this._acta()
204
208
  const chk = await verifyChain({
205
- data: res.ack, signature: res.signature, cert: res.cert, trustedIssuer: this.link.iss,
209
+ data: res.ack, signature: res.signature, cert: res.cert,
206
210
  actaSeq: acta?.seq ?? null, sealers: acta ? sealersOf(acta) : null
207
211
  })
208
- if (!chk.ok) throw new Error('the agent is not certified by your vault: ' + chk.reason)
209
- if (res.ack.machine !== this.agentPubkey) throw new Error('the ack came from another agent')
212
+ if (!chk.ok) throw Object.assign(new Error('the agent is not certified by your vault: ' + chk.reason), { code: 'unauthorized', reason: chk.reason })
213
+ // QUIEN FIRMA ES LA MÁQUINA QUE SE PIDIÓ. `machine` es un campo más del ack: lo que prueba
214
+ // quién contesta es la llave que firma (`publickey`, la que `verifyChain` comprobó).
215
+ // Mirar solo `machine` dejaba a cualquier llave con papel de la cuenta hacerse pasar por
216
+ // otra máquina, con un relevo que le pasara el saludo.
217
+ if (!samePubkey(chk.device, this.agentPubkey) || !samePubkey(res.ack.machine, this.agentPubkey)) {
218
+ throw Object.assign(new Error('the ack came from another agent'), { code: 'unauthorized', reason: 'wrong-agent' })
219
+ }
220
+ // Y ESA MÁQUINA SIGUE EN EL ACTA. El papel no caduca: el de una máquina quitada (robada)
221
+ // sigue bien firmado. La misma regla que aplica el agente a quien le saluda.
222
+ if (!canGreet(acta, this.agentPubkey)) {
223
+ throw Object.assign(new Error('that machine is no longer in your account'), { code: 'unauthorized', reason: 'not-in-record' })
224
+ }
210
225
  if (res.ack.ceph !== eph.pub || res.ack.sid !== res.sid) throw new Error('the ack does not match this handshake')
211
226
 
212
227
  this.sid = res.sid
package/src/link.js CHANGED
@@ -142,11 +142,32 @@ export function identityFromLink (link, { dir = dataDir() } = {}) {
142
142
  // actual de un salto («sin-acta-previa»), de modo que la cadena no iba a usarse jamás.
143
143
  // Costó tenerlo así: la respuesta llegó a 1,03 MB, el proxio corta el frame a 1 MB y
144
144
  // la bóveda se quedaba muda para todo el ecosistema (2026-08-24).
145
- return requestDevices({ master: link.iss, proxy, device, cert: link.cert })
145
+ const res = await requestDevices({ master: link.iss, proxy, device, cert: link.cert })
146
+ // EL ACTA QUE SE DEVUELVE ES UNA COMPROBADA, nunca la que llegó por la red: la respuesta
147
+ // no trae remitente comprobable, y con ella se decide quién es de la cuenta (a quién
148
+ // se le abre una consola). Vale la que encadena desde la de confianza del enlace (o la
149
+ // sella la bóveda con la que se enroló, `adoptRecord`); si no, la de confianza que ya había.
150
+ return { ...res, acta: await checkedActa(link, res.acta, device.publickey) }
151
+ },
152
+ /** El acta de confianza del enlace (la que guardó el agente al comprobarla), o `null`. */
153
+ async profileActa () {
154
+ const acta = trustedActaOf(link)
155
+ return acta ? { acta } : null
146
156
  }
147
157
  }
148
158
  }
149
159
 
160
+ const trustedActaOf = (link) => (link?.actaTrusted === true && link.acta ? link.acta : null)
161
+
162
+ /** El acta que `listVaultDevices` puede dar por buena. Exportada para las pruebas. */
163
+ export async function checkedActa (link, candidate, me) {
164
+ if (candidate && typeof candidate.seq === 'number') {
165
+ const r = await adoptRecord({ link, candidate, me })
166
+ if (r.adopt) return candidate
167
+ }
168
+ return trustedActaOf(link)
169
+ }
170
+
150
171
  // Se reexporta por compatibilidad del subpath '/link'; la definición vive en protocol.js.
151
172
  export { RENEW_BEFORE_MS }
152
173
 
@@ -0,0 +1,23 @@
1
+ /**
2
+ * membership.js — ¿PUEDE ESTE APARATO ESTAR EN UNA SESIÓN? Una sola regla, para las dos puntas.
3
+ *
4
+ * Lo dice el ACTA vigente, y nada más: que la nombre y que le reconozca `sign`. El papel
5
+ * (`cert`) no basta: no caduca, así que el de un aparato que el dueño ya quitó sigue bien
6
+ * firmado. Por eso el papel prueba QUIÉN lo emitió y el acta decide si ese aparato sigue
7
+ * dentro.
8
+ *
9
+ * Antes la comprobaba solo el agente. El cliente se fiaba del papel del agente, y abría
10
+ * sesión con una máquina quitada del acta (robada, por ejemplo) o con cualquier llave con
11
+ * papel de la cuenta que dijera ser esa máquina (2026-10-23).
12
+ *
13
+ * Sin acta no se sabe, y no saber es que no.
14
+ */
15
+ import { memberCan, samePubkey } from '@dotrino/identity/acta'
16
+
17
+ /** @returns {boolean} */
18
+ export function canGreet (acta, pub) {
19
+ if (!acta || typeof pub !== 'string' || !pub) return false
20
+ return (acta.members || []).some((m) => samePubkey(m?.pub, pub)) && memberCan(acta, pub, 'sign')
21
+ }
22
+
23
+ export default { canGreet }