mpp-rb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ca67d74a92976b39f4bb8ce28a4fc46bd87d1cc0fdfcc5978681760a05e1231b
+  data.tar.gz: 63526c4eff0144dfe35c1a722161a23173ecb8a94cc087efb98f8cb7e8f4f8b9
+SHA512:
+  metadata.gz: 37d08450e62ad4b411f52caddd71d403b0c78d861a596f4081b6e45705881612fc81ad085675a4a2cdde67174283af1b86eddce7fa1dd6a5f70827bede94749d
+  data.tar.gz: 8f0e2042ca49bc3c7ae54d6e79ff6276ac807d5e65111d83f2de012ee0680c75bac1452c3c70afdcfe2dd02d73f20fe229bc633cb892021a6bb4be0798edec19

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stripe, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,133 @@
+# mpp-rb
+
+Ruby SDK for the [**Machine Payments Protocol**](https://mpp.dev)
+
+[![Gem Version](https://img.shields.io/gem/v/mpp.svg)](https://rubygems.org/gems/mpp-rb)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+## Documentation
+
+Full documentation, API reference, and guides are available at **[mpp.dev/sdk/ruby](https://mpp.dev/sdk/ruby)**.
+
+## Install
+
+```bash
+gem install mpp-rb
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem "mpp-rb"
+```
+
+## Quick Start
+
+### Server
+
+```ruby
+require "mpp-rb"
+
+server = Mpp.create(
+  method: Mpp::Methods::Tempo.tempo(
+    intents: {"charge" => Mpp::Methods::Tempo::ChargeIntent.new},
+    recipient: "0x0000000000000000000000000000000000000001",
+  ),
+)
+
+# In your request handler (Sinatra, Rails, Rack, etc.)
+result = server.charge(authorization_header, "0.50", description: "Paid endpoint")
+
+if result.is_a?(Mpp::Challenge)
+  # Return 402 with WWW-Authenticate header
+  resp = Mpp::Server::Decorator.make_challenge_response(result, server.realm)
+  # resp["status"], resp["headers"], resp["body"]
+else
+  credential, receipt = result
+  # credential.source — payer address
+  # receipt.to_payment_receipt — Payment-Receipt header value
+end
+```
+
+### Client
+
+```ruby
+require "mpp-rb"
+
+account = Mpp::Methods::Tempo::Account.from_key("0x...")
+
+transport = Mpp::Client::Transport.new(
+  methods: [
+    Mpp::Methods::Tempo.tempo(
+      account: account,
+      intents: {"charge" => Mpp::Methods::Tempo::ChargeIntent.new},
+    ),
+  ],
+)
+
+response = transport.request(:get, "https://mpp.dev/api/ping/paid")
+```
+
+### Rack Middleware
+
+```ruby
+require "mpp-rb"
+
+handler = Mpp.create(
+  method: Mpp::Methods::Tempo.tempo(
+    intents: {"charge" => Mpp::Methods::Tempo::ChargeIntent.new},
+    recipient: "0x0000000000000000000000000000000000000001",
+  ),
+)
+
+# In your config.ru or Rails middleware stack:
+use Mpp::Server::Middleware, handler: handler
+
+# In your app, signal that payment is required:
+env["mpp.charge"] = { amount: "0.50", description: "Paid endpoint" }
+```
+
+## Examples
+
+| Example | Description |
+|---------|-------------|
+| [tempo_charge](./examples/tempo_charge/) | Tempo testnet payments via Sinatra |
+| [stripe_charge](./examples/stripe_charge/) | Stripe payments via Shared Payment Tokens |
+
+Each example is a standalone Sinatra app with `/free` and `/paid` endpoints. To run one:
+
+```sh
+cd examples/tempo_charge
+bundle install
+ruby app.rb
+```
+
+Then test with [mppx](https://www.npmjs.com/package/mppx), a CLI that handles the full 402 challenge/credential flow:
+
+```sh
+npx mppx http://localhost:4567/paid
+```
+
+## Support Matrix
+
+| Method | Charge Client | Charge Server |
+|--------|---------------|---------------|
+| Tempo | Yes | Yes |
+| Stripe | Yes | Yes |
+
+Tempo charge transaction construction is implemented directly in Ruby. Optional dependencies: `eth` (account signing) and `rlp` (fee payer envelope).
+
+## Protocol
+
+Built on the ["Payment" HTTP Authentication Scheme](https://datatracker.ietf.org/doc/draft-ryan-httpauth-payment/). See [mpp-specs](https://tempoxyz.github.io/mpp-specs/) for the full specification.
+
+## Releasing
+
+1. Update the version in `lib/mpp/version.rb`
+2. Commit: `git commit -am "v0.x.x"`
+3. Tag: `git tag v0.x.x`
+4. Push: `git push origin main --tags`
+
+## License
+
+MIT

data/lib/mpp/body_digest.rb

@@ -0,0 +1,37 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "openssl"
+require "base64"
+require "json"
+
+module Mpp
+  module BodyDigest
+    extend T::Sig
+
+    module_function
+
+    # Compute a SHA-256 digest of a request body.
+    # Returns: "sha-256=<base64>"
+    sig { params(body: T.untyped).returns(String) }
+    def compute(body)
+      case body
+      when Hash
+        body = Mpp::Json.compact_encode(body)
+      when String
+        # use as-is
+      end
+      body = body.encode(Encoding::UTF_8) if body.is_a?(String)
+      digest = OpenSSL::Digest::SHA256.digest(body)
+      encoded = Base64.strict_encode64(digest)
+      "sha-256=#{encoded}"
+    end
+
+    # Verify a body digest matches the expected value.
+    sig { params(digest: String, body: T.untyped).returns(T::Boolean) }
+    def verify(digest, body)
+      expected = compute(body)
+      Mpp.secure_compare(expected, digest)
+    end
+  end
+end

data/lib/mpp/challenge.rb

@@ -0,0 +1,115 @@
+# typed: true
+# frozen_string_literal: true
+
+require_relative "challenge_id"
+require_relative "secure_compare"
+require_relative "json"
+
+module Mpp
+  Challenge = Data.define(
+    :id,
+    :method,
+    :intent,
+    :request,
+    :realm,
+    :request_b64,
+    :digest,
+    :expires,
+    :description,
+    :opaque
+  ) do
+    def initialize(id:, method:, intent:, request:, realm: "", request_b64: "", digest: nil, expires: nil,
+      description: nil, opaque: nil)
+      super
+    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)
+      challenge_id = Mpp.generate_challenge_id(
+        secret_key: secret_key,
+        realm: realm,
+        method: method,
+        intent: intent,
+        request: request,
+        expires: expires,
+        digest: digest,
+        opaque: meta
+      )
+      request_json = Mpp::Json.compact_encode(request)
+      request_b64 = Mpp.b64url_encode(request_json)
+
+      new(
+        id: challenge_id,
+        method: method,
+        intent: intent,
+        request: request,
+        realm: realm,
+        request_b64: request_b64,
+        digest: digest,
+        expires: expires,
+        description: description,
+        opaque: meta
+      )
+    end
+
+    # Parse a Challenge from a WWW-Authenticate header value.
+    def self.from_www_authenticate(header)
+      Mpp::Parsing.parse_www_authenticate(header)
+    end
+
+    # Parse multiple Payment challenges from a merged WWW-Authenticate header.
+    # Handles RFC 9110 §11.6.1 comma-separated authentication schemes.
+    def self.from_www_authenticate_list(header)
+      indices = []
+      header.scan(/Payment\s+/i) { indices << T.must(Regexp.last_match).begin(0) }
+      return [] if indices.empty?
+
+      indices.each_with_index.map do |start_idx, i|
+        end_idx = (i + 1 < indices.length) ? indices[i + 1] : header.length
+        chunk = T.must(header[start_idx...end_idx]).sub(/,\s*$/, "")
+        from_www_authenticate(chunk)
+      end
+    end
+
+    # Serialize to a WWW-Authenticate header value.
+    def to_www_authenticate(realm)
+      Mpp::Parsing.format_www_authenticate(self, realm)
+    end
+
+    # Verify the challenge ID matches the expected HMAC.
+    def verify(secret_key, realm)
+      expected_id = Mpp.generate_challenge_id(
+        secret_key: secret_key,
+        realm: realm,
+        method: method,
+        intent: intent,
+        request: request,
+        expires: expires,
+        digest: digest,
+        opaque: opaque
+      )
+      Mpp.secure_compare(id, expected_id)
+    end
+
+    # Create a ChallengeEcho for use in credentials.
+    def to_echo
+      opaque_b64 = nil
+      if opaque
+        opaque_json = Mpp::Json.compact_encode(opaque)
+        opaque_b64 = Mpp.b64url_encode(opaque_json)
+      end
+
+      ChallengeEcho.new(
+        id: id,
+        realm: realm,
+        method: method,
+        intent: intent,
+        request: request_b64,
+        expires: expires,
+        digest: digest,
+        opaque: opaque_b64
+      )
+    end
+  end
+end

data/lib/mpp/challenge_echo.rb

@@ -0,0 +1,19 @@
+# typed: false
+# frozen_string_literal: true
+
+module Mpp
+  ChallengeEcho = Data.define(
+    :id,
+    :realm,
+    :method,
+    :intent,
+    :request,
+    :expires,
+    :digest,
+    :opaque
+  ) do
+    def initialize(id:, realm:, method:, intent:, request:, expires: nil, digest: nil, opaque: nil)
+      super
+    end
+  end
+end

data/lib/mpp/challenge_id.rb

@@ -0,0 +1,54 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "openssl"
+require "base64"
+
+module Mpp
+  extend T::Sig
+
+  module_function
+
+  # 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.
+  # 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)
+    request_json = Json.compact_encode(request)
+    request_b64 = b64url_encode(request_json)
+
+    opaque_b64 = if opaque
+      opaque_json = Json.compact_encode(opaque)
+      b64url_encode(opaque_json)
+    else
+      ""
+    end
+
+    hmac_input = [
+      realm,
+      method,
+      intent,
+      request_b64,
+      expires || "",
+      digest || "",
+      opaque_b64
+    ].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
+
+  # Encode string to base64url without padding.
+  sig { params(data: T.untyped).returns(String) }
+  def b64url_encode(data)
+    Base64.urlsafe_encode64(data.encode(Encoding::UTF_8), padding: false)
+  end
+
+  # Encode bytes to base64url without padding.
+  sig { params(data: String).returns(String) }
+  def b64url_encode_bytes(data)
+    Base64.urlsafe_encode64(data, padding: false)
+  end
+end

data/lib/mpp/client/transport.rb

@@ -0,0 +1,137 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require "time"
+
+module Mpp
+  module Client
+    # Payment-aware HTTP client that handles 402 Payment Required responses.
+    #
+    # Wraps Net::HTTP and automatically:
+    # 1. Detects 402 responses with WWW-Authenticate: Payment headers
+    # 2. Parses the challenge and finds a matching payment method
+    # 3. Creates credentials and retries the request
+    # 4. Returns the final response
+    class Transport
+      extend T::Sig
+
+      sig { params(methods: T::Array[T.untyped]).void }
+      def initialize(methods:)
+        @methods = T.let(methods.to_h { |m| [m.name, m] }, T::Hash[String, T.untyped])
+      end
+
+      # Send an HTTP request with automatic 402 payment handling.
+      # Returns [Net::HTTPResponse, body_string].
+      sig { params(method: T.untyped, url: T.any(URI::Generic, String), headers: T.untyped, body: T.untyped).returns(T.untyped) }
+      def request(method, url, headers: {}, body: nil)
+        uri = URI(url)
+        response = send_request(uri, method, headers, body)
+
+        return response unless response.code.to_i == 402
+
+        # Parse WWW-Authenticate headers
+        www_auth_headers = response.get_fields("www-authenticate") || []
+        challenge, matched_method = find_matching_challenge(www_auth_headers)
+        return response unless challenge && matched_method
+
+        # Check expiry before paying (client-side guardrail)
+        if challenge.expires
+          begin
+            expires_dt = Time.iso8601(challenge.expires.gsub("Z", "+00:00"))
+            return response if expires_dt < Time.now.utc
+          rescue ArgumentError
+            # If we can't parse, let server validate
+          end
+        end
+
+        credential = matched_method.create_credential(challenge)
+        auth_header = credential.to_authorization
+
+        retry_headers = headers.merge("Authorization" => auth_header)
+        send_request(uri, method, retry_headers, body)
+      end
+
+      sig { params(url: T.any(URI::Generic, String), kwargs: T.untyped).returns(T.untyped) }
+      def get(url, **kwargs)
+        request("GET", url, **kwargs)
+      end
+
+      sig { params(url: T.any(URI::Generic, String), kwargs: T.untyped).returns(T.untyped) }
+      def post(url, **kwargs)
+        request("POST", url, **kwargs)
+      end
+
+      sig { params(url: T.any(URI::Generic, String), kwargs: T.untyped).returns(T.untyped) }
+      def put(url, **kwargs)
+        request("PUT", url, **kwargs)
+      end
+
+      sig { params(url: T.any(URI::Generic, String), kwargs: T.untyped).returns(T.untyped) }
+      def delete(url, **kwargs)
+        request("DELETE", url, **kwargs)
+      end
+
+      private
+
+      sig { params(uri: URI::Generic, method: T.untyped, headers: T::Hash[String, String], body: T.nilable(String)).returns(Net::HTTPResponse) }
+      def send_request(uri, method, headers, body)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+
+        request_class = case method.to_s.upcase
+        when "GET" then Net::HTTP::Get
+        when "POST" then Net::HTTP::Post
+        when "PUT" then Net::HTTP::Put
+        when "DELETE" then Net::HTTP::Delete
+        when "PATCH" then Net::HTTP::Patch
+        else raise ArgumentError, "Unsupported HTTP method: #{method}"
+        end
+
+        req = request_class.new(uri)
+        headers.each { |k, v| req[k] = v }
+        req.body = body if body
+
+        http.request(req)
+      end
+
+      sig { params(www_auth_headers: T.untyped).returns(T::Array[T.untyped]) }
+      def find_matching_challenge(www_auth_headers)
+        www_auth_headers.each do |header|
+          next unless header.downcase.start_with?("payment ")
+
+          begin
+            parsed = Mpp::Challenge.from_www_authenticate(header)
+            return [parsed, @methods[parsed.method]] if @methods.key?(parsed.method)
+          rescue Mpp::ParseError
+            next
+          end
+        end
+        [nil, nil]
+      end
+    end
+
+    # Module-level convenience methods
+    extend T::Sig
+
+    module_function
+
+    sig { params(method: T.untyped, url: T.untyped, methods: T::Array[T.untyped], kwargs: T.untyped).returns(T.untyped) }
+    def request(method, url, methods:, **kwargs)
+      transport = Transport.new(methods: methods)
+      transport.request(method, url, **kwargs)
+    end
+
+    sig { params(url: T.untyped, methods: T::Array[T.untyped], kwargs: T.untyped).returns(T.untyped) }
+    def get(url, methods:, **kwargs)
+      request("GET", url, **T.unsafe({methods: methods, **kwargs}))
+    end
+
+    sig { params(url: T.untyped, methods: T::Array[T.untyped], kwargs: T.untyped).returns(T.untyped) }
+    def post(url, methods:, **kwargs)
+      request("POST", url, **T.unsafe({methods: methods, **kwargs}))
+    end
+  end
+end

data/lib/mpp/client.rb

@@ -0,0 +1,9 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "client/transport"
+
+module Mpp
+  module Client
+  end
+end

data/lib/mpp/credential.rb

@@ -0,0 +1,20 @@
+# typed: true
+# frozen_string_literal: true
+
+module Mpp
+  Credential = Data.define(:challenge, :payload, :source) do
+    def initialize(challenge:, payload:, source: nil)
+      super
+    end
+
+    # Parse a Credential from an Authorization header value.
+    def self.from_authorization(header)
+      Mpp::Parsing.parse_authorization(header)
+    end
+
+    # Serialize to an Authorization header value.
+    def to_authorization
+      Mpp::Parsing.format_authorization(self)
+    end
+  end
+end