terminal-smart-cli 0.98.1 → 0.99.0

package/hub/proto/ts-proto.js

@@ -0,0 +1,1643 @@
+/*
+ * ts-proto.js — protocolo e criptografia do hub do Terminal Smart (versão 1).
+ *
+ * Um único arquivo UMD, sem dependências, que roda igual:
+ *   - no Node 22+:   const TsProto = require('./ts-proto.js')   (usa globalThis.crypto.subtle)
+ *   - no navegador:  <script src="ts-proto.js"></script>         (expõe globalThis.TsProto)
+ *
+ * Só WebCrypto: ECDSA P-256 (assinatura), ECDH P-256 (efêmero por sessão), HKDF-SHA256,
+ * AES-256-GCM, SHA-256 e getRandomValues. A especificação completa está em PROTOCOLO.md,
+ * na mesma pasta; este arquivo é a implementação de referência dela.
+ *
+ * Regras que o código segue em todo lugar:
+ *   - Nada aqui escreve em log. Erros são TsProtoErro com um `codigo` estável e uma mensagem
+ *     fixa, sem eco de dados recebidos nem de segredos.
+ *   - Toda entrada externa é validada com esquema fechado (campo a mais ou a menos = recusa).
+ *   - Segredos (segredo do convite, chaves de pareamento e de sessão) ficam em WeakMap ou
+ *     em CryptoKey não exportável, para não vazarem por JSON.stringify ou console.log.
+ */
+(function (raiz, fabrica) {
+  'use strict';
+  var api = fabrica(raiz);
+  if (typeof module === 'object' && module && module.exports) module.exports = api;
+  else raiz.TsProto = api;
+})(typeof globalThis !== 'undefined' ? globalThis : this, function (g) {
+  'use strict';
+
+  // ===========================================================================================
+  // Constantes
+  // ===========================================================================================
+
+  const VERSAO = 1;
+  const PREFIXO = 'ts-hub/1/';
+
+  const LIMITES = Object.freeze({
+    QUADRO_MAX: 65536,              // bytes UTF-8 de uma mensagem WebSocket inteira
+    DADOS_MAX: 61440,               // caracteres do campo opaco `dados` dentro de um quadro do relay
+    TEXTO_CLARO_MAX: 32768,         // bytes do texto claro de um quadro cifrado de sessão
+    CONVITE_VALIDADE_MS: 300000,    // 5 min
+    DECISAO_MS: 300000,             // tempo extra, depois do vencimento, para a confirmação no PC
+    CONVITES_PENDENTES_MAX: 4,
+    PAREAR_FALHAS_MAX: 5,           // pedidos que não decifram até o convite ser descartado
+    TOLERANCIA_RELOGIO_MS: 120000,  // ±120 s
+    HANDSHAKE_MS: 30000,
+    SESSAO_VIDA_MS: 12 * 3600 * 1000,
+    SESSAO_QUADROS_MAX: 0x7fffffff, // por direção; depois disso, novo aperto de mão
+    DESAFIO_MS: 30000,
+    APARELHOS_MAX: 50,
+    NOME_MAX: 40,
+    TAXA_QUADROS_S: 30,
+    RAJADA_QUADROS: 60,
+    TAXA_BYTES_S: 262144,
+    RAJADA_BYTES: 524288,
+    ANON_QUADROS_MIN: 6,
+    PROFUNDIDADE_JSON_MAX: 16,
+    HISTORICO_MAX: 200,             // linhas de histórico que o celular pode pedir em terminal.watch
+    PAREAR_USADO_MAX: 4,            // respostas "usado" (assinadas) por convite a outros aparelhos
+  });
+
+  const MENSAGENS = Object.freeze({
+    E_FORMATO: 'quadro ou campo em formato inválido',
+    E_TAMANHO: 'quadro maior que o limite',
+    E_VERSAO: 'versão de protocolo não suportada',
+    E_ARGUMENTO: 'uso incorreto da API do protocolo',
+    E_CRIPTO_INDISPONIVEL: 'WebCrypto indisponível neste ambiente',
+    E_CHAVE: 'chave pública ou privada inválida',
+    E_CHAVE_EXPORTAVEL: 'chave privada do aparelho não pode ser exportável',
+    E_ID: 'identificador não corresponde à chave',
+    E_ASSINATURA: 'assinatura inválida',
+    E_DECIFRAR: 'falha ao decifrar ou autenticar',
+    E_CONVITE_INVALIDO: 'convite de pareamento inválido',
+    E_CONVITE_DESCONHECIDO: 'convite de pareamento desconhecido',
+    E_CONVITE_EXPIRADO: 'convite de pareamento expirado',
+    E_CONVITE_USADO: 'convite de pareamento já usado',
+    E_PAREAMENTO_ESTADO: 'pareamento fora de ordem ou encerrado',
+    E_NOME: 'nome do aparelho inválido',
+    E_LIMITE: 'limite de itens pendentes atingido',
+    E_HANDSHAKE_EXPIRADO: 'aperto de mão expirado',
+    E_APARELHO_NAO_AUTORIZADO: 'aparelho não autorizado ou revogado',
+    E_SESSAO: 'sessão inválida ou fora de ordem',
+    E_SESSAO_DERRUBADA: 'sessão derrubada',
+    E_SESSAO_EXPIRADA: 'sessão expirada',
+    E_CONTADOR: 'contador de quadro repetido ou fora de ordem',
+    E_LIMITE_SESSAO: 'limite de quadros da sessão atingido',
+    E_SEQ: 'sequência de comando repetida ou fora de ordem',
+    E_TEMPO: 'carimbo de tempo fora da janela',
+    E_METODO: 'método não permitido',
+    E_PARAMS: 'parâmetros inválidos',
+    E_DESAFIO: 'desafio inválido, vencido ou já usado',
+    E_LISTA_VERSAO: 'versão da lista de aparelhos não é maior que a atual',
+    E_LISTA_INVALIDA: 'lista de aparelhos inválida',
+    E_TAXA: 'limite de taxa excedido',
+    E_NO_NAO_AUTORIZADO: 'nó não autorizado neste relay',
+    E_TERMINAL_INEXISTENTE: 'terminal inexistente no nó',
+    E_PARAR_SEM_CONFIRMACAO: 'parar tudo não confirmado pelo consumidor do nó',
+    E_PARAR_INDISPONIVEL: 'parar tudo indisponível neste nó',
+    E_INTERNO: 'erro interno do protocolo',
+  });
+  const CODIGOS = Object.freeze(Object.keys(MENSAGENS));
+
+  class TsProtoErro extends Error {
+    constructor(codigo, extra) {
+      const c = Object.prototype.hasOwnProperty.call(MENSAGENS, codigo) ? codigo : 'E_INTERNO';
+      super(MENSAGENS[c]);
+      this.name = 'TsProtoErro';
+      this.codigo = c;
+      // Único dado extra permitido: o número de sequência do comando (não é sigiloso), para o
+      // hub conseguir responder o erro ao comando certo.
+      if (extra && Number.isSafeInteger(extra.seq)) this.seq = extra.seq;
+    }
+    toJSON() { return this.seq === undefined ? { codigo: this.codigo } : { codigo: this.codigo, seq: this.seq }; }
+  }
+  function falha(codigo, extra) { throw new TsProtoErro(codigo, extra); }
+
+  // ===========================================================================================
+  // Bytes, texto, base64url, JSON canônico
+  // ===========================================================================================
+
+  const codificador = new TextEncoder();
+  const decodificador = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+
+  function comoBytes(x) {
+    if (x instanceof Uint8Array) return x;
+    if (x instanceof ArrayBuffer) return new Uint8Array(x);
+    if (ArrayBuffer.isView(x)) return new Uint8Array(x.buffer, x.byteOffset, x.byteLength);
+    falha('E_ARGUMENTO');
+  }
+  function concat() {
+    let total = 0;
+    const partes = [];
+    for (let i = 0; i < arguments.length; i++) { const b = comoBytes(arguments[i]); partes.push(b); total += b.length; }
+    const out = new Uint8Array(total);
+    let o = 0;
+    for (const b of partes) { out.set(b, o); o += b.length; }
+    return out;
+  }
+  function utf8(s) {
+    if (typeof s !== 'string' || !textoBemFormado(s)) falha('E_FORMATO');
+    return codificador.encode(s);
+  }
+  function deUtf8(bytes) {
+    try { return decodificador.decode(comoBytes(bytes)); } catch (_) { falha('E_FORMATO'); }
+  }
+  function textoBemFormado(s) {
+    if (typeof s.isWellFormed === 'function') return s.isWellFormed();
+    return !/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(^|[^\uD800-\uDBFF])[\uDC00-\uDFFF]/.test(s);
+  }
+  function hex(bytes) {
+    const b = comoBytes(bytes);
+    let s = '';
+    for (let i = 0; i < b.length; i++) s += (b[i] < 16 ? '0' : '') + b[i].toString(16);
+    return s;
+  }
+  function deHex(s) {
+    if (typeof s !== 'string' || s.length % 2 || /[^0-9a-fA-F]/.test(s)) falha('E_FORMATO');
+    const out = new Uint8Array(s.length / 2);
+    for (let i = 0; i < out.length; i++) out[i] = parseInt(s.substr(i * 2, 2), 16);
+    return out;
+  }
+  function iguaisBytes(a, b) {
+    if (a.length !== b.length) return false;
+    let d = 0;
+    for (let i = 0; i < a.length; i++) d |= a[i] ^ b[i];
+    return d === 0;
+  }
+
+  const ALFABETO = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+  const REVERSO = (function () {
+    const r = new Int16Array(128).fill(-1);
+    for (let i = 0; i < 64; i++) r[ALFABETO.charCodeAt(i)] = i;
+    return r;
+  })();
+
+  /** base64url sem preenchimento (RFC 4648 §5). */
+  function b64u(bytes) {
+    const b = comoBytes(bytes);
+    let s = '';
+    let i = 0;
+    for (; i + 2 < b.length; i += 3) {
+      const n = (b[i] << 16) | (b[i + 1] << 8) | b[i + 2];
+      s += ALFABETO[(n >> 18) & 63] + ALFABETO[(n >> 12) & 63] + ALFABETO[(n >> 6) & 63] + ALFABETO[n & 63];
+    }
+    const resto = b.length - i;
+    if (resto === 1) {
+      const n = b[i] << 16;
+      s += ALFABETO[(n >> 18) & 63] + ALFABETO[(n >> 12) & 63];
+    } else if (resto === 2) {
+      const n = (b[i] << 16) | (b[i + 1] << 8);
+      s += ALFABETO[(n >> 18) & 63] + ALFABETO[(n >> 12) & 63] + ALFABETO[(n >> 6) & 63];
+    }
+    return s;
+  }
+
+  /** Decodificação ESTRITA: sem '=', sem espaços, sem bits de sobra diferentes de zero. */
+  function deB64u(s, tamanhoEsperado) {
+    if (typeof s !== 'string' || s.length % 4 === 1) falha('E_FORMATO');
+    const out = new Uint8Array(Math.floor((s.length * 3) / 4));
+    let o = 0, acc = 0, bits = 0;
+    for (let i = 0; i < s.length; i++) {
+      const c = s.charCodeAt(i);
+      const v = c < 128 ? REVERSO[c] : -1;
+      if (v < 0) falha('E_FORMATO');
+      acc = (acc << 6) | v;
+      bits += 6;
+      if (bits >= 8) { bits -= 8; out[o++] = (acc >> bits) & 255; }
+      acc &= (1 << bits) - 1;
+    }
+    if (acc !== 0 || o !== out.length) falha('E_FORMATO');
+    if (tamanhoEsperado !== undefined && out.length !== tamanhoEsperado) falha('E_FORMATO');
+    return out;
+  }
+
+  function ehObjetoSimples(o) {
+    if (o === null || typeof o !== 'object' || Array.isArray(o)) return false;
+    const p = Object.getPrototypeOf(o);
+    return p === Object.prototype || p === null;
+  }
+
+  /**
+   * JSON canônico: chaves ordenadas por unidade de código UTF-16 (ordem padrão de sort),
+   * sem espaços; números só inteiros seguros; nada de undefined, NaN, funções ou texto com
+   * substituto solitário. É o que se assina e o que entra nos hashes de transcript.
+   */
+  function canonico(v, prof) {
+    prof = prof || 0;
+    if (prof > LIMITES.PROFUNDIDADE_JSON_MAX) falha('E_FORMATO');
+    if (v === null) return 'null';
+    switch (typeof v) {
+      case 'boolean': return v ? 'true' : 'false';
+      case 'number':
+        if (!Number.isSafeInteger(v)) falha('E_FORMATO');
+        return String(v === 0 ? 0 : v);
+      case 'string':
+        if (!textoBemFormado(v)) falha('E_FORMATO');
+        return JSON.stringify(v);
+      case 'object': {
+        if (Array.isArray(v)) {
+          let s = '[';
+          for (let i = 0; i < v.length; i++) s += (i ? ',' : '') + canonico(v[i], prof + 1);
+          return s + ']';
+        }
+        if (!ehObjetoSimples(v)) falha('E_FORMATO');
+        const ks = Object.keys(v).sort();
+        let s = '{';
+        for (let i = 0; i < ks.length; i++) {
+          if (!textoBemFormado(ks[i])) falha('E_FORMATO');
+          s += (i ? ',' : '') + JSON.stringify(ks[i]) + ':' + canonico(v[ks[i]], prof + 1);
+        }
+        return s + '}';
+      }
+      default: falha('E_FORMATO');
+    }
+  }
+
+  function profundidade(v, prof) {
+    if (prof > LIMITES.PROFUNDIDADE_JSON_MAX) return false;
+    if (v === null || typeof v !== 'object') return true;
+    const vals = Array.isArray(v) ? v : Object.values(v);
+    for (const x of vals) if (!profundidade(x, prof + 1)) return false;
+    return true;
+  }
+
+  function lerJsonTexto(texto) {
+    let o;
+    try { o = JSON.parse(texto); } catch (_) { falha('E_FORMATO'); }
+    if (!ehObjetoSimples(o) || !profundidade(o, 0)) falha('E_FORMATO');
+    return o;
+  }
+
+  function tamanhoUtf8(s) {
+    let n = 0;
+    for (let i = 0; i < s.length; i++) {
+      const c = s.charCodeAt(i);
+      if (c < 0x80) n += 1;
+      else if (c < 0x800) n += 2;
+      else if (c >= 0xd800 && c <= 0xdbff && i + 1 < s.length && (s.charCodeAt(i + 1) & 0xfc00) === 0xdc00) { n += 4; i++; }
+      else n += 3;
+    }
+    return n;
+  }
+
+  /** Recusa (E_TAMANHO) texto ou bytes acima de QUADRO_MAX. Rápido para textos enormes. */
+  function verificarTamanhoQuadro(entrada) {
+    let n;
+    if (typeof entrada === 'string') {
+      if (entrada.length > LIMITES.QUADRO_MAX) falha('E_TAMANHO');
+      n = tamanhoUtf8(entrada);
+    } else {
+      n = comoBytes(entrada).length;
+    }
+    if (n > LIMITES.QUADRO_MAX) falha('E_TAMANHO');
+    return n;
+  }
+
+  // ===========================================================================================
+  // Validação de campos
+  // ===========================================================================================
+
+  const RX_ID = /^[A-Za-z0-9_-]{22}$/;
+  const RX_TERMINAL = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/;
+  const RX_CODIGO = /^E_[A-Z_]{1,40}$/;
+  const RX_EVENTO = /^[a-z][a-zA-Z0-9._]{0,63}$/;
+
+  function ehId(s) { return typeof s === 'string' && RX_ID.test(s); }
+  function inteiro(n, min, max) { return Number.isSafeInteger(n) && n >= min && n <= max; }
+
+  function exigirCampos(o, obrigatorios, opcionais) {
+    if (!ehObjetoSimples(o)) falha('E_FORMATO');
+    const ok = opcionais ? obrigatorios.concat(opcionais) : obrigatorios;
+    const ks = Object.keys(o);
+    for (const k of ks) if (ok.indexOf(k) < 0) falha('E_FORMATO');
+    for (const k of obrigatorios) if (!Object.prototype.hasOwnProperty.call(o, k)) falha('E_FORMATO');
+  }
+
+  function relogio(agora) {
+    if (agora === undefined) return Date.now();
+    if (!inteiro(agora, 0, Number.MAX_SAFE_INTEGER)) falha('E_ARGUMENTO');
+    return agora;
+  }
+
+  function exigirTs(ts, agora) {
+    if (!inteiro(ts, 0, Number.MAX_SAFE_INTEGER)) falha('E_FORMATO');
+    if (Math.abs(agora - ts) > LIMITES.TOLERANCIA_RELOGIO_MS) falha('E_TEMPO');
+  }
+
+  // Controles, formatação invisível e sobreposição bidi: não entram no nome exibido no PC.
+  const RX_NOME_PROIBIDO = /[\u0000-\u001f\u007f-\u009f\u00ad\u061c\u180e\u200b-\u200f\u2028-\u202e\u2060-\u206f\ufeff\ufff9-\ufffb]/;
+  function normalizarNome(nome) {
+    if (typeof nome !== 'string') falha('E_NOME');
+    const n = nome.normalize('NFC').replace(/\s+/g, ' ').trim();
+    validarNome(n);
+    return n;
+  }
+  function validarNome(nome) {
+    if (typeof nome !== 'string' || !textoBemFormado(nome)) falha('E_NOME');
+    if (nome !== nome.normalize('NFC') || nome !== nome.trim() || /\s{2,}/.test(nome)) falha('E_NOME');
+    const tam = Array.from(nome).length;
+    if (tam < 1 || tam > LIMITES.NOME_MAX || RX_NOME_PROIBIDO.test(nome)) falha('E_NOME');
+  }
+
+  // ===========================================================================================
+  // Primitivas WebCrypto
+  // ===========================================================================================
+
+  function subtle() {
+    const c = g.crypto;
+    if (!c || !c.subtle || typeof c.getRandomValues !== 'function') falha('E_CRIPTO_INDISPONIVEL');
+    return c.subtle;
+  }
+  function aleatorio(n) {
+    subtle();
+    const b = new Uint8Array(n);
+    g.crypto.getRandomValues(b);
+    return b;
+  }
+  async function sha256(bytes) {
+    return new Uint8Array(await subtle().digest('SHA-256', comoBytes(bytes)));
+  }
+
+  /** HKDF-SHA256 (RFC 5869) devolvendo bytes. */
+  async function hkdf(ikm, salt, info, tamanho) {
+    if (!inteiro(tamanho, 1, 255 * 32)) falha('E_ARGUMENTO');
+    const base = await subtle().importKey('raw', comoBytes(ikm), 'HKDF', false, ['deriveBits']);
+    const bits = await subtle().deriveBits(
+      { name: 'HKDF', hash: 'SHA-256', salt: comoBytes(salt), info: comoBytes(info) }, base, tamanho * 8);
+    return new Uint8Array(bits);
+  }
+
+  /** Importa 32 bytes como chave AES-256-GCM NÃO exportável e zera a cópia em memória. */
+  async function chaveAes(bytes, usos) {
+    try {
+      return await subtle().importKey('raw', bytes, { name: 'AES-GCM', length: 256 }, false, usos);
+    } finally {
+      bytes.fill(0);
+    }
+  }
+
+  async function aesSelar(chave, iv, claro, aad) {
+    const ct = await subtle().encrypt({ name: 'AES-GCM', iv, additionalData: aad, tagLength: 128 }, chave, claro);
+    return new Uint8Array(ct);
+  }
+  async function aesAbrir(chave, iv, ct, aad) {
+    if (ct.length < 16) falha('E_DECIFRAR');
+    try {
+      return new Uint8Array(await subtle().decrypt({ name: 'AES-GCM', iv, additionalData: aad, tagLength: 128 }, chave, ct));
+    } catch (_) {
+      falha('E_DECIFRAR');
+    }
+  }
+
+  const ALG_ECDSA = Object.freeze({ name: 'ECDSA', namedCurve: 'P-256' });
+  const ALG_ASSINATURA = Object.freeze({ name: 'ECDSA', hash: 'SHA-256' });
+  const ALG_ECDH = Object.freeze({ name: 'ECDH', namedCurve: 'P-256' });
+
+  // SPKI DER de uma chave P-256 em ponto não comprimido: prefixo fixo de 27 bytes + X + Y.
+  const PREFIXO_SPKI = deHex('3059301306072a8648ce3d020106082a8648ce3d030107034200' + '04');
+
+  function rotulo(nome) { return utf8(PREFIXO + nome + '\u0000'); }
+
+  function validarSpki(spki) {
+    if (spki.length !== 91 || !iguaisBytes(spki.subarray(0, 27), PREFIXO_SPKI)) falha('E_CHAVE');
+  }
+  async function importarSpki(spki) {
+    validarSpki(spki);
+    try {
+      return await subtle().importKey('spki', spki, ALG_ECDSA, true, ['verify']);
+    } catch (_) {
+      falha('E_CHAVE');
+    }
+  }
+
+  // Ponto comprimido SEC1 (0x02/0x03 || X, 33 bytes) da P-256: y² = x³ − 3x + b (mod p).
+  // Usado só pelo convite v2 (§3.1). BigInt é criado sob demanda (nada de literal `123n`).
+  let CURVA_P256 = null;
+  function curvaP256() {
+    if (!CURVA_P256) {
+      if (typeof BigInt !== 'function') falha('E_CRIPTO_INDISPONIVEL');
+      const p = BigInt('0xffffffff00000001000000000000000000000000ffffffffffffffffffffffff');
+      CURVA_P256 = Object.freeze({
+        p,
+        b: BigInt('0x5ac635d8aa3a93e7b3ebbd55769886bc651d06b0cc53b0f63bce3c3e27d2604b'),
+        raiz: (p + BigInt(1)) / BigInt(4),   // p ≡ 3 (mod 4): √a = a^((p+1)/4)
+        zero: BigInt(0), um: BigInt(1), tres: BigInt(3),
+      });
+    }
+    return CURVA_P256;
+  }
+  function bigDeBytes(b) { return BigInt('0x' + (hex(b) || '0')); }
+  function bytesDeBig(n, tamanho) {
+    const h = n.toString(16);
+    if (h.length > tamanho * 2) falha('E_CHAVE');
+    return deHex(h.padStart(tamanho * 2, '0'));
+  }
+  function potMod(base, e, m) {
+    const c = curvaP256();
+    let r = c.um;
+    base %= m;
+    while (e > c.zero) {
+      if (e & c.um) r = (r * base) % m;
+      base = (base * base) % m;
+      e >>= c.um;
+    }
+    return r;
+  }
+
+  /** SPKI P-256 (91 bytes, ponto não comprimido) → ponto comprimido SEC1 (33 bytes). */
+  function comprimirSpki(spki) {
+    const b = comoBytes(spki);
+    validarSpki(b);
+    return concat(new Uint8Array([0x02 | (b[90] & 1)]), b.subarray(27, 59));
+  }
+
+  /**
+   * Ponto comprimido SEC1 (33 bytes) → SPKI P-256 (91 bytes). Recusa (E_CHAVE) prefixo que não
+   * seja 0x02/0x03, x ≥ p e x sem raiz (fora da curva). A importação WebCrypto continua sendo a
+   * validação final do ponto (importarSpki).
+   */
+  function descomprimirSpki(ponto) {
+    const b = comoBytes(ponto);
+    if (b.length !== 33 || (b[0] !== 0x02 && b[0] !== 0x03)) falha('E_CHAVE');
+    const c = curvaP256();
+    const x = bigDeBytes(b.subarray(1));
+    if (x >= c.p) falha('E_CHAVE');
+    const rhs = (((x * x) % c.p * x - c.tres * x + c.b) % c.p + c.p) % c.p;
+    let y = potMod(rhs, c.raiz, c.p);
+    if ((y * y) % c.p !== rhs) falha('E_CHAVE');
+    if ((y & c.um) !== BigInt(b[0] & 1)) y = (c.p - y) % c.p;
+    if ((y & c.um) !== BigInt(b[0] & 1)) falha('E_CHAVE');   // y = 0 não tem as duas paridades
+    return concat(PREFIXO_SPKI, b.subarray(1), bytesDeBig(y, 32));
+  }
+
+  /** Assina PREFIXO+nome+NUL || dados; devolve a assinatura P1363 (r||s, 64 bytes) em base64url. */
+  async function assinar(chavePrivada, nome, dados) {
+    const sig = await subtle().sign(ALG_ASSINATURA, chavePrivada, concat(rotulo(nome), dados));
+    return b64u(new Uint8Array(sig));
+  }
+  async function verificarAssinatura(chavePublica, nome, dados, assinaturaB64) {
+    let sig;
+    try { sig = deB64u(assinaturaB64, 64); } catch (_) { return false; }
+    try {
+      return await subtle().verify(ALG_ASSINATURA, chavePublica, sig, concat(rotulo(nome), dados));
+    } catch (_) {
+      return false;
+    }
+  }
+
+  // ===========================================================================================
+  // Identidades
+  // ===========================================================================================
+
+  function idDeHash(h) { return b64u(h).slice(0, 22); }
+  function impressaoDeHash(h) {
+    const x = hex(h.subarray(0, 8)).toUpperCase();
+    return x.slice(0, 4) + '-' + x.slice(4, 8) + '-' + x.slice(8, 12) + '-' + x.slice(12, 16);
+  }
+  async function idDeSpki(spki) { const b = comoBytes(spki); validarSpki(b); return idDeHash(await sha256(b)); }
+  async function impressaoDeSpki(spki) { const b = comoBytes(spki); validarSpki(b); return impressaoDeHash(await sha256(b)); }
+
+  const IDENTIDADES = new WeakSet();
+
+  async function montarIdentidade(tipo, chavePrivada, chavePublica) {
+    let spki;
+    try { spki = new Uint8Array(await subtle().exportKey('spki', chavePublica)); } catch (_) { falha('E_CHAVE'); }
+    validarSpki(spki);
+    const h = await sha256(spki);
+    const ident = Object.freeze({
+      tipo,
+      chavePrivada,
+      chavePublica,
+      spki,
+      spkiB64: b64u(spki),
+      id: idDeHash(h),
+      impressao: impressaoDeHash(h),
+    });
+    IDENTIDADES.add(ident);
+    return ident;
+  }
+
+  function exigirIdentidade(ident, tipo) {
+    if (!ident || !IDENTIDADES.has(ident) || ident.tipo !== tipo) falha('E_ARGUMENTO');
+  }
+
+  /**
+   * Gera identidade de longo prazo.
+   *   tipo 'aparelho': chave privada SEMPRE não exportável (extractable:false). A PWA guarda o
+   *                    CryptoKey no IndexedDB (clone estruturado) e restaura com identidadeDeChaves.
+   *   tipo 'no':       chave privada exportável, porque o hub precisa gravá-la cifrada (DPAPI no
+   *                    Windows, arquivo 0600 do usuário tshub na VPS). Ver exportarIdentidadeNo.
+   */
+  async function gerarIdentidade(opcoes) {
+    const tipo = opcoes && opcoes.tipo;
+    if (tipo !== 'no' && tipo !== 'aparelho') falha('E_ARGUMENTO');
+    const par = await subtle().generateKey(ALG_ECDSA, tipo === 'no', ['sign', 'verify']);
+    if (tipo === 'aparelho' && par.privateKey.extractable !== false) falha('E_CHAVE_EXPORTAVEL');
+    return montarIdentidade(tipo, par.privateKey, par.publicKey);
+  }
+
+  /** Reconstrói a identidade a partir dos CryptoKey guardados (uso típico: aparelho + IndexedDB). */
+  async function identidadeDeChaves(opcoes) {
+    const o = opcoes || {};
+    const tipo = o.tipo;
+    if (tipo !== 'no' && tipo !== 'aparelho') falha('E_ARGUMENTO');
+    const priv = o.chavePrivada, pub = o.chavePublica;
+    const ehChave = k => k && typeof k === 'object' && k.algorithm && k.algorithm.name === 'ECDSA' && k.algorithm.namedCurve === 'P-256';
+    if (!ehChave(priv) || !ehChave(pub) || priv.type !== 'private' || pub.type !== 'public') falha('E_CHAVE');
+    if (tipo === 'aparelho' && priv.extractable !== false) falha('E_CHAVE_EXPORTAVEL');
+    // Confere que as duas metades são do mesmo par.
+    const teste = aleatorio(32);
+    let ok = false;
+    try {
+      const sig = await subtle().sign(ALG_ASSINATURA, priv, teste);
+      ok = await subtle().verify(ALG_ASSINATURA, pub, sig, teste);
+    } catch (_) { ok = false; }
+    if (!ok) falha('E_CHAVE');
+    return montarIdentidade(tipo, priv, pub);
+  }
+
+  /** Só para o nó: { pkcs8, spki } em base64url. O hub deve cifrar isso antes de gravar. */
+  async function exportarIdentidadeNo(ident) {
+    exigirIdentidade(ident, 'no');
+    const pkcs8 = new Uint8Array(await subtle().exportKey('pkcs8', ident.chavePrivada));
+    const r = { pkcs8: b64u(pkcs8), spki: ident.spkiB64 };
+    pkcs8.fill(0);
+    return r;
+  }
+  async function importarIdentidadeNo(dados) {
+    exigirCampos(dados, ['pkcs8', 'spki']);
+    const pkcs8 = deB64u(dados.pkcs8);
+    const spki = deB64u(dados.spki);
+    let priv, pub;
+    try {
+      priv = await subtle().importKey('pkcs8', pkcs8, ALG_ECDSA, true, ['sign']);
+    } catch (_) { falha('E_CHAVE'); } finally { pkcs8.fill(0); }
+    pub = await importarSpki(spki);
+    return identidadeDeChaves({ tipo: 'no', chavePrivada: priv, chavePublica: pub });
+  }
+
+  // ===========================================================================================
+  // Endereço do relay
+  // ===========================================================================================
+
+  function ehHostLocal(hostname) {
+    const h = String(hostname).toLowerCase();
+    return h === 'localhost' || h === '127.0.0.1' || h === '[::1]' || h.endsWith('.localhost');
+  }
+
+  /**
+   * `relay` é uma ORIGEM WebSocket canônica: "wss://host[:porta]" (sem caminho, consulta ou
+   * fragmento). "ws://" só para host local e só com permitirLocal (testes e etapa 6).
+   */
+  function validarRelay(relay, permitirLocal) {
+    if (typeof relay !== 'string' || relay.length > 255) falha('E_ARGUMENTO');
+    let u;
+    try { u = new URL(relay); } catch (_) { falha('E_ARGUMENTO'); }
+    const local = ehHostLocal(u.hostname);
+    if (!(u.protocol === 'wss:' || (u.protocol === 'ws:' && permitirLocal && local))) falha('E_ARGUMENTO');
+    if (u.username || u.password || u.search || u.hash || (u.pathname !== '/' && u.pathname !== '')) falha('E_ARGUMENTO');
+    if (relay !== u.protocol + '//' + u.host) falha('E_ARGUMENTO');
+    return {
+      relay,
+      host: u.host,
+      origemHttp: (u.protocol === 'wss:' ? 'https://' : 'http://') + u.host,
+    };
+  }
+
+  // ===========================================================================================
+  // Pareamento
+  // ===========================================================================================
+
+  async function derivarChavesPareamento(segredo, noSpki, papel) {
+    const salt = await sha256(noSpki);
+    const pid = idDeHash(await hkdf(segredo, salt, utf8(PREFIXO + 'parear/id'), 16));
+    const a2n = await hkdf(segredo, salt, utf8(PREFIXO + 'parear/a2n'), 32);
+    const n2a = await hkdf(segredo, salt, utf8(PREFIXO + 'parear/n2a'), 32);
+    const ehNo = papel === 'no';
+    return {
+      pid,
+      enviar: await chaveAes(ehNo ? n2a : a2n, ['encrypt']),
+      receber: await chaveAes(ehNo ? a2n : n2a, ['decrypt']),
+    };
+  }
+  function aadPareamento(tipo, pid) { return concat(rotulo('parear/' + tipo), utf8(pid)); }
+
+  async function selarPareamento(chave, tipo, pid, obj) {
+    const iv = aleatorio(12);
+    const ct = await aesSelar(chave, iv, utf8(JSON.stringify(obj)), aadPareamento(tipo, pid));
+    return { t: 'parear.' + tipo, v: VERSAO, pid, iv: b64u(iv), ct: b64u(ct) };
+  }
+  function lerQuadroPareamento(quadro, tipo) {
+    exigirCampos(quadro, ['t', 'v', 'pid', 'iv', 'ct']);
+    if (quadro.t !== 'parear.' + tipo) falha('E_FORMATO');
+    if (quadro.v !== VERSAO) falha('E_VERSAO');
+    if (!ehId(quadro.pid) || typeof quadro.ct !== 'string' || quadro.ct.length > LIMITES.DADOS_MAX) falha('E_FORMATO');
+    return { iv: deB64u(quadro.iv, 12), ct: deB64u(quadro.ct) };
+  }
+
+  const ESTADOS_PAREAMENTO = Object.freeze(['pendente', 'aceito', 'recusado', 'usado']);
+
+  // Convite v2: ponto comprimido (33) || segredo (32) || exp em ms, sem sinal, big-endian (6).
+  const CONVITE_V2_TAMANHO = 71;
+  const CONVITE_V2_EXP_MAX = 0xffffffffffff;   // 2^48 − 1 ms (ano 10889)
+  function u48(n) {
+    const out = new Uint8Array(6);
+    for (let i = 5; i >= 0; i--) { out[i] = n % 256; n = Math.floor(n / 256); }
+    return out;
+  }
+  function deU48(b) {
+    let n = 0;
+    for (let i = 0; i < 6; i++) n = n * 256 + b[i];
+    return n;
+  }
+
+  /**
+   * Origem HTTP da PWA que abre o convite: "https://host[:porta]" (sem caminho), ou
+   * "http://" só para host local com permitirLocal. Pode ser diferente do relay (§3.1).
+   */
+  function validarOrigemPwa(origem, permitirLocal) {
+    if (typeof origem !== 'string' || origem.length > 255) falha('E_ARGUMENTO');
+    let u;
+    try { u = new URL(origem); } catch (_) { falha('E_ARGUMENTO'); }
+    const local = ehHostLocal(u.hostname);
+    if (!(u.protocol === 'https:' || (u.protocol === 'http:' && permitirLocal && local))) falha('E_ARGUMENTO');
+    if (u.username || u.password || u.search || u.hash || (u.pathname !== '/' && u.pathname !== '')) falha('E_ARGUMENTO');
+    if (origem !== u.protocol + '//' + u.host) falha('E_ARGUMENTO');
+    return origem;
+  }
+
+  /**
+   * Lado do NÓ. Guarda os convites abertos em memória (nunca em disco) e aplica uso único,
+   * validade e o limite de tentativas. A decisão humana é da etapa do hub: ela chama
+   * responder(pid, 'aceito') só depois da confirmação na tela do PC.
+   */
+  class RegistroPareamentos {
+    constructor(opcoes) {
+      const ident = opcoes && opcoes.identidade;
+      exigirIdentidade(ident, 'no');
+      this._ident = ident;
+      this._mapa = new Map();
+    }
+
+    /** Convites ainda não usados e dentro da validade. */
+    pendentes(agora) {
+      const t = relogio(agora);
+      let n = 0;
+      for (const e of this._mapa.values()) if (!e.usado && t <= e.exp) n++;
+      return n;
+    }
+
+    _descartar(e) { e.chaves = null; e.encerrado = true; this._mapa.delete(e.pid); }
+    _limpar(agora) { for (const e of Array.from(this._mapa.values())) if (agora > e.fimMs) this._descartar(e); }
+
+    /** Devolve { url, pid, exp }. A URL contém o segredo: mostrar só no QR, nunca em log. */
+    async criarConvite(opcoes) {
+      const o = opcoes || {};
+      const agora = relogio(o.agora);
+      const relay = validarRelay(o.relay, !!o.permitirLocal);
+      const pwa = o.pwa === undefined ? relay.origemHttp : validarOrigemPwa(o.pwa, !!o.permitirLocal);
+      const validade = o.validadeMs === undefined ? LIMITES.CONVITE_VALIDADE_MS : o.validadeMs;
+      if (!inteiro(validade, 1000, LIMITES.CONVITE_VALIDADE_MS)) falha('E_ARGUMENTO');
+      this._limpar(agora);
+      if (this.pendentes(agora) >= LIMITES.CONVITES_PENDENTES_MAX) falha('E_LIMITE');
+
+      const exp = agora + validade;
+      if (exp > CONVITE_V2_EXP_MAX) falha('E_ARGUMENTO');
+      const segredo = aleatorio(32);
+      const chaves = await derivarChavesPareamento(segredo, this._ident.spki, 'no');
+      // Convite v2 (§3.1): ponto comprimido do nó || segredo || exp. O relay não vai no QR.
+      const carga = concat(comprimirSpki(this._ident.spki), segredo, u48(exp));
+      segredo.fill(0);
+      const url = pwa + '/parear#v2.' + b64u(carga);
+      carga.fill(0);
+      this._mapa.set(chaves.pid, {
+        pid: chaves.pid, exp, fimMs: exp + LIMITES.DECISAO_MS,
+        usado: false, encerrado: false, falhas: 0, chaves, aparelho: null, ultimoEstado: null, avisosUsado: 0,
+      });
+      return { url, pid: chaves.pid, exp };
+    }
+
+    cancelar(pid) { const e = this._mapa.get(pid); if (e) this._descartar(e); }
+
+    /**
+     * Abre o pedido cifrado do aparelho. Consome o convite no primeiro pedido que decifra.
+     * Devolve { pid, aparelho: { id, spki, nome, impressao } } para a tela de confirmação.
+     */
+    async abrirPedido(quadro, opcoes) {
+      const agora = relogio(opcoes && opcoes.agora);
+      const bruto = lerQuadroPareamento(quadro, 'pedido');
+      this._limpar(agora);
+      const e = this._mapa.get(quadro.pid);
+      if (!e) falha('E_CONVITE_DESCONHECIDO');
+      if (e.usado) falha('E_CONVITE_USADO');
+      if (agora > e.exp) { this._descartar(e); falha('E_CONVITE_EXPIRADO'); }
+
+      let claro;
+      try {
+        claro = await aesAbrir(e.chaves.receber, bruto.iv, bruto.ct, aadPareamento('pedido', e.pid));
+      } catch (err) {
+        if (++e.falhas >= LIMITES.PAREAR_FALHAS_MAX) this._descartar(e);
+        throw err;
+      }
+      // Checar e marcar sem await no meio: dois pedidos simultâneos não consomem o mesmo convite.
+      if (e.usado || !e.chaves) falha('E_CONVITE_USADO');
+      e.usado = true;
+
+      try {
+        e.aparelho = await this._lerPedidoClaro(e, claro, agora);
+        return { pid: e.pid, aparelho: e.aparelho };
+      } catch (err) {
+        // Convite já consumido; pedido defeituoso encerra (quem tentar de novo recebe E_CONVITE_USADO).
+        e.encerrado = true;
+        e.chaves = null;
+        throw err;
+      }
+    }
+
+    /** Confere o texto claro de um pedido (passo 5 de §3.4) e devolve o aparelho. */
+    async _lerPedidoClaro(e, claro, agora) {
+      const p = lerJsonTexto(deUtf8(claro));
+      exigirCampos(p, ['t', 'pid', 'no', 'aparelhoSpki', 'nome', 'ts', 'assinatura']);
+      if (p.t !== 'parear.pedido' || p.pid !== e.pid || p.no !== this._ident.id) falha('E_FORMATO');
+      exigirTs(p.ts, agora);
+      validarNome(p.nome);
+      const spki = deB64u(p.aparelhoSpki);
+      const pub = await importarSpki(spki);
+      const semAss = Object.assign({}, p);
+      delete semAss.assinatura;
+      if (!(await verificarAssinatura(pub, 'parear/pedido', utf8(canonico(semAss)), p.assinatura))) falha('E_ASSINATURA');
+      const h = await sha256(spki);
+      return Object.freeze({ id: idDeHash(h), spki: p.aparelhoSpki, nome: p.nome, impressao: impressaoDeHash(h) });
+    }
+
+    /**
+     * Segundo pedido para um convite JÁ consumido, enquanto a decisão do primeiro ainda está
+     * aberta (§3.4 e §3.6): decifra e confere o pedido como de costume (só quem tem o segredo
+     * do QR chega aqui) e devolve a resposta assinada com estado "usado", endereçada ao
+     * aparelho que mandou ESTE pedido. Não muda a decisão do convite. No máximo
+     * PAREAR_USADO_MAX tentativas por convite. Devolve { quadro, aparelho:{ id, nome, impressao } }.
+     */
+    async responderUsado(quadro, opcoes) {
+      const agora = relogio(opcoes && opcoes.agora);
+      const bruto = lerQuadroPareamento(quadro, 'pedido');
+      const e = this._mapa.get(quadro.pid);
+      if (!e) falha('E_CONVITE_DESCONHECIDO');
+      if (!e.usado || e.encerrado || !e.chaves || !e.aparelho) falha('E_PAREAMENTO_ESTADO');
+      if (agora > e.fimMs) falha('E_CONVITE_EXPIRADO');
+      if (e.avisosUsado >= LIMITES.PAREAR_USADO_MAX) falha('E_LIMITE');
+      e.avisosUsado++;
+      const chaves = e.chaves;
+      const claro = await aesAbrir(chaves.receber, bruto.iv, bruto.ct, aadPareamento('pedido', e.pid));
+      const outro = await this._lerPedidoClaro(e, claro, agora);
+      if (outro.id === e.aparelho.id) falha('E_CONVITE_USADO');   // o mesmo aparelho de novo: nada a avisar
+      if (!e.chaves || e.encerrado) falha('E_PAREAMENTO_ESTADO');  // decidido durante a conferência
+      const p = { t: 'parear.resposta', pid: e.pid, no: this._ident.id, aparelho: outro.id, estado: 'usado', ts: agora };
+      p.assinatura = await assinar(this._ident.chavePrivada, 'parear/resposta', utf8(canonico(p)));
+      return {
+        quadro: await selarPareamento(chaves.enviar, 'resposta', e.pid, p),
+        aparelho: Object.freeze({ id: outro.id, nome: outro.nome, impressao: outro.impressao }),
+      };
+    }
+
+    /** Resposta cifrada e assinada ao aparelho. estado: 'pendente' | 'aceito' | 'recusado'. */
+    async responder(pid, estado, opcoes) {
+      const agora = relogio(opcoes && opcoes.agora);
+      if (ESTADOS_PAREAMENTO.indexOf(estado) < 0 || estado === 'usado') falha('E_ARGUMENTO');
+      const e = this._mapa.get(pid);
+      if (!e || !e.usado || e.encerrado || !e.aparelho || !e.chaves) falha('E_PAREAMENTO_ESTADO');
+      if (agora > e.fimMs) { this._descartar(e); falha('E_CONVITE_EXPIRADO'); }
+      if (estado === 'pendente' && e.ultimoEstado !== null) falha('E_PAREAMENTO_ESTADO');
+      const chave = e.chaves.enviar;
+      e.ultimoEstado = estado;
+      if (estado !== 'pendente') { e.encerrado = true; e.chaves = null; }
+      const p = { t: 'parear.resposta', pid, no: this._ident.id, aparelho: e.aparelho.id, estado, ts: agora };
+      p.assinatura = await assinar(this._ident.chavePrivada, 'parear/resposta', utf8(canonico(p)));
+      return selarPareamento(chave, 'resposta', pid, p);
+    }
+  }
+
+  const SEGREDOS_CONVITE = new WeakMap();
+  const CONTEXTOS_PAREAMENTO = new WeakMap();
+
+  /**
+   * Lado do APARELHO. Lê a URL do QR (§3.1):
+   *   v2 (gerado hoje): https://<origem da PWA>/parear#v2.<base64url(ponto || segredo || exp)>
+   *   v1 (só leitura):  https://<origem da PWA>/parear#v1.<base64url(JSON)>
+   * opcoes: { agora, permitirLocal, origemPwa, relay }. `relay` só vale no v2 (que não leva o
+   * relay): origem wss:// que o aparelho vai usar; sem ela, a origem WebSocket da própria URL.
+   * No v1 o relay vem do convite e quem chama confere com o seu.
+   * O segredo não aparece no objeto devolvido (fica num WeakMap).
+   */
+  async function lerConvite(url, opcoes) {
+    const o = opcoes || {};
+    const agora = relogio(o.agora);
+    const permitirLocal = !!o.permitirLocal;
+    if (typeof url !== 'string' || url.length > 2048) falha('E_CONVITE_INVALIDO');
+    let u;
+    try { u = new URL(url); } catch (_) { falha('E_CONVITE_INVALIDO'); }
+    const local = ehHostLocal(u.hostname);
+    if (!(u.protocol === 'https:' || (u.protocol === 'http:' && permitirLocal && local))) falha('E_CONVITE_INVALIDO');
+    if (u.username || u.password || u.search || u.pathname !== '/parear') falha('E_CONVITE_INVALIDO');
+    const frag = u.hash;
+    if (!/^#v\d+\./.test(frag)) falha('E_CONVITE_INVALIDO');
+    const versao = frag.slice(0, 4);
+    if (versao !== '#v1.' && versao !== '#v2.') falha('E_VERSAO');
+    const origemUrl = u.protocol + '//' + u.host;
+
+    let relay, nodeId, segredo, spki, exp;
+    if (versao === '#v1.') {
+      let c;
+      try {
+        c = lerJsonTexto(deUtf8(deB64u(frag.slice(4))));
+        exigirCampos(c, ['relay', 'nodeId', 'nodePubSpki', 'segredo', 'exp']);
+      } catch (_) { falha('E_CONVITE_INVALIDO'); }
+      try { relay = validarRelay(c.relay, permitirLocal); } catch (_) { falha('E_CONVITE_INVALIDO'); }
+      if (!ehId(c.nodeId) || !inteiro(c.exp, 0, Number.MAX_SAFE_INTEGER)) falha('E_CONVITE_INVALIDO');
+      try { segredo = deB64u(c.segredo, 32); spki = deB64u(c.nodePubSpki); validarSpki(spki); } catch (_) { falha('E_CONVITE_INVALIDO'); }
+      nodeId = c.nodeId;
+      exp = c.exp;
+    } else {
+      // O relay vem de fora (configuração do aparelho), nunca do QR.
+      relay = o.relay !== undefined ? validarRelay(o.relay, permitirLocal) : null;
+      let b;
+      try { b = deB64u(frag.slice(4), CONVITE_V2_TAMANHO); } catch (_) { falha('E_CONVITE_INVALIDO'); }
+      try { spki = descomprimirSpki(b.subarray(0, 33)); } catch (_) { b.fill(0); falha('E_CONVITE_INVALIDO'); }
+      segredo = b.slice(33, 65);
+      exp = deU48(b.subarray(65, 71));
+      b.fill(0);
+      if (!relay) {
+        try { relay = validarRelay((u.protocol === 'https:' ? 'wss://' : 'ws://') + u.host, permitirLocal); } catch (_) { falha('E_CONVITE_INVALIDO'); }
+      }
+    }
+    let h;
+    try {
+      // A URL é aberta na origem da PWA. Sem `origemPwa`, a PWA é servida pelo próprio relay.
+      if (o.origemPwa !== undefined) {
+        if (o.origemPwa !== origemUrl) falha('E_CONVITE_INVALIDO');
+      } else if (relay.origemHttp !== origemUrl) falha('E_CONVITE_INVALIDO');
+      // Validação final do ponto: a chave do nó tem de importar no WebCrypto.
+      try { await importarSpki(spki); } catch (_) { falha('E_CONVITE_INVALIDO'); }
+      h = await sha256(spki);
+      if (nodeId === undefined) nodeId = idDeHash(h);       // v2: o ID sai da chave
+      else if (idDeHash(h) !== nodeId) falha('E_ID');      // v1: o ID do QR tem de ser o da chave
+      // O relógio do nó é quem manda; aqui só se recusa o que já está claramente vencido.
+      if (agora > exp + LIMITES.TOLERANCIA_RELOGIO_MS) falha('E_CONVITE_EXPIRADO');
+      if (exp - agora > LIMITES.CONVITE_VALIDADE_MS + LIMITES.TOLERANCIA_RELOGIO_MS) falha('E_CONVITE_INVALIDO');
+    } catch (e) {
+      segredo.fill(0);
+      throw e;
+    }
+
+    const convite = Object.freeze({
+      relay: relay.relay, nodeId, nodePubSpki: b64u(spki), exp, impressaoNo: impressaoDeHash(h),
+    });
+    SEGREDOS_CONVITE.set(convite, segredo);
+    return convite;
+  }
+
+  /** Monta o pedido cifrado. O convite só serve uma vez também deste lado. */
+  async function criarPedidoPareamento(opcoes) {
+    const o = opcoes || {};
+    const agora = relogio(o.agora);
+    exigirIdentidade(o.identidade, 'aparelho');
+    const segredo = o.convite ? SEGREDOS_CONVITE.get(o.convite) : undefined;
+    if (!segredo) falha('E_ARGUMENTO');
+    if (agora > o.convite.exp + LIMITES.TOLERANCIA_RELOGIO_MS) falha('E_CONVITE_EXPIRADO');
+    const nome = normalizarNome(o.nome);
+    const noSpki = deB64u(o.convite.nodePubSpki);
+    SEGREDOS_CONVITE.delete(o.convite);
+    const chaves = await derivarChavesPareamento(segredo, noSpki, 'aparelho');
+    segredo.fill(0);
+
+    const p = { t: 'parear.pedido', pid: chaves.pid, no: o.convite.nodeId, aparelhoSpki: o.identidade.spkiB64, nome, ts: agora };
+    p.assinatura = await assinar(o.identidade.chavePrivada, 'parear/pedido', utf8(canonico(p)));
+    const quadro = await selarPareamento(chaves.enviar, 'pedido', chaves.pid, p);
+
+    const contexto = Object.freeze({
+      pid: chaves.pid, nodeId: o.convite.nodeId, aparelhoId: o.identidade.id,
+      impressaoAparelho: o.identidade.impressao, impressaoNo: o.convite.impressaoNo,
+    });
+    CONTEXTOS_PAREAMENTO.set(contexto, {
+      receber: chaves.receber, noPub: await importarSpki(noSpki), ultimo: null, fimMs: o.convite.exp + LIMITES.DECISAO_MS,
+    });
+    return { quadro, contexto };
+  }
+
+  /** Abre a resposta do nó. Ordem aceita: [pendente] → aceito | recusado, ou "usado" sozinho. */
+  async function abrirRespostaPareamento(contexto, quadro, opcoes) {
+    const agora = relogio(opcoes && opcoes.agora);
+    const c = contexto ? CONTEXTOS_PAREAMENTO.get(contexto) : undefined;
+    if (!c) falha('E_PAREAMENTO_ESTADO');
+    if (agora > c.fimMs + LIMITES.TOLERANCIA_RELOGIO_MS) { CONTEXTOS_PAREAMENTO.delete(contexto); falha('E_CONVITE_EXPIRADO'); }
+    const bruto = lerQuadroPareamento(quadro, 'resposta');
+    if (quadro.pid !== contexto.pid) falha('E_FORMATO');
+    const claro = await aesAbrir(c.receber, bruto.iv, bruto.ct, aadPareamento('resposta', contexto.pid));
+    const p = lerJsonTexto(deUtf8(claro));
+    exigirCampos(p, ['t', 'pid', 'no', 'aparelho', 'estado', 'ts', 'assinatura']);
+    if (p.t !== 'parear.resposta' || p.pid !== contexto.pid || p.no !== contexto.nodeId || p.aparelho !== contexto.aparelhoId) falha('E_FORMATO');
+    if (ESTADOS_PAREAMENTO.indexOf(p.estado) < 0) falha('E_FORMATO');
+    exigirTs(p.ts, agora);
+    const semAss = Object.assign({}, p);
+    delete semAss.assinatura;
+    if (!(await verificarAssinatura(c.noPub, 'parear/resposta', utf8(canonico(semAss)), p.assinatura))) falha('E_ASSINATURA');
+    // Ordem: [pendente] → aceito | recusado; ou "usado" sozinho (outro aparelho chegou antes).
+    if (c.ultimo !== null && !(c.ultimo === 'pendente' && (p.estado === 'aceito' || p.estado === 'recusado'))) falha('E_PAREAMENTO_ESTADO');
+    c.ultimo = p.estado;
+    if (p.estado !== 'pendente') CONTEXTOS_PAREAMENTO.delete(contexto);
+    return {
+      estado: p.estado, nodeId: contexto.nodeId,
+      impressaoAparelho: contexto.impressaoAparelho, impressaoNo: contexto.impressaoNo,
+    };
+  }
+
+  // ===========================================================================================
+  // Sessão: aperto de mão e cifra dos quadros
+  // ===========================================================================================
+
+  const DIR_A2N = 1;
+  const DIR_N2A = 2;
+
+  function u64be(n) {
+    const b = new Uint8Array(8);
+    const dv = new DataView(b.buffer);
+    dv.setUint32(0, Math.floor(n / 0x100000000));
+    dv.setUint32(4, n >>> 0);
+    return b;
+  }
+  function nonceQuadro(dir, n) {
+    const b = new Uint8Array(12);
+    new DataView(b.buffer).setUint32(0, dir);
+    b.set(u64be(n), 4);
+    return b;
+  }
+  function aadQuadro(sidBytes, dir, n) { return concat(rotulo('dados'), sidBytes, new Uint8Array([dir]), u64be(n)); }
+
+  async function derivarChavesSessaoBrutas(segredoEcdh, hashTranscript) {
+    return {
+      a2n: await hkdf(segredoEcdh, hashTranscript, utf8(PREFIXO + 'sessao/a2n'), 32),
+      n2a: await hkdf(segredoEcdh, hashTranscript, utf8(PREFIXO + 'sessao/n2a'), 32),
+    };
+  }
+
+  const CHAVES_SESSAO = new WeakMap();
+
+  /**
+   * Sessão estabelecida. Um contador por direção, começando em 0 e exigido EXATO no
+   * recebimento (o WebSocket entrega em ordem): repetição, salto, reordenação, adulteração
+   * ou qualquer quadro malformado derrubam a sessão de vez.
+   */
+  class Sessao {
+    constructor(p) {
+      this.sid = p.sid;
+      this.papel = p.papel;
+      this.parId = p.parId;
+      this.proprioId = p.proprioId;
+      this.criadaEm = p.criadaEm;
+      this._sidBytes = deB64u(p.sid, 16);
+      this._dirEnvio = p.papel === 'aparelho' ? DIR_A2N : DIR_N2A;
+      this._dirReceb = p.papel === 'aparelho' ? DIR_N2A : DIR_A2N;
+      this._nEnvio = 0;
+      this._nReceb = 0;
+      this._seqComando = 0;   // aparelho: último seq enviado
+      this._ultimoSeq = 0;    // nó: último seq aceito
+      this._derrubada = false;
+      this._fila = Promise.resolve();
+      this._filaComandos = Promise.resolve();   // aparelho: criação de comandos, um por vez
+      CHAVES_SESSAO.set(this, { envio: p.envio, receb: p.receb, parPub: p.parPub });
+    }
+
+    get derrubada() { return this._derrubada; }
+    get chavePublicaPar() { const k = CHAVES_SESSAO.get(this); return k ? k.parPub : null; }
+
+    /** Descarta as chaves. Irreversível. */
+    derrubar() { this._derrubada = true; CHAVES_SESSAO.delete(this); }
+
+    _falhar(codigo, extra) { this.derrubar(); falha(codigo, extra); }
+
+    _vigente(agora) {
+      if (this._derrubada) falha('E_SESSAO_DERRUBADA');
+      if (agora - this.criadaEm > LIMITES.SESSAO_VIDA_MS) this._falhar('E_SESSAO_EXPIRADA');
+    }
+
+    _enfileirar(fn) {
+      const p = this._fila.then(fn);
+      this._fila = p.then(() => {}, () => {});
+      return p;
+    }
+
+    /** Cifra um objeto JSON e devolve o quadro { t:'dados', sid, n, ct }. */
+    cifrar(obj, opcoes) {
+      const agora = relogio(opcoes && opcoes.agora);
+      return this._enfileirar(async () => {
+        this._vigente(agora);
+        let claro;
+        try { claro = utf8(JSON.stringify(obj)); } catch (_) { falha('E_ARGUMENTO'); }
+        if (!ehObjetoSimples(obj) || claro.length > LIMITES.TEXTO_CLARO_MAX) falha('E_TAMANHO');
+        const n = this._nEnvio;
+        if (n >= LIMITES.SESSAO_QUADROS_MAX) this._falhar('E_LIMITE_SESSAO');
+        this._nEnvio = n + 1;
+        const k = CHAVES_SESSAO.get(this);
+        const ct = await aesSelar(k.envio, nonceQuadro(this._dirEnvio, n), claro, aadQuadro(this._sidBytes, this._dirEnvio, n));
+        return { t: 'dados', sid: this.sid, n, ct: b64u(ct) };
+      });
+    }
+
+    /** Decifra um quadro recebido e devolve o objeto. Qualquer defeito derruba a sessão. */
+    decifrar(quadro, opcoes) {
+      const agora = relogio(opcoes && opcoes.agora);
+      return this._enfileirar(async () => {
+        this._vigente(agora);
+        let bruto;
+        try {
+          exigirCampos(quadro, ['t', 'sid', 'n', 'ct']);
+          if (quadro.t !== 'dados' || quadro.sid !== this.sid || !inteiro(quadro.n, 0, LIMITES.SESSAO_QUADROS_MAX)) falha('E_FORMATO');
+          if (typeof quadro.ct !== 'string' || quadro.ct.length > LIMITES.DADOS_MAX) falha('E_TAMANHO');
+          bruto = deB64u(quadro.ct);
+        } catch (err) { this._falhar(err.codigo || 'E_FORMATO'); }
+        const n = this._nReceb;
+        if (quadro.n !== n) this._falhar('E_CONTADOR');
+        this._nReceb = n + 1;
+        const k = CHAVES_SESSAO.get(this);
+        let claro;
+        try {
+          claro = await aesAbrir(k.receb, nonceQuadro(this._dirReceb, n), bruto, aadQuadro(this._sidBytes, this._dirReceb, n));
+        } catch (_) { this._falhar('E_DECIFRAR'); }
+        try { return lerJsonTexto(deUtf8(claro)); } catch (_) { this._falhar('E_FORMATO'); }
+      });
+    }
+  }
+
+  async function montarSessao(p, brutas) {
+    const ehAparelho = p.papel === 'aparelho';
+    const envio = await chaveAes(ehAparelho ? brutas.a2n : brutas.n2a, ['encrypt']);
+    const receb = await chaveAes(ehAparelho ? brutas.n2a : brutas.a2n, ['decrypt']);
+    return new Sessao(Object.assign({}, p, { envio, receb }));
+  }
+
+  async function gerarEfemera() {
+    const par = await subtle().generateKey(ALG_ECDH, false, ['deriveBits']);
+    const pub = new Uint8Array(await subtle().exportKey('raw', par.publicKey));
+    return { priv: par.privateKey, pubB64: b64u(pub) };
+  }
+  async function importarEfemera(b64) {
+    const raw = deB64u(b64, 65);
+    if (raw[0] !== 4) falha('E_CHAVE');
+    try { return await subtle().importKey('raw', raw, ALG_ECDH, true, []); } catch (_) { falha('E_CHAVE'); }
+  }
+  async function segredoEcdh(priv, pub) {
+    try { return new Uint8Array(await subtle().deriveBits({ name: 'ECDH', public: pub }, priv, 256)); } catch (_) { falha('E_CHAVE'); }
+  }
+  async function hashTranscript(t) {
+    return sha256(utf8(canonico({
+      t: PREFIXO + 'sessao', v: VERSAO, sid: t.sid,
+      aparelho: t.aparelho, aparelhoSpki: t.aparelhoSpki, no: t.no, noSpki: t.noSpki, eA: t.eA, eN: t.eN,
+    })));
+  }
+
+  const ESTADOS_HANDSHAKE = new WeakMap();
+
+  /** Aparelho, passo 1: quadro sessao.ola. */
+  async function aparelhoIniciarSessao(opcoes) {
+    const o = opcoes || {};
+    const agora = relogio(o.agora);
+    exigirIdentidade(o.identidade, 'aparelho');
+    if (!ehId(o.noId)) falha('E_ARGUMENTO');
+    const noSpki = deB64u(o.noSpki);
+    const noPub = await importarSpki(noSpki);
+    if (idDeHash(await sha256(noSpki)) !== o.noId) falha('E_ID');
+    const sid = b64u(aleatorio(16));
+    const ef = await gerarEfemera();
+    const quadro = { t: 'sessao.ola', v: VERSAO, sid, aparelho: o.identidade.id, no: o.noId, eA: ef.pubB64 };
+    const estado = Object.freeze({ sid, papel: 'aparelho' });
+    ESTADOS_HANDSHAKE.set(estado, { ident: o.identidade, noId: o.noId, noSpki: o.noSpki, noPub, ef, criadoEm: agora });
+    return { quadro, estado };
+  }
+
+  /** Nó, passo 2: recebe sessao.ola e devolve sessao.resposta (assinada pelo nó). */
+  async function noResponderSessao(opcoes) {
+    const o = opcoes || {};
+    const agora = relogio(o.agora);
+    exigirIdentidade(o.identidade, 'no');
+    if (typeof o.buscarAparelho !== 'function') falha('E_ARGUMENTO');
+    const q = o.quadro;
+    exigirCampos(q, ['t', 'v', 'sid', 'aparelho', 'no', 'eA']);
+    if (q.t !== 'sessao.ola') falha('E_FORMATO');
+    if (q.v !== VERSAO) falha('E_VERSAO');
+    if (!ehId(q.sid) || !ehId(q.aparelho)) falha('E_FORMATO');
+    deB64u(q.sid, 16);
+    if (q.no !== o.identidade.id) falha('E_SESSAO');
+    if (o.origem !== undefined && o.origem !== q.aparelho) falha('E_SESSAO');
+    const spkiB64 = await o.buscarAparelho(q.aparelho);
+    if (typeof spkiB64 !== 'string') falha('E_APARELHO_NAO_AUTORIZADO');
+    const spki = deB64u(spkiB64);
+    const parPub = await importarSpki(spki);
+    if (idDeHash(await sha256(spki)) !== q.aparelho) falha('E_ID');
+    const eA = await importarEfemera(q.eA);
+
+    const ef = await gerarEfemera();
+    const compartilhado = await segredoEcdh(ef.priv, eA);
+    const th = await hashTranscript({
+      sid: q.sid, aparelho: q.aparelho, aparelhoSpki: spkiB64, no: o.identidade.id, noSpki: o.identidade.spkiB64, eA: q.eA, eN: ef.pubB64,
+    });
+    const assinatura = await assinar(o.identidade.chavePrivada, 'sessao/no', th);
+    const brutas = await derivarChavesSessaoBrutas(compartilhado, th);
+    compartilhado.fill(0);
+    // A efêmera do nó sai de escopo aqui: só as chaves de sessão derivadas seguem.
+    const estado = Object.freeze({ sid: q.sid, papel: 'no', aparelhoId: q.aparelho });
+    ESTADOS_HANDSHAKE.set(estado, { th, brutas, parPub, criadoEm: agora, proprioId: o.identidade.id });
+    return { quadro: { t: 'sessao.resposta', v: VERSAO, sid: q.sid, eN: ef.pubB64, assinatura }, estado };
+  }
+
+  /** Aparelho, passo 3: confere a assinatura do nó, devolve sessao.confirma e a Sessao. */
+  async function aparelhoConcluirSessao(estado, quadro, opcoes) {
+    const agora = relogio(opcoes && opcoes.agora);
+    const h = estado ? ESTADOS_HANDSHAKE.get(estado) : undefined;
+    if (!h || estado.papel !== 'aparelho') falha('E_SESSAO');
+    ESTADOS_HANDSHAKE.delete(estado);   // uso único, dê certo ou não
+    if (agora - h.criadoEm > LIMITES.HANDSHAKE_MS) falha('E_HANDSHAKE_EXPIRADO');
+    exigirCampos(quadro, ['t', 'v', 'sid', 'eN', 'assinatura']);
+    if (quadro.t !== 'sessao.resposta') falha('E_FORMATO');
+    if (quadro.v !== VERSAO) falha('E_VERSAO');
+    if (quadro.sid !== estado.sid) falha('E_SESSAO');
+    const eN = await importarEfemera(quadro.eN);
+    const th = await hashTranscript({
+      sid: estado.sid, aparelho: h.ident.id, aparelhoSpki: h.ident.spkiB64, no: h.noId, noSpki: h.noSpki, eA: h.ef.pubB64, eN: quadro.eN,
+    });
+    if (!(await verificarAssinatura(h.noPub, 'sessao/no', th, quadro.assinatura))) falha('E_ASSINATURA');
+    const compartilhado = await segredoEcdh(h.ef.priv, eN);
+    h.ef = null;
+    const brutas = await derivarChavesSessaoBrutas(compartilhado, th);
+    compartilhado.fill(0);
+    const assinatura = await assinar(h.ident.chavePrivada, 'sessao/aparelho', th);
+    const sessao = await montarSessao({
+      sid: estado.sid, papel: 'aparelho', parId: h.noId, proprioId: h.ident.id, criadaEm: agora, parPub: h.noPub,
+    }, brutas);
+    return { quadro: { t: 'sessao.confirma', v: VERSAO, sid: estado.sid, assinatura }, sessao };
+  }
+
+  /** Nó, passo 4: confere a assinatura do aparelho (e se ele ainda está autorizado). */
+  async function noConcluirSessao(estado, quadro, opcoes) {
+    const o = opcoes || {};
+    const agora = relogio(o.agora);
+    const h = estado ? ESTADOS_HANDSHAKE.get(estado) : undefined;
+    if (!h || estado.papel !== 'no') falha('E_SESSAO');
+    ESTADOS_HANDSHAKE.delete(estado);
+    const zerar = () => { h.brutas.a2n.fill(0); h.brutas.n2a.fill(0); };
+    try {
+      if (agora - h.criadoEm > LIMITES.HANDSHAKE_MS) falha('E_HANDSHAKE_EXPIRADO');
+      exigirCampos(quadro, ['t', 'v', 'sid', 'assinatura']);
+      if (quadro.t !== 'sessao.confirma') falha('E_FORMATO');
+      if (quadro.v !== VERSAO) falha('E_VERSAO');
+      if (quadro.sid !== estado.sid) falha('E_SESSAO');
+      if (typeof o.buscarAparelho === 'function') {
+        const ainda = await o.buscarAparelho(estado.aparelhoId);
+        if (typeof ainda !== 'string') falha('E_APARELHO_NAO_AUTORIZADO');
+      }
+      if (!(await verificarAssinatura(h.parPub, 'sessao/aparelho', h.th, quadro.assinatura))) falha('E_ASSINATURA');
+    } catch (err) { zerar(); throw err; }
+    return montarSessao({
+      sid: estado.sid, papel: 'no', parId: estado.aparelhoId, proprioId: h.proprioId, criadaEm: agora, parPub: h.parPub,
+    }, h.brutas);
+  }
+
+  // ===========================================================================================
+  // Comandos (lista fechada da entrega 1)
+  // ===========================================================================================
+
+  function paramsVazios(p) { exigirCampos(p, []); }
+  function paramsTerminal(p, opcionais) {
+    exigirCampos(p, ['terminalId'], opcionais);
+    if (typeof p.terminalId !== 'string' || !RX_TERMINAL.test(p.terminalId)) falha('E_PARAMS');
+  }
+
+  const VALIDADORES = Object.freeze({
+    'hub.status': paramsVazios,
+    'terminals.list': paramsVazios,
+    'terminal.watch': function (p) {
+      paramsTerminal(p, ['historico']);
+      if (p.historico !== undefined && !inteiro(p.historico, 0, LIMITES.HISTORICO_MAX)) falha('E_PARAMS');
+    },
+    'terminal.unwatch': function (p) { paramsTerminal(p); },
+    'hub.stopAll': function (p) {
+      exigirCampos(p, ['confirmar']);
+      if (p.confirmar !== true) falha('E_PARAMS');
+    },
+  });
+  const METODOS = Object.freeze(Object.keys(VALIDADORES));
+
+  /** Lança E_METODO (fora da lista) ou E_PARAMS (formato errado). */
+  function validarParametros(metodo, params) {
+    if (typeof metodo !== 'string' || !Object.prototype.hasOwnProperty.call(VALIDADORES, metodo)) falha('E_METODO');
+    try { VALIDADORES[metodo](params); } catch (_) { falha('E_PARAMS'); }
+    return true;
+  }
+
+  /**
+   * Aparelho: monta, assina e cifra um comando. Devolve Promise<{ quadro, seq }>.
+   * Serializado por sessão: reservar o `seq`, assinar e cifrar acontecem um comando de cada
+   * vez, na ordem das chamadas. Assim a ordem dos `seq` é sempre a ordem dos contadores `n`
+   * dos quadros (sem isso, chamadas simultâneas trocavam a ordem e o nó derrubava a sessão
+   * com E_SEQ). As promessas resolvem na ordem das chamadas: quem enviar cada quadro assim
+   * que a sua promessa resolver envia na ordem certa (§5).
+   */
+  function aparelhoCriarComando(sessao, identidade, metodo, params, opcoes) {
+    let agora;
+    try {
+      agora = relogio(opcoes && opcoes.agora);
+      if (!(sessao instanceof Sessao) || sessao.papel !== 'aparelho') falha('E_ARGUMENTO');
+      exigirIdentidade(identidade, 'aparelho');
+      if (identidade.id !== sessao.proprioId) falha('E_ARGUMENTO');
+      validarParametros(metodo, params);
+    } catch (err) { return Promise.reject(err); }
+    const p = sessao._filaComandos.then(async () => {
+      sessao._vigente(agora);
+      const seq = sessao._seqComando + 1;
+      // `no` amarra o comando ao nó desta sessão (além do sid): a assinatura do aparelho só
+      // vale para este nó.
+      const env = { sessao: sessao.sid, no: sessao.parId, seq, metodo, params, ts: agora };
+      const assinatura = await assinar(identidade.chavePrivada, 'comando', utf8(canonico(env)));
+      const quadro = await sessao.cifrar({ k: 'cmd', env, assinatura }, { agora });
+      // Só conta o seq depois que o quadro existe: comando que falhou não abre buraco.
+      sessao._seqComando = seq;
+      return { quadro, seq };
+    });
+    sessao._filaComandos = p.then(() => {}, () => {});
+    return p;
+  }
+
+  /**
+   * Nó: decifra e confere um comando. Devolve { seq, metodo, params }.
+   * Derrubam a sessão: falha de cifra, de assinatura, sessão trocada, seq não crescente,
+   * aparelho revogado. Só recusam o comando (sessão segue): E_TEMPO, E_METODO, E_PARAMS.
+   */
+  async function noAbrirComando(sessao, quadro, opcoes) {
+    const o = opcoes || {};
+    const agora = relogio(o.agora);
+    if (!(sessao instanceof Sessao) || sessao.papel !== 'no') falha('E_ARGUMENTO');
+    if (typeof o.aparelhoAutorizado === 'function' && !(await o.aparelhoAutorizado(sessao.parId))) {
+      sessao._falhar('E_APARELHO_NAO_AUTORIZADO');
+    }
+    const msg = await sessao.decifrar(quadro, { agora });
+    let env, dadosAssinados;
+    try {
+      exigirCampos(msg, ['k', 'env', 'assinatura']);
+      if (msg.k !== 'cmd') falha('E_FORMATO');
+      env = msg.env;
+      exigirCampos(env, ['sessao', 'no', 'seq', 'metodo', 'params', 'ts']);
+      dadosAssinados = utf8(canonico(env));
+    } catch (_) { sessao._falhar('E_FORMATO'); }
+    if (env.sessao !== sessao.sid || env.no !== sessao.proprioId) sessao._falhar('E_SESSAO');
+    if (!(await verificarAssinatura(sessao.chavePublicaPar, 'comando', dadosAssinados, msg.assinatura))) sessao._falhar('E_ASSINATURA');
+    if (!inteiro(env.seq, 1, Number.MAX_SAFE_INTEGER) || env.seq <= sessao._ultimoSeq) sessao._falhar('E_SEQ');
+    sessao._ultimoSeq = env.seq;
+    const seq = env.seq;
+    try { exigirTs(env.ts, agora); } catch (err) { falha(err.codigo, { seq }); }
+    try { validarParametros(env.metodo, env.params); } catch (err) { falha(err.codigo, { seq }); }
+    return { seq, metodo: env.metodo, params: env.params };
+  }
+
+  /** Nó: resposta a um comando. `erro` é só um código E_*; nada de texto livre. */
+  async function noResponder(sessao, seq, r, opcoes) {
+    if (!(sessao instanceof Sessao) || sessao.papel !== 'no') falha('E_ARGUMENTO');
+    if (!inteiro(seq, 1, Number.MAX_SAFE_INTEGER) || !ehObjetoSimples(r)) falha('E_ARGUMENTO');
+    let msg;
+    if (Object.prototype.hasOwnProperty.call(r, 'erro')) {
+      if (typeof r.erro !== 'string' || !RX_CODIGO.test(r.erro)) falha('E_ARGUMENTO');
+      msg = { k: 'resp', seq, ok: false, erro: { codigo: r.erro } };
+    } else {
+      msg = { k: 'resp', seq, ok: true, resultado: r.resultado === undefined ? null : r.resultado };
+    }
+    return sessao.cifrar(msg, opcoes);
+  }
+
+  /** Nó: evento assíncrono (ex.: 'terminal.tela', 'hub.estado'). */
+  async function noEnviarEvento(sessao, tipo, dados, opcoes) {
+    if (!(sessao instanceof Sessao) || sessao.papel !== 'no') falha('E_ARGUMENTO');
+    if (typeof tipo !== 'string' || !RX_EVENTO.test(tipo)) falha('E_ARGUMENTO');
+    return sessao.cifrar({ k: 'evento', tipo, dados: dados === undefined ? null : dados }, opcoes);
+  }
+
+  /** Aparelho: abre resposta ou evento do nó. */
+  async function aparelhoAbrirMensagem(sessao, quadro, opcoes) {
+    if (!(sessao instanceof Sessao) || sessao.papel !== 'aparelho') falha('E_ARGUMENTO');
+    const msg = await sessao.decifrar(quadro, opcoes);
+    try {
+      if (msg.k === 'resp') {
+        if (msg.ok === true) exigirCampos(msg, ['k', 'seq', 'ok', 'resultado']);
+        else if (msg.ok === false) {
+          exigirCampos(msg, ['k', 'seq', 'ok', 'erro']);
+          exigirCampos(msg.erro, ['codigo']);
+          if (typeof msg.erro.codigo !== 'string' || !RX_CODIGO.test(msg.erro.codigo)) falha('E_FORMATO');
+        } else falha('E_FORMATO');
+        if (!inteiro(msg.seq, 1, sessao._seqComando)) falha('E_FORMATO');
+      } else if (msg.k === 'evento') {
+        exigirCampos(msg, ['k', 'tipo', 'dados']);
+        if (typeof msg.tipo !== 'string' || !RX_EVENTO.test(msg.tipo)) falha('E_FORMATO');
+      } else falha('E_FORMATO');
+    } catch (_) { sessao._falhar('E_FORMATO'); }
+    return msg;
+  }
+
+  // ===========================================================================================
+  // Controle com o relay
+  // ===========================================================================================
+
+  const DESAFIOS = new WeakMap();
+  const PAPEIS_RELAY = Object.freeze(['no', 'aparelho']);
+
+  /** Relay: cria o desafio enviado logo que a conexão abre. */
+  function relayCriarDesafio(opcoes) {
+    const o = opcoes || {};
+    const agora = relogio(o.agora);
+    const relay = validarRelay(o.relay, !!o.permitirLocal);
+    const nonce = b64u(aleatorio(32));
+    const quadro = { t: 'relay.desafio', v: VERSAO, nonce, relay: relay.relay };
+    const estado = Object.freeze({ nonce });
+    DESAFIOS.set(estado, { relay: relay.relay, criadoEm: agora, usado: false });
+    return { quadro, estado };
+  }
+
+  function dadosAuthRelay(papel, id, nonce, relay) {
+    return utf8(canonico({ t: 'relay.auth', v: VERSAO, papel, id, nonce, relay }));
+  }
+
+  /** Nó ou aparelho: responde o desafio do relay, conferindo que é o relay esperado. */
+  async function clienteResponderDesafio(opcoes) {
+    const o = opcoes || {};
+    const ident = o.identidade;
+    if (!ident || !IDENTIDADES.has(ident)) falha('E_ARGUMENTO');
+    const q = o.quadro;
+    exigirCampos(q, ['t', 'v', 'nonce', 'relay']);
+    if (q.t !== 'relay.desafio') falha('E_FORMATO');
+    if (q.v !== VERSAO) falha('E_VERSAO');
+    deB64u(q.nonce, 32);
+    if (typeof o.relayEsperado !== 'string' || q.relay !== o.relayEsperado) falha('E_DESAFIO');
+    const assinatura = await assinar(ident.chavePrivada, 'relay/auth', dadosAuthRelay(ident.tipo, ident.id, q.nonce, q.relay));
+    return { t: 'relay.auth', v: VERSAO, papel: ident.tipo, id: ident.id, spki: ident.spkiB64, assinatura };
+  }
+
+  /**
+   * Relay: confere a resposta. Devolve { papel, id, spki }. Para papel 'aparelho', o relay
+   * ainda precisa conferir que o id está em alguma lista vigente (etapa do relay).
+   */
+  async function relayVerificarAuth(estado, quadro, opcoes) {
+    const agora = relogio(opcoes && opcoes.agora);
+    const d = estado ? DESAFIOS.get(estado) : undefined;
+    if (!d || d.usado) falha('E_DESAFIO');
+    d.usado = true;
+    DESAFIOS.delete(estado);
+    if (agora - d.criadoEm > LIMITES.DESAFIO_MS || agora < d.criadoEm) falha('E_DESAFIO');
+    exigirCampos(quadro, ['t', 'v', 'papel', 'id', 'spki', 'assinatura']);
+    if (quadro.t !== 'relay.auth') falha('E_FORMATO');
+    if (quadro.v !== VERSAO) falha('E_VERSAO');
+    if (PAPEIS_RELAY.indexOf(quadro.papel) < 0 || !ehId(quadro.id)) falha('E_FORMATO');
+    const spki = deB64u(quadro.spki);
+    const pub = await importarSpki(spki);
+    if (idDeHash(await sha256(spki)) !== quadro.id) falha('E_ID');
+    if (!(await verificarAssinatura(pub, 'relay/auth', dadosAuthRelay(quadro.papel, quadro.id, estado.nonce, d.relay), quadro.assinatura))) {
+      falha('E_ASSINATURA');
+    }
+    return { papel: quadro.papel, id: quadro.id, spki: quadro.spki };
+  }
+
+  async function validarEntradasLista(aparelhos) {
+    if (!Array.isArray(aparelhos) || aparelhos.length > LIMITES.APARELHOS_MAX) falha('E_LISTA_INVALIDA');
+    let anterior = '';
+    for (const a of aparelhos) {
+      try { exigirCampos(a, ['id', 'spki']); } catch (_) { falha('E_LISTA_INVALIDA'); }
+      if (!ehId(a.id) || a.id <= anterior) falha('E_LISTA_INVALIDA');   // ordenada por id, sem repetição
+      let spki;
+      try { spki = deB64u(a.spki); validarSpki(spki); } catch (_) { falha('E_LISTA_INVALIDA'); }
+      if (idDeHash(await sha256(spki)) !== a.id) falha('E_LISTA_INVALIDA');
+      anterior = a.id;
+    }
+  }
+
+  /** Nó: assina a lista de aparelhos autorizados. Revogar = nova versão sem o aparelho. */
+  async function noAssinarListaAparelhos(identidade, opcoes) {
+    exigirIdentidade(identidade, 'no');
+    const o = opcoes || {};
+    const agora = relogio(o.agora);
+    if (!inteiro(o.versao, 1, Number.MAX_SAFE_INTEGER) || !Array.isArray(o.aparelhos)) falha('E_ARGUMENTO');
+    const aparelhos = o.aparelhos.map(a => ({ id: a && a.id, spki: a && a.spki }))
+      .sort((x, y) => (x.id < y.id ? -1 : x.id > y.id ? 1 : 0));
+    await validarEntradasLista(aparelhos);
+    const lista = { no: identidade.id, versao: o.versao, emitidaEm: agora, aparelhos };
+    const assinatura = await assinar(identidade.chavePrivada, 'lista-aparelhos', utf8(canonico(lista)));
+    return { t: 'relay.lista', lista, assinatura };
+  }
+
+  /**
+   * Relay (e hub): confere assinatura, dono e versão estritamente maior que `versaoAtual`.
+   * Devolve a lista validada.
+   */
+  async function verificarListaAparelhos(quadro, opcoes) {
+    const o = opcoes || {};
+    const versaoAtual = o.versaoAtual === undefined ? 0 : o.versaoAtual;
+    if (!inteiro(versaoAtual, 0, Number.MAX_SAFE_INTEGER)) falha('E_ARGUMENTO');
+    exigirCampos(quadro, ['t', 'lista', 'assinatura']);
+    if (quadro.t !== 'relay.lista') falha('E_FORMATO');
+    const l = quadro.lista;
+    try { exigirCampos(l, ['no', 'versao', 'emitidaEm', 'aparelhos']); } catch (_) { falha('E_LISTA_INVALIDA'); }
+    if (!ehId(l.no) || !inteiro(l.versao, 1, Number.MAX_SAFE_INTEGER) || !inteiro(l.emitidaEm, 0, Number.MAX_SAFE_INTEGER)) falha('E_LISTA_INVALIDA');
+    const noSpki = deB64u(o.noSpki);
+    const noPub = await importarSpki(noSpki);
+    if (idDeHash(await sha256(noSpki)) !== l.no) falha('E_ID');
+    let dados;
+    try { dados = utf8(canonico(l)); } catch (_) { falha('E_LISTA_INVALIDA'); }
+    if (!(await verificarAssinatura(noPub, 'lista-aparelhos', dados, quadro.assinatura))) falha('E_ASSINATURA');
+    if (l.versao <= versaoAtual) falha('E_LISTA_VERSAO');
+    await validarEntradasLista(l.aparelhos);
+    return l;
+  }
+
+  // Esquemas fechados dos quadros de controle. `dados` é sempre texto opaco para o relay.
+  const ESQUEMAS_RELAY = Object.freeze({
+    'para-relay': {
+      'relay.auth': [['v', 'papel', 'id', 'spki', 'assinatura']],
+      'relay.lista': [['lista', 'assinatura']],
+      'relay.parear.abrir': [['pid', 'exp']],
+      'relay.parear.fechar': [['pid']],
+      'parear.enviar': [['pid', 'dados']],
+      'parear.responder': [['canal', 'dados']],
+      'rota': [['para', 'dados']],
+      'relay.ping': [[]],
+    },
+    'do-relay': {
+      'relay.desafio': [['v', 'nonce', 'relay']],
+      'relay.ok': [['papel', 'id']],
+      'relay.erro': [['codigo']],
+      'relay.presenca': [['no', 'online']],
+      'rota': [['de', 'dados']],
+      'parear.chegou': [['pid', 'dados'], ['canal']],
+      'relay.pong': [[]],
+    },
+  });
+
+  /** Valida um quadro de controle (já analisado). direcao: 'para-relay' | 'do-relay'. */
+  function validarQuadroRelay(q, direcao) {
+    const tabela = ESQUEMAS_RELAY[direcao];
+    if (!tabela) falha('E_ARGUMENTO');
+    if (!ehObjetoSimples(q) || typeof q.t !== 'string' || !Object.prototype.hasOwnProperty.call(tabela, q.t)) falha('E_FORMATO');
+    const esq = tabela[q.t];
+    exigirCampos(q, ['t'].concat(esq[0]), esq[1]);
+    for (const k of Object.keys(q)) {
+      const v = q[k];
+      switch (k) {
+        case 't': break;
+        case 'v': if (v !== VERSAO) falha('E_VERSAO'); break;
+        case 'id': case 'para': case 'de': case 'no': case 'pid': case 'canal':
+          if (!ehId(v)) falha('E_FORMATO'); break;
+        case 'dados':
+          if (typeof v !== 'string' || v.length > LIMITES.DADOS_MAX) falha(typeof v === 'string' ? 'E_TAMANHO' : 'E_FORMATO');
+          break;
+        case 'papel': if (PAPEIS_RELAY.indexOf(v) < 0) falha('E_FORMATO'); break;
+        case 'exp': if (!inteiro(v, 0, Number.MAX_SAFE_INTEGER)) falha('E_FORMATO'); break;
+        case 'online': if (typeof v !== 'boolean') falha('E_FORMATO'); break;
+        case 'codigo': if (typeof v !== 'string' || !RX_CODIGO.test(v)) falha('E_FORMATO'); break;
+        case 'nonce': deB64u(v, 32); break;
+        case 'assinatura': deB64u(v, 64); break;
+        case 'spki': if (typeof v !== 'string' || v.length > 200) falha('E_FORMATO'); break;
+        case 'relay': if (typeof v !== 'string' || v.length > 255) falha('E_FORMATO'); break;
+        case 'lista': if (!ehObjetoSimples(v)) falha('E_FORMATO'); break;
+        default: falha('E_FORMATO');
+      }
+    }
+    return q;
+  }
+
+  /** Tamanho + JSON + esquema, numa chamada. É o que o relay faz com cada mensagem. */
+  function lerQuadroRelay(texto, direcao) {
+    if (typeof texto !== 'string') falha('E_FORMATO');
+    verificarTamanhoQuadro(texto);
+    return validarQuadroRelay(lerJsonTexto(texto), direcao);
+  }
+
+  /** Lê o quadro fim a fim que viaja em `dados` (só nas pontas; o relay não chama isto). */
+  function lerQuadroFimAFim(texto) {
+    if (typeof texto !== 'string' || texto.length > LIMITES.DADOS_MAX) falha('E_TAMANHO');
+    return lerJsonTexto(texto);
+  }
+
+  /** Balde de fichas. `taxa` fichas por segundo, até `rajada` acumuladas. */
+  class LimitadorTaxa {
+    constructor(opcoes) {
+      const o = opcoes || {};
+      if (!(o.taxa > 0) || !(o.rajada > 0)) falha('E_ARGUMENTO');
+      this.taxa = o.taxa;
+      this.rajada = o.rajada;
+      this._fichas = o.rajada;
+      this._t = relogio(o.agora);
+    }
+    permitir(custo, agora) {
+      const c = custo === undefined ? 1 : custo;
+      const t = relogio(agora);
+      if (t > this._t) {
+        this._fichas = Math.min(this.rajada, this._fichas + ((t - this._t) / 1000) * this.taxa);
+        this._t = t;
+      }
+      if (c > this._fichas) return false;
+      this._fichas -= c;
+      return true;
+    }
+  }
+
+  /** Limites padrão por conexão. papel 'anonimo' = conexão de pareamento sem identidade. */
+  function criarLimitesConexao(papel, agora) {
+    if (papel === 'anonimo') {
+      return {
+        quadros: new LimitadorTaxa({ taxa: LIMITES.ANON_QUADROS_MIN / 60, rajada: LIMITES.ANON_QUADROS_MIN, agora }),
+        bytes: new LimitadorTaxa({ taxa: 8192, rajada: 2 * LIMITES.QUADRO_MAX, agora }),
+      };
+    }
+    return {
+      quadros: new LimitadorTaxa({ taxa: LIMITES.TAXA_QUADROS_S, rajada: LIMITES.RAJADA_QUADROS, agora }),
+      bytes: new LimitadorTaxa({ taxa: LIMITES.TAXA_BYTES_S, rajada: LIMITES.RAJADA_BYTES, agora }),
+    };
+  }
+  /** Lança E_TAXA se a mensagem (tamanho em bytes) estoura qualquer um dos dois baldes. */
+  function exigirTaxa(limites, tamanho, agora) {
+    const t = relogio(agora);
+    if (!limites.quadros.permitir(1, t) || !limites.bytes.permitir(tamanho, t)) falha('E_TAXA');
+  }
+
+  // ===========================================================================================
+  // API pública
+  // ===========================================================================================
+
+  return Object.freeze({
+    VERSAO,
+    LIMITES,
+    CODIGOS,
+    METODOS,
+    TsProtoErro,
+
+    // codificação
+    b64u,
+    deB64u,
+    hex,
+    canonico,
+    verificarTamanhoQuadro,
+    lerQuadroFimAFim,
+
+    // primitivas
+    sha256,
+    hkdf,
+
+    // identidades
+    gerarIdentidade,
+    identidadeDeChaves,
+    exportarIdentidadeNo,
+    importarIdentidadeNo,
+    idDeSpki,
+    impressaoDeSpki,
+    comprimirSpki,
+    descomprimirSpki,
+
+    // pareamento
+    RegistroPareamentos,
+    lerConvite,
+    validarOrigemPwa,
+    criarPedidoPareamento,
+    abrirRespostaPareamento,
+    normalizarNome,
+
+    // sessão
+    Sessao,
+    aparelhoIniciarSessao,
+    noResponderSessao,
+    aparelhoConcluirSessao,
+    noConcluirSessao,
+
+    // comandos
+    validarParametros,
+    aparelhoCriarComando,
+    noAbrirComando,
+    noResponder,
+    noEnviarEvento,
+    aparelhoAbrirMensagem,
+
+    // relay
+    relayCriarDesafio,
+    clienteResponderDesafio,
+    relayVerificarAuth,
+    noAssinarListaAparelhos,
+    verificarListaAparelhos,
+    validarQuadroRelay,
+    lerQuadroRelay,
+    LimitadorTaxa,
+    criarLimitesConexao,
+    exigirTaxa,
+
+    // só para testes de vetores (mesmo caminho de código da produção)
+    _interno: Object.freeze({
+      derivarChavesSessaoBrutas,
+      nonceQuadro,
+      aadQuadro,
+      rotulo,
+      montarSessao: function (p, brutas) {
+        return montarSessao({
+          sid: p.sid, papel: p.papel, parId: p.parId, proprioId: p.proprioId, criadaEm: relogio(p.criadaEm), parPub: p.parPub || null,
+        }, { a2n: comoBytes(brutas.a2n).slice(), n2a: comoBytes(brutas.n2a).slice() });
+      },
+    }),
+  });
+});