@dotrino/vaultd 0.6.0

package/lib/src/enroll.js

@@ -0,0 +1,293 @@
+/**
+ * enroll.js — núcleo del LADO BÓVEDA del emparejamiento endurecido.
+ *
+ * Fuente ÚNICA del flujo `vault.enroll` → `vault.enroll.challenge` → `vault.enrolled`
+ * y de la revocación firmada. Lo consumen los tres sitios que hacen de bóveda:
+ *   · el daemon del PC            (`dotrino-vault/src/vault.js`)
+ *   · «este dispositivo es bóveda» (`lib/src/index.js#startDeviceVault`)
+ *   · la copia vendorizada del iframe de identidad (`dotrino-identity/vault/vendor/vault/`)
+ *
+ * Módulo PURO: sin `node:*`, sin red, sin disco. Recibe la identidad (que firma), un
+ * transporte (`send`/`sendByPubkey`) y callbacks de log/auditoría. Así el binario Node
+ * lo embebe al compilar (SEA), el navegador lo importa y el iframe lo vendoriza sin
+ * bundler.
+ *
+ * EL CÓDIGO DE APROBACIÓN, en detalle (esto es lo que hace seguro el emparejamiento):
+ *   1. El DISPOSITIVO genera un código aleatorio de 6 dígitos, lo MUESTRA en su pantalla
+ *      y manda solo su COMPROMISO `SHA-256(code‖dpub‖sn)` dentro del `data` firmado.
+ *      El código en sí NUNCA viaja.
+ *   2. La bóveda no conoce el código: lo aprende cuando un humano lo TIPEA al aprobar.
+ *   3. Al aprobar, la bóveda RECOMPUTA el compromiso con el código tipeado y solo firma
+ *      el cert si coincide → aprobar exige haber ido a leer el código del dispositivo.
+ *   4. La bóveda ECHA el código junto al cert; el dispositivo lo acepta solo si es el
+ *      suyo → una bóveda falsa (que nunca vio el código) no puede enrolarlo.
+ *
+ * Qué cierra y qué NO (sin exagerar): cierra que se emita un cert sin que quien aprueba
+ * tenga el código del dispositivo — antes se firmaba igual y la defensa vivía solo en el
+ * cliente honesto, así que un cliente malicioso se quedaba con un cert válido. NO cierra
+ * el phishing en el que alguien le DICTA el código al dueño por otro canal: contra eso
+ * está la copy de advertencia y que el dueño reconozca el `deviceId` (residual A1/A2 de
+ * `docs/pairing-protocol.md`).
+ */
+import { verifyDeviceSig, pubkeyId, commitCode } from '@dotrino/identity/capabilities'
+import { verifyContinuity } from '@dotrino/identity/acta'
+
+/** Un token de emparejamiento vale 5 min. */
+export const PAIRING_TTL_MS = 5 * 60 * 1000
+/** Ventana anti-replay del ENROLL (±5 min), mismo criterio que el identify del proxy. */
+export const FRESH_WINDOW_MS = 5 * 60 * 1000
+/** Vida por defecto del cert de un dispositivo (tope duro de `MAX_DELEGATION_MS`). */
+export const DEVICE_TTL_MS = 30 * 24 * 60 * 60 * 1000
+
+export const MSG_ENROLL = 'vault.enroll'
+export const MSG_ENROLL_CHALLENGE = 'vault.enroll.challenge'
+export const MSG_ENROLLED = 'vault.enrolled'
+export const MSG_REVOKED = 'vault.revoked'
+export const MSG_ERROR = 'vault.error'
+
+/** Los scopes del cert se corresponden 1:1 con las capacidades del acta (§D7). */
+const SCOPE_TO_CAP = { 'vault:sign': 'sign', 'vault:store': 'store', 'vault:read': 'read' }
+export const scopeToCaps = (scope) =>
+  (Array.isArray(scope) ? scope : [scope]).map((s) => SCOPE_TO_CAP[s]).filter(Boolean)
+
+/**
+ * El CN de un servicio sale de su scope: `vault:secrets:proxy` ⇒ CN `proxy`. Con CN, el
+ * miembro entra al acta como SERVICIO —solo abre su propio cajón— en vez de como un
+ * dispositivo del usuario. Es la frontera, y vive en el acta para que se pueda comprobar.
+ */
+export function scopeToCn (scope) {
+  for (const s of (Array.isArray(scope) ? scope : [scope])) {
+    const m = /^vault:secrets:([a-z0-9-]{1,32})$/.exec(String(s || ''))
+    if (m) return m[1]
+  }
+  return null
+}
+
+/** Token aleatorio de 128 bits en hex. */
+export 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`) a partir de una pubkey JWK. */
+export async function deviceIdOf (pub) {
+  const id = (await pubkeyId(pub)).slice(0, 8).toUpperCase()
+  return id.slice(0, 4) + '-' + id.slice(4, 8)
+}
+
+/**
+ * Crea el «mostrador» de emparejamiento de una bóveda.
+ *
+ * @param {Object} opts
+ * @param {Object} opts.identity        firma: `signData`, `signDelegation`, `listDelegations`, `revokeDelegation`.
+ * @param {string} opts.iss             pubkey de la maestra de ESTA bóveda (va en el QR).
+ * @param {string} opts.proxy           URL del proxy (va en el QR).
+ * @param {(to:string, obj:object)=>void} opts.send            responder por el token de la conexión.
+ * @param {(pub:string, obj:object)=>void} opts.sendByPubkey   dirigir por pubkey (cola offline 24 h).
+ * @param {(op:string, info?:object)=>void} [opts.audit]
+ * @param {(...a:any[])=>void} [opts.log]
+ * @param {(c:{deviceId:string, scope:any, label:string})=>void} [opts.onChallenge]  un dispositivo espera aprobación.
+ * @param {()=>void} [opts.onPendingChange]
+ * @param {string[]} [opts.defaultScope]
+ * @param {number} [opts.defaultTtlMs]
+ */
+export function createEnrollDesk ({
+  identity, iss, proxy, send, sendByPubkey,
+  audit = () => {}, log = () => {},
+  onChallenge = () => {}, onPendingChange = () => {},
+  defaultScope = ['vault:sign'], defaultTtlMs = DEVICE_TTL_MS
+} = {}) {
+  if (!identity) throw new Error('createEnrollDesk: falta identity')
+  if (!iss) throw new Error('createEnrollDesk: falta iss (pubkey de la maestra)')
+
+  // token -> { token, exp, scope, ttlMs, label, sn, state, dpub?, deviceId?, commit?, from? }
+  // state: 'AWAITING_ENROLL' -> 'PENDING_CONFIRM'
+  const pending = new Map()
+
+  const fire = (fn, arg) => { try { fn(arg) } catch (_) {} }
+  const reply = (to, obj) => { try { send(to, obj) } catch (e) { log('[vault] no se pudo responder:', e.message) } }
+  const isFresh = (d) => typeof d?.ts === 'number' && Math.abs(Date.now() - d.ts) <= FRESH_WINDOW_MS
+
+  /** Inicia un emparejamiento: token + nonce de sesión. NO firma nada todavía. */
+  function startPairing ({ scope = defaultScope, ttlMs = defaultTtlMs, label = '' } = {}) {
+    pending.clear() // uno a la vez: una sesión nueva supersede a la anterior
+    const token = randToken()
+    const sn = randToken()
+    pending.set(token, { token, exp: Date.now() + PAIRING_TTL_MS, scope, ttlMs, label, sn, state: 'AWAITING_ENROLL' })
+    return { token, qr: { v: 2, iss, proxy, token, sn }, expiresInMs: PAIRING_TTL_MS }
+  }
+
+  function stopPairing (token) { pending.delete(token) }
+
+  function listPending () {
+    return [...pending.values()]
+      .filter((p) => p.state === 'PENDING_CONFIRM')
+      .map((p) => ({ deviceId: p.deviceId, label: p.label || '', scope: p.scope }))
+  }
+
+  function findPending (deviceId) {
+    for (const p of pending.values()) {
+      if (p.state === 'PENDING_CONFIRM' && p.deviceId === deviceId) return p
+    }
+    return null
+  }
+
+  /**
+   * ENROLL: el dispositivo prueba posesión de `D` firmando el sobre y deja el
+   * COMPROMISO de su código. Todavía NO se firma ningún cert.
+   */
+  async function handleEnroll (from, p) {
+    const d = p?.data
+    if (!d || typeof d.dpub !== 'string' || typeof p.signature !== 'string') {
+      return reply(from, { type: MSG_ERROR, error: 'enroll inválido' })
+    }
+    const pend = pending.get(d.token)
+    if (!pend || pend.state === 'DONE' || Date.now() > pend.exp) {
+      return reply(from, { type: MSG_ERROR, error: 'token de emparejamiento inválido o expirado' })
+    }
+    if (d.sn !== pend.sn) return reply(from, { type: MSG_ERROR, error: 'sesión inválida' })
+    if (!isFresh(d)) {
+      audit('rejected', { what: 'enroll', reason: 'stale' })
+      return reply(from, { type: MSG_ERROR, error: 'petición vencida: ts fuera de la ventana ±5 min (posible replay, o el reloj del dispositivo está desfasado)' })
+    }
+    // PRUEBA DE POSESIÓN: la firma de `data` debe verificar contra `dpub`.
+    if (!(await verifyDeviceSig({ publickey: d.dpub, data: d, signature: p.signature }))) {
+      audit('rejected', { what: 'enroll', reason: 'bad-device-signature' })
+      return reply(from, { type: MSG_ERROR, error: 'firma de dispositivo inválida' })
+    }
+    // El COMPROMISO del código es obligatorio: sin él no se puede comprobar al aprobar
+    // y volveríamos a emitir certs a ciegas. Un cliente viejo cae acá con un mensaje claro.
+    if (typeof d.commit !== 'string' || !/^[0-9a-f]{64}$/.test(d.commit)) {
+      audit('rejected', { what: 'enroll', reason: 'no-commit' })
+      return reply(from, { type: MSG_ERROR, error: 'este dispositivo usa una versión antigua del emparejamiento (no envía el compromiso del código). Actualízalo y vuelve a intentarlo.' })
+    }
+    // Un solo dispositivo a la vez esperando su código (así aprobar no es ambiguo).
+    if (pend.state === 'PENDING_CONFIRM' && pend.dpub && pend.dpub !== d.dpub) {
+      return reply(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.commit = d.commit
+    // Llave de CIFRADO del dispositivo: con ella se le envuelve la clave de contenido del
+    // perfil al admitirlo. Sin ella entra, pero no podrá leer lo que haya guardado.
+    if (typeof d.encPub === 'string') pend.encPub = d.encPub
+    // Certificado de continuidad (opcional): lo firma la identidad que se une, con su
+    // propia llave. Se comprueba aquí y se guarda con el miembro al aprobar.
+    if (d.continuity) {
+      const okC = await verifyContinuity(d.continuity)
+      pend.continuity = (okC && d.continuity.member === d.dpub) ? d.continuity : null
+    }
+    pend.from = from // la bóveda NO conoce el código: lo aprende cuando lo tipeas
+    if (d.label) pend.label = String(d.label).slice(0, 60)
+
+    reply(from, { type: MSG_ENROLL_CHALLENGE, deviceId })
+    fire(onChallenge, { deviceId, scope: pend.scope, label: pend.label || '' })
+    fire(onPendingChange)
+    return { deviceId }
+  }
+
+  /**
+   * Aprueba TIPEANDO el código que muestra el dispositivo. Recompone el compromiso
+   * `SHA-256(code‖dpub‖sn)` y solo firma el cert si coincide con el que llegó en el
+   * ENROLL — es decir, solo si de verdad fuiste a leer el código del dispositivo.
+   *
+   * @param {string} code
+   * @param {{deviceId?: string}} [opts]  cuál aprobar cuando hay varios pendientes.
+   */
+  async function approve (code, { deviceId } = {}) {
+    code = String(code || '').trim()
+    if (!code) throw new Error('falta el código (los dígitos que muestra el dispositivo)')
+
+    let pend
+    if (deviceId) {
+      pend = findPending(deviceId)
+      if (!pend) throw new Error('no hay ninguna máquina esperando aprobación con ese identificador')
+    } else {
+      const waiting = [...pending.values()].filter((p) => p.state === 'PENDING_CONFIRM' && p.dpub)
+      if (waiting.length === 0) throw new Error('no hay ningún dispositivo esperando aprobación')
+      if (waiting.length > 1) throw new Error('hay más de un emparejamiento en curso; reinícialo con dotrino-vault pair')
+      pend = waiting[0]
+    }
+
+    // COMPROBACIÓN DEL CÓDIGO — antes de firmar nada.
+    const expected = await commitCode({ code, dpub: pend.dpub, sn: pend.sn })
+    if (expected !== pend.commit) {
+      audit('rejected', { what: 'approve', device: pend.deviceId, reason: 'bad-code' })
+      log('[vault] código incorrecto para %s: no se emitió ningún certificado', pend.deviceId)
+      throw new Error('el código no coincide con el que muestra el dispositivo: no se emitió ningún certificado. Vuelve a mirarlo y prueba otra vez.')
+    }
+
+    const { cert } = await identity.signDelegation(pend.dpub, pend.scope, { ttlMs: pend.ttlMs, label: pend.label })
+
+    // Aprobar un emparejamiento ES admitir al dispositivo en el perfil: el cert es la
+    // credencial y el acta es la política, y no tiene sentido emitir una sin la otra.
+    // Las capacidades salen del scope que se pidió al emparejar (cert ∩ acta, §2.3).
+    let acta = null
+    try {
+      if (typeof identity.admitMember === 'function') {
+        const cn = scopeToCn(pend.scope)
+        const caps = cn ? ['secrets'] : scopeToCaps(pend.scope)
+        if (caps.length) await identity.admitMember({ pub: pend.dpub, encPub: pend.encPub || null, label: pend.label || '', cn, caps, cert, continuity: pend.continuity || null })
+      }
+      acta = (await identity.profileActa?.())?.acta || null
+    } catch (e) { log('[vault] no se pudo admitir en el acta:', e.message) }
+
+    audit('enroll', { device: pend.deviceId, label: pend.label || '', scope: pend.scope })
+    // Echamos el código tipeado junto al cert: el DISPOSITIVO acepta solo si coincide
+    // con el que generó → una bóveda falsa (que no lo conoce) no puede enrolarlo.
+    // El acta viaja con el cert: el dispositivo ya sabe de quién es el perfil al que entra.
+    reply(pend.from, { type: MSG_ENROLLED, code, cert, iss, acta })
+    pend.state = 'DONE'
+    pending.delete(pend.token)
+    fire(onPendingChange)
+    log('[vault] dispositivo aprobado: %s', pend.deviceId)
+    return { ok: true, deviceId: pend.deviceId, cert }
+  }
+
+  /** Rechaza un enrolamiento pendiente. */
+  function reject (deviceId) {
+    const pend = deviceId
+      ? findPending(deviceId)
+      : [...pending.values()].find((p) => p.state === 'PENDING_CONFIRM')
+    if (!pend) return { ok: false }
+    reply(pend.from, { type: MSG_ERROR, error: 'emparejamiento rechazado' })
+    pending.delete(pend.token)
+    audit('reject', { device: pend.deviceId })
+    fire(onPendingChange)
+    log('[vault] dispositivo rechazado: %s', pend.deviceId)
+    return { ok: true, deviceId: pend.deviceId }
+  }
+
+  /**
+   * Emite un REVOKED FIRMADO por la maestra para que el dispositivo se autoborre. El
+   * borrado remoto SOLO se dispara con esta firma (nunca con un error cualquiera →
+   * cierra el wipe-DoS). Va por `sendByPubkey`: si está apagado, el proxy lo encola 24 h.
+   */
+  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 { sendByPubkey(dpub, { type: MSG_REVOKED, body, signature }) }
+    catch (e) { log('[vault] no se pudo emitir revoke:', e.message) }
+  }
+
+  /** Revoca una delegación por `nonce` y avisa al dispositivo para que se autoborre. */
+  async function revoke (nonce) {
+    audit('revoke', { nonce })
+    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 {
+    startPairing, stopPairing, handleEnroll, approve, reject,
+    listPending, findPending, emitRevoke, revoke,
+    get pendingCount () { return pending.size }
+  }
+}
+
+export default { createEnrollDesk, deviceIdOf, randToken }

package/lib/src/env.js

@@ -0,0 +1,95 @@
+/**
+ * `@dotrino/vault/env` — el "dotenv contra el vault".
+ *
+ * Un proyecto Node cualquiera obtiene sus credenciales del vault del dueño en
+ * vez de llevarlas en un `.env`:
+ *
+ *   import { loadEnv } from '@dotrino/vault/env'
+ *   await loadEnv({ ns: 'miapp' })          // → process.env.API_KEY, …
+ *
+ * o, con la forma clásica de dotenv (side-effect, ns por `DOTRINO_NS`):
+ *
+ *   import '@dotrino/vault/config'
+ *
+ * Lo que queda en el disco del servicio NO es un secreto: es la llave del
+ * dispositivo (generada aquí, nunca sale) y un certificado con scope
+ * `vault:secrets:<ns>`. Los valores solo viven en memoria del proceso; si la
+ * máquina se compromete, se revoca el cert y no había nada que robar.
+ *
+ * Enrolar una vez:  npx dotrino-env enroll --ns miapp   (ver bin/dotrino-env.js)
+ */
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { fetchSecrets, waitForSecrets, readServiceIdentity } from './service.js'
+import { isValidSecretsNs } from './protocol.js'
+
+/** Raíz donde viven las identidades de servicio de esta máquina/usuario. */
+export function serviceRoot () {
+  return process.env.DOTRINO_ENV_HOME || path.join(os.homedir(), '.dotrino', 'service')
+}
+
+/** Directorio de la identidad del servicio `ns` (`DOTRINO_ENV_DIR` lo pisa). */
+export function serviceDir (ns) {
+  if (process.env.DOTRINO_ENV_DIR) return process.env.DOTRINO_ENV_DIR
+  if (!isValidSecretsNs(ns)) throw new Error('ns inválido (usa [a-z0-9-]{1,32}, p. ej. "miapp")')
+  return path.join(serviceRoot(), ns)
+}
+
+/** Namespaces ya enrolados en esta máquina. */
+export function listEnrolled () {
+  let names = []
+  try { names = fs.readdirSync(serviceRoot()) } catch (_) { return [] }
+  return names.filter((ns) => isValidSecretsNs(ns) && readServiceIdentity(path.join(serviceRoot(), ns)))
+}
+
+/**
+ * Resuelve el ns cuando no se pasa explícito: `DOTRINO_NS`, y si no, el único
+ * enrolado en esta máquina. Con varios, exige elegir (no adivinamos).
+ */
+export function resolveNs (ns) {
+  ns = ns || process.env.DOTRINO_NS
+  if (ns) {
+    if (!isValidSecretsNs(ns)) throw new Error('ns inválido: ' + ns)
+    return ns
+  }
+  const found = listEnrolled()
+  if (found.length === 1) return found[0]
+  if (found.length === 0) {
+    throw new Error('no hay ningún servicio enrolado en esta máquina: corre `npx dotrino-env enroll --ns <tu-app>`')
+  }
+  throw new Error(`hay varios servicios enrolados (${found.join(', ')}): elige uno con DOTRINO_NS=<ns> o loadEnv({ ns })`)
+}
+
+/**
+ * Trae los secretos del ns desde el vault y los pone en `process.env`.
+ *
+ * @param {Object} [opts]
+ * @param {string} [opts.ns]         Namespace (por defecto: `DOTRINO_NS` o el único enrolado).
+ * @param {string} [opts.dir]        Dónde está `service-identity.json` (por defecto: `serviceDir(ns)`).
+ * @param {boolean} [opts.override]  `true` = pisa variables ya presentes en el entorno (default: no).
+ * @param {boolean} [opts.wait]      `true` (default) = si el vault no está, ESPERA (reintenta) en vez de fallar.
+ * @param {string[]} [opts.required] Claves que deben venir; si falta alguna, lanza.
+ * @param {(e:Error, ms:number)=>void} [opts.onRetry]
+ * @returns {Promise<{ns:string, secrets:Record<string,string>, injected:string[], skipped:string[]}>}
+ */
+export async function loadEnv ({ ns, dir, override = false, wait = true, required = [], onRetry } = {}) {
+  ns = resolveNs(ns)
+  dir = dir || serviceDir(ns)
+  const load = wait ? waitForSecrets : fetchSecrets
+  const secrets = await load({ dir, ns, onRetry })
+
+  const missing = required.filter((k) => !(k in secrets))
+  if (missing.length) {
+    throw new Error(`faltan secretos en el ns "${ns}": ${missing.join(', ')} (agrégalos con \`dotrino-vault secret set ${ns} <CLAVE> <valor>\`)`)
+  }
+
+  const injected = []
+  const skipped = []
+  for (const [k, v] of Object.entries(secrets)) {
+    if (!override && k in process.env) { skipped.push(k); continue }
+    process.env[k] = String(v)
+    injected.push(k)
+  }
+  return { ns, secrets, injected, skipped }
+}

package/lib/src/index.js

@@ -0,0 +1,166 @@
+/**
+ * @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.
+ *
+ * El flujo de enrolamiento en sí (incluida la comprobación del código antes de firmar) vive
+ * en `./enroll.js`, COMPARTIDO con el daemon del PC y con la copia vendorizada del iframe:
+ * un solo sitio donde se decide a quién se le emite un certificado.
+ *
+ * Cripto 100% de `@dotrino/identity/capabilities`; firma con la identidad P
+ * (`identity.signDelegation`). Transporte: `@dotrino/proxy-client` (import perezoso).
+ * No reimplementa nada del ecosistema.
+ */
+import { verifyChain } from '@dotrino/identity/capabilities'
+import { createEnrollDesk, deviceIdOf, DEVICE_TTL_MS, FRESH_WINDOW_MS } from './enroll.js'
+
+const SIGN_SCOPE = 'vault:sign'
+const SELFCERT_TTL_MS = 24 * 60 * 60 * 1000    // el self-cert P←P se regenera cada 24 h
+
+const MSG = {
+  ENROLL: 'vault.enroll',
+  DEVICES: 'vault.devices',
+  DEVICES_RESULT: 'vault.devices.result',
+  ERROR: 'vault.error'
+}
+
+/** deviceId legible (p. ej. `C440-AC0E`) desde una pubkey JWK. */
+export { deviceIdOf }
+
+/**
+ * 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 (_) {} }
+
+  let _onPendingChange = () => {}
+
+  // ENROLL / aprobación / revocación: núcleo COMPARTIDO con el daemon del PC y con la
+  // copia vendorizada del iframe (`lib/src/enroll.js`). Un solo sitio donde vive el
+  // flujo → y por lo tanto un solo sitio donde se comprueba el código antes de firmar.
+  const desk = createEnrollDesk({
+    identity,
+    iss,
+    proxy,
+    send,
+    sendByPubkey: (pub, obj) => { try { client.sendByPubkey(pub, obj) } catch (_) {} },
+    defaultScope: [SIGN_SCOPE],
+    defaultTtlMs: DEVICE_TTL_MS,
+    onPendingChange: () => _onPendingChange()
+  })
+
+  // 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) desk.emitRevoke(chk.device, mine.nonce)
+  }
+
+  client.on('message', (_from, p) => {
+    if (!p || typeof p !== 'object') return
+    if (p.type === MSG.ENROLL) desk.handleEnroll(_from, p).catch(() => {})
+    else if (p.type === MSG.DEVICES) handleDevices(_from, p).catch(() => {})
+  })
+
+  /**
+   * 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) })))
+  }
+
+  return {
+    iss, proxy, client,
+    startPairing: desk.startPairing,
+    // Aprueba TIPEANDO el código que muestra la máquina: el núcleo compartido recompone
+    // el compromiso `SHA-256(code‖dpub‖sn)` y solo firma el cert si coincide.
+    approve: (deviceId, code) => desk.approve(code, { deviceId }),
+    reject: (deviceId) => desk.reject(deviceId),
+    listPending: desk.listPending,
+    listMachines,
+    // Revoca 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).
+    revoke: (nonce) => desk.revoke(nonce),
+    getSelfCert,
+    onPendingChange (fn) { _onPendingChange = fn || (() => {}) },
+    close () { try { client.close() } catch (_) {} }
+  }
+}
+
+export default { startDeviceVault, deviceIdOf }

package/lib/src/protocol.js

@@ -0,0 +1,53 @@
+/**
+ * Protocolo de mensajes entre un dispositivo y el vault (viajan por el proxy,
+ * direccionados por pubkey con `sendByPubkey`). El cuerpo va JSON-serializado en
+ * el campo `message` del sobre del proxy; el cliente lo entrega ya parseado.
+ *
+ * Emparejamiento ENDURECIDO (ver dotrino-vault/docs/pairing-protocol.md):
+ *   1. dispositivo → vault   ENROLL { data:{op,dpub,token,sn,label,ts}, signature }
+ *      (la firma es del dispositivo con su llave D = PRUEBA DE POSESION; un token
+ *       robado ya NO basta para enrolar).
+ *   2. vault → dispositivo   ENROLL_CHALLENGE { deviceId, sas }   (aun NO firma cert)
+ *   3. el dueño compara el SAS (pantalla del dispositivo ↔ del PC) y APRUEBA en el PC
+ *   4. vault → dispositivo   ENROLLED { cert, iss, sas }   (recien aqui firma el cert)
+ *   5. el dispositivo VALIDA la cadena: cert.iss === el iss que vio, cert.sub === D.
+ *
+ * Revocacion (robo): el vault envia REVOKED { body, signature } FIRMADO por la
+ * maestra → el dispositivo se autoborra SOLO si la firma valida contra la maestra
+ * pineada (cierra el wipe-DoS; un ERROR plano jamas borra).
+ */
+export const MSG = Object.freeze({
+  ENROLL: 'vault.enroll',                     // dispositivo → vault: { data, signature }
+  ENROLL_CHALLENGE: 'vault.enroll.challenge', // vault → dispositivo: { deviceId, sas }
+  ENROLLED: 'vault.enrolled',                 // vault → dispositivo (tras aprobar): { cert, iss, sas }
+  REVOKED: 'vault.revoked',                   // vault → dispositivo: { body:{op,sub,nonce,iat,exp}, signature }
+  SIGN: 'vault.sign',                         // dispositivo → vault: { data, signature, cert }
+  SIGNED: 'vault.signed',                     // vault → dispositivo: { signature, publickey, device }
+  GET: 'vault.get',                           // dispositivo → vault: { data, signature, cert }
+  DATA: 'vault.data',                         // vault → dispositivo: { id, node }
+  STORE: 'vault.store',                       // dispositivo → vault: { data:{method,args,publickey,ts}, signature, cert }
+  STORE_RESULT: 'vault.store.result',         // vault → dispositivo: { method, result }
+  DEVICES: 'vault.devices',                   // dispositivo → vault: { data:{publickey,ts}, signature, cert }
+  DEVICES_RESULT: 'vault.devices.result',     // vault → dispositivo: { devices, revoked }
+  RENEW: 'vault.renew',                       // dispositivo → vault: { data:{op,publickey,ts}, signature, cert }
+  RENEWED: 'vault.renewed',                   // vault → dispositivo: { cert }  (cert fresco, misma sub-clave/scope)
+  SECRETS: 'vault.secrets',                   // servicio → vault: { data:{op,ns,ek,publickey,ts}, signature, cert }
+  SECRETS_RESULT: 'vault.secrets.result',     // vault → servicio: { body:{op,ns,enc,ts}, signature } (enc SELLADO a ek; body firmado por la maestra)
+  ERROR: 'vault.error'                        // vault → dispositivo: { error }
+})
+
+/** Capacidades que puede llevar un `cert` (scope). Mínimo por defecto. */
+export const SCOPE = Object.freeze({
+  SIGN: 'vault:sign',   // pedir a la maestra que firme datos (identidad)
+  READ: 'vault:read',   // leer nodos del árbol de contenidos
+  STORE: 'vault:store'  // leer/escribir el store de hilos + aperturas del usuario
+})
+
+/**
+ * Scope de SECRETOS por namespace de servicio: un cert con `vault:secrets:proxy`
+ * solo puede leer los secretos del ns `proxy` — un VPS comprometido no puede
+ * pedir los de otro servicio. ns válido: [a-z0-9-]{1,32}.
+ */
+export const SECRETS_SCOPE_PREFIX = 'vault:secrets:'
+export const secretsScope = (ns) => SECRETS_SCOPE_PREFIX + ns
+export const isValidSecretsNs = (ns) => typeof ns === 'string' && /^[a-z0-9-]{1,32}$/.test(ns)