@dotrino/vaultd 0.11.0 → 0.13.0

package/lib/src/env.js

@@ -21,7 +21,7 @@
 import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
-import { fetchSecrets, waitForSecrets, readServiceIdentity } from './service.js'
+import { fetchSecrets, waitForSecrets, readServiceIdentity, watchSecretsChanges } from './service.js'
 import { isValidSecretsNs } from './protocol.js'
 
 /** Raíz donde viven las identidades de servicio de esta máquina/usuario. */
@@ -61,19 +61,42 @@ export function resolveNs (ns) {
   throw new Error(`hay varios servicios enrolados (${found.join(', ')}): elige uno con DOTRINO_NS=<ns> o loadEnv({ ns })`)
 }
 
+/**
+ * EL VAULT MANDA: sus valores PISAN los del `.env` y los del entorno.
+ *
+ * No es el default de `dotenv` y es a propósito. El vault no viene a reemplazar
+ * al `.env` —que sigue ahí y sigue siendo el arranque de cualquier máquina sin
+ * enrolar—, viene a ser la ÚLTIMA palabra sobre las claves que administra. Esa
+ * es justamente la pieza que hace barata la rotación: se cambia el valor en un
+ * solo lugar y ningún `.env` viejo, olvidado en un VPS, puede seguir ganando.
+ * Con la precedencia al revés, rotar exigía además ir a limpiar cada copia
+ * rancia —que es exactamente el trabajo que se quería evitar—, y peor: el
+ * servicio arrancaba con la llave vieja SIN decir nada.
+ *
+ * Escotilla para depurar: `DOTRINO_ENV_OVERRIDE=0` devuelve la precedencia
+ * clásica (gana lo que ya está en el entorno) para una corrida suelta, sin
+ * tocar el vault ni el código.
+ */
+function overrideByDefault () {
+  return process.env.DOTRINO_ENV_OVERRIDE !== '0'
+}
+
 /**
  * Trae los secretos del ns desde el vault y los pone en `process.env`.
  *
  * @param {Object} [opts]
  * @param {string} [opts.ns]         Namespace (por defecto: `DOTRINO_NS` o el único enrolado).
  * @param {string} [opts.dir]        Dónde está `service-identity.json` (por defecto: `serviceDir(ns)`).
- * @param {boolean} [opts.override]  `true` = pisa variables ya presentes en el entorno (default: no).
+ * @param {boolean} [opts.override]  El vault pisa lo que ya esté en el entorno (default: SÍ, ver arriba).
  * @param {boolean} [opts.wait]      `true` (default) = si el vault no está, ESPERA (reintenta) en vez de fallar.
  * @param {string[]} [opts.required] Claves que deben venir; si falta alguna, lanza.
  * @param {(e:Error, ms:number)=>void} [opts.onRetry]
- * @returns {Promise<{ns:string, secrets:Record<string,string>, injected:string[], skipped:string[]}>}
+ * @returns {Promise<{ns, secrets, injected:string[], overridden:string[], skipped:string[]}>}
+ *   `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 = false, wait = true, required = [], onRetry } = {}) {
+export async function loadEnv ({ ns, dir, override, wait = true, required = [], onRetry } = {}) {
+  if (override === undefined) override = overrideByDefault()
   ns = resolveNs(ns)
   dir = dir || serviceDir(ns)
   const load = wait ? waitForSecrets : fetchSecrets
@@ -84,12 +107,100 @@ export async function loadEnv ({ ns, dir, override = false, wait = true, require
     throw new Error(`faltan secretos en el ns "${ns}": ${missing.join(', ')} (agrégalos con \`dotrino-vault secret set ${ns} <CLAVE> <valor>\`)`)
   }
 
+  return { ns, secrets, ...applyEnv(secrets, override) }
+}
+
+/**
+ * Vuelca un bundle de secretos en `process.env` y cuenta qué cambió.
+ *
+ * ⚠ 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[]}}
+ */
+export function applyEnv (secrets, override = overrideByDefault()) {
   const injected = []
+  const overridden = []
   const skipped = []
-  for (const [k, v] of Object.entries(secrets)) {
-    if (!override && k in process.env) { skipped.push(k); continue }
-    process.env[k] = String(v)
+  for (const [k, v] of Object.entries(secrets || {})) {
+    const previo = process.env[k]
+    const tenia = k in process.env
+    if (!override && tenia) { skipped.push(k); continue }
+    const valor = String(v)
+    process.env[k] = valor
     injected.push(k)
+    if (tenia && previo !== valor) overridden.push(k)
   }
-  return { ns, secrets, injected, skipped }
+  return { injected, overridden, skipped }
+}
+
+/**
+ * Queda a la escucha de la bóveda y, cuando avisa que la configuración cambió,
+ * TERMINA EL PROCESO para que el supervisor lo levante con todo fresco.
+ *
+ * Por qué salir en vez de recargar en caliente:
+ *
+ * 1. **Borra de memoria el valor viejo.** Es la razón de peso. En JavaScript un
+ *    secreto no se puede borrar: los strings son inmutables, no hay `zeroize`, y
+ *    el valor sigue en el heap hasta que al recolector le apetezca — más lo que
+ *    capturó cada closure y cada caché derivada. Y una llave se rota casi siempre
+ *    PORQUE SE FILTRÓ, así que dejarla viva en el proceso anula el motivo de
+ *    rotarla. Un proceso nuevo empieza con el heap limpio.
+ * 2. **Lee todo fresco.** Recargar en caliente exige que cada sitio que leyó una
+ *    variable sepa releerla; esa lista hay que mantenerla para siempre y cuando se
+ *    queda corta falla en silencio.
+ * 3. **Sirve de interruptor de emergencia.** Revocar el cert de un agente ya no
+ *    espera a que alguien se acuerde de reiniciarlo: se apaga, y al arrancar
+ *    `fetchSecrets` recibe «no autorizado: revoked» y no vuelve.
+ *
+ * NO se reinicia solo: sale, y lo levanta quien lo supervisa (pm2, systemd con
+ * `Restart=always`). Un proceso no puede reiniciarse a sí mismo de forma fiable, y
+ * el supervisor ya trae backoff y tope de intentos, que es justo lo que evita que
+ * una configuración rota se convierta en un ciclo.
+ *
+ * @param {Object} [opts]
+ * @param {string} [opts.ns]
+ * @param {string} [opts.dir]
+ * @param {(info:{ns:string, ts:number, motivo:'cambio'|'revocado'})=>void} [opts.onUpdate]
+ *   Reemplaza la salida por defecto. Úsalo cuando terminar el proceso no sea una
+ *   opción — el caso del proxio, cuyo reinicio corta el transporte de todos.
+ * @param {number} [opts.exitCode=0]  Salida LIMPIA: systemd con `Restart=on-failure`
+ *   no levantaría un servicio que sale con 0, pero `Restart=always` sí, y pm2
+ *   también. Se elige 0 porque salir a propósito no es un fallo.
+ * @returns {Promise<{stop:()=>void}>}
+ */
+export async function watchEnv ({ ns, dir, onUpdate, exitCode = 0, quiet = false, ...resto } = {}) {
+  ns = resolveNs(ns)
+  dir = dir || serviceDir(ns)
+  const decir = (m) => { if (!quiet) console.error(m) }
+
+  const salir = (motivo) => {
+    decir(`[dotrino-env] ${motivo === 'revocado'
+      ? 'la bóveda REVOCÓ este agente: terminando (no volverá a arrancar)'
+      : 'configuración nueva en la bóveda: terminando para que el supervisor lo levante limpio'}`)
+    process.exit(motivo === 'revocado' ? 1 : exitCode)
+  }
+
+  return watchSecretsChanges({
+    dir,
+    ns,
+    log: decir,
+    onChange: ({ ts }) => (onUpdate ? onUpdate({ ns, ts, motivo: 'cambio' }) : salir('cambio')),
+    // Un cert revocado sale con código de FALLO a propósito: si el supervisor lo
+    // levanta, va a morir otra vez al no poder leer sus secretos, y el contador de
+    // reinicios fallidos es lo que hace que se note en vez de girar en silencio.
+    onRevoked: () => (onUpdate ? onUpdate({ ns, ts: Date.now(), motivo: 'revocado' }) : salir('revocado')),
+    ...resto
+  })
 }

package/lib/src/index.js

@@ -27,16 +27,13 @@
  */
 import { verifyChain } from '@dotrino/identity/capabilities'
 import { createEnrollDesk, deviceIdOf, DEVICE_TTL_MS, FRESH_WINDOW_MS } from './enroll.js'
+// Las constantes del protocolo salen del MISMO módulo que usa el daemon: si la lista
+// local se queda corta, el dispositivo deja de atender mensajes sin que nadie lo note.
+import { MSG, SCOPE } from './protocol.js'
 
-const SIGN_SCOPE = 'vault:sign'
+const SIGN_SCOPE = SCOPE.SIGN
 const SELFCERT_TTL_MS = 24 * 60 * 60 * 1000    // el self-cert P←P se regenera cada 24 h
-
-const MSG = {
-  ENROLL: 'vault.enroll',
-  DEVICES: 'vault.devices',
-  DEVICES_RESULT: 'vault.devices.result',
-  ERROR: 'vault.error'
-}
+const RENEW_TTL_MS = DEVICE_TTL_MS             // la renovación extiende la misma ventana (30 días)
 
 /** deviceId legible (p. ej. `C440-AC0E`) desde una pubkey JWK. */
 export { deviceIdOf }
@@ -49,10 +46,11 @@ export { deviceIdOf }
  *   `me.publickey`, `signData`, `signDelegation`, `listDelegations`, `revokeDelegation`.
  * @param {object} [opts]
  * @param {string} [opts.proxyUrl='wss://proxy.dotrino.com']
- * @returns {Promise<object>} handle: { iss, proxy, client, startPairing, approve, reject,
- *   listPending, listMachines, revoke, getSelfCert, onPendingChange, close }
+ * @returns {Promise<object>} handle: { iss, proxy, client, startPairing, stopPairing,
+ *   approve, reject, listPending, listMachines, revoke, getSelfCert, onPendingChange,
+ *   onAdopted, close }
  */
-export async function startDeviceVault (identity, { proxyUrl } = {}) {
+export async function startDeviceVault (identity, { proxyUrl, client: injectedClient } = {}) {
   const iss = identity.me?.publickey
   if (!iss) throw new Error('sin identidad: crea/desbloquea tu identidad antes de usar el dispositivo como bóveda')
   const proxy = proxyUrl || 'wss://proxy.dotrino.com'
@@ -67,12 +65,17 @@ export async function startDeviceVault (identity, { proxyUrl } = {}) {
     return cert
   }
 
-  const { WebSocketProxyClient } = await import('@dotrino/proxy-client')
-  const client = new WebSocketProxyClient({
-    url: proxy, enableWebRTC: false, autoReconnect: true,
-    maxReconnectAttempts: 100000, reconnectDelay: 4000
-  })
-  await client.connect()
+  // `client` inyectado: solo para las pruebas (transporte de mentira). En producción se
+  // levanta el del ecosistema — no hay otro transporte.
+  const client = injectedClient || await (async () => {
+    const { WebSocketProxyClient } = await import('@dotrino/proxy-client')
+    const c = new WebSocketProxyClient({
+      url: proxy, enableWebRTC: false, autoReconnect: true,
+      maxReconnectAttempts: 100000, reconnectDelay: 4000
+    })
+    await c.connect()
+    return c
+  })()
 
   const selfCert = await getSelfCert()
   const identify = async () => {
@@ -87,6 +90,7 @@ export async function startDeviceVault (identity, { proxyUrl } = {}) {
   const send = (to, obj) => { try { client.send(to, obj) } catch (_) {} }
 
   let _onPendingChange = () => {}
+  let _onAdopted = () => {}
 
   // ENROLL / aprobación / revocación: núcleo COMPARTIDO con el daemon del PC y con la
   // copia vendorizada del iframe (`lib/src/enroll.js`). Un solo sitio donde vive el
@@ -99,9 +103,49 @@ export async function startDeviceVault (identity, { proxyUrl } = {}) {
     sendByPubkey: (pub, obj) => { try { client.sendByPubkey(pub, obj) } catch (_) {} },
     defaultScope: [SIGN_SCOPE],
     defaultTtlMs: DEVICE_TTL_MS,
+    // Camino A (la cuenta del aparato pasa a vivir aquí): sin la llave de cifrado, esta
+    // bóveda entraría mandando una cuenta cuyo contenido no puede abrir.
+    encPub: identity.me?.encryptionPubkey || null,
+    vaultLabel: 'bóveda',
+    // Cita del proxio para la invitación corta (QR). Si el proxio es viejo y no las
+    // conoce, el desk se cae solo a la invitación larga.
+    connToken: async () => {
+      try { return (await client.requestPairingCode())?.code || null }
+      catch (_) { return null }
+    },
+    onAdopted: (info) => { try { _onAdopted(info) } catch (_) {} },
     onPendingChange: () => _onPendingChange()
   })
 
+  /** Nonces revocados, para que un cert revocado no pase ningún `verifyChain`. */
+  async function revocationSet () {
+    const { revoked } = await identity.listDelegations()
+    return new Set((revoked || []).map((r) => r.nonce || r))
+  }
+
+  /**
+   * RENOVACIÓN automática (igual que `dotrino-vault#handleRenew`): un dispositivo con
+   * cert VIGENTE y no revocado pide uno fresco —misma sub-clave y scope— sin QR ni
+   * aprobación: sigue siendo el mismo dispositivo, solo extiende la ventana. Un cert
+   * vencido o revocado NO se renueva (ahí toca re-emparejar con aprobación).
+   *
+   * Sin esto, toda máquina enrolada contra un dispositivo-bóveda caduca a los 30 días.
+   */
+  async function handleRenew (from, p) {
+    const d = p?.data
+    if (!d || !p.signature || !p.cert) return send(from, { type: MSG.ERROR, error: 'petición inválida' })
+    if (typeof d.ts !== 'number' || Math.abs(Date.now() - d.ts) > FRESH_WINDOW_MS) {
+      return send(from, { type: MSG.ERROR, error: 'stale request: ts outside the ±5 min window (possible replay, or the device clock is off)' })
+    }
+    const chk = await verifyChain({ data: d, signature: p.signature, cert: p.cert, trustedIssuer: iss, revoked: await revocationSet() })
+    if (!chk.ok) return send(from, { type: MSG.ERROR, error: 'unauthorized: ' + chk.reason })
+    // Reusar el label del cert original (si sigue registrado en delegations).
+    const { issued } = await identity.listDelegations()
+    const prev = (issued || []).find((x) => x.nonce === p.cert.nonce)
+    const { cert } = await identity.signDelegation(p.cert.sub, p.cert.scope, { ttlMs: RENEW_TTL_MS, label: prev?.label || '' })
+    send(from, { type: MSG.RENEWED, cert })
+  }
+
   // Consulta de revocaciones (igual que `vault.devices` del daemon): responde la lista
   // 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.
@@ -124,7 +168,12 @@ export async function startDeviceVault (identity, { proxyUrl } = {}) {
 
   client.on('message', (_from, p) => {
     if (!p || typeof p !== 'object') return
-    if (p.type === MSG.ENROLL) desk.handleEnroll(_from, p).catch(() => {})
+    // El QR corto no lleva la llave: el aparato la pide con un HELLO presentando el `sn`.
+    if (p.type === MSG.HELLO) Promise.resolve(desk.handleHello(_from, p)).catch(() => {})
+    else if (p.type === MSG.ENROLL) desk.handleEnroll(_from, p).catch(() => {})
+    // Camino A: el aparato devuelve su acta sellada admitiendo a esta bóveda.
+    else if (p.type === MSG.ACTA_SEALED) Promise.resolve(desk.handleActaSealed(_from, p)).catch(() => {})
+    else if (p.type === MSG.RENEW) handleRenew(_from, p).catch(() => {})
     else if (p.type === MSG.DEVICES) handleDevices(_from, p).catch(() => {})
   })
 
@@ -148,6 +197,7 @@ export async function startDeviceVault (identity, { proxyUrl } = {}) {
   return {
     iss, proxy, client,
     startPairing: desk.startPairing,
+    stopPairing: desk.stopPairing,
     // Aprueba TIPEANDO el código que muestra la máquina: el núcleo compartido recompone
     // el compromiso `SHA-256(code‖dpub‖sn)` y solo firma el cert si coincide.
     approve: (deviceId, code) => desk.approve(code, { deviceId }),
@@ -159,6 +209,8 @@ export async function startDeviceVault (identity, { proxyUrl } = {}) {
     revoke: (nonce) => desk.revoke(nonce),
     getSelfCert,
     onPendingChange (fn) { _onPendingChange = fn || (() => {}) },
+    /** Camino A: la cuenta del aparato quedó adoptada por esta bóveda. */
+    onAdopted (fn) { _onAdopted = fn || (() => {}) },
     close () { try { client.close() } catch (_) {} }
   }
 }

package/lib/src/invite.js

@@ -56,9 +56,12 @@ export const FMT_COMPACT = 'c'
  * que es lo único que de verdad decide. Esconderla no aportaba nada —una pública es
  * pública— y ocupaba 44 de los ~100 caracteres.
  *
- * `token` aquí NO es el de la sesión de emparejamiento: es el **token de conexión**
- * que el proxy le da a la bóveda (4 caracteres), o sea su dirección. Con eso el
- * aparato le habla directo, punto a punto, sin resolver nada.
+ * Lo que lleva NO es la dirección de la bóveda: es una **cita del proxy** —un código
+ * de 6 caracteres, de un solo uso y con minutos de vida, cuyos 2 primeros dicen qué
+ * proxio la emitió—. El aparato la CANJEA (`redeemPairingCode`) y obtiene la dirección
+ * real de la conexión, que hoy son 24 caracteres para poder rutearse entre proxios y no
+ * cabría cómoda en un QR. Además, una cita caduca y se quema: no deja una dirección
+ * permanente impresa en algo que circula.
  */
 export const FMT_SHORT = 't'
 
@@ -293,7 +296,10 @@ function compactDecode (text) {
  * Le pasa a cualquiera con proxy propio (y lo cazó el E2E de secretos, que levanta
  * uno local).
  */
-const CONN_TOKEN_LEN = 4
+// La CITA del proxio: 2 caracteres de prefijo de nodo + 4 = 6. Antes eran 4 (la
+// dirección de la conexión). Cambió porque la dirección pasó a ser una instancia
+// de 24 caracteres, y lo que se imprime en un QR ahora es una cita de un solo uso.
+const CONN_TOKEN_LEN = 6
 
 function shortEncode (qr) {
   if (!qr || qr.v !== 2) return null

package/lib/src/protocol.js

@@ -45,6 +45,30 @@ export const MSG = Object.freeze({
   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)
+  // AVISO DE CAMBIO (no lleva valores): la bóveda dice «la configuración del ns
+  // cambió». El agente no la recarga en caliente — SALE limpio y su supervisor lo
+  // levanta. Dos razones, y la segunda es la de peso:
+  //   · Lee todo fresco. Recargar en caliente exige que cada sitio que leyó una
+  //     variable sepa releerla, y esa lista hay que mantenerla para siempre.
+  //   · BORRA DE MEMORIA EL VALOR VIEJO. En JavaScript un secreto no se puede
+  //     borrar: los strings son inmutables, no hay zeroize, y el valor queda en el
+  //     heap hasta que al recolector le apetezca — más lo que capturó cada closure
+  //     y cada caché derivada. Una llave se rota casi siempre PORQUE SE FILTRÓ, así
+  //     que dejarla viva en el proceso anula la razón de rotarla. Un proceso nuevo
+  //     empieza con el heap limpio.
+  // Va FIRMADO por la maestra y el agente lo verifica contra su `iss` pineada: un
+  // aviso de reinicio sin autenticar ES un ataque de denegación.
+  SECRETS_CHANGED: 'vault.secrets.changed',   // vault → servicio: { body:{op,ns,ts}, signature }
+  // --- CONSOLA REMOTA (docs/consola-remota.md) — requiere cert `vault:admin` ---
+  // Un solo mensaje con `data.op`: pending · pair · approve · reject · revoke · audit.
+  // Admitir y expulsar, nada más: cambiar permisos, traspasar el mando y los secretos
+  // NO se exponen aquí, y no es un olvido — es el límite (§2 del diseño).
+  ADMIN: 'vault.admin',                       // admin → vault: { data:{op,…,ts,nonce}, signature, cert }
+  ADMIN_RESULT: 'vault.admin.result',         // vault → admin: { op, result }
+  // Aviso a TODOS los miembros de que el perfil cambió (alguien entró o salió). Es la
+  // contrapartida de administrar a distancia: sin esto, un enrolamiento remoto sería
+  // invisible para el resto de tus dispositivos.
+  ADMIN_EVENT: 'vault.admin.event',           // vault → todos: { body:{ev,deviceId,by,ts}, signature }
   ERROR: 'vault.error'                        // vault → dispositivo: { error }
 })
 
@@ -52,7 +76,11 @@ export const MSG = Object.freeze({
 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
+  STORE: 'vault:store', // leer/escribir el store de hilos + aperturas del usuario
+  // 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'
 })
 
 /**

package/lib/src/sealed.js

@@ -76,7 +76,7 @@ export async function seal ({ ek, payload }) {
  */
 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')
+    throw new Error('invalid sealed envelope')
   }
   const key = await deriveAesKey(privateKey, enc.epk)
   const pt = await subtle.decrypt({ name: 'AES-GCM', iv: fromB64(enc.iv) }, key, fromB64(enc.ct))