9.9 KiB
trigger
| 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- IMPLEMENTAÇÃO
Ao receber uma tarefa:
- ANALISE o projeto real e identifique impacto, dependências e riscos.
- PLANEJE a solução, apresentando arquivos/componentes afetados e estratégia de testes.
- PEÇA AUTORIZAÇÃO explícita antes de modificar o código.
- IMPLEMENTE seguindo os padrões existentes e evitando alterações fora do escopo.
- 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.
- 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.