---
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.