mpp-rb 0.1.3 → 0.1.5

data/lib/mpp/x402/header.rb

@@ -0,0 +1,131 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "types"
+require "base64"
+require "json"
+
+module Mpp
+  module X402
+    # Base64 JSON codecs for x402 v2 headers.
+    #
+    # x402 uses standard (not url-safe) base64 of JSON, unlike Payment-auth
+    # which uses base64url.
+    module Header
+      extend T::Sig
+
+      module_function
+
+      sig { params(payment_required: T::Hash[T.untyped, T.untyped]).returns(String) }
+      def encode_payment_required(payment_required)
+        encode_json(payment_required)
+      end
+
+      sig { params(value: String).returns(T::Hash[T.untyped, T.untyped]) }
+      def decode_payment_required(value)
+        parsed = decode_json(value)
+        validate_payment_required!(parsed)
+        parsed
+      end
+
+      sig { params(payment_payload: T::Hash[T.untyped, T.untyped]).returns(String) }
+      def encode_payment_signature(payment_payload)
+        encode_json(payment_payload)
+      end
+
+      sig { params(value: String).returns(T::Hash[T.untyped, T.untyped]) }
+      def decode_payment_signature(value)
+        parsed = decode_json(value)
+        validate_payment_payload!(parsed)
+        parsed
+      end
+
+      sig { params(settle_response: T::Hash[T.untyped, T.untyped]).returns(String) }
+      def encode_payment_response(settle_response)
+        encode_json(settle_response)
+      end
+
+      sig { params(value: String).returns(T::Hash[T.untyped, T.untyped]) }
+      def decode_payment_response(value)
+        parsed = decode_json(value)
+        validate_settle_response!(parsed)
+        parsed
+      end
+
+      sig { params(obj: T.untyped).returns(String) }
+      def encode_json(obj)
+        json = Mpp::Json.compact_encode(obj)
+        Base64.strict_encode64(json)
+      end
+
+      sig { params(value: String).returns(T::Hash[T.untyped, T.untyped]) }
+      def decode_json(value)
+        json = decode_base64(value)
+        parsed = JSON.parse(json)
+        Kernel.raise Mpp::ParseError, "Invalid base64 JSON header." unless parsed.is_a?(Hash)
+
+        parsed
+      rescue JSON::ParserError
+        Kernel.raise Mpp::ParseError, "Invalid base64 JSON header."
+      end
+
+      sig { params(value: String).returns(String) }
+      def decode_base64(value)
+        Base64.strict_decode64(value)
+      rescue ArgumentError
+        padded = value + ("=" * ((-value.length) % 4))
+        begin
+          Base64.urlsafe_decode64(padded)
+        rescue ArgumentError
+          Kernel.raise Mpp::ParseError, "Invalid base64 JSON header."
+        end
+      end
+      private_class_method :decode_base64
+
+      sig { params(parsed: T::Hash[T.untyped, T.untyped]).void }
+      def validate_payment_required!(parsed)
+        Kernel.raise Mpp::ParseError, "Invalid base64 JSON header." unless parsed["x402Version"] == VERSION
+        accepts = parsed["accepts"]
+        Kernel.raise Mpp::ParseError, "Invalid base64 JSON header." unless accepts.is_a?(Array) && !accepts.empty?
+        Kernel.raise Mpp::ParseError, "Invalid base64 JSON header." unless parsed["resource"].is_a?(Hash)
+
+        accepts.each { |item| validate_payment_requirements!(item) }
+      end
+      private_class_method :validate_payment_required!
+
+      sig { params(parsed: T::Hash[T.untyped, T.untyped]).void }
+      def validate_payment_payload!(parsed)
+        Kernel.raise Mpp::ParseError, "Invalid base64 JSON header." unless parsed["x402Version"] == VERSION
+        validate_payment_requirements!(parsed["accepted"])
+        payload = parsed["payload"]
+        Kernel.raise Mpp::ParseError, "Invalid base64 JSON header." unless payload.is_a?(Hash)
+        Kernel.raise Mpp::ParseError, "EVM charge only supports x402 EIP-3009 authorization payloads" unless payload.key?("authorization")
+      end
+      private_class_method :validate_payment_payload!
+
+      sig { params(parsed: T::Hash[T.untyped, T.untyped]).void }
+      def validate_settle_response!(parsed)
+        Kernel.raise Mpp::ParseError, "Invalid base64 JSON header." unless parsed.key?("success")
+        Kernel.raise Mpp::ParseError, "Invalid base64 JSON header." unless parsed["transaction"].is_a?(String)
+        Kernel.raise Mpp::ParseError, "Invalid base64 JSON header." unless parsed["network"].is_a?(String)
+      end
+      private_class_method :validate_settle_response!
+
+      sig { params(requirements: T.untyped).void }
+      def validate_payment_requirements!(requirements)
+        Kernel.raise Mpp::ParseError, "Invalid base64 JSON header." unless requirements.is_a?(Hash)
+        Kernel.raise Mpp::ParseError, "x402 exact requires scheme \"exact\"" unless requirements["scheme"] == SCHEME_EXACT
+        Kernel.raise Mpp::ParseError, "Invalid base64 JSON header." unless requirements["amount"].is_a?(String) && requirements["amount"].match?(/\A\d+\z/)
+        Kernel.raise Mpp::ParseError, "Invalid base64 JSON header." unless requirements["asset"].is_a?(String) && !requirements["asset"].empty?
+        Kernel.raise Mpp::ParseError, "Invalid EVM CAIP-2 network" unless requirements["network"].is_a?(String) && requirements["network"].start_with?(EVM_NETWORK_PREFIX)
+        Kernel.raise Mpp::ParseError, "Invalid base64 JSON header." unless requirements["payTo"].is_a?(String) && !requirements["payTo"].empty?
+        extra = requirements["extra"]
+        return if extra.nil?
+
+        transfer = extra["assetTransferMethod"]
+        Kernel.raise Mpp::ParseError, "x402 exact permit2 signing is not implemented" if transfer == "permit2"
+      end
+      private_class_method :validate_payment_requirements!
+    end
+  end
+end

data/lib/mpp/x402/server.rb

@@ -0,0 +1,247 @@
+# typed: true
+# frozen_string_literal: true
+
+require_relative "header"
+require "digest"
+require "openssl"
+
+module Mpp
+  module X402
+    # Server-side x402 exact binding, challenge decoration, and header merge.
+    module Server
+      extend T::Sig
+
+      module_function
+
+      sig { params(values: T::Array[String]).returns(String) }
+      def merge_payment_required(values)
+        decoded = values.map { |value| Header.decode_payment_required(value) }
+        first = decoded.first
+        Kernel.raise ArgumentError, "Expected at least one x402 payment-required header." unless first
+
+        rest = decoded.drop(1)
+        incompatible = rest.any? do |value|
+          value["resource"] != first["resource"] || value["extensions"] != first["extensions"]
+        end
+        if incompatible
+          error = [first["error"], "Cannot merge x402 payment requirements with different resources."]
+            .compact
+            .reject { |item| item.to_s.empty? }
+            .join("; ")
+          return Header.encode_payment_required(first.merge("error" => error))
+        end
+
+        errors = [first["error"], *rest.map { |value| value["error"] }]
+          .compact
+          .reject { |item| item.to_s.empty? }
+        merged = first.merge("accepts" => decoded.flat_map { |value| value["accepts"] })
+        merged["error"] = errors.join("; ") unless errors.empty?
+        Header.encode_payment_required(merged)
+      end
+
+      sig do
+        params(
+          request: T::Hash[T.untyped, T.untyped],
+          authorization: T::Hash[T.untyped, T.untyped],
+          max_timeout_seconds: Integer
+        ).returns(T::Hash[String, T.untyped])
+      end
+      def to_payment_requirements(request, authorization:, max_timeout_seconds:)
+        chain_id = request.dig("methodDetails", "chainId")
+        Kernel.raise ArgumentError, "EVM charge request requires methodDetails.chainId" if chain_id.nil?
+
+        {
+          "amount" => request["amount"].to_s,
+          "asset" => request["currency"].to_s,
+          "extra" => {
+            "assetTransferMethod" => ASSET_TRANSFER_EIP3009,
+            "name" => authorization["name"] || authorization[:name],
+            "version" => authorization["version"] || authorization[:version]
+          },
+          "maxTimeoutSeconds" => max_timeout_seconds,
+          "network" => "#{EVM_NETWORK_PREFIX}#{chain_id}",
+          "payTo" => request["recipient"].to_s,
+          "scheme" => SCHEME_EXACT
+        }
+      end
+
+      sig do
+        params(
+          requirements: T::Hash[T.untyped, T.untyped],
+          resource_url: String,
+          extensions: T.nilable(T::Hash[T.untyped, T.untyped]),
+          error: T.nilable(String)
+        ).returns(T::Hash[String, T.untyped])
+      end
+      def payment_required_body(requirements:, resource_url:, extensions: nil, error: nil)
+        body = {
+          "accepts" => [requirements],
+          "resource" => {"url" => resource_url},
+          "x402Version" => VERSION
+        }
+        body["extensions"] = extensions if extensions
+        body["error"] = error if error
+        body
+      end
+
+      sig do
+        params(
+          challenge: Mpp::Challenge,
+          http_method: T.nilable(String)
+        ).returns(T.nilable(T::Hash[String, T.untyped]))
+      end
+      def route_extensions(challenge, http_method)
+        return nil if http_method.nil? || http_method.empty?
+
+        binding = {"method" => http_method}
+        binding["digest"] = challenge.digest if challenge.digest
+        binding["opaque"] = Mpp::Parsing.b64_encode(challenge.opaque) if challenge.opaque
+        {
+          MPPX_EXTENSION_KEY => {
+            "info" => binding,
+            "schema" => MPPX_ROUTE_BINDING_SCHEMA
+          }
+        }
+      end
+
+      sig do
+        params(
+          accepted: T::Hash[T.untyped, T.untyped],
+          resource: T::Hash[T.untyped, T.untyped],
+          extensions: T::Hash[T.untyped, T.untyped]
+        ).returns(String)
+      end
+      def route_nonce(accepted:, resource:, extensions:)
+        input = [
+          serialize_request(accepted),
+          serialize_request(resource),
+          serialize_request(extensions)
+        ].join("|")
+        digest = Digest::SHA256.digest(input)
+        "0x#{digest.unpack1("H*")}"
+      end
+
+      sig { params(value: T.untyped).returns(String) }
+      def serialize_request(value)
+        json = Mpp::Json.compact_encode(value)
+        Mpp.b64url_encode(json)
+      end
+
+      sig do
+        params(
+          payment_payload: T::Hash[T.untyped, T.untyped],
+          requirements: T::Hash[T.untyped, T.untyped],
+          resource_url: T.nilable(String),
+          challenge: Mpp::Challenge,
+          body: T.untyped,
+          route_binding: Symbol,
+          http_method: T.nilable(String)
+        ).returns(T::Hash[T.untyped, T.untyped])
+      end
+      def bind_credential(payment_payload:, requirements:, resource_url:, challenge:, body:, route_binding:, http_method: nil)
+        unless canonical_equal?(payment_payload["accepted"], requirements)
+          Kernel.raise Mpp::VerificationFailedError.new(reason: "x402 payment payload does not match route requirements")
+        end
+
+        assert_body_digest!(challenge, body)
+
+        expected_resource = {"url" => resource_url}
+        client_nonce = payment_payload.dig("extensions", MPPX_EXTENSION_KEY, "info", "nonce")
+        route_bound = !client_nonce.nil?
+        route_requires_binding = !challenge.digest.nil? || !challenge.opaque.nil?
+
+        if route_requires_binding && !route_bound && route_binding == :required
+          Kernel.raise Mpp::VerificationFailedError.new(reason: "x402 payment payload does not bind required route metadata")
+        end
+
+        payload_resource = payment_payload["resource"]
+        if route_bound
+          unless payload_resource.is_a?(Hash) && payload_resource["url"] == expected_resource["url"]
+            Kernel.raise Mpp::VerificationFailedError.new(reason: "x402 payment payload resource does not match route resource")
+          end
+          expected_extensions = route_extensions(challenge, http_method) || {}
+          unless contains_extensions?(payment_payload["extensions"], expected_extensions)
+            Kernel.raise Mpp::VerificationFailedError.new(reason: "x402 payment payload extensions do not match route binding")
+          end
+        elsif resource_url
+          if payload_resource.is_a?(Hash) && payload_resource["url"] != resource_url
+            Kernel.raise Mpp::VerificationFailedError.new(reason: "x402 payment payload resource does not match route resource")
+          end
+          if route_requires_binding && (payload_resource.nil? || payload_resource["url"] != resource_url)
+            Kernel.raise Mpp::VerificationFailedError.new(reason: "x402 payment payload resource does not match route resource")
+          end
+        end
+
+        authorization = payload_to_authorization(payment_payload)
+        if route_bound
+          expected_nonce = route_nonce(
+            accepted: requirements,
+            extensions: payment_payload["extensions"],
+            resource: expected_resource
+          )
+          unless authorization["nonce"].to_s.downcase == expected_nonce.downcase
+            Kernel.raise Mpp::VerificationFailedError.new(reason: "x402 authorization nonce does not match route binding")
+          end
+        end
+
+        authorization
+      end
+
+      sig { params(payment_payload: T::Hash[T.untyped, T.untyped]).returns(T::Hash[String, T.untyped]) }
+      def payload_to_authorization(payment_payload)
+        payload = payment_payload["payload"]
+        unless payload.is_a?(Hash) && payload["authorization"].is_a?(Hash)
+          Kernel.raise Mpp::VerificationFailedError.new(reason: "EVM charge only supports x402 EIP-3009 authorization payloads")
+        end
+
+        authorization = payload["authorization"]
+        {
+          "from" => authorization["from"].to_s,
+          "nonce" => authorization["nonce"].to_s,
+          "signature" => payload["signature"].to_s,
+          "to" => authorization["to"].to_s,
+          "type" => "authorization",
+          "validAfter" => authorization["validAfter"].to_s,
+          "validBefore" => authorization["validBefore"].to_s,
+          "value" => authorization["value"].to_s
+        }
+      end
+
+      sig { params(left: T.untyped, right: T.untyped).returns(T::Boolean) }
+      def canonical_equal?(left, right)
+        Mpp::Json.compact_encode(left) == Mpp::Json.compact_encode(right)
+      end
+
+      sig { params(challenge: Mpp::Challenge, body: T.untyped).void }
+      def assert_body_digest!(challenge, body)
+        return if body.nil? || challenge.digest.nil?
+        return if Mpp::BodyDigest.verify(T.must(challenge.digest), body)
+
+        Kernel.raise Mpp::VerificationFailedError.new(reason: "x402 payment body digest mismatch")
+      end
+      private_class_method :assert_body_digest!
+
+      sig { params(actual: T.untyped, expected: T::Hash[T.untyped, T.untyped]).returns(T::Boolean) }
+      def contains_extensions?(actual, expected)
+        return false unless actual.is_a?(Hash)
+
+        expected.all? do |key, expected_extension|
+          actual_extension = actual[key]
+          next false unless actual_extension.is_a?(Hash)
+
+          canonical_equal?(actual_extension["schema"], expected_extension["schema"]) &&
+            canonical_equal?(strip_client_nonce(actual_extension["info"]), expected_extension["info"])
+        end
+      end
+      private_class_method :contains_extensions?
+
+      sig { params(info: T.untyped).returns(T.untyped) }
+      def strip_client_nonce(info)
+        return info unless info.is_a?(Hash)
+
+        info.except("nonce")
+      end
+      private_class_method :strip_client_nonce
+    end
+  end
+end

data/lib/mpp/x402/types.rb

@@ -0,0 +1,33 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Mpp
+  module X402
+    VERSION = 2
+    PAYMENT_METHOD = "evm"
+    EXACT_INTENT = "charge"
+    SCHEME_EXACT = "exact"
+    ASSET_TRANSFER_EIP3009 = "eip3009"
+    EVM_NETWORK_PREFIX = "eip155:"
+    SYNTHETIC_CHALLENGE_ID_PREFIX = "x402:"
+
+    PAYMENT_REQUIRED_HEADER = "PAYMENT-REQUIRED"
+    PAYMENT_SIGNATURE_HEADER = "PAYMENT-SIGNATURE"
+    PAYMENT_RESPONSE_HEADER = "PAYMENT-RESPONSE"
+
+    MPPX_EXTENSION_KEY = "mppx"
+
+    MPPX_ROUTE_BINDING_SCHEMA = T.let({
+      "additionalProperties" => false,
+      "properties" => {
+        "_mppx_scope" => {"type" => "string"},
+        "digest" => {"type" => "string"},
+        "method" => {"type" => "string"},
+        "nonce" => {"type" => "string"},
+        "opaque" => {"type" => "string"}
+      },
+      "required" => ["method"],
+      "type" => "object"
+    }.freeze, T::Hash[String, T.untyped])
+  end
+end

data/lib/mpp/x402.rb

@@ -0,0 +1,12 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Mpp
+  module X402
+    autoload :Header, "mpp/x402/header"
+    autoload :Facilitator, "mpp/x402/facilitator"
+    autoload :Server, "mpp/x402/server"
+  end
+end
+
+require_relative "x402/types"

data/lib/mpp.rb

@@ -22,6 +22,8 @@ module Mpp
   autoload :Events, "mpp/events"
   autoload :Units, "mpp/units"
   autoload :MemoryStore, "mpp/store"
+  autoload :Http, "mpp/http"
+  autoload :X402, "mpp/x402"
 
   # Server module (autoloaded)
   autoload :Server, "mpp/server"
@@ -33,6 +35,7 @@ module Mpp
   module Methods
     autoload :Tempo, "mpp/methods/tempo"
     autoload :Stripe, "mpp/methods/stripe"
+    autoload :Evm, "mpp/methods/evm"
   end
 
   # Extensions namespace
@@ -40,9 +43,9 @@ module Mpp
     autoload :MCP, "mpp/extensions/mcp"
   end
 
-  sig { params(method: T.untyped, realm: T.untyped, secret_key: T.untyped, events: T.nilable(Mpp::Events::Dispatcher)).returns(T.untyped) }
-  def self.create(method:, realm: nil, secret_key: nil, events: nil)
-    Server::MppHandler.create(method: method, realm: realm, secret_key: secret_key, events: events)
+  sig { params(method: T.untyped, methods: T.nilable(T::Array[T.untyped]), realm: T.untyped, secret_key: T.untyped, events: T.nilable(Mpp::Events::Dispatcher)).returns(T.untyped) }
+  def self.create(method: nil, methods: nil, realm: nil, secret_key: nil, events: nil)
+    Server::MppHandler.create(method: method, methods: methods, realm: realm, secret_key: secret_key, events: events)
   end
 
   # Error hierarchy

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mpp-rb
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.5
 platform: ruby
 authors:
 - Stripe
@@ -23,6 +23,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: keccak
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
 description: Ruby SDK for the Machine Payments Protocol (MPP) — an HTTP 402 Payment
   Authentication scheme.
 executables: []
@@ -50,7 +64,14 @@ files:
 - lib/mpp/extensions/mcp/errors.rb
 - lib/mpp/extensions/mcp/types.rb
 - lib/mpp/extensions/mcp/verify.rb
+- lib/mpp/http.rb
+- lib/mpp/http/headers.rb
 - lib/mpp/json.rb
+- lib/mpp/methods/evm.rb
+- lib/mpp/methods/evm/assets.rb
+- lib/mpp/methods/evm/authorization.rb
+- lib/mpp/methods/evm/charge_intent.rb
+- lib/mpp/methods/evm/evm_method.rb
 - lib/mpp/methods/stripe.rb
 - lib/mpp/methods/stripe/charge_intent.rb
 - lib/mpp/methods/stripe/client_method.rb
@@ -61,11 +82,13 @@ files:
 - lib/mpp/methods/tempo/attribution.rb
 - lib/mpp/methods/tempo/client_method.rb
 - lib/mpp/methods/tempo/defaults.rb
+- lib/mpp/methods/tempo/fee_payer_client.rb
 - lib/mpp/methods/tempo/fee_payer_envelope.rb
 - lib/mpp/methods/tempo/fee_payer_policy.rb
 - lib/mpp/methods/tempo/intents.rb
 - lib/mpp/methods/tempo/keychain.rb
 - lib/mpp/methods/tempo/proof.rb
+- lib/mpp/methods/tempo/relay.rb
 - lib/mpp/methods/tempo/rpc.rb
 - lib/mpp/methods/tempo/schemas.rb
 - lib/mpp/methods/tempo/transaction.rb
@@ -73,16 +96,24 @@ files:
 - lib/mpp/receipt.rb
 - lib/mpp/secure_compare.rb
 - lib/mpp/server.rb
+- lib/mpp/server/accept_payment.rb
+- lib/mpp/server/compose.rb
 - lib/mpp/server/decorator.rb
 - lib/mpp/server/defaults.rb
 - lib/mpp/server/intent.rb
 - lib/mpp/server/method.rb
 - lib/mpp/server/middleware.rb
 - lib/mpp/server/mpp_handler.rb
+- lib/mpp/server/result.rb
 - lib/mpp/server/verify.rb
 - lib/mpp/store.rb
 - lib/mpp/units.rb
 - lib/mpp/version.rb
+- lib/mpp/x402.rb
+- lib/mpp/x402/facilitator.rb
+- lib/mpp/x402/header.rb
+- lib/mpp/x402/server.rb
+- lib/mpp/x402/types.rb
 homepage: https://github.com/stripe/mpp-rb
 licenses:
 - MIT