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.

Instalando o Middleware CSRF

Para instalar o middleware CSRF, utilize o Composer:

composer require lithemod/csrf

Você pode encontrar mais informações e o código fonte do módulo em github.com/lithemod/csrf.

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:

use Lithe\Middleware\Security\csrf;

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

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 dentro de uma rota:

$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.

  $app->get('/', function ($req, $res) {
      $token = $req->csrf->generateToken();
      // Lógica adicional
  });
  

• getToken(): string
  Retorna o token CSRF atual armazenado na sessão.

  $app->get('/', function ($req, $res) {
      $token = $req->csrf->getToken();
      // Lógica adicional
  });
  

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:

$app->get('/form', function ($req, $res) {
    $res->send($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.

  $app->post('/submit', function ($req, $res) {
      $isValid = $req->csrf->verifyToken($req->input('_token'));
      // Lógica adicional
  });
  

Funções de Manipulação de Token

• invalidate(): void
  Destroi o token CSRF e sua variável de sessão associada, invalidando-o.

  $app->get('/invalidate', function ($req, $res) {
      $req->csrf->invalidate();
  });
  

• exists(): bool
  Verifica se um token CSRF existe na sessão.

  $app->get('/', function ($req, $res) {
      $exists = $req->csrf->exists();
      // Lógica adicional
  });
  

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.