organizations 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ffa0f2d13cc9a1eb2ca3c25bc1333f9ea27d2d1967d95b5acbd5bd5a57cd9b9
-  data.tar.gz: fd625579a6db02a11c5784eaef031a1789334cf01e3cf69cbb53d9dfbe0a2894
+  metadata.gz: 883d468209035eb168c343e8ffc8261ee27155f1c16b3879d367fa081ce937e2
+  data.tar.gz: d38f2b84422a031248b03682a1485dc43367deef95135e3e04fe7e32190c2e33
 SHA512:
-  metadata.gz: 167e836ce9aa5af1a2c99707170605be25bbaaf9923d88a8fbe13c4b2a2cc69af40febdde5c9debef799592f1a1d42040fcb1c0ec2d96ebe8a0f6c47e7c854e8
-  data.tar.gz: 76cd432b695b887649d9ed9cf9425e62b51b7c9a2d09f69374534afd27bf72db77f4b442e1a064130674513c23ef06467a965dd3e29bcfccca303a69dbb5bafa
+  metadata.gz: fc9d92ca2dac7522fd4911ba60e375fc60f8ef56a172d94b969b643fe2d9e719b1b69247dfa6b07064009e1b3d73fb893d30fdea6356b00d358f54def4a696a9
+  data.tar.gz: eca61e80a95a36ebb6e917283770c99c146b5b719a01d3c526b3a89e0444073eac08f678872bf9e151d731cb7f419eddac7a93aa9dd90ea50577a12c791ea423

data/Appraisals

@@ -2,6 +2,8 @@
 
 appraise "rails-7.2" do
   gem "rails", "~> 7.2.3"
+  # json 3 removed the quirks_mode option that ActiveSupport before 8.1 passes.
+  gem "json", "< 3"
 end
 
 appraise "rails-8.1" do

data/CHANGELOG.md

@@ -1,3 +1,22 @@
+## [0.6.0] - 2026-10-18
+
+**Custom role names.** Register a role outside owner > admin > member > viewer (a `client`, an `auditor`, a `guest`) in the existing `config.roles` block. No migration is needed. Installs without custom roles change nothing.
+
+### Added
+
+- **Custom roles.** `role :client, inherits: :viewer do can :answer_questions end` in `config.roles` adds a role with its own permissions plus its parent's. A custom role sits directly above its parent in `Roles.hierarchy`. A custom role without `inherits:` sits at the bottom. Two custom roles with the same parent stack in the order you define them.
+- Custom roles work in `add_member!`, memberships, invitations, `default_invitation_role`, promotions, demotions, `at_least?`, `by_role_hierarchy` and every permission helper. The generated views and the dummy reference views list them in the role pickers.
+- **Safety rules, checked when the configuration loads.** A custom role inherits from `member`, `viewer` or another custom role, never from `admin` or `owner`, so it ranks below admin. A custom role cannot grant a permission that the owner role has and the admin role lacks (`manage_billing`, `transfer_ownership`, `delete_organization` by default), because admins can assign it. A built-in role cannot inherit a custom role that ranks above it. A role name is lowercase letters, digits and underscores, and a parent must be defined above its child.
+- `Roles.hierarchy_for(definition)` returns the hierarchy of a roles definition.
+
+### Changed
+
+- `RoleBuilder` keeps roles outside the four built-in ones as custom roles. Before, it dropped them without an error. A `config.roles` block with such a role now registers it, or raises `ConfigurationError` when the role breaks a safety rule.
+- A block that only adds custom roles keeps the default permissions of the built-in roles. A block that redefines a built-in role defines only the built-in roles it lists, as before. An empty block still defines no permissions.
+- `Membership` and `Invitation` check the role against the configured roles only when the role is set or changed. A membership of a role that you remove from the configuration stays readable and updatable, and ranks below every configured role. Move such memberships with `org.change_role_of!(user, to: :member)`. A pending invitation for a removed role cannot be accepted.
+- `by_role_hierarchy` follows the configured hierarchy, custom roles included, with unknown roles last.
+- The hierarchy and the permissions are one immutable snapshot for each roles definition, and each comparison reads one snapshot. A reconfiguration, or a rolled-back one, can no longer leave a stale hierarchy in place.
+
 ## [0.5.0] - 2026-07-16
 
 **Verified Joining** — users can now join organizations by proving they belong, closing three roadmap items (domain-based joining, request-to-join, roster/bulk import). Fully additive: existing installs change nothing until they enroll a domain, generate a code, or import a roster. Run `rails g organizations:upgrade` + `rails db:migrate` to get the new tables/columns.

data/README.md

@@ -804,6 +804,34 @@ Organizations.configure do |config|
 end
 ```
 
+### Add custom roles
+
+Need a role that is not a step on the owner > admin > member > viewer ladder — a `client` who sees and answers for their own records, an `auditor`, a `guest`? Define it in the same block. A custom role inherits from one role and sits directly above it in the hierarchy:
+
+```ruby
+Organizations.configure do |config|
+  config.roles do
+    role :client, inherits: :viewer do
+      can :view_own_records
+      can :answer_questions
+    end
+  end
+end
+
+Organizations::Roles.hierarchy             # => [:owner, :admin, :member, :client, :viewer]
+org.add_member!(user, role: :client)
+user.role_in(org)                          # => :client
+user.has_organization_permission_to?(:answer_questions)  # => true
+require_organization_role!(:client)        # clients and everyone above them
+```
+
+- A custom role gets its own permissions plus its parent's (the parent's defaults when the block does not redefine a built-in parent).
+- A custom role without `inherits:` sits at the bottom of the hierarchy. Two custom roles with the same parent stack in the order you define them, the first one highest.
+- A block that only adds custom roles keeps the built-in roles' default permissions; a block that redefines a built-in role defines the built-in roles it lists, as before.
+- A custom role ranks below admin: it inherits from `member`, `viewer` or another custom role, never from `admin` or `owner`, so it never outranks the people who can assign it. A custom role also cannot grant a permission that the owner role has and the admin role lacks (`manage_billing`, `transfer_ownership`, `delete_organization` by default), because admins can assign it. A role name is lowercase letters, digits and underscores; a parent must be a built-in role or a custom role defined above it. Both are checked when the configuration loads.
+- Memberships, invitations, `default_invitation_role`, `add_member!`, promotions and demotions, `by_role_hierarchy` and every permission helper accept custom roles. The generated views list them in the role pickers.
+- Removing a custom role from the configuration later leaves its memberships readable and updatable (the role is checked only when it is set or changed) and ranks them below every configured role; move them to a configured role with `org.change_role_of!(user, to: :member)`. A pending invitation for a retired role cannot be accepted; revoke it and invite again with a configured role.
+
 ### Add custom permissions
 
 ```ruby

data/gemfiles/rails_7.2.gemfile

@@ -4,6 +4,7 @@ source "https://rubygems.org"
 
 gem "rake", "~> 13.0"
 gem "rails", "~> 7.2.3"
+gem "json", "< 3"
 
 group :development do
   gem "irb"

data/lib/generators/organizations/views/templates/organizations/invitations/_form.html.erb

@@ -35,7 +35,7 @@
   <div>
     <%= form.label :role, "Role", class: "block text-sm font-medium text-gray-700 mb-1" %>
     <%= form.select :role,
-      Organizations::Roles::HIERARCHY.reject { |role| role == :owner }.map { |role| [role.to_s.capitalize, role] },
+      Organizations::Roles.hierarchy.reject { |role| role == :owner }.map { |role| [role.to_s.capitalize, role] },
       { selected: @invitation.role || :member },
       required: true,
       class: "block w-full rounded-lg border-gray-300 shadow-sm focus:border-slate-500 focus:ring-slate-500 sm:text-sm" %>

data/lib/generators/organizations/views/templates/organizations/memberships/index.html.erb

@@ -63,7 +63,7 @@
                 <div class="flex items-center justify-end gap-2">
                   <%= form_with(model: membership, url: membership_path(membership), method: :patch, local: true, class: "flex items-center gap-2") do |form| %>
                     <%= form.select :role,
-                      Organizations::Roles::HIERARCHY.reject { |r| r == :owner }.map { |role| [role.to_s.capitalize, role] },
+                      Organizations::Roles.hierarchy.reject { |r| r == :owner }.map { |role| [role.to_s.capitalize, role] },
                       { selected: membership.role },
                       class: "rounded-md border-gray-300 text-sm focus:border-slate-500 focus:ring-slate-500" %>
                     <%= form.submit "Update",

data/lib/generators/organizations/views/templates/organizations/organizations/show.html.erb

@@ -126,7 +126,7 @@
             <div class="flex items-center gap-2">
               <%= form_with(model: membership, url: organizations.membership_path(membership), method: :patch, local: true, class: "flex items-center gap-2") do |form| %>
                 <%= form.select :role,
-                  Organizations::Roles::HIERARCHY.reject { |r| r == :owner }.map { |role| [role.to_s.capitalize, role] },
+                  Organizations::Roles.hierarchy.reject { |r| r == :owner }.map { |role| [role.to_s.capitalize, role] },
                   { selected: membership.role },
                   class: "rounded-md border-gray-300 text-xs focus:border-slate-500 focus:ring-slate-500 py-1" %>
                 <%= form.submit "Update",

data/lib/organizations/configuration.rb

@@ -558,8 +558,9 @@ module Organizations
         raise ConfigurationError, "invitation_expiry must be a Duration (e.g., 7.days) or nil"
       end
 
-      unless Roles::HIERARCHY.include?(@default_invitation_role.to_sym)
-        raise ConfigurationError, "default_invitation_role must be one of: #{Roles::HIERARCHY.join(', ')}"
+      roles = Roles.hierarchy_for(@custom_roles_definition)
+      unless roles.include?(@default_invitation_role.to_sym)
+        raise ConfigurationError, "default_invitation_role must be one of: #{roles.join(', ')}"
       end
     end
 

data/lib/organizations/models/invitation.rb

@@ -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

data/lib/organizations/models/membership.rb

@@ -53,7 +53,11 @@ module Organizations
 
     # === Validations ===
 
-    validates :role, presence: true, inclusion: { in: ->(_) { Roles::HIERARCHY.map(&:to_s) } }
+    validates :role, presence: true
+    # Checked when the role is set or changed, so a role retired from the
+    # configuration does not block unrelated updates of existing memberships.
+    validates :role, inclusion: { in: ->(_) { Roles.valid_roles.map(&:to_s) } },
+                     if: -> { new_record? || will_save_change_to_role? }
     # 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,
@@ -78,16 +82,11 @@ module Organizations
     scope :viewers, -> { where(role: "viewer") }
 
     # Order by role hierarchy (owners first)
+    # (the configured hierarchy, custom roles included; unknown roles last)
     scope :by_role_hierarchy, -> {
-      order(Arel.sql(<<~SQL.squish))
-        CASE role
-          WHEN 'owner' THEN 0
-          WHEN 'admin' THEN 1
-          WHEN 'member' THEN 2
-          WHEN 'viewer' THEN 3
-          ELSE 4
-        END
-      SQL
+      roles = Roles.hierarchy # one snapshot for the ranks and the fallback
+      ranks = roles.each_with_index.map { |role, index| "WHEN #{connection.quote(role.to_s)} THEN #{index}" }
+      order(Arel.sql("CASE role #{ranks.join(' ')} ELSE #{roles.length} END"))
     }
 
     # === Verified Joining (v0.5.0) ===

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/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: organizations
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-07-22 00:00:00.000000000 Z
+date: 2026-10-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties