cybercore-signer/docs/architecture.md

Arquitetura do CyberCore Signer

O CyberCore Signer é um agente desktop nativo desenvolvido em Java 21+ LTS (Java 25 LTS) com interface JavaFX e segurança criptográfica JCA/JCE pura, projetado para permitir que aplicações web autorizadas solicitem assinaturas digitais ICP-Brasil padrão A1 e A3 diretamente da máquina do usuário.

---

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

O projeto adota uma arquitetura desacoplada em múltiplos módulos Maven independentes:

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 cybercore-core

• Domínio: Modelos imutáveis como ManagedCertificate, SigningContext, SigningResult, CertificateType e CertificateStatus.
• Criptografia: SigningService e DigestAlgorithm utilizando exclusivamente os provedores padrão JCA/JCE (sem reimplementação manual de algoritmos).
• Provedores: Abstração CertificateProvider com implementações:
  • Pkcs12CertificateProvider: leitura de arquivos .pfx/.p12 em memória protegida.
  • WindowsCertificateStoreProvider: integração nativa com o repositório de chaves do Windows (Windows-MY via SunMSCAPI/CNG).
  • Pkcs11CertificateProvider: integração com drivers de middleware e tokens USB/Smartcards via SunPKCS11.
• Protocolo & Rede Local: CcspServer escuta estritamente em 127.0.0.1:21325, fornecendo a API REST CCSP/1.
• Segurança & Configurações: ApplicationRegistry, NonceManager (proteção anti-replay), OriginValidator, SmartCardSessionManager e AgentConfigurationService (persistência em ~/.cybercore/config.json).
• Validação Criptográfica: SignatureValidationService com suporte a Assinaturas Incorporadas (PAdES PDF, CMS/P7M com conteúdo embutido, XMLDSig) e Assinaturas Destacadas (Detached CMS/P7S).
• Selos Visuais Personalizados: CustomSealStorage (persistência em ~/.cybercore/seals/), PdfSealThemeRegistry dinâmico e CpfDisplayMode (privacidade LGPD).

1.2 cybercore-ui

• Interface desenvolvida com JavaFX 25, empregando layout moderno e simétrico de grade 3x3 de operações e coluna lateral de utilitários:
  • MainAppView: grade 3x3 otimizada:
    • Linha 0: Assinar PDF, Assinar XML, Assinatura Atachada
    • Linha 1: Co-Assinar Documento, Carimbo do Tempo, Gerenciar Selos
    • Linha 2: Validar Assinatura, Validar Carimbo, Sair do Agente
  • SealDesignerDialog: criador e instalador de selos digitais personalizados com pré-visualização ao vivo (Live Preview), seletores de cores, estilos de emblema, obrigatoriedade de nome completo, controle de mascaramento de CPF e estampa de data/hora.
  • SignatureValidationDialog: diálogo de validação criptográfica real com alternância entre Assinatura Incorporada e Assinatura Destacada, extração de documento embutido e relatório de signatários.
  • PdfSignDialog: modal de assinatura PAdES com posicionamento por clique na folha, atalho direto para criar/instalar selos e opções dinâmicas de CPF/data-hora.
  • SettingsView: configurações gerais persistentes, política de PIN e gerenciamento de selos instalados.

1.3 cybercore-app

• Main bootstrap (CyberCoreSignerApplication).
• Tratamento de parâmetros de inicialização (--dev, --headless).
• Execução de diagnósticos preliminares de ambiente e engine criptográfica antes do início das threads de escuta.
• Geração de Fat JAR autocontido via maven-shade-plugin e preparação para distribuição jpackage.

---

2. Fluxo de Dados e Princípio de Menor Privilégio

O CyberCore Signer opera sob o modelo de assinatura descentralizada por digest:

1. A aplicação web calcula o hash criptográfico SHA-256 no próprio navegador utilizando a Web Crypto API nativa.
2. Apenas o hash Base64 de 32 bytes trafega localmente para o CyberCore Signer.
3. O documento completo nunca sai do navegador e a chave privada nunca sai do computador ou do hardware do usuário.

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)
    CCSP->>CCSP: Valida autorização, nonce anti-replay e digest
    CCSP->>UI: Solicita confirmação visual (requestSignatureConfirmation)
    UI->>Usuario: Exibe Diálogo (Hash, Certificado, Aplicação)
    Usuario->>UI: Aprova assinatura (e insere PIN se A3)
    UI-->>CCSP: Confirmação concedida
    CCSP->>Crypto: sign(SigningContext) [Trava FIFO]
    Crypto->>Crypto: JCA/JCE Signature.update(digest) + sign()
    Crypto-->>CCSP: SigningResult (signatureBytes, certChain)
    CCSP-->>Web: JSON { status: "signed", signature: "...", certificate: "..." }