seguranca.php library

Path in the Gestor bibliotecas/seguranca.php

It gathers the Gestor's request defenses. The router loads it on every request, to validate CSRF before any module runs (request lifecycle).

CSRF

seguranca_csrf_requisicao_validar() runs in gestor_start() and only requires the token when all these conditions hold:

• the method is POST, PUT, PATCH or DELETE;

• the request carries the authentication cookie (COOKIE_AUTHNAME): visitors' public forms do not go through here and are protected by CAPTCHA;

• the route is not exempt: _api/…, api/… and _gestor-csrf-token, plus the admin-atualizacoes transition exceptions for clients older than 2.9.25.

On failure, the answer is 403 with {"status":"error","code":"CSRF_INVALID_OR_EXPIRED",…}.

In your own code, forms sent with fetch/$.ajax already carry the token (global.js attaches it). In a plain HTML <form>, include the field:

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

CAPTCHA

gestor_captcha_validar($token = null, $options = []) checks the token with the CAPTCHA_PROVIDER provider (google-recaptcha, cloudflare-turnstile or none, which always approves).

• Without $token, it reads cf-turnstile-response, g-recaptcha-response or token from POST.

• Options: provider, secret, v2 (uses the reCAPTCHA v2 key), action (required in v3: checks the action and a minimum score of 0.5), return_response, transport (injection for tests).

• It returns the provider's response array on success, or false. 5 s timeout.

In reCAPTCHA v3, the score is only checked when action is passed: without it, any valid token passes, even a bot's.

Session: User-Agent and IP

At login, seguranca_sessao_registrar() stores in the session the User-Agent (255 characters) and the IP block (/24 for IPv4; the full address for IPv6). On every authenticated request, gestor_permissao_token() calls seguranca_sessao_validar(); on a mismatch, seguranca_sessao_invalidar() deletes the token from usuarios_tokens and the user goes back to the login.

The IP used is the raw REMOTE_ADDR, not the one from ip_get(): behind a reverse proxy, it is always the proxy's IP and the IP check tells nobody apart.

Utilities

• seguranca_token_aleatorio($bytes = 32): hexadecimal from random_bytes(), at least 16 bytes.

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

Internal helpers (used by the functions above; rarely called directly): 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().

Functions

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