mpp-rb 0.1.4 → 0.1.6

data/lib/mpp/server/result.rb

@@ -0,0 +1,100 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Mpp
+  module Server
+    # Result of a composed (or multi-method) payment verification.
+    #
+    # Either a 402 with one or more Challenges, or a verified payment.
+    class ComposedResult
+      extend T::Sig
+
+      sig { returns(Integer) }
+      attr_reader :status
+
+      sig { returns(T::Array[Mpp::Challenge]) }
+      attr_reader :challenges
+
+      sig { returns(T.untyped) }
+      attr_reader :credential
+
+      sig { returns(T.nilable(Mpp::Receipt)) }
+      attr_reader :receipt
+
+      sig { returns(T::Hash[String, T.untyped]) }
+      attr_reader :extra_headers
+
+      sig { returns(String) }
+      attr_reader :realm
+
+      sig do
+        params(
+          status: Integer,
+          realm: String,
+          challenges: T::Array[Mpp::Challenge],
+          credential: T.untyped,
+          receipt: T.nilable(Mpp::Receipt),
+          extra_headers: T::Hash[String, T.untyped]
+        ).void
+      end
+      def initialize(status:, realm:, challenges: [], credential: nil, receipt: nil, extra_headers: {})
+        @status = T.let(status, Integer)
+        @realm = T.let(realm, String)
+        @challenges = T.let(challenges, T::Array[Mpp::Challenge])
+        @credential = T.let(credential, T.untyped)
+        @receipt = T.let(receipt, T.nilable(Mpp::Receipt))
+        @extra_headers = T.let(extra_headers, T::Hash[String, T.untyped])
+      end
+
+      sig do
+        params(
+          challenges: T::Array[Mpp::Challenge],
+          realm: String,
+          extra_headers: T::Hash[String, T.untyped]
+        ).returns(ComposedResult)
+      end
+      def self.payment_required(challenges, realm:, extra_headers: {})
+        new(status: 402, realm: realm, challenges: challenges, extra_headers: extra_headers)
+      end
+
+      sig do
+        params(
+          credential: T.untyped,
+          receipt: Mpp::Receipt,
+          realm: String,
+          extra_headers: T::Hash[String, T.untyped]
+        ).returns(ComposedResult)
+      end
+      def self.paid(credential, receipt, realm:, extra_headers: {})
+        new(status: 200, realm: realm, credential: credential, receipt: receipt, extra_headers: extra_headers)
+      end
+
+      sig { returns(T::Boolean) }
+      def payment_required?
+        @status == 402
+      end
+
+      # Returns [credential, receipt] for a successful payment.
+      sig { returns(T::Array[T.untyped]) }
+      def payment
+        Kernel.raise ArgumentError, "payment is not available for a 402 response" if payment_required?
+
+        [@credential, @receipt]
+      end
+
+      sig { returns(T.nilable(String)) }
+      def payment_response
+        value = @extra_headers["PAYMENT-RESPONSE"]
+        value.is_a?(String) ? value : nil
+      end
+
+      # Render a 402 challenge response hash, including extra x402 headers.
+      sig { returns(T::Hash[T.untyped, T.untyped]) }
+      def to_response
+        Kernel.raise ArgumentError, "to_response is only valid for 402 results" unless payment_required?
+
+        Decorator.make_challenge_response(@challenges, @realm, extra_headers: @extra_headers)
+      end
+    end
+  end
+end

data/lib/mpp/server/verify.rb

@@ -15,17 +15,17 @@ module Mpp
       # Verify a payment credential or generate a new challenge.
       #
       # Returns Challenge (payment required) or [Credential, Receipt] (verified).
-      sig { params(authorization: T.nilable(String), intent: T.untyped, request: T::Hash[String, T.untyped], realm: String, secret_key: String, method: T.nilable(String), description: T.nilable(String), meta: T.nilable(T::Hash[String, T.untyped]), expires: T.nilable(String), events: T.nilable(Mpp::Events::Dispatcher), body: T.untyped).returns(T.untyped) }
+      sig { params(authorization: T.nilable(String), intent: T.untyped, request: T::Hash[String, T.untyped], realm: String, secret_key: String, method: T.nilable(String), description: T.nilable(String), meta: T.nilable(T::Hash[String, T.untyped]), expires: T.nilable(String), events: T.nilable(Mpp::Events::Dispatcher), method_hook_events: T.nilable(Mpp::Events::Dispatcher), body: T.untyped, header: T.nilable(String)).returns(T.untyped) }
       def verify_or_challenge(authorization:, intent:, request:, realm:, secret_key:,
-        method: nil, description: nil, meta: nil, expires: nil, events: nil, body: nil)
+        method: nil, description: nil, meta: nil, expires: nil, events: nil, method_hook_events: nil, body: nil, header: nil)
         method_name = method || "tempo"
         request = Mpp::Units.transform_units(request)
         dispatcher = events
-        events_enabled = dispatcher&.has_handlers?
+        events_enabled = dispatcher&.has_handlers? || method_hook_events&.has_handlers?
         method_context = events_enabled ? {name: method_name, intent: intent.name} : nil
 
         new_challenge = Kernel.lambda { |credential = nil, error = nil, submitted_challenge = nil|
-          challenge = create_challenge(method_name, intent.name, request, realm, secret_key, description, meta, expires, body)
+          challenge = create_challenge(method_name, intent.name, request, realm, secret_key, description, meta, expires, body, header)
           if error && dispatcher&.has_handlers?(Mpp::Events::PAYMENT_FAILED)
             emit_payment_failed(
               dispatcher: dispatcher,
@@ -79,7 +79,8 @@ module Mpp
           request: echo_request,
           expires: echo.expires,
           digest: echo.digest,
-          opaque: echo_opaque
+          opaque: echo_opaque,
+          header: echo.header
         )
         unless Mpp.secure_compare(echo.id, expected_id)
           return new_challenge.call(
@@ -172,9 +173,10 @@ module Mpp
           end
           Kernel.raise
         end
-        if dispatcher&.has_handlers?(Mpp::Events::PAYMENT_SUCCESS)
+        if dispatcher&.has_handlers?(Mpp::Events::PAYMENT_SUCCESS) || method_hook_events&.has_handlers?(Mpp::Events::PAYMENT_SUCCESS)
           emit_payment_success(
             dispatcher: dispatcher,
+            method_hook_dispatcher: method_hook_events,
             challenge: echo,
             credential: credential,
             method: T.must(method_context),
@@ -185,9 +187,9 @@ module Mpp
         [credential, receipt]
       end
 
-      sig { params(method: String, intent_name: String, request: T::Hash[String, T.untyped], realm: String, secret_key: String, description: T.nilable(String), meta: T.nilable(T::Hash[String, T.untyped]), expires: T.nilable(String), body: T.untyped).returns(Mpp::Challenge) }
+      sig { params(method: String, intent_name: String, request: T::Hash[String, T.untyped], realm: String, secret_key: String, description: T.nilable(String), meta: T.nilable(T::Hash[String, T.untyped]), expires: T.nilable(String), body: T.untyped, header: T.nilable(String)).returns(Mpp::Challenge) }
       def create_challenge(method, intent_name, request, realm, secret_key,
-        description = nil, meta = nil, expires = nil, body = nil)
+        description = nil, meta = nil, expires = nil, body = nil, header = nil)
         expires = nil if expires && !expires.is_a?(String)
 
         if expires.nil?
@@ -205,7 +207,8 @@ module Mpp
           expires: expires,
           digest: digest,
           description: description,
-          meta: meta
+          meta: meta,
+          header: header
         )
       end
 
@@ -258,17 +261,24 @@ module Mpp
         dispatcher.emit(Mpp::Events::PAYMENT_FAILED, payload)
       end
 
-      sig { params(dispatcher: Mpp::Events::Dispatcher, challenge: T.untyped, credential: T.untyped, method: T::Hash[Symbol, T.untyped], receipt: T.untyped, request: T::Hash[String, T.untyped]).void }
-      def emit_payment_success(dispatcher:, challenge:, credential:, method:, receipt:, request:)
-        return unless dispatcher.has_handlers?(Mpp::Events::PAYMENT_SUCCESS)
+      # Method hooks are owned by a handler, while `dispatcher` may be shared
+      # by many handlers. Emit the same payload to each without exposing that
+      # handler ownership in the public event payload.
+      sig { params(dispatcher: T.nilable(Mpp::Events::Dispatcher), challenge: T.untyped, credential: T.untyped, method: T::Hash[Symbol, T.untyped], receipt: T.untyped, request: T::Hash[String, T.untyped], method_hook_dispatcher: T.nilable(Mpp::Events::Dispatcher)).void }
+      def emit_payment_success(dispatcher:, challenge:, credential:, method:, receipt:, request:, method_hook_dispatcher: nil)
+        public_handlers = dispatcher&.has_handlers?(Mpp::Events::PAYMENT_SUCCESS)
+        hook_handlers = method_hook_dispatcher&.has_handlers?(Mpp::Events::PAYMENT_SUCCESS)
+        return unless public_handlers || hook_handlers
 
-        dispatcher.emit(Mpp::Events::PAYMENT_SUCCESS, {
+        payload = {
           challenge: challenge,
           credential: credential,
           method: method,
           receipt: receipt,
           request: request
-        })
+        }
+        dispatcher.emit(Mpp::Events::PAYMENT_SUCCESS, payload) if public_handlers
+        method_hook_dispatcher.emit(Mpp::Events::PAYMENT_SUCCESS, payload) if hook_handlers && method_hook_dispatcher != dispatcher
       end
     end
   end

data/lib/mpp/server.rb

@@ -11,5 +11,9 @@ module Mpp
     autoload :MppHandler, "mpp/server/mpp_handler"
     autoload :Decorator, "mpp/server/decorator"
     autoload :Middleware, "mpp/server/middleware"
+    autoload :AcceptPayment, "mpp/server/accept_payment"
+    autoload :ComposedResult, "mpp/server/result"
+    autoload :ComposedHandler, "mpp/server/compose"
+    autoload :ComposeOffer, "mpp/server/compose"
   end
 end

data/lib/mpp/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module Mpp
-  VERSION = "0.1.4"
+  VERSION = "0.1.6"
 end

data/lib/mpp/x402/facilitator.rb

@@ -0,0 +1,127 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "types"
+require_relative "../http/headers"
+require "json"
+require "net/http"
+require "uri"
+
+module Mpp
+  module X402
+    # HTTP client for an x402 facilitator `/verify` and `/settle` API.
+    #
+    # `resolve` accepts:
+    #   * a URL string (public / unauthenticated facilitator)
+    #   * a config hash (`url:` plus optional `headers:` as a Hash or per-request proc)
+    #   * any object that responds to `#verify` and `#settle` (e.g. a CDP HTTPFacilitatorClient)
+    class Facilitator
+      extend T::Sig
+
+      sig { returns(String) }
+      attr_reader :base_url
+
+      sig {
+        params(
+          url: String,
+          headers: T.untyped
+        ).void
+      }
+      def initialize(url, headers: nil)
+        @base_url = T.let(Mpp::Http::Headers.normalize_base_url(url), String)
+        Kernel.raise ArgumentError, "x402 exact requires `facilitator`." if @base_url.empty?
+
+        @headers = T.let(headers, T.untyped)
+      end
+
+      sig { params(facilitator: T.untyped).returns(T.untyped) }
+      def self.resolve(facilitator)
+        return facilitator if facilitator.is_a?(Facilitator)
+        return new(facilitator) if facilitator.is_a?(String) && !facilitator.empty?
+        return from_config(facilitator) if facilitator.is_a?(Hash)
+        return facilitator if duck_type?(facilitator)
+
+        Kernel.raise ArgumentError, "x402 exact requires `facilitator`."
+      end
+
+      sig { params(config: T::Hash[T.untyped, T.untyped]).returns(Facilitator) }
+      def self.from_config(config)
+        cfg = Mpp::Http::Headers.symbolize(config)
+        url = cfg[:url] || cfg[:base_url] || cfg[:baseUrl]
+
+        new(url.to_s, headers: cfg[:headers])
+      end
+
+      sig { params(facilitator: T.untyped).returns(T::Boolean) }
+      def self.duck_type?(facilitator)
+        !facilitator.nil? && facilitator.respond_to?(:verify) && facilitator.respond_to?(:settle)
+      end
+
+      sig do
+        params(
+          payment_payload: T::Hash[T.untyped, T.untyped],
+          payment_requirements: T::Hash[T.untyped, T.untyped]
+        ).returns(T::Hash[T.untyped, T.untyped])
+      end
+      def verify(payment_payload, payment_requirements)
+        post("/verify", payment_payload, payment_requirements)
+      end
+
+      sig do
+        params(
+          payment_payload: T::Hash[T.untyped, T.untyped],
+          payment_requirements: T::Hash[T.untyped, T.untyped]
+        ).returns(T::Hash[T.untyped, T.untyped])
+      end
+      def settle(payment_payload, payment_requirements)
+        post("/settle", payment_payload, payment_requirements)
+      end
+
+      private
+
+      sig { params(path: String).returns(T::Hash[String, String]) }
+      def request_headers(path)
+        Mpp::Http::Headers.resolve(@headers, path)
+      end
+
+      sig do
+        params(
+          path: String,
+          payment_payload: T::Hash[T.untyped, T.untyped],
+          payment_requirements: T::Hash[T.untyped, T.untyped]
+        ).returns(T::Hash[T.untyped, T.untyped])
+      end
+      def post(path, payment_payload, payment_requirements)
+        uri = URI.parse("#{@base_url}#{path}")
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        request = Net::HTTP::Post.new(uri)
+        request["Content-Type"] = "application/json"
+        request_headers(path).each { |key, value| request[key] = value }
+        request.body = JSON.generate({
+          "paymentPayload" => payment_payload,
+          "paymentRequirements" => payment_requirements,
+          "x402Version" => VERSION
+        })
+        response = http.request(request)
+        unless response.is_a?(Net::HTTPSuccess)
+          Kernel.raise Mpp::VerificationFailedError.new(reason: "facilitator #{path} returned HTTP #{response.code}")
+        end
+
+        body = response.body.to_s
+        if body.empty?
+          Kernel.raise Mpp::VerificationFailedError.new(reason: "facilitator #{path} returned an empty body")
+        end
+
+        parsed = JSON.parse(body)
+        unless parsed.is_a?(Hash)
+          Kernel.raise Mpp::VerificationFailedError.new(reason: "facilitator #{path} returned JSON that is not an object")
+        end
+
+        parsed
+      rescue JSON::ParserError
+        Kernel.raise Mpp::VerificationFailedError.new(reason: "facilitator #{path} returned invalid JSON")
+      end
+    end
+  end
+end

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