sorcery 0.5.21 → 0.5.30

data/README.rdoc

@@ -29,7 +29,7 @@ Example Rails 3 app using sorcery: https://github.com/NoamB/sorcery-example-app
 
 Example Sinatra app using sorcery: https://github.com/NoamB/sorcery-example-app-sinatra
 
-Documentation: http://rubydoc.info/gems/sorcery/0.5.21/frames
+Documentation: http://rubydoc.info/gems/sorcery/0.5.30/frames
 
 Check out the tutorials in the github wiki!
 

data/VERSION

@@ -1 +1 @@
-0.5.21
+0.5.30

data/lib/sorcery/controller.rb

@@ -62,7 +62,8 @@ module Sorcery
         @current_user ||= login_from_session || login_from_other_sources unless @current_user == false
       end
       
-      # used when a user tries to access a page while logged out, is asked to login, and we want to return him back to the page he originally wanted.
+      # used when a user tries to access a page while logged out, is asked to login, 
+      # and we want to return him back to the page he originally wanted.
       def redirect_back_or_to(url, flash_hash = {})
         redirect_to(session[:return_to_url] || url, :flash => flash_hash)
       end
@@ -115,11 +116,12 @@ module Sorcery
       class << self
         attr_accessor :submodules,
         
-                      :user_class,                    # what class to use as the user class. Set automatically when you call authenticates_with_sorcery! in the User class.
+                      :user_class,                    # what class to use as the user class. 
                       
                       :not_authenticated_action,      # what controller action to call for non-authenticated users.
                       
-                      :save_return_to_url,            # when a non logged in user tries to enter a page that requires login, save the URL he wanted to reach, 
+                      :save_return_to_url,            # when a non logged in user tries to enter a page that requires
+                                                      # login, save the URL he wanted to reach, 
                                                       # and send him there after login.
                       
                       :login_sources,

data/lib/sorcery/controller/submodules/activity_logging.rb

@@ -1,13 +1,16 @@
 module Sorcery
   module Controller
     module Submodules
-      # This submodule keeps track of events such as login, logout, and last activity time, per user.
+      # This submodule keeps track of events such as login, logout, 
+      # and last activity time, per user.
       # It helps in estimating which users are active now in the site.
-      # This cannot be determined absolutely because a user might be reading a page without clicking anything for a while.
-      
-      # This is the controller part of the submodule, which adds hooks to register user events, 
+      # This cannot be determined absolutely because a user might be 
+      # reading a page without clicking anything for a while.
+      # This is the controller part of the submodule, which adds hooks 
+      # to register user events, 
       # and methods to collect active users data for use in the app.
-      # see Socery::Model::Submodules::ActivityLogging for configuration options.
+      # see Socery::Model::Submodules::ActivityLogging for configuration
+      # options.
       module ActivityLogging
         def self.included(base)
           base.send(:include, InstanceMethods)
@@ -21,7 +24,8 @@ module Sorcery
           def current_users
             Config.user_class.current_users
             # A possible patch here:
-            # we'll add the current_user to the users list if he's not in it (can happen when he was inactive for more than activity timeout):
+            # we'll add the current_user to the users list if he's not in it
+            # (can happen when he was inactive for more than activity timeout):
             #
             #   users.unshift!(current_user) if logged_in? && users.find {|u| u.id == current_user.id}.nil?
             #

data/lib/sorcery/controller/submodules/brute_force_protection.rb

@@ -1,9 +1,12 @@
 module Sorcery
   module Controller
     module Submodules
-      # This module helps protect user accounts by locking them down after too many failed attemps to login were detected.
-      # This is the controller part of the submodule which takes care of updating the failed logins and resetting them.
-      # See Sorcery::Model::Submodules::BruteForceProtection for configuration options.
+      # This module helps protect user accounts by locking them down after too
+      # many failed attemps to login were detected.
+      # This is the controller part of the submodule which takes care of
+      # updating the failed logins and resetting them.
+      # See Sorcery::Model::Submodules::BruteForceProtection for configuration
+      # options.
       module BruteForceProtection
         def self.included(base)
           base.send(:include, InstanceMethods)

data/lib/sorcery/controller/submodules/http_basic_auth.rb

@@ -2,8 +2,10 @@ module Sorcery
   module Controller
     module Submodules
       # This submodule integrates HTTP Basic authentication into sorcery.
-      # You are provided with a before filter, require_login_from_http_basic, which requests the browser for authentication.
-      # Then the rest of the submodule takes care of logging the user in into the session, so that the next requests will keep him logged in.
+      # You are provided with a before filter, require_login_from_http_basic, 
+      # which requests the browser for authentication.
+      # Then the rest of the submodule takes care of logging the user in 
+      # into the session, so that the next requests will keep him logged in.
       module HttpBasicAuth
         def self.included(base)
           base.send(:include, InstanceMethods)
@@ -28,9 +30,12 @@ module Sorcery
           # The method sets a session when requesting the user's credentials.
           # This is a trick to overcome the way HTTP authentication works (explained below):
           #
-          # Once the user fills the credentials once, the browser will always send it to the server when visiting the website, until the browser is closed.
-          # This causes wierd behaviour if the user logs out. The session is reset, yet the user is re-logged in by the before_filter calling 'login_from_basic_auth'.
-          # To overcome this, we set a session when requesting the password, which logout will reset, and that's how we know if we need to request for HTTP auth again.
+          # Once the user fills the credentials once, the browser will always send it to the 
+          # server when visiting the website, until the browser is closed.
+          # This causes wierd behaviour if the user logs out. The session is reset, yet the 
+          # user is re-logged in by the before_filter calling 'login_from_basic_auth'.
+          # To overcome this, we set a session when requesting the password, which logout will
+          # reset, and that's how we know if we need to request for HTTP auth again.
           def require_login_from_http_basic
             (request_http_basic_authentication(realm_name_by_controller) and (session[:http_authentication_used] = true) and return) if (request.authorization.nil? || session[:http_authentication_used].nil?)
             require_login

data/lib/sorcery/controller/submodules/remember_me.rb

@@ -1,7 +1,8 @@
 module Sorcery
   module Controller
     module Submodules
-      # The Remember Me submodule takes care of setting the user's cookie so that he will be automatically logged in to the site on every visit,
+      # The Remember Me submodule takes care of setting the user's cookie so that he will 
+      # be automatically logged in to the site on every visit,
       # until the cookie expires.
       # See Sorcery::Model::Submodules::RememberMe for configuration options.
       module RememberMe
@@ -16,7 +17,7 @@ module Sorcery
           # This method sets the cookie and calls the user to save the token and the expiration to db.
           def remember_me!
             current_user.remember_me!
-            cookies[:remember_me_token] = { :value => current_user.remember_me_token, :expires => current_user.remember_me_token_expires_at }        
+            set_remember_me_cookie!(current_user)      
           end
 
           # Clears the cookie and clears the token from the db.
@@ -33,17 +34,25 @@ module Sorcery
             remember_me! if credentials.size == 3 && credentials[2]
           end
           
-          # Checks the cookie for a remember me token, tried to find a user with that token and logs the user in if found.
+          # Checks the cookie for a remember me token, tried to find a user with that token 
+          # and logs the user in if found.
           # Runs as a login source. See 'current_user' method for how it is used.
           def login_from_cookie
             user = cookies[:remember_me_token] && Config.user_class.find_by_remember_me_token(cookies[:remember_me_token])
             if user && user.remember_me_token?
-              cookies[:remember_me_token] = { :value => user.remember_me_token, :expires => user.remember_me_token_expires_at }
+              set_remember_me_cookie!(user)
               @current_user = user
             else
               @current_user = false
             end
           end
+          
+          def set_remember_me_cookie!(user)
+            cookies[:remember_me_token] = { 
+              :value => user.send(user.sorcery_config.remember_me_token_attribute_name), 
+              :expires => user.send(user.sorcery_config.remember_me_token_expires_at_attribute_name)
+            }
+          end
         end
 
       end

data/lib/sorcery/controller/submodules/session_timeout.rb

@@ -9,7 +9,9 @@ module Sorcery
           Config.module_eval do
             class << self
               attr_accessor :session_timeout,                     # how long in seconds to keep the session alive.
-                            :session_timeout_from_last_action     # use the last action as the beginning of session timeout.
+              
+                            :session_timeout_from_last_action     # use the last action as the beginning of session
+                                                                  # timeout.
                             
               def merge_session_timeout_defaults!
                 @defaults.merge!(:@session_timeout                      => 3600, # 1.hour

data/lib/sorcery/crypto_providers/aes256.rb

@@ -2,18 +2,21 @@ require "openssl"
 
 module Sorcery
   module CryptoProviders
-    # This encryption method is reversible if you have the supplied key. So in order to use this encryption method you must supply it with a key first.
+    # This encryption method is reversible if you have the supplied key. 
+    # So in order to use this encryption method you must supply it with a key first.
     # In an initializer, or before your application initializes, you should do the following:
     #
     #   Sorcery::Model::ConfigAES256.key = "my 32 bytes long key"
     #
-    # My final comment is that this is a strong encryption method, but its main weakness is that its reversible. If you do not need to reverse the hash
+    # My final comment is that this is a strong encryption method, 
+    # but its main weakness is that its reversible. If you do not need to reverse the hash
     # then you should consider Sha512 or BCrypt instead.
     #
     # Keep your key in a safe place, some even say the key should be stored on a separate server.
-    # This won't hurt performance because the only time it will try and access the key on the separate server is during initialization, which only
-    # happens once. The reasoning behind this is if someone does compromise your server they won't have the key also. Basically, you don't want to
-    # store the key with the lock.
+    # This won't hurt performance because the only time it will try and access the key on the 
+    # separate server is during initialization, which only
+    # happens once. The reasoning behind this is if someone does compromise your server they 
+    # won't have the key also. Basically, you don't want to store the key with the lock.
     class AES256
       class << self
         attr_writer :key

data/lib/sorcery/crypto_providers/bcrypt.rb

@@ -2,9 +2,12 @@ require 'bcrypt'
 
 module Sorcery
   module CryptoProviders
-    # For most apps Sha512 is plenty secure, but if you are building an app that stores nuclear launch codes you might want to consier BCrypt. This is an extremely
-    # secure hashing algorithm, mainly because it is slow. A brute force attack on a BCrypt encrypted password would take much longer than a brute force attack on a
-    # password encrypted with a Sha algorithm. Keep in mind you are sacrificing performance by using this, generating a password takes exponentially longer than any
+    # For most apps Sha512 is plenty secure, but if you are building an app that stores nuclear 
+    # launch codes you might want to consier BCrypt. This is an extremely
+    # secure hashing algorithm, mainly because it is slow. 
+    # A brute force attack on a BCrypt encrypted password would take much longer than a brute force attack on a
+    # password encrypted with a Sha algorithm. Keep in mind you are sacrificing performance by using this,
+    # generating a password takes exponentially longer than any
     # of the Sha algorithms. I did some benchmarking to save you some time with your decision:
     #
     #   require "bcrypt"
@@ -37,8 +40,10 @@ module Sorcery
     # You are good to go!
     class BCrypt
       class << self
-        # This is the :cost option for the BCrpyt library. The higher the cost the more secure it is and the longer is take the generate a hash. By default this is 10.
-        # Set this to whatever you want, play around with it to get that perfect balance between security and performance.
+        # This is the :cost option for the BCrpyt library. 
+        # The higher the cost the more secure it is and the longer is take the generate a hash. By default this is 10.
+        # Set this to whatever you want, play around with it to get that perfect balance between 
+        # security and performance.
         def cost
           @cost ||= 10
         end
@@ -57,7 +62,8 @@ module Sorcery
           hash == join_tokens(tokens)
         end
         
-        # This method is used as a flag to tell Sorcery to "resave" the password upon a successful login, using the new cost
+        # This method is used as a flag to tell Sorcery to "resave" the password 
+        # upon a successful login, using the new cost
         def cost_matches?(hash)
           hash = new_from_hash(hash)
           if hash.nil? || hash == {}

data/lib/sorcery/crypto_providers/sha256.rb

@@ -1,7 +1,8 @@
 require "digest/sha2"
 
 module Sorcery
-  # The activate_sorcery method has a custom_crypto_provider configuration option. This allows you to use any type of encryption you like.
+  # The activate_sorcery method has a custom_crypto_provider configuration option. 
+  # This allows you to use any type of encryption you like.
   # Just create a class with a class level encrypt and matches? method. See example below.
   #
   # === Example

data/lib/sorcery/crypto_providers/sha512.rb

@@ -1,7 +1,8 @@
 require "digest/sha2"
 
 module Sorcery
-  # The activate_sorcery method has a custom_crypto_provider configuration option. This allows you to use any type of encryption you like.
+  # The activate_sorcery method has a custom_crypto_provider configuration option. 
+  # This allows you to use any type of encryption you like.
   # Just create a class with a class level encrypt and matches? method. See example below.
   #
   # === Example

data/lib/sorcery/initializers/initializer.rb

@@ -1,25 +1,35 @@
 # The first thing you need to configure is which modules you need in your app.
 # The default is nothing which will include only core features (password encryption, login/logout).
-# Available submodules are: :user_activation, :http_basic_auth, :remember_me, :reset_password, :session_timeout, :brute_force_protection, :activity_logging, :external
+# Available submodules are: :user_activation, :http_basic_auth, :remember_me, 
+# :reset_password, :session_timeout, :brute_force_protection, :activity_logging, :external
 Rails.application.config.sorcery.submodules = []
 
 # Here you can configure each submodule's features.
 Rails.application.config.sorcery.configure do |config|
   # -- core --
-  # config.not_authenticated_action = :not_authenticated              # what controller action to call for non-authenticated users. You can also override 'not_authenticated' instead.
-  # config.save_return_to_url = true                                  # when a non logged in user tries to enter a page that requires login, save the URL he wanted to reach, 
-                                                                      # and send him there after login, using 'redirect_back_or_to'.
+  # config.not_authenticated_action = :not_authenticated              # what controller action to call for
+                                                                      # non-authenticated users. 
+                                                                      # You can also override 'not_authenticated' 
+                                                                      # instead.
+                                                                      
+  # config.save_return_to_url = true                                  # when a non logged in user tries to enter 
+                                                                      # a page that requires login, 
+                                                                      # save the URL he wanted to reach, 
+                                                                      # and send him there after login, using
+                                                                      # 'redirect_back_or_to'.
 
   # -- session timeout --                                             
   # config.session_timeout = 3600                                     # how long in seconds to keep the session alive.
-  # config.session_timeout_from_last_action = false                   # use the last action as the beginning of session timeout.
+  # config.session_timeout_from_last_action = false                   # use the last action as the beginning of 
+                                                                      # session timeout.
   
   # -- http_basic_auth --
   # config.controller_to_realm_map = {"application" => "Application"} # What realm to display for which controller name.
                                                                       # For example {"My App" => "Application"}
   
   # -- external --
-  # config.external_providers = []                                    # What providers are supported by this app, i.e. [:twitter, :facebook] .
+  # config.external_providers = []                                    # What providers are supported by this app, 
+                                                                      # i.e. [:twitter, :facebook] .
   # 
   # config.twitter.key = "eYVNBjBDi33aa9GkA3w"
   # config.twitter.secret = "XpbeSdCoaKSmQGSeokz5qcUATClRW5u08QWNfv71N8"
@@ -34,56 +44,135 @@ Rails.application.config.sorcery.configure do |config|
   # --- user config ---
   config.user_config do |user|
     # -- core --
-    # user.username_attribute_name = :username                                        # change default username attribute, for example, to use :email as the login.
-    # user.password_attribute_name = :password                                        # change *virtual* password attribute, the one which is used until an encrypted one is generated.
+    # user.username_attribute_name = :username                                        # change default username
+                                                                                      # attribute, for example, 
+                                                                                      # to use :email as the login.
+                                                                                      
+    # user.password_attribute_name = :password                                        # change *virtual* password
+                                                                                      # attribute, the one which is used
+                                                                                      # until an encrypted one is
+                                                                                      # generated.
+                                                                                      
     # user.email_attribute_name = :email                                              # change default email attribute.
-    # user.crypted_password_attribute_name =  :crypted_password                       # change default crypted_password attribute.
-    # user.salt_join_token = ""                                                       # what pattern to use to join the password with the salt
+    
+    # user.crypted_password_attribute_name =  :crypted_password                       # change default crypted_password
+                                                                                      # attribute.
+                                                                                      
+    # user.salt_join_token = ""                                                       # what pattern to use to join the
+                                                                                      # password with the salt
+                                                                                      
     # user.salt_attribute_name = :salt                                                # change default salt attribute.
-    # user.stretches = nil                                                            # how many times to apply encryption to the password.
-    # user.encryption_key = nil                                                       # encryption key used to encrypt reversible encryptions such as AES256.
-    # user.custom_encryption_provider = nil                                           # use an external encryption class.
-    # user.encryption_algorithm = :bcrypt                                             # encryption algorithm name. See 'encryption_algorithm=' for available options.
-    # user.subclasses_inherit_config = false                                          # make this configuration inheritable for subclasses. Useful for ActiveRecord's STI.
+    
+    # user.stretches = nil                                                            # how many times to apply
+                                                                                      # encryption to the password.
+                                                                                      
+    # user.encryption_key = nil                                                       # encryption key used to encrypt
+                                                                                      # reversible encryptions such as
+                                                                                      # AES256.
+                                                                                      
+    # user.custom_encryption_provider = nil                                           # use an external encryption 
+                                                                                      # class.
+                                                                                      
+    # user.encryption_algorithm = :bcrypt                                             # encryption algorithm name. See
+                                                                                      # 'encryption_algorithm=' for
+                                                                                      # available options.
+                                                                                      
+    # user.subclasses_inherit_config = false                                          # make this configuration
+                                                                                      # inheritable for subclasses.
+                                                                                      # Useful for ActiveRecord's STI.
                                                                                       
     # -- user_activation --                                                           
-    # user.activation_state_attribute_name = :activation_state                        # the attribute name to hold activation state (active/pending).
-    # user.activation_token_attribute_name = :activation_token                        # the attribute name to hold activation code (sent by email).
-    # user.activation_token_expires_at_attribute_name = :activation_token_expires_at  # the attribute name to hold activation code expiration date. 
-    # user.activation_token_expiration_period =  nil                                  # how many seconds before the activation code expires. nil for never expires.
+    # user.activation_state_attribute_name = :activation_state                        # the attribute name to hold
+                                                                                      # activation state
+                                                                                      # (active/pending).
+                                                                                      
+    # user.activation_token_attribute_name = :activation_token                        # the attribute name to hold
+                                                                                      # activation code (sent by email).
+                                                                                      
+    # user.activation_token_expires_at_attribute_name = :activation_token_expires_at  # the attribute name to hold
+                                                                                      # activation code expiration date. 
+                                                                                      
+    # user.activation_token_expiration_period =  nil                                  # how many seconds before the
+                                                                                      # activation code expires. nil for
+                                                                                      # never expires.
+                                                                                      
     # user.user_activation_mailer = nil                                               # your mailer class. Required.
-    # user.activation_needed_email_method_name = :activation_needed_email             # activation needed email method on your mailer class.
-    # user.activation_success_email_method_name = :activation_success_email           # activation success email method on your mailer class.
-    # user.prevent_non_active_users_to_login = true                                   # do you want to prevent or allow users that did not activate by email to login?                     
+    
+    # user.activation_needed_email_method_name = :activation_needed_email             # activation needed email method
+                                                                                      # on your mailer class.
+                                                                                      
+    # user.activation_success_email_method_name = :activation_success_email           # activation success email method
+                                                                                      # on your mailer class.
+                                                                                      
+    # user.prevent_non_active_users_to_login = true                                   # do you want to prevent or allow
+                                                                                      # users that did not activate by
+                                                                                      # email to login?                     
                                                                   
     # -- reset_password --                                        
-    # user.reset_password_token_attribute_name = :reset_password_token                          # reset password code attribute name.
-    # user.reset_password_token_expires_at_attribute_name = :reset_password_token_expires_at    # expires at attribute name.
-    # user.reset_password_email_sent_at_attribute_name = :reset_password_email_sent_at          # when was email sent, used for hammering protection.
+    # user.reset_password_token_attribute_name = :reset_password_token                          # reset password code
+                                                                                                # attribute name.
+                                                                                                
+    # user.reset_password_token_expires_at_attribute_name = :reset_password_token_expires_at    # expires at attribute
+                                                                                                # name.
+                                                                                                
+    # user.reset_password_email_sent_at_attribute_name = :reset_password_email_sent_at          # when was email sent,
+                                                                                                # used for hammering
+                                                                                                # protection.
+                                                                                                
     # user.reset_password_mailer = nil                                                          # mailer class. Needed.
-    # user.reset_password_email_method_name = :reset_password_email                             # reset password email method on your mailer class.
-    # user.reset_password_expiration_period = nil                                               # how many seconds before the reset request expires. nil for never expires.
-    # user.reset_password_time_between_emails = 5 * 60                                          # hammering protection, how long to wait before allowing another email to be sent.
+    
+    # user.reset_password_email_method_name = :reset_password_email                             # reset password email
+                                                                                                # method on your mailer
+                                                                                                # class.
+                                                                                                
+    # user.reset_password_expiration_period = nil                                               # how many seconds
+                                                                                                # before the reset
+                                                                                                # request expires. nil
+                                                                                                # for never expires.
+                                                                                                
+    # user.reset_password_time_between_emails = 5 * 60                                          # hammering protection,
+                                                                                                # how long to wait
+                                                                                                # before allowing
+                                                                                                # another email to be
+                                                                                                # sent.
                                                                   
     # -- brute_force_protection --                                
     # user.failed_logins_count_attribute_name = :failed_logins_count                  # failed logins attribute name.
-    # user.lock_expires_at_attribute_name = :lock_expires_at                          # this field indicates whether user is banned and when it will be active again.
+    
+    # user.lock_expires_at_attribute_name = :lock_expires_at                          # this field indicates whether
+                                                                                      # user is banned and when it will
+                                                                                      # be active again.
+                                                                                      
     # user.consecutive_login_retries_amount_limit = 50                                # how many failed logins allowed.
-    # user.login_lock_time_period = 60 * 60                                           # how long the user should be banned. in seconds. 0 for permanent.
+    
+    # user.login_lock_time_period = 60 * 60                                           # how long the user should be
+                                                                                      # banned. in seconds. 0 for
+                                                                                      # permanent.
                                                                   
     # -- activity logging --                                      
     # user.last_login_at_attribute_name = :last_login_at                              # last login attribute name.
     # user.last_logout_at_attribute_name = :last_logout_at                            # last logout attribute name.
     # user.last_activity_at_attribute_name = :last_activity_at                        # last activity attribute name.
-    # user.activity_timeout = 10 * 60                                                 # how long since last activity is the user defined logged out?
+    # user.activity_timeout = 10 * 60                                                 # how long since last activity is
+                                                                                      # the user defined logged out?
                                                                                       
     # -- external --                                                                     
-    # user.authentications_class = nil                                                # class which holds the various external provider data for this user.
-    # user.authentications_user_id_attribute_name = :user_id                          # user's identifier in authentications class.
-    # user.provider_attribute_name = :provider                                        # provider's identifier in authentications class.
-    # user.provider_uid_attribute_name = :uid                                         # user's external unique identifier in authentications class.
+    # user.authentications_class = nil                                                # class which holds the various
+                                                                                      # external provider data for this
+                                                                                      # user.
+                                                                                      
+    # user.authentications_user_id_attribute_name = :user_id                          # user's identifier in
+                                                                                      # authentications class.
+                                                                                      
+    # user.provider_attribute_name = :provider                                        # provider's identifier in
+                                                                                      # authentications class.
+                                                                                      
+    # user.provider_uid_attribute_name = :uid                                         # user's external unique
+                                                                                      # identifier in authentications
+                                                                                      # class.
   end
 
   # This line must come after the 'user config' block.
-  config.user_class = User                                                            # define which model authenticates with sorcery.
+  config.user_class = User                                                            # define which model authenticates
+                                                                                      # with sorcery.
 end