118 lines
3.7 KiB
Markdown
118 lines
3.7 KiB
Markdown
# 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);
|
|
}
|
|
}
|
|
```
|