@cybercore/signer-sdk

SDK oficial em JavaScript/TypeScript para integração de aplicações web com o agente desktop CyberCore Signer via protocolo CCSP/1.

Permite que sistemas web solicitem assinaturas digitais ICP-Brasil padrão A1 (.pfx/.p12) e A3 (Tokens USB e Smart Cards via PKCS#11 / Windows Store) instalados localmente na máquina do usuário, mantendo as chaves privadas e o PIN sob proteção estrita e exclusiva do computador do cliente.

📦 Instalação via Registry npm Privado

Configure o escopo @cybercore no arquivo .npmrc da sua aplicação web:

# .npmrc
@cybercore:registry=https://git.cybercore.com.br/api/packages/cybercore/npm/
//git.cybercore.com.br/api/packages/cybercore/npm/:_authToken=${GITEA_NPM_TOKEN}
always-auth=true

Em seguida, instale o pacote:

npm install @cybercore/signer-sdk
# ou
yarn add @cybercore/signer-sdk
# ou
pnpm add @cybercore/signer-sdk

🚀 Uso Rápido (TypeScript / JavaScript ES Modules)

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

const signer = new CyberCoreSigner({
  applicationName: 'Portal Corporativo ERP',
  timeoutMs: 30000 // 30 segundos
});

async function executarAssinatura() {
  try {
    // 1. Verifica se o agente desktop está ativo na bandeja do sistema
    if (!(await signer.isInstalled())) {
      alert('Por favor, abra o CyberCore Signer na bandeja do sistema.');
      return;
    }

    // 2. Conecta e obtém autorização visual do usuário
    await signer.connect();

    // 3. Obtém certificados disponíveis
    const certs = await signer.getCertificates();
    if (certs.length === 0) {
      alert('Nenhum certificado A1 ou token A3 conectado.');
      return;
    }

    // 4. Assina o digest de um documento (o hash é gerado no próprio navegador)
    const resultado = await signer.sign({
      certificateId: certs[0].id,
      data: 'Conteúdo ou contrato em texto a ser assinado',
      documentName: 'contrato.pdf'
    });

    console.log('Assinatura Base64:', resultado.signature);
    console.log('Certificado X.509:', resultado.certificate);

  } catch (err) {
    if (err instanceof AgentNotRunningError) {
      alert(err.actionableGuidance);
    } else if (err instanceof UserCancelledError) {
      console.info('Assinatura cancelada pelo usuário.');
    } else {
      console.error('Falha na operação:', err);
    }
  }
}

📚 Métodos da API

Método	Retorno	Descrição
`isInstalled(timeoutMs?)`	`Promise<boolean>`	Verifica se o CyberCore Signer está ativo na porta local (`21325`).
`getStatus(timeoutMs?)`	`Promise<StatusResponse>`	Retorna status de prontidão, versão e sistema operacional.
`getVersion()`	`Promise<VersionInfo>`	Retorna versões do agente e do protocolo CCSP.
`getCapabilities()`	`Promise<CapabilitiesResponse>`	Retorna algoritmos suportados (`SHA256withRSA`, etc.) e tipos de certificados.
`connect()`	`Promise<boolean>`	Realiza o handshake de autorização da aplicação web com o usuário.
`getCertificates()`	`Promise<CertificateDto[]>`	Retorna a lista de certificados A1 e A3 disponíveis na máquina.
`sign(params)`	`Promise<SignResult>`	Assinatura desacoplada de digest SHA-256 (recomendado para alta performance).
`signPdfDocument(params)`	`Promise<SignPdfDocumentResult>`	Assinatura PAdES completa de PDF com estampa gráfica e posicionamento visual.
`signXmlDocument(params)`	`Promise<SignXmlDocumentResult>`	Assinatura XAdES-BES / XMLDSig Enveloped de arquivos XML ou notas fiscais.
`authenticate(params)`	`Promise<AuthenticateResult>`	Login seguro sem senha por desafio criptográfico (Challenge-Response).
`getSealThemes()`	`Promise<SealThemesResponse>`	Consulta temas de selos gráficos visuais disponíveis no agente.
`verify(params)`	`Promise<boolean>`	Validação sintática e integridade da assinatura no client.

📂 Exemplos Prontos

Consulte a pasta examples/ para implementações completas:

01-crypto-login.js — Autenticação sem senha via desafio.
02-sign-digest.js — Assinatura desacoplada de digest SHA-256.
03-sign-pades.js — Assinatura de PDF com carimbo visual ICP-Brasil / Gov.br.
04-error-handling.js — Tratamento completo e acionável de erros.

🔒 Segurança, Conectividade e Protocolo

Especificação do Protocolo: Consulte a documentação formal em docs/CCSP.md e o esquema JSON em docs/ccsp-v1.schema.json.
Compatibilidade HTTPS e Private Network Access (PNA): Consulte docs/browser-compatibility.md.
Processo de Release do Pacote: Consulte docs/sdk-release-process.md.

4.9 KiB Raw Blame History