req-107: Hardening de Segurança, Mitigação de Vulnerabilidades e Saneamento do Core

Descrição do Problema / Contexto

Esta requisição (BATCH-107) consolida e formaliza em especificação executável a suíte completa de 10 recomendações de segurança e arquitetura identificadas no backlog (BL-001 a BL-010).

O objetivo é promover o endurecimento (hardening) de segurança repo-wide no conn2flow, corrigindo vulnerabilidades em potencial na cadeia de instalação, geração de tokens, tratamento de caminhos estáticos, validação CSRF, cabeçalhos HTTP, endpoints de API/OAuth2 e persistência de dados.

Proposta de Alterações Detalhada

PARTE I: Segurança no Instalador e Servidor de Estáticos (BL-001, BL-003, BL-006, BL-009)

1. Integridade e Validação no Download de Releases (BL-001 - gestor-instalador/src/Installer.php):

   • Remover a desativação de SSL (CURLOPT_SSL_VERIFYPEER = false).

   • Baixar o hash .sha256 correspondente do release e implementar verificação estrita via verifyZipSha256 (alinhado a atualizacoes-sistema.php) antes da descompactação. Abortar se houver inconsistência.

2. Contenção de Path Traversal em Arquivos Estáticos (BL-003 - controladores/arquivo-estatico/arquivo-estatico.php, gestor.php):

   • Rejeitar imediatamente sequências de .., bytes nulos (\0) e barras invertidas no parâmetro _gestor-caminho / caminho-total.

   • Validar contenção física pós-resolução com realpath() utilizando str_starts_with() contra os diretórios base autorizados (assets/, contents/, modulos/).

3. Lock de Execução e Limpeza de Resíduos no Instalador (BL-006 - gestor-instalador/):

   • Exigir arquivo de trava install.lock ou token de sessão para processar etapas no index.php.

   • Bloquear re-execução em ambientes já instalados.

   • Forçar a limpeza/remoção completa de scripts de instalação e do installer.log ao concluir.

   • Substituir preg_replace por escrita literal ao gravar variáveis com metacaracteres no .env.

4. Cabeçalhos de Segurança HTTP (BL-009 - gestor.php):

   • Emitir no bootstrap de resposta HTML: X-Content-Type-Options: nosniff, Referrer-Policy: strict-origin-when-cross-origin, X-Frame-Options: SAMEORIGIN (ou frame-ancestors compatível com o módulo distribuído) e Strict-Transport-Security em HTTPS.

   • Suportar modo Report-Only para Content-Security-Policy (CSP) parametrizável via .env.

PARTE II: Criptografia, Proteção CSRF, API e OAuth2 (BL-002, BL-004, BL-005, BL-008)

5. Geração Criptograficamente Segura de Tokens e Sessões (BL-002 - gestor.php, oauth2.php):

   • Substituir o uso de md5(uniqid(rand(), true)) e md5(uniqid(mt_rand(), true)) pela helper centralizada seguranca_token_aleatorio($bytes) utilizando random_bytes() (CSPRNG de no mínimo 128 bits de entropia).

   • Aplicar a IDs de sessão, cookies de verificação e pubID de tokens OAuth2.

6. *Ativação da Proteção CSRF (BL-004 - seguranca.php, formulario.php, `interface.php`)**:

   • Injetar tokens CSRF em formulários e no cabeçalho/meta das requisições do painel administrativo.

   • Acionar obrigatoriamente gestor_csrf_validar() no processamento de requisições POST/PUT/DELETE autenticadas por cookie de sessão.

   • Manter isenção documentada para requisições M2M/HMAC (_api e canal distribuído).

7. Hardening da API Pública (BL-005 - controladores/api/api.php):

   • Parametrizar Access-Control-Allow-Origin via allow-list no .env (em vez do wildcard * genérico para endpoints autenticados).

   • Remover suporte à passagem de tokens de acesso via query string (?token=), aceitando exclusivamente o cabeçalho Authorization: Bearer.

   • Atualizar a gestão de rate limit para persistência com controle por usuário/rota.

8. Hardening do OAuth2 (BL-008 - bibliotecas/oauth2.php):

   • Incluir validação do HMAC pubIDValidation durante a verificação de access tokens em oauth2_validar_token().

   • Substituir a negação de login ao atingir o limite máximo de tokens por rotação FIFO (revogação do token ativo mais antigo).

PARTE III: Acesso a Dados e Saneamento de Código (BL-007, BL-010)

9. Prepared Statements e Escape Seguro (BL-007 - bibliotecas/banco.php, banco-v2.php):

   • Padronizar novos acessos de banco em prepared statements via banco-v2.php.

   • Remover o fallback inseguro addslashes() em banco_escape_field() quando não houver conexão mysqli ativa, fazendo o escape falhar explicitamente.

10. Aposentadoria de Código Morto e Hashing de Senhas (BL-010 - bibliotecas/, perfil-usuario.php):

    • Definir as bibliotecas -v2 como canônicas para novas funcionalidades e marcar a suíte legada v1 como obsoleta.

    • Remover comentários e algoritmos mortos; preservar como shim deprecated qualquer função pública ainda consumida externamente, incluindo banco_smartstripslashes().

    • Ajustar password_hash() no módulo de perfil para utilizar Argon2id com parâmetros explícitos (memory_cost, time_cost, threads).

Validação e Testes

1. Validação Estática:

   • php -l em todas as bibliotecas e controladores alterados.

   • node --check em scripts JS que consumirem os novos tokens/headers.

2. Suíte de Testes Automatizados:

   • Criar testes em tests/Unit/PHP/ para a verificação de verifyZipSha256, rejeição de Path Traversal (../), validação de CSRF e rotação FIFO de tokens OAuth2.

   • Executar suíte completa via composer test e npx vitest run.

Resultado da Implementação e Homologação

Status final: implementado e homologado em múltiplas instâncias de teste, consolidado na tag gestor-v2.9.30 em 2026-08-06.

Além dos dez itens originais, a homologação do CSRF e do processo de atualização revelou requisitos operacionais que passam a integrar esta requisição:

1. Compatibilidade do autoatualizador durante a troca do próprio código:

   • Uma página aberta em uma versão anterior ao CSRF pode executar start/deploy sem token e, após o deploy, encontrar o backend novo já exigindo CSRF nos passos db/finalize.

   • A compatibilidade não pode depender somente de $_GESTOR['versao'], pois o config.php é substituído durante o passo deploy enquanto o JavaScript antigo continua em memória.

   • Sessões legadas passam a ser reconhecidas pelo SID aleatório e pelo estado persistido em temp/atualizacoes/sessions/<sid>.json, com janela máxima de seis horas, sessão inacabada e validação da etapa esperada (deploy, db, finalize ou cancel).

   • Clientes atuais registram csrf_capable=1 na criação da sessão e permanecem obrigados a enviar o token; um token presente porém inválido nunca utiliza a isenção legada.

   • A consulta status, embora enviada por POST por clientes antigos, é tratada como leitura e pode consultar uma sessão válida sem CSRF.

   • A limpeza global de sessões provocada pelas migrações é adiada até depois de finalize, preservando o token necessário para terminar o fluxo.

2. Expiração de autenticação durante AJAX:

   • Ausência/expiração de login recebe o marcador explícito AUTH_REQUIRED e o header X-Gestor-Auth-Redirect.

   • Os interceptadores globais de jQuery e fetch redirecionam uma única vez para signin/, aceitam somente destino de mesma origem e preservam a rota local para retorno após o login.

   • O 401 de falta de permissão de módulo permanece distinto e não provoca redirecionamento incorreto ao login.

3. Cache do autoatualizador:

   • A versão de admin-atualizacoes.json foi elevada até 1.0.4, garantindo cache-bust do JavaScript que identifica clientes compatíveis com CSRF.

   • O asset global continua versionado por $_GESTOR['versao'], portanto o incremento do release invalida o cache do interceptor global.

4. Release manual e conteúdo de vendor/:

   • Foi criado/ajustado o modo de release manual para quando o GitHub Actions estiver indisponível, mantendo ZIP, SHA-256, notas e publicação equivalentes ao workflow.

   • O diretório vendor/ continua incluído porque fornece autoload.php, Phinx, Dotenv e demais dependências de runtime.

   • Metadados vendor/**/.git/ não são necessários em runtime: 21 diretórios internos, próximos de 100 MB, foram removidos do ambiente de empacotamento.

   • Workflow e script manual usam Composer com --prefer-dist, removem .git aninhados e falham defensivamente se algum permanecer no staging antes de produzir gestor.zip.

   • Artefatos locais de release não são adicionados acidentalmente ao commit.

5. Compatibilidade do banco legado:

   • banco.php permanece disponível e continua sendo o caminho padrão das áreas existentes; não houve remoção nem migração forçada repo-wide.

   • “Legado/obsoleto” significa que novas funcionalidades devem preferir banco-v2.php e prepared statements, mantendo compatibilidade com o core atual.

   • A remoção inicial de banco_smartstripslashes() foi revertida após a identificação de consumidores ativos em módulos externos. A função permanece deprecated com seu contrato efetivo anterior — conversão para string — sem reativar o algoritmo comentado de remoção de barras.

Evidências de homologação

• Instância conn2flow-site: reproduzidos e corrigidos CSRF em finalize/status e expiração do login durante atualização.

• Instância photon: sessão real a94064ba170414e5 reproduziu a falha entre deploy_files_done e db; o estado persistido foi validado pela nova regra de transição.

• PHPUnit final após a restauração de compatibilidade: 185 testes, 749 asserções, 4 skips preexistentes e nenhuma falha.

• Vitest final: 140 testes, nenhuma falha.

• php -l, node --check e git diff --check: aprovados nos arquivos alterados.