GBR: ADR-0003 Arquitetura "Shadow Token" para Interoperabilidade com Sistemas Legados

• *Status:* Proposto -> (Aceito)
• *Data:* 2026-05-12

*Contexto:*

A matemática ZCAP-LD é invisível para bancos de dados antigos e diretórios corporativos (LDAP/Active Directory), que operam com sessões estatais ou tokens legados. O GleamBR/Monitor v2.0 precisa consultar o banco de dados do cliente sem quebrar a postura Zero-Trust.

O sistema deve falar com o "mundo sujo" (Legacy). O Agente de borda torna-se um alvo (HVT) pois guarda segredos corporativos (senhas de banco) na RAM.

*Decisão:*

O Agente atua como *Tradutor & Validador Semântico. Os segredos são isolados em *Enclaves Rust (NIF Resources)**. Utilizamos mlock() para impedir Swap em disco e Opaque Types no Gleam para impedir vazamento em logs (Fator Humano).

1. *Enclave Tradutor:* O Agente de borda (Monitor v2.0) atuará como um "Tradutor Juramentado". Ele recebe o ZCAP-LD, valida a sua integridade e escopo.
2. *Credenciais JIT (Just-In-Time):* Após validação do ZCAP-LD, o Agente utilizará credenciais de serviço armazenadas em um estado opaco (isolado na BEAM) para solicitar um token de sessão curto ou realizar a query direta no sistema legado (ex: conexão JDBC ou proxy reverso).
3. *Blindagem do Segredo:* Sob nenhuma circunstância as credenciais corporativas legadas ou os tokens emitidos por elas viajarão pela malha P2P Yamux. Elas nunca abandonam a memória RAM do Agente de borda no cliente.

*Consequências:*

• *Positivas:* Viabiliza a venda do produto GleamBR/Monitor v2.0 para grandes empresas sem necessidade de reescrita da sua infraestrutura; protege a rede P2P da contaminação com arquiteturas legadas.

• *Positivas:* Interoperabilidade segura com sistemas legados. Proteção contra memory dumps e erros de desenvolvedores juniores.

• Negativas: O Agente de borda torna-se um alvo de alto valor (HVT - High Value Target) para atacantes locais buscando extrair o estado opaco da memória. (Mitigado)

Análise da Negativa

Quando o Agente atua como "Tradutor Juramentado", ele se torna o guardião do segredo corporativo. Vamos dissecar as entranhas deste risco, entender como um atacante pensa e construir a blindagem necessária para mitigá-lo de forma implacável.

1. A Autópsia da Ameaça: Por que o Agente é um "HVT" (High-Value Target)?

No mundo ZCAP-LD, se um atacante roubar uma mensagem, ele só vê matemática inútil. Mas para o Agente GleamBR/Monitor v2.0 "traduzir" essa matemática e abrir uma conexão JDBC com o banco Oracle do cliente, ele *precisa ter a senha do banco de dados na sua memória (RAM)*.

Se um atacante interno (um funcionário mal-intencionado ou um malware no servidor) focar os ataques na máquina onde o Monitor v2.0 roda, ele tentará extrair esse segredo de três formas:

Vetor 1: O "Memory Dump" (Extração de RAM)

O atacante com privilégios de root (ou explorando uma vulnerabilidade do SO) usa ferramentas para ler a memória física do processo (/proc/kcore no Linux) e extrair a string da senha em texto plano.

Vetor 2: O Calcanhar da Erlang VM (erl_crash.dump)

A BEAM (nossa Erlang VM) é famosa pelo "Let it Crash". Quando um nó sofre um pânico irreversível, ele gera um arquivo de texto gigante chamado erl_crash.dump. Este arquivo contém *o estado de todos os processos no momento do crash*. Se a senha do banco estava no estado do Ator OTP, ela é gravada em texto plano no disco.

Vetor 3: Paging / Swap File

Se o servidor estiver sem memória, o Linux pega páginas da RAM (que podem conter a nossa senha) e as escreve no disco (Swap). Um atacante que roubar o disco rígido, mesmo com a máquina desligada, pode ler o arquivo de paginação e encontrar a senha.

2. A Blindagem de Titânio: Estratégias de Mitigação

Nós não podemos eliminar o risco totalmente (pois o legado exige o segredo), mas podemos torná-lo tão difícil e restrito que o custo do ataque supere o valor do dado. Aplicaremos *Defesa em Profundidade*:

Nível 1: Mitigação Específica da BEAM (Software)

• *Ofuscação de Estado OTP:* No Gleam/Erlang, não guardaremos a credencial como uma String simples no estado do Ator. Vamos customizar a função format_status do comportamento OTP (via FFI Erlang) para que, caso o estado seja inspecionado ou ocorra um crash, a credencial seja substituída pela string [REDACTED].
• *Desativação de Crash Dumps Completos:* O Monitor v2.0 em produção será configurado via variáveis de ambiente (ERL_CRASH_DUMP_BYTES=0) para nunca escrever dados de memória em disco durante uma falha crítica.

Nível 2: Mitigação Criptográfica via Rustler (Memória Segura)

• **Uso de mlock():** O segredo legado não ficará na memória gerenciada pelo Garbage Collector da BEAM. Ele viverá dentro de um Enclave no nosso gbr_crypto (NIF em Rust). O código Rust usará bibliotecas como secrecy e a chamada de sistema mlock() para "trancar" essa região da memória, proibindo o Sistema Operacional de movê-la para o Swap (disco).
• *Zeroization (Expurgo Automático):* Quando o ZCAP-LD expirar ou a tarefa BPMN terminar, o NIF Rust sobrescreve a região da memória com zeros de forma determinística antes de liberá-la.

Nível 3: A Solução de Classe Enterprise (Dynamic Secrets)

Se o cliente for uma grande corporação (banco/governo), o Agente Monitor *não guardará a senha real do banco de dados*.

• Ele será integrado a um cofre de segredos como o *HashiCorp Vault*.
• O Agente usa o ZCAP-LD para pedir ao Vault: "Me dê uma senha para o Banco X que dure apenas 5 minutos".
• Mesmo que o atacante consiga fazer o memory dump do Agente e roubar a credencial, quando ele for usá-la, ela já terá expirado.

3. Veredito para o ADR

O risco é alto, mas as mitigações que a combinação *Gleam (OTP) + Rust (NIFs)* nos proporciona são de padrão militar.

*Atualização do Status do Risco no ADR:*

• *Negativa Original:* "O Agente de borda torna-se um alvo de alto valor (HVT)…"
• *Tratamento do Risco:* *MITIGADO (Risco residual aceito).*
• *Medidas Incorporadas:* 1. Credenciais residem estritamente em Enclaves Rust com proteção anti-swap (mlock). 2. Implementação de format_status no OTP para ocultação em logs e Crash Dumps desativados. 3. Adoção prioritária de credenciais efêmeras (Just-In-Time) gerenciadas via Cofres Externos (Vault) em ambientes de missão crítica.