@dotrino/vaultd 0.38.0 → 0.49.0

package/lib/src/service.js

@@ -22,9 +22,11 @@ import fs from 'node:fs'
 import path from 'node:path'
 import { createHash } from 'node:crypto'
 import {
-  makeDeviceKey, signWithDevice, verifyDelegation, verifyDeviceSig,
-  makePairingCode, commitCode, pubkeyId
+  makeDeviceKey, makeDeviceEncKey, importDeviceEncKey, signWithDevice, verifyDelegation,
+  verifyDeviceSig, makePairingCode, commitCode, pubkeyId
 } from '@dotrino/identity/capabilities'
+import { openWrap, wrapForMember, decryptWithCek } from '@dotrino/identity/content'
+import { verifyActa, sealKeyAt } from '@dotrino/identity/acta'
 import { MSG, secretsScope, isValidSecretsNs } from './protocol.js'
 import { makeEphemeralKey, openSealed } from './sealed.js'
 import { parseInvite } from './invite.js'
@@ -159,6 +161,9 @@ async function identifyAsService (client, device) {
   await client.identify({ data, signature })
 }
 
+/** Cuánto espera un agente a que alguien apruebe (el pedido vive 5 min en la bóveda). */
+export const APPROVAL_TIMEOUT_MS = 5 * 60 * 1000 + 10 * 1000
+
 function waitForMsg (client, predicate, timeoutMs = 30000) {
   return new Promise((resolve, reject) => {
     const off = client.on('message', (_from, payload) => {
@@ -222,47 +227,37 @@ function writeServiceIdentity (dir, obj) {
  *   Se llama ANTES de enrolar si ya había una identidad: la que va a descartarse.
  * @returns {Promise<{device, cert, iss:string, replaced:object|null}>}
  */
-export async function enrollService ({ qr, ns, dir, label, onCode, onReplace, approveTimeoutMs = 180000 } = {}) {
+/**
+ * EL ENROLAMIENTO, a secas: con una invitación de la bóveda (en cualquiera de sus
+ * formas) crea las DOS llaves del aparato —firma y cifrado—, pide el cert y lo
+ * verifica. **No persiste nada**: devuelve la identidad y quien llama decide dónde
+ * vive (`enrollService` la guarda como servicio; `@dotrino/remote-agent` como
+ * `link.json`). Es el único sitio del ecosistema donde se enrola un agente headless:
+ * si falta algo al enrolar, se añade aquí y lo heredan todos.
+ *
+ * @param {Object} opts
+ * @param {object|string} opts.qr   La invitación: objeto, URL del QR o código pegado.
+ * @param {string} [opts.label]
+ * @param {string|null} [opts.expectedScope]  Scope que el cert DEBE traer (null = no se exige).
+ * @param {(c:{deviceId:string, code:string})=>void} [opts.onCode]
+ * @param {number} [opts.approveTimeoutMs]
+ * @returns {Promise<{device, enc:{publickey:string, privateJwk:object}, cert, iss:string, proxy:string}>}
+ */
+export async function enrollWithVault ({ qr, label = 'agent', expectedScope = null, onCode, approveTimeoutMs = 180000 } = {}) {
   // `parseInvite` y NO `JSON.parse`: el vault no imprime JSON desde hace rato.
-  // `dotrino-vault pair --service` emite la URL del QR y el código compacto
-  // (`c…`/`t…`, ver invite.js), así que un `JSON.parse` fallaba SIEMPRE con
-  // «qr inválido: no es JSON» y el enrolamiento de un servicio era imposible por
-  // este camino. Lo tapaba que el único servicio enrolado del ecosistema lo hizo
-  // cuando el formato todavía era JSON. `parseInvite` acepta todas las formas,
-  // incluida la vieja, así que esto entiende cualquier invitación.
+  // `dotrino-vault pair` emite la URL del QR y el código compacto (`c…`/`t…`, ver
+  // invite.js); `parseInvite` acepta todas las formas, incluida la vieja.
   if (typeof qr === 'string') {
     const o = parseInvite(qr)
-    if (!o) throw new Error('that does not look like a vault invitation (paste the output of `dotrino-vault pair --service <ns>`)')
+    if (!o) throw new Error('that does not look like a vault invitation (paste the output of `dotrino-vault pair`)')
     qr = o
   }
   if (!qr?.sn || !(qr.iss || qr.conn)) throw new Error('invalid qr: missing the vault or the nonce')
   rejectAdoption(qr.m)
-  if (!isValidSecretsNs(ns)) throw new Error('invalid ns (use [a-z0-9-]{1,32}, e.g. "proxy")')
-  if (!dir) throw new Error('dir required (where to persist the service identity)')
-  label = label || 'service:' + ns
-
-  // La identidad que va a quedar descartada. Se avisa antes de tocar nada: para
-  // el proxy, por ejemplo, esta llave es además su identidad de red, así que
-  // reemplazarla le cambia el id de nodo y sus peers dejan de reconocerlo hasta
-  // que se re-pineen a mano.
-  const previous = readServiceIdentity(dir)
-  let replaced = null
-  if (previous?.device?.publickey) {
-    replaced = {
-      ns: previous.ns,
-      enrolledAt: previous.enrolledAt,
-      deviceId: (await pubkeyId(previous.device.publickey)).slice(0, 8).toUpperCase()
-    }
-    try { onReplace?.(replaced) } catch (_) {}
-  }
 
   const client = await freshClient(qr.proxy || 'wss://proxy.dotrino.com')
   // QR CORTO: se le pregunta a la bóveda quién es, punto a punto, presentando el `sn`.
   if (!qr.iss) {
-    // `qr.conn` es una CITA (código de 6 caracteres, un solo uso): hay que
-    // canjearla para saber a qué conexión apunta. El canje lo resuelve el proxio
-    // que la emitió —lo dice el prefijo del propio código—, así que funciona
-    // aunque la bóveda esté en otro proxio de la malla.
     const target = await resolveAppointment(client, qr.conn)
     const hello = await new Promise((resolve, reject) => {
       const off = client.on('message', (_f, p) => {
@@ -277,25 +272,22 @@ export async function enrollService ({ qr, ns, dir, label, onCode, onReplace, ap
   }
   try {
     const device = await makeDeviceKey({ label })
+    // La llave de CIFRADO: es a la que la bóveda sella cada variable. Sin ella el
+    // aparato entra al acta pero no le llega ningún secreto, y no da error.
+    const enc = await makeDeviceEncKey()
     const deviceId = (await pubkeyId(device.publickey)).slice(0, 8).toUpperCase().replace(/(.{4})(.{4})/, '$1-$2')
-    // Código ALEATORIO generado AQUÍ: el vault no lo conoce; solo puede echarlo
-    // de vuelta si el dueño lo tipeó (= tiene esta pantalla a la vista).
+    // Código de emparejamiento ALEATORIO: se muestra y NO se envía. La bóveda lo
+    // aprende solo cuando un humano lo tipea → aprobar exige TENER esta máquina.
     const code = makePairingCode()
-    // El COMPROMISO del código (nunca el código): la bóveda lo recompone con lo que
-    // tipeas y solo entonces firma el cert → aprobar exige haber leído esta pantalla.
     const commit = await commitCode({ code, dpub: device.publickey, sn: qr.sn })
-    // `intent: 'join'` EXPLÍCITO. La bóveda lo compara con el modo que abrió y,
-    // si falta, asume `join` — pero un agente no debe apoyarse en un default
-    // para algo que decide de quién es la cuenta. Yendo dentro de `data`, viaja
-    // firmado: nadie en el medio puede convertirlo en una adopción.
-    const data = { op: 'enroll', intent: 'join', dpub: device.publickey, token: qr.token || qr.sn, sn: qr.sn, commit, label, ts: Date.now() }
+    const data = { op: 'enroll', intent: 'join', dpub: device.publickey, encPub: enc.encPublickey, token: qr.token || qr.sn, sn: qr.sn, commit, label, ts: Date.now() }
     const { signature } = await signWithDevice({ privateJwk: device.privateJwk, data })
 
     const enrolled = new Promise((resolve, reject) => {
       const off = client.on('message', (_from, p) => {
         if (!p || typeof p !== 'object') return
         if (p.type === MSG.ENROLL_CHALLENGE) {
-          const show = onCode || (({ deviceId, code }) => console.log(`[vault-service] device ${deviceId} · approve it on the vault:  dotrino-vault approve ${code}`))
+          const show = onCode || (({ deviceId, code }) => console.log(`[vault] device ${deviceId} · approve it on the vault:  dotrino-vault approve ${code}`))
           show({ deviceId, code })
         } else if (p.type === MSG.ENROLLED) { cleanup(); resolve(p) } else if (p.type === MSG.ERROR) { cleanup(); reject(new Error(p.error)) }
       })
@@ -305,17 +297,110 @@ export async function enrollService ({ qr, ns, dir, label, onCode, onReplace, ap
     client.sendByPubkey(qr.iss, { type: MSG.ENROLL, data, signature })
     const res = await enrolled
 
-    // Validación estricta (igual que un dispositivo): cert de la maestra VISTA,
-    // para ESTA llave, y el código echado debe ser el nuestro (anti vault falso).
     if (res.code !== code) throw new Error('the vault echoed a code other than the one shown (possible malicious relay)')
-    const v = await verifyDelegation({ cert: res.cert, expectedSub: device.publickey, expectedScope: secretsScope(ns) })
+    const v = await verifyDelegation({ cert: res.cert, expectedSub: device.publickey, ...(expectedScope ? { expectedScope } : {}) })
     if (!v.ok) throw new Error('invalid cert: ' + v.reason)
     if (res.cert.iss !== qr.iss) throw new Error('cert signed by a master other than the one in the QR')
 
-    // Reemplazo, no acumulación: el archivo se sobrescribe entero y la identidad
-    // anterior deja de existir en este agente.
-    writeServiceIdentity(dir, { v: 1, ns, iss: qr.iss, proxy: qr.proxy, device, cert: res.cert, enrolledAt: Date.now() })
-    return { device, cert: res.cert, iss: qr.iss, replaced }
+    return { device, enc: { publickey: enc.encPublickey, privateJwk: enc.encPrivateJwk }, cert: res.cert, iss: qr.iss, proxy: qr.proxy || 'wss://proxy.dotrino.com' }
+  } finally { client.close() }
+}
+
+/**
+ * Enrola ESTE servicio contra el vault y persiste su identidad.
+ *
+ * UN AGENTE TIENE UNA SOLA IDENTIDAD, Y SE LA DA EL VAULT. A diferencia de un
+ * aparato —que puede llevar varios perfiles y hasta meter su cuenta al vault por
+ * adopción—, un agente no acumula identidades ni transfiere la suya: se enrola,
+ * el vault le cede una (llave propia + cert de la maestra) y **la anterior, si
+ * había, se descarta**. No hay fusión ni convivencia, y no hace falta: un agente
+ * es un servicio, no una persona; no tiene por qué "ser varios".
+ *
+ * Enrolar dos veces, entonces, no es un error a bloquear sino un REEMPLAZO — que
+ * es además la forma de rotar la identidad de un agente comprometido. Lo que sí
+ * hace falta es que se vea: se avisa por `onReplace` qué identidad se tira.
+ *
+ * En el vault se corre antes `dotrino-vault pair --service <ns>`; la invitación
+ * que imprime ese comando es el `qr` de aquí (en cualquiera de sus formas).
+ * Muestra un código por `onCode`: el dueño lo tipea en el vault
+ * (`dotrino-vault approve <código>`).
+ *
+ * @param {Object} opts
+ * @param {object|string} opts.qr  La invitación: objeto, URL del QR o código pegado.
+ * @param {string} opts.ns     Namespace de secretos del servicio (el mismo del pair).
+ * @param {string} opts.dir    Dónde persistir `service-identity.json`.
+ * @param {string} [opts.label]
+ * @param {(c:{deviceId:string, code:string})=>void} [opts.onCode]
+ * @param {(prev:{ns:string, enrolledAt:number, deviceId:string})=>void} [opts.onReplace]
+ *   Se llama ANTES de enrolar si ya había una identidad: la que va a descartarse.
+ * @returns {Promise<{device, cert, iss:string, replaced:object|null}>}
+ */
+export async function enrollService ({ qr, ns, dir, label, onCode, onReplace, approveTimeoutMs = 180000 } = {}) {
+  if (!isValidSecretsNs(ns)) throw new Error('invalid ns (use [a-z0-9-]{1,32}, e.g. "proxy")')
+  if (!dir) throw new Error('dir required (where to persist the service identity)')
+  label = label || 'service:' + ns
+
+  // La identidad que va a quedar descartada. Se avisa antes de tocar nada: para
+  // el proxy, por ejemplo, esta llave es además su identidad de red, así que
+  // reemplazarla le cambia el id de nodo y sus peers dejan de reconocerlo hasta
+  // que se re-pineen a mano.
+  const previous = readServiceIdentity(dir)
+  let replaced = null
+  if (previous?.device?.publickey) {
+    replaced = {
+      ns: previous.ns,
+      enrolledAt: previous.enrolledAt,
+      deviceId: (await pubkeyId(previous.device.publickey)).slice(0, 8).toUpperCase()
+    }
+    try { onReplace?.(replaced) } catch (_) {}
+  }
+
+  const { device, enc, cert, iss, proxy } = await enrollWithVault({ qr, label, expectedScope: secretsScope(ns), onCode, approveTimeoutMs })
+  // v2: suma `enc`. El `device` (la llave de FIRMA) no se toca — de él sale el
+  // id de nodo del proxio y la fila del acta.
+  writeServiceIdentity(dir, { v: 2, ns, iss, proxy, device, enc, cert, enrolledAt: Date.now() })
+  return { device, enc, cert, iss, replaced }
+}
+
+export async function ensureEncKey ({ dir } = {}) {
+  const saved = readServiceIdentity(dir)
+  if (!saved) throw new Error('service not enrolled: run enrollService() first')
+  if (saved.enc?.publickey && saved.enc?.privateJwk) return { encPub: saved.enc.publickey, created: false }
+  const enc = await makeDeviceEncKey()
+  writeServiceIdentity(dir, { ...saved, v: 2, enc: { publickey: enc.encPublickey, privateJwk: enc.encPrivateJwk } })
+  return { encPub: enc.encPublickey, created: true }
+}
+
+/**
+ * Registra en la bóveda la llave de cifrado de ESTE servicio, para que pueda sellarle
+ * sus variables. Genera la llave si falta.
+ *
+ * Va por `MSG.SECRETS` con `op:'enckey'` a propósito: no hace falta una constante nueva
+ * del protocolo, y así el trío de archivos vendorizado en el iframe de identidad no se
+ * mueve. Registrar una llave no da acceso a nada por sí solo —quien firma esta petición
+ * ya tiene la llave de firma del servicio, o sea ya lee ese namespace—, así que no exige
+ * la contraseña del perfil.
+ */
+export async function registerEncKey ({ dir, ns, proxyUrl, masterPubkey, device, cert, timeoutMs = 30000 } = {}) {
+  const saved = readServiceIdentity(dir)
+  const { encPub, created } = await ensureEncKey({ dir })
+  ns = ns || saved?.ns
+  proxyUrl = proxyUrl || saved?.proxy
+  masterPubkey = masterPubkey || saved?.iss
+  device = device || saved?.device
+  cert = cert || saved?.cert
+  if (!proxyUrl || !masterPubkey || !device || !cert) throw new Error('service not enrolled')
+
+  const client = await freshClient(proxyUrl)
+  try {
+    await identifyAsService(client, device)
+    const data = { op: 'enckey', ns, encPub, publickey: device.publickey, ts: Date.now() }
+    const { signature } = await signWithDevice({ privateJwk: device.privateJwk, data })
+    const pending = waitForMsg(client, (p) => p.type === MSG.SECRETS_RESULT || p.type === MSG.ERROR, timeoutMs)
+    client.sendByPubkey(masterPubkey, { type: MSG.SECRETS, data, signature, cert })
+    const res = await pending
+    if (res.type === MSG.ERROR) throw new Error(res.error)
+    return { encPub, created, ok: true }
   } finally { client.close() }
 }
 
@@ -325,9 +410,13 @@ export async function enrollService ({ qr, ns, dir, label, onCode, onReplace, ap
  * Renueva el cert automáticamente si está por vencer (best-effort).
  * @returns {Promise<Record<string,string>>}  secretos KEY→valor
  */
-export async function fetchSecrets ({ dir, ns, proxyUrl, masterPubkey, device, cert, timeoutMs = 30000 } = {}) {
+export async function fetchSecrets ({ dir, ns, proxyUrl, masterPubkey, device, cert, enc, timeoutMs = 30000, onPending, approvalTimeoutMs = APPROVAL_TIMEOUT_MS } = {}) {
   let saved = null
   if (dir) saved = readServiceIdentity(dir)
+  // Sin `dir`: la identidad viene entera por parámetros — es el caso de un agente
+  // enrolado por `@dotrino/remote-agent` (su `link.json` trae `device`, `cert` y `enc`).
+  // Un mismo enrolamiento sirve para el plano de control y para los secretos.
+  if (!saved && enc) saved = { ns, iss: masterPubkey, proxy: proxyUrl, device, cert, enc }
   ns = ns || saved?.ns
   proxyUrl = proxyUrl || saved?.proxy
   masterPubkey = masterPubkey || saved?.iss
@@ -362,9 +451,22 @@ export async function fetchSecrets ({ dir, ns, proxyUrl, masterPubkey, device, c
     const { signature } = await signWithDevice({ privateJwk: device.privateJwk, data })
     const pending = waitForMsg(client, (p) => p.type === MSG.SECRETS_RESULT || p.type === MSG.ERROR, timeoutMs)
     client.sendByPubkey(masterPubkey, { type: MSG.SECRETS, data, signature, cert })
-    const res = await pending
+    let res = await pending
     if (res.type === MSG.ERROR) throw new Error(res.error)
 
+    // CAJÓN CON APROBACIÓN: la bóveda contesta «pendiente» (firmado) y la respuesta de
+    // verdad llega cuando el aparato que aprueba firme — por esta misma conexión, que
+    // sigue identificada. Se espera lo que dura el pedido; denegado o vencido es error.
+    if (res.body?.op === 'secrets.pending' && res.body.ns === ns) {
+      const okPending = await verifyDeviceSig({ publickey: masterPubkey, data: res.body, signature: res.signature })
+      if (!okPending) throw new Error('invalid master signature on the pending reply')
+      try { onPending?.({ id: res.body.id, ns, exp: res.body.exp }) } catch (_) {}
+      const until = typeof res.body.exp === 'number' ? Math.max(5000, res.body.exp - Date.now() + 5000) : approvalTimeoutMs
+      res = await waitForMsg(client, (p) => (p.type === MSG.SECRETS_RESULT && p.body?.op === 'secrets.result') || p.type === MSG.ERROR, Math.min(until, approvalTimeoutMs))
+        .catch((e) => { throw new Error(/timeout/.test(e.message) ? 'approval: nobody approved the request in time' : e.message) })
+      if (res.type === MSG.ERROR) throw new Error(res.error)
+    }
+
     // Autenticidad: el cuerpo viene firmado por la MAESTRA pineada.
     const body = res.body
     if (!body || body.op !== 'secrets.result' || body.ns !== ns) throw new Error('malformed secrets reply')
@@ -373,11 +475,158 @@ export async function fetchSecrets ({ dir, ns, proxyUrl, masterPubkey, device, c
     if (!ok) throw new Error('invalid master signature on the secrets reply')
 
     const payload = await openSealed({ privateKey: eph.privateKey, enc: body.enc })
+
+    // DOS CAPAS DE SOBRE, y hacen cosas distintas:
+    //   · la de fuera (`ek` efímera, recién abierta) tapa el TRAMO — el proxio no ve
+    //     ni los nombres de tus variables;
+    //   · la de dentro (`sealed`) tapa el REPOSO — la bóveda guarda lo que reparte
+    //     sin poder abrirlo.
+    // Se quedan las dos: quitar la de fuera dejaría los nombres al aire.
+    if (payload?.sealed) return openSealedBundle(payload.sealed, saved, payload.acta, masterPubkey)
+
+    // Bóveda todavía en v3: manda los valores tal cual, como siempre. Desaparece
+    // cuando el último vault haya migrado (ver `docs/secretos-sellados.md`).
     if (!payload || typeof payload.secrets !== 'object') throw new Error('malformed secrets envelope')
     return payload.secrets
   } finally { client.close() }
 }
 
+/**
+ * AGENTE SSH DELGADO (`dotrino-env ssh-agent`): este proceso no custodia nada. Lista las
+ * llaves públicas que la bóveda tiene registradas y, por cada reto, le pide a la bóveda
+ * que lo convierta en un PEDIDO que el teléfono firma. Cualquier aparato con `vault:sign`
+ * puede pedir; quien decide es el teléfono.
+ */
+function serviceArgs ({ dir, ns, proxyUrl, masterPubkey, device, cert }) {
+  let saved = dir ? readServiceIdentity(dir) : null
+  if (!saved && device && cert) saved = { ns, iss: masterPubkey, proxy: proxyUrl, device, cert }
+  const out = { ns: ns || saved?.ns, proxyUrl: proxyUrl || saved?.proxy, masterPubkey: masterPubkey || saved?.iss, device: device || saved?.device, cert: cert || saved?.cert }
+  if (!out.proxyUrl || !out.masterPubkey || !out.device || !out.cert) throw new Error('service not enrolled: run enrollService() first (service-identity.json missing)')
+  return out
+}
+async function sshRpc (args, data, { timeoutMs = 30000, waitResult = null } = {}) {
+  const { proxyUrl, masterPubkey, device, cert } = serviceArgs(args)
+  const client = await freshClient(proxyUrl)
+  try {
+    await identifyAsService(client, device)
+    const signed = { ...data, publickey: device.publickey, ts: Date.now() }
+    const { signature } = await signWithDevice({ privateJwk: device.privateJwk, data: signed })
+    const pending = waitForMsg(client, (p) => p.type === MSG.SECRETS_RESULT || p.type === MSG.ERROR, timeoutMs)
+    client.sendByPubkey(masterPubkey, { type: MSG.SECRETS, data: signed, signature, cert })
+    let res = await pending
+    if (res.type === MSG.ERROR) throw new Error(res.error)
+    if (waitResult && res.body?.op === 'ssh.pending') {
+      try { waitResult.onPending?.({ id: res.body.id, exp: res.body.exp }) } catch (_) {}
+      const until = typeof res.body.exp === 'number' ? Math.max(5000, res.body.exp - Date.now() + 5000) : APPROVAL_TIMEOUT_MS
+      res = await waitForMsg(client, (p) => (p.type === MSG.SECRETS_RESULT && p.body?.op === 'ssh.sign.result') || p.type === MSG.ERROR, Math.min(until, APPROVAL_TIMEOUT_MS))
+        .catch((e) => { throw new Error(/timeout/.test(e.message) ? 'ssh: nobody approved the request in time' : e.message) })
+      if (res.type === MSG.ERROR) throw new Error(res.error)
+    }
+    const ok = await verifyDeviceSig({ publickey: masterPubkey, data: res.body, signature: res.signature })
+    if (!ok) throw new Error('invalid master signature on the reply')
+    return res.body
+  } finally { client.close() }
+}
+/** Las llaves SSH públicas registradas en la bóveda: `[{ id, blob, comment }]`. */
+export async function listSshKeys (args = {}) {
+  const body = await sshRpc(args, { op: 'ssh.keys.public' })
+  return Array.isArray(body.items) ? body.items : []
+}
+/** Pide la firma SSH de `data` con la llave `keyId`; devuelve el blob de firma (Buffer). */
+export async function requestSshSign (args = {}, { keyId, data, onPending } = {}) {
+  const body = await sshRpc(args, { op: 'ssh.sign', key: keyId, data: Buffer.from(data).toString('base64') }, { waitResult: { onPending } })
+  if (typeof body.sig !== 'string') throw new Error('ssh: malformed signature reply')
+  return Buffer.from(body.sig, 'base64')
+}
+
+/**
+ * Abre un bundle sellado: saca la CEK de la envoltura dirigida a este aparato y
+ * descifra con ella las variables privadas. Las públicas vienen en claro.
+ *
+ * Un fallo al abrir es un ERROR DURO, nunca un salto a lo del scope ni un valor
+ * omitido: silenciarlo convertiría una rotación mal sellada en «el servicio sigue
+ * con el valor viejo y nadie se entera», que es el peor modo de fallo de todo esto.
+ */
+/**
+ * ¿SALIÓ ESTE SOBRE DE MI BÓVEDA? (§8.8 de `dotrino-vault/docs/secretos-sellados.md`)
+ *
+ * Envolver una llave solo necesita públicas, así que **cualquiera puede fabricar un sobre
+ * válido** para este servicio: abrirlo prueba que es para mí, no que lo escribió quien
+ * debía. Lo que lo prueba es la firma, hecha con la llave de sellado que el acta nombra
+ * para el `seq` con el que se firmó — y el acta la firma la maestra, que es la que este
+ * agente lleva pineada desde que se enroló.
+ *
+ * Una firma que NO cuadra es un error duro: es exactamente el caso que esto viene a
+ * cazar. Un sobre SIN firma se acepta y se avisa: los hay de antes de que esto existiera
+ * y negarse a arrancar por eso apagaría servicios que llevan meses bien.
+ */
+export async function makeSealCheck (acta, masterPubkey, log = console.log) {
+  if (!acta) return () => {}
+  // El acta tiene que venir firmada por la maestra que este agente ya conoce. Si la
+  // selló otro (un traspaso que este agente no ha visto), no se puede establecer
+  // procedencia: se dice y se sigue, en vez de fingir que se comprobó.
+  const ok = acta.sealedBy === masterPubkey && (await verifyActa({ acta })).ok
+  if (!ok) {
+    log('[vault] ⚠ the record does not come from the master this agent knows: envelope provenance NOT checked')
+    return () => {}
+  }
+  let avisado = false
+  return async (owner, key, gen, e, seal) => {
+    if (!seal?.sig) {
+      if (!avisado) { avisado = true; log('[vault] ⚠ some envelopes carry no signature (sealed before this vault could sign)') }
+      return
+    }
+    const pub = sealKeyAt(acta, seal.seq)
+    if (!pub) throw new Error(`${key}: the record has no sealing key for #${seal.seq} (the envelope claims a record that does not exist)`)
+    const good = await verifyDeviceSig({ publickey: pub, data: { owner, key, gen, iv: e.iv, ct: e.ct }, signature: seal.sig })
+    if (!good) throw new Error(`${key}: the envelope signature does not check out — it did not come from this vault`)
+  }
+}
+
+async function openSealedBundle (sealed, ident, acta = null, masterPubkey = null) {
+  if (!ident?.enc?.privateJwk) {
+    throw new Error('this service has no encryption key: update @dotrino/vault and re-enroll it')
+  }
+  const mine = await importDeviceEncKey(ident.enc.privateJwk)
+
+  // UNA LLAVE POR GENERACIÓN, no una por cajón. Desde v5 cada escritura estrena
+  // generación —la bóveda no puede reutilizar una llave que no puede abrir—, así que dos
+  // variables del mismo cajón pueden venir de generaciones distintas. El bundle trae
+  // TODAS las envolturas de este aparato; se abren perezosamente, solo las que hagan
+  // falta. `sealed.ns`/`sealed.dev` (una sola, la vigente) siguen entrando: es el bundle
+  // de v4 y sirve para lo que ese vault selló.
+  const porGen = { ns: new Map(), dev: new Map() }
+  const añade = (cual, info) => { if (info?.wrap) porGen[cual].set(info.gen ?? 0, info.wrap) }
+  añade('ns', sealed.ns); añade('dev', sealed.dev)
+  for (const cual of ['ns', 'dev']) for (const info of sealed.wraps?.[cual] || []) añade(cual, info)
+
+  const abiertas = { ns: new Map(), dev: new Map() }
+  const cekDe = async (cual, gen) => {
+    if (abiertas[cual].has(gen)) return abiertas[cual].get(gen)
+    // Un bundle de v4 no traía `gen` en la envoltura: si solo hay una, es esa.
+    const wrap = porGen[cual].get(gen) ?? (porGen[cual].size === 1 ? [...porGen[cual].values()][0] : null)
+    if (!wrap) return null
+    const cek = await openWrap({ wrap, myEncPrivateKey: mine })
+    abiertas[cual].set(gen, cek)
+    return cek
+  }
+
+  const comprobarFirma = await makeSealCheck(acta, masterPubkey)
+
+  const out = {}
+  for (const [key, e] of Object.entries(sealed.entries || {})) {
+    if (e.pub) { out[key] = e.v; continue }
+    // `owner` dice de qué cajón salió, y `gen` con qué llave de ese cajón se abre.
+    const cual = String(e.owner || '').startsWith('dev:') ? 'dev' : 'ns'
+    const gen = e.gen ?? e.e?.gen ?? 0
+    await comprobarFirma(e.owner, key, gen, e.e, e.seal)
+    const cek = await cekDe(cual, gen)
+    if (!cek) throw new Error(`no key to open ${key}: this device has no wrapping for its drawer`)
+    out[key] = await decryptWithCek({ cek, envelope: e.e })
+  }
+  return out
+}
+
 /**
  * Escucha los avisos de cambio de configuración de la bóveda.
  *
@@ -489,8 +738,59 @@ export async function watchSecretsChanges ({
     try { onRevoked?.({ nonce: body.nonce }) } catch (e) { log('[vault] ' + e.message) }
   }
 
+  /**
+   * REPARTIR LA LLAVE DE MI CAJÓN a un miembro nuevo (§8.11 del diseño).
+   *
+   * Un aparato que entra después de escrita una variable no tiene envoltura de ella, y
+   * la bóveda no se la puede hacer: envolver exige abrir la llave, y abrirla pide la
+   * frase. Este agente SÍ la tiene abierta, así que la reparte él. No gana ningún poder
+   * haciéndolo —ya podía leer eso— y por eso es el único que puede hacerlo sin que
+   * nadie ceda nada.
+   *
+   * NO SE FÍA DE LO QUE LE MANDAN, y esto es lo que hace que sea seguro incluso si la
+   * bóveda estuviera comprometida:
+   *
+   *  · la petición va firmada por la MAESTRA;
+   *  · el acta viaja dentro y se comprueba aparte (también la firma la maestra);
+   *  · **la llave pública del destinatario se saca del ACTA, nunca del mensaje** — si
+   *    se cogiera del mensaje, quien lo mandara podría hacer que este agente envolviera
+   *    la llave para una pública suya;
+   *  · y el destinatario tiene que ser de ESTE cajón (`cn === ns`): un servicio no puede
+   *    ampliar el acceso a nada que no sea lo suyo.
+   */
+  const handleRewrap = async (payload) => {
+    const body = payload?.body
+    if (!body || body.op !== 'rewrap') return
+    const mineOwners = [`ns:${ns}`, `dev:${saved.device.publickey}`]
+    if (!mineOwners.includes(body.owner)) return log('[vault] rewrap for a drawer that is not mine: ignored')
+    if (!(await verifyDeviceSig({ publickey: master, data: body, signature: payload.signature }))) {
+      return log('[vault] rewrap request BADLY SIGNED: ignored')
+    }
+    const acta = body.acta
+    if (!acta || acta.sealedBy !== master || !(await verifyActa({ acta })).ok) {
+      return log('[vault] rewrap request without a valid record: ignored')
+    }
+    const target = (acta.members || []).find((m) => m.pub === body.target)
+    if (!target?.encPub) return log('[vault] rewrap: the target is not in the record (or has no encryption key)')
+    if (target.cn !== ns) return log(`[vault] rewrap: ${String(body.target).slice(0, 12)}… is not part of «${ns}»: refused`)
+
+    try {
+      const ident = readServiceIdentity(dir)
+      if (!ident?.enc?.privateJwk) return log('[vault] rewrap: this agent has no encryption key')
+      const cek = await openWrap({ wrap: body.wrap, myEncPrivateKey: await importDeviceEncKey(ident.enc.privateJwk) })
+      const wrap = await wrapForMember({ cek, memberEncPub: target.encPub })
+      const data = { op: 'rewrap.ok', owner: body.owner, gen: body.gen, target: body.target, wrap, ts: Date.now() }
+      const { signature } = await signWithDevice({ privateJwk: saved.device.privateJwk, data })
+      client.sendByPubkey(master, { type: MSG.REWRAP_OK, data, signature, cert: saved.cert })
+      log(`[vault] key handed to ${String(body.target).slice(0, 12)}… for ${body.owner} (gen ${body.gen})`)
+    } catch (e) {
+      log('[vault] rewrap failed: ' + e.message)
+    }
+  }
+
   const handleMessage = async (payload) => {
     if (payload?.type === MSG.REVOKED) return handleRevocation(payload)
+    if (payload?.type === MSG.REWRAP) return handleRewrap(payload)
     if (payload?.type !== MSG.SECRETS_CHANGED) return
     const body = payload.body
     if (!body || body.op !== 'secrets.changed' || body.ns !== ns) return
@@ -646,15 +946,16 @@ function fingerprintOf (secrets) {
  * servicio no opera hasta que esto resuelva — esa es la regla.
  * @returns {Promise<Record<string,string>>}
  */
-export async function waitForSecrets ({ dir, ns, proxyUrl, masterPubkey, device, cert, retryMs = 5000, maxRetryMs = 60000, onRetry } = {}) {
+export async function waitForSecrets ({ dir, ns, proxyUrl, masterPubkey, device, cert, enc, retryMs = 5000, maxRetryMs = 60000, onRetry, onPending } = {}) {
   let delay = retryMs
   for (;;) {
     try {
-      return await fetchSecrets({ dir, ns, proxyUrl, masterPubkey, device, cert })
+      return await fetchSecrets({ dir, ns, proxyUrl, masterPubkey, device, cert, enc, onPending })
     } catch (e) {
       // Lo NO transitorio no se arregla reintentando: falta de enrolamiento,
       // cert revocado/vencido o scope equivocado exigen re-emparejar → se corta.
-      if (/not enrolled|invalid ns|unauthorized: (revoked|expired|scope|cn|untrusted-issuer|cert-device-mismatch)/.test(e.message)) throw e
+      // Que te lo DENIEGUEN tampoco se reintenta: fue una decisión, no un tropiezo.
+      if (/not enrolled|invalid ns|unauthorized: (revoked|expired|scope|cn|untrusted-issuer|cert-device-mismatch|denied)/.test(e.message)) throw e
       try { onRetry?.(e, delay) } catch (_) {}
       await new Promise((r) => setTimeout(r, delay))
       delay = Math.min(maxRetryMs, Math.round(delay * 1.6))

package/lib/src/sshAgent.js

@@ -0,0 +1,100 @@
+/**
+ * AGENTE SSH del daemon: un socket Unix con el protocolo de `ssh-agent` (draft-miller-
+ * ssh-agent), para que el `ssh` del usuario firme con la llave que vive en su TELÉFONO.
+ *
+ * Lo que hace es poco a propósito: listar las llaves públicas registradas y, en cada
+ * `SIGN_REQUEST`, pedirle la firma al aparato que aprueba (`vault.requestSshSign`) y
+ * devolverla. No guarda llaves privadas, no acepta que le añadan (`ssh-add` de una llave
+ * del disco se rechaza: la idea es justo que no haya llaves en el disco) y no hace de
+ * proxy de nada más.
+ *
+ *   export SSH_AUTH_SOCK=$XDG_RUNTIME_DIR/dotrino-vault/ssh-agent.sock
+ *   ssh-add -L          # las llaves del teléfono
+ *   ssh mi-servidor     # el teléfono pide tu «sí» y firma
+ */
+import fs from 'node:fs'
+import net from 'node:net'
+import path from 'node:path'
+import { sshString, readStrings } from './sshKeys.js'
+
+const AGENT_FAILURE = 5
+const AGENT_SUCCESS = 6
+const REQUEST_IDENTITIES = 11
+const IDENTITIES_ANSWER = 12
+const SIGN_REQUEST = 13
+const SIGN_RESPONSE = 14
+
+/** Dónde va el socket: en el directorio de ejecución del usuario si lo hay (se limpia solo). */
+export function defaultSocketPath (dir) {
+  const run = process.env.XDG_RUNTIME_DIR
+  return run ? path.join(run, 'dotrino-vault', 'ssh-agent.sock') : path.join(dir, 'ssh-agent.sock')
+}
+
+const frame = (type, payload = Buffer.alloc(0)) => {
+  const body = Buffer.concat([Buffer.from([type]), payload])
+  const len = Buffer.alloc(4); len.writeUInt32BE(body.length)
+  return Buffer.concat([len, body])
+}
+
+/**
+ * @param {{ socketPath: string, vault: () => { sshKeys: () => any[], requestSshSign: (a: { keyId: string, data: Buffer }) => Promise<Buffer> }, log?: Function }} opts
+ */
+export function startSshAgent ({ socketPath, vault, log = () => {}, refresh = null }) {
+  fs.mkdirSync(path.dirname(socketPath), { recursive: true, mode: 0o700 })
+  try { fs.unlinkSync(socketPath) } catch (_) {}
+
+  async function handle (type, payload) {
+    if (refresh) { try { await refresh() } catch (_) {} }
+    const v = vault()
+    if (type === REQUEST_IDENTITIES) {
+      const keys = v.sshKeys()
+      const n = Buffer.alloc(4); n.writeUInt32BE(keys.length)
+      const parts = keys.map((k) => Buffer.concat([sshString(Buffer.from(k.blob, 'base64')), sshString(Buffer.from(k.comment || ''))]))
+      return frame(IDENTITIES_ANSWER, Buffer.concat([n, ...parts]))
+    }
+    if (type === SIGN_REQUEST) {
+      const [blob, data] = readStrings(payload, 2)
+      const key = v.sshKeys().find((k) => k.blob === blob.toString('base64'))
+      if (!key) return frame(AGENT_FAILURE)
+      try {
+        const sig = await v.requestSshSign({ keyId: key.id, data })
+        return frame(SIGN_RESPONSE, sshString(sig))
+      } catch (e) {
+        log('[vault] ssh-agent: not signed: ' + e.message)
+        return frame(AGENT_FAILURE)
+      }
+    }
+    // Añadir/quitar llaves, candado, extensiones: nada de eso vive aquí.
+    return frame(AGENT_FAILURE)
+  }
+
+  const server = net.createServer((sock) => {
+    let buf = Buffer.alloc(0)
+    let busy = Promise.resolve()
+    sock.on('data', (chunk) => {
+      buf = Buffer.concat([buf, chunk])
+      while (buf.length >= 4) {
+        const len = buf.readUInt32BE(0)
+        if (len < 1 || len > 256 * 1024) { sock.destroy(); return }
+        if (buf.length < 4 + len) break
+        const type = buf[4]; const payload = buf.subarray(5, 4 + len)
+        buf = buf.subarray(4 + len)
+        // En orden: el protocolo es petición-respuesta, y un cliente que encadena dos
+        // firmas espera las respuestas en el mismo orden.
+        busy = busy.then(() => handle(type, payload)).then((out) => { if (!sock.destroyed) sock.write(out) }).catch(() => { if (!sock.destroyed) sock.write(frame(AGENT_FAILURE)) })
+      }
+    })
+    sock.on('error', () => {})
+  })
+  server.on('error', (e) => log('[vault] ssh-agent: ' + e.message))
+  server.listen(socketPath, () => {
+    try { fs.chmodSync(socketPath, 0o600) } catch (_) {}
+    log(`[vault] ssh-agent listening at ${socketPath}  (export SSH_AUTH_SOCK=${socketPath})`)
+  })
+  return {
+    socketPath,
+    close () { try { server.close() } catch (_) {} try { fs.unlinkSync(socketPath) } catch (_) {} }
+  }
+}
+
+export default { startSshAgent, defaultSocketPath, AGENT_SUCCESS }