NAME

PAGI::Middleware::CSRF - Cross-Site Request Forgery protection middleware

SYNOPSIS

use PAGI::Middleware::Builder;

my $app = builder {
    enable 'CSRF',
        secret       => 'your-secret-key',
        token_header => 'X-CSRF-Token',
        cookie_name  => 'csrf_token',
        safe_methods => ['GET', 'HEAD', 'OPTIONS'];
    $my_app;
};

DESCRIPTION

PAGI::Middleware::CSRF provides protection against Cross-Site Request Forgery attacks by validating tokens on state-changing requests.

CONFIGURATION

• secret (required)

  Secret key used for token generation.

• token_header (default: 'X-CSRF-Token')

  Header name to look for the CSRF token.

• token_param (default: '_csrf_token')

  Form parameter name to look for the CSRF token.

• cookie_name (default: 'csrf_token')

  Cookie name for the CSRF token.

• safe_methods (default: ['GET', 'HEAD', 'OPTIONS', 'TRACE'])

  HTTP methods that don't require CSRF validation.

USAGE

The CSRF middleware uses a double-submit cookie pattern:

1. A token is generated and stored in a cookie 2. The same token must be submitted with unsafe requests (POST, PUT, etc.) 3. The submitted token is compared with the cookie token

To use in your application:

1. For forms, include the token in a hidden field:

<input type="hidden" name="_csrf_token" value="<%= $scope->{csrf_token} %>">

2. For AJAX requests, include the token in a header:

fetch('/api/resource', {
    method: 'POST',
    headers: {
        'X-CSRF-Token': getCookie('csrf_token')
    }
});

SEE ALSO

PAGI::Middleware - Base class for middleware