woods 1.1.0 → 1.3.0

data/lib/woods/console/redactor.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module Woods
+  module Console
+    # Shape-aware Layer 3 (column + EAV) redaction for console tool responses.
+    #
+    # Extracted from {Server} so the response-redaction logic can live next to
+    # the {ResponseContext} that invokes it and be unit-tested without the
+    # full server construction path.
+    #
+    # Redaction is shape-aware:
+    #   - {record: Hash}                        (find)
+    #   - {records: [Hash]}                     (sample, recent)
+    #   - {columns: [...], rows: [[...]]}       (sql, query)
+    #   - {columns: [...], values: [...|[...]]} (pluck)
+    #   - Plain Hash                            (redact top-level keys)
+    #   - Array<Hash>                           (redact each hash)
+    module Redactor
+      # Data-shape keys used by console tool responses. When any of these keys
+      # appear at the top of a Hash result we treat the value as row data and
+      # descend into it instead of redacting at the envelope level.
+      #
+      # Full recursive descent is intentionally NOT used here. Some tools return
+      # Hashes whose keys happen to be column names but whose values are metadata
+      # objects, not row data — e.g. `console_schema` returns
+      # {columns: {col_name => {type:..., null:...}}}. Recursing into that Hash
+      # would incorrectly replace schema metadata with "[REDACTED]" whenever a
+      # column name matches a redacted_columns entry. Keeping a closed list of
+      # envelope keys that carry actual row data is therefore the safer choice.
+      #
+      # When adding a new Tier 2/3 tool that returns row data under a new envelope
+      # key, add that key here AND add a matching `when` branch in
+      # `redact_envelope_value` that applies the appropriate redaction strategy.
+      DATA_ENVELOPE_KEYS = %w[record records rows values associations].freeze
+
+      module_function
+
+      # Apply SafeContext column redaction to a result value.
+      #
+      # @param result [Object] The result from the bridge or embedded executor
+      # @param ctx [SafeContext] The context with redacted_columns configured
+      # @return [Object] Redacted result, same shape as input
+      def apply(result, ctx)
+        case result
+        when Array
+          result.map { |item| item.is_a?(Hash) ? apply(item, ctx) : item }
+        when Hash
+          redact_hash(result, ctx)
+        else
+          result
+        end
+      end
+
+      def redact_hash(hash, ctx)
+        string_keyed = hash.transform_keys(&:to_s)
+        return ctx.redact(string_keyed) unless (string_keyed.keys & DATA_ENVELOPE_KEYS).any?
+
+        plan = positional_plan(string_keyed['columns'], ctx)
+        string_keyed.each_with_object({}) do |(key, value), out|
+          out[key] = redact_envelope_value(key, value, plan, ctx)
+        end
+      end
+
+      def redact_envelope_value(key, value, plan, ctx)
+        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 'associations'   then redact_association_map(value, ctx)
+        else                       value
+        end
+      end
+
+      def redact_hash_array(value, ctx)
+        Array(value).map { |row| row.is_a?(Hash) ? ctx.redact(row) : row }
+      end
+
+      # Redact an associations map returned by console_data_snapshot.
+      #
+      # The associations payload has the shape:
+      #   { "assoc_name" => [Hash, ...], ... }
+      # Each value is an Array of record Hashes. We redact each record
+      # the same way we handle `records` (column-name + EAV rules).
+      def redact_association_map(value, ctx)
+        return value unless value.is_a?(Hash)
+
+        value.each_with_object({}) do |(assoc_name, assoc_records), out|
+          out[assoc_name] = redact_hash_array(assoc_records, ctx)
+        end
+      end
+
+      # Precompute everything needed to redact positional rows for a given
+      # `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),
+          kv_rules: positional_kv_rules(columns, ctx) }
+      end
+
+      # Precompute the positional redaction mask from a `columns` header.
+      # Returns nil when there is nothing to redact so callers can short-circuit.
+      def positional_mask(columns, ctx)
+        return nil unless columns.is_a?(Array)
+
+        redacted = ctx.redacted_columns
+        return nil if redacted.empty?
+
+        mask = columns.map { |name| redacted.include?(name.to_s) }
+        mask.any? ? mask : nil
+      end
+
+      # 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.
+      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
+
+          { key_idx: key_idx, val_idx: val_idx, sensitive: pattern['sensitive_keys'] }
+        end
+      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)
+        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])
+        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)
+        end
+        result
+      end
+
+      def apply_mask(row, mask)
+        return row.dup unless mask
+
+        row.each_with_index.map { |value, idx| mask[idx] ? '[REDACTED]' : value }
+      end
+
+      def redact_scalar(value, mask)
+        return value unless mask
+
+        mask.first ? '[REDACTED]' : value
+      end
+    end
+  end
+end

data/lib/woods/console/response_context.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require 'singleton'
+require_relative 'redactor'
+
+module Woods
+  module Console
+    # Bundles the three Console response-safety layers the Server threads
+    # through every tool definition:
+    #
+    # - Layer 1 (TableGate)          — reject tool calls that touch blocked tables.
+    # - Layer 2 (CredentialScanner)  — redact credential-shaped substrings in the
+    #                                  final response tree, regardless of where they arrived.
+    # - Layer 3 (SafeContext)        — operator-configured column + EAV redaction.
+    #
+    # Exposed as tell-don't-ask commands: {#enforce!}, {#redact}, {#scan}. Callers
+    # never need to ask which layers are configured — a {NullResponseContext} is
+    # returned from {.build} when every layer is absent, and its commands are
+    # no-ops that return their input unchanged.
+    #
+    # Ordering (applied in Server#send_to_bridge, after the bridge responds):
+    #   Layer 3 (columns/EAV) -> Layer 2 (credential scan) -> response emitted.
+    # Layer 1 runs earlier, before tool dispatch.
+    class ResponseContext
+      attr_reader :safe_ctx, :table_gate, :credential_scanner
+
+      # @return [ResponseContext, NullResponseContext] NullResponseContext
+      #   when every layer is absent so callers never receive nil.
+      def self.build(safe_ctx: nil, table_gate: nil, credential_scanner: nil)
+        gate_inactive = table_gate.nil? || !table_gate.active?
+        if safe_ctx.nil? && gate_inactive && credential_scanner.nil?
+          NullResponseContext.instance
+        else
+          new(safe_ctx: safe_ctx, table_gate: table_gate, credential_scanner: credential_scanner)
+        end
+      end
+
+      def initialize(safe_ctx:, table_gate:, credential_scanner:)
+        @safe_ctx = safe_ctx
+        @table_gate = table_gate
+        @credential_scanner = credential_scanner
+      end
+
+      # True for real response contexts; false for {NullResponseContext}.
+      def present?
+        true
+      end
+
+      # Run the Layer 1 blocked-table gate against the arguments a tool was
+      # invoked with. Tools may arrive at tables through five different
+      # arg shapes — SQL string, model name, raw table, joined associations,
+      # or a single association name — so the gate checks every variant that's
+      # present. A no-op when the gate is nil.
+      #
+      # @param args [Hash] Tool arguments (symbol keys from MCP dispatch)
+      # @raise [TableGateError] if any referenced identifier is blocked
+      def enforce!(args) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+        return unless @table_gate
+
+        @table_gate.check_sql!(args[:sql]) if args[:sql]
+        @table_gate.check_model!(args[:model]) if args[:model]
+        @table_gate.check_table!(args[:table]) if args[:table]
+        @table_gate.check_joins!(args[:model], args[:joins]) if args[:model] && args[:joins]
+        return unless args[:model] && args[:association]
+
+        @table_gate.check_association!(args[:model], args[:association])
+      end
+
+      # Apply Layer 3 (column + EAV) redaction to a result value. Shape-aware —
+      # see {Redactor.apply} for the supported envelope keys.
+      #
+      # @param result [Object]
+      # @return [Object] Redacted result, same shape as input.
+      def redact(result)
+        return result unless @safe_ctx
+
+        Redactor.apply(result, @safe_ctx)
+      end
+
+      # Run Layer 2 (credential scanner) over a value and return the scanned
+      # form alongside any hit counts. Callers decide whether to log the
+      # counts — the context deliberately does not assume access to a logger.
+      #
+      # @param value [Object]
+      # @return [Array(Object, Hash)] [scanned_value, counts_by_pattern]
+      def scan(value)
+        return [value, {}] unless @credential_scanner
+
+        @credential_scanner.scan(value)
+      end
+    end
+
+    # Null variant returned by {ResponseContext.build} when every layer is
+    # absent. Exposes the same public surface so callers never need &.nil-guards.
+    class NullResponseContext
+      include Singleton
+
+      def present?
+        false
+      end
+
+      def safe_ctx
+        nil
+      end
+
+      def table_gate
+        nil
+      end
+
+      def credential_scanner
+        nil
+      end
+
+      def enforce!(_args)
+        nil
+      end
+
+      def redact(result)
+        result
+      end
+
+      def scan(value)
+        [value, {}]
+      end
+    end
+  end
+end

data/lib/woods/console/safe_context.rb

@@ -13,70 +13,267 @@ module Woods
     #
     # Safety layers:
     # - Every query runs inside a transaction that is always rolled back
-    # - Statement timeout prevents runaway queries
+    # - Statement timeout uses `SET LOCAL` so it cannot leak to the next
+    #   pool consumer
     # - Column redaction replaces sensitive values with "[REDACTED]"
     #
-    # @example
+    # == What SafeContext does NOT cover
+    #
+    # The rolled-back transaction is a strong guardrail but not absolute.
+    # Known escape paths — callers of {#execute} should assume anything
+    # below is effectively live:
+    # - `ActiveJob` / `ActionMailer` async deliveries. Earlier versions
+    #   tried to swap the global queue_adapter/delivery_method to `:test`
+    #   for the block's duration, but those settings are process-wide
+    #   class state: in a Puma worker serving both the host app and the
+    #   Console MCP, a concurrent host request would briefly see the
+    #   test adapter and silently drop real jobs / mail. We now leave
+    #   them alone — treat callback-triggered enqueues / deliveries as
+    #   live.
+    # - `after_rollback` callbacks (fire on rollback, can still enqueue
+    #   jobs or call external services).
+    # - `Thread.new` / `Fiber.new` inside the block — they lease a fresh
+    #   connection outside the transaction.
+    # - Direct HTTP egress (Net::HTTP, Faraday, HTTP gem, ...).
+    # - File I/O / shell-outs initiated from within AR callbacks.
+    # - Writes through a different pool or shard than the one this
+    #   SafeContext was built with.
+    # - `raw_connection.execute` on some adapters when the adapter's
+    #   transaction bookkeeping is out-of-band.
+    #
+    # Treat SafeContext as "rolls back the database", not "prevents every
+    # side effect" — operators must still apply the upstream defenses
+    # (TableGate, SqlValidator, EvalGuard, BearerAuth).
+    #
+    # Two construction modes are supported:
+    #
+    # - `connection:` — wraps the supplied connection in a single-use pool
+    #   adapter so the execution path is identical to the `pool:` form.
+    #   Useful in tests and for callers that already manage their own
+    #   connection lifecycle (e.g. bridge mode, `exe/woods-console`).
+    # - `pool:` — each call to {#execute} leases a fresh connection via
+    #   `pool.with_connection { |c| ... }`, so the connection is returned
+    #   to the pool immediately after the block. The leased connection is
+    #   also exposed via `Thread.current[:woods_console_leased_connection]`
+    #   so dispatch handlers (e.g. EmbeddedExecutor#active_connection) can
+    #   reuse the same connection without re-leasing.
+    #
+    # In both forms the connection is resolved *per {#execute} call* —
+    # SafeContext never holds a connection ivar. This is the key invariant
+    # for multi-DB / sharded hosts: if you supply a shard pool (or shard
+    # connection), the rolled-back transaction is opened on that shard's
+    # connection, not on the default pool.
+    #
+    # @example connection: form
     #   ctx = SafeContext.new(connection: conn, timeout_ms: 5000, redacted_columns: %w[ssn])
     #   ctx.execute { |c| c.execute("SELECT count(*) FROM users") }
     #
+    # @example pool: form (per-request lease)
+    #   ctx = SafeContext.new(pool: ActiveRecord::Base.connection_pool)
+    #   ctx.execute { |c| c.select_all("SELECT count(*) FROM users") }
+    #
+    # @example Shard pool — rollback covers the shard
+    #   shard_pool = ShardedModel.connection_pool
+    #   ctx = SafeContext.new(pool: shard_pool)
+    #   ctx.execute { |c| c.select_all("SELECT * FROM shard_table") }
+    #
+    # @example Key-value (EAV) redaction
+    #   ctx = SafeContext.new(
+    #     connection: conn,
+    #     redacted_key_values: [
+    #       { key_column: 'key', value_column: 'value',
+    #         sensitive_keys: %w[stripe_access_token oauth_token] }
+    #     ]
+    #   )
+    #
     class SafeContext
-      # @param connection [Object] Database connection (or mock)
+      # 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
+      # leased connection inside the rolled-back transaction.
+      LEASED_CONNECTION_KEY = :woods_console_leased_connection
+
+      # Thin adapter that makes a bare connection look like a connection pool
+      # with a `with_connection` interface. Used internally when callers pass
+      # `connection:` so that {#execute} always flows through a single code
+      # path regardless of construction form.
+      #
+      # @api private
+      SingleConnectionPool = Struct.new(:connection) do
+        # @yield [Object] the wrapped connection
+        def with_connection(&block)
+          block.call(connection)
+        end
+      end
+
+      # @return [Array<String>] Column names whose values are replaced with "[REDACTED]"
+      attr_reader :redacted_columns
+
+      # @return [Array<Hash>] Normalized EAV redaction patterns. Each entry has
+      #   string keys: 'key_column', 'value_column', 'sensitive_keys'.
+      attr_reader :redacted_key_values
+
+      # @param connection [Object, nil] Database connection (or mock).
+      #   Mutually exclusive with `pool:` — pass one or the other (or
+      #   neither, if this SafeContext is only being used for #redact).
+      #   The connection is wrapped in {SingleConnectionPool} so execution
+      #   always flows through `pool.with_connection`.
+      # @param pool [#with_connection, nil] Connection pool to lease from
+      #   per request. Each {#execute} call wraps `pool.with_connection`.
       # @param timeout_ms [Integer] Statement timeout in milliseconds
       # @param redacted_columns [Array<String>] Column names whose values should be redacted
-      def initialize(connection:, timeout_ms: 5000, redacted_columns: [])
-        @connection = connection
+      # @param redacted_key_values [Array<Hash>] EAV-style redaction patterns.
+      #   Each pattern: {key_column: 'key', value_column: 'value',
+      #   sensitive_keys: %w[stripe_access_token ...]}. When a row's
+      #   `key_column` cell matches one of `sensitive_keys`, the same row's
+      #   `value_column` cell is replaced with "[REDACTED]".
+      def initialize(connection: nil, pool: nil, timeout_ms: 5000,
+                     redacted_columns: [], redacted_key_values: [])
+        @pool = pool || (connection && SingleConnectionPool.new(connection))
         @timeout_ms = timeout_ms
         @redacted_columns = redacted_columns.map(&:to_s)
+        @redacted_key_values = normalize_key_value_patterns(redacted_key_values)
       end
 
       # Execute a block within a rolled-back transaction with statement timeout.
       #
       # The transaction is always rolled back to ensure read-only behavior.
+      # A fresh connection is leased from the pool on every call via
+      # `pool.with_connection`. The leased connection is published as
+      # `Thread.current[LEASED_CONNECTION_KEY]` for the duration of the
+      # block and cleared in `ensure` (even on exceptions) so dispatch
+      # handlers can pick it up without re-leasing.
       #
       # @yield [connection] The database connection
       # @return [Object] The block's return value
-      def execute
-        result = nil
-        @connection.transaction do
-          set_timeout
-          result = yield(@connection)
-          raise ActiveRecord::Rollback
-        end
-        result
+      # @raise [ArgumentError] when neither `connection:` nor `pool:` was
+      #   supplied at construction time. Deferred to #execute so callers
+      #   that only use #redact can construct with neither.
+      def execute(&block)
+        raise ArgumentError, 'SafeContext#execute requires connection: or pool: at construction time' unless @pool
+
+        # NOTE: on async side effects: earlier iterations of SafeContext
+        # tried to swap `ActiveJob::Base.queue_adapter` / `ActionMailer::Base
+        # .delivery_method` to `:test` for the duration of this block.
+        # That's unsafe — those settings are process-wide class state, so
+        # any concurrent request served by the SAME Puma worker (the host
+        # app running alongside the Console MCP) would race and briefly
+        # see the test adapter, silently dropping real jobs and mail.
+        # The gap is documented in the class docstring instead; operators
+        # must treat callback-triggered enqueues / deliveries as live.
+        @pool.with_connection { |conn| run_with_timeout(conn, &block) }
       end
 
       # Replace values of redacted columns with "[REDACTED]".
       #
+      # Runs column-name redaction first, then EAV key-value redaction — a row
+      # like {key: "stripe_access_token", value: "sk_live_..."} has its `value`
+      # column replaced when "stripe_access_token" is in the sensitive_keys
+      # list, regardless of whether `value` itself is in redacted_columns.
+      #
       # @param hash [Hash] Record attributes
       # @param _model_name [String] Model name (reserved for per-model redaction rules)
       # @return [Hash] Redacted copy of the hash
       def redact(hash, _model_name = nil)
-        return hash if @redacted_columns.empty?
+        return hash if @redacted_columns.empty? && @redacted_key_values.empty?
 
-        hash.transform_keys(&:to_s).each_with_object({}) do |(key, value), redacted|
-          redacted[key] = @redacted_columns.include?(key) ? '[REDACTED]' : value
+        redacted = hash.transform_keys(&:to_s).each_with_object({}) do |(key, value), out|
+          out[key] = @redacted_columns.include?(key) ? '[REDACTED]' : value
         end
+        apply_key_value_redaction(redacted)
       end
 
       private
 
+      # Wrap one connection in a rolled-back transaction with timeout, and
+      # publish it via Thread.current so handlers can reuse it. Always
+      # clears the thread-local in ensure so a raise mid-block cannot leak
+      # a stale connection reference into the next request on this thread.
+      def run_with_timeout(connection)
+        previous = Thread.current[LEASED_CONNECTION_KEY]
+        Thread.current[LEASED_CONNECTION_KEY] = connection
+        result = nil
+        connection.transaction do
+          set_timeout(connection)
+          result = yield(connection)
+          raise ActiveRecord::Rollback
+        end
+        result
+      ensure
+        Thread.current[LEASED_CONNECTION_KEY] = previous
+      end
+
+      def normalize_key_value_patterns(patterns)
+        Array(patterns).filter_map { |pattern| normalize_pattern(pattern) }
+      end
+
+      def normalize_pattern(pattern)
+        key_col = fetch_pattern_string(pattern, :key_column)
+        val_col = fetch_pattern_string(pattern, :value_column)
+        sensitive = Array(pattern[:sensitive_keys] || pattern['sensitive_keys']).map(&:to_s)
+        return if key_col.nil? || val_col.nil? || sensitive.empty?
+
+        { 'key_column' => key_col, 'value_column' => val_col, 'sensitive_keys' => sensitive }
+      end
+
+      def fetch_pattern_string(pattern, key)
+        (pattern[key] || pattern[key.to_s])&.to_s
+      end
+
+      def apply_key_value_redaction(hash)
+        @redacted_key_values.each do |pattern|
+          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)
+
+          hash[val_col] = '[REDACTED]'
+        end
+        hash
+      end
+
       # Set statement timeout on the connection.
       #
-      # PostgreSQL uses SET statement_timeout (applies to all statement types).
-      # MySQL uses SET max_execution_time (applies to SELECT only — MySQL limitation:
-      # DDL and DML statements cannot be time-limited via this variable).
-      def set_timeout(connection = @connection, timeout_ms = @timeout_ms)
+      # PostgreSQL uses `SET LOCAL statement_timeout` so the setting is
+      # scoped to the surrounding transaction and is automatically
+      # discarded on rollback — without LOCAL the timeout would persist on
+      # the pooled connection and bleed into the next consumer (host app
+      # 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).
+      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}")
         else
-          connection.execute("SET statement_timeout = '#{timeout_ms.to_i}ms'")
+          connection.execute("SET LOCAL statement_timeout = '#{timeout_ms.to_i}ms'")
         end
-      rescue StandardError
-        # Unsupported adapter — timeout enforcement is best-effort
+      rescue StandardError => e
+        # Unsupported adapter (SQLite, Trilogy on unsupported version, Oracle) —
+        # 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.
+        warn_timeout_unsupported(adapter, e)
         nil
       end
+
+      def warn_timeout_unsupported(adapter, error)
+        return unless defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+
+        @warned_adapters ||= {}
+        return if @warned_adapters[adapter]
+
+        @warned_adapters[adapter] = true
+        Rails.logger.warn(
+          '[Woods::Console::SafeContext] statement timeout not supported on ' \
+          "adapter #{adapter.inspect}: #{error.class}: #{error.message}. " \
+          'Queries will run without a per-statement time limit.'
+        )
+      rescue StandardError
+        # Last-resort swallow — never let telemetry failure break execution.
+      end
     end
   end
 end