organizations 0.4.2 → 0.5.0

data/lib/organizations/join_flow.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+module Organizations
+  # The controller-facing facade over verified joining: ONE call that says
+  # "this user is trying to join this organization with whatever they gave
+  # us", returning a Result instead of raising — so host controllers render
+  # states instead of writing ten-branch rescue ladders.
+  #
+  # The model APIs (JoinCode.redeem, JoinRequest#start_email_verification!,
+  # …) remain the exception-raising programmatic layer; JoinFlow is the skin
+  # every join UI ends up needing. Before this existed, the first production
+  # host's "JoinService" was ~60% this exact translation, rewritten by hand.
+  #
+  # Dispatch order (first present input wins):
+  #   verification_code → verify the emailed 6-digit code
+  #   code              → redeem a join code (PIN)
+  #   email             → start/restart the emailed challenge for an address
+  #   (none)            → confirmed-account-email shortcut when eligible,
+  #                       else a plain request-to-join
+  #
+  # @example A join endpoint in three lines
+  #   result = Organizations::JoinFlow.attempt(
+  #     user: current_user, organization: @org,
+  #     code: params[:code], email: params[:email], message: params[:message]
+  #   )
+  #   result.member? ? redirect_to(@org) : render_state(result)
+  #
+  # Result contract:
+  #   outcome — :member | :challenge_sent | :pending | :vetoed | :error
+  #   reason  — nil on success; on :vetoed/:error a stable symbol from
+  #             REASONS (build your copy off this, never off the message)
+  #   message — localized human string (the caught error's message, already
+  #             resolved through the gem's i18n catalog — override per key
+  #             in your locale files, or ignore it and map reason yourself)
+  #   membership / join_request — the record backing the outcome
+  #
+  # ⚠️ SECURITY (host responsibilities that CANNOT live in the gem):
+  #   - Rate-limit the endpoints that call this (code redemption and
+  #     verification are enumeration surfaces) — see README "Rate limiting
+  #     your join endpoints".
+  #   - :join_code_invalid deliberately covers unknown, revoked, expired AND
+  #     foreign-organization codes with one reason — never tell users which
+  #     codes exist. (Known narrow residual: response SHAPE is identical, but
+  #     an expired org-scoped code does slightly more work than the
+  #     fast-reject paths — it reaches redeem!'s row lock before raising — a
+  #     timing side-channel your endpoint rate limits should render moot.)
+  class JoinFlow
+    # Stable machine-readable reasons a host can switch on.
+    REASONS = %i[
+      join_code_invalid
+      join_code_exhausted
+      email_not_eligible
+      email_already_claimed
+      throttled
+      verification_code_invalid
+      verification_code_expired
+      verification_code_missing
+      verification_attempts_exceeded
+      request_closed
+      not_accepting_requests
+      membership_vetoed
+    ].freeze
+
+    Result = Struct.new(:outcome, :reason, :membership, :join_request, :message, keyword_init: true) do
+      def member? = outcome == :member
+      def challenge_sent? = outcome == :challenge_sent
+      def pending? = outcome == :pending
+      def vetoed? = outcome == :vetoed
+      def error? = outcome == :error
+      # Anything that should render as a problem state (veto included).
+      def failed? = error? || vetoed?
+    end
+
+    # @param user [User] the joining user (required)
+    # @param organization [Organizations::Organization] the org being joined
+    #   (required — codes from OTHER organizations resolve to
+    #   :join_code_invalid on purpose; for organization-less global
+    #   redemption call Organizations::JoinCode.redeem directly)
+    # @param code [String, nil] a join code (PIN) as typed
+    # @param email [String, nil] address for the emailed challenge
+    # @param verification_code [String, nil] the emailed 6-digit code as typed
+    # @param message [String, nil] optional note for manual approval requests
+    # @return [Result]
+    # Every parameter is an optional keyword with a safe default — this IS
+    # the public API surface, not incidental complexity (same posture as
+    # Organization#generate_join_code!).
+    # rubocop:disable Metrics/ParameterLists
+    def self.attempt(user:, organization:, code: nil, email: nil, verification_code: nil, message: nil)
+      new(user: user, organization: organization)
+        .attempt(code: code, email: email, verification_code: verification_code, message: message)
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    def initialize(user:, organization:)
+      @user = user
+      @organization = organization
+    end
+
+    def attempt(code: nil, email: nil, verification_code: nil, message: nil)
+      # Already a member: every input resolves to the same quiet success —
+      # never consume a code use or mint a request for someone who's in.
+      if (existing = organization.memberships.find_by(user_id: user.id))
+        return Result.new(outcome: :member, membership: existing)
+      end
+
+      return verify_emailed_code(verification_code) if verification_code.present?
+      return redeem_code(code) if code.present?
+      return start_challenge(email) if email.present?
+      return account_email_shortcut if account_email_eligible?
+
+      plain_request(message)
+    rescue Organizations::MembershipVetoed => e
+      # The host's on_member_joining gate said no — a first-class outcome,
+      # not a generic error (hosts usually show cap-specific copy + support).
+      Result.new(outcome: :vetoed, reason: :membership_vetoed, message: e.message)
+    end
+
+    private
+
+    attr_reader :user, :organization
+
+    def verify_emailed_code(typed_code)
+      request = user.pending_join_request_for(organization)
+      return error(:verification_code_missing, Organizations.t(:"errors.verification_code_missing")) unless request
+
+      from_outcome(request.verify_email_code!(typed_code))
+    rescue Organizations::VerificationAttemptsExceeded => e
+      error(:verification_attempts_exceeded, e.message)
+    rescue Organizations::VerificationCodeExpired => e
+      error(:verification_code_expired, e.message)
+    rescue Organizations::VerificationCodeInvalid => e
+      error(:verification_code_invalid, e.message)
+    rescue Organizations::VerificationEmailAlreadyClaimed => e
+      error(:email_already_claimed, e.message)
+    rescue Organizations::JoinRequestError => e
+      error(:request_closed, e.message)
+    end
+
+    def redeem_code(raw_code)
+      normalized = Organizations::JoinCode.normalize(raw_code)
+      join_code = normalized.present? && Organizations::JoinCode.not_revoked.find_by(code: normalized)
+
+      # One reason for unknown/revoked/expired/foreign codes — the code
+      # endpoint is the enumeration surface; never reveal which codes exist
+      # or whose they are.
+      unless join_code && join_code.organization_id == organization.id
+        return error(:join_code_invalid, Organizations.t(:"errors.join_code_invalid"))
+      end
+
+      from_outcome(join_code.redeem!(user: user))
+    rescue Organizations::JoinCodeExhausted => e
+      # NOTE: rescued before JoinCodeInvalid — it's a subclass.
+      error(:join_code_exhausted, e.message)
+    rescue Organizations::JoinCodeInvalid => e
+      error(:join_code_invalid, e.message)
+    end
+
+    def start_challenge(email)
+      request = user.pending_join_request_for(organization) || user.request_to_join!(organization)
+      request.start_email_verification!(email: email)
+
+      Result.new(outcome: :challenge_sent, join_request: request)
+    rescue Organizations::VerificationEmailNotEligible => e
+      error(:email_not_eligible, e.message)
+    rescue Organizations::VerificationEmailAlreadyClaimed => e
+      error(:email_already_claimed, e.message)
+    rescue Organizations::VerificationThrottled => e
+      error(:throttled, e.message)
+    rescue Organizations::JoinRequestError => e
+      error(:request_closed, e.message)
+    end
+
+    def account_email_shortcut
+      from_outcome(organization.join_with_account_email!(user))
+    rescue Organizations::VerificationEmailAlreadyClaimed => e
+      error(:email_already_claimed, e.message)
+    rescue Organizations::VerificationEmailNotEligible
+      # Eligibility changed between the pre-check and the call (domain
+      # removed, trust flipped) — degrade to the plain request path.
+      plain_request(nil)
+    end
+
+    def plain_request(message)
+      unless organization.accepts_join_requests?
+        return error(:not_accepting_requests, Organizations.t(:"errors.not_accepting_requests"))
+      end
+
+      from_outcome(user.request_to_join!(organization, message: message))
+    rescue Organizations::JoinRequestError => e
+      error(:request_closed, e.message)
+    end
+
+    def account_email_eligible?
+      Organizations.configuration.trust_confirmed_account_email &&
+        user.respond_to?(:confirmed_at) && user.confirmed_at.present? &&
+        user.respond_to?(:email) &&
+        organization.domains.matching_email(user.email).exists?
+    end
+
+    def from_outcome(outcome)
+      case outcome
+      when Organizations::Membership
+        Result.new(outcome: :member, membership: outcome)
+      when Organizations::JoinRequest
+        if outcome.verification_sent_at.present? && !outcome.email_verified?
+          Result.new(outcome: :challenge_sent, join_request: outcome)
+        else
+          Result.new(outcome: :pending, join_request: outcome)
+        end
+      else
+        error(:request_closed, Organizations.t(:"errors.join_request_create_failed"))
+      end
+    end
+
+    def error(reason, message)
+      # Developer guard (review finding): REASONS is a published contract
+      # hosts switch on — a typo'd symbol here would silently ship a reason
+      # nobody's copy mapping knows. (Hosts building their OWN Results may
+      # use their own symbols; this guards the gem's internal emissions.)
+      unless REASONS.include?(reason)
+        raise ArgumentError, "unknown JoinFlow reason #{reason.inspect} — add it to JoinFlow::REASONS"
+      end
+
+      Result.new(outcome: :error, reason: reason, message: message)
+    end
+  end
+end

data/lib/organizations/join_state.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Organizations
+  # The headless state machine behind any "join this organization" screen —
+  # BYO-UI in its truest form: the gem ships the STATE, the host ships the
+  # pixels. One object answers "which state is this screen in" so a page
+  # body, a pinned CTA, and a Turbo Stream response can never disagree
+  # (splitting these predicates across partials is exactly how a submit
+  # button ends up pointing at a form that no longer exists — a bug the
+  # first production host paid for before extracting this).
+  #
+  #   :member    — the viewer belongs; show the success/hub state
+  #   :verifying — an emailed-code challenge is in flight; show the 6-digit
+  #                input (+ resend with #resend_seconds cooldown)
+  #   :pending   — a request awaits manual approval; show the waiting state
+  #   :entry     — no relationship yet; show the join form(s) the org's
+  #                instruments allow (organization.accepts_domain_joining? /
+  #                accepts_code_joining? / accepts_join_requests?)
+  #
+  # @example In a controller
+  #   @result = Organizations::JoinFlow.attempt(user: current_user, organization: @org, **join_params)
+  #   @state  = Organizations::JoinState.for(user: current_user, organization: @org, result: @result)
+  #
+  # @example In the view
+  #   case @state.status
+  #   when :member    then render "joined"
+  #   when :verifying then render "code_input", seconds: @state.resend_seconds
+  #   when :pending   then render "waiting"
+  #   when :entry     then render "join_form"
+  #   end
+  class JoinState
+    STATUSES = %i[member verifying pending entry].freeze
+
+    attr_reader :organization, :membership, :join_request, :result
+
+    # Build the state for a viewer. Pass the JoinFlow::Result of the action
+    # that JUST ran (nil on a plain GET): its records are fresher than any
+    # association cache — right after a successful verify, the new membership
+    # lives on the result, not necessarily in a reloaded association.
+    #
+    # @param user [User]
+    # @param organization [Organizations::Organization]
+    # @param result [Organizations::JoinFlow::Result, nil]
+    # @return [JoinState]
+    def self.for(user:, organization:, result: nil)
+      new(
+        organization: organization,
+        membership: result&.membership || organization.memberships.find_by(user_id: user.id),
+        join_request: result&.join_request || user.pending_join_request_for(organization),
+        result: result
+      )
+    end
+
+    def initialize(organization:, membership:, join_request:, result: nil)
+      @organization = organization
+      @membership = membership
+      @join_request = join_request
+      @result = result
+    end
+
+    # @return [Symbol] one of STATUSES
+    def status
+      return :member if member?
+      return :verifying if verifying?
+      return :pending if pending?
+
+      :entry
+    end
+
+    def member?
+      membership.present? || result&.member?
+    end
+
+    def verifying?
+      return false if member?
+      return true if result&.challenge_sent?
+
+      challenge.present? && challenge.verification_sent_at.present? && !challenge.email_verified?
+    end
+
+    def pending?
+      return false if member? || verifying?
+
+      join_request.present? || result&.pending?
+    end
+
+    def entry?
+      status == :entry
+    end
+
+    # The join request whose emailed challenge is being answered (feeds the
+    # verify form and #resend_seconds).
+    # @return [Organizations::JoinRequest, nil]
+    def challenge
+      result&.join_request || join_request
+    end
+
+    # Seconds until the gem will accept another code send for this challenge
+    # — drive a client-side resend cooldown from this instead of mirroring
+    # config.verification_resend_interval as a magic number in the host
+    # (mirrored constants desync the day someone tunes the config).
+    # @return [Integer] 0 when a resend is allowed now
+    def resend_seconds
+      sent_at = challenge&.verification_sent_at
+      return 0 if sent_at.blank?
+
+      interval = Organizations.configuration.verification_resend_interval.to_i
+      [interval - (Time.current - sent_at).to_i, 0].max
+    end
+
+    # Localized message of a just-failed action, nil otherwise.
+    # @return [String, nil]
+    def error_message
+      result&.message if result&.failed?
+    end
+  end
+end

data/lib/organizations/metadata_flags.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Organizations
+  # Typed boolean accessors over a json(b) metadata bag, with a DEFAULT for
+  # missing keys — the pattern every host grows around the gem's metadata
+  # channel ("show this membership on the profile?", "receive digests?").
+  #
+  # Why not store_accessor: store_accessor gives raw reads — a nil (never
+  # set) is indistinguishable from false, so hosts hand-roll the same
+  # `value.nil? ? default : Boolean.cast(value)` predicate for every flag
+  # (one production host had three identical copies). metadata_flag bakes
+  # the default + cast in.
+  #
+  # Organizations::Organization and Organizations::Membership are already
+  # extended with this — call the macro from your extension concern:
+  #
+  #   ActiveSupport.on_load(:organizations_membership) do
+  #     metadata_flag :show_on_profile, default: true
+  #     metadata_flag :show_on_leaderboard, default: true
+  #   end
+  #
+  #   membership.show_on_profile?          # => true (unset ⇒ the default)
+  #   membership.show_on_profile = false   # writes into metadata
+  #   membership.toggle_show_on_profile!   # flip + save!
+  #
+  # ⚠️ Don't ALSO declare the same key via store_accessor — you'd get two
+  # writers with different semantics for one key. Pick one mechanism per key.
+  #
+  # @example A flag over a different bag column
+  #   metadata_flag :beta_features, default: false, column: :settings
+  module MetadataFlags
+    # @param name [Symbol] flag name (becomes name?, name=, toggle_name!)
+    # @param default [Boolean] value when the key is absent from the bag
+    # @param column [Symbol] the json(b) attribute holding the bag
+    def metadata_flag(name, default:, column: :metadata)
+      define_metadata_flag_reader(name, default, column)
+      define_metadata_flag_writer(name, column)
+      define_metadata_flag_toggle(name)
+    end
+
+    private
+
+    def define_metadata_flag_reader(name, default, column)
+      key = name.to_s
+      define_method("#{name}?") do
+        bag = public_send(column)
+        # Defensive: a non-Hash bag (text column, corrupted value) reads as
+        # empty → the default. The WRITER requires a real json(b)/serialized
+        # Hash column — see the module docs.
+        raw = bag.is_a?(Hash) ? bag[key] : nil
+        raw.nil? ? default : ActiveModel::Type::Boolean.new.cast(raw)
+      end
+    end
+
+    def define_metadata_flag_writer(name, column)
+      key = name.to_s
+      define_method("#{name}=") do |value|
+        bag = (public_send(column) || {}).merge(key => value)
+        public_send("#{column}=", bag)
+      end
+    end
+
+    def define_metadata_flag_toggle(name)
+      define_method("toggle_#{name}!") do
+        # with_lock (review finding): a bare read-negate-save! races under
+        # concurrent toggles (classic read-modify-write on a JSON column).
+        # The lock reloads, so the negation applies to the CURRENT database
+        # value — two racing toggles serialize instead of both writing the
+        # same flip. New (unpersisted) records just assign.
+        flip = lambda do
+          public_send("#{name}=", !public_send("#{name}?"))
+          save!
+        end
+        persisted? ? with_lock(&flip) : flip.call
+        self
+      end
+    end
+  end
+end

data/lib/organizations/models/allowlist_entry.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Organizations
+  # A pre-approved email address on an organization's roster/allowlist,
+  # used for verified joining when the organization has no email domain
+  # of its own (clubs, associations, mixed-provider orgs).
+  #
+  # A user who proves control of a rostered inbox (emailed code) becomes a
+  # verified member and the entry is marked claimed. Proof-of-control is
+  # still required — a leaked roster must never grant membership without
+  # inbox access.
+  #
+  # Entries are typically bulk-imported: see Organization#import_allowlist!.
+  #
+  # @example
+  #   org.import_allowlist!(["ana@gmail.com", "luis@yahoo.es"], source: "csv_2026-07")
+  #
+  class AllowlistEntry < ActiveRecord::Base
+    self.table_name = "organizations_allowlist_entries"
+
+    # === Associations ===
+
+    belongs_to :organization,
+               class_name: "Organizations::Organization",
+               inverse_of: :allowlist_entries
+
+    belongs_to :claimed_by,
+               class_name: Organizations.user_class_name,
+               optional: true
+
+    # === Validations ===
+
+    validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
+    # Proc message: resolved at VALIDATION time so it follows I18n.locale.
+    validates :email_normalized, presence: true,
+                                 uniqueness: { scope: :organization_id,
+                                               message: ->(*) { Organizations.t(:"attributes.allowlist_taken") } }
+
+    # === Callbacks ===
+
+    before_validation :normalize_email
+
+    # === Scopes ===
+
+    # Entries not yet consumed by a membership
+    scope :unclaimed, -> { where(claimed_at: nil) }
+
+    # Entries matching an email (through the configured normalizer)
+    scope :for_email, lambda { |email|
+      where(email_normalized: Organizations.configuration.normalize_verification_email(email))
+    }
+
+    # === Status ===
+
+    # @return [Boolean]
+    def claimed?
+      claimed_at.present?
+    end
+
+    # Mark this entry as consumed by a user's membership.
+    # Idempotent: claiming an already-claimed entry is a no-op.
+    # @param user [User]
+    # @return [self]
+    def claim!(user)
+      return self if claimed?
+
+      with_lock do
+        break if claimed?
+
+        update!(claimed_at: Time.current, claimed_by_id: user.id)
+      end
+
+      self
+    end
+
+    private
+
+    def normalize_email
+      return if email.blank?
+
+      self.email = email.to_s.strip
+      self.email_normalized = Organizations.configuration.normalize_verification_email(email)
+    end
+  end
+end
+
+# Host extension seam — see the load-hooks note in models/organization.rb.
+ActiveSupport.run_load_hooks(:organizations_allowlist_entry, Organizations::AllowlistEntry)

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

@@ -25,12 +25,15 @@ module Organizations
       module HasOrganizations
         extend ActiveSupport::Concern
 
-        # Error raised when org limits are exceeded
-        class OrganizationLimitReached < Organizations::Error; end
-        class CannotLeaveLastOrganization < Organizations::Error; end
-        class CannotLeaveAsLastOwner < Organizations::Error; end
-        class CannotDeleteAsOrganizationOwner < Organizations::Error; end
-        class NoCurrentOrganization < Organizations::Error; end
+        # Historical aliases — the CANONICAL constants live at Organizations::
+        # top level since 0.5.0 (rescue Organizations::CannotLeaveAsLastOwner,
+        # not this four-modules-deep path). Same class objects, so existing
+        # rescues of the nested paths keep working.
+        OrganizationLimitReached = Organizations::OrganizationLimitReached
+        CannotLeaveLastOrganization = Organizations::CannotLeaveLastOrganization
+        CannotLeaveAsLastOwner = Organizations::CannotLeaveAsLastOwner
+        CannotDeleteAsOrganizationOwner = Organizations::CannotDeleteAsOrganizationOwner
+        NoCurrentOrganization = Organizations::NoCurrentOrganization
 
         # Module containing class methods to be extended onto ActiveRecord::Base
         module ClassMethods
@@ -86,6 +89,38 @@ module Organizations
                      foreign_key: :invited_by_id,
                      inverse_of: :invited_by,
                      dependent: :nullify
+
+            define_verified_joining_associations
+          end
+
+          # Verified-joining (v0.5.0) associations, split out for readability
+          def define_verified_joining_associations
+            # This user's join requests (request-to-join workflow)
+            has_many :organization_join_requests,
+                     class_name: "Organizations::JoinRequest",
+                     foreign_key: :user_id,
+                     inverse_of: :user,
+                     dependent: :destroy
+
+            # Trails this user leaves as an actor on other people's records —
+            # nullified on deletion, same as sent_organization_invitations
+            has_many :decided_organization_join_requests,
+                     class_name: "Organizations::JoinRequest",
+                     foreign_key: :decided_by_id,
+                     inverse_of: :decided_by,
+                     dependent: :nullify
+
+            has_many :created_organization_join_codes,
+                     class_name: "Organizations::JoinCode",
+                     foreign_key: :created_by_id,
+                     inverse_of: :created_by,
+                     dependent: :nullify
+
+            has_many :claimed_organization_allowlist_entries,
+                     class_name: "Organizations::AllowlistEntry",
+                     foreign_key: :claimed_by_id,
+                     inverse_of: :claimed_by,
+                     dependent: :nullify
           end
 
           def define_organization_settings(options, &block)
@@ -401,7 +436,7 @@ module Organizations
             settings = self.class.organization_settings
             max = settings[:max_organizations]
             if max && owned_organizations.count >= max
-              raise OrganizationLimitReached, "Maximum number of organizations (#{max}) reached"
+              raise OrganizationLimitReached, Organizations.t(:"errors.organization_limit_reached", max: max)
             end
 
             org = nil
@@ -445,14 +480,14 @@ module Organizations
               if membership.role.to_sym == :owner
                 owner_count = org.memberships.where(role: "owner").count
                 if owner_count == 1
-                  raise CannotLeaveAsLastOwner, "Cannot leave organization as the only owner. Transfer ownership first."
+                  raise CannotLeaveAsLastOwner, Organizations.t(:"errors.cannot_leave_as_last_owner")
                 end
               end
 
               # Check require_organization setting
               settings = self.class.organization_settings
               if settings[:require_organization] && organizations.count == 1
-                raise CannotLeaveLastOrganization, "Cannot leave your only organization"
+                raise CannotLeaveLastOrganization, Organizations.t(:"errors.cannot_leave_last_organization")
               end
 
               membership.destroy!
@@ -474,7 +509,7 @@ module Organizations
           # @raise [NoCurrentOrganization] if no current organization
           def leave_current_organization!
             unless current_organization
-              raise NoCurrentOrganization, "No current organization to leave"
+              raise NoCurrentOrganization, Organizations.t(:"errors.no_current_organization_to_leave")
             end
 
             leave_organization!(current_organization)
@@ -498,7 +533,7 @@ module Organizations
             user_role = role_in(org)
             unless user_role && Roles.has_permission?(user_role, :invite_members)
               raise Organizations::NotAuthorized.new(
-                "You don't have permission to invite members",
+                Organizations.t(:"errors.invite_not_authorized"),
                 permission: :invite_members,
                 organization: org,
                 user: self
@@ -508,6 +543,59 @@ module Organizations
             org.send_invite_to!(email, invited_by: self, role: role)
           end
 
+          # === Verified Joining (v0.5.0) ===
+
+          # Petition to join an organization (request-to-join workflow).
+          # Idempotent: returns the existing open request when one exists.
+          # Fires the :join_request_created callback for new requests.
+          #
+          # @param organization [Organizations::Organization]
+          # @param message [String, nil] optional note shown to approvers
+          # @return [Organizations::JoinRequest]
+          #
+          # NOTE: `max_organizations` deliberately does NOT apply here — that
+          # setting caps orgs a user can OWN. Hosts wanting to cap plain
+          # memberships should check before approving (see README).
+          def request_to_join!(organization, message: nil)
+            existing = pending_join_request_for(organization)
+            return existing if existing
+
+            # A member doesn't need to request — surface their (approved)
+            # state instead of creating a nonsense pending row.
+            existing_membership = memberships.find_by(organization_id: organization.id)
+            if existing_membership
+              raise Organizations::JoinRequestAlreadyDecided,
+                    Organizations.t(:"errors.join_request_already_member")
+            end
+
+            # SAVEPOINT: the RecordNotUnique rescue below must stay reachable
+            # when a HOST wraps this call in its own transaction (PostgreSQL
+            # aborted-transaction semantics — see JoinRequest#create_membership!).
+            request = ActiveRecord::Base.transaction(requires_new: true) do
+              organization.join_requests.create!(user: self, message: message)
+            end
+
+            Callbacks.dispatch(
+              :join_request_created,
+              organization: organization,
+              user: self,
+              join_request: request
+            )
+
+            request
+          rescue ActiveRecord::RecordNotUnique
+            # Race: a concurrent request slipped past the pre-check.
+            pending_join_request_for(organization) ||
+              raise(Organizations::JoinRequestError, Organizations.t(:"errors.join_request_create_failed"))
+          end
+
+          # This user's open request for an organization, if any
+          # @param organization [Organizations::Organization]
+          # @return [Organizations::JoinRequest, nil]
+          def pending_join_request_for(organization)
+            organization_join_requests.pending.find_by(organization_id: organization.id)
+          end
+
           # Extension seam for personal organization creation.
           # Override this method in your User model to implement custom logic.
           #
@@ -553,7 +641,7 @@ module Organizations
           def prevent_deletion_while_owning_organizations
             return unless memberships.where(role: "owner").exists?
 
-            errors.add(:base, "Cannot delete a user who still owns organizations. Transfer ownership or delete those organizations first.")
+            errors.add(:base, Organizations.t(:"errors.cannot_delete_user_owns_organizations"))
             throw(:abort)
           end
         end