mpp-rb 0.1.5 → 0.1.6

data/lib/mpp/server/mpp_handler.rb

@@ -10,7 +10,7 @@ module Mpp
     class MppHandler
       extend T::Sig
 
-      REQUEST_OPTION_KEYS = [:body, :url, :payment_signature, :accept_payment, :http_method].freeze
+      REQUEST_OPTION_KEYS = [:body, :url, :payment_signature, :accept_payment, :http_method, :payment_authorization].freeze
 
       sig { returns(T.untyped) }
       attr_reader :method
@@ -27,6 +27,12 @@ module Mpp
       sig { returns(T::Hash[String, T.untyped]) }
       attr_reader :defaults
 
+      sig { returns(T::Boolean) }
+      attr_reader :requires_auth
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :credential_header
+
       sig do
         params(
           realm: String,
@@ -34,16 +40,21 @@ module Mpp
           method: T.untyped,
           methods: T.nilable(T::Array[T.untyped]),
           defaults: T.nilable(T::Hash[String, T.untyped]),
-          events: T.nilable(Mpp::Events::Dispatcher)
+          events: T.nilable(Mpp::Events::Dispatcher),
+          requires_auth: T::Boolean
         ).void
       end
-      def initialize(realm:, secret_key:, method: nil, methods: nil, defaults: nil, events: nil)
+      def initialize(realm:, secret_key:, method: nil, methods: nil, defaults: nil, events: nil, requires_auth: false)
         @methods = T.let(normalize_methods(method, methods), T::Array[T.untyped])
         @method = T.let(@methods.first, T.untyped)
         @realm = T.let(realm, String)
         @secret_key = T.let(secret_key, String)
         @defaults = T.let(defaults || {}, T::Hash[String, T.untyped])
         @events = T.let(events || Mpp::Events.server_dispatcher, Mpp::Events::Dispatcher)
+        @method_hook_events = T.let(Mpp::Events.server_dispatcher, Mpp::Events::Dispatcher)
+        @requires_auth = T.let(requires_auth, T::Boolean)
+        @credential_header = T.let(requires_auth ? Mpp::PAYMENT_AUTHORIZATION_HEADER : nil, T.nilable(String))
+        register_method_payment_success
       end
 
       # Create with auto-detected realm and secret_key.
@@ -53,16 +64,18 @@ module Mpp
           methods: T.nilable(T::Array[T.untyped]),
           realm: T.untyped,
           secret_key: T.untyped,
-          events: T.nilable(Mpp::Events::Dispatcher)
+          events: T.nilable(Mpp::Events::Dispatcher),
+          requires_auth: T::Boolean
         ).returns(T.attached_class)
       end
-      def self.create(method: nil, methods: nil, realm: nil, secret_key: nil, events: nil)
+      def self.create(method: nil, methods: nil, realm: nil, secret_key: nil, events: nil, requires_auth: false)
         new(
           method: method,
           methods: methods,
           realm: realm || Defaults.detect_realm,
           secret_key: secret_key || Defaults.detect_secret_key,
-          events: events
+          events: events,
+          requires_auth: requires_auth
         )
       end
 
@@ -86,6 +99,14 @@ module Mpp
         on(Mpp::Events::PAYMENT_SUCCESS, handler, &block)
       end
 
+      # Select the HTTP header value that carries the Payment credential.
+      # When requires_auth is true, Payment credentials ride in
+      # Payment-Authorization so Authorization can hold application auth.
+      sig { params(authorization: T.nilable(String), payment_authorization: T.nilable(String)).returns(T.nilable(String)) }
+      def payment_credential_value(authorization, payment_authorization = nil)
+        @requires_auth ? payment_authorization : authorization
+      end
+
       # Combine method offers into a single callable that presents every method.
       sig { params(entries: T.untyped).returns(ComposedHandler) }
       def compose(*entries)
@@ -119,11 +140,12 @@ module Mpp
 
         request_opts = kwargs.slice(*REQUEST_OPTION_KEYS)
         offer_opts = kwargs.except(*REQUEST_OPTION_KEYS)
+        payment = payment_credential_value(authorization, request_opts[:payment_authorization])
 
         if charge_methods.length == 1
           return charge_one(
             charge_methods.first,
-            authorization,
+            payment,
             amount,
             **request_opts,
             **offer_opts
@@ -133,6 +155,7 @@ module Mpp
         entries = charge_methods.map { |candidate| [candidate, offer_opts.merge(amount: amount)] }
         ComposedHandler.from_entries(self, entries).call(
           authorization: authorization,
+          payment_authorization: request_opts[:payment_authorization],
           payment_signature: request_opts[:payment_signature],
           body: request_opts[:body],
           url: request_opts[:url],
@@ -142,8 +165,10 @@ module Mpp
       end
 
       # Verify or challenge a single method. Used by compose and charge.
-      sig { params(method: T.untyped, authorization: T.nilable(String), amount: String, kwargs: T.untyped).returns(T.untyped) }
-      def charge_one(method, authorization, amount, **kwargs)
+      # The optional request guard can omit an offer after its canonical request
+      # is built, ensuring the guard and challenge use the exact same request.
+      sig { params(method: T.untyped, authorization: T.nilable(String), amount: String, kwargs: T.untyped, request_guard: T.nilable(T.proc.params(request: T::Hash[String, T.untyped]).returns(T::Boolean))).returns(T.untyped) }
+      def charge_one(method, authorization, amount, **kwargs, &request_guard)
         intent = method.intents["charge"]
         raise ArgumentError, "Method #{method.name} does not support charge intent" unless intent
 
@@ -152,6 +177,7 @@ module Mpp
         payment_signature = kwargs[:payment_signature]
         offer_opts = kwargs.except(*REQUEST_OPTION_KEYS)
         request = build_charge_request(method, amount, **offer_opts)
+        return nil if request_guard && !request_guard.call(request)
 
         if payment_signature && method.respond_to?(:bind_x402_credential)
           return verify_x402(
@@ -177,7 +203,9 @@ module Mpp
           description: offer_opts[:description],
           expires: offer_opts[:expires],
           events: @events,
-          body: body
+          method_hook_events: @method_hook_events,
+          body: body,
+          header: @credential_header
         )
       end
 
@@ -304,7 +332,8 @@ module Mpp
           description,
           nil,
           expires,
-          body
+          body,
+          @credential_header
         )
         method_context = {name: method.name, intent: intent.name}
 
@@ -346,9 +375,10 @@ module Mpp
           raise
         end
 
-        if @events.has_handlers?(Mpp::Events::PAYMENT_SUCCESS)
+        if @events.has_handlers?(Mpp::Events::PAYMENT_SUCCESS) || @method_hook_events.has_handlers?(Mpp::Events::PAYMENT_SUCCESS)
           Verify.emit_payment_success(
             dispatcher: @events,
+            method_hook_dispatcher: @method_hook_events,
             challenge: challenge,
             credential: credential,
             method: method_context,
@@ -358,6 +388,30 @@ module Mpp
         end
         [credential, receipt]
       end
+
+      private
+
+      sig { void }
+      def register_method_payment_success
+        @methods.each do |payment_method|
+          next unless payment_method.respond_to?(:on_payment_success)
+
+          hook = payment_method.on_payment_success
+          next if hook.nil?
+          raise ArgumentError, "on_payment_success must be callable" unless hook.respond_to?(:call)
+
+          method_name = payment_method.name
+          intent_names = payment_method.intents.each_value.map { |intent| intent.name }
+          @method_hook_events.on(Mpp::Events::PAYMENT_SUCCESS) do |payload|
+            event_method = payload[:method]
+            next unless event_method.is_a?(Hash)
+            next unless event_method[:name] == method_name
+            next unless intent_names.include?(event_method[:intent])
+
+            hook.call(payload)
+          end
+        end
+      end
     end
   end
 end

data/lib/mpp/server/verify.rb

@@ -15,17 +15,17 @@ module Mpp
       # 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), events: T.nilable(Mpp::Events::Dispatcher), body: T.untyped).returns(T.untyped) }
+      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), events: T.nilable(Mpp::Events::Dispatcher), method_hook_events: T.nilable(Mpp::Events::Dispatcher), body: T.untyped, header: T.nilable(String)).returns(T.untyped) }
       def verify_or_challenge(authorization:, intent:, request:, realm:, secret_key:,
-        method: nil, description: nil, meta: nil, expires: nil, events: nil, body: nil)
+        method: nil, description: nil, meta: nil, expires: nil, events: nil, method_hook_events: nil, body: nil, header: nil)
         method_name = method || "tempo"
         request = Mpp::Units.transform_units(request)
         dispatcher = events
-        events_enabled = dispatcher&.has_handlers?
+        events_enabled = dispatcher&.has_handlers? || method_hook_events&.has_handlers?
         method_context = events_enabled ? {name: method_name, intent: intent.name} : nil
 
         new_challenge = Kernel.lambda { |credential = nil, error = nil, submitted_challenge = nil|
-          challenge = create_challenge(method_name, intent.name, request, realm, secret_key, description, meta, expires, body)
+          challenge = create_challenge(method_name, intent.name, request, realm, secret_key, description, meta, expires, body, header)
           if error && dispatcher&.has_handlers?(Mpp::Events::PAYMENT_FAILED)
             emit_payment_failed(
               dispatcher: dispatcher,
@@ -79,7 +79,8 @@ module Mpp
           request: echo_request,
           expires: echo.expires,
           digest: echo.digest,
-          opaque: echo_opaque
+          opaque: echo_opaque,
+          header: echo.header
         )
         unless Mpp.secure_compare(echo.id, expected_id)
           return new_challenge.call(
@@ -172,9 +173,10 @@ module Mpp
           end
           Kernel.raise
         end
-        if dispatcher&.has_handlers?(Mpp::Events::PAYMENT_SUCCESS)
+        if dispatcher&.has_handlers?(Mpp::Events::PAYMENT_SUCCESS) || method_hook_events&.has_handlers?(Mpp::Events::PAYMENT_SUCCESS)
           emit_payment_success(
             dispatcher: dispatcher,
+            method_hook_dispatcher: method_hook_events,
             challenge: echo,
             credential: credential,
             method: T.must(method_context),
@@ -185,9 +187,9 @@ module Mpp
         [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), body: T.untyped).returns(Mpp::Challenge) }
+      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), body: T.untyped, header: T.nilable(String)).returns(Mpp::Challenge) }
       def create_challenge(method, intent_name, request, realm, secret_key,
-        description = nil, meta = nil, expires = nil, body = nil)
+        description = nil, meta = nil, expires = nil, body = nil, header = nil)
         expires = nil if expires && !expires.is_a?(String)
 
         if expires.nil?
@@ -205,7 +207,8 @@ module Mpp
           expires: expires,
           digest: digest,
           description: description,
-          meta: meta
+          meta: meta,
+          header: header
         )
       end
 
@@ -258,17 +261,24 @@ module Mpp
         dispatcher.emit(Mpp::Events::PAYMENT_FAILED, payload)
       end
 
-      sig { params(dispatcher: Mpp::Events::Dispatcher, challenge: T.untyped, credential: T.untyped, method: T::Hash[Symbol, T.untyped], receipt: T.untyped, request: T::Hash[String, T.untyped]).void }
-      def emit_payment_success(dispatcher:, challenge:, credential:, method:, receipt:, request:)
-        return unless dispatcher.has_handlers?(Mpp::Events::PAYMENT_SUCCESS)
+      # Method hooks are owned by a handler, while `dispatcher` may be shared
+      # by many handlers. Emit the same payload to each without exposing that
+      # handler ownership in the public event payload.
+      sig { params(dispatcher: T.nilable(Mpp::Events::Dispatcher), challenge: T.untyped, credential: T.untyped, method: T::Hash[Symbol, T.untyped], receipt: T.untyped, request: T::Hash[String, T.untyped], method_hook_dispatcher: T.nilable(Mpp::Events::Dispatcher)).void }
+      def emit_payment_success(dispatcher:, challenge:, credential:, method:, receipt:, request:, method_hook_dispatcher: nil)
+        public_handlers = dispatcher&.has_handlers?(Mpp::Events::PAYMENT_SUCCESS)
+        hook_handlers = method_hook_dispatcher&.has_handlers?(Mpp::Events::PAYMENT_SUCCESS)
+        return unless public_handlers || hook_handlers
 
-        dispatcher.emit(Mpp::Events::PAYMENT_SUCCESS, {
+        payload = {
           challenge: challenge,
           credential: credential,
           method: method,
           receipt: receipt,
           request: request
-        })
+        }
+        dispatcher.emit(Mpp::Events::PAYMENT_SUCCESS, payload) if public_handlers
+        method_hook_dispatcher.emit(Mpp::Events::PAYMENT_SUCCESS, payload) if hook_handlers && method_hook_dispatcher != dispatcher
       end
     end
   end

data/lib/mpp/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module Mpp
-  VERSION = "0.1.5"
+  VERSION = "0.1.6"
 end

data/lib/mpp.rb

@@ -11,6 +11,9 @@ require_relative "mpp/secure_compare"
 module Mpp
   extend T::Sig
 
+  AUTHORIZATION_HEADER = T.let("Authorization", String)
+  PAYMENT_AUTHORIZATION_HEADER = T.let("Payment-Authorization", String)
+
   autoload :Challenge, "mpp/challenge"
   autoload :ChallengeEcho, "mpp/challenge_echo"
   autoload :Credential, "mpp/credential"
@@ -43,9 +46,16 @@ module Mpp
     autoload :MCP, "mpp/extensions/mcp"
   end
 
-  sig { params(method: T.untyped, methods: T.nilable(T::Array[T.untyped]), realm: T.untyped, secret_key: T.untyped, events: T.nilable(Mpp::Events::Dispatcher)).returns(T.untyped) }
-  def self.create(method: nil, methods: nil, realm: nil, secret_key: nil, events: nil)
-    Server::MppHandler.create(method: method, methods: methods, realm: realm, secret_key: secret_key, events: events)
+  sig { params(method: T.untyped, methods: T.nilable(T::Array[T.untyped]), realm: T.untyped, secret_key: T.untyped, events: T.nilable(Mpp::Events::Dispatcher), requires_auth: T::Boolean).returns(T.untyped) }
+  def self.create(method: nil, methods: nil, realm: nil, secret_key: nil, events: nil, requires_auth: false)
+    Server::MppHandler.create(
+      method: method,
+      methods: methods,
+      realm: realm,
+      secret_key: secret_key,
+      events: events,
+      requires_auth: requires_auth
+    )
   end
 
   # Error hierarchy

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mpp-rb
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.6
 platform: ruby
 authors:
 - Stripe
@@ -37,6 +37,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: sorbet-runtime
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Ruby SDK for the Machine Payments Protocol (MPP) — an HTTP 402 Payment
   Authentication scheme.
 executables: []
@@ -75,7 +89,9 @@ files:
 - lib/mpp/methods/stripe.rb
 - lib/mpp/methods/stripe/charge_intent.rb
 - lib/mpp/methods/stripe/client_method.rb
+- lib/mpp/methods/stripe/crypto_payment_recorder.rb
 - lib/mpp/methods/stripe/defaults.rb
+- lib/mpp/methods/stripe/machine_payments.rb
 - lib/mpp/methods/stripe/stripe_method.rb
 - lib/mpp/methods/tempo.rb
 - lib/mpp/methods/tempo/account.rb