userbin 1.5.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bb87601eef49b0f5d845aadecd86b36c2aa2a5a2
-  data.tar.gz: d35d0620253e7702afbdddd95b1a94c586018b34
+  metadata.gz: a838f3a5b083d7baf4689189e9937242ee900f35
+  data.tar.gz: 43613aa2135886c221fd39fc2753cd9aed44e8fb
 SHA512:
-  metadata.gz: 7a7d1ad419f59374579ecff1a8d3038671da449fc9b7dd4a637ba8db300c711fe07394d6fc9d842e50a935c0055acc2c375d5a5f53f8610588b37371d581feb3
-  data.tar.gz: 2cda728dfc00d9c03288037a5b6039ff04b40d0d5a150994d4a329a7e34a40f7feaf844b8ec41f4540346548a10b04d69d58674262cc486a3ee7c7169104863f
+  metadata.gz: 64882804d2c11cc349d85e92fcbde230106bdb40e75099f94cf33b67ad47904ec587094dc98b18b656b326230e981c535248ed7256f1c1af10c903911efd7e0e
+  data.tar.gz: 89dcec756ea9f6856894071b1eae52f8017e48db7e6efb8484115d76cdf6bcd5e9eb0a12873137710a34e0fef44f242de67b702a4e0cfbf1cc760d1fb6029c31

data/README.md

@@ -3,14 +3,16 @@
 [![Build Status](https://travis-ci.org/userbin/userbin-ruby.png)](https://travis-ci.org/userbin/userbin-ruby)
 [![Gem Version](https://badge.fury.io/rb/userbin.png)](http://badge.fury.io/rb/userbin)
 [![Dependency Status](https://gemnasium.com/userbin/userbin-ruby.png)](https://gemnasium.com/userbin/userbin-ruby)
+[![Coverage Status](https://coveralls.io/repos/userbin/userbin-ruby/badge.png)](https://coveralls.io/r/userbin/userbin-ruby)
 
+**[Userbin](https://userbin.com) adds an additional security layer to your application by providing account takeover protection and two-factor authentication in a white-label package**
 
-[Userbin](https://userbin.com) provides an additional security layer to your application by adding user activity monitoring, real-time threat protection and two-factor authentication in a white-label package. Your users **do not** need to be signed up or registered for Userbin before using the service and there's no need for them to download any proprietary apps. Also, Userbin requires **no modification of your current database schema** as it uses your local user IDs.
+Your users **do not** need to be signed up or registered for Userbin before using the service and there's no need for them to download any proprietary apps. Also, Userbin requires **no modification of your current database schema** as it uses your local user IDs.
 
 ## Table of Contents
 
+- [Installation](#installation)
 - [Getting Started](#getting-started)
-- [Setup User Monitoring](#setup-user-monitoring)
 - [Active Sessions](#active-sessions)
 - [Security Events](#security-events)
 - [Two-factor Authentication](#two-factor-authentication)
@@ -22,7 +24,7 @@
   - [Backup Codes](#backup-codes)
   - [List Pairings](#list-pairings)
 
-## Getting Started
+## Installation
 
 Add the `userbin` gem to your `Gemfile`
 
@@ -30,22 +32,17 @@ Add the `userbin` gem to your `Gemfile`
 gem "userbin"
 ```
 
-Install the gem
-
-```bash
-bundle install
-```
-
 Load and configure the library with your Userbin API secret in an initializer or similar.
 
 ```ruby
-require 'userbin'
 Userbin.api_secret = "YOUR_API_SECRET"
 ```
 
-## Setup User Monitoring
+## Getting started
 
-You should call `login` as soon as the user has logged in to your application. Pass a unique user identifier, and an *optional* hash of user properties which are used when searching for users in your dashboard. This will create a [Session](https://api.userbin.com/#POST--version-users--user_id-sessions---format-) resource and return a corresponding [session token](https://api.userbin.com/#session-tokens) which is stored in the Userbin client.
+### 1. Logging in and out
+
+You should call `login` as soon as the user has logged in to your application to start the Userbin session. Pass a unique user identifier, and an *optional* hash of user properties which are used when searching for users in your dashboard.
 
 ```ruby
 def your_after_login_hook
@@ -53,9 +50,7 @@ def your_after_login_hook
 end
 ```
 
-Once logged in to Userbin, all requests made through the Userbin instance are on behalf of the currently logged in user.
-
-When a user logs out from within your application, call `logout` to remove the session from the user's [active sessions](#active-sessions).
+When a user logs out from within your application, call `logout` to tell Userbin to remove the session from the user's [active sessions](#active-sessions).
 
 ```ruby
 def your_after_logout_hook
@@ -63,32 +58,46 @@ def your_after_logout_hook
 end
 ```
 
-The real magic happens when you use `authorize!` to control access to only those logged in to Userbin, which is probably everywhere you allow authenticated users. This makes sure that the session token created by `login` is valid and up to date, and raises `UserUnauthorizedError` if it's not. Reasons for this include being automatically locked down due to suspicious behavior or the session being remotely revoked.
+**Check that it works** by logging in to your application and watch your user appear in the [Userbin dashboard](https://dashboard.userbin.com).
 
-**Note:** The session token will be [refreshed](https://api.userbin.com/#monitoring) every 5 minutes. This means that even though a session becomes invalid, no exceptions will be generated until the next refresh. E.g. revoking a session from the dashboard might take up to 5 minutes to happen.
+### 2. Protecting routes
 
-```ruby
-class AccountController < ApplicationController
-  before_filter :authenticate_user! # from e.g. Devise
-  before_filter { userbin.authorize! }
-  # ...
-end
-```
+Call `authorize!` just before your `current_user` is being initialized. Usually you'll want to override your normal authentication filter, e.g. `authenticate_user!` if you're using Devise.
 
-You should catch these errors in one place and log out the authenticated user.
+- `UserUnauthorizedError` will be raised if `login` has not yet been called, or if the session is no longer valid.
+- `ChallengeRequiredError` will be raised when the user has enabled two-factor authentication and is logging in from an untrusted device.
 
 ```ruby
 class ApplicationController < ActionController::Base
-  rescue_from Userbin::UserUnauthorizedError do |e|
-    sign_out # log out your user locally
-    redirect_to root_url
+  rescue_from Userbin::UserUnauthorizedError, with: :user_unauthorized
+  rescue_from Userbin::ChallengeRequiredError, with: :challenge_required
+
+  # IMPLEMENT: Override the authentication method from your framework
+  def authenticate_user!
+    userbin.authorize!
+    super
+  end
+
+  # IMPLEMENT: Log out your user locally
+  def user_unauthorized
+    sign_out
+    redirect_to root_path
+  end
+
+  # IMPLEMENT: Redirect to two-factor authentication login
+  def challenge_required
+    redirect_to show_challenge_path
   end
 end
 ```
 
+Then use the overridden filter in your protected routes as you normally would, and all your critical flows will be protected from account takeover.
 
-
-**That's it!** Now log in to your application and watch your user appear in the [Userbin dashboard](https://dashboard.userbin.com).
+```ruby
+class AccountController < ApplicationController
+  before_filter :authenticate_user!
+end
+```
 
 ## Active Sessions
 

data/lib/userbin.rb

@@ -12,13 +12,13 @@ require 'userbin/version'
 require 'userbin/configuration'
 require 'userbin/client'
 require 'userbin/errors'
-require 'userbin/session_store'
-require 'userbin/trusted_token_store'
+require 'userbin/token_store'
 require 'userbin/jwt'
 require 'userbin/utils'
 require 'userbin/request'
 require 'userbin/session_token'
 
+require 'userbin/support/cookie_store'
 require 'userbin/support/rails' if defined?(Rails::Railtie)
 if defined?(Sinatra::Base)
   if defined?(Padrino)
@@ -34,6 +34,7 @@ end
 
 # These need to be required after setting up Her
 require 'userbin/models/model'
+require 'userbin/models/account'
 require 'userbin/models/event'
 require 'userbin/models/challenge'
 require 'userbin/models/context'

data/lib/userbin/client.rb

@@ -17,21 +17,13 @@ module Userbin
       :backup_codes, :generate_backup_codes, :trusted_devices,
       :enable_mfa!, :disable_mfa!
 
-    def initialize(request, cookies, opts = {})
+    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[:userbin] = self
 
-      # By default the session token is persisted in the Rack store, which may
-      # in turn point to any source. This option give you an option to
-      # use any store, such as Redis or Memcached to store your Userbin tokens.
-      if opts[:session_store]
-        @session_store = opts[:session_store]
-      else
-        @session_store = Userbin::SessionStore::Rack.new(request.session)
-      end
-
-      @trusted_token_store = Userbin::TrustedTokenStore::Rack.new(cookies)
+      cookies = Userbin::CookieStore.new(request, response)
+      @store = Userbin::TokenStore.new(cookies)
 
       @request_context = {
         ip: request.ip,
@@ -39,58 +31,23 @@ module Userbin
       }
     end
 
-    def session_token=(value)
-      if value && value != @session_store.read
-        @session_store.write(value)
-      elsif !value
-        @session_store.destroy
-      end
-    end
-
     def session_token
-      token = @session_store.read
-      Userbin::SessionToken.new(token) if token
-    end
-
-    def trusted_device_token=(value)
-      if value && value != @trusted_token_store.read
-        @trusted_token_store.write(value)
-      elsif !value
-        @trusted_token_store.destroy
-      end
-    end
-
-    def trusted_device_token
-      @trusted_token_store.read
+      @store.session_token
     end
 
-    def identify(user_id)
-      # The user identifier is used in API paths so it needs to be cleaned
-      user_id = URI.encode(user_id.to_s)
-
-      @session_store.user_id = user_id
-      @trusted_token_store.user_id = user_id
-    end
-
-    def authorize
-      return unless session_token
-
-      if session_token.expired?
-        Userbin::Monitoring.heartbeat
-      end
-    end
-
-    def authorized?
-      !!session_token
+    def session_token=(session_token)
+      @store.session_token = session_token
     end
 
     def authorize!
-      unless session_token
+      unless @store.session_token
         raise Userbin::UserUnauthorizedError,
           'Need to call login before authorize'
       end
 
-      authorize
+      if @store.session_token.expired?
+        Userbin::Monitoring.heartbeat
+      end
 
       if mfa_in_progress?
         logout
@@ -103,63 +60,66 @@ module Userbin
       end
     end
 
+    def authorized?
+      !!@store.session_token
+    end
+
     def login(user_id, user_attrs = {})
       # Clear the session token if any
-      self.session_token = nil
-
-      identify(user_id)
+      @store.session_token = nil
 
-      user = Userbin::User.new(@session_store.user_id)
+      user = Userbin::User.new(user_id.to_s)
       session = user.sessions.create(
-        user: user_attrs, trusted_device_token: self.trusted_device_token)
+        user: user_attrs, trusted_device_token: @store.trusted_device_token)
 
       # Set the session token for use in all subsequent requests
-      self.session_token = session.token
+      @store.session_token = session.token
 
       session
     end
 
-    def trust_device(attrs = {})
-      trusted_device = trusted_devices.create(attrs)
-
-      # Set the session token for use in all subsequent requests
-      self.trusted_device_token = trusted_device.token
-    end
-
-    # This method ends the current monitoring session. It should be called
-    # whenever the user logs out from your system.
-    #
     def logout
-      return unless session_token
+      return unless @store.session_token
 
       # Destroy the current session specified in the session token
       begin
         sessions.destroy('$current')
-      rescue Userbin::Error # ignored
+      rescue Userbin::ApiError # ignored
       end
 
       # Clear the session token
-      self.session_token = nil
+      @store.session_token = nil
+    end
+
+    def trust_device(attrs = {})
+      unless @store.session_token
+        raise Userbin::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?
-      session_token ? session_token.mfa_enabled? : false
+      @store.session_token ? @store.session_token.mfa_enabled? : false
     end
 
     def device_trusted?
-      session_token ? session_token.device_trusted? : false
+      @store.session_token ? @store.session_token.device_trusted? : false
     end
 
     def mfa_in_progress?
-      session_token ? session_token.has_challenge? : false
+      @store.session_token ? @store.session_token.mfa_in_progress? : false
     end
 
     def mfa_required?
-      session_token ? session_token.needs_challenge? : false
+      @store.session_token ? @store.session_token.mfa_required? : false
     end
 
     def has_default_pairing?
-      session_token ? session_token.has_default_pairing? : false
+      @store.session_token ? @store.session_token.has_default_pairing? : false
     end
   end
 end

data/lib/userbin/models/account.rb

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

data/lib/userbin/models/context.rb

@@ -2,7 +2,7 @@ module Userbin
   class Context < Model
     def user_agent
       if attributes['user_agent']
-        Userbin::Location.new(attributes['user_agent'])
+        Userbin::UserAgent.new(attributes['user_agent'])
       end
     end
 

data/lib/userbin/models/pairing.rb

@@ -4,5 +4,8 @@ module Userbin
     instance_post :verify
     instance_post :set_default!
     belongs_to :user
+    has_one :config
   end
+
+  class Config < Model; end
 end

data/lib/userbin/session_token.rb

@@ -16,24 +16,24 @@ module Userbin
       @jwt.expired?
     end
 
-    def needs_challenge?
-      @jwt.payload['vfy'] > 0
+    def device_trusted?
+      @jwt.payload['tru'] == 1
     end
 
-    def has_challenge?
-      @jwt.payload['chg'] == 1
+    def has_default_pairing?
+      @jwt.payload['dpr'] > 0
     end
 
     def mfa_enabled?
       @jwt.payload['mfa'] == 1
     end
 
-    def device_trusted?
-      @jwt.payload['tru'] == 1
+    def mfa_in_progress?
+      @jwt.payload['chg'] == 1
     end
 
-    def has_default_pairing?
-      @jwt.payload['dpr'] == 1
+    def mfa_required?
+      @jwt.payload['vfy'] > 0
     end
   end
 end

data/lib/userbin/support/cookie_store.rb

@@ -10,7 +10,14 @@ module Userbin
     end
 
     def []=(key, value)
-      @response.set_cookie key, value
+      @request.cookies[key] = value
+      if value
+        @response.set_cookie(key, value: value,
+                                  expires: Time.now + (365 * 24 * 60 * 60),
+                                  path: '/')
+      else
+        @response.delete_cookie(key)
+      end
     end
   end
 end

data/lib/userbin/support/padrino.rb

@@ -5,8 +5,7 @@ module Padrino
     module Userbin
       module Helpers
         def userbin
-          store = ::Userbin::CookieStore.new(request, response)
-          @userbin ||= ::Userbin::Client.new(request, store)
+          @userbin ||= ::Userbin::Client.new(request, response)
         end
       end
 

data/lib/userbin/support/rails.rb

@@ -1,7 +1,7 @@
 module Userbin
   module UserbinClient
     def userbin
-      @userbin ||= Userbin::Client.new(request, cookies)
+      @userbin ||= Userbin::Client.new(request, response)
     end
   end
 

data/lib/userbin/support/sinatra.rb

@@ -4,8 +4,7 @@ module Sinatra
   module Userbin
     module Helpers
       def userbin
-        store = ::Userbin::CookieStore.new(request, response)
-        @userbin ||= ::Userbin::Client.new(request, store)
+        @userbin ||= ::Userbin::Client.new(request, response)
       end
     end
 

data/lib/userbin/token_store.rb

@@ -0,0 +1,30 @@
+module Userbin
+  class TokenStore
+    def initialize(cookies)
+      @cookies = cookies
+    end
+
+    def session_token
+      token = @cookies['_ubs']
+      Userbin::SessionToken.new(token) if token
+    end
+
+    def session_token=(value)
+      @cookies['_ubs'] = value
+
+      if value && value != @cookies['_ubs']
+        @cookies['_ubs']
+      elsif !value
+        @cookies['_ubs'] = nil
+      end
+    end
+
+    def trusted_device_token
+      @cookies['_ubt']
+    end
+
+    def trusted_device_token=(value)
+      @cookies['_ubt'] = value
+    end
+  end
+end

data/lib/userbin/version.rb

@@ -1,3 +1,3 @@
 module Userbin
-  VERSION = "1.5.0"
+  VERSION = "1.6.0"
 end

data/spec/models/user_spec.rb

@@ -28,16 +28,4 @@ describe 'Userbin::User' do
       user.save
     end
   end
-
-  it 'imports users' do
-    VCR.use_cassette('user_import') do
-      users = Userbin::User.import(
-        users: [
-          { email: '10@example.com', username: '10' },
-          { email: '20@example.com', username: '20' }
-        ]
-      )
-      users.count.should == 2
-    end
-  end
 end

data/spec/spec_helper.rb

@@ -1,9 +1,20 @@
 require 'rubygems'
 require 'bundler/setup'
 require 'rack'
-require 'userbin'
 require 'vcr'
 require 'webmock/rspec'
+require 'simplecov'
+require 'coveralls'
+
+SimpleCov.formatter = SimpleCov::Formatter::MultiFormatter[
+  SimpleCov::Formatter::HTMLFormatter,
+  Coveralls::SimpleCov::Formatter
+]
+SimpleCov.start do
+  add_filter 'spec'
+end
+
+require 'userbin'
 
 VCR.configure do |config|
   config.cassette_library_dir = 'spec/fixtures/vcr_cassettes'

data/spec/utils_spec.rb

@@ -1,20 +1,24 @@
 require 'spec_helper'
 
-class MemoryStore < Userbin::SessionStore
+class MemoryStore < Userbin::TokenStore
   def initialize
     @value = nil
   end
 
-  def read
-    @value
+  def session_token
+    @value['_ubs']
   end
 
-  def write(value)
-    @value = value
+  def session_token=(value)
+    @value['_ubs'] = value
   end
 
-  def destroy
-    @value = nil
+  def trusted_device_token
+    @value['_ubt']
+  end
+
+  def trusted_device_token=(value)
+    @value['_ubt'] = value
   end
 end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: userbin
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.6.0
 platform: ruby
 authors:
 - Johan
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-11-07 00:00:00.000000000 Z
+date: 2014-11-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: her
@@ -164,6 +164,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: coveralls
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.7.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.7.2
 description: Secure your application with multi-factor authentication, user activity
   monitoring, and real-time threat protection.
 email: johan@userbin.com
@@ -178,6 +192,7 @@ files:
 - lib/userbin/errors.rb
 - lib/userbin/ext/her.rb
 - lib/userbin/jwt.rb
+- lib/userbin/models/account.rb
 - lib/userbin/models/backup_codes.rb
 - lib/userbin/models/challenge.rb
 - lib/userbin/models/context.rb
@@ -195,7 +210,7 @@ files:
 - lib/userbin/support/padrino.rb
 - lib/userbin/support/rails.rb
 - lib/userbin/support/sinatra.rb
-- lib/userbin/trusted_token_store.rb
+- lib/userbin/token_store.rb
 - lib/userbin/utils.rb
 - lib/userbin/version.rb
 - spec/fixtures/vcr_cassettes/challenge_create.yml

data/lib/userbin/trusted_token_store.rb

@@ -1,35 +0,0 @@
-module Userbin
-  class TrustedTokenStore
-    class Rack < TrustedTokenStore
-      def initialize(cookies)
-        @cookies = cookies
-      end
-
-      def user_id
-        @cookies['userbin.user_id']
-      end
-
-      def user_id=(value)
-        @cookies['userbin.user_id'] = value
-      end
-
-      def read
-        @cookies[key]
-      end
-
-      def write(value)
-        @cookies[key] = value
-      end
-
-      def destroy
-        @cookies.delete(key)
-      end
-
-      private
-
-      def key
-        "userbin.trusted_device_token.#{user_id}"
-      end
-    end
-  end
-end