permission_forge 0.14.1

data/lib/permission_forge/audit/runtime.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Audit
+    # The runtime decision events of the gem — what each one carries — for
+    # the code that makes the decisions (PermissionScopedFindable,
+    # AutoPermissionScoping, ControllerActionGuard, the services). Every
+    # method returns at once, before anything is built, when the event is
+    # neither stored nor heard (Audit.instrument?).
+    #
+    # Payloads name the model and the record by class (record_type: the base
+    # class) and id only — never through a host record's readers, which a
+    # masked model guards. The user the decision was made for is
+    # subject_user_id, the actor is Actor.current (the request's actor), and
+    # the live user object goes to in-process subscribers as
+    # payload[:objects][:user].
+    #
+    # What happens on every query under auto-scoping is published at most once
+    # per request (an executor run) per event, model, reason and user (#once?):
+    # the memo lives in the request's isolated state (ExecutionState), never
+    # on a record, is emptied with the audit context at the end of every
+    # executor run that started without it (a request, a job) and by
+    # Audit.reset!.
+    #
+    # @api private
+    module Runtime
+      BYPASSED = 'rule.bypassed'
+      DENIED = 'access.denied'
+      ACTION_DENIED = 'action.denied'
+      UNSCOPED = 'query.unscoped'
+
+      # Why row-level rules (or the action guard) did not apply.
+      BYPASS_REASONS = %w[view_all modify_all nil_user scope_suspended auto_scope_opt_out no_rules guard_bypass].freeze
+
+      # Asked on every relation built under auto-scoping.
+      BYPASS_GATE = Gate.for(BYPASSED)
+
+      ONCE_KEY = :pf_audit_runtime_once
+      # A thread that never ends an executor run (a script, a daemon loop)
+      # forgets what it published past this many keys.
+      ONCE_LIMIT = 1_000
+
+      class << self
+        # rule.bypassed: the rules (or the guard) were skipped, and why.
+        #
+        # @param reason [String, Symbol] one of BYPASS_REASONS
+        # @param model [Class, String] the model (or Resource name)
+        # @param via [String] find_by, permission_scoped, auto_scope, rule_applier, action_guard
+        # @param user [Object, nil] the user the decision was made for
+        # @param once [Boolean] at most once per request
+        # @param data [Hash] more event data (string keys)
+        # @raise [ArgumentError] for a reason outside BYPASS_REASONS
+        def bypassed(reason, model:, via:, user: nil, once: false, data: nil) # rubocop:disable Metrics/ParameterLists
+          return unless BYPASS_GATE.open? && Audit.instrument?(BYPASSED)
+
+          reason = reason.to_s
+          raise ArgumentError, "unknown bypass reason #{reason.inspect} (#{BYPASS_REASONS.join(', ')})" unless BYPASS_REASONS.include?(reason)
+          return if once && !once?(BYPASSED, model, reason, via, user)
+
+          publish(BYPASSED, model: model, user: user, record_id: nil,
+                            data: { 'reason' => reason, 'via' => via }.merge(data || {}))
+        end
+
+        # access.denied (rows of a model) or action.denied (a controller
+        # action): the decision, why, and the record when it is known.
+        #
+        # @param event [String] DENIED or ACTION_DENIED
+        # @param reason [String, Symbol] why (rule, nil_user, a guard reason)
+        # @param model [Class, String]
+        # @param via [String]
+        # @param user [Object, nil]
+        # @param record_id [Object, nil] the denied record's id, when known
+        # @param once [Boolean] at most once per request
+        # @param data [Hash] more event data (string keys)
+        def denied(event, reason:, model:, via:, user: nil, record_id: nil, once: false, data: nil) # rubocop:disable Metrics/ParameterLists
+          return unless Audit.instrument?(event)
+          return if once && !once?(event, model, reason.to_s, via, user)
+
+          publish(event, model: model, user: user, record_id: record_id,
+                         data: { 'reason' => reason.to_s, 'via' => via }.merge(data || {}))
+        end
+
+        # query.unscoped: Level 2 detection saw a query on a protected table
+        # that went past the rules. Once per request per table.
+        #
+        # @param model [Class, String, nil] the protected model, when known
+        # @param table [String]
+        # @param data [Hash]
+        def unscoped(model:, table:, data: nil)
+          return unless Audit.instrument?(UNSCOPED)
+          return unless once?(UNSCOPED, model || table, table, nil, nil)
+
+          user = current_user
+          publish(UNSCOPED, model: model || table, user: user, record_id: nil, data: { 'table' => table }.merge(data || {}))
+        end
+
+        # permissions.rebuilt (the `cache` group): a user's permission hash
+        # was built — read through on a cache miss, or asked for — and whether
+        # it was withheld from the cache inside a transaction.
+        def rebuilt(user, read_through:, withheld:)
+          cache_event('permissions.rebuilt', user, 'read_through' => read_through, 'withheld' => withheld)
+        end
+
+        # permissions.invalidated (the `cache` group): a user's cached hash
+        # was removed, for which tenant, and whether the store confirmed it.
+        def invalidated(user, tenant_id:, confirmed:)
+          cache_event('permissions.invalidated', user, 'tenant_id' => tenant_id, 'confirmed' => confirmed)
+        end
+
+        # Whether this is the first time in this request that `key` was
+        # published; remembers it.
+        def once?(*key)
+          key[-1] = user_id(key[-1])
+          seen = (state[ONCE_KEY] ||= {})
+          return false if seen.key?(key)
+
+          seen.clear if seen.size >= ONCE_LIMIT
+          seen[key] = true
+        end
+
+        # Forgets what was published once (end of an executor run, tests).
+        def reset!
+          state.delete(ONCE_KEY)
+        end
+
+        # The user's id, read as its primary key; nil for no user or an
+        # object that has none.
+        def user_id(user)
+          user.id if user.respond_to?(:id)
+        end
+
+        # The model's base class name (a Resource name as given).
+        def record_type(model)
+          return model.to_s unless model.is_a?(Class)
+
+          model.respond_to?(:base_class) ? model.base_class.name : model.name
+        end
+
+        # The model's own name (a subclass stays itself).
+        def model_name(model)
+          model.is_a?(Class) ? model.name : model.to_s
+        end
+
+        private
+
+        # Whose hash: record and subject are the user.
+        def cache_event(event, user, data)
+          return unless Audit.instrument?(event)
+
+          Audit.instrument(event) do
+            { record_type: record_type(user.class), record_id: user_id(user), subject_user_id: user_id(user), data: data,
+              objects: { user: user } }
+          end
+        end
+
+        def publish(event, model:, user:, record_id:, data:)
+          Audit.instrument(event) do
+            { record_type: record_type(model), record_id: record_id, subject_user_id: user_id(user),
+              data: { 'model' => model_name(model) }.merge(data), objects: { user: user } }
+          end
+        end
+
+        # A user the resolver raises for is no user here: the decision being
+        # reported has been made already, and Actor.current reports the
+        # resolver's failure when the event is built.
+        def current_user
+          PermissionForge.current_user
+        rescue StandardError
+          nil
+        end
+
+        def state
+          ExecutionState
+        end
+      end
+    end
+  end
+end

data/lib/permission_forge/audit/runtime_emission.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Audit
+    # How Audit.instrument emits a runtime (access) event once it knows the
+    # event is stored or heard. Extended into Audit; uses its #write, #notify
+    # and #listening?.
+    #
+    # Published at once — the decision has been made, whatever becomes of the
+    # transaction it was made in — never after a commit. Stored at once, or,
+    # inside an open transaction, once the outermost transaction has ended,
+    # committed or rolled back (a denial inside a transaction the denial
+    # itself rolls back is still recorded); the notification then says
+    # `stored: false, deferred: true`.
+    #
+    # Re-entrancy: nothing is done while this thread (fiber) is already
+    # building, storing or publishing a runtime event (#emitting?). A payload
+    # or a subscriber that reads a masked attribute or runs a permission
+    # check gets its answer, but publishes no event about it — and cannot
+    # loop.
+    #
+    # @api private
+    module RuntimeEmission
+      # Set while this fiber builds, stores or publishes a runtime event — a
+      # fiber-local ExecutionState slot: the emission runs in the fiber that
+      # started it.
+      EMITTING_KEY = :pf_audit_emitting
+
+      # @return [Boolean] whether this fiber is building, storing or
+      #   publishing a runtime event
+      def emitting?
+        ExecutionState[EMITTING_KEY] == true
+      end
+
+      # Hands { data:, objects: } to the gem's light subscribers
+      # (Gate#direct_listeners) with the re-entrancy guard, building no event.
+      # For a caller that has the payload at hand (Audit::FieldAccess).
+      #
+      # @return [nil]
+      def emit_light(entry, listeners, light)
+        return if emitting?
+
+        emitting { deliver_light(entry, listeners, light) }
+        nil
+      end
+
+      # One field decision handed to the light subscribers (the legacy
+      # on_field_filtered hook) as it is made (Audit::FieldAccess::Direct).
+      #
+      # @return [nil]
+      def emit_decision(listeners, resource_name, field_name, action, user)
+        return if emitting?
+
+        emitting do
+          listeners.each { |listener| listener.deliver_decision(resource_name, field_name, action, user) }
+        end
+        nil
+      end
+
+      private
+
+      # The legacy hooks are the only listeners and nothing is stored
+      # (Gate#direct_listeners): they get { data:, objects: } straight away —
+      # no Recorder, no actor, no notification.
+      #
+      # @return [nil]
+      def instrument_light(entry, listeners, payload)
+        return if emitting?
+
+        emitting do
+          payload = runtime_payload(entry, payload) { yield if block_given? }
+          unless payload.equal?(FAILED)
+            light = { event: entry.name, data: payload[:data] || {}, objects: payload[:objects] || Recorder::NO_OBJECTS }
+            deliver_light(entry, listeners, light)
+          end
+        end
+        nil
+      end
+
+      def deliver_light(entry, listeners, light)
+        listeners.each { |listener| listener.deliver_light(entry.notification, light) }
+      rescue StandardError => e
+        Failure.handle(e, strategy: configuration.audit_hook_failure_strategy, operation: :publish, event: entry.name)
+      end
+
+      # @return [AuditEvent, nil]
+      def instrument_runtime(entry, payload, store:)
+        return if emitting?
+
+        emitting do
+          payload = runtime_payload(entry, payload) { yield if block_given? }
+          emit_runtime(Recorder.new(entry, payload), store: store) unless payload.equal?(FAILED)
+        end
+      end
+
+      def emitting(&)
+        ExecutionState.with(EMITTING_KEY, true, &)
+      end
+
+      # The caller's payload with the block's merged in, source 'runtime'
+      # unless given. A block that raises follows audit_hook_failure_strategy.
+      def runtime_payload(entry, payload)
+        more = yield
+        payload = payload.merge(more) if more
+        payload.merge(source: payload[:source] || 'runtime')
+      rescue StandardError => e
+        Failure.handle(e, strategy: configuration.audit_hook_failure_strategy, operation: :build, event: entry.name)
+        FAILED
+      end
+
+      def emit_runtime(recorder, store:)
+        transaction = OpenTransaction.current(PermissionForge::AuditEvent) if store
+        stored = write(recorder, store: store && transaction.nil?, strategy: configuration.audit_hook_failure_strategy,
+                                 change: false)
+        return if stored.equal?(FAILED)
+
+        store_runtime_later(transaction, recorder) if transaction
+        notify(recorder.entry, recorder.notification_payload(stored, deferred: !transaction.nil?)) if listening?(recorder.entry)
+        stored
+      end
+
+      # OpenTransaction#after_end: once, when the outermost transaction has
+      # ended either way (a savepoint that rolls back hands it on). It runs
+      # from Rails' commit or rollback, where raising would replace the
+      # caller's own exception: a failure is reported, never raised, whatever
+      # the strategy (as Audit::Detached does).
+      def store_runtime_later(transaction, recorder)
+        transaction.after_end do
+          strategy = configuration.audit_hook_failure_strategy
+          emitting { write(recorder, store: true, strategy: strategy == :raise ? :report : strategy, change: false) }
+        end
+      end
+    end
+  end
+end

data/lib/permission_forge/audit/settings_observer.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Audit
+    # Records an `audit.settings_observed` event when the audit settings in
+    # force differ from those of the most recent such event, so "was auditing
+    # ever off, and since when" can be answered from the log. The engine calls
+    # it at boot (not in the test environment); it never raises.
+    #
+    # Only the settings at boot are observed: a toggle made at runtime after
+    # boot is not seen until the next boot or an explicit call.
+    #
+    # Lambdas are recorded as "set" / "unset" only, never their code.
+    #
+    #   PermissionForge::Audit::SettingsObserver.call  # => AuditEvent | nil
+    #
+    # @api private
+    module SettingsObserver
+      EVENT = 'audit.settings_observed'
+      OPTIONS = %i[
+        audit_events audit_actor_resolver audit_request_context audit_change_failure_strategy
+        audit_hook_failure_strategy audit_runtime_events audit_log_subscriber audit_retention_period
+        audit_log_authorization admin_assignment_authorization
+      ].freeze
+
+      class << self
+        # @return [AuditEvent, nil] the new event; nil when nothing changed,
+        #   the table is missing, auditing is off or recording failed
+        def call(configuration: PermissionForge.configuration)
+          return unless PermissionForge::AuditEvent.table_exists?
+
+          settings = fingerprint(configuration)
+          return if last_observed == settings
+
+          payload = { data: { 'settings' => settings }, actor: { type: 'system', label: 'boot' }, source: 'service' }
+          return PermissionForge::Audit.record(EVENT, **payload) unless configuration.audit_events == false
+
+          # Auditing is off: Audit.record would store nothing, yet "was auditing
+          # ever off" is what this event answers. Stored directly, not published.
+          Recorder.new(EventCatalog.fetch(EVENT), payload).store!
+        rescue StandardError => e
+          Rails.logger&.warn("[PermissionForge] could not record the audit settings: #{e.class}: #{e.message}") if defined?(Rails)
+          nil
+        end
+
+        # @return [Hash{String => Object}] stable, JSON-safe values
+        def fingerprint(configuration = PermissionForge.configuration)
+          OPTIONS.to_h { |option| [option.to_s, value_of(configuration.public_send(option))] }
+        end
+
+        private
+
+        def value_of(value)
+          case value
+          when nil then 'unset'
+          when Array then value.map(&:to_s).sort
+          when ActiveSupport::Duration, Numeric then value.to_i
+          when Symbol then value.to_s
+          when String, true, false then value
+          else 'set' # a lambda, or anything else: only that it is configured
+          end
+        end
+
+        def last_observed
+          PermissionForge::AuditEvent.unscoped.where(event: EVENT).order(occurred_at: :desc, id: :desc).first&.data&.[]('settings')
+        end
+      end
+    end
+  end
+end

data/lib/permission_forge/audit/source.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Audit
+    # Where an event came from: the source column. The admin UI, the API and
+    # jobs say so through the audit context (Audit::Context); a process that
+    # says nothing is a console, a rake task, or else a service.
+    #
+    # @api private
+    module Source
+      SOURCES = %w[admin_ui api rake job console service runtime].freeze
+
+      class << self
+        # @return [String] the context's source, else the detected one
+        def current
+          Context[:source] || detect
+        end
+
+        # @param console [Boolean] whether this process is `rails console`
+        # @param rake_tasks [Array<String>] the tasks rake was started with
+        # @return [String]
+        def detect(console: process_console?, rake_tasks: process_rake_tasks)
+          return 'console' if console
+          return 'rake' if rake_tasks.any?
+
+          'service'
+        end
+
+        # @raise [ArgumentError] for a source outside the contract
+        # @return [String]
+        def validate!(value)
+          source = value.to_s
+          raise ArgumentError, "audit source must be one of #{SOURCES.join(', ')} (got #{value.inspect})" unless SOURCES.include?(source)
+
+          source
+        end
+
+        private
+
+        def process_console?
+          defined?(::Rails::Console) ? true : false
+        end
+
+        # Rake is loaded in a test process too: only a process started with a
+        # task is a rake task.
+        def process_rake_tasks
+          return [] unless defined?(::Rake::Application) && ::Rake.respond_to?(:application)
+
+          ::Rake.application.top_level_tasks
+        end
+      end
+    end
+  end
+end

data/lib/permission_forge/audit/subscribers/base.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Audit
+    module Subscribers
+      # A notification subscriber of the gem, switched by an option of the
+      # configuration: installed once (Audit.install!), silenced while the
+      # option is off. ActiveSupport asks #silenced? before it delivers, so a
+      # silenced subscriber costs nothing, and the option can change at run
+      # time. The option's writer calls Gate.changed!, which is how Audit::Gate
+      # knows the answer without asking every time.
+      #
+      # Subclasses name what they subscribe to (#pattern), when they are
+      # silenced, and what they do with an event's payload (#deliver).
+      class Base
+        # @return [String, Regexp] the notification(s) to subscribe to
+        def pattern
+          raise NotImplementedError
+        end
+
+        # @param _name [String] the notification
+        # @return [Boolean]
+        def silenced?(_name)
+          raise NotImplementedError
+        end
+
+        # Whether it can be handed the light payload ({ data:, objects: }) in
+        # place of a built event (Audit::Gate#direct_listeners).
+        def light? = false
+
+        # The light payload, from Audit.instrument (the hook path that builds
+        # no event).
+        def deliver_light(name, payload)
+          deliver(name, payload)
+        end
+
+        # @return [Object] the ActiveSupport subscriber, for Subscribers.uninstall!
+        def subscribe!
+          ActiveSupport::Notifications.subscribe(pattern, self)
+        end
+
+        # ActiveSupport's timed subscriber interface.
+        def call(name, _started, _finished, _id, payload)
+          deliver(name, payload)
+        end
+
+        private
+
+        # @param name [String] "<event>.permission_forge"
+        # @param payload [Hash] see Audit::Recorder#notification_payload
+        def deliver(name, payload)
+          raise NotImplementedError
+        end
+
+        def configuration
+          PermissionForge.configuration
+        end
+
+        # A hook that raises follows config.audit_hook_failure_strategy: it
+        # never breaks the request unless the strategy is :raise.
+        def guarded(event, hook)
+          yield
+        rescue StandardError => e
+          Failure.handle(e, strategy: configuration.audit_hook_failure_strategy, operation: :hook, event: event, hook: hook)
+        end
+      end
+    end
+  end
+end

data/lib/permission_forge/audit/subscribers/legacy_hooks.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Audit
+    module Subscribers
+      # The two hooks that existed before the audit event log, kept with the
+      # call signatures they always had, as subscribers of the runtime events
+      # that replaced them. Installed always and silenced while the hook is
+      # nil, so a hook set at run time is called from then on.
+      #
+      # Alone (no other listener, the group not stored) they are handed the
+      # decision without an event being built (Audit::Gate#direct_listeners):
+      # a hook costs what it cost before the audit event log, roughly.
+      #
+      # A hook that raises no longer only logs: the failure follows
+      # config.audit_hook_failure_strategy (:report by default — logged and
+      # handed to Rails.error; :raise raises it).
+      module LegacyHooks
+        # config.on_rule_bypass(user:, resource:, reason: :view_all_or_modify_all)
+        # — called when view_all or modify_all lets `find_by` / `find_by!` /
+        # `permission_scoped` skip the row-level rules, as before. Not called
+        # for auto-scoping (it would fire on every query) nor for the other
+        # bypass reasons, which only rule.bypassed reports.
+        class RuleBypass < Base
+          REASONS = %w[view_all modify_all].freeze
+          VIA = %w[find_by permission_scoped].freeze
+          LEGACY_REASON = :view_all_or_modify_all
+
+          def pattern = 'rule.bypassed.permission_forge'
+
+          def light? = true
+
+          def silenced?(_name)
+            configuration.on_rule_bypass.nil?
+          end
+
+          private
+
+          def deliver(_name, payload)
+            hook = configuration.on_rule_bypass
+            data = payload[:data]
+            return unless hook && REASONS.include?(data['reason']) && VIA.include?(data['via'])
+
+            guarded('rule.bypassed', :on_rule_bypass) do
+              hook.call(user: payload[:objects][:user], resource: data['model'], reason: LEGACY_REASON)
+            end
+          end
+        end
+
+        # config.on_field_filtered(resource_name:, field_name:, action:, user:)
+        # — called once for every field decision, in the order the decisions
+        # were made, as before: one field.access event (a record read)
+        # carries all of them in payload[:objects][:decisions]. Each call is
+        # guarded on its own, so one that raises does not stop the others.
+        class FieldFiltered < Base
+          def pattern = 'field.access.permission_forge'
+
+          def light? = true
+
+          def silenced?(_name)
+            configuration.on_field_filtered.nil?
+          end
+
+          # One decision, as it is made (Audit::FieldAccess::Direct).
+          def deliver_decision(resource_name, field_name, action, user)
+            hook = configuration.on_field_filtered
+            return unless hook
+
+            resource_name = resource_name.is_a?(Symbol) ? resource_name.name : resource_name.to_s
+            guarded('field.access', :on_field_filtered) do
+              hook.call(resource_name: resource_name, field_name: field_name, action: action, user: user)
+            end
+          end
+
+          private
+
+          def deliver(_name, payload)
+            hook = configuration.on_field_filtered
+            return unless hook
+
+            Array(payload[:objects][:decisions]).each do |decision|
+              next unless decision.hook
+
+              guarded('field.access', :on_field_filtered) do
+                hook.call(resource_name: decision.resource_name, field_name: decision.field_name,
+                          action: decision.action, user: decision.user)
+              end
+            end
+          end
+        end
+      end
+
+      register(:on_rule_bypass, ->(_config) { LegacyHooks::RuleBypass.new.subscribe! })
+      register(:on_field_filtered, ->(_config) { LegacyHooks::FieldFiltered.new.subscribe! })
+    end
+  end
+end

data/lib/permission_forge/audit/subscribers/log.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Audit
+    module Subscribers
+      # config.audit_log_subscriber = true: one structured line per audit
+      # event (stored or not) in Rails.logger, at info level —
+      #
+      #   [PermissionForge] audit {"event":"access.denied","category":"access","actor_type":"user","actor_id":"7",...}
+      #
+      # The line carries ids, never the name snapshots (actor_label,
+      # record_label): logs usually travel further than the audit table.
+      # Silenced while the option is off; notifications that are not audit
+      # events (cache_failure.permission_forge) are left alone.
+      class Log < Base
+        SUFFIX = '.permission_forge'
+        PREFIX = '[PermissionForge] audit '
+        OMITTED = %i[actor_label record_label audit_event objects].freeze
+
+        def pattern = /\.permission_forge\z/
+
+        def silenced?(_name)
+          !configuration.audit_log_subscriber
+        end
+
+        private
+
+        def deliver(name, payload)
+          return unless configuration.audit_log_subscriber && defined?(Rails) && Rails.logger
+
+          event = name.delete_suffix(SUFFIX)
+          return unless EventCatalog.registered?(event)
+
+          guarded(event, :audit_log_subscriber) { Rails.logger.info(PREFIX + line(payload).to_json) }
+        end
+
+        def line(payload)
+          payload.except(*OMITTED).compact
+        end
+      end
+
+      register(:log, ->(_config) { Log.new.subscribe! })
+    end
+  end
+end