organizations 0.6.0 → 0.7.1

data/lib/organizations/models/grant.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Organizations
+  # Access to one resource of the host app, with a list of capabilities. A
+  # grant belongs to a membership, or to an invitation until it is accepted.
+  #
+  # Grants narrow a membership: a member whose role ranks below
+  # config.full_resource_access_role sees only the resources granted to it,
+  # and on each one only the granted capabilities that its role also has.
+  # See Organizations::GrantHolder and Membership#can?.
+  #
+  # The resource is polymorphic (grantable_type, grantable_id). It can be
+  # an ActiveRecord record (`grant.grantable` loads it) or any object with an
+  # id, such as an Organizations::Resource (then only the type and id are
+  # stored, and `grantable` is not used).
+  class Grant < ActiveRecord::Base
+    self.table_name = "organizations_grants"
+
+    # === Associations ===
+
+    belongs_to :membership, class_name: "Organizations::Membership", inverse_of: :grants, optional: true
+    belongs_to :invitation, class_name: "Organizations::Invitation", inverse_of: :grants, optional: true
+    belongs_to :grantable, polymorphic: true, optional: true
+    belongs_to :granted_by, class_name: Organizations.user_class_name, optional: true
+
+    # === Validations ===
+
+    validates :grantable_type, :grantable_id, presence: true
+    validate :one_holder
+    validate :capabilities_listed
+
+    # === Callbacks ===
+
+    before_validation :normalize_capabilities
+
+    # === Scopes ===
+
+    # Grants on one resource (a record, any object with an id, or a Resource)
+    scope :for_resource, lambda { |resource|
+      type, id = Grant.resource_key(resource)
+      where(grantable_type: type, grantable_id: id)
+    }
+
+    # Grants on resources of one type (a class or a type name)
+    scope :of_type, ->(type) { where(grantable_type: Grant.type_name(type)) }
+
+    # Grants held by memberships (accepted), not by pending invitations
+    scope :active, -> { where.not(membership_id: nil) }
+
+    # [type, id] for a resource. The id must fit the grantable_id column
+    # without loss ("42-a" never becomes 42).
+    # @param resource [ActiveRecord::Base, Organizations::Resource, #id]
+    # @return [Array(String, Object)]
+    # @raise [ArgumentError] for an object without an id, or an id that does not fit
+    def self.resource_key(resource)
+      type, id =
+        case resource
+        when Organizations::Resource then [resource.type.to_s, resource.id]
+        when ActiveRecord::Base then [resource.class.polymorphic_name, resource.id]
+        else
+          raise ArgumentError, "A grant needs a resource with an id, got #{resource.inspect}" unless resource.respond_to?(:id)
+
+          [resource.class.name, resource.id]
+        end
+      [type, lossless_id(id)]
+    end
+
+    # @api private
+    # The id as the grantable_id column stores it, or ArgumentError when the
+    # column would change it.
+    def self.lossless_id(id)
+      cast = type_for_attribute("grantable_id").cast(id)
+      return cast if cast.to_s == id.to_s
+
+      raise ArgumentError, "The id #{id.inspect} does not fit the grantable_id column (#{columns_hash['grantable_id']&.type})"
+    end
+
+    # @api private
+    # The organization a resource belongs to, or nil when it does not say:
+    # an object with organization_id, or an Organizations::Resource naming
+    # an ActiveRecord model with an organization_id column (one query).
+    def self.resource_organization_id(resource)
+      if resource.is_a?(Organizations::Resource)
+        model = resource.type.to_s.safe_constantize
+        return nil unless tenant_model?(model)
+
+        model.where(model.primary_key => resource.id).pick(:organization_id)
+      elsif resource.respond_to?(:organization_id)
+        resource.organization_id.presence
+      end
+    end
+
+    # The stored type name for a class or a name.
+    # @return [String]
+    def self.type_name(type)
+      type.respond_to?(:polymorphic_name) ? type.polymorphic_name : type.to_s
+    end
+
+    # @api private
+    def self.tenant_model?(model)
+      model.is_a?(Class) && model < ActiveRecord::Base && model.column_names.include?("organization_id")
+    end
+
+    # @return [Array<String>]
+    def capabilities
+      Array(super).map(&:to_s)
+    end
+
+    # @param capability [Symbol, String]
+    # @return [Boolean] whether this grant lists the capability
+    def allows?(capability)
+      capabilities.include?(capability.to_s)
+    end
+
+    # The resource as an Organizations::Resource (no loading).
+    # @return [Organizations::Resource]
+    def resource
+      Organizations::Resource.new(grantable_type, grantable_id)
+    end
+
+    private
+
+    def normalize_capabilities
+      self.capabilities = Array(read_attribute(:capabilities)).map { |c| c.to_s.strip }.compact_blank.uniq
+    end
+
+    def one_holder
+      return if membership_id.present? ^ invitation_id.present?
+
+      errors.add(:base, Organizations.t(:"attributes.grant_one_holder"))
+    end
+
+    def capabilities_listed
+      if capabilities.empty?
+        errors.add(:capabilities, Organizations.t(:"attributes.grant_capabilities_blank"))
+        return
+      end
+
+      allowed = Organizations.configuration.grant_capabilities
+      return if allowed.nil?
+
+      unknown = capabilities - allowed.map(&:to_s)
+      return if unknown.empty?
+
+      errors.add(:capabilities,
+                 Organizations.t(:"attributes.grant_capabilities_unknown", capabilities: unknown.join(", ")))
+    end
+  end
+end
+
+# Host extension seam — see the load-hooks note in models/organization.rb.
+ActiveSupport.run_load_hooks(:organizations_grant, Organizations::Grant)

data/lib/organizations/models/invitation.rb

@@ -20,6 +20,10 @@ module Organizations
   class Invitation < ActiveRecord::Base
     self.table_name = "organizations_invitations"
 
+    # grant!, revoke_grant!, grant_for, granted?: grants the membership gets
+    # when this invitation is accepted
+    include Organizations::GrantHolder
+
     # === Associations ===
 
     belongs_to :organization,
@@ -34,6 +38,11 @@ module Organizations
     # Alias for invited_by (semantic convenience as per README)
     alias_method :from, :invited_by
 
+    # Grants that move to the membership on acceptance (scoped resource
+    # grants). No dependent: option, because the table is optional.
+    has_many :grants, class_name: "Organizations::Grant", inverse_of: :invitation
+    before_destroy :delete_grants
+
     # === Validations ===
 
     validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
@@ -133,7 +142,7 @@ module Organizations
       # Validate email matches at model level (security)
       unless skip_email_validation
         if accepting_user.respond_to?(:email) && !for_email?(accepting_user.email)
-          raise EmailMismatch, Organizations.t(:"errors.invitation_email_mismatch")
+          raise EmailMismatch, Organizations.t(:"errors.invitation_email_mismatch", organization: organization)
         end
       end
 
@@ -150,27 +159,29 @@ module Organizations
           existing_membership = organization.memberships.find_by(user_id: accepting_user.id)
           return existing_membership if existing_membership
 
-          raise InvitationAlreadyAccepted, Organizations.t(:"errors.invitation_already_accepted")
+          raise InvitationAlreadyAccepted, Organizations.t(:"errors.invitation_already_accepted", organization: organization)
         end
 
         if expired?
-          raise InvitationExpired, Organizations.t(:"errors.invitation_expired")
+          raise InvitationExpired, Organizations.t(:"errors.invitation_expired", organization: organization)
         end
 
         # Owner role cannot be assigned via invitation (defense in depth)
         if role.to_sym == :owner
-          raise CannotAcceptAsOwner, Organizations.t(:"errors.invitation_accept_as_owner")
+          raise CannotAcceptAsOwner, Organizations.t(:"errors.invitation_accept_as_owner", organization: organization)
         end
 
         # Check if user is already a member (race condition from another invitation)
         existing_membership = organization.memberships.find_by(user_id: accepting_user.id)
         if existing_membership
+          move_grants_to!(existing_membership)
           update!(accepted_at: Time.current)
           return existing_membership
         end
 
         # Create the membership (with verified-joining provenance)
         membership = create_membership_for!(accepting_user, skip_email_validation)
+        move_grants_to!(membership)
 
         # Mark invitation as accepted
         update!(accepted_at: Time.current)
@@ -188,15 +199,21 @@ module Organizations
 
     # Resend the invitation email
     # Generates new token and resets expiry
+    # @param resent_by [User, nil] Who is resending it. When that account is a
+    #   member, the invitation's role must rank at or below its own role.
     # @return [self]
-    def resend!
+    # @raise [InvitationAlreadyAccepted] if already accepted
+    # @raise [Organizations::NotAuthorized] if the role ranks above resent_by's own
+    def resend!(resent_by: nil)
       ActiveRecord::Base.transaction do
         lock!
 
         if accepted?
-          raise InvitationAlreadyAccepted, Organizations.t(:"errors.invitation_cannot_resend_accepted")
+          raise InvitationAlreadyAccepted, Organizations.t(:"errors.invitation_cannot_resend_accepted", organization: organization)
         end
 
+        authorize_management!(resent_by)
+
         update!(
           token: generate_unique_token,
           expires_at: calculate_expiry
@@ -207,6 +224,19 @@ module Organizations
       self
     end
 
+    # Revoke (delete) the invitation, so its link stops working
+    # @param revoked_by [User, nil] Who is revoking it. When that account is a
+    #   member, the invitation's role must rank at or below its own role.
+    # @return [self]
+    # @raise [Organizations::NotAuthorized] if the role ranks above revoked_by's own
+    def revoke!(revoked_by: nil)
+      ActiveRecord::Base.transaction do
+        lock!
+        authorize_management!(revoked_by)
+        destroy!
+      end
+    end
+
     # Get the acceptance URL
     # @param base_url [String, nil] Base URL for the link
     # @return [String]
@@ -227,6 +257,36 @@ module Organizations
 
     private
 
+    # The invitation's grants become the membership's (a grant on the same
+    # resource takes the invitation's capabilities). The inviter was
+    # checked when the invitation was sent.
+    # Grants are written only while the invitation is pending, under its
+    # row lock (accept! takes the same lock).
+    def lock_for_grant_write!
+      return unless persisted?
+
+      lock!
+      raise InvitationAlreadyAccepted, Organizations.t(:"errors.invitation_already_accepted", organization: organization) if accepted?
+    end
+
+    # Each grant is checked again, against the inviter as it is now and the
+    # membership that receives it (an existing member may hold a higher
+    # role than the invitation): a grant the inviter may no longer give, or
+    # whose capabilities config.grant_capabilities no longer allows, is
+    # dropped and logged. (Deleting the inviter deletes the grants of the
+    # invitations they sent, so a nil inviter here is a trusted actor.)
+    def move_grants_to!(membership)
+      return unless Organizations::GrantHolder.grants_table?
+
+      grants.each do |grant|
+        membership.authorize_grants!([[grant.resource, grant.capabilities]], invited_by)
+        membership.send(:upsert_grant!, grant.grantable_type, grant.grantable_id, grant.capabilities, invited_by)
+      rescue Organizations::NotAuthorized, ArgumentError, ActiveRecord::RecordInvalid => e
+        Callbacks.log_warn("[Organizations] Invitation grant on #{grant.grantable_type}##{grant.grantable_id} dropped: #{e.message}")
+      end
+      grants.delete_all(:delete_all)
+    end
+
     # Create the membership for an acceptance.
     # Uses invited_by_id instead of invited_by to avoid Rails class reloading
     # issues (AssociationTypeMismatch when User is reloaded in development).
@@ -315,6 +375,15 @@ module Organizations
       }
     end
 
+    # A member may only revoke or resend invitations for roles that rank at or
+    # below its own, so a custom role that can invite members still cannot
+    # manage an admin's invitation (see Membership.authorize_rank!).
+    def authorize_management!(actor)
+      Membership.authorize_rank!(organization, actor, [role],
+                                 permission: :invite_members,
+                                 message_key: :"errors.invitation_management_outranks_actor")
+    end
+
     def normalize_email
       self.email = email.to_s.downcase.strip if email.present?
     end
@@ -352,7 +421,7 @@ module Organizations
                            .exists?
 
       if existing
-        errors.add(:email, Organizations.t(:"attributes.invitation_taken"))
+        errors.add(:email, Organizations.t(:"attributes.invitation_taken", organization: organization))
       end
     end
 

data/lib/organizations/models/join_request.rb

@@ -31,7 +31,7 @@ module Organizations
   # The class carries the request's FULL lifecycle (statuses, challenge,
   # decisions) exactly like its mirror Invitation does — splitting it would
   # scatter one cohesive state machine across files.
-  # rubocop:disable Metrics/ClassLength
+  # rubocop:disable-next Metrics/ClassLength
   class JoinRequest < ActiveRecord::Base
     self.table_name = "organizations_join_requests"
 
@@ -146,7 +146,7 @@ module Organizations
       address = email.to_s.strip
 
       unless address.match?(URI::MailTo::EMAIL_REGEXP)
-        raise VerificationEmailNotEligible, Organizations.t(:"errors.verification_email_invalid")
+        raise VerificationEmailNotEligible, Organizations.t(:"errors.verification_email_invalid", organization: organization)
       end
 
       code = nil
@@ -183,6 +183,9 @@ module Organizations
         lock!
         ensure_open!
         ensure_active_challenge!
+        # The domain or roster entry may have been removed, revoked or
+        # blocked since the code was sent: the code then proves nothing.
+        ensure_instruments_still_eligible!
 
         if correct_code?(code)
           # Burn the code: single-use by construction.
@@ -192,13 +195,15 @@ module Organizations
           # raising here would roll the increment back and give attackers
           # unlimited tries.
           update!(verification_attempts: verification_attempts + 1)
-          failure = VerificationCodeInvalid.new(Organizations.t(:"errors.verification_code_invalid"))
+          failure = VerificationCodeInvalid.new(
+            Organizations.t(:"errors.verification_code_invalid", organization: organization)
+          )
         end
       end
 
       raise failure if failure
 
-      return approve!(decided_by: nil) if auto_approvable_after_verification?
+      return send(:auto_approve!) if auto_approvable_after_verification?
 
       self
     end
@@ -218,32 +223,22 @@ module Organizations
     # @return [Membership]
     # @raise [JoinRequestExpired, JoinRequestAlreadyDecided]
     def approve!(decided_by: nil)
-      membership = nil
-      reused_existing = false
-
-      ActiveRecord::Base.transaction do
-        lock!
-
-        return approved_membership! if approved? # idempotent re-approval
-
-        ensure_open!
-
-        existing = existing_membership
-
-        if existing
-          membership = existing
-          reused_existing = true
-        else
-          membership = create_membership!
-          claim_matched_allowlist_entry!
-        end
-
-        update!(status: "approved", decided_by_id: decided_by&.id, decided_at: Time.current)
-      end
+      perform_approval!(decided_by: decided_by, recheck_instruments: false)
+    end
 
-      dispatch_approval_callbacks(membership, decided_by, reused_existing)
-      membership
+    # The automatic approval behind a verified email (verify_email_code! and
+    # Organization#join_with_account_email!). Like approve!, but it needs a
+    # verified email and a matched domain or roster entry, and checks again,
+    # under row locks, that the instrument still admits members. A manual
+    # approve! by an admin does not need that check: the admin decides.
+    # @return [Membership]
+    # @raise [VerificationEmailNotEligible] when the instrument is gone, revoked or blocked
+    def auto_approve!
+      perform_approval!(decided_by: nil, recheck_instruments: true)
     end
+    # Callable from Organization#join_with_account_email! only. Hosts call
+    # approve! (a decision) or verify_email_code! (a proof).
+    private :auto_approve!
 
     # Reject this request.
     # @param rejected_by [User, nil]
@@ -324,9 +319,72 @@ module Organizations
 
     private
 
+    def perform_approval!(decided_by:, recheck_instruments:)
+      membership = nil
+      reused_existing = false
+
+      ActiveRecord::Base.transaction do
+        lock!
+
+        return approved_membership! if approved? # idempotent re-approval
+
+        ensure_open!
+        ensure_instruments_still_eligible!(require_proof: true) if recheck_instruments
+
+        existing = existing_membership
+
+        if existing
+          membership = existing
+          reused_existing = true
+        else
+          membership = create_membership!
+          claim_matched_allowlist_entry!
+        end
+
+        update!(status: "approved", decided_by_id: decided_by&.id, decided_at: Time.current)
+      end
+
+      dispatch_approval_callbacks(membership, decided_by, reused_existing)
+      membership
+    end
+
+    # The domain (or allowlist entry) that made the verification email
+    # eligible must still admit: present, matching the email, joinable
+    # (Domain.joinable), and for an entry, unclaimed by anyone else. The row
+    # is locked until the admission commits, so a revocation or removal
+    # either finishes first (and refuses) or waits.
+    #
+    # Called at the challenge check (verify_email_code!) before the proof
+    # exists, and again by auto_approve! after it, which also needs it.
+    def ensure_instruments_still_eligible!(require_proof: false)
+      return if verification_email.blank? && !require_proof
+      return if instruments_still_eligible?(require_proof)
+
+      raise VerificationEmailNotEligible, Organizations.t(:"errors.verification_email_not_eligible", organization: organization)
+    end
+
+    def instruments_still_eligible?(require_proof)
+      return false if require_proof && (!email_verified? || verification_email.blank?)
+
+      domain_id = (metadata || {})["matched_domain_id"]
+      entry_id = (metadata || {})["matched_allowlist_entry_id"]
+      return !require_proof unless domain_id || entry_id
+
+      matched_instrument_scope(domain_id, entry_id).lock.pick(:id).present?
+    end
+
+    def matched_instrument_scope(domain_id, entry_id)
+      if domain_id
+        organization.domains.joinable.matching_email(verification_email).where(id: domain_id)
+      else
+        organization.allowlist_entries.for_email(verification_email).where(id: entry_id)
+          .where("claimed_at IS NULL OR claimed_by_id = ?", user_id)
+      end
+    end
+
     # Raise unless this request is still open (pending and not expired)
     def ensure_open!
-      raise JoinRequestExpired, Organizations.t(:"errors.join_request_expired") if expired?
+      raise JoinRequestExpired, Organizations.t(:"errors.join_request_expired", organization: organization) if expired?
       raise JoinRequestAlreadyDecided, already_decided_message if decided?
     end
 
@@ -340,8 +398,10 @@ module Organizations
     # (organizations.join_request_status.*, lowercase for mid-sentence use)
     # so the whole sentence localizes as one unit.
     def already_decided_message
-      Organizations.t(:"errors.join_request_already_decided",
-                      status: Organizations.t(:"join_request_status.#{status}", default: status))
+      Organizations.t(:"errors.join_request_already_decided", organization: organization,
+                                                              status: Organizations.t(:"join_request_status.#{status}",
+                                                                                      organization: organization,
+                                                                                      default: status))
     end
 
     def auto_approvable_after_verification?
@@ -358,7 +418,7 @@ module Organizations
     # Raises if it was removed after approval — the request can't be reused.
     def approved_membership!
       membership = existing_membership
-      raise JoinRequestAlreadyDecided, Organizations.t(:"errors.join_request_membership_gone") unless membership
+      raise JoinRequestAlreadyDecided, Organizations.t(:"errors.join_request_membership_gone", organization: organization) unless membership
 
       membership
     end
@@ -392,11 +452,11 @@ module Organizations
     # Domains win over allowlist entries (an org can have both).
     # @return [Array(Domain|nil, AllowlistEntry|nil)]
     def eligible_instruments_for!(address)
-      matched_domain = organization.domains.matching_email(address).first
+      matched_domain = organization.domains.joinable.matching_email(address).first
       matched_entry = matched_domain ? nil : organization.allowlist_entries.unclaimed.for_email(address).first
 
       unless matched_domain || matched_entry
-        raise VerificationEmailNotEligible, Organizations.t(:"errors.verification_email_not_eligible")
+        raise VerificationEmailNotEligible, Organizations.t(:"errors.verification_email_not_eligible", organization: organization)
       end
 
       [matched_domain, matched_entry]
@@ -409,34 +469,34 @@ module Organizations
       return unless Membership.where(organization_id: organization_id, verified_email_normalized: normalized).exists?
 
       raise VerificationEmailAlreadyClaimed,
-            Organizations.t(:"errors.verification_email_already_claimed")
+            Organizations.t(:"errors.verification_email_already_claimed", organization: organization)
     end
 
     def ensure_send_allowed!
       config = Organizations.configuration
 
       if verification_sends_count >= config.verification_max_sends
-        raise VerificationThrottled, Organizations.t(:"errors.verification_sends_exceeded")
+        raise VerificationThrottled, Organizations.t(:"errors.verification_sends_exceeded", organization: organization)
       end
 
       resend_floor = interval_ago(config.verification_resend_interval)
       return unless verification_sent_at.present? && verification_sent_at > resend_floor
 
-      raise VerificationThrottled, Organizations.t(:"errors.verification_resend_throttled")
+      raise VerificationThrottled, Organizations.t(:"errors.verification_resend_throttled", organization: organization)
     end
 
     def ensure_active_challenge!
       config = Organizations.configuration
 
-      raise VerificationCodeInvalid, Organizations.t(:"errors.verification_code_missing") if verification_code_digest.blank?
+      raise VerificationCodeInvalid, Organizations.t(:"errors.verification_code_missing", organization: organization) if verification_code_digest.blank?
 
       if verification_attempts >= config.verification_max_attempts
-        raise VerificationAttemptsExceeded, Organizations.t(:"errors.verification_attempts_exceeded")
+        raise VerificationAttemptsExceeded, Organizations.t(:"errors.verification_attempts_exceeded", organization: organization)
       end
 
       return unless verification_expires_at.blank? || verification_expires_at <= Time.current
 
-      raise VerificationCodeExpired, Organizations.t(:"errors.verification_code_expired")
+      raise VerificationCodeExpired, Organizations.t(:"errors.verification_code_expired", organization: organization)
     end
 
     def correct_code?(code)
@@ -487,7 +547,7 @@ module Organizations
       return existing if existing
 
       raise VerificationEmailAlreadyClaimed,
-            Organizations.t(:"errors.verification_email_already_claimed")
+            Organizations.t(:"errors.verification_email_already_claimed", organization: organization)
     end
 
     def insert_membership_row!(effective_joined_via)
@@ -617,10 +677,9 @@ module Organizations
         .where.not(id: id)
         .exists?
 
-      errors.add(:user_id, Organizations.t(:"attributes.pending_request_taken")) if existing
+      errors.add(:user_id, Organizations.t(:"attributes.pending_request_taken", organization: organization)) if existing
     end
   end
-  # rubocop:enable Metrics/ClassLength
 end
 
 # Host extension seam — see the load-hooks note in models/organization.rb.