@dotrino/identity 0.10.0

package/src/index.js

@@ -0,0 +1,367 @@
+/**
+ * Dotrino Identity client.
+ *
+ * Loads a hidden iframe pointing at the vault origin and exchanges
+ * postMessage requests. The vault holds the user's keypair and the
+ * peer ratings/nicknames in its own localStorage, so all apps that
+ * use this library share identity even across different origins.
+ */
+
+const DEFAULT_VAULT_URL = 'https://id.dotrino.com/'
+
+let singleton = null
+
+export class Identity {
+  constructor (options = {}) {
+    this.vaultUrl = options.vaultUrl || DEFAULT_VAULT_URL
+    this.timeoutMs = options.timeoutMs ?? 5000
+    this._iframe = null
+    this._ready = null
+    this._readyResolve = null
+    this._nextId = 1
+    this._pending = new Map()
+    this._handler = null
+    this._me = null
+  }
+
+  static async connect (options = {}) {
+    if (!singleton) singleton = new Identity(options)
+    // Esperar SIEMPRE a ready(): si otro caller creó el singleton pero su
+    // handshake con el vault aún no resolvió, devolver el singleton "pelado"
+    // dejaba `me` en null y las apps no encontraban el nickname (carrera).
+    // ready() es idempotente (devuelve la misma promesa), así que esto es
+    // seguro de llamar en cada connect().
+    await singleton.ready()
+    return singleton
+  }
+
+  static current () {
+    return singleton
+  }
+
+  ready () {
+    if (this._ready) return this._ready
+
+    this._ready = new Promise((resolve, reject) => {
+      this._readyResolve = resolve
+
+      const iframe = document.createElement('iframe')
+      iframe.src = this.vaultUrl
+      iframe.style.display = 'none'
+      iframe.setAttribute('aria-hidden', 'true')
+      iframe.setAttribute('title', 'Dotrino identity vault')
+      iframe.referrerPolicy = 'origin'
+      this._iframe = iframe
+
+      const timeout = setTimeout(() => {
+        reject(new Error(`Vault did not respond within ${this.timeoutMs}ms`))
+      }, this.timeoutMs)
+
+      this._handler = (event) => {
+        if (event.source !== iframe.contentWindow) return
+        const msg = event.data
+        if (!msg || msg._cci !== true) return
+
+        if (msg.type === 'ready') {
+          clearTimeout(timeout)
+          this._me = msg.me
+          this._readyResolve(this)
+          return
+        }
+
+        if (msg.type === 'response') {
+          const pending = this._pending.get(msg.id)
+          if (!pending) return
+          this._pending.delete(msg.id)
+          clearTimeout(pending.timer)
+          if (msg.error) pending.reject(new Error(msg.error))
+          else pending.resolve(msg.result)
+          return
+        }
+
+        if (msg.type === 'event') {
+          this._emit(msg.event, msg.payload)
+        }
+      }
+
+      window.addEventListener('message', this._handler)
+      document.body.appendChild(iframe)
+    })
+
+    return this._ready
+  }
+
+  destroy () {
+    if (this._handler) window.removeEventListener('message', this._handler)
+    if (this._iframe && this._iframe.parentNode) this._iframe.parentNode.removeChild(this._iframe)
+    this._iframe = null
+    this._handler = null
+    if (singleton === this) singleton = null
+  }
+
+  // ----- public API -----
+
+  get me () { return this._me }
+
+  /**
+   * Identify a peer by token: the peer must respond to our challenge by
+   * signing it with their private key. The vault holds and applies the rating.
+   *
+   * The host app is responsible for delivering the challenge to the peer
+   * and bringing back the signed response — see makeChallenge / verifyResponse.
+   */
+  async makeChallenge () {
+    return this._call('makeChallenge')
+  }
+
+  async signChallenge (nonce) {
+    return this._call('signChallenge', { nonce })
+  }
+
+  async verifyResponse ({ nonce, publickey, signature }) {
+    return this._call('verifyResponse', { nonce, publickey, signature })
+  }
+
+  async getPeer (publickey) {
+    return this._call('getPeer', { publickey })
+  }
+
+  async setNickname (publickey, nickname) {
+    return this._call('setNickname', { publickey, nickname })
+  }
+
+  async setRating (publickey, rating, notes) {
+    return this._call('setRating', { publickey, rating, notes })
+  }
+
+  async listPeers () {
+    return this._call('listPeers')
+  }
+
+  async forgetPeer (publickey) {
+    return this._call('forgetPeer', { publickey })
+  }
+
+  /**
+   * Add (or refresh) a contact in the shared address book. Idempotent —
+   * existing peer records are upserted with the new metadata. Contacts are
+   * stored alongside the rating/endorsement record for the same pubkey, so
+   * any app in the ecosystem (chat, chess, messenger, …) sees the same list.
+   */
+  async addContact ({ publickey, nickname, encryptionPubkey, lastToken, notes } = {}) {
+    return this._call('addContact', { publickey, nickname, encryptionPubkey, lastToken, notes })
+  }
+
+  /** Patch contact metadata (nickname / lastToken / encryptionPubkey / contactNotes). */
+  async updateContact (publickey, patch) {
+    return this._call('updateContact', { publickey, patch })
+  }
+
+  /** Remove the `isContact` flag while preserving rating/endorsement history. */
+  async removeContact (publickey) {
+    return this._call('removeContact', { publickey })
+  }
+
+  /** List peers flagged as contacts, sorted by lastSeen desc. */
+  async listContacts () {
+    return this._call('listContacts')
+  }
+
+  /**
+   * Sign an arbitrary JSON-serializable payload with the vault's ECDSA key
+   * using canonical JSON encoding. Returns `{ signature, publickey }` —
+   * compatible with the proxy's `verifySignatureWithJWK` (used by
+   * `identify` to bind a stable pubkey to the proxy connection).
+   */
+  async signData (data) {
+    return this._call('signData', { data })
+  }
+
+  /**
+   * Firma un CERTIFICADO DE DELEGACIÓN: autoriza a una sub-clave de dispositivo
+   * `sub` (JWK string) a hacer `scope` en tu nombre, hasta `exp`, revocable por
+   * `nonce`. La clave maestra NUNCA sale del vault. `opts`: { ttlMs?, exp?, label?, nonce? }.
+   * @returns {Promise<{ cert: object }>}
+   */
+  async signDelegation (sub, scope, opts = {}) {
+    return this._call('signDelegation', { sub, scope, ...opts })
+  }
+
+  /** Revoca una delegación por su `nonce` (queda en la lista de revocación). */
+  async revokeDelegation (nonce) {
+    return this._call('revokeDelegation', { nonce })
+  }
+
+  /** Lista las delegaciones emitidas + la lista de revocación (para el gestor de dispositivos). */
+  async listDelegations () {
+    return this._call('listDelegations')
+  }
+
+  /**
+   * Merge endorsements (signed ratings from third parties) about a subject
+   * into the local peer book. Returns { merged, total }.
+   */
+  async mergeEndorsements (subject, endorsements, askerPubkey) {
+    return this._call('mergeEndorsements', { subject, endorsements, askerPubkey })
+  }
+
+  /**
+   * Return what this vault knows about a subject for the purpose of
+   * answering a RATING_QUERY: { mine: signedEnvelopeOrNull, endorsements: [] }.
+   */
+  async getRatingsForSubject (subject) {
+    return this._call('getRatingsForSubject', { subject })
+  }
+
+  /**
+   * Record that a peer asked us about a subject. Used for suspicion stats.
+   */
+  async recordQuery (askerPubkey, subject) {
+    return this._call('recordQuery', { askerPubkey, subject })
+  }
+
+  /** Update own nickname (broadcast to the vault, not to other apps automatically) */
+  async setMyNickname (nickname) {
+    const result = await this._call('setMyNickname', { nickname })
+    if (result?.me) this._me = result.me
+    return result
+  }
+
+  /** Pubkey ECDH (JWK string) propio para encripción. */
+  async getEncryptionPubkey () {
+    return this._call('getEncryptionPubkey')
+  }
+
+  /**
+   * Cifra `plaintext` para una lista de destinatarios usando ECDH+AES-GCM.
+   * @param {Array<{token:string, encryptionPubkey:string}>} recipients
+   * @param {string} plaintext
+   * @returns {Promise<Object>} Envelope { v, iv, ct, wrap }
+   */
+  async encrypt (recipients, plaintext) {
+    return this._call('encrypt', { recipients, plaintext })
+  }
+
+  /**
+   * Descifra un envelope dirigido a este vault.
+   * @param {string} senderEncryptionPubkey JWK string del emisor
+   * @param {string} myToken token efímero al que iba dirigido el wrap
+   * @param {Object} envelope
+   */
+  async decrypt (senderEncryptionPubkey, myToken, envelope) {
+    return this._call('decrypt', { senderEncryptionPubkey, myToken, envelope })
+  }
+
+  /**
+   * Export the full identity (private key + peer book) as a JSON-serializable object.
+   * The blob can be saved to a file by the host app and re-imported later.
+   * The private key is sensitive — handle accordingly.
+   */
+  async exportIdentity () {
+    return this._call('exportIdentity')
+  }
+
+  /**
+   * Import a previously exported identity blob, replacing the current one.
+   * Throws if the blob is malformed or keys are invalid.
+   */
+  async importIdentity (blob) {
+    const result = await this._call('importIdentity', blob)
+    if (result?.me) this._me = result.me
+    return result
+  }
+
+  // ----- Auto-sync (Google Drive encrypted backup) -----
+
+  /**
+   * Connect a Google account for encrypted backup to Drive's appDataFolder.
+   * Pops up a Google sign-in window. `clientId` is your Google OAuth Web client ID
+   * with Authorized JavaScript Origin = the vault origin (id.dotrino.com).
+   */
+  async syncConnect (clientId) {
+    return this._call('syncConnect', { clientId })
+  }
+
+  async syncDisconnect () {
+    return this._call('syncDisconnect')
+  }
+
+  /**
+   * Unlock auto-sync by providing the passphrase used to encrypt the backup.
+   * Must be ≥ 8 chars. After unlock the sync engine pulls remote, merges,
+   * and pushes on every local change (debounced).
+   */
+  async syncUnlock (passphrase) {
+    return this._call('syncUnlock', { passphrase })
+  }
+
+  async syncLock () {
+    return this._call('syncLock')
+  }
+
+  /** { connected, unlocked, dirty, lastError } */
+  async syncStatus () {
+    return this._call('syncStatus')
+  }
+
+  /** Force an immediate pull-then-push cycle. */
+  async syncNow () {
+    return this._call('syncNow')
+  }
+
+  /**
+   * Subscribe to sync status events emitted by the vault. Handler receives
+   * `{ kind, status, error?, ts }` where status is one of
+   * 'connected' | 'disconnected' | 'unlocked' | 'locked' | 'syncing' |
+   * 'synced' | 'conflict' | 'offline' | 'error'.
+   */
+  onSync (handler) {
+    return this.on('sync', handler)
+  }
+
+  on (event, handler) {
+    if (!this._listeners) this._listeners = new Map()
+    if (!this._listeners.has(event)) this._listeners.set(event, new Set())
+    this._listeners.get(event).add(handler)
+    return () => this._listeners.get(event)?.delete(handler)
+  }
+
+  _emit (event, payload) {
+    const set = this._listeners?.get(event)
+    if (!set) return
+    for (const h of set) {
+      try { h(payload) } catch (e) { console.error(e) }
+    }
+  }
+
+  _call (method, params = {}) {
+    return new Promise((resolve, reject) => {
+      if (!this._iframe?.contentWindow) {
+        return reject(new Error('Vault not ready'))
+      }
+      const id = `req_${this._nextId++}`
+      const timer = setTimeout(() => {
+        this._pending.delete(id)
+        reject(new Error(`Vault timeout for ${method}`))
+      }, this.timeoutMs)
+      this._pending.set(id, { resolve, reject, timer })
+
+      // Usamos targetOrigin='*' por compatibilidad: en algunos navegadores el
+      // origin que el browser asocia al postMessage SALIENTE no coincide con
+      // el de las respuestas (mismatch interno tras la navegación cross-origin
+      // del iframe), provocando rechazos espurios. El handler del lado padre
+      // sí filtra `event.source === iframe.contentWindow` y `_cci === true`,
+      // lo cual es la defensa real. El contenido de los mensajes salientes
+      // no contiene secretos (solo nombres de método y params); las claves
+      // privadas viven en el localStorage de la propia vault.
+      this._iframe.contentWindow.postMessage(
+        { _cci: true, type: 'request', id, method, params },
+        '*'
+      )
+    })
+  }
+}
+
+// Helpers de capacidad SIN clave maestra (lado dispositivo + verificación), reutilizables
+// por apps/bridges sin cargar el iframe del vault.
+export { makeDeviceKey, signWithDevice, verifyDelegation, verifyChain, pubkeyId, MAX_DELEGATION_MS, DEFAULT_DELEGATION_MS } from '../vault/capabilities.js'

package/src/node.js

@@ -0,0 +1,179 @@
+/**
+ * Dotrino Identity — adaptador headless para Node.js.
+ *
+ * Expone la MISMA API pública que el cliente de navegador (`./index.js`), pero
+ * sin iframe ni postMessage: llama directamente a los handlers de
+ * `../vault/core.js`. El keypair, `me`, los nonces y el peer book se persisten
+ * en archivos JSON dentro de un directorio por identidad, de modo que cada
+ * directorio es un "usuario" distinto y estable entre ejecuciones.
+ *
+ * La criptografía es byte-idéntica a la del vault del navegador (mismo core),
+ * así que un bot Node es plenamente interoperable con usuarios reales:
+ * firmas verificables por el proxy e `identify`, y cifrado E2E (ECDH+AES-GCM)
+ * descifrable por la app web y viceversa.
+ *
+ * Requiere Node ≥ 20 (crypto.subtle, btoa/atob, TextEncoder globales).
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+import os from 'node:os'
+import { createIdentityCore } from '../vault/core.js'
+
+/** kv síncrono respaldado por un archivo JSON (estilo localStorage). */
+function fileKv (filePath) {
+  let data = {}
+  try {
+    if (fs.existsSync(filePath)) data = JSON.parse(fs.readFileSync(filePath, 'utf8')) || {}
+  } catch (_) { data = {} }
+  const flush = () => {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true })
+    fs.writeFileSync(filePath, JSON.stringify(data))
+  }
+  return {
+    getItem: (k) => (k in data ? data[k] : null),
+    setItem: (k, v) => { data[k] = String(v); flush() },
+    removeItem: (k) => { delete data[k]; flush() }
+  }
+}
+
+/** Peer book respaldado por un archivo JSON (interfaz de vault/peerStore.js). */
+function filePeers (filePath) {
+  let peers = {}
+  let markDirty = null
+  const flush = () => {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true })
+    fs.writeFileSync(filePath, JSON.stringify(peers))
+  }
+  return {
+    async initPeerStorage () {
+      try {
+        if (fs.existsSync(filePath)) peers = JSON.parse(fs.readFileSync(filePath, 'utf8')) || {}
+      } catch (_) { peers = {} }
+      return peers
+    },
+    loadPeers: () => peers,
+    savePeers: (next) => { peers = next; flush(); if (markDirty) markDirty() },
+    setPeersDirect: (next) => { peers = next; flush() },
+    upsertPeer: (publickey, patch) => {
+      const existing = peers[publickey] || { publickey, firstSeen: Date.now() }
+      peers[publickey] = { ...existing, ...patch, publickey, lastSeen: Date.now() }
+      flush()
+      if (markDirty) markDirty()
+      return peers[publickey]
+    },
+    onDirty: (fn) => { markDirty = fn }
+  }
+}
+
+const DEFAULT_DIR = path.join(os.homedir(), '.dotrino', 'identity')
+
+export class Identity {
+  /**
+   * @param {Object} [options]
+   * @param {string} [options.dir]  Directorio de persistencia de esta identidad.
+   *   Cada directorio = un usuario distinto. Default: ~/.dotrino/identity
+   */
+  constructor (options = {}) {
+    this._dir = options.dir || DEFAULT_DIR
+    this._core = null
+    this._listeners = new Map()
+  }
+
+  /**
+   * Crea/abre una identidad headless. A diferencia del navegador NO es singleton:
+   * cada `dir` distinto devuelve una identidad independiente (para correr muchos
+   * bots-usuario en el mismo proceso).
+   */
+  static async connect (options = {}) {
+    const inst = new Identity(options)
+    await inst.ready()
+    return inst
+  }
+
+  async ready () {
+    if (this._core) return this
+    this._core = await createIdentityCore({
+      kv: fileKv(path.join(this._dir, 'identity.json')),
+      peers: filePeers(path.join(this._dir, 'peers.json')),
+      makeSync: null
+    })
+    this._core.onSyncStatus((payload) => this._emit('sync', payload))
+    return this
+  }
+
+  destroy () { this._core = null }
+
+  get me () { return this._core?.me || null }
+
+  _h (method, params = {}) {
+    if (!this._core) throw new Error('Identity not ready — call ready()/connect() first')
+    return this._core.handlers[method](params)
+  }
+
+  // ----- API pública (espeja src/index.js) -----
+
+  makeChallenge () { return this._h('makeChallenge') }
+  signChallenge (nonce) { return this._h('signChallenge', { nonce }) }
+  verifyResponse ({ nonce, publickey, signature, encryptionPubkey }) {
+    return this._h('verifyResponse', { nonce, publickey, signature, encryptionPubkey })
+  }
+  getPeer (publickey) { return this._h('getPeer', { publickey }) }
+  setNickname (publickey, nickname) { return this._h('setNickname', { publickey, nickname }) }
+  setRating (publickey, rating, notes) { return this._h('setRating', { publickey, rating, notes }) }
+  listPeers () { return this._h('listPeers') }
+  forgetPeer (publickey) { return this._h('forgetPeer', { publickey }) }
+  addContact ({ publickey, nickname, encryptionPubkey, lastToken, notes } = {}) {
+    return this._h('addContact', { publickey, nickname, encryptionPubkey, lastToken, notes })
+  }
+  updateContact (publickey, patch) { return this._h('updateContact', { publickey, patch }) }
+  removeContact (publickey) { return this._h('removeContact', { publickey }) }
+  listContacts () { return this._h('listContacts') }
+  signData (data) { return this._h('signData', { data }) }
+  // Delegación de capacidad (sub-clave de dispositivo con scope/exp/revocación)
+  signDelegation (sub, scope, opts = {}) { return this._h('signDelegation', { sub, scope, ...opts }) }
+  revokeDelegation (nonce) { return this._h('revokeDelegation', { nonce }) }
+  listDelegations () { return this._h('listDelegations') }
+  mergeEndorsements (subject, endorsements, askerPubkey) {
+    return this._h('mergeEndorsements', { subject, endorsements, askerPubkey })
+  }
+  getRatingsForSubject (subject) { return this._h('getRatingsForSubject', { subject }) }
+  recordQuery (askerPubkey, subject) { return this._h('recordQuery', { askerPubkey, subject }) }
+  async setMyNickname (nickname) {
+    const result = await this._h('setMyNickname', { nickname })
+    return result
+  }
+  getEncryptionPubkey () { return this._h('getEncryptionPubkey') }
+  encrypt (recipients, plaintext) { return this._h('encrypt', { recipients, plaintext }) }
+  decrypt (senderEncryptionPubkey, myToken, envelope) {
+    return this._h('decrypt', { senderEncryptionPubkey, myToken, envelope })
+  }
+  exportIdentity () { return this._h('exportIdentity') }
+  async importIdentity (blob) { return this._h('importIdentity', blob || {}) }
+
+  // Sync (Google Drive) no disponible headless — los handlers responden acorde.
+  syncConnect (clientId) { return this._h('syncConnect', { clientId }) }
+  syncDisconnect () { return this._h('syncDisconnect') }
+  syncUnlock (passphrase) { return this._h('syncUnlock', { passphrase }) }
+  syncLock () { return this._h('syncLock') }
+  syncStatus () { return this._h('syncStatus') }
+  syncNow () { return this._h('syncNow') }
+
+  onSync (handler) { return this.on('sync', handler) }
+  on (event, handler) {
+    if (!this._listeners.has(event)) this._listeners.set(event, new Set())
+    this._listeners.get(event).add(handler)
+    return () => this._listeners.get(event)?.delete(handler)
+  }
+  _emit (event, payload) {
+    const set = this._listeners.get(event)
+    if (!set) return
+    for (const h of set) { try { h(payload) } catch (e) { console.error(e) } }
+  }
+}
+
+export default Identity
+
+// Helpers de capacidad SIN clave maestra (lado dispositivo + verificación), para que
+// un bridge/bot Node pueda crear su clave, firmar acciones y verificar cadenas D←P.
+export { makeDeviceKey, signWithDevice, verifyDelegation, verifyChain, pubkeyId, MAX_DELEGATION_MS, DEFAULT_DELEGATION_MS } from '../vault/capabilities.js'

package/vault/CNAME

@@ -0,0 +1 @@
+id.dotrino.com

package/vault/capabilities.js

@@ -0,0 +1,143 @@
+/**
+ * Tokens de CAPACIDAD DELEGADOS, firmados por el vault.
+ *
+ * Problema: un dispositivo (p.ej. el bridge de OwnTracks, un bot, el launcher)
+ * necesita actuar EN NOMBRE de una identidad SIN tener su clave maestra. Si le
+ * diéramos la clave maestra, robar el dispositivo = robar la identidad.
+ *
+ * Solución (subkeys / capabilities, estilo certs SSH / OAuth device tokens):
+ *   - El dispositivo genera SU PROPIA clave `D` (la maestra nunca la ve).
+ *   - El vault firma un CERTIFICADO: «la clave D puede `scope` para la identidad P,
+ *     hasta `exp`», con un `nonce` que es el mango de revocación.
+ *   - El dispositivo firma cada acción con `D` y adjunta el cert. Cualquiera
+ *     verifica la CADENA `D ← P` + scope + expiración + revocación, offline.
+ *
+ * Garantía: robar el dispositivo solo permite lo del `scope` (p.ej. publicar
+ * ubicación), hasta `exp`, y se puede revocar. La clave maestra queda intacta.
+ *
+ * Cripto IDÉNTICA al resto del ecosistema: ECDSA P-256 + SHA-256 sobre
+ * `canonicalStringify`, firma en base64 de los 64 bytes crudos (r||s). Módulo
+ * PURO (sin kv/iframe/localStorage) → reusable en el vault, en Node y en el
+ * servidor de geo sin cargar el iframe.
+ */
+import { canonicalStringify, bufToBase64, base64ToBuf } from './core.js'
+
+const ECDSA = { name: 'ECDSA', namedCurve: 'P-256' }
+const SIGN = { name: 'ECDSA', hash: { name: 'SHA-256' } }
+
+/** Tope DURO de vida de una delegación (aunque pidan más). */
+export const MAX_DELEGATION_MS = 30 * 24 * 60 * 60 * 1000   // 30 días
+/** Vida por defecto si no se especifica ttl/exp. */
+export const DEFAULT_DELEGATION_MS = 24 * 60 * 60 * 1000    // 24 h
+
+const enc = (s) => new TextEncoder().encode(s)
+
+async function rawSign (privateKey, bytes) {
+  return bufToBase64(await crypto.subtle.sign(SIGN, privateKey, bytes))
+}
+async function rawVerify (publicJwkStr, bytes, sigB64) {
+  let pub
+  try { pub = await crypto.subtle.importKey('jwk', JSON.parse(publicJwkStr), ECDSA, true, ['verify']) }
+  catch (_) { return false }
+  try { return await crypto.subtle.verify(SIGN, pub, base64ToBuf(sigB64), bytes) }
+  catch (_) { return false }
+}
+
+const publicOf = (privateJwk) => ({ kty: privateJwk.kty, crv: privateJwk.crv, x: privateJwk.x, y: privateJwk.y })
+const scopeAllows = (scope, expected) => Array.isArray(scope) ? scope.includes(expected) : scope === expected
+
+/** id corto y estable de un pubkey (sha-256 hex de los campos canónicos del JWK). */
+export async function pubkeyId (publicJwkStr) {
+  const jwk = typeof publicJwkStr === 'string' ? JSON.parse(publicJwkStr) : publicJwkStr
+  const h = await crypto.subtle.digest('SHA-256', enc(canonicalStringify({ crv: jwk.crv, kty: jwk.kty, x: jwk.x, y: jwk.y })))
+  return [...new Uint8Array(h)].map(b => b.toString(16).padStart(2, '0')).join('')
+}
+
+/** Cuerpo canónico del certificado (lo que se firma): el cert SIN la firma. */
+export function delegationBody (cert) {
+  return { v: cert.v, iss: cert.iss, sub: cert.sub, scope: cert.scope, iat: cert.iat, exp: cert.exp, nonce: cert.nonce }
+}
+
+/**
+ * Genera una sub-clave de DISPOSITIVO `D`. Corre EN el dispositivo / bridge; la
+ * clave maestra nunca ve la privada. Solo `publickey` (JWK string) sale del device.
+ */
+export async function makeDeviceKey ({ label = '' } = {}) {
+  const pair = await crypto.subtle.generateKey(ECDSA, true, ['sign', 'verify'])
+  const privateJwk = await crypto.subtle.exportKey('jwk', pair.privateKey)
+  const publicJwk = await crypto.subtle.exportKey('jwk', pair.publicKey)
+  const publickey = JSON.stringify(publicJwk)
+  return { publickey, privateJwk, publicJwk, label: String(label || ''), createdAt: Date.now(), deviceId: await pubkeyId(publickey) }
+}
+
+/**
+ * Firma un certificado de delegación con una `privateKey` (CryptoKey) cuyo pubkey
+ * es `iss`. Lo usa el handler del vault (con la clave maestra). Devuelve el cert
+ * completo `{ v, iss, sub, scope, iat, exp, nonce, sig }`.
+ */
+export async function signDelegationWith (privateKey, iss, { sub, scope, iat, exp, nonce }) {
+  const body = { v: 1, iss, sub, scope, iat, exp, nonce }
+  const sig = await rawSign(privateKey, enc(canonicalStringify(body)))
+  return { ...body, sig }
+}
+
+/**
+ * Firma datos con la clave de DISPOSITIVO (formato byte-idéntico a `signData` del
+ * vault → lo que el dispositivo/bridge usa para firmar cada pin/acción).
+ */
+export async function signWithDevice ({ privateJwk, data }) {
+  const priv = await crypto.subtle.importKey('jwk', privateJwk, ECDSA, true, ['sign'])
+  const signature = await rawSign(priv, enc(canonicalStringify(data)))
+  return { signature, publickey: JSON.stringify(publicOf(privateJwk)) }
+}
+
+/**
+ * Verifica un CERTIFICADO de delegación (offline; no requiere la clave maestra):
+ *   1) firma de la maestra (`iss`) sobre el cuerpo canónico,
+ *   2) ventana temporal `iat ≤ now ≤ exp`,
+ *   3) `scope` incluye `expectedScope` (si se pide),
+ *   4) `sub` === `expectedSub` (si se pide),
+ *   5) `nonce` no revocado (`revoked`: fn(nonce)→bool, Set o mapa).
+ * @returns {{ok:boolean, reason?:string, iss?, sub?, scope?, iat?, exp?, nonce?}}
+ */
+export async function verifyDelegation ({ cert, expectedScope, expectedSub, now = Date.now(), skewMs = 0, revoked } = {}) {
+  if (!cert || typeof cert !== 'object') return { ok: false, reason: 'no-cert' }
+  const { v, iss, sub, scope, iat, exp, nonce, sig } = cert
+  if (v !== 1 || typeof iss !== 'string' || typeof sub !== 'string' || typeof sig !== 'string') return { ok: false, reason: 'shape' }
+  if (typeof iat !== 'number' || typeof exp !== 'number' || (typeof scope !== 'string' && !Array.isArray(scope))) return { ok: false, reason: 'shape' }
+  if (!(await rawVerify(iss, enc(canonicalStringify(delegationBody(cert))), sig))) return { ok: false, reason: 'bad-signature' }
+  // `skewMs` tolera la diferencia de reloj entre el EMISOR (vault) y el VERIFICADOR
+  // (p.ej. el bridge de geo, otra máquina). Default 0 = estricto.
+  const sk = Math.max(0, skewMs)
+  if (now < iat - sk) return { ok: false, reason: 'not-yet-valid' }
+  if (now > exp + sk) return { ok: false, reason: 'expired' }
+  if (expectedScope != null && !scopeAllows(scope, expectedScope)) return { ok: false, reason: 'scope' }
+  if (expectedSub != null && sub !== expectedSub) return { ok: false, reason: 'sub' }
+  if (nonce && revoked) {
+    const isRev = typeof revoked === 'function' ? revoked(nonce)
+      : (revoked instanceof Set ? revoked.has(nonce) : !!revoked[nonce])
+    if (isRev) return { ok: false, reason: 'revoked' }
+  }
+  return { ok: true, iss, sub, scope, iat, exp, nonce }
+}
+
+/**
+ * Verificación de CADENA de una acción/pin delegado (lo único que llama el bridge):
+ *   1) el dispositivo `D` (= `data.publickey`) firmó `data`,
+ *   2) el cert delega a ESTE dispositivo (`cert.sub === data.publickey`),
+ *   3) el cert es válido (firma de `P`, scope, exp, revocación),
+ *   4) opcional: `cert.iss === trustedIssuer` (fija la identidad maestra esperada).
+ * @returns {{ok:boolean, reason?:string, issuer?:string, device?:string}}
+ */
+export async function verifyChain ({ data, signature, cert, expectedScope, expectedIssuer, trustedIssuer, now = Date.now(), skewMs = 0, revoked } = {}) {
+  if (!data || typeof data !== 'object' || typeof signature !== 'string') return { ok: false, reason: 'shape' }
+  const device = data.publickey
+  if (typeof device !== 'string') return { ok: false, reason: 'no-device-pubkey' }
+  if (!(await rawVerify(device, enc(canonicalStringify(data)), signature))) return { ok: false, reason: 'bad-action-signature' }
+  if (!cert || cert.sub !== device) return { ok: false, reason: 'cert-device-mismatch' }
+  const d = await verifyDelegation({ cert, expectedScope, now, skewMs, revoked })
+  if (!d.ok) return { ok: false, reason: d.reason }
+  const issuer = trustedIssuer != null ? trustedIssuer : expectedIssuer
+  if (issuer != null && cert.iss !== issuer) return { ok: false, reason: 'untrusted-issuer' }
+  return { ok: true, issuer: cert.iss, device }
+}