@dotrino/vault 0.12.0 → 0.14.0

package/README.md

@@ -97,12 +97,38 @@ Para procesos que no son Node, el CLI los inyecta en el entorno de un hijo:
 dotrino-env run --ns miapp -- ./mi-binario
 ```
 
+### Precedencia: el vault MANDA
+
+Los valores del vault **pisan** los del `.env` y los del entorno. El vault no
+reemplaza al `.env` —que sigue siendo lo que arranca una máquina sin enrolar— pero
+sí tiene la última palabra sobre las claves que administra.
+
+Esa es la pieza que hace barata la **rotación**: cambias el valor en un solo lugar y
+ningún `.env` viejo olvidado en un VPS puede seguir ganando. Con la precedencia al
+revés (como estaba hasta la 0.14.0) rotar exigía además ir a limpiar cada copia
+rancia —el trabajo que se quería evitar— y, peor, el servicio arrancaba con la llave
+vieja **sin decir nada**.
+
+Lo que sí se dice en voz alta: al arrancar se listan las claves que el vault tuvo que
+pisar. Es la señal de que en esa máquina quedó un `.env` por limpiar.
+
+```bash
+DOTRINO_ENV_OVERRIDE=0 node server.js   # escotilla: por esta corrida, gana el entorno
+dotrino-env check                        # dice qué claves pisaría en esta máquina
+```
+
 ### API `@dotrino/vault/env`
 
-- `loadEnv({ ns?, dir?, override?, wait?, required?, onRetry? }) → { ns, secrets, injected, skipped }`
-  (por defecto **no pisa** variables ya presentes en el entorno; `override: true` sí)
+- `loadEnv({ ns?, dir?, override?, wait?, required?, onRetry? }) → { ns, secrets, injected, overridden, skipped }`
+  (por defecto **pisa** lo que ya esté en el entorno; `override: false` invierte la regla).
+  `overridden` son las claves que tenían otro valor y el vault reemplazó.
+- `applyEnv(secrets, override?) → { injected, overridden, skipped }` — vuelca un bundle
+  ya obtenido, sin pedirlo. Para servicios que **no pueden bloquear su arranque**
+  esperando al vault y lo aplican cuando llega (el caso del proxy: el vault le habla
+  *por* el proxy, así que esperarlo sería un abrazo mortal).
 - `serviceDir(ns)`, `serviceRoot()`, `listEnrolled()`, `resolveNs(ns?)`
-- Entorno: `DOTRINO_NS` · `DOTRINO_ENV_DIR` · `DOTRINO_ENV_HOME` · `DOTRINO_ENV_QUIET`
+- Entorno: `DOTRINO_NS` · `DOTRINO_ENV_DIR` · `DOTRINO_ENV_HOME` · `DOTRINO_ENV_QUIET` ·
+  `DOTRINO_ENV_OVERRIDE`
 - CLI: `dotrino-env enroll|status|check|run`  (`check` lista **nombres** de secretos, nunca valores)
 
 Bajo el capó es `@dotrino/vault/service` (`enrollService` / `waitForSecrets`): petición

package/bin/dotrino-env.js

@@ -16,8 +16,13 @@ import fs from 'node:fs'
 import path from 'node:path'
 import readline from 'node:readline/promises'
 import { spawn } from 'node:child_process'
-import { enrollService, readServiceIdentity } from '../src/service.js'
+import { enrollService, readServiceIdentity, fetchSecrets } from '../src/service.js'
 import { loadEnv, serviceDir, serviceRoot, listEnrolled, resolveNs } from '../src/env.js'
+// Se usaba sin importarlo: `enroll` —el comando principal— moría con
+// «sharedParseInvite is not defined» en cuanto tocaba una invitación. Nunca
+// llegó a funcionar, y por eso el único servicio enrolado del ecosistema (el
+// proxy) lo hizo con su propio `enroll-vault.js` en vez de con esta CLI.
+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 }
@@ -40,7 +45,11 @@ En tu código:
   import '@dotrino/vault/config'                       // ns por DOTRINO_NS
   import { loadEnv } from '@dotrino/vault/env'; await loadEnv({ ns: '<ns>' })
 
-Entorno: DOTRINO_NS · DOTRINO_ENV_DIR · DOTRINO_ENV_HOME · DOTRINO_ENV_QUIET`)
+El vault MANDA: sus valores pisan los del .env y los del entorno. Para una
+corrida suelta sin que pise nada:  DOTRINO_ENV_OVERRIDE=0
+
+Entorno: DOTRINO_NS · DOTRINO_ENV_DIR · DOTRINO_ENV_HOME · DOTRINO_ENV_QUIET
+         DOTRINO_ENV_OVERRIDE`)
 }
 
 /**
@@ -106,17 +115,27 @@ function cmdStatus () {
 
 async function cmdCheck () {
   const ns = resolveNs(flag('ns'))
-  const { secrets } = await loadEnv({ ns, wait: false })
+  // `fetchSecrets` y no `loadEnv`: listar NO debe tener efectos secundarios. Con
+  // `loadEnv` esto inyectaría el bundle en el entorno del propio `check`, que es
+  // justo lo que un comando de diagnóstico no tiene por qué hacer.
+  const secrets = await fetchSecrets({ dir: serviceDir(ns), ns })
   const keys = Object.keys(secrets)
   console.log('ns "%s": %d secreto(s)%s', ns, keys.length, keys.length ? ':' : '')
   for (const k of keys) console.log('  ' + k)   // NUNCA los valores
+  // Delata el `.env` rancio: qué claves de esta máquina el vault pisaría.
+  const chocan = keys.filter((k) => k in process.env && process.env[k] !== String(secrets[k]))
+  if (chocan.length) {
+    console.log('\nEl vault PISA estos valores del entorno de esta máquina:\n  %s', chocan.join(', '))
+  }
 }
 
 async function cmdRun () {
   const sep = argv.indexOf('--')
   const cmd = sep >= 0 ? argv.slice(sep + 1) : []
   if (!cmd.length) { console.error('uso: dotrino-env run [--ns <ns>] -- <cmd> [args…]'); process.exit(2) }
-  await loadEnv({ ns: flag('ns') })
+  const { injected, overridden } = await loadEnv({ ns: flag('ns') })
+  console.error('[dotrino-env] %d valor(es) en el entorno de %s%s', injected.length, cmd[0],
+    overridden.length ? ` (pisados: ${overridden.join(', ')})` : '')
   const child = spawn(cmd[0], cmd.slice(1), { stdio: 'inherit', env: process.env })
   child.on('exit', (code, signal) => process.exit(signal ? 1 : (code ?? 0)))
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotrino/vault",
-  "version": "0.12.0",
+  "version": "0.14.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",
@@ -43,7 +43,7 @@
   ],
   "peerDependencies": {
     "@dotrino/identity": ">=0.30.0",
-    "@dotrino/proxy-client": ">=0.6.0"
+    "@dotrino/proxy-client": ">=0.9.0"
   },
   "license": "MIT",
   "repository": {

package/src/config.js

@@ -8,19 +8,31 @@
  * secretos viejos ni vacíos. Un fallo NO transitorio (sin enrolar, cert revocado,
  * scope equivocado) sí aborta el proceso.
  *
+ * EL VAULT MANDA: lo que venga de aquí PISA lo que ya hubiera en el entorno
+ * (incluido un `.env` cargado antes). Ver `env.js` para el porqué.
+ *
  * Config por entorno:
- *   DOTRINO_NS         namespace de secretos (si no, el único enrolado en la máquina)
- *   DOTRINO_ENV_DIR    directorio de la identidad del servicio (si no, ~/.dotrino/service/<ns>)
- *   DOTRINO_ENV_QUIET  '1' para no imprimir la línea de arranque
+ *   DOTRINO_NS            namespace de secretos (si no, el único enrolado en la máquina)
+ *   DOTRINO_ENV_DIR       directorio de la identidad del servicio (si no, ~/.dotrino/service/<ns>)
+ *   DOTRINO_ENV_QUIET     '1' para no imprimir la línea de arranque
+ *   DOTRINO_ENV_OVERRIDE  '0' para NO pisar el entorno en esta corrida (depuración)
  */
 import { loadEnv } from './env.js'
 
 const quiet = process.env.DOTRINO_ENV_QUIET === '1'
 
-const { ns, injected } = await loadEnv({
+const { ns, injected, overridden } = await loadEnv({
   onRetry: (e, ms) => {
     if (!quiet) console.error('[dotrino-env] vault no disponible (%s); reintentando en %ds…', e.message, Math.round(ms / 1000))
   }
 })
 
-if (!quiet) console.error('[dotrino-env] %d secreto(s) del ns "%s" cargados en process.env', injected.length, ns)
+if (!quiet) {
+  console.error('[dotrino-env] %d valor(es) del ns "%s" cargados en process.env', injected.length, ns)
+  // Se dice en voz alta: que el vault haya tenido que pisar algo significa que
+  // en esta máquina hay un `.env` con valores viejos. Ganó el vault, pero el
+  // operador quiere enterarse — es la señal de que quedó basura por limpiar.
+  if (overridden.length) {
+    console.error('[dotrino-env] pisaron un valor previo del entorno: %s', overridden.join(', '))
+  }
+}

package/src/enroll.js

@@ -146,14 +146,20 @@ export function createEnrollDesk ({
    *                       aviso. Es ORIENTATIVO (un nombre que puso su dueño); la
    *                       identidad de verdad de la cuenta es `iss`.
    */
-  function startPairing ({ scope = defaultScope, ttlMs = defaultTtlMs, label = '', mode = 'join', account = '' } = {}) {
+  async function startPairing ({ scope = defaultScope, ttlMs = defaultTtlMs, label = '', mode = 'join', account = '' } = {}) {
     pending.clear() // uno a la vez: una sesión nueva supersede a la anterior
     const acct = String(account || '').slice(0, 40)
-    // INVITACIÓN CORTA: si sabemos nuestra dirección en el proxy, el QR lleva solo
-    // eso y el nonce de la sesión (13 bytes). La llave, el proxy y el nombre de la
-    // cuenta los pide el aparato por la red presentando el `sn`. El nonce hace de
-    // identificador de sesión: no hace falta un token de emparejamiento aparte.
-    const conn = typeof connToken === 'function' ? connToken() : connToken
+    // INVITACIÓN CORTA: si sabemos cómo alcanzarnos, el QR lleva solo eso y el
+    // nonce de la sesión. La llave, el proxy y el nombre de la cuenta los pide el
+    // aparato por la red presentando el `sn`. El nonce hace de identificador de
+    // sesión: no hace falta un token de emparejamiento aparte.
+    //
+    // `conn` es una CITA del proxio (6 caracteres, un solo uso, caduca en
+    // minutos), no la dirección de la conexión: esa pasó a ser una instancia de
+    // 24 caracteres, que ni entra cómoda en un QR ni tiene por qué quedar impresa
+    // en algo que circula. Por eso se pide una nueva por emparejamiento, y por
+    // eso esto es asíncrono.
+    const conn = typeof connToken === 'function' ? await connToken() : connToken
     if (conn) {
       const sn = randToken(8)
       pending.set(sn, { token: sn, exp: Date.now() + PAIRING_TTL_MS, scope, ttlMs, label, sn, mode, account: acct, state: 'AWAITING_ENROLL' })

package/src/env.js

@@ -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,31 @@ 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ó.
+ *
+ * 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.
+ *
+ * @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 }
 }

package/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/src/service.js

@@ -77,6 +77,25 @@ async function verificarHola (p, sn) {
   return b
 }
 
+/**
+ * Canjea la cita del QR y devuelve la instancia a la que apunta.
+ *
+ * Una cita se quema al usarse y caduca en minutos, así que un error acá casi
+ * siempre significa lo mismo para quien lo lee: el código ya se usó o venció, y
+ * hay que pedir otro en la bóveda. Se dice así, no con el error crudo.
+ */
+async function resolverCita (client, code) {
+  if (!code) throw new Error('la invitación no trae código de emparejamiento')
+  if (typeof client.redeemPairingCode !== 'function') {
+    throw new Error('el proxio no soporta códigos de emparejamiento (actualizá @dotrino/proxy-client)')
+  }
+  const r = await client.redeemPairingCode(code)
+  if (!r?.ok || !r.instance) {
+    throw new Error(`ese código no sirve: ${r?.error || 'no válido'}. Pedí uno nuevo en la bóveda.`)
+  }
+  return r.instance
+}
+
 async function freshClient (proxyUrl, connectTimeoutMs = 20000) {
   installNodeGlobals()
   const { WebSocketProxyClient } = await import('@dotrino/proxy-client')
@@ -157,6 +176,11 @@ export async function enrollService ({ qr, ns, dir, label, onCode, approveTimeou
   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 destino = await resolverCita(client, qr.conn)
     const hola = await new Promise((resolve, reject) => {
       const off = client.on('message', (_f, p) => {
         if (p?.type === MSG.HELLO_OK) { fin(); verificarHola(p, qr.sn).then(resolve, reject) }
@@ -164,7 +188,7 @@ export async function enrollService ({ qr, ns, dir, label, onCode, approveTimeou
       })
       const t = setTimeout(() => { fin(); reject(new Error('la bóveda no contestó: ese código pudo caducar')) }, 15000)
       const fin = () => { off(); clearTimeout(t) }
-      try { client.send(qr.conn, { type: MSG.HELLO, sn: qr.sn }) } catch (e) { fin(); reject(e) }
+      try { client.send(destino, { type: MSG.HELLO, sn: qr.sn }) } catch (e) { fin(); reject(e) }
     })
     qr = { ...qr, iss: hola.iss, proxy: hola.proxy || qr.proxy }
   }