![alt text](image.png)# Assinaturas PDF (PAdES) e Selos Visuais em SVG

Este documento descreve a arquitetura e o funcionamento da assinatura digital de arquivos PDF no padrão **PAdES (PDF Advanced Electronic Signatures)** no CyberCore Signer, incluindo o subsistema de **selos visuais temáticos baseados em SVG**.

---

## 1. Visão Geral da Arquitetura

O CyberCore Signer implementa assinatura PAdES em dois modos complementares:

1. **Modo Desacoplado via Protocolo CCSP/1 (Web):** A aplicação web prepara a estrutura `/ByteRange`, envia apenas o digest SHA-256 e o CyberCore assina localmente com o certificado A1/A3 sem expor a chave privada.
2. **Modo Desktop Completo (Desktop UI):** O usuário seleciona um arquivo PDF localmente, escolhe o certificado ICP-Brasil, customiza o selo visual e o `PdfSigningService` gera o PDF assinado completo com envelope CMS/PKCS#7 e estampa gráfica.

```mermaid
graph TD
    A[Arquivo PDF Original] --> B[PdfSigningService]
    C[Tema de Selo SVG] --> D[PdfSealRenderer Java2D]
    E[Metadados Signatário] --> D
    D -->|Estampa Visual 300 DPI| B
    F[Chave Privada A1/A3] --> G[Bouncy Castle CMS Generator]
    B -->|PAdES Incremental| H[PDF Assinado Digitalmente]
    G --> H
```

---

## 2. Subsistema de Selos Visuais em SVG e Temas

O selo visual é uma representação gráfica da assinatura estipulada em conformidade com as recomendações do ITI e MP nº 2.200-2/2001.

### 2.1 Temas Pré-configurados e Ícones Vetoriais (`PdfSealThemeRegistry` & `PdfSealRenderer`)

Os brasões e ícones padrão do sistema ficam centralizados em:
- **Catálogo de Temas:** `modules/cybercore-core/.../pdf/seal/PdfSealThemeRegistry.java` (definição de cores, dimensões, textos padrão e tipo de ícone).
- **Desenho Vetorial Java2D:** `modules/cybercore-core/.../pdf/seal/PdfSealRenderer.drawThemeIcon()` (renderização matemática em Java2D dos brasões padrão: `shield`, `star`, `crystal`, `notary`, etc.).

| ID do Tema | Nome | Descrição | Ícone Vetorial |
| :--- | :--- | :--- | :--- |
| `icp-brasil` | **ICP-Brasil Oficial** | Padrão clássico com brasão e cadeado verde/azul | Escudo e cadeado |
| `cybercore-modern` | **CyberCore Modern** | Estilo tecnológico neon com cristal multifacetado | Cristal vetorial |
| `minimal-clean` | **Minimalista Clean** | Monocromático para relatórios executivos sóbrios | Carimbo notarial com check |
| `gov-br` | **Gov.br Oficial** | Identidade visual Verde-Oliva conforme MP 2.200-2/2001 | Brasão estelar estilizado |

### 2.2 Renderização Gráfica (`PdfSealRenderer`)

- O núcleo `cybercore-core` **não depende de JavaFX**, atendendo às regras estritas de arquitetura (`ArchitectureTest`).
- A renderização é efetuada através da API **Java2D (AWT)** nativa com anti-aliasing duplo (`RenderingHints.VALUE_ANTIALIAS_ON`, subpixel text, escala 2x / 300 DPI).
- Exporta tanto `BufferedImage` quanto `byte[]` PNG para inclusão no PDFBox ou pré-visualização dinâmica na interface com `ImageView`.

### 2.3 Criação, Instalação e Privacidade de Selos Personalizados

- **Foco Exclusivo no Titular (Sem Emissor/AC no Gráfico):** O selo foi desenhado para ser limpo e elegante. Dados técnicos do certificado e o emissor da Autoridade Certificadora não são exibidos no gráfico do selo, evitando poluição visual.
- **Obrigatoriedade do Nome Completo:** O renderizador calcula dinamicamente a métrica de fontes via `drawFittedText()` para garantir que o nome completo do signatário seja sempre exibido na íntegra, com destaque tipográfico (13.5pt a 14.5pt em negrito), sem cortes ou truncamentos.
- **Upload de Logotipo / Emblema Próprio:** Suporte a upload de imagens de logotipos (PNG, JPG, BMP) armazenadas de forma portável em Base64 dentro do tema, com renderização redimensionada e anti-aliasing de 300 DPI.
- **Campos Customizáveis (Matrícula, Cargo, OAB, etc.):** Permite definir rótulo e valor padrão no tema (ex: `Matrícula: 104829/SP` ou `Cargo: Auditor Fiscal`) ou informar pontualmente durante a assinatura via `customExtraInfo`. A informação é posicionada de forma harmônica na linha de identificação do signatário.
- **Privacidade do CPF (LGPD):** O modelo `CpfDisplayMode` suporta três modalidades:
  - `FULL`: exibe o documento completo (`CPF: 123.456.789-00`).
  - `MASKED`: mascara dígitos sensíveis (`CPF: ***.456.789-**`).
  - `NONE`: oculta totalmente o CPF do gráfico do selo.
- **Data e Hora Opcional:** Parâmetro booleano para incluir ou suprimir data/hora no gráfico.
- **Instalação e Persistência Local:** Através de `CustomSealStorage`, novos selos criados ou importados são salvos em `~/.cybercore/seals/*.json` e registrados dinamicamente no `PdfSealThemeRegistry`.

### 2.4 Gerenciamento Centralizado de Selos (`SealManagementDialog`)

- **Lista Completa:** Exibição unificada de selos embutidos do sistema e selos personalizados instalados pelo usuário.
- **Selo Padrão Ativo:** Permite definir qual selo é o padrão ativo para todas as assinaturas do usuário, gravado em `AgentConfiguration` (`defaultSealThemeId`).
- **Pré-visualização em Tempo Real:** Renderização fiel do selo com dados de exemplo ao navegar pela lista.
- **Clonagem e Edição:** Permite duplicar qualquer selo (inclusive os embutidos) e abri-lo no `SealDesignerDialog` para customização.
- **Importação e Exportação:** Exportação de temas em arquivos `.json` e importação com um clique para compartilhamento entre máquinas e equipes.

---

## 3. Posicionamento e Pré-Visualização Interativa

A posição e a página da estampa são parametrizáveis via `PdfSignatureOptions`:

- **Posições Automáticas:** `BOTTOM_RIGHT`, `BOTTOM_LEFT`, `TOP_RIGHT`, `TOP_LEFT`.
- **Posição Interativa Personalizada (`CUSTOM`):** O usuário clica ou arrasta o selo diretamente sobre a página do PDF na interface gráfica. As coordenadas na tela são matematicamente mapeadas para as coordenadas de mídia do PDFBox:
  $$X_{pdf} = \frac{X_{clique}}{Largura_{view}} \times Largura_{pdf}$$
  $$Y_{pdf} = Altura_{pdf} - \left(\frac{Y_{clique}}{Altura_{view}} \times Altura_{pdf}\right) - Altura_{selo}$$
- **Páginas:** `LAST_PAGE` (recomendado), `FIRST_PAGE`, `ALL_PAGES`, ou página específica numérica (`targetPageNumber`).
- **Dimensões padrão:** 200 pt de largura por 55 pt de altura, com margens de segurança e clamping contra extravasamento.
- **Renderização da Folha:** O `PdfSigningService` fornece `renderPagePngBytes(pdfBytes, pageIndex, dpi)` via PDFBox `PDFRenderer`, permitindo que o diálogo da UI JavaFX renderize a folha de papel em background thread com paginação e sobreposição visual do selo.

---

## 4. Estrutura Criptográfica PAdES

- **Motor:** Apache PDFBox 3.0.4 + Bouncy Castle 1.80 (`bcpkix-jdk18on`).
- **Filtro:** `/Filter /Adobe.PPKLite` e `/SubFilter /adbe.pkcs7.detached`.
- **Algoritmo:** `SHA256withRSA` / PKCS#1 v1.5 com digest SHA-256.
- **Salva Incremental:** Preserva a integridade de assinaturas anteriores e do documento original sem quebrar certificações prévias.

---

## 5. Ferramentas Web do SDK (@cybercore/signer-sdk)

O SDK web fornece componentes visuais nativos em JavaScript vanilla para aplicações web:

### 5.1 `PdfStampPicker` (Posicionador Visual de Selo)
Permite que o usuário final suba um PDF no navegador, folheie páginas, selecione cantos predefinidos ou arraste a estampa visual interativamente. O componente mapeia as coordenadas do canvas para o sistema de coordenadas do PDFBox (ISO 32000, com origem no canto inferior esquerdo) e gera em tempo real o payload JSON para a requisição.

```javascript
import { PdfStampPicker } from '@cybercore/signer-sdk';

const picker = new PdfStampPicker({
  container: '#picker-container',
  pdfSource: pdfArrayBuffer, // ou URL / Base64
  initialScale: 1.0,
  onPositionChange: (pos) => {
    console.log('Página:', pos.page, 'X:', pos.x, 'Y:', pos.y);
  }
});

// Obtém parâmetros prontos para a requisição CCSP
const stampConfig = picker.getStampConfig();
```

### 5.2 `PdfSealDesigner` (Criador & Personalizador de Selos)
Componente interativo com live preview em SVG vetorial para personalização de selos:
- Paleta de cores primária, secundária, fundo e texto.
- Ícones vetoriais (`shield`, `certificate`, `lock`) e upload de logotipo em Base64.
- Regras LGPD para mascaramento ou ocultação de CPF/CNPJ.
- Exportação da configuração JSON para envio inline via `seal_custom` na requisição `signPdfDocument()`.

### 5.3 Assinatura Completa via Base64 (`signPdfDocument`)
Permite enviar o PDF completo em Base64 e receber de volta o PDF assinado completo em Base64 para envio direto ao backend:

```javascript
const result = await signer.signPdfDocument({
  certificateId: cert.id,
  pdf: pdfArrayBuffer, // ou base64
  page: stampConfig.page,
  x: stampConfig.x,
  y: stampConfig.y,
  scale: stampConfig.scale,
  seal_theme_id: 'icp-brasil', // ou seal_custom: customSealConfig
  reason: 'Documento homologado',
  location: 'São Paulo, SP'
});

console.log('PDF Assinado Base64:', result.signed_pdf);
console.log('SHA-256 do Documento Final:', result.sha256);
```

---

## 6. Políticas de Assinatura ICP-Brasil (DOC-ICP-15)

O padrão brasileiro de assinaturas digitais mantido pelo ITI prevê quatro perfis progressivos de conformidade:

| Política | Denominação | Status no CyberCore Signer | Componentes Arquiteturais |
| :--- | :--- | :--- | :--- |
| **AD-RB** | Assinatura com Referência Básica | **Homologado / Ativo** | Envelope PAdES detached CMS com selo Java2D e `/ByteRange` validado pelo ITI |
| **AD-RT** | Assinatura com Referência de Tempo | **Em Integração** | Cliente TSA RFC 3161 resiliente (`TsaClient`) com retentativas e fallback |
| **AD-RC** | Assinatura com Referências Completas | **Roadmap** | Validador de cadeia (`CertificateChainValidator`) e cache de revogação (`RevocationCache`) |
| **AD-RA** | Assinatura com Referência para Arquivamento | **Roadmap** | Dicionário LTV (`/DSS`) embutido no PDF com carimbos periódicos de arquivo |