woods 2.0.0 → 2.1.0

data/lib/woods/console/rack_middleware.rb

@@ -2,6 +2,8 @@
 
 require 'json'
 require 'woods/observability/structured_logger'
+require 'woods/mcp/bearer_auth'
+require 'woods/mcp/origin_guard'
 
 module Woods
   module Console
@@ -13,9 +15,10 @@ module Woods
     #
     # == Basic setup (Tier 1 tools only)
     #
-    # Add to config/application.rb or an initializer:
+    # The Woods railtie mounts this middleware automatically. Configure the
+    # path in config/application.rb before Rails constructs its middleware:
     #
-    #   config.middleware.use Woods::Console::RackMiddleware, path: '/mcp/console'
+    #   Woods.configure { |config| config.console_mcp_path = '/mcp/console' }
     #
     # This mounts the 9 executable Tier 1 tools at /mcp/console. Explicit
     # read-tool mode registers console_sql and console_query as well.
@@ -26,6 +29,7 @@ module Woods
     #
     #   Woods.configure do |config|
     #     config.console_mcp_enabled = true
+    #     config.console_mcp_token = ENV.fetch('WOODS_CONSOLE_MCP_TOKEN')
     #     config.console_blocked_tables = %w[authorizations credentials]
     #     config.console_redacted_columns = %w[api_token password_digest]
     #   end
@@ -39,13 +43,14 @@ module Woods
     #
     # == Enabling read tools (console_sql + console_query)
     #
-    # Set embedded_read_tools: true to unlock the sql and query tools:
+    # Set console_embedded_read_tools to unlock the sql and query tools:
     #
     #   # config/initializers/woods_console.rb
-    #   Rails.application.config.middleware.use \
-    #     Woods::Console::RackMiddleware,
-    #     path: '/mcp/console',
-    #     embedded_read_tools: true
+    #   Woods.configure { |config| config.console_embedded_read_tools = true }
+    #
+    # Legacy manual mounts remain guarded: each instance enforces the configured
+    # bearer token and origin policy before building or dispatching the server,
+    # even when it appears before the railtie's outer HTTP guards.
     #
     # Security posture with embedded_read_tools: true:
     #
@@ -68,6 +73,12 @@ module Woods
     # disabled when the host requires a narrower database capability.
     #
     class RackMiddleware # rubocop:disable Metrics/ClassLength
+      EAGER_LOAD_UNAVAILABLE = JSON.generate(
+        jsonrpc: '2.0', id: nil,
+        error: { code: -32_000,
+                 message: 'Console unavailable: Rails eager loading failed. ' \
+                          'Fix the application load error and restart the server.' }
+      ).freeze
       # @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, #call] Enable sql/query tools in
@@ -106,14 +117,23 @@ module Woods
         return @app.call(env) unless env['PATH_INFO'].to_s.start_with?(@path)
         return @app.call(env) unless enabled?
 
+        @guarded_request.call(env)
+      end
+
+      private
+
+      def handle_request(env)
         transport = ensure_transport
+        unless transport
+          return [503, { 'content-type' => 'application/json', 'cache-control' => 'no-store' },
+                  [EAGER_LOAD_UNAVAILABLE]]
+        end
+
         request_env = env.dup
         request_env.delete('HTTP_MCP_SESSION_ID') if @stateless_mode
         transport.handle_request(Rack::Request.new(request_env))
       end
 
-      private
-
       def initialize_options(app, path: '/mcp/console', embedded_read_tools: false, # rubocop:disable Metrics/ParameterLists
                              unsafe_eval_confirmation: nil, unsafe_eval_audit_log_path: nil,
                              stateless: true)
@@ -125,6 +145,26 @@ module Woods
         @stateless = stateless
         @mutex = Mutex.new
         @transport = nil
+        @guarded_request = guarded_request
+        validate_origin_configuration! if enabled?
+      end
+
+      def validate_origin_configuration!
+        @origin_guard.policy
+      rescue ArgumentError => e
+        raise Woods::ConfigurationError, "[Woods Console] #{e.message}"
+      end
+
+      # Every entry point owns its guards; an earlier manual mount cannot rely
+      # on middleware later in the Rails stack. Resolve configuration lazily
+      # so settings from application initializers and token rotation apply.
+      def guarded_request
+        authenticated = Woods::MCP::BearerAuth.new(
+          method(:handle_request), token: -> { Woods.configuration&.console_mcp_token }
+        )
+        @origin_guard = Woods::MCP::OriginGuard.new(
+          authenticated, allowed_origins: -> { Array(Woods.configuration&.console_mcp_allowed_origins) }
+        )
       end
 
       # Whether the console is enabled, read from the live configuration on
@@ -139,25 +179,42 @@ module Woods
       # @return [::MCP::Server::Transports::StreamableHTTPTransport]
       def ensure_transport
         return @transport if @transport
+        return if @eager_load_failed
 
         @mutex.synchronize do
           return @transport if @transport
+          return if @eager_load_failed
 
           check_blocked_tables_config!
 
           require 'woods/console/server'
-          Rails.application.eager_load!
+          return unless eager_load_application
 
           server = build_embedded_server
           @stateless_mode = resolve_deferred(@stateless)
           @transport = ::MCP::Server::Transports::StreamableHTTPTransport.new(
-            server, stateless: @stateless_mode
+            server, stateless: @stateless_mode, **@origin_guard.policy.transport_options
           )
           server.transport = @transport
           @transport
         end
       end
 
+      # A failed loader may have registered only part of the application.
+      # Keep this worker unavailable rather than retrying against partial state.
+      def eager_load_application
+        Rails.application.eager_load!
+        true
+      rescue NameError => e
+        @eager_load_failed = true
+        structured_logger.error(
+          'console.eager_load.failed', error_class: e.class.name,
+                                       remediation: 'Run Rails.application.eager_load! in the application ' \
+                                                    'environment; fix the error and restart.'
+        )
+        false
+      end
+
       # Emit a prominent warning (or raise in production) when the Console MCP
       # is enabled but no tables are blocked. An empty block list means Layer 1
       # of the defense stack is fully inactive — every table in the database is

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
 
@@ -123,30 +125,42 @@ module Woods
         return [] unless columns.is_a?(Array)
 
         names = columns.map(&:to_s)
-        ctx.redacted_key_values.filter_map { |pattern| positional_kv_rule(names, pattern) }
+        ctx.redacted_key_values.filter_map { |pattern| positional_kv_rule(names, pattern, ctx) }
       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)
+      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, sensitive: pattern['sensitive_keys'] }
+        { 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
 
@@ -156,7 +170,7 @@ module Woods
           if rule[:mask_idxs]
             # Ambiguous (duplicated) headers: mask every value-named cell.
             rule[:mask_idxs].each { |idx| result[idx] = '[REDACTED]' }
-          elsif rule[:sensitive].include?(row[rule[:key_idx]].to_s)
+          elsif rule[:key_matches].call(row[rule[:key_idx]])
             result[rule[:val_idx]] = '[REDACTED]'
           end
         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
@@ -203,6 +205,36 @@ module Woods
                         redacted_columns: policy_columns, redacted_key_values: policy_key_values)
       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
@@ -249,7 +281,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
@@ -279,14 +311,14 @@ module Woods
       #   unsupported adapter sets nothing to restore).
       def set_timeout(connection, timeout_ms = @timeout_ms)
         adapter = connection.adapter_name.downcase
-        if adapter.include?('mysql')
+        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) —
+        # Unsupported timeout facility (for example SQLite or older servers) —
         # timeout enforcement is best-effort, but operators need to know their
         # rollback fence is narrower than advertised. Log once per adapter via
         # Rails.logger when available; otherwise swallow as before.
@@ -295,16 +327,21 @@ module Woods
       end
 
       # Read MySQL's current session-scoped `max_execution_time`, override
-      # it, and return a Proc that restores the value read here. There is no
+      # it, and return a Proc that restores the value read here. MariaDB uses
+      # max_statement_time in seconds; MySQL uses milliseconds. There is no
       # per-statement `SET LOCAL` on MySQL, so the override otherwise
       # outlives this transaction's rollback and bleeds onto whatever the
       # pooled connection serves next.
       #
       # @return [Proc] restores the previous session value
       def set_mysql_timeout(connection, timeout_ms)
-        previous_value = connection.select_value('SELECT @@SESSION.max_execution_time').to_i
-        connection.execute("SET max_execution_time = #{timeout_ms.to_i}")
-        -> { connection.execute("SET max_execution_time = #{previous_value}") }
+        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)

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
@@ -101,9 +101,10 @@ module Woods
       # `: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
-      # untouched (not treated as a comment at all, under either dialect):
-      # MySQL runs its body, so it must stay visible to every downstream
-      # scan; leaving it visible under `:postgres` too is over-detection at
+      # 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 `--`/`#`
@@ -184,8 +185,22 @@ module Woods
           elsif dash_comment?(sql, i, mysql: mysql) || (mysql && ch == '#')
             nl = sql.index("\n", i)
             i = nl || len
-          elsif ch == '/' && sql[i + 1] == '*' && sql[i + 2] != '!'
-            close = sql.index('*/', i + 2)
+          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 = block_comment_end(sql, i, nested: dialect == :postgres)
             if close
               # Preserve a newline in place of the removed comment, mirroring
               # line comments (see class docs): callers that check for
@@ -193,7 +208,7 @@ module Woods
               # need a survivable marker showing a comment sat here, the
               # same way a `--`/`#` comment's own trailing newline does.
               out << "\n"
-              i = close + 2
+              i = close
             else
               # Unterminated block comment: never under-detect. Leave it in
               # place (over-detection is safe; the old regex also required a
@@ -210,6 +225,20 @@ module Woods
         out
       end
 
+      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?
+
+          position = match.end(0)
+        end
+        nil
+      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|
@@ -231,7 +260,7 @@ module Woods
 
       # 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.
@@ -244,7 +273,7 @@ module Woods
       private_class_method :dollar_tag_at
 
       # Whether the character immediately before +index+ is a word character
-      # (`\w`). PostgreSQL allows `$` inside identifiers (`x$a$`), so a `$`
+      # (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
@@ -252,7 +281,7 @@ module Woods
       #
       # @api private
       def self.preceded_by_word_char?(sql, index)
-        index.positive? && sql[index - 1].match?(/\w/)
+        index.positive? && sql[index - 1].match?(/[A-Za-z0-9_$\u0080-\u{10ffff}]/u)
       end
       private_class_method :preceded_by_word_char?
 
@@ -303,7 +332,7 @@ module Woods
       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_$]/)
+        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

data/lib/woods/console/sql_table_scanner.rb

@@ -38,20 +38,20 @@ module Woods
       # 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+)?
+        \b(?:STRAIGHT_)?JOIN(?=[\s("`])\s*
+        (?:ONLY(?=[\s("`])\s*\(?\s*)?
         (?:
           (?:
-            `(?<jschema_bt>[^`]+)` |
-            "(?<jschema_dq>[^"]+)" |
-            (?<jschema_bare>\w+)
+            `(?<jschema_bt>(?:``|[^`])+)` |
+            "(?<jschema_dq>(?:""|[^"])+)" |
+            (?<jschema_bare>[A-Za-z0-9_$\u0080-\u{10ffff}]+)
           )
           \s* \. \s*
         )?
         (?:
-          `(?<backtick>[^`]+)` |
-          "(?<double>[^"]+)"   |
-          (?<bare>\w+(?:\.\w+)?)
+          `(?<backtick>(?:``|[^`])+)` |
+          "(?<double>(?:""|[^"])+)"   |
+          (?<bare>[A-Za-z0-9_$\u0080-\u{10ffff}]+(?:\.[A-Za-z0-9_$\u0080-\u{10ffff}]+)?)
         )
       /xi
 
@@ -66,7 +66,7 @@ module Woods
       # every `FROM` as its own independent scan match is what keeps CTEs,
       # UNIONs, and nested subqueries in coverage.
       FROM_CLAUSE = /
-        \bFROM\s+
+        \bFROM(?=[\s("`])\s*
         (?<clause>.+?)
         (?=
           \b(?:WHERE|GROUP|HAVING|ORDER|LIMIT|OFFSET|UNION|INTERSECT|EXCEPT|
@@ -85,16 +85,16 @@ module Woods
         \A
         (?:
           (?:
-            `(?<schema_bt>[^`]+)` |
-            "(?<schema_dq>[^"]+)" |
-            (?<schema_bare>\w+)
+            `(?<schema_bt>(?:``|[^`])+)` |
+            "(?<schema_dq>(?:""|[^"])+)" |
+            (?<schema_bare>[A-Za-z0-9_$\u0080-\u{10ffff}]+)
           )
           \s* \. \s*
         )?
         (?:
-          `(?<backtick>[^`]+)` |
-          "(?<double>[^"]+)"   |
-          (?<bare>\w+(?:\.\w+)?)
+          `(?<backtick>(?:``|[^`])+)` |
+          "(?<double>(?:""|[^"])+)"   |
+          (?<bare>[A-Za-z0-9_$\u0080-\u{10ffff}]+(?:\.[A-Za-z0-9_$\u0080-\u{10ffff}]+)?)
         )
       /xi
 
@@ -102,7 +102,7 @@ module Woods
       # 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
+      ONLY_PREFIX = /\AONLY(?=[\s("`])\s*/i
 
       # Matches a MySQL executable comment (`/*!...*/` or the version-guarded
       # `/*!NNNNN...*/`), capturing the body. Mirrors
@@ -110,7 +110,7 @@ module Woods
       # deliberately leaves these markers in place because their meaning is
       # version-dependent; .executable_comment_views scans both of their
       # possible semantics.
-      EXECUTABLE_COMMENT_PATTERN = %r{/\*!(?:\d{5})?(.*?)\*/}m
+      EXECUTABLE_COMMENT_PATTERN = %r{/\*(?:M)?!(?:\d{5,6})?(.*?)\*/}m
 
       # Matches the standalone SQL `TABLE name` statement (PostgreSQL, and
       # MySQL 8.0.19+) — shorthand for `SELECT * FROM name`. It appears as a
@@ -119,20 +119,20 @@ module Woods
       # scanned independently of FROM_CLAUSE/JOIN_REFERENCE rather than as
       # part of either. The identifier grammar mirrors LEAD_IDENT.
       TABLE_STATEMENT = /
-        \bTABLE\s+
-        (?:ONLY\s+)?
+        \bTABLE(?=[\s("`])\s*
+        (?:ONLY(?=[\s("`])\s*\(?\s*)?
         (?:
           (?:
-            `(?<schema_bt>[^`]+)` |
-            "(?<schema_dq>[^"]+)" |
-            (?<schema_bare>\w+)
+            `(?<schema_bt>(?:``|[^`])+)` |
+            "(?<schema_dq>(?:""|[^"])+)" |
+            (?<schema_bare>[A-Za-z0-9_$\u0080-\u{10ffff}]+)
           )
           \s* \. \s*
         )?
         (?:
-          `(?<backtick>[^`]+)` |
-          "(?<double>[^"]+)"   |
-          (?<bare>\w+(?:\.\w+)?)
+          `(?<backtick>(?:``|[^`])+)` |
+          "(?<double>(?:""|[^"])+)"   |
+          (?<bare>[A-Za-z0-9_$\u0080-\u{10ffff}]+(?:\.[A-Za-z0-9_$\u0080-\u{10ffff}]+)?)
         )
       /xi
 
@@ -169,10 +169,12 @@ module Woods
 
       # Table-factor prefixes, retaining commas after balanced subqueries and
       # JOIN predicates. Each nested FROM/JOIN is also scanned independently.
+      # SQL punctuation separates tokens without mandatory whitespace. Keep
+      # compact quoted targets and parenthesized relations in the same policy.
       # @param sql [String] noise-stripped SQL
       # @return [Array<String>]
       def self.relation_factors(sql)
-        sql.to_enum(:scan, /\b(?:FROM|JOIN)\s+/i).flat_map do
+        sql.to_enum(:scan, /\b(?:FROM|(?:STRAIGHT_)?JOIN)(?=[\s("`])\s*/i).flat_map do
           suffix = sql[Regexp.last_match.end(0)..]
           split_top_level_commas(relation_clause(suffix))
         end
@@ -204,7 +206,7 @@ module Woods
         return false unless token.match?(/\A[A-Za-z]/)
         return false if prefix.strip.empty? || prefix.match?(/(?:,|\bAS)\s*\z/i) || rest.lstrip.start_with?(',')
         return rest.match?(/\A\s+BY\b/i) if %w[GROUP ORDER].include?(token.upcase)
-        return rest.match?(/\A\s+\w+\s+AS\b/i) if token.casecmp?('WINDOW')
+        return rest.match?(/\A\s+[A-Za-z0-9_$\u0080-\u{10ffff}]+\s+AS\b/i) if token.casecmp?('WINDOW')
 
         true
       end
@@ -299,8 +301,9 @@ module Woods
       # 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?
+        stripped = chunk.to_s.strip.sub(/\A(?:\(\s*)+/, '').sub(ONLY_PREFIX, '')
+        stripped = stripped.sub(/\A(?:\(\s*)+/, '')
+        return nil if stripped.empty? || stripped.match?(/\A(?:SELECT|WITH|TABLE)\b/i)
 
         match = LEAD_IDENT.match(stripped)
         return nil unless match
@@ -313,14 +316,22 @@ module Woods
       # 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
+        captures = match.named_captures
+        table = decoded_identifier(*captures.values_at('backtick', 'double', 'bare'))
+        schema = decoded_identifier(captures['schema_bt'] || captures['jschema_bt'],
+                                    captures['schema_dq'] || captures['jschema_dq'],
+                                    captures['schema_bare'] || captures['jschema_bare'])
         schema ? "#{schema}.#{table}" : table
       end
       private_class_method :qualified_identifier
+
+      def self.decoded_identifier(backtick, double, bare)
+        return backtick.gsub('``', '`') if backtick
+        return double.gsub('""', '"') if double
+
+        bare
+      end
+      private_class_method :decoded_identifier
     end
   end
 end