permission_forge 0.14.1

data/lib/permission_forge/operators/value_casters.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative 'value_casters/number'
+require_relative 'value_casters/temporal'
+
+module PermissionForge
+  module Operators
+    # What a rule value becomes for a column of each ActiveRecord type: a Ruby
+    # value the adapter quotes as that type, or {UNUSABLE} when the text is not
+    # one of that type. Each caster is a `#call(value)`; {.for} picks the one
+    # for a column.
+    #
+    # The notations are the same on every database and deliberately narrower
+    # than Ruby's own parsers, which take `4_2`, `0x5` and `NaN`.
+    module ValueCasters
+      # A value the column cannot hold. A rule with one matches nothing.
+      UNUSABLE = Object.new.tap { |marker| marker.define_singleton_method(:inspect) { 'UNUSABLE' } }.freeze
+
+      # What PostgreSQL's boolean input takes. The id `current_user` stands for
+      # is not text, and so never a boolean.
+      BOOLEANS = {
+        true => true, 'true' => true, 't' => true, 'yes' => true, 'y' => true, 'on' => true, '1' => true,
+        false => false, 'false' => false, 'f' => false, 'no' => false, 'n' => false, 'off' => false, '0' => false
+      }.freeze
+
+      NUMBER = Number::EXACT
+
+      BOOLEAN = ->(value) { BOOLEANS.fetch(value.is_a?(String) ? value.strip.downcase : value, UNUSABLE) }
+
+      # Compared as written; the id `current_user` stands for, as its text.
+      TEXT = ->(value) { value.nil? ? UNUSABLE : value.to_s }
+
+      # A column type without a caster (uuid, json, an array column, ...) or a
+      # field name that names no known column: the value is left to the database.
+      UNTYPED = ->(value) { value }
+
+      BY_TYPE = {
+        integer: NUMBER, float: NUMBER, decimal: NUMBER,
+        boolean: BOOLEAN,
+        string: TEXT, text: TEXT,
+        date: Temporal::DATE, time: Temporal::TIME,
+        datetime: Temporal::DATETIME, timestamp: Temporal::DATETIME, timestamptz: Temporal::DATETIME
+      }.freeze
+
+      # PostgreSQL is typed like the others, with two things left the way it
+      # always did them, so that no rule that works there stops working:
+      #
+      # - It reads date and time text itself and raises on what it cannot
+      #   read. Text the Temporal casters do not recognise is left to it
+      #   (`due_on less_than '31 Jan 2026'`, `due_on equal 'today'`); on SQLite
+      #   and MySQL, which compare or convert such text, it stays UNUSABLE.
+      # - A `real` column is compared in single precision (Number::SINGLE_PRECISION).
+      #   The SQL type is the key: its ActiveRecord type is `float` as well.
+      POSTGRESQL = BY_TYPE.transform_values { |caster| caster.is_a?(Temporal) ? caster.as_written : caster }
+                          .merge('real' => Number::SINGLE_PRECISION).freeze
+
+      # Adapter name => the casters of that database, where they are not BY_TYPE.
+      BY_ADAPTER = { 'PostgreSQL' => POSTGRESQL, 'PostGIS' => POSTGRESQL }.freeze
+
+      # The casters that read the two bounds of `between` together, where the
+      # others cast one bound at a time. With nothing known about the column
+      # the pair is read as it was before values were typed: both integers,
+      # both decimals, both dates, or text.
+      BOUNDS = {
+        UNTYPED => ->(bounds) { Registry.coerce_between_values(*bounds) },
+        Number::SINGLE_PRECISION => Number::SINGLE_PRECISION_BOUNDS
+      }.freeze
+
+      # @param column [ActiveRecord::ConnectionAdapters::Column, nil]
+      # @param adapter_name [String, nil] the adapter of the column's model
+      # @return [#call] the caster for the column
+      def self.for(column, adapter_name = nil)
+        return UNTYPED if column.nil? || column.try(:array?)
+
+        casters = BY_ADAPTER.fetch(adapter_name, BY_TYPE)
+        casters.fetch(column.sql_type) { casters.fetch(column.type, UNTYPED) }
+      end
+    end
+  end
+end

data/lib/permission_forge/operators/value_typing.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Operators
+    # Gives a rule value the type of the column it is compared with, so no
+    # database is left to convert one side of a comparison.
+    #
+    # Rule values are text, and databases disagree about text compared with a
+    # number, a boolean or a date: PostgreSQL raises on text it cannot cast,
+    # SQLite compares as text, and MySQL converts — there `5 = '5_id'` and
+    # `0 = 'abc'` are true, and a boolean column equals `'true'` exactly when
+    # it is false. So the value is typed here, the same way for every database
+    # and for the RLS policy (Services::RlsOperatorSql):
+    #
+    # - a value the column can hold is bound as a value of its type
+    #   ({ValueCasters}); an enum label, as the value the model stores for it;
+    # - a value it cannot hold is {UNUSABLE}: the rule matches nothing.
+    #
+    # PostgreSQL, which raises instead of guessing, keeps two habits of its own
+    # (ValueCasters::POSTGRESQL): it reads date and time text in notations of
+    # its own, and compares a `real` column in single precision.
+    #
+    # Only the built-in operators are typed, each by the shape of its value
+    # ({SHAPES}). A custom operator's value is returned as it came, and a
+    # column nothing is known about leaves the value to the database. A rule
+    # whose field_name is not a name (RuleColumn#malformed?) has no column to
+    # compare with: its value is UNUSABLE whatever the operator.
+    module ValueTyping
+      UNUSABLE = ValueCasters::UNUSABLE
+      CURRENT_USER = 'current_user'
+
+      # The shape of each built-in operator's value. The null checks take none.
+      SHAPES = {
+        Constants::EQUAL => :single, Constants::NOT_EQUAL => :single,
+        Constants::LESS_THAN => :single, Constants::GREATER_THAN => :single,
+        Constants::LESS_THAN_OR_EQUAL => :single, Constants::GREATER_THAN_OR_EQUAL => :single,
+        Constants::IN => :list, Constants::NOT_IN => :list, Constants::BETWEEN => :pair,
+        Constants::CONTAINS => :pattern, Constants::NOT_CONTAINS => :pattern,
+        Constants::STARTS_WITH => :pattern, Constants::ENDS_WITH => :pattern
+      }.freeze
+      # The shapes read from the rule's text as a whole, comma by comma.
+      SEVERAL = %i[list pair].freeze
+
+      module_function
+
+      # @param operator [String] the rule's operator
+      # @param value [Object] the rule's value — the user's id where
+      #   `current_user` stood for it (see {.current_user?})
+      # @param target [RuleColumn] the column it is compared with
+      # @return [Object] what the operator's strategy binds: one value, an Array
+      #   for `in` / `not_in` / `between`, or {UNUSABLE}
+      def call(operator, value, target)
+        return UNUSABLE if target.malformed?
+
+        shape = SHAPES[operator]
+        shape ? send(shape, value, target) : value
+      end
+
+      # `current_user` stands for the user's id wherever one value is compared.
+      # In a list it is an element like any other.
+      def current_user?(operator, value)
+        value == CURRENT_USER && SEVERAL.exclude?(SHAPES[operator])
+      end
+
+      # The caster for the column's type; an enum label is first replaced by
+      # the value the model stores for it.
+      #
+      # @return [#call]
+      def caster(target)
+        typed = target.caster
+        labels = target.enum
+        return typed unless labels
+
+        ->(value) { typed.call(labels.fetch(value.is_a?(String) ? value.strip : value, value)) }
+      end
+
+      def single(value, target)
+        caster(target).call(value)
+      end
+
+      # A LIKE pattern is built from the text of the value, whatever the column.
+      def pattern(value, _target)
+        ValueCasters::TEXT.call(value)
+      end
+
+      # Every element has to be a value of the column; a list of none is no list.
+      def list(value, target)
+        elements = split(value)
+        elements.empty? ? UNUSABLE : all_typed(elements, caster(target))
+      end
+
+      # Exactly two bounds, each a value of the column — or read together, by
+      # the casters that do so (ValueCasters::BOUNDS).
+      def pair(value, target)
+        bounds = split(value)
+        return UNUSABLE unless bounds.size == 2
+
+        typed = caster(target)
+        together = ValueCasters::BOUNDS[typed]
+        together ? together.call(bounds) : all_typed(bounds, typed)
+      end
+
+      def split(value)
+        value.to_s.split(',').map(&:strip)
+      end
+
+      def all_typed(elements, caster)
+        typed = elements.map { |element| caster.call(element) }
+        typed.include?(UNUSABLE) ? UNUSABLE : typed
+      end
+
+      private_class_method :caster, :single, :pattern, :list, :pair, :split, :all_typed
+    end
+  end
+end

data/lib/permission_forge/query_scoping_warnings.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  # Boot warnings for the three query-scoping levels (called by BootChecks).
+  #
+  # @api private
+  module QueryScopingWarnings
+    module_function
+
+    # Level 2 in :raise mode is a dev/test/CI guard; raising in production
+    # turns a missed call site into an outage. Allowed, but never silently.
+    def warn_unscoped_detection_raise_in_production(pf_config)
+      return unless pf_config.unscoped_query_detection == :raise
+      return unless pf_config.unscoped_query_detection_environments.include?('production')
+
+      Rails.logger&.warn '[PermissionForge] WARNING: unscoped_query_detection = :raise is enabled ' \
+                         'for production. A single unscoped query will raise UnscopedQueryError ' \
+                         'in live traffic — prefer :log in production and :raise in test/CI.'
+    end
+
+    # Level 1 applies filter-type rules only; join-type rules still require
+    # permission_scoped. Surface that gap when both are in play.
+    def warn_join_rules_not_auto_scoped(pf_config)
+      return unless pf_config.auto_query_scoping_enabled?
+
+      join_rules = PermissionForge::PermissionSetRule.join_type_rules
+      return unless join_rules.exists?
+
+      Rails.logger&.warn '[PermissionForge] SECURITY warning: auto_query_scoping is enabled but ' \
+                         "#{join_rules.count} join-type rule(s) exist. Join rules are NOT applied " \
+                         'by auto-scoping — queries relying on them must go through ' \
+                         'Model.permission_scoped.'
+    rescue ActiveRecord::StatementInvalid
+      # Tables don't exist yet (pre-migration)
+    end
+
+    # Level 3 needs Postgres; on any other adapter the session variable and
+    # policies simply don't exist, so enabling it is a silent no-op — warn.
+    # On Postgres, compare live policy digests against the current rule state
+    # so edited rules can't silently diverge from the installed policies.
+    def warn_rls_misconfiguration(pf_config)
+      return unless pf_config.database_row_level_security
+
+      unless PermissionForge::RLS.postgres?
+        Rails.logger&.warn '[PermissionForge] WARNING: database_row_level_security is enabled but ' \
+                           'the database adapter is not PostgreSQL. RLS policies cannot be enforced — ' \
+                           'row-level security falls back to application-level scoping only.'
+        return
+      end
+
+      warn_rls_policy_drift
+    rescue ActiveRecord::NoDatabaseError, ActiveRecord::ConnectionNotEstablished
+      # Pre-boot: adapter unknown
+    end
+
+    def warn_rls_policy_drift
+      stale = PermissionForge::RLS.drift_report.reject { |report| report[:in_sync] }
+      return if stale.empty?
+
+      Rails.logger&.warn '[PermissionForge] SECURITY warning: RLS policies are missing or stale for ' \
+                         "table(s): #{stale.map { |report| report[:table] }.join(', ')}. " \
+                         'Rule rows have changed since the last policy sync (or policies were never ' \
+                         'installed) — run `rake permission_forge:rls:sync`.'
+    rescue ActiveRecord::StatementInvalid
+      # Tables don't exist yet (pre-migration)
+    end
+  end
+end

data/lib/permission_forge/rake_audit.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  # What every rake task of the gem does about the audit log: names who ran it
+  # (ACTOR=, stored as actor_label with actor_type 'system' and source 'rake'),
+  # records `report.generated` for the read-only ones, and logs through
+  # Rails.logger. The tasks' own output is untouched.
+  #
+  #   PermissionForge::RakeAudit.changing('permission_forge:erasure') { ... }   # warns without ACTOR
+  #   PermissionForge::RakeAudit.reporting('permission_forge:audit', counts: ->(r) { r.counts }) { report }
+  #
+  # @api private
+  module RakeAudit
+    class << self
+      # A task that changes data. Without ACTOR the label is "rake <task>" and
+      # a warning is printed.
+      def changing(task, env: ENV, warn_io: $stderr, &)
+        warn_io.puts(missing_actor_warning(task)) if env['ACTOR'].blank? && warn_io
+        run(task, env, &)
+      end
+
+      # A read-only task: runs the block (it returns the task's result), records
+      # `report.generated` (task name, counts of that result) and returns the
+      # result — before the task prints or exits.
+      def reporting(task, counts:, env: ENV)
+        run(task, env) do
+          result = yield
+          record_report(task, counts.call(result))
+          result
+        end
+      end
+
+      def label(task, env = ENV)
+        env['ACTOR'].presence || "rake #{task}"
+      end
+
+      # One line in the application log.
+      def log(task, message)
+        Rails.logger&.info("[permission_forge] #{task}: #{message}")
+      end
+
+      private
+
+      # A report must never fail because its own event cannot be written: the
+      # failure is reported (Rails.error, the log) and the task goes on.
+      def record_report(task, counts)
+        PermissionForge::Audit.record('report.generated', data: { 'task' => task, 'counts' => counts.as_json })
+      rescue StandardError => e
+        PermissionForge::Audit::Failure.handle(e, strategy: :report, operation: :store, event: 'report.generated', task: task)
+      end
+
+      def run(task, env, &)
+        actor = label(task, env)
+        log(task, "run by #{actor}")
+        PermissionForge::Audit::Context.with(
+          actor: PermissionForge::Audit::Actor.system(actor), source: 'rake', reason: env['REASON'].presence, &
+        )
+      end
+
+      def missing_actor_warning(task)
+        "WARNING: ACTOR is not set; recorded as \"rake #{task}\". Usage: rake #{task} ACTOR=\"your name or ticket\""
+      end
+    end
+  end
+end

data/lib/permission_forge/resource_chain.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  # The Resource names a model class answers to: its own, and those of its
+  # single-table-inheritance ancestors up to base_class — nearest first.
+  # `VipCustomer < Customer` gives [:VipCustomer, :Customer]; a plain model
+  # its own name alone.
+  #
+  # Every entry the user has along the chain counts, and a subclass can only
+  # be narrower than its base: the rules of every entry apply together; a
+  # view_all / modify_all bypass skips the rules of the entry that grants it
+  # and no other; a field is as closed as the strictest entry that configures
+  # it, and an entry that does not grant read hides every field the chain
+  # configures. A subclass with no entry of its own is its base. (A class
+  # used to answer to its own name only, so a subclass of a protected model
+  # had no rules at all and every field of it was unconfigured, before
+  # 0.14.) A subclass with a table of its own is not
+  # STI and answers to its own name alone.
+  #
+  # The one resolver for every path: find_by / permission_scoped
+  # (PermissionScopedFindable), the auto scope (AutoPermissionScoping), the
+  # attribute guard (MaskedAttributes, AttributeAccessGuard), the response
+  # filter (FiltersResponseAttributes) and PermitsAttributes.
+  #
+  # @api private
+  module ResourceChain
+    # The entry of a field hidden by an unreadable entry along the chain.
+    HIDDEN_ENTRY = { read_access: false, edit_access: false, mask_access: false, mask_strategy: 'full' }.freeze
+
+    module_function
+
+    # @param klass [Class] a model class (any class answers to its own name)
+    # @return [Array<Symbol>] frozen; worked out once per class
+    def names(klass)
+      klass.instance_variable_get(:@pf_resource_chain) ||
+        klass.instance_variable_set(:@pf_resource_chain, compute_names(klass))
+    end
+
+    # The names behind a resource name: the chain of the model it names, or
+    # the name alone when it names no model.
+    #
+    # @param resource_name [String, Symbol]
+    # @return [Array<Symbol>]
+    def names_for(resource_name)
+      klass = resource_name.to_s.safe_constantize
+      klass.is_a?(Class) && klass.respond_to?(:base_class) ? names(klass) : [resource_name.to_sym]
+    end
+
+    # The user's resource entries along the chain, nearest first.
+    #
+    # @param user [#permissions_hash]
+    # @param names [Array<Symbol>]
+    # @return [Array<Hash>]
+    def entries(user, names)
+      resources = user.permissions_hash.dig(:permissions, :resources)
+      return [] unless resources
+
+      names.filter_map do |name|
+        entry = resources[name]
+        entry if entry.present?
+      end
+    end
+
+    # The row-level rules that apply to a class, and why none do.
+    #
+    # @return [Array(Array<Hash>, Symbol)] the rules of every entry without a
+    #   bypass, and — when that leaves none — the nearest entry's :view_all /
+    #   :modify_all, else :no_rules
+    def rules(user, names)
+      rules = []
+      bypass = nil
+      entries(user, names).each do |entry|
+        reason = bypass_reason(entry[:permissions])
+        if reason
+          bypass ||= reason
+        else
+          rules.concat(entry[:permission_set_rules] || [])
+        end
+      end
+      [rules, (bypass || :no_rules if rules.empty?)]
+    end
+
+    # Whether the entry the class answers to grants a resource flag: the
+    # nearest entry along the chain — the class's own, or its base's when it
+    # has none of its own (the same entry can_*? reads for a class with one;
+    # a muted base reaches it, see PermissionHashBuilder's muting phase).
+    # False without an entry.
+    #
+    # @param flag [Symbol] :read_access, :delete_access, …
+    # @return [Boolean]
+    def grants?(user, names, flag)
+      entries(user, names).first&.dig(:permissions, flag) == true
+    end
+
+    # @return [Symbol, nil] :view_all or :modify_all when one of them lets
+    #   the user past the rules of an entry
+    def bypass_reason(permissions)
+      return unless permissions
+
+      if permissions[:view_all] then :view_all
+      elsif permissions[:modify_all] then :modify_all
+      end
+    end
+
+    # The field entry a class answers with for one attribute: the one entry
+    # along the chain that configures it — one entry is read as a plain
+    # model's, its rows decide — or, among several, the strictest; hidden
+    # when one of them does not grant read; nil when none configures it (or
+    # the user has no field_permissions).
+    #
+    # @param names [Array<Symbol>, Symbol] the chain, or one name
+    # @return [Hash, nil]
+    def field_permissions(user, names, attribute)
+      return unless user.respond_to?(:field_permissions)
+      return user.field_permissions(names, attribute) unless names.is_a?(Array)
+      return user.field_permissions(names.first, attribute) if names.size == 1
+      return strictest(names.filter_map { |name| user.field_permissions(name, attribute) }) unless user.respond_to?(:permissions_hash)
+
+      compose_field(entries(user, names), attribute.to_sym)
+    end
+
+    # One entry: its field entry (its rows decide). Several: hidden when one
+    # does not grant read, else the strictest of those that configure the
+    # field; nil when none does.
+    def compose_field(resource_entries, attribute)
+      field_entries = resource_entries.filter_map { |entry| entry.dig(:fields, attribute) }
+      return field_entries.first if resource_entries.size <= 1 || field_entries.empty?
+
+      unreadable?(resource_entries) ? HIDDEN_ENTRY.dup : strictest(field_entries)
+    end
+
+    # The field entries a class answers with, every configured name composed
+    # the same way. The one table itself when one entry has fields: read-only.
+    #
+    # @return [Hash{Symbol => Hash}]
+    def fields(user, names)
+      resource_entries = entries(user, names)
+      tables = resource_entries.filter_map { |entry| entry[:fields].presence }
+      return tables.first || {} if resource_entries.size <= 1
+
+      compose_tables(tables, unreadable?(resource_entries))
+    end
+
+    def compose_tables(tables, hidden)
+      tables.flat_map(&:keys).uniq.to_h do |name|
+        [name, hidden ? HIDDEN_ENTRY.dup : strictest(tables.filter_map { |table| table[name] })]
+      end
+    end
+
+    # Whether one of several entries does not grant read: a class cannot be
+    # more readable than an entry it answers to (a muted base read reaches
+    # the fields only the subclass configures).
+    def unreadable?(resource_entries)
+      resource_entries.any? { |entry| entry.dig(:permissions, :read_access) != true }
+    end
+
+    # Of several entries for one field: readable and editable only when every
+    # one grants it, masked when any does, with the first masking entry's
+    # strategy (in chain order). One entry: itself.
+    def strictest(field_entries)
+      return field_entries.first if field_entries.size <= 1
+
+      masked = field_entries.find { |entry| entry[:mask_access] }
+      { read_access: field_entries.all? { |entry| entry[:read_access] == true },
+        edit_access: field_entries.all? { |entry| entry[:edit_access] == true },
+        mask_access: !masked.nil?,
+        mask_strategy: (masked || field_entries.first)[:mask_strategy] }
+    end
+
+    # The class and its superclasses up to base_class that share its table
+    # (single-table inheritance: Rails' base_class ignores table_name, and a
+    # subclass with a table of its own holds other rows); the names they
+    # have. A nameless class (an anonymous subclass) answers as its ancestors
+    # do; a subclass renamed after its base answers once.
+    def compute_names(klass)
+      classes = [klass]
+      if klass.respond_to?(:base_class)
+        base = klass.base_class
+        classes << classes.last.superclass while classes.last != base && same_table?(classes.last.superclass, klass)
+      end
+      classes.filter_map(&:name).map(&:to_sym).uniq.freeze
+    end
+    private_class_method :compute_names
+
+    def same_table?(ancestor, klass)
+      ancestor.respond_to?(:table_name) && ancestor.table_name == klass.table_name
+    end
+    private_class_method :same_table?
+  end
+end