permission_forge 0.14.1 → 0.15.0

data/lib/permission_forge/field_names.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  # Whether a ResourceField name names something on the Resource's model —
+  # what `rake permission_forge:audit` reports (integrity/unknown_fields): a
+  # typo such as `emial` configures nothing the model has. Saving does not
+  # refuse such a name: FiltersResponseAttributes filters any key of a hash
+  # (a key only a serializer computes is configured by a row of its name).
+  # A name is a field of the model when it is
+  #
+  # - a column of its table (a model's `ignored_columns` included), read
+  #   again from the database before the name is called unknown
+  #   (PermissionForge::SchemaRead): the schema cache may predate a column a
+  #   migration just added;
+  # - an attribute (`attribute :nickname`) or an `alias_attribute`;
+  # - a virtual field: declared (extra_fields_method, also a key only a
+  #   serializer computes) or discovered (store accessors, attribute-API
+  #   attributes) — PermissionForge::VirtualFields;
+  # - a public reader or writer (a store accessor with a custom prefix, a
+  #   `delegate … prefix: true`, `has_secure_password`'s `password=`),
+  #   as FieldVariants counts one; or
+  # - a configured variant (config.field_variant_mappings) of one of those
+  #   or of another row of the Resource: `owner_uuid` next to `owner_id`,
+  #   the key a serializer computes and FiltersResponseAttributes reads by
+  #   its base field (FieldVariants.base_entries).
+  #
+  # Any of those on a loaded single-table-inheritance subclass of the model
+  # (one on the same table) counts too: a row on the base Resource reaches
+  # the subclass's records (ResourceChain), so `vip_level`, a method only
+  # VipCustomer defines, is a field of Customer's rows. A subclass not
+  # loaded yet (development, before it is referenced) is not seen.
+  #
+  # Nothing is said (.for returns nil) when the model cannot be told: the
+  # Resource names no Active Record model this app can load (a Resource
+  # shared with another app), an abstract class, a table that does not exist
+  # (yet), or a database that cannot be asked.
+  #
+  # @example
+  #   names = PermissionForge::FieldNames.for('Customer')
+  #   names.include?('email') # => true
+  #   names.include?('emial') # => false
+  #
+  # @api private
+  class FieldNames
+    # Errors that mean the model cannot be told now.
+    UNREADABLE = [NameError, ArgumentError, ActiveRecord::ActiveRecordError].freeze
+
+    # @param resource_name [String, Symbol, nil] the Resource's name
+    # @param siblings [Array<String>, #call] the names of the Resource's other
+    #   rows (variant bases), or what answers them (asked only when needed)
+    # @return [FieldNames, nil] nil when the model cannot be told
+    def self.for(resource_name, siblings: [], configuration: PermissionForge.configuration)
+      model = ModelLookup.model_for(resource_name)
+      return unless model
+
+      new(model, siblings: siblings, configuration: configuration)
+    rescue *UNREADABLE
+      nil
+    end
+
+    # An attribute, an alias, or a public reader or writer of the model —
+    # the one answer to "the model has this name" (FieldNames, FieldVariants).
+    # A name the table has no column for is asked again after the schema is
+    # read again, once (PermissionForge::SchemaRead.has?): a column a
+    # migration just added is an attribute.
+    #
+    # @param model [Class]
+    # @param name [String]
+    # @return [Boolean]
+    def self.declares?(model, name)
+      name = name.to_s
+      SchemaRead.has?(model, name) do
+        model.attribute_names.include?(name) || model.attribute_alias?(name) || model.public_method_defined?(name) ||
+          model.public_method_defined?("#{name}=")
+      end
+    end
+
+    # @return [Class] the Resource's model
+    attr_reader :model
+
+    def initialize(model, siblings: [], configuration: PermissionForge.configuration)
+      @model = model
+      @siblings = siblings
+      @configuration = configuration
+    end
+
+    # @param name [String, Symbol]
+    # @return [Boolean] whether the model has the name (its table read again,
+    #   once, before saying no: PermissionForge::SchemaRead)
+    def include?(name)
+      name = name.to_s
+      SchemaRead.has?(@model, name) { known?(name) }
+    rescue *UNREADABLE
+      true
+    end
+
+    private
+
+    def known?(name)
+      forget_stale_memos
+      own?(name) || variant?(name)
+    end
+
+    # The subclasses and virtual fields as of the schema the cache holds now:
+    # a re-read (SchemaRead) resets the model's attributes.
+    def forget_stale_memos
+      reads = SchemaRead.rereads
+      return if @reads == reads
+
+      @reads = reads
+      @virtual_fields = nil
+      @models = nil
+    end
+
+    def own?(name)
+      columns.include?(name) || models.any? { |model| virtual_fields(model).include?(name) || self.class.declares?(model, name) }
+    end
+
+    def variant?(name)
+      bases = models.flat_map { |model| model.attribute_names + virtual_fields(model).names }
+      (columns + bases + siblings).uniq.any? do |base|
+        base != name && @configuration.field_variants_for(base).include?(name)
+      end
+    end
+
+    # The model and its loaded subclasses on the same table (STI).
+    def models
+      @models ||= [@model] + @model.descendants.select { |sub| sub.table_name == @model.table_name }
+    end
+
+    def siblings
+      @siblings = Array(@siblings.respond_to?(:call) ? @siblings.call : @siblings).map(&:to_s)
+    end
+
+    # The table's columns as the database has them: ignored_columns too.
+    def columns
+      SchemaRead.columns(@model).keys
+    end
+
+    def virtual_fields(model)
+      @virtual_fields ||= {}
+      @virtual_fields[model] ||= VirtualFields.new(model, @configuration)
+    end
+  end
+end

data/lib/permission_forge/field_variants.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  # The names a field row's setting also applies to on one Resource:
+  # Configuration#field_variants_for (config.field_variant_mappings:
+  # `owner_id` → `owner_uuid`, `price_cents` → `price`), kept to the names
+  # the Resource's model has —
+  #
+  # - an attribute (a column, or one declared with `attribute`),
+  # - an `alias_attribute`,
+  # - a public reader or writer (a `delegate :uuid, to: :owner, prefix: true`
+  #   defines `owner_uuid`; `def owner_uuid=(uuid)` takes one), or
+  # - a virtual field, declared or discovered (PermissionForge::VirtualFields#include?)
+  #
+  # — the answer FieldNames gives (FieldNames.declares?, one definition). A
+  # name the table has no column for is asked again after the schema is
+  # read again, once (PermissionForge::SchemaRead): a variant column a
+  # migration just added gets its entry.
+  #
+  # A name the model does not have would be an entry in the permission hash
+  # for nothing (the admin's Effective access listed it as a field and
+  # counted it). A model that cannot be read — no such constant (a Resource
+  # shared with another app), not an Active Record model, a schema that
+  # cannot be loaded — keeps every variant, as before 0.15.
+  #
+  # A hash a serializer builds can still carry such a name (`owner_uuid`
+  # computed in a view): FiltersResponseAttributes reads it by the entry of
+  # the field it is a variant of (.base_entries), as when the hash had it.
+  #
+  # The one definition for the permission hash (granting and muting,
+  # PermissionHashBuilder / FieldPermissionMerger) and the admin
+  # (Admin::EffectiveFields, Admin::FieldDetail), which must agree.
+  #
+  # @example
+  #   variants = PermissionForge::FieldVariants.new('Customer')
+  #   variants.call('supplier_id') # => [] (Customer has no supplier_uuid)
+  #
+  # @api private
+  class FieldVariants
+    # Errors that mean the model's attributes cannot be read (no connection,
+    # a schema that cannot be loaded).
+    UNREADABLE = [ActiveRecord::ActiveRecordError].freeze
+
+    # The entries of the configured fields by the names of their variants
+    # (`owner_uuid` → the `owner_id` entry), to read a name that has no entry
+    # of its own. A name two fields map to (custom field_variant_mappings)
+    # gets the strictest of their entries (ResourceChain.strictest, the one
+    # definition): such a key is never more readable than any of its bases.
+    # This covers names the model does
+    # not have (serializer keys); a variant the model has gets its entry from
+    # FieldPermissionMerger, which merges every base row like any granting row.
+    #
+    # @param fields [Hash] a resource's field entries, by name
+    # @return [Hash{String => Hash}]
+    def self.base_entries(fields, configuration = PermissionForge.configuration)
+      bases = fields.each_with_object({}) do |(base, entry), by_variant|
+        configuration.field_variants_for(base).each { |variant| (by_variant[variant] ||= []) << entry }
+      end
+      bases.transform_values { |entries| ResourceChain.strictest(entries) }
+    end
+
+    # @param resource_name [String, Symbol] the Resource's name (a model's class name)
+    # @param configuration [Configuration]
+    def initialize(resource_name, configuration = PermissionForge.configuration)
+      @resource_name = resource_name.to_s
+      @configuration = configuration
+      @variants = {}
+    end
+
+    # @param field_name [String, Symbol]
+    # @return [Array<String>] the variants of the field that the model has
+    def call(field_name)
+      @variants[field_name.to_s] ||= @configuration.field_variants_for(field_name).select { |name| attribute?(name) }
+    end
+
+    private
+
+    def attribute?(name)
+      return true unless model
+
+      FieldNames.declares?(model, name) || virtual_fields.include?(name)
+    rescue *UNREADABLE
+      true
+    end
+
+    def model
+      return @model if defined?(@model)
+
+      @model = ModelLookup.model_for(@resource_name)
+    end
+
+    def virtual_fields
+      @virtual_fields ||= VirtualFields.new(model, @configuration)
+    end
+  end
+end

data/lib/permission_forge/generated_text.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  # The one definition of "this stored text is a default the gem generated",
+  # not something an admin wrote. Through 0.15 the gem stored English it had
+  # made up — a field or action row's label (`name.humanize`, the install
+  # migration's 'Untitled Field'), a rule's blocked message and the names of
+  # a set, a group or a rule created without one (the install migration's
+  # column defaults) — and showed it as if an admin had typed it, in every
+  # language. The writers store the name itself now and the models store
+  # nothing for a message or name nobody wrote; the rows stored before keep
+  # their text (no data is rewritten), and whatever displays one asks here
+  # and renders the locale's own words instead.
+  #
+  # Asked by PermissionRuleApplier.failure_message_for (a denial's
+  # message), the admin's labels (Admin::FieldLabel, Admin::ActionLabel: a
+  # generated label is no label), names (Admin::RecordName: an install
+  # default is named in the page's language) and form pre-fills
+  # (Admin::Prefill: blank for generated text).
+  #
+  # @example
+  #   GeneratedText.label?('Owner', 'owner_id')                         # => true
+  #   GeneratedText.failure_message?('You do not have permission to perform this action.') # => true
+  #   GeneratedText.name?('Untitled Rule', :permission_set_rule)        # => true
+  #
+  # @api private
+  module GeneratedText
+    # The label the install migration gives a field row (the column default).
+    UNTITLED_FIELD = 'Untitled Field'
+    # The names the install migration gave a set, a group and a rule created
+    # without one (the column defaults of installs made before 0.15), by kind
+    # (the model's `model_name.element`).
+    NAMES = {
+      permission_set: 'Untitled Permission Set',
+      permission_set_group: 'Untitled Permission Set Group',
+      permission_set_rule: 'Untitled Rule'
+    }.freeze
+    # The blocked messages the install migration gave a rule created without
+    # one (the column default of installs made before 0.15).
+    FAILURE_MESSAGES = ['You do not have permission to perform this action.'].freeze
+
+    module_function
+
+    # Whether a field or action row's label is nothing an admin wrote: blank,
+    # the name itself, the name humanized (what the gem stored through 0.15)
+    # or the install default. A label an admin typed that happens to equal
+    # the humanized name reads the same as one the gem generated — and as
+    # what Rails' own English would show for it.
+    #
+    # @param text [String, nil] the stored label
+    # @param name [String, Symbol] the row's name (a column, a virtual field, an action key)
+    # @return [Boolean]
+    def label?(text, name)
+      label = text.to_s.strip
+      return true if label.empty? || label == UNTITLED_FIELD
+
+      name = name.to_s
+      label == name || label == name.to_s.humanize
+    end
+
+    # Whether a rule's blocked message is the install migration's default.
+    #
+    # @param text [String, nil] the stored failure_message
+    # @return [Boolean]
+    def failure_message?(text)
+      FAILURE_MESSAGES.include?(text.to_s.strip)
+    end
+
+    # Whether a set's, group's or rule's name is the install migration's
+    # default for its kind.
+    #
+    # @param text [String, nil] the stored name
+    # @param kind [Symbol, Class, ActiveRecord::Base] :permission_set,
+    #   :permission_set_group or :permission_set_rule — or the model (class or record)
+    # @return [Boolean]
+    def name?(text, kind)
+      NAMES[kind_of(kind)] == text.to_s.strip
+    end
+
+    # Every text the install migration has given a column of the nine tables
+    # (an upgraded install still has them as column defaults): what no form
+    # may pre-fill.
+    #
+    # @return [Array<String>]
+    def install_defaults
+      [UNTITLED_FIELD, *NAMES.values, *FAILURE_MESSAGES]
+    end
+
+    def kind_of(kind)
+      kind = kind.class if kind.is_a?(ActiveRecord::Base)
+      kind.respond_to?(:model_name) ? kind.model_name.element.to_sym : kind.to_s.to_sym
+    end
+    private_class_method :kind_of
+  end
+end

data/lib/permission_forge/inspection_filters.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  # What #inspect hides on the gem's own models. Rails copies
+  # config.filter_parameters into ActiveRecord::Base.filter_attributes, so
+  # the GDPR patterns PermissionForge adds there (filter_parameters_integration:
+  # `\Aname\z`, …) also hid the *configuration* names of the gem's rows: a
+  # console printed `#<PermissionForge::PermissionSet … name: [FILTERED]>` for a
+  # set called "Sales rep", and a ResourceField's `name` (a column name such as
+  # "email") the same way.
+  #
+  # Each model sets its own list with Rails' `filter_attributes=` as its
+  # class body runs (after config/initializers, again after a reload):
+  #
+  # - .show_configuration_names: the inherited filters, each made unable to
+  #   match the model's configuration-name attributes (`name`, `label`,
+  #   `field_name`) — they keep hiding every other attribute they matched (a
+  #   rule's `field_value` or `failure_message`, a description). A Proc filter
+  #   is kept as it is: it decides for itself.
+  # - .hide_people_labels (AuditEvent): the inherited filters plus the
+  #   labels that name people (`actor_label`, `record_label`, which
+  #   DataSubjectErasure scrubs), whenever the inherited filters hide a
+  #   person's `name` — with the GDPR patterns, or a host's own `:name`.
+  #
+  # Only Regexps are added, so Rails 8's FilterAttributeHandler (which copies a
+  # model's String and Symbol entries back into config.filter_parameters as
+  # "model.attribute") adds nothing to the host's request-parameter filter.
+  # Request parameters, SQL bind logging (ActiveRecord::Base's filter) and the
+  # host's models are untouched. A filter added to
+  # ActiveRecord::Base.filter_attributes after a model has loaded does not
+  # reach it until the next reload.
+  #
+  # @api private
+  module InspectionFilters
+    # The attributes of the gem's models that hold configuration names.
+    CONFIGURATION_NAMES = %w[name label field_name].freeze
+    # AuditEvent's labels that name a person.
+    PEOPLE_LABELS = %w[actor_label record_label].freeze
+
+    module_function
+
+    # @param klass [Class] a model of the gem
+    # @return [void]
+    def show_configuration_names(klass, names = CONFIGURATION_NAMES)
+      klass.filter_attributes = sparing(klass.superclass.filter_attributes, names)
+    end
+
+    # @param klass [Class] PermissionForge::AuditEvent
+    # @return [void]
+    def hide_people_labels(klass, labels = PEOPLE_LABELS)
+      inherited = klass.superclass.filter_attributes
+      return unless hides?(inherited, 'name')
+
+      # The inherited entries as Regexps too (sparing nothing): a String or
+      # Symbol here would be copied into config.filter_parameters.
+      klass.filter_attributes = sparing(inherited, []) + [/\A(?:#{labels.map { |label| Regexp.escape(label) }.join('|')})\z/]
+    end
+
+    # `filters` (a filter_attributes list) with every String, Symbol and
+    # Regexp turned into a Regexp that matches what it matched, except the
+    # attribute names `names` themselves (none when `names` is empty). A
+    # String or Symbol matches as Rails reads it: anywhere in the name,
+    # ignoring case.
+    #
+    # @return [Array]
+    def sparing(filters, names)
+      guard = names.empty? ? '' : "\\A(?!(?:#{names.map { |name| Regexp.escape(name.to_s) }.join('|')})\\z).*?"
+      filters.map do |filter|
+        case filter
+        when Proc then filter
+        when Regexp
+          # Under /x a trailing comment would swallow the closing parenthesis.
+          Regexp.new("#{guard}(?:#{filter.source}#{"\n" if filter.options.anybits?(Regexp::EXTENDED)})", filter.options)
+        else Regexp.new("#{guard}(?:#{Regexp.escape(filter.to_s)})", Regexp::IGNORECASE)
+        end
+      end
+    end
+
+    def hides?(filters, attribute)
+      ActiveSupport::ParameterFilter.new(filters).filter_param(attribute, 'x') != 'x'
+    end
+  end
+end

data/lib/permission_forge/managed_fields.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  # The one definition of the fields a model's Resource has rows for: its
+  # columns (`ignored_columns` and config.ignored_fields left out), then its
+  # virtual fields (PermissionForge::VirtualFields: declared and
+  # discovered), whatever extra_fields_default_access says. Every path that
+  # creates rows for a model writes rows for these names and no others —
+  # the admin's presets, "Sync fields" and bulk add (a posted name outside
+  # them is no row), and ResourceFieldGenerator — so a level chosen for "all
+  # fields" (Hidden, say) reaches a virtual field on every path. The admin's
+  # model catalog lists them (Admin::ModelCatalog::ModelInfo#managed_field_names).
+  #
+  # The columns are read through PermissionForge::SchemaRead: compared with
+  # the database first with `verify: true` (a list that builds rows), from
+  # the schema cache without it (a count on every admin page).
+  #
+  # @api private
+  class ManagedFields
+    # @param model [Class] an Active Record model with a table
+    # @param configuration [Configuration]
+    # @param verify [Boolean] compare the columns with the database first
+    def initialize(model, configuration: PermissionForge.configuration, verify: true)
+      @model = model
+      @configuration = configuration
+      @verify = verify
+    end
+
+    # @return [Array<String>] the model's columns (`ignored_columns` excluded)
+    def column_names
+      @column_names ||= SchemaRead.column_names(@model, verify: @verify)
+    end
+
+    # @return [Array<String>] the columns config.ignored_fields leaves out
+    def ignored_column_names
+      column_names & ignored_fields
+    end
+
+    # @return [Array<String>] the columns that get rows
+    def managed_column_names
+      column_names - ignored_fields
+    end
+
+    # @return [Array<String>] declared and discovered virtual fields
+    def virtual_field_names
+      virtual_fields.names
+    end
+
+    # @return [Array<String>] managed columns, then virtual fields
+    def names
+      managed_column_names + virtual_field_names
+    end
+
+    # @return [VirtualFields]
+    def virtual_fields
+      @virtual_fields ||= VirtualFields.new(@model, @configuration)
+    end
+
+    private
+
+    # Symbols or Strings, as the host wrote them.
+    def ignored_fields
+      @ignored_fields ||= Array(@configuration.ignored_fields).map(&:to_s)
+    end
+  end
+end

data/lib/permission_forge/masked_models.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'database_reach'
+
 module PermissionForge
   # Auto-applied masking: mixes MaskedAttributes into the models
   # config.auto_apply_masked_attributes selects and wraps the virtual readers
@@ -44,11 +46,12 @@ module PermissionForge
       def apply(only: nil)
         config = PermissionForge.configuration
         return true unless enabled?(config)
-        return false unless PermissionForge::Resource.table_exists?
+        # No database to use (not configured, unreachable), or no table yet.
+        return false unless DatabaseReach.table_exists?(PermissionForge::Resource)
 
         apply_selected(config, only).all? & unknown_listed_names(config, only).empty?
-      rescue ActiveRecord::StatementInvalid, ActiveRecord::ConnectionNotEstablished
-        # Tables may not exist yet during early boot or pre-migration.
+      rescue *DatabaseReach::READ_ERRORS
+        # The database went away while the rows were read.
         false
       end
 
@@ -162,8 +165,9 @@ module PermissionForge
       def warn_unknown(setting, name)
         return if unmaskable_warned.put_if_absent("#{setting}=#{name}", true)
 
-        Rails.logger&.warn("[PermissionForge] SECURITY warning: '#{name}' is listed in config.#{setting} but is no " \
-                           'model in this process: nothing is masked for it. It is tried again at the next request or job.')
+        Warnings.emit("masked_models.unknown_listed.#{setting}=#{name}",
+                      "'#{name}' is listed in config.#{setting} but is no model in this process: nothing is " \
+                      'masked for it. It is tried again at the next request or job.', severity: :security)
       end
 
       # Every tenant's rows: a model is masked for the whole process.
@@ -187,29 +191,31 @@ module PermissionForge
       #
       # @return [String, nil] why the concern cannot be included now
       def unmaskable_reason(klass)
-        return 'its table cannot be read' unless readable_table?(klass)
-
-        'an earlier attempt failed halfway; restart the process' if klass.include?(PermissionForge::Concerns::MaskedAttributes)
+        unreadable_table(klass) ||
+          ('an earlier attempt failed halfway; restart the process' if klass.include?(PermissionForge::Concerns::MaskedAttributes))
       end
 
-      # The table exists and can be read. A table found missing is looked up
-      # again next time (the cached answer is dropped): a migration may run.
-      def readable_table?(klass)
-        return true if klass.table_exists?
+      # Why the table cannot be read, nil when it exists and can be. A table
+      # found missing is looked up again next time (the cached answer is
+      # dropped): a migration may run. Its database may be another one than
+      # the gem's (a host on several databases); a check that raised names
+      # the error (DatabaseReach): the model's own table_name, its database
+      # not configured.
+      def unreadable_table(klass)
+        cause = nil
+        return if DatabaseReach.table_exists?(klass) { |error| cause = error }
 
-        klass.reset_column_information
-        false
-      rescue ActiveRecord::StatementInvalid, ActiveRecord::ConnectionNotEstablished
-        false
+        cause ? "its table cannot be read (#{cause.class}: #{cause.message.lines.first&.strip})" : 'its table cannot be read'
       end
 
-      # Logs once per model and process (MaskingSync retries every request).
+      # Warns once per model and process (MaskingSync retries every request).
       def warn_unmaskable(klass, why)
         name = klass.to_s
         return if unmaskable_warned.put_if_absent(name, true)
 
-        Rails.logger&.warn("[PermissionForge] SECURITY warning: #{name} has a Resource row but #{why}: its columns " \
-                           'are NOT masked in this process. It is tried again at the next request or job.')
+        Warnings.emit("masked_models.unmaskable.#{name}",
+                      "#{name} has a Resource row but #{why}: its columns are NOT masked in this process. " \
+                      'It is tried again at the next request or job.', severity: :security)
       end
 
       # The models (and unknown listed names) whose warning this process has logged.