organizations 0.6.0 → 0.7.1

data/lib/organizations/models/concerns/has_organizations.rb

@@ -47,6 +47,9 @@ module Organizations
           def has_organizations(**options, &block)
             # Include instance methods
             include InstanceMethods
+            # Prepended, so a host override of destroy or of the association
+            # reader cannot drop these guards.
+            prepend PrependedMethods
 
             # Define associations
             define_organization_associations
@@ -59,6 +62,9 @@ module Organizations
 
             # Preserve owner integrity on user deletion
             setup_owner_deletion_guard
+
+            # Join auto_join domains once the account email is confirmed
+            after_commit :join_organizations_by_domain_after_confirmation, on: %i[create update]
           end
 
           private
@@ -83,6 +89,15 @@ module Organizations
                      source: :organization,
                      class_name: "Organizations::Organization"
 
+            # The user's personal organization (organizations.personal_owner_id).
+            # A lookup only: it never creates anything. See
+            # create_personal_organization!. Deleting the user is governed by
+            # config.account_deletion_policy, not by a dependent: option.
+            has_one :personal_organization,
+                    class_name: "Organizations::Organization",
+                    foreign_key: :personal_owner_id,
+                    inverse_of: :personal_owner
+
             # Invitations sent by this user
             has_many :sent_organization_invitations,
                      class_name: "Organizations::Invitation",
@@ -90,6 +105,13 @@ module Organizations
                      inverse_of: :invited_by,
                      dependent: :nullify
 
+            # Memberships those invitations became. Nullified on deletion like
+            # the invitations: the install migration gives invited_by_id a
+            # foreign key with no ON DELETE rule, so without this the database
+            # refuses to delete anyone whose invitation was accepted.
+            has_many :invited_organization_memberships, class_name: "Organizations::Membership",
+                                                        foreign_key: :invited_by_id, inverse_of: :invited_by, dependent: :nullify
+
             define_verified_joining_associations
           end
 
@@ -156,7 +178,13 @@ module Organizations
           def setup_owner_deletion_guard
             # `memberships` uses `dependent: :destroy`; this guard must run first
             # so owner memberships still exist when we verify ownership.
+            # The method name is kept from earlier versions, so a host's
+            # skip_callback for it keeps working.
             before_destroy :prevent_deletion_while_owning_organizations, prepend: true
+            # Before sent_organization_invitations is nullified: grants that
+            # this user attached to pending invitations die with the account,
+            # so an orphaned invitation never hands out unchecked access.
+            before_destroy :drop_grants_of_sent_invitations, prepend: true
           end
         end
 
@@ -192,6 +220,31 @@ module Organizations
           end
         end
 
+        # Prepended to the user model (see has_organizations).
+        module PrependedMethods
+          # Destroy inside its own SAVEPOINT. The account-deletion guard can
+          # delete a personal organization before a later callback aborts the
+          # destroy. Inside a host transaction, Rails would only release (not
+          # roll back) a joined transaction on abort, and the organization
+          # would stay deleted while the user survives. The savepoint makes
+          # the abort roll back everything this destroy did.
+          def destroy
+            result = nil
+            self.class.transaction(requires_new: true) do
+              result = super
+              raise ActiveRecord::Rollback unless result
+            end
+            result
+          end
+
+          # nil, not an unknown-column error, before the upgrade migration ran.
+          def personal_organization
+            return nil unless Organizations::Organization.column_names.include?("personal_owner_id")
+
+            super
+          end
+        end
+
         # Instance methods included in the user model
         module InstanceMethods
           # === Current Organization Context ===
@@ -431,6 +484,7 @@ module Organizations
           #
           def create_organization!(name_or_attributes)
             attributes = name_or_attributes.is_a?(Hash) ? name_or_attributes : { name: name_or_attributes }
+            Organizations::Organization.ensure_personal_owner_is_owner!(attributes, self)
 
             # Check max organizations limit
             settings = self.class.organization_settings
@@ -480,14 +534,14 @@ module Organizations
               if membership.role.to_sym == :owner
                 owner_count = org.memberships.where(role: "owner").count
                 if owner_count == 1
-                  raise CannotLeaveAsLastOwner, Organizations.t(:"errors.cannot_leave_as_last_owner")
+                  raise CannotLeaveAsLastOwner, Organizations.t(:"errors.cannot_leave_as_last_owner", organization: org)
                 end
               end
 
               # Check require_organization setting
               settings = self.class.organization_settings
               if settings[:require_organization] && organizations.count == 1
-                raise CannotLeaveLastOrganization, Organizations.t(:"errors.cannot_leave_last_organization")
+                raise CannotLeaveLastOrganization, Organizations.t(:"errors.cannot_leave_last_organization", organization: org)
               end
 
               membership.destroy!
@@ -519,9 +573,10 @@ module Organizations
           # @param email [String] Email address to invite
           # @param organization [Organizations::Organization] (optional, defaults to current)
           # @param role [Symbol] (optional, defaults to configured default)
+          # @param grants [Hash{resource => Array}, nil] see Organization#send_invite_to!
           # @return [Organizations::Invitation]
           # @raise [Organizations::NotAuthorized] if user doesn't have permission
-          def send_organization_invite_to!(email, organization: nil, role: nil)
+          def send_organization_invite_to!(email, organization: nil, role: nil, grants: nil)
             org = organization || current_organization
 
             unless org
@@ -533,14 +588,14 @@ module Organizations
             user_role = role_in(org)
             unless user_role && Roles.has_permission?(user_role, :invite_members)
               raise Organizations::NotAuthorized.new(
-                Organizations.t(:"errors.invite_not_authorized"),
+                Organizations.t(:"errors.invite_not_authorized", organization: org),
                 permission: :invite_members,
                 organization: org,
                 user: self
               )
             end
 
-            org.send_invite_to!(email, invited_by: self, role: role)
+            org.send_invite_to!(email, invited_by: self, role: role, grants: grants)
           end
 
           # === Verified Joining (v0.5.0) ===
@@ -565,7 +620,7 @@ module Organizations
             existing_membership = memberships.find_by(organization_id: organization.id)
             if existing_membership
               raise Organizations::JoinRequestAlreadyDecided,
-                    Organizations.t(:"errors.join_request_already_member")
+                    Organizations.t(:"errors.join_request_already_member", organization: organization)
             end
 
             # SAVEPOINT: the RecordNotUnique rescue below must stay reachable
@@ -596,6 +651,81 @@ module Organizations
             organization_join_requests.pending.find_by(organization_id: organization.id)
           end
 
+          # === Personal organization (v0.7.0) ===
+
+          # Create this user's personal organization, or return it when it
+          # already exists. The organization, the owner membership and the
+          # personal link are written together. Safe to call again: it is the
+          # retry path when sign-up provisioning failed, and concurrent calls
+          # converge on one organization (unique index on personal_owner_id).
+          #
+          # @param name_or_attributes [String, Hash, nil] defaults to
+          #   config.default_organization_name
+          # @return [Organizations::Organization]
+          # @raise [OrganizationLimitReached] when the user's limit is reached
+          def create_personal_organization!(name_or_attributes = nil)
+            ensure_personal_organizations_column!
+            existing = Organizations::Organization.find_by(personal_owner_id: id)
+            return remember_personal_organization(existing) if existing
+
+            attributes = name_or_attributes.is_a?(Hash) ? name_or_attributes.symbolize_keys : { name: name_or_attributes }
+            attributes[:name] ||= Organizations.configuration.resolve_default_organization_name(self)
+
+            # SAVEPOINT: the rescues below must stay reachable inside a host
+            # transaction on PostgreSQL.
+            organization = ActiveRecord::Base.transaction(requires_new: true) do
+              create_organization!(attributes.merge(personal_owner_id: id))
+            end
+            remember_personal_organization(organization)
+          rescue ActiveRecord::RecordNotUnique, Organizations::OrganizationLimitReached
+            # A concurrent call created it first: the unique index fired, or
+            # the winner's organization now counts against the limit. Any
+            # other failure re-raises, because then no personal organization
+            # exists. (When one exists, the call is idempotent by contract.)
+            winner = Organizations::Organization.find_by(personal_owner_id: id)
+            raise unless winner
+
+            remember_personal_organization(winner)
+          end
+
+          # === Domain policies (v0.7.0) ===
+
+          # Organizations to offer this user: a verified domain of theirs
+          # matches the user's confirmed account email, with join_policy
+          # "suggest" or "auto_join", and the user is not a member yet. Empty
+          # while the email is unconfirmed (it proves nothing yet) or
+          # config.trust_confirmed_account_email is off. Joining still goes
+          # through Organization#join_with_account_email! or JoinFlow.
+          # @return [ActiveRecord::Relation<Organizations::Organization>]
+          def suggested_organizations
+            organizations_with_domain_policy(%w[suggest auto_join])
+              .where.not(id: memberships.select(:organization_id))
+          end
+
+          # Join every organization whose verified domain has join_policy
+          # "auto_join" and matches the confirmed account email, through the
+          # membership gate (Organization#join_with_account_email!). Runs on
+          # its own after sign-up and after the email confirmation. A refusal
+          # (a veto, an email already claimed) skips that organization.
+          # Idempotent: it returns existing memberships too.
+          # @return [Array<Organizations::Membership>]
+          def join_organizations_by_domain!
+            organizations_with_domain_policy(%w[auto_join]).order(:id).filter_map do |organization|
+              memberships.find_by(organization_id: organization.id) || organization.join_with_account_email!(self)
+            rescue Organizations::Error, ActiveRecord::RecordInvalid => e
+              Callbacks.log_warn("[Organizations] Domain auto-join to organization #{organization.id} skipped: #{e.message}")
+              nil
+            end
+          end
+
+          # What deleting this user would do to their organizations. Changes
+          # nothing. See Organizations::AccountDeletionPlan.
+          # @param policy [Symbol] defaults to config.account_deletion_policy
+          # @return [Organizations::AccountDeletionPlan]
+          def account_deletion_plan(policy: Organizations.configuration.account_deletion_policy)
+            Organizations::AccountDeletionPlan.for(self, policy: policy)
+          end
+
           # Extension seam for personal organization creation.
           # Override this method in your User model to implement custom logic.
           #
@@ -632,18 +762,103 @@ module Organizations
             return unless should_create_personal_organization?
 
             org_name = Organizations.configuration.resolve_default_organization_name(self)
-            create_organization!(org_name)
+            if record_personal_organization?
+              create_personal_organization!(org_name)
+            else
+              create_organization!(org_name)
+            end
           rescue StandardError => e
             # Log but don't fail user creation
             Callbacks.log_error("[Organizations] Failed to create personal organization: #{e.message}")
           end
 
+          # The account-deletion guard (config.account_deletion_policy). Runs
+          # inside the destroy transaction, before the dependent memberships
+          # are destroyed. It locks this user's row first, so a concurrent
+          # join or organization creation for this user waits, then locks the
+          # owned organizations, so a concurrent join or transfer in them
+          # waits too. It checks the complete owned set before it deletes
+          # anything; a blocker, or any failure, aborts the whole destroy and
+          # rolls back every organization deleted so far.
           def prevent_deletion_while_owning_organizations
-            return unless memberships.where(role: "owner").exists?
+            lock_own_row_for_deletion
+            plan = Organizations::AccountDeletionPlan.for(self, lock: true)
+            unless plan.allowed?
+              errors.add(:base, Organizations.t(:"errors.cannot_delete_user_owns_organizations"))
+              throw(:abort)
+            end
+
+            plan.organizations_to_destroy.each { |organization| destroy_personal_organization_for_deletion(organization) }
+            memberships.reset if plan.organizations_to_destroy.any?
+          end
+
+          def drop_grants_of_sent_invitations
+            return unless Organizations::GrantHolder.grants_table?
+
+            Organizations::Grant.where(invitation_id: sent_organization_invitations.select(:id)).delete_all
+          end
+
+          def lock_own_row_for_deletion
+            self.class.unscoped.where(self.class.primary_key => id).lock.pick(self.class.primary_key)
+          end
 
-            errors.add(:base, Organizations.t(:"errors.cannot_delete_user_owns_organizations"))
+          def destroy_personal_organization_for_deletion(organization)
+            ActiveRecord::Base.transaction(requires_new: true) { organization.destroy! }
+          rescue ActiveRecord::RecordNotDestroyed => e
+            reasons = e.record.errors.full_messages.presence || [e.message]
+            reasons.each { |reason| errors.add(:base, reason) }
             throw(:abort)
           end
+
+          # The flag is on. Before the upgrade migration ran, keep the old
+          # behaviour (an ordinary organization) and warn, so a sign-up never
+          # loses its organization.
+          def record_personal_organization?
+            return false unless Organizations.configuration.record_personal_organizations
+            return true if Organizations::Organization.column_names.include?("personal_owner_id")
+
+            Callbacks.log_warn("[Organizations] record_personal_organizations is on but the personal_owner_id " \
+                               "column is missing. Run `rails g organizations:upgrade && rails db:migrate`.")
+            false
+          end
+
+          # The account email counts as proof of inbox control: it is
+          # confirmed, and config.trust_confirmed_account_email is on.
+          def proven_account_email?
+            Organizations.configuration.trust_confirmed_account_email &&
+              respond_to?(:confirmed_at) && confirmed_at.present? &&
+              respond_to?(:email) && email.present?
+          end
+
+          def organizations_with_domain_policy(policies)
+            return Organizations::Organization.none unless proven_account_email? && Organizations::Domain.authority_columns?
+
+            domains = Organizations::Domain.verified.joinable.with_join_policy(policies).matching_email(email)
+            Organizations::Organization.where(id: domains.select(:organization_id))
+          end
+
+          def join_organizations_by_domain_after_confirmation
+            return unless respond_to?(:confirmed_at) && saved_change_to_attribute?(:confirmed_at) && confirmed_at.present?
+            return unless Organizations::Domain.authority_columns?
+
+            join_organizations_by_domain!
+          rescue StandardError => e
+            # Never let a domain policy break a sign-up or a confirmation.
+            Callbacks.log_error("[Organizations] Domain auto-join failed: #{e.message}")
+          end
+
+          def remember_personal_organization(organization)
+            association(:personal_organization).target = organization
+            organization
+          end
+
+          def ensure_personal_organizations_column!
+            return if Organizations::Organization.column_names.include?("personal_owner_id")
+
+            raise Organizations::ConfigurationError,
+                  "Personal organizations need the personal_owner_id column. " \
+                  "Run `rails g organizations:upgrade && rails db:migrate`."
+          end
         end
       end
     end

data/lib/organizations/models/domain.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "active_support/security_utils"
+
 module Organizations
   # An email domain owned/claimed by an organization, used for verified joining.
   #
@@ -18,6 +20,22 @@ module Organizations
   # domain (see JoinRequest#approve!) — hosts use it for cohort tags like
   # { "member_kind" => "student" } without the gem interpreting the contents.
   #
+  # DOMAIN AUTHORITY (v0.7.0). An emailed code proves control of one inbox,
+  # never authority over the whole domain. Authority is a separate claim per
+  # organization: a DNS TXT record with an unpredictable token bound to this
+  # row (one organization, one exact domain), or an approval recorded by a
+  # platform operator who is not a member of the organization.
+  #
+  #   domain.start_verification!
+  #   domain.verification_record_name   # => "_organizations-verification.acme.com"
+  #   domain.verification_record_value  # => "organizations-verification=…"
+  #   domain.verify!                    # => true, or raises DomainVerificationFailed (#reason)
+  #
+  # `join_policy` decides what happens when someone with a confirmed account
+  # email at this domain signs up: "none" (default), "suggest" (listed in
+  # user.suggested_organizations) or "auto_join" (joined through the
+  # membership gate). The policy acts only while the domain is verified.
+  #
   # @example
   #   org.add_domain!("inizio.com")
   #   org.add_domain!("alumnos.urjc.es", membership_metadata: { member_kind: "student" })
@@ -26,20 +44,37 @@ module Organizations
   class Domain < ActiveRecord::Base
     self.table_name = "organizations_domains"
 
+    JOIN_POLICIES = %w[none suggest auto_join].freeze
+    VERIFICATION_METHODS = %w[dns_txt operator].freeze
+
     # === Associations ===
 
     belongs_to :organization,
                class_name: "Organizations::Organization",
                inverse_of: :domains
 
+    # The platform operator who recorded an approval (verification_method "operator")
+    belongs_to :verified_by,
+               class_name: Organizations.user_class_name,
+               optional: true
+
     # === Validations ===
 
     validates :domain, presence: true, uniqueness: { scope: :organization_id }
     validate :domain_shape
+    validate :domain_not_blocked, if: -> { new_record? || will_save_change_to_domain? }
+    validates :join_policy,
+              inclusion: { in: JOIN_POLICIES, message: ->(*) { Organizations.t(:"attributes.join_policy_invalid") } },
+              if: :authority_columns?
 
     # === Callbacks ===
 
     before_validation :normalize_domain
+    before_validation :normalize_join_policy, if: :authority_columns?
+    # A proof belongs to one claim: one organization and one exact domain.
+    before_save :reset_verification, if: lambda {
+      persisted? && authority_columns? && (will_save_change_to_domain? || will_save_change_to_organization_id?)
+    }
 
     # === Scopes ===
 
@@ -51,6 +86,49 @@ module Organizations
       extracted ? where(domain: extracted) : none
     }
 
+    # Domains whose control was proven and not revoked
+    scope :verified, -> { where.not(verified_at: nil).where(verification_revoked_at: nil) }
+
+    # Domains with one of these sign-up policies
+    scope :with_join_policy, ->(*policies) { where(join_policy: policies.flatten.map(&:to_s)) }
+
+    # Domains that may admit members right now: not revoked, not blocked
+    # (config.blocked_email_domains), and verified when
+    # config.require_verified_domains is on. Every domain-backed join path
+    # reads this scope, at the challenge and again at admission.
+    scope :joinable, lambda {
+      relation = all
+      if authority_columns?
+        relation = relation.where(verification_revoked_at: nil)
+        relation = relation.verified if Organizations.configuration.require_verified_domains
+      elsif Organizations.configuration.require_verified_domains
+        relation = none # fail closed before the upgrade migration ran
+      end
+      blocked = Organizations.configuration.normalized_blocked_email_domains
+      blocked.any? ? relation.where.not(domain: blocked) : relation
+    }
+
+    # Whether the domain-authority columns exist (rails g organizations:upgrade)
+    # @return [Boolean]
+    def self.authority_columns?
+      table_exists? && column_names.include?("verified_at")
+    end
+
+    # The built-in TXT lookup: Resolv, with config.domain_verification_timeout.
+    # @return [Proc] ->(record_name) { [String] }
+    def self.default_txt_resolver
+      lambda do |name|
+        require "resolv"
+        Resolv::DNS.open do |dns|
+          dns.timeouts = Organizations.configuration.domain_verification_timeout
+          # A trailing dot makes the name absolute: no resolver search list,
+          # so a wildcard record under a search domain cannot answer.
+          absolute = name.end_with?(".") ? name : "#{name}."
+          dns.getresources(absolute, Resolv::DNS::Resource::IN::TXT).map { |record| record.strings.join }
+        end
+      end
+    end
+
     # === Matching ===
 
     # Whether an email address belongs to this domain (exact match).
@@ -61,8 +139,212 @@ module Organizations
       extracted.present? && extracted == domain
     end
 
+    # === Domain authority ===
+
+    # @return [Boolean] control was proven and not revoked
+    def verified?
+      authority_columns? && verified_at.present? && verification_revoked_at.blank?
+    end
+
+    # @return [Boolean] the verification was revoked
+    def revoked?
+      authority_columns? && verification_revoked_at.present?
+    end
+
+    # @return [Boolean] whether config.blocked_email_domains lists this domain
+    def blocked?
+      Organizations.configuration.normalized_blocked_email_domains.include?(domain)
+    end
+
+    # @return [Boolean] the instance twin of the joinable scope
+    def joinable?
+      return false if revoked? || blocked?
+      return true unless Organizations.configuration.require_verified_domains
+
+      verified?
+    end
+
+    # The sign-up policy that acts now: the stored policy while the domain is
+    # verified and not blocked, :none otherwise.
+    # @return [Symbol] :none, :suggest or :auto_join
+    def effective_join_policy
+      verified? && !blocked? ? join_policy.to_sym : :none
+    end
+
+    # A copy (dup) of a claim carries no proof.
+    def initialize_dup(other)
+      super
+      reset_verification if authority_columns?
+    end
+
+    # Start (or restart) the DNS challenge: a new unpredictable token, and
+    # any earlier verification cleared. A revocation stays until a new proof
+    # succeeds. Publish verification_record_value as a TXT record at
+    # verification_record_name, then call verify!.
+    # @return [self]
+    def start_verification!
+      update!(
+        verification_token: SecureRandom.urlsafe_base64(32),
+        verification_started_at: Time.current,
+        verified_at: nil, verification_method: nil, verified_by_id: nil
+      )
+      self
+    end
+
+    # @return [String] where the TXT record goes, e.g. "_organizations-verification.acme.com"
+    def verification_record_name
+      "#{Organizations.configuration.domain_verification_record_prefix}.#{domain}"
+    end
+
+    # @return [String, nil] the exact TXT value, e.g. "organizations-verification=…"
+    def verification_record_value
+      return nil if verification_token.blank?
+
+      "#{Organizations.configuration.domain_verification_record_prefix.delete_prefix('_')}=#{verification_token}"
+    end
+
+    # @return [Boolean] the open challenge is past config.domain_verification_ttl
+    def verification_expired?
+      verification_started_at.blank? ||
+        verification_started_at + Organizations.configuration.domain_verification_ttl <= Time.current
+    end
+
+    # Check the TXT record and mark the domain verified. The DNS lookup runs
+    # outside any row lock; rate-limit the endpoint that calls this.
+    # @return [self]
+    # @raise [DomainVerificationFailed] reason :not_started, :expired,
+    #   :record_not_found or :lookup_failed
+    def verify!
+      reload
+      raise DomainVerificationFailed, :not_started if verification_token.blank?
+      raise DomainVerificationFailed, :expired if verification_expired?
+
+      snapshot = challenge_snapshot
+      raise DomainVerificationFailed, :record_not_found unless txt_record_present?(verification_record_value)
+
+      with_lock do
+        # The claim changed during the lookup (new token, other domain or
+        # organization, a revocation) or the challenge expired: the lookup
+        # proves nothing about the claim as it is now.
+        raise DomainVerificationFailed, :changed if challenge_snapshot != snapshot
+        raise DomainVerificationFailed, :expired if verification_expired?
+
+        update!(verified_at: Time.current, verification_method: "dns_txt",
+                verified_by_id: nil, verification_revoked_at: nil)
+      end
+      self
+    end
+
+    # Record an approval by a trusted platform operator who checked the
+    # claim another way. The claiming organization cannot self-attest: an
+    # operator who is a member of it is refused. Authorizing the operator as
+    # platform staff is the host's job.
+    # @param operator [User]
+    # @param note [String, nil] audit provenance, kept in metadata["verification_note"]
+    # @return [self]
+    # @raise [Organizations::NotAuthorized] when the operator is a member of the organization
+    def verify_by_operator!(operator:, note: nil)
+      raise ArgumentError, "operator is required" unless operator
+
+      ActiveRecord::Base.transaction do
+        # The organization row lock serializes this check with joins that
+        # take it (the seat-limit gate pattern) and with ownership changes.
+        organization.lock!
+        lock!
+        if organization.memberships.exists?(user_id: operator.id)
+          raise Organizations::NotAuthorized.new(Organizations.t(:"errors.domain_operator_is_member", organization: organization),
+                                                 organization: organization, user: operator)
+        end
+
+        update!(verified_at: Time.current, verification_method: "operator", verified_by_id: operator.id,
+                verification_revoked_at: nil, metadata: metadata_with("verification_note" => note))
+      end
+      self
+    end
+
+    # Revoke the verification. New domain-backed admissions stop (also
+    # pending ones); existing members stay. The verification stays on record
+    # for audit. Idempotent.
+    # @param reason [String, nil] kept in metadata["verification_revoked_reason"]
+    # @return [self]
+    def revoke_verification!(reason: nil)
+      return self if revoked?
+
+      update!(verification_revoked_at: Time.current, metadata: metadata_with("verification_revoked_reason" => reason))
+      self
+    end
+
+    # Re-check a DNS verification (run it on a schedule if you like). Revokes
+    # when the TXT record is gone; a lookup failure raises and changes
+    # nothing. An operator approval is not re-checked. Read verified? after.
+    # @return [self]
+    # @raise [DomainVerificationFailed] reason :lookup_failed
+    def recheck_verification!
+      reload
+      return self unless verified? && verification_method == "dns_txt"
+
+      snapshot = proof_snapshot
+      return self if txt_record_present?(verification_record_value)
+
+      with_lock do
+        # Revoke only the proof that was checked, never a newer one.
+        revoke_verification!(reason: "dns_record_removed") if proof_snapshot == snapshot
+      end
+      self
+    end
+
     private
 
+    def authority_columns?
+      self.class.authority_columns?
+    end
+
+    # metadata with these keys set, or removed when the value is nil. Other
+    # keys (the host's) stay exactly as they are.
+    def metadata_with(values)
+      values.each_with_object((metadata || {}).dup) do |(key, value), result|
+        value.nil? ? result.delete(key) : result[key] = value
+      end
+    end
+
+    def challenge_snapshot
+      [verification_token, domain, organization_id, verification_revoked_at]
+    end
+
+    def proof_snapshot
+      [verification_token, verified_at, verification_method, domain, organization_id]
+    end
+
+    def txt_record_present?(expected)
+      resolver = Organizations.configuration.domain_txt_resolver || self.class.default_txt_resolver
+      values = Array(resolver.call(verification_record_name)).map { |value| value.to_s.strip }
+      values.any? { |value| ActiveSupport::SecurityUtils.secure_compare(value, expected) }
+    rescue StandardError => e
+      # Resolv::ResolvError/ResolvTimeout, socket errors, or a host resolver's
+      # own error. Logged, so a broken resolver does not look like an outage.
+      Callbacks.log_warn("[Organizations] TXT lookup for #{verification_record_name} failed: #{e.class}: #{e.message}")
+      raise DomainVerificationFailed, :lookup_failed
+    end
+
+    def normalize_join_policy
+      self.join_policy = join_policy.to_s if join_policy.is_a?(Symbol)
+    end
+
+    def reset_verification
+      self.verification_token = nil
+      self.verification_started_at = nil
+      self.verified_at = nil
+      self.verification_method = nil
+      self.verified_by_id = nil
+      self.verification_revoked_at = nil
+    end
+
+    def domain_not_blocked
+      return if domain.blank? || !blocked?
+
+      errors.add(:domain, Organizations.t(:"attributes.domain_blocked", organization: organization))
+    end
+
     def normalize_domain
       return if domain.blank?
 
@@ -75,7 +357,7 @@ module Organizations
       return if domain.blank? # presence validation covers this
 
       unless domain.match?(/\A[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+\z/)
-        errors.add(:domain, Organizations.t(:"attributes.domain_invalid"))
+        errors.add(:domain, Organizations.t(:"attributes.domain_invalid", organization: organization))
       end
     end
   end