coolhand 0.5.1 → 0.6.0

data/lib/coolhand/open_ai/webhook_validator.rb

@@ -2,6 +2,8 @@
 
 require "openssl"
 
+require_relative "webhook_id_store"
+
 module Coolhand
   module OpenAi
     class WebhookValidator
@@ -23,7 +25,7 @@ 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
+        return validate_headers_in_non_production_env unless webhook_signature && webhook_timestamp && webhook_id
 
         verify_signature(webhook_signature, webhook_timestamp, webhook_id, secret_bytes)
       end
@@ -40,7 +42,8 @@ module Coolhand
         return true if @payload
 
         if should_enforce_strict_validation?
-          @errors << "Empty webhook payload - rejecting webhook in production/staging"
+          @errors << "Empty webhook payload - rejecting webhook (Rails.env=#{Rails.env.inspect} " \
+                     "not in development/test allowlist)"
           Rails.logger.error(@errors.last)
           false
         else
@@ -51,7 +54,8 @@ module Coolhand
 
       def validate_in_non_production_env
         if should_enforce_strict_validation?
-          @errors << "OpenAI webhook secret not configured - rejecting webhook in production/staging"
+          @errors << "OpenAI webhook secret not configured - rejecting webhook (Rails.env=#{Rails.env.inspect} " \
+                     "not in development/test allowlist)"
           Rails.logger.error(@errors.last)
           false
         else
@@ -80,8 +84,8 @@ module Coolhand
 
       def validate_headers_in_non_production_env
         if should_enforce_strict_validation?
-          @errors << "Missing OpenAI webhook signature or timestamp headers - " \
-                     "rejecting webhook in production/staging"
+          @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
@@ -96,13 +100,43 @@ module Coolhand
 
         signature_valid = webhook_signature.start_with?("v1,") &&
                           secure_compare(webhook_signature[3..], expected_signature)
-        if signature_valid
-          true
-        else
+
+        unless signature_valid
           @errors << "OpenAI webhook signature verification failed"
           Rails.logger.error(@errors.last)
-          false
+          return false
         end
+
+        return false unless timestamp_fresh?(webhook_timestamp)
+        return false unless webhook_id_unused?(webhook_id)
+
+        true
+      end
+
+      # Checked only after the signature is confirmed valid, so an
+      # unsigned/forged request can't poison the id-dedup store (or fail a
+      # freshness check) and DoS a later legitimate webhook with the same id.
+      def timestamp_fresh?(webhook_timestamp)
+        tolerance = Coolhand.configuration.webhook_replay_tolerance_seconds
+        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
+      end
+
+      def webhook_id_unused?(webhook_id)
+        tolerance = Coolhand.configuration.webhook_replay_tolerance_seconds
+        return true if id_store.claim!(webhook_id, tolerance)
+
+        @errors << "OpenAI webhook id already processed (replay protection)"
+        Rails.logger.error(@errors.last)
+        false
+      end
+
+      def id_store
+        Coolhand.configuration.webhook_id_store
       end
 
       def secure_compare(a, b)
@@ -124,7 +158,7 @@ module Coolhand
       end
 
       def should_enforce_strict_validation?
-        ["production", "staging"].include?(Rails.env)
+        !%w[development test].include?(Rails.env)
       end
     end
   end

data/lib/coolhand/pagination.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Coolhand
+  # Paging state for a v2 list endpoint. These send a bare JSON array and carry paging in the
+  # `X-Page`, `X-Per-Page`, `X-Total-Count` and `X-Total-Pages` headers, never in the body.
+  Pagination = Struct.new(
+    :current_page,
+    :per_page,
+    :total_count,
+    :total_pages,
+    :has_next_page,
+    :has_prev_page,
+    keyword_init: true
+  )
+
+  class Pagination
+    # Mirrors of the v2 controllers' values, used only to fill a header the server did not send.
+    DEFAULT_PER_PAGE = 25
+    MAX_PER_PAGE = 100
+
+    class << self
+      def from_headers(response, items:, page: nil, per: nil)
+        requested_page = positive_int(page) || 1
+        requested_per = [positive_int(per) || DEFAULT_PER_PAGE, MAX_PER_PAGE].min
+
+        current_page = header_int(response, "X-Page") || requested_page
+        per_page = header_int(response, "X-Per-Page") || requested_per
+        reported_total_pages = header_int(response, "X-Total-Pages")
+        total_count = header_int(response, "X-Total-Count") || fallback_total_count(current_page, per_page, items)
+        total_pages = reported_total_pages || fallback_total_pages(total_count, per_page)
+
+        new(
+          current_page: current_page,
+          per_page: per_page,
+          total_count: total_count,
+          total_pages: total_pages,
+          has_next_page: next_page?(reported_total_pages, current_page, per_page, items),
+          has_prev_page: current_page > 1
+        ).freeze
+      end
+
+      private
+
+      # Falling back to the computed totals here would report "no next page" for a full page, and
+      # silently truncate a caller's loop.
+      def next_page?(reported_total_pages, current_page, per_page, items)
+        return current_page < reported_total_pages if reported_total_pages
+        return false unless per_page.positive?
+
+        items.size >= per_page
+      end
+
+      # A lower bound, not a count: every earlier page assumed full, plus this page.
+      def fallback_total_count(current_page, per_page, items)
+        return items.size unless per_page.positive?
+
+        [((current_page - 1) * per_page) + items.size, items.size].max
+      end
+
+      def fallback_total_pages(total_count, per_page)
+        return total_count.positive? ? 1 : 0 unless per_page.positive?
+
+        (total_count.to_f / per_page).ceil
+      end
+
+      # Neither `Integer()` nor `to_i` is safe alone: the first raises on `""`, the second turns
+      # `"3.5"` into `3` and `"nonsense"` into `0` — a fabricated, legitimate-looking count.
+      def header_int(response, name)
+        raw = response[name]
+        return nil if raw.nil?
+
+        value = raw.strip
+        value.match?(/\A\d+\z/) ? value.to_i : nil
+      end
+
+      def positive_int(value)
+        integer = Integer(value, exception: false)
+        integer&.positive? ? integer : nil
+      end
+    end
+  end
+end

data/lib/coolhand/read_requests.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require_relative "errors"
+
+module Coolhand
+  # The GET half of {ApiService}, split out to keep that class inside this repo's 200-line budget.
+  #
+  # Reads raise where writes log-and-return-nil, on purpose: a write is instrumentation inline in
+  # the host app's request, while a read's caller must tell a 404 from a timeout from an empty result.
+  module ReadRequests
+    # 60s is deliberate, not a slip: writes allow 5, but the server bounds each *statement* at 10s
+    # and one response runs several. A tighter read timeout pre-empts the 504 callers should retry.
+    READ_OPEN_TIMEOUT = 5
+    READ_TIMEOUT = 60
+
+    # ERROR_BODY_LIMIT caps the message; this caps the body the exception object itself carries.
+    RETAINED_ERROR_BODY_LIMIT = 8_000
+
+    protected
+
+    def get_json(url, noun)
+      body, = get_json_with_headers(url, noun)
+      body
+    end
+
+    # Also returns the response, for endpoints that carry pagination in headers rather than the body.
+    def get_json_with_headers(url, noun)
+      raise Error, "#{noun} request failed: an API key is required" unless Coolhand.required_field?(api_key)
+
+      response = perform_get(url, noun)
+
+      unless response.is_a?(Net::HTTPSuccess)
+        raise HttpError.new(
+          "#{noun} request failed (#{response.code}): #{format_error_body(response.body)}",
+          status: response.code.to_i,
+          body: retained_error_body(response.body)
+        )
+      end
+
+      [parse_json_body(response.body, noun), response]
+    end
+
+    private
+
+    def perform_get(url, noun)
+      uri = url.is_a?(URI::Generic) ? url : URI.parse(url.to_s)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == "https")
+      http.open_timeout = READ_OPEN_TIMEOUT
+      http.read_timeout = READ_TIMEOUT
+
+      request = Net::HTTP::Get.new(uri.request_uri)
+      apply_headers(request, "Accept" => "application/json", "X-API-Key" => api_key)
+
+      # Net::HTTP does not follow redirects, so a 3xx raises rather than replaying the API key at
+      # an unapproved host. without_capture is the same recursion guard send_request uses.
+      Coolhand.without_capture { http.request(request) }
+    rescue StandardError => e
+      raise Error, "#{noun} request failed: #{e.message}"
+    end
+
+    def retained_error_body(body)
+      return body if body.nil? || body.length <= RETAINED_ERROR_BODY_LIMIT
+
+      "#{body[0, RETAINED_ERROR_BODY_LIMIT]}... [truncated]"
+    end
+
+    def parse_json_body(body, noun)
+      JSON.parse(body.to_s, symbolize_names: true)
+    rescue JSON::ParserError
+      raise Error, "#{noun} response was not valid JSON: #{format_error_body(body)}"
+    end
+  end
+end

data/lib/coolhand/template_service.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "uri"
+require_relative "api_service"
+require_relative "pagination"
+
+module Coolhand
+  # Rows stay plain Symbol-keyed Hashes so a field the server adds later is not dropped in transit.
+  TemplateSearchResult = Struct.new(:templates, :pagination, keyword_init: true)
+
+  # Read-only. Requires the client's **private** key — the public key is write-only here and is
+  # rejected like an invalid one.
+  #
+  # Not a port of the MCP `search_templates` tool and does not agree with its `log_count`.
+  # See docs/template-search.md.
+  class TemplateService < ApiService
+    ERROR_NOUN = "Template"
+    BLANK_ID_MESSAGE = "get_template: id must be a non-empty template hashid"
+
+    def initialize
+      super("v2/llm_request_templates")
+    end
+
+    # Filters, error semantics and server behaviour: docs/template-search.md.
+    def search_templates(search: nil, workload_id: nil, status: nil, include_deprecated: nil,
+      include_system: nil, page: nil, per: nil)
+      query = {
+        search: search,
+        workload_id: workload_id,
+        status: status,
+        include_deprecated: include_deprecated,
+        include_system: include_system,
+        page: page,
+        per: per
+      }.compact
+
+      templates, response = get_json_with_headers(list_url(query), ERROR_NOUN)
+      raise Error, "#{ERROR_NOUN} response was not a JSON array" unless templates.is_a?(Array)
+
+      TemplateSearchResult.new(
+        templates: templates,
+        pagination: Pagination.from_headers(response, items: templates, page: page, per: per)
+      ).freeze
+    end
+
+    # Adds `user_prompt_pattern` / `system_prompt_pattern`, which the list omits, and unlike the
+    # list reaches deprecated and system templates by id with no opt-in flag.
+    def get_template(id)
+      get_json(resource_url(id), ERROR_NOUN)
+    end
+
+    private
+
+    def list_url(query)
+      uri = URI.parse(api_endpoint)
+      uri.query = URI.encode_www_form(query) unless query.empty?
+      uri
+    end
+
+    def resource_url(id)
+      raise Error, BLANK_ID_MESSAGE unless id.is_a?(String)
+
+      trimmed = id.strip
+      # A blank id resolves to the index route (bare array, not one template); a bare dot segment
+      # retargets the request at another path. Neither would 404, so both are rejected here.
+      raise Error, BLANK_ID_MESSAGE if trimmed.empty? || [".", ".."].include?(trimmed)
+
+      URI.parse("#{api_endpoint}/#{escape_path_segment(trimmed)}")
+    end
+
+    # Escapes to RFC 3986 unreserved, so an id carrying `/`, `?` or `#` cannot retarget the request.
+    def escape_path_segment(value)
+      URI::DEFAULT_PARSER.escape(value, /[^A-Za-z0-9\-._~]/)
+    end
+  end
+end

data/lib/coolhand/version.rb

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

data/lib/coolhand.rb

@@ -6,6 +6,7 @@ require "json"
 require "base64"
 require "time"
 
+require_relative "coolhand/errors"
 require_relative "coolhand/version"
 require_relative "coolhand/configuration"
 require_relative "coolhand/collector"
@@ -14,13 +15,12 @@ require_relative "coolhand/net_http_interceptor"
 require_relative "coolhand/api_service"
 require_relative "coolhand/logger_service"
 require_relative "coolhand/feedback_service"
+require_relative "coolhand/template_service"
 require_relative "coolhand/webhook_interceptor"
 
 # The main module for the Coolhand gem.
 # It provides the configuration interface and initializes the patching.
 module Coolhand
-  class Error < StandardError; end
-
   # Class-level instance variables to hold the configuration
   @configuration = Configuration.new
 
@@ -62,12 +62,11 @@ module Coolhand
 
       return yield unless configuration.enabled
 
-      patched = NetHttpInterceptor.patched?
       NetHttpInterceptor.patch!
       begin
         yield
       ensure
-        NetHttpInterceptor.unpatch! unless patched
+        NetHttpInterceptor.unpatch!
       end
     end
 
@@ -104,6 +103,12 @@ module Coolhand
       LoggerService.new
     end
 
+    # Creates a new TemplateService instance, for reading LLM request templates back out of
+    # Coolhand. Needs the private API key - the public key is write-only on this API.
+    def template_service
+      TemplateService.new
+    end
+
     def required_field?(value)
       return false if value.nil?
       return false if value.respond_to?(:empty?) && value.empty?

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: coolhand
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Michael Carroll
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-02 00:00:00.000000000 Z
+date: 2026-09-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -39,6 +39,7 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - ".simplecov"
+- AGENTS.harness.md
 - CHANGELOG.md
 - LICENSE
 - README.md
@@ -49,6 +50,7 @@ files:
 - docs/elevenlabs.md
 - docs/feedback.md
 - docs/openai.md
+- docs/template-search.md
 - docs/vertex.md
 - lib/coolhand.rb
 - lib/coolhand/api_service.rb
@@ -57,11 +59,17 @@ files:
 - lib/coolhand/configuration.rb
 - lib/coolhand/default_exclude_api_patterns.yml
 - lib/coolhand/default_intercept_addresses.yml
+- lib/coolhand/default_intercept_path_patterns.yml
+- lib/coolhand/errors.rb
 - lib/coolhand/feedback_service.rb
 - lib/coolhand/logger_service.rb
 - lib/coolhand/net_http_interceptor.rb
 - lib/coolhand/open_ai/batch_result_processor.rb
+- lib/coolhand/open_ai/webhook_id_store.rb
 - lib/coolhand/open_ai/webhook_validator.rb
+- lib/coolhand/pagination.rb
+- lib/coolhand/read_requests.rb
+- lib/coolhand/template_service.rb
 - lib/coolhand/version.rb
 - lib/coolhand/vertex/batch_result_processor.rb
 - lib/coolhand/webhook_interceptor.rb