safe_cookies 0.2.0 → 0.2.1

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    YjY2ZmQ0ZDEzMWVhMDRmNWE0MmM2ODRjYTU5MzEyZmQxN2JkMGQzMg==
+    YWE0YmVmNWE0NjE3N2ZiYWUzNDM2ODYwMDFhNGNkYTE1Yzc2ZjllYQ==
   data.tar.gz: !binary |-
-    N2E2Yzg5OGQzMzkyYWI3N2E1MWJlZWJmZjI1NGM0ZjY2MjkzNDVkZQ==
+    NDliMDkwMDFjOTMxZDVhNmU4NjgyZDgxZTQ1OWQ1N2E4NjFhNmZmYw==
 SHA512:
   metadata.gz: !binary |-
-    MzU1ZTQyYjQzNmNhNzljNzA2Y2U2NWIyMDU5MTkyMTU5MDZjYmQ0ZDY4MjNl
-    M2MxMWJhYmQwMzJkZDdlYzJlZTkwYWFkNWJkNzE4ZTc5MTUxOWI0YjMwNmVk
-    NGM0YzUyZWU3MjJjMGZlMzgzYjk2OTg4OWU1MzY5ZGQzYjE0NzE=
+    YzYxNGU4MmIyNjg1MDhjNzM0ZjRmNWMxZGYwNmM4MDUxYmMwNDE0ZDRiYmQx
+    YmY0NTdiOGUxODQ4NWFiOTUzOTUyMjM0MTU2ZWUyOGQ3OGUxYjZhMDYzZGFk
+    ZDc5NTcwYjg2Zjc5MWM0MzgwMGE3YTA2NGMyZmQxYmIyOTg5NGY=
   data.tar.gz: !binary |-
-    OTMzYTYzN2JkMzk3OGU5NzE4MzAwMWUxYWVmMmI1ZThmYTExNmQyNzgyYWU4
-    YjFiYzIyOTg4YTk0Njg3YTk0NzRiMjAyMzc1NmM0OWVhYjRhNWI3NDdlZjZm
-    NTMxYTkwNmJlYTJlMjBkY2NhMGYzM2MwYzRkYzcwMTViMTlmMzc=
+    NWI3YmNhNzE2ODI1YzQ2ZGQ0NTk3NTAxODg5MTFhMWI0MDIxYWJmODNlZTU2
+    ZjVjZDRkYjE1YmNlNTU4YTIwYTYxNTMyNDFjMWQ2MGFiOTU3ZGNkNTlmZmZi
+    ZTdlOTI1M2ZhNTE1NDQzZTRiNTIzMjc2NTYxYzk3MGQ1Zjk5N2Q=

data/README.md

@@ -1,84 +1,79 @@
 # SafeCookies
 
-This Gem has a middleware that will make all cookies secure. In detail, it will:
+This gem has a middleware that will make all cookies secure. In detail, it will
+to two separate things:
 
-* set all new application cookies 'HttpOnly', unless specified otherwise
-* set all new application cookies 'secure', if the request came via HTTPS and not specified otherwise
-* rewrite request cookies, setting both flags as above
+1) set all new application cookies 'HttpOnly', unless specified otherwise;  
+   set all new application cookies 'secure', if the request came via HTTPS and not specified otherwise
+
+2) rewrite request cookies, setting both flags as above
 
 ## Installation
 
 ### Step 1
-Add this line to your application's Gemfile:
-
-    gem 'safe_cookies'
-
-Then run `bundle install`.
+Add `gem 'safe_cookies'` to your application's Gemfile, then run `bundle install`.
 
-Though this gem is aimed at Rails applications, you may even use it without
-Rails. In that case, install it with `gem install safe_cookies`.
+### Step 2
+**Rails 3 and 4**: add the following lines to the application block in config/application.rb:
 
+    require 'safe_cookies'
+    config.middleware.insert_before ActionDispatch::Cookies, SafeCookies::Middleware
 
-### Step 2
-**Rails 3 and 4**: add the following line in config/application.rb:
+**Rails 2:** add the following lines to the initializer block in config/environment.rb:
 
-    class Application < Rails::Application
-      # ...
-      config.middleware.insert_before ActionDispatch::Cookies, SafeCookies::Middleware
-    end
+    require 'safe_cookies'
+    config.middleware.insert_before ActionController::Session::CookieStore, SafeCookies::Middleware
 
-**Rails 2:** add the following lines in config/environment.rb:
 
-    Rails::Initializer.run do |config|
-      # ...
-      require 'safe_cookies'
-      config.middleware.insert_before ActionController::Session::CookieStore, SafeCookies::Middleware
-    end
+Now all your cookies will be made `secure` and `HttpOnly`. But what if you need
+a cookie to be accessible via HTTP or Javascript?
 
-### Step 3
-Register cookies, either just after the lines you added above or in in an initializer
-(e.g. in `config/initializers/safe_cookies.rb`):
+### Having a cookie non-secure or non-HttpOnly
+Tell the middleware which cookies not to make `secure` or `HttpOnly` by
+registering them. Do it either just after the lines you added above or in an
+initializer (e.g. in `config/initializers/safe_cookies.rb`). The `:expire_after` option is required.
 
     SafeCookies.configure do |config|
-      config.register_cookie :remember_token, :expire_after => 1.year
-      config.register_cookie :last_action, :expire_after => 30.days
       config.register_cookie :default_language, :expire_after => 10.years, :secure => false
       config.register_cookie :javascript_data, :expire_after => 1.day, :http_only => false
     end
 
-If a request has any of those four cookies, the middleware will set them anew. The `remember_token` and
-`last_action` cookies will be made `secure` and `HttpOnly`.
-Since we want to access the default language even if the user comes via HTTP,  the `default_language`
-cookie is not made secure. Analogous, the `javascript_data` cookie will be used by a script and hence is
-not made `HttpOnly`.
+### Employing SafeCookies in apps that are already running in production
+Unfortunately, [the client won't ever tell us](http://tools.ietf.org/html/rfc6265#section-4.2.2)
+if it stores the cookie with flags such as `secure` or which expiry date it
+currently has. Therefore, in order to make the middleware retroactively secure
+cookies owned by the client, you need to register each of those cookies with
+the middleware, specifying their properties.
+
+Carefully scan your app for cookies you are using. There's no easy way to find
+out if you missed one (but see below for some help the gem provides).
 
-Available options are: `:expire_after (required), :path, :secure, :http_only`.
+    SafeCookies.configure do |config|
+      config.register_cookie :remember_token, :expire_after => 1.year
+      config.register_cookie :last_action, :expire_after => 30.days, :path => '/commerce'
+    end
 
-### Step 4 (important for Rails 2 only)
-Override `SafeCookies::Middleware#handle_unknown_cookies(cookies)` to notify you
-e.g. by email (see "Dealing with unregistered cookies" below).
+Available options are: `:expire_after` (required)`, :path, :secure, :http_only`.
 
 
-## Dealing with unregistered cookies
+## Dealing with unknown cookies
 
-The middleware is not able to secure cookies without knowing their attributes
-(most importantly: their expiry). Unfortunately, [the client won't ever tell us](http://tools.ietf.org/html/rfc6265#section-4.2.2)
-if it stores the cookie with flags such as "secure" or which expiry date it
-currently has. Therefore, it is important to register all cookies that may be
-sent by the client, specifying their properties. Unregistered cookies cannot be
-secured by the middleware.
+There are lots of cookies your application receives that you never did set.
+However, if you want to know about any unknown cookies touching your
+application, SafeCookies offers two ways to achieve this.
 
-Unknown cookies are written to the Rails log. When you start implementing the
-middleware, you should closely watch it to find cookies you forgot to register.
-You may overwrite `SafeCookies::Middleware#handle_unknown_cookies(cookies)` in
-the config initializer for customized behaviour (like, notifying you per email).
+1) If you set `config.log_unknown_cookies = true` in the configuration, all
+unknown cookies will be written to the Rails log. When you start implementing
+the middleware, closely watch it to find cookies you forgot to register.
 
-You should register any cookie that your application is using.
+2) You may overwrite `SafeCookies::Middleware#handle_unknown_cookies(cookies)`
+in the config initializer for customized behaviour (like, notifying you per
+email).
 
 
 ## Ignoring cookies
 
-Currently, ignoring cookies only prevents the middleware from writing them to the logs.
+The middleware won't see request cookies that are configured to be ignored. Use this to keep your logs lean, if you are using the `log_unknown_cookies` option.
 
 You can tell the middleware to ignore cookies with the `config.ignore_cookie`
 directive, which takes either a String or a Regex parameter. Be careful when using regular expressions!
@@ -93,7 +88,7 @@ Users would get multiple cookies for that domain, leading to issues like being u
 The configuration option `config.fix_paths` turns on fixing this error. It requires an option
 `:for_cookies_secured_before => Time.parse('some minutes after you will have deployed')` which reflects the
 point of time from which cookies will be secured with the correct path. The middleware will fix the cookie
-paths by rewriting all cookies that it has already secured, but only if the were secured before the time
+paths by rewriting all cookies that it has already secured, but only if they were secured before the time
 you specified.
 
 

data/lib/safe_cookies.rb

@@ -64,6 +64,9 @@ module SafeCookies
       unknown_cookie_names = request_cookie_names - known_cookie_names
       
       if unknown_cookie_names.any?
+        message = "Request for '#{@request.url}' had unknown cookies: #{unknown_cookie_names.join(', ')}"
+        log(message) if @config.log_unknown_cookies
+
         handle_unknown_cookies(unknown_cookie_names)
       end
     end
@@ -128,11 +131,10 @@ module SafeCookies
     
     # API method
     def handle_unknown_cookies(cookie_names)
-      log_error("Request for '#{@request.url}' had unknown cookies: #{cookie_names.join(', ')}")
     end
     
-    def log_error(error_message)
-      message = '** [SafeCookies error] '
+    def log(error_message)
+      message = '** [SafeCookies] '
       message << error_message
       
       Rails.logger.error(message) if defined?(Rails)

data/lib/safe_cookies/configuration.rb

@@ -13,7 +13,9 @@ module SafeCookies
   end
 
   class Configuration
-    attr_reader :registered_cookies, :fix_cookie_paths, :correct_cookie_paths_timestamp, :ignored_cookies
+    attr_accessor :log_unknown_cookies
+    attr_reader :registered_cookies, :fix_cookie_paths, :correct_cookie_paths_timestamp,
+      :ignored_cookies
 
     def initialize
       self.registered_cookies = {}
@@ -72,7 +74,8 @@ module SafeCookies
     private
     
     attr_accessor :insecure_cookies, :scriptable_cookies
-    attr_writer :registered_cookies, :fix_cookie_paths, :correct_cookie_paths_timestamp, :ignored_cookies
+    attr_writer :registered_cookies, :fix_cookie_paths, :correct_cookie_paths_timestamp,
+      :ignored_cookies
 
   end
 

data/lib/safe_cookies/version.rb

@@ -1,3 +1,3 @@
 module SafeCookies
-  VERSION = '0.2.0'
+  VERSION = '0.2.1'
 end

data/spec/safe_cookies_spec.rb

@@ -214,69 +214,79 @@ describe SafeCookies::Middleware do
   # importance in the future.
   context 'when a request has unknown cookies,' do
     
-    it 'logs an error message' do
+    it 'allows overwriting the handling mechanism' do
       stub_app_call(app)
       set_request_cookies(env, 'foo=bar')
       
-      subject.should_receive(:log_error).with(/unknown cookies: foo/)
+      def subject.handle_unknown_cookies(*args)
+        @custom_method_called = true
+      end
+      
       subject.call(env)
+      subject.instance_variable_get('@custom_method_called').should == true
     end
     
-    it 'does not log an error if the (unregistered) cookie was initially set by the application' do
-      # application sets cookie
-      stub_app_call(app, :application_cookies => 'foo=bar; path=/some/path; secure')
+    context 'and it is configured to log unknown cookies' do
+    
+      before do
+        SafeCookies.configure do |config|
+          config.log_unknown_cookies = true
+        end
+      end
+    
+      it 'logs an error message' do
+        stub_app_call(app)
+        set_request_cookies(env, 'foo=bar')
       
-      code, headers, response = subject.call(env)
+        subject.should_receive(:log).with(/unknown cookies: foo/)
+        subject.call(env)
+      end
+    
+      it 'does not log an error if the (unregistered) cookie was initially set by the application' do
+        # application sets cookie
+        stub_app_call(app, :application_cookies => 'foo=bar; path=/some/path; secure')
+      
+        code, headers, response = subject.call(env)
 
-      received_cookies = extract_cookies(headers['Set-Cookie'])
-      received_cookies.should include('foo=bar') # sanity check
+        received_cookies = extract_cookies(headers['Set-Cookie'])
+        received_cookies.should include('foo=bar') # sanity check
       
-      # client returns with the cookie, `app` and `subject` are different
-      # objects than in the previous request
-      other_app = stub('application')
-      other_subject = described_class.new(other_app)
+        # client returns with the cookie, `app` and `subject` are different
+        # objects than in the previous request
+        other_app = stub('application')
+        other_subject = described_class.new(other_app)
       
-      stub_app_call(other_app)
-      set_request_cookies(env, *received_cookies)
+        stub_app_call(other_app)
+        set_request_cookies(env, *received_cookies)
 
-      other_subject.should_not_receive(:log_error)
-      other_subject.call(env)
-    end
-    
-    it 'does not log an error if the cookie is listed in the cookie configuration' do
-      SafeCookies.configure do |config|
-        config.register_cookie('foo', :expire_after => 3600)
+        other_subject.should_not_receive(:log)
+        other_subject.call(env)
       end
     
-      stub_app_call(app)
-      set_request_cookies(env, 'foo=bar')
-      
-      subject.should_not_receive(:log_error)
-      subject.call(env)
-    end
+      it 'does not log an error if the cookie is listed in the cookie configuration' do
+        SafeCookies.configure do |config|
+          config.register_cookie('foo', :expire_after => 3600)
+        end
     
-    it 'does not log an error if the cookie is ignored' do
-      SafeCookies.configure do |config|
-        config.ignore_cookie '__utma'
-      end
-
-      stub_app_call(app)
-      set_request_cookies(env, '__utma=tracking')
+        stub_app_call(app)
+        set_request_cookies(env, 'foo=bar')
       
-      subject.should_not_receive(:log_error)
-      subject.call(env)
-    end
+        subject.should_not_receive(:log)
+        subject.call(env)
+      end
     
-    it 'allows overwriting the handling mechanism' do
-      stub_app_call(app)
-      set_request_cookies(env, 'foo=bar')
+      it 'does not log an error if the cookie is ignored' do
+        SafeCookies.configure do |config|
+          config.ignore_cookie '__utma'
+        end
+
+        stub_app_call(app)
+        set_request_cookies(env, '__utma=tracking')
       
-      def subject.handle_unknown_cookies(*args)
-        @custom_method_called = true
+        subject.should_not_receive(:log)
+        subject.call(env)
       end
-      
-      subject.call(env)
-      subject.instance_variable_get('@custom_method_called').should == true
+    
     end
     
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: safe_cookies
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Dominik Schöler
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-11-11 00:00:00.000000000 Z
+date: 2013-11-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -109,7 +109,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.1.3
+rubygems_version: 2.1.2
 signing_key: 
 specification_version: 4
 summary: Make all cookies `secure` and `HttpOnly`.