sorcery 0.5.3 → 0.5.21

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.3/frames
+Documentation: http://rubydoc.info/gems/sorcery/0.5.21/frames
 
 Check out the tutorials in the github wiki!
 

data/VERSION

@@ -1 +1 @@
-0.5.3
+0.5.21

data/lib/sorcery/controller.rb

@@ -62,8 +62,7 @@ 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
@@ -116,12 +115,11 @@ module Sorcery
       class << self
         attr_accessor :submodules,
         
-                      :user_class,                    # what class to use as the user class. 
+                      :user_class,                    # what class to use as the user class. Set automatically when you call authenticates_with_sorcery! in 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,16 +1,13 @@
 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)
@@ -24,8 +21,7 @@ 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,12 +1,9 @@
 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,10 +2,8 @@ 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)
@@ -30,12 +28,9 @@ 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,8 +1,7 @@
 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
@@ -17,7 +16,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!
-            set_remember_me_cookie!(current_user)      
+            cookies[:remember_me_token] = { :value => current_user.remember_me_token, :expires => current_user.remember_me_token_expires_at }        
           end
 
           # Clears the cookie and clears the token from the db.
@@ -34,25 +33,17 @@ 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?
-              set_remember_me_cookie!(user)
+              cookies[:remember_me_token] = { :value => user.remember_me_token, :expires => user.remember_me_token_expires_at }
               @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,9 +9,7 @@ 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,21 +2,18 @@ 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,12 +2,9 @@ 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"
@@ -40,10 +37,8 @@ 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
@@ -62,8 +57,7 @@ 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,8 +1,7 @@
 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,8 +1,7 @@
 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,35 +1,25 @@
 # 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"
@@ -44,135 +34,56 @@ 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