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