mpp-rb 0.1.5 → 0.1.6

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

@@ -19,14 +19,21 @@ module Mpp
       class TempoMethod
         attr_reader :name, :account, :fee_payer, :fee_payer_allowed_fee_tokens,
           :root_account, :rpc_url, :chain_id, :currency, :recipient, :decimals, :client_id,
-          :expected_recipients, :relay
+          :expected_recipients, :relay, :on_payment_success
         attr_accessor :intents
 
         def initialize(account: nil, fee_payer: nil, root_account: nil,
           rpc_url: Defaults::RPC_URL, chain_id: nil, currency: nil,
           recipient: nil, decimals: 6, client_id: nil,
           expected_recipients: nil, fee_payer_allowed_fee_tokens: nil,
-          relay: nil)
+          relay: nil, on_payment_success: nil, can_offer: nil)
+          unless on_payment_success.nil? || on_payment_success.respond_to?(:call)
+            raise ArgumentError, "on_payment_success must be callable"
+          end
+          if !can_offer.nil? && !can_offer.respond_to?(:call)
+            raise ArgumentError, "can_offer must be callable"
+          end
+
           @name = "tempo"
           @account = account
           @fee_payer = fee_payer
@@ -41,9 +48,17 @@ module Mpp
           @decimals = decimals
           @client_id = client_id
           @expected_recipients = expected_recipients&.map(&:downcase)&.to_set
+          @on_payment_success = on_payment_success
+          @can_offer = can_offer
           @intents = {}
         end
 
+        def can_offer?(request)
+          return true unless @can_offer
+
+          @can_offer.call(request)
+        end
+
         # Create a credential to satisfy the given challenge.
         #
         # mode: :pull (default) — return signed transaction for server to broadcast
@@ -251,7 +266,8 @@ module Mpp
       # Factory function to create a configured TempoMethod.
       def self.tempo(intents:, account: nil, fee_payer: nil, chain_id: nil, rpc_url: nil,
         root_account: nil, currency: nil, recipient: nil, decimals: 6, client_id: nil,
-        expected_recipients: nil, fee_payer_allowed_fee_tokens: nil, relay: nil)
+        expected_recipients: nil, fee_payer_allowed_fee_tokens: nil, relay: nil,
+        on_payment_success: nil, can_offer: nil)
         rpc_url ||= chain_id ? Defaults.rpc_url_for_chain(chain_id) : Defaults::RPC_URL
         currency ||= Defaults.default_currency_for_chain(chain_id)
 
@@ -273,7 +289,9 @@ module Mpp
           client_id: client_id,
           expected_recipients: expected_recipients,
           fee_payer_allowed_fee_tokens: fee_payer_allowed_fee_tokens,
-          relay: Relay.resolve_optional(relay)
+          relay: Relay.resolve_optional(relay),
+          on_payment_success: on_payment_success,
+          can_offer: can_offer
         )
 
         intents.each_value do |intent|

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

@@ -22,7 +22,9 @@ module Mpp
         attr_reader :name
         attr_accessor :rpc_url
 
-        def initialize(chain_id: nil, rpc_url: nil, timeout: 30, store: nil, validate_sender: nil)
+        def initialize(chain_id: nil, rpc_url: nil, timeout: 30, store: Mpp::MemoryStore.new, validate_sender: nil)
+          raise ArgumentError, "store is required" if store.nil?
+
           @name = "charge"
           @rpc_url = rpc_url || (chain_id ? Defaults.rpc_url_for_chain(chain_id) : nil)
           @_method = nil
@@ -111,11 +113,9 @@ module Mpp
           # Validate the source before reserving the hash.
           source_address = parse_hash_credential_source(credential.source, request.method_details.chain_id)
 
-          if @store
-            store_key = "mpp:charge:#{payload.hash.downcase}"
-            raise Mpp::VerificationError, "Transaction hash already used" unless @store.put_if_absent(store_key,
-              payload.hash)
-          end
+          store_key = "mpp:charge:#{payload.hash.downcase}"
+          raise Mpp::VerificationError, "Transaction hash already used" unless @store.put_if_absent(store_key,
+            payload.hash)
 
           rpc_url = get_rpc_url
           result = Rpc.call(rpc_url, "eth_getTransactionReceipt", [payload.hash])
@@ -158,19 +158,15 @@ module Mpp
           end
 
           rpc_url = get_rpc_url
-          reserved_tx_hash = T.let(nil, T.nilable(String))
-          store_key = T.let(nil, T.nilable(String))
-          if @store
-            reserved_tx_hash = raw_transaction_hash(raw_tx)
-            store_key = "mpp:charge:#{reserved_tx_hash.downcase}"
-            unless @store.put_if_absent(store_key, TRANSACTION_PENDING)
-              raise Mpp::VerificationError, "Transaction hash already used" unless @store.get(store_key) == TRANSACTION_PENDING
+          reserved_tx_hash = raw_transaction_hash(raw_tx)
+          store_key = "mpp:charge:#{reserved_tx_hash.downcase}"
+          unless @store.put_if_absent(store_key, TRANSACTION_PENDING)
+            raise Mpp::VerificationError, "Transaction hash already used" unless @store.get(store_key) == TRANSACTION_PENDING
 
-              receipt_data = fetch_transaction_receipt(rpc_url, reserved_tx_hash)
-              verify_transaction_receipt!(receipt_data, request, credential: credential)
-              @store.put(store_key, TRANSACTION_VERIFIED)
-              return Mpp::Receipt.success(reserved_tx_hash)
-            end
+            receipt_data = fetch_transaction_receipt(rpc_url, reserved_tx_hash)
+            verify_transaction_receipt!(receipt_data, request, credential: credential)
+            @store.put(store_key, TRANSACTION_VERIFIED)
+            return Mpp::Receipt.success(reserved_tx_hash)
           end
 
           # We pay the gas, so simulate the co-signed tx first and bail if it
@@ -178,7 +174,7 @@ module Mpp
           begin
             simulate_before_broadcast(simulate_payload, rpc_url) if simulate_payload
           rescue
-            @store.delete(store_key) if @store && store_key
+            @store.delete(store_key)
             raise
           end
 
@@ -186,33 +182,36 @@ module Mpp
           begin
             tx_hash = Rpc.call(rpc_url, "eth_sendRawTransaction", [raw_tx])
           rescue => e
-            if reserved_tx_hash && store_key && transaction_submission_may_have_succeeded?(e)
+            if transaction_submission_may_have_succeeded?(e)
               receipt_data = fetch_transaction_receipt(rpc_url, reserved_tx_hash)
               verify_transaction_receipt!(receipt_data, request, credential: credential)
-              @store&.put(store_key, TRANSACTION_VERIFIED)
+              @store.put(store_key, TRANSACTION_VERIFIED)
               return Mpp::Receipt.success(reserved_tx_hash)
             end
 
-            @store.delete(store_key) if @store && store_key
+            @store.delete(store_key)
             raise Mpp::VerificationError, "Transaction submission failed: #{e.message}"
           end
 
           unless tx_hash
-            @store.delete(store_key) if @store && store_key
+            @store.delete(store_key)
             raise Mpp::VerificationError, "No transaction hash returned"
           end
 
-          if reserved_tx_hash && tx_hash.downcase != reserved_tx_hash.downcase
-            @store.delete(store_key) if @store && store_key
-            raise Mpp::VerificationError, "Returned transaction hash does not match submitted transaction"
-          end
+          # Tempo nodes hash canonical RLP, which can differ from keccak(raw
+          # bytes). Replay keys must follow the chain hash so a later hash
+          # credential for the same payment is rejected. Keep the raw-hash
+          # claim until verification finishes so a concurrent retry cannot
+          # rebroadcast the same payload.
+          raw_store_key = store_key
+          store_key, reserved_tx_hash = rebase_reservation_to_chain_hash(store_key, reserved_tx_hash, tx_hash)
 
-          tx_hash = reserved_tx_hash || tx_hash
-          receipt_data = fetch_transaction_receipt(rpc_url, tx_hash)
+          receipt_data = fetch_transaction_receipt(rpc_url, reserved_tx_hash)
           verify_transaction_receipt!(receipt_data, request, credential: credential)
-          @store.put(store_key, TRANSACTION_VERIFIED) if @store && store_key
+          @store.put(store_key, TRANSACTION_VERIFIED)
+          @store.put(raw_store_key, TRANSACTION_VERIFIED) if raw_store_key != store_key
 
-          Mpp::Receipt.success(tx_hash)
+          Mpp::Receipt.success(reserved_tx_hash)
         end
 
         def transaction_submission_may_have_succeeded?(error)
@@ -389,17 +388,32 @@ module Mpp
         end
 
         def raw_transaction_hash(raw_tx)
-          Kernel.require "eth"
-
           hex = raw_tx.delete_prefix("0x")
           unless hex.match?(/\A[0-9a-fA-F]+\z/) && hex.length.even?
             raise Mpp::VerificationError, "Invalid transaction signature"
           end
 
-          "0x#{Eth::Util.keccak256([hex].pack("H*")).unpack1("H*")}"
-        rescue LoadError
-          raise Mpp::VerificationError,
-            "eth gem is required to compute transaction hash for transaction replay protection"
+          "0x#{Attribution.keccak256([hex].pack("H*")).unpack1("H*")}"
+        end
+
+        def normalize_tx_hash(tx_hash)
+          hex = tx_hash.to_s.downcase
+          hex.start_with?("0x") ? hex : "0x#{hex}"
+        end
+
+        def rebase_reservation_to_chain_hash(store_key, reserved_tx_hash, returned_tx_hash)
+          canonical = normalize_tx_hash(returned_tx_hash)
+          return [store_key, reserved_tx_hash] if canonical == reserved_tx_hash.downcase
+
+          canonical_key = "mpp:charge:#{canonical}"
+          unless @store.put_if_absent(canonical_key, TRANSACTION_PENDING)
+            unless @store.get(canonical_key) == TRANSACTION_PENDING
+              @store.put(store_key, TRANSACTION_VERIFIED)
+              raise Mpp::VerificationError, "Transaction hash already used"
+            end
+          end
+
+          [canonical_key, canonical]
         end
 
         def match_transfer_calldata(call_data_hex, request, challenge: nil)
@@ -455,10 +469,8 @@ module Mpp
           )
           raise Mpp::VerificationError, "Proof signature does not match source" unless valid
 
-          if @store
-            store_key = "mpp:proof:#{credential.challenge.id}"
-            raise Mpp::VerificationError, "Proof credential has already been used" unless @store.put_if_absent(store_key, true)
-          end
+          store_key = "mpp:proof:#{credential.challenge.id}"
+          raise Mpp::VerificationError, "Proof credential has already been used" unless @store.put_if_absent(store_key, true)
 
           Mpp::Receipt.success(credential.challenge.id)
         end

data/lib/mpp/parsing.rb

@@ -101,6 +101,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 +117,8 @@ module Mpp
         digest: params["digest"],
         expires: params["expires"],
         description: params["description"],
-        opaque: opaque
+        opaque: opaque,
+        header: header
       )
     end
 
@@ -131,6 +138,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 +168,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 +182,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 +205,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
@@ -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,
@@ -330,10 +337,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/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,20 @@ module Mpp
           request
         end
       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
     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"