cybercore-signer/docs/pades.md

# 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.

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.