organizations 0.4.2 → 0.5.0

data/lib/organizations/models/membership.rb

@@ -15,9 +15,23 @@ module Organizations
   #   membership.promote_to!(:admin)
   #   membership.demote_to!(:member)
   #
+  # ⚠️ THE MEMBERSHIP GATE IS NOT ON THIS MODEL. `on_member_joining` (the
+  # strict, vetoing host callback — seat limits, member caps) is dispatched
+  # by the SANCTIONED join paths: Organization#add_member!,
+  # Invitation#accept!, and JoinRequest#approve! (which covers codes,
+  # domains, allowlists, and the account-email shortcut). A direct
+  # `Membership.create!` bypasses the gate entirely — that's deliberate for
+  # ops/console/test usage (Organization.create_with_owner!, TestHelpers),
+  # but NEVER create memberships directly from request-cycle product code,
+  # and any NEW join path added to the gem must dispatch the gate itself
+  # (see Configuration#on_member_joining).
   class Membership < ActiveRecord::Base
     self.table_name = "organizations_memberships"
 
+    # metadata_flag macro for typed boolean toggles over the metadata bag —
+    # see Organizations::MetadataFlags.
+    extend Organizations::MetadataFlags
+
     # Error raised when trying to demote below current role
     class CannotDemoteOwner < Organizations::Error; end
     class CannotPromoteToOwner < Organizations::Error; end
@@ -25,20 +39,25 @@ module Organizations
 
     # === Associations ===
 
-    belongs_to :user
+    # Explicit class_name (NOT inferred from the association name) so hosts
+    # with a differently-named account model work: config.user_class.
+    belongs_to :user, class_name: Organizations.user_class_name
     belongs_to :organization,
                class_name: "Organizations::Organization",
                inverse_of: :memberships,
                counter_cache: :memberships_count
 
     belongs_to :invited_by,
-               class_name: "User",
+               class_name: Organizations.user_class_name,
                optional: true
 
     # === Validations ===
 
     validates :role, presence: true, inclusion: { in: ->(_) { Roles::HIERARCHY.map(&:to_s) } }
-    validates :user_id, uniqueness: { scope: :organization_id, message: "is already a member of this organization" }
+    # Proc message: resolved at VALIDATION time so it follows I18n.locale —
+    # a literal string here would be frozen in whatever locale loaded first.
+    validates :user_id, uniqueness: { scope: :organization_id,
+                                      message: ->(*) { Organizations.t(:"attributes.membership_taken") } }
     validate :single_owner_per_organization, if: :owner?
 
     # === Scopes ===
@@ -71,6 +90,15 @@ module Organizations
       SQL
     }
 
+    # === Verified Joining (v0.5.0) ===
+
+    # Whether this membership was created with a proven email address
+    # (emailed-code challenge, confirmed account email, or accepted invitation)
+    # @return [Boolean]
+    def verified?
+      verified_at.present?
+    end
+
     # === Role Methods ===
 
     # Get the role as a symbol
@@ -152,11 +180,11 @@ module Organizations
 
       # Owner role is only assignable via transfer_ownership_to!
       if new_role_sym == :owner
-        raise CannotPromoteToOwner, "Cannot promote to owner. Use organization.transfer_ownership_to! instead."
+        raise CannotPromoteToOwner, Organizations.t(:"errors.cannot_promote_to_owner")
       end
 
       unless Roles.at_least?(new_role_sym, role_sym)
-        raise InvalidRoleChange, "Cannot promote to #{new_role} - it's not a higher role than #{role}"
+        raise InvalidRoleChange, Organizations.t(:"errors.promote_not_higher", new_role: new_role, role: role)
       end
 
       change_role_to!(new_role_sym, changed_by: changed_by)
@@ -173,11 +201,11 @@ module Organizations
       validate_role!(new_role_sym)
 
       if owner?
-        raise CannotDemoteOwner, "Cannot demote owner. Transfer ownership first."
+        raise CannotDemoteOwner, Organizations.t(:"errors.cannot_demote_owner")
       end
 
       unless Roles.at_least?(role_sym, new_role_sym)
-        raise InvalidRoleChange, "Cannot demote to #{new_role} - it's not a lower role than #{role}"
+        raise InvalidRoleChange, Organizations.t(:"errors.demote_not_lower", new_role: new_role, role: role)
       end
 
       change_role_to!(new_role_sym, changed_by: changed_by)
@@ -193,7 +221,7 @@ module Organizations
 
       return unless existing_owner.exists?
 
-      errors.add(:role, "owner already exists for this organization")
+      errors.add(:role, Organizations.t(:"attributes.owner_taken"))
     end
 
     def validate_role!(role)
@@ -226,3 +254,6 @@ module Organizations
     end
   end
 end
+
+# Host extension seam — see the load-hooks note in models/organization.rb.
+ActiveSupport.run_load_hooks(:organizations_membership, Organizations::Membership)

data/lib/organizations/models/organization.rb

@@ -18,6 +18,10 @@ module Organizations
   class Organization < ActiveRecord::Base
     self.table_name = "organizations_organizations"
 
+    # metadata_flag macro for typed boolean toggles over the metadata bag —
+    # see Organizations::MetadataFlags.
+    extend Organizations::MetadataFlags
+
     # Error raised when trying to perform invalid operations on organization
     class CannotRemoveOwner < Organizations::Error; end
     class CannotDemoteOwner < Organizations::Error; end
@@ -43,6 +47,32 @@ module Organizations
              inverse_of: :organization,
              dependent: :destroy
 
+    # === Verified joining (v0.5.0) ===
+
+    has_many :domains,
+             class_name: "Organizations::Domain",
+             inverse_of: :organization,
+             dependent: :destroy
+
+    # NOTE: join_requests are declared BEFORE join_codes on purpose — Rails
+    # runs dependent: :destroy cascades in DECLARATION order, and requests
+    # hold an FK to the code that created them. Requests must die first (and
+    # JoinCode#join_requests additionally nullifies for standalone deletes).
+    has_many :join_requests,
+             class_name: "Organizations::JoinRequest",
+             inverse_of: :organization,
+             dependent: :destroy
+
+    has_many :join_codes,
+             class_name: "Organizations::JoinCode",
+             inverse_of: :organization,
+             dependent: :destroy
+
+    has_many :allowlist_entries,
+             class_name: "Organizations::AllowlistEntry",
+             inverse_of: :organization,
+             dependent: :destroy
+
     # === Validations ===
 
     validates :name, presence: true
@@ -57,6 +87,44 @@ module Organizations
       joins(:memberships).where(organizations_memberships: { user_id: user.id })
     }
 
+    # === Creation ===
+
+    # Create an organization WITH its owner membership in one transaction —
+    # the ops/provisioning primitive. This is what consoles, seed scripts,
+    # and admin provisioning services should call instead of hand-rolling
+    # `create! + Membership.create!(role: "owner")` (which one production
+    # host did, accidentally skipping the organization_created callback).
+    #
+    # Differences from user.create_organization! (the SELF-SERVE path):
+    #   - no session/current-organization switching (there is no session)
+    #   - not subject to max_organizations_per_user (an ops admin may own
+    #     hundreds of provisioned orgs)
+    #   - does NOT fire on_member_joining (owner-at-creation is not
+    #     "joining" — same contract as the rest of the gate)
+    #   - DOES fire on_organization_created, like every creation path.
+    #
+    # ⚠️ Because it skips the per-user cap, do NOT expose this from
+    # request-cycle self-serve code — users creating their own organizations
+    # go through user.create_organization!. This is for consoles, seeds, and
+    # admin-vetted provisioning services.
+    #
+    # @param owner [User] becomes the owner (single-owner invariant holds)
+    # @param attributes [Hash] organization attributes (name:, plus any host columns)
+    # @return [Organizations::Organization]
+    def self.create_with_owner!(owner:, **attributes)
+      raise ArgumentError, "owner is required" unless owner
+
+      organization = nil
+      ActiveRecord::Base.transaction do
+        organization = create!(**attributes)
+        Membership.create!(user: owner, organization: organization, role: "owner")
+      end
+
+      Callbacks.dispatch(:organization_created, organization: organization, user: owner)
+
+      organization
+    end
+
     # === Member Query Methods ===
 
     # Get the owner of this organization
@@ -128,7 +196,7 @@ module Organizations
 
       # Owner role is only assignable via transfer_ownership_to! or initial creation
       if role_sym == :owner
-        raise CannotHaveMultipleOwners, "Cannot add member as owner. Use transfer_ownership_to! instead."
+        raise CannotHaveMultipleOwners, Organizations.t(:"errors.cannot_add_as_owner")
       end
 
       # Check if already a member (idempotent operation)
@@ -136,19 +204,51 @@ module Organizations
       return existing if existing
 
       membership = nil
-      ActiveRecord::Base.transaction do
+      created = false
+      # requires_new: the rescued unique-violation below must roll back only
+      # a SAVEPOINT — if a HOST wraps add_member! in its own transaction, a
+      # plain nested block joins it, and on PostgreSQL the violation would
+      # poison the host's whole transaction before the rescue could run the
+      # idempotent lookup (see JoinRequest#create_membership!).
+      ActiveRecord::Base.transaction(requires_new: true) do
+        # Re-check under the transaction (review finding): a concurrent
+        # add_member! that already inserted makes this call an idempotent
+        # no-op — resolving here (instead of falling through to the gate)
+        # keeps the gate from firing/vetoing a join that already happened,
+        # and member_joined is NOT re-dispatched for it (the concurrent
+        # creator already fired it). The RecordNotUnique rescue below stays
+        # as the backstop for the window this narrows but cannot close.
+        existing = memberships.find_by(user_id: user.id)
+        next (membership = existing) if existing
+
+        # THE MEMBERSHIP GATE (strict, vetoing, pre-persist): the one place a
+        # host can abort ANY membership creation — seat limits, member caps.
+        # Raising here rolls back cleanly (nothing persisted yet). Runs after
+        # the idempotency check on purpose: an existing member isn't joining.
+        Callbacks.dispatch(
+          :member_joining,
+          strict: true,
+          organization: self,
+          user: user,
+          role: role_sym.to_s,
+          joined_via: "manual"
+        )
+
         membership = memberships.create!(
           user: user,
           role: role_sym.to_s
         )
+        created = true
       end
 
-      Callbacks.dispatch(
-        :member_joined,
-        organization: self,
-        membership: membership,
-        user: user
-      )
+      if created
+        Callbacks.dispatch(
+          :member_joined,
+          organization: self,
+          membership: membership,
+          user: user
+        )
+      end
 
       membership
     rescue ActiveRecord::RecordNotUnique
@@ -165,7 +265,7 @@ module Organizations
       return unless membership
 
       if membership.role.to_sym == :owner
-        raise CannotRemoveOwner, "Cannot remove the organization owner. Transfer ownership first."
+        raise CannotRemoveOwner, Organizations.t(:"errors.cannot_remove_owner")
       end
 
       ActiveRecord::Base.transaction do
@@ -210,12 +310,12 @@ 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, "Cannot promote to owner. Use transfer_ownership_to! instead."
+          raise CannotHaveMultipleOwners, Organizations.t(:"errors.cannot_promote_to_owner")
         end
 
         if old_role == :owner && new_role != :owner
           # Demoting owner - not allowed directly
-          raise CannotDemoteOwner, "Cannot demote owner directly. Use transfer_ownership_to! instead."
+          raise CannotDemoteOwner, Organizations.t(:"errors.cannot_demote_owner_directly")
         end
 
         membership.update!(role: new_role.to_s)
@@ -250,16 +350,16 @@ module Organizations
         new_owner_membership = memberships.find_by(user_id: new_owner.id)
 
         unless old_owner_membership
-          raise NoOwnerPresent, "Cannot transfer ownership because organization has no owner membership"
+          raise NoOwnerPresent, Organizations.t(:"errors.transfer_no_owner")
         end
 
         unless new_owner_membership
-          raise CannotTransferToNonMember, "Cannot transfer ownership to a non-member"
+          raise CannotTransferToNonMember, Organizations.t(:"errors.transfer_to_non_member")
         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, "Cannot transfer ownership to non-admin. Promote them to admin first."
+          raise CannotTransferToNonAdmin, Organizations.t(:"errors.transfer_to_non_admin")
         end
 
         # No-op transfer to the current owner.
@@ -307,7 +407,7 @@ module Organizations
 
       # Owner role cannot be assigned via invitation - only via transfer_ownership_to!
       if role_sym == :owner
-        raise CannotInviteAsOwner, "Cannot invite as owner. Invite as admin, then use transfer_ownership_to! after they join."
+        raise CannotInviteAsOwner, Organizations.t(:"errors.invite_as_owner")
       end
 
       normalized_email = email.downcase.strip
@@ -318,7 +418,7 @@ module Organizations
 
       # Check if already a member (case-insensitive)
       if users.where("LOWER(email) = ?", normalized_email).exists?
-        raise Organizations::InvitationError, "User is already a member of this organization"
+        raise Organizations::InvitationError, Organizations.t(:"errors.invitation_already_member")
       end
 
       # Allow callback hooks to veto invitations (e.g., plan seat limits) before write.
@@ -338,7 +438,11 @@ module Organizations
       )
 
       invitation = nil
-      ActiveRecord::Base.transaction do
+      # requires_new: the rescued unique-violation must roll back only a
+      # SAVEPOINT so the method-level rescue's lookup still works when a HOST
+      # wraps this call in its own transaction (PostgreSQL poisons the whole
+      # transaction otherwise — see JoinRequest#create_membership!).
+      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
@@ -370,8 +474,186 @@ module Organizations
       invitations.pending.for_email(normalized_email).first!
     end
 
+    # === Verified Joining Methods (v0.5.0) ===
+
+    # 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
+    # @return [Domain]
+    def add_domain!(domain, membership_metadata: {})
+      domains.create!(domain: domain, membership_metadata: membership_metadata)
+    end
+
+    # Generate a shareable join code (PIN).
+    # @param label [String, nil] campaign attribution ("cafeteria poster")
+    # @param requires_verified_domain_email [Boolean] chain the emailed-code challenge ("reinforced" level)
+    # @param auto_approve [Boolean] false parks redemptions as pending requests for manual approval
+    # @param expires_at [Time, nil]
+    # @param max_uses [Integer, nil]
+    # @param created_by [User, nil]
+    # @param membership_metadata [Hash] copied onto memberships created through this code
+    # @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
+    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!(
+        label: label,
+        requires_verified_domain_email: requires_verified_domain_email,
+        auto_approve: auto_approve,
+        expires_at: expires_at,
+        max_uses: max_uses,
+        created_by_id: created_by&.id,
+        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).
+    # @param emails [Enumerable<String>]
+    # @param source [String, nil] provenance tag ("csv_2026-07")
+    # @param membership_metadata [Hash] copied onto memberships created through these entries
+    # @return [Array<AllowlistEntry>] the newly created entries
+    def import_allowlist!(emails, source: nil, membership_metadata: {})
+      Array(emails).filter_map do |email|
+        # SAVEPOINT per entry: the duplicate-skip rescue below must survive
+        # under a CALLER's transaction (real hosts wrap provisioning in one)
+        # — on PostgreSQL the first duplicate would otherwise poison the
+        # whole wrapping transaction and abort the import mid-list.
+        entry = ActiveRecord::Base.transaction(requires_new: true) do
+          allowlist_entries.create!(
+            email: email,
+            source: source,
+            membership_metadata: membership_metadata
+          )
+        end
+        entry
+      rescue ActiveRecord::RecordInvalid, ActiveRecord::RecordNotUnique => e
+        # Skip duplicates silently (idempotent import); re-raise anything else.
+        raise e unless duplicate_allowlist_error?(e)
+
+        nil
+      end
+    end
+
+    # Open join requests awaiting a decision
+    # @return [ActiveRecord::Relation<JoinRequest>]
+    def pending_join_requests
+      join_requests.pending
+    end
+
+    # Whether this organization accepts EMAIL-PROOF joining: an enrolled
+    # domain or an unclaimed roster entry (both run the same emailed-code
+    # challenge). Drives whether a join screen shows the email form.
+    # @return [Boolean]
+    def accepts_domain_joining?
+      domains.exists? || allowlist_entries.unclaimed.exists?
+    end
+
+    # Whether this organization has at least one code that can actually be
+    # redeemed right now (not revoked/expired/exhausted). Drives whether a
+    # join screen shows the code form.
+    # @return [Boolean]
+    def accepts_code_joining?
+      join_codes.active.exists?
+    end
+
+    # Whether this organization exposes any self-serve joining mechanism.
+    # NOTE (0.5.0 refinement): codes now count only while actually
+    # redeemable — an org whose every code expired or ran out no longer
+    # reads as joinable.
+    # @return [Boolean]
+    def accepts_join_requests?
+      accepts_domain_joining? || accepts_code_joining?
+    end
+
+    # Approve a join request (creates the membership). See JoinRequest#approve!.
+    # @param join_request [JoinRequest]
+    # @param approved_by [User, nil]
+    # @return [Membership]
+    def approve_join_request!(join_request, approved_by: nil)
+      ensure_join_request_belongs_here!(join_request)
+      join_request.approve!(decided_by: approved_by)
+    end
+
+    # Reject a join request. See JoinRequest#reject!.
+    # @param join_request [JoinRequest]
+    # @param rejected_by [User, nil]
+    # @param reason [String, nil]
+    # @return [JoinRequest]
+    def reject_join_request!(join_request, rejected_by: nil, reason: nil)
+      ensure_join_request_belongs_here!(join_request)
+      join_request.reject!(rejected_by: rejected_by, reason: reason)
+    end
+
+    # Zero-friction domain join for hosts with confirmed account emails
+    # (e.g. Devise :confirmable): if the user's own account email is confirmed
+    # and its domain is enrolled, the inbox was already proven at signup — no
+    # emailed code needed.
+    #
+    # @param user [User] must respond to #email; #confirmed_at gates trust
+    # @return [Membership]
+    # @raise [VerificationEmailNotEligible] when the account email's domain isn't enrolled,
+    #   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")
+      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")
+      end
+
+      matched_domain = domains.matching_email(email).first
+      unless matched_domain
+        raise VerificationEmailNotEligible, Organizations.t(:"errors.verification_email_not_eligible")
+      end
+
+      # Uniform funnel: every self-serve join goes through a JoinRequest so
+      # provenance and audit trail come for free.
+      request = join_requests.pending.find_by(user_id: user.id) || join_requests.new(user: user)
+      normalized = Organizations.configuration.normalize_verification_email(email)
+
+      ActiveRecord::Base.transaction do
+        if Membership.where(organization_id: id, verified_email_normalized: normalized).exists?
+          raise VerificationEmailAlreadyClaimed,
+                Organizations.t(:"errors.verification_email_already_claimed")
+        end
+
+        request.assign_attributes(
+          joined_via: "domain_email",
+          verification_email: email,
+          verification_email_normalized: normalized,
+          verified_at: Time.current,
+          metadata: (request.metadata || {}).merge("matched_domain_id" => matched_domain.id)
+        )
+        request.save!
+      end
+
+      request.approve!(decided_by: nil)
+    end
+
     private
 
+    def ensure_join_request_belongs_here!(join_request)
+      return if join_request.organization_id == id
+
+      raise ArgumentError, "Join request does not belong to this organization"
+    end
+
+    def duplicate_allowlist_error?(error)
+      return true if error.is_a?(ActiveRecord::RecordNotUnique)
+
+      error.is_a?(ActiveRecord::RecordInvalid) &&
+        error.record.is_a?(Organizations::AllowlistEntry) &&
+        error.record.errors.of_kind?(:email_normalized, :taken)
+    end
+
     # Defense in depth for organization-centric API usage.
     # The user-level API already checks this, but direct calls to `org.send_invite_to!`
     # must enforce membership and invite permission as well.
@@ -380,7 +662,7 @@ module Organizations
 
       unless inviter_membership
         raise Organizations::NotAMember.new(
-          "Only organization members can send invitations",
+          Organizations.t(:"errors.invite_not_a_member"),
           organization: self,
           user: inviter
         )
@@ -389,7 +671,7 @@ module Organizations
       return if Roles.has_permission?(inviter_membership.role.to_sym, :invite_members)
 
       raise Organizations::NotAuthorized.new(
-        "You don't have permission to invite members",
+        Organizations.t(:"errors.invite_not_authorized"),
         permission: :invite_members,
         organization: self,
         user: inviter
@@ -432,3 +714,19 @@ module Organizations
     end
   end
 end
+
+# HOST EXTENSION SEAM (pay-gem style load hooks): fires on EVERY load of this
+# file — including Zeitwerk reloads via the app/models shims — so extensions
+# registered with ActiveSupport.on_load survive code reloading in development.
+# A bare `Organizations::Organization.class_eval` in an initializer runs ONCE
+# and evaporates on the first reload (the shim `load`s a fresh class object);
+# a `to_prepare` block works but is one shared basket — one bad constant in
+# it silently kills every extension after it. Load hooks are per-model and
+# re-run automatically. Register in an initializer:
+#
+#   ActiveSupport.on_load(:organizations_organization) do
+#     include OrganizationExtensions   # `self` is Organizations::Organization
+#   end
+#
+# Docs: https://api.rubyonrails.org/classes/ActiveSupport/LazyLoadHooks.html
+ActiveSupport.run_load_hooks(:organizations_organization, Organizations::Organization)