authenticate 0.3.1 → 0.3.2

data/lib/authenticate/model/email.rb

@@ -2,7 +2,7 @@ require 'email_validator'
 
 module Authenticate
   module Model
-
+    #
     # Use :email as the identifier for the user. Email must be unique.
     #
     # = Columns
@@ -18,7 +18,7 @@ module Authenticate
     #
     # = Class Methods
     # * credentials(params) - return the credentials required for authorization by email
-    # * authenticate(credentials) - find user with given email, validate their password, return the user if authenticated
+    # * authenticate(credentials) - find user with given email, validate their password, return user if authenticated
     # * normalize_email(email) - clean up the given email and return it.
     # * find_by_credentials(credentials) - find and return the user with the email address in the credentials
     #
@@ -37,9 +37,11 @@ module Authenticate
                   uniqueness: { allow_blank: true }
       end
 
-
+      # Class methods for authenticating using email as the user identifier.
       module ClassMethods
-
+        # Retrieve credentials from params.
+        #
+        # @return [id, pw]
         def credentials(params)
           return [] if params.nil? || params[:session].nil?
           [params[:session][:email], params[:session][:password]]
@@ -54,18 +56,14 @@ module Authenticate
           email = credentials[0]
           find_by_normalized_email(email)
         end
-
       end
 
-      # Sets the email on this instance to the value returned by
-      # {.normalize_email}
+      # Sets the email on this instance to the value returned by class method #normalize_email
       #
       # @return [String]
       def normalize_email
         self.email = self.class.normalize_email(email)
       end
     end
-
   end
 end
-

data/lib/authenticate/model/lifetimed.rb

@@ -2,7 +2,7 @@ require 'authenticate/callbacks/lifetimed'
 
 module Authenticate
   module Model
-
+    #
     # Imposes a maximum allowed lifespan on a user's session, after which the session is expired and requires
     # re-authentication.
     #
@@ -41,7 +41,6 @@ module Authenticate
       def max_session_lifetime
         Authenticate.configuration.max_session_lifetime
       end
-
     end
   end
 end

data/lib/authenticate/model/password_reset.rb

@@ -1,6 +1,5 @@
 module Authenticate
   module Model
-
     # Support 'forgot my password' functionality.
     #
     # = Columns
@@ -68,7 +67,7 @@ module Authenticate
       def reset_password_period_valid?
         reset_within = Authenticate.configuration.reset_password_within
         return true if reset_within.nil?
-        self.password_reset_sent_at &&  self.password_reset_sent_at.utc >= reset_within.ago.utc
+        password_reset_sent_at && password_reset_sent_at.utc >= reset_within.ago.utc
       end
 
       private
@@ -77,7 +76,6 @@ module Authenticate
         self.password_reset_token = nil
         self.password_reset_sent_at = nil
       end
-
     end
   end
 end

data/lib/authenticate/model/timeoutable.rb

@@ -2,7 +2,6 @@ require 'authenticate/callbacks/timeoutable'
 
 module Authenticate
   module Model
-
     # Expire user sessions that have not been accessed within a certain period of time.
     # Expired users will be asked for credentials again.
     #
@@ -27,24 +26,24 @@ module Authenticate
     # * timeout_in - look up timeout period in config, @return [ActiveSupport::CoreExtensions::Numeric::Time]
     #
     module Timeoutable
-        extend ActiveSupport::Concern
+      extend ActiveSupport::Concern
 
-        def self.required_fields(_klass)
-          [:last_access_at]
-        end
+      def self.required_fields(_klass)
+        [:last_access_at]
+      end
 
-        # Checks whether the user session has expired based on configured time.
-        def timedout?
-          return false if timeout_in.nil?
-          return false if last_access_at.nil?
-          last_access_at <= timeout_in.ago
-        end
+      # Checks whether the user session has expired based on configured time.
+      def timedout?
+        return false if timeout_in.nil?
+        return false if last_access_at.nil?
+        last_access_at <= timeout_in.ago
+      end
 
-        private
+      private
 
-        def timeout_in
-          Authenticate.configuration.timeout_in
-        end
+      def timeout_in
+        Authenticate.configuration.timeout_in
+      end
     end
   end
 end

data/lib/authenticate/model/trackable.rb

@@ -2,7 +2,7 @@ require 'authenticate/callbacks/trackable'
 
 module Authenticate
   module Model
-
+    #
     # Track information about your user sign ins. This module is always enabled.
     #
     # = Methods
@@ -24,11 +24,13 @@ module Authenticate
       end
 
       def update_tracked_fields(request)
-        old_current, new_current = self.current_sign_in_at, Time.now.utc
+        old_current = current_sign_in_at
+        new_current = Time.now.utc
         self.last_sign_in_at     = old_current || new_current
         self.current_sign_in_at  = new_current
 
-        old_current, new_current = self.current_sign_in_ip, request.remote_ip
+        old_current = current_sign_in_ip
+        new_current = request.remote_ip
         self.last_sign_in_ip     = old_current || new_current
         self.current_sign_in_ip  = new_current
 
@@ -40,7 +42,6 @@ module Authenticate
         update_tracked_fields(request)
         save(validate: false)
       end
-
     end
   end
 end

data/lib/authenticate/model/username.rb

@@ -1,6 +1,6 @@
 module Authenticate
   module Model
-
+    #
     # Use :username as the identifier for the user. Username must be unique.
     #
     # = Columns
@@ -11,7 +11,7 @@ module Authenticate
     #
     # = class methods
     # * credentials(params) - return the credentials required for authorization by username
-    # * authenticate(credentials) - find user with given username, validate their password, return the user if authenticated
+    # * authenticate(credentials) - find user with given username, validate their password, return user if authenticated
     # * find_by_credentials(credentials) - find and return the user with the username in the credentials
     #
     module Username
@@ -28,6 +28,7 @@ module Authenticate
                   uniqueness: { allow_blank: true }
       end
 
+      # Class methods for managing username-based authentication
       module ClassMethods
         def credentials(params)
           [params[:session][:username], params[:session][:password]]
@@ -42,10 +43,7 @@ module Authenticate
           username = credentials[0]
           find_by_username username
         end
-
       end
-
     end
-
   end
 end

data/lib/authenticate/modules.rb

@@ -1,80 +1,78 @@
 module Authenticate
+  #
+  # Modules injects Authenticate modules into the app User model.
+  #
+  # Any module being loaded into User can optionally define a class method `required_fields(klass)` defining
+  # any required attributes in the User model. For example, the :username module declares:
+  #
+  #   module Username
+  #     extend ActiveSupport::Concern
+  #
+  #     def self.required_fields(klass)
+  #       [:username]
+  #     end
+  #     ...
+  #
+  # If the model class is missing a required field, Authenticate will fail with a MissingAttribute error.
+  # The error will declare what required fields are missing.
   module Modules
     extend ActiveSupport::Concern
-
-    # Module to help Authenticate's user model load Authenticate modules.
-    #
-    # All Authenticate modules implement ActiveSupport::Concern.
-    #
-    # Modules can optionally define a class method to define what attributes they require present
-    # in the user model. For example, :username declares:
-    #
-    #   module Username
-    #     extend ActiveSupport::Concern
     #
-    #     def self.required_fields(klass)
-    #       [:username]
-    #     end
-    #     ...
+    # Class methods injected into User model.
     #
-    # If the model class is missing a required field, Authenticate will fail with a MissingAttribute error.
-    # The error will declare what required fields are missing.
     module ClassMethods
-
+      #
       # Load all modules declared in Authenticate.configuration.modules.
       # Requires them, then loads as a constant, then checks fields, and finally includes.
+      #
+      # @raise MissingAttribute if attributes required by Authenticate are missing.
       def load_modules
-        constants = []
+        modules_to_include = []
         Authenticate.configuration.modules.each do |mod|
-          # puts "load_modules about to load #{mod.to_s}"
-          require "authenticate/model/#{mod.to_s}" if mod.is_a?(Symbol)
+          # The built-in modules are referred to by symbol. Additional module classes (constants) can be added
+          # via Authenticate.configuration.modules.
+          require "authenticate/model/#{mod}" if mod.is_a?(Symbol)
           mod = load_constant(mod) if mod.is_a?(Symbol)
-          constants << mod
+          modules_to_include << mod
         end
-        check_fields constants
-        constants.each { |mod|
-          include mod
-        }
+        check_fields modules_to_include
+        modules_to_include.each { |mod| include mod }
       end
 
       private
 
-      def load_constant module_symbol
+      def load_constant(module_symbol)
         Authenticate::Model.const_get(module_symbol.to_s.classify)
       end
 
       # For each module, look at the fields it requires. Ensure the User
-      # model including the module has the required fields. If it does not
-      # have all required fields, huck an exception.
-      def check_fields modules
+      # model including the module has the required fields.
+      # @raise MissingAttribute if required attributes are missing.
+      def check_fields(modules)
         failed_attributes = []
-        instance = self.new
+        instance = new
         modules.each do |mod|
           if mod.respond_to?(:required_fields)
-            mod.required_fields(self).each do |field|
-              failed_attributes << field unless instance.respond_to?(field)
-            end
+            mod.required_fields(self).each { |field| failed_attributes << field unless instance.respond_to?(field) }
           end
         end
 
         if failed_attributes.any?
-          # fail MissingAttribute.new(failed_attributes)
-          Rails.logger.warn "The following attribute(s) is (are) missing on your user model: #{failed_attributes.join(", ")}"
+          raise MissingAttribute.new(failed_attributes),
+                "Required attribute are missing on your user model: #{failed_attributes.join(', ')}"
         end
       end
-
     end
 
+    # Thrown if required attributes are missing.
     class MissingAttribute < StandardError
       def initialize(attributes)
         @attributes = attributes
       end
 
       def message
-        "The following attribute(s) is (are) missing on your user model: #{@attributes.join(", ")}"
+        "Required attributes are missing on your user model: #{@attributes.join(', ')}"
       end
     end
-
   end
 end
-

data/lib/authenticate/session.rb

@@ -2,6 +2,7 @@ require 'authenticate/login_status'
 require 'authenticate/debug'
 
 module Authenticate
+  # Represents an Authenticate session.
   class Session
     include Debug
 
@@ -16,19 +17,19 @@ module Authenticate
 
     # Finish user login process, *after* the user has been authenticated.
     # Called when user creates an account or signs back into the app.
+    # Runs all callbacks checking for any login failure. If a login failure
+    # occurs, user is NOT logged in.
     #
     # @return [User]
-    def login(user, &block)
-      debug 'session.login()'
+    def login(user)
       @current_user = user
       @current_user.generate_session_token if user.present?
 
       message = catch(:failure) do
-        Authenticate.lifecycle.run_callbacks(:after_set_user, @current_user, self, { event: :authentication })
-        Authenticate.lifecycle.run_callbacks(:after_authentication, @current_user, self, { event: :authentication })
+        Authenticate.lifecycle.run_callbacks(:after_set_user, @current_user, self, event: :authentication)
+        Authenticate.lifecycle.run_callbacks(:after_authentication, @current_user, self, event: :authentication)
       end
 
-      debug "session.login after lifecycle callbacks, message: #{message}"
       status = message.present? ? Failure.new(message) : Success.new
       if status.success?
         @current_user.save
@@ -37,9 +38,7 @@ module Authenticate
         @current_user = nil
       end
 
-      if block_given?
-        block.call(status)
-      end
+      yield(status) if block_given?
     end
 
     # Get the user represented by this session.
@@ -47,9 +46,7 @@ module Authenticate
     # @return [User]
     def current_user
       debug 'session.current_user'
-      if @session_token.present?
-        @current_user ||= load_user
-      end
+      @current_user ||= load_user if @session_token.present?
       @current_user
     end
 
@@ -66,9 +63,7 @@ module Authenticate
     # @return [void]
     def deauthenticate
       # nuke session_token in db
-      if current_user.present?
-        current_user.reset_session_token!
-      end
+      current_user.reset_session_token! if current_user.present?
 
       # nuke notion of current_user
       @current_user = nil
@@ -87,16 +82,15 @@ module Authenticate
 
     def write_cookie
       cookie_hash = {
-          path: Authenticate.configuration.cookie_path,
-          secure: Authenticate.configuration.secure_cookie,
-          httponly: Authenticate.configuration.cookie_http_only,
-          value: @current_user.session_token,
-          expires: Authenticate.configuration.cookie_expiration.call
+        path: Authenticate.configuration.cookie_path,
+        secure: Authenticate.configuration.secure_cookie,
+        httponly: Authenticate.configuration.cookie_http_only,
+        value: @current_user.session_token,
+        expires: Authenticate.configuration.cookie_expiration.call
       }
       cookie_hash[:domain] = Authenticate.configuration.cookie_domain if Authenticate.configuration.cookie_domain
-      # @cookies.signed[cookie_name] = cookie_hash
+      # Consider adding an option for a signed cookie
       @cookies[cookie_name] = cookie_hash
-      debug 'session.write_cookie WROTE COOKIE I HOPE. Cookie guts:' + @cookies[cookie_name].inspect
     end
 
     def cookie_name
@@ -106,7 +100,5 @@ module Authenticate
     def load_user
       Authenticate.configuration.user_model_class.where(session_token: @session_token).first
     end
-
   end
 end
-

data/lib/authenticate/token.rb

@@ -1,4 +1,7 @@
 module Authenticate
+  #
+  # A secure token, consisting of a big random number.
+  #
   class Token
     def self.new
       SecureRandom.hex(20).encode('UTF-8')

data/lib/authenticate/user.rb

@@ -3,7 +3,6 @@ require 'authenticate/token'
 require 'authenticate/callbacks/authenticatable'
 
 module Authenticate
-
   # Required to be included in your configured user class, which is `User` by
   # default, but can be changed with {Configuration#user_model=}.
   #
@@ -52,8 +51,8 @@ module Authenticate
       save validate: false
     end
 
+    # Class methods added to users.
     module ClassMethods
-
       def normalize_email(email)
         email.to_s.downcase.gsub(/\s+/, '')
       end
@@ -62,9 +61,6 @@ module Authenticate
       def find_by_normalized_email(email)
         find_by_email normalize_email(email)
       end
-
-      end
-
+    end
   end
 end
-