# Diagnóstico de Ambiente e Resolução de Problemas

> **Guia de Auto-Teste, Checklist de Integridade de Runtime e Troubleshooting de Hardware**

O **CyberCore Signer** conta com um subsistema nativo de diagnóstico e telemetria local (`DiagnosticService`), projetado para validar a integridade da estação de trabalho e identificar rapidamente falhas de drivers, certificados ou subsistemas criptográficos do sistema operacional.

---

## 1. Itens Inspecionados pelo Diagnóstico Automático

Ao acessar a aba **Diagnóstico** na interface do agente desktop ou ao inicializar em modo `--dev`, o agente executa uma auditoria completa nos seguintes componentes:

1. **Ambiente Java / Runtime Nativo:**
   - Versão do Java (requer Java 25 LTS);
   - Vendor do JDK (Eclipse Temurin, Oracle OpenJDK, Amazon Corretto);
   - Arquitetura da CPU (x86_64 / amd64) e sistema operacional (Windows 10/11 ou Linux).
2. **Engine Criptográfica JCA/JCE:**
   - Disponibilidade dos provedores de segurança registrados na JVM (`SUN`, `SunRsaSign`, `SunMSCAPI`, etc.);
   - Suporte aos algoritmos de hash criptográfico (`SHA-256`, `SHA-512`);
   - Suporte aos algoritmos de assinatura digital (`SHA256withRSA`).
3. **Repositório de Certificados do Sistema Operacional:**
   - Detecção do repositório de chaves `Windows-MY` via SunMSCAPI / CryptoAPI / CNG.
4. **Middlewares PKCS#11 e Subsistema PC/SC:**
   - Presença das bibliotecas dinâmicas do fabricante (`aetpkss1.dll`, `eps2003csp11.dll`, `acospkcs11.dll`, `opensc-pkcs11.dll`);
   - Disponibilidade do subsistema de leitoras de smartcard `javax.smartcardio` (PC/SC Daemon / Smart Card Service do Windows).
5. **Servidor Local CCSP/1:**
   - Teste de bind do socket em `127.0.0.1:21325` e integridade do pool de threads.

---

## 2. Auto-Teste de Assinatura Local (Self-Test)

A tela de diagnóstico oferece a função **"Executar Auto-teste de Assinatura"**:
1. O agente identifica o primeiro certificado digital operacional conectado.
2. Gera um hash SHA-256 interno sintético para teste: `"Documento_Teste_CyberCore_<timestamp>"`.
3. Abre o diálogo nativo de confirmação visual para validação do usuário.
4. Executa a assinatura real através do provedor JCA/JCE correspondente (solicitando PIN se A3).
5. Valida os bytes da assinatura gerada e emite relatório com tempo decorrido em milissegundos e tamanho da assinatura.

---

## 3. Guia de Resolução de Problemas (Troubleshooting)

### 3.1 Token USB ou Smartcard A3 não é detectado
* **Sintoma:** O token está plugado na porta USB mas não aparece no CyberCore nem na lista de certificados.
* **Causa Comum:** O serviço de cartão inteligente do Windows (`ScardSvr`) está desativado ou o middleware do fabricante (SafeSign/SafeNet) não está instalado.
* **Solução:**
  1. No Windows, pressione `Win + R`, digite `services.msc` e pressione Enter.
  2. Localize o serviço **Cartão Inteligente (Smart Card)** e garanta que seu status esteja **Em Execução** (Tipo de Inicialização: Automático).
  3. Verifique se o aplicativo de gerenciamento do token (ex: *SafeSign Token Utility* ou *SafeNet Authentication Client Tools*) reconhece o token.
  4. Desconecte o token USB, aguarde 3 segundos e reconecte em outra porta USB.

### 3.2 Erro `NTE_BAD_KEYSET` ou `Chave Privada Não Acessível`
* **Sintoma:** O certificado aparece na lista, mas a assinatura falha com erro `PRIVATE_KEY_NOT_AVAILABLE` ou código Windows `0x80090016`.
* **Causa Comum:** O certificado foi importado no Windows sem a chave privada correspondente, ou o usuário não tem permissão de leitura sobre o contêiner de chaves.
* **Solução:**
  1. Abra o gerenciador de certificados do Windows: `certmgr.msc`.
  2. Navegue até **Pessoal -> Certificados** e dê um duplo clique sobre o certificado.
  3. Verifique se na parte inferior da aba Geral consta a mensagem: *"Você tem uma chave privada correspondente a este certificado"*. Se não constar, reinstale o arquivo A1 com a opção "Marcar esta chave como exportável" ativada.

### 3.3 Porta local `21325` já em uso (`BindException`)
* **Sintoma:** O CyberCore Signer não inicializa e os logs acusam `Address already in use: bind`.
* **Causa Comum:** Outra instância do CyberCore Signer ou aplicativo conflitante já está em execução na porta `21325`.
* **Solução:**
  1. No Windows, abra o Gerenciador de Tarefas (`Ctrl + Shift + Esc`) e encerre eventuais processos `cybercore-signer` ou `javaw.exe` órfãos.
  2. No terminal (PowerShell), você pode identificar o processo ocupando a porta:
     ```powershell
     Get-NetTCPConnection -LocalPort 21325 | Select-Object OwningProcess
     ```
  3. No Linux:
     ```bash
     sudo lsof -i :21325
     ```

### 3.4 Aplicação Web acusa "Agente não instalado" ou Falha de Conexão
* **Sintoma:** A chamada `signer.isInstalled()` no navegador retorna `false` ou dá timeout.
* **Causa Comum:** O CyberCore Signer está fechado, o antivírus bloqueou a conexão loopback local, ou a aplicação web tenta conectar com protocolo incorreto.
* **Solução:**
  1. Verifique se o ícone do CyberCore Signer está ativo na barra de tarefas (System Tray).
  2. Abra uma nova aba no navegador e acesse diretamente: `http://127.0.0.1:21325/ccsp/v1/status`.
  3. O navegador deve exibir o JSON com `"status": "ready"`. Se não exibir, abra o executável do CyberCore Signer.

---

## 4. Comandos Úteis de Diagnóstico no Terminal

### No Windows:
```cmd
:: Testar leitura de smartcards e drivers via utilitário nativo do Windows:
certutil -scinfo

:: Listar certificados instalados no repositório Pessoal do usuário:
certutil -user -store My
```

### No Linux:
```bash
:: Verificar leitoras e cartões conectados via subsistema PC/SC:
pcsc_scan

:: Verificar status do serviço pcscd:
systemctl status pcscd
```