castle-rb 3.6.2 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01fa92f200806e9649d71afa71dff0e8ff37db950a74e122134fdbda5413ef8a
-  data.tar.gz: f3a11d66711788d68c228ff63b647326e5446fff0ddb1be4e33e4b400d4587a8
+  metadata.gz: 40234604d033086c79d951cbec5a52902df4ccda433eff1749c20cfeaca114d6
+  data.tar.gz: e46b4d91acbcf6c370de3a0804d3f9e75ad86bc181b40e2727e92d5d63579953
 SHA512:
-  metadata.gz: 5329a71bd213ee88665b68ab4a79f6eca7987355d839d9e26b4d132ea3d4b7986714d23c3b6f97e7743ce774d969438365ea004fdcdd99eb7643f5c07c43d7b9
-  data.tar.gz: 89d8241793e59288651ac45b8d799c545a9b60aa25e6ae8d0092cda6183e9ecdf3b9d5b8ee68e0184b8021dc8633f9f949c987c6f0cd3abc1db6f7f2b47bda99
+  metadata.gz: d70f1b03fb44e3d23afcb03ca83165f5b521a53269f34d2ed63740cc181e110da3692db50d6f701477a24430262d08859a71f7faeae8867c8962242d7421545d
+  data.tar.gz: b4a32a603c55df97450e59f936677d5b56387b8d4bf145d4355ca7f5ec606c557d00da72a92bb3f2b641d93a3d3f6e21b9f9412fff35f1840c43db66789b3b6c

data/README.md

@@ -85,20 +85,51 @@ 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.
+  # 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
+  configuration.ip_headers = []
+
+  # Additionally to make X-Forwarded-For or X-Client-Id 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
+  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
 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 +163,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 +175,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,6 +29,7 @@
   castle/configuration
   castle/failover_auth_response
   castle/client
+  castle/header_filter
   castle/header_formatter
   castle/secure_mode
   castle/extractors/client_id
@@ -52,7 +54,7 @@ module Castle
     end
 
     def config
-      @configuration ||= Castle::Configuration.new
+      @config ||= Castle::Configuration.new
     end
 
     def api_secret=(api_secret)

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.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
     end
 
@@ -60,6 +56,7 @@ 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)
@@ -70,6 +67,7 @@ module Castle
       options = Castle::Utils.deep_symbolize_keys(options || {})
 
       return unless tracked?
+
       add_timestamp_if_necessary(options)
 
       command = Castle::Commands::Track.new(@context).build(options)
@@ -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

@@ -9,6 +9,15 @@ module Castle
     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.
@@ -32,7 +41,7 @@ module Castle
     ].freeze
 
     attr_accessor :host, :port, :request_timeout, :url_prefix
-    attr_reader :api_secret, :whitelisted, :blacklisted, :failover_strategy
+    attr_reader :api_secret, :whitelisted, :blacklisted, :failover_strategy, :ip_headers, :trusted_proxies
 
     def initialize
       @formatter = Castle::HeaderFormatter.new
@@ -43,11 +52,13 @@ module Castle
       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
     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 +69,22 @@ 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
+
     def valid?
       !api_secret.to_s.empty? && !host.to_s.empty? && !port.to_s.empty?
     end

data/lib/castle/context/default.rb

@@ -4,36 +4,54 @@ module Castle
   module Context
     class Default
       def initialize(request, cookies = nil)
-        @client_id = Extractors::ClientId.new(request, cookies || request.cookies).call
-        @headers = Extractors::Headers.new(request).call
-        @request_ip = Extractors::IP.new(request).call
+        @pre_headers = HeaderFilter.new(request).call
+        @cookies = cookies || request.cookies
+        @request = request
       end
 
       def call
-        defaults.merge!(additional_defaults)
-      end
-
-      private
-
-      def defaults
         {
-          client_id: @client_id,
+          client_id: client_id,
           active: true,
           origin: 'web',
-          headers: @headers,
-          ip: @request_ip,
+          headers: headers,
+          ip: ip,
           library: {
             name: 'castle-rb',
             version: Castle::VERSION
           }
-        }
+        }.tap do |result|
+          result[:locale] = locale if locale
+          result[:user_agent] = user_agent if user_agent
+        end
       end
 
-      def additional_defaults
-        {}.tap do |result|
-          result[:locale] = @headers['Accept-Language'] if @headers['Accept-Language']
-          result[:user_agent] = @headers['User-Agent'] if @headers['User-Agent']
-        end
+      private
+
+      # @return [String]
+      def locale
+        @pre_headers['Accept-Language']
+      end
+
+      # @return [String]
+      def user_agent
+        @pre_headers['User-Agent']
+      end
+
+      # @return [String]
+      def ip
+        Extractors::IP.new(@pre_headers).call
+      end
+
+      # @return [String]
+      def client_id
+        Extractors::ClientId.new(@pre_headers, @cookies).call
+      end
+
+      # formatted and filtered headers
+      # @return [Hash]
+      def headers
+        Extractors::Headers.new(@pre_headers).call
       end
     end
   end

data/lib/castle/context/sanitizer.rb

@@ -15,6 +15,7 @@ module Castle
           return unless context
           return context unless context.key?(:active)
           return context if [true, false].include?(context[:active])
+
           context.reject { |key| key == :active }
         end
       end

data/lib/castle/events.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Castle
+  # list of events based on https://docs.castle.io/api_reference/#list-of-recognized-events
+  module Events
+    # Record when a user succesfully logs in.
+    LOGIN_SUCCEEDED = '$login.succeeded'
+    # Record when a user failed to log in.
+    LOGIN_FAILED = '$login.failed'
+    # Record when a user logs out.
+    LOGOUT_SUCCEEDED = '$logout.succeeded'
+    # Record when a user updated their profile (including password, email, phone, etc).
+    PROFILE_UPDATE_SUCCEEDED = '$profile_update.succeeded'
+    # Record errors when updating profile.
+    PROFILE_UPDATE_FAILED = '$profile_update.failed'
+    # Capture account creation, both when a user signs up as well as when created manually
+    # by an administrator.
+    REGISTRATION_SUCCEEDED = '$registration.succeeded'
+    # Record when an account failed to be created.
+    REGISTRATION_FAILED = '$registration.failed'
+    # The user completed all of the steps in the password reset process and the password was
+    # successfully reset.Password resets do not required knowledge of the current password.
+    PASSWORD_RESET_SUCCEEDED = '$password_reset.succeeded'
+    # Use to record when a user failed to reset their password.
+    PASSWORD_RESET_FAILED = '$password_reset.failed'
+    # The user successfully requested a password reset.
+    PASSWORD_RESET_REQUEST_SUCCCEEDED = '$password_reset_request.succeeded'
+    # The user failed to request a password reset.
+    PASSWORD_RESET_REQUEST_FAILED = '$password_reset_request.failed'
+    # User account has been reset.
+    INCIDENT_MITIGATED = '$incident.mitigated'
+    # User confirmed malicious activity.
+    REVIEW_ESCALATED = '$review.escalated'
+    # User confirmed safe activity.
+    REVIEW_RESOLVED = '$review.resolved'
+    # Record when a user is prompted with additional verification, such as two-factor
+    # authentication or a captcha.
+    CHALLENGE_REQUESTED = '$challenge.requested'
+    # Record when additional verification was successful.
+    CHALLENGE_SUCCEEDED = '$challenge.succeeded'
+    # Record when additional verification failed.
+    CHALLENGE_FAILED = '$challenge.failed'
+    # Record when a user attempts an in-app transaction, such as a purchase or withdrawal.
+    TRANSACTION_ATTEMPTED = '$transaction.attempted'
+    # Record when a user session is extended, or use any time you want
+    # to re-authenticate a user mid-session.
+    SESSION_EXTENDED = '$session.extended'
+  end
+end

data/lib/castle/extractors/client_id.rb

@@ -4,13 +4,17 @@ module Castle
   module Extractors
     # used for extraction of cookies and headers from the request
     class ClientId
-      def initialize(request, cookies)
-        @request = request
+      # @param headers [Hash]
+      # @param cookies [NilClass|Hash]
+      def initialize(headers, cookies)
+        @headers = headers
         @cookies = cookies || {}
       end
 
+      # extracts client id
+      # @return [String]
       def call
-        @request.env['HTTP_X_CASTLE_CLIENT_ID'] || @cookies['__cid'] || ''
+        @headers['X-Castle-Client-Id'] || @cookies['__cid'] || ''
       end
     end
   end

data/lib/castle/extractors/headers.rb

@@ -5,47 +5,41 @@ module Castle
     # used for extraction of cookies and headers from the request
     class Headers
       # Headers that we will never scrub, even if they land on the configuration blacklist.
-      ALWAYS_INCLUDED_HEADERS = %w[User-Agent].freeze
+      ALWAYS_WHITELISTED = %w[User-Agent].freeze
 
       # Headers that will always be scrubbed, even if whitelisted.
-      ALWAYS_SCRUBBED_HEADERS = %w[Cookie Authorization].freeze
+      ALWAYS_BLACKLISTED = %w[Cookie Authorization].freeze
 
-      # Rack does not add the HTTP_ prefix to Content-Length for some reason
-      CONTENT_LENGTH = 'CONTENT_LENGTH'
+      private_constant :ALWAYS_WHITELISTED, :ALWAYS_BLACKLISTED
 
-      # Prefix that Rack adds for HTTP headers
-      HTTP_HEADER_PREFIX = 'HTTP_'
-
-      private_constant :ALWAYS_INCLUDED_HEADERS, :ALWAYS_SCRUBBED_HEADERS,
-                       :CONTENT_LENGTH, :HTTP_HEADER_PREFIX
-
-      # @param request [Rack::Request]
-      def initialize(request)
-        @request_env = request.env
-        @formatter = HeaderFormatter.new
+      # @param headers [Hash]
+      def initialize(headers)
+        @headers = headers
+        @no_whitelist = Castle.config.whitelisted.empty?
       end
 
       # Serialize HTTP headers
       # @return [Hash]
       def call
-        @request_env.keys.each_with_object({}) do |env_header, acc|
-          next unless env_header.to_s.start_with?(HTTP_HEADER_PREFIX) || env_header == CONTENT_LENGTH
-
-          header = @formatter.call(env_header)
-
-          if ALWAYS_SCRUBBED_HEADERS.include?(header)
-            acc[header] = true
-          elsif ALWAYS_INCLUDED_HEADERS.include?(header)
-            acc[header] = @request_env[env_header]
-          elsif Castle.config.blacklisted.include?(header)
-            acc[header] = true
-          elsif Castle.config.whitelisted.empty? || Castle.config.whitelisted.include?(header)
-            acc[header] = @request_env[env_header]
-          else
-            acc[header] = true
-          end
+        @headers.each_with_object({}) do |(name, value), acc|
+          acc[name] = header_value(name, value)
         end
       end
+
+      private
+
+      # scrub header value
+      # @param name [String]
+      # @param value [String]
+      # @return [TrueClass | FalseClass | String]
+      def header_value(name, value)
+        return true if ALWAYS_BLACKLISTED.include?(name)
+        return value if ALWAYS_WHITELISTED.include?(name)
+        return true if Castle.config.blacklisted.include?(name)
+        return value if @no_whitelist || Castle.config.whitelisted.include?(name)
+
+        true
+      end
     end
   end
 end