@dotrino/vault 0.2.1 → 0.4.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.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 servicio del ecosistema se enrola como dispositivo y obtiene sus secretos del vault en vez del .env.",
+  "version": "0.4.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"
   ],
@@ -32,7 +42,7 @@
     "pairing"
   ],
   "peerDependencies": {
-    "@dotrino/identity": ">=0.17.0",
+    "@dotrino/identity": ">=0.23.0",
     "@dotrino/proxy-client": ">=0.6.0"
   },
   "license": "MIT",

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/enroll.js

@@ -0,0 +1,250 @@
+/**
+ * enroll.js — núcleo del LADO BÓVEDA del emparejamiento endurecido.
+ *
+ * Fuente ÚNICA del flujo `vault.enroll` → `vault.enroll.challenge` → `vault.enrolled`
+ * y de la revocación firmada. Lo consumen los tres sitios que hacen de bóveda:
+ *   · el daemon del PC            (`dotrino-vault/src/vault.js`)
+ *   · «este dispositivo es bóveda» (`lib/src/index.js#startDeviceVault`)
+ *   · la copia vendorizada del iframe de identidad (`dotrino-identity/vault/vendor/vault/`)
+ *
+ * Módulo PURO: sin `node:*`, sin red, sin disco. Recibe la identidad (que firma), un
+ * transporte (`send`/`sendByPubkey`) y callbacks de log/auditoría. Así el binario Node
+ * lo embebe al compilar (SEA), el navegador lo importa y el iframe lo vendoriza sin
+ * bundler.
+ *
+ * EL CÓDIGO DE APROBACIÓN, en detalle (esto es lo que hace seguro el emparejamiento):
+ *   1. El DISPOSITIVO genera un código aleatorio de 6 dígitos, lo MUESTRA en su pantalla
+ *      y manda solo su COMPROMISO `SHA-256(code‖dpub‖sn)` dentro del `data` firmado.
+ *      El código en sí NUNCA viaja.
+ *   2. La bóveda no conoce el código: lo aprende cuando un humano lo TIPEA al aprobar.
+ *   3. Al aprobar, la bóveda RECOMPUTA el compromiso con el código tipeado y solo firma
+ *      el cert si coincide → aprobar exige haber ido a leer el código del dispositivo.
+ *   4. La bóveda ECHA el código junto al cert; el dispositivo lo acepta solo si es el
+ *      suyo → una bóveda falsa (que nunca vio el código) no puede enrolarlo.
+ *
+ * Qué cierra y qué NO (sin exagerar): cierra que se emita un cert sin que quien aprueba
+ * tenga el código del dispositivo — antes se firmaba igual y la defensa vivía solo en el
+ * cliente honesto, así que un cliente malicioso se quedaba con un cert válido. NO cierra
+ * el phishing en el que alguien le DICTA el código al dueño por otro canal: contra eso
+ * está la copy de advertencia y que el dueño reconozca el `deviceId` (residual A1/A2 de
+ * `docs/pairing-protocol.md`).
+ */
+import { verifyDeviceSig, pubkeyId, commitCode } from '@dotrino/identity/capabilities'
+
+/** Un token de emparejamiento vale 5 min. */
+export const PAIRING_TTL_MS = 5 * 60 * 1000
+/** Ventana anti-replay del ENROLL (±5 min), mismo criterio que el identify del proxy. */
+export const FRESH_WINDOW_MS = 5 * 60 * 1000
+/** Vida por defecto del cert de un dispositivo (tope duro de `MAX_DELEGATION_MS`). */
+export const DEVICE_TTL_MS = 30 * 24 * 60 * 60 * 1000
+
+export const MSG_ENROLL = 'vault.enroll'
+export const MSG_ENROLL_CHALLENGE = 'vault.enroll.challenge'
+export const MSG_ENROLLED = 'vault.enrolled'
+export const MSG_REVOKED = 'vault.revoked'
+export const MSG_ERROR = 'vault.error'
+
+/** Token aleatorio de 128 bits en hex. */
+export function randToken () {
+  const b = crypto.getRandomValues(new Uint8Array(16))
+  return [...b].map((x) => x.toString(16).padStart(2, '0')).join('')
+}
+
+/** deviceId legible (p. ej. `C440-AC0E`) a partir de una pubkey JWK. */
+export async function deviceIdOf (pub) {
+  const id = (await pubkeyId(pub)).slice(0, 8).toUpperCase()
+  return id.slice(0, 4) + '-' + id.slice(4, 8)
+}
+
+/**
+ * Crea el «mostrador» de emparejamiento de una bóveda.
+ *
+ * @param {Object} opts
+ * @param {Object} opts.identity        firma: `signData`, `signDelegation`, `listDelegations`, `revokeDelegation`.
+ * @param {string} opts.iss             pubkey de la maestra de ESTA bóveda (va en el QR).
+ * @param {string} opts.proxy           URL del proxy (va en el QR).
+ * @param {(to:string, obj:object)=>void} opts.send            responder por el token de la conexión.
+ * @param {(pub:string, obj:object)=>void} opts.sendByPubkey   dirigir por pubkey (cola offline 24 h).
+ * @param {(op:string, info?:object)=>void} [opts.audit]
+ * @param {(...a:any[])=>void} [opts.log]
+ * @param {(c:{deviceId:string, scope:any, label:string})=>void} [opts.onChallenge]  un dispositivo espera aprobación.
+ * @param {()=>void} [opts.onPendingChange]
+ * @param {string[]} [opts.defaultScope]
+ * @param {number} [opts.defaultTtlMs]
+ */
+export function createEnrollDesk ({
+  identity, iss, proxy, send, sendByPubkey,
+  audit = () => {}, log = () => {},
+  onChallenge = () => {}, onPendingChange = () => {},
+  defaultScope = ['vault:sign'], defaultTtlMs = DEVICE_TTL_MS
+} = {}) {
+  if (!identity) throw new Error('createEnrollDesk: falta identity')
+  if (!iss) throw new Error('createEnrollDesk: falta iss (pubkey de la maestra)')
+
+  // token -> { token, exp, scope, ttlMs, label, sn, state, dpub?, deviceId?, commit?, from? }
+  // state: 'AWAITING_ENROLL' -> 'PENDING_CONFIRM'
+  const pending = new Map()
+
+  const fire = (fn, arg) => { try { fn(arg) } catch (_) {} }
+  const reply = (to, obj) => { try { send(to, obj) } catch (e) { log('[vault] no se pudo responder:', e.message) } }
+  const isFresh = (d) => typeof d?.ts === 'number' && Math.abs(Date.now() - d.ts) <= FRESH_WINDOW_MS
+
+  /** Inicia un emparejamiento: token + nonce de sesión. NO firma nada todavía. */
+  function startPairing ({ scope = defaultScope, ttlMs = defaultTtlMs, label = '' } = {}) {
+    pending.clear() // uno a la vez: una sesión nueva supersede a la anterior
+    const token = randToken()
+    const sn = randToken()
+    pending.set(token, { token, exp: Date.now() + PAIRING_TTL_MS, scope, ttlMs, label, sn, state: 'AWAITING_ENROLL' })
+    return { token, qr: { v: 2, iss, proxy, token, sn }, expiresInMs: PAIRING_TTL_MS }
+  }
+
+  function stopPairing (token) { pending.delete(token) }
+
+  function listPending () {
+    return [...pending.values()]
+      .filter((p) => p.state === 'PENDING_CONFIRM')
+      .map((p) => ({ deviceId: p.deviceId, label: p.label || '', scope: p.scope }))
+  }
+
+  function findPending (deviceId) {
+    for (const p of pending.values()) {
+      if (p.state === 'PENDING_CONFIRM' && p.deviceId === deviceId) return p
+    }
+    return null
+  }
+
+  /**
+   * ENROLL: el dispositivo prueba posesión de `D` firmando el sobre y deja el
+   * COMPROMISO de su código. Todavía NO se firma ningún cert.
+   */
+  async function handleEnroll (from, p) {
+    const d = p?.data
+    if (!d || typeof d.dpub !== 'string' || typeof p.signature !== 'string') {
+      return reply(from, { type: MSG_ERROR, error: 'enroll inválido' })
+    }
+    const pend = pending.get(d.token)
+    if (!pend || pend.state === 'DONE' || Date.now() > pend.exp) {
+      return reply(from, { type: MSG_ERROR, error: 'token de emparejamiento inválido o expirado' })
+    }
+    if (d.sn !== pend.sn) return reply(from, { type: MSG_ERROR, error: 'sesión inválida' })
+    if (!isFresh(d)) {
+      audit('rejected', { what: 'enroll', reason: 'stale' })
+      return reply(from, { type: MSG_ERROR, error: 'petición vencida: ts fuera de la ventana ±5 min (posible replay, o el reloj del dispositivo está desfasado)' })
+    }
+    // PRUEBA DE POSESIÓN: la firma de `data` debe verificar contra `dpub`.
+    if (!(await verifyDeviceSig({ publickey: d.dpub, data: d, signature: p.signature }))) {
+      audit('rejected', { what: 'enroll', reason: 'bad-device-signature' })
+      return reply(from, { type: MSG_ERROR, error: 'firma de dispositivo inválida' })
+    }
+    // El COMPROMISO del código es obligatorio: sin él no se puede comprobar al aprobar
+    // y volveríamos a emitir certs a ciegas. Un cliente viejo cae acá con un mensaje claro.
+    if (typeof d.commit !== 'string' || !/^[0-9a-f]{64}$/.test(d.commit)) {
+      audit('rejected', { what: 'enroll', reason: 'no-commit' })
+      return reply(from, { type: MSG_ERROR, error: 'este dispositivo usa una versión antigua del emparejamiento (no envía el compromiso del código). Actualízalo y vuelve a intentarlo.' })
+    }
+    // Un solo dispositivo a la vez esperando su código (así aprobar no es ambiguo).
+    if (pend.state === 'PENDING_CONFIRM' && pend.dpub && pend.dpub !== d.dpub) {
+      return reply(from, { type: MSG_ERROR, error: 'ya hay un dispositivo usando este emparejamiento' })
+    }
+
+    const deviceId = await deviceIdOf(d.dpub)
+    pend.state = 'PENDING_CONFIRM'
+    pend.dpub = d.dpub
+    pend.deviceId = deviceId
+    pend.commit = d.commit
+    pend.from = from // la bóveda NO conoce el código: lo aprende cuando lo tipeas
+    if (d.label) pend.label = String(d.label).slice(0, 60)
+
+    reply(from, { type: MSG_ENROLL_CHALLENGE, deviceId })
+    fire(onChallenge, { deviceId, scope: pend.scope, label: pend.label || '' })
+    fire(onPendingChange)
+    return { deviceId }
+  }
+
+  /**
+   * Aprueba TIPEANDO el código que muestra el dispositivo. Recompone el compromiso
+   * `SHA-256(code‖dpub‖sn)` y solo firma el cert si coincide con el que llegó en el
+   * ENROLL — es decir, solo si de verdad fuiste a leer el código del dispositivo.
+   *
+   * @param {string} code
+   * @param {{deviceId?: string}} [opts]  cuál aprobar cuando hay varios pendientes.
+   */
+  async function approve (code, { deviceId } = {}) {
+    code = String(code || '').trim()
+    if (!code) throw new Error('falta el código (los dígitos que muestra el dispositivo)')
+
+    let pend
+    if (deviceId) {
+      pend = findPending(deviceId)
+      if (!pend) throw new Error('no hay ninguna máquina esperando aprobación con ese identificador')
+    } else {
+      const waiting = [...pending.values()].filter((p) => p.state === 'PENDING_CONFIRM' && p.dpub)
+      if (waiting.length === 0) throw new Error('no hay ningún dispositivo esperando aprobación')
+      if (waiting.length > 1) throw new Error('hay más de un emparejamiento en curso; reinícialo con dotrino-vault pair')
+      pend = waiting[0]
+    }
+
+    // COMPROBACIÓN DEL CÓDIGO — antes de firmar nada.
+    const expected = await commitCode({ code, dpub: pend.dpub, sn: pend.sn })
+    if (expected !== pend.commit) {
+      audit('rejected', { what: 'approve', device: pend.deviceId, reason: 'bad-code' })
+      log('[vault] código incorrecto para %s: no se emitió ningún certificado', pend.deviceId)
+      throw new Error('el código no coincide con el que muestra el dispositivo: no se emitió ningún certificado. Vuelve a mirarlo y prueba otra vez.')
+    }
+
+    const { cert } = await identity.signDelegation(pend.dpub, pend.scope, { ttlMs: pend.ttlMs, label: pend.label })
+    audit('enroll', { device: pend.deviceId, label: pend.label || '', scope: pend.scope })
+    // Echamos el código tipeado junto al cert: el DISPOSITIVO acepta solo si coincide
+    // con el que generó → una bóveda falsa (que no lo conoce) no puede enrolarlo.
+    reply(pend.from, { type: MSG_ENROLLED, code, cert, iss })
+    pend.state = 'DONE'
+    pending.delete(pend.token)
+    fire(onPendingChange)
+    log('[vault] dispositivo aprobado: %s', pend.deviceId)
+    return { ok: true, deviceId: pend.deviceId, cert }
+  }
+
+  /** Rechaza un enrolamiento pendiente. */
+  function reject (deviceId) {
+    const pend = deviceId
+      ? findPending(deviceId)
+      : [...pending.values()].find((p) => p.state === 'PENDING_CONFIRM')
+    if (!pend) return { ok: false }
+    reply(pend.from, { type: MSG_ERROR, error: 'emparejamiento rechazado' })
+    pending.delete(pend.token)
+    audit('reject', { device: pend.deviceId })
+    fire(onPendingChange)
+    log('[vault] dispositivo rechazado: %s', pend.deviceId)
+    return { ok: true, deviceId: pend.deviceId }
+  }
+
+  /**
+   * Emite un REVOKED FIRMADO por la maestra para que el dispositivo se autoborre. El
+   * borrado remoto SOLO se dispara con esta firma (nunca con un error cualquiera →
+   * cierra el wipe-DoS). Va por `sendByPubkey`: si está apagado, el proxy lo encola 24 h.
+   */
+  async function emitRevoke (dpub, nonce) {
+    const body = { op: 'revoke', sub: dpub, nonce, iat: Date.now(), exp: Date.now() + DEVICE_TTL_MS }
+    const { signature } = await identity.signData(body)
+    try { sendByPubkey(dpub, { type: MSG_REVOKED, body, signature }) }
+    catch (e) { log('[vault] no se pudo emitir revoke:', e.message) }
+  }
+
+  /** Revoca una delegación por `nonce` y avisa al dispositivo para que se autoborre. */
+  async function revoke (nonce) {
+    audit('revoke', { nonce })
+    const { issued } = await identity.listDelegations()
+    const dele = (issued || []).find((d) => d.nonce === nonce)
+    const res = await identity.revokeDelegation(nonce)
+    if (dele?.sub) await emitRevoke(dele.sub, nonce)
+    return res
+  }
+
+  return {
+    startPairing, stopPairing, handleEnroll, approve, reject,
+    listPending, findPending, emitRevoke, revoke,
+    get pendingCount () { return pending.size }
+  }
+}
+
+export default { createEnrollDesk, deviceIdOf, randToken }

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/index.js

@@ -17,37 +17,29 @@
  *     → una bóveda falsa (que nunca vio el código) no puede enrolar el dispositivo, y
  *     aprobar "a ciegas" (sin ir a leer el código del dispositivo) tampoco enrola nada.
  *
- * Cripto 100% de `@dotrino/identity/capabilities` (verifyDeviceSig/verifyChain/pubkeyId)
- * + firma con la identidad P (`identity.signDelegation`). Transporte: `@dotrino/proxy-client`
- * (import perezoso). No reimplementa nada del ecosistema.
+ * El flujo de enrolamiento en sí (incluida la comprobación del código antes de firmar) vive
+ * en `./enroll.js`, COMPARTIDO con el daemon del PC y con la copia vendorizada del iframe:
+ * un solo sitio donde se decide a quién se le emite un certificado.
+ *
+ * Cripto 100% de `@dotrino/identity/capabilities`; firma con la identidad P
+ * (`identity.signDelegation`). Transporte: `@dotrino/proxy-client` (import perezoso).
+ * No reimplementa nada del ecosistema.
  */
-import { verifyDeviceSig, verifyChain, pubkeyId } from '@dotrino/identity/capabilities'
+import { verifyChain } from '@dotrino/identity/capabilities'
+import { createEnrollDesk, deviceIdOf, DEVICE_TTL_MS, FRESH_WINDOW_MS } from './enroll.js'
 
 const SIGN_SCOPE = 'vault:sign'
-const PAIRING_TTL_MS = 5 * 60 * 1000           // un emparejamiento (token) vale 5 min
-const DEVICE_TTL_MS = 30 * 24 * 60 * 60 * 1000 // vida de un cert de dispositivo (30 días)
 const SELFCERT_TTL_MS = 24 * 60 * 60 * 1000    // el self-cert P←P se regenera cada 24 h
-const FRESH_WINDOW_MS = 5 * 60 * 1000          // ventana anti-replay del enroll (±5 min)
 
 const MSG = {
   ENROLL: 'vault.enroll',
-  ENROLL_CHALLENGE: 'vault.enroll.challenge',
-  ENROLLED: 'vault.enrolled',
   DEVICES: 'vault.devices',
   DEVICES_RESULT: 'vault.devices.result',
-  REVOKED: 'vault.revoked',
   ERROR: 'vault.error'
 }
 
-function randToken () {
-  const b = crypto.getRandomValues(new Uint8Array(16))
-  return [...b].map((x) => x.toString(16).padStart(2, '0')).join('')
-}
-
 /** deviceId legible (p. ej. `C440-AC0E`) desde una pubkey JWK. */
-export function deviceIdOf (pub) {
-  return pubkeyId(pub).then((id) => id.slice(0, 8).toUpperCase().replace(/(.{4})(.{4})/, '$1-$2'))
-}
+export { deviceIdOf }
 
 /**
  * Levanta la bóveda de este dispositivo: se conecta al proxy identificado como P y
@@ -94,49 +86,21 @@ export async function startDeviceVault (identity, { proxyUrl } = {}) {
 
   const send = (to, obj) => { try { client.send(to, obj) } catch (_) {} }
 
-  // token -> { exp, sn, scope, ttlMs, label, state, dpub?, deviceId?, from? }
-  const pending = new Map()
   let _onPendingChange = () => {}
 
-  async function handleEnroll (from, p) {
-    const d = p?.data
-    if (!d || typeof d.dpub !== 'string' || typeof p.signature !== 'string') {
-      return send(from, { type: MSG.ERROR, error: 'enroll inválido' })
-    }
-    const pend = pending.get(d.token)
-    if (!pend || Date.now() > pend.exp) {
-      return send(from, { type: MSG.ERROR, error: 'token de emparejamiento inválido o expirado' })
-    }
-    if (d.sn !== pend.sn) return send(from, { type: MSG.ERROR, error: 'sesión inválida' })
-    if (typeof d.ts !== 'number' || Math.abs(Date.now() - d.ts) > FRESH_WINDOW_MS) {
-      return send(from, { type: MSG.ERROR, error: 'enroll vencido (posible replay, o el reloj desfasado)' })
-    }
-    // PRUEBA DE POSESIÓN: la firma de `data` debe verificar contra `dpub`.
-    const ok = await verifyDeviceSig({ publickey: d.dpub, data: d, signature: p.signature })
-    if (!ok) return send(from, { type: MSG.ERROR, error: 'firma de dispositivo inválida' })
-    // Un solo dispositivo a la vez esperando su código (así `approve` no es ambiguo).
-    if (pend.state === 'PENDING_CONFIRM' && pend.dpub && pend.dpub !== d.dpub) {
-      return send(from, { type: MSG.ERROR, error: 'ya hay un dispositivo usando este emparejamiento' })
-    }
-    const deviceId = await deviceIdOf(d.dpub)
-    pend.state = 'PENDING_CONFIRM'
-    pend.dpub = d.dpub
-    pend.deviceId = deviceId
-    pend.from = from // esta bóveda NO conoce el código (no viaja): el dispositivo lo MUESTRA
-    if (d.label) pend.label = String(d.label).slice(0, 60)
-    _onPendingChange()
-    send(from, { type: MSG.ENROLL_CHALLENGE, deviceId })
-  }
-
-  // Emite un REVOKED FIRMADO por la maestra a la máquina revocada para que se
-  // auto-borre. Va por `sendByPubkey` → si está offline, el proxy lo encola 24 h; y
-  // si reaparece más tarde, `handleDevices` lo re-emite en su siguiente consulta.
-  // El auto-borrado remoto SOLO se dispara con esta firma (no con un error cualquiera).
-  async function emitRevoke (dpub, nonce) {
-    const body = { op: 'revoke', sub: dpub, nonce, iat: Date.now(), exp: Date.now() + DEVICE_TTL_MS }
-    const { signature } = await identity.signData(body)
-    try { client.sendByPubkey(dpub, { type: MSG.REVOKED, body, signature }) } catch (_) {}
-  }
+  // 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
+  // flujo → y por lo tanto un solo sitio donde se comprueba el código antes de firmar.
+  const desk = createEnrollDesk({
+    identity,
+    iss,
+    proxy,
+    send,
+    sendByPubkey: (pub, obj) => { try { client.sendByPubkey(pub, obj) } catch (_) {} },
+    defaultScope: [SIGN_SCOPE],
+    defaultTtlMs: DEVICE_TTL_MS,
+    onPendingChange: () => _onPendingChange()
+  })
 
   // 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
@@ -155,62 +119,15 @@ export async function startDeviceVault (identity, { proxyUrl } = {}) {
     send(from, { type: MSG.DEVICES_RESULT, devices, revoked: (revoked || []).map((r) => r.nonce || r) })
     // ¿el que consulta es una máquina revocada que reapareció? → re-emite el REVOKED firmado.
     const mine = (issued || []).find((x) => x.sub === chk.device && x.revokedAt)
-    if (mine) emitRevoke(chk.device, mine.nonce)
+    if (mine) desk.emitRevoke(chk.device, mine.nonce)
   }
 
   client.on('message', (_from, p) => {
     if (!p || typeof p !== 'object') return
-    if (p.type === MSG.ENROLL) handleEnroll(_from, p).catch(() => {})
+    if (p.type === MSG.ENROLL) desk.handleEnroll(_from, p).catch(() => {})
     else if (p.type === MSG.DEVICES) handleDevices(_from, p).catch(() => {})
   })
 
-  /**
-   * Abre un emparejamiento: devuelve el QR/JSON v2 que el dispositivo consume para
-   * enrolarse. `scope`/`ttlMs`/`label` fijan lo que otorgará el cert al aprobar.
-   */
-  function startPairing ({ scope = [SIGN_SCOPE], ttlMs = DEVICE_TTL_MS, label = '' } = {}) {
-    pending.clear()
-    const token = randToken()
-    const sn = randToken()
-    pending.set(token, { token, exp: Date.now() + PAIRING_TTL_MS, sn, scope, ttlMs, label, state: 'AWAITING_ENROLL' })
-    return { qr: { v: 2, iss, proxy, token, sn }, expiresInMs: PAIRING_TTL_MS }
-  }
-
-  function listPending () {
-    return [...pending.values()]
-      .filter((p) => p.state === 'PENDING_CONFIRM')
-      .map((p) => ({ deviceId: p.deviceId, label: p.label }))
-  }
-  function findPending (deviceId) {
-    for (const [, p] of pending) if (p.state === 'PENDING_CONFIRM' && p.deviceId === deviceId) return p
-    return null
-  }
-
-  /**
-   * Aprueba una máquina pendiente TIPEANDO el código que ella muestra. Esta bóveda NO
-   * conoce/valida el código: firma el cert y ECHA el código tipeado; la máquina lo acepta
-   * solo si coincide con el que generó. (Modelo `dotrino-vault#approveDevice`.)
-   */
-  async function approve (deviceId, code) {
-    const pend = findPending(deviceId)
-    if (!pend || !pend.dpub) throw new Error('no hay ninguna máquina esperando aprobación')
-    code = String(code || '').trim()
-    if (!code) throw new Error('escribe el código que muestra la máquina')
-    const { cert } = await identity.signDelegation(pend.dpub, pend.scope, { ttlMs: pend.ttlMs, label: pend.label })
-    send(pend.from, { type: MSG.ENROLLED, code, cert, iss })
-    pending.delete(pend.token)
-    _onPendingChange()
-    return { ok: true, deviceId }
-  }
-
-  function reject (deviceId) {
-    const pend = findPending(deviceId)
-    if (!pend) return
-    send(pend.from, { type: MSG.ERROR, error: 'emparejamiento rechazado' })
-    pending.delete(pend.token)
-    _onPendingChange()
-  }
-
   /**
    * Máquinas enroladas bajo esta identidad (P), vigentes, con scope de firma y label
    * propio (excluye navegadores enrolados con label 'cli', que no atienden peticiones).
@@ -228,20 +145,18 @@ export async function startDeviceVault (identity, { proxyUrl } = {}) {
     return Promise.all([...bySub.values()].map(async (x) => ({ ...x, deviceId: await deviceIdOf(x.sub) })))
   }
 
-  async function revoke (nonce) {
-    // Deja el registro persistente (revokedAt en la delegación) y AVISA a la máquina
-    // con un REVOKED firmado para que se auto-borre (ahora si está online, o al
-    // reaparecer vía handleDevices). Ver emitRevoke.
-    const { issued } = await identity.listDelegations()
-    const dele = (issued || []).find((d) => d.nonce === nonce)
-    const res = await identity.revokeDelegation(nonce)
-    if (dele?.sub) await emitRevoke(dele.sub, nonce)
-    return res
-  }
-
   return {
     iss, proxy, client,
-    startPairing, approve, reject, listPending, listMachines, revoke,
+    startPairing: desk.startPairing,
+    // 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 }),
+    reject: (deviceId) => desk.reject(deviceId),
+    listPending: desk.listPending,
+    listMachines,
+    // Revoca y AVISA a la máquina con un REVOKED firmado para que se auto-borre (ahora si
+    // está online, o al reaparecer vía handleDevices).
+    revoke: (nonce) => desk.revoke(nonce),
     getSelfCert,
     onPendingChange (fn) { _onPendingChange = fn || (() => {}) },
     close () { try { client.close() } catch (_) {} }

package/src/service.js

@@ -22,7 +22,7 @@ import fs from 'node:fs'
 import path from 'node:path'
 import {
   makeDeviceKey, signWithDevice, verifyDelegation, verifyDeviceSig,
-  makePairingCode, pubkeyId
+  makePairingCode, commitCode, pubkeyId
 } from '@dotrino/identity/capabilities'
 import { MSG, secretsScope, isValidSecretsNs } from './protocol.js'
 import { makeEphemeralKey, openSealed } from './sealed.js'
@@ -76,7 +76,10 @@ async function freshClient (proxyUrl, connectTimeoutMs = 20000) {
     await Promise.race([client.connect(), timeout])
   } catch (e) {
     try { client.close() } catch (_) {}
-    throw e
+    // 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)
   }
@@ -141,7 +144,10 @@ export async function enrollService ({ qr, ns, dir, label, onCode, approveTimeou
     // Código ALEATORIO generado AQUÍ: el vault no lo conoce; solo puede echarlo
     // de vuelta si el dueño lo tipeó (= tiene esta pantalla a la vista).
     const code = makePairingCode()
-    const data = { op: 'enroll', dpub: device.publickey, token: qr.token, sn: qr.sn, label, ts: Date.now() }
+    // 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, sn: qr.sn, commit, label, ts: Date.now() }
     const { signature } = await signWithDevice({ privateJwk: device.privateJwk, data })
 
     const enrolled = new Promise((resolve, reject) => {