rhino-rails 4.2.1 → 4.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c15dd271d0b613f2effa9bb7c8d050b3214c74884e3021461150017f0f159af6
-  data.tar.gz: 5b4e5dcb736acc54674ad24e9d689cd93582e7ba0195554ef99e7735f2c33050
+  metadata.gz: 43ae824cbc25eeacd6ce09fc6a9d5b218206d8877fc672a49b728dd6fbf10b1c
+  data.tar.gz: 6590704092005ad3b6c0b959b0166332387b2503d8db19e57fc17be7734c2d0b
 SHA512:
-  metadata.gz: 93c2de702533d23edcfe6b334aa0ffaf0f327efe6518a8c608e8072b4fe27862430d6591a651e730f198f9e9e8cf39456005464490a12137dadce641613ef268
-  data.tar.gz: 7fe767badf982f99dd3fca7b72c441929ee0eb336b72b117ed4a5296cdcaafacda6582a338025e6e611f1a0e87117d6d906469c8b01abc9339109d9da32c711a
+  metadata.gz: a8007c1c7f90ceae1cb0aed88ca032009e417f0e8052897f5ed73e514d9f3c782c6304f92f9b16002179d6492f5510d7ef3a3e00f5902094a925c2dd74c3b781
+  data.tar.gz: a58f92293f66ad18700a9ec39bf48e0696f64c72b7ac82c64fde715775821a5f00c3b90ce8e61dbf76b4edf4973eb520bc04b075e04ffb16c84fe7253c350e74

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/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/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.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rhino-rails
 version: !ruby/object:Gem::Version
-  version: 4.2.1
+  version: 4.3.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
@@ -246,10 +247,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