x402-rack 0.1.0

data/lib/x402/configuration.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module X402
+  class Configuration
+    Route = Struct.new(:http_method, :path, :amount_sats, keyword_init: true)
+
+    GATEWAY_METHODS = %i[challenge_headers proof_header_names settle!].freeze
+
+    attr_accessor :domain, :payee_locking_script_hex, :gateways
+    attr_reader :routes
+
+    def initialize
+      @routes = []
+      @gateways = []
+    end
+
+    # Register a protected route.
+    #
+    # @param method [String] HTTP method or "*" for any
+    # @param path [String, Regexp] exact path or pattern
+    # @param amount_sats [Integer] required payment in satoshis
+    def protect(method:, path:, amount_sats:)
+      @routes << Route.new(http_method: method.upcase, path: path, amount_sats: amount_sats)
+    end
+
+    # Find the matching route for a request method and path.
+    #
+    # @return [Route, nil]
+    def find_route(request_method, request_path)
+      @routes.find do |route|
+        method_matches?(route.http_method, request_method) &&
+          path_matches?(route.path, request_path)
+      end
+    end
+
+    def validate!
+      raise ConfigurationError, "domain is required" if domain.nil? || domain.empty?
+
+      if payee_locking_script_hex.nil? || payee_locking_script_hex.empty?
+        raise ConfigurationError,
+              "payee_locking_script_hex is required"
+      end
+      validate_gateways!
+      raise ConfigurationError, "at least one route must be protected" if routes.empty?
+    end
+
+    private
+
+    def validate_gateways!
+      raise ConfigurationError, "at least one gateway is required" if gateways.nil? || gateways.empty?
+
+      gateways.each_with_index do |gw, i|
+        GATEWAY_METHODS.each do |method|
+          unless gw.respond_to?(method)
+            raise ConfigurationError,
+                  "gateway at index #{i} does not respond to ##{method}"
+          end
+        end
+      end
+
+      validate_no_duplicate_proof_headers!
+    end
+
+    def validate_no_duplicate_proof_headers!
+      seen = {}
+      gateways.each_with_index do |gw, i|
+        gw.proof_header_names.each do |name|
+          if seen.key?(name)
+            raise ConfigurationError,
+                  "duplicate proof header \"#{name}\" claimed by gateways at indices #{seen[name]} and #{i}"
+          end
+          seen[name] = i
+        end
+      end
+    end
+
+    def method_matches?(route_method, request_method)
+      route_method == "*" || route_method == request_method.upcase
+    end
+
+    def path_matches?(route_path, request_path)
+      case route_path
+      when Regexp then route_path.match?(request_path)
+      when String then route_path == request_path
+      else false
+      end
+    end
+  end
+end

data/lib/x402/errors.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module X402
+  class Error < StandardError; end
+
+  class ConfigurationError < Error; end
+
+  class VerificationError < Error
+    attr_reader :reason, :status
+
+    def initialize(reason, status: 400)
+      @reason = reason
+      @status = status
+      super(reason)
+    end
+  end
+end

data/lib/x402/middleware.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "rack"
+require "json"
+
+module X402
+  class Middleware
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      request = Rack::Request.new(env)
+      config = X402.configuration
+      route = config.find_route(request.request_method, request.path_info)
+
+      # Unprotected route — pass through
+      return @app.call(env) unless route
+
+      # Check for a proof/payment header from any gateway
+      gateway, header_name, proof_payload = detect_proof(env, config)
+
+      if gateway
+        settle_and_forward(env, gateway, header_name, proof_payload, request, route)
+      else
+        issue_challenge(request, route, config)
+      end
+    end
+
+    private
+
+    def detect_proof(env, config)
+      config.gateways.each do |gw|
+        gw.proof_header_names.each do |name|
+          rack_key = rack_header_key(name)
+          value = env[rack_key]
+          return [gw, name, value] if value && !value.empty?
+        end
+      end
+      nil
+    end
+
+    def issue_challenge(request, route, config)
+      headers = { "content-type" => "application/json" }
+
+      config.gateways.each do |gw|
+        gw.challenge_headers(request, route).each do |name, value|
+          headers[name.downcase] = value
+        end
+      end
+
+      body = JSON.generate({ error: "Payment Required" })
+      [402, headers, [body]]
+    end
+
+    def settle_and_forward(env, gateway, header_name, proof_payload, request, route)
+      result = gateway.settle!(header_name, proof_payload, request, route)
+
+      status, headers, body = @app.call(env)
+
+      # Merge any receipt headers from the gateway
+      if result.respond_to?(:receipt_headers) && result.receipt_headers
+        result.receipt_headers.each do |name, value|
+          headers[name.downcase] = value
+        end
+      end
+
+      [status, headers, body]
+    rescue X402::VerificationError => e
+      error_response(e.status, e.reason)
+    rescue X402::Error => e
+      error_response(400, e.message)
+    rescue StandardError => e
+      error_response(500, "internal error: #{e.message}")
+    end
+
+    def error_response(status, reason)
+      body = JSON.generate({ error: reason })
+      [status, { "content-type" => "application/json" }, [body]]
+    end
+
+    def rack_header_key(http_header_name)
+      "HTTP_#{http_header_name.upcase.tr("-", "_")}"
+    end
+  end
+end

data/lib/x402/protocol/base64url.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module X402
+  module Base64Url
+    module_function
+
+    def encode(data)
+      Base64.urlsafe_encode64(data, padding: false)
+    end
+
+    def decode(data)
+      Base64.urlsafe_decode64(data)
+    rescue ArgumentError => e
+      raise X402::Error, "invalid base64url: #{e.message}"
+    end
+  end
+end

data/lib/x402/protocol/challenge.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+
+module X402
+  class Challenge
+    CURRENT_VERSION = 1
+    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
+
+    def initialize(attrs = {})
+      attrs.each { |k, v| instance_variable_set(:"@#{k}", v) }
+    end
+
+    def to_h
+      {
+        version: @version,
+        scheme: @scheme,
+        domain: @domain,
+        method: @method,
+        path: @path,
+        query: @query,
+        req_headers_sha256: @req_headers_sha256,
+        req_body_sha256: @req_body_sha256,
+        amount_sats: @amount_sats,
+        payee_locking_script_hex: @payee_locking_script_hex,
+        nonce_txid: @nonce_txid,
+        nonce_vout: @nonce_vout,
+        nonce_satoshis: @nonce_satoshis,
+        nonce_locking_script_hex: @nonce_locking_script_hex,
+        expires_at: @expires_at
+      }
+    end
+
+    def to_canonical_json
+      to_h.to_json_c14n
+    end
+
+    def sha256_hex
+      OpenSSL::Digest::SHA256.hexdigest(to_canonical_json)
+    end
+
+    def to_header
+      Base64Url.encode(to_canonical_json)
+    end
+
+    # Reconstruct a challenge from the echoed X402-Challenge header.
+    def self.from_header(header_value)
+      json = Base64Url.decode(header_value)
+      data = JSON.parse(json, symbolize_names: true)
+      new(data)
+    rescue JSON::ParserError => e
+      raise X402::Error, "invalid challenge JSON: #{e.message}"
+    end
+  end
+end

data/lib/x402/protocol/proof.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "json"
+
+module X402
+  class Proof
+    attr_reader :challenge_sha256, :payment
+
+    def initialize(challenge_sha256:, payment:)
+      @challenge_sha256 = challenge_sha256
+      @payment = payment
+    end
+
+    # Parse a proof from the X402-Proof header (base64url-encoded JSON).
+    def self.from_header(header_value)
+      json = Base64Url.decode(header_value)
+      data = JSON.parse(json, symbolize_names: true)
+
+      new(
+        challenge_sha256: data[:challenge_sha256],
+        payment: data[:payment]
+      )
+    rescue JSON::ParserError => e
+      raise X402::Error, "invalid proof JSON: #{e.message}"
+    end
+
+    # Convenience accessors for payment fields.
+    def rawtx_b64
+      @payment&.fetch(:rawtx_b64, nil)
+    end
+
+    def txid
+      @payment&.fetch(:txid, nil)
+    end
+  end
+end

data/lib/x402/protocol/request_binding.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module X402
+  # Computes canonical hashes of request headers and body for binding
+  # challenges and proofs to the actual HTTP request.
+  module RequestBinding
+    module_function
+
+    # Compute SHA-256 hex digest of the request body.
+    # Returns the hash of an empty string if no body is present.
+    def body_sha256(rack_request)
+      return sha256_hex("") unless rack_request.body
+
+      rack_request.body.rewind if rack_request.body.respond_to?(:rewind)
+      body = rack_request.body.read || ""
+      rack_request.body.rewind if rack_request.body.respond_to?(:rewind)
+      sha256_hex(body)
+    end
+
+    # Compute SHA-256 hex digest of canonical request headers.
+    # For v1, this is the empty string hash (no headers bound).
+    def headers_sha256(_rack_request)
+      sha256_hex("")
+    end
+
+    def sha256_hex(data)
+      OpenSSL::Digest::SHA256.hexdigest(data)
+    end
+  end
+end

data/lib/x402/settlement_result.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module X402
+  # Returned by Gateway#settle! on successful settlement.
+  #
+  # @attr receipt_headers [Hash] HTTP headers to include in the 200 response
+  # @attr txid [String, nil] transaction identifier
+  # @attr network [String, nil] CAIP-2 network identifier (e.g. "bsv:mainnet")
+  SettlementResult = Struct.new(:receipt_headers, :txid, :network, keyword_init: true) do
+    def initialize(receipt_headers: {}, txid: nil, network: nil)
+      super
+    end
+  end
+end

data/lib/x402/verification/protocol_checks.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module X402
+  module Verification
+    module ProtocolChecks
+      module_function
+
+      def check_version!(challenge)
+        return if challenge.version == Challenge::CURRENT_VERSION
+
+        raise VerificationError, "unsupported version: #{challenge.version}"
+      end
+
+      def check_scheme!(challenge)
+        return if Challenge::SUPPORTED_SCHEMES.include?(challenge.scheme)
+
+        raise VerificationError, "unsupported scheme: #{challenge.scheme}"
+      end
+
+      def check_challenge_hash!(challenge, proof)
+        raise VerificationError, "challenge hash mismatch" unless challenge.sha256_hex == proof.challenge_sha256
+      end
+
+      def check_request_binding!(challenge, rack_request)
+        raise VerificationError, "request method mismatch" unless challenge.method == rack_request.request_method
+        raise VerificationError, "request path mismatch" unless challenge.path == rack_request.path_info
+        raise VerificationError, "request query mismatch" unless challenge.query == rack_request.query_string
+
+        expected_body = RequestBinding.body_sha256(rack_request)
+        raise VerificationError, "request body hash mismatch" unless challenge.req_body_sha256 == expected_body
+
+        expected_headers = RequestBinding.headers_sha256(rack_request)
+        return if challenge.req_headers_sha256 == expected_headers
+
+        raise VerificationError, "request headers hash mismatch"
+      end
+
+      def check_expiry!(challenge)
+        raise VerificationError.new("challenge expired", status: 402) if challenge.expires_at <= Time.now.to_i
+      end
+    end
+  end
+end

data/lib/x402/version.rb

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

data/lib/x402.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "x402/version"
+require_relative "x402/errors"
+require_relative "x402/settlement_result"
+require_relative "x402/configuration"
+require_relative "x402/middleware"
+
+module X402
+  class << self
+    def configure
+      yield(configuration)
+      configuration.validate!
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

data/sig/x402.rbs

@@ -0,0 +1,4 @@
+module X402
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,140 @@
+--- !ruby/object:Gem::Specification
+name: x402-rack
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Simon Bettison
+bindir: exe
+cert_chain: []
+date: 2026-03-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: bsv-sdk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: bsv-wallet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: json-canonicalization
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Rack middleware implementing the x402 stateless settlement-gated HTTP
+  protocol using BSV (Bitcoin SV) payments.
+email:
+- simon@bettison.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".claude/plans/20260325-bsv-module.md"
+- ".claude/plans/20260326-rack-stack-architecture.md"
+- ".rspec"
+- ".rubocop.yml"
+- CLAUDE.md
+- DESIGN.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- docs/process-flow/pay_gateway.md
+- lib/x402.rb
+- lib/x402/bsv.rb
+- lib/x402/bsv/gateway.rb
+- lib/x402/bsv/pay_gateway.rb
+- lib/x402/bsv/proof_gateway.rb
+- lib/x402/configuration.rb
+- lib/x402/errors.rb
+- lib/x402/middleware.rb
+- lib/x402/protocol/base64url.rb
+- lib/x402/protocol/challenge.rb
+- lib/x402/protocol/proof.rb
+- lib/x402/protocol/request_binding.rb
+- lib/x402/settlement_result.rb
+- lib/x402/verification/protocol_checks.rb
+- lib/x402/version.rb
+- sig/x402.rbs
+homepage: https://github.com/sgbett/x402-rack
+licenses:
+- LicenseRef-OpenBSV
+metadata:
+  source_code_uri: https://github.com/sgbett/x402-rack
+  changelog_uri: https://github.com/sgbett/x402-rack/blob/master/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: x402 protocol server middleware for BSV micropayments
+test_files: []