File Coverage

blib/lib/Mojolicious/Plugin/WithCSRFProtection.pm

Criterion	Covered	Total	%
statement	21	21	100.0
branch	4	4	100.0
condition	6	6	100.0
subroutine	5	5	100.0
pod	1	1	100.0
total	37	37	100.0

package Mojolicious::Plugin::WithCSRFProtection;

# ABSTRACT: Mojolicious plugin providing CSRF protection at the routing level

use Mojo::Base 'Mojolicious::Plugin';

our $VERSION = '1.00';

#pod =head1 SYNOPSIS
#pod
#pod    # in a lite application
#pod    post '/some-url' => ( with_csrf_protection => 1 ) => sub { ... };
#pod
#pod    # in a full application
#pod    $app->routes->post('/some-url')
#pod                ->with_csrf_protection
#pod                ->to(...);
#pod
#pod =head1 DESCRIPTION
#pod
#pod This Mojolicious plugin provides a routing condition (called
#pod C) and routing shortcut to add that condition (also called
#pod C) that can be used to protect against cross site request
#pod forgery.
#pod
#pod Adding the condition to the route checks a valid CSRF token was passed, either
#pod in the C HTTP header or in the C parameter.
#pod
#pod Failing the CSRF check causes a 403 error and the C template to be
#pod rendered, or if no such template is found a simple error string to be
#pod output. This behavior is unlike most conditions that can be applied to
#pod Mojolicious routes that normally just cause the route matching to fail and
#pod alternative subsequent routes to be evaluated, but immediately returning an
#pod error response makes sense for a failed CSRF check.  The actual error rendering
#pod is performed by the C helper that this plugin installs, and if
#pod you want different error output you should override that helper.
#pod
#pod =cut

sub register {
    my ( $self, $app ) = @_;

    my $routes = $app->routes;

    $app->helper(
        'reply.bad_csrf' => sub {
            my ($c) = @_;
            $c->res->code(403);
            $c->render_maybe('bad_csrf')
                or $c->render( text => 'Failed CSRF check' );
            return;
        }
    );

    $routes->add_condition(
        with_csrf_protection => sub {
            my ( $route, $c ) = @_;

            my $csrf = $c->req->headers->header('X-CSRF-Token')
                || $c->param('csrf_token');

            unless ( $csrf && $csrf eq $c->csrf_token ) {
                $c->reply->bad_csrf;
                return;
            }

            return 1;
        }
    );

    $routes->add_shortcut(
        with_csrf_protection => sub {
            my ($route) = @_;
            return $route->over( with_csrf_protection => 1 );
        }
    );

    return;
}

1;

__END__