terminal-smart-cli 0.98.0 → 0.99.0

package/hub/cli.js

@@ -0,0 +1,255 @@
+'use strict';
+// Subcomandos `ts hub ...` (roteados por bin/ts.js).
+//
+//   ts hub iniciar          processo de longa duração (systemd na VPS, usuário tshub)
+//   ts hub parear           QR de uso único (5 min); confirmação DIGITANDO no PC os 8 primeiros
+//                           caracteres da impressão digital mostrada no celular
+//   ts hub aparelhos        lista os aparelhos autorizados
+//   ts hub revogar <id>     tira o aparelho da lista e derruba a sessão dele na hora
+//   ts hub status           estado do daemon
+//   ts hub exportar-telas   (usuário dos agentes, não o hub) grava as telas do tmux para o hub
+//
+// Variáveis: TS_HUB_DIR (padrão ~/.ts/hub), TS_HUB_RELAY (padrão
+// https://relay.terminalsmart.com.br), TS_HUB_PWA_URL (origem da PWA no QR; padrão = celular.terminalsmart.com.br com o relay oficial),
+// TS_HUB_PARAR_DIR (diretório do Parar tudo; sem ele, indisponível), TS_HUB_TELAS_DIR
+// (instantâneos de tela), TS_HUB_NOME.
+
+const readline = require('readline');
+const estado = require('./estado');
+const { conectarControle } = require('./controle');
+
+const AJUDA = [
+  'Uso: ts hub <subcomando>',
+  '',
+  '  iniciar                 inicia o hub (conexão de saída com o relay; deixe rodando)',
+  '  parear [--mostrar-url]  mostra o QR para parear um celular (confirmação digitando aqui no PC)',
+  '  aparelhos               lista os aparelhos autorizados',
+  '  revogar <id>            revoga um aparelho (corta a sessão na hora)',
+  '  status                  estado do hub',
+  '  exportar-telas [--uma-vez]  (como o usuário dos agentes) grava as telas do tmux para o hub ler',
+  '',
+  'Variáveis: TS_HUB_DIR, TS_HUB_RELAY, TS_HUB_PWA_URL, TS_HUB_PARAR_DIR, TS_HUB_TELAS_DIR, TS_HUB_NOME',
+  '           exportar-telas: TS_HUB_TELAS_DIR, TS_HUB_TELAS_PERMITIDAS, TS_HUB_TELAS_HISTORICO',
+].join('\n');
+
+const MENSAGENS_ERRO = {
+  E_LIMITE: 'limite atingido (aparelhos ou convites abertos)',
+  E_PAREAMENTO_ESTADO: 'pareamento fora de ordem ou encerrado',
+  E_CONTROLE_NEGADO: 'o hub recusou o controle',
+  E_CONFIRMACAO: 'o código não confere com a impressão digital do celular',
+};
+
+function falhar(msg, codigo) {
+  console.error('  ✗ ' + msg);
+  process.exitCode = codigo || 1;
+}
+
+function hora(ms) {
+  return new Date(ms).toLocaleTimeString('pt-BR', { hour: '2-digit', minute: '2-digit', second: '2-digit' });
+}
+
+function logDaemon(msg) {
+  // Só ID, tipo, estado e código: nunca segredo, URL de convite ou conteúdo de tela.
+  console.log(new Date().toISOString() + ' ts-hub: ' + msg);
+}
+
+async function iniciar() {
+  const { Hub } = require('./hub');
+  const { abrirControle } = require('./controle');
+  const dir = estado.dirPadrao();
+  let hub, controle;
+  try {
+    hub = await Hub.criar({ dir, log: logDaemon });
+    controle = await abrirControle(hub);
+  } catch (e) {
+    if (hub) hub.parar();
+    return falhar(e.message);
+  }
+  if (hub.chaveCriada) logDaemon('chave do nó gerada');
+  logDaemon('nó ' + hub.id + ' (impressão ' + hub.impressao + ') · relay ' + hub.relay + ' · estado ' + dir);
+  logDaemon('terminais: ' + (hub.provedor.nome || '?') + ' · parar tudo: ' + (hub.pararDisponivel ? 'disponível' : 'indisponível neste nó'));
+  hub.iniciar();
+  await new Promise(resolve => {
+    let saindo = false;
+    const sair = async sinal => {
+      if (saindo) return;
+      saindo = true;
+      logDaemon('encerrando (' + sinal + ')');
+      hub.parar();
+      await controle.fechar();
+      resolve();
+    };
+    process.on('SIGINT', () => sair('SIGINT'));
+    process.on('SIGTERM', () => sair('SIGTERM'));
+  });
+  process.exit(0);
+}
+
+async function comControle(fn) {
+  let c;
+  try { c = await conectarControle(estado.dirPadrao()); } catch (e) { return falhar(e.message, 2); }
+  try { return await fn(c); } catch (e) {
+    return falhar(MENSAGENS_ERRO[e.codigo] || e.message);
+  } finally { c.fechar(); }
+}
+
+function exigirOk(r) {
+  if (!r.ok) throw Object.assign(new Error(MENSAGENS_ERRO[r.erro] || ('o hub recusou (' + r.erro + ')')), { codigo: r.erro });
+  return r;
+}
+
+async function status(json) {
+  return comControle(async c => {
+    const { status: s } = exigirOk(await c.pedir({ op: 'status' }));
+    if (json) return console.log(JSON.stringify(s));
+    console.log('');
+    console.log('  ts hub — ' + s.nome);
+    console.log('  nó         ' + s.id + '   impressão ' + s.impressao);
+    console.log('  relay      ' + s.relay + ' (' + s.relayEstado + ')');
+    console.log('  aparelhos  ' + s.aparelhos + '   sessões ativas ' + s.sessoes);
+    console.log('  terminais  ' + (s.provedorTerminais || '?'));
+    console.log('  parar tudo ' + (s.pararDisponivel ? 'disponível' : 'indisponível neste nó (sem TS_HUB_PARAR_DIR/consumidor)'));
+    console.log('  parado     ' + (s.parado ? 'SIM (confirmado pelo consumidor)' : 'não'));
+    console.log('  no ar há   ' + s.tempoNoArSeg + ' s   versão ' + s.versao);
+    console.log('');
+  });
+}
+
+async function aparelhos(json) {
+  return comControle(async c => {
+    const { aparelhos: lista } = exigirOk(await c.pedir({ op: 'aparelhos' }));
+    if (json) return console.log(JSON.stringify(lista));
+    if (!lista.length) return console.log('  Nenhum aparelho pareado. Use: ts hub parear');
+    console.log('');
+    for (const a of lista) {
+      console.log('  ' + a.id + '  ' + a.impressao + '  ' + a.nome + (a.sessoes ? '  (' + a.sessoes + ' sessão ativa)' : ''));
+      console.log('      pareado em ' + a.pareadoEm);
+    }
+    console.log('');
+  });
+}
+
+async function revogar(id) {
+  if (!id || !/^[A-Za-z0-9_-]{22}$/.test(id)) return falhar('informe o ID do aparelho (veja: ts hub aparelhos)', 2);
+  return comControle(async c => {
+    const r = exigirOk(await c.pedir({ op: 'revogar', id }));
+    if (!r.revogado) return falhar('aparelho não encontrado: ' + id);
+    console.log('  ✔ aparelho revogado; sessões dele derrubadas e nova lista publicada.');
+  });
+}
+
+function perguntar(rl, texto) {
+  return new Promise(resolve => rl.question(texto, r => resolve(r)));
+}
+
+async function parear(mostrarUrl) {
+  return comControle(async c => {
+    exigirOk(await c.pedir({ op: 'parear' }));
+    const conv = await c.receber(m => m.evento === 'convite' || m.evento === 'fim', 15000);
+    if (conv.evento === 'fim') return falhar('convite encerrado: ' + conv.estado);
+    let qr = null;
+    try { qr = require('qrcode-terminal'); } catch (_) {}
+    if (!qr && !mostrarUrl) return falhar('não consegui desenhar o QR (qrcode-terminal ausente). Para ver o endereço: ts hub parear --mostrar-url');
+    console.log('');
+    if (qr) qr.generate(conv.url, { small: true }, q => console.log(q.split('\n').map(l => '  ' + l).join('\n')));
+    console.log('  Leia o QR com a câmera do celular.');
+    // A URL tem o segredo do convite: só na tela, e só a pedido (nada de log ou arquivo).
+    if (mostrarUrl) {
+      console.log('  ATENÇÃO: o endereço abaixo contém o segredo do convite. Quem o tiver nos próximos');
+      console.log('  minutos pode pedir o pareamento. Não cole em chat, e-mail ou documento.');
+      console.log('  ' + conv.url);
+    }
+    console.log('  Válido até ' + hora(conv.exp) + ' (uso único).' + (conv.conectado ? '' : '  Atenção: o hub ainda não está conectado ao relay.'));
+    console.log('');
+    console.log('  Aguardando o celular…');
+
+    const ev = await c.receber(m => m.evento === 'pedido' || m.evento === 'fim');
+    if (ev.evento === 'fim') return falhar(ev.estado === 'expirado' ? 'o convite expirou sem pedido; gere outro.' : 'convite encerrado: ' + ev.estado);
+
+    // Outro aparelho tentando o mesmo convite: avisa enquanto a decisão estiver aberta.
+    let aberto = true;
+    (async () => {
+      while (aberto) {
+        try { await c.receber(m => m.evento === 'outroAparelho'); } catch (_) { return; }
+        if (!aberto) return;
+        console.log('');
+        console.log('  ⚠ OUTRO aparelho tentou usar este convite. Se o seu celular mostrar "Outro aparelho');
+        console.log('    usou este convite", NÃO digite o código: aperte Enter para recusar e gere outro QR.');
+      }
+    })();
+
+    console.log('');
+    console.log('  Pedido de pareamento do aparelho "' + ev.aparelho.nome + '".');
+    console.log('  No CELULAR aparece a impressão digital dele (XXXX-XXXX-XXXX-XXXX).');
+    console.log('  Digite aqui os 8 primeiros caracteres dela (sem hífen) para aceitar, ou só Enter para recusar.');
+    console.log('  Se o celular disser "Outro aparelho usou este convite", recuse.');
+    console.log('  Decida até ' + hora(conv.exp) + ' (depois disso o convite vence e nada é gravado).');
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const fimAntes = c.receber(m => m.evento === 'fim').then(m => { rl.close(); return m; }, () => null);
+    try {
+      for (;;) {
+        const resposta = await Promise.race([perguntar(rl, '  Código (8 caracteres): '), fimAntes.then(() => null)]);
+        if (resposta === null) {
+          const m = await fimAntes;
+          return falhar('o convite terminou antes da confirmação (' + (m ? m.estado : 'conexão caiu') + ').');
+        }
+        const codigo = String(resposta).trim();
+        const pedido = codigo
+          ? { op: 'decidir', pid: conv.pid, aceitar: true, confirmacao: codigo }
+          : { op: 'decidir', pid: conv.pid, aceitar: false };
+        const r = await c.pedir(pedido);
+        if (!r.ok && r.erro === 'E_CONFIRMACAO') {
+          console.log('  ✗ Não confere com a impressão digital do celular. Confira e digite de novo (ou Enter para recusar).');
+          continue;
+        }
+        exigirOk(r);
+        if (r.estado === 'aceito') console.log('  ✔ aparelho pareado: ' + ev.aparelho.nome);
+        else falhar(r.estado === 'recusado' ? 'pareamento recusado; nada foi gravado.' : 'pareamento não concluído (' + r.estado + ').');
+        return;
+      }
+    } finally {
+      aberto = false;
+      rl.close();
+    }
+  });
+}
+
+async function exportarTelas(umaVez) {
+  const X = require('./exportar-telas');
+  let cfg;
+  try { cfg = X.lerConfig(process.env); } catch (e) { return falhar(e.message, 2); }
+  if (umaVez) {
+    try {
+      const r = await X.exportarUmaVez(cfg);
+      console.log('  ✔ ' + r.exportados.length + ' terminal(is) exportado(s) para ' + cfg.dir);
+    } catch (e) { falhar('falha ao exportar (' + (e.codigo || e.code || 'erro') + ')'); }
+    return;
+  }
+  const sinal = { parar: false };
+  process.on('SIGINT', () => { sinal.parar = true; });
+  process.on('SIGTERM', () => { sinal.parar = true; });
+  logDaemon('exportando telas de ' + cfg.permitidas.length + ' entrada(s) permitida(s) para ' + cfg.dir + ' a cada ' + cfg.intervaloMs + ' ms');
+  await X.exportarTelas(Object.assign({ sinal, log: logDaemon }, cfg));
+}
+
+async function main(args) {
+  const todos = args || [];
+  const lista = todos.filter(a => !['--json', '--mostrar-url', '--uma-vez'].includes(a));
+  const json = todos.includes('--json');
+  const sub = String(lista[0] || '').toLowerCase();
+  switch (sub) {
+    case 'iniciar': case 'start': case 'daemon': return iniciar();
+    case 'parear': case 'pair': return parear(todos.includes('--mostrar-url'));
+    case 'aparelhos': case 'devices': return aparelhos(json);
+    case 'revogar': case 'revoke': return revogar(lista[1]);
+    case 'status': return status(json);
+    case 'exportar-telas': return exportarTelas(todos.includes('--uma-vez'));
+    case '': case 'ajuda': case 'help': case '--help': case '-h':
+      console.log(AJUDA); return;
+    default:
+      console.error(AJUDA);
+      process.exitCode = 2;
+  }
+}
+
+module.exports = { main };

package/hub/controle.js

@@ -0,0 +1,262 @@
+'use strict';
+// Controle local do daemon: só o MESMO usuário do SO comanda.
+//
+// - Linux/macOS: socket unix <TS_HUB_DIR>/controle.sock com 0600, dentro do diretório 0700
+//   (o kernel exige permissão de escrita no arquivo do socket para conectar).
+// - Windows: named pipe de nome aleatório (128 bits), anotado em controle.json.
+// - Nos dois: controle.json (0600; no Windows, ACL do perfil do usuário) guarda também uma
+//   FICHA aleatória de 256 bits que o cliente precisa apresentar na primeira mensagem. Quem
+//   não lê o arquivo não comanda, mesmo que alcance o socket/pipe.
+//
+// Protocolo: uma mensagem JSON por linha. Primeira: { op:"ola", ficha }.
+// Pedidos: status | aparelhos | revogar {id} | parear | decidir {pid, aceitar, confirmacao}.
+// `confirmacao` = os 8 primeiros caracteres da impressão digital mostrada no celular,
+// digitados no PC (E_CONFIRMACAO se não conferir; no terceiro erro o pedido é recusado).
+// Respostas: { r:<op>, ok:true, ... } ou { r:<op>, ok:false, erro:"E_..." }; eventos de
+// pareamento: { evento:"convite"|"pedido"|"outroAparelho"|"fim", ... }.
+
+const fs = require('fs');
+const net = require('net');
+const path = require('path');
+const crypto = require('crypto');
+const estado = require('./estado');
+
+const LINHA_MAX = 64 * 1024;
+const CONEXOES_MAX = 8;
+const OLA_MS = 5000;
+
+function arquivoControle(dir) { return path.join(dir, 'controle.json'); }
+
+function iguaisSeguro(a, b) {
+  const x = Buffer.from(String(a)), y = Buffer.from(String(b));
+  return x.length === y.length && crypto.timingSafeEqual(x, y);
+}
+
+function leitorLinhas(sock, aoLinha) {
+  let buf = '';
+  sock.setEncoding('utf8');
+  sock.on('data', parte => {
+    buf += parte;
+    if (buf.length > LINHA_MAX && buf.indexOf('\n') < 0) { sock.destroy(); return; }
+    let i;
+    while ((i = buf.indexOf('\n')) >= 0) {
+      const linha = buf.slice(0, i);
+      buf = buf.slice(i + 1);
+      if (!linha.trim()) continue;
+      let msg;
+      try { msg = JSON.parse(linha); } catch (_) { sock.destroy(); return; }
+      if (!msg || typeof msg !== 'object' || Array.isArray(msg)) { sock.destroy(); return; }
+      aoLinha(msg);
+    }
+  });
+}
+
+function escrever(sock, obj) {
+  if (!sock.destroyed) { try { sock.write(JSON.stringify(obj) + '\n'); } catch (_) {} }
+}
+
+/** Tenta conectar a um endereço; resolve true se alguém atende. */
+function alguemAtende(endereco) {
+  return new Promise(resolve => {
+    const s = net.connect(endereco);
+    const fim = r => { s.destroy(); resolve(r); };
+    s.once('connect', () => fim(true));
+    s.once('error', () => fim(false));
+    setTimeout(() => fim(false), 1500).unref();
+  });
+}
+
+/**
+ * Abre o servidor de controle do hub. Recusa se já há um daemon atendendo neste diretório.
+ * Devolve { endereco, fechar() }.
+ */
+async function abrirControle(hub, opcoes) {
+  const o = opcoes || {};
+  const dir = hub.dir;
+  const arqCtl = arquivoControle(dir);
+  const plataforma = o.plataforma || process.platform;
+
+  // Um daemon por diretório de estado.
+  try {
+    const anterior = estado.lerJson(arqCtl);
+    if (anterior && typeof anterior.endereco === 'string' && await alguemAtende(anterior.endereco)) {
+      throw new Error('já existe um hub rodando com o diretório ' + dir);
+    }
+  } catch (e) {
+    if (/já existe um hub/.test(e.message)) throw e;
+  }
+
+  const ficha = crypto.randomBytes(32).toString('base64url');
+  const endereco = plataforma === 'win32'
+    ? '\\\\.\\pipe\\ts-hub-' + crypto.randomBytes(16).toString('hex')
+    : path.join(dir, 'controle.sock');
+  if (plataforma !== 'win32') {
+    if (await alguemAtende(endereco)) throw new Error('já existe um hub rodando com o diretório ' + dir);
+    try { fs.unlinkSync(endereco); } catch (_) {}
+  }
+
+  const clientes = new Set();
+  const servidor = net.createServer(sock => atender(hub, sock, ficha, clientes));
+  servidor.maxConnections = CONEXOES_MAX;
+
+  await new Promise((resolve, reject) => {
+    servidor.once('error', reject);
+    // O socket nasce já com 0600 (umask), sem janela em que outro usuário o abra.
+    const antiga = plataforma === 'win32' ? null : process.umask(0o177);
+    try {
+      servidor.listen(endereco, () => { servidor.removeListener('error', reject); resolve(); });
+    } finally {
+      if (antiga !== null) process.umask(antiga);
+    }
+  });
+  if (plataforma !== 'win32') fs.chmodSync(endereco, 0o600);
+  estado.gravarPrivado(arqCtl, JSON.stringify({ v: 1, endereco, ficha, pid: process.pid }) + '\n');
+
+  return {
+    endereco,
+    fechar() {
+      return new Promise(resolve => {
+        for (const c of clientes) c.destroy();
+        servidor.close(() => resolve());
+        try {
+          const atual = estado.lerJson(arqCtl);
+          if (atual && atual.endereco === endereco) fs.unlinkSync(arqCtl);
+        } catch (_) {}
+        if (plataforma !== 'win32') { try { fs.unlinkSync(endereco); } catch (_) {} }
+      });
+    },
+  };
+}
+
+function atender(hub, sock, ficha, clientes) {
+  clientes.add(sock);
+  let autenticado = false;
+  const meusConvites = new Set();
+  const limite = setTimeout(() => { if (!autenticado) sock.destroy(); }, OLA_MS);
+  sock.on('error', () => {});
+  sock.on('close', () => {
+    clearTimeout(limite);
+    clientes.delete(sock);
+    // Quem abriu o convite foi embora: recusa o pendente e fecha.
+    for (const pid of meusConvites) hub.cancelarConvite(pid).catch(() => {});
+  });
+
+  let fila = Promise.resolve();
+  leitorLinhas(sock, msg => {
+    fila = fila.then(() => tratar(msg)).catch(() => {});
+  });
+
+  async function tratar(msg) {
+    const op = typeof msg.op === 'string' ? msg.op : '';
+    if (!autenticado) {
+      if (op === 'ola' && iguaisSeguro(msg.ficha, ficha)) {
+        autenticado = true;
+        clearTimeout(limite);
+        escrever(sock, { r: 'ola', ok: true, id: hub.id });
+      } else {
+        hub.auditar({ tipo: 'controle', resultado: 'E_CONTROLE_NEGADO' });
+        escrever(sock, { r: 'ola', ok: false, erro: 'E_CONTROLE_NEGADO' });
+        sock.end();
+        setTimeout(() => sock.destroy(), 200).unref();
+      }
+      return;
+    }
+    try {
+      switch (op) {
+        case 'status': return escrever(sock, { r: op, ok: true, status: hub.status() });
+        case 'aparelhos': return escrever(sock, { r: op, ok: true, aparelhos: hub.listarAparelhos() });
+        case 'revogar': {
+          const revogado = await hub.revogar(String(msg.id || ''));
+          return escrever(sock, { r: op, ok: true, revogado });
+        }
+        case 'parear': {
+          const c = await hub.abrirConvite(ev => {
+            if (ev.evento === 'fim') meusConvites.delete(ev.pid);
+            escrever(sock, ev);
+          });
+          meusConvites.add(c.pid);
+          escrever(sock, { r: op, ok: true });
+          // A URL leva o segredo do convite: vai só para o terminal de quem pediu.
+          return escrever(sock, { evento: 'convite', pid: c.pid, url: c.url, exp: c.exp, conectado: c.conectado });
+        }
+        case 'decidir': {
+          if (!meusConvites.has(msg.pid)) return escrever(sock, { r: op, ok: false, erro: 'E_PAREAMENTO_ESTADO' });
+          // Aceitar exige o código digitado no PC (8 primeiros caracteres da impressão do celular).
+          const estadoFinal = await hub.decidir(msg.pid, msg.aceitar === true, typeof msg.confirmacao === 'string' ? msg.confirmacao.slice(0, 64) : undefined);
+          return escrever(sock, { r: op, ok: true, estado: estadoFinal });
+        }
+        default:
+          return escrever(sock, { r: op, ok: false, erro: 'E_METODO' });
+      }
+    } catch (e) {
+      const codigo = e && /^E_[A-Z_]{1,40}$/.test(String(e.codigo)) ? e.codigo : 'E_INTERNO';
+      return escrever(sock, { r: op, ok: false, erro: codigo });
+    }
+  }
+}
+
+/**
+ * Cliente do controle local. Devolve { enviar(obj), receber(filtro, ms), fechar(), id }.
+ * `ficha` pode ser forçada (testes de recusa).
+ */
+async function conectarControle(dir, opcoes) {
+  const o = opcoes || {};
+  let ctl;
+  try { ctl = estado.lerJson(arquivoControle(dir)); } catch (_) {
+    throw Object.assign(new Error('o hub não está rodando (inicie com: ts hub iniciar)'), { codigo: 'E_SEM_HUB' });
+  }
+  const sock = await new Promise((resolve, reject) => {
+    const s = net.connect(ctl.endereco);
+    s.once('connect', () => resolve(s));
+    s.once('error', () => reject(Object.assign(new Error('o hub não está rodando (inicie com: ts hub iniciar)'), { codigo: 'E_SEM_HUB' })));
+  });
+  const caixa = [];
+  const esperando = [];
+  let fechado = false;
+  const entregar = () => {
+    for (let i = 0; i < esperando.length; i++) {
+      const w = esperando[i];
+      const k = caixa.findIndex(w.filtro);
+      if (k >= 0) {
+        const [m] = caixa.splice(k, 1);
+        esperando.splice(i--, 1);
+        clearTimeout(w.timer);
+        w.resolve(m);
+      }
+    }
+  };
+  leitorLinhas(sock, msg => { caixa.push(msg); entregar(); });
+  sock.on('error', () => {});
+  sock.on('close', () => {
+    fechado = true;
+    for (const w of esperando.splice(0)) { clearTimeout(w.timer); w.reject(Object.assign(new Error('conexão com o hub caiu'), { codigo: 'E_SEM_HUB' })); }
+  });
+
+  const cliente = {
+    enviar(obj) { escrever(sock, obj); },
+    receber(filtro, ms) {
+      const f = typeof filtro === 'function' ? filtro : () => true;
+      return new Promise((resolve, reject) => {
+        const w = { filtro: f, resolve, reject, timer: null };
+        if (ms) w.timer = setTimeout(() => { esperando.splice(esperando.indexOf(w), 1); reject(Object.assign(new Error('tempo esgotado esperando o hub'), { codigo: 'E_TEMPO' })); }, ms);
+        esperando.push(w);
+        entregar();
+        if (fechado && esperando.includes(w)) { esperando.splice(esperando.indexOf(w), 1); clearTimeout(w.timer); reject(Object.assign(new Error('conexão com o hub caiu'), { codigo: 'E_SEM_HUB' })); }
+      });
+    },
+    async pedir(obj, ms) {
+      escrever(sock, obj);
+      return cliente.receber(m => m.r === obj.op, ms || 15000);
+    },
+    fechar() { sock.end(); sock.destroy(); },
+  };
+  const ola = await cliente.pedir({ op: 'ola', ficha: o.ficha !== undefined ? o.ficha : ctl.ficha }, 5000);
+  if (!ola.ok) {
+    cliente.fechar();
+    throw Object.assign(new Error('o hub recusou o controle (ficha inválida: outro usuário?)'), { codigo: ola.erro || 'E_CONTROLE_NEGADO' });
+  }
+  cliente.id = ola.id;
+  return cliente;
+}
+
+module.exports = { abrirControle, conectarControle, arquivoControle };

package/hub/dpapi.js

@@ -0,0 +1,55 @@
+'use strict';
+// DPAPI do Windows (escopo do usuário atual) sem dependência nova: usa o PowerShell do
+// próprio sistema, pelo caminho absoluto (não pelo PATH), e passa os bytes pela entrada
+// padrão — nunca pela linha de comando, que outros processos conseguem ler.
+
+const path = require('path');
+const { execFile } = require('child_process');
+
+// Entropia fixa (não é segredo): amarra o blob a este uso, para um blob DPAPI de outro
+// programa do mesmo usuário não ser aceito aqui e vice-versa.
+const ENTROPIA = 'ts-hub/1/chave-no';
+
+const PREAMBULO =
+  "$ErrorActionPreference='Stop';" +
+  'Add-Type -AssemblyName System.Security;' +
+  "$e=[Text.Encoding]::UTF8.GetBytes('" + ENTROPIA + "');" +
+  '$i=[Convert]::FromBase64String([Console]::In.ReadToEnd().Trim());' +
+  '$s=[System.Security.Cryptography.DataProtectionScope]::CurrentUser;';
+
+const SCRIPT_PROTEGER = PREAMBULO +
+  '$o=[System.Security.Cryptography.ProtectedData]::Protect($i,$e,$s);' +
+  '[Console]::Out.Write([Convert]::ToBase64String($o))';
+const SCRIPT_ABRIR = PREAMBULO +
+  '$o=[System.Security.Cryptography.ProtectedData]::Unprotect($i,$e,$s);' +
+  '[Console]::Out.Write([Convert]::ToBase64String($o))';
+
+function powershell() {
+  const raiz = process.env.SystemRoot || process.env.windir || 'C:\\Windows';
+  return path.join(raiz, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
+}
+
+function rodar(script, bytes) {
+  return new Promise((resolve, reject) => {
+    const filho = execFile(powershell(),
+      ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', script],
+      { windowsHide: true, timeout: 60000, maxBuffer: 1 << 20 },
+      (err, stdout) => {
+        if (err) return reject(new Error('DPAPI indisponível ou falhou (código ' + (err.code || '?') + ')'));
+        const out = String(stdout || '').trim();
+        if (!/^[A-Za-z0-9+/=]+$/.test(out)) return reject(new Error('DPAPI devolveu saída inesperada'));
+        resolve(Buffer.from(out, 'base64'));
+      });
+    filho.stdin.on('error', () => {});
+    filho.stdin.end(Buffer.from(bytes).toString('base64'));
+  });
+}
+
+/** Protetor padrão no Windows: { nome, proteger(bytes) → Buffer, abrir(bytes) → Buffer }. */
+const dpapi = Object.freeze({
+  nome: 'dpapi',
+  proteger: bytes => rodar(SCRIPT_PROTEGER, bytes),
+  abrir: bytes => rodar(SCRIPT_ABRIR, bytes),
+});
+
+module.exports = { dpapi };