cybercore-signer/sdk/README.md

@cybercore/signer-sdk

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

Permite que sistemas web executem assinaturas digitais ICP-Brasil padrão A1 (.pfx/.p12) e A3 (Tokens USB e Smart Cards) instalados localmente na máquina do usuário, mantendo as chaves privadas e o PIN sob proteção estrita do hardware.

---

🚀 Instalação e Uso Rápido

1. Inclusão Direta no HTML (ES Module)

<script type="module">
  import { CyberCoreSigner } from './src/signer-sdk.js';

  const signer = new CyberCoreSigner({
    applicationName: 'Portal Minha Empresa'
  });

  // 1. Verifica se o agente desktop está rodando
  if (await signer.isInstalled()) {
    console.log('Agente detectado!');

    // 2. Conecta e solicita autorização ao usuário
    await signer.connect();

    // 3. Obtém certificados disponíveis
    const certs = await signer.getCertificates();
    console.log('Certificados encontrados:', certs);

    // 4. Assina um documento (o SDK calcula o SHA-256 no próprio navegador)
    const result = await signer.sign({
      certificateId: certs[0].id,
      data: 'Texto ou buffer do contrato para assinatura'
    });

    console.log('Assinatura Base64:', result.signature);
  }
</script>

---

📚 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()	Promise<Object>	Retorna status de prontidão, versão e sistema operacional.
getVersion()	Promise<Object>	Retorna versões do agente e do protocolo CCSP.
getCapabilities()	Promise<Object>	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<Array>	Retorna a lista de certificados A1 e A3 disponíveis na máquina.
sign(options)	Promise<Object>	Solicita a assinatura digital de um digest ou documento.
verify(options)	Promise<boolean>	Validação criptográfica da integridade da assinatura.

---

🔒 Princípios de Segurança e Privacidade

• Apenas o Digest é transmitido: O documento completo nunca sai do navegador da aplicação web. O SDK calcula o hash SHA-256 localmente antes de invocar o agente.
• Isolamento Total: A comunicação ocorre exclusivamente via loopback em 127.0.0.1:21325.
• Autorização Prévia: Aplicações web desconhecidas devem ser autorizadas visualmente pelo usuário na tela do CyberCore Signer antes de listar certificados.
• PIN Protegido: O PIN do token A3 nunca trafega pela web e nunca é enviado a nenhum servidor remoto.