@dotrino/vault 0.84.0 → 0.86.0

package/README.md

@@ -1,42 +1,42 @@
 # @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`).
+La bóveda de Dotrino como librería. **El mismo núcleo que el binario `dotrino-vault`**
+(`src/core/vault.js`) corre en el navegador: la pestaña de `vault.dotrino.com` y la extensión
+del gestor de contraseñas son la misma bóveda que el demonio, con el disco en IndexedDB
+(regla de las tres versiones, `docs/three-versions.md` del repo).
 
-Pensado para que **cualquier app** del ecosistema (no solo la terminal) pueda ofrecer
-"usar este dispositivo como bóveda".
+Incluye además el cliente de SERVICIO (Node): un proyecto se enrola una vez y jala sus
+credenciales del vault en vez del `.env` (abajo).
 
-## Uso
+## La bóveda en el navegador
 
 ```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()
+import { startBrowserVault } from '@dotrino/vault/browser'
+
+// `core`: el núcleo de identidad ya abierto (`createIdentityCore` de @dotrino/identity),
+// el del iframe de id.dotrino.com o el de la extensión.
+const vault = await startBrowserVault({ core, onPendingChange: () => pintar(vault.listPending()) })
+
+// Emparejar: abrir una invitación y aprobar TECLEANDO el código que muestra el aparato.
+const { qr } = await vault.startPairing({ label: 'mi-agente' })
+// await vault.approve(deviceId, codigoTipeado)
+
+await vault.close()
 ```
 
+Devuelve el mismo objeto que el núcleo del binario (cajones, aprobaciones, inicios de
+sesión, bloqueados, revocar…) más `approve(deviceId, code)`, `reject`, `listMachines`,
+`revokeDevice(sub)` y `close()`. La consola que corre en ese mismo navegador la administra
+con el protocolo de la consola remota, por un camino local (`core.setSelfVault`).
+
+Opciones: `proxyUrl`, `makeClient` (quién crea el cliente del proxio; obligatorio en un
+contexto sin `import()`), `opaque` (el servidor de OPAQUE si el del paquete no carga),
+`servePasswords: false` (las contraseñas las atiende quien monta la bóveda, con la política
+del núcleo: `passwordsNeedApproval`, `approvePasswordRequest`), `legacyLogins`, `log`.
+
+`startDeviceVault(identity, opts)` (el mostrador anterior, la mitad del protocolo) se
+conserva solo para `dotrino-passmanager serve` y desaparecerá.
+
 ## Credenciales del vault en vez del `.env` (Node)
 
 La cara "dotenv" del paquete: **cualquier proyecto Node** jala sus credenciales del
@@ -315,7 +315,7 @@ quien llama. Lo preferible es instalar los servicios como usuario, que no necesi
 
 ## API
 
-`startDeviceVault(identity, { proxyUrl? }) → Promise<handle>`
+`startDeviceVault(identity, { proxyUrl? }) → Promise<handle>` — el mostrador anterior, solo para `dotrino-passmanager serve`. Para una bóveda de navegador, `startBrowserVault` (arriba).
 
 - `startPairing({ scope?, ttlMs?, label?, mode?, account? }) → { qr, expiresInMs }`
 - `stopPairing(token)`

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dotrino/vault",
-  "version": "0.84.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'`).",
+  "version": "0.86.0",
+  "description": "La bóveda de Dotrino como librería: el MISMO núcleo que el binario corriendo en el navegador (`@dotrino/vault/browser`), el mostrador de emparejamiento y 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",
@@ -13,6 +13,9 @@
     ".": {
       "import": "./src/index.js"
     },
+    "./browser": {
+      "import": "./src/browser.js"
+    },
     "./service": {
       "import": "./src/service.js"
     },
@@ -59,8 +62,9 @@
     "pairing"
   ],
   "peerDependencies": {
-    "@dotrino/identity": ">=0.111.0",
-    "@dotrino/proxy-client": ">=0.23.1"
+    "@dotrino/identity": ">=0.116.0",
+    "@dotrino/proxy-client": ">=0.23.1",
+    "@dotrino/store": ">=0.11.0"
   },
   "license": "MIT",
   "repository": {
@@ -76,7 +80,15 @@
     "type-check": "tsc --noEmit"
   },
   "dependencies": {
+    "@dotrino/compat": "0.4.0",
     "@dotrino/opaque": "0.1.0",
+    "@dotrino/passmanager": "0.17.0",
+    "@dotrino/roadmap": "0.4.13",
     "@dotrino/update": "0.5.1"
+  },
+  "peerDependenciesMeta": {
+    "@dotrino/store": {
+      "optional": true
+    }
   }
 }

package/src/browser.js

@@ -0,0 +1,167 @@
+/**
+ * LA BÓVEDA EN EL NAVEGADOR: la pestaña (`vault.dotrino.com`, dentro del iframe de
+ * identidad) y la extensión del gestor de contraseñas corren el MISMO núcleo que el
+ * binario (`./core/vault.js`). Lo único distinto es lo que pone la plataforma:
+ *
+ *   · el disco es IndexedDB cifrado (`./core/browserDisk.js`), uno por perfil;
+ *   · la identidad es la que ya tiene abierta la pestaña o la extensión;
+ *   · no hay `/proc` ni socket de archivo: lo que declara quien pide se queda como
+ *     declarado, y los servicios de la misma máquina llegan por el proxio.
+ *
+ * Y lo que sí suma: la consola que corre en este mismo navegador administra esta bóveda
+ * por un canal local (`core.setSelfVault`), con el MISMO protocolo y las mismas
+ * comprobaciones que contra el binario.
+ *
+ * Lo que el binario tiene y el navegador no, por su contexto: actualizarse solo (la pestaña
+ * se sirve siempre al día y la extensión la actualiza su tienda), las llaves de hardware
+ * como puerta del perfil y el candado que cifra la maestra con la contraseña. Ver
+ * `docs/three-versions.md`.
+ */
+import { startVault } from './core/vault.js'
+import { openBrowserDisk } from './core/browserDisk.js'
+import { LIB_VERSION } from './core/libVersion.js'
+import { IdentityFacade } from '@dotrino/identity/facade'
+import { memberScopes } from '@dotrino/identity/acta'
+import { deviceIdOf } from './enroll.js'
+
+const DEFAULT_PROXY = 'wss://proxy.dotrino.com'
+/** Cada cuánto se rehace el papel con el que la consola local administra esta bóveda. */
+const SELF_CERT_EVERY_MS = 60_000
+
+/**
+ * @param {object} opts
+ * @param {object} opts.core  el núcleo de identidad ya abierto (`createIdentityCore`)
+ * @param {string} [opts.proxyUrl]
+ * @param {Function} [opts.makeClient]  quién crea el cliente del proxio. La extensión lo
+ *   pasa siempre: un service worker no puede hacer `import()`.
+ * @param {Function} [opts.legacyLogins]  los inicios de sesión que esta pestaña guardaba
+ *   antes de correr el núcleo (`{ state, drop }` o `null`). Se traen UNA vez.
+ * @param {Function} [opts.onPendingChange]  un aparato espera aprobación, o dejó de esperar
+ * @param {Function} [opts.onAdopted]
+ * @param {Function} [opts.log]
+ * @param {object} [opts.opaque]  el servidor de OPAQUE, si el del paquete no se puede cargar aquí
+ *   (la extensión: su CSP no deja WASM en la página de la bóveda).
+ * @param {boolean} [opts.servePasswords]  `false` si las contraseñas las atiende quien monta
+ *   la bóveda (la extensión, con su worker); decide con `passwordsNeedApproval`/`approvePasswordRequest`.
+ * @param {Function} [opts.openDisk]  `(name) => disk`. Solo para las pruebas (Node no tiene
+ *   IndexedDB); por defecto, `openBrowserDisk`.
+ */
+export async function startBrowserVault ({ core, proxyUrl = DEFAULT_PROXY, makeClient = null, legacyLogins = null, onPendingChange = () => {}, onAdopted = () => {}, log = console.log, openDisk = openBrowserDisk, opaque = null, servePasswords = true } = {}) {
+  if (!core?.handlers) throw Object.assign(new Error('startBrowserVault: the identity core is required'), { code: 'no-identity' })
+  const identity = new IdentityFacade(core)
+  if (!identity.me?.publickey) throw Object.assign(new Error('no identity: create or unlock your profile before using this browser as a vault'), { code: 'no-identity' })
+  const { id: pid } = await identity.currentProfile()
+  if (!pid) throw Object.assign(new Error('no profile: the vault belongs to an account'), { code: 'no-profile' })
+
+  const disk = await openDisk(`dotrino-vault.${pid}`)
+
+  // LOS INICIOS DE SESIÓN QUE YA HABÍA. Antes de correr el núcleo, la pestaña guardaba los
+  // usuarios y contraseñas de la cuenta en su propio almacén. Se traen una vez —si el disco
+  // ya tiene los suyos, mandan esos— y después se borra lo viejo: dos copias acaban diciendo
+  // cosas distintas.
+  if (legacyLogins && !disk.exists('logins.json')) {
+    const old = await legacyLogins()
+    if (old?.state) {
+      disk.write('logins.json', disk.atRest.encrypt(JSON.stringify(old.state)))
+      await disk.flush()
+      try { await old.drop?.() } catch (_) {}
+      log('[vault] password logins moved into the vault storage')
+    }
+  }
+
+  const avisar = () => { try { onPendingChange() } catch (_) {} }
+  const vault = await startVault({
+    platform: {
+      disk,
+      product: 'vault',
+      version: LIB_VERSION,
+      openIdentity: async () => identity,
+      makeClient,
+      noticeGroupMs: 3000,
+      ...(opaque ? { opaque } : {}),
+      servePasswords
+    },
+    proxyUrl,
+    log,
+    isLocked: () => !!core.masterLocked,
+    // El navegador no tiene la contraseña del perfil con la que el binario cierra la copia
+    // de recuperación: se cierra con la llave de este almacén, y el núcleo lo dice.
+    hasPassword: () => false,
+    onEnrollChallenge: avisar,
+    onAdopted: (info) => { try { onAdopted(info) } catch (_) {} }
+  })
+
+  // EL PAPEL CON EL QUE LA CONSOLA DE ESTE NAVEGADOR ADMINISTRA ESTA BÓVEDA: la llave del
+  // perfil firmándose a sí misma con lo que el acta le deja hoy. Se rehace cada minuto
+  // porque el acta cambia (un permiso que te quitas, un sellado nuevo).
+  const master = identity.me.publickey
+  const selfCert = async () => {
+    const acta = (await identity.profileActa().catch(() => null))?.acta || null
+    if (!acta) return null
+    const scope = memberScopes(acta, master)
+    if (!scope.length) return null
+    return (await identity.signDelegation(master, scope, { label: 'self' })).cert
+  }
+  /**
+   * EL DUEÑO EN SU MÁQUINA ADMINISTRA. En el binario eso es la TUI, que no necesita ningún
+   * permiso del acta; aquí la consola habla el protocolo de la consola remota, que exige
+   * `admin`. Así que la llave de la cuenta se lo da a sí misma, una vez y a la vista en el
+   * acta: es verdad que este navegador administra la cuenta. `aprueba` NO, a propósito: con
+   * él los servicios pasarían a esperar el visto bueno de una pestaña que puede no estar.
+   */
+  const asegurarAdmin = async () => {
+    if (core.masterLocked) return
+    const acta = (await identity.profileActa().catch(() => null))?.acta || null
+    const yo = (acta?.members || []).find((m) => m.pub === master)
+    if (!yo || (yo.caps || []).includes('admin')) return
+    if (!(await identity.isMaster().catch(() => false))) return
+    await identity.setCaps(master, [...yo.caps, 'admin'])
+    log('[vault] this browser administers the account: admin added to its own key')
+  }
+  const open = (onReply) => vault.localChannel(onReply)
+  const presentar = async () => {
+    try {
+      await asegurarAdmin()
+      const cert = await selfCert()
+      core.setSelfVault?.(cert ? { cert, proxy: proxyUrl, open } : null)
+    } catch (e) { log('[vault] the console in this browser cannot administer this vault yet: ' + (e?.message || e)) }
+  }
+  await presentar()
+  const refresco = setInterval(presentar, SELF_CERT_EVERY_MS)
+
+  return {
+    ...vault,
+    iss: master,
+    proxy: proxyUrl,
+    disk,
+    /** Aprueba TIPEANDO el código que muestra el aparato (el núcleo comprueba el compromiso). */
+    approve: async (_deviceId, code) => { try { return await vault.approveDevice(code) } finally { avisar() } },
+    reject: (deviceId) => { try { return vault.rejectDevice(deviceId) } finally { avisar() } },
+    /**
+     * Las máquinas con papel de firma de esta cuenta (excluye los navegadores enrolados con
+     * etiqueta `cli`, que no atienden pedidos). Se queda el papel del acta más nueva.
+     */
+    async listMachines () {
+      const { issued } = await identity.listDelegations()
+      const bySub = new Map()
+      for (const x of (issued || [])) {
+        if (!x.sub || x.revokedAt) continue
+        if (!Array.isArray(x.scope) || !x.scope.includes('vault:sign')) continue
+        if (!x.label || x.label === 'cli' || x.label === 'self') continue
+        if (!bySub.has(x.sub) || (x.seq || 0) > (bySub.get(x.sub).seq || 0)) bySub.set(x.sub, x)
+      }
+      return Promise.all([...bySub.values()].map(async (x) => ({ ...x, deviceId: await deviceIdOf(x.sub) })))
+    },
+    revokeDevice: (sub) => vault.revokeDevice({ sub }),
+    revoke: (nonce) => vault.revokeDevice(nonce),
+    async close () {
+      clearInterval(refresco)
+      try { core.setSelfVault?.(null) } catch (_) {}
+      vault.close()
+      try { await disk.flush() } catch (e) { log('[vault] some changes could not be saved: ' + (e?.message || e)) }
+      disk.close()
+    }
+  }
+}
+
+export default { startBrowserVault }

package/src/core/approvals.js

@@ -0,0 +1,204 @@
+/**
+ * PEDIDOS DE APROBACIÓN Y CONCESIONES (puro: sin red ni disco).
+ *
+ * Un aparato marcado con `approval on` no recibe claves privadas solo por tener el cert: el
+ * vault apunta el pedido, avisa a los aparatos con `approve` (el teléfono), y solo su firma
+ * libera los secretos. Lo que nadie aprueba vence solo a los 5 min.
+ *
+ * Lo que se guarda de cada pedido es lo justo para contestar después: el cajón, quién pide,
+ * su llave efímera `ek` (a la que se sella la respuesta) y **qué comando está corriendo y
+ * desde dónde**. Nunca un valor.
+ *
+ * LA CONCESIÓN POR COMANDO (dueño, 2026-09-11). Antes no había ventana: cada petición era un
+ * pedido, y para un servicio bien hecho eso era una por arranque. Dejó de alcanzar en cuanto
+ * los pedidos empezaron a decir QUÉ comando piden: si el dueño ya dijo que sí a ese comando
+ * exacto desde esa carpeta exacta, volver a timbrarle por lo mismo es ruido. Así que aprobar
+ * concede **una hora, contada desde el último uso** — o sea que un servicio que sigue
+ * pidiendo la mantiene viva indefinidamente, que es lo que se pidió. Lo que la corta: que
+ * cambie el comando o la carpeta (otra huella, otro pedido), una hora entera sin usarla,
+ * revocarla a mano, o reiniciar la bóveda (viven en memoria y no se escriben en ningún
+ * sitio: un permiso que sobrevive a un reinicio es un permiso que nadie recuerda haber dado).
+ *
+ * SIN COMANDO NO HAY CONCESIÓN. Un pedido que no dice qué está corriendo —porque vino de
+ * otra máquina por el proxio, donde mandarlo en claro filtraría las rutas del dueño— no
+ * tiene huella con la que emparejarse, y entonces se pide aprobación cada vez. No se
+ * inventa una huella «vacía» que valdría para todo: eso sería exactamente un repliegue.
+ *
+ * Y PARA EL GESTOR DE CONTRASEÑAS ESO ES LO QUE SE QUIERE, no una carencia que arreglar
+ * (dueño, 2026-09-11: «para el gestor de contraseñas es perfecto»). La extensión es un
+ * navegador hablando por el proxio, no un proceso con línea de comandos, así que nunca va a
+ * traer huella — y así cada acceso a una credencial vuelve a pasar por tu mano, que es la
+ * protección por la que esto existe. No se le busque un sustituto del comando para que
+ * entre en la ventana.
+ */
+import { commandFingerprint } from '../procContext.js'
+
+const rnd = () => [...crypto.getRandomValues(new Uint8Array(8))].map((b) => b.toString(16).padStart(2, '0')).join('')
+
+/** Separador de la llave compuesta. Es un byte que no puede aparecer en un cajón ni en una pubkey. */
+const SEP = String.fromCharCode(0)
+
+/**
+ * LO QUE DURA UN PEDIDO SIN CONTESTAR, y por qué son dos números y no uno.
+ *
+ * CINCO MINUTOS es lo correcto para un COMANDO: hay un proceso bloqueado esperando, y
+ * aprobar media hora más tarde entregaría claves a algo cuyo contexto ya cambió — la
+ * carpeta, el comando o la máquina pueden ser otros. Que caduque rápido es la protección.
+ *
+ * UNA ACTUALIZACIÓN no se parece en nada (dueño, 2026-09-20): no hay nadie esperando, y
+ * caducar no protege de nada — solo significa que mañana se vuelve a pedir y se vuelve a
+ * perder, porque mirar el teléfono puede tardar horas. Un pedido que nunca llega a tiempo
+ * es una función que no existe.
+ *
+ * Por eso el plazo es DEL PEDIDO y no de la mesa. Quien pide dice cuánto aguanta lo suyo.
+ */
+export const PENDING_TTL_MS = 5 * 60 * 1000
+/**
+ * Y el de una actualización: un día. Cuadra con que la bóveda mire una vez al día — pedir
+ * otra vez reemplaza el pedido anterior del mismo cajón y aparato, así que siempre hay
+ * exactamente uno vivo, en vez de una cola de avisos caducados.
+ */
+export const UPDATE_TTL_MS = 24 * 60 * 60 * 1000
+/** Lo que dura una concesión SIN USARSE. Cada uso la vuelve a poner en una hora. */
+export const GRANT_TTL_MS = 60 * 60 * 1000
+
+export function createApprovals ({ now = Date.now, pendingTtlMs = PENDING_TTL_MS } = {}) {
+  /** id → { id, ns, device, deviceId, label, ek, ctx, ts, exp, from } */
+  const pending = new Map()
+  /**
+   * EL CONTEXTO VA EN LA LISTA, Y QUIEN LA SACA POR LA RED LO ENVUELVE.
+   *
+   * `ctx` es el comando y el path del dueño: por el mostrador local y en la consola de su
+   * propia máquina se enseña tal cual, pero al teléfono viaja por el proxio y ahí va dentro
+   * de un sobre (`handleApproval`). Si mañana aparece otro sitio que publique esta lista,
+   * esto es lo que hay que recordar.
+   */
+  // `kind` dice QUÉ se pide: `read` (llevarse las claves, lo de siempre) o `write` (guardar
+  // variables). La pantalla del teléfono no puede decir «pide tus claves» a una escritura.
+  const publicOf = (p) => ({ id: p.id, ns: p.ns, kind: p.kind, deviceId: p.deviceId, label: p.label, ts: p.ts, exp: p.exp, ctx: p.ctx || null })
+
+  return {
+    /** Apunta un pedido. Uno por cajón y aparato: pedir otra vez reemplaza al anterior. */
+    /**
+     * `from` es POR DÓNDE ENTRÓ la pregunta. La respuesta llega más tarde —cuando alguien
+     * apruebe— y tiene que volver por el mismo sitio: desde que la bóveda atiende también
+     * por un socket local, mandarla siempre por el proxio la dejaba en el vacío.
+     */
+    request ({ ns, device, deviceId, label = '', ek, ctx = null, from = null, ttlMs = null, kind = 'read' }) {
+      // Pedir las claves otra vez reemplaza al pedido anterior: es la misma pregunta. Una
+      // ESCRITURA no: cada una lleva su propio valor, y reemplazarla tiraría la anterior
+      // sin que nadie dijera que no.
+      if (kind !== 'write') for (const [id, p] of pending) if (p.kind !== 'write' && p.ns === ns && p.device === device) pending.delete(id)
+      const ts = now()
+      // `ttlMs` lo pone quien pide: una actualización aguanta un día y un comando cinco
+      // minutos, y la mesa no tiene por qué saber cuál es cuál (ver `PENDING_TTL_MS`).
+      const p = { id: rnd(), ns, kind, device, deviceId, label, ek, ctx, ts, exp: ts + (ttlMs || pendingTtlMs), from }
+      pending.set(p.id, p)
+      return publicOf(p)
+    },
+    /** Los pedidos vivos, sin la `ek` (no hace falta fuera de aquí). */
+    list () { this.sweep(); return [...pending.values()].map(publicOf) },
+    /** Saca un pedido para resolverlo (aprobar o denegar). `null` si no existe o venció. */
+    take (id) {
+      this.sweep()
+      const p = pending.get(id)
+      if (p) pending.delete(id)
+      return p || null
+    },
+    /** Tira lo vencido; devuelve los pedidos que vencieron, para anotarlos. */
+    sweep () {
+      const t = now(); const gone = []
+      for (const [id, p] of pending) if (p.exp <= t) { pending.delete(id); gone.push(publicOf(p)) }
+      return gone
+    }
+  }
+}
+
+/**
+ * LAS CONCESIONES VIVAS: «este comando, desde esta carpeta, ya está aprobado».
+ *
+ * La llave es cajón + aparato + huella del comando. Nada de esto se escribe en disco.
+ */
+export function createGrants ({ now = Date.now, ttlMs = GRANT_TTL_MS } = {}) {
+  /** key → { id, ns, device, deviceId, fp, ctx, by, grantedAt, lastAt, exp, uses } */
+  const grants = new Map()
+  const keyOf = (ns, device, fp) => ns + SEP + device + SEP + fp
+  const publicOf = (g) => ({
+    id: g.id, ns: g.ns, deviceId: g.deviceId, fp: g.fp, ctx: g.ctx,
+    by: g.by, grantedAt: g.grantedAt, lastAt: g.lastAt, exp: g.exp, uses: g.uses
+  })
+
+  const api = {
+    /**
+     * Anota que este comando quedó aprobado. Devuelve la concesión, o `null` si el pedido no
+     * traía comando: sin huella no hay nada que recordar, y el próximo pedido volverá a
+     * timbrar. Que eso se diga en el log es cosa de quien llama.
+     */
+    grant ({ ns, device, deviceId = null, ctx = null, by = null }) {
+      const fp = commandFingerprint(ctx)
+      if (!fp) return null
+      const t = now()
+      const g = { id: rnd(), ns, device, deviceId, fp, ctx, by, grantedAt: t, lastAt: t, exp: t + ttlMs, uses: 0 }
+      grants.set(keyOf(ns, device, fp), g)
+      return publicOf(g)
+    },
+    /**
+     * ¿Está este comando ya aprobado? Si lo está, **la concesión se estira**: la hora cuenta
+     * desde el último uso, no desde que se dio. Devuelve la concesión (ya refrescada) o `null`.
+     */
+    allows ({ ns, device, ctx }) {
+      api.sweep()
+      const fp = commandFingerprint(ctx)
+      if (!fp) return null
+      const g = grants.get(keyOf(ns, device, fp))
+      if (!g) return null
+      const t = now()
+      g.lastAt = t
+      g.exp = t + ttlMs
+      g.uses += 1
+      return publicOf(g)
+    },
+    /** Las concesiones vivas. */
+    list () { api.sweep(); return [...grants.values()].map(publicOf) },
+    /** Corta una por su id. `true` si existía. */
+    revoke (id) {
+      for (const [k, g] of grants) if (g.id === id) { grants.delete(k); return true }
+      return false
+    },
+    /** Corta todas, o las de un cajón / un aparato. Devuelve cuántas se fueron. */
+    revokeAll ({ ns = null, device = null } = {}) {
+      let n = 0
+      for (const [k, g] of grants) {
+        if (ns && g.ns !== ns) continue
+        if (device && g.device !== device) continue
+        grants.delete(k); n++
+      }
+      return n
+    },
+    /** Tira lo vencido; devuelve lo que se fue, para anotarlo. */
+    sweep () {
+      const t = now(); const gone = []
+      for (const [k, g] of grants) if (g.exp <= t) { grants.delete(k); gone.push(publicOf(g)) }
+      return gone
+    }
+  }
+  return api
+}
+
+/**
+ * ¿SE LLEVÓ UNA LIMPIEZA AL ÚLTIMO QUE APROBABA? Devuelve los aprobadores que se fueron si
+ * antes había alguno y ahora no queda ninguno; si no, una lista vacía.
+ *
+ * Una cuenta SIN aprobadores puede ser legítima (todo desatendido, se actualiza sola), así
+ * que el aviso no es «no hay aprobadores»: es «LOS HABÍA y acabas de perder el último».
+ *
+ * @param {string[]} before  llaves con `approve` antes
+ * @param {string[]} after   llaves con `approve` después
+ * @param {string[]} removed llaves que salieron del acta
+ */
+export function lastApproverGone (before, after, removed) {
+  if (!before.length || after.length) return []
+  return removed.filter((pub) => before.includes(pub))
+}
+
+export default { createApprovals, createGrants, lastApproverGone, PENDING_TTL_MS, UPDATE_TTL_MS, GRANT_TTL_MS }

package/src/core/blocked.js

@@ -0,0 +1,68 @@
+/**
+ * LOS APARATOS BLOQUEADOS: la lista que un aprobador decide y solo la bóveda deshace.
+ *
+ * Un agente (la terminal, por ahora) reporta un INCIDENTE cuando un aparato de la cuenta se
+ * equivoca de clave tres veces seguidas. El aprobador lo ve en su teléfono y elige: bloquear
+ * o ignorar. Bloquear NO es revocar: el aparato sigue en el acta —no hace falta la maestra, y
+ * la bóveda vive cerrada—, pero la bóveda deja de atenderle y los agentes, que reciben esta
+ * lista con el acta, le cierran la puerta. Se deshace aquí (`dotrino-vault unblock <ID>`) o
+ * desde la consola de administración; un aprobador solo bloquea.
+ *
+ * Va en el disco cifrado en reposo como las contraseñas: es parte del mapa de la cuenta.
+ * Se carga UNA vez: un archivo que existe y no se puede leer NO es «nadie bloqueado» — se
+ * lanza, y la bóveda no arranca con una lista que no puede saber.
+ */
+
+export const BLOCKED_FILE = 'blocked.json'
+
+const fail = (code, message) => Object.assign(new Error(message), { code })
+
+/**
+ * @param {{ disk: object, now?: () => number }} opts
+ */
+export function openBlocked ({ disk, now = Date.now }) {
+  const file = BLOCKED_FILE
+  const atRest = disk.atRest
+  /** pub → { deviceId, label, since, by, reason } */
+  let items = load()
+
+  function load () {
+    let raw
+    try { raw = disk.read(file) } catch (e) {
+      throw fail('blocked-unreadable', `cannot read ${BLOCKED_FILE}: ${e.message}`)
+    }
+    if (raw == null) return new Map()
+    let d
+    try { d = JSON.parse(atRest.decrypt(raw)) } catch (e) { throw fail('blocked-unreadable', `${BLOCKED_FILE} cannot be opened: ${e.message}`) }
+    if (d?.v !== 1 || !d.items || typeof d.items !== 'object') throw fail('blocked-unreadable', `${BLOCKED_FILE} has an unknown shape`)
+    return new Map(Object.entries(d.items))
+  }
+
+  function save () {
+    disk.write(file, atRest.encrypt(JSON.stringify({ v: 1, items: Object.fromEntries(items) })))
+  }
+
+  const publicOf = (pub, b) => ({ pub, deviceId: b.deviceId || null, label: b.label || '', since: b.since, by: b.by || null, reason: b.reason || null })
+
+  return {
+    has: (pub) => items.has(pub),
+    pubs: () => [...items.keys()],
+    list: () => [...items].map(([pub, b]) => publicOf(pub, b)),
+    /** Bloquea. Devuelve la entrada; si ya estaba, la que había (no se pisa el «desde cuándo»). */
+    block ({ pub, deviceId = null, label = '', by = null, reason = null }) {
+      if (typeof pub !== 'string' || !pub) throw fail('bad-pub', 'block: a device key is required')
+      if (items.has(pub)) return publicOf(pub, items.get(pub))
+      const b = { deviceId, label, since: now(), by, reason }
+      items.set(pub, b)
+      save()
+      return publicOf(pub, b)
+    },
+    /** Desbloquea. `true` si estaba. */
+    unblock (pub) {
+      if (!items.has(pub)) return false
+      items.delete(pub)
+      save()
+      return true
+    }
+  }
+}