121 lines
4.9 KiB
Markdown
121 lines
4.9 KiB
Markdown
# @cybercore/signer-sdk
|
|
|
|
SDK oficial em JavaScript/TypeScript para integração de aplicações web com o agente desktop **CyberCore Signer** via protocolo **CCSP/1**.
|
|
|
|
Permite que sistemas web solicitem assinaturas digitais ICP-Brasil padrão **A1** (.pfx/.p12) e **A3** (Tokens USB e Smart Cards via PKCS#11 / Windows Store) instalados localmente na máquina do usuário, mantendo as chaves privadas e o PIN sob proteção estrita e exclusiva do computador do cliente.
|
|
|
|
---
|
|
|
|
## 📦 Instalação via Registry npm Privado
|
|
|
|
Configure o escopo `@cybercore` no arquivo `.npmrc` da sua aplicação web:
|
|
|
|
```ini
|
|
# .npmrc
|
|
@cybercore:registry=https://git.cybercore.com.br/api/packages/cybercore/npm/
|
|
//git.cybercore.com.br/api/packages/cybercore/npm/:_authToken=${GITEA_NPM_TOKEN}
|
|
always-auth=true
|
|
```
|
|
|
|
Em seguida, instale o pacote:
|
|
```bash
|
|
npm install @cybercore/signer-sdk
|
|
# ou
|
|
yarn add @cybercore/signer-sdk
|
|
# ou
|
|
pnpm add @cybercore/signer-sdk
|
|
```
|
|
|
|
---
|
|
|
|
## 🚀 Uso Rápido (TypeScript / JavaScript ES Modules)
|
|
|
|
```typescript
|
|
import {
|
|
CyberCoreSigner,
|
|
AgentNotRunningError,
|
|
UserCancelledError
|
|
} from '@cybercore/signer-sdk';
|
|
|
|
const signer = new CyberCoreSigner({
|
|
applicationName: 'Portal Corporativo ERP',
|
|
timeoutMs: 30000 // 30 segundos
|
|
});
|
|
|
|
async function executarAssinatura() {
|
|
try {
|
|
// 1. Verifica se o agente desktop está ativo na bandeja do sistema
|
|
if (!(await signer.isInstalled())) {
|
|
alert('Por favor, abra o CyberCore Signer na bandeja do sistema.');
|
|
return;
|
|
}
|
|
|
|
// 2. Conecta e obtém autorização visual do usuário
|
|
await signer.connect();
|
|
|
|
// 3. Obtém certificados disponíveis
|
|
const certs = await signer.getCertificates();
|
|
if (certs.length === 0) {
|
|
alert('Nenhum certificado A1 ou token A3 conectado.');
|
|
return;
|
|
}
|
|
|
|
// 4. Assina o digest de um documento (o hash é gerado no próprio navegador)
|
|
const resultado = await signer.sign({
|
|
certificateId: certs[0].id,
|
|
data: 'Conteúdo ou contrato em texto a ser assinado',
|
|
documentName: 'contrato.pdf'
|
|
});
|
|
|
|
console.log('Assinatura Base64:', resultado.signature);
|
|
console.log('Certificado X.509:', resultado.certificate);
|
|
|
|
} catch (err) {
|
|
if (err instanceof AgentNotRunningError) {
|
|
alert(err.actionableGuidance);
|
|
} else if (err instanceof UserCancelledError) {
|
|
console.info('Assinatura cancelada pelo usuário.');
|
|
} else {
|
|
console.error('Falha na operação:', err);
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 📚 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(timeoutMs?)` | `Promise<StatusResponse>` | Retorna status de prontidão, versão e sistema operacional. |
|
|
| `getVersion()` | `Promise<VersionInfo>` | Retorna versões do agente e do protocolo CCSP. |
|
|
| `getCapabilities()` | `Promise<CapabilitiesResponse>` | 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<CertificateDto[]>` | Retorna a lista de certificados A1 e A3 disponíveis na máquina. |
|
|
| `sign(params)` | `Promise<SignResult>` | Assinatura desacoplada de digest SHA-256 (recomendado para alta performance). |
|
|
| `signPdfDocument(params)` | `Promise<SignPdfDocumentResult>` | Assinatura PAdES completa de PDF com estampa gráfica e posicionamento visual. |
|
|
| `signXmlDocument(params)` | `Promise<SignXmlDocumentResult>` | Assinatura XAdES-BES / XMLDSig Enveloped de arquivos XML ou notas fiscais. |
|
|
| `authenticate(params)` | `Promise<AuthenticateResult>` | Login seguro sem senha por desafio criptográfico (Challenge-Response). |
|
|
| `getSealThemes()` | `Promise<SealThemesResponse>` | Consulta temas de selos gráficos visuais disponíveis no agente. |
|
|
| `verify(params)` | `Promise<boolean>` | Validação sintática e integridade da assinatura no client. |
|
|
|
|
---
|
|
|
|
## 📂 Exemplos Prontos
|
|
|
|
Consulte a pasta [`examples/`](./examples/) para implementações completas:
|
|
- [`01-crypto-login.js`](./examples/01-crypto-login.js) — Autenticação sem senha via desafio.
|
|
- [`02-sign-digest.js`](./examples/02-sign-digest.js) — Assinatura desacoplada de digest SHA-256.
|
|
- [`03-sign-pades.js`](./examples/03-sign-pades.js) — Assinatura de PDF com carimbo visual ICP-Brasil / Gov.br.
|
|
- [`04-error-handling.js`](./examples/04-error-handling.js) — Tratamento completo e acionável de erros.
|
|
|
|
---
|
|
|
|
## 🔒 Segurança, Conectividade e Protocolo
|
|
|
|
- **Especificação do Protocolo:** Consulte a documentação formal em [`docs/CCSP.md`](../docs/CCSP.md) e o esquema JSON em [`docs/ccsp-v1.schema.json`](../docs/ccsp-v1.schema.json).
|
|
- **Compatibilidade HTTPS e Private Network Access (PNA):** Consulte [`docs/browser-compatibility.md`](../docs/browser-compatibility.md).
|
|
- **Processo de Release do Pacote:** Consulte [`docs/sdk-release-process.md`](../docs/sdk-release-process.md).
|