@dotrino/vault 0.13.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.13.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",

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/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 }
 }