x402-rack 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d1c49c723394e852eb4f825b4f849967895cddc8a787dad72a5b6b3959ab618d
-  data.tar.gz: c417200fd8a715c7795d673f8e0f10b6627502aa6ee04e679265d44e3bb66e80
+  metadata.gz: '04961db3ca1280873324aa191fc39d968e52b79ff90819569851811354106398'
+  data.tar.gz: 4a90ebc4e88fc7c55412059687d19751ffb58db90767973a18a666d560a6020d
 SHA512:
-  metadata.gz: 4b2a7277eea92f8f546fd45730ad860d239ec5df6592854942d214cc43415382f5f9adf33185cf871a81f971bd447e1dd804007597c9aa26a978d12cd6503728
-  data.tar.gz: 5143cd4fae5666792ab3338344ff7b28269b5544e353965d7c5e19be3395de2a68cbb07e8d1050840e0a97a58336694c89a6a0fbf6926066ae56b027b06b4f41
+  metadata.gz: 7996d498aa4230ad84a2b02912c05347ac53830dd159ff36666a92268f6eb4dcbcf5e9acacb60c1be8fc8f1b930d6e7a942f852c6e4f87c4908022e314b59130
+  data.tar.gz: a75ee1bd1e2017b53aab6a204164825c6ffc06bd9ee6f312f2b5c7f560178e96afaf220199bf51b6fbc63f1fa7243e3a2360426774b899418ff408e66826c7e8

data/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2026-04-04
+
+### Changed
+
+- **Default `binding_mode` now `:strict`** — OP_RETURN request binding enforced by default. Set `binding_mode: :permissive` to restore previous behaviour.
+
+### Added
+
+- **Txid deduplication store** — `record_if_unseen!` prevents double-processing of the same transaction across settlement and observer paths.
+
+### Fixed
+
+- **Security audit quick wins** — handle numeric JSON amount, non-string derivation components (H-3, M-2, M-4, M-5).
+- **SettlementWorker hardening** — `on_failure` callback, capped queue via Queue with size check (replaces SizedQueue), exponential backoff improvements.
+- **Atomic txid deduplication** — `record_if_unseen!` provides thread-safe check-and-insert in a single call.
+- **Runtime warnings scoped** — warnings emitted only for relevant gateways, check value not just key presence.
+- **Production environment warnings** — warn on ephemeral `challenge_secret` and in-memory `PrefixStore`.
+
 ## [0.4.0] - 2026-04-03
 
 ### Added
@@ -109,6 +127,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Operations docs** — deployment, performance, treasury/nonce lifecycle.
 - **Ecosystem docs** — Coinbase v2, merkleworks, BRC-105 positioning and header namespace reservations.
 
+[0.5.0]: https://github.com/sgbett/x402-rack/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/sgbett/x402-rack/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/sgbett/x402-rack/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/sgbett/x402-rack/compare/v0.1.0...v0.2.0

data/lib/x402/bsv/brc105_gateway.rb

@@ -23,6 +23,7 @@ module X402
       PROOF_HEADER = "x-bsv-payment"
       NETWORK = "bsv:mainnet"
       COMPRESSED_PUBKEY_HEX = /\A0[23][0-9a-fA-F]{64}\z/
+      MAX_DERIVATION_BYTES = 64
 
       # @param key_deriver [BSV::Wallet::KeyDeriver] provides identity key + BRC-42 derivation
       # @param prefix_store [#store!, #valid?, #consume!] replay protection for derivation prefixes
@@ -94,8 +95,16 @@ module X402
       end
 
       def validate_prefix_and_suffix!(prefix, suffix)
-        raise VerificationError.new("missing derivationPrefix", status: 400) if prefix.nil? || prefix.empty?
-        raise VerificationError.new("missing derivationSuffix", status: 400) if suffix.nil? || suffix.empty?
+        validate_derivation_component!("derivationPrefix", prefix)
+        validate_derivation_component!("derivationSuffix", suffix)
+      end
+
+      def validate_derivation_component!(name, value)
+        raise VerificationError.new("missing #{name}", status: 400) if value.nil?
+        unless value.is_a?(String) && !value.empty? &&
+               value.bytesize <= MAX_DERIVATION_BYTES && value.match?(/\A[0-9a-f]+\z/)
+          raise VerificationError.new("invalid #{name} format", status: 400)
+        end
       end
 
       def consume_prefix!(prefix)

data/lib/x402/bsv/pay_gateway.rb

@@ -28,10 +28,12 @@ module X402
       # @param binding_mode [Symbol] :strict or :permissive for OP_RETURN binding
       # @param payee_locking_script_hex [String, nil] payee script (falls back to config)
       # @param settlement_worker [#enqueue, nil] async settlement worker
+      # @param txid_store [#seen?, #record!, nil] optional txid deduplication store.
+      #   When provided, rejects proofs whose txid has already been settled.
       def initialize(arc_client:, arc_wait_for: DEFAULT_ARC_WAIT_FOR,
-                     arc_timeout: DEFAULT_ARC_TIMEOUT, binding_mode: :permissive,
+                     arc_timeout: DEFAULT_ARC_TIMEOUT, binding_mode: :strict,
                      payee_locking_script_hex: nil, wallet: nil, challenge_secret: nil,
-                     settlement_worker: nil)
+                     settlement_worker: nil, txid_store: nil)
         super(payee_locking_script_hex: payee_locking_script_hex, wallet: wallet,
               challenge_secret: challenge_secret)
         @arc_client = arc_client
@@ -39,6 +41,7 @@ module X402
         @arc_timeout = arc_timeout
         @binding_mode = binding_mode
         @settlement_worker = settlement_worker
+        @txid_store = txid_store
       end
 
       def challenge_headers(rack_request, route)
@@ -58,6 +61,7 @@ module X402
         pay_to_sig = payload.dig("accepted", "extra", "payToSig")
         verify_pay_to_signature!(accepted_payee, pay_to_sig)
         transaction = decode_transaction(payload)
+        check_txid_unique!(transaction)
         verify_payment_output!(transaction, required_sats, accepted_payee)
         verify_binding!(transaction, rack_request)
         settle_transaction!(transaction, route)
@@ -113,10 +117,13 @@ module X402
           raise VerificationError.new("network mismatch: expected #{NETWORK}", status: 400)
         end
 
-        amount = accepted["amount"].to_i
+        raw_amount = accepted["amount"]
+        amount = raw_amount.is_a?(Integer) ? raw_amount : Integer(raw_amount, 10)
         return unless amount < required_sats
 
         raise VerificationError.new("insufficient amount: #{amount} < #{required_sats}", status: 402)
+      rescue ArgumentError, TypeError
+        raise VerificationError.new("invalid amount field", status: 400)
       end
 
       def decode_transaction(payload)
@@ -141,6 +148,13 @@ module X402
         raise VerificationError.new("no output pays >= #{required_sats} sats to payee", status: 402)
       end
 
+      def check_txid_unique!(transaction)
+        return unless @txid_store
+        return if @txid_store.record_if_unseen!(transaction.txid_hex)
+
+        raise VerificationError.new("transaction already settled", status: 400)
+      end
+
       def verify_binding!(transaction, rack_request)
         expected_hex = "006a047834303220#{request_binding_hash(rack_request).unpack1("H*")}"
         found = transaction.outputs.any? do |output|

data/lib/x402/bsv/txid_store.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module X402
+  module BSV
+    # Pluggable txid deduplication store for PayGateway settlement.
+    #
+    # Prevents the same transaction from being accepted twice.
+    # Duck-type contract — any backend must implement:
+    #   record_if_unseen!(txid) — atomically records the txid and returns true
+    #     if it was not already seen. Returns false if already recorded.
+    module TxidStore
+      # In-memory backend suitable for development and single-process deployments.
+      # Thread-safe via Monitor. Entries expire after +ttl+ seconds.
+      #
+      # NOTE: This store provides no deduplication across OS processes.
+      # Production multi-process deployments should use a shared backend.
+      class Memory
+        DEFAULT_TTL = 600
+        DEFAULT_MAX_SIZE = 10_000
+
+        # @param ttl [Integer] seconds before a seen txid expires (default 600)
+        # @param max_size [Integer] cap on stored txids (default 10_000)
+        def initialize(ttl: DEFAULT_TTL, max_size: DEFAULT_MAX_SIZE)
+          @entries = {}
+          @monitor = Monitor.new
+          @ttl = ttl
+          @max_size = max_size
+        end
+
+        # Atomically checks and records a txid.
+        # Returns true if the txid was new (now recorded).
+        # Returns false if already seen (duplicate).
+        def record_if_unseen!(txid)
+          @monitor.synchronize do
+            purge_expired!
+
+            entry = @entries[txid]
+            return false if entry && !expired?(entry)
+
+            @entries[txid] = monotonic_now
+            evict_oldest! if @entries.size > @max_size
+            true
+          end
+        end
+
+        private
+
+        def purge_expired!
+          @entries.delete_if { |_, recorded_at| (monotonic_now - recorded_at) > @ttl }
+        end
+
+        def evict_oldest!
+          oldest_key = @entries.min_by { |_, recorded_at| recorded_at }&.first
+          @entries.delete(oldest_key) if oldest_key
+        end
+
+        def expired?(recorded_at)
+          (monotonic_now - recorded_at) > @ttl
+        end
+
+        def monotonic_now
+          Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        end
+      end
+    end
+  end
+end

data/lib/x402/bsv.rb

@@ -5,3 +5,4 @@ require_relative "bsv/pay_gateway"
 require_relative "bsv/proof_gateway"
 require_relative "bsv/brc105_gateway"
 require_relative "bsv/prefix_store"
+require_relative "bsv/txid_store"

data/lib/x402/configuration.rb

@@ -17,7 +17,7 @@ module X402
 
     PAY_GATEWAY_KNOWN_OPTS = %i[
       arc_client payee_locking_script_hex arc_wait_for arc_timeout
-      binding_mode wallet challenge_secret settlement_worker
+      binding_mode wallet challenge_secret settlement_worker txid_store
     ].freeze
 
     PROOF_GATEWAY_KNOWN_OPTS = %i[
@@ -120,11 +120,42 @@ module X402
       validate_payee_source!
       build_gateways_from_specs! if gateways.empty? && !gateway_specs.empty?
       validate_gateways!
+      warn_operational_concerns!
       raise ConfigurationError, "at least one route must be protected" if routes.empty?
     end
 
     private
 
+    def warn_operational_concerns!
+      return if gateway_specs.empty? # gateways= was used directly — specs not relevant
+
+      warn_ephemeral_challenge_secret!
+      warn_in_memory_prefix_store!
+    end
+
+    def warn_ephemeral_challenge_secret!
+      secret_gateways = %w[X402::BSV::PayGateway X402::BSV::ProofGateway]
+      needs_warning = gateway_specs.any? do |class_name, options|
+        secret_gateways.include?(class_name) && !options[:challenge_secret]
+      end
+      return unless needs_warning
+
+      warn "[x402] challenge_secret is auto-generated. " \
+           "In-flight challenges will fail after process restart. " \
+           "Set challenge_secret: explicitly for production."
+    end
+
+    def warn_in_memory_prefix_store!
+      needs_warning = gateway_specs.any? do |class_name, options|
+        class_name == "X402::BSV::BRC105Gateway" && !options[:prefix_store]
+      end
+      return unless needs_warning
+
+      warn "[x402] BRC105Gateway using in-memory PrefixStore. " \
+           "No replay protection across processes. " \
+           "Use a shared backend (Redis) for multi-process deployments."
+    end
+
     def validate_gateways!
       raise ConfigurationError, "at least one gateway is required" if gateways.nil? || gateways.empty?
 
@@ -211,7 +242,7 @@ module X402
       opts = { arc_client: options[:arc_client] || shared_arc_client }
       opts[:payee_locking_script_hex] = options[:payee_locking_script_hex] || payee_locking_script_hex
       opts[:wallet] = wallet if wallet
-      %i[arc_wait_for arc_timeout binding_mode challenge_secret settlement_worker].each do |key|
+      %i[arc_wait_for arc_timeout binding_mode challenge_secret settlement_worker txid_store].each do |key|
         opts[key] = options[key] if options.key?(key)
       end
       klass.new(**opts)

data/lib/x402/protocol/challenge.rb

@@ -9,14 +9,21 @@ module X402
     SUPPORTED_SCHEMES = ["bsv-tx-v1"].freeze
     DEFAULT_TTL = 300 # 5 minutes
 
-    attr_reader :version, :scheme, :domain, :method, :path, :query,
-                :req_headers_sha256, :req_body_sha256,
-                :amount_sats, :payee_locking_script_hex,
-                :nonce_txid, :nonce_vout, :nonce_satoshis, :nonce_locking_script_hex,
-                :expires_at, :partial_tx_b64, :payee_sig
+    KNOWN_ATTRS = %i[
+      version scheme domain method path query
+      req_headers_sha256 req_body_sha256
+      amount_sats payee_locking_script_hex
+      nonce_txid nonce_vout nonce_satoshis nonce_locking_script_hex
+      expires_at partial_tx_b64 payee_sig
+    ].freeze
+
+    attr_reader(*KNOWN_ATTRS)
 
     def initialize(attrs = {})
-      attrs.each { |k, v| instance_variable_set(:"@#{k}", v) }
+      attrs.each do |k, v|
+        key = k.to_sym
+        instance_variable_set(:"@#{key}", v) if KNOWN_ATTRS.include?(key)
+      end
     end
 
     def to_h

data/lib/x402/settlement_worker.rb

@@ -6,20 +6,41 @@ module X402
   #
   # Any object responding to +#enqueue(tx_binary)+ satisfies the pluggable
   # worker interface expected by PayGateway's async settlement path.
+  #
+  # @example With failure callback
+  #   worker = X402::SettlementWorker.new(
+  #     arc_client: arc,
+  #     on_failure: ->(tx_binary, error) { logger.error("Settlement failed: #{error}") }
+  #   )
   class SettlementWorker
     ACCEPTABLE_STATUSES = %w[SEEN_ON_NETWORK ANNOUNCED_TO_NETWORK MINED].freeze
+    DEFAULT_MAX_QUEUE = 1000
 
-    attr_reader :max_retries
+    attr_reader :max_retries, :max_queue
 
-    def initialize(arc_client:, max_retries: 5)
+    # @param arc_client [#broadcast] ARC client for broadcasting
+    # @param max_retries [Integer] retry attempts before giving up (default 5)
+    # @param max_queue [Integer] maximum queued transactions (default 1000).
+    #   Raises +X402::VerificationError+ (503) when full.
+    # @param on_failure [#call, nil] callback invoked with +(tx_binary, error)+
+    #   when all retries are exhausted. Default nil (silent drop).
+    def initialize(arc_client:, max_retries: 5, max_queue: DEFAULT_MAX_QUEUE, on_failure: nil)
       @arc_client = arc_client
       @max_retries = max_retries
+      @max_queue = max_queue
+      @on_failure = on_failure
       @queue = Queue.new
       @thread = nil
       @mutex = Mutex.new
     end
 
+    # Enqueue a transaction for background broadcast.
+    #
+    # @param tx_binary [String] raw transaction bytes
+    # @raise [X402::VerificationError] with status 503 when queue is full
     def enqueue(tx_binary)
+      raise VerificationError.new("settlement queue full — try again later", status: 503) if @queue.size >= @max_queue
+
       ensure_thread_running
       @queue.push(tx_binary)
     end
@@ -57,15 +78,28 @@ module X402
     def broadcast_with_retry(tx_binary, attempt = 0)
       result = @arc_client.broadcast(tx_binary, wait_for: "SEEN_ON_NETWORK")
       return if ACCEPTABLE_STATUSES.include?(result.tx_status)
-      return if attempt >= @max_retries
+
+      if attempt >= @max_retries
+        notify_failure(tx_binary, "status #{result.tx_status} after #{attempt + 1} attempts")
+        return
+      end
 
       sleep(2**attempt)
       broadcast_with_retry(tx_binary, attempt + 1)
-    rescue StandardError
-      return if attempt >= @max_retries
+    rescue StandardError => e
+      if attempt >= @max_retries
+        notify_failure(tx_binary, e)
+        return
+      end
 
       sleep(2**attempt)
       broadcast_with_retry(tx_binary, attempt + 1)
     end
+
+    def notify_failure(tx_binary, error)
+      @on_failure&.call(tx_binary, error)
+    rescue StandardError
+      # Never let callback failures crash the worker thread
+    end
   end
 end

data/lib/x402/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module X402
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: x402-rack
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Simon Bettison
 bindir: exe
 cert_chain: []
-date: 2026-04-02 00:00:00.000000000 Z
+date: 2026-04-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -117,6 +117,7 @@ files:
 - lib/x402/bsv/pay_gateway.rb
 - lib/x402/bsv/prefix_store.rb
 - lib/x402/bsv/proof_gateway.rb
+- lib/x402/bsv/txid_store.rb
 - lib/x402/configuration.rb
 - lib/x402/errors.rb
 - lib/x402/middleware.rb