organizations 0.4.3 → 0.6.0

data/lib/organizations/models/domain.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Organizations
+  # An email domain owned/claimed by an organization, used for verified joining.
+  #
+  # A user who proves control of an inbox under one of the organization's
+  # domains (emailed code, or an already-confirmed account email — see
+  # Organization#join_with_account_email!) is considered a verified member.
+  #
+  # Matching is EXACT and dot-boundary safe: "alumnos.urjc.es" and "urjc.es"
+  # are two different domains and must both be enrolled if both should join.
+  # This is deliberate — subdomains often carry different member semantics
+  # (e.g. students vs employees), and suffix matching would collapse them.
+  # It also neutralizes lookalike attacks ("urjc.es.evil.com" never equals
+  # "urjc.es").
+  #
+  # `membership_metadata` is copied onto memberships created through this
+  # domain (see JoinRequest#approve!) — hosts use it for cohort tags like
+  # { "member_kind" => "student" } without the gem interpreting the contents.
+  #
+  # @example
+  #   org.add_domain!("inizio.com")
+  #   org.add_domain!("alumnos.urjc.es", membership_metadata: { member_kind: "student" })
+  #   Organizations::Domain.matching_email("j.doe@inizio.com") # => [domain]
+  #
+  class Domain < ActiveRecord::Base
+    self.table_name = "organizations_domains"
+
+    # === Associations ===
+
+    belongs_to :organization,
+               class_name: "Organizations::Organization",
+               inverse_of: :domains
+
+    # === Validations ===
+
+    validates :domain, presence: true, uniqueness: { scope: :organization_id }
+    validate :domain_shape
+
+    # === Callbacks ===
+
+    before_validation :normalize_domain
+
+    # === Scopes ===
+
+    # All domain rows (across organizations) matching an email's domain.
+    # Returns none for emails whose domain can't be safely extracted
+    # (multi-@ evasion shapes, blanks).
+    scope :matching_email, lambda { |email|
+      extracted = EmailNormalizer.domain_of(email)
+      extracted ? where(domain: extracted) : none
+    }
+
+    # === Matching ===
+
+    # Whether an email address belongs to this domain (exact match).
+    # @param email [String]
+    # @return [Boolean]
+    def matches_email?(email)
+      extracted = EmailNormalizer.domain_of(email)
+      extracted.present? && extracted == domain
+    end
+
+    private
+
+    def normalize_domain
+      return if domain.blank?
+
+      self.domain = domain.to_s.strip.downcase.delete_prefix("@").chomp(".")
+    end
+
+    # Pragmatic hostname shape check: lowercase labels, at least one dot,
+    # no whitespace or "@". (IDN domains should be enrolled in punycode form.)
+    def domain_shape
+      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"))
+      end
+    end
+  end
+end
+
+# Host extension seam — see the load-hooks note in models/organization.rb.
+ActiveSupport.run_load_hooks(:organizations_domain, Organizations::Domain)

data/lib/organizations/models/invitation.rb

@@ -28,7 +28,7 @@ module Organizations
 
     # Optional because inviter can be deleted (dependent: :nullify on User)
     belongs_to :invited_by,
-               class_name: "User",
+               class_name: Organizations.user_class_name,
                optional: true
 
     # Alias for invited_by (semantic convenience as per README)
@@ -38,7 +38,9 @@ module Organizations
 
     validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
     validates :token, presence: true, uniqueness: true
-    validates :role, presence: true, inclusion: { in: ->(_) { Roles::HIERARCHY.map(&:to_s) } }
+    validates :role, presence: true
+    validates :role, inclusion: { in: ->(_) { Roles.valid_roles.map(&:to_s) } },
+                     if: -> { new_record? || will_save_change_to_role? }
 
     # Validate only one non-accepted invitation per email per organization
     # This matches the DB constraint (accepted_at IS NULL), not expiry status
@@ -131,7 +133,7 @@ module Organizations
       # Validate email matches at model level (security)
       unless skip_email_validation
         if accepting_user.respond_to?(:email) && !for_email?(accepting_user.email)
-          raise EmailMismatch, "This invitation was sent to a different email address"
+          raise EmailMismatch, Organizations.t(:"errors.invitation_email_mismatch")
         end
       end
 
@@ -148,16 +150,16 @@ module Organizations
           existing_membership = organization.memberships.find_by(user_id: accepting_user.id)
           return existing_membership if existing_membership
 
-          raise InvitationAlreadyAccepted, "This invitation has already been accepted"
+          raise InvitationAlreadyAccepted, Organizations.t(:"errors.invitation_already_accepted")
         end
 
         if expired?
-          raise InvitationExpired, "This invitation has expired"
+          raise InvitationExpired, Organizations.t(:"errors.invitation_expired")
         end
 
         # Owner role cannot be assigned via invitation (defense in depth)
         if role.to_sym == :owner
-          raise CannotAcceptAsOwner, "Cannot accept invitation as owner. Invite as admin, then use transfer_ownership_to! after joining."
+          raise CannotAcceptAsOwner, Organizations.t(:"errors.invitation_accept_as_owner")
         end
 
         # Check if user is already a member (race condition from another invitation)
@@ -167,14 +169,8 @@ module Organizations
           return existing_membership
         end
 
-        # Create the membership
-        # Use invited_by_id instead of invited_by to avoid Rails class reloading issues
-        # (AssociationTypeMismatch when User class is reloaded in development)
-        membership = organization.memberships.create!(
-          user: accepting_user,
-          role: role,
-          invited_by_id: invited_by_id
-        )
+        # Create the membership (with verified-joining provenance)
+        membership = create_membership_for!(accepting_user, skip_email_validation)
 
         # Mark invitation as accepted
         update!(accepted_at: Time.current)
@@ -198,7 +194,7 @@ module Organizations
         lock!
 
         if accepted?
-          raise InvitationAlreadyAccepted, "Cannot resend an accepted invitation"
+          raise InvitationAlreadyAccepted, Organizations.t(:"errors.invitation_cannot_resend_accepted")
         end
 
         update!(
@@ -216,7 +212,10 @@ module Organizations
     # @return [String]
     def acceptance_url(base_url: nil)
       base = base_url || default_base_url
-      "#{base}/invitations/#{token}"
+      # Organizations.engine_mount_path keeps this correct for hosts that
+      # mount the engine somewhere other than root ("/orgs/invitations/…") —
+      # a hardcoded "/invitations/…" silently 404'd for them.
+      "#{base}#{Organizations.engine_mount_path}/invitations/#{token}"
     end
 
     # Check if invitation matches a specific email
@@ -228,6 +227,94 @@ module Organizations
 
     private
 
+    # Create the membership for an acceptance.
+    # Uses invited_by_id instead of invited_by to avoid Rails class reloading
+    # issues (AssociationTypeMismatch when User is reloaded in development).
+    #
+    # Verified-joining provenance (v0.5.0): accepting the emailed token is
+    # proof of control of the invited address, so the membership records it
+    # as a verified email — UNLESS the acceptance bypassed the email match
+    # (skip_email_validation with a different account email), where no inbox
+    # proof exists. If the address was already claimed by another membership
+    # in this org (rare recycled-address edge), the membership is still
+    # created, just without the verified-email stamp.
+    def create_membership_for!(accepting_user, skip_email_validation)
+      # THE MEMBERSHIP GATE (strict, vetoing, pre-persist) — see
+      # Configuration#on_member_joining. Runs inside accept!'s locked
+      # transaction: a veto rolls back accepted_at too, so the invitation
+      # stays pending and can be accepted again once the host unblocks.
+      Callbacks.dispatch(
+        :member_joining,
+        strict: true,
+        organization: organization,
+        user: accepting_user,
+        role: role,
+        joined_via: "invited",
+        invitation: self
+      )
+
+      # SAVEPOINT (requires_new): rescued unique-violation inside accept!'s
+      # transaction — see JoinRequest#create_membership! for the PostgreSQL
+      # aborted-transaction rationale (proven by the PG leg of the suite).
+      ActiveRecord::Base.transaction(requires_new: true) do
+        organization.memberships.create!(
+          **base_membership_attributes(accepting_user),
+          **verified_email_attributes_for(accepting_user, skip_email_validation)
+        )
+      end
+    rescue ActiveRecord::RecordNotUnique
+      # Two unique indexes can fire here (same disambiguation as
+      # JoinRequest#create_membership!):
+      # 1. (user, org) — another acceptance/join path just made them a member:
+      #    reuse it (invitations to one address aren't normalization-aware, so
+      #    two plus-variant invitations can race).
+      # 2. (org, verified_email_normalized) — the address was claimed between
+      #    our pre-check and the INSERT: degrade gracefully by creating the
+      #    membership WITHOUT the verified-email stamp. Acceptance never breaks.
+      existing = organization.memberships.find_by(user_id: accepting_user.id)
+      return existing if existing
+
+      # Its own savepoint too: this fallback INSERT can itself lose the
+      # (user, org) race, and accept!'s rescue must stay reachable on PG.
+      ActiveRecord::Base.transaction(requires_new: true) do
+        organization.memberships.create!(**base_membership_attributes(accepting_user))
+      end
+    end
+
+    def base_membership_attributes(accepting_user)
+      {
+        user: accepting_user,
+        role: role,
+        invited_by_id: invited_by_id,
+        joined_via: "invited",
+        metadata: membership_metadata.is_a?(Hash) ? membership_metadata : {}
+      }
+    end
+
+    # Provenance attributes for the membership created by this acceptance.
+    # See create_membership_for! for the trust rules.
+    def verified_email_attributes_for(accepting_user, skip_email_validation)
+      email_proven =
+        !skip_email_validation ||
+        (accepting_user.respond_to?(:email) && for_email?(accepting_user.email))
+
+      return {} unless email_proven
+
+      normalized = Organizations.configuration.normalize_verification_email(email)
+
+      already_claimed = Membership
+                        .where(organization_id: organization_id, verified_email_normalized: normalized)
+                        .exists?
+
+      return {} if already_claimed
+
+      {
+        verified_email: email,
+        verified_email_normalized: normalized,
+        verified_at: Time.current
+      }
+    end
+
     def normalize_email
       self.email = email.to_s.downcase.strip if email.present?
     end
@@ -265,7 +352,7 @@ module Organizations
                            .exists?
 
       if existing
-        errors.add(:email, "has already been invited to this organization")
+        errors.add(:email, Organizations.t(:"attributes.invitation_taken"))
       end
     end
 
@@ -283,7 +370,7 @@ module Organizations
     end
 
     def default_base_url
-      if defined?(Rails) && Rails.application&.routes
+      if Organizations.full_rails_app? && Rails.application.routes
         Rails.application.routes.url_helpers.root_url.chomp("/")
       else
         ""
@@ -293,3 +380,6 @@ module Organizations
     end
   end
 end
+
+# Host extension seam — see the load-hooks note in models/organization.rb.
+ActiveSupport.run_load_hooks(:organizations_invitation, Organizations::Invitation)

data/lib/organizations/models/join_code.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+module Organizations
+  # A shareable join code ("PIN") for an organization — the classroom/Slack
+  # style joining mechanism. Codes are globally unique so redemption needs no
+  # organization context (QR posters, links, plain typing).
+  #
+  # Per-code knobs:
+  # - `requires_verified_domain_email` — redemption additionally requires the
+  #   emailed-code challenge against one of the org's domains (the "reinforced"
+  #   level). Per-code (not per-org) so one org can run both levels at once.
+  # - `auto_approve` — false means redemption parks a pending JoinRequest for
+  #   manual approval instead of granting membership immediately.
+  # - `expires_at`, `max_uses`, `revoked_at` — abuse containment. Rotation is
+  #   revoke + generate a new code (history preserved for audit).
+  # - `label` — campaign attribution ("cafeteria poster" vs "newsletter").
+  #
+  # `membership_metadata` is copied onto memberships created through this code.
+  #
+  # @example
+  #   code = org.generate_join_code!(label: "poster", requires_verified_domain_email: true)
+  #   Organizations::JoinCode.redeem(code.code, user: user)
+  #   # => Membership (instant join) or JoinRequest (challenge/approval pending)
+  #
+  class JoinCode < ActiveRecord::Base
+    self.table_name = "organizations_join_codes"
+
+    # Ambiguity-free alphabet (no I/L/O/0/1 lookalikes) — same idea as
+    # user-facing referral codes: survives posters, print, and dictation.
+    CODE_ALPHABET = "ABCDEFGHJKMNPQRSTUVWXYZ23456789"
+    DEFAULT_CODE_LENGTH = 8
+
+    # === Associations ===
+
+    belongs_to :organization,
+               class_name: "Organizations::Organization",
+               inverse_of: :join_codes
+
+    belongs_to :created_by,
+               class_name: Organizations.user_class_name,
+               optional: true
+
+    # Requests OUTLIVE the codes that created them (they are the join audit
+    # trail; joined_via/metadata are already snapshotted) — deleting a code
+    # nullifies the linkage instead of cascading or violating the FK.
+    # Prefer revoke! over destroy for rotation; destroy stays safe regardless.
+    has_many :join_requests,
+             class_name: "Organizations::JoinRequest",
+             inverse_of: :join_code,
+             dependent: :nullify
+
+    # === Validations ===
+
+    validates :code, presence: true, uniqueness: true
+    validates :max_uses, numericality: { only_integer: true, greater_than: 0, allow_nil: true }
+    validates :uses_count, numericality: { only_integer: true, greater_than_or_equal_to: 0 }
+
+    # === Callbacks ===
+
+    before_validation :normalize_code
+    before_validation :generate_code, on: :create, if: -> { code.blank? }
+
+    # === Scopes ===
+
+    scope :not_revoked, -> { where(revoked_at: nil) }
+
+    # Codes that can actually be redeemed right now — the SQL twin of
+    # #active? (not revoked, not expired, not exhausted). Powers
+    # Organization#accepts_code_joining? without loading rows.
+    scope :active, lambda {
+      not_revoked
+        .where("expires_at IS NULL OR expires_at > ?", Time.current)
+        .where("max_uses IS NULL OR uses_count < max_uses")
+    }
+
+    # === Status ===
+
+    # @return [Boolean]
+    def revoked?
+      revoked_at.present?
+    end
+
+    # @return [Boolean]
+    def expired?
+      expires_at.present? && expires_at <= Time.current
+    end
+
+    # @return [Boolean]
+    def exhausted?
+      max_uses.present? && uses_count >= max_uses
+    end
+
+    # @return [Boolean]
+    def active?
+      !revoked? && !expired? && !exhausted?
+    end
+
+    # @return [Symbol] :active, :revoked, :expired, or :exhausted
+    def status
+      return :revoked if revoked?
+      return :expired if expired?
+      return :exhausted if exhausted?
+
+      :active
+    end
+
+    # Revoke this code (rotation = revoke + generate a new one). Idempotent.
+    # @return [self]
+    def revoke!
+      return self if revoked?
+
+      with_lock do
+        break if revoked?
+
+        update!(revoked_at: Time.current)
+      end
+
+      self
+    end
+
+    # Presentation form, grouped for readability: "7FHK2MPX" => "7FHK-2MPX".
+    # Storage and matching always use the bare form.
+    # @return [String]
+    def display_code
+      code.to_s.scan(/.{1,4}/).join("-")
+    end
+
+    # === Redemption ===
+
+    # Redeem a code for a user.
+    # @param code [String] the code as typed (case/hyphen/space insensitive)
+    # @param user [User] the redeeming user
+    # @return [Membership] when the code grants instant membership (or the
+    #   user is already a member)
+    # @return [JoinRequest] when a challenge or manual approval is still needed
+    # @raise [JoinCodeInvalid] for unknown, revoked, or expired codes
+    # @raise [JoinCodeExhausted] when max_uses is spent
+    def self.redeem(code, user:)
+      normalized = normalize(code)
+      raise JoinCodeInvalid, Organizations.t(:"errors.join_code_invalid") if normalized.blank?
+
+      join_code = find_by(code: normalized)
+      raise JoinCodeInvalid, Organizations.t(:"errors.join_code_invalid") unless join_code
+
+      join_code.redeem!(user: user)
+    end
+
+    # Instance-level redemption. See .redeem for semantics.
+    def redeem!(user:)
+      raise ArgumentError, "user is required" unless user
+
+      outcome = nil
+
+      ActiveRecord::Base.transaction do
+        # Lock the code row: uses_count accounting and the max_uses cap must
+        # be race-safe (two concurrent redemptions of a max_uses: 1 code must
+        # yield exactly one success).
+        lock!
+        ensure_redeemable!
+
+        # Already a member — idempotent no-op that does NOT consume a use.
+        existing_membership = organization.memberships.find_by(user_id: user.id)
+        if existing_membership
+          outcome = existing_membership
+          raise ActiveRecord::Rollback # nothing to persist
+        end
+
+        outcome = attach_request!(user)
+      end
+
+      # Instant-join path: no email challenge required and auto-approve on.
+      # Approval runs AFTER the redemption transaction commits so the
+      # member_joined/join_request_approved callbacks never fire for a
+      # transaction that could still roll back. If approval fails, the
+      # pending request survives — a safe, resumable state.
+      return outcome unless outcome.is_a?(JoinRequest)
+      return outcome if requires_verified_domain_email? || !auto_approve?
+
+      outcome.approve!(decided_by: nil)
+    end
+
+    # Normalize user input to storage form: uppercase, strip separators.
+    # @param code [String, nil]
+    # @return [String]
+    def self.normalize(code)
+      code.to_s.upcase.gsub(/[\s-]/, "")
+    end
+
+    private
+
+    def ensure_redeemable!
+      raise JoinCodeInvalid, Organizations.t(:"errors.join_code_invalid") if revoked? || expired?
+      raise JoinCodeExhausted, Organizations.t(:"errors.join_code_exhausted") if exhausted?
+    end
+
+    # Attach this code to the user's open request (creating one if needed),
+    # consuming a use — except for idempotent re-redemptions of the same code.
+    def attach_request!(user)
+      request = pending_request_for(user)
+
+      # Same user re-redeeming the same code: idempotent, no extra use.
+      return request if request.persisted? && request.join_code_id == id
+
+      request.join_code = self
+      request.joined_via = "code"
+      request.save!
+      increment!(:uses_count)
+      request
+    end
+
+    # Find or build this user's open request for the organization.
+    # Reuses an existing pending request (partial unique index: one pending
+    # request per user per org) so re-entry via a different mechanism upgrades
+    # the same request instead of exploding.
+    def pending_request_for(user)
+      organization.join_requests.pending.find_by(user_id: user.id) ||
+        organization.join_requests.new(user: user)
+    end
+
+    def normalize_code
+      self.code = self.class.normalize(code) if code.present?
+    end
+
+    def generate_code
+      generator = Organizations.configuration.join_code_generator
+
+      self.code = loop do
+        candidate =
+          if generator.respond_to?(:call)
+            self.class.normalize(generator.call)
+          else
+            Array.new(DEFAULT_CODE_LENGTH) { CODE_ALPHABET[SecureRandom.random_number(CODE_ALPHABET.length)] }.join
+          end
+
+        break candidate unless self.class.exists?(code: candidate)
+      end
+    end
+  end
+end
+
+# Host extension seam — see the load-hooks note in models/organization.rb.
+ActiveSupport.run_load_hooks(:organizations_join_code, Organizations::JoinCode)