From 8d0e58711436989fd9a06859bae1b999909935a1 Mon Sep 17 00:00:00 2001 From: Claudecio Martins Date: Tue, 20 Oct 2026 16:45:03 -0300 Subject: [PATCH] chore(sdk): prepare package manifest for gitea npm registry and document release flow --- docs/sdk-release-process.md | 99 +++++++++++++++++++++++++++++ sdk/README.md | 120 ++++++++++++++++++++++++++---------- sdk/package.json | 13 +++- 3 files changed, 198 insertions(+), 34 deletions(-) create mode 100644 docs/sdk-release-process.md diff --git a/docs/sdk-release-process.md b/docs/sdk-release-process.md new file mode 100644 index 0000000..c92d895 --- /dev/null +++ b/docs/sdk-release-process.md @@ -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(); + ``` diff --git a/sdk/README.md b/sdk/README.md index 02166cb..f13a2a7 100644 --- a/sdk/README.md +++ b/sdk/README.md @@ -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 - +} ``` --- @@ -45,20 +88,33 @@ Permite que sistemas web executem assinaturas digitais ICP-Brasil padrão **A1** | Método | Retorno | Descrição | |---|---|---| -| `isInstalled(timeoutMs)` | `Promise` | Verifica se o CyberCore Signer está ativo na porta local `21325`. | -| `getStatus()` | `Promise` | Retorna status de prontidão, versão e sistema operacional. | -| `getVersion()` | `Promise` | Retorna versões do agente e do protocolo CCSP. | -| `getCapabilities()` | `Promise` | Retorna algoritmos suportados (`SHA256withRSA`, etc.) e tipos de certificados. | +| `isInstalled(timeoutMs?)` | `Promise` | Verifica se o CyberCore Signer está ativo na porta local (`21325`). | +| `getStatus(timeoutMs?)` | `Promise` | Retorna status de prontidão, versão e sistema operacional. | +| `getVersion()` | `Promise` | Retorna versões do agente e do protocolo CCSP. | +| `getCapabilities()` | `Promise` | Retorna algoritmos suportados (`SHA256withRSA`, etc.) e tipos de certificados. | | `connect()` | `Promise` | Realiza o handshake de autorização da aplicação web com o usuário. | -| `getCertificates()` | `Promise` | Retorna a lista de certificados A1 e A3 disponíveis na máquina. | -| `sign(options)` | `Promise` | Solicita a assinatura digital de um digest ou documento. | -| `verify(options)` | `Promise` | Validação criptográfica da integridade da assinatura. | +| `getCertificates()` | `Promise` | Retorna a lista de certificados A1 e A3 disponíveis na máquina. | +| `sign(params)` | `Promise` | Assinatura desacoplada de digest SHA-256 (recomendado para alta performance). | +| `signPdfDocument(params)` | `Promise` | Assinatura PAdES completa de PDF com estampa gráfica e posicionamento visual. | +| `signXmlDocument(params)` | `Promise` | Assinatura XAdES-BES / XMLDSig Enveloped de arquivos XML ou notas fiscais. | +| `authenticate(params)` | `Promise` | Login seguro sem senha por desafio criptográfico (Challenge-Response). | +| `getSealThemes()` | `Promise` | Consulta temas de selos gráficos visuais disponíveis no agente. | +| `verify(params)` | `Promise` | 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). diff --git a/sdk/package.json b/sdk/package.json index fe7c39f..fd70f49 100644 --- a/sdk/package.json +++ b/sdk/package.json @@ -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",