permission_forge 0.14.1

data/lib/permission_forge/concerns/masked_attributes/alias_access.rb

@@ -0,0 +1,280 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Concerns
+    module MaskedAttributes
+      # `alias_attribute` on a model with MaskedAttributes. An alias is not a
+      # field of its own: reading or writing it is reading or writing the
+      # attribute it points to, at that attribute's level.
+      #
+      # Rails generates an alias's reader and writer to reach the attribute
+      # directly — always on Rails 7.2 and later, and on 7.1 unless the model
+      # defines the target's method itself — past the masked getter and the
+      # guarded setter. So every alias gets a reader and a writer here that do
+      # what the Rails version in use does, plus the guard (see
+      # {AttributeAccessors} and {TargetMethodAccessors}).
+      #
+      # Where they live decides which of the model's own methods still run.
+      # Rails keeps an alias's methods in the generated-attribute-methods
+      # module of the class that declares it; the accessors go in a module
+      # prepended to that very module. Whatever is found before Rails' own
+      # alias methods — the class's methods, modules it includes, subclasses —
+      # is found before these too, and `super` there reaches them.
+      #
+      # They never call `super` themselves: Ruby (3.4 at least) does not
+      # notice that the method behind a module prepended to an already
+      # included module was redefined, and would keep calling the old one.
+      #
+      # The other methods Rails generates for an alias (`mail?`, `mail_was`,
+      # `mail_changed?`, `mail_before_type_cast`…) are already the target's
+      # (`email?`, `email_was`…) under another name and are left alone.
+      #
+      # @api private
+      module AliasAccess
+        extend ActiveSupport::Concern
+
+        # The module a class's alias readers and writers live in.
+        class AccessorModule < Module; end
+
+        # `id_value`, which Rails itself aliases to `id`, stays Rails': `id`
+        # is the primary key reader, not the reader of a column called id.
+        UNMASKED_TARGET = 'id'
+
+        CREATION = Mutex.new
+        private_constant :CREATION
+
+        # Rails 7.2 and later: an alias reads and writes the attribute itself,
+        # whatever reader or setter the model defines for the target. So do
+        # these: through `read_attribute` when the target's reader is one the
+        # concern masks, and past the write-back guard when the target is a
+        # masked column.
+        #
+        # An alias declared by a class without the concern (a parent of the
+        # one that has it) is reached by records of its other subclasses too.
+        # For those, this is what Rails generates, word for word. Such a class
+        # may declare the alias again with another target without the concern
+        # hearing of it, so the target is asked of the declaring class at each
+        # call, as Rails generates the alias's methods again there.
+        module AttributeAccessors
+          def self.define(klass, accessors, name, declared)
+            accessors.redefine_method(name, &reader(klass, name, declared))
+            accessors.redefine_method(:"#{name}=", &writer(klass, name, declared))
+          end
+
+          def self.reader(klass, name, declared)
+            proc do
+              target = klass.attribute_aliases.fetch(name, declared)
+              if is_a?(MaskedAttributes) && pf_masked_reader?(target)
+                read_attribute(target) { |missing| missing_attribute(missing, caller) }
+              else
+                _read_attribute(target) { |missing| missing_attribute(missing, caller) }
+              end
+            end
+          end
+
+          def self.writer(klass, name, declared)
+            proc do |value|
+              target = klass.attribute_aliases.fetch(name, declared)
+              next if is_a?(MaskedAttributes) && pf_masked_column?(target) && pf_skip_masked_write?(target, value)
+
+              _write_attribute(target, value)
+            end
+          end
+        end
+
+        # Rails 7.1: an alias calls the target's own reader or setter when the
+        # model defines it (deprecated there) or the target is not an
+        # attribute, and otherwise reads and writes the attribute as later
+        # versions do. So do these.
+        module TargetMethodAccessors
+          def self.define(klass, accessors, name, declared)
+            own = OwnMethods.new(klass, name, declared)
+            attribute_reader = AttributeAccessors.reader(klass, name, declared)
+            attribute_writer = AttributeAccessors.writer(klass, name, declared)
+            accessors.redefine_method(name) do
+              (reader = own.reader) ? send(reader) : instance_exec(&attribute_reader)
+            end
+            accessors.redefine_method(:"#{name}=") do |value|
+              (setter = own.setter) ? send(setter, value) : instance_exec(value, &attribute_writer)
+            end
+          end
+
+          # The target's methods an alias calls on Rails 7.1. The choice is
+          # Rails' own (`alias_attribute_method_definition`), made once per
+          # method on the class that declares the alias, with the concern's
+          # modules looked past: seen by Rails, the masked getter is a method
+          # the model defines.
+          class OwnMethods
+            def initialize(klass, name, declared)
+              @klass = klass
+              @name = name
+              @declared = declared
+              @choices = {}
+            end
+
+            # @return [String, nil] the reader to call; nil to read the attribute
+            def reader
+              own(target)
+            end
+
+            # @return [String, nil] the setter to call; nil to write the attribute
+            def setter
+              own("#{target}=")
+            end
+
+            private
+
+            def target
+              @klass.attribute_aliases.fetch(@name, @declared)
+            end
+
+            def own(method_name)
+              @choices.fetch(method_name) { @choices[method_name] = (method_name if defined_by_the_model?(method_name)) }
+            end
+
+            def defined_by_the_model?(method_name)
+              return true unless @klass.abstract_class? || @klass.has_attribute?(target)
+              return false if ActiveRecord::AttributeMethods.dangerous_attribute_methods.include?(method_name)
+
+              owner = owner_outside_the_concern(method_name)
+              !owner.nil? && !owner.is_a?(ActiveRecord::AttributeMethods::GeneratedAttributeMethods)
+            end
+
+            def owner_outside_the_concern(method_name)
+              method = @klass.instance_method(method_name)
+              method = method.super_method while method && concern_module?(method.owner)
+              method&.owner
+            rescue NameError
+              nil
+            end
+
+            def concern_module?(owner)
+              [ColumnAccessors, VirtualReaders::ReaderModule, AccessorModule].any? { |kind| owner.is_a?(kind) }
+            end
+          end
+        end
+
+        class << self
+          # Defines the reader and the writer of one alias `klass` declares.
+          def define_accessors(klass, name, target)
+            target = target.to_s
+            return if target == UNMASKED_TARGET
+
+            accessors.define(klass, accessor_module(klass), name.to_s, target)
+          end
+
+          # Covers the aliases `klass` itself declared, where Rails generates
+          # their methods: in `klass`, not in the classes that inherit them.
+          def mask_aliases_declared_by(klass)
+            declared_aliases(klass).each { |name, target| define_accessors(klass, name, target) }
+          end
+
+          # @return [String, nil] the attribute `name` is an alias of on
+          #   `klass`, following aliases of aliases
+          def target(klass, name)
+            aliases = klass.attribute_aliases
+            target = aliases[name.to_s]
+            target && chain_end(aliases, target)
+          end
+
+          # The attribute at the end of a chain of aliases that starts with
+          # `target`. Bounded, so aliases that point at each other end too.
+          def chain_end(aliases, target)
+            aliases.size.times { target = aliases.fetch(target) { return target } }
+            target
+          end
+
+          private
+
+          def accessors
+            @accessors ||= ActiveRecord.version < Gem::Version.new('7.2') ? TargetMethodAccessors : AttributeAccessors
+          end
+
+          # The class's own module, prepended to the module Rails generates
+          # the class's attribute methods into.
+          def accessor_module(klass)
+            CREATION.synchronize do
+              next klass.const_get(:MaskedAliasAccessors, false) if klass.const_defined?(:MaskedAliasAccessors, false)
+
+              klass.const_set(:MaskedAliasAccessors, AccessorModule.new)
+                   .tap { |accessors| klass.send(:generated_attribute_methods).prepend(accessors) }
+            end
+          end
+
+          # Rails keeps the aliases each class declares in a registry of its
+          # own; without one, the aliases that differ from the superclass's.
+          def declared_aliases(klass)
+            return registered_aliases(klass) if klass.respond_to?(:aliases_by_attribute_name)
+
+            inherited = klass.superclass.attribute_aliases
+            klass.attribute_aliases.reject { |name, target| inherited[name] == target }.to_a
+          end
+
+          # The registry keeps the old target of an alias that was declared
+          # again with another one; only what the alias points to now counts.
+          def registered_aliases(klass)
+            current = klass.attribute_aliases
+            klass.aliases_by_attribute_name
+                 .flat_map { |target, names| names.map { |name| [name, target] } }
+                 .select { |name, target| current[name] == target }
+          end
+        end
+
+        # Extended into the model by ActiveSupport::Concern.
+        module ClassMethods
+          # The accessors are defined before Rails registers the alias, so
+          # they are in place however soon Rails generates its own.
+          def alias_attribute(new_name, old_name)
+            AliasAccess.define_accessors(self, new_name, old_name)
+            super
+          end
+
+          private
+
+          # For the aliases that were declared before the concern was
+          # included, each in the class that declared it: this class, its
+          # ancestors (which do not have the concern) and the subclasses that
+          # are loaded.
+          def pf_mask_attribute_aliases
+            lineage = ancestors.grep(Class).take_while { |klass| klass < ActiveRecord::Base }
+            (lineage + descendants).each { |klass| AliasAccess.mask_aliases_declared_by(klass) }
+          end
+        end
+
+        # `methods:` names that are aliases of an attribute the current user
+        # may not read are dropped, the way the attribute itself is dropped
+        # from the attribute names. Only a loaded attribute is: reading an
+        # alias of one that was not loaded raises, as on any model.
+        #
+        # This module is included before MaskedAttributes itself (it is a
+        # dependency): while the concern is being included, on another
+        # thread, a record answers as it did without it.
+        def serializable_hash(options = nil)
+          return super unless is_a?(MaskedAttributes)
+
+          super(pf_without_hidden_alias_methods(options))
+        end
+
+        private
+
+        # The attribute an alias that points to `target` is judged as.
+        def pf_alias_end(target)
+          AliasAccess.chain_end(self.class.attribute_aliases, target)
+        end
+
+        def pf_without_hidden_alias_methods(options)
+          methods = options && options[:methods]
+          return options unless methods && (pf_guarded_user || pf_hide_without_user?) &&
+                                PermissionForge.configuration.omit_hidden_in_attributes_hash
+
+          options.merge(methods: Array(methods).reject { |name| pf_hidden_alias?(name) })
+        end
+
+        def pf_hidden_alias?(name)
+          target = AliasAccess.target(self.class, name)
+          target && has_attribute?(target) && pf_hidden_attribute?(target)
+        end
+      end
+    end
+  end
+end

data/lib/permission_forge/concerns/masked_attributes/store_access.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Concerns
+    module MaskedAttributes
+      # Store accessors (`store :settings, accessors: [:theme]`,
+      # `store_accessor`) reach the store column through its public getter —
+      # the masked one. Left alone, a hidden or masked store column makes Rails
+      # see nil (or the mask) where it expects the stored hash: depending on
+      # the Rails version the read raises, or Rails replaces the column with an
+      # empty hash in memory and a later save wipes the stored data.
+      #
+      #   - Reading a key of a store column the user may not read in full
+      #     returns the hidden value and never touches the column.
+      #   - Writing a key works on the real stored hash, so the other keys
+      #     survive. The accessors and the column getter still return nothing
+      #     readable afterwards.
+      #
+      # Only stores whose getter this concern masks are affected (a column, or
+      # a wrapped virtual reader while virtual masking is on); any other store
+      # is left to Rails.
+      #
+      # @api private
+      module StoreAccess
+        # Fiber-local ExecutionState slot: map (by identity) of record => the
+        # store column an accessor is writing. Kept beside the record, like
+        # the virtual-masking escape hatch, so a copy made during the write
+        # or another thread holding the record never reads the column raw.
+        RAW_STORE_KEY = :pf_raw_store_columns
+
+        private
+
+        def read_store_attribute(store_attribute, key)
+          return super if pf_store_column_readable?(store_attribute) || pf_store_column_unloaded?(store_attribute)
+
+          PermissionForge.configuration.hidden_attribute_value
+        end
+
+        def write_store_attribute(store_attribute, key, value)
+          pf_with_raw_store_column(store_attribute) { super }
+        end
+
+        # The attribute Rails reads the store through: a store may be declared
+        # on an alias_attribute name.
+        def pf_store_column_name(store_attribute)
+          name = store_attribute.to_s
+          self.class.attribute_aliases[name] || name
+        end
+
+        # Readable in full for the current user. Asked of the guard with a
+        # probe rather than by comparing stored values: a store that is nil
+        # (a NULL json column, a new record) must not look "readable".
+        def pf_store_column_readable?(store_attribute)
+          name = pf_store_column_name(store_attribute)
+          return true unless pf_masked_reader?(name)
+
+          include_field, value = pf_guard(name, VirtualReaders::PROBE)
+          include_field && value.equal?(VirtualReaders::PROBE)
+        end
+
+        # A store column the record was loaded without (`select(:id)`). Rails
+        # raises ActiveModel::MissingAttributeError when an accessor reads or
+        # writes one of its keys; hidden or not, it is left to do so.
+        def pf_store_column_unloaded?(store_attribute)
+          name = pf_store_column_name(store_attribute)
+          self.class.has_attribute?(name) && !has_attribute?(name)
+        end
+
+        # Whether the reader of `name` is one this concern masks: the one Rails
+        # is about to call for a store, or the target of an alias (AliasAccess).
+        def pf_masked_reader?(name)
+          pf_masked_column?(name) || (pf_mask_virtual_reads? && self.class.pf_virtual_reader_masked?(name))
+        end
+
+        # A column whose getter is masked and whose setter is guarded.
+        def pf_masked_column?(name)
+          klass = self.class
+          klass.const_defined?(:MaskedAttributeReaders) && klass::MaskedAttributeReaders.method_defined?(name)
+        end
+
+        # Inside the block this record's getter for the store column returns
+        # the stored value (see MaskedAttributes#read_attribute). Only that
+        # column, only this record on this fiber, and restored when
+        # the block ends.
+        def pf_with_raw_store_column(store_attribute)
+          windows = PermissionForge::ExecutionState.fetch(RAW_STORE_KEY) { {}.compare_by_identity }
+          previous = windows[self]
+          windows[self] = pf_store_column_name(store_attribute)
+          yield
+        ensure
+          previous ? windows[self] = previous : windows.delete(self)
+        end
+
+        def pf_raw_store_column?(name)
+          PermissionForge::ExecutionState[RAW_STORE_KEY]&.[](self) == name
+        end
+      end
+    end
+  end
+end

data/lib/permission_forge/concerns/masked_attributes/validation_reads.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Concerns
+    module MaskedAttributes
+      # Validations judge the stored value; what they report shows what the
+      # current user reads.
+      #
+      # A hidden or masked value would fail a presence or format check the
+      # stored value passes (nobody signed in under :hide, a user who reads
+      # `s***@acme.com` or nothing) and pass a uniqueness check against the
+      # mask. So while the validators run (run_validations!), the attribute
+      # Rails reads for a validation (read_attribute_for_validation) — that
+      # one attribute, nothing else of the record — reads as stored: a derived
+      # reader that reads other columns sees them masked, as always.
+      #
+      # Rails puts the value it validated into the error (value:, which
+      # errors.details returns and %{value} interpolates). When the
+      # validators are done, every error's value is replaced with what the
+      # current user's getter returns, or removed when the user may not read
+      # the attribute. A message rendered later reads the getter
+      # (read_attribute_for_validation outside the validators), so %{value}
+      # in a custom or i18n message shows the masked value or nothing.
+      #
+      # A Rails EachValidator reads the attribute through
+      # read_attribute_for_validation and then, in numericality, again with
+      # read_attribute (prepare_value_for_validation). So while an
+      # EachValidator judges this record (EachValidatorWindow), the attribute
+      # it last read for a validation stays readable as stored until the
+      # validator is done; anything else — another validator, a custom
+      # `validate` block — reads masked.
+      #
+      # @api private
+      module ValidationReads
+        # ExecutionState slots (fiber, by record identity): the records whose
+        # validators are running, and the attribute each is reading for one.
+        VALIDATING_KEY = :pf_validating_records
+        READS_KEY = :pf_validation_reads
+        # The records an EachValidator is judging right now.
+        WINDOWS_KEY = :pf_validator_windows
+
+        # Prepended to ActiveModel::EachValidator: keeps the attribute it
+        # read for a validation readable as stored until it is done.
+        module EachValidatorWindow
+          def validate(record)
+            return super unless record.is_a?(MaskedAttributes)
+
+            ValidationReads.within_validator(record) { super }
+          end
+        end
+
+        # @api private
+        def self.within_validator(record)
+          windows = PermissionForge::ExecutionState.fetch(WINDOWS_KEY) { Set.new.compare_by_identity }
+          added = windows.add?(record)
+          yield
+        ensure
+          if added
+            windows.delete(record)
+            PermissionForge::ExecutionState[READS_KEY]&.delete(record)
+          end
+        end
+
+        def read_attribute_for_validation(name)
+          window = pf_validator_window?
+          return super unless pf_validation_read_open?(window)
+
+          column = pf_validation_column(name)
+          pf_reading_for_validation(column || name.to_s, keep: window) do
+            column || !VirtualReaders.masked?(self.class, name) ? super : pf_without_virtual_masking { super }
+          end
+        end
+
+        private
+
+        def run_validations!
+          validating = PermissionForge::ExecutionState.fetch(VALIDATING_KEY) { Set.new.compare_by_identity }
+          added = validating.add?(self)
+          super
+        ensure
+          validating&.delete(self) if added
+          pf_mask_error_values
+        end
+
+        def pf_validating?
+          PermissionForge::ExecutionState[VALIDATING_KEY]&.include?(self) || false
+        end
+
+        # Validating, and no other validation read in progress — or inside an
+        # EachValidator, whose next read replaces the last.
+        def pf_validation_read_open?(window)
+          pf_validating? && (window || !pf_validation_read)
+        end
+
+        # Marks `attribute` as read as stored for the block; inside an
+        # EachValidator (keep) it stays marked until the validator is done.
+        def pf_reading_for_validation(attribute, keep:)
+          reads = PermissionForge::ExecutionState.fetch(READS_KEY) { {}.compare_by_identity }
+          reads[self] = attribute
+          yield
+        ensure
+          reads&.delete(self) unless keep
+        end
+
+        def pf_validator_window?
+          PermissionForge::ExecutionState[WINDOWS_KEY]&.include?(self) || false
+        end
+
+        # The attribute a validator is reading on this record, or nil.
+        def pf_validation_read
+          PermissionForge::ExecutionState[READS_KEY]&.[](self)
+        end
+
+        # The column an attribute name reads (an alias as the attribute at
+        # the end of its chain), or nil for a method.
+        def pf_validation_column(name)
+          name = name.to_s
+          target = self.class.attribute_aliases[name]
+          name = pf_alias_end(target) if target
+          name if self.class.attribute_names.include?(name)
+        end
+
+        def pf_mask_error_values
+          errors.objects.each do |error|
+            options = error.options
+            next unless options.key?(:value) && error.attribute != :base
+
+            include_field, value = pf_error_value(error.attribute)
+            include_field ? options[:value] = value : options.delete(:value)
+          end
+        end
+
+        # [include?, value]: what the current user reads for the attribute,
+        # as a debugging read (no field.access decision). The primary key is
+        # never masked. Anything that fails leaves no value.
+        def pf_error_value(attribute)
+          column = pf_validation_column(attribute)
+          pf_while_inspecting do
+            if column
+              column == self.class.primary_key ? [true, _read_attribute(column)] : pf_guard(column, _read_attribute(column))
+            else
+              respond_to?(attribute) ? [true, public_send(attribute)] : [false, nil]
+            end
+          end
+        rescue StandardError
+          [false, nil]
+        end
+      end
+    end
+  end
+end
+
+ActiveModel::EachValidator.prepend(PermissionForge::Concerns::MaskedAttributes::ValidationReads::EachValidatorWindow)