mpp-rb 0.1.0

data/lib/mpp/errors.rb

@@ -0,0 +1,190 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Mpp
+  BASE_URI = "https://paymentauth.org/problems"
+
+  # Parse error for malformed payment headers.
+  class ParseError < StandardError; end
+
+  # Base verification error.
+  class VerificationError < StandardError; end
+
+  # Base class for all payment-related errors with RFC 9457 support.
+  class PaymentError < StandardError
+    extend T::Sig
+
+    sig { params(subclass: T::Class[T.anything]).returns(T.untyped) }
+    def self.inherited(subclass)
+      super
+      return if subclass.instance_variable_defined?(:@_mpp_configured)
+
+      subclass.instance_variable_set(:@_mpp_configured, true)
+      name = subclass.name&.split("::")&.last || "PaymentError"
+      unless subclass.instance_variable_defined?(:@type)
+        subclass.instance_variable_set(:@type,
+          "#{BASE_URI}/#{to_slug(name)}")
+      end
+      subclass.instance_variable_set(:@title, to_title(name)) unless subclass.instance_variable_defined?(:@title)
+      subclass.instance_variable_set(:@status, 402) unless subclass.instance_variable_defined?(:@status)
+    end
+
+    class << self
+      extend T::Sig
+
+      sig { returns(T.nilable(Integer)) }
+      attr_reader :status
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :type
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :title
+
+      private
+
+      sig { params(name: String).returns(String) }
+      def to_slug(name)
+        name.sub(/Error$/, "").gsub(/(?<=[a-z0-9])(?=[A-Z])/, "-").downcase
+      end
+
+      sig { params(name: String).returns(String) }
+      def to_title(name)
+        name.sub(/Error$/, "").gsub(/(?<=[a-z0-9])(?=[A-Z])/, " ")
+      end
+    end
+
+    @status = T.let(402, Integer)
+    @type = T.let("#{BASE_URI}/payment-error", String)
+    @title = T.let("Payment Error", String)
+
+    sig { returns(T.untyped) }
+    def status = self.class.status
+    sig { returns(T.untyped) }
+    def type = self.class.type
+    sig { returns(T.untyped) }
+    def title = self.class.title
+
+    # Convert to RFC 9457 Problem Details format.
+    sig { params(challenge_id: T.untyped).returns(T::Hash[T.untyped, T.untyped]) }
+    def to_problem_details(challenge_id: nil)
+      details = {
+        "type" => type,
+        "title" => title,
+        "status" => status,
+        "detail" => message
+      }
+      details["challengeId"] = challenge_id if challenge_id
+      details
+    end
+  end
+
+  class PaymentRequiredError < PaymentError
+    extend T::Sig
+
+    sig { params(realm: T.untyped, description: T.untyped).void }
+    def initialize(realm: nil, description: nil)
+      parts = ["Payment is required"]
+      parts << "for \"#{realm}\"" if realm
+      parts << "(#{description})" if description
+      super("#{parts.join(" ")}.")
+    end
+  end
+
+  class MalformedCredentialError < PaymentError
+    extend T::Sig
+
+    sig { params(reason: T.untyped).void }
+    def initialize(reason: nil)
+      msg = reason ? "Credential is malformed: #{reason}." : "Credential is malformed."
+      super(msg)
+    end
+  end
+
+  class InvalidChallengeError < PaymentError
+    extend T::Sig
+
+    sig { params(challenge_id: T.untyped, reason: T.untyped).void }
+    def initialize(challenge_id: nil, reason: nil)
+      id_part = challenge_id ? " \"#{challenge_id}\"" : ""
+      reason_part = reason ? ": #{reason}" : ""
+      super("Challenge#{id_part} is invalid#{reason_part}.")
+    end
+  end
+
+  class VerificationFailedError < PaymentError
+    extend T::Sig
+
+    sig { params(reason: T.untyped).void }
+    def initialize(reason: nil)
+      msg = reason ? "Payment verification failed: #{reason}." : "Payment verification failed."
+      super(msg)
+    end
+  end
+
+  class PaymentExpiredError < PaymentError
+    extend T::Sig
+
+    sig { params(expires: T.untyped).void }
+    def initialize(expires: nil)
+      msg = expires ? "Payment expired at #{expires}." : "Payment has expired."
+      super(msg)
+    end
+  end
+
+  class InvalidPayloadError < PaymentError
+    extend T::Sig
+
+    sig { params(reason: T.untyped).void }
+    def initialize(reason: nil)
+      msg = reason ? "Credential payload is invalid: #{reason}." : "Credential payload is invalid."
+      super(msg)
+    end
+  end
+
+  class BadRequestError < PaymentError
+    extend T::Sig
+
+    @status = T.let(400, Integer)
+
+    sig { params(reason: T.untyped).void }
+    def initialize(reason: nil)
+      msg = reason ? "Bad request: #{reason}." : "Bad request."
+      super(msg)
+    end
+  end
+
+  class PaymentInsufficientError < PaymentError
+    extend T::Sig
+
+    sig { params(reason: T.untyped).void }
+    def initialize(reason: nil)
+      msg = reason ? "Payment insufficient: #{reason}." : "Payment amount is insufficient."
+      super(msg)
+    end
+  end
+
+  class PaymentMethodUnsupportedError < PaymentError
+    extend T::Sig
+
+    @status = T.let(400, Integer)
+    @type = T.let("#{BASE_URI}/method-unsupported", String)
+    @title = T.let("Method Unsupported", String)
+
+    sig { params(method: T.untyped).void }
+    def initialize(method: nil)
+      msg = method ? "Payment method \"#{method}\" is not supported." : "Payment method is not supported."
+      super(msg)
+    end
+  end
+
+  class PaymentActionRequiredError < PaymentError
+    extend T::Sig
+
+    sig { params(reason: T.untyped).void }
+    def initialize(reason: nil)
+      msg = reason ? "Payment requires action: #{reason}." : "Payment requires action."
+      super(msg)
+    end
+  end
+end

data/lib/mpp/expires.rb

@@ -0,0 +1,60 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "time"
+
+module Mpp
+  module Expires
+    extend T::Sig
+
+    module_function
+
+    # Format a Time as ISO 8601 with Z suffix and millisecond precision.
+    sig { params(time: Time).returns(String) }
+    def to_iso(time)
+      time.utc.strftime("%Y-%m-%dT%H:%M:%S.%LZ")
+    end
+
+    # Returns an ISO 8601 datetime string n seconds from now.
+    sig { params(n: BasicObject).returns(T.untyped) }
+    def seconds(n)
+      to_iso(Time.now.utc + n)
+    end
+
+    # Returns an ISO 8601 datetime string n minutes from now.
+    sig { params(n: Numeric).returns(String) }
+    def minutes(n)
+      to_iso(Time.now.utc + (n * 60))
+    end
+
+    # Returns an ISO 8601 datetime string n hours from now.
+    sig { params(n: Numeric).returns(String) }
+    def hours(n)
+      to_iso(Time.now.utc + (n * 3600))
+    end
+
+    # Returns an ISO 8601 datetime string n days from now.
+    sig { params(n: Numeric).returns(String) }
+    def days(n)
+      to_iso(Time.now.utc + (n * 86_400))
+    end
+
+    # Returns an ISO 8601 datetime string n weeks from now.
+    sig { params(n: Numeric).returns(String) }
+    def weeks(n)
+      to_iso(Time.now.utc + (n * 7 * 86_400))
+    end
+
+    # Returns an ISO 8601 datetime string n months (30 days) from now.
+    sig { params(n: Numeric).returns(String) }
+    def months(n)
+      to_iso(Time.now.utc + (n * 30 * 86_400))
+    end
+
+    # Returns an ISO 8601 datetime string n years (365 days) from now.
+    sig { params(n: Numeric).returns(String) }
+    def years(n)
+      to_iso(Time.now.utc + (n * 365 * 86_400))
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Mpp
+  module Extensions
+    module MCP
+      extend T::Sig
+
+      module_function
+
+      # Build payment capabilities object for MCP.
+      sig { params(methods: T.untyped, intents: T.untyped).returns(T::Hash[T.untyped, T.untyped]) }
+      def payment_capabilities(methods, intents)
+        {
+          "payment" => {
+            "methods" => methods,
+            "intents" => intents
+          }
+        }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Mpp
+  module Extensions
+    module MCP
+      META_CREDENTIAL = "org.paymentauth/credential"
+      META_RECEIPT = "org.paymentauth/receipt"
+
+      CODE_PAYMENT_REQUIRED = -32_042
+      CODE_PAYMENT_VERIFICATION_FAILED = -32_043
+      CODE_MALFORMED_CREDENTIAL = -32_602
+
+      HTTP_STATUS_PAYMENT_REQUIRED = 402
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Mpp
+  module Extensions
+    module MCP
+      extend T::Sig
+
+      module_function
+
+      # Wrapper for MCP tool handlers with payment verification.
+      #
+      # Usage:
+      #   result = Mpp::Extensions::MCP.pay(mpp_handler, meta: params["_meta"],
+      #     request: { "amount" => "1000" }, realm: "api.example.com") do |credential, receipt|
+      #     # execute tool
+      #   end
+      sig { params(intent: T.untyped, request: T.untyped, meta: T.untyped, realm: T.nilable(String), secret_key: T.nilable(String), method: T.nilable(String), expires_in: Integer, description: T.nilable(String), blk: T.untyped).returns(T.untyped) }
+      def pay_tool(intent:, request:, meta:, realm: nil, secret_key: nil,
+        method: nil, expires_in: DEFAULT_CHALLENGE_TTL, description: nil, &blk)
+        resolved_realm = realm || Mpp::Server::Defaults.detect_realm
+        resolved_secret_key = secret_key || Mpp::Server::Defaults.detect_secret_key
+
+        request_params = request.respond_to?(:call) ? request.call : request
+
+        result = verify_or_challenge(
+          meta: meta,
+          intent: intent,
+          request: request_params,
+          realm: resolved_realm,
+          secret_key: resolved_secret_key,
+          method: method,
+          expires_in: expires_in,
+          description: description
+        )
+
+        Kernel.raise PaymentRequiredError.new(challenges: [result]) if result.is_a?(MCPChallenge)
+
+        credential, receipt = result
+        yield credential, receipt
+      end
+    end
+  end
+end

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

@@ -0,0 +1,110 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Mpp
+  module Extensions
+    module MCP
+      class PaymentRequiredError < StandardError
+        extend T::Sig
+
+        sig { returns(T.untyped) }
+        attr_reader :challenges
+
+        sig { returns(Integer) }
+        attr_reader :code
+
+        sig { params(challenges: T.untyped, message: BasicObject).void }
+        def initialize(challenges:, message: "Payment Required")
+          @challenges = T.let(challenges, T.untyped)
+          @code = T.let(CODE_PAYMENT_REQUIRED, Integer)
+          super(message)
+        end
+
+        sig { returns(T::Hash[T.untyped, T.untyped]) }
+        def to_jsonrpc_error
+          {
+            "code" => CODE_PAYMENT_REQUIRED,
+            "message" => message,
+            "data" => {
+              "httpStatus" => HTTP_STATUS_PAYMENT_REQUIRED,
+              "challenges" => @challenges.map(&:to_dict)
+            }
+          }
+        end
+      end
+
+      class PaymentVerificationError < StandardError
+        extend T::Sig
+
+        sig { returns(T.untyped) }
+        attr_reader :challenges
+
+        sig { returns(T.untyped) }
+        attr_reader :reason
+
+        sig { returns(T.untyped) }
+        attr_reader :detail
+
+        sig { returns(Integer) }
+        attr_reader :code
+
+        sig { params(challenges: T.untyped, reason: T.untyped, detail: T.untyped, message: BasicObject).void }
+        def initialize(challenges:, reason: nil, detail: nil, message: "Payment Verification Failed")
+          @challenges = T.let(challenges, T.untyped)
+          @reason = T.let(reason, T.untyped)
+          @detail = T.let(detail, T.untyped)
+          @code = T.let(CODE_PAYMENT_VERIFICATION_FAILED, Integer)
+          super(message)
+        end
+
+        sig { returns(T::Hash[T.untyped, T.untyped]) }
+        def to_jsonrpc_error
+          data = {
+            "httpStatus" => HTTP_STATUS_PAYMENT_REQUIRED,
+            "challenges" => @challenges.map(&:to_dict)
+          }
+          if @reason || @detail
+            failure = {}
+            failure["reason"] = @reason if @reason
+            failure["detail"] = @detail if @detail
+            data["failure"] = failure
+          end
+          {
+            "code" => CODE_PAYMENT_VERIFICATION_FAILED,
+            "message" => message,
+            "data" => data
+          }
+        end
+      end
+
+      class MalformedCredentialError < StandardError
+        extend T::Sig
+
+        sig { returns(T.untyped) }
+        attr_reader :detail
+
+        sig { returns(Integer) }
+        attr_reader :code
+
+        sig { params(detail: T.untyped, message: BasicObject).void }
+        def initialize(detail:, message: "Invalid params")
+          @detail = T.let(detail, T.untyped)
+          @code = T.let(CODE_MALFORMED_CREDENTIAL, Integer)
+          super(message)
+        end
+
+        sig { returns(T::Hash[T.untyped, T.untyped]) }
+        def to_jsonrpc_error
+          {
+            "code" => CODE_MALFORMED_CREDENTIAL,
+            "message" => message,
+            "data" => {
+              "httpStatus" => HTTP_STATUS_PAYMENT_REQUIRED,
+              "detail" => @detail
+            }
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,205 @@
+# typed: true
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "time"
+
+module Mpp
+  module Extensions
+    module MCP
+      MCPChallenge = Data.define(:id, :realm, :method, :intent, :request,
+        :expires, :description, :digest, :opaque) do
+        def initialize(id:, realm:, method:, intent:, request:,
+          expires: nil, description: nil, digest: nil, opaque: nil)
+          super
+        end
+
+        def to_dict
+          result = {
+            "id" => id,
+            "realm" => realm,
+            "method" => method,
+            "intent" => intent,
+            "request" => request
+          }
+          result["expires"] = expires if expires
+          result["description"] = description if description
+          result["digest"] = digest if digest
+          result["opaque"] = opaque if opaque
+          result
+        end
+
+        def self.from_dict(data)
+          new(
+            id: data["id"],
+            realm: data["realm"],
+            method: data["method"],
+            intent: data["intent"],
+            request: data["request"],
+            expires: data["expires"],
+            description: data["description"],
+            digest: data["digest"],
+            opaque: data["opaque"]
+          )
+        end
+
+        def to_core
+          Mpp::Challenge.new(
+            id: id,
+            method: method,
+            intent: intent,
+            request: request,
+            digest: digest,
+            opaque: opaque
+          )
+        end
+
+        def self.from_core(challenge, realm, expires: nil, description: nil)
+          new(
+            id: challenge.id,
+            realm: realm,
+            method: challenge.method,
+            intent: challenge.intent,
+            request: challenge.request,
+            expires: expires,
+            description: description,
+            digest: challenge.digest,
+            opaque: challenge.opaque
+          )
+        end
+      end
+
+      MCPCredential = Data.define(:challenge, :payload, :source) do
+        def initialize(challenge:, payload:, source: nil)
+          super
+        end
+
+        def to_dict
+          result = {
+            "challenge" => challenge.to_dict,
+            "payload" => payload
+          }
+          result["source"] = source if source
+          result
+        end
+
+        def to_meta
+          {META_CREDENTIAL => to_dict}
+        end
+
+        def self.from_dict(data)
+          new(
+            challenge: MCPChallenge.from_dict(data["challenge"]),
+            payload: data["payload"],
+            source: data["source"]
+          )
+        end
+
+        def self.from_meta(meta)
+          return nil unless meta.key?(META_CREDENTIAL)
+
+          from_dict(meta[META_CREDENTIAL])
+        end
+
+        def to_core
+          request_json = Mpp::Json.compact_encode(challenge.request)
+          request_b64 = Base64.urlsafe_encode64(request_json, padding: false)
+
+          opaque_b64 = nil
+          if challenge.opaque
+            opaque_json = Mpp::Json.compact_encode(challenge.opaque)
+            opaque_b64 = Base64.urlsafe_encode64(opaque_json, padding: false)
+          end
+
+          echo = Mpp::ChallengeEcho.new(
+            id: challenge.id,
+            realm: challenge.realm,
+            method: challenge.method,
+            intent: challenge.intent,
+            request: request_b64,
+            expires: challenge.expires,
+            digest: challenge.digest,
+            opaque: opaque_b64
+          )
+          Mpp::Credential.new(
+            challenge: echo,
+            payload: payload,
+            source: source
+          )
+        end
+
+        def self.from_core(credential, challenge)
+          new(
+            challenge: challenge,
+            payload: credential.payload,
+            source: credential.source
+          )
+        end
+      end
+
+      MCPReceipt = Data.define(:status, :challenge_id, :method, :timestamp,
+        :reference, :settlement) do
+        def initialize(status:, challenge_id:, method:, timestamp:,
+          reference: nil, settlement: nil)
+          super
+        end
+
+        def to_dict
+          result = {
+            "status" => status,
+            "challengeId" => challenge_id,
+            "method" => method,
+            "timestamp" => timestamp
+          }
+          result["reference"] = reference if reference
+          result["settlement"] = settlement if settlement
+          result
+        end
+
+        def to_meta
+          {META_RECEIPT => to_dict}
+        end
+
+        def self.from_dict(data)
+          new(
+            status: data["status"],
+            challenge_id: data["challengeId"],
+            method: data["method"],
+            timestamp: data["timestamp"],
+            reference: data["reference"],
+            settlement: data["settlement"]
+          )
+        end
+
+        def self.from_meta(meta)
+          return nil unless meta.key?(META_RECEIPT)
+
+          from_dict(meta[META_RECEIPT])
+        end
+
+        def to_core
+          Mpp::Receipt.new(
+            status: status,
+            timestamp: Time.iso8601(timestamp.gsub("Z", "+00:00")),
+            reference: reference || ""
+          )
+        end
+
+        def self.from_core(receipt, challenge_id:, method:, settlement: nil)
+          ts = receipt.timestamp.utc.iso8601
+          ts = ts.sub(/\+00:00$/, "Z")
+
+          new(
+            status: receipt.status,
+            challenge_id: challenge_id,
+            method: method,
+            timestamp: ts,
+            reference: receipt.reference.empty? ? nil : receipt.reference,
+            settlement: settlement
+          )
+        end
+      end
+    end
+  end
+end