@dotrino/vault 0.14.0 → 0.15.1

package/README.md

@@ -91,12 +91,54 @@ que los secretos estén. Si el vault no está disponible, **espera** (reintento
 backoff) — un servicio sin vault no arranca, no opera con secretos viejos ni vacíos.
 Un fallo NO transitorio (sin enrolar, cert revocado, scope equivocado) sí aborta.
 
+#### Esperar al vault es la REGLA. La excepción es una sola
+
+Un agente enrolado **espera**. No es una preferencia: arrancar igual significaría
+operar con la configuración vieja del `.env`, que es justo lo que el vault vino a
+dejar de ser. Y la espera casi nunca duele, porque estos agentes no son críticos:
+que un bot o un firmador tarden en levantar no rompe a nadie.
+
+La **única** excepción conocida es **el proxio**, y no por importancia sino por una
+razón estructural: el vault habla con sus servicios **por el proxio**. Un proxio que
+espera al vault espera a alguien que necesita que el proxio ya esté escuchando —
+abrazo mortal, y con él se cae el vault de todo el mundo. Por eso el proxio arranca
+con lo que tenga y aplica la configuración cuando llega, con `applyEnv`.
+
+> `applyEnv` existe **para ese caso**, no como alternativa cómoda al bloqueo. Si tu
+> agente no está en el camino por el que viaja el propio vault, usa
+> `import '@dotrino/vault/config'` y deja que espere. El precio de la excepción es
+> real: lo que sólo se lee al arrancar llega tarde y no toma efecto hasta reiniciar,
+> así que hay que avisarlo en el log — el proxio lo hace.
+
 Para procesos que no son Node, el CLI los inyecta en el entorno de un hijo:
 
 ```bash
 dotrino-env run --ns miapp -- ./mi-binario
 ```
 
+### Un agente tiene UNA identidad, y se la da el vault
+
+Un **aparato** puede llevar varios perfiles, y hasta meter su propia cuenta al vault
+por adopción: llega con una historia que conservar. Un **agente** no es eso. Es un
+servicio: su identidad se la cede el vault y no hay caso en que quiera empujar la
+suya hacia arriba. De ahí tres reglas, que el paquete aplica solas:
+
+- **No adopta, nunca.** La invitación declara su modo (`join` / `adopt`); si viene
+  abierta para adoptar, `enrollService` la **rechaza al pegarla**, sin salir a la red.
+  La intención `join` va además firmada dentro de la petición, para que nadie en el
+  medio la convierta en otra cosa.
+- **No acumula.** Enrolar de nuevo **reemplaza** la identidad anterior, que deja de
+  existir en ese agente. No es un error a desbloquear con `--force`: es la forma de
+  **rotar** la identidad de un agente comprometido. Se avisa por `onReplace` qué se
+  descarta.
+- **Un agente, un `ns`.** Varios agentes pueden convivir en una máquina (un
+  directorio por namespace); lo que no existe es un agente que sea varios.
+
+> ⚠ Si esa llave es además la **identidad de red** del servicio —el caso del proxio,
+> cuyo id de nodo se deriva de ella— reemplazarla le cambia el nombre en la red: las
+> instancias y citas vivas dejan de resolver y los peers que lo tenían pineado lo
+> rechazan hasta re-pinearlo. Es a propósito: así se echa a un nodo comprometido.
+
 ### Precedencia: el vault MANDA
 
 Los valores del vault **pisan** los del `.env` y los del entorno. El vault no

package/bin/dotrino-env.js

@@ -26,7 +26,6 @@ import { parseInvite as sharedParseInvite } from '../src/invite.js'
 
 const argv = process.argv.slice(2)
 const flag = (name) => { const i = argv.indexOf('--' + name); return i >= 0 ? argv[i + 1] : undefined }
-const has = (name) => argv.includes('--' + name)
 
 function help () {
   console.log(`dotrino-env — credenciales del vault en vez del .env
@@ -75,9 +74,6 @@ async function cmdEnroll () {
   const ns = flag('ns')
   if (!ns) { console.error('falta --ns <ns>  (el mismo del `dotrino-vault pair --service <ns>`)'); process.exit(2) }
   const dir = flag('dir') || serviceDir(ns)
-  if (readServiceIdentity(dir) && !has('force')) {
-    console.error('ya hay un servicio enrolado en %s (usa --force para re-enrolar)', dir); process.exit(2)
-  }
   const qr = parseInvite(flag('qr') || await readInvite())
 
   console.log('\nEnrolando el servicio "%s" contra el vault…', ns)
@@ -86,6 +82,17 @@ async function cmdEnroll () {
     ns,
     dir,
     label: flag('label') || 'servicio:' + ns,
+    // Un agente tiene UNA identidad y se la da el vault: re-enrolar REEMPLAZA,
+    // no acumula. Antes había una reja (`--force`) que hacía de esto un error a
+    // desbloquear; sobra, porque no existe la alternativa de "quedarse con las
+    // dos". Lo que sí corresponde es que se vea qué se está tirando.
+    onReplace: (prev) => {
+      console.log('\n  ⚠ Este agente YA tenía identidad (dispositivo %s, del %s).',
+        prev.deviceId, new Date(prev.enrolledAt).toISOString().slice(0, 10))
+      console.log('    Se DESCARTA: el vault le cede una nueva y la anterior deja de existir aquí.')
+      console.log('    Si esa llave era además la identidad de red del servicio (el caso del')
+      console.log('    proxio), su id de nodo cambia y sus peers lo rechazan hasta re-pinearlo.\n')
+    },
     onCode: ({ deviceId, code }) => {
       console.log('\n  Dispositivo: %s', deviceId)
       console.log('  APRUEBA en el vault tipeando este código:\n')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotrino/vault",
-  "version": "0.14.0",
+  "version": "0.15.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. 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/env.js

@@ -113,10 +113,19 @@ export async function loadEnv ({ ns, dir, override, wait = true, required = [],
 /**
  * Vuelca un bundle de secretos en `process.env` y cuenta qué cambió.
  *
- * Separado de `loadEnv` porque un servicio que NO puede bloquear su arranque
- * esperando al vault (el proxy: el vault le habla POR el proxy, así que
- * esperarlo sería un abrazo mortal) igual necesita aplicar el bundle cuando
- * llegue, tarde y por su cuenta.
+ * ⚠ ESTO NO ES LA FORMA NORMAL. Un agente enrolado ESPERA al vault
+ * (`loadEnv` / `import '@dotrino/vault/config'`): arrancar igual sería operar con
+ * la configuración vieja del `.env`, que es justo lo que el vault vino a dejar de
+ * ser, y la espera casi nunca duele porque estos agentes no son críticos.
+ *
+ * `applyEnv` existe para la ÚNICA excepción estructural: **el proxio**. El vault
+ * habla con sus servicios POR el proxio, así que un proxio que espera al vault
+ * espera a alguien que necesita el proxio escuchando — abrazo mortal, y con él se
+ * cae el vault de todos. Ese caso arranca con lo que tenga y aplica el bundle
+ * cuando llega, tarde y por su cuenta.
+ *
+ * Si tu agente no está en el camino por el que viaja el propio vault, no uses
+ * esto: usa `loadEnv` y deja que espere.
  *
  * @returns {{injected:string[], overridden:string[], skipped:string[]}}
  */

package/src/service.js

@@ -26,6 +26,7 @@ import {
 } from '@dotrino/identity/capabilities'
 import { MSG, secretsScope, isValidSecretsNs } from './protocol.js'
 import { makeEphemeralKey, openSealed } from './sealed.js'
+import { parseInvite } from './invite.js'
 
 const IDENTITY_FILE = 'service-identity.json'
 const FRESH_WINDOW_MS = 5 * 60 * 1000
@@ -74,9 +75,36 @@ async function verificarHola (p, sn) {
   if (!(await verifyDeviceSig({ publickey: b.iss, data: b, signature: p.signature }))) {
     throw new Error('la respuesta de la bóveda no está bien firmada')
   }
+  // El modo también viene aquí, y aquí viene FIRMADO por la bóveda. Se comprueba
+  // de nuevo aunque ya se haya mirado el del QR: en la forma corta el QR es un
+  // código que pasó por manos ajenas, y esta es la primera vez que la bóveda
+  // dice de su puño y letra qué se propone hacer.
+  rechazarAdopcion(b.m)
   return b
 }
 
+/**
+ * UN AGENTE NUNCA TRANSFIERE SU IDENTIDAD: el vault propone, el agente acepta.
+ *
+ * El emparejamiento tiene dos modos y los declara la bóveda en la invitación:
+ * `join` (el que se enrola entra a la cuenta de la bóveda) y `adopt` (la bóveda
+ * se queda con la cuenta que trae el aparato). El segundo existe para APARATOS,
+ * que llegan con una cuenta propia y una historia que conservar.
+ *
+ * Un agente no tiene nada de eso: es un servicio, su identidad se la da el vault
+ * y no hay caso en que quiera empujar la suya hacia arriba. Así que este camino
+ * no se negocia, se rechaza — y se rechaza ACÁ, cuando el humano pega la
+ * invitación, en vez de dejar que el viaje termine en un «intent-mismatch» del
+ * otro lado que no le explica nada a nadie.
+ */
+function rechazarAdopcion (modo) {
+  if (modo !== 'adopt') return
+  throw new Error(
+    'esta invitación se abrió para ADOPTAR la cuenta del aparato, y un agente no transfiere su identidad: ' +
+    'la suya se la cede el vault. Abre el emparejamiento sin `--adopt` (`dotrino-vault pair --service <ns>`).'
+  )
+}
+
 /**
  * Canjea la cita del QR y devuelve la instancia a la que apunta.
  *
@@ -153,26 +181,68 @@ function writeServiceIdentity (dir, obj) {
 }
 
 /**
- * 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>`).
+ * 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 {{v:number, iss:string, proxy:string, token:string, sn:string}|string} opts.qr  QR v2 (objeto o JSON string).
+ * @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]
- * @returns {Promise<{device, cert, iss:string}>}
+ * @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, approveTimeoutMs = 180000 } = {}) {
-  if (typeof qr === 'string') { try { qr = JSON.parse(qr) } catch (_) { throw new Error('qr inválido: no es JSON') } }
+export async function enrollService ({ qr, ns, dir, label, onCode, onReplace, 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.
+  if (typeof qr === 'string') {
+    const o = parseInvite(qr)
+    if (!o) throw new Error('eso no parece una invitación del vault (pega la salida de `dotrino-vault pair --service <ns>`)')
+    qr = o
+  }
   if (!qr?.sn || !(qr.iss || qr.conn)) throw new Error('qr inválido: falta la bóveda o el nonce')
+  rechazarAdopcion(qr.m)
   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
 
+  // 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 anterior = readServiceIdentity(dir)
+  let replaced = null
+  if (anterior?.device?.publickey) {
+    replaced = {
+      ns: anterior.ns,
+      enrolledAt: anterior.enrolledAt,
+      deviceId: (await pubkeyId(anterior.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) {
@@ -201,7 +271,11 @@ export async function enrollService ({ qr, ns, dir, label, onCode, approveTimeou
     // 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 })
-    const data = { op: 'enroll', dpub: device.publickey, token: qr.token || qr.sn, sn: qr.sn, commit, label, ts: Date.now() }
+    // `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 { signature } = await signWithDevice({ privateJwk: device.privateJwk, data })
 
     const enrolled = new Promise((resolve, reject) => {
@@ -225,8 +299,10 @@ export async function enrollService ({ qr, ns, dir, label, onCode, approveTimeou
     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')
 
+    // 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 }
+    return { device, cert: res.cert, iss: qr.iss, replaced }
   } finally { client.close() }
 }