authenticate 0.1.0 → 0.2.0

data/lib/authenticate/controller.rb

@@ -40,7 +40,7 @@ module Authenticate
     end
 
 
-    # Use this as a before_action to restrict controller actions to authenticated users.
+    # Use this filter as a before_action to restrict controller actions to authenticated users.
     # Consider using in application_controller to restrict access to all controllers.
     #
     # Example:
@@ -89,22 +89,82 @@ module Authenticate
       authenticate_session.current_user
     end
 
-    private
-
-    def authenticate_session
-      @authenticate_session ||= Authenticate::Session.new(request, cookies)
-    end
+    protected
 
-    def unauthorized(msg = 'You must sign in')
+    # User is not authorized, bounce 'em to sign in
+    def unauthorized(msg = 'You must sign in') # get default message from locale
       respond_to do |format|
         format.any(:js, :json, :xml) { head :unauthorized }
         format.any {
-          flash[:notice] = msg  # TODO use locales
-          redirect_to '/authenticate' #TODO something better baby
+          redirect_unauthorized(msg)
+        }
+      end
+    end
+
+    def redirect_unauthorized(flash_message)
+      store_location
+
+      if flash_message
+        flash[:notice] = flash_message  # TODO use locales
+      end
+
+      if authenticated?
+        redirect_to url_after_denied_access_when_signed_in
+      else
+        redirect_to url_after_denied_access_when_signed_out
+      end
+    end
+
+
+    def redirect_back_or(default)
+      redirect_to(stored_location || default)
+      clear_stored_location
+    end
+
+
+    # Used as the redirect location when {#unauthorized} is called and there is a
+    # currently signed in user.
+    #
+    # @return [String]
+    def url_after_denied_access_when_signed_in
+      Authenticate.configuration.redirect_url
+    end
+
+    # Used as the redirect location when {#unauthorized} is called and there is
+    # no currently signed in user.
+    #
+    # @return [String]
+    def url_after_denied_access_when_signed_out
+      sign_in_url
+    end
+
+    private
+
+    # Write location to return to in a cookie. This is 12-factor compliant, cloud-safe.
+    def store_location
+      if request.get?
+        value = {
+            expires: nil,
+            httponly: true,
+            path: nil,
+            secure: Authenticate.configuration.secure_cookie,
+            value: request.original_fullpath
         }
+        cookies[:authenticate_return_to] = value
       end
     end
 
+    def stored_location
+      cookies[:authenticate_return_to]
+    end
+
+    def clear_stored_location
+      cookies.delete :authenticate_return_to
+    end
+
+    def authenticate_session
+      @authenticate_session ||= Authenticate::Session.new(request, cookies)
+    end
 
   end
 end

data/lib/authenticate/debug.rb

@@ -3,6 +3,7 @@ module Authenticate
     extend ActiveSupport::Concern
 
     def d(msg)
+      # todo check: Rails constant loaded? Authenticate config read? do a puts otherwise
       Rails.logger.info msg.to_s if Authenticate.configuration.debug
     end
 

data/lib/authenticate/engine.rb

@@ -1,20 +1,13 @@
 module Authenticate
   class Engine < ::Rails::Engine
-    # config.generators do |g|
-    #   g.test_framework :rspec
-    #   g.fixture_replacement :factory_girl, dir: 'spec/factories'
-    # end
 
-    # viget
+    initializer 'authenticate.filter' do |app|
+      app.config.filter_parameters += [:password, :token]
+    end
+
     config.generators do |g|
       g.test_framework :rspec
       g.fixture_replacement :factory_girl, dir: 'spec/factories'
-
-
-      # g.test_framework      :rspec,        fixture: false
-      # g.fixture_replacement :factory_girl, dir: 'spec/factories'
-      # g.assets false
-      # g.helper false
     end
 
   end

data/lib/authenticate/model/brute_force.rb

@@ -4,9 +4,28 @@ module Authenticate
   module Model
 
 
-    # Protect from brute force attacks.
-    # Lock accounts that have too many failed consecutive logins.
-    # Todo: email user to allow faster unlocking via token.
+    # Protect from brute force attacks. Lock accounts that have too many failed consecutive logins.
+    # Todo: email user to allow unlocking via a token.
+    #
+    # = Columns
+    #
+    # * failed_logins_count - each consecutive failed login increments this counter. Set back to 0 on successful login.
+    # * lock_expires_at - datetime a locked account will again become available.
+    #
+    # = Configuration
+    #
+    # * max_consecutive_bad_logins_allowed - how many failed logins are allowed?
+    # * bad_login_lockout_period - how long is the user locked out? nil indicates forever.
+    #
+    # = Methods
+    #
+    # The following methods are added to your user model:
+    # * register_failed_login! - increment failed_logins_count, lock account if in violation
+    # * lock! - lock the account, setting the lock_expires_at attribute
+    # * unlock! - reset failed_logins_count to 0, lock_expires_at to nil
+    # * locked? - is the account locked? @return[Boolean]
+    # * unlocked? - is the account unlocked? @return[Boolean]
+    #
     module BruteForce
       extend ActiveSupport::Concern
 

data/lib/authenticate/model/db_password.rb

@@ -4,19 +4,26 @@ require 'authenticate/crypto/bcrypt'
 module Authenticate
   module Model
 
-    # Encrypts and stores a password in the database to validate the authenticity of a user while signing in.
+    # Encrypts and stores a password in the database to validate the authenticity of a user while logging in.
     #
     # Authenticate can plug in any crypto provider, but currently only features BCrypt.
+    # A crypto provider must provide:
+    # * encrypt(secret) - encrypt the secret, @return [String]
+    # * match?(secret, encrypted) - does the secret match the encrypted? @return [Boolean]
+    #
+    # = Columns
+    #
+    # * encrypted_password - the user's password, encrypted
     #
     # = Methods
     #
     # The following methods are added to your user model:
-    # - password_match?(password) - checks to see if the user's password matches the given password
-    # - password=(new_password) - encrypt and set the user password
+    # * password=(new_password) - encrypt and set the user password
+    # * password_match?(password) - checks to see if the user's password matches the given password
     #
     # = Validations
     #
-    # - :password validation, requiring the password is set
+    # * :password validation, requiring the password is set unless we're skipping due to a password change
     #
     module DbPassword
       extend ActiveSupport::Concern
@@ -36,8 +43,7 @@ module Authenticate
 
       module ClassMethods
 
-        # We only have one crypto provider at the moment, but this is a pluggable point
-        # to install different crypto.
+        # We only have one crypto provider at the moment, but look up the provider in the config.
         def crypto_provider
           Authenticate.configuration.crypto_provider || Authenticate::Crypto::BCrypt
         end
@@ -45,7 +51,6 @@ module Authenticate
       end
 
 
-
       def password_match?(password)
         match?(password, self.encrypted_password)
       end

data/lib/authenticate/model/email.rb

@@ -3,24 +3,24 @@ require 'email_validator'
 module Authenticate
   module Model
 
-    # Use :email as the identifier for the user. Must be unique to the system.
+    # Use :email as the identifier for the user. Email must be unique.
     #
     # = Columns
-    # - :email containing the email address of the user
+    # * email - the email address of the user
     #
     # = Validations
-    # - :email requires email is set, validations the format, and ensure it is unique
+    # * :email - require email is set, is a valid format, and is unique
     #
     # = Callbacks
-    # - :normalize_email - normalize the email, removing spaces etc, before saving
     #
     # = Methods
-    # - :email - require the email address is set and is a valid format
+    # * normalize_email - normalize the email, removing spaces etc, before saving
     #
     # = class methods
-    # - authenticate(email, password) - find user with given email, validate their password, return the user.
-    # - normalize_email(email) - clean up the given email and return it.
-    # - find_by_normalized_email(email) - normalize the given email, then look for the user with that email.
+    # * 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
+    # * 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
     #
     module Email
       extend ActiveSupport::Concern
@@ -41,7 +41,6 @@ module Authenticate
       module ClassMethods
 
         def credentials(params)
-          # todo closure from configuration
           [params[:session][:email], params[:session][:password]]
         end
 
@@ -52,7 +51,6 @@ module Authenticate
 
         def find_by_credentials(credentials)
           email = credentials[0]
-          puts "find_by_credentials email: #{email}"
           find_by_email normalize_email(email)
         end
 

data/lib/authenticate/model/password_reset.rb

@@ -0,0 +1,76 @@
+module Authenticate
+  module Model
+
+    # Support 'forgot my password' functionality.
+    # Methods:
+    # * update_password(new_password) - call password setter below, generate a new session token if user.valid?, & save
+    # *
+
+    module PasswordReset
+      extend ActiveSupport::Concern
+
+      def self.required_fields(klass)
+        [:password_reset_token, :password_reset_sent_at, :email]
+      end
+
+      # Sets the user's password to the new value. The new password will be encrypted with
+      # the selected encryption scheme (defaults to Bcrypt).
+      #
+      # Updating the user password also generates a new session token.
+      #
+      # Validations will be run as part of this update. If the user instance is
+      # not valid, the password change will not be persisted, and this method will
+      # return `false`.
+      #
+      # @return [Boolean] Was the save successful?
+      def update_password(new_password)
+        return false unless reset_password_period_valid?
+
+        self.password_changing = true
+        self.password = new_password
+
+        if valid?
+          clear_reset_password_token
+          generate_session_token
+        end
+
+        save
+      end
+
+      # Generates a {#password_reset_token} for the user, which allows them to reset
+      # their password via an email link.
+      #
+      # The user model is saved without validations. Any other changes you made to
+      # this user instance will also be persisted, without validation.
+      # It is intended to be called on an instance with no changes (`dirty? == false`).
+      #
+      # @return [Boolean] Was the save successful?
+      def forgot_password!
+        self.password_reset_token = Authenticate::Token.new
+        self.password_reset_sent_at = Time.now.utc
+        save validate: false
+      end
+
+      # Checks if the reset password token is within the time limit.
+      # If the application's reset_password_within is nil, then always return true.
+      #
+      # Example:
+      #   # reset_password_within = 1.day and reset_password_sent_at = today
+      #   reset_password_period_valid?   # returns true
+      #
+      def reset_password_period_valid?
+        reset_within = Authenticate.configuration.reset_password_within.ago.utc
+        return true if reset_within.nil?
+        self.password_reset_sent_at &&  self.password_reset_sent_at.utc >= reset_within
+      end
+
+      private
+
+      def clear_reset_password_token
+        self.password_reset_token = nil
+        self.password_reset_sent_at = nil
+      end
+
+    end
+  end
+end

data/lib/authenticate/model/timeoutable.rb

@@ -6,12 +6,14 @@ module Authenticate
     # Expire user sessions that have not been accessed within a certain period of time.
     # Expired users will be asked for credentials again.
     #
-    # == Columns
+    # = Columns
     #
     # This module expects and tracks this column on your user model:
-    # - last_access_at - timestamp of the last access by the user
+    # * last_access_at - datetime of the last access by the user
     #
-    # == Configuration
+    # = Configuration
+    #
+    # * timeout_in - maximum idle time allowed before session is invalidated. nil shuts off this feature.
     #
     # Timeoutable is enabled and configured with the `timeout_in` configuration parameter.
     # `timeout_in` expects a timestamp. Example:
@@ -22,6 +24,10 @@ module Authenticate
     #
     # You must specify a non-nil timeout_in in your initializer to enable Timeoutable.
     #
+    # = Methods
+    # * timedout? - has this user timed out? @return[Boolean]
+    # * timeout_in - look up timeout period in config, @return [ActiveSupport::CoreExtensions::Numeric::Time]
+    #
     module Timeoutable
         extend ActiveSupport::Concern
 

data/lib/authenticate/model/trackable.rb

@@ -7,7 +7,7 @@ module Authenticate
     #
     # == Columns
     # This module expects and tracks the following columns on your user model:
-    # - sign_in_count - increase every time a sign in is made
+    # - sign_in_count - increase every time a sign in is successful
     # - current_sign_in_at - a timestamp updated at each sign in
     # - last_sign_in_at - a timestamp of the previous sign in
     # - current_sign_in_ip - the remote ip address of the user at sign in

data/lib/authenticate/model/username.rb

@@ -1,6 +1,19 @@
 module Authenticate
   module Model
 
+    # Use :username as the identifier for the user. Username must be unique.
+    #
+    # = Columns
+    # * username - the username of your user
+    #
+    # = Validations
+    # * :username requires username is set, ensure it is unique
+    #
+    # = 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
+    # * find_by_credentials(credentials) - find and return the user with the username in the credentials
+    #
     module Username
       extend ActiveSupport::Concern
 
@@ -9,7 +22,7 @@ module Authenticate
       end
 
       included do
-        before_validation :normalize_username
+        # before_validation :normalize_username
         validates :username,
                   presence: true,
                   uniqueness: { allow_blank: true }
@@ -27,17 +40,17 @@ module Authenticate
 
         def find_by_credentials(credentials)
           username = credentials[0]
-          find_by_username normalize_username(username)
+          find_by_username username
         end
 
-        def normalize_username(username)
-          username.to_s.downcase.gsub(/\s+/, '')
-        end
+        # def normalize_username(username)
+        #   username.to_s.downcase.gsub(/\s+/, '')
+        # end
       end
 
-      def normalize_username
-        self.username = self.class.normalize_username(username)
-      end
+      # def normalize_username
+      #   self.username = self.class.normalize_username(username)
+      # end
 
     end
 

data/lib/authenticate/modules.rb

@@ -2,9 +2,27 @@ module Authenticate
   module Modules
     extend ActiveSupport::Concern
 
-    # Methods to help your user model load Authenticate modules
+    # 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
+    #     ...
+    #
+    # 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.
       def load_modules
         constants = []
         Authenticate.configuration.modules.each do |mod|