feat: initial commit - cybercore signer desktop agent

2026-10-11 08:20:24 -03:00
commit ccfa358f97
206 changed files with 23952 additions and 0 deletions
@@ -0,0 +1,64 @@
+# @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.