coolhand 0.10.0 → 0.10.1

data/lib/coolhand/open_ai/webhook_validator.rb

@@ -20,6 +20,7 @@ module Coolhand
 
       def valid?
         @errors.clear
+        @claimed_id = nil
         @payload = request.raw_post || request.body.read
 
         return false unless payload_valid?
@@ -28,7 +29,9 @@ module Coolhand
         secret_bytes = extract_secret_bytes
         webhook_signature, webhook_timestamp, webhook_id = extract_webhook_headers
 
-        return validate_headers_in_non_production_env unless webhook_signature && webhook_timestamp && webhook_id
+        unless webhook_signature && webhook_timestamp && webhook_id
+          return reject_unsigned("Missing OpenAI webhook signature, timestamp, or id headers")
+        end
 
         verify_signature(webhook_signature, webhook_timestamp, webhook_id, secret_bytes)
       end
@@ -37,12 +40,29 @@ module Coolhand
         @errors.join(", ")
       end
 
+      # Gives back the webhook-id claim made by the last successful `valid?` so a same-id retry
+      # (e.g. after processing failed) isn't rejected as a replay. A no-op when nothing was claimed
+      # or when the store has no `release!` (custom stores may implement only `claim!`).
+      def release_claim!
+        claimed_id = @claimed_id
+        return unless claimed_id
+
+        @claimed_id = nil
+        id_store.release!(claimed_id) if id_store.respond_to?(:release!)
+      rescue StandardError => e
+        # Best effort: a failing store must not stop the caller from rejecting the request.
+        Rails.logger.error("OpenAI webhook id release failed: #{e.message}")
+      end
+
       private
 
       attr_reader :webhook_secret
 
+      # Only a nil payload counts as missing. An empty string is a real (empty) body, so it continues
+      # to the signature check, where it is accepted only if it was actually signed.
       def payload_valid?
         return true if @payload
+        return reject_unsigned("Empty webhook payload") if Coolhand.required_field?(webhook_secret)
 
         enforce_or_allow("Empty webhook payload",
           "Empty webhook payload - allowing in #{Rails.env} environment")
@@ -57,10 +77,8 @@ module Coolhand
       # check is skipped with a warning.
       def enforce_or_allow(problem, allow_warning)
         if should_enforce_strict_validation?
-          @errors << "#{problem} - rejecting webhook (Rails.env=#{Rails.env.inspect} " \
-                     "not in development/test allowlist)"
-          Rails.logger.error(@errors.last)
-          false
+          reject("#{problem} - rejecting webhook (Rails.env=#{Rails.env.inspect} " \
+                 "not in development/test allowlist)")
         else
           Rails.logger.warn(allow_warning)
           true
@@ -83,16 +101,15 @@ module Coolhand
         [webhook_signature, webhook_timestamp, webhook_id]
       end
 
-      def validate_headers_in_non_production_env
-        if should_enforce_strict_validation?
-          @errors << "Missing OpenAI webhook signature, timestamp, or id headers - " \
-                     "rejecting webhook (Rails.env=#{Rails.env.inspect} not in development/test allowlist)"
-          Rails.logger.error(@errors.last)
-          false
-        else
-          Rails.logger.warn("Missing OpenAI webhook headers - skipping verification in #{Rails.env}")
-          true
-        end
+      # A secret is configured, so anything that can't be verified is rejected in every environment.
+      def reject_unsigned(problem)
+        reject("#{problem} - rejecting webhook")
+      end
+
+      def reject(message)
+        @errors << message
+        Rails.logger.error(message)
+        false
       end
 
       def verify_signature(webhook_signature, webhook_timestamp, webhook_id, secret_bytes)
@@ -102,11 +119,7 @@ module Coolhand
         # An empty key (a bare "whsec_" secret) makes the HMAC forgeable by anyone, so never accept it.
         signature_valid = !secret_bytes.empty? && signature_matches?(webhook_signature, expected_signature)
 
-        unless signature_valid
-          @errors << "OpenAI webhook signature verification failed"
-          Rails.logger.error(@errors.last)
-          return false
-        end
+        return reject("OpenAI webhook signature verification failed") unless signature_valid
 
         return false unless timestamp_fresh?(webhook_timestamp)
         return false unless webhook_id_unused?(webhook_id)
@@ -134,18 +147,20 @@ module Coolhand
         age = (Time.now.to_i - webhook_timestamp.to_i).abs
         return true if age <= tolerance
 
-        @errors << "OpenAI webhook timestamp outside replay-protection tolerance window"
-        Rails.logger.error(@errors.last)
-        false
+        reject("OpenAI webhook timestamp outside replay-protection tolerance window")
       end
 
+      # The timestamp check accepts anything within +/- tolerance of now, so a request stamped
+      # `now + tolerance` stays fresh until `now + 2 * tolerance`. Remember the id for twice the
+      # tolerance so it can't be replayed after its claim expires but while it is still fresh.
       def webhook_id_unused?(webhook_id)
-        tolerance = Coolhand.configuration.webhook_replay_tolerance_seconds
-        return true if id_store.claim!(webhook_id, tolerance)
+        ttl = Coolhand.configuration.webhook_replay_tolerance_seconds * 2
+        if id_store.claim!(webhook_id, ttl)
+          @claimed_id = webhook_id
+          return true
+        end
 
-        @errors << "OpenAI webhook id already processed (replay protection)"
-        Rails.logger.error(@errors.last)
-        false
+        reject("OpenAI webhook id already processed (replay protection)")
       end
 
       def id_store

data/lib/coolhand/path_normalizer.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Coolhand
+  module PathNormalizer
+    UNRESERVED_CHAR = /\A[A-Za-z0-9\-._~]\z/
+    private_constant :UNRESERVED_CHAR
+
+    module_function
+
+    # Path used for matching only (the URL that is sent and logged is never touched), so
+    # sloppy joins like "/openai//files", "/openai/./files", "/openai/%66iles" or
+    # "/v2/chat/../../v1/rerank" can't slip past an exclude pattern or a path anchor.
+    # Decodes unreserved-character escapes (%2F and other reserved escapes stay encoded, and
+    # decoding is one pass, so "%252e" stays literal), collapses repeated "/", and resolves
+    # "." and ".." segments without ever climbing above the root. Case is left as is. A path
+    # that can't be normalized falls back to the raw one rather than raising, and an empty
+    # path comes back as "/".
+    def normalize(path)
+      decoded = path.gsub(/%\h\h/) do |escape|
+        char = escape[1, 2].hex.chr
+        UNRESERVED_CHAR.match?(char) ? char : escape
+      end
+      segments = decoded.split("/").each_with_object([]) do |segment, kept|
+        case segment
+        when "", "." then next
+        when ".." then kept.pop
+        else kept << segment
+        end
+      end
+      directory = !segments.empty? && decoded.end_with?("/", "/.", "/..")
+      "/#{segments.join('/')}#{'/' if directory}"
+    rescue StandardError
+      path
+    end
+  end
+end

data/lib/coolhand/string_body_redactor.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Coolhand
+  # Redacts credentials in raw String bodies, which BodyRedactor's tree walk never sees: a streamed
+  # (server-sent event) response arrives as one String of `data: {...}` lines, and a webhook body
+  # may be raw JSON text. Each JSON object/array payload is parsed, run through BodyRedactor and
+  # re-serialized; text that is not JSON (plain text, `[DONE]`, `event:` and comment lines, a
+  # payload that fails to parse) is left byte for byte. A JSON payload is always re-serialized, even
+  # when nothing in it needed redacting: JSON.parse keeps only the last of a repeated key, so
+  # "nothing changed" cannot be trusted to mean "no credential in the original text".
+  module StringBodyRedactor
+    module_function
+
+    NESTING_MARKER = { "_coolhand_capture_skipped" => "nesting_too_deep" }.freeze
+    FAILED_MARKER = { "_coolhand_capture_skipped" => "redaction_failed" }.freeze
+
+    # A `data:` field at the start of a line (LF, CRLF or bare CR), or after a byte order mark,
+    # which the SSE spec ignores. Whitespace after the colon is captured apart from the payload so
+    # a rewritten line keeps its own.
+    DATA_LINE = /(?<![^\r\n\uFEFF])data:([ \t]*)([^\r\n]*)/
+    JSON_CONTAINER = /\A\uFEFF?\s*[\[{]/
+
+    def redact(body)
+      text = utf8_text(body)
+      json = redacted_json(text) if text.match?(JSON_CONTAINER)
+      json || redact_stream(body, text)
+    rescue StandardError => e
+      # Fail closed: never log a body that could not be checked. The message is left out because
+      # a parser error can quote the payload.
+      Coolhand.log "❌ Error redacting string body: #{e.class}"
+      FAILED_MARKER
+    end
+
+    # Captured bodies are UTF-8, but a binary-tagged, other-encoded or invalid-UTF-8 String (a
+    # webhook body can be any of them) is not worth a failure: inspect a UTF-8 working copy, with
+    # invalid bytes replaced, so every line can still be checked.
+    def utf8_text(body)
+      text = case body.encoding
+             when Encoding::UTF_8 then body
+             when Encoding::BINARY then body.dup.force_encoding(Encoding::UTF_8)
+             else body.encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+      end
+      text.valid_encoding? ? text : text.scrub
+    end
+
+    # One pass with gsub (linear in the body); the original String is returned when no line differs
+    # once re-serialized (providers emit compact JSON, so a clean stream usually round-trips as is).
+    def redact_stream(body, text)
+      changed = false
+      redacted = text.gsub(DATA_LINE) do |line|
+        match = Regexp.last_match
+        payload = match[2].match?(JSON_CONTAINER) ? redacted_json(match[2]) : nil
+        next line if payload.nil? || payload == match[2]
+
+        changed = true
+        "data:#{match[1]}#{payload}"
+      end
+      changed ? redacted : body
+    end
+
+    # The redacted, re-serialized JSON; nil when the text should stay as is (not a JSON
+    # object/array, or unparsable). Anything else that goes wrong yields a `redaction_failed`
+    # marker rather than the unchecked text.
+    def redacted_json(text)
+      # NaN/Infinity are not JSON, but some servers emit them; a payload that failed to parse
+      # would be logged unredacted next to its credential-named fields.
+      parsed = JSON.parse(text.delete_prefix("\uFEFF"), allow_nan: true)
+      return unless parsed.is_a?(Hash) || parsed.is_a?(Array)
+
+      redacted = BodyRedactor.redact(parsed)
+      JSON.generate(redacted, allow_nan: true)
+    rescue JSON::NestingError
+      JSON.generate(NESTING_MARKER)
+    rescue JSON::ParserError
+      nil
+    rescue StandardError => e
+      # e.g. a string with a lone surrogate that parses but cannot be serialized: fail closed for
+      # this payload alone so the rest of the body is still redacted.
+      Coolhand.log "❌ Error redacting JSON payload: #{e.class}"
+      JSON.generate(FAILED_MARKER)
+    end
+  end
+end

data/lib/coolhand/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Coolhand
-  VERSION = "0.10.0"
+  VERSION = "0.10.1"
 end

data/lib/coolhand/vertex/batch_result_processor.rb

@@ -111,9 +111,9 @@ module Coolhand
           source_api: SOURCE_API,
           model: model,
           request_headers: {},
-          request_body: batch_item["request"],
+          request_body: BatchBodyCap.cap(batch_item["request"]),
           response_headers: {},
-          response_body: batch_item["response"],
+          response_body: BatchBodyCap.cap(batch_item["response"]),
           status_code: 200,
           start_time: start_time,
           end_time: end_time,

data/lib/coolhand/webhook_interceptor.rb

@@ -5,6 +5,27 @@ require_relative "open_ai/batch_result_processor"
 
 module Coolhand
   module WebhookInterceptor
+    # Helpers that must never be routable as controller actions.
+    HELPER_METHODS = %w[intercept_batch_request webhook_secret process_event].freeze
+    private_constant :HELPER_METHODS
+
+    # `private` below only covers the definitions in this module. A host that
+    # re-defines `webhook_secret` or `process_event` as public would make them
+    # public again, and Rails would then count them as action methods. Filtering
+    # them out of `action_methods` keeps them unroutable either way, without this
+    # gem depending on Rails (`super` is Rails' own `action_methods`).
+    module ClassMethods
+      def action_methods
+        super - HELPER_METHODS
+      end
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    private
+
     def intercept_batch_request
       Rails.logger.info("[Interceptor] #{controller_name}##{action_name}")
 
@@ -27,6 +48,8 @@ module Coolhand
       # let the controller action run for a request whose webhook
       # signature was never confirmed valid.
       Rails.logger.error("[Interceptor] Failed to intercept batch request: #{e.message}")
+      # Give the webhook-id back so the sender's retry isn't rejected as a replay.
+      @validator&.release_claim!
       head :unauthorized
       false
     end

data/lib/coolhand.rb

@@ -14,15 +14,18 @@ require_relative "coolhand/declared_context"
 require_relative "coolhand/declarable"
 require_relative "coolhand/rails_auto_declare"
 require_relative "coolhand/log_queue"
+require_relative "coolhand/body_redactor"
+require_relative "coolhand/string_body_redactor"
 require_relative "coolhand/base_interceptor"
 require_relative "coolhand/net_http_interceptor"
+require_relative "coolhand/batch_body_cap"
 require_relative "coolhand/api_service"
 require_relative "coolhand/logger_service"
 require_relative "coolhand/feedback_service"
 require_relative "coolhand/template_service"
 require_relative "coolhand/optimization_feedback_link_service"
 require_relative "coolhand/workload_service"
-require_relative "coolhand/public_content_service"
+require_relative "coolhand/help_center_service"
 require_relative "coolhand/log_service"
 require_relative "coolhand/webhook_interceptor"
 # Only when Rails is already loaded; the gem has no Rails dependency.
@@ -148,10 +151,10 @@ module Coolhand
       LogService.new
     end
 
-    # Creates a new PublicContentService, for reading the Coolhand help center. Needs no API key; a
+    # Creates a new HelpCenterService, for reading the Coolhand help center. Needs no API key; a
     # configured one is sent and lifts the anonymous rate limit.
-    def public_content_service
-      PublicContentService.new
+    def help_center_service
+      HelpCenterService.new
     end
 
     # Creates a new OptimizationFeedbackLinkService instance, for linking feedback to an

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: coolhand
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.10.1
 platform: ruby
 authors:
 - Michael Carroll
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-21 00:00:00.000000000 Z
+date: 2026-10-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -60,6 +60,9 @@ files:
 - lib/coolhand.rb
 - lib/coolhand/api_service.rb
 - lib/coolhand/base_interceptor.rb
+- lib/coolhand/batch_body_cap.rb
+- lib/coolhand/body_redactor.rb
+- lib/coolhand/body_stream_tap.rb
 - lib/coolhand/collector.rb
 - lib/coolhand/configuration.rb
 - lib/coolhand/declarable.rb
@@ -69,6 +72,7 @@ files:
 - lib/coolhand/default_intercept_path_patterns.yml
 - lib/coolhand/errors.rb
 - lib/coolhand/feedback_service.rb
+- lib/coolhand/help_center_service.rb
 - lib/coolhand/log_queue.rb
 - lib/coolhand/log_service.rb
 - lib/coolhand/logger_service.rb
@@ -78,12 +82,13 @@ files:
 - lib/coolhand/open_ai/webhook_validator.rb
 - lib/coolhand/optimization_feedback_link_service.rb
 - lib/coolhand/pagination.rb
-- lib/coolhand/public_content_service.rb
+- lib/coolhand/path_normalizer.rb
 - lib/coolhand/rails_auto_declare.rb
 - lib/coolhand/railtie.rb
 - lib/coolhand/read_query.rb
 - lib/coolhand/read_requests.rb
 - lib/coolhand/response_warnings.rb
+- lib/coolhand/string_body_redactor.rb
 - lib/coolhand/template_service.rb
 - lib/coolhand/version.rb
 - lib/coolhand/vertex/batch_result_processor.rb