castle_devise 0.1.0

data/lib/castle_devise/models/castle_protectable.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Devise
+  module Models
+    # This module contains methods that will be included in your Devise model when you
+    # include the castle_protectable Devise module.
+    #
+    # Configuration:
+    #
+    #   castle_hooks: configures which events trigger Castle API calls
+    #     {
+    #       after_login: true, # trigger risk($login) and log($login, $failed),
+    #       before_registration: true # trigger filter($registration)
+    #     }
+    module CastleProtectable
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+        Devise::Models.config(self, :castle_hooks)
+      end
+
+      # @return [String, nil] ID used for sending requests to Castle
+      def castle_id
+        id&.to_s
+      end
+
+      # @return [Hash] additional traits that will be sent to Castle
+      #
+      # @example
+      # @example
+      #   class User
+      #     belongs_to :company
+      #
+      #     devise :castle_protectable,
+      #            :confirmable,
+      #            :database_authenticatable,
+      #            :registerable,
+      #            :rememberable,
+      #            :validatable
+      #
+      #     def castle_traits
+      #       {
+      #         company_name: company.name
+      #       }
+      #     end
+      #   end
+      def castle_traits
+        {}
+      end
+
+      # This method is meant to be overridden with a human-readable username
+      # that will be shown on the Castle Dashboard.
+      #
+      # @return [String, nil]
+      #
+      # @example
+      #   class User
+      #     devise :castle_protectable,
+      #            :confirmable,
+      #            :database_authenticatable,
+      #            :registerable,
+      #            :rememberable,
+      #            :validatable
+      #
+      #     def castle_name
+      #       [first_name, last_name].join(' ').strip
+      #     end
+      #   end
+      def castle_name
+        nil
+      end
+    end
+  end
+end

data/lib/castle_devise/patches.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module CastleDevise
+  module Patches
+    class << self
+      # Applies monkey-patches to Devise controllers
+      # @api private
+      def apply
+        Devise::RegistrationsController.send(:include, Patches::RegistrationsController)
+      end
+    end
+  end
+end

data/lib/castle_devise/patches/registrations_controller.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module CastleDevise
+  module Patches
+    # Monkey-patch for
+    # {https://github.com/heartcombo/devise/blob/master/app/controllers/devise/registrations_controller.rb Devise::RegistrationsController}
+    # which includes Castle in the registration workflow.
+    module RegistrationsController
+      extend ActiveSupport::Concern
+
+      included do
+        before_action :castle_filter, only: :create
+      end
+
+      # Sends a /v1/filter request to Castle
+      def castle_filter
+        return unless resource_class.castle_hooks[:before_registration]
+
+        response = CastleDevise.sdk_facade.filter(
+          event: "$registration",
+          context: CastleDevise::Context.from_rack_env(request.env, resource_name)
+        )
+
+        return if CastleDevise.monitoring_mode?
+
+        case response.dig(:policy, :action)
+        when "deny"
+          set_flash_message!(:alert, "blocked_by_castle")
+          flash.alert = "Account cannot be created at this moment. Please try again later."
+          redirect_to new_session_path(resource_name)
+          false
+        else
+          # everything fine, continue
+        end
+      rescue Castle::InvalidParametersError
+        # TODO: We should act differently if the error is about missing/invalid request token
+        #   compared to any other validation errors. However, we can't do this with the
+        #   current Castle SDK as it doesn't give us any way to differentiate these two cases.
+        CastleDevise.logger.warn(
+          "[CastleDevise] /v1/filter request contained invalid parameters." \
+          " This might mean that either you didn't configure Castle's Javascript properly, or" \
+          " a request has been made without Javascript (eg. cURL/bot)." \
+          " Such a request is treated as if Castle responded with a 'deny' action in non-monitoring mode."
+        )
+
+        unless CastleDevise.monitoring_mode?
+          set_flash_message!(:alert, "blocked_by_castle")
+          redirect_to new_session_path(resource_name)
+          false
+        end
+      rescue Castle::Error => e
+        # log API errors and allow
+        CastleDevise.logger.error("[CastleDevise] filter($registration): #{e}")
+      end
+    end
+  end
+end

data/lib/castle_devise/rails.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+ActiveSupport.on_load(:action_controller) do
+  include CastleDevise::Controllers::Helpers
+end
+
+ActiveSupport.on_load(:action_view) do
+  include CastleDevise::Helpers::CastleHelper
+end
+
+ActiveSupport::Reloader.to_prepare do
+  CastleDevise::Patches.apply
+end

data/lib/castle_devise/sdk_facade.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module CastleDevise
+  # A Facade layer providing a simpler API on top of the Castle SDK
+  class SdkFacade
+    # @return [Castle::Client]
+    attr_reader :castle
+
+    # @param castle [Castle::Client]
+    # @param before_request_hooks [Array<Proc>]
+    # @param after_request_hooks [Array<Proc>]
+    def initialize(castle, before_request_hooks = [], after_request_hooks = [])
+      @castle = castle
+      @before_request_hooks = before_request_hooks
+      @after_request_hooks = after_request_hooks
+    end
+
+    # Sends request to the /v1/filter endpoint.
+    # @param event [String]
+    # @param context [CastleDevise::Context]
+    # @return [Hash] Raw API response
+    # @see https://docs.castle.io/v1/reference/api-reference/#v1filter
+    def filter(event:, context:)
+      payload = {
+        event: event,
+        user: {
+          email: context.email
+        },
+        request_token: context.request_token,
+        context: payload_context(context.rack_request)
+      }
+
+      with_request_hooks(:filter, context, payload) do
+        castle.filter(payload)
+      end
+    end
+
+    # Sends request to the /v1/risk endpoint.
+    # @param event [String]
+    # @param context [CastleDevise::Context]
+    # @return [Hash] Raw API response
+    # @see https://docs.castle.io/v1/reference/api-reference/#v1risk
+    def risk(event:, context:)
+      payload = {
+        event: event,
+        status: "$succeeded",
+        user: {
+          id: context.castle_id,
+          email: context.email,
+          registered_at: format_time(context.registered_at),
+          traits: context.user_traits
+        },
+        request_token: context.request_token,
+        context: payload_context(context.rack_request)
+      }
+
+      payload[:user][:name] = context.username if context.username
+
+      with_request_hooks(:risk, context, payload) do
+        castle.risk(payload)
+      end
+    end
+
+    # Sends request to the /v1/log endpoint.
+    # @param event [String]
+    # @param status [String, nil]
+    # @param context [CastleDevise::Context]
+    # @return [Hash] Raw API response
+    # @see https://docs.castle.io/v1/reference/api-reference/#v1log
+    def log(event:, status:, context:)
+      payload = {
+        event: event,
+        status: status,
+        user: {
+          id: context.castle_id,
+          email: context.email,
+          registered_at: format_time(context.registered_at),
+          traits: context.user_traits
+        }.compact,
+        context: payload_context(context.rack_request)
+      }
+
+      # request_token is optional on the Log endpoint, but if it's sent it must
+      # be a valid Castle token
+      payload[:request_token] = context.request_token if context.request_token
+
+      with_request_hooks(:log, context, payload) do
+        castle.log(payload)
+      end
+    end
+
+    private
+
+    attr_reader :before_request_hooks, :after_request_hooks
+
+    # @param rack_request [Rack::Request]
+    # @return [Hash]
+    def payload_context(rack_request)
+      ctx = Castle::Context::Prepare.call(rack_request)
+
+      # Castle SDK still generates some legacy parameters which can be removed
+      # when sending requests to the new Castle endpoints
+      ctx.slice!(:headers, :ip, :library)
+
+      ctx
+    end
+
+    # @param time [Time, nil]
+    # @return [String, nil]
+    def format_time(time)
+      time&.utc&.iso8601(3)
+    end
+
+    # @param action [Symbol] Castle API method
+    # @param context [CastleDevise::Context]
+    # @param payload [Hash] payload passed to the Castle Client
+    def with_request_hooks(action, context, payload)
+      before_request(action, context, payload)
+
+      yield.tap do |response|
+        after_request(action, context, payload, response)
+      end
+    end
+
+    # @param action [Symbol] Castle API method
+    # @param context [CastleDevise::Context]
+    # @param payload [Hash] payload passed to the Castle Client
+    def before_request(action, context, payload)
+      before_request_hooks.each do |hook|
+        hook.call(action, context, payload)
+      end
+    end
+
+    # @param action [Symbol] Castle API method
+    # @param context [CastleDevise::Context]
+    # @param payload [Hash] payload passed to the Castle Client
+    # @param response [Hash] response received from Castle
+    def after_request(action, context, payload, response)
+      after_request_hooks.each do |hook|
+        hook.call(action, context, payload, response)
+      end
+    end
+  end
+end

data/lib/castle_devise/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module CastleDevise
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,127 @@
+--- !ruby/object:Gem::Specification
+name: castle_devise
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kacper Madej
+- Johan Brissmyr
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2021-07-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: castle-rb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: devise
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.3.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.3.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: castle_devise provides out-of-the-box protection against bot registrations
+  and account takeover attacks.
+email:
+- kacper@castle.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/lint.yml"
+- ".github/workflows/specs.yml"
+- ".gitignore"
+- ".rspec"
+- CHANGELOG.md
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- castle_devise.gemspec
+- lib/castle_devise.rb
+- lib/castle_devise/configuration.rb
+- lib/castle_devise/context.rb
+- lib/castle_devise/controllers/helpers.rb
+- lib/castle_devise/helpers/castle_helper.rb
+- lib/castle_devise/hooks/castle_protectable.rb
+- lib/castle_devise/models/castle_protectable.rb
+- lib/castle_devise/patches.rb
+- lib/castle_devise/patches/registrations_controller.rb
+- lib/castle_devise/rails.rb
+- lib/castle_devise/sdk_facade.rb
+- lib/castle_devise/version.rb
+homepage: https://github.com/castle/castle_devise
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/castle/castle_devise
+  source_code_uri: https://github.com/castle/castle_devise
+  changelog_uri: https://github.com/castle/castle_devise/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key:
+specification_version: 4
+summary: Integrates Castle with Devise
+test_files: []