O Governance System é uma plataforma de governança institucional e identidade digital, projetada para operar em cenários de DAO, Web3 e RWA (Real World Assets).
- 1. Introdução
- 2. Visão Geral do Sistema
- 3. Arquitetura Geral
- 4. Stack Tecnológica
- 5. Identidade como Núcleo do Sistema
- 6. Authentication Assurance Levels (AAL)
- 7. Fluxos de Autenticação e Credenciais
- 8. Arquitetura de Integração Web3
- 9. Estratégia de Dados
- 10. Auditoria, Logs e Compliance
- 11. Modelo de Ameaças (STRIDE)
- 12. Diagrama de Arquitetura
- 13. Estrutura do Repositório
- 14. Configuração e Setup
- 15. Status do Projeto
- 16. Considerações Finais
O Governance System é uma plataforma de governança institucional e identidade digital, projetada para operar em cenários de DAO, Web3 e RWA (Real World Assets).
Mais do que um sistema de votação ou gestão administrativa, este projeto implementa um Identity Provider (IdP) soberano, com segurança de nível financeiro, compliance jurídico e rastreabilidade completa.
- 🏛️ Sustentar governança descentralizada (DAO)
- 🌱 Operar em contextos de cooperativismo
- 🧾 Atender requisitos de compliance e auditoria
- 🦊 Integrar identidade Web3 (SIWE) com Web2 tradicional
- 🛡️ Garantir segurança bancária (MFA, sessões rastreáveis)
O sistema foi concebido para priorizar latência mínima, escalabilidade global e simplicidade operacional.
A plataforma é desenhada para suportar operações que exigem um alto grau de confiança e verificação, adequadas para ambientes corporativos e regulados.
Toda a arquitetura roda no edge da Cloudflare, garantindo performance e segurança distribuídas globalmente.
O Governance System utiliza uma arquitetura Jamstack + Edge Computing, com separação clara entre interface, identidade, governança e persistência de dados.
A arquitetura é dividida em camadas lógicas para garantir manutenibilidade e escalabilidade. * Interface (Front-end): SPA em React + TypeScript. * Edge / Backend: Cloudflare Workers como API serverless. * Identidade (IdP): Núcleo de autenticação e autorização. * Governança: Módulos de votação e gestão. * Persistência de Dados: Solução híbrida com D1, R2 e IPFS.
- SPA em React + TypeScript
- Material-UI (MUI) para UI responsiva e acessível
- Cloudflare Pages para servir o front-end
- Cloudflare Workers como API serverless
- Cloudflare KV (Workers KV) para cache de ultra-baixa latência:
- Nonces de autenticação (SIWE)
- Sessões revogadas
- Preços e estados temporários de ativos (RWA)
- Autenticação por email/senha
- MFA / TOTP (Google Authenticator, Authy, etc.)
- Web3 SIWE (Sign-In with Ethereum)
- Sessões rastreáveis com fingerprint heurístico
- Cloudflare D1 (SQLite serverless): dados relacionais, perfis, sessões e logs
- Cloudflare R2 (Object Storage): documentos KYC e arquivos privados
- IPFS (InterPlanetary File System): metadados imutáveis de ativos RWA e propostas da DAO
- Logs forenses de todas as ações críticas
- Trilhas auditáveis para compliance e disputas jurídicas
A identidade é o eixo central da arquitetura. Todas as ações — governança, votos, movimentações, permissões — partem de um usuário autenticado, auditável e com nível de garantia de autenticação (AAL) conhecido.
- Contas Tradicionais: email + senha
- Contas Web3: carteiras Ethereum
- Contas Híbridas: email + wallet
- Múltiplas Carteiras (1:N): Um usuário pode vincular várias carteiras.
Todas as ações críticas geram logs forenses, garantindo uma trilha auditável completa.
O sistema adota níveis formais de garantia de autenticação, permitindo controle de risco e governança baseada em identidade.
| Nível | Descrição | Requisitos |
|---|---|---|
| AAL1 | Identidade Básica | Email + senha verificada |
| AAL2 | Identidade Forte | Email + senha + MFA/TOTP |
| AAL3 | Identidade Institucional | MFA + Wallet vinculada + KYC aprovado |
Cada ação sensível (voto, emissão de ativo, proposta, admin) exige um AAL mínimo configurável.
- Usuário informa email e senha.
- Senha é armazenada usando hash forte (Argon2id).
- Token de verificação com expiração curta é enviado ao email do usuário.
- JWT de curta duração.
- Refresh token com rotação obrigatória (one-time-use).
- Geração de segredo TOTP para apps como Google Authenticator.
- Validação dupla antes de ativação.
- Geração de nonce via Workers KV.
- Assinatura SIWE pela wallet.
- Persistência do vínculo User ↔ Wallet.
- Upload de documentos (R2).
- Aprovação manual ou automatizada.
- Elevação do nível de garantia do usuário.
Esta seção detalha a integração com o ecossistema Web3, incluindo a gestão de carteiras e a validação de assinaturas.
O sistema adota uma estratégia que equilibra privacidade, performance e transparência pública.
- O quê: Emails, senhas, documentos pessoais e status KYC.
- Tecnologia: Cloudflare D1 + R2.
- Proteção: Criptografados e protegidos por controle de acesso.
- O quê: Sessões revogadas, nonces de login Web3, cotações e estados temporários de ativos.
- Tecnologia: Cloudflare Workers KV.
- O quê: Metadados de ativos RWA, propostas e resultados finais de votações.
- Tecnologia: IPFS.
- Garantia: Cada publicação no IPFS gera um CID (Content Identifier) que prova matematicamente a imutabilidade do conteúdo.
Esta seção descreve a estratégia para garantir a rastreabilidade completa das ações e a conformidade com requisitos regulatórios.
| Categoria | Mitigação |
|---|---|
| Spoofing | MFA, SIWE, verificação de email |
| Tampering | IPFS (imutabilidade), hash criptográfico |
| Repudiation | Logs forenses e trilhas auditáveis |
| Information Disclosure | Criptografia, segregação de dados |
| Denial of Service | Rate limiting, edge caching |
| Elevation of Privilege | AAL mínimo por ação, roles explícitos |
| Categoria | Mitigação |
|---|---|
| Spoofing | MFA, SIWE, verificação de email |
| Tampering | IPFS (imutabilidade), hash criptográfico |
| Repudiation | Logs forenses e trilhas auditáveis |
| Information Disclosure | Criptografia, segregação de dados |
| Denial of Service | Rate limiting, edge caching |
| Elevation of Privilege | AAL mínimo por ação, roles explícitos |
graph TD
subgraph "Navegador do Usuário"
A[React App]
W[Wallet Web3]
end
subgraph "Cloudflare Edge"
B(Cloudflare Pages)
C(API Worker)
K[(Workers KV)]
end
subgraph "Camada de Identidade (IdP)"
C1[Auth Core]
C2[MFA / TOTP]
C3[Web3 SIWE]
C4[Compliance & KYC]
end
subgraph "Persistência Híbrida"
D[(Banco de Dados D1)]
E[(Storage R2)]
I((IPFS Network))
F[(Audit Logs)]
end
%% Fluxo principal
B -- Serve o App --> A
A -- Requisições HTTP --> C
C -- Checa Sessão / Nonce --> K
C --> C1
%% Auth & Segurança
C1 -- Sessões / Usuários --> D
C1 -- Eventos --> F
%% MFA
C1 --> C2
C2 -- Validar Código --> D
C2 -- Eventos --> F
%% Web3
W -- Assinatura --> C3
C3 -- Valida Nonce --> K
C3 -- Wallets / Users --> D
C3 -- Eventos --> F
%% Compliance
C1 --> C4
C4 -- Status KYC / Termos --> D
C4 -- Upload Docs --> E
C4 -- Eventos --> F
%% RWA & DAO (Imutabilidade)
C -- Metadados RWA / Propostas --> I
I -. CID .-> D
src/
├── db/
│ └── schema.ts # Users, Sessions, Wallets, Audit Logs
├── routes/
│ └── core/auth/
│ ├── index.ts # Login, Refresh, Logout
│ ├── session.ts # /me, Perfil
│ ├── password.ts # Recuperação de senha
│ ├── mfa.ts # MFA / TOTP
│ ├── web3.ts # SIWE & Wallets
│ ├── compliance.ts # Termos & KYC
│ └── admin.ts # Roles & Banimento
├── services/
│ └── audit.ts # Logger global de auditoria
└── utils/
└── auth-guard.ts # Middleware de autenticação
- Node.js v24+
- pnpm v10+
- Wrangler CLI
JWT_SECRET=super_secret_key
REFRESH_TOKEN_SECRET=another_secret
R2_BUCKET_NAME=governance-docs
🟡 Em desenvolvimento ativo — arquitetura de identidade consolidada, pronta para ambientes regulados, DAOs e tokenização de ativos.
Este repositório implementa um núcleo soberano de identidade e governança institucional para Web2 + Web3.