castle-rb 3.6.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 01fa92f200806e9649d71afa71dff0e8ff37db950a74e122134fdbda5413ef8a
+  data.tar.gz: f3a11d66711788d68c228ff63b647326e5446fff0ddb1be4e33e4b400d4587a8
+SHA512:
+  metadata.gz: 5329a71bd213ee88665b68ab4a79f6eca7987355d839d9e26b4d132ea3d4b7986714d23c3b6f97e7743ce774d969438365ea004fdcdd99eb7643f5c07c43d7b9
+  data.tar.gz: 89d8241793e59288651ac45b8d799c545a9b60aa25e6ae8d0092cda6183e9ecdf3b9d5b8ee68e0184b8021dc8633f9f949c987c6f0cd3abc1db6f7f2b47bda99

data/README.md

@@ -0,0 +1,157 @@
+# Ruby SDK for Castle
+
+[![Build Status](https://travis-ci.org/castle/castle-ruby.svg?branch=master)](https://travis-ci.org/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)
+
+**[Castle](https://castle.io) analyzes device, location, and interaction patterns in your web and mobile apps and lets you stop account takeover attacks in real-time..**
+
+## Installation
+
+Add the `castle-rb` gem to your `Gemfile`
+
+```ruby
+gem 'castle-rb'
+```
+
+## Configuration
+
+### Framework configuration
+
+Load and configure the library with your Castle API secret in an initializer or similar.
+
+```ruby
+Castle.api_secret = 'YOUR_API_SECRET'
+```
+
+A Castle client instance will be made available as `castle` in your
+
+* Rails controllers when you add `require 'castle/support/rails'`
+
+* Padrino controllers when you add `require 'castle/support/padrino'`
+
+* Sinatra app when you add `require 'castle/support/sinatra'` (and additionally explicitly add `register Sinatra::Castle` to your `Sinatra::Base` class if you have a modular application)
+
+```ruby
+require 'castle/support/sinatra'
+
+class ApplicationController < Sinatra::Base
+  register Sinatra::Castle
+end
+```
+
+* Hanami when you add `require 'castle/support/hanami'` and include `Castle::Hanami` to your Hanami application
+
+```ruby
+require 'castle/support/hanami'
+
+module Web
+  class Application < Hanami::Application
+    include Castle::Hanami
+  end
+end
+```
+
+### Client configuration
+
+```ruby
+Castle.configure do |config|
+  # Same as setting it through Castle.api_secret
+  config.api_secret = 'secret'
+
+  # 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
+
+  # Whitelisted and Blacklisted headers are case insensitive and allow to use _ and - as a separator, http prefixes are removed
+  # Whitelisted headers
+  # By default, the SDK sends all HTTP headers, except for Cookie and Authorization.
+  # If you decide to use a whitelist, the SDK will:
+  # - always send the User-Agent header
+  # - send scrubbed values of non-whitelisted headers
+  # - send proper values of whitelisted headers.
+  # @example
+  #   config.whitelisted = ['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
+  # amount of headers we recommend:
+  config.whitelisted = Castle::Configuration::DEFAULT_WHITELIST
+
+  # 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']
+end
+```
+
+The client will automatically configure the context for each request.
+
+## Tracking
+
+Here is a simple example of a track event.
+
+
+```ruby
+begin
+  castle.track(
+    event: '$login.succeeded',
+    user_id: user.id
+  )
+rescue Castle::Error => e
+  puts e.message
+end
+```
+
+## Signature
+
+`Castle::SecureMode.signature(user_id)` will create a signed user_id.
+
+## Async tracking
+
+By default Castle sends requests synchronously. To eg. use Sidekiq to send requests in a background worker you can pass data to the worker:
+
+#### castle_tracking_worker.rb
+
+```ruby
+class CastleTrackingWorker
+  include Sidekiq::Worker
+
+  def perform(context, track_options = {})
+    client = ::Castle::Client.new(context)
+    client.track(track_options)
+  end
+end
+```
+
+#### tracking_controller.rb
+
+```ruby
+request_context = ::Castle::Client.to_context(request)
+track_options = ::Castle::Client.to_options({
+  event: '$login.succeeded',
+  user_id: user.id,
+  properties: {
+    key: 'value'
+  },
+  user_traits: {
+    key: 'value'
+  }
+})
+CastleTrackingWorker.perform_async(request_context, track_options)
+```
+
+## Impersonation mode
+
+https://castle.io/docs/impersonation
+
+## 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).
+
+## Documentation
+
+[Official Castle docs](https://castle.io/docs)

data/lib/castle-rb.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require 'castle'

data/lib/castle.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+%w[
+  openssl
+  net/http
+  json
+  time
+].each(&method(:require))
+
+%w[
+  castle/version
+  castle/errors
+  castle/command
+  castle/utils
+  castle/utils/merger
+  castle/utils/cloner
+  castle/utils/timestamp
+  castle/validators/present
+  castle/validators/not_supported
+  castle/context/merger
+  castle/context/sanitizer
+  castle/context/default
+  castle/commands/identify
+  castle/commands/authenticate
+  castle/commands/track
+  castle/commands/review
+  castle/commands/impersonate
+  castle/configuration
+  castle/failover_auth_response
+  castle/client
+  castle/header_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/review
+  castle/api
+].each(&method(:require))
+
+# main sdk module
+module Castle
+  class << self
+    def configure(config_hash = nil)
+      (config_hash || {}).each do |config_name, config_value|
+        config.send("#{config_name}=", config_value)
+      end
+
+      yield(config) if block_given?
+    end
+
+    def config
+      @configuration ||= Castle::Configuration.new
+    end
+
+    def api_secret=(api_secret)
+      config.api_secret = api_secret
+    end
+  end
+end

data/lib/castle/api.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Castle
+  # this class is responsible for making requests to api
+  module API
+    # Errors we handle internally
+    HANDLED_ERRORS = [
+      Timeout::Error,
+      Errno::EINVAL,
+      Errno::ECONNRESET,
+      EOFError,
+      Net::HTTPBadResponse,
+      Net::HTTPHeaderSyntaxError,
+      Net::ProtocolError
+    ].freeze
+
+    private_constant :HANDLED_ERRORS
+
+    class << self
+      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
+            )
+          )
+        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
+        end
+      end
+    end
+  end
+end

data/lib/castle/api/request.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Castle
+  # this class is responsible for making requests to api
+  module API
+    module Request
+      # Default headers that we add to passed ones
+      DEFAULT_HEADERS = {
+        'Content-Type' => 'application/json'
+      }.freeze
+
+      private_constant :DEFAULT_HEADERS
+
+      class << self
+        def call(command, api_secret, headers)
+          http.request(
+            Castle::API::Request::Build.call(
+              command,
+              headers.merge(DEFAULT_HEADERS),
+              api_secret
+            )
+          )
+        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
+          end
+          http
+        end
+      end
+    end
+  end
+end

data/lib/castle/api/request/build.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Castle
+  module API
+    # generate api request
+    module Request
+      module Build
+        class << self
+          def call(command, headers, api_secret)
+            request = Net::HTTP.const_get(
+              command.method.to_s.capitalize
+            ).new("/#{Castle.config.url_prefix}/#{command.path}", headers)
+
+            unless command.method == :get
+              request.body = ::Castle::Utils.replace_invalid_characters(
+                command.data
+              ).to_json
+            end
+
+            request.basic_auth('', api_secret)
+            request
+          end
+        end
+      end
+    end
+  end
+end

data/lib/castle/api/response.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Castle
+  module API
+    # parses api response
+    module Response
+      RESPONSE_ERRORS = {
+        400 => Castle::BadRequestError,
+        401 => Castle::UnauthorizedError,
+        403 => Castle::ForbiddenError,
+        404 => Castle::NotFoundError,
+        419 => Castle::UserUnauthorizedError,
+        422 => Castle::InvalidParametersError
+      }.freeze
+
+      class << self
+        def call(response)
+          verify!(response)
+
+          return {} if response.body.nil? || response.body.empty?
+
+          begin
+            JSON.parse(response.body, symbolize_names: true)
+          rescue JSON::ParserError
+            raise Castle::ApiError, 'Invalid response from Castle API'
+          end
+        end
+
+        def verify!(response)
+          return if response.code.to_i.between?(200, 299)
+
+          raise Castle::InternalServerError if response.code.to_i.between?(500, 599)
+
+          error = RESPONSE_ERRORS.fetch(response.code.to_i, Castle::ApiError)
+          raise error, response[:message]
+        end
+      end
+    end
+  end
+end

data/lib/castle/client.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Castle
+  class Client
+    class << self
+      def from_request(request, options = {})
+        new(
+          to_context(request, options),
+          to_options(options)
+        )
+      end
+
+      def to_context(request, options = {})
+        default_context = Castle::Context::Default.new(request, options[:cookies]).call
+        Castle::Context::Merger.call(default_context, options[:context])
+      end
+
+      def to_options(options = {})
+        options[:timestamp] ||= Castle::Utils::Timestamp.call
+        warn '[DEPRECATION] use user_traits instead of traits key' if options.key?(:traits)
+        options
+      end
+
+      def failover_response_or_raise(failover_response, error)
+        return failover_response.generate unless Castle.config.failover_strategy == :throw
+        raise error
+      end
+    end
+
+    attr_accessor :context
+
+    def initialize(context, options = {})
+      @do_not_track = options.fetch(:do_not_track, false)
+      @timestamp = options[:timestamp]
+      @context = context
+    end
+
+    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
+      end
+    end
+
+    def identify(options = {})
+      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)
+    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)
+    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|
+        raise Castle::ImpersonationFailed unless response[:success]
+      end
+    end
+
+    def disable_tracking
+      @do_not_track = true
+    end
+
+    def enable_tracking
+      @do_not_track = false
+    end
+
+    def tracked?
+      !@do_not_track
+    end
+
+    private
+
+    def add_timestamp_if_necessary(options)
+      options[:timestamp] ||= @timestamp if @timestamp
+    end
+  end
+end