mpp-rb 0.1.4 → 0.1.5

data/lib/mpp/server/compose.rb

@@ -0,0 +1,387 @@
+# typed: true
+# frozen_string_literal: true
+
+require_relative "result"
+require_relative "accept_payment"
+
+module Mpp
+  module Server
+    extend T::Sig
+
+    # A configured payment offer: a method plus per-request charge options.
+    class ComposeOffer
+      extend T::Sig
+
+      sig { returns(T.untyped) }
+      attr_reader :method
+
+      sig { returns(T::Hash[Symbol, T.untyped]) }
+      attr_reader :options
+
+      sig { params(handler: T.untyped, method: T.untyped, options: T::Hash[T.untyped, T.untyped]).void }
+      def initialize(handler, method, options)
+        @handler = T.let(handler, T.untyped)
+        @method = T.let(method, T.untyped)
+        @options = T.let(symbolize(options), T::Hash[Symbol, T.untyped])
+        amount = @options[:amount]
+        Kernel.raise ArgumentError, "compose entry requires amount:" if amount.nil? || amount.to_s.empty?
+      end
+
+      sig { returns(String) }
+      def intent_name
+        "charge"
+      end
+
+      sig { returns(String) }
+      def key
+        "#{@method.name}/#{intent_name}"
+      end
+
+      sig { returns(T::Hash[String, T.untyped]) }
+      def canonical_request
+        @canonical_request ||= @handler.build_charge_request(@method, amount, **charge_kwargs)
+      end
+
+      sig { params(authorization: T.nilable(String), payment_signature: T.nilable(String), body: T.untyped, url: T.nilable(String), http_method: T.nilable(String)).returns(T.untyped) }
+      def verify(authorization: nil, payment_signature: nil, body: nil, url: nil, http_method: nil)
+        @handler.charge_one(
+          @method,
+          authorization,
+          amount,
+          payment_signature: payment_signature,
+          url: url,
+          body: body,
+          http_method: http_method,
+          **charge_kwargs
+        )
+      end
+
+      sig { params(body: T.untyped, url: T.nilable(String), http_method: T.nilable(String)).returns(Mpp::Challenge) }
+      def challenge(body: nil, url: nil, http_method: nil)
+        result = verify(body: body, url: url, http_method: http_method)
+        return result if result.is_a?(Mpp::Challenge)
+
+        Kernel.raise "expected a challenge from unpaid offer #{key}"
+      end
+
+      sig { params(headers: T::Hash[String, T.untyped], challenge: Mpp::Challenge, url: T.nilable(String), http_method: T.nilable(String)).returns(T::Hash[String, T.untyped]) }
+      def decorate_challenge(headers, challenge, url: nil, http_method: nil)
+        return headers unless @method.respond_to?(:decorate_challenge)
+
+        @method.decorate_challenge(headers, challenge, url: url, http_method: http_method, request: canonical_request)
+        headers
+      end
+
+      sig { params(headers: T::Hash[String, T.untyped], credential: T.untyped, receipt: Mpp::Receipt, payment_signature: T.nilable(String)).returns(T::Hash[String, T.untyped]) }
+      def decorate_receipt(headers, credential, receipt, payment_signature: nil)
+        return headers unless payment_signature && @method.respond_to?(:decorate_receipt)
+
+        @method.decorate_receipt(headers, receipt, credential, payment_signature: payment_signature)
+        headers
+      end
+
+      sig { params(payload: T::Hash[T.untyped, T.untyped]).returns(T::Boolean) }
+      def x402_matches?(payload)
+        return false unless @method.respond_to?(:x402_matches?)
+
+        @method.x402_matches?(payload, canonical_request)
+      end
+
+      # Return a per-request offer bound to the Rack request scope.
+      sig { params(scope: T::Hash[String, String]).returns(ComposeOffer) }
+      def with_scope(scope)
+        ComposeOffer.new(@handler, @method, @options.merge(mppx_scope: @options[:mppx_scope] || scope.dup))
+      end
+
+      private
+
+      sig { returns(String) }
+      def amount
+        @options[:amount].to_s
+      end
+
+      REQUEST_OPTION_KEYS = [:body, :url, :payment_signature, :accept_payment, :authorization, :http_method].freeze
+
+      sig { returns(T::Hash[Symbol, T.untyped]) }
+      def charge_kwargs
+        @options.except(:amount, *REQUEST_OPTION_KEYS)
+      end
+
+      sig { params(options: T::Hash[T.untyped, T.untyped]).returns(T::Hash[Symbol, T.untyped]) }
+      def symbolize(options)
+        options.each_with_object({}) do |(key, value), acc|
+          acc[key.to_sym] = value
+        end
+      end
+    end
+
+    # Combines multiple method offers into a single callable that presents
+    # every method via multiple WWW-Authenticate headers (and x402 extras).
+    class ComposedHandler
+      extend T::Sig
+
+      sig { returns(T.untyped) }
+      attr_reader :handler
+
+      sig { returns(T::Array[ComposeOffer]) }
+      attr_reader :offers
+
+      sig { params(handler: T.untyped, offers: T::Array[ComposeOffer]).void }
+      def initialize(handler:, offers:)
+        Kernel.raise ArgumentError, "compose() requires at least one entry" if offers.empty?
+
+        @handler = T.let(handler, T.untyped)
+        @offers = T.let(offers, T::Array[ComposeOffer])
+      end
+
+      sig { params(handler: T.untyped, entries: T::Array[T.untyped]).returns(ComposedHandler) }
+      def self.from_entries(handler, entries)
+        new(handler: handler, offers: entries.map { |entry| offer_from_entry(handler, entry) })
+      end
+
+      # Flatten nested compositions into a single handler.
+      sig { params(handlers: T::Array[T.untyped]).returns(ComposedHandler) }
+      def self.compose(handlers)
+        Kernel.raise ArgumentError, "compose() requires at least one handler" if handlers.empty?
+
+        offers = handlers.flat_map do |value|
+          if value.is_a?(ComposedHandler)
+            value.offers
+          elsif value.respond_to?(:offers)
+            value.offers
+          else
+            Kernel.raise ArgumentError, "compose() expected a ComposedHandler, got #{value.class}"
+          end
+        end
+        new(handler: handlers.first.handler, offers: offers)
+      end
+
+      sig do
+        params(
+          authorization: T.nilable(String),
+          payment_signature: T.nilable(String),
+          body: T.untyped,
+          url: T.nilable(String),
+          accept_payment: T.nilable(String),
+          http_method: T.nilable(String),
+          scope: T.nilable(T::Hash[String, String])
+        ).returns(ComposedResult)
+      end
+      def call(authorization: nil, payment_signature: nil, body: nil, url: nil, accept_payment: nil, http_method: nil, scope: nil)
+        if scope && !scope.empty?
+          return self.class.new(handler: @handler, offers: @offers.map { |offer| offer.with_scope(scope) }).call(
+            authorization: authorization,
+            payment_signature: payment_signature,
+            body: body,
+            url: url,
+            accept_payment: accept_payment,
+            http_method: http_method
+          )
+        end
+
+        dispatched = dispatch_credential(
+          authorization: authorization,
+          payment_signature: payment_signature,
+          body: body,
+          url: url,
+          http_method: http_method
+        )
+        return dispatched if dispatched
+
+        merge_challenges(body: body, url: url, accept_payment: accept_payment, http_method: http_method)
+      end
+
+      private
+
+      sig { params(handler: T.untyped, entry: T.untyped).returns(ComposeOffer) }
+      def self.offer_from_entry(handler, entry)
+        unless entry.is_a?(Array) && entry.length == 2
+          Kernel.raise ArgumentError, "compose() entries must be [method, options] tuples"
+        end
+
+        method_ref, options = entry
+        options = {} if options.nil?
+        unless options.is_a?(Hash)
+          Kernel.raise ArgumentError, "compose() options must be a Hash"
+        end
+
+        ComposeOffer.new(handler, handler.resolve_method(method_ref), options)
+      end
+      private_class_method :offer_from_entry
+
+      sig do
+        params(
+          authorization: T.nilable(String),
+          payment_signature: T.nilable(String),
+          body: T.untyped,
+          url: T.nilable(String),
+          http_method: T.nilable(String)
+        ).returns(T.nilable(ComposedResult))
+      end
+      def dispatch_credential(authorization:, payment_signature:, body:, url:, http_method: nil)
+        if payment_signature && !payment_signature.strip.empty?
+          result = dispatch_x402(payment_signature, body: body, url: url, http_method: http_method)
+          return result if result
+        end
+
+        return nil if authorization.nil? || authorization.strip.empty?
+
+        dispatch_authorization(authorization, body: body, url: url, http_method: http_method)
+      end
+
+      sig { params(payment_signature: String, body: T.untyped, url: T.nilable(String), http_method: T.nilable(String)).returns(T.nilable(ComposedResult)) }
+      def dispatch_x402(payment_signature, body:, url:, http_method: nil)
+        payload = decode_x402_payload(payment_signature)
+        return nil unless payload
+
+        offer = @offers.find { |candidate| candidate.x402_matches?(payload) }
+        return nil unless offer
+
+        wrap_offer_result(
+          offer.verify(payment_signature: payment_signature, body: body, url: url, http_method: http_method),
+          offer,
+          payment_signature: payment_signature,
+          url: url,
+          http_method: http_method
+        )
+      end
+
+      sig { params(authorization: String, body: T.untyped, url: T.nilable(String), http_method: T.nilable(String)).returns(T.nilable(ComposedResult)) }
+      def dispatch_authorization(authorization, body:, url:, http_method: nil)
+        payment = Mpp::Server::Verify.extract_payment_scheme(authorization)
+        return nil unless payment
+
+        begin
+          credential = Mpp::Credential.from_authorization(payment)
+        rescue Mpp::ParseError
+          return nil
+        end
+
+        offer = matching_offer(credential)
+        return nil unless offer
+
+        wrap_offer_result(
+          offer.verify(authorization: authorization, body: body, url: url, http_method: http_method),
+          offer,
+          url: url,
+          http_method: http_method
+        )
+      end
+
+      sig { params(credential: Mpp::Credential).returns(T.nilable(ComposeOffer)) }
+      def matching_offer(credential)
+        echo = credential.challenge
+        echo_request = decode_echo_request(echo)
+        return nil if echo_request.nil?
+
+        candidates = @offers.select do |offer|
+          offer.method.name == echo.method && offer.intent_name == echo.intent
+        end
+        return nil if candidates.empty?
+
+        exact = candidates.select { |offer| offer.canonical_request == echo_request }
+        exact.first || candidates.first
+      end
+
+      sig { params(echo: T.untyped).returns(T.nilable(T::Hash[T.untyped, T.untyped])) }
+      def decode_echo_request(echo)
+        return {} if echo.request.nil? || echo.request.empty?
+
+        Mpp::Parsing.b64_decode(echo.request)
+      rescue Mpp::ParseError
+        nil
+      end
+
+      sig { params(payment_signature: String).returns(T.nilable(T::Hash[T.untyped, T.untyped])) }
+      def decode_x402_payload(payment_signature)
+        Mpp::X402::Header.decode_payment_signature(payment_signature)
+      rescue Mpp::ParseError, ArgumentError
+        nil
+      end
+
+      sig do
+        params(
+          result: T.untyped,
+          offer: ComposeOffer,
+          payment_signature: T.nilable(String),
+          url: T.nilable(String),
+          http_method: T.nilable(String)
+        ).returns(ComposedResult)
+      end
+      def wrap_offer_result(result, offer, payment_signature: nil, url: nil, http_method: nil)
+        if result.is_a?(Mpp::Challenge)
+          extra = {}
+          offer.decorate_challenge(extra, result, url: url, http_method: http_method)
+          return ComposedResult.payment_required([result], realm: @handler.realm, extra_headers: extra)
+        end
+
+        credential, receipt = result
+        extra = {}
+        offer.decorate_receipt(extra, credential, receipt, payment_signature: payment_signature)
+        ComposedResult.paid(credential, receipt, realm: @handler.realm, extra_headers: extra)
+      end
+
+      sig do
+        params(
+          body: T.untyped,
+          url: T.nilable(String),
+          accept_payment: T.nilable(String),
+          http_method: T.nilable(String)
+        ).returns(ComposedResult)
+      end
+      def merge_challenges(body:, url:, accept_payment:, http_method:)
+        pairs = @offers.map do |offer|
+          challenge = offer.challenge(body: body, url: url, http_method: http_method)
+          [offer, challenge]
+        end
+
+        ranked = AcceptPayment.apply(pairs.map { |_offer, challenge| challenge }, accept_payment)
+        by_id = pairs.to_h { |offer, challenge| [challenge.id, [offer, challenge]] }
+        pairs = ranked.filter_map { |challenge| by_id[challenge.id] }
+
+        extra = merge_extra_headers(pairs, url: url, http_method: http_method)
+        ComposedResult.payment_required(pairs.map { |_offer, challenge| challenge }, realm: @handler.realm, extra_headers: extra)
+      end
+
+      sig do
+        params(
+          pairs: T::Array[T.untyped],
+          url: T.nilable(String),
+          http_method: T.nilable(String)
+        ).returns(T::Hash[String, T.untyped])
+      end
+      def merge_extra_headers(pairs, url:, http_method:)
+        extra = {}
+        required_headers = []
+        pairs.each do |offer, challenge|
+          headers = {}
+          offer.decorate_challenge(headers, challenge, url: url, http_method: http_method)
+          required = headers["PAYMENT-REQUIRED"]
+          required_headers << required if required
+          headers.each do |key, value|
+            next if key == "PAYMENT-REQUIRED"
+
+            extra[key] = value
+          end
+        end
+
+        merged = merge_payment_required(required_headers)
+        extra["PAYMENT-REQUIRED"] = merged if merged
+        extra
+      end
+
+      sig { params(values: T::Array[String]).returns(T.nilable(String)) }
+      def merge_payment_required(values)
+        return nil if values.empty?
+        return values.first if values.length == 1
+
+        Mpp::X402::Server.merge_payment_required(values)
+      end
+    end
+
+    sig { params(handlers: T.untyped).returns(ComposedHandler) }
+    def self.compose(*handlers)
+      ComposedHandler.compose(handlers)
+    end
+  end
+end

data/lib/mpp/server/decorator.rb

@@ -10,17 +10,38 @@ module Mpp
 
       module_function
 
-      # Build a 402 response for a payment challenge with RFC 9457 problem details body.
-      sig { params(challenge: T.untyped, realm: T.untyped).returns(T::Hash[T.untyped, T.untyped]) }
-      def make_challenge_response(challenge, realm)
-        error = Mpp::PaymentRequiredError.new(realm: realm, description: challenge.description)
-        body = JSON.generate(error.to_problem_details(challenge_id: challenge.id))
+      # Build a 402 response for one or more payment challenges with RFC 9457
+      # problem details. Extra headers (e.g. PAYMENT-REQUIRED) are merged in.
+      sig do
+        params(
+          challenge: T.untyped,
+          realm: T.untyped,
+          extra_headers: T::Hash[T.untyped, T.untyped]
+        ).returns(T::Hash[T.untyped, T.untyped])
+      end
+      def make_challenge_response(challenge, realm, extra_headers: {})
+        challenges = challenge.is_a?(Array) ? challenge : [challenge]
+        Kernel.raise ArgumentError, "at least one challenge is required" if challenges.empty?
+
+        first = challenges.first
+        error = Mpp::PaymentRequiredError.new(realm: realm, description: first.description)
+        body = JSON.generate(error.to_problem_details(challenge_id: first.id))
+        www = challenges.map { |item| item.to_www_authenticate(realm) }
+
         headers = {
-          "WWW-Authenticate" => challenge.to_www_authenticate(realm),
+          "WWW-Authenticate" => ((www.length == 1) ? www.first : www),
           "Cache-Control" => "no-store",
           "Content-Type" => "application/problem+json"
         }
-        Mpp::Server::Middleware.mark_authorization_bound_response(headers)
+        extra_headers.each do |key, value|
+          next if value.nil?
+
+          headers[key] = value
+        end
+        Mpp::Server::Middleware.mark_authorization_bound_response(
+          headers,
+          vary: extra_headers.key?("PAYMENT-REQUIRED") ? ["Authorization", "PAYMENT-SIGNATURE"] : ["Authorization"]
+        )
         {
           "_mpp_challenge" => true,
           "status" => 402,

data/lib/mpp/server/middleware.rb

@@ -14,6 +14,8 @@ module Mpp
     #
     # Payment is verified BEFORE the downstream app runs — if verification
     # fails, the app never executes and a 402 challenge is returned.
+    # Payment-Receipt is attached only when the app then returns 2xx, so a
+    # failed fulfillment is not reported as a successful paid response.
     #
     # Example:
     #   use Mpp::Server::Middleware,
@@ -22,10 +24,10 @@ module Mpp
     class Middleware
       extend T::Sig
 
-      sig { params(app: T.untyped, handler: Mpp::Server::MppHandler, pricing: T.untyped).void }
+      sig { params(app: T.untyped, handler: T.untyped, pricing: T.untyped).void }
       def initialize(app, handler:, pricing:)
         @app = T.let(app, T.untyped)
-        @handler = T.let(handler, Mpp::Server::MppHandler)
+        @handler = T.let(handler, T.untyped)
         @pricing = T.let(pricing, T.untyped)
       end
 
@@ -35,40 +37,56 @@ module Mpp
         return @app.call(env) unless charge_opts
 
         authorization = env["HTTP_AUTHORIZATION"]
+        payment_signature = env["HTTP_PAYMENT_SIGNATURE"]
+        accept_payment = env["HTTP_ACCEPT_PAYMENT"]
+        http_method = env["REQUEST_METHOD"]
+        url = request_url(env)
         body_capture = capture_request_body(env)
 
         request_body = body_capture&.materialize
         env["rack.input"] = StringIO.new(request_body || "") if body_capture
 
-        amount = charge_opts[:amount]
-        opts = charge_opts.except(:amount, :body)
-        opts[:mppx_scope] ||= mppx_scope(env)
+        result = verify_payment(
+          env,
+          charge_opts,
+          authorization: authorization,
+          payment_signature: payment_signature,
+          accept_payment: accept_payment,
+          http_method: http_method,
+          url: url,
+          request_body: request_body
+        )
 
-        result = @handler.charge(authorization, amount, **opts, body: request_body)
-
-        if result.is_a?(Mpp::Challenge)
-          resp = Mpp::Server::Decorator.make_challenge_response(result, @handler.realm)
-          return [resp["status"], resp["headers"], [resp["body"]]]
-        end
+        challenge_response = challenge_rack_response(result, url: url, http_method: http_method)
+        return challenge_response if challenge_response
 
-        _credential, receipt = result
+        credential, receipt, extra_headers = paid_result(result)
         status, headers, body = @app.call(env)
-        headers["Payment-Receipt"] = receipt.to_payment_receipt
-        self.class.mark_authorization_bound_response(headers)
+        if success_status?(status)
+          headers["Payment-Receipt"] = receipt.to_payment_receipt
+          extra_headers.each { |key, value| headers[key] = value unless value.nil? }
+          decorate_single_method_receipt(headers, credential, receipt, payment_signature)
+        end
+        vary = ["Authorization"]
+        vary << "PAYMENT-SIGNATURE" if x402_bound?(headers, payment_signature)
+        self.class.mark_authorization_bound_response(headers, vary: vary)
 
         [status, headers, body]
       end
 
-      sig { params(headers: T::Hash[T.untyped, T.untyped]).void }
-      def self.mark_authorization_bound_response(headers)
+      sig { params(headers: T::Hash[T.untyped, T.untyped], vary: T::Array[String]).void }
+      def self.mark_authorization_bound_response(headers, vary: ["Authorization"])
         headers["Cache-Control"] = "no-store"
 
         vary_values = headers["Vary"].to_s.split(",").map do |value|
           value.strip.downcase
         end
-        return if vary_values.include?("*") || vary_values.include?("authorization")
+        return if vary_values.include?("*")
+
+        additions = vary.reject { |field| vary_values.include?(field.downcase) }
+        return if additions.empty?
 
-        headers["Vary"] = [headers["Vary"], "Authorization"]
+        headers["Vary"] = [headers["Vary"], *additions]
           .compact
           .reject(&:empty?)
           .join(", ")
@@ -76,6 +94,116 @@ module Mpp
 
       private
 
+      sig do
+        params(
+          env: T.untyped,
+          charge_opts: T.untyped,
+          authorization: T.untyped,
+          payment_signature: T.untyped,
+          accept_payment: T.untyped,
+          http_method: T.untyped,
+          url: T.untyped,
+          request_body: T.untyped
+        ).returns(T.untyped)
+      end
+      def verify_payment(env, charge_opts, authorization:, payment_signature:, accept_payment:, http_method:, url:, request_body:)
+        if @handler.is_a?(Mpp::Server::ComposedHandler)
+          return @handler.call(
+            authorization: authorization,
+            payment_signature: payment_signature,
+            body: request_body,
+            url: url,
+            accept_payment: accept_payment,
+            http_method: http_method,
+            scope: mppx_scope(env)
+          )
+        end
+
+        amount = charge_opts[:amount]
+        opts = charge_opts.except(:amount, :body)
+        opts[:mppx_scope] ||= mppx_scope(env)
+        @handler.charge(
+          authorization,
+          amount,
+          **opts,
+          body: request_body,
+          payment_signature: payment_signature,
+          url: url,
+          accept_payment: accept_payment,
+          http_method: http_method
+        )
+      end
+
+      sig { params(result: T.untyped, url: T.nilable(String), http_method: T.nilable(String)).returns(T.nilable(T::Array[T.untyped])) }
+      def challenge_rack_response(result, url:, http_method:)
+        if result.is_a?(Mpp::Server::ComposedResult)
+          return nil unless result.payment_required?
+
+          resp = result.to_response
+          return [resp["status"], resp["headers"], [resp["body"]]]
+        end
+
+        return nil unless result.is_a?(Mpp::Challenge)
+
+        resp = if @handler.respond_to?(:challenge_response)
+          @handler.challenge_response(result, url: url, http_method: http_method)
+        else
+          Mpp::Server::Decorator.make_challenge_response(result, @handler.realm)
+        end
+        [resp["status"], resp["headers"], [resp["body"]]]
+      end
+
+      sig { params(status: T.untyped).returns(T::Boolean) }
+      def success_status?(status)
+        code = Integer(status)
+        (code >= 200) && (code < 300)
+      rescue ArgumentError, TypeError
+        false
+      end
+
+      sig { params(result: T.untyped).returns(T::Array[T.untyped]) }
+      def paid_result(result)
+        if result.is_a?(Mpp::Server::ComposedResult)
+          credential, receipt = result.payment
+          return [credential, receipt, result.extra_headers]
+        end
+
+        credential, receipt = result
+        [credential, receipt, {}]
+      end
+
+      sig { params(headers: T::Hash[T.untyped, T.untyped], credential: T.untyped, receipt: T.untyped, payment_signature: T.untyped).void }
+      def decorate_single_method_receipt(headers, credential, receipt, payment_signature)
+        return unless payment_signature
+        return unless @handler.respond_to?(:method)
+        return unless @handler.method.respond_to?(:decorate_receipt)
+
+        @handler.method.decorate_receipt(headers, receipt, credential, payment_signature: payment_signature)
+      end
+
+      sig { params(headers: T::Hash[T.untyped, T.untyped], payment_signature: T.untyped).returns(T::Boolean) }
+      def x402_bound?(headers, payment_signature)
+        !payment_signature.to_s.empty? ||
+          headers.key?("PAYMENT-RESPONSE") ||
+          headers.key?("PAYMENT-REQUIRED")
+      end
+
+      sig { params(env: T.untyped).returns(String) }
+      def request_url(env)
+        scheme = env["HTTP_X_FORWARDED_PROTO"] || env["rack.url_scheme"] || "http"
+        host = env["HTTP_HOST"]
+        unless host
+          server = env["SERVER_NAME"] || "localhost"
+          port = env["SERVER_PORT"]
+          host = (port && !["80", "443"].include?(port.to_s)) ? "#{server}:#{port}" : server
+        end
+        path = "#{env["SCRIPT_NAME"]}#{env["PATH_INFO"]}"
+        query = env["QUERY_STRING"]
+        url = "#{scheme}://#{host}#{path}"
+        url += "?#{query}" if query && !query.empty?
+        url
+      end
+
       sig { params(env: T.untyped).returns(T.nilable(RackInputCapture)) }
       def capture_request_body(env)
         input = env["rack.input"]