bsv-sdk 0.11.1 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dcf5a5168875f0ff711c5bd328a513689dca51ec26e7d2c1ccf48a0ba54389d9
-  data.tar.gz: 378499b7a78c41aa0b10026cf40a3dcf80b07e66a0df2c9c364336d9180a0051
+  metadata.gz: 7b562fa9e3a12641ddf7e24ca393560c70df5a92e75af2c8ed68c7cc1ff0bda0
+  data.tar.gz: 912f02ff095cdb88af595e9f97d340a80492cd1b72abd696b90e0bb7a64aa8b5
 SHA512:
-  metadata.gz: fb7ad05f65c746db6ad60cd7d85ff90067df2f70d11f88ae65beed84521479fa9c898261d56ca18a220c774f98532d8cc367ac1f85a22b6fd287e283eb0285d5
-  data.tar.gz: ae3baed0d279ffb883267656a0a3734a3192f9f84d9bdd8f6f67d4e50adbf01bbdcea3e1ab9f079572afb5f4a86c537b39eaca34821e8ed5d2c02b192a6d0ab9
+  metadata.gz: 44ab1a69fc9e2a9e7eb4fbcdfa09b7d6870bbba81f1f8d1e8f0265f89e450c38488fefb23729bc9b545aa4b9baacaa49621faa484468d121753950a207108b45
+  data.tar.gz: bf945875e3253d82376b27c23f9bb359a45fc426b99447f98a54b1b30335876708dc50e98d848b1a9f7546028ede523e7edd3790d3d33e01e3a47eb16dd151d7

data/CHANGELOG.md

@@ -5,6 +5,43 @@ All notable changes to the `bsv-sdk` gem are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 and this gem adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.12.0 — 2026-04-15
+
+### Added
+- Certificate infrastructure: `BSV::Auth::Certificate` base class with field map,
+  serialisation, and signature verification (#420)
+- `BSV::Auth::MasterCertificate` for certificate issuance with identity key
+  binding (#421)
+- `BSV::Auth::VerifiableCertificate` for selective field revelation with
+  proof-of-field-revelation (#422)
+- Certificate utilities: `validate_certificates` and `get_verifiable_certificates`
+  helpers (#427, #428)
+- Peer protocol: `certificateRequest`/`certificateResponse` message handling,
+  callback registration, and `last_interacted_peer` (#430, #431)
+- High-level peer session API: `Peer#to_peer` and `Peer#get_authenticated_session`
+  for reusable authenticated sessions (#433)
+- BRC-104 HTTP auth transport: `AuthFetch` client, `SimplifiedFetchTransport`,
+  `AuthMiddleware` (Rack), and `AuthHeaders`/`AuthPayload` serialiser (#437–#441)
+- `AuthFetch` 402 payment handling for paid API endpoints (#441)
+- `BSV::WireFormat` module for camelCase/snake_case conversion at JSON
+  boundaries (#447)
+- Cross-SDK conformance and integration specs for certificates (#423)
+- Peer protocol integration tests (#434)
+- BRC-104 integration tests (#442)
+
+### Fixed
+- Auth handshake now uses shallow key conversion to avoid corrupting nested
+  message payloads
+- Certificate classes hardened against edge cases from code review
+- Certifier allowlist enforced in `process_certificate_response`
+- Flaky `validate_certificates_spec` fixed (missing `require 'base64'`)
+
+### Changed
+- `GetVerifiableCertificates` bug warning note removed (underlying bug now
+  fixed in bsv-wallet)
+- Peer protocol internals refactored: `PairedTransport` helper, deduplicated
+  high-level API, hardened message processing
+
 ## 0.11.1 — 2026-04-13
 
 ### Fixed

data/lib/bsv/auth/auth_fetch.rb

@@ -0,0 +1,387 @@
+# frozen_string_literal: true
+
+require 'uri'
+require 'json'
+require 'base64'
+require 'securerandom'
+require 'timeout'
+
+module BSV
+  module Auth
+    # BRC-104 high-level client for authenticated HTTP requests.
+    #
+    # Manages a pool of {Peer} instances (one per base URL) and serialises
+    # HTTP requests as BRC-104 binary payloads. The handshake is initiated
+    # automatically on the first request to each base URL.
+    #
+    # When the server responds with HTTP 402 Payment Required, AuthFetch
+    # automatically constructs a BSV payment transaction via the wallet and
+    # retries the original request with an +x-bsv-payment+ header attached.
+    #
+    # Thread safety: the +@peers+ hash is protected by a mutex. Each in-flight
+    # request uses its own +Queue+ to receive exactly the matching response.
+    #
+    # @example
+    #   client = BSV::Auth::AuthFetch.new(wallet: my_wallet)
+    #   response = client.fetch('https://api.example.com/resource')
+    #   puts response.status   # => 200
+    #   puts response.body     # => "..."
+    class AuthFetch
+      DEFAULT_TIMEOUT         = 30
+      DEFAULT_PAYMENT_RETRIES = 3
+      PAYMENT_RETRY_DELAY_MS  = 250
+      PAYMENT_PROTOCOL_ID     = [2, '3241645161d8'].freeze
+      SUPPORTED_PAYMENT_VERSION = '1.0'
+
+      # @param wallet [BSV::Wallet::Interface] wallet for crypto operations
+      # @param requested_certificates [Hash, nil] certificate set to request from peers
+      # @param session_manager [SessionManager, nil] optional shared session store
+      # @param payment_max_retries [Integer] maximum number of payment retry attempts (default 3)
+      def initialize(wallet:, requested_certificates: nil, session_manager: nil, payment_max_retries: DEFAULT_PAYMENT_RETRIES)
+        @wallet                 = wallet
+        @requested_certificates = requested_certificates
+        @session_manager        = session_manager
+        @payment_max_retries    = payment_max_retries
+        @peers                  = {}
+        @peers_mutex            = Mutex.new
+      end
+
+      # Sends an authenticated HTTP request to +url+.
+      #
+      # The first request to a new base URL performs a BRC-103 mutual-auth
+      # handshake automatically. Subsequent requests reuse the cached peer.
+      #
+      # If the server responds with 402, a BSV payment is created and the
+      # request is retried with an +x-bsv-payment+ header (up to
+      # +payment_max_retries+ times).
+      #
+      # @param url [String] full URL including scheme, host, optional port, path, and query
+      # @param method [String] HTTP method (default 'GET')
+      # @param headers [Hash] request headers; only +content-type+, +authorization+,
+      #   and +x-bsv-*+ (excluding +x-bsv-auth-*+) are allowed
+      # @param body [String, Hash, nil] request body
+      # @param timeout [Integer] seconds to wait for the authenticated response (default 30)
+      # @return [AuthResponse]
+      # @raise [ArgumentError] if disallowed headers are provided
+      # @raise [Timeout::Error] if no response arrives within +timeout+ seconds
+      # @raise [AuthError] if 402 payment handling fails or max retries are exceeded
+      def fetch(url, method: 'GET', headers: {}, body: nil, timeout: DEFAULT_TIMEOUT)
+        do_fetch(url, method: method, headers: headers, body: body, timeout: timeout,
+                      retry_count: 0, payment_context: nil)
+      end
+
+      private
+
+      def do_fetch(url, method:, headers:, body:, timeout:, retry_count:, payment_context:)
+        uri      = URI.parse(url)
+        base_url = extract_base_url(uri)
+        path     = uri.path.empty? ? '/' : uri.path
+        query    = uri.query ? "?#{uri.query}" : nil
+
+        peer = get_or_create_peer(base_url)
+
+        # Validate and filter headers (raises ArgumentError for unsupported headers)
+        filtered_headers = AuthHeaders.filter_request_headers(headers)
+
+        # Normalise body: Hash → JSON string, set content-type if not already set
+        effective_body, filtered_headers = normalise_body(body, filtered_headers)
+
+        # Generate 32-byte request nonce
+        request_nonce = SecureRandom.random_bytes(32)
+
+        # Serialise request to binary payload
+        payload_bytes = AuthPayload.serialize_request(
+          request_nonce: request_nonce,
+          method: method,
+          path: path,
+          query: query,
+          headers: filtered_headers,
+          body: effective_body
+        )
+
+        # Queue to block until the matching response arrives
+        response_queue = Queue.new
+
+        # Register a one-shot callback on the peer
+        callback_id = peer.on_general_message do |sender_key, raw_payload|
+          binary = array_to_binary(raw_payload)
+          # Match by first 32 bytes of payload
+          next unless binary.bytesize >= 32 && binary.byteslice(0, 32) == request_nonce
+
+          begin
+            deserialized = AuthPayload.deserialize_response(binary)
+            response_queue.push({ ok: true, data: deserialized, identity_key: sender_key })
+          rescue StandardError => e
+            response_queue.push({ ok: false, error: e })
+          end
+        end
+
+        begin
+          peer.to_peer(payload_bytes.bytes)
+        rescue AuthError => e
+          peer.off_general_message(callback_id)
+          if e.message.include?('Session not found') && retry_count < 3
+            # Stale session — clear the cached peer and retry with a fresh one
+            @peers_mutex.synchronize { @peers.delete(base_url) }
+            return do_fetch(url, method: method, headers: headers, body: body,
+                                 timeout: timeout, retry_count: retry_count + 1,
+                                 payment_context: payment_context)
+          end
+          raise
+        end
+
+        begin
+          result = Timeout.timeout(timeout) { response_queue.pop }
+        rescue Timeout::Error
+          peer.off_general_message(callback_id)
+          raise Timeout::Error, "AuthFetch timed out waiting for response from #{base_url}"
+        end
+
+        peer.off_general_message(callback_id)
+
+        raise result[:error] unless result[:ok]
+
+        data = result[:data]
+        response = AuthResponse.new(
+          status: data[:status],
+          headers: pairs_to_hash(data[:headers]),
+          body: data[:body] || '',
+          identity_key: result[:identity_key]
+        )
+
+        return response unless response.status == 402
+
+        handle_payment_required(url, method, headers, body, timeout, response, payment_context)
+      end
+
+      # Handles a 402 Payment Required response by creating a BSV payment
+      # transaction and retrying the original request.
+      #
+      # @param url [String] the original request URL
+      # @param method [String] HTTP method
+      # @param headers [Hash] original request headers
+      # @param body original request body
+      # @param timeout [Integer] request timeout in seconds
+      # @param response [AuthResponse] the 402 response
+      # @param payment_context [Hash, nil] existing payment context (for retries)
+      # @return [AuthResponse] the response after payment
+      # @raise [AuthError] if payment headers are invalid, wallet lacks capability,
+      #   or maximum retries are exhausted
+      def handle_payment_required(url, method, headers, body, timeout, response, payment_context)
+        validated = validate_payment_headers(response.headers)
+
+        satoshis_required    = validated[:satoshis_required]
+        server_identity_key  = validated[:server_identity_key]
+        derivation_prefix    = validated[:derivation_prefix]
+
+        # Determine whether we can reuse an existing payment context or must create a new one
+        new_context = if payment_context && compatible_payment_context?(payment_context, satoshis_required, server_identity_key, derivation_prefix)
+                        payment_context
+                      else
+                        create_payment_context(url, satoshis_required, server_identity_key, derivation_prefix)
+                      end
+
+        attempt = new_context[:attempts] + 1
+
+        if attempt > @payment_max_retries
+          raise AuthError, "Payment for #{url} failed after #{@payment_max_retries} attempt(s): " \
+                           "#{satoshis_required} satoshis required"
+        end
+
+        new_context[:attempts] = attempt
+
+        payment_header_value = JSON.generate(
+          'derivationPrefix' => new_context[:derivation_prefix],
+          'derivationSuffix' => new_context[:derivation_suffix],
+          'transaction' => new_context[:transaction_base64]
+        )
+
+        # Apply linear backoff for retries after the first attempt
+        sleep(PAYMENT_RETRY_DELAY_MS * attempt / 1000.0) if attempt > 1
+
+        retry_headers = headers.merge(AuthHeaders::PAYMENT => payment_header_value)
+
+        do_fetch(url, method: method, headers: retry_headers, body: body, timeout: timeout,
+                      retry_count: 0, payment_context: new_context)
+      end
+
+      # Validates the payment-related headers from a 402 response.
+      #
+      # @param response_headers [Hash] response headers (string keys)
+      # @return [Hash] validated values: :satoshis_required, :server_identity_key, :derivation_prefix
+      # @raise [AuthError] if any required header is missing or invalid
+      def validate_payment_headers(response_headers)
+        version = response_headers[AuthHeaders::PAYMENT_VERSION]
+        unless version == SUPPORTED_PAYMENT_VERSION
+          raise AuthError,
+                "Unsupported #{AuthHeaders::PAYMENT_VERSION} response header. " \
+                "Client version: #{SUPPORTED_PAYMENT_VERSION}, server version: #{version.inspect}"
+        end
+
+        satoshis_str = response_headers[AuthHeaders::PAYMENT_SATOSHIS_REQUIRED]
+        raise AuthError, "Missing #{AuthHeaders::PAYMENT_SATOSHIS_REQUIRED} response header." unless satoshis_str
+
+        satoshis = Integer(satoshis_str, 10)
+        raise AuthError, "Invalid #{AuthHeaders::PAYMENT_SATOSHIS_REQUIRED} value: must be a positive integer." unless satoshis.positive?
+
+        server_identity_key = response_headers[AuthHeaders::IDENTITY_KEY]
+        unless server_identity_key.is_a?(String) && !server_identity_key.empty?
+          raise AuthError,
+                "Missing #{AuthHeaders::IDENTITY_KEY} response header."
+        end
+
+        derivation_prefix = response_headers[AuthHeaders::PAYMENT_DERIVATION_PREFIX]
+        unless derivation_prefix.is_a?(String) && !derivation_prefix.empty?
+          raise AuthError,
+                "Missing #{AuthHeaders::PAYMENT_DERIVATION_PREFIX} response header."
+        end
+
+        {
+          satoshis_required: satoshis,
+          server_identity_key: server_identity_key,
+          derivation_prefix: derivation_prefix
+        }
+      rescue ArgumentError
+        raise AuthError, "Invalid #{AuthHeaders::PAYMENT_SATOSHIS_REQUIRED} value: must be a positive integer."
+      end
+
+      # Creates a new payment context by deriving a payment key and building a transaction.
+      #
+      # @param url [String] request URL (used in the transaction description)
+      # @param satoshis_required [Integer] payment amount
+      # @param server_identity_key [String] server's compressed public key hex
+      # @param derivation_prefix [String] BIP-32 derivation prefix from the server
+      # @return [Hash] payment context with keys :satoshis_required, :server_identity_key,
+      #   :derivation_prefix, :derivation_suffix, :transaction_base64, :attempts
+      # @raise [AuthError] if the wallet does not support payment methods
+      def create_payment_context(url, satoshis_required, server_identity_key, derivation_prefix)
+        unless @wallet.respond_to?(:get_public_key) && @wallet.respond_to?(:create_action)
+          raise AuthError, '402 payment handling requires a wallet that supports create_action and get_public_key'
+        end
+
+        base_url = extract_base_url(URI.parse(url))
+
+        derivation_suffix = Nonce.create(@wallet)
+
+        key_result = @wallet.get_public_key(
+          protocol_id: PAYMENT_PROTOCOL_ID,
+          key_id: "#{derivation_prefix} #{derivation_suffix}",
+          counterparty: server_identity_key
+        )
+        public_key_hex = key_result[:public_key]
+
+        address = BSV::Primitives::PublicKey.from_hex(public_key_hex).address
+        lock_script = BSV::Script::Script.p2pkh_lock(address)
+
+        action_result = @wallet.create_action(
+          description: "Payment for request to #{base_url}",
+          outputs: [{
+            satoshis: satoshis_required,
+            locking_script: lock_script.to_hex,
+            output_description: 'HTTP request payment'
+          }]
+        )
+
+        tx_bytes = action_result[:tx] || action_result['tx']
+        raise AuthError, 'wallet.create_action did not return a :tx byte array' unless tx_bytes.is_a?(Array)
+
+        transaction_base64 = Base64.strict_encode64(tx_bytes.pack('C*'))
+
+        {
+          satoshis_required: satoshis_required,
+          server_identity_key: server_identity_key,
+          derivation_prefix: derivation_prefix,
+          derivation_suffix: derivation_suffix,
+          transaction_base64: transaction_base64,
+          attempts: 0
+        }
+      end
+
+      # Returns true if the existing payment context is compatible with the
+      # current 402 response requirements (same satoshis, identity key, and prefix).
+      def compatible_payment_context?(context, satoshis_required, server_identity_key, derivation_prefix)
+        context[:satoshis_required] == satoshis_required &&
+          context[:server_identity_key] == server_identity_key &&
+          context[:derivation_prefix]   == derivation_prefix
+      end
+
+      # Returns an existing peer for +base_url+ or creates a new one.
+      def get_or_create_peer(base_url)
+        @peers_mutex.synchronize do
+          @peers[base_url] ||= build_peer(base_url)
+        end
+      end
+
+      def build_peer(base_url)
+        transport = SimplifiedFetchTransport.new(base_url)
+        Peer.new(
+          wallet: @wallet,
+          transport: transport,
+          session_manager: @session_manager,
+          certificates_to_request: @requested_certificates
+        )
+      end
+
+      # Extracts scheme + host + port from a URI.
+      #
+      # For standard ports (80 for http, 443 for https), the port is omitted
+      # to match browser +URL#origin+ behaviour used in the TS SDK.
+      def extract_base_url(uri)
+        default_port = uri.scheme == 'https' ? 443 : 80
+        if uri.port == default_port
+          "#{uri.scheme}://#{uri.host}"
+        else
+          "#{uri.scheme}://#{uri.host}:#{uri.port}"
+        end
+      end
+
+      # Normalises the request body and updates headers accordingly.
+      #
+      # - Hash body → JSON.generate, sets content-type to application/json if absent
+      # - String/nil body → used as-is (nil body defaults handled by AuthPayload)
+      #
+      # Returns [normalised_body, updated_filtered_headers].
+      def normalise_body(body, filtered_headers)
+        if body.is_a?(Hash)
+          json_body = JSON.generate(body)
+          # Add content-type: application/json if not already present
+          has_ct = filtered_headers.any? { |k, _| k == 'content-type' }
+          filtered_headers = (filtered_headers + [['content-type', 'application/json']]).sort_by { |k, _| k } unless has_ct
+          [json_body, filtered_headers]
+        else
+          [body, filtered_headers]
+        end
+      end
+
+      # Converts an Array<[key, value]> to a Hash with string keys.
+      def pairs_to_hash(pairs)
+        return {} unless pairs.is_a?(Array)
+
+        pairs.each_with_object({}) { |(k, v), h| h[k.to_s] = v.to_s }
+      end
+
+      # Converts Array<Integer> or binary String to a binary String.
+      def array_to_binary(payload)
+        return payload if payload.is_a?(String)
+
+        payload.map(&:chr).join.force_encoding('BINARY')
+      end
+    end
+
+    # Immutable value object representing an authenticated HTTP response.
+    class AuthResponse
+      attr_reader :status, :headers, :body, :identity_key
+
+      # @param status [Integer] HTTP status code
+      # @param headers [Hash] response headers
+      # @param body [String] response body
+      # @param identity_key [String] server's compressed public key hex
+      def initialize(status:, headers:, body:, identity_key:)
+        @status       = status
+        @headers      = headers
+        @body         = body
+        @identity_key = identity_key
+      end
+    end
+  end
+end

data/lib/bsv/auth/auth_headers.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module BSV
+  module Auth
+    # BRC-104 HTTP header name constants and filtering helpers.
+    #
+    # Provides the canonical header names used in BSV auth HTTP transport,
+    # matching the Go SDK's brc104/auth_http_headers.go exactly.
+    #
+    # Header filtering:
+    # - Requests: content-type (normalised), authorization, x-bsv-* (excl. x-bsv-auth-*)
+    # - Responses: authorization, x-bsv-* (excl. x-bsv-auth-*) — content-type is NOT signed
+    #
+    # Both {.filter_request_headers} and {.filter_response_headers} return sorted
+    # [key, value] pairs ready for payload serialisation.
+    module AuthHeaders
+      module_function
+
+      # Common prefix for all BSV auth headers.
+      AUTH_PREFIX = 'x-bsv-auth'
+
+      # Prefix for BSV payment headers (excluded from signed payload).
+      PAYMENT_PREFIX = 'x-bsv-payment'
+
+      # Prefix for all BSV custom headers (non-auth).
+      BSV_PREFIX = 'x-bsv-'
+
+      # Protocol version header.
+      VERSION = 'x-bsv-auth-version'
+
+      # Sender's identity public key (compressed hex).
+      IDENTITY_KEY = 'x-bsv-auth-identity-key'
+
+      # Sender's nonce.
+      NONCE = 'x-bsv-auth-nonce'
+
+      # Recipient's nonce (echoed back for mutual verification).
+      YOUR_NONCE = 'x-bsv-auth-your-nonce'
+
+      # Request ID for correlation (base64-encoded 32 bytes).
+      REQUEST_ID = 'x-bsv-auth-request-id'
+
+      # Message type string (e.g. 'general', 'initialRequest').
+      MESSAGE_TYPE = 'x-bsv-auth-message-type'
+
+      # ECDSA/Schnorr signature (hex-encoded).
+      SIGNATURE = 'x-bsv-auth-signature'
+
+      # Requested certificate set (JSON-encoded).
+      REQUESTED_CERTIFICATES = 'x-bsv-auth-requested-certificates'
+
+      # Payment protocol version.
+      PAYMENT_VERSION = 'x-bsv-payment-version'
+
+      # Number of satoshis required for payment.
+      PAYMENT_SATOSHIS_REQUIRED = 'x-bsv-payment-satoshis-required'
+
+      # BIP-32 derivation prefix for payment key.
+      PAYMENT_DERIVATION_PREFIX = 'x-bsv-payment-derivation-prefix'
+
+      # Raw payment transaction (hex or base64).
+      PAYMENT = 'x-bsv-payment'
+
+      # Filters request headers to the set that is signed in the payload.
+      #
+      # Includes (matching TS/Go SDK behaviour):
+      # - +content-type+ — normalised by stripping "; charset=..." params
+      # - +authorization+
+      # - +x-bsv-*+ headers, excluding any that start with +x-bsv-auth+
+      #
+      # Raises +ArgumentError+ if any header does not fall into the above
+      # categories (matching TS SDK strictness — an unsupported header that
+      # the caller expects to be signed is a security concern).
+      #
+      # @param headers [Hash] header key/value pairs (keys need not be lowercased)
+      # @return [Array<Array(String, String)>] sorted [key, value] pairs, keys lowercased
+      # @raise [ArgumentError] if an unsupported header is present
+      def filter_request_headers(headers)
+        result = []
+        headers.each do |k, v|
+          key = k.to_s.downcase
+          if key.start_with?(BSV_PREFIX)
+            raise ArgumentError, "BSV auth headers are not allowed in the request payload: #{key}" if key.start_with?(AUTH_PREFIX)
+            next if key.start_with?(PAYMENT_PREFIX) # payment headers are transport-level, not signed
+
+            result << [key, v.to_s]
+          elsif key == 'authorization'
+            result << [key, v.to_s]
+          elsif key == 'content-type'
+            # Normalise: strip parameters like "; charset=utf-8"
+            normalised = v.to_s.split(';').first.to_s.strip
+            result << [key, normalised]
+          else
+            raise ArgumentError,
+                  'Unsupported header in the simplified fetch implementation. ' \
+                  "Only content-type, authorization, and x-bsv-* headers are supported. Got: #{key}"
+          end
+        end
+        result.sort_by { |key, _| key }
+      end
+
+      # Filters response headers to the set that is signed in the payload.
+      #
+      # Includes (matching TS/Go SDK behaviour):
+      # - +authorization+
+      # - +x-bsv-*+ headers, excluding any that start with +x-bsv-auth+
+      #
+      # Note: +content-type+ is intentionally excluded from response signing
+      # (matches both Go and TS SDK behaviour).
+      #
+      # @param headers [Hash] header key/value pairs
+      # @return [Array<Array(String, String)>] sorted [key, value] pairs, keys lowercased
+      def filter_response_headers(headers)
+        result = []
+        headers.each do |k, v|
+          key = k.to_s.downcase
+          if key.start_with?(BSV_PREFIX)
+            next if key.start_with?(AUTH_PREFIX)
+
+            result << [key, v.to_s]
+          elsif key == 'authorization'
+            result << [key, v.to_s]
+          end
+        end
+        result.sort_by { |key, _| key }
+      end
+
+      # Extracts +x-bsv-auth-*+ headers from a hash and returns a structured hash
+      # with symbolised keys derived from the header name suffix.
+      #
+      # For example, +x-bsv-auth-identity-key+ becomes +:identity_key+.
+      #
+      # @param headers [Hash] incoming headers hash (keys may be mixed case)
+      # @return [Hash] symbolised auth header values; only present keys are included
+      def extract_auth_headers(headers)
+        prefix = "#{AUTH_PREFIX}-"
+        result = {}
+        headers.each do |k, v|
+          key = k.to_s.downcase
+          next unless key.start_with?(prefix)
+
+          suffix = key[prefix.length..]
+          symbol_key = suffix.tr('-', '_').to_sym
+          result[symbol_key] = v
+        end
+        result
+      end
+    end
+  end
+end