> 🇧🇷 Tradução em Português. [English version](../../security/PR_SECURITY_CHECKLIST.md)

# PR #56 - Checklist de Hardening de Segurança

## Resumo das Alterações

Este PR implementa hardening de segurança abrangente para o validador pós-instalação como parte da Story 6.19.

## Arquivos Alterados

| Arquivo                                          | Tipo de Alteração | Descrição                                    |
| ------------------------------------------------ | ----------------- | -------------------------------------------- |
| `src/installer/post-install-validator.js`        | **Modificado**    | Reescrita completa com hardening de segurança |
| `src/installer/manifest-signature.js`            | **Novo**          | Módulo de verificação de assinatura Ed25519  |
| `bin/lmas-init.js`                               | **Modificado**    | Adicionada opção `requireSignature`          |
| `tests/installer/post-install-validator.test.js` | **Novo**          | Suite de testes de segurança                 |
| `docs/security/MANIFEST_SIGNING.md`              | **Novo**          | Documentação do fluxo de assinatura          |

## Controles de Segurança Implementados

### 1. Raiz de Confiança e Verificação de Assinatura

- [x] Assinaturas Ed25519 usando formato minisign
- [x] Chave pública fixada no código-fonte (não carregada de arquivos)
- [x] Assinatura verificada ANTES de parsear o YAML do manifest
- [x] Validação de Key ID para prevenir ataques de confusão de chaves

**Ação Necessária**: Antes da release de produção, os mantenedores devem:

1. Gerar um par de chaves: `minisign -G -p lmas-core.pub -s lmas-core.key`
2. Atualizar `PINNED_PUBLIC_KEY` em `manifest-signature.js` com a chave pública real
3. Assinar o manifest: `minisign -Sm install-manifest.yaml -s lmas-core.key`

### 2. Prevenção de Path Traversal

- [x] Bloquear sequências `../` e `..\`
- [x] Bloquear caminhos absolutos (`/etc/passwd`, `C:\Windows`)
- [x] Bloquear injeção de null byte (`file.txt\0.exe`)
- [x] Bloquear Windows Alternate Data Streams (`file.txt:$DATA`)
- [x] Validar que todos os caminhos estão contidos dentro da raiz do projeto

### 3. Validação de Schema do Manifest

- [x] Rejeitar campos desconhecidos (prevenir injeção de propriedades maliciosas)
- [x] Validar que algoritmo de hash é apenas `sha256`
- [x] Validar que tamanho é inteiro não-negativo
- [x] Validar que caminho é string não-vazia
- [x] Limitar comprimento do caminho a 1024 caracteres
- [x] Usar YAML FAILSAFE_SCHEMA para prevenir execução de código

### 4. Proteção contra DoS

- [x] MAX_MANIFEST_SIZE: 10 MB
- [x] MAX_FILE_COUNT: 50.000 arquivos
- [x] MAX_SCAN_DEPTH: 50 níveis de diretório
- [x] MAX_SCAN_FILES: 100.000 arquivos durante descoberta
- [x] MAX_PATH_LENGTH: 1.024 caracteres

### 5. Segurança do Sistema de Arquivos

- [x] Rejeição de symlinks usando `fs.lstatSync()`
- [x] Operações atômicas de arquivo quando possível
- [x] Nenhuma modificação de arquivos fora da raiz do projeto

### 6. Verificação de Hash

- [x] SHA256 para todas as verificações de integridade de arquivos
- [x] Cálculo de hash por streaming para eficiência de memória
- [x] Validação de tamanho primeiro para falha rápida
- [x] Detecção de arquivo corrompido bloqueia validação

### 7. Mecanismo de Reparo Seguro

- [x] Reparo requer manifest válido
- [x] Reparo requer verificação de hash do arquivo fonte
- [x] Caminho de reparo é validado antes da cópia
- [x] Sem reparo em modo de assinatura obrigatória sem assinatura válida

## Resultados dos Testes

```text
Security Audit Results:
- Total tests: 31
- Passed: 31 (100%)
- Files validated: 766
- Integrity: 100%
- Performance: 4,453 files/sec (SHA256)
```

### Categorias de Testes

| Categoria                        | Testes | Status      |
| -------------------------------- | ------ | ----------- |
| Prevenção de Path Traversal      | 7      | ✅ Todos OK |
| Validação de Schema              | 9      | ✅ Todos OK |
| Imposição de Assinatura          | 2      | ✅ Todos OK |
| Validação Completa de Hash       | 1      | ✅ OK       |
| Validação Rápida de Tamanho      | 1      | ✅ OK       |
| Ataque de Symlink                | 1      | ✅ OK       |
| Limites de DoS                   | 3      | ✅ OK       |
| Estrutura do Package             | 6      | ✅ Todos OK |

## Breaking Changes

Nenhuma. O validador mantém compatibilidade retroativa:

- Projetos existentes sem assinaturas funcionarão em modo de desenvolvimento
- Comportamento de verificação de hash inalterado
- Códigos de saída inalterados

## Guia de Migração

### Para Mantenedores (Antes da Produção)

1. **Gerar chaves de assinatura**:

   ```bash
   minisign -G -p lmas-core.pub -s lmas-core.key
   ```

2. **Atualizar chave pública** em `src/installer/manifest-signature.js`:

   ```javascript
   const PINNED_PUBLIC_KEY = {
     keyId: 'LMAS0001',
     publicKey: 'YOUR_BASE64_PUBLIC_KEY_HERE',
     algorithm: 'Ed25519',
   };
   ```

3. **Assinar manifest** antes de cada release:

   ```bash
   minisign -Sm .lmas-core/install-manifest.yaml -s lmas-core.key
   ```

4. **Commitar arquivo de assinatura**:
   ```bash
   git add .lmas-core/install-manifest.yaml.minisig
   ```

### Para Usuários

Nenhuma ação necessária. O validador lida com a verificação de assinatura automaticamente.

## Checklist do Revisor

- [ ] Verificar que o placeholder da chave pública está marcado como TODO
- [ ] Confirmar que nenhum secret está hardcoded
- [ ] Revisar cobertura de testes de path traversal
- [ ] Verificar que parsing YAML usa FAILSAFE_SCHEMA
- [ ] Confirmar que verificação de assinatura acontece antes do parsing YAML
- [ ] Verificar se limites de DoS são razoáveis
- [ ] Verificar que testes cobrem todos os controles de segurança

## Issues Relacionadas

- Fecha CodeRabbit Issue #1: Arquivos corrompidos agora falham na validação
- Fecha CodeRabbit Issue #2: Path traversal totalmente prevenido
- Fecha CodeRabbit Issue #3: Divergências de tamanho agora tratadas corretamente

## Referências

- [minisign](https://jedisct1.github.io/minisign/) - Ferramenta de assinatura
- [OWASP Path Traversal](https://owasp.org/www-community/attacks/Path_Traversal)
- [CWE-22: Improper Limitation of a Pathname](https://cwe.mitre.org/data/definitions/22.html)