organizations 0.6.0 → 0.7.1

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,6 +56,12 @@ 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
@@ -81,6 +92,11 @@ 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, -> {
@@ -165,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)
@@ -195,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)
@@ -220,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)
@@ -237,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
 

data/lib/organizations/models/organization.rb

@@ -31,6 +31,7 @@ module Organizations
     class CannotInviteAsOwner < Organizations::Error; end
     class NoOwnerPresent < Organizations::Error; end
     class MemberAlreadyExists < Organizations::Error; end
+    class CannotTransferPersonalOrganization < Organizations::Error; end
 
     # === Associations ===
 
@@ -42,6 +43,10 @@ module Organizations
     has_many :users,
              through: :memberships
 
+    # Every grant of every membership (scoped resource grants). Grants held
+    # by pending invitations are not included: see invitation.grants.
+    has_many :grants, through: :memberships
+
     has_many :invitations,
              class_name: "Organizations::Invitation",
              inverse_of: :organization,
@@ -73,9 +78,19 @@ module Organizations
              inverse_of: :organization,
              dependent: :destroy
 
+    # === Personal organizations (v0.7.0) ===
+
+    # The user whose personal workspace this is (nil for every other
+    # organization). Set by user.create_personal_organization!, never guessed.
+    # The column is added by `rails g organizations:upgrade`.
+    belongs_to :personal_owner,
+               class_name: Organizations.user_class_name,
+               optional: true
+
     # === Validations ===
 
     validates :name, presence: true
+    validate :personal_owner_holds_ownership, on: :update, if: :personal_owner_changed_to_someone?
 
     # === Scopes ===
 
@@ -87,6 +102,12 @@ module Organizations
       joins(:memberships).where(organizations_memberships: { user_id: user.id })
     }
 
+    # Personal organizations (each one linked to the user it belongs to)
+    scope :personal, -> { where.not(personal_owner_id: nil) }
+
+    # Every organization that is not a personal organization
+    scope :not_personal, -> { where(personal_owner_id: nil) }
+
     # === Creation ===
 
     # Create an organization WITH its owner membership in one transaction —
@@ -114,6 +135,8 @@ module Organizations
     def self.create_with_owner!(owner:, **attributes)
       raise ArgumentError, "owner is required" unless owner
 
+      ensure_personal_owner_is_owner!(attributes, owner)
+
       organization = nil
       ActiveRecord::Base.transaction do
         organization = create!(**attributes)
@@ -125,6 +148,51 @@ module Organizations
       organization
     end
 
+    # @api private (public only because HasOrganizations#create_organization! calls it)
+    # A new organization may be personal only for the user who becomes its
+    # owner in the same transaction (user.create_organization!,
+    # create_with_owner!). Raw Organization.create! writes stay privileged.
+    # @raise [ArgumentError]
+    def self.ensure_personal_owner_is_owner!(attributes, owner)
+      attributes = attributes.to_h.symbolize_keys
+      personal_owner_id =
+        attributes.key?(:personal_owner) ? attributes[:personal_owner]&.id : attributes[:personal_owner_id]
+      return if personal_owner_id.nil? || personal_owner_id.to_s == owner.id.to_s
+
+      raise ArgumentError, "personal_owner must be the owner of the new organization"
+    end
+
+    # Link reviewed users to the organizations that are their personal
+    # organizations, for installs that created personal workspaces before
+    # 0.7.0. Nothing is guessed: pass the mapping you reviewed. A pair
+    # conflicts when the organization is missing, the user is not its owner,
+    # the organization is linked to another user, the user already has another
+    # personal organization, or one organization is mapped twice. When any
+    # pair conflicts, nothing is written.
+    #
+    # @param mapping [Hash{User, id => Organization, id}]
+    # @param dry_run [Boolean] report only, write nothing
+    # @return [Organizations::PersonalOwnerBackfill::Report]
+    def self.backfill_personal_owners!(mapping, dry_run: false)
+      PersonalOwnerBackfill.new(mapping).run(dry_run: dry_run)
+    end
+
+    # === Personal organizations ===
+
+    # Whether this is a user's personal organization
+    # @return [Boolean]
+    def personal?
+      has_attribute?(:personal_owner_id) && personal_owner_id.present?
+    end
+
+    # Stop treating this organization as the owner's personal organization.
+    # Do this before you transfer its ownership. Members, roles and data stay.
+    # @return [self]
+    def convert_to_shared!
+      update!(personal_owner_id: nil)
+      self
+    end
+
     # === Member Query Methods ===
 
     # Get the owner of this organization
@@ -196,7 +264,7 @@ module Organizations
 
       # Owner role is only assignable via transfer_ownership_to! or initial creation
       if role_sym == :owner
-        raise CannotHaveMultipleOwners, Organizations.t(:"errors.cannot_add_as_owner")
+        raise CannotHaveMultipleOwners, Organizations.t(:"errors.cannot_add_as_owner", organization: self)
       end
 
       # Check if already a member (idempotent operation)
@@ -260,17 +328,33 @@ module Organizations
     # @param user [User] The user to remove
     # @param removed_by [User, nil] Who is removing them (for callbacks)
     # @raise [CannotRemoveOwner] if trying to remove the owner
+    # @raise [Organizations::NotAuthorized] if removed_by is a member whose role
+    #   ranks below the removed member's role
     def remove_member!(user, removed_by: nil)
       membership = memberships.find_by(user_id: user.id)
       return unless membership
 
       if membership.role.to_sym == :owner
-        raise CannotRemoveOwner, Organizations.t(:"errors.cannot_remove_owner")
+        raise CannotRemoveOwner, Organizations.t(:"errors.cannot_remove_owner", organization: self)
       end
 
       ActiveRecord::Base.transaction do
         # Lock organization to prevent race conditions
         lock!
+
+        # Re-read the role under a row lock, without reloading the record (a
+        # reload would drop the live counter cache and fail on a row that is
+        # already gone). A member promoted, or made owner, since the lookup
+        # above is judged by the role they hold now.
+        locked_role = Membership.where(id: membership.id).lock.pick(:role)
+        if locked_role == "owner"
+          raise CannotRemoveOwner, Organizations.t(:"errors.cannot_remove_owner", organization: self)
+        end
+
+        # Only roles removed_by may act on (see Roles.assignment_refusal)
+        Membership.authorize_rank!(self, removed_by, [locked_role || membership.role],
+                                   permission: :remove_members,
+                                   message_key: :"errors.member_removal_outranks_actor")
         membership.destroy!
       end
 
@@ -290,6 +374,8 @@ module Organizations
     # @return [Membership] The updated membership
     # @raise [CannotHaveMultipleOwners] if promoting to owner when one exists
     # @raise [CannotRemoveLastOwner] if demoting the only owner
+    # @raise [Organizations::NotAuthorized] if changed_by is a member whose role
+    #   ranks below the member's current role or the new role
     def change_role_of!(user, to:, changed_by: nil)
       new_role = to.to_sym
       validate_role!(new_role)
@@ -310,14 +396,17 @@ module Organizations
         if new_role == :owner && old_role != :owner
           # Promoting to owner - this is only allowed via transfer_ownership_to!
           # Direct role change to owner is not permitted
-          raise CannotHaveMultipleOwners, Organizations.t(:"errors.cannot_promote_to_owner")
+          raise CannotHaveMultipleOwners, Organizations.t(:"errors.cannot_promote_to_owner", organization: self)
         end
 
         if old_role == :owner && new_role != :owner
           # Demoting owner - not allowed directly
-          raise CannotDemoteOwner, Organizations.t(:"errors.cannot_demote_owner_directly")
+          raise CannotDemoteOwner, Organizations.t(:"errors.cannot_demote_owner_directly", organization: self)
         end
 
+        # Only roles at or below changed_by's own may be given or taken away
+        membership.authorize_role_change!(new_role, changed_by: changed_by)
+
         membership.update!(role: new_role.to_s)
       end
 
@@ -341,8 +430,10 @@ module Organizations
     # @raise [CannotTransferToNonAdmin] if user is not an admin
     def transfer_ownership_to!(new_owner)
       ActiveRecord::Base.transaction do
-        # Lock organization first to prevent concurrent operations
-        lock!
+        lock_new_owner_row!(new_owner)
+        lock! # then the organization row, to prevent concurrent operations
+
+        ensure_not_personal_for_transfer!
 
         # Always perform a fresh read in this write path, even if memberships
         # are preloaded on this instance, to avoid stale-owner selection.
@@ -350,24 +441,23 @@ module Organizations
         new_owner_membership = memberships.find_by(user_id: new_owner.id)
 
         unless old_owner_membership
-          raise NoOwnerPresent, Organizations.t(:"errors.transfer_no_owner")
+          raise NoOwnerPresent, Organizations.t(:"errors.transfer_no_owner", organization: self)
         end
 
         unless new_owner_membership
-          raise CannotTransferToNonMember, Organizations.t(:"errors.transfer_to_non_member")
+          raise CannotTransferToNonMember, Organizations.t(:"errors.transfer_to_non_member", organization: self)
         end
 
         # New owner must be at least an admin (per README: "Ownership can be transferred to any admin")
         unless Roles.at_least?(new_owner_membership.role.to_sym, :admin)
-          raise CannotTransferToNonAdmin, Organizations.t(:"errors.transfer_to_non_admin")
+          raise CannotTransferToNonAdmin, Organizations.t(:"errors.transfer_to_non_admin", organization: self)
         end
 
         # No-op transfer to the current owner.
         return old_owner_membership if old_owner_membership.user_id == new_owner.id
 
         # Lock both memberships
-        old_owner_membership.lock!
-        new_owner_membership.lock!
+        [old_owner_membership, new_owner_membership].each(&:lock!)
 
         old_owner_user = old_owner_membership.user
 
@@ -393,8 +483,14 @@ module Organizations
     # @param invited_by [User, nil] Who is sending the invitation (uses Current.user if not provided)
     # @param role [Symbol] Role for the invitation (default: from config)
     # @return [Invitation] The created or existing invitation
+    # @param grants [Hash{resource => Array}, nil] resources the new member
+    #   gets on acceptance, with their capabilities (scoped resource grants).
+    #   The inviter needs config.grant_management_permission and, when grants
+    #   limit it, may give only access it has. On an existing pending
+    #   invitation they are added to it.
     # @raise [CannotInviteAsOwner] if role is :owner
-    def send_invite_to!(email, invited_by: nil, role: nil)
+    # @raise [Organizations::NotAuthorized] if the role ranks above the inviter's own
+    def send_invite_to!(email, invited_by: nil, role: nil, grants: nil)
       inviter = invited_by || current_user_from_context
       unless inviter
         raise ArgumentError, "invited_by is required (or set Current.user)"
@@ -407,18 +503,22 @@ module Organizations
 
       # Owner role cannot be assigned via invitation - only via transfer_ownership_to!
       if role_sym == :owner
-        raise CannotInviteAsOwner, Organizations.t(:"errors.invite_as_owner")
+        raise CannotInviteAsOwner, Organizations.t(:"errors.invite_as_owner", organization: self)
       end
 
+      # Nobody can invite to a role that ranks above their own
+      authorize_invited_role!(inviter, role_sym)
+
       normalized_email = email.downcase.strip
+      grants = grants.to_a
 
       # Check for existing pending invitation (idempotent)
       existing = invitations.pending.for_email(normalized_email).first
-      return existing if existing
+      return add_invitation_grants(existing, grants, inviter) if existing
 
       # Check if already a member (case-insensitive)
       if users.where("LOWER(email) = ?", normalized_email).exists?
-        raise Organizations::InvitationError, Organizations.t(:"errors.invitation_already_member")
+        raise Organizations::InvitationError, Organizations.t(:"errors.invitation_already_member", organization: self)
       end
 
       # Allow callback hooks to veto invitations (e.g., plan seat limits) before write.
@@ -429,6 +529,9 @@ module Organizations
         expires_at: calculate_expiry
       )
 
+      # Checked before anything is written or sent
+      invitation_context.authorize_grants!(grants, inviter)
+
       Callbacks.dispatch(
         :member_invited,
         strict: true,
@@ -445,24 +548,18 @@ module Organizations
       ActiveRecord::Base.transaction(requires_new: true) do
         # Check for expired invitation and refresh it instead of creating duplicate
         expired_invitation = invitations.expired.for_email(normalized_email).first
-        if expired_invitation
-          expired_invitation.lock!
-          expired_invitation.update!(
-            invited_by: inviter,
-            role: role.to_s,
-            token: generate_unique_token,
-            expires_at: calculate_expiry
-          )
-          invitation = expired_invitation
-        else
-          invitation = invitations.create!(
-            email: normalized_email,
-            invited_by: inviter,
-            role: role.to_s,
-            token: generate_unique_token,
-            expires_at: calculate_expiry
-          )
-        end
+        invitation = if expired_invitation
+                       reissue_invitation!(expired_invitation, inviter, role)
+                     else
+                       invitations.create!(
+                         email: normalized_email,
+                         invited_by: inviter,
+                         role: role.to_s,
+                         token: generate_unique_token,
+                         expires_at: calculate_expiry
+                       )
+                     end
+        apply_invitation_grants(invitation, grants, inviter)
       end
 
       # Send invitation email
@@ -470,8 +567,9 @@ module Organizations
 
       invitation
     rescue ActiveRecord::RecordNotUnique
-      # Race condition: invitation was created by another process
-      invitations.pending.for_email(normalized_email).first!
+      # Race condition: invitation was created by another process. Its
+      # grants are added the same way as for any existing invitation.
+      add_invitation_grants(invitations.pending.for_email(normalized_email).first!, grants.to_a, inviter)
     end
 
     # === Verified Joining Methods (v0.5.0) ===
@@ -479,9 +577,12 @@ module Organizations
     # Enroll an email domain for domain-verified joining.
     # @param domain [String] e.g. "inizio.com" (exact match — subdomains must be enrolled separately)
     # @param membership_metadata [Hash] copied onto memberships created through this domain
+    # @param join_policy [Symbol, String, nil] :none, :suggest or :auto_join (acts once the domain is verified)
     # @return [Domain]
-    def add_domain!(domain, membership_metadata: {})
-      domains.create!(domain: domain, membership_metadata: membership_metadata)
+    def add_domain!(domain, membership_metadata: {}, join_policy: nil)
+      attributes = { domain: domain, membership_metadata: membership_metadata }
+      attributes[:join_policy] = join_policy.to_s unless join_policy.nil?
+      domains.create!(attributes)
     end
 
     # Generate a shareable join code (PIN).
@@ -495,7 +596,7 @@ module Organizations
     # @return [JoinCode]
     # Every parameter is an optional keyword with a safe default — this IS
     # the public API surface, not incidental complexity.
-    # rubocop:disable Metrics/ParameterLists
+    # rubocop:disable-next Metrics/ParameterLists
     def generate_join_code!(label: nil, requires_verified_domain_email: false, auto_approve: true,
                             expires_at: nil, max_uses: nil, created_by: nil, membership_metadata: {})
       join_codes.create!(
@@ -508,7 +609,6 @@ module Organizations
         membership_metadata: membership_metadata
       )
     end
-    # rubocop:enable Metrics/ParameterLists
 
     # Bulk-import roster emails as allowlist entries (idempotent per address:
     # already-enrolled addresses are skipped, not duplicated).
@@ -549,7 +649,7 @@ module Organizations
     # challenge). Drives whether a join screen shows the email form.
     # @return [Boolean]
     def accepts_domain_joining?
-      domains.exists? || allowlist_entries.unclaimed.exists?
+      domains.joinable.exists? || allowlist_entries.unclaimed.exists?
     end
 
     # Whether this organization has at least one code that can actually be
@@ -599,19 +699,19 @@ module Organizations
     #   the email is unconfirmed, or the feature is disabled
     def join_with_account_email!(user)
       unless Organizations.configuration.trust_confirmed_account_email
-        raise VerificationEmailNotEligible, Organizations.t(:"errors.account_email_trust_disabled")
+        raise VerificationEmailNotEligible, Organizations.t(:"errors.account_email_trust_disabled", organization: self)
       end
 
       email = user.respond_to?(:email) ? user.email.to_s : ""
       confirmed = user.respond_to?(:confirmed_at) && user.confirmed_at.present?
 
       unless confirmed
-        raise VerificationEmailNotEligible, Organizations.t(:"errors.account_email_unconfirmed")
+        raise VerificationEmailNotEligible, Organizations.t(:"errors.account_email_unconfirmed", organization: self)
       end
 
-      matched_domain = domains.matching_email(email).first
+      matched_domain = domains.joinable.matching_email(email).first
       unless matched_domain
-        raise VerificationEmailNotEligible, Organizations.t(:"errors.verification_email_not_eligible")
+        raise VerificationEmailNotEligible, Organizations.t(:"errors.verification_email_not_eligible", organization: self)
       end
 
       # Uniform funnel: every self-serve join goes through a JoinRequest so
@@ -622,7 +722,7 @@ module Organizations
       ActiveRecord::Base.transaction do
         if Membership.where(organization_id: id, verified_email_normalized: normalized).exists?
           raise VerificationEmailAlreadyClaimed,
-                Organizations.t(:"errors.verification_email_already_claimed")
+                Organizations.t(:"errors.verification_email_already_claimed", organization: self)
         end
 
         request.assign_attributes(
@@ -635,11 +735,72 @@ module Organizations
         request.save!
       end
 
-      request.approve!(decided_by: nil)
+      request.send(:auto_approve!)
     end
 
     private
 
+    # Lock the new owner's user row before the organization row: the
+    # account-deletion guard locks a user row before organization rows, so
+    # both take their locks in the same order and cannot deadlock. A
+    # concurrent deletion of that user either finishes first (the membership
+    # is gone and the transfer is refused) or waits until the transfer
+    # commits (and sees the new ownership).
+    def lock_new_owner_row!(new_owner)
+      user_class = new_owner.class
+      return if user_class.unscoped.where(user_class.primary_key => new_owner.id).lock.pick(user_class.primary_key)
+
+      raise CannotTransferToNonMember, Organizations.t(:"errors.transfer_to_non_member", organization: self)
+    end
+
+    # A personal organization belongs to its owner. Call convert_to_shared!
+    # first to move it to someone else.
+    def ensure_not_personal_for_transfer!
+      return unless personal?
+
+      raise CannotTransferPersonalOrganization, Organizations.t(:"errors.transfer_personal_organization", organization: self)
+    end
+
+    def personal_owner_changed_to_someone?
+      has_attribute?(:personal_owner_id) && will_save_change_to_personal_owner_id? && personal_owner_id.present?
+    end
+
+    # The personal owner is the owner of the organization. A second,
+    # independent ownership record would be an authorization hole.
+    def personal_owner_holds_ownership
+      # Lock this organization's row first: transfer_ownership_to! takes the
+      # same lock, so the owner read here cannot go stale before the write.
+      self.class.unscoped.where(id: id).lock.pick(:id)
+      owner_id = memberships.where(role: "owner").pick(:user_id)
+      return if owner_id.present? && owner_id == personal_owner_id
+
+      errors.add(:personal_owner, Organizations.t(:"attributes.personal_owner_not_owner", organization: self))
+    end
+
+    # Refresh an expired invitation instead of creating a duplicate. It
+    # carries only the grants of the new call: the old ones were authorized
+    # for another inviter and role.
+    def reissue_invitation!(invitation, inviter, role)
+      invitation.lock!
+      invitation.grants.delete_all(:delete_all) if Organizations::GrantHolder.grants_table?
+      invitation.update!(invited_by: inviter, role: role.to_s, token: generate_unique_token,
+                         expires_at: calculate_expiry)
+      invitation
+    end
+
+    def add_invitation_grants(invitation, grants, inviter)
+      return invitation if grants.empty?
+
+      ActiveRecord::Base.transaction(requires_new: true) { apply_invitation_grants(invitation, grants, inviter) }
+      invitation
+    end
+
+    def apply_invitation_grants(invitation, grants, inviter)
+      grants.each do |resource, capabilities|
+        invitation.grant!(resource, capabilities: capabilities, granted_by: inviter)
+      end
+    end
+
     def ensure_join_request_belongs_here!(join_request)
       return if join_request.organization_id == id
 
@@ -662,7 +823,7 @@ module Organizations
 
       unless inviter_membership
         raise Organizations::NotAMember.new(
-          Organizations.t(:"errors.invite_not_a_member"),
+          Organizations.t(:"errors.invite_not_a_member", organization: self),
           organization: self,
           user: inviter
         )
@@ -671,13 +832,23 @@ module Organizations
       return if Roles.has_permission?(inviter_membership.role.to_sym, :invite_members)
 
       raise Organizations::NotAuthorized.new(
-        Organizations.t(:"errors.invite_not_authorized"),
+        Organizations.t(:"errors.invite_not_authorized", organization: self),
         permission: :invite_members,
         organization: self,
         user: inviter
       )
     end
 
+    # An inviter may only invite to roles that rank at or below their own (see
+    # Roles.can_assign?), so a custom role that can invite members still
+    # cannot invite an admin. A role that is not configured at all passes
+    # here and fails the invitation's own role validation instead.
+    def authorize_invited_role!(inviter, role)
+      Membership.authorize_rank!(self, inviter, [role],
+                                 permission: :invite_members,
+                                 message_key: :"errors.invite_role_outranks_actor")
+    end
+
     def validate_role!(role)
       unless Roles.valid_role?(role)
         raise ArgumentError, "Invalid role: #{role}. Must be one of: #{Roles.valid_roles.join(', ')}"