=head1 NAME

Mojolicious::Plugin::CSRFProtect - fully protects you from CSRF attacks

=head1 SYNOPSIS

  # Mojolicious
  $self->plugin('CSRFProtect');

  # Mojolicious::Lite
  plugin 'CSRFProtect';
  
  # Use "form_for" helper and all your html forms will have CSRF protection token 

    <%= form_for login => (method => 'post') => begin %>
           <%= text_field 'first_name' %>
           <%= submit_button %>
    <% end %>
    
  # Place jquery_ajax_csrf_protection helper to your layout template 
  # and all AJAX requests will have CSRF protection token (requires JQuery)
   
    <%= jquery_ajax_csrf_protection %>


=head1 DESCRIPTION

L<Mojolicious::Plugin::CSRFProtect> is a L<Mojolicious> plugin which fully protects you from CSRF attacks.

It does next things:

1. Adds a hidden input (with name 'csrftoken') with CSRF protection token to every form 
(works only if you use C<form_for> helper from Mojolicious::Plugin::TagHelpers.) 

2. Adds the header "X-CSRF-Token" with CSRF token to every AJAX request (works with JQuery only)   

3. Rejects all non GET requests without the correct CSRF protection token.
 

If you want protect your GET requests then you can do it manually

In template: <a href="/delete_user/123/?csrftoken=<%= csrftoken %>">

In controller: $self->is_valid_csrftoken() 

=head1 HELPERS

=head2 C<form_for>

    This helper overrides the C<form_for> helper from Mojolicious::Plugin::TagHelpers 
    
    and adds hidden input with CSRF protection token.

=head2 C<jquery_ajax_csrf_protection>

    This helper adds CSRF protection headers to all JQuery AJAX requests.
    
    You should add <%= jquery_ajax_csrf_protection %> in head of your HTML page. 

=head2 C<csrftoken>

    returns  CSRF Protection token. 
    
    In templates <%= csrftoken %>
    
    In controller $self->csrftoken;
    
=head2 C<is_valid_csrftoken>

    With this helper you can check $csrftoken manually. It will take $csrftoken from $c->param('csrftoken');
     
    $self->is_valid_csrftoken() will return 1 or 0

=head1 SEE ALSO

=over 4

=item L<Mojolicious::Plugin::CSRFDefender>  

This plugin followes the same aproach but it works in different manner. 

It will parse your response body searching for '<form>' tag and then will insert CSRF token there.

=back

=head1 LICENSE AND COPYRIGHT

Copyright 2011 Viktor Turskyi

This program is free software; you can redistribute it and/or modify it
under the terms of either: the GNU General Public License as published
by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

=cut
