sorcery 0.1.4 → 0.3.0

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

@@ -1,27 +1,25 @@
 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
           
-          base.class_eval do
-
-          end
-          
           base.sorcery_config.before_authenticate << :prevent_locked_user_login
           base.extend(ClassMethods)
           base.send(:include, InstanceMethods)
@@ -33,11 +31,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 +59,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

data/lib/sorcery/sinatra.rb

@@ -0,0 +1,14 @@
+ActiveRecord::Base.send(:include, Sorcery::Model) if defined?(ActiveRecord)
+if defined?(Sinatra::Base)
+  Sinatra::Base.send(:include, Sorcery::Controller::Adapters::Sinatra)
+  Sinatra::Base.send(:include, Sorcery::Controller)
+  # Sorcery::Controller::Config.class_eval do
+  #   class << self
+  #     def submodules=(mods)
+  #       @submodules = mods
+  #       Sinatra::Base.send(:include, Sorcery::Controller::Adapters::Sinatra)
+  #       Sinatra::Base.send(:include, Sorcery::Controller)
+  #     end
+  #   end
+  # end
+end

data/lib/sorcery/test_helpers/rails.rb

@@ -0,0 +1,57 @@
+module Sorcery
+  module TestHelpers
+    module Rails
+      SUBMODUELS_AUTO_ADDED_CONTROLLER_FILTERS = [:register_last_activity_time_to_db, :deny_banned_user, :validate_session]
+      
+      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_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
+      
+      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
+    end
+  end
+end

data/lib/sorcery/test_helpers/sinatra.rb

@@ -0,0 +1,131 @@
+module Sorcery
+  module TestHelpers
+    module Sinatra
+      
+      class MyApp
+        class << self
+          def new
+            return this
+          end
+        end
+      end
+      
+      class ::Sinatra::Application
+        class << self
+          attr_accessor :sorcery_vars
+        end
+        @sorcery_vars = {}
+
+        # NOTE: see before and after test filters in filters.rb
+        
+        def save_instance_vars
+          instance_variables.each do |var|
+            self.class.sorcery_vars[:"#{var.to_s.delete("@")}"] = instance_variable_get(var)
+          end
+        end
+      end
+                    
+      ::RSpec::Matchers.define :redirect_to do |expected|
+        match do |actual|
+          actual.status == 302 && actual.location == expected
+        end
+      end
+      
+      def get_sinatra_app(app)
+        while app.class != ::Sinatra::Application do
+          app = app.instance_variable_get(:@app)
+        end
+        app
+      end
+      
+      def login_user(user=nil)
+        user ||= @user
+        get_sinatra_app(subject).send(:login_user,user)
+        get_sinatra_app(subject).send(:after_login!,user,[user.username,'secret'])
+      end
+      
+      def logout_user
+        get_sinatra_app(subject).send(:logout)
+      end
+
+      def clear_user_without_logout
+        get_sinatra_app(subject).instance_variable_set(:@current_user,nil)
+      end
+        
+      def assigns
+        ::Sinatra::Application.sorcery_vars
+      end
+      
+      class SessionData
+        def initialize(cookies)
+          @cookies = cookies
+          @data = cookies['rack.session']
+          if @data
+            @data = @data.unpack("m*").first
+            @data = Marshal.load(@data)
+          else
+            @data = {}
+          end
+        end
+
+        def [](key)
+          @data[key]
+        end
+
+        def []=(key, value)
+          @data[key] = value
+          session_data = Marshal.dump(@data)
+          session_data = [session_data].pack("m*")
+          @cookies.merge("rack.session=#{Rack::Utils.escape(session_data)}", URI.parse("//example.org//"))
+          raise "session variable not set" unless @cookies['rack.session'] == session_data
+        end
+      end
+
+      def session
+        SessionData.new(rack_test_session.instance_variable_get(:@rack_mock_session).cookie_jar)
+      end
+      
+      def cookies
+        rack_test_session.instance_variable_get(:@rack_mock_session).cookie_jar
+      end
+      
+      def sorcery_reload!(submodules = [], options = {})
+        reload_user_class
+
+        # return to no-module configuration
+        ::Sorcery::Controller::Config.init!
+        ::Sorcery::Controller::Config.reset!
+
+        # clear all filters
+        ::Sinatra::Application.instance_variable_set(:@filters,{:before => [],:after => []})
+        ::Sinatra::Application.class_eval do
+          load File.join(File.dirname(__FILE__),'..','..','..','spec','sinatra','filters.rb')
+        end
+        
+        # configure
+        ::Sorcery::Controller::Config.submodules = submodules
+        ::Sorcery::Controller::Config.user_class = nil
+        ::Sinatra::Application.send(:include, Sorcery::Controller::Adapters::Sinatra)
+        ::Sinatra::Application.send(:include, Sorcery::Controller)
+        
+        User.activate_sorcery! do |config|
+          options.each do |property,value|
+            config.send(:"#{property}=", value)
+          end
+        end
+      end
+      
+      def sorcery_controller_property_set(property, value)
+        ::Sinatra::Application.activate_sorcery! do |config|
+          config.send(:"#{property}=", value)
+        end
+      end
+
+      def sorcery_controller_oauth_property_set(provider, property, value)
+        ::Sinatra::Application.activate_sorcery! do |config|
+          config.send(provider).send(:"#{property}=", value)
+        end
+      end
+    end
+  end
+end

data/lib/sorcery/test_helpers.rb

@@ -0,0 +1,40 @@
+module Sorcery
+  module TestHelpers
+    # a patch to fix a bug in testing that happens when you 'destroy' a session twice.
+    # After the first destroy, the session is an ordinary hash, and then when destroy is called again there's an exception.
+    class ::Hash
+      def destroy
+        clear
+      end
+    end
+    
+    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 sorcery_model_property_set(property, *values)
+      User.class_eval do
+        sorcery_config.send(:"#{property}=", *values)
+      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