authentication-logic 0.1.0

data/lib/auth/logic/session/base.rb

@@ -0,0 +1,2205 @@
+# frozen_string_literal: true
+
+require "request_store"
+
+module Authentication
+  module Logic
+    module Session
+      module Activation
+        # :nodoc:
+        class NotActivatedError < ::StandardError
+          def initialize
+            super(
+              "You must activate the Authentication::Logic::Session::Base.controller with " \
+                  "a controller object before creating objects"
+            )
+          end
+        end
+      end
+
+      module Existence
+        # :nodoc:
+        class SessionInvalidError < ::StandardError
+          def initialize(session)
+            message = I18n.t(
+              "error_messages.session_invalid",
+              default: "Your session is invalid and has the following errors:"
+            )
+            message += " #{session.errors.full_messages.to_sentence}"
+            super message
+          end
+        end
+      end
+
+      # This is the most important class in Authentication::Logic. You will inherit this class
+      # for your own eg. `UserSession`.
+      #
+      # Ongoing consolidation of modules
+      # ================================
+      #
+      # We are consolidating modules into this class (inlining mixins). When we
+      # are done, there will only be this one file. It will be quite large, but it
+      # will be easier to trace execution.
+      #
+      # Once consolidation is complete, we hope to identify and extract
+      # collaborating objects. For example, there may be a "session adapter" that
+      # connects this class with the existing `ControllerAdapters`. Perhaps a
+      # data object or a state machine will reveal itself.
+      #
+      # Activation
+      # ==========
+      #
+      # Activating Authentication::Logic requires that you pass it an
+      # Authentication::Logic::ControllerAdapters::AbstractAdapter object, or a class that
+      # extends it. This is sort of like a database connection for an ORM library,
+      # Authentication::Logic can't do anything until it is "connected" to a controller. If
+      # you are using a supported framework, Authentication::Logic takes care of this for you.
+      #
+      # ActiveRecord Trickery
+      # =====================
+      #
+      # Authentication::Logic looks like ActiveRecord, sounds like ActiveRecord, but its not
+      # ActiveRecord. That's the goal here. This is useful for the various rails
+      # helper methods such as form_for, error_messages_for, or any method that
+      # expects an ActiveRecord object. The point is to disguise the object as an
+      # ActiveRecord object so we can take advantage of the many ActiveRecord
+      # tools.
+      #
+      # Brute Force Protection
+      # ======================
+      #
+      # A brute force attacks is executed by hammering a login with as many password
+      # combinations as possible, until one works. A brute force attacked is generally
+      # combated with a slow hashing algorithm such as BCrypt. You can increase the cost,
+      # which makes the hash generation slower, and ultimately increases the time it takes
+      # to execute a brute force attack. Just to put this into perspective, if a hacker was
+      # to gain access to your server and execute a brute force attack locally, meaning
+      # there is no network lag, it would probably take decades to complete. Now throw in
+      # network lag and it would take MUCH longer.
+      #
+      # But for those that are extra paranoid and can't get enough protection, why not stop
+      # them as soon as you realize something isn't right? That's what this module is all
+      # about. By default the consecutive_failed_logins_limit configuration option is set to
+      # 50, if someone consecutively fails to login after 50 attempts their account will be
+      # suspended. This is a very liberal number and at this point it should be obvious that
+      # something is not right. If you wish to lower this number just set the configuration
+      # to a lower number:
+      #
+      #   class UserSession < Authentication::Logic::Session::Base
+      #     consecutive_failed_logins_limit 10
+      #   end
+      #
+      # Callbacks
+      # =========
+      #
+      # Between these callbacks and the configuration, this is the contract between me and
+      # you to safely modify Authentication::Logic's behavior. I will do everything I can to make sure
+      # these do not change.
+      #
+      # Check out the sub modules of Authentication::Logic::Session. They are very concise, clear, and
+      # to the point. More importantly they use the same API that you would use to extend
+      # Authentication::Logic. That being said, they are great examples of how to extend Authentication::Logic and
+      # add / modify behavior to Authentication::Logic. 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 Authentication::Logic, see the METHODS
+      # constant below. The order of execution is as follows:
+      #
+      #   before_persisting
+      #   persist
+      #   after_persisting
+      #   [save record if record.has_changes_to_save?]
+      #
+      #   before_validation
+      #   before_validation_on_create
+      #   before_validation_on_update
+      #   validate
+      #   after_validation_on_update
+      #   after_validation_on_create
+      #   after_validation
+      #   [save record if record.has_changes_to_save?]
+      #
+      #   before_save
+      #   before_create
+      #   before_update
+      #   after_update
+      #   after_create
+      #   after_save
+      #   [save record if record.has_changes_to_save?]
+      #
+      #   before_destroy
+      #   [save record if record.has_changes_to_save?]
+      #   after_destroy
+      #
+      # Notice the "save record if has_changes_to_save" lines above. This helps with performance. If
+      # you need to make changes to the associated record, there is no need to save the
+      # record, Authentication::Logic 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:
+      #
+      #   class UserSession < Authentication::Logic::Session::Base
+      #     before_validation :my_method
+      #     validate :another_method
+      #     # ..etc
+      #   end
+      #
+      # You can NOT define a "before_validation" method, this is bad practice and does not
+      # allow Authentication::Logic to extend properly with multiple extensions. Please ONLY use the
+      # method above.
+      #
+      # HTTP Basic Authentication
+      # =========================
+      #
+      # 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 use a single access token, as described below.
+      #
+      # Magic Columns
+      # =============
+      #
+      # Just like ActiveRecord has "magic" columns, such as: created_at and updated_at.
+      # Authentication::Logic has its own "magic" columns too:
+      #
+      # * login_count - Increased every time an explicit login is made. This will *NOT*
+      #   increase if logging in by a session, cookie, or basic http auth
+      # * failed_login_count - This increases for each consecutive failed login. See
+      #   the consecutive_failed_logins_limit option for details.
+      # * last_request_at - Updates every time the user logs in, either by explicitly
+      #   logging in, or logging in by cookie, session, or http auth
+      # * current_login_at - Updates with the current time when an explicit login is made.
+      # * last_login_at - Updates with the value of current_login_at before it is reset.
+      # * current_login_ip - Updates with the request ip when an explicit login is made.
+      # * last_login_ip - Updates with the value of current_login_ip before it is reset.
+      #
+      # Multiple Simultaneous Sessions
+      # ==============================
+      #
+      # See `id`. Allows you to separate sessions with an id, ultimately letting
+      # you create multiple sessions for the same user.
+      #
+      # Timeout
+      # =======
+      #
+      # Think about financial websites, if you are inactive for a certain period
+      # of time you will be asked to log back in on your next request. You can do
+      # this with Authentication::Logic easily, there are 2 parts to this:
+      #
+      # 1. Define the timeout threshold:
+      #
+      #   acts_as_authentic do |c|
+      #     c.logged_in_timeout = 10.minutes # default is 10.minutes
+      #   end
+      #
+      # 2. Enable logging out on timeouts
+      #
+      #   class UserSession < Authentication::Logic::Session::Base
+      #     logout_on_timeout true # default is false
+      #   end
+      #
+      # This will require a user to log back in if they are inactive for more than
+      # 10 minutes. In order for this feature to be used you must have a
+      # last_request_at datetime column in your table for whatever model you are
+      # authenticating with.
+      #
+      # Params
+      # ======
+      #
+      # This module is responsible for authenticating the user via params, which ultimately
+      # allows the user to log in using a URL like the following:
+      #
+      #   https://www.domain.com?user_credentials=4LiXF7FiGUppIPubBPey
+      #
+      # Notice the token in the URL, this is a single access token. A single access token is
+      # used for single access only, it is not persisted. Meaning the user provides it,
+      # Authentication::Logic grants them access, and that's it. If they want access again they need to
+      # provide the token again. Authentication::Logic will *NEVER* try to persist the session after
+      # authenticating through this method.
+      #
+      # For added security, this token is *ONLY* allowed for RSS and ATOM requests. You can
+      # change this with the configuration. You can also define if it is allowed dynamically
+      # by defining a single_access_allowed? method in your controller. For example:
+      #
+      #   class UsersController < ApplicationController
+      #     private
+      #       def single_access_allowed?
+      #         action_name == "index"
+      #       end
+      #
+      # Also, by default, this token is permanent. Meaning if the user changes their
+      # password, this token will remain the same. It will only change when it is explicitly
+      # reset.
+      #
+      # You can modify all of this behavior with the Config sub module.
+      #
+      # Perishable Token
+      # ================
+      #
+      # Maintains the perishable token, which is helpful for confirming records or
+      # authorizing records to reset their password. All that this module does is
+      # reset it after a session have been saved, just keep it changing. The more
+      # it changes, the tighter the security.
+      #
+      # See Authentication::Logic::ActsAsAuthentic::PerishableToken for more information.
+      #
+      # Scopes
+      # ======
+      #
+      # Authentication can be scoped, and it's easy, you just need to define how you want to
+      # scope everything. See `.with_scope`.
+      #
+      # Unauthorized Record
+      # ===================
+      #
+      # Allows you to create session with an object. Ex:
+      #
+      #   UserSession.create(my_user_object)
+      #
+      # Be careful with this, because Authentication::Logic is assuming that you have already
+      # confirmed that the user is who he says he is.
+      #
+      # For example, this is the method used to persist the session internally.
+      # Authentication::Logic finds the user with the persistence token. At this point we know
+      # the user is who he says he is, so Authentication::Logic just creates a session with
+      # the record. This is particularly useful for 3rd party authentication
+      # methods, such as OpenID. Let that method verify the identity, once it's
+      # verified, pass the object and create a session.
+      #
+      # Magic States
+      # ============
+      #
+      # Authentication::Logic tries to check the state of the record before creating the session. If
+      # your record responds to the following methods and any of them return false,
+      # validation will fail:
+      #
+      #   Method name           Description
+      #   active?               Is the record marked as active?
+      #   approved?             Has the record been approved?
+      #   confirmed?            Has the record been confirmed?
+      #
+      # Authentication::Logic does nothing to define these methods for you, its up to you to define what
+      # they mean. If your object responds to these methods Authentication::Logic will use them,
+      # otherwise they are ignored.
+      #
+      # What's neat about this is that these are checked upon any type of login. When
+      # logging in explicitly, by cookie, session, or basic http auth. So if you mark a user
+      # inactive in the middle of their session they wont be logged back in next time they
+      # refresh the page. Giving you complete control.
+      #
+      # Need Authentication::Logic to check your own "state"? No problem, check out the hooks section
+      # below. Add in a before_validation to do your own checking. The sky is the limit.
+      #
+      # Validation
+      # ==========
+      #
+      # The errors in Authentication::Logic work just like ActiveRecord. In fact, it uses
+      # the `ActiveModel::Errors` class. Use it the same way:
+      #
+      # ```
+      # class UserSession
+      #   validate :check_if_awesome
+      #
+      #   private
+      #
+      #   def check_if_awesome
+      #     if login && !login.include?("awesome")
+      #       errors.add(:login, "must contain awesome")
+      #     end
+      #     unless attempted_record.awesome?
+      #       errors.add(:base, "You must be awesome to log in")
+      #     end
+      #   end
+      # end
+      # ```
+      class Base
+        extend ActiveModel::Naming
+        extend ActiveModel::Translation
+        extend Authentication::Logic::Config
+        include ActiveSupport::Callbacks
+
+        E_AC_PARAMETERS = <<~EOS
+          Passing an ActionController::Parameters to Authentication::Logic is not allowed.
+
+          In Authentication::Logic 3, especially during the transition of rails to Strong
+          Parameters, it was common for Authentication::Logic users to forget to `permit`
+          their params. They would pass their params into Authentication::Logic, we'd call
+          `to_h`, and they'd be surprised when authentication failed.
+
+          In 2018, people are still making this mistake. We'd like to help them
+          and make auth-logic a little simpler at the same time, so in Authentication::Logic
+          3.7.0, we deprecated the use of ActionController::Parameters. Instead,
+          pass a plain Hash. Please replace:
+
+              UserSession.new(user_session_params)
+              UserSession.create(user_session_params)
+
+          with
+
+              UserSession.new(user_session_params.to_h)
+              UserSession.create(user_session_params.to_h)
+
+          And don't forget to `permit`!
+
+          We discussed this issue thoroughly between late 2016 and early
+          2018. Notable discussions include:
+
+          - https://github.com/binarylogic/authlogic/issues/512
+          - https://github.com/binarylogic/authlogic/pull/558
+          - https://github.com/binarylogic/authlogic/pull/577
+        EOS
+        E_DPR_FIND_BY_LOGIN_METHOD = <<~EOS.squish.freeze
+          find_by_login_method is deprecated in favor of record_selection_method,
+          to avoid confusion with ActiveRecord's "Dynamic Finders".
+          (https://guides.rubyonrails.org/v6.0/active_record_querying.html#dynamic-finders)
+          For example, rubocop-rails is confused by the deprecated method.
+          (https://github.com/rubocop-hq/rubocop-rails/blob/master/lib/rubocop/cop/rails/dynamic_find_by.rb)
+        EOS
+        VALID_SAME_SITE_VALUES = [nil, "Lax", "Strict", "None"].freeze
+
+        # Callbacks
+        # =========
+
+        METHODS = %w[
+          before_persisting
+          persist
+          after_persisting
+          before_validation
+          before_validation_on_create
+          before_validation_on_update
+          validate
+          after_validation_on_update
+          after_validation_on_create
+          after_validation
+          before_save
+          before_create
+          before_update
+          after_update
+          after_create
+          after_save
+          before_destroy
+          after_destroy
+        ].freeze
+
+        # Defines the "callback installation methods" used below.
+        METHODS.each do |method|
+          class_eval <<-EOS, __FILE__, __LINE__ + 1
+            def self.#{method}(*filter_list, &block)
+              set_callback(:#{method}, *filter_list, &block)
+            end
+          EOS
+        end
+
+        # Defines session life cycle events that support callbacks.
+        define_callbacks(
+          *METHODS,
+          terminator: ->(_target, result_lambda) { result_lambda.call == false }
+        )
+        define_callbacks(
+          "persist",
+          terminator: ->(_target, result_lambda) { result_lambda.call == true }
+        )
+
+        # Use the "callback installation methods" defined above
+        # -----------------------------------------------------
+
+        before_persisting :reset_stale_state
+
+        # `persist` callbacks, in order of priority
+        persist :persist_by_params
+        persist :persist_by_cookie
+        persist :persist_by_session
+        persist :persist_by_http_auth, if: :persist_by_http_auth?
+
+        after_persisting :enforce_timeout
+        after_persisting :update_session, unless: :single_access?
+        after_persisting :set_last_request_at
+
+        before_save :update_info
+        before_save :set_last_request_at
+
+        after_save :reset_perishable_token!
+        after_save :save_cookie, if: :cookie_enabled?
+        after_save :update_session
+        after_create :renew_session_id
+
+        after_destroy :destroy_cookie, if: :cookie_enabled?
+        after_destroy :update_session
+
+        # `validate` callbacks, in deliberate order. For example,
+        # validate_magic_states must run *after* a record is found.
+        validate :validate_by_password, if: :authenticating_with_password?
+        validate(
+          :validate_by_unauthorized_record,
+          if: :authenticating_with_unauthorized_record?
+        )
+        validate :validate_magic_states, unless: :disable_magic_states?
+        validate :reset_failed_login_count, if: :reset_failed_login_count?
+        validate :validate_failed_logins, if: :being_brute_force_protected?
+        validate :increase_failed_login_count
+
+        # Accessors
+        # =========
+
+        class << self
+          attr_accessor(
+            :configured_password_methods
+          )
+        end
+        attr_accessor(
+          :invalid_password,
+          :new_session,
+          :priority_record,
+          :record,
+          :single_access,
+          :stale_record,
+          :unauthorized_record
+        )
+        attr_writer :scope
+
+        # Public class methods
+        # ====================
+
+        class << self
+          # Returns true if a controller has been set and can be used properly.
+          # This MUST be set before anything can be done. Similar to how
+          # ActiveRecord won't allow you to do anything without establishing a DB
+          # connection. In your framework environment this is done for you, but if
+          # you are using Authentication::Logic outside of your framework, you need to assign
+          # a controller object to Authentication::Logic via
+          # Authentication::Logic::Session::Base.controller = obj. See the controller= method
+          # for more information.
+          def activated?
+            !controller.nil?
+          end
+
+          # Allow users to log in via HTTP basic authentication.
+          #
+          # * <tt>Default:</tt> false
+          # * <tt>Accepts:</tt> Boolean
+          def allow_http_basic_auth(value = nil)
+            rw_config(:allow_http_basic_auth, value, false)
+          end
+          alias allow_http_basic_auth= allow_http_basic_auth
+
+          # Lets you change which model to use for authentication.
+          #
+          # * <tt>Default:</tt> inferred from the class name. UserSession would
+          #   automatically try User
+          # * <tt>Accepts:</tt> an ActiveRecord class
+          def authenticate_with(klass)
+            @klass_name = klass.name
+            @klass = klass
+          end
+          alias authenticate_with= authenticate_with
+
+          # The current controller object
+          def controller
+            RequestStore.store[:auth_logic_controller]
+          end
+
+          # This accepts a controller object wrapped with the Authentication::Logic controller
+          # adapter. The controller adapters close the gap between the different
+          # controllers in each framework. That being said, Authentication::Logic is expecting
+          # your object's class to extend
+          # Authentication::Logic::ControllerAdapters::AbstractAdapter. See
+          # Authentication::Logic::ControllerAdapters for more info.
+          #
+          # Lastly, this is thread safe.
+          def controller=(value)
+            RequestStore.store[:auth_logic_controller] = value
+          end
+
+          # To help protect from brute force attacks you can set a limit on the
+          # allowed number of consecutive failed logins. By default this is 50,
+          # this is a very liberal number, and if someone fails to login after 50
+          # tries it should be pretty obvious that it's a machine trying to login
+          # in and very likely a brute force attack.
+          #
+          # In order to enable this field your model MUST have a
+          # failed_login_count (integer) field.
+          #
+          # If you don't know what a brute force attack is, it's when a machine
+          # tries to login into a system using every combination of character
+          # possible. Thus resulting in possibly millions of attempts to log into
+          # an account.
+          #
+          # * <tt>Default:</tt> 50
+          # * <tt>Accepts:</tt> Integer, set to 0 to disable
+          def consecutive_failed_logins_limit(value = nil)
+            rw_config(:consecutive_failed_logins_limit, value, 50)
+          end
+          alias consecutive_failed_logins_limit= consecutive_failed_logins_limit
+
+          # The name of the cookie or the key in the cookies hash. Be sure and use
+          # a unique name. If you have multiple sessions and they use the same
+          # cookie it will cause problems. Also, if a id is set it will be
+          # inserted into the beginning of the string. Example:
+          #
+          #   session = UserSession.new
+          #   session.cookie_key => "user_credentials"
+          #
+          #   session = UserSession.new(:super_high_secret)
+          #   session.cookie_key => "super_high_secret_user_credentials"
+          #
+          # * <tt>Default:</tt> "#{klass_name.underscore}_credentials"
+          # * <tt>Accepts:</tt> String
+          def cookie_key(value = nil)
+            rw_config(:cookie_key, value, "#{klass_name.underscore}_credentials")
+          end
+          alias cookie_key= cookie_key
+
+          # A convenience method. The same as:
+          #
+          #   session = UserSession.new(*args)
+          #   session.save
+          #
+          # Instead you can do:
+          #
+          #   UserSession.create(*args)
+          def create(*args, &block)
+            session = new(*args)
+            session.save(&block)
+            session
+          end
+
+          # Same as create but calls create!, which raises an exception when
+          # validation fails.
+          def create!(*args)
+            session = new(*args)
+            session.save!
+            session
+          end
+
+          # Set this to true if you want to disable the checking of active?, approved?, and
+          # confirmed? on your record. This is more or less of a convenience feature, since
+          # 99% of the time if those methods exist and return false you will not want the
+          # user logging in. You could easily accomplish this same thing with a
+          # before_validation method or other callbacks.
+          #
+          # * <tt>Default:</tt> false
+          # * <tt>Accepts:</tt> Boolean
+          def disable_magic_states(value = nil)
+            rw_config(:disable_magic_states, value, false)
+          end
+          alias disable_magic_states= disable_magic_states
+
+          # Once the failed logins limit has been exceed, how long do you want to
+          # ban the user? This can be a temporary or permanent ban.
+          #
+          # * <tt>Default:</tt> 2.hours
+          # * <tt>Accepts:</tt> Fixnum, set to 0 for permanent ban
+          def failed_login_ban_for(value = nil)
+            rw_config(:failed_login_ban_for, (!value.nil? && value) || value, 2.hours.to_i)
+          end
+          alias failed_login_ban_for= failed_login_ban_for
+
+          # This is how you persist a session. This finds the record for the
+          # current session using a variety of methods. It basically tries to "log
+          # in" the user without the user having to explicitly log in. Check out
+          # the other Authentication::Logic::Session modules for more information.
+          #
+          # The best way to use this method is something like:
+          #
+          #   helper_method :current_user_session, :current_user
+          #
+          #   def current_user_session
+          #     return @current_user_session if defined?(@current_user_session)
+          #     @current_user_session = UserSession.find
+          #   end
+          #
+          #   def current_user
+          #     return @current_user if defined?(@current_user)
+          #     @current_user = current_user_session && current_user_session.user
+          #   end
+          #
+          # Also, this method accepts a single parameter as the id, to find
+          # session that you marked with an id:
+          #
+          #   UserSession.find(:secure)
+          #
+          # See the id method for more information on ids.
+          #
+          # Priority Record
+          # ===============
+          #
+          # This internal feature supports ActiveRecord's optimistic locking feature,
+          # which is automatically enabled when a table has a `lock_version` column.
+          #
+          # ```
+          # # https://api.rubyonrails.org/classes/ActiveRecord/Locking/Optimistic.html
+          # p1 = Person.find(1)
+          # p2 = Person.find(1)
+          # p1.first_name = "Michael"
+          # p1.save
+          # p2.first_name = "should fail"
+          # p2.save # Raises an ActiveRecord::StaleObjectError
+          # ```
+          #
+          # Now, consider the following Authentication::Logic scenario:
+          #
+          # ```
+          # User.log_in_after_password_change = true
+          # ben = User.find(1)
+          # UserSession.create(ben)
+          # ben.password = "newpasswd"
+          # ben.password_confirmation = "newpasswd"
+          # ben.save
+          # ```
+          #
+          # We've used one of Authentication::Logic's session maintenance features,
+          # `log_in_after_password_change`. So, when we call `ben.save`, there is a
+          # `before_save` callback that logs Ben in (`UserSession.find`). Well, when
+          # we log Ben in, we update his user record, eg. `login_count`. When we're
+          # done logging Ben in, then the normal `ben.save` happens. So, there were
+          # two `update` queries. If those two updates came from different User
+          # instances, we would get a `StaleObjectError`.
+          #
+          # Our solution is to carefully pass around a single `User` instance, using
+          # it for all `update` queries, thus avoiding the `StaleObjectError`.
+          def find(id = nil, priority_record = nil)
+            session = new({ priority_record: priority_record }, id)
+            session.priority_record = priority_record
+            return unless session.persisting?
+
+            session
+          end
+
+          # @deprecated in favor of record_selection_method
+          def find_by_login_method(value = nil)
+            ::ActiveSupport::Deprecation.warn(E_DPR_FIND_BY_LOGIN_METHOD)
+            record_selection_method(value)
+          end
+          alias find_by_login_method= find_by_login_method
+
+          # The text used to identify credentials (username/password) combination
+          # when a bad login attempt occurs. When you show error messages for a
+          # bad login, it's considered good security practice to hide which field
+          # the user has entered incorrectly (the login field or the password
+          # field). For a full explanation, see
+          # http://www.gnucitizen.org/blog/username-enumeration-vulnerabilities/
+          #
+          # Example of use:
+          #
+          #   class UserSession < Authentication::Logic::Session::Base
+          #     generalize_credentials_error_messages true
+          #   end
+          #
+          #   This would make the error message for bad logins and bad passwords
+          #   look identical:
+          #
+          #   Login/Password combination is not valid
+          #
+          #   Alternatively you may use a custom message:
+          #
+          #   class UserSession < AuthLogic::Session::Base
+          #     generalize_credentials_error_messages "Your login information is invalid"
+          #   end
+          #
+          #   This will instead show your custom error message when the UserSession is invalid.
+          #
+          # The downside to enabling this is that is can be too vague for a user
+          # that has a hard time remembering their username and password
+          # combinations. It also disables the ability to to highlight the field
+          # with the error when you use form_for.
+          #
+          # If you are developing an app where security is an extreme priority
+          # (such as a financial application), then you should enable this.
+          # Otherwise, leaving this off is fine.
+          #
+          # * <tt>Default</tt> false
+          # * <tt>Accepts:</tt> Boolean
+          def generalize_credentials_error_messages(value = nil)
+            rw_config(:generalize_credentials_error_messages, value, false)
+          end
+          alias generalize_credentials_error_messages= generalize_credentials_error_messages
+
+          # HTTP authentication realm
+          #
+          # Sets the HTTP authentication realm.
+          #
+          # Note: This option has no effect unless request_http_basic_auth is true
+          #
+          # * <tt>Default:</tt> 'Application'
+          # * <tt>Accepts:</tt> String
+          def http_basic_auth_realm(value = nil)
+            rw_config(:http_basic_auth_realm, value, "Application")
+          end
+          alias http_basic_auth_realm= http_basic_auth_realm
+
+          # Should the cookie be set as httponly?  If true, the cookie will not be
+          # accessible from javascript
+          #
+          # * <tt>Default:</tt> true
+          # * <tt>Accepts:</tt> Boolean
+          def httponly(value = nil)
+            rw_config(:httponly, value, true)
+          end
+          alias httponly= httponly
+
+          # How to name the class, works JUST LIKE ActiveRecord, except it uses
+          # the following namespace:
+          #
+          #   auth.logic.models.user_session
+          def human_name(*)
+            I18n.t("models.#{name.underscore}", count: 1, default: name.humanize)
+          end
+
+          def i18n_scope
+            I18n.scope
+          end
+
+          # The name of the class that this session is authenticating with. For
+          # example, the UserSession class will authenticate with the User class
+          # unless you specify otherwise in your configuration. See
+          # authenticate_with for information on how to change this value.
+          #
+          # @api public
+          def klass
+            @klass ||= klass_name&.constantize
+          end
+
+          # The model name, guessed from the session class name, e.g. "User",
+          # from "UserSession".
+          #
+          # TODO: This method can return nil. We should explore this. It seems
+          # likely to cause a NoMethodError later, so perhaps we should raise an
+          # error instead.
+          #
+          # @api private
+          def klass_name
+            return @klass_name if instance_variable_defined?(:@klass_name)
+
+            @klass_name = name.scan(/(.*)Session/)[0]&.first
+          end
+
+          # The name of the method you want Authentication::Logic to create for storing the
+          # login / username. Keep in mind this is just for your
+          # Authentication::Logic::Session, if you want it can be something completely
+          # different than the field in your model. So if you wanted people to
+          # login with a field called "login" and then find users by email this is
+          # completely doable. See the `record_selection_method` configuration
+          # option for details.
+          #
+          # * <tt>Default:</tt> klass.login_field || klass.email_field
+          # * <tt>Accepts:</tt> Symbol or String
+          def login_field(value = nil)
+            rw_config(:login_field, value, klass.login_field || klass.email_field)
+          end
+          alias login_field= login_field
+
+          # With acts_as_authentic you get a :logged_in_timeout configuration
+          # option. If this is set, after this amount of time has passed the user
+          # will be marked as logged out. Obviously, since web based apps are on a
+          # per request basis, we have to define a time limit threshold that
+          # determines when we consider a user to be "logged out". Meaning, if
+          # they login and then leave the website, when do mark them as logged
+          # out? I recommend just using this as a fun feature on your website or
+          # reports, giving you a ballpark number of users logged in and active.
+          # This is not meant to be a dead accurate representation of a user's
+          # logged in state, since there is really no real way to do this with web
+          # based apps. Think about a user that logs in and doesn't log out. There
+          # is no action that tells you that the user isn't technically still
+          # logged in and active.
+          #
+          # That being said, you can use that feature to require a new login if
+          # their session times out. Similar to how financial sites work. Just set
+          # this option to true and if your record returns true for stale? then
+          # they will be required to log back in.
+          #
+          # Lastly, UserSession.find will still return an object if the session is
+          # stale, but you will not get a record. This allows you to determine if
+          # the user needs to log back in because their session went stale, or
+          # because they just aren't logged in. Just call
+          # current_user_session.stale? as your flag.
+          #
+          # * <tt>Default:</tt> false
+          # * <tt>Accepts:</tt> Boolean
+          def logout_on_timeout(value = nil)
+            rw_config(:logout_on_timeout, value, false)
+          end
+          alias logout_on_timeout= logout_on_timeout
+
+          # Every time a session is found the last_request_at field for that record is
+          # updated with the current time, if that field exists. If you want to limit how
+          # frequent that field is updated specify the threshold here. For example, if your
+          # user is making a request every 5 seconds, and you feel this is too frequent, and
+          # feel a minute is a good threshold. Set this to 1.minute. Once a minute has
+          # passed in between requests the field will be updated.
+          #
+          # * <tt>Default:</tt> 0
+          # * <tt>Accepts:</tt> integer representing time in seconds
+          def last_request_at_threshold(value = nil)
+            rw_config(:last_request_at_threshold, value, 0)
+          end
+          alias last_request_at_threshold= last_request_at_threshold
+
+          # Works exactly like cookie_key, but for params. So a user can login via
+          # params just like a cookie or a session. Your URL would look like:
+          #
+          #   http://www.domain.com?user_credentials=my_single_access_key
+          #
+          # You can change the "user_credentials" key above with this
+          # configuration option. Keep in mind, just like cookie_key, if you
+          # supply an id the id will be appended to the front. Check out
+          # cookie_key for more details. Also checkout the "Single Access /
+          # Private Feeds Access" section in the README.
+          #
+          # * <tt>Default:</tt> cookie_key
+          # * <tt>Accepts:</tt> String
+          def params_key(value = nil)
+            rw_config(:params_key, value, cookie_key)
+          end
+          alias params_key= params_key
+
+          # Works exactly like login_field, but for the password instead. Returns
+          # :password if a login_field exists.
+          #
+          # * <tt>Default:</tt> :password
+          # * <tt>Accepts:</tt> Symbol or String
+          def password_field(value = nil)
+            rw_config(:password_field, value, login_field && :password)
+          end
+          alias password_field= password_field
+
+          # Authentication::Logic tries to validate the credentials passed to it. One part of
+          # validation is actually finding the user and making sure it exists.
+          # What method it uses the do this is up to you.
+          #
+          # ```
+          # # user_session.rb
+          # record_selection_method :find_by_email
+          # ```
+          #
+          # This is the recommended way to find the user by email address.
+          # The resulting query will be `User.find_by_email(send(login_field))`.
+          # (`login_field` will fall back to `email_field` if there's no `login`
+          # or `username` column).
+          #
+          # In your User model you can make that method do anything you want,
+          # giving you complete control of how users are found by the UserSession.
+          #
+          # Let's take an example: You want to allow users to login by username or
+          # email. Set this to the name of the class method that does this in the
+          # User model. Let's call it "find_by_username_or_email"
+          #
+          # ```
+          # class User < ActiveRecord::Base
+          #   def self.find_by_username_or_email(login)
+          #     find_by_username(login) || find_by_email(login)
+          #   end
+          # end
+          # ```
+          #
+          # Now just specify the name of this method for this configuration option
+          # and you are all set. You can do anything you want here. Maybe you
+          # allow users to have multiple logins and you want to search a has_many
+          # relationship, etc. The sky is the limit.
+          #
+          # * <tt>Default:</tt> "find_by_smart_case_login_field"
+          # * <tt>Accepts:</tt> Symbol or String
+          def record_selection_method(value = nil)
+            rw_config(:record_selection_method, value, "find_by_smart_case_login_field")
+          end
+          alias record_selection_method= record_selection_method
+
+          # Whether or not to request HTTP authentication
+          #
+          # If set to true and no HTTP authentication credentials are sent with
+          # the request, the Rails controller method
+          # authenticate_or_request_with_http_basic will be used and a '401
+          # Authorization Required' header will be sent with the response.  In
+          # most cases, this will cause the classic HTTP authentication popup to
+          # appear in the users browser.
+          #
+          # If set to false, the Rails controller method
+          # authenticate_with_http_basic is used and no 401 header is sent.
+          #
+          # Note: This parameter has no effect unless allow_http_basic_auth is
+          # true
+          #
+          # * <tt>Default:</tt> false
+          # * <tt>Accepts:</tt> Boolean
+          def request_http_basic_auth(value = nil)
+            rw_config(:request_http_basic_auth, value, false)
+          end
+          alias request_http_basic_auth= request_http_basic_auth
+
+          # If sessions should be remembered by default or not.
+          #
+          # * <tt>Default:</tt> false
+          # * <tt>Accepts:</tt> Boolean
+          def remember_me(value = nil)
+            rw_config(:remember_me, value, false)
+          end
+          alias remember_me= remember_me
+
+          # The length of time until the cookie expires.
+          #
+          # * <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 = nil)
+            rw_config(:remember_me_for, value, 3.months)
+          end
+          alias remember_me_for= remember_me_for
+
+          # Should the cookie be prevented from being send along with cross-site
+          # requests?
+          #
+          # * <tt>Default:</tt> nil
+          # * <tt>Accepts:</tt> String, one of nil, 'Lax' or 'Strict'
+          def same_site(value = nil)
+            unless VALID_SAME_SITE_VALUES.include?(value)
+              msg = "Invalid same_site value: #{value}. Valid: #{VALID_SAME_SITE_VALUES.inspect}"
+              raise ArgumentError, msg
+            end
+            rw_config(:same_site, value)
+          end
+          alias same_site= same_site
+
+          # The current scope set, should be used in the block passed to with_scope.
+          def scope
+            RequestStore.store[:auth_logic_scope]
+          end
+
+          # Should the cookie be set as secure?  If true, the cookie will only be sent over
+          # SSL connections
+          #
+          # * <tt>Default:</tt> true
+          # * <tt>Accepts:</tt> Boolean
+          def secure(value = nil)
+            rw_config(:secure, value, true)
+          end
+          alias secure= secure
+
+          # Should the Rack session ID be reset after authentication, to protect
+          # against Session Fixation attacks?
+          #
+          # * <tt>Default:</tt> true
+          # * <tt>Accepts:</tt> Boolean
+          def session_fixation_defense(value = nil)
+            rw_config(:session_fixation_defense, value, true)
+          end
+          alias session_fixation_defense= session_fixation_defense
+
+          # Should the cookie be signed? If the controller adapter supports it, this is a
+          # measure against cookie tampering.
+          def sign_cookie(value = nil)
+            if value && controller && !controller.cookies.respond_to?(:signed)
+              raise "Signed cookies not supported with #{controller.class}!"
+            end
+
+            rw_config(:sign_cookie, value, false)
+          end
+          alias sign_cookie= sign_cookie
+
+          # Should the cookie be encrypted? If the controller adapter supports it, this is a
+          # measure to hide the contents of the cookie (e.g. persistence_token)
+          def encrypt_cookie(value = nil)
+            if value && controller && !controller.cookies.respond_to?(:encrypted)
+              raise "Encrypted cookies not supported with #{controller.class}!"
+            end
+
+            if value && sign_cookie
+              raise "It is recommended to use encrypt_cookie instead of sign_cookie. " \
+                    "You may not enable both options."
+            end
+            rw_config(:encrypt_cookie, value, false)
+          end
+          alias encrypt_cookie= encrypt_cookie
+
+          # Works exactly like cookie_key, but for sessions. See cookie_key for more info.
+          #
+          # * <tt>Default:</tt> cookie_key
+          # * <tt>Accepts:</tt> Symbol or String
+          def session_key(value = nil)
+            rw_config(:session_key, value, cookie_key)
+          end
+          alias session_key= session_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.
+          #
+          # * <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)
+            rw_config(
+              :single_access_allowed_request_types,
+              value,
+              ["application/rss+xml", "application/atom+xml"]
+            )
+          end
+          alias single_access_allowed_request_types= single_access_allowed_request_types
+
+          # The name of the method in your model used to verify the password. This
+          # should be an instance method. It should also be prepared to accept a
+          # raw password and a crytped password.
+          #
+          # * <tt>Default:</tt> "valid_password?" defined in acts_as_authentic/password.rb
+          # * <tt>Accepts:</tt> Symbol or String
+          def verify_password_method(value = nil)
+            rw_config(:verify_password_method, value, "valid_password?")
+          end
+          alias verify_password_method= verify_password_method
+
+          # What with_scopes focuses on is scoping the query when finding the
+          # object and the name of the cookie / session. It works very similar to
+          # ActiveRecord::Base#with_scopes. It accepts a hash with any of the
+          # following options:
+          #
+          # * <tt>find_options:</tt> any options you can pass into ActiveRecord::Base.find.
+          #   This is used when trying to find the record.
+          # * <tt>id:</tt> The id of the session, this gets merged with the real id. For
+          #   information ids see the id method.
+          #
+          # Here is how you use it:
+          #
+          # ```
+          # UserSession.with_scope(find_options: User.where(account_id: 2), id: "account_2") do
+          #   UserSession.find
+          # end
+          # ```
+          #
+          # Essentially what the above does is scope the searching of the object
+          # with the sql you provided. So instead of:
+          #
+          # ```
+          # User.where("login = 'ben'").first
+          # ```
+          #
+          # it would effectively be:
+          #
+          # ```
+          # User.where("login = 'ben' and account_id = 2").first
+          # ```
+          #
+          # You will also notice the :id option. This works just like the id
+          # method. It scopes your cookies. So the name of your cookie will be:
+          #
+          #   account_2_user_credentials
+          #
+          # instead of:
+          #
+          #   user_credentials
+          #
+          # What is also nifty about scoping with an :id is that it merges your
+          # id's. So if you do:
+          #
+          #   UserSession.with_scope(
+          #     find_options: { conditions: "account_id = 2"},
+          #     id: "account_2"
+          #   ) do
+          #     session = UserSession.new
+          #     session.id = :secure
+          #   end
+          #
+          # The name of your cookies will be:
+          #
+          #   secure_account_2_user_credentials
+          def with_scope(options = {})
+            raise ArgumentError, "You must provide a block" unless block_given?
+
+            self.scope = options
+            result = yield
+            self.scope = nil
+            result
+          end
+        end
+
+        # Constructor
+        # ===========
+
+        def initialize(*args)
+          @id = nil
+          self.scope = self.class.scope
+          define_record_alias_method
+          raise Activation::NotActivatedError unless self.class.activated?
+
+          unless self.class.configured_password_methods
+            configure_password_methods
+            self.class.configured_password_methods = true
+          end
+          instance_variable_set("@#{password_field}", nil)
+          self.credentials = args
+        end
+
+        # Public instance methods
+        # =======================
+
+        # You should use this as a place holder for any records that you find
+        # during validation. The main reason for this is to allow other modules to
+        # use it if needed. Take the failed_login_count feature, it needs this in
+        # order to increase the failed login count.
+        attr_reader :attempted_record
+
+        # See attempted_record
+        def attempted_record=(value)
+          value = priority_record if value == priority_record # See notes in `.find`
+          @attempted_record = value
+        end
+
+        # 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
+
+        # The credentials you passed to create your session, in a redacted format
+        # intended for output (debugging, logging). See credentials= for more
+        # info.
+        #
+        # @api private
+        def credentials
+          if authenticating_with_unauthorized_record?
+            { unauthorized_record: "<protected>" }
+          elsif authenticating_with_password?
+            {
+              login_field.to_sym => send(login_field),
+              password_field.to_sym => "<protected>"
+            }
+          else
+            {}
+          end
+        end
+
+        # Set your credentials before you save your session. There are many
+        # method signatures.
+        #
+        # ```
+        # # A hash of credentials is most common
+        # session.credentials = { login: "foo", password: "bar", remember_me: true }
+        #
+        # # You must pass an actual Hash, `ActionController::Parameters` is
+        # # specifically not allowed.
+        #
+        # # You can pass an array of objects:
+        # session.credentials = [my_user_object, true]
+        #
+        # # If you need to set an id (see `#id`) pass it last.
+        # session.credentials = [
+        #   {:login => "foo", :password => "bar", :remember_me => true},
+        #   :my_id
+        # ]
+        # session.credentials = [my_user_object, true, :my_id]
+        #
+        # The `id` is something that you control yourself, it should never be
+        # set from a hash or a form.
+        #
+        # # Finally, there's priority_record
+        # [{ priority_record: my_object }, :my_id]
+        # ```
+        #
+        # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+        def credentials=(value)
+          normalized = Array.wrap(value)
+          raise TypeError, E_AC_PARAMETERS if normalized.first.instance_of?(::ActionController::Parameters)
+
+          # Allows you to set the remember_me option when passing credentials.
+          values = value.is_a?(Array) ? value : [value]
+          case values.first
+          when Hash
+            if values.first.with_indifferent_access.key?(:remember_me)
+              self.remember_me = values.first.with_indifferent_access[:remember_me]
+            end
+          else
+            r = values.find { |val| val.is_a?(TrueClass) || val.is_a?(FalseClass) }
+            self.remember_me = r unless r.nil?
+          end
+
+          # Accepts the login_field / password_field credentials combination in
+          # hash form.
+          #
+          # You must pass an actual Hash, `ActionController::Parameters` is
+          # specifically not allowed.
+          values = Array.wrap(value)
+          if values.first.is_a?(Hash)
+            sliced = values
+                     .first
+                     .with_indifferent_access
+                     .slice(login_field, password_field)
+            sliced.each do |field, val|
+              next if val.blank?
+
+              send("#{field}=", val)
+            end
+          end
+
+          # Setting the unauthorized record if it exists in the credentials passed.
+          values = value.is_a?(Array) ? value : [value]
+          self.unauthorized_record = values.first if values.first.class < ::ActiveRecord::Base
+
+          # Setting the id if it is passed in the credentials.
+          values = value.is_a?(Array) ? value : [value]
+          self.id = values.last if values.last.is_a?(Symbol)
+
+          # Setting priority record if it is passed. The only way it can be passed
+          # is through an array:
+          #
+          #   session.credentials = [real_user_object, priority_user_object]
+          #
+          # See notes in `.find`
+          values = value.is_a?(Array) ? value : [value]
+          self.priority_record = values[1] if values[1].class < ::ActiveRecord::Base
+        end
+        # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+        # Clears all errors and the associated record, you should call this
+        # terminate a session, thus requiring the user to authenticate again if
+        # it is needed.
+        def destroy
+          run_callbacks :before_destroy
+          save_record
+          errors.clear
+          @record = nil
+          run_callbacks :after_destroy
+          true
+        end
+
+        def destroyed?
+          record.nil?
+        end
+
+        # @api public
+        def errors
+          @errors ||= ::ActiveModel::Errors.new(self)
+        end
+
+        # If the cookie should be marked as httponly (not accessible via javascript)
+        def httponly
+          return @httponly if defined?(@httponly)
+
+          @httponly = self.class.httponly
+        end
+
+        # Accepts a boolean as to whether the cookie should be marked as
+        # httponly.  If true, the cookie will not be accessible from javascript
+        attr_writer :httponly
+
+        # See httponly
+        def httponly?
+          httponly == true || httponly == "true" || httponly == "1"
+        end
+
+        # Allows you to set a unique identifier for your session, so that you can
+        # have more than 1 session at a time.
+        #
+        # For example, you may want to have simultaneous private and public
+        # sessions. Or, a normal user session and a "secure" user session. The
+        # secure user session would be created only when they want to modify their
+        # billing information, or other sensitive information.
+        #
+        # You can set the id during initialization (see initialize for more
+        # information), or as an attribute:
+        #
+        #   session.id = :my_id
+        #
+        # Set your id before you save your session.
+        #
+        # Lastly, to retrieve your session with the id, use the `.find` method.
+        attr_accessor :id
+
+        def inspect
+          format(
+            "#<%s: %s>",
+            self.class.name,
+            credentials.blank? ? "no credentials provided" : credentials.inspect
+          )
+        end
+
+        def invalid_password?
+          invalid_password == true
+        end
+
+        # 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
+
+        # 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
+
+        def persisted?
+          !(new_record? || destroyed?)
+        end
+
+        # Returns boolean indicating if the session is being persisted or not,
+        # meaning the user does not have to explicitly log in in order to be
+        # logged in.
+        #
+        # If the session has no associated record, it will try to find a record
+        # and persist the session.
+        #
+        # This is the method that the class level method find uses to ultimately
+        # persist the session.
+        def persisting?
+          return true unless record.nil?
+
+          self.attempted_record = nil
+          self.remember_me = cookie_credentials&.remember_me?
+          run_callbacks :before_persisting
+          run_callbacks :persist
+          ensure_authentication_attempted
+          if errors.empty? && !attempted_record.nil?
+            self.record = attempted_record
+            run_callbacks :after_persisting
+            save_record
+            self.new_session = false
+            true
+          else
+            false
+          end
+        end
+
+        def save_record(alternate_record = nil)
+          r = alternate_record || record
+          return unless r != priority_record
+          return unless r&.has_changes_to_save? && !r.readonly?
+
+          r.save_without_session_maintenance(validate: false)
+        end
+
+        # Tells you if the record is stale or not. Meaning the record has timed
+        # out. This will only return true if you set logout_on_timeout to true
+        # in your configuration. Basically how a bank website works. If you
+        # aren't active over a certain period of time your session becomes stale
+        # and requires you to log back in.
+        def stale?
+          if remember_me?
+            remember_me_expired?
+          else
+            !stale_record.nil? || (logout_on_timeout? && record && record.logged_out?)
+          end
+        end
+
+        # 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
+
+        # Accepts a boolean as a flag to remember the session or not. Basically
+        # to expire the cookie at the end of the session or keep it for
+        # "remember_me_until".
+        attr_writer :remember_me
+
+        # See remember_me
+        def remember_me?
+          remember_me == true || remember_me == "true" || remember_me == "1"
+        end
+
+        # Has the cookie expired due to current time being greater than remember_me_until.
+        def remember_me_expired?
+          return unless remember_me?
+
+          cookie_credentials.remember_me_until < ::Time.now
+        end
+
+        # How long to remember the user if remember_me is true. This is based on the class
+        # level configuration: remember_me_for
+        def remember_me_for
+          return unless remember_me?
+
+          self.class.remember_me_for
+        end
+
+        # When to expire the cookie. See remember_me_for configuration option to change
+        # this.
+        def remember_me_until
+          return unless remember_me?
+
+          remember_me_for.from_now
+        end
+
+        # After you have specified all of the details for your session you can
+        # try to save it. This will run validation checks and find the
+        # associated record, if all validation passes. If validation does not
+        # pass, the save will fail and the errors will be stored in the errors
+        # object.
+        def save
+          result = nil
+          if valid?
+            self.record = attempted_record
+
+            run_callbacks :before_save
+            run_callbacks(new_session? ? :before_create : :before_update)
+            run_callbacks(new_session? ? :after_create : :after_update)
+            run_callbacks :after_save
+
+            save_record
+            self.new_session = false
+            result = true
+          else
+            result = false
+          end
+
+          yield result if block_given?
+          result
+        end
+
+        # Same as save but raises an exception of validation errors when
+        # validation fails
+        def save!
+          result = save
+          raise Existence::SessionInvalidError, self unless result
+
+          result
+        end
+
+        # If the cookie should be marked as secure (SSL only)
+        def secure
+          return @secure if defined?(@secure)
+
+          @secure = self.class.secure
+        end
+
+        # Accepts a boolean as to whether the cookie should be marked as secure.  If true
+        # the cookie will only ever be sent over an SSL connection.
+        attr_writer :secure
+
+        # See secure
+        def secure?
+          secure == true || secure == "true" || secure == "1"
+        end
+
+        # If the cookie should be marked as SameSite with 'Lax' or 'Strict' flag.
+        def same_site
+          return @same_site if defined?(@same_site)
+
+          @same_site = self.class.same_site(nil)
+        end
+
+        # Accepts nil, 'Lax' or 'Strict' as possible flags.
+        def same_site=(value)
+          unless VALID_SAME_SITE_VALUES.include?(value)
+            msg = "Invalid same_site value: #{value}. Valid: #{VALID_SAME_SITE_VALUES.inspect}"
+            raise ArgumentError, msg
+          end
+          @same_site = value
+        end
+
+        # If the cookie should be signed
+        def sign_cookie
+          return @sign_cookie if defined?(@sign_cookie)
+
+          @sign_cookie = self.class.sign_cookie
+        end
+
+        # Accepts a boolean as to whether the cookie should be signed.  If true
+        # the cookie will be saved and verified using a signature.
+        attr_writer :sign_cookie
+
+        # See sign_cookie
+        def sign_cookie?
+          sign_cookie == true || sign_cookie == "true" || sign_cookie == "1"
+        end
+
+        # If the cookie should be encrypted
+        def encrypt_cookie
+          return @encrypt_cookie if defined?(@encrypt_cookie)
+
+          @encrypt_cookie = self.class.encrypt_cookie
+        end
+
+        # Accepts a boolean as to whether the cookie should be encrypted.  If true
+        # the cookie will be saved in an encrypted state.
+        attr_writer :encrypt_cookie
+
+        # See encrypt_cookie
+        def encrypt_cookie?
+          encrypt_cookie == true || encrypt_cookie == "true" || encrypt_cookie == "1"
+        end
+
+        # The scope of the current object
+        def scope
+          @scope ||= {}
+        end
+
+        def to_key
+          new_record? ? nil : record.to_key
+        end
+
+        # For rails >= 3.0
+        def to_model
+          self
+        end
+
+        # Determines if the information you provided for authentication is valid
+        # or not. If there is a problem with the information provided errors will
+        # be added to the errors object and this method will return false.
+        #
+        # @api public
+        def valid?
+          errors.clear
+          self.attempted_record = nil
+          run_the_before_validation_callbacks
+
+          # Run the `validate` callbacks, eg. `validate_by_password`.
+          # This is when `attempted_record` is set.
+          run_callbacks(:validate)
+
+          ensure_authentication_attempted
+          run_the_after_validation_callbacks if errors.empty?
+          save_record(attempted_record)
+          errors.empty?
+        end
+
+        # Private class methods
+        # =====================
+
+        class << self
+          private
+
+          def scope=(value)
+            RequestStore.store[:auth_logic_scope] = value
+          end
+        end
+
+        # Private instance methods
+        # ========================
+
+        private
+
+        def add_general_credentials_error
+          error_message =
+            if self.class.generalize_credentials_error_messages.is_a? String
+              self.class.generalize_credentials_error_messages
+            else
+              "#{login_field.to_s.humanize}/Password combination is not valid"
+            end
+          errors.add(
+            :base,
+            I18n.t("error_messages.general_credentials_error", default: error_message)
+          )
+        end
+
+        def add_invalid_password_error
+          if generalize_credentials_error_messages?
+            add_general_credentials_error
+          else
+            errors.add(
+              password_field,
+              I18n.t("error_messages.password_invalid", default: "is not valid")
+            )
+          end
+        end
+
+        def add_login_not_found_error
+          if generalize_credentials_error_messages?
+            add_general_credentials_error
+          else
+            errors.add(
+              login_field,
+              I18n.t("error_messages.login_not_found", default: "is not valid")
+            )
+          end
+        end
+
+        def allow_http_basic_auth?
+          self.class.allow_http_basic_auth == true
+        end
+
+        def authenticating_with_password?
+          login_field && (!send(login_field).nil? || !send("protected_#{password_field}").nil?)
+        end
+
+        def authenticating_with_unauthorized_record?
+          !unauthorized_record.nil?
+        end
+
+        # Used for things like cookie_key, session_key, etc.
+        # Examples:
+        # - user_credentials
+        # - ziggity_zack_user_credentials
+        #   - ziggity_zack is an "id"
+        #   - see persistence_token_test.rb
+        def build_key(last_part)
+          [id, scope[:id], last_part].compact.join("_")
+        end
+
+        def clear_failed_login_count
+          return unless record.respond_to?(:failed_login_count)
+
+          record.failed_login_count = 0
+        end
+
+        def consecutive_failed_logins_limit
+          self.class.consecutive_failed_logins_limit
+        end
+
+        def controller
+          self.class.controller
+        end
+
+        def cookie_key
+          build_key(self.class.cookie_key)
+        end
+
+        # Look in the `cookie_jar`, find the cookie that contains auth-logic
+        # credentials (`cookie_key`).
+        #
+        # @api private
+        # @return ::Authentication::Logic::CookieCredentials or if no cookie is found, nil
+        def cookie_credentials
+          return unless cookie_enabled?
+
+          cookie_value = cookie_jar[cookie_key]
+          return if cookie_value.nil?
+
+          ::Authentication::Logic::CookieCredentials.parse(cookie_value)
+        end
+
+        def cookie_enabled?
+          !controller.cookies.nil?
+        end
+
+        def cookie_jar
+          if self.class.encrypt_cookie
+            controller.cookies.encrypted
+          elsif self.class.sign_cookie
+            controller.cookies.signed
+          else
+            controller.cookies
+          end
+        end
+
+        def configure_password_methods
+          define_login_field_methods
+          define_password_field_methods
+        end
+
+        # Assign a new controller-session ID, to defend against Session Fixation.
+        # https://guides.rubyonrails.org/v6.0/security.html#session-fixation
+        def renew_session_id
+          return unless self.class.session_fixation_defense
+
+          controller.renew_session_id
+        end
+
+        def define_login_field_methods
+          return unless login_field
+
+          self.class.send(:attr_writer, login_field) unless respond_to?("#{login_field}=")
+          self.class.send(:attr_reader, login_field) unless respond_to?(login_field)
+        end
+
+        # @api private
+        def define_password_field_methods
+          return unless password_field
+
+          define_password_field_writer_method
+          define_password_field_reader_methods
+        end
+
+        # The password should not be accessible publicly. This way forms using
+        # form_for don't fill the password with the attempted password. To prevent
+        # this we just create this method that is private.
+        #
+        # @api private
+        def define_password_field_reader_methods
+          unless respond_to?(password_field)
+            # Deliberate no-op method, see rationale above.
+            self.class.send(:define_method, password_field) {}
+          end
+          self.class.class_eval(
+            <<-EOS, __FILE__, __LINE__ + 1
+            private
+            def protected_#{password_field}
+              @#{password_field}
+            end
+            EOS
+          )
+        end
+
+        def define_password_field_writer_method
+          return if respond_to?("#{password_field}=")
+
+          self.class.send(:attr_writer, password_field)
+        end
+
+        # Creating an alias method for the "record" method based on the klass
+        # name, so that we can do:
+        #
+        #   session.user
+        #
+        # instead of:
+        #
+        #   session.record
+        #
+        # @api private
+        def define_record_alias_method
+          noun = klass_name.demodulize.underscore.to_sym
+          return if respond_to?(noun)
+
+          self.class.send(:alias_method, noun, :record)
+        end
+
+        def destroy_cookie
+          controller.cookies.delete cookie_key, domain: controller.cookie_domain
+        end
+
+        def disable_magic_states?
+          self.class.disable_magic_states == true
+        end
+
+        def enforce_timeout
+          return unless stale?
+
+          self.stale_record = record
+          self.record = nil
+        end
+
+        def ensure_authentication_attempted
+          return unless errors.empty? && attempted_record.nil?
+
+          errors.add(
+            :base,
+            I18n.t(
+              "error_messages.no_authentication_details",
+              default: "You did not provide any details for authentication."
+            )
+          )
+        end
+
+        def exceeded_failed_logins_limit?
+          !attempted_record.nil? &&
+            attempted_record.respond_to?(:failed_login_count) &&
+            consecutive_failed_logins_limit.positive? &&
+            attempted_record.failed_login_count &&
+            attempted_record.failed_login_count >= consecutive_failed_logins_limit
+        end
+
+        # @deprecated in favor of `self.class.record_selection_method`
+        def find_by_login_method
+          ::ActiveSupport::Deprecation.warn(E_DPR_FIND_BY_LOGIN_METHOD)
+          self.class.record_selection_method
+        end
+
+        def generalize_credentials_error_messages?
+          self.class.generalize_credentials_error_messages
+        end
+
+        # @api private
+        def generate_cookie_for_saving
+          {
+            value: generate_cookie_value.to_s,
+            expires: remember_me_until,
+            secure: secure,
+            httponly: httponly,
+            same_site: same_site,
+            domain: controller.cookie_domain
+          }
+        end
+
+        def generate_cookie_value
+          ::Authentication::Logic::CookieCredentials.new(
+            record.persistence_token,
+            record.send(record.class.primary_key),
+            remember_me? ? remember_me_until : nil
+          )
+        end
+
+        # Returns a Proc to be executed by
+        # `ActionController::HttpAuthentication::Basic` when credentials are
+        # present in the HTTP request.
+        #
+        # @api private
+        # @return Proc
+        def http_auth_login_proc
+          proc do |login, password|
+            if !login.blank? && !password.blank?
+              send("#{login_field}=", login)
+              send("#{password_field}=", password)
+              valid?
+            end
+          end
+        end
+
+        def failed_login_ban_for
+          self.class.failed_login_ban_for
+        end
+
+        def increase_failed_login_count
+          return unless invalid_password? && attempted_record.respond_to?(:failed_login_count)
+
+          attempted_record.failed_login_count ||= 0
+          attempted_record.failed_login_count += 1
+        end
+
+        def increment_login_count
+          return unless record.respond_to?(:login_count)
+
+          record.login_count = (record.login_count.blank? ? 1 : record.login_count + 1)
+        end
+
+        def klass
+          self.class.klass
+        end
+
+        def klass_name
+          self.class.klass_name
+        end
+
+        def last_request_at_threshold
+          self.class.last_request_at_threshold
+        end
+
+        def login_field
+          self.class.login_field
+        end
+
+        def logout_on_timeout?
+          self.class.logout_on_timeout == true
+        end
+
+        def params_credentials
+          controller.params[params_key]
+        end
+
+        def params_enabled?
+          return false if !params_credentials || !klass.column_names.include?("single_access_token")
+          return controller.single_access_allowed? if controller.responds_to_single_access_allowed?
+
+          params_enabled_by_allowed_request_types?
+        end
+
+        def params_enabled_by_allowed_request_types?
+          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
+            %i[all any].include?(single_access_allowed_request_types)
+          end
+        end
+
+        def params_key
+          build_key(self.class.params_key)
+        end
+
+        def password_field
+          self.class.password_field
+        end
+
+        # Tries to validate the session from information in the cookie
+        def persist_by_cookie
+          creds = cookie_credentials
+          if creds&.persistence_token.present?
+            record = search_for_record("find_by_#{klass.primary_key}", creds.record_id)
+            self.unauthorized_record = record if record && record.persistence_token == creds.persistence_token
+            valid?
+          else
+            false
+          end
+        end
+
+        def persist_by_params
+          return false unless params_enabled?
+
+          self.unauthorized_record = search_for_record(
+            "find_by_single_access_token",
+            params_credentials
+          )
+          self.single_access = valid?
+        end
+
+        def persist_by_http_auth
+          login_proc = http_auth_login_proc
+
+          if self.class.request_http_basic_auth
+            controller.authenticate_or_request_with_http_basic(
+              self.class.http_basic_auth_realm,
+              &login_proc
+            )
+          else
+            controller.authenticate_with_http_basic(&login_proc)
+          end
+
+          false
+        end
+
+        def persist_by_http_auth?
+          allow_http_basic_auth? && login_field && password_field
+        end
+
+        # Tries to validate the session from information in the session
+        def persist_by_session
+          persistence_token, record_id = session_credentials
+          if !persistence_token.nil?
+            record = persist_by_session_search(persistence_token, record_id)
+            self.unauthorized_record = record if record && record.persistence_token == persistence_token
+            valid?
+          else
+            false
+          end
+        end
+
+        # Allow finding by persistence token, because when records are created
+        # the session is maintained in a before_save, when there is no id.
+        # This is done for performance reasons and to save on queries.
+        def persist_by_session_search(persistence_token, record_id)
+          if record_id.nil?
+            search_for_record("find_by_persistence_token", persistence_token.to_s)
+          else
+            search_for_record("find_by_#{klass.primary_key}", record_id.to_s)
+          end
+        end
+
+        def reset_stale_state
+          self.stale_record = nil
+        end
+
+        def reset_perishable_token!
+          if record.respond_to?(:reset_perishable_token) &&
+             !record.disable_perishable_token_maintenance?
+            record.reset_perishable_token
+          end
+        end
+
+        # @api private
+        def required_magic_states_for(record)
+          %i[active approved confirmed].select do |state|
+            record.respond_to?("#{state}?")
+          end
+        end
+
+        def reset_failed_login_count?
+          exceeded_failed_logins_limit? && !being_brute_force_protected?
+        end
+
+        def reset_failed_login_count
+          attempted_record.failed_login_count = 0
+        end
+
+        # @api private
+        def run_the_after_validation_callbacks
+          run_callbacks(new_session? ? :after_validation_on_create : :after_validation_on_update)
+          run_callbacks(:after_validation)
+        end
+
+        # @api private
+        def run_the_before_validation_callbacks
+          run_callbacks(:before_validation)
+          run_callbacks(new_session? ? :before_validation_on_create : :before_validation_on_update)
+        end
+
+        # `args[0]` is the name of a model method, like
+        # `find_by_single_access_token` or `find_by_smart_case_login_field`.
+        def search_for_record(*args)
+          search_scope.scoping do
+            klass.send(*args)
+          end
+        end
+
+        # Returns an AR relation representing the scope of the search. The
+        # relation is either provided directly by, or defined by
+        # `find_options`.
+        def search_scope
+          if scope[:find_options].is_a?(ActiveRecord::Relation)
+            scope[:find_options]
+          else
+            conditions = scope[:find_options] && scope[:find_options][:conditions] || {}
+            klass.send(:where, conditions)
+          end
+        end
+
+        # @api private
+        def set_last_request_at
+          current_time = Time.current
+          MagicColumn::AssignsLastRequestAt
+            .new(current_time, record, controller, last_request_at_threshold)
+            .assign
+        end
+
+        def single_access?
+          single_access == true
+        end
+
+        def single_access_allowed_request_types
+          self.class.single_access_allowed_request_types
+        end
+
+        def save_cookie
+          cookie_jar[cookie_key] = generate_cookie_for_saving
+        end
+
+        # @api private
+        # @return [String] - Examples:
+        # - user_credentials_id
+        # - ziggity_zack_user_credentials_id
+        #   - ziggity_zack is an "id", see `#id`
+        #   - see persistence_token_test.rb
+        def session_compound_key
+          "#{session_key}_#{klass.primary_key}"
+        end
+
+        def session_credentials
+          [
+            controller.session[session_key],
+            controller.session[session_compound_key]
+          ].collect { |i| i.nil? ? i : i.to_s }.compact
+        end
+
+        # @return [String] - Examples:
+        # - user_credentials
+        # - ziggity_zack_user_credentials
+        #   - ziggity_zack is an "id", see `#id`
+        #   - see persistence_token_test.rb
+        def session_key
+          build_key(self.class.session_key)
+        end
+
+        def update_info
+          increment_login_count
+          clear_failed_login_count
+          update_login_timestamps
+          update_login_ip_addresses
+        end
+
+        def update_login_ip_addresses
+          return unless record.respond_to?(:current_login_ip)
+
+          record.last_login_ip = record.current_login_ip if record.respond_to?(:last_login_ip)
+          record.current_login_ip = controller.request.ip
+        end
+
+        def update_login_timestamps
+          return unless record.respond_to?(:current_login_at)
+
+          record.last_login_at = record.current_login_at if record.respond_to?(:last_login_at)
+          record.current_login_at = Time.current
+        end
+
+        def update_session
+          update_session_set_persistence_token
+          update_session_set_primary_key
+        end
+
+        # Updates the session, setting the primary key (usually `id`) of the
+        # record.
+        #
+        # @api private
+        def update_session_set_primary_key
+          compound_key = session_compound_key
+          controller.session[compound_key] = record && record.send(record.class.primary_key)
+        end
+
+        # Updates the session, setting the `persistence_token` of the record.
+        #
+        # @api private
+        def update_session_set_persistence_token
+          controller.session[session_key] = record && record.persistence_token
+        end
+
+        # In keeping with the metaphor of ActiveRecord, verification of the
+        # password is referred to as a "validation".
+        def validate_by_password
+          self.invalid_password = false
+          validate_by_password__blank_fields
+          return if errors.count.positive?
+
+          self.attempted_record = search_for_record(
+            self.class.record_selection_method,
+            send(login_field)
+          )
+          if attempted_record.blank?
+            add_login_not_found_error
+            return
+          end
+          validate_by_password__invalid_password
+        end
+
+        def validate_by_password__blank_fields
+          if send(login_field).blank?
+            errors.add(
+              login_field,
+              I18n.t("error_messages.login_blank", default: "cannot be blank")
+            )
+          end
+          return unless send("protected_#{password_field}").blank?
+
+          errors.add(
+            password_field,
+            I18n.t("error_messages.password_blank", default: "cannot be blank")
+          )
+        end
+
+        # Verify the password, usually using `valid_password?` in
+        # `acts_as_authentic/password.rb`. If it cannot be verified, we
+        # refer to it as "invalid".
+        def validate_by_password__invalid_password
+          unless attempted_record.send(
+            verify_password_method,
+            send("protected_#{password_field}")
+          )
+            self.invalid_password = true
+            add_invalid_password_error
+          end
+        end
+
+        def validate_by_unauthorized_record
+          self.attempted_record = unauthorized_record
+        end
+
+        def validate_magic_states
+          return true if attempted_record.nil?
+
+          required_magic_states_for(attempted_record).each do |required_status|
+            next if attempted_record.send("#{required_status}?")
+
+            errors.add(
+              :base,
+              I18n.t(
+                "error_messages.not_#{required_status}",
+                default: "Your account is not #{required_status}"
+              )
+            )
+            return false
+          end
+          true
+        end
+
+        def validate_failed_logins
+          # Clear all other error messages, as they are irrelevant at this point and can
+          # only provide additional information that is not needed
+          errors.clear
+          duration = failed_login_ban_for.zero? ? "" : " temporarily"
+          errors.add(
+            :base,
+            I18n.t(
+              "error_messages.consecutive_failed_logins_limit_exceeded",
+              default: format(
+                "Consecutive failed logins limit exceeded, account has been%s disabled.",
+                duration
+              )
+            )
+          )
+        end
+
+        def verify_password_method
+          self.class.verify_password_method
+        end
+      end
+    end
+  end
+end