@dotrino/vault 0.53.0 → 0.54.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotrino/vault",
-  "version": "0.53.0",
+  "version": "0.54.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",

package/src/enroll.js

@@ -52,7 +52,18 @@ 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', 'vault:admin': 'admin', 'vault:passwords': 'passwords' }
+const SCOPE_TO_CAP = {
+  'vault:sign': 'sign',
+  'vault:store': 'store',
+  'vault:read': 'read',
+  'vault:admin': 'admin',
+  'vault:passwords': 'passwords',
+  // `replica` SÍ se empareja, al revés que `sealer` y `admin`. La razón es la misma que
+  // hace estrecho al permiso: un replicador reparte sobres que no puede abrir y no cambia
+  // nada. Y se despliega sin teclado —un contenedor, una máquina ajena—, que es justo
+  // donde obligar a un segundo paso a mano es el paso que nadie da.
+  'vault:replica': 'replica'
+}
 export const scopeToCaps = (scope) =>
   (Array.isArray(scope) ? scope : [scope]).map((s) => SCOPE_TO_CAP[s]).filter(Boolean)
 

package/src/service.js

@@ -25,7 +25,7 @@ import {
   makeDeviceKey, makeDeviceEncKey, importDeviceEncKey, signWithDevice, verifyDelegation,
   verifyDeviceSig, makePairingCode, commitCode, pubkeyId } from '@dotrino/identity/capabilities'
 import { openWrap, wrapForMember, decryptWithCek } from '@dotrino/identity/content'
-import { verifyActa, sealKeyAt, sealersOf } from '@dotrino/identity/acta'
+import { verifyActa, sealKeyAt, sealersOf, memberCan } from '@dotrino/identity/acta'
 import { MSG, secretsScope, isValidSecretsNs } from './protocol.js'
 import { makeEphemeralKey, openSealed } from './sealed.js'
 import { parseInvite } from './invite.js'
@@ -241,7 +241,17 @@ function writeServiceIdentity (dir, obj) {
  * @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 } = {}) {
+/**
+ * @param {boolean} [opts.withEncKey] Estrenar llave de CIFRADO y registrarla en el acta.
+ *   Por defecto sí: sin ella el aparato entra pero no le llega ningún secreto.
+ *
+ *   Un REPLICADOR entra con `false`, y no es una optimización: es su garantía. Regla del
+ *   dueño (2026-09-02), *«recibirá todos los sobres que se generen, ningún sobre firmado
+ *   para él»*. Sin `encPub` en el acta no hay a dónde envolverle nada, así que repartir no
+ *   puede convertirse en leer ni por descuido ni por un cambio futuro. Es el mismo cerrojo
+ *   que tiene la llave de comunicación.
+ */
+export async function enrollWithVault ({ qr, label = 'agent', expectedScope = null, onCode, approveTimeoutMs = 180000, withEncKey = true } = {}) {
   // `parseInvite` y NO `JSON.parse`: el vault no imprime JSON desde hace rato.
   // `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.
@@ -271,14 +281,15 @@ export async function enrollWithVault ({ qr, label = 'agent', expectedScope = nu
   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()
+    // aparato entra al acta pero no le llega ningún secreto, y no da error. Un replicador
+    // entra así A PROPÓSITO (ver `withEncKey`): reparte sobres cerrados y no abre ninguno.
+    const enc = withEncKey ? await makeDeviceEncKey() : null
     const deviceId = (await pubkeyId(device.publickey)).slice(0, 8).toUpperCase().replace(/(.{4})(.{4})/, '$1-$2')
     // 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()
     const commit = await commitCode({ code, dpub: device.publickey, sn: qr.sn })
-    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 data = { op: 'enroll', intent: 'join', dpub: device.publickey, encPub: enc?.encPublickey || null, 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) => {
@@ -313,7 +324,7 @@ export async function enrollWithVault ({ qr, label = 'agent', expectedScope = nu
     })
     if (!v.ok) throw new Error('invalid cert: ' + v.reason)
 
-    return { device, enc: { publickey: enc.encPublickey, privateJwk: enc.encPrivateJwk }, cert: res.cert, iss: qr.iss, proxy: qr.proxy || 'wss://proxy.dotrino.com' }
+    return { device, enc: enc ? { publickey: enc.encPublickey, privateJwk: enc.encPrivateJwk } : null, cert: res.cert, iss: qr.iss, proxy: qr.proxy || 'wss://proxy.dotrino.com' }
   } finally { client.close() }
 }
 
@@ -459,10 +470,23 @@ export async function fetchSecrets ({ dir, ns, proxyUrl, masterPubkey, device, c
     saved = { ...saved, ...patch }
     if (dir) { try { writeServiceIdentity(dir, saved) } catch (_) {} }
   }
-  /** Hasta qué acta hemos visto: es lo que dispara la renovación la próxima vez. */
+  /**
+   * Hasta qué acta hemos visto. Dispara la renovación la próxima vez, y desde que hay
+   * replicadores es además el freno anti-rollback (`verifyResponder`).
+   *
+   * SOLO SUBE. Antes escribía cualquier `seq` que llegara, también uno MENOR: bastaba que
+   * alguien contestara con un acta vieja para que el pin bajara y dejara de proteger de
+   * ahí en adelante. Un pin que retrocede no es un pin — se llama `maxSeq` en el diseño
+   * justo por esto (`acta-de-perfil.md` §2.3).
+   */
   const anotarActa = (acta) => {
-    if (typeof acta?.seq !== 'number' || saved?.actaSeq === acta.seq) return
-    recordar({ actaSeq: acta.seq })
+    if (typeof acta?.seq !== 'number') return
+    if (typeof saved?.actaSeq === 'number' && acta.seq <= saved.actaSeq) return
+    // Y QUIÉNES REPARTEN. Sale del acta, que llega firmada en cada respuesta, así que no
+    // hay una lista que mantener a mano ni un `.env` que se olvide: darle `replica` a un
+    // aparato basta para que sus servicios sepan preguntarle cuando la bóveda no esté.
+    const replicas = (acta.members || []).filter((m) => memberCan(acta, m.pub, 'replica')).map((m) => m.pub)
+    recordar({ actaSeq: acta.seq, replicas })
   }
 
     // DOS MOTIVOS PARA PEDIR PAPEL NUEVO:
@@ -503,16 +527,35 @@ export async function fetchSecrets ({ dir, ns, proxyUrl, masterPubkey, device, c
     // poner por el camino. Quien decide qué se manda es la bóveda; esto solo es la petición.
     const data = { op: 'secrets', ns, ek: eph.ek, publickey: device.publickey, ts: Date.now(), ...(publicOnly ? { publicOnly: true } : {}) }
     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 })
-    let res = await pending
+    // A QUIÉN SE LE PREGUNTA: primero a la bóveda, y si no contesta, a los REPLICADORES
+    // que el acta nombraba la última vez que la vimos (`docs/replicas.md` §8: «el servicio
+    // lleva una lista de bóvedas y las prueba en orden»).
+    //
+    // Sin esto, un replicador no servía absolutamente para nada: el mensaje se mandaba a
+    // la llave de la bóveda y, con la bóveda apagada, no llegaba a ninguna parte. Lo
+    // destapó el smoke con las dos máquinas encendidas y la bóveda muerta, que es
+    // exactamente el caso que un replicador existe para cubrir.
+    //
+    // La bóveda va PRIMERO siempre: un replicador solo puede estar igual de al día o menos.
+    const destinos = [masterPubkey, ...(saved?.replicas || []).filter((k) => k !== masterPubkey)]
+    // El plazo se reparte: no tiene sentido esperar el timeout entero a una bóveda apagada
+    // y quedarse sin tiempo para preguntarle a quien sí está.
+    const porDestino = Math.max(4000, Math.round(timeoutMs / destinos.length))
+    let res = null
+    let ultimo = null
+    for (const destino of destinos) {
+      const pending = waitForMsg(client, (p) => p.type === MSG.SECRETS_RESULT || p.type === MSG.ERROR, porDestino)
+      client.sendByPubkey(destino, { type: MSG.SECRETS, data, signature, cert })
+      try { res = await pending; break } catch (e) { ultimo = e }
+    }
+    if (!res) throw ultimo || new Error('nobody answered: neither the vault nor any replica')
     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) {
-      await verifyResponder({ body: res.body, seal: res.seal, acta: res.acta, masterPubkey })
+      await verifyResponder({ body: res.body, seal: res.seal, acta: res.acta, masterPubkey, knownSeq: saved?.actaSeq ?? null })
       anotarActa(res.acta)
       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
@@ -534,7 +577,7 @@ export async function fetchSecrets ({ dir, ns, proxyUrl, masterPubkey, device, c
     // confía en nadie — solo saca el acta con la que SÍ se comprueba. Nada de lo que hay
     // dentro se usa hasta después de verificar.
     const payload = await openSealed({ privateKey: eph.privateKey, enc: body.enc })
-    await verifyResponder({ body, seal: res.seal, acta: payload?.acta, masterPubkey })
+    await verifyResponder({ body, seal: res.seal, acta: payload?.acta, masterPubkey, knownSeq: saved?.actaSeq ?? null })
     anotarActa(payload?.acta)
 
     // DOS CAPAS DE SOBRE, y hacen cosas distintas:
@@ -578,8 +621,32 @@ export async function fetchSecrets ({ dir, ns, proxyUrl, masterPubkey, device, c
  * Sin el paso 1 el paso 2 no vale nada: un acta cualquiera nombraría la llave que
  * quisiera.
  */
-export async function verifyResponder ({ body, seal, acta, masterPubkey }) {
-  if (!seal?.sig || typeof seal.seq !== 'number') {
+/**
+ * ¿QUIÉN PUEDE HABERME CONTESTADO ESTO? Hay dos respuestas legítimas y una condición.
+ *
+ *   · **La bóveda.** Firma con la llave de sellado que el acta nombra para ese `seq`. Es
+ *     el camino de siempre y no cambia.
+ *   · **Un REPLICADOR** (`seal.by`). No tiene esa llave —no tiene maestra— así que firma
+ *     con la suya de aparato, y lo que la autoriza es que el acta le reconozca `replica`.
+ *     Reparte lo que la bóveda ya selló: los sobres de dentro se siguen comprobando contra
+ *     la llave de sellado (`makeSealCheck`), así que un replicador no puede inventarse
+ *     contenido, solo entregarlo.
+ *
+ * LA CONDICIÓN, y es la que cierra el agujero que `replicas.md` §6.1 llama «construir el
+ * ataque»: **un replicador solo le contesta a quien YA conoce la cuenta.** Un replicador
+ * atrasado presenta un acta donde un aparato revocado sigue siendo miembro; contra eso, a
+ * quien tiene `maxSeq` pineado lo protege el pin, pero a un aparato que llega nuevo no hay
+ * con qué compararlo. Así que sin pin no se le cree: que conteste la bóveda.
+ *
+ * El precio, dicho en voz alta: un aparato nuevo necesita la bóveda encendida una vez. El
+ * oráculo de frescura (§2.4.2 del acta) es lo que quitaría ese precio; mientras no exista,
+ * esto es el freno, y es un freno de verdad y no un aviso.
+ *
+ * @param {number|null} [knownSeq] El `seq` más alto que este agente ya vio de esta cuenta.
+ *   `null`/ausente = no conoce la cuenta, y entonces un replicador no vale.
+ */
+export async function verifyResponder ({ body, seal, acta, masterPubkey, knownSeq = null }) {
+  if (!seal?.sig) {
     throw new Error('the reply carries no sealing signature: this vault is too old to serve (update it)')
   }
   if (!acta) throw new Error('the reply carries no record: cannot tell which key was allowed to sign it')
@@ -587,6 +654,33 @@ export async function verifyResponder ({ body, seal, acta, masterPubkey }) {
     throw new Error('the record was not sealed by the master this agent knows: refusing the reply')
   }
   if (!(await verifyActa({ acta })).ok) throw new Error('the record does not verify')
+
+  // NUNCA HACIA ATRÁS. Vale para los dos caminos: un acta con `seq` menor del que ya
+  // vimos es un rollback, venga de donde venga.
+  if (typeof knownSeq === 'number' && typeof acta.seq === 'number' && acta.seq < knownSeq) {
+    throw Object.assign(
+      new Error(`the record went backwards (#${acta.seq} after #${knownSeq}): refusing the reply`),
+      { code: 'stale-record' })
+  }
+
+  if (seal.by) {
+    if (typeof knownSeq !== 'number') {
+      throw Object.assign(
+        new Error('a replica answered, and this device has never seen the account: ask the vault itself the first time'),
+        { code: 'replica-unknown-account' })
+    }
+    if (!memberCan(acta, seal.by, 'replica')) {
+      throw new Error('the reply comes from a device the record does not allow to serve as a replica')
+    }
+    if (!(await verifyDeviceSig({ publickey: seal.by, data: body, signature: seal.sig }))) {
+      throw new Error('the replica signature does not check out')
+    }
+    return
+  }
+
+  if (typeof seal.seq !== 'number') {
+    throw new Error('the reply carries no sealing signature: this vault is too old to serve (update it)')
+  }
   const pub = sealKeyAt(acta, seal.seq)
   if (!pub) throw new Error(`the record names no sealing key for #${seal.seq}`)
   if (!(await verifyDeviceSig({ publickey: pub, data: body, signature: seal.sig }))) {