@dotrino/vaultd 0.11.0 → 0.13.0

package/bin/dotrino-vaultd.js

@@ -36,7 +36,9 @@ const mgr = await runDaemon()
 // Atajo de dev: --pair imprime el QR directo en stdout (en producción se usa el CLI).
 // Empareja contra el perfil ACTIVO.
 if (process.argv.includes('--pair')) {
-  const { qr, expiresInMs } = mgr.current().startPairing({ label: 'cli' })
+  // `startPairing` es asíncrono desde que el QR lleva una CITA del proxio (hay
+  // que pedírsela) en vez de la dirección de la conexión.
+  const { qr, expiresInMs } = await mgr.current().startPairing({ label: 'cli' })
   const { url, b64 } = pairUrl(qr)
   console.log(`\nEmparejá un dispositivo (válido ${expiresInMs / 60000} min):\n`)
   console.log(qrToString(url))

package/lib/README.md

@@ -91,18 +91,128 @@ que los secretos estén. Si el vault no está disponible, **espera** (reintento
 backoff) — un servicio sin vault no arranca, no opera con secretos viejos ni vacíos.
 Un fallo NO transitorio (sin enrolar, cert revocado, scope equivocado) sí aborta.
 
+#### Esperar al vault es la REGLA. La excepción es una sola
+
+Un agente enrolado **espera**. No es una preferencia: arrancar igual significaría
+operar con la configuración vieja del `.env`, que es justo lo que el vault vino a
+dejar de ser. Y la espera casi nunca duele, porque estos agentes no son críticos:
+que un bot o un firmador tarden en levantar no rompe a nadie.
+
+La **única** excepción conocida es **el proxio**, y no por importancia sino por una
+razón estructural: el vault habla con sus servicios **por el proxio**. Un proxio que
+espera al vault espera a alguien que necesita que el proxio ya esté escuchando —
+abrazo mortal, y con él se cae el vault de todo el mundo. Por eso el proxio arranca
+con lo que tenga y aplica la configuración cuando llega, con `applyEnv`.
+
+> `applyEnv` existe **para ese caso**, no como alternativa cómoda al bloqueo. Si tu
+> agente no está en el camino por el que viaja el propio vault, usa
+> `import '@dotrino/vault/config'` y deja que espere. El precio de la excepción es
+> real: lo que sólo se lee al arrancar llega tarde y no toma efecto hasta reiniciar,
+> así que hay que avisarlo en el log — el proxio lo hace.
+
 Para procesos que no son Node, el CLI los inyecta en el entorno de un hijo:
 
 ```bash
 dotrino-env run --ns miapp -- ./mi-binario
 ```
 
+### Un agente tiene UNA identidad, y se la da el vault
+
+Un **aparato** puede llevar varios perfiles, y hasta meter su propia cuenta al vault
+por adopción: llega con una historia que conservar. Un **agente** no es eso. Es un
+servicio: su identidad se la cede el vault y no hay caso en que quiera empujar la
+suya hacia arriba. De ahí tres reglas, que el paquete aplica solas:
+
+- **No adopta, nunca.** La invitación declara su modo (`join` / `adopt`); si viene
+  abierta para adoptar, `enrollService` la **rechaza al pegarla**, sin salir a la red.
+  La intención `join` va además firmada dentro de la petición, para que nadie en el
+  medio la convierta en otra cosa.
+- **No acumula.** Enrolar de nuevo **reemplaza** la identidad anterior, que deja de
+  existir en ese agente. No es un error a desbloquear con `--force`: es la forma de
+  **rotar** la identidad de un agente comprometido. Se avisa por `onReplace` qué se
+  descarta.
+- **Un agente, un `ns`.** Varios agentes pueden convivir en una máquina (un
+  directorio por namespace); lo que no existe es un agente que sea varios.
+
+> ⚠ Si esa llave es además la **identidad de red** del servicio —el caso del proxio,
+> cuyo id de nodo se deriva de ella— reemplazarla le cambia el nombre en la red: las
+> instancias y citas vivas dejan de resolver y los peers que lo tenían pineado lo
+> rechazan hasta re-pinearlo. Es a propósito: así se echa a un nodo comprometido.
+
+### Rotar: la bóveda avisa y el agente SE REINICIA
+
+Cambiar un secreto en la bóveda no sirve de nada si quien lo usa no se entera. Al
+guardar, la bóveda manda un **aviso firmado** a los agentes de ese `ns` (sin
+valores: sólo dice que cambió), **agrupando** las escrituras seguidas para que
+cargar cinco valores no provoque cinco reinicios.
+
+El agente **no recarga en caliente: termina**, y lo levanta su supervisor (pm2,
+systemd `Restart=always`). Con `import '@dotrino/vault/config'` ya viene puesto.
+
+Salir en vez de recargar, por tres razones — y la primera es la de peso:
+
+1. **Borra de memoria el valor viejo.** En JavaScript un secreto no se puede
+   borrar: los strings son inmutables, no hay `zeroize`, y el valor sigue en el
+   heap hasta que al recolector le apetezca, más lo que capturó cada *closure* y
+   cada caché derivada. Una llave se rota casi siempre **porque se filtró**, así
+   que dejarla viva en el proceso anula el motivo de rotarla. Un proceso nuevo
+   empieza con el heap limpio.
+2. **Lee todo fresco.** Recargar en caliente exige que cada sitio que leyó una
+   variable sepa releerla; esa lista hay que mantenerla para siempre y, cuando se
+   queda corta, falla en silencio.
+3. **Es un interruptor de emergencia.** Revocar el cert de un agente ya no espera a
+   que alguien se acuerde de reiniciarlo: recibe el `REVOKED` firmado, se apaga, y
+   al arrancar `fetchSecrets` recibe «no autorizado: revoked», que no se arregla
+   reintentando. Antes, revocar no le quitaba nada a un proceso ya corriendo.
+
+Defensas, porque una señal que provoca reinicios es un arma si se descuida: firma
+de la maestra pineada, `ns` que coincida, frescura y anti-replay, **gracia de
+arranque** y **piso entre avisos** (si la configuración nueva rompe el arranque, sin
+eso el servicio entra en ciclo) y **jitter** (diez agentes del mismo `ns` no salen
+todos en el mismo segundo).
+
+```js
+import { watchEnv } from '@dotrino/vault/env'
+await watchEnv({ ns: 'miapp' })                       // termina el proceso al cambiar
+await watchEnv({ ns: 'proxy', onUpdate: (i) => … })   // o decide tú (ver abajo)
+```
+
+`onUpdate` es para cuando terminar **no es una opción**. El caso real es el proxio:
+reiniciarlo corta el transporte de todo el ecosistema, así que anota el aviso, lo
+publica en su `GET /peers` y deja el momento a un humano.
+
+### Precedencia: el vault MANDA
+
+Los valores del vault **pisan** los del `.env` y los del entorno. El vault no
+reemplaza al `.env` —que sigue siendo lo que arranca una máquina sin enrolar— pero
+sí tiene la última palabra sobre las claves que administra.
+
+Esa es la pieza que hace barata la **rotación**: cambias el valor en un solo lugar y
+ningún `.env` viejo olvidado en un VPS puede seguir ganando. Con la precedencia al
+revés (como estaba hasta la 0.14.0) rotar exigía además ir a limpiar cada copia
+rancia —el trabajo que se quería evitar— y, peor, el servicio arrancaba con la llave
+vieja **sin decir nada**.
+
+Lo que sí se dice en voz alta: al arrancar se listan las claves que el vault tuvo que
+pisar. Es la señal de que en esa máquina quedó un `.env` por limpiar.
+
+```bash
+DOTRINO_ENV_OVERRIDE=0 node server.js   # escotilla: por esta corrida, gana el entorno
+dotrino-env check                        # dice qué claves pisaría en esta máquina
+```
+
 ### API `@dotrino/vault/env`
 
-- `loadEnv({ ns?, dir?, override?, wait?, required?, onRetry? }) → { ns, secrets, injected, skipped }`
-  (por defecto **no pisa** variables ya presentes en el entorno; `override: true` sí)
+- `loadEnv({ ns?, dir?, override?, wait?, required?, onRetry? }) → { ns, secrets, injected, overridden, skipped }`
+  (por defecto **pisa** lo que ya esté en el entorno; `override: false` invierte la regla).
+  `overridden` son las claves que tenían otro valor y el vault reemplazó.
+- `applyEnv(secrets, override?) → { injected, overridden, skipped }` — vuelca un bundle
+  ya obtenido, sin pedirlo. Para servicios que **no pueden bloquear su arranque**
+  esperando al vault y lo aplican cuando llega (el caso del proxy: el vault le habla
+  *por* el proxy, así que esperarlo sería un abrazo mortal).
 - `serviceDir(ns)`, `serviceRoot()`, `listEnrolled()`, `resolveNs(ns?)`
-- Entorno: `DOTRINO_NS` · `DOTRINO_ENV_DIR` · `DOTRINO_ENV_HOME` · `DOTRINO_ENV_QUIET`
+- Entorno: `DOTRINO_NS` · `DOTRINO_ENV_DIR` · `DOTRINO_ENV_HOME` · `DOTRINO_ENV_QUIET` ·
+  `DOTRINO_ENV_OVERRIDE`
 - CLI: `dotrino-env enroll|status|check|run`  (`check` lista **nombres** de secretos, nunca valores)
 
 Bajo el capó es `@dotrino/vault/service` (`enrollService` / `waitForSecrets`): petición
@@ -124,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/lib/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/lib/src/config.js

@@ -8,19 +8,51 @@
  * secretos viejos ni vacíos. Un fallo NO transitorio (sin enrolar, cert revocado,
  * scope equivocado) sí aborta el proceso.
  *
+ * EL VAULT MANDA: lo que venga de aquí PISA lo que ya hubiera en el entorno
+ * (incluido un `.env` cargado antes). Ver `env.js` para el porqué.
+ *
+ * Y queda A LA ESCUCHA: cuando el dueño cambia la configuración en la bóveda, el
+ * proceso TERMINA para que su supervisor lo levante limpio. No se recarga en
+ * caliente a propósito — salir borra de la memoria el valor viejo, que en
+ * JavaScript no hay forma de borrar de otra manera, y una llave se rota casi
+ * siempre porque se filtró. Requiere correr bajo pm2 o systemd `Restart=always`.
+ * Se apaga con `DOTRINO_ENV_WATCH=0`.
+ *
  * Config por entorno:
- *   DOTRINO_NS         namespace de secretos (si no, el único enrolado en la máquina)
- *   DOTRINO_ENV_DIR    directorio de la identidad del servicio (si no, ~/.dotrino/service/<ns>)
- *   DOTRINO_ENV_QUIET  '1' para no imprimir la línea de arranque
+ *   DOTRINO_NS            namespace de secretos (si no, el único enrolado en la máquina)
+ *   DOTRINO_ENV_DIR       directorio de la identidad del servicio (si no, ~/.dotrino/service/<ns>)
+ *   DOTRINO_ENV_QUIET     '1' para no imprimir la línea de arranque
+ *   DOTRINO_ENV_OVERRIDE  '0' para NO pisar el entorno en esta corrida (depuración)
+ *   DOTRINO_ENV_WATCH     '0' para no escuchar avisos de cambio (no terminar solo)
  */
-import { loadEnv } from './env.js'
+import { loadEnv, watchEnv } from './env.js'
 
 const quiet = process.env.DOTRINO_ENV_QUIET === '1'
 
-const { ns, injected } = await loadEnv({
+const { ns, injected, overridden } = await loadEnv({
   onRetry: (e, ms) => {
     if (!quiet) console.error('[dotrino-env] vault no disponible (%s); reintentando en %ds…', e.message, Math.round(ms / 1000))
   }
 })
 
-if (!quiet) console.error('[dotrino-env] %d secreto(s) del ns "%s" cargados en process.env', injected.length, ns)
+if (!quiet) {
+  console.error('[dotrino-env] %d valor(es) del ns "%s" cargados en process.env', injected.length, ns)
+  // Se dice en voz alta: que el vault haya tenido que pisar algo significa que
+  // en esta máquina hay un `.env` con valores viejos. Ganó el vault, pero el
+  // operador quiere enterarse — es la señal de que quedó basura por limpiar.
+  if (overridden.length) {
+    console.error('[dotrino-env] pisaron un valor previo del entorno: %s', overridden.join(', '))
+  }
+}
+
+// La escucha no debe impedir que el proceso termine por su cuenta si no tiene
+// nada más que hacer, así que si falla (agente sin enrolar del todo, proxio
+// caído) se avisa y se sigue: el servicio ya tiene su configuración; lo único
+// que pierde es enterarse del próximo cambio.
+if (process.env.DOTRINO_ENV_WATCH !== '0') {
+  try {
+    await watchEnv({ ns, quiet })
+  } catch (e) {
+    if (!quiet) console.error('[dotrino-env] sin escucha de cambios (%s): habrá que reiniciar a mano al rotar', e.message)
+  }
+}

package/lib/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
 
   /**
@@ -146,14 +146,20 @@ export function createEnrollDesk ({
    *                       aviso. Es ORIENTATIVO (un nombre que puso su dueño); la
    *                       identidad de verdad de la cuenta es `iss`.
    */
-  function startPairing ({ scope = defaultScope, ttlMs = defaultTtlMs, label = '', mode = 'join', account = '' } = {}) {
+  async function startPairing ({ scope = defaultScope, ttlMs = defaultTtlMs, label = '', mode = 'join', account = '' } = {}) {
     pending.clear() // uno a la vez: una sesión nueva supersede a la anterior
     const acct = String(account || '').slice(0, 40)
-    // INVITACIÓN CORTA: si sabemos nuestra dirección en el proxy, el QR lleva solo
-    // eso y el nonce de la sesión (13 bytes). La llave, el proxy y el nombre de la
-    // cuenta los pide el aparato por la red presentando el `sn`. El nonce hace de
-    // identificador de sesión: no hace falta un token de emparejamiento aparte.
-    const conn = typeof connToken === 'function' ? connToken() : connToken
+    // INVITACIÓN CORTA: si sabemos cómo alcanzarnos, el QR lleva solo eso y el
+    // nonce de la sesión. La llave, el proxy y el nombre de la cuenta los pide el
+    // aparato por la red presentando el `sn`. El nonce hace de identificador de
+    // sesión: no hace falta un token de emparejamiento aparte.
+    //
+    // `conn` es una CITA del proxio (6 caracteres, un solo uso, caduca en
+    // minutos), no la dirección de la conexión: esa pasó a ser una instancia de
+    // 24 caracteres, que ni entra cómoda en un QR ni tiene por qué quedar impresa
+    // en algo que circula. Por eso se pide una nueva por emparejamiento, y por
+    // eso esto es asíncrono.
+    const conn = typeof connToken === 'function' ? await connToken() : connToken
     if (conn) {
       const sn = randToken(8)
       pending.set(sn, { token: sn, exp: Date.now() + PAIRING_TTL_MS, scope, ttlMs, label, sn, mode, account: acct, state: 'AWAITING_ENROLL' })
@@ -190,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
@@ -209,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' })
@@ -229,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)
@@ -283,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]
     }
 
@@ -300,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
@@ -313,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 }
     }
@@ -363,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.
@@ -394,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 }
     }
   }
@@ -405,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)
@@ -422,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. */