GBR: ADR-0001 Autorização Descentralizada via ZCAP-LD e Compressão CBOR

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

*Contexto:*

Uma vez autenticado, o usuário precisa autorizar o Agente (Edge/Monitor) a agir em seu nome na rede. Sistemas centralizados (OAuth2) falham em ambientes offline-first ou altamente particionados.

Autorização em redes P2P não pode depender de servidores centrais. O uso de JSON-LD puro é "obeso" para pacotes TCP/MTU.

*Decisão:*

Utilizar ZCAP-LD (Authorization Capabilities) para delegação de poder. A obesidade do JSON é mitigada via DAG-CBOR e a validação é Stateful (feita uma vez por stream Yamux), eliminando o tráfego redundante de certificados.

*Autorização via Capabilities (ZCAP-LD):* Em vez de solicitar acesso a um servidor central a cada ação, o sistema gerará um objeto JSON-LD assinado pela Passkey do usuário, delegando autoridade ao did:key do Agente.
*Validação Autônoma:* Qualquer Agente receptor (Nó Oráculo, Nó Banco de Dados) validará a assinatura P-256 localmente (via gbr_crypto Rustler NIF), sem depender de um Ponto Único de Falha (SPOF).
*Atenuação de Escopo (Caveats):* As delegações zcap-ld terão vida curta (ex: 30 dias) e escopo restrito (read:telemetry, execute:bpmn), garantindo o Princípio do Menor Privilégio.

*Consequências:*

*Positivas:* Autorização O(1) com tolerância total a partições de rede; arquitetura Zero-Trust real; Autorização offline-first e soberana; Eficiência de banda comparável a protocolos binários puros.
Negativas: Adiciona peso ao payload das mensagens P2P devido ao tamanho dos certificados JSON-LD. (Mitigdo)

Análise do ponto negativo

1. A Autópsia do JSON-LD: Por que ele é "Obeso"?

Quando pensamos em uma permissão, imaginamos algo simples como {"user": "paulo", "role": "admin"} (35 bytes). Mas o *ZCAP-LD (Authorization Capabilities for Linked Data)* é um documento criptográfico auto-contido projetado para não depender de bancos de dados. Para isso, ele carrega muito contexto semântico.

Veja a anatomia real de uma delegação ZCAP-LD básica:

{
  "@context": ["https://w3id.org/security/v2", "https://w3id.org/zcap/v1"],
  "id": "urn:uuid:3b...8c",
  "parentCapability": "did:key:z6MkhaXg1...",
  "invoker": "did:key:z6Mkk7yqn...",
  "caveats": [
    {
      "type": "ExpiryCaveat",
      "expires": "2026-06-11T20:00:00Z"
    },
    {
      "type": "AllowedActionCaveat",
      "actions": ["read:telemetry"]
    }
  ],
  "proof": {
    "type": "Ed25519Signature2018",
    "created": "2026-05-11T20:00:00Z",
    "verificationMethod": "did:key:z6MkhaXg1...#z6MkhaXg1...",
    "proofPurpose": "capabilityDelegation",
    "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..a_long_base64_string_representing_the_signature..."
  }
}

*O Peso Físico:*

Um único certificado como este pesa entre *800 bytes e 1.5 KB* em texto plano. Se você tiver uma cadeia de delegação (O CEO autorizou o Diretor, que autorizou o Agente), o Agente precisa enviar a cadeia inteira para provar a origem. Uma cadeia de 3 níveis pode bater *4 KB*.

2. O Choque com a Física (A Malha P2P)

No mundo das APIs REST (HTTP/2), enviar 4 KB no cabeçalho Authorization é feio, mas tolerável. No mundo do GleamBR/Monitor v2.0 (Telemetria M2M), é *catastrófico*.

*O Limite MTU do TCP:* A maioria das redes Ethernet tem um MTU (Maximum Transmission Unit) de *1500 bytes*.
*A Fragmentação:* Se o seu pacote P2P contiver 50 bytes de métrica de CPU + 4000 bytes de ZCAP-LD + Overhead do Noise (Criptografia), o sistema operacional terá que quebrar esse pacote em 3 ou 4 pacotes TCP menores.
*O Colapso de Throughput:* Se o Monitor envia 1.000 métricas por segundo, enviar o ZCAP-LD junto com cada métrica faria a banda pular de 50 KB/s para *4 MB/s* apenas de lixo de autorização! A latência dispara, o Edge engasga e o cliente Horus cancela o contrato.

3. A Engenharia de Mitigação (O Cartório de Titânio)

Nós não vamos aceitar esse risco passivamente. A nossa arquitetura Hexagonal e o poder da Erlang VM nos dão três salvaguardas que transformam esse elefante (JSON-LD) numa formiga:

A) Compressão Binária (CBOR-LD)

Como decidimos no *ADR-038, não trafegaremos JSON na malha. Utilizaremos o DAG-CBOR. O padrão *CBOR-LD** comprime URIs repetitivas (como os links do @context) e transforma chaves de texto em inteiros (tags). Aqueles 1.5 KB caem drasticamente para cerca de *300-400 bytes*.

B) Autorização Stateful (A Mágica do Yamux + OTP)

Esta é a nossa grande arma. Nós *não* enviaremos a Capability a cada mensagem.

*O Handshake:* Quando o Agente A quer mandar métricas para o Gateway B, ele abre um Stream Yamux. No primeiro frame deste stream, ele envia um pacote de AuthInit contendo o ZCAP-LD (comprimido).
*O Estado do Ator:* O Nó B recebe, valida a assinatura P-256 e as datas de expiração. Se for válido, o Ator OTP (o piper do túnel) salva no seu estado: Authorized = True.
*O Silêncio:* A partir daí, pelos próximos 10 milhões de pacotes de métricas enviados naquele stream, *não vai nenhum byte de autorização*. A validação é vinculada ao ciclo de vida da conexão/stream, e não ao pacote.

C) Referência por CID (GossipSub caching)

Se uma Capability for realmente gigante (muitas restrições corporativas), o Agente A nem envia o conteúdo. Ele envia apenas o Hash de 32 bytes (CID): Auth: <CID>. O Nó B olha no seu DuckDB/Cache. Se não tiver aquele CID, ele pede ao Nó A. Se já tiver (porque o Nó A fofocou isso no GossipSub antes), a autorização ocorre instantaneamente sem trafegar o documento novamente.

Veredito Final para o ADR

A negativa do ADR é um perigo real e fatal para sistemas ingênuos, mas na arquitetura Gleam-BR, nós a esmagamos na camada de design de rede.

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

*Negativa Original:* "Adiciona peso ao payload das mensagens P2P…"
*Tratamento do Risco:* *MITIGADO*. O peso excessivo é neutralizado por: 1. Serialização DAG-CBOR. 2. Validação por Sessão (Stateful Stream Authorization no Yamux), evitando o envio redundante de atestados por pacote. 3. Resolução via Cache de CIDs na borda.

GBR: ADR-0001 Autorização Descentralizada via ZCAP-LD e Compressão CBOR | Wiki