rhino-rails 4.2.1 → 4.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c15dd271d0b613f2effa9bb7c8d050b3214c74884e3021461150017f0f159af6
-  data.tar.gz: 5b4e5dcb736acc54674ad24e9d689cd93582e7ba0195554ef99e7735f2c33050
+  metadata.gz: 0155b30eedf93061b38295ed96254194529de0abf03aad309becc312a512c5ba
+  data.tar.gz: 5e1ce1624bab2a77f8603ebdf6984a43e4bd71d277f51900ae533465e4fd0881
 SHA512:
-  metadata.gz: 93c2de702533d23edcfe6b334aa0ffaf0f327efe6518a8c608e8072b4fe27862430d6591a651e730f198f9e9e8cf39456005464490a12137dadce641613ef268
-  data.tar.gz: 7fe767badf982f99dd3fca7b72c441929ee0eb336b72b117ed4a5296cdcaafacda6582a338025e6e611f1a0e87117d6d906469c8b01abc9339109d9da32c711a
+  metadata.gz: 975f1ee3efc83423ae775131eace5689a7b09269541848da21e286f2f55cedd71b265a8e3c5c448a85cc7b9c8ecdde2e27dd615ef1a26719732a7d958cbfb8da
+  data.tar.gz: 3a32ccaf04ad8f351828752a83efac31503d53afbd4c3239d0f38e836c8e151dd4681f2a650a853e9d6d728e6477f34e72023680c6bbd36dc63369ad6ca6d10c

data/README.md

@@ -40,6 +40,7 @@ Register a model, get a full REST API instantly.
 | 26 | **Generator CLI** | `rhino:install`, `rhino:generate`, `rhino:blueprint`, `rhino:export_postman`. |
 | 27 | **Postman Export** | Auto-generated Postman Collection v2.1 with all endpoints. |
 | 28 | **Blueprint System** | YAML-to-code generation for models, migrations, factories, policies, tests, and seeders. |
+| 29 | **Named Scopes** | `?scope=availableForDrivers` client-selectable scopes (whitelisted via `rhino_scopes`), plus a `rhino_default_scope` applied when none is requested. Unknown scopes return 403. Applies to `index`/`trashed` only. |
 
 ## Quick Start
 

data/lib/rhino/commands/install_command.rb

@@ -109,7 +109,8 @@ module Rhino
           "create_users" => "#{timestamp}00",
           "create_organizations" => "#{timestamp}01",
           "create_roles" => "#{timestamp}02",
-          "create_user_roles" => "#{timestamp}03"
+          "create_user_roles" => "#{timestamp}03",
+          "create_org_role_permissions" => "#{timestamp}04"
         }.each do |name, ts|
           template = File.join(templates_dir, "#{name}.rb.erb")
           next unless File.exist?(template)
@@ -125,7 +126,7 @@ module Rhino
 
         templates_dir = File.expand_path("../../templates/multi_tenant/models", __FILE__)
 
-        %w[user organization role user_role].each do |model|
+        %w[user organization role user_role org_role_permission].each do |model|
           template = File.join(templates_dir, "#{model}.rb.erb")
           next unless File.exist?(template)
 

data/lib/rhino/concerns/has_permissions.rb

@@ -12,21 +12,36 @@ module Rhino
   #   end
   #
   # Permission format: '{slug}.{action}' (e.g., 'posts.index', 'blogs.store')
-  # Wildcard support:
-  #   - '*' grants access to everything
-  #   - 'posts.*' grants access to all actions on posts
+  # Wildcard support on every layer:
+  #   - '*' grants/denies everything
+  #   - 'posts.*' grants/denies all actions on posts
   #
-  # Two permission sources:
-  #   - users.permissions: used for non-tenant route groups (no organization context).
-  #     Stored as a JSON array directly on the user model.
-  #   - role.permissions (via user_roles): used for tenant route groups (organization context present).
-  #     Resolved per-organization via the user_roles → role association.
+  # ── Layered resolution (organization context) ────────────────────────────
+  # The effective decision for an org-scoped check is:
   #
-  # Resolution:
-  #   1. When an organization is provided (tenant route group) → checks role.permissions
-  #      for that specific organization via user_roles.
-  #   2. When no organization is provided (non-tenant route group) → checks users.permissions
-  #      directly on the user model.
+  #     effective = (role ∪ granted) − denied        (deny always wins)
+  #
+  #   - role    → org_role_permissions[(organization, role)].permissions
+  #               The shared "role layer" an org manages once per role.
+  #   - granted → user_roles.granted_permissions  (per-user additive delta)
+  #   - denied  → user_roles.denied_permissions   (per-user subtractive delta)
+  #   - legacy  → user_roles.permissions          (kept in the allow set)
+  #
+  # Deny is checked first and overrides everything — even a role '*'. This is
+  # intentionally deny-overrides (not most-specific-wins).
+  #
+  # Backward compatibility:
+  #   - The global roles.permissions column is preserved as a FALLBACK: it is
+  #     consulted only when the primary union (legacy ∪ granted ∪ org role layer)
+  #     is empty — exactly the pre-layer "fall back to role.permissions when
+  #     user_role.permissions is empty" behavior.
+  #   - When org_role_permissions has no row and the granted/denied columns are
+  #     absent, resolution reduces to the previous behavior byte-for-byte.
+  #
+  # Sources:
+  #   1. organization provided (tenant route group) → user_roles layers above.
+  #   2. no organization (non-tenant route group)   → users.permissions (with
+  #      optional user-level granted/denied if those columns exist; deny wins).
   module HasPermissions
     extend ActiveSupport::Concern
 
@@ -34,54 +49,58 @@ module Rhino
     #
     # @param permission [String] Permission string like 'posts.index'
     # @param organization [Object, nil] Organization to check permissions for
+    # @param route_group [String, nil] Resolved route group (group enforcement only)
     # @return [Boolean]
     def has_permission?(permission, organization = nil, route_group: nil)
       return false if permission.blank?
 
       # Group-aware permission resolution (GROUP_AUTH_DESIGN.md §6). Only active
       # when enforce_group_membership is on. Permissions then resolve from the
-      # membership row matching (route_group, organization), not the heuristic.
+      # membership row matching (route_group, organization).
       if group_membership_enforced?
         membership = Rhino::GroupMembership.matching_membership(self, route_group, organization)
-        return false unless membership
+        return decide_for_record(permission, membership, organization)
+      end
 
-        ur_permissions = parse_permissions(membership.respond_to?(:permissions) ? membership.permissions : nil)
-        return matches_permission?(permission, ur_permissions) if ur_permissions.present?
+      if organization
+        # Tenant route group: layered resolution from the user_role for this org.
+        return decide_for_record(permission, find_user_role(organization), organization)
+      end
 
-        role = membership.respond_to?(:role) ? membership.role : nil
-        if role
-          role_permissions = parse_permissions(role.respond_to?(:permissions) ? role.permissions : nil)
-          return matches_permission?(permission, role_permissions) if role_permissions.present?
-        end
+      # Non-tenant route group: users.permissions (+ optional user-level deltas).
+      deny = parse_permissions(safe_attr(self, :denied_permissions))
+      return false if matches_permission?(permission, deny)
+
+      allow = parse_permissions(safe_attr(self, :permissions)) +
+              parse_permissions(safe_attr(self, :granted_permissions))
+      matches_permission?(permission, allow)
+    end
+
+    # Explain a permission decision — returns the deciding layer.
+    #
+    # @return [Hash] { granted: Boolean, reason: String }
+    #   reason ∈ { 'denied', 'role', 'granted', 'legacy', 'user', 'default-deny' }
+    def explain_permission(permission, organization = nil, route_group: nil)
+      return { granted: false, reason: "default-deny" } if permission.blank?
 
-        return false
+      if group_membership_enforced?
+        membership = Rhino::GroupMembership.matching_membership(self, route_group, organization)
+        return decide_for_record(permission, membership, organization, explain: true)
       end
 
       if organization
-        # Tenant route group: check permissions for this organization
-        user_role = find_user_role(organization)
-
-        if user_role
-          # Check user_role.permissions first (per-user-org permissions on the pivot)
-          ur_permissions = parse_permissions(user_role.respond_to?(:permissions) ? user_role.permissions : nil)
-          if ur_permissions.present?
-            return matches_permission?(permission, ur_permissions)
-          end
-
-          # Fallback to role.permissions (shared role-level permissions)
-          role = user_role.respond_to?(:role) ? user_role.role : nil
-          if role
-            role_permissions = parse_permissions(role.respond_to?(:permissions) ? role.permissions : nil)
-            return matches_permission?(permission, role_permissions) if role_permissions.present?
-          end
-        end
-
-        return false
+        return decide_for_record(permission, find_user_role(organization), organization, explain: true)
       end
 
-      # Non-tenant route group: check users.permissions directly
-      user_perms = parse_permissions(respond_to?(:permissions) ? self.permissions : nil)
-      matches_permission?(permission, user_perms)
+      deny = parse_permissions(safe_attr(self, :denied_permissions))
+      return { granted: false, reason: "denied" } if matches_permission?(permission, deny)
+
+      user = parse_permissions(safe_attr(self, :permissions))
+      granted = parse_permissions(safe_attr(self, :granted_permissions))
+      return { granted: true, reason: "granted" } if matches_permission?(permission, granted)
+      return { granted: true, reason: "user" } if matches_permission?(permission, user)
+
+      { granted: false, reason: "default-deny" }
     end
 
     # Get the role slug for validation purposes.
@@ -100,7 +119,77 @@ module Rhino
 
     private
 
+    # Resolve a decision from a single membership/user_role record, applying
+    # deny-overrides over the layered allow set.
+    def decide_for_record(permission, record, organization, explain: false)
+      return explain ? { granted: false, reason: "default-deny" } : false unless record
+
+      # Deny always wins.
+      deny = parse_permissions(safe_attr(record, :denied_permissions))
+      if matches_permission?(permission, deny)
+        return explain ? { granted: false, reason: "denied" } : false
+      end
+
+      role_id = record.respond_to?(:role_id) ? record.role_id : nil
+      role_layer = org_role_permissions(organization, role_id)
+      granted = parse_permissions(safe_attr(record, :granted_permissions))
+      legacy = parse_permissions(safe_attr(record, :permissions))
+
+      primary = legacy + granted + role_layer
+
+      if primary.present?
+        unless explain
+          return matches_permission?(permission, primary)
+        end
+
+        return { granted: true, reason: "role" } if matches_permission?(permission, role_layer)
+        return { granted: true, reason: "granted" } if matches_permission?(permission, granted)
+        return { granted: true, reason: "legacy" } if matches_permission?(permission, legacy)
+        return { granted: false, reason: "default-deny" }
+      end
+
+      # Legacy fallback: the global roles.permissions column, consulted only when
+      # the primary union is empty (preserving pre-layer behavior).
+      role = record.respond_to?(:role) ? record.role : nil
+      global = role ? parse_permissions(safe_attr(role, :permissions)) : []
+      allowed = matches_permission?(permission, global)
+
+      return { granted: allowed, reason: allowed ? "role" : "default-deny" } if explain
+
+      allowed
+    end
+
+    # Resolve the shared role-layer permissions for (organization, role) from the
+    # org_role_permissions table. Memoized per instance; tolerant of the table not
+    # existing (un-migrated apps) so it degrades to "no role layer".
+    def org_role_permissions(organization, role_id)
+      return [] unless organization && role_id
+
+      org_id = organization.respond_to?(:id) ? organization.id : organization
+      return [] if org_id.nil?
+
+      @_org_role_permissions_cache ||= {}
+      key = "#{org_id}:#{role_id}"
+      return @_org_role_permissions_cache[key] if @_org_role_permissions_cache.key?(key)
+
+      perms =
+        begin
+          sql = ActiveRecord::Base.sanitize_sql_array(
+            ["SELECT permissions FROM org_role_permissions WHERE organization_id = ? AND role_id = ? LIMIT 1",
+             org_id, role_id]
+          )
+          row = ActiveRecord::Base.connection.select_one(sql)
+          row ? parse_permissions(row["permissions"]) : []
+        rescue ActiveRecord::ActiveRecordError
+          # Table absent (app has not run the new migration) → no role layer.
+          []
+        end
+
+      @_org_role_permissions_cache[key] = perms
+    end
+
     def matches_permission?(permission, granted_permissions)
+      return false if permission.blank?
       return true if granted_permissions.include?(permission)
       return true if granted_permissions.include?("*")
 
@@ -115,7 +204,8 @@ module Rhino
 
       if perms.is_a?(String)
         begin
-          JSON.parse(perms)
+          parsed = JSON.parse(perms)
+          parsed.is_a?(Array) ? parsed : []
         rescue JSON::ParserError
           []
         end
@@ -126,6 +216,12 @@ module Rhino
       end
     end
 
+    def safe_attr(obj, name)
+      return nil unless obj.respond_to?(name)
+
+      obj.public_send(name)
+    end
+
     def find_user_role(organization)
       return nil unless respond_to?(:user_roles)
       return nil unless organization

data/lib/rhino/concerns/has_rhino.rb

@@ -13,6 +13,8 @@ module Rhino
   #     rhino_includes :user, :comments
   #     rhino_fields :id, :title, :status, :created_at
   #     rhino_search :title, :content, 'user.name'
+  #     rhino_scopes :active, available_for_drivers: Scopes::AvailableForDriversScope
+  #     rhino_default_scope :active
   #     rhino_per_page 25
   #     rhino_pagination_enabled true
   #     rhino_middleware 'throttle:60,1'
@@ -24,6 +26,8 @@ module Rhino
 
     included do
       class_attribute :allowed_filters, default: []
+      class_attribute :allowed_scopes, default: {}
+      class_attribute :default_rhino_scope, default: nil
       class_attribute :allowed_sorts, default: []
       class_attribute :default_sort_field, default: nil
       class_attribute :allowed_includes, default: []
@@ -42,6 +46,23 @@ module Rhino
         self.allowed_filters = fields.map(&:to_s)
       end
 
+      # Whitelist client-selectable named scopes for ?scope=.
+      #   rhino_scopes :active, available_for_drivers: Scopes::AvailableForDriversScope
+      # Bare symbols must name an existing ActiveRecord scope/class method on the model.
+      # Hash values may be a Proc(relation, user) or a Rhino::ResourceScope subclass.
+      def rhino_scopes(*names, **named)
+        merged = allowed_scopes.dup
+        names.each { |n| merged[n.to_s] = n.to_sym }
+        named.each { |k, v| merged[k.to_s] = v }
+        self.allowed_scopes = merged
+      end
+
+      # Named scope applied when no ?scope param is sent. Convenience, not a
+      # security boundary. Value is the scope name (string/symbol).
+      def rhino_default_scope(name)
+        self.default_rhino_scope = name.to_s
+      end
+
       def rhino_sorts(*fields)
         self.allowed_sorts = fields.map(&:to_s)
       end

data/lib/rhino/controllers/resources_controller.rb

@@ -16,6 +16,10 @@ module Rhino
       render json: { message: "This action is unauthorized." }, status: :forbidden
     end
 
+    rescue_from Rhino::ScopeNotAllowedError do |e|
+      render json: { message: "Scope '#{e.message}' is not allowed" }, status: :forbidden
+    end
+
     # Cache for auto-detected organization paths (class-level, survives across requests)
     @@organization_path_cache = {}
 
@@ -38,7 +42,7 @@ module Rhino
     def index
       authorize model_class, :index?, policy_class: policy_for(model_class)
 
-      builder = QueryBuilder.new(model_class, params: params)
+      builder = QueryBuilder.new(model_class, params: params, named_scopes: true)
       apply_organization_scope(builder)
       builder.build
 
@@ -170,7 +174,7 @@ module Rhino
     def trashed
       authorize model_class, :view_trashed?, policy_class: policy_for(model_class)
 
-      builder = QueryBuilder.new(model_class.discarded, params: params)
+      builder = QueryBuilder.new(model_class.discarded, params: params, named_scopes: true)
       apply_organization_scope(builder)
       builder.build
 
@@ -900,7 +904,7 @@ module Rhino
     end
 
     def params_hash
-      params.except(:controller, :action, :model_slug, :route_group, :organization, :id, :format).to_unsafe_h
+      params.except(:controller, :action, :model_slug, :route_group, :organization, :id, :format, :scope).to_unsafe_h
     end
   end
 end

data/lib/rhino/models/rhino_model.rb

@@ -104,6 +104,36 @@ module Rhino
     #     self.allowed_filters = %w[status user_id category_id]
     self.allowed_filters = []
 
+    # @!attribute [rw] allowed_scopes
+    #   Client-selectable named scopes (whitelist for +?scope=+).
+    #
+    #   Controls which named scopes can be requested via +?scope=name+
+    #   (camelCase on the wire, underscored internally). Only whitelisted
+    #   scopes are accepted — unknown/unlisted names return 403.
+    #
+    #   Set via DSL: +rhino_scopes :active, available_for_drivers: Scopes::AvailableForDriversScope+
+    #
+    #   Query: +GET /api/posts?scope=availableForDrivers+
+    #
+    #   @return [Hash{String => Symbol, Proc, Class}]
+    #   @example
+    #     rhino_scopes :active, available_for_drivers: Scopes::AvailableForDriversScope
+    self.allowed_scopes = {}
+
+    # @!attribute [rw] default_rhino_scope
+    #   Named scope applied automatically when no +?scope+ param is sent.
+    #
+    #   This is a listing convenience, not a security boundary. The default
+    #   scope is always requestable by name even if it is not otherwise
+    #   whitelisted via +rhino_scopes+.
+    #
+    #   Set via DSL: +rhino_default_scope :active+
+    #
+    #   @return [String, nil]
+    #   @example
+    #     rhino_default_scope :active
+    self.default_rhino_scope = nil
+
     # @!attribute [rw] allowed_sorts
     #   Sortable columns.
     #

data/lib/rhino/permissions_migrator.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Rhino
+  # Lift per-user permissions into the shared org role layer.
+  #
+  # For each (organization, role) group, the literal intersection of every user's
+  # `user_roles.permissions` becomes the `org_role_permissions` row (the shared
+  # role layer). Each user's row is then reduced to only its delta
+  # (`granted_permissions = permissions − roleLayer`) and its legacy `permissions`
+  # is cleared. Effective permissions are preserved exactly (the intersection is a
+  # subset of every user's set, so nothing is gained or lost).
+  #
+  # Safe & idempotent:
+  #   - Dry-run by default; pass apply: true to write.
+  #   - Groups that already have an org_role_permissions row are skipped.
+  #   - After a run the legacy permissions are empty, so a second run is a no-op.
+  #   - Non-tenant (NULL organization) rows are left untouched.
+  class PermissionsMigrator
+    Result = Struct.new(:groups_migrated, :rows_reduced, :skipped_existing, :lines, keyword_init: true)
+
+    def self.call(apply: false)
+      new.call(apply: apply)
+    end
+
+    def call(apply: false)
+      conn = ActiveRecord::Base.connection
+      unless conn.data_source_exists?("user_roles") && conn.data_source_exists?("org_role_permissions")
+        raise "Required tables (user_roles, org_role_permissions) are missing. Run migrations first."
+      end
+
+      groups = conn.select_all(
+        "SELECT DISTINCT organization_id, role_id FROM user_roles " \
+        "WHERE organization_id IS NOT NULL AND role_id IS NOT NULL"
+      )
+
+      groups_migrated = 0
+      rows_reduced = 0
+      skipped_existing = 0
+      lines = []
+
+      groups.each do |g|
+        org_id = g["organization_id"]
+        role_id = g["role_id"]
+
+        rows = conn.select_all(
+          ActiveRecord::Base.sanitize_sql_array(
+            ["SELECT id, permissions, granted_permissions FROM user_roles " \
+             "WHERE organization_id = ? AND role_id = ?", org_id, role_id]
+          )
+        ).to_a
+
+        with_legacy = rows.select { |r| decode(r["permissions"]).any? }
+        next if with_legacy.empty?
+
+        existing = conn.select_value(
+          ActiveRecord::Base.sanitize_sql_array(
+            ["SELECT 1 FROM org_role_permissions WHERE organization_id = ? AND role_id = ? LIMIT 1",
+             org_id, role_id]
+          )
+        )
+        if existing
+          skipped_existing += 1
+          next
+        end
+
+        sets = with_legacy.map { |r| decode(r["permissions"]) }
+        role_layer = sets.reduce { |acc, s| acc & s } || []
+        lines << "org=#{org_id} role=#{role_id} → role layer [#{role_layer.join(', ')}] (#{with_legacy.size} user rows)"
+
+        if apply
+          now = Time.now.utc
+          conn.execute(
+            ActiveRecord::Base.sanitize_sql_array(
+              ["INSERT INTO org_role_permissions (organization_id, role_id, permissions, created_at, updated_at) " \
+               "VALUES (?, ?, ?, ?, ?)", org_id, role_id, JSON.generate(role_layer), now, now]
+            )
+          )
+
+          with_legacy.each do |r|
+            legacy = decode(r["permissions"])
+            grants = decode(r["granted_permissions"])
+            delta = ((legacy - role_layer) + grants).uniq
+
+            conn.execute(
+              ActiveRecord::Base.sanitize_sql_array(
+                ["UPDATE user_roles SET permissions = ?, granted_permissions = ?, updated_at = ? WHERE id = ?",
+                 JSON.generate([]), JSON.generate(delta), now, r["id"]]
+              )
+            )
+          end
+        end
+
+        groups_migrated += 1
+        rows_reduced += with_legacy.size
+      end
+
+      Result.new(
+        groups_migrated: groups_migrated,
+        rows_reduced: rows_reduced,
+        skipped_existing: skipped_existing,
+        lines: lines
+      )
+    end
+
+    private
+
+    def decode(value)
+      return value.select { |v| v.is_a?(String) } if value.is_a?(Array)
+
+      if value.is_a?(String) && !value.empty?
+        parsed = begin
+          JSON.parse(value)
+        rescue JSON::ParserError
+          []
+        end
+        return parsed.is_a?(Array) ? parsed.select { |v| v.is_a?(String) } : []
+      end
+
+      []
+    end
+  end
+end

data/lib/rhino/query_builder.rb

@@ -14,14 +14,16 @@ module Rhino
   class QueryBuilder
     attr_reader :scope, :model_class, :params
 
-    def initialize(model_class, params: {})
+    def initialize(model_class, params: {}, named_scopes: false)
       @model_class = model_class
       @scope = model_class.all
       @params = params
+      @named_scopes = named_scopes
     end
 
     # Apply all query modifications based on params and model config.
     def build
+      apply_named_scope if @named_scopes
       apply_filters
       apply_default_sort
       apply_sorts
@@ -62,6 +64,41 @@ module Rhino
 
     private
 
+    # ------------------------------------------------------------------
+    # Named scopes: ?scope=availableForDrivers
+    # ------------------------------------------------------------------
+    #
+    # Only runs for collection endpoints (index/trashed), which pass
+    # +named_scopes: true+. `show` (including its ?include= build path) stays
+    # unscoped so a record excluded by the default scope is still viewable.
+    def apply_named_scope
+      requested = params[:scope].presence
+      name = requested ? requested.to_s.underscore : model_class.try(:default_rhino_scope)
+      return unless name
+
+      allowed = model_class.try(:allowed_scopes) || {}
+      entry = allowed[name]
+      # The default scope is implicitly allowed when requested by name.
+      entry ||= name.to_sym if name == model_class.try(:default_rhino_scope)
+
+      # Echo the client's wire name (not the underscored form) in the error.
+      raise Rhino::ScopeNotAllowedError, (requested ? requested.to_s : name) if entry.nil?
+
+      user = defined?(RequestStore) ? RequestStore.store[:rhino_current_user] : nil
+
+      @scope =
+        case entry
+        when Symbol
+          # Whitelisted AR scope. Client input never reaches public_send unless the
+          # developer declared it via rhino_scopes. .merge composes with default_scopes.
+          @scope.merge(model_class.public_send(entry))
+        when Proc
+          entry.call(@scope, user)
+        else
+          entry.new.apply(@scope) # Rhino::ResourceScope subclass (user/org/role helpers)
+        end
+    end
+
     # ------------------------------------------------------------------
     # Filtering: ?filter[status]=published&filter[user_id]=1
     # ------------------------------------------------------------------

data/lib/rhino/scope_not_allowed_error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Rhino
+  # Raised when a client requests a ?scope= name that is not whitelisted via
+  # rhino_scopes / rhino_default_scope. Rendered as 403 by ResourcesController.
+  class ScopeNotAllowedError < StandardError; end
+end

data/lib/rhino/tasks/rhino.rake

@@ -26,6 +26,19 @@ namespace :rhino do
     cmd.perform
   end
 
+  desc "Lift per-user permissions into the org_role_permissions role layer (APPLY=1 to write)"
+  task :permissions_migrate, [:apply] => :environment do |_t, args|
+    require "rhino/permissions_migrator"
+    apply = args[:apply].to_s == "apply" || ENV["APPLY"] == "1"
+    result = Rhino::PermissionsMigrator.call(apply: apply)
+    result.lines.each { |line| puts line }
+    verb = apply ? "Migrated" : "Would migrate"
+    summary = "#{verb} #{result.groups_migrated} (org, role) group(s); #{result.rows_reduced} user row(s) reduced to deltas."
+    summary += " Skipped #{result.skipped_existing} group(s) with an existing role layer." if result.skipped_existing.positive?
+    puts summary
+    puts "Dry-run only. Re-run with APPLY=1 to write these changes." if !apply && result.groups_migrated.positive?
+  end
+
   desc "Generate TypeScript type definitions from registered Rhino models"
   task :export_types, [:output] => :environment do |_t, args|
     require "rhino/commands/export_types_command"

data/lib/rhino/templates/multi_tenant/migrations/create_org_role_permissions.rb.erb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+class CreateOrgRolePermissions < ActiveRecord::Migration[8.0]
+  # The shared "role layer": the permission set a role has within a given
+  # organization. Defining permissions here (once per org+role) means user_roles
+  # rows only need to carry per-user deltas (granted_permissions /
+  # denied_permissions) instead of the full permission set.
+  def change
+    create_table :org_role_permissions do |t|
+      t.references :organization, null: false, foreign_key: true
+      t.references :role, null: false, foreign_key: true
+      t.json :permissions, default: []
+
+      t.timestamps
+    end
+
+    # One row per (organization, role).
+    add_index :org_role_permissions, %i[organization_id role_id], unique: true,
+              name: "index_org_role_permissions_on_org_role"
+  end
+end

data/lib/rhino/templates/multi_tenant/migrations/create_user_roles.rb.erb

@@ -11,7 +11,14 @@ class CreateUserRoles < ActiveRecord::Migration[8.0]
       # Group membership scope. NULL = wildcard (member of every group), which
       # keeps existing rows valid when enforce_group_membership is enabled.
       t.string :route_group
+      # Legacy per-user permission set (full list). Still honored as an allow
+      # layer for backward compatibility.
       t.json :permissions, default: []
+      # Layered-permission deltas applied on top of the org role layer
+      # (org_role_permissions). granted = additive, denied = subtractive.
+      # Deny always wins. Leave empty to inherit the role layer as-is.
+      t.json :granted_permissions, default: []
+      t.json :denied_permissions, default: []
 
       t.timestamps
     end

data/lib/rhino/templates/multi_tenant/models/org_role_permission.rb.erb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# The shared "role layer" for permissions: what a role can do within a given
+# organization. One row per (organization, role).
+#
+# Resolution (see Rhino::HasPermissions):
+#   effective = (org_role_permissions ∪ user_roles.granted_permissions)
+#               − user_roles.denied_permissions     (deny always wins)
+class OrgRolePermission < ApplicationRecord
+  belongs_to :organization
+  belongs_to :role
+
+  validates :role_id, uniqueness: { scope: :organization_id }
+end

data/lib/rhino/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rhino
-  VERSION = "4.2.1"
+  VERSION = "4.4.0"
 end

data/lib/rhino.rb

@@ -3,6 +3,7 @@
 require "rhino/version"
 require "rhino/configuration"
 require "rhino/auth_rejected"
+require "rhino/scope_not_allowed_error"
 require "rhino/auth_hooks"
 require "rhino/group_membership"
 require "rhino/resource_scope"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rhino-rails
 version: !ruby/object:Gem::Version
-  version: 4.2.1
+  version: 4.4.0
 platform: ruby
 authors:
 - Bruno Cipolla
@@ -226,6 +226,7 @@ files:
 - lib/rhino/models/audit_log.rb
 - lib/rhino/models/organization_invitation.rb
 - lib/rhino/models/rhino_model.rb
+- lib/rhino/permissions_migrator.rb
 - lib/rhino/policies/invitation_policy.rb
 - lib/rhino/policies/resource_policy.rb
 - lib/rhino/query_builder.rb
@@ -234,6 +235,7 @@ files:
 - lib/rhino/routes.rb
 - lib/rhino/routing/domain_constraint.rb
 - lib/rhino/routing/route_group_validator.rb
+- lib/rhino/scope_not_allowed_error.rb
 - lib/rhino/tasks/rhino.rake
 - lib/rhino/templates/audit_trail/create_audit_logs.rb.erb
 - lib/rhino/templates/generate/factory.rb.erb
@@ -246,10 +248,12 @@ files:
 - lib/rhino/templates/multi_tenant/factories/user_roles.rb.erb
 - lib/rhino/templates/multi_tenant/factories/users.rb.erb
 - lib/rhino/templates/multi_tenant/migrations/add_group_membership.rb.erb
+- lib/rhino/templates/multi_tenant/migrations/create_org_role_permissions.rb.erb
 - lib/rhino/templates/multi_tenant/migrations/create_organizations.rb.erb
 - lib/rhino/templates/multi_tenant/migrations/create_roles.rb.erb
 - lib/rhino/templates/multi_tenant/migrations/create_user_roles.rb.erb
 - lib/rhino/templates/multi_tenant/migrations/create_users.rb.erb
+- lib/rhino/templates/multi_tenant/models/org_role_permission.rb.erb
 - lib/rhino/templates/multi_tenant/models/organization.rb.erb
 - lib/rhino/templates/multi_tenant/models/role.rb.erb
 - lib/rhino/templates/multi_tenant/models/user.rb.erb