castle-rb 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 7cf6e4ab5cc8e82409be1c17d5c4a27a9c71190d
+  data.tar.gz: 2a79f7284ad075e025d2c5c3c160c1bce6ef5134
+SHA512:
+  metadata.gz: f0487c283b4da37dabb38d870be3d79d69013ef6ac267954dea165f8d2aa8b2fa61570ddc9911e880a533921fc5b0bdb05743164b0c5572dbb80b69cbd24bee7
+  data.tar.gz: 309970c57c13c40158906f226af70ce790077a3a6f818f24d39a319c0fbd74a777141d9dc14019199e4d366bab38b3c211381e70740b4332d5f8f56d46934064

data/README.md

@@ -0,0 +1,77 @@
+# Ruby SDK for Castle
+
+[![Build Status](https://travis-ci.org/castle/castle-ruby.png)](https://travis-ci.org/castle/castle-ruby)
+[![Gem Version](https://badge.fury.io/rb/castle.png)](http://badge.fury.io/rb/castle)
+[![Dependency Status](https://gemnasium.com/castle/castle-ruby.png)](https://gemnasium.com/castle/castle-ruby)
+[![Coverage Status](https://coveralls.io/repos/castle/castle-ruby/badge.png)](https://coveralls.io/r/castle/castle-ruby)
+
+**[Castle](https://castle.io) adds real-time monitoring of your authentication stack, instantly notifying you and your users on potential account hijacks.**
+
+## Installation
+
+Add the `castle-rb` gem to your `Gemfile`
+
+```ruby
+gem 'castle-rb'
+```
+
+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 automatically be made available as `castle` in your Rails, Sinatra or Padrino controllers.
+
+## Tracking security events
+
+`track` lets you record the security-related actions your users perform. The more actions you track, the more accurate Castle is in identifying fraudsters.
+
+Event names and detail properties that have semantic meaning are prefixed `$`, and we handle them in special ways.
+
+When you have access to a **logged in user**, set `user_id` to the same user identifier as when you initiated Castle.js.
+
+```ruby
+castle.track(
+  name: '$login.succeeded',
+  user_id: user.id)
+```
+
+When you **don't** have access to a logged in user just omit `user_id`, typically when tracking `$login.failed` and `$password_reset.requested`. Instead, whenever you have access to the user-submitted form value, add this to the event details as `$login`.
+
+```ruby
+castle.track(
+  name: '$login.failed',
+  details: {
+    '$login' => 'johan@castle.io'
+  })
+```
+
+### Supported events
+
+- `$login.succeeded`: Record when a user attempts to log in.
+- `$login.failed`: Record when a user logs out.
+- `$logout.succeeded`:  Record when a user logs out.
+- `$registration.succeeded`: Capture account creation, both when a user signs up as well as when created manually by an administrator.
+- `$registration.failed`: Record when an account failed to be created.
+- `$password_reset.requested`: An attempt was made to reset a user’s password.
+- `$password_reset.succeeded`: 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.failed`: Use to record when a user failed to reset their password.
+- `$password_change.succeeded`: Use to record when a user changed their password. This event is only logged when users change their **own** password.
+- `$password_change.failed`:  Use to record when a user failed to change their password.
+
+### Supported detail properties
+
+- `$login`: The submitted email or username from when the user attempted to log in or reset their password. Useful when there is no `user_id` available.
+
+## Configuration
+
+```ruby
+Castle.configure do |config|
+  # Same as setting it through Castle.api_secret
+  config.api_secret = 'secret'
+
+  # Castle::RequestError is raised when timing out (default: 30.0)
+  config.request_timeout = 2.0
+end
+```

data/lib/castle.rb

@@ -0,0 +1,47 @@
+require 'her'
+require 'castle/ext/her'
+require 'faraday_middleware'
+require 'multi_json'
+require 'openssl'
+require 'net/http'
+require 'request_store'
+require 'active_support/core_ext/hash/indifferent_access'
+
+require 'castle/version'
+
+require 'castle/configuration'
+require 'castle/client'
+require 'castle/errors'
+require 'castle/token_store'
+require 'castle/jwt'
+require 'castle/utils'
+require 'castle/request'
+require 'castle/session_token'
+
+require 'castle/support/cookie_store'
+require 'castle/support/rails' if defined?(Rails::Railtie)
+if defined?(Sinatra::Base)
+  if defined?(Padrino)
+    require 'castle/support/padrino'
+  else
+    require 'castle/support/sinatra'
+  end
+end
+
+module Castle
+  API = Castle.setup_api
+end
+
+# These need to be required after setting up Her
+require 'castle/models/model'
+require 'castle/models/account'
+require 'castle/models/event'
+require 'castle/models/challenge'
+require 'castle/models/context'
+require 'castle/models/monitoring'
+require 'castle/models/pairing'
+require 'castle/models/backup_codes'
+require 'castle/models/recommendation'
+require 'castle/models/session'
+require 'castle/models/trusted_device'
+require 'castle/models/user'

data/lib/castle/client.rb

@@ -0,0 +1,139 @@
+module Castle
+  class Client
+
+    attr_accessor :request_context
+
+    def self.install_proxy_methods(*names)
+      names.each do |name|
+        class_eval <<-RUBY, __FILE__, __LINE__ + 1
+          def #{name}(*args)
+            Castle::User.new('$current').#{name}(*args)
+          end
+        RUBY
+      end
+    end
+
+    install_proxy_methods :challenges, :events, :sessions, :pairings,
+      :backup_codes, :generate_backup_codes, :trusted_devices,
+      :enable_mfa!, :disable_mfa!
+
+    def initialize(request, response, opts = {})
+      # Save a reference in the per-request store so that the request
+      # middleware in request.rb can access it
+      RequestStore.store[:castle] = self
+
+      if response.class.name == 'ActionDispatch::Cookies::CookieJar'
+        cookies = Castle::CookieStore::Rack.new(response)
+      else
+        cookies = Castle::CookieStore::Base.new(request, response)
+      end
+
+      @store = Castle::TokenStore.new(cookies)
+
+      @request_context = {
+        ip: request.ip,
+        user_agent: request.user_agent,
+        cookie_id: cookies['__cid']
+      }
+    end
+
+    def session_token
+      @store.session_token
+    end
+
+    def session_token=(session_token)
+      @store.session_token = session_token
+    end
+
+    def authorize!
+      unless @store.session_token
+        raise Castle::UserUnauthorizedError,
+          'Need to call login before authorize'
+      end
+
+      if @store.session_token.expired?
+        Castle::Monitoring.heartbeat
+      end
+
+      if mfa_in_progress?
+        logout
+        raise Castle::UserUnauthorizedError,
+            'Logged out due to being unverified'
+      end
+
+      if mfa_required? && !device_trusted?
+        raise Castle::ChallengeRequiredError
+      end
+    end
+
+    def authorized?
+      !!@store.session_token
+    end
+
+    def login(user_id, user_attrs = {})
+      # Clear the session token if any
+      @store.session_token = nil
+
+      user = Castle::User.new(user_id.to_s)
+      session = user.sessions.create(
+        user: user_attrs, trusted_device_token: @store.trusted_device_token)
+
+      # Set the session token for use in all subsequent requests
+      @store.session_token = session.token
+
+      session
+    end
+
+    def logout
+      return unless @store.session_token
+
+      # Destroy the current session specified in the session token
+      begin
+        sessions.destroy('$current')
+      rescue Castle::ApiError # ignored
+      end
+
+      # Clear the session token
+      @store.session_token = nil
+    end
+
+    def trust_device(attrs = {})
+      unless @store.session_token
+        raise Castle::UserUnauthorizedError,
+          'Need to call login before trusting device'
+      end
+      trusted_device = trusted_devices.create(attrs)
+
+      # Set the session token for use in all subsequent requests
+      @store.trusted_device_token = trusted_device.token
+    end
+
+    def mfa_enabled?
+      @store.session_token ? @store.session_token.mfa_enabled? : false
+    end
+
+    def device_trusted?
+      @store.session_token ? @store.session_token.device_trusted? : false
+    end
+
+    def mfa_in_progress?
+      @store.session_token ? @store.session_token.mfa_in_progress? : false
+    end
+
+    def mfa_required?
+      @store.session_token ? @store.session_token.mfa_required? : false
+    end
+
+    def has_default_pairing?
+      @store.session_token ? @store.session_token.has_default_pairing? : false
+    end
+
+    def track(opts = {})
+      Castle::Event.post('/v1/events', opts)
+    end
+
+    def recommendation(opts = {})
+      Castle::Recommendation.get('/v1/recommendation', opts)
+    end
+  end
+end

data/lib/castle/configuration.rb

@@ -0,0 +1,37 @@
+module Castle
+  class << self
+    def configure(config_hash=nil)
+      if config_hash
+        config_hash.each do |k,v|
+          config.send("#{k}=", v)
+        end
+      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
+
+  class Configuration
+    attr_accessor :request_timeout
+
+    def initialize
+      self.request_timeout = 30.0
+    end
+
+    def api_secret
+      ENV['CASTLE_API_SECRET'] || @_api_secret || ''
+    end
+
+    def api_secret=(value)
+      @_api_secret = value
+    end
+  end
+end

data/lib/castle/errors.rb

@@ -0,0 +1,16 @@
+class Castle::Error < Exception; end
+
+class Castle::RequestError < Castle::Error; end
+class Castle::SecurityError < Castle::Error; end
+class Castle::ConfigurationError < Castle::Error; end
+
+class Castle::ApiError < Castle::Error; end
+
+class Castle::BadRequestError < Castle::ApiError; end
+class Castle::ForbiddenError < Castle::ApiError; end
+class Castle::NotFoundError < Castle::ApiError; end
+class Castle::UserUnauthorizedError < Castle::ApiError; end
+class Castle::InvalidParametersError < Castle::ApiError; end
+
+class Castle::UnauthorizedError < Castle::ApiError; end
+class Castle::ChallengeRequiredError < Castle::ApiError; end

data/lib/castle/ext/her.rb

@@ -0,0 +1,14 @@
+#
+# Add destroy to association: user.challenges.destroy(id)
+#
+module Her::Model::Associations
+  class AssociationProxy
+    install_proxy_methods :association, :destroy
+  end
+
+  class HasManyAssociation < Association ## remove inheritance
+    def destroy(id)
+      @klass.destroy_existing(id, :"#{@parent.singularized_resource_name}_id" => @parent.id)
+    end
+  end
+end

data/lib/castle/jwt.rb

@@ -0,0 +1,36 @@
+require 'jwt'
+
+module Castle
+  class JWT
+    attr_accessor :header, :payload
+
+    def initialize(jwt)
+      begin
+        raise Castle::SecurityError, 'Empty JWT' unless jwt
+        @payload = ::JWT.decode(jwt, Castleconfig.api_secret, true) do |header|
+          @header = header.with_indifferent_access
+          Castleconfig.api_secret # used by the 'key finder' in the JWT gem
+        end.with_indifferent_access
+      rescue ::JWT::DecodeError => e
+        raise Castle::SecurityError.new(e)
+      end
+    end
+
+    def expired?
+      Time.now.utc > Time.at(@header['exp']).utc
+    end
+
+    def merge!(payload = {})
+      @payload.merge!(payload)
+    end
+
+    def to_json
+      @payload
+    end
+
+    def to_token
+      ::JWT.encode(@payload, Castleconfig.api_secret, "HS256", @header)
+    end
+
+  end
+end

data/lib/castle/models/account.rb

@@ -0,0 +1,11 @@
+module Castle
+  class Account < Model
+    def self.fetch
+      get('/v1/account')
+    end
+
+    def self.update(settings = {})
+      put('/v1/account', settings: settings)
+    end
+  end
+end

data/lib/castle/models/backup_codes.rb

@@ -0,0 +1,4 @@
+module Castle
+  class BackupCodes < Model
+  end
+end

data/lib/castle/models/challenge.rb

@@ -0,0 +1,7 @@
+module Castle
+  class Challenge < Model
+    collection_path "users/:user_id/challenges"
+    has_one :pairing
+    instance_post :verify
+  end
+end

data/lib/castle/models/context.rb

@@ -0,0 +1,18 @@
+module Castle
+  class Context < Model
+    def user_agent
+      if attributes['user_agent']
+        Castle::UserAgent.new(attributes['user_agent'])
+      end
+    end
+
+    def location
+      if attributes['location']
+        Castle::Location.new(attributes['location'])
+      end
+    end
+  end
+
+  class UserAgent < Model; end
+  class Location < Model; end
+end

data/lib/castle/models/event.rb

@@ -0,0 +1,7 @@
+module Castle
+  class Event < Model
+    collection_path "users/:user_id/events"
+    belongs_to :user
+    has_one :context
+  end
+end

data/lib/castle/models/model.rb

@@ -0,0 +1,71 @@
+require 'her'
+
+class Her::Collection
+  # Call the overridden to_json in Castle::Model
+  def to_json
+    self.map { |m| m.to_json }
+  end
+end
+
+module Castle
+  class Model
+    include Her::Model
+    use_api Castle::API
+
+    def initialize(args = {})
+      # allow initializing with id as a string
+      args = { id: args } if args.is_a? String
+      super(args)
+    end
+
+    # Transform model.user.id to model.user_id to allow calls on nested models
+    def attributes
+      attrs = super
+      if attrs['user'] && attrs['user']['id']
+        attrs.merge!('user_id' => attrs['user']['id'])
+        attrs.delete 'user'
+      end
+      attrs
+    end
+
+    # Remove the auto-generated embedded User model to prevent recursion
+    def to_json
+      attrs = attributes
+      if attrs['user'] && attrs['user']['id'] == '$current'
+        attrs.delete 'user'
+      end
+      attrs.to_json
+    end
+
+    METHODS.each do |method|
+      class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def self.instance_#{method}(action)
+          instance_custom(:#{method}, action)
+        end
+      RUBY
+    end
+
+    def self.instance_custom(method, action)
+      #
+      # Add method calls to association: user.challenges.verify(id, attributes)
+      #
+      AssociationProxy.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        install_proxy_methods :association, :#{action}
+      RUBY
+      HasManyAssociation.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def #{action}(id, attributes={})
+          @klass.build({:id => id, :"\#{@parent.singularized_resource_name}_id" => @parent.id}).#{action}(attributes)
+        end
+      RUBY
+
+      #
+      # Add method call to instance: user.enable_mfa
+      #
+      class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def #{action}(params={})
+          self.class.#{method}("\#{request_path}/#{action.to_s.delete('!')}", params)
+        end
+      RUBY
+    end
+  end
+end