pdfsigner-rs
v0.1.0
Published
Programa para assinar documentos PDF digitalmente utilizando certificados digitais no padrão ICP-Brasil.
Maintainers
Readme
pdfsigner-rs
Biblioteca de alto desempenho para assinatura digital de documentos PDF usando certificados digitais no padrão ICP-Brasil, escrita em Rust com bindings para Node.js via NAPI-RS.
🚀 Características
- ✅ Alta Performance: Implementado em Rust para máxima velocidade
- ✅ Otimizado: Binários com menos de 10MB
- ✅ Suporte AWS3: Salve o arquivo assinado em um bucket AWS S3
- ✅ Compatível com ICP-Brasil: Suporta certificados A1 (PFX/P12)
- ✅ Padrão PAdES AD-RB (ICP-Brasil): Assinaturas com política de assinatura ICP-Brasil, compatíveis com Adobe Reader
- ✅ Assinatura múltipla: Cada assinatura é uma atualização incremental; nada do PDF original é apagado
- ✅ Campos de assinatura: Crie campos pré-definidos e assine dentro deles pelo nome
- ✅ Assinatura visível: Texto e imagem definidos pelo backend
- ✅ Anotações editáveis: Texto e imagem como comentários do Acrobat
- ✅ Respeita travas: Detecta PDFs certificados (DocMDP) e campos travados (FieldMDP)
- ✅ Zero Dependências Nativas: Binários pré-compilados para todas as plataformas
- ✅ TypeScript: Tipagem completa incluída
- ✅ Cross-Platform: Windows, macOS e Linux
📦 Instalação
npm install pdfsigner-rs
# ou
yarn add pdfsigner-rs
# ou
pnpm add pdfsigner-rs
# ou
bun add pdfsigner-rs🔧 Uso
Assinando um PDF a partir de um arquivo
const { signPdfWithPath } = require('pdfsigner-rs')
const fs = require('fs')
// Assinar PDF e retornar buffer
// Nesse método usamos o caminho do documento ao invés de ser buffer.
const pdfSigned = signPdfWithPath(
{
pfxPath: path.join(__dirname, 'certificado.pfx'),
pfxPassword: 'senha',
},
path.join(__dirname, 'pdf_sample_2.pdf'),
{
reason: 'I approve this document',
location: 'New York, USA',
},
)
// Salvar o PDF assinado
fs.writeFileSync('./documento_assinado.pdf', pdfSigned.toBuffer())
console.log('✓ PDF assinado com sucesso!')Assinando um PDF a partir de bytes (Buffer)
const { signPdf } = require('pdfsigner-rs')
const fs = require('fs')
// Ler o PDF como buffer
const pdfBuffer = fs.readFileSync('./documento.pdf')
// Assinar o buffer
// Nesse método usamos o buffer do documento.
const pdfSigned = signPdf(
{
pfxPath: path.join(__dirname, 'certificado.pfx'),
pfxPassword: 'senha',
},
pdfBuffer,
{
reason: 'I approve this document',
location: 'New York, USA',
},
)
// Salvar ou usar o buffer diretamente
fs.writeFileSync('./documento_assinado.pdf', pdfSigned.toBuffer())TypeScript
import { signPdf } from 'pdfsigner-rs'
const pdfSigned: PdfSigned = signPdf(
{
pfxPath: path.join(__dirname, 'certificado.pfx'),
pfxPassword: 'senha',
},
pdfBuffer,
{
reason: 'I approve this document',
location: 'New York, USA',
},
)📝 API
Coordenadas: sempre em pontos PDF (1/72 polegada), com origem no canto superior esquerdo da página como ela aparece na tela (a rotação da página é considerada). A primeira página é
1.
Assinatura múltipla
Cada chamada de signPdf acrescenta uma nova assinatura ao final do arquivo (atualização incremental). Campos, anotações e assinaturas existentes são preservados, e as assinaturas anteriores continuam válidas.
let pdf = fs.readFileSync('./documento.pdf')
pdf = signPdf(certA, pdf, { reason: 'Aprovo' }).toBuffer()
pdf = signPdf(certB, pdf, { reason: 'Ciente' }).toBuffer()⚠️ Concorrência: o backend deve serializar as assinaturas de um mesmo documento (fila ou lock). Se duas assinaturas partirem da mesma versão do arquivo, a última gravação descarta a outra.
⚠️ Não reconstrua o PDF (ex.:
copyPagesdo pdf-lib, juntar PDFs) depois de assinado: isso destrói assinaturas, campos e anotações existentes. Junte primeiro, assine depois.
Campos de assinatura pré-definidos
const { createSignatureFields, listSignatureFields, signPdf } = require('pdfsigner-rs')
// O backend decide os campos (ex.: um por vereador)
let pdf = createSignatureFields(pdfBuffer, [
{ name: 'vereador_joao', page: 3, x: 40, y: 600, width: 160, height: 50 },
{ name: 'vereador_maria', page: 3, x: 220, y: 600, width: 160, height: 50 },
]).toBuffer()
// Depois, cada um assina no seu campo
pdf = signPdf(certJoao, pdf, {
fieldName: 'vereador_joao',
appearance: { lines: ['JOÃO DA SILVA', 'Vereador', '03/11/2026 10:00'] },
}).toBuffer()
listSignatureFields(pdf)
// [{ name: 'vereador_joao', page: 3, signed: true, x: 40, y: 600, width: 160, height: 50 }, ...]Assinatura visível
O conteúdo é decidido pelo backend (lines e/ou image); a lib apenas desenha no retângulo, com imagem à esquerda e texto à direita (fonte reduzida automaticamente para caber, ou fixa com fontSize).
signPdf(cert, pdfBuffer, {
appearance: {
page: 1, x: 40, y: 700, width: 220, height: 60,
lines: ['Assinado digitalmente por FULANO', 'Data: 03/11/2026 10:00'],
image: fs.readFileSync('./rubrica.png'), // PNG (com transparência) ou JPEG
},
})Sem fieldName e sem appearance, a assinatura é invisível (comportamento anterior).
Anotações (texto e imagem)
Anotações são comentários editáveis no Acrobat (podem ser movidos, editados e apagados). Podem ser adicionadas sozinhas ou junto com a assinatura (config.annotations), caso em que ficam cobertas por ela.
const { addAnnotations, AnnotationKind } = require('pdfsigner-rs')
const out = addAnnotations(pdfBuffer, [
{ kind: AnnotationKind.Text, page: 1, x: 40, y: 40, width: 200, height: 40,
text: 'Recebido em 03/11/2026', fontSize: 10, color: '#000000', backgroundColor: '#FFFF99', borderColor: '#000000' },
{ kind: AnnotationKind.Image, page: 1, x: 300, y: 40, width: 80, height: 80, image: fs.readFileSync('./carimbo.png') },
]).toBuffer()O texto usa Helvetica (WinAnsi): acentos do português são suportados; emojis e caracteres fora do WinAnsi geram erro [INVALID_TEXT].
Travas e permissões
PDFs vindos de fora podem estar travados. A lib nunca cria travas, mas respeita as existentes (mesmo que a assinatura que as declara esteja quebrada, como o Acrobat):
| Situação | Assinar | Anotar | Criar campos | | --- | --- | --- | --- | | Sem certificação | ✅ | ✅ | ✅ | | Certificado DocMDP P=1 (nenhuma alteração) | ❌ | ❌ | ❌ | | Certificado DocMDP P=2 (formulário e assinatura) | ✅ campo existente ou invisível | ❌ | ❌ | | Certificado DocMDP P=3 | ✅ | ✅ | ✅ | | FieldMDP com P=1 em assinatura existente | ❌ | ❌ | ❌ | | PDF criptografado | ❌ | ❌ | ❌ |
const { getPdfPermissions } = require('pdfsigner-rs')
const p = getPdfPermissions(pdfBuffer)
// { locked, canSign, canAnnotate, canAddFields, encrypted, docMdpLevel, reason, lockedFields }
if (!p.canSign) avisarUsuario(p.reason)Códigos de erro
Erros são lançados como Error com a mensagem iniciando por um código estável:
| Código | Quando |
| --- | --- |
| [DOCUMENT_LOCKED] | PDF ou campo travado (DocMDP/FieldMDP/seed value) |
| [ENCRYPTED_PDF] | PDF criptografado |
| [FIELD_NOT_FOUND] | fieldName inexistente |
| [FIELD_ALREADY_SIGNED] | campo já assinado |
| [DUPLICATE_FIELD_NAME] | nome de campo repetido |
| [INVALID_FIELD_NAME] | nome vazio ou com . |
| [INVALID_PAGE] / [INVALID_RECT] | página inexistente / retângulo fora da página |
| [INVALID_IMAGE] / [INVALID_TEXT] | imagem não PNG/JPEG / caractere não suportado |
| [INVALID_PDF] | PDF ilegível |
Formato da assinatura
Por padrão a assinatura é PAdES AD-RB da ICP-Brasil (/SubFilter /ETSI.CAdES.detached, política 2.16.76.1.7.1.11.1.3). Para o formato antigo (adbe.pkcs7.detached), use legacyPkcs7: true.
signPdf(certificate: CertificateInfo, pdfData: Buffer, config?: Config | undefined | null): PdfSigned
Assina um PDF a partir de bytes e retorna o buffer assinado.
Parâmetros:
certificate(CertificateInfo): Informações do certificadopdfData(Buffer): Buffer contendo o PDFconfig(Config | undefined | null, opcional): Configurações adicionais
Retorna: PdfSigned - Uma classe que representa o PDF assinado
signPdfWithPath(certificate: CertificateInfo, pdfPath: string, config?: Config | undefined | null): PdfSigned
Assina um PDF a partir de um caminho de arquivo e retorna o buffer assinado.
Parâmetros:
certificate(CertificateInfo): Informações do certificadopdfPath(string): Caminho para o arquivo PDFconfig(Config | undefined | null, opcional): Configurações adicionais
Retorna: PdfSigned - Uma classe que representa o PDF assinado
🏗️ Plataformas Suportadas
| Plataforma | Arquitetura | Status | | ---------- | --------------------- | ------ | | Windows | x64 | ✅ | | macOS | x64 | ✅ | | macOS | ARM64 (Apple Silicon) | ✅ | | Linux | x64 (glibc) | ✅ |
🔐 Segurança
- Suporta certificados digitais ICP-Brasil (A1)
- Implementa assinatura PAdES AD-RB (política de assinatura ICP-Brasil)
- Compatível com Adobe Reader e validadores ICP-Brasil
- OpenSSL para operações criptográficas
🛠️ Desenvolvimento
Requisitos
- Rust (última versão estável)
- Node.js 20+
- Yarn 1.x ou superior
Build Local
# Instalar dependências
yarn install
# Build do projeto
yarn build
# Executar testes
yarn test
# Lint
yarn lint📄 Licença
MIT
🤝 Contribuindo
Contribuições são bem-vindas! Sinta-se à vontade para abrir issues ou pull requests.
👤 Autor
AaronKing - @KingTimer12
🙏 Agradecimentos
- Baseado em NAPI-RS para bindings Rust ↔ Node.js
- Inspirado em node-signpdf
