mpp-rb 0.1.4 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c71efa5e58021d08e4ed10c0156ed9b140923b0f3ebeb5ce6b42839594c27dd6
-  data.tar.gz: d40e3c4994086eea6f2c11023f47fda635637ae6815dc263d63c12ca10235ae8
+  metadata.gz: d028d7ba9d07e95173c4d3618a688dd87d4674284195a58ecfa4d6d43a311bf7
+  data.tar.gz: 3a342589c1478477c42077297f11244550ce035e4d66f9e4afde2e9a125d091c
 SHA512:
-  metadata.gz: af6ba306f236fb01dd140f63ce51c764fdee655a7f1282d7adad87d8586e4838d43f096ca79a4053dbab703afdc6fa1806d3e20ea6b6afa75c7c70bf6d3885f3
-  data.tar.gz: db9bc204d61dcdb4c3e9d0b8f9034f935dd38d4291b71b37e61a29889240b27667400e5c48333d2cf39e2d6513b5af70368a354a8a20fd5a543558b07b68f700
+  metadata.gz: bf7ad2c6e7db109dc6244609e24eaf42f444396f0df9a69dd428017635dca2abb001271d89cd6c1e715fa3c58bf352ee267455ea0e38623cfd6dc608cd2da609
+  data.tar.gz: 6f090b293910e66a99054316767d36913a1a258c9ae5e1989fd74b16f67c8bad236b2e5351f6c4582140f5f48a0f707f2395245196470ec4c2206b0fb41418ad

data/README.md

@@ -49,6 +49,114 @@ else
 end
 ```
 
+If the endpoint already uses `Authorization` (API keys, Bearer tokens), create the server with `requires_auth: true`. Challenges then advertise `header="Payment-Authorization"`, and clients send the Payment credential in that header instead of `Authorization`.
+
+```ruby
+server = Mpp.create(method: tempo, requires_auth: true)
+
+result = server.charge(
+  env["HTTP_AUTHORIZATION"],
+  "0.50",
+  payment_authorization: env["HTTP_PAYMENT_AUTHORIZATION"],
+)
+```
+
+### Multiple methods
+
+```ruby
+server = Mpp.create(methods: [tempo, evm, stripe])
+
+paid = server.compose(
+  [tempo, {amount: "0.01"}],
+  [evm, {amount: "0.01"}],
+  [stripe, {amount: "0.01", currency: "usd"}]
+)
+
+result = paid.call(
+  authorization: env["HTTP_AUTHORIZATION"],
+  payment_authorization: env["HTTP_PAYMENT_AUTHORIZATION"],
+  payment_signature: env["HTTP_PAYMENT_SIGNATURE"],
+  accept_payment: env["HTTP_ACCEPT_PAYMENT"],
+  url: request.url,
+  http_method: request.request_method
+)
+
+if result.payment_required?
+  resp = result.to_response
+else
+  credential, receipt = result.payment
+end
+```
+
+### Stripe machine payments
+
+`Mpp::Methods::Stripe.create` configures Stripe Payment Tokens and static
+crypto deposit addresses from an injected Stripe client. Add the `stripe` gem
+to your application, then configure the methods:
+
+```ruby
+require "stripe"
+
+stripe_client = Stripe::StripeClient.new(ENV.fetch("STRIPE_SECRET_KEY"))
+payments = Mpp::Methods::Stripe.create(
+  client: stripe_client,
+  network_id: ENV.fetch("STRIPE_NETWORK_ID"),
+  livemode: false,
+  deposit_addresses: {
+    tempo: ENV.fetch("TEMPO_DEPOSIT_ADDRESS"),
+    base: ENV.fetch("BASE_DEPOSIT_ADDRESS")
+  },
+  metadata: {"product" => "example"}
+)
+
+server = Mpp.create(methods: payments.default_methods)
+```
+
+With no deposit addresses, defaults are Stripe Payment Tokens only.
+`default_methods` adds Tempo when its static address is configured. Add Base
+explicitly with its x402 facilitator:
+
+```ruby
+base = payments.base.charge(
+  x402: {facilitator: "https://x402.org/facilitator"}
+)
+server = Mpp.create(methods: [*payments.default_methods, base])
+```
+
+When composed, SPT offers below $0.50 and Tempo/Base offers below one cent are
+not advertised. Successful Tempo and Base payments are best-effort recorded as
+Stripe crypto transaction-verification PaymentIntents. Metadata is included on
+every Stripe PaymentIntent.
+
+`evm.charge` additionally emits `PAYMENT-REQUIRED` and accepts `PAYMENT-SIGNATURE` (x402 v2 exact) when a facilitator is configured:
+
+```ruby
+# Public / testnet facilitator
+x402: {facilitator: "https://x402.org/facilitator"}
+
+# Per-request headers (bearer token, CDP JWT, etc.)
+x402: {facilitator: {url: facilitator_url, headers: -> { {"Authorization" => "Bearer #{token}"} }}}
+
+# The proc may take the request path (`/verify`, `/settle`) when headers differ per call
+x402: {facilitator: {url: cdp_url, headers: ->(path) { cdp_headers(path) }}}
+
+# Any client with #verify / #settle
+x402: {facilitator: cdp_client}
+```
+
+Tempo charge can sponsor gas through a hosted fee payer, or skip local RPC by sending credentials to a Tempo API-compatible relay. Both use the same `{url:, headers:}` shape as the x402 facilitator:
+
+```ruby
+# Hosted fee payer (JSON-RPC eth_signRawTransaction)
+fee_payer: {url: sponsor_url, headers: -> { {"Authorization" => "Bearer #{token}"} }}
+
+# Local co-sign
+fee_payer: Mpp::Methods::Tempo::Account.from_key(ENV.fetch("FEE_PAYER_KEY"))
+
+# Relay (POST /v1/mpp/validate then /v1/mpp/broadcast)
+relay: {url: "https://api.tempo.xyz", headers: -> { {"tempo-api-key" => ENV.fetch("TEMPO_API_KEY")} }}
+```
+
 ### Client
 
 ```ruby
@@ -97,6 +205,18 @@ end
 
 Client events are `challenge.received`, `credential.created`, `payment.response`, and `payment.failed`. Server events are `challenge.created`, `payment.success`, and `payment.failed`.
 
+When a side effect belongs to one payment method, attach it to the method instead. The hook only receives successful payments for that method and intent; an exception in the hook does not invalidate the payment.
+
+```ruby
+method = Mpp::Methods::Tempo.tempo(
+  intents: {"charge" => Mpp::Methods::Tempo::ChargeIntent.new},
+  recipient: "0x0000000000000000000000000000000000000001",
+  on_payment_success: ->(payload) {
+    record_payment(payload[:receipt], payload[:request])
+  },
+)
+```
+
 ### Rack Middleware
 
 ```ruby
@@ -122,6 +242,10 @@ env["mpp.charge"] = { amount: "0.50", description: "Paid endpoint" }
 |---------|-------------|
 | [tempo_charge](./examples/tempo_charge/) | Tempo testnet payments via Sinatra |
 | [stripe_charge](./examples/stripe_charge/) | Stripe payments via Shared Payment Tokens |
+| [compose](./examples/compose/) | Tempo + Base USDC + Stripe SPTs on one endpoint |
+| [evm_x402](./examples/evm_x402/) | EVM charge with x402 exact compatibility |
+| [tempo_feepayer](./examples/tempo_feepayer/) | Tempo charge with a hosted fee-payer `{url:, headers:}` |
+| [tempo_relay](./examples/tempo_relay/) | Tempo charge delegated to an MPP relay `{url:, headers:}` |
 
 Each example is a standalone Sinatra app with `/free` and `/paid` endpoints. To run one:
 
@@ -143,8 +267,11 @@ npx mppx http://localhost:4567/paid
 |--------|---------------|---------------|
 | Tempo | Yes | Yes |
 | Stripe | Yes | Yes |
+| EVM (`evm.charge`, x402 exact) | No | Yes |
+
+Tempo charge transaction construction is implemented directly in Ruby. Runtime dependency: `keccak` (Tempo attribution memos). Optional dependencies: `eth` (account signing, EIP-3009 recovery) and `rlp` (fee payer envelope).
 
-Tempo charge transaction construction is implemented directly in Ruby. Optional dependencies: `eth` (account signing) and `rlp` (fee payer envelope).
+`Mpp.create` accepts a single `method:` (unchanged) or `methods:` to register several payment methods. `server.compose` presents every method as multiple `WWW-Authenticate` challenges; `evm.charge` also emits `PAYMENT-REQUIRED` and accepts `PAYMENT-SIGNATURE` when a facilitator is configured. The Ruby HTTP client does not yet sign EVM or x402 credentials.
 
 ## Protocol
 

data/lib/mpp/challenge.rb

@@ -16,16 +16,30 @@ module Mpp
     :digest,
     :expires,
     :description,
-    :opaque
+    :opaque,
+    :header
   ) do
     def initialize(id:, method:, intent:, request:, realm: "", request_b64: "", digest: nil, expires: nil,
-      description: nil, opaque: nil)
-      super
+      description: nil, opaque: nil, header: nil)
+      super(
+        id: id,
+        method: method,
+        intent: intent,
+        request: request,
+        realm: realm,
+        request_b64: request_b64,
+        digest: digest,
+        expires: expires,
+        description: description,
+        opaque: opaque,
+        header: Mpp.advertised_credential_header(header)
+      )
     end
 
     # Create a Challenge with an HMAC-bound ID.
     def self.create(secret_key:, realm:, method:, intent:, request:, expires: nil, digest: nil, description: nil,
-      meta: nil)
+      meta: nil, header: nil)
+      header = Mpp.advertised_credential_header(header)
       challenge_id = Mpp.generate_challenge_id(
         secret_key: secret_key,
         realm: realm,
@@ -34,7 +48,8 @@ module Mpp
         request: request,
         expires: expires,
         digest: digest,
-        opaque: meta
+        opaque: meta,
+        header: header
       )
       request_json = Mpp::Json.compact_encode(request)
       request_b64 = Mpp.b64url_encode(request_json)
@@ -49,7 +64,8 @@ module Mpp
         digest: digest,
         expires: expires,
         description: description,
-        opaque: meta
+        opaque: meta,
+        header: header
       )
     end
 
@@ -152,6 +168,11 @@ module Mpp
       Mpp::Parsing.format_www_authenticate(self, realm)
     end
 
+    # HTTP field a client must use for the payment credential.
+    def credential_header
+      header || Mpp::AUTHORIZATION_HEADER
+    end
+
     # Verify the challenge ID matches the expected HMAC.
     def verify(secret_key, realm)
       expected_id = Mpp.generate_challenge_id(
@@ -162,7 +183,8 @@ module Mpp
         request: request,
         expires: expires,
         digest: digest,
-        opaque: opaque
+        opaque: opaque,
+        header: header
       )
       Mpp.secure_compare(id, expected_id)
     end
@@ -183,7 +205,8 @@ module Mpp
         request: request_b64,
         expires: expires,
         digest: digest,
-        opaque: opaque_b64
+        opaque: opaque_b64,
+        header: header
       )
     end
   end

data/lib/mpp/challenge_echo.rb

@@ -10,10 +10,21 @@ module Mpp
     :request,
     :expires,
     :digest,
-    :opaque
+    :opaque,
+    :header
   ) do
-    def initialize(id:, realm:, method:, intent:, request:, expires: nil, digest: nil, opaque: nil)
-      super
+    def initialize(id:, realm:, method:, intent:, request:, expires: nil, digest: nil, opaque: nil, header: nil)
+      super(
+        id: id,
+        realm: realm,
+        method: method,
+        intent: intent,
+        request: request,
+        expires: expires,
+        digest: digest,
+        opaque: opaque,
+        header: Mpp.advertised_credential_header(header)
+      )
     end
   end
 end

data/lib/mpp/challenge_id.rb

@@ -9,13 +9,18 @@ module Mpp
 
   module_function
 
+  # RFC 9110 token used as an HTTP field name.
+  HTTP_HEADER_NAME_RE = T.let(/\A[!#$%&'*+.^_`|~0-9A-Za-z-]+\z/, Regexp)
+
   # Generate HMAC-SHA256 challenge ID per spec.
   #
   # HMAC input format: realm|method|intent|request_b64|expires|digest|opaque_b64
-  # All fields always included; absent optional fields use empty string.
+  # Challenges that advertise a credential header insert it immediately before
+  # the final opaque slot. Authorization is the implicit default and is never
+  # included, preserving the legacy binding.
   # Output: base64url(HMAC-SHA256(secret_key, input))
-  sig { params(secret_key: T.untyped, realm: T.untyped, method: T.untyped, intent: T.untyped, request: T.untyped, expires: T.untyped, digest: T.untyped, opaque: T.untyped).returns(String) }
-  def generate_challenge_id(secret_key:, realm:, method:, intent:, request:, expires: nil, digest: nil, opaque: nil)
+  sig { params(secret_key: T.untyped, realm: T.untyped, method: T.untyped, intent: T.untyped, request: T.untyped, expires: T.untyped, digest: T.untyped, opaque: T.untyped, header: T.untyped).returns(String) }
+  def generate_challenge_id(secret_key:, realm:, method:, intent:, request:, expires: nil, digest: nil, opaque: nil, header: nil)
     request_json = Json.compact_encode(request)
     request_b64 = b64url_encode(request_json)
 
@@ -32,14 +37,33 @@ module Mpp
       intent,
       request_b64,
       expires || "",
-      digest || "",
-      opaque_b64
-    ].join("|")
+      digest || ""
+    ]
+    advertised = advertised_credential_header(header)
+    hmac_input << advertised if advertised
+    hmac_input << opaque_b64
+    hmac_input = hmac_input.join("|")
 
     mac = OpenSSL::HMAC.digest("SHA256", secret_key.encode(Encoding::UTF_8), hmac_input.encode(Encoding::UTF_8))
     Base64.urlsafe_encode64(mac, padding: false)
   end
 
+  # True when the credential header is omitted or is the implicit Authorization default.
+  sig { params(header: T.untyped).returns(T::Boolean) }
+  def default_credential_header?(header)
+    header.nil? || header.to_s.empty? || header.to_s.casecmp(AUTHORIZATION_HEADER).zero?
+  end
+
+  # Returns an advertised credential header, or nil for the Authorization default.
+  sig { params(header: T.untyped).returns(T.nilable(String)) }
+  def advertised_credential_header(header)
+    return nil if default_credential_header?(header)
+
+    name = header.to_s
+    Kernel.raise ArgumentError, "Invalid HTTP header name" unless HTTP_HEADER_NAME_RE.match?(name)
+    name
+  end
+
   # Encode string to base64url without padding.
   sig { params(data: T.untyped).returns(String) }
   def b64url_encode(data)

data/lib/mpp/client/transport.rb

@@ -117,7 +117,7 @@ module Mpp
           raise
         end
 
-        retry_headers = headers.merge("Authorization" => auth_header)
+        retry_headers = headers.merge(challenge.credential_header => auth_header)
         payment_response = nil
         begin
           payment_response = send_request(uri, method, retry_headers, body)

data/lib/mpp/errors.rb

@@ -30,6 +30,7 @@ module Mpp
       end
       subclass.instance_variable_set(:@title, to_title(name)) unless subclass.instance_variable_defined?(:@title)
       subclass.instance_variable_set(:@status, 402) unless subclass.instance_variable_defined?(:@status)
+      subclass.instance_variable_set(:@hint, nil) unless subclass.instance_variable_defined?(:@hint)
     end
 
     class << self
@@ -44,6 +45,9 @@ module Mpp
       sig { returns(T.nilable(String)) }
       attr_reader :title
 
+      sig { returns(T.nilable(String)) }
+      attr_reader :hint
+
       private
 
       sig { params(name: String).returns(String) }
@@ -60,6 +64,7 @@ module Mpp
     @status = T.let(402, Integer)
     @type = T.let("#{BASE_URI}/payment-error", String)
     @title = T.let("Payment Error", String)
+    @hint = T.let(nil, T.nilable(String))
 
     sig { returns(T.untyped) }
     def status = self.class.status
@@ -67,6 +72,8 @@ module Mpp
     def type = self.class.type
     sig { returns(T.untyped) }
     def title = self.class.title
+    sig { returns(T.untyped) }
+    def hint = self.class.hint
 
     # Convert to RFC 9457 Problem Details format.
     sig { params(challenge_id: T.untyped).returns(T::Hash[T.untyped, T.untyped]) }
@@ -77,14 +84,26 @@ module Mpp
         "status" => status,
         "detail" => message
       }
+      details["hint"] = hint if hint
       details["challengeId"] = challenge_id if challenge_id
       details
     end
   end
 
+  # Default hint messages for payment errors.
+  module Hints
+    PAYMENT_REQUIRED = "Use a supported wallet to pay for this resource using one of the supported " \
+      "payment methods returned in the WWW-Authenticate header. See https://mpp.dev/tools/wallet.md"
+    MALFORMED_CREDENTIAL = "Use a supported wallet to construct valid credentials for one of the supported " \
+      "payment methods returned in the WWW-Authenticate header. See https://mpp.dev/tools/wallet.md"
+    METHOD_UNSUPPORTED = PAYMENT_REQUIRED
+  end
+
   class PaymentRequiredError < PaymentError
     extend T::Sig
 
+    @hint = T.let(Hints::PAYMENT_REQUIRED, T.nilable(String))
+
     sig { params(realm: T.untyped, description: T.untyped).void }
     def initialize(realm: nil, description: nil)
       parts = ["Payment is required"]
@@ -97,6 +116,8 @@ module Mpp
   class MalformedCredentialError < PaymentError
     extend T::Sig
 
+    @hint = T.let(Hints::MALFORMED_CREDENTIAL, T.nilable(String))
+
     sig { params(reason: T.untyped).void }
     def initialize(reason: nil)
       msg = reason ? "Credential is malformed: #{reason}." : "Credential is malformed."
@@ -173,6 +194,7 @@ module Mpp
     @status = T.let(400, Integer)
     @type = T.let("#{BASE_URI}/method-unsupported", String)
     @title = T.let("Method Unsupported", String)
+    @hint = T.let(Hints::METHOD_UNSUPPORTED, T.nilable(String))
 
     sig { params(method: T.untyped).void }
     def initialize(method: nil)

data/lib/mpp/http/headers.rb

@@ -0,0 +1,61 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Mpp
+  module Http
+    # Shared `{url:, headers:}` helpers used by the x402 facilitator and Tempo
+    # fee-payer and relay HTTP clients.
+    #
+    # `headers` may be:
+    #   * a Hash of static header names/values
+    #   * a zero-arity proc returning that Hash
+    #   * a proc receiving the request path (or JSON-RPC method) and returning
+    #     that Hash
+    #   * a nested Hash keyed by operation (`"verify"`, `"broadcast"`, …)
+    module Headers
+      extend T::Sig
+
+      module_function
+
+      sig { params(url: T.untyped).returns(String) }
+      def normalize_base_url(url)
+        base = url.to_s
+        base = base.chomp("/") while base.end_with?("/")
+        base
+      end
+
+      sig { params(config: T::Hash[T.untyped, T.untyped]).returns(T::Hash[Symbol, T.untyped]) }
+      def symbolize(config)
+        config.each_with_object({}) do |(key, value), acc|
+          acc[key.to_sym] = value
+        end
+      end
+
+      sig { params(headers: T.nilable(T::Hash[T.untyped, T.untyped])).returns(T::Hash[String, String]) }
+      def stringify(headers)
+        return {} if headers.nil?
+
+        headers.each_with_object({}) do |(key, value), acc|
+          acc[key.to_s] = value.to_s
+        end
+      end
+
+      sig { params(source: T.untyped, path: String).returns(T::Hash[String, String]) }
+      def resolve(source, path)
+        return {} if source.nil?
+
+        if source.respond_to?(:call)
+          arity = source.respond_to?(:arity) ? source.arity : 1
+          source = (arity == 0) ? source.call : source.call(path)
+        end
+        return {} unless source.is_a?(Hash)
+
+        operation = path.to_s.delete_prefix("/")
+        last = T.let(operation.split("/").last, T.nilable(String))
+        keyed = source[operation] || source[operation.to_sym]
+        keyed ||= source[last] || source[last.to_sym] if last && last != operation
+        stringify(keyed.is_a?(Hash) ? keyed : source)
+      end
+    end
+  end
+end

data/lib/mpp/http.rb

@@ -0,0 +1,8 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Mpp
+  module Http
+    autoload :Headers, "mpp/http/headers"
+  end
+end

data/lib/mpp/methods/evm/assets.rb

@@ -0,0 +1,103 @@
+# typed: true
+# frozen_string_literal: true
+
+module Mpp
+  module Methods
+    module Evm
+      # Known EIP-3009 assets plus helpers to resolve a currency config.
+      module Assets
+        Asset = Struct.new(:address, :decimals, :chain_id, :name, :version, keyword_init: true) do
+          def network
+            "eip155:#{chain_id}"
+          end
+        end
+
+        def self.hex_address(*chunks)
+          "0x#{chunks.join}"
+        end
+
+        BASE_USDC = Asset.new(
+          address: hex_address("833589fCD6eDb6E08f", "4c7C32D4f71b54bdA02913"),
+          decimals: 6,
+          chain_id: 8453,
+          name: "USD Coin",
+          version: "2"
+        )
+        BASE_SEPOLIA_USDC = Asset.new(
+          address: hex_address("036CbD53842c542663", "4e7929541eC2318f3dCF7e"),
+          decimals: 6,
+          chain_id: 84532,
+          name: "USDC",
+          version: "2"
+        )
+        CELO_USDC = Asset.new(
+          address: hex_address("cebA9300f2b948710d", "2653dD7B07f33A8B32118C"),
+          decimals: 6,
+          chain_id: 42220,
+          name: "USDC",
+          version: "2"
+        )
+        CELO_USDT = Asset.new(
+          address: hex_address("48065fbBE25f71C928", "2ddf5e1cD6D6A887483D5e"),
+          decimals: 6,
+          chain_id: 42220,
+          name: "Tether USD",
+          version: "1"
+        )
+        CELO_SEPOLIA_USDC = Asset.new(
+          address: hex_address("01C5C0122039549AD1", "493B8220cABEdD739BC44E"),
+          decimals: 6,
+          chain_id: 11142220,
+          name: "USDC",
+          version: "2"
+        )
+
+        private_class_method :hex_address
+
+        module_function
+
+        def resolve(currency, authorization: nil, chain_id: nil, decimals: nil)
+          if currency.is_a?(Asset)
+            auth = authorization_hash(authorization) || {"name" => currency.name, "version" => currency.version}
+            return {
+              address: checksum(currency.address),
+              chain_id: chain_id || currency.chain_id,
+              decimals: decimals || currency.decimals,
+              authorization: auth
+            }
+          end
+
+          address = currency.to_s
+          Kernel.raise ArgumentError, "EVM currency must be a known asset or 0x-prefixed address" unless address.match?(/\A0x[a-fA-F0-9]{40}\z/)
+          Kernel.raise ArgumentError, "EVM authorization requires `chain_id`." if chain_id.nil?
+          Kernel.raise ArgumentError, "EVM authorization requires `decimals`." if decimals.nil?
+
+          auth = authorization_hash(authorization)
+          Kernel.raise ArgumentError, "EVM authorization requires `authorization` metadata." unless auth
+
+          {
+            address: checksum(address),
+            chain_id: Kernel.Integer(chain_id),
+            decimals: Kernel.Integer(decimals),
+            authorization: auth
+          }
+        end
+
+        def checksum(address)
+          Authorization.checksum_address(address)
+        end
+
+        def authorization_hash(authorization)
+          return nil if authorization.nil?
+
+          name = authorization[:name] || authorization["name"]
+          version = authorization[:version] || authorization["version"]
+          Kernel.raise ArgumentError, "authorization requires name and version" if name.to_s.empty? || version.to_s.empty?
+
+          {"name" => name.to_s, "version" => version.to_s}
+        end
+        private_class_method :authorization_hash
+      end
+    end
+  end
+end