organizations 0.4.3 → 0.6.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/roles.rb

@@ -56,6 +56,9 @@ module Organizations
       ].freeze
     }.freeze
 
+    # One published roles configuration (see Roles.snapshot).
+    Snapshot = Struct.new(:definition, :hierarchy, :permissions, :permission_sets)
+
     class << self
       # Get the default permission structure
       # @return [Hash<Symbol, Array<Symbol>>]
@@ -66,13 +69,13 @@ module Organizations
       # Get the role hierarchy
       # @return [Array<Symbol>]
       def hierarchy
-        HIERARCHY
+        snapshot.hierarchy
       end
 
       # Get all valid role names
       # @return [Array<Symbol>]
       def valid_roles
-        HIERARCHY
+        hierarchy
       end
 
       # Check if a role is valid
@@ -81,7 +84,7 @@ module Organizations
       def valid_role?(role)
         return false if role.nil?
 
-        HIERARCHY.include?(role.to_sym)
+        hierarchy.include?(role.to_sym)
       end
 
       # Check if role_a is at least as high as role_b in hierarchy
@@ -96,8 +99,9 @@ module Organizations
       def at_least?(role_a, role_b)
         return false if role_a.nil? || role_b.nil?
 
-        idx_a = HIERARCHY.index(role_a.to_sym)
-        idx_b = HIERARCHY.index(role_b.to_sym)
+        order = hierarchy # one snapshot for both lookups
+        idx_a = order.index(role_a.to_sym)
+        idx_b = order.index(role_b.to_sym)
 
         return false unless idx_a && idx_b
 
@@ -110,8 +114,10 @@ module Organizations
       # @param role_b [Symbol, String] Second role
       # @return [Integer] -1 if a > b, 0 if equal, 1 if a < b
       def compare(role_a, role_b)
-        idx_a = HIERARCHY.index(role_a.to_sym)
-        idx_b = HIERARCHY.index(role_b.to_sym)
+        # A role that is no longer configured ranks below every configured role.
+        order = hierarchy # one snapshot for both lookups
+        idx_a = order.index(role_a.to_sym) || order.length
+        idx_b = order.index(role_b.to_sym) || order.length
 
         return 0 if idx_a == idx_b
 
@@ -146,19 +152,18 @@ module Organizations
       # Get the pre-computed permission hash (for direct access)
       # @return [Hash<Symbol, Array<Symbol>>]
       def permissions
-        @permissions ||= compute_permissions
+        snapshot.permissions
       end
 
       # Get the pre-computed permission sets (for O(1) lookups)
       # @return [Hash<Symbol, Set<Symbol>>]
       def permission_sets
-        @permission_sets ||= permissions.transform_values { |perms| Set.new(perms) }
+        snapshot.permission_sets
       end
 
       # Reset computed permissions (used when custom roles are defined)
       def reset!
-        @permissions = nil
-        @permission_sets = nil
+        @snapshot = nil
       end
 
       # Get the next role up in hierarchy
@@ -167,10 +172,11 @@ module Organizations
       def higher_role(role)
         return nil if role.nil?
 
-        idx = HIERARCHY.index(role.to_sym)
+        order = hierarchy # one snapshot for the lookup and the result
+        idx = order.index(role.to_sym)
         return nil unless idx && idx > 0
 
-        HIERARCHY[idx - 1]
+        order[idx - 1]
       end
 
       # Get the next role down in hierarchy
@@ -179,23 +185,54 @@ module Organizations
       def lower_role(role)
         return nil if role.nil?
 
-        idx = HIERARCHY.index(role.to_sym)
-        return nil unless idx && idx < HIERARCHY.length - 1
+        order = hierarchy # one snapshot for the lookup and the result
+        idx = order.index(role.to_sym)
+        return nil unless idx && idx < order.length - 1
 
-        HIERARCHY[idx + 1]
+        order[idx + 1]
+      end
+
+      # The role hierarchy (highest first) of a roles definition: the four
+      # built-in roles, and each custom role directly above the role it
+      # inherits from (a custom role without `inherits:` sits at the bottom).
+      def hierarchy_for(definition)
+        return HIERARCHY unless definition
+
+        builder = RoleBuilder.new
+        builder.instance_eval(&definition)
+        builder.validate_privileges!
+        builder.hierarchy
       end
 
       private
 
-      def compute_permissions
-        # Use custom roles if defined, otherwise use defaults
-        custom_def = Organizations.configuration&.custom_roles_definition
-        return DEFAULT_PERMISSIONS.dup unless custom_def
+      # The hierarchy and permissions of one roles definition, computed
+      # together and published as one immutable value. It belongs to the
+      # definition object it was built from: after a reconfiguration (or a
+      # rolled-back one) the next reader sees the identity change and builds a
+      # new snapshot, so a reader that raced a reset can never keep an
+      # obsolete hierarchy in place.
+      def snapshot
+        definition = Organizations.configuration&.custom_roles_definition
+        current = @snapshot
+        return current if current && current.definition.equal?(definition)
+
+        @snapshot = build_snapshot(definition)
+      end
 
-        # Build custom permissions using DSL
-        builder = RoleBuilder.new
-        builder.instance_eval(&custom_def)
-        builder.to_permissions
+      def build_snapshot(definition)
+        if definition
+          builder = RoleBuilder.new
+          builder.instance_eval(&definition)
+          builder.validate_privileges!
+          hierarchy = builder.hierarchy
+          permissions = builder.to_permissions
+        else
+          hierarchy = HIERARCHY
+          permissions = DEFAULT_PERMISSIONS
+        end
+        sets = permissions.transform_values { |perms| Set.new(perms).freeze }.freeze
+        Snapshot.new(definition, hierarchy, permissions, sets).freeze
       end
     end
 
@@ -211,6 +248,10 @@ module Organizations
       # @param inherits [Symbol, nil] Role to inherit from
       # @yield Block to define permissions
       def role(name, inherits: nil, &block)
+        name = name.to_sym
+        inherits = inherits&.to_sym
+        validate_role_definition!(name, inherits)
+
         @roles[name] = {
           inherits: inherits,
           permissions: []
@@ -228,28 +269,94 @@ module Organizations
         @roles[@current_role][:permissions] << permission.to_sym
       end
 
+      # The hierarchy, highest first: the built-in roles in their fixed order,
+      # and each custom role inserted directly above the role it inherits from.
+      # @return [Array<Symbol>]
+      def hierarchy
+        order = Roles::HIERARCHY.dup
+        custom_roles.each do |name|
+          parent = @roles[name][:inherits]
+          parent ? order.insert(order.index(parent), name) : order << name
+        end
+        order.freeze
+      end
+
       # Build final permissions hash with inheritance resolved
       # @return [Hash<Symbol, Array<Symbol>>]
       def to_permissions
-        result = {}
-
         # Process roles in reverse hierarchy order (lowest first)
         # so inheritance works correctly
-        Roles::HIERARCHY.reverse_each do |role_name|
-          next unless @roles.key?(role_name)
+        hierarchy.reverse_each.with_object({}) do |role_name, result|
+          perms = @roles.key?(role_name) ? defined_permissions(role_name, result) : omitted_permissions(role_name)
+          result[role_name] = perms.freeze if perms
+        end.freeze
+      end
 
-          role_def = @roles[role_name]
-          perms = role_def[:permissions].dup
+      # An admin can assign a custom role, so a custom role may not grant a
+      # permission that the owner role has and the admin role lacks (for
+      # example manage_billing or transfer_ownership). Otherwise an admin
+      # could give another account a power that the admin does not have.
+      def validate_privileges!
+        validate_built_in_parents!
+        permissions = to_permissions
+        owner_only = (permissions[:owner] || DEFAULT_PERMISSIONS[:owner]) -
+                     (permissions[:admin] || DEFAULT_PERMISSIONS[:admin])
+        custom_roles.each do |name|
+          granted = @roles[name][:permissions] & owner_only
+          next if granted.empty?
+
+          raise ConfigurationError, "Custom role #{name} cannot grant #{granted.join(', ')}: " \
+                                    "admins can assign it, and only the owner has that permission"
+        end
+      end
 
-          # Add inherited permissions
-          if role_def[:inherits] && result.key?(role_def[:inherits])
-            perms = (result[role_def[:inherits]] + perms).uniq
-          end
+      private
+
+      # A built-in role may inherit a custom role only when that custom role
+      # ranks below it; otherwise the inheritance would be dropped silently.
+      def validate_built_in_parents!
+        order = hierarchy
+        (@roles.keys & Roles::HIERARCHY).each do |name|
+          parent = @roles[name][:inherits]
+          next unless parent && custom_roles.include?(parent)
+          next if order.index(parent) > order.index(name)
 
-          result[role_name] = perms.freeze
+          raise ConfigurationError, "Role #{name} cannot inherit from #{parent}: #{parent} ranks above #{name}"
+        end
+      end
+
+      def custom_roles = @roles.keys - Roles::HIERARCHY
+
+      # A role's own permissions plus its parent's. A custom role that inherits
+      # a built-in role the block does not redefine inherits its defaults.
+      def defined_permissions(role_name, result)
+        role_def = @roles[role_name]
+        parent = role_def[:inherits]
+        inherited = parent && (result[parent] || (custom_roles.include?(role_name) && DEFAULT_PERMISSIONS[parent]))
+        inherited ? (inherited + role_def[:permissions]).uniq : role_def[:permissions].dup
+      end
+
+      # A block that only adds custom roles keeps the built-in roles' defaults.
+      # An empty block still defines no permissions, as before custom roles.
+      def omitted_permissions(role_name) = custom_only? ? DEFAULT_PERMISSIONS[role_name] : nil
+      def custom_only? = custom_roles.any? && !@roles.keys.intersect?(Roles::HIERARCHY)
+
+      # A custom role needs a plain name, and a parent that already exists (a
+      # built-in role below admin or a custom role defined above it). Nothing
+      # inherits admin or owner.
+      def validate_role_definition!(name, inherits)
+        unless name.to_s.match?(/\A[a-z][a-z0-9_]{0,31}\z/)
+          raise ConfigurationError, "Role name #{name.inspect} must be lowercase letters, digits and underscores"
+        end
+        return if Roles::HIERARCHY.include?(name)
+        raise ConfigurationError, "Role #{name} is defined twice" if @roles.key?(name)
+        # A custom role ranks below admin, so it never outranks the people who can assign it.
+        if %i[owner admin].include?(inherits)
+          raise ConfigurationError, "Custom role #{name} cannot inherit from #{inherits}: a custom role ranks below admin"
         end
+        return if inherits.nil? || %i[member viewer].include?(inherits) || @roles.key?(inherits)
 
-        result.freeze
+        raise ConfigurationError, "Custom role #{name} inherits from #{inherits}, which is not defined above it"
       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.6.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