@dotrino/vaultd 0.6.0

package/lib/src/sealed.js

@@ -0,0 +1,84 @@
+/**
+ * Sobres SELLADOS para respuestas del vault con contenido sensible (secretos).
+ *
+ * El proxy transporta pero NUNCA debe ver el contenido. Como la llave de
+ * dispositivo `D` es ECDSA (solo firma), el que PIDE genera una llave ECDH
+ * EFÍMERA por petición (`ek`) y la manda dentro del sobre firmado por `D`
+ * (→ ek queda autenticada por la cadena D←maestra). El vault sella la
+ * respuesta a esa ek: ECDH efímero propio + AES-256-GCM. Reproducir una
+ * respuesta vieja es inerte: cada petición usa una ek nueva y el replay no
+ * se puede descifrar.
+ *
+ * La AUTENTICIDAD de la respuesta no la da este módulo sino la firma de la
+ * maestra sobre el cuerpo (el dispositivo la verifica contra la `iss` pineada).
+ *
+ * WebCrypto puro (browser y Node ≥20). Cripto alineada al ecosistema:
+ * P-256 + AES-GCM, llaves como JWK string.
+ */
+
+const subtle = globalThis.crypto.subtle
+
+function b64 (buf) {
+  const bytes = new Uint8Array(buf)
+  let s = ''
+  for (let i = 0; i < bytes.length; i++) s += String.fromCharCode(bytes[i])
+  return btoa(s)
+}
+
+function fromB64 (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
+}
+
+async function deriveAesKey (privateKey, publicJwkStr) {
+  const pub = await subtle.importKey(
+    'jwk', JSON.parse(publicJwkStr),
+    { name: 'ECDH', namedCurve: 'P-256' }, false, []
+  )
+  const bits = await subtle.deriveBits({ name: 'ECDH', public: pub }, privateKey, 256)
+  return subtle.importKey('raw', bits, { name: 'AES-GCM' }, false, ['encrypt', 'decrypt'])
+}
+
+/**
+ * Genera la llave ECDH EFÍMERA del solicitante (una por petición).
+ * `ek` (JWK string pública) viaja en el sobre firmado; `privateKey` se queda
+ * en memoria para abrir la respuesta.
+ */
+export async function makeEphemeralKey () {
+  const kp = await subtle.generateKey({ name: 'ECDH', namedCurve: 'P-256' }, false, ['deriveBits'])
+  const jwk = await subtle.exportKey('jwk', kp.publicKey)
+  return { ek: JSON.stringify({ kty: jwk.kty, crv: jwk.crv, x: jwk.x, y: jwk.y }), privateKey: kp.privateKey }
+}
+
+/**
+ * Sella `payload` (cualquier JSON) hacia la ek del solicitante.
+ * @returns {Promise<{epk:string, iv:string, ct:string}>}
+ */
+export async function seal ({ ek, payload }) {
+  const eph = await subtle.generateKey({ name: 'ECDH', namedCurve: 'P-256' }, false, ['deriveBits'])
+  const key = await deriveAesKey(eph.privateKey, ek)
+  const iv = globalThis.crypto.getRandomValues(new Uint8Array(12))
+  const pt = new TextEncoder().encode(JSON.stringify(payload))
+  const ct = await subtle.encrypt({ name: 'AES-GCM', iv }, key, pt)
+  const epkJwk = await subtle.exportKey('jwk', eph.publicKey)
+  return {
+    epk: JSON.stringify({ kty: epkJwk.kty, crv: epkJwk.crv, x: epkJwk.x, y: epkJwk.y }),
+    iv: b64(iv),
+    ct: b64(ct)
+  }
+}
+
+/**
+ * Abre un sobre sellado con la privada efímera de `makeEphemeralKey()`.
+ * Lanza si el sobre no es para esa llave (AES-GCM autentica el contenido).
+ */
+export async function openSealed ({ privateKey, enc }) {
+  if (!enc || typeof enc.epk !== 'string' || typeof enc.iv !== 'string' || typeof enc.ct !== 'string') {
+    throw new Error('sobre sellado inválido')
+  }
+  const key = await deriveAesKey(privateKey, enc.epk)
+  const pt = await subtle.decrypt({ name: 'AES-GCM', iv: fromB64(enc.iv) }, key, fromB64(enc.ct))
+  return JSON.parse(new TextDecoder().decode(pt))
+}

package/lib/src/service.js

@@ -0,0 +1,258 @@
+/**
+ * Cliente de SERVICIO del vault (Node ≥22). Para que un servicio del ecosistema
+ * (proxy, geo, bots…) sea un CLIENTE IDENTIFICADO más y obtenga sus secretos
+ * del vault en vez de llevarlos en el `.env`:
+ *
+ *   1. En el vault:  `dotrino-vault pair --service proxy`  (QR/código con scope
+ *      SOLO `vault:secrets:proxy`) y `dotrino-vault secret set proxy TURN_KEY_ID …`
+ *   2. En el servicio (una vez):  `enrollService({ qr, ns, dir })` — genera la
+ *      llave del servicio, muestra el código de aprobación y persiste
+ *      `service-identity.json` (device + cert + iss + proxy).
+ *   3. En cada arranque:  `waitForSecrets({ dir, ns })` — pide los secretos y,
+ *      si el vault no está, REINTENTA para siempre (regla del ecosistema: sin
+ *      vault, el servicio espera; no arranca con secretos viejos ni vacíos).
+ *
+ * Seguridad: la petición va firmada por la llave del servicio + cert (cadena
+ * D←maestra, scope `vault:secrets:<ns>`); la respuesta viene SELLADA (ECDH
+ * efímero + AES-GCM → el proxy no ve los valores) y FIRMADA por la maestra
+ * (verificada contra la `iss` pineada en el enrolamiento → un relay no puede
+ * inyectar secretos falsos).
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import {
+  makeDeviceKey, signWithDevice, verifyDelegation, verifyDeviceSig,
+  makePairingCode, commitCode, pubkeyId
+} from '@dotrino/identity/capabilities'
+import { MSG, secretsScope, isValidSecretsNs } from './protocol.js'
+import { makeEphemeralKey, openSealed } from './sealed.js'
+
+const IDENTITY_FILE = 'service-identity.json'
+const FRESH_WINDOW_MS = 5 * 60 * 1000
+const RENEW_BEFORE_MS = 7 * 24 * 60 * 60 * 1000 // renovar el cert si vence en <7 días
+
+let _globalsInstalled = false
+function installNodeGlobals () {
+  if (_globalsInstalled) return
+  _globalsInstalled = true
+  // localStorage en memoria: @dotrino/proxy-client lo usa solo para su keypair
+  // de canales (que un servicio no necesita persistir). Se define SIN leer el
+  // getter nativo: en Node ≥22 acceder a `globalThis.localStorage` sin
+  // `--localstorage-file` es no-funcional y además emite un warning.
+  const desc = Object.getOwnPropertyDescriptor(globalThis, 'localStorage')
+  const isUsable = desc && 'value' in desc && typeof desc.value?.getItem === 'function'
+  if (!isUsable) {
+    const mem = new Map()
+    Object.defineProperty(globalThis, 'localStorage', {
+      configurable: true,
+      value: {
+        getItem: (k) => (mem.has(k) ? mem.get(k) : null),
+        setItem: (k, v) => mem.set(k, String(v)),
+        removeItem: (k) => mem.delete(k),
+        clear: () => mem.clear(),
+        key: (i) => [...mem.keys()][i] ?? null,
+        get length () { return mem.size }
+      }
+    })
+  }
+  if (typeof globalThis.WebSocket === 'undefined') {
+    throw new Error('este entorno no tiene WebSocket global: usa Node ≥22')
+  }
+}
+
+async function freshClient (proxyUrl, connectTimeoutMs = 20000) {
+  installNodeGlobals()
+  const { WebSocketProxyClient } = await import('@dotrino/proxy-client')
+  const client = new WebSocketProxyClient({ url: proxyUrl, enableWebRTC: false, autoReconnect: false })
+  // connect() del cliente solo se resuelve con 'connected' y solo rechaza en el
+  // evento 'error' de transporte: si el socket cierra LIMPIO antes de 'connected'
+  // (p.ej. el proxy banea la IP y envía close 1008), la promesa quedaría colgada
+  // para siempre y waitForSecrets no reintentaría. Le ponemos un timeout propio.
+  let timer
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new Error('timeout conectando al proxy')), connectTimeoutMs)
+  })
+  try {
+    await Promise.race([client.connect(), timeout])
+  } catch (e) {
+    try { client.close() } catch (_) {}
+    // El 'error' de transporte del cliente puede llegar como un Event sin
+    // `message` → sin esto el operador ve una línea de error vacía.
+    const why = e?.message || e?.type || 'error de transporte'
+    throw new Error(`no se pudo conectar al proxy ${proxyUrl}: ${why}`)
+  } finally {
+    clearTimeout(timer)
+  }
+  return client
+}
+
+/** Identifica la conexión bajo la pubkey del servicio (para ser direccionable). */
+async function identifyAsService (client, device) {
+  const data = { op: 'identify', publickey: device.publickey, token: client.token, ts: Date.now() }
+  const { signature } = await signWithDevice({ privateJwk: device.privateJwk, data })
+  await client.identify({ data, signature })
+}
+
+function waitForMsg (client, predicate, timeoutMs = 30000) {
+  return new Promise((resolve, reject) => {
+    const off = client.on('message', (_from, payload) => {
+      if (payload && typeof payload === 'object' && predicate(payload)) { cleanup(); resolve(payload) }
+    })
+    const t = setTimeout(() => { cleanup(); reject(new Error('timeout esperando respuesta del vault')) }, timeoutMs)
+    const cleanup = () => { off(); clearTimeout(t) }
+  })
+}
+
+const identityFileOf = (dir) => path.join(dir, IDENTITY_FILE)
+
+/** Lee la identidad persistida del servicio ({device, cert, iss, proxy, ns}) o null. */
+export function readServiceIdentity (dir) {
+  try { return JSON.parse(fs.readFileSync(identityFileOf(dir), 'utf8')) } catch (_) { return null }
+}
+
+function writeServiceIdentity (dir, obj) {
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 })
+  const f = identityFileOf(dir)
+  fs.writeFileSync(f, JSON.stringify(obj, null, 2), { mode: 0o600 })
+}
+
+/**
+ * Enrola ESTE servicio contra el vault (una sola vez; persiste la identidad).
+ * En el vault se corre antes `dotrino-vault pair --service <ns>`; el QR/payload
+ * de ese comando es el `qr` de aquí. Muestra un código por `onCode` (o stdout):
+ * el dueño lo tipea en el vault (`dotrino-vault approve <código>`).
+ *
+ * @param {Object} opts
+ * @param {{v:number, iss:string, proxy:string, token:string, sn:string}|string} opts.qr  QR v2 (objeto o JSON string).
+ * @param {string} opts.ns     Namespace de secretos del servicio (el mismo del pair).
+ * @param {string} opts.dir    Dónde persistir `service-identity.json`.
+ * @param {string} [opts.label]
+ * @param {(c:{deviceId:string, code:string})=>void} [opts.onCode]
+ * @returns {Promise<{device, cert, iss:string}>}
+ */
+export async function enrollService ({ qr, ns, dir, label, onCode, approveTimeoutMs = 180000 } = {}) {
+  if (typeof qr === 'string') { try { qr = JSON.parse(qr) } catch (_) { throw new Error('qr inválido: no es JSON') } }
+  if (!qr?.iss || !qr?.proxy || !qr?.token || !qr?.sn) throw new Error('qr inválido (v2): faltan iss/proxy/token/sn')
+  if (!isValidSecretsNs(ns)) throw new Error('ns inválido (usa [a-z0-9-]{1,32}, p.ej. "proxy")')
+  if (!dir) throw new Error('falta dir (dónde persistir la identidad del servicio)')
+  label = label || 'servicio:' + ns
+
+  const client = await freshClient(qr.proxy)
+  try {
+    const device = await makeDeviceKey({ label })
+    const deviceId = (await pubkeyId(device.publickey)).slice(0, 8).toUpperCase().replace(/(.{4})(.{4})/, '$1-$2')
+    // Código ALEATORIO generado AQUÍ: el vault no lo conoce; solo puede echarlo
+    // de vuelta si el dueño lo tipeó (= tiene esta pantalla a la vista).
+    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 enrolled = new Promise((resolve, reject) => {
+      const off = client.on('message', (_from, p) => {
+        if (!p || typeof p !== 'object') return
+        if (p.type === MSG.ENROLL_CHALLENGE) {
+          const show = onCode || (({ deviceId, code }) => console.log(`[vault-service] dispositivo ${deviceId} · aprueba en el vault:  dotrino-vault approve ${code}`))
+          show({ deviceId, code })
+        } else if (p.type === MSG.ENROLLED) { 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')) }, approveTimeoutMs)
+      const cleanup = () => { off(); clearTimeout(t) }
+    })
+    client.sendByPubkey(qr.iss, { type: MSG.ENROLL, data, signature })
+    const res = await enrolled
+
+    // Validación estricta (igual que un dispositivo): cert de la maestra VISTA,
+    // para ESTA llave, y el código echado debe ser el nuestro (anti vault falso).
+    if (res.code !== code) throw new Error('el vault devolvió un código distinto al mostrado (posible relay malicioso)')
+    const v = await verifyDelegation({ cert: res.cert, expectedSub: device.publickey, expectedScope: secretsScope(ns) })
+    if (!v.ok) throw new Error('cert inválido: ' + v.reason)
+    if (res.cert.iss !== qr.iss) throw new Error('cert firmado por una maestra distinta a la del QR')
+
+    writeServiceIdentity(dir, { v: 1, ns, iss: qr.iss, proxy: qr.proxy, device, cert: res.cert, enrolledAt: Date.now() })
+    return { device, cert: res.cert, iss: qr.iss }
+  } finally { client.close() }
+}
+
+/**
+ * Pide los secretos del ns al vault (una petición puntual; lanza si falla).
+ * Usa la identidad persistida por `enrollService` salvo que se pase explícita.
+ * Renueva el cert automáticamente si está por vencer (best-effort).
+ * @returns {Promise<Record<string,string>>}  secretos KEY→valor
+ */
+export async function fetchSecrets ({ dir, ns, proxyUrl, masterPubkey, device, cert, timeoutMs = 30000 } = {}) {
+  let saved = null
+  if (dir) saved = readServiceIdentity(dir)
+  ns = ns || saved?.ns
+  proxyUrl = proxyUrl || saved?.proxy
+  masterPubkey = masterPubkey || saved?.iss
+  device = device || saved?.device
+  cert = cert || saved?.cert
+  if (!isValidSecretsNs(ns)) throw new Error('ns inválido')
+  if (!proxyUrl || !masterPubkey || !device || !cert) {
+    throw new Error('servicio sin enrolar: corre primero enrollService() (falta service-identity.json)')
+  }
+
+  const client = await freshClient(proxyUrl)
+  try {
+    await identifyAsService(client, device)
+
+    // Renovación de cert best-effort si vence pronto (mientras siga vigente).
+    if (typeof cert.exp === 'number' && cert.exp - Date.now() < RENEW_BEFORE_MS && cert.exp > Date.now()) {
+      try {
+        const data = { op: 'renew', publickey: device.publickey, ts: Date.now() }
+        const { signature } = await signWithDevice({ privateJwk: device.privateJwk, data })
+        const pending = waitForMsg(client, (p) => p.type === MSG.RENEWED || p.type === MSG.ERROR, 15000)
+        client.sendByPubkey(masterPubkey, { type: MSG.RENEW, data, signature, cert })
+        const res = await pending
+        if (res.type === MSG.RENEWED && res.cert?.sub === device.publickey) {
+          const v = await verifyDelegation({ cert: res.cert, expectedSub: device.publickey, expectedScope: secretsScope(ns) })
+          if (v.ok) { cert = res.cert; if (dir && saved) writeServiceIdentity(dir, { ...saved, cert }) }
+        }
+      } catch (_) { /* la renovación no bloquea el fetch */ }
+    }
+
+    const eph = await makeEphemeralKey()
+    const data = { op: 'secrets', ns, ek: eph.ek, publickey: device.publickey, ts: Date.now() }
+    const { signature } = await signWithDevice({ privateJwk: device.privateJwk, data })
+    const pending = waitForMsg(client, (p) => p.type === MSG.SECRETS_RESULT || p.type === MSG.ERROR, timeoutMs)
+    client.sendByPubkey(masterPubkey, { type: MSG.SECRETS, data, signature, cert })
+    const res = await pending
+    if (res.type === MSG.ERROR) throw new Error(res.error)
+
+    // Autenticidad: el cuerpo viene firmado por la MAESTRA pineada.
+    const body = res.body
+    if (!body || body.op !== 'secrets.result' || body.ns !== ns) throw new Error('respuesta de secretos malformada')
+    if (typeof body.ts !== 'number' || Math.abs(Date.now() - body.ts) > FRESH_WINDOW_MS) throw new Error('respuesta de secretos vencida')
+    const ok = await verifyDeviceSig({ publickey: masterPubkey, data: body, signature: res.signature })
+    if (!ok) throw new Error('firma de la maestra inválida en la respuesta de secretos')
+
+    const payload = await openSealed({ privateKey: eph.privateKey, enc: body.enc })
+    if (!payload || typeof payload.secrets !== 'object') throw new Error('sobre de secretos malformado')
+    return payload.secrets
+  } finally { client.close() }
+}
+
+/**
+ * Bucle de arranque de un servicio: pide los secretos y, si el vault no está
+ * disponible, REINTENTA para siempre (con backoff hasta `maxRetryMs`). El
+ * servicio no opera hasta que esto resuelva — esa es la regla.
+ * @returns {Promise<Record<string,string>>}
+ */
+export async function waitForSecrets ({ dir, ns, proxyUrl, masterPubkey, device, cert, retryMs = 5000, maxRetryMs = 60000, onRetry } = {}) {
+  let delay = retryMs
+  for (;;) {
+    try {
+      return await fetchSecrets({ dir, ns, proxyUrl, masterPubkey, device, cert })
+    } catch (e) {
+      // Lo NO transitorio no se arregla reintentando: falta de enrolamiento,
+      // cert revocado/vencido o scope equivocado exigen re-emparejar → se corta.
+      if (/sin enrolar|ns inválido|no autorizado: (revoked|expired|scope|cn|untrusted-issuer|cert-device-mismatch)/.test(e.message)) throw e
+      try { onRetry?.(e, delay) } catch (_) {}
+      await new Promise((r) => setTimeout(r, delay))
+      delay = Math.min(maxRetryMs, Math.round(delay * 1.6))
+    }
+  }
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@dotrino/vaultd",
+  "version": "0.6.0",
+  "type": "module",
+  "description": "Certificador personal de Dotrino: daemon headless que custodia la clave maestra y delega capacidades a tus dispositivos por el proxy. Tu CA propia.",
+  "bin": {
+    "dotrino-vaultd": "bin/dotrino-vaultd.js",
+    "dotrino-vault-tui": "bin/dotrino-vault-tui.js",
+    "dotrino-vault": "bin/dotrino-vault.js"
+  },
+  "scripts": {
+    "start": "node bin/dotrino-vaultd.js",
+    "pair": "node bin/dotrino-vaultd.js --pair",
+    "tui": "node bin/dotrino-vault-tui.js",
+    "test": "node --test test/*.test.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@dotrino/identity": "^0.34.0",
+    "@dotrino/proxy-client": "0.8.0",
+    "ws": "^8.18.0"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/imdotrino/dotrino-vault.git"
+  },
+  "homepage": "https://vault.dotrino.com/",
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "vendor",
+    "lib/src"
+  ]
+}

package/src/client.js

@@ -0,0 +1,149 @@
+/**
+ * Cliente de DISPOSITIVO (lado del que consulta el vault). Pensado para Node
+ * (CLI/tests); en un dispositivo real (navegador/app) se usa el mismo flujo con
+ * `@dotrino/identity/capabilities` + `@dotrino/proxy-client`.
+ *
+ * Emparejamiento ENDURECIDO (docs/pairing-protocol.md): el dispositivo genera su
+ * sub-clave `D`, FIRMA el ENROLL con ella (prueba de posesión) y adjunta el COMPROMISO
+ * de un código de 6 dígitos que MUESTRA en pantalla (el código nunca viaja). El dueño lo
+ * tipea en la bóveda, que recompone el compromiso y solo entonces firma el cert; al
+ * recibirlo, el dispositivo comprueba que le ECHAN su código y VALIDA el cert
+ * estrictamente (firmado por la maestra que vio en el QR, y para SU clave) antes de
+ * guardarlo. La maestra nunca sale del vault.
+ */
+import { makeDeviceKey, signWithDevice, verifyDelegation, verifyDeviceSig, makePairingCode, commitCode, pubkeyId } from '@dotrino/identity/capabilities'
+import { installNodeGlobals } from './node-globals.js'
+import { MSG } from './protocol.js'
+
+async function freshClient ({ proxyUrl, dir = '.dotrino-vault-device' }) {
+  installNodeGlobals(dir)
+  const { WebSocketProxyClient } = await import('@dotrino/proxy-client')
+  const client = new WebSocketProxyClient({ url: proxyUrl, enableWebRTC: false, autoReconnect: false })
+  await client.connect()
+  return client
+}
+
+/** Identifica la conexión bajo la pubkey de dispositivo D (para ser direccionable). */
+async function identifyAsDevice (client, device) {
+  if (!client.token) return
+  const data = { op: 'identify', publickey: device.publickey, token: client.token, ts: Date.now() }
+  const { signature } = await signWithDevice({ privateJwk: device.privateJwk, data })
+  await client.identify({ data, signature })
+}
+
+function waitFor (client, predicate, timeoutMs = 30000) {
+  return new Promise((resolve, reject) => {
+    const off = client.on('message', (_from, payload) => {
+      if (payload && typeof payload === 'object' && predicate(payload)) { cleanup(); resolve(payload) }
+    })
+    const t = setTimeout(() => { cleanup(); reject(new Error('timeout esperando respuesta del vault')) }, timeoutMs)
+    const cleanup = () => { off(); clearTimeout(t) }
+  })
+}
+
+/**
+ * Enrola este dispositivo contra un vault (flujo endurecido).
+ * @param {Object} opts
+ * @param {{v:number, iss:string, proxy:string, token:string, sn:string}} opts.qr  QR v2 del vault.
+ * @param {string} [opts.label]
+ * @param {(c:{deviceId:string,code:string})=>void} [opts.onChallenge]  Para MOSTRAR el código que el usuario tipea en la bóveda.
+ * @param {number} [opts.approveTimeoutMs]  Cuánto esperar la aprobación humana (def 3 min).
+ * @returns {Promise<{ device, cert, iss:string }>}  GUARDAR `device` (incluye la privada) + `cert`. `iss` = qr.iss verificado.
+ */
+export async function enroll ({ qr, label = '', dir, onChallenge, approveTimeoutMs = 180000 } = {}) {
+  if (!qr?.iss || !qr?.proxy || !qr?.token || !qr?.sn) throw new Error('qr inválido (v2): faltan iss/proxy/token/sn')
+  const client = await freshClient({ proxyUrl: qr.proxy, dir })
+  try {
+    const device = await makeDeviceKey({ label })
+    const myDeviceId = (await pubkeyId(device.publickey)).slice(0, 8).toUpperCase().replace(/(.{4})(.{4})/, '$1-$2')
+    // ESTE dispositivo genera el código y lo MUESTRA; solo viaja su COMPROMISO. El vault
+    // lo aprende cuando un humano lo tipea, y solo firma el cert si el compromiso coincide.
+    const code = makePairingCode()
+    const commit = await commitCode({ code, dpub: device.publickey, sn: qr.sn })
+    // ENROLL firmado con D = prueba de posesión (un token robado ya no basta).
+    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 enrolled = 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: myDeviceId, code }) // el código lo genera y muestra ESTE dispositivo
+        } else if (p.type === MSG.ENROLLED) {
+          // Aceptamos solo si la bóveda ECHA nuestro código: una que no lo conoce no nos enrola.
+          if (String(p.code || '').trim() !== code) return
+          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')) }, approveTimeoutMs)
+      const cleanup = () => { off(); clearTimeout(t) }
+    })
+    client.sendByPubkey(qr.iss, { type: MSG.ENROLL, data, signature })
+    const res = await enrolled
+
+    // VALIDACIÓN ESTRICTA antes de persistir (cierra inyección de cert / sustitución de maestra).
+    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 una maestra distinta a la que viste (posible proxy malicioso)')
+    if (res.cert.sub !== device.publickey) throw new Error('cert emitido para otro dispositivo')
+    // OJO: devolvemos qr.iss (la maestra que el usuario VIO), NO res.iss.
+    return { device, cert: res.cert, iss: qr.iss }
+  } finally { client.close() }
+}
+
+/**
+ * Verifica que un mensaje REVOKED es AUTÉNTICO (firmado por la maestra pineada y
+ * para este dispositivo). SOLO si esto es true se debe ejecutar el self-wipe — un
+ * `MSG.ERROR` plano o una firma de otra clave JAMÁS borra (cierra el wipe-DoS).
+ */
+export async function verifyRevoke ({ body, signature, master, devicePubkey }) {
+  if (!body || body.op !== 'revoke' || body.sub !== devicePubkey) return false
+  if (typeof body.exp === 'number' && Date.now() > body.exp) return false
+  return verifyDeviceSig({ publickey: master, data: body, signature })
+}
+
+/** Pide a la maestra que firme `payload` (scope vault:sign). */
+export async function requestSign ({ masterPubkey, proxyUrl, device, cert, payload, dir } = {}) {
+  const client = await freshClient({ proxyUrl, dir })
+  try {
+    const data = { op: 'sign', payload, publickey: device.publickey, ts: Date.now() }
+    const { signature } = await signWithDevice({ privateJwk: device.privateJwk, data })
+    const pending = waitFor(client, (p) => p.type === MSG.SIGNED || p.type === MSG.ERROR)
+    client.sendByPubkey(masterPubkey, { type: MSG.SIGN, data, signature, cert })
+    const res = await pending
+    if (res.type === MSG.ERROR) throw new Error(res.error)
+    return { signature: res.signature, publickey: res.publickey }
+  } finally { client.close() }
+}
+
+/** Lee un nodo del árbol del vault (scope vault:read). */
+export async function requestGet ({ masterPubkey, proxyUrl, device, cert, id = 'root', dir } = {}) {
+  const client = await freshClient({ proxyUrl, dir })
+  try {
+    const data = { op: 'get', id, publickey: device.publickey, ts: Date.now() }
+    const { signature } = await signWithDevice({ privateJwk: device.privateJwk, data })
+    const pending = waitFor(client, (p) => p.type === MSG.DATA || p.type === MSG.ERROR)
+    client.sendByPubkey(masterPubkey, { type: MSG.GET, data, signature, cert })
+    const res = await pending
+    if (res.type === MSG.ERROR) throw new Error(res.error)
+    return { id: res.id, node: res.node }
+  } finally { client.close() }
+}
+
+/** Llama un método del store de hilos/aperturas del vault (scope vault:store). */
+export async function requestStore ({ masterPubkey, proxyUrl, device, cert, method, args, dir } = {}) {
+  const client = await freshClient({ proxyUrl, dir })
+  try {
+    const data = { op: 'store', method, args: args || {}, publickey: device.publickey, ts: Date.now() }
+    const { signature } = await signWithDevice({ privateJwk: device.privateJwk, data })
+    const pending = waitFor(client, (p) => p.type === MSG.STORE_RESULT || p.type === MSG.ERROR)
+    client.sendByPubkey(masterPubkey, { type: MSG.STORE, data, signature, cert })
+    const res = await pending
+    if (res.type === MSG.ERROR) throw new Error(res.error)
+    return res.result
+  } finally { client.close() }
+}
+
+export { identifyAsDevice }