onlinepayments-sdk-ruby 3.0.0

data/lib/onlinepayments/sdk/webhooks/signature_validation_exception.rb

@@ -0,0 +1,19 @@
+module OnlinePayments::SDK
+  module Webhooks
+
+    # Raised when an error occurred when validating Webhooks signatures
+    class SignatureValidationException < RuntimeError
+
+      # Creates a new SignatureValidationException
+      #
+      # @param [Hash] args the options to create the Exception with
+      # @option args [String] :message the error message
+      # @option args [RuntimeError] :cause an Error object that causes the Exception
+      def initialize(args)
+        super(args[:message]) # NOTE: can be nil
+        # store backtrace info if exception given
+        set_backtrace(args[:cause].backtrace) if args[:cause]
+      end
+    end
+  end
+end

data/lib/onlinepayments/sdk/webhooks/webhooks.rb

@@ -0,0 +1,22 @@
+module OnlinePayments::SDK
+  module Webhooks
+    # Online Payments platform factory for several webhooks components
+    module Webhooks
+      DefaultMarshaller ||= OnlinePayments::SDK::DefaultImpl::DefaultMarshaller
+
+      # Creates a WebhooksHelperBuilder that uses the
+      # given SecretkeyStore
+      def self.create_helper_builder(secret_key_store)
+        WebhooksHelperBuilder.new
+                             .with_marshaller(DefaultMarshaller.INSTANCE)
+                             .with_secret_key_store(secret_key_store)
+      end
+
+      # Creates a WebhooksHelper that uses the given
+      # SecretkeyStore.
+      def self.create_helper(secret_key_store)
+        create_helper_builder(secret_key_store).build
+      end
+    end
+  end
+end

data/lib/onlinepayments/sdk/webhooks/webhooks_event.rb

@@ -0,0 +1,58 @@
+module OnlinePayments::SDK
+  module Webhooks
+
+    # @attr [String] api_version
+    # @attr [String] id
+    # @attr [String] created
+    # @attr [String] merchant_id
+    # @attr [String] type
+    # @attr [OnlinePayments::SDK::Domain::PaymentResponse] payment
+    # @attr [OnlinePayments::SDK::Domain::PayoutResponse] refund
+    # @attr [OnlinePayments::SDK::Domain::RefundResponse] payout
+    # @attr [OnlinePayments::SDK::Domain::TokenResponse] token
+    # @attr [OnlinePayments::SDK::Domain::DisputeResponse] dispute
+    class WebhooksEvent < OnlinePayments::SDK::DataObject
+
+      attr_accessor :api_version
+      attr_accessor :id
+      attr_accessor :created
+      attr_accessor :merchant_id
+      attr_accessor :type
+
+      attr_accessor :payment
+      attr_accessor :refund
+      attr_accessor :payout
+      attr_accessor :token
+      attr_accessor :dispute
+
+      # @return [Hash]
+      def to_h
+        hash = super
+        hash['apiVersion'] = @api_version if @api_version
+        hash['id'] = @id if @id
+        hash['created'] = @created if @created
+        hash['merchantId'] = @merchant_id if @merchant_id
+        hash['type'] = @type if @type
+        hash['payment'] = @payment.to_h if @payment
+        hash['refund'] = @refund.to_h if @refund
+        hash['payout'] = @payout.to_h if @payout
+        hash['token'] = @token.to_h if @token
+        hash['dispute'] = @dispute.to_h if @dispute
+        hash
+      end
+
+      def from_hash(hash)
+        super
+        @api_version = hash['apiVersion'] if hash.key? 'apiVersion'
+        @id = hash['id'] if hash.key? 'id'
+        @created = hash['created'] if hash.key? 'created'
+        @merchant_id = hash['merchantId'] if hash.key? 'merchantId'
+        @type = hash['type'] if hash.key? 'type'
+        @payment = OnlinePayments::SDK::Domain::PaymentResponse.new_from_hash(hash['payment']) if hash.key? 'payment'
+        @refund = OnlinePayments::SDK::Domain::RefundResponse.new_from_hash(hash['refund']) if hash.key? 'refund'
+        @payout = OnlinePayments::SDK::Domain::PayoutResponse.new_from_hash(hash['payout']) if hash.key? 'payout'
+        @token = OnlinePayments::SDK::Domain::TokenResponse.new_from_hash(hash['token']) if hash.key? 'token'
+      end
+    end
+  end
+end

data/lib/onlinepayments/sdk/webhooks/webhooks_helper.rb

@@ -0,0 +1,100 @@
+require 'openssl'
+require 'base64'
+
+module OnlinePayments::SDK
+  module Webhooks
+
+    # Online Payments platform webhooks Helper, Thread-safe.
+    class WebhooksHelper
+      def initialize(marshaller, secret_key_store)
+        raise ArgumentError unless marshaller
+        raise ArgumentError unless secret_key_store
+        @marshaller = marshaller
+        @secret_key_store = secret_key_store
+      end
+
+      # Unmarshals the given body, while also validating it using the given request headers.
+      #
+      # @param body            [String] body of the request
+      # @param request_headers [Array<OnlinePayments::SDK::RequestHeader>] headers of the request
+      def unmarshal(body, request_headers)
+        validate(body, request_headers)
+        event = @marshaller.unmarshal(body, WebhooksEvent)
+        validate_api_version(event)
+        event
+      end
+
+      # Validates incoming request using request headers
+      #
+      # @param body            [String] body of the request
+      # @param request_headers [Array<OnlinePayments::SDK::RequestHeader>] headers of the request
+      def validate(body, request_headers)
+        validate_body(body, request_headers)
+      end
+
+      private
+
+      HEADER_SIGNATURE = 'X-GCS-Signature'.freeze
+      HEADER_KEY_ID = 'X-GCS-KeyId'.freeze
+      HMAC_SCHEME = 'SHA256'.freeze
+
+      # validation utility methods
+
+      # Validates the body using given request headers
+      #
+      # @param body            [String] body of the request
+      # @param request_headers [Array<OnlinePayments::SDK::RequestHeader>] headers of the request
+      def validate_body(body, request_headers)
+        signature = get_header_value(request_headers, HEADER_SIGNATURE)
+        key_id = get_header_value(request_headers, HEADER_KEY_ID)
+        secret_key = @secret_key_store.get_secret_key(key_id)
+        digest = OpenSSL::Digest.new(HMAC_SCHEME)
+        hmac = OpenSSL::HMAC.digest(digest, secret_key, body)
+        expected_signature = Base64.strict_encode64(hmac).strip
+
+        unless equal_signatures?(signature, expected_signature)
+          msg = "failed to validate signature '#{signature}'"
+          raise SignatureValidationException, message: msg
+        end
+      end
+
+      # Checks two signatures
+      #
+      # @param signature          [String]
+      # @param expected_signature [String]
+      def equal_signatures?(signature, expected_signature)
+        # NOTE: copy the signatures to avoid runtime tampering via references
+        signature = signature.dup.freeze
+        expected_signature = expected_signature.dup.freeze
+        # NOTE: do not use simple equality comparision to avoid side channel attack
+        limit = [signature.length, expected_signature.length, 256].max
+        limit.times.inject(true) do |flag, idx|
+          # NOTE: this block is constructed to take constant time to run
+          flag &= signature[idx] == expected_signature[idx]
+          # [] returns nil if idx >= the length of the String
+        end
+      end
+
+      # general utility methods
+
+      # Returns true if the client API version and the webhooks event API version matches
+      def validate_api_version(event)
+        raise ApiVersionMismatchException.new event.api_version, 'v1' unless 'v1'.eql?(event.api_version)
+      end
+
+      # Retrieves header value from the request headers whose header name matches the given parameter
+      def get_header_value(request_headers, header_name)
+        if (right_header = request_headers.select { |h| h.name.casecmp(header_name) == 0 }).size != 1
+          msg = if right_header.empty?
+                  "could not find header '#{header_name}'"
+                else
+                  # more than 2 headers
+                  "encountered multiple occurrences of header '#{header_name}'"
+                end
+          raise SignatureValidationException, message: msg
+        end
+        right_header.first.value
+      end
+    end
+  end
+end

data/lib/onlinepayments/sdk/webhooks/webhooks_helper_builder.rb

@@ -0,0 +1,25 @@
+module OnlinePayments::SDK
+  module Webhooks
+
+    # Builder for a WebhooksHelper object.
+    class WebhooksHelperBuilder
+
+      # Sets the Marshaller to use.
+      def with_marshaller(marshaller)
+        @marshaller = marshaller
+        self
+      end
+
+      # Sets the SecretkeyStore to use.
+      def with_secret_key_store(secret_key_store)
+        @secret_key_store = secret_key_store
+        self
+      end
+
+      # Creates a fully initialized WebhooksHelper object
+      def build
+        WebhooksHelper.new(@marshaller, @secret_key_store)
+      end
+    end
+  end
+end

data/lib/onlinepayments/sdk/webhooks.rb

@@ -0,0 +1,11 @@
+prefix = 'onlinepayments/sdk/webhooks'
+
+require "#{prefix}/api_version_mismatch_exception"
+require "#{prefix}/signature_validation_exception"
+require "#{prefix}/secret_key_not_available_exception"
+require "#{prefix}/secret_key_store"
+require "#{prefix}/in_memory_secret_key_store"
+require "#{prefix}/webhooks_event"
+require "#{prefix}/webhooks_helper"
+require "#{prefix}/webhooks_helper_builder"
+require "#{prefix}/webhooks"

data/lib/onlinepayments/sdk.rb

@@ -0,0 +1,26 @@
+prefix = 'onlinepayments/sdk'
+
+require "#{prefix}/logging"
+require "#{prefix}/exceptions"
+
+require "#{prefix}/marshaller"
+require "#{prefix}/response_header"
+require "#{prefix}/authenticator"
+require "#{prefix}/data_object"
+require "#{prefix}/proxy_configuration"
+require "#{prefix}/connection"
+require "#{prefix}/pooled_connection"
+require "#{prefix}/communicator"
+require "#{prefix}/endpoint_configuration"
+require "#{prefix}/communicator_configuration"
+require "#{prefix}/client"
+require "#{prefix}/call_context"
+require "#{prefix}/api_resource"
+require "#{prefix}/request_param"
+require "#{prefix}/request_header"
+require "#{prefix}/param_request"
+require "#{prefix}/meta_data_provider"
+require "#{prefix}/factory"
+
+require "#{prefix}/defaultimpl"
+require "#{prefix}/webhooks"

data/onlinepayments-sdk-ruby.gemspec

@@ -0,0 +1,28 @@
+Gem::Specification.new do |spec|
+  spec.name           = 'onlinepayments-sdk-ruby'
+  spec.version        = '3.0.0'
+  spec.authors        = ['Worldline Direct support team']
+  spec.email          = ['82139942+worldline-direct-support-team@users.noreply.github.com']
+  spec.summary        = %q{SDK to communicate with the Online Payments platform using the Online Payments Server API}
+  spec.description    = %q{SDK to communicate with the Online Payments platform using the Online Payments Server API}
+  spec.homepage       = %q{https://github.com/wl-online-payments-direct/sdk-ruby}
+  spec.license        = 'MIT'
+
+  # exclude hidden files like .gitignore
+  spec.files          = Dir['lib/**/*'] + %w[onlinepayments-sdk-ruby.gemspec Gemfile LICENSE.txt Rakefile README.md]
+  spec.executables    = spec.files.grep(%r{^bin\/}) { |f| File.basename(f) }
+  spec.test_files     = spec.files.grep(%r{^(test|spec|features)\/})
+  spec.require_paths  = ['lib']
+
+  spec.required_ruby_version = '>= 2.0'
+
+  spec.add_dependency 'httpclient', '~> 2.8'
+  spec.add_dependency 'concurrent-ruby', '~>1.0'
+
+  spec.add_development_dependency 'yard', '~> 0.9'
+  spec.add_development_dependency 'rspec', '~> 3.5'
+  spec.add_development_dependency 'webmock', '~> 2.1'
+  spec.add_development_dependency 'sinatra', '~> 1.4'
+  spec.add_development_dependency 'rake', '~> 12.3', '>= 12.3.3'
+  # spec.metadata['yard.run'] = 'yri'  # compiles yard doc on install
+end