crypt_ident 0.2.1

data/lib/crypt_ident/generate_reset_token.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+require 'dry/monads/result'
+require 'dry/matcher/result_matcher'
+
+require_relative './config'
+
+# Include and interact with `CryptIdent` to add authentication to a
+# Hanami controller action.
+#
+# Note the emphasis on *controller action*; this module interacts with session
+# data, which is quite theoretically possible in an Interactor but practically
+# *quite* the PITA. YHBW.
+#
+# @author Jeff Dickey
+# @version 0.2.0
+module CryptIdent
+  # Generate a Password Reset Token
+  #
+  # Password Reset Tokens are useful for verifying that the person requesting a
+  # Password Reset for an existing User is sufficiently likely to be the person
+  # who Registered that User or, if not, that no compromise or other harm is
+  # done.
+  #
+  # Typically, this is done by sending a link through email or other such medium
+  # to the address previously associated with the User purportedly requesting
+  # the Password Reset. `CryptIdent` *does not* automate generation or sending
+  # of the email message. What it *does* provide is a method to generate a new
+  # Password Reset Token to be embedded into an HTML anchor link within an email
+  # that you construct, and then another method (`#reset_password`) to actually
+  # change the password given a valid, correct token.
+  #
+  # It also implements an expiry system, such that if the confirmation of the
+  # Password Reset request is not completed within a configurable time, that the
+  # token is no longer valid (and so cannot be later reused by unauthorised
+  # persons).
+  #
+  # This method *requires* a block, to which a `result` indicating success or
+  # failure is yielded. That block **must** in turn call **both**
+  # `result.success` and `result.failure` to handle success and failure results,
+  # respectively. On success, the block yielded to by `result.success` is called
+  # and passed a `user:` parameter, which is identical to the `user` parameter
+  # passed in to `#generate_reset_token` *except* that the `:token` and
+  # `:password_reset_expires_at` attributes have been updated to reflect the
+  # token request. An updated record matching that `:user` Entity will also have
+  # been saved to the Repository.
+  #
+  # On failure, the `result.failure` call will yield three parameters: `:code`,
+  # `:current_user`, and `:name`, and will be set as follows:
+  #
+  # If the `:code` value is `:user_logged_in`, that indicates that the
+  # `current_user` parameter to this method represented a Registered User. In
+  # this event, the `:current_user` value passed in to the `result.failure` call
+  # will be the same User Entity passed into the method, and the `:name` value
+  # will be `:unassigned`.
+  #
+  # If the `:code` value is `:user_not_found`, the named User was not found in
+  # the Repository. The `:current_user` parameter will be the Guest User Entity,
+  # and the `:name` parameter to the `result.failure` block will be the
+  # `user_name` value passed into the method.
+  # @yieldparam result [Dry::Matcher::Evaluator] Indicates whether the attempt
+  #               to generate a new Reset Token succeeded or failed. The lock
+  #               **must** call **both** `result.success` and `result.failure`
+  #               methods, where the block passed to `result.success` accepts a
+  #               parameter for `user:`, which is a User Entity with the
+  #               specified `name` value as well as non-`nil` values for its
+  #               `:token` and `:password_reset_expires_at` attributes. The
+  #               block passed to `result.failure` accepts parameters for
+  #               `code:`, `current_user:`, and `name` as described above.
+  # @yieldreturn (void) Use the `result.success` and `result.failure`
+  #               method-call blocks to retrieve data from the method.
+  #
+  # @since 0.1.0
+  # @authenticated Must not be Authenticated.
+  # @param [String] user_name The name of the User for whom a Password Reset
+  #                 Token is to be generated.
+  # @param [User, Hash] current_user Entity representing the currently
+  #                 Authenticated User Entity. This **must** be a Registered
+  #                 User, either as an Entity or as a Hash of attributes.
+  # @return (void)
+  # @example Demonstrating a (refactorable) Controller Action Class #call method
+  #
+  #   def call(params)
+  #     config = CryptIdent.config
+  #     # Remember that reading an Entity stored in session data will in fact
+  #     #   return a *Hash of its attribute values*. This is acceptable.
+  #     other_params = { current_user: session[:current_user] }
+  #     generate_reset_token(params[:name], other_params) do |result|
+  #       result.success do |user:|
+  #         @user = user
+  #         flash[config.success_key] = 'Request for #{user.name} sent'
+  #       end
+  #       result.failure do |code:, current_user:, name:| do
+  #         respond_to_error(code, current_user, name)
+  #       end
+  #     end
+  #   end
+  #
+  #   private
+  #
+  #   def respond_to_error(code, current_user, name)
+  #     # ...
+  #   end
+  # @session_data
+  #   `:current_user` **must not** be a Registered User.
+  # @ubiq_lang
+  #   - Authentication
+  #   - Guest User
+  #   - Password Reset Token
+  #   - Registered User
+  def generate_reset_token(user_name, current_user: nil)
+    other_params = { current_user: current_user }
+    GenerateResetToken.new.call(user_name, other_params) do |result|
+      yield result
+    end
+  end
+
+  # Generate Reset Token for non-Authenticated User
+  #
+  # This class *is not* part of the published API.
+  # @private
+  class GenerateResetToken
+    include Dry::Monads::Result::Mixin
+    include Dry::Matcher.for(:call, with: Dry::Matcher::ResultMatcher)
+
+    LogicError = Class.new(RuntimeError)
+
+    def initialize
+      @current_user = nil
+      @user_name = :unassigned
+    end
+
+    def call(user_name, current_user: nil)
+      init_ivars(user_name, current_user)
+      Success(user: updated_user)
+    rescue LogicError => error
+      # rubocop:disable Security/MarshalLoad
+      error_data = Marshal.load(error.message)
+      # rubocop:enable Security/MarshalLoad
+      Failure(error_data)
+    end
+
+    private
+
+    attr_reader :current_user, :user_name
+
+    def current_user_or_guest
+      guest_user = CryptIdent.config.repository.guest_user
+      current_user = @current_user || guest_user
+      # This will convert a Hash of attributes to an Entity instance. It leaves
+      # an actual Entity value unmolested.
+      @current_user = guest_user.class.new(current_user)
+    end
+
+    def init_ivars(user_name, current_user)
+      @current_user = current_user
+      @user_name = user_name
+    end
+
+    def new_token
+      token_length = CryptIdent.config.token_bytes
+      clear_text_token = SecureRandom.alphanumeric(token_length)
+      Base64.strict_encode64(clear_text_token)
+    end
+
+    def update_repo(user)
+      CryptIdent.config.repository.update(user.id, updated_attribs)
+    end
+
+    def updated_attribs
+      prea = Time.now + CryptIdent.config.reset_expiry
+      { token: new_token, password_reset_expires_at: prea }
+    end
+
+    def updated_user
+      validate_current_user
+      update_repo(user_by_name)
+    end
+
+    def find_user_by_name
+      # will be `nil` if no match found
+      CryptIdent.config.repository.find_by_name(user_name)
+    end
+
+    def user_by_name
+      found_user = find_user_by_name
+      raise LogicError, user_not_found_error unless found_user
+
+      found_user
+    end
+
+    def user_logged_in_error
+      Marshal.dump(code: :user_logged_in, current_user: current_user,
+                   name: :unassigned)
+    end
+
+    def user_not_found_error
+      Marshal.dump(code: :user_not_found, current_user: current_user,
+                   name: user_name)
+    end
+
+    def validate_current_user
+      return current_user if current_user_or_guest.guest?
+
+      raise LogicError, user_logged_in_error
+    end
+  end
+  # Leave the class visible durinig Gem development and testing; hide in an app
+  private_constant :GenerateResetToken if Hanami.respond_to?(:env?)
+end

data/lib/crypt_ident/reset_password.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+require 'bcrypt'
+
+require 'dry/monads/result'
+require 'dry/matcher/result_matcher'
+require 'hanami/utils/kernel'
+
+require_relative './config'
+
+# Include and interact with `CryptIdent` to add authentication to a
+# Hanami controller action.
+#
+# Note the emphasis on *controller action*; this module interacts with session
+# data, which is quite theoretically possible in an Interactor but practically
+# *quite* the PITA. YHBW.
+#
+# @author Jeff Dickey
+# @version 0.2.0
+module CryptIdent
+  # Reset the password for the User associated with a Password Reset Token.
+  #
+  # After a Password Reset Token has been
+  # [generated](#generate_reset_token-instance_method) and sent to a User, that
+  # User would then exercise the Client system and perform a Password Reset.
+  #
+  # Calling `#reset_password` is different than calling `#change_password` in
+  # one vital respect: with `#change_password`, the User involved **must** be
+  # the Current User (as presumed by passing the appropriate User Entity in as
+  # the `current_user:` parameter), whereas `#reset_password` **must not** be
+  # called with *any* User other than the Guest User as the `current_user:`
+  # parameter (and, again presumably, the Current User for the session). How can
+  # we assure ourselves that the request is legitimate for a specific User? By
+  # use of the Token generated by a previous call to `#generate_reset_token`,
+  # which is used _in place of_ a User Name for this request.
+  #
+  # Given a valid set of parameters, and given that the updated User is
+  # successfully persisted, the method calls the **required** block with a
+  # `result` whose `result.success` matcher is yielded a `user:` parameter with
+  # the updated User as its value.
+  #
+  # NOTE: Each of the error returns documented below calls the **required**
+  # block with a `result` whose `result.failure` matcher is yielded a `code:`
+  # parameter as described, and a `token:` parameter that has the same value
+  # as the passed-in `token` parameter.
+  #
+  # If the passed-in `token` parameter matches the `token` field of a record in
+  # the Repository *and* that Token is determined to have Expired, then the
+  # `code:` parameter mentioned earlier will have the value `:expired_token`.
+  #
+  # If the passed-in `token` parameter *does not* match the `token` field of any
+  # record in the Repository, then the `code:` parameter will have the value
+  # `:token_not_found`.
+  #
+  # If the passed-in `current_user:` parameter is a Registered User, then the
+  # `code:` parameter will have the value `:invalid_current_user`.
+  #
+  # In no event are session values, including the Current User, changed. After a
+  # successful Password Reset, the User must Authenticate as usual.
+  #
+  # @yieldparam result [Dry::Matcher::Evaluator] Indicates whether the attempt
+  #               to generate a new Reset Token succeeded or failed. The lock
+  #               **must** call **both** `result.success` and `result.failure`
+  #               methods, where the block passed to `result.success` accepts a
+  #               parameter for `user:`, which is a User Entity with the
+  #               specified `name` value as well as non-`nil` values for its
+  #               `:token` and `:password_reset_expires_at` attributes. The
+  #               block passed to `result.failure` accepts parameters for
+  #               `code:`, `current_user:`, and `name` as described above.
+  # @yieldreturn (void) Use the `result.success` and `result.failure`
+  #               method-call blocks to retrieve data from the method.
+  #
+  # @since 0.1.0
+  # @authenticated Must not be Authenticated.
+  # @param [String] token The Password Reset Token previously communicated to
+  #                       the User.
+  # @param [String] new_password New Clear-Text Password to encrypt and add to
+  #                 return value
+  # @return (void)
+  # @example
+  #   def call(params)
+  #     reset_password(params[:token], params[:new_password],
+  #                    current_user: session[:current_user]) do |result
+  #       result.success do |user:|
+  #         @user = user
+  #         message = "Password for #{user.name} successfully reset."
+  #         flash[CryptIdent.config.success_key] = message
+  #         redirect_to routes.root_path
+  #       end
+  #       result.failure do |code:, token:|
+  #         failure_key = CryptIdent.config.failure_key
+  #         flash[failure_key] = failure_message_for(code, token)
+  #       end
+  #     end
+  #   end
+  #
+  #   private
+  #
+  #   def failure_message_for(code, token)
+  #     # ...
+  #   end
+  # @session_data
+  #   `:current_user` **must not** be a Registered User.
+  # @ubiq_lang
+  #   - Authentication
+  #   - Clear-Text Password
+  #   - Encrypted Password
+  #   - Password Reset Token
+  #   - Registered User
+  #
+  def reset_password(token, new_password, current_user: nil)
+    other_params = { current_user: current_user }
+    ResetPassword.new.call(token, new_password, other_params) do |result|
+      yield result
+    end
+  end
+
+  # Reset Password using previously-sent Reset Token for non-Authenticated User
+  #
+  # This class *is not* part of the published API.
+  # @private
+  class ResetPassword
+    include Dry::Monads::Result::Mixin
+    include Dry::Matcher.for(:call, with: Dry::Matcher::ResultMatcher)
+
+    LogicError = Class.new(RuntimeError)
+
+    def initialize
+      @current_user = :unassigned
+    end
+
+    def call(token, new_password, current_user: nil)
+      init_ivars(current_user)
+      verify_no_current_user(token)
+      user = verify_token(token)
+      Success(user: update(user, new_password))
+    rescue LogicError => error
+      report_failure(error)
+    end
+
+    private
+
+    attr_reader :current_user
+
+    def encrypted(password)
+      BCrypt::Password.create(password)
+    end
+
+    def expired_token?(entity)
+      prea = entity.password_reset_expires_at
+      # Calling this on a non-reset Entity is treated as expiring at the epoch
+      Time.now > Hanami::Utils::Kernel.Time(prea.to_i)
+    end
+
+    # Reek sees a :reek:ControlParameter. Yep.
+    def init_ivars(current_user)
+      guest_user = CryptIdent.config.guest_user
+      current_user ||= guest_user
+      @current_user = guest_user.class.new(current_user)
+    end
+
+    def matching_record_for(token)
+      Array(CryptIdent.config.repository.find_by_token(token)).first
+    end
+
+    def new_attribs(password)
+      { password_hash: encrypted(password), password_reset_expires_at: nil,
+        token: nil }
+    end
+
+    def raise_logic_error(code, token)
+      payload = { code: code, token: token }
+      raise LogicError, Marshal.dump(payload)
+    end
+
+    def report_failure(error)
+      # rubocop:disable Security/MarshalLoad
+      error_data = Marshal.load(error.message)
+      # rubocop:enable Security/MarshalLoad
+      Failure(error_data)
+    end
+
+    def update(user, password)
+      CryptIdent.config.repository.update(user.id, new_attribs(password))
+    end
+
+    def validate_match_and_token(match, token)
+      raise_logic_error(:token_not_found, token) unless match
+      raise_logic_error(:expired_token, token) if expired_token?(match)
+      match
+    end
+
+    def verify_no_current_user(token)
+      return if current_user.guest?
+
+      payload = { code: :invalid_current_user, token: token }
+      raise LogicError, Marshal.dump(payload)
+    end
+
+    def verify_token(token)
+      match = matching_record_for(token)
+      validate_match_and_token(match, token)
+    end
+  end
+  # Leave the class visible durinig Gem development and testing; hide in an app
+  private_constant :ResetPassword if Hanami.respond_to?(:env?)
+end

data/lib/crypt_ident/session_expired.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+# Include and interact with `CryptIdent` to add authentication to a
+# Hanami controller action.
+#
+# Note the emphasis on *controller action*; this module interacts with session
+# data, which is quite theoretically possible in an Interactor but practically
+# *quite* the PITA. YHBW.
+#
+# @author Jeff Dickey
+# @version 0.2.0
+module CryptIdent
+  # Determine whether the Session has Expired due to User inactivity.
+  #
+  # This is one of two methods in `CryptIdent` (the other being
+  # [`#update_session_expiry?`](#update_session_expiry)) which *does not* follow
+  # the `result`/success/failure [monad workflow](#interfaces). This is because
+  # there is no success/failure division in the workflow. Calling the method
+  # determines if the Current User session has Expired. If the passed-in
+  # `:current_user` is a Registered User, then this will return `true` if the
+  # current time is *later than* the passed-in `:expires_at` value; for the
+  # Guest User, it should always return `false`. (Guest User sessions never
+  # expire; after all, what would you change the session state to?).
+  #
+  # The client code is responsible for applying these values to its own actual
+  # session data, as described by the sample session-management code shown in
+  # the README.
+  #
+  # @param [Hash] session_data The Rack session data of interest to the method.
+  #               If the `:current_user` entry is defined, it **must** be either
+  #               a User Entity or `nil`, signifying the Guest User. If the
+  #               `:expires_at` entry is defined, its value in the returned Hash
+  #               *will* be different.
+  #
+  # @since 0.1.0
+  # @authenticated Must be Authenticated.
+  # @return [Boolean]
+  # @example As used in module included by Controller Action Class (see README)
+  #   def validate_session
+  #     updates = update_session_expiry(session)
+  #     if !session_expired?(session)
+  #       session[:expires_at] = updates[:expires_at]
+  #       return
+  #     end
+  #
+  #     # ... sign out and redirect appropriately ...
+  #   end
+  # @session_data
+  #   `:current_user` **must** be an Entity for a Registered User on entry
+  #   `:expires_at`   read during determination of expiry status
+  # @ubiq_lang
+  #   - Authentication
+  #   - Current User
+  #   - Guest User
+  #   - Registered User
+  #   - Session Expiration
+  #
+  def session_expired?(session_data = {})
+    SessionExpired.new.call(session_data)
+  end
+
+  # Determine whether the Session has Expired due to User inactivity.
+  #
+  # This class *is not* part of the published API.
+  # @private
+  class SessionExpired
+    def call(session_data)
+      # Guest sessions never expire.
+      return false if guest_user_from?(session_data)
+
+      expiry_from(session_data) <= Time.now
+    end
+
+    private
+
+    def guest_user_from?(session_data)
+      user = session_data[:current_user] || UserRepository.guest_user
+      # If the `session_data` in fact came from Rack session data, then any
+      # objects (such as a `User` Entity) have been converted to JSON-compatible
+      # types. Hanami Entities can be implicitly converted to and from Hashes of
+      # their attributes, so this part's easy...
+      User.new(user).guest?
+    end
+
+    def expiry_from(session_data)
+      Hanami::Utils::Kernel.Time(session_data[:expires_at].to_i)
+    end
+  end
+  # Leave the class visible durinig Gem development and testing; hide in an app
+  private_constant :SessionExpired if Hanami.respond_to?(:env?)
+end