organizations 0.4.3 → 0.5.0

data/lib/organizations/configuration.rb

@@ -26,6 +26,22 @@ module Organizations
   #
   class Configuration
     # === Authentication ===
+    # Class name of the host's user model (default: "User").
+    #
+    # Set this when your account model is named differently:
+    #   config.user_class = "Account"
+    #
+    # ⚠️ Configure this BEFORE the gem's models are first referenced: the
+    # class name is read when each model class body executes. In Rails this
+    # is automatic (initializers run before Zeitwerk autoloads the models);
+    # in plain-Ruby usage, call Organizations.configure before touching
+    # Organizations::Organization & friends.
+    #
+    # ⚠️ The install generator's migrations reference `to_table: :users` —
+    # if your user model uses a different table, adjust the generated
+    # migration accordingly (see the comment inside the migration template).
+    attr_accessor :user_class
+
     # Method that returns the current user (default: :current_user)
     attr_accessor :current_user_method
 
@@ -81,6 +97,41 @@ module Organizations
     # Custom mailer for invitations (class name as string)
     attr_accessor :invitation_mailer
 
+    # === Verified Joining ===
+    # Custom mailer for email-verification codes (class name as string)
+    attr_accessor :verification_mailer
+
+    # How long an emailed verification code stays valid.
+    # Must be a Duration/Numeric — codes always expire (OTP hygiene).
+    attr_accessor :verification_code_ttl
+
+    # Maximum wrong-code attempts per challenge before it locks
+    attr_accessor :verification_max_attempts
+
+    # Minimum time between (re)sends of a verification code for one request
+    attr_accessor :verification_resend_interval
+
+    # Maximum number of code sends per join request
+    attr_accessor :verification_max_sends
+
+    # Custom email normalizer for the verified_email uniqueness invariant.
+    # nil = use Organizations::EmailNormalizer (downcase + strip + drop +tag).
+    # Can be a Proc/Lambda: ->(email) { ... } returning the normalized string.
+    attr_accessor :verification_email_normalizer
+
+    # Allow Organization#join_with_account_email! to trust a host user's
+    # already-confirmed account email (e.g. Devise :confirmable) as proof of
+    # inbox control, skipping the emailed code when the domain matches.
+    attr_accessor :trust_confirmed_account_email
+
+    # How long join requests stay pending before they read as expired
+    # (derived status, like invitations). nil = never expire.
+    attr_accessor :join_request_expiry
+
+    # Custom join code generator. nil = built-in 8-char ambiguity-free code.
+    # Can be a Proc/Lambda: -> { ... } returning the code string.
+    attr_accessor :join_code_generator
+
     # === Limits ===
     # Maximum organizations a user can own (nil = unlimited)
     attr_accessor :max_organizations_per_user
@@ -132,6 +183,38 @@ module Organizations
     attr_accessor :additional_organization_params
 
     # === Engine configuration ===
+
+    # Which engine route groups to draw (devise_for-style skip/only, see
+    # https://rubydoc.info/github/heartcombo/devise/main/ActionDispatch/Routing/Mapper#devise_for-instance_method
+    # for the pattern precedent). nil (default) draws everything.
+    #
+    #   config.engine_routes = { except: [:organizations] } # no org CRUD
+    #   config.engine_routes = { only: [:switching, :public_invitations] }
+    #
+    # Groups: :switching (POST /organizations/switch/:id), :organizations
+    # (org CRUD), :memberships, :invitations (authenticated management),
+    # :public_invitations (token acceptance pages).
+    #
+    # Why this exists: hosts that keep the models but not the whole engine
+    # UI (e.g. an app where org creation is admin-vetted) previously had to
+    # SHADOW engine routes with redirects declared before the mount — a
+    # route-order-load-bearing hack that actually bit one production host
+    # (the engine's resources :organizations swallowed an app route as :id).
+    # Declare what you want instead.
+    attr_reader :engine_routes
+
+    ENGINE_ROUTE_GROUPS = %i[switching organizations memberships invitations public_invitations].freeze
+
+    def engine_routes=(value)
+      @engine_routes = value.nil? ? nil : normalize_engine_routes(value)
+    end
+
+    # The resolved set of enabled groups.
+    # @return [Array<Symbol>]
+    def engine_route_groups
+      @engine_routes || ENGINE_ROUTE_GROUPS
+    end
+
     # Base controller for authenticated routes (default: ::ApplicationController)
     attr_accessor :parent_controller
 
@@ -147,6 +230,14 @@ module Organizations
     # Can be nil (use controller default), String, or Symbol
     attr_accessor :public_controller_layout
 
+    # Host helper modules to mix into the PUBLIC engine controller — it
+    # inherits ActionController::Base (not the host ApplicationController),
+    # so host layouts rendered by public pages need their helper modules
+    # declared here. Array of module names (Strings, constantized lazily at
+    # controller load — safe to set in an initializer) or Modules.
+    # @example config.public_controller_helpers = ["ApplicationHelper", "PageHelper"]
+    attr_accessor :public_controller_helpers
+
     # === Handlers (blocks) ===
     # @private - stored handler blocks
     attr_reader :unauthorized_handler, :no_organization_handler
@@ -155,10 +246,15 @@ module Organizations
     # @private - stored callback blocks
     attr_reader :on_organization_created_callback,
                 :on_member_invited_callback,
+                :on_member_joining_callback,
                 :on_member_joined_callback,
                 :on_member_removed_callback,
                 :on_role_changed_callback,
-                :on_ownership_transferred_callback
+                :on_ownership_transferred_callback,
+                :on_join_request_created_callback,
+                :on_join_request_approved_callback,
+                :on_join_request_rejected_callback,
+                :on_verification_delivery_failed_callback
 
     # === Custom Roles ===
     # @private - custom roles definition
@@ -166,6 +262,7 @@ module Organizations
 
     def initialize
       # Authentication defaults
+      @user_class = "User"
       @current_user_method = :current_user
       @authenticate_user_method = :authenticate_user!
 
@@ -178,6 +275,17 @@ module Organizations
       @default_invitation_role = :member
       @invitation_mailer = "Organizations::InvitationMailer"
 
+      # Verified joining defaults
+      @verification_mailer = "Organizations::VerificationMailer"
+      @verification_code_ttl = 15.minutes
+      @verification_max_attempts = 5
+      @verification_resend_interval = 60.seconds
+      @verification_max_sends = 5
+      @verification_email_normalizer = nil
+      @trust_confirmed_account_email = true
+      @join_request_expiry = 30.days
+      @join_code_generator = nil
+
       # Limits
       @max_organizations_per_user = nil
 
@@ -202,10 +310,12 @@ module Organizations
       @additional_organization_params = []
 
       # Engine
+      @engine_routes = nil
       @parent_controller = "::ApplicationController"
       @public_controller = "ActionController::Base"
       @authenticated_controller_layout = nil
       @public_controller_layout = nil
+      @public_controller_helpers = []
 
       # Handlers (nil by default - use default behavior)
       @unauthorized_handler = nil
@@ -214,10 +324,15 @@ module Organizations
       # Callbacks (nil by default - no-op)
       @on_organization_created_callback = nil
       @on_member_invited_callback = nil
+      @on_member_joining_callback = nil
       @on_member_joined_callback = nil
       @on_member_removed_callback = nil
       @on_role_changed_callback = nil
       @on_ownership_transferred_callback = nil
+      @on_join_request_created_callback = nil
+      @on_join_request_approved_callback = nil
+      @on_join_request_rejected_callback = nil
+      @on_verification_delivery_failed_callback = nil
 
       # Custom roles
       @custom_roles_definition = nil
@@ -267,6 +382,37 @@ module Organizations
       @on_member_invited_callback = block if block_given?
     end
 
+    # THE MEMBERSHIP GATE — called STRICTLY, inside the creating transaction,
+    # immediately BEFORE any non-owner membership row is inserted, on EVERY
+    # join path: add_member!, invitation acceptance, join-request approval
+    # (which covers join codes, domain-email verification, allowlists, and
+    # join_with_account_email!). Raise Organizations::MembershipVetoed (or any
+    # error) to veto: the transaction rolls back cleanly — no membership, join
+    # requests stay pending (resumable), invitations stay unaccepted.
+    #
+    # This is where hard limits belong (plan seat caps, per-org member caps,
+    # compliance holds). Unlike on_member_joined and the other after-callbacks
+    # (error-isolated by design), this one CAN and SHOULD abort the operation.
+    # It deliberately does NOT fire for owner memberships created with the
+    # organization itself (creating your own org is not "joining"), nor for
+    # idempotent already-a-member paths, nor for role changes.
+    #
+    # @yield [context] Block to execute (raise to veto)
+    # @yieldparam context [CallbackContext] organization, user, role,
+    #   joined_via, and the instrument (invitation/join_request) when one applies
+    #
+    # @example Enforce plan seat limits on every join path (pricing_plans)
+    #   config.on_member_joining do |ctx|
+    #     limit = ctx.organization.current_plan&.limit_for(:team_members)
+    #     if limit && ctx.organization.member_count >= limit
+    #       raise Organizations::MembershipVetoed,
+    #             "This organization has reached its plan's member limit."
+    #     end
+    #   end
+    def on_member_joining(&block)
+      @on_member_joining_callback = block if block_given?
+    end
+
     # Called when a member joins (invitation accepted)
     # @yield [context] Block to execute
     # @yieldparam context [CallbackContext] Context with organization, membership, user
@@ -295,6 +441,41 @@ module Organizations
       @on_ownership_transferred_callback = block if block_given?
     end
 
+    # Called when a join request is created (request-to-join workflow)
+    # @yield [context] Block to execute
+    # @yieldparam context [CallbackContext] Context with organization, user, join_request
+    def on_join_request_created(&block)
+      @on_join_request_created_callback = block if block_given?
+    end
+
+    # Called when a join request is approved (manually or auto-approved).
+    # NOTE: like all after-callbacks, errors here are isolated — hosts must
+    # enforce hard caps (e.g. member limits) BEFORE approving, in their own code.
+    # @yield [context] Block to execute
+    # @yieldparam context [CallbackContext] Context with organization, user, join_request, membership, decided_by (nil for auto-approvals)
+    def on_join_request_approved(&block)
+      @on_join_request_approved_callback = block if block_given?
+    end
+
+    # Called when a join request is rejected
+    # @yield [context] Block to execute
+    # @yieldparam context [CallbackContext] Context with organization, user, join_request, decided_by
+    def on_join_request_rejected(&block)
+      @on_join_request_rejected_callback = block if block_given?
+    end
+
+    # Called when a verification-code email FAILS to enqueue/deliver.
+    # The gem already rolls the challenge's throttle bookkeeping back (so the
+    # user can retry immediately) — this hook is the host's observability
+    # seam: report to your error tracker (Rails.error, Sentry, …) so silent
+    # mail outages don't strand joiners.
+    # @yield [context] Block to execute
+    # @yieldparam context [CallbackContext] organization, user, join_request,
+    #   metadata: { "error_class" =>, "error_message" => }
+    def on_verification_delivery_failed(&block)
+      @on_verification_delivery_failed_callback = block if block_given?
+    end
+
     # === Roles Configuration ===
 
     # Define custom roles with permissions
@@ -319,6 +500,16 @@ module Organizations
       end
     end
 
+    # Normalize an email through the configured (or default) normalizer
+    # @param email [String, nil]
+    # @return [String] normalized email
+    def normalize_verification_email(email)
+      normalizer = @verification_email_normalizer
+      return normalizer.call(email).to_s if normalizer.respond_to?(:call)
+
+      EmailNormalizer.normalize(email)
+    end
+
     # Resolve the default organization name for a user
     # @param user [Object] The user object
     # @return [String] The organization name
@@ -338,6 +529,7 @@ module Organizations
     def validate!
       validate_authentication_methods!
       validate_invitation_settings!
+      validate_verification_settings!
       validate_limits!
       validate_invitation_redirects!
       validate_no_organization_messages!
@@ -348,6 +540,10 @@ module Organizations
     private
 
     def validate_authentication_methods!
+      unless @user_class.is_a?(String) && @user_class.present?
+        raise ConfigurationError, "user_class must be a non-empty String (e.g. \"User\")"
+      end
+
       unless @current_user_method.is_a?(Symbol)
         raise ConfigurationError, "current_user_method must be a Symbol"
       end
@@ -367,6 +563,45 @@ module Organizations
       end
     end
 
+    def validate_verification_settings!
+      validate_duration_option!(@verification_code_ttl, "verification_code_ttl", "15.minutes")
+      validate_duration_option!(@verification_resend_interval, "verification_resend_interval", "60.seconds")
+      validate_positive_integer_option!(@verification_max_attempts, "verification_max_attempts")
+      validate_positive_integer_option!(@verification_max_sends, "verification_max_sends")
+      validate_callable_option!(@verification_email_normalizer, "verification_email_normalizer")
+      validate_callable_option!(@join_code_generator, "join_code_generator")
+
+      unless [true, false].include?(@trust_confirmed_account_email)
+        raise ConfigurationError, "trust_confirmed_account_email must be true or false"
+      end
+
+      return if @join_request_expiry.nil? || duration_like?(@join_request_expiry)
+
+      raise ConfigurationError, "join_request_expiry must be a Duration (e.g., 30.days), Numeric, or nil (never expire)"
+    end
+
+    def duration_like?(value)
+      value.is_a?(ActiveSupport::Duration) || value.is_a?(Numeric)
+    end
+
+    def validate_duration_option!(value, option_name, example)
+      return if duration_like?(value)
+
+      raise ConfigurationError, "#{option_name} must be a Duration (e.g., #{example}) or Numeric"
+    end
+
+    def validate_positive_integer_option!(value, option_name)
+      return if value.is_a?(Integer) && value >= 1
+
+      raise ConfigurationError, "#{option_name} must be an Integer of at least 1"
+    end
+
+    def validate_callable_option!(value, option_name)
+      return if value.nil? || value.respond_to?(:call)
+
+      raise ConfigurationError, "#{option_name} must be nil or callable (Proc/Lambda)"
+    end
+
     def validate_limits!
       if @max_organizations_per_user && !@max_organizations_per_user.is_a?(Integer)
         raise ConfigurationError, "max_organizations_per_user must be an Integer or nil"
@@ -395,6 +630,11 @@ module Organizations
     def validate_controller_layouts!
       validate_layout_option!(@authenticated_controller_layout, "authenticated_controller_layout")
       validate_layout_option!(@public_controller_layout, "public_controller_layout")
+
+      unless @public_controller_helpers.is_a?(Array) &&
+             @public_controller_helpers.all? { |h| h.is_a?(String) || h.is_a?(Module) }
+        raise ConfigurationError, "public_controller_helpers must be an Array of Strings or Modules"
+      end
     end
 
     def validate_no_organization_messages!
@@ -422,5 +662,39 @@ module Organizations
       raise ConfigurationError,
             "#{option_name} must be nil or a String"
     end
+
+    # Normalize {only:}/{except:}/Array(=only) into the enabled-group list,
+    # rejecting unknown group names loudly at configure time.
+    def normalize_engine_routes(value)
+      case value
+      when Array
+        validate_engine_route_groups!(value)
+      when Hash
+        only = value[:only]
+        except = value[:except]
+        if [only, except].compact.size != 1
+          raise ConfigurationError, "engine_routes takes exactly one of only:/except: (or an Array meaning only:)"
+        end
+
+        if only
+          validate_engine_route_groups!(Array(only))
+        else
+          ENGINE_ROUTE_GROUPS - validate_engine_route_groups!(Array(except))
+        end
+      else
+        raise ConfigurationError, "engine_routes must be a Hash with only:/except:, an Array, or nil"
+      end
+    end
+
+    def validate_engine_route_groups!(groups)
+      groups = groups.map(&:to_sym)
+      unknown = groups - ENGINE_ROUTE_GROUPS
+      unless unknown.empty?
+        raise ConfigurationError,
+              "Unknown engine route group(s): #{unknown.join(', ')}. Valid: #{ENGINE_ROUTE_GROUPS.join(', ')}"
+      end
+
+      groups
+    end
   end
 end

data/lib/organizations/controller_helpers.rb

@@ -344,7 +344,7 @@ module Organizations
         config_value,
         invitation,
         user,
-        default: -> { default_auth_required_redirect_path }
+        default: -> { default_auth_required_redirect_path(invitation) }
       )
     end
 
@@ -419,7 +419,7 @@ module Organizations
       flash_options[:notice] = notice unless notice.nil?
 
       # Keep current behavior for existing apps when nothing is configured/passed.
-      flash_options[:alert] = "Please select or create an organization." if flash_options.empty?
+      flash_options[:alert] = Organizations.t(:"notices.select_or_create_organization") if flash_options.empty?
 
       redirect_to no_organization_redirect_path, **flash_options
       false
@@ -468,7 +468,7 @@ module Organizations
 
       unless membership_exists_for?(acting_user, org)
         raise Organizations::NotAMember.new(
-          "You are not a member of this organization",
+          Organizations.t(:"errors.not_a_member"),
           organization: org,
           user: acting_user
         )
@@ -624,11 +624,14 @@ module Organizations
 
     def build_unauthorized_message(permission, required_role)
       if required_role
-        "You need #{required_role} access to perform this action"
+        # Same custom-role fallback as ViewHelpers#organization_role_label:
+        # humanized, so "superfan" renders as "Superfan" in both places.
+        Organizations.t(:"errors.unauthorized_role",
+                        role: Organizations.t(:"roles.#{required_role}", default: required_role.to_s.humanize))
       elsif permission
-        "You don't have permission to #{permission.to_s.humanize.downcase}"
+        Organizations.t(:"errors.unauthorized_permission", permission: permission.to_s.humanize.downcase)
       else
-        "You are not authorized to perform this action"
+        Organizations.t(:"errors.unauthorized")
       end
     end
 
@@ -662,7 +665,7 @@ module Organizations
             notice: config.no_organization_notice
           )
         end
-        format.json { render json: { error: "Organization required" }, status: :forbidden }
+        format.json { render json: { error: Organizations.t(:"errors.organization_required") }, status: :forbidden }
       end
     end
 
@@ -745,10 +748,20 @@ module Organizations
       end
     end
 
-    # Default path when invitation requires authentication
+    # Default path when invitation requires authentication.
+    #
+    # KNOWN-USER PROMOTION (default since 0.5.0): an invitation sent to an
+    # address that already has an account lands on SIGN-IN; everyone else
+    # lands on SIGN-UP. Both production hosts overrode the old always-sign-up
+    # default with this exact lambda — when every real host writes the same
+    # override, that's the default. Opt out by configuring
+    # redirect_path_when_invitation_requires_authentication yourself.
+    # @param invitation [Organizations::Invitation, nil]
     # @return [String]
-    def default_auth_required_redirect_path
-      if main_app.respond_to?(:new_user_registration_path)
+    def default_auth_required_redirect_path(invitation = nil)
+      if known_invited_user?(invitation) && main_app.respond_to?(:new_user_session_path)
+        main_app.new_user_session_path
+      elsif main_app.respond_to?(:new_user_registration_path)
         main_app.new_user_registration_path
       elsif main_app.respond_to?(:root_path)
         main_app.root_path
@@ -757,6 +770,19 @@ module Organizations
       end
     end
 
+    # Does the invited address already belong to an account? Fails closed
+    # (false → sign-up) if the user class can't answer — never let a lookup
+    # error break the invitation flow.
+    def known_invited_user?(invitation)
+      email = invitation&.email.to_s.downcase
+      return false if email.blank?
+
+      klass = Organizations.user_class
+      klass.respond_to?(:where) && klass.where("LOWER(email) = ?", email).exists?
+    rescue StandardError
+      false
+    end
+
     # Default path after invitation acceptance
     # @return [String]
     def default_after_accept_redirect_path
@@ -779,9 +805,9 @@ module Organizations
 
     def default_pending_invitation_acceptance_notice(result)
       organization_name = result.invitation.organization.name
-      return "You're already a member of #{organization_name}." if result.already_member?
+      return Organizations.t(:"notices.already_member", organization: organization_name) if result.already_member?
 
-      "Welcome to #{organization_name}!"
+      Organizations.t(:"notices.welcome", organization: organization_name)
     end
   end
 end

data/lib/organizations/email_normalizer.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Organizations
+  # Default email normalization for verified joining.
+  #
+  # Verified joining enforces "one proven email address => one membership per
+  # organization" (partial unique index on memberships.verified_email_normalized).
+  # That invariant is only meaningful if trivially-aliased addresses collapse to
+  # the same normalized value, otherwise one inbox can mint unlimited "distinct"
+  # identities via plus-addressing (user+1@corp.com, user+2@corp.com, ...).
+  #
+  # Normalization rules (deliberately conservative):
+  # - downcase + strip surrounding whitespace
+  # - strip a single trailing dot from the domain (FQDN form: "corp.com.")
+  # - drop the +tag suffix from the local part (RFC 5233 subaddressing)
+  #
+  # Gmail-style dot-collapsing in the local part is intentionally NOT applied:
+  # dots are significant in most corporate mail systems, and collapsing them
+  # would wrongly merge distinct mailboxes (j.doe@ vs jdoe@).
+  #
+  # Hosts can replace this wholesale via:
+  #   config.verification_email_normalizer = ->(email) { ... }
+  #
+  # @example
+  #   EmailNormalizer.normalize("  J.Doe+carpool@INIZIO.COM. ") # => "j.doe@inizio.com"
+  #   EmailNormalizer.domain_of("j.doe@inizio.com")             # => "inizio.com"
+  #   EmailNormalizer.domain_of("evil@a.com@b.com")             # => nil (multi-@ rejected)
+  #
+  module EmailNormalizer
+    module_function
+
+    # Normalize an email address for uniqueness comparison.
+    # @param email [String, nil]
+    # @return [String] normalized email ("" for blank input)
+    def normalize(email)
+      value = email.to_s.strip.downcase
+      return "" if value.empty?
+
+      local, at, domain = value.rpartition("@")
+      return value if at.empty? # not an email shape; leave as-is (validation rejects it upstream)
+
+      local = local.split("+", 2).first.to_s
+      domain = domain.chomp(".")
+
+      "#{local}@#{domain}"
+    end
+
+    # Extract the domain of an email address, hardened against evasion shapes.
+    # Returns nil (instead of guessing) when the address doesn't have exactly
+    # one "@" — multi-@ addresses are a classic trick against naive splitting.
+    # A single trailing dot (FQDN form) is tolerated and stripped.
+    # @param email [String, nil]
+    # @return [String, nil] lowercased domain, or nil if not extractable
+    def domain_of(email)
+      value = email.to_s.strip.downcase
+      return nil if value.empty?
+      return nil unless value.count("@") == 1
+
+      domain = value.split("@", 2).last.to_s.chomp(".")
+      return nil if domain.empty? || domain.include?("@")
+
+      domain
+    end
+  end
+end