cybercore-signer/docs/sdk.md

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.

---

1. Instalação e Importação

Via Módulo ES6 (Browser ou Bundler Vite/Webpack/Next.js)

import { CyberCoreSigner } from '@cybercore/signer-sdk';

const signer = new CyberCoreSigner({
  applicationName: 'Portal Meu Negócio'
});

---

2. Métodos da API

isInstalled(timeoutMs = 2000): Promise<boolean>

Testa rapidamente se o agente desktop está ativo na porta local 21325.

connect(): 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.

getCertificates(): Promise<Array<Object>>

Retorna todos os certificados A1 e A3 disponíveis e operacionais na máquina do usuário.

const certs = await signer.getCertificates();
certs.forEach(cert => {
  console.log(`[${cert.type}] ${cert.common_name} (Validade: ${cert.valid_to})`);
});

sign(options): Promise<Object>

Solicita a assinatura digital local de um digest ou conteúdo bruto.

signPdf(pdfFile, options): Promise<Object>

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.

const pdfResult = await signer.signPdf(fileInput.files[0], {
  certificateId: certs[0].id
});

signXml(xmlContent, options): Promise<Object>

Assina um documento XML (XMLDSig / NF-e). Aceita string com o XML formatado ou objeto de arquivo File/Blob.

const xmlResult = await signer.signXml(xmlString, {
  certificateId: certs[0].id,
  documentName: 'nfe-3524.xml'
});

signFile(file, options): Promise<Object>

Assina qualquer arquivo (ZIP, DOCX, imagens, binários, executáveis) gerando pacote de assinatura detached / CAdES.

const fileResult = await signer.signFile(fileInput.files[0], {
  certificateId: certs[0].id
});

authenticate(options): Promise<Object> (ou login(options))

Executa login seguro com certificado digital via desafio criptográfico (Challenge-Response).

const auth = await signer.authenticate({
  certificateId: certs[0].id,
  challenge: 'server-nonce-12345'
});

console.log('Bem-vindo,', auth.subjectName);
console.log('CPF/CNPJ:', auth.subjectCpfCnpj);
console.log('Assinatura do Desafio:', auth.signature);

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:

import {
  UserCancelledError,
  CertificateNotFoundError,
  PinIncorrectError,
  TokenNotFoundError
} from '@cybercore/signer-sdk/errors';

try {
  await signer.sign({ certificateId: 'cert-1', data: 'Contrato' });
} catch (err) {
  if (err instanceof UserCancelledError) {
    alert('Você cancelou a assinatura no CyberCore Signer.');
  } else if (err instanceof PinIncorrectError) {
    alert('O PIN do token informado está incorreto.');
  } else if (err instanceof TokenNotFoundError) {
    alert('Conecte o seu token USB na máquina para assinar.');
  } else {
    console.error('Erro na assinatura:', err);
  }
}