ruby-x402 0.1.0

data/lib/x402/rack/require_payment.rb

@@ -0,0 +1,113 @@
+require "json"
+require_relative "../encoding"
+require_relative "../facilitator_client"
+require_relative "../server/requirements"
+require_relative "../types/payment_payload"
+
+module X402
+  module Rack
+    class RequirePayment
+      X402_VERSION = 1
+
+      def initialize(app, config:)
+        @app = app
+        @config = symbolize_keys(config || {})
+        @client = X402::FacilitatorClient.new(
+          url: @config.dig(:facilitator, :url) || X402::FacilitatorClient::DEFAULT_URL,
+          create_headers: @config.dig(:facilitator, :create_headers)
+        )
+        @mode = (@config[:mode] || :settle_sync).to_sym
+      end
+
+      def call(env)
+        req_path = env["PATH_INFO"].to_s
+        accepts = X402::Server::Requirements.build_for(path: req_path, config: @config)
+        return @app.call(env) if accepts.empty?
+
+        x_payment = env["HTTP_X_PAYMENT"]
+        unless x_payment && !x_payment.empty?
+          return payment_required_response(accepts, "X-PAYMENT header is required")
+        end
+
+        begin
+          decoded = X402::Encoding.decode_header(x_payment)
+          payload = X402::Types::PaymentPayload.from_hash(decoded)
+        rescue StandardError => e
+          return payment_required_response(accepts, "Invalid X-PAYMENT header: #{e.message}")
+        end
+
+        selected = select_requirements_for_payload(accepts, payload)
+        unless selected
+          return payment_required_response(accepts, "Unsupported scheme or network for this route")
+        end
+
+        verify = @client.verify(payment: payload, payment_requirements: selected)
+        unless verify.is_valid
+          return payment_required_response(accepts, "Payment verification failed: #{verify.invalid_reason || "invalid"}")
+        end
+
+        x_payment_response = nil
+        if @mode == :settle_sync
+          settle = @client.settle(payment: payload, payment_requirements: selected)
+          x_payment_response = X402::Encoding.encode_header(settle.to_h)
+        elsif @mode == :settle_async && defined?(::ActiveJob::Base)
+          # Enqueue background settlement; response header will not be populated synchronously
+          begin
+            X402::Rails::SettleJob.perform_later(payload: payload.to_h, payment_requirements: selected.to_h)
+          rescue StandardError
+            # If enqueue fails, fall back to sync settle
+            settle = @client.settle(payment: payload, payment_requirements: selected)
+            x_payment_response = X402::Encoding.encode_header(settle.to_h)
+          end
+        else
+          # :verify_only or unknown mode: do nothing beyond verification
+        end
+
+        status, headers, body = @app.call(env)
+        headers = headers.dup
+        if x_payment_response
+          headers["X-PAYMENT-RESPONSE"] = x_payment_response
+        end
+        headers["Access-Control-Expose-Headers"] = [headers["Access-Control-Expose-Headers"], "X-PAYMENT-RESPONSE"].compact.join(", ")
+        [status, headers, body]
+      end
+
+      private
+
+      def payment_required_response(accepts, error)
+        body_hash = {
+          "x402Version" => X402_VERSION,
+          "error" => error,
+          "accepts" => accepts.map(&:to_h)
+        }
+        body = JSON.generate(body_hash)
+        headers = {
+          "Content-Type" => "application/json",
+          "Access-Control-Expose-Headers" => "X-PAYMENT-RESPONSE"
+        }
+        [402, headers, [body]]
+      end
+
+      def select_requirements_for_payload(accepts, payload)
+        accepts.find do |req|
+          req.scheme == payload.scheme && req.network == payload.network
+        end
+      end
+
+      def symbolize_keys(obj)
+        case obj
+        when Hash
+          obj.each_with_object({}) do |(k, v), acc|
+            acc[(k.to_sym rescue k) || k] = symbolize_keys(v)
+          end
+        when Array
+          obj.map { |v| symbolize_keys(v) }
+        else
+          obj
+        end
+      end
+    end
+  end
+end
+
+

data/lib/x402/rails/controller_concern.rb

@@ -0,0 +1,27 @@
+begin
+  require "active_support/concern"
+rescue LoadError
+  # ActiveSupport not available
+end
+
+module X402
+  module Rails
+    module ControllerConcern
+      extend ::ActiveSupport::Concern if defined?(::ActiveSupport::Concern)
+
+      class_methods do
+        def require_x402_payment(path:, evm: nil, svm: nil, description: nil, mime_type: nil)
+          return unless defined?(::ActiveSupport::Concern)
+          routes = X402.config.routes.dup
+          routes[path] ||= {}
+          routes[path][:evm] = (evm || {}).merge(description: description, mime_type: mime_type).compact if evm
+          routes[path][:svm] = (svm || {}).merge(description: description, mime_type: mime_type).compact if svm
+          X402.config.routes = routes
+        end
+      end if respond_to?(:class_methods, true)
+    end
+  end
+end
+
+
+

data/lib/x402/rails/settle_job.rb

@@ -0,0 +1,30 @@
+begin
+  require "active_job"
+rescue LoadError
+  # ActiveJob not available
+end
+
+require_relative "../facilitator_client"
+
+module X402
+  module Rails
+    class SettleJob < (defined?(::ActiveJob::Base) ? ::ActiveJob::Base : Object)
+      queue_as :default if respond_to?(:queue_as)
+
+      def perform(payload:, payment_requirements:)
+        return unless defined?(::ActiveJob::Base)
+        client = ::X402::FacilitatorClient.new(
+          url: ::X402.config.facilitator.url,
+          create_headers: ::X402.config.facilitator.create_headers
+        )
+        client.settle(
+          payment: ::X402::Types::PaymentPayload.from_hash(payload),
+          payment_requirements: ::X402::Types::PaymentRequirements.from_hash(payment_requirements)
+        )
+      end
+    end
+  end
+end
+
+
+

data/lib/x402/railtie.rb

@@ -0,0 +1,35 @@
+begin
+  require "rails/railtie"
+rescue LoadError
+  # Rails not available; Railtie will not be loaded
+end
+
+require_relative "rack/require_payment"
+
+module X402
+  class Railtie < ::Rails::Railtie
+    initializer "x402.configure_middleware" do |app|
+      # Ensure config is valid before inserting middleware
+      begin
+        X402.config.validate!
+      rescue StandardError
+        # Defer validation errors until first use; don't crash boot in development
+      end
+
+      app.config.middleware.insert_after(
+        defined?(ActionDispatch::Executor) ? ActionDispatch::Executor : 0,
+        X402::Rack::RequirePayment,
+        config: X402.config.to_h
+      )
+    end
+
+    initializer "x402.filter_parameters" do |app|
+      if app.config.respond_to?(:filter_parameters)
+        app.config.filter_parameters |= [:x_payment, :x_payment_response]
+      end
+    end
+  end
+end
+
+
+

data/lib/x402/server/requirements.rb

@@ -0,0 +1,74 @@
+require_relative "../types/payment_requirements"
+
+module X402
+  module Server
+    class Requirements
+      DEFAULT_TIMEOUT = 60
+
+      # Build an array of PaymentRequirements for a given request path
+      # config:
+      # {
+      #   networks: ["base-sepolia", "solana-devnet"],
+      #   routes: {
+      #     "/paid" => { evm: { amount: "1000000" }, svm: { amount: "1000000" } }
+      #   },
+      #   evm: { asset: "0x...", pay_to: "0x...", extra: { name: "USDC", version: "2" } },
+      #   svm: { asset: "EPjF...", pay_to: "SoL...", extra: { fee_payer: "SoL..." } },
+      #   max_timeout_seconds: 60
+      # }
+      def self.build_for(path:, config:)
+        route = find_route_config(path, config.fetch(:routes, {}))
+        return [] unless route
+
+        accepts = []
+        timeout = (config[:max_timeout_seconds] || DEFAULT_TIMEOUT).to_i
+
+        if config.fetch(:networks, []).any? { |n| n.include?("base") } && route[:evm]
+          accepts << X402::Types::PaymentRequirements.new(
+            scheme: "exact",
+            network: config[:networks].find { |n| n.include?("base") },
+            max_amount_required: route[:evm][:amount].to_s,
+            resource: path,
+            description: route[:evm][:description] || "Paid resource",
+            mime_type: route[:evm][:mime_type] || "application/json",
+            pay_to: config.dig(:evm, :pay_to),
+            max_timeout_seconds: timeout,
+            asset: config.dig(:evm, :asset),
+            extra: config.dig(:evm, :extra) || {}
+          )
+        end
+
+        if config.fetch(:networks, []).any? { |n| n.start_with?("solana") } && route[:svm]
+          accepts << X402::Types::PaymentRequirements.new(
+            scheme: "exact",
+            network: config[:networks].find { |n| n.start_with?("solana") },
+            max_amount_required: route[:svm][:amount].to_s,
+            resource: path,
+            description: route[:svm][:description] || "Paid resource",
+            mime_type: route[:svm][:mime_type] || "application/json",
+            pay_to: config.dig(:svm, :pay_to),
+            max_timeout_seconds: timeout,
+            asset: config.dig(:svm, :asset),
+            extra: config.dig(:svm, :extra) || {}
+          )
+        end
+
+        accepts
+      end
+
+      def self.find_route_config(path, routes)
+        # exact match (string or symbol) or first regex match
+        return routes[path] if routes.key?(path)
+        sym_key = (path.to_sym rescue nil)
+        return routes[sym_key] if sym_key && routes.key?(sym_key)
+        key = routes.keys.find do |k|
+          k.is_a?(Regexp) ? k.match?(path) : false
+        end
+        key ? routes[key] : nil
+      end
+      private_class_method :find_route_config
+    end
+  end
+end
+
+

data/lib/x402/types/networks.rb

@@ -0,0 +1,19 @@
+module X402
+  module Types
+    module Networks
+      EVM = [
+        "base",
+        "base-sepolia"
+      ].freeze
+
+      SVM = [
+        "solana",
+        "solana-devnet"
+      ].freeze
+
+      ALL = (EVM + SVM).freeze
+    end
+  end
+end
+
+

data/lib/x402/types/payment_payload.rb

@@ -0,0 +1,94 @@
+require "json"
+
+module X402
+  module Types
+    class PaymentPayload
+      attr_reader :x402_version, :scheme, :network, :payload
+
+      def initialize(x402_version:, scheme:, network:, payload:)
+        @x402_version = Integer(x402_version)
+        @scheme = scheme
+        @network = network
+        @payload = payload # Hash; scheme-specific
+        validate!
+      end
+
+      def self.from_hash(hash)
+        h = stringify_keys(hash)
+        new(
+          x402_version: h["x402Version"] || h["x402_version"],
+          scheme: h["scheme"],
+          network: h["network"],
+          payload: h["payload"] || {}
+        )
+      end
+
+      def self.from_json(json)
+        from_hash(JSON.parse(json))
+      end
+
+      def to_h
+        {
+          "x402Version" => x402_version,
+          "scheme" => scheme,
+          "network" => network,
+          "payload" => payload
+        }
+      end
+
+      def to_json(*args)
+        JSON.generate(to_h, *args)
+      end
+
+      def exact_evm?
+        scheme == "exact" && network.include?("base")
+      end
+
+      def exact_svm?
+        scheme == "exact" && network.start_with?("solana")
+      end
+
+      class << self
+        private
+
+        def stringify_keys(obj)
+          case obj
+          when Hash
+            obj.each_with_object({}) { |(k, v), acc| acc[k.to_s] = stringify_keys(v) }
+          when Array
+            obj.map { |v| stringify_keys(v) }
+          else
+            obj
+          end
+        end
+      end
+
+      private
+
+      def validate!
+        unless x402_version == 1
+          raise X402::Errors::ValidationError, "invalid_x402_version"
+        end
+        unless X402::Types::Networks::ALL.include?(network)
+          raise X402::Errors::ValidationError, "invalid_network"
+        end
+        unless scheme == "exact"
+          raise X402::Errors::ValidationError, "invalid_scheme"
+        end
+        unless payload.is_a?(Hash)
+          raise X402::Errors::ValidationError, "invalid_payload"
+        end
+        if exact_evm?
+          auth = payload["authorization"] || payload[:authorization]
+          sig = payload["signature"] || payload[:signature]
+          required = %w[from to value validAfter validBefore nonce]
+          if sig.to_s.empty? || !auth.is_a?(Hash) || required.any? { |k| (auth[k] || auth[k.to_sym]).to_s.empty? }
+            raise X402::Errors::ValidationError, "invalid_payload"
+          end
+        end
+      end
+    end
+  end
+end
+
+

data/lib/x402/types/payment_requirements.rb

@@ -0,0 +1,120 @@
+require "json"
+
+module X402
+  module Types
+    class PaymentRequirements
+      attr_reader :scheme, :network, :max_amount_required, :resource,
+                  :description, :mime_type, :output_schema, :pay_to,
+                  :max_timeout_seconds, :asset, :extra
+
+      def initialize(scheme:, network:, max_amount_required:, resource:,
+                     description:, mime_type:, pay_to:, max_timeout_seconds:,
+                     asset:, output_schema: nil, extra: nil)
+        @scheme = scheme
+        @network = network
+        @max_amount_required = max_amount_required.to_s
+        @resource = resource
+        @description = description
+        @mime_type = mime_type
+        @output_schema = output_schema
+        @pay_to = pay_to
+        @max_timeout_seconds = Integer(max_timeout_seconds)
+        @asset = asset
+        @extra = extra || {}
+        validate!
+      end
+
+      def self.from_hash(hash)
+
+        h = stringify_keys(hash)
+        new(
+          scheme: h["scheme"],
+          network: h["network"],
+          max_amount_required: h["maxAmountRequired"] || h["max_amount_required"],
+          resource: h["resource"],
+          description: h["description"],
+          mime_type: h["mimeType"] || h["mime_type"],
+          output_schema: h["outputSchema"] || h["output_schema"],
+          pay_to: h["payTo"] || h["pay_to"],
+          max_timeout_seconds: h["maxTimeoutSeconds"] || h["max_timeout_seconds"],
+          asset: h["asset"],
+          extra: h["extra"] || {}
+        )
+      end
+
+      def self.from_json(json)
+        from_hash(JSON.parse(json))
+      end
+
+      def to_h
+        {
+          "scheme" => scheme,
+          "network" => network,
+          "maxAmountRequired" => max_amount_required,
+          "resource" => resource,
+          "description" => description,
+          "mimeType" => mime_type,
+          "outputSchema" => output_schema,
+          "payTo" => pay_to,
+          "maxTimeoutSeconds" => max_timeout_seconds,
+          "asset" => asset,
+          "extra" => extra
+        }.reject { |_, v| v.nil? }
+      end
+
+      def to_json(*args)
+        JSON.generate(to_h, *args)
+      end
+
+      def evm?
+        network.include?("base")
+      end
+
+      def svm?
+        network.start_with?("solana")
+      end
+
+      class << self
+        private
+
+        def stringify_keys(obj)
+          case obj
+          when Hash
+            obj.each_with_object({}) { |(k, v), acc| acc[k.to_s] = stringify_keys(v) }
+          when Array
+            obj.map { |v| stringify_keys(v) }
+          else
+            obj
+          end
+        end
+      end
+
+      private
+
+      def validate!
+        required = {
+          "scheme" => scheme,
+          "network" => network,
+          "maxAmountRequired" => max_amount_required,
+          "resource" => resource,
+          "description" => description,
+          "payTo" => pay_to,
+          "maxTimeoutSeconds" => max_timeout_seconds,
+          "asset" => asset
+        }
+        missing = required.select { |_, v| v.nil? || v.to_s.strip.empty? }.keys
+        unless missing.empty?
+          raise X402::Errors::ValidationError, "Missing PaymentRequirements fields: #{missing.join(", ")}"
+        end
+        unless X402::Types::Networks::ALL.include?(network)
+          raise X402::Errors::ValidationError, "Unsupported network: #{network}"
+        end
+        unless scheme == "exact"
+          raise X402::Errors::ValidationError, "Unsupported scheme: #{scheme}"
+        end
+      end
+    end
+  end
+end
+
+

data/lib/x402/types/responses.rb

@@ -0,0 +1,153 @@
+require "json"
+require_relative "payment_requirements"
+
+module X402
+  module Types
+    class VerifyResponse
+      attr_reader :is_valid, :invalid_reason, :payer
+
+      def initialize(is_valid:, invalid_reason: nil, payer: nil)
+        @is_valid = !!is_valid
+        @invalid_reason = invalid_reason
+        @payer = payer
+      end
+
+      def self.from_hash(hash)
+        h = stringify_keys(hash)
+        new(
+          is_valid: h["isValid"] || h["is_valid"],
+          invalid_reason: h["invalidReason"] || h["invalid_reason"],
+          payer: h["payer"]
+        )
+      end
+
+      def to_h
+        {
+          "isValid" => is_valid,
+          "invalidReason" => invalid_reason,
+          "payer" => payer
+        }.reject { |_, v| v.nil? }
+      end
+
+      def to_json(*args)
+        JSON.generate(to_h, *args)
+      end
+
+      class << self
+        private
+
+        def stringify_keys(obj)
+          case obj
+          when Hash
+            obj.each_with_object({}) { |(k, v), acc| acc[k.to_s] = stringify_keys(v) }
+          when Array
+            obj.map { |v| stringify_keys(v) }
+          else
+            obj
+          end
+        end
+      end
+    end
+
+    class SettleResponse
+      attr_reader :success, :error_reason, :transaction, :network, :payer
+
+      def initialize(success:, error_reason: nil, transaction: nil, network: nil, payer: nil)
+        @success = !!success
+        @error_reason = error_reason
+        @transaction = transaction
+        @network = network
+        @payer = payer
+      end
+
+      def self.from_hash(hash)
+        h = stringify_keys(hash)
+        new(
+          success: h["success"],
+          error_reason: h["errorReason"] || h["error_reason"],
+          transaction: h["transaction"],
+          network: h["network"],
+          payer: h["payer"]
+        )
+      end
+
+      def to_h
+        {
+          "success" => success,
+          "errorReason" => error_reason,
+          "transaction" => transaction,
+          "network" => network,
+          "payer" => payer
+        }.reject { |_, v| v.nil? }
+      end
+
+      def to_json(*args)
+        JSON.generate(to_h, *args)
+      end
+
+      class << self
+        private
+
+        def stringify_keys(obj)
+          case obj
+          when Hash
+            obj.each_with_object({}) { |(k, v), acc| acc[k.to_s] = stringify_keys(v) }
+          when Array
+            obj.map { |v| stringify_keys(v) }
+          else
+            obj
+          end
+        end
+      end
+    end
+
+    class PaymentRequiredResponse
+      attr_reader :x402_version, :accepts, :error
+
+      def initialize(x402_version:, accepts:, error:)
+        @x402_version = Integer(x402_version)
+        @accepts = accepts
+        @error = error
+      end
+
+      def self.from_hash(hash)
+        h = stringify_keys(hash)
+        accepts = (h["accepts"] || []).map { |pr| PaymentRequirements.from_hash(pr) }
+        new(
+          x402_version: h["x402Version"] || h["x402_version"],
+          accepts: accepts,
+          error: h["error"]
+        )
+      end
+
+      def to_h
+        {
+          "x402Version" => x402_version,
+          "accepts" => accepts.map(&:to_h),
+          "error" => error
+        }
+      end
+
+      def to_json(*args)
+        JSON.generate(to_h, *args)
+      end
+
+      class << self
+        private
+
+        def stringify_keys(obj)
+          case obj
+          when Hash
+            obj.each_with_object({}) { |(k, v), acc| acc[k.to_s] = stringify_keys(v) }
+          when Array
+            obj.map { |v| stringify_keys(v) }
+          else
+            obj
+          end
+        end
+      end
+    end
+  end
+end
+
+

data/lib/x402/version.rb

@@ -0,0 +1,5 @@
+module X402
+  VERSION = "0.1.0"
+end
+
+

data/lib/x402.rb

@@ -0,0 +1,23 @@
+require_relative "x402/version"
+require_relative "x402/errors"
+require_relative "x402/config"
+
+module X402
+  class << self
+    def configure
+      @config ||= X402::Config.new
+      yield @config if block_given?
+      @config
+    end
+
+    def config
+      @config ||= X402::Config.new
+    end
+
+    def reset_config!
+      @config = X402::Config.new
+    end
+  end
+end
+
+