apimatic_core 0.3.18 → 0.3.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2b0a483f088067743a544f3de82e94a1fd7e69c8ae909183b78f4d1ef5b1ae58
-  data.tar.gz: cd450513cff448d0a5c26ab010965d1a6c96c69aaa4d28867a4837b23860ddd0
+  metadata.gz: f7d8b0c1b444eea245cf2e0ca29d5fbd980529d682183b50a74e9a930fa90930
+  data.tar.gz: 72438e6b5d173296dac13e5289e93ca9705de8a28e57b9beff52e7c59f9f6607
 SHA512:
-  metadata.gz: e979257d3120334ba5b91869185aabb76a370d9fb7e8dff380d11275be052dcee00162b46e72e426812f4228b0c93fb7eda06bdc12ecdfce931b2529d00475ec
-  data.tar.gz: 2adbc4d4e20342ff76a26b90225a6cce77e0ff7ba2a6ee0d7e1904682369a561c513a5b6fe9668ed0fd801ec49d445d496f520ddc9b96e05934dabd1ee7d3d53
+  metadata.gz: 3bf3553f1053f3da1ab4a9e971aec4466d20ff84bcecdf2bf20051f3920e4ba0f471f782dc606875429214196ba934d9988ab9a2884a193a6f4aade5f692d1e4
+  data.tar.gz: e39757f877aeba7cd2f80cc70d15076daa9b44700dab1830608cc77b7799866e5abc389aa502b64aeeb2ad715a128ba4ddf898c853ffda4ffb2601f37425111a

data/README.md

@@ -45,7 +45,7 @@ gem 'apimatic_core'
 | [`Single`](lib/apimatic-core/authentication/multiple/single_auth.rb)   | Helper class to support single authentication                               |
 
 
-## Configurations
+## Global Configuration
 | Name                                                                                           | Description                                                                     |
 |------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------|
 | [`GlobalConfiguration`](lib/apimatic-core/configurations/global_configuration.rb )             | Class holding the global configuration properties to make a successful API Call |
@@ -63,14 +63,19 @@ gem 'apimatic_core'
 |-------------------------------------------------------------------------------|------------------------------------------|
 | [`HttpResponseFactory`](lib/apimatic-core/factories/http_response_factory.rb) | Factory class to create an HTTP Response |
 
+## HTTP Configuration
+| Name                                                                                            | Description                                                                                                           |
+|-------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|
+| [`HttpClientConfiguration`](lib/apimatic-core/http/configurations/http_client_configuration.rb) | Class used for configuring SDK by a user                                                                              |
+| [`ProxySettings`](lib/apimatic-core/http/configurations/proxy_settings.rb)                      | ProxySettings encapsulates HTTP proxy configuration for Faraday, e.g. address, port and optional basic authentication |
+
 ## HTTP
-| Name                                                                                            | Description                                                                                                                                                      |
-|-------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| [`HttpClientConfiguration`](lib/apimatic-core/http/configurations/http_client_configuration.rb) | Class used for configuring SDK by a user                                                                                                                         |
-| [`HttpRequest`](lib/apimatic-core/http/request/http_request.rb)                                 | Class which contains information about the HTTP Request                                                                                                          |
-| [`ApiResponse`](lib/apimatic-core/http/response/api_response.rb)                                | Wrapper class for Api Response                                                                                                                                   |
-| [`HttpResponse`](lib/apimatic-core/http/response/http_response.rb)                              | Class which contains information about the HTTP Response                                                                                                         |
-| [`HttpCallContext`](lib/apimatic-core/http/http_call_context.rb)                                | This class captures the HTTP request and response lifecycle during an API call and is used with clients or controllers that support pre- and post-request hooks. |
+| Name                                                               | Description                                                                                                                                                      |
+|--------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [`HttpRequest`](lib/apimatic-core/http/request/http_request.rb)    | Class which contains information about the HTTP Request                                                                                                          |
+| [`ApiResponse`](lib/apimatic-core/http/response/api_response.rb)   | Wrapper class for Api Response                                                                                                                                   |
+| [`HttpResponse`](lib/apimatic-core/http/response/http_response.rb) | Class which contains information about the HTTP Response                                                                                                         |
+| [`HttpCallContext`](lib/apimatic-core/http/http_call_context.rb)   | This class captures the HTTP request and response lifecycle during an API call and is used with clients or controllers that support pre- and post-request hooks. |
 
 ## Logger
 | Name                                                                                       | Description                                                         |
@@ -119,6 +124,15 @@ gem 'apimatic_core'
 | [`JsonPointerHelper`](lib/apimatic-core/utilities/json_pointer_helper.rb ) | Utility methods for getting and setting JSON pointer values in hashes.                                                 |
 | [`JsonPointer`](lib/apimatic-core/utilities/json_pointer.rb )              | Enables querying, updating, and deleting values in nested Ruby Hashes and Arrays using JSON Pointer syntax (RFC 6901). |
 | [`LoggerHelper`](lib/apimatic-core/utilities/logger_helper.rb )            | Utility methods for logging.                                                                                           |
+| [`RackRequestHelper`](lib/apimatic-core/utilities/rack_request_helper.rb ) | Utility methods for Rack::Request.                                                                                     |
+
+## Signature Verification
+| Name                                                                                                    | Description                                                                           |
+|---------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------|
+| [`HmacSignatureVerifier`](lib/apimatic-core/security/signature_verification/hmac_signature_verifier.rb) | Verifies HMAC signatures using configurable templates, hash algorithms, and encoders. |
+| [`HexEncoder`](lib/apimatic-core/security/signature_verification/hmac_signature_verifier.rb)            | Encodes digest as lowercase hex.                                                      |
+| [`Base64Encoder`](lib/apimatic-core/security/signature_verification/hmac_signature_verifier.rb)         | Encodes digest as Base64.                                                             |
+| [`Base64UrlEncoder`](lib/apimatic-core/security/signature_verification/hmac_signature_verifier.rb)      | Encodes digest as URL-safe Base64 without padding.                                    |
 
 ## Links
 * [apimatic_core_interfaces](https://rubygems.org/gems/apimatic_core_interfaces)

data/lib/apimatic-core/http/configurations/http_client_configuration.rb

@@ -16,12 +16,13 @@ module CoreLibrary
     # @param [Boolean] verify Should verification be enabled.
     # @param http_callback A method to be used as http callback
     # @param [HttpClient] http_client An instance of HttpClient
+    # @param [ProxySettings] proxy_settings The configurable settings for proxy
     def initialize(
       connection: nil, adapter: :net_http_persistent, timeout: 60,
       max_retries: 0, retry_interval: 1, backoff_factor: 2,
       retry_statuses: [408, 413, 429, 500, 502, 503, 504, 521, 522, 524],
       retry_methods: %i[get put], cache: false, verify: true, http_callback: nil, http_client: nil,
-      logging_configuration: nil
+      logging_configuration: nil, proxy_settings: nil
     )
       @response_factory = HttpResponseFactory.new
       @connection = connection
@@ -37,6 +38,7 @@ module CoreLibrary
       @cache = cache
       @http_client = http_client
       @logging_configuration = logging_configuration
+      @proxy_settings = proxy_settings
     end
 
     # Setter for http_client.
@@ -58,7 +60,8 @@ module CoreLibrary
         verify: @verify,
         http_callback: http_callback || DeepCloneUtils.deep_copy(@http_callback),
         http_client: DeepCloneUtils.deep_copy(@http_client),
-        logging_configuration: DeepCloneUtils.deep_copy(@logging_configuration)
+        logging_configuration: DeepCloneUtils.deep_copy(@logging_configuration),
+        proxy_settings: DeepCloneUtils.deep_copy(@proxy_settings)
       )
     end
   end

data/lib/apimatic-core/http/configurations/proxy_settings.rb

@@ -0,0 +1,42 @@
+module CoreLibrary
+  ##
+  # ProxySettings encapsulates HTTP proxy configuration for Faraday,
+  # including optional basic authentication.
+  #
+  class ProxySettings
+    attr_accessor :address, :port, :username, :password
+
+    ##
+    # @param address [String] The proxy server address (e.g., 'http://localhost').
+    # @param port [Integer, nil] Optional proxy server port (e.g., 8080).
+    # @param username [String, nil] Optional proxy auth username.
+    # @param password [String, nil] Optional proxy auth password.
+    #
+    # @raise [ArgumentError] If address is invalid.
+    #
+    def initialize(address:, port: nil, username: nil, password: nil)
+      raise ArgumentError, 'Proxy address must be a non-empty string' unless address.is_a?(String) && !address.empty?
+
+      @address = address
+      @port = port
+      @username = username
+      @password = password
+    end
+
+    ##
+    # Converts the proxy settings into a Faraday-compatible hash.
+    #
+    # @return [Hash] A hash with keys :uri, :user, and :password (as applicable).
+    #
+    def to_h
+      uri_str = port ? "#{address}:#{port}" : address
+
+      {
+        uri: uri_str
+      }.tap do |hash|
+        hash[:user] = username if username
+        hash[:password] = password if password
+      end
+    end
+  end
+end

data/lib/apimatic-core/security/signature_verification/hmac_signature_verifier.rb

@@ -0,0 +1,138 @@
+require 'openssl'
+require 'base64'
+
+module CoreLibrary
+  # === DigestEncoder Interface ===
+  class DigestEncoder
+    # Encodes a digest (bytes) into a string.
+    # @param digest [String] raw digest bytes
+    # @return [String]
+    def encode(digest)
+      raise NotImplementedError, 'This method must be implemented in a subclass.'
+    end
+  end
+
+  # === HexEncoder ===
+  class HexEncoder < DigestEncoder
+    def encode(digest)
+      digest.unpack1('H*')
+    end
+  end
+
+  # === Base64Encoder ===
+  class Base64Encoder < DigestEncoder
+    def encode(digest)
+      Base64.strict_encode64(digest)
+    end
+  end
+
+  # === Base64UrlEncoder ===
+  class Base64UrlEncoder < DigestEncoder
+    def encode(digest)
+      Base64.urlsafe_encode64(digest).delete('=')
+    end
+  end
+
+  # === HmacSignatureVerifier ===
+  # Verifies HMAC signatures for incoming requests.
+  #
+  # Works with Rack::Request or any object exposing Rack-like `env` or `headers`/`raw_body`.
+  #
+  # Example:
+  #   verifier = HmacSignatureVerifier.new(
+  #     secret_key: "supersecret",
+  #     signature_header: "X-Signature"
+  #   )
+  #   result = verifier.verify(rack_request)
+  #
+  class HmacSignatureVerifier < CoreLibrary::SignatureVerifier
+    def initialize(secret_key:, signature_header:, canonical_message_builder: nil, hash_algorithm: 'sha256',
+                   encoder: HexEncoder.new, signature_value_template: DIGEST_PLACEHOLDER)
+      raise ArgumentError, 'secret_key must be a non-empty string' unless secret_key.is_a?(String) && !secret_key.empty?
+
+      unless signature_header.is_a?(String) && !signature_header.strip.empty?
+        raise ArgumentError,
+              'signature_header must be a non-empty string'
+      end
+
+      @secret_key = secret_key
+      @signature_header_lc = signature_header.strip.downcase.tr('_', '-')
+      @canonical_message_builder = canonical_message_builder
+      @hash_alg = hash_algorithm
+      @encoder = encoder
+      @signature_value_template = signature_value_template
+    end
+
+    # Verifies the HMAC signature for the request.
+    #
+    # @param request [Rack::Request, #env, #headers, #raw_body]
+    # @return [CoreLibrary::SignatureVerificationResult]
+    def verify(request)
+      headers = RackRequestHelper.extract_headers_hash(request)
+      provided_signature = headers[@signature_header_lc]
+
+      if provided_signature.nil?
+        return CoreLibrary::SignatureVerificationResult.failed(
+          ["Signature header '#{@signature_header_lc}' is missing"]
+        )
+      end
+
+      message = resolve_message_bytes(request)
+      digest = OpenSSL::HMAC.digest(@hash_alg, @secret_key, message)
+      encoded_digest = @encoder.encode(digest) unless @encoder.nil?
+
+      expected_signature =
+        if @signature_value_template.include?(DIGEST_PLACEHOLDER)
+          @signature_value_template.gsub(DIGEST_PLACEHOLDER, encoded_digest)
+        else
+          @signature_value_template
+        end
+
+      if HmacSignatureVerifier.fixed_length_secure_compare(provided_signature, expected_signature)
+        CoreLibrary::SignatureVerificationResult.passed
+      else
+        CoreLibrary::SignatureVerificationResult.failed(
+          ['Signature mismatch']
+        )
+      end
+    rescue StandardError => e
+      CoreLibrary::SignatureVerificationResult.failed(
+        ["Signature verification failed: #{e.message}"]
+      )
+    end
+
+    # Compares two strings in constant time to prevent timing attacks.
+    # Uses OpenSSL.fixed_length_secure_compare when available (Ruby ≥ 3
+    # with openssl gem ≥ 3.x); falls back to a pure Ruby implementation otherwise.
+    #
+    # @param a [String] the first string to compare
+    # @param b [String] the second string to compare
+    # @return [Boolean] true if the strings are equal, false otherwise
+    # @raise [ArgumentError] if the inputs are of unequal length
+    def self.fixed_length_secure_compare(a, b)
+      if RUBY_VERSION >= '3.0' && OpenSSL.respond_to?(:fixed_length_secure_compare)
+        OpenSSL.fixed_length_secure_compare(a, b)
+      else
+        raise ArgumentError, 'inputs must be same length' unless a.bytesize == b.bytesize
+
+        res = 0
+        a.bytes.zip(b.bytes) { |x, y| res |= (x ^ y) }
+        res.zero?
+      end
+    end
+
+    private
+
+    # Builds the canonical message (raw body or custom builder)
+    def resolve_message_bytes(request)
+      if @canonical_message_builder.nil?
+        RackRequestHelper.read_raw_body(request)
+      else
+        result = @canonical_message_builder.call(request)
+        result.to_s
+      end
+    end
+
+    DIGEST_PLACEHOLDER = '{digest}'.freeze
+  end
+end

data/lib/apimatic-core/utilities/rack_request_helper.rb

@@ -0,0 +1,93 @@
+module CoreLibrary
+  # === SignatureVerifierHelper ===
+  # Utility class for extracting headers and body from Rack::Request (or request-like objects).
+  #
+  # All methods are class methods and can be used without instantiating.
+  class RackRequestHelper
+    class << self
+      # Extract headers into a downcast-key Hash from Rack::Request or request-like object.
+      # Supports both Rack env (`request.env`) and objects exposing `headers` Hash.
+      #
+      # @param request [Rack::Request, #env, #headers]
+      # @return [Hash{String => String}]
+      def extract_headers_hash(request)
+        env = if request.respond_to?(:env)
+                request.env
+              elsif request.respond_to?(:headers) && request.headers.is_a?(Hash)
+                headers_to_env(request.headers)
+              else
+                {}
+              end
+
+        env.each_with_object({}) do |(k, v), acc|
+          next if v.nil?
+
+          key = k.to_s
+          if key.start_with?('HTTP_') || %w[CONTENT_TYPE CONTENT_LENGTH].include?(key)
+            header_name = format_header_name(key)
+            acc[header_name.downcase] = v.to_s
+          end
+        end
+      end
+
+      # Read raw body from a Rack::Request (rewinds after reading).
+      # Falls back to `raw_body` if provided.
+      #
+      # @param request [Rack::Request, #body, #raw_body]
+      # @return [String]
+      def read_raw_body(request)
+        if request.respond_to?(:body) && request.body.respond_to?(:read)
+          body = request.body.read
+          request.body.rewind if request.body.respond_to?(:rewind)
+          body
+        elsif request.respond_to?(:raw_body)
+          request.raw_body.to_s
+        else
+          ''.dup
+        end
+      end
+
+      # Normalizes a header name to the Rack environment variable format.
+      #
+      # - Converts "Content-Type" → "CONTENT_TYPE"
+      # - Converts "Content-Length" → "CONTENT_LENGTH"
+      # - Converts all other headers → "HTTP_<UPPERCASED_NAME>"
+      #
+      # @param [String, Symbol] name The header name.
+      # @return [String] The Rack-compliant environment key.
+      def prepend_header(name)
+        k_s = name.to_s
+        if /\Acontent[-_]type\z/i.match?(k_s)
+          'CONTENT_TYPE'
+        elsif /\Acontent[-_]length\z/i.match?(k_s)
+          'CONTENT_LENGTH'
+        else
+          "HTTP_#{k_s.upcase.gsub('-', '_')}"
+        end
+      end
+
+      private
+
+      # Convert a simple headers Hash (e.g., { "Content-Type" => "a" }) into Rack-style env.
+      #
+      # @param headers_hash [Hash]
+      # @return [Hash]
+      def headers_to_env(headers_hash)
+        headers_hash.transform_keys do |k|
+          prepend_header(k)
+        end
+      end
+
+      # Convert Rack env key (eg. 'HTTP_X_TIMESTAMP') into header name ('X-Timestamp')
+      #
+      # @param raw [String]
+      # @return [String]
+      def format_header_name(raw)
+        raw.to_s.sub(/^HTTP_/, '')
+           .split('_')
+           .map(&:capitalize)
+           .join('-')
+      end
+    end
+  end
+end

data/lib/apimatic_core.rb

@@ -30,6 +30,7 @@ require_relative 'apimatic-core/pagination/strategies/offset_pagination'
 require_relative 'apimatic-core/pagination/strategies/page_pagination'
 
 require_relative 'apimatic-core/http/configurations/http_client_configuration'
+require_relative 'apimatic-core/http/configurations/proxy_settings'
 require_relative 'apimatic-core/http/request/http_request'
 require_relative 'apimatic-core/http/response/http_response'
 require_relative 'apimatic-core/http/response/api_response'
@@ -60,6 +61,7 @@ require_relative 'apimatic-core/utilities/logger_helper'
 require_relative 'apimatic-core/utilities/constants'
 require_relative 'apimatic-core/utilities/deep_clone_utils'
 require_relative 'apimatic-core/utilities/json_pointer'
+require_relative 'apimatic-core/utilities/rack_request_helper'
 
 require_relative 'apimatic-core/authentication/header_auth'
 require_relative 'apimatic-core/authentication/query_auth'
@@ -67,3 +69,5 @@ require_relative 'apimatic-core/authentication/multiple/auth_group'
 require_relative 'apimatic-core/authentication/multiple/and_auth_group'
 require_relative 'apimatic-core/authentication/multiple/or_auth_group'
 require_relative 'apimatic-core/authentication/multiple/single_auth'
+
+require_relative 'apimatic-core/security/signature_verification/hmac_signature_verifier'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: apimatic_core
 version: !ruby/object:Gem::Version
-  version: 0.3.18
+  version: 0.3.20
 platform: ruby
 authors:
 - APIMatic Ltd.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-08-11 00:00:00.000000000 Z
+date: 2025-10-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: apimatic_core_interfaces
@@ -170,6 +170,7 @@ files:
 - lib/apimatic-core/exceptions/one_of_validation_exception.rb
 - lib/apimatic-core/factories/http_response_factory.rb
 - lib/apimatic-core/http/configurations/http_client_configuration.rb
+- lib/apimatic-core/http/configurations/proxy_settings.rb
 - lib/apimatic-core/http/http_call_context.rb
 - lib/apimatic-core/http/request/http_request.rb
 - lib/apimatic-core/http/response/api_response.rb
@@ -186,6 +187,7 @@ files:
 - lib/apimatic-core/pagination/strategies/page_pagination.rb
 - lib/apimatic-core/request_builder.rb
 - lib/apimatic-core/response_handler.rb
+- lib/apimatic-core/security/signature_verification/hmac_signature_verifier.rb
 - lib/apimatic-core/types/error_case.rb
 - lib/apimatic-core/types/parameter.rb
 - lib/apimatic-core/types/sdk/api_exception.rb
@@ -207,6 +209,7 @@ files:
 - lib/apimatic-core/utilities/json_pointer.rb
 - lib/apimatic-core/utilities/json_pointer_helper.rb
 - lib/apimatic-core/utilities/logger_helper.rb
+- lib/apimatic-core/utilities/rack_request_helper.rb
 - lib/apimatic-core/utilities/union_type_helper.rb
 - lib/apimatic-core/utilities/xml_helper.rb
 - lib/apimatic_core.rb