@dotrino/vaultd 0.6.0

package/README.md

@@ -0,0 +1,301 @@
+# Dotrino Vault — tu certificador personal
+
+> **Parte del ecosistema [Dotrino](https://dotrino.com).** Tu identidad, en tu
+> máquina, bajo tus reglas — sin anuncios, sin cookies, sin rastreo.
+
+`dotrino-vault` es el **certificador personal** del usuario: un **servicio headless**
+que custodia tu **clave maestra** y actúa como tu **propia CA**. En vez de depender
+de las CAs, del "Inicia sesión con Google/Apple" o de verificadores de KYC, **tú
+certificas**: enrolas tus dispositivos, firmas documentos y avalas a otras personas,
+sin pedirle permiso a ningún portero central. La maestra **nunca sale** de tu máquina.
+
+## Modelo: identidad delegada (la maestra se queda en una sola máquina)
+
+```
+ PC (vault)  ── clave maestra P (NUNCA sale) ────────────────────────────┐
+   · genera/custodia P (vía @dotrino/identity)                            │
+   · firma un CERT por dispositivo:  "D puede <scope> en nombre de P,     │
+     hasta <exp>, revocable por <nonce>"                                  │
+   · firma datos a pedido de un dispositivo enrolado (devuelve solo la firma)
+         ▲ proxy (sendByPubkey + cola offline 24h)                        │
+         │                                                                │
+   cel / laptop  ── su propia sub-clave D (P nunca la ve) ────────────────┘
+     · se enrola escaneando un QR del vault → recibe su cert
+     · firma cada acción con D y adjunta el cert; el vault verifica la CADENA D←P
+```
+
+Todo esto **no se reimplementa**: la cripto de delegación vive en
+`@dotrino/identity` (`signDelegation`, `verifyChain`, `makeDeviceKey`), el transporte
+es `@dotrino/proxy-client`. Este repo solo **orquesta**.
+
+## Instalación (Linux)
+
+**Ubuntu / Debian — `.deb`** (lo más simple): descarga el `.deb` (versionado) desde
+[Releases](https://github.com/imdotrino/dotrino-vault/releases/latest) y haz doble
+clic, o en la terminal:
+
+```sh
+sudo apt install ./dotrino-vault_*.deb
+```
+
+**Otro Linux — tarball:** descarga el binario autosuficiente y ejecuta el instalador:
+
+```sh
+tar xzf dotrino-vault-*-linux-x64.tar.gz
+cd dotrino-vault-*-linux-x64
+sh install.sh
+```
+
+El `.deb` deja los binarios en `/usr/bin`, instala la unidad `systemd --user` y la
+habilita; el tarball hace lo equivalente en tu `$HOME`. Ambos: nada de Node ni
+dependencias, y el servicio arranca solo.
+
+El binario **trae Node embebido**: no necesitas instalar Node ni dependencias de npm. Lo
+único que espera del sistema es la biblioteca `libatomic1`, que casi todas las distribuciones
+traen puesta; el `.deb` la declara y la instala sola si falta. Con el tarball, en un sistema
+muy pelado (un contenedor mínimo, por ejemplo), instálala tú:
+`sudo apt install libatomic1`. El instalador lo
+deja como **servicio systemd `--user`** que arranca solo (también en el boot, vía
+`linger`). En el primer arranque genera tu identidad y se conecta al proxy. **Sin
+contraseña, sin abrir puertos** (el vault marca hacia afuera).
+
+> Sin firma de código: tu sistema puede advertir que el binario no está firmado. Es
+> autohospedado y de código abierto; en Linux solo necesita permiso de ejecución (el
+> instalador lo da). macOS y Windows llegan en v2.
+
+### CLI de control
+
+```sh
+dotrino-vault tui                  # interfaz de terminal a pantalla completa (ver abajo)
+dotrino-vault status               # estado del servicio + fingerprint
+dotrino-vault pair                 # inicia un emparejamiento (muestra el código y espera al dispositivo)
+dotrino-vault pending              # muestra el dispositivo pendiente + su código a comparar
+dotrino-vault approve <deviceId>   # aprueba un dispositivo (tras comparar el código en ambas pantallas)
+dotrino-vault reject  <deviceId>   # rechaza un dispositivo pendiente
+dotrino-vault devices              # lista dispositivos enrolados / revocados
+dotrino-vault revoke  <nonce>      # revoca un dispositivo (le ordena autoborrarse)
+dotrino-vault pair --service <ns>  # empareja un SERVICIO (proxy, geo…) con acceso SOLO a sus secretos
+dotrino-vault secret set <ns> <CLAVE> <valor>   # guarda un secreto para ese servicio
+dotrino-vault secret rm  <ns> <CLAVE>           # borra un secreto
+dotrino-vault secret list                       # nombres de secretos (nunca valores)
+dotrino-vault logs                 # últimos logs del servicio
+```
+
+### Interfaz de terminal (TUI)
+
+Todo lo anterior (bóvedas, dispositivos y secretos) también se maneja desde una
+**interfaz de terminal a pantalla completa**, sin memorizar subcomandos:
+
+```sh
+dotrino-vault tui             # binario instalado
+node bin/dotrino-vault-tui.js # en desarrollo  (o:  npm run tui)
+```
+
+Como la CLI, la TUI **no abre la identidad ni la red**: le habla al daemon por el
+mismo canal de archivos + señales. El daemon debe estar corriendo; si no, la TUI
+ofrece arrancarlo. No agrega dependencias (se dibuja con ANSI y lee el teclado en
+raw mode).
+
+**Navegación en dos niveles**, para que siempre sea explícito de qué bóveda son
+los dispositivos/variables que estás viendo:
+
+1. **Bóvedas** es la pantalla de entrada: lista tus perfiles (`↑↓` mover, `Enter`
+   **entrar** a uno — lo activa si no lo estaba). Ahí también creas una bóveda
+   nueva, renombras, borras y pones/quitas/usas la contraseña (candado).
+2. Al entrar caes en sus **pestañas horizontales**, que cambias con `←→`:
+   - **Dispositivos (pares):** verlos, **emparejar** uno nuevo (muestra el QR y la
+     URL, y espera a que se conecte), **aprobar** con el código que muestra el
+     dispositivo, **rechazar** y **revocar**.
+   - **Scopes y variables (secretos):** ver los scopes y sus variables (nunca los
+     valores), **agregar** una variable (con su scope) y **quitar** una variable o
+     un scope entero.
+
+`Esc` desde las pestañas vuelve a la lista de bóvedas (para entrar a otra); `q`
+sale desde cualquier pantalla. Las teclas de cada acción se listan en la barra
+inferior.
+
+### Varios perfiles en el mismo PC
+
+Puedes tener varias identidades tuyas en la misma máquina (p. ej. personal y
+trabajo). Cada perfil es **una identidad distinta**: su propia clave, sus propios
+dispositivos, sus propios datos y secretos — nada se cruza entre ellos. **Todos
+atienden a la vez**: el perfil «activo» solo decide a cuál va un comando cuando no
+lo dices con `--profile`, no apaga a los demás.
+
+```sh
+dotrino-vault profile ls                  # lista los perfiles (* = el activo)
+dotrino-vault profile add Trabajo         # crea un perfil (identidad nueva, vacía)
+dotrino-vault profile use Trabajo         # elige el activo
+dotrino-vault profile rename <nombre>     # renombra
+dotrino-vault profile rm Trabajo          # BORRA el perfil y su identidad (irreversible)
+
+dotrino-vault pair --profile Trabajo      # cualquier comando acepta --profile
+dotrino-vault devices --profile personal
+```
+
+Si ya usabas el vault antes de esto, tu identidad de siempre se convierte sola en
+el primer perfil («Perfil 1»): la misma clave, los mismos dispositivos, nada que
+volver a emparejar.
+
+### Contraseña del perfil (opcional)
+
+Cada perfil puede llevar contraseña. **Solo se pide para EDITAR el perfil** (cambiar
+tu nombre, avatar o datos): tus dispositivos siguen firmando, leyendo y guardando
+aunque el perfil esté bloqueado — así un reinicio del PC nunca deja tus apps
+muertas esperando a que alguien teclee algo.
+
+```sh
+dotrino-vault profile password     # pone o cambia la contraseña (te la pregunta)
+dotrino-vault profile password rm  # la quita
+dotrino-vault unlock               # desbloquea para poder editar
+dotrino-vault lock                 # vuelve a bloquear
+```
+
+El perfil se vuelve a bloquear al reiniciar el servicio. La contraseña **no se
+guarda**: solo un verificador con sal (PBKDF2), igual que el candado del navegador.
+Para que quede claro qué protege y qué no: evita que otro que se siente en tu
+máquina —o un dispositivo tuyo comprometido— te reescriba el perfil; **no** cifra la
+clave en el disco (eso es el cifrado en reposo, ver *Alcance*).
+
+**Emparejamiento endurecido** (ver [`docs/pairing-protocol.md`](./docs/pairing-protocol.md)):
+el dispositivo prueba posesión de su llave firmando el enrolamiento, y la maestra
+solo firma el certificado **después** de que compares un código de 6 dígitos (SAS)
+entre las dos pantallas y corras `approve`. Un código robado ya no alcanza para
+entrar; la revocación de un dispositivo le ordena **autoborrarse** (con firma de la
+maestra, no por un mensaje cualquiera).
+
+El servicio se gestiona con systemd `--user`
+(`systemctl --user {start,stop,restart} dotrino-vault`). Tus datos —clave maestra
+incluida— viven en `~/.local/share/dotrino/vault` (permisos `0600`/`0700`), con un
+subdirectorio `p/<id>/` por perfil.
+
+## Desarrollo
+
+```sh
+npm install
+node bin/dotrino-vaultd.js          # arranca el daemon (modo servicio)
+node bin/dotrino-vaultd.js --pair   # arranca + imprime un QR de emparejamiento
+bash packaging/build.sh             # compila el binario único (dist/)
+```
+
+### Enrolar y usar desde un dispositivo (Node, para testing)
+
+```js
+import { enroll, requestSign } from 'dotrino-vault/src/client.js'
+
+// 1) escaneas el QR del vault → obtienes { iss, proxy, token }
+const { device, cert, iss } = await enroll({ qr })   // GUARDA device (privada) + cert
+
+// 2) le pides a la maestra que firme algo (la maestra nunca sale del vault)
+const { signature } = await requestSign({
+  masterPubkey: iss, proxyUrl: qr.proxy, device, cert,
+  payload: { hola: 'mundo' }
+})
+```
+
+### Secretos de servicios (los servicios del ecosistema son clientes identificados)
+
+Los servicios (proxy, geo, bots…) **no llevan secretos de terceros en su `.env`**:
+se enrolan al vault como un dispositivo más, con un cert limitado al scope
+`vault:secrets:<ns>` (`pair --service <ns>`), y al arrancar piden su bundle.
+
+Son **dos momentos distintos, a propósito**: el **enrolamiento** (registro de la
+máquina) es un **comando previo** que corre un humano **una sola vez**; el
+**arranque** de la app solo lee la identidad ya guardada y no interactúa con nadie.
+
+#### 1) Enrolamiento — comando previo, una vez por máquina
+
+```bash
+# en el VAULT (tu PC)
+dotrino-vault pair --service proxy                 # invitación con scope SOLO vault:secrets:proxy
+dotrino-vault secret set proxy TURN_KEY_ID  …
+
+# en la MÁQUINA del servicio (pega la invitación; te MUESTRA un código)
+npx dotrino-env enroll --ns proxy
+
+# de vuelta en el VAULT: tipeas el código LEYÉNDOLO de la pantalla del servicio
+dotrino-vault approve 7K3F-92Q1
+```
+
+Deja `~/.dotrino/service/<ns>/service-identity.json` (0600) con la llave del
+dispositivo (generada ahí, nunca sale) + el cert. **No hay ningún secreto en disco.**
+
+**Por qué NO se enrola en el primer arranque de la app:** el enrolamiento exige un
+humano que **lea el código en la pantalla del servicio** — es lo único que impide que
+un vault falso (que nunca vio el código) enrole la máquina, o que alguien apruebe a
+ciegas. Un servicio arranca bajo systemd/PM2, sin TTY y sin nadie mirando: el código
+acabaría en un log (y quien lea el log ya podría aprobar). Además el arranque quedaría
+bloqueado esperando una aprobación que quizá nadie da, y un reinicio automático de
+madrugada intentaría re-enrolar. Separados, el arranque es determinista e idempotente:
+solo **lee**; el enrolamiento **escribe** y consume una invitación de un solo uso.
+
+Va donde va el `npm ci` al aprovisionar el VPS. (Para máquinas efímeras —Docker,
+autoescalado— haría falta una invitación pre-provisionada de un solo uso con TTL corto
+y auto-aprobación; **aún no está decidido ni implementado**.)
+
+#### 2) Arranque — sin interacción, en cada reinicio
+
+```js
+import '@dotrino/vault/config'     // como `dotenv/config`, pero contra el vault (ns = DOTRINO_NS)
+console.log(process.env.TURN_KEY_ID)
+```
+
+o explícito, con `@dotrino/vault/env` / `@dotrino/vault/service`:
+
+```js
+import { loadEnv } from '@dotrino/vault/env'
+const { secrets } = await loadEnv({ ns: 'proxy', required: ['TURN_KEY_ID'] })
+```
+
+**Modos de fallo (importante):**
+
+- **Vault caído / proxy caído** → **espera** (reintento con backoff, para siempre). Sin
+  vault el servicio no opera: no arranca con secretos viejos ni vacíos.
+- **Sin enrolar, cert revocado o vencido, scope equivocado** → **aborta en el acto**.
+  Son errores que no se arreglan reintentando: hay que (re)enrolar.
+
+CLI de apoyo: `dotrino-env status` (qué hay enrolado aquí), `dotrino-env check` (lista
+los **nombres** de los secretos, nunca los valores), `dotrino-env run -- <cmd>` (inyecta
+los secretos en el entorno de un proceso que no es Node).
+
+Garantías: la petición va firmada por la llave del servicio + cert (scope solo
+su `ns`); la respuesta viaja **sellada** a una llave efímera por petición (el
+proxy que la transporta no puede leerla, y un replay no se puede descifrar) y
+**firmada por la maestra** (verificada contra la `iss` pineada del enrolamiento).
+Revocar el cert (`revoke`) corta el acceso de inmediato; `activity` audita cada
+lectura. Los servicios críticos sin secretos en su core (el propio proxy) arrancan
+sin vault; solo la feature que los necesita (TURN) espera. Primer consumidor:
+`dotrino-proxy` (TURN de Cloudflare, ver su README).
+
+## Alcance
+
+- **v1 (este):** servicio headless en Node (Linux), **multi-perfil**, con
+  **contraseña opcional por perfil para editarlo** (verificador PBKDF2) pero la
+  **clave privada en claro** en el disco (en `~/.local/share/dotrino/vault`, permisos
+  `0600`). Enrolamiento de dispositivos, firma delegada y lectura del árbol de
+  contenidos por el proxy. Distribución como binario único (Node SEA) + servicio systemd.
+- **v2:** **cifrado en reposo** con la contraseña (keychain del SO o archivo, a
+  elección) — hoy la contraseña es un candado de edición, no cifra la clave; UI de
+  escritorio (Tauri) como cliente del daemon; firma de documentos con sellado de
+  tiempo (`dotrino-signer`); macOS y Windows.
+
+## Estructura
+
+- `src/vault.js` — núcleo de UN perfil (Identity + transporte + router: enrolar/firmar/leer).
+- `src/profiles.js` — registro multi-perfil (`profiles.json`, `p/<id>/`) + candado por contraseña.
+- `src/manager.js` — corre todos los perfiles a la vez (uno por maestra/conexión).
+- `src/daemon.js` — modo servicio: `state.json`, emparejamiento por señal, apagado limpio.
+- `src/ctl.js` — CLI de control (habla con el daemon por archivos + señales, sin socket).
+- `src/vaultControl.js` — API de control programática (misma vía que la CLI); la usa la TUI.
+- `src/tui/` — interfaz de terminal a pantalla completa, sin dependencias (`term.js` primitivas ANSI/raw-mode; `app.js` pantallas).
+- `src/transport.js` — conexión headless al proxy + `identify` firmado.
+- `src/store.js` — árbol de contenidos (`vault.json`, versionado).
+- `src/client.js` — helper de **dispositivo** (enrolar / pedir firma / leer).
+- `src/protocol.js` — tipos de mensaje y scopes. · `src/qr.js` — QR ASCII. · `src/paths.js` — dirs.
+- `bin/sea-entry.js` — entrypoint del binario único (multicall daemon / `--ctl` / `--tui`).
+- `bin/dotrino-vaultd.js` — entrypoint de desarrollo (node directo).
+- `bin/dotrino-vault-tui.js` — entrypoint de desarrollo de la TUI.
+- `packaging/` — `build.sh` (binario), `install.sh`/`uninstall.sh`, unit systemd.
+- `web/` — la página `vault.dotrino.com` (Vite + Vue).
+
+Sin anuncios, sin cuentas, sin rastreo. MIT · parte de Dotrino.

package/bin/dotrino-vault-tui.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+/**
+ * dotrino-vault-tui — interfaz de terminal (pantalla completa) del vault.
+ *
+ * Entrypoint de DESARROLLO (node directo). En producción el binario SEA expone
+ * lo mismo con `dotrino-vaultd --tui` (ver bin/sea-entry.js).
+ *
+ * NO abre la identidad ni la red: le da órdenes al daemon por archivos + señales
+ * (misma vía que la CLI de control). El daemon debe estar corriendo; si no, la
+ * TUI ofrece arrancarlo.
+ *
+ *   node bin/dotrino-vault-tui.js
+ *
+ * Env:
+ *   DOTRINO_VAULT_DIR   dir de datos (default ~/.local/share/dotrino/vault)
+ */
+import { runTui } from '../src/tui/app.js'
+
+if (!process.stdout.isTTY) {
+  console.error('dotrino-vault-tui necesita un terminal interactivo (TTY).')
+  process.exit(2)
+}
+
+runTui().catch((e) => {
+  // El finally de runTui ya restauró el terminal; aquí solo reportamos.
+  console.error('error en la TUI:', e?.stack || e?.message || e)
+  process.exit(1)
+})

package/bin/dotrino-vault.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+/**
+ * dotrino-vault — el CLI de control, instalado por npm.
+ *
+ * En el binario autosuficiente (SEA) este mismo CLI vive dentro del ejecutable y se
+ * invoca con `dotrino-vaultd --ctl …`; instalado por npm es un `bin` propio, que es lo
+ * que espera quien lo corre con `npx` o tras un `npm i -g`.
+ *
+ * NO abre la identidad ni la red: le da órdenes al daemon escribiendo archivos en el
+ * dir de datos (ver `src/vaultControl.js`). Por eso funciona igual en Linux, Windows,
+ * macOS y —montando el dir— desde fuera de un contenedor.
+ *
+ *   dotrino-vault status · pair · approve <código> · members · devices · revoke <nonce>
+ *
+ * Env:
+ *   DOTRINO_VAULT_DIR   dir de datos (default: ver `src/paths.js`)
+ */
+import { runCtl } from '../src/ctl.js'
+
+runCtl(process.argv.slice(2)).catch((e) => {
+  console.error('error:', e?.message || e)
+  process.exit(1)
+})

package/bin/dotrino-vaultd.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+/**
+ * dotrino-vaultd — entrypoint de DESARROLLO (node directo, sin SEA).
+ *
+ *   node bin/dotrino-vaultd.js          arranca el vault (modo servicio)
+ *   node bin/dotrino-vaultd.js --pair   arranca e imprime un QR de emparejamiento
+ *
+ * En producción el usuario corre el binario SEA (bin/sea-entry.js → src/daemon.js).
+ * Este archivo comparte el mismo núcleo (`runDaemon`) para no divergir.
+ *
+ * Env:
+ *   DOTRINO_VAULT_DIR   dir de datos (default ~/.dotrino/vault)
+ *   PROXY_URL           proxy (default wss://proxy.dotrino.com)
+ */
+import { runDaemon } from '../src/daemon.js'
+import { qrToString } from '../src/qr.js'
+
+const mgr = await runDaemon()
+
+// Atajo de dev: --pair imprime el QR directo en stdout (en producción se usa el CLI).
+// Empareja contra el perfil ACTIVO.
+if (process.argv.includes('--pair')) {
+  const { qr, expiresInMs } = mgr.current().startPairing({ label: 'cli' })
+  console.log(`\nEmparejá un dispositivo (válido ${expiresInMs / 60000} min):\n`)
+  console.log(qrToString(JSON.stringify(qr)))
+  console.log(JSON.stringify(qr))
+}
+
+console.log('\n(Ctrl+C para detener)')

package/bin/sea-entry.js

@@ -0,0 +1,29 @@
+/**
+ * sea-entry.js — punto de entrada ÚNICO del binario autosuficiente (SEA).
+ *
+ * El mismo binario hace de daemon y de CLI de control (multicall):
+ *   dotrino-vaultd            → arranca el daemon (modo servicio)
+ *   dotrino-vaultd --ctl ...  → CLI de control (status / pair / devices / revoke)
+ *
+ * El wrapper `dotrino-vault` invoca siempre con `--ctl`. Se usa import dinámico
+ * para no cargar el grafo del daemon (transporte/identity) cuando solo quieres
+ * un `status` rápido.
+ */
+const argv = process.argv.slice(2)
+
+if (argv[0] === '--tui') {
+  // Interfaz de terminal (pantalla completa). Como la CLI, NO toca la identidad
+  // ni el proxy: habla con el daemon por el dir de datos + señales.
+  if (!process.stdout.isTTY) { console.error('la TUI necesita un terminal interactivo (TTY).'); process.exit(2) }
+  import('../src/tui/app.js').then(({ runTui }) => runTui())
+    .catch((e) => { console.error('error en la TUI:', e.message); process.exit(1) })
+} else if (argv[0] === '--ctl') {
+  // CLI de control: NO toca la identidad ni el proxy; habla con el daemon vía
+  // el dir de datos (state.json) y señales (SIGUSR1 para emparejar).
+  import('../src/ctl.js').then(({ runCtl }) => runCtl(argv.slice(1)))
+    .catch((e) => { console.error('error:', e.message); process.exit(1) })
+} else {
+  // Modo daemon (servicio).
+  import('../src/daemon.js').then(({ runDaemon }) => runDaemon(argv))
+    .catch((e) => { console.error('error fatal del daemon:', e.message); process.exit(1) })
+}

package/lib/README.md

@@ -0,0 +1,139 @@
+# @dotrino/vault
+
+Usa **este dispositivo (navegador) como bóveda/CA** del ecosistema Dotrino, sin un PC
+con el daemon. Es la contraparte browser del daemon `dotrino-vault`: atiende el mismo
+protocolo de enrolamiento endurecido por el proxy y firma certificados de delegación
+`D ← P` (donde `P` es la identidad de este dispositivo, `@dotrino/identity`).
+
+Pensado para que **cualquier app** del ecosistema (no solo la terminal) pueda ofrecer
+"usar este dispositivo como bóveda".
+
+## Uso
+
+```js
+import { Identity } from '@dotrino/identity'
+import { startDeviceVault } from '@dotrino/vault'
+
+const identity = await Identity.connect()
+const vault = await startDeviceVault(identity)          // se conecta al proxy como P
+
+// 1) Abrir un emparejamiento y mostrar el QR/JSON al dispositivo a enrolar:
+const { qr } = vault.startPairing({ label: 'mi-agente' })
+// El dispositivo (p. ej. @dotrino/identity#enrollDevice) consume `qr`, GENERA un
+// código aleatorio y lo MUESTRA (no lo envía).
+
+// 2) Cuando el dispositivo pide acceso, aparece en la lista de pendientes:
+vault.onPendingChange(() => {
+  for (const { deviceId } of vault.listPending()) {
+    // Un humano LEE el código del dispositivo y lo TIPEA aquí:
+    // await vault.approve(deviceId, codigoTipeado)
+  }
+})
+
+// 3) Máquinas ya enroladas / revocar:
+const machines = await vault.listMachines()   // [{ sub, deviceId, label, exp, nonce, scope }]
+// await vault.revoke(nonce)
+
+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
+  lo **muestra**; el código **no viaja** por la red.
+- Esta bóveda **no conoce** el código: un humano lo **lee del dispositivo** y lo **tipea**
+  aquí. Al aprobar, la bóveda firma el cert y **echa** el código tipeado de vuelta.
+- El dispositivo acepta el cert **solo si el código echado coincide** con el que generó.
+  Así, una bóveda falsa (que nunca vio el código) no puede enrolarlo, y **aprobar a ciegas**
+  (sin ir a leer el código del dispositivo) no enrola a nadie.
+
+## API
+
+`startDeviceVault(identity, { proxyUrl? }) → Promise<handle>`
+
+- `startPairing({ scope?, ttlMs?, label? }) → { qr, expiresInMs }`
+- `listPending() → [{ deviceId, label }]`
+- `approve(deviceId, code) → Promise<{ ok, deviceId }>`  (code = lo que muestra el dispositivo)
+- `reject(deviceId)`
+- `listMachines() → Promise<[{ sub, deviceId, label, scope, exp, nonce }]>`
+- `revoke(nonce) → Promise`
+- `getSelfCert() → Promise<cert>`  (self-cert `P ← P`, para actuar además de cliente)
+- `onPendingChange(fn)`, `close()`
+
+Cripto y firma: `@dotrino/identity`. Transporte: `@dotrino/proxy-client`. No reimplementa
+nada del ecosistema.
+
+MIT · parte de [Dotrino](https://dotrino.com).

package/lib/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)