mpp-rb 0.1.3 → 0.1.5

data/lib/mpp/server/mpp_handler.rb

@@ -1,4 +1,4 @@
-# typed: strict
+# typed: true
 # frozen_string_literal: true
 
 require_relative "method"
@@ -10,9 +10,14 @@ module Mpp
     class MppHandler
       extend T::Sig
 
+      REQUEST_OPTION_KEYS = [:body, :url, :payment_signature, :accept_payment, :http_method].freeze
+
       sig { returns(T.untyped) }
       attr_reader :method
 
+      sig { returns(T::Array[T.untyped]) }
+      attr_reader :methods
+
       sig { returns(String) }
       attr_reader :realm
 
@@ -22,9 +27,19 @@ module Mpp
       sig { returns(T::Hash[String, T.untyped]) }
       attr_reader :defaults
 
-      sig { params(method: T.untyped, realm: String, secret_key: String, defaults: T.nilable(T::Hash[String, T.untyped]), events: T.nilable(Mpp::Events::Dispatcher)).void }
-      def initialize(method:, realm:, secret_key:, defaults: nil, events: nil)
-        @method = T.let(method, T.untyped)
+      sig do
+        params(
+          realm: String,
+          secret_key: String,
+          method: T.untyped,
+          methods: T.nilable(T::Array[T.untyped]),
+          defaults: T.nilable(T::Hash[String, T.untyped]),
+          events: T.nilable(Mpp::Events::Dispatcher)
+        ).void
+      end
+      def initialize(realm:, secret_key:, method: nil, methods: nil, defaults: nil, events: nil)
+        @methods = T.let(normalize_methods(method, methods), T::Array[T.untyped])
+        @method = T.let(@methods.first, T.untyped)
         @realm = T.let(realm, String)
         @secret_key = T.let(secret_key, String)
         @defaults = T.let(defaults || {}, T::Hash[String, T.untyped])
@@ -32,10 +47,19 @@ module Mpp
       end
 
       # Create with auto-detected realm and secret_key.
-      sig { params(method: T.untyped, realm: T.untyped, secret_key: T.untyped, events: T.nilable(Mpp::Events::Dispatcher)).returns(T.attached_class) }
-      def self.create(method:, realm: nil, secret_key: nil, events: nil)
+      sig do
+        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.attached_class)
+      end
+      def self.create(method: nil, methods: nil, realm: nil, secret_key: nil, events: nil)
         new(
           method: method,
+          methods: methods,
           realm: realm || Defaults.detect_realm,
           secret_key: secret_key || Defaults.detect_secret_key,
           events: events
@@ -62,20 +86,123 @@ module Mpp
         on(Mpp::Events::PAYMENT_SUCCESS, handler, &block)
       end
 
+      # Combine method offers into a single callable that presents every method.
+      sig { params(entries: T.untyped).returns(ComposedHandler) }
+      def compose(*entries)
+        ComposedHandler.from_entries(self, entries)
+      end
+
+      # Look up a registered method by object, name, or "name/intent" key.
+      sig { params(method_ref: T.untyped).returns(T.untyped) }
+      def resolve_method(method_ref)
+        case method_ref
+        when String
+          resolve_method_key(method_ref)
+        else
+          found = @methods.find { |candidate| candidate.equal?(method_ref) } ||
+            @methods.find { |candidate| candidate.name == method_ref.name }
+          return found if found
+
+          raise ArgumentError, "No handler for #{method_ref.inspect}. Is this method in your methods array?"
+        end
+      end
+
       # Handle a charge intent.
-      sig { params(authorization: T.nilable(String), amount: String, currency: T.nilable(String), recipient: T.nilable(String), expires: T.nilable(String), description: T.nilable(String), external_id: T.nilable(String), memo: T.nilable(String), fee_payer: T::Boolean, chain_id: T.nilable(Integer), extra: T.nilable(T::Hash[String, String]), mppx_scope: T.nilable(T::Hash[String, String]), body: T.untyped).returns(T.untyped) }
-      def charge(authorization, amount, currency: nil, recipient: nil, expires: nil,
-        description: nil, external_id: nil, memo: nil, fee_payer: false, chain_id: nil,
-        extra: nil, mppx_scope: nil, body: nil)
-        intent = @method.intents["charge"]
-        raise ArgumentError, "Method #{@method.name} does not support charge intent" unless intent
-
-        resolved_currency = currency || (@method.respond_to?(:currency) ? @method.currency : nil)
-        resolved_recipient = recipient || (@method.respond_to?(:recipient) ? @method.recipient : nil)
+      #
+      # With a single registered charge method this returns Challenge or
+      # [Credential, Receipt]. With multiple charge methods it implicitly
+      # composes them and returns a ComposedResult.
+      sig { params(authorization: T.nilable(String), amount: String, kwargs: T.untyped).returns(T.untyped) }
+      def charge(authorization, amount, **kwargs)
+        charge_methods = @methods.select { |candidate| candidate.intents.key?("charge") }
+        raise ArgumentError, "No registered method supports charge intent" if charge_methods.empty?
+
+        request_opts = kwargs.slice(*REQUEST_OPTION_KEYS)
+        offer_opts = kwargs.except(*REQUEST_OPTION_KEYS)
+
+        if charge_methods.length == 1
+          return charge_one(
+            charge_methods.first,
+            authorization,
+            amount,
+            **request_opts,
+            **offer_opts
+          )
+        end
+
+        entries = charge_methods.map { |candidate| [candidate, offer_opts.merge(amount: amount)] }
+        ComposedHandler.from_entries(self, entries).call(
+          authorization: authorization,
+          payment_signature: request_opts[:payment_signature],
+          body: request_opts[:body],
+          url: request_opts[:url],
+          accept_payment: request_opts[:accept_payment],
+          http_method: request_opts[:http_method]
+        )
+      end
+
+      # Verify or challenge a single method. Used by compose and charge.
+      sig { params(method: T.untyped, authorization: T.nilable(String), amount: String, kwargs: T.untyped).returns(T.untyped) }
+      def charge_one(method, authorization, amount, **kwargs)
+        intent = method.intents["charge"]
+        raise ArgumentError, "Method #{method.name} does not support charge intent" unless intent
+
+        body = kwargs[:body]
+        url = kwargs[:url]
+        payment_signature = kwargs[:payment_signature]
+        offer_opts = kwargs.except(*REQUEST_OPTION_KEYS)
+        request = build_charge_request(method, amount, **offer_opts)
+
+        if payment_signature && method.respond_to?(:bind_x402_credential)
+          return verify_x402(
+            method,
+            intent,
+            request,
+            payment_signature: payment_signature,
+            url: url,
+            body: body,
+            description: offer_opts[:description],
+            expires: offer_opts[:expires],
+            http_method: kwargs[:http_method]
+          )
+        end
+
+        Verify.verify_or_challenge(
+          authorization: authorization,
+          intent: intent,
+          request: request,
+          realm: @realm,
+          secret_key: @secret_key,
+          method: method.name,
+          description: offer_opts[:description],
+          expires: offer_opts[:expires],
+          events: @events,
+          body: body
+        )
+      end
+
+      # Build the canonical charge request for a method without verifying.
+      sig { params(method: T.untyped, amount: String, kwargs: T.untyped).returns(T::Hash[String, T.untyped]) }
+      def build_charge_request(method, amount, **kwargs)
+        currency = kwargs[:currency]
+        recipient = kwargs[:recipient]
+        external_id = kwargs[:external_id]
+        memo = kwargs[:memo]
+        fee_payer = if kwargs.key?(:fee_payer)
+          kwargs[:fee_payer]
+        else
+          method.respond_to?(:fee_payer) && method.fee_payer
+        end
+        chain_id = kwargs[:chain_id]
+        extra = kwargs[:extra]
+        mppx_scope = kwargs[:mppx_scope]
+
+        resolved_currency = currency || (method.respond_to?(:currency) ? method.currency : nil)
+        resolved_recipient = recipient || (method.respond_to?(:recipient) ? method.recipient : nil)
         raise ArgumentError, "currency must be set on the method or passed to charge()" unless resolved_currency
         raise ArgumentError, "recipient must be set on the method or passed to charge()" unless resolved_recipient
 
-        decimals = @method.respond_to?(:decimals) ? @method.decimals : DEFAULT_DECIMALS
+        decimals = method.respond_to?(:decimals) ? method.decimals : DEFAULT_DECIMALS
         base_amount = Mpp::Units.parse_units(amount, decimals).to_s
 
         request = {
@@ -86,20 +213,20 @@ module Mpp
         request["externalId"] = external_id unless external_id.nil?
 
         if extra
-          extra.each do |k, v|
-            raise ArgumentError, "extra must be a dict[str, str]" unless k.is_a?(String) && v.is_a?(String)
+          extra.each do |key, value|
+            raise ArgumentError, "extra must be a dict[str, str]" unless key.is_a?(String) && value.is_a?(String)
           end
           request["extra"] = extra
         end
         if mppx_scope
-          mppx_scope.each do |k, v|
-            raise ArgumentError, "mppx_scope must be a dict[str, str]" unless k.is_a?(String) && v.is_a?(String)
+          mppx_scope.each do |key, value|
+            raise ArgumentError, "mppx_scope must be a dict[str, str]" unless key.is_a?(String) && value.is_a?(String)
           end
           request["_mppx_scope"] = mppx_scope
         end
 
         resolved_chain_id = chain_id
-        resolved_chain_id ||= @method.chain_id if @method.respond_to?(:chain_id)
+        resolved_chain_id ||= method.chain_id if method.respond_to?(:chain_id)
 
         if memo || fee_payer || !resolved_chain_id.nil?
           method_details = {}
@@ -109,20 +236,127 @@ module Mpp
           request["methodDetails"] = method_details
         end
 
-        request = Mpp::Server::MethodHelper.transform_request(@method, request, nil)
+        Mpp::Server::MethodHelper.transform_request(method, request, nil)
+      end
 
-        Verify.verify_or_challenge(
-          authorization: authorization,
-          intent: intent,
-          request: request,
-          realm: @realm,
-          secret_key: @secret_key,
-          method: @method.name,
-          description: description,
-          expires: expires,
-          events: @events,
-          body: body
+      # Render a 402 response, applying method-specific extra headers (x402).
+      sig { params(challenge: T.untyped, url: T.nilable(String), http_method: T.nilable(String)).returns(T::Hash[T.untyped, T.untyped]) }
+      def challenge_response(challenge, url: nil, http_method: nil)
+        challenges = challenge.is_a?(Array) ? challenge : [challenge]
+        extra = {}
+        if @methods.length == 1 && @method.respond_to?(:decorate_challenge)
+          @method.decorate_challenge(extra, challenges.first, url: url, http_method: http_method)
+        end
+        Decorator.make_challenge_response(challenges, @realm, extra_headers: extra)
+      end
+
+      private
+
+      sig { params(method: T.untyped, methods: T.untyped).returns(T::Array[T.untyped]) }
+      def normalize_methods(method, methods)
+        if !method.nil? && !methods.nil?
+          raise ArgumentError, "pass method: or methods:, not both"
+        end
+
+        list = methods || (method.nil? ? nil : [method])
+        raise ArgumentError, "method: or methods: is required" if list.nil? || list.empty?
+
+        names = list.map(&:name)
+        duplicates = names.tally.select { |_name, count| count > 1 }.keys
+        raise ArgumentError, "duplicate payment method names: #{duplicates.join(", ")}" unless duplicates.empty?
+
+        list
+      end
+
+      sig { params(key: String).returns(T.untyped) }
+      def resolve_method_key(key)
+        name, intent = key.split("/", 2)
+        found = if intent
+          @methods.find { |candidate| candidate.name == name && candidate.intents.key?(intent) }
+        else
+          @methods.find { |candidate| candidate.name == name }
+        end
+        return found if found
+
+        raise ArgumentError, "No handler for #{key.inspect}. Is this method in your methods array?"
+      end
+
+      sig do
+        params(
+          method: T.untyped,
+          intent: T.untyped,
+          request: T::Hash[String, T.untyped],
+          payment_signature: String,
+          url: T.nilable(String),
+          body: T.untyped,
+          description: T.nilable(String),
+          expires: T.nilable(String),
+          http_method: T.nilable(String)
+        ).returns(T.untyped)
+      end
+      def verify_x402(method, intent, request, payment_signature:, url:, body:, description:, expires:, http_method: nil)
+        challenge = Verify.create_challenge(
+          method.name,
+          intent.name,
+          Mpp::Units.transform_units(request),
+          @realm,
+          @secret_key,
+          description,
+          nil,
+          expires,
+          body
         )
+        method_context = {name: method.name, intent: intent.name}
+
+        begin
+          credential = method.bind_x402_credential(
+            payment_signature,
+            challenge: challenge,
+            request: challenge.request,
+            url: url,
+            body: body,
+            http_method: http_method
+          )
+          receipt = intent.verify(credential, challenge.request)
+        rescue => error
+          if @events.has_handlers?(Mpp::Events::PAYMENT_FAILED)
+            Verify.emit_payment_failed(
+              dispatcher: @events,
+              challenge: challenge,
+              credential: nil,
+              error: error,
+              method: method_context,
+              request: challenge.request,
+              retry_challenge: challenge
+            )
+          end
+          if error.is_a?(Mpp::ParseError) || error.is_a?(Mpp::VerificationError) || error.is_a?(Mpp::PaymentError)
+            if @events.has_handlers?(Mpp::Events::CHALLENGE_CREATED)
+              Verify.emit_challenge_created(
+                dispatcher: @events,
+                challenge: challenge,
+                credential: nil,
+                error: error,
+                method: method_context,
+                request: challenge.request
+              )
+            end
+            return challenge
+          end
+          raise
+        end
+
+        if @events.has_handlers?(Mpp::Events::PAYMENT_SUCCESS)
+          Verify.emit_payment_success(
+            dispatcher: @events,
+            challenge: challenge,
+            credential: credential,
+            method: method_context,
+            receipt: receipt,
+            request: challenge.request
+          )
+        end
+        [credential, receipt]
       end
     end
   end

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.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.3"
+  VERSION = "0.1.5"
 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