permission_forge 0.14.1

data/lib/permission_forge/services/security_audit/personal_data_check.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Services
+    module SecurityAuditChecks
+      # Personal data shown unmasked, from GdprFieldAuditor. Fields an admin
+      # marked "This is intended" in the privacy audit are left out.
+      class PersonalDataCheck < BaseCheck
+        def call
+          report = GdprFieldAuditor.call(configuration: configuration)
+          [unmasked(report), implicit_virtual(report), cross_set(report), unmapped(report)].compact
+        end
+
+        private
+
+        def unmasked(report)
+          rows = report.select { |row| row[:type] == :unmasked_field && acknowledged_ids.exclude?(row[:resource_field_id]) }
+          return if rows.empty?
+
+          finding(:medium, :unmasked_personal_data, 'Personal data readable unmasked',
+                  'These fields look like personal data and are readable without a mask. Mask them, or mark ' \
+                  'them "This is intended" in the admin privacy audit if that access is deliberate.',
+                  items: rows.map do |row|
+                    "#{row[:permission_set]} › #{row[:resource_name]}.#{row[:field_name]} (suggested: #{row[:suggested_strategy]})"
+                  end)
+        end
+
+        # Declared virtual fields left on the implicit grant: readable and
+        # editable, unmasked, without anyone having chosen that. A field whose
+        # only row is switched off is one of them.
+        def implicit_virtual(report)
+          rows = report.select { |row| row[:type] == :implicit_virtual_grant }
+          return if rows.empty?
+
+          finding(:medium, :implicit_virtual_personal_data, 'Personal data in virtual fields granted by default',
+                  'These virtual fields look like personal data and have no active field row, so ' \
+                  'extra_fields_default_access = :grant makes them readable and editable, unmasked. Give them a ' \
+                  'level, or set extra_fields_default_access = :unconfigured so they follow unconfigured_field_strategy.',
+                  items: rows.map do |row|
+                    "#{row[:permission_set]} › #{row[:resource_name]}.#{row[:field_name]} (suggested: #{row[:suggested_strategy]})"
+                  end)
+        end
+
+        def cross_set(report)
+          rows = report.select { |row| row[:type] == :cross_set_unmasking }
+          return if rows.empty?
+
+          finding(:medium, :cross_set_unmasking, 'One set unmasks what another masks',
+                  'Masks combine with AND: anyone holding both sets sees the full value.',
+                  items: rows.map { |row| "#{row[:permission_set]} › #{row[:resource_name]}.#{row[:field_name]}" })
+        end
+
+        def unmapped(report)
+          rows = report.select { |row| row[:type] == :unmapped_column }
+          return if rows.empty?
+
+          passes = %w[pass_through warn].include?(configuration.unconfigured_field_strategy.to_s)
+          detail = if passes
+                     'unconfigured_field_strategy lets them through unfiltered. Add a field row, or switch ' \
+                       'the existing one back on.'
+                   else
+                     'They are blocked from filtered responses until configured; add a field row (or switch ' \
+                       'the existing one back on) to decide.'
+                   end
+          finding(passes ? :high : :low, :unmapped_personal_data, 'Personal-data columns with no active field row', detail,
+                  items: rows.map { |row| "#{row[:resource]}.#{row[:column]}" })
+        end
+
+        def acknowledged_ids
+          @acknowledged_ids ||= if PermissionForge::Admin::AttentionItems.acknowledgement_supported?
+                                  PermissionForge::ResourceField.where.not(sensitive_acknowledged_at: nil).pluck(:id).to_set
+                                else
+                                  Set.new
+                                end
+        end
+      end
+    end
+  end
+end

data/lib/permission_forge/services/security_audit/privilege_check.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Services
+    module SecurityAuditChecks
+      # Privileged access: View All / Modify All, sets that look temporary,
+      # and sets that grant delete almost everywhere.
+      class PrivilegeCheck < BaseCheck
+        TEMPORARY_NAME = /\b(dev|debug|dbg|test|tmp|temp|sandbox|demo)\b|full access/i
+        BROAD_DELETE_MIN = 10
+        BROAD_DELETE_SHARE = 0.75
+
+        def call
+          [bypass_grants, temporary_sets, broad_delete].compact
+        end
+
+        private
+
+        def granting_resources
+          @granting_resources ||= PermissionForge::Resource.active.where(permission_set_id: active_granting_sets.select(:id))
+                                                           .includes(:permission_set).order(:name).to_a
+        end
+
+        def bypass_grants
+          bypassing = granting_resources.select(&:rules_bypassed?)
+          return if bypassing.empty?
+
+          held = bypassing.any? { |resource| people_counts.fetch(resource.permission_set_id, 0).positive? }
+          finding(held ? :medium : :low, :bypass_grants, 'View All / Modify All skip every record rule',
+                  'People with these grants see (and with Modify All change) every record of the resource. ' \
+                  'Keep them for administrators and give them an end date where possible.',
+                  items: bypassing.map { |resource| bypass_item(resource) })
+        end
+
+        def bypass_item(resource)
+          grant = resource.modify_all ? 'View All + Modify All' : 'View All'
+          "#{resource.permission_set.name} › #{resource.name}: #{grant} · #{people(resource.permission_set_id)}"
+        end
+
+        def temporary_sets
+          sets = PermissionForge::PermissionSet.active.order(:name).select { |set| set.name.match?(TEMPORARY_NAME) }
+          return if sets.empty?
+
+          held = sets.map(&:id).any? { |id| people_counts.key?(id) }
+          finding(held ? :medium : :low, :temporary_sets, 'Sets that look temporary are still active',
+                  'Their names suggest development, debugging or testing. Confirm they belong in this ' \
+                  'environment, or delete them.',
+                  items: sets.map { |set| "#{set.name} · #{people(set.id)}" })
+        end
+
+        def broad_delete
+          broad = granting_resources.group_by(&:permission_set).filter_map do |set, resources|
+            deletable = resources.count(&:delete_access)
+            next if deletable < BROAD_DELETE_MIN || deletable < resources.size * BROAD_DELETE_SHARE
+
+            "#{set.name}: delete on #{deletable} of #{resources.size} resources · #{people(set.id)}"
+          end
+          return if broad.empty?
+
+          finding(:low, :broad_delete, 'Sets grant delete almost everywhere',
+                  'Delete is rarely needed broadly. If people other than administrators hold these sets, ' \
+                  'move delete into a separate set.', items: broad)
+        end
+      end
+    end
+  end
+end

data/lib/permission_forge/services/security_audit/rule_check.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Services
+    module SecurityAuditChecks
+      # Record (row-level) rules: whether the app's query scoping applies them,
+      # rules whose value makes them match nothing, rules View All makes
+      # pointless, and likely misconfigurations.
+      class RuleCheck < BaseCheck
+        TEXT_OPERATORS = %w[contains starts_with ends_with].freeze
+        # What `current_user` is typed as here: an id is a number or its text,
+        # whoever the user is, and never a boolean or a date.
+        ANY_USER_ID = 0
+
+        def call
+          return [no_rules] unless active_rules.exists?
+
+          [unenforced, unusable_values, bypassed, text_operator_on_ids].compact
+        end
+
+        private
+
+        def active_rules
+          PermissionForge::PermissionSetRule.active
+        end
+
+        def no_rules
+          finding(:info, :no_rules, 'No record rules are in use',
+                  'Anyone with read access to a resource sees every record of it. That is fine if your app ' \
+                  'limits records itself; otherwise add rules and enable auto_query_scoping.')
+        end
+
+        def unenforced
+          findings = PermissionForge::Admin::AttentionItems.new(configuration: configuration).unenforced_rules
+          return if findings.empty?
+
+          held = findings.any? { |item| item.people_count.positive? }
+          finding(held ? :high : :medium, :unenforced_rules, 'Record rules are not applied to every query',
+                  unenforced_detail, items: findings.map { |item| unenforced_item(item) })
+        end
+
+        def unenforced_detail
+          if configuration.auto_query_scoping_enabled?
+            'These are join rules: auto_query_scoping skips them, so only find_by / permission_scoped apply ' \
+              'them. Route the queries through Model.permission_scoped.'
+          else
+            'auto_query_scoping is off, so these rules only apply to find_by / permission_scoped; a bare ' \
+              'where / all / association query returns every record. Enable auto_query_scoping = :filter_only ' \
+              '(see docs/query-scoping.md), and unscoped_query_detection to find the call sites.'
+          end
+        end
+
+        def unenforced_item(item)
+          "#{item.permission_set.name} › #{item.resource.name}: #{item.rule_count} rule(s) · " \
+            "#{people_label(item.people_count)}"
+        end
+
+        def unusable_values
+          rules = rules_in_effect.select { |rule| unusable_value?(rule) }
+          return if rules.empty?
+
+          held = rules.any? { |rule| people_counts.fetch(rule.resource.permission_set_id, 0).positive? }
+          finding(held ? :medium : :low, :unusable_rule_values, 'Rules that match nothing',
+                  'The value of these rules is not one their column can hold: text on a number column, a word that ' \
+                  'is no boolean, an unknown enum label, a date that is not ISO 8601 (on MySQL and SQLite), a list ' \
+                  'or range with the wrong number of values — or the field name is not a name (a trailing or ' \
+                  'doubled dot). Such a rule matches nothing: everyone it applies to is denied every record of ' \
+                  'the resource. Correct the rule or remove it (see "How Values Are Compared" in ' \
+                  'docs/row-level-rules.md).',
+                  items: rules.map { |rule| unusable_item(rule) })
+        end
+
+        # Active rules of active resources in active granting sets: the rules
+        # that are applied right now (a muting set's rules never are). Not the
+        # ones View All skips — nobody is denied by those; they are listed
+        # under bypassed_rules.
+        def rules_in_effect
+          resources = PermissionForge::Resource.in_effect.merge(PermissionForge::PermissionSet.granting)
+          active_rules.where(resource_id: resources.select(:id)).includes(resource: :permission_set).order(:resource_id, :id)
+                      .reject { |rule| rule.resource.rules_bypassed? }
+        end
+
+        # Typed the way the application layer types it (Operators::ValueTyping).
+        # A model that is not there, or cannot be read, says nothing about the
+        # value — that is the integrity check's finding, not one of this check.
+        def unusable_value?(rule)
+          target = rule_column(rule)
+          return false unless target
+
+          operator = rule.operator
+          value = rule.field_value
+          value = ANY_USER_ID if Operators::ValueTyping.current_user?(operator, value)
+          Operators::ValueTyping.call(operator, value, target).equal?(Operators::ValueTyping::UNUSABLE)
+        rescue ActiveRecord::ActiveRecordError, NameError, ArgumentError
+          false
+        end
+
+        # The column the rule names, found the way PermissionRuleApplier finds
+        # it. A rule whose association path cannot be followed is left out: the
+        # engine raises for it, it does not match nothing. Tables are checked
+        # first: asking a missing one for its columns fails the statement, and
+        # with it a transaction the audit may run in.
+        def rule_column(rule)
+          model = rule.resource.name.safe_constantize
+          return unless model.is_a?(Class) && model < ActiveRecord::Base
+
+          path = rule.join_rule? ? rule.field_accessor_path.to_s.split('.') : []
+          models = Operators::RuleColumn.models_along(model, path)
+          Operators::RuleColumn.find(rule.field_name, models) if models.any? && models.all?(&:table_exists?)
+        end
+
+        def unusable_item(rule)
+          resource = rule.resource
+          path = rule.field_accessor_path.presence if rule.join_rule?
+          field = [resource.name, path, rule.field_name].compact.join('.')
+          "#{resource.permission_set.name} › #{field} #{rule.operator} #{rule.field_value.inspect}: #{rule.name} · " \
+            "#{people(resource.permission_set_id)}"
+        end
+
+        def bypassed
+          rules = active_rules.includes(resource: :permission_set).select { |rule| rule.resource&.rules_bypassed? }
+          return if rules.empty?
+
+          finding(:low, :bypassed_rules, 'Rules ignored because View All is on',
+                  'View All / Modify All skip these rules. Remove the rule or the bypass so the setup says what it does.',
+                  items: rules.map { |rule| "#{rule.resource.permission_set.name} › #{rule.resource.name}: #{rule.name}" })
+        end
+
+        def text_operator_on_ids
+          rules = active_rules.where(operator: TEXT_OPERATORS).includes(:resource)
+                              .select { |rule| rule.field_name.to_s.end_with?('id') }
+          return if rules.empty?
+
+          finding(:low, :text_operator_on_ids, 'Text matching on id columns',
+                  'contains / starts_with / ends_with on an id matches more records than intended (12 contains 1). ' \
+                  'Use equal or in.', items: rules.map { |rule| "#{rule.resource.name}.#{rule.field_name}: #{rule.name}" })
+        end
+      end
+    end
+  end
+end

data/lib/permission_forge/services/security_audit/text_report.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Services
+    module SecurityAuditChecks
+      # Plain-text rendering of a SecurityAudit::Report for terminals and logs.
+      class TextReport
+        def initialize(report)
+          @report = report
+        end
+
+        def to_s
+          [header, *@report.findings.map { |finding| section(finding) }, footer].join("\n\n")
+        end
+
+        private
+
+        def header
+          counts = @report.counts.map { |severity, count| "#{severity.to_s.capitalize}: #{count}" }.join(' · ')
+          ["PermissionForge security audit — #{@report.generated_at.utc.iso8601}", preset, counts].compact.join("\n")
+        end
+
+        def preset
+          case @report.preset
+          when nil then nil
+          when :compat then 'Preset: :compat (the library defaults; config.preset = :strict closes the fail-open ones)'
+          else "Preset: #{@report.preset.inspect}"
+          end
+        end
+
+        def section(finding)
+          lines = ["[#{finding.severity.to_s.upcase}] #{finding.title}  (#{finding.check}/#{finding.code})",
+                   "  #{finding.detail}"]
+          lines.concat(Array(finding.items).map { |item| "    - #{item}" })
+          lines.join("\n")
+        end
+
+        def footer
+          return 'No findings.' if @report.findings.empty?
+
+          'Read-only: nothing was changed. FORMAT=json for machine output; FAIL_ON=high to fail CI.'
+        end
+      end
+    end
+  end
+end

data/lib/permission_forge/services/security_audit/user_model_check.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Services
+    module SecurityAuditChecks
+      # The user model (config.user_class): what sign-in needs from it, which
+      # runs before anyone is signed in, and what it shows then.
+      class UserModelCheck < BaseCheck
+        RULES = %i[user_model_scoped user_model_unmasked_without_user].freeze
+
+        def call
+          return [] unless user_model
+
+          RULES.filter_map { |rule| send(rule) }
+        end
+
+        private
+
+        def user_model
+          return @user_model if defined?(@user_model)
+
+          model = configuration.user_class.to_s.safe_constantize
+          @user_model = model.is_a?(Class) ? model : nil
+        end
+
+        # Record rules on the user model, with nobody signed in denied.
+        def user_model_scoped
+          return unless user_model < PermissionForge::Concerns::PermissionScopedFindable
+          return unless %i[deny raise].include?(configuration.nil_user_strategy)
+
+          finding(:low, :user_model_scoped, 'The user model cannot be looked up before sign-in',
+                  "#{user_model.name} includes PermissionScopedFindable and nil_user_strategy is " \
+                  ":#{configuration.nil_user_strategy}: sign-in, session restore, password reset and " \
+                  'confirmation run before anyone is signed in, and their lookups (where, find_by, ' \
+                  'authenticate_by) find nothing. Remove the concern from the user model (scope a user ' \
+                  'directory with permission_scoped in its controller), or run those lookups inside ' \
+                  'PermissionForge.without_permission_scope.')
+        end
+
+        # :hide exempts the user model so sign-in can read it.
+        def user_model_unmasked_without_user
+          return unless configuration.hide_masked_attributes_without_user?
+
+          names = user_model_resource_names
+          return if names.empty?
+
+          finding(:low, :user_model_unmasked_without_user, 'The user model is not masked with nobody signed in',
+                  'masked_attributes_nil_user_strategy is :hide, but the user model is exempt so that sign-in ' \
+                  "can read it: with nobody signed in, #{user_model.name}'s columns — password digests and " \
+                  'reset or confirmation tokens included — read as stored through its getters and as_json. ' \
+                  'Do not render it with no current user. Another authenticatable model (a second Devise ' \
+                  'scope) is not exempt: with a Resource row its sign-in reads hidden values.',
+                  items: names)
+        end
+
+        # The Resource names that mask the user model: its own and its STI
+        # ancestors' (ResourceChain), and its subclasses'.
+        def user_model_resource_names
+          chain = PermissionForge::ResourceChain.names(user_model).map(&:to_s)
+          PermissionForge::Resource.distinct.order(:name).pluck(:name).select do |name|
+            chain.include?(name) || configuration.user_model_class?(name.safe_constantize)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/permission_forge/services/security_audit.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Services
+    # Read-only security review of a PermissionForge setup: configuration,
+    # privileged grants, assignments, data integrity, record rules,
+    # personal-data exposure and controller actions. Backs
+    # `rake permission_forge:audit`.
+    #
+    # Each check is a class answering `#call` with an array of Finding,
+    # listed by `SecurityAudit.checks` (config, privilege, assignment, rule,
+    # integrity, personal data, controller actions, the audit trail and the
+    # user model);
+    # add one by passing `checks:` to `call` or by overriding `.checks`
+    # (OCP). Nothing is ever changed.
+    #
+    # @example
+    #   report = SecurityAudit.call
+    #   report.counts            # => { critical: 0, high: 1, ... }
+    #   report.at_least(:high)   # => [#<Finding ...>]
+    #
+    # @api public
+    class SecurityAudit
+      SEVERITIES = %i[critical high medium low info].freeze
+
+      # @api private
+      Finding = Struct.new(:check, :severity, :code, :title, :detail, :items, keyword_init: true) do
+        def to_h = super.merge(items: items || [])
+        def rank = SEVERITIES.index(severity)
+      end
+
+      # preset: the configuration's preset (:compat or :strict).
+      #
+      # @api private
+      Report = Struct.new(:findings, :generated_at, :preset, keyword_init: true) do
+        def counts = SEVERITIES.index_with { |severity| findings.count { |finding| finding.severity == severity } }
+
+        def at_least(severity)
+          limit = SEVERITIES.index(severity.to_sym) || SEVERITIES.size
+          findings.select { |finding| finding.rank <= limit }
+        end
+
+        def to_h = { generated_at: generated_at.iso8601, preset: preset, counts: counts, findings: findings.map(&:to_h) }
+      end
+
+      # @return [Array<Class>] the check classes run by default
+      def self.checks
+        [
+          SecurityAuditChecks::ConfigCheck, SecurityAuditChecks::PrivilegeCheck,
+          SecurityAuditChecks::AssignmentCheck, SecurityAuditChecks::RuleCheck,
+          SecurityAuditChecks::IntegrityCheck, SecurityAuditChecks::PersonalDataCheck,
+          SecurityAuditChecks::ActionCheck, SecurityAuditChecks::AuditTrailCheck,
+          SecurityAuditChecks::UserModelCheck
+        ]
+      end
+
+      # Runs the read-only security review.
+      # @return [Report]
+      def self.call(...) = new(...).call
+
+      def initialize(configuration: PermissionForge.configuration, checks: self.class.checks,
+                     environment: defined?(Rails) ? Rails.env.to_s : 'development')
+        @configuration = configuration
+        @checks = checks
+        @environment = environment
+      end
+
+      # @return [Report] the findings, most severe first
+      def call
+        findings = @checks.flat_map { |check| check.new(configuration: @configuration, environment: @environment).call }
+        Report.new(findings: findings.sort_by(&:rank), generated_at: Time.current, preset: @configuration.preset)
+      end
+    end
+  end
+end

data/lib/permission_forge/services/stale_assignment_auditor.rb

@@ -0,0 +1,68 @@
+module PermissionForge
+  module Services
+    # Audits permanent permission set assignments that haven't been reviewed
+    # within a configurable threshold (default: 90 days). Reviewed means the
+    # last access review "Keep" (reviewed_at), else the grant (created_at) —
+    # PermissionSetUser.stale_before; editing an assignment is not a review.
+    # Supports GDPR Art. 5(1)(e) — Storage Limitation.
+    #
+    # @example Find stale assignments
+    #   result = StaleAssignmentAuditor.call
+    #   # => { stale_count: 5, affected_user_ids: [1, 2], assignments: [...] }
+    #
+    # @example Custom threshold
+    #   result = StaleAssignmentAuditor.call(threshold_days: 30)
+    #
+    # With a tenant ambient, that tenant's assignments; with none, every
+    # tenant's — also under acts_as_tenant's require_tenant
+    # (Concerns::AcrossTenants).
+    #
+    # @api public
+    class StaleAssignmentAuditor
+      include Concerns::AcrossTenants
+
+      # @param threshold_days [Integer] how long a permanent assignment may go unreviewed
+      # @return [Hash] see {#call}
+      def self.call(...) = new(...).call
+
+      def initialize(threshold_days: 90)
+        @threshold_days = threshold_days
+      end
+
+      # @return [Hash] `{ stale_count:, affected_user_ids:, assignments: }`
+      def call
+        across_tenants do
+          stale = stale_assignments
+          {
+            stale_count: stale.count,
+            affected_user_ids: stale.distinct.pluck(:user_id),
+            threshold_days: @threshold_days,
+            assignments: stale.includes(:permission_set).map { |psu| row_for(psu) }
+          }
+        end
+      end
+
+      private
+
+      def row_for(psu)
+        last_reviewed = psu.last_reviewed_at
+        {
+          user_id: psu.user_id,
+          permission_set: psu.permission_set&.name,
+          last_updated: psu.updated_at,
+          last_reviewed_at: last_reviewed,
+          reviewed_by_id: psu.try(:reviewed_by_id),
+          days_stale: ((Time.current - last_reviewed) / 1.day).round
+        }
+      end
+
+      def stale_assignments
+        PermissionForge::PermissionSetUser.stale_before(threshold_cutoff)
+      end
+
+      def threshold_cutoff
+        @threshold_days.days.ago
+      end
+    end
+  end
+end

data/lib/permission_forge/services/unscoped_query_detector.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Services
+    # Level 2 — DETECT (config.unscoped_query_detection = :log | :raise).
+    #
+    # Subscribes to sql.active_record and reports SELECT/UPDATE/DELETE
+    # statements that touch a protected model's table without carrying the
+    # pf_scoped annotation (added by permission_scoped, Level 1 auto-scoping,
+    # and internal gem paths). INSERTs, schema/EXPLAIN queries, and anything
+    # executed inside PermissionForge.without_permission_scope (which also
+    # covers the gem's own internal probes) are never flagged.
+    #
+    #   :log   -> Rails.logger.warn with the SQL and the first app call site
+    #   :raise -> PermissionForge::UnscopedQueryError
+    #
+    # Either way the finding is published as query.unscoped (model, table,
+    # mode, call site — not the SQL, which can carry values), at most once per
+    # request per table.
+    #
+    # Detection is environment-gated via
+    # config.unscoped_query_detection_environments (default: development, test)
+    # — it is a migration aid and CI guard, not a production control. The
+    # notification subscriber runs synchronously on the querying thread, so
+    # :raise surfaces at the offending call site.
+    #
+    # @api private
+    class UnscopedQueryDetector
+      MARKER = "/* #{PermissionForge::Concerns::PermissionScopedFindable::SCOPED_ANNOTATION} */".freeze
+      STATEMENT_PATTERN = /\A\s*(?:SELECT|UPDATE|DELETE)\b/i
+      IGNORED_PAYLOAD_NAMES = ['SCHEMA', 'EXPLAIN', nil].freeze
+
+      class << self
+        # Installs the sql.active_record subscriber (idempotent).
+        def install!
+          # rubocop:disable-next Naming/MemoizedInstanceVariableName -- @subscriber is the handle uninstall! needs
+          @subscriber ||= ActiveSupport::Notifications.subscribe('sql.active_record') do |*, payload|
+            check(payload)
+          end
+        end
+
+        # Removes the subscriber (used by tests to isolate detection state).
+        def uninstall!
+          return unless @subscriber
+
+          ActiveSupport::Notifications.unsubscribe(@subscriber)
+          @subscriber = nil
+        end
+
+        def installed?
+          !@subscriber.nil?
+        end
+
+        # Evaluates a single sql.active_record payload. Public for direct
+        # testing without a live subscriber.
+        def check(payload)
+          return unless PermissionForge.configuration.unscoped_query_detection_active?
+          return if PermissionForge.scope_suspended?
+          return if IGNORED_PAYLOAD_NAMES.include?(payload[:name])
+
+          sql = payload[:sql].to_s
+          return unless sql.match?(STATEMENT_PATTERN)
+          return if sql.include?(MARKER)
+
+          table = protected_table_in(sql)
+          return unless table
+
+          report(sql, table)
+        end
+
+        private
+
+        def protected_table_in(sql)
+          PermissionForge::Concerns::PermissionScopedFindable.protected_table_names.find do |table|
+            sql.match?(/\b#{Regexp.escape(table)}\b/)
+          end
+        end
+
+        def report(sql, table)
+          publish(table)
+          message = I18n.t(
+            'permission_forge.errors.unscoped_query',
+            table: table,
+            default: "Unscoped query on protected table '#{table}'. Use permission_scoped / find_by, " \
+                     'enable auto_query_scoping, or wrap intentional access in ' \
+                     'PermissionForge.without_permission_scope { }.'
+          )
+
+          raise PermissionForge::UnscopedQueryError, "#{message} SQL: #{sql}" if raise_mode?
+
+          Rails.logger&.warn("[PermissionForge] #{message} SQL: #{truncate_sql(sql)}#{app_call_site}")
+        end
+
+        def publish(table)
+          return unless PermissionForge::Audit.instrument?(PermissionForge::Audit::Runtime::UNSCOPED)
+
+          PermissionForge::Audit::Runtime.unscoped(
+            model: protected_model_for(table), table: table,
+            data: { 'mode' => PermissionForge.configuration.unscoped_query_detection.to_s, 'call_site' => cleaned_backtrace_frame }
+          )
+        end
+
+        def protected_model_for(table)
+          PermissionForge::Concerns::PermissionScopedFindable.protected_model_names.find do |model_name|
+            model_name.safe_constantize&.table_name == table
+          end
+        end
+
+        def raise_mode?
+          PermissionForge.configuration.unscoped_query_detection == :raise
+        end
+
+        def truncate_sql(sql)
+          sql.length > 300 ? "#{sql[0, 300]}…" : sql
+        end
+
+        # The subscriber runs synchronously on the querying thread, so caller
+        # still contains the app frame that triggered the query.
+        def app_call_site
+          frame = cleaned_backtrace_frame
+          frame ? " Called from: #{frame}" : ''
+        end
+
+        def cleaned_backtrace_frame
+          return caller.first unless defined?(Rails) && Rails.respond_to?(:backtrace_cleaner)
+
+          Rails.backtrace_cleaner.clean(caller).first
+        end
+      end
+    end
+  end
+end