@dotrino/identity 0.37.0 → 0.38.0

package/vault/vendor/proxy-client/client.js

@@ -1,5 +1,5 @@
 import { buildSignedChannel, getPublicKeyJwk, signData } from './signature.js'
-import { WebRTCManager, RTC_TAG } from './webrtc.js'
+import { WebRTCManager, RTC_TAG, DEFAULT_ICE_SERVERS } from './webrtc.js'
 
 /**
  * Dotrino WebSocket proxy client.
@@ -76,6 +76,10 @@ export class WebSocketProxyClient {
       clearTimeout(this._reconnectTimer)
       this._reconnectTimer = null
     }
+    if (this._turnTimer) {
+      clearTimeout(this._turnTimer)
+      this._turnTimer = null
+    }
     if (this._rtc) this._rtc.closeAll()
     if (this.ws) {
       try { this.ws.close(1000) } catch (_) {}
@@ -219,12 +223,57 @@ export class WebSocketProxyClient {
    * @param {string|string[]} toPubkeys publickey JWK string o array
    * @param {any} payload
    */
-  sendByPubkey (toPubkeys, payload) {
+  /**
+   * Enviar a una o varias pubkeys.
+   *
+   * `opts.ephemeral` marca el mensaje como de TIEMPO REAL: si el destinatario no
+   * está conectado en ese momento, se descarta en vez de guardarse en la cola
+   * offline de 24 h. Úsalo para lo que caduca —jugadas de una partida,
+   * señalización WebRTC, presencia—: entregar eso mañana no es tarde, es
+   * incorrecto (reinicia negociaciones imposibles y muestra movimientos fuera de
+   * contexto). NO lo uses para mensajes de chat, que sí quieren esperar.
+   */
+  sendByPubkey (toPubkeys, payload, opts = {}) {
     const list = Array.isArray(toPubkeys) ? toPubkeys : [toPubkeys]
-    this._sendRaw({
+    const msg = {
       to_publickey: list,
       message: typeof payload === 'string' ? payload : JSON.stringify(payload)
-    })
+    }
+    if (opts.ephemeral) msg.ephemeral = true
+    this._sendRaw(msg)
+  }
+
+  /**
+   * Pedir una CITA: el código corto que una persona lee, dicta o escanea para
+   * emparejarse con esta conexión.
+   *
+   * Es un código de 6 caracteres (los 2 primeros dicen qué proxio lo emitió),
+   * que **caduca en minutos y se quema al usarse**. Esa es la diferencia con el
+   * token de 4 caracteres de antes: aquel era permanente mientras durara la
+   * conexión Y era la dirección de ruteo, así que tenía que ser adivinable-seguro
+   * y corto a la vez, dos cosas incompatibles.
+   *
+   * @param {{ttlMs?:number}} [opts] vida del código (30s–30min, por defecto 5min)
+   * @returns {Promise<{code:string, expiresAt:number, node:string}>}
+   */
+  requestPairingCode (opts = {}) {
+    const msg = { type: 'pair-code' }
+    if (opts.ttlMs) msg.ttlMs = opts.ttlMs
+    return this._request(msg, 'pair-code')
+  }
+
+  /**
+   * Canjear una cita ajena: devuelve a qué conexión (y a qué identidad) apunta.
+   * Acepta el código en minúsculas y con espacios o guiones.
+   *
+   * Si el código lo emitió otro proxio, este le pregunta a ESE proxio — no a
+   * toda la malla: un pregón se lo queda el primero que conteste, y así es como
+   * un nodo hostil se mete en emparejamientos ajenos.
+   *
+   * @returns {Promise<{ok:boolean, instance?:string, publickey?:string, error?:string}>}
+   */
+  redeemPairingCode (code) {
+    return this._request({ type: 'pair-redeem', code }, 'pair-redeem')
   }
 
   /**
@@ -233,13 +282,79 @@ export class WebSocketProxyClient {
    * (típicamente por el identity vault). Devuelve la respuesta del proxy con
    * `queued_delivered` (mensajes offline despachados al instante).
    */
-  identify ({ data, signature, cert }) {
+  identify ({ data, signature, cert, acta }) {
     if (!data || !signature) throw new Error('identify requires {data, signature}')
     const msg = { type: 'identify', data, signature }
     if (cert) msg.cert = cert // "una identidad": el proxy bindea este token también bajo tu maestra M
+    // Acta de perfil: el proxy la verifica (va firmada) y bindea también el `profileId`, así
+    // escribirle a la PERSONA llega a cualquiera de sus dispositivos. Ver acta-de-perfil.md.
+    if (acta) msg.acta = acta
     return this._request(msg, 'identified')
   }
 
+  /**
+   * Pedir al proxy credenciales TURN temporales (Cloudflare) para WebRTC.
+   * Requiere haber llamado antes a `identify` en ESTA conexión con la misma
+   * pubkey: el proxy solo emite a conexiones identificadas (así el TURN se
+   * usa solo desde apps Dotrino y no como relay abierto). Las credenciales
+   * expiran solas (TTL corto) y hay cuota por pubkey/hora.
+   *
+   * @param {Object} opts
+   * @param {string} opts.publicKey  Pubkey JWK string del vault (la de identify).
+   * @param {(data:any)=>Promise<string|{signature:string}>} opts.sign  Firma del vault (id.signData).
+   * @returns {Promise<{enabled:boolean, iceServers:any[]|null, expiresAt:number|null}>}
+   */
+  async getTurnCredentials ({ publicKey, sign } = {}) {
+    if (!publicKey || typeof sign !== 'function') {
+      throw new Error('getTurnCredentials requires { publicKey, sign }')
+    }
+    const data = { op: 'turn-credentials', publickey: publicKey, ts: Date.now() }
+    const signature = await normalizeSignature(sign, data)
+    const res = await this._request({ type: 'turn-credentials', data, signature }, 'turn-credentials')
+    return {
+      enabled: !!res.enabled,
+      iceServers: res.iceServers || null,
+      expiresAt: res.expiresAt || null
+    }
+  }
+
+  /**
+   * Activar TURN para WebRTC: obtiene credenciales temporales del proxy, las
+   * inyecta como ICE servers (junto a los STUN por defecto) y las renueva
+   * sola antes de expirar. Si el proxy no tiene TURN configurado, no cambia
+   * nada (los peers siguen STUN-only con fallback al proxy).
+   *
+   * Afecta a las conexiones P2P NUEVAS (los peers ya negociados conservan su
+   * configuración). Llamalo después de `identify`.
+   *
+   * @param {Object} opts  Igual que getTurnCredentials ({ publicKey, sign }).
+   * @returns {Promise<boolean>} true si TURN quedó activo.
+   */
+  async enableTurn ({ publicKey, sign } = {}) {
+    if (!this._rtc) throw new Error('WebRTC está deshabilitado en este cliente')
+    if (this._turnTimer) {
+      clearTimeout(this._turnTimer)
+      this._turnTimer = null
+    }
+    const res = await this.getTurnCredentials({ publicKey, sign })
+    if (!res.enabled || !res.iceServers) return false
+    this._rtc.setIceServers([...res.iceServers, ...DEFAULT_ICE_SERVERS])
+    // Renovar con margen antes de expirar (mínimo 30 s entre renovaciones)
+    const refreshIn = Math.max(30000, (res.expiresAt || 0) - Date.now() - 60000)
+    this._turnTimer = setTimeout(() => {
+      this._turnTimer = null
+      this.enableTurn({ publicKey, sign }).catch(() => {
+        // Sin conexión o cuota: reintento suave en 60 s; mientras tanto los
+        // peers nuevos usan los STUN por defecto.
+        this._turnTimer = setTimeout(() => {
+          this._turnTimer = null
+          this.enableTurn({ publicKey, sign }).catch(() => {})
+        }, 60000)
+      })
+    }, refreshIn)
+    return true
+  }
+
   /**
    * Consultar la config de Web Push del proxy.
    * @returns {Promise<{enabled:boolean, vapidPublicKey:string|null}>}
@@ -451,7 +566,12 @@ export class WebSocketProxyClient {
       const wasConnected = this._connected
       this._connected = false
       this._emit('disconnect', { code: ev.code, reason: ev.reason })
-      if (wasConnected && this.autoReconnect && ev.code !== 1000) {
+      // Reconectar ante cualquier cierre del servidor (incluido code 1000 de un
+      // restart limpio del proxy): los cierres INTENCIONALES del cliente ya
+      // tienen autoReconnect=false (puesto por close()), así que este guard no
+      // filtra desconexiones pedidas por la app. Sin esto, un restart del proxy
+      // deja a clientes de larga duración (bots, apps abiertas) zombis para siempre.
+      if (wasConnected && this.autoReconnect) {
         this._scheduleReconnect()
       }
     })
@@ -516,7 +636,20 @@ export class WebSocketProxyClient {
     const { type } = data
     switch (type) {
       case 'connected':
-        this.token = data.token
+        // `instance` es el identificador de esta conexión, ya cualificado por
+        // nodo: se le puede escribir desde cualquier proxio de la malla. Es el
+        // mismo valor que `token` (el nombre histórico), pero ya NO es un código
+        // de 4 caracteres para dictar — para eso está `requestPairingCode()`.
+        this.instance = data.instance || data.token
+        this.node = data.node || null
+        // Los nodos que conoce este proxio. Sirve para los descubrimientos que
+        // son de TODO el ecosistema y no tienen dueño natural (la lista pública
+        // de salas): se pregunta en cada nodo y se mezcla, en vez de designar a
+        // uno como árbitro. Son públicos: van en cada instancia y en /peers.
+        this.peers = Array.isArray(data.peers) ? data.peers : []
+        /** Este nodo + los que conoce, sin repetidos. */
+        this.knownNodes = [this.node, ...this.peers].filter((n, i, a) => n && a.indexOf(n) === i)
+        this.token = this.instance
         this._emit('token', this.token)
         if (this._connectResolve) {
           this._connectResolve(this.token)
@@ -569,6 +702,9 @@ export class WebSocketProxyClient {
       case 'push-scheduled':
       case 'push-canceled':
       case 'push-list':
+      case 'turn-credentials':
+      case 'pair-code':
+      case 'pair-redeem':
         this._resolvePending(data, type)
         break
       case 'error':

package/vault/vendor/proxy-client/webrtc.js

@@ -12,7 +12,7 @@
  * the "polite" one (rolls back on collision).
  */
 
-const DEFAULT_ICE_SERVERS = [
+export const DEFAULT_ICE_SERVERS = [
   { urls: 'stun:stun.l.google.com:19302' },
   { urls: 'stun:stun1.l.google.com:19302' },
   { urls: 'stun:global.stun.twilio.com:3478' }
@@ -93,6 +93,15 @@ export class WebRTCManager {
     for (const t of Array.from(this.peers.keys())) this.closePeer(t)
   }
 
+  /**
+   * Reemplaza la lista de ICE servers para las PRÓXIMAS conexiones (los peers
+   * ya negociados conservan la suya). Lo usa `client.enableTurn()` para
+   * inyectar las credenciales TURN temporales del proxy.
+   */
+  setIceServers (list) {
+    if (Array.isArray(list) && list.length) this.iceServers = list
+  }
+
   isOpen (to) {
     const p = this.peers.get(to)
     return !!(p && p.dc && p.dc.readyState === 'open')

package/vault/vendor/vault/VERSION.txt

@@ -1,6 +1,6 @@
-Copia vendorizada de @dotrino/vault@0.7.0 (lib/src/{index,enroll}.js, sin dependencias).
+Copia vendorizada de @dotrino/vault@0.18.0 (lib/src/{index,enroll,protocol}.js, sin dependencias).
 El iframe de identity se sirve estatico (vanilla, sin build); asi startDeviceVault
-resuelve en el navegador sin bundler. index.js importa ./enroll.js (relativo, se
-vendoriza tambien) y @dotrino/identity/capabilities (=../../capabilities.js) y
-@dotrino/proxy-client (=../proxy-client/), ambos via el import map de index.html.
-Re-vendorizar AMBOS archivos al subir @dotrino/vault.
+resuelve en el navegador sin bundler. index.js importa ./enroll.js y ./protocol.js
+(relativos, se vendorizan tambien) y @dotrino/identity/capabilities (=../../capabilities.js)
+y @dotrino/proxy-client (=../proxy-client/), ambos via el import map de index.html.
+Re-vendorizar LOS TRES archivos al subir @dotrino/vault.

package/vault/vendor/vault/enroll.js

@@ -39,14 +39,20 @@ 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_HELLO = 'vault.hello'
+export const MSG_HELLO_OK = 'vault.hello.ok'
 export const MSG_ENROLL = 'vault.enroll'
 export const MSG_ENROLL_CHALLENGE = 'vault.enroll.challenge'
 export const MSG_ENROLLED = 'vault.enrolled'
+// --- camino A: la cuenta del aparato pasa a vivir en la bóveda ---
+export const MSG_ENROLL_ADOPT = 'vault.enroll.adopt'
+export const MSG_ACTA_SEALED = 'vault.acta.sealed'
+export const MSG_ACTA_ADOPTED = 'vault.acta.adopted'
 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)
 
@@ -63,12 +69,22 @@ export function scopeToCn (scope) {
   return null
 }
 
-/** Token aleatorio de 128 bits en hex. */
-export function randToken () {
-  const b = crypto.getRandomValues(new Uint8Array(16))
+/**
+ * Token aleatorio en hex (16 bytes = 128 bits por defecto).
+ *
+ * El emparejamiento pide 12 (96 bits): son de un solo uso, valen 5 minutos y hay
+ * UNA sesión viva a la vez, así que adivinarlo es 2^95 intentos contra una bóveda
+ * que además exige el código de 6 dígitos. A cambio, cada byte de menos son ~1,4
+ * caracteres menos en el QR — y el QR se mide en filas de terminal.
+ */
+export function randToken (bytes = 16) {
+  const b = crypto.getRandomValues(new Uint8Array(bytes))
   return [...b].map((x) => x.toString(16).padStart(2, '0')).join('')
 }
 
+/** Tamaño del token/nonce de una sesión de emparejamiento (ver `randToken`). */
+const PAIR_TOKEN_BYTES = 12
+
 /** 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()
@@ -94,27 +110,65 @@ export async function deviceIdOf (pub) {
 export function createEnrollDesk ({
   identity, iss, proxy, send, sendByPubkey,
   audit = () => {}, log = () => {},
-  onChallenge = () => {}, onPendingChange = () => {},
-  defaultScope = ['vault:sign'], defaultTtlMs = DEVICE_TTL_MS
+  onChallenge = () => {}, onPendingChange = () => {}, onAdopted = () => {},
+  defaultScope = ['vault:sign'], defaultTtlMs = DEVICE_TTL_MS,
+  // Camino A: lo que ESTA bóveda le manda al aparato para que la meta en su acta. `encPub`
+  // es su llave de CIFRADO — sin ella entra mandando pero sin poder leer el contenido.
+  encPub = null, vaultLabel = '',
+  // Token de CONEXIÓN de esta bóveda en el proxy (4 chars): su dirección. Es lo
+  // ú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
 
-  /** Inicia un emparejamiento: token + nonce de sesión. NO firma nada todavía. */
-  function startPairing ({ scope = defaultScope, ttlMs = defaultTtlMs, label = '' } = {}) {
+  /**
+   * Inicia un emparejamiento: token + nonce de sesión. NO firma nada todavía.
+   *
+   * `mode` y `account` son LO QUE LA BÓVEDA DECLARA que va a pasar, y viajan en el QR
+   * para que el aparato pueda **decirlo antes de hacerlo** en vez de emparejar a
+   * ciegas (decisión V9 de `docs/vinculacion-de-cuentas.md`: pregunta el vault, el
+   * dispositivo muestra el proceso y sus consecuencias):
+   *
+   *   · `mode: 'join'`  → el dispositivo estrena una cuenta suya y entra a la de la
+   *                       bóveda. Es lo único que existe hoy.
+   *   · `mode: 'adopt'` → la bóveda se quedaría con la cuenta que trae el aparato
+   *                       (camino A). Reservado: todavía no hay protocolo.
+   *   · `account`       → cómo se llama la cuenta de la bóveda, para nombrarla en el
+   *                       aviso. Es ORIENTATIVO (un nombre que puso su dueño); la
+   *                       identidad de verdad de la cuenta es `iss`.
+   */
+  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 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 }
+    const acct = String(account || '').slice(0, 40)
+    // 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' })
+      return { token: sn, qr: { v: 2, conn, sn, m: mode, proxy }, expiresInMs: PAIRING_TTL_MS }
+    }
+    const token = randToken(PAIR_TOKEN_BYTES)
+    const sn = randToken(PAIR_TOKEN_BYTES)
+    pending.set(token, { token, exp: Date.now() + PAIRING_TTL_MS, scope, ttlMs, label, sn, mode, account: acct, state: 'AWAITING_ENROLL' })
+    return { token, qr: { v: 2, iss, proxy, token, sn, m: mode, ...(acct ? { acct } : {}) }, expiresInMs: PAIRING_TTL_MS }
   }
 
   function stopPairing (token) { pending.delete(token) }
@@ -132,6 +186,28 @@ export function createEnrollDesk ({
     return null
   }
 
+  /**
+   * «¿Quién eres?» — la respuesta al QR corto. Solo se contesta a quien presente el
+   * `sn` de una sesión VIVA: el token de conexión son 4 caracteres y se puede acertar
+   * a ciegas, el `sn` no. Fuera de un emparejamiento no hay ninguna sesión y por lo
+   * tanto no hay respuesta: la puerta solo está abierta mientras dura el `pair`.
+   */
+  async function handleHello (from, p) {
+    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 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
+    // de otra bóveda. Lo que NO hace es demostrar que sea TU bóveda —cualquiera puede
+    // firmar con una llave suya—; eso solo lo demuestra el código de 6 dígitos.
+    const body = { op: 'hello', sn: pend.sn, iss, proxy, acct: pend.account || '', m: pend.mode || 'join', ts: Date.now() }
+    const { signature } = await identity.signData(body)
+    reply(from, { type: MSG_HELLO_OK, body, signature })
+    return { ok: true }
+  }
+
   /**
    * 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.
@@ -139,31 +215,42 @@ 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: '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: 'unknown intent: ' + intent })
+    }
+    if (intent !== (pend.mode || 'join')) {
+      audit('rejected', { what: 'enroll', reason: 'intent-mismatch' })
+      return reply(from, { type: MSG_ERROR, error: `este emparejamiento se abrió para «${pend.mode || 'join'}» y el dispositivo pidió «${intent}»` })
     }
-    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)' })
+      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)
@@ -182,9 +269,12 @@ export function createEnrollDesk ({
     }
     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)
+    // Camino A: de qué cuenta estamos hablando. Se guarda para poder comprobar, cuando
+    // llegue el acta sellada, que es la que este dispositivo dijo que iba a entregar.
+    if (intent === 'adopt' && typeof d.profileId === 'string') pend.profileId = d.profileId
 
     reply(from, { type: MSG_ENROLL_CHALLENGE, deviceId })
-    fire(onChallenge, { deviceId, scope: pend.scope, label: pend.label || '' })
+    fire(onChallenge, { deviceId, scope: pend.scope, label: pend.label || '', mode: pend.mode || 'join' })
     fire(onPendingChange)
     return { deviceId }
   }
@@ -199,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]
     }
 
@@ -216,8 +306,22 @@ 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
+    // aparato la meta en el acta de la cuenta que le está pasando. El código de vuelta es
+    // la misma defensa de siempre, en el otro sentido: el aparato solo hace caso a una
+    // bóveda que demuestre que un humano la aprobó.
+    if ((pend.mode || 'join') === 'adopt') {
+      audit('adopt-approve', { device: pend.deviceId, profile: pend.profileId || null })
+      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] adoption approved for %s: waiting for the sealed record', pend.deviceId)
+      fire(onPendingChange)
+      return { ok: true, deviceId: pend.deviceId, adopting: true }
     }
 
     const { cert } = await identity.signDelegation(pend.dpub, pend.scope, { ttlMs: pend.ttlMs, label: pend.label })
@@ -247,13 +351,67 @@ export function createEnrollDesk ({
     return { ok: true, deviceId: pend.deviceId, cert }
   }
 
+  /**
+   * CAMINO A · paso 6: llega el acta que el aparato acaba de sellar, con la bóveda dentro
+   * como miembro, la clave de contenido envuelta para ella y el mando ya traspasado.
+   *
+   * Lo que se comprueba antes de guardar nada (y por qué):
+   *   · que el sellador sea ESTA bóveda — si no, no es un traspaso, es un acta ajena;
+   *   · que la selle el aparato que estaba en este emparejamiento — cierra que un tercero
+   *     que vea pasar el mensaje cuele la suya;
+   *   · que sea la cuenta que ese aparato declaró al enrolarse (`profileId`) — cierra el
+   *     cambiazo de cuenta entre el anuncio que leyó el humano y lo que llega después.
+   *
+   * Adoptar la cuenta de otro solo procede sobre un perfil que **nació para eso** (la marca
+   * de `prepareForAdoption`). Es la misma regla del navegador: sin la marca, adoptar sería
+   * pisar una cuenta con datos, y eso no puede pasar por accidente.
+   */
+  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 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: '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: '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: '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 || '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.
+      const mia = (await identity.profileActa?.())?.acta || acta
+      reply(pend.from, { type: MSG_ACTA_ADOPTED, code: p.code, acta: mia })
+      pend.state = 'DONE'
+      pending.delete(pend.token)
+      fire(onPendingChange)
+      fire(onAdopted, { deviceId: pend.deviceId, profileId: acta.profileId, seq: mia.seq })
+      log('[vault] cuenta adoptada del dispositivo %s (perfil %s)', pend.deviceId, acta.profileId?.slice(0, 12))
+      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: 'the vault could not adopt the account: ' + e.message })
+      return { ok: false, error: e.message }
+    }
+  }
+
   /** 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' })
+    reply(pend.from, { type: MSG_ERROR, error: 'pairing rejected' })
     pending.delete(pend.token)
     audit('reject', { device: pend.deviceId })
     fire(onPendingChange)
@@ -270,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. */
@@ -284,7 +442,7 @@ export function createEnrollDesk ({
   }
 
   return {
-    startPairing, stopPairing, handleEnroll, approve, reject,
+    startPairing, stopPairing, handleEnroll, handleActaSealed, handleHello, approve, reject,
     listPending, findPending, emitRevoke, revoke,
     get pendingCount () { return pending.size }
   }