api_engine_base 0.1.1 → 0.2.0

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

@@ -34,6 +34,7 @@ module ApiEngineBase::LoginStrategy::PlainText
 
       if user.save
         context.user = user
+        ApiEngineBase::InboxService::Blast::NewUserBlaster.(user:)
       else
         inline_argument_failure!(errors: user.errors)
       end

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,36 @@ 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 "inbox" do
+    scope "messages" do
+      get "/", to: "api_engine_base/inbox/message#metadata", as: :"#{append_to_ass}_inbox_metadata"
+
+      get "/:id", to: "api_engine_base/inbox/message#message", as: :"#{append_to_ass}_inbox_message"
+      delete "/:id", to: "api_engine_base/inbox/message#delete", as: :"#{append_to_ass}_inbox_message_del"
+
+      post "/ack", to: "api_engine_base/inbox/message#ack", as: :"#{append_to_ass}_inbox_ack"
+      post "/delete", to: "api_engine_base/inbox/message#delete", as: :"#{append_to_ass}_inbox_delete"
+    end
+
+    scope "blast" do
+      get "/", to: "api_engine_base/inbox/message_blast#metadata", as: :"#{append_to_ass}_blast_metadata"
+      post "/", to: "api_engine_base/inbox/message_blast#create", as: :"#{append_to_ass}_blast_create"
+
+      get "/:id", to: "api_engine_base/inbox/message_blast#blast", as: :"#{append_to_ass}_blast_blast"
+      patch "/:id", to: "api_engine_base/inbox/message_blast#modify", as: :"#{append_to_ass}_blast_modify"
+      delete "/:id", to: "api_engine_base/inbox/message_blast#delete", as: :"#{append_to_ass}_blast_delete"
+    end
+  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/db/migrate/20250223023306_create_api_engine_base_messages.rb

@@ -0,0 +1,12 @@
+class CreateApiEngineBaseMessages < ActiveRecord::Migration[7.2]
+  def change
+    create_table :messages do |t|
+      t.timestamps
+      t.references :user, null: false, foreign_key: true # Required
+      t.text :text
+      t.string :title
+      t.boolean :viewed, default: false
+      t.boolean :pushed, default: false
+    end
+  end
+end

data/db/migrate/20250223023313_create_api_engine_base_message_blasts.rb

@@ -0,0 +1,14 @@
+class CreateApiEngineBaseMessageBlasts < ActiveRecord::Migration[7.2]
+  def change
+    create_table :message_blasts do |t|
+      t.timestamps
+      t.references :user, null: false, foreign_key: true # Required
+      t.text :text
+      t.string :title
+      t.boolean :existing_users, default: false
+      t.boolean :new_users, default: false
+    end
+
+    add_reference :messages, :message_blast, foreign_key: true, null: true
+  end
+end

data/lib/api_engine_base/authorization/default.yml

@@ -0,0 +1,42 @@
+---
+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
+      - message-blast
+  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
+      - message-blast
+  admin-read-only:
+    description: |
+      This group defines permissions for Admin Read interface only.
+    entities:
+      - read-admin
+      - message-blast-read-only
+entities:
+  - name: message-blast
+    controller: ApiEngineBase::Inbox::MessageBlastController
+  - name: message-blast-read-only
+    controller: ApiEngineBase::Inbox::MessageBlastController
+    only: metadata
+  - 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

data/lib/api_engine_base/configuration/config.rb

@@ -9,6 +9,9 @@ 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"
+require "api_engine_base/configuration/admin/config"
+require "api_engine_base/configuration/authorization/config"
+require "api_engine_base/configuration/user/config"
 
 module ApiEngineBase
   module Configuration
@@ -48,9 +51,24 @@ module ApiEngineBase
       # allow shorthand to be used
       alias_method :app, :application
 
+      add_composer :authorization,
+        desc: "Authorization via rbac configurations",
+        allowed: Configuration::Authorization::Config,
+        default: Configuration::Authorization::Config.new
+
+      add_composer :user,
+        desc: "User configuration for the app. Includes what to display and what attributes can be changed",
+        allowed: Configuration::User::Config,
+        default: Configuration::User::Config.new
+
+      add_composer :admin,
+        desc: "Admin configuration for the app",
+        allowed: Configuration::Admin::Config,
+        default: Configuration::Admin::Config.new
+
       # 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",
+        desc: "One Time Password generation is used for ease in quickly validating a users actions. This is good for short term validation requirements as opposed to UserSecrets",
         allowed: Configuration::Otp::Config,
         default: Configuration::Otp::Config.new
     end