@dotrino/vault 0.29.0 → 0.31.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotrino/vault",
-  "version": "0.29.0",
+  "version": "0.31.0",
   "description": "Usa ESTE dispositivo (navegador) como bóveda/CA del ecosistema Dotrino: atiende enrolamientos por el proxy y firma certificados de delegación a tus máquinas. Incluye el cliente de SERVICIO (Node): un proyecto se enrola una vez y jala sus credenciales del vault en vez del .env (`import '@dotrino/vault/config'`).",
   "type": "module",
   "main": "src/index.js",
@@ -24,6 +24,9 @@
     "./sealed": {
       "import": "./src/sealed.js"
     },
+    "./invite": {
+      "import": "./src/invite.js"
+    },
     "./protocol": {
       "import": "./src/protocol.js"
     }
@@ -43,7 +46,7 @@
     "pairing"
   ],
   "peerDependencies": {
-    "@dotrino/identity": ">=0.56.0",
+    "@dotrino/identity": "^0.58.0",
     "@dotrino/proxy-client": ">=0.9.0"
   },
   "license": "MIT",

package/src/enroll.js

@@ -341,8 +341,11 @@ export function createEnrollDesk ({
     let record = null
     try {
       if (typeof identity.admitMember === 'function') {
+        // PERMISOS, no tipos (2026-08-22): las capacidades son las del scope ENTERO. Un
+        // cajón (`secrets:<ns>`) suma `secrets` y fija el CN; no borra lo demás — un bot
+        // con `sign,secrets:eco` firma como aparato del acta Y lee solo su cajón.
         const cn = scopeToCn(pend.scope)
-        const caps = cn ? ['secrets'] : scopeToCaps(pend.scope)
+        const caps = [...new Set([...scopeToCaps(pend.scope), ...(cn ? ['secrets'] : [])])]
         if (caps.length) await identity.admitMember({ pub: pend.dpub, encPub: pend.encPub || null, label: pend.label || '', cn, caps, cert, continuity: pend.continuity || null })
       }
       record = (await identity.profileActa?.())?.acta || null

package/src/env.js

@@ -98,12 +98,12 @@ let lastApplied = null
  *   `overridden` = las que YA tenían otro valor en el entorno y el vault pisó. Es
  *   el dato que delata un `.env` rancio, así que se reporta en vez de callarse.
  */
-export async function loadEnv ({ ns, dir, override, wait = true, required = [], onRetry } = {}) {
+export async function loadEnv ({ ns, dir, override, wait = true, required = [], onRetry, onPending } = {}) {
   if (override === undefined) override = overrideByDefault()
   ns = resolveNs(ns)
   dir = dir || serviceDir(ns)
   const load = wait ? waitForSecrets : fetchSecrets
-  const secrets = await load({ dir, ns, onRetry })
+  const secrets = await load({ dir, ns, onRetry, onPending })
 
   const missing = required.filter((k) => !(k in secrets))
   if (missing.length) {

package/src/protocol.js

@@ -97,7 +97,8 @@ export const SCOPE = Object.freeze({
   // Consola remota (docs/consola-remota.md): admitir y expulsar miembros a distancia.
   // NO incluye cambiar permisos, traspasar el mando ni conceder `admin`: eso es el rol
   // de master y sigue siendo local. No se empareja — se concede desde el PC.
-  ADMIN: 'vault:admin'
+  ADMIN: 'vault:admin',
+  APPROVE: 'vault:approve' // aprobar pedidos de secretos (cajones con `approval`); se concede a mano, como admin
 })
 
 /**

package/src/service.js

@@ -161,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) => {
@@ -224,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) => {
@@ -279,22 +272,14 @@ export async function enrollService ({ qr, ns, dir, label, onCode, onReplace, ap
   }
   try {
     const device = await makeDeviceKey({ label })
-    // La llave de CIFRADO, hermana de la de firma. Sin ella el vault no puede
-    // sellarle sus variables a ESTE aparato, y arrancaría sin configuración sin
-    // que nadie sepa por qué. Su pública viaja en el enrolamiento y acaba en el
-    // acta como `encPub`; la privada no sale de este disco.
+    // 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, encPub: enc.encPublickey, token: qr.token || qr.sn, sn: qr.sn, commit, label, ts: Date.now() }
     const { signature } = await signWithDevice({ privateJwk: device.privateJwk, data })
 
@@ -302,7 +287,7 @@ export async function enrollService ({ qr, ns, dir, label, onCode, onReplace, ap
       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)) }
       })
@@ -312,35 +297,71 @@ 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.
-    // v2: suma `enc`. El `device` (la llave de FIRMA) no se toca — de él sale el
-    // `nodeId` del proxio, y cambiarlo le costaría su cajón de variables.
-    writeServiceIdentity(dir, { v: 2, ns, iss: qr.iss, proxy: qr.proxy, device, enc: { publickey: enc.encPublickey, privateJwk: enc.encPrivateJwk }, cert: res.cert, enrolledAt: Date.now() })
-    return { device, enc, 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() }
 }
 
 /**
- * Se asegura de que este servicio TENGA llave de cifrado, generándola si le falta.
+ * Enrola ESTE servicio contra el vault y persiste su identidad.
  *
- * Existe para los agentes que se enrolaron ANTES de que la llave existiera: su
- * `service-identity.json` es v1 y solo lleva la de firma. Sin esto, la única forma de
- * conseguirla sería re-enrolarse — y re-enrolar le cambia la pubkey, con lo que pierde
- * su cajón de variables (va indexado por ella) y arrancaría sin configuración, en
- * silencio. Ese es justo el accidente que esta función existe para evitar.
+ * 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".
  *
- * La llave de FIRMA no se toca: de ella sale el `nodeId` del proxio.
+ * 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.
  *
- * @returns {Promise<{ encPub: string, created: boolean }>}
+ * 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')
@@ -389,9 +410,13 @@ export async function registerEncKey ({ dir, ns, proxyUrl, masterPubkey, device,
  * 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
@@ -426,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')
@@ -860,15 +898,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))