mpp-rb 0.1.0

data/lib/mpp/extensions/mcp/verify.rb

@@ -0,0 +1,152 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "time"
+
+module Mpp
+  module Extensions
+    module MCP
+      extend T::Sig
+
+      DEFAULT_CHALLENGE_TTL = T.let(5 * 60, Integer) # 5 minutes in seconds
+
+      module_function
+
+      # Verify a payment credential or generate a new challenge.
+      # Returns MCPChallenge or [MCPCredential, MCPReceipt].
+      sig { params(meta: T.untyped, intent: T.untyped, request: T.untyped, realm: String, secret_key: String, method: T.nilable(String), expires_in: Integer, description: T.nilable(String)).returns(T.untyped) }
+      def verify_or_challenge(meta:, intent:, request:, realm:, secret_key:,
+        method: nil, expires_in: DEFAULT_CHALLENGE_TTL, description: nil)
+        method_name = method || "tempo"
+        meta ||= {}
+
+        new_challenge = Kernel.lambda {
+          create_challenge(
+            method: method_name,
+            intent_name: intent.name,
+            request: request,
+            realm: realm,
+            secret_key: secret_key,
+            expires_in: expires_in,
+            description: description
+          )
+        }
+
+        credential_data = meta[META_CREDENTIAL]
+        return new_challenge.call unless credential_data
+
+        begin
+          mcp_credential = MCPCredential.from_dict(credential_data)
+        rescue KeyError, TypeError, NoMethodError => e
+          Kernel.raise MalformedCredentialError.new(detail: "Invalid credential structure: #{e}")
+        end
+
+        # Stateless challenge verification
+        echoed = mcp_credential.challenge
+        expected_id = Mpp.generate_challenge_id(
+          secret_key: secret_key,
+          realm: echoed.realm,
+          method: echoed.method,
+          intent: echoed.intent,
+          request: echoed.request,
+          expires: echoed.expires,
+          digest: echoed.digest,
+          opaque: echoed.opaque
+        )
+        return new_challenge.call unless Mpp.secure_compare(echoed.id, expected_id)
+
+        # Assert echoed fields match server's values
+        unless echoed.realm == realm && echoed.method == method_name && echoed.intent == intent.name
+          return new_challenge.call
+        end
+
+        # Assert echoed request matches server's current request
+        return new_challenge.call unless echoed.request == request
+
+        # Reject expired challenges as defense-in-depth
+        if echoed.expires
+          begin
+            expires_dt = Time.iso8601(echoed.expires.gsub("Z", "+00:00"))
+            return new_challenge.call if expires_dt < Time.now.utc
+          rescue ArgumentError
+            # continue to stricter check
+          end
+        end
+
+        # Verify echoed request parameters
+        echoed_request = echoed.request.is_a?(Hash) ? echoed.request : {}
+        request.each do |key, value|
+          next if key == "expires"
+
+          return new_challenge.call unless echoed_request[key] == value
+        end
+
+        # Enforce challenge expiry - fail closed
+        return new_challenge.call unless echoed.expires
+
+        begin
+          expires_dt = Time.iso8601(echoed.expires.gsub("Z", "+00:00"))
+        rescue ArgumentError
+          return new_challenge.call
+        end
+        return new_challenge.call if expires_dt < Time.now.utc
+
+        core_credential = mcp_credential.to_core
+
+        begin
+          core_receipt = intent.verify(core_credential, request)
+        rescue Mpp::VerificationError => e
+          Kernel.raise PaymentVerificationError.new(
+            challenges: [new_challenge.call],
+            reason: "verification-failed",
+            detail: e.message
+          )
+        end
+
+        mcp_receipt = MCPReceipt.from_core(
+          core_receipt,
+          challenge_id: mcp_credential.challenge.id,
+          method: mcp_credential.challenge.method,
+          settlement: extract_settlement(request)
+        )
+
+        [mcp_credential, mcp_receipt]
+      end
+
+      sig { params(method: T.untyped, intent_name: T.untyped, request: T.untyped, realm: T.untyped, secret_key: T.untyped, expires_in: BasicObject, description: T.untyped).returns(Mpp::Extensions::MCP::MCPChallenge) }
+      def create_challenge(method:, intent_name:, request:, realm:, secret_key:,
+        expires_in: DEFAULT_CHALLENGE_TTL, description: nil)
+        expires_time = Time.now.utc + expires_in
+        expires = expires_time.iso8601
+        expires = expires.sub(/\+00:00$/, "Z")
+
+        challenge_id = Mpp.generate_challenge_id(
+          secret_key: secret_key,
+          realm: realm,
+          method: method,
+          intent: intent_name,
+          request: request,
+          expires: expires
+        )
+
+        MCPChallenge.new(
+          id: challenge_id,
+          realm: realm,
+          method: method,
+          intent: intent_name,
+          request: request,
+          expires: expires,
+          description: description
+        )
+      end
+
+      sig { params(request: T.untyped).returns(T.nilable(T::Hash[T.untyped, T.untyped])) }
+      def extract_settlement(request)
+        settlement = {}
+        settlement["amount"] = request["amount"] if request.key?("amount")
+        settlement["currency"] = request["currency"] if request.key?("currency")
+        settlement.empty? ? nil : settlement
+      end
+    end
+  end
+end

data/lib/mpp/extensions/mcp.rb

@@ -0,0 +1,16 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "mcp/constants"
+require_relative "mcp/types"
+require_relative "mcp/verify"
+require_relative "mcp/errors"
+require_relative "mcp/decorator"
+require_relative "mcp/capabilities"
+
+module Mpp
+  module Extensions
+    module MCP
+    end
+  end
+end

data/lib/mpp/json.rb

@@ -0,0 +1,32 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "json"
+
+module Mpp
+  module Json
+    extend T::Sig
+
+    module_function
+
+    # Encode object as compact JSON with recursively sorted keys.
+    # Matches Python's json.dumps(separators=(",", ":"), sort_keys=True).
+    sig { params(obj: T.untyped).returns(String) }
+    def compact_encode(obj)
+      ::JSON.generate(deep_sort_keys(obj), space: "", object_nl: "", array_nl: "")
+    end
+
+    # Recursively sort hash keys for deterministic serialization.
+    sig { params(obj: T.anything).returns(T.untyped) }
+    def deep_sort_keys(obj)
+      case obj
+      when Hash
+        obj.sort_by { |k, _| k.to_s }.to_h.transform_values { |v| deep_sort_keys(v) }
+      when Array
+        obj.map { |v| deep_sort_keys(v) }
+      else
+        obj
+      end
+    end
+  end
+end

data/lib/mpp/methods/stripe/charge_intent.rb

@@ -0,0 +1,90 @@
+# typed: false
+# frozen_string_literal: true
+
+require "time"
+
+module Mpp
+  module Methods
+    module Stripe
+      # Server-side charge intent that verifies payment via Stripe PaymentIntents.
+      # Requires the `stripe` gem.
+      class ChargeIntent
+        attr_reader :name
+
+        def initialize(secret_key:, api_base: Defaults::STRIPE_API_BASE)
+          @name = "charge"
+          @secret_key = secret_key
+          @api_base = api_base
+        end
+
+        def verify(credential, request)
+          # Check challenge expiry
+          challenge_expires = credential.challenge.expires
+          if challenge_expires
+            expires = Time.iso8601(challenge_expires.gsub("Z", "+00:00"))
+            raise Mpp::VerificationError, "Request has expired" if expires < Time.now.utc
+          end
+
+          payload_data = credential.payload
+          unless payload_data.is_a?(Hash) && payload_data.key?("spt")
+            raise Mpp::VerificationError, "Invalid credential payload: missing spt"
+          end
+
+          spt = payload_data["spt"]
+          external_id = payload_data["externalId"]
+
+          # Build PaymentIntent params
+          params = {
+            amount: Integer(request["amount"]),
+            currency: request["currency"],
+            shared_payment_granted_token: spt,
+            confirm: true,
+            automatic_payment_methods: {
+              enabled: true,
+              allow_redirects: "never"
+            }
+          }
+
+          # Include metadata from methodDetails if present
+          method_details = request["methodDetails"]
+          if method_details.is_a?(Hash) && method_details["metadata"].is_a?(Hash)
+            params[:metadata] = method_details["metadata"].transform_values(&:to_s)
+          end
+
+          # Create PaymentIntent via Stripe SDK
+          begin
+            Kernel.require "stripe"
+          rescue LoadError
+            raise "stripe gem is required for Stripe charge verification. Install with: gem install stripe"
+          end
+
+          begin
+            client = ::Stripe::StripeClient.new(@secret_key)
+            result = client.v1.payment_intents.create(params)
+          rescue => e
+            raise Mpp::VerificationError, e.message
+          end
+
+          # https://docs.stripe.com/error-low-level#idempotency
+          if result.respond_to?(:last_response) &&
+              result.last_response&.headers&.[]("idempotent-replayed") == "true"
+            raise Mpp::VerificationError, "Payment has already been processed."
+          end
+
+          pi_id = result.id
+          status = result.status
+
+          if status == "requires_action"
+            raise Mpp::PaymentActionRequiredError.new(reason: "PaymentIntent #{pi_id} requires action")
+          end
+
+          unless status == "succeeded"
+            raise Mpp::VerificationError, "PaymentIntent #{pi_id} has status: #{status}"
+          end
+
+          Mpp::Receipt.success(pi_id, method: "stripe", external_id: external_id)
+        end
+      end
+    end
+  end
+end

data/lib/mpp/methods/stripe/client_method.rb

@@ -0,0 +1,42 @@
+# typed: false
+# frozen_string_literal: true
+
+module Mpp
+  module Methods
+    module Stripe
+      # Client-side Stripe method for creating SPT-based credentials.
+      class ClientMethod
+        attr_reader :name
+
+        def initialize(create_spt:, payment_method: nil, external_id: nil)
+          @name = "stripe"
+          @create_spt = create_spt
+          @payment_method = payment_method
+          @external_id = external_id
+        end
+
+        # Create a credential to satisfy the given challenge.
+        def create_credential(challenge)
+          request = challenge.request
+          method_details = request["methodDetails"]
+          method_details = {} unless method_details.is_a?(Hash)
+
+          spt_id = @create_spt.call(
+            amount: request["amount"],
+            currency: request["currency"],
+            network_id: method_details["networkId"],
+            payment_method: @payment_method
+          )
+
+          payload = {"spt" => spt_id}
+          payload["externalId"] = @external_id if @external_id
+
+          Mpp::Credential.new(
+            challenge: challenge.to_echo,
+            payload: payload
+          )
+        end
+      end
+    end
+  end
+end

data/lib/mpp/methods/stripe/defaults.rb

@@ -0,0 +1,14 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Mpp
+  module Methods
+    module Stripe
+      module Defaults
+        STRIPE_API_BASE = "https://api.stripe.com"
+        DEFAULT_CURRENCY = "usd"
+        DEFAULT_DECIMALS = 2
+      end
+    end
+  end
+end

data/lib/mpp/methods/stripe/stripe_method.rb

@@ -0,0 +1,63 @@
+# typed: false
+# frozen_string_literal: true
+
+require_relative "defaults"
+
+module Mpp
+  module Methods
+    module Stripe
+      # Stripe payment method implementation.
+      # Handles SPT-based payments through Stripe's Business Network.
+      class StripeMethod
+        attr_reader :name, :currency, :recipient, :decimals
+        attr_accessor :intents
+
+        def initialize(secret_key:, network_id:, payment_methods: nil,
+          metadata: nil, currency: Defaults::DEFAULT_CURRENCY,
+          decimals: Defaults::DEFAULT_DECIMALS)
+          @name = "stripe"
+          @secret_key = secret_key
+          @network_id = network_id
+          @payment_methods = payment_methods
+          @metadata = metadata
+          @currency = currency
+          @recipient = network_id
+          @decimals = decimals
+          @intents = {}
+        end
+
+        # Transform request - injects Stripe-specific methodDetails.
+        def transform_request(request, _credential)
+          method_details = request.fetch("methodDetails", {})
+          method_details = {} unless method_details.is_a?(Hash)
+
+          method_details["networkId"] = @network_id
+          method_details["paymentMethods"] = @payment_methods if @payment_methods
+          method_details["metadata"] = @metadata if @metadata
+
+          request.merge("methodDetails" => method_details)
+        end
+      end
+
+      # Factory function to create a configured StripeMethod with ChargeIntent.
+      def self.stripe(secret_key:, network_id:, payment_methods: nil,
+        metadata: nil, currency: Defaults::DEFAULT_CURRENCY,
+        decimals: Defaults::DEFAULT_DECIMALS,
+        api_base: Defaults::STRIPE_API_BASE)
+        charge_intent = ChargeIntent.new(secret_key: secret_key, api_base: api_base)
+
+        method = StripeMethod.new(
+          secret_key: secret_key,
+          network_id: network_id,
+          payment_methods: payment_methods,
+          metadata: metadata,
+          currency: currency,
+          decimals: decimals
+        )
+
+        method.intents = {"charge" => charge_intent}
+        method
+      end
+    end
+  end
+end

data/lib/mpp/methods/stripe.rb

@@ -0,0 +1,14 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Mpp
+  module Methods
+    module Stripe
+      autoload :Defaults, "mpp/methods/stripe/defaults"
+      # Eagerly require stripe_method so the Stripe.stripe factory method is available
+      require_relative "stripe/stripe_method"
+      autoload :ChargeIntent, "mpp/methods/stripe/charge_intent"
+      autoload :ClientMethod, "mpp/methods/stripe/client_method"
+    end
+  end
+end

data/lib/mpp/methods/tempo/account.rb

@@ -0,0 +1,52 @@
+# typed: false
+# frozen_string_literal: true
+
+module Mpp
+  module Methods
+    module Tempo
+      # Wrapper around the eth gem for signing.
+      # Requires the `eth` gem to be installed.
+      class Account
+        attr_reader :key
+
+        def initialize(key)
+          @key = key
+        end
+
+        # Load from hex private key (0x-prefixed).
+        def self.from_key(private_key)
+          require "eth"
+          new(Eth::Key.new(priv: private_key.delete_prefix("0x")))
+        end
+
+        # Load from environment variable.
+        def self.from_env(var = "TEMPO_PRIVATE_KEY")
+          key = ENV.fetch(var, nil)
+          raise ArgumentError, "$#{var} not set" unless key && !key.empty?
+
+          from_key(key)
+        end
+
+        # Get the account's Ethereum address (checksummed).
+        def address
+          @key.address.to_s
+        end
+
+        # Get the private key as hex string.
+        def private_key
+          "0x#{@key.private_hex}"
+        end
+
+        # Sign a 32-byte hash, return 65-byte signature (r || s || v).
+        def sign_hash(msg_hash)
+          raise ArgumentError, "msg_hash must be 32 bytes, got #{msg_hash.bytesize}" unless msg_hash.bytesize == 32
+
+          sig = @key.sign(msg_hash)
+          # eth gem returns hex signature, parse r, s, v
+          sig_hex = sig.delete_prefix("0x")
+          [sig_hex].pack("H*")
+        end
+      end
+    end
+  end
+end

data/lib/mpp/methods/tempo/attribution.rb

@@ -0,0 +1,112 @@
+# typed: false
+# frozen_string_literal: true
+
+require "openssl"
+require "securerandom"
+
+module Mpp
+  module Methods
+    module Tempo
+      module Attribution
+        VERSION = 0x01
+        ANONYMOUS = "\x00" * 10
+
+        module_function
+
+        # Compute keccak256 hash. Uses OpenSSL if available, otherwise pure Ruby.
+        def keccak256(data)
+          # Try eth gem's keccak first
+          Kernel.require "eth"
+          Eth::Util.keccak256(data)
+        rescue LoadError
+          # Fallback: use OpenSSL's SHA3-256 (not exactly keccak, but close)
+          # For production, the eth gem should be installed
+          OpenSSL::Digest.new("SHA3-256").digest(data)
+        end
+
+        # Compute TAG = keccak256("mpp")[0:4]
+        def tag
+          @tag ||= keccak256("mpp".b)[0, 4]
+        end
+
+        def fingerprint(value)
+          keccak256(value.encode(Encoding::UTF_8))[0, 10]
+        end
+
+        # Encode an MPP attribution memo (32 bytes).
+        #
+        # Byte Layout:
+        #   0..3:   TAG = keccak256("mpp")[0:4]
+        #   4:      version (0x01)
+        #   5..14:  serverId fingerprint
+        #   15..24: clientId fingerprint or zeros
+        #   25..31: random nonce
+        def encode(server_id:, client_id: nil, challenge_id: nil)
+          buf = "\x00".b * 32
+          buf[0, 4] = tag
+          buf[4] = [VERSION].pack("C")
+          buf[5, 10] = fingerprint(server_id)
+          buf[15, 10] = client_id ? fingerprint(client_id) : ANONYMOUS.b
+          buf[25, 7] = if challenge_id
+            keccak256(challenge_id.encode(Encoding::UTF_8))[0, 7]
+          else
+            SecureRandom.random_bytes(7)
+          end
+          "0x#{buf.unpack1("H*")}"
+        end
+
+        # Check if a memo is an MPP attribution memo.
+        def mpp_memo?(memo)
+          return false unless memo.length == 66
+
+          begin
+            memo_tag = [memo[2, 8]].pack("H*")
+            memo_version = memo[10, 2].to_i(16)
+          rescue ArgumentError
+            return false
+          end
+          memo_tag == tag && memo_version == VERSION
+        end
+
+        # Verify server fingerprint in memo.
+        def verify_server(memo, server_id)
+          return false unless mpp_memo?(memo)
+
+          begin
+            memo_server = [memo[12, 20]].pack("H*")
+          rescue ArgumentError
+            return false
+          end
+          memo_server == fingerprint(server_id)
+        end
+
+        # Decoded memo structure.
+        DecodedMemo = Data.define(:version, :server_fingerprint, :client_fingerprint, :nonce)
+
+        # Decode an MPP attribution memo.
+        def decode(memo)
+          return nil unless mpp_memo?(memo)
+
+          begin
+            version = memo[10, 2].to_i(16)
+            server_fingerprint = "0x#{memo[12, 20]}"
+            client_hex = memo[32, 20]
+            nonce = "0x#{memo[52..]}"
+
+            client_bytes = [client_hex].pack("H*")
+            client_fingerprint = (client_bytes == ANONYMOUS.b) ? nil : "0x#{client_hex}"
+          rescue ArgumentError
+            return nil
+          end
+
+          DecodedMemo.new(
+            version: version,
+            server_fingerprint: server_fingerprint,
+            client_fingerprint: client_fingerprint,
+            nonce: nonce
+          )
+        end
+      end
+    end
+  end
+end