woods 1.6.3 → 1.6.4

data/lib/woods/console/rack_middleware.rb

@@ -3,6 +3,9 @@
 require 'json'
 require 'woods/mcp/http_transport_options'
 require 'woods/observability/structured_logger'
+require 'woods/mcp/bearer_auth'
+require 'woods/mcp/origin_guard'
+require 'rack/request'
 
 module Woods
   module Console
@@ -66,7 +69,7 @@ module Woods
     # If your threat model requires stricter isolation, use the bridge mode instead
     # (docs/CONSOLE_MCP_SETUP.md) which runs the executor in a separate process.
     #
-    class RackMiddleware
+    class RackMiddleware # rubocop:disable Metrics/ClassLength -- mount-local authentication precedes legacy construction
       # @param app [#call] The next Rack app in the middleware stack
       # @param path [String] URL path to mount the MCP endpoint (default: '/mcp/console')
       # @param embedded_read_tools [Boolean] Enable sql/query tools in embedded mode (default: false)
@@ -77,8 +80,14 @@ module Woods
       # @param unsafe_eval_audit_log_path [String, Pathname, nil] JSONL audit log
       #   path for every `console_eval` run. Required on the opt-in path. Takes
       #   precedence over `config.console_unsafe_eval_audit_log_path`.
-      def initialize(app, path: '/mcp/console', embedded_read_tools: false,
-                     unsafe_eval_confirmation: nil, unsafe_eval_audit_log_path: nil)
+      def initialize(app, options = {}, **keywords)
+        raise TypeError, 'middleware options must be a Hash' unless options.is_a?(Hash)
+
+        initialize_options(app, **options, **keywords)
+      end
+
+      def initialize_options(app, path: '/mcp/console', embedded_read_tools: false, origin_policy: nil, # rubocop:disable Metrics/ParameterLists -- preserves legacy eval options alongside the shared HTTP policy
+                             unsafe_eval_confirmation: nil, unsafe_eval_audit_log_path: nil)
         @app = app
         @path = path
         @embedded_read_tools = embedded_read_tools
@@ -86,7 +95,15 @@ module Woods
         @unsafe_eval_audit_log_path = unsafe_eval_audit_log_path
         @mutex = Mutex.new
         @transport = nil
+        @origin_policy = origin_policy || Woods::MCP::OriginPolicy.new(
+          allowed_origins: Woods.configuration&.console_mcp_allowed_origins
+        )
+        authenticated = Woods::MCP::BearerAuth.new(
+          method(:handle_request), token: -> { Woods.configuration.console_mcp_token }
+        )
+        @guarded_request = Woods::MCP::OriginGuard.new(authenticated, policy: @origin_policy)
       end
+      private :initialize_options
 
       DISABLED_BODY = JSON.generate(
         error: 'woods_console_disabled',
@@ -108,11 +125,15 @@ module Woods
         return @app.call(env) unless env['PATH_INFO'].start_with?(@path)
         return [410, { 'content-type' => 'application/json' }, [DISABLED_BODY]] unless enabled?
 
-        ensure_transport.handle_request(Rack::Request.new(env))
+        @guarded_request.call(env)
       end
 
       private
 
+      def handle_request(env)
+        ensure_transport.handle_request(Rack::Request.new(env))
+      end
+
       def enabled?
         Woods.configuration.console_mcp_enabled
       end
@@ -133,7 +154,7 @@ module Woods
 
           server = build_embedded_server
           @transport = ::MCP::Server::Transports::StreamableHTTPTransport.new(
-            server, **Woods::MCP::HttpTransportOptions.for(Woods.configuration.console_mcp_allowed_origins)
+            server, **@origin_policy.transport_options
           )
           server.transport = @transport
           @transport
@@ -179,7 +200,7 @@ module Woods
         config = Woods.configuration
         introspection = build_model_introspection
         Server.build_embedded(
-          model_validator: ModelValidator.new(registry: introspection[:registry]),
+          model_validator: ModelValidator.new(registry: introspection[:registry], table_names: introspection[:tables]),
           safe_context: SafeContext.new(pool: ActiveRecord::Base.connection_pool),
           redacted_columns: Array(config&.console_redacted_columns),
           redacted_key_values: Array(config&.console_redacted_key_values),

data/lib/woods/console/redactor.rb

@@ -65,7 +65,8 @@ module Woods
         case key
         when 'record'         then value.is_a?(Hash) ? ctx.redact(value) : value
         when 'records'        then redact_hash_array(value, ctx)
-        when 'rows', 'values' then redact_positional(value, plan)
+        when 'rows'           then redact_positional(value, plan)
+        when 'values'         then redact_positional(value, plan, single_column: plan[:column_count] == 1)
         when 'associations'   then redact_association_map(value, ctx)
         else                       value
         end
@@ -93,7 +94,8 @@ module Woods
       # `columns` header: the column-name mask plus any EAV key-value rules
       # resolved to column indexes.
       def positional_plan(columns, ctx)
-        { mask: positional_mask(columns, ctx),
+        { column_count: columns.is_a?(Array) ? columns.length : nil,
+          mask: positional_mask(columns, ctx),
           kv_rules: positional_kv_rules(columns, ctx) }
       end
 
@@ -112,35 +114,65 @@ module Woods
       # Resolve EAV patterns against a `columns` header into concrete index
       # pairs. A rule only fires when both key_column and value_column are
       # present in the header, and costs nothing per row otherwise.
+      #
+      # A duplicated key or value header (an `AS` alias can shadow the real
+      # column — CON-1) makes index attribution ambiguous: a last-index-wins
+      # lookup would let the shadow steal the mask from the secret. The
+      # executor refuses those selects up front; here, defense-in-depth
+      # fails toward masking — every cell under a value-named header is
+      # redacted unconditionally.
       def positional_kv_rules(columns, ctx)
         return [] unless columns.is_a?(Array)
 
-        index = columns.each_with_index.to_h { |name, idx| [name.to_s, idx] }
-        ctx.redacted_key_values.filter_map do |pattern|
-          key_idx = index[pattern['key_column']]
-          val_idx = index[pattern['value_column']]
-          next unless key_idx && val_idx
+        names = columns.map(&:to_s)
+        ctx.redacted_key_values.filter_map { |pattern| positional_kv_rule(names, pattern, ctx) }
+      end
 
-          { key_idx: key_idx, val_idx: val_idx, sensitive: pattern['sensitive_keys'] }
-        end
+      # One resolved rule for one EAV pattern, or nil when the header lacks
+      # either column. Unambiguous headers get the key/value index pair;
+      # duplicated headers get the unconditional mask list.
+      def positional_kv_rule(names, pattern, ctx)
+        key_idxs = names.each_index.select { |i| names[i] == pattern['key_column'] }
+        val_idxs = names.each_index.select { |i| names[i] == pattern['value_column'] }
+        return nil if key_idxs.empty? || val_idxs.empty?
+        return { mask_idxs: val_idxs } unless key_idxs.one? && val_idxs.one?
+
+        { key_idx: key_idxs.first, val_idx: val_idxs.first,
+          key_matches: ->(value) { sensitive_key?(ctx, value, pattern) } }
+      end
+
+      def sensitive_key?(ctx, value, pattern)
+        return ctx.sensitive_key?(value, pattern) if ctx.respond_to?(:sensitive_key?)
+
+        pattern['sensitive_keys'].include?(value.to_s)
       end
 
       # Redact positional row data using a precomputed plan. Handles both
-      # nested arrays (multi-column pluck, sql/query rows) and flat scalar
-      # arrays (pluck with a single column — Rails collapses the result).
-      def redact_positional(rows, plan)
+      # nested arrays (multi-column pluck, sql/query rows) and single-column
+      # pluck values. Rails collapses the row for single-column pluck, so an
+      # Array/Hash value is still one cell and must be redacted as a whole.
+      def redact_positional(rows, plan, single_column: false)
         return rows unless rows.is_a?(Array)
         return rows if plan[:mask].nil? && plan[:kv_rules].empty?
 
         rows.map do |row|
-          row.is_a?(Array) ? redact_row(row, plan) : redact_scalar(row, plan[:mask])
+          if !single_column && row.is_a?(Array)
+            redact_row(row, plan)
+          else
+            redact_scalar(row, plan[:mask])
+          end
         end
       end
 
       def redact_row(row, plan)
         result = apply_mask(row, plan[:mask])
         plan[:kv_rules].each do |rule|
-          result[rule[:val_idx]] = '[REDACTED]' if rule[:sensitive].include?(row[rule[:key_idx]].to_s)
+          if rule[:mask_idxs]
+            # Ambiguous (duplicated) headers: mask every value-named cell.
+            rule[:mask_idxs].each { |idx| result[idx] = '[REDACTED]' }
+          elsif rule[:key_matches].call(row[rule[:key_idx]])
+            result[rule[:val_idx]] = '[REDACTED]'
+          end
         end
         result
       end

data/lib/woods/console/safe_context.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'adapter_family'
+
 # Stub for environments that don't load ActiveRecord
 unless defined?(ActiveRecord::Rollback)
   module ActiveRecord
@@ -86,7 +88,7 @@ module Woods
     #     ]
     #   )
     #
-    class SafeContext
+    class SafeContext # rubocop:disable Metrics/ClassLength
       # Thread-local key that exposes the connection currently leased for
       # the in-flight #execute block. Handlers should prefer this over
       # acquiring their own connection so every request stays on a single
@@ -183,6 +185,36 @@ module Woods
         apply_key_value_redaction(redacted)
       end
 
+      # Add runtime key types to a request-local redaction view. The original
+      # context and its execution policy are unchanged.
+      # @param types [Hash<String, Array<Object>>] Active Record attribute types
+      # @param raw [Boolean] whether keys are raw database cells
+      # @return [SafeContext]
+      def with_key_value_types(types, raw: false)
+        dup.tap do |context|
+          context.instance_variable_set(:@key_value_types, types)
+          context.instance_variable_set(:@raw_key_values, raw)
+        end
+      end
+
+      # Match the database spelling and its application representation. If a
+      # type cannot safely transform a key, protect the value rather than
+      # returning a value whose sensitivity could not be established.
+      # @param value [Object] raw or cast EAV key
+      # @param pattern [Hash] normalized EAV policy
+      # @return [Boolean]
+      def sensitive_key?(value, pattern)
+        sensitive = pattern['sensitive_keys']
+        return true if sensitive.include?(value.to_s)
+
+        Array(@key_value_types&.fetch(pattern['key_column'], nil)).any? do |type|
+          alternate = @raw_key_values ? type.deserialize(value) : type.serialize(value)
+          sensitive.include?(alternate.to_s)
+        rescue StandardError
+          true
+        end
+      end
+
       private
 
       # Wrap one connection in a rolled-back transaction with timeout, and
@@ -194,8 +226,12 @@ module Woods
         Thread.current[LEASED_CONNECTION_KEY] = connection
         result = nil
         connection.transaction do
-          set_timeout(connection)
-          result = yield(connection)
+          restore_timeout = set_timeout(connection)
+          begin
+            result = yield(connection)
+          ensure
+            restore_timeout&.call
+          end
           raise ActiveRecord::Rollback
         end
         result
@@ -225,7 +261,7 @@ module Woods
           key_col = pattern['key_column']
           val_col = pattern['value_column']
           next unless hash.key?(key_col) && hash.key?(val_col)
-          next unless pattern['sensitive_keys'].include?(hash[key_col].to_s)
+          next unless sensitive_key?(hash[key_col], pattern)
 
           hash[val_col] = '[REDACTED]'
         end
@@ -241,14 +277,16 @@ module Woods
       # request, background job, etc.). Safe here because every #execute
       # is wrapped in a transaction.
       #
-      # MySQL uses `SET max_execution_time` (applies to SELECT only — DDL
-      # and DML statements cannot be time-limited via this variable).
+      # MySQL uses session-scoped `SET max_execution_time` for SELECTs.
+      # Return a callback that restores the previous value before releasing
+      # the pooled connection; rollback alone does not reset this setting.
       def set_timeout(connection, timeout_ms = @timeout_ms)
         adapter = connection.adapter_name.downcase
-        if adapter.include?('mysql')
-          connection.execute("SET max_execution_time = #{timeout_ms.to_i}")
+        if AdapterFamily.for(connection) == :mysql
+          set_mysql_timeout(connection, timeout_ms)
         else
           connection.execute("SET LOCAL statement_timeout = '#{timeout_ms.to_i}ms'")
+          nil
         end
       rescue StandardError => e
         # Unsupported adapter (SQLite, Trilogy on unsupported version, Oracle) —
@@ -259,6 +297,16 @@ module Woods
         nil
       end
 
+      def set_mysql_timeout(connection, timeout_ms)
+        maria = connection.respond_to?(:mariadb?) && connection.mariadb?
+        variable = maria ? 'max_statement_time' : 'max_execution_time'
+        timeout = maria ? timeout_ms.to_i / 1000.0 : timeout_ms.to_i
+        previous_value = Float(connection.select_value("SELECT @@SESSION.#{variable}"))
+        connection.execute("SET #{variable} = #{timeout}")
+        previous_value = previous_value.to_i unless maria
+        -> { connection.execute("SET #{variable} = #{previous_value}") }
+      end
+
       def warn_timeout_unsupported(adapter, error)
         return unless defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
 

data/lib/woods/console/server.rb

@@ -176,7 +176,7 @@ module Woods
         # @param unsafe_eval_audit_log_path [String, Pathname, nil] JSONL audit log
         #   path for `console_eval`. Required when the opt-in is on.
         # @return [MCP::Server] Configured server ready for transport
-        def build_embedded(model_validator:, safe_context:, redacted_columns: [], # rubocop:disable Metrics/ParameterLists
+        def build_embedded(model_validator:, safe_context:, redacted_columns: [], # rubocop:disable Metrics/ParameterLists, Metrics/MethodLength
                            redacted_key_values: [], connection: nil,
                            read_tools_enabled: false, model_tables: {},
                            model_reflections: {},
@@ -201,6 +201,7 @@ module Woods
           table_gate = ctx&.table_gate
           executor = EmbeddedExecutor.new(
             model_validator: model_validator, safe_context: safe_context,
+            redaction_context: safe_ctx,
             connection: connection, read_tools_enabled: read_tools_enabled,
             table_gate: table_gate,
             eval_guard: eval_wiring[:eval_guard],

data/lib/woods/console/sql_noise_stripper.rb

@@ -30,8 +30,8 @@ module Woods
       # 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.
+      # This legacy helper is not a security scanner. Use strip_noise for
+      # quote-aware and PostgreSQL nested-comment handling.
       #
       # @param sql [String] the SQL string to process
       # @return [String] a new string with all SQL comments removed
@@ -59,9 +59,8 @@ module Woods
       #     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).
-      #   - `:sqlite` — doubled apostrophes escape strings; dollar signs stay literal.
+      #     are not recognized by the combined MySQL security scanner.
+      #   - `:sqlite` — doubled apostrophes escape strings; backslashes and dollar signs are literal.
       # @return [String] a new string with all string literals replaced by `''`
       # @raise [ArgumentError] if an unsupported dialect is provided
       DOLLAR_QUOTED = /\$(\w*)\$.*?\$\1\$/m
@@ -98,13 +97,30 @@ module Woods
       # never under-detect: an unterminated literal is treated as an ordinary
       # character rather than swallowing the rest of the statement.
       #
+      # `#` opens a MySQL line comment, mirroring `--`, but only under the
+      # `:mysql` dialect — PostgreSQL does not treat `#` as a comment, and
+      # collapsing it there would hide SQL that a real PostgreSQL server
+      # still executes. A MySQL `/*! ... */` executable comment is left
+      # visible as one span, including MariaDB's `/*M! ... */` spelling:
+      # its body can execute, so it must stay visible to every downstream
+      # scan without changing literal state outside the span. Leaving it
+      # visible under `:postgres` too is over-detection at
+      # worst, never under-detection, on a server where it really is inert.
+      # An ordinary `/* ... */` block comment is replaced by a single
+      # newline rather than vanishing outright, mirroring how a `--`/`#`
+      # line comment's own trailing newline survives: SqlValidator's
+      # statement-leader scan needs a durable marker showing a comment sat
+      # here so a comment-hidden statement (`SELECT 1 /*;*/ DELETE ...`)
+      # still reads as following a boundary once comments are gone.
+      #
       # @param sql [String] the SQL string to process
       # @param dialect [Symbol] `:postgres` (default), `:mysql`, or `:sqlite` — controls
-      #   single-quote escape rules (see {.strip_literals}).
+      #   single-quote escape rules (see {.strip_literals}) and whether `#`
+      #   opens a line comment. MySQL quote flags reflect session sql_mode.
       # @return [String] a new string with comments removed and every string
       #   literal replaced by `''`
       # @raise [ArgumentError] if an unsupported dialect is provided
-      def self.strip_noise(sql, dialect: :postgres) # rubocop:disable Metrics/MethodLength,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity,Metrics/AbcSize
+      def self.strip_noise(sql, dialect: :postgres, ansi_quotes: false, no_backslash_escapes: false) # rubocop:disable Metrics/MethodLength,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity,Metrics/AbcSize
         unless SUPPORTED_DIALECTS.include?(dialect)
           raise ArgumentError, "Unknown dialect #{dialect.inspect}. Supported: #{SUPPORTED_DIALECTS.inspect}"
         end
@@ -118,7 +134,11 @@ module Woods
           ch = sql[i]
 
           if ch == "'"
-            close = single_quote_end(sql, i, mysql: mysql)
+            close = single_quote_end(
+              sql, i,
+              backslash_escapes: (mysql && !no_backslash_escapes) ||
+                (dialect == :postgres && postgres_escape_string?(sql, i))
+            )
             if close
               out << "''"
               i = close
@@ -127,16 +147,33 @@ module Woods
               out << ch
               i += 1
             end
-          elsif ['"', '`'].include?(ch)
-            close = quoted_identifier_end(sql, i, ch)
+          elsif ch == '"'
+            close = quoted_span_end(sql, i, quote: '"',
+                                            backslash_escapes: mysql && !ansi_quotes && !no_backslash_escapes)
             if close
+              # MySQL parses double quotes as strings unless ANSI_QUOTES is
+              # enabled. Treating them as literals prevents a `#` inside the
+              # value from hiding live SQL. PostgreSQL uses them for
+              # identifiers, which must remain visible to table/column scans.
+              out << double_quote_replacement(sql, i, close, mysql: mysql && !ansi_quotes)
+              i = close
+            else
+              out << ch
+              i += 1
+            end
+          elsif (mysql || dialect == :sqlite) && ch == '`'
+            close = quoted_span_end(sql, i, quote: '`', backslash_escapes: false)
+            if close
+              # Backticks delimit identifiers. Preserve the token for table
+              # and protected-column scans while shielding comment markers
+              # inside it from the noise scanner.
               out << sql[i...close]
               i = close
             else
               out << ch
               i += 1
             end
-          elsif dialect != :sqlite && ch == '$' && (tag = dollar_tag_at(sql, i))
+          elsif dialect == :postgres && ch == '$' && !preceded_by_word_char?(sql, i) && (tag = dollar_tag_at(sql, i))
             close = sql.index(tag, i + tag.length)
             if close
               out << "''"
@@ -145,14 +182,33 @@ module Woods
               out << ch
               i += 1
             end
-          elsif ch == '-' && sql[i + 1] == '-'
+          elsif dash_comment?(sql, i, mysql: mysql) || (mysql && ch == '#')
             nl = sql.index("\n", i)
             i = nl || len
+          elsif sql[i, 3] == '/*!' || sql[i, 4] == '/*M!'
+            close = block_comment_end(sql, i, nested: dialect == :postgres)
+            if close
+              comment = sql[i...close]
+              yield comment if block_given?
+              # An executable comment is a lexical boundary even when its
+              # version guard makes its body inert. A quote in that body must
+              # never change the scanner's state outside the comment.
+              out << comment
+              i = close
+            else
+              out << ch
+              i += 1
+            end
           elsif ch == '/' && sql[i + 1] == '*'
-            close = sql.index('*/', i + 2)
+            close = block_comment_end(sql, i, nested: dialect == :postgres)
             if close
-              out << ' '
-              i = close + 2
+              # Preserve a newline in place of the removed comment, mirroring
+              # line comments (see class docs): callers that check for
+              # statement structure (SqlValidator's statement-leader scan)
+              # need a survivable marker showing a comment sat here, the
+              # same way a `--`/`#` comment's own trailing newline does.
+              out << "\n"
+              i = close
             else
               # Unterminated block comment: never under-detect. Leave it in
               # place (over-detection is safe; the old regex also required a
@@ -169,26 +225,42 @@ module Woods
         out
       end
 
-      # Preserve quoted identifiers while shielding their comment markers.
-      # @api private
-      def self.quoted_identifier_end(sql, start, quote)
-        i = start + 1
-        while i < sql.length
-          if sql[i] == quote
-            return i + 1 unless sql[i + 1] == quote
+      def self.block_comment_end(sql, start, nested:)
+        depth = 1
+        position = start + 2
+        while (match = %r{/\*|\*/}.match(sql, position))
+          depth += 1 if nested && match[0] == '/*'
+          depth -= 1 if match[0] == '*/'
+          return match.end(0) if depth.zero?
 
-            i += 2
-          else
-            i += 1
-          end
+          position = match.end(0)
         end
         nil
       end
-      private_class_method :quoted_identifier_end
+      private_class_method :block_comment_end
+
+      # Session modes change MySQL quoting without changing the adapter name.
+      # Security consumers must reject SQL unsafe under any supported combination.
+      MYSQL_QUOTE_MODES = [false, true].product([false, true]).map do |ansi, no_backslash|
+        { ansi_quotes: ansi, no_backslash_escapes: no_backslash }.freeze
+      end.freeze
+
+      def self.security_views(sql, dialect:, mysql_modes: nil)
+        modes = dialect == :mysql && mysql_modes.nil? ? MYSQL_QUOTE_MODES : [mysql_modes || {}]
+        modes.map { |mode| strip_noise(sql, dialect: dialect, **mode) }.uniq
+      end
+
+      # MySQL requires whitespace/control after --; otherwise it is subtraction.
+      def self.dash_comment?(sql, index, mysql:)
+        return false unless sql[index, 2] == '--'
+
+        !mysql || sql[index + 2].nil? || sql[index + 2].match?(/[[:space:][:cntrl:]]/)
+      end
+      private_class_method :dash_comment?
 
       # Regexp matching a PostgreSQL dollar-quote opening tag (`$$` or
       # `$tag$`) at the start of the given slice.
-      DOLLAR_TAG = /\A\$\w*\$/
+      DOLLAR_TAG = /\A\$(?:[A-Za-z_\u0080-\u{10ffff}][A-Za-z0-9_\u0080-\u{10ffff}]*)?\$/u
       private_constant :DOLLAR_TAG
 
       # Return the dollar-quote tag opening at +index+, or nil.
@@ -200,29 +272,69 @@ module Woods
       end
       private_class_method :dollar_tag_at
 
+      # Whether the character immediately before +index+ is a word character
+      # (including high-bit characters). PostgreSQL allows `$` inside identifiers (`x$a$`), so a `$`
+      # is only a candidate dollar-quote opener when it does NOT follow an
+      # identifier character — otherwise `x$a$ FROM blocked, (SELECT 1 AS
+      # z$a$)` gets misread as one dollar-quoted literal spanning the real
+      # FROM clause.
+      #
+      # @api private
+      def self.preceded_by_word_char?(sql, index)
+        index.positive? && sql[index - 1].match?(/[A-Za-z0-9_$\u0080-\u{10ffff}]/u)
+      end
+      private_class_method :preceded_by_word_char?
+
       # Return the index just past the closing quote of the single-quoted
       # literal that opens at +start+, honoring `''` (both dialects) and `\'`
       # (MySQL only) escapes. Returns nil when the literal is unterminated.
       #
       # @api private
-      def self.single_quote_end(sql, start, mysql:)
+      def self.single_quote_end(sql, start, backslash_escapes:)
+        quoted_span_end(sql, start, quote: "'", backslash_escapes: backslash_escapes)
+      end
+      private_class_method :single_quote_end
+
+      def self.double_quote_replacement(sql, start, close, mysql:)
+        mysql ? "''" : sql[start...close]
+      end
+      private_class_method :double_quote_replacement
+
+      # Return the index just past a quoted span. Doubled delimiters escape
+      # themselves in every supported dialect; MySQL strings/identifiers and
+      # PostgreSQL E-strings additionally honor backslash escapes.
+      #
+      # @api private
+      def self.quoted_span_end(sql, start, quote:, backslash_escapes:)
         i = start + 1
         len = sql.length
         while i < len
           c = sql[i]
-          if mysql && c == '\\'
+          if backslash_escapes && c == '\\'
             i += 2
-          elsif c == "'"
-            return i + 1 unless sql[i + 1] == "'" # closing quote
+          elsif c == quote
+            return i + 1 unless sql[i + 1] == quote # closing delimiter
 
-            i += 2 # doubled-quote escape — literal continues
+            i += 2 # doubled-delimiter escape — span continues
           else
             i += 1
           end
         end
         nil
       end
-      private_class_method :single_quote_end
-    end
+      private_class_method :quoted_span_end
+
+      # PostgreSQL E'...' strings opt into C-style backslash escapes. The E
+      # must begin a token; an identifier ending in e immediately before a
+      # quote is not an escape-string prefix.
+      #
+      # @api private
+      def self.postgres_escape_string?(sql, quote_index)
+        return false unless quote_index.positive? && sql[quote_index - 1].match?(/[eE]/)
+
+        quote_index < 2 || !sql[quote_index - 2].match?(/[A-Za-z0-9_$\u0080-\u{10ffff}]/u)
+      end
+      private_class_method :postgres_escape_string?
+    end # rubocop:enable Metrics/ModuleLength
   end
 end