@dotrino/vault 0.13.0 → 0.15.0

package/README.md

@@ -97,12 +97,61 @@ Para procesos que no son Node, el CLI los inyecta en el entorno de un hijo:
 dotrino-env run --ns miapp -- ./mi-binario
 ```
 
+### Un agente tiene UNA identidad, y se la da el vault
+
+Un **aparato** puede llevar varios perfiles, y hasta meter su propia cuenta al vault
+por adopción: llega con una historia que conservar. Un **agente** no es eso. Es un
+servicio: su identidad se la cede el vault y no hay caso en que quiera empujar la
+suya hacia arriba. De ahí tres reglas, que el paquete aplica solas:
+
+- **No adopta, nunca.** La invitación declara su modo (`join` / `adopt`); si viene
+  abierta para adoptar, `enrollService` la **rechaza al pegarla**, sin salir a la red.
+  La intención `join` va además firmada dentro de la petición, para que nadie en el
+  medio la convierta en otra cosa.
+- **No acumula.** Enrolar de nuevo **reemplaza** la identidad anterior, que deja de
+  existir en ese agente. No es un error a desbloquear con `--force`: es la forma de
+  **rotar** la identidad de un agente comprometido. Se avisa por `onReplace` qué se
+  descarta.
+- **Un agente, un `ns`.** Varios agentes pueden convivir en una máquina (un
+  directorio por namespace); lo que no existe es un agente que sea varios.
+
+> ⚠ Si esa llave es además la **identidad de red** del servicio —el caso del proxio,
+> cuyo id de nodo se deriva de ella— reemplazarla le cambia el nombre en la red: las
+> instancias y citas vivas dejan de resolver y los peers que lo tenían pineado lo
+> rechazan hasta re-pinearlo. Es a propósito: así se echa a un nodo comprometido.
+
+### 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,12 +16,16 @@ 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 }
-const has = (name) => argv.includes('--' + name)
 
 function help () {
   console.log(`dotrino-env — credenciales del vault en vez del .env
@@ -40,7 +44,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`)
 }
 
 /**
@@ -66,9 +74,6 @@ 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)
@@ -77,6 +82,17 @@ async function cmdEnroll () {
     ns,
     dir,
     label: flag('label') || 'servicio:' + ns,
+    // Un agente tiene UNA identidad y se la da el vault: re-enrolar REEMPLAZA,
+    // no acumula. Antes había una reja (`--force`) que hacía de esto un error a
+    // desbloquear; sobra, porque no existe la alternativa de "quedarse con las
+    // dos". Lo que sí corresponde es que se vea qué se está tirando.
+    onReplace: (prev) => {
+      console.log('\n  ⚠ Este agente YA tenía identidad (dispositivo %s, del %s).',
+        prev.deviceId, new Date(prev.enrolledAt).toISOString().slice(0, 10))
+      console.log('    Se DESCARTA: el vault le cede una nueva y la anterior deja de existir aquí.')
+      console.log('    Si esa llave era además la identidad de red del servicio (el caso del')
+      console.log('    proxio), su id de nodo cambia y sus peers lo rechazan hasta re-pinearlo.\n')
+    },
     onCode: ({ deviceId, code }) => {
       console.log('\n  Dispositivo: %s', deviceId)
       console.log('  APRUEBA en el vault tipeando este código:\n')
@@ -106,17 +122,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.15.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 }
 }

package/src/service.js

@@ -26,6 +26,7 @@ import {
 } from '@dotrino/identity/capabilities'
 import { MSG, secretsScope, isValidSecretsNs } from './protocol.js'
 import { makeEphemeralKey, openSealed } from './sealed.js'
+import { parseInvite } from './invite.js'
 
 const IDENTITY_FILE = 'service-identity.json'
 const FRESH_WINDOW_MS = 5 * 60 * 1000
@@ -74,9 +75,36 @@ async function verificarHola (p, sn) {
   if (!(await verifyDeviceSig({ publickey: b.iss, data: b, signature: p.signature }))) {
     throw new Error('la respuesta de la bóveda no está bien firmada')
   }
+  // El modo también viene aquí, y aquí viene FIRMADO por la bóveda. Se comprueba
+  // de nuevo aunque ya se haya mirado el del QR: en la forma corta el QR es un
+  // código que pasó por manos ajenas, y esta es la primera vez que la bóveda
+  // dice de su puño y letra qué se propone hacer.
+  rechazarAdopcion(b.m)
   return b
 }
 
+/**
+ * UN AGENTE NUNCA TRANSFIERE SU IDENTIDAD: el vault propone, el agente acepta.
+ *
+ * El emparejamiento tiene dos modos y los declara la bóveda en la invitación:
+ * `join` (el que se enrola entra a la cuenta de la bóveda) y `adopt` (la bóveda
+ * se queda con la cuenta que trae el aparato). El segundo existe para APARATOS,
+ * que llegan con una cuenta propia y una historia que conservar.
+ *
+ * Un agente no tiene nada de eso: es un servicio, su identidad se la da el vault
+ * y no hay caso en que quiera empujar la suya hacia arriba. Así que este camino
+ * no se negocia, se rechaza — y se rechaza ACÁ, cuando el humano pega la
+ * invitación, en vez de dejar que el viaje termine en un «intent-mismatch» del
+ * otro lado que no le explica nada a nadie.
+ */
+function rechazarAdopcion (modo) {
+  if (modo !== 'adopt') return
+  throw new Error(
+    'esta invitación se abrió para ADOPTAR la cuenta del aparato, y un agente no transfiere su identidad: ' +
+    'la suya se la cede el vault. Abre el emparejamiento sin `--adopt` (`dotrino-vault pair --service <ns>`).'
+  )
+}
+
 /**
  * Canjea la cita del QR y devuelve la instancia a la que apunta.
  *
@@ -153,26 +181,68 @@ function writeServiceIdentity (dir, obj) {
 }
 
 /**
- * Enrola ESTE servicio contra el vault (una sola vez; persiste la identidad).
- * En el vault se corre antes `dotrino-vault pair --service <ns>`; el QR/payload
- * de ese comando es el `qr` de aquí. Muestra un código por `onCode` (o stdout):
- * el dueño lo tipea en el vault (`dotrino-vault approve <código>`).
+ * Enrola ESTE servicio contra el vault y persiste su identidad.
+ *
+ * UN AGENTE TIENE UNA SOLA IDENTIDAD, Y SE LA DA EL VAULT. A diferencia de un
+ * aparato —que puede llevar varios perfiles y hasta meter su cuenta al vault por
+ * adopción—, un agente no acumula identidades ni transfiere la suya: se enrola,
+ * el vault le cede una (llave propia + cert de la maestra) y **la anterior, si
+ * había, se descarta**. No hay fusión ni convivencia, y no hace falta: un agente
+ * es un servicio, no una persona; no tiene por qué "ser varios".
+ *
+ * Enrolar dos veces, entonces, no es un error a bloquear sino un REEMPLAZO — que
+ * es además la forma de rotar la identidad de un agente comprometido. Lo que sí
+ * hace falta es que se vea: se avisa por `onReplace` qué identidad se tira.
+ *
+ * En el vault se corre antes `dotrino-vault pair --service <ns>`; la invitación
+ * que imprime ese comando es el `qr` de aquí (en cualquiera de sus formas).
+ * Muestra un código por `onCode`: el dueño lo tipea en el vault
+ * (`dotrino-vault approve <código>`).
  *
  * @param {Object} opts
- * @param {{v:number, iss:string, proxy:string, token:string, sn:string}|string} opts.qr  QR v2 (objeto o JSON string).
+ * @param {object|string} opts.qr  La invitación: objeto, URL del QR o código pegado.
  * @param {string} opts.ns     Namespace de secretos del servicio (el mismo del pair).
  * @param {string} opts.dir    Dónde persistir `service-identity.json`.
  * @param {string} [opts.label]
  * @param {(c:{deviceId:string, code:string})=>void} [opts.onCode]
- * @returns {Promise<{device, cert, iss:string}>}
+ * @param {(prev:{ns:string, enrolledAt:number, deviceId:string})=>void} [opts.onReplace]
+ *   Se llama ANTES de enrolar si ya había una identidad: la que va a descartarse.
+ * @returns {Promise<{device, cert, iss:string, replaced:object|null}>}
  */
-export async function enrollService ({ qr, ns, dir, label, onCode, approveTimeoutMs = 180000 } = {}) {
-  if (typeof qr === 'string') { try { qr = JSON.parse(qr) } catch (_) { throw new Error('qr inválido: no es JSON') } }
+export async function enrollService ({ qr, ns, dir, label, onCode, onReplace, approveTimeoutMs = 180000 } = {}) {
+  // `parseInvite` y NO `JSON.parse`: el vault no imprime JSON desde hace rato.
+  // `dotrino-vault pair --service` emite la URL del QR y el código compacto
+  // (`c…`/`t…`, ver invite.js), así que un `JSON.parse` fallaba SIEMPRE con
+  // «qr inválido: no es JSON» y el enrolamiento de un servicio era imposible por
+  // este camino. Lo tapaba que el único servicio enrolado del ecosistema lo hizo
+  // cuando el formato todavía era JSON. `parseInvite` acepta todas las formas,
+  // incluida la vieja, así que esto entiende cualquier invitación.
+  if (typeof qr === 'string') {
+    const o = parseInvite(qr)
+    if (!o) throw new Error('eso no parece una invitación del vault (pega la salida de `dotrino-vault pair --service <ns>`)')
+    qr = o
+  }
   if (!qr?.sn || !(qr.iss || qr.conn)) throw new Error('qr inválido: falta la bóveda o el nonce')
+  rechazarAdopcion(qr.m)
   if (!isValidSecretsNs(ns)) throw new Error('ns inválido (usa [a-z0-9-]{1,32}, p.ej. "proxy")')
   if (!dir) throw new Error('falta dir (dónde persistir la identidad del servicio)')
   label = label || 'servicio:' + ns
 
+  // La identidad que va a quedar descartada. Se avisa antes de tocar nada: para
+  // el proxy, por ejemplo, esta llave es además su identidad de red, así que
+  // reemplazarla le cambia el id de nodo y sus peers dejan de reconocerlo hasta
+  // que se re-pineen a mano.
+  const anterior = readServiceIdentity(dir)
+  let replaced = null
+  if (anterior?.device?.publickey) {
+    replaced = {
+      ns: anterior.ns,
+      enrolledAt: anterior.enrolledAt,
+      deviceId: (await pubkeyId(anterior.device.publickey)).slice(0, 8).toUpperCase()
+    }
+    try { onReplace?.(replaced) } catch (_) {}
+  }
+
   const client = await freshClient(qr.proxy || 'wss://proxy.dotrino.com')
   // QR CORTO: se le pregunta a la bóveda quién es, punto a punto, presentando el `sn`.
   if (!qr.iss) {
@@ -201,7 +271,11 @@ export async function enrollService ({ qr, ns, dir, label, onCode, approveTimeou
     // 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 || qr.sn, sn: qr.sn, commit, label, ts: Date.now() }
+    // `intent: 'join'` EXPLÍCITO. La bóveda lo compara con el modo que abrió y,
+    // si falta, asume `join` — pero un agente no debe apoyarse en un default
+    // para algo que decide de quién es la cuenta. Yendo dentro de `data`, viaja
+    // firmado: nadie en el medio puede convertirlo en una adopción.
+    const data = { op: 'enroll', intent: 'join', dpub: device.publickey, token: qr.token || qr.sn, sn: qr.sn, commit, label, ts: Date.now() }
     const { signature } = await signWithDevice({ privateJwk: device.privateJwk, data })
 
     const enrolled = new Promise((resolve, reject) => {
@@ -225,8 +299,10 @@ export async function enrollService ({ qr, ns, dir, label, onCode, approveTimeou
     if (!v.ok) throw new Error('cert inválido: ' + v.reason)
     if (res.cert.iss !== qr.iss) throw new Error('cert firmado por una maestra distinta a la del QR')
 
+    // Reemplazo, no acumulación: el archivo se sobrescribe entero y la identidad
+    // anterior deja de existir en este agente.
     writeServiceIdentity(dir, { v: 1, ns, iss: qr.iss, proxy: qr.proxy, device, cert: res.cert, enrolledAt: Date.now() })
-    return { device, cert: res.cert, iss: qr.iss }
+    return { device, cert: res.cert, iss: qr.iss, replaced }
   } finally { client.close() }
 }