CSRF Protection (everton3x/csrf)

Biblioteca utilitária em PHP simples, leve e segura para prevenção e proteção contra ataques do tipo CSRF/XSRF (Cross-Site Request Forgery) em aplicações web.

---

🛡️ O que é CSRF?

O ataque de Falsificação de Solicitação entre Sites (CSRF/XSRF) ocorre quando uma aplicação web maliciosa faz com que o navegador de um usuário execute ações indesejadas em uma aplicação confiável na qual o usuário está autenticado no momento.

Esta biblioteca mitiga esse vetor de ataque vinculando cada requisição do tipo POST a um token criptográfico único armazenado na sessão do usuário ($_SESSION).

---

✨ Características e Recursos

• Simplicidade de Integração: API estática direta ao ponto com apenas dois métodos principais (Csrf::token() e Csrf::check()).
• Criptograficamente Seguro: Geração de tokens de alta entropia utilizando random_bytes(32).
• Prevenção a Timing Attacks: Comparação segura de tokens utilizando a função nativa hash_equals().
• Rotação Automática de Tokens: A cada requisição validada com sucesso, um novo token é emitido automaticamente, prevenindo reutilização (replay attacks).
• Tratamento Imediato de Violações: Interrompe requisições inválidas ou sem token enviando o status HTTP padronizado 409 Conflict (HTTP/1.1 409 Conflict).

---

📋 Requisitos

• PHP 8.5.7 ou superior
• Extensão session habilitada (sessões PHP ativas via session_start())

---

📦 Instalação

Instale a biblioteca em seu projeto utilizando o Composer:

composer require everton3x/csrf

---

🚀 Como Usar

O uso da biblioteca é composto por três etapas simples:

1. Iniciar a Sessão do PHP

Certifique-se de chamar session_start() antes de invocar qualquer método da biblioteca.

2. Renderizar o Token no Formulário HTML

No seu formulário HTML, inclua a chamada Csrf::token(). O método gera o token (caso ainda não exista na sessão) e renderiza a tag <input type="hidden" name="csrf_token" value="..."> com o valor sanitizado:

<?php
require_once __DIR__ . '/vendor/autoload.php';

use Csrf\Csrf;

session_start();
?>

<form action="processar.php" method="POST">
    <!-- Renderiza o campo oculto com o token CSRF -->
    <?= Csrf::token(); ?>

    <input type="text" name="usuario" placeholder="Nome de usuário" required>
    <button type="submit">Entrar</button>
</form>

3. Validar a Requisição no Endpoint Receptor

No arquivo que processa a requisição POST (ex: processar.php), invoque Csrf::check():

<?php
require_once __DIR__ . '/vendor/autoload.php';

use Csrf\Csrf;

session_start();

// Valida a requisição POST contra o token da sessão
Csrf::check();

// Se chegou até aqui, a requisição é legítima!
echo "Requisição validada com sucesso!";

Note

Se o token for inválido, ausente ou se a requisição não corresponder à sessão atual, Csrf::check() define o cabeçalho de resposta HTTP/1.1 409 Conflict e interrompe imediatamente a execução da aplicação (exit).

---

📖 Referência da API

Csrf::token(): string

Gera (caso necessário) e retorna a tag HTML do campo oculto contendo o token CSRF da sessão atual, sanitizado para inclusão segura no documento.

• Retorno: string contendo <input type="hidden" name="csrf_token" value="...">
• Exceções: Lança \RuntimeException se a sessão PHP não tiver sido iniciada (!isset($_SESSION)).

Csrf::check(): void

Inspeciona requisições do tipo POST e valida o campo csrf_token contra o valor armazenado em $_SESSION['csrf_token'].

• Comportamento:
  • Requisições com métodos diferentes de POST são ignoradas.
  • Compara os tokens usando hash_equals($sessinToken, $formToken).
  • Em caso de sucesso, renova o token na sessão (self::generateToken()) e permite que a execução continue.
  • Em caso de falha (token ausente ou incorreto), responde com HTTP 409 Conflict e encerra o script (exit).
• Exceções: Lança \RuntimeException se a sessão PHP não tiver sido iniciada.

---

🧪 Exemplo Prático

O projeto inclui uma aplicação funcional demonstrando formulários válidos e cenários de falha.

Para executar o exemplo localmente:

# A partir da raiz do projeto
php -S localhost:8000 -t example

Acesse http://localhost:8000 no navegador.

Para mais detalhes sobre o funcionamento do exemplo, consulte o arquivo example/README.md.

---

🛠️ Desenvolvimento e Qualidade

O projeto utiliza ferramentas modernas de garantia de qualidade:

Análise Estática (PHPStan)

composer static
# ou
vendor/bin/phpstan analyse src

Testes Automatizados (Pest)

composer test

---

👤 Autor

• Everton da Rosa
  • E-mail: [email protected]
  • Homepage: https://everton3x.github.io

---

📄 Licença

Este projeto está licenciado sob a licença MIT - consulte o arquivo LICENSE para obter mais detalhes.