mpp-rb 0.1.5 → 0.1.7

data/lib/mpp/methods/tempo/relay.rb

@@ -96,8 +96,40 @@ module Mpp
         end
         private_class_method :merge_api_key_headers
 
+        def self.to_relay_input(credential)
+          echo = credential.challenge
+          challenge = {
+            "id" => echo.id,
+            "realm" => echo.realm,
+            "method" => echo.method,
+            "intent" => echo.intent,
+            "request" => decode_request(echo.request)
+          }
+          challenge["expires"] = echo.expires if echo.expires
+          challenge["digest"] = echo.digest if echo.digest
+          challenge["opaque"] = echo.opaque if echo.opaque
+
+          input = {
+            "challenge" => challenge,
+            "payload" => credential.payload
+          }
+          input["source"] = credential.source if credential.source
+          input
+        end
+
+        def self.decode_request(request)
+          return request if request.is_a?(Hash)
+          return request unless request.is_a?(String) && !request.empty?
+
+          Mpp::Parsing.b64_decode(request)
+        rescue Mpp::ParseError
+          request
+        end
+        private_class_method :decode_request
+
+        # @deprecated Use #validate followed by #broadcast.
         def verify(credential, _request = nil)
-          input = to_relay_input(credential)
+          input = self.class.to_relay_input(credential)
           validate(input)
           broadcast(input)
         end
@@ -155,36 +187,6 @@ module Mpp
           raise Mpp::VerificationFailedError.new(reason: "relay request failed: #{e.message}")
         end
 
-        def to_relay_input(credential)
-          echo = credential.challenge
-          challenge = {
-            "id" => echo.id,
-            "realm" => echo.realm,
-            "method" => echo.method,
-            "intent" => echo.intent,
-            "request" => decode_request(echo.request)
-          }
-          challenge["expires"] = echo.expires if echo.expires
-          challenge["digest"] = echo.digest if echo.digest
-          challenge["opaque"] = echo.opaque if echo.opaque
-
-          input = {
-            "challenge" => challenge,
-            "payload" => credential.payload
-          }
-          input["source"] = credential.source if credential.source
-          input
-        end
-
-        def decode_request(request)
-          return request if request.is_a?(Hash)
-          return request unless request.is_a?(String) && !request.empty?
-
-          Mpp::Parsing.b64_decode(request)
-        rescue Mpp::ParseError
-          request
-        end
-
         def idempotency_key(input)
           payload = input["payload"]
           if payload.is_a?(Hash) && payload["type"] == "transaction" && payload["signature"].is_a?(String)

data/lib/mpp/methods/tempo/schemas.rb

@@ -7,8 +7,8 @@ module Mpp
       module Schemas
         HEX_PATTERN = /\A0x[a-fA-F0-9]+\z/
 
-        MethodDetails = Data.define(:chain_id, :fee_payer, :fee_payer_url, :memo) do
-          def initialize(chain_id: 4217, fee_payer: false, fee_payer_url: nil, memo: nil)
+        MethodDetails = Data.define(:chain_id, :fee_payer, :fee_payer_url) do
+          def initialize(chain_id: 4217, fee_payer: false, fee_payer_url: nil)
             super
           end
 
@@ -18,8 +18,7 @@ module Mpp
             new(
               chain_id: hash["chainId"] || 4217,
               fee_payer: hash["feePayer"] || false,
-              fee_payer_url: hash["feePayerUrl"],
-              memo: hash["memo"]
+              fee_payer_url: hash["feePayerUrl"]
             )
           end
         end

data/lib/mpp/parsing.rb

@@ -58,10 +58,17 @@ module Mpp
     def parse_auth_params(params_str)
       params = {}
       params_str.scan(AUTH_PARAM_RE) do |key, quoted_val, token_val|
-        Kernel.raise Mpp::ParseError, "Duplicate parameter: #{key}" if params.key?(key)
+        # Auth-parameter names are case-insensitive (RFC 9110 §11.2). Normalize
+        # to lowercase for both the duplicate check and storage, so "id" and
+        # "ID" are treated as the same parameter -- otherwise both get stored
+        # under their original casing and only the lowercase lookup downstream
+        # is ever read, silently ignoring the other value instead of rejecting
+        # the ambiguous header.
+        normalized_key = key.downcase
+        Kernel.raise Mpp::ParseError, "Duplicate parameter: #{key}" if params.key?(normalized_key)
 
         value = quoted_val.nil? ? token_val : unescape_quoted(quoted_val)
-        params[key] = value
+        params[normalized_key] = value
       end
       params
     end
@@ -101,6 +108,12 @@ module Mpp
       opaque_b64 = params["opaque"]
       opaque = (opaque_b64 && !opaque_b64.empty?) ? b64_decode(opaque_b64) : nil
 
+      header = begin
+        Mpp.advertised_credential_header(params["header"])
+      rescue ArgumentError => e
+        Kernel.raise Mpp::ParseError, e.message
+      end
+
       Mpp::Challenge.new(
         id: id,
         method: method,
@@ -111,7 +124,8 @@ module Mpp
         digest: params["digest"],
         expires: params["expires"],
         description: params["description"],
-        opaque: opaque
+        opaque: opaque,
+        header: header
       )
     end
 
@@ -131,6 +145,9 @@ module Mpp
       parts << "digest=\"#{escape_quoted(challenge.digest)}\"" if challenge.digest
       parts << "expires=\"#{escape_quoted(challenge.expires)}\"" if challenge.expires
       parts << "description=\"#{escape_quoted(challenge.description)}\"" if challenge.description
+      if challenge.header
+        parts << "header=\"#{escape_quoted(challenge.header)}\""
+      end
       if challenge.opaque
         opaque_b64 = b64_encode(challenge.opaque)
         parts << "opaque=\"#{opaque_b64}\""
@@ -158,6 +175,12 @@ module Mpp
       method = challenge_data["method"]
       validate_payment_method_id(method)
 
+      header = begin
+        Mpp.advertised_credential_header(challenge_data["header"]&.to_s)
+      rescue ArgumentError => e
+        Kernel.raise Mpp::ParseError, e.message
+      end
+
       echo = Mpp::ChallengeEcho.new(
         id: challenge_data["id"].to_s,
         realm: (challenge_data["realm"] || "").to_s,
@@ -166,7 +189,8 @@ module Mpp
         request: (challenge_data["request"] || "").to_s,
         expires: challenge_data["expires"]&.to_s,
         digest: challenge_data["digest"]&.to_s,
-        opaque: challenge_data["opaque"]&.to_s
+        opaque: challenge_data["opaque"]&.to_s,
+        header: header
       )
 
       Mpp::Credential.new(
@@ -188,6 +212,7 @@ module Mpp
       }
       challenge_dict["expires"] = credential.challenge.expires if credential.challenge.expires
       challenge_dict["digest"] = credential.challenge.digest if credential.challenge.digest
+      challenge_dict["header"] = credential.challenge.header if credential.challenge.header
       challenge_dict["opaque"] = credential.challenge.opaque if credential.challenge.opaque
 
       payload = {

data/lib/mpp/server/compose.rb

@@ -42,8 +42,8 @@ module Mpp
         @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)
+      sig { params(authorization: T.nilable(String), payment_signature: T.nilable(String), body: T.untyped, url: T.nilable(String), http_method: T.nilable(String), request_guard: T.nilable(T.proc.params(request: T::Hash[String, T.untyped]).returns(T::Boolean))).returns(T.untyped) }
+      def verify(authorization: nil, payment_signature: nil, body: nil, url: nil, http_method: nil, &request_guard)
         @handler.charge_one(
           @method,
           authorization,
@@ -52,13 +52,17 @@ module Mpp
           url: url,
           body: body,
           http_method: http_method,
-          **charge_kwargs
+          **charge_kwargs,
+          &request_guard
         )
       end
 
-      sig { params(body: T.untyped, url: T.nilable(String), http_method: T.nilable(String)).returns(Mpp::Challenge) }
+      sig { params(body: T.untyped, url: T.nilable(String), http_method: T.nilable(String)).returns(T.nilable(Mpp::Challenge)) }
       def challenge(body: nil, url: nil, http_method: nil)
-        result = verify(body: body, url: url, http_method: http_method)
+        result = verify(body: body, url: url, http_method: http_method) do |request|
+          Mpp::Server::MethodHelper.can_offer?(@method, request)
+        end
+        return nil if result.nil?
         return result if result.is_a?(Mpp::Challenge)
 
         Kernel.raise "expected a challenge from unpaid offer #{key}"
@@ -68,7 +72,7 @@ module Mpp
       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)
+        @method.decorate_challenge(headers, challenge, url: url, http_method: http_method, request: challenge.request)
         headers
       end
 
@@ -100,7 +104,7 @@ module Mpp
         @options[:amount].to_s
       end
 
-      REQUEST_OPTION_KEYS = [:body, :url, :payment_signature, :accept_payment, :authorization, :http_method].freeze
+      REQUEST_OPTION_KEYS = [:body, :url, :payment_signature, :accept_payment, :authorization, :http_method, :payment_authorization].freeze
 
       sig { returns(T::Hash[Symbol, T.untyped]) }
       def charge_kwargs
@@ -136,7 +140,7 @@ module Mpp
 
       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) })
+        new(handler: handler, offers: entries.flat_map { |entry| offers_from_entry(handler, entry) })
       end
 
       # Flatten nested compositions into a single handler.
@@ -159,6 +163,7 @@ module Mpp
       sig do
         params(
           authorization: T.nilable(String),
+          payment_authorization: T.nilable(String),
           payment_signature: T.nilable(String),
           body: T.untyped,
           url: T.nilable(String),
@@ -167,10 +172,11 @@ module Mpp
           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)
+      def call(authorization: nil, payment_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_authorization: payment_authorization,
             payment_signature: payment_signature,
             body: body,
             url: url,
@@ -179,8 +185,9 @@ module Mpp
           )
         end
 
+        credential = @handler.payment_credential_value(authorization, payment_authorization)
         dispatched = dispatch_credential(
-          authorization: authorization,
+          authorization: credential,
           payment_signature: payment_signature,
           body: body,
           url: url,
@@ -193,8 +200,9 @@ module Mpp
 
       private
 
-      sig { params(handler: T.untyped, entry: T.untyped).returns(ComposeOffer) }
-      def self.offer_from_entry(handler, entry)
+      # A method accepting several currencies yields one offer per currency.
+      sig { params(handler: T.untyped, entry: T.untyped).returns(T::Array[ComposeOffer]) }
+      def self.offers_from_entry(handler, entry)
         unless entry.is_a?(Array) && entry.length == 2
           Kernel.raise ArgumentError, "compose() entries must be [method, options] tuples"
         end
@@ -205,9 +213,13 @@ module Mpp
           Kernel.raise ArgumentError, "compose() options must be a Hash"
         end
 
-        ComposeOffer.new(handler, handler.resolve_method(method_ref), options)
+        method = handler.resolve_method(method_ref)
+        currencies = Mpp::Server::MethodHelper.offer_currencies(method, options)
+        return [ComposeOffer.new(handler, method, options)] if currencies.nil?
+
+        currencies.map { |currency| ComposeOffer.new(handler, method, options.merge(currency: currency)) }
       end
-      private_class_method :offer_from_entry
+      private_class_method :offers_from_entry
 
       sig do
         params(
@@ -330,10 +342,15 @@ module Mpp
         ).returns(ComposedResult)
       end
       def merge_challenges(body:, url:, accept_payment:, http_method:)
-        pairs = @offers.map do |offer|
+        pairs = @offers.filter_map do |offer|
           challenge = offer.challenge(body: body, url: url, http_method: http_method)
+          next if challenge.nil?
+
           [offer, challenge]
         end
+        if pairs.empty?
+          Kernel.raise ArgumentError, "No payment offers are available for this request"
+        end
 
         ranked = AcceptPayment.apply(pairs.map { |_offer, challenge| challenge }, accept_payment)
         by_id = pairs.to_h { |offer, challenge| [challenge.id, [offer, challenge]] }

data/lib/mpp/server/decorator.rb

@@ -38,9 +38,11 @@ module Mpp
 
           headers[key] = value
         end
+        credential_headers = challenges.map(&:credential_header).uniq
+        vary = extra_headers.key?("PAYMENT-REQUIRED") ? credential_headers + ["PAYMENT-SIGNATURE"] : credential_headers
         Mpp::Server::Middleware.mark_authorization_bound_response(
           headers,
-          vary: extra_headers.key?("PAYMENT-REQUIRED") ? ["Authorization", "PAYMENT-SIGNATURE"] : ["Authorization"]
+          vary: vary
         )
         {
           "_mpp_challenge" => true,

data/lib/mpp/server/intent.rb

@@ -6,7 +6,11 @@ module Mpp
     extend T::Sig
 
     # Intent interface (duck type):
-    #   name  -> String
+    #   name -> String
+    #   validate(credential, request) -> Validation
+    #   broadcast(credential, request) -> Receipt
+    #
+    # Intents may temporarily implement only the deprecated verify API:
     #   verify(credential, request) -> Receipt
     #
     # Implement this interface for custom payment intents.
@@ -25,6 +29,7 @@ module Mpp
       end
 
       sig { params(credential: Mpp::Credential, request: T::Hash[String, T.untyped]).returns(Mpp::Receipt) }
+      # @deprecated Implement #validate and #broadcast for new intents.
       def verify(credential, request)
         @verify_fn.call(credential, request)
       end

data/lib/mpp/server/intent_lifecycle.rb

@@ -0,0 +1,41 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Mpp
+  module Server
+    # Dispatches an intent through its optional two-phase lifecycle.
+    #
+    # Two-phase intents expose separate non-mutating validation and terminal
+    # payment operations:
+    #   validate(credential, request) -> Validation
+    #   broadcast(credential, request) -> Receipt
+    #
+    # Broadcast receives the original inputs rather than trusting a prior
+    # validation result, matching mppx's re-validation behavior.
+    #
+    # Intents that only implement the deprecated #verify API continue to work
+    # through the legacy path.
+    module IntentLifecycle
+      extend T::Sig
+
+      module_function
+
+      sig { params(intent: T.untyped, credential: Mpp::Credential, request: T::Hash[String, T.untyped]).returns(Mpp::Receipt) }
+      def call(intent, credential, request)
+        has_validate = intent.respond_to?(:validate)
+        has_broadcast = intent.respond_to?(:broadcast)
+
+        if has_validate != has_broadcast
+          Kernel.raise ArgumentError, "intent must implement both #validate and #broadcast"
+        end
+
+        if has_validate
+          intent.validate(credential, request)
+          intent.broadcast(credential, request)
+        else
+          intent.verify(credential, request)
+        end
+      end
+    end
+  end
+end

data/lib/mpp/server/method.rb

@@ -7,6 +7,7 @@ module Mpp
     #   name       -> String
     #   intents    -> Hash[String, Intent]
     #   create_credential(challenge) -> Credential
+    #   on_payment_success -> optional callable receiving a payment.success payload
 
     module MethodHelper
       extend T::Sig
@@ -22,6 +23,46 @@ module Mpp
           request
         end
       end
+
+      # Give a method a chance to create a request-scoped intent view and to
+      # remove private server input before the canonical request is built.
+      sig { params(method: T.untyped, intent: T.untyped, input: T::Hash[Symbol, T.untyped]).returns([T.untyped, T::Hash[Symbol, T.untyped]]) }
+      def prepare_intent(method, intent, input)
+        return [intent, input] unless method.respond_to?(:prepare_intent)
+
+        prepared = method.prepare_intent(intent, input)
+        unless prepared.is_a?(Array) && prepared.length == 2 && prepared[1].is_a?(Hash)
+          Kernel.raise ArgumentError, "prepare_intent must return [intent, request_input]"
+        end
+
+        [prepared[0], prepared[1]]
+      end
+
+      # Check whether a method should be advertised for a canonical request.
+      # This only governs composing new 402 offers, never credential redemption.
+      sig { params(method: T.untyped, request: T::Hash[String, T.untyped]).returns(T::Boolean) }
+      def can_offer?(method, request)
+        return true unless method.respond_to?(:can_offer?)
+
+        available = method.can_offer?(request)
+        unless available == true || available == false
+          Kernel.raise ArgumentError, "can_offer? must return true or false"
+        end
+
+        available
+      end
+
+      # Currencies to fan out into one offer each, in order. Returns nil when
+      # the offer needs no fan-out: the method accepts at most one currency or
+      # the request already pins a currency.
+      sig { params(method: T.untyped, options: T::Hash[T.untyped, T.untyped]).returns(T.nilable(T::Array[String])) }
+      def offer_currencies(method, options)
+        return nil unless options[:currency].nil? && options["currency"].nil?
+        return nil unless method.respond_to?(:currencies)
+
+        currencies = method.currencies
+        (currencies.is_a?(Array) && currencies.length > 1) ? currencies : nil
+      end
     end
   end
 end

data/lib/mpp/server/middleware.rb

@@ -37,6 +37,7 @@ module Mpp
         return @app.call(env) unless charge_opts
 
         authorization = env["HTTP_AUTHORIZATION"]
+        payment_authorization = env["HTTP_PAYMENT_AUTHORIZATION"]
         payment_signature = env["HTTP_PAYMENT_SIGNATURE"]
         accept_payment = env["HTTP_ACCEPT_PAYMENT"]
         http_method = env["REQUEST_METHOD"]
@@ -50,6 +51,7 @@ module Mpp
           env,
           charge_opts,
           authorization: authorization,
+          payment_authorization: payment_authorization,
           payment_signature: payment_signature,
           accept_payment: accept_payment,
           http_method: http_method,
@@ -67,7 +69,7 @@ module Mpp
           extra_headers.each { |key, value| headers[key] = value unless value.nil? }
           decorate_single_method_receipt(headers, credential, receipt, payment_signature)
         end
-        vary = ["Authorization"]
+        vary = [credential_vary_field]
         vary << "PAYMENT-SIGNATURE" if x402_bound?(headers, payment_signature)
         self.class.mark_authorization_bound_response(headers, vary: vary)
 
@@ -99,6 +101,7 @@ module Mpp
           env: T.untyped,
           charge_opts: T.untyped,
           authorization: T.untyped,
+          payment_authorization: T.untyped,
           payment_signature: T.untyped,
           accept_payment: T.untyped,
           http_method: T.untyped,
@@ -106,10 +109,11 @@ module Mpp
           request_body: T.untyped
         ).returns(T.untyped)
       end
-      def verify_payment(env, charge_opts, authorization:, payment_signature:, accept_payment:, http_method:, url:, request_body:)
+      def verify_payment(env, charge_opts, authorization:, payment_authorization:, payment_signature:, accept_payment:, http_method:, url:, request_body:)
         if @handler.is_a?(Mpp::Server::ComposedHandler)
           return @handler.call(
             authorization: authorization,
+            payment_authorization: payment_authorization,
             payment_signature: payment_signature,
             body: request_body,
             url: url,
@@ -127,6 +131,7 @@ module Mpp
           amount,
           **opts,
           body: request_body,
+          payment_authorization: payment_authorization,
           payment_signature: payment_signature,
           url: url,
           accept_payment: accept_payment,
@@ -188,6 +193,15 @@ module Mpp
           headers.key?("PAYMENT-REQUIRED")
       end
 
+      sig { returns(String) }
+      def credential_vary_field
+        if @handler.respond_to?(:requires_auth) && @handler.requires_auth
+          Mpp::PAYMENT_AUTHORIZATION_HEADER
+        else
+          Mpp::AUTHORIZATION_HEADER
+        end
+      end
+
       sig { params(env: T.untyped).returns(String) }
       def request_url(env)
         scheme = env["HTTP_X_FORWARDED_PROTO"] || env["rack.url_scheme"] || "http"