@dotrino/vault 0.1.1 → 0.2.0

package/package.json

@@ -1,13 +1,22 @@
 {
   "name": "@dotrino/vault",
-  "version": "0.1.1",
-  "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. Contraparte browser del daemon dotrino-vault, reutilizable por cualquier app.",
+  "version": "0.2.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 servicio del ecosistema se enrola como dispositivo y obtiene sus secretos del vault en vez del .env.",
   "type": "module",
   "main": "src/index.js",
   "module": "src/index.js",
   "exports": {
     ".": {
       "import": "./src/index.js"
+    },
+    "./service": {
+      "import": "./src/service.js"
+    },
+    "./sealed": {
+      "import": "./src/sealed.js"
+    },
+    "./protocol": {
+      "import": "./src/protocol.js"
     }
   },
   "files": [

package/src/index.js

@@ -35,6 +35,7 @@ const MSG = {
   ENROLLED: 'vault.enrolled',
   DEVICES: 'vault.devices',
   DEVICES_RESULT: 'vault.devices.result',
+  REVOKED: 'vault.revoked',
   ERROR: 'vault.error'
 }
 
@@ -127,8 +128,19 @@ export async function startDeviceVault (identity, { proxyUrl } = {}) {
     send(from, { type: MSG.ENROLL_CHALLENGE, deviceId })
   }
 
+  // Emite un REVOKED FIRMADO por la maestra a la máquina revocada para que se
+  // auto-borre. Va por `sendByPubkey` → si está offline, el proxy lo encola 24 h; y
+  // si reaparece más tarde, `handleDevices` lo re-emite en su siguiente consulta.
+  // El auto-borrado remoto SOLO se dispara con esta firma (no con un error cualquiera).
+  async function emitRevoke (dpub, nonce) {
+    const body = { op: 'revoke', sub: dpub, nonce, iat: Date.now(), exp: Date.now() + DEVICE_TTL_MS }
+    const { signature } = await identity.signData(body)
+    try { client.sendByPubkey(dpub, { type: MSG.REVOKED, body, signature }) } catch (_) {}
+  }
+
   // Consulta de revocaciones (igual que `vault.devices` del daemon): responde la lista
-  // de dispositivos enrolados + revocados para que el dispositivo refresque su set.
+  // de dispositivos enrolados + revocados para que el dispositivo refresque su set. Y si
+  // QUIEN consulta es una máquina ya revocada (reapareció), le re-emite el REVOKED firmado.
   async function handleDevices (from, p) {
     const d = p?.data
     if (!d || !p.signature || !p.cert) return send(from, { type: MSG.ERROR, error: 'petición inválida' })
@@ -141,6 +153,9 @@ export async function startDeviceVault (identity, { proxyUrl } = {}) {
       label: x.label || '', scope: x.scope, exp: x.exp, nonce: x.nonce
     })))
     send(from, { type: MSG.DEVICES_RESULT, devices, revoked: (revoked || []).map((r) => r.nonce || r) })
+    // ¿el que consulta es una máquina revocada que reapareció? → re-emite el REVOKED firmado.
+    const mine = (issued || []).find((x) => x.sub === chk.device && x.revokedAt)
+    if (mine) emitRevoke(chk.device, mine.nonce)
   }
 
   client.on('message', (_from, p) => {
@@ -214,7 +229,14 @@ export async function startDeviceVault (identity, { proxyUrl } = {}) {
   }
 
   async function revoke (nonce) {
-    return identity.revokeDelegation(nonce)
+    // Deja el registro persistente (revokedAt en la delegación) y AVISA a la máquina
+    // con un REVOKED firmado para que se auto-borre (ahora si está online, o al
+    // reaparecer vía handleDevices). Ver emitRevoke.
+    const { issued } = await identity.listDelegations()
+    const dele = (issued || []).find((d) => d.nonce === nonce)
+    const res = await identity.revokeDelegation(nonce)
+    if (dele?.sub) await emitRevoke(dele.sub, nonce)
+    return res
   }
 
   return {

package/src/protocol.js

@@ -0,0 +1,53 @@
+/**
+ * Protocolo de mensajes entre un dispositivo y el vault (viajan por el proxy,
+ * direccionados por pubkey con `sendByPubkey`). El cuerpo va JSON-serializado en
+ * el campo `message` del sobre del proxy; el cliente lo entrega ya parseado.
+ *
+ * Emparejamiento ENDURECIDO (ver dotrino-vault/docs/pairing-protocol.md):
+ *   1. dispositivo → vault   ENROLL { data:{op,dpub,token,sn,label,ts}, signature }
+ *      (la firma es del dispositivo con su llave D = PRUEBA DE POSESION; un token
+ *       robado ya NO basta para enrolar).
+ *   2. vault → dispositivo   ENROLL_CHALLENGE { deviceId, sas }   (aun NO firma cert)
+ *   3. el dueño compara el SAS (pantalla del dispositivo ↔ del PC) y APRUEBA en el PC
+ *   4. vault → dispositivo   ENROLLED { cert, iss, sas }   (recien aqui firma el cert)
+ *   5. el dispositivo VALIDA la cadena: cert.iss === el iss que vio, cert.sub === D.
+ *
+ * Revocacion (robo): el vault envia REVOKED { body, signature } FIRMADO por la
+ * maestra → el dispositivo se autoborra SOLO si la firma valida contra la maestra
+ * pineada (cierra el wipe-DoS; un ERROR plano jamas borra).
+ */
+export const MSG = Object.freeze({
+  ENROLL: 'vault.enroll',                     // dispositivo → vault: { data, signature }
+  ENROLL_CHALLENGE: 'vault.enroll.challenge', // vault → dispositivo: { deviceId, sas }
+  ENROLLED: 'vault.enrolled',                 // vault → dispositivo (tras aprobar): { cert, iss, sas }
+  REVOKED: 'vault.revoked',                   // vault → dispositivo: { body:{op,sub,nonce,iat,exp}, signature }
+  SIGN: 'vault.sign',                         // dispositivo → vault: { data, signature, cert }
+  SIGNED: 'vault.signed',                     // vault → dispositivo: { signature, publickey, device }
+  GET: 'vault.get',                           // dispositivo → vault: { data, signature, cert }
+  DATA: 'vault.data',                         // vault → dispositivo: { id, node }
+  STORE: 'vault.store',                       // dispositivo → vault: { data:{method,args,publickey,ts}, signature, cert }
+  STORE_RESULT: 'vault.store.result',         // vault → dispositivo: { method, result }
+  DEVICES: 'vault.devices',                   // dispositivo → vault: { data:{publickey,ts}, signature, cert }
+  DEVICES_RESULT: 'vault.devices.result',     // vault → dispositivo: { devices, revoked }
+  RENEW: 'vault.renew',                       // dispositivo → vault: { data:{op,publickey,ts}, signature, cert }
+  RENEWED: 'vault.renewed',                   // vault → dispositivo: { cert }  (cert fresco, misma sub-clave/scope)
+  SECRETS: 'vault.secrets',                   // servicio → vault: { data:{op,ns,ek,publickey,ts}, signature, cert }
+  SECRETS_RESULT: 'vault.secrets.result',     // vault → servicio: { body:{op,ns,enc,ts}, signature } (enc SELLADO a ek; body firmado por la maestra)
+  ERROR: 'vault.error'                        // vault → dispositivo: { error }
+})
+
+/** Capacidades que puede llevar un `cert` (scope). Mínimo por defecto. */
+export const SCOPE = Object.freeze({
+  SIGN: 'vault:sign',   // pedir a la maestra que firme datos (identidad)
+  READ: 'vault:read',   // leer nodos del árbol de contenidos
+  STORE: 'vault:store'  // leer/escribir el store de hilos + aperturas del usuario
+})
+
+/**
+ * Scope de SECRETOS por namespace de servicio: un cert con `vault:secrets:proxy`
+ * solo puede leer los secretos del ns `proxy` — un VPS comprometido no puede
+ * pedir los de otro servicio. ns válido: [a-z0-9-]{1,32}.
+ */
+export const SECRETS_SCOPE_PREFIX = 'vault:secrets:'
+export const secretsScope = (ns) => SECRETS_SCOPE_PREFIX + ns
+export const isValidSecretsNs = (ns) => typeof ns === 'string' && /^[a-z0-9-]{1,32}$/.test(ns)

package/src/sealed.js

@@ -0,0 +1,84 @@
+/**
+ * Sobres SELLADOS para respuestas del vault con contenido sensible (secretos).
+ *
+ * El proxy transporta pero NUNCA debe ver el contenido. Como la llave de
+ * dispositivo `D` es ECDSA (solo firma), el que PIDE genera una llave ECDH
+ * EFÍMERA por petición (`ek`) y la manda dentro del sobre firmado por `D`
+ * (→ ek queda autenticada por la cadena D←maestra). El vault sella la
+ * respuesta a esa ek: ECDH efímero propio + AES-256-GCM. Reproducir una
+ * respuesta vieja es inerte: cada petición usa una ek nueva y el replay no
+ * se puede descifrar.
+ *
+ * La AUTENTICIDAD de la respuesta no la da este módulo sino la firma de la
+ * maestra sobre el cuerpo (el dispositivo la verifica contra la `iss` pineada).
+ *
+ * WebCrypto puro (browser y Node ≥20). Cripto alineada al ecosistema:
+ * P-256 + AES-GCM, llaves como JWK string.
+ */
+
+const subtle = globalThis.crypto.subtle
+
+function b64 (buf) {
+  const bytes = new Uint8Array(buf)
+  let s = ''
+  for (let i = 0; i < bytes.length; i++) s += String.fromCharCode(bytes[i])
+  return btoa(s)
+}
+
+function fromB64 (str) {
+  const bin = atob(str)
+  const out = new Uint8Array(bin.length)
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i)
+  return out
+}
+
+async function deriveAesKey (privateKey, publicJwkStr) {
+  const pub = await subtle.importKey(
+    'jwk', JSON.parse(publicJwkStr),
+    { name: 'ECDH', namedCurve: 'P-256' }, false, []
+  )
+  const bits = await subtle.deriveBits({ name: 'ECDH', public: pub }, privateKey, 256)
+  return subtle.importKey('raw', bits, { name: 'AES-GCM' }, false, ['encrypt', 'decrypt'])
+}
+
+/**
+ * Genera la llave ECDH EFÍMERA del solicitante (una por petición).
+ * `ek` (JWK string pública) viaja en el sobre firmado; `privateKey` se queda
+ * en memoria para abrir la respuesta.
+ */
+export async function makeEphemeralKey () {
+  const kp = await subtle.generateKey({ name: 'ECDH', namedCurve: 'P-256' }, false, ['deriveBits'])
+  const jwk = await subtle.exportKey('jwk', kp.publicKey)
+  return { ek: JSON.stringify({ kty: jwk.kty, crv: jwk.crv, x: jwk.x, y: jwk.y }), privateKey: kp.privateKey }
+}
+
+/**
+ * Sella `payload` (cualquier JSON) hacia la ek del solicitante.
+ * @returns {Promise<{epk:string, iv:string, ct:string}>}
+ */
+export async function seal ({ ek, payload }) {
+  const eph = await subtle.generateKey({ name: 'ECDH', namedCurve: 'P-256' }, false, ['deriveBits'])
+  const key = await deriveAesKey(eph.privateKey, ek)
+  const iv = globalThis.crypto.getRandomValues(new Uint8Array(12))
+  const pt = new TextEncoder().encode(JSON.stringify(payload))
+  const ct = await subtle.encrypt({ name: 'AES-GCM', iv }, key, pt)
+  const epkJwk = await subtle.exportKey('jwk', eph.publicKey)
+  return {
+    epk: JSON.stringify({ kty: epkJwk.kty, crv: epkJwk.crv, x: epkJwk.x, y: epkJwk.y }),
+    iv: b64(iv),
+    ct: b64(ct)
+  }
+}
+
+/**
+ * Abre un sobre sellado con la privada efímera de `makeEphemeralKey()`.
+ * Lanza si el sobre no es para esa llave (AES-GCM autentica el contenido).
+ */
+export async function openSealed ({ privateKey, enc }) {
+  if (!enc || typeof enc.epk !== 'string' || typeof enc.iv !== 'string' || typeof enc.ct !== 'string') {
+    throw new Error('sobre sellado inválido')
+  }
+  const key = await deriveAesKey(privateKey, enc.epk)
+  const pt = await subtle.decrypt({ name: 'AES-GCM', iv: fromB64(enc.iv) }, key, fromB64(enc.ct))
+  return JSON.parse(new TextDecoder().decode(pt))
+}

package/src/service.js

@@ -0,0 +1,237 @@
+/**
+ * Cliente de SERVICIO del vault (Node ≥22). Para que un servicio del ecosistema
+ * (proxy, geo, bots…) sea un CLIENTE IDENTIFICADO más y obtenga sus secretos
+ * del vault en vez de llevarlos en el `.env`:
+ *
+ *   1. En el vault:  `dotrino-vault pair --service proxy`  (QR/código con scope
+ *      SOLO `vault:secrets:proxy`) y `dotrino-vault secret set proxy TURN_KEY_ID …`
+ *   2. En el servicio (una vez):  `enrollService({ qr, ns, dir })` — genera la
+ *      llave del servicio, muestra el código de aprobación y persiste
+ *      `service-identity.json` (device + cert + iss + proxy).
+ *   3. En cada arranque:  `waitForSecrets({ dir, ns })` — pide los secretos y,
+ *      si el vault no está, REINTENTA para siempre (regla del ecosistema: sin
+ *      vault, el servicio espera; no arranca con secretos viejos ni vacíos).
+ *
+ * Seguridad: la petición va firmada por la llave del servicio + cert (cadena
+ * D←maestra, scope `vault:secrets:<ns>`); la respuesta viene SELLADA (ECDH
+ * efímero + AES-GCM → el proxy no ve los valores) y FIRMADA por la maestra
+ * (verificada contra la `iss` pineada en el enrolamiento → un relay no puede
+ * inyectar secretos falsos).
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import {
+  makeDeviceKey, signWithDevice, verifyDelegation, verifyDeviceSig,
+  makePairingCode, pubkeyId
+} from '@dotrino/identity/capabilities'
+import { MSG, secretsScope, isValidSecretsNs } from './protocol.js'
+import { makeEphemeralKey, openSealed } from './sealed.js'
+
+const IDENTITY_FILE = 'service-identity.json'
+const FRESH_WINDOW_MS = 5 * 60 * 1000
+const RENEW_BEFORE_MS = 7 * 24 * 60 * 60 * 1000 // renovar el cert si vence en <7 días
+
+let _globalsInstalled = false
+function installNodeGlobals () {
+  if (_globalsInstalled) return
+  _globalsInstalled = true
+  // localStorage en memoria: @dotrino/proxy-client lo usa solo para su keypair
+  // de canales (que un servicio no necesita persistir). Se define SIN leer el
+  // getter nativo: en Node ≥22 acceder a `globalThis.localStorage` sin
+  // `--localstorage-file` es no-funcional y además emite un warning.
+  const desc = Object.getOwnPropertyDescriptor(globalThis, 'localStorage')
+  const isUsable = desc && 'value' in desc && typeof desc.value?.getItem === 'function'
+  if (!isUsable) {
+    const mem = new Map()
+    Object.defineProperty(globalThis, 'localStorage', {
+      configurable: true,
+      value: {
+        getItem: (k) => (mem.has(k) ? mem.get(k) : null),
+        setItem: (k, v) => mem.set(k, String(v)),
+        removeItem: (k) => mem.delete(k),
+        clear: () => mem.clear(),
+        key: (i) => [...mem.keys()][i] ?? null,
+        get length () { return mem.size }
+      }
+    })
+  }
+  if (typeof globalThis.WebSocket === 'undefined') {
+    throw new Error('este entorno no tiene WebSocket global: usa Node ≥22')
+  }
+}
+
+async function freshClient (proxyUrl) {
+  installNodeGlobals()
+  const { WebSocketProxyClient } = await import('@dotrino/proxy-client')
+  const client = new WebSocketProxyClient({ url: proxyUrl, enableWebRTC: false, autoReconnect: false })
+  await client.connect()
+  return client
+}
+
+/** Identifica la conexión bajo la pubkey del servicio (para ser direccionable). */
+async function identifyAsService (client, device) {
+  const data = { op: 'identify', publickey: device.publickey, token: client.token, ts: Date.now() }
+  const { signature } = await signWithDevice({ privateJwk: device.privateJwk, data })
+  await client.identify({ data, signature })
+}
+
+function waitForMsg (client, predicate, timeoutMs = 30000) {
+  return new Promise((resolve, reject) => {
+    const off = client.on('message', (_from, payload) => {
+      if (payload && typeof payload === 'object' && predicate(payload)) { cleanup(); resolve(payload) }
+    })
+    const t = setTimeout(() => { cleanup(); reject(new Error('timeout esperando respuesta del vault')) }, timeoutMs)
+    const cleanup = () => { off(); clearTimeout(t) }
+  })
+}
+
+const identityFileOf = (dir) => path.join(dir, IDENTITY_FILE)
+
+/** Lee la identidad persistida del servicio ({device, cert, iss, proxy, ns}) o null. */
+export function readServiceIdentity (dir) {
+  try { return JSON.parse(fs.readFileSync(identityFileOf(dir), 'utf8')) } catch (_) { return null }
+}
+
+function writeServiceIdentity (dir, obj) {
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 })
+  const f = identityFileOf(dir)
+  fs.writeFileSync(f, JSON.stringify(obj, null, 2), { mode: 0o600 })
+}
+
+/**
+ * Enrola ESTE servicio contra el vault (una sola vez; persiste la identidad).
+ * En el vault se corre antes `dotrino-vault pair --service <ns>`; el QR/payload
+ * de ese comando es el `qr` de aquí. Muestra un código por `onCode` (o stdout):
+ * el dueño lo tipea en el vault (`dotrino-vault approve <código>`).
+ *
+ * @param {Object} opts
+ * @param {{v:number, iss:string, proxy:string, token:string, sn:string}|string} opts.qr  QR v2 (objeto o JSON string).
+ * @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]
+ * @returns {Promise<{device, cert, iss:string}>}
+ */
+export async function enrollService ({ qr, ns, dir, label, onCode, approveTimeoutMs = 180000 } = {}) {
+  if (typeof qr === 'string') { try { qr = JSON.parse(qr) } catch (_) { throw new Error('qr inválido: no es JSON') } }
+  if (!qr?.iss || !qr?.proxy || !qr?.token || !qr?.sn) throw new Error('qr inválido (v2): faltan iss/proxy/token/sn')
+  if (!isValidSecretsNs(ns)) throw new Error('ns inválido (usa [a-z0-9-]{1,32}, p.ej. "proxy")')
+  if (!dir) throw new Error('falta dir (dónde persistir la identidad del servicio)')
+  label = label || 'servicio:' + ns
+
+  const client = await freshClient(qr.proxy)
+  try {
+    const device = await makeDeviceKey({ label })
+    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).
+    const code = makePairingCode()
+    const data = { op: 'enroll', dpub: device.publickey, token: qr.token, sn: qr.sn, 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] dispositivo ${deviceId} · aprueba en el 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)) }
+      })
+      const t = setTimeout(() => { cleanup(); reject(new Error('timeout esperando la aprobación en el vault')) }, approveTimeoutMs)
+      const cleanup = () => { off(); clearTimeout(t) }
+    })
+    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('el vault devolvió un código distinto al mostrado (posible relay malicioso)')
+    const v = await verifyDelegation({ cert: res.cert, expectedSub: device.publickey, expectedScope: secretsScope(ns) })
+    if (!v.ok) throw new Error('cert inválido: ' + v.reason)
+    if (res.cert.iss !== qr.iss) throw new Error('cert firmado por una maestra distinta a la del QR')
+
+    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 }
+  } finally { client.close() }
+}
+
+/**
+ * Pide los secretos del ns al vault (una petición puntual; lanza si falla).
+ * Usa la identidad persistida por `enrollService` salvo que se pase explícita.
+ * 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 } = {}) {
+  let saved = null
+  if (dir) saved = readServiceIdentity(dir)
+  ns = ns || saved?.ns
+  proxyUrl = proxyUrl || saved?.proxy
+  masterPubkey = masterPubkey || saved?.iss
+  device = device || saved?.device
+  cert = cert || saved?.cert
+  if (!isValidSecretsNs(ns)) throw new Error('ns inválido')
+  if (!proxyUrl || !masterPubkey || !device || !cert) {
+    throw new Error('servicio sin enrolar: corre primero enrollService() (falta service-identity.json)')
+  }
+
+  const client = await freshClient(proxyUrl)
+  try {
+    await identifyAsService(client, device)
+
+    // Renovación de cert best-effort si vence pronto (mientras siga vigente).
+    if (typeof cert.exp === 'number' && cert.exp - Date.now() < RENEW_BEFORE_MS && cert.exp > Date.now()) {
+      try {
+        const data = { op: 'renew', publickey: device.publickey, ts: Date.now() }
+        const { signature } = await signWithDevice({ privateJwk: device.privateJwk, data })
+        const pending = waitForMsg(client, (p) => p.type === MSG.RENEWED || p.type === MSG.ERROR, 15000)
+        client.sendByPubkey(masterPubkey, { type: MSG.RENEW, data, signature, cert })
+        const res = await pending
+        if (res.type === MSG.RENEWED && res.cert?.sub === device.publickey) {
+          const v = await verifyDelegation({ cert: res.cert, expectedSub: device.publickey, expectedScope: secretsScope(ns) })
+          if (v.ok) { cert = res.cert; if (dir && saved) writeServiceIdentity(dir, { ...saved, cert }) }
+        }
+      } catch (_) { /* la renovación no bloquea el fetch */ }
+    }
+
+    const eph = await makeEphemeralKey()
+    const data = { op: 'secrets', ns, ek: eph.ek, 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)
+
+    // 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('respuesta de secretos malformada')
+    if (typeof body.ts !== 'number' || Math.abs(Date.now() - body.ts) > FRESH_WINDOW_MS) throw new Error('respuesta de secretos vencida')
+    const ok = await verifyDeviceSig({ publickey: masterPubkey, data: body, signature: res.signature })
+    if (!ok) throw new Error('firma de la maestra inválida en la respuesta de secretos')
+
+    const payload = await openSealed({ privateKey: eph.privateKey, enc: body.enc })
+    if (!payload || typeof payload.secrets !== 'object') throw new Error('sobre de secretos malformado')
+    return payload.secrets
+  } finally { client.close() }
+}
+
+/**
+ * Bucle de arranque de un servicio: pide los secretos y, si el vault no está
+ * disponible, REINTENTA para siempre (con backoff hasta `maxRetryMs`). El
+ * 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 } = {}) {
+  let delay = retryMs
+  for (;;) {
+    try {
+      return await fetchSecrets({ dir, ns, proxyUrl, masterPubkey, device, cert })
+    } catch (e) {
+      // Lo NO transitorio no se arregla reintentando: falta de enrolamiento,
+      // cert revocado/vencido o scope equivocado exigen re-emparejar → se corta.
+      if (/sin enrolar|ns inválido|no autorizado: (revoked|expired|scope|untrusted-issuer|cert-device-mismatch)/.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))
+    }
+  }
+}