castle-rb 5.0.0 → 7.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 441cbae1aed67e419bff1683c41183abb10c3890d5a159f3365c0b4bd3855f0b
-  data.tar.gz: 6ef7663b21e2de6b1ef833917dd4b62ee1891f017e33f88a1cb57252e5c3bcc4
+  metadata.gz: 774cdc6663639d2a96b9a9a0010bc34bea827edd6b7a42d2f72bb87f94573026
+  data.tar.gz: ab2d684474508d1e20fce26dabe1f7594cf255b8682e8b3b1d9b52289d5bab39
 SHA512:
-  metadata.gz: b54200b206ea055878d2e4a6b46f82960cda186c4b57009765c7e4c8cce28c7f00c66ad216840f8fa5412a7ed876224f285a18388620bf7df9201425a0efb055
-  data.tar.gz: cf9f8b5019377138fe5e61ced02b6323aa27464dc117c521fe560a6832115416bbd7e92a64a4710b96939adcd49af12feb538f3d24392d9654b14a21a48021a5
+  metadata.gz: 9810ca259c0e26cf3195c8ddc1ca1409256011a89584585dd806ddd6b98efac526de25371b33a7cd122a08f271b0d99c61fe68a8da53714483e85fdc065367db
+  data.tar.gz: c89c84e1748f1c8bf06e480d5273bfa8c5003da08b01b74f40d588fc1b0567d3828ea4e0b277d3526fe9a179836e5d86606cd88723cd5e70ecb40b23b925e1f5

data/README.md

@@ -62,8 +62,14 @@ Castle.configure do |config|
   # For authenticate method you can set failover strategies: allow(default), deny, challenge, throw
   config.failover_strategy = :deny
 
-  # Castle::RequestError is raised when timing out in milliseconds (default: 500 milliseconds)
-  config.request_timeout = 2000
+  # Castle::RequestError is raised when timing out in milliseconds (default: 1000 milliseconds)
+  config.request_timeout = 1500
+
+  # Base Castle API url
+  # config.base_url = "https://api.castle.io/v1"
+
+  # Logger (need to respond to info method) - logs Castle API requests and responses
+  # config.logger = Logger.new(STDOUT)
 
   # Allowlisted and Denylisted headers are case insensitive and allow to use _ and - as a separator, http prefixes are removed
   # Allowlisted headers
@@ -95,13 +101,14 @@ Castle.configure do |config|
   # 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 = []
+  # It would be used like so: config.ip_headers=['Cf-Connecting-Ip']
+  config.ip_headers = []
 
   # 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)
+  # then you must choose only one of the following (but not both):
+  # 1. The trusted_proxies value must match the known proxy IPs. This option is preferable if the IP is static.
+  # 2. The trusted_proxy_depth value must be set to the number of known trusted proxies in the chain (see below).
+  # This option is preferable if the IPs are ephemeral, but the depth is consistent.
 
   # 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
@@ -110,38 +117,60 @@ Castle.configure do |config|
   # 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 = []
+  # in the trusted_proxies setting
+  config.trusted_proxies = []
   # or by providing number of trusted proxies used in the chain
-  configuration.trusted_proxy_depth = 0
+  config.trusted_proxy_depth = 0
+  # note that you must pick one approach over the other.
 
-  # 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
+  # If there is no possibility to define options above and there is no other header that holds the client IP,
+  # then you may set trust_proxy_chain = true to trust all of the proxy IPs in X-Forwarded-For
+  config.trust_proxy_chain = false
+  # *Warning*: this mode is highly promiscuous and could lead to wrongly trusting a spoofed IP if the request passes through a malicious proxy
 
-  # *Note: default list of proxies which is always marked as trusted: Castle::Configuration::TRUSTED_PROXIES
+  # *Note: the default list of proxies that are always marked as "trusted" can be found in: Castle::Configuration::TRUSTED_PROXIES
 end
 ```
 
+### Multi-environment configuration
+
+It is also possible to define multiple configs within one application.
+
+```ruby
+# Initialize new instance of Castle::Configuration
+config = Castle::Configuration.new.tap do |c|
+  # and set any attribute
+  c.api_secret = 'YOUR_API_SECRET'
+end
+```
+
+After a successful setup, you can pass the config to any API command as follows:
+
+```ruby
+::Castle::API::GetDevice.call(device_token: device_token, config: config)
+```
+
 ## 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:
+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 along with the other data. For example:
 ```ruby
-request_context = ::Castle::Client.to_context(request)
-track_options = ::Castle::Client.to_options({
-  event: ::Castle::Events::LOGIN_SUCCEEDED,
+{
+  event: '$login.succeeded',
   user_id: user.id,
   properties: {
     key: 'value'
   },
   user_traits: {
     key: 'value'
+  },
+  context: {
+    section: 'mobile'
   }
-})
+}
 ```
 
 ## Tracking
@@ -151,7 +180,7 @@ Here is a simple example of a track event.
 ```ruby
 begin
   castle.track(
-    event: ::Castle::Events::LOGIN_SUCCEEDED,
+    event: '$login.succeeded',
     user_id: user.id
   )
 rescue Castle::Error => e
@@ -173,9 +202,8 @@ By default Castle sends requests synchronously. To eg. use Sidekiq to send reque
 class CastleTrackingWorker
   include Sidekiq::Worker
 
-  def perform(context, track_options = {})
-    client = ::Castle::Client.new(context)
-    client.track(track_options)
+  def perform(payload = {})
+    ::Castle::API::Track.call(payload)
   end
 end
 ```
@@ -183,18 +211,20 @@ end
 #### tracking_controller.rb
 
 ```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'
+payload = ::Castle::Payload::Prepare.call(
+  {
+    event: '$login.succeeded',
+    user_id: user.id,
+    properties: {
+      key: 'value'
+    },
+    user_traits: {
+      key: 'value'
+    }
   },
-  user_traits: {
-    key: 'value'
-  }
-})
-CastleTrackingWorker.perform_async(request_context, track_options)
+  request
+)
+CastleTrackingWorker.perform_async(payload)
 ```
 
 ## Connection reuse
@@ -202,14 +232,14 @@ CastleTrackingWorker.perform_async(request_context, track_options)
 If you want to reuse the connection to send multiple events:
 
 ```ruby
-Castle::API::Session.call do |http|
+Castle::Session.call do |http|
   castle.track(
-    event: ::Castle::Events::LOGOUT_SUCCEEDED,
+    event: '$logout.succeeded',
     user_id: user2.id
     http: http
   )
   castle.track(
-    event: ::Castle::Events::LOGIN_SUCCEEDED,
+    event: '$login.succeeded',
     user_id: user1.id
     http: http
   )
@@ -218,7 +248,41 @@ 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)
+List of Recognized Events can be found in the [docs](https://docs.castle.io/v1/reference/events/)
+
+## Device management
+
+This SDK allows issuing requests to [Castle's Device Management Endpoints](https://docs.castle.io/v1/reference/api-reference/#devices). Use these endpoints for admin-level management of end-user devices (i.e., for an internal dashboard).
+
+Fetching device data, approving a device, reporting a device requires a valid `device_token`.
+
+```ruby
+# Get device data
+::Castle::API::GetDevice.call(device_token: device_token)
+# Approve a device
+::Castle::API::ApproveDevice.call(device_token: device_token)
+# Report a device
+::Castle::API::ReportDevice.call(device_token: device_token)
+```
+
+#### castle_device_reporting_worker.rb
+
+```ruby
+class CastleDeviceReportingWorker
+  include Sidekiq::Worker
+
+  def perform(device_token)
+    ::Castle::API::ReportDevice.call(device_token: device_token)
+  end
+end
+```
+
+Fetching available devices that belong to a given user requires a valid `user_id`.
+
+```ruby
+# Get user's devices data
+::Castle::API::GetDevicesForUser.call(user_id: user.id)
+```
 
 ## Impersonation mode
 
@@ -229,6 +293,16 @@ https://castle.io/docs/impersonation_mode
 `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).
 
+## Webhooks
+
+Castle uses webhooks to notify about `$incident.confirmed` or `$review.opened` events. Each webhook has `X-Castle-Signature` header that allows verifying webhook's source.
+
+```ruby
+# Verify the webhook, passed as a Request object
+::Castle::Webhooks::Verify.call(webhook_request)
+# Castle::WebhookVerificationError is raised when the signature is not matching
+```
+
 ## Documentation
 
-[Official Castle docs](https://castle.io/docs)
+[Official Castle docs](https://docs.castle.io/)

data/lib/castle.rb

@@ -1,45 +1,65 @@
 # frozen_string_literal: true
 
-%w[
-  openssl
-  net/http
-  json
-  time
-].each(&method(:require))
+%w[openssl net/http json time].each(&method(:require))
 
 %w[
   castle/version
-  castle/events
+  castle/verdict
   castle/errors
   castle/command
-  castle/utils
-  castle/utils/merger
-  castle/utils/cloner
-  castle/utils/timestamp
+  castle/utils/deep_symbolize_keys
+  castle/utils/clean_invalid_chars
+  castle/utils/merge
+  castle/utils/clone
+  castle/utils/get_timestamp
+  castle/utils/secure_compare
   castle/validators/present
   castle/validators/not_supported
-  castle/context/merger
-  castle/context/sanitizer
-  castle/context/default
-  castle/commands/identify
+  castle/webhooks/verify
+  castle/context/merge
+  castle/context/sanitize
+  castle/context/get_default
+  castle/context/prepare
+  castle/commands/approve_device
   castle/commands/authenticate
+  castle/commands/end_impersonation
+  castle/commands/filter
+  castle/commands/get_device
+  castle/commands/get_devices_for_user
+  castle/commands/log
+  castle/commands/report_device
+  castle/commands/risk
+  castle/commands/start_impersonation
   castle/commands/track
-  castle/commands/review
-  castle/commands/impersonate
+  castle/api/approve_device
+  castle/api/authenticate
+  castle/api/end_impersonation
+  castle/api/filter
+  castle/api/get_device
+  castle/api/get_devices_for_user
+  castle/api/log
+  castle/api/report_device
+  castle/api/risk
+  castle/api/start_impersonation
+  castle/api/track
+  castle/payload/prepare
   castle/configuration
-  castle/failover_auth_response
+  castle/singleton_configuration
+  castle/logger
+  castle/failover/prepare_response
+  castle/failover/strategy
   castle/client
-  castle/headers_filter
-  castle/headers_formatter
+  castle/headers/filter
+  castle/headers/format
+  castle/headers/extract
   castle/secure_mode
-  castle/extractors/client_id
-  castle/extractors/headers
-  castle/extractors/ip
-  castle/api/connection
-  castle/api/response
-  castle/api/request
-  castle/api/session
-  castle/review
+  castle/client_id/extract
+  castle/ips/extract
+  castle/core/get_connection
+  castle/core/process_response
+  castle/core/send_request
+  castle/core/process_webhook
+  castle/session
   castle/api
 ].each(&method(:require))
 
@@ -55,7 +75,7 @@ module Castle
     end
 
     def config
-      Configuration.instance
+      SingletonConfiguration.instance
     end
 
     def api_secret=(api_secret)

data/lib/castle/api.rb

@@ -20,30 +20,34 @@ module Castle
       # @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?
+      # @param config [Castle::Configuration, Castle::SingletonConfiguration, nil]
+      # @return [Hash]
+      def call(command, headers = {}, http = nil, config = nil)
+        Castle::Core::ProcessResponse.call(send_request(command, headers, http, config), config)
+      end
+
+      private
+
+      # @param command [String]
+      # @param headers [Hash]
+      # @param http [Net::HTTP]
+      # @param config [Castle::Configuration, Castle::SingletonConfiguration]
+      def send_request(command, headers = {}, http = nil, config = nil)
+        config ||= Castle.config
+
+        raise Castle::ConfigurationError, 'configuration is not valid' unless config.valid?
 
         begin
-          Castle::API::Request.call(
-            command,
-            Castle.config.api_secret,
-            headers,
-            http
-          )
+          Castle::Core::SendRequest.call(command, headers, http, config)
         rescue *HANDLED_ERRORS => e
           # @note We need to initialize the error, as the original error is a cause for this
           # custom exception. If we would do it the default Ruby way, the original error
           # would get converted into a string
-          raise Castle::RequestError.new(e) # rubocop:disable Style/RaiseArgs
+          # rubocop:disable Style/RaiseArgs
+          raise Castle::RequestError.new(e)
+          # rubocop:enable 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/approve_device.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Castle
+  module API
+    # Sends PUT devices/#{device_token}/approve request
+    module ApproveDevice
+      class << self
+        # @param options [Hash]
+        # return [Hash]
+        def call(options = {})
+          options = Castle::Utils::DeepSymbolizeKeys.call(options || {})
+          http = options.delete(:http)
+          config = options.delete(:config) || Castle.config
+
+          Castle::API.call(Castle::Commands::ApproveDevice.build(options), {}, http, config)
+        end
+      end
+    end
+  end
+end

data/lib/castle/api/authenticate.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Castle
+  module API
+    module Authenticate
+      class << self
+        # @param options [Hash]
+        # return [Hash]
+        def call(options = {})
+          unless options[:no_symbolize]
+            options = Castle::Utils::DeepSymbolizeKeys.call(options || {})
+          end
+          options.delete(:no_symbolize)
+          http = options.delete(:http)
+          config = options.delete(:config) || Castle.config
+
+          response =
+            Castle::API.call(Castle::Commands::Authenticate.build(options), {}, http, config)
+          response.merge(failover: false, failover_reason: nil)
+        rescue Castle::RequestError, Castle::InternalServerError => e
+          unless config.failover_strategy == :throw
+            strategy = (config || Castle.config).failover_strategy
+            return(
+              Castle::Failover::PrepareResponse.new(
+                options[:user_id],
+                reason: e.to_s,
+                strategy: strategy
+              ).call
+            )
+          end
+
+          raise e
+        end
+      end
+    end
+  end
+end