rabarber 1.4.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bcddaf07627eb382c58a733150e460348527476d2234f65fe0db2760bce6206f
-  data.tar.gz: 3d1bbfab2a57d860bcb9656cadb5606d09674f887a58b96db0897c3516aed5d2
+  metadata.gz: f719eb670170521e94a58a1c75d30110699ab941da6d5dae151fbf53e0eb9880
+  data.tar.gz: bd06646e15ab2eb5ff7b49d2a18316c4b539b95aa98bd2ec1b4de5c6b5fb921a
 SHA512:
-  metadata.gz: e5ae51e17b580757cc427f269b43155ca3ea5eda5b4813be5d023c273f2271d96108639e24c1921ace823de4cc06b43c03372eb98d64f6d4376f9628e7b6d616
-  data.tar.gz: 232a9ded49264955b8cf7d22de5a1443947dd84d90f44f15f6dc9c9346ee7b1cee56afa85a55bf44bf5325bb1d26e17e6fcf0b8076d3f14381a9bb43254038ab
+  metadata.gz: 0db86c7d46337decbe9972ea3b0c1ad30e1c66f2b76b3ef27a494ef8c2ecc9bcf35ce3f135360e74045b7f20beb38149f5ca308af0cb3d3a0db829ff9dc7147b
+  data.tar.gz: d1a20c732318d12ccfe49338df7338dcf09bd1222fd574e8581d035cb38b55295e501bfa45ef63ea0a556a8c21a28abdad7d06ca765c3f14eed6e6cd98db93be

data/CHANGELOG.md

@@ -1,27 +1,53 @@
-## 1.4.0
+## v2.0.0
+
+### Breaking:
+
+- Removed `when_actions_missing` and `when_roles_missing` configuration options
+- Replaced `when_unauthorized` configuration option with an overridable controller method
+- Renamed `Rabarber::Role.assignees_for` method to `Rabarber::Role.assignees`
+
+To upgrade to v2.0.0, please refer to the [migration guide](https://github.com/enjaku4/rabarber/discussions/52).
+
+### Features:
+
+- Added support for UUID primary keys
+
+### Bugs:
+
+- Fixed the issue where an error would occur if the user was not authenticated
+
+### Misc:
+
+- Significant refactoring and code improvements
+
+## v1.4.1
+
+- Fix an issue where an error could be raised when using controller-wide dynamic rules
+
+## v1.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
+## v1.3.1
 
 - Add `Rabarber::Role.assignees_for` method
 - Fix inconsistent behavior where passing `nil` as a role name to role management methods would raise an `ActiveRecord` error instead of `Rabarber` error
 - Various minor code improvements
 
-## 1.3.0
+## v1.3.0
 
 - Add methods to directly add, rename, and remove roles
 - Modify `Rabarber::HasRoles#assign_roles` and `Rabarber::HasRoles#revoke_roles` methods to return the list of roles assigned to the user
 - Minor performance improvements
 
-## 1.2.2
+## v1.2.2
 
 - Refactor to improve readability and maintainability
 - Fix minor code errors
 
-## 1.2.1
+## v1.2.1
 
 - Cache roles to avoid unnecessary database queries
 - Introduce `cache_enabled` configuration option allowing to enable or disable role caching
@@ -29,61 +55,61 @@
 - Fix an issue where an error would be raised if the user is not authenticated
 - Various minor improvements
 
-## 1.2.0
+## v1.2.0
 
 - Enhance handling of missing actions and roles specified in `grant_access` method by raising an error for missing actions and logging a warning for missing roles
 - Introduce `when_actions_missing` and `when_roles_missing` configuration options, allowing to customize the behavior when actions or roles are not found
 
-## 1.1.0
+## v1.1.0
 
 - Add support for `unless` argument in `grant_access` method, allowing to define negated dynamic rules
 - Fix a bug where specifying a dynamic rule as a symbol without specifying an action would result in an error
 
-## 1.0.5
+## v1.0.5
 
 - Add co-author: [trafium](https://github.com/trafium)
 
-## 1.0.4
+## v1.0.4
 
 - Allow to use strings as role names
 
-## 1.0.3
+## v1.0.3
 
 - Enhance clarity by improving error types and messages
 - Resolve inconsistency in types of role names
 
-## 1.0.2
+## v1.0.2
 
 - Various enhancements for gem development and release
 - Modify `Rabarber::HasRoles#roles` method to return an array of role names instead of `Rabarber::Role` objects
 
-## 1.0.1
+## v1.0.1
 
 - Various enhancements for gem development
 
-## 1.0.0
+## v1.0.0
 
 - Drop support for Ruby 2.7
 - Add support for Ruby 3.3
 - Various minor improvements
 
-## 0.1.5
+## v0.1.5
 
 - Add missing `foreign_key` option to `CreateRabarberRoles` migration
 - Allow only lowercase alphanumeric characters and underscores in role names
 
-## 0.1.4
+## v0.1.4
 
 - Remove `Rabarber::HasRoles#role?` method as unnecessary
 
-## 0.1.3
+## v0.1.3
 
 - Fully revise and update README for clarity
 
-## 0.1.2
+## v0.1.2
 
 - Fix check that `Rabarber::HasRoles` can only be included once
 
-## 0.1.1
+## v0.1.1
 
 - Initial release

data/README.md

@@ -9,7 +9,7 @@ Rabarber is a role-based authorization library for Ruby on Rails, primarily desi
 
 **Example of Usage**:
 
-Consider a CRM where users with different roles have distinct access levels. For instance, the role `accountant` can interact with invoices but cannot access marketing information, while the role `marketer` has access to marketing-related data. Such authorization rules can be easily defined with Rabarber.
+Consider a CRM system where users with different roles have distinct access levels. For instance, the role `accountant` can interact with invoices but cannot access marketing information, while the role `marketer` has access to marketing-related data. Such authorization rules can be easily defined with Rabarber.
 
 ---
 
@@ -21,39 +21,65 @@ class TicketsController < ApplicationController
 
   grant_access action: :index, roles: :manager
   def index
-    ...
+    # ...
   end
 
   def delete
-    ...
+    # ...
   end
 end
 ```
 This means that `admin` users can access everything in `TicketsController`, while `manager` role can access only `index` action.
 
+## Table of Contents
+
+**Gem usage:**
+  - [Installation](#installation)
+  - [Configuration](#configuration)
+  - [Roles](#roles)
+  - [Authorization Rules](#authorization-rules)
+  - [Dynamic Authorization Rules](#dynamic-authorization-rules)
+  - [When Unauthorized](#when-unauthorized)
+  - [View Helpers](#view-helpers)
+  - [Audit Trail](#audit-trail)
+
+**Community Resources:**
+  - [Problems?](#problems)
+  - [Contributing](#contributing)
+  - [Code of Conduct](#code-of-conduct)
+
+**Legal:**
+  - [License](#license)
+
 ## Installation
 
 Add the Rabarber gem to your Gemfile:
 
-```
+```rb
 gem "rabarber"
 ```
 
 Install the gem:
 
-```
+```shell
 bundle install
 ```
 
 Next, generate a migration to create tables for storing roles in the database. Make sure to specify the table name of the model representing users in your application as an argument. For instance, if the table name is `users`, run:
 
-```
+```shell
 rails g rabarber:roles users
 ```
 
-Finally, run the migration to apply the changes to the database:
+Rabarber supports UUIDs as primary keys. If your application uses UUIDs, add `--uuid` option to the generator:
 
+```shell
+rails g rabarber:roles users --uuid
 ```
+
+Finally, run the migration to apply the changes to the database:
+
+```shell
 rails db:migrate
 ```
 
@@ -67,29 +93,13 @@ Rabarber.configure do |config|
   config.cache_enabled = true
   config.current_user_method = :current_user
   config.must_have_roles = false
-  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._
-
-### Deprecated Configuration Options
-
-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_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._
+- `audit_trail_enabled` determines whether the audit trail functionality is enabled. The audit trail is enabled by default.
+- `cache_enabled` determines whether roles are cached to avoid unnecessary database queries. Roles are cached by default. If you need to clear the cache, use `Rabarber::Cache.clear` method.
+- `current_user_method` represents the method that returns the currently authenticated user. The default value is `:current_user`.
+- `must_have_roles` determines whether a user with no roles can access endpoints permitted to everyone. The default value is `false` (allowing users without roles to access such endpoints).
 
 ## Roles
 
@@ -98,7 +108,7 @@ Include `Rabarber::HasRoles` module in your model representing users in your app
 ```rb
 class User < ApplicationRecord
   include Rabarber::HasRoles
-  ...
+  # ...
 end
 ```
 
@@ -124,7 +134,7 @@ To revoke roles, use:
 ```rb
 user.revoke_roles(:accountant, :marketer)
 ```
-If any of the specified roles doesn't exist or the user doesn't have the role you want to revoke, it will be ignored.
+If the user doesn't have the role you want to revoke, it will be ignored.
 
 The method returns an array of roles assigned to the user.
 
@@ -140,7 +150,7 @@ It returns `true` if the user has at least one role and `false` otherwise.
 
 **`#roles`**
 
-To view all the roles assigned to the user, use:
+To get all the roles assigned to the user, use:
 
 ```rb
 user.roles
@@ -150,7 +160,7 @@ user.roles
 
 To manipulate roles directly, you can use `Rabarber::Role` methods:
 
-**`.add(role)`**
+**`.add(role_name)`**
 
 To add a new role, use:
 
@@ -167,14 +177,14 @@ To rename a role, use:
 ```rb
 Rabarber::Role.rename(:admin, :administrator)
 ```
-The first argument is the old name, and the second argument is the new name. This will rename the role and return `true`. If a role with the new name already exists, it will return `false`.
+The first argument is the old name, and the second argument is the new name. This will rename the role and return `true`. If the role with a new name already exists, it will return `false`.
 
 The method won't rename the role and will return `false` if it is assigned to any user. To force the rename, use the method with `force: true` argument:
 ```rb
 Rabarber::Role.rename(:admin, :administrator, force: true)
 ```
 
-**`.remove(role, force: false)`**
+**`.remove(role_name, force: false)`**
 
 To remove a role, use:
 
@@ -197,12 +207,12 @@ If you need to list all the role names available in your application, use:
 Rabarber::Role.names
 ```
 
-**`.assignees_for(role)`**
+**`.assignees(role_name)`**
 
 To get all the users to whom the role is assigned, use:
 
 ```rb
-Rabarber::Role.assignees_for(:admin)
+Rabarber::Role.assignees(:admin)
 ```
 
 ## Authorization Rules
@@ -212,7 +222,7 @@ Include `Rabarber::Authorization` module into the controller that needs authoriz
 ```rb
 class ApplicationController < ActionController::Base
   include Rabarber::Authorization
-  ...
+  # ...
 end
 ```
 This adds `.grant_access(action: nil, roles: nil, if: nil, unless: nil)` method which allows you to define the authorization rules.
@@ -220,19 +230,23 @@ This adds `.grant_access(action: nil, roles: nil, if: nil, unless: nil)` method
 The most basic usage of the method is as follows:
 
 ```rb
-class InvoicesController < ApplicationController
+class Crm::InvoicesController < ApplicationController
   grant_access action: :index, roles: [:accountant, :admin]
   def index
-    ...
+    @invoices = Invoice.all
+    @invoices = @invoices.paid if current_user.has_role?(:accountant)
+    # ...
   end
 
-  grant_access action: :delete, roles: :admin
-  def delete
-    ...
+  grant_access action: :destroy, roles: :admin
+  def destroy
+    # ...
   end
 end
 ```
-This grants access to `index` action for users with `accountant` or `admin` role, and access to `delete` action for `admin` users only.
+This grants access to `index` action for users with `accountant` or `admin` role, and access to `destroy` action for `admin` users only.
+
+Please note that Rabarber does not provide any built-in data scoping mechanism as it is not a part of the authorization layer and is not necessarily role specific or has anything to do with the current user. The business logic can vary drastically depending on the application, so you're encouraged to limit the data visibility yourself, for example, in the same way as in the example above, where `accountant` role can only see paid invoices.
 
 You can also define controller-wide rules (without `action` argument):
 
@@ -242,18 +256,18 @@ class Crm::BaseController < ApplicationController
 
   grant_access action: :dashboard, roles: :marketer
   def dashboard
-    ...
+    # ...
   end
 end
 
 class Crm::InvoicesController < Crm::BaseController
   grant_access roles: :accountant
   def index
-    ...
+    # ...
   end
 
   def delete
-    ...
+    # ...
   end
 end
 ```
@@ -264,35 +278,53 @@ Roles can also be omitted:
 ```rb
 class OrdersController < ApplicationController
   grant_access
-  ...
+  # ...
 end
 
 class InvoicesController < ApplicationController
   grant_access action: :index
   def index
-    ...
+    # ...
   end
 end
 ```
 
 This allows everyone to access `OrdersController` and its children and also `index` action in `InvoicesController`. This extends to scenarios where there is no user present, i.e. when the method responsible for returning the currently authenticated user in your application returns `nil`.
 
-_Be aware that if the user is not authenticated (the method responsible for returning the currently authenticated user in your application returns `nil`), Rabarber will treat this situation as if the user with no roles assigned was authenticated._
+If the user is not authenticated (the method responsible for returning the currently authenticated user in your application returns `nil`), Rabarber will handle this situation as if the user has no roles.
 
-If you've set `must_have_roles` setting to `true`, then, only the users with at least one role can have access. This setting can be useful if your requirements are such that users without roles are not allowed to access anything.
+If you've set `must_have_roles` setting to `true`, then only the users with at least one role can gain access. This setting can be useful if your requirements are such that users without roles (or unauthenticated users) are not allowed to access anything.
+
+Also keep in mind that rules defined in child classes don't override parent rules but rather add to them:
+```rb
+class Crm::BaseController < ApplicationController
+  grant_access roles: :admin
+  # ...
+end
+
+class Crm::InvoicesController < Crm::BaseController
+  grant_access roles: :accountant
+  # ...
+end
+```
+This means that `Crm::InvoicesController` is still accessible to `admin` but is also accessible to `accountant`.
+
+## Dynamic Authorization Rules
 
 For more complex cases, Rabarber provides dynamic rules:
 
 ```rb
-class OrdersController < ApplicationController
-  grant_access if: :current_company_accountant?
-  grant_access unless: :fired?
-  ...
+class Crm::OrdersController < ApplicationController
+  grant_access roles: :manager, if: :company_manager?, unless: :fired?
+
+  def index
+    # ...
+  end
 
   private
 
-  def current_company_accountant?
-    current_company.accountant == current_user
+  def company_manager?
+    Company.find(params[:company_id]).manager == current_user
   end
 
   def fired?
@@ -300,33 +332,65 @@ class OrdersController < ApplicationController
   end
 end
 
-class InvoicesController < ApplicationController
-  grant_access action: :index, roles: :accountant, if: -> { current_user.passed_probation_period? }
+class Crm::InvoicesController < ApplicationController
+  grant_access roles: :senior_accountant
+
+  grant_access action: :index, roles: [:secretary, :accountant], if: -> { InvoicesPolicy.new(current_user).can_access?(:index) }
   def index
-    ...
+    @invoices = Invoice.all
+    @invoices = @invoices.where("total < 10000") if current_user.has_role?(:accountant)
+    @invoices = @invoices.unpaid if current_user.has_role?(:secretary)
+    # ...
   end
 
-  grant_access action: :show, roles: :client, unless: -> { current_user.banned? }
+  grant_access action: :show, roles: :accountant, unless: -> { Invoice.find(params[:id]).total > 10_000 }
   def show
-    ...
+    # ...
   end
 end
 ```
-You can pass a dynamic rule as `if` or `unless` argument. It can be a symbol, in which case the method with the same name will be called. Alternatively, it can be a proc, which will be executed within the context of the controller's instance.
+You can pass a dynamic rule as `if` or `unless` argument. It can be a symbol, in which case the method with that name will be called. Alternatively, it can be a proc, which will be executed within the context of the controller's instance.
 
-Rules defined in child classes don't override parent rules but rather add to them:
+You can use only dynamic rules without specifying roles if that suits your needs:
 ```rb
-class Crm::BaseController < ApplicationController
-  grant_access roles: :admin
-  ...
+class InvoicesController < ApplicationController
+  grant_access action: :index, if: -> { current_user.company == Company.find(params[:company_id]) }
+  def index
+    # ...
+  end
+end
+```
+This basically allows you to use Rabarber as a policy-based authorization library by calling your own custom policy within a dynamic rule:
+```rb
+class InvoicesController < ApplicationController
+  grant_access action: :index, if: -> { InvoicesPolicy.new(current_user).can_access?(:index) }
+  def index
+    # ...
+  end
 end
+```
 
-class Crm::InvoicesController < Crm::BaseController
-  grant_access roles: :accountant
-  ...
+## When Unauthorized
+
+By default, in the event of an unauthorized attempt, Rabarber redirects the user back if the request format is HTML (with fallback to the root path), and returns a 401 (Unauthorized) status code otherwise.
+
+This behavior can be customized by overriding private `when_unauthorized` method:
+
+```rb
+class ApplicationController < ActionController::Base
+  include Rabarber::Authorization
+
+  # ...
+
+  private
+
+  def when_unauthorized
+    head :not_found # pretend the page doesn't exist
+  end
 end
 ```
-This means that `Crm::InvoicesController` is still accessible to `admin` but is also accessible to `accountant`.
+
+The method can be overridden in different controllers, providing flexibility in handling unauthorized access attempts.
 
 ## View Helpers
 
@@ -335,7 +399,7 @@ Rabarber also provides a couple of helpers that can be used in views: `visible_t
 ```rb
 module ApplicationHelper
   include Rabarber::Helpers
-  ...
+  # ...
 end
 ```
 
@@ -367,7 +431,7 @@ The logs are written to the file `log/rabarber_audit.log` unless the `audit_trai
 
 Facing a problem or want to suggest an enhancement?
 
-- **Open a Discussion**: If you have a question, experience difficulties using the gem, or have an improvement suggestion, feel free to use the Discussions section.
+- **Open a Discussion**: If you have a question, experience difficulties using the gem, or have a suggestion for improvements, feel free to use the Discussions section.
 
 Encountered a bug?
 
@@ -376,12 +440,12 @@ Encountered a bug?
 
 ## Contributing
 
-Before opening an issue or creating a pull request, please read the [contributing guidelines](https://github.com/enjaku4/rabarber/blob/main/CONTRIBUTING.md).
-
-## License
-
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+Before creating an issue or a pull request, please read the [contributing guidelines](https://github.com/enjaku4/rabarber/blob/main/CONTRIBUTING.md).
 
 ## Code of Conduct
 
 Everyone interacting in the Rabarber project is expected to follow the [code of conduct](https://github.com/enjaku4/rabarber/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://github.com/enjaku4/rabarber/blob/main/LICENSE.txt).

data/lib/generators/rabarber/roles_generator.rb

@@ -10,6 +10,8 @@ module Rabarber
 
     argument :table_name, type: :string, required: true
 
+    class_option :uuid, type: :boolean, default: false, desc: "Use UUIDs as primary keys"
+
     def create_migrations
       migration_template "create_rabarber_roles.rb.erb", "db/migrate/create_rabarber_roles.rb"
     end

data/lib/generators/rabarber/templates/create_rabarber_roles.rb.erb

@@ -2,14 +2,14 @@
 
 class CreateRabarberRoles < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version.to_s %>]
   def change
-    create_table :rabarber_roles do |t|
+    create_table :rabarber_roles<%= ", id: :uuid" if options[:uuid] %> do |t|
       t.string :name, null: false, index: { unique: true }
       t.timestamps
     end
 
     create_table :rabarber_roles_roleables, id: false do |t|
-      t.belongs_to :role, null: false, index: true, foreign_key: { to_table: :rabarber_roles }
-      t.belongs_to :roleable, null: false, index: true, foreign_key: { to_table: <%= table_name.to_sym.inspect %> }
+      t.belongs_to :role, null: false, index: true, foreign_key: { to_table: :rabarber_roles }<%= ", type: :uuid" if options[:uuid] %>
+      t.belongs_to :roleable, null: false, index: true, foreign_key: { to_table: <%= table_name.to_sym.inspect %> }<%= ", type: :uuid" if options[:uuid] %>
     end
 
     add_index :rabarber_roles_roleables, [:role_id, :roleable_id], unique: true

data/lib/rabarber/audit/events/base.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative "../logger"
+
+module Rabarber
+  module Audit
+    module Events
+      class Base
+        attr_reader :roleable, :specifics
+
+        def self.trigger(roleable, specifics)
+          new(roleable, specifics).send(:log)
+        end
+
+        private
+
+        def initialize(roleable, specifics)
+          raise ArgumentError, "Roleable is required for #{self.class} event" if roleable.nil? && !nil_roleable_allowed?
+
+          @roleable = roleable
+          @specifics = specifics
+        end
+
+        def nil_roleable_allowed?
+          raise NotImplementedError
+        end
+
+        def log
+          Rabarber::Audit::Logger.log(log_level, message)
+        end
+
+        def log_level
+          raise NotImplementedError
+        end
+
+        def message
+          raise NotImplementedError
+        end
+
+        def identity
+          roleable_identity(with_roles: identity_with_roles?)
+        end
+
+        def identity_with_roles?
+          raise NotImplementedError
+        end
+
+        def roleable_identity(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 #{Rabarber::HasRoles.roleable_class.model_name.human.downcase}"
+          end
+        end
+      end
+    end
+  end
+end