@dotrino/identity 0.94.0 → 0.96.0

package/vault/vendor/opaque/src/index.js

@@ -0,0 +1,123 @@
+/**
+ * @dotrino/opaque — OPAQUE (RFC 9807) para el ecosistema Dotrino.
+ *
+ * Comprueba una contraseña SIN que el servidor la vea nunca y sin entregar nada con qué
+ * adivinarla desde fuera. Lo usan las tres versiones del vault (el binario, la pestaña y la
+ * extensión) y el gestor, para el aparato que se abre con usuario y contraseña.
+ *
+ * Aquí no hay criptografía propia: el protocolo es `opaque-ke` (Meta, auditado por NCC
+ * Group) compilado a WASM desde su código fuente en nuestro CI. Este archivo solo pone
+ * nombres y comprueba lo que entra.
+ *
+ * Todo lo que entra y sale son cadenas base64url. Los errores llevan `code`:
+ *   · `bad-input`    — falta un dato o no se puede leer
+ *   · `login-failed` — contraseña equivocada, usuario inexistente, identificadores que no
+ *                      casan o un mensaje alterado. A propósito son el MISMO código: distinguirlos
+ *                      le diría a quien prueba qué usuarios existen.
+ *   · `protocol`     — cualquier otro fallo del protocolo
+ *   · `internal`     — un fallo que no viene del protocolo (no debería pasar)
+ */
+import * as wasm from '../build/opaque.js'
+import wasmBytes from '../build/wasm-bytes.js'
+
+export class OpaqueError extends Error {
+  constructor (code, message) {
+    super(message)
+    this.name = 'OpaqueError'
+    this.code = code
+  }
+}
+
+let ready = false
+function init () {
+  if (ready) return
+  const bin = Uint8Array.from(atob(wasmBytes), (c) => c.charCodeAt(0))
+  wasm.initSync({ module: bin })
+  ready = true
+}
+
+const CODE = /^(bad-input|login-failed|protocol): ([\s\S]*)$/
+
+function call (fn, ...args) {
+  init()
+  try {
+    return fn(...args)
+  } catch (e) {
+    const msg = String(e?.message ?? e)
+    const m = CODE.exec(msg)
+    if (m) throw new OpaqueError(m[1], m[2])
+    throw new OpaqueError('internal', msg)
+  }
+}
+
+function need (name, v) {
+  if (typeof v !== 'string' || !v) throw new OpaqueError('bad-input', `${name} is required`)
+  return v
+}
+
+/**
+ * Los identificadores que se atan al intercambio. Si se usan, las DOS puntas tienen que
+ * pasar los mismos; si no casan, el inicio falla como una contraseña equivocada.
+ */
+function idents (identifiers) {
+  if (identifiers == null || typeof identifiers !== 'object') throw new OpaqueError('bad-input', 'identifiers must be an object')
+  const { client, server } = identifiers
+  for (const [k, v] of [['identifiers.client', client], ['identifiers.server', server]]) {
+    if (v !== undefined && (typeof v !== 'string' || !v)) throw new OpaqueError('bad-input', `${k} must be a non-empty string`)
+  }
+  return [client, server]
+}
+
+/** La suite y sus parámetros. Se guarda junto a cada registro. */
+export function suiteId () {
+  return call(wasm.suiteId)
+}
+
+export const server = {
+  /** La preparación del servidor: SECRETA, una por bóveda. Sin ella no se puede comprobar nada. */
+  createSetup () {
+    return call(wasm.serverCreateSetup)
+  },
+  publicKey ({ setup } = {}) {
+    return call(wasm.serverPublicKey, need('setup', setup))
+  },
+  registrationResponse ({ setup, request, credentialId } = {}) {
+    return call(wasm.serverRegistrationResponse, need('setup', setup), need('request', request), need('credentialId', credentialId))
+  },
+  /** Lo que se guarda del usuario (el «registro»). */
+  registrationFinish ({ upload } = {}) {
+    return call(wasm.serverRegistrationFinish, need('upload', upload))
+  },
+  /**
+   * `record` tiene que venir SIEMPRE: el registro, o `null` si el usuario no existe. Con
+   * `null` responde igual, así que desde fuera no se sabe qué usuarios hay.
+   */
+  loginStart ({ setup, record, request, credentialId, identifiers = {} } = {}) {
+    if (record !== null && (typeof record !== 'string' || !record)) {
+      throw new OpaqueError('bad-input', 'record must be the stored record, or null for an unknown user')
+    }
+    return call(wasm.serverLoginStart, need('setup', setup), record ?? undefined, need('request', request), need('credentialId', credentialId), ...idents(identifiers))
+  },
+  loginFinish ({ state, finalization, identifiers = {} } = {}) {
+    return call(wasm.serverLoginFinish, need('state', state), need('finalization', finalization), ...idents(identifiers))
+  },
+}
+
+export const client = {
+  registrationStart ({ password } = {}) {
+    return call(wasm.clientRegistrationStart, need('password', password))
+  },
+  /** Devuelve `upload` (para el servidor) y `exportKey`, que solo sale de la contraseña. */
+  registrationFinish ({ state, response, password, identifiers = {} } = {}) {
+    return call(wasm.clientRegistrationFinish, need('state', state), need('response', response), need('password', password), ...idents(identifiers))
+  },
+  loginStart ({ password } = {}) {
+    return call(wasm.clientLoginStart, need('password', password))
+  },
+  /** Devuelve `finalization` (para el servidor), `sessionKey` y el mismo `exportKey` del registro. */
+  loginFinish ({ state, response, password, identifiers = {} } = {}) {
+    return call(wasm.clientLoginFinish, need('state', state), need('response', response), need('password', password), ...idents(identifiers))
+  },
+}
+
+export default { suiteId, server, client, OpaqueError }

package/vault/vendor/proxy-client/VERSION.txt

@@ -1,4 +1,4 @@
-Copia vendorizada de @dotrino/proxy-client@0.22.0 (dotrino-proxy-client/src/{index,client,signature,canonical,sealing,encpub,webrtc}.js).
+Copia vendorizada de @dotrino/proxy-client@0.23.1 (dotrino-proxy-client/src/{index,client,signature,canonical,sealing,encpub,webrtc}.js).
 NO se edita a mano: la escribe `node vendor.mjs` y la vigila test/vendor-up-to-date.test.mjs.
 sealing.js resuelve @dotrino/identity/content de forma PEREZOSA (= ../../content.js
 por el import map): solo se carga si de verdad se sella algo.

package/vault/vendor/proxy-client/client.js

@@ -1124,7 +1124,23 @@ export class WebSocketProxyClient {
       // tienen autoReconnect=false (puesto por close()), así que este guard no
       // filtra desconexiones pedidas por la app. Sin esto, un restart del proxy
       // deja a clientes de larga duración (bots, apps abiertas) zombis para siempre.
-      if (wasConnected && this.autoReconnect) {
+      //
+      // Y TAMBIÉN CUANDO EL INTENTO NI LLEGÓ A ABRIRSE (`reintentando`). Ese era el
+      // agujero, y costó 36 horas de bóveda muda el 2026-09-16: un socket que falla al
+      // conectar cierra con `_connected` en false, así que con solo `wasConnected` no se
+      // programaba el siguiente intento. O sea que el cliente hacía UN reintento —el de
+      // la caída— y si ese caía en un momento en que la red seguía mal, se rendía para
+      // siempre, en silencio y con `maxReconnectAttempts` en 100000. Justo el caso normal:
+      // cuando se cae la red, el primer reintento a los pocos segundos tampoco encuentra a
+      // nadie.
+      //
+      // Los eventos que se veían: `disconnect reconnecting#1 disconnect` y nada más.
+      //
+      // `_reconnectAttempts` vuelve a 0 al abrir, así que esto NO convierte un `connect()`
+      // inicial fallido en un bucle de fondo: ahí vale 0 y la promesa se rechaza como
+      // siempre.
+      const reintentando = this._reconnectAttempts > 0
+      if ((wasConnected || reintentando) && this.autoReconnect) {
         this._scheduleReconnect()
       }
     })
@@ -1178,6 +1194,12 @@ export class WebSocketProxyClient {
     this._reconnectAttempts++
     this._emit('reconnecting', this._reconnectAttempts, this.maxReconnectAttempts)
     this._reconnectTimer = setTimeout(() => this._open(), this.reconnectDelay)
+    // UN REINTENTO PENDIENTE NO MANTIENE VIVO EL PROCESO. Desde que se reintenta de verdad
+    // —antes la cadena se cortaba sola al primer fallo—, este temporizador basta para que un
+    // programa de Node que se olvidó de cerrar el cliente no termine nunca. Lo de siempre:
+    // esto es mantenimiento de fondo, y quién se va es decisión de la app. En el navegador
+    // `unref` no existe y no hace falta.
+    this._reconnectTimer.unref?.()
   }
 
   _handleFrame (raw) {

package/vault/vendor/vault/VERSION.txt

@@ -1,5 +1,9 @@
-Copia vendorizada de @dotrino/vault@0.65.0 (dotrino-vault/lib/src/{index,enroll,protocol}.js).
+Copia vendorizada de @dotrino/vault@0.67.0 (dotrino-vault/lib/src/{index,enroll,protocol,passwordLogins,loginClient,b64}.js).
 NO se edita a mano: la escribe `node vendor.mjs` y la vigila test/vendor-up-to-date.test.mjs.
 index.js importa ./enroll.js y ./protocol.js (relativos, van en esta misma copia),
 @dotrino/identity/{capabilities,acta} (= ../../{capabilities,acta}.js) y
 @dotrino/proxy-client (= ../proxy-client/), todos por el import map de index.html.
+passwordLogins.js es el aparato que se abre con usuario y contraseña: lo carga
+vault.js SOLO cuando esta pestaña es bóveda, porque arrastra el OPAQUE en WASM.
+loginClient.js es la otra mitad —el que ENTRA con esa contraseña— y lo carga core.js
+solo al entrar, por lo mismo: arrastra el OPAQUE.

package/vault/vendor/vault/b64.js

@@ -0,0 +1,36 @@
+/**
+ * b64.js — base64url a mano, sin `Buffer` ni `btoa`.
+ *
+ * Vive aparte porque lo usan piezas que corren en los tres sitios: el binario (Node), la
+ * pestaña y la extensión. `Buffer` no existe en el navegador y `btoa` no existe en algunos
+ * workers, así que la única forma de tener UNA implementación es esta.
+ */
+
+const B64_STD = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'
+
+export function bytesToB64url (bytes) {
+  let out = ''
+  for (let i = 0; i < bytes.length; i += 3) {
+    const a = bytes[i]; const b = bytes[i + 1]; const c = bytes[i + 2]
+    out += B64_STD[a >> 2]
+    out += B64_STD[((a & 3) << 4) | ((b ?? 0) >> 4)]
+    if (b === undefined) break
+    out += B64_STD[((b & 15) << 2) | ((c ?? 0) >> 6)]
+    if (c === undefined) break
+    out += B64_STD[c & 63]
+  }
+  return out.replace(/\+/g, '-').replace(/\//g, '_')
+}
+
+export function b64urlToBytes (s) {
+  const clean = String(s).replace(/-/g, '+').replace(/_/g, '/').replace(/[^A-Za-z0-9+/]/g, '')
+  const out = []
+  let acc = 0; let bits = 0
+  for (const ch of clean) {
+    const v = B64_STD.indexOf(ch)
+    if (v < 0) return null
+    acc = (acc << 6) | v; bits += 6
+    if (bits >= 8) { bits -= 8; out.push((acc >> bits) & 0xff) }
+  }
+  return Uint8Array.from(out)
+}

package/vault/vendor/vault/index.js

@@ -31,6 +31,10 @@ import { createEnrollDesk, deviceIdOf, DEVICE_TTL_MS, FRESH_WINDOW_MS } from './
 // Las constantes del protocolo salen del MISMO módulo que usa el daemon: si la lista
 // local se queda corta, el dispositivo deja de handle mensajes sin que nadie lo note.
 import { MSG, SCOPE } from './protocol.js'
+// El canal donde se anuncia esta cuenta y la huella que lo nombra: la MISMA pieza que usa
+// el daemon y que lee quien entra con usuario y contraseña. Un canal que se escriba distinto
+// en cada bóveda no es el mismo canal.
+import { vaultChannel, accountFingerprint } from './passwordLogins.js'
 
 const SIGN_SCOPE = SCOPE.SIGN
 const RENEW_TTL_MS = DEVICE_TTL_MS             // la renovación extiende la misma ventana (30 días)
@@ -46,11 +50,16 @@ export { deviceIdOf }
  *   `me.publickey`, `signData`, `signDelegation`, `listDelegations`, `revokeDelegation`.
  * @param {object} [opts]
  * @param {string} [opts.proxyUrl='wss://proxy.dotrino.com']
+ * @param {object} [opts.logins]  escritorio de `createLoginDesk` (`./password-logins`) para
+ *   ENTRAR CON USUARIO Y CONTRASEÑA. Lo monta quien levanta esta bóveda, porque en el
+ *   navegador no hay archivos y el estado tiene que guardarlo él. Sin él, esta bóveda
+ *   contesta `logins-unavailable` — no se inventa un almacén.
  * @returns {Promise<object>} handle: { iss, proxy, client, startPairing, stopPairing,
- *   approve, reject, listPending, listMachines, revoke, getSelfCert, onPendingChange,
- *   onAdopted, close }
+ *   approve, reject, listPending, listMachines, revoke, getSelfCert, listLogins,
+ *   loginRegisterBegin, loginRegisterFinish, loginBegin, loginEnd, closeLogin,
+ *   clearLoginBlock, removeLogin, onPendingChange, onAdopted, close }
  */
-export async function startDeviceVault (identity, { proxyUrl, client: injectedClient } = {}) {
+export async function startDeviceVault (identity, { proxyUrl, client: injectedClient, logins = null } = {}) {
   const iss = identity.me?.publickey
   if (!iss) throw new Error('no identity: create/unlock your identity before using this device as a vault')
   const proxy = proxyUrl || 'wss://proxy.dotrino.com'
@@ -95,10 +104,35 @@ export async function startDeviceVault (identity, { proxyUrl, client: injectedCl
   })()
 
   const selfCert = await getSelfCert()
+
+  /**
+   * ANUNCIARSE EN EL CANAL DE LA CUENTA, igual que el daemon del PC (`src/transport.js`).
+   *
+   * Sin esto, una bóveda-pestaña no existe para quien entra con usuario y contraseña: ese
+   * equipo no tiene ninguna llave, solo el código de la dirección, y el canal es lo único
+   * que puede convertirlo en «con quién hablo». Faltaba, así que quien tenía su bóveda solo
+   * en una pestaña no era encontrable por dirección — y la pestaña sí sabe atender el
+   * inicio de sesión desde que existe `logins`.
+   *
+   * Va DESPUÉS de identificarse y en cada token nuevo, porque el canal guarda el token y el
+   * token cambia con cada reconexión. Y no bloquea el arranque: una bóveda que no consigue
+   * anunciarse sigue sirviendo a sus aparatos, que es casi todo lo que hace.
+   */
+  const announce = async () => {
+    if (!logins || !client.token || typeof client.publish !== 'function') return
+    try {
+      const canal = vaultChannel(await accountFingerprint(identity))
+      await client.publish(canal)
+    } catch (e) {
+      console.warn('[device-vault] could not announce this account on the proxy:', e?.message || e)
+    }
+  }
+
   const identify = async () => {
     if (!client.token) return
     // El sobre lo arma el pilar (`identifyAs`), que le pone el destinatario.
     await client.identifyAs({ publickey: iss, sign: (d) => identity.signData(d), cert: selfCert })
+    await announce()
   }
   await identify()
   client.on('token', () => identify().catch(() => {}))
@@ -328,8 +362,72 @@ export async function startDeviceVault (identity, { proxyUrl, client: injectedCl
     else if (p.type === MSG.GET) handle('get', handleGet(_from, p), _from)
     else if (p.type === MSG.STORE) handle('store', handleStore(_from, p), _from)
     else if (p.type === MSG.CHECK) handle('check', handleCheck(_from, p), _from)
+    // ENTRAR CON USUARIO Y CONTRASEÑA. La misma pieza que usa el binario
+    // (`passwordLogins.js`), con el almacén que le ponga quien monta esta bóveda: en el
+    // navegador no hay archivos, así que lo pone el iframe de identidad.
+    else if (p.type === MSG.LOGIN_START) handle('login', handleLoginStart(_from, p), _from)
+    else if (p.type === MSG.LOGIN_FINISH) handle('login', handleLoginFinish(_from, p), _from)
+    else if (p.type === MSG.LOGIN_CLOSE) handle('login', handleLoginClose(_from, p), _from)
   })
 
+  // --- ENTRAR CON USUARIO Y CONTRASEÑA ---------------------------------------------------
+  //
+  // Sin almacén no se inventa nada: se contesta que aquí no hay inicios de sesión. Es una
+  // bóveda que no atiende esto, no una que dice que la contraseña está mal.
+  const noLogins = (from) => send(from, { type: MSG.ERROR, error: 'this vault does not keep password logins', code: 'logins-unavailable' })
+
+  /** Lo mismo desde la consola: sin almacén no se administra nada, y se dice. */
+  function needLogins () {
+    if (!logins) throw Object.assign(new Error('this vault does not keep password logins: no store was given to startDeviceVault'), { code: 'logins-unavailable' })
+    return logins
+  }
+
+  function loginError (from, e) {
+    const code = e?.code
+    if (code === 'too-many-tries') return send(from, { type: MSG.ERROR, error: e.message, code, waitMs: e.waitMs || 0 })
+    if (code === 'login-failed' || code === 'no-exchange' || code === 'bad-input' || code === 'bad-user') {
+      return send(from, { type: MSG.ERROR, error: e.message, code })
+    }
+    send(from, { type: MSG.ERROR, error: 'login failed', code: 'login-error' })
+  }
+
+  async function handleLoginStart (from, p) {
+    if (!logins) return noLogins(from)
+    try {
+      const { lid, response } = logins.loginBegin({ user: p?.user, request: p?.request })
+      send(from, { type: MSG.LOGIN_RESPONSE, lid, response })
+    } catch (e) { loginError(from, e) }
+  }
+
+  async function handleLoginFinish (from, p) {
+    if (!logins) return noLogins(from)
+    try {
+      const r = logins.loginEnd({ lid: p?.lid, finalization: p?.finalization, label: p?.label })
+      const acta = (await identity.profileActa?.().catch(() => null))?.acta || null
+      send(from, { type: MSG.LOGIN_OK, sid: r.sid, blob: r.blob, cert: r.cert, iss: r.iss || iss, acta })
+    } catch (e) { loginError(from, e) }
+  }
+
+  /** Salir va firmado con la llave que acaba de abrir: cerrar la de otro sería echarlo. */
+  async function handleLoginClose (from, p) {
+    if (!logins) return noLogins(from)
+    const d = p?.data
+    if (typeof d?.ts !== 'number' || Math.abs(Date.now() - d.ts) > FRESH_WINDOW_MS) {
+      return send(from, { type: MSG.ERROR, error: 'stale request', code: 'stale' })
+    }
+    if (d?.op !== 'login.close' || typeof d.publickey !== 'string' || typeof d.user !== 'string' || typeof d.sid !== 'string') {
+      return send(from, { type: MSG.ERROR, error: 'unauthorized: shape', code: 'bad-input' })
+    }
+    if (!(await verifyDeviceSig({ publickey: d.publickey, data: d, signature: p.signature }))) {
+      return send(from, { type: MSG.ERROR, error: 'unauthorized: bad-signature', code: 'bad-signature' })
+    }
+    const mine = logins.list().find((x) => x.user === d.user)
+    if (!mine || mine.pub !== d.publickey) {
+      return send(from, { type: MSG.ERROR, error: 'unauthorized: that key does not own this login', code: 'not-yours' })
+    }
+    send(from, { type: MSG.LOGIN_CLOSED, ok: logins.closeSession({ user: d.user, sid: d.sid }).ok })
+  }
+
   /**
    * Máquinas enroladas bajo esta identidad (P), vigentes, con scope de firma y label
    * propio (excluye navegadores enrolados con label 'cli', que no atienden peticiones).
@@ -368,6 +466,31 @@ export async function startDeviceVault (identity, { proxyUrl, client: injectedCl
     // exactamente esto.
     revoke: (nonce) => desk.revoke(nonce),
     getSelfCert,
+    // ENTRAR CON USUARIO Y CONTRASEÑA, desde la consola de esta bóveda. Es la misma pieza
+    // que el binario (`registerLogin`), para que el aparato que sale de aquí sea idéntico.
+    // Sin almacén no hay nada que administrar, y se dice en vez de contestar una lista vacía.
+    listLogins: () => needLogins().list(),
+    loginRegisterBegin: (opts) => needLogins().registerBegin(opts),
+    // El alta se trae cuando se usa: arrastra el OPAQUE en WASM (unos 260 KB) y la mayoría
+    // de las apps que usan este módulo no crean ningún inicio de sesión.
+    loginRegisterFinish: async (opts) => {
+      const { registerLogin } = await import('./passwordLogins.js')
+      return registerLogin({ ...opts, identity, logins: needLogins() })
+    },
+    // Entrar desde la propia consola, sin pasar por el proxio. Hace falta para cambiar la
+    // contraseña: el paquete de llaves se abre con la vieja y se vuelve a cerrar con la nueva.
+    loginBegin: ({ user, request }) => needLogins().loginBegin({ user, request }),
+    loginEnd: ({ lid, finalization, label }) => needLogins().loginEnd({ lid, finalization, label }),
+    closeLogin: ({ user, sid }) => needLogins().closeSession({ user, sid }),
+    clearLoginBlock: ({ user }) => needLogins().clearBlock({ user }),
+    removeLogin: ({ user }) => {
+      const store = needLogins()
+      const found = store.list().find((x) => x.user === user)
+      if (!found) return { ok: false }
+      store.remove({ user })
+      // Quitarlo de aquí no lo saca del acta: lo suyo es revocar el aparato, y eso ya existe.
+      return { ok: true, pub: found.pub, deviceId: found.deviceId }
+    },
     onPendingChange (fn) { _onPendingChange = fn || (() => {}) },
     /** Camino A: la cuenta del aparato quedó adoptada por esta bóveda. */
     onAdopted (fn) { _onAdopted = fn || (() => {}) },

package/vault/vendor/vault/loginClient.js

@@ -0,0 +1,216 @@
+/**
+ * ENTRAR CON USUARIO Y CONTRASEÑA — EL LADO DEL QUE ENTRA.
+ *
+ * La otra mitad de `passwordLogins.js`: allí está la bóveda que atiende, aquí el equipo
+ * prestado que llega sin ninguna llave y solo con una dirección escrita a mano. Diseño en
+ * `dotrino-passmanager/docs/temporary-access.md` §3.2.
+ *
+ *     nombre@AB12-CD34-EF56 + contraseña
+ *     lista el canal del código         ──►  las bóvedas de esa cuenta que estén encendidas
+ *     OPAQUE (inicio)                  ◄──►  comprueba sin ver la contraseña
+ *     abre el paquete de llaves        ◄──   { sid, blob, cert, iss, acta }
+ *     desde aquí es un aparato del acta
+ *
+ * **Vive en el pilar y no en la página** porque lo van a hacer tres sitios distintos —la
+ * pantalla de `profile.dotrino.com`, la extensión del gestor y cualquier app que ofrezca
+ * entrar— y una dirección que se lea distinto, o una comprobación que uno se salte, no es
+ * la misma puerta. Aquí no se abre ninguna conexión: el transporte se INYECTA, como en
+ * `@dotrino/identity/session-flow`.
+ *
+ * QUÉ SE COMPRUEBA, Y EN QUÉ ORDEN (importa):
+ *
+ *   1. **OPAQUE autentica a las DOS partes.** Una bóveda falsa no tiene tu registro, así
+ *      que no puede armar una respuesta que cuadre: `loginFinish` revienta en ESTE lado y
+ *      la contraseña no se le ha dicho a nadie. Por eso mandarle el primer mensaje a un
+ *      desconocido del canal no cuenta nada — es el único orden posible, porque el canal
+ *      solo da tokens y un token no dice de quién es.
+ *   2. **El acta tiene que ser de la cuenta que escribiste**: `pubkeyId(acta.profileId)`
+ *      empieza por el código de la dirección. Esto es lo que ata la respuesta a TU cuenta
+ *      y no a otra bóveda que también sepa contestar.
+ *   3. **El papel y el acta se sostienen entre sí** (`checkVaultReply`).
+ *   4. **La llave que acaba de salir del paquete es la del papel**: se firma un reto y se
+ *      verifica contra `cert.sub`. Sin esto, una bóveda podría devolver el paquete de otro.
+ *
+ * Si algo de eso falla, se PARA con un `code` propio. No hay repliegue: entrar «a medias»
+ * en una cuenta es peor que no entrar.
+ */
+import { client as opaque } from '@dotrino/opaque'
+import { pubkeyId, verifyDeviceSig, signWithDevice } from '@dotrino/identity/capabilities'
+import { checkVaultReply } from '@dotrino/identity/acta'
+import { MSG } from './protocol.js'
+import { accountCode, parseLoginAddress, vaultChannel, openDeviceKeys } from './passwordLogins.js'
+
+const err = (code, message, extra = {}) => Object.assign(new Error(message), { code, ...extra })
+
+/** Cuánto se espera a que una bóveda conteste antes de probar con la siguiente. */
+export const REPLY_TIMEOUT_MS = 15_000
+
+/**
+ * Escucha UNA respuesta de un token concreto. El `off` se suelta siempre —también al
+ * agotarse la espera—: un oyente que se queda pegado hace que el segundo intento vea la
+ * respuesta del primero.
+ */
+function waitFor (transport, from, match, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    let listo = false
+    const fin = (fn, arg) => { if (!listo) { listo = true; clearTimeout(reloj); quitar(); fn(arg) } }
+    const reloj = setTimeout(() => fin(reject, err('no-answer', 'the vault did not answer in time')), timeoutMs)
+    const oyente = (quien, payload) => {
+      if (from && quien !== from) return
+      const p = typeof payload === 'string' ? parseJson(payload) : payload
+      if (p && match(p)) fin(resolve, p)
+    }
+    const off = transport.on('message', oyente)
+    const quitar = () => {
+      if (typeof off === 'function') return off()
+      transport.off?.('message', oyente)
+    }
+  })
+}
+
+const parseJson = (s) => { try { return JSON.parse(s) } catch (_) { return null } }
+
+/**
+ * ENTRAR. Devuelve el aparato entero —sus llaves privadas, su papel y el acta— para que
+ * quien llama decida dónde vive eso: en el navegador lo adopta `@dotrino/identity` como una
+ * cuenta más; en la extensión, su propio almacén.
+ *
+ * @param {object} opts
+ * @param {object} opts.transport  cliente de `@dotrino/proxy-client` ya conectado. NO hace
+ *   falta identificarse: quien entra todavía no tiene con qué.
+ * @param {string} opts.address    `nombre@AB12-CD34-EF56`, tal como lo teclea una persona.
+ * @param {string} opts.password
+ * @param {string} [opts.label]    de dónde se entra («el cyber de la esquina»): es lo que
+ *   el dueño va a leer en su consola para decidir si cerrarlo.
+ * @returns {Promise<{user:string,address:string,code:string,sid:string,cert:object,
+ *   iss:string,acta:object,vaultToken:string,publickey:string,encPublickey:(string|null),
+ *   keys:{sign:object,enc:(object|null)}}>}
+ */
+export async function loginWithPassword ({ transport, address, password, label = '', timeoutMs = REPLY_TIMEOUT_MS } = {}) {
+  if (!transport || typeof transport.on !== 'function' || typeof transport.send !== 'function') {
+    throw err('no-transport', 'loginWithPassword: a connected transport is required')
+  }
+  if (typeof password !== 'string' || !password) throw err('no-password', 'loginWithPassword: password required')
+  const { user, code, address: dir } = parseLoginAddress(address)
+
+  const tokens = await transport.list(vaultChannel(code))
+  if (!tokens.length) {
+    throw err('no-vault', 'no vault is answering for that address right now: turn yours on, or check the address')
+  }
+
+  // De una en una, y parando en cuanto la contraseña resulte estar mal: cada intento GASTA
+  // uno del freno en la bóveda que lo atiende (`passwordLogins.js`), así que repartir el
+  // mismo error entre las réplicas solo sirve para bloquearse en todas a la vez.
+  let ultimo = null
+  for (const token of tokens) {
+    try {
+      return await unIntento({ transport, token, user, code, dir, password, label, timeoutMs })
+    } catch (e) {
+      // Se para: son cosas del que entra, y probar con otra bóveda no las arregla.
+      if (e?.code === 'login-failed' || e?.code === 'too-many-tries' || e?.code === 'wrong-account' ||
+          e?.code === 'bad-blob' || e?.code === 'bad-keys' || e?.code === 'bad-reply') throw e
+      ultimo = e   // «esa no atiende inicios de sesión», «no contestó»: quizá la siguiente sí
+    }
+  }
+  throw ultimo || err('no-vault', 'none of the vaults on that address could let you in')
+}
+
+async function unIntento ({ transport, token, user, code, dir, password, label, timeoutMs }) {
+  const start = opaque.loginStart({ password })
+  transport.send(token, { type: MSG.LOGIN_START, user, request: start.request })
+  const r1 = await waitFor(transport, token, (p) => p.type === MSG.LOGIN_RESPONSE || p.type === MSG.ERROR, timeoutMs)
+  if (r1.type === MSG.ERROR) throw deVuelta(r1)
+
+  let fin
+  try {
+    fin = opaque.loginFinish({ state: start.state, response: r1.response, password })
+  } catch (_) {
+    // OPAQUE comprueba a las dos partes: aquí se sabe que el otro lado NO conoce el
+    // registro de este usuario. Contraseña equivocada, usuario que no existe o una bóveda
+    // que no es la tuya — y son el mismo error a propósito, porque distinguirlos diría
+    // desde fuera qué usuarios hay.
+    throw err('login-failed', 'wrong address or password')
+  }
+
+  transport.send(token, { type: MSG.LOGIN_FINISH, lid: r1.lid, finalization: fin.finalization, label })
+  const ok = await waitFor(transport, token, (p) => p.type === MSG.LOGIN_OK || p.type === MSG.ERROR, timeoutMs)
+  if (ok.type === MSG.ERROR) throw deVuelta(ok)
+
+  const acta = ok.acta
+  const cert = ok.cert
+  if (!acta || !cert?.sub) throw err('bad-reply', 'the vault let you in without saying which account this is')
+
+  // 2. ¿ES LA CUENTA QUE ESCRIBISTE? Es la única comprobación que ata todo esto a lo que la
+  //    persona tecleó: el canal no prueba nada y el acta viene de quien contesta.
+  if (accountCode((await pubkeyId(acta.profileId)).slice(0, 16)) !== code) {
+    throw err('wrong-account', 'that vault serves a different account than the address says')
+  }
+  // 3. El papel lo firmó esa bóveda, esa bóveda puede sellar esta acta, y el papel vale
+  //    según ella. Una sola llamada, la misma que usa el enrolamiento.
+  const v = await checkVaultReply({ acta, cert, vault: ok.iss, sub: cert.sub })
+  if (!v.ok) throw err('bad-reply', 'the vault reply does not hold together: ' + v.reason)
+
+  const keys = await openDeviceKeys(fin.exportKey, ok.blob)   // `bad-blob` si no es el paquete
+  if (!keys?.sign) throw err('bad-blob', 'the key package does not carry a signing key')
+
+  // 4. La llave que salió del paquete tiene que SER la del papel. Se prueba firmando.
+  const reto = { op: 'login.proof', sub: cert.sub, sid: ok.sid, ts: Date.now() }
+  const { signature } = await signWithDevice({ privateJwk: keys.sign, data: reto })
+  if (!(await verifyDeviceSig({ publickey: cert.sub, data: reto, signature }))) {
+    throw err('bad-keys', 'the keys in the package are not the ones this certificate is for')
+  }
+
+  const member = (acta.members || []).find((m) => m?.pub === cert.sub)
+  if (!member) throw err('bad-reply', 'that certificate names a key the account record does not list')
+
+  return {
+    user,
+    address: dir,
+    code,
+    sid: ok.sid,
+    cert,
+    iss: ok.iss,
+    acta,
+    vaultToken: token,
+    publickey: cert.sub,
+    // La pública de CIFRADO la dice el acta, no el paquete: es lo que los demás miran para
+    // envolverle un secreto a este aparato, y tiene que ser la misma que ellos ven.
+    encPublickey: member.encPub || null,
+    caps: [...(member.caps || [])],
+    keys: { sign: keys.sign, enc: keys.enc || null }
+  }
+}
+
+/** Un error de la bóveda con su `code` intacto: `too-many-tries` se arregla esperando. */
+function deVuelta (p) {
+  const code = p.code || 'login-error'
+  const e = err(code, p.error || 'the vault refused the login')
+  if (typeof p.waitMs === 'number') e.waitMs = p.waitMs
+  return e
+}
+
+/**
+ * SALIR. Va firmado con la llave que acabas de abrir —cerrar el inicio de sesión de otro
+ * sería echarlo de su cuenta— y es lo que suelta la plaza en la bóveda; lo que se borre en
+ * este navegador es cosa de quien llama.
+ *
+ * Es «mejor esfuerzo» a propósito: si la bóveda está apagada, salir de este equipo no puede
+ * quedarse bloqueado esperándola. La sesión sigue abierta allí hasta que se cierre desde la
+ * consola, y eso ya está dicho en el diseño (§3.2).
+ */
+export async function closeLogin ({ transport, token, user, sid, publickey, privateJwk, privateKey, timeoutMs = REPLY_TIMEOUT_MS } = {}) {
+  if (!transport || typeof transport.send !== 'function') throw err('no-transport', 'closeLogin: transport required')
+  if (!token || !user || !sid || !publickey) throw err('bad-input', 'closeLogin: token, user, sid and publickey are required')
+  const data = { op: 'login.close', publickey, user, sid, ts: Date.now() }
+  const { signature } = await signWithDevice({ privateJwk, privateKey, publickey, data })
+  transport.send(token, { type: MSG.LOGIN_CLOSE, data, signature })
+  try {
+    const r = await waitFor(transport, token, (p) => p.type === MSG.LOGIN_CLOSED || p.type === MSG.ERROR, timeoutMs)
+    if (r.type === MSG.ERROR) return { ok: false, reason: r.code || 'login-error' }
+    return { ok: !!r.ok }
+  } catch (e) {
+    return { ok: false, reason: e?.code || 'no-answer' }
+  }
+}
+
+export default { loginWithPassword, closeLogin, REPLY_TIMEOUT_MS }