permission_forge 0.14.1

data/lib/permission_forge/audit/gate.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Audit
+    # Whether a runtime event could be stored or heard right now — asked on
+    # the hottest paths of the gem (every attribute read under
+    # MaskedAttributes asks it for field.access), so the answer is kept and
+    # only worked out again when something it depends on changed. The
+    # generation is bumped by:
+    #
+    #   - the writers of the options that decide it (audit_runtime_events,
+    #     on_field_filtered, on_rule_bypass, audit_log_subscriber);
+    #   - every subscribe and unsubscribe: they go through
+    #     ActiveSupport::Notifications::Fanout#clear_cache (FanoutHook), also
+    #     for a pattern subscriber;
+    #   - a new notifier (ActiveSupport::Notifications.notifier=, NotifierHook);
+    #   - a new Configuration (PermissionForge.reset!, Configuration.new). A
+    #     configuration object put back in place past PermissionForge's API
+    #     (instance_variable_set with one made earlier) is not noticed.
+    #
+    # The answer is a superset: a subscriber of the host that says it is
+    # silenced still counts (it may change its mind without telling), and
+    # Audit.instrument asks the notifier again before it builds anything. The
+    # gem's own subscribers (Subscribers::Base) are silenced by their option,
+    # whose writer bumps the generation, so they count only while it is set.
+    # Where the notifier is not a Fanout with the hook, nothing is kept and
+    # the notifier is asked every time.
+    #
+    #   Gate.for('field.access').open? # => false
+    #
+    # @api private
+    class Gate
+      # Bumps the generation whenever ActiveSupport changes who listens.
+      module FanoutHook
+        def clear_cache(...)
+          super
+        ensure
+          PermissionForge::Audit::Gate.changed!
+        end
+      end
+
+      # Bumps the generation when the notifier is replaced.
+      module NotifierHook
+        def notifier=(notifier)
+          super
+        ensure
+          PermissionForge::Audit::Gate.changed!
+        end
+      end
+
+      MUTEX = Mutex.new
+      # The generation, read on every check: an Array element in a constant
+      # is the cheapest read Ruby has.
+      GENERATION = [0] # rubocop:disable Style/MutableConstant -- bumped in place by changed!
+
+      @gates = {}
+
+      class << self
+        # @return [Integer] bumped by every change the answers depend on
+        def generation = GENERATION[0]
+
+        # @param event [String] an access event of the catalogue
+        # @return [Gate]
+        def for(event)
+          @gates[event] || MUTEX.synchronize { @gates[event.to_s] ||= new(EventCatalog.fetch(event).name) }
+        end
+
+        # Something an answer depends on changed: every gate works it out again.
+        def changed!
+          MUTEX.synchronize { GENERATION[0] += 1 }
+        end
+
+        # Hooks the generation to ActiveSupport's subscriptions and notifier
+        # (once; Audit.install!). Without the hooks nothing is kept.
+        def install!
+          fanout = ActiveSupport::Notifications::Fanout
+          fanout.prepend(FanoutHook) if fanout.method_defined?(:clear_cache) && !(fanout <= FanoutHook)
+          notifications = ActiveSupport::Notifications.singleton_class
+          notifications.prepend(NotifierHook) unless notifications <= NotifierHook
+          changed!
+        end
+
+        # Whether answers can be kept for this notifier.
+        def tracking?(notifier)
+          notifier.is_a?(FanoutHook) && ActiveSupport::Notifications.singleton_class <= NotifierHook
+        end
+      end
+
+      # @param name [String] a registered access event
+      def initialize(name)
+        @name = name
+        @snapshot = nil
+      end
+
+      # The kept answer is one frozen Array [generation, answer], replaced
+      # whole: a reader on another thread sees an old answer or a new one,
+      # never half of each.
+      #
+      # @return [Boolean] whether the event's group is stored or anyone may listen
+      def open?
+        snapshot = @snapshot
+        return snapshot[1] if snapshot && snapshot[0] == GENERATION[0]
+
+        refresh[1]
+      end
+
+      # The gem's own subscribers that take a light payload, when they are
+      # the only ones that hear the event and its group is not stored: the
+      # legacy hooks alone. Audit.instrument then hands them the payload
+      # without building an event (no Recorder, no notification) — a hook set
+      # for years must not cost what a full audit event costs. nil otherwise,
+      # and wherever nothing is kept (no tracking).
+      #
+      # @return [Array<Subscribers::Base>, nil]
+      def direct_listeners
+        snapshot = @snapshot
+        return snapshot[2] if snapshot && snapshot[0] == GENERATION[0]
+
+        refresh[2]
+      end
+
+      private
+
+      # The generation is read before the answer is worked out: a change made
+      # meanwhile leaves a snapshot that is already out of date.
+      #
+      # @return [Array(Integer, Boolean, Array|nil)]
+      def refresh
+        generation = GENERATION[0]
+        notifier = ActiveSupport::Notifications.notifier
+        entry = EventCatalog.fetch(@name)
+        stored = PermissionForge.configuration.store_runtime_group?(entry.runtime_group)
+        listeners = heard_by(notifier, entry.notification)
+        tracking = Gate.tracking?(notifier)
+        snapshot = [generation, stored || !listeners.empty?, (direct_of(listeners) if tracking && !stored)].freeze
+        @snapshot = (snapshot if tracking)
+        snapshot
+      end
+
+      # What hears the notification: a delegate per listener (the listener
+      # itself when it has none); [:unknown] when the notifier cannot say.
+      def heard_by(notifier, notification)
+        unless notifier.respond_to?(:all_listeners_for)
+          return notifier.listening?(notification) ? [:unknown] : []
+        end
+
+        notifier.all_listeners_for(notification).filter_map do |listener|
+          delegate = listener.respond_to?(:delegate) ? listener.delegate : listener
+          delegate if counts?(delegate, notification)
+        end
+      end
+
+      def counts?(delegate, notification)
+        return true unless delegate.is_a?(Subscribers::Base)
+
+        !delegate.silenced?(notification)
+      end
+
+      def direct_of(listeners)
+        return if listeners.empty?
+        return unless listeners.all? { |delegate| delegate.is_a?(Subscribers::Base) && delegate.light? }
+
+        listeners.freeze
+      end
+    end
+  end
+end

data/lib/permission_forge/audit/job_context.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Audit
+    # Every ActiveJob job runs with source 'job' in the audit context. The
+    # actor stays what the context already says (a job performed inline
+    # inside an admin request keeps the admin) or what the job names with
+    # PermissionForge.with_audit_actor; otherwise the usual resolution
+    # (PermissionForge.current_user, else unknown).
+    #
+    # Installed by the engine through ActiveSupport.on_load(:active_job), so
+    # an app without ActiveJob never loads it.
+    #
+    # @api private
+    module JobContext
+      def self.install!
+        ActiveSupport.on_load(:active_job) { include PermissionForge::Audit::JobContext::Hook }
+      end
+
+      # Included into ActiveJob::Base.
+      module Hook
+        extend ActiveSupport::Concern
+
+        included do
+          around_perform do |_job, block|
+            PermissionForge::Audit::Context.with(source: 'job') { block.call }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/permission_forge/audit/log_access.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Audit
+    # The one answer to "may this request read the audit log?", asked by the
+    # JSON API endpoint and by the HTML pages and exports alike.
+    #
+    # The request has already passed the surface's own gate (api_enabled and
+    # api_auth for the API, the admin authentication for the HTML pages) by the
+    # time this is asked, so with `config.audit_log_authorization` unset the
+    # answer is yes: reading the log needs no more than the admin access that
+    # reading every other admin endpoint needs.
+    #
+    # With a lambda(controller) set, only an exact `true` allows. Anything else
+    # (false, nil, a truthy non-true value) denies, and so does a lambda that
+    # raises: an authorization hook that fails must never open the log.
+    #
+    # @api private
+    module LogAccess
+      class << self
+        # @param controller [ActionController::Base] the request's controller
+        # @param configuration [PermissionForge::Configuration]
+        # @return [Boolean]
+        def allowed?(controller, configuration: PermissionForge.configuration)
+          hook = configuration.audit_log_authorization
+          return true if hook.nil?
+
+          true.equal?(hook.call(controller))
+        rescue StandardError => e
+          Failure.handle(e, strategy: :report, operation: :authorize, hook: 'audit_log_authorization')
+          false
+        end
+      end
+    end
+  end
+end

data/lib/permission_forge/audit/recorder.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Audit
+    # Builds the row of one event from its catalogue entry, the audit context
+    # and the caller's payload, stores it (AuditEvent) and gives the
+    # notification payload. The row is built once (#attributes) and kept.
+    #
+    # Payload keys (anything else raises — a typo must not pass silently):
+    #   record:             the record the event is about. A permission model
+    #                       (Concerns::RecordsAuditEvents) fills its columns
+    #                       through #audit_reference. Any other record fills
+    #                       record_type (its base class), record_id and, when
+    #                       the table has a uuid column, record_uuid from the
+    #                       raw column — never through its readers, which a
+    #                       masked host model guards, and never a label
+    #   record_label:       the label of a host record, if any
+    #   data:               event-specific Hash, stored as JSON with string keys
+    #   reason:             free text or ticket reference
+    #   actor:              an Actor, a user or a Hash — overrides Actor.current
+    #   source:             overrides Source.current
+    #   subject_user_id:    the person whose access is affected
+    #   permission_set:     a PermissionSet (fills id and uuid) or an id
+    #   occurred_at:        defaults to now (UTC)
+    #   record_type, record_id, record_uuid, permission_set_id,
+    #   permission_set_uuid, tenant_id: column overrides
+    #   ambient_tenant_id:  the tenant that was ambient when the event
+    #                       happened, for an event written later
+    #                       (Audit::Detached); defaults to the one ambient now
+    #   objects:            live objects for the subscribers in this process
+    #                       (the user a decision was made for, …): handed over
+    #                       as payload[:objects], never stored or serialized
+    #
+    # @api private
+    class Recorder
+      OPTIONS = %i[record data reason actor source subject_user_id permission_set occurred_at
+                   record_type record_id record_uuid record_label permission_set_id permission_set_uuid tenant_id
+                   ambient_tenant_id objects].freeze
+      NO_OBJECTS = {}.freeze
+      REFERENCE_COLUMNS = %i[record_type record_id record_uuid record_label permission_set_id permission_set_uuid
+                             subject_user_id tenant_id].freeze
+
+      attr_reader :entry
+
+      # @param entry [EventCatalog::Entry]
+      # @param payload [Hash] see OPTIONS
+      def initialize(entry, payload)
+        unknown = payload.keys - OPTIONS
+        raise ArgumentError, "unknown audit payload key(s) #{unknown.map(&:inspect).join(', ')} (known: #{OPTIONS.join(', ')})" \
+          unless unknown.empty?
+
+        @entry = entry
+        @payload = payload
+      end
+
+      def name
+        entry.name
+      end
+
+      # The event as a Hash: every column of AuditEvent (uuid included) plus
+      # tenant_id. What subscribers receive, with stored: and audit_event:.
+      # Every string column is cleaned (Audit::ColumnValues).
+      def attributes
+        @attributes ||= ColumnValues.clean(raw_attributes).freeze
+      end
+
+      # @return [AuditEvent] the stored event
+      def store!
+        PermissionForge::AuditEvent.store!(attributes.except(:tenant_id).merge(subject_tenant_id: attributes[:tenant_id]))
+      end
+
+      # @param stored [AuditEvent, nil]
+      # @param deferred [Boolean] the row is written later: a runtime event
+      #   heard inside an open transaction is stored once the outermost
+      #   transaction has ended (Audit.instrument)
+      def notification_payload(stored, deferred: false)
+        attributes.merge(stored: !stored.nil?, audit_event: stored, deferred: deferred,
+                         objects: @payload[:objects] || NO_OBJECTS)
+      end
+
+      private
+
+      def raw_attributes
+        {
+          uuid: Audit.new_id, event: entry.name, category: entry.category,
+          **actor.to_columns, source: source,
+          **reference,
+          data: data, reason: reason,
+          request_id: Context[:request_id], ip: Context[:ip],
+          correlation_id: correlation_id, occurred_at: occurred_at
+        }
+      end
+
+      def actor
+        Actor.coerce(@payload[:actor]) || Actor.current
+      end
+
+      def source
+        @payload[:source] ? Source.validate!(@payload[:source]) : Source.current
+      end
+
+      def reason
+        (@payload[:reason] || Context[:reason])&.to_s
+      end
+
+      def data
+        (@payload[:data] || {}).as_json
+      end
+
+      def occurred_at
+        (@payload[:occurred_at] || Time.current).utc
+      end
+
+      # The context's id, else one per open transaction, else one of its own:
+      # a correlation id is never blank.
+      def correlation_id
+        Context[:correlation_id] || Context.transaction_correlation_id || Audit.new_id
+      end
+
+      # Columns from the record, then from permission_set:, then explicit overrides.
+      def reference
+        columns = REFERENCE_COLUMNS.index_with { nil }.merge!(record_reference, permission_set_reference,
+                                                              @payload.slice(*REFERENCE_COLUMNS))
+        columns[:record_id] = columns[:record_id]&.to_s
+        columns[:subject_user_id] = columns[:subject_user_id]&.to_s
+        columns[:tenant_id] = ambient_tenant_id if columns[:tenant_id].nil?
+        columns
+      end
+
+      # Pinned when the event is built: a row written later (after the
+      # transaction it was noticed in has ended) keeps the tenant of the
+      # moment it happened, whatever is ambient at the write.
+      def ambient_tenant_id
+        @payload.key?(:ambient_tenant_id) ? @payload[:ambient_tenant_id] : PermissionForge.ambient_tenant_id
+      end
+
+      def record_reference
+        record = @payload[:record]
+        return {} unless record
+        return record.audit_reference if record.respond_to?(:audit_reference)
+
+        { record_type: record_type_of(record), record_id: record.id, record_uuid: raw_uuid_of(record) }
+      end
+
+      def record_type_of(record)
+        klass = record.class
+        klass.respond_to?(:base_class) ? klass.base_class.name : klass.name
+      end
+
+      # The uuid column as stored, past the record's readers (a host model
+      # with MaskedAttributes guards those, and a guard that audits reads
+      # would recurse).
+      def raw_uuid_of(record)
+        return unless record.respond_to?(:has_attribute?) && record.has_attribute?('uuid')
+
+        record.read_attribute_before_type_cast('uuid')
+      end
+
+      def permission_set_reference
+        set = @payload[:permission_set]
+        return {} unless set
+        return { permission_set_id: set.id, permission_set_uuid: set.uuid } if set.respond_to?(:uuid)
+
+        { permission_set_id: set }
+      end
+    end
+  end
+end

data/lib/permission_forge/audit/refusals.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Audit
+    # The payloads of refusal events built from what a client sent, bounded:
+    # a refused request must not be able to make its own record too big to
+    # store (MySQL refuses an over-long value; a huge JSON row costs the
+    # store), nor shape it with nested parameters.
+    #
+    # @api private
+    module Refusals
+      # How many of the people concerned are listed; user_count has them all.
+      USER_IDS_LIMIT = 100
+      VALUE_LIMIT = 255
+
+      module_function
+
+      # The payload of a refused change to who holds a Permission Set or
+      # belongs to a Permission Set Group, for Audit.record / pf_audit_refused.
+      #
+      # @param target [PermissionForge::PermissionSet, PermissionForge::PermissionSetGroup, nil]
+      # @param user_ids [Object] as the client sent them: a scalar, an Array, anything
+      # @param action [Symbol, String, nil] e.g. :grant, :revoke, :add_member
+      # @param hook [String] the option that refused (data 'hook')
+      # @return [Hash] subject_user_id: (one person only), permission_set: or record:, data:
+      def assignment(target, user_ids, hook:, action: nil)
+        ids = user_ids_of(user_ids)
+        data = { 'reason' => 'assignment_not_authorized', 'hook' => hook,
+                 'user_ids' => ids.first(USER_IDS_LIMIT), 'user_count' => ids.size }
+        data['action'] = action.to_s if action
+        { subject_user_id: (ids.first if ids.one?), data: data, **target_reference(target) }
+      end
+
+      # Scalars only (strings, numbers), each as a String of at most
+      # VALUE_LIMIT characters; nested arrays are flattened, hashes dropped.
+      #
+      # @return [Array<String>]
+      def user_ids_of(user_ids)
+        return [] if user_ids.nil? || user_ids.is_a?(Hash) || user_ids.respond_to?(:to_unsafe_h)
+
+        Array(user_ids).flatten.filter_map { |id| scalar(id) }
+      end
+
+      # @return [String, nil] a non-empty String or number, capped
+      def scalar(value)
+        return unless value.is_a?(String) || value.is_a?(Numeric)
+
+        value.to_s[0, VALUE_LIMIT].presence
+      end
+
+      # A Permission Set fills permission_set_id/uuid; a group is the record.
+      def target_reference(target)
+        case target
+        when nil then {}
+        when PermissionForge::PermissionSet then { permission_set: target }
+        else { record: target }
+        end
+      end
+    end
+  end
+end

data/lib/permission_forge/audit/request_context.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Audit
+    # The audit context of one admin UI or API request, set by the
+    # around-action of both base controllers:
+    #
+    #   around_action :pf_audit_request
+    #   def pf_audit_request(&) = PermissionForge::Audit::RequestContext.wrap(self, source: 'admin_ui', &)
+    #
+    # Inside the block every event carries the actor (Audit::ActorResolver),
+    # the source, the request id and IP (config.audit_request_context, else
+    # `request.request_id` and `request.remote_ip`) and, for a request that
+    # can change something (anything but GET and HEAD), the `reason`
+    # parameter and one correlation id for all its events. A read-only page
+    # in Audit::AuditedViews is recorded after a successful response.
+    #
+    # Nothing is set outside the block, and the block restores the previous
+    # context also when the action raises.
+    #
+    # @api private
+    class RequestContext
+      # The reason column is a varchar(255) (MySQL counts characters).
+      REASON_LIMIT = 255
+      REQUEST_VALUE_LIMIT = 255
+      READ_ONLY_METHODS = %w[GET HEAD].freeze
+
+      class << self
+        # @param controller [ActionController::Metal]
+        # @param source [String] 'admin_ui' or 'api'
+        # @return the value of the block
+        def wrap(controller, source:, &)
+          new(controller, source).wrap(&)
+        end
+
+        # The request id and IP to store: config.audit_request_context
+        # (lambda(controller) → { request_id:, ip: }; a key it returns — also
+        # as nil — replaces the default) over request.request_id and the
+        # remote IP (#remote_ip). A lambda that raises is reported and the
+        # defaults are used.
+        #
+        # @return [Hash] { request_id:, ip: }
+        def request_slots(controller, configuration: PermissionForge.configuration)
+          request = controller.request
+          slots = { request_id: request.request_id, ip: remote_ip(request).first }
+          slots.merge!(custom_request_slots(controller, configuration))
+          slots.transform_values { |value| value.presence && value.to_s[0, REQUEST_VALUE_LIMIT] }
+        end
+
+        # `request.remote_ip`, which raises IpSpoofAttackError when the
+        # Client-IP and X-Forwarded-For headers disagree. That must neither
+        # fail the request nor keep a refused sign-in out of the log: the
+        # peer address is used instead, and the second value says so.
+        #
+        # @return [Array(String, Boolean)] [ip, spoofing suspected?]
+        def remote_ip(request)
+          [request.remote_ip, false]
+        rescue ActionDispatch::RemoteIp::IpSpoofAttackError
+          [request.remote_addr, true]
+        end
+
+        # The `reason` parameter (form field or JSON body key) of a request
+        # that can change something: a String cleaned as an event column is
+        # (one line, no NUL or other control character — PostgreSQL refuses a
+        # NUL, and the assignment rows keep the reason too), stripped, nil
+        # when blank, capped at REASON_LIMIT characters.
+        #
+        # @return [String, nil]
+        def reason(controller)
+          return unless mutating?(controller.request)
+
+          value = controller.params[:reason]
+          ColumnValues.value(value.strip)[0, REASON_LIMIT].strip.presence if value.is_a?(String)
+        end
+
+        def mutating?(request)
+          !READ_ONLY_METHODS.include?(request.request_method)
+        end
+
+        # Records a refusal — a failed sign-in, a denied authorization, a
+        # locked record — through Audit::Detached, so that a transaction the
+        # caller rolls back does not take it along. Works before the request's
+        # context is set (authentication runs first): source, request id and
+        # IP are set for the event, and the actor is `actor:`, else the
+        # request's, else whoever the host names (ActorResolver, no fallback:
+        # an unidentified client stays unknown). `data` gets the request's
+        # method, path and endpoint, and 'ip_spoof_suspected' => true when
+        # the forwarding headers contradict each other (#remote_ip).
+        #
+        # @param event [String] e.g. 'admin.auth_failed', 'api.auth_failed', 'admin.lock_refused'
+        # @param payload [Hash] see Audit::Recorder
+        # @return [AuditEvent, nil]
+        def refused(controller, event, source:, actor: nil, **payload)
+          data = request_data(controller).merge(payload.delete(:data) || {})
+          data['ip_spoof_suspected'] = true if remote_ip(controller.request).last
+          Context.with(source: source, **request_slots(controller)) do
+            actor ||= Context[:actor] || ActorResolver.call(controller, source: source, fallback: false)
+            Detached.record(event, actor: actor, source: source, data: data, **payload)
+          end
+        end
+
+        # @return [Hash] 'method', 'path' and 'endpoint' ("controller_path#action")
+        def request_data(controller)
+          request = controller.request
+          { 'method' => request.request_method, 'path' => request.path,
+            'endpoint' => "#{controller.controller_path}##{controller.action_name}" }
+        end
+
+        private
+
+        def custom_request_slots(controller, configuration)
+          custom = configuration.audit_request_context
+          return {} unless custom
+
+          answer = custom.call(controller)
+          answer.respond_to?(:to_h) ? answer.to_h.symbolize_keys.slice(:request_id, :ip) : {}
+        rescue StandardError => e
+          Failure.handle(e, strategy: configuration.audit_hook_failure_strategy, operation: :request_context)
+          {}
+        end
+      end
+
+      def initialize(controller, source)
+        @controller = controller
+        @source = source
+      end
+
+      # @return the value of the block
+      def wrap(&block)
+        Context.with(**slots) do
+          result = self.class.mutating?(@controller.request) ? Audit.correlate(&block) : block.call
+          AuditedViews.record(@controller)
+          result
+        end
+      end
+
+      private
+
+      # An actor or source the host has already named around the request
+      # (PermissionForge.with_audit_actor in its own around-action) wins, as
+      # an explicit block does everywhere else.
+      def slots
+        {
+          actor: Context[:actor] || ActorResolver.call(@controller, source: @source),
+          source: Context[:source] || @source,
+          reason: self.class.reason(@controller),
+          **self.class.request_slots(@controller)
+        }
+      end
+    end
+  end
+end