permission_forge 0.14.1

data/lib/permission_forge/configuration/admin_ui_settings.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  class Configuration
+    # Options that only affect the built-in admin UI (never permission checks).
+    #
+    # @api public
+    module AdminUiSettings
+      # 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.
+      #   config.admin_model_resolver = -> { [Customer, Invoice, Deal] }
+      attr_accessor :admin_model_resolver
+
+      # Friendly labels for the session flags offered on the Conditions tab.
+      # Keys are the flag names your request_context_resolver puts in
+      # :session_flags. Flags already used by a Permission Set are always shown.
+      #   config.admin_session_flags = { 'mfa_verified' => 'Signed in with two-factor' }
+      attr_accessor :admin_session_flags
+
+      # Assignments not reviewed for this many days appear under
+      # "Stale assignments" on the admin home page. Default: 90.
+      attr_accessor :admin_stale_assignment_days
+
+      # Name of the host app shown under the logo (e.g. "Acme CRM").
+      # nil (default) derives it from the Rails application class.
+      attr_accessor :admin_app_name
+
+      # Where the "Back to <app>" link under the logo points. A String, or a
+      # lambda receiving the view context (e.g. ->(view) { view.main_app.dashboard_path }).
+      # nil (default) uses the host app's root route, or "/".
+      attr_accessor :admin_back_url
+
+      # Base URL for "Configuration docs" links on the Settings page. The
+      # setting key is appended as an anchor.
+      attr_accessor :admin_docs_url
+
+      # What the admin screens and the admin JSON API do with a request that
+      # has no current tenant while tenancy is on (tenant_model):
+      #
+      #   :deny  — refuse it with a 403, recorded as admin.auth_failed /
+      #            api.auth_failed, reason tenant_missing (default). With no
+      #            tenant acts_as_tenant scopes nothing, so the request would
+      #            read and change every tenant's permissions.
+      #   :allow — serve it: it reads, edits and deletes existing records of
+      #            every tenant. Creating a record still needs a tenant (the
+      #            new row's tenant is required): with none, a create is
+      #            refused as invalid ("must exist"), never stored tenant-less.
+      #
+      # A String is taken as its Symbol; any other value raises
+      # ConfigurationError (StrategyValues). Set the tenant in the controllers
+      # the engine inherits from (base_controller_class, api_base_controller_class)
+      # or in middleware.
+      attr_accessor :admin_tenantless_access
+
+      # 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_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
+      end
+
+      # @return [Boolean] whether an admin or admin API request may run with
+      #   no current tenant. Only the exact :allow value allows.
+      def admin_tenantless_access_allowed?
+        admin_tenantless_access.to_s == 'allow'
+      end
+
+      # The admin base-controller settings still at the default
+      # ::ActionController::Base while tenancy is on: nothing the engine
+      # inherits from sets the tenant there (the API's only counts when the
+      # API is enabled).
+      #
+      # @return [Array<Symbol>] e.g. [:base_controller_class]
+      def default_admin_controllers_under_tenancy
+        return [] unless tenant_enabled?
+
+        names = { base_controller_class: base_controller_class }
+        names[:api_base_controller_class] = api_base_controller_class if api_enabled
+        names.select { |_, name| name.to_s.delete_prefix('::') == 'ActionController::Base' }.keys
+      end
+
+      # The boot warning for default_admin_controllers_under_tenancy, or nil.
+      #
+      # @return [String, nil]
+      def tenantless_admin_warning
+        names = default_admin_controllers_under_tenancy
+        return if names.empty?
+
+        consequence = if admin_tenantless_access_allowed?
+                        'admin_tenantless_access is :allow, so a request with no tenant reads and changes the ' \
+                          'existing records of every tenant.'
+                      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, 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
+    end
+  end
+end

data/lib/permission_forge/configuration/audit_settings.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  class Configuration
+    # Options for the audit event log ({PermissionForge::Audit}): what is
+    # recorded, who is recorded as the actor, what happens when a record
+    # cannot be written, and how long events are kept.
+    #
+    # The older options stay as they are: `audit_trail_enabled` and
+    # `audit_user_class` (created_by / updated_by on the live row),
+    # `on_rule_bypass` and `on_field_filtered` (callbacks).
+    #
+    # @api public
+    module AuditSettings
+      AUDIT_EVENTS = [:auto, true, false].freeze
+      CHANGE_FAILURE_STRATEGIES = %i[raise report log].freeze
+      HOOK_FAILURE_STRATEGIES = %i[report log raise].freeze
+
+      # The groups of runtime (access) events that can be stored, as named in
+      # the event catalogue (Audit::EventCatalog):
+      #   denied          — access.denied, action.denied
+      #   bypass          — rule.bypassed, query.unscoped
+      #   field_read      — field.access
+      #   params_filtered — params.filtered, write.masked_skipped
+      #   cache           — permissions.rebuilt, permissions.invalidated
+      RUNTIME_GROUPS = %i[denied bypass field_read params_filtered cache].freeze
+
+      # Whether audit events are stored in the audit_events table.
+      #   :auto  (default) when the table exists; when it does not, a boot
+      #          warning is logged, the security audit reports it, and changes
+      #          still work — an upgrade is never broken by an unrun migration
+      #   true   always (a missing table then fails every change under the
+      #          default :raise strategy)
+      #   false  never (events are still published as notifications)
+      attr_reader :audit_events
+
+      # Lambda(controller) returning who acts in an admin UI or API request: a
+      # 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 }
+      attr_accessor :audit_actor_resolver
+
+      # Lambda(controller) returning the request context stored with each
+      # event: a Hash with :request_id and :ip. nil (default) records the
+      # request id and the remote IP.
+      attr_accessor :audit_request_context
+
+      # What happens when a change event cannot be written (the table is
+      # unreachable, say) — change events are written inside the transaction
+      # of the change:
+      #   :raise  (default) the change rolls back: no change without its record
+      #   :report the change goes through; the error is logged and handed to
+      #           Rails.error (handled)
+      #   :log    the change goes through; the error is logged only
+      attr_reader :audit_change_failure_strategy
+
+      # What happens when a notification subscriber, a legacy hook, or the
+      # store of a runtime event fails: :report (default), :log or :raise.
+      attr_reader :audit_hook_failure_strategy
+
+      # Which runtime event groups are stored (every runtime event is published
+      # regardless). Default: %i[denied]. See RUNTIME_GROUPS.
+      attr_reader :audit_runtime_events
+
+      # When true, every audit event is also written to Rails.logger.
+      attr_reader :audit_log_subscriber
+
+      # How long events are kept: a duration (90.days), seconds, or nil
+      # (default) to keep them forever. Only the purge service deletes events,
+      # and only ones older than this.
+      attr_reader :audit_retention_period
+
+      # Lambda(controller) returning whether the request may read the audit
+      # log (pages, exports, the API endpoint). nil (default): anyone with
+      # admin access.
+      attr_accessor :audit_log_authorization
+
+      # Lambda(controller, target, user_ids, action) returning whether the
+      # request may change who holds a Permission Set or belongs to a group:
+      # target is the PermissionSet or PermissionSetGroup, user_ids the people
+      # concerned (cast to the user key type), action one of :grant, :revoke,
+      # :change_expiry, :review, :add_member, :remove_member. Asked by the HTML
+      # admin and by the API assignment endpoints (after
+      # api_assignment_authorization). A refusal changes nothing. nil
+      # (default): no extra check. See PermissionForge::AssignmentAuthorization.
+      attr_accessor :admin_assignment_authorization
+
+      # Sets this group's defaults; called from Configuration#initialize.
+      # @return [void]
+      # @api private
+      def set_audit_defaults
+        @audit_events = :auto
+        @audit_actor_resolver = nil
+        @audit_request_context = nil
+        @audit_change_failure_strategy = :raise
+        @audit_hook_failure_strategy = :report
+        @audit_runtime_events = %i[denied].freeze
+        @audit_log_subscriber = false
+        @audit_retention_period = nil
+        @audit_log_authorization = nil
+        @admin_assignment_authorization = nil
+        # a new configuration may become PermissionForge.configuration
+        audit_observation_changed!
+      end
+
+      # @raise [PermissionForge::ConfigurationError] for anything but :auto,
+      #   true or false (a string from ENV would otherwise pass for :auto)
+      def audit_events=(value)
+        @audit_events = one_of!(:audit_events, value, AUDIT_EVENTS)
+      end
+
+      def audit_change_failure_strategy=(value)
+        @audit_change_failure_strategy = one_of!(:audit_change_failure_strategy, value, CHANGE_FAILURE_STRATEGIES)
+      end
+
+      def audit_hook_failure_strategy=(value)
+        @audit_hook_failure_strategy = one_of!(:audit_hook_failure_strategy, value, HOOK_FAILURE_STRATEGIES)
+      end
+
+      # Symbols or strings; nil means none.
+      def audit_runtime_events=(value)
+        groups = Array(value).map { |group| group.to_s.to_sym }
+        unknown = groups - RUNTIME_GROUPS
+        unless unknown.empty?
+          raise PermissionForge::ConfigurationError,
+                "audit_runtime_events: unknown group(s) #{unknown.map(&:inspect).join(', ')} " \
+                "(known: #{RUNTIME_GROUPS.map(&:inspect).join(', ')})"
+        end
+
+        # frozen: a group pushed in place would pass Audit::Gate by
+        @audit_runtime_events = groups.uniq.freeze
+        audit_observation_changed!
+      end
+
+      def audit_log_subscriber=(value)
+        @audit_log_subscriber = value
+        audit_observation_changed!
+      end
+
+      # @param group [Symbol, nil] a runtime group of the catalogue
+      # @return [Boolean] whether runtime events of that group are stored
+      def store_runtime_group?(group)
+        !group.nil? && audit_runtime_events.include?(group.to_sym)
+      end
+
+      # The one definition of a valid retention period (the setter and
+      # Services::AuditEventPurger both ask it).
+      #
+      # @param value [ActiveSupport::Duration, Numeric, nil]
+      # @return [ActiveSupport::Duration, nil] a Duration stays as given (calendar
+      #   arithmetic), a number is seconds
+      # @raise [PermissionForge::ConfigurationError] for anything else
+      def self.retention_period(value)
+        return if value.nil?
+
+        period = value.is_a?(ActiveSupport::Duration) || !value.is_a?(Numeric) ? value : value.seconds
+        return period if period.is_a?(ActiveSupport::Duration) && period.to_i.positive?
+
+        raise PermissionForge::ConfigurationError,
+              "audit_retention_period must be a positive duration (90.days), a number of seconds or nil (got #{value.inspect})"
+      end
+
+      def audit_retention_period=(value)
+        AuditSettings.retention_period(value)
+        @audit_retention_period = value
+      end
+
+      private
+
+      # Audit::Gate keeps whether a runtime event is stored or heard.
+      def audit_observation_changed!
+        PermissionForge::Audit::Gate.changed! if defined?(PermissionForge::Audit::Gate)
+      end
+
+      def one_of!(option, value, allowed)
+        return value if allowed.include?(value)
+
+        raise PermissionForge::ConfigurationError,
+              "#{option} must be one of #{allowed.map(&:inspect).join(', ')} (got #{value.inspect})"
+      end
+    end
+  end
+end

data/lib/permission_forge/configuration/cache_settings.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  class Configuration
+    # Options for what happens when the cache store fails
+    # ({PermissionForge::Cache::Failure}) and for what is cached from inside a
+    # database transaction ({PermissionForge::OpenTransaction}).
+    #
+    # @api public
+    module CacheSettings
+      # Optional callback when the cache store fails an invalidation: a stamp
+      # or a removal it did not confirm after the retries, an entry that could
+      # not be removed, or an error inside an after_commit invalidation. The
+      # process that failed makes the invalidation when the store answers
+      # again (Cache::Backlog); until then, and in other processes, a cached
+      # permission hash may be out of date until cache_ttl.
+      #
+      # Nothing is raised (a raising after_commit makes Rails skip the
+      # callbacks of the remaining records); the failure is logged at error
+      # level, published as the `cache_failure.permission_forge` notification,
+      # and handed to this hook. Receives (operation:, user_id:, keys:,
+      # error:, **details). Errors raised by the hook are logged and swallowed.
+      #
+      #   config.on_cache_failure = ->(operation:, user_id:, **) {
+      #     Sentry.capture_message("permission cache: #{operation} failed for user #{user_id}")
+      #   }
+      attr_accessor :on_cache_failure
+
+      # Whether a database transaction is treated as reading from a snapshot —
+      # the rows as they were when it began, whatever others have committed
+      # since (REPEATABLE READ or stronger). A permission hash built inside
+      # such a transaction can be older than an invalidation that has already
+      # finished, so it is not cached: the request uses it, and
+      # `regenerate_permissions` / `invalidate_permissions` called there take
+      # effect in the cache once the transaction has committed.
+      #
+      #   :auto  (default) decided from what Rails knows, without asking the
+      #          server: yes on MySQL (its default isolation) and SQLite; on
+      #          PostgreSQL only inside a transaction opened with
+      #          `isolation: :repeatable_read` or `:serializable`. Any other
+      #          adapter counts as a snapshot.
+      #   true   every transaction — for a PostgreSQL whose default isolation
+      #          was raised for the database or the role
+      #          (`default_transaction_isolation`).
+      #   false  none — for a MySQL run at READ COMMITTED. Inside a
+      #          transaction everything is then cached and invalidated as it
+      #          is outside one.
+      #
+      # Where transactions read from a snapshot, permissions first read
+      # inside a transaction are built once per transaction and not cached:
+      # read them once before a loop of saves.
+      attr_reader :snapshot_transactions
+
+      SNAPSHOT_TRANSACTIONS = [:auto, true, false].freeze
+
+      # @raise [PermissionForge::ConfigurationError] for anything else (a
+      #   string from ENV, say), which would otherwise pass for :auto
+      def snapshot_transactions=(value)
+        unless SNAPSHOT_TRANSACTIONS.include?(value)
+          raise PermissionForge::ConfigurationError,
+                "snapshot_transactions must be :auto, true or false (got #{value.inspect})"
+        end
+
+        @snapshot_transactions = value
+      end
+
+      # Sets this group's defaults; called from Configuration#initialize.
+      # @return [void]
+      # @api private
+      def set_cache_failure_defaults
+        @on_cache_failure = nil
+        @snapshot_transactions = :auto
+      end
+    end
+  end
+end

data/lib/permission_forge/configuration/controller_action_settings.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  class Configuration
+    # Options for controller actions: discovery in the admin and the runtime
+    # guard ({PermissionForge::Concerns::ControllerActionGuard}).
+    #
+    # @api public
+    module ControllerActionSettings
+      # Rails' own controllers never show up in discovery or get guarded.
+      DEFAULT_CONTROLLER_DISCOVERY_EXCLUDE = [
+        %r{\A(rails|active_storage|action_mailbox|action_cable|action_text|turbo)(/|\z)}
+      ].freeze
+
+      # When true, a Resource's Actions tab lists the host app's controller
+      # actions that map to that resource. Default: false.
+      attr_accessor :controller_action_discovery
+
+      # Maps a controller action to a Resource and an action key. Receives
+      # (controller_path, action_name) — e.g. ('customers/merges', 'create').
+      #
+      #   ['Customer', 'merge'] — this Resource, this action key
+      #   false                 — never managed (not listed, not guarded)
+      #   nil                   — use the convention (controller name → model)
+      #
+      #   config.controller_action_resolver = lambda do |controller_path, action_name|
+      #     ['Customer', 'merge'] if controller_path == 'customers/merges' && action_name == 'create'
+      #   end
+      attr_accessor :controller_action_resolver
+
+      # Controllers left out of discovery and the guard: Regexps, or Strings
+      # naming a controller or a namespace ('webhooks' leaves out `webhooks`
+      # and `webhooks/*`, not `webhooks_admin`). Blank entries are ignored.
+      # PermissionForge's own controllers are always excluded.
+      attr_accessor :controller_discovery_exclude
+
+      # 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
+      #
+      # A String is taken as its Symbol; any other value raises
+      # ConfigurationError (StrategyValues).
+      attr_accessor :unconfigured_action_strategy
+
+      # Lambda(user, controller) returning true to skip the guard for this
+      # request (e.g. ->(user, _controller) { user.admin? }). Default: nil.
+      attr_accessor :action_guard_bypass
+
+      # What the guard does with a mapped action when there is no current
+      # user, apart from nil_user_strategy (which keeps governing record
+      # rules and masking):
+      #
+      #   nil     — follow nil_user_strategy (default: no change for existing apps)
+      #   :bypass — let the request through
+      #   :deny   — refuse it (PermissionForge::ActionNotAuthorizedError)
+      #
+      # :raise refuses too; nil or blank follows nil_user_strategy; a String
+      # is taken as its Symbol; any other value raises ConfigurationError
+      # (StrategyValues). New installs get :deny in the
+      # generated initializer.
+      attr_accessor :action_guard_nil_user_strategy
+
+      # Sets this group's defaults; called from Configuration#initialize.
+      # @return [void]
+      # @api private
+      def set_controller_action_defaults
+        @controller_action_discovery = false
+        @controller_action_resolver = nil
+        @controller_discovery_exclude = DEFAULT_CONTROLLER_DISCOVERY_EXCLUDE.dup
+        @unconfigured_action_strategy = :allow
+        @action_guard_bypass = nil
+        @action_guard_nil_user_strategy = nil
+      end
+
+      # @return [Boolean] whether the guard lets a request with no user
+      #   through: action_guard_nil_user_strategy, else nil_user_strategy.
+      #   Only the exact :bypass value lets it through.
+      def action_guard_nil_user_bypass?
+        (action_guard_nil_user_strategy.presence || nil_user_strategy).to_s == 'bypass'
+      end
+
+      # @return [Boolean] whether the admin lists the app's controller actions.
+      def controller_action_discovery?
+        controller_action_discovery == true
+      end
+
+      # @return [Boolean] whether an unmanaged resource or action passes the
+      #   guard. Only the exact :allow value allows.
+      def allow_unconfigured_actions?
+        unconfigured_action_strategy.to_s == 'allow'
+      end
+
+      # @param controller_path [String] e.g. 'api/v1/customers'
+      # @return [Boolean] whether the controller is outside discovery and the guard.
+      def controller_excluded?(controller_path)
+        path = controller_path.to_s
+        return true if path == 'permission_forge' || path.start_with?('permission_forge/')
+
+        Array(controller_discovery_exclude).any? do |pattern|
+          next pattern.match?(path) if pattern.is_a?(Regexp)
+
+          # A blank String (an unset ENV value) must not exclude everything,
+          # and 'custom' must not exclude 'customers'.
+          prefix = pattern.to_s.chomp('/')
+          prefix.present? && (path == prefix || path.start_with?("#{prefix}/"))
+        end
+      end
+    end
+  end
+end

data/lib/permission_forge/configuration/gdpr_settings.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  class Configuration
+    # GDPR-related configuration methods extracted for SRP.
+    #
+    # @api public
+    module GdprSettings
+      # Turns the GDPR masking defaults on or off (an explicit setting wins over a preset).
+      # @param value [Boolean]
+      def gdpr_defaults=(value)
+        @gdpr_defaults_explicitly_set = true
+        @gdpr_defaults = value
+      end
+
+      # Replaces the patterns that mark a field name as personal data.
+      # @param patterns [Array<Regexp>]
+      # @raise [ConfigurationError] for anything that is not a list of regular expressions
+      def gdpr_field_patterns=(patterns)
+        validate_gdpr_patterns!(patterns)
+        @gdpr_field_patterns = patterns
+      end
+
+      def gdpr_defaults_explicitly_set?
+        @gdpr_defaults_explicitly_set
+      end
+
+      # Remembers the digest of the current patterns (it tells a changed list from the default).
+      # @return [String]
+      # @api private
+      def record_gdpr_pattern_checksum
+        @gdpr_pattern_checksum = compute_pattern_checksum
+      end
+
+      def gdpr_patterns_changed_since_generation?
+        return false unless @gdpr_pattern_checksum
+
+        @gdpr_pattern_checksum != compute_pattern_checksum
+      end
+
+      def validate_gdpr_explicit_choice!
+        return unless @gdpr_require_explicit_choice
+        return if gdpr_defaults_explicitly_set?
+
+        raise PermissionForge::ConfigurationError,
+              'gdpr_require_explicit_choice is enabled but gdpr_defaults was not explicitly set. ' \
+              'Please set config.gdpr_defaults = true or config.gdpr_defaults = false in your initializer.'
+      end
+
+      private
+
+      def validate_gdpr_patterns!(patterns)
+        return if patterns.blank?
+
+        patterns.each_key do |key|
+          next if key.is_a?(Regexp)
+
+          Regexp.new(key)
+        rescue RegexpError => e
+          raise PermissionForge::ConfigurationError,
+                "Invalid GDPR field pattern for '#{key}': #{e.message}"
+        end
+      end
+
+      def compute_pattern_checksum
+        Digest::SHA256.hexdigest(@gdpr_field_patterns.to_a.map { |k, v| "#{k.source}:#{v}" }.sort.join('|'))
+      end
+    end
+  end
+end

data/lib/permission_forge/configuration/masked_attributes_settings.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  class Configuration
+    # Configuration for {PermissionForge::Concerns::MaskedAttributes} model-level enforcement.
+    #
+    # @api public
+    module MaskedAttributesSettings
+      # Value returned by MaskedAttributes when read_access is denied. Default: nil.
+      attr_accessor :hidden_attribute_value
+
+      # When true (default), MaskedAttributes omits hidden keys from `attributes` /
+      # `as_json` / `serializable_hash`. When false, keys are present with hidden_attribute_value.
+      attr_accessor :omit_hidden_in_attributes_hash
+
+      # Controls auto-applying MaskedAttributes to host models.
+      #
+      #   :auto / true                       — apply to every model that has a Resource record (default)
+      #   ['Customer', 'Order']              — only apply to these named models
+      #   false / nil                        — no auto-apply; dev includes the concern manually
+      #
+      # Auto-apply runs at engine boot (scanning existing Resource rows) and again
+      # whenever a new Resource is created at runtime. Both paths respect this setting.
+      attr_accessor :auto_apply_masked_attributes
+
+      # Protects against persisting a masked/hidden value back to the database.
+      # MaskedAttributes overrides column getters, so a host callback like
+      # `before_save { self.email = email.strip }` would otherwise read the MASKED
+      # value and write it back, corrupting the stored data. This guard remembers
+      # the exact sentinel handed out for each attribute and, when that same
+      # sentinel is written back, prevents the overwrite.
+      #
+      #   :skip  — silently keep the original stored value (default, safe)
+      #   :raise — raise MaskedAttributes::MaskedWriteError (surfaces the bug)
+      #   :off   — disable the guard (legacy behavior; risks silent corruption)
+      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.
+      #
+      #   :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).
+      attr_accessor :masked_attributes_nil_user_strategy
+
+      # @return [Boolean] whether the strategy is :hide (whatever the model)
+      def hide_masked_attributes_without_user?
+        @masked_attributes_nil_user_strategy.to_s == 'hide'
+      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.
+      #
+      # @param klass [Class]
+      # @return [Boolean]
+      def hide_masked_attributes_without_user_for?(klass)
+        hide_masked_attributes_without_user? && !user_model_class?(klass)
+      end
+
+      # Sets this group's defaults; called from Configuration#initialize.
+      # @return [void]
+      # @api private
+      def set_masked_attributes_defaults
+        @hidden_attribute_value = nil
+        @omit_hidden_in_attributes_hash = true
+        @auto_apply_masked_attributes = :auto
+        @masked_write_protection = :skip
+        @masked_attributes_nil_user_strategy = :bypass
+      end
+    end
+  end
+end

data/lib/permission_forge/configuration/permits_attributes_settings.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  class Configuration
+    # Options for the write path: {PermissionForge::Services::PermitsAttributes},
+    # which filters incoming params by field-level edit access.
+    #
+    # @api public
+    module PermitsAttributesSettings
+      # How PermitsAttributes treats a `<assoc>_attributes` payload when the
+      # user's permission hash has no entry for the association's model:
+      #   false — the payload is dropped (default, fail closed)
+      #   true  — it is filtered against the PARENT resource's fields, as
+      #           versions before 0.14 did (a key editable on the parent then
+      #           admits the same key on a child the user was never granted)
+      attr_accessor :nested_attributes_parent_fallback
+
+      # Sets this group's defaults; called from Configuration#initialize.
+      # @return [void]
+      # @api private
+      def set_permits_attributes_defaults
+        @nested_attributes_parent_fallback = false
+      end
+    end
+  end
+end