terminal-smart-cli 0.98.1 → 0.99.0

package/hub/hub.js

@@ -0,0 +1,717 @@
+'use strict';
+// Núcleo do `ts hub` (etapa 3 do plano). Usa só as funções de ./proto/ts-proto.js para
+// cripto e formato; aqui fica a política: quem está autorizado, o que cada comando faz,
+// pareamento com confirmação humana no PC, revogação imediata e Parar tudo (com confirmação
+// de um consumidor externo, hub/parar.js). Terminais: o hub só LÊ instantâneos gravados por
+// `ts hub exportar-telas` (hub/telas-arquivo.js); não fala com o tmux.
+
+const os = require('os');
+const path = require('path');
+const P = require('./proto/ts-proto.js');
+const estado = require('./estado');
+const { ConexaoRelay, normalizarRelay } = require('./relay-conexao');
+const { criarProvedorTmux, provedorVazio, sanitizarTela, cortarTela, TELA_MAX_BYTES } = require('./tmux');
+const { criarProvedorTelas } = require('./telas-arquivo');
+const { Parada } = require('./parar');
+const { mascararSegredos } = require('./mascara');
+
+const RELAY_PADRAO = 'https://relay.terminalsmart.com.br';
+// Com o relay oficial, a PWA vem de origem estática separada (R2): quem invadir o relay
+// não troca a página que guarda a chave do aparelho.
+const PWA_PADRAO = 'https://celular.terminalsmart.com.br';
+const RX_CODIGO = /^E_[A-Z_]{1,40}$/;
+const HANDSHAKES_POR_APARELHO = 4;
+const ACOMPANHAMENTOS_POR_SESSAO = 8;
+const TERMINAIS_MAX = 100;
+const CONFIRMACAO_TENTATIVAS = 3;     // códigos errados digitados no PC antes de recusar
+const AVISOS_POR_APARELHO = 5;        // hub.aparelhoNovo guardados para quem está sem sessão
+
+/** "8 primeiros caracteres da impressão digital" digitados no PC (sem hífen, sem caixa). */
+function confereImpressao(digitado, impressao) {
+  if (typeof digitado !== 'string' || typeof impressao !== 'string') return false;
+  const d = digitado.replace(/[-\s]/g, '').toUpperCase();
+  const alvo = impressao.replace(/-/g, '').toUpperCase();
+  return d.length >= 8 && d.length <= alvo.length && /^[0-9A-F]+$/.test(d) && alvo.startsWith(d);
+}
+
+/**
+ * Provedor de terminais: telas em arquivo (TS_HUB_TELAS_DIR) é o normal. O tmux direto
+ * (TS_HUB_TMUX_DIRETO=1) é só para desenvolvimento e testes. Sem nada configurado: nenhum.
+ */
+function provedorPadrao(o, log) {
+  if (o.provedor) return o.provedor;
+  const env = o.env || process.env;
+  if (env.TS_HUB_TMUX_DIRETO === '1') {
+    log('AVISO: TS_HUB_TMUX_DIRETO=1 (o hub lê o tmux direto; só para desenvolvimento)');
+    return criarProvedorTmux();
+  }
+  const dir = o.telasDir || env.TS_HUB_TELAS_DIR;
+  if (dir) return criarProvedorTelas({ dir });
+  return provedorVazio();
+}
+
+function erro(codigo) { return Object.assign(new Error(codigo), { codigo }); }
+
+function ehLocalHttp(u) {
+  try {
+    const x = new URL(String(u));
+    return x.protocol === 'http:' && /^(localhost|127\.0\.0\.1|\[::1\])$|\.localhost$/i.test(x.hostname);
+  } catch (_) { return false; }
+}
+function uidDoAmbiente(v) {
+  if (v === undefined || v === '') return 0;
+  const n = Number(v);
+  return Number.isSafeInteger(n) && n >= 0 ? n : 0;
+}
+
+function versaoPacote() {
+  try { return require('../package.json').version; } catch (_) { return '0'; }
+}
+
+class Hub {
+  /** Cria o hub a partir do diretório de estado (gera a chave do nó na primeira vez). */
+  static async criar(opcoes) {
+    const o = opcoes || {};
+    const dir = path.resolve(o.dir || estado.dirPadrao());
+    const avisar = o.log || (() => {});
+    estado.garantirDir(dir);
+    const { identidade, criada } = await estado.carregarOuCriarIdentidade(dir, { protetor: o.protetor, avisar });
+    const aparelhos = await new estado.Aparelhos(dir).carregar(avisar);
+    const hub = new Hub(Object.assign({}, o, { dir, identidade, aparelhos }));
+    hub.chaveCriada = criada;
+    if (aparelhos.restauradoDeBackup || aparelhos.mantidosRevogados.length) {
+      hub.auditar({ tipo: 'estado', resultado: 'backup_antigo' });
+      for (const id of aparelhos.mantidosRevogados) hub.auditar({ tipo: 'revogacao', aparelho: id, resultado: 'mantida' });
+    }
+    return hub;
+  }
+
+  constructor(o) {
+    this.dir = o.dir;
+    this.ident = o.identidade;
+    this.aparelhos = o.aparelhos;
+    this.log = o.log || (() => {});
+    this.agora = o.agora || Date.now;
+    this.nome = String(o.nome || process.env.TS_HUB_NOME || os.hostname()).slice(0, 64);
+    this.versao = versaoPacote();
+    const r = normalizarRelay(o.relay || process.env.TS_HUB_RELAY || RELAY_PADRAO);
+    this.relay = r.origem;
+    this.permitirLocal = r.local;
+    // Origem da PWA para o QR (TS_HUB_PWA_URL); padrão = PWA_PADRAO com o relay oficial, senão o
+    // próprio relay (https://host do relay).
+    const pwa = o.pwa || process.env.TS_HUB_PWA_URL || (r.origem === 'wss://relay.terminalsmart.com.br' ? PWA_PADRAO : undefined);
+    this.pwa = undefined;
+    if (pwa) {
+      try { this.pwa = P.validarOrigemPwa(String(pwa).trim().replace(/\/$/, ''), r.local || ehLocalHttp(pwa)); } catch (_) {
+        throw new Error('TS_HUB_PWA_URL inválida (use https://host[:porta], sem caminho; http:// só para localhost)');
+      }
+    }
+    this.parada = new Parada({
+      dir: o.pararDir !== undefined ? o.pararDir : (process.env.TS_HUB_PARAR_DIR || null),
+      prazoMs: o.pararPrazoMs, sondaMs: o.pararSondaMs,
+      donoUid: o.pararDonoUid !== undefined ? o.pararDonoUid : uidDoAmbiente(process.env.TS_HUB_PARAR_DONO_UID),
+    });
+    this.provedor = provedorPadrao(o, this.log);
+    this.sondagemMs = o.sondagemMs || 250;
+    this.intervaloTelaMs = o.intervaloTelaMs || 500;          // ≤ 2 telas/s por terminal
+    this.conviteValidadeMs = o.conviteValidadeMs || P.LIMITES.CONVITE_VALIDADE_MS;
+    this.aparelhosMax = Math.min(P.LIMITES.APARELHOS_MAX,
+      o.aparelhosMax || Number(process.env.TS_HUB_APARELHOS_MAX) || 3);
+    this.auditar = estado.criarAuditoria(this.dir);
+    this.registro = new P.RegistroPareamentos({ identidade: this.ident });
+    this.convites = new Map();      // pid → { pid, exp, ouvinte, pedido, canal, falhas, timer }
+    this.handshakes = new Map();    // "<aparelho>|<sid>" → { estado, aparelhoId, criadoEm }
+    this.sessoes = new Map();       // sid → { sessao, sid, aparelhoId, fila, envio, acomp: Map }
+    this.inicio = Date.now();
+    this._cadeiaLista = Promise.resolve();
+    this._filasRota = new Map();    // aparelho → promessa: quadros de um aparelho em ordem
+    this._republicacoes = 0;
+    this._timerSondagem = null;
+    this._sondando = false;
+    // Folga para os limites do relay (30 quadros/s, 256 KiB/s por conexão): as telas usam no
+    // máximo isto, e o resto (respostas) passa sempre.
+    this._taxaTela = new P.LimitadorTaxa({ taxa: 160 * 1024, rajada: 320 * 1024 });
+    this._quadrosTela = new P.LimitadorTaxa({ taxa: 15, rajada: 20 });
+    // Balde global para sessao.ola: cada olá custa ECDH + assinatura antes de o aparelho
+    // provar a posse da chave (a confirmação vem depois).
+    this._baldeOla = new P.LimitadorTaxa({ taxa: o.olaPorSegundo || 10, rajada: o.olaRajada || 20 });
+    this._olaDescartados = 0;
+    this._olaUltimoAviso = 0;
+    this._avisosPendentes = new Map();   // aparelho → [{ nome, impressao }] (hub.aparelhoNovo)
+    this.conexao = new ConexaoRelay({
+      relay: this.relay, urlWs: r.urlWs, identidade: this.ident, log: this.log,
+      recuoMinMs: o.recuoMinMs, recuoMaxMs: o.recuoMaxMs, pingMs: o.pingMs, silencioMs: o.silencioMs, authMs: o.authMs,
+      WebSocket: o.WebSocket,
+    });
+    this.conexao.on('conectado', () => this._aoConectar());
+    this.conexao.on('desconectado', () => this._aoDesconectar());
+    this.conexao.on('quadro', q => this._aoQuadro(q));
+  }
+
+  get id() { return this.ident.id; }
+  get impressao() { return this.ident.impressao; }
+
+  iniciar() { this.conexao.iniciar(); return this; }
+
+  parar() {
+    this.conexao.parar();
+    for (const s of Array.from(this.sessoes.values())) this._encerrarSessao(s, 'E_SESSAO_DERRUBADA', true);
+    this.handshakes.clear();
+    for (const c of Array.from(this.convites.values())) this._fecharConvite(c, 'cancelado');
+    if (this._timerSondagem) { clearTimeout(this._timerSondagem); this._timerSondagem = null; }
+  }
+
+  /** Parado = o consumidor CONFIRMOU uma parada (não basta o pedido). */
+  parado() { return this.parada.parado(); }
+
+  get pararDisponivel() { return this.parada.disponivel(); }
+
+  status() {
+    return {
+      id: this.id,
+      impressao: this.impressao,
+      nome: this.nome,
+      versao: this.versao,
+      relay: this.relay,
+      relayEstado: this.conexao.estado,
+      aparelhos: this.aparelhos.tamanho,
+      sessoes: this.sessoes.size,
+      convites: this.convites.size,
+      parado: this.parado(),
+      pararDisponivel: this.pararDisponivel,
+      tempoNoArSeg: Math.floor((Date.now() - this.inicio) / 1000),
+      versaoLista: this.aparelhos.versaoLista,
+      provedorTerminais: this.provedor.nome || 'desconhecido',
+    };
+  }
+
+  listarAparelhos() {
+    return this.aparelhos.lista().map(a => ({
+      id: a.id, nome: a.nome, impressao: a.impressao, pareadoEm: a.pareadoEm,
+      sessoes: Array.from(this.sessoes.values()).filter(s => s.aparelhoId === a.id).length,
+    }));
+  }
+
+  // ─── Relay ──────────────────────────────────────────────────────────────────────────────
+
+  _aoConectar() {
+    this._republicacoes = 0;
+    this.log('conectado ao relay ' + this.relay);
+    this.publicarLista();
+    // Convites ainda sem pedido: o relay pode ter perdido o pid na queda.
+    for (const c of this.convites.values()) {
+      if (!c.pedido) this.conexao.enviar({ t: 'relay.parear.abrir', pid: c.pid, exp: c.exp });
+    }
+  }
+
+  _aoDesconectar() {
+    this.log('desconectado do relay');
+    // Reconexão = nova sessão (PROTOCOLO §4.3): nada de retomada.
+    for (const s of Array.from(this.sessoes.values())) this._encerrarSessao(s, 'E_SESSAO_DERRUBADA');
+    this.handshakes.clear();
+  }
+
+  /**
+   * Publica a lista assinada. A versão é persistida antes de enviar e nunca diminui; usa
+   * max(anterior + 1, relógio) para continuar crescente mesmo se o estado vier de um backup.
+   */
+  publicarLista() {
+    const p = this._cadeiaLista.then(async () => {
+      if (!this.conexao.conectado) return false;
+      const versao = Math.max(this.aparelhos.versaoLista + 1, this.agora());
+      this.aparelhos.versaoLista = versao;
+      this.aparelhos.salvar();
+      const q = await P.noAssinarListaAparelhos(this.ident, {
+        versao, aparelhos: this.aparelhos.lista().map(a => ({ id: a.id, spki: a.spki })), agora: this.agora(),
+      });
+      return this.conexao.enviar(q);
+    });
+    this._cadeiaLista = p.catch(e => { this.log('falha ao publicar a lista (' + (e.codigo || e.message) + ')'); });
+    return p.catch(() => false);
+  }
+
+  _aoQuadro(q) {
+    switch (q.t) {
+      case 'rota': return this._porAparelho(q.de, () => this._aoRota(q.de, q.dados));
+      case 'parear.chegou': {
+        if (typeof q.canal !== 'string') return;
+        // Pedidos do mesmo convite em ordem: o segundo só é tratado depois do primeiro.
+        const conv = this.convites.get(q.pid);
+        if (!conv) return;
+        conv.fila = conv.fila.then(() => this._aoPedido(q.pid, q.canal, q.dados)).catch(() => {});
+        return conv.fila;
+      }
+      case 'relay.erro':
+        this.log('relay.erro ' + q.codigo);
+        if (q.codigo === 'E_LISTA_VERSAO' && this._republicacoes++ < 3) this.publicarLista();
+        return;
+      default: return;
+    }
+  }
+
+  /** Processa os quadros de um mesmo aparelho na ordem de chegada (olá → confirma → dados). */
+  _porAparelho(de, fn) {
+    const anterior = this._filasRota.get(de) || Promise.resolve();
+    const p = anterior.then(fn).catch(() => {});
+    this._filasRota.set(de, p);
+    p.then(() => { if (this._filasRota.get(de) === p) this._filasRota.delete(de); });
+    return p;
+  }
+
+  _enviarRota(para, quadro) {
+    return this.conexao.enviar({ t: 'rota', para, dados: JSON.stringify(quadro) });
+  }
+
+  // ─── Pareamento (§3) ────────────────────────────────────────────────────────────────────
+
+  /**
+   * Abre um convite. `ouvinte(evento)` recebe:
+   *   { evento:'pedido', pid, aparelho:{ id, nome, impressao } }
+   *   { evento:'fim', pid, estado:'aceito'|'recusado'|'expirado'|'cancelado'|'invalido'|..., codigo? }
+   * Devolve { url, pid, exp, conectado }. A URL contém o segredo: só para a tela do QR.
+   */
+  async abrirConvite(ouvinte) {
+    if (this.aparelhos.tamanho >= this.aparelhosMax) throw erro('E_LIMITE');
+    const c = await this.registro.criarConvite({
+      relay: this.relay, pwa: this.pwa, permitirLocal: this.permitirLocal, validadeMs: this.conviteValidadeMs, agora: this.agora(),
+    });
+    const conv = {
+      pid: c.pid, exp: c.exp, ouvinte: ouvinte || (() => {}), pedido: null, canal: null, falhas: 0, timer: null,
+      fila: Promise.resolve(), errosConfirmacao: 0,
+    };
+    conv.timer = setTimeout(() => this._venceuConvite(conv), Math.max(0, c.exp - this.agora()) + 20);
+    this.convites.set(c.pid, conv);
+    this.conexao.enviar({ t: 'relay.parear.abrir', pid: c.pid, exp: c.exp });
+    this.auditar({ tipo: 'convite', resultado: 'aberto' });
+    return { url: c.url, pid: c.pid, exp: c.exp, conectado: this.conexao.conectado };
+  }
+
+  /**
+   * Vencimento do convite. A decisão no PC também termina aqui, com ou sem pedido aguardando
+   * (§3.6): o pedido chega no máximo em `exp` e a conexão anônima do celular vive 6 min a
+   * partir dele no relay, então a resposta sempre ainda encontra o celular.
+   */
+  _venceuConvite(conv) {
+    if (this.convites.get(conv.pid) !== conv) return;
+    this._fecharConvite(conv, 'expirado');
+  }
+
+  _fecharConvite(conv, estadoFinal, codigo) {
+    if (this.convites.get(conv.pid) !== conv) return;
+    this.convites.delete(conv.pid);
+    clearTimeout(conv.timer);
+    this.registro.cancelar(conv.pid);
+    this.conexao.enviar({ t: 'relay.parear.fechar', pid: conv.pid });
+    this.auditar({ tipo: 'pareamento', aparelho: conv.pedido ? conv.pedido.id : undefined, resultado: codigo || estadoFinal });
+    const ev = { evento: 'fim', pid: conv.pid, estado: estadoFinal };
+    if (codigo) ev.codigo = codigo;
+    try { conv.ouvinte(ev); } catch (_) {}
+  }
+
+  /** O dono do convite desistiu (fechou o `ts hub parear`): recusa o que estiver pendente. */
+  async cancelarConvite(pid) {
+    const conv = this.convites.get(pid);
+    if (!conv) return;
+    if (conv.pedido) { try { await this.decidir(pid, false); return; } catch (_) {} }
+    this._fecharConvite(conv, 'cancelado');
+  }
+
+  async _aoPedido(pid, canal, dados) {
+    const conv = this.convites.get(pid);
+    if (!conv) return;                    // pid não é nosso (ou já encerrado)
+    let quadro;
+    try { quadro = P.lerQuadroFimAFim(dados); } catch (_) { return; }
+    if (conv.pedido) return this._outroPedido(conv, canal, quadro);
+    let r;
+    // `pendentes` conta convites vigentes e não usados: se cair durante a chamada, o pedido
+    // decifrou e consumiu o convite (§3.4 passo 4), mesmo que depois tenha falhado.
+    const antes = this.registro.pendentes(this.agora());
+    try {
+      r = await this.registro.abrirPedido(quadro, { agora: this.agora() });
+    } catch (e) {
+      const codigo = (e && e.codigo) || 'E_INTERNO';
+      if (codigo === 'E_CONVITE_USADO') return this._outroPedido(conv, canal, quadro);
+      if (codigo === 'E_DECIFRAR') {
+        if (++conv.falhas >= P.LIMITES.PAREAR_FALHAS_MAX) this._fecharConvite(conv, 'invalido', codigo);
+        return;
+      }
+      if (codigo === 'E_CONVITE_EXPIRADO' || codigo === 'E_CONVITE_DESCONHECIDO') return this._fecharConvite(conv, 'expirado');
+      const consumido = this.registro.pendentes(this.agora()) < antes;
+      if (!consumido) return;   // quadro malformado antes de decifrar: o convite segue valendo
+      // Depois de decifrar, qualquer defeito encerra o convite (já consumido).
+      return this._fecharConvite(conv, 'invalido', codigo);
+    }
+    if (this.convites.get(pid) !== conv) return;
+    conv.pedido = r.aparelho;
+    conv.canal = canal;
+    try {
+      const resp = await this.registro.responder(pid, 'pendente', { agora: this.agora() });
+      this.conexao.enviar({ t: 'parear.responder', canal, dados: JSON.stringify(resp) });
+    } catch (_) {}
+    try {
+      conv.ouvinte({ evento: 'pedido', pid, aparelho: { id: r.aparelho.id, nome: r.aparelho.nome, impressao: r.aparelho.impressao } });
+    } catch (_) {}
+  }
+
+  /**
+   * Segundo pedido para um convite já em análise (quem fotografou o QR chegou antes, ou
+   * depois): o aparelho que mandou ESTE pedido recebe "usado" assinado (a PWA mostra "Outro
+   * aparelho usou este convite — recuse no PC") e o PC é avisado. A decisão do primeiro segue.
+   */
+  async _outroPedido(conv, canal, quadro) {
+    if (this.convites.get(conv.pid) !== conv || !conv.pedido || canal === conv.canal) return;
+    let r;
+    try { r = await this.registro.responderUsado(quadro, { agora: this.agora() }); } catch (_) { return; }
+    this.conexao.enviar({ t: 'parear.responder', canal, dados: JSON.stringify(r.quadro) });
+    this.auditar({ tipo: 'pareamento', aparelho: r.aparelho.id, resultado: 'E_CONVITE_USADO' });
+    try { conv.ouvinte({ evento: 'outroAparelho', pid: conv.pid }); } catch (_) {}
+  }
+
+  /**
+   * Decisão humana no PC. Aceitar exige `confirmacao` = os 8 primeiros caracteres da
+   * impressão digital MOSTRADA NO CELULAR, digitados no PC (sem hífen, sem diferenciar
+   * maiúsculas). Código errado = E_CONFIRMACAO (o pedido segue aberto); no terceiro erro, o
+   * pareamento é recusado. Só então o aparelho é gravado e entra na lista. Devolve o estado final.
+   */
+  async decidir(pid, aceitar, confirmacao) {
+    const conv = this.convites.get(pid);
+    if (!conv || !conv.pedido) throw erro('E_PAREAMENTO_ESTADO');
+    const ap = conv.pedido;
+    let estadoFinal = aceitar === true ? 'aceito' : 'recusado';
+    if (estadoFinal === 'aceito' && !confereImpressao(confirmacao, ap.impressao)) {
+      this.auditar({ tipo: 'pareamento', aparelho: ap.id, resultado: 'E_CONFIRMACAO' });
+      if (++conv.errosConfirmacao < CONFIRMACAO_TENTATIVAS) throw erro('E_CONFIRMACAO');
+      estadoFinal = 'recusado';
+    }
+    if (estadoFinal === 'aceito' && !this.aparelhos.tem(ap.id) && this.aparelhos.tamanho >= this.aparelhosMax) {
+      estadoFinal = 'recusado';
+      this.auditar({ tipo: 'pareamento', aparelho: ap.id, resultado: 'E_LIMITE' });
+    }
+    let resp;
+    try {
+      resp = await this.registro.responder(pid, estadoFinal, { agora: this.agora() });
+    } catch (e) {
+      this._fecharConvite(conv, 'expirado', e.codigo);
+      return 'expirado';
+    }
+    if (estadoFinal === 'aceito') {
+      this.aparelhos.adicionar({ id: ap.id, spki: ap.spki, nome: ap.nome, impressao: ap.impressao, pareadoEm: new Date(this.agora()).toISOString() });
+      this.aparelhos.salvar();
+      // A lista vai antes da resposta, na mesma conexão: quando o celular souber que foi
+      // aceito, o relay já o conhece.
+      await this.publicarLista();
+    }
+    this.conexao.enviar({ t: 'parear.responder', canal: conv.canal, dados: JSON.stringify(resp) });
+    this._fecharConvite(conv, estadoFinal);
+    if (estadoFinal === 'aceito') this._avisarAparelhoNovo(ap);
+    return estadoFinal;
+  }
+
+  /**
+   * Cada pareamento aceito vira o evento hub.aparelhoNovo { nome, impressao } para os outros
+   * aparelhos: na hora, para quem tem sessão; na próxima sessão, para quem não tem (em
+   * memória, até AVISOS_POR_APARELHO; um reinício do hub perde o aviso, a auditoria fica).
+   */
+  _avisarAparelhoNovo(ap) {
+    const dados = { nome: ap.nome, impressao: ap.impressao };
+    const comSessao = new Set();
+    for (const s of this.sessoes.values()) {
+      if (s.aparelhoId === ap.id) continue;
+      comSessao.add(s.aparelhoId);
+      this._evento(s, 'hub.aparelhoNovo', dados);
+    }
+    for (const a of this.aparelhos.lista()) {
+      if (a.id === ap.id || comSessao.has(a.id)) continue;
+      const fila = this._avisosPendentes.get(a.id) || [];
+      fila.push(dados);
+      while (fila.length > AVISOS_POR_APARELHO) fila.shift();
+      this._avisosPendentes.set(a.id, fila);
+    }
+  }
+
+  // ─── Revogação ──────────────────────────────────────────────────────────────────────────
+
+  /** Tira o aparelho da lista, publica a nova versão e derruba as sessões dele na hora. */
+  async revogar(id) {
+    if (!this.aparelhos.tem(id)) return false;
+    this.aparelhos.remover(id);
+    // Primeiro o registro fora do aparelhos.json: um backup antigo não reautoriza o aparelho.
+    try { this.aparelhos.registrarRevogacao(id, this.agora()); } catch (_) { this.log('não consegui gravar revogados.jsonl'); }
+    this.aparelhos.salvar();
+    this._avisosPendentes.delete(id);
+    for (const s of Array.from(this.sessoes.values())) {
+      if (s.aparelhoId === id) this._encerrarSessao(s, 'E_APARELHO_NAO_AUTORIZADO');
+    }
+    for (const [k, h] of Array.from(this.handshakes)) if (h.aparelhoId === id) this.handshakes.delete(k);
+    this.auditar({ tipo: 'revogacao', aparelho: id, resultado: 'ok' });
+    await this.publicarLista();
+    return true;
+  }
+
+  // ─── Sessões (§4–5) ─────────────────────────────────────────────────────────────────────
+
+  async _aoRota(de, dados) {
+    let q;
+    try { q = P.lerQuadroFimAFim(dados); } catch (_) { return; }
+    if (typeof q.sid !== 'string') return;
+    if (q.t === 'sessao.ola') return this._ola(de, q);
+    if (q.t === 'sessao.confirma') return this._confirma(de, q);
+    if (q.t === 'dados') return this._dados(de, q);
+  }
+
+  _buscarAparelho() { return id => this.aparelhos.spki(id); }
+
+  async _ola(de, q) {
+    if (!this.aparelhos.tem(de) || this.sessoes.has(q.sid)) return;
+    const agora = this.agora();
+    for (const [k, h] of Array.from(this.handshakes)) if (agora - h.criadoEm > P.LIMITES.HANDSHAKE_MS) this.handshakes.delete(k);
+    const doAparelho = Array.from(this.handshakes).filter(([, h]) => h.aparelhoId === de);
+    while (doAparelho.length >= HANDSHAKES_POR_APARELHO) this.handshakes.delete(doAparelho.shift()[0]);
+    if (!this._baldeOla.permitir(1)) {
+      // Muitos olás no total: descarta sem gastar cripto. Log agregado, no máximo 1 por minuto.
+      this._olaDescartados++;
+      if (Date.now() - this._olaUltimoAviso > 60000) {
+        this._olaUltimoAviso = Date.now();
+        this.log('sessao.ola descartados por taxa: ' + this._olaDescartados);
+        this.auditar({ tipo: 'sessao', resultado: 'E_TAXA' });
+        this._olaDescartados = 0;
+      }
+      return;
+    }
+    let r;
+    try {
+      r = await P.noResponderSessao({ identidade: this.ident, quadro: q, origem: de, buscarAparelho: this._buscarAparelho(), agora });
+    } catch (e) {
+      this.auditar({ tipo: 'sessao', aparelho: de, resultado: (e && e.codigo) || 'E_INTERNO' });
+      return;
+    }
+    this.handshakes.set(de + '|' + q.sid, { estado: r.estado, aparelhoId: de, criadoEm: agora });
+    this._enviarRota(de, r.quadro);
+  }
+
+  async _confirma(de, q) {
+    const k = de + '|' + q.sid;
+    const h = this.handshakes.get(k);
+    if (!h) return;
+    this.handshakes.delete(k);
+    let sessao;
+    try {
+      sessao = await P.noConcluirSessao(h.estado, q, { buscarAparelho: this._buscarAparelho(), agora: this.agora() });
+    } catch (e) {
+      this.auditar({ tipo: 'sessao', aparelho: de, resultado: (e && e.codigo) || 'E_INTERNO' });
+      return;
+    }
+    if (!this.aparelhos.tem(de) || !this.conexao.conectado) { sessao.derrubar(); return; }
+    // O relay mantém uma conexão por aparelho (a nova derruba a anterior) e não avisa o nó
+    // quando o aparelho cai: a sessão nova substitui as anteriores do mesmo aparelho, que
+    // ficaram sem dono. Sem isso elas seguiam recebendo eventos (telas) até o limite.
+    for (const s of Array.from(this.sessoes.values())) {
+      if (s.aparelhoId === de) this._encerrarSessao(s, 'substituida');
+    }
+    const nova = {
+      sessao, sid: sessao.sid, aparelhoId: de, fila: Promise.resolve(), envio: Promise.resolve(), acomp: new Map(),
+    };
+    this.sessoes.set(sessao.sid, nova);
+    this.auditar({ tipo: 'sessao', aparelho: de, resultado: 'aberta' });
+    const avisos = this._avisosPendentes.get(de);
+    if (avisos) {
+      this._avisosPendentes.delete(de);
+      for (const a of avisos) this._evento(nova, 'hub.aparelhoNovo', a);
+    }
+  }
+
+  _dados(de, q) {
+    const s = this.sessoes.get(q.sid);
+    // Outro aparelho usando o sid de alguém: ignora sem derrubar a sessão alheia.
+    if (!s || s.aparelhoId !== de) return;
+    s.fila = s.fila.then(() => this._comando(s, q)).catch(() => {});
+  }
+
+  _encerrarSessao(s, motivo, silencioso) {
+    if (this.sessoes.get(s.sid) !== s) return;
+    this.sessoes.delete(s.sid);
+    s.acomp.clear();
+    s.sessao.derrubar();
+    if (!silencioso) this.auditar({ tipo: 'sessao', aparelho: s.aparelhoId, resultado: motivo || 'encerrada' });
+  }
+
+  /** Enfileira um quadro cifrado para envio na ordem em que foi produzido (§5). */
+  _enviarSessao(s, promessaQuadro) {
+    promessaQuadro.catch(() => {});
+    s.envio = s.envio
+      .then(() => promessaQuadro)
+      .then(quadro => { if (this.sessoes.get(s.sid) === s) this._enviarRota(s.aparelhoId, quadro); })
+      .catch(e => { if (s.sessao.derrubada) this._encerrarSessao(s, (e && e.codigo) || 'E_SESSAO_DERRUBADA'); });
+    return s.envio;
+  }
+
+  _evento(s, tipo, dados) {
+    return this._enviarSessao(s, P.noEnviarEvento(s.sessao, tipo, dados, { agora: this.agora() }));
+  }
+
+  // ─── Comandos (§6) ──────────────────────────────────────────────────────────────────────
+
+  async _comando(s, q) {
+    if (this.sessoes.get(s.sid) !== s) return;
+    let cmd;
+    try {
+      cmd = await P.noAbrirComando(s.sessao, q, { aparelhoAutorizado: id => this.aparelhos.tem(id), agora: this.agora() });
+    } catch (e) {
+      const codigo = (e && e.codigo) || 'E_INTERNO';
+      this.auditar({ tipo: 'comando', metodo: null, aparelho: s.aparelhoId, resultado: codigo });
+      if (s.sessao.derrubada) return this._encerrarSessao(s, codigo);
+      if (Number.isSafeInteger(e && e.seq)) this._enviarSessao(s, P.noResponder(s.sessao, e.seq, { erro: codigo }, { agora: this.agora() }));
+      return;
+    }
+    let r;
+    try {
+      r = { resultado: await this._executar(s, cmd.metodo, cmd.params) };
+    } catch (e) {
+      r = { erro: e && RX_CODIGO.test(String(e.codigo)) ? e.codigo : 'E_INTERNO' };
+    }
+    if (this.sessoes.get(s.sid) !== s) return;    // revogado ou derrubado durante a execução
+    this._enviarSessao(s, P.noResponder(s.sessao, cmd.seq, r, { agora: this.agora() }));
+    this.auditar({ tipo: 'comando', metodo: cmd.metodo, aparelho: s.aparelhoId, resultado: r.erro || 'ok' });
+    if (r.erro) return;
+    if (cmd.metodo === 'terminal.watch') {
+      const w = s.acomp.get(cmd.params.terminalId);
+      if (w) w.pronto = true;
+      this._agendarSondagem();
+    } else if (cmd.metodo === 'hub.stopAll') {
+      for (const outra of this.sessoes.values()) this._evento(outra, 'hub.estado', { parado: true });
+    }
+  }
+
+  async _listarTerminais() {
+    let lista;
+    try { lista = await this.provedor.listar(); } catch (_) { lista = []; }
+    return Array.isArray(lista) ? lista.slice(0, TERMINAIS_MAX) : [];
+  }
+
+  async _executar(s, metodo, params) {
+    switch (metodo) {
+      case 'hub.status': {
+        const terminais = await this._listarTerminais();
+        return {
+          nome: this.nome, versao: this.versao, so: process.platform,
+          tempoNoArSeg: Math.floor((Date.now() - this.inicio) / 1000),
+          parado: this.parado(), pararDisponivel: this.pararDisponivel, terminais: terminais.length,
+        };
+      }
+      case 'terminals.list': {
+        const terminais = await this._listarTerminais();
+        return { terminais: terminais.map(t => ({ terminalId: t.terminalId, titulo: t.titulo, ativo: !!t.ativo })) };
+      }
+      case 'terminal.watch': {
+        const id = params.terminalId;
+        const historico = params.historico === undefined ? 0 : params.historico;
+        const t = (await this._listarTerminais()).find(x => x.terminalId === id);
+        if (!t) throw erro('E_TERMINAL_INEXISTENTE');
+        if (!s.acomp.has(id) && s.acomp.size >= ACOMPANHAMENTOS_POR_SESSAO) throw erro('E_LIMITE');
+        const tela = this._prepararTela(id, t.colunas, t.linhas, await this.provedor.capturar(id, historico));
+        s.acomp.set(id, { historico, ultimaTela: tela, colunas: t.colunas, linhas: t.linhas, ultimoEnvio: Date.now(), pronto: false });
+        return { terminalId: id, colunas: t.colunas, linhas: t.linhas, tela };
+      }
+      case 'terminal.unwatch':
+        s.acomp.delete(params.terminalId);
+        return null;
+      case 'hub.stopAll':
+        await this.pararTudo();
+        return { parado: true };
+      default:
+        throw erro('E_METODO');
+    }
+  }
+
+  /**
+   * Parar tudo: grava o pedido em TS_HUB_PARAR_DIR/pedidos e espera a confirmação do
+   * consumidor externo (na VPS, unidade de root: cli/hub/vps/). Só com ela resolve; sem ela,
+   * E_PARAR_SEM_CONFIRMACAO (prazo de 10 s). Nó sem consumidor: E_PARAR_INDISPONIVEL. Os
+   * acompanhamentos de terminal param já no pedido. O evento hub.estado sai depois da resposta.
+   */
+  async pararTudo() {
+    if (!this.pararDisponivel) {
+      this.auditar({ tipo: 'parar-tudo', resultado: 'E_PARAR_INDISPONIVEL' });
+      throw erro('E_PARAR_INDISPONIVEL');
+    }
+    for (const s of this.sessoes.values()) s.acomp.clear();
+    this.auditar({ tipo: 'parar-tudo', resultado: 'pedido' });
+    try {
+      await this.parada.pedir();
+    } catch (e) {
+      const codigo = e && /^E_[A-Z_]{1,40}$/.test(String(e.codigo)) ? e.codigo : 'E_PARAR_SEM_CONFIRMACAO';
+      this.auditar({ tipo: 'parar-tudo', resultado: codigo });
+      this.log('parar tudo sem confirmação (' + codigo + ')');
+      throw erro(codigo);
+    }
+    this.auditar({ tipo: 'parar-tudo', resultado: 'confirmado' });
+  }
+
+  // ─── Telas ──────────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Tela sanitizada (só SGR) que cabe inteira no texto claro de um quadro (32 KiB, já com o
+   * JSON e os escapes ). Se não couber, corta o histórico mais antigo (linhas do topo).
+   */
+  _prepararTela(terminalId, colunas, linhas, bruta) {
+    // A máscara já foi aplicada pelo exportar-telas; aqui de novo, por garantia.
+    const tela = mascararSegredos(sanitizarTela(bruta));
+    const cabe = t => Buffer.byteLength(t, 'utf8') <= TELA_MAX_BYTES &&
+      Buffer.byteLength(JSON.stringify({ k: 'resp', seq: Number.MAX_SAFE_INTEGER, ok: true,
+        resultado: { terminalId, colunas, linhas, tela: t } }), 'utf8') <= P.LIMITES.TEXTO_CLARO_MAX - 64;
+    return cortarTela(tela, cabe);
+  }
+
+  _temAcompanhamentos() {
+    for (const s of this.sessoes.values()) if (s.acomp.size) return true;
+    return false;
+  }
+
+  _agendarSondagem() {
+    if (this._timerSondagem || this._sondando || !this._temAcompanhamentos()) return;
+    this._timerSondagem = setTimeout(() => { this._timerSondagem = null; this._sondar(); }, this.sondagemMs);
+  }
+
+  async _sondar() {
+    this._sondando = true;
+    try {
+      const alvos = [];
+      for (const s of this.sessoes.values()) for (const [id, w] of s.acomp) if (w.pronto) alvos.push({ s, id, w });
+      if (!alvos.length) return;
+      const lista = await this._listarTerminais();
+      const porId = new Map(lista.map(t => [t.terminalId, t]));
+      const capturas = new Map();
+      for (const { s, id, w } of alvos) {
+        if (this.sessoes.get(s.sid) !== s || s.acomp.get(id) !== w) continue;
+        const t = porId.get(id);
+        if (!t) {
+          s.acomp.delete(id);
+          this._evento(s, 'terminal.fim', { terminalId: id });
+          continue;
+        }
+        const agora = Date.now();
+        if (agora - w.ultimoEnvio < this.intervaloTelaMs) continue;
+        const chave = id + '|' + w.historico;
+        let tela = capturas.get(chave);
+        if (tela === undefined) {
+          try { tela = this._prepararTela(id, t.colunas, t.linhas, await this.provedor.capturar(id, w.historico)); } catch (_) { tela = null; }
+          capturas.set(chave, tela);
+        }
+        if (tela === null || s.acomp.get(id) !== w) continue;
+        if (tela === w.ultimaTela && t.colunas === w.colunas && t.linhas === w.linhas) continue;
+        const bytes = Buffer.byteLength(tela, 'utf8') + 256;
+        if (!this._quadrosTela.permitir(1) ) continue;
+        if (!this._taxaTela.permitir(bytes)) continue;
+        w.ultimaTela = tela; w.colunas = t.colunas; w.linhas = t.linhas; w.ultimoEnvio = agora;
+        this._evento(s, 'terminal.tela', { terminalId: id, colunas: t.colunas, linhas: t.linhas, tela });
+      }
+    } catch (_) {
+      /* sondagem nunca derruba o hub */
+    } finally {
+      this._sondando = false;
+      this._agendarSondagem();
+    }
+  }
+}
+
+module.exports = { Hub, RELAY_PADRAO, PWA_PADRAO, confereImpressao };