api_engine_base 0.1.1 → 0.1.2

data/app/services/api_engine_base/authorize/validate.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module ApiEngineBase::Authorize
+  class Validate < ApiEngineBase::ServiceBase
+    on_argument_validation :fail_early
+
+    validate :user, is_a: User, required: true
+    validate :controller, is_a: [ActionController::Base, ActionController::API], required: true
+    validate :method, is_a: String, required: true
+
+    def call
+      context.authorization_required = authorization_required?
+      unless context.authorization_required
+        log_info("controller:#{controller}; method:#{method} -- No Authorization required")
+        context.msg = "Authorization not required at this time"
+        return
+      end
+
+      # At this point we know authorization on the route is required
+      # Iterate through the users roles to find a matching role that allows authorization
+      # If at least 1 of the users roles passes validation, we can allow access to the path
+      log_info("User Roles: #{user.roles}")
+      auhorization_result = user_role_objects.any? do |_role_name, role_object|
+        result = role_object.authorized?(controller:, method:, user:)
+        log_info("Role:#{result[:role]};Authorized:[#{result[:authorized]}];Reason:[#{result[:reason]}]")
+        result[:authorized] == true
+      end
+
+      if auhorization_result
+        context.msg = "User is Authorized for action"
+      else
+        context.fail!(msg: "Unauthorized Access. Incorrect User Privileges")
+      end
+    end
+
+    def authorization_required?
+      controller_mapping = ApiEngineBase::Authorization.mapped_controllers[controller]
+      return false if controller_mapping.nil?
+
+      controller_mapping.include?(method.to_sym)
+    end
+
+    def user_role_objects
+      ApiEngineBase::Authorization::Role.roles.select do |role_name, _|
+        user.roles.include?(role_name.to_s)
+      end
+    end
+  end
+end

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

@@ -5,6 +5,7 @@ module ApiEngineBase::Jwt
 
     validate :token, is_a: String, required: true, sensitive: true
     validate :bypass_email_validation, is_one: [true, false], default: false
+    validate :with_reset, is_one: [true, false], default: false
 
     def call
       result = Decode.(token:)
@@ -14,7 +15,7 @@ module ApiEngineBase::Jwt
       end
       payload = result.payload
 
-      validate_expires_at!(expires_at: payload[:expires_at])
+      expires_at = validate_generated_at!(generated_at: payload[:generated_at])
 
       user = User.find(payload[:user_id]) rescue nil
       if user.nil?
@@ -29,25 +30,39 @@ module ApiEngineBase::Jwt
       end
 
       email_validation_required!(user:)
+
+      if with_reset
+        context.generated_token = ApiEngineBase::Jwt::LoginCreate.(user:).token
+        expires_at = ApiEngineBase.config.jwt.ttl.from_now.to_time
+      end
+
+      context.expires_at = expires_at.to_s
     end
 
-    def validate_expires_at!(expires_at:)
-      if expires_at.nil?
-        log_warn("expires_at payload is missing from the JWT token. Cannot continue")
+    def validate_generated_at!(generated_at:)
+      if generated_at.nil?
+        log_warn("generated_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
+      expires_time = begin
+        time = Time.at(generated_at)
+        time + ApiEngineBase.config.jwt.ttl
+      rescue
+        nil
+      end
 
       if expires_time.nil?
-        log_warn("expires_at payload cannot be parsed. Cannot continue")
+        log_warn("generated_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")
+        log_warn("generated_at is no longer valid. Must request new token")
         context.fail!(msg: "Unauthorized Access. Invalid Authorization token")
       end
+
+      expires_time
     end
 
     def email_validation_required!(user:)

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

@@ -12,7 +12,7 @@ module ApiEngineBase::Jwt
 
     def payload
       {
-        expires_at: ApiEngineBase.config.jwt.ttl.from_now.to_i,
+        generated_at: Time.now.to_i,
         user_id: user.id,
         verifier_token: user.retreive_verifier_token!,
       }

data/app/services/api_engine_base/service_base.rb

@@ -41,9 +41,8 @@ class ApiEngineBase::ServiceBase
   def internal_validate(interactor)
     # call validate that is overridden from child
     begin
-      validate!
-      # validate_param!
-      run_validations!
+      validate! # custom validations defined on the child class
+      run_validations! # ArgumentValidation's based on defined settings on child
     rescue StandardError => e
       log_error("Error during validation. #{e.message}")
       raise
@@ -72,8 +71,8 @@ class ApiEngineBase::ServiceBase
 
     # 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
+  # Capture exception explicitly for logging purposes, then reraise
+  rescue ::Exception => e
     # set status for use in ensure block
     status = :error
 

data/app/services/api_engine_base/user_attributes/modify.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module ApiEngineBase::UserAttributes
+  class Modify < ApiEngineBase::ServiceBase
+    on_argument_validation :fail_early
+    DEFAULT = {
+      verifier_token: [true, false]
+    }
+    validate :user, is_a: User, required: true
+    validate :admin_user, is_a: User, required: false
+
+    # Gets assigned during configuration phase via
+    # lib/api_engine_base/configuration/user/config.rb
+    def self.assign!
+      attributes = ApiEngineBase.config.user.default_attributes_for_change + ApiEngineBase.config.user.additional_attributes_for_change
+      one_of(:modify_attribute, required: true) do
+        attributes.uniq.each do |attribute|
+          if metadata = User.attribute_to_type_mapping[attribute]
+            arguments = {}
+            if default = DEFAULT[attribute.to_sym]
+              arguments[:is_one] = default
+            else
+              if allowed_types = metadata[:allowed_types]
+                arguments[:is_one] = allowed_types
+              else
+                arguments[:is_a] = metadata[:ruby_type]
+              end
+            end
+
+            validate(attribute, **arguments)
+          end
+        end
+      end
+    end
+
+    def call
+      case modify_attribute_key
+      when :email
+        unless email =~ URI::MailTo::EMAIL_REGEXP
+          inline_argument_failure!(errors: { email: "Invalid email address" })
+        end
+      when :username
+        username_validity = ApiEngineBase::Username::Available.(username:)
+        unless username_validity.valid
+          inline_argument_failure!(errors: { username: "Username is invalid. #{ApiEngineBase.config.username.username_failure_message}" })
+        end
+      when :verifier_token
+        if verifier_token
+          verifier_token!
+        else
+          inline_argument_failure!(errors: { verifier_token: "verifier_token is invalid. Expected [true] when value present" })
+        end
+
+        return
+      end
+
+      update!
+    end
+
+    def verifier_token!
+      user.reset_verifier_token!
+    end
+
+    def update!
+      user.update!(modify_attribute_key => modify_attribute)
+    end
+  end
+end

data/app/services/api_engine_base/user_attributes/roles.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module ApiEngineBase::UserAttributes
+  class Roles < ApiEngineBase::ServiceBase
+    on_argument_validation :fail_early
+
+    validate :user, is_a: User, required: true
+    validate :admin_user, is_a: User, required: true
+    validate :roles, is_a: Array, required: true
+
+    def call
+      if valid_roles?
+        user.update!(roles:)
+        return true
+      end
+
+      inline_argument_failure!(errors: { roles: "Invalid roles provided" })
+    end
+
+    def valid_roles?
+      return true if roles.empty?
+
+      available_roles = ApiEngineBase::Authorization::Role.roles.keys
+      roles.all? { available_roles.include?(_1) }
+    end
+  end
+end

data/config/routes.rb

@@ -20,4 +20,15 @@ Rails.application.routes.draw do
       end
     end
   end
+
+  scope "user" do
+    get "/", to: "api_engine_base/user#show", as: :"#{append_to_ass}_user_show_get"
+    post "/modify", to: "api_engine_base/user#modify", as: :"#{append_to_ass}_user_modify_post"
+  end
+
+  scope "admin" do
+    get "/", to: "api_engine_base/admin#show", as: :"#{append_to_ass}_admin_show_get"
+    post "/modify", to: "api_engine_base/admin#modify", as: :"#{append_to_ass}_admin_modify_post"
+    post "/modify/role", to: "api_engine_base/admin#modify_role", as: :"#{append_to_ass}_admin_modify_role_post"
+  end
 end

data/db/migrate/20241117043720_create_api_engine_base_users.rb

@@ -12,6 +12,8 @@ class CreateApiEngineBaseUsers < ActiveRecord::Migration[7.2]
       t.string :last_login_strategy
       t.datetime :last_login
 
+      t.string :roles, default: ""
+
       ###
       # Database token to verify JWT
       # Token will allow JWT values to expire/reset all devices

data/lib/api_engine_base/authorization/default.yml

@@ -0,0 +1,34 @@
+---
+groups:
+  owner:
+    description: The owner of the application will have full access to all components
+    entities: true
+  admin:
+    description: |
+      This group defines permissions for Admin Read and Write operations. Users with this role will have
+      the ability to view and update other users states.
+    entities:
+      - admin
+  admin-without-impersonation:
+    description: |
+      This group defines permissions for Admin Read and Write operations. Users with this role will have
+      the ability to view and update other users states. However, impersonation is not permitted with this role
+    entities:
+      - admin-without-impersonate
+  admin-read-only:
+    description: |
+      This group defines permissions for Admin Read interface only.
+    entities:
+      - read-admin
+entities:
+  - name: read-admin
+    controller: ApiEngineBase::AdminController
+    only: show
+  - name: admin
+    controller: ApiEngineBase::AdminController
+  - name: admin-without-impersonate
+    controller: ApiEngineBase::AdminController
+    except: impersonate
+
+
+

data/lib/api_engine_base/authorization/entity.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module ApiEngineBase
+  module Authorization
+    class Entity
+      class << self
+        def create_entity(name:, controller:, only: nil, except: nil)
+          if entities[name]
+            Rails.logger.warn("Warning: Authorization entity #{name} duplicated. Only the most recent one will persist")
+          end
+
+          entities[name] = new(name:, controller:, only:, except:)
+
+          entities[name]
+        end
+
+        def entities
+          @entities ||= ActiveSupport::HashWithIndifferentAccess.new
+        end
+
+        def entities_reset!
+          @entities = ActiveSupport::HashWithIndifferentAccess.new
+        end
+      end
+
+      attr_reader :name, :controller, :only, :except
+      def initialize(name:, controller:, only: nil, except: nil)
+        @controller = controller
+        @except = except.nil? ? nil : Array(except).map(&:to_sym)
+        @only = only.nil? ? nil : Array(only).map(&:to_sym)
+
+        validate!
+      end
+
+      def humanize
+        "name:[#{name}]; controller:[#{controller}]; only:[#{only}]; except:[#{except}]"
+      end
+
+      # controller will be the class object
+      # method will be the string of the route method
+      def matches?(controller:, method:)
+        # Return early if the controller does not match the existing entity controller
+        return nil if @controller != controller
+
+        # We are in the correct controller
+
+        # if inclusions are not present, the check is on the entire contoller and we can return true
+        if only.nil? && except.nil?
+          return true
+        end
+
+        ## `only` or `except` is present at this point
+        if only
+          # If method is included in only, accept otherwise return reject
+          return only.include?(method.to_sym)
+        else
+          # If method is included in except, reject otherwise return accept
+          return !except.include?(method.to_sym)
+        end
+      end
+
+      # This is a custom method that can get overridden by a child class for custom
+      # authorization logic beyond grouping
+      def authorized?(user:)
+        true
+      end
+
+      private
+
+      def validate!
+        if @only && @except
+          raise Error, "kwargs `only` and `except` passed in. At most 1 can be passed in."
+        end
+
+        validate_controller!
+        validate_methods!(@only, :only)
+        validate_methods!(@except, :except)
+      end
+
+      def validate_controller!
+        return true if Class === @controller
+
+        @controller = @controller.constantize
+      rescue NameError => e
+        raise Error, "Controller [#{@controller}] was not found. Please validate spelling or ensure it is loaded earlier"
+      end
+
+      def validate_methods!(array_of_methods, string)
+        return if array_of_methods.nil?
+
+        missing_methods = array_of_methods.select do |method|
+          !@controller.instance_methods.include?(method)
+        end
+
+        return true if missing_methods.empty?
+
+        raise Error, "#{string} parameter is invalid. Controller [#{@controller}] is missing methods:[#{missing_methods}]"
+      end
+    end
+  end
+end

data/lib/api_engine_base/authorization/role.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module ApiEngineBase
+  module Authorization
+    class Role
+      class << self
+        def create_role(name:, description:, entities: nil, allow_everything: false)
+          if roles[name]
+            raise Error, "Role [#{name}] already exists. Must use different name"
+          end
+
+          if allow_everything
+            Rails.logger.info { "Authorization Role: #{name} is granted authorization to all roles" }
+          else
+            unless Array(entities).all? { Entity === _1 }
+              raise Error, "Parameter :entities must include objects of or inherited by ApiEngineBase::Authorization::Entity"
+            end
+          end
+
+          roles[name] = new(name:, description:, entities:, allow_everything:)
+          # A role is `intended` to be immutable (attr_reader)
+          # Once the role is defined it will not get changed
+          # After it is created, add the mapping to the source of truth list of mapped method names to their controllers
+          ApiEngineBase::Authorization.add_mapping!(role: roles[name])
+
+          roles[name]
+        end
+
+        def roles
+          @roles ||= ActiveSupport::HashWithIndifferentAccess.new
+        end
+
+        def roles_reset!
+          @roles = ActiveSupport::HashWithIndifferentAccess.new
+        end
+      end
+
+      attr_reader :entities, :name, :description, :allow_everything
+      def initialize(name:, description:, entities:, allow_everything: false)
+        @name = name
+        @entities = Array(entities)
+        @description = description
+        @allow_everything = allow_everything
+      end
+
+      def authorized?(controller:, method:, user:)
+        return_value = { role: name, description: }
+        return return_value.merge(authorized: true, reason: "#{name} allows all authorizations") if allow_everything
+
+        matched_controllers = controller_entity_mapping[controller]
+        # if Role does not match any of the controllers
+        # explicitly return nil here to ensure upstream knows this role does not care about the route
+        return return_value.merge(authorized: nil, reason: "#{name} does not match") if matched_controllers.nil?
+
+        rejected_entities = matched_controllers.map do |entity|
+          case entity.matches?(controller:, method:)
+          when false, nil
+            { authorized: false, entity: entity.name, controller:, readable: entity.humanize, status: "Rejected by inclusion" }
+          when true
+            # Entity matches all inclusions
+            if entity.authorized?(user:)
+              # Do nothing! Entity has authorized the user
+            else
+              { authorized: false, entity: entity.name, controller:, readable: entity.humanize, status: "Rejected via custom Entity Authorization" }
+            end
+          end
+        end.compact
+
+        # If there were no entities that rejected authorization, return authorized
+        return return_value.merge(authorized: true, reason: "All entities approve authorization") if rejected_entities.empty?
+
+        return_value.merge(authorized: false, reason: "Subset of Entities Rejected authorization", rejected_entities:)
+      end
+
+      def guards
+        mapping = {}
+        controller_entity_mapping.each do |controller, entities|
+          mapping[controller] ||= []
+          entities.map do |entity|
+            if entity.only
+              # We only care about these methods on the controller
+              mapping[controller] += entity.only
+            elsif entity.except
+              # We care about all methods on the controller except these
+              mapping[controller] += controller.instance_methods(false) - entity.except
+            else
+              # We care about all methods on the controller
+              mapping[controller] += controller.instance_methods(false)
+            end
+          end
+        end
+
+        mapping
+      end
+
+      def controller_entity_mapping
+        @controller_entity_mapping ||= @entities.group_by(&:controller)
+      end
+    end
+  end
+end

data/lib/api_engine_base/authorization.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "set"
+require "api_engine_base/error"
+require "api_engine_base/authorization/entity"
+require "api_engine_base/authorization/role"
+
+module ApiEngineBase
+  module Authorization
+    module_function
+
+    class Error < ApiEngineBase::Error; end
+
+    def mapped_controllers
+      @mapped_controllers ||= {}
+    end
+
+    def add_mapping!(role:)
+      role.guards.each do |controller, methods|
+        mapped_controllers[controller] ||= Set.new
+        mapped_controllers[controller] += methods
+      end
+    end
+
+    def mapped_controllers_reset!
+      @mapped_controllers = {}
+    end
+
+    def default_defined!
+      provision_rbac_default!
+      provision_rbac_user_defined!
+    end
+
+    def provision_rbac_user_defined!
+      path = ApiEngineBase.config.authorization.rbac_group_path
+      rbac_configuration = load_yaml(path)
+      provision_rbac_via_yaml(rbac_configuration)
+    end
+
+    def provision_rbac_default!
+      path = ApiEngineBase::Engine.root.join("lib", "api_engine_base", "authorization", "default.yml")
+      rbac_configuration = load_yaml(path)
+      provision_rbac_via_yaml(rbac_configuration)
+    end
+
+    def load_yaml(path)
+      return nil unless File.exist?(path)
+
+      YAML.load_file(path)
+    end
+
+    def provision_rbac_via_yaml(rbac_configuration)
+      return if rbac_configuration.nil?
+
+      rbac_configuration["entities"].each do |entity|
+        ApiEngineBase::Authorization::Entity.create_entity(
+          name: entity["name"],
+          controller: entity["controller"],
+          only: entity["only"],
+          except: entity["except"],
+        )
+      end
+
+      rbac_configuration["groups"].each do |name, metadata|
+        entities = nil
+        allow_everything = false
+        description = metadata["description"]
+
+        if metadata["entities"] == true
+          allow_everything =  true
+        else
+          entities = ApiEngineBase::Authorization::Entity.entities.map { |k, v| v if metadata["entities"].include?(k) }.compact
+        end
+
+        ApiEngineBase::Authorization::Role.create_role(
+          name:,
+          entities:,
+          description:,
+          allow_everything:,
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "class_composer"
+
+module ApiEngineBase
+  module Configuration
+    module Admin
+      class Config
+        include ClassComposer::Generator
+
+        add_composer :enable,
+          desc: "Allow Admin Capabilities for the application. By default, this is enabled",
+          allowed: [FalseClass, TrueClass],
+          default: true
+      end
+    end
+  end
+end

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

@@ -27,13 +27,13 @@ module ApiEngineBase
         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"
+          desc: "When composing SSO's or verification URL's, this is the PORT 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"
+          default_shown: "# Composed String of the URL and PORT. Override this with caution"
       end
     end
   end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "class_composer"
+
+module ApiEngineBase
+  module Configuration
+    module Authorization
+      class Config
+        include ClassComposer::Generator
+
+        add_composer :rbac_default_groups,
+          desc: "The default Group Roles defined by this engine.",
+          allowed: [TrueClass, FalseClass],
+          default: true
+
+        add_composer :rbac_group_path,
+          desc: "If defined, this config points to the users YAML file defining RBAC group roles.",
+          allowed: String,
+          dynamic_default: ->(_) { Rails.root.join("config","rbac_groups.yml").to_s },
+          default_shown: "Rails.root.join(\"config\",\"rbac_groups.yml\")"
+      end
+    end
+  end
+end