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:

# ~/.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:

Testes Automatizados 100% Verdes:
```
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).
Auditoria de Conteúdo Empacotado: Execute uma simulação de empacotamento para inspecionar exatamente quais arquivos serão distribuídos:
```
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.
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.
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/:

# 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

npm publish

Passo 3: Criar Tag Git e Sincronizar

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):

Adicionar o arquivo .npmrc na raiz do projeto:

@cybercore:registry=https://git.cybercore.com.br/api/packages/cybercore/npm/

Instalar a dependência:

npm install @cybercore/signer-sdk@latest

Testar a importação:

import { CyberCoreSigner } from '@cybercore/signer-sdk';
const signer = new CyberCoreSigner();

3.7 KiB Raw Blame History