organizations 0.4.3 → 0.5.0

data/lib/organizations/organization_scoped.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Organizations
+  # URL-SCOPED organization resolution — the second addressing mode.
+  #
+  # The engine's own controllers are SESSION-scoped (one "current"
+  # organization per user, workspace/tenant style — the LicenseSeat shape).
+  # Overlay-style hosts (community/marketplace apps where users belong to
+  # organizations but don't "work inside" one) address organizations BY URL
+  # instead: /org/:slug/admin, /teams/:id/settings. Before this concern,
+  # such hosts re-derived the same base controller by hand: find org by
+  # param → find viewer membership → role-gate → pick a not-found posture.
+  #
+  # @example A slug-addressed admin portal (the overlay shape)
+  #   class Portal::BaseController < ApplicationController
+  #     include Organizations::OrganizationScoped
+  #
+  #     self.organization_param  = :slug
+  #     self.organization_finder = ->(param) { Organizations::Organization.find_by(slug: param) }
+  #     # 404-never-403: don't disclose which orgs/surfaces exist (default).
+  #     require_organization_role :admin
+  #   end
+  #
+  #   class Portal::MembersController < Portal::BaseController
+  #     def index
+  #       @memberships = current_scoped_organization.memberships.includes(:user)
+  #     end
+  #   end
+  #
+  # Knobs (class_attributes, inheritable/overridable per controller):
+  #   organization_param    — request param holding the identifier
+  #                           (default :organization_id)
+  #   organization_finder   — ->(param) { ... } returning the org or nil;
+  #                           instance_exec'd on the controller (default
+  #                           find_by(id:))
+  #   organization_not_found_behavior — :not_found (default) raises
+  #                           ActionController::RoutingError so unknown orgs,
+  #                           non-members, and under-role members are all
+  #                           INDISTINGUISHABLE (no existence oracle);
+  #                           :forbidden responds 403 instead (internal
+  #                           tools where disclosure is fine).
+  #
+  # Deliberately DISTINCT from the session helpers (current_organization/
+  # current_membership): the two modes coexist — a session-tenant app can
+  # still expose a URL-scoped surface — so this concern never touches the
+  # session or the model-level current-organization context.
+  module OrganizationScoped
+    extend ActiveSupport::Concern
+    include Organizations::CurrentUserResolution
+
+    included do
+      class_attribute :organization_param, default: :organization_id, instance_writer: false
+      class_attribute :organization_finder,
+                      default: ->(param) { Organizations::Organization.find_by(id: param) },
+                      instance_writer: false
+      class_attribute :organization_not_found_behavior, default: :not_found, instance_writer: false
+
+      before_action :set_scoped_organization if respond_to?(:before_action)
+
+      if respond_to?(:helper_method)
+        helper_method :current_scoped_organization
+        helper_method :current_scoped_membership
+      end
+    end
+
+    class_methods do
+      # Gate every action (or only:/except: subsets, forwarded to
+      # before_action) behind a minimum role in the scoped organization.
+      # Below-role viewers get the configured not-found behavior — same
+      # posture as an unknown organization, on purpose.
+      #
+      # @param role [Symbol] minimum role (uses the gem hierarchy /
+      #   custom-role at_least semantics)
+      def require_organization_role(role, **options)
+        before_action(**options) { require_scoped_organization_role!(role) }
+      end
+    end
+
+    # The organization resolved from the URL for this request.
+    # @return [Organizations::Organization, nil]
+    def current_scoped_organization
+      @current_scoped_organization
+    end
+
+    # The requesting user's membership in the scoped organization.
+    # Memoized per request; nil for strangers/signed-out.
+    # @return [Organizations::Membership, nil]
+    def current_scoped_membership
+      return @current_scoped_membership if defined?(@current_scoped_membership)
+
+      user = scoped_organization_viewer
+      @current_scoped_membership =
+        (current_scoped_organization.memberships.find_by(user_id: user.id) if user && current_scoped_organization)
+    end
+
+    private
+
+    # The requesting user via the shared resolution (configured
+    # current_user_method, Warden fallback) — own cache ivar so it never
+    # collides with ControllerHelpers' memoization when both are included.
+    def scoped_organization_viewer
+      resolve_organizations_current_user(
+        cache_ivar: :@_scoped_organization_viewer,
+        prefer_super_for_current_user: false,
+        prefer_warden_for_current_user: true
+      )
+    end
+
+    def set_scoped_organization
+      finder = self.class.organization_finder
+      @current_scoped_organization = instance_exec(params[self.class.organization_param], &finder)
+
+      scoped_organization_not_found! unless @current_scoped_organization
+    end
+
+    def require_scoped_organization_role!(role)
+      membership = current_scoped_membership
+      return if membership&.is_at_least?(role)
+
+      scoped_organization_not_found!
+    end
+
+    def scoped_organization_not_found!
+      case self.class.organization_not_found_behavior
+      when :forbidden
+        head :forbidden
+      else
+        # RoutingError renders the host's 404 page — chosen over head(:not_found)
+        # so the user sees the app's normal not-found experience, and over 403
+        # so existence is never disclosed.
+        raise ActionController::RoutingError, "Not Found"
+      end
+    end
+  end
+end

data/lib/organizations/test_helpers.rb

@@ -111,7 +111,9 @@ module Organizations
     # @param role [Symbol] Role in the organization
     # @return [User]
     def create_user(email: "user@example.com", name: "Test User", org: nil, role: :member)
-      user = User.create!(email: email, name: name)
+      # Respects config.user_class so hosts with a differently-named account
+      # model can use this helper unchanged.
+      user = Organizations.user_class.create!(email: email, name: name)
 
       if org
         Organizations::Membership.create!(
@@ -124,6 +126,38 @@ module Organizations
       user
     end
 
+    # Force a KNOWN verification code onto a join request's active challenge,
+    # so tests can complete the emailed-code flow without intercepting mail.
+    #
+    # The database only ever stores a digest (SHA-256, peppered by row id) —
+    # before this helper, every host test suite reverse-engineered that
+    # recipe by hand (overwriting verification_code_digest with
+    # digest_verification_code). That's gem INTERNALS leaking into host
+    # tests; use this instead:
+    #
+    #   request.start_email_verification!(email: "j.doe@acme.com")
+    #   code = issue_verification_code(request)   # => "424242"
+    #   request.verify_email_code!(code)          # => Membership
+    #
+    # Also callable WITHOUT including the module —
+    #   Organizations::TestHelpers.issue_verification_code(request)
+    # — for suites whose own factory names (create_user, …) would collide
+    # with this module's (a real host hit exactly that).
+    #
+    # @param join_request [Organizations::JoinRequest] with a challenge started
+    # @param code [String] the plaintext code to force (default "424242")
+    # @return [String] the plaintext code, for typing into the flow
+    def issue_verification_code(join_request, code: "424242")
+      join_request.update!(
+        verification_code_digest: Organizations::JoinRequest.digest_verification_code(code, join_request.id)
+      )
+      code
+    end
+    module_function :issue_verification_code
+    # module_function makes the INSTANCE copy private — fine for included
+    # test usage (implicit receiver) while enabling the module-level call.
+    public :issue_verification_code
+
     # Assert that a user is a member of an organization
     # @param user [User] The user
     # @param org [Organizations::Organization] The organization

data/lib/organizations/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Organizations
-  VERSION = "0.4.3"
+  VERSION = "0.5.0"
 end

data/lib/organizations/view_helpers.rb

@@ -101,13 +101,11 @@ module Organizations
     #   organization_role_label(:admin) # => "Admin"
     #
     def organization_role_label(role)
-      case role.to_sym
-      when :owner then "Owner"
-      when :admin then "Admin"
-      when :member then "Member"
-      when :viewer then "Viewer"
-      else role.to_s.humanize
-      end
+      # I18n-backed (organizations.roles.*) so hosts localize/retheme labels
+      # by overriding locale keys instead of monkey-patching this helper.
+      # Custom roles defined via config.roles fall back to humanize unless
+      # the host adds a matching organizations.roles.<name> key.
+      Organizations.t(:"roles.#{role}", default: role.to_s.humanize)
     end
 
     # Returns a hash of role information for building badges
@@ -143,11 +141,9 @@ module Organizations
     # @param invitation [Organizations::Invitation] The invitation
     # @return [String]
     def organization_invitation_status_label(invitation)
-      case organization_invitation_status(invitation)
-      when :pending then "Pending"
-      when :accepted then "Accepted"
-      when :expired then "Expired"
-      end
+      status = organization_invitation_status(invitation)
+      # I18n-backed (organizations.invitation_status.*) — see role labels.
+      Organizations.t(:"invitation_status.#{status}", default: status.to_s.humanize)
     end
 
     # Returns a hash of invitation status information

data/lib/organizations.rb

@@ -41,6 +41,52 @@ module Organizations
   class InvitationAlreadyAccepted < InvitationError; end
   class InvitationEmailMismatch < InvitationError; end
 
+  # User-level membership errors — canonical TOP-LEVEL homes (0.5.0). These
+  # were historically defined four modules deep inside the HasOrganizations
+  # concern, forcing hosts to rescue
+  # Organizations::Models::Concerns::HasOrganizations::CannotLeaveAsLastOwner
+  # — a real papercut found in a production host. The nested constants are
+  # kept as aliases; rescue THESE.
+  class OrganizationLimitReached < Error; end
+  class CannotLeaveLastOrganization < Error; end
+  class CannotLeaveAsLastOwner < Error; end
+  class CannotDeleteAsOrganizationOwner < Error; end
+  class NoCurrentOrganization < Error; end
+
+  # Join request errors (verified joining)
+  class JoinRequestError < Error; end
+  class JoinRequestExpired < JoinRequestError; end
+  class JoinRequestAlreadyDecided < JoinRequestError; end
+
+  # Raised (typically by the host's `on_member_joining` gate) to VETO a
+  # membership that is about to be created — seat limits, member caps,
+  # compliance holds. The gate dispatches strictly inside the creating
+  # transaction, so raising this rolls everything back cleanly: no membership
+  # row, join requests stay pending (resumable), invitations stay unaccepted.
+  # Raising without a message gets the localized default
+  # (organizations.errors.membership_vetoed).
+  class MembershipVetoed < Error
+    def initialize(message = nil)
+      super(message || Organizations.t(:"errors.membership_vetoed"))
+    end
+  end
+
+  # Join code errors (verified joining)
+  # JoinCodeInvalid covers unknown, revoked, and expired codes — hosts should
+  # show the same generic message for all three (don't leak which codes exist).
+  class JoinCodeError < Error; end
+  class JoinCodeInvalid < JoinCodeError; end
+  class JoinCodeExhausted < JoinCodeInvalid; end
+
+  # Email verification errors (verified joining)
+  class VerificationError < JoinRequestError; end
+  class VerificationEmailNotEligible < VerificationError; end
+  class VerificationEmailAlreadyClaimed < VerificationError; end
+  class VerificationCodeInvalid < VerificationError; end
+  class VerificationCodeExpired < VerificationError; end
+  class VerificationAttemptsExceeded < VerificationError; end
+  class VerificationThrottled < VerificationError; end
+
   # === Autoload Components (lazy loading) ===
 
   autoload :Configuration, "organizations/configuration"
@@ -54,6 +100,11 @@ module Organizations
   autoload :CurrentUserResolution, "organizations/current_user_resolution"
   autoload :InvitationAcceptanceResult, "organizations/invitation_acceptance_result"
   autoload :InvitationAcceptanceFailure, "organizations/invitation_acceptance_failure"
+  autoload :EmailNormalizer, "organizations/email_normalizer"
+  autoload :JoinFlow, "organizations/join_flow"
+  autoload :JoinState, "organizations/join_state"
+  autoload :MetadataFlags, "organizations/metadata_flags"
+  autoload :OrganizationScoped, "organizations/organization_scoped"
 
   # Alias for README compatibility: `include Organizations::Controller`
   Controller = ControllerHelpers
@@ -87,6 +138,19 @@ module Organizations
     autoload :Organization, "organizations/models/organization"
     autoload :Membership, "organizations/models/membership"
     autoload :Invitation, "organizations/models/invitation"
+    autoload :Domain, "organizations/models/domain"
+    autoload :JoinCode, "organizations/models/join_code"
+    autoload :AllowlistEntry, "organizations/models/allowlist_entry"
+    autoload :JoinRequest, "organizations/models/join_request"
+
+    # Non-Rails contexts (plain ActiveRecord, the gem's own test suite) don't
+    # get the Rails engine's automatic `config/locales` pickup, so register
+    # the gem's locale files directly. `|=` keeps this idempotent. In Rails
+    # apps the engine handles it (Rails::Engine adds paths["config/locales"]
+    # to I18n.load_path — https://guides.rubyonrails.org/engines.html).
+    # I18n itself is always available: it's a hard dependency of
+    # activesupport, which this gem depends on.
+    I18n.load_path |= Dir[File.expand_path("../config/locales/*.yml", __dir__)]
   end
 
   class << self
@@ -107,22 +171,123 @@ module Organizations
     #     config.invitation_expiry = 7.days
     #   end
     #
+    # ATOMIC on validation failure: a configure block that raises (typically
+    # via validate!) restores the previous configuration instead of leaving
+    # half-applied settings on the live object. Found the hard way: a
+    # validation-failure left its invalid assignment behind on the shared
+    # config, and every LATER configure call re-raised that stale error —
+    # an order-dependent heisenbug in test suites and a real hazard for
+    # hosts rescuing ConfigurationError in initializers.
+    # NOTE: restoration is a shallow dup — use SETTERS in configure blocks
+    # (config.x = [...]), never in-place mutation (config.x << ...), which
+    # is the documented contract anyway.
     def configure
+      snapshot = configuration.dup
       yield(configuration)
       configuration.validate!
+    rescue StandardError
+      @configuration = snapshot
+      raise
     end
 
     # Reset configuration to defaults
     # Primarily used in tests
     def reset_configuration!
       @configuration = nil
+      remove_instance_variable(:@engine_mount_path) if defined?(@engine_mount_path)
       Roles.reset!
     end
 
+    # The path prefix the engine is mounted at in the HOST app ("" when
+    # mounted at root, "/orgs" when mounted there, "" outside Rails).
+    #
+    # Why this exists: engine route helpers called WITHOUT a controller
+    # context (from models/mailers — e.g. building an invitation acceptance
+    # URL) don't know the mount point, so URLs built as
+    # "/invitations/<token>" silently 404 for any host that mounts the
+    # engine anywhere but root. Both known hosts mount at root, which is
+    # exactly why nobody noticed. Memoized — the mount point is fixed at
+    # boot. Source on mounted helpers vs raw engine url_helpers:
+    # https://guides.rubyonrails.org/engines.html#routes
+    # @return [String]
+    def engine_mount_path
+      return @engine_mount_path if defined?(@engine_mount_path)
+
+      @engine_mount_path = compute_engine_mount_path
+    end
+
+    # @api private
+    def compute_engine_mount_path
+      routes = host_application_routes
+      return "" unless routes && defined?(Organizations::Engine)
+
+      mount = routes.routes.detect do |route|
+        route.app.respond_to?(:app) && route.app.app == Organizations::Engine
+      end
+      return "" unless mount
+
+      # "/orgs(.:format)" → "/orgs"; a root mount "/" → "".
+      mount.path.spec.to_s.delete_suffix("(.:format)").chomp("/")
+    rescue StandardError
+      ""
+    end
+
+    # True only under a real, booted Rails app — the ONE home for this guard
+    # (mailers and URL builders all need it). ⚠️ `defined?(Rails)` alone is
+    # NOT enough: several gems define a bare `Rails` module WITHOUT
+    # `.application` (globalid setups, railtie fragments, bare test
+    # harnesses), where `Rails.application` raises NoMethodError instead of
+    # returning nil. Found by the first tests to ever render the stock mails.
+    def full_rails_app?
+      !!(defined?(Rails) && Rails.respond_to?(:application) && Rails.application)
+    end
+
+    # @api private
+    def host_application_routes
+      return nil unless full_rails_app?
+
+      Rails.application.routes
+    end
+
     # Get the roles module
     # @return [Module]
     def roles
       Roles
     end
+
+    # The host's user model class name (config.user_class, default "User").
+    # Used as `class_name:` at association-definition time in the gem's
+    # models — they load AFTER initializers in Rails (Zeitwerk shims) and on
+    # first constant reference in plain Ruby, so a configured value is
+    # visible as long as hosts configure before touching the models.
+    # @return [String]
+    def user_class_name
+      configuration.user_class
+    end
+
+    # The host's user model class (constantized user_class_name).
+    # @return [Class]
+    def user_class
+      user_class_name.constantize
+    end
+
+    # Resolve a gem string through I18n under the `organizations.` namespace.
+    # This is the ONE door every user-facing string the gem produces goes
+    # through — error messages, labels, mailer copy. en.yml is the catalog
+    # SSOT (no inline English defaults on purpose: a missing key renders as
+    # "Translation missing: …", a loud and findable bug, instead of silently
+    # drifting from the catalog).
+    #
+    # Hosts override any key the standard Rails way — app locale files load
+    # after engine locale files, so the host's value wins.
+    #
+    # @param key [String, Symbol] key under the `organizations.` scope,
+    #   e.g. :"errors.join_code_invalid" or "roles.owner"
+    # @param options [Hash] I18n options (interpolations, :locale, :default…)
+    # @return [String]
+    def translate(key, **)
+      I18n.t(key, scope: :organizations, **)
+    end
+    alias t translate
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: organizations
 version: !ruby/object:Gem::Version
-  version: 0.4.3
+  version: 0.5.0
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-03-19 00:00:00.000000000 Z
+date: 2026-07-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -81,6 +81,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".rubocop.yml"
+- ".rubocop_todo.yml"
 - ".simplecov"
 - AGENTS.md
 - Appraisals
@@ -97,11 +98,20 @@ files:
 - app/controllers/organizations/public_invitations_controller.rb
 - app/controllers/organizations/switch_controller.rb
 - app/mailers/organizations/invitation_mailer.rb
+- app/mailers/organizations/verification_mailer.rb
+- app/models/organizations/allowlist_entry.rb
+- app/models/organizations/domain.rb
 - app/models/organizations/invitation.rb
+- app/models/organizations/join_code.rb
+- app/models/organizations/join_request.rb
 - app/models/organizations/membership.rb
 - app/models/organizations/organization.rb
 - app/views/organizations/invitation_mailer/invitation_email.html.erb
 - app/views/organizations/invitation_mailer/invitation_email.text.erb
+- app/views/organizations/verification_mailer/code_email.html.erb
+- app/views/organizations/verification_mailer/code_email.text.erb
+- config/locales/en.yml
+- config/locales/es.yml
 - config/routes.rb
 - context7.json
 - docs/organizations-invitation-accept-create-account.webp
@@ -113,6 +123,19 @@ files:
 - lib/generators/organizations/install/install_generator.rb
 - lib/generators/organizations/install/templates/create_organizations_tables.rb.erb
 - lib/generators/organizations/install/templates/initializer.rb
+- lib/generators/organizations/upgrade/templates/add_verified_joining_to_organizations.rb.erb
+- lib/generators/organizations/upgrade/upgrade_generator.rb
+- lib/generators/organizations/views/templates/organizations/invitations/_form.html.erb
+- lib/generators/organizations/views/templates/organizations/invitations/index.html.erb
+- lib/generators/organizations/views/templates/organizations/invitations/new.html.erb
+- lib/generators/organizations/views/templates/organizations/invitations/show.html.erb
+- lib/generators/organizations/views/templates/organizations/memberships/index.html.erb
+- lib/generators/organizations/views/templates/organizations/organizations/_form.html.erb
+- lib/generators/organizations/views/templates/organizations/organizations/edit.html.erb
+- lib/generators/organizations/views/templates/organizations/organizations/index.html.erb
+- lib/generators/organizations/views/templates/organizations/organizations/new.html.erb
+- lib/generators/organizations/views/templates/organizations/organizations/show.html.erb
+- lib/generators/organizations/views/views_generator.rb
 - lib/organizations.rb
 - lib/organizations/acts_as_tenant_integration.rb
 - lib/organizations/callback_context.rb
@@ -120,13 +143,22 @@ files:
 - lib/organizations/configuration.rb
 - lib/organizations/controller_helpers.rb
 - lib/organizations/current_user_resolution.rb
+- lib/organizations/email_normalizer.rb
 - lib/organizations/engine.rb
 - lib/organizations/invitation_acceptance_failure.rb
 - lib/organizations/invitation_acceptance_result.rb
+- lib/organizations/join_flow.rb
+- lib/organizations/join_state.rb
+- lib/organizations/metadata_flags.rb
+- lib/organizations/models/allowlist_entry.rb
 - lib/organizations/models/concerns/has_organizations.rb
+- lib/organizations/models/domain.rb
 - lib/organizations/models/invitation.rb
+- lib/organizations/models/join_code.rb
+- lib/organizations/models/join_request.rb
 - lib/organizations/models/membership.rb
 - lib/organizations/models/organization.rb
+- lib/organizations/organization_scoped.rb
 - lib/organizations/roles.rb
 - lib/organizations/test_helpers.rb
 - lib/organizations/version.rb