@dotrino/identity 0.21.0 → 0.22.1

package/README.md

@@ -1,6 +1,6 @@
 # @dotrino/identity
 
-> **Parte del ecosistema [Dotrino](https://dotrino.com).** Misión: aplicaciones que resuelven problemas comunes, respetando tu privacidad — sin anuncios, sin cookies, sin rastreo de datos, sin vender tu identidad a nadie.
+> **Parte del ecosistema [Dotrino](https://dotrino.com).** Dotrino es un ecosistema de aplicaciones centradas en la privacidad de los datos: tu información es tuya, y las decisiones sobre ella también — qué compartes, con quién, cuándo y por qué. Sin anuncios, sin cookies, sin rastreo de datos, sin vender tu identidad a nadie.
 
 Identidad de usuario y rating de peers compartidos entre las apps de Dotrino. Funciona aunque las apps vivan en orígenes distintos: usa un **vault iframe** alojado en un origin estable que guarda la información en su propio `localStorage` y expone una API por `postMessage`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotrino/identity",
-  "version": "0.21.0",
+  "version": "0.22.1",
   "description": "Identidad y rating de usuarios compartidos entre apps de Dotrino (vault iframe + postMessage)",
   "type": "module",
   "main": "src/index.js",

package/src/index.d.ts

@@ -155,7 +155,27 @@ export class Identity {
   syncStatus (): Promise<SyncStatus>
   syncNow (): Promise<SyncStatus>
   onSync (handler: (event: SyncEvent) => void): () => void
-  on (event: 'peer_updated' | 'me_updated' | 'sync', handler: (payload: any) => void): () => void
+  // vault (este dispositivo es cliente de un vault externo)
+  enrollDevice (qr: string): Promise<any>
+  vaultStatus (): Promise<any>
+  vaultUnpair (): Promise<any>
+  vaultSign (payload: any): Promise<{ signature: string; publickey: string }>
+  vaultStore (method: string, args?: any): Promise<any>
+  listVaultDevices (): Promise<{ devices: any[]; revoked: any[] }>
+  getVaultCert (): Promise<any>
+  onVault (handler: (payload: any) => void): () => void
+  // self-vault (este dispositivo ES el vault, daemon dentro del iframe)
+  selfVaultStatus (): Promise<{ enabled: boolean; running: boolean }>
+  setSelfVault (enabled: boolean): Promise<{ ok: true; enabled: boolean }>
+  selfVaultPairing (opts?: any): Promise<any>
+  selfVaultPending (): Promise<any[]>
+  selfVaultMachines (): Promise<any[]>
+  selfVaultApprove (deviceId: string, code: string): Promise<any>
+  selfVaultReject (deviceId: string): Promise<{ ok: true }>
+  selfVaultRevoke (nonce: string): Promise<any>
+  selfVaultProbe (pubkeys: string[]): Promise<{ online: string[] }>
+  onSelfVault (handler: (payload: any) => void): () => void
+  on (event: 'peer_updated' | 'me_updated' | 'sync' | 'vault' | 'selfVault', handler: (payload: any) => void): () => void
 }
 
 export interface SyncStatus {

package/src/index.js

@@ -318,6 +318,33 @@ export class Identity {
     return this.on('vault', handler)
   }
 
+  // ----- Self-vault: ESTE dispositivo actúa como su propia bóveda/CA -----
+  // El daemon device-vault vive dentro del iframe (no requiere el binario del PC ni
+  // vault.dotrino.com/pair). Cualquier app puede activarlo, generar códigos de
+  // emparejamiento, aprobar SAS y revocar máquinas — todo por RPC al iframe.
+  // El daemon sólo corre en una pestaña visible a la vez (navigator.locks), pero los
+  // getters (status/pending/machines) y revoke sirven desde cualquier pestaña.
+  /** { enabled, running }: si el modo self está activado y si esta pestaña sostiene el daemon. */
+  async selfVaultStatus () { return this._call('selfVaultStatus') }
+  /** Activa/desactiva el modo self-vault en este dispositivo. */
+  async setSelfVault (enabled) { return this._call('setSelfVault', { enabled }) }
+  /** Genera un código de emparejamiento + QR para enlazar otra máquina. Sólo sirve desde la pestaña activa. */
+  async selfVaultPairing (opts) { return this._call('selfVaultPairing', opts || {}, 60000) }
+  /** Lista de solicitudes de emparejamiento pendientes de aprobar. */
+  async selfVaultPending () { return this._call('selfVaultPending') }
+  /** Máquinas/agentes enrolados (delegaciones vigentes con scope vault:sign). */
+  async selfVaultMachines () { return this._call('selfVaultMachines') }
+  /** Aprueba una solicitud de emparejamiento comparando el código SAS. */
+  async selfVaultApprove (deviceId, code) { return this._call('selfVaultApprove', { deviceId, code }) }
+  /** Rechaza una solicitud de emparejamiento pendiente. */
+  async selfVaultReject (deviceId) { return this._call('selfVaultReject', { deviceId }) }
+  /** Revoca una máquina/agente enrolado por nonce de delegación. */
+  async selfVaultRevoke (nonce) { return this._call('selfVaultRevoke', { nonce }) }
+  /** Presencia online (ping/pong) de las máquinas enroladas. Devuelve { online: [pubkeys] }. */
+  async selfVaultProbe (pubkeys) { return this._call('selfVaultProbe', { pubkeys }, 10000) }
+  /** Suscribe a eventos del self-vault ('selfVault'): { running?, pending?, error? }. */
+  onSelfVault (handler) { return this.on('selfVault', handler) }
+
   // ----- multi-perfil por dispositivo -----
   // Podés tener varios perfiles (identidades) en el mismo navegador, cada uno conectado o no
   // a su propio vault. Crear/cambiar setea el perfil activo; la app RECARGA la página y toma

package/vault/index.html

@@ -22,7 +22,11 @@
   <!-- Transporte self-hosted (vendorizado): el emparejamiento de dispositivos importa
        @dotrino/proxy-client de forma perezosa; este import map lo resuelve sin CDN. -->
   <script type="importmap">
-  { "imports": { "@dotrino/proxy-client": "./vendor/proxy-client/index.js" } }
+  { "imports": {
+    "@dotrino/proxy-client": "./vendor/proxy-client/index.js",
+    "@dotrino/vault": "./vendor/vault/index.js",
+    "@dotrino/identity/capabilities": "./capabilities.js"
+  } }
   </script>
   <script type="module" src="./vault.js"></script>
 </body>

package/vault/vault.js

@@ -13,6 +13,7 @@ import {
   initPeerStorage, loadPeers, savePeers, setPeersDirect, upsertPeer, onDirty
 } from './peerStore.js'
 import { createIdentityCore } from './core.js'
+import { pubkeyId } from './capabilities.js'
 
 ;(async () => {
   // kv estilo localStorage (síncrono) para me, nonces, delegaciones, certs.
@@ -97,6 +98,147 @@ import { createIdentityCore } from './core.js'
   core.onSyncStatus((p) => broadcast('sync', p))
   core.onVaultEvent((p) => broadcast('vault', p))
 
+  // ---- Modo SELF: este navegador actúa como bóveda (daemon device-vault) ----
+  // startDeviceVault convierte la identidad P en CA: atiende enrolamientos y consultas
+  // de revocación por el proxy. Solo UN iframe por origin es el daemon activo
+  // (navigator.locks): la pestaña VISIBLE sostiene el lock; al pasar a background lo
+  // libera y otra pestaña visible lo toma. Así varias apps abiertas no compiten.
+  const SELF_FLAG = 'dotrino.self-vault.enabled' // persistido en localStorage (kv)
+  const SELF_LOCK = 'dotrino-self-vault'
+  let daemon = null           // handle de startDeviceVault cuando ESTE iframe es el activo
+  let _lockResolver = null    // resolver del callback del lock (libera al resolverlo)
+
+  // Adaptador: startDeviceVault exige identity.{me.publickey, signData, signDelegation,
+  // listDelegations, revokeDelegation}; el core los expone vía handlers + getter me.
+  const selfIdentity = {
+    get me () { return core.me },
+    signData: (data) => handlers.signData({ data }),
+    signDelegation: (sub, scope, opts) => handlers.signDelegation({ sub, scope, ...(opts || {}) }),
+    listDelegations: () => handlers.listDelegations({}),
+    revokeDelegation: (nonce) => handlers.revokeDelegation({ nonce })
+  }
+
+  async function startSelfDaemon () {
+    if (daemon) return
+    try {
+      // Import dinámico: aísla fallos del vendor del arranque del vault (cargado por
+      // todas las apps). El import map de index.html resuelve @dotrino/vault.
+      const { startDeviceVault } = await import('@dotrino/vault')
+      daemon = await startDeviceVault(selfIdentity)
+      daemon.onPendingChange(() => broadcast('selfVault', { pending: daemon.listPending() }))
+      broadcast('selfVault', { running: true })
+    } catch (e) { daemon = null; broadcast('selfVault', { error: e?.message || String(e) }) }
+  }
+  function stopSelfDaemon () {
+    if (!daemon) return
+    try { daemon.close() } catch {}
+    daemon = null
+    broadcast('selfVault', { running: false })
+  }
+
+  // Adquiere el lock solo si el modo self está activado Y la pestaña es visible.
+  function holdSelfLock () {
+    if (!navigator.locks) return
+    if (kv.getItem(SELF_FLAG) !== '1' || document.visibilityState !== 'visible') return
+    navigator.locks.request(SELF_LOCK, { mode: 'exclusive', ifAvailable: true }, async (lock) => {
+      if (!lock) return // otra pestaña visible lo tiene
+      await startSelfDaemon()
+      await new Promise((resolve) => { _lockResolver = resolve }) // mantener el lock
+      stopSelfDaemon()
+    }).catch(() => {})
+  }
+  function releaseSelfLock () { if (_lockResolver) { _lockResolver(); _lockResolver = null } }
+
+  document.addEventListener('visibilitychange', () => {
+    if (document.visibilityState === 'visible') holdSelfLock()
+    else releaseSelfLock()
+  })
+
+  // Sonda de presencia (ping/pong por el proxy del daemon). Mandamos AMBOS tipos
+  // (ra.ping para agentes @dotrino/remote-agent —ia—; terminal.ping para terminal
+  // pre-migración) y consideramos online si responde cualquiera. Reusa el cliente
+  // del proxy del daemon activo en ESTE iframe; si no hay daemon, devuelve vacío.
+  function probeOnline (pubkeys, { timeoutMs = 4000 } = {}) {
+    return new Promise((resolve) => {
+      const online = new Set()
+      const client = daemon?.client
+      if (!client?.sendByPubkey || !pubkeys.length) return resolve(online)
+      let rest = pubkeys.length
+      const byNonce = new Map()
+      const off = client.on('message', (_f, p) => {
+        if (!p || typeof p !== 'object') return
+        if (p.type === 'ra.pong' || p.type === 'terminal.pong') {
+          const pk = byNonce.get(p.n)
+          if (pk) { online.add(pk); byNonce.delete(p.n); settle() }
+        }
+      })
+      function settle () { if (--rest <= 0) { off(); resolve(online) } }
+      for (const pk of pubkeys) {
+        const n = pk.slice(0, 6) + Math.random().toString(36).slice(2, 8)
+        byNonce.set(n, pk)
+        try { client.sendByPubkey(pk, { type: 'ra.ping', n }); client.sendByPubkey(pk, { type: 'terminal.ping', n }) } catch {}
+        setTimeout(settle, timeoutMs)
+      }
+    })
+  }
+
+  // Handlers de UI (emparejamiento/gestión) expuestos por postMessage. Las ACCIONES
+  // (pairing/approve) requieren que ESTE iframe sea el daemon activo (la pestaña visible);
+  // la lectura (máquinas/pending) siempre funciona (lee delegaciones persistidas).
+  const selfHandlers = {
+    // En modo self, listar máquinas enroladas lee LOCAL (listDelegations) en vez de
+    // hacer RPC al daemon del PC: somos nuestra propia maestra. Así ia/terminal listan
+    // agentes siempre, sin depender de qué pestaña sostenga el lock del daemon.
+    listVaultDevices: async () => {
+      if (kv.getItem(SELF_FLAG) !== '1') return handlers.listVaultDevices({})
+      const { issued, revoked } = await handlers.listDelegations({})
+      const now = Date.now()
+      const bySub = new Map()
+      for (const x of (issued || [])) {
+        if (!x.sub || x.revokedAt || (x.exp && x.exp <= now)) continue
+        if (!Array.isArray(x.scope) || !x.scope.includes('vault:sign')) continue
+        if (!bySub.has(x.sub) || (x.exp || 0) > (bySub.get(x.sub).exp || 0)) bySub.set(x.sub, x)
+      }
+      const devices = await Promise.all([...bySub.values()].map(async (x) => ({
+        deviceId: (await pubkeyId(x.sub)).slice(0, 8).toUpperCase().replace(/(.{4})(.{4})/, '$1-$2'),
+        sub: x.sub, label: x.label || '', scope: x.scope, exp: x.exp, nonce: x.nonce
+      })))
+      return { devices, revoked: (revoked || []).map((r) => r.nonce || r) }
+    },
+    selfVaultStatus: async () => ({ enabled: kv.getItem(SELF_FLAG) === '1', running: !!daemon }),
+    setSelfVault: async ({ enabled }) => {
+      kv.setItem(SELF_FLAG, enabled ? '1' : '0')
+      if (enabled) holdSelfLock(); else releaseSelfLock()
+      return { ok: true, enabled: !!enabled }
+    },
+    selfVaultPairing: async (opts) => {
+      if (!daemon) throw new Error('esta pestaña no es la bóveda activa; ábrela como pestaña visible')
+      return daemon.startPairing(opts)
+    },
+    selfVaultPending: async () => (daemon ? daemon.listPending() : []),
+    selfVaultMachines: async () => {
+      if (daemon) return daemon.listMachines()
+      const { issued } = await handlers.listDelegations({})
+      return issued || []
+    },
+    selfVaultApprove: async ({ deviceId, code }) => {
+      if (!daemon) throw new Error('esta pestaña no es la bóveda activa')
+      return daemon.approve(deviceId, code)
+    },
+    selfVaultReject: async ({ deviceId }) => {
+      if (!daemon) throw new Error('esta pestaña no es la bóveda activa')
+      daemon.reject(deviceId)
+      return { ok: true }
+    },
+    selfVaultRevoke: async ({ nonce }) => {
+      if (daemon) return daemon.revoke(nonce)
+      return handlers.revokeDelegation({ nonce })
+    },
+    // Presencia online (ping/pong) de las máquinas enroladas. Requiere que ESTE
+    // iframe sea el daemon activo (tiene el cliente del proxy); si no, devuelve [].
+    selfVaultProbe: async ({ pubkeys }) => ({ online: [...(await probeOnline(pubkeys || []))] })
+  }
+
   window.addEventListener('message', async (event) => {
     const msg = event.data
     if (!msg || msg._cci !== true || msg.type !== 'request') return
@@ -107,7 +249,7 @@ import { createIdentityCore } from './core.js'
       { _cci: true, type: 'response', id, ...payload },
       event.origin
     )
-    const handler = handlers[method]
+    const handler = selfHandlers[method] || handlers[method]
     if (!handler) return reply({ error: `Unknown method: ${method}` })
     try {
       const result = await handler(params || {})
@@ -135,4 +277,6 @@ import { createIdentityCore } from './core.js'
       window.parent.postMessage({ _cci: true, type: 'ready' }, '*')
     }
   }
+  // Si el modo self-vault ya estaba activado, intentar tomar el lock (pestaña visible).
+  holdSelfLock()
 })()

package/vault/vendor/vault/VERSION.txt

@@ -0,0 +1,5 @@
+Copia vendorizada de @dotrino/vault@0.3.0 (lib/src/index.js, sin dependencias).
+El iframe de identity se sirve estático (vanilla, sin build); así startDeviceVault
+resuelve en el navegador sin bundler. Importa @dotrino/identity/capabilities
+(=../../capabilities.js) y @dotrino/proxy-client (=../proxy-client/), ambos vía
+el import map de index.html. Re-vendorizar al subir @dotrino/vault.

package/vault/vendor/vault/index.js

@@ -0,0 +1,251 @@
+/**
+ * @dotrino/vault — "este dispositivo es una bóveda" (lado SERVIDOR, browser+node).
+ *
+ * Convierte la identidad de ESTE dispositivo (`@dotrino/identity`, la clave P) en una
+ * bóveda/CA: atiende el MISMO protocolo de enrolamiento endurecido que el daemon
+ * `dotrino-vault` (`vault.enroll` → `vault.enroll.challenge` → `vault.enrolled`) por el
+ * proxy del ecosistema, firma certificados de delegación `D ← P` al aprobar, y responde
+ * consultas de revocación (`vault.devices`). Así CUALQUIER app (no solo la terminal)
+ * puede dejar que el usuario use su dispositivo como bóveda, sin un PC con el daemon.
+ *
+ * Modelo de aprobación SEGURO (idéntico al daemon `dotrino-vault#approveDevice`):
+ *   - El DISPOSITIVO que se enrola (p. ej. `@dotrino/identity#enrollDevice`) genera un
+ *     código ALEATORIO (`makePairingCode`) y lo MUESTRA; NO lo envía por la red.
+ *   - Esta bóveda NO conoce el código: un humano lo LEE del dispositivo y lo TIPEA aquí.
+ *   - Al aprobar, la bóveda firma el cert y ECHA el código tipeado de vuelta.
+ *   - El dispositivo acepta el cert SOLO si el código echado coincide con el que generó.
+ *     → una bóveda falsa (que nunca vio el código) no puede enrolar el dispositivo, y
+ *     aprobar "a ciegas" (sin ir a leer el código del dispositivo) tampoco enrola nada.
+ *
+ * Cripto 100% de `@dotrino/identity/capabilities` (verifyDeviceSig/verifyChain/pubkeyId)
+ * + firma con la identidad P (`identity.signDelegation`). Transporte: `@dotrino/proxy-client`
+ * (import perezoso). No reimplementa nada del ecosistema.
+ */
+import { verifyDeviceSig, verifyChain, pubkeyId } from '@dotrino/identity/capabilities'
+
+const SIGN_SCOPE = 'vault:sign'
+const PAIRING_TTL_MS = 5 * 60 * 1000           // un emparejamiento (token) vale 5 min
+const DEVICE_TTL_MS = 30 * 24 * 60 * 60 * 1000 // vida de un cert de dispositivo (30 días)
+const SELFCERT_TTL_MS = 24 * 60 * 60 * 1000    // el self-cert P←P se regenera cada 24 h
+const FRESH_WINDOW_MS = 5 * 60 * 1000          // ventana anti-replay del enroll (±5 min)
+
+const MSG = {
+  ENROLL: 'vault.enroll',
+  ENROLL_CHALLENGE: 'vault.enroll.challenge',
+  ENROLLED: 'vault.enrolled',
+  DEVICES: 'vault.devices',
+  DEVICES_RESULT: 'vault.devices.result',
+  REVOKED: 'vault.revoked',
+  ERROR: 'vault.error'
+}
+
+function randToken () {
+  const b = crypto.getRandomValues(new Uint8Array(16))
+  return [...b].map((x) => x.toString(16).padStart(2, '0')).join('')
+}
+
+/** deviceId legible (p. ej. `C440-AC0E`) desde una pubkey JWK. */
+export function deviceIdOf (pub) {
+  return pubkeyId(pub).then((id) => id.slice(0, 8).toUpperCase().replace(/(.{4})(.{4})/, '$1-$2'))
+}
+
+/**
+ * Levanta la bóveda de este dispositivo: se conecta al proxy identificado como P y
+ * atiende enrolamientos + consultas de revocación de los dispositivos que se enrolan.
+ *
+ * @param {object} identity  instancia de `@dotrino/identity` (P): expone
+ *   `me.publickey`, `signData`, `signDelegation`, `listDelegations`, `revokeDelegation`.
+ * @param {object} [opts]
+ * @param {string} [opts.proxyUrl='wss://proxy.dotrino.com']
+ * @returns {Promise<object>} handle: { iss, proxy, client, startPairing, approve, reject,
+ *   listPending, listMachines, revoke, getSelfCert, onPendingChange, close }
+ */
+export async function startDeviceVault (identity, { proxyUrl } = {}) {
+  const iss = identity.me?.publickey
+  if (!iss) throw new Error('sin identidad: crea/desbloquea tu identidad antes de usar el dispositivo como bóveda')
+  const proxy = proxyUrl || 'wss://proxy.dotrino.com'
+
+  // ----- self-cert P ← P (para que este dispositivo pueda además actuar de cliente
+  // de sus propias máquinas: lo firma la propia P y verifyChain lo acepta) -----
+  let _selfCert = null
+  const getSelfCert = async () => {
+    if (_selfCert && _selfCert.exp > Date.now() + 60_000) return _selfCert
+    const { cert } = await identity.signDelegation(iss, SIGN_SCOPE, { ttlMs: SELFCERT_TTL_MS })
+    _selfCert = cert
+    return cert
+  }
+
+  const { WebSocketProxyClient } = await import('@dotrino/proxy-client')
+  const client = new WebSocketProxyClient({
+    url: proxy, enableWebRTC: false, autoReconnect: true,
+    maxReconnectAttempts: 100000, reconnectDelay: 4000
+  })
+  await client.connect()
+
+  const selfCert = await getSelfCert()
+  const identify = async () => {
+    if (!client.token) return
+    const data = { op: 'identify', publickey: iss, token: client.token, ts: Date.now() }
+    const { signature } = await identity.signData(data)
+    await client.identify({ data, signature, cert: selfCert })
+  }
+  await identify()
+  client.on('token', () => identify().catch(() => {}))
+
+  const send = (to, obj) => { try { client.send(to, obj) } catch (_) {} }
+
+  // token -> { exp, sn, scope, ttlMs, label, state, dpub?, deviceId?, from? }
+  const pending = new Map()
+  let _onPendingChange = () => {}
+
+  async function handleEnroll (from, p) {
+    const d = p?.data
+    if (!d || typeof d.dpub !== 'string' || typeof p.signature !== 'string') {
+      return send(from, { type: MSG.ERROR, error: 'enroll inválido' })
+    }
+    const pend = pending.get(d.token)
+    if (!pend || Date.now() > pend.exp) {
+      return send(from, { type: MSG.ERROR, error: 'token de emparejamiento inválido o expirado' })
+    }
+    if (d.sn !== pend.sn) return send(from, { type: MSG.ERROR, error: 'sesión inválida' })
+    if (typeof d.ts !== 'number' || Math.abs(Date.now() - d.ts) > FRESH_WINDOW_MS) {
+      return send(from, { type: MSG.ERROR, error: 'enroll vencido (posible replay, o el reloj desfasado)' })
+    }
+    // PRUEBA DE POSESIÓN: la firma de `data` debe verificar contra `dpub`.
+    const ok = await verifyDeviceSig({ publickey: d.dpub, data: d, signature: p.signature })
+    if (!ok) return send(from, { type: MSG.ERROR, error: 'firma de dispositivo inválida' })
+    // Un solo dispositivo a la vez esperando su código (así `approve` no es ambiguo).
+    if (pend.state === 'PENDING_CONFIRM' && pend.dpub && pend.dpub !== d.dpub) {
+      return send(from, { type: MSG.ERROR, error: 'ya hay un dispositivo usando este emparejamiento' })
+    }
+    const deviceId = await deviceIdOf(d.dpub)
+    pend.state = 'PENDING_CONFIRM'
+    pend.dpub = d.dpub
+    pend.deviceId = deviceId
+    pend.from = from // esta bóveda NO conoce el código (no viaja): el dispositivo lo MUESTRA
+    if (d.label) pend.label = String(d.label).slice(0, 60)
+    _onPendingChange()
+    send(from, { type: MSG.ENROLL_CHALLENGE, deviceId })
+  }
+
+  // Emite un REVOKED FIRMADO por la maestra a la máquina revocada para que se
+  // auto-borre. Va por `sendByPubkey` → si está offline, el proxy lo encola 24 h; y
+  // si reaparece más tarde, `handleDevices` lo re-emite en su siguiente consulta.
+  // El auto-borrado remoto SOLO se dispara con esta firma (no con un error cualquiera).
+  async function emitRevoke (dpub, nonce) {
+    const body = { op: 'revoke', sub: dpub, nonce, iat: Date.now(), exp: Date.now() + DEVICE_TTL_MS }
+    const { signature } = await identity.signData(body)
+    try { client.sendByPubkey(dpub, { type: MSG.REVOKED, body, signature }) } catch (_) {}
+  }
+
+  // Consulta de revocaciones (igual que `vault.devices` del daemon): responde la lista
+  // de dispositivos enrolados + revocados para que el dispositivo refresque su set. Y si
+  // QUIEN consulta es una máquina ya revocada (reapareció), le re-emite el REVOKED firmado.
+  async function handleDevices (from, p) {
+    const d = p?.data
+    if (!d || !p.signature || !p.cert) return send(from, { type: MSG.ERROR, error: 'petición inválida' })
+    if (typeof d.ts !== 'number' || Math.abs(Date.now() - d.ts) > FRESH_WINDOW_MS) return
+    const chk = await verifyChain({ data: d, signature: p.signature, cert: p.cert, trustedIssuer: iss })
+    if (!chk.ok) return send(from, { type: MSG.ERROR, error: 'no autorizado: ' + chk.reason })
+    const { issued, revoked } = await identity.listDelegations()
+    const devices = await Promise.all((issued || []).map(async (x) => ({
+      deviceId: x.sub ? await deviceIdOf(x.sub) : null, sub: x.sub || null,
+      label: x.label || '', scope: x.scope, exp: x.exp, nonce: x.nonce
+    })))
+    send(from, { type: MSG.DEVICES_RESULT, devices, revoked: (revoked || []).map((r) => r.nonce || r) })
+    // ¿el que consulta es una máquina revocada que reapareció? → re-emite el REVOKED firmado.
+    const mine = (issued || []).find((x) => x.sub === chk.device && x.revokedAt)
+    if (mine) emitRevoke(chk.device, mine.nonce)
+  }
+
+  client.on('message', (_from, p) => {
+    if (!p || typeof p !== 'object') return
+    if (p.type === MSG.ENROLL) handleEnroll(_from, p).catch(() => {})
+    else if (p.type === MSG.DEVICES) handleDevices(_from, p).catch(() => {})
+  })
+
+  /**
+   * Abre un emparejamiento: devuelve el QR/JSON v2 que el dispositivo consume para
+   * enrolarse. `scope`/`ttlMs`/`label` fijan lo que otorgará el cert al aprobar.
+   */
+  function startPairing ({ scope = [SIGN_SCOPE], ttlMs = DEVICE_TTL_MS, label = '' } = {}) {
+    pending.clear()
+    const token = randToken()
+    const sn = randToken()
+    pending.set(token, { token, exp: Date.now() + PAIRING_TTL_MS, sn, scope, ttlMs, label, state: 'AWAITING_ENROLL' })
+    return { qr: { v: 2, iss, proxy, token, sn }, expiresInMs: PAIRING_TTL_MS }
+  }
+
+  function listPending () {
+    return [...pending.values()]
+      .filter((p) => p.state === 'PENDING_CONFIRM')
+      .map((p) => ({ deviceId: p.deviceId, label: p.label }))
+  }
+  function findPending (deviceId) {
+    for (const [, p] of pending) if (p.state === 'PENDING_CONFIRM' && p.deviceId === deviceId) return p
+    return null
+  }
+
+  /**
+   * Aprueba una máquina pendiente TIPEANDO el código que ella muestra. Esta bóveda NO
+   * conoce/valida el código: firma el cert y ECHA el código tipeado; la máquina lo acepta
+   * solo si coincide con el que generó. (Modelo `dotrino-vault#approveDevice`.)
+   */
+  async function approve (deviceId, code) {
+    const pend = findPending(deviceId)
+    if (!pend || !pend.dpub) throw new Error('no hay ninguna máquina esperando aprobación')
+    code = String(code || '').trim()
+    if (!code) throw new Error('escribe el código que muestra la máquina')
+    const { cert } = await identity.signDelegation(pend.dpub, pend.scope, { ttlMs: pend.ttlMs, label: pend.label })
+    send(pend.from, { type: MSG.ENROLLED, code, cert, iss })
+    pending.delete(pend.token)
+    _onPendingChange()
+    return { ok: true, deviceId }
+  }
+
+  function reject (deviceId) {
+    const pend = findPending(deviceId)
+    if (!pend) return
+    send(pend.from, { type: MSG.ERROR, error: 'emparejamiento rechazado' })
+    pending.delete(pend.token)
+    _onPendingChange()
+  }
+
+  /**
+   * Máquinas enroladas bajo esta identidad (P), vigentes, con scope de firma y label
+   * propio (excluye navegadores enrolados con label 'cli', que no atienden peticiones).
+   */
+  async function listMachines () {
+    const { issued } = await identity.listDelegations()
+    const now = Date.now()
+    const bySub = new Map()
+    for (const x of (issued || [])) {
+      if (!x.sub || x.revokedAt || (x.exp && x.exp <= now)) continue // revocada = fuera de la lista
+      if (!Array.isArray(x.scope) || !x.scope.includes(SIGN_SCOPE)) continue
+      if (!x.label || x.label === 'cli') continue
+      if (!bySub.has(x.sub) || (x.exp || 0) > (bySub.get(x.sub).exp || 0)) bySub.set(x.sub, x)
+    }
+    return Promise.all([...bySub.values()].map(async (x) => ({ ...x, deviceId: await deviceIdOf(x.sub) })))
+  }
+
+  async function revoke (nonce) {
+    // Deja el registro persistente (revokedAt en la delegación) y AVISA a la máquina
+    // con un REVOKED firmado para que se auto-borre (ahora si está online, o al
+    // reaparecer vía handleDevices). Ver emitRevoke.
+    const { issued } = await identity.listDelegations()
+    const dele = (issued || []).find((d) => d.nonce === nonce)
+    const res = await identity.revokeDelegation(nonce)
+    if (dele?.sub) await emitRevoke(dele.sub, nonce)
+    return res
+  }
+
+  return {
+    iss, proxy, client,
+    startPairing, approve, reject, listPending, listMachines, revoke,
+    getSelfCert,
+    onPendingChange (fn) { _onPendingChange = fn || (() => {}) },
+    close () { try { client.close() } catch (_) {} }
+  }
+}
+
+export default { startDeviceVault, deviceIdOf }