organizations 0.5.0 → 0.7.0

data/lib/organizations/public_email_domains.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Organizations
+  # Common free email providers, for config.blocked_email_domains. Opt-in:
+  #
+  #   config.blocked_email_domains = Organizations::PUBLIC_EMAIL_DOMAINS
+  #   config.blocked_email_domains = Organizations::PUBLIC_EMAIL_DOMAINS + ["example-isp.net"]
+  #
+  # Defence in depth, not proof of authority and not a complete list: the
+  # proof is the DNS challenge. A blocked domain cannot be enrolled and never
+  # admits through a domain. People with these addresses can still join by
+  # invitation, code or allowlist.
+  PUBLIC_EMAIL_DOMAINS = %w[
+    aol.com
+    fastmail.com
+    gmail.com
+    gmx.com
+    gmx.de
+    gmx.net
+    googlemail.com
+    hey.com
+    hotmail.co.uk
+    hotmail.com
+    hotmail.es
+    hotmail.fr
+    icloud.com
+    live.com
+    mac.com
+    mail.com
+    mail.ru
+    me.com
+    msn.com
+    outlook.com
+    outlook.es
+    pm.me
+    proton.me
+    protonmail.com
+    qq.com
+    tutanota.com
+    web.de
+    yahoo.co.uk
+    yahoo.com
+    yahoo.es
+    yahoo.fr
+    yandex.com
+    yandex.ru
+    zoho.com
+  ].freeze
+end

data/lib/organizations/resource.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Organizations
+  # A resource of the host app named by type and id, for grants on records
+  # that are not ActiveRecord models (or that you do not want to load):
+  #
+  #   entity = Organizations::Resource.new("Ledger::Entity", entity_id)
+  #   membership.grant!(entity, capabilities: %w[read])
+  #   membership.can?(:read, entity)
+  Resource = Data.define(:type, :id)
+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,14 +114,62 @@ 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
 
         idx_a < idx_b ? -1 : 1
       end
 
+      # Check if an account holding actor_role may act on role: give it to a
+      # member, take it away, remove a member who holds it, or invite to it.
+      # See assignment_refusal for the rule.
+      # @param actor_role [Symbol, String] The role of the account making the change
+      # @param role [Symbol, String] The role being acted on
+      # @return [Boolean]
+      #
+      # @example
+      #   Roles.can_assign?(:admin, :admin)  # => true (same rank)
+      #   Roles.can_assign?(:admin, :member) # => true
+      #   Roles.can_assign?(:member, :admin) # => false (admin ranks above member)
+      #
+      def can_assign?(actor_role, role) = assignment_refusal(actor_role, role).nil?
+
+      # Why an account holding actor_role may not act on role, or nil when it
+      # may. A role acts only on roles at or below its own rank, so a custom
+      # role that can edit member roles still cannot create or demote an
+      # admin. Rank alone is not enough below admin: two custom roles with the
+      # same parent are ranked by definition order, so a role below admin may
+      # also act only on roles whose permissions it holds itself. Admins and
+      # the owner keep the rank rule alone, as before. A role that is no
+      # longer configured ranks below every configured role and has no
+      # permissions; an actor whose own role is no longer configured may act
+      # on nothing. The owner role keeps its own rules on top of this: it
+      # moves only through transfer_ownership_to!.
+      # @param actor_role [Symbol, String] The role of the account making the change
+      # @param role [Symbol, String] The role being acted on
+      # @return [nil, :outranks, :lacks_permissions]
+      #
+      # @example
+      #   Roles.assignment_refusal(:member, :admin)  # => :outranks
+      #   Roles.assignment_refusal(:lead, :finance)  # => :lacks_permissions (a sibling with other powers)
+      #   Roles.assignment_refusal(:lead, :member)   # => nil
+      #
+      def assignment_refusal(actor_role, role)
+        return :outranks if actor_role.nil? || role.nil?
+
+        current = snapshot # one snapshot for the ranks and the permissions
+        actor_role = actor_role.to_sym
+        role = role.to_sym
+        return :outranks unless ranks_at_or_above?(current.hierarchy, actor_role, role)
+        return nil if ranks_at_or_above?(current.hierarchy, actor_role, :admin)
+
+        holds_permissions_of?(current.permission_sets, actor_role, role) ? nil : :lacks_permissions
+      end
+
       # Get all permissions for a role (pre-computed, O(1) lookup)
       # @param role [Symbol, String] The role
       # @return [Array<Symbol>] All permissions for the role
@@ -146,19 +198,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 +218,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 +231,63 @@ 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
+
+        order[idx + 1]
+      end
 
-        HIERARCHY[idx + 1]
+      # 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
+      # A role missing from order ranks below every configured role; an actor
+      # missing from it ranks at or above nothing.
+      def ranks_at_or_above?(order, actor_role, role)
+        actor_rank = order.index(actor_role)
+        !actor_rank.nil? && actor_rank <= (order.index(role) || order.length)
+      end
 
-        # Build custom permissions using DSL
-        builder = RoleBuilder.new
-        builder.instance_eval(&custom_def)
-        builder.to_permissions
+      def holds_permissions_of?(sets, actor_role, role) = (sets[role] || Set.new).subset?(sets[actor_role] || Set.new)
+
+      # 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
+
+      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 +303,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 +324,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
+
+      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)
+
+          raise ConfigurationError, "Role #{name} cannot inherit from #{parent}: #{parent} ranks above #{name}"
+        end
+      end
 
-          # Add inherited permissions
-          if role_def[:inherits] && result.key?(role_def[:inherits])
-            perms = (result[role_def[:inherits]] + perms).uniq
-          end
+      def custom_roles = @roles.keys - Roles::HIERARCHY
 
-          result[role_name] = perms.freeze
+      # 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.7.0"
 end

data/lib/organizations/view_helpers.rb

@@ -95,32 +95,36 @@ module Organizations
 
     # Returns a human-readable role label
     # @param role [Symbol, String] The role
+    # @param organization [Organizations::Organization, nil] pass it to use
+    #   that organization's vocabulary (config.vocabulary); never inferred
     # @return [String]
     #
     # @example
     #   organization_role_label(:admin) # => "Admin"
+    #   organization_role_label(:member, organization: school) # => "Student"
     #
-    def organization_role_label(role)
+    def organization_role_label(role, organization: nil)
       # 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)
+      Organizations.t(:"roles.#{role}", organization: organization, default: role.to_s.humanize)
     end
 
     # Returns a hash of role information for building badges
     # @param role [Symbol, String] The role
+    # @param organization [Organizations::Organization, nil] for its vocabulary
     # @return [Hash] Hash with :role, :label, and :color keys
     #
     # @example
     #   organization_role_info(:admin)
     #   # => { role: :admin, label: "Admin", color: :blue }
     #
-    def organization_role_info(role)
+    def organization_role_info(role, organization: nil)
       role_sym = role.to_sym
       {
         role: role_sym,
-        label: organization_role_label(role_sym),
+        label: role_label_for(role_sym, organization),
         color: role_color(role_sym)
       }
     end
@@ -172,8 +176,8 @@ module Organizations
           name: user.respond_to?(:name) && user.name.present? ? user.name : user.email,
           email: user.email,
           role: membership.role.to_sym,
-          role_label: organization_role_label(membership.role),
-          role_info: organization_role_info(membership.role),
+          role_label: role_label_for(membership.role, organization),
+          role_info: organization_role_info(membership.role, organization: organization),
           joined_at: membership.created_at,
           is_owner: membership.owner?
         }
@@ -190,7 +194,7 @@ module Organizations
           id: invitation.id,
           email: invitation.email,
           role: invitation.role.to_sym,
-          role_label: organization_role_label(invitation.role),
+          role_label: role_label_for(invitation.role, organization),
           invited_by: inviter,
           invited_by_name: inviter_display_name(inviter),
           status: organization_invitation_status(invitation),
@@ -240,6 +244,8 @@ module Organizations
     end
 
     # Check if current user can remove a member
+    # Follows the same rule as Organization#remove_member!: the member's role
+    # must be one the user may act on (see Roles.assignment_refusal).
     # @param user [User] The user performing the action
     # @param membership [Organizations::Membership] The membership to remove
     # @return [Boolean]
@@ -247,10 +253,12 @@ module Organizations
       return false unless user_has_permission_in_org?(user, membership.organization, :remove_members)
       return false if membership.owner? # Can't remove owner
 
-      true
+      user_can_act_on_role?(user, membership)
     end
 
     # Check if current user can change a member's role
+    # Follows the same rule as Organization#change_role_of!: the member's
+    # current role must be one the user may act on (see Roles.assignment_refusal).
     # @param user [User] The user performing the action
     # @param membership [Organizations::Membership] The membership to update
     # @return [Boolean]
@@ -262,7 +270,7 @@ module Organizations
       if membership.owner?
         user_has_permission_in_org?(user, membership.organization, :transfer_ownership)
       else
-        true
+        user_can_act_on_role?(user, membership)
       end
     end
 
@@ -353,6 +361,24 @@ module Organizations
       end
     end
 
+    # organization_role_label with the organization, unless a host override
+    # of it takes only the role (written before 0.7.0).
+    def role_label_for(role, organization)
+      if role_label_takes_organization?
+        organization_role_label(role, organization: organization)
+      else
+        organization_role_label(role)
+      end
+    end
+
+    def role_label_takes_organization?
+      return @_role_label_takes_organization if defined?(@_role_label_takes_organization)
+
+      @_role_label_takes_organization = method(:organization_role_label).parameters.any? do |kind, name|
+        kind == :keyrest || name == :organization
+      end
+    end
+
     def role_color(role)
       case role.to_sym
       when :owner then :purple
@@ -379,6 +405,11 @@ module Organizations
       role && Roles.has_permission?(role, permission)
     end
 
+    def user_can_act_on_role?(user, membership)
+      role = user.role_in(membership.organization)
+      role.present? && Roles.can_assign?(role, membership.role)
+    end
+
     # Returns display name for invitation sender (handles nil inviter)
     def inviter_display_name(inviter)
       return nil unless inviter

data/lib/organizations.rb

@@ -71,6 +71,20 @@ module Organizations
     end
   end
 
+  # Domain authority: why a DNS verification failed. reason is one of
+  # :not_started, :expired, :changed (the claim changed during the check),
+  # :record_not_found, :lookup_failed.
+  class DomainVerificationFailed < Error
+    REASONS = %i[not_started expired changed record_not_found lookup_failed].freeze
+
+    attr_reader :reason
+
+    def initialize(reason)
+      @reason = reason
+      super(Organizations.t(:"errors.domain_verification.#{reason}"))
+    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).
@@ -105,6 +119,13 @@ module Organizations
   autoload :JoinState, "organizations/join_state"
   autoload :MetadataFlags, "organizations/metadata_flags"
   autoload :OrganizationScoped, "organizations/organization_scoped"
+  autoload :PersonalOwnerBackfill, "organizations/personal_owner_backfill"
+  autoload :PUBLIC_EMAIL_DOMAINS, "organizations/public_email_domains"
+  autoload :Resource, "organizations/resource"
+  autoload :GrantHolder, "organizations/grant_holder"
+  autoload :GrantAccess, "organizations/grant_access"
+  autoload :Grantable, "organizations/grantable"
+  autoload :AccountDeletionPlan, "organizations/account_deletion_plan"
 
   # Alias for README compatibility: `include Organizations::Controller`
   Controller = ControllerHelpers
@@ -142,6 +163,7 @@ module Organizations
     autoload :JoinCode, "organizations/models/join_code"
     autoload :AllowlistEntry, "organizations/models/allowlist_entry"
     autoload :JoinRequest, "organizations/models/join_request"
+    autoload :Grant, "organizations/models/grant"
 
     # Non-Rails contexts (plain ActiveRecord, the gem's own test suite) don't
     # get the Rails engine's automatic `config/locales` pickup, so register
@@ -281,13 +303,86 @@ module Organizations
     # 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,
+    # VOCABULARY (config.vocabulary): pass the organization record as
+    # `organization:`. When the selected vocabulary has the key
+    # (`organizations.vocabularies.<vocabulary>.<key>`, in the current locale
+    # or one of its I18n fallbacks), that translation wins. Otherwise the call
+    # is exactly the ordinary one: same key, scope, defaults and options.
+    # `%{organization}` interpolates the record's name. A String
+    # `organization:` stays a plain interpolation value, as before. Calls
+    # with an Array key or a custom `scope:` skip the vocabulary.
+    #
+    #   Organizations.t("roles.member", organization: school)  # => "Student"
+    #
+    # @param key [String, Symbol, Array] key under the `organizations.` scope,
     #   e.g. :"errors.join_code_invalid" or "roles.owner"
-    # @param options [Hash] I18n options (interpolations, :locale, :default…)
+    # @param options [Hash] I18n options (interpolations, :locale, :count,
+    #   :default…) and :organization (a record or a String)
     # @return [String]
-    def translate(key, **)
-      I18n.t(key, scope: :organizations, **)
+    def translate(key, **options)
+      # A nil organization is no organization: the ordinary call stays unchanged.
+      options = options.except(:organization) if options.key?(:organization) && options[:organization].nil?
+      record = options[:organization].is_a?(Organizations::Organization) ? options[:organization] : nil
+      options = options.merge(organization: record.name) if record
+      vocabulary_key = vocabulary_key_for(key, record, options)
+      # The vocabulary key exists, so the caller's default (meant for the
+      # ordinary key) does not apply.
+      return I18n.t(vocabulary_key, scope: :organizations, **options.except(:default)) if vocabulary_key
+
+      I18n.t(key, scope: :organizations, **options)
     end
+
+    # The I18n lookup chain for a key, most specific first: the vocabulary
+    # key (when config.vocabulary selects one for this organization), then
+    # the ordinary key. Absolute keys, for the Rails `t` view helper (needed
+    # for `_html` keys):
+    #
+    #   primary, *fallbacks = Organizations.i18n_keys(:"mailers.invitation.invited_by_html", organization: org)
+    #   t(primary, default: fallbacks, inviter: name, organization: org.name)
+    #
+    # @param key [String, Symbol]
+    # @param organization [Organizations::Organization, nil]
+    # @return [Array<Symbol>]
+    def i18n_keys(key, organization: nil)
+      ordinary = :"organizations.#{key}"
+      vocabulary = vocabulary_for(organization)
+      vocabulary ? [:"organizations.vocabularies.#{vocabulary}.#{key}", ordinary] : [ordinary]
+    end
+
+    # @api private
+    # The vocabulary key to use for this call, or nil for the ordinary call.
+    def vocabulary_key_for(key, record, options)
+      return nil if key.is_a?(Array) || options.key?(:scope)
+
+      vocabulary = vocabulary_for(record)
+      return nil unless vocabulary
+
+      candidate = :"vocabularies.#{vocabulary}.#{key}"
+      I18n.exists?(candidate, scope: :organizations, locale: options[:locale] || I18n.locale) ? candidate : nil
+    end
+
+    # The vocabulary config.vocabulary selects: a Symbol/String for the whole
+    # app, or a callable that receives the organization (never called
+    # without one). nil selects the ordinary translations.
+    # @param organization [Organizations::Organization, nil]
+    # @return [String, nil]
+    # A resolver that raises, or returns a name that is not one plain label
+    # (letters, digits, underscores), selects the ordinary translations and
+    # logs a warning: wording must never break a page or an email.
+    def vocabulary_for(organization)
+      setting = configuration.vocabulary
+      setting = organization ? setting.call(organization) : nil if setting.respond_to?(:call)
+      name = setting.to_s.presence
+      return nil unless name
+      return name if name.match?(/\A[a-z0-9_]+\z/i)
+
+      Callbacks.log_warn("[Organizations] Ignored vocabulary #{name.inspect}: use letters, digits and underscores")
+      nil
+    rescue StandardError => e
+      Callbacks.log_warn("[Organizations] The vocabulary resolver failed: #{e.class}: #{e.message}")
+      nil
+    end
+
     alias t translate
   end
 end