# Revisão de segurança — padrões adotados no sistema

Documento para **revisar mudanças de código** (PR, merge homologação → main, análise de qualidade) contra os **padrões de segurança já adotados** neste repositório. Não substitui auditoria externa nem testes de penetração; serve para **não regressar** controles existentes e para **alinhar novas features** ao modelo atual.

---

## 1. Como usar este guia

- **Antes de aprovar** alterações em rotas, autenticação, uploads, webhooks, formulários públicos ou áreas logadas (DaCruz, administrativo, cliente): percorra a **seção 3** (checklist) e a **seção 2** (mapa de padrões) nos trechos afetados.
- **Se introduzir** um novo endpoint sensível: confirme autenticação/autorização, validação de entrada, limitação de taxa quando fizer sentido, e tratamento de erros sem vazamento de detalhes internos.
- **Integrações externas** (webhook, API sem sessão): CSRF da stack `web` **não** protege; exija **assinatura, segredo compartilhado, IP allowlist ou outro controle** documentado pelo provedor.

---

## 2. Mapa dos padrões atuais (por área)

### 2.1 Sessão e cookies

- Configuração em `config/session.php`: cookies com foco em ambiente seguro (`secure` via env, `http_only`, `same_site` típico `lax`).
- **Revisar:** novas features que dependam de cookie cross-site (`SameSite=None`) exigem `Secure` e análise explícita de CSRF.

### 2.2 Proteção CSRF (rotas `web`)

- Laravel aplica verificação CSRF ao grupo `web` por padrão.
- Views expõem `csrf_token` em `<meta name="csrf-token">` e formulários usam `@csrf`.
- Requisições AJAX/fetch devem enviar o token (ex.: header `X-CSRF-TOKEN` alinhado ao meta).

**Revisar:**

- Novo POST/PUT/PATCH/DELETE em rota `web` sem token no cliente.
- Exceções globais de CSRF (se existirem em versões futuras do framework): documentar motivo e compensação.

### 2.3 Autenticação e guards

- Uso de **guards distintos** conforme o painel (ex.: `administrativo`, `cliente`, fluxo web padrão).
- Fluxo **cliente** pode envolver **2FA** e middleware que bloqueia navegação até concluir etapas (`VerificarClienteAtivo`).

**Revisar:**

- Controller que assume usuário logado sem `auth`/`auth:guard` adequado na rota.
- Mistura de guards (ler/escrever sessão do guard errado).

### 2.4 DaCruz (transportadora / colaborador)

- `VerificaTransportadora`: exige sessão da transportadora; validações em cache; aborta com 403 se permissões não configuradas.
- `VerificarPermissao`: exige `id_colaborador` e `transportadora` na sessão; perfis **Administrador** e **Comercial** com acesso amplo; perfil **Personalizado** consulta `config/permissions-routes.php` (mapeamento permissão → nomes de rota); logs em canais de warning em tentativas suspeitas.
- Tokens em URL/query em fluxos específicos (`VerificaToken`): validade e revogação no banco.

**Revisar:**

- Nova rota nomeada DaCruz sem estar em `permissions-routes.php` quando o público-alvo for perfil **Personalizado** (risco de bloqueio indevido ou necessidade de nova chave de permissão).
- Expor IDs ou tokens em logs em claro sem necessidade.
- Confiar apenas em dados do cliente (hidden fields) para autorização; **sempre** revalidar no servidor com sessão/DB.

### 2.5 Administrativo (painel interno)

- `VerificarAdministrativoPermissoes` (`auth.administrativo`):  
  - exige login no guard administrativo;  
  - **fingerprint** de sessão `hash('sha256', User-Agent + IP)` — mudança de IP ou UA invalida sessão;  
  - **rotas bloqueadas** por último segmento da URI conforme campo `bloqueados` do usuário.

**Revisar:**

- Novas URLs administrativas: o último segmento pode coincidir com valor em `bloqueados` — validar regra de negócio.
- Operações sensíveis sem confirmação de papel (apenas “estar logado” pode não bastar se houver subperfis no futuro).

### 2.6 LGPD e consentimento

- `VerificarConsentimentoLgpd`: para usuário autenticado com e-mail, exige consentimentos ativos (política e termos) antes de prosseguir.

**Revisar:**

- Novo fluxo que armazena/processa dados pessoais sem passar pelas mesmas regras de consentimento quando aplicável.
- Formulários públicos: checkbox/termos alinhados ao backend (não só ao HTML).

### 2.7 Limitação de taxa (rate limiting)

- Exemplos no projeto: limite nomeado `uploads` (por IP) em `AppServiceProvider`; `throttle` em verificação de e-mail; lógica de bloqueio/throttle em controllers de login (DaCruz/administrativo).

**Revisar:**

- Endpoints públicos de alto risco (login, recuperação de senha, envio em massa, APIs abertas) sem limite quando o padrão do módulo já usa throttle.
- Uploads: respeitar o limiter `uploads` ou justificar exceção.

### 2.8 Rotas `api` e webhooks

- `routes/api.php` concentra integrações POST externas (ex.: webhooks de pagamento, WhatsApp).

**Revisar:**

- **Crítico:** validação de origem/assinatura/payload conforme documentação do provedor (o repositório já possui notas de hardening em materiais como `webhook-cora-seguranca.md` — alinhar implementação ao que foi acordado).
- Idempotência e proteção contra replay quando o negócio exigir.
- Não retornar stack traces ou mensagens internas em JSON de erro.

### 2.9 Validação de entrada

- Padrão Laravel: `$request->validate()`, regras explícitas, Form Requests onde o projeto já os utiliza (`app/Http/Requests/...`).

**Revisar:**

- `Request::all()` sem validação em ação que persiste ou executa efeito.
- Uploads: tipo MIME/extensão, tamanho máximo, armazenamento fora da web root quando possível, nomes seguros.
- SQL: usar binding; evitar concatenação de strings vindas do usuário (o projeto usa SQL em arquivos `.sql` para schema, mas **consultas em runtime** devem permanecer parametrizadas).

### 2.10 Views (Blade) e XSS

- Padrão: `{{ }}` escapa; `{!! !!}` apenas para HTML confiável (markdown sanitizado, HTML fixo).

**Revisar:**

- `{!! $variavelUsuario !!}` sem sanitização.
- JSON embutido em `<script>`: usar `json_encode` com flags adequadas e dados já validados.

### 2.11 Logs e mensagens de erro

- Tentativas de acesso negado no DaCruz costumam gerar log estruturado (canal dedicado).

**Revisar:**

- Logar dados sensíveis (senha, token completo, CPF integral) em claro.
- Resposta HTTP com `$e->getMessage()` ou trace para o navegador em produção.

---

## 3. Checklist rápido por tipo de mudança

| Tipo de mudança | Verificar |
|-----------------|----------|
| Nova rota GET autenticada | Middleware/guard correto; autorização (permissão/bloqueio); cache não vaza dados de outro tenant |
| Nova rota POST/PUT/DELETE | CSRF (web); validação; idempotência se webhook; rate limit se público |
| Novo formulário público | Validação server-side; spam/abuse (rate limit, captcha se padrão do site); LGPD |
| Novo arquivo upload | Validação de tipo/tamanho; path seguro; vírus scan se política existir |
| Nova integração webhook | Assinatura/segredo; rejeitar payload inválido; logs sem segredos |
| Query SQL / relatório | Apenas parâmetros bindados; escopo por transportadora/cliente quando multi-tenant |
| Blade / JS | Sem XSS; sem secrets no front; tokens só onde necessário |

---

## 4. Relação com outros documentos

- **Homologação → main:** após merge, na fase de verificação local, usar este guia como lembrete para mudanças que tocam autenticação, permissões, webhooks ou dados pessoais (ver `processo-homologacao-para-main-manual-equipe.md`).
- **Análise de qualidade:** problemas de segurança encontrados devem seguir priorização do `guia-analise-qualidade.md`; este arquivo lista **o que o sistema já espera** para não duplicar achados genéricos.

---

## 5. Histórico

| Data | Nota |
|------|------|
| 2026-05-07 | Criação do documento a partir dos padrões observados no código (middleware, config de sessão, permissões, API, LGPD). |