role_fu 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d8ca75bef3838c779e395c17a16c8e61ddb6a7fdab7b2819412cd9356213436
-  data.tar.gz: b3b280add77cac1f4778c7e72b4ec3717e9554ab053cbcce869ef7180dd98ed2
+  metadata.gz: 3a8521c0afe782f8985577cf76d9b59b950522b1c445150a11db74e7f944718b
+  data.tar.gz: 0a82d9b19260c3ea95b2506cb45ad2e12ab23b64bdb0e3b1c0b84c8f93d8061f
 SHA512:
-  metadata.gz: 0c7448aa048ad1836888270417e15d2acf5375cef727059cac77e9dea5c644d2b5156fc9e90134d9918367b38e4c127f753f5dda01b836c24794baf0102646dd
-  data.tar.gz: 57a6f48677cb49653b3c22e298b13fb3ac13003bb7e8d895e9c17396304e8385b7fb7162db426a7862ce1aad3031396e66dda60a897f898952594ee6011a4784
+  metadata.gz: 386f524a75c3116601af67eaf6612c0bc23893695120a2646ba6d0caafba8bcf7e0bc12dc05d93dc7ddcbc9c508da936cfebf679d973675f5b9742438ed85c50
+  data.tar.gz: d9db11c9b4490d35714acb1f20a4eb576a53584fd235bf0328ca33959f53756221478e5af877dfec5833f1431ccdde9fafded39980d5f90ce87e995dfef20695

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 ## [Unreleased]
 
+## [0.2.0] - 2026-02-03
+
+### Added
+- **Temporal Roles**: Support for role expiration (`expires_at`) and automatic filtering.
+- **Audit Logging**: Built-in generator for audit trails (`RoleAssignmentAudit`) and actor tracking (`RoleFu.with_actor`).
+- **Role Abilities**: Granular permissions system with `Permission` model and `role_fu_can?` helper.
+- **Metadata**: Support for attaching arbitrary JSON metadata to role assignments.
+- **Adapters**: Seamless integration with **Pundit** and **CanCanCan**.
+- **Permissive Mode**: Configuration option `global_roles_override` to match Rolify behavior.
+- **Cleanup Automation**: `rake role_fu:cleanup` task and ActiveJob generator for expired roles.
+- **Custom Aliases**: `role_fu_alias` to generate domain-specific methods (e.g., `add_group`, `in_group`).
+
 ## [0.1.0] - 2026-02-03
 
-- Initial release: modern role management for Rails with explicit models and N+1 prevention.
+- Initial release: modern role management for Rails with explicit models and N+1 prevention.

data/README.md

@@ -1,13 +1,14 @@
 # RoleFu
 
-RoleFu is a modern, explicit role management gem for Ruby on Rails. It is designed as a cleaner, more performant alternative to `rolify`.
+RoleFu is a modern, explicit role management gem for Ruby on Rails. It is designed as a cleaner, more performant alternative to legacy role gems, providing full control over role assignments and granular permissions.
 
 ## Why RoleFu?
 
-- **Explicit Models**: Unlike Rolify which often uses hidden `has_and_belongs_to_many` tables, RoleFu uses an explicit `RoleAssignment` join model. This makes it easier to extend with metadata (e.g., `created_by`, `expires_at`).
-- **N+1 Prevention**: Built-in support for `has_cached_role?` to work with preloaded associations.
-- **Strict by Default**: Focused on resource-specific roles with clear `has_role?` semantics.
-- **Orphaned Role Cleanup**: Automatically deletes roles when the last user assignment is removed.
+- **Explicit Models**: Uses an explicit `RoleAssignment` join model instead of hidden tables, making it easy to add metadata or audit trails.
+- **N+1 Prevention**: Built-in support for `has_cached_role?` and optimized scopes.
+- **Strict by Default**: Resource-specific checks are strict, ensuring global roles don't accidentally leak permissions unless configured otherwise.
+- **Advanced Features**: Supports temporal (expiring) roles, metadata, audit logging, and granular abilities.
+- **Modern Infrastructure**: Fully compatible with Rails 7.0 through 8.1, includes Lefthook and Appraisal support.
 
 ## Installation
 
@@ -25,17 +26,18 @@ bundle install
 
 ### Setup
 
-1. Run the install generator to create the configuration:
+1. **Install Configuration:**
 ```bash
 rails generate role_fu:install
 ```
 
-2. Generate the Role models (default names are `Role` and `RoleAssignment`):
+2. **Generate Models:**
+Default names are `Role` and `RoleAssignment`, linked to the `User` model.
 ```bash
 rails generate role_fu Role User
 ```
 
-3. Run migrations:
+3. **Run Migrations:**
 ```bash
 rails db:migrate
 ```
@@ -49,10 +51,10 @@ Include `RoleFu::Roleable` in your User model (done automatically by the generat
 ```ruby
 class User < ApplicationRecord
   include RoleFu::Roleable
-  
+
   # Optional callbacks
   role_fu_options after_add: :notify_user
-  
+
   def notify_user(role)
     # ...
   end
@@ -65,35 +67,122 @@ end
 user = User.find(1)
 
 # Global roles
-user.add_role(:admin)
-user.grant(:admin) # Alias
+user.grant(:admin)
 user.has_role?(:admin) # => true
-user.remove_role(:admin)
-user.revoke(:admin) # Alias
+user.revoke(:admin)
 
 # Resource-specific roles
 org = Organization.first
-user.add_role(:manager, org)
+user.grant(:manager, org)
 user.has_role?(:manager, org) # => true
 user.has_role?(:manager)      # => false (strict check)
 user.has_role?(:manager, :any) # => true
 user.only_has_role?(:manager, org) # => true if this is their only role
+```
 
-# Scopes (Finders)
+#### Scopes (Finders)
+
+```ruby
 User.with_role(:admin)
 User.with_role(:manager, org)
 User.without_role(:admin)
 User.with_any_role(:admin, :editor)
 User.with_all_roles(:admin, :manager)
+```
 
-# Resource Scopes
-Organization.with_role(:manager, user)
-Organization.without_role(:manager, user)
+---
+
+### Advanced Features
+
+#### 1. Temporal Roles (Expiration)
+Roles can be assigned with an expiration time. They are automatically filtered out from queries once expired.
+
+```ruby
+user.grant(:manager, org, expires_at: 1.week.from_now)
+
+# To physically remove expired roles from the database:
+# rake role_fu:cleanup
+
+# Or generate a scheduled ActiveJob:
+# rails generate role_fu:job
+```
+
+#### 2. Metadata
+Attach arbitrary metadata to a role assignment.
+
+```ruby
+user.grant(:manager, org, meta: { assigned_by: current_user.id, reason: "Project lead" })
+```
+
+#### 3. Audit Log
+Track every grant, revoke, and update (e.g., expiration extensions).
+
+**Setup:**
+```bash
+rails generate role_fu:audit
+rails db:migrate
+```
+
+**Usage:**
+Wrap changes in `with_actor` to capture the responsible user:
+```ruby
+RoleFu.with_actor(current_user) do
+  user.grant(:manager, org)
+end
+
+# Check history
+RoleAssignmentAudit.where(user: user).last
+# => #<RoleAssignmentAudit operation: "INSERT", whodunnit: "1", ...>
+```
+
+#### 4. Role Abilities (Permissions)
+Attach granular permissions to roles.
+
+**Setup:**
+```bash
+rails generate role_fu:abilities
+rails db:migrate
 ```
 
-#### Performance (N+1 Prevention)
+**Usage:**
+```ruby
+# Setup permissions
+manager_role = Role.find_by(name: "manager")
+manager_role.permissions.create(action: "posts.edit")
+
+# Check abilities
+user.role_fu_can?("posts.edit") # => true
+```
+
+---
+
+### Adapters (Pundit & CanCanCan)
+
+#### CanCanCan
+```ruby
+class Ability
+  include CanCan::Ability
+  include RoleFu::Adapters::CanCanCan
+
+  def initialize(user)
+    role_fu_load_permissions!(user)
+  end
+end
+```
 
-Use `has_cached_role?` when roles are preloaded.
+#### Pundit
+```ruby
+class ApplicationPolicy
+  include RoleFu::Adapters::Pundit
+end
+```
+*`PostPolicy#update?` will automatically check `user.role_fu_can?('posts.update')`.*
+
+---
+
+### Performance (N+1 Prevention)
+
+Use `has_cached_role?` when roles are preloaded to avoid database roundtrips.
 
 ```ruby
 users = User.includes(:roles).all
@@ -102,7 +191,7 @@ users.each do |user|
 end
 ```
 
-### Resourceable (Models with roles)
+### Resourceable
 
 Include `RoleFu::Resourceable` in any model that should have roles scoped to it.
 
@@ -113,32 +202,55 @@ end
 
 org = Organization.first
 org.users_with_role(:manager)
-org.count_users_with_role(:admin)
 org.available_roles # ["manager", "admin"]
-```
 
-## Comparison with Rolify
-
-| Feature | Rolify | RoleFu |
-|---------|--------|--------|
-| Join Model | Implicit (HABTM) | Explicit (RoleAssignment) |
-| Performance | Frequent N+1 | Cached role support + Optimized Scopes |
-| Orphaned Roles | Configurable cleanup | Automatic cleanup |
-| Scopes | `User.with_role` | `User.with_role`, `without_role`, `with_any`, `with_all` |
-| Modern Rails | Older codebase | Optimized for Rails 7+ |
+# Scopes
+Organization.with_role(:manager, user)
+Organization.without_role(:manager, user)
+```
 
 ## Configuration
 
-If your models are named differently (e.g., `Account` instead of `User`, or `Group` instead of `Role`), you can configure them in `config/initializers/role_fu.rb`:
+Customize your model names in `config/initializers/role_fu.rb`:
 
 ```ruby
 RoleFu.configure do |config|
   config.user_class_name = "Account"
   config.role_class_name = "Group"
-  config.role_assignment_class_name = "GroupAssignment" # Optional
+  
+  # Enable Rolify-style permissive checks (Global roles override resource checks)
+  config.global_roles_override = true
 end
 ```
 
+## Custom Aliases (e.g. Groups)
+
+If you prefer different terminology (e.g., "Groups" instead of "Roles"), you can alias the methods in your models:
+
+```ruby
+class User < ApplicationRecord
+  include RoleFu::Roleable
+  role_fu_alias :group
+end
+
+# Now you can use:
+user.add_group(:admin)
+user.has_group?(:admin)
+User.in_group(:admin)      # Alias for with_group/with_role
+User.not_in_group(:admin)  # Alias for without_group/without_role
+```
+
+## Migrating from Rolify
+
+1. **Code Changes**: Replace `rolify` with `include RoleFu::Roleable` and `resourcify` with `include RoleFu::Resourceable`.
+2. **Data Migration**:
+```sql
+INSERT INTO role_assignments (user_id, role_id, created_at, updated_at)
+SELECT user_id, role_id, NOW(), NOW()
+FROM users_roles;
+```
+3. **Behavior**: Set `config.global_roles_override = true` if you rely on global roles satisfying resource checks.
+
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/generators/role_fu/abilities_generator.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "rails/generators/active_record"
+
+module RoleFu
+  module Generators
+    class AbilitiesGenerator < ActiveRecord::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def generate_permission_model
+        template "permission.rb.erb", "app/models/permission.rb"
+      end
+
+      def create_migration
+        migration_template "abilities_migration.rb.erb", "db/migrate/role_fu_create_permissions.rb", migration_version: migration_version
+      end
+
+      def inject_into_role_model
+        role_cname = RoleFu.configuration.role_class_name
+        path = "app/models/#{role_cname.underscore}.rb"
+
+        if File.exist?(path)
+          inject_into_class(path, role_cname.constantize) do
+            "  has_many :permissions, dependent: :destroy\n"
+          end
+        else
+          say "Role model #{role_cname} not found. Please add 'has_many :permissions' manually."
+        end
+      end
+
+      def inject_into_user_model
+        user_cname = RoleFu.configuration.user_class_name
+        path = "app/models/#{user_cname.underscore}.rb"
+
+        if File.exist?(path)
+          inject_into_class(path, user_cname.constantize) do
+            "  include RoleFu::Ability\n"
+          end
+        else
+          say "User model #{user_cname} not found. Please add 'include RoleFu::Ability' manually."
+        end
+      end
+
+      private
+
+      def migration_version
+        "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]" if Rails::VERSION::MAJOR >= 5
+      end
+    end
+  end
+end

data/lib/generators/role_fu/audit_generator.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "rails/generators/active_record"
+
+module RoleFu
+  module Generators
+    class AuditGenerator < ActiveRecord::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def create_migration
+        migration_template "audit_migration.rb.erb", "db/migrate/role_fu_create_audits.rb", migration_version: migration_version
+      end
+
+      def create_model
+        template "audit_model.rb.erb", "app/models/role_assignment_audit.rb"
+      end
+
+      private
+
+      def migration_version
+        "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]" if Rails::VERSION::MAJOR >= 5
+      end
+    end
+  end
+end

data/lib/generators/role_fu/job_generator.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module RoleFu
+  module Generators
+    class JobGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def create_job
+        template "cleanup_job.rb.erb", "app/jobs/role_fu/cleanup_job.rb"
+      end
+    end
+  end
+end

data/lib/generators/role_fu/templates/abilities_migration.rb.erb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+class RoleFuCreatePermissions < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :permissions do |t|
+      t.references :role, null: false, index: true
+      t.string :action, null: false
+      t.jsonb :conditions, default: {}
+
+      t.timestamps
+    end
+    
+    add_index :permissions, [:role_id, :action]
+  end
+end

data/lib/generators/role_fu/templates/audit_migration.rb.erb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+class RoleFuCreateAudits < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :role_assignment_audits do |t|
+      t.references :user, index: true
+      t.references :role, index: true
+      t.references :role_assignment, index: true
+      t.string :operation, null: false # INSERT, UPDATE, DELETE
+      t.string :whodunnit
+      t.jsonb :meta_snapshot
+      t.datetime :expires_at_snapshot
+
+      t.timestamps
+    end
+    
+    # If using PostgreSQL, you can add a trigger here to automatically populate this table.
+    # Example (Conceptual):
+    # execute <<-SQL
+    #   CREATE TRIGGER ...
+    # SQL
+  end
+end

data/lib/generators/role_fu/templates/audit_model.rb.erb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class RoleAssignmentAudit < ApplicationRecord
+  belongs_to :user, optional: true
+  belongs_to :role, optional: true
+  belongs_to :role_assignment, optional: true
+end

data/lib/generators/role_fu/templates/cleanup_job.rb.erb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module RoleFu
+  class CleanupJob < ApplicationJob
+    queue_as :default
+
+    def perform
+      result = RoleFu::Cleanup.call
+      Rails.logger.info("RoleFu::CleanupJob: Deleted #{result[:deleted]} expired assignments.")
+    end
+  end
+end

data/lib/generators/role_fu/templates/migration.rb.erb

@@ -12,6 +12,8 @@ class RoleFuCreate<%= table_name.camelize %> < ActiveRecord::Migration<%= migrat
     create_table :<%= table_name.singularize %>_assignments do |t|
       t.references :<%= user_cname.underscore %>, index: true
       t.references :<%= table_name.singularize %>, index: true
+      t.datetime :expires_at, index: true
+      t.jsonb :meta, default: {}
 
       t.timestamps
     end

data/lib/generators/role_fu/templates/permission.rb.erb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class Permission < ApplicationRecord
+  include RoleFu::Permission
+end

data/lib/role_fu/ability.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module RoleFu
+  module Ability
+    extend ActiveSupport::Concern
+
+    def role_fu_can?(action, _resource = nil)
+      role_fu_permissions.include?(action.to_s)
+    end
+
+    def role_fu_permissions
+      return @_role_fu_permissions if defined?(@_role_fu_permissions) && @_role_fu_permissions
+
+      permission_class = "Permission".safe_constantize
+      return Set.new unless permission_class
+
+      scope = roles
+      scope = filter_expired(scope) if respond_to?(:filter_expired, true)
+
+      @_role_fu_permissions = scope.joins(:permissions).pluck("permissions.action").map(&:to_s).to_set
+    end
+  end
+end

data/lib/role_fu/adapters/cancancan.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module RoleFu
+  module Adapters
+    module CanCanCan
+      # Mixin for CanCan::Ability class
+      def role_fu_load_permissions!(user)
+        return unless user.respond_to?(:role_fu_permissions)
+
+        user.role_fu_permissions.each do |action|
+          # Action format: "posts.update" (resource.action) or "manage_all"
+          parts = action.split(".")
+
+          if parts.size == 2
+            subject_name, rule = parts
+            begin
+              subject_class = subject_name.classify.constantize
+              can rule.to_sym, subject_class
+            rescue NameError
+              can rule.to_sym, subject_name.to_sym
+            end
+          else
+            can action.to_sym, :all
+          end
+        end
+      end
+    end
+  end
+end

data/lib/role_fu/adapters/pundit.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module RoleFu
+  module Adapters
+    module Pundit
+      # Mixin for Pundit Policies (e.g. ApplicationPolicy)
+      def method_missing(method, *args, &block)
+        if method.to_s.end_with?("?")
+          action = method.to_s.delete_suffix("?")
+
+          # Infer resource from policy name: PostPolicy -> "posts"
+          resource_name = self.class.to_s.gsub("Policy", "").underscore.pluralize
+
+          # Check "posts.update"
+          permission = "#{resource_name}.#{action}"
+
+          return true if user.role_fu_can?(permission)
+        end
+
+        super
+      end
+
+      def respond_to_missing?(method, include_private = false)
+        method.to_s.end_with?("?") || super
+      end
+    end
+  end
+end

data/lib/role_fu/cleanup.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module RoleFu
+  class Cleanup
+    def self.call
+      assignment_class = RoleFu.configuration.role_assignment_class_name.constantize
+
+      if assignment_class.column_names.include?("expires_at")
+        count = assignment_class.where("expires_at < ?", Time.current).delete_all
+        {deleted: count}
+      else
+        {deleted: 0, error: "expires_at column missing"}
+      end
+    end
+  end
+end

data/lib/role_fu/configuration.rb

@@ -2,12 +2,13 @@
 
 module RoleFu
   class Configuration
-    attr_accessor :user_class_name, :role_class_name, :role_assignment_class_name
+    attr_accessor :user_class_name, :role_class_name, :role_assignment_class_name, :global_roles_override
 
     def initialize
       @user_class_name = "User"
       @role_class_name = "Role"
       @role_assignment_class_name = "RoleAssignment"
+      @global_roles_override = false
     end
   end
 

data/lib/role_fu/permission.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module RoleFu
+  module Permission
+    extend ActiveSupport::Concern
+
+    included do
+      belongs_to :role, class_name: RoleFu.configuration.role_class_name
+      validates :action, presence: true
+    end
+  end
+end

data/lib/role_fu/railtie.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module RoleFu
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      load "tasks/role_fu.rake"
+    end
+  end
+end

data/lib/role_fu/resourceable.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 module RoleFu
-  # Resourceable concern - provides resource management for models with roles
   module Resourceable
     extend ActiveSupport::Concern
 
@@ -13,144 +12,111 @@ module RoleFu
     end
 
     module ClassMethods
-      # Find roles defined on any instance of this resource class
-      # @param role_name [String, Symbol, nil] Filter by role name
-      # @param user [User, nil] Filter by user
-      # @return [ActiveRecord::Relation] Roles
       def find_roles(role_name = nil, user = nil)
-        RoleFu.role_class.table_name
         query = RoleFu.role_class.where(resource_type: name)
         query = query.where(name: role_name.to_s) if role_name
         query = query.joins(:users).where(RoleFu.user_class.table_name => {id: user.id}) if user
         query
       end
 
-      # Find resources that have a specific role applied (to a user)
-      # @param role_name [String, Symbol] The role name
-      # @param user [User, nil] Filter by specific user having the role
-      # @return [ActiveRecord::Relation] Resources
       def with_role(role_name, user = nil)
         role_table = RoleFu.role_class.table_name
-
         query = joins(:roles).where(role_table => {name: role_name.to_s})
-
-        if user
-          query = query.joins(roles: :users).where(RoleFu.user_class.table_name => {id: user.id})
-        end
-
+        query = query.joins(roles: :users).where(RoleFu.user_class.table_name => {id: user.id}) if user
         query.distinct
       end
 
-      # Find resources that do NOT have a specific role applied
-      # @param role_name [String, Symbol] The role name
-      # @param user [User, nil] Filter by user
-      # @return [ActiveRecord::Relation] Resources
       def without_role(role_name, user = nil)
         where.not(id: with_role(role_name, user).select(:id))
       end
+
+      # Dynamically create aliases for role methods
+      # @param name [Symbol, String] The alias name (e.g. :group)
+      def role_fu_alias(name)
+        singular = name.to_s.singularize
+        plural = name.to_s.pluralize
+
+        # Class methods
+        singleton_class.class_eval do
+          alias_method "find_#{plural}", :find_roles
+          alias_method "with_#{singular}", :with_role
+          alias_method "without_#{singular}", :without_role
+        end
+
+        # Instance methods
+        alias_method "users_with_#{singular}", :users_with_role
+        alias_method "users_with_any_#{singular}", :users_with_any_role
+        alias_method "users_with_all_#{plural}", :users_with_all_roles
+        alias_method "users_with_#{plural}", :users_with_roles
+        alias_method "available_#{plural}", :available_roles
+        alias_method "has_#{singular}?", :has_role?
+        alias_method "count_users_with_#{singular}", :count_users_with_role
+        alias_method "user_has_#{singular}?", :user_has_role?
+        alias_method "add_#{singular}_to_user", :add_role_to_user
+        alias_method "remove_#{singular}_from_user", :remove_role_from_user
+      end
     end
 
-    # Get roles applied to this resource instance (plus global class-level roles if any - though RoleFu focuses on instance roles)
-    # @return [ActiveRecord::Relation] Roles
     def applied_roles
       roles
     end
 
-    # Get users with a specific role on this resource
-    # @param role_name [String, Symbol] The role name
-    # @return [ActiveRecord::Relation] Relation of users
     def users_with_role(role_name)
       role_table = RoleFu.role_class.table_name
-      user_class.joins(:roles)
+      RoleFu.user_class.joins(:roles)
         .where(role_table => {name: role_name.to_s, resource_type: self.class.name, resource_id: id})
         .distinct
     end
 
-    # Get users with any role on this resource
-    # @param role_names [Array<String, Symbol>] Array of role names
-    # @return [ActiveRecord::Relation] Relation of users
     def users_with_any_role(*role_names)
       role_table = RoleFu.role_class.table_name
-      user_class.joins(:roles)
+      RoleFu.user_class.joins(:roles)
         .where(role_table => {name: role_names.flatten.map(&:to_s), resource_type: self.class.name, resource_id: id})
         .distinct
     end
 
-    # Get users with all specified roles on this resource
-    # @param role_names [Array<String, Symbol>] Array of role names
-    # @return [Array<User>] Array of users
     def users_with_all_roles(*role_names)
       role_names = role_names.flatten.map(&:to_s)
       role_table = RoleFu.role_class.table_name
+      user_table = RoleFu.user_class.table_name
+      user_pk = RoleFu.user_class.primary_key
 
-      user_class.joins(:roles)
+      RoleFu.user_class.joins(:roles)
         .where(role_table => {name: role_names, resource_type: self.class.name, resource_id: id})
-        .group("#{user_class.table_name}.#{user_class.primary_key}")
+        .group("#{user_table}.#{user_pk}")
         .having("COUNT(DISTINCT #{role_table}.name) = ?", role_names.size)
         .distinct
     end
 
-    # Get all users with any role on this resource
-    # @return [ActiveRecord::Relation] Relation of users
     def users_with_roles
       role_table = RoleFu.role_class.table_name
-      user_class.joins(:roles)
+      RoleFu.user_class.joins(:roles)
         .where(role_table => {resource_type: self.class.name, resource_id: id})
         .distinct
     end
 
-    # Get all role names defined for this resource
-    # @return [Array<String>] Array of role names
     def available_roles
       roles.pluck(:name).uniq
     end
 
-    # Check if resource has any users with a specific role
-    # @param role_name [String, Symbol] The role name
-    # @return [Boolean] true if any user has this role
     def has_role?(role_name)
       roles.exists?(name: role_name.to_s)
     end
 
-    # Count users with a specific role
-    # @param role_name [String, Symbol] The role name
-    # @return [Integer] Number of users
     def count_users_with_role(role_name)
       users_with_role(role_name).count
     end
 
-    # Check if a specific user has a role on this resource
-    # @param user [User] The user
-    # @param role_name [String, Symbol] The role name
-    # @return [Boolean] true if user has the role
     def user_has_role?(user, role_name)
-      return false if user.nil?
-
-      user.has_role?(role_name, self)
+      user&.has_role?(role_name, self) || false
     end
 
-    # Add a role to a user on this resource
-    # @param user [User] The user
-    # @param role_name [String, Symbol] The role name
-    # @return [Role] The role
     def add_role_to_user(user, role_name)
       user.add_role(role_name, self)
     end
 
-    # Remove a role from a user on this resource
-    # @param user [User] The user
-    # @param role_name [String, Symbol] The role name
-    # @return [Array<Role>] The removed roles
     def remove_role_from_user(user, role_name)
       user.remove_role(role_name, self)
     end
-
-    private
-
-    # Get the User class
-    # @return [Class] User class
-    def user_class
-      RoleFu.user_class
-    end
   end
 end

data/lib/role_fu/role_assignment.rb

@@ -12,11 +12,48 @@ module RoleFu
       scope :global_roles, -> { joins(:role).where(RoleFu.role_class.table_name => {resource_type: nil, resource_id: nil}) }
       scope :resource_specific, -> { joins(:role).where.not(RoleFu.role_class.table_name => {resource_type: nil}) }
 
+      after_create :audit_create
+      after_update :audit_update
+      after_destroy :audit_destroy
+
       after_destroy :cleanup_orphaned_role
     end
 
     private
 
+    def audit_create
+      audit_log("INSERT")
+    end
+
+    def audit_update
+      audit_log("UPDATE")
+    end
+
+    def audit_destroy
+      audit_log("DELETE")
+    end
+
+    def audit_log(operation)
+      # Only audit if the Audit model exists
+      audit_class = "RoleAssignmentAudit".safe_constantize
+      return unless audit_class
+
+      actor = RoleFu.current_actor
+
+      audit_class.create(
+        role_assignment_id: id,
+        user_id: user_id,
+        role_id: role_id,
+        operation: operation,
+        whodunnit: actor.try(:id) || actor.to_s,
+        meta_snapshot: try(:meta),
+        expires_at_snapshot: try(:expires_at)
+      )
+    rescue
+      # Fail silently or log error? Logging is safer to avoid breaking the main flow.
+      # defined?(Rails) ? Rails.logger.error("RoleFu Audit Error: #{e.message}") : puts("RoleFu Audit Error: #{e.message}")
+    end
+
     def cleanup_orphaned_role
       # If this record is being destroyed as part of role destruction,
       # do not try to destroy the same role again.

data/lib/role_fu/roleable.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 module RoleFu
-  # Roleable concern - provides role management for User model
   module Roleable
     extend ActiveSupport::Concern
 
@@ -21,16 +20,16 @@ module RoleFu
         self.role_fu_callbacks = options.slice(:before_add, :after_add, :before_remove, :after_remove)
       end
 
-      # Find users with a specific role
-      # @param role_name [String, Symbol] The name of the role
-      # @param resource [ActiveRecord::Base, Class, nil, :any] The resource
-      # @return [ActiveRecord::Relation] Users with the role
       def with_role(role_name, resource = nil)
         role_table = RoleFu.role_class.table_name
-        RoleFu.role_assignment_class.table_name
+        assignment_table = RoleFu.role_assignment_class.table_name
 
         query = joins(:roles).where(role_table => {name: role_name.to_s})
 
+        if RoleFu.role_assignment_class.column_names.include?("expires_at")
+          query = query.where("#{assignment_table}.expires_at IS NULL OR #{assignment_table}.expires_at > ?", Time.current)
+        end
+
         if resource.nil?
           query.where(role_table => {resource_type: nil, resource_id: nil})
         elsif resource == :any
@@ -42,75 +41,87 @@ module RoleFu
         end.distinct
       end
 
-      # Find users without a specific role
-      # @param role_name [String, Symbol] The name of the role
-      # @param resource [ActiveRecord::Base, Class, nil, :any] The resource
-      # @return [ActiveRecord::Relation] Users without the role
       def without_role(role_name, resource = nil)
         where.not(id: with_role(role_name, resource).select(:id))
       end
 
-      # Find users with any of the specified roles
-      # @param args [Array<String, Symbol, Hash>] Roles to check
-      # @return [ActiveRecord::Relation] Users with any of the roles
       def with_any_role(*args)
-        ids = []
-        args.each do |arg|
-          ids += if arg.is_a?(Hash)
-            with_role(arg[:name], arg[:resource]).pluck(:id)
-          else
-            with_role(arg).pluck(:id)
-          end
+        ids = args.flat_map do |arg|
+          arg.is_a?(Hash) ? with_role(arg[:name], arg[:resource]).pluck(:id) : with_role(arg).pluck(:id)
         end
         where(id: ids.uniq)
       end
 
-      # Find users with all of the specified roles
-      # @param args [Array<String, Symbol, Hash>] Roles to check
-      # @return [ActiveRecord::Relation] Users with all of the roles
       def with_all_roles(*args)
         ids = nil
         args.each do |arg|
-          current_ids = if arg.is_a?(Hash)
-            with_role(arg[:name], arg[:resource]).pluck(:id)
-          else
-            with_role(arg).pluck(:id)
-          end
+          current_ids = arg.is_a?(Hash) ? with_role(arg[:name], arg[:resource]).pluck(:id) : with_role(arg).pluck(:id)
           ids = ids.nil? ? current_ids : ids & current_ids
           return none if ids.empty?
         end
         where(id: ids)
       end
+
+      # Dynamically create aliases for role methods
+      # @param name [Symbol, String] The alias name (e.g. :group)
+      # @example
+      #   role_fu_alias :group
+      #   # Creates: add_group, remove_group, has_group?, with_group, in_group, etc.
+      def role_fu_alias(name)
+        singular = name.to_s.singularize
+        plural = name.to_s.pluralize
+
+        # Instance methods
+        alias_method "add_#{singular}", :add_role
+        alias_method "remove_#{singular}", :remove_role
+        alias_method "has_#{singular}?", :has_role?
+        alias_method "only_has_#{singular}?", :only_has_role?
+        alias_method "has_any_#{singular}?", :has_any_role?
+        alias_method "has_all_#{plural}?", :has_all_roles?
+        alias_method "#{plural}_name", :roles_name
+
+        # Class methods (Scopes)
+        singleton_class.class_eval do
+          alias_method "with_#{singular}", :with_role
+          alias_method "without_#{singular}", :without_role
+          alias_method "with_any_#{singular}", :with_any_role
+          alias_method "with_all_#{plural}", :with_all_roles
+
+          # Additional natural aliases
+          alias_method "in_#{singular}", :with_role
+          alias_method "not_in_#{singular}", :without_role
+        end
+      end
     end
 
-    # Add a role to the user
-    # @param role_name [String, Symbol] The name of the role
-    # @param resource [ActiveRecord::Base, Class, nil] The resource (organization, etc.) or nil for global role
-    # @return [Role] The role that was added
-    def add_role(role_name, resource = nil)
+    def add_role(role_name, resource = nil, expires_at: nil, meta: nil)
       role = find_or_create_role(role_name, resource)
-
-      return role if roles.include?(role)
+      existing_assignment = role_assignments.find_by(role: role)
+
+      if existing_assignment
+        if expires_at || meta
+          updates = {}
+          updates[:expires_at] = expires_at if expires_at
+          updates[:meta] = meta if meta
+          existing_assignment.update(updates)
+        end
+        return role
+      end
 
       run_role_fu_callback(:before_add, role)
-      roles << role
+      role_assignments.create!(role: role, expires_at: expires_at, meta: meta)
+      roles.reload
       run_role_fu_callback(:after_add, role)
 
       role
     end
     alias_method :grant, :add_role
 
-    # Remove a role from the user
-    # @param role_name [String, Symbol] The name of the role
-    # @param resource [ActiveRecord::Base, Class, nil] The resource or nil for global role
-    # @return [Array<Role>] The roles that were removed
     def remove_role(role_name, resource = nil)
       roles_to_remove_relation = find_roles(role_name, resource)
       return [] if roles_to_remove_relation.empty?
 
-      # Materialize before removing associations, because removing may trigger cleanup that deletes the role.
       removed_roles = roles_to_remove_relation.to_a
-
       removed_roles.each do |role|
         run_role_fu_callback(:before_remove, role)
         role_assignments.where(role_id: role.id).destroy_all
@@ -121,45 +132,38 @@ module RoleFu
     end
     alias_method :revoke, :remove_role
 
-    # Check if user has a specific role
-    # @param role_name [String, Symbol] The name of the role
-    # @param resource [ActiveRecord::Base, Class, nil, :any] The resource, nil for global, or :any for any resource
-    # @return [Boolean] true if user has the role
     def has_role?(role_name, resource = nil)
       return false if role_name.nil?
 
       if resource == :any
-        roles.exists?(name: role_name.to_s)
+        filter_expired(roles.where(name: role_name.to_s)).exists?
       else
-        find_roles(role_name, resource).any?
+        return true if filter_expired(find_roles(role_name, resource)).any?
+
+        if RoleFu.configuration.global_roles_override && resource && !resource.is_a?(Class)
+          return filter_expired(find_roles(role_name, nil)).any?
+        end
+
+        false
       end
     end
 
-    # Check if user has a specific role strictly (resource match must be exact, no globals overriding)
-    # Note: In RoleFu, has_role? is already strict about resource matching unless :any is passed,
-    # but this method explicitly bypasses any future global-fallback logic if we were to add it.
-    # Included for API compatibility.
-    # @param role_name [String, Symbol] The name of the role
-    # @param resource [ActiveRecord::Base, Class, nil] The resource
-    # @return [Boolean] true if user has the role strictly
     def has_strict_role?(role_name, resource = nil)
-      has_role?(role_name, resource)
+      filter_expired(find_roles(role_name, resource)).any?
     end
 
-    # Check if user only has this one role
-    # @param role_name [String, Symbol] The name of the role
-    # @param resource [ActiveRecord::Base, Class, nil] The resource
-    # @return [Boolean] true if user has this role and no others
     def only_has_role?(role_name, resource = nil)
-      has_role?(role_name, resource) && roles.count == 1
+      has_role?(role_name, resource) && filter_expired(roles).count == 1
     end
 
-    # Check for role using preloaded association to avoid N+1
     def has_cached_role?(role_name, resource = nil)
       role_name = role_name.to_s
       roles.to_a.any? do |role|
         next false unless role.name == role_name
 
+        assignment = role_assignments.find { |ra| ra.role_id == role.id }
+        next false if assignment&.respond_to?(:expires_at) && assignment.expires_at && assignment.expires_at <= Time.current
+
         if resource == :any
           true
         elsif resource.is_a?(Class)
@@ -172,80 +176,58 @@ module RoleFu
       end
     end
 
-    # Get all role names for this user
-    # @param resource [ActiveRecord::Base, Class, nil] Filter by resource
-    # @return [Array<String>] Array of role names
     def roles_name(resource = nil)
-      if resource
-        roles.where(resource: resource).pluck(:name)
-      else
-        roles.pluck(:name)
-      end
+      scope = resource ? roles.where(resource: resource) : roles
+      filter_expired(scope).pluck(:name)
     end
 
-    # Check if user has only global roles (no resource-specific roles)
-    # @return [Boolean] true if user has only global roles
     def has_only_global_roles?
-      roles.where.not(resource_type: nil).empty?
+      filter_expired(roles).where.not(resource_type: nil).empty?
     end
 
-    # Check if user has any role (global or resource-specific)
-    # @param resource [ActiveRecord::Base, Class, nil] Filter by resource
-    # @return [Boolean] true if user has any role
     def has_any_role?(resource = nil)
-      if resource
-        roles.exists?(resource: resource)
-      else
-        roles.exists?
-      end
+      scope = resource ? roles.where(resource: resource) : roles
+      filter_expired(scope).exists?
     end
 
-    # Check if user has all specified roles
-    # @param role_names [Array<String, Symbol>] Array of role names
-    # @param resource [ActiveRecord::Base, Class, nil] The resource
-    # @return [Boolean] true if user has all roles
     def has_all_roles?(*role_names, resource: nil)
       role_names.flatten.all? { |role_name| has_role?(role_name, resource) }
     end
 
-    # Check if user has any of the specified roles
-    # @param role_names [Array<String, Symbol>] Array of role names
-    # @param resource [ActiveRecord::Base, Class, nil] The resource
-    # @return [Boolean] true if user has any of the roles
     def has_any_role_of?(*role_names, resource: nil)
       role_names.flatten.any? { |role_name| has_role?(role_name, resource) }
     end
 
-    # Get all resources of a specific type where user has a role
-    # @param resource_class [Class] The resource class (e.g., Organization)
-    # @return [ActiveRecord::Relation] Relation of resources
     def resources(resource_class)
-      resource_class.joins(:roles)
-        .merge(roles.where(resource_type: resource_class.name))
-        .distinct
+      assignment_table = RoleFu.role_assignment_class.table_name
+      query = resource_class.joins(:roles).merge(roles.where(resource_type: resource_class.name))
+
+      if RoleFu.role_assignment_class.column_names.include?("expires_at")
+        query = query.where("#{assignment_table}.expires_at IS NULL OR #{assignment_table}.expires_at > ?", Time.current)
+      end
+
+      query.distinct
     end
 
     private
 
-    # Find or create a role
-    # @param role_name [String, Symbol] The role name
-    # @param resource [ActiveRecord::Base, Class, nil] The resource
-    # @return [Role] The found or created role
-    def find_or_create_role(role_name, resource)
-      resource_type = resource_type_for(resource)
-      resource_id = resource_id_for(resource)
+    def filter_expired(relation)
+      return relation unless RoleFu.role_assignment_class.column_names.include?("expires_at")
+
+      assignment_table = RoleFu.role_assignment_class.table_name
+      relation.joins(:role_assignments)
+        .where("#{assignment_table}.user_id = ? AND (#{assignment_table}.expires_at IS NULL OR #{assignment_table}.expires_at > ?)", id, Time.current)
+        .distinct
+    end
 
+    def find_or_create_role(role_name, resource)
       RoleFu.role_class.find_or_create_by(
         name: role_name.to_s,
-        resource_type: resource_type,
-        resource_id: resource_id
+        resource_type: resource_type_for(resource),
+        resource_id: resource_id_for(resource)
       )
     end
 
-    # Find roles matching criteria
-    # @param role_name [String, Symbol] The role name
-    # @param resource [ActiveRecord::Base, Class, nil] The resource
-    # @return [ActiveRecord::Relation] Relation of matching roles
     def find_roles(role_name, resource)
       query = roles.where(name: role_name.to_s)
 
@@ -258,20 +240,14 @@ module RoleFu
       end
     end
 
-    # Get resource type for a resource
-    # @param resource [ActiveRecord::Base, Class, nil] The resource
-    # @return [String, nil] The resource type
     def resource_type_for(resource)
-      return nil if resource.nil?
+      return if resource.nil?
 
       resource.is_a?(Class) ? resource.to_s : resource.class.name
     end
 
-    # Get resource id for a resource
-    # @param resource [ActiveRecord::Base, Class, nil] The resource
-    # @return [Integer, nil] The resource id
     def resource_id_for(resource)
-      return nil if resource.nil? || resource.is_a?(Class)
+      return if resource.nil? || resource.is_a?(Class)
 
       resource.id
     end
@@ -280,10 +256,8 @@ module RoleFu
       method_name = role_fu_callbacks[callback_name]
       return unless method_name
 
-      if method_name.is_a?(Proc)
-        instance_exec(role, &method_name)
-      elsif respond_to?(method_name, true)
-        send(method_name, role)
+      if respond_to?(method_name, true) || method_name.is_a?(Proc)
+        method_name.is_a?(Proc) ? instance_exec(role, &method_name) : send(method_name, role)
       end
     end
   end

data/lib/role_fu/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RoleFu
-  VERSION = "0.1.0"
-end
+  VERSION = "0.2.0"
+end

data/lib/role_fu.rb

@@ -9,8 +9,26 @@ require_relative "role_fu/role"
 require_relative "role_fu/role_assignment"
 require_relative "role_fu/roleable"
 require_relative "role_fu/resourceable"
+require_relative "role_fu/permission"
+require_relative "role_fu/ability"
+require_relative "role_fu/cleanup"
+require_relative "role_fu/adapters/cancancan"
+require_relative "role_fu/adapters/pundit"
+require_relative "role_fu/railtie" if defined?(Rails)
 
 module RoleFu
   class Error < StandardError; end
-  # Your code goes here...
+
+  class << self
+    def with_actor(actor)
+      Thread.current[:role_fu_actor] = actor
+      yield
+    ensure
+      Thread.current[:role_fu_actor] = nil
+    end
+
+    def current_actor
+      Thread.current[:role_fu_actor]
+    end
+  end
 end

data/lib/tasks/role_fu.rake

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+namespace :role_fu do
+  desc "Clean up expired role assignments"
+  task cleanup: :environment do
+    result = RoleFu::Cleanup.call
+    puts result[:error] || "Deleted #{result[:deleted]} expired role assignment(s)."
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: role_fu
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Alexey Poimtsev
@@ -132,19 +132,34 @@ files:
 - gemfiles/rails_8.1.gemfile
 - gemfiles/rails_8.1.gemfile.lock
 - lefthook.yml
+- lib/generators/role_fu/abilities_generator.rb
+- lib/generators/role_fu/audit_generator.rb
 - lib/generators/role_fu/install_generator.rb
+- lib/generators/role_fu/job_generator.rb
 - lib/generators/role_fu/role_fu_generator.rb
+- lib/generators/role_fu/templates/abilities_migration.rb.erb
+- lib/generators/role_fu/templates/audit_migration.rb.erb
+- lib/generators/role_fu/templates/audit_model.rb.erb
+- lib/generators/role_fu/templates/cleanup_job.rb.erb
 - lib/generators/role_fu/templates/migration.rb.erb
+- lib/generators/role_fu/templates/permission.rb.erb
 - lib/generators/role_fu/templates/role.rb.erb
 - lib/generators/role_fu/templates/role_assignment.rb.erb
 - lib/generators/role_fu/templates/role_fu.rb
 - lib/role_fu.rb
+- lib/role_fu/ability.rb
+- lib/role_fu/adapters/cancancan.rb
+- lib/role_fu/adapters/pundit.rb
+- lib/role_fu/cleanup.rb
 - lib/role_fu/configuration.rb
+- lib/role_fu/permission.rb
+- lib/role_fu/railtie.rb
 - lib/role_fu/resourceable.rb
 - lib/role_fu/role.rb
 - lib/role_fu/role_assignment.rb
 - lib/role_fu/roleable.rb
 - lib/role_fu/version.rb
+- lib/tasks/role_fu.rake
 - sig/role_fu.rbs
 homepage: https://github.com/alec-c4/role_fu
 licenses: