permission_forge 0.14.1

data/lib/permission_forge/controller_actions/authorizer.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module ControllerActions
+    # Decides whether a user may run a controller action. The runtime guard
+    # ({PermissionForge::Concerns::ControllerActionGuard}) raises on a denied
+    # decision; host apps call {.allowed?} to hide buttons with the same logic.
+    #
+    # Decision order — the first row that applies wins:
+    #   1. the action maps to no Resource (Mapping returns nil)     → allow
+    #   2. no user → action_guard_nil_user_strategy, else nil_user_strategy → :bypass allows, anything else denies
+    #   3. config.action_guard_bypass returns true                  → allow
+    #   4. no Permission Set manages the Resource                   → unconfigured_action_strategy
+    #   5. the action means a CRUD permission                       → user.can?(crud, resource)
+    #   6. custom action the user is granted                        → allow
+    #   7. custom action some Permission Set manages                → deny
+    #   8. custom action no Permission Set manages                  → unconfigured_action_strategy
+    #
+    # A grant (rows 5 and 6) is checked before the index, so a granted request
+    # costs no extra cache read; rows 4, 7 and 8 share one. Everything
+    # unexpected fails closed: a user object without `can?`, a bypass lambda
+    # that raises or returns something other than true, an unknown strategy.
+    #
+    # @example
+    #   Authorizer.call(controller_path: 'customers', action_name: 'export')
+    #   # => #<struct allowed=false, reason=:action_denied, target=#<struct resource="Customer", ...>>
+    #   Authorizer.allowed?(controller_path: 'customers', action_name: 'export', user: current_user)
+    #   # => false
+    #
+    # @api public
+    class Authorizer
+      # Every outcome and whether it lets the request through.
+      REASONS = {
+        unmapped: true,                       # row 1
+        nil_user_bypassed: true,              # row 2, the nil-user strategy is :bypass
+        nil_user_denied: false,               # row 2, any other nil-user strategy
+        guard_bypassed: true,                 # row 3
+        unsupported_user: false,              # the user object has no can?
+        resource_not_managed: true,           # row 4, unconfigured_action_strategy = :allow
+        resource_not_managed_blocked: false,  # row 4, any other strategy
+        crud_granted: true,                   # row 5
+        crud_denied: false,                   # row 5
+        action_granted: true,                 # row 6
+        action_denied: false,                 # row 7
+        action_not_managed: true,             # row 8, unconfigured_action_strategy = :allow
+        action_not_managed_blocked: false     # row 8, any other strategy
+      }.freeze
+
+      # The allowed outcomes that let a request past the Permission Sets, and
+      # the rule.bypassed reason each one is published with (the guard does
+      # it: Authorizer.allowed? also answers button checks).
+      BYPASS_REASONS = {
+        nil_user_bypassed: 'nil_user',
+        guard_bypassed: 'guard_bypass',
+        resource_not_managed: 'no_rules',
+        action_not_managed: 'no_rules'
+      }.freeze
+
+      # target is the Mapping::Target that was checked, or nil when the action
+      # maps to no Resource. Every denied decision carries a target.
+      #
+      # @api private
+      Decision = Struct.new(:allowed, :reason, :target, keyword_init: true) do
+        def allowed? = allowed == true
+        def denied? = !allowed?
+
+        # @return [String, nil] the rule.bypassed reason, for an allowed
+        #   decision that skipped the Permission Sets
+        def bypass_reason = BYPASS_REASONS[reason]
+      end
+
+      # @param controller_path [String] e.g. 'customers/merges'
+      # @param action_name [String, Symbol] e.g. 'create'
+      # @param controller_class [Class, nil] the controller, for its
+      #   `permission_forge_actions` declaration. Defaults to the controller's
+      #   class, then to the class the path names (`Customers::MergesController`).
+      # @param controller [Object, nil] the controller instance, handed to
+      #   config.action_guard_bypass
+      # @param user [Object, nil] defaults to PermissionForge.current_user
+      # @param configuration [PermissionForge::Configuration]
+      # @param index [#managed_actions] defaults to ManagedIndex
+      # @return [Decision]
+      def self.call(...) = new(...).call
+
+      # Same arguments as {.call}.
+      #
+      # @return [Boolean] whether the user may run the action
+      def self.allowed?(...) = call(...).allowed?
+
+      # What to check, plus the injectable dependencies — all keywords.
+      def initialize(controller_path:, action_name:, controller_class: nil, controller: nil, # rubocop:disable Metrics/ParameterLists
+                     user: PermissionForge.current_user, configuration: PermissionForge.configuration,
+                     index: ManagedIndex)
+        @controller_path = controller_path.to_s
+        @action_name = action_name.to_s
+        @controller = controller
+        # No controller given (a button check): the class the path names.
+        @controller_class = controller_class || controller&.class || ControllerActions.controller_class_for(@controller_path)
+        @user = user
+        @configuration = configuration
+        @index = index
+      end
+
+      # @return [Decision]
+      def call
+        @target = Mapping.call(controller_path: @controller_path, action_name: @action_name,
+                               controller_class: @controller_class, configuration: @configuration)
+        return decide(:unmapped) unless @target
+        return decide(nil_user_bypass? ? :nil_user_bypassed : :nil_user_denied) unless @user
+        return decide(:guard_bypassed) if guard_bypassed?
+        return decide(:unsupported_user) unless @user.respond_to?(:can?)
+
+        authorize
+      end
+
+      private
+
+      # Rows 4–8: what the Permission Sets say. A grant is checked first — a
+      # user can only be granted something on a managed resource, so the answer
+      # is the same and a granted request never reads the index. Everything
+      # else costs one index read.
+      def authorize
+        return decide(@target.crud? ? :crud_granted : :action_granted) if can?(@target.permission)
+
+        managed_actions = @index.managed_actions(@target.resource)
+        return unconfigured(:resource_not_managed) if managed_actions.nil?
+        return decide(:crud_denied) if @target.crud?
+        return decide(:action_denied) if managed_actions.include?(@target.action)
+
+        unconfigured(:action_not_managed)
+      end
+
+      def decide(reason)
+        Decision.new(allowed: REASONS.fetch(reason), reason: reason, target: @target)
+      end
+
+      # Nobody configured this resource or action: the strategy decides.
+      def unconfigured(reason)
+        decide(@configuration.allow_unconfigured_actions? ? reason : :"#{reason}_blocked")
+      end
+
+      # Only an explicit true from can? grants.
+      def can?(permission)
+        @user.can?(permission, @target.resource) == true
+      end
+
+      # Only the exact :bypass value lets a request with no user through.
+      def nil_user_bypass?
+        @configuration.action_guard_nil_user_bypass?
+      end
+
+      # Only an explicit true skips the guard. A raising (or non-callable)
+      # bypass counts as "no bypass": the Permission Sets still decide.
+      def guard_bypassed?
+        bypass = @configuration.action_guard_bypass
+        return false if bypass.nil?
+
+        bypass.call(@user, @controller) == true
+      rescue StandardError => e
+        log_bypass_error(e)
+        false
+      end
+
+      def log_bypass_error(error)
+        return unless defined?(Rails) && Rails.respond_to?(:logger)
+
+        Rails.logger&.error("[PermissionForge] action_guard_bypass error: #{error.class}: #{error.message}")
+      end
+    end
+  end
+end

data/lib/permission_forge/controller_actions/managed_index.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require 'active_support/current_attributes'
+
+module PermissionForge
+  module ControllerActions
+    # Which resources and custom actions any Permission Set manages.
+    #
+    # "Managed" means a row is in effect — an active row in an active resource
+    # of an active Permission Set, granting or muting — in the current tenant
+    # (Resource.in_effect / ResourceAction.in_effect). The guard uses it to tell
+    # "nobody has configured this" (unconfigured_action_strategy applies) from
+    # "configured, and this user was not granted it" (denied).
+    #
+    # The index is one small hash ({ 'Customer' => ['export', 'merge'] }) kept
+    # in PermissionForge.cache, so every process sees an invalidation
+    # (InvalidatesManagedActions drops it when a defining record changes).
+    #
+    # A stale "not managed" lets a request through under the default
+    # strategy, so the index is invalidated and rebuilt the way a user's
+    # permission hash is — the same code, one definition:
+    #   - every invalidation leaves a fresh stamp (STAMP_KEY) before it removes
+    #     the keys, and a build only leaves the index in the store when the
+    #     stamp it read before reading the rows is still there after storing it
+    #     (Cache::Invalidation, Cache::Rebuild). A build that raced a commit is
+    #     removed and made once more; it reads the rows past ActiveRecord's
+    #     query cache;
+    #   - a removal the store does not confirm is tried again, reported
+    #     (Cache::Failure) and owed by this process (Cache::Backlog): until the
+    #     store confirms it, this process builds the index from the database
+    #     instead of reading it from the store;
+    #   - the cached copy lives at most MAX_TTL seconds, whatever cache_ttl is.
+    #     That bounds what nothing above can see: rows changed behind the
+    #     callbacks (update_all), and — in the other processes, which do not
+    #     know what this one owes — an index whose removal the store never
+    #     confirmed;
+    #   - a request keeps its own copy (RequestMemo), so many checks in one
+    #     request cost one cache read. Rails resets it between requests and
+    #     jobs; it is dropped on this thread by invalidate! and re-read after
+    #     MAX_TTL in a long-lived process.
+    class ManagedIndex
+      CACHE_KEY = 'managed_actions'
+
+      # The invalidation stamp: one for every tenant's index, as a user has one
+      # whatever the tenant (an invalidation in another tenant makes a build
+      # repeat itself, which costs time, not correctness).
+      STAMP_KEY = 'managed_actions_invalidation'
+
+      # Rebuilding costs two small queries, so the index can afford to be fresh.
+      MAX_TTL = 60
+
+      # The current request's copies: one per cache key, holding the cache
+      # version it was read under (a bump replaces it — a job that
+      # invalidates many users must not keep one copy per bump).
+      class RequestMemo < ActiveSupport::CurrentAttributes
+        attribute :indexes
+      end
+
+      class << self
+        # The managed action keys of a resource, in one lookup. Callers that
+        # need both answers (the guard) use this instead of the two predicates.
+        #
+        # @param resource [String, Symbol] resource name (e.g. 'Customer')
+        # @return [Array<String>, nil] nil when no Permission Set manages the resource
+        def managed_actions(resource)
+          entries[resource.to_s]
+        end
+
+        # @param resource [String, Symbol] resource name
+        # @return [Boolean]
+        def managed_resource?(resource)
+          !managed_actions(resource).nil?
+        end
+
+        # @param resource [String, Symbol] resource name
+        # @param action [String, Symbol] action key (e.g. 'export')
+        # @return [Boolean]
+        def managed_action?(resource, action)
+          Array(managed_actions(resource)).include?(action.to_s)
+        end
+
+        # Drops the index for the ambient tenant, the tenant-less key and —
+        # when the caller knows it (a callback on a tenant-scoped record) —
+        # that record's tenant, along with this request's copies.
+        #
+        # A Cache::Invalidation: a fresh stamp first, then every key, each
+        # removal confirmed by the store (Cache::Base#expunge). One the store
+        # does not confirm — or that raises — is tried again; when it still
+        # fails it is reported through Cache::Failure, not raised, and owed
+        # (Cache::Backlog): this process does not read the index from the store
+        # until the store has confirmed it. Other processes may serve the old
+        # index until it expires: MAX_TTL seconds at most.
+        #
+        # Inside an open transaction the rows this is about are not visible to
+        # anybody else yet, and a request that builds the index right now
+        # caches it without them. So the drop is repeated once the outermost
+        # transaction has committed (Cache::Settlement).
+        #
+        # @param tenant_id [Object, nil]
+        # @return [Boolean] whether the store confirmed every removal
+        def invalidate!(tenant_id: nil)
+          keys = [cache_key, CACHE_KEY, (tenant_key(tenant_id) if tenant_id)].compact.uniq
+          confirmed = PermissionForge::Cache::Invalidation.call(user_id: nil, stamp_key: STAMP_KEY, keys: keys)
+          repeat_after_commit(tenant_id)
+          confirmed
+        ensure
+          RequestMemo.indexes = nil
+        end
+
+        private
+
+        def repeat_after_commit(tenant_id)
+          transaction = PermissionForge::OpenTransaction.current
+          return unless transaction
+
+          # the tenant that is ambient now: the commit may run after the block that made it so
+          tenant_id ||= PermissionForge.ambient_tenant_id
+          PermissionForge::Cache::Settlement.for(transaction).add([CACHE_KEY, tenant_id]) { invalidate!(tenant_id: tenant_id) }
+        end
+
+        # @return [Hash{String => Array<String>}] frozen
+        def entries
+          key = cache_key
+          memo = (RequestMemo.indexes ||= {})
+          version = PermissionForge.permissions_cache_version
+          held = memo[key]
+          return held[:entries] if held && current?(held, version)
+
+          index, transaction = load(key)
+          memo[key] = { entries: index, version: version, at: Time.now, transaction: transaction }
+          index
+        end
+
+        # A request's copy is good under the cache version it was read with,
+        # for MAX_TTL — and, when it was built inside a transaction, for as
+        # long as that transaction is open.
+        def current?(held, version)
+          held[:version] == version && Time.now - held[:at] < MAX_TTL && !held[:transaction]&.finished?
+        end
+
+        # An index built inside an open transaction holds rows nobody else can
+        # see yet, and that a rollback takes back — at every isolation level.
+        # It is not written to the store, and the request's copy of it is
+        # dropped when that transaction ends.
+        #
+        # @return [Array(Hash, PermissionForge::OpenTransaction)] the index, and
+        #   the open transaction it was built in (nil when it came from the
+        #   store or was built outside one)
+        def load(key)
+          cached = read_shared(key)
+          return [normalize(cached), nil] unless cached.nil?
+
+          transaction = PermissionForge::OpenTransaction.current
+          [transaction ? build : store_built(key), transaction]
+        end
+
+        # The cached index — unless this process still owes the store its
+        # removal (Cache::Backlog): the entry may be the very one that should
+        # be gone.
+        def read_shared(key)
+          PermissionForge.cache.read(key) unless PermissionForge::Cache::Invalidation.owed?(STAMP_KEY)
+        end
+
+        # Builds the index and leaves it in the store only when no
+        # invalidation overtook the build (Cache::Rebuild).
+        #
+        # @return [Hash] the index as built, whether or not the store kept it
+        def store_built(key)
+          PermissionForge::Cache::Rebuild.call(key: key, stamp_key: STAMP_KEY, user_id: nil, build: -> { [build, ttl] }).first
+        end
+
+        def ttl
+          [PermissionForge.configuration.cache_ttl, MAX_TTL].compact.min
+        end
+
+        # String keys (the cache symbolizes hash keys on read), frozen so a
+        # request's shared copy cannot be changed by a caller.
+        def normalize(index)
+          index.to_h { |resource, actions| [resource.to_s, Array(actions).map(&:to_s).freeze] }.freeze
+        end
+
+        # Reads the rows outside ActiveRecord's query cache: inside a request
+        # it would answer a repeated build with the rows the first one read.
+        #
+        # @return [Hash{String => Array<String>}] frozen
+        def build
+          PermissionForge::Resource.uncached do
+            index = PermissionForge::Resource.in_effect.distinct.pluck(:name).index_with { [] }
+            action_pairs.each { |resource, action| index[resource] << action }
+            normalize(index)
+          end
+        end
+
+        def action_pairs
+          PermissionForge::ResourceAction.in_effect.distinct
+                                         .pluck(PermissionForge::Resource.arel_table[:name],
+                                                PermissionForge::ResourceAction.arel_table[:name])
+        end
+
+        # Mirrors PermissionCacheAccessor#permission_cache_key.
+        def cache_key
+          config = PermissionForge.configuration
+          tenant = ActsAsTenant.current_tenant if config.tenant_enabled? && defined?(ActsAsTenant)
+          tenant ? tenant_key(tenant.id) : CACHE_KEY
+        end
+
+        def tenant_key(tenant_id)
+          "tenant_#{tenant_id}_#{CACHE_KEY}"
+        end
+      end
+    end
+  end
+end

data/lib/permission_forge/controller_actions/mapping.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module ControllerActions
+    # Resolves a controller action to the Resource and action key that govern
+    # it. The runtime guard and the admin's controller catalog both go through
+    # here, so the admin lists exactly what the guard checks.
+    #
+    # Resolution order, for the resource and for the action key independently:
+    #   1. the controller's own `permission_forge_actions` declaration
+    #   2. config.controller_action_resolver
+    #   3. convention — controller name → model, action name → key
+    #
+    # @example
+    #   Mapping.call(controller_path: 'api/v1/customers', action_name: 'export')
+    #   # => #<struct resource="Customer", action="export", crud=nil>
+    #   Mapping.call(controller_path: 'customers', action_name: 'index')
+    #   # => #<struct resource="Customer", action="index", crud=:read>
+    class Mapping
+      # crud is the CRUD permission the action means (:read, :create, :edit,
+      # :delete), or nil for a custom action checked by its key.
+      Target = Struct.new(:resource, :action, :crud, keyword_init: true) do
+        def crud? = !crud.nil?
+
+        # What to ask PermissionedUser#can? for.
+        def permission = crud || action
+
+        # Whether the admin and the API can give this action a row: a CRUD
+        # flag, or a key that is a valid ResourceAction name. An action whose
+        # name is not a valid key (`exportCSV`) is still mapped, so the guard
+        # checks it like any other — with no row for it, that means
+        # unconfigured_action_strategy — instead of waving it through.
+        def manageable? = crud? || action.match?(KEY_FORMAT)
+      end
+
+      def self.call(...) = new(...).call
+
+      # @param conventions [Hash, nil] a caller-owned memo of controller_path =>
+      #   conventional resource, for callers that map many actions at once (the
+      #   admin's controller catalog). The guard passes none.
+      def initialize(controller_path:, action_name:, controller_class: nil, configuration: PermissionForge.configuration,
+                     conventions: nil)
+        @controller_path = controller_path.to_s
+        @action_name = action_name.to_s
+        @controller_class = controller_class
+        @configuration = configuration
+        @conventions = conventions
+      end
+
+      # @return [Target, nil] nil when the action is excluded, unmapped or
+      #   explicitly unmanaged
+      # @raise [PermissionForge::ConfigurationError] when a declaration or the
+      #   resolver names a resource or key that is not a valid name
+      def call
+        return nil if unmanaged?
+
+        resource = resource_name
+        return nil unless resource
+
+        key = explicit_key || @action_name
+        crud = crud_for(key)
+        Target.new(resource: resource, action: key, crud: crud) unless crud && skip_rest_action?
+      end
+
+      private
+
+      # Excluded controller, or the host resolver said "never managed".
+      def unmanaged?
+        @configuration.controller_excluded?(@controller_path) || resolved == false
+      end
+
+      def declared
+        @declared ||= if @controller_class.respond_to?(:pf_action_guard_options)
+                        @controller_class.pf_action_guard_options || EMPTY_OPTIONS
+                      else
+                        EMPTY_OPTIONS
+                      end
+      end
+
+      # The host resolver's answer: [resource, key], false, or nil. A raising
+      # resolver propagates, and so does an answer of any other shape —
+      # treating either as "unmanaged" would fail open.
+      def resolved
+        return @resolved if defined?(@resolved)
+
+        answer = @configuration.controller_action_resolver&.call(@controller_path, @action_name)
+        unless answer.nil? || answer == false || answer.is_a?(Array)
+          raise PermissionForge::ConfigurationError,
+                "#{@controller_path}##{@action_name}: controller_action_resolver must return " \
+                "[resource, key], false or nil, got #{answer.inspect}"
+        end
+
+        @resolved = answer
+      end
+
+      def resolved_pair
+        resolved.is_a?(Array) ? resolved : []
+      end
+
+      # Declarations are validated when they are made (normalize_options);
+      # resolver answers are validated here.
+      def resource_name
+        declared[:resource] || resolved_part(0, RESOURCE_FORMAT, 'Resource name') || conventional_resource
+      end
+
+      # A key the controller or the resolver chose, as opposed to the action name.
+      def explicit_key
+        return @explicit_key if defined?(@explicit_key)
+
+        @explicit_key = declared[:actions][@action_name] || resolved_part(1, KEY_FORMAT, 'action key')
+      end
+
+      def resolved_part(index, format, kind)
+        value = resolved_pair[index]&.to_s.presence
+        value && valid!(value, format, kind)
+      end
+
+      # A resolver answer that cannot be used is a configuration bug. Raising
+      # fails closed; treating it as "unmapped" would leave the action unchecked.
+      def valid!(value, format, kind)
+        return value if value.match?(format)
+
+        raise PermissionForge::ConfigurationError,
+              "#{@controller_path}##{@action_name}: #{value.inspect} is not a valid #{kind}"
+      end
+
+      # An explicit key means CRUD only when it is one of can?'s CRUD words
+      # (`actions: { approve: :edit }`); an action name also counts when it is
+      # a REST action.
+      def crud_for(key)
+        return CRUD_KEYS[key] if explicit_key
+
+        REST_ACTIONS[key] || CRUD_KEYS[key]
+      end
+
+      def skip_rest_action?
+        declared[:rest_actions] == false && explicit_key.nil? && REST_ACTIONS.key?(@action_name)
+      end
+
+      def conventional_resource
+        return resolve_convention unless @conventions
+
+        @conventions.fetch(@controller_path) { @conventions[@controller_path] = resolve_convention }
+      end
+
+      # 'api/v1/customers' → Api::V1::Customer, then Customer.
+      def resolve_convention
+        candidates = [@controller_path.classify, @controller_path.split('/').last.to_s.classify].uniq
+        candidates.each do |candidate|
+          klass = model_class(candidate)
+          return klass.name if klass
+        end
+        nil
+      end
+
+      # safe_constantize answers nil for a missing constant. A model that
+      # exists but fails to load raises, and that propagates: swallowing it
+      # would turn the controller into "unmapped", which the guard allows.
+      def model_class(name)
+        return nil unless name.match?(RESOURCE_FORMAT)
+
+        klass = name.safe_constantize
+        klass if klass.is_a?(Class) && klass < ActiveRecord::Base && !klass.abstract_class?
+      end
+    end
+  end
+end

data/lib/permission_forge/controller_actions.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  # Controller actions as permissions: which Resource and action key a
+  # controller action means (Mapping), whether any Permission Set manages it
+  # (ManagedIndex), and whether a user may run it (Authorizer).
+  #
+  # @api private
+  module ControllerActions
+    # Format of a ResourceAction name, and so of every action key.
+    KEY_FORMAT = /\A[a-z][a-z0-9_]{0,62}\z/
+
+    # A Resource name: a Ruby constant path (the one definition is
+    # PermissionForge::RESOURCE_NAME_FORMAT; the Resource model is autoloaded
+    # later than this file).
+    RESOURCE_FORMAT = PermissionForge::RESOURCE_NAME_FORMAT
+
+    # The before_action the guard concern installs.
+    GUARD_CALLBACK = :pf_authorize_action!
+
+    # Controller action names that mean a CRUD permission on the resource.
+    REST_ACTIONS = {
+      'index' => :read, 'show' => :read,
+      'new' => :create, 'create' => :create,
+      'edit' => :edit, 'update' => :edit,
+      'destroy' => :delete
+    }.freeze
+
+    # Action keys PermissionedUser#can? answers from the CRUD flags instead of
+    # the resource's custom actions — can?'s own table, so the two cannot drift.
+    CRUD_KEYS = PermissionForge::Concerns::ResourcePermissionChecker::CRUD_ACTIONS.transform_keys(&:to_s).freeze
+
+    EMPTY_OPTIONS = { resource: nil, actions: {}.freeze, rest_actions: true }.freeze
+
+    # Normalizes a controller's `permission_forge_actions` declaration into the
+    # frozen shape Mapping reads. The only constructor of that shape, so it is
+    # also where a declaration is validated.
+    #
+    # @param resource [String, Symbol, Class, nil]
+    # @param actions [Hash] controller action name => action key
+    # @param rest_actions [Boolean] false leaves index/show/new/... unmanaged
+    # @return [Hash] { resource: String|nil, actions: { String => String }, rest_actions: Boolean }
+    # @raise [ArgumentError] when the resource or a key is not a valid name
+    def self.normalize_options(resource: nil, actions: {}, rest_actions: true)
+      options = {
+        resource: resource_name(resource),
+        actions: actions.to_h.to_h { |name, key| [name.to_s, key.to_s] }.freeze,
+        rest_actions: rest_actions != false
+      }.freeze
+      validate_options!(options)
+      options
+    end
+
+    # Adds a declaration to the one a controller already has — its own earlier
+    # call, or an inherited one. A given resource or rest_actions replaces;
+    # actions are merged. Declaring twice therefore never drops the resource
+    # the first call named (which would leave the controller unchecked).
+    #
+    # @param current [Hash] a normalized declaration
+    # @return [Hash] a normalized, frozen declaration
+    def self.merge_options(current, **declaration)
+      rest_actions = declaration.fetch(:rest_actions, nil)
+      given = normalize_options(**declaration, rest_actions: rest_actions.nil? ? current[:rest_actions] : rest_actions)
+      { resource: given[:resource] || current[:resource],
+        actions: current[:actions].merge(given[:actions]).freeze,
+        rest_actions: given[:rest_actions] }.freeze
+    end
+
+    # A declaration the mapping could not use fails here, when the controller
+    # loads. Left alone, a typo (`resource: 'customer'`, `actions: { create:
+    # 'Merge' }`) would map the action to nothing and leave it unchecked.
+    def self.validate_options!(options)
+      resource = options[:resource]
+      if resource && !resource.match?(RESOURCE_FORMAT)
+        raise ArgumentError, "permission_forge_actions: #{resource.inspect} is not a Resource name " \
+                             "(expected a model name such as 'Customer')"
+      end
+
+      invalid = options[:actions].values.grep_v(KEY_FORMAT)
+      return if invalid.empty?
+
+      raise ArgumentError, "permission_forge_actions: invalid action key #{invalid.map(&:inspect).join(', ')} " \
+                           '(expected lowercase letters, digits and _, starting with a letter)'
+    end
+    private_class_method :validate_options!
+
+    # 'api/v1/customers' → Api::V1::CustomersController, the way the router
+    # names it; nil when there is no such class.
+    #
+    # @param controller_path [String]
+    # @return [Class, nil]
+    def self.controller_class_for(controller_path)
+      "#{controller_path}_controller".camelize.safe_constantize
+    end
+
+    # Whether the controller runs the guard: it includes the concern and has
+    # not removed the callback with a blanket skip_before_action. (A skip
+    # limited with only:/except: still counts as guarded.)
+    #
+    # @param controller_class [Class, nil]
+    # @return [Boolean]
+    # @raise [PermissionForge::ConfigurationError] when the controller's
+    #   before_action chain cannot be read (`_process_action_callbacks`, a
+    #   Rails internal): the answer is not guessed either way
+    def self.guarded?(controller_class)
+      return false unless controller_class.respond_to?(:pf_action_guard_options)
+      unless controller_class.respond_to?(:_process_action_callbacks)
+        raise PermissionForge::ConfigurationError,
+              "PermissionForge cannot read the before_action chain of #{controller_class} (_process_action_callbacks, " \
+              "ActionPack #{ActionPack.version}): this version of the gem does not support that Rails version"
+      end
+
+      controller_class._process_action_callbacks.any? { |callback| callback.filter == GUARD_CALLBACK }
+    end
+
+    def self.resource_name(resource)
+      name = resource.is_a?(Module) ? resource.name : resource
+      name.to_s.presence
+    end
+    private_class_method :resource_name
+  end
+end