docs: update documentation files and project README structure

2026-10-11 18:04:46 -03:00
parent 176acf6f40
commit d8d2e6ee46
12 changed files with 1040 additions and 425 deletions
@@ -1,48 +1,89 @@
-# Modo de Desenvolvimento e Diagnóstico Detalhado
+# Modo de Desenvolvimento e Homologação

-O **CyberCore Signer** opera exclusivamente com **certificados digitais e provedores criptográficos reais** (A1 via arquivos `.pfx`/`.p12`, repositório nativo do Windows `Windows-MY` e tokens/smart cards físicos PKCS#11). Em conformidade com a exigência de segurança de produção, **não existem mocks ou certificados sintéticos no agente**.
+> **Diretrizes para Execução Local com Argumento `--dev`, Testes e Criação de Certificados A1 de Homologação**
+
+O **CyberCore Signer** opera exclusivamente com certificados digitais e provedores criptográficos reais (arquivos `.pfx`/`.p12`, Windows-MY e tokens físicos PKCS#11). Em cumprimento às normas de integridade do projeto, **não existem mocks ou certificados artificiais no runtime de produção**.

 ---

 ## 1. Ativação do Modo de Desenvolvimento

-Para iniciar o agente em modo de desenvolvimento (com logs detalhados e diagnósticos ampliados), utilize o argumento `--dev`:
+Para iniciar o agente em ambiente de homologação e desenvolvimento com logs estendidos de auditoria e detalhamento de operações de rede, utilize o argumento de linha de comando `--dev`:

 ```bash
-java -jar cybercore-signer.jar --dev
+# Executando via script Linux / macOS:
+./run.sh --dev
+
+# Executando no Windows:
+run.bat --dev
+
+# Ou diretamente pelo JAR compilado:
+java -jar modules/cybercore-app/target/cybercore-signer.jar --dev
 ```

-Ao iniciar, uma mensagem informativa é registrada no log:
+Ao ser iniciado com esta flag, o agente imprime no terminal o banner de diagnóstico:
 ```
 =========================================================
- MODO DE DESENVOLVIMENTO ATIVADO (--dev)
- Logs detalhados ativos. Operação com certificados reais.
+ CYBERCORE SIGNER — MODO DE DESENVOLVIMENTO ATIVADO (--dev)
+ Logs detalhados ativos. Operação com certificados reais JCA/JCE.
+ Servidor local CCSP/1 pronto em: http://127.0.0.1:21325
 =========================================================
 ```

 ---

-## 2. Testando em Ambiente de Desenvolvimento
+## 2. Geração de Certificados A1 de Teste com OpenSSL

-Para desenvolvedores testarem fluxos completos de assinatura de PDF, XML, arquivos em geral e login digital:
+Para desenvolvedores e testadores que precisam simular fluxos completos de assinatura digital (PAdES, XAdES, login digital) sem utilizar um certificado ICP-Brasil real de produção, é possível gerar um certificado digital de teste no formato `.pfx` protegido por senha utilizando o utilitário **OpenSSL**:

-1. **Certificados A1 de Teste/Homologação:**
-   - Adicione um certificado A1 `.pfx` ou `.p12` emitido por uma autoridade de teste ou autoassinado.
-   - Pela interface desktop, clique no botão **"Importar A1 (.pfx/.p12)"** no Dashboard e informe o arquivo e a senha.
-   - O certificado ficará disponível imediatamente para todas as operações CCSP/1.
+### Passo 1: Gerar a Chave Privada RSA (2048 bits)
+```bash
+openssl genrsa -out teste_signer.key 2048
+```

-2. **Repositório Nativo do Windows (Windows-MY):**
-   - Instale o certificado no repositório de certificados pessoais do Windows (`certmgr.msc`).
-   - O provedor `WindowsCertificateStoreProvider` detectará o certificado automaticamente.
+### Passo 2: Gerar o Certificado X.509 Autoassinado
+```bash
+openssl req -new -x509 -key teste_signer.key -out teste_signer.crt -days 365 \
+  -subj "/C=BR/O=ICP-Brasil Teste/OU=Desenvolvimento CyberCore/CN=DESENVOLVEDOR TESTE:12345678900"
+```

-3. **Tokens USB / Smart Cards (PKCS#11):**
-   - Conecte o dispositivo físico com middleware homologado (SafeSign, GD Burti, SafeNet, OpenSC, etc.).
-   - O provedor `Pkcs11CertificateProvider` detectará o token e seus slots.
+### Passo 3: Exportar o Certificado e Chave no Contêiner PKCS#12 (`.pfx`)
+```bash
+openssl pkcs12 -export -out certificado_teste.pfx \
+  -inkey teste_signer.key -in teste_signer.crt \
+  -name "DESENVOLVEDOR TESTE:12345678900" \
+  -passout pass:123456
+```
+
+### Passo 4: Importar no CyberCore Signer
+1. Abra o CyberCore Signer.
+2. Na tela principal, clique em **"Importar A1 (.pfx/.p12)"**.
+3. Selecione o arquivo `certificado_teste.pfx` gerado e informe a senha `123456`.
+4. O certificado aparecerá instantaneamente como disponível no Dashboard e poderá ser utilizado para todos os testes do SDK e CCSP/1.

 ---

-## 3. Garantia de Operação Real
+## 3. Execução da Suíte de Testes Automatizados

-1. Toda assinatura é gerada criptograficamente através dos provedores JCA/JCE reais.
-2. A resposta do protocolo CCSP/1 contém assinaturas válidas e certificados X.509 autênticos.
-3. Não há certificados simulados ou flags artificiais nas respostas do agente.
+O repositório do CyberCore Signer conta com suíte abrangente de testes unitários, testes de concorrência e testes de arquitetura (ArchUnit):
+
+```bash
+# Executar todos os testes unitários do projeto:
+./mvnw test
+
+# Executar testes específicos do protocolo CCSP/1:
+./mvnw test -Dtest=CcspServerTest
+
+# Executar testes de concorrência e trava FIFO (signLock):
+./mvnw test -Dtest=CcspConcurrencyTest
+
+# Executar testes de conformidade arquitetural (garante desacoplamento de UI no core):
+./mvnw test -Dtest=ArchitectureTest
+```
+
+---
+
+## 4. Garantia de Operação Real
+
+1. **Assinaturas Autênticas:** Mesmo ao utilizar um certificado autoassinado de teste, os bytes da assinatura são calculados matematicamente pelos algoritmos reais do JCA/JCE (`SHA256withRSA`).
+2. **Sem Falsos Positivos:** O comportamento do agente é 100% idêntico entre o ambiente de teste e o ambiente de produção com tokens físicos A3.