sorcery 0.1.4 → 0.2.1

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

@@ -1,6 +1,8 @@
 module Sorcery
   module Controller
     module Submodules
+      # This submodule helps you set a timeout to all user sessions.
+      # The timeout can be configured and also you can choose to reset it on every user action.
       module SessionTimeout
         def self.included(base)
           base.send(:include, InstanceMethods)
@@ -23,16 +25,19 @@ module Sorcery
         module InstanceMethods
           protected
           
+          # Registers last login to be used as the timeout starting point.
+          # Runs as a hook after a successful login.
           def register_login_time(user, credentials)
             session[:login_time] = session[:last_action_time] = Time.now.utc
           end
           
+          # Checks if session timeout was reached and expires the current session if so.
           # To be used as a before_filter, before require_login
           def validate_session
             session_to_use = Config.session_timeout_from_last_action ? session[:last_action_time] : session[:login_time]
             if session_to_use && (Time.now.utc - session_to_use > Config.session_timeout)
               reset_session
-              @logged_in_user = false
+              @current_user = false
             else
               session[:last_action_time] = Time.now.utc
             end

data/lib/sorcery/controller.rb

@@ -5,7 +5,7 @@ module Sorcery
         extend ClassMethods
         include InstanceMethods
         Config.submodules.each do |mod|
-          begin
+          begin # FIXME: is this protection needed?
             include Submodules.const_get(mod.to_s.split("_").map {|p| p.capitalize}.join("")) 
           rescue NameError
             # don't stop on a missing submodule.
@@ -32,62 +32,74 @@ module Sorcery
       # If all attempts to auto-login fail, the failure callback will be called.
       def require_login
         if !logged_in?
-          session[:user_wanted_url] = request.url if Config.save_user_wanted_url
+          session[:return_to_url] = request.url if Config.save_return_to_url
           self.send(Config.not_authenticated_action) 
         end
       end
       
+      # Takes credentials and returns a user on successful authentication.
+      # Runs hooks after login or failed login.
       def login(*credentials)
         user = Config.user_class.authenticate(*credentials)
         if user
+          return_to_url = session[:return_to_url]
           reset_session # protect from session fixation attacks
+          session[:return_to_url] = return_to_url
           login_user(user)
           after_login!(user, credentials)
-          logged_in_user
+          current_user
         else
           after_failed_login!(credentials)
           nil
         end
       end
       
+      # Resets the session and runs hooks before and after.
       def logout
         if logged_in?
-          before_logout!(logged_in_user)
+          before_logout!(current_user)
           reset_session
           after_logout!
         end
       end
       
       def logged_in?
-        !!logged_in_user
+        !!current_user
       end
       
       # attempts to auto-login from the sources defined (session, basic_auth, cookie, etc.)
       # returns the logged in user if found, false if not (using old restful-authentication trick, nil != false).
-      def logged_in_user
-        @logged_in_user ||= login_from_session || login_from_other_sources unless @logged_in_user == false
+      def current_user
+        @current_user ||= login_from_session || login_from_other_sources unless @current_user == false
       end
       
-      def login_from_other_sources
-        result = nil
-        Config.login_sources.find do |source|
-          result = send(source)
-        end
-        result || false
+      def return_or_redirect_to(url, flash_hash = {})
+        redirect_to(session[:return_to_url] || url, :flash => flash_hash)
       end
       
+      # The default action for denying non-authenticated users.
+      # You can override this method in your controllers.
       def not_authenticated
         redirect_to root_path
       end
       
       protected
       
+      # Tries all available sources (methods) until one doesn't return false.
+      def login_from_other_sources
+        result = nil
+        Config.login_sources.find do |source|
+          result = send(source)
+        end
+        result || false
+      end
+      
       def login_user(user)
         session[:user_id] = user.id
       end
       
       def login_from_session
-        @logged_in_user = (Config.user_class.find_by_id(session[:user_id]) if session[:user_id]) || false
+        @current_user = (Config.user_class.find_by_id(session[:user_id]) if session[:user_id]) || false
       end
       
       def after_login!(user, credentials)
@@ -112,11 +124,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 activate_sorcery! in the User class.
                       
                       :not_authenticated_action,      # what controller action to call for non-authenticated users.
                       
-                      :save_user_wanted_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,
@@ -138,7 +150,7 @@ module Sorcery
             :@before_logout                        => [],
             :@after_logout                         => [],
             :@after_config                         => [],
-            :@save_user_wanted_url                 => true
+            :@save_return_to_url                   => true
           }
         end
         

data/lib/sorcery/engine.rb

@@ -13,8 +13,15 @@ module Sorcery
     
     initializer "extend Controller with sorcery" do |app|
       ActionController::Base.send(:include, Sorcery::Controller)
-      ActionController::Base.helper_method :logged_in_user
+      ActionController::Base.helper_method :current_user
     end
-
+    
+    initializer "attempt to preload user model" do |app|
+      begin
+        require Rails.root + "app/models/user.rb"
+      rescue LoadError
+      end
+    end
+    
   end
 end

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

@@ -1,20 +1,25 @@
 module Sorcery
   module Model
     module Submodules
+      # 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 model part of the submodule, which provides configuration options.
       module ActivityLogging
         def self.included(base)
           base.extend(ClassMethods)
           base.sorcery_config.class_eval do
-            attr_accessor :last_login_at_attribute_name,                     # last login attribute name.
-                          :last_logout_at_attribute_name,                    # last logout attribute name.
-                          :last_activity_at_attribute_name,                  # last activity attribute name.
+            attr_accessor :last_login_at_attribute_name,                  # last login attribute name.
+                          :last_logout_at_attribute_name,                 # last logout attribute name.
+                          :last_activity_at_attribute_name,               # last activity attribute name.
                           :activity_timeout                               # how long since last activity is the user defined logged out?
           end
           
           base.sorcery_config.instance_eval do
-            @defaults.merge!(:@last_login_at_attribute_name                   => :last_login_at,
-                             :@last_logout_at_attribute_name                  => :last_logout_at,
-                             :@last_activity_at_attribute_name                => :last_activity_at,
+            @defaults.merge!(:@last_login_at_attribute_name                => :last_login_at,
+                             :@last_logout_at_attribute_name               => :last_logout_at,
+                             :@last_activity_at_attribute_name             => :last_activity_at,
                              :@activity_timeout                            => 10.minutes)
             reset!
           end
@@ -22,7 +27,7 @@ module Sorcery
         
         module ClassMethods
           # get all users with last_activity within timeout
-          def logged_in_users
+          def current_users
             config = sorcery_config
             where("#{config.last_activity_at_attribute_name} IS NOT NULL") \
             .where("#{config.last_logout_at_attribute_name} IS NULL OR #{config.last_activity_at_attribute_name} > #{config.last_logout_at_attribute_name}") \

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

@@ -1,19 +1,21 @@
 module Sorcery
   module Model
     module Submodules
+      # This module helps protect user accounts by locking them down after too many failed attemps to login were detected.
+      # This is the model part of the submodule which provides configuration options and methods for locking and unlocking the user.
       module BruteForceProtection
         def self.included(base)
           base.sorcery_config.class_eval do
             attr_accessor :failed_logins_count_attribute_name,        # failed logins attribute name.
                           :lock_expires_at_attribute_name,            # this field indicates whether user is banned and when it will be active again.
-                          :consecutive_login_retries_amount_allowed,  # how many failed logins allowed.
+                          :consecutive_login_retries_amount_limit,    # how many failed logins allowed.
                           :login_lock_time_period                     # how long the user should be banned. in seconds. 0 for permanent.
           end
           
           base.sorcery_config.instance_eval do
             @defaults.merge!(:@failed_logins_count_attribute_name              => :failed_logins_count,
                              :@lock_expires_at_attribute_name                  => :lock_expires_at,
-                             :@consecutive_login_retries_amount_allowed        => 50,
+                             :@consecutive_login_retries_amount_limit          => 50,
                              :@login_lock_time_period                          => 3600)
             reset!
           end
@@ -33,11 +35,14 @@ module Sorcery
         end
         
         module InstanceMethods
+          # Called by the controller to increment the failed logins counter.
+          # Calls 'lock!' if login retries limit was reached.
           def register_failed_login!
             config = sorcery_config
+            return if !unlocked?
             self.increment(config.failed_logins_count_attribute_name)
             save!
-            self.lock! if self.send(config.failed_logins_count_attribute_name) >= config.consecutive_login_retries_amount_allowed
+            self.lock! if self.send(config.failed_logins_count_attribute_name) >= config.consecutive_login_retries_amount_limit
           end
           
           protected
@@ -58,9 +63,11 @@ module Sorcery
             self.send(config.lock_expires_at_attribute_name).nil?
           end
           
+          # Prevents a locked user from logging in, and unlocks users that expired their lock time.
+          # Runs as a hook before authenticate.
           def prevent_locked_user_login
             config = sorcery_config
-            if !self.unlocked?
+            if !self.unlocked? && config.login_lock_time_period != 0
               self.unlock! if self.send(config.lock_expires_at_attribute_name) <= Time.now.utc
             end
             unlocked?

data/lib/sorcery/model/submodules/oauth.rb

@@ -0,0 +1,53 @@
+module Sorcery
+  module Model
+    module Submodules
+      # This submodule helps you login users from OAuth providers such as Twitter.
+      # This is the model part which handles finding the user using access tokens.
+      # For the controller options see Sorcery::Controller::Oauth.
+      #
+      # Socery assumes (read: requires) you will create external users in the same table where you keep your regular users,
+      # but that you will have a separate table for keeping their external authentication data,
+      # and that that separate table has a few rows for each user, facebook and twitter for example (a one-to-many relationship).
+      #
+      # External users will have a null crypted_password field, since we do not hold their password.
+      # They will not be sent activation emails on creation.
+      module Oauth
+        def self.included(base)
+          base.sorcery_config.class_eval do
+            attr_accessor :authentications_class,
+                          :authentications_user_id_attribute_name,
+                          :provider_attribute_name,
+                          :provider_uid_attribute_name
+
+          end
+          
+          base.sorcery_config.instance_eval do
+            @defaults.merge!(:@authentications_class                  => nil,
+                             :@authentications_user_id_attribute_name => :user_id,
+                             :@provider_attribute_name                => :provider,
+                             :@provider_uid_attribute_name            => :uid)
+
+            reset!
+          end
+          
+          base.send(:include, InstanceMethods)
+          base.extend(ClassMethods)
+        end
+        
+        module ClassMethods
+          # takes a provider and uid and finds a user by them.
+          def load_from_provider(provider,uid)
+            config = sorcery_config
+            authentication = config.authentications_class.find_by_provider_and_uid(provider, uid)
+            user = find(authentication.send(config.authentications_user_id_attribute_name)) if authentication
+          end
+        end
+        
+        module InstanceMethods
+
+        end
+      
+      end
+    end
+  end
+end

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

@@ -1,6 +1,8 @@
 module Sorcery
   module Model
     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,
+      # until the cookie expires.
       module RememberMe
         def self.included(base)
           base.sorcery_config.class_eval do
@@ -22,15 +24,15 @@ module Sorcery
         end
         
         module InstanceMethods
-          # You shouldn't really use this one - it's called by the controller's 'remember_me!' method.
+          # You shouldn't really use this one yourself - it's called by the controller's 'remember_me!' method.
           def remember_me!
             config = sorcery_config
-            self.send(:"#{config.remember_me_token_attribute_name}=", generate_random_code)
+            self.send(:"#{config.remember_me_token_attribute_name}=", generate_random_token)
             self.send(:"#{config.remember_me_token_expires_at_attribute_name}=", Time.now + config.remember_me_for)
             self.save!(:validate => false)
           end
           
-          # You shouldn't really use this one - it's called by the controller's 'forget_me!' method.
+          # You shouldn't really use this one yourself - it's called by the controller's 'forget_me!' method.
           def forget_me!
             config = sorcery_config
             self.send(:"#{config.remember_me_token_attribute_name}=", nil)

data/lib/sorcery/model/submodules/reset_password.rb

@@ -2,6 +2,12 @@ module Sorcery
   module Model
     module Submodules
       # This submodule adds the ability to reset password via email confirmation.
+      # When the user requests an email is sent to him with a url.
+      # The url includes a token, which is also saved with the user's record in the db.
+      # The token has configurable expiration.
+      # When the user clicks the url in the email, providing the token has not yet expired, he will be able to reset his password via a form.
+      #
+      # When using this submodule, supplying a mailer is mandatory.
       module ResetPassword       
         def self.included(base)
           base.sorcery_config.class_eval do
@@ -30,22 +36,22 @@ module Sorcery
           base.sorcery_config.after_config << :validate_mailer_defined
           
           base.extend(ClassMethods)
+          base.send(:include, TemporaryToken)
           base.send(:include, InstanceMethods)
         end
         
         module ClassMethods
-          
+          # Find user by token, also checks for expiration.
+          # Returns the user if token found and is valid.
           def load_from_reset_password_token(token)
-            return nil if token.blank?
-            user = where("#{@sorcery_config.reset_password_token_attribute_name} = ?", token).first
-            if !user.blank? && !@sorcery_config.reset_password_expiration_period.nil?
-              return user.reset_password_token_valid? ? user : nil
-            end
-            user
+            token_attr_name = @sorcery_config.reset_password_token_attribute_name
+            token_expiration_date_attr = @sorcery_config.reset_password_token_expires_at_attribute_name
+            load_from_token(token, token_attr_name, token_expiration_date_attr)
           end
           
           protected
           
+          # This submodule requires the developer to define his own mailer class to be used by it.
           def validate_mailer_defined
             msg = "To use reset_password submodule, you must define a mailer (config.reset_password_mailer = YourMailerClass)."
             raise ArgumentError, msg if @sorcery_config.reset_password_mailer == nil
@@ -59,7 +65,7 @@ module Sorcery
             config = sorcery_config
             # hammering protection
             return if config.reset_password_time_between_emails && self.send(config.reset_password_email_sent_at_attribute_name) && self.send(config.reset_password_email_sent_at_attribute_name) > config.reset_password_time_between_emails.ago.utc
-            self.send(:"#{config.reset_password_token_attribute_name}=", generate_random_code)
+            self.send(:"#{config.reset_password_token_attribute_name}=", generate_random_token)
             self.send(:"#{config.reset_password_token_expires_at_attribute_name}=", Time.now.utc + config.reset_password_expiration_period) if config.reset_password_expiration_period
             self.send(:"#{config.reset_password_email_sent_at_attribute_name}=", Time.now.utc)
             self.class.transaction do
@@ -68,18 +74,15 @@ module Sorcery
             end
           end
           
+          # Clears token and tries to update the new password for the user.
           def reset_password!(params)
             clear_reset_password_token
             update_attributes(params)
           end
-          
-          def reset_password_token_valid?
-            config = sorcery_config
-            config.reset_password_expiration_period ? Time.now.utc < self.send(config.reset_password_token_expires_at_attribute_name) : true
-          end
 
           protected
 
+          # Clears the token.
           def clear_reset_password_token
             config = sorcery_config
             self.send(:"#{config.reset_password_token_attribute_name}=", nil)

data/lib/sorcery/model/submodules/user_activation.rb

@@ -8,27 +8,33 @@ module Sorcery
       module UserActivation
         def self.included(base)
           base.sorcery_config.class_eval do
-            attr_accessor :activation_state_attribute_name,         # the attribute name to hold activation state (active/pending).
-                          :activation_code_attribute_name,          # the attribute name to hold activation code (sent by email).
-                          :user_activation_mailer,                  # your mailer class. Needed.
-                          :activation_needed_email_method_name,     # activation needed email method on your mailer class.
-                          :activation_success_email_method_name,    # activation success email method on your mailer class.
-                          :prevent_non_active_users_to_login        # do you want to prevent or allow users that did not activate by email to login?
+            attr_accessor :activation_state_attribute_name,               # the attribute name to hold activation state (active/pending).
+                          :activation_token_attribute_name,               # the attribute name to hold activation code (sent by email).
+                          :activation_token_expires_at_attribute_name,    # the attribute name to hold activation code expiration date. 
+                          :activation_token_expiration_period,            # how many seconds before the activation code expires. nil for never expires.
+                          :user_activation_mailer,                        # your mailer class. Required.
+                          :activation_needed_email_method_name,           # activation needed email method on your mailer class.
+                          :activation_success_email_method_name,          # activation success email method on your mailer class.
+                          :prevent_non_active_users_to_login              # do you want to prevent or allow users that did not activate by email to login?
           end
           
           base.sorcery_config.instance_eval do
-            @defaults.merge!(:@activation_state_attribute_name      => :activation_state,
-                             :@activation_code_attribute_name       => :activation_code,
-                             :@user_activation_mailer               => nil,
-                             :@activation_needed_email_method_name  => :activation_needed_email,
-                             :@activation_success_email_method_name => :activation_success_email,
-                             :@prevent_non_active_users_to_login    => true)
+            @defaults.merge!(:@activation_state_attribute_name             => :activation_state,
+                             :@activation_token_attribute_name             => :activation_token,
+                             :@activation_token_expires_at_attribute_name  => :activation_token_expires_at,
+                             :@activation_token_expiration_period          => nil,
+                             :@user_activation_mailer                      => nil,
+                             :@activation_needed_email_method_name         => :activation_needed_email,
+                             :@activation_success_email_method_name        => :activation_success_email,
+                             :@prevent_non_active_users_to_login           => true)
             reset!
           end
           
           base.class_eval do
-            before_create :setup_activation
-            after_create :send_activation_needed_email!
+            # don't setup activation if no password supplied - this user is created automatically
+            before_create :setup_activation, :if => Proc.new { |user| user.send(sorcery_config.password_attribute_name).present? }
+            # don't send activation needed email if no crypted password created - this user is external (OAuth etc.)
+            after_create  :send_activation_needed_email!, :if => Proc.new { |user| !user.external?}
           end
           
           base.sorcery_config.after_config << :validate_mailer_defined
@@ -36,12 +42,22 @@ module Sorcery
           base.sorcery_config.before_authenticate << :prevent_non_active_login
           
           base.extend(ClassMethods)
+          base.send(:include, TemporaryToken)
           base.send(:include, InstanceMethods)
         end
         
         module ClassMethods
+          # Find user by token, also checks for expiration.
+          # Returns the user if token found and is valid.
+          def load_from_activation_token(token)
+            token_attr_name = @sorcery_config.activation_token_attribute_name
+            token_expiration_date_attr = @sorcery_config.activation_token_expires_at_attribute_name
+            load_from_token(token, token_attr_name, token_expiration_date_attr)
+          end
+          
           protected
           
+          # This submodule requires the developer to define his own mailer class to be used by it.
           def validate_mailer_defined
             msg = "To use user_activation submodule, you must define a mailer (config.user_activation_mailer = YourMailerClass)."
             raise ArgumentError, msg if @sorcery_config.user_activation_mailer == nil
@@ -49,23 +65,26 @@ module Sorcery
         end
         
         module InstanceMethods
+          # clears activation code, sets the user as 'active' and optionaly sends a success email.
           def activate!
             config = sorcery_config
-            self.send(:"#{config.activation_code_attribute_name}=", nil)
+            self.send(:"#{config.activation_token_attribute_name}=", nil)
             self.send(:"#{config.activation_state_attribute_name}=", "active")
-            send_activation_success_email!
+            send_activation_success_email! unless self.external?
             save!(:validate => false) # don't run validations
           end
-
+          
           protected
 
           def setup_activation
             config = sorcery_config
-            generated_activation_code = CryptoProviders::SHA1.encrypt( Time.now.to_s.split(//).sort_by {rand}.join )
-            self.send(:"#{config.activation_code_attribute_name}=", generated_activation_code)
+            generated_activation_token = generate_random_token
+            self.send(:"#{config.activation_token_attribute_name}=", generated_activation_token)
             self.send(:"#{config.activation_state_attribute_name}=", "pending")
+            self.send(:"#{config.activation_token_expires_at_attribute_name}=", Time.now.utc + config.activation_token_expiration_period) if config.activation_token_expiration_period
           end
 
+          # called automatically after user initial creation.
           def send_activation_needed_email!
             generic_send_email(:activation_needed_email_method_name, :user_activation_mailer) unless sorcery_config.activation_needed_email_method_name.nil?
           end

data/lib/sorcery/model/temporary_token.rb

@@ -0,0 +1,22 @@
+module Sorcery
+  module Model
+    # This module encapsulates the logic for temporary token.
+    # A temporary token is created to identify a user in scenarios such as reseting password and activating the user by email.
+    module TemporaryToken
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+      
+      module ClassMethods
+        def load_from_token(token, token_attr_name, token_expiration_date_attr)
+          return nil if token.blank?
+          user = where("#{token_attr_name} = ?", token).first
+          if !user.blank? && !user.send(token_expiration_date_attr).nil?
+            return Time.now.utc < user.send(token_expiration_date_attr) ? user : nil
+          end
+          user
+        end
+      end
+    end
+  end
+end

data/lib/sorcery/model.rb

@@ -55,7 +55,8 @@ module Sorcery
         _salt = user.send(@sorcery_config.salt_attribute_name) if user && !@sorcery_config.salt_attribute_name.nil? && !@sorcery_config.encryption_provider.nil?
         user if user && @sorcery_config.before_authenticate.all? {|c| user.send(c)} && credentials_match?(user.send(@sorcery_config.crypted_password_attribute_name),credentials[1],_salt)
       end
-
+      
+      # Calls the configured encryption provider to compare the supplied password with the encrypted one.
       def credentials_match?(crypted, *tokens)
         return crypted == tokens.join if @sorcery_config.encryption_provider.nil?
         @sorcery_config.encryption_provider.matches?(crypted, *tokens)
@@ -78,13 +79,19 @@ module Sorcery
         self.class.sorcery_config
       end
       
+      # identifies whether this user is regular, i.e. we hold his credentials in our db,
+      # or that he is external, and his credentials are saved elsewhere (twitter/facebook etc.).
+      def external?
+        send(sorcery_config.crypted_password_attribute_name).nil?
+      end
+      
       protected
       
       # creates new salt and saves it.
       # encrypts password with salt and save it.
       def encrypt_password
         config = sorcery_config
-        new_salt = self.send(:"#{config.salt_attribute_name}=", generate_random_code) if !config.salt_attribute_name.nil?
+        new_salt = self.send(:"#{config.salt_attribute_name}=", generate_random_token) if !config.salt_attribute_name.nil?
         self.send(:"#{config.crypted_password_attribute_name}=", self.class.encrypt(self.send(config.password_attribute_name),new_salt))
       end
 
@@ -104,7 +111,7 @@ module Sorcery
       end
       
       # Random code, used for salt and temporary tokens.
-      def generate_random_code
+      def generate_random_token
         return Digest::SHA1.hexdigest( Time.now.to_s.split(//).sort_by {rand}.join )
       end
     end