feat: initial commit - cybercore signer desktop agent

docs/sdk.md

@@ -0,0 +1,117 @@
+# SDK Web JavaScript (@cybercore/signer-sdk)
+
+O `@cybercore/signer-sdk` é a biblioteca oficial cliente em JavaScript para integrar aplicações web modernas com o agente desktop **CyberCore Signer** via protocolo **CCSP/1**.
+
+---
+
+## 1. Instalação e Importação
+
+### Via Módulo ES6 (Browser ou Bundler Vite/Webpack/Next.js)
+```javascript
+import { CyberCoreSigner } from '@cybercore/signer-sdk';
+
+const signer = new CyberCoreSigner({
+  applicationName: 'Portal Meu Negócio'
+});
+```
+
+---
+
+## 2. Métodos da API
+
+### `isInstalled(timeoutMs = 2000): Promise<boolean>`
+Testa rapidamente se o agente desktop está ativo na porta local `21325`.
+
+### `connect(): Promise<boolean>`
+Realiza o handshake inicial de autorização. Se for a primeira vez que a aplicação tenta se conectar, abre uma caixa de diálogo nativa no desktop do usuário para concessão de acesso.
+
+### `getCertificates(): Promise<Array<Object>>`
+Retorna todos os certificados A1 e A3 disponíveis e operacionais na máquina do usuário.
+
+```javascript
+const certs = await signer.getCertificates();
+certs.forEach(cert => {
+  console.log(`[${cert.type}] ${cert.common_name} (Validade: ${cert.valid_to})`);
+});
+```
+
+### `sign(options): Promise<Object>`
+Solicita a assinatura digital local de um digest ou conteúdo bruto.
+
+### `signPdf(pdfFile, options): Promise<Object>`
+Assina um documento PDF (PAdES / Assinatura desacoplada). Recebe `File`, `Blob`, `ArrayBuffer` ou `Uint8Array`.
+Calcula o SHA-256 no próprio navegador e transmite metadados do documento (`PDF`) ao agente para exibição clara na janela de confirmação.
+
+```javascript
+const pdfResult = await signer.signPdf(fileInput.files[0], {
+  certificateId: certs[0].id
+});
+```
+
+### `signXml(xmlContent, options): Promise<Object>`
+Assina um documento XML (XMLDSig / NF-e). Aceita string com o XML formatado ou objeto de arquivo `File`/`Blob`.
+
+```javascript
+const xmlResult = await signer.signXml(xmlString, {
+  certificateId: certs[0].id,
+  documentName: 'nfe-3524.xml'
+});
+```
+
+### `signFile(file, options): Promise<Object>`
+Assina qualquer arquivo (ZIP, DOCX, imagens, binários, executáveis) gerando pacote de assinatura detached / CAdES.
+
+```javascript
+const fileResult = await signer.signFile(fileInput.files[0], {
+  certificateId: certs[0].id
+});
+```
+
+### `authenticate(options): Promise<Object>` (ou `login(options)`)
+Executa login seguro com certificado digital via desafio criptográfico (Challenge-Response).
+
+```javascript
+const auth = await signer.authenticate({
+  certificateId: certs[0].id,
+  challenge: 'server-nonce-12345'
+});
+
+console.log('Bem-vindo,', auth.subjectName);
+console.log('CPF/CNPJ:', auth.subjectCpfCnpj);
+console.log('Assinatura do Desafio:', auth.signature);
+```
+
+### `extractSubjectInfo(certificateBase64): { name, cpfCnpj }`
+Decodifica o certificado X.509 e extrai os dados do titular ICP-Brasil (Nome, CPF ou CNPJ).
+
+### `verify(options): Promise<boolean>`
+Validação sintática e criptográfica da integridade da assinatura gerada.
+
+---
+
+## 3. Tratamento Estruturado de Erros
+
+O SDK expõe classes de erro dedicadas que herdam de `CyberCoreError`:
+
+```javascript
+import {
+  UserCancelledError,
+  CertificateNotFoundError,
+  PinIncorrectError,
+  TokenNotFoundError
+} from '@cybercore/signer-sdk/errors';
+
+try {
+  await signer.sign({ certificateId: 'cert-1', data: 'Contrato' });
+} catch (err) {
+  if (err instanceof UserCancelledError) {
+    alert('Você cancelou a assinatura no CyberCore Signer.');
+  } else if (err instanceof PinIncorrectError) {
+    alert('O PIN do token informado está incorreto.');
+  } else if (err instanceof TokenNotFoundError) {
+    alert('Conecte o seu token USB na máquina para assinar.');
+  } else {
+    console.error('Erro na assinatura:', err);
+  }
+}
+```