castle-rb 3.6.2 → 4.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01fa92f200806e9649d71afa71dff0e8ff37db950a74e122134fdbda5413ef8a
-  data.tar.gz: f3a11d66711788d68c228ff63b647326e5446fff0ddb1be4e33e4b400d4587a8
+  metadata.gz: 0dd544ffa6fc2660fc67c058011df5b9d83a8078b48506ab611809166960f501
+  data.tar.gz: 1720630a7f1925ba1142208114198cf176a8a3fec5c04be480aa4d2384e03de2
 SHA512:
-  metadata.gz: 5329a71bd213ee88665b68ab4a79f6eca7987355d839d9e26b4d132ea3d4b7986714d23c3b6f97e7743ce774d969438365ea004fdcdd99eb7643f5c07c43d7b9
-  data.tar.gz: 89d8241793e59288651ac45b8d799c545a9b60aa25e6ae8d0092cda6183e9ecdf3b9d5b8ee68e0184b8021dc8633f9f949c987c6f0cd3abc1db6f7f2b47bda99
+  metadata.gz: 71320c8ff0a5dd2a137723efc76c5530449bdf4635eed38f4c5fcad8bcb9253c5b2557b9113071cd606528eb58d3d66921fa1a728e6ea123d65ab2173e71ad59
+  data.tar.gz: d2f57e05bd976a294385808757b148248f01b2319cd99e88277bc18e104d4a2fabbcd2d1aa55057d7fc5a12e4ab7e3ec66086502c74ba6d8e5f6b8e51acfba01

data/README.md

@@ -85,20 +85,67 @@ Castle.configure do |config|
   # 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']
+
+  # Castle needs the original IP of the client, not the IP of your proxy or load balancer.
+  # 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.
+  # 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)
+  configuration.ip_headers = []
+
+  # 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 = []
+  # 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
 ```
 
+## Event Context
+
 The client will automatically configure the context for each request.
 
+### Overriding Default Context Properties
+
+If you need to modify the event context properties or if you desire to add additional properties such as user traits to the context, you can pass the properties in as options to the method of interest. An example:
+```ruby
+request_context = ::Castle::Client.to_context(request)
+track_options = ::Castle::Client.to_options({
+  event: ::Castle::Events::LOGIN_SUCCEEDED,
+  user_id: user.id,
+  properties: {
+    key: 'value'
+  },
+  user_traits: {
+    key: 'value'
+  }
+})
+```
+
 ## Tracking
 
 Here is a simple example of a track event.
 
-
 ```ruby
 begin
   castle.track(
-    event: '$login.succeeded',
+    event: ::Castle::Events::LOGIN_SUCCEEDED,
     user_id: user.id
   )
 rescue Castle::Error => e
@@ -132,7 +179,7 @@ end
 ```ruby
 request_context = ::Castle::Client.to_context(request)
 track_options = ::Castle::Client.to_options({
-  event: '$login.succeeded',
+  event: ::Castle::Events::LOGIN_SUCCEEDED,
   user_id: user.id,
   properties: {
     key: 'value'
@@ -144,13 +191,18 @@ track_options = ::Castle::Client.to_options({
 CastleTrackingWorker.perform_async(request_context, track_options)
 ```
 
+## 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)
+
 ## Impersonation mode
 
-https://castle.io/docs/impersonation
+https://castle.io/docs/impersonation_mode
 
 ## Exceptions
 
-`Castle::Error` will be thrown if the Castle API returns a 400 or a 500 level HTTP response. You can also choose to catch a more [finegrained error](https://github.com/castle/castle-ruby/blob/master/lib/castle/errors.rb).
+`Castle::Error` will be thrown if the Castle API returns a 400 or a 500 level HTTP response.
+You can also choose to catch a more [finegrained error](https://github.com/castle/castle-ruby/blob/master/lib/castle/errors.rb).
 
 ## Documentation
 

data/lib/castle.rb

@@ -9,6 +9,7 @@
 
 %w[
   castle/version
+  castle/events
   castle/errors
   castle/command
   castle/utils
@@ -28,14 +29,15 @@
   castle/configuration
   castle/failover_auth_response
   castle/client
-  castle/header_formatter
+  castle/headers_filter
+  castle/headers_formatter
   castle/secure_mode
   castle/extractors/client_id
   castle/extractors/headers
   castle/extractors/ip
   castle/api/response
   castle/api/request
-  castle/api/request/build
+  castle/api/session
   castle/review
   castle/api
 ].each(&method(:require))
@@ -52,7 +54,7 @@ module Castle
     end
 
     def config
-      @configuration ||= Castle::Configuration.new
+      Configuration.instance
     end
 
     def api_secret=(api_secret)

data/lib/castle/api.rb

@@ -17,16 +17,16 @@ module Castle
     private_constant :HANDLED_ERRORS
 
     class << self
+      # @param command [String]
+      # @param headers [Hash]
       def request(command, headers = {})
         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
           )
         rescue *HANDLED_ERRORS => e
           # @note We need to initialize the error, as the original error is a cause for this
@@ -35,6 +35,12 @@ module Castle
           raise Castle::RequestError.new(e) # rubocop:disable Style/RaiseArgs
         end
       end
+
+      # @param command [String]
+      # @param headers [Hash]
+      def call(command, headers = {})
+        Castle::API::Response.call(request(command, headers))
+      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 = {
@@ -13,8 +13,8 @@ module Castle
 
       class << self
         def call(command, api_secret, headers)
-          http.request(
-            Castle::API::Request::Build.call(
+          Castle::API::Session.get.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_prefix}/#{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,39 @@
+# frozen_string_literal: true
+
+require 'singleton'
+
+module Castle
+  module API
+    # this class keeps http config object
+    # and provides start/finish methods for persistent connection usage
+    # when there is a need of sending multiple requests at once
+    class Session
+      include Singleton
+
+      attr_accessor :http
+
+      def initialize
+        reset
+      end
+
+      def reset
+        @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
+        end
+
+        @http
+      end
+
+      class << self
+        # @return [Net::HTTP]
+        def get
+          instance.http
+        end
+      end
+    end
+  end
+end

data/lib/castle/client.rb

@@ -23,6 +23,7 @@ module Castle
 
       def failover_response_or_raise(failover_response, error)
         return failover_response.generate unless Castle.config.failover_strategy == :throw
+
         raise error
       end
     end
@@ -38,21 +39,16 @@ module Castle
     def authenticate(options = {})
       options = Castle::Utils.deep_symbolize_keys(options || {})
 
-      if 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)
-        rescue Castle::RequestError, Castle::InternalServerError => e
-          self.class.failover_response_or_raise(
-            FailoverAuthResponse.new(options[:user_id], reason: e.to_s), e
-          )
-        end
-      else
-        FailoverAuthResponse.new(
-          options[:user_id],
-          strategy: :allow, reason: 'Castle set to do not track.'
-        ).generate
+      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.call(command).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
+        )
       end
     end
 
@@ -60,27 +56,29 @@ module Castle
       options = Castle::Utils.deep_symbolize_keys(options || {})
 
       return unless tracked?
+
       add_timestamp_if_necessary(options)
 
       command = Castle::Commands::Identify.new(@context).build(options)
-      Castle::API.request(command)
+      Castle::API.call(command)
     end
 
     def track(options = {})
       options = Castle::Utils.deep_symbolize_keys(options || {})
 
       return unless tracked?
+
       add_timestamp_if_necessary(options)
 
       command = Castle::Commands::Track.new(@context).build(options)
-      Castle::API.request(command)
+      Castle::API.call(command)
     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(command).tap do |response|
         raise Castle::ImpersonationFailed unless response[:success]
       end
     end
@@ -99,6 +97,13 @@ module Castle
 
     private
 
+    def generate_do_not_track_response(user_id)
+      FailoverAuthResponse.new(
+        user_id,
+        strategy: :allow, reason: 'Castle is set to do not track.'
+      ).generate
+    end
+
     def add_timestamp_if_necessary(options)
       options[:timestamp] ||= @timestamp if @timestamp
     end

data/lib/castle/configuration.rb

@@ -1,14 +1,27 @@
 # frozen_string_literal: true
 
+require 'singleton'
+
 module Castle
   # manages configuration variables
   class Configuration
+    include Singleton
+
     HOST = 'api.castle.io'
     PORT = 443
-    URL_PREFIX = 'v1'
+    URL_PREFIX = '/v1'
     FAILOVER_STRATEGY = :allow
     REQUEST_TIMEOUT = 500 # in milliseconds
     FAILOVER_STRATEGIES = %i[allow deny challenge throw].freeze
+    # regexp of trusted proxies which is always appended to the trusted proxy list
+    TRUSTED_PROXIES = [/
+      \A127\.0\.0\.1\Z|
+      \A(10|172\.(1[6-9]|2[0-9]|30|31)|192\.168)\.|
+      \A::1\Z|\Afd[0-9a-f]{2}:.+|
+      \Alocalhost\Z|
+      \Aunix\Z|
+      \Aunix:
+    /ix].freeze
 
     # @note this value is not assigned as we don't recommend using a whitelist. If you need to use
     #   one, this constant is provided as a good default.
@@ -31,23 +44,32 @@ module Castle
       X-Castle-Client-Id
     ].freeze
 
-    attr_accessor :host, :port, :request_timeout, :url_prefix
-    attr_reader :api_secret, :whitelisted, :blacklisted, :failover_strategy
+    attr_accessor :host, :port, :request_timeout, :url_prefix, :trust_proxy_chain
+    attr_reader :api_secret, :whitelisted, :blacklisted, :failover_strategy, :ip_headers,
+                :trusted_proxies, :trusted_proxy_depth
 
     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.api_secret = ''
+      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 api_secret=(value)
-      @api_secret = ENV.fetch('CASTLE_API_SECRET', value).to_s
+      @api_secret = value.to_s
     end
 
     def whitelisted=(value)
@@ -58,6 +80,27 @@ module Castle
       @blacklisted = (value ? value.map { |header| @formatter.call(header) } : []).freeze
     end
 
+    # sets ip headers
+    # @param value [Array<String>]
+    def ip_headers=(value)
+      raise Castle::ConfigurationError, 'ip headers must be an Array' unless value.is_a?(Array)
+
+      @ip_headers = value.map { |header| @formatter.call(header) }.freeze
+    end
+
+    # sets trusted proxies
+    # @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?
     end