@dotrino/vault 0.34.0 → 0.36.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotrino/vault",
-  "version": "0.34.0",
+  "version": "0.36.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",
@@ -47,8 +47,8 @@
     "pairing"
   ],
   "peerDependencies": {
-    "@dotrino/identity": ">=0.58.0",
-    "@dotrino/proxy-client": ">=0.9.0"
+    "@dotrino/identity": ">=0.63.0",
+    "@dotrino/proxy-client": ">=0.13.0"
   },
   "license": "MIT",
   "repository": {

package/src/atrest.js

@@ -32,6 +32,13 @@
  *   · `/etc/machine-id` — identifica la instalación del sistema
  *   · un SALT aleatorio local (`atrest.salt`, 0600) — se genera la primera vez
  *
+ * **Y desde 0.55: de dónde sale la clave es CONFIGURABLE** (`kek.js`). Todo lo anterior
+ * describe el proveedor `machine`, que sigue siendo el de por defecto y el que se usa si
+ * no hay `atrest.json`. Con `provider: "command"` la clave la envuelve un KMS —el que
+ * sea, incluido el del cliente— y entonces **sí** deja de estar en este disco, que es la
+ * única forma de cerrar el párrafo de arriba. Cambiar de proveedor es `atrest rekey`;
+ * editar el JSON a mano está expresamente bloqueado porque dejaría los datos ilegibles.
+ *
  * `machineKey` **acepta** además una contraseña, pero **ningún llamante se la pasa** y no es
  * un descuido: los cinco (`src/store.js`, `src/secretsStore.js`, `src/vault.js`,
  * `src/threadStore.js`, `lib/src/service.js`) usan `atRestFor(dir)` a secas, porque el
@@ -47,6 +54,7 @@ import path from 'node:path'
 import os from 'node:os'
 import crypto from 'node:crypto'
 import { execFileSync } from 'node:child_process'
+import { resolveKey, mintKey, readConfig, writeConfig, probe, clearCache, configFromEnv, KekError, CONFIG_FILE, WRAPPED_FILE, MACHINE_FILE } from './kek.js'
 
 const MAGIC = 'DOTRINO-ATREST-v1'
 const SALT_FILE = 'atrest.salt'
@@ -124,13 +132,28 @@ export function decryptText (blob, key) {
   return Buffer.concat([d.update(Buffer.from(ct, 'base64')), d.final()]).toString('utf8')
 }
 
+/**
+ * La clave de ESTE directorio, por el proveedor que diga su `atrest.json`.
+ *
+ * Sin ese archivo el proveedor es `machine` y esto devuelve exactamente lo mismo que
+ * `machineKey(dir, password)` — o sea, una instalación existente no nota el cambio.
+ * Con `provider: "command"` la clave viene envuelta por un KMS (ver `kek.js`).
+ *
+ * **Usa esto, no `machineKey`, en cualquier código nuevo.** `machineKey` es ahora la
+ * implementación de UN proveedor; llamarla directamente se salta la costura y deja de
+ * funcionar en cuanto alguien configure otro.
+ */
+export function kekFor (dir, { password = '' } = {}) {
+  return resolveKey(dir, { password, machineKeyFn: machineKey, materialFn: machineMaterial, magic: MAGIC })
+}
+
 /**
  * Adaptador para `@dotrino/identity/node`: cifra/descifra el archivo entero de la identidad.
  * Si el archivo está en claro (instalación anterior), lo lee igual y lo deja cifrado en la
  * primera escritura — sin pedirle nada al usuario.
  */
 export function atRestFor (dir, { password = '' } = {}) {
-  const key = machineKey(dir, password)
+  const key = kekFor(dir, { password })
   return {
     encrypt: (text) => encryptText(text, key),
     decrypt: (text) => (isEncrypted(text) ? decryptText(text, key) : text)
@@ -154,4 +177,95 @@ export function migrateFile (file, key) {
   return 'migrado'
 }
 
-export default { machineKey, atRestFor, migrateFile, isEncrypted, encryptText, decryptText }
+/** Los archivos de este directorio que están cifrados por nosotros. */
+export function encryptedFilesIn (dir) {
+  let names = []
+  try { names = fs.readdirSync(dir) } catch (_) { return [] }
+  return names.filter((n) => {
+    if (n === CONFIG_FILE || n === WRAPPED_FILE || n === SALT_FILE || n === MACHINE_FILE) return false
+    try { return isEncrypted(fs.readFileSync(path.join(dir, n), 'utf8')) } catch (_) { return false }
+  })
+}
+
+/**
+ * CAMBIAR DE PROVEEDOR: descifra todo con la clave vieja y lo vuelve a cifrar con la nueva.
+ *
+ * Sin esto, cambiar `atrest.json` a mano deja el perfil ilegible — la maestra incluida — y
+ * no hay vuelta atrás. Por eso `kek.js` se niega a estrenar una DEK sobre datos que ya
+ * están cifrados: el único camino para cambiar de proveedor es este.
+ *
+ * Cómo se protege, por orden:
+ *   1. Se descifra TODO en memoria antes de escribir un solo byte. Si un archivo no abre,
+ *      no se ha tocado nada.
+ *   2. Se comprueba que lo recifrado se vuelve a leer igual, archivo por archivo.
+ *   3. Se deja una copia `.bak-rekey` de cada original.
+ *   4. La config nueva se escribe LA ÚLTIMA, cuando los datos ya están convertidos.
+ *
+ * Lo que NO se puede prometer, y se dice: renombrar varios archivos no es atómico. Si el
+ * proceso muere a mitad, queda una mezcla — y se sale de ella restaurando los
+ * `.bak-rekey`, que es justo lo que devuelve `backups`.
+ */
+export function rekeyDir (dir, newConfig, { password = '' } = {}) {
+  const oldCfg = readConfig(dir)
+  const nextCfg = { provider: 'machine', ...(newConfig || {}) }
+  const oldKey = kekFor(dir, { password })
+
+  // 1. Descifrar todo primero. Un fallo aquí no ha tocado nada.
+  const files = encryptedFilesIn(dir)
+  const plain = new Map()
+  for (const n of files) {
+    const p = path.join(dir, n)
+    try { plain.set(n, decryptText(fs.readFileSync(p, 'utf8'), oldKey)) } catch (e) {
+      throw new KekError('kek-rekey', `cannot decrypt ${n} with the current provider (${oldCfg.provider}): ${e.message}`)
+    }
+  }
+
+  // 2. La clave nueva, todavía sin escribir su envoltorio.
+  let newKey; let newBlob = null
+  if (nextCfg.provider === 'machine') {
+    newKey = machineKey(dir, password)
+  } else {
+    const minted = mintKey(nextCfg)
+    newKey = minted.dek; newBlob = minted.blob
+  }
+
+  // 3. Recifrar y comprobar, todo en memoria.
+  const out = new Map()
+  for (const [n, text] of plain) {
+    const blob = encryptText(text, newKey)
+    if (decryptText(blob, newKey) !== text) throw new KekError('kek-verify', `re-encryption check failed for ${n}: nothing was written`)
+    out.set(n, blob)
+  }
+
+  // 4. A disco. Copia de seguridad, temporal, renombrar.
+  const backups = []
+  for (const [n, blob] of out) {
+    const p = path.join(dir, n)
+    const bak = p + '.bak-rekey'
+    fs.copyFileSync(p, bak); backups.push(bak)
+    const tmp = p + '.rekey.tmp'
+    fs.writeFileSync(tmp, blob, { mode: 0o600 })
+    fs.renameSync(tmp, p)
+  }
+
+  // 5. El envoltorio nuevo y la config, al final: hasta aquí `atrest.json` seguía
+  //    describiendo la clave con la que YA no están cifrados los datos.
+  const wrappedPath = path.join(dir, WRAPPED_FILE)
+  if (newBlob) {
+    const tmp = wrappedPath + '.tmp'
+    fs.writeFileSync(tmp, newBlob.toString('base64') + '\n', { mode: 0o600 })
+    fs.renameSync(tmp, wrappedPath)
+  } else {
+    try { fs.unlinkSync(wrappedPath) } catch (_) { /* no lo había */ }
+  }
+  writeConfig(dir, nextCfg)
+  clearCache()
+
+  return { from: oldCfg.provider, to: nextCfg.provider, files: [...out.keys()], backups }
+}
+
+export default {
+  machineKey, kekFor, atRestFor, migrateFile, isEncrypted, encryptText, decryptText,
+  rekeyDir, encryptedFilesIn, readConfig, writeConfig, probe, KekError
+}
+export { readConfig, writeConfig, probe, configFromEnv, KekError, CONFIG_FILE, WRAPPED_FILE }

package/src/enroll.js

@@ -52,7 +52,7 @@ export const MSG_REVOKED = 'vault.revoked'
 export const MSG_ERROR = 'vault.error'
 
 /** Los scopes del cert se corresponden 1:1 con las capacidades del acta (§D7). */
-const SCOPE_TO_CAP = { 'vault:sign': 'sign', 'vault:store': 'store', 'vault:read': 'read', 'vault:admin': 'admin' }
+const SCOPE_TO_CAP = { 'vault:sign': 'sign', 'vault:store': 'store', 'vault:read': 'read', 'vault:admin': 'admin', 'vault:passwords': 'passwords' }
 export const scopeToCaps = (scope) =>
   (Array.isArray(scope) ? scope : [scope]).map((s) => SCOPE_TO_CAP[s]).filter(Boolean)
 

package/src/kek.js

@@ -0,0 +1,293 @@
+/**
+ * kek.js — DE DÓNDE SALE la clave que cifra el disco.
+ *
+ * Antes había UNA forma cableada dentro de `atrest.js`: derivarla del material de la
+ * máquina (`/etc/machine-id` + salt). Eso sigue siendo el proveedor por defecto y no
+ * cambia nada — pero ahora es *un* proveedor, no *el* proveedor.
+ *
+ * Por qué importa: el hueco grande frente a un KMS es que no hay raíz de confianza en
+ * hardware, y `machine-id` y el salt viven **en el mismo disco que los datos**, así que
+ * una instantánea del disco se lo lleva todo. Cerrarlo pide que la clave salga de otro
+ * sitio — una llave FIDO2, el TPM, un KMS — y cada uno de esos es un módulo pequeño
+ * SIEMPRE QUE exista esta costura. Sin ella, cada opción es una cirugía.
+ * Plan completo: `docs/llaves-de-hardware.md`.
+ *
+ * El contrato es deliberadamente mínimo: un proveedor devuelve 32 bytes para este
+ * directorio. Nada más. Quien los guarda, los envuelve o los pide por red es asunto suyo.
+ *
+ * Proveedores:
+ *   - `machine`  (por defecto)  lo de siempre: scrypt(material de la máquina + salt).
+ *   - `command`                 envuelve una DEK aleatoria llamando a un programa de
+ *                               fuera. Con eso vale CUALQUIER KMS (AWS, OpenBao, gcloud,
+ *                               un script propio) sin meter un SDK aquí dentro.
+ *
+ * Por qué `command` y no un cliente de KMS de verdad, que es la pregunta obvia:
+ *   1. **Todo esto es síncrono.** `atRestFor()` devuelve `{ encrypt, decrypt }` que usan
+ *      cinco módulos sin `await`. Un SDK sería asíncrono y habría que tocarlos todos;
+ *      `execFileSync` entra sin mover una línea de los llamantes.
+ *   2. **Cero dependencias nuevas** y ningún módulo nativo: el binario único sigue siendo
+ *      único.
+ *   3. Sirve para el KMS que ya tenga el cliente, que es justo lo que pide una empresa.
+ *
+ * REGLA QUE NO SE TOCA: si el proveedor configurado falla, esto **revienta**. No se cae
+ * al `machine` de reserva. Un repliegue silencioso convertiría «tumbo la red del vault»
+ * en «el vault se cifra con la clave débil», que es un agujero, no una comodidad.
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { execFileSync } from 'node:child_process'
+
+/** Config del proveedor. EN CLARO a propósito: hay que leerla para poder descifrar. */
+export const CONFIG_FILE = 'atrest.json'
+/** La DEK envuelta por el proveedor externo. Sin él, estos bytes no valen nada. */
+export const WRAPPED_FILE = 'atrest.kek'
+/** Huella de la máquina que escribió estos datos. Ver `assertSameMachine`. */
+export const MACHINE_FILE = 'atrest.machine'
+
+/**
+ * Los errores cruzan procesos (el daemon los enseña, la CLI los distingue), así que
+ * llevan `code` y se comprueban por ahí. Traducir la frase no debe romper a nadie.
+ */
+export class KekError extends Error {
+  constructor (code, message) { super(message); this.name = 'KekError'; this.code = code }
+}
+
+/** Caché por proceso: sin ella, cinco `atRestFor()` = cinco viajes al KMS en cada arranque. */
+const cache = new Map()
+export const clearCache = () => cache.clear()
+
+/**
+ * Config efectiva del directorio. Sin archivo, `machine` — que es lo que hacía siempre,
+ * así que una instalación existente no nota nada.
+ */
+export function readConfig (dir) {
+  let raw
+  try { raw = fs.readFileSync(path.join(dir, CONFIG_FILE), 'utf8') } catch (_) { return { provider: 'machine' } }
+  let cfg
+  try { cfg = JSON.parse(raw) } catch (e) {
+    throw new KekError('kek-config', `${CONFIG_FILE} is not valid JSON: ${e.message}`)
+  }
+  const provider = cfg?.provider || 'machine'
+  if (provider !== 'machine' && provider !== 'command') {
+    throw new KekError('kek-config', `unknown kek provider: ${provider}`)
+  }
+  return { ...cfg, provider }
+}
+
+export function writeConfig (dir, cfg) {
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 })
+  fs.writeFileSync(path.join(dir, CONFIG_FILE), JSON.stringify(cfg, null, 2) + '\n', { mode: 0o600 })
+}
+
+/**
+ * Llama al programa de fuera: base64 por la entrada, base64 por la salida. Ese contrato
+ * es a propósito el más tonto posible — cada CLI de KMS tiene sus manías con los binarios
+ * y sus flags, y se resuelven en un envoltorio de tres líneas en vez de aquí dentro.
+ */
+function runStep (step, input, what) {
+  if (!step || typeof step.cmd !== 'string' || !step.cmd) {
+    throw new KekError('kek-config', `kek provider "command": missing ${what}.cmd`)
+  }
+  let out
+  try {
+    out = execFileSync(step.cmd, Array.isArray(step.args) ? step.args : [], {
+      input: input.toString('base64'),
+      encoding: 'utf8',
+      timeout: Number(step.timeoutMs) || 15000,
+      maxBuffer: 1024 * 1024,
+      stdio: ['pipe', 'pipe', 'pipe']
+    })
+  } catch (e) {
+    // `stderr` es lo único que dice POR QUÉ (credenciales caducadas, sin permiso, sin red).
+    const detail = (e.stderr ? String(e.stderr).trim().split('\n').slice(-3).join(' / ') : '') || e.message
+    throw new KekError('kek-unavailable', `kek ${what} failed (${step.cmd}): ${detail}`)
+  }
+  const buf = Buffer.from(String(out).trim(), 'base64')
+  if (!buf.length) throw new KekError('kek-unavailable', `kek ${what} returned nothing (${step.cmd})`)
+  return buf
+}
+
+/** ¿Hay ya datos cifrados aquí? Si los hay, estrenar una DEK nueva los dejaría ilegibles. */
+function hasEncryptedData (dir, magic) {
+  let names = []
+  try { names = fs.readdirSync(dir) } catch (_) { return false }
+  for (const n of names) {
+    if (n === CONFIG_FILE || n === WRAPPED_FILE) continue
+    try {
+      const fd = fs.openSync(path.join(dir, n), 'r')
+      const head = Buffer.alloc(magic.length + 1)
+      const read = fs.readSync(fd, head, 0, head.length, 0)
+      fs.closeSync(fd)
+      if (read === head.length && head.toString('utf8') === magic + '.') return true
+    } catch (_) { /* directorios y archivos ilegibles: no cuentan */ }
+  }
+  return false
+}
+
+/**
+ * La DEK del proveedor `command`. Si ya está envuelta en el disco, se desenvuelve; si no,
+ * se estrena una — **pero solo si no hay nada cifrado todavía**.
+ *
+ * Ese portazo es el que evita el desastre silencioso: cambiar `atrest.json` a mano en un
+ * perfil que ya tiene datos generaría una DEK nueva y **dejaría todo lo anterior
+ * ilegible**, sin un solo aviso. Cambiar de proveedor es `atrest rekey`, no editar un JSON.
+ */
+function commandKey (dir, cfg, magic) {
+  const wrappedPath = path.join(dir, WRAPPED_FILE)
+  let wrapped = null
+  try { wrapped = Buffer.from(fs.readFileSync(wrappedPath, 'utf8').trim(), 'base64') } catch (_) {}
+
+  if (wrapped && wrapped.length) {
+    const dek = runStep(cfg.unwrap, wrapped, 'unwrap')
+    if (dek.length !== 32) throw new KekError('kek-unavailable', `kek unwrap returned ${dek.length} bytes, expected 32`)
+    return dek
+  }
+
+  if (hasEncryptedData(dir, magic)) {
+    throw new KekError('kek-needs-rekey',
+      `${CONFIG_FILE} says provider "command" but ${WRAPPED_FILE} is missing and this profile already holds encrypted data. ` +
+      'Switching providers requires re-encrypting: run `dotrino-vault atrest rekey`.')
+  }
+
+  // Estreno: envolver, COMPROBAR que se vuelve a abrir, y solo entonces escribir.
+  const dek = crypto.randomBytes(32)
+  const blob = runStep(cfg.wrap, dek, 'wrap')
+  const back = runStep(cfg.unwrap, blob, 'unwrap')
+  if (back.length !== dek.length || !crypto.timingSafeEqual(dek, back)) {
+    throw new KekError('kek-verify', 'kek wrap/unwrap round-trip mismatch: refusing to write a key that will not open')
+  }
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 })
+  const tmp = wrappedPath + '.tmp'
+  fs.writeFileSync(tmp, blob.toString('base64') + '\n', { mode: 0o600 })
+  fs.renameSync(tmp, wrappedPath)
+  return dek
+}
+
+/**
+ * ¿LOS ESCRIBIÓ ESTA MÁQUINA? Con el proveedor `machine` la clave sale del material de la
+ * máquina, así que en otra los datos no abren. Eso es lo que se quiere — copiar el archivo
+ * no basta— pero **cuando pasa por accidente, hay que decirlo**.
+ *
+ * El caso que lo hizo urgente: **un contenedor**. En una imagen Alpine no hay
+ * `/etc/machine-id`, así que el material se cae al `hostname`, que en Docker es el ID DEL
+ * CONTENEDOR y cambia en cada `docker run`. Con los datos en un volumen —o en un EBS— el
+ * ciclo normal (`docker rm` y volver a levantar, actualizar la imagen, mover el disco a
+ * otra instancia) dejaba la cuenta **ilegible para siempre**, y el único síntoma era un
+ * «unable to authenticate data» de la librería de cripto. Comprobado, no supuesto.
+ *
+ * Se guarda una HUELLA (no el material) de quién escribió aquí. Si no coincide y ya hay
+ * datos cifrados, se para y se explica, en vez de dejar al usuario delante de un error de
+ * AES preguntándose qué hizo mal.
+ */
+export function assertSameMachine (dir, material, hasData) {
+  const f = path.join(dir, MACHINE_FILE)
+  const huella = crypto.createHash('sha256').update('dotrino-atrest-machine\u0000' + material).digest('hex').slice(0, 32)
+  let previa = null
+  try { previa = fs.readFileSync(f, 'utf8').trim() } catch (_) {}
+
+  if (previa && previa !== huella && hasData) {
+    throw new KekError('kek-machine-changed',
+      'this data was written by a DIFFERENT machine and the key is derived from the machine itself, so it cannot be opened here. ' +
+      'In a container this is usually the container id changing on every run: the fix is to stop deriving the key from the machine — ' +
+      'give the profile a KMS provider (see docs/llaves-de-hardware.md) and re-create it, or restore this volume on the original host. ' +
+      'Nothing was modified.')
+  }
+  if (!previa) {
+    try {
+      fs.mkdirSync(dir, { recursive: true, mode: 0o700 })
+      fs.writeFileSync(f, huella + '\n', { mode: 0o600 })
+    } catch (_) { /* si no se puede escribir la huella, no se bloquea el arranque */ }
+  }
+}
+
+/**
+ * Los 32 bytes de este directorio, por el proveedor que diga su config.
+ * `machineKeyFn` la inyecta `atrest.js` para no importarnos en círculo.
+ */
+export function resolveKey (dir, { password = '', machineKeyFn, materialFn = null, magic, config = null } = {}) {
+  const cfg = config || readConfig(dir)
+  if (cfg.provider === 'machine') {
+    // La comprobación va ANTES de derivar: si la máquina cambió, el error tiene que
+    // explicar por qué, no salir de las tripas de AES tres llamadas más abajo.
+    if (typeof materialFn === 'function') {
+      try { assertSameMachine(dir, materialFn(), hasEncryptedData(dir, magic)) } catch (e) {
+        if (e instanceof KekError) throw e
+      }
+    }
+    return machineKeyFn(dir, password)
+  }
+
+  const ck = 'command ' + path.resolve(dir)
+  const hit = cache.get(ck)
+  if (hit) return hit
+  const dek = commandKey(dir, cfg, magic)
+  cache.set(ck, dek)
+  return dek
+}
+
+/**
+ * Estrena una DEK y la envuelve, SIN escribir nada. La usa `rekey`, que necesita la
+ * clave nueva en la mano mientras todavía está descifrando con la vieja — y que no puede
+ * permitirse pisar el `atrest.kek` de la vieja hasta el final.
+ */
+export function mintKey (cfg) {
+  if (cfg.provider !== 'command') throw new KekError('kek-config', 'mintKey only applies to the "command" provider')
+  const dek = crypto.randomBytes(32)
+  const blob = runStep(cfg.wrap, dek, 'wrap')
+  const back = runStep(cfg.unwrap, blob, 'unwrap')
+  if (back.length !== dek.length || !crypto.timingSafeEqual(dek, back)) {
+    throw new KekError('kek-verify', 'kek wrap/unwrap round-trip mismatch: refusing to use a key that will not open')
+  }
+  return { dek, blob }
+}
+
+/**
+ * EL PROVEEDOR QUE PIDE EL ENTORNO. Es lo que hace que un contenedor se pueda levantar con
+ * KMS sin entrar a escribir un JSON dentro: se pasan variables y ya.
+ *
+ *   · `DOTRINO_KEK_CMD`        un programa cualquiera que cumpla el contrato (base64 ⇄ base64)
+ *   · `DOTRINO_KMS_KEY_ID`     atajo para AWS: usa el `kms-aws.mjs` que viaja en la imagen
+ *
+ * Devuelve `null` si no hay nada configurado, que es el caso normal de un PC: ahí el
+ * proveedor sigue siendo `machine` y nada cambia.
+ *
+ * Solo se consulta al CREAR un perfil. Un perfil que ya existe manda con su `atrest.json`,
+ * porque cambiarle el proveedor por una variable de entorno lo dejaría ilegible — y eso se
+ * hace con `atrest rekey`, mirando, no con un `docker run` distinto por accidente.
+ */
+export function configFromEnv (env = process.env) {
+  if (env.DOTRINO_KEK_CMD) {
+    return {
+      provider: 'command',
+      label: env.DOTRINO_KEK_LABEL || env.DOTRINO_KEK_CMD,
+      wrap: { cmd: env.DOTRINO_KEK_CMD, args: ['wrap'] },
+      unwrap: { cmd: env.DOTRINO_KEK_CMD, args: ['unwrap'] }
+    }
+  }
+  if (env.DOTRINO_KMS_KEY_ID) {
+    const script = env.DOTRINO_KMS_SCRIPT || '/app/packaging/kms-aws.mjs'
+    return {
+      provider: 'command',
+      label: 'AWS KMS ' + env.DOTRINO_KMS_KEY_ID,
+      wrap: { cmd: process.execPath, args: [script, 'wrap'] },
+      unwrap: { cmd: process.execPath, args: [script, 'unwrap'] }
+    }
+  }
+  return null
+}
+
+/** Prueba el ida y vuelta del proveedor SIN tocar los datos. Para `atrest test`. */
+export function probe (dir, cfg = null) {
+  const c = cfg || readConfig(dir)
+  if (c.provider === 'machine') return { provider: 'machine', ok: true }
+  const sample = crypto.randomBytes(32)
+  const blob = runStep(c.wrap, sample, 'wrap')
+  const back = runStep(c.unwrap, blob, 'unwrap')
+  if (back.length !== sample.length || !crypto.timingSafeEqual(sample, back)) {
+    throw new KekError('kek-verify', 'kek wrap/unwrap round-trip mismatch')
+  }
+  return { provider: 'command', ok: true, label: c.label || c.wrap?.cmd || null, wrappedBytes: blob.length }
+}
+
+export default { readConfig, writeConfig, resolveKey, mintKey, probe, clearCache, assertSameMachine, configFromEnv, KekError, CONFIG_FILE, WRAPPED_FILE, MACHINE_FILE }

package/src/lock.js

@@ -0,0 +1,117 @@
+/**
+ * lock.js — UN SOLO PROCESO POR DIRECTORIO, también entre máquinas.
+ *
+ * Es la otra mitad de la invariante que pidió el dueño (la primera está en
+ * `src/keyowner.js`): cada proceso con su directorio, y **uno solo** dentro de cada uno.
+ *
+ * El candado que había miraba un pid: si el proceso seguía vivo, no arrancábamos. Sirve
+ * cuando las dos bóvedas son procesos del mismo sistema, y **no sirve para nada** en
+ * cuanto dejan de serlo:
+ *
+ *   · **Contenedores.** Cada uno tiene su espacio de pids. El segundo pregunta por el pid
+ *     del primero en el suyo, no lo encuentra y concluye que está muerto. Comprobado con
+ *     Docker: dos contenedores sobre el mismo volumen arrancaban los dos, sanos, con la
+ *     misma cuenta.
+ *   · **Un disco de red (EFS, NFS).** Peor todavía: son dos máquinas distintas. El pid del
+ *     otro host o no existe aquí, o existe y es un proceso que no tiene nada que ver.
+ *
+ * Y dos daemons sobre el mismo directorio no son dos bóvedas: son la misma corriendo dos
+ * veces. Cargan la misma maestra, se identifican igual en el proxio y sellan actas las dos
+ * como el mismo sellador — el caso que `acta-de-perfil.md` §2.4.1 llama «el master
+ * mintiendo» y del que dice que no hay defensa.
+ *
+ * LA IDEA: un archivo que se crea con `O_EXCL` (crear-o-fallar, atómico también en NFS)
+ * más un LATIDO. Quien lo tiene lo va tocando; quien llega lo mira:
+ *
+ *   · latido fresco  → hay alguien vivo, no arrancamos.
+ *   · latido viejo   → se cortó la luz, se le quita el candado y se sigue.
+ *
+ * El plazo no es un reloj compartido —eso no existe entre máquinas— sino la EDAD del
+ * archivo medida por quien mira. Un reloj desajustado alarga o acorta la espera, pero no
+ * rompe la exclusión: la exclusión la da `O_EXCL`, el latido solo decide cuándo se
+ * considera abandonado.
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import os from 'node:os'
+
+export const LOCK_FILE = 'vault.lock'
+/** Cada cuánto se toca el archivo. */
+export const HEARTBEAT_MS = 10_000
+/** Sin latido durante esto, se da por abandonado. Holgado a propósito: una máquina con
+ *  carga o un disco de red lento no pueden costar que otro le quite el candado a uno vivo. */
+export const STALE_MS = 60_000
+
+const quienSoy = () => ({ pid: process.pid, host: os.hostname(), desde: Date.now() })
+
+/**
+ * Toma el candado del directorio, o explica quién lo tiene y se rinde.
+ * @returns {{release:()=>void}}
+ */
+export function takeLock (dir, { staleMs = STALE_MS, heartbeatMs = HEARTBEAT_MS } = {}) {
+  const f = path.join(dir, LOCK_FILE)
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 })
+
+  const intentar = () => {
+    try {
+      // 'wx' = O_CREAT|O_EXCL: o lo creo yo, o alguien lo tiene. Esa atomicidad es lo
+      // único que aquí hace de exclusión.
+      const fd = fs.openSync(f, 'wx', 0o600)
+      fs.writeSync(fd, JSON.stringify(quienSoy()))
+      fs.closeSync(fd)
+      return true
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e
+      return false
+    }
+  }
+
+  if (!intentar()) {
+    const edad = (() => {
+      try { return Date.now() - fs.statSync(f).mtimeMs } catch (_) { return Infinity }
+    })()
+    let dueño = null
+    try { dueño = JSON.parse(fs.readFileSync(f, 'utf8')) } catch (_) {}
+
+    if (edad <= staleMs) {
+      const e = new Error(
+        `another vault is running on this data (host ${dueño?.host || '?'}, process ${dueño?.pid ?? '?'}, ` +
+        `last heartbeat ${Math.round(edad / 1000)}s ago)`
+      )
+      e.code = 'vault-locked'
+      e.owner = dueño
+      throw e
+    }
+    // Abandonado: se quita y se vuelve a intentar UNA vez. Si en ese hueco entró otro,
+    // pierde este — que es lo correcto: dos que ven el candado viejo a la vez, solo uno
+    // gana el `O_EXCL`.
+    try { fs.unlinkSync(f) } catch (_) {}
+    if (!intentar()) {
+      const e = new Error('another vault took this data first')
+      e.code = 'vault-locked'
+      throw e
+    }
+  }
+
+  const latido = setInterval(() => {
+    // `utimes` y no reescribir: tocar la fecha basta y no puede dejar el archivo a medias.
+    try { fs.utimesSync(f, new Date(), new Date()) } catch (_) {}
+  }, heartbeatMs)
+  latido.unref?.()
+
+  let suelto = false
+  const release = () => {
+    if (suelto) return
+    suelto = true
+    clearInterval(latido)
+    // Solo se borra SI SIGUE SIENDO MÍO. Si otro me lo quitó por viejo, borrarlo aquí le
+    // quitaría a él un candado que sí es suyo.
+    try {
+      const d = JSON.parse(fs.readFileSync(f, 'utf8'))
+      if (d?.pid === process.pid && d?.host === os.hostname()) fs.unlinkSync(f)
+    } catch (_) {}
+  }
+  return { release }
+}
+
+export default { takeLock, LOCK_FILE, STALE_MS, HEARTBEAT_MS }

package/src/protocol.js

@@ -86,6 +86,10 @@ export const MSG = Object.freeze({
   // contrapartida de administrar a distancia: sin esto, un enrolamiento remoto sería
   // invisible para el resto de tus dispositivos.
   ADMIN_EVENT: 'vault.admin.event',           // vault → todos: { body:{ev,deviceId,by,ts}, signature }
+  // RÉPLICAS: la principal empuja lo que hay que servir (el acta y los sobres, que van
+  // firmados de antes y no se pueden falsificar) y la réplica acusa hasta qué `seq` tiene.
+  REPLICA_PUSH: 'vault.replica.push',         // master → réplica: { body:{seq,acta,secrets,ts}, signature }
+  REPLICA_ACK: 'vault.replica.ack',           // réplica → master: { body:{seq,ts}, signature }
   ERROR: 'vault.error'                        // vault → dispositivo: { error }
 })
 
@@ -98,7 +102,15 @@ export const SCOPE = Object.freeze({
   // NO incluye cambiar permisos, traspasar el mando ni conceder `admin`: eso es el rol
   // de master y sigue siendo local. No se empareja — se concede desde el PC.
   ADMIN: 'vault:admin',
-  APPROVE: 'vault:approve' // aprobar pedidos de secretos (cajones con `approval`); se concede a mano, como admin
+  APPROVE: 'vault:approve', // aprobar pedidos de secretos (cajones con `approval`); se concede a mano, como admin
+  // El gestor de contraseñas: pedir credenciales de la bóveda, de a una y por dominio.
+  // Nunca lista la bóveda entera. Este SÍ se empareja (`pair --scope contrasenas`): es
+  // lo primero que hace la extensión, y no tendría sentido obligar a un segundo paso.
+  PASSWORDS: 'vault:passwords',
+  // SELLAR EL ACTA: la OTRA bóveda de esta cuenta. Con esto puede admitir aparatos y
+  // cambiar permisos si la principal se pierde — que es todo el punto del multivault. Como
+  // `admin`, no se empareja: se concede a mano (`caps <ID> +sella`).
+  SEALER: 'vault:sealer'
 })
 
 /**

package/src/service.js

@@ -458,8 +458,7 @@ export async function fetchSecrets ({ dir, ns, proxyUrl, masterPubkey, device, c
     // verdad llega cuando el aparato que aprueba firme — por esta misma conexión, que
     // sigue identificada. Se espera lo que dura el pedido; denegado o vencido es error.
     if (res.body?.op === 'secrets.pending' && res.body.ns === ns) {
-      const okPending = await verifyDeviceSig({ publickey: masterPubkey, data: res.body, signature: res.signature })
-      if (!okPending) throw new Error('invalid master signature on the pending reply')
+      await verifyResponder({ body: res.body, seal: res.seal, acta: res.acta, masterPubkey })
       try { onPending?.({ id: res.body.id, ns, exp: res.body.exp }) } catch (_) {}
       const until = typeof res.body.exp === 'number' ? Math.max(5000, res.body.exp - Date.now() + 5000) : approvalTimeoutMs
       res = await waitForMsg(client, (p) => (p.type === MSG.SECRETS_RESULT && p.body?.op === 'secrets.result') || p.type === MSG.ERROR, Math.min(until, approvalTimeoutMs))
@@ -467,14 +466,20 @@ export async function fetchSecrets ({ dir, ns, proxyUrl, masterPubkey, device, c
       if (res.type === MSG.ERROR) throw new Error(res.error)
     }
 
-    // Autenticidad: el cuerpo viene firmado por la MAESTRA pineada.
+    // AUTENTICIDAD: la firma NO es de la maestra. El acta dice qué llave vale para esto
+    // (`sealPub`, buscada por `seq`), que es la misma regla que ya gobierna los sobres.
+    // La maestra solo sella el acta y reenvuelve; servir no es cosa suya, y por eso puede
+    // quedarse cerrada.
     const body = res.body
     if (!body || body.op !== 'secrets.result' || body.ns !== ns) throw new Error('malformed secrets reply')
     if (typeof body.ts !== 'number' || Math.abs(Date.now() - body.ts) > FRESH_WINDOW_MS) throw new Error('stale secrets reply')
-    const ok = await verifyDeviceSig({ publickey: masterPubkey, data: body, signature: res.signature })
-    if (!ok) throw new Error('invalid master signature on the secrets reply')
 
+    // Se abre ANTES de comprobar la firma, y no es un descuido: el sobre de fuera va
+    // sellado a la efímera que acabamos de estrenar, así que abrirlo no prueba nada ni
+    // confía en nadie — solo saca el acta con la que SÍ se comprueba. Nada de lo que hay
+    // dentro se usa hasta después de verificar.
     const payload = await openSealed({ privateKey: eph.privateKey, enc: body.enc })
+    await verifyResponder({ body, seal: res.seal, acta: payload?.acta, masterPubkey })
 
     // DOS CAPAS DE SOBRE, y hacen cosas distintas:
     //   · la de fuera (`ek` efímera, recién abierta) tapa el TRAMO — el proxio no ve
@@ -499,6 +504,40 @@ export async function fetchSecrets ({ dir, ns, proxyUrl, masterPubkey, device, c
  * omitido: silenciarlo convertiría una rotación mal sellada en «el servicio sigue
  * con el valor viejo y nadie se entera», que es el peor modo de fallo de todo esto.
  */
+/**
+ * ¿QUIÉN CONTESTÓ, Y PUEDE? La misma regla que gobierna los sobres, aplicada al
+ * transporte: **el acta dice qué llave firma qué**.
+ *
+ * La maestra no entra aquí. Sus dos trabajos son sellar el acta y reenvolver los sobres
+ * de todos los aparatos; servir una petición no es ninguno de los dos, así que exigir su
+ * firma la obligaba a estar despierta todo el tiempo — y de paso hacía imposible que
+ * sirviera nadie más.
+ *
+ * Lo que se comprueba, en orden:
+ *   1. el acta que llega va firmada por la maestra que este agente lleva pineada desde
+ *      que se enroló (o por la que aquella nombró al traspasar);
+ *   2. la firma del cuerpo cuadra con la llave de sellado que ESA acta nombra para el
+ *      `seq` con el que se firmó.
+ *
+ * Sin el paso 1 el paso 2 no vale nada: un acta cualquiera nombraría la llave que
+ * quisiera.
+ */
+export async function verifyResponder ({ body, seal, acta, masterPubkey }) {
+  if (!seal?.sig || typeof seal.seq !== 'number') {
+    throw new Error('the reply carries no sealing signature: this vault is too old to serve (update it)')
+  }
+  if (!acta) throw new Error('the reply carries no record: cannot tell which key was allowed to sign it')
+  if (acta.sealedBy !== masterPubkey) {
+    throw new Error('the record was not sealed by the master this agent knows: refusing the reply')
+  }
+  if (!(await verifyActa({ acta })).ok) throw new Error('the record does not verify')
+  const pub = sealKeyAt(acta, seal.seq)
+  if (!pub) throw new Error(`the record names no sealing key for #${seal.seq}`)
+  if (!(await verifyDeviceSig({ publickey: pub, data: body, signature: seal.sig }))) {
+    throw new Error('the reply signature does not check out against the key the record names')
+  }
+}
+
 /**
  * ¿SALIÓ ESTE SOBRE DE MI BÓVEDA? (§8.8 de `dotrino-vault/docs/secretos-sellados.md`)
  *