permission_forge 0.14.1

data/lib/permission_forge/configuration/presets.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  class Configuration
+    # `config.preset`: a named set of values for the options that decide
+    # whether something fails open, applied as a layer of defaults under
+    # the settings the host makes itself.
+    #
+    #   :compat (default) — the library defaults, as every version had them
+    #   :strict           — every fail-open default of the README's
+    #                       "Production hardening checklist" closed, and the
+    #                       settings that are already closed kept so
+    #
+    # A setting made explicitly always wins, before or after `preset =`, in
+    # the same configure block or a later one: the preset only fills the
+    # options nobody set. A String is taken as its Symbol; anything else
+    # raises ConfigurationError. SecurityAudit reports the preset and, under
+    # :strict, every option set looser than the preset.
+    #
+    # The options that need host code to close (an authenticated
+    # base_controller_class, admin_assignment_authorization,
+    # audit_log_authorization, a request_context_resolver, user_active_check)
+    # are not in a preset. Nor is masked_attributes_nil_user_strategy
+    # (OPT_IN): :hide makes jobs and mailers that read masked models with no
+    # user see hidden values, a cost each app must choose; it stays :bypass
+    # under every preset.
+    #
+    # @api public
+    module Presets
+      # The library defaults of every option a preset decides: what
+      # Configuration.new starts with (a test pins the two together).
+      COMPAT = {
+        # fail open by default (the checklist)
+        nil_user_strategy: :bypass,
+        response_filter_nil_user_strategy: :bypass,
+        auto_query_scoping: :off,
+        unconfigured_action_strategy: :allow,
+        action_guard_nil_user_strategy: nil,
+        conditional_sets_strict_mode: false,
+        mask_virtual_attributes: false,
+        extra_fields_default_access: :grant,
+        cache_backend: :memory,
+        # closed by default
+        api_require_authorization: true,
+        admin_tenantless_access: :deny,
+        nested_attributes_parent_fallback: false,
+        unconfigured_field_strategy: :block
+      }.freeze
+
+      STRICT = COMPAT.merge(
+        nil_user_strategy: :deny,
+        response_filter_nil_user_strategy: :block,
+        auto_query_scoping: :filter_only,
+        unconfigured_action_strategy: :block,
+        action_guard_nil_user_strategy: :deny,
+        conditional_sets_strict_mode: true,
+        mask_virtual_attributes: :auto,
+        extra_fields_default_access: :unconfigured,
+        cache_backend: :rails_cache
+      ).freeze
+
+      PRESETS = { compat: COMPAT, strict: STRICT }.freeze
+
+      # Fail-open defaults of the hardening checklist that no preset closes:
+      # an explicit choice with a documented cost.
+      OPT_IN = %i[masked_attributes_nil_user_strategy].freeze
+      OPTIONS = COMPAT.keys.freeze
+
+      # When an option counts as closed with a value other than the :strict
+      # one: receives (value, configuration).
+      ALSO_CLOSED = {
+        nil_user_strategy: ->(value, _config) { value == :raise },
+        # nil follows nil_user_strategy
+        action_guard_nil_user_strategy: ->(_value, config) { !config.action_guard_nil_user_bypass? },
+        mask_virtual_attributes: ->(value, _config) { [true, 'auto'].include?(value) },
+        # no cache at all, or a shared store the host built
+        cache_backend: ->(value, _config) { value == :null || value.is_a?(ActiveSupport::Cache::Store) }
+      }.freeze
+
+      # Each writer of an option a preset decides marks the option as set by
+      # the host (after the value passed validation).
+      OPTIONS.each do |option|
+        define_method(:"#{option}=") do |value|
+          super(value)
+          @explicit_options << option
+        end
+      end
+
+      # @return [Symbol] :compat or :strict
+      attr_reader :preset
+
+      # @raise [PermissionForge::ConfigurationError] for anything but :strict
+      #   or :compat (or its String)
+      def preset=(value)
+        name = StrategyValues.as_symbol(value)
+        unless PRESETS.key?(name)
+          raise PermissionForge::ConfigurationError,
+                "preset must be one of #{PRESETS.keys.map(&:inspect).join(', ')} (or its String); got #{value.inspect}"
+        end
+
+        backend = @cache_backend
+        @preset = name
+        PRESETS.fetch(name).each do |option, preset_value|
+          instance_variable_set(:"@#{option}", preset_value) unless @explicit_options.include?(option)
+        end
+        # A store built from the old backend (preset set outside configure,
+        # which rebuilds it anyway) is rebuilt.
+        reset_cache_store! if @cache_store && !backend.equal?(@cache_backend)
+      end
+
+      # @param option [Symbol]
+      # @return [Boolean] whether the host set the option itself (not the preset)
+      def explicitly_set?(option)
+        @explicit_options.include?(option.to_sym)
+      end
+
+      # The options whose value is looser than the :strict preset's — under
+      # :strict, the ones the host overrode.
+      #
+      # @return [Hash{Symbol => Object}] option => current value
+      def options_looser_than_strict
+        STRICT.each_with_object({}) do |(option, strict_value), looser|
+          value = public_send(option)
+          value = value.to_sym if value.is_a?(String) # 'block' is :block, as the strategy writers take it
+          next if value == strict_value || ALSO_CLOSED[option]&.call(value, self)
+
+          looser[option] = value
+        end
+      end
+
+      private
+
+      def set_preset_defaults
+        @preset = :compat
+        @explicit_options = Set.new
+      end
+    end
+  end
+end

data/lib/permission_forge/configuration/query_scoping_settings.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  class Configuration
+    # Query-scoping configuration (the three defense levels) extracted for SRP.
+    #
+    # Level 1 — ENFORCE:  auto_query_scoping applies filter-type row rules to
+    #                     every relation built on a protected model.
+    # Level 2 — DETECT:   unscoped_query_detection reports queries on protected
+    #                     tables that bypassed a permission-scoped path.
+    # Level 3 — DATABASE: database_row_level_security enables Postgres RLS
+    #                     session-variable plumbing (policies via the
+    #                     permission_forge:rls generator + rls:sync rake task).
+    #
+    # All options default OFF — behavior is unchanged unless a level is enabled.
+    #
+    # @api public
+    module QueryScopingSettings
+      AUTO_QUERY_SCOPING_VALUES = %i[off filter_only].freeze
+      UNSCOPED_QUERY_DETECTION_VALUES = %i[off log raise].freeze
+
+      # Level 1 — ENFORCE.
+      #   :off         — (default) only find_by/find_by!/permission_scoped apply rules
+      #   :filter_only — a default_scope applies the current user's FILTER-type rules
+      #                  to every relation (where/all/find/first/count/pluck and
+      #                  association traversal). Join-type rules are NOT auto-applied
+      #                  and still require permission_scoped (a boot warning fires
+      #                  when join rules exist while this is enabled).
+      # Notes: view_all/modify_all bypasses auto-scoping (parity with find_by);
+      # nil current_user follows nil_user_strategy (:bypass -> unscoped,
+      # :deny/:raise -> none — fail closed, never raising from inside a scope);
+      # denied rows are silently filtered (find -> RecordNotFound).
+      # Unknown values raise ConfigurationError at assignment (see below).
+      attr_reader :auto_query_scoping
+
+      # Level 2 — DETECT.
+      #   :off   — (default) no detection
+      #   :log   — Rails.logger.warn for each unscoped query on a protected table
+      #   :raise — raise PermissionForge::UnscopedQueryError instead (CI guard)
+      # Detection only activates in environments listed in
+      # unscoped_query_detection_environments. Queries carrying the pf_scoped
+      # annotation (permission_scoped, auto-scoping, gem internals) are never
+      # flagged; INSERTs and schema queries are ignored.
+      attr_reader :unscoped_query_detection
+
+      # Environments (strings) where unscoped_query_detection is active.
+      # Default: %w[development test]. Adding 'production' is allowed but a
+      # boot warning fires when :raise is configured for production.
+      attr_accessor :unscoped_query_detection_environments
+
+      # Level 3 — DATABASE (Postgres only). When true, PermissionForge::RLS
+      # helpers set/clear the session variable used by generated policies.
+      # Policies themselves are installed via `rails generate permission_forge:rls`
+      # and kept in sync with `rake permission_forge:rls:sync`.
+      attr_accessor :database_row_level_security
+
+      # Postgres session variable (set via SET LOCAL) that generated policies
+      # read through current_setting(..., true). Must contain a dot (Postgres
+      # requires namespaced custom settings).
+      attr_accessor :rls_session_variable
+
+      def auto_query_scoping=(value)
+        @auto_query_scoping = normalize_scoping_value(
+          value, AUTO_QUERY_SCOPING_VALUES, 'auto_query_scoping'
+        )
+      end
+
+      def unscoped_query_detection=(value)
+        @unscoped_query_detection = normalize_scoping_value(
+          value, UNSCOPED_QUERY_DETECTION_VALUES, 'unscoped_query_detection'
+        )
+      end
+
+      def auto_query_scoping_enabled?
+        @auto_query_scoping == :filter_only
+      end
+
+      def unscoped_query_detection_active?
+        return false if @unscoped_query_detection == :off
+        return false unless defined?(Rails) && Rails.respond_to?(:env)
+
+        @unscoped_query_detection_environments.include?(Rails.env.to_s)
+      end
+
+      private
+
+      def set_query_scoping_defaults
+        @auto_query_scoping = :off
+        @unscoped_query_detection = :off
+        @unscoped_query_detection_environments = %w[development test]
+        @database_row_level_security = false
+        @rls_session_variable = 'permission_forge.user_id'
+      end
+
+      # Fail closed on typos: an unknown value must never silently enable a
+      # weaker mode than the dev intended, so we raise at assignment time
+      # (initializer) rather than guessing at query time.
+      def normalize_scoping_value(value, allowed, option)
+        sym = value.to_sym
+        return sym if allowed.include?(sym)
+
+        raise PermissionForge::ConfigurationError,
+              "Invalid #{option}: #{value.inspect}. Allowed: #{allowed.map(&:inspect).join(', ')}"
+      end
+    end
+  end
+end

data/lib/permission_forge/configuration/strategy_values.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  class Configuration
+    # The strategy options that decide whether something is allowed. Each
+    # writer takes a Symbol from its list, or that Symbol's String
+    # ('block' is :block), and raises ConfigurationError for anything else,
+    # at assignment time (the initializer). Before, a String was compared
+    # with a Symbol and read as an unknown value: for some options that
+    # failed open ('block' for response_filter_nil_user_strategy was
+    # :bypass). Prepended, so it wraps the plain writers declared in
+    # Configuration and its sub-settings.
+    #
+    # @api private
+    module StrategyValues
+      ALLOWED = {
+        nil_user_strategy: %i[bypass raise deny],
+        response_filter_nil_user_strategy: %i[bypass block],
+        masked_write_protection: %i[skip raise off],
+        masked_attributes_nil_user_strategy: %i[bypass hide],
+        action_guard_nil_user_strategy: %i[bypass deny raise],
+        admin_tenantless_access: %i[deny allow],
+        unconfigured_action_strategy: %i[allow block],
+        extra_fields_default_access: %i[grant unconfigured]
+      }.freeze
+
+      # nil or blank means "follow nil_user_strategy".
+      BLANK_ALLOWED = %i[action_guard_nil_user_strategy].freeze
+
+      ALLOWED.each_key do |option|
+        define_method(:"#{option}=") do |value|
+          super(StrategyValues.strategy(option, value))
+        end
+      end
+
+      # @return [Symbol, nil]
+      # @raise [PermissionForge::ConfigurationError] for a value not in ALLOWED[option]
+      def self.strategy(option, value)
+        blank_allowed = BLANK_ALLOWED.include?(option)
+        return nil if blank_allowed && value.to_s.strip.empty?
+
+        allowed = ALLOWED.fetch(option)
+        symbol = as_symbol(value)
+        return symbol if allowed.include?(symbol)
+
+        raise PermissionForge::ConfigurationError,
+              "#{option} must be one of #{allowed.map(&:inspect).join(', ')} (or its String)" \
+              "#{' or nil' if blank_allowed}; got #{value.inspect}"
+      end
+
+      # A Symbol as is, a String as its Symbol, anything else nil.
+      def self.as_symbol(value)
+        value.to_s.to_sym if value.is_a?(String) || value.is_a?(Symbol)
+      end
+    end
+  end
+end

data/lib/permission_forge/configuration/virtual_attributes_settings.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  class Configuration
+    # Options for virtual (non-column) fields: names a model declares through
+    # `extra_fields_method`, plus names the admin can discover.
+    #
+    # @api public
+    module VirtualAttributesSettings
+      EXTRA_FIELDS_DEFAULT_ACCESS = %i[grant unconfigured].freeze
+
+      # What a declared virtual field gets when no ResourceField row configures it:
+      #
+      #   :grant        — readable and editable, unmasked (default, backward-compatible)
+      #   :unconfigured — no implicit entry; the field follows unconfigured_field_strategy
+      #                   until an admin gives it a level (fail closed with :block)
+      #
+      # A String is taken as its Symbol; any other value raises
+      # ConfigurationError (StrategyValues).
+      attr_accessor :extra_fields_default_access
+
+      # When true, the admin also lists attribute-API attributes and
+      # store_accessor keys as virtual fields. Discovered names never get
+      # implicit access — they stay unconfigured until an admin sets a level.
+      # Default: false.
+      attr_accessor :virtual_field_discovery
+
+      # Model-level masking of virtual readers (methods, store accessors,
+      # attribute-API attributes), on top of the column masking MaskedAttributes
+      # already does. Off by default: the model's own callbacks and validations
+      # then see the masked value too (see pf_without_virtual_masking).
+      #
+      #   false / nil            — off; virtual fields are enforced only by
+      #                            PermitsAttributes and FiltersResponseAttributes (default)
+      #   :auto / true           — every model that has MaskedAttributes
+      #   ['Customer', 'Order']  — only these models
+      attr_accessor :mask_virtual_attributes
+
+      # Sets this group's defaults; called from Configuration#initialize.
+      # @return [void]
+      # @api private
+      def set_virtual_attributes_defaults
+        @extra_fields_default_access = :grant
+        @virtual_field_discovery = false
+        @mask_virtual_attributes = false
+      end
+
+      # @return [Boolean] whether declared virtual fields get the implicit
+      #   read + edit entry. Only the exact :grant value grants.
+      def grant_extra_fields_by_default?
+        extra_fields_default_access.to_s == 'grant'
+      end
+
+      # @param model_name [String, Symbol, Class]
+      # @return [Boolean] whether virtual readers of this model are masked.
+      def mask_virtual_attributes_for?(model_name)
+        setting = mask_virtual_attributes
+        return false if [false, nil].include?(setting)
+        return setting.map(&:to_s).include?(model_name.to_s) if setting.is_a?(Array)
+
+        [true, :auto, 'auto'].include?(setting)
+      end
+    end
+  end
+end