@dotrino/vault 0.16.0 → 0.18.0

package/README.md

@@ -234,16 +234,37 @@ pineada en el enrolamiento.
 
 `startDeviceVault(identity, { proxyUrl? }) → Promise<handle>`
 
-- `startPairing({ scope?, ttlMs?, label? }) → { qr, expiresInMs }`
+- `startPairing({ scope?, ttlMs?, label?, mode?, account? }) → { qr, expiresInMs }`
+- `stopPairing(token)`
 - `listPending() → [{ deviceId, label }]`
 - `approve(deviceId, code) → Promise<{ ok, deviceId }>`  (code = lo que muestra el dispositivo)
 - `reject(deviceId)`
 - `listMachines() → Promise<[{ sub, deviceId, label, scope, exp, nonce }]>`
 - `revoke(nonce) → Promise`
 - `getSelfCert() → Promise<cert>`  (self-cert `P ← P`, para actuar además de cliente)
-- `onPendingChange(fn)`, `close()`
+- `onPendingChange(fn)`, `onAdopted(fn)`, `close()`
 
 Cripto y firma: `@dotrino/identity`. Transporte: `@dotrino/proxy-client`. No reimplementa
 nada del ecosistema.
 
+### Qué atiende, y qué NO
+
+Esta bóveda **no es** el daemon del PC: comparte el núcleo de enrolamiento
+(`lib/src/enroll.js`, el mismo archivo), pero atiende menos mensajes del protocolo.
+
+Atiende: `vault.hello` (la llave que pide el QR corto), `vault.enroll` +
+`vault.acta.sealed` (enrolar y adoptar), `vault.renew` (**renovación automática** del
+cert de una máquina vigente: sin esto toda máquina enrolada caducaba a los 30 días) y
+`vault.devices` (lista + revocados, con re-emisión del `REVOKED` firmado).
+
+**No** atiende, y hoy solo existen contra el daemon `dotrino-vault`:
+
+| Falta | Qué implica |
+|---|---|
+| `vault.sign` | una máquina no puede pedirle a la maestra que firme por ella |
+| `vault.store` / `vault.get` | no hay store centralizado, ni edición de perfil, ni clave de contenido |
+| `vault.secrets` | `@dotrino/vault/config` (el reemplazo del `.env`) **no funciona** contra un dispositivo |
+| `vault.admin` | sin consola remota |
+| bitácora, cifrado en reposo, candado, multi-perfil | son del daemon; en el navegador dependen de `@dotrino/identity` |
+
 MIT · parte de [Dotrino](https://dotrino.com).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotrino/vault",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "Usa ESTE dispositivo (navegador) como bóveda/CA del ecosistema Dotrino: atiende enrolamientos por el proxy y firma certificados de delegación a tus máquinas. Incluye el cliente de SERVICIO (Node): un proyecto se enrola una vez y jala sus credenciales del vault en vez del .env (`import '@dotrino/vault/config'`).",
   "type": "module",
   "main": "src/index.js",

package/src/admin.js

@@ -0,0 +1,146 @@
+/**
+ * admin.js — CONSOLA REMOTA: administrar el perfil desde un dispositivo emparejado.
+ *
+ * Diseño: `dotrino-vault/docs/consola-remota.md`. Módulo PURO (sin `node:*`, sin red,
+ * sin disco), igual que `enroll.js`, para que lo puedan usar el daemon del PC y «este
+ * dispositivo es bóveda» sin duplicar la regla.
+ *
+ * QUÉ SE DELEGA Y QUÉ NO — esto es el módulo entero, el resto es plomería:
+ *
+ *   sí  · ver el acta y la bitácora · iniciar un emparejamiento (mostrar el QR)
+ *       · APROBAR o rechazar a quien entra · REVOCAR a un miembro
+ *   no  · cambiar permisos · traspasar el mando · conceder `admin`
+ *       · nada de los secretos de servicios
+ *
+ * La frontera no es un capricho: un admin puede **admitir y expulsar**, pero no
+ * reescribir quién manda. Así un aparato con `admin` robado hace daño **acotado y
+ * reversible** (se le revoca) en vez de poder traspasarse el mando y dejar al dueño
+ * fuera de su propia cuenta, que no tiene vuelta atrás. Las operaciones que no se
+ * delegan **no existen como mensaje**: no hay nada que autorizar mal.
+ *
+ * POR QUÉ APROBAR A DISTANCIA NO DEBILITA EL EMPAREJAMIENTO: el código de 6 dígitos es
+ * un COMPROMISO (`enroll.js`) — lo genera y lo MUESTRA el aparato que entra, y la bóveda
+ * solo firma si el código tecleado lo recompone. Aprobar exige haber leído la pantalla
+ * del aparato nuevo, se haga desde el PC o desde el teléfono. Lo que cambia es dónde
+ * está el humano, no qué tiene que demostrar.
+ */
+
+/** Las únicas operaciones que existen a distancia. Lista cerrada, como las capacidades. */
+export const ADMIN_OPS = Object.freeze(['pending', 'pair', 'approve', 'reject', 'revoke', 'audit'])
+
+/** Cuánto se recuerda un nonce ya usado (el doble de la ventana de frescura). */
+export const ADMIN_NONCE_TTL_MS = 10 * 60 * 1000
+
+/** Tope de entradas de bitácora por petición. */
+export const AUDIT_MAX = 500
+
+/**
+ * @param {Object} o
+ * @param {Object} o.desk                mostrador de emparejamiento (`createEnrollDesk`).
+ * @param {(scope:string[])=>Promise<any>} o.verify  verifica cadena+cert; devuelve `{ok, device, reason}`.
+ * @param {(limit:number)=>any[]} o.readActivity     últimas entradas de la bitácora.
+ * @param {(pub:string)=>Promise<string>} o.deviceIdOf
+ * @param {(ev:string, info?:object)=>Promise<void>} [o.notify]  aviso a todos los miembros.
+ * @param {(op:string, info?:object)=>void} [o.audit]
+ * @param {string[]} [o.defaultScope]    lo que recibe un dispositivo emparejado a distancia.
+ * @param {number} [o.ttlMs]             vida del cert que se emita.
+ */
+export function createAdminDesk ({
+  desk, verify, readActivity = () => [], deviceIdOf,
+  notify = async () => {}, audit = () => {},
+  defaultScope = ['vault:sign', 'vault:read', 'vault:store'],
+  ttlMs, now = () => Date.now()
+}) {
+  const ops = new Set(ADMIN_OPS)
+
+  // NONCE de un solo uso. `sign`/`get` son idempotentes y les basta la ventana de ±5
+  // min; `approve` y `revoke` CAMBIAN ESTADO, así que reproducir uno dentro de esa
+  // ventana sí importa (re-aprobar un enrolamiento que el dueño ya rechazó, por
+  // ejemplo). Por eso el nonce, y por eso es obligatorio en todas las ops: una lista
+  // de excepciones es una invitación a equivocarse.
+  const seen = new Map()
+  function nonceAlreadyUsed (nonce) {
+    const t = now()
+    for (const [n, exp] of seen) if (exp <= t) seen.delete(n)
+    if (seen.has(nonce)) return true
+    seen.set(nonce, t + ADMIN_NONCE_TTL_MS)
+    return false
+  }
+
+  /**
+   * Atiende una petición ya verificada como *fresca*. Devuelve `{ ok, result }` o
+   * `{ ok: false, error }` — quien llama se encarga de responder por el transporte.
+   */
+  async function handle (data, { signature, cert } = {}) {
+    if (!data || !ops.has(data.op)) return { ok: false, error: 'admin: invalid operation' }
+    if (typeof data.nonce !== 'string' || data.nonce.length < 16) {
+      return { ok: false, error: 'admin: missing single-use nonce' }
+    }
+
+    const chk = await verify({ data, signature, cert })
+    if (!chk?.ok) {
+      audit('rejected', { what: 'admin', op: data.op, reason: chk?.reason })
+      return { ok: false, error: 'unauthorized: ' + (chk?.reason || 'cert') }
+    }
+    const by = await deviceIdOf(chk.device).catch(() => null)
+
+    // El nonce se marca DESPUÉS de autorizar: si no, cualquiera podría quemarle los
+    // nonces a un admin legítimo mandando basura firmada por nadie.
+    if (nonceAlreadyUsed(data.nonce)) {
+      audit('rejected', { what: 'admin', op: data.op, by, reason: 'replay' })
+      return { ok: false, error: 'admin: nonce already used' }
+    }
+
+    try {
+      if (data.op === 'pending') return { ok: true, result: { pending: desk.listPending() } }
+
+      if (data.op === 'audit') {
+        const limit = Math.min(Math.max(Number(data.limit) || 100, 1), AUDIT_MAX)
+        return { ok: true, result: { entries: readActivity(limit) } }
+      }
+
+      if (data.op === 'pair') {
+        // Un admin NO empareja servicios ni crea otros admins. Se corta aquí, en la
+        // bóveda, no en la interfaz: una pantalla no es un control de seguridad.
+        const scope = Array.isArray(data.scope) && data.scope.length ? data.scope : defaultScope
+        const forbidden = scope.find((s) => s === 'vault:admin' || String(s).startsWith('vault:secrets:'))
+        if (forbidden) {
+          audit('rejected', { what: 'admin', op: 'pair', by, reason: 'forbidden-scope', scope: forbidden })
+          return { ok: false, error: 'admin: cannot grant admin or service secrets from here; do that on the vault machine' }
+        }
+        const label = String(data.label || '').slice(0, 60) || 'remoto'
+        const r = await desk.startPairing({ scope, label, ...(ttlMs ? { ttlMs } : {}) })
+        audit('admin.pair', { by })
+        return { ok: true, result: r }
+      }
+
+      if (data.op === 'approve') {
+        const r = await desk.approve(String(data.code || ''), { deviceId: data.deviceId })
+        audit('admin.approve', { by, device: data.deviceId || null })
+        await notify('enrolled', { deviceId: r?.deviceId || data.deviceId || null, by })
+        return { ok: true, result: r || { ok: true } }
+      }
+
+      if (data.op === 'reject') {
+        desk.reject(data.deviceId)
+        audit('admin.reject', { by, device: data.deviceId || null })
+        return { ok: true, result: { ok: true } }
+      }
+
+      if (data.op === 'revoke') {
+        const r = await desk.revoke(String(data.certNonce || ''))
+        audit('admin.revoke', { by, certNonce: data.certNonce })
+        await notify('revoked', { certNonce: data.certNonce, by })
+        return { ok: true, result: r || { ok: true } }
+      }
+    } catch (e) {
+      audit('rejected', { what: 'admin', op: data.op, by, reason: e.message })
+      return { ok: false, error: e.message }
+    }
+    return { ok: false, error: 'admin: invalid operation' }
+  }
+
+  return { handle, get nonceCount () { return seen.size } }
+}
+
+export default { createAdminDesk, ADMIN_OPS, ADMIN_NONCE_TTL_MS }

package/src/enroll.js

@@ -52,7 +52,7 @@ 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' }
+const SCOPE_TO_CAP = { 'vault:sign': 'sign', 'vault:store': 'store', 'vault:read': 'read', 'vault:admin': 'admin' }
 export const scopeToCaps = (scope) =>
   (Array.isArray(scope) ? scope : [scope]).map((s) => SCOPE_TO_CAP[s]).filter(Boolean)
 
@@ -119,15 +119,15 @@ export function createEnrollDesk ({
   // único que necesita el QR corto para que el aparato le hable punto a punto.
   connToken = null
 } = {}) {
-  if (!identity) throw new Error('createEnrollDesk: falta identity')
-  if (!iss) throw new Error('createEnrollDesk: falta iss (pubkey de la maestra)')
+  if (!identity) throw new Error('createEnrollDesk: missing identity')
+  if (!iss) throw new Error('createEnrollDesk: missing iss (master pubkey)')
 
   // 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 reply = (to, obj) => { try { send(to, obj) } catch (e) { log('[vault] could not reply:', e.message) } }
   const isFresh = (d) => typeof d?.ts === 'number' && Math.abs(Date.now() - d.ts) <= FRESH_WINDOW_MS
 
   /**
@@ -196,7 +196,7 @@ export function createEnrollDesk ({
     const pend = pending.get(String(p?.sn || ''))
     if (!pend || Date.now() > pend.exp) {
       audit('rejected', { what: 'hello', reason: 'sin-sesion' })
-      return reply(from, { type: MSG_ERROR, error: 'no hay ningún emparejamiento abierto con ese código' })
+      return reply(from, { type: MSG_ERROR, error: 'no pairing session open for that code' })
     }
     // La respuesta va FIRMADA por la maestra y el `sn` va dentro de lo firmado. Eso ata
     // la respuesta a ESTA sesión: no se puede reutilizar la de otro emparejamiento ni la
@@ -215,19 +215,19 @@ export function createEnrollDesk ({
   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' })
+      return reply(from, { type: MSG_ERROR, error: 'invalid enroll' })
     }
     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' })
+      return reply(from, { type: MSG_ERROR, error: 'invalid or expired pairing token' })
     }
-    if (d.sn !== pend.sn) return reply(from, { type: MSG_ERROR, error: 'sesión inválida' })
+    if (d.sn !== pend.sn) return reply(from, { type: MSG_ERROR, error: 'invalid session' })
     // V7 · la INTENCIÓN viaja firmada y tiene que coincidir con el modo con el que ESTA
     // bóveda abrió el emparejamiento. Es lo que garantiza que lo que pasa es lo que el
     // humano vio anunciado en las dos pantallas, y no algo que se decidió a mitad de camino.
     const intent = d.intent || 'join'
     if (intent !== 'join' && intent !== 'adopt') {
-      return reply(from, { type: MSG_ERROR, error: 'intención desconocida: ' + intent })
+      return reply(from, { type: MSG_ERROR, error: 'unknown intent: ' + intent })
     }
     if (intent !== (pend.mode || 'join')) {
       audit('rejected', { what: 'enroll', reason: 'intent-mismatch' })
@@ -235,22 +235,22 @@ export function createEnrollDesk ({
     }
     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)' })
+      return reply(from, { type: MSG_ERROR, error: 'stale request: ts outside the ±5 min window (possible replay, or the device clock is off)' })
     }
     // 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' })
+      return reply(from, { type: MSG_ERROR, error: 'invalid device signature' })
     }
     // 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.' })
+      return reply(from, { type: MSG_ERROR, error: 'this device speaks an old pairing version (no code commitment). Update it and try again.' })
     }
     // 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' })
+      return reply(from, { type: MSG_ERROR, error: 'another device is already using this pairing session' })
     }
 
     const deviceId = await deviceIdOf(d.dpub)
@@ -289,16 +289,16 @@ export function createEnrollDesk ({
    */
   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)')
+    if (!code) throw new Error('missing code (the digits shown by the device)')
 
     let pend
     if (deviceId) {
       pend = findPending(deviceId)
-      if (!pend) throw new Error('no hay ninguna máquina esperando aprobación con ese identificador')
+      if (!pend) throw new Error('no device awaiting approval with that id')
     } 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')
+      if (waiting.length === 0) throw new Error('no device awaiting approval')
+      if (waiting.length > 1) throw new Error('more than one pairing in flight; restart it with dotrino-vault pair')
       pend = waiting[0]
     }
 
@@ -306,8 +306,8 @@ export function createEnrollDesk ({
     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.')
+      log('[vault] wrong code for %s: no certificate was issued', pend.deviceId)
+      throw new Error('code does not match the one shown by the device: no certificate was issued. Check it and try again.')
     }
 
     // CAMINO A · aquí la bóveda no entrega un cert: entrega SU IDENTIDAD para que el
@@ -319,7 +319,7 @@ export function createEnrollDesk ({
       pend.state = 'AWAITING_ACTA'
       pend.approvedAt = Date.now()
       reply(pend.from, { type: MSG_ENROLL_ADOPT, code, pub: iss, encPub: encPub || null, label: vaultLabel || '' })
-      log('[vault] adopción aprobada para %s: esperando el acta sellada', pend.deviceId)
+      log('[vault] adoption approved for %s: waiting for the sealed record', pend.deviceId)
       fire(onPendingChange)
       return { ok: true, deviceId: pend.deviceId, adopting: true }
     }
@@ -369,24 +369,24 @@ export function createEnrollDesk ({
   async function handleActaSealed (from, p) {
     const acta = p?.acta
     const pend = [...pending.values()].find((x) => x.state === 'AWAITING_ACTA' && (x.from === from || x.dpub))
-    if (!pend) return reply(from, { type: MSG_ERROR, error: 'no hay ninguna adopción esperando un acta' })
-    if (!acta || typeof acta !== 'object') return reply(from, { type: MSG_ERROR, error: 'acta ausente o ilegible' })
+    if (!pend) return reply(from, { type: MSG_ERROR, error: 'no adoption awaiting a record' })
+    if (!acta || typeof acta !== 'object') return reply(from, { type: MSG_ERROR, error: 'record missing or unreadable' })
     if (acta.sealer !== iss) {
       audit('rejected', { what: 'adopt', reason: 'not-sealer' })
-      return reply(from, { type: MSG_ERROR, error: 'esa acta no nombra a esta bóveda como quien manda' })
+      return reply(from, { type: MSG_ERROR, error: 'that record does not name this vault as the sealer' })
     }
     if (acta.sealedBy !== pend.dpub) {
       audit('rejected', { what: 'adopt', reason: 'sealed-by-other' })
-      return reply(from, { type: MSG_ERROR, error: 'esa acta no la selló el dispositivo de este emparejamiento' })
+      return reply(from, { type: MSG_ERROR, error: 'that record was not sealed by the device of this pairing' })
     }
     if (pend.profileId && acta.profileId !== pend.profileId) {
       audit('rejected', { what: 'adopt', reason: 'other-profile' })
-      return reply(from, { type: MSG_ERROR, error: 'esa acta es de otra cuenta distinta a la que anunció el dispositivo' })
+      return reply(from, { type: MSG_ERROR, error: 'that record belongs to an account other than the one the device announced' })
     }
 
     try {
       const r = await identity.joinProfile(acta)
-      if (!r?.joined) throw new Error(r?.reason || 'no se pudo adoptar')
+      if (!r?.joined) throw new Error(r?.reason || 'could not adopt')
       audit('adopt', { device: pend.deviceId, profile: acta.profileId, seq: acta.seq })
       // El acta que vuelve es la que la bóveda tiene guardada: el aparato la adopta y los
       // dos quedan en la misma versión.
@@ -400,7 +400,7 @@ export function createEnrollDesk ({
       return { ok: true, adopted: true, profileId: acta.profileId, seq: mia.seq }
     } catch (e) {
       log('[vault] no se pudo adoptar la cuenta: %s', e.message)
-      reply(pend.from, { type: MSG_ERROR, error: 'la bóveda no pudo adoptar la cuenta: ' + e.message })
+      reply(pend.from, { type: MSG_ERROR, error: 'the vault could not adopt the account: ' + e.message })
       return { ok: false, error: e.message }
     }
   }
@@ -411,7 +411,7 @@ export function createEnrollDesk ({
       ? findPending(deviceId)
       : [...pending.values()].find((p) => p.state === 'PENDING_CONFIRM')
     if (!pend) return { ok: false }
-    reply(pend.from, { type: MSG_ERROR, error: 'emparejamiento rechazado' })
+    reply(pend.from, { type: MSG_ERROR, error: 'pairing rejected' })
     pending.delete(pend.token)
     audit('reject', { device: pend.deviceId })
     fire(onPendingChange)
@@ -428,7 +428,7 @@ export function createEnrollDesk ({
     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) }
+    catch (e) { log('[vault] could not emit revoke:', e.message) }
   }
 
   /** Revoca una delegación por `nonce` y avisa al dispositivo para que se autoborre. */

package/src/index.js

@@ -27,16 +27,13 @@
  */
 import { verifyChain } from '@dotrino/identity/capabilities'
 import { createEnrollDesk, deviceIdOf, DEVICE_TTL_MS, FRESH_WINDOW_MS } from './enroll.js'
+// Las constantes del protocolo salen del MISMO módulo que usa el daemon: si la lista
+// local se queda corta, el dispositivo deja de atender mensajes sin que nadie lo note.
+import { MSG, SCOPE } from './protocol.js'
 
-const SIGN_SCOPE = 'vault:sign'
+const SIGN_SCOPE = SCOPE.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'
-}
+const RENEW_TTL_MS = DEVICE_TTL_MS             // la renovación extiende la misma ventana (30 días)
 
 /** deviceId legible (p. ej. `C440-AC0E`) desde una pubkey JWK. */
 export { deviceIdOf }
@@ -49,10 +46,11 @@ export { deviceIdOf }
  *   `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 }
+ * @returns {Promise<object>} handle: { iss, proxy, client, startPairing, stopPairing,
+ *   approve, reject, listPending, listMachines, revoke, getSelfCert, onPendingChange,
+ *   onAdopted, close }
  */
-export async function startDeviceVault (identity, { proxyUrl } = {}) {
+export async function startDeviceVault (identity, { proxyUrl, client: injectedClient } = {}) {
   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'
@@ -67,12 +65,17 @@ export async function startDeviceVault (identity, { proxyUrl } = {}) {
     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()
+  // `client` inyectado: solo para las pruebas (transporte de mentira). En producción se
+  // levanta el del ecosistema — no hay otro transporte.
+  const client = injectedClient || await (async () => {
+    const { WebSocketProxyClient } = await import('@dotrino/proxy-client')
+    const c = new WebSocketProxyClient({
+      url: proxy, enableWebRTC: false, autoReconnect: true,
+      maxReconnectAttempts: 100000, reconnectDelay: 4000
+    })
+    await c.connect()
+    return c
+  })()
 
   const selfCert = await getSelfCert()
   const identify = async () => {
@@ -87,6 +90,7 @@ export async function startDeviceVault (identity, { proxyUrl } = {}) {
   const send = (to, obj) => { try { client.send(to, obj) } catch (_) {} }
 
   let _onPendingChange = () => {}
+  let _onAdopted = () => {}
 
   // 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
@@ -99,9 +103,49 @@ export async function startDeviceVault (identity, { proxyUrl } = {}) {
     sendByPubkey: (pub, obj) => { try { client.sendByPubkey(pub, obj) } catch (_) {} },
     defaultScope: [SIGN_SCOPE],
     defaultTtlMs: DEVICE_TTL_MS,
+    // Camino A (la cuenta del aparato pasa a vivir aquí): sin la llave de cifrado, esta
+    // bóveda entraría mandando una cuenta cuyo contenido no puede abrir.
+    encPub: identity.me?.encryptionPubkey || null,
+    vaultLabel: 'bóveda',
+    // Cita del proxio para la invitación corta (QR). Si el proxio es viejo y no las
+    // conoce, el desk se cae solo a la invitación larga.
+    connToken: async () => {
+      try { return (await client.requestPairingCode())?.code || null }
+      catch (_) { return null }
+    },
+    onAdopted: (info) => { try { _onAdopted(info) } catch (_) {} },
     onPendingChange: () => _onPendingChange()
   })
 
+  /** Nonces revocados, para que un cert revocado no pase ningún `verifyChain`. */
+  async function revocationSet () {
+    const { revoked } = await identity.listDelegations()
+    return new Set((revoked || []).map((r) => r.nonce || r))
+  }
+
+  /**
+   * RENOVACIÓN automática (igual que `dotrino-vault#handleRenew`): un dispositivo con
+   * cert VIGENTE y no revocado pide uno fresco —misma sub-clave y scope— sin QR ni
+   * aprobación: sigue siendo el mismo dispositivo, solo extiende la ventana. Un cert
+   * vencido o revocado NO se renueva (ahí toca re-emparejar con aprobación).
+   *
+   * Sin esto, toda máquina enrolada contra un dispositivo-bóveda caduca a los 30 días.
+   */
+  async function handleRenew (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 send(from, { type: MSG.ERROR, error: 'stale request: ts outside the ±5 min window (possible replay, or the device clock is off)' })
+    }
+    const chk = await verifyChain({ data: d, signature: p.signature, cert: p.cert, trustedIssuer: iss, revoked: await revocationSet() })
+    if (!chk.ok) return send(from, { type: MSG.ERROR, error: 'unauthorized: ' + chk.reason })
+    // Reusar el label del cert original (si sigue registrado en delegations).
+    const { issued } = await identity.listDelegations()
+    const prev = (issued || []).find((x) => x.nonce === p.cert.nonce)
+    const { cert } = await identity.signDelegation(p.cert.sub, p.cert.scope, { ttlMs: RENEW_TTL_MS, label: prev?.label || '' })
+    send(from, { type: MSG.RENEWED, cert })
+  }
+
   // 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.
@@ -124,7 +168,12 @@ export async function startDeviceVault (identity, { proxyUrl } = {}) {
 
   client.on('message', (_from, p) => {
     if (!p || typeof p !== 'object') return
-    if (p.type === MSG.ENROLL) desk.handleEnroll(_from, p).catch(() => {})
+    // El QR corto no lleva la llave: el aparato la pide con un HELLO presentando el `sn`.
+    if (p.type === MSG.HELLO) Promise.resolve(desk.handleHello(_from, p)).catch(() => {})
+    else if (p.type === MSG.ENROLL) desk.handleEnroll(_from, p).catch(() => {})
+    // Camino A: el aparato devuelve su acta sellada admitiendo a esta bóveda.
+    else if (p.type === MSG.ACTA_SEALED) Promise.resolve(desk.handleActaSealed(_from, p)).catch(() => {})
+    else if (p.type === MSG.RENEW) handleRenew(_from, p).catch(() => {})
     else if (p.type === MSG.DEVICES) handleDevices(_from, p).catch(() => {})
   })
 
@@ -148,6 +197,7 @@ export async function startDeviceVault (identity, { proxyUrl } = {}) {
   return {
     iss, proxy, client,
     startPairing: desk.startPairing,
+    stopPairing: desk.stopPairing,
     // 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 }),
@@ -159,6 +209,8 @@ export async function startDeviceVault (identity, { proxyUrl } = {}) {
     revoke: (nonce) => desk.revoke(nonce),
     getSelfCert,
     onPendingChange (fn) { _onPendingChange = fn || (() => {}) },
+    /** Camino A: la cuenta del aparato quedó adoptada por esta bóveda. */
+    onAdopted (fn) { _onAdopted = fn || (() => {}) },
     close () { try { client.close() } catch (_) {} }
   }
 }

package/src/protocol.js

@@ -59,6 +59,16 @@ export const MSG = Object.freeze({
   // Va FIRMADO por la maestra y el agente lo verifica contra su `iss` pineada: un
   // aviso de reinicio sin autenticar ES un ataque de denegación.
   SECRETS_CHANGED: 'vault.secrets.changed',   // vault → servicio: { body:{op,ns,ts}, signature }
+  // --- CONSOLA REMOTA (docs/consola-remota.md) — requiere cert `vault:admin` ---
+  // Un solo mensaje con `data.op`: pending · pair · approve · reject · revoke · audit.
+  // Admitir y expulsar, nada más: cambiar permisos, traspasar el mando y los secretos
+  // NO se exponen aquí, y no es un olvido — es el límite (§2 del diseño).
+  ADMIN: 'vault.admin',                       // admin → vault: { data:{op,…,ts,nonce}, signature, cert }
+  ADMIN_RESULT: 'vault.admin.result',         // vault → admin: { op, result }
+  // Aviso a TODOS los miembros de que el perfil cambió (alguien entró o salió). Es la
+  // contrapartida de administrar a distancia: sin esto, un enrolamiento remoto sería
+  // invisible para el resto de tus dispositivos.
+  ADMIN_EVENT: 'vault.admin.event',           // vault → todos: { body:{ev,deviceId,by,ts}, signature }
   ERROR: 'vault.error'                        // vault → dispositivo: { error }
 })
 
@@ -66,7 +76,11 @@ export const MSG = Object.freeze({
 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
+  STORE: 'vault:store', // leer/escribir el store de hilos + aperturas del usuario
+  // Consola remota (docs/consola-remota.md): admitir y expulsar miembros a distancia.
+  // NO incluye cambiar permisos, traspasar el mando ni conceder `admin`: eso es el rol
+  // de master y sigue siendo local. No se empareja — se concede desde el PC.
+  ADMIN: 'vault:admin'
 })
 
 /**

package/src/sealed.js

@@ -76,7 +76,7 @@ export async function seal ({ ek, payload }) {
  */
 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')
+    throw new Error('invalid sealed envelope')
   }
   const key = await deriveAesKey(privateKey, enc.epk)
   const pt = await subtle.decrypt({ name: 'AES-GCM', iv: fromB64(enc.iv) }, key, fromB64(enc.ct))

package/src/service.js

@@ -27,6 +27,7 @@ import {
 import { MSG, secretsScope, isValidSecretsNs } from './protocol.js'
 import { makeEphemeralKey, openSealed } from './sealed.js'
 import { parseInvite } from './invite.js'
+import { atRestFor } from './atrest.js'
 
 const IDENTITY_FILE = 'service-identity.json'
 const FRESH_WINDOW_MS = 5 * 60 * 1000
@@ -169,15 +170,26 @@ function waitForMsg (client, predicate, timeoutMs = 30000) {
 
 const identityFileOf = (dir) => path.join(dir, IDENTITY_FILE)
 
-/** Lee la identidad persistida del servicio ({device, cert, iss, proxy, ns}) o null. */
+/**
+ * Lee la identidad persistida del servicio ({device, cert, iss, proxy, ns}) o null.
+ *
+ * CIFRADA EN REPOSO (`atrest.js`) con una clave ligada a ESTA máquina: el archivo
+ * lleva la llave privada del dispositivo, así que copiarlo a otro equipo no sirve.
+ * Un archivo de una versión anterior (en claro) se lee igual y queda cifrado en la
+ * primera escritura.
+ */
 export function readServiceIdentity (dir) {
-  try { return JSON.parse(fs.readFileSync(identityFileOf(dir), 'utf8')) } catch (_) { return null }
+  try {
+    const text = fs.readFileSync(identityFileOf(dir), 'utf8')
+    return JSON.parse(atRestFor(dir).decrypt(text))
+  } 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 })
+  const blob = atRestFor(dir).encrypt(JSON.stringify(obj, null, 2))
+  fs.writeFileSync(f, blob, { mode: 0o600 })
 }
 
 /**
@@ -433,9 +445,9 @@ export async function watchSecretsChanges ({
     if (body.sub !== saved.device.publickey) return
     if (saved.cert?.nonce && body.nonce !== saved.cert.nonce) return
     if (!(await verifyDeviceSig({ publickey: master, data: body, signature: payload.signature }))) {
-      return log('[vault] aviso de revocación MAL FIRMADO: ignorado')
+      return log('[vault] revocation notice BADLY SIGNED: ignored')
     }
-    log('[vault] ⚠ la bóveda REVOCÓ el cert de este agente: apagando')
+    log('[vault] ⚠ the vault REVOKED this agent cert: shutting down')
     try { onRevoked?.({ nonce: body.nonce }) } catch (e) { log('[vault] ' + e.message) }
   }
 
@@ -459,13 +471,13 @@ export async function watchSecretsChanges ({
     try {
       valida = await verifyDeviceSig({ publickey: master, data: body, signature: payload.signature })
     } finally { enVuelo.delete(body.ts) }
-    if (!valida) return log('[vault] aviso de cambio MAL FIRMADO: ignorado (no viene de tu bóveda)')
+    if (!valida) return log('[vault] change notice BADLY SIGNED: ignored (not from your vault)')
     if (body.ts <= ultimoTs) return
     ultimoTs = body.ts
 
     const ahora = Date.now()
     if (ahora - nacido < graceMs) {
-      return log('[vault] aviso de cambio recién arrancado: ignorado (evita el ciclo de reinicios)')
+      return log('[vault] change notice right after start: ignored (avoids the restart loop)')
     }
     if (ahora - ultimoObedecido < minIntervalMs) {
       return log('[vault] aviso de cambio demasiado seguido del anterior: ignorado')
@@ -473,7 +485,7 @@ export async function watchSecretsChanges ({
     ultimoObedecido = ahora
 
     const espera = Math.floor(Math.random() * jitterMs)
-    log(`[vault] la bóveda avisa que la configuración de «${ns}» cambió (en ${espera} ms)`)
+    log(`[vault] the vault reports config for "${ns}" changed (in ${espera} ms)`)
     setTimeout(() => { if (!parado) { try { onChange?.({ ns, ts: body.ts }) } catch (e) { log('[vault] ' + e.message) } } }, espera)
   }
 
@@ -486,7 +498,7 @@ export async function watchSecretsChanges ({
       // Reconectar solo: si se cae el proxio, el agente deja de ser avisable, y
       // eso es exactamente el momento en que uno querría enterarse de una rotación.
       client.on('disconnected', () => { if (!parado) reintento = setTimeout(conectar, 5000) })
-      log('[vault] a la escucha de cambios de configuración')
+      log('[vault] listening for config changes')
     } catch (e) {
       if (!parado) reintento = setTimeout(conectar, 5000)
     }