api_engine_base 0.1.1

data/app/services/api_engine_base/argument_validation/instance_methods.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module ApiEngineBase::ArgumentValidation
+  module InstanceMethods
+    def run_validations!
+      context.valid_arguments = true
+
+      validate_param!
+      validate_compositions!
+      continue_with_logical_code!
+    end
+
+    def continue_with_logical_code!
+      return if @context_validation_failures.nil?
+
+      invalid_argument_keys = @context_validation_failures.keys
+      msg = @context_validation_failures.map { |_k, obj| obj[:msg] }.join(", ")
+      context.fail!(msg:, invalid_argument_hash: @context_validation_failures, invalid_argument_keys:, invalid_arguments: true)
+    end
+
+    def inline_argument_failure!(errors:)
+      errors = errors.to_hash
+      invalid_argument_keys = errors.keys
+      invalid_argument_hash = {}
+      human_readable = []
+
+      errors.each do |k, v|
+        error_message = Array(v).join(", ")
+        invalid_argument_hash[k] = { msg: error_message }
+        human_readable << "#{k}: #{error_message}"
+      end
+
+      msg = "Invalid arguments: #{human_readable.join(", ")}"
+      context.fail!(msg:, invalid_argument_hash:, invalid_argument_keys:, invalid_arguments: true)
+    end
+
+    def validate_param!
+      self.class.validate_params.each do |metadata|
+        value = context.public_send(metadata[:name])
+        use_length = metadata[:length]
+        if metadata[:required] && value.nil?
+          __failed_argument_validation(msg: "Parameter [#{metadata[:name]}] is required but not present", argument: metadata[:name], metadata:)
+        end
+
+        if value.nil? && metadata[:default]
+          context.public_send(:"#{metadata[:name]}=", metadata[:default])
+          next
+        elsif value.nil?
+          next
+        end
+
+        if is_a = metadata[:is_a]
+          if Array(is_a).none? { _1 === value }
+            __failed_argument_validation(msg: "Parameter [#{metadata[:name]}] must be of type #{is_a}. Given #{value.class} [#{value}]", argument: metadata[:name], metadata:)
+          end
+        end
+
+        if metadata[:is_one]
+          if Array(metadata[:is_one]).none? { _1 == value }
+            __failed_argument_validation(msg: "Parameter [#{metadata[:name]}] must be one of #{Array(metadata[:is_one])}. Given #{value}", argument: metadata[:name], metadata:)
+          end
+        end
+
+        validate_sign!(name: metadata[:name], value:, sign: "lt", validation: metadata[:lte], use_length:, metadata:) { (use_length ? value.length : value) <= _1 }
+        validate_sign!(name: metadata[:name], value:, sign: "lte", validation: metadata[:lt], use_length:, metadata:) { (use_length ? value.length : value) < _1 }
+        validate_sign!(name: metadata[:name], value:, sign: "eq", validation: metadata[:eq], use_length:, metadata:) { (use_length ? value.length : value) == _1 }
+        validate_sign!(name: metadata[:name], value:, sign: "gte", validation: metadata[:gte], use_length:, metadata:) { (use_length ? value.length : value) >= _1 }
+        validate_sign!(name: metadata[:name], value:, sign: "gt", validation: metadata[:gt], use_length:, metadata:) { (use_length ? value.length : value) > _1 }
+      end
+    end
+
+    def validate_compositions!
+      self.class.compositions.each do |type, metadata|
+        value_list = {}
+
+        metadata[:keys].each do |argument|
+          value = context.public_send(argument)
+          next if value.nil?
+
+          value_list[argument] = value
+        end
+
+        composition_result = metadata[:validation_proc].(value_list.count, value_list.keys)
+
+        next if value_list.count == 0 && !metadata[:required]
+
+        if !composition_result[:is_valid]
+          composition_result[:message]
+          context.client_composite_error = composition_result[:requirement]
+          msg = "Composite Key failure for #{type} [#{metadata[:name]}]. #{composition_result[:message]}. Provided values for the following keys: #{value_list.keys}. Available keys #{metadata[:keys]}"
+          __failed_argument_validation(msg:, argument: metadata[:name], metadata: ,error: ApiEngineBase::ServiceBase::CompositionValidationError)
+          next
+        end
+
+        if metadata[:delegation]
+          context.public_send("#{metadata[:name]}=", value_list.first[1])
+          context.public_send("#{metadata[:name]}_key=", value_list.first[0])
+        end
+      end
+    end
+
+    def validate_sign!(name:, value:, sign:, validation:, use_length:, metadata:)
+      return if validation.nil?
+      return if yield(validation)
+
+      __failed_argument_validation(metadata:, msg: "Parameter [#{name}]#{ " lengths" if use_length} must be #{sign} to #{validation}. Given #{value}", argument: name)
+    end
+
+    def __failed_argument_validation(msg:, argument:, metadata:, error: ApiEngineBase::ServiceBase::ArgumentValidationError)
+      case self.class.on_argument_validation_assigned
+      when :raise
+        raise error, msg
+      when :fail_early
+        @context_validation_failures ||= {}
+        @context_validation_failures[argument] = {
+          msg: msg,
+          required: metadata[:requirement],
+          is_a: metadata[:is_a],
+        }
+        # When gracefully failing, it will find all failures first before setting appropriate
+        # context variables -- Check out continue_with_logical_code!
+      else
+        context.invalid_arguments = true
+        log_warn(msg)
+      end
+    end
+
+    def sanitize_params
+      self.class.sensitive_params.each do |param|
+        next if context.send(param).nil?
+
+        context.send("#{param}=","[FILTERED]")
+      end
+    end
+  end
+end

data/app/services/api_engine_base/argument_validation.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module ApiEngineBase::ArgumentValidation
+  class NameConflictError < ApiEngineBase::ServiceBase::ConfigurationError; end
+  class NestedDuplicateTypeError < ApiEngineBase::ServiceBase::ConfigurationError; end
+
+  def self.included(base)
+    base.extend(ApiEngineBase::ArgumentValidation::ClassMethods)
+    base.include(ApiEngineBase::ArgumentValidation::InstanceMethods)
+  end
+end

data/app/services/api_engine_base/jwt/authenticate_user.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module ApiEngineBase::Jwt
+  class AuthenticateUser < ApiEngineBase::ServiceBase
+
+    validate :token, is_a: String, required: true, sensitive: true
+    validate :bypass_email_validation, is_one: [true, false], default: false
+
+    def call
+      result = Decode.(token:)
+
+      if result.failure?
+        context.fail!(msg: "Unauthorized Access. Invalid Authorization token")
+      end
+      payload = result.payload
+
+      validate_expires_at!(expires_at: payload[:expires_at])
+
+      user = User.find(payload[:user_id]) rescue nil
+      if user.nil?
+        log_warn("user_id [#{payload[:user_id]}] was not found. Cannot Continue")
+        context.fail!(msg: "Unauthorized Access. Invalid Authorization token")
+      end
+
+      if user.verifier_token == payload[:verifier_token]
+        context.user = user
+      else
+        context.fail!(msg: "Unauthorized Access. Token is no longer valid")
+      end
+
+      email_validation_required!(user:)
+    end
+
+    def validate_expires_at!(expires_at:)
+      if expires_at.nil?
+        log_warn("expires_at payload is missing from the JWT token. Cannot continue")
+        context.fail!(msg: "Unauthorized Access. Invalid Authorization token")
+      end
+
+      expires_time = Time.at(expires_at) rescue nil
+
+      if expires_time.nil?
+        log_warn("expires_at payload cannot be parsed. Cannot continue")
+        context.fail!(msg: "Unauthorized Access. Invalid Authorization token")
+      end
+
+      if expires_time < Time.now
+        log_warn("expires_at is no longer valid. Must request new token")
+        context.fail!(msg: "Unauthorized Access. Invalid Authorization token")
+      end
+    end
+
+    def email_validation_required!(user:)
+      return unless ApiEngineBase.config.login.plain_text.email_verify?
+
+      if bypass_email_validation
+        log_info("Bypassing email validation without checking if user should be able to continue")
+        return
+      end
+
+      return if user.email_validated
+
+      log_info("User's email is not yet validated.")
+      result = ApiEngineBase::LoginStrategy::PlainText::EmailVerification::Required.(user:)
+
+      if result.required
+        context.fail!(msg: "User's Email must be validated before they can continue")
+      end
+    end
+  end
+end

data/app/services/api_engine_base/jwt/decode.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "jwt"
+
+module ApiEngineBase::Jwt
+  class Decode < ApiEngineBase::ServiceBase
+
+    validate :token, is_a: String, required: true, sensitive: true
+
+    def call
+      data = JWT.decode(token, ApiEngineBase.config.jwt.hmac_secret, true, { algorithm: "HS256" })
+
+      context.payload = data[0].with_indifferent_access
+      context.headers = data[1].with_indifferent_access
+    rescue JWT::DecodeError => e
+      log_error(e)
+
+      context.fail!(msg: "Invalid Token")
+    end
+  end
+end

data/app/services/api_engine_base/jwt/encode.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "jwt"
+
+module ApiEngineBase::Jwt
+  class Encode < ApiEngineBase::ServiceBase
+
+    validate :payload, is_a: Hash, required: true
+    validate :header, is_a: Hash, required: false
+
+    def call
+      context.token = JWT.encode(payload, ApiEngineBase.config.jwt.hmac_secret, "HS256", header || {})
+    end
+  end
+end

data/app/services/api_engine_base/jwt/login_create.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module ApiEngineBase::Jwt
+  class LoginCreate < ApiEngineBase::ServiceBase
+    on_argument_validation :fail_early
+
+    validate :user, is_a: User, required: true
+
+    def call
+      context.token = Encode.(payload:).token
+    end
+
+    def payload
+      {
+        expires_at: ApiEngineBase.config.jwt.ttl.from_now.to_i,
+        user_id: user.id,
+        verifier_token: user.retreive_verifier_token!,
+      }
+    end
+  end
+end

data/app/services/api_engine_base/jwt/time_delay_token.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module ApiEngineBase::Jwt
+  class TimeDelayToken < ApiEngineBase::ServiceBase
+    on_argument_validation :fail_early
+
+    validate :expires_in, is_a: ActiveSupport::Duration, required: true
+
+    def call
+      context.token = Encode.(payload:).token
+    end
+
+    def payload
+      { expires_in: expires_in }
+    end
+  end
+end

data/app/services/api_engine_base/login_strategy/plain_text/create.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module ApiEngineBase::LoginStrategy::PlainText
+  class Create < ApiEngineBase::ServiceBase
+    on_argument_validation :fail_early
+
+    EASY_GETTER = ApiEngineBase.config.login.plain_text
+
+    validate :first_name, is_a: String, required: true
+    validate :last_name, is_a: String, required: true
+    validate :username, is_a: String, required: true
+    validate :email, length: true, lt: EASY_GETTER.email_length_max, gt: EASY_GETTER.email_length_min, is_a: String, required: true, sensitive: true
+    validate :password, length: true, lt: EASY_GETTER.password_length_max, gt: EASY_GETTER.password_length_min, is_a: String, required: true, sensitive: true
+    validate :password_confirmation, is_a: String, required: true, sensitive: true
+
+    def call
+      unless email =~ URI::MailTo::EMAIL_REGEXP
+        inline_argument_failure!(errors: { email: "Invalid email address" })
+      end
+
+      username_validity = ApiEngineBase::Username::Available.(username:)
+      if !username_validity.valid
+        inline_argument_failure!(errors: { username: "Username is invalid. #{ApiEngineBase.config.username.username_failure_message}" })
+      end
+
+      user = User.new(
+        first_name:,
+        last_name:,
+        username:,
+        email:,
+        password:,
+        password_confirmation:,
+      )
+
+      if user.save
+        context.user = user
+      else
+        inline_argument_failure!(errors: user.errors)
+      end
+    end
+  end
+end

data/app/services/api_engine_base/login_strategy/plain_text/email_verification/generate.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module ApiEngineBase::LoginStrategy::PlainText::EmailVerification
+  class Generate < ApiEngineBase::ServiceBase
+    validate :user, is_a: User, required: true
+
+    def call
+      result = ApiEngineBase::Secrets::Generate.(
+        user:,
+        secret_length: email_verify.verify_code_length,
+        reason: ApiEngineBase::Secrets::EMAIL_VERIFICIATION,
+        use_count_max: 1,
+        death_time: email_verify.verify_code_link_valid_for,
+        type: ApiEngineBase::Secrets::NUMERIC,
+        cleanse: true,
+      )
+
+      if result.failure?
+        context.fail!(msg: "Secret Generation is not available at this time")
+      end
+
+      context.secret = result.secret
+    end
+
+    def email_verify
+      ApiEngineBase.config.login.plain_text.email_verify
+    end
+  end
+end

data/app/services/api_engine_base/login_strategy/plain_text/email_verification/required.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module ApiEngineBase::LoginStrategy::PlainText::EmailVerification
+  class Required < ApiEngineBase::ServiceBase
+    validate :user, is_a: User, required: true
+
+    def call
+      context.reqired_after_time = reqired_after_time
+      context.required = Time.now > reqired_after_time
+    end
+
+    def reqired_after_time
+      user.created_at + email_verify.verify_email_required_within
+    end
+
+    def email_verify
+      ApiEngineBase.config.login.plain_text.email_verify
+    end
+  end
+end

data/app/services/api_engine_base/login_strategy/plain_text/email_verification/send.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module ApiEngineBase::LoginStrategy::PlainText::EmailVerification
+  class Send < ApiEngineBase::ServiceBase
+    on_argument_validation :fail_early
+
+    validate :user, is_a: User, required: true
+
+    def call
+      result = Generate.(user:)
+      if result.failure?
+        context.fail!(msg: result.msg)
+      end
+
+      begin
+        ApiEngineBase::EmailVerificationMailer.verify_email(user.email, user, result.secret).deliver
+      rescue StandardError => e
+        log_error("Failed to send message to [#{user.id}]: #{e.message}")
+        context.fail!(msg: "Unable to send email. Please try again later", status: 500)
+      end
+    end
+  end
+end

data/app/services/api_engine_base/login_strategy/plain_text/email_verification/verify.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module ApiEngineBase::LoginStrategy::PlainText::EmailVerification
+  class Verify < ApiEngineBase::ServiceBase
+    on_argument_validation :fail_early
+
+    validate :user, is_a: User, required: true
+    validate :code, is_a: String, required: true
+
+    def call
+      result = ApiEngineBase::Secrets::Verify.(secret: code, reason: ApiEngineBase::Secrets::EMAIL_VERIFICIATION)
+      if result.failure?
+        inline_argument_failure!(errors: { code:  "Incorrect verification code provided" })
+      end
+
+      if result.user != user
+        log_warn("Yikes! The logged in user does not match the correct code. Kick them back out and do not verify")
+        inline_argument_failure!(errors: { code:  "Incorrect verification code provided" })
+      end
+
+      user.update(email_validated: true)
+    end
+  end
+end

data/app/services/api_engine_base/login_strategy/plain_text/login.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module ApiEngineBase::LoginStrategy::PlainText
+  class Login < ApiEngineBase::ServiceBase
+    on_argument_validation :fail_early
+
+    one_of(:login_key, required: true) do
+      validate :username, is_a: String, sensitive: true
+      validate :email, is_a: String, sensitive: true
+    end
+    validate :password, is_a: String, required: true, sensitive: true
+
+    def call
+      if user.nil?
+        log_warn("Login attempted with [#{login_key_key}] => [#{login_key}]. Resource not found")
+        credential_mismatch!
+      end
+
+      if user.authenticate(password)
+        user.successful_login += 1
+        user.password_consecutive_fail = 0
+        user.save
+      else
+        user.password_consecutive_fail += 1
+        user.save
+        log_warn("Valid #{login_key_key}. Incorrect password. Consecutive Password failures: #{user.password_consecutive_fail}")
+        credential_mismatch!
+      end
+
+      context.user = user
+
+      result = ApiEngineBase::Jwt::LoginCreate.(user:)
+      if result.failure?
+        context.fail!(msg: "Failed to generate Authorization. Please Try again")
+        return
+      end
+
+      context.token = result.token
+    end
+
+    def credential_mismatch!
+      msg = "Unauthorized Access. Incorrect Credentials"
+      inline_argument_failure!(errors: { login_key_key => msg, password: msg })
+    end
+
+    def user
+      @user ||= User.where(login_key_key => login_key).first
+    end
+  end
+end

data/app/services/api_engine_base/secrets/cleanse.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module ApiEngineBase::Secrets
+  class Cleanse < ApiEngineBase::ServiceBase
+    validate :user, is_a: User, required: true
+    validate :reason, is_one: ALLOWED_SECRET_REASONS, required: true
+
+    def call
+      secrets = UserSecret.where(user:, reason:)
+      count = secrets.delete_all
+      log_info("Cleansed #{count} #{reason} secret(s) from the store for user [#{user.id}]")
+    end
+  end
+end

data/app/services/api_engine_base/secrets/generate.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module ApiEngineBase::Secrets
+  class Generate < ApiEngineBase::ServiceBase
+    MAX_RETRY = 10
+
+    validate :user, is_a: User, required: true
+    validate :secret_length, is_a: Integer, gte: 4, lte: 64, required: true
+    validate :reason, is_one: ALLOWED_SECRET_REASONS, required: true
+    validate :type, is_one: ALLOWED_SECRET_TYPES, default: DEFAULT_SECRET_TYPE
+    validate :extra, is_a: String, length: true, lt: 256
+    validate :cleanse, is_one: [true, false], default: false
+    at_least_one(:death, required: true) do
+      validate :death_time, is_a: ActiveSupport::Duration, gte: 10.seconds
+      validate :use_count_max, is_a: Integer, gte: 1
+    end
+
+    def call
+      if cleanse && @attempts.nil?
+        # if this fails ... so be it
+        Cleanse.(user:, reason:)
+      end
+
+      @attempts ||= 1
+      record = UserSecret.create!(**db_params)
+
+      context.record = record
+      context.secret = record.secret
+    rescue ActiveRecord::RecordNotUnique => e
+      if @attempts < MAX_RETRY
+        @attempts += 1
+        log_warn("Duplicate Secret was generated. Attempting to retry: #{@attempts} of #{MAX_RETRY}")
+        retry
+      else
+        log_error("Duplicate Secret was generated. Exhausted Max attempts of #{MAX_RETRY}.")
+        context.fail!(msg: "Failed to generate Secret. Cannot Continue")
+      end
+    end
+
+    def db_params
+      {
+        death_time: death_time&.from_now,
+        use_count_max:,
+        extra:,
+        reason:,
+        secret: generate_secret,
+        user:,
+      }.compact
+    end
+
+    def generate_secret
+      case type
+      when :numeric
+        secret_length.times.map { SecureRandom.rand(0...10) }.join
+      when :alphanumeric, :hex
+        SecureRandom.public_send(type, secret_length)
+      when :uuid
+        SecureRandom.public_send(type)
+      end
+    end
+  end
+end

data/app/services/api_engine_base/secrets/verify.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module ApiEngineBase::Secrets
+  class Verify < ApiEngineBase::ServiceBase
+    validate :secret, is_a: String, required: true, sensitive: true
+    validate :reason, is_one: ALLOWED_SECRET_REASONS, required: true
+    validate :access_count, is_one: [true, false], default: false
+
+    def call
+      record = UserSecret.find_record(secret:, reason:, access_count:)
+
+      if record[:found] == false
+        context.fail!(record:, msg: "Secret not found")
+      end
+
+      if record[:valid] == false
+        if ApiEngineBase.config.delete_secret_after_invalid
+          record[:record].destroy
+        end
+
+        context.fail!(record:, msg: "Secret is invalid. #{record[:record].invalid_reason.join(" ")}")
+      end
+
+      context.user = record[:user]
+    end
+  end
+end

data/app/services/api_engine_base/secrets.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module ApiEngineBase::Secrets
+  ALLOWED_SECRET_REASONS = [
+    EMAIL_VERIFICIATION = :email_verification,
+    SSO = :sso,
+  ]
+
+  ALLOWED_SECRET_TYPES = [
+    DEFAULT_SECRET_TYPE = ALPHANUMERIC = :alphanumeric,
+    HEX = :hex,
+    NUMERIC = :numeric,
+    UUID = :uuid,
+  ]
+end