chore(sdk): prepare package manifest for gitea npm registry and document release flow

2026-10-20 16:45:03 -03:00
parent b19d09a236
commit 8d0e587114
3 changed files with 198 additions and 34 deletions
@@ -0,0 +1,99 @@
+# Processo de Release e Publicação do SDK Web (@cybercore/signer-sdk)
+
+Este documento estabelece o fluxo oficial de versionamento, empacotamento, auditoria de segurança e publicação do pacote npm `@cybercore/signer-sdk` em registry privado (Gitea / Verdaccio / Artifactory).
+
+---
+
+## 1. Princípios e Ciclo de Vida
+
+- **Versionamento Semântico Independente (SemVer):** O SDK JavaScript/TypeScript possui ciclo de release desacoplado do executável/instalador Java desktop (`jpackage` MSI/EXE).
+  - Mudanças de correção de bugs / tipagem: `patch` (ex: `0.1.0` $\rightarrow$ `0.1.1`).
+  - Novos métodos de alto nível ou temas de selos: `minor` (ex: `0.1.0` $\rightarrow$ `0.2.0`).
+  - Mudanças de quebra de compatibilidade de API: `major` (ex: `0.1.0` $\rightarrow$ `1.0.0`).
+- **Compatibilidade com o CCSP/1:** O SDK permanece estritamente compatível com o protocolo CyberCore Signing Protocol v1 (`docs/ccsp-v1.schema.json`).
+
+---
+
+## 2. Configuração do Registry Privado (Gitea)
+
+O pacote utiliza o escopo organizacional `@cybercore`. Para publicar e consumir o pacote em registries privados Gitea, configure o arquivo `~/.npmrc` na máquina de build ou no ambiente CI/CD:
+
+```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
+```
+
+> [!CAUTION]
+> **Nunca comite tokens de autenticação ou credenciais no repositório Git.** Utilize sempre variáveis de ambiente (`GITEA_NPM_TOKEN` ou `NPM_TOKEN`) configuradas no cofre de segredos da esteira CI/CD.
+
+---
+
+## 3. Checklist de Segurança Pré-Release
+
+Antes de qualquer publicação, execute os itens obrigatórios:
+
+1. [ ] **Testes Automatizados 100% Verdes:**
+   ```bash
+   cd sdk
+   npm test
+   ```
+   Deve executar e aprovar os testes unitários (`signer-sdk.test.js`), testes de servidor mock (`mock-server.test.js`) e validação cruzada do schema (`schema-validation.test.js`).
+
+2. [ ] **Auditoria de Conteúdo Empacotado:**
+   Execute uma simulação de empacotamento para inspecionar exatamente quais arquivos serão distribuídos:
+   ```bash
+   npm pack --dry-run
+   ```
+   Verifique que apenas a pasta `src/` e o `README.md` estão listados no tarball. **Arquivos `.pfx`, `.p12`, `.key`, `.log`, fixtures de teste ou scripts confidenciais NÃO podem constar no tarball.**
+
+3. [ ] **Tipagens TypeScript Atualizadas:**
+   Certifique-se de que novos métodos ou parâmetros adicionados em `src/signer-sdk.js` e `src/errors.js` estão declarados em `src/signer-sdk.d.ts` e `src/errors.d.ts`.
+
+4. [ ] **Validação Cruzada de Schema:**
+   Certifique-se de que `docs/ccsp-v1.schema.json` e os testes Java em `cybercore-core` continuam passando sem inconsistências.
+
+---
+
+## 4. Passo a Passo de Publicação
+
+### Passo 1: Atualizar a Versão
+A partir da pasta `sdk/`:
+```bash
+# Para correções de bugs retrocompatíveis:
+npm version patch -m "chore(release): bump sdk version to %s"
+
+# Para novas funcionalidades retrocompatíveis:
+npm version minor -m "chore(release): bump sdk version to %s"
+```
+
+### Passo 2: Publicar no Registry Privado
+```bash
+npm publish
+```
+
+### Passo 3: Criar Tag Git e Sincronizar
+```bash
+git push origin feature/pdf-signing-flow --tags
+```
+
+---
+
+## 5. Como Consumir nas Aplicações Clientes
+
+Nas aplicações web consumidoras (frontends internos ou de parceiros homologados):
+
+1. Adicionar o arquivo `.npmrc` na raiz do projeto:
+   ```ini
+   @cybercore:registry=https://git.cybercore.com.br/api/packages/cybercore/npm/
+   ```
+2. Instalar a dependência:
+   ```bash
+   npm install @cybercore/signer-sdk@latest
+   ```
+3. Testar a importação:
+   ```typescript
+   import { CyberCoreSigner } from '@cybercore/signer-sdk';
+   const signer = new CyberCoreSigner();
+   ```
@@ -1,42 +1,85 @@
 # @cybercore/signer-sdk

-SDK oficial em JavaScript para integração de aplicações web com o agente desktop **CyberCore Signer** via protocolo **CCSP/1**.
+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 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.
+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 e Uso Rápido
+## 📦 Instalação via Registry npm Privado

-### 1. Inclusão Direta no HTML (ES Module)
-```html
-<script type="module">
-  import { CyberCoreSigner } from './src/signer-sdk.js';
+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 Minha Empresa'
+  applicationName: 'Portal Corporativo ERP',
+  timeoutMs: 30000 // 30 segundos
 });

-  // 1. Verifica se o agente desktop está rodando
-  if (await signer.isInstalled()) {
-    console.log('Agente detectado!');
+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 solicita autorização ao usuário
+    // 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();
-    console.log('Certificados encontrados:', certs);
+    if (certs.length === 0) {
+      alert('Nenhum certificado A1 ou token A3 conectado.');
+      return;
+    }

-    // 4. Assina um documento (o SDK calcula o SHA-256 no próprio navegador)
-    const result = await signer.sign({
+    // 4. Assina o digest de um documento (o hash é gerado no próprio navegador)
+    const resultado = await signer.sign({
      certificateId: certs[0].id,
-      data: 'Texto ou buffer do contrato para assinatura'
+      data: 'Conteúdo ou contrato em texto a ser assinado',
+      documentName: 'contrato.pdf'
    });

-    console.log('Assinatura Base64:', result.signature);
+    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);
+    }
+  }
 }
-</script>
 ```

 ---
@@ -45,20 +88,33 @@ Permite que sistemas web executem assinaturas digitais ICP-Brasil padrão **A1**

 | 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. |
+| `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<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. |
+| `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. |

 ---

-## 🔒 Princípios de Segurança e Privacidade
+## 📂 Exemplos Prontos

- **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.
+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).
@@ -1,7 +1,7 @@
 {
  "name": "@cybercore/signer-sdk",
  "version": "0.1.0",
-  "description": "SDK JavaScript para integração de aplicações web com o agente desktop CyberCore Signer via protocolo CCSP/1",
+  "description": "SDK JavaScript/TypeScript para integração de aplicações web com o agente desktop CyberCore Signer via protocolo CCSP/1",
  "type": "module",
  "main": "src/signer-sdk.js",
  "module": "src/signer-sdk.js",
@@ -22,15 +22,24 @@
    "src",
    "README.md"
  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "restricted"
+  },
  "scripts": {
    "test": "node --test test/*.test.js"
  },
-  "author": "CyberCore",
+  "author": "CyberCore Systems",
  "license": "Proprietary",
  "keywords": [
    "cybercore",
    "digital-signature",
    "icp-brasil",
+    "pades",
+    "xmldsig",
    "a1",
    "a3",
    "token",