remitmd 0.1.5 → 0.1.7

data/lib/remitmd/x402_client.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require "securerandom"
+require "base64"
+
+module Remitmd
+  # Raised when an x402 payment amount exceeds the configured auto-pay limit.
+  class AllowanceExceededError < RemitError
+    attr_reader :amount_usdc, :limit_usdc
+
+    def initialize(amount_usdc, limit_usdc)
+      @amount_usdc = amount_usdc
+      @limit_usdc  = limit_usdc
+      super(
+        "ALLOWANCE_EXCEEDED",
+        "x402 payment #{format("%.6f", amount_usdc)} USDC exceeds auto-pay limit #{format("%.6f", limit_usdc)} USDC"
+      )
+    end
+  end
+
+  # x402 client — fetch wrapper that auto-pays HTTP 402 Payment Required responses.
+  #
+  # On receiving a 402, the client:
+  # 1. Decodes the PAYMENT-REQUIRED header (base64 JSON)
+  # 2. Checks the amount is within max_auto_pay_usdc
+  # 3. Builds and signs an EIP-3009 transferWithAuthorization
+  # 4. Base64-encodes the PAYMENT-SIGNATURE header
+  # 5. Retries the original request with payment attached
+  #
+  # @example
+  #   signer = Remitmd::PrivateKeySigner.new("0x...")
+  #   client = Remitmd::X402Client.new(wallet: signer)
+  #   response = client.fetch("https://api.provider.com/v1/data")
+  #
+  class X402Client
+    attr_reader :last_payment
+
+    # @param wallet [#sign, #address] a signer that can sign EIP-712 digests
+    # @param max_auto_pay_usdc [Float] maximum USDC amount to auto-pay per request (default: 0.10)
+    def initialize(wallet:, max_auto_pay_usdc: 0.10)
+      @wallet            = wallet
+      @max_auto_pay_usdc = max_auto_pay_usdc
+      @last_payment      = nil
+    end
+
+    # Make an HTTP request, auto-paying any 402 responses within the configured limit.
+    #
+    # @param url [String] the URL to fetch
+    # @param method [Symbol] HTTP method (:get, :post, etc.)
+    # @param headers [Hash] additional request headers
+    # @param body [String, nil] request body (for POST/PUT)
+    # @return [Net::HTTPResponse]
+    def fetch(url, method: :get, headers: {}, body: nil)
+      uri  = URI(url)
+      resp = make_request(uri, method, headers, body)
+
+      if resp.code.to_i == 402
+        handle402(uri, resp, method, headers, body)
+      else
+        resp
+      end
+    end
+
+    private
+
+    def make_request(uri, method, headers, body)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.read_timeout = 15
+
+      req = case method
+            when :get    then Net::HTTP::Get.new(uri)
+            when :post   then Net::HTTP::Post.new(uri)
+            when :put    then Net::HTTP::Put.new(uri)
+            when :delete then Net::HTTP::Delete.new(uri)
+            else              Net::HTTP::Get.new(uri)
+            end
+
+      headers.each { |k, v| req[k.to_s] = v.to_s }
+      req.body = body if body
+      http.request(req)
+    end
+
+    def handle402(uri, response, method, headers, body)
+      # 1. Decode PAYMENT-REQUIRED header.
+      raw = response["payment-required"] || response["PAYMENT-REQUIRED"]
+      raise RemitError.new("SERVER_ERROR", "402 response missing PAYMENT-REQUIRED header") unless raw
+
+      required = JSON.parse(Base64.decode64(raw))
+
+      # 2. Only "exact" scheme is supported.
+      unless required["scheme"] == "exact"
+        raise RemitError.new("SERVER_ERROR", "Unsupported x402 scheme: #{required["scheme"]}")
+      end
+
+      # Store for caller inspection (V2 fields: resource, description, mimeType).
+      @last_payment = required
+
+      # 3. Check auto-pay limit.
+      amount_base_units = required["amount"].to_i
+      amount_usdc       = amount_base_units / 1_000_000.0
+      if amount_usdc > @max_auto_pay_usdc
+        raise AllowanceExceededError.new(amount_usdc, @max_auto_pay_usdc)
+      end
+
+      # 4. Parse chainId from CAIP-2 network string (e.g. "eip155:84532" -> 84532).
+      chain_id = required["network"].split(":")[1].to_i
+
+      # 5. Build EIP-3009 authorization fields.
+      now_secs     = Time.now.to_i
+      valid_before = now_secs + (required["maxTimeoutSeconds"] || 60).to_i
+      nonce_bytes  = SecureRandom.bytes(32)
+      nonce_hex    = "0x#{nonce_bytes.unpack1("H*")}"
+
+      # 6. Sign EIP-712 typed data for TransferWithAuthorization.
+      digest = eip3009_digest(
+        chain_id:     chain_id,
+        asset:        required["asset"],
+        from:         @wallet.address,
+        to:           required["payTo"],
+        value:        amount_base_units,
+        valid_after:  0,
+        valid_before: valid_before,
+        nonce_bytes:  nonce_bytes
+      )
+      signature = @wallet.sign(digest)
+
+      # 7. Build PAYMENT-SIGNATURE JSON payload.
+      payment_payload = {
+        scheme:      required["scheme"],
+        network:     required["network"],
+        x402Version: 1,
+        payload: {
+          signature:     signature,
+          authorization: {
+            from:        @wallet.address,
+            to:          required["payTo"],
+            value:       required["amount"],
+            validAfter:  "0",
+            validBefore: valid_before.to_s,
+            nonce:       nonce_hex,
+          },
+        },
+      }
+      payment_header = Base64.strict_encode64(JSON.generate(payment_payload))
+
+      # 8. Retry with PAYMENT-SIGNATURE header.
+      new_headers = headers.merge("PAYMENT-SIGNATURE" => payment_header)
+      make_request(uri, method, new_headers, body)
+    end
+
+    # Compute the EIP-712 hash for EIP-3009 TransferWithAuthorization.
+    def eip3009_digest(chain_id:, asset:, from:, to:, value:, valid_after:, valid_before:, nonce_bytes:)
+      # Domain separator: USD Coin / version 2
+      domain_type_hash = keccak256(
+        "EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)"
+      )
+      name_hash     = keccak256("USD Coin")
+      version_hash  = keccak256("2")
+      chain_id_enc  = abi_uint256(chain_id)
+      contract_enc  = abi_address(asset)
+
+      domain_data      = domain_type_hash + name_hash + version_hash + chain_id_enc + contract_enc
+      domain_separator = keccak256(domain_data)
+
+      # TransferWithAuthorization struct hash
+      type_hash = keccak256(
+        "TransferWithAuthorization(address from,address to,uint256 value," \
+        "uint256 validAfter,uint256 validBefore,bytes32 nonce)"
+      )
+      struct_data = type_hash +
+                    abi_address(from) +
+                    abi_address(to) +
+                    abi_uint256(value) +
+                    abi_uint256(valid_after) +
+                    abi_uint256(valid_before) +
+                    nonce_bytes
+
+      struct_hash = keccak256(struct_data)
+
+      # Final EIP-712 hash
+      keccak256("\x19\x01" + domain_separator + struct_hash)
+    end
+
+    def keccak256(data)
+      Remitmd::Keccak.digest(data.b)
+    end
+
+    def abi_uint256(value)
+      [value.to_i.to_s(16).rjust(64, "0")].pack("H*")
+    end
+
+    def abi_address(addr)
+      hex = addr.to_s.delete_prefix("0x").rjust(64, "0")
+      [hex].pack("H*")
+    end
+  end
+end

data/lib/remitmd/x402_paywall.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require "base64"
+
+module Remitmd
+  # x402 paywall for service providers — gate HTTP endpoints behind payments.
+  #
+  # Providers use this class to:
+  # - Return HTTP 402 responses with properly formatted PAYMENT-REQUIRED headers
+  # - Verify incoming PAYMENT-SIGNATURE headers against the remit.md facilitator
+  #
+  # @example Rack middleware
+  #   paywall = Remitmd::X402Paywall.new(
+  #     wallet_address: "0xYourProviderWallet",
+  #     amount_usdc: 0.001,
+  #     network: "eip155:84532",
+  #     asset: "0x2d846325766921935f37d5b4478196d3ef93707c"
+  #   )
+  #   use paywall.rack_middleware
+  #
+  class X402Paywall
+    # @param wallet_address [String] provider's checksummed Ethereum address (the payTo field)
+    # @param amount_usdc [Float] price per request in USDC (e.g. 0.001)
+    # @param network [String] CAIP-2 network string (e.g. "eip155:84532")
+    # @param asset [String] USDC contract address on the target network
+    # @param facilitator_url [String] base URL of the remit.md facilitator
+    # @param facilitator_token [String] bearer JWT for authenticating calls to /api/v1/x402/verify
+    # @param max_timeout_seconds [Integer] how long the payment authorization remains valid
+    # @param resource [String, nil] V2 — URL or path of the resource being protected
+    # @param description [String, nil] V2 — human-readable description
+    # @param mime_type [String, nil] V2 — MIME type of the resource
+    def initialize( # rubocop:disable Metrics/ParameterLists
+      wallet_address:,
+      amount_usdc:,
+      network:,
+      asset:,
+      facilitator_url: "https://remit.md",
+      facilitator_token: "",
+      max_timeout_seconds: 60,
+      resource: nil,
+      description: nil,
+      mime_type: nil
+    )
+      @wallet_address      = wallet_address
+      @amount_base_units   = (amount_usdc * 1_000_000).round.to_s
+      @network             = network
+      @asset               = asset
+      @facilitator_url     = facilitator_url.chomp("/")
+      @facilitator_token   = facilitator_token
+      @max_timeout_seconds = max_timeout_seconds
+      @resource            = resource
+      @description         = description
+      @mime_type           = mime_type
+    end
+
+    # Return the base64-encoded JSON PAYMENT-REQUIRED header value.
+    # @return [String]
+    def payment_required_header
+      payload = {
+        scheme:            "exact",
+        network:           @network,
+        amount:            @amount_base_units,
+        asset:             @asset,
+        payTo:             @wallet_address,
+        maxTimeoutSeconds: @max_timeout_seconds,
+      }
+      payload[:resource]    = @resource    if @resource
+      payload[:description] = @description if @description
+      payload[:mimeType]    = @mime_type   if @mime_type
+      Base64.strict_encode64(JSON.generate(payload))
+    end
+
+    # Check whether a PAYMENT-SIGNATURE header represents a valid payment.
+    # Calls the remit.md facilitator's /api/v1/x402/verify endpoint.
+    #
+    # @param payment_sig [String, nil] the raw header value (base64 JSON), or nil if absent
+    # @return [Hash] { is_valid: true/false, invalid_reason: String or nil }
+    def check(payment_sig)
+      return { is_valid: false } unless payment_sig
+
+      payment_payload = begin
+        JSON.parse(Base64.decode64(payment_sig))
+      rescue JSON::ParserError
+        return { is_valid: false, invalid_reason: "INVALID_PAYLOAD" }
+      end
+
+      body = {
+        paymentPayload:  payment_payload,
+        paymentRequired: payment_required_object,
+      }
+
+      uri = URI("#{@facilitator_url}/api/v1/x402/verify")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.read_timeout = 10
+
+      req = Net::HTTP::Post.new(uri.path)
+      req["Content-Type"] = "application/json"
+      req["Authorization"] = "Bearer #{@facilitator_token}" unless @facilitator_token.empty?
+      req.body = JSON.generate(body)
+
+      begin
+        resp = http.request(req)
+        unless resp.is_a?(Net::HTTPSuccess)
+          return { is_valid: false, invalid_reason: "FACILITATOR_ERROR" }
+        end
+
+        data = JSON.parse(resp.body)
+      rescue StandardError
+        return { is_valid: false, invalid_reason: "FACILITATOR_ERROR" }
+      end
+
+      {
+        is_valid:       data["isValid"] == true,
+        invalid_reason: data["invalidReason"],
+      }
+    end
+
+    # Rack middleware adapter.
+    #
+    # @example
+    #   use paywall.rack_middleware
+    #
+    # @return [Class] a Rack middleware class
+    def rack_middleware
+      paywall = self
+      Class.new do
+        define_method(:initialize) do |app|
+          @app     = app
+          @paywall = paywall
+        end
+
+        define_method(:call) do |env|
+          payment_sig = env["HTTP_PAYMENT_SIGNATURE"]
+          result = @paywall.check(payment_sig)
+
+          unless result[:is_valid]
+            headers = {
+              "Content-Type"     => "application/json",
+              "PAYMENT-REQUIRED" => @paywall.payment_required_header,
+            }
+            body = JSON.generate({
+              error:         "Payment required",
+              invalidReason: result[:invalid_reason],
+            })
+            return [402, headers, [body]]
+          end
+
+          @app.call(env)
+        end
+      end
+    end
+
+    private
+
+    def payment_required_object
+      {
+        scheme:            "exact",
+        network:           @network,
+        amount:            @amount_base_units,
+        asset:             @asset,
+        payTo:             @wallet_address,
+        maxTimeoutSeconds: @max_timeout_seconds,
+      }
+    end
+  end
+end

data/lib/remitmd.rb

@@ -7,6 +7,9 @@ require_relative "remitmd/signer"
 require_relative "remitmd/http"
 require_relative "remitmd/wallet"
 require_relative "remitmd/mock"
+require_relative "remitmd/a2a"
+require_relative "remitmd/x402_client"
+require_relative "remitmd/x402_paywall"
 
 # remit.md Ruby SDK — universal payment protocol for AI agents.
 #
@@ -22,5 +25,5 @@ require_relative "remitmd/mock"
 #   mock.was_paid?("0x0000000000000000000000000000000000000001", 1.00) # => true
 #
 module Remitmd
-  VERSION = "0.1.5"
+  VERSION = "0.1.7"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: remitmd
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.7
 platform: ruby
 authors:
 - remit.md
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-23 00:00:00.000000000 Z
+date: 2026-03-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -58,6 +58,8 @@ files:
 - lib/remitmd/models.rb
 - lib/remitmd/signer.rb
 - lib/remitmd/wallet.rb
+- lib/remitmd/x402_client.rb
+- lib/remitmd/x402_paywall.rb
 homepage: https://remit.md
 licenses:
 - MIT