65 lines
2.8 KiB
Markdown
65 lines
2.8 KiB
Markdown
# @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)
|
|
```html
|
|
<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.
|