mpp-rb 0.1.0

data/lib/mpp/server/mpp_handler.rb

@@ -0,0 +1,97 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "method"
+
+module Mpp
+  module Server
+    DEFAULT_DECIMALS = 6
+
+    class MppHandler
+      extend T::Sig
+
+      sig { returns(T.untyped) }
+      attr_reader :method
+
+      sig { returns(String) }
+      attr_reader :realm
+
+      sig { returns(String) }
+      attr_reader :secret_key
+
+      sig { returns(T::Hash[String, T.untyped]) }
+      attr_reader :defaults
+
+      sig { params(method: T.untyped, realm: String, secret_key: String, defaults: T.nilable(T::Hash[String, T.untyped])).void }
+      def initialize(method:, realm:, secret_key:, defaults: nil)
+        @method = T.let(method, T.untyped)
+        @realm = T.let(realm, String)
+        @secret_key = T.let(secret_key, String)
+        @defaults = T.let(defaults || {}, T::Hash[String, T.untyped])
+      end
+
+      # Create with auto-detected realm and secret_key.
+      sig { params(method: T.untyped, realm: T.untyped, secret_key: T.untyped).returns(T.attached_class) }
+      def self.create(method:, realm: nil, secret_key: nil)
+        new(
+          method: method,
+          realm: realm || Defaults.detect_realm,
+          secret_key: secret_key || Defaults.detect_secret_key
+        )
+      end
+
+      # Handle a charge intent.
+      sig { params(authorization: T.nilable(String), amount: String, currency: T.nilable(String), recipient: T.nilable(String), expires: T.nilable(String), description: T.nilable(String), memo: T.nilable(String), fee_payer: T::Boolean, chain_id: T.nilable(Integer), extra: T.nilable(T::Hash[String, String])).returns(T.untyped) }
+      def charge(authorization, amount, currency: nil, recipient: nil, expires: nil,
+        description: nil, memo: nil, fee_payer: false, chain_id: nil, extra: nil)
+        intent = @method.intents["charge"]
+        raise ArgumentError, "Method #{@method.name} does not support charge intent" unless intent
+
+        resolved_currency = currency || (@method.respond_to?(:currency) ? @method.currency : nil)
+        resolved_recipient = recipient || (@method.respond_to?(:recipient) ? @method.recipient : nil)
+        raise ArgumentError, "currency must be set on the method or passed to charge()" unless resolved_currency
+        raise ArgumentError, "recipient must be set on the method or passed to charge()" unless resolved_recipient
+
+        decimals = @method.respond_to?(:decimals) ? @method.decimals : DEFAULT_DECIMALS
+        base_amount = Mpp::Units.parse_units(amount, decimals).to_s
+
+        request = {
+          "amount" => base_amount,
+          "currency" => resolved_currency,
+          "recipient" => resolved_recipient
+        }
+
+        if extra
+          extra.each do |k, v|
+            raise ArgumentError, "extra must be a dict[str, str]" unless k.is_a?(String) && v.is_a?(String)
+          end
+          request["extra"] = extra
+        end
+
+        resolved_chain_id = chain_id
+        resolved_chain_id ||= @method.chain_id if @method.respond_to?(:chain_id)
+
+        if memo || fee_payer || !resolved_chain_id.nil?
+          method_details = {}
+          method_details["chainId"] = resolved_chain_id unless resolved_chain_id.nil?
+          method_details["memo"] = memo if memo
+          method_details["feePayer"] = true if fee_payer
+          request["methodDetails"] = method_details
+        end
+
+        request = Mpp::Server::MethodHelper.transform_request(@method, request, nil)
+
+        Verify.verify_or_challenge(
+          authorization: authorization,
+          intent: intent,
+          request: request,
+          realm: @realm,
+          secret_key: @secret_key,
+          method: @method.name,
+          description: description,
+          expires: expires
+        )
+      end
+    end
+  end
+end

data/lib/mpp/server/verify.rb

@@ -0,0 +1,129 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "time"
+
+module Mpp
+  module Server
+    module Verify
+      extend T::Sig
+
+      DEFAULT_EXPIRES_MINUTES = 5
+
+      module_function
+
+      # Verify a payment credential or generate a new challenge.
+      #
+      # Returns Challenge (payment required) or [Credential, Receipt] (verified).
+      sig { params(authorization: T.nilable(String), intent: T.untyped, request: T::Hash[String, T.untyped], realm: String, secret_key: String, method: T.nilable(String), description: T.nilable(String), meta: T.nilable(T::Hash[String, T.untyped]), expires: T.nilable(String)).returns(T.untyped) }
+      def verify_or_challenge(authorization:, intent:, request:, realm:, secret_key:,
+        method: nil, description: nil, meta: nil, expires: nil)
+        method_name = method || "tempo"
+        request = Mpp::Units.transform_units(request)
+
+        new_challenge = Kernel.lambda {
+          create_challenge(method_name, intent.name, request, realm, secret_key, description, meta, expires)
+        }
+
+        return new_challenge.call if authorization.nil?
+
+        payment_scheme = extract_payment_scheme(authorization)
+        return new_challenge.call if payment_scheme.nil?
+
+        begin
+          credential = Mpp::Credential.from_authorization(payment_scheme)
+        rescue Mpp::ParseError
+          return new_challenge.call
+        end
+
+        # Stateless challenge verification
+        echo = credential.challenge
+        begin
+          echo_request = echo.request.empty? ? {} : Mpp::Parsing.b64_decode(echo.request)
+          echo_opaque = (echo.opaque && !T.must(echo.opaque).empty?) ? Mpp::Parsing.b64_decode(echo.opaque) : nil
+        rescue Mpp::ParseError
+          return new_challenge.call
+        end
+
+        expected_id = Mpp.generate_challenge_id(
+          secret_key: secret_key,
+          realm: echo.realm,
+          method: echo.method,
+          intent: echo.intent,
+          request: echo_request,
+          expires: echo.expires,
+          digest: echo.digest,
+          opaque: echo_opaque
+        )
+        return new_challenge.call unless Mpp.secure_compare(echo.id, expected_id)
+
+        # Assert echoed fields match server's values
+        return new_challenge.call unless echo.realm == realm && echo.method == method_name && echo.intent == intent.name
+
+        # Assert echoed request matches server's current request
+        return new_challenge.call unless echo_request == request
+
+        return new_challenge.call unless echo_opaque == meta
+
+        # Reject expired challenges as defense-in-depth
+        if echo.expires
+          begin
+            expires_dt = Time.iso8601(T.must(echo.expires).gsub("Z", "+00:00"))
+            return new_challenge.call if expires_dt < Time.now.utc
+          rescue ArgumentError
+            # If we can't parse, continue to stricter check below
+          end
+        end
+
+        # Verify echoed request parameters match endpoint's expected request
+        request.each do |key, value|
+          return new_challenge.call unless echo_request[key] == value
+        end
+
+        # Enforce challenge expiry - fail closed
+        return new_challenge.call unless echo.expires
+
+        begin
+          expires_dt = Time.iso8601(T.must(echo.expires).gsub("Z", "+00:00"))
+        rescue ArgumentError
+          return new_challenge.call
+        end
+        return new_challenge.call if expires_dt < Time.now.utc
+
+        receipt = intent.verify(credential, request)
+        [credential, receipt]
+      end
+
+      sig { params(method: String, intent_name: String, request: T::Hash[String, T.untyped], realm: String, secret_key: String, description: T.nilable(String), meta: T.nilable(T::Hash[String, T.untyped]), expires: T.nilable(String)).returns(Mpp::Challenge) }
+      def create_challenge(method, intent_name, request, realm, secret_key,
+        description = nil, meta = nil, expires = nil)
+        expires = nil if expires && !expires.is_a?(String)
+
+        if expires.nil?
+          expires_dt = Time.now.utc + (DEFAULT_EXPIRES_MINUTES * 60)
+          expires = expires_dt.strftime("%Y-%m-%dT%H:%M:%S.%LZ")
+        end
+
+        Mpp::Challenge.create(
+          secret_key: secret_key,
+          realm: realm,
+          method: method,
+          intent: intent_name,
+          request: request,
+          expires: expires,
+          description: description,
+          meta: meta
+        )
+      end
+
+      sig { params(header: String).returns(T.nilable(String)) }
+      def extract_payment_scheme(header)
+        header.split(",").each do |scheme|
+          scheme = scheme.strip
+          return scheme if scheme.downcase.start_with?("payment ")
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/mpp/server.rb

@@ -0,0 +1,15 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Mpp
+  module Server
+    autoload :Defaults, "mpp/server/defaults"
+    autoload :Intent, "mpp/server/intent"
+    autoload :FunctionalIntent, "mpp/server/intent"
+    autoload :Method, "mpp/server/method"
+    autoload :Verify, "mpp/server/verify"
+    autoload :MppHandler, "mpp/server/mpp_handler"
+    autoload :Decorator, "mpp/server/decorator"
+    autoload :Middleware, "mpp/server/middleware"
+  end
+end

data/lib/mpp/store.rb

@@ -0,0 +1,49 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Mpp
+  # In-memory key-value store for development/testing.
+  # Production implementations should use Redis, DynamoDB, etc.
+  #
+  # Duck type interface (Store):
+  #   get(key) -> value or nil
+  #   put(key, value) -> void
+  #   delete(key) -> void
+  #   put_if_absent(key, value) -> bool
+  class MemoryStore
+    extend T::Sig
+
+    sig { void }
+    def initialize
+      @data = T.let({}, T::Hash[T.untyped, T.untyped])
+      @mutex = T.let(Mutex.new, Thread::Mutex)
+    end
+
+    sig { params(key: String).returns(T.untyped) }
+    def get(key)
+      @mutex.synchronize { @data[key] }
+    end
+
+    sig { params(key: String, value: T.untyped).returns(T.untyped) }
+    def put(key, value)
+      @mutex.synchronize { @data[key] = value }
+    end
+
+    sig { params(key: String).returns(T.untyped) }
+    def delete(key)
+      @mutex.synchronize { @data.delete(key) }
+    end
+
+    # Store value under key only if key does not already exist.
+    # Returns true if the key was new, false if it already existed.
+    sig { params(key: String, value: T.untyped).returns(T::Boolean) }
+    def put_if_absent(key, value)
+      @mutex.synchronize do
+        return false if @data.key?(key)
+
+        @data[key] = value
+        true
+      end
+    end
+  end
+end

data/lib/mpp/units.rb

@@ -0,0 +1,57 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+module Mpp
+  module Units
+    extend T::Sig
+
+    module_function
+
+    # Convert a human-readable decimal string to base units.
+    # e.g. parse_units("1.5", 6) => 1500000
+    sig { params(value: T.untyped, decimals: T.any(Integer, Float, Rational, BigDecimal)).returns(Integer) }
+    def parse_units(value, decimals)
+      Kernel.raise ArgumentError, "amount is required" unless value.is_a?(String) && !value.strip.empty?
+
+      stripped = value.strip
+      d = Kernel.BigDecimal(stripped)
+    rescue ArgumentError
+      Kernel.raise ArgumentError, "Invalid amount: #{value.inspect}"
+    else
+      Kernel.raise ArgumentError, "amount must be finite" unless d.finite?
+      Kernel.raise ArgumentError, "amount must be non-negative" if d.negative?
+
+      result = d * (Kernel.BigDecimal(10)**decimals)
+      int_result = result.to_i
+
+      unless T.unsafe(result) == int_result
+        Kernel.raise ArgumentError,
+          "Amount #{value.inspect} with #{decimals} decimals produces fractional base units"
+      end
+
+      int_result
+    end
+
+    # Transform request amounts from human-readable to base units.
+    # If `decimals` is present, converts amount and optional suggestedDeposit.
+    sig { params(request: T::Hash[String, T.untyped]).returns(T::Hash[String, T.untyped]) }
+    def transform_units(request)
+      return request unless request.key?("decimals")
+
+      result = request.dup
+      decimals = result.delete("decimals")
+
+      Kernel.raise ArgumentError, "decimals must be an integer, got #{decimals.class.name}" unless decimals.is_a?(Integer)
+
+      result["amount"] = parse_units(result["amount"], decimals).to_s if result.key?("amount")
+
+      if result.key?("suggestedDeposit") && !result["suggestedDeposit"].nil?
+        result["suggestedDeposit"] = parse_units(result["suggestedDeposit"], decimals).to_s
+      end
+
+      result
+    end
+  end
+end

data/lib/mpp/version.rb

@@ -0,0 +1,6 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Mpp
+  VERSION = "0.1.0"
+end

data/lib/mpp-rb.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "mpp"

data/lib/mpp.rb

@@ -0,0 +1,68 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require_relative "mpp/version"
+require_relative "mpp/json"
+require_relative "mpp/challenge_id"
+require_relative "mpp/secure_compare"
+
+module Mpp
+  extend T::Sig
+
+  autoload :Challenge, "mpp/challenge"
+  autoload :ChallengeEcho, "mpp/challenge_echo"
+  autoload :Credential, "mpp/credential"
+  autoload :Receipt, "mpp/receipt"
+  autoload :Parsing, "mpp/parsing"
+  autoload :Json, "mpp/json"
+  autoload :BodyDigest, "mpp/body_digest"
+  autoload :Expires, "mpp/expires"
+  autoload :Units, "mpp/units"
+  autoload :MemoryStore, "mpp/store"
+
+  # Server module (autoloaded)
+  autoload :Server, "mpp/server"
+
+  # Client module (autoloaded)
+  autoload :Client, "mpp/client"
+
+  # Methods namespace
+  module Methods
+    autoload :Tempo, "mpp/methods/tempo"
+    autoload :Stripe, "mpp/methods/stripe"
+  end
+
+  # Extensions namespace
+  module Extensions
+    autoload :MCP, "mpp/extensions/mcp"
+  end
+
+  sig { params(method: T.untyped, realm: T.untyped, secret_key: T.untyped).returns(T.untyped) }
+  def self.create(method:, realm: nil, secret_key: nil)
+    Server::MppHandler.create(method: method, realm: realm, secret_key: secret_key)
+  end
+
+  # Error hierarchy
+  autoload :PaymentError, "mpp/errors"
+  autoload :PaymentRequiredError, "mpp/errors"
+  autoload :MalformedCredentialError, "mpp/errors"
+  autoload :InvalidChallengeError, "mpp/errors"
+  autoload :VerificationFailedError, "mpp/errors"
+  autoload :PaymentExpiredError, "mpp/errors"
+  autoload :InvalidPayloadError, "mpp/errors"
+  autoload :PaymentInsufficientError, "mpp/errors"
+  autoload :PaymentMethodUnsupportedError, "mpp/errors"
+  autoload :PaymentActionRequiredError, "mpp/errors"
+  autoload :BadRequestError, "mpp/errors"
+  autoload :VerificationError, "mpp/errors"
+  autoload :ParseError, "mpp/errors"
+  autoload :InsufficientBalanceError, "mpp/errors"
+  autoload :InvalidSignatureError, "mpp/errors"
+  autoload :SignerMismatchError, "mpp/errors"
+  autoload :AmountExceedsDepositError, "mpp/errors"
+  autoload :DeltaTooSmallError, "mpp/errors"
+  autoload :ChannelNotFoundError, "mpp/errors"
+  autoload :ChannelClosedError, "mpp/errors"
+end

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification
+name: mpp-rb
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Stripe
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-04-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+description: Ruby SDK for the Machine Payments Protocol (MPP) — an HTTP 402 Payment
+  Authentication scheme.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/mpp-rb.rb
+- lib/mpp.rb
+- lib/mpp/body_digest.rb
+- lib/mpp/challenge.rb
+- lib/mpp/challenge_echo.rb
+- lib/mpp/challenge_id.rb
+- lib/mpp/client.rb
+- lib/mpp/client/transport.rb
+- lib/mpp/credential.rb
+- lib/mpp/errors.rb
+- lib/mpp/expires.rb
+- lib/mpp/extensions/mcp.rb
+- lib/mpp/extensions/mcp/capabilities.rb
+- lib/mpp/extensions/mcp/constants.rb
+- lib/mpp/extensions/mcp/decorator.rb
+- lib/mpp/extensions/mcp/errors.rb
+- lib/mpp/extensions/mcp/types.rb
+- lib/mpp/extensions/mcp/verify.rb
+- lib/mpp/json.rb
+- lib/mpp/methods/stripe.rb
+- lib/mpp/methods/stripe/charge_intent.rb
+- lib/mpp/methods/stripe/client_method.rb
+- lib/mpp/methods/stripe/defaults.rb
+- lib/mpp/methods/stripe/stripe_method.rb
+- lib/mpp/methods/tempo.rb
+- lib/mpp/methods/tempo/account.rb
+- lib/mpp/methods/tempo/attribution.rb
+- lib/mpp/methods/tempo/client_method.rb
+- lib/mpp/methods/tempo/defaults.rb
+- lib/mpp/methods/tempo/fee_payer_envelope.rb
+- lib/mpp/methods/tempo/intents.rb
+- lib/mpp/methods/tempo/keychain.rb
+- lib/mpp/methods/tempo/proof.rb
+- lib/mpp/methods/tempo/rpc.rb
+- lib/mpp/methods/tempo/schemas.rb
+- lib/mpp/methods/tempo/transaction.rb
+- lib/mpp/parsing.rb
+- lib/mpp/receipt.rb
+- lib/mpp/secure_compare.rb
+- lib/mpp/server.rb
+- lib/mpp/server/decorator.rb
+- lib/mpp/server/defaults.rb
+- lib/mpp/server/intent.rb
+- lib/mpp/server/method.rb
+- lib/mpp/server/middleware.rb
+- lib/mpp/server/mpp_handler.rb
+- lib/mpp/server/verify.rb
+- lib/mpp/store.rb
+- lib/mpp/units.rb
+- lib/mpp/version.rb
+homepage: https://github.com/stripe/mpp-rb
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/stripe/mpp-rb
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: HTTP 402 Payment Authentication for Ruby
+test_files: []