woods 1.2.0 → 1.3.0

data/lib/woods/console/sql_noise_stripper.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+# @see Woods
+module Woods
+  module Console
+    # Strips SQL comments and string literals from a SQL string so that
+    # downstream checks (keyword scanning, table scanning) are not confused
+    # by content embedded inside comments or literals.
+    #
+    # This is a shared utility used by {SqlValidator} and {TableGate} to
+    # avoid duplicating comment- and literal-stripping logic. All methods
+    # are module-level and stateless — pass a SQL string in, receive a
+    # stripped string out.
+    #
+    # @example Strip comments only
+    #   SqlNoiseStripper.strip_comments("SELECT 1 -- pick one\nFROM t")
+    #   # => "SELECT 1 \nFROM t"
+    #
+    # @example Strip literals (PostgreSQL dialect)
+    #   SqlNoiseStripper.strip_literals("SELECT 'it''s ok' FROM t")
+    #   # => "SELECT '' FROM t"
+    #
+    # @example Strip literals (MySQL dialect — backslash escapes)
+    #   SqlNoiseStripper.strip_literals("SELECT 'it\\'s ok' FROM t", dialect: :mysql)
+    #   # => "SELECT '' FROM t"
+    #
+    module SqlNoiseStripper
+      # Strips SQL line comments (`-- ...`) and block comments (`/* ... */`).
+      # Line comments are stripped to (but not including) the newline so that
+      # newline-separated statement structure is preserved for callers that
+      # check for multiple statements.
+      #
+      # Block comments are non-nested — real SQL engines do not support nested
+      # block comments, and neither does this stripper.
+      #
+      # @param sql [String] the SQL string to process
+      # @return [String] a new string with all SQL comments removed
+      LINE_COMMENT   = /--[^\n]*/
+      BLOCK_COMMENT  = %r{/\*.*?\*/}m
+
+      def self.strip_comments(sql)
+        out = sql.gsub(LINE_COMMENT, '')
+        out.gsub(BLOCK_COMMENT, '')
+      end
+
+      # Strips single-quoted string literals and (for the `:postgres` dialect)
+      # PostgreSQL dollar-quoted string literals from a SQL string, replacing
+      # each with an empty `''` placeholder so that the structure of the SQL
+      # is maintained for subsequent checks.
+      #
+      # Dollar-quoted strings are stripped before single-quoted strings so that
+      # stray apostrophes inside a dollar-quoted body do not confuse the
+      # single-quote scanner.
+      #
+      # @param sql [String] the SQL string to process
+      # @param dialect [Symbol] `:postgres` (default) or `:mysql`.
+      #   - `:postgres` — single-quoted strings support `''` as an apostrophe
+      #     escape. Backslash is treated literally and does not escape quotes.
+      #     Dollar-quoted strings (`$$...$$`, `$tag$...$tag$`) are also stripped.
+      #   - `:mysql` — single-quoted strings support both `\'` (backslash-escape)
+      #     and `''` (doubled-quote) as apostrophe escapes. Dollar-quoted strings
+      #     are also stripped (MySQL does not use them, but stripping them is
+      #     harmless and keeps the two dialects consistent).
+      # @return [String] a new string with all string literals replaced by `''`
+      # @raise [ArgumentError] if an unsupported dialect is provided
+      DOLLAR_QUOTED = /\$(\w*)\$.*?\$\1\$/m
+      SINGLE_QUOTED_POSTGRES = /'(?:''|[^'])*'/m
+      SINGLE_QUOTED_MYSQL    = /'(?:\\.|''|[^'])*'/m
+
+      SUPPORTED_DIALECTS = %i[postgres mysql].freeze
+      private_constant :SUPPORTED_DIALECTS
+
+      def self.strip_literals(sql, dialect: :postgres)
+        unless SUPPORTED_DIALECTS.include?(dialect)
+          raise ArgumentError, "Unknown dialect #{dialect.inspect}. Supported: #{SUPPORTED_DIALECTS.inspect}"
+        end
+
+        # Strip dollar-quoted strings first so stray apostrophes inside them
+        # do not interfere with the single-quote scanner.
+        out = sql.gsub(DOLLAR_QUOTED, "''")
+
+        pattern = dialect == :mysql ? SINGLE_QUOTED_MYSQL : SINGLE_QUOTED_POSTGRES
+        out.gsub(pattern, "''")
+      end
+    end
+  end
+end

data/lib/woods/console/sql_table_scanner.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require 'woods/console/sql_noise_stripper'
+
+# @see Woods
+module Woods
+  module Console
+    # Extracts table and schema-qualified identifiers from a SQL string.
+    #
+    # Handles both JOIN-style and ANSI-89 comma-join syntax across MySQL and
+    # PostgreSQL quoting styles (`backtick`, `"double"`, bare). Schema-qualified
+    # identifiers (`schema.table`, `"schema"."table"`, `` `db`.`table` ``) are
+    # returned as `schema.table` strings so callers can compare against either
+    # the bare or qualified form.
+    #
+    # Noise (comments, string literals, dollar-quoted bodies) is stripped via
+    # {SqlNoiseStripper} before scanning so that identifiers embedded in literal
+    # content are never surfaced.
+    #
+    # All methods are module-level and stateless — pass a SQL string in, receive
+    # an array of identifier strings out.
+    #
+    # @example
+    #   SqlTableScanner.identifiers_in('SELECT * FROM users JOIN orders ON ...')
+    #   # => ["users", "orders"]
+    #
+    #   SqlTableScanner.identifiers_in('SELECT * FROM "audit"."events"')
+    #   # => ["audit.events"]
+    #
+    module SqlTableScanner # rubocop:disable Metrics/ModuleLength
+      # Matches a JOIN token followed by its target identifier. The identifier
+      # may be schema-qualified in any quoting style — `"schema"."table"`,
+      # `` `db`.`table` ``, bare `schema.table`, or the mixed
+      # `schema."table"` / `` schema.`table` `` forms — and the optional
+      # schema prefix is captured separately so callers can compare against
+      # either the bare or qualified configured form. An optional `ONLY`
+      # keyword (PostgreSQL inheritance opt-out) is consumed before the
+      # identifier so it does not hide the table name. ANSI-89 comma joins
+      # are handled separately — see FROM_CLAUSE.
+      JOIN_REFERENCE = /
+        \b(?:STRAIGHT_)?JOIN\s+
+        (?:ONLY\s+)?
+        (?:
+          (?:
+            `(?<jschema_bt>[^`]+)` |
+            "(?<jschema_dq>[^"]+)" |
+            (?<jschema_bare>\w+)
+          )
+          \.
+        )?
+        (?:
+          `(?<backtick>[^`]+)` |
+          "(?<double>[^"]+)"   |
+          (?<bare>\w+(?:\.\w+)?)
+        )
+      /xi
+
+      # Matches a FROM clause and captures its body up to the next clause
+      # terminator. The body may be a single table or a comma-joined list.
+      #
+      # An inner `FROM` is also a terminator — this is H-3 of the bypass
+      # series. Without it, a FROM-clause subquery like
+      # `FROM (SELECT * FROM blocked) AS a` would be swallowed by the outer
+      # clause's `.+?` match, and the inner `FROM blocked` would never be
+      # re-scanned because `.scan` advances past consumed input. Treating
+      # every `FROM` as its own independent scan match is what keeps CTEs,
+      # UNIONs, and nested subqueries in coverage.
+      FROM_CLAUSE = /
+        \bFROM\s+
+        (?<clause>.+?)
+        (?=
+          \b(?:WHERE|GROUP|HAVING|ORDER|LIMIT|OFFSET|UNION|INTERSECT|EXCEPT|
+               STRAIGHT_JOIN|JOIN|INNER|OUTER|LEFT|RIGHT|FULL|CROSS|FROM)\b
+          | [;)]
+          | \z
+        )
+      /xim
+
+      # Matches a leading table identifier at the start of a FROM-list chunk.
+      # The identifier may carry an optional schema prefix in any quoting
+      # style — `"schema"."table"`, `` `db`.`table` ``, or the mixed
+      # `schema."table"` / `` schema.`table` `` form — captured separately so
+      # callers can match against bare or qualified configured forms.
+      LEAD_IDENT = /
+        \A
+        (?:
+          (?:
+            `(?<schema_bt>[^`]+)` |
+            "(?<schema_dq>[^"]+)" |
+            (?<schema_bare>\w+)
+          )
+          \.
+        )?
+        (?:
+          `(?<backtick>[^`]+)` |
+          "(?<double>[^"]+)"   |
+          (?<bare>\w+(?:\.\w+)?)
+        )
+      /xi
+
+      # PostgreSQL ONLY keyword that appears between FROM and the table
+      # identifier. Strip it so the lead-identifier regex sees the table
+      # directly. Anchored with `\A` because callers strip leading whitespace
+      # first via #strip.
+      ONLY_PREFIX = /\AONLY\s+/i
+
+      # Returns every table/schema-qualified identifier referenced in the SQL
+      # string. Noise (comments, string literals, dollar-quoted bodies) is
+      # stripped before scanning. Both JOIN-style and ANSI-89 comma-join syntax
+      # are handled.
+      #
+      # @param sql [String, nil] the SQL string to scan
+      # @return [Array<String>] identifiers in the order they were encountered;
+      #   may contain duplicates if the same table is referenced multiple times
+      def self.identifiers_in(sql)
+        return [] if sql.nil? || sql.empty?
+
+        stripped = strip_noise(sql)
+        results = []
+        collect_join_identifiers(stripped, results)
+        collect_from_identifiers(stripped, results)
+        results
+      end
+
+      # @api private
+      def self.strip_noise(sql)
+        out = SqlNoiseStripper.strip_comments(sql)
+        SqlNoiseStripper.strip_literals(out, dialect: :mysql)
+      end
+      private_class_method :strip_noise
+
+      # @api private
+      def self.collect_join_identifiers(sql, results)
+        sql.scan(JOIN_REFERENCE) do
+          match = Regexp.last_match
+          results << qualified_identifier(match)
+        end
+      end
+      private_class_method :collect_join_identifiers
+
+      # @api private
+      def self.collect_from_identifiers(sql, results)
+        sql.scan(FROM_CLAUSE) do
+          clause = Regexp.last_match[:clause]
+          split_top_level_commas(clause).each do |chunk|
+            ident = lead_identifier(chunk)
+            results << ident if ident
+          end
+        end
+      end
+      private_class_method :collect_from_identifiers
+
+      # @api private
+      # Split a comma-separated list at depth 0, skipping commas inside parens.
+      def self.split_top_level_commas(clause) # rubocop:disable Metrics/MethodLength
+        depth = 0
+        buf = +''
+        parts = []
+        clause.each_char do |ch|
+          case ch
+          when '('
+            depth += 1
+            buf << ch
+          when ')'
+            depth -= 1
+            buf << ch
+          when ','
+            if depth.zero?
+              parts << buf
+              buf = +''
+            else
+              buf << ch
+            end
+          else
+            buf << ch
+          end
+        end
+        parts << buf unless buf.strip.empty?
+        parts
+      end
+      private_class_method :split_top_level_commas
+
+      # @api private
+      # Extract the table identifier at the start of a FROM-list chunk,
+      # joining a schema prefix to the table when both are present. The
+      # PostgreSQL `ONLY` inheritance keyword is stripped first so it does
+      # not hide the table.
+      def self.lead_identifier(chunk)
+        stripped = chunk.to_s.strip.sub(ONLY_PREFIX, '')
+        return nil if stripped.empty?
+
+        match = LEAD_IDENT.match(stripped)
+        return nil unless match
+
+        qualified_identifier(match)
+      end
+      private_class_method :lead_identifier
+
+      # @api private
+      # Combine a schema prefix with the table identifier captured by
+      # JOIN_REFERENCE / LEAD_IDENT into a single `schema.table` string.
+      def self.qualified_identifier(match)
+        table = match[:backtick] || match[:double] || match[:bare]
+        schema = match.named_captures.values_at(
+          'schema_bt', 'schema_dq', 'schema_bare',
+          'jschema_bt', 'jschema_dq', 'jschema_bare'
+        ).compact.first
+        schema ? "#{schema}.#{table}" : table
+      end
+      private_class_method :qualified_identifier
+    end
+  end
+end

data/lib/woods/console/sql_validator.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'woods/console/sql_noise_stripper'
+
 # @see Woods
 module Woods
   class Error < StandardError; end unless defined?(Woods::Error)
@@ -17,18 +19,44 @@ module Woods
     #
     # @example
     #   validator = SqlValidator.new
-    #   validator.validate!('SELECT * FROM users')         # => true
-    #   validator.validate!('DELETE FROM users')            # => raises SqlValidationError
+    #   validator.validate!('SELECT * FROM users')         # passes
+    #   validator.validate!('DELETE FROM users')            # raises SqlValidationError
     #   validator.valid?('SELECT 1')                       # => true
     #
     class SqlValidator
       # Forbidden statement prefixes (case-insensitive).
+      #
+      # Expanded beyond DML/DDL to cover:
+      # - PG procedural (`DO`, `CALL`) which can run arbitrary plpgsql.
+      # - Session-state mutation (`SET`, `RESET`) — `SET ROLE`, `SET search_path`
+      #   can swap out the effective permission set for the rest of the session
+      #   even under rollback.
+      # - Admin/cluster ops (`VACUUM`, `ANALYZE`, `CLUSTER`, `REINDEX`,
+      #   `REFRESH`, `LOCK`) which are reads in the English-language sense
+      #   but carry side effects or heavy locks.
+      # - Async signalling (`LISTEN`, `NOTIFY`).
+      # - Prepared-statement lifecycle (`PREPARE`, `EXECUTE`, `DEALLOCATE`).
+      # - Transaction control (`BEGIN`, `COMMIT`, `ROLLBACK`, `SAVEPOINT`,
+      #   `RELEASE`, `START`) — SafeContext already owns the surrounding
+      #   transaction; inner tx control would corrupt it.
+      # - File I/O vectors (`LOAD`, `HANDLER`, `COPY`).
       FORBIDDEN_KEYWORDS = %w[
         INSERT UPDATE DELETE DROP ALTER TRUNCATE CREATE GRANT REVOKE
+        DO CALL SET RESET LISTEN NOTIFY
+        VACUUM ANALYZE CLUSTER REINDEX REFRESH LOCK
+        PREPARE EXECUTE DEALLOCATE
+        BEGIN COMMIT ROLLBACK SAVEPOINT RELEASE START
+        LOAD HANDLER COPY
       ].freeze
 
       # Keywords that are forbidden anywhere in the SQL (not just at start).
-      BODY_FORBIDDEN_KEYWORDS = %w[UNION INTO COPY].freeze
+      #
+      # UNION / INTERSECT / EXCEPT are SQL set operators — any of them can graft
+      # a second SELECT onto a validated one, which defeats the "single SELECT"
+      # posture even though TableGate still catches references to blocked tables.
+      # INTO / COPY are PostgreSQL write vectors that must not appear in read
+      # contexts.
+      BODY_FORBIDDEN_KEYWORDS = %w[UNION INTERSECT EXCEPT INTO COPY].freeze
 
       # Dangerous functions that can be used for DoS or file access.
       DANGEROUS_FUNCTIONS = %w[
@@ -37,11 +65,44 @@ module Woods
       ].freeze
 
       # Allowed statement prefixes (case-insensitive).
-      ALLOWED_PREFIXES = /\A\s*(SELECT|WITH|EXPLAIN)\b/i
+      #
+      # `EXPLAIN ANALYZE` actually executes the planned query on PostgreSQL
+      # (and the MySQL 8.0+ `EXPLAIN ANALYZE` does the same) — explicitly
+      # reject the `ANALYZE` variant. PostgreSQL also accepts an option-list
+      # form `EXPLAIN (ANALYZE, FORMAT JSON) SELECT …` where `ANALYZE` follows
+      # `(` rather than whitespace; the `(?!\s*\(?\s*ANALYZE)` lookahead
+      # rejects both spellings so SafeContext doesn't silently trust
+      # "we're just planning, not running" for what is a side-effectful
+      # execution. `EXPLAIN (…)` without `ANALYZE` is still permitted
+      # (e.g. `EXPLAIN (FORMAT JSON) SELECT 1`).
+      ALLOWED_PREFIXES = /\A\s*(SELECT|WITH|EXPLAIN(?!\s+ANALYZE)(?!\s*\([^)]*\bANALYZE\b))\b/i
+
+      # Frozen map of forbidden keyword => regex matching the keyword at statement start.
+      # Used by {#check_forbidden_keywords!} and {#check_forbidden_keywords_in_body!}.
+      FORBIDDEN_PREFIX_REGEXES = FORBIDDEN_KEYWORDS.to_h do |kw|
+        [kw, /\A\s*#{kw}\b/i]
+      end.freeze
+
+      # Frozen map of forbidden body keyword => regex matching the keyword anywhere.
+      # Used by {#check_body_forbidden_keywords!}.
+      BODY_FORBIDDEN_REGEXES = BODY_FORBIDDEN_KEYWORDS.to_h do |kw|
+        [kw, /\b#{kw}\b/i]
+      end.freeze
+
+      # Frozen map of forbidden keyword => regex matching the keyword anywhere in the body.
+      # Used by {#check_forbidden_keywords_in_body!} for the whole-body scan.
+      FORBIDDEN_BODY_REGEXES = FORBIDDEN_KEYWORDS.to_h do |kw|
+        [kw, /\b#{kw}\b/i]
+      end.freeze
+
+      # Frozen map of dangerous function name => regex matching a call to that function.
+      # Used by {#check_dangerous_functions!}.
+      DANGEROUS_FUNCTION_REGEXES = DANGEROUS_FUNCTIONS.to_h do |func|
+        [func, /\b#{func}\s*\(/i]
+      end.freeze
 
-      # @return [true]
       # @raise [SqlValidationError] if the SQL is not a safe read-only statement
-      def validate!(sql) # rubocop:disable Naming/PredicateMethod
+      def validate!(sql)
         raise SqlValidationError, 'SQL is empty' if sql.nil? || sql.strip.empty?
 
         normalized = sql.strip
@@ -67,11 +128,9 @@ module Woods
         check_forbidden_keywords_in_body!(normalized)
 
         # Must start with an allowed prefix
-        unless normalized.match?(ALLOWED_PREFIXES)
-          raise SqlValidationError, 'Rejected: SQL must start with SELECT, WITH, or EXPLAIN'
-        end
+        return if normalized.match?(ALLOWED_PREFIXES)
 
-        true
+        raise SqlValidationError, 'Rejected: SQL must start with SELECT, WITH, or EXPLAIN'
       end
 
       # Check if SQL is valid without raising.
@@ -93,11 +152,8 @@ module Woods
       # @param sql [String]
       # @return [Boolean]
       def contains_multiple_statements?(sql)
-        # Strip SQL comments before checking
-        stripped = sql.gsub(/--[^\n]*/, '') # line comments
-        stripped = stripped.gsub(%r{/\*.*?\*/}m, '') # block comments
-        # Strip single-quoted strings to avoid false positives
-        stripped = stripped.gsub(/'[^']*'/, '')
+        stripped = SqlNoiseStripper.strip_comments(sql)
+        stripped = SqlNoiseStripper.strip_literals(stripped)
         stripped.include?(';')
       end
 
@@ -106,10 +162,8 @@ module Woods
       # @param sql [String]
       # @raise [SqlValidationError] if a forbidden keyword is found
       def check_forbidden_keywords!(sql)
-        FORBIDDEN_KEYWORDS.each do |keyword|
-          if sql.match?(/\A\s*#{keyword}\b/i)
-            raise SqlValidationError, "Rejected: #{keyword} statements are not allowed"
-          end
+        FORBIDDEN_PREFIX_REGEXES.each do |keyword, pattern|
+          raise SqlValidationError, "Rejected: #{keyword} statements are not allowed" if sql.match?(pattern)
         end
       end
 
@@ -118,8 +172,8 @@ module Woods
       # @param sql [String]
       # @raise [SqlValidationError] if a forbidden keyword is found
       def check_body_forbidden_keywords!(sql)
-        BODY_FORBIDDEN_KEYWORDS.each do |keyword|
-          raise SqlValidationError, "Rejected: #{keyword} is not allowed" if sql.match?(/\b#{keyword}\b/i)
+        BODY_FORBIDDEN_REGEXES.each do |keyword, pattern|
+          raise SqlValidationError, "Rejected: #{keyword} is not allowed" if sql.match?(pattern)
         end
       end
 
@@ -138,10 +192,8 @@ module Woods
       # @param sql [String]
       # @raise [SqlValidationError] if a dangerous function is found
       def check_dangerous_functions!(sql)
-        DANGEROUS_FUNCTIONS.each do |func|
-          if sql.match?(/\b#{func}\s*\(/i)
-            raise SqlValidationError, "Rejected: dangerous function #{func} is not allowed"
-          end
+        DANGEROUS_FUNCTION_REGEXES.each do |func, pattern|
+          raise SqlValidationError, "Rejected: dangerous function #{func} is not allowed" if sql.match?(pattern)
         end
       end
 
@@ -151,17 +203,15 @@ module Woods
       # @param sql [String]
       # @raise [SqlValidationError] if a forbidden keyword is found
       def check_forbidden_keywords_in_body!(sql)
-        # Strip comments to reveal hidden statements
-        stripped = sql.gsub(/--[^\n]*/, '') # line comments
-        stripped = stripped.gsub(%r{/\*.*?\*/}m, '') # block comments
+        stripped = SqlNoiseStripper.strip_comments(sql)
 
         # Check if any forbidden keyword appears anywhere (not just at start)
-        FORBIDDEN_KEYWORDS.each do |keyword|
+        FORBIDDEN_BODY_REGEXES.each do |keyword, body_pattern|
           # Look for keyword as a whole word anywhere in the stripped SQL
-          next unless stripped.match?(/\b#{keyword}\b/i)
+          next unless stripped.match?(body_pattern)
 
           # Make sure it's not at the very start (already checked)
-          unless stripped.match?(/\A\s*#{keyword}\b/i)
+          unless stripped.match?(FORBIDDEN_PREFIX_REGEXES[keyword])
             raise SqlValidationError,
                   "Rejected: #{keyword} statements are not allowed (found in SQL body)"
           end

data/lib/woods/console/table_gate.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require 'set'
+require 'woods/console/sql_table_scanner'
+
+# @see Woods
+module Woods
+  class Error < StandardError; end unless defined?(Woods::Error)
+
+  module Console
+    class TableGateError < Woods::Error; end
+
+    # Layer 1 of the Console defense-in-depth stack: rejects requests touching
+    # blocked tables. SQL parsing is delegated to {SqlTableScanner}; this class
+    # handles permission enforcement only. Raises {TableGateError} on violations.
+    class TableGate
+      # @param blocked_tables [Array<String>] case-insensitive; bare names match every schema.
+      # @param model_tables [Hash{String=>String}] model => table.
+      # @param model_reflections [Hash{String=>Hash{String=>String}}] model => assoc => table.
+      def initialize(blocked_tables:, model_tables:, model_reflections: {})
+        @blocked_bare = Set.new
+        @blocked_qualified = Set.new
+        Array(blocked_tables).each do |entry|
+          name = entry.to_s.downcase
+          next if name.empty?
+
+          name.include?('.') ? @blocked_qualified << name : @blocked_bare << name
+        end
+        @model_tables = model_tables || {}
+        @model_reflections = model_reflections || {}
+      end
+
+      def active? = !(@blocked_bare.empty? && @blocked_qualified.empty?)
+
+      def check_sql!(sql)
+        return unless active? && sql&.length&.positive?
+
+        SqlTableScanner.identifiers_in(sql).each do |raw|
+          raise TableGateError, reject_message(raw) if blocked?(raw)
+        end
+      end
+
+      def check_model!(model_name)
+        return unless active?
+
+        table = @model_tables[model_name.to_s]
+        check_table!(table) unless table.nil?
+      end
+
+      def check_table!(table_name)
+        return unless active?
+        return if table_name.nil? || table_name.to_s.empty?
+        raise TableGateError, reject_message(table_name) if blocked?(table_name)
+      end
+
+      def check_joins!(model_name, joins) # rubocop:disable Metrics/CyclomaticComplexity
+        return unless active? && joins && Array(joins).any?
+
+        reflections = @model_reflections[model_name.to_s]
+        return unless reflections
+
+        Array(joins).each do |join|
+          table = reflections[join.to_s]
+          raise TableGateError, reject_message(table) if table && blocked?(table)
+        end
+      end
+
+      def check_association!(model_name, association)
+        return unless active? && association
+
+        reflections = @model_reflections[model_name.to_s]
+        return unless reflections
+
+        table = reflections[association.to_s]
+        raise TableGateError, reject_message(table) if table && blocked?(table)
+      end
+
+      private
+
+      def blocked?(raw)
+        name = raw.to_s.downcase
+        @blocked_qualified.include?(name) || @blocked_bare.include?(strip_schema(name))
+      end
+
+      def strip_schema(raw) = raw.to_s.split('.').last.to_s
+
+      def reject_message(name)
+        "Rejected: table '#{name}' is on console_blocked_tables. " \
+          'This tool is gated in Console MCP configuration.'
+      end
+    end
+  end
+end