🕵 GBR: P2P Crypto Library

*Fonte Única de Verdade (SSoT)* para o empacotamento CBOR determinístico e assinaturas Ed25519 no ecossistema P2P leam-BR.

Rust native core: Rust native core p/ criptografia isolada do FFI, permitindo utilizar outras linguagem e a mesma implementação de criptografia para qualquer nó P2P Gleam-BR.
Rust native FFI: Gleam/Erlang FFI acessando Rustler NIF contendo funções wrappers p/ o *gbrcryptocore*.

Visão: A Fonte Única de Verdade (Single Source of Truth) O `gbr_crypto` é o pilar de segurança do SO Distribuído, fornecendo determinismo absoluto e identidade zero-trust. Nele, a matemática da criptografia garante que as interações entre Agentes e Provedores sejam autênticas, privadas e imutáveis.

Futuro: Pesquisa e Fronteira Criptográfica

[ ] *Primitivas Pós-Quânticas (PQC):* Investigação de algoritmos resistentes a computação quântica (ex: Kyber/Dilithium).
[ ] *Zero-Knowledge Proofs (ZKPs):* Estudo de provas de conhecimento zero para validação de canal de estado sem revelar saldos privados.
[ ] *Assinaturas de Grupo:* Mecanismos para validação coletiva de oráculos ou governança de malha.

Build

# build all
just clean
just build

# ou somente ./native/gbr_crypto_ffi

just clean-native
just build-native

Test

gleam test

ou,

cd native/gbr_crypto_core
cargo test

🚀 Objetivo

Garantir que a serialização de assinaturas digitais e vouchers financeiros sejam matematicamente idênticas em qualquer nó P2P da malha Gleam-BR.

⚠️ Regra de Ouro: Determinismo Absoluto

Para evitar falhas de consenso entre diferentes arquiteturas de CPU (ex: ARM vs x86), o uso de números de ponto flutuante (*Float/IEEE 754*) é TERMINANTEMENTE PROIBIDO em qualquer estrutura de dados que seja assinada.

*Padrão:* Matemática de Ponto Fixo (Inteiros).
*Escala:* Micro-unidades ($10^6$). Exemplo: 1.50 Tokens = 1_500_000.

📜 Contrato CBOR (Array Posicional)

Os vouchers são serializados como arrays CBOR estritos para evitar variações de ordenação de chaves.

PaymentPayload (Para Assinatura - 5 elementos)

[channel_id, nonce, agent_did, provider_did, amount]

SignedVoucher (Voucher Completo - 7 elementos)

[channel_id, nonce, agent_did, provider_did, amount, agent_sig, provider_sig]

channel_id: 32 bytes (Binary)
nonce: u64
agent_did: 32 bytes (PubKey)
provider_did: 32 bytes (PubKey)
amount: u64
agent_sig: 64 bytes (Signature)
provider_sig: 64 bytes (Signature)

🛡️ Segurança

*Zero Mutexes no Core:* Lógica puramente funcional e determinística.
*Dirty Schedulers:* NIFs de criptografia devem ser usados com cautela para não bloquear a BEAM (implementação atual foca na segurança).

SYSTEM CONTEXT: gbr_crypto (Universal Deterministic Cryptography)

1. PROJECT OBJECTIVE Biblioteca núcleo `gbr_crypto_core` em Rust puro. Este módulo é a "Fonte Única de Verdade" para a assinatura dupla (Dual-Signature Ed25519) e empacotamento CBOR no ecossistema `gleam-br`. O objetivo é garantir 100% de determinismo binário: não importa se o Agente é escrito em Python, JavaScript ou Gleam, o array CBOR gerado DEVE ser matematicamente idêntico bit a bit.

2. CORE ENGINEERING DIRECTIVES (CRITICAL) - RUST COMO NÚCLEO UNIVERSAL: O código fonte deve ser agnóstico. A arquitetura do repositório deve ter um core puro em Rust (`gbr_crypto_core`) e wrappers de compilação: `rustler` (para BEAM/Gleam), `wasm-bindgen` (para JS) e `pyo3` (para Python). - DETERMINISMO CBOR (STRICT POSITIONAL ARRAYS): É estritamente proibido utilizar estruturas de Mapa/Dicionário na serialização. O contrato financeiro deve ser empacotado usando a biblioteca `ciborium` (ou `serde_cbor` em modo estrito), forçando a criação de um Array posicional. - FORÇAR TIPAGEM DE INTEIROS: Para evitar discrepâncias entre linguagens de tipagem dinâmica (Python/JS), o Rust DEVE converter internamente todos os inteiros numéricamente críticos (ex: `amount`, `nonce`) para tipos fixos (ex: `u64`) ANTES de empacotar no CBOR. - ISOLAMENTO DE CHAVES PRIVADAS: A biblioteca deve receber a chave privada (Ed25519) da linguagem hospedeira como um array de bytes, assinar o pacote na memória segura do Rust e devolver apenas o SignedVoucher. A chave nunca deve ser persistida no estado do Rust.

3. THE FINANCIAL CONTRACT (DATA STRUCTURE) A biblioteca deve exportar uma função primária de assinatura que aceita os seguintes parâmetros brutos e constrói internamente a estrutura:

*Estrutura Alvo no CBOR (Obrigatoriamente nesta ordem):* [ Channel_ID (Bytes), Nonce (u64), Agent_DID (Bytes), Provider_DID (Bytes), Amount (u64), Agent_Signature (Option<Bytes>), Provider_Signature (Option<Bytes>) ]

4. CODING STANDARDS - Zero Panics. Qualquer falha de parsing ou criptografia deve retornar um tipo `Result::Err` capturável pela linguagem hospedeira. - Use a crate `ed25519-dalek` para as assinaturas criptográficas, pois é rápida, auditada e possui suporte nativo em Rust padrão e WASM `no_std`.

"Criptografia determinística para um mundo onde a confiança é calculada, não presumida." 🎯

🕵 GBR: P2P Crypto Library | Governança