Biblioteca seguranca.php

Caminho no Gestor bibliotecas/seguranca.php

Reúne as defesas de requisição do Gestor. O roteador a carrega em toda requisição, para validar o CSRF antes de qualquer módulo (ciclo de uma requisição).

CSRF

seguranca_csrf_requisicao_validar() roda em gestor_start() e só exige o token quando todas as condições valem:

• o método é POST, PUT, PATCH ou DELETE;

• a requisição traz o cookie de autenticação (COOKIE_AUTHNAME): formulários públicos de visitantes não passam por aqui e se protegem com CAPTCHA;

• a rota não é isenta: _api/…, api/… e _gestor-csrf-token, além das exceções de transição do admin-atualizacoes para clientes anteriores à 2.9.25.

Falhou, a resposta é 403 com {"status":"error","code":"CSRF_INVALID_OR_EXPIRED",…}.

Em código próprio, formulários enviados por fetch/$.ajax já levam o token (o global.js o anexa). Num <form> HTML comum, inclua o campo:

<input type="hidden" name="_csrf_token" value="…valor de gestor_csrf_token()…">

CAPTCHA

gestor_captcha_validar($token = null, $opcoes = []) confere o token no provedor de CAPTCHA_PROVIDER (google-recaptcha, cloudflare-turnstile ou none, que sempre aprova).

• Sem $token, lê cf-turnstile-response, g-recaptcha-response ou token do POST.

• Opções: provider, secret, v2 (usa a chave do reCAPTCHA v2), action (exigida no v3: confere a ação e nota mínima 0,5), return_response, transport (injeção para testes).

• Devolve o array de resposta do provedor em caso de sucesso, ou false. Tempo limite de 5 s.

No reCAPTCHA v3, a nota só é conferida quando action é passada: sem ela, qualquer token válido passa, mesmo de robô.

Sessão: User-Agent e IP

No login, seguranca_sessao_registrar() guarda na sessão o User-Agent (255 caracteres) e o bloco de IP (/24 no IPv4; o endereço inteiro no IPv6). A cada requisição autenticada, gestor_permissao_token() chama seguranca_sessao_validar(); divergiu, seguranca_sessao_invalidar() apaga o token de usuarios_tokens e o usuário volta ao login.

O IP usado é o REMOTE_ADDR cru, não o de ip_get(): atrás de proxy reverso, é sempre o IP do proxy e a checagem de IP não distingue ninguém.

Utilitários

• seguranca_token_aleatorio($bytes = 32): hexadecimal com random_bytes(), mínimo de 16 bytes.

• seguranca_ip_bloco($ip = null), seguranca_user_agent().

Auxiliares internos (usados pelas funções acima; raramente chamados direto): seguranca_csrf_rota_isenta(), seguranca_csrf_resposta_invalida_corpo(), seguranca_csrf_atualizador_transicao_isento(), seguranca_csrf_atualizador_status_isento(), seguranca_csrf_atualizador_sessao_legada_isento().

Funções

gestor_captcha_validar(?string $token = null, array $opcoes = []): array|bool

seguranca_token_aleatorio(int $bytes = 32): string

seguranca_ip_bloco(string|null $ip = null): string

seguranca_user_agent(): string

seguranca_sessao_registrar(): void

seguranca_sessao_validar(): bool

seguranca_sessao_invalidar(string|null $tokenPubId = null): void

gestor_csrf_token(): string

gestor_csrf_validar(string $token, $esperado = null): bool

seguranca_csrf_token_requisicao(): string

seguranca_csrf_rota_isenta(array $caminho): bool

seguranca_csrf_resposta_invalida_corpo(string $mensagem): array

seguranca_csrf_token_resposta(array $contexto): array

seguranca_csrf_retorno_normalizar(mixed $retorno): string

seguranca_csrf_atualizador_transicao_isento(array $caminho, string $versao): bool

seguranca_csrf_atualizador_status_isento(array $caminho, array $requisicao): bool

seguranca_csrf_atualizador_sessao_legada_isento(array $caminho, array $requisicao, string|null $rootPath = null, int|null $agora = null): bool

seguranca_csrf_requisicao_validar(): bool