cybercore-signer/docs/architecture.md

Arquitetura do CyberCore Signer

Especificação da Arquitetura Modular, Modelo de Threads e Fluxo Criptográfico

O CyberCore Signer foi concebido a partir de princípios de alta coesão, baixo acoplamento e estrito isolamento de camadas. O software é desenvolvido em Java 21+ LTS (Java 25 LTS), utilizando o runtime modular do JDK, JavaFX para a camada de apresentação e os provedores JCA/JCE da plataforma para operações criptográficas seguras.

---

1. Visão Geral da Arquitetura em Módulos

O projeto adota uma divisão modular rigorosa no Maven, garantindo que regras de negócio e algoritmos de criptografia nunca se acoplem a componentes visuais:

cybercore-signer/
├── modules/
│   ├── cybercore-core/         # Núcleo de criptografia, provedores, protocolo e segurança
│   ├── cybercore-ui/           # Interface gráfica JavaFX, diálogos nativos e System Tray
│   └── cybercore-app/          # Ponto de entrada (Main), bootstrap e empacotamento nativo
├── sdk/                        # SDK Web em JavaScript (@cybercore/signer-sdk)
├── scripts/                    # Scripts de build nativo jpackage para Windows e Linux
└── docs/                       # Especificações técnicas e manuais de integração

1.1 Módulo cybercore-core (Agnóstico de UI)

O módulo de núcleo é totalmente independente de JavaFX ou bibliotecas visuais:

• Domínio Imutável: Modelos imutáveis (ManagedCertificate, SigningContext, SigningResult, CertificateType, CertificateStatus).
• Serviços de Assinatura: SigningService orquestra a aplicação de algoritmos certificados (SHA256withRSA) delegando a operação ao provedor de certificado resolvido.
• Provedores de Certificados (CertificateProvider): Abstração que unifica:
  • Pkcs12CertificateProvider: leitura de arquivos .pfx/.p12 em memória com limpeza volátil de senha.
  • WindowsCertificateStoreProvider: integração com o repositório nativo do Windows (Windows-MY via SunMSCAPI/CNG).
  • Pkcs11CertificateProvider: integração direta com bibliotecas dinâmicas (DLL/SO) de drivers e tokens USB através do SunPKCS11.
• Protocolo e Rede Local: CcspServer escuta exclusivamente em 127.0.0.1:21325, fornecendo a API REST CCSP/1 com validação de origens e controle de concorrência.
• Segurança e Persistência: ApplicationRegistry, NonceManager (proteção anti-replay), OriginValidator, SmartCardSessionManager e AgentConfigurationService com armazenamento persistente em diretório de usuário (~/.cybercore/).
• Assinatura de Documentos e Validação: PdfSigningService (PAdES com salvamento incremental e carimbo TSA via PDFBox e Bouncy Castle), XmlSigningService (XAdES-BES e XMLDSig via javax.xml.crypto) e SignatureValidationService para conferência de integridade e signatários.

1.2 Módulo cybercore-ui (Apresentação JavaFX)

Responsável por toda a interação com o usuário:

• Interface Principal (MainAppView): Painel de navegação moderno com alternador dinâmico de tema (Claro/Escuro), grade de operações rápidas (PDF, XML, Assinatura Atachada, Designer de Selos, Validar Assinatura, Sair do Agente) e coluna lateral de utilitários (Logs em tempo real, Configurações, Tutorial, Certificados e Sobre).
• Diálogos de Consentimento e PIN: Modais nativos de aprovação visual para requisições do protocolo CCSP/1 (SignatureConfirmationDialog, ApplicationAuthorizeDialog) e coleta segura de PIN de tokens (A1PasswordDialog).
• Designer de Selos Digitais (SealDesignerDialog): Ferramenta com Live Preview para criação de selos visuais com controle de cores, estilo de brasão, exibição de nome completo sem truncamento e privacidade de CPF.
• Bandeja do Sistema (System Tray): Execução minimizada com menu de contexto rápido para restauração da tela ou encerramento da sessão.

1.3 Módulo cybercore-app (Orquestração e Bootstrap)

Ponto de partida da aplicação (CyberCoreApp):

• Processa argumentos de linha de comando (--dev, --headless).
• Executa rotinas de diagnóstico pré-inicialização do ambiente Java e disponibilidade criptográfica.
• Inicia o CcspServer em segundo plano e abre a interface gráfica na JavaFX Application Thread.
• Empacota o executável consolidado via maven-shade-plugin e orquestra o build nativo via jpackage.

---

2. Modelo de Threads e Concorrência

Para manter a interface gráfica sempre fluida e ágil, o CyberCore Signer utiliza um particionamento rígido de threads:

graph TD
    subgraph UI Layer
        JFX[JavaFX Application Thread]
    end
    
    subgraph Local Protocol Layer
        HTTPPool[CcspServer Worker Pool (FixedThreadPool 8)]
    end
    
    subgraph Background Services
        Watcher[SmartCardWatcher Thread (PC/SC Loop)]
        AsyncTasks[JavaFX Task / CompletableFuture Workers]
    end
    
    subgraph Hardware Critical Section
        Lock[Trava Serializada FIFO: signLock]
        Hardware[Token Físico A3 / SmartCard Driver]
    end

    HTTPPool -->|Solicita Aprovação Visual| JFX
    JFX -->|Consentimento Concedido| HTTPPool
    HTTPPool --> Lock
    AsyncTasks --> Lock
    Lock --> Hardware

1. JavaFX Application Thread: Dedicada exclusivamente à renderização da interface e tratamento de eventos visuais. Nenhuma operação criptográfica, leitura de disco ou chamada de rede é executada nesta thread.
2. CcspServer Worker Pool: Pool de 8 threads daemon dedicadas ao atendimento de requisições HTTP da API REST CCSP/1.
3. SmartCardWatcher Thread: Thread daemon isolada que executa cardTerminal.waitForCardPresent() e waitForCardAbsent() para monitorar hardware PC/SC sem onerar a CPU.
4. Trava Serializada FIFO (signLock): Implementada via ReentrantLock(true). Garante que operações de assinatura em cartões inteligentes físicos sejam enfileiradas ordenadamente, prevenindo falhas de hardware e estados corrompidos em drivers de fabricantes mono-thread.

---

3. Fluxo de Dados e Assinatura Descentralizada por Digest

A arquitetura do CyberCore Signer prioriza a privacidade e o modelo de assinatura por digest:

sequenceDiagram
    autonumber
    actor Usuario as Usuário
    participant Web as Aplicação Web (SDK)
    participant CCSP as CcspServer (127.0.0.1)
    participant UI as CyberCore JavaFX
    participant Crypto as SigningService & Providers

    Web->>CCSP: POST /ccsp/v1/sign (digest, appId, certHint, nonce, expires_at)
    CCSP->>CCSP: Valida autorização, nonce anti-replay e integridade do digest
    CCSP->>UI: Solicita confirmação visual (requestSignatureConfirmation)
    UI->>Usuario: Exibe Diálogo Nativo (Nome do Documento, Hash SHA-256, Certificado)
    Usuario->>UI: Clica em "Autorizar Assinatura" (e digita PIN se requerido)
    UI-->>CCSP: Confirmação concedida
    CCSP->>Crypto: sign(SigningContext) sob signLock.lock()
    Crypto->>Crypto: JCA/JCE Signature.update(digest) + sign()
    Crypto-->>CCSP: SigningResult (signatureBytes, certChain)
    CCSP-->>Web: 200 OK JSON { status: "signed", signature: "Base64", certificate: "Base64" }

---

4. Persistência de Dados e Configurações

Todos os dados de configuração e personalizações do usuário são armazenados no diretório do usuário no sistema operacional:

• Diretório Base: ~/.cybercore/ (ou %USERPROFILE%\.cybercore\ no Windows).
• config.json: Configurações globais do agente (política de cache de PIN, tema padrão, selo padrão ativo).
• authorized-apps.json: Registro de aplicações web autorizadas pelo usuário, contendo application_id, nome amigável e data da aprovação.
• seals/*.json: Selos visuais SVG personalizados criados ou importados pelo usuário no designer de selos.