woods 1.1.0 → 1.3.0

data/lib/woods/console/confirmation.rb

@@ -52,9 +52,8 @@ module Woods
       # @param tool [String] Tool name
       # @param description [String] Human-readable description of the action
       # @param params [Hash] Tool parameters
-      # @return [true] if confirmed
       # @raise [ConfirmationDeniedError] if denied
-      def request_confirmation(tool:, description:, params:) # rubocop:disable Naming/PredicateMethod
+      def request_confirmation(tool:, description:, params:)
         approved = evaluate(tool: tool, description: description, params: params)
 
         @history << {
@@ -65,9 +64,9 @@ module Woods
           timestamp: Time.now.utc.iso8601
         }
 
-        raise ConfirmationDeniedError, "Confirmation denied for #{tool}: #{description}" unless approved
+        return if approved
 
-        true
+        raise ConfirmationDeniedError, "Confirmation denied for #{tool}: #{description}"
       end
 
       private

data/lib/woods/console/console_response_renderer.rb

@@ -9,11 +9,19 @@ module Woods
     #
     # Auto-detects:
     # - Array<Hash> → Markdown tables
-    # - Single Hash → Key-value bullet lists
+    # - Single Hash → Key-value bullet lists (Array values recurse into tables;
+    #   `rows` / `values` paired with a sibling `columns` render as positional
+    #   Markdown tables so sql/query/pluck output isn't collapsed)
     # - Simple Array → Bullet list
     # - Scalars → Plain text
     #
     class ConsoleResponseRenderer < MCP::ToolResponseRenderer
+      # Keys that carry positional row data in tool responses. When any of
+      # these appears alongside a `columns` array we render a proper table
+      # using the columns as headers instead of dumping bracketed arrays.
+      POSITIONAL_ROW_KEYS = %w[rows values].freeze
+      private_constant :POSITIONAL_ROW_KEYS
+
       # Smart default: auto-detect data shape and render accordingly.
       #
       # @param data [Object] The bridge response result
@@ -43,26 +51,56 @@ module Woods
 
       def render_table(rows)
         keys = rows.first.keys
-        lines = []
-        lines << "| #{keys.join(' | ')} |"
-        lines << "| #{keys.map { '---' }.join(' | ')} |"
-        rows.each do |row|
-          lines << "| #{keys.map { |k| row[k] }.join(' | ')} |"
-        end
-        lines.join("\n")
+        header_row(keys) + rows.map { |row| row_line(keys.map { |k| row[k] }) }.join
       end
 
       def render_hash(data)
-        data.map do |key, value|
-          case value
-          when Hash
-            "**#{key}:**\n" + value.map { |k, v| "  - #{k}: #{v}" }.join("\n")
-          when Array
-            "**#{key}:** #{value.size} items"
-          else
-            "**#{key}:** #{value}"
-          end
-        end.join("\n")
+        columns = stringify_array(data['columns'] || data[:columns])
+        data.map { |key, value| render_hash_entry(key, value, columns) }.join("\n")
+      end
+
+      def render_hash_entry(key, value, sibling_columns)
+        case value
+        when Hash
+          "**#{key}:**\n" + value.map { |k, v| "  - #{k}: #{v}" }.join("\n")
+        when Array
+          "**#{key}:**\n" + render_hash_array_value(key, value, sibling_columns)
+        else
+          "**#{key}:** #{value}"
+        end
+      end
+
+      def render_hash_array_value(key, value, sibling_columns)
+        if POSITIONAL_ROW_KEYS.include?(key.to_s) && sibling_columns && !sibling_columns.empty?
+          render_positional_table(value, sibling_columns)
+        else
+          render_array(value)
+        end
+      end
+
+      # Build a Markdown table from positional row data + a columns header.
+      # Handles both Array<Array> (multi-column rows) and flat scalar arrays
+      # (pluck with a single column — Rails collapses the result).
+      def render_positional_table(rows, columns)
+        return '_(empty)_' if rows.empty?
+
+        header_row(columns) + rows.map { |row| row_line(positional_row_values(row)) }.join
+      end
+
+      def positional_row_values(row)
+        row.is_a?(Array) ? row : [row]
+      end
+
+      def header_row(keys)
+        "| #{keys.join(' | ')} |\n| #{keys.map { '---' }.join(' | ')} |\n"
+      end
+
+      def row_line(values)
+        "| #{values.join(' | ')} |\n"
+      end
+
+      def stringify_array(value)
+        value.is_a?(Array) ? value.map(&:to_s) : nil
       end
     end
 

data/lib/woods/console/credential_index.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require 'set'
+
+# @see Woods
+module Woods
+  class Error < StandardError; end unless defined?(Woods::Error)
+
+  module Console
+    # Boot-time index of every string leaf in `Rails.application.credentials`.
+    #
+    # The pattern-based {CredentialScanner} catches *known credential shapes*
+    # (Stripe `sk_live_…`, AWS `AKIA…`, etc.). It cannot catch a value whose
+    # shape is unknown — a hand-rolled HMAC secret, a Twilio auth token, a
+    # third-party webhook signing key. This index closes that gap by
+    # remembering the host app's *actual* credential values and substring-
+    # matching them in every Console MCP response, so a row whose value
+    # exactly matches a stored credential is redacted regardless of column
+    # name or value shape.
+    #
+    # The index is built once at server boot — walking encrypted credentials
+    # on every request would be both expensive and unsafe (it requires the
+    # master key). Each string leaf with length ≥ {MIN_LENGTH} is added to a
+    # frozen Set, and a pre-compiled `Regexp.union` is held for one-pass
+    # `gsub` substitution.
+    #
+    # ### Multi-DB / sharded caveat
+    # The index reflects credentials available to the *Rails process* that
+    # boots the Console MCP server. A separate database that holds its own
+    # secrets (e.g., a vendored CMS app sharing the same Rails host) is not
+    # in scope. Use Layer 3 (`console_redacted_columns` /
+    # `console_redacted_key_values`) for those.
+    #
+    # ### Missing master key
+    # In environments without `config/master.key` (CI, fresh checkouts) the
+    # `Rails.application.credentials.config` call raises
+    # `ActiveSupport::EncryptedConfiguration::MissingKeyError` or
+    # `ActiveSupport::MessageEncryptor::InvalidMessage`. {.build} catches
+    # both *by name* (no constant reference, so the class load order is
+    # irrelevant) and returns an empty index — the server still boots, the
+    # other defense layers still apply.
+    #
+    # @example
+    #   index = CredentialIndex.build(rails_app: Rails.application)
+    #   index.match?("sk_live_actual_secret_value")  # => true
+    #   index.redact("token: sk_live_actual_secret_value")
+    #     # => "token: [REDACTED:credential]"
+    #
+    class CredentialIndex
+      # Captured at require time so the mtime-check warning has a stable
+      # reference point even if the clock skews later. Frozen immediately
+      # to prevent accidental mutation.
+      PROCESS_START = Time.now.freeze
+
+      # Substrings shorter than this are not added to the index. Below ~12
+      # chars the false-positive rate climbs sharply (env names like
+      # `production`, hostnames, version strings, etc.).
+      MIN_LENGTH = 12
+
+      # Rendered marker for substring hits — distinct from the pattern
+      # scanner's `[REDACTED]` so operators reading audit output can see
+      # *which* layer caught the leak.
+      REDACTED = '[REDACTED:credential]'
+
+      # Encryption-related exception class names caught by name. Rails moves
+      # these around between versions; matching by `Class#name` keeps us
+      # from coupling to a specific constant path.
+      MISSING_KEY_ERRORS = %w[
+        ActiveSupport::EncryptedConfiguration::MissingKeyError
+        ActiveSupport::EncryptedFile::MissingKeyError
+        ActiveSupport::MessageEncryptor::InvalidMessage
+      ].freeze
+
+      class << self
+        # Build an index from a Rails application's encrypted credentials.
+        #
+        # **Restart required after rotation.** The index is built once at
+        # server boot and held in memory for the life of the MCP process.
+        # When a host app rotates Rails credentials, the MCP process keeps
+        # the pre-rotation secrets in its frozen Set until the process
+        # restarts. New secrets added during rotation are NOT in the index
+        # — only Layer 2 shape patterns can catch them until restart.
+        #
+        # To trigger a rebuild without restarting, call
+        # `Woods::Console::Server.rebuild_credential_index` from a rotation
+        # job or initializer hook. See docs/CONSOLE_MCP_SETUP.md for the
+        # full restart guidance.
+        #
+        # @param rails_app [#credentials] usually `Rails.application`.
+        # @return [CredentialIndex] populated index, or an empty index when
+        #   the credentials store can't be opened.
+        def build(rails_app:)
+          new(secrets: collect_secrets(rails_app))
+        rescue StandardError => e
+          raise unless missing_key_error?(e)
+
+          new(secrets: [])
+        end
+
+        # Emit a structured log warning when any of the given credentials
+        # files has a modification time newer than `process_start`. This
+        # catches the common "rotated credentials but forgot to restart"
+        # situation at boot time.
+        #
+        # Only files that actually exist on disk are checked; missing paths
+        # are silently skipped so CI and fresh-checkout environments (which
+        # have no credentials file) produce no noise.
+        #
+        # @param credentials_files [Array<String>] Paths to check (e.g.
+        #   `config/credentials.yml.enc`,
+        #   `config/credentials/production.yml.enc`).
+        # @param process_start [Time] When the current process started.
+        #   Typically `Woods::Console::CredentialIndex::PROCESS_START`.
+        # @param logger [#warn] A logger responding to `warn(event, **kwargs)`.
+        # @return [void]
+        def warn_if_credentials_rotated(credentials_files:, process_start:, logger:)
+          credentials_files.each do |path|
+            next unless File.exist?(path)
+
+            mtime = File.mtime(path)
+            next unless mtime > process_start
+
+            logger.warn(
+              'console.credential_index.stale',
+              credentials_file: path,
+              file_mtime: mtime.iso8601,
+              process_start: process_start.iso8601,
+              hint: 'Credentials file was modified after process start — ' \
+                    'restart the MCP process or call ' \
+                    'Woods::Console::Server.rebuild_credential_index to ' \
+                    'pick up rotated secrets.'
+            )
+          end
+        end
+
+        private
+
+        def collect_secrets(rails_app)
+          config = rails_app.credentials.config
+          collected = []
+          walk(config, collected)
+          collected
+        end
+
+        def walk(node, collected)
+          case node
+          when Hash  then node.each_value { |v| walk(v, collected) }
+          when Array then node.each { |v| walk(v, collected) }
+          when String
+            collected << node if node.length >= MIN_LENGTH
+          end
+        end
+
+        def missing_key_error?(error)
+          MISSING_KEY_ERRORS.include?(error.class.name)
+        end
+      end
+
+      # @return [Set<String>] frozen set of secret strings (length ≥ MIN_LENGTH).
+      attr_reader :secrets
+
+      # @return [Regexp, nil] precompiled `Regexp.union` of every secret, or
+      #   nil when the index is empty (no allocation, no per-string overhead).
+      attr_reader :pattern
+
+      # @param secrets [Enumerable<String>] string leaves harvested from
+      #   credentials. Duplicates are collapsed; strings shorter than
+      #   {MIN_LENGTH} are dropped.
+      def initialize(secrets:)
+        filtered = Array(secrets).select { |s| s.is_a?(String) && s.length >= MIN_LENGTH }
+        @secrets = filtered.to_set.freeze
+        @pattern = @secrets.empty? ? nil : Regexp.union(@secrets.to_a)
+      end
+
+      # @return [Boolean] true when no secrets were collected (missing key,
+      #   empty credentials file, or every leaf below MIN_LENGTH).
+      def empty?
+        @secrets.empty?
+      end
+
+      # @param str [String]
+      # @return [Boolean] true when any indexed secret appears as a substring.
+      def match?(str)
+        return false if empty? || !str.is_a?(String)
+
+        @pattern.match?(str)
+      end
+
+      # Replace every indexed-secret substring in `str` with {REDACTED}.
+      #
+      # @param str [String]
+      # @return [String] redacted copy. Returns the input unchanged when the
+      #   index is empty or no secret appears.
+      def redact(str)
+        return str if empty? || !str.is_a?(String) || !@pattern.match?(str)
+
+        str.gsub(@pattern, REDACTED)
+      end
+    end
+  end
+end

data/lib/woods/console/credential_scanner.rb

@@ -0,0 +1,302 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'cgi'
+require 'set'
+
+require_relative 'credential_index'
+
+# @see Woods
+module Woods
+  class Error < StandardError; end unless defined?(Woods::Error)
+
+  module Console
+    # Content-shape credential scanner for Console MCP responses.
+    #
+    # Walks a serialized response tree (strings, nested Hash, nested Array)
+    # and replaces substrings that match known credential formats with
+    # `[REDACTED]`. Pattern matching is high-specificity (word-boundary
+    # anchored, minimum-length bounded) so false positives against UUIDs,
+    # email addresses, and short identifiers stay rare.
+    #
+    # This is Layer 2 of the defense-in-depth stack — it runs AFTER the
+    # operator-configured column and EAV redaction layers so it catches
+    # credentials those layers missed (newly-added EAV keys, secrets stored
+    # in JSONB columns, associated records pulled via nested serialization).
+    #
+    # @example
+    #   scanner = CredentialScanner.new
+    #   value, counts = scanner.scan('token is sk_test_4eC39HqLyjWDarjtT1zdp7dc')
+    #   value  # => "token is [REDACTED]"
+    #   counts # => { stripe_secret_key: 1 }
+    #
+    class CredentialScanner # rubocop:disable Metrics/ClassLength
+      REDACTED = '[REDACTED]'
+
+      # High-specificity credential patterns. Each is word-boundary anchored
+      # and bounded by a realistic minimum length so random short strings
+      # cannot trigger a match.
+      #
+      # Order matters: more-specific patterns appear before less-specific
+      # alternatives (e.g., `anthropic_api_key` before `openai_api_key`)
+      # so the specific counter increments rather than the generic one.
+      PATTERNS = {
+        stripe_secret_key: /\b(?:sk|rk)_(?:live|test)_[A-Za-z0-9]{24,}\b/,
+        stripe_publishable_key: /\bpk_(?:live|test)_[A-Za-z0-9]{24,}\b/,
+        stripe_webhook_secret: /\bwhsec_[A-Za-z0-9]{24,}\b/,
+        # Stripe Connect account IDs are PII per Stripe's ToS even though they
+        # are not strictly secret — surfacing one in an MCP response leaks the
+        # connected merchant's identity.
+        stripe_connect_account_id: /\bacct_[A-Za-z0-9]{16,}\b/,
+        # Klaviyo private API keys use a bare `pk_` prefix with no live/test
+        # infix — they evade the Stripe publishable regex and grant full API
+        # access to the Klaviyo tenant. Order matters: stripe_publishable_key
+        # runs first so its more-specific match wins on Stripe values.
+        klaviyo_private_key: /\bpk_[A-Za-z0-9]{34}\b/,
+        aws_access_key_id: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/,
+        github_fine_grained_pat: /\bgithub_pat_[A-Za-z0-9_]{82}\b/,
+        github_token: /\bgh[pousr]_[A-Za-z0-9]{36,}\b/,
+        google_oauth_token: /\bya29\.[A-Za-z0-9_-]{20,}\b/,
+        jwt_token: /\beyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/,
+        pem_private_key_block: /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/,
+        slack_token: /\bxox[abpr]-[A-Za-z0-9-]{10,}\b/,
+        sendgrid_api_key: /\bSG\.[A-Za-z0-9_-]{22}\.[A-Za-z0-9_-]{43}\b/,
+        mailgun_api_key: /\bkey-[a-f0-9]{32}\b/,
+        # Matches both the current `sk-ant-api03-…` / `sk-ant-admin01-…` shape
+        # and the legacy `sk-ant-…` format that shipped without the
+        # `api|admin` infix. Length floor prevents matching on a bare `sk-ant-`
+        # prefix in logs or docs.
+        anthropic_api_key: /\bsk-ant-(?:(?:api|admin)\d{2}-)?[A-Za-z0-9_-]{80,}\b/,
+        openai_api_key: %r{\bsk-(?:proj-)?[A-Za-z0-9/_-]{40,}\b},
+        # `rt`/`ua` extend the existing alternation to cover refresh tokens
+        # (`shprt_`) and user-access tokens (`shpua_`) — the prefix list
+        # before this PR missed both.
+        shopify_access_token: /\bshp(?:at|ca|ss|pa|rt|ua)_[a-f0-9]{32}\b/,
+        square_access_token: /\bsq0[a-z]{3}-[A-Za-z0-9_-]{22,}\b/,
+        paypal_access_token: /\baccess_token\$(?:production|sandbox)\$[A-Za-z0-9]+\$[a-f0-9]+\b/,
+        # Distinctive `00D<15-org-id>!<base64 payload>` shape — no FP risk
+        # and one of the highest-leverage additions per the research brief.
+        salesforce_access_token: /\b00D[A-Za-z0-9]{12}![A-Za-z0-9._]{80,250}\b/,
+        launchdarkly_sdk_key: /\bsdk-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/,
+        launchdarkly_mobile_key: /\bmob-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/,
+        hubspot_private_app_token: Regexp.new(
+          '\bpat-(?:na1|na2|eu1|eu2|ap1)-' \
+          '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b'
+        ),
+        brevo_api_key: /\bxkeysib-[a-f0-9]{64}-[A-Za-z0-9]{16}\b/,
+        brevo_smtp_key: /\bxsmtpsib-[a-f0-9]{64}-[A-Za-z0-9]{16}\b/,
+        kit_api_key: /\bkit_[A-Za-z0-9]{20,}\b/,
+        twilio_account_sid: /\bAC[0-9a-fA-F]{32}\b/,
+        twilio_api_key_sid: /\bSK[0-9a-fA-F]{32}\b/,
+        twilio_verify_service_sid: /\bVA[0-9a-fA-F]{32}\b/,
+        # Connection strings with embedded credentials: `postgres://user:pass@host/db`,
+        # `mysql2://user:pass@host/db`, `mongodb://…`, `amqp://…`, `redis://…`.
+        # Captures the entire URL — the password is part of it and redacting
+        # just the password field while leaving `user@host` visible is not
+        # worth the regex complexity when the host may itself be sensitive.
+        database_url_with_password: Regexp.new(
+          '\b(?:postgres|postgresql|mysql|mysql2|mongodb|mongodb\+srv|amqp|amqps|redis|rediss|' \
+          'clickhouse|cockroachdb|mariadb)://[^\s:@/]+:[^\s@/]+@\S+'
+        )
+      }.freeze
+
+      # @return [Array<Symbol>] every pattern name the scanner knows about.
+      def self.patterns
+        PATTERNS.keys
+      end
+
+      # Replace the boot-time credential index with a freshly built one.
+      #
+      # Called by `Woods::Console::Server.rebuild_credential_index` after a
+      # host app rotates its Rails credentials. Thread-safe: the assignment
+      # is atomic on MRI (GVL) and the new index is fully constructed before
+      # being swapped in, so in-flight scans see either the old or the new
+      # index — never a partial one.
+      #
+      # @param new_index [CredentialIndex, nil] The replacement index.
+      # @return [void]
+      def replace_index!(new_index)
+        @secret_index = if new_index.respond_to?(:empty?) && new_index.empty?
+                          nil
+                        else
+                          new_index
+                        end
+      end
+
+      # Counter key emitted when {CredentialIndex} substring-matches a value
+      # before any shape pattern fires. Distinct from pattern names so
+      # observability can tell the two layers apart.
+      INDEX_HIT = :credential_index
+
+      # @param disabled_patterns [Array<Symbol, String>] names to skip at scan
+      #   time. Strings are coerced to Symbols.
+      # @param secret_index [#match?, #redact, nil] Optional {CredentialIndex}
+      #   built from the host app's actual credentials. When present, every
+      #   string is run through the index *before* the pattern pass — so a
+      #   value whose shape no pattern recognizes (Twilio auth tokens,
+      #   hand-rolled HMAC keys, etc.) is still redacted when it matches a
+      #   stored credential exactly. Pass `nil` (or a `CredentialIndex#empty?`
+      #   index) to skip the substring layer.
+      def initialize(disabled_patterns: [], secret_index: nil)
+        disabled = Array(disabled_patterns).to_set(&:to_sym)
+        @active_patterns = PATTERNS.except(*disabled)
+        @secret_index = secret_index unless secret_index.respond_to?(:empty?) && secret_index.empty?
+      end
+
+      # Scan a value (String, Hash, Array, or any other object) for credentials.
+      #
+      # Strings are gsub'd against every active pattern. Hash values and Array
+      # elements are walked recursively; keys and non-string scalars
+      # (Integer, Float, true/false, nil) pass through untouched.
+      #
+      # @param value [Object]
+      # @return [Array(Object, Hash{Symbol=>Integer})] two-tuple of the scanned
+      #   value and a per-pattern match count. Count entries are only present
+      #   for patterns that fired — callers should treat a missing key as zero.
+      def scan(value)
+        counts = {}
+        scanned = walk(value, counts)
+        [scanned, counts]
+      end
+
+      private
+
+      def walk(value, counts)
+        case value
+        when String then scan_string(value, counts)
+        when Hash   then walk_hash(value, counts)
+        when Array  then value.map { |item| walk(item, counts) }
+        else value
+        end
+      end
+
+      # Walk a Hash, scanning both keys and values for credentials.
+      #
+      # Keys are scanned by coercing them to String, running the scan, then
+      # restoring the original key type — a Symbol key that carries a
+      # credential-shaped string is emitted as a Symbol after redaction
+      # (e.g. `:"[REDACTED]"`). String keys stay Strings. Non-String,
+      # non-Symbol keys (Integer, etc.) pass through unchanged.
+      def walk_hash(hash, counts)
+        hash.each_with_object({}) do |(key, val), out|
+          scanned_key = case key
+                        when String then scan_string(key, counts)
+                        when Symbol then scan_string(key.to_s, counts).to_sym
+                        else             key
+                        end
+          out[scanned_key] = walk(val, counts)
+        end
+      end
+
+      def scan_string(str, counts)
+        result = redact_indexed_secrets(str, counts)
+        result = scan_encoded_forms(result, counts)
+        @active_patterns.inject(result) do |acc, (name, pattern)|
+          acc.gsub(pattern) do
+            counts[name] = (counts[name] || 0) + 1
+            REDACTED
+          end
+        end
+      end
+
+      # Best-effort redaction of credentials that slip past the literal-pattern
+      # pass because they are URL-encoded (`sk%5Ftest%5F…`) or base64-wrapped
+      # (`c2tfdGVzdF8…`). For each candidate substring we try the decoded form
+      # against every active pattern; if any pattern matches, we redact the
+      # encoded substring in the original string. This is a defense-in-depth
+      # layer — the literal patterns remain the primary guarantee and the
+      # decoded scan runs only over substrings whose shape suggests encoding.
+      def scan_encoded_forms(str, counts)
+        str = scan_url_encoded(str, counts) if str.include?('%')
+        scan_base64(str, counts)
+      end
+
+      URL_ENCODED_CANDIDATE = %r{[A-Za-z0-9%_.~+/=-]{24,}}
+      # No trailing `\b` anchor — `\b` requires a word/non-word transition
+      # and fails at end-of-string after a `=` padding char. Use a negative
+      # look-ahead to stop at the next alphanumeric character instead.
+      BASE64_CANDIDATE = %r{\b[A-Za-z0-9+/]{40,}={0,2}(?![A-Za-z0-9+/])}
+      private_constant :URL_ENCODED_CANDIDATE, :BASE64_CANDIDATE
+
+      def scan_url_encoded(str, counts)
+        str.gsub(URL_ENCODED_CANDIDATE) do |candidate|
+          next candidate unless candidate.include?('%')
+
+          decoded = safely_unescape(candidate)
+          credential_name = first_matching_pattern(decoded)
+          if credential_name
+            counts[credential_name] = (counts[credential_name] || 0) + 1
+            REDACTED
+          else
+            candidate
+          end
+        end
+      end
+
+      def scan_base64(str, counts)
+        str.gsub(BASE64_CANDIDATE) do |candidate|
+          decoded = safely_base64_decode(candidate)
+          next candidate unless decoded
+
+          credential_name = first_matching_pattern(decoded)
+          if credential_name
+            counts[credential_name] = (counts[credential_name] || 0) + 1
+            REDACTED
+          else
+            candidate
+          end
+        end
+      end
+
+      def first_matching_pattern(value)
+        @active_patterns.each do |name, pattern|
+          return name if pattern.match?(value)
+        end
+        nil
+      end
+
+      def safely_unescape(value)
+        CGI.unescape(value)
+      rescue ArgumentError
+        value
+      end
+
+      def safely_base64_decode(value)
+        decoded = Base64.strict_decode64(value)
+        decoded.force_encoding(Encoding::UTF_8)
+        return nil unless decoded.valid_encoding?
+        # CPU short-circuit: credential strings are printable ASCII. If
+        # the decoded bytes are mostly non-printable (likely a binary
+        # hash / random bytes / image), skip the pattern scan entirely —
+        # avoids running every `active_patterns` regex over gigabytes of
+        # hex dumps on every scan.
+        return nil unless mostly_printable?(decoded)
+
+        decoded
+      rescue ArgumentError
+        nil
+      end
+
+      PRINTABLE_RATIO_THRESHOLD = 0.85
+      private_constant :PRINTABLE_RATIO_THRESHOLD
+
+      def mostly_printable?(str)
+        return false if str.empty?
+
+        # ASCII printable (0x20-0x7e) + tab/newline; the threshold matches
+        # base64 encodings of typical credential shapes (sk_live_..., AKIA...,
+        # ghp_..., etc.) which are 100% printable.
+        printable = str.each_char.count { |c| c.match?(/[\t\n\x20-\x7e]/) }
+        printable.to_f / str.length >= PRINTABLE_RATIO_THRESHOLD
+      end
+
+      def redact_indexed_secrets(str, counts)
+        return str unless @secret_index&.match?(str)
+
+        redacted = @secret_index.redact(str)
+        counts[INDEX_HIT] = (counts[INDEX_HIT] || 0) + redacted.scan(CredentialIndex::REDACTED).size
+        redacted
+      end
+    end
+  end
+end