coolhand 0.9.0 → 0.10.1

data/docs/openai.md

@@ -12,7 +12,7 @@ Requires Rails — `Coolhand::WebhookInterceptor` and `Coolhand::OpenAi::BatchRe
 - Include the interceptor in your controller: `include Coolhand::WebhookInterceptor`
 - Add the `before_action` to validate and populate the `@validator` payload: `before_action :intercept_batch_request, only: :openai`
 - Ensure you skip CSRF for the webhook endpoint: `skip_before_action :verify_authenticity_token`
-- Override the `webhook_secret` method to return your OpenAI webhook secret
+- Override the `webhook_secret` method to return your OpenAI webhook secret. Define it under `private` so it can't be routed as an action
 
 `intercept_batch_request` already validates the webhook and, for `batch.completed`/`batch.failed`/`batch.expired`/`batch.cancelled` events, calls `Coolhand::OpenAi::BatchResultProcessor` — that part requires no code in your controller action. The batch's status is checked inline in the `before_action`, but for a completed batch the two JSONL file downloads and the one-request-log-per-item sends run on Coolhand's [background log thread](configuration.md#asynchronous-logging), so a large batch doesn't hold up your webhook response. (With `config.async_logging = false` this all runs inline, and a large batch can trip your webhook endpoint's timeout and OpenAI's retry behavior.) The example below shows a controller action doing additional, app-specific work on top of that (e.g. updating your own `BatchApiRequest` record and enqueuing your own background job), which is optional.
 
@@ -53,19 +53,68 @@ rescue StandardError => e
   head :internal_server_error
 end
 
+private # keep helpers like this below your public actions
+
 def webhook_secret
   Rails.application.credentials.openai_webhook_secret
 end
 # ...existing code...
 ```
 
+`intercept_batch_request`, `webhook_secret` and `process_event` are private in `Coolhand::WebhookInterceptor`, so Rails doesn't treat them as controller actions, and `before_action :intercept_batch_request` works with a private method. Code outside the controller can no longer call them directly (it gets `NoMethodError`); `super` from your own override still works.
+
+If your controller re-defines `webhook_secret` or `process_event` as public, they are public methods again, but `Coolhand::WebhookInterceptor` still removes all three names from the controller's `action_methods`, so they stay unroutable. That also means these names are reserved: a controller action with one of those names would not be routable. Defining your overrides under `private` is still the recommended form.
+
+## What gets logged for a completed batch
+
+Each batch item is logged with `source_api: "openai"` and the `model` from the item's request body (falling back to the response body). Batch input files use relative URLs such as `/v1/chat/completions`; these are logged as `https://api.openai.com/v1/chat/completions` (the host is not configurable, so Azure OpenAI or proxy batches are logged with that host too). The batch's `in_progress_at` and `completed_at` timestamps become each log's start and completion times; if OpenAI reports either as missing, the whole batch is skipped with an error in `Rails.logger` rather than logged with bogus times. If `completed_at` is earlier than `in_progress_at`, a warning is logged and `duration_ms` is clamped to 0.
+
+Each item's request body and response body are capped separately by [`max_captured_body_bytes`](configuration.md#body-capture-limits): one over the limit is logged as a `{"_coolhand_capture_skipped" => "body_too_large", ...}` placeholder (the item itself is still logged, and `model` is still taken from the full request body). See [Body Capture Limits](configuration.md#body-capture-limits) for the other placeholders. When the OpenAI client returns a result file as a String or IO, it is read and parsed one JSONL line at a time; a client that returns the file already parsed (`ruby-openai` does) has loaded it in full before Coolhand sees it. A malformed line is skipped and counted in an error log, and the other lines are still processed.
+
+The batch ID from the webhook payload and the batch's input/output file IDs are used in calls to the OpenAI API with your `OPENAI_API_KEY`, so they are format-checked first (`batch_...` and `file-...`/`file_...`, letters, digits, `_` and `-` only). An event or batch whose IDs don't match is ignored with an error in `Rails.logger`.
+
 ## Signature header and secret rotation
 
 The `webhook-signature` header may carry several space-separated signatures (`v1,sigA v1,sigB`), as senders produce while a webhook secret is being rotated. `Coolhand::OpenAi::WebhookValidator` accepts the request if any `v1,` entry matches your secret, comparing each in constant time and ignoring entries with any other version prefix. The timestamp and replay checks below still run, and only after a signature matches.
 
+## Local development and testing
+
+Signature headers (`webhook-signature`, `webhook-timestamp`, `webhook-id`) are required whenever a webhook secret is configured, in every `Rails.env`, including `development` and `test`. A request missing any of them is rejected, so your controller responds with 401. Earlier versions let unsigned requests through in development and test, which meant an app running with `RAILS_ENV=development` on a reachable host accepted forged webhooks.
+
+The same applies to a missing (`nil`) request body: with a secret configured it is rejected in every `Rails.env`, since there is nothing to verify the signature against. An empty-string body is not treated as missing; it goes through the normal signature check and passes only if it was actually signed.
+
+Signature verification (and the missing-body check) is skipped, with a logged warning, only when no secret is configured at all, and only in `development` and `test`. Every other environment rejects the request.
+
+If you post unsigned test payloads to a local app that has a secret set, pick one of these:
+
+- **Sign the test payload** with the same secret:
+
+  ```ruby
+  require "openssl"
+  require "base64"
+  require "json"
+  require "securerandom"
+
+  # Same key handling as the validator: a `whsec_` secret is base64-decoded, anything else is used as-is.
+  secret = ENV.fetch("OPENAI_WEBHOOK_SECRET")
+  secret_bytes = secret.start_with?("whsec_") ? Base64.strict_decode64(secret.delete_prefix("whsec_")) : secret
+  id = "wh_local_#{SecureRandom.hex(4)}"
+  timestamp = Time.now.to_i.to_s
+  body = { type: "batch.completed", data: { id: "batch_123" } }.to_json
+  signature = Base64.strict_encode64(OpenSSL::HMAC.digest("sha256", secret_bytes, "#{id}.#{timestamp}.#{body}"))
+
+  # Send `body` with these headers:
+  #   webhook-id: <id>
+  #   webhook-timestamp: <timestamp>
+  #   webhook-signature: v1,<signature>
+  ```
+
+- **Leave the secret unset in development**, for example have `webhook_secret` return `nil` unless `Rails.env.production?`.
+- **Replay a real delivery** to your local app through a tunnel.
+
 ## Replay protection
 
-`Coolhand::OpenAi::WebhookValidator` rejects requests whose `webhook-timestamp` is more than **300 seconds** away from the current time, and rejects a `webhook-id` it has already seen within that window — this prevents a captured request (from a log aggregator, APM trace, or proxy log) from being replayed to re-trigger `Coolhand::OpenAi::BatchResultProcessor`.
+`Coolhand::OpenAi::WebhookValidator` rejects requests whose `webhook-timestamp` is more than **300 seconds** away from the current time, and rejects a `webhook-id` it has already seen within twice that window (a request dated at the edge of the tolerance stays fresh for up to two tolerances, so the id is remembered at least as long) — this prevents a captured request (from a log aggregator, APM trace, or proxy log) from being replayed to re-trigger `Coolhand::OpenAi::BatchResultProcessor`.
 
 Both are configurable:
 
@@ -76,7 +125,7 @@ Coolhand.configure do |config|
 end
 ```
 
-The default `webhook-id` dedup store is in-memory and per-process, so it only protects a single process — replays across multiple app processes/dynos within the tolerance window aren't caught by default. If you run more than one process, supply your own store via `config.webhook_id_store`; any object responding to `claim!(id, ttl_seconds)` works, e.g. one backed by `Rails.cache`. `claim!` must atomically check-and-record the id in one operation (not a separate read then write) — otherwise two requests racing on the same id can both "win" — so lean on your cache backend's compare-and-set primitive (`unless_exist:` below maps to Redis `SET NX` when using `RedisCacheStore`):
+The default `webhook-id` dedup store is in-memory and per-process, so it only protects a single process — replays across multiple app processes/dynos within the replay-protection window aren't caught by default. If you run more than one process, supply your own store via `config.webhook_id_store`; any object responding to `claim!(id, ttl_seconds)` works (`ttl_seconds` is twice `webhook_replay_tolerance_seconds`), e.g. one backed by `Rails.cache`. `claim!` must atomically check-and-record the id in one operation (not a separate read then write) — otherwise two requests racing on the same id can both "win" — so lean on your cache backend's compare-and-set primitive (`unless_exist:` below maps to Redis `SET NX` when using `RedisCacheStore`):
 
 ```ruby
 class RailsCacheWebhookIdStore
@@ -92,4 +141,14 @@ Coolhand.configure do |config|
 end
 ```
 
-Note: the `webhook-id` is claimed as soon as the signature and timestamp are confirmed valid — before your controller's `process_event` runs. If something downstream fails before the batch is actually handled (e.g. an unexpectedly-shaped payload), a same-id retry within the tolerance window will be rejected as a replay rather than reprocessed.
+Note: the `webhook-id` is claimed as soon as the signature and timestamp are confirmed valid — before your controller's `process_event` runs. If something downstream raises (e.g. an error in your own `process_event` override, or an unexpectedly-shaped payload), the interceptor releases the claim before responding, so OpenAI's retry of the same `webhook-id` is processed rather than rejected as a replay. (`Coolhand::OpenAi::BatchResultProcessor` rescues and logs its own errors, and does its heavy work in the background, so this mainly matters for exceptions raised in your own code.)
+
+Releasing is optional for custom stores: if your store also responds to `release!(id)`, it is called to forget the claim; a store that only implements `claim!` behaves as before and keeps the id claimed for its TTL even after a failure. To opt in, add `release!` to the store above:
+
+```ruby
+class RailsCacheWebhookIdStore
+  def release!(id)
+    Rails.cache.delete("coolhand:openai_webhook:#{id}")
+  end
+end
+```

data/docs/vertex.md

@@ -19,6 +19,7 @@ require "coolhand/vertex/batch_result_processor"
 - Optionally pass `model:` to populate the logged `model` field. It falls back to a `"model"` key in `batch_info` if present, and is omitted from the payload entirely when neither is available. If the value (from either source) looks like a Vertex model resource path (`publishers/<publisher>/models/<id>` or `projects/<project>/locations/<location>/models/<id>`), it's normalized down to just the trailing id/version before being logged; any other string is sent as-is.
 - `batch_info["name"]` must be the exact Vertex job resource name (`projects/<project>/locations/<location>/batchPredictionJobs/<job-id>`), and `batch_info["startTime"]`/`["endTime"]` must be valid ISO 8601 timestamps — a batch with a missing or malformed resource name or timestamps is skipped entirely (logged as an error) rather than sent with a broken URL.
 - If `endTime` precedes `startTime` (e.g. clock skew), the batch is still logged — `duration_ms` is clamped to `0` and a warning is logged — rather than dropping the results.
+- Each item's `"request"` and `"response"` are capped separately by [`max_captured_body_bytes`](configuration.md#body-capture-limits): one over the limit is logged as a `{"_coolhand_capture_skipped" => "body_too_large", ...}` placeholder. (See [Body Capture Limits](configuration.md#body-capture-limits) for the other placeholders.) The results array is supplied by your code, so it is already in memory; only what is sent to Coolhand is capped.
 - Each element of the `batch_results` array passed to `.call` must be a `Hash` with a `"request"` and/or `"response"` key (the request/response body to log for that item — either key alone is accepted). Any other shape is treated as malformed and skipped, with the skip counted in a `Rails.logger.warn` summary rather than raised.
 
 ## Minimal example

data/lib/coolhand/base_interceptor.rb

@@ -13,6 +13,28 @@ module Coolhand
     # paths (interceptor + webhook forwarding) stay consistent.
     SENSITIVE_HEADER_PATTERN = /key|token|secret|signature|auth|passw|credential|bearer|jwt|session|cookie/i
 
+    # Rate-limit telemetry headers (OpenAI `x-ratelimit-remaining-tokens`, Anthropic
+    # `anthropic-ratelimit-input-tokens-reset`, ...) contain the word "token" but carry counts and
+    # reset times, not credentials, so redacting them only loses useful data. The vocabulary after
+    # `ratelimit` is closed (a lookalike such as `x-ratelimit-api-key` stays redacted), and the
+    # optional vendor prefix captured in group 1 must itself be free of sensitive words (see
+    # `safe_header?`), so `secret-ratelimit-remaining` stays redacted too. Checked against the
+    # downcased header name.
+    SAFE_HEADER_PATTERN =
+      /\A((?:[a-z0-9]+-){0,2})rate-?limit(?:-(?:limit|remaining|reset|requests|tokens|input|output))+\z/
+
+    # True when a header name should be redacted. Shared with LoggerService so both logging paths
+    # make the same call.
+    def sensitive_header?(name)
+      down = name.to_s.downcase
+      down.match?(SENSITIVE_HEADER_PATTERN) && !safe_header?(down)
+    end
+
+    def safe_header?(down_name)
+      match = SAFE_HEADER_PATTERN.match(down_name)
+      !match.nil? && !match[1].match?(SENSITIVE_HEADER_PATTERN)
+    end
+
     def sanitize_headers(headers)
       return {} if headers.nil?
 
@@ -37,7 +59,7 @@ module Coolhand
         headers.each { |k, v| h[k.to_s] = normalize_header_value(v) }
         h
       else
-        { "raw" => headers.to_s }
+        {} # fail closed: an unrecognised shape can't be checked header-by-header
       end
 
       raw ||= {} # in case to_hash raised and nothing was built
@@ -55,7 +77,7 @@ module Coolhand
           else
             "[REDACTED]"
           end
-        elsif key_down.match?(SENSITIVE_HEADER_PATTERN)
+        elsif sensitive_header?(key_down)
           sanitized[k] = "[REDACTED]"
         end
       end
@@ -78,7 +100,39 @@ module Coolhand
     # credential params used by AWS (X-Amz-Signature, X-Amz-Credential,
     # X-Amz-Security-Token) and Google Cloud (X-Goog-Signature,
     # X-Goog-Credential) storage APIs.
-    SENSITIVE_QUERY_PARAM_PATTERN = /key|token|secret|sig|credential|password|auth/i
+    SENSITIVE_QUERY_PARAM_PATTERN = Regexp.new(
+      %w[key token secret sig credential password auth jwt bearer session cookie passphrase ticket assertion].join("|"),
+      Regexp::IGNORECASE
+    )
+
+    # Param names that are sensitive but too short or generic to match as a substring without
+    # over-matching (`code` would hit `encoding`, `country_code`). Matched by whole name,
+    # case-insensitively: `code` (Azure Functions keys, OAuth authorization codes), `sas` (Azure
+    # SAS tokens), and `pwd`/`passwd`, which the `password` substring above does not cover.
+    SENSITIVE_QUERY_PARAM_EXACT_NAMES = %w[code sas pwd passwd pass sid otp].freeze
+
+    # Percent-encoded "[REDACTED]", the form the placeholder takes once inside a URL.
+    REDACTED_URL_VALUE = "%5BREDACTED%5D"
+
+    # A `;name=value` matrix parameter. In a path the value stops at the next path delimiter; in a
+    # query value "/" is legal inside a secret (base64), so the value runs to the next ";" or "&".
+    PATH_MATRIX_PARAM_PATTERN = %r{;([^/;?#=&]+)=([^/;?#&]*)}
+    QUERY_MATRIX_PARAM_PATTERN = /;([^;=&#]+)=([^;&#]*)/
+
+    def sensitive_query_param?(name)
+      decoded = begin
+        # scrub: a percent-escaped invalid byte (`%FF`) must not make the match below raise.
+        URI.decode_www_form_component(name).scrub
+      rescue ArgumentError
+        name.scrub
+      end
+      decoded.match?(SENSITIVE_QUERY_PARAM_PATTERN) || exact_sensitive_query_name?(decoded)
+    end
+
+    # Exact-name check that also sees through Rails/PHP bracket syntax: `code[]`, `auth[code]`.
+    def exact_sensitive_query_name?(decoded_name)
+      decoded_name.downcase.split(/[\[\]]+/).any? { |part| SENSITIVE_QUERY_PARAM_EXACT_NAMES.include?(part) }
+    end
 
     def sanitize_url(url)
       uri = URI.parse(url)
@@ -91,28 +145,57 @@ module Coolhand
         modified = true
       end
 
-      if uri.query
-        params = URI.decode_www_form(uri.query)
-        redacted_query = false
-        params.map! do |n, v|
-          if n.match?(SENSITIVE_QUERY_PARAM_PATTERN)
-            redacted_query = true
-            [n, "[REDACTED]"]
-          else
-            [n, v]
-          end
-        end
-        if redacted_query
-          uri.query = URI.encode_www_form(params)
-          modified = true
-        end
+      path = uri.path && redact_matrix_params(uri.path, PATH_MATRIX_PARAM_PATTERN)
+      if path != uri.path
+        uri.path = path
+        modified = true
+      end
+
+      query = uri.query && redact_query(uri.query)
+      if query != uri.query
+        uri.query = query
+        modified = true
+      end
+
+      # A fragment never reaches a server, but a caller-supplied URL can carry one (OAuth
+      # implicit flow puts `access_token=...` there), so drop it as the fallback below does.
+      if uri.fragment
+        uri.fragment = nil
+        modified = true
       end
 
       modified ? uri.to_s : url
     rescue URI::InvalidURIError
       # Fail closed: an unparseable URL can't be checked param-by-param, so drop everything
       # that could carry a credential (userinfo, query, fragment) rather than pass it through.
-      url.to_s.sub(%r{//[^/?#]*@}, "//REDACTED@").split(/[?#]/, 2).first
+      stripped = url.to_s.sub(%r{//[^/?#]*@}, "//REDACTED@").split(/[?#]/, 2).first
+      redact_matrix_params(stripped, PATH_MATRIX_PARAM_PATTERN)
+    end
+
+    def redact_matrix_params(text, pattern)
+      text.gsub(pattern) do |match|
+        sensitive_query_param?(Regexp.last_match(1)) ? ";#{Regexp.last_match(1)}=#{REDACTED_URL_VALUE}" : match
+      end
+    end
+
+    # Works on the raw query rather than decode_www_form so a bare segment (`?sk-abc123`) is not
+    # mistaken for an empty-valued param, and untouched segments pass through byte-for-byte.
+    def redact_query(query)
+      query.split("&", -1).map { |segment| redact_query_segment(segment) }.join("&")
+    end
+
+    def redact_query_segment(segment)
+      return segment if segment.empty?
+
+      # Matrix redaction first: in `x;code=S` the first "=" makes the "name" `x;code`, which would
+      # dodge the exact-name rule.
+      segment = redact_matrix_params(segment, QUERY_MATRIX_PARAM_PATTERN)
+      name, separator, = segment.partition("=")
+      # No "=": nothing says what this is, so a stray token could be a credential. Fail closed.
+      return REDACTED_URL_VALUE if separator.empty?
+      return "#{name}=#{REDACTED_URL_VALUE}" if sensitive_query_param?(name)
+
+      segment
     end
 
     # Key names inside an Azure OpenAI "On Your Data" data_sources/dataSources entry that carry
@@ -122,32 +205,46 @@ module Coolhand
     # (Elasticsearch) are caught — not just exact or snake_case-only names.
     SENSITIVE_BODY_KEY_PATTERN = /key|token|secret|passw|pwd|credential|bearer|jwt|connectionstring|signature/i
 
+    REDACTED = "[REDACTED]"
+
+    # Subtrees nested deeper than this are replaced wholesale rather than walked, so a pathological
+    # body can neither overflow the stack (SystemStackError is not a StandardError, so
+    # send_complete_request_log's rescue would not catch it) nor smuggle a credential past the walk.
+    MAX_BODY_DEPTH = 100
+
     def sanitize_body(body)
-      return body unless body.is_a?(Hash)
+      BodyRedactor.redact(body)
+    end
 
-      sanitized = body.dup
-      sanitized.each_key do |key|
-        next unless key.to_s.delete("_-").casecmp?("datasources")
+    def redact_sensitive_body_values(node, depth = 0)
+      return REDACTED if depth > MAX_BODY_DEPTH
 
-        sanitized[key] = redact_sensitive_body_values(sanitized[key])
+      case node
+      when Hash then redact_sensitive_body_hash(node, depth)
+      when Array then node.map { |v| redact_sensitive_body_values(v, depth + 1) }
+      when String then redact_embedded_url_credentials(node)
+      else node
       end
-      sanitized
     end
 
-    def redact_sensitive_body_values(node)
-      case node
-      when Hash
-        node.each_with_object({}) do |(k, v), acc|
-          normalized = k.to_s.gsub(/[_\-\s]/, "").downcase
-          acc[k] = normalized.match?(SENSITIVE_BODY_KEY_PATTERN) ? "[REDACTED]" : redact_sensitive_body_values(v)
-        end
-      when Array
-        node.map { |v| redact_sensitive_body_values(v) }
-      else
-        node
+    def redact_sensitive_body_hash(hash, depth)
+      hash.each_with_object({}) do |(k, v), acc|
+        normalized = k.to_s.gsub(/[_\-\s]/, "").downcase
+        acc[k] = normalized.match?(SENSITIVE_BODY_KEY_PATTERN) ? REDACTED : redact_sensitive_body_values(v, depth + 1)
       end
     end
 
+    # A single whitespace-free absolute URL, e.g. an Azure `endpoint` of `https://u:PASS@h/?sas=...`.
+    # Only applied to data_sources config and to the exact URL-valued body keys in BodyRedactor
+    # (never free text), where a URL value can carry userinfo or a SAS/key query param itself.
+    EMBEDDED_URL_PATTERN = %r{\A[a-z][a-z0-9+.-]*://\S+\z}i
+
+    def redact_embedded_url_credentials(value)
+      # JSON.parse accepts invalid UTF-8, which would make the regexp raise and drop the whole log.
+      value = value.scrub unless value.valid_encoding?
+      value.match?(EMBEDDED_URL_PATTERN) ? sanitize_url(value) : value
+    end
+
     def send_complete_request_log(request_id:, method:, url:, request_headers:, request_body:, response_headers:,
       response_body:, status_code:, start_time:, end_time:, duration_ms:, is_streaming:, source_api: nil, model: nil,
       declared: nil)
@@ -159,7 +256,7 @@ module Coolhand
         headers: sanitize_headers(request_headers),
         request_body: sanitize_body(request_body),
         response_headers: sanitize_headers(response_headers),
-        response_body: response_body,
+        response_body: sanitize_body(response_body),
         status_code: status_code,
         duration_ms: duration_ms,
         completed_at: end_time.iso8601,
@@ -181,6 +278,9 @@ module Coolhand
 
     def parse_json(string)
       JSON.parse(string)
+    rescue JSON::NestingError
+      # Too deep to walk for redaction; logging the raw string would skip BodyRedactor entirely.
+      { "_coolhand_capture_skipped" => "nesting_too_deep" }
     rescue JSON::ParserError, TypeError
       string
     end

data/lib/coolhand/batch_body_cap.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Coolhand
+  # Applies max_captured_body_bytes to the request/response bodies of batch items, the same way
+  # NetHttpInterceptor does for live requests: an oversized body is replaced by the body_too_large
+  # marker so the log entry (and the queued job holding it) stays small.
+  module BatchBodyCap
+    module_function
+
+    # Re-serializing a parsed number can write more bytes than the source had (depending on the json
+    # version, "1e9" becomes "1000000000.0" and "7e22" becomes "7.0000000000000004e+22"). Counting
+    # the separators around them, a body grows by well under this factor.
+    SERIALIZED_GROWTH = 6
+
+    # Returns the body, or the marker when its JSON size is over the cap. `source_size` is the byte
+    # size of the JSON the body was parsed from, when the caller has it (e.g. a JSONL line): a body
+    # that small even after SERIALIZED_GROWTH is within the cap without serializing it to measure.
+    def cap(body, source_size: nil)
+      return body if body.nil? || helpers.capture_limit.nil?
+      return body if source_size && !helpers.over_capture_limit?(source_size * SERIALIZED_GROWTH)
+
+      size = JSON.generate(body).bytesize
+      helpers.over_capture_limit?(size) ? helpers.body_too_large_marker(nil, size) : body
+    rescue JSON::NestingError
+      helpers.skipped_capture_marker(nil, "nesting_too_deep")
+    rescue JSON::JSONError
+      # NaN/Infinity or invalid UTF-8: it can't be logged either, and must not fail the other
+      # items of the batch.
+      helpers.skipped_capture_marker(nil, "unserializable_body")
+    end
+
+    def helpers
+      NetHttpInterceptor::Helpers
+    end
+  end
+end

data/lib/coolhand/body_redactor.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Coolhand
+  # Redacts credential-bearing values from request and response bodies before they are sent to
+  # Coolhand. Header and URL redaction live in BaseInterceptor; this covers the body.
+  module BodyRedactor
+    module_function
+
+    # Body keys whose *string* value is a credential in any request or response body, matched
+    # exactly (never as a substring) against the key lowercased with `_`, `-` and spaces removed,
+    # so `api_key`, `apiKey`, `API-Key` and `apikey` all match. Only String leaves are redacted:
+    # a JSON Schema property named `api_key` has a Hash value and is left alone, as is a numeric
+    # `usage.total_tokens`. Covers OpenAI Responses/Realtime MCP `tools[].authorization`, Anthropic
+    # `mcp_servers[].authorization_token`, and the legacy Realtime `client_secret` string form. Also
+    # covers `x-api-key`, AWS `aws_secret_access_key`/`secret_access_key`, `session_token`,
+    # `bearer_token` and any String under a generic `secret` key.
+    CREDENTIAL_BODY_KEYS = %w[
+      authorization authorizationtoken accesstoken refreshtoken idtoken
+      apikey clientsecret privatekey secretkey password
+      xapikey secret secretaccesskey awssecretaccesskey sessiontoken bearertoken
+    ].freeze
+
+    # Body keys whose *string* value is a URL that can carry credentials (MCP `server_url`, a
+    # presigned `image_url`/`file_url`, a datastore `endpoint`). Matched exactly like
+    # CREDENTIAL_BODY_KEYS, but the value is scrubbed with BaseInterceptor.sanitize_url instead of
+    # replaced, and only when it is a single absolute URL: prose that merely contains one is never
+    # touched. A bare `token` key is deliberately absent from both lists (logprobs use `{"token":"Hello"}`).
+    URL_BODY_KEYS = %w[url serverurl imageurl fileurl endpoint].freeze
+
+    def redact(body)
+      return StringBodyRedactor.redact(body) if body.is_a?(String)
+      return body unless body.is_a?(Hash) || body.is_a?(Array)
+
+      redact_body_node(body, 0)
+    end
+
+    def redact_body_node(node, depth, secret_object: false)
+      return BaseInterceptor::REDACTED if depth > BaseInterceptor::MAX_BODY_DEPTH
+
+      case node
+      when Hash then redact_body_hash(node, depth, secret_object: secret_object)
+      when Array then node.map { |v| redact_body_node(v, depth + 1) }
+      else node
+      end
+    end
+
+    # `secret_object` marks the object under a `client_secret` key (legacy Realtime
+    # `{value, expires_at}`), whose `value` is the ephemeral key.
+    def redact_body_hash(hash, depth, secret_object: false)
+      context = { secret_value: secret_object || ephemeral_secret?(hash), mcp: mcp_tool?(hash) }
+      hash.each_with_object({}) do |(key, value), acc|
+        acc[key] = redact_body_entry(normalize_body_key(key), value, depth, context)
+      end
+    end
+
+    def redact_body_entry(name, value, depth, context)
+      if name == "datasources"
+        BaseInterceptor.redact_sensitive_body_values(value, depth + 1)
+      elsif value.is_a?(String)
+        redact_string_value(name, value, context)
+      elsif name == "headers" && context[:mcp]
+        redact_header_values(value, depth + 1)
+      elsif name == "clientsecret" && value.is_a?(Hash)
+        redact_body_node(value, depth + 1, secret_object: true)
+      else
+        redact_body_node(value, depth + 1)
+      end
+    end
+
+    def redact_string_value(name, value, context)
+      return BaseInterceptor::REDACTED if redact_string_leaf?(name, context)
+
+      URL_BODY_KEYS.include?(name) ? BaseInterceptor.redact_embedded_url_credentials(value) : value
+    end
+
+    def redact_string_leaf?(name, context)
+      CREDENTIAL_BODY_KEYS.include?(name) || (context[:secret_value] && name == "value")
+    end
+
+    def normalize_body_key(key)
+      key.to_s.delete("_ -").downcase # trailing "-" is a literal hyphen, not a range
+    end
+
+    # Realtime GA `POST /v1/realtime/client_secrets` returns `{"value": "ek_...", "expires_at": 123,
+    # "session": {...}}`. `value` alone is far too generic to redact by name, so require the
+    # numeric `expires_at` that accompanies it.
+    def ephemeral_secret?(hash)
+      hash_value(hash, "value").is_a?(String) && hash_value(hash, "expires_at").is_a?(Numeric)
+    end
+
+    # An OpenAI remote-MCP tool (`type: "mcp"`, or any entry carrying a `server_url`), whose
+    # `headers` map holds authentication headers. A bare `headers` key elsewhere is left alone.
+    def mcp_tool?(hash)
+      hash_value(hash, "type") == "mcp" || !hash_value(hash, "server_url").nil?
+    end
+
+    # String values are the credentials; anything else (a malformed nested shape) goes back through
+    # the generic walk so it is still depth-limited and credential-key checked.
+    def redact_header_values(headers, depth)
+      return redact_body_node(headers, depth) unless headers.is_a?(Hash)
+
+      headers.transform_values do |v|
+        v.is_a?(String) ? BaseInterceptor::REDACTED : redact_body_node(v, depth + 1)
+      end
+    end
+
+    def hash_value(hash, name)
+      hash.fetch(name) { hash[name.to_sym] }
+    end
+  end
+end

data/lib/coolhand/body_stream_tap.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Coolhand
+  module NetHttpInterceptor
+    # Stands in for a request's body_stream while Net::HTTP sends it, copying the bytes that pass
+    # through into a buffer capped at max_captured_body_bytes. The host's stream is read exactly
+    # once, by Net::HTTP, in the same chunks as without the gem; nothing is read ahead, buffered in
+    # full or rewound. Past the cap the buffer is dropped and only a byte count is kept, so memory
+    # stays bounded however large the upload is.
+    #
+    # Deliberately exposes nothing but #read (and #readpartial, only when the source has it): a
+    # delegating wrapper would also expose #to_io/#to_path, which IO.copy_stream uses to read the
+    # underlying file directly, bypassing the tap.
+    class BodyStreamTap
+      attr_reader :source, :bytes_seen
+
+      # IO.copy_stream also accepts a path (String) or a Pathname as its source, reading the file
+      # itself; the tap only offers #read, which those don't support, so they are left untouched.
+      def self.tappable?(stream)
+        stream.respond_to?(:read) && !stream.is_a?(String) &&
+          (stream.respond_to?(:to_io) || !stream.respond_to?(:to_path))
+      end
+
+      def self.install(req)
+        tap = new(req.body_stream)
+        req.body_stream = tap
+        tap
+      end
+
+      def initialize(source)
+        @source = source
+        @buffer = +"".b
+        @bytes_seen = 0
+        @eof = false
+        @failed = false
+        define_singleton_method(:readpartial) { |*args| read_partial(*args) } if source.respond_to?(:readpartial)
+      end
+
+      def read(*args)
+        data = @source.read(*args)
+        record(data, finished: end_of_stream?(args, data))
+        data
+      end
+
+      # Whether the source has been read to its end (not IO#eof?: false until a read hits the end).
+      def reached_end?
+        @eof
+      end
+
+      # The capture itself failed (not the host's stream); the request body is simply not logged.
+      def failed?
+        @failed
+      end
+
+      def overflowed?
+        @buffer.nil? && !@failed
+      end
+
+      def body
+        @buffer&.dup&.force_encoding(Encoding::UTF_8)
+      end
+
+      # Puts the host's own stream back, unless something else has replaced the tap since.
+      def restore_stream(req)
+        req.body_stream = @source if req.body_stream.equal?(self)
+      end
+
+      # The request body for the log once the request has been attempted. Over the cap is known
+      # from the bytes seen so far, even if the stream was not fully sent. Otherwise a stream that
+      # never reached its end (the request failed first) has no complete body.
+      def body_for_log(req)
+        return if failed?
+        return helpers.body_too_large_marker(req, bytes_seen) if overflowed?
+        return incomplete_marker(req) unless reached_end?
+
+        BaseInterceptor.parse_json(body)
+      end
+
+      private
+
+      # Reading everything, or getting nothing back from a read for a positive length (IO.copy_stream
+      # also treats an empty String there as the end).
+      def end_of_stream?(args, data)
+        length = args.first
+        length.nil? || data.nil? || (length.positive? && data.empty?)
+      end
+
+      def helpers
+        NetHttpInterceptor::Helpers
+      end
+
+      def incomplete_marker(req)
+        helpers.skipped_capture_marker(req, "body_stream_incomplete", size_bytes: bytes_seen)
+      end
+
+      def read_partial(*args)
+        data = @source.readpartial(*args)
+        record(data)
+        data
+      rescue EOFError
+        @eof = true
+        raise
+      end
+
+      # Runs inside the host's request send: whatever goes wrong here must never reach the host.
+      def record(data, finished: false)
+        @eof ||= finished
+        return unless data.is_a?(String)
+
+        @bytes_seen += data.bytesize
+        return unless @buffer
+
+        @buffer = helpers.over_capture_limit?(@bytes_seen) ? nil : @buffer << data.b
+      rescue StandardError => e
+        @failed = true
+        @buffer = nil
+        Coolhand.log "❌ Error capturing request body_stream: #{e.message}"
+      end
+    end
+  end
+end

data/lib/coolhand/default_intercept_addresses.yml

@@ -23,7 +23,15 @@
 - "models.inference.ai.azure.com"
 - "aiplatform.googleapis.com"
 - "gateway.ai.cloudflare.com"
+# Amazon Bedrock. Every endpoint variant needs its own entry: a wildcard entry is
+# an exact host match with no implicit subdomains, and "amazonaws.com.cn" is not a
+# dot-boundary suffix of "amazonaws.com". "api.aws" hosts are the dual-stack (IPv6)
+# endpoints; "-fips" hosts are the FIPS 140-3 ones, used by GovCloud callers.
 - "bedrock-runtime.*.amazonaws.com"
+- "bedrock-runtime.*.amazonaws.com.cn"
+- "bedrock-runtime-fips.*.amazonaws.com"
+- "bedrock-runtime.*.api.aws"
+- "bedrock-runtime-fips.*.api.aws"
 - "api.deepseek.com"
 - "api.mistral.ai"
 - "api.perplexity.ai"