mppx 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d92f36a4729fc57e8a72788d5b67b53945692f399654c4167b57b9686a22d75a
+  data.tar.gz: 7eeb66bf6bc9807f30d38b0816f5d85ce088a3bee282b57b1a008f0a637f35f8
+SHA512:
+  metadata.gz: 2861beda451ae26de90d3b013c8a4404098e83da91bd2746d3e54a9f2cd92652e6777b1d1ed031fe95c35fd4d08d284fb49b73712c0190f16d65c207a08cc378
+  data.tar.gz: e82ae5aefa538ce07ff18bd69e727cdc28e70e4df25c7a428cca221cc8f55e059d33b20b8d7dc68d35ec3fbb2dc52c0af75f45158727b08c087c2e16950fc451

data/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2025 CJ Avilla
+
+This project is a Ruby port of the official MPP SDK (https://github.com/mppx/mppx),
+originally created by the MPP team. All credit for the protocol design and original
+implementation belongs to the original authors.
+
+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 @@
+# mppx
+
+Ruby SDK for the [Machine Payments Protocol](https://paymentauth.org) (MPP). Implements the Payment HTTP Authentication Scheme (HTTP 402) for payment-gated APIs.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "mppx"
+```
+
+Then run:
+
+```sh
+bundle install
+```
+
+Or install directly:
+
+```sh
+gem install mppx
+```
+
+## Quick Start
+
+### Server: Protect an endpoint with payment gating
+
+```ruby
+require "mppx"
+
+# Define a payment method with name, intent, and schema
+method = Mppx::Method.from(
+  name: "tempo",
+  intent: "charge",
+  schema: {
+    request: ->(r) { r },
+    credential: { payload: ->(p) { p } }
+  }
+)
+
+# Configure the server method with a verification callback
+server_method = Mppx::Method.to_server(method,
+  verify: ->(credential:, request:) {
+    # Verify the payment and return receipt data
+    Mppx::Receipt.from(
+      method: "tempo",
+      reference: "tx_123",
+      status: "success",
+      timestamp: Time.now.utc.iso8601
+    )
+  }
+)
+
+# Create a handler
+handler = Mppx::Server::Handler.create(
+  methods: [server_method],
+  secret_key: ENV["MPP_SECRET_KEY"],
+  realm: "My API"
+)
+```
+
+### Server: Rack middleware
+
+```ruby
+# In your Rack app or Rails config
+use Mppx::Server::Middleware,
+  handler: handler,
+  method_key: "charge",
+  options: { amount: "0.01", currency: "USD" }
+```
+
+### Client: Build and send a credential
+
+```ruby
+# Parse the 402 challenge from response headers
+challenge = Mppx::Challenge.from_headers(response_headers)
+
+# Create a credential with payment proof
+credential = Mppx::Credential.from(
+  challenge: challenge,
+  payload: { transaction_hash: "0xabc..." }
+)
+
+# Serialize for the Authorization header
+auth_header = Mppx::Credential.serialize(credential)
+# => "Payment eyJjaGFsbGVuZ2U..."
+```
+
+### Parse a receipt
+
+```ruby
+receipt = Mppx::Receipt.from_response(response_headers)
+# => { method: "tempo", reference: "tx_123", status: "success", timestamp: "..." }
+```
+
+## Modules
+
+| Module | Purpose |
+|--------|---------|
+| `Mppx::Challenge` | Create, serialize, deserialize, and verify 402 challenges |
+| `Mppx::Credential` | Build and parse `Authorization: Payment ...` credentials |
+| `Mppx::Receipt` | Create and parse `Payment-Receipt` headers |
+| `Mppx::PaymentRequest` | Serialize/deserialize payment request objects |
+| `Mppx::Method` | Define payment methods with schemas for client and server use |
+| `Mppx::Store` | Pluggable key-value stores (in-memory, Redis) |
+| `Mppx::Server::Handler` | Server-side handler that validates credentials and issues challenges |
+| `Mppx::Server::Transport` | HTTP transport layer for challenge/receipt responses |
+| `Mppx::Server::Middleware` | Rack middleware for payment gating |
+| `Mppx::BodyDigest` | SHA-256 body digest computation and verification |
+| `Mppx::Errors` | Structured error types following RFC 9457 Problem Details |
+
+## Configuration
+
+The handler reads these environment variables:
+
+- `MPP_SECRET_KEY` - HMAC secret for signing challenges (required unless passed directly)
+- `MPP_REALM` - Default realm for challenges (optional)
+
+## Development
+
+```sh
+bundle install
+bundle exec rake spec
+```
+
+## Requirements
+
+- Ruby >= 3.1
+
+## License
+
+MIT

data/lib/mppx/base64url.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module Mppx
+  module Base64Url
+    module_function
+
+    def encode(data)
+      Base64.urlsafe_encode64(data, padding: false)
+    end
+
+    def decode(data)
+      # Add padding if needed
+      padded = case data.length % 4
+               when 2 then "#{data}=="
+               when 3 then "#{data}="
+               else data
+               end
+      Base64.urlsafe_decode64(padded)
+    end
+  end
+end

data/lib/mppx/body_digest.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "base64"
+require "json"
+
+module Mppx
+  module BodyDigest
+    module_function
+
+    def compute(body)
+      str = body.is_a?(Hash) ? JSON.generate(body) : body
+      hash = OpenSSL::Digest::SHA256.digest(str)
+      "sha-256=#{Base64.strict_encode64(hash)}"
+    end
+
+    def verify(digest, body)
+      ConstantTimeEqual.call(compute(body), digest)
+    end
+  end
+end

data/lib/mppx/canonical_json.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Mppx
+  module CanonicalJson
+    module_function
+
+    def canonicalize(obj)
+      JSON.generate(deep_sort(obj))
+    end
+
+    def deep_sort(obj)
+      case obj
+      when Hash
+        obj.keys.sort.each_with_object({}) do |key, sorted|
+          sorted[key] = deep_sort(obj[key])
+        end
+      when Array
+        obj.map { |item| deep_sort(item) }
+      else
+        obj
+      end
+    end
+  end
+end

data/lib/mppx/challenge.rb

@@ -0,0 +1,276 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "json"
+
+module Mppx
+  module Challenge
+    METHOD_PATTERN = /\A[a-z][a-z0-9:_-]*\z/
+
+    module_function
+
+    def from(params)
+      secret_key = params[:secret_key]
+      meta = params[:meta]
+
+      challenge = {
+        realm: params[:realm],
+        method: params[:method],
+        intent: params[:intent],
+        request: params[:request]
+      }
+      challenge[:description] = params[:description] if params[:description]
+      challenge[:digest] = params[:digest] if params[:digest]
+      challenge[:expires] = params[:expires] if params[:expires]
+      challenge[:opaque] = meta if meta
+
+      challenge[:id] = if secret_key
+                         compute_id(challenge, secret_key)
+                       else
+                         params[:id]
+                       end
+
+      challenge
+    end
+
+    def from_method(method, params)
+      request = PaymentRequest.from_method(method, params[:request])
+
+      from(
+        id: params[:id],
+        secret_key: params[:secret_key],
+        realm: params[:realm],
+        method: method[:name],
+        intent: method[:intent],
+        request: request,
+        description: params[:description],
+        digest: params[:digest],
+        expires: params[:expires],
+        meta: params[:meta]
+      )
+    end
+
+    def serialize(challenge)
+      parts = [
+        "id=\"#{challenge[:id]}\"",
+        "realm=\"#{challenge[:realm]}\"",
+        "method=\"#{challenge[:method]}\"",
+        "intent=\"#{challenge[:intent]}\"",
+        "request=\"#{PaymentRequest.serialize(challenge[:request])}\""
+      ]
+
+      parts << "description=\"#{challenge[:description]}\"" if challenge[:description]
+      parts << "digest=\"#{challenge[:digest]}\"" if challenge[:digest]
+      parts << "expires=\"#{challenge[:expires]}\"" if challenge[:expires]
+      parts << "opaque=\"#{PaymentRequest.serialize(challenge[:opaque])}\"" if challenge[:opaque]
+
+      "Payment #{parts.join(", ")}"
+    end
+
+    def deserialize(value)
+      params_str = extract_payment_auth_params(value)
+      raise "Missing Payment scheme." unless params_str
+
+      result = parse_auth_params(params_str)
+
+      request_encoded = result.delete("request")
+      raise "Missing request parameter." unless request_encoded
+
+      method_name = result["method"]
+      if method_name && !METHOD_PATTERN.match?(method_name)
+        raise "Invalid method: \"#{method_name}\". Must be lowercase per spec."
+      end
+
+      opaque_encoded = result.delete("opaque")
+
+      challenge = {
+        id: result["id"],
+        realm: result["realm"],
+        method: result["method"],
+        intent: result["intent"],
+        request: PaymentRequest.deserialize(request_encoded)
+      }
+      challenge[:description] = result["description"] if result["description"]
+      challenge[:digest] = result["digest"] if result["digest"]
+      challenge[:expires] = result["expires"] if result["expires"]
+      challenge[:opaque] = PaymentRequest.deserialize(opaque_encoded) if opaque_encoded
+
+      challenge
+    end
+
+    def deserialize_list(value)
+      starts = []
+      value.scan(/Payment\s+/i) do
+        starts << Regexp.last_match.begin(0)
+      end
+      raise "No Payment schemes found." if starts.empty?
+
+      starts.each_with_index.map do |start, i|
+        end_pos = i + 1 < starts.length ? starts[i + 1] : value.length
+        chunk = value[start...end_pos].sub(/,\s*\z/, "")
+        deserialize(chunk)
+      end
+    end
+
+    def from_headers(headers)
+      header = headers["WWW-Authenticate"] || headers["www-authenticate"]
+      raise "Missing WWW-Authenticate header." unless header
+
+      deserialize(header)
+    end
+
+    def from_response(status:, headers:)
+      raise "Response status is not 402." unless status == 402
+
+      from_headers(headers)
+    end
+
+    def verify(challenge, secret_key:)
+      expected_id = compute_id(challenge, secret_key)
+      ConstantTimeEqual.call(challenge[:id], expected_id)
+    end
+
+    def meta(challenge)
+      challenge[:opaque]
+    end
+
+    # @private
+    def compute_id(challenge, secret_key)
+      input = [
+        challenge[:realm],
+        challenge[:method],
+        challenge[:intent],
+        PaymentRequest.serialize(challenge[:request]),
+        challenge[:expires] || "",
+        challenge[:digest] || "",
+        challenge[:opaque] ? PaymentRequest.serialize(challenge[:opaque]) : ""
+      ].join("|")
+
+      mac = OpenSSL::HMAC.digest("SHA256", secret_key, input)
+      Base64Url.encode(mac)
+    end
+
+    # @private - Extract Payment scheme from a multi-scheme WWW-Authenticate header
+    def extract_payment_auth_params(header)
+      token = "Payment"
+      in_quotes = false
+      escaped = false
+
+      header.length.times do |i|
+        char = header[i]
+
+        if in_quotes
+          if escaped
+            escaped = false
+          elsif char == "\\"
+            escaped = true
+          elsif char == '"'
+            in_quotes = false
+          end
+          next
+        end
+
+        if char == '"'
+          in_quotes = true
+          next
+        end
+
+        next unless starts_with_scheme_token?(header, i, token)
+
+        prefix = header[0...i]
+        next if prefix.strip.length > 0 && !prefix.rstrip.end_with?(",")
+
+        params_start = i + token.length
+        params_start += 1 while params_start < header.length && header[params_start] =~ /\s/
+        return header[params_start..]
+      end
+
+      nil
+    end
+
+    # @private
+    def starts_with_scheme_token?(value, index, token)
+      return false unless value[index..].downcase.start_with?(token.downcase)
+
+      next_char = value[index + token.length]
+      next_char && next_char =~ /\s/
+    end
+
+    # @private - Parse auth-params with support for escaped quoted-string values
+    def parse_auth_params(input)
+      result = {}
+      i = 0
+
+      while i < input.length
+        # Skip whitespace and commas
+        i += 1 while i < input.length && input[i] =~ /[\s,]/
+        break if i >= input.length
+
+        # Read key
+        key_start = i
+        i += 1 while i < input.length && input[i] =~ /[A-Za-z0-9_-]/
+        key = input[key_start...i]
+        raise "Malformed auth-param." if key.empty?
+
+        # Skip whitespace
+        i += 1 while i < input.length && input[i] =~ /\s/
+
+        # If no '=' after token, likely another auth scheme
+        break if input[i] != "="
+        i += 1
+
+        # Skip whitespace
+        i += 1 while i < input.length && input[i] =~ /\s/
+
+        # Read value
+        value, i = read_auth_param_value(input, i)
+
+        raise "Duplicate parameter: #{key}" if result.key?(key)
+
+        result[key] = value
+      end
+
+      result
+    end
+
+    # @private
+    def read_auth_param_value(input, start)
+      if input[start] == '"'
+        read_quoted_auth_param_value(input, start + 1)
+      else
+        i = start
+        i += 1 while i < input.length && input[i] != ","
+        [input[start...i].strip, i]
+      end
+    end
+
+    # @private
+    def read_quoted_auth_param_value(input, start)
+      i = start
+      value = +""
+      escaped = false
+
+      while i < input.length
+        char = input[i]
+        i += 1
+
+        if escaped
+          value << char
+          escaped = false
+          next
+        end
+
+        if char == "\\"
+          escaped = true
+          next
+        end
+
+        return [value, i] if char == '"'
+
+        value << char
+      end
+
+      raise "Unterminated quoted-string."
+    end
+  end
+end

data/lib/mppx/constant_time_equal.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Mppx
+  module ConstantTimeEqual
+    module_function
+
+    def call(a, b)
+      hash_a = OpenSSL::Digest::SHA256.hexdigest(a)
+      hash_b = OpenSSL::Digest::SHA256.hexdigest(b)
+      result = 0
+      hash_a.bytes.each_with_index do |byte, i|
+        result |= byte ^ hash_b.bytes[i]
+      end
+      result == 0
+    end
+  end
+end

data/lib/mppx/credential.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Mppx
+  module Credential
+    module_function
+
+    def from(challenge:, payload:, source: nil)
+      credential = {
+        challenge: challenge,
+        payload: payload
+      }
+      credential[:source] = source if source
+      credential
+    end
+
+    def serialize(credential)
+      wire = {
+        challenge: credential[:challenge].merge(
+          request: PaymentRequest.serialize(credential[:challenge][:request])
+        ),
+        payload: credential[:payload]
+      }
+      wire[:source] = credential[:source] if credential[:source]
+      json = JSON.generate(wire)
+      encoded = Base64Url.encode(json)
+      "Payment #{encoded}"
+    end
+
+    def deserialize(value)
+      match = value.match(/\APayment\s+(.+)\z/i)
+      raise "Missing Payment scheme." unless match
+
+      begin
+        json = Base64Url.decode(match[1])
+        parsed = JSON.parse(json)
+
+        challenge_data = parsed["challenge"]
+        request = PaymentRequest.deserialize(challenge_data["request"])
+
+        challenge = {
+          id: challenge_data["id"],
+          realm: challenge_data["realm"],
+          method: challenge_data["method"],
+          intent: challenge_data["intent"],
+          request: request
+        }
+        challenge[:description] = challenge_data["description"] if challenge_data["description"]
+        challenge[:digest] = challenge_data["digest"] if challenge_data["digest"]
+        challenge[:expires] = challenge_data["expires"] if challenge_data["expires"]
+        challenge[:opaque] = challenge_data["opaque"] if challenge_data["opaque"]
+
+        credential = {
+          challenge: challenge,
+          payload: parsed["payload"]
+        }
+        credential[:source] = parsed["source"] if parsed["source"]
+        credential
+      rescue StandardError
+        raise "Invalid base64url or JSON."
+      end
+    end
+
+    def from_request(request)
+      header = request[:headers]["Authorization"] || request[:headers]["HTTP_AUTHORIZATION"]
+      raise "Missing Authorization header." unless header
+
+      payment = extract_payment_scheme(header)
+      raise "Missing Payment scheme." unless payment
+
+      deserialize(payment)
+    end
+
+    def from_rack_request(env)
+      header = env["HTTP_AUTHORIZATION"]
+      raise "Missing Authorization header." unless header
+
+      payment = extract_payment_scheme(header)
+      raise "Missing Payment scheme." unless payment
+
+      deserialize(payment)
+    end
+
+    def extract_payment_scheme(header)
+      schemes = header.split(",").map(&:strip)
+      schemes.find { |s| s =~ /\APayment\s+/i }
+    end
+  end
+end

data/lib/mppx/env.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Mppx
+  module Env
+    VARIABLES = {
+      realm: %w[
+        FLY_APP_NAME
+        HEROKU_APP_NAME
+        HOST
+        HOSTNAME
+        MPP_REALM
+        RAILWAY_PUBLIC_DOMAIN
+        RENDER_EXTERNAL_HOSTNAME
+        VERCEL_URL
+        WEBSITE_HOSTNAME
+      ].freeze,
+      secret_key: %w[MPP_SECRET_KEY].freeze
+    }.freeze
+
+    DEFAULTS = {
+      realm: "MPP Payment"
+    }.freeze
+
+    module_function
+
+    def get(key)
+      vars = VARIABLES[key]
+      return nil unless vars
+
+      vars.each do |name|
+        value = ENV[name]
+        return value if value && !value.empty?
+      end
+
+      DEFAULTS[key]
+    end
+  end
+end