@dotrino/vault 0.2.0 → 0.3.0

package/README.md

@@ -37,6 +37,79 @@ const machines = await vault.listMachines()   // [{ sub, deviceId, label, exp, n
 vault.close()
 ```
 
+## Credenciales del vault en vez del `.env` (Node)
+
+La cara "dotenv" del paquete: **cualquier proyecto Node** jala sus credenciales del
+vault del dueño y las deja en `process.env`. En el disco del servicio **no queda
+ningún secreto**: solo la llave del dispositivo (generada ahí, nunca sale) y un
+certificado con scope `vault:secrets:<ns>`. Los valores viven **solo en memoria**;
+si la máquina se compromete, revocas el cert y no había nada que robar.
+
+### 1) Registro del cliente (una sola vez)
+
+```bash
+# en el VAULT (tu PC): abres el emparejamiento del servicio y cargas sus secretos
+dotrino-vault pair --service miapp          # invitación con scope SOLO vault:secrets:miapp
+dotrino-vault secret set miapp API_KEY  sk-…
+
+# en el PROYECTO/servidor: enrola esta máquina (pega la invitación)
+npx dotrino-env enroll --ns miapp
+#   → muestra un código:  dotrino-vault approve 7K3F-92Q1
+
+# de vuelta en el VAULT: lo tipeas leyéndolo de esa pantalla
+dotrino-vault approve 7K3F-92Q1
+```
+
+El código lo **genera el servicio** y **no viaja** por la red: el vault solo puede
+echarlo de vuelta si un humano lo tipeó. Así, un vault falso no puede enrolarte y
+aprobar a ciegas no enrola a nadie. Queda `~/.dotrino/service/<ns>/service-identity.json`
+(0600) con `{ device, cert, iss, proxy, ns }`.
+
+Es un **comando previo**, no el primer arranque de la app: el enrolamiento necesita a
+un humano leyendo el código en esta pantalla (bajo systemd/PM2 no hay TTY y el código
+acabaría en un log), bloquea esperando la aprobación y **escribe** en disco consumiendo
+una invitación de un solo uso. El arranque, en cambio, solo **lee** la identidad ya
+guardada: es idempotente y no interactúa con nadie. Corre el `enroll` donde corres el
+`npm ci` al aprovisionar la máquina.
+
+### 2) En el código
+
+```js
+import '@dotrino/vault/config'    // como `dotenv/config`, pero contra el vault (ns = DOTRINO_NS)
+console.log(process.env.API_KEY)
+```
+
+o explícito:
+
+```js
+import { loadEnv } from '@dotrino/vault/env'
+const { secrets } = await loadEnv({ ns: 'miapp', required: ['API_KEY'] })
+```
+
+Es **asíncrono a propósito**: el `import` bloquea el arranque (top-level await) hasta
+que los secretos estén. Si el vault no está disponible, **espera** (reintento con
+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.
+
+Para procesos que no son Node, el CLI los inyecta en el entorno de un hijo:
+
+```bash
+dotrino-env run --ns miapp -- ./mi-binario
+```
+
+### 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í)
+- `serviceDir(ns)`, `serviceRoot()`, `listEnrolled()`, `resolveNs(ns?)`
+- Entorno: `DOTRINO_NS` · `DOTRINO_ENV_DIR` · `DOTRINO_ENV_HOME` · `DOTRINO_ENV_QUIET`
+- 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
+firmada por la llave del servicio + cert, respuesta **sellada** (ECDH efímero + AES-GCM,
+el proxy no ve los valores) y **firmada por la maestra**, verificada contra la `iss`
+pineada en el enrolamiento.
+
 ## Modelo de aprobación (seguro por diseño)
 
 - El **dispositivo** que se enrola genera un **código aleatorio** (`makePairingCode`) y

package/bin/dotrino-env.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+/**
+ * dotrino-env — CLI del "dotenv contra el vault".
+ *
+ *   dotrino-env enroll --ns <ns> [--qr <invitación>]   enrola ESTA máquina/servicio (una vez)
+ *   dotrino-env status                                  qué hay enrolado aquí
+ *   dotrino-env check [--ns <ns>]                       pide los secretos y lista sus NOMBRES (nunca valores)
+ *   dotrino-env run [--ns <ns>] -- <cmd> [args…]        corre un comando con los secretos en su entorno
+ *
+ * El enrolamiento es el registro del cliente contra el vault del dueño:
+ *   1. en el vault:   dotrino-vault pair --service <ns>      (invitación con scope SOLO vault:secrets:<ns>)
+ *   2. aquí:          dotrino-env enroll --ns <ns>           (pegas la invitación; se MUESTRA un código)
+ *   3. en el vault:   dotrino-vault approve <código>         (lo tipeas leyéndolo de esta pantalla)
+ */
+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 { loadEnv, serviceDir, serviceRoot, listEnrolled, resolveNs } from '../src/env.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
+
+  enroll --ns <ns> [--qr <invitación>] [--dir <dir>]
+        Registra ESTE servicio contra el vault (una sola vez).
+        Antes, en el vault:  dotrino-vault pair --service <ns>
+        Si no pasas --qr, se pide por consola (también acepta stdin).
+
+  status                 servicios enrolados en esta máquina
+  check [--ns <ns>]      pide los secretos al vault y lista sus NOMBRES (nunca los valores)
+  run [--ns <ns>] -- <cmd> [args…]
+                         ejecuta <cmd> con los secretos inyectados en su entorno
+
+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`)
+}
+
+/**
+ * La invitación que imprime `dotrino-vault pair` viene en tres formas: el JSON
+ * crudo, el base64url del payload, o la URL de profile con `#vault=<b64>`.
+ * Aceptamos las tres para que el operador pegue lo que tenga a mano.
+ */
+function parseInvite (raw) {
+  const s = String(raw || '').trim()
+  if (!s) throw new Error('invitación vacía')
+  if (s.startsWith('{')) return JSON.parse(s)
+  const b64 = s.includes('#vault=') ? s.split('#vault=')[1] : (s.includes('#') ? s.split('#').pop() : s)
+  const json = Buffer.from(b64.replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf8')
+  if (!json.trim().startsWith('{')) throw new Error('no parece una invitación del vault')
+  return JSON.parse(json)
+}
+
+async function readInvite () {
+  if (!process.stdin.isTTY) return fs.readFileSync(0, 'utf8')
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+  const answer = await rl.question('Pega la invitación del vault (salida de `dotrino-vault pair --service <ns>`):\n> ')
+  rl.close()
+  return answer
+}
+
+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)
+  const { cert } = await enrollService({
+    qr,
+    ns,
+    dir,
+    label: flag('label') || 'servicio:' + ns,
+    onCode: ({ deviceId, code }) => {
+      console.log('\n  Dispositivo: %s', deviceId)
+      console.log('  APRUEBA en el vault tipeando este código:\n')
+      console.log('      dotrino-vault approve %s\n', code)
+      console.log('  (el vault NO conoce este código: tiene que leerlo de aquí un humano)')
+    }
+  })
+  console.log('\nListo. Identidad del servicio en: %s', path.join(dir, 'service-identity.json'))
+  console.log('Certificado con scope: %s  (vence %s)', (cert.scope || []).join(', '), new Date(cert.exp).toISOString())
+  console.log('\nEn tu app:  import \'@dotrino/vault/config\'   (con DOTRINO_NS=%s)', ns)
+}
+
+function cmdStatus () {
+  const found = listEnrolled()
+  if (!found.length) {
+    console.log('Ningún servicio enrolado en %s\n  Enrola uno:  dotrino-env enroll --ns <ns>', serviceRoot())
+    return
+  }
+  for (const ns of found) {
+    const id = readServiceIdentity(serviceDir(ns))
+    const exp = id?.cert?.exp
+    console.log('%s\n  dir:   %s\n  vault: %s…\n  scope: %s\n  cert:  vence %s',
+      ns, serviceDir(ns), String(id.iss).slice(0, 24), (id.cert?.scope || []).join(', '),
+      exp ? new Date(exp).toISOString() : '?')
+  }
+}
+
+async function cmdCheck () {
+  const ns = resolveNs(flag('ns'))
+  const { secrets } = await loadEnv({ ns, wait: false })
+  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
+}
+
+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 child = spawn(cmd[0], cmd.slice(1), { stdio: 'inherit', env: process.env })
+  child.on('exit', (code, signal) => process.exit(signal ? 1 : (code ?? 0)))
+}
+
+const run = async () => {
+  switch (argv[0]) {
+    case 'enroll': return cmdEnroll()
+    case 'status': return cmdStatus()
+    case 'check': return cmdCheck()
+    case 'run': return cmdRun()
+    case undefined:
+    case 'help':
+    case '--help':
+    case '-h': return help()
+    default: console.error('comando desconocido: %s\n', argv[0]); help(); process.exit(2)
+  }
+}
+
+run().catch((e) => { console.error('\n[dotrino-env] ' + e.message); process.exit(1) })

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@dotrino/vault",
-  "version": "0.2.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 servicio del ecosistema se enrola como dispositivo y obtiene sus secretos del vault en vez del .env.",
+  "version": "0.3.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",
   "module": "src/index.js",
+  "bin": {
+    "dotrino-env": "bin/dotrino-env.js"
+  },
   "exports": {
     ".": {
       "import": "./src/index.js"
@@ -12,6 +15,12 @@
     "./service": {
       "import": "./src/service.js"
     },
+    "./env": {
+      "import": "./src/env.js"
+    },
+    "./config": {
+      "import": "./src/config.js"
+    },
     "./sealed": {
       "import": "./src/sealed.js"
     },
@@ -21,6 +30,7 @@
   },
   "files": [
     "src",
+    "bin",
     "README.md",
     "LICENSE"
   ],

package/src/config.js

@@ -0,0 +1,26 @@
+/**
+ * `import '@dotrino/vault/config'` — el equivalente de `import 'dotenv/config'`,
+ * pero contra el vault del dueño.
+ *
+ * Bloquea el arranque (top-level await) hasta que los secretos del ns estén en
+ * `process.env`. Si el vault no está disponible, ESPERA (reintento con backoff):
+ * la regla del ecosistema es que 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 el proceso.
+ *
+ * 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
+ */
+import { loadEnv } from './env.js'
+
+const quiet = process.env.DOTRINO_ENV_QUIET === '1'
+
+const { ns, injected } = 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)

package/src/env.js

@@ -0,0 +1,95 @@
+/**
+ * `@dotrino/vault/env` — el "dotenv contra el vault".
+ *
+ * Un proyecto Node cualquiera obtiene sus credenciales del vault del dueño en
+ * vez de llevarlas en un `.env`:
+ *
+ *   import { loadEnv } from '@dotrino/vault/env'
+ *   await loadEnv({ ns: 'miapp' })          // → process.env.API_KEY, …
+ *
+ * o, con la forma clásica de dotenv (side-effect, ns por `DOTRINO_NS`):
+ *
+ *   import '@dotrino/vault/config'
+ *
+ * Lo que queda en el disco del servicio NO es un secreto: es la llave del
+ * dispositivo (generada aquí, nunca sale) y un certificado con scope
+ * `vault:secrets:<ns>`. Los valores solo viven en memoria del proceso; si la
+ * máquina se compromete, se revoca el cert y no había nada que robar.
+ *
+ * Enrolar una vez:  npx dotrino-env enroll --ns miapp   (ver bin/dotrino-env.js)
+ */
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { fetchSecrets, waitForSecrets, readServiceIdentity } from './service.js'
+import { isValidSecretsNs } from './protocol.js'
+
+/** Raíz donde viven las identidades de servicio de esta máquina/usuario. */
+export function serviceRoot () {
+  return process.env.DOTRINO_ENV_HOME || path.join(os.homedir(), '.dotrino', 'service')
+}
+
+/** Directorio de la identidad del servicio `ns` (`DOTRINO_ENV_DIR` lo pisa). */
+export function serviceDir (ns) {
+  if (process.env.DOTRINO_ENV_DIR) return process.env.DOTRINO_ENV_DIR
+  if (!isValidSecretsNs(ns)) throw new Error('ns inválido (usa [a-z0-9-]{1,32}, p. ej. "miapp")')
+  return path.join(serviceRoot(), ns)
+}
+
+/** Namespaces ya enrolados en esta máquina. */
+export function listEnrolled () {
+  let names = []
+  try { names = fs.readdirSync(serviceRoot()) } catch (_) { return [] }
+  return names.filter((ns) => isValidSecretsNs(ns) && readServiceIdentity(path.join(serviceRoot(), ns)))
+}
+
+/**
+ * Resuelve el ns cuando no se pasa explícito: `DOTRINO_NS`, y si no, el único
+ * enrolado en esta máquina. Con varios, exige elegir (no adivinamos).
+ */
+export function resolveNs (ns) {
+  ns = ns || process.env.DOTRINO_NS
+  if (ns) {
+    if (!isValidSecretsNs(ns)) throw new Error('ns inválido: ' + ns)
+    return ns
+  }
+  const found = listEnrolled()
+  if (found.length === 1) return found[0]
+  if (found.length === 0) {
+    throw new Error('no hay ningún servicio enrolado en esta máquina: corre `npx dotrino-env enroll --ns <tu-app>`')
+  }
+  throw new Error(`hay varios servicios enrolados (${found.join(', ')}): elige uno con DOTRINO_NS=<ns> o loadEnv({ ns })`)
+}
+
+/**
+ * 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.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[]}>}
+ */
+export async function loadEnv ({ ns, dir, override = false, wait = true, required = [], onRetry } = {}) {
+  ns = resolveNs(ns)
+  dir = dir || serviceDir(ns)
+  const load = wait ? waitForSecrets : fetchSecrets
+  const secrets = await load({ dir, ns, onRetry })
+
+  const missing = required.filter((k) => !(k in secrets))
+  if (missing.length) {
+    throw new Error(`faltan secretos en el ns "${ns}": ${missing.join(', ')} (agrégalos con \`dotrino-vault secret set ${ns} <CLAVE> <valor>\`)`)
+  }
+
+  const injected = []
+  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)
+    injected.push(k)
+  }
+  return { ns, secrets, injected, skipped }
+}

package/src/service.js

@@ -60,11 +60,29 @@ function installNodeGlobals () {
   }
 }
 
-async function freshClient (proxyUrl) {
+async function freshClient (proxyUrl, connectTimeoutMs = 20000) {
   installNodeGlobals()
   const { WebSocketProxyClient } = await import('@dotrino/proxy-client')
   const client = new WebSocketProxyClient({ url: proxyUrl, enableWebRTC: false, autoReconnect: false })
-  await client.connect()
+  // connect() del cliente solo se resuelve con 'connected' y solo rechaza en el
+  // evento 'error' de transporte: si el socket cierra LIMPIO antes de 'connected'
+  // (p.ej. el proxy banea la IP y envía close 1008), la promesa quedaría colgada
+  // para siempre y waitForSecrets no reintentaría. Le ponemos un timeout propio.
+  let timer
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new Error('timeout conectando al proxy')), connectTimeoutMs)
+  })
+  try {
+    await Promise.race([client.connect(), timeout])
+  } catch (e) {
+    try { client.close() } catch (_) {}
+    // El 'error' de transporte del cliente puede llegar como un Event sin
+    // `message` → sin esto el operador ve una línea de error vacía.
+    const why = e?.message || e?.type || 'error de transporte'
+    throw new Error(`no se pudo conectar al proxy ${proxyUrl}: ${why}`)
+  } finally {
+    clearTimeout(timer)
+  }
   return client
 }