permission_forge 0.14.1

data/lib/permission_forge/api/serializers/permission_set_user_serializer.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Api
+    module Serializers
+      class PermissionSetUserSerializer < BaseSerializer
+        attributes :id, :uuid, :permission_set_id, :user_id, :expires_at, :created_at, :updated_at
+      end
+    end
+  end
+end

data/lib/permission_forge/api/serializers/resource_action_serializer.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Api
+    module Serializers
+      class ResourceActionSerializer < BaseSerializer
+        attributes :id, :uuid, :resource_id, :name, :label, :description,
+                   :is_permitted, :is_active,
+                   :created_at, :updated_at
+      end
+    end
+  end
+end

data/lib/permission_forge/api/serializers/resource_field_serializer.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Api
+    module Serializers
+      class ResourceFieldSerializer < BaseSerializer
+        attributes :id, :uuid, :resource_id, :name, :label, :description,
+                   :is_active, :is_editable,
+                   :read_access, :edit_access, :mask_access, :mask_strategy,
+                   :created_at, :updated_at
+      end
+    end
+  end
+end

data/lib/permission_forge/api/serializers/resource_serializer.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Api
+    module Serializers
+      class ResourceSerializer < BaseSerializer
+        attributes :id, :uuid, :permission_set_id, :name, :description,
+                   :is_active, :is_editable,
+                   :read_access, :create_access, :edit_access, :delete_access,
+                   :view_all, :modify_all,
+                   :created_at, :updated_at
+      end
+    end
+  end
+end

data/lib/permission_forge/audit/actor.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Audit
+    # Who did it, as stored on an event: the type (user, api, basic_auth,
+    # system, unknown), the id as a string (bigint and UUID keys both fit) and
+    # a label — the person's name as it was at the time.
+    #
+    # Resolution order (Actor.current): the actor in the audit context (an
+    # explicit `PermissionForge.with_audit_actor` block, or the request
+    # context the controllers set), then `PermissionForge.current_user`,
+    # otherwise unknown.
+    #
+    # @api public
+    class Actor
+      TYPES = %w[user api basic_auth system unknown].freeze
+
+      # The actor's type (`user`, `system`, `unknown`, ...), id and display label, as stored on the event.
+      attr_reader :type, :id, :label
+
+      # The class of the user object the actor was made from (for_user), nil
+      # for an actor given as a Hash or built by hand. Not part of equality:
+      # it says whether the id is a key of config.audit_user_class
+      # (HasAuditTrail stamps created_by / updated_by only then).
+      attr_reader :user_class
+
+      # @raise [ArgumentError] for a type outside TYPES
+      def initialize(type:, id: nil, label: nil, user_class: nil)
+        type = type.to_s
+        raise ArgumentError, "audit actor type must be one of #{TYPES.join(', ')} (got #{type.inspect})" unless TYPES.include?(type)
+
+        @type = type
+        @id = id&.to_s
+        @label = label.presence&.to_s
+        @user_class = user_class
+        freeze
+      end
+
+      class << self
+        # @return [Actor] never nil
+        def current
+          Context[:actor] || from_current_user || unknown
+        end
+
+        # @param user [Object] a host user (anything with an id)
+        # @param label [String, nil] overrides the name snapshot
+        # @param type [String] 'user' unless the user acts as an API principal
+        def for_user(user, label: nil, type: 'user')
+          new(type: type, id: user.id, label: label || label_for(user), user_class: record_class_of(user))
+        end
+
+        # The class of the record behind a decorated user (SimpleDelegator /
+        # Delegator, Draper), so a host's decorated current_user still stamps.
+        def record_class_of(user)
+          inner = user
+          3.times do
+            if inner.respond_to?(:__getobj__) then inner = inner.__getobj__
+            elsif inner.respond_to?(:decorated?) && inner.respond_to?(:object) && inner.decorated? then inner = inner.object
+            else break
+            end
+          end
+          inner.class
+        end
+
+        # @return [Actor] the actor used when nothing identifies who acted
+        def unknown
+          new(type: 'unknown')
+        end
+
+        # @param label [String] what ran (a job, a rake task)
+        # @return [Actor] a `system` actor
+        def system(label)
+          new(type: 'system', label: label)
+        end
+
+        # An Actor, a Hash { type:, id:, label: }, a user, or nil.
+        #
+        # @return [Actor, nil]
+        def coerce(value)
+          case value
+          when nil then nil
+          when Actor then value
+          when Hash then new(**value.symbolize_keys.slice(:type, :id, :label))
+          else for_user(value)
+          end
+        end
+
+        # The name snapshot for a user: config.user_label_formatter, else the
+        # same readers the admin screens use (Admin::PersonLabel).
+        def label_for(user)
+          PermissionForge::Admin::PersonLabel.new(user).name
+        end
+
+        private
+
+        def from_current_user
+          user = resolve_current_user
+          for_user(user) if user
+        end
+
+        # A current_user_resolver that raises (a Current attribute reset, a
+        # session store that is down) must not turn every change into an
+        # error: the actor is unknown and the failure is reported
+        # (config.audit_hook_failure_strategy; :raise raises). A user it
+        # returns that cannot be read is a failure of the event itself.
+        def resolve_current_user
+          PermissionForge.current_user
+        rescue StandardError => e
+          Failure.handle(e, strategy: PermissionForge.configuration.audit_hook_failure_strategy, operation: :actor)
+          nil
+        end
+      end
+
+      # Whether the actor is a record of `klass` (or a subclass): made from a
+      # user object of that class, not merely carrying an id.
+      #
+      # @param klass [Class, nil]
+      def user_of?(klass)
+        !klass.nil? && type == 'user' && !id.nil? && user_class.is_a?(Class) && user_class <= klass
+      end
+
+      # The three actor columns of an event.
+      def to_columns
+        { actor_type: type, actor_id: id, actor_label: label }
+      end
+
+      # [type, id, label]
+      def to_a
+        [type, id, label]
+      end
+
+      # Two actors are equal when their type, id and label are.
+      def ==(other)
+        other.is_a?(Actor) && to_a == other.to_a
+      end
+      alias eql? ==
+
+      # @return [Integer] consistent with {#==}
+      def hash
+        to_a.hash
+      end
+    end
+  end
+end

data/lib/permission_forge/audit/actor_resolver.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Audit
+    # Who acts in an admin UI or API request — never taken from what the
+    # client sends (parameters, headers), only from what the host and the
+    # engine have verified:
+    #
+    #   1. config.audit_actor_resolver, called with the controller (a user, an
+    #      Actor or a Hash { type:, id:, label: }; nil: it does not know)
+    #   2. the signed-in host user (config.current_user_resolver)
+    #   3. admin UI under HTTP Basic: the username that was checked, as
+    #      actor_type 'basic_auth' with no id
+    #
+    # Nobody named: the request's fallback — unknown in the admin UI, an
+    # anonymous API client in the API (api_auth said yes, but not who).
+    #
+    # A step that raises, or answers with something that is no actor, makes
+    # the actor unknown and is reported (Audit::Failure, under
+    # config.audit_hook_failure_strategy): the request goes on.
+    #
+    # @api private
+    class ActorResolver
+      # The request env key under which BasicAuthentication leaves the
+      # username it has just verified. Not reachable from a header (those are
+      # HTTP_*).
+      BASIC_AUTH_ENV = 'permission_forge.audit.basic_auth_user'
+      API_CLIENT_LABEL = 'API client'
+
+      # The steps tried, in order, per request source; the first that names
+      # someone wins.
+      STEPS = {
+        'admin_ui' => %i[configured_actor current_user basic_auth_user],
+        'api' => %i[configured_actor current_user]
+      }.freeze
+
+      # Who acts when no step names anyone.
+      FALLBACKS = {
+        'admin_ui' => -> { Actor.unknown },
+        'api' => -> { Actor.new(type: 'api', label: API_CLIENT_LABEL) }
+      }.freeze
+
+      # @param controller [ActionController::Metal]
+      # @param source [String] 'admin_ui' or 'api'
+      # @param fallback [Boolean] false: unknown instead of the source's
+      #   fallback when nobody is named (a refused request)
+      # @return [Actor] never nil
+      def self.call(controller, source:, fallback: true, configuration: PermissionForge.configuration)
+        new(controller, configuration).call(source, fallback: fallback)
+      end
+
+      def initialize(controller, configuration)
+        @controller = controller
+        @configuration = configuration
+      end
+
+      # @return [Actor]
+      def call(source, fallback: true)
+        identify(source) || (fallback ? FALLBACKS.fetch(source).call : Actor.unknown)
+      rescue StandardError => e
+        Failure.handle(e, strategy: @configuration.audit_hook_failure_strategy, operation: :actor, source: source)
+        Actor.unknown
+      end
+
+      # Who the request names, without a fallback. Raises what a step raises.
+      #
+      # @return [Actor, nil]
+      def identify(source)
+        STEPS.fetch(source).each do |step|
+          actor = send(step)
+          return actor if actor
+        end
+        nil
+      end
+
+      private
+
+      def configured_actor
+        resolver = @configuration.audit_actor_resolver
+        coerce(resolver.call(@controller)) if resolver
+      end
+
+      def current_user
+        coerce(PermissionForge.current_user)
+      end
+
+      # Set by BasicAuthentication only after the credentials matched.
+      def basic_auth_user
+        username = @controller.request.env[BASIC_AUTH_ENV]
+        Actor.new(type: 'basic_auth', label: username) if username.present?
+      end
+
+      # A user without an id names nobody; anything Actor.coerce cannot read
+      # raises (and so counts as a failure).
+      def coerce(value)
+        actor = Actor.coerce(value)
+        return if actor.nil? || (actor.type == 'user' && actor.id.nil?)
+
+        actor
+      end
+    end
+  end
+end

data/lib/permission_forge/audit/audited_views.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Audit
+    # The read-only admin pages that leave a trace: who looked at someone's
+    # effective access, who read or exported the audit trail. One registry,
+    # keyed by "controller_path#action"; the base controllers record the
+    # first entry that applies after a successful (2xx) response — the
+    # controllers themselves are not touched.
+    #
+    # Adding a page is one call:
+    #
+    #   AuditedViews.register('permission_forge/audit_events#index', 'audit.viewed',
+    #                         only_if: ->(c) { c.request.format.html? },
+    #                         payload: ->(c) { { data: { 'filters' => c.params.to_unsafe_h.slice('from', 'to') } } })
+    #
+    # `only_if` (optional) decides whether the entry applies to the request;
+    # `payload` (optional) returns the keys passed to Audit.record (record:,
+    # subject_user_id:, permission_set:, data: …). Actor, source, request id
+    # and IP come from the request's audit context.
+    #
+    # @api private
+    module AuditedViews
+      View = Struct.new(:event, :only_if, :payload, keyword_init: true) do
+        def applies?(controller)
+          only_if.nil? || only_if.call(controller) ? true : false
+        end
+
+        def payload_for(controller)
+          payload ? payload.call(controller) : {}
+        end
+      end
+
+      @entries = {}
+
+      class << self
+        # @param key [String] "controller_path#action", e.g. 'permission_forge/people#show'
+        # @param event [String] an admin, change or system event of the catalogue
+        # @param only_if [#call, nil] lambda(controller) → whether the entry applies
+        # @param payload [#call, nil] lambda(controller) → Hash for Audit.record
+        # @raise [EventCatalog::UnknownEventError, ArgumentError]
+        def register(key, event, only_if: nil, payload: nil)
+          entry = EventCatalog.fetch(event)
+          raise ArgumentError, "#{event} is an access event: views record admin events" if entry.runtime?
+
+          (@entries[key.to_s] ||= []) << View.new(event: entry.name, only_if: only_if, payload: payload)
+        end
+
+        # Removes every entry of a key, or only those of one event.
+        def unregister(key, event = nil)
+          views = @entries[key.to_s]
+          return unless views
+
+          event ? views.reject! { |view| view.event == event } : views.clear
+          @entries.delete(key.to_s) if views.empty?
+        end
+
+        # @return [Hash{String => Array<View>}]
+        def entries
+          @entries.transform_values(&:dup)
+        end
+
+        # @return [Array<View>]
+        def entries_for(key)
+          Array(@entries[key.to_s]).dup
+        end
+
+        # @return [View, nil] the first entry that applies to the request
+        def match(controller)
+          views = @entries["#{controller.controller_path}##{controller.action_name}"]
+          views&.find { |view| view.applies?(controller) }
+        end
+
+        # Records the view when the response succeeded and an entry applies.
+        # A HEAD request shows nothing and is not recorded.
+        #
+        # @return [AuditEvent, nil]
+        def record(controller)
+          return if controller.request.head? || !controller.response.successful?
+
+          view = match(controller)
+          Audit.record(view.event, **view.payload_for(controller)) if view
+        end
+      end
+
+      # Shared pieces of the built-in entries. What was shown is decided by
+      # the response (its media type), not by what the client asked for: an
+      # Accept header can negotiate a CSV without a .csv in the path.
+      module Requests
+        AUDIT_FILTERS = %w[who type days sort].freeze
+        LOG_FILTERS = %w[from to event category actor_type actor_id subject_user_id permission_set correlation_id
+                         record_type record_id record_uuid].freeze
+        API_FILTERS = %w[from to event category actor_type actor_id subject_user_id permission_set record_type record_id
+                         record_uuid correlation_id page per_page].freeze
+        VALUE_LIMIT = 255
+
+        module_function
+
+        def csv?(controller)
+          controller.response.media_type == Mime[:csv].to_s
+        end
+
+        # 'csv' / 'json' for a file the response handed over, nil for a page.
+        def export_format(controller)
+          { Mime[:csv].to_s => 'csv', Mime[:json].to_s => 'json' }[controller.response.media_type]
+        end
+
+        def export?(controller)
+          !export_format(controller).nil?
+        end
+
+        def tab?(controller, tab)
+          !csv?(controller) && controller.params[:tab] == tab
+        end
+
+        # A parameter as a String: a scalar, or the first scalar of an
+        # array (`?explain_user_id[]=7` — what `find_by(id: [...])` uses),
+        # capped; nil for anything else.
+        def scalar(value)
+          value = value.first if value.is_a?(Array)
+          value.to_s[0, VALUE_LIMIT] if value.is_a?(String) || value.is_a?(Numeric)
+        end
+
+        def id_param(controller, key)
+          scalar(controller.params[key])
+        end
+
+        def person(controller, data = {})
+          { subject_user_id: id_param(controller, :id), data: data }
+        end
+
+        def permission_set(controller, data = {})
+          { record: find_set(id_param(controller, :id)), data: data }
+        end
+
+        def find_set(id)
+          PermissionForge::PermissionSet.find_by(id: id) if id
+        end
+
+        def filters(controller, names)
+          names.to_h { |name| [name, scalar(controller.params[name])] }.compact_blank
+        end
+
+        def audit_filters(controller)
+          filters(controller, AUDIT_FILTERS)
+        end
+      end
+
+      requests = Requests
+
+      # A person's page: effective access tab, audit tab, the CSV of their changes.
+      register('permission_forge/people#show', 'audit.exported',
+               only_if: requests.method(:csv?),
+               payload: ->(controller) { requests.person(controller, 'scope' => 'person', 'format' => 'csv') })
+      register('permission_forge/people#show', 'admin.effective_access_viewed',
+               only_if: ->(controller) { requests.tab?(controller, 'effective') },
+               payload: ->(controller) { requests.person(controller, 'scope' => 'person') })
+      register('permission_forge/people#show', 'audit.viewed',
+               only_if: ->(controller) { requests.tab?(controller, 'audit') },
+               payload: ->(controller) { requests.person(controller, 'scope' => 'person') })
+
+      # A Permission Set's audit tab and its CSV export.
+      register('permission_forge/permission_sets#show', 'audit.exported',
+               only_if: requests.method(:csv?),
+               payload: lambda { |controller|
+                 requests.permission_set(controller, 'scope' => 'permission_set', 'format' => 'csv', 'filters' => requests.audit_filters(controller))
+               })
+      register('permission_forge/permission_sets#show', 'audit.viewed',
+               only_if: ->(controller) { requests.tab?(controller, 'audit') },
+               payload: lambda { |controller|
+                 requests.permission_set(controller, 'scope' => 'permission_set', 'filters' => requests.audit_filters(controller))
+               })
+
+      # The field drawer's "explain for a person": that person's effective access to the field.
+      # Same test as the controller's (`params[:explain_user_id].present?`), so whatever it explains is recorded.
+      register('permission_forge/resource_fields#show', 'admin.effective_access_viewed',
+               only_if: ->(controller) { controller.params[:explain_user_id].present? },
+               payload: lambda { |controller|
+                 { subject_user_id: requests.id_param(controller, :explain_user_id),
+                   permission_set: requests.find_set(requests.id_param(controller, :permission_set_id)),
+                   data: { 'scope' => 'field', 'resource' => controller.params[:resource_model].to_s, 'field' => controller.params[:key].to_s } }
+               })
+
+      # The audit log pages (AuditEventsController): the filtered list, its
+      # CSV / JSON export, one event, and the "who holds what" export.
+      register('permission_forge/audit_events#index', 'audit.exported',
+               only_if: requests.method(:export?),
+               payload: lambda { |controller|
+                 { data: { 'scope' => 'log', 'format' => requests.export_format(controller),
+                           'filters' => requests.filters(controller, Requests::LOG_FILTERS) } }
+               })
+      register('permission_forge/audit_events#index', 'audit.viewed',
+               payload: lambda { |controller|
+                 { data: { 'scope' => 'log', 'filters' => requests.filters(controller, Requests::LOG_FILTERS + %w[views page]) } }
+               })
+      register('permission_forge/audit_events#show', 'audit.viewed',
+               payload: ->(controller) { { data: { 'scope' => 'event', 'identifier' => requests.id_param(controller, :id) } } })
+      register('permission_forge/audit_events#holdings', 'audit.exported',
+               payload: ->(controller) { { data: { 'scope' => 'holdings', 'format' => requests.export_format(controller) } } })
+
+      # The JSON API's audit log (Api::AuditEventsController): a page of events, or one.
+      register('permission_forge/api/audit_events#index', 'audit.viewed',
+               payload: ->(controller) { { data: { 'scope' => 'api', 'filters' => requests.filters(controller, Requests::API_FILTERS) } } })
+      register('permission_forge/api/audit_events#show', 'audit.viewed',
+               payload: ->(controller) { { data: { 'scope' => 'api', 'identifier' => requests.id_param(controller, :identifier) } } })
+    end
+  end
+end

data/lib/permission_forge/audit/boot_warnings.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Audit
+    # The audit boot warnings, written by the engine once the database is
+    # reachable. The missing-table warning is logged by Audit (once per
+    # process, by Audit.verify_table!) with the text of .missing_table; this
+    # adds auditing switched off and one shared login for every change.
+    #
+    # @api private
+    module BootWarnings
+      def self.call(configuration = PermissionForge.configuration)
+        PermissionForge::Audit.verify_table!
+
+        if configuration.audit_events == false
+          Rails.logger&.warn '[PermissionForge] SECURITY warning: audit_events is false, so permission changes ' \
+                             'are not recorded. Set config.audit_events = :auto unless another system records them.'
+        end
+
+        return unless configuration.http_basic_auth_enabled && configuration.audit_actor_resolver.nil?
+
+        Rails.logger&.warn '[PermissionForge] The admin UI uses HTTP Basic auth and audit_actor_resolver is not ' \
+                           'set: every change is attributed to the shared login. Set ' \
+                           'config.audit_actor_resolver to return the signed-in admin.'
+      end
+
+      # The missing-table warning (Audit logs it once per process). Its
+      # remedy depends on the app: a migration of the gem's that creates the
+      # table is there (a fresh install, or an upgrade already generated) and
+      # has not run — db:migrate; none — the install predates the audit log,
+      # and the upgrade generator writes it (on a fresh install it would
+      # duplicate migrations).
+      #
+      # @param table [String] the audit events table name
+      # @return [String]
+      def self.missing_table(table)
+        remedy = if audit_migration_present?
+                   'the pending migration has run (bin/rails db:migrate)'
+                 else
+                   'its migration is generated and run (bin/rails generate permission_forge:upgrade, then bin/rails db:migrate)'
+                 end
+        "[PermissionForge] audit_events is :auto but the table '#{table}' was not found: no audit events are " \
+          "recorded until #{remedy}. Changes still work."
+      end
+
+      # @return [Boolean] whether a permission_forge migration in the app's
+      #   migration paths creates the audit events table
+      def self.audit_migration_present?
+        Array(ActiveRecord::Migrator.migrations_paths).any? do |path|
+          Dir.glob(File.join(path.to_s, '*permission_forge*.rb')).any? { |file| File.read(file).include?('audit_events') }
+        end
+      rescue SystemCallError
+        false
+      end
+      private_class_method :audit_migration_present?
+    end
+  end
+end

data/lib/permission_forge/audit/column_values.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Audit
+    # The one cleaning of every string an event stores in a column of its own
+    # — whoever supplied it: a request (reason, a typed Basic username, a
+    # request id), the host (a resolver's label, with_audit_actor, a rake
+    # ACTOR or REASON) or the gem. Audit::Recorder applies it to every event
+    # it builds.
+    #
+    #   - valid UTF-8 (invalid bytes replaced), so a row is never refused
+    #   - one line: tab, newline and the other line breaks become a space;
+    #     NUL (PostgreSQL refuses it) and every other C0/C1 control character
+    #     (terminal escapes) are removed
+    #   - at most LIMIT characters: the columns are varchar(255), and MySQL
+    #     in strict mode refuses — not truncates — a longer value, which
+    #     would let a client keep its own refusal out of the log
+    #
+    # `data` (JSON, escaped by the encoder) is left as it is.
+    #
+    # @api private
+    module ColumnValues
+      LIMIT = 255
+      COLUMNS = %i[event category actor_type actor_id actor_label source record_type record_id record_uuid record_label
+                   permission_set_uuid subject_user_id reason request_id ip correlation_id].freeze
+      LINE_BREAKS = /[\t\n\v\f\r\u0085

]/
+      CONTROLS = /[\u0000-\u001F\u007F-\u009F]/
+
+      class << self
+        # @param row [Hash] the event's attributes
+        # @return [Hash] a copy with every String in COLUMNS cleaned
+        def clean(row)
+          row.to_h { |column, value| [column, COLUMNS.include?(column) ? value(value) : value] }
+        end
+
+        # @return [String, Object] a cleaned String; anything else unchanged
+        def value(value)
+          return value unless value.is_a?(String)
+
+          utf8(value).gsub(LINE_BREAKS, ' ').gsub(CONTROLS, '')[0, LIMIT]
+        end
+
+        private
+
+        def utf8(value)
+          text = if [Encoding::UTF_8, Encoding::BINARY].include?(value.encoding)
+                   value.dup.force_encoding(Encoding::UTF_8)
+                 else
+                   value.encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+                 end
+          text.scrub
+        end
+      end
+    end
+  end
+end