rabarber 1.3.1 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fc0447acdc988dc558859b695d24d227697258a92bb1f444944fb76bfbace526
-  data.tar.gz: 975f4377d5cc4fb2f28c42060012b67b3a85fea589aadb5106c33ecb943cde4a
+  metadata.gz: bcddaf07627eb382c58a733150e460348527476d2234f65fe0db2760bce6206f
+  data.tar.gz: 3d1bbfab2a57d860bcb9656cadb5606d09674f887a58b96db0897c3516aed5d2
 SHA512:
-  metadata.gz: cbfed2814ae750ec0b2870126818cb67c6b55c28a7529d8ab2db3364adc463768853b41ac89ba4653d014aa1024622ae261f5b2c8afcc10b99194fd916a40266
-  data.tar.gz: 7b77adeb8cc95acc4b104e6c39c6366b466262a8b0df0584d9e7d99d6369d96d01779a5962c7963696bccf7a941578a82774f2af23ac76d4a515bf37f7bed2ad
+  metadata.gz: e5ae51e17b580757cc427f269b43155ca3ea5eda5b4813be5d023c273f2271d96108639e24c1921ace823de4cc06b43c03372eb98d64f6d4376f9628e7b6d616
+  data.tar.gz: 232a9ded49264955b8cf7d22de5a1443947dd84d90f44f15f6dc9c9346ee7b1cee56afa85a55bf44bf5325bb1d26e17e6fcf0b8076d3f14381a9bb43254038ab

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 1.4.0
+
+- Add 'Audit trail' feature: Logging of role assignments, revocations, and unauthorized access attempts
+- Add `audit_trail_enabled` configuration option, allowing to enable or disable the audit trail
+- Deprecate `when_actions_missing` and `when_roles_missing` configuration options (see [the discussion](https://github.com/enjaku4/rabarber/discussions/48))
+
 ## 1.3.1
 
 - Add `Rabarber::Role.assignees_for` method

data/README.md

@@ -3,7 +3,7 @@
 [![Gem Version](https://badge.fury.io/rb/rabarber.svg)](http://badge.fury.io/rb/rabarber)
 [![Github Actions badge](https://github.com/enjaku4/rabarber/actions/workflows/ci.yml/badge.svg)](https://github.com/enjaku4/rabarber/actions/workflows/ci.yml)
 
-Rabarber is a role-based authorization library for Ruby on Rails, designed primarily for use in the application's web layer (specifically controllers and views) but not limited to that. It provides tools for managing user roles and defining authorization rules and mainly focuses on answering the question: 'Who has access to which endpoints?'.
+Rabarber is a role-based authorization library for Ruby on Rails, primarily designed for use in the web layer of your application but not limited to that. It provides a set of tools for managing user roles and defining authorization rules, along with audit logging for enhanced security.
 
 ---
 
@@ -63,26 +63,33 @@ If specific customization is required, Rabarber can be configured by using `.con
 
 ```rb
 Rabarber.configure do |config|
+  config.audit_trail_enabled = true
   config.cache_enabled = true
   config.current_user_method = :current_user
   config.must_have_roles = false
-  config.when_actions_missing = -> (missing_actions, context) { ... }
-  config.when_roles_missing = -> (missing_roles, context) { ... }
-  config.when_unauthorized = -> (controller) { ... }
+  config.when_unauthorized = -> (controller) {
+    if controller.request.format.html?
+      controller.redirect_back fallback_location: controller.root_path
+    else
+      controller.head :unauthorized
+    end
+  }
 end
 ```
 
+- `audit_trail_enabled` must be a boolean determining whether the audit trail functionality is enabled. _The audit trail is enabled by default._
 - `cache_enabled` must be a boolean determining whether roles are cached. _Roles are cached by default to avoid unnecessary database queries._ If you want to disable caching, set this option to `false`. If caching is enabled and you need to clear the cache, use `Rabarber::Cache.clear` method.
-
 - `current_user_method` must be a symbol representing the method that returns the currently authenticated user. _The default value is `:current_user`._
-
 - `must_have_roles` must be a boolean determining whether a user with no roles can access endpoints permitted to everyone. _The default value is `false` (allowing users without roles to access endpoints permitted to everyone)._
+- `when_unauthorized` must be a proc where you can define the behaviour when access is not authorized. Lambda argument `controller` is an instance of the controller where the code is executed. _By default, the user is redirected back if the request format is HTML; otherwise, a 401 Unauthorized response is sent._
 
-- `when_actions_missing` must be a proc where you can define the behaviour when the actions specified in `grant_access` method cannot be found in the controller (`missing_actions` is an array of symbols e.g., `[:index]`, `context` is a hash that looks like this: `{ controller: "InvoicesController" }`). This check is performed on every request and when the application is initialized if `eager_load` configuration is enabled in Rails. _By default, an error is raised when actions are missing._
+### Deprecated Configuration Options
 
-- `when_roles_missing` must be a proc where you can define the behaviour when the roles specified in `grant_access` method cannot be found in the database (`missing_roles` is an array of symbols e.g., `[:admin]`, `context` is a hash that looks like this: `{ controller: "InvoicesController", action: "index" }`). This check is performed on every request and when the application is initialized if `eager_load` configuration is enabled in Rails. _By default, only a warning is logged when roles are missing._
+The following configuration options are deprecated and will be removed in the next major version (see [the discussion](https://github.com/enjaku4/rabarber/discussions/48)):
 
-- `when_unauthorized` must be a proc where you can define the behaviour when access is not authorized (`controller` is an instance of the controller where the code is executed). _By default, the user is redirected back if the request format is HTML; otherwise, a 401 Unauthorized response is sent._
+- `when_actions_missing` must be a proc where you can define the behaviour when the action specified in `grant_access` method cannot be found in the controller. Lambda argument `missing_actions` is an array of symbols, e.g., `[:index]`, while `context` argument is a hash that looks like this: `{ controller: "InvoicesController" }`. This check is performed when the application is initialized if `eager_load` configuration is enabled in Rails and also on every request. _By default, an error is raised when action is missing._
+
+- `when_roles_missing` must be a proc where you can define the behaviour when the roles specified in `grant_access` method cannot be found in the database. Lambda argument `missing_roles` is an array of symbols, e.g., `[:admin]`, while `context` argument is a hash that looks like this: `{ controller: "InvoicesController", action: "index" }`. This check is performed when the application is initialized if `eager_load` configuration is enabled in Rails and also on every request. _By default, a warning is logged when roles are missing._
 
 ## Roles
 
@@ -97,20 +104,20 @@ end
 
 This adds the following methods:
 
-**`#assign_roles`**
+**`#assign_roles(*roles, create_new: true)`**
 
 To assign roles, use:
 
 ```rb
 user.assign_roles(:accountant, :marketer)
 ```
-By default, `#assign_roles` method will automatically create any roles that don't exist. If you want to assign only existing roles and prevent the creation of new ones, use the method with `create_new: false` argument:
+By default, it will automatically create any roles that don't exist. If you want to assign only existing roles and prevent the creation of new ones, use the method with `create_new: false` argument:
 ```rb
 user.assign_roles(:accountant, :marketer, create_new: false)
 ```
 The method returns an array of roles assigned to the user.
 
-**`#revoke_roles`**
+**`#revoke_roles(*roles)`**
 
 To revoke roles, use:
 
@@ -121,7 +128,7 @@ If any of the specified roles doesn't exist or the user doesn't have the role yo
 
 The method returns an array of roles assigned to the user.
 
-**`#has_role?`**
+**`#has_role?(*roles)`**
 
 To check whether the user has a role, use:
 
@@ -143,7 +150,7 @@ user.roles
 
 To manipulate roles directly, you can use `Rabarber::Role` methods:
 
-**`.add`**
+**`.add(role)`**
 
 To add a new role, use:
 
@@ -153,7 +160,7 @@ Rabarber::Role.add(:admin)
 
 This will create a new role with the specified name and return `true`. If the role already exists, it will return `false`.
 
-**`.rename`**
+**`.rename(old_role_name, new_role_name, force: false)`**
 
 To rename a role, use:
 
@@ -167,7 +174,7 @@ The method won't rename the role and will return `false` if it is assigned to an
 Rabarber::Role.rename(:admin, :administrator, force: true)
 ```
 
-**`.remove`**
+**`.remove(role, force: false)`**
 
 To remove a role, use:
 
@@ -190,7 +197,7 @@ If you need to list all the role names available in your application, use:
 Rabarber::Role.names
 ```
 
-**`.assignees_for`**
+**`.assignees_for(role)`**
 
 To get all the users to whom the role is assigned, use:
 
@@ -208,7 +215,7 @@ class ApplicationController < ActionController::Base
   ...
 end
 ```
-This adds `.grant_access` method which allows you to define the authorization rules.
+This adds `.grant_access(action: nil, roles: nil, if: nil, unless: nil)` method which allows you to define the authorization rules.
 
 The most basic usage of the method is as follows:
 
@@ -323,7 +330,7 @@ This means that `Crm::InvoicesController` is still accessible to `admin` but is
 
 ## View Helpers
 
-Rabarber also provides a couple of helpers that can be used in views: `visible_to` and `hidden_from`. To use them, simply include `Rabarber::Helpers` in the desired helper. Usually it is `ApplicationHelper`, but it can be any helper of your choice.
+Rabarber also provides a couple of helpers that can be used in views: `visible_to(*roles, &block)` and `hidden_from(*roles, &block)`. To use them, simply include `Rabarber::Helpers` in the desired helper. Usually it is `ApplicationHelper`, but it can be any helper of your choice.
 
 ```rb
 module ApplicationHelper
@@ -346,6 +353,16 @@ The usage is straightforward:
 <% end %>
 ```
 
+## Audit Trail
+
+Rabarber supports audit trail, which provides a record of user access control activity. This feature logs the following events:
+
+- Role assignments to users
+- Role revocations from users
+- Unauthorized access attempts
+
+The logs are written to the file `log/rabarber_audit.log` unless the `audit_trail_enabled` configuration option is set to `false`.
+
 ## Problems?
 
 Facing a problem or want to suggest an enhancement?

data/lib/rabarber/configuration.rb

@@ -1,15 +1,14 @@
 # frozen_string_literal: true
 
-require "singleton"
-
 module Rabarber
   class Configuration
     include Singleton
 
-    attr_reader :cache_enabled, :current_user_method, :must_have_roles,
+    attr_reader :audit_trail_enabled, :cache_enabled, :current_user_method, :must_have_roles,
                 :when_actions_missing, :when_roles_missing, :when_unauthorized
 
     def initialize
+      @audit_trail_enabled = default_audit_trail_enabled
       @cache_enabled = default_cache_enabled
       @current_user_method = default_current_user_method
       @must_have_roles = default_must_have_roles
@@ -18,6 +17,12 @@ module Rabarber
       @when_unauthorized = default_when_unauthorized
     end
 
+    def audit_trail_enabled=(value)
+      @audit_trail_enabled = Rabarber::Input::Types::Boolean.new(
+        value, Rabarber::ConfigurationError, "Configuration 'audit_trail_enabled' must be a Boolean"
+      ).process
+    end
+
     def cache_enabled=(value)
       @cache_enabled = Rabarber::Input::Types::Boolean.new(
         value, Rabarber::ConfigurationError, "Configuration 'cache_enabled' must be a Boolean"
@@ -56,6 +61,10 @@ module Rabarber
 
     private
 
+    def default_audit_trail_enabled
+      true
+    end
+
     def default_cache_enabled
       true
     end
@@ -70,21 +79,20 @@ module Rabarber
 
     def default_when_actions_missing
       -> (missing_actions, context) {
-        raise Rabarber::Error, "Missing actions: #{missing_actions}, context: #{context[:controller]}"
+        raise(Rabarber::Error, "'grant_access' method called with non-existent actions: #{missing_actions}, context: '#{context[:controller]}'")
       }
     end
 
     def default_when_roles_missing
       -> (missing_roles, context) {
         delimiter = context[:action] ? "#" : ""
-        message = "Missing roles: #{missing_roles}, context: #{context[:controller]}#{delimiter}#{context[:action]}"
+        message = "'grant_access' method called with non-existent roles: #{missing_roles}, context: '#{context[:controller]}#{delimiter}#{context[:action]}'"
         Rabarber::Logger.log(:warn, message)
       }
     end
 
     def default_when_unauthorized
       -> (controller) do
-        Rabarber::Logger.log(:warn, "Unauthorized attempt")
         if controller.request.format.html?
           controller.redirect_back fallback_location: controller.main_app.root_path
         else

data/lib/rabarber/controllers/concerns/authorization.rb

@@ -28,14 +28,18 @@ module Rabarber
       Rabarber::Missing::Actions.new(self.class).handle
       Rabarber::Missing::Roles.new(self.class).handle
 
-      return if Rabarber::Core::Permissions.access_granted?(rabarber_roles, self.class, action_name.to_sym, self)
+      roleable = send(Rabarber::Configuration.instance.current_user_method)
 
-      Rabarber::Configuration.instance.when_unauthorized.call(self)
-    end
+      return if Rabarber::Core::Permissions.access_granted?(
+        roleable ? roleable.roles : [], self.class, action_name.to_sym, self
+      )
 
-    def rabarber_roles
-      user = send(Rabarber::Configuration.instance.current_user_method)
-      user ? user.roles : []
+      Rabarber::Logger.audit(
+        :warn,
+        "[Unauthorized Attempt] #{Rabarber::Logger.roleable_identity(roleable, with_roles: true)} attempted to access '#{request.path}'"
+      )
+
+      Rabarber::Configuration.instance.when_unauthorized.call(self)
     end
   end
 end

data/lib/rabarber/logger.rb

@@ -1,11 +1,40 @@
 # frozen_string_literal: true
 
 module Rabarber
-  module Logger
-    module_function
+  class Logger
+    include Singleton
 
-    def log(log_level, message)
-      Rails.logger.tagged("Rabarber") { Rails.logger.public_send(log_level, message) }
+    attr_reader :rails_logger, :audit_logger
+
+    def initialize
+      @rails_logger = Rails.logger
+      @audit_logger = ::Logger.new(Rails.root.join("log/rabarber_audit.log"))
+    end
+
+    class << self
+      def log(log_level, message)
+        instance.rails_logger.tagged("Rabarber") { instance.rails_logger.public_send(log_level, message) }
+      end
+
+      def audit(log_level, message)
+        return unless Rabarber::Configuration.instance.audit_trail_enabled
+
+        instance.audit_logger.public_send(log_level, message)
+      end
+
+      def roleable_identity(roleable, with_roles:)
+        if roleable
+          model_name = roleable.model_name.human
+          primary_key = roleable.class.primary_key
+          roleable_id = roleable.public_send(primary_key)
+
+          roles = with_roles ? ", roles: #{roleable.roles}" : ""
+
+          "#{model_name} with #{primary_key}: '#{roleable_id}'#{roles}"
+        else
+          "Unauthenticated user"
+        end
+      end
     end
   end
 end

data/lib/rabarber/missing/roles.rb

@@ -16,9 +16,7 @@ module Rabarber
         action_rules.each do |controller, controller_action_rules|
           controller_action_rules.each do |action_rule|
             missing_roles = action_rule.roles - all_roles
-            if missing_roles.any?
-              missing_list << Rabarber::Missing::Item.new(missing_roles, controller, action_rule.action)
-            end
+            missing_list << Rabarber::Missing::Item.new(missing_roles, controller, action_rule.action) if missing_roles.any?
           end
         end
       end

data/lib/rabarber/models/concerns/has_roles.rb

@@ -5,9 +5,7 @@ module Rabarber
     extend ActiveSupport::Concern
 
     included do
-      if defined?(@@included) && @@included != name
-        raise Rabarber::Error, "Rabarber::HasRoles can only be included once"
-      end
+      raise Rabarber::Error, "Rabarber::HasRoles can only be included once" if defined?(@@included) && @@included != name
 
       @@included = name
 
@@ -27,26 +25,37 @@ module Rabarber
     end
 
     def assign_roles(*role_names, create_new: true)
-      roles_to_assign = process_role_names(role_names)
+      processed_role_names = process_role_names(role_names)
 
-      create_new_roles(roles_to_assign) if create_new
+      create_new_roles(processed_role_names) if create_new
 
-      new_roles = Rabarber::Role.where(name: roles_to_assign) - rabarber_roles
+      roles_to_assign = Rabarber::Role.where(name: processed_role_names) - rabarber_roles
 
-      if new_roles.any?
+      if roles_to_assign.any?
         delete_roleable_cache
-        rabarber_roles << new_roles
+        rabarber_roles << roles_to_assign
+
+        Rabarber::Logger.audit(
+          :info,
+          "[Role Assignment] #{Rabarber::Logger.roleable_identity(self, with_roles: false)} has been assigned the following roles: #{roles_to_assign.pluck(:name).map(&:to_sym)}, current roles: #{roles}"
+        )
       end
 
       roles
     end
 
     def revoke_roles(*role_names)
-      new_roles = rabarber_roles - Rabarber::Role.where(name: process_role_names(role_names))
+      processed_role_names = process_role_names(role_names)
+      roles_to_revoke = Rabarber::Role.where(name: processed_role_names.intersection(roles))
 
-      if rabarber_roles != new_roles
+      if roles_to_revoke.any?
         delete_roleable_cache
-        self.rabarber_roles = new_roles
+        self.rabarber_roles -= roles_to_revoke
+
+        Rabarber::Logger.audit(
+          :info,
+          "[Role Revocation] #{Rabarber::Logger.roleable_identity(self, with_roles: false)} has been revoked from the following roles: #{roles_to_revoke.pluck(:name).map(&:to_sym)}, current roles: #{roles}"
+        )
       end
 
       roles

data/lib/rabarber/railtie.rb

@@ -8,6 +8,11 @@ module Rabarber
       app.config.after_initialize do
         Rabarber::Missing::Actions.new.handle
         Rabarber::Missing::Roles.new.handle if Rabarber::Role.table_exists?
+
+        Rabarber::Logger.log(
+          :warn,
+          "DEPRECATION WARNING: Configurations 'when_actions_missing' and 'when_roles_missing' are deprecated and will be removed in v2.0.0"
+        )
       end
     end
   end

data/lib/rabarber/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rabarber
-  VERSION = "1.3.1"
+  VERSION = "1.4.0"
 end

data/lib/rabarber.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "singleton"
+
 require_relative "rabarber/version"
 require_relative "rabarber/logger"
 require_relative "rabarber/configuration"

data/rabarber.gemspec

@@ -7,7 +7,7 @@ Gem::Specification.new do |spec|
   spec.version = Rabarber::VERSION
   spec.authors = ["enjaku4", "trafium"]
   spec.email = ["rabarber_gem@icloud.com"]
-
+  spec.metadata["rubygems_mfa_required"] = "true"
   spec.summary = "Simple role-based authorization library for Ruby on Rails."
   spec.homepage = "https://github.com/enjaku4/rabarber"
   spec.license = "MIT"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rabarber
 version: !ruby/object:Gem::Version
-  version: 1.3.1
+  version: 1.4.0
 platform: ruby
 authors:
 - enjaku4
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-03-07 00:00:00.000000000 Z
+date: 2024-03-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -65,7 +65,8 @@ files:
 homepage: https://github.com/enjaku4/rabarber
 licenses:
 - MIT
-metadata: {}
+metadata:
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -81,7 +82,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.26
+rubygems_version: 3.2.33
 signing_key:
 specification_version: 4
 summary: Simple role-based authorization library for Ruby on Rails.