authlogic 2.0.0 → 2.1.0

data/lib/authlogic/crypto_providers/bcrypt.rb

@@ -35,7 +35,9 @@ module Authlogic
     #
     # Tell acts_as_authentic to use it:
     #
-    #   acts_as_authentic :crypto_provider => Authlogic::CryptoProviders::BCrypt
+    #   acts_as_authentic do |c|
+    #     c.crypto_provider = Authlogic::CryptoProviders::BCrypt
+    #   end
     #
     # You are good to go!
     class BCrypt

data/lib/authlogic/crypto_providers/sha1.rb

@@ -2,8 +2,8 @@ require "digest/sha1"
 
 module Authlogic
   module CryptoProviders
-    # This class was made for the users transitioning from restful_authentication. I highly discourage using this crypto provider as it inferior to your other options.
-    # Please use any other provider offered by Authlogic.
+    # This class was made for the users transitioning from restful_authentication. I highly discourage using this
+    # crypto provider as it inferior to your other options. Please use any other provider offered by Authlogic.
     class Sha1
       class << self
         def join_token

data/lib/authlogic/i18n.rb

@@ -29,7 +29,7 @@ module Authlogic
   #   authlogic:
   #     error_messages:
   #       login_blank: can not be blank
-  #       login_not_found: does not exist
+  #       login_not_found: is not valid
   #       login_invalid: should use only letters, numbers, spaces, and .-_@ please.
   #       consecutive_failed_logins_limit_exceeded: Consecutive failed logins limit exceeded, account is disabled.
   #       email_invalid: should look like an email address.
@@ -39,6 +39,14 @@ module Authlogic
   #       not_confirmed: Your account is not confirmed
   #       not_approved: Your account is not approved
   #       no_authentication_details: You did not provide any details for authentication.
+  #     models:
+  #       user_session: UserSession (or whatever name you are using)
+  #     attributes:
+  #       user_session: (or whatever name you are using)
+  #         login: login
+  #         email: email
+  #         password: password
+  #         remember_me: remember me
   class I18n
     class << self
       # All message translation is passed to this method. The first argument is the key for the message. The second is options, see the rails I18n library for a list of options used.
@@ -49,6 +57,7 @@ module Authlogic
           options[:default]
         end
       end
+      alias_method :translate, :t
     end
   end
 end

data/lib/authlogic/regex.rb

@@ -0,0 +1,25 @@
+module Authlogic
+  # This is a module the contains regular expressions used throughout Authlogic. The point of extracting
+  # them out into their own module is to make them easily available to you for other uses. Ex:
+  #
+  #   validates_format_of :my_email_field, :with => Authlogic::Regex.email
+  module Regex
+    # A general email regular expression. It allows top level domains (TLD) to be from 2 - 4 in length, any
+    # TLD longer than that must be manually specified. The decisions behind this regular expression were made
+    # by reading this website: http://www.regular-expressions.info/email.html, which is an excellent resource
+    # for regular expressions.
+    def self.email
+      return @email_regex if @email_regex
+      email_name_regex  = '[A-Z0-9_\.%\+\-]+'
+      domain_head_regex = '(?:[A-Z0-9\-]+\.)+'
+      domain_tld_regex  = '(?:[A-Z]{2,4}|museum|travel)'
+      @email_regex = /\A#{email_name_regex}@#{domain_head_regex}#{domain_tld_regex}\z/i
+    end
+    
+    # A simple regular expression that only allows for letters, numbers, spaces, and .-_@. Just a standard login / username
+    # regular expression.
+    def self.login
+      /\A\w[\w\.+\-_@ ]+\z/
+    end
+  end
+end

data/lib/authlogic/session/activation.rb

@@ -29,6 +29,8 @@ module Authlogic
         # This accepts a controller object wrapped with the Authlogic controller adapter. The controller adapters close the gap
         # between the different controllers in each framework. That being said, Authlogic is expecting your object's class to
         # extend Authlogic::ControllerAdapters::AbstractAdapter. See Authlogic::ControllerAdapters for more info.
+        #
+        # Lastly, this is thread safe.
         def controller=(value)
           Thread.current[:authlogic_controller] = value
         end

data/lib/authlogic/session/active_record_trickery.rb

@@ -11,20 +11,36 @@ module Authlogic
       end
       
       module ClassMethods
-        def human_attribute_name(*args)
-          klass.human_attribute_name(*args)
+        # How to name the attributes of Authlogic, works JUST LIKE ActiveRecord, but instead it uses the following
+        # namespace:
+        #
+        #   authlogic.attributes.user_session.login
+        def human_attribute_name(attribute_key_name, options = {})
+          options[:count] ||= 1
+          options[:default] ||= attribute_key_name.to_s.humanize
+          I18n.t("attributes.#{name.underscore}.#{attribute_key_name}", options)
         end
         
+        # How to name the class, works JUST LIKE ActiveRecord, except it uses the following namespace:
+        #
+        #   authlogic.models.user_session
         def human_name(*args)
-          klass.human_name(*args)
+          I18n.t("models.#{name.underscore}", {:count => 1, :default => name.humanize})
         end
         
+        # For rails < 2.3, mispelled
         def self_and_descendents_from_active_record
           [self]
         end
+        
+        # For Rails >2.3, fix mispelling
+        def self_and_descendants_from_active_record
+          [self]
+        end
       end
       
       module InstanceMethods
+        # Don't use this yourself, this is to just trick some of the helpers since this is the method it calls.
         def new_record?
           new_session?
         end

data/lib/authlogic/session/brute_force_protection.rb

@@ -19,7 +19,8 @@ module Authlogic
         klass.class_eval do
           extend Config
           include InstanceMethods
-          validate :validate_failed_logins, :if => :protect_from_brute_force_attacks?
+          validate :reset_failed_login_count, :if => :reset_failed_login_count?
+          validate :validate_failed_logins, :if => :being_brute_force_protected?
         end
       end
       
@@ -36,7 +37,7 @@ module Authlogic
         # * <tt>Default:</tt> 50
         # * <tt>Accepts:</tt> Integer, set to 0 to disable
         def consecutive_failed_logins_limit(value = nil)
-          config(:consecutive_failed_logins_limit, value, 50)
+          rw_config(:consecutive_failed_logins_limit, value, 50)
         end
         alias_method :consecutive_failed_logins_limit=, :consecutive_failed_logins_limit
         
@@ -45,31 +46,45 @@ module Authlogic
         # * <tt>Default:</tt> 2.hours
         # * <tt>Accepts:</tt> Fixnum, set to 0 for permanent ban
         def failed_login_ban_for(value = nil)
-          config(:failed_login_ban_for, (!value.nil? && value) || value, 2.hours.to_i)
+          rw_config(:failed_login_ban_for, (!value.nil? && value) || value, 2.hours.to_i)
         end
         alias_method :failed_login_ban_for=, :failed_login_ban_for
       end
       
       # The methods available for an Authlogic::Session::Base object that make up the brute force protection feature.
       module InstanceMethods
+        # Returns true when the consecutive_failed_logins_limit has been exceeded and is being temporarily banned.
+        # Notice the word temporary, the user will not be permanently banned unless you choose to do so with configuration.
+        # By default they will be banned for 2 hours. During that 2 hour period this method will return true.
+        def being_brute_force_protected?
+          exceeded_failed_logins_limit? && (failed_login_ban_for <= 0 || (attempted_record.respond_to?(:updated_at) && attempted_record.updated_at >= failed_login_ban_for.seconds.ago))
+        end
+        
         private
-          def protect_from_brute_force_attacks?
+          def exceeded_failed_logins_limit?
             !attempted_record.nil? && attempted_record.respond_to?(:failed_login_count) && consecutive_failed_logins_limit > 0 &&
-              attempted_record.failed_login_count && attempted_record.failed_login_count >= consecutive_failed_logins_limit &&
-              (failed_login_ban_for <= 0 || (attempted_record.respond_to?(:updated_at) && attempted_record.updated_at >= failed_login_ban_for.seconds.ago))
+              attempted_record.failed_login_count && attempted_record.failed_login_count >= consecutive_failed_logins_limit
           end
           
-          def consecutive_failed_logins_limit
-            self.class.consecutive_failed_logins_limit
+          def reset_failed_login_count?
+            exceeded_failed_logins_limit? && !being_brute_force_protected?
           end
           
-          def failed_login_ban_for
-            self.class.failed_login_ban_for
+          def reset_failed_login_count
+            attempted_record.failed_login_count = 0
           end
         
           def validate_failed_logins
             errors.clear # Clear all other error messages, as they are irrelevant at this point and can only provide additional information that is not needed
-            errors.add_to_base(I18n.t('error_messages.consecutive_failed_logins_limit_exceeded', :default => "Consecutive failed logins limit exceeded, account is disabled."))
+            errors.add(:base, I18n.t('error_messages.consecutive_failed_logins_limit_exceeded', :default => "Consecutive failed logins limit exceeded, account is disabled."))
+          end
+          
+          def consecutive_failed_logins_limit
+            self.class.consecutive_failed_logins_limit
+          end
+          
+          def failed_login_ban_for
+            self.class.failed_login_ban_for
           end
       end
     end

data/lib/authlogic/session/callbacks.rb

@@ -1,8 +1,15 @@
 module Authlogic
   module Session
-    # Just like in ActiveRecord you have before_save, before_validation, etc. You have similar callbacks with Authlogic, see the METHODS constant below. The order of execution is as follows:
+    # Between these callsbacks and the configuration, this is the contract between me and you to safely
+    # modify Authlogic's behavior. I will do everything I can to make sure these do not change.
     #
-    # Here is the order they execute
+    # Check out the sub modules of Authlogic::Session. They are very concise, clear, and to the point. More
+    # importantly they use the same API that you would use to extend Authlogic. That being said, they are great
+    # examples of how to extend Authlogic and add / modify behavior to Authlogic. These modules could easily be pulled out
+    # into their own plugin and become an "add on" without any change.
+    #
+    # Now to the point of this module. Just like in ActiveRecord you have before_save, before_validation, etc.
+    # You have similar callbacks with Authlogic, see the METHODS constant below. The order of execution is as follows:
     #
     #   before_persisting
     #   persist
@@ -27,11 +34,13 @@ module Authlogic
     #   [save record if record.changed?]
     #   
     #   before_destroy
+    #   [save record if record.changed?]
     #   destroy
     #   after_destroy
     #
-    # Notice the "save record if changed?" lines above. This helps with performance. If you need to make changes to the associated record, there is no need to save the record, Authlogic will do it for you.
-    # This allow multiple modules to modify the record and execute as few queries as possible.
+    # Notice the "save record if changed?" lines above. This helps with performance. If you need to make
+    # changes to the associated record, there is no need to save the record, Authlogic will do it for you.
+    # This allows multiple modules to modify the record and execute as few queries as possible.
     #
     # **WARNING**: unlike ActiveRecord, these callbacks must be set up on the class level:
     #
@@ -41,7 +50,8 @@ module Authlogic
     #     # ..etc
     #   end
     #
-    # You can NOT define a "before_validation" method, this is bad practice and does not allow Authlogic to extend properly with multiple extensions. Please ONLY use the method above.
+    # You can NOT define a "before_validation" method, this is bad practice and does not allow Authlogic
+    # to extend properly with multiple extensions. Please ONLY use the method above.
     module Callbacks
       METHODS = [
         "before_persisting", "persist", "after_persisting",
@@ -70,7 +80,7 @@ module Authlogic
         
         def save_record(alternate_record = nil)
           r = alternate_record || record
-          r.save_without_session_maintenance(false) if r && r.changed?
+          r.save_without_session_maintenance(false) if r && r.changed? && !r.readonly?
         end
     end
   end

data/lib/authlogic/session/cookies.rb

@@ -1,6 +1,6 @@
 module Authlogic
   module Session
-    # Handles all authentication that deals with cookies, such as persisting a session and saving / destroying a session.
+    # Handles all authentication that deals with cookies, such as persisting, saving, and destroying.
     module Cookies
       def self.included(klass)
         klass.class_eval do
@@ -26,7 +26,7 @@ module Authlogic
         # * <tt>Default:</tt> "#{klass_name.underscore}_credentials"
         # * <tt>Accepts:</tt> String
         def cookie_key(value = nil)
-          config(:cookie_key, value, "#{klass_name.underscore}_credentials")
+          rw_config(:cookie_key, value, "#{klass_name.underscore}_credentials")
         end
         alias_method :cookie_key=, :cookie_key
         
@@ -35,7 +35,7 @@ module Authlogic
         # * <tt>Default:</tt> false
         # * <tt>Accepts:</tt> Boolean
         def remember_me(value = nil)
-          config(:remember_me, value, false)
+          rw_config(:remember_me, value, false)
         end
         alias_method :remember_me=, :remember_me
         
@@ -44,13 +44,14 @@ module Authlogic
         # * <tt>Default:</tt> 3.months
         # * <tt>Accepts:</tt> Integer, length of time in seconds, such as 60 or 3.months
         def remember_me_for(value = :_read)
-          config(:remember_me_for, value, 3.months, :_read)
+          rw_config(:remember_me_for, value, 3.months, :_read)
         end
         alias_method :remember_me_for=, :remember_me_for
       end
       
       # The methods available for an Authlogic::Session::Base object that make up the cookie feature set.
-      module InstanceMethods  
+      module InstanceMethods
+        # Allows you to set the remember_me option when passing credentials.
         def credentials=(value)
           super
           values = value.is_a?(Array) ? value : [value]
@@ -63,7 +64,8 @@ module Authlogic
           end
         end
         
-        def remember_me # :nodoc:
+        # Is the cookie going to expire after the session is over, or will it stick around?
+        def remember_me
           return @remember_me if defined?(@remember_me)
           @remember_me = self.class.remember_me
         end
@@ -73,7 +75,7 @@ module Authlogic
           @remember_me = value
         end
       
-        # Allows users to be remembered via a cookie.
+        # See remember_me
         def remember_me?
           remember_me == true || remember_me == "true" || remember_me == "1"
         end
@@ -96,13 +98,15 @@ module Authlogic
           end
           
           def cookie_credentials
-            controller.cookies[cookie_key]
+            controller.cookies[cookie_key] && controller.cookies[cookie_key].split("::")
           end
           
           # Tries to validate the session from information in the cookie
           def persist_by_cookie
-            if cookie_credentials
-              self.unauthorized_record = search_for_record("find_by_persistence_token", cookie_credentials)
+            persistence_token, record_id = cookie_credentials
+            if !persistence_token.nil?
+              record = record_id.nil? ? search_for_record("find_by_persistence_token", persistence_token) : search_for_record("find_by_#{klass.primary_key}", record_id)
+              self.unauthorized_record = record if record && record.persistence_token == persistence_token
               valid?
             else
               false
@@ -111,7 +115,7 @@ module Authlogic
         
           def save_cookie
             controller.cookies[cookie_key] = {
-              :value => record.persistence_token,
+              :value => "#{record.persistence_token}::#{record.send(record.class.primary_key)}",
               :expires => remember_me_until,
               :domain => controller.cookie_domain
             }

data/lib/authlogic/session/existence.rb

@@ -20,7 +20,7 @@ module Authlogic
         # A convenince method. The same as:
         #
         #   session = UserSession.new(*args)
-        #   session.create
+        #   session.save
         #
         # Instead you can do:
         #
@@ -42,13 +42,15 @@ module Authlogic
         # the user to authenticate again if it is needed.
         def destroy
           before_destroy
+          save_record
           errors.clear
           @record = nil
           after_destroy
           true
         end
         
-        # Returns true if the session has not been saved yet.
+        # Returns true if the session is new, meaning no action has been taken on it and a successful save
+        # has not taken place.
         def new_session?
           new_session != false
         end

data/lib/authlogic/session/foundation.rb

@@ -13,7 +13,7 @@ module Authlogic
       
       module ClassMethods
         private
-          def config(key, value, default_value = nil, read_value = nil)
+          def rw_config(key, value, default_value = nil, read_value = nil)
             if value == read_value
               return read_inheritable_attribute(key) if inheritable_attributes.include?(key)
               write_inheritable_attribute(key, default_value)

data/lib/authlogic/session/http_auth.rb

@@ -1,23 +1,58 @@
 module Authlogic
   module Session
-    # Handles all authentication that deals with basic HTTP auth.
+    # Handles all authentication that deals with basic HTTP auth. Which is authentication built into the HTTP protocol:
+    #
+    #   http://username:password@whatever.com
+    #
+    # Also, if you are not comfortable letting users pass their raw username and password you can always use the single
+    # access token. See Authlogic::Session::Params for more info.
     module HttpAuth
       def self.included(klass)
-        klass.persist :persist_by_http_auth
+        klass.class_eval do
+          extend Config
+          include InstanceMethods
+          persist :persist_by_http_auth, :if => :persist_by_http_auth?
+        end
       end
       
-      private
-        def persist_by_http_auth
-          controller.authenticate_with_http_basic do |login, password|
-            if !login.blank? && !password.blank?
-              send("#{login_field}=", login)
-              send("#{password_field}=", password)
-              return valid?
+      # Configuration for the HTTP basic auth feature of Authlogic.
+      module Config
+        # Do you want to allow your users to log in via HTTP basic auth?
+        #
+        # I recommend keeping this enabled. The only time I feel this should be disabled is if you are not comfortable
+        # having your users provide their raw username and password. Whatever the reason, you can disable it here.
+        #
+        # * <tt>Default:</tt> true
+        # * <tt>Accepts:</tt> Boolean
+        def allow_http_basic_auth(value = nil)
+          rw_config(:allow_http_basic_auth, value, true)
+        end
+        alias_method :allow_http_basic_auth=, :allow_http_basic_auth
+      end
+      
+      # Instance methods for the HTTP basic auth feature of authlogic.
+      module InstanceMethods
+        private
+          def persist_by_http_auth?
+            allow_http_basic_auth? && login_field && password_field
+          end
+        
+          def persist_by_http_auth
+            controller.authenticate_with_http_basic do |login, password|
+              if !login.blank? && !password.blank?
+                send("#{login_field}=", login)
+                send("#{password_field}=", password)
+                return valid?
+              end
             end
+        
+            false
           end
         
-          false
-        end
+          def allow_http_basic_auth?
+            self.class.allow_http_basic_auth == true
+          end
+      end
     end
   end
 end

data/lib/authlogic/session/magic_columns.rb

@@ -15,9 +15,10 @@ module Authlogic
         klass.class_eval do
           extend Config
           include InstanceMethods
-          after_persisting :set_last_request_at
+          after_persisting :set_last_request_at, :if => :set_last_request_at?
           validate :increase_failed_login_count
           before_save :update_info
+          before_save :set_last_request_at, :if => :set_last_request_at?
         end
       end
       
@@ -30,7 +31,7 @@ module Authlogic
         # * <tt>Default:</tt> 0
         # * <tt>Accepts:</tt> integer representing time in seconds
         def last_request_at_threshold(value = nil)
-          config(:last_request_at_threshold, value, 0)
+          rw_config(:last_request_at_threshold, value, 0)
         end
         alias_method :last_request_at_threshold=, :last_request_at_threshold
       end
@@ -39,7 +40,7 @@ module Authlogic
       module InstanceMethods
         private
           def increase_failed_login_count
-            if errors.on(password_field) && attempted_record.respond_to?(:failed_login_count)
+            if invalid_password? && attempted_record.respond_to?(:failed_login_count)
               attempted_record.failed_login_count ||= 0
               attempted_record.failed_login_count += 1
             end
@@ -59,11 +60,29 @@ module Authlogic
               record.current_login_ip = controller.request.remote_ip
             end
           end
+          
+          # This method lets authlogic know whether it should allow the last_request_at field to be updated
+          # with the current time (Time.now). One thing to note here is that it also checks for the existence of a
+          # last_request_update_allowed? method in your controller. This allows you to control this method pragmatically
+          # in your controller.
+          #
+          # For example, what if you had a javascript function that polled the server updating how much time is left in their
+          # session before it times out. Obviously you would want to ignore this request, because then the user would never time out.
+          # So you can do something like this in your controller:
+          #
+          #   def last_request_update_allowed?
+          #     action_name =! "update_session_time_left"
+          #   end
+          #
+          # You can do whatever you want with that method.
+          def set_last_request_at? # :doc:
+            return false if !record || !klass.column_names.include?("last_request_at")
+            return controller.last_request_update_allowed? if controller.responds_to_last_request_update_allowed?
+            record.last_request_at.blank? || last_request_at_threshold.to_i.seconds.ago >= record.last_request_at
+          end
         
           def set_last_request_at
-            if record && record.class.column_names.include?("last_request_at") && (record.last_request_at.blank? || last_request_at_threshold.to_i.seconds.ago >= record.last_request_at)
-              record.last_request_at = klass.default_timezone == :utc ? Time.now.utc : Time.now
-            end
+            record.last_request_at = klass.default_timezone == :utc ? Time.now.utc : Time.now
           end
           
           def last_request_at_threshold

data/lib/authlogic/session/magic_states.rb

@@ -17,7 +17,7 @@ module Authlogic
         klass.class_eval do
           extend Config
           include InstanceMethods
-          validate :validate_magic_states
+          validate :validate_magic_states, :unless => :disable_magic_states?
         end
       end
       
@@ -30,7 +30,7 @@ module Authlogic
         # * <tt>Default:</tt> false
         # * <tt>Accepts:</tt> Boolean
         def disable_magic_states(value = nil)
-          config(:disable_magic_states, value, false)
+          rw_config(:disable_magic_states, value, false)
         end
         alias_method :disable_magic_states=, :disable_magic_states
       end
@@ -43,10 +43,10 @@ module Authlogic
           end
         
           def validate_magic_states
-            return true if disable_magic_states? || attempted_record.nil?
+            return true if attempted_record.nil?
             [:active, :approved, :confirmed].each do |required_status|
               if attempted_record.respond_to?("#{required_status}?") && !attempted_record.send("#{required_status}?")
-                errors.add_to_base(I18n.t("error_messages.not_#{required_status}", :default => "Your account is not #{required_status}"))
+                errors.add(:base, I18n.t("error_messages.not_#{required_status}", :default => "Your account is not #{required_status}"))
                 return false
               end
             end

data/lib/authlogic/session/params.rb

@@ -43,17 +43,17 @@ module Authlogic
         # * <tt>Default:</tt> cookie_key
         # * <tt>Accepts:</tt> String
         def params_key(value = nil)
-          config(:params_key, value, cookie_key)
+          rw_config(:params_key, value, cookie_key)
         end
         alias_method :params_key=, :params_key
         
         # Authentication is allowed via a single access token, but maybe this is something you don't want for your application as a whole. Maybe this is something you only want for specific request types.
-        # Specify a list of allowed request types and single access authentication will only be allowed for the ones you specify. Checkout the "Single Access / Private Feeds Access" section in the README.
+        # Specify a list of allowed request types and single access authentication will only be allowed for the ones you specify.
         #
-        # * <tt>Default:</tt> "application/rss+xml", "application/atom+xml"
-        # * <tt>Accepts:</tt> String of request type, or :all to allow single access authentication for any and all request types
+        # * <tt>Default:</tt> ["application/rss+xml", "application/atom+xml"]
+        # * <tt>Accepts:</tt> String of a request type, or :all or :any to allow single access authentication for any and all request types
         def single_access_allowed_request_types(value = nil)
-          config(:single_access_allowed_request_types, value, ["application/rss+xml", "application/atom+xml"])
+          rw_config(:single_access_allowed_request_types, value, ["application/rss+xml", "application/atom+xml"])
         end
         alias_method :single_access_allowed_request_types=, :single_access_allowed_request_types
       end
@@ -68,10 +68,15 @@ module Authlogic
           end
           
           def params_enabled?
-            params_credentials && klass.column_names.include?("single_access_token") &&
-              (single_access_allowed_request_types.include?(controller.request_content_type) ||
-                single_access_allowed_request_types.include?(:all) ||
-                  controller.single_access_allowed?)
+            return false if !params_credentials || !klass.column_names.include?("single_access_token")
+            return controller.single_access_allowed? if controller.responds_to_single_access_allowed?
+            
+            case single_access_allowed_request_types
+            when Array
+              single_access_allowed_request_types.include?(controller.request_content_type) || single_access_allowed_request_types.include?(:all)
+            else
+              [:all, :any].include?(single_access_allowed_request_types)
+            end
           end
           
           def params_key