req-274: Autorização de Navegador Confiável para Acesso Anônimo no Site com Acesso Restrito Ativo

1. Relato Original do Engenheiro Chefe Humano

"Eu queria te falar um problema para você colocar para na próxima requisição. Eu já fiz o release, já está online. Lá no ambiente config, no módulo, a gente tem a parte onde cuida de acesso restrito, aí só administrador. Eu precisaria que você me orientasse como que eu faço quando eu quero deslogar para fazer acessos anônimos, mas para o restante dos outros tem que logar, entendeu? Precisava ver um jeito aí. Eu não sei se já tem. Em outras palavras, eu logo, aí aquele navegador me libera para eu acessar e aí depois se eu deslogo ele continua dando acesso, entendeu? Só para quem é de outro IP que não, por exemplo, ou de outro navegador, na verdade, acho que é melhor. E eu não sei se tem isso. E também para poder renovar isso aí e excluir, né? Pode ser no próprio ambiente config, eu acho."

2. Interpretação do Arquiteto & Diagnóstico da Situação Atual

1. Estado Atual no Core (desde a req-163):

   • A trava SITE_RESTRICTED_ACCESS=true no roteador (gestor/gestor.php) é estrita e binária: qualquer requisição a rotas não isentas sem token de autenticação JWT/sessão (gestor_permissao_token()) é interceptada e enviada para /signin/.

   • Quando o administrador faz logout (signout), o cookie de autenticação é destruído. Como consequência, o administrador não consegue auditar ou navegar no site como visitante anônimo, pois o porteiro o bloqueia imediatamente.

   • Atualmente não existe nenhum mecanismo de bypass por IP ou por cookie de navegador confiável no sistema.

2. Necessidade do Negócio:

   • Permitir que administradores autorizem seus navegadores de desenvolvimento/auditoria para navegar no site público deslogados (vendo páginas, formulários e componentes sob a ótica real de um visitante anônimo), enquanto o restante da internet continua rigidamente barrado pela tela de login do Acesso Restrito.

   • Permitir gerenciar esse passe diretamente pelo módulo admin-environment ("Configurações do Ambiente / Site"): autorizar o navegador atual, revogar a autorização do navegador atual, e revogar em massa todos os passes gerados.

3. Especificação Técnica da Solução

3.1. Mecanismo de Token Criptográfico por Cookie (Passe de Navegador)

• Utilizar um cookie assinado criptograficamente com HMAC-SHA256 (_C2F_RESTRICTED_BYPASS):

  • Payload: timestamp_criacao|expiracao|salt_versao assinado com a chave da aplicação (APP_KEY ou secret do Conn2Flow).

  • Parâmetros do Cookie: HttpOnly, SameSite=Lax, Secure (quando HTTPS), validade padrão configurável (ex: 30 dias).

  • O cookie não concede privilégios de usuário ou perfil: ele apenas atua como salvo-conduto perante o porteiro do Acesso Restrito, mantendo o usuário como 100% anônimo no runtime.

3.2. Gerenciamento no Módulo admin-environment (gestor/modulos/admin-environment)

• Na aba "Configurações do Site", dentro da seção "Acesso Restrito ao Site":

  • Exibir um bloco de controle: "Navegador Confiável (Passe para Acesso Anônimo)".

  • Status: Indicador visual mostrando se o navegador que está acessando a tela possui ou não o passe ativo e data de validade.

  • Ação 1 - [Autorizar Este Navegador]:

  • Dispara chamada AJAX para o controlador emitir e gravar o cookie assinado no navegador atual.

  • Ação 2 - [Revogar Este Navegador]:

  • Limpa o cookie do navegador atual.

  • Ação 3 - [Revogar Todos os Navegadores Autorizados]:

  • Incrementa ou regenera a variável SITE_RESTRICTED_BYPASS_SALT (ou timestamp de corte) no .env.

  • Isso invalida imediatamente todos os cookies de bypass emitidos anteriormente em qualquer dispositivo.

3.3. Roteamento e Porteiro em gestor/gestor.php

• Na função gestor_roteador_acesso_restrito():

  • Se SITE_RESTRICTED_ACCESS estiver ativo:

  • Se a requisição não possui sessão de usuário logado (!gestor_permissao_token()):

    • Verificar se a requisição possui o cookie _C2F_RESTRICTED_BYPASS válido e assinado.

    • Se a assinatura HMAC for válida, a expiração não tiver sido atingida e o salt bater com o .env:

    • O porteiro permite a requisição prosseguir sem redirecionamento para o login.

    • Preserva o cabeçalho X-Robots-Tag: noindex, nofollow para evitar indexação por buscadores.

    • A requisição continua com usuário anônimo (gestor_usuario() === null).

    • Se o cookie não for válido ou não existir: mantém o comportamento padrão de redirecionamento para signin/.

4. Escopo Técnico de Alterações

1. gestor/bibliotecas/gestor.php:

   • Novas funções auxiliares puras e testáveis:

     • gestor_site_acesso_restrito_bypass_gerar($validadeDias, $salt)

     • gestor_site_acesso_restrito_bypass_validar($token, $salt)

     • gestor_site_acesso_restrito_bypass_cookie_nome()

2. gestor/gestor.php:

   • Integração da checagem de bypass em gestor_roteador_acesso_restrito().

3. gestor/modulos/admin-environment/admin-environment.php:

   • Ações AJAX para autorizar navegador, revogar navegador atual e revogar todos os navegadores.

4. gestor/modulos/admin-environment/resources/{pt-br,en}/pages/admin-environment/admin-environment.html:

   • Interface com status do navegador, botão de emitir passe, botão de revogar e botão de revogação global.

5. gestor/modulos/admin-environment/admin-environment.js:

   • Interações da interface com feedback visual e atualização de status em tempo real.

6. Testes Unitários:

   • PHPUnit: validação de emissão, assinatura HMAC, expiração, revogação por salt e bypass no roteador de acesso restrito.

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

1. Sem Bypass Ativo: Com SITE_RESTRICTED_ACCESS=true, visitante deslogado continua sendo redirecionado para /signin/.

2. Emissão de Passe: No painel de administração (admin-environment), clicar em "Autorizar este navegador" grava o cookie assinado e atualiza o status na tela.

3. Acesso Anônimo com Passe: Ao deslogar do sistema (signout), o navegador autorizado consegue acessar todas as páginas públicas do site normalmente como visitante deslogado (sem dados de usuário e sem estar logado).

4. Outros Navegadores Bloqueados: Abrir uma janela anônima ou outro navegador sem o cookie mantém o bloqueio estrito para /signin/.

5. Revogação Local: Clicar em "Revogar este navegador" limpa o cookie; o próximo acesso volta a ser bloqueado.

6. Revogação Global: Clicar em "Revogar todos os navegadores" invalida os cookies de todos os dispositivos anteriormente autorizados.

7. SEO Protegido: Todas as páginas servidas via bypass mantêm X-Robots-Tag: noindex, nofollow.