rbacan 0.1.1 → 0.2.0

data/README.md

@@ -1,81 +1,332 @@
-# Rbacan
+# RBACan
 
-a Role-based access control tool to control user access to the functionnalities of your application
+Role-Based Access Control for Rails. Assign roles to users, attach permissions to roles, and enforce access at the controller, view, and route level.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Setup](#setup)
+- [Configuration](#configuration)
+- [Defining Roles and Permissions](#defining-roles-and-permissions)
+- [Role Management](#role-management)
+- [Checking Permissions](#checking-permissions)
+- [Querying Users by Role or Permission](#querying-users-by-role-or-permission)
+- [Controller Authorization](#controller-authorization)
+- [View Helpers](#view-helpers)
+- [Route Constraints](#route-constraints)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Add to your Gemfile:
 
 ```ruby
 gem 'rbacan'
 ```
 
-And then execute:
+Then run:
+
+```bash
+bundle install
+```
+
+---
+
+## Setup
+
+**1. Run the generator**
+
+```bash
+rails generate rbacan:install
+```
+
+This copies four migrations, a seed helper file, and an initializer into your app.
+
+**2. Migrate**
+
+```bash
+rails db:migrate
+```
+
+**3. Include the concern in your user model**
+
+```ruby
+class User < ApplicationRecord
+  include Rbacan::Permittable
+end
+```
+
+**4. Define your roles and permissions in `db/seeds.rb`**
+
+Open `db/copy_to_seeds.rb` (created by the generator) and copy its contents into your `db/seeds.rb`. Fill in your roles and permissions, then run:
+
+```bash
+rails db:seed
+```
+
+---
+
+## Configuration
+
+The generator creates `config/initializers/rbacan.rb`. All options are optional — the defaults work for a standard Devise setup.
+
+```ruby
+Rbacan.configure do |config|
+  # Your user model name (default: "User")
+  config.permittable_class = "User"
+
+  # Override model class names if you have custom implementations
+  # config.role_class             = "Rbacan::Role"
+  # config.permission_class       = "Rbacan::Permission"
+  # config.user_role_class        = "Rbacan::UserRole"
+  # config.role_permission_class  = "Rbacan::RolePermission"
+
+  # Override table names if needed
+  # config.role_table             = "roles"
+  # config.permission_table       = "permissions"
+  # config.user_role_table        = "user_roles"
+  # config.role_permission_table  = "role_permissions"
+
+  # How to handle unauthorized access (see Controller Authorization)
+  # config.unauthorized_handler = :raise       # default — raises Rbacan::NotAuthorized
+  # config.unauthorized_handler = :redirect    # redirects to unauthorized_redirect_path
+  # config.unauthorized_handler = ->(controller, permission:, role:) {
+  #   controller.render plain: "Forbidden", status: :forbidden
+  # }
+
+  # Redirect path used when unauthorized_handler is :redirect (default: "/")
+  # config.unauthorized_redirect_path = "/login"
+end
+```
+
+---
+
+## Defining Roles and Permissions
+
+Use the `Rbacan::RolesAndPermissions` module in your seeds. All methods are idempotent — safe to run multiple times.
+
+```ruby
+# db/seeds.rb
+
+roles       = ["admin", "moderator", "viewer"]
+permissions = ["edit_post", "delete_post", "publish_post", "view_dashboard"]
+
+Rbacan::RolesAndPermissions.create_roles(roles)
+Rbacan::RolesAndPermissions.create_permissions(permissions)
+
+# Assign permissions to each role
+Rbacan::RolesAndPermissions.assign_permissions_to_role("admin",     permissions)
+Rbacan::RolesAndPermissions.assign_permissions_to_role("moderator", ["edit_post", "publish_post"])
+Rbacan::RolesAndPermissions.assign_permissions_to_role("viewer",    ["view_dashboard"])
+```
+
+You can also create roles and permissions programmatically at runtime:
+
+```ruby
+Rbacan.create_role("editor")
+Rbacan.create_permission("manage_comments")
+Rbacan.assign_permission_to_role("editor", "manage_comments")
+```
+
+---
+
+## Role Management
+
+```ruby
+user = User.find(1)
+
+# Assign a role — idempotent, safe to call multiple times
+user.assign_role("admin")
+user.assign_role(:moderator)
+
+# Remove a role
+user.remove_role("moderator")
+```
+
+---
+
+## Checking Permissions
+
+### On a single permission
+
+```ruby
+user.can?("edit_post")   # => true or false
+user.can?(:edit_post)    # symbols work too
+```
+
+### Checking all permissions at once
+
+```ruby
+# Returns true only if the user has every listed permission
+user.can_all?(:edit_post, :delete_post, :publish_post)
+```
+
+### Checking roles
 
-    $ bundle
+```ruby
+# Does the user have this specific role?
+user.has_role?(:admin)
+
+# Does the user have at least one of these roles?
+user.has_any_role?(:admin, :moderator)
+```
 
-Or install it yourself as:
+---
 
-    $ gem install rbacan
+## Querying Users by Role or Permission
 
-## Usage
+Use these ActiveRecord scopes to query your user table.
 
 ```ruby
-run rails generate rbacan:install
+# All users with the admin role
+User.with_role(:admin)
+
+# All users who have a given permission (via any of their roles)
+User.with_permission(:publish_post)
+
+# Combine with other scopes
+User.with_role(:moderator).where(active: true)
 ```
 
-copy the content in the generated file db/copy_to_seed.rb in your seeds.rb file
-you have there all the tools you need to create you roles and permissions
+---
+
+## Controller Authorization
 
-You might need to configure you user class_name if you're using a different class_name for the user, go to rbacan.rb in your initializers folder and make your change
+Include `Rbacan::Authorization` in your `ApplicationController` (or any specific controller):
 
 ```ruby
-    Rbacan.configure do |config|
-    config.permittable_class = "YOUR USER CLASS_NAME"
-    end
+class ApplicationController < ActionController::Base
+  include Rbacan::Authorization
+end
 ```
 
-if you want to assign a role to a user it is simple you just have to do so:
+Then use `authorize!` or `authorize_role!` as `before_action` callbacks:
 
-    user = current_user
+```ruby
+class PostsController < ApplicationController
+  before_action -> { authorize!(:edit_post) },   only: [:edit, :update]
+  before_action -> { authorize!(:delete_post) },  only: [:destroy]
+  before_action -> { authorize_role!(:admin) },   only: [:admin_index]
+end
+```
 
-    user.assign_role(role_name)
+Or call them directly inside an action:
 
-to remove a role from user do this:
+```ruby
+def destroy
+  authorize!(:delete_post)
+  @post.destroy
+end
+```
 
-    user.remove_role(role_name)
+### Handling unauthorized access
 
-now when you want to test if a user have access to a functionnality use this:
+The default behavior raises `Rbacan::NotAuthorized`. You can rescue it globally:
 
-    user.can?(permission_name)
+```ruby
+# app/controllers/application_controller.rb
+rescue_from Rbacan::NotAuthorized, with: :handle_unauthorized
 
-add this line to your user model:
+private
 
-    include Rbacan::Permittable
+def handle_unauthorized(exception)
+  render plain: exception.message, status: :forbidden
+end
+```
 
-run:
+Or configure a different handler in the initializer:
 
 ```ruby
-    rails db:migrate
-    rails db:seed
+# Redirect to a path instead of raising
+config.unauthorized_handler      = :redirect
+config.unauthorized_redirect_path = "/login"
+
+# Or use a fully custom lambda
+config.unauthorized_handler = ->(controller, permission:, role:) {
+  controller.render json: { error: "Forbidden" }, status: :forbidden
+}
 ```
 
-enjoy :D
+---
+
+## View Helpers
+
+`Rbacan::ViewHelpers` is automatically included in all views. Use `authorized?` to conditionally render content:
+
+```erb
+<% authorized?(:delete_post) do %>
+  <%= link_to "Delete", post_path(@post), data: { turbo_method: :delete } %>
+<% end %>
+
+<% authorized?(:publish_post) do %>
+  <%= button_to "Publish", publish_post_path(@post) %>
+<% end %>
+```
+
+You can also use `has_role?` and `has_any_role?` directly in views since they are instance methods on the user:
+
+```erb
+<% if current_user.has_role?(:admin) %>
+  <%= link_to "Admin Panel", admin_root_path %>
+<% end %>
+
+<% if current_user.has_any_role?(:admin, :moderator) %>
+  <%= link_to "Moderation Queue", moderation_path %>
+<% end %>
+```
+
+---
+
+## Route Constraints
+
+Restrict access to entire route namespaces based on role or permission. Add constraints in `config/routes.rb`:
+
+```ruby
+# Restrict by role
+constraints Rbacan::RouteConstraint.new(role: :admin) do
+  namespace :admin do
+    resources :users
+    resources :roles
+  end
+end
+
+# Restrict by permission
+constraints Rbacan::RouteConstraint.new(permission: :access_dashboard) do
+  get "/dashboard", to: "dashboard#index"
+end
+```
+
+The constraint reads the current user from the Warden session (used by Devise). For apps using a manual session, it falls back to looking up `session[:user_id]`.
+
+---
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+```bash
+bin/setup          # install dependencies
+bundle exec rake spec                        # run all tests
+bundle exec rspec spec/rbacan_spec.rb        # run a specific file
+bundle exec rake install                     # install gem locally
+```
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To release a new version:
 
-## Contributing
+1. Bump the version in `lib/rbacan/version.rb`
+2. `gem build rbacan.gemspec`
+3. `gem push rbacan-<version>.gem`
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/hamdi777/RBACan. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+---
 
-## License
+## Contributing
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+Bug reports and pull requests are welcome on GitHub at https://github.com/hamdi777/RBACan.
 
-## Code of Conduct
+---
+
+## License
 
-Everyone interacting in the Rbacan project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/rbacan/blob/master/CODE_OF_CONDUCT.md).
+Available as open source under the [MIT License](https://opensource.org/licenses/MIT).

data/app/models/rbacan/user_role.rb

@@ -1,6 +1,7 @@
 module Rbacan
     class UserRole < ApplicationRecord
         self.table_name = Rbacan.user_role_table
+
         belongs_to :role, class_name: Rbacan.role_class
         belongs_to :user, class_name: Rbacan.permittable_class
     end

data/lib/generators/install/templates/copy_to_seeds.rb

@@ -1,26 +1,22 @@
-#Copy the content of this file into your seeds.rb and comment what you don't need
+# Copy the content of this file into your seeds.rb and uncomment what you need.
 
-
-# define the roles you are going to use example: roles = ["support", "carrier", "mid lane :D", "bot lane :p"]
+# Define the roles you want, e.g.:
+#   roles = ["admin", "moderator", "viewer"]
 roles = []
-# create roles
 Rbacan::RolesAndPermissions.create_roles(roles)
 
 
-# define the permissions you are going to use example: permissions = ["fire", "invoke", "fly"]
+# Define the permissions you want, e.g.:
+#   permissions = ["edit_post", "delete_post", "publish_post"]
 permissions = []
-# create permissions
 Rbacan::RolesAndPermissions.create_permissions(permissions)
 
 
-# now assign some permissions to each role 
-# to do that you need to define an array of the permissions you want to assign example: 
-# role_permissions = ["fly", "fire"]
-role_permissions = []
-Rbacan::RolesAndPermissions.assign_permissions_to_role(role_name, role_permissions)
-# example Rbacan::RolesAndPermissions.assign_permissions_to_role("mid lane :D", role_permissions)
-# you can even define an array of many roles and then do :
-# roles.each do |role|
-#   role_name = role.name
-#   Rbacan::RolesAndPermissions.assign_permissions_to_role(role_name, role_permissions)
-# end
+# Assign permissions to a role. Repeat this block for each role you want to configure.
+# Replace "admin" with the role name, and list the permissions it should have.
+#
+# role_permissions = ["edit_post", "delete_post", "publish_post"]
+# Rbacan::RolesAndPermissions.assign_permissions_to_role("admin", role_permissions)
+#
+# To assign all permissions to a role:
+# Rbacan::RolesAndPermissions.assign_permissions_to_role("admin", permissions)

data/lib/generators/install/templates/create_permissions.rb

@@ -1,9 +1,11 @@
-class CreatePermissions < ActiveRecord::Migration[5.2]
-    def change
-        create_table :permissions do |t|
-            t.string :name
-      
-            t.timestamps
-        end
+class CreatePermissions < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :permissions do |t|
+      t.string :name, null: false
+
+      t.timestamps
     end
+
+    add_index :permissions, :name, unique: true
+  end
 end

data/lib/generators/install/templates/create_role_permissions.rb

@@ -1,9 +1,12 @@
-class CreateRolePermissions < ActiveRecord::Migration[5.2]
-    def change
-        create_table :role_permissions do |t|
-            t.references :role, index: true, foreign_key: {on_delete: :cascade}
-            t.references :permission, index: true,  foreign_key: {on_delete: :cascade}
-            t.timestamps
-        end
+class CreateRolePermissions < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :role_permissions do |t|
+      t.references :role,       null: false, index: true, foreign_key: { to_table: :roles,       on_delete: :cascade }
+      t.references :permission, null: false, index: true, foreign_key: { to_table: :permissions, on_delete: :cascade }
+
+      t.timestamps
     end
+
+    add_index :role_permissions, [:role_id, :permission_id], unique: true
+  end
 end

data/lib/generators/install/templates/create_roles.rb

@@ -1,9 +1,11 @@
-class CreateRoles < ActiveRecord::Migration[5.2]
-    def change
-        create_table :roles do |t|
-            t.string :name
-      
-            t.timestamps
-        end
+class CreateRoles < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :roles do |t|
+      t.string :name, null: false
+
+      t.timestamps
     end
+
+    add_index :roles, :name, unique: true
+  end
 end

data/lib/generators/install/templates/create_user_roles.rb

@@ -1,10 +1,13 @@
-class CreateUserRoles < ActiveRecord::Migration[5.2]
-    def change
-        create_table :user_roles do |t|
-            t.references :role, index: true, foreign_key: {on_delete: :cascade}
-            t.references :user, index: true, foreign_key: {on_delete: :cascade}
-      
-            t.timestamps
-        end
+class CreateUserRoles < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :user_roles do |t|
+      t.references :role, null: false, index: true, foreign_key: { to_table: :roles, on_delete: :cascade }
+      t.bigint :user_id,  null: false
+
+      t.timestamps
     end
+
+    add_index :user_roles, :user_id
+    add_index :user_roles, [:user_id, :role_id], unique: true
+  end
 end

data/lib/generators/install/templates/rbacan.rb

@@ -1,3 +1,30 @@
 Rbacan.configure do |config|
+  # The name of your user model (default: "User")
   # config.permittable_class = "User"
+
+  # Override AR model class names if you have custom models
+  # config.role_class             = "Rbacan::Role"
+  # config.permission_class       = "Rbacan::Permission"
+  # config.user_role_class        = "Rbacan::UserRole"
+  # config.role_permission_class  = "Rbacan::RolePermission"
+
+  # Override table names if needed
+  # config.role_table             = "roles"
+  # config.permission_table       = "permissions"
+  # config.user_role_table        = "user_roles"
+  # config.role_permission_table  = "role_permissions"
+
+  # Authorization failure handling:
+  #   :raise    — raises Rbacan::NotAuthorized (default)
+  #   :redirect — redirects to unauthorized_redirect_path
+  #   lambda    — called with (controller, permission:, role:)
+  #
+  # config.unauthorized_handler = :raise
+  # config.unauthorized_handler = :redirect
+  # config.unauthorized_handler = ->(controller, permission:, role:) {
+  #   controller.render plain: "Forbidden", status: :forbidden
+  # }
+
+  # Path to redirect to when unauthorized_handler is :redirect
+  # config.unauthorized_redirect_path = "/"
 end

data/lib/rbacan/authorization.rb

@@ -0,0 +1,46 @@
+require 'active_support/concern'
+
+module Rbacan
+  module Authorization
+    extend ActiveSupport::Concern
+
+    included do
+      helper_method :authorized? if respond_to?(:helper_method)
+    end
+
+    # Calls the unauthorized handler if current_user lacks the given permission.
+    def authorize!(permission)
+      unless current_user&.can?(permission.to_s)
+        _handle_unauthorized(permission: permission.to_s)
+      end
+    end
+
+    # Calls the unauthorized handler if current_user lacks the given role.
+    def authorize_role!(role)
+      unless current_user&.has_role?(role.to_s)
+        _handle_unauthorized(role: role.to_s)
+      end
+    end
+
+    private
+
+    def _handle_unauthorized(permission: nil, role: nil)
+      handler = Rbacan.unauthorized_handler
+
+      case handler
+      when :raise
+        raise Rbacan::NotAuthorized.new(nil, permission: permission, role: role)
+      when :redirect
+        redirect_to Rbacan.unauthorized_redirect_path,
+                    alert: Rbacan::NotAuthorized.new(nil, permission: permission, role: role).message
+      else
+        if handler.respond_to?(:call)
+          handler.call(self, permission: permission, role: role)
+        else
+          raise ArgumentError,
+                "Rbacan.unauthorized_handler must be :raise, :redirect, or a callable. Got: #{handler.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/rbacan/engine.rb

@@ -1,6 +1,12 @@
 module Rbacan
-    require "rails/all"
-    class Engine < ::Rails::Engine
-        engine_name 'rbacan'    
+  require "rails/all"
+  class Engine < ::Rails::Engine
+    engine_name 'rbacan'
+
+    initializer "rbacan.view_helpers" do
+      ActiveSupport.on_load(:action_view) do
+        include Rbacan::ViewHelpers
+      end
     end
+  end
 end

data/lib/rbacan/not_authorized.rb

@@ -0,0 +1,23 @@
+module Rbacan
+  class NotAuthorized < StandardError
+    attr_reader :permission, :role
+
+    def initialize(message = nil, permission: nil, role: nil)
+      @permission = permission
+      @role       = role
+      super(message || default_message)
+    end
+
+    private
+
+    def default_message
+      if permission
+        "Not authorized: missing permission '#{permission}'"
+      elsif role
+        "Not authorized: missing role '#{role}'"
+      else
+        "Not authorized"
+      end
+    end
+  end
+end