castle_devise 0.1.0

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: %i[spec]

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "castle/devise"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/castle_devise.gemspec

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "lib/castle_devise/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "castle_devise"
+  spec.version = CastleDevise::VERSION
+  spec.license = "MIT"
+  spec.summary = "Integrates Castle with Devise"
+  spec.description = "castle_devise provides out-of-the-box protection against bot registrations and account takeover attacks."
+  spec.homepage = "https://github.com/castle/castle_devise"
+  spec.required_ruby_version = Gem::Requirement.new(">= 2.5.0")
+
+  spec.authors = ["Kacper Madej", "Johan Brissmyr"]
+  spec.email = ["kacper@castle.io"]
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/castle/castle_devise"
+  spec.metadata["changelog_uri"] = "https://github.com/castle/castle_devise/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Uncomment to register a new dependency of your gem
+  spec.add_dependency "castle-rb", ">= 7.0", "< 8.0"
+  spec.add_dependency "activesupport", ">= 5.0"
+
+  spec.add_runtime_dependency "devise", ">= 4.3.0", "< 5.0"
+end

data/lib/castle_devise.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "castle"
+require "devise"
+
+# CastleDevise consists of a few different parts:
+#
+# - Devise castle_protectable module defined in lib/castle_devise/models/
+# - Minimal monkey patches to Devise controller defined in lib/castle_devise/patches/
+# - Warden hooks defined in lib/castle_devise/hooks/
+# - A Facade layer on top of the Castle SDK: {CastleDevise::SdkFacade}
+# - A Context object that contains all the data you might want to use when integrating
+#   Castle with your application: {CastleDevise::Context}
+module CastleDevise
+  class << self
+    # @return [CastleDevise::Configuration]
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # @return [Logger]
+    def logger
+      configuration.logger
+    end
+
+    # @yieldparam [CastleDevise::Configuration] configuration object
+    def configure
+      yield configuration
+
+      Castle.api_secret = configuration.api_secret
+      Castle.config.logger = configuration.logger
+    end
+
+    # @return [true, false] whether in monitoring mode or not
+    def monitoring_mode?
+      configuration.monitoring_mode
+    end
+
+    # @return [CastleDevise::SdkFacade]
+    def sdk_facade
+      @sdk_facade ||= CastleDevise::SdkFacade.new(
+        castle,
+        configuration.before_request_hooks,
+        configuration.after_request_hooks
+      )
+    end
+
+    # @return [Castle::Client]
+    def castle
+      @castle ||= Castle::Client.new
+    end
+  end
+end
+
+require_relative "castle_devise/configuration"
+require_relative "castle_devise/context"
+require_relative "castle_devise/patches"
+require_relative "castle_devise/sdk_facade"
+require_relative "castle_devise/controllers/helpers"
+require_relative "castle_devise/helpers/castle_helper"
+require_relative "castle_devise/hooks/castle_protectable"
+require_relative "castle_devise/models/castle_protectable"
+require_relative "castle_devise/patches/registrations_controller"
+
+require_relative "castle_devise/rails"
+
+# Monkey patching Devise module in order to add
+# additional configuration options
+module Devise
+  # Configures which events trigger Castle API calls
+  mattr_accessor :castle_hooks
+  @@castle_hooks = {
+    before_registration: true,
+    after_login: true
+  }
+end
+
+Devise.add_module :castle_protectable, model: "castle_devise/models/castle_protectable"

data/lib/castle_devise/configuration.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "active_support/configurable"
+require "logger"
+
+module CastleDevise
+  # Configuration object using {ActiveSupport::Configurable}
+  class Configuration
+    include ActiveSupport::Configurable
+
+    # @!attribute api_secret
+    #   @return [String] Your API secret
+    config_accessor(:api_secret)
+
+    # @!attribute app_id
+    #   @return [String] Your Castle App ID
+    config_accessor(:app_id)
+
+    # @!attribute monitoring_mode
+    #   When CastleDevise is in monitoring mode, it sends requests to Castle
+    #   but it doesn't act on "deny" verdicts.
+    #
+    #   This mode is useful if you're just checking Castle out and you're not yet sure whether
+    #   your configuration is correct so you don't accidentally block legitimate users
+    #   from logging in/registering.
+    #
+    #   @return [true, false] whether to act on deny requests or not
+    config_accessor(:monitoring_mode) { false }
+
+    # @!attribute logger
+    #   @return [Logger] A Logger instance. You might want to use Rails.logger here.
+    config_accessor(:logger) { Logger.new("/dev/null") }
+
+    # @!attribute before_request_hooks
+    #   @return [Array<Proc>] Array of procs that will get called before a request to the Castle API
+    config_accessor(:before_request_hooks) { [] }
+
+    # @!attribute after_request_hooks
+    #   @return [Array<Proc>] Array of procs that will get called after a request to the Castle API
+    config_accessor(:after_request_hooks) { [] }
+
+    # Adds a new before_request hook
+    # @param blk [Proc]
+    def before_request(&blk)
+      before_request_hooks << blk
+    end
+
+    # Adds a new after_request hook
+    # @param blk [Proc]
+    def after_request(&blk)
+      after_request_hooks << blk
+    end
+  end
+end

data/lib/castle_devise/context.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module CastleDevise
+  # Provides a small layer of abstraction on top of raw Rack::Request and Warden
+  class Context
+    class << self
+      # @param rack_env [Hash]
+      # @param scope [Symbol] Warden scope
+      # @param resource [ActiveRecord::Base, nil]
+      # @return [CastleDevise::Context]
+      def from_rack_env(rack_env, scope, resource = nil)
+        new(rack_request: Rack::Request.new(rack_env), scope: scope, resource: resource)
+      end
+    end
+
+    # @return [Rack::Request]
+    attr_reader :rack_request
+    # @return [ActiveRecord::Base, nil]
+    attr_reader :resource
+    # @return [Symbol] The Devise scope for the resource
+    attr_reader :scope
+
+    # @param rack_request [Rack::Request]
+    # @param resource [ActiveRecord::Base, nil]
+    # @param scope [Symbol] Warden scope
+    def initialize(rack_request:, scope:, resource: nil)
+      @rack_request = rack_request
+      @resource = resource
+      @scope = scope
+    end
+
+    # @return [String, nil] Castle request token, if present in POST params
+    def request_token
+      rack_request.env.dig("rack.request.form_hash", "castle_request_token")
+    end
+
+    # @return [String, nil] user_id that will be sent to Castle
+    def castle_id
+      resource&.castle_id
+    end
+
+    # Email for the current context. If there is no resource available (eg. for a failed login request)
+    # this method will attempt to fetch an email from Rack POST parameters using the current Devise scope.
+    #
+    # @return [String, nil]
+    def email
+      resource&.email || email_from_form_params
+    end
+
+    # @return [String, nil]
+    def username
+      resource&.castle_name
+    end
+
+    # @return [Hash] additional user traits that will be sent to Castle
+    def user_traits
+      resource&.castle_traits || {}
+    end
+
+    # @return [Time, nil]
+    def registered_at
+      resource&.created_at
+    end
+
+    # Logs out current resource. Adds `castle_devise: :skip` to the authentication options
+    # to make sure we do not accidentally call Castle due to auth failure.
+    def logout!
+      warden.logout(scope)
+      throw(:warden, scope: scope, castle_devise: :skip, message: :not_found_in_database)
+    end
+
+    private
+
+    # Attempts to retrieve an email from Rack form parameters for the current Devise scope.
+    #
+    # @return [String, nil]
+    def email_from_form_params
+      rack_request.env.dig("rack.request.form_hash", scope.to_s, "email")
+    end
+
+    # @return [Warden::Proxy]
+    def warden
+      rack_request.env["warden"]
+    end
+  end
+end

data/lib/castle_devise/controllers/helpers.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module CastleDevise
+  module Controllers
+    # Methods defined here will be included in all your controllers.
+    module Helpers
+      # @return [Castle::Client]
+      def castle
+        CastleDevise.castle
+      end
+
+      # Returns a Castle response from /v1/risk endpoint, if such a request has been made
+      # during the request.
+      #
+      # @return [Hash, nil]
+      def castle_risk_response
+        request.env["castle_devise.risk_response"]
+      end
+
+      # Returns true if Castle Risk API call resulted in a "challenge" action.
+      # Returns false if no request has been made, or the action was different than "challenge".
+      #
+      # @return [true, false]
+      def castle_challenge?
+        castle_risk_response&.dig(:policy, :action) == "challenge"
+      end
+    end
+  end
+end

data/lib/castle_devise/helpers/castle_helper.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module CastleDevise
+  module Helpers
+    # Methods defined here will be available in all your views.
+    module CastleHelper
+      # Creates a <script> tag that includes our c.js script from a CDN.
+      # You have to make sure that your app_id is valid, otherwise the script won't work.
+      #
+      # You shouldn't call this method if you bundle our c.js script with your other
+      # JS packages.
+      #
+      # You should put this in the <head> section of your page:
+      #
+      # @example
+      #   # app/views/layouts/application.html.erb
+      #   <!DOCTYPE html>
+      #   <html>
+      #   <head>
+      #     <%= castle_javascript_tag %>
+      #   <title>Your app title</title>
+      #
+      #   <!-- the rest of your layout -->
+      def castle_javascript_tag
+        javascript_include_tag(
+          "https://d2t77mnxyo7adj.cloudfront.net/v1/c.js?#{CastleDevise.configuration.app_id}"
+        )
+      end
+
+      # Puts an inline <script> tag that includes a "castle_devise_token" field
+      # within the current form.
+      #
+      # @example
+      #   <%= form_for(resource, as: resource_name, url: sessions_path(resource_name)) do |f| %>
+      #     <%= castle_request_token %>
+      #     <%= f.email_field :email %>
+      #     <%= f.password_field :password, autocomplete: 'off' %>
+      #   <% end %>
+      #
+      # @return [String]
+      def castle_request_token
+        tag = <<~HEREDOC
+          <script>
+          // The current script tag is the last one at the time of load
+          var el = document.getElementsByTagName('script');
+          el = el[el.length - 1];
+
+          // Traverse up until we find a form
+          while (el  && el !== document) {
+            if (el.tagName === 'FORM') break;
+            el = el.parentNode;
+          }
+
+          // Intercept the form submit
+          if (el.tagName === 'FORM') {
+            el.onsubmit = function(e) {
+              e.preventDefault();
+
+              _castle('createRequestToken').then(function(requestToken) {
+                // Populate a hidden field called `castle_request_token` with the
+                // request token
+                var hiddenInput = document.createElement('input');
+                hiddenInput.setAttribute('type', 'hidden');
+                hiddenInput.setAttribute('name', 'castle_request_token');
+                hiddenInput.setAttribute('value', requestToken);
+
+                // Add the hidden field to the form so it gets sent to the server
+                // before submitting the form
+                el.appendChild(hiddenInput);
+
+                el.submit();
+              });
+            };
+          } else {
+            console.log('[Castle] The script helper needs to be within a <form> tag')
+          }
+          </script>
+        HEREDOC
+        tag.html_safe
+      end
+    end
+  end
+end

data/lib/castle_devise/hooks/castle_protectable.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+Warden::Manager.after_authentication do |resource, warden, opts|
+  next unless resource.devise_modules.include?(:castle_protectable)
+  next unless resource.class.castle_hooks[:after_login]
+
+  context = CastleDevise::Context.from_rack_env(warden.env, opts[:scope], resource)
+
+  warden.env["castle_devise.risk_context"] = context
+
+  begin
+    response = CastleDevise.sdk_facade.risk(
+      event: "$login",
+      context: context
+    )
+
+    warden.env["castle_devise.risk_response"] = response
+
+    next if CastleDevise.monitoring_mode?
+
+    if response.dig(:policy, :action) == "deny"
+      # high ATO risk, pretend the User does not exist
+      context.logout!
+    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/risk 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."
+    )
+
+    context.logout! unless CastleDevise.monitoring_mode?
+  rescue Castle::Error => e
+    # log API errors and allow
+    CastleDevise.logger.error("[CastleDevise] risk($login): #{e}")
+  end
+end
+
+Warden::Manager.before_failure do |env, opts|
+  next if opts[:castle_devise] == :skip
+
+  resource_class = Devise.mappings[opts[:scope]].to
+
+  next if resource_class.nil?
+  next unless resource_class.devise_modules.include?(:castle_protectable)
+  next unless resource_class.castle_hooks[:after_login]
+
+  context = CastleDevise::Context.from_rack_env(env, opts[:scope])
+
+  begin
+    CastleDevise.sdk_facade.log(
+      event: "$login",
+      status: "$failed",
+      context: context
+    )
+  rescue Castle::Error => e
+    CastleDevise.logger.error("[CastleDevise] log($login, $failed): #{e}")
+  end
+end