req-163: Interceptação Global de CSRF em XMLHttpRequest e Camada de Acesso Restrito ao Site (admin-environment e gestor.php)

1. Descrição do Problema & Objetivos

Esta requisição formaliza duas entregas de segurança e governança no núcleo do Conn2Flow:

Pilar 1: Interceptação Global de CSRF e Tratamento de 401 em XMLHttpRequest (global.js)

• Contexto: O backend exige token CSRF (X-CSRF-Token ou _csrf_token) para qualquer requisição mutável (POST, PUT, PATCH, DELETE) de usuário autenticado por cookie (seguranca_csrf_requisicao_validar()).

• Problema: O arquivo gestor/assets/global/global.js cobre $.ajax (via prefilter), window.fetch (via monkey-patch) e formulários (via submit nativo e prototype). Porém, XMLHttpRequest cru não é interceptado. Como fetch não possui suporte a eventos de progresso de upload (upload.onprogress), módulos que realizam upload de arquivos (ex.: PDFs no [REDACTED], modelos no 3D-Catalog) recorrem a new XMLHttpRequest() e falham com HTTP 403 Forbidden quando o usuário está logado.

• Objetivo: Estender global.js com wrapper transparente em XMLHttpRequest.prototype.open, setRequestHeader e send, adicionando automaticamente X-CSRF-Token para métodos mutáveis de mesma origem caso não tenha sido informado manualmente, além de unificar o redirecionamento de login em respostas 401 (X-Gestor-Auth-Redirect).

Pilar 2: Camada de Acesso Restrito ao Site para Desenvolvimento e Staging

• Contexto: Instalações em desenvolvimento, homologação ou ambientes privados precisam de blindagem centralizada para que nenhuma página pública seja acessada sem credenciais de acesso válidas, e para que nenhum motor de busca indexe conteúdo do ambiente.

• Objetivo:

  1. No módulo admin-environment (gestor/modulos/admin-environment), criar na aba "Configurações do Site" (inserida como segunda seção, antes de "HTML entregue ao navegador") a seção "Acesso Restrito ao Site":

     • Texto explicativo sobre o uso em desenvolvimento, testes ou ambientes privados.

     • Botão de alternância (toggle) para ativar/desativar o acesso restrito (desativado por padrão).

     • Campo de busca autocomplete via AJAX para seleção de perfis de usuários autorizados (usuarios_perfis).

     • Renderização de badges/tags com botão de remoção ("x") para cada perfil ativo selecionado.

     • Persistência das variáveis no .env: SITE_RESTRICTED_ACCESS (true/false) e SITE_RESTRICTED_PROFILES (lista separada por vírgula dos IDs de perfis autorizados).

  2. No roteador do núcleo (gestor/gestor.php):

     • Quando SITE_RESTRICTED_ACCESS estiver ativo, qualquer rota de página (mesmo as marcadas com sem_permissao) exige autenticação e perfil autorizado.

     • Usuários não logados são direcionados para /signin/ (com redirecionar-local na sessão para retornar após o login).

     • Usuários logados com perfil não autorizado são barrados (redirecionamento ou 403).

     • Se SITE_RESTRICTED_PROFILES estiver vazio, qualquer usuário logado no sistema tem acesso.

  3. Isenções de Segurança Arquiteturais:

     • Rotas de Identidade: /signin/, /signout/, /esqueci-minha-senha/, /redefinir-senha/, /ativacao-de-conta/, /validar-email/, /cookies-is-mandatory/ e _gestor-cookie-verify devem permanecer acessíveis para possibilitar o próprio fluxo de login.

     • APIs e Webhooks: Controladores de API (_api/, api/) e gateways (_gateways/), que usam tokens de máquina ou assinaturas HMAC próprias de webhooks de pagamento (ex.: PayPal, Stripe), operam sem cookie de sessão e continuam liberados para não interromper integrações externas.

     • Arquivos Estáticos: O despachador de arquivos estáticos (arquivo-estatico.php) permanece liberado para servir imagens, CSS e scripts necessários para a renderização da tela de login.

  4. Bloqueio Mandatório de Indexação (SEO):

     • Quando SITE_RESTRICTED_ACCESS estiver ativo, forçar <meta name="robots" content="noindex, nofollow"> no <head> e o cabeçalho HTTP X-Robots-Tag: noindex, nofollow em 100% das páginas servidas pelo sistema.

2. Escopo Técnico de Alterações

Módulo 1: Interceptação Global em gestor/assets/global/global.js

• Interceptar XMLHttpRequest.prototype.open para memorizar método e URL na instância.

• Interceptar XMLHttpRequest.prototype.setRequestHeader para registrar cabeçalhos manuais.

• Interceptar XMLHttpRequest.prototype.send para injetar X-CSRF-Token em métodos mutáveis de mesma origem caso não tenha sido definido manualmente.

• Adicionar ouvinte no XHR para tratar 401 com cabeçalho X-Gestor-Auth-Redirect.

• Proteger contra dupla injeção com a flag XMLHttpRequest.prototype.__c2fCsrf = true.

Módulo 2: Interface e Persistência em gestor/modulos/admin-environment

• Em admin-environment.php:

  • Ler e escrever SITE_RESTRICTED_ACCESS e SITE_RESTRICTED_PROFILES no .env.

  • Endpoint AJAX (ajaxOpcao: 'buscar-perfis') para consulta de perfis na tabela usuarios_perfis.

  • Passagem dos perfis ativos e estado do toggle para o template.

• Em admin-environment.html (pt-br e en):

  • Inserir seção "Acesso Restrito ao Site" na aba data-tab="site", logo antes de "HTML entregue ao navegador".

  • Componente de autocomplete e contêiner para os perfis adicionados.

• Em admin-environment.js:

  • Gerenciar a busca AJAX, inserção de tags/badges dos perfis e remoção no clique do "x".

Módulo 3: Roteamento e SEO em gestor/gestor.php

• Em gestor_roteador():

  • Avaliar flag SITE_RESTRICTED_ACCESS.

  • Criar lista canônica de rotas de identidade isentas (signin, signout, etc.).

  • Para rotas não isentas: verificar gestor_permissao_token(). Se não autenticado, salvar redirecionar-local e chamar gestor_roteador_erro(['codigo' => 401, 'redirect' => 'signin/']).

  • Se autenticado e houver perfis restritos definidos em SITE_RESTRICTED_PROFILES, verificar se o perfil do usuário atual (gestor_usuario_perfil()) está autorizado.

• Em gestor_pagina_extra_head_e_javascript():

  • Se SITE_RESTRICTED_ACCESS for ativo, injetar obrigatoriamente <meta name="robots" content="noindex, nofollow"> e header('X-Robots-Tag: noindex, nofollow').

Módulo 4: Governança, Skills e Documentação

• Atualizar a skill .codex/skills/c2f-javascript-ajax/SKILL.md (e espelhos) informando a cobertura automática de XMLHttpRequest.

• Documentar a nova diretiva de ambiente na memória de engenharia.

3. Critérios de Validação e Aceite

1. CSRF em XMLHttpRequest:

   • Teste Vitest em tests/Unit/JS/global-csrf.test.js simulando POST via new XMLHttpRequest() de mesma origem: cabeçalho X-CSRF-Token injetado automaticamente.

   • Requisição que já declare X-CSRF-Token manualmente não duplica nem sobrescreve o valor.

   • Requisições GET ou cross-origin não recebem o cabeçalho.

2. Acesso Restrito ao Site:

   • Com SITE_RESTRICTED_ACCESS=true, acessar página pública sem login redireciona para /signin/.

   • Acessar /signin/ carrega normalmente sem laço de redirecionamento.

   • Arquivos estáticos (CSS, imagens) continuam respondendo 200.

   • APIs (_api/) e webhooks (_gateways/) continuam respondendo sem exigência de cookie de sessão.

   • Usuário logado com perfil autorizado acessa as páginas normalmente; usuário com perfil não autorizado é bloqueado.

   • Com SITE_RESTRICTED_ACCESS=false, o site volta a permitir acesso público irrestrito às páginas sem permissão.

3. Bloqueio de Indexação:

   • Com SITE_RESTRICTED_ACCESS=true, qualquer página HTML servida traz noindex, nofollow na meta tag e no cabeçalho X-Robots-Tag.

4. Suíte e Pipeline:

   • c2f resources:sync --force executado com sucesso e version bump aplicado.

   • PHPUnit e Vitest com 100% de aprovação (zero regressão).