kingsman 0.0.0.beta → 0.1.0

data/lib/kingsman/models/lockable.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require "kingsman/hooks/lockable"
+
+module Kingsman
+  module Models
+    # Handles blocking a user access after a certain number of attempts.
+    # Lockable accepts two different strategies to unlock a user after it's
+    # blocked: email and time. The former will send an email to the user when
+    # the lock happens, containing a link to unlock its account. The second
+    # will unlock the user automatically after some configured time (ie 2.hours).
+    # It's also possible to set up lockable to use both email and time strategies.
+    #
+    # == Options
+    #
+    # Lockable adds the following options to +kingsman+:
+    #
+    #   * +maximum_attempts+: how many attempts should be accepted before blocking the user.
+    #   * +lock_strategy+: lock the user account by :failed_attempts or :none.
+    #   * +unlock_strategy+: unlock the user account by :time, :email, :both or :none.
+    #   * +unlock_in+: the time you want to unlock the user after lock happens. Only available when unlock_strategy is :time or :both.
+    #   * +unlock_keys+: the keys you want to use when locking and unlocking an account
+    #
+    module Lockable
+      extend  ActiveSupport::Concern
+
+      delegate :lock_strategy_enabled?, :unlock_strategy_enabled?, to: "self.class"
+
+      def self.required_fields(klass)
+        attributes = []
+        attributes << :failed_attempts if klass.lock_strategy_enabled?(:failed_attempts)
+        attributes << :locked_at if klass.unlock_strategy_enabled?(:time)
+        attributes << :unlock_token if klass.unlock_strategy_enabled?(:email)
+
+        attributes
+      end
+
+      # Lock a user setting its locked_at to actual time.
+      # * +opts+: Hash options if you don't want to send email
+      #   when you lock access, you could pass the next hash
+      #   `{ send_instructions: false } as option`.
+      def lock_access!(opts = { })
+        self.locked_at = Time.now.utc
+
+        if unlock_strategy_enabled?(:email) && opts.fetch(:send_instructions, true)
+          send_unlock_instructions
+        else
+          save(validate: false)
+        end
+      end
+
+      # Unlock a user by cleaning locked_at and failed_attempts.
+      def unlock_access!
+        self.locked_at = nil
+        self.failed_attempts = 0 if respond_to?(:failed_attempts=)
+        self.unlock_token = nil  if respond_to?(:unlock_token=)
+        save(validate: false)
+      end
+
+      # Resets failed attempts counter to 0.
+      def reset_failed_attempts!
+        if respond_to?(:failed_attempts) && !failed_attempts.to_i.zero?
+          self.failed_attempts = 0
+          save(validate: false)
+        end
+      end
+
+      # Verifies whether a user is locked or not.
+      def access_locked?
+        !!locked_at && !lock_expired?
+      end
+
+      # Send unlock instructions by email
+      def send_unlock_instructions
+        raw, enc = Kingsman.token_generator.generate(self.class, :unlock_token)
+        self.unlock_token = enc
+        save(validate: false)
+        send_kingsman_notification(:unlock_instructions, raw, {})
+        raw
+      end
+
+      # Resend the unlock instructions if the user is locked.
+      def resend_unlock_instructions
+        if_access_locked { send_unlock_instructions }
+      end
+
+      # Overwrites active_for_authentication? from Kingsman::Models::Activatable for locking purposes
+      # by verifying whether a user is active to sign in or not based on locked?
+      def active_for_authentication?
+        super && !access_locked?
+      end
+
+      # Overwrites invalid_message from Kingsman::Models::Authenticatable to define
+      # the correct reason for blocking the sign in.
+      def inactive_message
+        access_locked? ? :locked : super
+      end
+
+      # Overwrites valid_for_authentication? from Kingsman::Models::Authenticatable
+      # for verifying whether a user is allowed to sign in or not. If the user
+      # is locked, it should never be allowed.
+      def valid_for_authentication?
+        return super unless persisted? && lock_strategy_enabled?(:failed_attempts)
+
+        # Unlock the user if the lock is expired, no matter
+        # if the user can login or not (wrong password, etc)
+        unlock_access! if lock_expired?
+
+        if super && !access_locked?
+          true
+        else
+          increment_failed_attempts
+          if attempts_exceeded?
+            lock_access! unless access_locked?
+          else
+            save(validate: false)
+          end
+          false
+        end
+      end
+
+      def increment_failed_attempts
+        self.class.increment_counter(:failed_attempts, id)
+        reload
+      end
+
+      def unauthenticated_message
+        # If set to paranoid mode, do not show the locked message because it
+        # leaks the existence of an account.
+        if Kingsman.paranoid
+          super
+        elsif access_locked? || (lock_strategy_enabled?(:failed_attempts) && attempts_exceeded?)
+          :locked
+        elsif lock_strategy_enabled?(:failed_attempts) && last_attempt? && self.class.last_attempt_warning
+          :last_attempt
+        else
+          super
+        end
+      end
+
+      protected
+
+        def attempts_exceeded?
+          self.failed_attempts >= self.class.maximum_attempts
+        end
+
+        def last_attempt?
+          self.failed_attempts == self.class.maximum_attempts - 1
+        end
+
+        # Tells if the lock is expired if :time unlock strategy is active
+        def lock_expired?
+          if unlock_strategy_enabled?(:time)
+            locked_at && locked_at < self.class.unlock_in.ago
+          else
+            false
+          end
+        end
+
+        # Checks whether the record is locked or not, yielding to the block
+        # if it's locked, otherwise adds an error to email.
+        def if_access_locked
+          if access_locked?
+            yield
+          else
+            self.errors.add(Kingsman.unlock_keys.first, :not_locked)
+            false
+          end
+        end
+
+      module ClassMethods
+        # List of strategies that are enabled/supported if :both is used.
+        BOTH_STRATEGIES = [:time, :email]
+
+        # Attempt to find a user by its unlock keys. If a record is found, send new
+        # unlock instructions to it. If not user is found, returns a new user
+        # with an email not found error.
+        # Options must contain the user's unlock keys
+        def send_unlock_instructions(attributes = {})
+          lockable = find_or_initialize_with_errors(unlock_keys, attributes, :not_found)
+          lockable.resend_unlock_instructions if lockable.persisted?
+          lockable
+        end
+
+        # Find a user by its unlock token and try to unlock it.
+        # If no user is found, returns a new user with an error.
+        # If the user is not locked, creates an error for the user
+        # Options must have the unlock_token
+        def unlock_access_by_token(unlock_token)
+          original_token = unlock_token
+          unlock_token   = Kingsman.token_generator.digest(self, :unlock_token, unlock_token)
+
+          lockable = find_or_initialize_with_error_by(:unlock_token, unlock_token)
+          lockable.unlock_access! if lockable.persisted?
+          lockable.unlock_token = original_token
+          lockable
+        end
+
+        # Is the unlock enabled for the given unlock strategy?
+        def unlock_strategy_enabled?(strategy)
+          self.unlock_strategy == strategy ||
+            (self.unlock_strategy == :both && BOTH_STRATEGIES.include?(strategy))
+        end
+
+        # Is the lock enabled for the given lock strategy?
+        def lock_strategy_enabled?(strategy)
+          self.lock_strategy == strategy
+        end
+
+        Kingsman::Models.config(self, :maximum_attempts, :lock_strategy, :unlock_strategy, :unlock_in, :unlock_keys, :last_attempt_warning)
+      end
+    end
+  end
+end

data/lib/kingsman/models/omniauthable.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'kingsman/omniauth'
+
+module Kingsman
+  module Models
+    # Adds OmniAuth support to your model.
+    #
+    # == Options
+    #
+    # Oauthable adds the following options to +kingsman+:
+    #
+    #   * +omniauth_providers+: Which providers are available to this model. It expects an array:
+    #
+    #       kingsman :database_authenticatable, :omniauthable, omniauth_providers: [:twitter]
+    #
+    module Omniauthable
+      extend ActiveSupport::Concern
+
+      def self.required_fields(klass)
+        []
+      end
+
+      module ClassMethods
+        Kingsman::Models.config(self, :omniauth_providers)
+      end
+    end
+  end
+end

data/lib/kingsman/models/recoverable.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module Kingsman
+  module Models
+
+    # Recoverable takes care of resetting the user password and send reset instructions.
+    #
+    # ==Options
+    #
+    # Recoverable adds the following options to +kingsman+:
+    #
+    #   * +reset_password_keys+: the keys you want to use when recovering the password for an account
+    #   * +reset_password_within+: the time period within which the password must be reset or the token expires.
+    #   * +sign_in_after_reset_password+: whether or not to sign in the user automatically after a password reset.
+    #
+    # == Examples
+    #
+    #   # resets the user password and save the record, true if valid passwords are given, otherwise false
+    #   User.find(1).reset_password('password123', 'password123')
+    #
+    #   # creates a new token and send it with instructions about how to reset the password
+    #   User.find(1).send_reset_password_instructions
+    #
+    module Recoverable
+      extend ActiveSupport::Concern
+
+      def self.required_fields(klass)
+        [:reset_password_sent_at, :reset_password_token]
+      end
+
+      included do
+        before_update :clear_reset_password_token, if: :clear_reset_password_token?
+      end
+
+      # Update password saving the record and clearing token. Returns true if
+      # the passwords are valid and the record was saved, false otherwise.
+      def reset_password(new_password, new_password_confirmation)
+        if new_password.present?
+          self.password = new_password
+          self.password_confirmation = new_password_confirmation
+          save
+        else
+          errors.add(:password, :blank)
+          false
+        end
+      end
+
+      # Resets reset password token and send reset password instructions by email.
+      # Returns the token sent in the e-mail.
+      def send_reset_password_instructions
+        token = set_reset_password_token
+        send_reset_password_instructions_notification(token)
+
+        token
+      end
+
+      # Checks if the reset password token sent is within the limit time.
+      # We do this by calculating if the difference between today and the
+      # sending date does not exceed the confirm in time configured.
+      # Returns true if the resource is not responding to reset_password_sent_at at all.
+      # reset_password_within is a model configuration, must always be an integer value.
+      #
+      # Example:
+      #
+      #   # reset_password_within = 1.day and reset_password_sent_at = today
+      #   reset_password_period_valid?   # returns true
+      #
+      #   # reset_password_within = 5.days and reset_password_sent_at = 4.days.ago
+      #   reset_password_period_valid?   # returns true
+      #
+      #   # reset_password_within = 5.days and reset_password_sent_at = 5.days.ago
+      #   reset_password_period_valid?   # returns false
+      #
+      #   # reset_password_within = 0.days
+      #   reset_password_period_valid?   # will always return false
+      #
+      def reset_password_period_valid?
+        reset_password_sent_at && reset_password_sent_at.utc >= self.class.reset_password_within.ago.utc
+      end
+
+      protected
+
+        # Removes reset_password token
+        def clear_reset_password_token
+          self.reset_password_token = nil
+          self.reset_password_sent_at = nil
+        end
+
+        def set_reset_password_token
+          raw, enc = Kingsman.token_generator.generate(self.class, :reset_password_token)
+
+          self.reset_password_token   = enc
+          self.reset_password_sent_at = Time.now.utc
+          save(validate: false)
+          raw
+        end
+
+        def send_reset_password_instructions_notification(token)
+          send_kingsman_notification(:reset_password_instructions, token, {})
+        end
+
+        def clear_reset_password_token?
+          encrypted_password_changed = kingsman_respond_to_and_will_save_change_to_attribute?(:encrypted_password)
+          authentication_keys_changed = self.class.authentication_keys.any? do |attribute|
+            kingsman_respond_to_and_will_save_change_to_attribute?(attribute)
+          end
+
+          authentication_keys_changed || encrypted_password_changed
+        end
+
+      module ClassMethods
+        # Attempt to find a user by password reset token. If a user is found, return it
+        # If a user is not found, return nil
+        def with_reset_password_token(token)
+          reset_password_token = Kingsman.token_generator.digest(self, :reset_password_token, token)
+          to_adapter.find_first(reset_password_token: reset_password_token)
+        end
+
+        # Attempt to find a user by its email. If a record is found, send new
+        # password instructions to it. If user is not found, returns a new user
+        # with an email not found error.
+        # Attributes must contain the user's email
+        def send_reset_password_instructions(attributes = {})
+          recoverable = find_or_initialize_with_errors(reset_password_keys, attributes, :not_found)
+          recoverable.send_reset_password_instructions if recoverable.persisted?
+          recoverable
+        end
+
+        # Attempt to find a user by its reset_password_token to reset its
+        # password. If a user is found and token is still valid, reset its password and automatically
+        # try saving the record. If not user is found, returns a new user
+        # containing an error in reset_password_token attribute.
+        # Attributes must contain reset_password_token, password and confirmation
+        def reset_password_by_token(attributes = {})
+          original_token       = attributes[:reset_password_token]
+          reset_password_token = Kingsman.token_generator.digest(self, :reset_password_token, original_token)
+
+          recoverable = find_or_initialize_with_error_by(:reset_password_token, reset_password_token)
+
+          if recoverable.persisted?
+            if recoverable.reset_password_period_valid?
+              recoverable.reset_password(attributes[:password], attributes[:password_confirmation])
+            else
+              recoverable.errors.add(:reset_password_token, :expired)
+            end
+          end
+
+          recoverable.reset_password_token = original_token if recoverable.reset_password_token.present?
+          recoverable
+        end
+
+        Kingsman::Models.config(self, :reset_password_keys, :reset_password_within, :sign_in_after_reset_password)
+      end
+    end
+  end
+end

data/lib/kingsman/models/registerable.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Kingsman
+  module Models
+    # Registerable is responsible for everything related to registering a new
+    # resource (ie user sign up).
+    module Registerable
+      extend ActiveSupport::Concern
+
+      def self.required_fields(klass)
+        []
+      end
+
+      module ClassMethods
+        # A convenience method that receives both parameters and session to
+        # initialize a user. This can be used by OAuth, for example, to send
+        # in the user token and be stored on initialization.
+        #
+        # By default discards all information sent by the session by calling
+        # new with params.
+        def new_with_session(params, session)
+          new(params)
+        end
+
+        Kingsman::Models.config(self, :sign_in_after_change_password)
+      end
+    end
+  end
+end

data/lib/kingsman/models/rememberable.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require 'kingsman/strategies/rememberable'
+require 'kingsman/hooks/rememberable'
+require 'kingsman/hooks/forgetable'
+
+module Kingsman
+  module Models
+    # Rememberable manages generating and clearing token for remembering the user
+    # from a saved cookie. Rememberable also has utility methods for dealing
+    # with serializing the user into the cookie and back from the cookie, trying
+    # to lookup the record based on the saved information.
+    # You probably wouldn't use rememberable methods directly, they are used
+    # mostly internally for handling the remember token.
+    #
+    # == Options
+    #
+    # Rememberable adds the following options to +kingsman+:
+    #
+    #   * +remember_for+: the time you want the user will be remembered without
+    #     asking for credentials. After this time the user will be blocked and
+    #     will have to enter their credentials again. This configuration is also
+    #     used to calculate the expires time for the cookie created to remember
+    #     the user. By default remember_for is 2.weeks.
+    #
+    #   * +extend_remember_period+: if true, extends the user's remember period
+    #     when remembered via cookie. False by default.
+    #
+    #   * +rememberable_options+: configuration options passed to the created cookie.
+    #
+    # == Examples
+    #
+    #   User.find(1).remember_me!  # regenerating the token
+    #   User.find(1).forget_me!    # clearing the token
+    #
+    #   # generating info to put into cookies
+    #   User.serialize_into_cookie(user)
+    #
+    #   # lookup the user based on the incoming cookie information
+    #   User.serialize_from_cookie(cookie_string)
+    module Rememberable
+      extend ActiveSupport::Concern
+
+      attr_accessor :remember_me
+
+      def self.required_fields(klass)
+        [:remember_created_at]
+      end
+
+      def remember_me!
+        self.remember_token ||= self.class.remember_token if respond_to?(:remember_token)
+        self.remember_created_at ||= Time.now.utc
+        save(validate: false) if self.changed?
+      end
+
+      # If the record is persisted, remove the remember token (but only if
+      # it exists), and save the record without validations.
+      def forget_me!
+        return unless persisted?
+        self.remember_token = nil if respond_to?(:remember_token)
+        self.remember_created_at = nil if self.class.expire_all_remember_me_on_sign_out
+        save(validate: false)
+      end
+
+      def remember_expires_at
+        self.class.remember_for.from_now
+      end
+
+      def extend_remember_period
+        self.class.extend_remember_period
+      end
+
+      def rememberable_value
+        if respond_to?(:remember_token)
+          remember_token
+        elsif respond_to?(:authenticatable_salt) && (salt = authenticatable_salt.presence)
+          salt
+        else
+          raise "authenticatable_salt returned nil for the #{self.class.name} model. " \
+            "In order to use rememberable, you must ensure a password is always set " \
+            "or have a remember_token column in your model or implement your own " \
+            "rememberable_value in the model with custom logic."
+        end
+      end
+
+      def rememberable_options
+        self.class.rememberable_options
+      end
+
+      # A callback initiated after successfully being remembered. This can be
+      # used to insert your own logic that is only run after the user is
+      # remembered.
+      #
+      # Example:
+      #
+      #   def after_remembered
+      #     self.update_attribute(:invite_code, nil)
+      #   end
+      #
+      def after_remembered
+      end
+
+      def remember_me?(token, generated_at)
+        # TODO: Normalize the JSON type coercion along with the Timeoutable hook
+        # in a single place https://github.com/heartcombo/kingsman/blob/ffe9d6d406e79108cf32a2c6a1d0b3828849c40b/lib/kingsman/hooks/timeoutable.rb#L14-L18
+        if generated_at.is_a?(String)
+          generated_at = time_from_json(generated_at)
+        end
+
+        # The token is only valid if:
+        # 1. we have a date
+        # 2. the current time does not pass the expiry period
+        # 3. the record has a remember_created_at date
+        # 4. the token date is bigger than the remember_created_at
+        # 5. the token matches
+        generated_at.is_a?(Time) &&
+         (self.class.remember_for.ago < generated_at) &&
+         (generated_at > (remember_created_at || Time.now).utc) &&
+         Kingsman.secure_compare(rememberable_value, token)
+      end
+
+      private
+
+      def time_from_json(value)
+        if value =~ /\A\d+\.\d+\Z/
+          Time.at(value.to_f)
+        else
+          Time.parse(value) rescue nil
+        end
+      end
+
+      module ClassMethods
+        # Create the cookie key using the record id and remember_token
+        def serialize_into_cookie(record)
+          [record.to_key, record.rememberable_value, Time.now.utc.to_f.to_s]
+        end
+
+        # Recreate the user based on the stored cookie
+        def serialize_from_cookie(*args)
+          id, token, generated_at = *args
+
+          record = to_adapter.get(id)
+          record if record && record.remember_me?(token, generated_at)
+        end
+
+        # Generate a token checking if one does not already exist in the database.
+        def remember_token #:nodoc:
+          loop do
+            token = Kingsman.friendly_token
+            break token unless to_adapter.find_first({ remember_token: token })
+          end
+        end
+
+        Kingsman::Models.config(self, :remember_for, :extend_remember_period, :rememberable_options, :expire_all_remember_me_on_sign_out)
+      end
+    end
+  end
+end

data/lib/kingsman/models/timeoutable.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'kingsman/hooks/timeoutable'
+
+module Kingsman
+  module Models
+    # Timeoutable takes care of verifying whether a user session has already
+    # expired or not. When a session expires after the configured time, the user
+    # will be asked for credentials again, it means, they will be redirected
+    # to the sign in page.
+    #
+    # == Options
+    #
+    # Timeoutable adds the following options to +kingsman+:
+    #
+    #   * +timeout_in+: the interval to timeout the user session without activity.
+    #
+    # == Examples
+    #
+    #   user.timedout?(30.minutes.ago)
+    #
+    module Timeoutable
+      extend ActiveSupport::Concern
+
+      def self.required_fields(klass)
+        []
+      end
+
+      # Checks whether the user session has expired based on configured time.
+      def timedout?(last_access)
+        !timeout_in.nil? && last_access && last_access <= timeout_in.ago
+      end
+
+      def timeout_in
+        self.class.timeout_in
+      end
+
+      private
+
+      module ClassMethods
+        Kingsman::Models.config(self, :timeout_in)
+      end
+    end
+  end
+end

data/lib/kingsman/models/trackable.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'kingsman/hooks/trackable'
+
+module Kingsman
+  module Models
+    # Track information about your user sign in. It tracks the following columns:
+    #
+    # * sign_in_count      - Increased every time a sign in is made (by form, openid, oauth)
+    # * current_sign_in_at - A timestamp updated when the user signs in
+    # * last_sign_in_at    - Holds the timestamp of the previous sign in
+    # * current_sign_in_ip - The remote ip updated when the user sign in
+    # * last_sign_in_ip    - Holds the remote ip of the previous sign in
+    #
+    module Trackable
+      def self.required_fields(klass)
+        [:current_sign_in_at, :current_sign_in_ip, :last_sign_in_at, :last_sign_in_ip, :sign_in_count]
+      end
+
+      def update_tracked_fields(request)
+        old_current, new_current = self.current_sign_in_at, 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, extract_ip_from(request)
+        self.last_sign_in_ip     = old_current || new_current
+        self.current_sign_in_ip  = new_current
+
+        self.sign_in_count ||= 0
+        self.sign_in_count += 1
+      end
+
+      def update_tracked_fields!(request)
+        # We have to check if the user is already persisted before running
+        # `save` here because invalid users can be saved if we don't.
+        # See https://github.com/heartcombo/kingsman/issues/4673 for more details.
+        return if new_record?
+
+        update_tracked_fields(request)
+        save(validate: false)
+      end
+
+      protected
+
+      def extract_ip_from(request)
+        request.remote_ip
+      end
+
+    end
+  end
+end