# Guia de Contribuição — CyberCore Signer

Agradecemos o interesse em contribuir com o **CyberCore Signer**! Para garantir a segurança criptográfica, a estabilidade e a manutenibilidade do projeto, siga as orientações descritas abaixo.

---

## 1. Pré-requisitos do Ambiente

* **Java Development Kit (JDK):** Versão 25 LTS (Eclipse Temurin, OpenJDK ou Amazon Corretto).
* **Maven Wrapper:** Utilize sempre o executável `./mvnw` (Linux/macOS) ou `mvnw.cmd` (Windows) embutido no projeto.
* **Git:** Com suporte a quebra de linha `LF`.

---

## 2. Princípios de Segurança Invioláveis

Como este é um software de assinatura digital e custódia de credenciais criptográficas:

1. **Nunca exponha credenciais:** É estritamente proibido registrar, logar ou comitar PINs, senhas de arquivos A1, chaves privadas ou certificados de produção.
2. **Testes isolados:** Use fixtures mockadas ou certificados autoassinados temporários gerados dinamicamente nos testes.
3. **Loopback estrito:** O servidor CCSP escuta exclusivamente em `127.0.0.1:21325`. Nunca altere o bind para interfaces externas.

---

## 3. Padrão de Commits

Adotamos a especificação [Conventional Commits](https://www.conventionalcommits.org/pt-br/v1.0.0/). Cada commit deve representar uma alteração coesa e atômica:

* `feat:` Nova funcionalidade no agente, SDK ou UI.
* `fix:` Correção de bug sem alteração de escopo.
* `docs:` Alterações exclusivas na documentação.
* `test:` Adição ou melhoria de suítes de testes.
* `refactor:` Alterações de código que não mudam o comportamento funcional.
* `chore:` Tarefas de manutenção de build, scripts ou dependências.
* `ci:` Alterações no pipeline de CI/CD.

Exemplo: `feat(core): add support for custom pkcs11 pin retry limit`

---

## 4. Validação Pré-Commit / Pré-PR

Antes de submeter um Pull Request, certifique-se de que o build completo e todas as análises de qualidade passam localmente:

```bash
# Executa compilação, testes, checagem JaCoCo, SpotBugs e ArchUnit:
./mvnw clean verify
```

Critérios obrigatórios:
* Todos os testes unitários e de integração devem passar com sucesso.
* A cobertura mínima definida no `jacoco:check` de cada módulo deve ser mantida ou superada.
* Nenhum novo apontamento de segurança ou erro do SpotBugs deve ser introduzido.

---

## 5. Fluxo de Pull Requests

1. Crie uma branch descritiva a partir de `main` (ex: `feature/suporte-token-safenet` ou `fix/pades-timestamp-timeout`).
2. Mantenha os commits organizados e pequenos.
3. Abra o Pull Request preenchendo o template oficial do repositório em `.gitea/pull_request_template.md`.
4. Garanta que o pipeline de CI do Gitea Actions finalize com status verde.