mpp-rb 0.1.0

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

@@ -0,0 +1,144 @@
+# typed: false
+# frozen_string_literal: true
+
+module Mpp
+  module Methods
+    module Tempo
+      module Transaction
+        TYPE_ID = 0x76
+        EMPTY_SIGNATURE = "\x00".b
+        EMPTY_LIST = [].freeze
+
+        Call = Data.define(:to, :value, :data) do
+          def as_rlp_list
+            [pack_address(to), encode_uint(value), pack_bytes(data)]
+          end
+
+          private
+
+          def pack_address(value)
+            [value.delete_prefix("0x")].pack("H*")
+          end
+
+          def pack_bytes(value)
+            [value.delete_prefix("0x")].pack("H*")
+          end
+
+          def encode_uint(value)
+            Integer(value)
+          end
+        end
+
+        SignedTransaction = Data.define(
+          :chain_id, :max_priority_fee_per_gas, :max_fee_per_gas, :gas_limit,
+          :calls, :access_list, :nonce_key, :nonce, :valid_before, :valid_after,
+          :fee_token, :sender_signature, :fee_payer_signature, :sender_address,
+          :tempo_authorization_list, :key_authorization
+        ) do
+          def encoded_2718
+            require_rlp!
+
+            [TYPE_ID].pack("C") + RLP.encode(rlp_fields)
+          end
+
+          def signature_hash
+            require_eth!
+            require_rlp!
+
+            Eth::Util.keccak256([TYPE_ID].pack("C") + RLP.encode(unsigned_rlp_fields))
+          end
+
+          # Hash for fee payer to sign — includes sender_signature in the RLP.
+          def fee_payer_signature_hash
+            require_eth!
+            require_rlp!
+
+            fields = unsigned_rlp_fields
+            fields.insert(11, sender_signature)
+            Eth::Util.keccak256([TYPE_ID].pack("C") + RLP.encode(fields))
+          end
+
+          private
+
+          def rlp_fields
+            fields = unsigned_rlp_fields
+            fields.insert(11, sender_signature)
+            fields.insert(12, fee_payer_signature || EMPTY_SIGNATURE)
+            fields
+          end
+
+          def unsigned_rlp_fields
+            fields = [
+              chain_id,
+              max_priority_fee_per_gas,
+              max_fee_per_gas,
+              gas_limit,
+              calls.map(&:as_rlp_list),
+              access_list || EMPTY_LIST,
+              nonce_key,
+              nonce,
+              encode_optional_uint(valid_before),
+              encode_optional_uint(valid_after),
+              fee_token ? pack_hex(fee_token) : "".b,
+              tempo_authorization_list || EMPTY_LIST
+            ]
+            fields << key_authorization if key_authorization
+            fields
+          end
+
+          def pack_hex(value)
+            [value.delete_prefix("0x")].pack("H*")
+          end
+
+          def encode_optional_uint(value)
+            return "".b if value.nil?
+
+            Integer(value)
+          end
+
+          def require_eth!
+            Kernel.require "eth"
+          rescue LoadError
+            raise LoadError, "eth gem is required for Tempo transaction signing. Install with: gem install eth"
+          end
+
+          def require_rlp!
+            Kernel.require "rlp"
+          rescue LoadError
+            raise LoadError, "rlp gem is required for Tempo transaction encoding. Install with: gem install rlp"
+          end
+        end
+
+        module_function
+
+        def build_signed_transfer(account:, chain_id:, gas_limit:, gas_price:, nonce:, nonce_key:,
+          currency:, transfer_data:, valid_before: nil, awaiting_fee_payer: false)
+          tx = SignedTransaction.new(
+            chain_id: chain_id,
+            max_priority_fee_per_gas: gas_price,
+            max_fee_per_gas: gas_price,
+            gas_limit: gas_limit,
+            calls: [Call.new(to: currency, value: 0, data: transfer_data)],
+            access_list: EMPTY_LIST,
+            nonce_key: nonce_key,
+            nonce: nonce,
+            valid_before: valid_before,
+            valid_after: nil,
+            fee_token: awaiting_fee_payer ? nil : currency,
+            sender_signature: nil,
+            fee_payer_signature: EMPTY_SIGNATURE,
+            sender_address: account.address,
+            tempo_authorization_list: EMPTY_LIST,
+            key_authorization: nil
+          )
+
+          signature = account.sign_hash(tx.signature_hash)
+          signed = tx.with(sender_signature: signature)
+          raw = awaiting_fee_payer ? FeePayer.encode(signed) : signed.encoded_2718
+
+          ["0x#{raw.unpack1("H*")}", chain_id]
+        end
+      end
+    end
+  end
+end

data/lib/mpp/methods/tempo.rb

@@ -0,0 +1,22 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Mpp
+  module Methods
+    module Tempo
+      autoload :Defaults, "mpp/methods/tempo/defaults"
+      autoload :Account, "mpp/methods/tempo/account"
+      autoload :Keychain, "mpp/methods/tempo/keychain"
+      autoload :Attribution, "mpp/methods/tempo/attribution"
+      autoload :Rpc, "mpp/methods/tempo/rpc"
+      autoload :Transaction, "mpp/methods/tempo/transaction"
+      autoload :Schemas, "mpp/methods/tempo/schemas"
+      # Eagerly require client_method so the Tempo.tempo factory method is available
+      require_relative "tempo/client_method"
+      autoload :Intents, "mpp/methods/tempo/intents"
+      autoload :ChargeIntent, "mpp/methods/tempo/intents"
+      autoload :FeePayer, "mpp/methods/tempo/fee_payer_envelope"
+      autoload :Proof, "mpp/methods/tempo/proof"
+    end
+  end
+end

data/lib/mpp/parsing.rb

@@ -0,0 +1,252 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "time"
+
+module Mpp
+  module Parsing
+    extend T::Sig
+
+    MAX_HEADER_PAYLOAD_SIZE = T.let(16 * 1024, Integer)
+
+    # RFC 9110 auth-param regex: key="value" or key=token
+    AUTH_PARAM_RE = /([a-zA-Z_][\w-]*)\s*=\s*(?:"((?:[^"\\]|\\.)*)"|([^\s,]+))/
+
+    module_function
+
+    # Encode dict as URL-safe base64 JSON (compact, no padding).
+    sig { params(data: T.untyped).returns(String) }
+    def b64_encode(data)
+      compact_json = Mpp::Json.compact_encode(data)
+      Base64.urlsafe_encode64(compact_json, padding: false)
+    end
+
+    # Decode URL-safe base64 JSON to hash.
+    sig { params(encoded: T.untyped).returns(T::Hash[T.untyped, T.untyped]) }
+    def b64_decode(encoded)
+      Kernel.raise Mpp::ParseError, "Header payload exceeds maximum size" if encoded.length > MAX_HEADER_PAYLOAD_SIZE
+
+      padded = encoded + ("=" * ((-encoded.length) % 4))
+      decoded = Base64.urlsafe_decode64(padded)
+      obj = JSON.parse(decoded)
+      Kernel.raise Mpp::ParseError, "Expected JSON object" unless obj.is_a?(Hash)
+
+      obj
+    rescue ArgumentError, JSON::ParserError
+      Kernel.raise Mpp::ParseError, "Invalid base64 or JSON encoding"
+    end
+
+    # Escape a string for use in a quoted-string. Rejects CRLF.
+    sig { params(str: String).returns(String) }
+    def escape_quoted(str)
+      Kernel.raise Mpp::ParseError, "Header value contains invalid CRLF characters" if str.include?("\r") || str.include?("\n")
+
+      str.gsub("\\", "\\\\\\\\").gsub('"', '\\"')
+    end
+
+    # Unescape a quoted-string value.
+    sig { params(str: String).returns(String) }
+    def unescape_quoted(str)
+      str.gsub(/\\(.)/, '\1')
+    end
+
+    # Parse RFC 9110 auth-params into a hash.
+    sig { params(params_str: T.untyped).returns(T::Hash[T.untyped, T.untyped]) }
+    def parse_auth_params(params_str)
+      params = {}
+      params_str.scan(AUTH_PARAM_RE) do |key, quoted_val, token_val|
+        Kernel.raise Mpp::ParseError, "Duplicate parameter: #{key}" if params.key?(key)
+
+        value = quoted_val.nil? ? token_val : unescape_quoted(quoted_val)
+        params[key] = value
+      end
+      params
+    end
+
+    # Parse a WWW-Authenticate header into a Challenge.
+    sig { params(header: T.untyped).returns(Mpp::Challenge) }
+    def parse_www_authenticate(header)
+      header = header.strip
+      Kernel.raise Mpp::ParseError, "Expected 'Payment' authentication scheme" unless header.downcase.start_with?("payment ")
+
+      params_str = header[8..].strip
+      params = parse_auth_params(params_str)
+
+      id = params["id"]
+      Kernel.raise Mpp::ParseError, "Missing 'id' field" unless id && !id.empty?
+
+      realm = params["realm"]
+      Kernel.raise Mpp::ParseError, "Missing 'realm' field" unless realm && !realm.empty?
+
+      method = params["method"]
+      Kernel.raise Mpp::ParseError, "Missing 'method' field" unless method && !method.empty?
+
+      intent = params["intent"]
+      Kernel.raise Mpp::ParseError, "Missing 'intent' field" unless intent && !intent.empty?
+
+      request_b64 = params["request"]
+      Kernel.raise Mpp::ParseError, "Missing 'request' field" unless request_b64 && !request_b64.empty?
+
+      request = b64_decode(request_b64)
+
+      opaque_b64 = params["opaque"]
+      opaque = (opaque_b64 && !opaque_b64.empty?) ? b64_decode(opaque_b64) : nil
+
+      Mpp::Challenge.new(
+        id: id,
+        method: method,
+        intent: intent,
+        request: request,
+        realm: realm,
+        request_b64: request_b64,
+        digest: params["digest"],
+        expires: params["expires"],
+        description: params["description"],
+        opaque: opaque
+      )
+    end
+
+    # Format a Challenge as a WWW-Authenticate header value.
+    sig { params(challenge: T.untyped, realm: T.untyped).returns(String) }
+    def format_www_authenticate(challenge, realm)
+      request_b64 = b64_encode(challenge.request)
+
+      parts = [
+        "id=\"#{escape_quoted(challenge.id)}\"",
+        "realm=\"#{escape_quoted(realm)}\"",
+        "method=\"#{escape_quoted(challenge.method)}\"",
+        "intent=\"#{escape_quoted(challenge.intent)}\"",
+        "request=\"#{request_b64}\""
+      ]
+
+      parts << "digest=\"#{escape_quoted(challenge.digest)}\"" if challenge.digest
+      parts << "expires=\"#{escape_quoted(challenge.expires)}\"" if challenge.expires
+      parts << "description=\"#{escape_quoted(challenge.description)}\"" if challenge.description
+      if challenge.opaque
+        opaque_b64 = b64_encode(challenge.opaque)
+        parts << "opaque=\"#{opaque_b64}\""
+      end
+
+      "Payment #{parts.join(", ")}"
+    end
+
+    # Parse an Authorization header into a Credential.
+    sig { params(header: T.untyped).returns(Mpp::Credential) }
+    def parse_authorization(header)
+      header = header.strip
+      Kernel.raise Mpp::ParseError, "Expected 'Payment' authentication scheme" unless header.downcase.start_with?("payment ")
+
+      credential_b64 = header[8..].strip
+      data = b64_decode(credential_b64)
+
+      Kernel.raise Mpp::ParseError, "Credential missing required field: challenge" unless data.key?("challenge")
+      Kernel.raise Mpp::ParseError, "Credential missing required field: payload" unless data.key?("payload")
+
+      challenge_data = data["challenge"]
+      Kernel.raise Mpp::ParseError, "Credential challenge must be an object" unless challenge_data.is_a?(Hash)
+      Kernel.raise Mpp::ParseError, "Credential challenge missing required field: id" unless challenge_data.key?("id")
+
+      echo = Mpp::ChallengeEcho.new(
+        id: challenge_data["id"].to_s,
+        realm: (challenge_data["realm"] || "").to_s,
+        method: (challenge_data["method"] || "").to_s,
+        intent: (challenge_data["intent"] || "").to_s,
+        request: (challenge_data["request"] || "").to_s,
+        expires: challenge_data["expires"]&.to_s,
+        digest: challenge_data["digest"]&.to_s,
+        opaque: challenge_data["opaque"]&.to_s
+      )
+
+      Mpp::Credential.new(
+        challenge: echo,
+        payload: data["payload"],
+        source: data["source"]&.to_s
+      )
+    end
+
+    # Format a Credential as an Authorization header value.
+    sig { params(credential: T.untyped).returns(String) }
+    def format_authorization(credential)
+      challenge_dict = {
+        "id" => credential.challenge.id,
+        "realm" => credential.challenge.realm,
+        "method" => credential.challenge.method,
+        "intent" => credential.challenge.intent,
+        "request" => credential.challenge.request
+      }
+      challenge_dict["expires"] = credential.challenge.expires if credential.challenge.expires
+      challenge_dict["digest"] = credential.challenge.digest if credential.challenge.digest
+      challenge_dict["opaque"] = credential.challenge.opaque if credential.challenge.opaque
+
+      payload = {
+        "challenge" => challenge_dict,
+        "payload" => credential.payload
+      }
+      payload["source"] = credential.source if credential.source
+
+      encoded = b64_encode(payload)
+      "Payment #{encoded}"
+    end
+
+    # Parse an ISO 8601 timestamp string to Time.
+    sig { params(value: T.untyped).returns(Time) }
+    def parse_timestamp(value)
+      ts_str = value.gsub("Z", "+00:00")
+      Time.iso8601(ts_str)
+    rescue ArgumentError
+      Kernel.raise Mpp::ParseError, "Invalid timestamp format"
+    end
+
+    # Parse a Payment-Receipt header into a Receipt.
+    sig { params(header: T.untyped).returns(Mpp::Receipt) }
+    def parse_payment_receipt(header)
+      header = header.strip
+      data = b64_decode(header)
+
+      required = %w[status timestamp reference method]
+      missing = required - data.keys
+      Kernel.raise Mpp::ParseError, "Receipt missing required fields: #{missing}" unless missing.empty?
+
+      status = data["status"]
+      Kernel.raise Mpp::ParseError, "Invalid receipt status" unless status == "success"
+
+      timestamp = parse_timestamp(data["timestamp"].to_s)
+
+      extra = data["extra"]
+      extra = nil unless extra.is_a?(Hash)
+
+      Mpp::Receipt.new(
+        status: status,
+        timestamp: timestamp,
+        reference: data["reference"].to_s,
+        method: (data["method"] || "").to_s,
+        external_id: data["externalId"]&.to_s,
+        extra: extra
+      )
+    end
+
+    # Format a Receipt as a Payment-Receipt header value.
+    sig { params(receipt: Mpp::Receipt).returns(String) }
+    def format_payment_receipt(receipt)
+      t = receipt.timestamp.utc
+      timestamp_str = if t.usec == 0
+        t.strftime("%Y-%m-%dT%H:%M:%SZ")
+      else
+        t.strftime("%Y-%m-%dT%H:%M:%S.%LZ")
+      end
+
+      payload = {
+        "method" => receipt.method,
+        "reference" => receipt.reference,
+        "status" => receipt.status,
+        "timestamp" => timestamp_str
+      }
+      payload["externalId"] = receipt.external_id if receipt.external_id
+      payload["extra"] = receipt.extra if receipt.extra
+
+      b64_encode(payload)
+    end
+  end
+end

data/lib/mpp/receipt.rb

@@ -0,0 +1,31 @@
+# typed: true
+# frozen_string_literal: true
+
+module Mpp
+  Receipt = Data.define(:status, :timestamp, :reference, :method, :external_id, :extra) do
+    def initialize(status:, timestamp:, reference:, method: "", external_id: nil, extra: nil)
+      super
+    end
+
+    # Parse a Receipt from a Payment-Receipt header value.
+    def self.from_payment_receipt(header)
+      Mpp::Parsing.parse_payment_receipt(header)
+    end
+
+    # Serialize to a Payment-Receipt header value.
+    def to_payment_receipt
+      Mpp::Parsing.format_payment_receipt(self)
+    end
+
+    # Create a success receipt with current timestamp.
+    def self.success(reference, timestamp: nil, method: "tempo", external_id: nil)
+      new(
+        status: "success",
+        timestamp: timestamp || Time.now.utc,
+        reference: reference,
+        method: method,
+        external_id: external_id
+      )
+    end
+  end
+end

data/lib/mpp/secure_compare.rb

@@ -0,0 +1,25 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "openssl"
+
+module Mpp
+  extend T::Sig
+
+  module_function
+
+  # Timing-safe string comparison to prevent timing attacks.
+  # Falls back to OpenSSL.fixed_length_secure_compare when lengths match,
+  # otherwise uses double-HMAC comparison for variable-length safety.
+  sig { params(a: T.untyped, b: T.untyped).returns(T::Boolean) }
+  def secure_compare(a, b)
+    return false if a.nil? || b.nil?
+
+    a_bytes = a.encode(Encoding::UTF_8)
+    b_bytes = b.encode(Encoding::UTF_8)
+
+    return false unless a_bytes.bytesize == b_bytes.bytesize
+
+    OpenSSL.fixed_length_secure_compare(a_bytes, b_bytes)
+  end
+end

data/lib/mpp/server/decorator.rb

@@ -0,0 +1,32 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "json"
+
+module Mpp
+  module Server
+    module Decorator
+      extend T::Sig
+
+      module_function
+
+      # Build a 402 response for a payment challenge with RFC 9457 problem details body.
+      sig { params(challenge: T.untyped, realm: T.untyped).returns(T::Hash[T.untyped, T.untyped]) }
+      def make_challenge_response(challenge, realm)
+        error = Mpp::PaymentRequiredError.new(realm: realm, description: challenge.description)
+        body = JSON.generate(error.to_problem_details(challenge_id: challenge.id))
+        headers = {
+          "WWW-Authenticate" => challenge.to_www_authenticate(realm),
+          "Cache-Control" => "no-store",
+          "Content-Type" => "application/problem+json"
+        }
+        {
+          "_mpp_challenge" => true,
+          "status" => 402,
+          "headers" => headers,
+          "body" => body
+        }
+      end
+    end
+  end
+end

data/lib/mpp/server/defaults.rb

@@ -0,0 +1,45 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Mpp
+  module Server
+    module Defaults
+      extend T::Sig
+
+      SECRET_KEY_NAME = "MPP_SECRET_KEY"
+
+      REALM_ENV_VARS = %w[
+        MPP_REALM
+        FLY_APP_NAME
+        HEROKU_APP_NAME
+        HOST
+        HOSTNAME
+        RAILWAY_PUBLIC_DOMAIN
+        RENDER_EXTERNAL_HOSTNAME
+        VERCEL_URL
+        WEBSITE_HOSTNAME
+      ].freeze
+
+      module_function
+
+      # Detect server realm from environment.
+      sig { returns(String) }
+      def detect_realm
+        REALM_ENV_VARS.each do |var|
+          value = ENV.fetch(var, nil)
+          return value if value && !value.empty?
+        end
+        "localhost"
+      end
+
+      # Get server secret key from environment.
+      sig { returns(String) }
+      def detect_secret_key
+        value = ENV.fetch(SECRET_KEY_NAME, nil)
+        return value if value && !value.strip.empty?
+
+        Kernel.raise ArgumentError, "Missing secret key. Set MPP_SECRET_KEY or pass secret_key explicitly."
+      end
+    end
+  end
+end

data/lib/mpp/server/intent.rb

@@ -0,0 +1,40 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Mpp
+  module Server
+    extend T::Sig
+
+    # Intent interface (duck type):
+    #   name  -> String
+    #   verify(credential, request) -> Receipt
+    #
+    # Implement this interface for custom payment intents.
+
+    # Function-based intent wrapper.
+    class FunctionalIntent
+      extend T::Sig
+
+      sig { returns(String) }
+      attr_reader :name
+
+      sig { params(name: String, verify_fn: T.proc.params(arg0: Mpp::Credential, arg1: T::Hash[String, T.untyped]).returns(Mpp::Receipt)).void }
+      def initialize(name, &verify_fn)
+        @name = T.let(name, String)
+        @verify_fn = T.let(verify_fn, T.proc.params(arg0: Mpp::Credential, arg1: T::Hash[String, T.untyped]).returns(Mpp::Receipt))
+      end
+
+      sig { params(credential: Mpp::Credential, request: T::Hash[String, T.untyped]).returns(Mpp::Receipt) }
+      def verify(credential, request)
+        @verify_fn.call(credential, request)
+      end
+    end
+
+    # Decorator to define an intent from a block.
+    #   intent = Mpp::Server.intent("charge") { |credential, request| ... }
+    sig { params(name: String, blk: T.proc.params(arg0: Mpp::Credential, arg1: T::Hash[String, T.untyped]).returns(Mpp::Receipt)).returns(Mpp::Server::FunctionalIntent) }
+    def self.intent(name, &blk)
+      FunctionalIntent.new(name, &blk)
+    end
+  end
+end

data/lib/mpp/server/method.rb

@@ -0,0 +1,27 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Mpp
+  module Server
+    # Method interface (duck type):
+    #   name       -> String
+    #   intents    -> Hash[String, Intent]
+    #   create_credential(challenge) -> Credential
+
+    module MethodHelper
+      extend T::Sig
+
+      module_function
+
+      # Transform request using method's transform_request if available.
+      sig { params(method: T.untyped, request: T::Hash[String, T.untyped], credential: T.untyped).returns(T::Hash[String, T.untyped]) }
+      def transform_request(method, request, credential)
+        if method.respond_to?(:transform_request)
+          method.transform_request(request, credential)
+        else
+          request
+        end
+      end
+    end
+  end
+end

data/lib/mpp/server/middleware.rb

@@ -0,0 +1,51 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Mpp
+  module Server
+    # Rack middleware that intercepts requests requiring payment.
+    #
+    # The downstream app signals payment is needed by setting env["mpp.charge"]
+    # to a hash with at least :amount, and optionally :currency, :recipient,
+    # :description, :expires, etc.
+    #
+    # Example:
+    #   use Mpp::Server::Middleware, handler: my_handler
+    #
+    #   # In your app:
+    #   env["mpp.charge"] = { amount: "1.00" }
+    class Middleware
+      extend T::Sig
+
+      sig { params(app: T.untyped, handler: Mpp::Server::MppHandler).void }
+      def initialize(app, handler:)
+        @app = T.let(app, T.untyped)
+        @handler = T.let(handler, Mpp::Server::MppHandler)
+      end
+
+      sig { params(env: T.untyped).returns(T::Array[T.untyped]) }
+      def call(env)
+        authorization = env["HTTP_AUTHORIZATION"]
+        status, headers, body = @app.call(env)
+
+        charge_opts = env["mpp.charge"]
+        return [status, headers, body] unless charge_opts
+
+        amount = charge_opts[:amount]
+        opts = charge_opts.except(:amount)
+
+        result = @handler.charge(authorization, amount, **opts)
+
+        if result.is_a?(Mpp::Challenge)
+          resp = Mpp::Server::Decorator.make_challenge_response(result, @handler.realm)
+          return [resp["status"], resp["headers"], [resp["body"]]]
+        end
+
+        _credential, receipt = result
+        headers["Payment-Receipt"] = receipt.to_payment_receipt
+
+        [status, headers, body]
+      end
+    end
+  end
+end