# @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.