permission_forge 0.14.1

data/lib/permission_forge/deprecation.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  # The gem's deprecations: one ActiveSupport::Deprecation for every renamed
+  # or removed public API (the README "Versioning and stability" surface).
+  #
+  # Convention: a public API is never renamed or removed in one step. The
+  # release that changes it keeps the old name working for at least one
+  # minor version, warning through {PermissionForge.deprecator}, and lists it
+  # under "Deprecated" in the CHANGELOG; the release at HORIZON removes it.
+  #
+  #   # a renamed method or configuration option (reader and writer): the old
+  #   # name calls the new one — not alias_method, which would skip the
+  #   # writers Configuration prepends (validation, the preset's bookkeeping)
+  #   def old_name = new_name
+  #   def old_name=(value)
+  #     self.new_name = value
+  #   end
+  #   PermissionForge.deprecator.deprecate_methods(self, old_name: :new_name, 'old_name=': :'new_name=')
+  #   # a removed behaviour, warned once per process
+  #   PermissionForge::Deprecation.warn('passing a String is deprecated; pass a Symbol')
+  #
+  # In a Rails application the deprecator is registered as
+  # `Rails.application.deprecators[:permission_forge]`, so the host's
+  # `config.active_support.deprecation` (:stderr, :log, :raise, :silence…),
+  # `disallowed_deprecation` and `Rails.application.deprecators.silence { }`
+  # govern it as they govern Rails' own.
+  #
+  # @api private
+  module Deprecation
+    # The version that removes what is deprecated now. A test fails once
+    # VERSION reaches it: remove the deprecated code, then move the horizon.
+    HORIZON = '0.15'
+    GEM_NAME = 'PermissionForge'
+
+    DEPRECATOR = ActiveSupport::Deprecation.new(HORIZON, GEM_NAME)
+
+    WARNED_MUTEX = Mutex.new
+    private_constant :WARNED_MUTEX
+
+    @warned = Set.new
+
+    class << self
+      # @return [ActiveSupport::Deprecation]
+      def deprecator = DEPRECATOR
+
+      # Warns through the deprecator the first time `key` is seen in this
+      # process, so a deprecated call on a hot path does not flood the log.
+      # A warning that raised (behavior :raise) or was silenced is not
+      # remembered: the next call warns (or raises) again. The message says
+      # what to use instead; the version that removes it is added.
+      #
+      # @param message [String] e.g. "passing a String is deprecated; pass a Symbol"
+      # @param key [Object] what "once" is counted by (default: the message)
+      # @return [void]
+      def warn(message, key: message, callstack: caller_locations(1))
+        return if WARNED_MUTEX.synchronize { @warned.include?(key) }
+
+        DEPRECATOR.warn("#{message}. #{GEM_NAME} #{HORIZON} removes it.", callstack)
+        WARNED_MUTEX.synchronize { @warned << key } unless DEPRECATOR.silenced
+      end
+
+      # Forgets which keys warned (for tests that check a warning).
+      #
+      # @return [void]
+      def reset!
+        WARNED_MUTEX.synchronize { @warned.clear }
+      end
+
+      # Hands the deprecator to the application's deprecators (Rails 7.1+).
+      #
+      # @param app [Rails::Application]
+      # @return [void]
+      def register(app)
+        app.deprecators[:permission_forge] = DEPRECATOR if app.respond_to?(:deprecators)
+      end
+    end
+  end
+
+  # @return [ActiveSupport::Deprecation] the gem's deprecator
+  def self.deprecator = Deprecation.deprecator
+end
+
+# Runs when the application starts initializing, or at once when it already
+# has (the gem required late).
+ActiveSupport.on_load(:before_initialize, yield: true) { |app| PermissionForge::Deprecation.register(app) }

data/lib/permission_forge/engine.rb

@@ -0,0 +1,113 @@
+require_relative 'query_scoping_warnings'
+require_relative 'boot_checks'
+require_relative 'masking_sync'
+require_relative 'masked_models'
+
+module PermissionForge
+  # Wires the gem into the host application: initializers, the executor and
+  # reloader hooks, the boot checks. The work is done by plain modules
+  # (BootChecks, MaskingSync, Audit, ...).
+  #
+  # @api public
+  class Engine < ::Rails::Engine
+    isolate_namespace PermissionForge
+
+    config.generators do |g|
+      g.test_framework :minitest
+    end
+
+    # The models (app/models/permission_forge) are autoloaded like any engine
+    # model: their class bodies read the configuration after the host's
+    # config/initializers, so nothing is re-declared after boot. No engine
+    # initializer may reference them — the application's autoloader is set up
+    # after every initializer has run (Rails 7.1+).
+
+    # The admin UI's CSS/JS/brand files are served by PermissionForge::AssetsController
+    # straight from app/frontend — no Sprockets/Propshaft/importmap registration needed.
+
+    initializer 'permission_forge.i18n' do
+      locale_dir = root.join('config', 'locales')
+      allowed = PermissionForge.configuration.available_locales || PermissionForge::BUNDLED_LOCALES
+
+      if allowed.present?
+        pattern = "{#{Array(allowed).join(',')}}"
+        config.i18n.load_path += Dir[locale_dir.join("permission_forge.#{pattern}.yml")]
+      else
+        config.i18n.load_path += Dir[locale_dir.join('permission_forge.*.yml')]
+      end
+    end
+
+    initializer 'permission_forge.append_routes' do |_app|
+      # Routes are only active when the engine is mounted — no automatic injection
+    end
+
+    initializer 'permission_forge.filter_parameters', after: :load_config_initializers do |app|
+      pf_config = PermissionForge.configuration
+      if pf_config.gdpr_defaults && pf_config.filter_parameters_integration
+        new_filters = PermissionForge.gdpr_filter_parameters
+        app.config.filter_parameters += new_filters
+
+        Rails.logger.info "[PermissionForge] Added #{new_filters.size} GDPR patterns to filter_parameters."
+      end
+    end
+
+    # Tenancy needs the acts_as_tenant gem: refuse to boot without it. The
+    # scope itself is declared by each model as it loads (HasTenantScoping).
+    initializer 'permission_forge.tenant_scoping', after: :load_config_initializers do
+      PermissionForge::BootChecks.ensure_tenancy_gem!(PermissionForge.configuration)
+    end
+
+    # Audit event log: install the notification subscribers (Audit::Subscribers
+    # — log, store and legacy-hook adapters register there) and reset the
+    # audit context at the end of every executor run.
+    initializer 'permission_forge.audit', after: :load_config_initializers do |app|
+      PermissionForge::Audit.install!(app)
+      PermissionForge::Audit::JobContext.install!
+    end
+
+    # Level 2 — install the unscoped-query detection subscriber once config is
+    # final. The per-event check re-reads config, so the subscriber is only
+    # installed when detection could ever be active (avoids a no-op subscriber
+    # on every query in production).
+    initializer 'permission_forge.unscoped_query_detection', after: :load_config_initializers do
+      PermissionForge::Services::UnscopedQueryDetector.install! if PermissionForge.configuration.unscoped_query_detection != :off
+    end
+
+    # Auto-applied masking in every process (MaskingSync): a check at the
+    # start of each request and job, and a re-apply after a code reload.
+    # Installed whatever the settings say now: one may be switched on after
+    # the boot step (check! costs nothing while both are off).
+    initializer 'permission_forge.masking_sync' do |app|
+      app.executor.to_run { PermissionForge::MaskingSync.check! }
+    end
+
+    config.to_prepare { PermissionForge::MaskingSync.reloaded! }
+
+    config.after_initialize do
+      PermissionForge::BootChecks.run(PermissionForge.configuration)
+    end
+
+    # A setting a model reads as it loads (user_class, audit_user_class,
+    # tenant_model) changed by the host's own after_initialize, once a
+    # production boot has eager-loaded the models: the classes keep what they
+    # declared (a development process would pick the change up). Registered
+    # after config/initializers so it runs after the after_initialize blocks
+    # declared there; nothing loads a model.
+    initializer 'permission_forge.model_bindings', after: :load_config_initializers do |app|
+      app.config.after_initialize { PermissionForge::ModelBindings.warn! }
+    end
+
+    # Deprecated: the masking machinery left the Engine (0.14). Removed in
+    # PermissionForge::Deprecation::HORIZON.
+    #
+    # @return [Boolean] what MaskedModels.apply returns
+    def self.apply_masked_attributes_to_managed_models(only: nil)
+      PermissionForge::Deprecation.warn(
+        'PermissionForge::Engine.apply_masked_attributes_to_managed_models is deprecated; ' \
+        'use PermissionForge::MaskedModels.apply(only:)',
+        callstack: caller_locations(1) # the host's call, not this method
+      )
+      PermissionForge::MaskedModels.apply(only: only)
+    end
+  end
+end

data/lib/permission_forge/execution_state.rb

@@ -0,0 +1,318 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  # The one place the gem keeps state for the code running right now: a
+  # flag set inside a block, the record being read, the build in progress.
+  # Nothing else in lib/ or app/ touches `Thread.current`, `Fiber[]`,
+  # ActiveSupport::IsolatedExecutionState or a CurrentAttributes class
+  # (test/permission_forge/execution_state_test.rb fails when something
+  # does; its ALLOWED list names the exceptions and why).
+  #
+  # Every slot is listed in KEYS with what it holds, where it is kept and
+  # what the end of an executor run (a request, a job) does to it.
+  #
+  # Where (`scope`):
+  #
+  #   - :fiber — the running fiber, whatever Rails' isolation level says
+  #     (Thread#[], which is fiber-local). For every slot whose value,
+  #     seen by code it was not set for, would widen access (a scope
+  #     suspended, a mask lifted, a re-entrant build answered with {}) or
+  #     drop audit events (an emission or a read in progress): another
+  #     fiber of the thread — an Enumerator iterated with #next, a
+  #     streaming template — never sees it, and a fiber left paused inside
+  #     the block takes it with it.
+  #   - :execution — ActiveSupport::IsolatedExecutionState: per thread
+  #     under Rails' `:thread` isolation (the fibers of the thread share
+  #     it, as they share ActiveRecord's connection and CurrentAttributes),
+  #     per fiber under `:fiber`. For state that has to be seen wherever
+  #     the request's code runs: the audit context, the open invalidation
+  #     batch of the connection, and the cache failures (a failure reported
+  #     in an Enumerator's fiber must still count for the Failure.none?
+  #     around it).
+  #
+  # At the end of a run (`at_run_end`):
+  #
+  #   - :clean — what the run added is removed, and nothing else: a slot
+  #     that was empty when the run started is emptied, a collection that
+  #     was there loses the entries the run added, and a slot that held a
+  #     value is left alone. A request or job run starts empty, so there
+  #     the slot is emptied, and nothing a request left set reaches the
+  #     next one on the thread. Nothing is ever written back: a run may
+  #     complete after the block it started in has ended
+  #     (ActionDispatch::Executor completes it when the server closes the
+  #     body, after the middlewares above it returned), and writing the
+  #     block's value back then would leave it set for good. A block that
+  #     wraps the whole run (a console or rake block around an inline job)
+  #     keeps its value because it is still there.
+  #   - :keep — outlives runs: a counter only ever compared before and
+  #     after one call, or a slot whose block puts back what it found and
+  #     which, emptied in the middle of the block, would fail open.
+  #
+  # A run that completes inside a block that started during the run — a
+  # `run!(reset: true)` completing an outer run (ActionDispatch::Executor
+  # does that for a run left open) — empties that block's slot for the
+  # rest of the block: it fails closed (scoping applies again).
+  #
+  # @api private
+  module ExecutionState
+    # One slot: its name, where it is kept (:fiber or :execution), what the
+    # end of an executor run does to it (:clean or :keep) and what it holds.
+    Key = Data.define(:name, :scope, :at_run_end, :holds)
+
+    SCOPES = %i[fiber execution].freeze
+    AT_RUN_END = %i[clean keep].freeze
+
+    KEYS = [
+      Key.new(:pf_skip_auto_scope, :fiber, :clean,
+              'true inside PermissionForge.without_permission_scope (and the internal builds): Level 1 auto-scoping ' \
+              'and Level 2 detection are suspended. Fiber: seen elsewhere it would lift scoping there'),
+      Key.new(:pf_internal_scope_suspension, :fiber, :clean,
+              'true while the gem suspends Level 1 for its own queries (AutoPermissionScoping.internally_suspended: ' \
+              'find_by / permission_scoped bodies, invalidation holders, cache clears, audit lookups): not reported as ' \
+              'a scope_suspended bypass, and nobody signed in gets no find_by bypass. Same scope as pf_skip_auto_scope ' \
+              '(host_suspended? reads both). Fiber: seen elsewhere it would hide a bypass from the audit log'),
+      Key.new(:pf_in_auto_scope_hook, :fiber, :clean,
+              'true while the Level 1 default scope builds the rules: a query made meanwhile (current_user_resolver, a ' \
+              'permissions rebuild) runs unscoped instead of recursing. Fiber: seen elsewhere every query runs unscoped'),
+      Key.new(:pf_building_permission_keys, :fiber, :clean,
+              'Hash of permission cache key => the read-through build (or request-context resolution) in progress; a ' \
+              'read of a key being built gets the reentrant {}. Fiber: seen elsewhere a read gets {} (rules off)'),
+      Key.new(:pf_raw_store_columns, :fiber, :clean,
+              'Hash (by identity) of record => the store column a store accessor is writing. Fiber: seen elsewhere ' \
+              'the column reads unmasked'),
+      Key.new(:pf_validating_records, :fiber, :clean,
+              'Set (by identity) of the records whose validators are running (MaskedAttributes::ValidationReads). ' \
+              'Fiber: seen elsewhere a validation read there would read stored values'),
+      Key.new(:pf_validator_windows, :fiber, :clean,
+              'Set (by identity) of the records a Rails EachValidator is judging: the attribute it read for the ' \
+              'validation stays readable as stored until it is done (numericality reads it twice). Fiber: seen ' \
+              'elsewhere that attribute reads unmasked'),
+      Key.new(:pf_validation_reads, :fiber, :clean,
+              'Hash (by identity) of record => the attribute a validator is reading, which reads as stored. Fiber: ' \
+              'seen elsewhere that column reads unmasked'),
+      Key.new(:pf_unmasked_virtual_records, :fiber, :clean,
+              'Set (by identity) of the records inside pf_without_virtual_masking. Fiber: seen elsewhere the virtual ' \
+              'readers read unmasked'),
+      Key.new(:pf_audit_emitting, :fiber, :clean,
+              'true while a runtime audit event is built, stored or published (re-entrancy guard). Fiber: seen ' \
+              'elsewhere no runtime event is emitted there'),
+      Key.new(:pf_audit_field_access, :fiber, :clean,
+              'the Audit::FieldAccess::Frame of the record read in progress. Fiber: seen elsewhere its decisions go ' \
+              'into a frame that is not theirs'),
+      Key.new(:pf_inspecting, :fiber, :clean,
+              'true while inspect / pretty_print read a record: no field.access decision. Fiber: seen elsewhere ' \
+              'field reads go unrecorded'),
+      Key.new(:pf_open_invalidation_batch, :execution, :clean,
+              'the InvalidationBatch the next permission record written on its connection joins. Execution, like the ' \
+              'connection: losing or sharing a batch costs repeated invalidations, never a missed one'),
+      Key.new(:pf_cache_failure_collectors, :execution, :keep,
+              'stack of Cache::Failure::Collected, one per Cache::Failure.collect block. Execution: a failure ' \
+              'reported in a fiber of the block is collected. Kept at the end of a run: each collect removes its ' \
+              'own entry by identity, and emptying the stack inside a block would lose its failure (fails open)'),
+      Key.new(:pf_cache_failures, :execution, :keep,
+              'Integer count of the cache failures reported (Cache::Failure.none? compares it before and after). ' \
+              'Execution: a failure in a fiber of the block counts; never reset, so a none? around a run sees one in it'),
+      Key.new(:pf_store_errors, :execution, :keep,
+              'Array of the errors a cache store handed its error handler during the store call in progress ' \
+              '(Cache::HandledErrors.during, .written). Execution: another fiber\'s error seen here counts against the call ' \
+              '(it is tried again). Kept at the end of a run: the block puts back what it found, and emptying the ' \
+              'slot inside the call would lose the error (a failed write taken for done)'),
+      Key.new(:pf_audit_context, :execution, :clean,
+              'the frozen Hash of the Audit::Context slots (actor, source, request id, IP, reason, correlation id)'),
+      Key.new(:pf_audit_transaction_correlation, :execution, :clean,
+              '[transaction, id] of the correlation id minted for the outermost open transaction'),
+      Key.new(:pf_audit_runtime_once, :execution, :clean,
+              'Hash of the runtime audit events published once per request (Audit::Runtime.once?)')
+    ].to_h { |key| [key.name, key] }.freeze
+
+    CLEANED = KEYS.values.select { |key| key.at_run_end == :clean }.map(&:name).freeze
+
+    # The :fiber store: Thread#[] is fiber-local.
+    module FiberStorage
+      class << self
+        def [](name)
+          Thread.current[name]
+        end
+
+        def []=(name, value)
+          Thread.current[name] = value
+        end
+
+        # Ruby drops a fiber-local set to nil.
+        def delete(name)
+          locals = Thread.current
+          value = locals[name]
+          locals[name] = nil unless value.nil?
+          value
+        end
+      end
+    end
+
+    STORAGE = KEYS.transform_values { |key| key.scope == :fiber ? FiberStorage : ActiveSupport::IsolatedExecutionState }.freeze
+
+    # The :clean slots by scope: what the start and the end of a run walk.
+    CLEANED_FIBER = CLEANED.select { |name| KEYS[name].scope == :fiber }.freeze
+    CLEANED_EXECUTION = (CLEANED - CLEANED_FIBER).freeze
+
+    # The executor hook (Rails.application.executor.register_hook): notes
+    # what the :clean slots hold when a run starts, and removes what the run
+    # added when it completes.
+    module RunHook
+      # The fiber and the execution context the run started on, and what the
+      # :clean slots held then (ExecutionState.snapshot; nil for nothing).
+      Snapshot = Data.define(:fiber, :context, :values)
+
+      class << self
+        # @return [Snapshot]
+        def run
+          Snapshot.new(Fiber.current, ActiveSupport::IsolatedExecutionState.context, ExecutionState.snapshot)
+        end
+
+        # Only where the run started: its fiber (:fiber slots) or its
+        # execution context (:execution slots).
+        #
+        # @param snapshot [Snapshot]
+        # @return [void]
+        def complete(snapshot)
+          ExecutionState.run_completed(snapshot.values, fiber: snapshot.fiber.equal?(Fiber.current),
+                                                        execution: snapshot.context.equal?(ActiveSupport::IsolatedExecutionState.context))
+        end
+      end
+    end
+
+    class << self
+      # @param name [Symbol] a key of KEYS
+      # @return [Object, nil]
+      def [](name)
+        storage(name)[name]
+      end
+
+      # @param name [Symbol] a key of KEYS
+      # @return [Object] the value
+      def []=(name, value)
+        storage(name)[name] = value
+      end
+
+      # The slot's value; when it holds nothing, the block's value, stored.
+      #
+      #   ExecutionState.fetch(:pf_unmasked_virtual_records) { Set.new.compare_by_identity }
+      #
+      # @param name [Symbol] a key of KEYS
+      # @return [Object]
+      def fetch(name)
+        value = self[name]
+        value.nil? ? (self[name] = yield) : value
+      end
+
+      # @param name [Symbol] a key of KEYS
+      # @return [Object, nil] what the slot held
+      def delete(name)
+        store = storage(name)
+        store.delete(name)
+      end
+
+      # Sets the slot for the block and puts back what it held when the
+      # block ends, however it ends (a slot that held nil is emptied).
+      #
+      # @param name [Symbol] a key of KEYS
+      # @return the block's value
+      def with(name, value)
+        store = storage(name)
+        previous = store[name]
+        store[name] = value
+        begin
+          yield
+        ensure
+          previous.nil? ? store.delete(name) : store[name] = previous
+        end
+      end
+
+      # Empties every slot of this fiber and execution context: tests.
+      #
+      # @return [void]
+      def reset!
+        KEYS.each_key { |name| delete(name) }
+      end
+
+      # Registers RunHook with the application's executor (every request and
+      # job). Called once by Audit.install!.
+      #
+      # @param app [Rails::Application]
+      # @return [void]
+      def install!(app)
+        app.executor.register_hook(RunHook)
+      end
+
+      # What the :clean slots hold now (RunHook): nil when they are all
+      # empty (a request or a job), else name => [value, copy of its entries
+      # when it is a collection changed in place].
+      #
+      # @return [Hash{Symbol => Array(Object, Object)}, nil]
+      def snapshot
+        values = nil
+        locals = Thread.current
+        CLEANED_FIBER.each { |name| values = noted(values, name, locals[name]) }
+        CLEANED_EXECUTION.each { |name| values = noted(values, name, ActiveSupport::IsolatedExecutionState[name]) }
+        values
+      end
+
+      # The end of an executor run (RunHook): removes from the :clean slots of
+      # the scopes the run ends in what the run added, and never writes a
+      # value. A slot empty at the start (`values` from #snapshot) is
+      # emptied; from a collection there at the start, the entries the run
+      # added are dropped; any other slot is left as it is.
+      #
+      # @param values [Hash, nil] from #snapshot
+      # @return [void]
+      def run_completed(values, fiber:, execution:)
+        clean_all(CLEANED_FIBER, FiberStorage, values) if fiber
+        clean_all(CLEANED_EXECUTION, ActiveSupport::IsolatedExecutionState, values) if execution
+      end
+
+      private
+
+      def noted(values, name, value)
+        return values if value.nil?
+
+        (values || {}).merge!(name => [value, collection?(value) ? value.dup : nil])
+      end
+
+      def clean_all(names, store, values)
+        return names.each { |name| store.delete(name) } unless values
+
+        names.each { |name| (before = values[name]) ? clean(store, name, before) : store.delete(name) }
+      end
+
+      # A slot that held `value` when the run started: only a collection
+      # still in it loses what the run added.
+      def clean(store, name, before)
+        value, entries = before
+        return unless entries
+
+        current = store[name]
+        drop_added(current, entries) if current.equal?(value)
+      end
+
+      # Drops the entries of `collection` that `before` (its copy from the
+      # start of the run) does not have.
+      def drop_added(collection, before)
+        case collection
+        when Hash then collection.select! { |key, _| before.key?(key) }
+        when Set then collection.select! { |entry| before.include?(entry) }
+        else collection.select! { |entry| before.any? { |kept| kept.equal?(entry) } }
+        end
+      end
+
+      def storage(name)
+        STORAGE.fetch(name) do
+          raise ArgumentError, "unknown execution state key #{name.inspect} (PermissionForge::ExecutionState::KEYS)"
+        end
+      end
+
+      # A collection changed in place (a frozen one is replaced, never changed).
+      def collection?(value)
+        (value.is_a?(Hash) || value.is_a?(Set) || value.is_a?(Array)) && !value.frozen?
+      end
+    end
+  end
+end