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,100 +1,137 @@
 # CyberCore Signer
-> **Agente Desktop de Assinatura Digital e Autenticação Criptográfica (A1 / A3 / PKCS#11) para Windows e Linux.**
+> **Agente Desktop Nativo de Assinatura Digital e Autenticação Criptográfica (A1 / A3 / PKCS#11) para Windows e Linux.**
-O **CyberCore Signer** é uma solução desktop em Java 21 LTS com JavaFX que permite que aplicações web autorizadas solicitem assinaturas digitais, autenticação de sessão e carimbos do tempo utilizando certificados digitais ICP-Brasil (A1 em arquivo e A3 em tokens/smartcards físicos) instalados ou conectados na estação de trabalho do usuário.
+[![Java 21+](https://img.shields.io/badge/Java-21%2B%20LTS-orange.svg)](https://openjdk.org/)
 [![JavaFX 25](https://img.shields.io/badge/JavaFX-25-blue.svg)](https://openjfx.io/)
 [![Protocol CCSP/1](https://img.shields.io/badge/Protocol-CCSP%2F1-green.svg)](docs/CCSP.md)
 [![Standard ICP-Brasil](https://img.shields.io/badge/Standard-ICP--Brasil-emerald.svg)](https://www.gov.br/iti/pt-br)
 [![License](https://img.shields.io/badge/License-Proprietary-darkred.svg)](#licença)
-A comunicação local entre a página web e o agente utiliza o protocolo **CCSP (CyberCore Signing Protocol)** via HTTP/WebSocket localhost autenticado e seguro.
+O **CyberCore Signer** é uma solução desktop desenvolvida em Java 21+ LTS (homologada em Java 25 LTS) com interface gráfica moderna JavaFX e segurança criptográfica estrita JCA/JCE. Permite que aplicações web autorizadas solicitem assinaturas digitais, autenticação de sessão e validação de documentos utilizando certificados digitais padrão ICP-Brasil (A1 em arquivo e A3 em tokens/smartcards físicos) conectados ou instalados na máquina do usuário.
 A comunicação local entre a página web e o agente utiliza o protocolo **CCSP (CyberCore Signing Protocol)** via HTTP localhost (`127.0.0.1:21325`), garantindo isolamento total de rede, consentimento visual explícito e preservação integral das chaves privadas na máquina local.
 ---
 ## ⚡ Quick Start
 ### 🌐 Para Aplicações Web (via SDK JavaScript)
 Instale e utilize o SDK oficial `@cybercore/signer-sdk` para conectar sua aplicação web ao agente local em poucos passos:
 ```javascript
 import { CyberCoreSigner } from '@cybercore/signer-sdk';
 // 1. Inicializar o cliente do assinador
 const signer = new CyberCoreSigner({
  applicationName: 'Portal Meu Negócio'
 });
 // 2. Obter certificados disponíveis na máquina do usuário
 const certificates = await signer.getCertificates();
 const cert = certificates[0]; // Seleciona o primeiro certificado disponível
 // 3. Assinar o hash SHA-256 de um documento (a chave nunca sai da máquina!)
 const result = await signer.sign({
  certificateId: cert.id,
  digest: '47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=',
  documentName: 'contrato_prestacao_servicos.pdf'
 });
 console.log('Assinatura gerada:', result.signature);
 console.log('Certificado titular:', result.subject_name);
 ```
 > Para o manual completo com exemplos de login digital, assinatura de PDF e XML, consulte o [Guia do SDK](docs/sdk.md).
 ---
 ### ☕ Para Desenvolvedores Desktop
 #### Requisitos
 * **Java Development Kit (JDK):** Versão 21+ LTS (OpenJDK, Temurin ou Corretto).
 * **Maven:** 3.9+ (ou utilizar o `./mvnw` embutido).
 * **Sistema Operacional:** Windows 10/11 ou Linux x86_64.
 #### Compilação e Execução
 ```bash
 # Compilar e gerar o JAR consolidado (Fat JAR sombreado):
 ./mvnw clean package -DskipTests
 # Executar o agente no Linux / macOS:
 ./run.sh
 # Executar o agente no Windows:
 run.bat
 # Executar com logs detalhados de diagnóstico:
 java -jar modules/cybercore-app/target/cybercore-signer.jar --dev
 ```
 ---
 ## 🏛 Arquitetura do Projeto
-O projeto é estruturado em módulos Maven:
+O projeto é estruturado em módulos Maven desacoplados, garantindo isolamento entre regras criptográficas de baixo nível e a camada de interface gráfica:
-* **[modules/cybercore-core](modules/cybercore-core)**: Núcleo de regras criptográficas (JCA/JCE, SunPKCS11, X.509, PAdES, XMLDSig, carimbo de tempo TSA, LTV e validação de cadeias). Não possui dependência de interface gráfica.
+* **[`modules/cybercore-core`](modules/cybercore-core):** Núcleo de regras criptográficas (JCA/JCE, SunPKCS11, X.509, PAdES com Apache PDFBox e Bouncy Castle, XAdES-BES/XMLDSig, carimbo de tempo TSA, LTV, fila FIFO de concorrência e validação de cadeias). **Agnóstico de UI**, sem nenhuma dependência de JavaFX.
-* **[modules/cybercore-ui](modules/cybercore-ui)**: Interface gráfica com o usuário construída em JavaFX (Dashboard, Gerenciador de Certificados, Diagnóstico Criptográfico, Diálogo de Confirmação de Assinatura, PIN dialog e System Tray).
+* **[`modules/cybercore-ui`](modules/cybercore-ui):** Interface gráfica com o usuário construída em JavaFX 25, apresentando design moderno com alternância dinâmica Claro/Escuro (Dual-Theme), Dashboard, Gerenciador de Certificados, Designer de Selos Visuais SVG com Live Preview, Diálogos de Confirmação de Assinatura, PIN dialog e System Tray.
-* **[modules/cybercore-app](modules/cybercore-app)**: Ponto de entrada da aplicação (`CyberCoreApp`), orquestrador dos serviços de ciclo de vida e servidor CCSP local.
+* **[`modules/cybercore-app`](modules/cybercore-app):** Ponto de entrada da aplicação (`CyberCoreApp`), orquestrador dos serviços de ciclo de vida, diagnóstico pré-inicialização e servidor CCSP local.
-* **[sdk/](sdk)**: SDK JavaScript oficial (`@cybercore/signer-sdk`) para integração de aplicações web com o agente desktop.
+* **[`sdk/`](sdk):** SDK JavaScript oficial (`@cybercore/signer-sdk`) para integração simplificada de aplicações web modernas com o agente desktop.
-* **[docs/](docs)**: Documentação técnica detalhada de arquitetura, protocolo, segurança e casos de uso.
+* **[`docs/`](docs):** Documentação técnica abrangente contendo especificações do protocolo, arquitetura, segurança e manuais de integração.
 ---
-## 🚀 Requisitos
+## 📊 Matriz de Recursos e Conformidade
-* **Java Development Kit (JDK):** Versão 21+ LTS (OpenJDK, Temurin, Corretto, etc.).
+| Recurso | Padrão / Tecnologia | Descrição |
-* **Maven:** 3.9+ (ou utilizar o wrapper `./mvnw` incluído no projeto).
+|---|---|---|
-* **Sistema Operacional Alvo:** Windows 10/11 ou Linux (x86_64).
+| **Certificados A1** | PKCS#12 / `.pfx` / `.p12` | Leitura em memória volátil com destruição segura de senhas |
 | **Certificados A3** | Windows-MY (CryptoAPI/CNG) & PKCS#11 | Acesso nativo a tokens USB e smartcards (SafeSign, SafeNet, GD Burti, OpenSC) |
 | **Assinatura PDF** | PAdES (ISO 32000-1 / ETSI TS 102 778) | Envelope CMS/PKCS#7, suporte a salvamento incremental e carimbo TSA |
 | **Selos Visuais PDF** | Renderização Java2D de Alta Resolução (300 DPI) | Brasões vetoriais, upload de logos, controle de sigilo de CPF (LGPD) e pré-visualização interativa |
 | **Assinatura XML** | XAdES-BES (ETSI TS 101 903 / DOC-ICP-15.03) | Suporte completo a NF-e, CT-e, MDF-e, eSocial e documentos envelopados |
 | **Assinatura Genérica** | CMS / CAdES / P7S / P7M | Modalidades atachada (enveloped) e destacada (detached) |
 | **Login Digital** | Challenge-Response ICP-Brasil | Autenticação web segura sem senhas tradicionais |
 | **Validação** | Verificação Criptográfica Local | Auditoria de integridade de hashes, validade de certificados e signatários |
 | **Interface Desktop** | JavaFX 25 com Dual-Theme | Modo Claro e Modo Escuro com comutação instantânea e atalhos na bandeja |
 | **Protocolo Local** | CCSP/1 REST (`127.0.0.1:21325`) | Bind estrito em loopback, proteção anti-replay via nonce e autorização de origens |
 ---
-## 🛠 Compilação e Empacotamento
+## 🔒 Princípios Fundamentais de Segurança
-### 1. Compilação do JAR Executável
+1. **A Chave Privada Permanece na Estação de Trabalho:** A chave privada e os segredos (PIN do token A3 ou senha do arquivo A1) nunca saem da máquina do usuário nem trafegam pela rede ou saem em logs.
-
+2. **Assinatura por Digest Descentralizada:** Por padrão, a aplicação web calcula o hash SHA-256 do documento localmente e o CyberCore assina apenas o digest de 32 bytes, eliminando o tráfego desnecessário de arquivos inteiros.
-Para compilar e gerar o JAR consolidado (com todas as dependências sombreadas e assets):
+3. **Consentimento Visual Explícito:** Nenhuma operação de assinatura ocorre silenciosamente. Toda requisição exige autorização física do usuário em diálogo nativo do sistema operacional.
-
+4. **Isolamento de Origem e Anti-Replay:** Cada requisição web deve apresentar identificador de aplicação aprovado, nonce único com validação temporal (`expires_at`) e cabeçalho de origem verificado.
-```bash
+5. **Fila FIFO de Operações:** O acesso a tokens físicos A3 é protegido por trava de concorrência (`signLock`) serializada, prevenindo travamento ou corrupção de sessão nos chips criptográficos.
 ./build-jar.sh
 ```
 Ou diretamente via Maven:
 ```bash
 ./mvnw clean package -DskipTests
 ```
 O artefato consolidado será gerado em:
 `modules/cybercore-app/target/cybercore-signer.jar`
 ### 2. Execução Local
 Para iniciar o agente em ambiente de desenvolvimento:
 ```bash
 # No Linux / macOS:
 ./run.sh
 # No Windows:
 run.bat
 ```
 ### 3. Empacotamento com Runtime Nativo (`jpackage`)
 Para criar a distribuição com Java Runtime embutido (sem exigir JDK pré-instalado pelo usuário final):
 ```bash
 ./scripts/package-jpackage.sh
 ```
 ---
-## 🔒 Princípios de Segurança e Privacidade
+## 📚 Documentação Técnica Detalhada
-1. **Chave Privada Preservada:** A chave privada e os segredos (PIN de token A3 e senha de certificado A1) nunca saem da máquina do usuário nem trafegam pela rede.
+Para detalhes completos sobre arquitetura, protocolos e manuais técnicos, acesse o [Portal de Documentação](docs/README.md) ou consulte diretamente os links abaixo:
-2. **Assinatura por Digest:** Por padrão, a aplicação web calcula o hash/digest (ex: SHA-256) do documento e o CyberCore assina localmente apenas o digest, minimizando o tráfego de dados sensíveis.
+
-3. **Confirmação Explícita:** Toda operação de assinatura exige consentimento e autorização visual do usuário antes da aplicação da chave.
+* 🌐 **[Protocolo CCSP/1](docs/CCSP.md):** Contrato REST, endpoints, códigos de status e anti-replay.
-4. **Isolamento de Origem e CCSP:** O agente atende apenas origens web autorizadas, protegendo contra abusos via CSRF ou requisições locais não autenticadas.
+* 📦 **[SDK Web JavaScript](docs/sdk.md):** Guia de integração e métodos da biblioteca oficial.
 * 🏛 **[Arquitetura do Sistema](docs/architecture.md):** Módulos, threading e fluxo sequencial.
 * 💳 **[Certificados A1, A3 e PKCS#11](docs/a1-a3-certificates.md):** Suporte a hardware, drivers e OIDs ICP-Brasil.
 * 📄 **[Assinaturas PDF e Selos SVG](docs/pades.md):** PAdES, renderização Java2D e selos visuais.
 * 📑 **[Assinaturas XML (XAdES-BES)](docs/xml-xmldsig.md):** Padrão DOC-ICP-15.03 e notas fiscais.
 * 🔑 **[Autenticação e Login Digital](docs/authentication-login.md):** Fluxo Challenge-Response via ICP-Brasil.
 * ⚠️ **[Catálogo Estruturado de Erros](docs/errors.md):** Tabela de erros `CcspErrorCode` e códigos HTTP.
 * 🛡️ **[Modelo de Segurança e Privacidade](docs/security.md):** Diretrizes de isolamento, memória e LGPD.
 * 🩺 **[Diagnóstico e Troubleshooting](docs/diagnostics.md):** Auto-teste e guia de resolução de problemas.
 * 💿 **[Instalação e Empacotamento Nativo](docs/installation.md):** Distribuição via `jpackage` sem JRE pré-instalado.
 * ⚖️ **[Limitações Técnicas](docs/limitations.md):** Declaração de dependências conforme a Regra 23.
 * 🛠️ **[Modo de Desenvolvimento](docs/development-mode.md):** Parâmetro `--dev` e certificados de teste.
 * 🎨 **[Layout Dual-Theme e Assinatura em Lote](docs/serpro-layout-and-batch.md):** Design da UI e operações em lote.
 ---
-## 📚 Documentação Técnica
+## 📄 Licença e Propriedade
-Consulte a pasta [docs/](docs) para especificações completas:
+Copyright © 2026 **CyberCore Systems**. Todos os direitos reservados.
-
+Este software é proprietário e confidencial. O uso, distribuição ou modificação não autorizados são estritamente proibidos.
 * [Protocolo CCSP (CyberCore Signing Protocol)](docs/CCSP.md)
 * [Arquitetura e Fluxo do Sistema](docs/architecture.md)
 * [Certificados A1 e A3 (PKCS#11 / MSCAPI)](docs/a1-a3-certificates.md)
 * [Assinatura de Documentos PDF (PAdES / LTV / TSA)](docs/pades.md)
 * [Assinatura de Documentos XML (XMLDSig)](docs/xml-xmldsig.md)
 * [Autenticação e Sessão Criptográfica](docs/authentication-login.md)
 * [Diagnóstico e Resolução de Problemas](docs/diagnostics.md)
 * [Segurança e Tratamento de Erros](docs/security.md)
 * [SDK Web JavaScript](docs/sdk.md)
 * [Guia de Instalação](docs/installation.md)
 ---
 ## 📄 Licença
 Propriedade de **CyberCore Systems**. Todos os direitos reservados.
@@ -1,28 +1,52 @@
 # CyberCore Signing Protocol (CCSP/1)
-O **CyberCore Signing Protocol (CCSP)** é o protocolo padrão para comunicação local entre aplicações web rodando no navegador e o agente desktop **CyberCore Signer**.
+> **Especificação Técnica do Protocolo de Comunicação Local e API REST (Versão 1)**
-A versão inicial descrita neste documento é a **CCSP/1**.
+O **CyberCore Signing Protocol (CCSP)** é o protocolo padrão para comunicação local entre aplicações web rodando no navegador do usuário e o agente desktop **CyberCore Signer**.
 A versão atual especificada neste documento é a **CCSP/1**.
 ---
-## 1. Princípios de Segurança
+## 1. Princípios de Segurança e Isolamento
-1. **Isolamento de Rede:** O servidor local escuta exclusivamente no endereço de loopback `127.0.0.1` (porta padrão `21325`), impedindo qualquer acesso a partir da rede local (LAN) ou externa (WAN).
+O protocolo CCSP/1 adota o princípio de menor privilégio e segurança em profundidade:
-2. **Controle Estrito de Origem (CORS):** O agente valida cabeçalhos `Origin` e responde apenas a pré-voos `OPTIONS` com origens autorizadas.
+
-3. **Registro e Autorização de Aplicações:** Nenhuma aplicação desconhecida tem acesso a certificados ou assinaturas. Ao tentar conectar pela primeira vez, uma caixa de diálogo nativa solicita aprovação explícita do usuário.
+1. **Loopback Estrito (`127.0.0.1`):** O servidor HTTP local vincula seu socket exclusivamente ao endereço IP `127.0.0.1` na porta padrão `21325`. O agente rejeita escuta em `0.0.0.0`, prevenindo qualquer acesso proveniente da rede local (LAN) ou externa (WAN).
-4. **Confirmação Visual da Assinatura:** Toda operação de assinatura exige confirmação manual na interface gráfica, exibindo a aplicação solicitante, o hash do documento e o certificado selecionado.
+2. **Validação de Cabeçalhos e DNS Rebinding:** O agente valida o cabeçalho `Host` para garantir que as requisições se originem estritamente de `127.0.0.1:21325` ou `localhost:21325`.
-5. **Proteção Contra Ataques de Replay:** Toda requisição deve conter um `nonce` UUID único com validação temporal (`expires_at` ou `timestamp`). Requisições com nonces repetidos são sumariamente rejeitadas (`REPLAY_DETECTED`).
+3. **Controle de Origem (CORS):** Todas as respostas incluem cabeçalhos CORS restritivos. Métodos HTTP `OPTIONS` prévios (preflight) são tratados para liberar apenas métodos e headers homologados (`Content-Type`, `Origin`, `X-CyberCore-AppId`).
-6. **Privacidade Criptográfica:** Apenas o **digest (hash)** do documento é enviado ao agente. O documento completo nunca sai da aplicação web e a chave privada nunca sai do dispositivo/computador do usuário.
+4. **Handshake de Autorização de Aplicações:** Nenhuma página web desconhecida pode listar certificados ou solicitar assinaturas. Uma aplicação deve se identificar (`POST /ccsp/v1/authorize`) e obter aprovação explícita do usuário via diálogo nativo do sistema operacional.
 5. **Proteção Anti-Replay com Nonce e TTL:** Todas as chamadas de assinatura exigem um identificador pseudoaleatório `nonce` único e um timestamp de expiração (`expires_at`). Requisições com nonces repetidos são sumariamente rejeitadas com erro estruturado `REPLAY_DETECTED`.
 6. **Privacidade Criptográfica por Digest:** Por padrão, a aplicação web calcula o hash SHA-256 no próprio navegador utilizando a Web Crypto API nativa e envia apenas o digest de 32 bytes (em Base64). O documento confidencial nunca trafega para o agente e a chave privada nunca sai do computador ou do chip criptográfico do usuário.
 7. **Trava FIFO Serializada (`signLock`):** O processamento de assinaturas físicas em smartcards/tokens USB A3 é serializado em fila FIFO para evitar colisões no hardware mono-thread do middleware do fabricante.
 ---
-## 2. Endpoints do Protocolo (CCSP/1)
+## 2. Visão Geral dos Endpoints (CCSP/1)
-### 2.1 `GET /ccsp/v1/status`
+| Método | Endpoint | Finalidade | Autenticação Requerida |
-Verifica se o agente está instalado, em execução e pronto para operações.
+|---|---|---|---|
 | `GET` | `/ccsp/v1/status` | Verifica integridade e status de prontidão do agente local | Nenhuma |
 | `POST` | `/ccsp/v1/authorize` | Handshake de autorização inicial de uma aplicação web | Consentimento visual do usuário |
 | `GET` | `/ccsp/v1/certificates` | Lista certificados digitais ICP-Brasil válidos e operacionais | Aplicação Autorizada |
 | `POST` | `/ccsp/v1/sign` | Executa assinatura digital do digest informado | Aplicação Autorizada + Diálogo Nativo |
 | `POST` | `/ccsp/v1/authenticate` | Realiza login seguro via desafio criptográfico (*Challenge-Response*) | Aplicação Autorizada + Diálogo Nativo |
-#### Resposta de Sucesso (200 OK)
+---
 ## 3. Especificação Detalhada dos Endpoints
 ### 3.1 `GET /ccsp/v1/status`
 Verifica se o agente desktop está instalado, em execução e pronto para operações criptográficas.
 #### Requisição
 ```http
 GET /ccsp/v1/status HTTP/1.1
 Host: 127.0.0.1:21325
 Origin: https://meusistema.empresa.com.br
 ```
 #### Resposta de Sucesso (`200 OK`)
 ```json
 {
  "version": "1",
@@ -30,20 +54,58 @@ Verifica se o agente está instalado, em execução e pronto para operações.
  "agent": "CyberCore Signer",
  "agent_version": "0.1.0",
  "os": "Windows 11",
-  "timestamp": "2026-10-08T19:40:00Z"
+  "timestamp": "2026-10-11T20:45:00Z"
 }
 ```
 ---
-### 2.2 `GET /ccsp/v1/certificates`
+### 3.2 `POST /ccsp/v1/authorize`
-Retorna a lista de certificados digitais atualmente disponíveis e aptos para assinatura.
+Inicia o handshake para autorizar uma nova aplicação web. Quando a aplicação ainda não foi homologada pelo usuário, o CyberCore Signer suspende a requisição e exibe um modal nativo na tela do desktop para confirmação.
-#### Headers / Parâmetros
+#### Cabeçalhos
- `X-CyberCore-AppId`: UUID da aplicação autorizada (ou query param `?application_id=uuid`).
+- `Content-Type: application/json`
 - `Origin: https://meusistema.empresa.com.br`
 #### Payload da Requisição
 ```json
 {
  "version": "1",
  "application_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Portal Jurídico e Tributário"
 }
 ```
 #### Resposta de Sucesso (`200 OK`)
 ```json
 {
  "version": "1",
  "status": "authorized",
  "application_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Aplicação autorizada pelo usuário com sucesso."
 }
 ```
 #### Resposta de Recusa do Usuário (`403 Forbidden`)
 ```json
 {
  "version": "1",
  "status": "error",
  "error_code": "APPLICATION_NOT_AUTHORIZED",
  "message": "O usuário recusou a autorização para esta aplicação."
 }
 ```
 ---
 ### 3.3 `GET /ccsp/v1/certificates`
 Retorna a lista de certificados digitais atualmente disponíveis e aptos para assinatura no sistema (A1 importados e A3 conectados via Windows Store ou PKCS#11).
 #### Cabeçalhos / Parâmetros
 - `Origin`: Origem web autorizada.
 - `X-CyberCore-AppId` (Header) ou `?application_id=uuid` (Query Param).
-#### Resposta de Sucesso (200 OK)
+#### Resposta de Sucesso (`200 OK`)
 ```json
 {
  "version": "1",
@@ -51,16 +113,18 @@ Retorna a lista de certificados digitais atualmente disponíveis e aptos para as
  "certificates": [
    {
      "id": "win-4340656a",
-      "alias": "CLAUDIO SILVA:12345678900",
+      "alias": "MARIA DA SILVA:12345678900",
-      "common_name": "CLAUDIO SILVA:12345678900",
+      "common_name": "MARIA DA SILVA:12345678900",
-      "subject_dn": "CN=CLAUDIO SILVA:12345678900, OU=Autenticado por AR, O=ICP-Brasil, C=BR",
+      "subject_dn": "CN=MARIA DA SILVA:12345678900, OU=Autenticado por AR, O=ICP-Brasil, C=BR",
-      "issuer_dn": "CN=AC SERPRO v5, O=ICP-Brasil, C=BR",
+      "issuer_dn": "CN=AC SERPRO v5, OU=Servico Federal de Processamento de Dados, O=ICP-Brasil, C=BR",
      "type": "A3",
      "provider_id": "provider-win-store",
-      "device_name": "Token / Smart Card (Windows CAPI/CNG)",
+      "device_name": "Token USB / Smart Card (Windows CAPI/CNG)",
-      "valid_from": "2024-05-10T12:00:00Z",
+      "valid_from": "2025-01-10T10:00:00Z",
-      "valid_to": "2027-05-10T12:00:00Z",
+      "valid_to": "2028-01-10T10:00:00Z",
      "serial_number": "72910482910482019482",
      "cpf": "12345678900",
      "cnpj": null,
      "can_sign": true,
      "status": "AVAILABLE"
    }
@@ -70,33 +134,10 @@ Retorna a lista de certificados digitais atualmente disponíveis e aptos para as
 ---
-### 2.3 `POST /ccsp/v1/authorize`
+### 3.4 `POST /ccsp/v1/sign`
-Handshake inicial de uma nova aplicação web para solicitar autorização ao usuário.
+Solicita a assinatura digital local do digest informado com o certificado escolhido.
-#### Requisição
+#### Payload da Requisição
 ```json
 {
  "version": "1",
  "application_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Portal Assinaturas Jurídicas"
 }
 ```
 #### Resposta (200 OK)
 ```json
 {
  "version": "1",
  "status": "authorized",
  "application_id": "550e8400-e29b-41d4-a716-446655440000"
 }
 ```
 ---
 ### 2.4 `POST /ccsp/v1/sign`
 Executa a assinatura digital do digest informado (PDF, XML, documentos ou arquivos gerais).
 #### Requisição
 ```json
 {
  "version": "1",
@@ -106,103 +147,128 @@ Executa a assinatura digital do digest informado (PDF, XML, documentos ou arquiv
  "algorithm": "SHA256withRSA",
  "digest": "47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=",
  "certificate_hint": "win-4340656a",
-  "document_name": "contrato_locacao.pdf",
+  "document_name": "contrato_prestacao_servicos.pdf",
  "document_type": "PDF",
  "nonce": "c4ca4238a0b923820dcc509a6f75849b",
-  "expires_at": "2026-10-08T19:45:00Z"
+  "expires_at": "2026-10-11T20:50:00Z"
 }
 ```
-#### Resposta de Sucesso (200 OK)
+#### Resposta de Sucesso (`200 OK`)
 ```json
 {
  "version": "1",
  "request_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "status": "signed",
-  "signature": "MEUCIQDq...base64...",
+  "signature": "MEUCIQDq95kZc...Base64...",
-  "certificate": "MIIFazC...base64...",
+  "certificate": "MIIFazCCBF...Base64...",
  "certificate_chain": [
-    "MIIFazC...base64...",
+    "MIIFazCCBF...Base64...",
-    "MIIEazC...base64..."
+    "MIIEazCCA1...Base64..."
  ],
  "algorithm": "SHA256withRSA",
-  "subject_name": "CLAUDIO SILVA",
+  "subject_name": "MARIA DA SILVA",
  "subject_cpf_cnpj": "12345678900",
-  "document_name": "contrato_locacao.pdf",
+  "document_name": "contrato_prestacao_servicos.pdf",
  "document_type": "PDF"
 }
 ```
 ---
-### 2.5 `POST /ccsp/v1/authenticate`
+### 3.5 `POST /ccsp/v1/authenticate`
-Executa o login / autenticação digital segura de um usuário em sistemas web via desafio criptográfico (Challenge-Response ICP-Brasil).
+Executa o login criptográfico de um usuário em sistemas web através do mecanismo de desafio e resposta (*Challenge-Response*).
-#### Requisição
+#### Payload da Requisição
 ```json
 {
  "version": "1",
-  "request_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
+  "request_id": "8f3b201a-8c9d-4e5f-b012-3456789abcde",
  "application_id": "550e8400-e29b-41d4-a716-446655440000",
  "operation": "authenticate",
-  "challenge": "server-session-challenge-nonce-2026",
+  "challenge": "session-nonce-random-server-token-998877",
  "certificate_hint": "win-4340656a",
  "purpose": "AUTHENTICATION",
-  "nonce": "c4ca4238a0b923820dcc509a6f75849b",
+  "nonce": "d3b07384d113edec49eaa6238ad5ff00",
-  "expires_at": "2026-10-08T19:45:00Z"
+  "expires_at": "2026-10-11T20:50:00Z"
 }
 ```
-#### Resposta de Sucesso (200 OK)
+#### Resposta de Sucesso (`200 OK`)
 ```json
 {
  "version": "1",
-  "request_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
+  "request_id": "8f3b201a-8c9d-4e5f-b012-3456789abcde",
  "status": "authenticated",
-  "signature": "MEUCIQDq...base64...",
+  "signature": "MEQCIF61pP...Base64...",
-  "certificate": "MIIFazC...base64...",
+  "certificate": "MIIFazCCBF...Base64...",
  "certificate_chain": [
-    "MIIFazC...base64..."
+    "MIIFazCCBF...Base64...",
    "MIIEazCCA1...Base64..."
  ],
  "algorithm": "SHA256withRSA",
-  "subject_name": "CLAUDIO SILVA",
+  "subject_name": "MARIA DA SILVA",
-  "subject_cpf_cnpj": "12345678900",
+  "subject_cpf_cnpj": "12345678900"
  "document_type": "AUTH_CHALLENGE"
 }
 ```
 #### Resposta de Erro (400/403/404)
 ```json
 {
  "version": "1",
  "request_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "status": "error",
  "error_code": "USER_CANCELLED",
  "message": "Operação de assinatura cancelada pelo usuário."
 }
 ```
 ---
-## 3. Tabela de Códigos de Erro Estruturados
+## 4. Estrutura Padrão de Erro e Códigos HTTP
-| Código | Significado |
+Quando qualquer operação falha, o servidor local CCSP/1 responde com um objeto JSON padronizado e o código de status HTTP correspondente:
-|---|---|
+
-| `CERTIFICATE_NOT_FOUND` | Certificado indicado no hint não foi encontrado. |
+```json
-| `CERTIFICATE_EXPIRED` | O certificado selecionado está fora do período de vigência. |
+{
-| `CERTIFICATE_INVALID` | O certificado é inválido ou corrompido. |
+  "version": "1",
-| `PRIVATE_KEY_NOT_AVAILABLE` | Chave privada inacessível ou ausente. |
+  "request_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
-| `TOKEN_NOT_FOUND` | Nenhum dispositivo ou leitor compatível foi localizado. |
+  "status": "error",
-| `TOKEN_REMOVED` | Dispositivo de hardware foi removido durante a assinatura. |
+  "error_code": "PIN_INCORRECT",
-| `PIN_REQUIRED` | PIN obrigatório para liberar chave privada em PKCS#11. |
+  "message": "O PIN informado para o token A3 é inválido."
-| `PIN_INCORRECT` | PIN digitado está incorreto. |
+}
-| `PKCS11_ERROR` | Falha no middleware PKCS#11 do fabricante. |
+```
-| `SIGNATURE_FAILED` | Erro durante a geração da assinatura digital. |
+
-| `APPLICATION_NOT_AUTHORIZED` | Aplicação não autorizada ou recusada pelo usuário. |
+### Mapeamento de Status HTTP
-| `REQUEST_EXPIRED` | A data/hora de validade da requisição expirou. |
+
-| `REPLAY_DETECTED` | O nonce informado já foi processado anteriormente. |
+| Código HTTP | Erro Típico | Descrição |
-| `INVALID_ORIGIN` | O cabeçalho Origin não corresponde ao cadastro da aplicação. |
+|---|---|---|
-| `UNSUPPORTED_ALGORITHM` | Algoritmo não suportado (ex: diferente de SHA256withRSA). |
+| `400 Bad Request` | `USER_CANCELLED`, `PIN_INCORRECT`, `SIGNATURE_FAILED` | Requisição malformada, cancelamento pelo usuário ou falha de PIN |
-| `USER_CANCELLED` | O usuário clicou em Cancelar ou fechou a janela de confirmação. |
+| `401 Unauthorized` | `APPLICATION_NOT_AUTHORIZED` | Aplicação não autorizada ou sem cabeçalho `X-CyberCore-AppId` |
-| `PROVIDER_NOT_AVAILABLE` | O provedor criptográfico necessário está inativo no SO. |
+| `403 Forbidden` | `INVALID_ORIGIN` | Cabeçalho `Origin` não confere com o domínio cadastrado |
-| `COMMUNICATION_ERROR` | Erro interno no agente de comunicação local. |
+| `404 Not Found` | `CERTIFICATE_NOT_FOUND`, `TOKEN_NOT_FOUND` | Certificado ou dispositivo físico ausente |
 | `409 Conflict` | `REPLAY_DETECTED` | Nonce já utilizado anteriormente na janela de validação |
 | `422 Unprocessable`| `REQUEST_EXPIRED`, `CERTIFICATE_EXPIRED` | Parâmetros sintaticamente válidos mas expirados temporalmente |
 | `500 Server Error` | `PKCS11_ERROR`, `PROVIDER_NOT_AVAILABLE` | Falha interna no middleware do fabricante ou driver criptográfico |
 | `503 Service Unavail`| `TOKEN_REMOVED`, `COMMUNICATION_ERROR` | Hardware desconectado ou serviço em recuperação |
 ---
 ## 5. Diagrama de Sequência Completo
 ```mermaid
 sequenceDiagram
    autonumber
    actor User as Usuário
    participant Browser as Aplicação Web (Browser)
    participant SDK as @cybercore/signer-sdk
    participant CCSP as CyberCore CcspServer (127.0.0.1)
    participant UI as CyberCore Desktop UI
    participant HW as Hardware Token / Windows MY
    Browser->>SDK: signer.sign({ digest, certId })
    SDK->>CCSP: POST /ccsp/v1/sign (Headers, AppId, Nonce, Digest)
    CCSP->>CCSP: Valida Origin, AppId e Nonce (anti-replay)
    CCSP->>UI: Solicita confirmação visual (requestSignatureConfirmation)
    UI->>User: Exibe Diálogo Nativo (Aplicação, Documento, Certificado)
    User->>UI: Clica em "Assinar"
    opt Certificado A3 exige PIN
        UI->>User: Solicita PIN do Hardware
        User->>UI: Digita PIN
    end
    UI-->>CCSP: Confirmação concedida
    CCSP->>HW: signLock.lock() -> JCA/JCE Signature.sign()
    HW-->>CCSP: Bytes da assinatura + Cadeia X.509
    CCSP->>CCSP: signLock.unlock()
    CCSP-->>SDK: 200 OK (signature Base64, cert, subject)
    SDK-->>Browser: Retorna resultado para a página web
 ```
@@ -0,0 +1,66 @@
 # Documentação Técnica — CyberCore Signer
 > **Índice Unificado e Guias Técnicos do Agente Desktop e Protocolo CCSP**
 Bem-vindo à documentação oficial do **CyberCore Signer**. O agente foi desenvolvido em Java 21+ LTS (Java 25 LTS) com interface JavaFX e segurança criptográfica nativa JCA/JCE, permitindo que aplicações web autorizadas realizem operações de assinatura digital e autenticação com certificados ICP-Brasil (A1 em arquivo e A3 em tokens/smartcards físicos) mantendo as chaves privadas estritamente no dispositivo do usuário.
 ---
 ## 🗺️ Trilhas de Navegação por Perfil
 Para facilitar a consulta, os documentos estão organizados de acordo com o seu perfil de atuação:
 ### 🌐 1. Para Desenvolvedores Web e Integradores
 Se você desenvolve aplicações web (frontend/backend) que precisam interagir com o agente do usuário:
 * **[Protocolo CCSP/1 (CyberCore Signing Protocol)](CCSP.md):** Especificação completa da API REST local (`127.0.0.1:21325`), endpoints, ciclo de handshake, proteção anti-replay e exemplos de requisição/resposta.
 * **[SDK Web JavaScript (@cybercore/signer-sdk)](sdk.md):** Manual de instalação e uso da biblioteca oficial cliente para integração em aplicações web (Vite, Next.js, Vue, Angular, Vanilla JS).
 * **[Autenticação e Login Digital ICP-Brasil](authentication-login.md):** Fluxo de autenticação segura via desafio criptográfico (*Challenge-Response*) para substituição ou complemento de senhas tradicionais.
 * **[Catálogo Estruturado de Erros](errors.md):** Lista completa de códigos de erro (`CcspErrorCode`), status HTTP correspondentes e orientações de tratamento na interface web.
 ---
 ### ☕ 2. Para Desenvolvedores Desktop e Contribuidores
 Se você atua no desenvolvimento, manutenção ou auditoria do código-fonte do agente desktop:
 * **[Arquitetura do Sistema](architecture.md):** Organização modular Maven (`cybercore-core`, `cybercore-ui`, `cybercore-app`), fluxo de dados por digest, modelo de concorrência com fila FIFO (`signLock`) e isolamento de dependências.
 * **[Certificados A1, A3 e PKCS#11](a1-a3-certificates.md):** Funcionamento dos provedores `Pkcs12CertificateProvider`, `WindowsCertificateStoreProvider` (SunMSCAPI/CNG) e `Pkcs11CertificateProvider` (SunPKCS11), monitoramento dinâmico PC/SC (`SmartCardWatcher`) e extração de OIDs ICP-Brasil.
 * **[Assinaturas PDF (PAdES) e Selos Visuais SVG](pades.md):** Motor de assinatura PDFBox + Bouncy Castle, salvamento incremental, renderização de alta resolução (300 DPI Java2D) e gerenciamento de selos digitais.
 * **[Assinaturas XML (XAdES-BES e XMLDSig)](xml-xmldsig.md):** Conformidade com o padrão ETSI TS 101 903 / DOC-ICP-15.03 e suporte a notas fiscais eletrônicas (NF-e, CT-e, MDF-e, eSocial).
 * **[Layout Dual-Theme e Assinatura em Lote](serpro-layout-and-batch.md):** Especificação de interface gráfica moderna, alternância dinâmica de tema (Claro/Escuro) e fila de processamento em lote.
 * **[Modo de Desenvolvimento](development-mode.md):** Guia de inicialização em modo `--dev`, políticas de não utilização de mocks em produção e geração de certificados A1 de teste locais.
 ---
 ### 🛡️ 3. Para DevOps, Infraestrutura e Segurança
 Se você precisa implantar, homologar ou validar os aspectos de conformidade e segurança da solução:
 * **[Modelo de Segurança e Privacidade](security.md):** Diretrizes de menor privilégio, proteção contra CSRF e DNS Rebinding, descarte seguro de senhas e PIN em memória e conformidade com a LGPD.
 * **[Instalação e Empacotamento Nativo](installation.md):** Criação de instaladores autocontidos para Windows (MSI/EXE) via `jpackage`, requisitos do sistema e parâmetros de instalação corporativa silenciosa.
 * **[Diagnóstico e Troubleshooting](diagnostics.md):** Subsistema de auto-teste, checklist de integridade de runtime e guia de resolução de problemas comuns de hardware/middleware.
 * **[Limitações Técnicas Declaradas](limitations.md):** Declaração formal de requisitos de drivers, limitações de hardware mono-thread e dependências de sistema operacional (em conformidade com a Regra 23 do projeto).
 ---
 ## 📋 Sumário Geral de Arquivos
 | Documento | Assunto Principal | Público-Alvo |
 |---|---|---|
 | [`CCSP.md`](CCSP.md) | Especificação técnica do protocolo local CCSP versão 1 | Integradores Web & Core Devs |
 | [`architecture.md`](architecture.md) | Estrutura modular, threading e fluxo de operações | Desenvolvedores Desktop |
 | [`a1-a3-certificates.md`](a1-a3-certificates.md) | Provedores A1/A3, PKCS#11, PC/SC e OIDs ICP-Brasil | Especialistas em Criptografia |
 | [`pades.md`](pades.md) | Assinatura PAdES, envelope CMS e selos vetoriais | Desenvolvedores Desktop & Web |
 | [`xml-xmldsig.md`](xml-xmldsig.md) | XAdES-BES, XMLDSig e documentos fiscais | Integradores de NF-e/XAdES |
 | [`authentication-login.md`](authentication-login.md) | Login Challenge-Response via ICP-Brasil | Integradores Web |
 | [`errors.md`](errors.md) | Tabela estruturada de erros e mapeamentos HTTP | Todos |
 | [`security.md`](security.md) | Políticas de isolamento, memória e privacidade | Segurança & Compliance |
 | [`diagnostics.md`](diagnostics.md) | Auto-testes e guia de resolução de problemas | Suporte & Operações |
 | [`installation.md`](installation.md) | Empacotamento com `jpackage` e instaladores MSI | DevOps & Usuários Finais |
 | [`limitations.md`](limitations.md) | Dependências de drivers e limitações declaradas | Todos |
 | [`development-mode.md`](development-mode.md) | Parâmetro `--dev` e certificados de teste | Desenvolvedores Desktop |
 | [`sdk.md`](sdk.md) | Guia completo da biblioteca JavaScript | Desenvolvedores Web |
 | [`serpro-layout-and-batch.md`](serpro-layout-and-batch.md) | Design de interface e processamento em lote | UI/UX & Desenvolvedores |
 ---
 > Dúvidas ou inconsistências? Verifique os testes unitários e de arquitetura em `modules/cybercore-core/src/test` ou consulte o arquivo [README.md principal](../README.md).
@@ -1,46 +1,100 @@
 # Certificados Digitais A1, A3 e PKCS#11
-O **CyberCore Signer** oferece suporte abrangente aos formatos e repositórios de certificados digitais padrão ICP-Brasil utilizados no Brasil.
+> **Guia Técnico de Suporte a Provedores Criptográficos, Hardware PC/SC e ICP-Brasil**
 O **CyberCore Signer** fornece uma camada unificada de abstração para gerenciamento e consumo de certificados digitais brasileiros padrão **ICP-Brasil**, cobrindo certificados em arquivo de software (**A1**) e dispositivos físicos criptográficos em hardware (**A3** via tokens USB e cartões inteligentes smartcards).
 ---
 ## 1. Certificados Digitais A1 (Software / PKCS#12)
-Os certificados A1 são arquivos com extensão `.pfx` ou `.p12` protegidos por senha.
+Os certificados padrão A1 são contêineres criptográficos protegidos por senha em formato `.pfx` ou `.p12`.
-### Fluxo de Uso
+### 1.1 Arquitetura e Ciclo de Vida
-1. O usuário seleciona o arquivo via diálogo nativo (`FileChooser`) na interface ou importa via tela de Dashboard.
+1. **Importação:** O usuário seleciona o arquivo via diálogo nativo (`FileChooser`) na interface ou pelo método de importação no Dashboard.
-2. É solicitada a senha em um diálogo seguro (`A1PasswordDialog`), mantida em `char[]` temporário e sobrescrita com zeros logo após a leitura da chave.
+2. **Coleta Segura de Senha:** A senha é obtida por meio do diálogo `A1PasswordDialog` e armazenada estritamente em um array de caracteres `char[]` volátil. Logo após o carregamento do `KeyStore`, o array é preenchido com zeros via `Arrays.fill(passwordChars, (char) 0)`.
-3. O provedor `Pkcs12CertificateProvider` instancia um `KeyStore.getInstance("PKCS12")` e extrai os metadados do certificado X.509 (`subject`, `issuer`, `validade`, `algoritmo`, `tamanho da chave`).
+3. **Instanciação JCA/JCE:** O provedor `Pkcs12CertificateProvider` inicializa um `KeyStore.getInstance("PKCS12")` e extrai o certificado X.509 e o manipulador da chave privada (`PrivateKey`).
-4. Durante a assinatura, a chave privada em memória gera a assinatura digital via `Signature.getInstance("SHA256withRSA")`.
+4. **Isolamento de Memória:** A chave privada nunca é serializada, exportada para disco ou enviada em logs. Durante a assinatura, a chave privada em memória gera os bytes da assinatura via `Signature.getInstance("SHA256withRSA")`.
 ---
 ## 2. Certificados Digitais A3 no Windows (Windows Certificate Store)
-No Windows 10/11, a maioria dos drivers de tokens USB e Smart Cards (ex: SafeSign, SafeNet Authentication Client, Serpro, Certisign) registra seus certificados diretamente no repositório de certificados do usuário (`Windows-MY`).
+No sistema operacional Microsoft Windows (Windows 10 e Windows 11), a grande maioria dos middlewares de fabricantes de tokens e smartcards registra os certificados automaticamente no repositório de certificados pessoais do usuário (`Windows-MY`).
-### Vantagens do Provider `WindowsCertificateStoreProvider`
+### 2.1 Funcionamento do `WindowsCertificateStoreProvider`
- Acessa certificados físicos via CryptoAPI (CAPI) e Cryptography Next Generation (CNG) através do provedor JDK `SunMSCAPI`.
+* **Integração SunMSCAPI / CNG:** O agente consome o provedor JCA nativo `SunMSCAPI` (`KeyStore.getInstance("Windows-MY")`), integrando-se diretamente à CryptoAPI e à moderna Cryptography Next Generation (CNG) do Windows.
- A chave privada permanece dentro do chip criptográfico do token.
+* **Preservação no Chip Físico:** A chave privada nunca sai do chip criptográfico do token. As operações de assinatura delegam a cifragem ao módulo de segurança em hardware (HSM/Token).
- Quando o token exige autenticação por PIN, a janela nativa do próprio driver do fabricante é invocada com segurança pelo sistema operacional Windows.
+* **Diálogo Nativo de PIN do Fabricante:** Quando o token exige autenticação por PIN para liberar a chave privada, a janela nativa do próprio driver do fabricante (ex: diálogo nativo SafeSign ou SafeNet) é exibida com total segurança pelo subsistema de segurança do Windows.
 * **Tratamento de Chaves Não Exportáveis:** O CyberCore Signer respeita integralmente a flag de chave privada não exportável, utilizando apenas referências de handle sem tentar copiar os bytes brutos da chave.
 ---
-## 3. Hardware PKCS#11 Direto (Tokens USB e Smartcards)
+## 3. Acesso Direto a Hardware PKCS#11 (Tokens USB e Smartcards)
-Para ambientes onde se deseja acesso direto ao middleware ou no Linux:
+Para ambientes corporativos que requerem comunicação direta com bibliotecas de middleware ou para execução em ambientes Linux, o componente `Pkcs11CertificateProvider` interage com o driver PKCS#11 do fabricante através do módulo do JDK `jdk.crypto.cryptoki` (`SunPKCS11`).
- `Pkcs11CertificateProvider` pesquisa bibliotecas DLL / SO padrão:
+
-  - `eps2003csp11.dll` (SafeNet / eToken)
+### 3.1 Mapeamento de Middlewares Homologados no Brasil
-  - `aetpkss1.dll` (SafeSign AET)
+
-  - `acospkcs11.dll` (ACOS / G&D)
+O CyberCore Signer possui rotinas automáticas de varredura nos diretórios padrão do sistema (`System32`, `SysWOW64` no Windows e `/usr/lib/`, `/usr/local/lib/` no Linux):
-  - `opensc-pkcs11.dll` / `opensc-pkcs11.so` (OpenSC)
+
- Utiliza o provider SunPKCS11 do JDK (`jdk.crypto.cryptoki`).
+| Fabricante / Modelo | Biblioteca Windows (DLL) | Biblioteca Linux (.so) | Tipo de Dispositivo |
 |---|---|---|---|
 | **SafeSign Identity Client** (AET / GD) | `aetpkss1.dll` | `libaetpkss.so` | Tokens e Smartcards (Certisign, Valid, Serasa) |
 | **SafeNet Authentication Client** (Gemalto / Thales) | `eps2003csp11.dll`, `eTPKCS11.dll` | `libeTPkcs11.so` | Tokens eToken Pro / 5110 (Serpro, Safeweb) |
 | **ACOS / Oberthur** (Idemia) | `acospkcs11.dll`, `OcsCryptoki.dll` | `libacospkcs11.so` | Smartcards e leitores de cartão |
 | **Watchdata / PROXKey** | `Watchdata ProxKey PKCS11.dll` | `libwatchdata.so` | Tokens USB |
 | **OpenSC (Padrão Aberto)** | `opensc-pkcs11.dll` | `opensc-pkcs11.so` | Leitores genéricos PC/SC e smartcards |
 ### 3.2 Configuração Dinâmica do Provedor SunPKCS11
 A configuração do provedor é criada dinamicamente em memória (sem gravar arquivos temporários em disco com dados sensíveis):
 ```properties
 name = CyberCore-Token
 library = C:\Windows\System32\aetpkss1.dll
 slotListIndex = 0
 ```
 ---
 ## 4. Monitoramento Dinâmico de Hardware (`SmartCardWatcher`)
-O componente `SmartCardWatcher` monitora os leitores PC/SC em segundo plano:
+O componente `SmartCardWatcher` executa um loop em segundo plano baseado na API padrão `javax.smartcardio` (subsistema PC/SC):
- **Ao inserir um token:** Atualiza a lista de certificados automaticamente e notifica a interface gráfica.
+
- **Ao remover o token:** Registra evento de auditoria (`AUDITORIA [TOKEN_REMOVED]`), limpa o cache de PIN de sessão em `PinSessionManager` e força um warm reset via `SmartCardSessionManager`.
+1. **Detecção de Conexão (Card Inserted):**
   - Detecta quando um novo smartcard ou token USB é conectado a qualquer leitora do sistema.
   - Dispara recarregamento assíncrono do repositório de certificados.
   - Notifica a interface gráfica (`UIEventListener`) e emite evento de auditoria (`AUDITORIA [TOKEN_INSERTED]`).
 2. **Detecção de Desconexão (Card Removed):**
   - Ao detectar a remoção do dispositivo, registra imediatamente o evento de auditoria `AUDITORIA [TOKEN_REMOVED]`.
   - Limpa e zera os buffers de memória de PIN mantidos pelo `PinSessionManager`.
   - Força o encerramento das conexões com o leitor via `SmartCardSessionManager` para liberar handles travados no sistema operacional.
 3. **Serialização de Concorrência (`signLock`):**
   - Como grande parte dos drivers de smartcard e chips criptográficos físicos não suporta acesso concorrente multi-thread, todas as requisições de assinatura são processadas de forma estritamente sequencial (fila FIFO garantida por `ReentrantLock`).
 ---
 ## 5. Extração e Parsing de Identidade ICP-Brasil (OIDs X.509)
 O CyberCore Signer implementa o analisador de extensões X.509 conforme os padrões da **Infraestrutura de Chaves Públicas Brasileira (ICP-Brasil)** estabelecidos pelo ITI (normas DOC-ICP-04).
 As informações são extraídas da extensão `SubjectAlternativeName` (OID `2.5.29.17`) e analisadas a partir de seus identificadores de objeto (OIDs):
 ### 5.1 OID ICP-Brasil de Pessoa Física (e-CPF) — `2.16.76.1.3.1`
 Contém uma estrutura ASN.1 com as informações cadastrais do titular:
 * **Data de Nascimento:** 8 caracteres no formato `DDMMAAAA`;
 * **CPF do Titular:** 11 dígitos numéricos;
 * **Número do NIS/PIS/PASEP:** 11 dígitos numéricos;
 * **Registro Geral (RG):** Número do documento de identidade;
 * **Órgão Expedidor e UF:** Identificação do órgão emissor.
 ### 5.2 OID ICP-Brasil de Pessoa Jurídica (e-CNPJ) — `2.16.76.1.3.3`
 Contém os dados cadastrais da empresa e do seu representante legal:
 * **CNPJ da Entidade:** 14 dígitos numéricos;
 * **Nome do Responsável:** Nome completo do signatário cadastrado na Receita Federal.
 ### 5.3 Demais OIDs Mapeados
 * **OID `2.16.76.1.3.2`:** Título de Eleitor, zona e seção eleitoral.
 * **OID `2.16.76.1.3.4`:** Cadastro Específico do INSS (CEI / CAEPF).
 Essa extração permite ao agente preencher automaticamente o nome e documento do signatário para o SDK Web e selos visuais em PDF, garantindo conformidade com a legislação e auditoria fiscal.
@@ -1,12 +1,14 @@
 # Arquitetura do CyberCore Signer
-O **CyberCore Signer** é um agente desktop nativo desenvolvido em Java 21+ LTS (Java 25 LTS) com interface JavaFX e segurança criptográfica JCA/JCE pura, projetado para permitir que aplicações web autorizadas solicitem assinaturas digitais ICP-Brasil padrão **A1** e **A3** diretamente da máquina do usuário.
+> **Especificação da Arquitetura Modular, Modelo de Threads e Fluxo Criptográfico**
 O **CyberCore Signer** foi concebido a partir de princípios de alta coesão, baixo acoplamento e estrito isolamento de camadas. O software é desenvolvido em **Java 21+ LTS (Java 25 LTS)**, utilizando o runtime modular do JDK, JavaFX para a camada de apresentação e os provedores JCA/JCE da plataforma para operações criptográficas seguras.
 ---
 ## 1. Visão Geral da Arquitetura em Módulos
-O projeto adota uma arquitetura desacoplada em múltiplos módulos Maven independentes:
+O projeto adota uma divisão modular rigorosa no Maven, garantindo que regras de negócio e algoritmos de criptografia nunca se acoplem a componentes visuais:
 ```
 cybercore-signer/
@@ -19,43 +21,75 @@ cybercore-signer/
 └── docs/                       # Especificações técnicas e manuais de integração
 ```
-### 1.1 `cybercore-core`
+### 1.1 Módulo `cybercore-core` (Agnóstico de UI)
- **Domínio:** Modelos imutáveis como `ManagedCertificate`, `SigningContext`, `SigningResult`, `CertificateType` e `CertificateStatus`.
+O módulo de núcleo é totalmente independente de JavaFX ou bibliotecas visuais:
- **Criptografia:** `SigningService` e `DigestAlgorithm` utilizando exclusivamente os provedores padrão JCA/JCE (sem reimplementação manual de algoritmos).
+* **Domínio Imutável:** Modelos imutáveis (`ManagedCertificate`, `SigningContext`, `SigningResult`, `CertificateType`, `CertificateStatus`).
- **Provedores:** Abstração `CertificateProvider` com implementações:
+* **Serviços de Assinatura:** `SigningService` orquestra a aplicação de algoritmos certificados (`SHA256withRSA`) delegando a operação ao provedor de certificado resolvido.
-  - `Pkcs12CertificateProvider`: leitura de arquivos `.pfx`/`.p12` em memória protegida.
+* **Provedores de Certificados (`CertificateProvider`):** Abstração que unifica:
-  - `WindowsCertificateStoreProvider`: integração nativa com o repositório de chaves do Windows (`Windows-MY` via SunMSCAPI/CNG).
+  - `Pkcs12CertificateProvider`: leitura de arquivos `.pfx`/`.p12` em memória com limpeza volátil de senha.
-  - `Pkcs11CertificateProvider`: integração com drivers de middleware e tokens USB/Smartcards via `SunPKCS11`.
+  - `WindowsCertificateStoreProvider`: integração com o repositório nativo do Windows (`Windows-MY` via SunMSCAPI/CNG).
- **Protocolo & Rede Local:** `CcspServer` escuta estritamente em `127.0.0.1:21325`, fornecendo a API REST CCSP/1.
+  - `Pkcs11CertificateProvider`: integração direta com bibliotecas dinâmicas (DLL/SO) de drivers e tokens USB através do SunPKCS11.
- **Segurança & Configurações:** `ApplicationRegistry`, `NonceManager` (proteção anti-replay), `OriginValidator`, `SmartCardSessionManager` e `AgentConfigurationService` (persistência em `~/.cybercore/config.json`).
+* **Protocolo e Rede Local:** `CcspServer` escuta exclusivamente em `127.0.0.1:21325`, fornecendo a API REST CCSP/1 com validação de origens e controle de concorrência.
- **Validação Criptográfica:** `SignatureValidationService` com suporte a Assinaturas Incorporadas (PAdES PDF, CMS/P7M com conteúdo embutido, XMLDSig) e Assinaturas Destacadas (Detached CMS/P7S).
+* **Segurança e Persistência:** `ApplicationRegistry`, `NonceManager` (proteção anti-replay), `OriginValidator`, `SmartCardSessionManager` e `AgentConfigurationService` com armazenamento persistente em diretório de usuário (`~/.cybercore/`).
- **Selos Visuais Personalizados:** `CustomSealStorage` (persistência em `~/.cybercore/seals/`), `PdfSealThemeRegistry` dinâmico e `CpfDisplayMode` (privacidade LGPD).
+* **Assinatura de Documentos e Validação:** `PdfSigningService` (PAdES com salvamento incremental e carimbo TSA via PDFBox e Bouncy Castle), `XmlSigningService` (XAdES-BES e XMLDSig via `javax.xml.crypto`) e `SignatureValidationService` para conferência de integridade e signatários.
-### 1.2 `cybercore-ui`
+### 1.2 Módulo `cybercore-ui` (Apresentação JavaFX)
- Interface desenvolvida com JavaFX 25, empregando layout moderno e simétrico de grade 3x3 de operações e coluna lateral de utilitários:
+Responsável por toda a interação com o usuário:
-  - `MainAppView`: grade 3x3 otimizada:
+* **Interface Principal (`MainAppView`):** Painel de navegação moderno com alternador dinâmico de tema (Claro/Escuro), grade 3x3 de operações rápidas (PDF, XML, Arquivo Genérico, Assinatura em Lote, Assinatura Atachada, Co-Assinatura, Carimbo de Tempo, Designer de Selos, Validador) e coluna lateral de utilitários (Logs em tempo real, Configurações e Diagnóstico).
-    - Linha 0: Assinar PDF, Assinar XML, Assinatura Atachada
+* **Diálogos de Consentimento e PIN:** Modais nativos de aprovação visual para requisições do protocolo CCSP/1 (`SignatureConfirmationDialog`, `ApplicationAuthorizeDialog`) e coleta segura de PIN de tokens (`A1PasswordDialog`).
-    - Linha 1: Co-Assinar Documento, Carimbo do Tempo, Gerenciar Selos
+* **Designer de Selos Digitais (`SealDesignerDialog`):** Ferramenta com Live Preview para criação de selos visuais com controle de cores, estilo de brasão, exibição de nome completo sem truncamento e privacidade de CPF.
-    - Linha 2: Validar Assinatura, Validar Carimbo, Sair do Agente
+* **Bandeja do Sistema (System Tray):** Execução minimizada com menu de contexto rápido para restauração da tela ou encerramento da sessão.
  - `SealDesignerDialog`: criador e instalador de selos digitais personalizados com pré-visualização ao vivo (Live Preview), seletores de cores, estilos de emblema, obrigatoriedade de nome completo, controle de mascaramento de CPF e estampa de data/hora.
  - `SignatureValidationDialog`: diálogo de validação criptográfica real com alternância entre Assinatura Incorporada e Assinatura Destacada, extração de documento embutido e relatório de signatários.
  - `PdfSignDialog`: modal de assinatura PAdES com posicionamento por clique na folha, atalho direto para criar/instalar selos e opções dinâmicas de CPF/data-hora.
  - `SettingsView`: configurações gerais persistentes, política de PIN e gerenciamento de selos instalados.
-### 1.3 `cybercore-app`
+### 1.3 Módulo `cybercore-app` (Orquestração e Bootstrap)
- Main bootstrap (`CyberCoreSignerApplication`).
+Ponto de partida da aplicação (`CyberCoreApp`):
- Tratamento de parâmetros de inicialização (`--dev`, `--headless`).
+* Processa argumentos de linha de comando (`--dev`, `--headless`).
- Execução de diagnósticos preliminares de ambiente e engine criptográfica antes do início das threads de escuta.
+* Executa rotinas de diagnóstico pré-inicialização do ambiente Java e disponibilidade criptográfica.
- Geração de Fat JAR autocontido via `maven-shade-plugin` e preparação para distribuição `jpackage`.
+* Inicia o `CcspServer` em segundo plano e abre a interface gráfica na `JavaFX Application Thread`.
 * Empacota o executável consolidado via `maven-shade-plugin` e orquestra o build nativo via `jpackage`.
 ---
-## 2. Fluxo de Dados e Princípio de Menor Privilégio
+## 2. Modelo de Threads e Concorrência
-O CyberCore Signer opera sob o **modelo de assinatura descentralizada por digest**:
+Para manter a interface gráfica sempre fluida e ágil, o CyberCore Signer utiliza um particionamento rígido de threads:
-1. A aplicação web calcula o hash criptográfico SHA-256 no próprio navegador utilizando a Web Crypto API nativa.
+
-2. Apenas o hash Base64 de 32 bytes trafega localmente para o CyberCore Signer.
+```mermaid
-3. O documento completo nunca sai do navegador e a chave privada nunca sai do computador ou do hardware do usuário.
+graph TD
    subgraph UI Layer
        JFX[JavaFX Application Thread]
    end
    subgraph Local Protocol Layer
        HTTPPool[CcspServer Worker Pool (FixedThreadPool 8)]
    end
    subgraph Background Services
        Watcher[SmartCardWatcher Thread (PC/SC Loop)]
        AsyncTasks[JavaFX Task / CompletableFuture Workers]
    end
    subgraph Hardware Critical Section
        Lock[Trava Serializada FIFO: signLock]
        Hardware[Token Físico A3 / SmartCard Driver]
    end
    HTTPPool -->|Solicita Aprovação Visual| JFX
    JFX -->|Consentimento Concedido| HTTPPool
    HTTPPool --> Lock
    AsyncTasks --> Lock
    Lock --> Hardware
 ```
 1. **JavaFX Application Thread:** Dedicada exclusivamente à renderização da interface e tratamento de eventos visuais. Nenhuma operação criptográfica, leitura de disco ou chamada de rede é executada nesta thread.
 2. **CcspServer Worker Pool:** Pool de 8 threads daemon dedicadas ao atendimento de requisições HTTP da API REST CCSP/1.
 3. **SmartCardWatcher Thread:** Thread daemon isolada que executa `cardTerminal.waitForCardPresent()` e `waitForCardAbsent()` para monitorar hardware PC/SC sem onerar a CPU.
 4. **Trava Serializada FIFO (`signLock`):** Implementada via `ReentrantLock(true)`. Garante que operações de assinatura em cartões inteligentes físicos sejam enfileiradas ordenadamente, prevenindo falhas de hardware e estados corrompidos em drivers de fabricantes mono-thread.
 ---
 ## 3. Fluxo de Dados e Assinatura Descentralizada por Digest
 A arquitetura do CyberCore Signer prioriza a privacidade e o modelo de **assinatura por digest**:
 ```mermaid
 sequenceDiagram
@@ -66,14 +100,25 @@ sequenceDiagram
    participant UI as CyberCore JavaFX
    participant Crypto as SigningService & Providers
-    Web->>CCSP: POST /ccsp/v1/sign (digest, appId, certHint, nonce)
+    Web->>CCSP: POST /ccsp/v1/sign (digest, appId, certHint, nonce, expires_at)
-    CCSP->>CCSP: Valida autorização, nonce anti-replay e digest
+    CCSP->>CCSP: Valida autorização, nonce anti-replay e integridade do digest
    CCSP->>UI: Solicita confirmação visual (requestSignatureConfirmation)
-    UI->>Usuario: Exibe Diálogo (Hash, Certificado, Aplicação)
+    UI->>Usuario: Exibe Diálogo Nativo (Nome do Documento, Hash SHA-256, Certificado)
-    Usuario->>UI: Aprova assinatura (e insere PIN se A3)
+    Usuario->>UI: Clica em "Autorizar Assinatura" (e digita PIN se requerido)
    UI-->>CCSP: Confirmação concedida
-    CCSP->>Crypto: sign(SigningContext) [Trava FIFO]
+    CCSP->>Crypto: sign(SigningContext) sob signLock.lock()
    Crypto->>Crypto: JCA/JCE Signature.update(digest) + sign()
    Crypto-->>CCSP: SigningResult (signatureBytes, certChain)
-    CCSP-->>Web: JSON { status: "signed", signature: "...", certificate: "..." }
+    CCSP-->>Web: 200 OK JSON { status: "signed", signature: "Base64", certificate: "Base64" }
 ```
 ---
 ## 4. Persistência de Dados e Configurações
 Todos os dados de configuração e personalizações do usuário são armazenados no diretório do usuário no sistema operacional:
 * **Diretório Base:** `~/.cybercore/` (ou `%USERPROFILE%\.cybercore\` no Windows).
 * **`config.json`:** Configurações globais do agente (política de cache de PIN, tema padrão, selo padrão ativo).
 * **`authorized-apps.json`:** Registro de aplicações web autorizadas pelo usuário, contendo `application_id`, nome amigável e data da aprovação.
 * **`seals/*.json`:** Selos visuais SVG personalizados criados ou importados pelo usuário no designer de selos.
@@ -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)
+ CYBERCORE SIGNER — MODO DE DESENVOLVIMENTO ATIVADO (--dev)
- Logs detalhados ativos. Operação com certificados reais.
+ 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:**
+### Passo 1: Gerar a Chave Privada RSA (2048 bits)
-   - Adicione um certificado A1 `.pfx` ou `.p12` emitido por uma autoridade de teste ou autoassinado.
+```bash
-   - Pela interface desktop, clique no botão **"Importar A1 (.pfx/.p12)"** no Dashboard e informe o arquivo e a senha.
+openssl genrsa -out teste_signer.key 2048
-   - O certificado ficará disponível imediatamente para todas as operações CCSP/1.
+```
-2. **Repositório Nativo do Windows (Windows-MY):**
+### Passo 2: Gerar o Certificado X.509 Autoassinado
-   - Instale o certificado no repositório de certificados pessoais do Windows (`certmgr.msc`).
+```bash
-   - O provedor `WindowsCertificateStoreProvider` detectará o certificado automaticamente.
+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):**
+### Passo 3: Exportar o Certificado e Chave no Contêiner PKCS#12 (`.pfx`)
-   - Conecte o dispositivo físico com middleware homologado (SafeSign, GD Burti, SafeNet, OpenSC, etc.).
+```bash
-   - O provedor `Pkcs11CertificateProvider` detectará o token e seus slots.
+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.
+O repositório do CyberCore Signer conta com suíte abrangente de testes unitários, testes de concorrência e testes de arquitetura (ArchUnit):
-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.
+```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.
@@ -1,34 +1,103 @@
-# Diagnóstico de Ambiente e Auto-Teste
+# Diagnóstico de Ambiente e Resolução de Problemas
-O **CyberCore Signer** possui um subsistema nativo de diagnóstico integrado (`DiagnosticService`), permitindo auditoria detalhada de saúde e integridade técnica da máquina do usuário.
+> **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 no Diagnóstico
+## 1. Itens Inspecionados pelo Diagnóstico Automático
-Ao abrir a aba **Diagnóstico** na interface ou invocar `diagnosticService.runDiagnostic()`, o agente avalia:
+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:**
+1. **Ambiente Java / Runtime Nativo:**
   - Versão do Java (requer Java 21+ LTS, homologado em Java 25 LTS);
-   - Vendor do JDK (Temurin, Oracle, etc.);
+   - Vendor do JDK (Eclipse Temurin, Oracle OpenJDK, Amazon Corretto);
-   - Arquitetura do processador e sistema operacional.
+   - 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 ao algoritmo de hash `SHA-256`;
+   - Suporte aos algoritmos de hash criptográfico (`SHA-256`, `SHA-512`);
-   - Suporte ao algoritmo de assinatura `SHA256withRSA`.
+   - Suporte aos algoritmos de assinatura digital (`SHA256withRSA`).
-3. **Repositório de Chaves do Sistema Operacional:**
+3. **Repositório de Certificados do Sistema Operacional:**
-   - Detecção do repositório `Windows-MY` (Windows CryptoAPI / CNG).
+   - Detecção do repositório de chaves `Windows-MY` via SunMSCAPI / CryptoAPI / CNG.
-4. **Middlewares PKCS#11 e SmartCard:**
+4. **Middlewares PKCS#11 e Subsistema PC/SC:**
-   - Verificação de bibliotecas de smartcard registradas no sistema (`eps2003csp11.dll`, `aetpkss1.dll`, `opensc-pkcs11.dll`, etc.);
+   - Presença das bibliotecas dinâmicas do fabricante (`aetpkss1.dll`, `eps2003csp11.dll`, `acospkcs11.dll`, `opensc-pkcs11.dll`);
-   - Disponibilidade do subsistema PC/SC `javax.smartcardio`.
+   - 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 aba de diagnóstico disponibiliza o botão **"Executar Auto-teste de Assinatura"**:
+A tela de diagnóstico oferece a função **"Executar Auto-teste de Assinatura"**:
-1. Seleciona o primeiro certificado operacional disponível na máquina.
+1. O agente identifica o primeiro certificado digital operacional conectado.
-2. Gera um hash SHA-256 interno de teste: `"Documento_Teste_CyberCore_<timestamp>"`.
+2. Gera um hash SHA-256 interno sintético para teste: `"Documento_Teste_CyberCore_<timestamp>"`.
-3. Abre o diálogo de confirmação visual para validação do usuário.
+3. Abre o diálogo nativo de confirmação visual para validação do usuário.
-4. Executa a assinatura real JCA/JCE e afere os bytes gerados.
+4. Executa a assinatura real através do provedor JCA/JCE correspondente (solicitando PIN se A3).
-5. Emite relatório de sucesso com tempo decorrido e tamanho da assinatura.
+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
 ```
@@ -1,28 +1,80 @@
 # Catálogo Estruturado de Erros
-O **CyberCore Signer** adota um sistema unificado e determinístico de códigos de erro (`CcspErrorCode`) compartilhados entre o agente Java desktop, o protocolo CCSP/1 e o SDK Web em JavaScript.
+> **Especificação Unificada de Códigos de Erro (`CcspErrorCode`), Status HTTP e Tratamento no SDK**
 O **CyberCore Signer** adota uma taxonomia estrita e estável de erros estruturados, garantindo que o agente desktop Java, a API REST do protocolo CCSP/1 e o SDK JavaScript manipulem falhas com previsibilidade e sem expor detalhes internos sensíveis ao usuário final.
 ---
-## 1. Tabela de Erros Estruturados
+## 1. Tabela Completa de Códigos de Erro
-| Código de Erro | Descrição Detalhada | Ação Recomendada para a Aplicação Web |
+| Código de Erro (`CcspErrorCode`) | Status HTTP | Descrição do Erro | Ação Recomendada para a Aplicação Web |
-|---|---|---|
+|---|---|---|---|
-| `CERTIFICATE_NOT_FOUND` | O certificado indicado pelo `certificate_hint` não foi localizado. | Solicite ao usuário selecionar novamente o certificado via `getCertificates()`. |
+| `CERTIFICATE_NOT_FOUND` | `404 Not Found` | O certificado indicado pelo `certificate_hint` não foi localizado na máquina. | Solicitar ao usuário selecionar novamente o certificado via `getCertificates()`. |
-| `CERTIFICATE_EXPIRED` | O certificado selecionado expirou. | Oriente o usuário a renovar o certificado digital junto à autoridade certificadora. |
+| `CERTIFICATE_EXPIRED` | `422 Unprocessable` | O certificado digital selecionado ultrapassou sua data limite de validade. | Orientar o usuário a renovar o certificado digital junto à autoridade certificadora (AC). |
-| `CERTIFICATE_INVALID` | O certificado possui estrutura corrompida ou ainda não é válido. | Verificar a data e integridade do arquivo/dispositivo. |
+| `CERTIFICATE_INVALID` | `400 Bad Request` | Estrutura ASN.1/X.509 corrompida ou ainda não iniciada (`NotBefore`). | Verificar integridade do arquivo `.pfx` ou relógio do sistema operacional. |
-| `PRIVATE_KEY_NOT_AVAILABLE` | O certificado está presente mas a chave privada não está acessível. | Em tokens A3, verifique se o middleware/driver está instalado corretamente. |
+| `PRIVATE_KEY_NOT_AVAILABLE` | `404 Not Found` | O certificado está presente mas a chave privada não está acessível no repositório. | Em tokens A3, verificar se o middleware/driver do token está instalado corretamente. |
-| `TOKEN_NOT_FOUND` | Nenhum dispositivo ou leitor compatível foi localizado. | Solicite ao usuário conectar o token USB ou inserir o smartcard no leitor. |
+| `TOKEN_NOT_FOUND` | `404 Not Found` | Nenhum dispositivo criptográfico físico ou leitora de cartão foi detectado. | Solicitar ao usuário conectar o token USB ou inserir o smartcard no leitor. |
-| `TOKEN_REMOVED` | O token USB ou cartão foi removido fisicamente durante a assinatura. | Peça ao usuário reconectar o token e reiniciar a operação de assinatura. |
+| `TOKEN_REMOVED` | `503 Service Unavail`| O token USB ou cartão foi desconectado fisicamente durante o processamento. | Orientar o usuário a reconectar o token e reiniciar a operação de assinatura. |
-| `PIN_REQUIRED` | O token exige PIN para liberar a chave privada e nenhum PIN foi fornecido. | Exibir campo de solicitação de PIN na tela. |
+| `PIN_REQUIRED` | `400 Bad Request` | O token exige PIN para liberar a chave privada e nenhum PIN foi informado. | Exibir campo para inserção do PIN do dispositivo. |
-| `PIN_INCORRECT` | O PIN digitado está incorreto. | Informar o usuário e alertar sobre o risco de bloqueio de PUK após 3 tentativas. |
+| `PIN_INCORRECT` | `400 Bad Request` | O PIN digitado para o token A3 é incorreto. | Alertar o usuário sobre o risco de bloqueio do cartão (PUK) após tentativas consecutivas. |
-| `PKCS11_ERROR` | Falha no driver ou biblioteca PKCS#11 do fabricante. | Verificar a instalação do SafeSign, SafeNet ou OpenSC. |
+| `PKCS11_ERROR` | `500 Server Error` | Falha na biblioteca DLL/SO do middleware ou driver do fabricante. | Verificar a instalação do SafeSign, SafeNet, GD Burti ou OpenSC. |
-| `SIGNATURE_FAILED` | Erro durante a geração dos bytes da assinatura digital. | Tentar novamente ou reiniciar o agente desktop. |
+| `SIGNATURE_FAILED` | `400 Bad Request` | Falha criptográfica na geração dos bytes da assinatura digital. | Reiniciar a operação ou verificar integridade do algoritmo especificado. |
-| `APPLICATION_NOT_AUTHORIZED` | A aplicação web teve autorização recusada pelo usuário. | Informar o usuário que é necessário aceitar a notificação na tela do agente. |
+| `APPLICATION_NOT_AUTHORIZED` | `401 Unauthorized` | A aplicação web teve autorização recusada pelo usuário ou não foi cadastrada. | Notificar o usuário que é necessário aceitar a solicitação na janela do CyberCore. |
-| `REQUEST_EXPIRED` | O timestamp ou `expires_at` da requisição expirou. | Gerar nova requisição de assinatura com timestamp atualizado. |
+| `REQUEST_EXPIRED` | `422 Unprocessable` | A validade temporal (`expires_at`) da requisição foi ultrapassada. | Gerar nova requisição de assinatura com timestamp atualizado no backend/frontend. |
-| `REPLAY_DETECTED` | O nonce informado já foi processado anteriormente. | Sempre gerar um UUID único para cada chamada de assinatura. |
+| `REPLAY_DETECTED` | `409 Conflict` | O `nonce` informado já foi processado anteriormente dentro da janela ativa. | Sempre gerar um UUID criptograficamente novo para cada chamada de assinatura. |
-| `INVALID_ORIGIN` | O cabeçalho `Origin` não confere com o cadastro da aplicação. | Conectar-se com a URL e protocolo autorizados. |
+| `INVALID_ORIGIN` | `403 Forbidden` | O cabeçalho `Origin` não confere com o domínio autorizado da aplicação. | Conectar a partir da URL e domínio homologados pelo usuário. |
-| `UNSUPPORTED_ALGORITHM` | Algoritmo solicitado não é suportado pelo agente ou certificado. | Utilizar algoritmo padrão homologado (`SHA256withRSA`). |
+| `UNSUPPORTED_ALGORITHM` | `400 Bad Request` | O algoritmo de hash ou assinatura solicitado não é suportado pelo provedor. | Utilizar os algoritmos padrão homologados (`SHA256withRSA`). |
-| `USER_CANCELLED` | O usuário clicou em Cancelar ou fechou a janela do CyberCore. | Tratar como cancelamento voluntário sem mensagem de erro alarmante. |
+| `USER_CANCELLED` | `400 Bad Request` | O usuário clicou em Cancelar ou fechou o diálogo nativo de confirmação. | Tratar como cancelamento voluntário do usuário sem exibir alerta de erro crítico. |
-| `PROVIDER_NOT_AVAILABLE` | O provedor criptográfico necessário não está ativo no sistema operacional. | Verificar a integridade do Windows Certificate Store ou Java Runtime. |
+| `PROVIDER_NOT_AVAILABLE` | `500 Server Error` | O provedor criptográfico necessário não está ativo no sistema operacional. | Verificar o Windows Certificate Store ou bibliotecas de runtime do Java. |
-| `COMMUNICATION_ERROR` | Erro interno de socket ou timeout de rede local. | Verificar se a porta `21325` não está bloqueada por antivírus local. |
+| `COMMUNICATION_ERROR` | `503 Service Unavail`| Erro de socket, timeout na confirmação visual ou porta ocupada. | Verificar se o CyberCore Signer está em execução e se a porta `21325` está livre. |
 ---
 ## 2. Estrutura do Payload JSON de Erro
 Em qualquer resposta com status diferente de `200 OK`, o payload retornado pela API CCSP/1 adota o seguinte formato:
 ```json
 {
  "version": "1",
  "request_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "status": "error",
  "error_code": "PIN_INCORRECT",
  "message": "O PIN informado para o token A3 é incorreto."
 }
 ```
 ---
 ## 3. Tratamento Tipado no SDK JavaScript
 No SDK `@cybercore/signer-sdk`, cada código estruturado possui uma classe de erro correspondente herdando de `CyberCoreError`:
 ```javascript
 import {
  UserCancelledError,
  PinIncorrectError,
  TokenNotFoundError,
  CertificateNotFoundError
 } from '@cybercore/signer-sdk/errors';
 try {
  const result = await signer.sign({
    certificateId: cert.id,
    digest: documentoDigest
  });
 } catch (error) {
  if (error instanceof UserCancelledError) {
    console.info('Assinatura cancelada voluntariamente pelo usuário.');
  } else if (error instanceof PinIncorrectError) {
    alert('PIN incorreto! Verifique a senha do seu token para evitar o bloqueio.');
  } else if (error instanceof TokenNotFoundError) {
    alert('Dispositivo não detectado. Por favor, conecte seu token USB na porta do computador.');
  } else if (error instanceof CertificateNotFoundError) {
    alert('O certificado selecionado não foi encontrado ou expirou.');
  } else {
    console.error('Erro na operação de assinatura:', error.message);
  }
 }
 ```
@@ -1,43 +1,99 @@
 # Instalação e Empacotamento Nativo
-O **CyberCore Signer** foi projetado para distribuição sem exigir que o usuário final tenha o Java ou JRE instalado em seu computador.
+> **Guia de Distribuição com Runtime Embutido (`jpackage`), Instaladores MSI e Implantação Corporativa**
 O **CyberCore Signer** foi projetado para distribuição nativa através da ferramenta `jpackage` (introduzida no JDK 14 e consolidada nas versões LTS 21/25). Isso significa que o usuário final **não precisa instalar o Java ou configurar variáveis de ambiente (JRE/JDK)** em sua máquina. O aplicativo carrega um runtime Java reduzido e isolado exclusivamente para sua execução.
 ---
 ## 1. Requisitos de Sistema
- **Sistema Operacional Homologado:** Windows 10 (64-bit) ou Windows 11 (64-bit).
+* **Sistema Operacional Alvo:** Windows 10 (64-bit) ou Windows 11 (64-bit).
- **Compatibilidade Adicional:** Linux x86_64 e macOS (arquitetura preparada).
+* **Compatibilidade Adicional:** Distribuições Linux modernas x86_64 (Ubuntu 20.04+, Debian 11+, Fedora 38+, RHEL 9+).
- **Hardware:** Mínimo de 4 GB RAM, 150 MB de espaço em disco.
+* **Memória RAM:** Mínimo de 4 GB (Recomendado: 8 GB).
- **Porta de Rede Local:** A porta TCP `21325` deve estar livre em `127.0.0.1`.
+* **Espaço em Disco:** 180 MB livres para os arquivos da aplicação e runtime embutido.
 * **Rede Local:** A porta TCP `21325` deve estar livre no endereço de loopback `127.0.0.1`.
 ---
 ## 2. Geração do Instalador Windows (MSI / EXE) com `jpackage`
-O empacotamento utiliza a ferramenta nativa `jpackage` incluída no JDK 21/25.
+### 2.1 Pré-requisitos para a Máquina de Build
 Para compilar e gerar o pacote de instalação no Windows:
 1. **JDK 21+ LTS:** Com a variável `JAVA_HOME` devidamente configurada.
 2. **WiX Toolset (v3.11+):** Necessário pelo `jpackage` para gerar instaladores `.msi`. Baixe em [wixtoolset.org](https://wixtoolset.org/) e adicione a pasta `bin` ao `PATH`.
 ### 2.2 Execução do Script de Empacotamento
 Na raiz do projeto, execute o script em lote:
 ### No Windows:
 Execute o script em lote localizado na raiz:
 ```cmd
 scripts\package-windows.bat
 ```
-### O que o script realiza:
+Ou execute manualmente os comandos do pipeline:
-1. Compila o projeto em modo release:
+
-   ```cmd
+```cmd
-   mvnw clean package -DskipTests
+:: 1. Compilação do projeto e geração do Fat JAR consolidado
-   ```
+mvnw clean package -DskipTests
-2. Invoca o `jpackage` criando o instalador Windows:
+
-   - Extrai um runtime mínimo customizado contendo apenas os módulos necessários (`java.base`, `java.desktop`, `java.smartcardio`, `jdk.crypto.cryptoki`, etc.).
+:: 2. Geração do instalador nativo via jpackage
-   - Cria atalhos na Área de Trabalho e no Menu Iniciar.
+jpackage ^
-   - Gera um instalador padrão MSI ou EXE em `dist/`.
+  --type msi ^
  --name "CyberCore Signer" ^
  --app-version 0.1.0 ^
  --vendor "CyberCore Systems" ^
  --input modules\cybercore-app\target ^
  --main-jar cybercore-signer.jar ^
  --main-class br.com.cybercore.signer.app.CyberCoreApp ^
  --icon assets\cybercore.ico ^
  --win-menu ^
  --win-shortcut ^
  --win-dir-chooser ^
  --dest dist
 ```
 O instalador `CyberCore Signer-0.1.0.msi` será gerado dentro da pasta `dist/`.
 ---
-## 3. Instalação e Inicialização com o Sistema
+## 3. Empacotamento para Linux (DEB / RPM / AppImage)
-1. Execute o instalador `CyberCore-Signer-0.1.0.msi`.
+No ambiente Linux x86_64:
-2. Siga as instruções do assistente de instalação.
+
-3. Ao concluir, o ícone do **CyberCore Signer** aparecerá na Área de Notificação (System Tray) ao lado do relógio do Windows.
+```bash
-4. O serviço local `http://127.0.0.1:21325` estará imediatamente disponível para atender as aplicações web autorizadas.
+# Executar o script nativo:
 ./scripts/package-jpackage.sh
 ```
 O script utiliza o `jpackage` com o parâmetro `--type deb` ou `--type app-image`, empacotando os binários nativos e dependências do JavaFX com suporte ao subsistema gráfico X11/Wayland.
 ---
 ## 4. Implantação Corporativa e Instalação Silenciosa
 Para administradores de rede (AD / GPO / SCCM / Intune) que precisam instalar o agente em centenas de estações de trabalho de forma automatizada:
 ### Instalação Silenciosa via Linha de Comando (MSI):
 ```cmd
 msiexec /i "CyberCore Signer-0.1.0.msi" /qn /norestart
 ```
 ### Instalação com Registro de Log de Auditoria:
 ```cmd
 msiexec /i "CyberCore Signer-0.1.0.msi" /qn /l*v "C:\Temp\cybercore_install.log"
 ```
 ### Desinstalação Silenciosa:
 ```cmd
 msiexec /x "CyberCore Signer-0.1.0.msi" /qn /norestart
 ```
 ---
 ## 5. Inicialização com o Sistema e Área de Notificação (System Tray)
 1. **Atalhos Criados:** O instalador cria automaticamente atalhos no Menu Iniciar e na Área de Trabalho.
 2. **Inicialização Automática:** Durante a instalação, pode ser adicionada uma entrada no registro do Windows:
   `HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Run`
   Chave: `CyberCoreSigner` -> Caminho: `"C:\Program Files\CyberCore Systems\CyberCore Signer\CyberCore Signer.exe" --minimized`
 3. **Área de Notificação:** Quando iniciado, o agente minimiza para a bandeja do sistema (System Tray) ao lado do relógio do Windows, garantindo que o servidor local `127.0.0.1:21325` esteja sempre pronto para atender as solicitações das aplicações web homologadas.
@@ -1,25 +1,42 @@
 # Limitações Técnicas e Dependências Declaradas
-Conforme estabelecido na **Regra 23** do projeto (*"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"*), as seguintes limitações são formalmente declaradas:
+> **Declaração Formal de Dependências de Plataforma, Limitações de Hardware e Concorrência (Regra 23)**
 Em estrita conformidade com a **Regra 23** do projeto CyberCore Signer (*"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"*), as seguintes limitações técnicas e dependências são formalmente declaradas:
 ---
-## 1. Dependências de Sistema Operacional e Hardware
+## 1. Dependências de Sistema Operacional e Repositório Nativo
-1. **Windows Certificate Store (Windows-MY):**
+1. **Repositório Nativo do Windows (`Windows-MY`):**
-   - Disponível apenas em sistemas operacionais Microsoft Windows (Windows 10/11).
+   - O provedor `WindowsCertificateStoreProvider` depende exclusivamente das APIs Win32/CryptoAPI e CNG expostas pelo provedor `SunMSCAPI` do JDK.
-   - Em Linux e macOS, o provedor `WindowsCertificateStoreProvider` declara-se automaticamente indisponível (`isAvailable() == false`), operando via arquivos A1 ou PKCS#11 direto.
+   - **Disponibilidade:** Suportado exclusivamente em Microsoft Windows (Windows 10 e Windows 11).
-2. **Tokens A3 e Middlewares Proprietários:**
+   - **Comportamento em Linux e macOS:** O provedor declara-se indisponível (`isAvailable() == false`) em sistemas não-Windows, operando através de arquivos A1 (PKCS#12) ou acesso PKCS#11 direto.
-   - O reconhecimento de smartcards e tokens USB depende da instalação prévia dos drivers do fabricante do dispositivo físico (ex: SafeSign Identity Client, SafeNet Authentication Client, drivers de leitoras Gemalto/Omnikey).
+
-   - O CyberCore Signer não instala drivers de hardware nem substitui o middleware do fabricante.
+2. **Arquitetura de CPU dos Middlewares Proprietários:**
-3. **Bloqueio de Cartão por Tentativas de PIN:**
+   - A maioria dos drivers comerciais de tokens USB no Brasil (ex: SafeSign Identity Client da AET Europe e SafeNet da Thales) é compilada nativamente para a arquitetura **x86_64 (64-bit)**.
-   - A política de bloqueio por tentativas consecutivas de PIN incorreto (geralmente 3 tentativas) é governada estritamente pelo chip físico do dispositivo A3 e pelo driver do fabricante, estando fora do controle do software do agente.
+   - Ambientes executando em processadores ARM64 (como novos computadores Windows on ARM ou Apple Silicon) requerem a camada de emulação x64 do sistema operacional para carregar essas bibliotecas dinâmicas legadas.
 ---
-## 2. Limitações de Rede e Concorrência
+## 2. Dependências de Hardware e Middlewares de Terceiros
-1. **Escuta Exclusiva em Loopback:**
+1. **Tokens A3 e Leitores de Smartcard Físicos:**
-   - O agente não oferece nem oferece suporte para escuta em endereços de rede externa (IPs locais de LAN ou WAN). Essa restrição é um elemento fundamental do modelo de segurança.
+   - O CyberCore Signer **não substitui os drivers do fabricante do token**. É indispensável que os drivers de hardware e o middleware do fabricante (SafeSign, SafeNet, GD Burti, Certisign, OpenSC, etc.) estejam instalados na estação de trabalho para que o sistema operacional e a leitora USB reconheçam o chip físico.
-2. **Operações Concorrentes no Mesmo Token Físico:**
+   - O agente detecta a presença da biblioteca e interage com o dispositivo através de interfaces padronizadas (PKCS#11 ou CAPI/CNG).
-   - Drivers PKCS#11 e smartcards ICP-Brasil frequentemente operam em modo mono-thread ou canal serial exclusivo. Por essa razão, o CyberCore Signer serializa as assinaturas em fila FIFO (`signLock`) para impedir corrupção de sessão no chip do cartão.
+
 2. **Política de Bloqueio por PIN Incorreto (Controle do Chip Físico):**
   - O chip criptográfico de qualquer smartcard ou token ICP-Brasil possui um contador de segurança interno em hardware (geralmente limitado a 3 tentativas incorretas consecutivas).
   - O bloqueio do cartão e a exigência do código de desbloqueio (PUK) são governados com exclusividade pelo hardware do fabricante. O software do CyberCore Signer não tem como burlar, redefinir ou impedir esse bloqueio.
 ---
 ## 3. Concorrência e Acesso a Dispositivos Mono-Thread
 1. **Serialização Mandatória de Operações (`signLock`):**
   - A especificação PKCS#11 e a maioria das implementações de drivers de smartcard operam sob canal serial exclusivo de I/O por leitora.
   - Requisições simultâneas de assinatura contra o mesmo token físico causam erro de sessão ou congelamento no driver caso executadas em paralelo.
   - **Solução Arquitetural:** O CyberCore Signer enfileira todas as operações criptográficas através de uma trava FIFO (`signLock`), processando cada assinatura individualmente e garantindo a estabilidade do hardware.
 2. **Isolamento de Origem e Rede Loopback:**
   - O servidor local CCSP/1 vincula-se estritamente ao endereço `127.0.0.1:21325`. O agente não suporta e deliberadamente rejeita conexões de computadores remotos da rede local (LAN), priorizando a segurança e a inviolabilidade da máquina do usuário.
@@ -1,17 +1,30 @@
 # SDK Web JavaScript (@cybercore/signer-sdk)
-O `@cybercore/signer-sdk` é a biblioteca oficial cliente em JavaScript para integrar aplicações web modernas com o agente desktop **CyberCore Signer** via protocolo **CCSP/1**.
+> **Manual de Integração de Aplicações Web Modernas com o Agente Desktop CyberCore Signer**
 O **`@cybercore/signer-sdk`** é a biblioteca cliente oficial em JavaScript (TypeScript ready) desenvolvida para permitir que aplicações web modernas (React, Next.js, Vue, Angular ou JavaScript nativo) se comuniquem com o agente desktop **CyberCore Signer** através do protocolo local **CCSP/1**.
 ---
-## 1. Instalação e Importação
+## 1. Instalação e Configuração
-### Via Módulo ES6 (Browser ou Bundler Vite/Webpack/Next.js)
+### 1.1 Instalação via Gerenciador de Pacotes
 ```bash
 npm install @cybercore/signer-sdk
 # ou
 yarn add @cybercore/signer-sdk
 # ou
 pnpm add @cybercore/signer-sdk
 ```
 ### 1.2 Inicialização do Cliente
 ```javascript
 import { CyberCoreSigner } from '@cybercore/signer-sdk';
 const signer = new CyberCoreSigner({
-  applicationName: 'Portal Meu Negócio'
+  applicationName: 'Portal Meu Negócio', // Nome exibido no diálogo nativo do usuário
  port: 21325,                           // Porta padrão do agente local (opcional)
  timeoutMs: 30000                       // Timeout padrão para operações (opcional)
 });
 ```
@@ -19,99 +32,173 @@ const signer = new CyberCoreSigner({
 ## 2. Métodos da API
-### `isInstalled(timeoutMs = 2000): Promise<boolean>`
+### 2.1 Verificação de Disponibilidade e Conexão
 Testa rapidamente se o agente desktop está ativo na porta local `21325`.
-### `connect(): Promise<boolean>`
+#### `isInstalled(timeoutMs = 2000): Promise<boolean>`
-Realiza o handshake inicial de autorização. Se for a primeira vez que a aplicação tenta se conectar, abre uma caixa de diálogo nativa no desktop do usuário para concessão de acesso.
+Testa de forma rápida e silenciosa se o agente desktop está ativo na máquina do usuário.
 ### `getCertificates(): Promise<Array<Object>>`
 Retorna todos os certificados A1 e A3 disponíveis e operacionais na máquina do usuário.
 ```javascript
-const certs = await signer.getCertificates();
+const disponivel = await signer.isInstalled();
-certs.forEach(cert => {
+if (!disponivel) {
-  console.log(`[${cert.type}] ${cert.common_name} (Validade: ${cert.valid_to})`);
+  alert('O CyberCore Signer não foi detectado em sua máquina. Por favor, instale o aplicativo para continuar.');
 }
 ```
 #### `connect(): Promise<boolean>`
 Inicia o handshake de autorização com o agente. Se a aplicação ainda não foi homologada pelo usuário, abre um diálogo nativo na tela do computador para autorização expressa.
 ```javascript
 const autorizado = await signer.connect();
 if (!autorizado) {
  console.warn('O usuário recusou a autorização da aplicação.');
 }
 ```
 ---
 ### 2.2 Descoberta de Certificados Digitais
 #### `getCertificates(): Promise<Array<CertificateInfo>>`
 Retorna a lista de certificados digitais válidos e disponíveis na máquina (A1 importados e A3 conectados via USB).
 ```javascript
 const certificados = await signer.getCertificates();
 certificados.forEach(cert => {
  console.log(`[${cert.type}] ${cert.common_name}`);
  console.log(`Titular: ${cert.subject_dn}`);
  console.log(`Validade até: ${cert.valid_to}`);
  console.log(`CPF/CNPJ: ${cert.cpf || cert.cnpj}`);
 });
 ```
-### `sign(options): Promise<Object>`
+---
 Solicita a assinatura digital local de um digest ou conteúdo bruto.
-### `signPdf(pdfFile, options): Promise<Object>`
+### 2.3 Operações de Assinatura Digital
-Assina um documento PDF (PAdES / Assinatura desacoplada). Recebe `File`, `Blob`, `ArrayBuffer` ou `Uint8Array`.
+
-Calcula o SHA-256 no próprio navegador e transmite metadados do documento (`PDF`) ao agente para exibição clara na janela de confirmação.
+#### `sign(options): Promise<SignatureResult>`
 Assina o hash SHA-256 (digest) de qualquer informação. A chave privada nunca sai do computador e apenas o digest é assinado.
 ```javascript
-const pdfResult = await signer.signPdf(fileInput.files[0], {
+const resultado = await signer.sign({
-  certificateId: certs[0].id
+  certificateId: 'win-4340656a',
  digest: '47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=', // Hash SHA-256 em Base64
  documentName: 'contrato_prestacao_servicos.pdf',
  documentType: 'PDF'
 });
 console.log('Assinatura gerada (Base64):', resultado.signature);
 console.log('Certificado do signatário:', resultado.certificate);
 console.log('Cadeia de certificação:', resultado.certificate_chain);
 ```
-### `signXml(xmlContent, options): Promise<Object>`
+#### `signPdf(file, options): Promise<SignatureResult>`
-Assina um documento XML (XMLDSig / NF-e). Aceita string com o XML formatado ou objeto de arquivo `File`/`Blob`.
+Calcula o hash do documento PDF no próprio navegador e solicita a assinatura ao CyberCore Signer.
 ```javascript
-const xmlResult = await signer.signXml(xmlString, {
+const inputElement = document.getElementById('arquivo-pdf');
-  certificateId: certs[0].id,
+const arquivoPdf = inputElement.files[0];
 const resultadoPdf = await signer.signPdf(arquivoPdf, {
  certificateId: certificados[0].id
 });
 console.log('PDF assinado digitalmente com sucesso!');
 ```
 #### `signXml(xmlContent, options): Promise<SignatureResult>`
 Assina o hash de documentos XML ou notas fiscais eletrônicas (NF-e, CT-e, MDF-e, XAdES). Aceita `string` com o XML ou arquivo `File`/`Blob`.
 ```javascript
 const xmlString = '<infNFe Id="NFe3524...">...</infNFe>';
 const resultadoXml = await signer.signXml(xmlString, {
  certificateId: certificados[0].id,
  documentName: 'nfe-3524.xml'
 });
 ```
-### `signFile(file, options): Promise<Object>`
+#### `signFile(file, options): Promise<SignatureResult>`
-Assina qualquer arquivo (ZIP, DOCX, imagens, binários, executáveis) gerando pacote de assinatura detached / CAdES.
+Assina arquivos genéricos de qualquer formato (ZIP, DOCX, XLSX, imagens, binários).
 ```javascript
-const fileResult = await signer.signFile(fileInput.files[0], {
+const fileInput = document.getElementById('input-qualquer-arquivo');
-  certificateId: certs[0].id
+
 const resultadoArquivo = await signer.signFile(fileInput.files[0], {
  certificateId: certificados[0].id
 });
 ```
-### `authenticate(options): Promise<Object>` (ou `login(options)`)
+---
-Executa login seguro com certificado digital via desafio criptográfico (Challenge-Response).
+
 ### 2.4 Autenticação e Login Digital (Challenge-Response)
 #### `authenticate(options): Promise<AuthResult>`
 Realiza o login seguro de um usuário através de seu certificado digital ICP-Brasil. O backend da sua aplicação fornece um desafio único (*challenge / nonce*) e o CyberCore assina esse desafio.
 ```javascript
-const auth = await signer.authenticate({
+// 1. Obter desafio único do backend da sua aplicação
-  certificateId: certs[0].id,
+const { challenge } = await fetch('/api/auth/challenge').then(res => res.json());
-  challenge: 'server-nonce-12345'
+
 // 2. Solicitar assinatura do desafio ao CyberCore Signer
 const authResult = await signer.authenticate({
  certificateId: certificados[0].id,
  challenge: challenge
 });
-console.log('Bem-vindo,', auth.subjectName);
+// 3. Enviar a assinatura e o certificado para o backend validar e autenticar a sessão
-console.log('CPF/CNPJ:', auth.subjectCpfCnpj);
+const response = await fetch('/api/auth/validate-login', {
-console.log('Assinatura do Desafio:', auth.signature);
+  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    challenge: authResult.challenge,
    signature: authResult.signature,
    certificate: authResult.certificate
  })
 });
 if (response.ok) {
  console.log(`Login aprovado para: ${authResult.subjectName} (${authResult.subjectCpfCnpj})`);
  window.location.href = '/dashboard';
 }
 ```
 ### `extractSubjectInfo(certificateBase64): { name, cpfCnpj }`
 Decodifica o certificado X.509 e extrai os dados do titular ICP-Brasil (Nome, CPF ou CNPJ).
 ### `verify(options): Promise<boolean>`
 Validação sintática e criptográfica da integridade da assinatura gerada.
 ---
 ## 3. Tratamento Estruturado de Erros
-O SDK expõe classes de erro dedicadas que herdam de `CyberCoreError`:
+O SDK expõe classes de erro dedicadas que herdam de `CyberCoreError`, permitindo tratar cenários de forma elegante na interface:
 ```javascript
 import {
  UserCancelledError,
  CertificateNotFoundError,
  PinIncorrectError,
-  TokenNotFoundError
+  TokenNotFoundError,
  CertificateNotFoundError,
  CertificateExpiredError
 } from '@cybercore/signer-sdk/errors';
 try {
-  await signer.sign({ certificateId: 'cert-1', data: 'Contrato' });
+  const res = await signer.sign({
-} catch (err) {
+    certificateId: certId,
-  if (err instanceof UserCancelledError) {
+    digest: documentoDigest
-    alert('Você cancelou a assinatura no CyberCore Signer.');
+  });
-  } else if (err instanceof PinIncorrectError) {
+} catch (error) {
-    alert('O PIN do token informado está incorreto.');
+  if (error instanceof UserCancelledError) {
-  } else if (err instanceof TokenNotFoundError) {
+    // Usuário cancelou a assinatura voluntariamente na janela nativa
-    alert('Conecte o seu token USB na máquina para assinar.');
+    console.info('Operação cancelada pelo usuário.');
  } else if (error instanceof PinIncorrectError) {
    // PIN do token A3 incorreto
    alert('PIN incorreto! Por favor, digite o PIN correto do seu token.');
  } else if (error instanceof TokenNotFoundError) {
    // Token USB desconectado
    alert('Token não encontrado! Por favor, conecte seu dispositivo USB para assinar.');
  } else if (error instanceof CertificateExpiredError) {
    // Certificado ultrapassou a data de validade
    alert('O certificado selecionado expirou. Entre em contato com sua autoridade certificadora.');
  } else {
-    console.error('Erro na assinatura:', err);
+    // Demais falhas
    console.error('Falha na operação com o CyberCore Signer:', error);
  }
 }
 ```
@@ -1,46 +1,71 @@
 # Modelo de Segurança e Privacidade
-O **CyberCore Signer** foi projetado seguindo as diretrizes rigorosas da ICP-Brasil e os princípios de *Security by Design* e *Least Privilege*.
+> **Diretrizes de Segurança em Profundidade, Proteção Criptográfica e Conformidade LGPD**
 O **CyberCore Signer** foi concebido sob os princípios de *Security by Design* (Segurança desde a Concepção) e *Least Privilege* (Menor Privilégio), seguindo as normas da **Infraestrutura de Chaves Públicas Brasileira (ICP-Brasil)** e as exigências da **Lei Geral de Proteção de Dados (LGPD — Lei nº 13.709/2018)**.
 ---
-## 1. Isolamento de Rede
+## 1. Isolamento de Rede e Proteção Local
-1. **Loopback Estrito:** O socket do servidor HTTP local vincula-se exclusivamente ao endereço IP `127.0.0.1`. Nenhuma interface de rede externa (LAN ou WAN) escuta a porta de serviço `21325`.
+### 1.1 Ligação Estrita ao Loopback (`127.0.0.1`)
-2. **Prevenção contra Exposição Acidental:** Testes unitários e de arquitetura garantem que conexões fora de `127.0.0.1` sejam bloqueadas imediatamente no nível de bind do socket.
+O servidor HTTP do protocolo CCSP/1 vincula-se exclusivamente ao endereço IPv4 local `127.0.0.1`.
 * **Sem Escuta Externa:** O agente nunca realiza bind em `0.0.0.0` ou em interfaces de rede de área local (LAN) ou externa (WAN).
 * **Bloqueio no Socket:** Tentativas de acesso originadas fora da própria estação de trabalho são sumariamente recusadas pelo subsistema de rede do sistema operacional antes de qualquer processamento da aplicação.
 ### 1.2 Proteção Contra Ataques de DNS Rebinding
 Para neutralizar ataques em que domínios externos tentam resolver para `127.0.0.1` e burlar a política de mesma origem do navegador:
 * O `CcspServer` valida expressamente o cabeçalho HTTP `Host`.
 * Somente requisições com `Host: 127.0.0.1:21325` ou `Host: localhost:21325` são aceitas; qualquer outro valor é rejeitado com status `403 Forbidden`.
 ### 1.3 Controle de Origem (CORS) e Preflight
 * Requisições prévias HTTP `OPTIONS` são validadas contra as origens web homologadas.
 * O cabeçalho `Access-Control-Allow-Origin` é devolvido estritamente com a origem solicitante autorizada (nunca com wildcard `*`).
 ---
 ## 2. Autenticação e Autorização de Aplicações
-Nenhuma aplicação desconhecida tem autorização para obter certificados ou assinar documentos sem consentimento expresso:
+Nenhuma aplicação web externa tem acesso a certificados digitais ou serviços de assinatura sem autorização prévia e explícita do usuário:
-1. **Handshake de Autorização (`POST /ccsp/v1/authorize`):**
+1. **Handshake de Aprovação (`POST /ccsp/v1/authorize`):**
-   - A aplicação web identifica-se enviando seu `application_id` (UUID estável) e seu nome amigável.
+   - Ao tentar comunicar-se pela primeira vez, a aplicação web deve fornecer seu `application_id` (UUID estável) e seu nome amigável.
-   - O CyberCore Signer suspende a requisição e abre uma janela modal nativa na tela principal do sistema operacional perguntando se o usuário autoriza aquele domínio web.
+   - O CyberCore Signer suspende a requisição e exibe um modal nativo no desktop informando o nome da aplicação e solicitando autorização do usuário.
-2. **Armazenamento Seguro das Autorizações:**
+2. **Armazenamento Seguro de Permissões:**
-   - As aplicações autorizadas são gravadas em `~/.cybercore/authorized-apps.json`.
+   - As aplicações autorizadas são gravadas no arquivo local `~/.cybercore/authorized-apps.json`.
-   - O usuário pode visualizar e **revogar a qualquer momento** qualquer permissão através da aba **Configurações** na interface gráfica.
+   - O usuário pode visualizar e **revogar a qualquer momento** a autorização de qualquer aplicação através da aba **Configurações** na interface gráfica.
 ---
 ## 3. Proteção Contra Ataques de Replay
-Cada solicitação de assinatura enviada pelo SDK deve incluir:
+Para impedir que requisições de assinatura capturadas por softwares maliciosos na máquina sejam reenviadas:
- Um `nonce` (UUID criptograficamente aleatório);
+1. **Identificador Único (`nonce`):** Toda requisição ao `/ccsp/v1/sign` deve conter um UUID aleatório criptograficamente forte gerado pelo chamador.
- Um campo `expires_at` (ou `timestamp`).
+2. **Janela de Validade Temporal (`expires_at`):** A requisição inclui uma estampa de tempo limite (TTL).
-
+3. **Gerenciador de Nonces (`NonceManager`):**
-O componente `NonceManager`:
+   - Mantém uma estrutura em memória com os identificadores recentes;
- Armazena os nonces recentes em memória protegida com expiração temporal (TTL);
+   - Se o mesmo `nonce` for submetido mais de uma vez dentro da janela de validade, a operação é rejeitada com erro estruturado `REPLAY_DETECTED` (HTTP `409 Conflict`);
- Rejeita com código estruturado `REPLAY_DETECTED` caso o mesmo nonce seja submetido mais de uma vez;
+   - Se a data/hora atual ultrapassar `expires_at`, a operação é rejeitada com erro `REQUEST_EXPIRED` (HTTP `422 Unprocessable Entity`).
 - Rejeita com código `REQUEST_EXPIRED` requisições cuja data/hora de validade já tenha sido ultrapassada.
 ---
 ## 4. Confirmação Visual Obrigatória e Proteção de PIN/Chaves
-1. **Confirmação Manual do Usuário:** Toda e qualquer assinatura exige intervenção física e visual do usuário. Não é possível assinar "silenciosamente" por chamadas de API em segundo plano.
+1. **Assinatura Exclusivamente Assistida:** Toda operação de assinatura exige interação humana voluntária. O agente nunca assina documentos em segundo plano de forma silenciosa ou desassistida via API.
-2. **Inviolabilidade da Chave Privada:** A chave privada nunca é exportada nem manipulada em forma de bytes puros. Todas as operações utilizam handles JCA/JCE ou comandos de hardware nativo.
+2. **Inviolabilidade da Chave Privada:** As chaves privadas ICP-Brasil nunca são exportadas em formato de bytes brutos. Operações em certificados A3 utilizam handles criptográficos do hardware, garantindo que a chave nunca deixe o chip criptográfico.
-3. **Proteção de PIN e Senhas:**
+3. **Higienização Segura de Memória Volátil:**
-   - O PIN de smartcards e a senha de arquivos A1 nunca são transmitidos para a aplicação web e nunca aparecem em logs de auditoria.
+   - O PIN de smartcards e senhas de certificados A1 nunca são convertidos para strings imutáveis do Java (`java.lang.String`).
-   - Em caso de remoção do hardware, o `SmartCardWatcher` limpa e zera os buffers de memória de PIN imediatamente.
+   - São manipulados estritamente como arrays de caracteres mutáveis `char[]`.
   - Imediatamente após o carregamento da chave, o array é sobrescrito com zeros através de `Arrays.fill(pinBuffer, (char) 0)`.
 4. **Remoção de Hardware (`TOKEN_REMOVED`):** Se o usuário desconectar o token USB ou retirar o cartão do leitor durante ou após a assinatura, o `SmartCardWatcher` força a limpeza imediata do cache de sessão e dos buffers do sistema operacional.
 ---
 ## 5. Privacidade de Dados e Conformidade com a LGPD
 1. **Assinatura Descentralizada por Digest:** O CyberCore Signer opera prioritariamente recebendo apenas o hash SHA-256 do arquivo. O conteúdo completo do documento (contrato, laudo, prontuário) não transita pela API local nem é gravado em logs.
 2. **Mascaramento e Sigilo de CPF:** Nos selos visuais em PDF, o usuário pode configurar o modo de exibição de seu CPF (`CpfDisplayMode`):
   - `FULL`: Exibição completa (`123.456.789-00`);
   - `MASKED`: Dígitos sensíveis ocultados (`***.456.789-**`);
   - `NONE`: Remoção completa do CPF do gráfico visual do selo.
 3. **Auditoria e Logs Transparentes:** Os logs do agente registram apenas identificadores de correlação (`request_id`), algoritmo utilizado e status da operação, sem armazenar hashes de documentos sigilosos ou dados pessoais desnecessários.