organizations 0.5.0 → 0.7.0

data/lib/organizations/models/membership.rb

@@ -32,6 +32,11 @@ module Organizations
     # see Organizations::MetadataFlags.
     extend Organizations::MetadataFlags
 
+    # grant!, revoke_grant!, grant_for, granted? (scoped resource grants)
+    include Organizations::GrantHolder
+    # limited_by_grants?, capabilities_for, can?, visible, granted_ids
+    include Organizations::GrantAccess
+
     # Error raised when trying to demote below current role
     class CannotDemoteOwner < Organizations::Error; end
     class CannotPromoteToOwner < Organizations::Error; end
@@ -51,9 +56,19 @@ module Organizations
                class_name: Organizations.user_class_name,
                optional: true
 
+    # Scoped resource grants (rails g organizations:grants). Removed with the
+    # membership: a member who leaves keeps no access. (No dependent:
+    # option, because the table is optional: see GrantHolder.)
+    has_many :grants, class_name: "Organizations::Grant", inverse_of: :membership
+    before_destroy :delete_grants
+
     # === Validations ===
 
-    validates :role, presence: true, inclusion: { in: ->(_) { Roles::HIERARCHY.map(&:to_s) } }
+    validates :role, presence: true
+    # Checked when the role is set or changed, so a role retired from the
+    # configuration does not block unrelated updates of existing memberships.
+    validates :role, inclusion: { in: ->(_) { Roles.valid_roles.map(&:to_s) } },
+                     if: -> { new_record? || will_save_change_to_role? }
     # Proc message: resolved at VALIDATION time so it follows I18n.locale —
     # a literal string here would be frozen in whatever locale loaded first.
     validates :user_id, uniqueness: { scope: :organization_id,
@@ -77,17 +92,17 @@ module Organizations
     # Memberships with viewer role
     scope :viewers, -> { where(role: "viewer") }
 
+    # Memberships with a grant on a resource
+    scope :with_grant_on, lambda { |resource|
+      where(id: Organizations::Grant.active.for_resource(resource).select(:membership_id))
+    }
+
     # Order by role hierarchy (owners first)
+    # (the configured hierarchy, custom roles included; unknown roles last)
     scope :by_role_hierarchy, -> {
-      order(Arel.sql(<<~SQL.squish))
-        CASE role
-          WHEN 'owner' THEN 0
-          WHEN 'admin' THEN 1
-          WHEN 'member' THEN 2
-          WHEN 'viewer' THEN 3
-          ELSE 4
-        END
-      SQL
+      roles = Roles.hierarchy # one snapshot for the ranks and the fallback
+      ranks = roles.each_with_index.map { |role, index| "WHEN #{connection.quote(role.to_s)} THEN #{index}" }
+      order(Arel.sql("CASE role #{ranks.join(' ')} ELSE #{roles.length} END"))
     }
 
     # === Verified Joining (v0.5.0) ===
@@ -166,25 +181,87 @@ module Organizations
       Roles.compare(role_sym, other.role_sym)
     end
 
+    # Check if this member may give another member the specified role, or
+    # take it away from them: only roles that rank at or below this member's
+    # own role qualify. Useful to filter the role picker in an admin UI.
+    # @param role [Symbol, String] The role to give or take away
+    # @return [Boolean]
+    #
+    # @example
+    #   admin_membership.can_assign_role?(:admin)  # => true
+    #   member_membership.can_assign_role?(:admin) # => false
+    #
+    def can_assign_role?(role)
+      Roles.can_assign?(role_sym, role)
+    end
+
     # === Role Change Methods ===
 
+    # Raise unless changed_by may move this member to new_role. A member who
+    # changes another member's role must rank at or above both the role being
+    # taken away and the role being given (see Roles.can_assign?), so a custom
+    # role that can edit member roles still cannot create or demote an admin.
+    # A changed_by who holds no membership in this organization, such as a
+    # console session or platform staff, is only recorded for the callbacks,
+    # as before; authorizing that account is the host's job. promote_to!,
+    # demote_to! and Organization#change_role_of! all call this.
+    # @param new_role [Symbol, String] The role being given
+    # @param changed_by [User, nil] Who is making the change
+    # @raise [Organizations::NotAuthorized] if either role ranks above changed_by's own
+    def authorize_role_change!(new_role, changed_by:)
+      self.class.authorize_rank!(organization, changed_by, [role_sym, new_role],
+                                 permission: :edit_member_roles,
+                                 message_key: :"errors.role_change_outranks_actor")
+    end
+
+    # @api private
+    # The one check behind every action on a role: inviting to it, changing a
+    # member to or from it, removing a member who holds it, and revoking or
+    # resending an invitation for it. An actor may only act on roles that
+    # rank at or below its own and, below admin, whose permissions it holds
+    # (see Roles.assignment_refusal). An actor that is nil or holds no
+    # membership in the organization is not checked: the gem records it for
+    # the callbacks and the host authorizes it.
+    # @param message_key [Symbol] The message for a role that ranks above the actor's own
+    # @raise [Organizations::NotAuthorized] naming the first role the actor may not act on
+    def self.authorize_rank!(organization, actor, roles, permission:, message_key:)
+      actor_membership = actor && organization.memberships.find_by(user_id: actor.id)
+      return unless actor_membership
+
+      roles.map(&:to_sym).each do |role|
+        refusal = Roles.assignment_refusal(actor_membership.role_sym, role)
+        next unless refusal
+
+        key = refusal == :outranks ? message_key : :"errors.role_has_permissions_actor_lacks"
+        raise Organizations::NotAuthorized.new(
+          Organizations.t(key, organization: organization,
+                               role: Organizations.t(:"roles.#{role}", organization: organization,
+                                                                       default: role.to_s.humanize)),
+          permission: permission,
+          organization: organization,
+          user: actor
+        )
+      end
+    end
+
     # Promote to a higher role
     # @param new_role [Symbol, String] The new role
     # @param changed_by [User, nil] Who is making the change
     # @return [self]
     # @raise [InvalidRoleChange] if new role is not higher
     # @raise [CannotPromoteToOwner] if trying to promote to owner (use transfer_ownership_to!)
+    # @raise [Organizations::NotAuthorized] if changed_by is a member whose role ranks below the new role
     def promote_to!(new_role, changed_by: nil)
       new_role_sym = new_role.to_sym
       validate_role!(new_role_sym)
 
       # Owner role is only assignable via transfer_ownership_to!
       if new_role_sym == :owner
-        raise CannotPromoteToOwner, Organizations.t(:"errors.cannot_promote_to_owner")
+        raise CannotPromoteToOwner, Organizations.t(:"errors.cannot_promote_to_owner", organization: organization)
       end
 
       unless Roles.at_least?(new_role_sym, role_sym)
-        raise InvalidRoleChange, Organizations.t(:"errors.promote_not_higher", new_role: new_role, role: role)
+        raise InvalidRoleChange, Organizations.t(:"errors.promote_not_higher", organization: organization, new_role: new_role, role: role)
       end
 
       change_role_to!(new_role_sym, changed_by: changed_by)
@@ -196,16 +273,17 @@ module Organizations
     # @return [self]
     # @raise [CannotDemoteOwner] if trying to demote owner
     # @raise [InvalidRoleChange] if new role is not lower
+    # @raise [Organizations::NotAuthorized] if changed_by is a member whose role ranks below the current role
     def demote_to!(new_role, changed_by: nil)
       new_role_sym = new_role.to_sym
       validate_role!(new_role_sym)
 
       if owner?
-        raise CannotDemoteOwner, Organizations.t(:"errors.cannot_demote_owner")
+        raise CannotDemoteOwner, Organizations.t(:"errors.cannot_demote_owner", organization: organization)
       end
 
       unless Roles.at_least?(role_sym, new_role_sym)
-        raise InvalidRoleChange, Organizations.t(:"errors.demote_not_lower", new_role: new_role, role: role)
+        raise InvalidRoleChange, Organizations.t(:"errors.demote_not_lower", organization: organization, new_role: new_role, role: role)
       end
 
       change_role_to!(new_role_sym, changed_by: changed_by)
@@ -221,7 +299,7 @@ module Organizations
 
       return unless existing_owner.exists?
 
-      errors.add(:role, Organizations.t(:"attributes.owner_taken"))
+      errors.add(:role, Organizations.t(:"attributes.owner_taken", organization: organization))
     end
 
     def validate_role!(role)
@@ -238,6 +316,9 @@ module Organizations
       ActiveRecord::Base.transaction do
         # Lock row to prevent concurrent changes
         lock!
+        # Checked on the locked, freshly read role, so a concurrent change
+        # cannot slip an admin past the check.
+        authorize_role_change!(new_role, changed_by: changed_by)
         update!(role: new_role.to_s)
       end