CSRF

O middleware CSRF (Cross-Site Request Forgery) no Lithe protege sua aplicação contra ataques que tentam realizar ações em nome do usuário sem a sua autorização.

Usando o Middleware CSRF

O middleware CSRF no Lithe é projetado para proteger sua aplicação contra ataques de falsificação de requisições entre sites (CSRF). Para configurá-lo, adicione-o à sua aplicação usando o método use() em uma instância do aplicativo Lithe e forneça um array de configurações:

use Lithe\Middleware\Security\csrf;

$app->use(csrf([
    'expire' => 600,
]));

Isso garante que todas as requisições que alteram o estado da aplicação (como POST, PUT, DELETE) contenham um token CSRF válido, conforme configurado.

Configurações do Middleware

O middleware CSRF pode ser configurado com os seguintes parâmetros em um array:

name (string): O nome do token CSRF. O padrão é _token.
expire (int): O tempo de expiração do token em segundos. O padrão é 600 segundos.
checkBody (bool): Indica se o token deve ser verificado no corpo da requisição. O padrão é false.
bodyMethods (array): Métodos HTTP para os quais a validação do token deve ser aplicada se a configuração checkBody estiver habilitada. O padrão é ['POST'].
regenerate (bool): Indica se o token deve ser regenerado a cada requisição. O padrão é false.

Exemplo de configuração:

$app->use(csrf([
    'name' => '_token',
    'expire' => 600,
    'checkBody' => true,
    'bodyMethods' => ['POST', 'PUT', 'DELETE'],
    'regenerate' => true,
]));

Gerando e Obtendo Tokens CSRF

O middleware CSRF gera um token único para cada sessão. Você pode gerar e obter o token usando os seguintes métodos:

generateToken(bool $force = false): string
Gera um novo token CSRF e o armazena na sessão. Se $force for true, um novo token será gerado mesmo que já exista um.
```
$token = $req->csrf->generateToken();
```
getToken(): string
Retorna o token CSRF atual armazenado na sessão.
```
$token = $req->csrf->getToken();
```

Incluindo o Token CSRF em Formulários

Para incluir o token CSRF em formulários HTML, use o método getTokenField() para gerar um campo oculto com o token:

echo $req->csrf->getTokenField();

Verificando Tokens CSRF

O middleware verifica automaticamente o token em requisições POST e outros métodos especificados em bodyMethods quando a opção checkBody está habilitada. Se o token for inválido ou estiver ausente, uma exceção HTTP 419 será lançada. Se checkBody estiver desativado, você pode usar os seguintes métodos para verificar a validade do token:

verifyToken(string $token, bool $checkBody = false): bool
Verifica se o token CSRF fornecido é válido. Se $checkBody for true, ele verifica o token no corpo da requisição; caso contrário, verifica na sessão.
```
$isValid = $req->csrf->verifyToken($token);
```

Funções de Manipulação de Token

invalidate(): void
Destroi o token CSRF e sua variável de sessão associada, invalidando-o.
```
$req->csrf->invalidate();
```
exists(): bool
Verifica se um token CSRF existe na sessão.
```
$exists = $req->csrf->exists();
```

Considerações

Segurança: Certifique-se de que o token CSRF esteja incluído em todos os formulários que enviam dados modificáveis e em requisições AJAX para prevenir ataques CSRF. A validação e inclusão adequada do token são essenciais para proteção adequada.
Expiração do Token: Configure o tempo de expiração do token com cuidado para equilibrar segurança e usabilidade. Tokens expirados são regenerados para evitar problemas de autenticação.
Verificação no Corpo: Se checkBody estiver habilitado, o token será verificado tanto nos cabeçalhos quanto no corpo da requisição. Isso é útil para APIs que recebem tokens via POST, PUT ou DELETE, mas pode adicionar uma sobrecarga extra.
Regeneração do Token: Quando regenerate está habilitado, um novo token é gerado a cada requisição. Isso pode aumentar a segurança, mas deve ser usado com cautela para não impactar a experiência do usuário.
Tratamento de Erros: Esteja preparado para lidar com exceções HTTP 419 lançadas quando o token CSRF é inválido ou ausente. Isso pode incluir redirecionar para uma página de erro ou exibir uma mensagem apropriada para o usuário. Para mais informações sobre o tratamento de exceções HTTP, consulte a documentação de Exceções HTTP.