api_engine_base 0.1.1

data/app/services/api_engine_base/service_base.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "interactor"
+
+class ApiEngineBase::ServiceBase
+  class ServiceBaseError < ApiEngineBase::Error; end;
+  class ValidationError < ServiceBaseError; end;
+  class ConfigurationError < ServiceBaseError; end;
+
+  class NameConflictError < ApiEngineBase::Error; end
+  class DefaultValueError < ApiEngineBase::Error; end
+  class OneOfError < ApiEngineBase::Error; end
+  class NestedOneOfError < ApiEngineBase::Error; end
+  class ArgumentValidationError < ApiEngineBase::Error; end
+
+  class KeyValidationError < ApiEngineBase::ServiceBase::ValidationError; end
+  class CompositionValidationError < ApiEngineBase::ServiceBase::ValidationError; end
+
+  include Interactor
+  include ApiEngineBase::ServiceLogging
+  include ApiEngineBase::ArgumentValidation
+
+  ON_ARGUMENT_VALIDATION = [
+    DEFAULT_VALIDATION = :raise,
+    :fail_early,
+    :log,
+  ]
+
+  def self.inherited(subclass)
+    # Add the base logging to the subclass.
+    # Since this is done at inheritance time it should always be the first and last hook to run.
+    subclass.around(:service_base_logging)
+    subclass.around(:internal_validate)
+    subclass.after(:sanitize_params)
+  end
+
+  def validate!
+    # overload from child
+  end
+
+  def internal_validate(interactor)
+    # call validate that is overridden from child
+    begin
+      validate!
+      # validate_param!
+      run_validations!
+    rescue StandardError => e
+      log_error("Error during validation. #{e.message}")
+      raise
+    end
+
+    # call interactor
+    interactor.call
+  end
+
+  def service_base_logging(interactor)
+    beginning_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+    # Pre processing stats
+    log_info("Start")
+
+    # Run the job!
+    interactor.call
+
+    # Set status for use in ensure block
+    status = :complete
+
+  # Capture Interactor::Failure for logging purposes, then reraise
+  rescue ::Interactor::Failure
+    # set status for use in ensure block
+    status = :failure
+
+    # Re-raise to let the core Interactor handle this
+    raise
+  # Capture exception explicitly to try to logging purposes. Then reraise.
+  rescue ::Exception => e # rubocop:disable Lint/RescueException
+    # set status for use in ensure block
+    status = :error
+
+    # Log error
+    log_error("Error #{e.class.name}")
+
+    raise
+  ensure
+    # Always log how long it took along with a status
+    finished_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    elapsed = ((finished_time - beginning_time) * 1000).round(2)
+    log_info("Finished with [#{status}]...elapsed #{elapsed}ms")
+  end
+end

data/app/services/api_engine_base/service_logging.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module ApiEngineBase::ServiceLogging
+  def log_info(msg)
+    log(level: :info, msg:)
+  end
+
+  def log_warn(msg)
+    log(level: :warn, msg:)
+  end
+
+  def log_error(msg)
+    log(level: :error, msg:)
+  end
+
+  def log(level:, msg:)
+    logger.public_send(level, aletered_message(msg))
+  rescue StandardError
+    Rails.logger.public_send(level, aletered_message(msg))
+  end
+
+  def aletered_message(msg)
+    "#{log_prefix}: #{msg}"
+  end
+
+  def logger
+    defined?(context) ? context.logger : Rails.logger
+  end
+
+  def log_prefix
+    "[#{class_name}-#{service_id}]"
+  end
+
+  def class_name
+    self.class.name
+  end
+
+  def service_id
+    @service_id ||= SecureRandom.alphanumeric(10)
+  end
+end

data/app/services/api_engine_base/username/available.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module ApiEngineBase::Username
+  class Available < ApiEngineBase::ServiceBase
+    on_argument_validation :fail_early
+
+    REFRESH_KEY = "username.refresh_after"
+
+    validate :username, is_a: String, required: true
+    validate :force_query, is_a: [TrueClass, FalseClass]
+
+    def initialize(*)
+      super
+
+      @mutex = Mutex.new
+    end
+
+    def call
+      populate_local_cache! if refresh?
+
+      context.available = available?
+      context.valid = valid?
+    end
+
+    def valid?
+      return false if username.length < ApiEngineBase.config.username.username_length_min
+      return false if username.length > ApiEngineBase.config.username.username_length_max
+
+      !!username[ApiEngineBase.config.username.username_regex]
+    end
+
+    def available?
+      !realtime.local_cache.exist?(username)
+    end
+
+    # this is a very terrible cache design at scale
+    # If we can use Redis, a bloom filter would be great
+    def populate_local_cache!
+      @mutex.synchronize do
+        values = User.pluck(:username).map { [_1, 1] }.to_h rescue {}
+        realtime.local_cache.write_multi(values)
+        realtime.local_cache.write(REFRESH_KEY, realtime.local_cache_ttl.from_now)
+
+        values
+      end
+    end
+
+    def refresh?
+      return true if force_query
+
+      refresh_by = realtime.local_cache.read(REFRESH_KEY)
+      return true if refresh_by.nil?
+
+      time = Time.at(refresh_by) rescue nil
+      return true if time.nil?
+
+      time < Time.now
+    end
+
+    def realtime
+      ApiEngineBase.config.username.realtime_username_check
+    end
+  end
+end

data/app/views/api_engine_base/email_verification_mailer/verify_email.html.erb

@@ -0,0 +1,26 @@
+<p>Hello <%= @user.full_name %>!</p>
+
+<p>
+  Welcome to <%= ApiEngineBase.config.app.communication_name %>.
+</p>
+<p>
+  Please provide the following verification code to confirm your email address.
+</p>
+<p></p>
+<p></p>
+<p>
+  <h1>
+    <%= @code %>
+  </h1>
+</p>
+
+<p></p>
+<p></p>
+
+<p>
+  Best wishes, <%= ApiEngineBase.config.app.communication_name %> team
+</p>
+<p></p>
+<p></p>
+
+Visit us at <a href="<%= ApiEngineBase.config.app.composed_url %>" target="_blank"><%= ApiEngineBase.config.app.composed_url %></a>

data/config/routes.rb

@@ -0,0 +1,23 @@
+Rails.application.routes.draw do
+  append_to_ass = "api_engine_base"
+
+  constraints(->(_req) { ApiEngineBase.config.username.realtime_username_check? }) do
+    scope "username" do
+      get "/available/:username", to: "api_engine_base/username#username_availability", as: :"#{append_to_ass}_username_availability_get"
+    end
+  end
+
+  scope "auth" do
+    constraints(->(_req) { ApiEngineBase.config.login.plain_text.enable? }) do
+      post "/login", to: "api_engine_base/auth/plain_text#login_post", as: :"#{append_to_ass}_auth_login_post"
+      post "/create", to: "api_engine_base/auth/plain_text#create_post", as: :"#{append_to_ass}_auth_create_post"
+
+      constraints(->(_req) { ApiEngineBase.config.login.plain_text.email_verify? }) do
+        scope "email" do
+          post "/verify", to: "api_engine_base/auth/plain_text#email_verify_post", as: :"#{append_to_ass}_auth_email_verification"
+          post "/send", to: "api_engine_base/auth/plain_text#email_verify_resend_post", as: :"#{append_to_ass}_auth_email_verification_send"
+        end
+      end
+    end
+  end
+end

data/db/migrate/20241117043720_create_api_engine_base_users.rb

@@ -0,0 +1,33 @@
+class CreateApiEngineBaseUsers < ActiveRecord::Migration[7.2]
+  def change
+    create_table :users do |t|
+      t.string :first_name, null: false, default: ""
+      t.string :last_name, null: false, default: ""
+      t.string :username
+
+      t.string :last_known_timezone
+      t.timestamp :last_known_timezone_update
+
+      t.integer :successful_login, default: 0
+      t.string :last_login_strategy
+      t.datetime :last_login
+
+      ###
+      # Database token to verify JWT
+      # Token will allow JWT values to expire/reset all devices
+      t.string :verifier_token
+      t.datetime :verifier_token_last_reset
+
+      # Login Strategy: PlainText
+      t.string :email, null: false, default: ""
+      t.boolean :email_validated, default: false
+      t.integer :password_consecutive_fail, default: 0
+      t.string :password_digest, null: false, default: ""
+      t.string :recovery_password_digest, null: false, default: ""
+
+      t.timestamps
+    end
+
+    add_index :users, :username, unique: true
+  end
+end

data/db/migrate/20241204065708_create_api_engine_base_user_secrets.rb

@@ -0,0 +1,16 @@
+class CreateApiEngineBaseUserSecrets < ActiveRecord::Migration[7.2]
+  def change
+    create_table :user_secrets do |t|
+      t.references :user, null: false, foreign_key: true
+      t.integer :use_count, default: 0
+      t.integer :use_count_max
+      t.string :reason
+      t.string :extra
+      t.string :secret
+      t.datetime :death_time
+
+      t.timestamps
+    end
+    add_index :user_secrets, :secret, unique: true
+  end
+end

data/lib/api_engine_base/configuration/application/config.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "class_composer"
+
+module ApiEngineBase
+  module Configuration
+    module Application
+      class Config
+        include ClassComposer::Generator
+
+        add_composer :app_name,
+          allowed: String,
+          dynamic_default:  ->(_) { ApiEngineBase.default_app_name },
+          desc: "The default name of the application",
+          default_shown: "# Auto Populates to the name of the application"
+
+        add_composer :communication_name,
+          allowed: String,
+          dynamic_default: :app_name,
+          desc: "The name of the application to use in communications like SMS or Email"
+
+        add_composer :url,
+          allowed: String,
+          default: ENV.fetch("API_ENGINE_BASE_URL", "http://localhost"),
+          desc: "When composing SSO's or verification URL's, this is the URL for the application"
+
+        add_composer :port,
+          allowed: [String, NilClass],
+          default: ENV.fetch("API_ENGINE_BASE_PORT", nil),
+          desc: "When composing SSO's or verification URL's, this is the URL for the application"
+
+        add_composer :composed_url,
+          allowed: String,
+          dynamic_default: ->(instance) { "#{instance.url}#{ ":#{instance.port}" if instance.port }" },
+          desc: "The fully composed URL including the port number when needed. This Config variable is not needed as it is composed of the `url` and `port` composed values",
+          default_shown: "Composed String of the URL and PORT. Override this with caution"
+      end
+    end
+  end
+end

data/lib/api_engine_base/configuration/base.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "class_composer"
+require "pry"
+
+module ApiEngineBase
+  module Configuration
+    class Base
+    end
+  end
+end

data/lib/api_engine_base/configuration/config.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "singleton"
+require "class_composer"
+require "api_engine_base/configuration/base"
+require "api_engine_base/configuration/email/config"
+require "api_engine_base/configuration/jwt/config"
+require "api_engine_base/configuration/login/config"
+require "api_engine_base/configuration/otp/config"
+require "api_engine_base/configuration/username/config"
+require "api_engine_base/configuration/application/config"
+
+module ApiEngineBase
+  module Configuration
+    class Config < ::ApiEngineBase::Configuration::Base
+      include ClassComposer::Generator
+
+      add_composer :delete_secret_after_invalid,
+        desc: "Remove Secret after it is found as invalid",
+        allowed: [TrueClass, FalseClass],
+        default: true
+
+      add_composer :jwt,
+        desc: "JWT is the basis for Authorization and Authentication for this Engine. HMAC is the only support algorithm",
+        allowed: Configuration::Jwt::Config,
+        default: Configuration::Jwt::Config.new
+
+      add_composer :login,
+        desc: "Definition of Login Strategies.",
+        allowed: Configuration::Login::Config,
+        default: Configuration::Login::Config.new
+
+      add_composer :email,
+        desc: "Email configuration for the app sending Native Rails emails via ActiveMailer. Config changed here will update the Rails Configuration as well",
+        allowed: Configuration::Email::Config,
+        default: Configuration::Email::Config.new
+
+      add_composer :username,
+        desc: "Username configuration for the app",
+        allowed: Configuration::Username::Config,
+        default: Configuration::Username::Config.new
+
+      add_composer :application,
+        desc: "General configurations for the application. Primarily include application specific names, URL's, etc",
+        allowed: Configuration::Application::Config,
+        default: Configuration::Application::Config.new
+
+      # allow shorthand to be used
+      alias_method :app, :application
+
+      # To be Deleted
+      add_composer :otp,
+        desc: "One Time Password generator is used for all Code validation. This describes defaults not set in other configurations",
+        allowed: Configuration::Otp::Config,
+        default: Configuration::Otp::Config.new
+    end
+  end
+end
+

data/lib/api_engine_base/configuration/email/config.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module ApiEngineBase
+  module Configuration
+    module Email
+      class Config < ::ApiEngineBase::Configuration::Base
+        include ClassComposer::Generator
+
+        ASSIGNMENT = Proc.new do |key, value|
+          hash = Rails.configuration.action_mailer.smtp_settings ||= {}
+          Rails.configuration.action_mailer.smtp_settings = hash.merge({key => value})
+        end
+
+        ACTION_MAILER = Proc.new do |key, value|
+          Rails.configuration.action_mailer.public_send(:"#{key}=", value)
+        end
+
+        add_composer :user_name,
+          desc: "User Name for email. Defaults to ENV['GMAIL_USER_NAME']",
+          allowed: String,
+          default: ENV.fetch("GMAIL_USER_NAME", ""),
+          default_shown: "ENV[\"GMAIL_USER_NAME\"]",
+          &ASSIGNMENT
+
+        add_composer :password,
+          desc: "Password for email. Defaults to ENV['GMAIL_PASSWORD']. For more info on how to get this for GMAIL...https://support.google.com/accounts/answer/185833",
+          allowed: String,
+          default: ENV.fetch("GMAIL_PASSWORD", ""),
+          default_shown: "ENV[\"GMAIL_PASSWORD\"]",
+          &ASSIGNMENT
+
+        add_composer :port,
+          allowed: Integer,
+          default: 587,
+          &ASSIGNMENT
+
+        add_composer :address,
+          desc: "SMTP address for email. Defaults to smtp.gmail.com",
+          allowed: String,
+          default: "smtp.gmail.com",
+          &ASSIGNMENT
+
+        add_composer :authentication,
+          desc: "Authentication type for email",
+          allowed: String,
+          default: "plain",
+          &ASSIGNMENT
+
+        add_composer :enable_starttls_auto,
+          allowed: [TrueClass, FalseClass],
+          default: true,
+          &ASSIGNMENT
+
+        add_composer :delivery_method,
+          allowed: Symbol,
+          default: Rails.env.test? ? :test : :smtp,
+          &ACTION_MAILER
+
+        add_composer :perform_deliveries,
+          allowed: [TrueClass, FalseClass],
+          default: true,
+          &ACTION_MAILER
+
+        add_composer :raise_delivery_errors,
+          allowed: [TrueClass, FalseClass],
+          default: true,
+          &ACTION_MAILER
+
+        def gmail!(
+          from: ENV["GMAIL_USER_NAME"],
+          password: ENV["GMAIL_PASSWORD"],
+          port: 587,
+          address: "smtp.gmail.com",
+          authentication: "plain",
+          enable_starttls_auto: true
+        )
+          method(:from=).call(from)
+          method(:password=).call(password)
+          method(:port=).call(port)
+          method(:address=).call(address)
+          method(:authentication=).call(authentication)
+          method(:enable_starttls_auto=).call(enable_starttls_auto)
+        end
+      end
+    end
+  end
+end

data/lib/api_engine_base/configuration/jwt/config.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module ApiEngineBase
+  module Configuration
+    module Jwt
+      class Config < ::ApiEngineBase::Configuration::Base
+        include ClassComposer::Generator
+
+        add_composer :ttl,
+          desc: "Default TTL on how long the token is valid for",
+          allowed: ActiveSupport::Duration,
+          default: 7.days
+
+        add_composer :hmac_secret,
+          desc: "HMAC is the only algorithm supported. This is the secret key to encrypt he JWT token",
+          allowed: String,
+          default: ENV.fetch("SECRET_KEY_BASE","Thi$IsASeccretIwi::CH&ang3"),
+          default_shown: "ENV.fetch(\"SECRET_KEY_BASE\",\"Thi$IsASeccretIwi::CH&ang3\")"
+      end
+    end
+  end
+end

data/lib/api_engine_base/configuration/login/config.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "api_engine_base/configuration/login/strategy/plain_text/config"
+
+module ApiEngineBase
+  module Configuration
+    module Login
+      class Config < ::ApiEngineBase::Configuration::Base
+        include ClassComposer::Generator
+
+        add_composer_blocking :plain_text,
+          desc: "Login strategy for plain text authentication via User/Password combination",
+          composer_class: Strategy::PlainText::Config,
+          enable_attr: :enable
+      end
+    end
+  end
+end

data/lib/api_engine_base/configuration/login/strategy/plain_text/config.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "api_engine_base/configuration/login/strategy/plain_text/lockable"
+require "api_engine_base/configuration/login/strategy/plain_text/email_verify"
+
+module ApiEngineBase
+  module Configuration
+    module Login
+      module Strategy
+        module PlainText
+          class Config < ::ApiEngineBase::Configuration::Base
+            include ClassComposer::Generator
+
+            add_composer :enable,
+              desc: "Login Strategy for User/Password. By default, this is enabled",
+              allowed: [FalseClass, TrueClass],
+              default: true
+
+            add_composer_blocking :lockable,
+              desc: "Enable and change Lockable for User/Password Login strategy.",
+              composer_class: Locakable,
+              enable_attr: :enable
+
+            add_composer_blocking :email_verify,
+              desc: "Enable and change Email Verification for User/Password Login strategy.",
+              composer_class: EmailVerify,
+              enable_attr: :enable
+
+            add_composer :password_length_max,
+              desc: "Max Length for Password",
+              allowed: Integer,
+              default: 64
+
+            add_composer :password_length_min,
+              desc: "Min Length for Password",
+              allowed: Integer,
+              default: 8
+
+            add_composer :email_length_max,
+              desc: "Max Length for Email",
+              allowed: Integer,
+              default: 64
+
+            add_composer :email_length_min,
+              desc: "Min Length for Email",
+              allowed: Integer,
+              default: 8
+
+            def enable?
+              enable
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/api_engine_base/configuration/login/strategy/plain_text/email_verify.rb

@@ -0,0 +1,50 @@
+    # frozen_string_literal: true
+
+module ApiEngineBase
+  module Configuration
+    module Login
+      module Strategy
+        module PlainText
+          class EmailVerify < ::ApiEngineBase::Configuration::Base
+            include ClassComposer::Generator
+
+            add_composer :enable,
+              desc: "Email Verify will help ensure that users emails are valid by requesting a verify code. By default this is enabled",
+              allowed: [FalseClass, TrueClass],
+              default: true
+
+            add_composer :verify_email_required_within,
+              desc: "Strategy allows user to set time before email verification is required. After time has expired, usage of API is no longer valid until email has been verified. Up until this time, the Login Strategy will allow usage of the API. Default time is set to 0 minutes",
+              allowed: ActiveSupport::Duration,
+              default: 0.minutes,
+              validator: -> (val) { val < 10.days },
+              invalid_message: ->(val) { "Provided #{val}. Value must be less than #{10.days}" }
+
+
+            add_composer :verify_code_link_required_within,
+              desc: "When the email verification is sent, how long will that code be valid for. By default, this is set to 10 minutes",
+              allowed: ActiveSupport::Duration,
+              default: 10.minutes,
+              validator: -> (val) { val < 60.minutes },
+              invalid_message: ->(val) { "Provided #{val}. Value must be less than #{60.minutes}" }
+
+
+            add_composer :verify_code_link_valid_for,
+              desc: "When the email verification is sent, how long will that code be valid for. By default, this is set to 10 minutes",
+              allowed: ActiveSupport::Duration,
+              default: 10.minutes,
+              validator: -> (val) { val < 60.minutes },
+              invalid_message: ->(val) { "Provided #{val}. Value must be less than #{60.minutes}" }
+
+            add_composer :verify_code_length,
+              desc: "The length of the verify code sent via email.",
+              allowed: Integer,
+              default: 6,
+              validator: -> (val) { (val <= 10) && (val >= 4) },
+              invalid_message: ->(val) { "Provided #{val}. Value must be less than or equal to 10 and greater than or equal to 4." }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/api_engine_base/configuration/login/strategy/plain_text/lockable.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module ApiEngineBase
+  module Configuration
+    module Login
+      module Strategy
+        module PlainText
+          class Locakable < ::ApiEngineBase::Configuration::Base
+            include ClassComposer::Generator
+
+            add_composer :enable,
+              desc: "Disabled by default. When enabled, this adds an additional level of support for brute force attacks on User/Password Logins",
+              allowed: [FalseClass, TrueClass],
+              default: false
+
+            add_composer :password_attempts,
+              desc: "Max failed password attempts before additional verification on account is required.",
+              allowed: Integer,
+              default: 10,
+              validator: -> (val) { val >= 0 && val < 50 },
+              invalid_message: ->(val) { "Max password attempts must be >=0 and less than 50. Received #{val}" }
+          end
+        end
+      end
+    end
+  end
+end