permission_forge 0.14.1

data/lib/permission_forge/cache/settlement.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Cache
+    # What is invalidated once more when a transaction has committed.
+    #
+    # An invalidation made inside an open transaction comes too early for
+    # everybody else: the rows it is about are not visible to them yet, so a
+    # request that rebuilds right after it caches the rows as they were
+    # before the commit — and keeps them. (regenerate_permissions inside a
+    # transaction that reads from a snapshot leaves nothing in the cache at
+    # all, which tells nobody that something changed.) So the invalidation
+    # is made again when the outermost transaction has committed: once per
+    # key for each transaction that asked. A rollback drops it, because
+    # nothing changed.
+    #
+    # Used for a user's permission hash (PermissionCacheAccessor, inside a
+    # transaction that reads from a snapshot) and for the managed-actions
+    # index (ControllerActions::ManagedIndex, inside any open transaction).
+    #
+    # @api private
+    class Settlement
+      # The settlement of each open transaction, by the adapter's transaction
+      # object. Keys and values are held weakly: a settlement lives as long
+      # as the commit hook it is registered as.
+      PENDING = ObjectSpace::WeakMap.new
+
+      # @param transaction [PermissionForge::OpenTransaction]
+      # @return [Settlement] the one of this transaction
+      def self.for(transaction)
+        subject = transaction.subject
+        PENDING[subject] ||= new.tap { |settlement| transaction.after_commit { settlement.call } }
+      end
+
+      def initialize
+        @work = {}
+      end
+
+      # @param key [Object] what is invalidated (e.g. [:user, id, tenant_id]):
+      #   the first block given for a key is the one that runs
+      # @return [void]
+      def add(key, &block)
+        @work[key] ||= block
+      end
+
+      # Runs among the commit callbacks of the transaction, so nothing is
+      # raised: Rails would skip the callbacks that come after it.
+      #
+      # @return [void]
+      def call
+        @work.each_value { |block| run(block) }
+      end
+
+      private
+
+      def run(block)
+        block.call
+      rescue StandardError => e
+        Failure.report(operation: :after_commit, error: e)
+      end
+    end
+  end
+end

data/lib/permission_forge/cache/user_keys.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Cache
+    # Where a user's permission hash and invalidation stamp live, and what an
+    # invalidation of the user removes — one definition for
+    # User#invalidate_permissions (PermissionCacheAccessor) and for the
+    # invalidation of many holders by id (HolderInvalidation). A key added to
+    # one is added to both.
+    #
+    # The entries live under ENTRY_NAMESPACE ("v2:user_<id>",
+    # "v2:tenant_<tenant id>_user_<id>"), bumped when their format changes
+    # (0.14: the base entry of a user with conditional sets carries them under
+    # :conditional_sets), so that during a rolling deploy a process running
+    # another version never reads an entry it would misread. An invalidation
+    # removes the keys of the previous namespaces as well
+    # (PREVIOUS_ENTRY_NAMESPACES), so a change made through either version
+    # reaches both. The stamp is not namespaced: every version must see it.
+    #
+    # An invalidation removes the base entries, and reads nothing: the
+    # per-context variants of a user with conditional sets cannot be reached
+    # once the base entry that carries their token is gone, and are left to
+    # their TTL (ConditionalSets). Where they must go now — erasure,
+    # cache:clear — .variant_removals names them: the index entry of each
+    # base entry of this namespace is read (a few bytes, written only for a
+    # user who had a variant stored; one call for many users where the store
+    # can, Base#read_many), and every slot of a base entry that has one
+    # (ConditionalSets.variant_keys) goes with it.
+    #
+    # @api private
+    module UserKeys
+      ENTRY_NAMESPACE = 'v2'
+      # '' is the bare key of 0.13. Drop in 0.15.
+      PREVIOUS_ENTRY_NAMESPACES = [''].freeze
+
+      module_function
+
+      # Every namespace an entry may be under: this version's and the previous ones.
+      #
+      # @return [Array<String>]
+      def namespaces
+        [ENTRY_NAMESPACE, *PREVIOUS_ENTRY_NAMESPACES]
+      end
+
+      # What the permission entries of a namespace look like, for a store that
+      # removes keys by pattern (Base#clear_entries): the keys of every user
+      # — any id, a prefixed string one included — tenant-agnostic and per
+      # tenant, and their variants. Nothing else of the gem under the bare
+      # namespace matches the Regexp: not the stamps (`_invalidation`), not
+      # the managed-actions index. The globs, which cannot say "not followed
+      # by", take the stamps along with the bare keys. The Regexp starts with
+      # `^`, the one anchor ActiveSupport's key_matcher keeps when it puts the
+      # store's own namespace in front (a `\A` would be prefixed with `.*`
+      # and never match).
+      #
+      # @param namespace [String]
+      # @param prefix [String] the store's key prefix (Base#prefix)
+      # @return [Array(Regexp, Array<String>)] the Regexp, and the globs
+      def entry_patterns(namespace, prefix:)
+        lead = Regexp.escape(entry_lead(namespace, prefix))
+        regexp = /^#{lead}(tenant_.+_)?user_(?!.*_invalidation\z).+\z/
+        globs = ["#{entry_lead(namespace, prefix)}user_*", "#{entry_lead(namespace, prefix)}tenant_*_user_*"]
+        [regexp, globs]
+      end
+
+      # Two entries no user can have, one of each key shape, under
+      # `namespace`: written before a removal by pattern and read after it,
+      # they say whether the pattern reached the store's keys at all
+      # (Base#clear_entries).
+      #
+      # @return [Array<String>] the tenant-agnostic and the tenant key
+      def canary_keys(namespace)
+        [hash_key(CANARY, nil, namespace: namespace), hash_key(CANARY, CANARY, namespace: namespace)]
+      end
+
+      # An id no host key has (not an integer, not a uuid).
+      CANARY = 'pf-canary'
+
+      def entry_lead(namespace, prefix)
+        namespace.empty? ? "#{prefix}:" : "#{prefix}:#{namespace}:"
+      end
+
+      # The key of the user's base entry in a tenant — the ambient one unless
+      # named; nil: the tenant-agnostic key — in this namespace
+      # (PermissionCacheAccessor#permission_cache_key).
+      #
+      # @param user_id [Object]
+      # @param tenant_id [Object, nil]
+      # @param namespace [String] ENTRY_NAMESPACE, or a previous one
+      # @return [String]
+      def hash_key(user_id, tenant_id = PermissionForge.ambient_tenant_id, namespace: ENTRY_NAMESPACE)
+        key = tenant_id ? "tenant_#{tenant_id}_user_#{user_id}" : "user_#{user_id}"
+        namespace.empty? ? key : "#{namespace}:#{key}"
+      end
+
+      # One per user, whatever the tenant and the version (see Cache::Invalidation).
+      #
+      # @param user_id [Object]
+      # @return [String]
+      def stamp_key(user_id)
+        "user_#{user_id}_invalidation"
+      end
+
+      # The keys a base entry of the user may be under — in the ambient
+      # tenant, in no tenant, and in the tenant the caller named (a callback
+      # on a tenant-scoped record) — in this namespace, and in the previous
+      # ones.
+      #
+      # @param user_id [Object]
+      # @param tenant_id [Object, nil]
+      # @param ambient_key [String] the key under the ambient tenant, when
+      #   the user instance names its own (#permission_cache_key)
+      # @return [Array(Array<String>, Array<String>)] this namespace's keys,
+      #   the previous namespaces' keys
+      def base_keys(user_id, tenant_id: nil, ambient_key: hash_key(user_id))
+        current = ([ambient_key] + [nil, tenant_id].uniq.map { |tenant| hash_key(user_id, tenant) }).uniq
+        previous = PREVIOUS_ENTRY_NAMESPACES.flat_map { |namespace| current.map { |key| in_namespace(key, namespace) } }
+        [current, previous]
+      end
+
+      # `key`, of this namespace, in another one ('' : the bare key of 0.13).
+      def in_namespace(key, namespace)
+        bare = key.delete_prefix("#{ENTRY_NAMESPACE}:")
+        namespace.empty? ? bare : "#{namespace}:#{bare}"
+      end
+
+      # The arguments of the user's Invalidation: the stamp, and every key —
+      # this namespace's, then the previous namespaces'.
+      #
+      # @param user_id [Object]
+      # @param tenant_id [Object, nil]
+      # @param named [Hash] the keys a user instance names itself, when it
+      #   does: ambient_key: (#permission_cache_key), stamp_key:
+      #   (#pf_invalidation_stamp_key)
+      # @return [Hash] user_id:, stamp_key:, keys:
+      def invalidation(user_id, tenant_id: nil, **named)
+        invalidations([user_id], tenant_id: tenant_id, **named).first
+      end
+
+      # The invalidations of many users.
+      #
+      # @param user_ids [Array]
+      # @param tenant_id [Object, nil]
+      # @return [Array<Hash>] one per user (see .invalidation)
+      def invalidations(user_ids, tenant_id: nil, **named)
+        user_ids.map do |user_id|
+          current, previous = base_keys(user_id, tenant_id: tenant_id, **named.slice(:ambient_key))
+          target(user_id, current + previous, named)
+        end
+      end
+
+      # The removals of the per-context variants of many users
+      # (Cache::VariantRemoval): for each base entry of this namespace, its
+      # index entry and every slot (ConditionalSets.variant_keys). With
+      # `indexed_only` (cache:clear, many users) only the base entries whose
+      # index entry is found — read in one call — and a user none of whose
+      # base entries has one is left out. Without it (erasure, one person)
+      # nothing is read: a store that fails a read answers "nothing", and the
+      # store may have evicted the index entry.
+      #
+      # @param user_ids [Array]
+      # @param tenant_id [Object, nil]
+      # @param named [Hash] ambient_key:, stamp_key:, as for .invalidation;
+      #   indexed_only: (default true)
+      # @return [Array<Hash>] user_id:, stamp_key:, keys: — the arguments of
+      #   an Invalidation
+      def variant_removals(user_ids, tenant_id: nil, **named)
+        keyed = user_ids.map { |user_id| [user_id, base_keys(user_id, tenant_id: tenant_id, **named.slice(:ambient_key)).first] }
+        indexes = keyed.flat_map { |_user_id, current| current.map { |key| index_key(key) } }
+        found = named.fetch(:indexed_only, true) ? read_indexes(indexes) : EVERY_KEY
+        keyed.filter_map do |user_id, current|
+          keys = slot_keys(current, found)
+          target(user_id, keys, named) if keys.any?
+        end
+      end
+
+      # Answers every index entry as found.
+      EVERY_KEY = Hash.new(true).freeze
+
+      # The arguments of an Invalidation of the user (stamp_key: as named, else the user's own).
+      def target(user_id, keys, named)
+        { user_id: user_id, stamp_key: named.fetch(:stamp_key) { stamp_key(user_id) }, keys: keys }
+      end
+
+      # For each base key whose index entry was found: the index entry and every slot.
+      def slot_keys(base_keys, found)
+        conditional = PermissionForge::ConditionalSets
+        base_keys.select { |key| found[index_key(key)] }.flat_map { |key| [index_key(key), *conditional.variant_keys(key)] }
+      end
+
+      def index_key(key)
+        PermissionForge::ConditionalSets.index_key(key)
+      end
+
+      # A read that raises tells nothing about the index entries: each counts
+      # as found, so every slot is removed rather than none.
+      #
+      # @return [Hash{String => Object}]
+      def read_indexes(keys)
+        PermissionForge.cache.read_many(keys)
+      rescue StandardError
+        keys.to_h { |key| [key, true] }
+      end
+    end
+  end
+end

data/lib/permission_forge/cache/variant_removal.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Cache
+    # Removes the per-context variants of users with conditional permission
+    # sets, where the personal data they hold (the profile) must go now:
+    # Services::DataSubjectErasure and the enumerated
+    # Services::PermissionCacheClearer. An invalidation leaves them to their
+    # TTL: no read can reach them once the base entry that carries their
+    # token is gone (ConditionalSets).
+    #
+    # For the clear (indexed_only, many users) the users' index entries are
+    # read (UserKeys.variant_removals, one call per SLICE users), and for each
+    # one found the index entry and every slot of its base entry go. For an
+    # erasure (one person) nothing is read: the index entry and every slot of
+    # each of the person's base entries go — a read that fails silently, or
+    # an index entry the store evicted, cannot leave a variant behind. Either
+    # way the keys are removed the way an invalidation removes them
+    # (BulkInvalidation: a fresh stamp first, every answer checked, retries,
+    # what fails reported through Cache::Failure and owed).
+    #
+    # Callers run it after the users' invalidation. A variant whose rebuild
+    # read the stamp before that invalidation was then either verified
+    # before it — its index entry, written first, is found here — or is
+    # discarded by its verification. A rebuild still in flight that reads the
+    # stamp after the removal's and writes after it leaves a variant built
+    # from the rows as they are then (its profile from that request's user
+    # instance, which may predate the change): unreachable, gone with its TTL.
+    #
+    # @api private
+    class VariantRemoval
+      def self.call(...) = new(...).call
+
+      # @param user_ids [Array]
+      # @param tenant_id [Object, nil] the tenant whose base keys to include
+      #   besides the ambient and the tenant-agnostic ones (UserKeys.base_keys)
+      # @param indexed_only [Boolean] only the base entries whose index entry
+      #   is found (false: every base entry, nothing read)
+      # @param named [Hash] ambient_key: — the key a single user instance
+      #   names (#permission_cache_key)
+      def initialize(user_ids:, tenant_id: nil, indexed_only: true, **named)
+        @user_ids = user_ids
+        @tenant_id = tenant_id
+        @named = named.merge(indexed_only: indexed_only)
+      end
+
+      # @return [Array] the ids whose removal the store did not confirm
+      def call
+        @user_ids.each_slice(HolderInvalidation::SLICE).flat_map do |slice|
+          BulkInvalidation.unconfirmed(UserKeys.variant_removals(slice, tenant_id: @tenant_id, **@named))
+        end
+      end
+    end
+  end
+end

data/lib/permission_forge/cache/withheld_notice.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Cache
+    # Says once per process that permission hashes keep being built inside a
+    # database transaction that reads from a snapshot, where they are not
+    # cached (PermissionCacheAccessor#pf_rebuild_permissions, config.snapshot_transactions).
+    #
+    # One such rebuild is nothing to mention. A job that only reads
+    # permissions inside the transaction of each save, or an application that
+    # wraps every request in a transaction, never caches a hash, though, and
+    # rebuilds the permissions every time — and nothing else would tell it
+    # why. So the rebuilds that were withheld are counted until one runs
+    # outside such a transaction again, and the count reaching AFTER is
+    # logged, once.
+    #
+    # @api private
+    module WithheldNotice
+      AFTER = 20
+      MUTEX = Mutex.new
+
+      class << self
+        # @return [void]
+        def withheld
+          say = MUTEX.synchronize do
+            @in_a_row = (@in_a_row || 0) + 1
+            @in_a_row == AFTER && !@said && (@said = true)
+          end
+          log if say
+        end
+
+        # A rebuild ran outside a transaction: the count starts again.
+        #
+        # @return [void]
+        def not_withheld
+          MUTEX.synchronize { @in_a_row = 0 }
+        end
+
+        # For tests: the notice can be given again.
+        def reset!
+          MUTEX.synchronize { @in_a_row = @said = nil }
+        end
+
+        private
+
+        def log
+          return unless defined?(Rails) && Rails.logger
+
+          Rails.logger.warn(
+            "[PermissionForge] The last #{AFTER} permission rebuilds ran inside a database transaction that reads from " \
+            'a snapshot, so none of them was cached: such a hash may be older than a change that was already ' \
+            'invalidated. Read the permissions once (current_user.permissions_hash) before the loop of saves or the ' \
+            'transaction — or, if this database runs at READ COMMITTED, set config.snapshot_transactions = false. ' \
+            'This is logged once per process.'
+          )
+        end
+      end
+    end
+  end
+end

data/lib/permission_forge/concerns/audited_collection.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Concerns
+    # Association extension (`has_many ..., extend: AuditedCollection`) for
+    # the collections the gem declares on its models and on the host's User.
+    #
+    # Rails' `collection.delete_all` and `collection.clear` remove rows with
+    # one SQL statement and run no callbacks — even under
+    # `dependent: :destroy` — so an assignment or membership removed that way
+    # would leave no audit event and keep the person's cached permissions.
+    # Here they remove each record the way `collection.delete(record)` does
+    # (destroy under `dependent: :destroy`, the `before_remove` callbacks
+    # otherwise), inside one transaction.
+    #
+    # An explicit strategy (`delete_all(:delete_all)`, `delete_all(:nullify)`)
+    # and a narrowed relation (`collection.where(...).delete_all`, which
+    # Rails extends with this module too) are the caller asking for SQL and
+    # are left to Rails, like `Model.where(...).delete_all`.
+    #
+    # @api public
+    module AuditedCollection
+      # @return [Integer] the number of records removed
+      def delete_all(dependent = nil)
+        return super if dependent
+        return super() unless is_a?(ActiveRecord::Associations::CollectionProxy)
+
+        records = load_target.dup
+        delete(*records) if records.any?
+        records.size
+      end
+    end
+  end
+end

data/lib/permission_forge/concerns/auto_permission_scoping.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Concerns
+    # Level 1 — ENFORCE (config.auto_query_scoping = :filter_only).
+    #
+    # Class methods backing the default_scope installed by
+    # {PermissionScopedFindable}: every relation built on a protected model
+    # applies the current user's FILTER-type rules automatically. Extracted
+    # from PermissionScopedFindable for SRP — this module owns the auto-scope
+    # decision tree, the host concern owns find_by/permission_scoped.
+    #
+    # Every path that lets a query past the rules while Level 1 is on is
+    # published as rule.bypassed (scope_suspended, auto_scope_opt_out,
+    # nil_user, view_all, modify_all, no_rules) and a nil user under :deny /
+    # :raise as access.denied — at most once per request per model, reason
+    # and user (Audit::Runtime.once?): this runs on every relation built.
+    #
+    # @api private
+    module AutoPermissionScoping
+      extend ActiveSupport::Concern
+
+      # Set while the gem suspends Level 1 for its own queries
+      # (internally_suspended): that suspension is not the host's, is not
+      # reported, and gives nobody signed in no bypass.
+      INTERNAL_SUSPENSION_KEY = :pf_internal_scope_suspension
+
+      # Set while the default scope builds the rules (re-entrancy guard).
+      IN_HOOK_KEY = :pf_in_auto_scope_hook
+
+      # The gem's own suspension of the scoping, for the queries it makes for
+      # itself and the host code they run (callbacks, default scopes): Level 1
+      # and detection are off, as in the host's block, but it is not the
+      # host's opt-out — not reported as scope_suspended, and nobody signed in
+      # gets no bypass of nil_user_strategy. Both flags are :fiber slots of
+      # ExecutionState, so they move together.
+      def self.internally_suspended(&)
+        PermissionForge::ExecutionState.with(INTERNAL_SUSPENSION_KEY, true) do
+          PermissionForge.without_permission_scope(&)
+        end
+      end
+
+      # @return [Boolean] whether the gem suspended the scoping for itself
+      def self.internally_suspended?
+        PermissionForge::ExecutionState[INTERNAL_SUSPENSION_KEY] == true
+      end
+
+      # @return [Boolean] whether the host suspended the scoping
+      #   (PermissionForge.without_permission_scope), as opposed to the gem
+      #   for its own queries
+      def self.host_suspended?
+        PermissionForge.scope_suspended? && !internally_suspended?
+      end
+
+      class_methods do
+        # Level 1 hook body. Public because the default_scope block delegates
+        # to the model class through Relation#method_missing (public dispatch).
+        #
+        # Every path taken while Level 1 is enabled annotates the relation as
+        # scoped — including bypasses (view_all, no rules, nil-user :bypass):
+        # the query went through the permission check, so Level 2 detection
+        # must treat it as compliant and flag only true escapes
+        # (unscoped, find_by_sql, raw SQL).
+        #
+        # @return [ActiveRecord::Relation]
+        def pf_auto_permission_scope
+          return all unless pf_auto_scope_applicable?
+          # Re-entrancy guard: current_user_resolver or a permissions rebuild
+          # may itself query a protected model — that inner query runs unscoped
+          # (identity resolution precedes authorization) instead of recursing.
+          return all.annotate(PermissionScopedFindable::SCOPED_ANNOTATION) if PermissionForge::ExecutionState[IN_HOOK_KEY]
+
+          PermissionForge::ExecutionState.with(IN_HOOK_KEY, true) do
+            pf_build_auto_scope.annotate(PermissionScopedFindable::SCOPED_ANNOTATION)
+          end
+        end
+
+        private
+
+        # The same three conditions as ever; the order only decides which
+        # bypass is reported (none while Level 1 is off).
+        def pf_auto_scope_applicable?
+          return false unless PermissionForge.configuration.auto_query_scoping_enabled?
+
+          if PermissionForge.scope_suspended?
+            pf_auto_scope_bypassed(:scope_suspended) if AutoPermissionScoping.host_suspended?
+            return false
+          end
+          return true if permission_forge_auto_scope
+
+          pf_auto_scope_bypassed(:auto_scope_opt_out)
+          false
+        end
+
+        def pf_auto_scope_bypassed(reason, user = nil)
+          return unless PermissionForge::Audit::Runtime::BYPASS_GATE.open?
+
+          PermissionForge::Audit::Runtime.bypassed(reason, model: self, via: 'auto_scope', user: user, once: true)
+        end
+
+        # The rules do not apply: reported, and the relation as it is.
+        def pf_unscoped_by(reason, user)
+          pf_auto_scope_bypassed(reason, user)
+          all
+        end
+
+        def pf_build_auto_scope
+          current_user = PermissionForge.current_user
+          return pf_nil_user_auto_scope unless current_user
+
+          # Resolve the rules once — permissions_hash is a cache read per
+          # call, and this hook runs on every relation build: those of this
+          # class's Resource entry and of its STI ancestors' (ResourceChain).
+          # view_all/modify_all bypasses rules (parity with find_by). The
+          # on_rule_bypass hook is deliberately NOT fired here — it would fire
+          # on every query the user runs; rule.bypassed is, once per request.
+          rules, bypass = PermissionForge::ResourceChain.rules(current_user, PermissionForge::ResourceChain.names(self))
+          return pf_unscoped_by(bypass, current_user) if bypass
+
+          rules = rules.select { |rule| pf_filter_rule?(rule) }
+          return pf_unscoped_by(:no_rules, current_user) if rules.empty?
+
+          # INVARIANT: PermissionRuleApplier builds from @model_class.where(nil),
+          # which inside this default_scope block resolves against the in-flight
+          # current_scope — preserving acts_as_tenant and any host default_scope
+          # (soft-delete) in either declaration order. Never change the applier
+          # to unscoped/fresh relations.
+          PermissionForge::Services::PermissionRuleApplier.scope(
+            model_class: self, rules: rules, current_user: current_user
+          )
+        end
+
+        # Fail closed for :deny AND :raise — raising from inside a default_scope
+        # would detonate in consoles, rake tasks, and view-layer counts, so the
+        # strictest safe behavior is an empty relation (documented deviation).
+        def pf_nil_user_auto_scope
+          case PermissionForge.configuration.nil_user_strategy
+          when :deny, :raise
+            PermissionForge::Audit::Runtime.denied(PermissionForge::Audit::Runtime::DENIED, reason: :nil_user, model: self,
+                                                                                            via: 'auto_scope', once: true)
+            none
+          else # :bypass
+            pf_auto_scope_bypassed(:nil_user)
+            all
+          end
+        end
+
+        # Filter-type rules only: join-type rules inside a default_scope would
+        # break includes/count/pluck and duplicate rows, so they remain the job
+        # of permission_scoped (a boot warning fires when join rules exist while
+        # Level 1 is enabled).
+        def pf_filter_rule?(rule)
+          PermissionForge::PermissionSetRule.filter_join_type?(rule[:join_type])
+        end
+      end
+    end
+  end
+end

data/lib/permission_forge/concerns/controller_action_guard.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Concerns
+    # Runtime guard for host controllers: checks every action against the
+    # current user's Permission Sets before it runs.
+    #
+    #   class CustomersController < ApplicationController
+    #     include PermissionForge::Concerns::ControllerActionGuard
+    #   end
+    #
+    #   class Customers::MergesController < ApplicationController
+    #     include PermissionForge::Concerns::ControllerActionGuard
+    #     permission_forge_actions resource: 'Customer', actions: { create: :merge }
+    #   end
+    #
+    # The guard never renders or redirects. A denied action raises
+    # PermissionForge::ActionNotAuthorizedError — rescue it in the host app:
+    #
+    #   rescue_from PermissionForge::ActionNotAuthorizedError do
+    #     head :forbidden
+    #   end
+    #
+    # The decision itself lives in {PermissionForge::ControllerActions::Authorizer}.
+    #
+    # @api public
+    module ControllerActionGuard
+      extend ActiveSupport::Concern
+
+      included do
+        # The controller's declaration, in the shape ControllerActions::Mapping
+        # reads. Class-level only: a public instance reader would be routable
+        # as a controller action.
+        class_attribute :pf_action_guard_options, instance_accessor: false, instance_predicate: false,
+                                                  default: PermissionForge::ControllerActions::EMPTY_OPTIONS
+
+        before_action :pf_authorize_action!
+      end
+
+      class_methods do
+        # Declares which Resource and action keys this controller's actions
+        # mean. Subclasses inherit the declaration. Declaring again — in the
+        # same class or a subclass — adds to it: a given resource or
+        # rest_actions replaces, actions are merged.
+        #
+        # @param resource [String, Symbol, Class, nil] Resource name; nil keeps
+        #   the convention (controller name → model)
+        # @param actions [Hash] controller action name => action key
+        #   (`{ create: :merge }`); a CRUD word (`:edit`) checks that CRUD flag
+        # @param rest_actions [Boolean, nil] false leaves index/show/new/create/
+        #   edit/update/destroy unchecked unless listed in `actions`; nil keeps
+        #   the current setting (checked, unless an earlier declaration said false)
+        # @return [Hash] the normalized, frozen declaration
+        # @raise [ArgumentError] when the resource or a key is not a valid name
+        def permission_forge_actions(resource: nil, actions: {}, rest_actions: nil)
+          self.pf_action_guard_options = PermissionForge::ControllerActions.merge_options(
+            pf_action_guard_options, resource: resource, actions: actions, rest_actions: rest_actions
+          )
+        end
+      end
+
+      private
+
+      # A denial is published as action.denied, an allowed request that
+      # skipped the Permission Sets (no user under :bypass, the bypass lambda,
+      # an action nobody manages) as rule.bypassed.
+      #
+      # @raise [PermissionForge::ActionNotAuthorizedError] when the current
+      #   user may not run this action
+      def pf_authorize_action!
+        user = PermissionForge.current_user
+        decision = PermissionForge::ControllerActions::Authorizer.call(
+          controller_path: controller_path, action_name: action_name, controller: self, user: user
+        )
+        return pf_action_allowed(decision, user) if decision.allowed?
+
+        target = decision.target
+        pf_action_denied(decision, user)
+        raise PermissionForge::ActionNotAuthorizedError.new(
+          resource: target.resource, action: target.action, controller_path: controller_path,
+          reason: decision.reason, user: user
+        )
+      end
+
+      def pf_action_allowed(decision, user)
+        reason = decision.bypass_reason
+        return unless reason
+
+        PermissionForge::Audit::Runtime.bypassed(reason, model: decision.target.resource, via: 'action_guard', user: user,
+                                                         data: pf_action_event_data(decision))
+      end
+
+      def pf_action_denied(decision, user)
+        PermissionForge::Audit::Runtime.denied(
+          PermissionForge::Audit::Runtime::ACTION_DENIED, reason: decision.reason, model: decision.target.resource,
+                                                          via: 'action_guard', user: user,
+                                                          data: pf_action_event_data(decision)
+        )
+      end
+
+      def pf_action_event_data(decision)
+        { 'action' => decision.target.action, 'controller' => controller_path, 'action_name' => action_name }
+      end
+    end
+  end
+end