@dotrino/remote-agent 0.4.1 → 0.5.0

package/README.md

@@ -33,7 +33,7 @@ Provee lo común — y **solo** eso:
 | `@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/link` | Node | `enroll`, `loadLink`, `saveLink`, `dataDir`, `parseQr`, `identityFromLink`, `clientLink` |
 | `@dotrino/remote-agent/discover` | navegador | `listAgentsByLabel` |
 
 ## Uso
@@ -68,14 +68,40 @@ const ra = await startRemoteAgent({
 //   `identify`, una segunda identidad de transporte y una segunda cola.
 ```
 
-Enrolar la máquina (una vez, con el QR del vault):
+Enrolar la máquina (una vez, con la invitación del vault — URL del QR, código compacto
+o JSON, da igual: la entiende `enrollWithVault` de `@dotrino/vault`, que es el único
+enrolamiento headless del ecosistema y el que esto reusa):
 
 ```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}`)
+  onChallenge: ({ deviceId, code }) => console.log(`Escribe en el vault: dotrino-vault approve ${code}`)
 })
+// link = { device, enc, cert, iss, proxy, label, ns?, at } — `enc` es la llave de
+// CIFRADO: con ella la bóveda puede sellarle secretos a este agente.
+```
+
+**Lo que puede hacer el agente lo dice la invitación, no este paquete**: no hay tipos
+de agente, hay permisos (`dotrino-vault pair --scope sign,read,store,secrets:<ns>`). Un
+bot que publica en las apps y lee solo su cajón de secretos se empareja con
+`pair --service <ns> --scope sign`, y se enrola con `enroll({ qr, ns: '<ns>' })` (el `ns`
+hace que se exija ese permiso en el cert y queda en el enlace). Sus secretos los pide
+con `fetchSecrets`/`waitForSecrets` de `@dotrino/vault/service` pasando la identidad por
+parámetros (`{ ns, proxyUrl: link.proxy, masterPubkey: link.iss, device, cert, enc }`).
+
+### Un agente como CLIENTE de otro agente (Node)
+
+Un agente Node también puede hablar con otro agente —un bot que guarda en el node de
+contenido, por ejemplo— con el mismo código que usa una app: `clientLink(link)` arma el
+`{ id, cert, iss, proxy }` que esperan `RemoteAgentClient` y `ContentClient`, con un `id`
+que firma con la llave del aparato (`identityFromLink`).
+
+```js
+import { loadLink, clientLink } from '@dotrino/remote-agent/link'
+import { ContentClient } from '@dotrino/content-client'
+const cc = await ContentClient.connect({ link: clientLink(loadLink()) })
+const ref = await cc.put(bytes, { encrypt: false, acl: 'public', mime: 'application/json' })
 ```
 
 ### Cliente (navegador, la PWA)
@@ -116,6 +142,7 @@ extraerlo luego a este paquete.
 - `@dotrino/identity` (capabilities: `verifyChain`, `signWithDevice`, `verifyDeviceSig`,
   `pubkeyId`, `makeDeviceKey`, `verifyDelegation`, `makePairingCode`)
 - `@dotrino/proxy-client` (`WebSocketProxyClient`)
+- `@dotrino/vault` (`enrollWithVault`: el enrolamiento headless del ecosistema; `parseInvite`)
 - `ws` (shim de `WebSocket` en Node, lado agente)
 
 ## Licencia

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotrino/remote-agent",
-  "version": "0.4.1",
+  "version": "0.5.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",
@@ -23,8 +23,9 @@
     "type-check": "tsc --noEmit"
   },
   "dependencies": {
-    "@dotrino/identity": "0.53.0",
+    "@dotrino/identity": "0.56.0",
     "@dotrino/proxy-client": "0.10.1",
+    "@dotrino/vault": "0.30.0",
     "ws": "8.21.0"
   },
   "engines": {

package/src/link.js

@@ -16,19 +16,10 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import os from 'node:os'
-import {
-  makeDeviceKey, signWithDevice, verifyDelegation, makePairingCode, commitCode, pubkeyId
-} from '@dotrino/identity/capabilities'
+import { signWithDevice, pubkeyId } from '@dotrino/identity/capabilities'
+import { requestDevices } from '@dotrino/identity/vault/remote.js'
 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')
@@ -37,6 +28,7 @@ export function dataDir (name = 'dotrino-remote-agent') {
 
 const linkPath = (dir) => path.join(dir, 'link.json')
 
+/** Lee el enlace persistido (o null si no está enrolado). */
 export function loadLink (dir = dataDir()) {
   try { return JSON.parse(fs.readFileSync(linkPath(dir), 'utf8')) } catch { return null }
 }
@@ -47,91 +39,97 @@ export function saveLink (dir, link) {
   fs.writeFileSync(linkPath(dir), JSON.stringify(link, null, 2), { mode: 0o600 })
 }
 
-export function parseQr (text) {
-  const qr = normalizeQr(text)
-  if (!qr?.iss || !qr?.proxy || !qr?.token || !qr?.sn) throw new Error('QR inválido (v2): faltan iss/proxy/token/sn')
+/**
+ * Parsea una invitación de la bóveda a objeto. Acepta TODAS las formas que imprime
+ * `dotrino-vault pair` (URL del QR, código compacto, JSON, base64url): es el mismo
+ * `parseInvite` del ecosistema. `enroll` ya lo hace solo; esto es para quien quiera
+ * mirar la invitación antes (qué bóveda, qué proxy) sin enrolar.
+ */
+export async function parseQr (text) {
+  const { parseInvite } = await import('@dotrino/vault/invite')
+  const qr = parseInvite(String(text ?? '').trim())
+  if (!qr?.sn || !(qr.iss || qr.conn)) throw new Error('invalid invitation: paste the output of `dotrino-vault pair`')
   return qr
 }
 
-// Acepta el código de emparejamiento en 3 formas: JSON crudo, base64url del JSON, o
-// URL "profile.dotrino.com/#vault=<base64url>". El base64url es el formato canónico
-// del ecosistema (no expone la estructura en texto plano).
+/** base64url → utf8 (lo usan los tests y algún QR viejo). */
 export function b64urlDecode (s) {
   const b64 = String(s).replace(/-/g, '+').replace(/_/g, '/')
   return Buffer.from(b64, 'base64').toString('utf8')
 }
 
-function normalizeQr (text) {
-  let s = String(text ?? '').trim()
-  const i = s.indexOf('#vault=')
-  if (i >= 0) s = s.slice(i + 7).trim()        // profile.dotrino.com/#vault=…
-  if (!s.startsWith('{')) {                     // no es JSON → probar base64url
-    const json = b64urlDecode(s)
-    if (json && json.trim().startsWith('{')) s = json
-    else throw new Error('código de emparejamiento inválido (se espera JSON o base64url)')
-  }
-  return JSON.parse(s)
-}
-
-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 }`.
+ * Enrola ESTA máquina contra la bóveda y persiste el enlace
+ * `{ device, enc, cert, iss, proxy, label, ns?, at }`.
+ *
+ * El enrolamiento en sí es el del ecosistema —`enrollWithVault` de `@dotrino/vault`—
+ * y no se duplica aquí: entiende cualquier invitación, crea las DOS llaves del aparato
+ * (firma y **cifrado**: sin la segunda la bóveda no puede sellarle secretos) y
+ * verifica el cert. Este módulo solo decide dónde vive.
+ *
+ * Lo que puede hacer el aparato lo decide la invitación (`dotrino-vault pair --scope …`):
+ * no hay tipos de agente, hay permisos. Un bot que publica y lee su cajón se empareja
+ * con `pair --service <ns> --scope sign`; pásale `ns` para que el enlace lo recuerde y
+ * exija ese permiso en el cert.
  *
  * @param {object} args
- * @param {object} args.qr           QR parseado del vault ({ iss, proxy, token, sn }).
+ * @param {object|string} args.qr     La invitación, en cualquiera de sus formas.
  * @param {string} [args.label='remote-agent']  label del dispositivo (lo filtra el cliente).
  * @param {string} [args.dir=dataDir()]         dónde persistir el enlace.
+ * @param {string} [args.ns]                    cajón de secretos que lee este agente (si lo hay).
  * @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()
-    // 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, sn: qr.sn, commit, 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
+export async function enroll ({ qr, label = 'remote-agent', dir = dataDir(), ns = null, onChallenge, timeoutMs = 180000 } = {}) {
+  installNodeGlobals(dir)
+  const { enrollWithVault } = await import('@dotrino/vault/service')
+  const res = await enrollWithVault({
+    qr,
+    label,
+    expectedScope: ns ? 'vault:secrets:' + ns : null,
+    onCode: onChallenge,
+    approveTimeoutMs: timeoutMs
+  })
+  const link = { device: res.device, enc: res.enc, cert: res.cert, iss: res.iss, proxy: res.proxy, label, ...(ns ? { ns } : {}), at: Date.now() }
+  saveLink(dir, link)
+  return link
+}
 
-    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)')
+/**
+ * La IDENTIDAD de un agente a partir de su enlace: lo que un cliente del ecosistema
+ * espera como `link.id` (`RemoteAgentClient`, `ContentClient`, `listAgentsByLabel`) —
+ * `me.publickey`, `signData`, `listVaultDevices`, `getVaultCert`, `vaultStatus`— pero
+ * firmando con la llave del aparato en vez de con el pilar del navegador. Así un agente
+ * Node puede ser CLIENTE de otro agente (un bot que guarda en el node de contenido)
+ * con el mismo código que usa una app.
+ *
+ * @param {object} link  el enlace (`loadLink(dir)`).
+ * @param {{ dir?: string }} [opts]  dir para los globals de Node (localStorage del proxy-client).
+ */
+export function identityFromLink (link, { dir = dataDir() } = {}) {
+  if (!link?.device?.privateJwk || !link?.cert || !link?.iss) throw new Error('invalid link: device/cert/iss required')
+  installNodeGlobals(dir)
+  const device = link.device
+  const proxy = link.proxy || 'wss://proxy.dotrino.com'
+  return {
+    me: { publickey: device.publickey },
+    async signData (data) {
+      return signWithDevice({ privateJwk: device.privateJwk, publickey: device.publickey, data })
+    },
+    async getVaultCert () { return { cert: link.cert } },
+    async vaultStatus () {
+      return { paired: true, master: link.iss, proxy, exp: link.cert.exp, deviceId: await pubkeyId(device.publickey) }
+    },
+    async listVaultDevices () {
+      return requestDevices({ master: link.iss, proxy, device, cert: link.cert, sinceSeq: 0 })
+    }
+  }
+}
 
-    const link = { device, cert: res.cert, iss: qr.iss, proxy: qr.proxy, label, at: Date.now() }
-    saveLink(dir, link)
-    return link
-  } finally { client.close() }
+/** El enlace como lo esperan `ContentClient.connect({ link })` y `RemoteAgentClient`. */
+export function clientLink (link, opts) {
+  return { id: identityFromLink(link, opts), cert: link.cert, iss: link.iss, proxy: link.proxy || 'wss://proxy.dotrino.com' }
 }
 
-export default { dataDir, loadLink, parseQr, enroll }
+export default { dataDir, loadLink, saveLink, parseQr, enroll, identityFromLink, clientLink }