sorcery 0.1.4 → 0.2.0

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                  => Sorcery::Controller::Config.authentications_class,
+                             :@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/test_helpers.rb

@@ -0,0 +1,84 @@
+module Sorcery
+  module TestHelpers
+    SUBMODUELS_AUTO_ADDED_CONTROLLER_FILTERS = [:register_last_activity_time_to_db, :deny_banned_user, :validate_session]
+
+    def create_new_user(attributes_hash = nil)
+      user_attributes_hash = attributes_hash || {:username => 'gizmo', :email => "bla@bla.com", :password => 'secret'}
+      @user = User.new(user_attributes_hash)
+      @user.save!
+      @user
+    end
+
+    def create_new_external_user(provider, attributes_hash = nil)
+      user_attributes_hash = attributes_hash || {:username => 'gizmo', :authentications_attributes => [{:provider => provider, :uid => 123}]}
+      @user = User.new(user_attributes_hash)
+      @user.save!
+      @user
+    end
+    
+    def login_user(user = nil)
+      user ||= @user
+      subject.send(:login_user,user)
+      subject.send(:after_login!,user,[user.username,'secret'])
+    end
+
+    def logout_user
+      subject.send(:logout)
+    end
+
+    def clear_user_without_logout
+      subject.instance_variable_set(:@current_user,nil)
+    end
+
+    def sorcery_reload!(submodules = [], options = {})
+      reload_user_class
+
+      # return to no-module configuration
+      ::Sorcery::Controller::Config.init!
+      ::Sorcery::Controller::Config.reset!
+
+      # remove all plugin before_filters so they won't fail other tests.
+      # I don't like this way, but I didn't find another.
+      # hopefully it won't break until Rails 4.
+      ApplicationController._process_action_callbacks.delete_if {|c| SUBMODUELS_AUTO_ADDED_CONTROLLER_FILTERS.include?(c.filter) }
+
+      # configure
+      ::Sorcery::Controller::Config.submodules = submodules
+      ::Sorcery::Controller::Config.user_class = nil
+      ActionController::Base.send(:include,::Sorcery::Controller)
+
+      User.activate_sorcery! do |config|
+        options.each do |property,value|
+          config.send(:"#{property}=", value)
+        end
+      end
+    end
+
+    def sorcery_model_property_set(property, *values)
+      User.class_eval do
+        sorcery_config.send(:"#{property}=", *values)
+      end
+    end
+
+    def sorcery_controller_property_set(property, value)
+      ApplicationController.activate_sorcery! do |config|
+        config.send(:"#{property}=", value)
+      end
+    end
+    
+    def sorcery_controller_oauth_property_set(provider, property, value)
+      ApplicationController.activate_sorcery! do |config|
+        config.send(provider).send(:"#{property}=", value)
+      end
+    end
+
+    private
+
+    # reload user class between specs
+    # so it will be possible to test the different submodules in isolation
+    def reload_user_class
+      Object.send(:remove_const,:User)
+      load 'user.rb'
+    end
+  end
+end