250 lines
9.9 KiB
Markdown
250 lines
9.9 KiB
Markdown
---
|
|
trigger: always_on
|
|
---
|
|
|
|
PROMPT MESTRE — CYBERCORE SIGNER
|
|
|
|
Você é responsável pelo desenvolvimento do CyberCore Signer, um agente desktop Java para Windows que permite aplicações web autorizadas solicitar assinaturas digitais usando certificados instalados/localmente disponíveis na máquina do usuário.
|
|
|
|
1. REGRA DE DESENVOLVIMENTO
|
|
|
|
Siga sempre: ANALISAR → PLANEJAR → AUTORIZAR → IMPLEMENTAR → VALIDAR.
|
|
|
|
Antes de alterar qualquer código, analise o repositório real, sua estrutura, dependências, configurações, padrões, documentação e testes. Não invente arquivos, classes ou arquitetura existentes.
|
|
|
|
Na fase de análise, não altere o projeto. Depois apresente o plano e aguarde autorização explícita para implementar.
|
|
|
|
Se durante a implementação surgir mudança relevante de escopo, pare e peça nova autorização.
|
|
|
|
Ao finalizar, informe arquivos alterados/criados, dependências, decisões arquiteturais, testes executados, limitações e pendências.
|
|
|
|
2. TECNOLOGIA
|
|
|
|
Use Java 21+ LTS, Maven ou Gradle conforme o projeto, JavaFX para a interface e JCA/JCE para criptografia.
|
|
|
|
Use X.509, KeyStore/PKCS12 e PKCS#11 conforme necessário. Use SunPKCS11 quando apropriado e Bouncy Castle somente quando houver necessidade real.
|
|
|
|
O aplicativo deve ser empacotado com runtime próprio, preferencialmente via jpackage, sem exigir Java instalado pelo usuário.
|
|
|
|
Windows 10/11 é o alvo inicial; mantenha a arquitetura preparada para macOS/Linux.
|
|
|
|
3. ARQUITETURA
|
|
|
|
Separe responsabilidades em módulos/componentes coerentes, sem criar módulos artificiais. A arquitetura deve permitir evolução e testes independentes.
|
|
|
|
Crie abstrações para descoberta e uso de certificados, por exemplo CertificateProvider, com implementações para A1, Windows Certificate Store e PKCS#11 quando aplicável.
|
|
|
|
CertificateManager deve centralizar descoberta, validade, subject, issuer, algoritmo, disponibilidade da chave privada e seleção do provider.
|
|
|
|
SigningService deve executar a assinatura por JCA/JCE e providers; nunca implemente criptografia própria.
|
|
|
|
Mantenha o núcleo independente de fabricantes.
|
|
|
|
4. A1
|
|
|
|
Suporte certificados .PFX/.P12.
|
|
|
|
A chave privada permanece exclusivamente na máquina. A senha nunca deve ser enviada ao servidor nem aparecer em logs.
|
|
|
|
Trate certificado válido, expirado, inválido, senha incorreta, ausência de chave privada e algoritmos não suportados.
|
|
|
|
Se houver persistência de credenciais, use armazenamento seguro do sistema operacional.
|
|
|
|
5. A3 / PKCS#11
|
|
|
|
Suporte tokens USB, smart cards, leitores e middleware compatíveis com PKCS#11, além de cenários Windows CSP/CNG/KSP quando necessários.
|
|
|
|
Detecte slots, tokens, certificados e chaves disponíveis.
|
|
|
|
Trate token ausente/removido, middleware/provider indisponível, PIN requerido/incorreto, timeout e falhas do dispositivo.
|
|
|
|
Nunca armazene ou envie PIN. Nunca implemente sua própria camada PKCS#11: utilize APIs/providers existentes.
|
|
|
|
Não assuma que todos os A3 funcionam da mesma forma; use adapters/providers sem acoplar o núcleo a um fabricante.
|
|
|
|
6. ASSINATURA
|
|
|
|
Priorize o modelo em que a aplicação web calcula o digest e o CyberCore assina localmente apenas esse digest.
|
|
|
|
Exemplo: documento → SHA-256 → digest → CyberCore → certificado A1/A3 → assinatura.
|
|
|
|
A chave privada nunca sai da máquina.
|
|
|
|
Valide algoritmo, tamanho/formato do digest, certificado e capacidade do provider antes da operação.
|
|
|
|
7. PROTOCOLO CCSP
|
|
|
|
Defina o CyberCore Signing Protocol (CCSP), versão inicial CCSP/1.
|
|
|
|
Toda requisição deve possuir request_id UUID, application_id, operação, algoritmo, digest, indicação opcional do certificado e expiração.
|
|
|
|
Exemplo:
|
|
|
|
{
|
|
"version":"1","request_id":"uuid","application_id":"uuid",
|
|
"operation":"sign","algorithm":"SHA256withRSA",
|
|
"digest":"base64","certificate_hint":"uuid","expires_at":"..."
|
|
}
|
|
|
|
Resposta:
|
|
|
|
{
|
|
"version":"1","request_id":"uuid","status":"signed",
|
|
"signature":"base64","certificate":"base64","algorithm":"SHA256withRSA"
|
|
}
|
|
|
|
Especifique em documentação autenticação, autorização, validação, timeouts, nonce, replay protection, erros e compatibilidade de versões.
|
|
|
|
8. COMUNICAÇÃO LOCAL
|
|
|
|
A comunicação deve ocorrer somente localmente por padrão. Avalie HTTPS localhost, WebSocket ou outro mecanismo adequado.
|
|
|
|
Nunca exponha uma API de assinatura local sem autenticação/autorização.
|
|
|
|
Não permita exposição involuntária à rede LAN.
|
|
|
|
Use registro/autorização de aplicações, origem permitida, desafio/nonce, timestamp, expiração e proteção contra replay.
|
|
|
|
Não confie exclusivamente em Origin ou User-Agent.
|
|
|
|
9. SEGURANÇA
|
|
|
|
A assinatura deve exigir confirmação explícita do usuário por padrão.
|
|
|
|
Mostre aplicação solicitante, certificado, tipo A1/A3, algoritmo e informações relevantes antes de assinar.
|
|
|
|
Nunca registre PIN, senha, chave privada ou conteúdo desnecessário do documento.
|
|
|
|
Minimize dados trafegados e armazenados.
|
|
|
|
Use UUIDs, correlação por request_id e validação rigorosa de entrada.
|
|
|
|
10. INTERFACE
|
|
|
|
Use JavaFX com aparência profissional e consistente.
|
|
|
|
Inclua, conforme o escopo: Dashboard, Certificados, Solicitação de Assinatura, Configurações, Diagnóstico e Sobre.
|
|
|
|
Suporte System Tray.
|
|
|
|
A interface deve informar claramente estado do agente, certificados disponíveis, token conectado e erros acionáveis.
|
|
|
|
11. DIAGNÓSTICO
|
|
|
|
Disponibilize diagnóstico de Java/runtime, engine criptográfica, Windows Certificate Store, A1, A3, PKCS#11, comunicação local e SDK.
|
|
|
|
Permita diagnóstico completo e teste de assinatura.
|
|
|
|
Diferencie claramente falha de configuração, middleware, token, certificado, comunicação e aplicação solicitante.
|
|
|
|
12. ERROS
|
|
|
|
Utilize erros estruturados e estáveis, incluindo:
|
|
|
|
CERTIFICATE_NOT_FOUND, CERTIFICATE_EXPIRED, CERTIFICATE_INVALID,
|
|
PRIVATE_KEY_NOT_AVAILABLE, TOKEN_NOT_FOUND, TOKEN_REMOVED,
|
|
PIN_REQUIRED, PIN_INCORRECT, PKCS11_ERROR, SIGNATURE_FAILED,
|
|
APPLICATION_NOT_AUTHORIZED, REQUEST_EXPIRED, REPLAY_DETECTED,
|
|
INVALID_ORIGIN, UNSUPPORTED_ALGORITHM, USER_CANCELLED,
|
|
PROVIDER_NOT_AVAILABLE e COMMUNICATION_ERROR.
|
|
|
|
Mensagens para o usuário devem ser claras, sem expor segredos ou detalhes internos desnecessários.
|
|
|
|
13. LOGS E AUDITORIA
|
|
|
|
Registre eventos relevantes: inicialização, descoberta de certificados, provider utilizado, aplicação, request_id, operação, sucesso/falha e remoção de token.
|
|
|
|
Nunca registre PIN, senha, chave privada ou dados sensíveis desnecessários.
|
|
|
|
Use níveis de log adequados e correlação por request_id.
|
|
|
|
14. SDK WEB
|
|
|
|
Planeje o pacote JavaScript @cybercore/signer-sdk.
|
|
|
|
API mínima:
|
|
|
|
connect(), isInstalled(), getVersion(), getStatus(),
|
|
getCertificates(), getCapabilities(), sign(), verify().
|
|
|
|
O SDK deve abstrair o CCSP e fornecer erros previsíveis para aplicações web.
|
|
|
|
15. MULTIAPLICAÇÃO E CONCORRÊNCIA
|
|
|
|
Uma única instalação deve atender múltiplas aplicações web autorizadas.
|
|
|
|
Controle concorrência e fila de operações, especialmente em A3, pois tokens/middleware podem não suportar operações simultâneas.
|
|
|
|
Nunca misture contexto ou autorização de uma aplicação com outra.
|
|
|
|
16. PDF/PAdES
|
|
|
|
Não misture a operação criptográfica básica com a montagem/finalização de PDF.
|
|
|
|
Para PAdES, avalie bibliotecas maduras como Apache PDFBox, Bouncy Castle ou DSS.
|
|
|
|
Nunca implemente manualmente mecanismos criptográficos ou estruturas complexas de assinatura PDF sem necessidade.
|
|
|
|
17. TESTES
|
|
|
|
Crie testes unitários, integração, segurança, protocolo, providers, comunicação local, SDK e concorrência.
|
|
|
|
Cubra A1 válido/expirado/inválido/senha incorreta; A3 sem token, token removido, PIN incorreto, middleware indisponível e cancelamento; assinatura válida; algoritmo incompatível; requisição expirada/repetida/não autorizada; origem inválida; payload malformado e concorrência.
|
|
|
|
Testes dependentes de hardware só podem ser declarados executados quando o hardware realmente estiver disponível.
|
|
|
|
18. MODO DESENVOLVIMENTO
|
|
|
|
Implemente mock quando útil para desenvolvimento e testes, simulando A1/A3, token removido, PIN incorreto, certificado expirado, provider indisponível, timeout e cancelamento.
|
|
|
|
O modo deve ser claramente identificado como DESENVOLVIMENTO.
|
|
|
|
Nunca apresente assinatura simulada como assinatura real.
|
|
|
|
19. INSTALADOR E ATUALIZAÇÃO
|
|
|
|
Crie instalador Windows com runtime próprio, instalação/desinstalação, atalhos e opções de inicialização quando aplicável.
|
|
|
|
Atualizações devem ser autenticadas e seguras.
|
|
|
|
Executáveis e instaladores devem ser preparados para code signing.
|
|
|
|
20. PRIVACIDADE
|
|
|
|
A chave privada, PIN e senha A1 permanecem na máquina.
|
|
|
|
Quando apenas o digest for necessário, o documento não deve ser enviado ao CyberCore.
|
|
|
|
Colete, armazene e registre somente o necessário para operação, diagnóstico e auditoria.
|
|
|
|
21. DOCUMENTAÇÃO
|
|
|
|
Mantenha documentação técnica em docs/.
|
|
|
|
Documente especialmente docs/CCSP.md, arquitetura, instalação, certificados A1/A3, PKCS#11, segurança, SDK, erros, diagnóstico, desenvolvimento e limitações.
|
|
|
|
Toda mudança relevante de protocolo ou arquitetura deve atualizar a documentação correspondente.
|
|
|
|
22. IMPLEMENTAÇÃO
|
|
|
|
Ao receber uma tarefa:
|
|
|
|
1) ANALISE o projeto real e identifique impacto, dependências e riscos.
|
|
2) PLANEJE a solução, apresentando arquivos/componentes afetados e estratégia de testes.
|
|
3) PEÇA AUTORIZAÇÃO explícita antes de modificar o código.
|
|
4) IMPLEMENTE seguindo os padrões existentes e evitando alterações fora do escopo.
|
|
5) VALIDE com build, testes, análise de erros e, quando possível, execução real.
|
|
|
|
Não marque uma tarefa como concluída apenas porque o código compila.
|
|
|
|
23. REGRA FINAL
|
|
|
|
Priorize segurança, interoperabilidade, rastreabilidade, manutenção e compatibilidade.
|
|
|
|
Não invente suporte a certificados, tokens, providers, algoritmos ou hardware que não tenham sido realmente implementados/testados.
|
|
|
|
Quando algo depender de fabricante, middleware, Windows ou hardware físico, declare a dependência.
|
|
|
|
Princípio obrigatório:
|
|
|
|
ANALISAR → PLANEJAR → AUTORIZAR → IMPLEMENTAR → VALIDAR. |