rack_csrf 2.3.0 → 2.4.0

data/Changelog.md

@@ -1,3 +1,16 @@
+# v2.4.0 (2012-02-28)
+
+* Updated examples' Gemfiles.
+* Dependency management is entrusted totally to Bundler.
+* Added support for CSRF validation via request headers (courtesy of
+  [jeffreyiacono](https://github.com/jeffreyiacono)).
+* Improved a bit documentation and testing code.
+* New option :skip_if (courtesy of
+  [jakubpawlowicz](https://github.com/jakubpawlowicz) and
+  [GoalSmashers](https://github.com/GoalSmashers)).
+
+
+
 # v2.3.0 (2011-10-23)
 
 * Updated examples' Gemfiles.

data/Gemfile

@@ -0,0 +1,12 @@
+source 'http://rubygems.org'
+
+gem 'rack', '>= 0.9'
+
+group :development do
+  gem 'bundler', '>= 1.0.0'
+  gem 'cucumber', '>= 1.1.1'
+  gem 'rack-test'
+  gem 'rspec', '>= 2.0.0'
+  gem 'rdoc', '>= 2.4.2'
+  gem 'jeweler'
+end

data/LICENSE.rdoc

@@ -2,7 +2,7 @@
 
 (The MIT License)
 
-Copyright (c) 2009, 2010, 2011 Emanuele Vicentini
+Copyright (c) 2009, 2010, 2011, 2012 Emanuele Vicentini
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the 'Software'), to deal

data/README.rdoc

@@ -18,6 +18,8 @@ session. If there's a token and it matches with the stored one, then the
 request is handed over to the next rack component; if not, Rack::Csrf
 immediately replies with an empty response.
 
+The anti-forging token can be passed as a request parameter or a header.
+
 I have not tested Rack::Csrf with Rack 0.4.0 or earlier versions, but it could
 possibly work.
 
@@ -62,6 +64,23 @@ The following options allow you to tweak Rack::Csrf.
 
   Default value: empty.
 
+[<tt>:skip_if</tt>]
+  Sets a lambda/Proc executed on every request to determine if that request
+  should be let pass untouched:
+
+    use Rack::Csrf, :skip_if => lambda { |request|
+      request.env.key?('HTTP_X_VERY_SPECIAL_HEADER')
+    }
+
+  Your code will receive a request object (see Rack's documentation for
+  details); if it returns anything but nil or false, no further checking is
+  performed and the request is let pass.
+
+  This option is useful if a guarded resource can be accessed by clients who
+  support CSRF token (e.g. browsers) and by ones who don't (e.g. API clients).
+
+  Default value: empty.
+
 [<tt>:field</tt>]
   Default field name (see below) is <tt>_csrf</tt>; you can adapt it to
   specific needs.
@@ -78,6 +97,34 @@ The following options allow you to tweak Rack::Csrf.
 
   Default value: csrf.token
 
+[<tt>:header</tt>]
+  Default header name (see below) is <tt>X_CSRF_TOKEN</tt>; you can adapt it
+  to specific needs.
+
+    use Rack::Csrf, :header => 'MY_CSRF_TOKEN_HEADER'
+
+  This is useful if we want to configure our application to send the CSRF
+  token in all of our AJAX requests via a header. We could implement something
+  along the lines of the following:
+
+    (function(jQuery) {
+      /*
+       * Set the CSRF token for each AJAX request, Rack::Csrf handle the rest.
+       * Assumes your layout has a metatag with name of "_csrf" and you're
+       * using the default Rack:Csrf header setup.
+       */
+      jQuery.ajaxSetup({
+        beforeSend: function(xhr) {
+          var token = jQuery('meta[name="_csrf"]').attr('content');
+          xhr.setRequestHeader('X_CSRF_TOKEN', token);
+        }
+      });
+    }(jQuery));
+
+  Default value: X_CSRF_TOKEN
+
+  Note that Rack will append "HTTP_" to this value.
+
 [<tt>:check_also</tt>]
   By passing an array of uppercase strings to this option you can add them to
   the list of HTTP methods which "mark" requests that must be searched for the
@@ -110,6 +157,9 @@ token.
 [<tt>Rack::Csrf.field</tt> (also <tt>Rack::Csrf.csrf_field</tt>)]
   Returns the name of the field that must be present in the request.
 
+[<tt>Rack::Csrf.header</tt> (also <tt>Rack::Csrf.csrf_header</tt>)]
+  Returns the name of the header that must be present in the request.
+
 [<tt>Rack::Csrf.token(env)</tt> (also <tt>Rack::Csrf.csrf_token(env)</tt>)]
   Given the request's environment, it generates a random token, stuffs it in
   the session and returns it to the caller or simply retrieves the already
@@ -120,6 +170,16 @@ token.
   insert the token in a standard form like an hidden input field with the
   right value already entered for you.
 
+[<tt>Rack::Csrf.metatag(env, options = {})</tt> (also <tt>Rack::Csrf.csrf_metatag(env, options = {})</tt>)]
+  Given the request's environment, it generates a small HTML fragment to
+  insert the token in a standard metatag within your layout's head with the
+  right value already entered for you.
+
+  <tt>options</tt> is an optional hash that can currently take a +name+
+  setting, which will alter the metatag's name attribute.
+
+  Default name: _csrf
+
 == Working examples
 
 In the +examples+ directory there are some small, working web applications
@@ -148,5 +208,5 @@ forgo responsibilities for keeping your application as safe as possible.
 
 == Copyright
 
-Copyright (c) 2009, 2010, 2011 Emanuele Vicentini. See LICENSE.rdoc for
+Copyright (c) 2009, 2010, 2011, 2012 Emanuele Vicentini. See LICENSE.rdoc for
 details.

data/Rakefile

@@ -1,3 +1,13 @@
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+
 require 'rake/clean'
 require 'cucumber/rake/task'
 require 'rspec/core/rake_task'
@@ -5,11 +15,9 @@ require 'rdoc/task'
 require 'jeweler'
 
 Cucumber::Rake::Task.new :features
-task :features => :check_dependencies
 task :default => :features
 
 RSpec::Core::RakeTask.new :spec
-task :spec => :check_dependencies
 task :default => :spec
 
 version = File.exists?('VERSION') ? File.read('VERSION').strip : ''
@@ -31,11 +39,7 @@ Jeweler::Tasks.new do |gem|
   gem.email = 'emanuele.vicentini@gmail.com'
   gem.homepage = 'https://github.com/baldowl/rack_csrf'
   gem.rubyforge_project = 'rackcsrf'
-  gem.add_dependency 'rack', '>= 0.9'
-  gem.add_development_dependency 'cucumber', '>= 0.1.13'
-  gem.add_development_dependency 'rack-test'
-  gem.add_development_dependency 'rspec', '>= 2.0.0'
-  gem.add_development_dependency 'rdoc', '>= 2.4.2'
+  # dependencies defined in Gemfile
   gem.rdoc_options << '--line-numbers' << '--inline-source' << '--title' <<
     "Rack::Csrf #{version}" << '--main' << 'README.rdoc'
   gem.test_files.clear

data/VERSION

@@ -1 +1 @@
-2.3.0
+2.4.0

data/examples/cuba/Gemfile

@@ -1,3 +1,3 @@
 source 'http://rubygems.org'
 
-gem 'cuba', '2.1.0'
+gem 'cuba', '>= 2.1.0', '<= 2.2.1'

data/examples/innate/Gemfile

@@ -1,3 +1,3 @@
 source 'http://rubygems.org'
 
-gem 'innate', '>= 2009.07', '<= 2011.04'
+gem 'innate', '>= 2009.07', '<= 2011.12'

data/examples/rack/Gemfile

@@ -1,3 +1,3 @@
 source 'http://rubygems.org'
 
-gem 'rack', '>= 1.0.0', '<= 1.3.5'
+gem 'rack', '>= 1.0.0', '<= 1.4.1'

data/examples/sinatra/Gemfile

@@ -1,3 +1,3 @@
 source 'http://rubygems.org'
 
-gem 'sinatra', '>= 0.9.4', '<= 1.3.1'
+gem 'sinatra', '>= 0.9.4', '<= 1.3.2'

data/features/check_only_some_specific_requests.feature

@@ -9,6 +9,10 @@ Feature: Check only some specific requests
     When it receives a POST request for /check/this without the CSRF token
     Then it responds with 403
 
+  Scenario: Blocking that specific request
+    When it receives a POST request for /check/this without the CSRF header
+    Then it responds with 403
+
   Scenario Outline: Not blocking other requests
     When it receives a <method> request for <path> without the CSRF token
     Then it lets it pass untouched
@@ -26,3 +30,21 @@ Feature: Check only some specific requests
       | PATCH  | /another/one |
       | DELETE | /another/one |
       | CUSTOM | /another/one |
+
+  Scenario Outline: Not blocking other requests
+    When it receives a <method> request for <path> without the CSRF header
+    Then it lets it pass untouched
+
+    Examples:
+      | method | path         |
+      | GET    | /check/this  |
+      | PUT    | /check/this  |
+      | PATCH  | /check/this  |
+      | DELETE | /check/this  |
+      | CUSTOM | /check/this  |
+      | GET    | /another/one |
+      | POST   | /another/one |
+      | PUT    | /another/one |
+      | PATCH  | /another/one |
+      | DELETE | /another/one |
+      | CUSTOM | /another/one |

data/features/custom_http_methods.feature

@@ -18,6 +18,19 @@ Feature: Handling custom HTTP methods
       | DELETE |
       | PATCH  |
 
+  Scenario Outline: Blocking "standard" requests without the header
+    When it receives a <method> request without the CSRF header
+    Then it responds with 403
+    And the response body is empty
+
+    Examples:
+      | method |
+      | POST   |
+      | PUT    |
+      | DELETE |
+      | PATCH  |
+
+
   Scenario Outline: Blocking "standard" requests with the wrong token
     When it receives a <method> request with the wrong CSRF token
     Then it responds with 403
@@ -30,6 +43,18 @@ Feature: Handling custom HTTP methods
       | DELETE |
       | PATCH  |
 
+  Scenario Outline: Blocking "standard" requests with the wrong header
+    When it receives a <method> request with the wrong CSRF header
+    Then it responds with 403
+    And the response body is empty
+
+    Examples:
+      | method |
+      | POST   |
+      | PUT    |
+      | DELETE |
+      | PATCH  |
+
   Scenario Outline: Blocking requests without the token
     When it receives a <method> request without the CSRF token
     Then it responds with 403
@@ -40,6 +65,16 @@ Feature: Handling custom HTTP methods
       | ME     |
       | YOU    |
 
+  Scenario Outline: Blocking requests without the header
+    When it receives a <method> request without the CSRF header
+    Then it responds with 403
+    And the response body is empty
+
+    Examples:
+      | method |
+      | ME     |
+      | YOU    |
+
   Scenario Outline: Blocking requests with the wrong token
     When it receives a <method> request with the wrong CSRF token
     Then it responds with 403
@@ -50,6 +85,17 @@ Feature: Handling custom HTTP methods
       | ME     |
       | YOU    |
 
+  Scenario Outline: Blocking requests with the wrong header
+    When it receives a <method> request with the wrong CSRF header
+    Then it responds with 403
+    And the response body is empty
+
+    Examples:
+      | method |
+      | ME     |
+      | YOU    |
+
+
   Scenario Outline: Letting pass "unknown" and safe requests without the token
     When it receives a <method> request without the CSRF token
     Then it lets it pass untouched

data/features/empty_responses.feature

@@ -7,14 +7,26 @@ Feature: Handling of the HTTP requests returning an empty response
     When it receives a GET request with the right CSRF token
     Then it lets it pass untouched
 
+  Scenario: GET request with the right CSRF header
+    When it receives a GET request with the right CSRF header
+    Then it lets it pass untouched
+
   Scenario: GET request with the wrong CSRF token
     When it receives a GET request with the wrong CSRF token
     Then it lets it pass untouched
 
+  Scenario: GET request with the wrong CSRF header
+    When it receives a GET request with the wrong CSRF header
+    Then it lets it pass untouched
+
   Scenario: GET request without CSRF token
     When it receives a GET request without the CSRF token
     Then it lets it pass untouched
 
+  Scenario: GET request without CSRF header
+    When it receives a GET request without the CSRF header
+    Then it lets it pass untouched
+
   Scenario Outline: Handling request without CSRF token
     When it receives a <method> request without the CSRF token
     Then it responds with 403
@@ -27,6 +39,18 @@ Feature: Handling of the HTTP requests returning an empty response
       | DELETE |
       | PATCH  |
 
+  Scenario Outline: Handling request without CSRF header
+    When it receives a <method> request without the CSRF header
+    Then it responds with 403
+    And the response body is empty
+
+    Examples:
+      | method |
+      | POST   |
+      | PUT    |
+      | DELETE |
+      | PATCH  |
+
   Scenario Outline: Handling request with the right CSRF token
     When it receives a <method> request with the right CSRF token
     Then it lets it pass untouched
@@ -38,6 +62,17 @@ Feature: Handling of the HTTP requests returning an empty response
       | DELETE |
       | PATCH  |
 
+  Scenario Outline: Handling request with the right CSRF header
+    When it receives a <method> request with the right CSRF header
+    Then it lets it pass untouched
+
+    Examples:
+      | method |
+      | POST   |
+      | PUT    |
+      | DELETE |
+      | PATCH  |
+
   Scenario Outline: Handling request with the wrong CSRF token
     When it receives a <method> request with the wrong CSRF token
     Then it responds with 403
@@ -49,3 +84,15 @@ Feature: Handling of the HTTP requests returning an empty response
       | PUT    |
       | DELETE |
       | PATCH  |
+
+  Scenario Outline: Handling request with the wrong CSRF header
+    When it receives a <method> request with the wrong CSRF token
+    Then it responds with 403
+    And the response body is empty
+
+    Examples:
+      | method |
+      | POST   |
+      | PUT    |
+      | DELETE |
+      | PATCH  |

data/features/inspecting_also_get_requests.feature

@@ -18,3 +18,17 @@ Feature: Inspecting also GET requests
     When it receives a GET request without the CSRF token
     Then it responds with 403
     And the response body is empty
+
+  Scenario: GET request with the right CSRF header
+    When it receives a GET request with the right CSRF header
+    Then it lets it pass untouched
+
+  Scenario: GET request with the wrong CSRF header
+    When it receives a GET request with the wrong CSRF header
+    Then it responds with 403
+    And the response body is empty
+
+  Scenario: GET request without the CSRF header
+    When it receives a GET request without the CSRF header
+    Then it responds with 403
+    And the response body is empty

data/features/raising_exception.feature

@@ -7,6 +7,10 @@ Feature: Handling of the HTTP requests raising an exception
     When it receives a GET request without the CSRF token
     Then it lets it pass untouched
 
+  Scenario: GET request without CSRF header
+    When it receives a GET request without the CSRF header
+    Then it lets it pass untouched
+
   Scenario Outline: Handling request without CSRF token
     When it receives a <method> request without the CSRF token
     Then there is no response
@@ -30,6 +34,17 @@ Feature: Handling of the HTTP requests raising an exception
       | DELETE |
       | PATCH  |
 
+  Scenario Outline: Handling request with the right CSRF header
+    When it receives a <method> request with the right CSRF header
+    Then it lets it pass untouched
+
+    Examples:
+      | method |
+      | POST   |
+      | PUT    |
+      | DELETE |
+      | PATCH  |
+
   Scenario Outline: Handling request with the wrong CSRF token
     When it receives a <method> request with the wrong CSRF token
     Then there is no response
@@ -41,3 +56,15 @@ Feature: Handling of the HTTP requests raising an exception
       | PUT    |
       | DELETE |
       | PATCH  |
+
+  Scenario Outline: Handling request with the wrong CSRF header
+    When it receives a <method> request with the wrong CSRF header
+    Then there is no response
+    And an exception is climbing up the stack
+
+    Examples:
+      | method |
+      | POST   |
+      | PUT    |
+      | DELETE |
+      | PATCH  |