crypt_ident 0.2.1

data/lib/crypt_ident/sign_in.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require 'bcrypt'
+
+require 'dry/monads/result'
+require 'dry/matcher/result_matcher'
+
+# 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
+  # Attempt to Authenticate a User, passing in an Entity for that User (which
+  # **must** contain a `password_hash` attribute), and a Clear-Text Password.
+  # It also passes in the Current User.
+  #
+  # If the Current User is not a Registered User, then Authentication of the
+  # specified User Entity against the specified Password is accomplished by
+  # comparing the User Entity's `password_hash` attribute to the passed-in
+  # Clear-Text Password.
+  #
+  # The 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 the Authenticated User (and is the
+  # same Entity as the `user` parameter passed in to `#sign_in`).
+  #
+  # On failure, the `result.failure` call will yield a `code:` parameter to its
+  # block, which indicates the cause of failure as follows:
+  #
+  # If the specified password *did not* match the passed-in `user` Entity, then
+  # the `code:` for failure will be `:invalid_password`.
+  #
+  # If the specified `user` was not a Registered User, then the `code:` for
+  # failure will be `:user_is_guest`.
+  #
+  # If the specified `current_user` is *neither* the Guest User *nor* the `user`
+  # passed in as a parameter to `#sign_in`, then the `code:` for failure will be
+  # `:illegal_current_user`.
+  #
+  # On *success,* the Controller-level client code **must** set:
+  #
+  # * `session[:expires_at]` to the expiration time for the session. This is
+  #   ordinarily computed by adding the current time as returned by `Time.now`
+  #   to the `:session_expiry` value in the current configuration.
+  # * `session[:current_user]` to tne returned *Entity* for the successfully
+  #   Authenticated User. This is to eliminate possible repeated reads of the
+  #   Repository.
+  #
+  # On *failure,* the Controller-level client code **should** set:
+  #
+  # * `session[:expires_at]` to some sufficiently-past time to *always* trigger
+  #   `#session_expired?`; `Hanami::Utils::Kernel.Time(0)` does this quite well
+  #   (returning midnight GMT on 1 January 1970, converted to local time).
+  # * `session[:current_user]` to either `nil` or the Guest User.
+  #
+  # @since 0.1.0
+  # @authenticated Must not be Authenticated as a different User.
+  # @param [User] user_in Entity representing a User to be Authenticated.
+  # @param [String] password Claimed Clear-Text Password for the specified User.
+  # @param [User, nil] current_user Entity representing the currently
+  #               Authenticated User Entity; either `nil` or the Guest User if
+  #               none.
+  # @return (void) Use the `result` yield parameter to determine results.
+  # @yieldparam result [Dry::Matcher::Evaluator] Indicates whether the attempt
+  #               to Authenticate a User succeeded or failed. Block **must**
+  #               call **both** `result.success` and `result.failure` methods,
+  #               where the block passed to `result.success` accepts a parameter
+  #               for `user:` (which is the newly-created User Entity). The
+  #               block passed to `result.failure` accepts a parameter for
+  #               `code:`, which is a Symbol reporting the reason for the
+  #               failure (as described above).
+  # @yieldreturn [void]
+  # @example As in a Controller Action Class (which you'd refactor somewhat):
+  #   def call(params)
+  #     user = UserRepository.new.find_by_email(params[:email])
+  #     guest_user = CryptIdent.config.guest_user
+  #     return update_session_data(guest_user, 0) unless user
+  #
+  #     current_user = session[:current_user]
+  #     config = CryptIdent.config
+  #     sign_in(user, params[:password], current_user: current_user) do |result|
+  #       result.success do |user:|
+  #         @user = user
+  #         update_session_data(user, Time.now)
+  #         flash[config.success_key] = "User #{user.name} signed in."
+  #         redirect_to routes.root_path
+  #       end
+  #
+  #       result.failure do |code:|
+  #         update_session_data(guest_user, config, 0)
+  #         flash[config.error_key] = error_message_for(code)
+  #       end
+  #     end
+  #
+  #   private
+  #
+  #   def error_message_for(code)
+  #     # ...
+  #   end
+  #
+  #   def update_session_data(user, time)
+  #     session[:current_user] = user
+  #     expiry = Time.now + CryptIdent.config.session_expiry
+  #     session[:expires_at] == Hanami::Utils::Kernel.Time(expiry)
+  #   end
+  # @session_data
+  #   `:current_user` **must not** be a Registered User
+  # @ubiq_lang
+  #   - Authenticated User
+  #   - Authentication
+  #   - Clear-Text Password
+  #   - Entity
+  #   - Guest User
+  #   - Registered User
+  #
+  def sign_in(user_in, password, current_user: nil)
+    params = { user: user_in, password: password, current_user: current_user }
+    SignIn.new.call(params) { |result| yield result }
+  end
+
+  # Reworked sign-in logic for `CryptIdent`, per Issue #9.
+  #
+  # This class *is not* part of the published API.
+  # @private
+  class SignIn
+    include Dry::Monads::Result::Mixin
+    include Dry::Matcher.for(:call, with: Dry::Matcher::ResultMatcher)
+
+    # As a reminder, calling `Failure` *does not* interrupt control flow *or*
+    # prevent a future `Success` call from overriding the result. This is one
+    # case where raising *and catching* an exception is Useful
+    def call(user:, password:, current_user: nil)
+      set_ivars(user, password, current_user)
+      validate_call_params
+      Success(user: user)
+    rescue LogicError => error
+      Failure(code: error.message.to_sym)
+    end
+
+    private
+
+    attr_reader :current_user, :password, :user
+
+    LogicError = Class.new(RuntimeError)
+    private_constant :LogicError
+
+    def illegal_current_user?
+      !current_user.guest? && !same_user?
+    end
+
+    def password_comparator
+      BCrypt::Password.new(user.password_hash)
+    end
+
+    def same_user?
+      current_user.name == user.name
+    end
+
+    # Reek complains about a :reek:ControlParameter for `current`. Never mind.
+    def set_ivars(user, password, current)
+      @user = user
+      @password = password
+      guest_user = CryptIdent.config.guest_user
+      current ||= guest_user
+      @current_user = guest_user.class.new(current)
+    end
+
+    def validate_call_params
+      raise LogicError, 'user_is_guest' if user.guest?
+      raise LogicError, 'illegal_current_user' if illegal_current_user?
+
+      verify_matching_password
+    end
+
+    def verify_matching_password
+      match = password_comparator == password
+      raise LogicError, 'invalid_password' unless match
+    end
+  end
+  # Leave the class visible durinig Gem development and testing; hide in an app
+  private_constant :SignIn if Hanami.respond_to?(:env?)
+end

data/lib/crypt_ident/sign_out.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require 'dry/monads/result'
+require 'dry/matcher/result_matcher'
+
+# 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
+  # Sign out a previously Authenticated User.
+  #
+  # The method *requires* a block, to which a `result` indicating success or
+  # failure is yielded. (Presently, any call to `#sign_out` results in success.)
+  # That block **must** in turn call **both** `result.success` and
+  # `result.failure` (even though no failure is implemented) to handle success
+  # and failure results, respectively. On success, the block yielded to by
+  # `result.success` is called without parameters.
+  #
+  # @since 0.1.0
+  # @authenticated Should be Authenticated.
+  # @param [User, `nil`] current_user Entity representing the currently
+  #               Authenticated User Entity. This **should** be a Registered
+  #               User.
+  # @return (void)
+  # @yieldparam result [Dry::Matcher::Evaluator] Normally, used to report
+  #               whether a method succeeded or failed. The block **must**
+  #               call **both** `result.success` and `result.failure` methods.
+  #               In practice, parameters to both may presently be safely
+  #               ignored.
+  # @yieldreturn [void]
+  #
+  # @example Controller Action Class method example resetting values
+  #   def call(_params)
+  #     sign_out(session[:current_user]) do |result|
+  #       result.success do
+  #         session[:current_user] = CryptIdent.config.guest_user
+  #         session[:expires_at] = Hanami::Utils::Kernel.Time(0)
+  #       end
+  #
+  #       result.failure { next }
+  #     end
+  #   end
+  #
+  # @example Controller Action Class method example deleting values
+  #   def call(_params)
+  #     sign_out(session[:current_user]) do |result|
+  #       result.success do
+  #         session[:current_user] = nil
+  #         session[:expires_at] = nil
+  #       end
+  #
+  #       result.failure { next }
+  #     end
+  #   end
+  #
+  # @session_data
+  #   See method description above.
+  #
+  # @ubiq_lang
+  #   - Authenticated User
+  #   - Authentication
+  #   - Controller Action Class
+  #   - Entity
+  #   - Guest User
+  #   - Interactor
+  #   - Repository
+  #
+  def sign_out(current_user:)
+    SignOut.new.call(current_user: current_user) { |result| yield result }
+  end
+
+  # Sign-out logic for `CryptIdent`, per Issue #9.
+  #
+  # This class *is not* part of the published API.
+  # @private
+  class SignOut
+    include Dry::Monads::Result::Mixin
+    include Dry::Matcher.for(:call, with: Dry::Matcher::ResultMatcher)
+
+    # This method exists, despite YAGNI, to provide for future expansion of
+    # features like analytics. More importantly, it provides an API congruent
+    # with that of the (reworked) `#sign_up` and `#sign_in` methods.
+    def call(current_user:)
+      _ = current_user # presently ignored
+      Success()
+    end
+  end
+  # Leave the class visible durinig Gem development and testing; hide in an app
+  private_constant :SignOut if Hanami.respond_to?(:env?)
+end

data/lib/crypt_ident/sign_up.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+require 'bcrypt'
+
+require 'dry/monads/result'
+require 'dry/matcher/result_matcher'
+
+# 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
+  # Persist a new User to a Repository based on passed-in attributes, where the
+  # resulting Entity (on success) contains a  `:password_hash` attribute
+  # containing the encrypted value of a **random** Clear-Text Password; any
+  # `password` value within `attribs` is ignored.
+  #
+  # The 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 the newly-created User Entity.
+  #
+  # If the call fails, the `result.success` block is yielded to, and passed a
+  # `code:` parameter, which will contain one of the following symbols:
+  #
+  # * `:current_user_exists` indicates that the method was called with a
+  # Registered User as the `current_user` parameter.
+  # * `:user_already_created` indicates that the specified `name` attribute
+  # matches a record that already exists in the underlying Repository.
+  # * `:user_creation_failed` indicates that the Repository was unable to create
+  # the new User for some other reason, such as an internal error.
+  #
+  # **NOTE** that the incoming `params` are expected to have been whitelisted at
+  # the Controller Action Class level.
+  #
+  # @since 0.1.0
+  # @authenticated Must not be Authenticated.
+  # @param [Hash] attribs Hash-like object of attributes for new User Entity and
+  #               record. **Must** include `name` and  any other attributes
+  #               required by the underlying database schema. Any `password`
+  #               attribute will be ignored.
+  # @param [User, nil] current_user Entity representing the current
+  #               Authenticated User, or the Guest User. A value of `nil` is
+  #               treated as though the Guest User had been specified.
+  # @return (void) Use the `result` yield parameter to determine results.
+  # @yieldparam result [Dry::Matcher::Evaluator] Indicates whether the attempt
+  #               to create a new User succeeded or failed. Block **must**
+  #               call **both** `result.success` and `result.failure` methods,
+  #               where the block passed to `result.success` accepts a parameter
+  #               for `user:` (which is the newly-created User Entity). The
+  #               block passed to `result.failure` accepts a parameter for
+  #               `code:`, which is a Symbol reporting the reason for the
+  #               failure (as described above).
+  # @example in a Controller Action Class
+  #   def call(_params)
+  #     sign_up(params, current_user: session[:current_user]) do |result|
+  #       result.success do |user:|
+  #         @user = user
+  #         message = "#{user.name} successfully created. You may sign in now."
+  #         flash[CryptIdent.config.success_key] = message
+  #         redirect_to routes.root_path
+  #       end
+  #
+  #       result.failure do |code:|
+  #         # `#error_message_for` is a method on the same class, not shown
+  #         failure_key = CryptIdent.config.failure_key
+  #         flash[failure_key] = error_message_for(code, params)
+  #       end
+  #     end
+  #   end
+  # @session_data
+  #   `:current_user` **must not** be a Registered User.
+  # @ubiq_lang
+  #   - Authentication
+  #   - Clear-Text Password
+  #   - Entity
+  #   - Guest User
+  #   - Registered User
+  def sign_up(attribs, current_user:)
+    SignUp.new.call(attribs, current_user: current_user) do |result|
+      yield result
+    end
+  end
+
+  # Reworked sign-up logic for `CryptIdent`, per Issue #9
+  #
+  # This class *is not* part of the published API.
+  # @private
+  class SignUp
+    include Dry::Monads::Result::Mixin
+    include Dry::Matcher.for(:call, with: Dry::Matcher::ResultMatcher)
+
+    def call(attribs, current_user:)
+      return failure_for(:current_user_exists) if current_user?(current_user)
+
+      create_result(all_attribs(attribs))
+    end
+
+    private
+
+    def all_attribs(attribs)
+      new_attribs.merge(attribs)
+    end
+
+    # XXX: This has a Flog score of 9.8. Truly simplifying PRs welcome.
+    def create_result(attribs_in)
+      user = CryptIdent.config.repository.create(attribs_in)
+      success_for(user)
+    rescue Hanami::Model::UniqueConstraintViolationError
+      failure_for(:user_already_created)
+    rescue Hanami::Model::Error
+      failure_for(:user_creation_failed)
+    end
+
+    def current_user?(user)
+      guest_user = CryptIdent.config.guest_user
+      user ||= guest_user
+      !guest_user.class.new(user).guest?
+    end
+
+    def failure_for(code)
+      Failure(code: code)
+    end
+
+    def hashed_password(password_in)
+      password = password_in.to_s.strip
+      password = SecureRandom.alphanumeric(64) if password.empty?
+      ::BCrypt::Password.create(password)
+    end
+
+    def new_attribs
+      prea = Time.now + CryptIdent.config.reset_expiry
+      {
+        password_hash: hashed_password(nil),
+        password_reset_expires_at: prea,
+        token: new_token
+      }
+    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 success_for(user)
+      Success(user: user)
+    end
+  end
+  # Leave the class visible durinig Gem development and testing; hide in an app
+  private_constant :SignUp if Hanami.respond_to?(:env?)
+end

data/lib/crypt_ident/update_session_expiry.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+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 Hash containing an updated Session Expiration timestamp, which
+  # can then be used for session management.
+  #
+  # This is one of two methods in `CryptIdent` (the other being
+  # [`#session_expired?`](#session-expired)) 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
+  # only makes sense if there is a Registered User as the Current User, but *all
+  # this method does* is build a Hash with `:current_user` and `:expires_at`
+  # entries. The returned `:current_user` is the passed-in `:current_user` if a
+  # Registered User, or the Guest User if not. The returned `:updated_at` value,
+  # for a Registered User, is the configured Session Expiry added to the current
+  # time, and for the Guest User, a time far enough in the future that any call
+  # to `#session_expired?` will be highly unlikely to ever return `true`.
+  #
+  # 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 [Hash] A `Hash` with entries to be used to update session data.
+  #                `expires_at` will have a value of the current time plus the
+  #                configuration-specified `session_expiry` offset *if* the
+  #                supplied `:current_user` value is a Registered User;
+  #                otherwise it will have a value far enough in advance of the
+  #                current time (e.g., by 100 years) that the
+  #                `#session_expired?` method is highly unlikely to ever return
+  #                `true`. The `:current_user` value will be the passed-in
+  #                `session_data[:current_user]` value if that represents a
+  #                Registered User, or the Guest User otherwise.
+  #
+  # @example As used in module included by Controller Action Class (see README)
+  #   def validate_session
+  #     if !session_expired?(session)
+  #       updates = update_session_expiry(session)
+  #       session[:expires_at] = updates[:expires_at]
+  #       return
+  #     end
+  #
+  #     # ... sign out and redirect appropriately ...
+  #   end
+  # @session_data
+  #   `:current_user` **must** be a User Entity. `nil` is accepted to indicate
+  #                   the Guest User
+  #   `:expires_at`   set to the session-expiration time on exit, which will be
+  #                   arbitrarily far in the future for the Guest User.
+  # @ubiq_lang
+  #   - Authentication
+  #   - Guest User
+  #   - Registered User
+  #   - Session Expiration
+  #   - User
+  #
+  def update_session_expiry(session_data = {})
+    UpdateSessionExpiry.new.call(session_data)
+  end
+
+  # Produce an updated Session Expiration timestamp, to support session
+  # management and prevent prematurely Signing Out a User.
+  #
+  # This class *is not* part of the published API.
+  # @private
+  class UpdateSessionExpiry
+    def initialize
+      config = CryptIdent.config
+      @guest_user = config.guest_user
+      @session_expiry = config.session_expiry
+    end
+
+    def call(session_data = {})
+      if guest_user?(session_data)
+        session_data.merge(guest_data)
+      else
+        session_data.merge(updated_expiry)
+      end
+    end
+
+    private
+
+    attr_reader :guest_user, :session_expiry
+
+    GUEST_YEARS = 100
+    SECONDS_PER_YEAR = 31_536_000
+    private_constant :GUEST_YEARS, :SECONDS_PER_YEAR
+
+    def guest_data
+      { expires_at: Time.now + GUEST_YEARS * SECONDS_PER_YEAR }
+    end
+
+    def guest_user?(session_data)
+      user = session_data[:current_user] || 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 updated_expiry
+      { expires_at: Time.now + session_expiry }
+    end
+  end
+  # Leave the class visible durinig Gem development and testing; hide in an app
+  private_constant :UpdateSessionExpiry if Hanami.respond_to?(:env?)
+end