terminal-smart-cli 0.98.1 → 0.99.0

package/hub/proto/PROTOCOLO.md

@@ -0,0 +1,789 @@
+# Protocolo do hub do Terminal Smart — versão 1
+
+Especificação do canal entre o **nó** (`ts hub`, no PC ou na VPS dos agentes), o **aparelho**
+(PWA no celular) e o **relay** (`ts-relay`, cego). A implementação de referência é
+`ts-proto.js`, na mesma pasta; os testes ficam em `cli/test/hub-proto.test.js`. Onde este
+texto e o código divergirem, é defeito: corrigir os dois juntos.
+
+Palavras normativas: **DEVE**, **NÃO DEVE**, **PODE**.
+
+---
+
+## 0. Visão geral
+
+```
+ PC / VPS (nó)                  ts-relay (cego)                 celular (aparelho)
+ ─────────────                  ───────────────                 ──────────────────
+ WSS de saída  ───────────────►  /ws  ◄─────────────────────── WSS
+   relay.auth (desafio)            confere assinatura            relay.auth (desafio)
+   relay.lista (assinada)          guarda IDs + chaves públicas
+   rota{para, dados} ◄──────────── repassa `dados` opaco ──────► rota{de, dados}
+                 └──────── fim a fim: aperto de mão ECDH + AES-256-GCM ────────┘
+```
+
+- O aparelho nunca fala direto com o nó. O nó só abre conexão **de saída**.
+- Tudo o que importa vai cifrado de ponta a ponta. O relay vê: IDs, tipo dos quadros de
+  controle, tamanhos e horários. Não vê nomes, métodos, parâmetros nem conteúdo de terminal.
+- Duas chaves de longo prazo por par: a do nó e a do aparelho. Roubar a chave do nó permite
+  se passar pelo nó para o celular, mas **não** permite mandar comandos ao hub: isso exige a
+  chave do aparelho, que não sai do aparelho.
+
+### 0.1 Ameaças consideradas
+
+| Quem | Pode | O protocolo garante |
+|---|---|---|
+| Relay hostil ou invadido | ler, reter, repetir, reordenar, descartar, injetar e forjar quadros | não lê nem forja conteúdo; repetição/reordenação derruba a sessão; não reinsere aparelho revogado (lista assinada) |
+| Quem fotografou o QR | usar o segredo nos 5 min | o convite é de uso único; o PC mostra a impressão do aparelho que chegou e só grava com confirmação humana |
+| Rede entre as pontas e o relay | o mesmo que o relay | TLS (WSS) por cima; o conteúdo continua cifrado de ponta a ponta |
+| Agente com a chave do nó | se passar pelo nó | não consegue assinar comandos do aparelho (o envelope ainda leva o ID do nó, §6.1) |
+| Aparelho perdido | — | revogar no PC: nova lista sem ele; o hub corta as sessões na hora |
+| Quem fotografou o QR e chegou depois | mandar um segundo pedido | recebe `usado` assinado; o celular legítimo que chegar depois vê "Outro aparelho usou este convite — recuse no PC" e o PC é avisado (§3.6) |
+| Agente (outro usuário) na VPS | ler/escrever arquivos dele, tmux dele | o hub não fala com o tmux (lê instantâneos já mascarados, §6.2) e o "Parar tudo" só vale com confirmação de root (§6.2) |
+
+Fora do escopo desta etapa: aparelho desbloqueado nas mãos de terceiros (entrega seguinte:
+biometria/WebAuthn para ações de risco), negação de serviço pelo relay (ele sempre pode
+descartar tudo).
+
+**Limites que o protocolo NÃO resolve (registrados de propósito):**
+
+- **Quem controla a origem que serve a PWA controla o cliente.** A chave do aparelho é não
+  exportável, mas a página a USA: quem trocar o JavaScript servido (servidor da PWA, conta da
+  hospedagem/CDN, Cloudflare com injeção de script — Rocket Loader, Zaraz, analytics) assina
+  comandos e lê telas como se fosse o celular. CSP e esquema fechado não protegem contra quem
+  serve a própria página. Mitigação: origem dedicada, sem script de terceiros, deploy
+  controlado e os requisitos de Cloudflare do `cli/relay/README.md`. WebAuthn (entrega
+  seguinte) amarra ações de risco a um gesto no aparelho, mas também confia na página da
+  mesma origem.
+- **No PC (entrega 2), qualquer processo do mesmo usuário alcança o controle local** (lê
+  `controle.json` com a ficha e conecta no pipe/socket): pode abrir convite e confirmar um
+  pareamento. Por isso, antes de o PC exportar terminais (entrega 2), a confirmação do
+  pareamento no PC exigirá uma interação do sistema (Windows Hello / verificação de
+  consentimento do usuário) que um processo não consegue simular. Na entrega 1 o PC não tem
+  terminais nem "Parar tudo" (`pararDisponivel:false`).
+- **Backup antigo de `aparelhos.json`** traria de volta um aparelho revogado (a lista local é a
+  fonte da verdade, e o hub publica versão `max(anterior+1, relógio)`, que o relay aceita). O
+  hub guarda as revogações em `revogados.jsonl` e a maior versão publicada em
+  `lista-versao.json`, fora do `aparelhos.json`: revogado depois do próprio pareamento continua
+  revogado e a restauração é registrada na auditoria. Quem restaura o diretório inteiro desfaz
+  isso também; depois de qualquer restauração, conferir `ts hub aparelhos` e revogar de novo.
+
+---
+
+## 1. Convenções
+
+- **Texto**: UTF-8. Texto com substituto UTF-16 solitário é inválido.
+- **Bytes em JSON**: base64url **sem preenchimento** (RFC 4648 §5). Decodificação estrita:
+  recusa `=`, espaços, caracteres fora do alfabeto, comprimento ≡ 1 (mod 4) e bits de sobra
+  diferentes de zero (só existe uma codificação válida para cada sequência de bytes).
+- **Tempo**: milissegundos desde 1970-01-01 UTC, inteiro (`ts`, `exp`, `emitidaEm`).
+- **JSON canônico** (o que se assina e o que entra em hash): objetos com chaves ordenadas
+  por unidade de código UTF-16 (a ordem padrão de `Array.prototype.sort`), sem espaços,
+  strings como `JSON.stringify`, números **só inteiros seguros** (|n| ≤ 2⁵³−1; `-0` vira
+  `0`), `true`/`false`/`null`, arrays na ordem dada; nada de `undefined`, `NaN`, objetos não
+  simples; profundidade máxima 16. Exemplo:
+  `{"b":1,"a":[true,null,"x"],"c":{"z":"é","y":-0}}` → `{"a":[true,null,"x"],"b":1,"c":{"y":0,"z":"é"}}`.
+- **Esquema fechado**: todo objeto recebido tem um conjunto exato de campos. Campo a mais,
+  campo faltando ou tipo errado = recusa (`E_FORMATO`).
+- **Rótulo de domínio**: toda assinatura e todo AAD começam com
+  `rotulo(nome) = UTF-8("ts-hub/1/" + nome) || 0x00`. Toda derivação HKDF usa
+  `info = UTF-8("ts-hub/1/" + nome)`. Um valor produzido para um fim nunca vale para outro.
+
+| Rótulo | Uso |
+|---|---|
+| `parear/id` | HKDF: identificador público do convite (`pid`) |
+| `parear/a2n`, `parear/n2a` | HKDF: chaves AES do pareamento, uma por direção |
+| `parear/pedido`, `parear/resposta` | AAD dos quadros de pareamento e assinaturas do texto claro |
+| `sessao` | campo `t` do transcript (`"ts-hub/1/sessao"`) |
+| `sessao/no`, `sessao/aparelho` | assinatura do hash do transcript por cada lado |
+| `sessao/a2n`, `sessao/n2a` | HKDF: chaves AES da sessão, uma por direção |
+| `dados` | AAD dos quadros cifrados de sessão |
+| `comando` | assinatura do envelope de comando |
+| `relay/auth` | assinatura da resposta ao desafio do relay |
+| `lista-aparelhos` | assinatura da lista de aparelhos autorizados |
+
+Primitivas (somente WebCrypto): ECDSA P-256 com SHA-256 (assinatura no formato IEEE P1363,
+`r‖s`, 64 bytes), ECDH P-256, HKDF-SHA256, AES-256-GCM (IV 96 bits, etiqueta 128 bits),
+SHA-256, `getRandomValues`.
+
+---
+
+## 2. Identidades
+
+- Nó e aparelho têm, cada um, um par **ECDSA P-256** de longo prazo.
+- **SPKI**: DER da chave pública, **sempre** na forma de ponto não comprimido: exatamente
+  91 bytes, começando por `3059301306072a8648ce3d020106082a8648ce3d03010703420004`. Outra
+  forma é recusada (`E_CHAVE`); assim cada chave tem um único SPKI e um único ID. O ponto
+  comprimido (33 bytes) só aparece dentro do convite v2 (§3.1); o aparelho o expande para
+  este SPKI antes de qualquer outro uso.
+- **ID** = `base64url(SHA-256(SPKI))` truncado nos primeiros **22 caracteres** (132 bits).
+  Formato: `^[A-Za-z0-9_-]{22}$`.
+- **Impressão digital** (para humanos) = primeiros 16 dígitos hexadecimais de
+  `SHA-256(SPKI)`, em maiúsculas, em grupos de 4: `XXXX-XXXX-XXXX-XXXX` (64 bits).
+- Vetor: SPKI do ponto público do RFC 6979 A.2.5 → ID `Wnp4zKSg9CDZvGK7Zpw8J1`, impressão
+  `5A7A-78CC-A4A0-F420`.
+- Quem recebe um par (ID, SPKI) **DEVE** recalcular o ID a partir do SPKI (`E_ID`).
+
+**Guarda das chaves privadas**
+
+- **Aparelho**: gerada com `extractable:false`. Guardada como `CryptoKey` no IndexedDB
+  (clone estruturado); nunca existe em bytes fora do motor de criptografia do navegador.
+  `identidadeDeChaves` recusa restaurar aparelho com chave exportável
+  (`E_CHAVE_EXPORTAVEL`).
+- **Nó**: exportável, porque o processo Node precisa gravá-la: PKCS#8 cifrado com DPAPI no
+  Windows; na VPS, arquivo `0600` do usuário `tshub`. O módulo só exporta/importa
+  (`exportarIdentidadeNo` / `importarIdentidadeNo`); a cifra em disco é da etapa do hub.
+
+---
+
+## 3. Pareamento
+
+Começa **sempre no PC**. Nunca pelo celular.
+
+### 3.1 Convite (QR)
+
+O nó gera:
+
+- `segredo`: 32 bytes aleatórios (256 bits), **uso único**;
+- `exp` = agora + 5 min (máximo 300 000 ms).
+
+O QR é uma URL. O hub gera o formato **v2** (compacto); o **v1** (JSON) só é lido, para
+compatibilidade com QR antigos — nenhum hub atual o gera.
+
+```
+v2 (gerado):  https://<origem da PWA>/parear#v2.<base64url(71 bytes)>
+v1 (leitura): https://<origem da PWA>/parear#v1.<base64url(JSON canônico da carga)>
+```
+
+A origem da PWA é, por padrão, a do próprio relay (`https://` + host de `relay`); o hub pode
+apontar para outra (`TS_HUB_PWA_URL`, `criarConvite({ pwa })`), quando a PWA é servida por
+outra origem (o relay então não a serve: `TS_RELAY_SERVIR_PWA=0`).
+
+**Carga v2** — concatenação fixa de **exatamente 71 bytes** (qualquer outro tamanho =
+`E_CONVITE_INVALIDO`), em base64url sem preenchimento (95 caracteres):
+
+| Bytes | Conteúdo |
+|---|---|
+| 0–32 (33) | chave pública ECDSA P-256 do nó em ponto **comprimido** SEC1: `0x02`/`0x03` (paridade de y) ‖ X |
+| 33–64 (32) | `segredo` do convite |
+| 65–70 (6) | `exp`: vencimento em ms, inteiro sem sinal big-endian (48 bits) |
+
+- O `nodeId` **não** vai no QR: o aparelho descomprime o ponto (y = (x³ − 3x + b)^((p+1)/4)
+  mod p, com a paridade do prefixo; recusa prefixo ≠ `0x02`/`0x03`, x ≥ p e x sem raiz,
+  conferindo y² ≡ x³ − 3x + b), monta o SPKI (prefixo DER fixo da P-256 + `0x04` ‖ X ‖ Y),
+  confere com `validarSpki`, importa com o WebCrypto (validação final do ponto) e **calcula**
+  `nodeId` e impressão digital a partir dele (§2).
+- O `relay` **não** vai no QR: o aparelho informa o seu (`lerConvite(url, { relay })`, a
+  origem `wss://` com que já conecta — na PWA, a do `config.json`). Sem essa opção, vale a
+  origem WebSocket equivalente à da URL (`https` → `wss`, mesmo host; `http` → `ws` só com
+  `permitirLocal`). O objeto devolvido continua com o campo `relay` (esse valor).
+- Tamanho típico: `https://celular.terminalsmart.com.br/parear#v2.…` tem **142 caracteres**
+  (o v1 equivalente tinha ~440), e o QR cai de 73 para 45 módulos (versão 7, correção L).
+
+**Por que tirar o relay e o `nodeId` não enfraquece nada.** O relay é transporte **não
+confiável** (§0.1): ele só repassa quadros cifrados e não consegue se passar pelo nó. A
+autenticidade do nó vem **só** da chave pública que está no QR — o pedido é cifrado com
+chaves derivadas do `segredo` e do SPKI do nó (§3.2), e a resposta é assinada por essa chave
+(§3.4). Um relay errado (ou malicioso) consegue no máximo atrasar ou derrubar o pareamento.
+O `nodeId` é, por definição, derivado dessa chave (§2); no v1 ele vinha junto e era só
+conferido (`E_ID`), então calculá-lo no aparelho dá o mesmo resultado com menos bytes. Trocar
+a paridade do ponto produz OUTRA chave válida — ou seja, outro `nodeId` e outra impressão;
+não há como apontar para o nó certo com um ponto adulterado.
+
+**Carga v1** (só leitura; exatamente estes campos):
+
+| Campo | Tipo | Conteúdo |
+|---|---|---|
+| `relay` | texto | origem WebSocket canônica do relay: `wss://host[:porta]` (sem caminho; porta padrão omitida) |
+| `nodeId` | ID | ID do nó |
+| `nodePubSpki` | base64url | SPKI do nó |
+| `segredo` | base64url (32 bytes) | segredo do convite |
+| `exp` | inteiro | vencimento (ms) |
+
+No v1 a opção `relay` de `lerConvite` é ignorada (o relay vem do QR), e a PWA exige que ele
+seja o relay da sua configuração (`config.json`; senão `E_RELAY_DIFERENTE`, código local).
+
+Regras comuns às duas versões:
+
+- O fragmento (`#…`) **não vai ao servidor** quando o navegador abre a URL; a PWA lê o
+  fragmento localmente e o apaga do histórico (`history.replaceState`).
+- Sem origem de PWA informada, o host da URL **DEVE** ser o host do relay (`https` ↔ `wss`):
+  no v1, o `relay` da carga; no v2, o `relay` informado (ou, sem ele, a própria origem da
+  URL). Com a PWA em outra origem, o aparelho passa `origemPwa` (a própria origem) a
+  `lerConvite`, e a URL **DEVE** ser dessa origem.
+- Modo local (só testes e etapa 6): `ws://` e `http://` para `localhost`, `127.0.0.1`,
+  `[::1]` e `*.localhost`, apenas com a opção `permitirLocal`.
+- A URL contém o segredo: **NÃO DEVE** ir para log, telemetria, área de transferência ou
+  arquivo. Só para a tela do QR.
+
+O aparelho, ao ler (`lerConvite`), **DEVE** recusar: esquema que não seja `https`, caminho
+diferente de `/parear`, consulta (`?`), credenciais na URL, prefixo diferente de `#v1.` e
+`#v2.` (`E_VERSAO` se for `#vN.` com N ∉ {1, 2}), carga que não decodifica, com tamanho
+(v2) ou campos (v1) diferentes, ponto que não descomprime ou chave que o WebCrypto não
+importa, `nodeId` (v1) que não é o ID de `nodePubSpki` (`E_ID`), convite claramente vencido
+(`agora > exp + 120 s`) e `exp` absurdo (`exp − agora > 5 min + 120 s`). O relógio que
+manda é o do nó; a checagem no aparelho é só de bom senso. A opção `relay` inválida é erro de
+quem chama (`E_ARGUMENTO`).
+
+### 3.2 Derivação
+
+```
+salt   = SHA-256(SPKI do nó)
+pid    = primeiros 22 caracteres de base64url(HKDF(segredo, salt, "ts-hub/1/parear/id", 16))
+K_a2n  = HKDF(segredo, salt, "ts-hub/1/parear/a2n", 32)   → AES-256-GCM, aparelho → nó
+K_n2a  = HKDF(segredo, salt, "ts-hub/1/parear/n2a", 32)   → AES-256-GCM, nó → aparelho
+```
+
+`pid` é o único identificador do convite que o relay vê. Ele não revela o segredo (HKDF
+unidirecional) e é diferente a cada convite.
+
+### 3.3 Pedido (aparelho → nó)
+
+Texto claro (JSON), com assinatura do aparelho como prova de posse da chave:
+
+```
+{ t:"parear.pedido", pid, no:<nodeId>, aparelhoSpki, nome, ts, assinatura }
+assinatura = ECDSA(chave do aparelho, rotulo("parear/pedido") || canonico(objeto sem "assinatura"))
+```
+
+- `nome`: rótulo do aparelho para a tela do PC. O aparelho normaliza (NFC, espaços
+  colapsados, aparado). Regras: 1 a 40 caracteres; proibidos caracteres de controle, de
+  formatação invisível e de sobreposição bidirecional (U+0000–001F, U+007F–009F, U+00AD,
+  U+061C, U+180E, U+200B–200F, U+2028–202E, U+2060–206F, U+FEFF, U+FFF9–FFFB). Inválido =
+  `E_NOME`.
+
+Quadro no fio (o que o relay vê):
+
+```
+{ t:"parear.pedido", v:1, pid, iv:<12 bytes aleatórios>, ct:<AES-GCM(K_a2n, iv, texto claro, AAD)> }
+AAD = rotulo("parear/pedido") || UTF-8(pid)
+```
+
+O convite também é de uso único **no aparelho**: depois de montar o pedido, o segredo é
+apagado da memória do convite.
+
+### 3.4 Processamento no nó (ordem exata)
+
+1. Esquema do quadro (`E_FORMATO`), `v` = 1 (`E_VERSAO`).
+2. `pid` conhecido (`E_CONVITE_DESCONHECIDO`); não usado (`E_CONVITE_USADO`); não vencido
+   pelo relógio do nó (`E_CONVITE_EXPIRADO`, e o convite é descartado). Pedido para convite
+   **já usado** enquanto a decisão do primeiro está aberta: `responderUsado` decifra com
+   `K_a2n`, confere o texto claro como no passo 5 e devolve ao aparelho que mandou ESTE pedido
+   a resposta assinada com `estado:"usado"` (§3.5), pelo canal dele; no máximo
+   `PAREAR_USADO_MAX` (4) tentativas por convite; o mesmo aparelho do primeiro pedido não
+   recebe `usado`. Nada muda no convite.
+3. Decifrar com `K_a2n`. Falha = `E_DECIFRAR` e conta uma tentativa; **5 tentativas que não
+   decifram descartam o convite** (proteção contra adivinhação e contra quem só quer
+   gastar o convite: sem o segredo ninguém produz um pedido que decifre).
+4. **Consumir o convite** (marcar usado) — no primeiro pedido que decifra, sem `await`
+   entre a checagem e a marcação: dois pedidos simultâneos nunca consomem o mesmo convite.
+5. Esquema do texto claro; `pid` e `no` conferem; `ts` dentro de ±120 s (`E_TEMPO`); `nome`
+   válido (`E_NOME`); SPKI válido (`E_CHAVE`); assinatura (`E_ASSINATURA`). Qualquer falha
+   aqui **encerra** o convite (já consumido).
+6. Devolver à etapa do hub `{ id, spki, nome, impressao }` do aparelho.
+
+### 3.5 Resposta (nó → aparelho)
+
+```
+texto claro = { t:"parear.resposta", pid, no:<nodeId>, aparelho:<ID do aparelho>, estado, ts, assinatura }
+assinatura  = ECDSA(chave do nó, rotulo("parear/resposta") || canonico(objeto sem "assinatura"))
+quadro      = { t:"parear.resposta", v:1, pid, iv, ct }   AAD = rotulo("parear/resposta") || UTF-8(pid)
+```
+
+`estado`: `pendente` (opcional, no máximo uma vez, sempre primeiro) → `aceito` ou
+`recusado` (final; depois disso o nó apaga as chaves do convite); ou `usado` sozinho (final:
+outro aparelho mandou pedido antes com este convite; a PWA mostra "Outro aparelho usou este
+convite — recuse no PC"). O aparelho confere a assinatura com a chave do nó que veio **no
+QR** (canal autêntico: a tela do PC), que `aparelho` é ele mesmo, e aceita só essa ordem
+(`E_PAREAMENTO_ESTADO`).
+
+### 3.6 Confirmação humana
+
+- Os dois lados calculam a **impressão digital do aparelho**
+  (`impressaoDeSpki(aparelhoSpki)`): o celular, da própria chave (e a mostra); o PC, da
+  chave que chegou no pedido (e a usa para conferir o código digitado). O aparelho também
+  pode mostrar a impressão do nó.
+- O PC **não mostra** a impressão do aparelho. A pessoa lê a impressão **no celular** e
+  **digita no PC** os 8 primeiros caracteres (comparação sem hífen e sem diferenciar
+  maiúsculas; código errado = `E_CONFIRMACAO` no controle local, e no terceiro erro o
+  pedido é recusado). Nada de "s/N": confirmar exige ter o celular na mão. Só então o PC
+  **grava** o aparelho (e publica nova lista, seção 7.4) e o hub chama
+  `responder(pid, "aceito")`. Na entrega 2 (PC com terminais), a confirmação também exigirá
+  interação do sistema (§0.1).
+- Se alguém que fotografou o QR chegar primeiro, o código que ele mostra não é o do celular
+  da pessoa; o celular legítimo, ao mandar o pedido, recebe `usado` (§3.4) e mostra "Outro
+  aparelho usou este convite — recuse no PC"; o PC também avisa que outro aparelho tentou.
+  A pessoa recusa e gera outro QR.
+- Cada pareamento aceito gera o evento `hub.aparelhoNovo { nome, impressao }` para os
+  aparelhos já pareados (na hora, para quem tem sessão; na próxima sessão, para quem não tem,
+  enquanto o hub não reiniciar). A PWA mostra o aviso até a pessoa dispensar.
+- Prazo para decidir: **até o vencimento do convite (`exp`)**. O nó encerra a decisão em
+  `exp`, com ou sem pedido aguardando (nada é gravado; decidir depois = `E_PAREAMENTO_ESTADO`).
+  Motivo: o pedido só entra até `exp`, e a conexão anônima do celular vive 6 min a partir do
+  primeiro `parear.enviar` no relay (§7.2), então qualquer resposta dada até `exp` ainda
+  encontra o celular (folga ≥ 1 min). `LIMITES.DECISAO_MS` (5 min) fica só como teto do
+  protocolo e tolerância de relógio: o registro do nó e o aparelho não aceitam resposta depois
+  de `exp + DECISAO_MS`.
+- No máximo 4 convites vigentes ao mesmo tempo por nó (`E_LIMITE`).
+
+### 3.7 Transporte do pareamento pelo relay
+
+O aparelho ainda não tem identidade registrada; ele usa uma conexão **anônima** (seção 7.2).
+
+```
+nó       → relay   { t:"relay.parear.abrir", pid, exp }        abre o pid (exp ≤ agora + 5 min)
+aparelho → relay   { t:"parear.enviar", pid, dados:<quadro parear.pedido em JSON> }
+relay    → nó      { t:"parear.chegou", pid, canal, dados }    canal = ID aleatório do relay
+nó       → relay   { t:"parear.responder", canal, dados:<quadro parear.resposta> }
+relay    → aparelho{ t:"parear.chegou", pid, dados }
+nó       → relay   { t:"relay.parear.fechar", pid }            ao terminar ou cancelar
+```
+
+O relay só aceita `parear.enviar` para `pid` aberto e não vencido, no máximo
+`PAREAR_FALHAS_MAX` (5) por `pid`, e fecha o `pid` no vencimento.
+
+---
+
+## 4. Sessão: aperto de mão
+
+Três mensagens, iniciadas pelo aparelho, levadas em `rota.dados`. Ambos os lados usam chaves
+ECDH P-256 **efêmeras** e assinam o mesmo transcript com a chave de longo prazo.
+
+```
+1. aparelho → nó   { t:"sessao.ola",      v:1, sid, aparelho:<ID>, no:<ID>, eA }
+2. nó → aparelho   { t:"sessao.resposta", v:1, sid, eN, assinatura:Sig_nó(rotulo("sessao/no") || th) }
+3. aparelho → nó   { t:"sessao.confirma", v:1, sid, assinatura:Sig_aparelho(rotulo("sessao/aparelho") || th) }
+```
+
+- `sid`: 16 bytes aleatórios do aparelho (22 caracteres base64url).
+- `eA`, `eN`: chave pública ECDH efêmera, formato `raw` não comprimido (65 bytes, começa
+  por `0x04`), em base64url. Ponto fora da curva = `E_CHAVE`.
+- Transcript:
+
+```
+th = SHA-256(canonico({ t:"ts-hub/1/sessao", v:1, sid,
+                        aparelho, aparelhoSpki, no, noSpki, eA, eN }))
+```
+
+  Inclui os **SPKI completos** dos dois lados (não só os IDs truncados): a sessão fica
+  amarrada às duas identidades e às duas efêmeras. Rótulos distintos por signatário impedem
+  refletir a assinatura de um lado como se fosse do outro.
+
+**Nó, ao receber `sessao.ola`**: balde de fichas **global** do hub para olás (10/s, rajada
+20; cada olá custa ECDH + assinatura antes de o aparelho provar a posse da chave): sem ficha,
+descarta em silêncio (log agregado); esquema e versão; `no` é o próprio ID (`E_SESSAO`); se o
+relay informou o remetente (`rota.de`), ele **DEVE** ser igual a `aparelho` (`E_SESSAO`);
+aparelho na lista local de autorizados (`E_APARELHO_NAO_AUTORIZADO`); ID confere com o SPKI
+guardado (`E_ID`); `eA` válida. Gera `eN`, calcula o segredo ECDH, `th`, assina, deriva as
+chaves (4.1) e descarta a efêmera e o segredo ECDH.
+
+**Aparelho, ao receber `sessao.resposta`**: no máximo 30 s depois do olá
+(`E_HANDSHAKE_EXPIRADO`); `sid` confere; assinatura do nó com a chave gravada no
+pareamento (`E_ASSINATURA`). Deriva as chaves, assina `th`, manda `sessao.confirma` e já
+pode cifrar.
+
+**Nó, ao receber `sessao.confirma`**: no máximo 30 s depois da resposta; `sid` confere;
+aparelho **ainda** autorizado (pode ter sido revogado no meio); assinatura do aparelho
+(`E_ASSINATURA`). Só então a sessão existe do lado do nó. O nó **NÃO DEVE** aceitar nem
+enviar quadro `dados` antes disso.
+
+Os estados intermediários são de uso único (repetir a mesma resposta ou confirmação =
+`E_SESSAO`). Um olá repetido pelo relay gera nova `eN`, novo `th`, e a confirmação antiga
+deixa de valer: não há cache de repetição a manter.
+
+### 4.1 Chaves da sessão
+
+```
+z      = ECDH(efêmera própria, efêmera do outro)            32 bytes
+K_a2n  = HKDF(ikm=z, salt=th, info="ts-hub/1/sessao/a2n", 32)   aparelho → nó
+K_n2a  = HKDF(ikm=z, salt=th, info="ts-hub/1/sessao/n2a", 32)   nó → aparelho
+```
+
+As chaves viram `CryptoKey` AES-GCM **não exportáveis** e as cópias em bytes são zeradas.
+
+### 4.2 Sigilo futuro
+
+As privadas efêmeras são geradas não exportáveis e descartadas assim que `z` é calculado; `z`
+é zerado depois da derivação. Vazar depois a chave de longo prazo de um dos lados não abre
+sessões passadas. (JavaScript não garante apagar memória; o código zera o que controla e não
+guarda referências.)
+
+### 4.3 Vida da sessão
+
+- No máximo **12 h** (`E_SESSAO_EXPIRADA`) e 2³¹−1 quadros por direção
+  (`E_LIMITE_SESSAO`). Depois, novo aperto de mão.
+- Reconexão ao relay = nova sessão (novo aperto de mão). Não há retomada.
+- **Uma sessão por aparelho em cada nó**: o relay mantém uma só conexão por ID (a nova fecha a
+  anterior com 4001) e não avisa o nó quando o aparelho cai; por isso o nó, ao concluir uma
+  sessão nova, encerra as anteriores do mesmo aparelho. O aparelho que recebe 4001 (outra
+  aba/janela dele assumiu) não reconecta sozinho — só quando volta a ser usado — para as
+  abas não se derrubarem em ciclo.
+
+---
+
+## 5. Cifra dos quadros de sessão
+
+```
+{ t:"dados", sid, n, ct }
+nonce = direção (4 bytes, big-endian: 1 = aparelho→nó, 2 = nó→aparelho) || n (8 bytes, big-endian)
+AAD   = rotulo("dados") || sid (16 bytes) || direção (1 byte) || n (8 bytes, big-endian)
+ct    = AES-256-GCM(K_direção, nonce, UTF-8(JSON do texto claro), AAD)   (inclui a etiqueta de 16 bytes)
+```
+
+- `n` começa em 0 em cada direção e sobe de 1 em 1. Como o WebSocket entrega em ordem, o
+  receptor exige `n` **exatamente igual** ao próximo esperado.
+- **Qualquer** anomalia derruba a sessão de vez e apaga as chaves: `n` repetido, saltado ou
+  fora de ordem (`E_CONTADOR`), falha de autenticação (`E_DECIFRAR`), `sid` trocado ou
+  quadro malformado (`E_FORMATO`), texto claro que não é objeto JSON. Depois disso, tudo
+  falha com `E_SESSAO_DERRUBADA`; o aparelho refaz o aperto de mão.
+- Nonce nunca se repete: chave por direção + contador estritamente crescente. A direção no
+  nonce é defesa extra contra reflexão (a chave já é outra).
+- Texto claro ≤ **32 KiB** (`E_TAMANHO`), para o quadro caber em 64 KiB depois de base64url.
+- Cifrar e decifrar são serializados por sessão: o contador é reservado e os resultados saem
+  na ordem das chamadas. O chamador **DEVE** enviar os quadros na ordem em que foram
+  produzidos.
+
+---
+
+## 6. Mensagens de aplicação
+
+Texto claro dos quadros `dados`. O campo `k` diz o tipo.
+
+### 6.1 Comando (aparelho → nó)
+
+```
+{ k:"cmd", env:{ sessao:<sid>, no:<ID do nó>, seq, metodo, params, ts }, assinatura }
+assinatura = ECDSA(chave do aparelho, rotulo("comando") || canonico(env))
+```
+
+- `no`: ID do nó da sessão. Amarra a assinatura do comando ao nó (além do `sid`): um envelope
+  assinado para um nó nunca vale em outro.
+
+- `seq`: inteiro ≥ 1, estritamente crescente dentro da sessão (o módulo usa 1, 2, 3…).
+  `aparelhoCriarComando` serializa por sessão a reserva do `seq`, a assinatura e a cifra:
+  com chamadas simultâneas, a ordem dos `seq` é a mesma dos contadores `n` dos quadros, e as
+  promessas resolvem na ordem das chamadas (enviar cada quadro quando a sua promessa resolve
+  mantém a ordem). Comando recusado localmente não gasta `seq`.
+- `ts`: relógio do aparelho.
+- O envelope é assinado **além** da cifra: o hub verifica com a chave do aparelho guardada
+  localmente, então nem o relay, nem quem tiver a chave do nó, nem um defeito no transporte
+  consegue produzir um comando.
+
+**Verificação no hub (ordem e consequência):**
+
+| # | Checagem | Falha | Sessão |
+|---|---|---|---|
+| 1 | aparelho ainda autorizado (consulta a cada comando) | `E_APARELHO_NAO_AUTORIZADO` | derruba |
+| 2 | decifrar o quadro (seção 5) | `E_CONTADOR` / `E_DECIFRAR` / `E_FORMATO` | derruba |
+| 3 | esquema `{k,env,assinatura}` e `env` com exatamente 6 campos, JSON canônico possível | `E_FORMATO` | derruba |
+| 4 | `env.sessao` = `sid` da sessão e `env.no` = ID do próprio nó | `E_SESSAO` | derruba |
+| 5 | assinatura com a chave do aparelho | `E_ASSINATURA` | derruba |
+| 6 | `seq` > último aceito | `E_SEQ` | derruba |
+| 7 | `ts` dentro de ±120 s do relógio do hub | `E_TEMPO` | segue |
+| 8 | `metodo` na lista fechada | `E_METODO` | segue |
+| 9 | `params` válidos para o método | `E_PARAMS` | segue |
+
+Nos casos 7–9 o erro carrega o `seq` (único dado não sigiloso), para o hub responder
+`{ok:false}` ao comando certo. O `seq` é consumido a partir do passo 6.
+
+### 6.2 Lista fechada da entrega 1
+
+| Método | `params` (esquema fechado) | Efeito |
+|---|---|---|
+| `hub.status` | `{}` | estado do nó (no ar, agentes, versão) |
+| `terminals.list` | `{}` | terminais visíveis do nó |
+| `terminal.watch` | `{ terminalId, historico? }` | passa a receber `terminal.tela` (só leitura) |
+| `terminal.unwatch` | `{ terminalId }` | para de receber |
+| `hub.stopAll` | `{ confirmar: true }` | Parar tudo |
+
+- `terminalId`: `^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$`.
+- `historico`: inteiro 0–200 (`LIMITES.HISTORICO_MAX`; linhas de histórico iniciais).
+- Evento `terminal.tela` → `{ terminalId, colunas, linhas, tela }`: a tela inteira de novo
+  (texto com escapes SGR de cor), só quando mudou. A tela vai **num único quadro**: o limite
+  é o texto claro de §5 (32 KiB, contando o JSON e os escapes). Se não couber, o nó corta o
+  histórico **mais antigo** (linhas do topo; em último caso, o começo da última linha) até
+  caber. `terminal.fim` → `{ terminalId }` quando o terminal some; `hub.estado` →
+  `{ parado }`. Resultados e eventos detalhados: `CONTRATO-ENTREGA1.md`.
+- Terminal que não existe (ou sumiu) no nó: `E_TERMINAL_INEXISTENTE` (a sessão segue).
+- `confirmar` **DEVE** ser o booleano `true` (proteção contra toque acidental ou cliente
+  com defeito).
+- `hub.status` → `{ nome, versao, so, tempoNoArSeg, parado, pararDisponivel, terminais }`.
+  `pararDisponivel:false` = o nó não tem consumidor do "Parar tudo" (ex.: o PC); a PWA
+  desabilita o botão para ele.
+- `hub.stopAll`: o hub grava um **pedido** (diretório fixo, `O_EXCL`, sem seguir link) e só
+  responde `{ parado:true }` depois da **confirmação** de um consumidor externo (na VPS, uma
+  unidade de root; exemplos em `cli/hub/vps/`), em até 10 s. Sem confirmação:
+  `E_PARAR_SEM_CONFIRMACAO` (a PWA mostra "não confirmado"). Sem consumidor:
+  `E_PARAR_INDISPONIVEL`. `parado` (em `hub.status` e `hub.estado`) reflete a confirmação,
+  nunca a existência do pedido.
+- Telas: o hub não fala com o tmux. `ts hub exportar-telas` (rodando como o usuário dos
+  agentes) grava instantâneos só das janelas permitidas, com no máximo 200 linhas de
+  histórico, só SGR e segredos conhecidos mascarados; o hub só lê esses arquivos.
+- Evento `hub.aparelhoNovo` → `{ nome, impressao }` (§3.6).
+- Qualquer outro método = `E_METODO`. Nunca pelo celular: parear, mudar agentes,
+  permissões, drivers ou credenciais, digitar no terminal (fica para entrega futura, com
+  biometria).
+- O módulo exporta `METODOS` (lista) e `validarParametros(metodo, params)`.
+
+### 6.3 Resposta e evento (nó → aparelho)
+
+```
+{ k:"resp", seq, ok:true,  resultado }          resultado: qualquer JSON (null se vazio)
+{ k:"resp", seq, ok:false, erro:{ codigo } }    codigo: ^E_[A-Z_]{1,40}$ — nunca texto livre
+{ k:"evento", tipo, dados }                     tipo: ^[a-z][a-zA-Z0-9._]{0,63}$ (ex.: terminal.tela)
+```
+
+Respostas e eventos não levam assinatura própria: a chave de sessão só existe nas duas
+pontas e o nó já provou a identidade no aperto de mão. O aparelho recusa `seq` que ele não
+enviou (derruba a sessão).
+
+---
+
+## 7. Relay
+
+### 7.1 Conexão
+
+- Endpoint: `<relay>/ws` (ex.: `wss://relay.terminalsmart.com.br/ws`), TLS validado.
+- Cada mensagem WebSocket é **texto** com um quadro de controle JSON, ≤ **64 KiB** em bytes
+  UTF-8 (`E_TAMANHO`; o relay fecha a conexão).
+- O relay **DEVE**: validar cada quadro com o esquema da sua direção (`lerQuadroRelay`);
+  **preencher** `de` a partir da conexão autenticada (o cliente não pode informar `de`);
+  tratar `dados` como texto opaco (não analisar, não guardar, não registrar em log); não
+  registrar em log nada além de ID, tipo, tamanho, horário e código de erro.
+- Ao abrir a conexão, o relay manda o desafio. Sem `relay.auth` válido em 10 s (ou sem
+  `parear.enviar`, para conexão anônima), fecha.
+- Navegador: o relay só aceita no `/ws` o cabeçalho `Origin` das origens da PWA (a do próprio
+  relay quando ele serve a PWA; mais `TS_RELAY_ORIGENS_PWA`). Cliente sem `Origin` (o hub)
+  passa.
+
+### 7.2 Papéis
+
+| Papel | Como se obtém | Pode enviar |
+|---|---|---|
+| `no` | `relay.auth` com `papel:"no"` | `relay.lista`, `rota`, `relay.parear.abrir`, `relay.parear.fechar`, `parear.responder`, `relay.ping` |
+| `aparelho` | `relay.auth` com `papel:"aparelho"` **e** ID presente na lista vigente de pelo menos um nó | `rota` (só para nós cuja lista o contém), `relay.ping` |
+| anônimo | primeiro quadro `parear.enviar` | só `parear.enviar`; 6 quadros/min; fechada em 6 min |
+
+### 7.3 Desafio-resposta (autenticação de nó e aparelho)
+
+```
+relay → cliente  { t:"relay.desafio", v:1, nonce:<32 bytes aleatórios>, relay:<origem do relay> }
+cliente → relay  { t:"relay.auth", v:1, papel, id, spki, assinatura }
+assinatura = ECDSA(chave do cliente, rotulo("relay/auth") ||
+                   canonico({ t:"relay.auth", v:1, papel, id, nonce, relay }))
+relay → cliente  { t:"relay.ok", papel, id }   ou   { t:"relay.erro", codigo }
+```
+
+- O cliente **DEVE** conferir que `relay` do desafio é o relay ao qual quis se conectar
+  (`E_DESAFIO`), para nunca assinar autenticação para outro relay.
+- O relay confere: desafio desta conexão, não usado, com no máximo 30 s (`E_DESAFIO`);
+  `id` = ID do `spki` (`E_ID`); assinatura (`E_ASSINATURA`). `papel` está dentro do que é
+  assinado.
+- **Registro do nó**: o ID é autocertificado (hash da própria chave). A primeira
+  autenticação de um nó cria o registro dele no relay (ID + SPKI); as seguintes só
+  confirmam. O relay **PODE** restringir os nós aceitos (lista `TS_RELAY_NOS`, obrigatória
+  em produção); nó fora dela = `relay.erro {codigo:"E_NO_NAO_AUTORIZADO"}` e fecha.
+- **Aparelho**: além da assinatura, o relay exige que o ID esteja na lista vigente de algum
+  nó, com o **mesmo SPKI** que está na lista.
+
+### 7.4 Lista de aparelhos autorizados (assinada pelo nó)
+
+```
+{ t:"relay.lista",
+  lista:{ no:<ID do nó>, versao, emitidaEm, aparelhos:[ { id, spki }, … ] },
+  assinatura:ECDSA(chave do nó, rotulo("lista-aparelhos") || canonico(lista)) }
+```
+
+- `versao`: inteiro ≥ 1, **estritamente crescente**. Lista com versão menor ou igual à
+  guardada = `E_LISTA_VERSAO` (o relay não aceita lista velha reapresentada).
+- `aparelhos`: no máximo 50, ordenados por `id`, sem repetição, cada `id` = ID do `spki`
+  (`E_LISTA_INVALIDA`).
+- O relay confere a assinatura com o SPKI do nó **autenticado** na conexão e exige
+  `lista.no` = esse nó.
+- **Revogar** = publicar nova versão sem o aparelho. Ao aceitar a lista, o relay derruba as
+  conexões de aparelho que saíram dela (para aquele nó) e passa a recusar `rota` entre eles.
+- O hub mantém a própria lista (fonte da verdade) e corta as sessões do aparelho revogado
+  na hora, sem depender do relay. A lista no relay é defesa em profundidade e serve para o
+  relay recusar aparelhos desconhecidos antes de gastar recursos com eles.
+- O relay guarda só a última lista (com assinatura) de cada nó. Nada mais.
+
+### 7.5 Roteamento e presença
+
+```
+cliente → relay  { t:"rota", para:<ID>, dados:<texto ≤ 61 440 caracteres> }
+relay → destino  { t:"rota", de:<ID do remetente autenticado>, dados }
+relay → aparelho { t:"relay.presenca", no:<ID>, online:<booleano> }   nós cuja lista contém o aparelho
+cliente → relay  { t:"relay.ping" }       relay → cliente { t:"relay.pong" }
+```
+
+`dados` carrega os quadros fim a fim (`sessao.*`, `dados`, `parear.*`) como texto JSON. O
+relay só repassa entre nó e aparelho que se autorizam pela lista vigente; nó↔nó e
+aparelho↔aparelho são recusados.
+
+### 7.6 Tabela de quadros de controle
+
+| Direção | `t` | Campos (além de `t`) |
+|---|---|---|
+| para o relay | `relay.auth` | `v, papel, id, spki, assinatura` |
+| para o relay | `relay.lista` | `lista, assinatura` |
+| para o relay | `relay.parear.abrir` | `pid, exp` |
+| para o relay | `relay.parear.fechar` | `pid` |
+| para o relay | `parear.enviar` | `pid, dados` |
+| para o relay | `parear.responder` | `canal, dados` |
+| para o relay | `rota` | `para, dados` |
+| para o relay | `relay.ping` | — |
+| do relay | `relay.desafio` | `v, nonce, relay` |
+| do relay | `relay.ok` | `papel, id` |
+| do relay | `relay.erro` | `codigo` |
+| do relay | `relay.presenca` | `no, online` |
+| do relay | `rota` | `de, dados` |
+| do relay | `parear.chegou` | `pid, dados` e, só para o nó, `canal` |
+| do relay | `relay.pong` | — |
+
+---
+
+## 8. Limites
+
+| Limite | Valor | Onde |
+|---|---|---|
+| Mensagem WebSocket (quadro de controle) | 64 KiB (65 536 bytes UTF-8) | relay e pontas |
+| Histórico pedido em `terminal.watch` | 0–200 linhas | aparelho e nó |
+| Respostas `usado` por convite | 4 | nó |
+| `sessao.ola` no hub (global) | 10/s, rajada 20 | nó |
+| Reabertura de sessão no aparelho | recuo até 60 s; no máximo 6 apertos de mão por nó por minuto (a presença não zera) | aparelho |
+| Conexões não autenticadas no relay | 200 (de 2000), vagas reservadas para autenticados; cheio, sai a pendente mais antiga | relay |
+| Conexões por IP no relay | 32 (IPv6 por /64) e 128 por /48 | relay |
+| Campo `dados` | 61 440 caracteres | relay e pontas |
+| Texto claro de quadro de sessão | 32 KiB | pontas |
+| Taxa por conexão autenticada | 30 quadros/s (rajada 60) e 256 KiB/s (rajada 512 KiB) | relay |
+| Conexão anônima de pareamento | 6 quadros/min, 8 KiB/s; fechada em 6 min | relay |
+| Validade do convite | 5 min; decisão no PC até o vencimento | nó |
+| Convites vigentes por nó | 4 | nó |
+| Pedidos que não decifram por convite | 5 | nó e relay |
+| Tolerância de relógio (`ts`) | ±120 s | nó e aparelho |
+| Aperto de mão | 30 s por etapa | pontas |
+| Vida da sessão | 12 h ou 2³¹−1 quadros por direção | pontas |
+| Validade do desafio do relay | 30 s, uso único | relay |
+| Aparelhos por lista | 50 (o plano grátis limita a 3 no hub) | nó e relay |
+| Nome do aparelho | 1–40 caracteres | nó e aparelho |
+| Profundidade de JSON | 16 | todos |
+
+Excedeu a taxa: `relay.erro {codigo:"E_TAXA"}` e o relay **PODE** fechar a conexão. O
+módulo traz `LimitadorTaxa` (balde de fichas), `criarLimitesConexao(papel)` e `exigirTaxa`.
+
+---
+
+## 9. Códigos de erro
+
+Todos os erros são `TsProtoErro` com `codigo` estável e mensagem fixa em português, **sem
+eco** do dado recebido nem de segredo. `JSON.stringify(erro)` = `{"codigo":…}` (mais `seq`,
+quando for erro de comando). Pelo fio, só o código.
+
+| Código | Significado |
+|---|---|
+| `E_FORMATO` | quadro ou campo fora do esquema |
+| `E_TAMANHO` | acima do limite de tamanho |
+| `E_VERSAO` | versão não suportada |
+| `E_ARGUMENTO` | uso incorreto da API (erro de programação local) |
+| `E_CRIPTO_INDISPONIVEL` | sem WebCrypto (ex.: página fora de contexto seguro) |
+| `E_CHAVE` | chave pública/privada inválida, ponto fora da curva, SPKI fora do formato |
+| `E_CHAVE_EXPORTAVEL` | tentativa de usar chave de aparelho exportável |
+| `E_ID` | ID não corresponde à chave |
+| `E_ASSINATURA` | assinatura inválida |
+| `E_DECIFRAR` | AES-GCM não autenticou |
+| `E_CONVITE_INVALIDO` | URL de QR malformada |
+| `E_CONVITE_DESCONHECIDO` | `pid` desconhecido (nunca existiu, vencido e apagado, ou descartado) |
+| `E_CONVITE_EXPIRADO` | convite vencido |
+| `E_CONVITE_USADO` | convite já consumido |
+| `E_PAREAMENTO_ESTADO` | resposta de pareamento fora de ordem ou após o fim |
+| `E_NOME` | nome do aparelho inválido |
+| `E_LIMITE` | limite de convites vigentes |
+| `E_HANDSHAKE_EXPIRADO` | etapa do aperto de mão depois de 30 s |
+| `E_APARELHO_NAO_AUTORIZADO` | aparelho não pareado ou revogado |
+| `E_SESSAO` | `sid` ou estado de sessão inválido |
+| `E_SESSAO_DERRUBADA` | sessão já derrubada |
+| `E_SESSAO_EXPIRADA` | sessão passou de 12 h |
+| `E_CONTADOR` | quadro repetido, saltado ou fora de ordem |
+| `E_LIMITE_SESSAO` | contador de quadros esgotado |
+| `E_SEQ` | `seq` de comando não crescente |
+| `E_TEMPO` | `ts` fora de ±120 s |
+| `E_METODO` | método fora da lista fechada |
+| `E_PARAMS` | parâmetros inválidos |
+| `E_DESAFIO` | desafio do relay inválido, vencido, já usado ou de outro relay |
+| `E_LISTA_VERSAO` | lista com versão não maior que a atual |
+| `E_LISTA_INVALIDA` | lista malformada |
+| `E_TAXA` | limite de taxa |
+| `E_NO_NAO_AUTORIZADO` | relay: nó fora da lista de nós permitidos (`TS_RELAY_NOS`) |
+| `E_TERMINAL_INEXISTENTE` | hub: `terminalId` válido, mas o terminal não existe (ou sumiu) |
+| `E_PARAR_SEM_CONFIRMACAO` | hub: "Parar tudo" pedido, mas o consumidor não confirmou no prazo (ou falhou) |
+| `E_PARAR_INDISPONIVEL` | hub: o nó não tem consumidor do "Parar tudo" (`pararDisponivel:false`) |
+| `E_INTERNO` | código desconhecido (não deveria acontecer) |
+
+Códigos novos podem ser **acrescentados**; os existentes não mudam de significado.
+
+---
+
+## 10. Versionamento
+
+- A versão aparece em três lugares: prefixo do QR (`#v2.`/`#v1.`), campo `v` dos quadros
+  (`relay.desafio`, `relay.auth`, `parear.*`, `sessao.*`) e prefixo de todos os rótulos
+  (`ts-hub/1/`). O número do QR é a versão do **formato do convite** (§3.1), independente dos
+  outros dois: o v2 do QR muda só a codificação da URL e segue no protocolo 1 (`v: 1`,
+  `ts-hub/1/`). Mudar o significado de qualquer campo, rótulo, primitiva ou ordem de
+  verificação = **nova versão** (2), com prefixo `ts-hub/2/`.
+- Versão desconhecida é recusada com `E_VERSAO`; nunca se tenta "o mais parecido". Não há
+  negociação para baixo (sem ataque de rebaixamento): quando existir a v2, o aparelho manda
+  o `sessao.ola` da maior versão que conhece e o nó responde `E_VERSAO` se não a suportar;
+  o aparelho então mostra "atualize o hub".
+- Acrescentar um método à lista fechada não muda a versão do protocolo (muda a lista
+  exportada e a validação), mas exige atualizar hub e PWA juntos.
+- Campos novos em quadros existentes **não** são tolerados (esquema fechado): exigem nova
+  versão.
+
+---
+
+## 11. API do módulo (`ts-proto.js`)
+
+Carregar: `require('./hub/proto/ts-proto.js')` no Node 22+, ou `<script src="ts-proto.js">`
+no navegador (expõe `globalThis.TsProto`; servir com `charset=utf-8`; exige contexto seguro
+para `crypto.subtle`). Todas as funções aceitam `{ agora }` (ms) para testes; o padrão é
+`Date.now()`.
+
+| Área | Funções |
+|---|---|
+| Codificação | `b64u`, `deB64u`, `hex`, `canonico`, `verificarTamanhoQuadro`, `lerQuadroFimAFim` |
+| Primitivas | `sha256`, `hkdf` |
+| Identidade | `gerarIdentidade({tipo})`, `identidadeDeChaves`, `exportarIdentidadeNo`, `importarIdentidadeNo`, `idDeSpki`, `impressaoDeSpki`, `comprimirSpki`, `descomprimirSpki` (ponto SEC1 do convite v2) |
+| Pareamento (nó) | `new RegistroPareamentos({identidade})` → `criarConvite({relay, pwa?})`, `abrirPedido`, `responderUsado`, `responder`, `cancelar`, `pendentes` |
+| Pareamento (aparelho) | `lerConvite(url, {origemPwa?, relay?})`, `criarPedidoPareamento`, `abrirRespostaPareamento`, `normalizarNome`, `validarOrigemPwa` |
+| Sessão | `aparelhoIniciarSessao`, `noResponderSessao`, `aparelhoConcluirSessao`, `noConcluirSessao`; `Sessao#cifrar`, `#decifrar`, `#derrubar`, `#derrubada` |
+| Comandos | `METODOS`, `validarParametros`, `aparelhoCriarComando`, `noAbrirComando`, `noResponder`, `noEnviarEvento`, `aparelhoAbrirMensagem` |
+| Relay | `relayCriarDesafio`, `clienteResponderDesafio`, `relayVerificarAuth`, `noAssinarListaAparelhos`, `verificarListaAparelhos`, `validarQuadroRelay`, `lerQuadroRelay`, `LimitadorTaxa`, `criarLimitesConexao`, `exigirTaxa` |
+| Constantes | `VERSAO`, `LIMITES`, `CODIGOS`, `TsProtoErro` |
+
+Segredos nunca ficam em propriedades enumeráveis: o segredo do convite e as chaves de
+pareamento/sessão ficam em `WeakMap` ou em `CryptoKey` não exportável, para não vazarem por
+`JSON.stringify` ou `console.log`. O módulo não escreve em log.
+
+---
+
+## 12. Notas de segurança para as próximas etapas
+
+- **Hub (etapa 3)**: guardar a lista de aparelhos autorizados (ID, SPKI, nome, data) fora
+  do alcance dos agentes; consultar `aparelhoAutorizado` em todo comando; ao revogar,
+  derrubar as sessões do aparelho, registrar a revogação fora do `aparelhos.json` e publicar
+  nova lista; confirmar o pareamento digitando no PC o código mostrado no celular; nunca
+  registrar a URL do convite (`ts hub parear` só mostra o QR; a URL só com `--mostrar-url`).
+- **Origem da PWA**: quem a controla controla o cliente (§0.1). Servir de origem dedicada,
+  sem scripts de terceiros, e com a CSP liberando só o relay em `connect-src`.
+- **PC (entrega 2)**: qualquer processo do mesmo usuário alcança o controle local; antes de
+  habilitar terminais no PC, a confirmação do pareamento exigirá Windows Hello (ou outra
+  interação do sistema) no processo que decide (§0.1).
+- **Backup**: restaurar `aparelhos.json` antigo é detectado (`lista-versao.json`) e não
+  reautoriza revogados (`revogados.jsonl`); restaurar o diretório inteiro desfaz isso (§0.1).
+- **Relay (etapa 2)**: aplicar a tabela de papéis (7.2), sobrescrever `de`, limitar taxa e
+  tamanho antes de analisar JSON, guardar só ID/SPKI dos nós e a última lista de cada um.
+- **PWA (etapa 4)**: ler o fragmento e apagá-lo do histórico; gerar a chave com
+  `gerarIdentidade({tipo:'aparelho'})` e guardar o `CryptoKey` no IndexedDB; CSP estrita.
+- Assinaturas ECDSA não são determinísticas e são maleáveis (`s` ↔ `n−s`); o protocolo
+  nunca usa assinatura como identificador nem como proteção contra repetição (para isso
+  existem `seq`, contador, nonce de desafio e uso único).