permission_forge 0.14.1 → 0.15.0

data/lib/permission_forge/concerns/records_audit_events.rb

@@ -150,9 +150,17 @@ module PermissionForge
       end
 
       # saved_changes minus the bookkeeping columns, JSON-ready.
-      def audit_changes
-        saved_changes.except(*BOOKKEEPING_COLUMNS).as_json
-      end
+      def audit_changes = saved_changes.except(*BOOKKEEPING_COLUMNS).as_json
+
+      # Whether the last save wrote a change event: SaveNotice asks it.
+      def saved_audited_changes? = audit_changes.any?
+
+      # Whether saving now would write one (a new record always does): the
+      # admin saves a record only then (SaveNotice#pf_save_changed), so an
+      # unchanged submit runs no commit callback and invalidates nobody's
+      # cached permissions. Never asked by a callback: a second, unchanged
+      # save in a transaction must not drop the first one's invalidation.
+      def audited_changes_pending? = new_record? || changes_to_save.except(*BOOKKEEPING_COLUMNS).any?
 
       # The Permission Set an event about this record belongs to, if any.
       def audit_permission_set
@@ -226,10 +234,9 @@ module PermissionForge
       end
 
       def record_audit_event_for_update
-        changes = audit_changes
-        return if changes.empty?
+        return unless saved_audited_changes?
 
-        record_audit_event(:update, audit_update_details.merge('changes' => changes))
+        record_audit_event(:update, audit_update_details.merge('changes' => audit_changes))
       end
 
       # Event data a model adds to its update events (the computed 'changes' wins).

data/lib/permission_forge/concerns/requires_name.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Concerns
+    # The one definition of "this record needs a name": a Permission Set, a
+    # group, a rule, a Resource, a field row and an action row. A name that
+    # is nil, empty or only whitespace is refused with
+    # `permission_forge.validations.name_blank` — in code, through the JSON
+    # API and in the admin alike.
+    #
+    # Checked for a new row and on a rename only: a row stored with a blank
+    # name before (written past the model, or before 0.15 for a rule) stays
+    # editable in its other attributes; the admin shows such a name as
+    # "Untitled …" in the page's language (Admin::RecordName).
+    #
+    # Field test round 8 found a rule saved with name "" or "   " while sets
+    # and groups refused it: each model declared the rule itself, and the rule
+    # model never had it.
+    #
+    # @api private
+    module RequiresName
+      extend ActiveSupport::Concern
+
+      included do
+        validates :name, presence: { message: ->(*) { I18n.t('permission_forge.validations.name_blank') } },
+                         if: :name_check_due?
+      end
+
+      private
+
+      # A new row, or a change to its name.
+      def name_check_due?
+        new_record? || will_save_change_to_name?
+      end
+    end
+  end
+end

data/lib/permission_forge/concerns/validates_column_lengths.rb

@@ -24,6 +24,7 @@ module PermissionForge
       }.freeze
 
       included do
+        before_validation :refuse_nul_bytes
         validate :validate_column_lengths
       end
 
@@ -38,6 +39,29 @@ module PermissionForge
 
       private
 
+      # A NUL byte in a string or text attribute being written: PostgreSQL
+      # cannot store one (its driver raises on any statement carrying it, a
+      # uniqueness check's included) and SQLite reads the statement cut
+      # short. Refused before the other validators run — they may query
+      # with the value — so a save is a validation error, never a raise. A
+      # value a copy keeps from its original (KeepsCopiedValues) is the
+      # original's, as stored.
+      def refuse_nul_bytes
+        names = self.class.columns.filter_map do |column|
+          name = column.name
+          name if MEASURES.key?(column.type) && will_save_change_to_attribute?(name) && nul_byte?(name)
+        end
+        return if names.empty?
+
+        names.each { |name| errors.add(name, :nul_byte, message: ->(*) { I18n.t('permission_forge.validations.nul_byte') }) }
+        throw :abort
+      end
+
+      def nul_byte?(name)
+        value = read_attribute(name)
+        value.is_a?(String) && value.include?("\0") && !(respond_to?(:copied_unchanged?, true) && copied_unchanged?(name))
+      end
+
       def validate_column_lengths
         self.class.columns.each do |column|
           name = column.name

data/lib/permission_forge/concerns/validates_dependency.rb

@@ -14,7 +14,7 @@ module PermissionForge
     #
     #   resource = Resource.new(edit_access: true, read_access: false)
     #   resource.valid? # => false
-    #   resource.errors[:edit_access] # => ["requires read_access to be enabled"]
+    #   resource.errors[:edit_access] # => ["requires Read to be enabled"]
     #
     # @api private
     module ValidatesDependency
@@ -44,7 +44,10 @@ module PermissionForge
           define_method(method_name) do
             return if belongs_to_muting_permission_set?
 
-            errors.add(field, "requires #{requires} to be enabled") if send(field) && !send(requires)
+            return unless send(field) && !send(requires)
+
+            label = I18n.t("permission_forge.validations.attributes.#{requires}", default: requires.to_s)
+            errors.add(field, :requires, message: I18n.t('permission_forge.validations.requires', requires: label))
           end
           private method_name
         end

data/lib/permission_forge/concerns/validates_required_columns.rb

@@ -0,0 +1,74 @@
+module PermissionForge
+  module Concerns
+    # Refuses nil for every column the schema declares NOT NULL as a
+    # validation error keyed by the attribute, so a JSON `null` or a blank
+    # form value (a boolean column casts "" to nil) is a 422 in the API and
+    # the form again in the admin, where the database raised NotNullViolation
+    # (a 500). Read from the schema: a NOT NULL column added later is covered
+    # without a change here.
+    #
+    # Left to whoever fills them: the primary key; on a new record the
+    # columns Rails or the gem fill when the row is created (the timestamps,
+    # `uuid` from HasUuid); a column that already has an error once every
+    # other validation ran — a presence rule's, with or without a condition
+    # — or whose required `belongs_to` names it as the foreign key (one
+    # message, not two). The check runs after every other validation of the
+    # model whatever the order they were declared in: an `:after` callback
+    # of the `validate` chain (canary `:validate_after_callback`).
+    #
+    # @api private
+    module ValidatesRequiredColumns
+      extend ActiveSupport::Concern
+
+      # Filled by the gem when a row is created (HasUuid, before_create).
+      FILLED_ON_CREATE = %w[uuid].freeze
+      # Filled by Rails when a row is created while record_timestamps is on.
+      TIMESTAMPS = %w[created_at created_on updated_at updated_on].freeze
+
+      included do
+        # After every `validate` / `validates` of the model, also those
+        # declared below the include or in a subclass.
+        set_callback :validate, :after, :validate_required_columns
+      end
+
+      # Whether `association` is a required belongs_to: Rails' own presence
+      # rule (message :required), whose condition holds whenever the
+      # foreign key is nil.
+      def self.required_association?(klass, association)
+        klass.validators_on(association).any? { |validator| validator.kind == :presence && validator.options[:message] == :required }
+      end
+
+      private
+
+      def validate_required_columns
+        self.class.columns.each do |column|
+          name = column.name
+          next if column.null || !has_attribute?(name) || !read_attribute(name).nil? || filled_elsewhere?(name)
+
+          errors.add(name, :blank, message: ->(*) { I18n.t('permission_forge.validations.blank') })
+        end
+      end
+
+      # Said already (an error on the attribute), or filled or checked by someone else.
+      def filled_elsewhere?(name)
+        klass = self.class
+        return true if errors.include?(name) || name == klass.primary_key
+        return true if new_record? && filled_on_create?(name)
+
+        required_foreign_key?(name)
+      end
+
+      def filled_on_create?(name)
+        FILLED_ON_CREATE.include?(name) || (self.class.record_timestamps && TIMESTAMPS.include?(name))
+      end
+
+      # The foreign key of a required belongs_to: its error is keyed by the association.
+      def required_foreign_key?(name)
+        klass = self.class
+        klass.reflect_on_all_associations(:belongs_to).any? do |reflection|
+          reflection.foreign_key.to_s == name && ValidatesRequiredColumns.required_association?(klass, reflection.name)
+        end
+      end
+    end
+  end
+end

data/lib/permission_forge/conditional_sets.rb

@@ -58,7 +58,8 @@ module PermissionForge
   #   - a context with an IP or session flags: those whose conditions pass
   #     (Services::PermissionSetConditionEvaluator), granting and muting alike;
   #   - no context at all — the resolver returned nothing (no resolver, as
-  #     shipped): every conditional set, as before;
+  #     shipped): every conditional set, as before, but a granting set whose
+  #     condition nobody can judge (ActivationConditions#never_grants?), which never applies;
   #   - under config.conditional_sets_strict_mode, no request context — the
   #     resolver returned nothing, or neither an IP nor session flags (a job,
   #     the console; the time alone is not a request context): only the
@@ -104,6 +105,8 @@ module PermissionForge
     #
     # @api private
     Member = Data.define(:id, :muting, :requires_session_flag, :allowed_ips, :allowed_hours_start, :allowed_hours_end) do
+      include PermissionForge::ActivationConditions
+
       def self.of(permission_set)
         new(id: permission_set.id, muting: permission_set.is_muting == true,
             requires_session_flag: permission_set.requires_session_flag, allowed_ips: permission_set.allowed_ips,
@@ -121,13 +124,17 @@ module PermissionForge
 
       def muting? = muting
 
-      # Whether the set counts in `context`: its conditions pass — or, in
-      # strict mode, it is a muting set whose condition cannot be judged
-      # there (no IP for an IP allowlist, no flags at all for a session flag).
+      # Whether the set counts in `context`: its conditions pass — or it is
+      # a muting set whose condition cannot be judged: one nobody can judge
+      # (ActivationConditions#conditions_broken?: an IP entry that is not an
+      # address, one hour of the two, the same hour twice) in every mode, or
+      # one the context cannot answer (no IP for an IP allowlist, no flags
+      # at all for a session flag) in strict mode. A lockdown that never
+      # locked is the defect; a granting set never passes on such a condition.
       def applies?(context, strict)
         evaluator = Services::PermissionSetConditionEvaluator
         evaluator.call(permission_set: self, context: context) ||
-          (strict && muting && evaluator.unjudgeable?(permission_set: self, context: context))
+          (muting && (conditions_broken? || (strict && evaluator.unjudgeable?(permission_set: self, context: context))))
       end
     end
 
@@ -353,7 +360,7 @@ module PermissionForge
       klass = self.class
       strict = klass.strict?
       return sets.select(&:muting?) if strict && klass.no_context?(context)
-      return sets if context.blank?
+      return sets.reject(&:never_grants?) if context.blank?
 
       sets.select { |member| member.applies?(context, strict) }
     end

data/lib/permission_forge/configuration/admin_ui_settings.rb

@@ -6,6 +6,10 @@ module PermissionForge
     #
     # @api public
     module AdminUiSettings
+      # The default of admin_stale_assignment_days, and the threshold used
+      # wherever that setting is nil (the one definition of the fallback).
+      DEFAULT_STALE_ASSIGNMENT_DAYS = 90
+
       # Lambda returning the model classes offered in "Add a resource".
       # nil (default) eager-loads app/models and lists every concrete
       # ActiveRecord model with a table, excluding PermissionForge's own.
@@ -19,7 +23,9 @@ module PermissionForge
       attr_accessor :admin_session_flags
 
       # Assignments not reviewed for this many days appear under
-      # "Stale assignments" on the admin home page. Default: 90.
+      # "Stale assignments" on the admin home page; also the default threshold
+      # of StaleAssignmentAuditor and rake permission_forge:stale_assignments. Default: 90
+      # (DEFAULT_STALE_ASSIGNMENT_DAYS, also used when it is set to nil).
       attr_accessor :admin_stale_assignment_days
 
       # Name of the host app shown under the logo (e.g. "Acme CRM").
@@ -53,17 +59,24 @@ module PermissionForge
       # or in middleware.
       attr_accessor :admin_tenantless_access
 
+      # Whether an API-only application (`config.api_only = true`) that
+      # mounts the engine is warned that the admin screens need the cookies,
+      # session and flash middlewares (default true). false for an app that
+      # uses only the JSON API and never opens the admin screens.
+      attr_accessor :api_only_admin_warning
+
       # Sets this group's defaults; called from Configuration#initialize.
       # @return [void]
       # @api private
       def set_admin_ui_defaults
         @admin_model_resolver = nil
         @admin_session_flags = {}
-        @admin_stale_assignment_days = 90
+        @admin_stale_assignment_days = DEFAULT_STALE_ASSIGNMENT_DAYS
         @admin_app_name = nil
         @admin_back_url = nil
         @admin_docs_url = 'https://github.com/fetijashari/permission_forge/blob/main/docs/configuration.md'
         @admin_tenantless_access = :deny
+        @api_only_admin_warning = true
       end
 
       # @return [Boolean] whether an admin or admin API request may run with
@@ -86,7 +99,8 @@ module PermissionForge
         names.select { |_, name| name.to_s.delete_prefix('::') == 'ActionController::Base' }.keys
       end
 
-      # The boot warning for default_admin_controllers_under_tenancy, or nil.
+      # The boot warning for default_admin_controllers_under_tenancy, or nil:
+      # the bare text (Warnings.emit puts the prefix and the severity on).
       #
       # @return [String, nil]
       def tenantless_admin_warning
@@ -99,7 +113,7 @@ module PermissionForge
                       else
                         'Every admin request with no tenant is refused (admin_tenantless_access :deny).'
                       end
-        '[PermissionForge] SECURITY warning: tenant_model is set but ActionController::Base, which sets no ' \
+        'tenant_model is set but ActionController::Base, which sets no ' \
           "tenant, is still the base of #{names.join(' and ')}. #{consequence} Point each at a controller " \
           'that sets the current tenant (or set the tenant in middleware).'
       end

data/lib/permission_forge/configuration/audit_settings.rb

@@ -38,7 +38,8 @@ module PermissionForge
       # user, an Audit::Actor, or a Hash { type:, id:, label: }. nil (default)
       # falls back to current_user_resolver; under HTTP Basic auth the
       # supplied username is recorded with actor_type 'basic_auth'.
-      #   config.audit_actor_resolver = ->(controller) { controller.current_admin }
+      #   # Rails 8's authentication generator, under HTTP Basic (its sign-in does not run there):
+      #   config.audit_actor_resolver = ->(controller) { Session.find_by(id: controller.request.cookie_jar.signed[:session_id])&.user }
       attr_accessor :audit_actor_resolver
 
       # Lambda(controller) returning the request context stored with each

data/lib/permission_forge/configuration/controller_action_settings.rb

@@ -36,9 +36,10 @@ module PermissionForge
 
       # What the guard does with a resource or action no Permission Set manages:
       #
-      #   :allow — let it through (default — nothing is restricted until an admin
-      #            adds the action to a Permission Set)
-      #   :block — deny until a Permission Set permits it
+      #   :block — deny until a Permission Set permits it (default since 0.15)
+      #   :allow — let it through: nothing is restricted until an admin adds the
+      #            action to a Permission Set (the default before 0.15; an
+      #            explicit opt-out that fails open, reported by SecurityAudit)
       #
       # A String is taken as its Symbol; any other value raises
       # ConfigurationError (StrategyValues).
@@ -69,7 +70,7 @@ module PermissionForge
         @controller_action_discovery = false
         @controller_action_resolver = nil
         @controller_discovery_exclude = DEFAULT_CONTROLLER_DISCOVERY_EXCLUDE.dup
-        @unconfigured_action_strategy = :allow
+        @unconfigured_action_strategy = :block
         @action_guard_bypass = nil
         @action_guard_nil_user_strategy = nil
       end

data/lib/permission_forge/configuration/masked_attributes_settings.rb

@@ -6,6 +6,10 @@ module PermissionForge
     #
     # @api public
     module MaskedAttributesSettings
+      # The masked_attributes_nil_user_strategy values that hide inside web
+      # requests.
+      HIDING_NIL_USER_STRATEGIES = %i[hide_in_requests hide].freeze
+
       # Value returned by MaskedAttributes when read_access is denied. Default: nil.
       attr_accessor :hidden_attribute_value
 
@@ -36,36 +40,86 @@ module PermissionForge
       attr_accessor :masked_write_protection
 
       # What the attribute guard does when there is no current user (a job, a
-      # mailer, the console, a resolver that returns nil). Nothing else
-      # governs masking without a user: nil_user_strategy is about rows,
-      # response_filter_nil_user_strategy about FiltersResponseAttributes.
+      # mailer, the console, a public page, a resolver that returns nil).
+      # Nothing else governs masking without a user: nil_user_strategy is
+      # about rows, response_filter_nil_user_strategy about
+      # FiltersResponseAttributes.
+      #
+      #   :bypass           — every getter returns the stored value (the
+      #                       library default). Inside a web request each
+      #                       guarded attribute so returned is recorded:
+      #                       field.unmasked_without_user (runtime group
+      #                       :bypass, once per request per model and
+      #                       attribute) and one SECURITY warning per model
+      #                       and process in the log.
+      #   :hide_in_requests — inside a web request (PermissionForge::WebRequest:
+      #                       a public page, a webhook, a controller that
+      #                       forgot authentication, the before_actions and
+      #                       middlewares that run before sign-in) every
+      #                       guarded attribute is hidden as under :hide;
+      #                       everywhere else (jobs, rake, runner, the
+      #                       console) as :bypass. What the generated
+      #                       initializer and config.preset = :strict set.
+      #   :hide             — every guarded attribute reads as
+      #                       hidden_attribute_value everywhere: getters,
+      #                       read_attribute, `[]`, attributes, as_json and
+      #                       the wrapped virtual readers and store accessors.
+      #                       Code that reads masked models with no user then
+      #                       sees hidden values: set the current user in
+      #                       those jobs and mailers.
       #
-      #   :bypass — every getter returns the stored value (default)
-      #   :hide   — every guarded attribute reads as hidden_attribute_value:
-      #             getters, read_attribute, `[]`, attributes, as_json and
-      #             the wrapped virtual readers and store accessors. The
-      #             primary key and the raw paths (read_attribute_before_type_cast,
-      #             pluck) are untouched, as for a signed-in user. Code that
-      #             reads masked models with no user then sees hidden values:
-      #             set the current user in those jobs and mailers. The user
-      #             model (user_class and its subclasses) is exempt: sign-in
-      #             reads it before anyone is signed in (encrypted_password,
-      #             confirmation_token, lockable counters).
+      # Where it hides, the primary key and the raw paths
+      # (read_attribute_before_type_cast, pluck) are untouched, as for a
+      # signed-in user, and the user model (user_class and its subclasses) is
+      # exempt: sign-in reads it before anyone is signed in
+      # (encrypted_password, confirmation_token, lockable counters).
       attr_accessor :masked_attributes_nil_user_strategy
 
-      # @return [Boolean] whether the strategy is :hide (whatever the model)
+      # @return [Boolean] whether the strategy is :hide: hidden everywhere
+      #   (whatever the model; ask #hide_masked_attributes_without_user_for?
+      #   for a record)
       def hide_masked_attributes_without_user?
-        @masked_attributes_nil_user_strategy.to_s == 'hide'
+        @masked_attributes_nil_user_strategy == :hide
+      end
+
+      # @return [Boolean] whether the strategy hides guarded attributes at
+      #   least inside web requests (:hide_in_requests or :hide)
+      def hide_masked_attributes_without_user_in_requests?
+        HIDING_NIL_USER_STRATEGIES.include?(@masked_attributes_nil_user_strategy)
       end
 
       # The one decision of whether a record of klass hides its guarded
-      # attributes when nobody is signed in: under :hide, every model but the
-      # user model.
+      # attributes when nobody is signed in: under :hide, and under
+      # :hide_in_requests inside a web request, every model but the user
+      # model.
       #
       # @param klass [Class]
       # @return [Boolean]
       def hide_masked_attributes_without_user_for?(klass)
-        hide_masked_attributes_without_user? && !user_model_class?(klass)
+        masked_attributes_without_user_for(klass) == :hide
+      end
+
+      # What the attribute guard does with a read of klass when nobody is
+      # signed in, the one definition behind #hide_masked_attributes_without_user_for?:
+      #
+      #   :hide   — hidden (:hide; :hide_in_requests inside a web request)
+      #   :record — returned as stored and recorded (:bypass inside a web
+      #             request: field.unmasked_without_user), the reads
+      #             :hide_in_requests would hide
+      #   :bypass — returned as stored (outside a web request, and always
+      #             for the user model)
+      #
+      # Asked on every guarded read with no user: outside a web request
+      # under :bypass or :hide_in_requests it reads one execution-state slot.
+      #
+      # @param klass [Class]
+      # @return [Symbol] :hide, :record or :bypass
+      def masked_attributes_without_user_for(klass)
+        strategy = @masked_attributes_nil_user_strategy
+        return :bypass unless strategy == :hide || PermissionForge::WebRequest.active?
+        return :bypass if user_model_class?(klass)
+
+        strategy == :bypass ? :record : :hide
       end
 
       # Sets this group's defaults; called from Configuration#initialize.

data/lib/permission_forge/configuration/presets.rb

@@ -6,7 +6,8 @@ module PermissionForge
     # 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
+    #   :compat (default) — the library defaults (Configuration.new; since 0.15
+    #                       unconfigured_action_strategy is :block there too)
     #   :strict           — every fail-open default of the README's
     #                       "Production hardening checklist" closed, and the
     #                       settings that are already closed kept so
@@ -20,10 +21,10 @@ module PermissionForge
     # 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.
+    # are not in a preset. :strict sets masked_attributes_nil_user_strategy
+    # to :hide_in_requests (hidden inside web requests with nobody signed in,
+    # stored values for jobs, rake and the console); :hide, which hides in
+    # jobs and mailers too, counts as closed but stays each app's choice.
     #
     # @api public
     module Presets
@@ -34,36 +35,42 @@ module PermissionForge
         nil_user_strategy: :bypass,
         response_filter_nil_user_strategy: :bypass,
         auto_query_scoping: :off,
-        unconfigured_action_strategy: :allow,
+        no_read_access_strategy: :rules_only,
         action_guard_nil_user_strategy: nil,
         conditional_sets_strict_mode: false,
         mask_virtual_attributes: false,
         extra_fields_default_access: :grant,
         cache_backend: :memory,
+        masked_attributes_nil_user_strategy: :bypass,
         # closed by default
         api_require_authorization: true,
         admin_tenantless_access: :deny,
         nested_attributes_parent_fallback: false,
-        unconfigured_field_strategy: :block
+        unconfigured_field_strategy: :block,
+        # closed by default since 0.15 (:allow is the explicit opt-out)
+        unconfigured_action_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,
+        no_read_access_strategy: :deny,
         action_guard_nil_user_strategy: :deny,
         conditional_sets_strict_mode: true,
         mask_virtual_attributes: :auto,
         extra_fields_default_access: :unconfigured,
-        cache_backend: :rails_cache
+        cache_backend: :rails_cache,
+        masked_attributes_nil_user_strategy: :hide_in_requests
       ).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
+      # an explicit choice with a documented cost. None at present
+      # (masked_attributes_nil_user_strategy left it in 0.15: :strict sets
+      # :hide_in_requests).
+      OPT_IN = [].freeze
       OPTIONS = COMPAT.keys.freeze
 
       # When an option counts as closed with a value other than the :strict
@@ -73,6 +80,8 @@ module PermissionForge
         # 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) },
+        # hidden everywhere, jobs and the console included
+        masked_attributes_nil_user_strategy: ->(value, _config) { value == :hide },
         # no cache at all, or a shared store the host built
         cache_backend: ->(value, _config) { value == :null || value.is_a?(ActiveSupport::Cache::Store) }
       }.freeze

data/lib/permission_forge/configuration/query_scoping_settings.rb

@@ -18,6 +18,19 @@ module PermissionForge
     module QueryScopingSettings
       AUTO_QUERY_SCOPING_VALUES = %i[off filter_only].freeze
       UNSCOPED_QUERY_DETECTION_VALUES = %i[off log raise].freeze
+      # Columns a record rule never compares (PermissionForge::SecretColumns),
+      # by name: password digests, tokens, `encrypted_*` columns (a gem's own
+      # encryption, attr_encrypted), secrets, then the credentials a
+      # user table commonly has — passwords and their salts, API / private /
+      # access keys, one-time-password seeds — anchored to name segments so
+      # `owner_id`, `sort_key`, `secretary` or `crypto_wallet` are never caught.
+      # An attribute declared with Active Record's `encrypts` keeps its column
+      # name: it is found by its declaration, not by a pattern
+      # (Operators::RuleProblem :encrypted_column).
+      DEFAULT_RULE_SECRET_COLUMN_PATTERNS = [
+        /\Apassword_digest\z/, /_digest\z/, /token/, /\Aencrypted_/, /_secret/, /passw/, /\Asecret(?:_|\z)/,
+        /(?:\A|_)(?:api|private|secret|access)_key\z/, /(?:\A|_)crypted(?:_|\z)/, /(?:\A|_)salt\z/, /(?:\A|_)otp(?:_|\z)/
+      ].freeze
 
       # Level 1 — ENFORCE.
       #   :off         — (default) only find_by/find_by!/permission_scoped apply rules
@@ -33,6 +46,20 @@ module PermissionForge
       # Unknown values raise ConfigurationError at assignment (see below).
       attr_reader :auto_query_scoping
 
+      # What the record reads (find_by / find_by! / permission_scoped, and the
+      # default scope under auto_query_scoping) do for a signed-in user whose
+      # entry for the model's Resource chain does not grant read_access (no
+      # entry at all included):
+      #   :rules_only — (default) apply the rules of the user's entries, if
+      #                 any: no rules, every row (can_read? is the check)
+      #   :deny       — no rows: permission_scoped and the default scope are
+      #                 empty, find_by / find_by! raise NotAuthorizedError for
+      #                 an existing record (nil / RecordNotFound for a missing
+      #                 one). The strict preset's value.
+      # With nobody signed in nil_user_strategy decides. One definition:
+      # PermissionForge::RecordReadAccess.
+      attr_accessor :no_read_access_strategy
+
       # Level 2 — DETECT.
       #   :off   — (default) no detection
       #   :log   — Rails.logger.warn for each unscoped query on a protected table
@@ -59,6 +86,25 @@ module PermissionForge
       # requires namespaced custom settings).
       attr_accessor :rls_session_variable
 
+      # The column names a record rule may not compare (PermissionForge::
+      # SecretColumns, matched against the column name in lower case): a new
+      # rule on one, or a change of a rule's column or path to one, is
+      # refused, and the admin's rule builder does not offer them. Rules
+      # stored before keep evaluating; the audit and Home list them. `[]`
+      # opts out.
+      attr_reader :rule_secret_column_patterns
+
+      # @param patterns [Array<Regexp>]
+      # @raise [ConfigurationError] for anything that is not a list of regular expressions
+      def rule_secret_column_patterns=(patterns)
+        unless patterns.is_a?(Array) && patterns.all?(Regexp)
+          raise PermissionForge::ConfigurationError,
+                "Invalid rule_secret_column_patterns: #{patterns.inspect}. Give a list of regular expressions ([] opts out)."
+        end
+
+        @rule_secret_column_patterns = patterns
+      end
+
       def auto_query_scoping=(value)
         @auto_query_scoping = normalize_scoping_value(
           value, AUTO_QUERY_SCOPING_VALUES, 'auto_query_scoping'
@@ -75,6 +121,13 @@ module PermissionForge
         @auto_query_scoping == :filter_only
       end
 
+      # @return [Boolean] whether the record reads of a signed-in user need
+      #   read_access on the model's Resource chain. Only the exact
+      #   :rules_only value applies the rules alone.
+      def deny_record_reads_without_read_access?
+        no_read_access_strategy.to_s != 'rules_only'
+      end
+
       def unscoped_query_detection_active?
         return false if @unscoped_query_detection == :off
         return false unless defined?(Rails) && Rails.respond_to?(:env)
@@ -86,10 +139,12 @@ module PermissionForge
 
       def set_query_scoping_defaults
         @auto_query_scoping = :off
+        @no_read_access_strategy = :rules_only
         @unscoped_query_detection = :off
         @unscoped_query_detection_environments = %w[development test]
         @database_row_level_security = false
         @rls_session_variable = 'permission_forge.user_id'
+        @rule_secret_column_patterns = DEFAULT_RULE_SECRET_COLUMN_PATTERNS.dup
       end
 
       # Fail closed on typos: an unknown value must never silently enable a