@dotrino/remote-agent 0.1.0

package/README.md

@@ -0,0 +1,112 @@
+# @dotrino/remote-agent
+
+Middleware compartido del ecosistema Dotrino para **apps de agente remoto cifrado
+punto a punto**. Lo consumen [`dotrino-terminal`](https://github.com/imdotrino/dotrino-terminal)
+(PTY remoto) y [`dotrino-ia`](https://github.com/imdotrino/dotrino-ia) (chat con
+agentes de IA), y cualquier app futura que necesite hablar con un proceso que corre
+en la máquina del usuario.
+
+Provee lo común — y **solo** eso:
+
+- **Canal cifrado E2E por sesión** (ECDH P-256 → HKDF → AES-256-GCM, isomórfico WebCrypto).
+- **Handshake anti-MITM** con `verifyChain` + anti-replay (firmado por el vault).
+- **Emparejamiento SAS** del agente contra el vault (código que no viaja).
+- **Revocación** con auto-borrado del enlace al ser revocada la máquina.
+- **Wiring de proxy + identity** (`identify` firmado, transporte por `proxy.dotrino.com`).
+- **Autodescubrimiento** de agentes por label (`listVaultDevices` + filtro).
+- **Auditoría** (`sessions.log` JSONL).
+
+**No sabe nada de PTY ni de IA.** Cada app define sus payloads de dominio
+(terminal pasa `{type:'cmd',...}`, ia pasa `{type:'msg',...}`) y su renderer.
+
+## Entry points (subpath exports)
+
+| Import | Entorno | Qué da |
+|---|---|---|
+| `@dotrino/remote-agent` | isomórfico | `e2e` (`makeEphemeral`/`deriveKey`/`seal`/`open`) + constantes de protocolo |
+| `@dotrino/remote-agent/agent` | Node | `startRemoteAgent(opts)` |
+| `@dotrino/remote-agent/client` | navegador | `RemoteAgentClient` |
+| `@dotrino/remote-agent/link` | Node | `enroll`, `loadLink`, `dataDir`, `parseQr` |
+| `@dotrino/remote-agent/discover` | navegador | `listAgentsByLabel` |
+
+## Uso
+
+### Agente (Node, en tu PC)
+
+```js
+import { startRemoteAgent } from '@dotrino/remote-agent/agent'
+
+const ra = await startRemoteAgent({
+  label: 'ia-agent',
+  proxyUrl: 'wss://proxy.dotrino.com',   // opcional
+  dir: '/home/yo/.local/share/dotrino-ia-agent', // opcional
+  quiet: false,
+  onSession (session) {
+    // sesión cifrada con un dispositivo cliente. session.device = su pubkey.
+    session.on('message', async (msg) => {
+      // msg es un payload de dominio: la app define la forma
+      if (msg.type === 'msg') {
+        const reply = await runYourDriver(msg.text) // Claude / OpenCode / ...
+        session.send({ type: 'done', text: reply })
+      }
+    })
+    session.on('close', () => {})
+  },
+  onRevoked () { console.log('me revocaron') }
+})
+// ra.machine, ra.machineId, ra.master, ra.close()
+```
+
+Enrolar la máquina (una vez, con el QR del vault):
+
+```js
+import { enroll } from '@dotrino/remote-agent/link'
+const link = await enroll({
+  qr, label: 'ia-agent',
+  onChallenge: ({ deviceId, code }) => console.log(`Tipeá en el vault: ${code}`)
+})
+```
+
+### Cliente (navegador, la PWA)
+
+```js
+import { RemoteAgentClient } from '@dotrino/remote-agent/client'
+import { listAgentsByLabel } from '@dotrino/remote-agent/discover'
+
+const agentes = await listAgentsByLabel(id, 'ia-agent')   // tarjetas en la UI
+const chat = new RemoteAgentClient(link, { agentPubkey: agentes[0].sub })
+await chat.connect()                                        // handshake E2E
+chat.on('message', (payload) => render(payload))
+chat.on('error', (e) => console.warn(e))
+chat.send({ type: 'msg', text: 'arreglá el bug en auth.js' })
+
+const online = await chat.ping()  // liveness sin abrir sesión
+```
+
+### `link` (la PWA lo obtiene del vault)
+
+Ver `dotrino-terminal/src/vault.js` (`getLink` / `getSelfLink`) como referencia: es
+el enlace del dispositivo (cert `P ← maestra`, `iss`, `proxy`), que se pasa al
+`RemoteAgentClient`. La terminal ya lo resuelve; cada app puede copiar ese patrón o
+extraerlo luego a este paquete.
+
+## Seguridad
+
+- **Autorización = estar vinculado al vault.** El agente solo atiende dispositivos
+  cuya cadena certifica la maestra pineada (`verifyChain` con `trustedIssuer`).
+- **Emparejamiento con código SAS** que no viaja (anti aprobación a ciegas / vault impostor).
+- **Anti-replay** en el handshake (`ts` ±5 min).
+- **Auto-borrado** del `link.json` al recibir un `revoke` firmado por la maestra.
+- **Auditoría** local de cada sesión abierta.
+- El relay de transporte (`proxy.dotrino.com`) **solo ve bytes cifrados**.
+
+## Dependencias
+
+- `@dotrino/identity` (capabilities: `verifyChain`, `signWithDevice`, `verifyDeviceSig`,
+  `pubkeyId`, `makeDeviceKey`, `verifyDelegation`, `makePairingCode`)
+- `@dotrino/proxy-client` (`WebSocketProxyClient`)
+- `ws` (shim de `WebSocket` en Node, lado agente)
+
+## Licencia
+
+MIT.

package/e2e.js

@@ -0,0 +1,75 @@
+/**
+ * e2e.js — canal cifrado punto a punto entre el dispositivo enlazado y un agente
+ * remoto del ecosistema Dotrino. Isomórfico: usa WebCrypto
+ * (`globalThis.crypto.subtle`), disponible tanto en el navegador (PWA) como en
+ * Node ≥ 18.
+ *
+ * NO reimplementa la identidad ni la firma del ecosistema: la AUTORIZACIÓN la da
+ * el vault (cert de dispositivo verificado con `@dotrino/identity/capabilities`
+ * → cadena hasta la maestra). Este módulo solo levanta un secreto de sesión
+ * efímero (ECDH P-256 → HKDF → AES-256-GCM) para que el relay de transporte
+ * (`proxy.dotrino.com`) vea únicamente texto cifrado. La identidad de las dos
+ * puntas ya la garantizan las firmas del vault que envuelven las claves efímeras.
+ *
+ * Fuente única para `@dotrino/remote-agent` (consumido por terminal, ia y futuras
+ * apps de agente remoto).
+ */
+
+const subtle = () => globalThis.crypto.subtle
+
+const b64 = {
+  enc (buf) {
+    const b = new Uint8Array(buf)
+    let s = ''
+    for (let i = 0; i < b.length; i++) s += String.fromCharCode(b[i])
+    return btoa(s)
+  },
+  dec (str) {
+    const bin = atob(str)
+    const out = new Uint8Array(bin.length)
+    for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i)
+    return out
+  }
+}
+
+/** Genera un par ECDH P-256 efímero. Devuelve la pub en raw (base64) + privada. */
+export async function makeEphemeral () {
+  const kp = await subtle().generateKey({ name: 'ECDH', namedCurve: 'P-256' }, false, ['deriveBits'])
+  const raw = await subtle().exportKey('raw', kp.publicKey)
+  return { privateKey: kp.privateKey, pub: b64.enc(raw) }
+}
+
+/**
+ * Deriva la clave AES-256-GCM de la sesión a partir de la privada propia y la
+ * pub efímera (base64 raw) del otro extremo. `salt` liga la clave a la sesión.
+ */
+export async function deriveKey (privateKey, otherPubB64, salt) {
+  const otherPub = await subtle().importKey(
+    'raw', b64.dec(otherPubB64), { name: 'ECDH', namedCurve: 'P-256' }, false, []
+  )
+  const bits = await subtle().deriveBits({ name: 'ECDH', public: otherPub }, privateKey, 256)
+  const hkdfKey = await subtle().importKey('raw', bits, 'HKDF', false, ['deriveKey'])
+  return subtle().deriveKey(
+    { name: 'HKDF', hash: 'SHA-256', salt: new TextEncoder().encode(salt), info: new TextEncoder().encode('dotrino-remote-agent-e2e') },
+    hkdfKey,
+    { name: 'AES-GCM', length: 256 },
+    false,
+    ['encrypt', 'decrypt']
+  )
+}
+
+/** Cifra un objeto JSON → sobre { iv, ct } (ambos base64). */
+export async function seal (key, obj) {
+  const iv = globalThis.crypto.getRandomValues(new Uint8Array(12))
+  const pt = new TextEncoder().encode(JSON.stringify(obj))
+  const ct = await subtle().encrypt({ name: 'AES-GCM', iv }, key, pt)
+  return { iv: b64.enc(iv), ct: b64.enc(ct) }
+}
+
+/** Descifra un sobre { iv, ct } → objeto JSON. Lanza si el tag GCM no valida. */
+export async function open (key, env) {
+  const pt = await subtle().decrypt({ name: 'AES-GCM', iv: b64.dec(env.iv) }, key, b64.dec(env.ct))
+  return JSON.parse(new TextDecoder().decode(pt))
+}
+
+export { b64 }

package/index.js

@@ -0,0 +1,16 @@
+/**
+ * @dotrino/remote-agent — middleware compartido para apps de agente remoto
+ * cifrado punto a punto del ecosistema Dotrino.
+ *
+ * Entry points (subpath exports en package.json):
+ *   '@dotrino/remote-agent'          → e2e + constantes de protocolo (isomórfico)
+ *   '@dotrino/remote-agent/agent'    → startRemoteAgent() (Node, lado del agente)
+ *   '@dotrino/remote-agent/client'   → RemoteAgentClient (navegador, lado PWA)
+ *   '@dotrino/remote-agent/link'     → enroll() emparejamiento SAS (Node)
+ *   '@dotrino/remote-agent/discover' → listAgentsByLabel() (navegador)
+ *
+ * El paquete NO sabe nada de PTY ni de IA: provee canal cifrado por sesión,
+ * despacho de payloads de dominio, emparejamiento con vault y revocación.
+ */
+export * from './e2e.js'
+export * from './protocol.js'

package/node-globals.js

@@ -0,0 +1,40 @@
+/**
+ * Instala los globals del navegador que los paquetes del ecosistema esperan
+ * cuando corren headless en Node: `WebSocket` (paquete `ws`) y un `localStorage`
+ * respaldado en archivo (lo usa `@dotrino/proxy-client` para su keypair de
+ * transporte estable). Mismo patrón que `dotrino-bots/src/core/node-globals.js`
+ * — NO se reimplementa nada, solo se inyecta el entorno.
+ *
+ * Solo para uso del lado del AGENTE (Node). No importar desde entrypoints de
+ * navegador.
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import WebSocket from 'ws'
+
+/** localStorage síncrono respaldado por un archivo JSON (solo lo que usan los paquetes). */
+export function fileLocalStorage (filePath) {
+  let data = {}
+  try { if (fs.existsSync(filePath)) data = JSON.parse(fs.readFileSync(filePath, 'utf8')) || {} } catch (_) {}
+  const flush = () => {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true })
+    fs.writeFileSync(filePath, JSON.stringify(data), { mode: 0o600 })
+  }
+  return {
+    getItem: (k) => (k in data ? data[k] : null),
+    setItem: (k, v) => { data[k] = String(v); flush() },
+    removeItem: (k) => { delete data[k]; flush() },
+    clear: () => { data = {}; flush() },
+    key: (i) => Object.keys(data)[i] ?? null,
+    get length () { return Object.keys(data).length }
+  }
+}
+
+let _installed = false
+export function installNodeGlobals (dir) {
+  if (_installed) return
+  if (typeof globalThis.WebSocket === 'undefined') globalThis.WebSocket = WebSocket
+  // Node ≥22 expone un `localStorage` no funcional sin flag → forzamos el shim.
+  globalThis.localStorage = fileLocalStorage(path.join(dir, 'transport.json'))
+  _installed = true
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@dotrino/remote-agent",
+  "version": "0.1.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",
+  "exports": {
+    ".": "./index.js",
+    "./agent": "./src/agent.js",
+    "./client": "./src/client.js",
+    "./link": "./src/link.js",
+    "./discover": "./src/discover.js"
+  },
+  "files": [
+    "index.js",
+    "e2e.js",
+    "protocol.js",
+    "node-globals.js",
+    "src"
+  ],
+  "scripts": {
+    "test": "node -e \"import('@dotrino/remote-agent').then(()=>console.log('ok'))\""
+  },
+  "dependencies": {
+    "@dotrino/identity": "0.17.0",
+    "@dotrino/proxy-client": "0.6.4",
+    "ws": "8.21.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/imdotrino/dotrino-remote-agent.git"
+  },
+  "homepage": "https://github.com/imdotrino/dotrino-remote-agent",
+  "keywords": ["dotrino", "remote", "agent", "e2e", "vault", "proxy", "p2p"]
+}

package/protocol.js

@@ -0,0 +1,34 @@
+/**
+ * protocol.js — constantes del protocolo de transporte de `@dotrino/remote-agent`.
+ *
+ * El protocolo tiene dos capas:
+ *  1. Envelope de transporte (visible al relay/proxy): `{ type, sid, env?, ... }`.
+ *     Usa los tipos `ra.*` de aquí abajo. El proxy solo ve el `type` + ciphertext.
+ *  2. Payload de dominio (dentro de `env`, cifrado AES-256-GCM): un objeto
+ *     arbitrario definido por CADA app (terminal envía `{type:'cmd',...}`,
+ *     ia envía `{type:'msg',...}`). El paquete no impone su forma.
+ *
+ * El handshake (HS/ACK) y la liveness (PING/PONG) son comunes; el despacho de
+ * payloads de dominio viaja por el tipo `DATA` genérico.
+ */
+
+export const HS = 'ra.hs'
+export const ACK = 'ra.hs.ack'
+export const DATA = 'ra.data'        // payload de dominio cifrado (cualquier dirección)
+export const PING = 'ra.ping'
+export const PONG = 'ra.pong'
+export const ERROR = 'ra.error'
+
+/** Mensajes del vault (refresco de dispositivos / revocación). */
+export const VMSG = {
+  DEVICES: 'vault.devices',
+  DEVICES_RESULT: 'vault.devices.result',
+  REVOKED: 'vault.revoked'
+}
+
+/** Scope del cert de dispositivo que autoriza a hablar con el agente. */
+export const SIGN_SCOPE = 'vault:sign'
+
+/** Vigencia de una sesión inactiva y refresco de la lista de revocados. */
+export const SESSION_TTL_MS = 30 * 60 * 1000
+export const REVOKE_REFRESH_MS = 5 * 60 * 1000

package/src/agent.js

@@ -0,0 +1,227 @@
+/**
+ * agent.js — lado del AGENTE (Node) de `@dotrino/remote-agent`.
+ *
+ * Abre sesiones cifradas punto a punto SOLO para dispositivos enlazados al mismo
+ * vault. Puede correr en CUALQUIER máquina: se enrola con el vault como un
+ * dispositivo más (ver link.js), así que NO necesita la maestra — solo su propia
+ * sub-clave `D` + `cert` y la pública maestra pineada (`iss`).
+ *
+ * Autorización = el vault. Cada `ra.hs` llega firmado por la `D` del cliente con su
+ * `cert`; el agente verifica la cadena `D_cliente ← maestra` (misma maestra que la
+ * suya) con `verifyChain`. Ambas puntas son peers certificados por el mismo vault;
+ * ninguna tiene la clave maestra. El ack lo firma el agente con SU `D` y adjunta su
+ * `cert`, para que el cliente compruebe que habla con un agente que el vault certificó
+ * (anti-MITM del relay).
+ *
+ * Transporte = el proxy (`@dotrino/proxy-client`): el agente se identifica bajo SU
+ * pubkey y el cliente lo direcciona por ella. Revocación: refresca la lista del vault
+ * por el proxy; si está offline, usa la última cacheada + el TTL del cert acota el
+ * riesgo. Los payloads de dominio viajan cifrados E2E (../e2e.js) dentro del tipo
+ * `DATA` genérico — el agente NO sabe nada de PTY ni de IA.
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { verifyChain, signWithDevice, verifyDeviceSig, pubkeyId } from '@dotrino/identity/capabilities'
+import { installNodeGlobals } from '../node-globals.js'
+import { makeEphemeral, deriveKey, seal, open } from '../e2e.js'
+import { HS, ACK, DATA, PING, PONG, ERROR, VMSG, SIGN_SCOPE, SESSION_TTL_MS, REVOKE_REFRESH_MS } from '../protocol.js'
+import { loadLink, dataDir } from './link.js'
+
+/** Sesión cifrada con un dispositivo cliente. La app recibe esto en `onSession`. */
+class AgentSession {
+  constructor ({ sid, key, from, device, send }) {
+    this.sid = sid
+    this.key = key
+    this.from = from                  // token del cliente en el proxy
+    this.device = device              // pubkey del dispositivo cliente
+    this._send = send                 // (to, obj) => void
+    this._h = { message: [], close: [] }
+    this._closed = false
+  }
+
+  /** Envía un payload de dominio cifrado al cliente. */
+  async send (payload) {
+    if (this._closed) return
+    const env = await seal(this.key, payload).catch(() => null)
+    if (env) this._send(this.from, { type: DATA, sid: this.sid, env })
+  }
+
+  on (ev, cb) { this._h[ev]?.push(cb); return this }
+
+  async _ingest (env) {
+    let msg
+    try { msg = await open(this.key, env) } catch { return }
+    for (const h of this._h.message) { try { h(msg) } catch (_) {} }
+  }
+
+  close () {
+    if (this._closed) return
+    this._closed = true
+    for (const h of this._h.close) { try { h() } catch (_) {} }
+  }
+}
+
+/**
+ * Arranca el agente. Devuelve `{ machine, machineId, master, close }`.
+ *
+ * @param {object} opts
+ * @param {string} [opts.label]       label del dispositivo (para logging; el real vive en link.json).
+ * @param {string} [opts.proxyUrl]    default wss://proxy.dotrino.com.
+ * @param {string} [opts.dir]         dir del enlace (default dataDir()).
+ * @param {object} [opts.link]        enlace ya cargado (override de dir).
+ * @param {(session:AgentSession)=>void} [opts.onSession]  cada handshake exitoso abre una sesión.
+ * @param {()=>void} [opts.onRevoked] se llamó al auto-borrarse por revocación.
+ * @param {()=>void} [opts.onReady]   agente listo y escuchando.
+ * @param {boolean} [opts.quiet]      sin logs.
+ */
+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.')
+  }
+  const master = link.iss
+  const myPub = link.device.publickey
+  const myId = (await pubkeyId(myPub)).slice(0, 8).toUpperCase().replace(/(.{4})(.{4})/, '$1-$2')
+
+  installNodeGlobals(dir)
+
+  const { getWebSocketProxyClient } = await import('@dotrino/proxy-client')
+  const proxyUrl = opts.proxyUrl || process.env.PROXY_URL || link.proxy || 'wss://proxy.dotrino.com'
+  const client = getWebSocketProxyClient({
+    url: proxyUrl, enableWebRTC: false, autoReconnect: true,
+    maxReconnectAttempts: 100000, reconnectDelay: 4000
+  })
+  await client.connect()
+
+  // Identificarse bajo la pubkey de ESTA máquina (firmado con su D).
+  const identify = async () => {
+    if (!client.token) return
+    const data = { op: 'identify', publickey: myPub, token: client.token, ts: Date.now() }
+    const { signature } = await signWithDevice({ privateJwk: link.device.privateJwk, data })
+    await client.identify({ data, signature })
+  }
+  await identify()
+  client.on('token', () => { identify().catch(() => {}) })
+
+  // Bitácora persistente (sessions.log, JSONL): qué dispositivo abrió sesión y cuándo
+  // — auditoría local si un dispositivo tuyo cae en malas manos.
+  const sessionsLog = path.join(dir, 'sessions.log')
+  const audit = (op, info = {}) => {
+    try { fs.appendFileSync(sessionsLog, JSON.stringify({ ts: Date.now(), op, ...info }) + '\n') } catch (_) {}
+  }
+
+  const send = (to, obj) => { try { client.send(to, obj) } catch (e) { if (!opts.quiet) console.error('[remote-agent] send:', e.message) } }
+
+  // --- Revocación: refrescar la lista del vault por el proxy (best-effort) ---
+  let revokedSet = new Set()
+  async function refreshRevocations () {
+    try {
+      const data = { op: 'devices', publickey: myPub, ts: Date.now() }
+      const { signature } = await signWithDevice({ privateJwk: link.device.privateJwk, data })
+      const res = await new Promise((resolve, reject) => {
+        const off = client.on('message', (_f, p) => {
+          if (p?.type === VMSG.DEVICES_RESULT) { off(); resolve(p) }
+          else if (p?.type === 'vault.error') { off(); reject(new Error(p.error)) }
+        })
+        setTimeout(() => { off(); reject(new Error('timeout')) }, 15000)
+        client.sendByPubkey(master, { type: VMSG.DEVICES, data, signature, cert: link.cert })
+      })
+      revokedSet = new Set((res.revoked || []).map((r) => r.nonce || r))
+    } catch (e) {
+      if (!opts.quiet) console.error('[remote-agent] no pude refrescar revocaciones (uso la cache):', e.message)
+    }
+  }
+  refreshRevocations()
+  const revTimer = setInterval(refreshRevocations, REVOKE_REFRESH_MS); revTimer.unref?.()
+
+  // sid -> AgentSession
+  const sessions = new Map()
+  const sweeper = setInterval(() => {
+    const now = Date.now()
+    for (const [sid, s] of sessions) {
+      if (now > s._exp) { s.close(); sessions.delete(sid); audit('session-expire', { sid: sid.slice(0, 8) }) }
+    }
+  }, 60 * 1000); sweeper.unref?.()
+
+  async function handleHandshake (from, p) {
+    const { data, signature, cert } = p
+    if (!data || !signature || !cert) return send(from, { type: ERROR, error: 'handshake incompleto' })
+    // 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)' })
+    }
+    const chk = await verifyChain({ data, signature, cert, expectedScope: SIGN_SCOPE, trustedIssuer: master, revoked: revokedSet })
+    if (!chk.ok) return send(from, { type: ERROR, error: 'no autorizado: ' + chk.reason })
+    if (data.op !== HS || typeof data.eph !== 'string') return send(from, { type: ERROR, error: 'handshake inválido' })
+
+    const eph = await makeEphemeral()
+    const sid = [...crypto.getRandomValues(new Uint8Array(16))].map((x) => x.toString(16).padStart(2, '0')).join('')
+    const key = await deriveKey(eph.privateKey, data.eph, sid)
+    // Ack firmado con la D de ESTA máquina + su cert: el cliente verifica la cadena
+    // a la maestra y que la pub efímera viene de un agente certificado. `publickey`
+    // va DENTRO del dato firmado (verifyChain lo exige: firma contra data.publickey
+    // y cert.sub === data.publickey).
+    const ack = { op: ACK, sid, seph: eph.pub, ceph: data.eph, machine: myPub, publickey: myPub, ts: Date.now() }
+    const { signature: ackSig } = await signWithDevice({ privateJwk: link.device.privateJwk, data: ack })
+
+    const session = new AgentSession({ sid, key, from, device: chk.device, send })
+    session._exp = Date.now() + SESSION_TTL_MS
+    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.onSession) { try { opts.onSession(session) } catch (e) { if (!opts.quiet) console.error('[remote-agent] onSession:', e.message) } }
+  }
+
+  function handleData (from, p) {
+    const s = sessions.get(p.sid)
+    if (!s) return send(from, { type: ERROR, error: 'sesión desconocida o expirada' })
+    s._exp = Date.now() + SESSION_TTL_MS
+    s.from = from
+    s._ingest(p.env).catch(() => send(from, { type: ERROR, error: 'sobre inválido' }))
+  }
+
+  const stop = () => {
+    clearInterval(revTimer); clearInterval(sweeper)
+    for (const s of sessions.values()) s.close()
+    try { client.close() } catch {}
+  }
+
+  // AUTO-BORRADO al ser REVOCADA: la bóveda envía un REVOKED FIRMADO por la maestra
+  // dirigido a ESTA máquina (al revocar, o cuando reaparece). Solo nos borramos si la
+  // firma valida y el body es para nuestra pubkey → un proxy/peer malicioso NO puede
+  // borrarnos con un mensaje falso (cierra el wipe-DoS). Borra el enlace (link.json) y
+  // detiene el agente.
+  async function handleRevoked (p) {
+    const b = p?.body
+    if (!b || b.op !== 'revoke' || b.sub !== myPub) return
+    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.')
+    try { fs.rmSync(path.join(dir, 'link.json'), { force: true }) } catch (_) {}
+    stop()
+    if (opts.onRevoked) { try { opts.onRevoked() } catch (_) {} }
+  }
+
+  client.on('message', (from, payload) => {
+    if (!payload || typeof payload !== 'object') return
+    if (payload.type === HS) handleHandshake(from, payload).catch((e) => send(from, { type: ERROR, error: e.message }))
+    else if (payload.type === DATA) handleData(from, payload)
+    // Sonda de presencia (liveness): el cliente hace ping y respondemos pong con el
+    // mismo nonce → así la app sabe que el agente está online (sin abrir sesión).
+    else if (payload.type === PING) send(from, { type: PONG, n: payload.n })
+    else if (payload.type === VMSG.REVOKED) handleRevoked(payload).catch(() => {})
+  })
+
+  if (!opts.quiet) {
+    console.log(`[remote-agent] agente activo · máquina ${myId} · vault ${(await pubkeyId(master)).slice(0, 16)} · proxy ${proxyUrl}`)
+  }
+  if (opts.onReady) { try { opts.onReady({ machine: myPub, machineId: myId, master }) } catch (_) {} }
+
+  return { machine: myPub, machineId: myId, master, close: stop }
+}
+
+export default { startRemoteAgent }

package/src/client.js

@@ -0,0 +1,152 @@
+/**
+ * client.js — lado del CLIENTE (navegador/PWA) de `@dotrino/remote-agent`.
+ *
+ * Habla con un agente remoto por el proxy del ecosistema (`@dotrino/proxy-client`).
+ * El agente es otro dispositivo enrolado en el MISMO vault: lo direccionamos por SU
+ * pubkey (`agentPubkey`) y verificamos que su `cert` encadena a la maestra que este
+ * dispositivo vio al enlazar. Ambas puntas son peers certificados por el vault;
+ * ninguna tiene la clave maestra.
+ *
+ * La firma de este lado la hace el PILAR de identidad (`id.signData`, dentro del
+ * iframe id.dotrino.com): la clave del dispositivo es la identidad del navegador y
+ * su cert (`P ← maestra`) viene del emparejamiento estándar del ecosistema
+ * (profile.dotrino.com/#vault). Nada de claves privadas en la app.
+ *
+ * Handshake: firmamos la autorización → el agente responde un ack firmado con SU
+ * `D` + su `cert` → verificamos la cadena a la maestra pineada (anti-MITM del
+ * relay) → levantamos el canal cifrado (ECDH → AES-GCM).
+ *
+ * Una vez conectado, `send(payload)` envía un objeto de dominio arbitrario (la app
+ * define la forma: terminal pasa `{type:'cmd',...}`, ia pasa `{type:'msg',...}`) y
+ * `on('message', cb)` recibe los payloads del agente, ya descifrados.
+ */
+import { verifyChain } from '@dotrino/identity/capabilities'
+import { makeEphemeral, deriveKey, seal, open } from '../e2e.js'
+import { HS, ACK, DATA, PING, PONG, ERROR } from '../protocol.js'
+
+export class RemoteAgentClient {
+  /**
+   * @param {{ id:object, cert:object, iss:string, proxy?:string, mode?:string }} link
+   *   enlace del vault (modo vault) o de @dotrino/vault (modo self: el dispositivo
+   *   es su propio vault; `cert` es el self-cert `P ← P` e `iss` es la propia P).
+   * @param {object} opts
+   * @param {string} opts.agentPubkey dirección (pubkey) del agente destino.
+   * @param {string} [opts.proxyUrl]  override del proxy del enlace.
+   */
+  constructor (link, { agentPubkey, proxyUrl } = {}) {
+    this.link = link                                  // { id, cert, iss, proxy, mode? }
+    this.agentPubkey = agentPubkey                    // pubkey del agente destino
+    this.proxyUrl = proxyUrl || link.proxy || 'wss://proxy.dotrino.com'
+    this.client = null
+    this.key = null
+    this.sid = null
+    this._h = { message: [], error: [] }
+  }
+
+  /** Suscribe a eventos. Devuelve un `off()` para desuscribir. Eventos: message, error. */
+  on (ev, cb) {
+    if (!this._h[ev]) this._h[ev] = []
+    this._h[ev].push(cb)
+    return () => { this._h[ev] = this._h[ev].filter((f) => f !== cb) }
+  }
+
+  _emit (ev, ...args) { for (const h of (this._h[ev] || [])) { try { h(...args) } catch (_) {} } }
+
+  async _identify () {
+    // En modo self NO identificamos esta conexión como P: el proxy enruta por token
+    // las respuestas del agente (no por pubkey), y así no recibimos el fan-out de
+    // mensajes dirigidos a P (que atiende el listener de enrolamiento). La
+    // autorización la da el vault/self-cert que va firmado en el handshake.
+    if (this.link.mode === 'self') return
+    if (!this.client.token) return
+    // Patrón estándar del ecosistema (messenger): identify firmado por id.signData
+    // + cert del vault → el proxy enruta también lo dirigido a la maestra.
+    const { id, cert } = this.link
+    const publickey = id.me?.publickey
+    if (!publickey) return
+    const data = { op: 'identify', publickey, token: this.client.token, ts: Date.now() }
+    const { signature } = await id.signData(data)
+    await this.client.identify({ data, signature, cert })
+  }
+
+  async connect () {
+    if (!this.agentPubkey) throw new Error('falta la dirección del agente destino')
+    const { WebSocketProxyClient } = await import('@dotrino/proxy-client')
+    this.client = new WebSocketProxyClient({ url: this.proxyUrl, enableWebRTC: false, autoReconnect: true })
+    await this.client.connect()
+    await this._identify()
+    if (this.link.mode !== 'self') {
+      this.client.on('token', () => { this._identify().catch(() => {}) })
+    }
+
+    this.client.on('message', async (_from, p) => {
+      if (!p || typeof p !== 'object') return
+      if (p.type === DATA && p.sid === this.sid) {
+        try { const m = await open(this.key, p.env); this._emit('message', m) } catch {}
+      } else if (p.type === ERROR) {
+        this._emit('error', new Error(p.error))
+      }
+    })
+
+    const eph = await makeEphemeral()
+    // El self-cert P←P del modo self puede vencerse (24 h): refrescarlo si hace falta.
+    let cert = this.link.cert
+    if (this.link.mode === 'self' && this.link.getSelfCert) {
+      cert = await this.link.getSelfCert()
+    }
+    // `publickey` va DENTRO del dato firmado: verifyChain verifica la firma contra
+    // data.publickey y exige cert.sub === data.publickey.
+    const data = { op: HS, eph: eph.pub, publickey: this.link.id.me?.publickey, ts: Date.now() }
+    const { signature } = await this.link.id.signData(data)
+
+    // El ACK se correlaciona por la clave efímera PROPIA (ceph === eph.pub): así
+    // varias sesiones simultáneas (varios RemoteAgentClient sobre la misma pubkey)
+    // no se roban el ACK de la otra.
+    const acked = new Promise((resolve, reject) => {
+      const off = this.client.on('message', (_from, p) => {
+        if (!p || typeof p !== 'object') return
+        if (p.type === ACK && p.ack && p.ack.ceph === eph.pub) { off(); resolve(p) }
+        else if (p.type === ERROR) { off(); reject(new Error(p.error)) }
+      })
+      setTimeout(() => { off(); reject(new Error('el agente no respondió (¿está corriendo allí?)')) }, 20000)
+    })
+    this.client.sendByPubkey(this.agentPubkey, { type: HS, data, signature, cert })
+    const res = await acked
+
+    // El ack debe: (1) encadenar a NUESTRA maestra, (2) estar firmado por el agente
+    // que apuntamos, (3) atar nuestra pub efímera y el sid.
+    const chk = await verifyChain({ data: res.ack, signature: res.signature, cert: res.cert, trustedIssuer: this.link.iss })
+    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')
+
+    this.sid = res.sid
+    this.key = await deriveKey(eph.privateKey, res.ack.seph, res.sid)
+    return this
+  }
+
+  /** Envía un payload de dominio cifrado al agente. */
+  async send (payload) {
+    const env = await seal(this.key, payload)
+    this.client.sendByPubkey(this.agentPubkey, { type: DATA, sid: this.sid, env })
+  }
+
+  /** Sonda de presencia (liveness) sin abrir sesión. Devuelve true si responde. */
+  async ping ({ timeoutMs = 4000 } = {}) {
+    const n = crypto.getRandomValues(new Uint8Array(8)).join('')
+    const got = new Promise((resolve) => {
+      const off = this.client.on('message', (_f, p) => {
+        if (p?.type === PONG && p.n === n) { off(); resolve(true) }
+      })
+      setTimeout(() => { off(); resolve(false) }, timeoutMs)
+    })
+    this.client.sendByPubkey(this.agentPubkey, { type: PING, n })
+    return got
+  }
+
+  async close () {
+    try { this.client?.close() } catch {}
+  }
+}
+
+export default { RemoteAgentClient }

package/src/discover.js

@@ -0,0 +1,33 @@
+/**
+ * discover.js — autodescubrimiento de agentes vinculados al vault (lado cliente).
+ *
+ * Tus agentes = los dispositivos enrolados en TU vault (`vault.devices` trae la
+ * pubkey `sub` de cada uno = su dirección en el proxy). Sin pegar nada: filtrás por
+ * label y abrís una sesión con el que quieras.
+ *
+ * Si pasás `label` (p. ej. `'ia-agent'`), lista solo los dispositivos con ESE label
+ * exacto. Si NO pasás `label`, mantiene el comportamiento legacy de terminal: lista
+ * cualquier dispositivo que tenga un label y no sea `'cli'` (los navegadores
+ * enrolados quedan con label `'cli'` y no atienden agentes).
+ */
+
+/**
+ * @param {object} id   instancia de Identity (del vault) ya conectada.
+ * @param {string} [label]  filtrar por label exacto (p. ej. 'ia-agent'). Omitir = todos los no-cli.
+ * @returns {Promise<Array<{sub:string,label:string,deviceId:string,exp?:number}>>}
+ *   dedup por pubkey (renovaciones/re-emparejes → el cert más nuevo).
+ */
+export async function listAgentsByLabel (id, label) {
+  const { devices } = await id.listVaultDevices()
+  const mine = id.me?.publickey
+  const now = Date.now()
+  const bySub = new Map()
+  for (const d of devices || []) {
+    if (!d.sub || d.sub === mine || (d.exp && d.exp <= now)) continue
+    if (label ? d.label !== label : (!d.label || d.label === 'cli')) continue
+    if (!bySub.has(d.sub) || (d.exp || 0) > (bySub.get(d.sub).exp || 0)) bySub.set(d.sub, d)
+  }
+  return [...bySub.values()]
+}
+
+export default { listAgentsByLabel }

package/src/link.js

@@ -0,0 +1,113 @@
+/**
+ * link.js — enrola ESTA máquina como un dispositivo del vault (mismo flujo
+ * endurecido que usa el navegador / `dotrino-vault/src/client.js#enroll`). Es lo
+ * que vuelve al agente INDEPENDIENTE de la máquina del vault: guarda su propia
+ * sub-clave `D` + `cert` (cadena `D ← maestra`); la maestra NUNCA vive aquí, solo
+ * su pública pineada (`iss`).
+ *
+ * Persistencia en un directorio propio (por defecto
+ * `~/.local/share/<name>`, override `DOTRINO_REMOTE_AGENT_DIR` o `dir` explícito):
+ * NO comparte carpeta con el vault, así el agente puede correr en otro host.
+ *
+ * El `label` (p. ej. `terminal-agent`, `ia-agent`) viaja en el cert y lo usa el
+ * cliente para FILTRAR qué dispositivos son agentes del tipo que busca
+ * (listAgentsByLabel).
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import os from 'node:os'
+import {
+  makeDeviceKey, signWithDevice, verifyDelegation, makePairingCode, pubkeyId
+} from '@dotrino/identity/capabilities'
+import { installNodeGlobals } from '../node-globals.js'
+
+const MSG = {
+  ENROLL: 'vault.enroll',
+  ENROLL_CHALLENGE: 'vault.enroll.challenge',
+  ENROLLED: 'vault.enrolled',
+  ERROR: 'vault.error'
+}
+
+/** Directorio de datos del agente. `name` define el subdir (p. ej. 'dotrino-ia-agent'). */
+export function dataDir (name = 'dotrino-remote-agent') {
+  if (process.env.DOTRINO_REMOTE_AGENT_DIR) return process.env.DOTRINO_REMOTE_AGENT_DIR
+  const base = process.env.XDG_DATA_HOME || path.join(os.homedir(), '.local', 'share')
+  return path.join(base, name)
+}
+
+const linkPath = (dir) => path.join(dir, 'link.json')
+
+export function loadLink (dir = dataDir()) {
+  try { return JSON.parse(fs.readFileSync(linkPath(dir), 'utf8')) } catch { return null }
+}
+
+function saveLink (dir, link) {
+  fs.mkdirSync(dir, { recursive: true })
+  fs.writeFileSync(linkPath(dir), JSON.stringify(link, null, 2), { mode: 0o600 })
+}
+
+export function parseQr (text) {
+  const qr = JSON.parse(String(text).trim())
+  if (!qr?.iss || !qr?.proxy || !qr?.token || !qr?.sn) throw new Error('QR inválido (v2): faltan iss/proxy/token/sn')
+  return qr
+}
+
+async function freshClient (proxyUrl, dir) {
+  installNodeGlobals(dir)
+  const { WebSocketProxyClient } = await import('@dotrino/proxy-client')
+  const client = new WebSocketProxyClient({ url: proxyUrl, enableWebRTC: false, autoReconnect: false })
+  await client.connect()
+  return client
+}
+
+/**
+ * Enrola esta máquina contra el vault del QR. Devuelve y persiste
+ * `{ device, cert, iss, proxy, label, at }`.
+ *
+ * @param {object} args
+ * @param {object} args.qr           QR parseado del vault ({ iss, proxy, token, sn }).
+ * @param {string} [args.label='remote-agent']  label del dispositivo (lo filtra el cliente).
+ * @param {string} [args.dir=dataDir()]         dónde persistir el enlace.
+ * @param {(c:{deviceId:string,code:string})=>void} [args.onChallenge]  mostrar el CÓDIGO para
+ *        que un humano lo TIPEE en la bóveda al aprobar (el código NO viaja de aquí).
+ * @param {number} [args.timeoutMs=180000]
+ */
+export async function enroll ({ qr, label = 'remote-agent', dir = dataDir(), onChallenge, timeoutMs = 180000 } = {}) {
+  const client = await freshClient(qr.proxy, dir)
+  try {
+    const device = await makeDeviceKey({ label })
+    const deviceId = (await pubkeyId(device.publickey)).slice(0, 8).toUpperCase().replace(/(.{4})(.{4})/, '$1-$2')
+    // Código de emparejamiento ALEATORIO (un secreto, NO derivable de valores públicos):
+    // lo mostramos y NO lo enviamos. La bóveda lo aprende solo cuando un humano lo tipea
+    // y nos lo ECHA de vuelta → así aprobar exige TENER esta máquina (de aquí sale el código).
+    const code = makePairingCode()
+    const data = { op: 'enroll', dpub: device.publickey, token: qr.token, sn: qr.sn, label, ts: Date.now() }
+    const { signature } = await signWithDevice({ privateJwk: device.privateJwk, data })
+
+    const done = new Promise((resolve, reject) => {
+      const off = client.on('message', (_from, p) => {
+        if (!p || typeof p !== 'object') return
+        if (p.type === MSG.ENROLL_CHALLENGE) onChallenge?.({ deviceId, code })
+        // Aceptamos SOLO si el código echado coincide con el que generamos (anti
+        // aprobación-a-ciegas / bóveda impostora). Un eco distinto se IGNORA y seguimos
+        // esperando la aprobación correcta (o el timeout).
+        else if (p.type === MSG.ENROLLED) { if (String(p.code || '').trim() === code) { cleanup(); resolve(p) } }
+        else if (p.type === MSG.ERROR) { cleanup(); reject(new Error(p.error)) }
+      })
+      const t = setTimeout(() => { cleanup(); reject(new Error('timeout esperando la aprobación en el vault')) }, timeoutMs)
+      const cleanup = () => { off(); clearTimeout(t) }
+    })
+    client.sendByPubkey(qr.iss, { type: MSG.ENROLL, data, signature })
+    const res = await done
+
+    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 otra maestra (posible proxy malicioso)')
+
+    const link = { device, cert: res.cert, iss: qr.iss, proxy: qr.proxy, label, at: Date.now() }
+    saveLink(dir, link)
+    return link
+  } finally { client.close() }
+}
+
+export default { dataDir, loadLink, parseQr, enroll }