mpp-rb 0.1.4 → 0.1.6

data/lib/mpp/receipt.rb

@@ -2,8 +2,8 @@
 # frozen_string_literal: true
 
 module Mpp
-  Receipt = Data.define(:status, :timestamp, :reference, :method, :external_id, :extra) do
-    def initialize(status:, timestamp:, reference:, method: "", external_id: nil, extra: nil)
+  Receipt = Data.define(:status, :timestamp, :reference, :method, :external_id, :extra, :subscription_id) do
+    def initialize(status:, timestamp:, reference:, method: "", external_id: nil, extra: nil, subscription_id: nil)
       super
     end
 
@@ -18,13 +18,14 @@ module Mpp
     end
 
     # Create a success receipt with current timestamp.
-    def self.success(reference, timestamp: nil, method: "tempo", external_id: nil, extra: nil)
+    def self.success(reference, timestamp: nil, method: "tempo", external_id: nil, extra: nil, subscription_id: nil)
       new(
         status: "success",
         timestamp: timestamp || Time.now.utc,
         reference: reference,
         method: method,
         external_id: external_id,
+        subscription_id: subscription_id,
         extra: extra
       )
     end

data/lib/mpp/server/accept_payment.rb

@@ -0,0 +1,194 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Mpp
+  module Server
+    # Parse, format, and rank the Accept-Payment client-preference header.
+    #
+    # Syntax mirrors HTTP content negotiation: `method/intent[;q=value]`,
+    # comma-separated. Wildcards (`*` / `tempo/*` / `*/charge`) are allowed.
+    # Entries with q=0 are excluded. If the header is empty, invalid, or
+    # filters out every offer, the original offer list is returned.
+    module AcceptPayment
+      extend T::Sig
+
+      TOKEN_RE = /\A(?:\*|[a-z0-9-]+)\z/
+      ENTRY_RE = %r{\A(?<method>[^/;\s]+|\*)\s*/\s*(?<intent>[^/;\s]+|\*)(?<params>(?:\s*;\s*.+)?)\z}
+      PARAM_RE = /\A(?<name>[A-Za-z0-9_-]+)\s*=\s*(?<value>\S+)\z/
+      QVALUE_RE = /\A(?:0(?:\.\d{0,3})?|1(?:\.0{0,3})?)\z/
+
+      Entry = T.type_alias { T::Hash[Symbol, T.untyped] }
+
+      module_function
+
+      # Parse an Accept-Payment header. Raises ArgumentError on malformed input.
+      sig { params(header: String).returns(T::Array[Entry]) }
+      def parse(header)
+        parts = header.split(",").map(&:strip).reject(&:empty?)
+        Kernel.raise ArgumentError, "Accept-Payment header is empty." if parts.empty?
+
+        parts.each_with_index.map { |part, index| parse_entry(part, index) }
+      end
+
+      # Filter and reorder offers by Accept-Payment. Returns `offers` unchanged
+      # when the header is missing, malformed, or matches nothing.
+      sig { params(offers: T::Array[T.untyped], header: T.nilable(String)).returns(T::Array[T.untyped]) }
+      def apply(offers, header)
+        return offers if header.nil? || header.strip.empty?
+
+        begin
+          preferences = parse(header)
+        rescue ArgumentError
+          return offers
+        end
+
+        ranked = rank(offers, preferences)
+        ranked.empty? ? offers : ranked
+      end
+
+      # Order offers by the best matching client preference.
+      # More specific matches win before comparing q-values.
+      sig { params(offers: T::Array[T.untyped], preferences: T::Array[Entry]).returns(T::Array[T.untyped]) }
+      def rank(offers, preferences)
+        scored = []
+        offers.each_with_index do |offer, index|
+          match = best_match(offer, preferences)
+          next unless match && T.unsafe(match[:q]) > 0
+
+          scored << {match: match, offer: offer, index: index}
+        end
+
+        scored.sort_by! { |row| [-T.unsafe(row[:match][:q]), T.unsafe(row[:index])] }
+        scored.map { |row| row[:offer] }
+      end
+
+      sig { params(value: T.untyped).returns(String) }
+      def key_of(value)
+        method, intent = method_intent(value)
+        Kernel.raise ArgumentError, "Missing payment method name." if method.empty?
+
+        "#{method}/#{intent}"
+      end
+
+      sig { params(part: String, index: Integer).returns(Entry) }
+      def parse_entry(part, index)
+        match = ENTRY_RE.match(part)
+        Kernel.raise ArgumentError, "Invalid Accept-Payment entry: #{part}" unless match
+
+        method = T.must(match[:method])
+        intent = T.must(match[:intent])
+        assert_token!(method, "method")
+        assert_token!(intent, "intent")
+
+        q = 1.0
+        split_parameters(match[:params]).each do |param|
+          next if param.empty?
+
+          parameter_match = PARAM_RE.match(param)
+          Kernel.raise ArgumentError, "Invalid Accept-Payment parameter: #{param}" unless parameter_match
+
+          next unless parameter_match[:name] == "q"
+
+          q = parse_header_q(T.must(parameter_match[:value]), %(Accept-Payment entry "#{part}"))
+        end
+
+        {method: method, intent: intent, q: q, index: index}
+      end
+      private_class_method :parse_entry
+
+      sig { params(offer: T.untyped, preferences: T::Array[Entry]).returns(T.nilable(Entry)) }
+      def best_match(offer, preferences)
+        method, intent = method_intent(offer)
+        best = T.let(nil, T.nilable(Entry))
+
+        preferences.each do |preference|
+          next unless matches?(method, intent, preference)
+
+          candidate = preference.merge(specificity: specificity(preference))
+          if better_match?(candidate, best)
+            best = candidate
+          end
+        end
+
+        best
+      end
+      private_class_method :best_match
+
+      sig { params(candidate: Entry, best: T.nilable(Entry)).returns(T::Boolean) }
+      def better_match?(candidate, best)
+        return true if best.nil?
+        return true if T.unsafe(candidate[:specificity]) > T.unsafe(best[:specificity])
+        return true if T.unsafe(candidate[:specificity]) == T.unsafe(best[:specificity]) &&
+          T.unsafe(candidate[:q]) > T.unsafe(best[:q])
+        return true if T.unsafe(candidate[:specificity]) == T.unsafe(best[:specificity]) &&
+          T.unsafe(candidate[:q]) == T.unsafe(best[:q]) &&
+          T.unsafe(candidate[:index]) < T.unsafe(best[:index])
+
+        false
+      end
+      private_class_method :better_match?
+
+      sig { params(method: String, intent: String, preference: Entry).returns(T::Boolean) }
+      def matches?(method, intent, preference)
+        (preference[:method] == "*" || preference[:method] == method) &&
+          (preference[:intent] == "*" || preference[:intent] == intent)
+      end
+      private_class_method :matches?
+
+      sig { params(preference: Entry).returns(Integer) }
+      def specificity(preference)
+        ((preference[:method] == "*") ? 0 : 1) + ((preference[:intent] == "*") ? 0 : 1)
+      end
+      private_class_method :specificity
+
+      sig { params(offer: T.untyped).returns([String, String]) }
+      def method_intent(offer)
+        if offer.is_a?(Hash)
+          [(offer[:method] || offer["method"]).to_s, (offer[:intent] || offer["intent"]).to_s]
+        else
+          [offer.method.to_s, offer.intent.to_s]
+        end
+      end
+      private_class_method :method_intent
+
+      sig { params(value: T.nilable(String)).returns(T::Array[String]) }
+      def split_parameters(value)
+        return [] if value.nil? || value.empty?
+
+        value.split(";").map(&:strip).reject(&:empty?)
+      end
+      private_class_method :split_parameters
+
+      sig { params(value: String, context: String).returns(Float) }
+      def parse_header_q(value, context)
+        unless QVALUE_RE.match?(value)
+          Kernel.raise ArgumentError, "Invalid q-value for #{context}. Expected an HTTP qvalue."
+        end
+
+        assert_q(Kernel.Float(value), context)
+      end
+      private_class_method :parse_header_q
+
+      sig { params(value: Float, context: String).returns(Float) }
+      def assert_q(value, context)
+        Kernel.raise ArgumentError, "Invalid q-value for #{context}. Expected a value between 0 and 1." if value.negative? || value > 1
+
+        rounded = (value * 1000).round
+        if (value * 1000 - rounded).abs > 1e-9
+          Kernel.raise ArgumentError, "Invalid q-value for #{context}. Expected at most 3 decimal places."
+        end
+
+        rounded / 1000.0
+      end
+      private_class_method :assert_q
+
+      sig { params(value: String, label: String).void }
+      def assert_token!(value, label)
+        return if TOKEN_RE.match?(value)
+
+        Kernel.raise ArgumentError, "Invalid Accept-Payment #{label}: #{value}"
+      end
+      private_class_method :assert_token!
+    end
+  end
+end

data/lib/mpp/server/compose.rb

@@ -0,0 +1,399 @@
+# 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), 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,
+          amount,
+          payment_signature: payment_signature,
+          url: url,
+          body: body,
+          http_method: http_method,
+          **charge_kwargs,
+          &request_guard
+        )
+      end
+
+      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) 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}"
+      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: challenge.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, :payment_authorization].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_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_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,
+            accept_payment: accept_payment,
+            http_method: http_method
+          )
+        end
+
+        credential = @handler.payment_credential_value(authorization, payment_authorization)
+        dispatched = dispatch_credential(
+          authorization: credential,
+          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.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]] }
+        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,40 @@ 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
+        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: vary
+        )
         {
           "_mpp_challenge" => true,
           "status" => 402,

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