castle-rb 4.0.0 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 40234604d033086c79d951cbec5a52902df4ccda433eff1749c20cfeaca114d6
-  data.tar.gz: e46b4d91acbcf6c370de3a0804d3f9e75ad86bc181b40e2727e92d5d63579953
+  metadata.gz: 441cbae1aed67e419bff1683c41183abb10c3890d5a159f3365c0b4bd3855f0b
+  data.tar.gz: 6ef7663b21e2de6b1ef833917dd4b62ee1891f017e33f88a1cb57252e5c3bcc4
 SHA512:
-  metadata.gz: d70f1b03fb44e3d23afcb03ca83165f5b521a53269f34d2ed63740cc181e110da3692db50d6f701477a24430262d08859a71f7faeae8867c8962242d7421545d
-  data.tar.gz: b4a32a603c55df97450e59f936677d5b56387b8d4bf145d4355ca7f5ec606c557d00da72a92bb3f2b641d93a3d3f6e21b9f9412fff35f1840c43db66789b3b6c
+  metadata.gz: b54200b206ea055878d2e4a6b46f82960cda186c4b57009765c7e4c8cce28c7f00c66ad216840f8fa5412a7ed876224f285a18388620bf7df9201425a0efb055
+  data.tar.gz: cf9f8b5019377138fe5e61ced02b6323aa27464dc117c521fe560a6832115416bbd7e92a64a4710b96939adcd49af12feb538f3d24392d9654b14a21a48021a5

data/README.md

@@ -1,6 +1,6 @@
 # Ruby SDK for Castle
 
-[![Build Status](https://travis-ci.org/castle/castle-ruby.svg?branch=master)](https://travis-ci.org/castle/castle-ruby)
+[![Build Status](https://circleci.com/gh/castle/castle-ruby.svg?style=shield&branch=master)](https://circleci.com/gh/castle/castle-ruby)
 [![Coverage Status](https://coveralls.io/repos/github/castle/castle-ruby/badge.svg?branch=coveralls)](https://coveralls.io/github/castle/castle-ruby?branch=coveralls)
 [![Gem Version](https://badge.fury.io/rb/castle-rb.svg)](https://badge.fury.io/rb/castle-rb)
 
@@ -65,39 +65,61 @@ Castle.configure do |config|
   # Castle::RequestError is raised when timing out in milliseconds (default: 500 milliseconds)
   config.request_timeout = 2000
 
-  # Whitelisted and Blacklisted headers are case insensitive and allow to use _ and - as a separator, http prefixes are removed
-  # Whitelisted headers
+  # Allowlisted and Denylisted headers are case insensitive and allow to use _ and - as a separator, http prefixes are removed
+  # Allowlisted headers
   # By default, the SDK sends all HTTP headers, except for Cookie and Authorization.
-  # If you decide to use a whitelist, the SDK will:
+  # If you decide to use a allowlist, the SDK will:
   # - always send the User-Agent header
-  # - send scrubbed values of non-whitelisted headers
-  # - send proper values of whitelisted headers.
+  # - send scrubbed values of non-allowlisted headers
+  # - send proper values of allowlisted headers.
   # @example
-  #   config.whitelisted = ['X_HEADER']
+  #   config.allowlisted = ['X_HEADER']
   #   # will send { 'User-Agent' => 'Chrome', 'X_HEADER' => 'proper value', 'Any-Other-Header' => true }
   #
-  # We highly suggest using blacklist instead of whitelist, so that Castle can use as many data points
-  # as possible to secure your users. If you want to use the whitelist, this is the minimal
+  # We highly suggest using denylist instead of allowlist, so that Castle can use as many data points
+  # as possible to secure your users. If you want to use the allowlist, this is the minimal
   # amount of headers we recommend:
-  config.whitelisted = Castle::Configuration::DEFAULT_WHITELIST
+  config.allowlisted = Castle::Configuration::DEFAULT_ALLOWLIST
 
-  # Blacklisted headers take precedence over whitelisted elements
-  # We always blacklist Cookie and Authentication headers. If you use any other headers that
-  # might contain sensitive information, you should blacklist them.
-  config.blacklisted = ['HTTP-X-header']
+  # Denylisted headers take precedence over allowlisted elements
+  # We always denylist Cookie and Authentication headers. If you use any other headers that
+  # might contain sensitive information, you should denylist them.
+  config.denylisted = ['HTTP-X-header']
 
   # Castle needs the original IP of the client, not the IP of your proxy or load balancer.
-  # we try to fetch proper ip based on X-Forwarded-For, X-Client-Id or Remote-Addr headers in that order
-  # but sometimes proper ip may be stored in different header or order could be different.
-  # SDK can extract ip automatically for you, but you must configure which ip_headers you would like to use
+  # The SDK will only trust the proxy chain as defined in the configuration.
+  # We try to fetch the client IP based on X-Forwarded-For or Remote-Addr headers in that order,
+  # but sometimes the client IP may be stored in a different header or order.
+  # The SDK can be configured to look for the client IP address in headers that you specify.
+
+  # Sometimes, Cloud providers do not use consistent IP addresses to proxy requests.
+  # In this case, the client IP is usually preserved in a custom header. Example:
+  # Cloudflare preserves the client request in the 'Cf-Connecting-Ip' header.
+  # It would be used like so: configuration.ip_headers=['Cf-Connecting-Ip']
   configuration.ip_headers = []
 
-  # Additionally to make X-Forwarded-For or X-Client-Id work better discovering client ip address,
+  # If the specified header or X-Forwarded-For default contains a proxy chain with public IP addresses,
+  # then one of the following must be set
+  # 1. The trusted_proxies value must match the known proxy IP's
+  # 2. The trusted_proxy_depth value must be set to the number of known trusted proxies in the chain (see below)
+
+  # Additionally to make X-Forwarded-For and other headers work better discovering client ip address,
   # and not the address of a reverse proxy server, you can define trusted proxies
   # which will help to fetch proper ip from those headers
+
+  # In order to extract the client IP of the X-Forwarded-For header
+  # and not the address of a reverse proxy server, you must define all trusted public proxies
+  # you can achieve this by listing all the proxies ip defined by string or regular expressions
+  # in trusted_proxies setting
   configuration.trusted_proxies = []
-  # *Note: proxies list can be provided as an array of regular expressions
-  # *Note: default always marked as trusty list is here: Castle::Configuration::TRUSTED_PROXIES
+  # or by providing number of trusted proxies used in the chain
+  configuration.trusted_proxy_depth = 0
+
+  # If there is no possibility to define options above and there is no other header which can have client ip
+  # then you may set trust_proxy_chain = true to trust all of the proxy IP's in X-Forwarded-For
+  configuration.trust_proxy_chain = false
+
+  # *Note: default list of proxies which is always marked as trusted: Castle::Configuration::TRUSTED_PROXIES
 end
 ```
 
@@ -175,6 +197,25 @@ track_options = ::Castle::Client.to_options({
 CastleTrackingWorker.perform_async(request_context, track_options)
 ```
 
+## Connection reuse
+
+If you want to reuse the connection to send multiple events:
+
+```ruby
+Castle::API::Session.call do |http|
+  castle.track(
+    event: ::Castle::Events::LOGOUT_SUCCEEDED,
+    user_id: user2.id
+    http: http
+  )
+  castle.track(
+    event: ::Castle::Events::LOGIN_SUCCEEDED,
+    user_id: user1.id
+    http: http
+  )
+end
+```
+
 ## Events
 
 List of Recognized Events can be found [here](https://github.com/castle/castle-ruby/tree/master/lib/castle/events.rb) or in the [docs](https://docs.castle.io/api_reference/#list-of-recognized-events)

data/lib/castle.rb

@@ -29,15 +29,16 @@
   castle/configuration
   castle/failover_auth_response
   castle/client
-  castle/header_filter
-  castle/header_formatter
+  castle/headers_filter
+  castle/headers_formatter
   castle/secure_mode
   castle/extractors/client_id
   castle/extractors/headers
   castle/extractors/ip
+  castle/api/connection
   castle/api/response
   castle/api/request
-  castle/api/request/build
+  castle/api/session
   castle/review
   castle/api
 ].each(&method(:require))
@@ -54,7 +55,7 @@ module Castle
     end
 
     def config
-      @config ||= Castle::Configuration.new
+      Configuration.instance
     end
 
     def api_secret=(api_secret)

data/lib/castle/api.rb

@@ -17,16 +17,18 @@ module Castle
     private_constant :HANDLED_ERRORS
 
     class << self
-      def request(command, headers = {})
+      # @param command [String]
+      # @param headers [Hash]
+      # @param http [Net::HTTP]
+      def request(command, headers = {}, http = nil)
         raise Castle::ConfigurationError, 'configuration is not valid' unless Castle.config.valid?
 
         begin
-          Castle::API::Response.call(
-            Castle::API::Request.call(
-              command,
-              Castle.config.api_secret,
-              headers
-            )
+          Castle::API::Request.call(
+            command,
+            Castle.config.api_secret,
+            headers,
+            http
           )
         rescue *HANDLED_ERRORS => e
           # @note We need to initialize the error, as the original error is a cause for this
@@ -35,6 +37,13 @@ module Castle
           raise Castle::RequestError.new(e) # rubocop:disable Style/RaiseArgs
         end
       end
+
+      # @param command [String]
+      # @param headers [Hash]
+      # @param http [Net::HTTP]
+      def call(command, headers = {}, http = nil)
+        Castle::API::Response.call(request(command, headers, http))
+      end
     end
   end
 end

data/lib/castle/api/connection.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Castle
+  module API
+    # this module returns a new configured Net::HTTP object
+    module Connection
+      HTTPS_SCHEME = 'https'
+
+      class << self
+        def call
+          http = Net::HTTP.new(Castle.config.url.host, Castle.config.url.port)
+          http.read_timeout = Castle.config.request_timeout / 1000.0
+
+          if Castle.config.url.scheme == HTTPS_SCHEME
+            http.use_ssl = true
+            http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+          end
+
+          http
+        end
+      end
+    end
+  end
+end

data/lib/castle/api/request.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 module Castle
-  # this class is responsible for making requests to api
   module API
+    # this class is responsible for making requests to api
     module Request
       # Default headers that we add to passed ones
       DEFAULT_HEADERS = {
@@ -12,9 +12,9 @@ module Castle
       private_constant :DEFAULT_HEADERS
 
       class << self
-        def call(command, api_secret, headers)
-          http.request(
-            Castle::API::Request::Build.call(
+        def call(command, api_secret, headers, http = nil)
+          (http || Castle::API::Connection.call).request(
+            build(
               command,
               headers.merge(DEFAULT_HEADERS),
               api_secret
@@ -22,14 +22,19 @@ module Castle
           )
         end
 
-        def http
-          http = Net::HTTP.new(Castle.config.host, Castle.config.port)
-          http.read_timeout = Castle.config.request_timeout / 1000.0
-          if Castle.config.port == 443
-            http.use_ssl = true
-            http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+        def build(command, headers, api_secret)
+          request_obj = Net::HTTP.const_get(
+            command.method.to_s.capitalize
+          ).new("#{Castle.config.url.path}/#{command.path}", headers)
+
+          unless command.method == :get
+            request_obj.body = ::Castle::Utils.replace_invalid_characters(
+              command.data
+            ).to_json
           end
-          http
+
+          request_obj.basic_auth('', api_secret)
+          request_obj
         end
       end
     end

data/lib/castle/api/session.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Castle
+  module API
+    # this module uses the Connection object
+    # and provides start method for persistent connection usage
+    # when there is a need of sending multiple requests at once
+    module Session
+      HTTPS_SCHEME = 'https'
+
+      class << self
+        def call(&block)
+          return unless block_given?
+
+          Connection.call.start(&block)
+        end
+      end
+    end
+  end
+end

data/lib/castle/client.rb

@@ -42,9 +42,11 @@ module Castle
       return generate_do_not_track_response(options[:user_id]) unless tracked?
 
       add_timestamp_if_necessary(options)
-      command = Castle::Commands::Authenticate.new(@context).build(options)
+
       begin
-        Castle::API.request(command).merge(failover: false, failover_reason: nil)
+        Castle::API
+          .call(authenticate_command(options), {}, options[:http])
+          .merge(failover: false, failover_reason: nil)
       rescue Castle::RequestError, Castle::InternalServerError => e
         self.class.failover_response_or_raise(
           FailoverAuthResponse.new(options[:user_id], reason: e.to_s), e
@@ -59,8 +61,7 @@ module Castle
 
       add_timestamp_if_necessary(options)
 
-      command = Castle::Commands::Identify.new(@context).build(options)
-      Castle::API.request(command)
+      Castle::API.call(identify_command(options), {}, options[:http])
     end
 
     def track(options = {})
@@ -70,15 +71,15 @@ module Castle
 
       add_timestamp_if_necessary(options)
 
-      command = Castle::Commands::Track.new(@context).build(options)
-      Castle::API.request(command)
+      Castle::API.call(track_command(options), {}, options[:http])
     end
 
     def impersonate(options = {})
       options = Castle::Utils.deep_symbolize_keys(options || {})
+
       add_timestamp_if_necessary(options)
-      command = Castle::Commands::Impersonate.new(@context).build(options)
-      Castle::API.request(command).tap do |response|
+
+      Castle::API.call(impersonate_command(options), {}, options[:http]).tap do |response|
         raise Castle::ImpersonationFailed unless response[:success]
       end
     end
@@ -104,6 +105,26 @@ module Castle
       ).generate
     end
 
+    # @param options [Hash]
+    def authenticate_command(options)
+      Castle::Commands::Authenticate.new(@context).build(options)
+    end
+
+    # @param options [Hash]
+    def identify_command(options)
+      Castle::Commands::Identify.new(@context).build(options)
+    end
+
+    # @param options [Hash]
+    def impersonate_command(options)
+      Castle::Commands::Impersonate.new(@context).build(options)
+    end
+
+    # @param options [Hash]
+    def track_command(options)
+      Castle::Commands::Track.new(@context).build(options)
+    end
+
     def add_timestamp_if_necessary(options)
       options[:timestamp] ||= @timestamp if @timestamp
     end

data/lib/castle/configuration.rb

@@ -1,11 +1,15 @@
 # frozen_string_literal: true
 
+require 'singleton'
+require 'uri'
+
 module Castle
   # manages configuration variables
   class Configuration
-    HOST = 'api.castle.io'
-    PORT = 443
-    URL_PREFIX = 'v1'
+    include Singleton
+
+    # API endpoint
+    URL = 'https://api.castle.io/v1'
     FAILOVER_STRATEGY = :allow
     REQUEST_TIMEOUT = 500 # in milliseconds
     FAILOVER_STRATEGIES = %i[allow deny challenge throw].freeze
@@ -19,9 +23,9 @@ module Castle
       \Aunix:
     /ix].freeze
 
-    # @note this value is not assigned as we don't recommend using a whitelist. If you need to use
+    # @note this value is not assigned as we don't recommend using a allowlist. If you need to use
     #   one, this constant is provided as a good default.
-    DEFAULT_WHITELIST = %w[
+    DEFAULT_ALLOWLIST = %w[
       Accept
       Accept-Charset
       Accept-Datetime
@@ -31,42 +35,58 @@ module Castle
       Connection
       Content-Length
       Content-Type
+      Dnt
       Host
       Origin
       Pragma
       Referer
-      TE
+      Sec-Fetch-Dest
+      Sec-Fetch-Mode
+      Sec-Fetch-Site
+      Sec-Fetch-User
+      Te
       Upgrade-Insecure-Requests
+      User-Agent
       X-Castle-Client-Id
+      X-Requested-With
     ].freeze
 
-    attr_accessor :host, :port, :request_timeout, :url_prefix
-    attr_reader :api_secret, :whitelisted, :blacklisted, :failover_strategy, :ip_headers, :trusted_proxies
+    attr_accessor :request_timeout, :trust_proxy_chain
+    attr_reader :api_secret, :allowlisted, :denylisted, :failover_strategy, :ip_headers,
+                :trusted_proxies, :trusted_proxy_depth, :url
 
     def initialize
-      @formatter = Castle::HeaderFormatter.new
+      @formatter = Castle::HeadersFormatter
       @request_timeout = REQUEST_TIMEOUT
+      reset
+    end
+
+    def reset
       self.failover_strategy = FAILOVER_STRATEGY
-      self.host = HOST
-      self.port = PORT
-      self.url_prefix = URL_PREFIX
-      self.whitelisted = [].freeze
-      self.blacklisted = [].freeze
+      self.url = URL
+      self.allowlisted = [].freeze
+      self.denylisted = [].freeze
       self.api_secret = ENV.fetch('CASTLE_API_SECRET', '')
       self.ip_headers = [].freeze
       self.trusted_proxies = [].freeze
+      self.trust_proxy_chain = false
+      self.trusted_proxy_depth = nil
+    end
+
+    def url=(value)
+      @url = URI(value)
     end
 
     def api_secret=(value)
       @api_secret = value.to_s
     end
 
-    def whitelisted=(value)
-      @whitelisted = (value ? value.map { |header| @formatter.call(header) } : []).freeze
+    def allowlisted=(value)
+      @allowlisted = (value ? value.map { |header| @formatter.call(header) } : []).freeze
     end
 
-    def blacklisted=(value)
-      @blacklisted = (value ? value.map { |header| @formatter.call(header) } : []).freeze
+    def denylisted=(value)
+      @denylisted = (value ? value.map { |header| @formatter.call(header) } : []).freeze
     end
 
     # sets ip headers
@@ -78,15 +98,20 @@ module Castle
     end
 
     # sets trusted proxies
-    # @param value [Array<String|Regexp>]
+    # @param value [Array<String,Regexp>]
     def trusted_proxies=(value)
       raise Castle::ConfigurationError, 'trusted proxies must be an Array' unless value.is_a?(Array)
 
       @trusted_proxies = value
     end
 
+    # @param value [String,Number,NilClass]
+    def trusted_proxy_depth=(value)
+      @trusted_proxy_depth = value.to_i
+    end
+
     def valid?
-      !api_secret.to_s.empty? && !host.to_s.empty? && !port.to_s.empty?
+      !api_secret.to_s.empty? && !url.host.to_s.empty? && !url.port.to_s.empty?
     end
 
     def failover_strategy=(value)