@dotrino/vaultd 0.139.1 → 0.141.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotrino/vaultd",
-  "version": "0.139.1",
+  "version": "0.141.0",
   "type": "module",
   "description": "Certificador personal de Dotrino: daemon headless que custodia la clave maestra y delega capacidades a tus dispositivos por el proxy. Tu CA propia.",
   "bin": {

package/src/ctl.js

@@ -37,6 +37,7 @@ import { qrToString } from './qr.js'
 import { encodeInvite, inviteUrl, parseInvite } from '../lib/src/invite.js'
 import { atRestFor, readConfig as readKekConfig, probe as probeKek, rekeyDir, encryptedFilesIn, CONFIG_FILE as KEK_CONFIG_FILE } from '../lib/src/atrest.js'
 import { VERSION } from './version.js'
+import * as hw from './hwkeys.js'
 import { isNewer } from './update.js'
 
 const dir = dataDir()
@@ -163,7 +164,7 @@ function cmdStatus () {
 
 /** Una línea por perfil: nombre, id, huella y estado del candado. */
 function describeProfile (p) {
-  const lock = !p.protected ? 'sin contraseña' : (p.locked ? `${B}🔒 bloqueado${Z}` : '🔓 desbloqueado')
+  const lock = !p.protected ? 'sin candado' : `${p.locked ? `${B}🔒 bloqueado${Z}` : '🔓 desbloqueado'} · ${doorsSummary(p)}`
   // ALCANZABLE, Y SE DICE AQUÍ. Una bóveda puede estar corriendo y fuera de la red —si el
   // proxio le rechazó el `identify`, nadie la alcanza por su pubkey— y desde fuera eso se ve
   // igual que «no hay nada que aprobar»: el teléfono no timbra y no hay nada que mirar.
@@ -173,6 +174,16 @@ function describeProfile (p) {
   return `${B}${p.name || '(sin nombre)'}${Z}  ${p.id}  ${p.fingerprint || '—'}  ${lock}${red}`
 }
 
+/** Con qué se abre un perfil, dicho corto: «contraseña o YubiKey (toque)». */
+function doorsSummary (p) {
+  const names = (p.doors || []).map(doorName)
+  return names.length ? names.join(' o ') : 'contraseña'
+}
+function doorName (d) {
+  const base = d.kind === 'password' ? 'contraseña' : d.kind === 'fido2' ? 'llave (toque)' : d.kind === 'chalresp' ? 'llave (sin toque)' : d.kind
+  return d.withPassword ? `${base} + contraseña` : base
+}
+
 function showChallenge (pe) {
   console.log('\n%sUn dispositivo quiere conectarse a tu bóveda:%s', B, Z)
   console.log('  dispositivo : %s%s%s', B, pe.deviceId, Z)
@@ -1800,6 +1811,13 @@ function reportProfiles (d) {
     // resto se reenvía tal cual (son diagnósticos del servicio).
     if (d.code === 'WRONG_PASSWORD') console.error('Contraseña incorrecta%s.', d.tries ? ` — van ${d.tries} intentos fallidos` : '')
     else if (d.code === 'TOO_MANY_TRIES') console.error('Demasiados intentos: espera %s s antes de volver a probar.', d.waitSec || '?')
+    else if (d.code === 'NEEDS_SECURITY_KEY') console.error('Este perfil no se abre solo con contraseña: enchufa su llave de seguridad.')
+    else if (d.code === 'NEEDS_PASSWORD') console.error('Esa llave pide también la contraseña.')
+    else if (d.code === 'PASSWORD_TOO_SHORT') console.error('La contraseña necesita al menos %s caracteres: usa varias palabras al azar.', d.min || 12)
+    else if (d.code === 'MASTER_SEALED_ELSEWHERE') {
+      console.error('La llave maestra de este perfil quedó cerrada con una contraseña ANTERIOR (al quitarla, una versión vieja no la volvió a cerrar).')
+      console.error('Pon esa misma contraseña para recuperarla:  dotrino-vault profile password')
+    }
     else console.error('%s', d.error)
     process.exit(1)
   }
@@ -1815,7 +1833,9 @@ async function cmdProfile (rest) {
   const kmsAt = rawArgs.indexOf('--kms')
   const kmsFile = kmsAt !== -1 ? rawArgs[kmsAt + 1] : null
   const args = kmsAt !== -1 ? rawArgs.filter((_, i) => i !== kmsAt && i !== kmsAt + 1) : rawArgs
-  const name = args.join(' ').trim()
+  // Las banderas de la llave tampoco son parte del nombre (`profile add trabajo --key`).
+  const KEY_FLAGS = ['--key', '--no-touch', '--with-password']
+  const name = args.filter((a) => !KEY_FLAGS.includes(a)).join(' ').trim()
   switch (sub || 'ls') {
     case 'ls': {
       const d = await profileRequest('list')
@@ -1826,7 +1846,7 @@ async function cmdProfile (rest) {
       return
     }
     case 'add': {
-      if (!name) { console.error('uso: dotrino-vault profile add <nombre> [--kms <config.json>]'); process.exit(2) }
+      if (!name) { console.error('uso: dotrino-vault profile add <nombre> [--kms <config.json>] [--key [--no-touch] [--with-password]]'); process.exit(2) }
       // NACER con el KMS es la única forma de que la maestra no haya existido nunca bajo
       // la clave de esta máquina. Migrar después no da lo mismo y no se ofrece como si
       // lo diera (ver el freno de `atrest rekey`).
@@ -1843,7 +1863,14 @@ async function cmdProfile (rest) {
           console.error('No se creó ningún perfil.'); process.exit(1)
         }
       }
-      reportProfiles(await profileRequest('add', { name, ...(kek ? { kek } : {}) }))
+      const creado = reportProfiles(await profileRequest('add', { name, ...(kek ? { kek } : {}) }))
+      // CON LA LLAVE DESDE EL PRINCIPIO: el perfil nace sin candado y se le pone la puerta en
+      // el acto, así que su maestra solo pasa un instante bajo la llave de la máquina.
+      if (args.includes('--key')) {
+        PROFILE = creado.id
+        console.log('')
+        await cmdProfileKey(['add', ...args.filter((a) => a === '--no-touch' || a === '--with-password')])
+      }
       console.log('Conecta un dispositivo a este perfil:  dotrino-vault pair --profile "%s"', name)
       return
     }
@@ -1906,6 +1933,7 @@ async function cmdProfile (rest) {
       reportProfiles(await profileRequest('password-set', { password: pwd, current: actual || undefined }))
       return
     }
+    case 'key': return cmdProfileKey(args)
     // LA CONTRASEÑA DEL ADMIN. Otra, distinta, que solo sirve desde el admin remoto — aquí
     // no abre nada. Pantalla administrativa: dice qué hace y qué no, y ya (§5.1).
     case 'admin-password': {
@@ -1927,7 +1955,7 @@ async function cmdProfile (rest) {
       return
     }
     default:
-      console.error('uso: dotrino-vault profile {ls|add|rename|use|rm|password|admin-password}'); process.exit(2)
+      console.error('uso: dotrino-vault profile {ls|add|rename|use|rm|password|key|admin-password}'); process.exit(2)
   }
 }
 
@@ -1940,17 +1968,127 @@ function askText (prompt) {
   })
 }
 
-async function cmdUnlock () {
-  const pwd = await askPassword('Contraseña del perfil: ')
+/** La entrada del perfil al que apunta la orden: el de `--profile`, o el activo. */
+async function targetProfile () {
+  const d = await profileRequest('list')
+  const all = d.profiles || []
+  if (!PROFILE) return all.find((p) => p.current) || null
+  const n = String(PROFILE).toLowerCase()
+  return all.find((p) => p.id === PROFILE) || all.find((p) => (p.name || '').toLowerCase() === n) ||
+    all.find((p) => p.id.toLowerCase().startsWith(n)) || null
+}
+
+const hwDoors = hw.hardwareDoors
+const b64s = (u8) => Buffer.from(u8).toString('base64')
+
+/** Los fallos de la llave, en palabras de quien la tiene en la mano. */
+function hwReason (e) {
+  switch (e.code) {
+    case 'HWKEY_TOOLS_MISSING': return `falta ${e.tool} (instala el paquete ${e.pkg})`
+    case 'HWKEY_NO_DEVICE': return 'no hay ninguna llave enchufada'
+    case 'HWKEY_NOT_TOUCHED': return 'no se tocó la llave a tiempo'
+    case 'HWKEY_WRONG_KEY': return 'esta llave no es la de este perfil'
+    case 'HWKEY_WRONG_PIN': return 'el PIN de la llave no es ese'
+    case 'HWKEY_PIN_BLOCKED': return 'el PIN de la llave está bloqueado'
+    case 'HWKEY_SLOT_BUSY': return 'la ranura 2 de la llave ya está programada'
+    default: return e.message
+  }
+}
+
+async function cmdUnlock (args = []) {
+  const p = await targetProfile()
+  const doors = hwDoors(p)
+  const hasPassword = (p?.doors || []).some((d) => d.kind === 'password')
+  let creds = null
+  // CON LA LLAVE si el perfil tiene una y está enchufada; `--password` se la salta.
+  if (doors.length && !args.includes('--password')) {
+    try { creds = await hw.secretForDoors(doors, { onTouch: () => console.log('Toca la llave de seguridad…') }) } catch (e) { console.error('La llave de seguridad no abrió el perfil: %s.', hwReason(e)) }
+    if (!creds && !hasPassword) {
+      console.error('Este perfil se abre con su llave de seguridad. Enchúfala y vuelve a intentarlo.')
+      process.exit(1)
+    }
+  }
+  const password = !creds || creds.withPassword
+    ? await askPassword(creds ? 'Contraseña (esta llave pide también la contraseña): ' : 'Contraseña del perfil: ')
+    : null
   // El daemon devuelve cuánto aguanta abierto: se dice AQUÍ, al abrirlo, que es cuando
   // sirve de algo. Encontrárselo cerrado sin haberlo leído nunca parece una avería.
-  const out = await profileRequest('unlock', { password: pwd })
+  const out = await profileRequest('unlock', { password, ...(creds ? { door: creds.door, secret: b64s(creds.secret) } : {}) })
+  if (creds) creds.secret.fill(0)
   reportProfiles(out)
   const min = Math.max(1, Math.round((out?.autoLockMs || 5 * 60 * 1000) / 60000))
   console.log(`Ya puedes editar el perfil. Se vuelve a bloquear solo tras ${min} min sin usarse` +
     ' (o al reiniciar el servicio, o con: dotrino-vault lock).')
 }
 
+/**
+ * Da de alta la llave como puerta: la credencial FIDO2 (dos toques) o la ranura 2 programada
+ * para reto-respuesta sin toque. Devuelve lo que el daemon necesita para sellar la puerta.
+ */
+async function enrollHwKey ({ noTouch = false, label = '', overwrite = false } = {}) {
+  if (noTouch) {
+    const serial = await hw.ykSerial()
+    if (!serial) throw Object.assign(new Error('no key'), { code: 'HWKEY_NO_DEVICE' })
+    if (!overwrite && await hw.ykSlot2Busy()) {
+      console.error('La ranura 2 de la YubiKey %s ya está programada. Programarla otra vez BORRA lo que tenga.', serial)
+      console.error('Si estás seguro:  dotrino-vault profile key add --no-touch --overwrite-slot')
+      process.exit(1)
+    }
+    console.log('Programando la ranura 2 de la YubiKey %s: reto-respuesta, sin toque…', serial)
+    await hw.ykProgramSlot2({ overwrite })
+    const challenge = hw.newChallenge()
+    const secret = await hw.ykChallenge({ challenge })
+    return { kind: 'chalresp', challenge, serial, secret, label: label || `YubiKey ${serial}` }
+  }
+  console.log('Toca la llave de seguridad (1 de 2)…')
+  const { credId, device } = await hw.fido2MakeCredential({ label: label || 'dotrino-vault' })
+  const hsalt = hw.newHsalt()
+  console.log('Toca la llave otra vez (2 de 2)…')
+  const secret = await hw.fido2Secret({ credId, hsalt })
+  return { kind: 'fido2', credId, hsalt, secret, label: label || device || 'llave de seguridad' }
+}
+
+/** `profile key add|ls|rm`: las llaves de seguridad con que se abre el perfil. */
+async function cmdProfileKey (args) {
+  const [action = 'ls', ...rest] = args
+  const flag = (f) => rest.includes(f)
+  const at = rest.indexOf('--label')
+  const label = at !== -1 ? (rest[at + 1] || '') : ''
+  const p = await targetProfile()
+  if (!p) { console.error('el perfil no existe: %s', PROFILE); process.exit(1) }
+  if (action === 'ls') {
+    console.log('%s se abre con: %s', p.name || p.id, p.protected ? doorsSummary(p) : 'nada (sin candado)')
+    for (const d of hwDoors(p)) {
+      console.log('  %s  %s  %s%s', d.id, doorName(d), d.label || '', d.createdAt ? `  (${new Date(d.createdAt).toISOString().slice(0, 10)})` : '')
+    }
+    return
+  }
+  if (action === 'rm') {
+    if (!rest[0]) { console.error('uso: dotrino-vault profile key rm <id>   (los ids salen en: profile key ls)'); process.exit(2) }
+    reportProfiles(await profileRequest('door-rm', { door: rest[0] }))
+    return
+  }
+  if (action !== 'add') { console.error('uso: dotrino-vault profile key {ls|add|rm}'); process.exit(2) }
+  if (p.locked) { console.error('El perfil está bloqueado. Ábrelo primero:  dotrino-vault unlock'); process.exit(1) }
+  let spec
+  try { spec = await enrollHwKey({ noTouch: flag('--no-touch'), label, overwrite: flag('--overwrite-slot') }) } catch (e) {
+    console.error('No se pudo dar de alta la llave: %s.', hwReason(e)); process.exit(1)
+  }
+  if (flag('--with-password')) {
+    console.log('\nEsta llave abrirá el perfil SOLO junto con una contraseña (mínimo 12 caracteres).')
+    const pwd = await askPassword('Contraseña para esta llave: ')
+    if (pwd !== await askPassword('Repítela: ')) { console.error('Las contraseñas no coinciden.'); process.exit(1) }
+    spec.password = pwd
+  }
+  const out = await profileRequest('door-add', { spec: { ...spec, secret: b64s(spec.secret) } })
+  spec.secret.fill(0)
+  reportProfiles(out)
+  const tiene = (out.profiles || []).find((x) => x.id === p.id)
+  if (tiene) console.log('Ahora se abre con: %s', doorsSummary(tiene))
+  if (spec.kind === 'chalresp') console.log('Sin toque: con la llave enchufada, cualquier programa de esta máquina puede abrirlo. Desenchúfala cuando no la uses.')
+  console.log('Registra una segunda llave de repuesto, o deja también una contraseña: perder la única puerta es perder el perfil.')
+}
+
 async function cmdLock () {
   reportProfiles(await profileRequest('lock'))
 }
@@ -2083,7 +2221,16 @@ Contraseña del perfil (opcional; solo se pide para EDITAR el perfil — tus
 dispositivos siguen firmando y leyendo aunque esté bloqueado):
   profile password [set]            pone o cambia la contraseña
   profile password rm               la quita
-  unlock                            desbloquea para poder editar
+  unlock [--password]               desbloquea para poder editar (con la llave de
+                                    seguridad si el perfil tiene una y está enchufada)
+
+Llaves de seguridad (YubiKey). Cada una es otra forma de abrir el perfil, como la
+contraseña; abre cualquiera. Necesitan fido2-tools y yubikey-personalization:
+  profile key add                   con toque (FIDO2): pide tocar la llave dos veces
+  profile key add --no-touch        sin toque: programa la ranura 2 de la YubiKey
+  profile key add --with-password   esa llave abre SOLO junto con una contraseña
+  profile key ls | rm <id>          las llaves del perfil
+  profile add <nombre> --key        crea el perfil ya con su llave
   lock                              vuelve a bloquear (también solo, a los 5 min sin
                                     usarse, y al reiniciar el servicio)
 
@@ -2176,7 +2323,7 @@ export async function runCtl (argv) {
   switch (cmd) {
     case 'tui': return cmdTui()
     case 'profile': return cmdProfile(rest)
-    case 'unlock': return cmdUnlock()
+    case 'unlock': return cmdUnlock(rest)
     case 'lock': return cmdLock()
     // `info` es el comando común de todo el ecosistema para «qué aparato soy» (regla del
     // dueño, 2026-09-29); en la bóveda eso es su estado, que ya enseña el id de cada perfil.

package/src/daemon.js

@@ -389,19 +389,6 @@ export async function runDaemon () {
    * 0700 del vault y se BORRA al consumirla — mismo camino que ya usan los
    * secretos, y así nunca pasa por `ps` ni por el historial de la shell.
    */
-  /**
-   * Vuelve a cerrar la copia maestra de los secretos con otra llave. Se llama al poner
-   * o quitar la contraseña del perfil: los sobres de las variables NO se tocan (siguen
-   * sellados a la llave de cada aparato), solo cambia con qué se abre el llavero de
-   * administración. Sin esto, cambiar la contraseña dejaría los secretos ilegibles.
-   */
-  async function rekey (id, vieja, nueva) {
-    const v = mgr.get(id)
-    if (!v?.rekeySecrets) return
-    const r = await v.rekeySecrets(vieja, nueva)
-    // Se re-sella UNA copia (la de recuperación, que abre el llavero), no cajón por cajón.
-    if (r?.rekeyed) console.log('[vault] secrets recovery copy re-sealed under the new key')
-  }
 
   /**
    * BORRA la llave derivada en cuanto se usó. Es lo único de la contraseña que se puede
@@ -484,11 +471,14 @@ export async function runDaemon () {
       // paga; el dueño no tiene que acordarse de un comando aparte.
       case 'unlock': {
         const id = ref()
-        await mgr.unlock(id, req.password)   // por el manager: mueve la maestra a memoria y la sella
+        // Con cualquier puerta: la contraseña, los bytes que dio la YubiKey (`door` + `secret`,
+        // en base64), o las dos cosas si la puerta pide ambas.
+        await mgr.unlock(id, { password: req.password || null, door: req.door || null, secret: req.secret || null })
         let note = ''
         let ak = null
         try {
-          ak = await mgr.profiles.adminKey(id, req.password)
+          // Una COPIA: `wipe` pisa lo que se le pase, y la de memoria tiene que quedarse.
+          ak = new Uint8Array(mgr.profiles.openKey(id))
           // REHACER el llavero, no solo saldar: con la frase delante se puede dejar cada
           // cajón envuelto para exactamente quien dice el acta — creando lo que falta,
           // reemplazando lo que alguien metiera mal y quitando lo que sobre.
@@ -536,26 +526,47 @@ export async function runDaemon () {
       // abrirse con la frase. Hay que volver a cerrar la copia maestra con la nueva, o
       // quedarían ilegibles. Si el perfil YA tenía contraseña, hace falta la vieja para
       // poder abrirla: por eso el camino normal para cambiarla es quitarla y ponerla.
+      // LA CONTRASEÑA ES UNA PUERTA (`profiles.js`). Ponerla o cambiarla no vuelve a sellar nada:
+      // la llave del perfil es la misma, solo cambia el sobre. Si el perfil no tenía candado,
+      // `addDoor` estrena la llave y sella con ella lo que estaba bajo la de la máquina.
       case 'password-set': {
         const id = ref()
-        const tenia = !!mgr.profiles.get(id)?.protected
-        if (tenia && !req.current) throw new Error('this profile already has a password: remove it first (`profile password --rm`) and then set the new one')
-        const vieja = tenia ? await mgr.profiles.adminKey(id, req.current) : null
-        await mgr.profiles.setPassword(id, req.password)
-        const nueva = await mgr.profiles.adminKey(id, req.password)
-        try { await rekey(id, vieja, nueva) } finally { wipe(vieja); wipe(nueva) }
+        if (mgr.profiles.isLocked(id)) {
+          if (!req.current) throw Object.assign(new Error('the profile is locked: unlock it first, or give the current password'), { code: 'PROFILE_LOCKED' })
+          await mgr.unlock(id, { password: req.current })
+        }
+        await mgr.addDoor(id, { kind: 'password', password: req.password })
         return { done: 'contraseña guardada' }
       }
-      // QUITARLA: al revés. Se abre la copia maestra con la frase y se vuelve a cerrar
-      // con la llave de la máquina, que es la protección de siempre — el disco sigue
-      // cifrado, pero su material vive en ese mismo disco.
+      // QUITARLA. Si era la última puerta, el perfil se queda sin candado: su llave pasa a
+      // guardarse con la de esta máquina y se abre sola — lo sellado con ella sigue abriendo.
       case 'password-rm': {
         const id = ref()
-        if (!req.password) throw new Error('removing the password needs the current one: the secrets must be re-sealed before it goes')
-        const vieja = await mgr.profiles.adminKey(id, req.password)
-        try { await rekey(id, vieja, null) } finally { wipe(vieja) }
-        mgr.profiles.removePassword(id)
-        return { done: 'contraseña quitada · los secretos ahora se abren con la llave de esta máquina' }
+        if (mgr.profiles.isLocked(id)) {
+          if (!req.password) throw Object.assign(new Error('the profile is locked: unlock it first, or give the current password'), { code: 'PROFILE_LOCKED' })
+          await mgr.unlock(id, { password: req.password })
+        }
+        const r = await mgr.removeDoor(id, 'password')
+        return { done: r.protected ? 'contraseña quitada · el perfil sigue cerrándose con su llave de seguridad' : 'contraseña quitada · el perfil ya no tiene candado: se abre con la llave de esta máquina' }
+      }
+      // LLAVES DE SEGURIDAD (YubiKey). Quien habla con la llave es la CLI; aquí llegan la
+      // credencial o el reto, y los bytes que devolvió — nunca un secreto que la abra sin ella.
+      case 'door-add': {
+        const id = ref()
+        const spec = req.spec || {}
+        if (spec.kind !== 'fido2' && spec.kind !== 'chalresp') throw Object.assign(new Error('door-add is for security keys; the password uses password-set'), { code: 'BAD_DOOR' })
+        const door = await mgr.addDoor(id, {
+          kind: spec.kind, label: spec.label || '', password: spec.password || null,
+          credId: spec.credId, hsalt: spec.hsalt, challenge: spec.challenge, serial: spec.serial,
+          secret: spec.secret ? Buffer.from(spec.secret, 'base64') : null
+        })
+        return { done: `llave de seguridad añadida (${door.id})`, door }
+      }
+      case 'door-rm': {
+        const id = ref()
+        if (!req.door) throw Object.assign(new Error('which door? (dotrino-vault profile key ls)'), { code: 'NO_SUCH_DOOR' })
+        const r = await mgr.removeDoor(id, req.door)
+        return { done: r.protected ? 'llave de seguridad quitada' : 'llave de seguridad quitada · el perfil ya no tiene candado: se abre con la llave de esta máquina' }
       }
       // ----- LA CONTRASEÑA DEL ADMIN (`docs/abrir-a-distancia.md`) -----
       //

package/src/hwkeys.js

@@ -0,0 +1,247 @@
+/**
+ * LLAVES DE HARDWARE (YubiKey y compañía) como PUERTA del perfil — `docs/llaves-de-hardware.md`
+ * nivel 2. Esto vive del lado de la CLI y la TUI, **nunca del daemon**: la llave pide un toque
+ * (y a veces un PIN) a la persona que está delante, y esa persona está en la terminal.
+ *
+ * Lo único que sale de aquí hacia el daemon son los 32 (o 20) bytes que devuelve la llave, por
+ * el mismo camino que la contraseña. El daemon los convierte en la llave que abre la puerta.
+ *
+ * DOS SABORES, porque la llave tiene dos funciones que sirven y se comportan distinto:
+ *
+ *   · `fido2`    — extensión `hmac-secret`. **Siempre pide toque**: la llave contesta
+ *                  `FIDO_ERR_UP_REQUIRED` si no lo hay (comprobado con una YubiKey 5.7.4).
+ *   · `chalresp` — reto-respuesta HMAC-SHA1 de la ranura OTP 2, programada SIN toque. Abre con
+ *                  la llave enchufada y nada más. Es la que pidió el dueño para no tener que
+ *                  tocar (2026-10-05). El precio se dice: enchufada, cualquier programa de esta
+ *                  máquina puede pedirle la respuesta.
+ *
+ * SIN MÓDULOS NATIVOS. Se llama a los comandos de libfido2 (`fido2-token`, `fido2-cred`,
+ * `fido2-assert`) y de yubikey-personalization (`ykinfo`, `ykchalresp`, `ykpersonalize`), igual
+ * que el proveedor de KEK `command` llama a un KMS: el binario único no puede llevar un `.node`.
+ * Dónde buscarlos: `DOTRINO_HWKEY_BIN` (carpeta) y si no, el PATH.
+ */
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { spawn } from 'node:child_process'
+
+/** El «relying party» de las credenciales FIDO2 de la bóveda. No es un dominio: nadie lo resuelve. */
+export const RP_ID = 'dotrino-vault'
+
+const coded = (msg, code, extra = {}) => Object.assign(new Error(msg), { code, ...extra })
+
+/** Dónde está un comando, o `null`. */
+export function findTool (name) {
+  const dirs = [process.env.DOTRINO_HWKEY_BIN, ...String(process.env.PATH || '').split(path.delimiter)].filter(Boolean)
+  for (const d of dirs) {
+    for (const n of process.platform === 'win32' ? [name + '.exe', name] : [name]) {
+      const f = path.join(d, n)
+      try { fs.accessSync(f, fs.constants.X_OK); return f } catch (_) {}
+    }
+  }
+  return null
+}
+
+function tool (name, pkg) {
+  const f = findTool(name)
+  if (!f) throw coded(`${name} not found: install ${pkg} (or point DOTRINO_HWKEY_BIN at its folder)`, 'HWKEY_TOOLS_MISSING', { tool: name, pkg })
+  return f
+}
+
+/**
+ * Corre un comando y devuelve stdout. La entrada va por ARCHIVO (`-i`), no por stdin: así la
+ * terminal queda libre para que la herramienta pida el PIN si la llave tiene uno puesto.
+ */
+function run (file, args, { timeoutMs = 60_000 } = {}) {
+  return new Promise((resolve, reject) => {
+    const p = spawn(file, args, { stdio: ['inherit', 'pipe', 'pipe'] })
+    let out = ''; let err = ''
+    p.stdout.on('data', (d) => { out += d })
+    p.stderr.on('data', (d) => { err += d })
+    const t = setTimeout(() => { try { p.kill() } catch (_) {} }, timeoutMs)
+    p.on('error', (e) => { clearTimeout(t); reject(e) })
+    p.on('close', (code) => {
+      clearTimeout(t)
+      if (code === 0) return resolve(out)
+      reject(classify(err.trim() || `${path.basename(file)} exited with ${code}`))
+    })
+  })
+}
+
+/** Los fallos de la llave con nombre: cada uno se arregla de una forma distinta. */
+function classify (msg) {
+  if (/OPERATION_DENIED|ACTION_TIMEOUT|USER_ACTION_TIMEOUT/.test(msg)) return coded('the key was not touched in time', 'HWKEY_NOT_TOUCHED')
+  if (/NO_CREDENTIALS|INVALID_CREDENTIAL/.test(msg)) return coded('this key does not hold that credential', 'HWKEY_WRONG_KEY')
+  if (/PIN_INVALID|PIN_AUTH_INVALID/.test(msg)) return coded('wrong PIN', 'HWKEY_WRONG_PIN')
+  if (/PIN_BLOCKED/.test(msg)) return coded('the key PIN is blocked', 'HWKEY_PIN_BLOCKED')
+  if (/no yubikey present|No such device|Device not found/i.test(msg)) return coded('no key plugged in', 'HWKEY_NO_DEVICE')
+  return coded(msg, 'HWKEY_FAILED')
+}
+
+/** Escribe la entrada en un archivo 0600 de una carpeta propia, y la borra al terminar. */
+async function withInput (lines, fn) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'dotrino-hwkey-'))
+  const f = path.join(dir, 'in')
+  try {
+    fs.writeFileSync(f, lines.join('\n') + '\n', { mode: 0o600 })
+    return await fn(f)
+  } finally {
+    try { fs.rmSync(dir, { recursive: true, force: true }) } catch (_) {}
+  }
+}
+
+const b64 = (b) => Buffer.from(b).toString('base64')
+const randomB64 = (n = 32) => b64(crypto.randomBytes(n))
+
+// ----------------------------------------------------------------- FIDO2 (con toque)
+
+/** Las llaves FIDO2 enchufadas: `[{ path, name }]`. */
+export async function fido2Devices () {
+  const out = await run(tool('fido2-token', 'fido2-tools (libfido2)'), ['-L'])
+  return out.split('\n').map((l) => /^(\S+?):\s*(.*)$/.exec(l.trim())).filter(Boolean)
+    .map((m) => ({ path: m[1], name: (/\(([^)]*)\)\s*$/.exec(m[2]) || [])[1] || m[2] }))
+}
+
+async function oneFido2Device () {
+  const devs = await fido2Devices()
+  if (!devs.length) throw coded('no FIDO2 key plugged in', 'HWKEY_NO_DEVICE')
+  return devs
+}
+
+/**
+ * Crea la credencial de la puerta (un toque). No es residente: no ocupa sitio en la llave y
+ * su id lo guarda la bóveda. Devuelve `{ credId, device }`.
+ */
+export async function fido2MakeCredential ({ label = 'dotrino-vault' } = {}) {
+  const [dev] = await oneFido2Device()
+  const out = await withInput([randomB64(), RP_ID, String(label).replace(/[\n\0]/g, ' ').slice(0, 60) || 'dotrino-vault', randomB64()],
+    (f) => run(tool('fido2-cred', 'fido2-tools (libfido2)'), ['-M', '-h', '-i', f, dev.path]))
+  const credId = out.split('\n')[4]?.trim()
+  if (!credId) throw coded('fido2-cred gave no credential id', 'HWKEY_FAILED')
+  return { credId, device: dev.name }
+}
+
+/** ¿Tiene esta llave la credencial? Sin toque (`up=false`): sirve para elegir puerta sin molestar. */
+async function fido2Holds (devPath, credId) {
+  try {
+    await withInput([randomB64(), RP_ID, credId],
+      (f) => run(tool('fido2-assert', 'fido2-tools (libfido2)'), ['-G', '-t', 'up=false', '-i', f, devPath], { timeoutMs: 10_000 }))
+    return true
+  } catch (e) {
+    // Algunas llaves contestan «hace falta toque» en vez de «no la tengo» cuando SÍ la tienen.
+    return e.code !== 'HWKEY_WRONG_KEY'
+  }
+}
+
+/**
+ * El secreto de la puerta (un toque): `HMAC(secreto-de-la-credencial, hsalt)`, 32 bytes.
+ * Prueba las llaves enchufadas hasta encontrar la que guarda `credId`.
+ */
+export async function fido2Secret ({ credId, hsalt }) {
+  const devs = await oneFido2Device()
+  for (const d of devs) {
+    if (devs.length > 1 && !(await fido2Holds(d.path, credId))) continue
+    const out = await withInput([randomB64(), RP_ID, credId, hsalt],
+      (f) => run(tool('fido2-assert', 'fido2-tools (libfido2)'), ['-G', '-h', '-i', f, d.path]))
+    const lines = out.split('\n').map((l) => l.trim()).filter(Boolean)
+    const secret = Buffer.from(lines[lines.length - 1] || '', 'base64')
+    if (secret.length !== 32) throw coded('the key returned no hmac-secret', 'HWKEY_FAILED')
+    return new Uint8Array(secret)
+  }
+  throw coded('none of the plugged keys holds this credential', 'HWKEY_WRONG_KEY')
+}
+
+/** De estas credenciales, ¿cuáles tiene alguna llave enchufada? Sin toque. */
+export async function fido2Present (credIds) {
+  let devs = []
+  try { devs = await fido2Devices() } catch (e) { if (e.code === 'HWKEY_TOOLS_MISSING') throw e; return [] }
+  const hits = []
+  for (const id of credIds) {
+    for (const d of devs) { if (await fido2Holds(d.path, id)) { hits.push(id); break } }
+  }
+  return hits
+}
+
+// ------------------------------------------------- reto-respuesta, ranura OTP 2 (sin toque)
+
+const SLOT = '2'
+
+/** El número de serie de la YubiKey enchufada (por la interfaz OTP), o `null` si no hay. */
+export async function ykSerial () {
+  try {
+    const out = await run(tool('ykinfo', 'yubikey-personalization'), ['-s', '-q'], { timeoutMs: 10_000 })
+    return out.trim() || null
+  } catch (e) {
+    if (e.code === 'HWKEY_TOOLS_MISSING') throw e
+    return null
+  }
+}
+
+/** ¿Está ocupada la ranura 2? Programarla encima borraría lo que tenga. */
+export async function ykSlot2Busy () {
+  const out = await run(tool('ykinfo', 'yubikey-personalization'), ['-a'], { timeoutMs: 10_000 })
+  return /slot2_status:\s*1/.test(out)
+}
+
+/**
+ * Programa la ranura 2 con reto-respuesta HMAC-SHA1 **sin toque** y un secreto al azar que no se
+ * guarda en ningún sitio: queda solo dentro de la llave. Se niega si la ranura está ocupada,
+ * salvo `overwrite` — sobrescribirla es borrar lo que hubiera ahí, y eso lo decide la persona.
+ */
+export async function ykProgramSlot2 ({ overwrite = false } = {}) {
+  if (!overwrite && await ykSlot2Busy()) {
+    throw coded('slot 2 of this key is already programmed: overwriting it erases what is there', 'HWKEY_SLOT_BUSY')
+  }
+  const secret = crypto.randomBytes(20)
+  try {
+    await run(tool('ykpersonalize', 'yubikey-personalization'),
+      ['-' + SLOT, '-y', '-ochal-resp', '-ochal-hmac', '-ohmac-lt64', '-oserial-api-visible', '-a', secret.toString('hex')])
+  } finally { secret.fill(0) }
+  return { serial: await ykSerial() }
+}
+
+/** La respuesta de la ranura 2 a `challenge` (hex), 20 bytes. Sin toque si se programó así. */
+export async function ykChallenge ({ challenge }) {
+  const out = await run(tool('ykchalresp', 'yubikey-personalization'), ['-' + SLOT, '-x', challenge], { timeoutMs: 20_000 })
+  const resp = Buffer.from(out.trim(), 'hex')
+  if (resp.length !== 20) throw coded('the key gave no response (is slot 2 set to challenge-response?)', 'HWKEY_FAILED')
+  return new Uint8Array(resp)
+}
+
+/**
+ * Para ABRIR: le pide a la llave enchufada los bytes de una de las puertas del perfil. Primero
+ * la que NO pide toque (reto-respuesta), después la de toque (FIDO2), avisando con `onTouch`
+ * justo antes de que la llave parpadee. `null` si ninguna llave de este perfil está enchufada.
+ * Devuelve `{ door, secret, withPassword }`.
+ */
+export async function secretForDoors (doors = [], { onTouch = () => {} } = {}) {
+  let last = null
+  const cr = doors.filter((d) => d.kind === 'chalresp')
+  if (cr.length) {
+    const serial = await ykSerial()
+    for (const d of cr.filter((x) => serial && (!x.serial || x.serial === serial))) {
+      try { return { door: d.id, secret: await ykChallenge({ challenge: d.challenge }), withPassword: !!d.withPassword } } catch (e) { last = e }
+    }
+  }
+  const f = doors.filter((d) => d.kind === 'fido2')
+  if (f.length) {
+    const present = await fido2Present(f.map((d) => d.credId))
+    const d = f.find((x) => present.includes(x.credId))
+    if (d) {
+      onTouch(d)
+      return { door: d.id, secret: await fido2Secret({ credId: d.credId, hsalt: d.hsalt }), withPassword: !!d.withPassword }
+    }
+  }
+  if (last) throw last
+  return null
+}
+
+/** Las puertas de hardware de un perfil (de su entrada en la lista). */
+export const hardwareDoors = (p) => (p?.doors || []).filter((d) => d.kind === 'fido2' || d.kind === 'chalresp')
+
+/** Un reto nuevo para una puerta: 32 bytes en hex (cabe en el modo `hmac-lt64`). */
+export const newChallenge = () => crypto.randomBytes(32).toString('hex')
+/** Un salt nuevo para `hmac-secret`: 32 bytes en base64. */
+export const newHsalt = () => randomB64(32)
+