thisdata 0.1.6 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a460e8478eb4bca5802e86c76eba3017d42c5bfa
-  data.tar.gz: 58af31a7fab25be9d628aa612641da581ca03009
+  metadata.gz: c34091bf99a2ccce9303d2c1a3952c0c1b2a990e
+  data.tar.gz: abf7211329821a58bcecf4fb21045562ea24f350
 SHA512:
-  metadata.gz: 48adde7517313dcb521fbdd3c36386a5391a1b75366261b679c709c8ad5d8df62d4a3607f8908469ce910f4f317f307469b123c72257f591e7424333448b1198
-  data.tar.gz: 3bf8a38732da9679277ddb7770fe2ec17064985e8f37ce50d51d15a2e7d7e277dd28fa17118ca62c1f86fa6f95aee3a3d0b2a2961b9034c5ada1c281ba898f33
+  metadata.gz: 16a1310073c2fff9cd51ca8dc9c1b60b12e389cbd3b9906ef73156d8f74090fe890c06395a8e38de1b8cf6fab455fd12f8c82af7f8e7e4c42acfcddffd036cc6
+  data.tar.gz: 3e1b4fa3752eafd370c4f398d56e3232aa1b3aa06e28ae0280331d19f05b7673294aa04c3d5301c38dd146ae14d32d84506a36faa6fdf18aa6081daa511febd6

data/CHANGELOG

@@ -1,3 +1,15 @@
+# 0.2.0
+
+  - Add support for two new API endpoints, POST /verify and GET /events
+    https://github.com/thisdata/thisdata-ruby/issues/19
+    - help.thisdata.com/docs/apiv1verify
+    - help.thisdata.com/docs/v1getevents
+    - `ThisData::Event.all` returns a filterable, pageable, list of Events
+    - `ThisData.verify(...)` uses ThisData to determine how likely it is that
+       the person who is currently logged in has had their account compromised.
+    - Includes `thisdata_verify` method in the TrackRequest module, for easier
+      use within Rails apps
+
 # 0.1.6
 
   - Add support for setting the authenticated value when using `thisdata_track`.

data/README.md

@@ -52,20 +52,53 @@ to our app:
 
 ```ruby
 ThisData.track(
-  {
-    ip: request.remote_ip,
-    user_agent: request.user_agent,
-    verb: ThisData::Verbs::LOG_IN,
-    user: {
-      id: user.id.to_s,
-      name: user.name,
-      email: user.email,
-      mobile: user.mobile
-    }
+  ip: request.remote_ip,
+  user_agent: request.user_agent,
+  verb: ThisData::Verbs::LOG_IN,
+  user: {
+    id: user.id.to_s,
+    name: user.name,
+    email: user.email,
+    mobile: user.mobile
   }
 )
 ```
 
+#### Verifying a User
+
+```ruby
+response = ThisData.verify(
+  ip: request.remote_ip,
+  user_agent: request.user_agent,
+  user: {
+    id: user.id
+  }
+)
+
+if response["risk_level"] == ThisData::RISK_LEVEL_GREEN
+  # Let them log in
+else
+  # Challenge for a Two Factor Authentication code
+end
+```
+
+
+#### Getting Events (Audit Log)
+
+```ruby
+events = ThisData::Event.all(
+  verb: ThisData::Verbs::LOG_IN,
+  user_id: user.id,
+  limit: 25,
+  offset: 50
+)
+
+events.length
+=> 25
+
+events.first.user.id
+=> "112233"
+```
 
 ### Rails
 
@@ -132,6 +165,41 @@ Note: as with many sensitive operations, taking different actions when an
 account exists vs. when an account doesn't exist can lead to a information
 disclosure through timing attacks.
 
+
+#### Verifying
+
+Similar to the approach above, there is also a convenience method for verifying
+the current user.
+
+```ruby
+class SessionsController < ApplicationController
+  include ThisData::TrackRequest
+
+  def create
+    if User.authenticate(params[:email], params[:password])
+
+      # They used the right credentials, but does this login look unusual?
+      response = thisdata_verify
+
+      if response["risk_level"] == ThisData::RISK_LEVEL_GREEN
+        # The login looks OK. Do the things one usually does for a successful
+        # auth
+
+        # And track it
+        thisdata_track
+      else
+        # There is a chance the account could be breached.
+        # Confirm authentication by asking for a Two Factor Authentication code
+        # ....
+      end
+
+    else
+      # Their credentials are wrong...
+    end
+  end
+end
+```
+
 ### Will this break my app?
 
 We hope not! We encourage you to use the asynchronous API call where possible

data/Rakefile

@@ -1,10 +1,18 @@
 require "bundler/gem_tasks"
 require "rake/testtask"
 
-Rake::TestTask.new(:test) do |t|
+Rake::TestTask.new(:test_task) do |t|
   t.libs << "test"
   t.libs << "lib"
   t.test_files = FileList['test/**/*_test.rb']
 end
 
+task :test do
+  begin
+    Rake::Task['test_task'].invoke
+  rescue
+    # Supress the verbose failure output of TestTask
+  end
+end
+
 task :default => :test

data/lib/this_data.rb

@@ -2,14 +2,25 @@ require "httparty"
 require "logger"
 require "json"
 
+require "this_data/event"
 require "this_data/version"
 require "this_data/verbs"
 require "this_data/client"
 require "this_data/configuration"
 require "this_data/track_request"
+require "util/nested_struct"
 
 module ThisData
 
+  # API Endpoint Paths
+  EVENTS_ENDPOINT   = '/events'
+  VERIFY_ENDPOINT   = '/verify'
+
+  # Risk level constants, defined at http://help.thisdata.com/docs/apiv1verify#what-does-the-risk_level-mean
+  RISK_LEVEL_GREEN  = 'green'
+  RISK_LEVEL_ORANGE = 'orange'
+  RISK_LEVEL_RED    = 'red'
+
   class << self
 
     # Configuration Object (instance of ThisData::Configuration)
@@ -27,11 +38,15 @@ module ThisData
       configuration.defaults
     end
 
-    # Tracks an event. If `ThisData.configuration.async` is true, this action
-    # will be performed in a new Thread.
-    # Event must be a Hash
-    # When performed asynchronously, true is always returned.
-    # Otherwise an HTTPRequest is returned.
+    # Tracks a user initiated event which has occurred within your app, e.g.
+    # a user logging in.
+    #
+    # Performs asynchronously if ThisData.configuration.async is true.
+    #
+    # Parameters:
+    # - event       (Required: Hash) a Hash containing details about the event.
+    #               See http://help.thisdata.com/v1.0/docs/apiv1events for a
+    #               full & current list of available options.
     def track(event)
       if ThisData.configuration.async
         track_async(event)
@@ -40,6 +55,26 @@ module ThisData
       end
     end
 
+    # Verify asks ThisData's API "is this request really from this user?",
+    # and returns a response with a risk score.
+    #
+    # Note: this method does not perform error handling.
+    #
+    # Parameters:
+    # - params      (Required: Hash) a Hash containing details about the current
+    #               request & user.
+    #               See http://help.thisdata.com/docs/apiv1verify for a
+    #               full & current list of available options.
+    #
+    # Returns a Hash
+    def verify(params)
+      response = Client.new.post(
+        ThisData::VERIFY_ENDPOINT,
+        body: JSON.generate(params)
+      )
+      response.parsed_response
+    end
+
     # A helper method to track a log-in event. Validates that the minimum
     # required data is present.
     def track_login(ip: '', user: {}, user_agent: nil)

data/lib/this_data/client.rb

@@ -4,7 +4,7 @@ module ThisData
   class Client
 
     USER_AGENT = "ThisData Ruby v#{ThisData::VERSION}"
-    NO_API_KEY_MESSAGE  = "Oops: you've got no ThisData API Key configured, so we can't send events. Specify your ThisData API key using ThisData#setup (find yours at https://thisdata.com)"
+    NO_API_KEY_MESSAGE  = "Oops: you've got no ThisData API Key configured, so we can't talk to the API. Specify your ThisData API key using ThisData#setup (find yours at https://thisdata.com)"
 
     include HTTParty
 
@@ -15,33 +15,37 @@ module ThisData
       @headers = {
         "User-Agent" => USER_AGENT
       }
+      @default_query = {
+        api_key: ThisData.configuration.api_key
+      }
     end
 
     def require_api_key
       ThisData.configuration.api_key || print_api_key_warning
     end
 
-    # Tracks a user initiated event which has occurred within your app, e.g.
-    # a user logging in.
-    # See http://help.thisdata.com/v1.0/docs/apiv1events for more information.
-    # - event       (Required: Hash) the event, containing the following keys:
-    #  - verb       (Required: String) 'what' the user did, e.g. 'log-in'.
-    #                 See ThisData::Verbs for predefined options.
-    #  - ip         (Required: String) the IP address of the request
-    #  - user_agent (Optional: String) the user agent from the request
-    #  - user       (Required: Hash)
-    #   - id        (Required: String)  a unique identifier for this User
-    #   - email     (Optional*: String) the user's email address.
-    #   - mobile    (Optional*: String) a mobile phone number in E.164 format
-    #                 *email and/or mobile MUST be passed if you want ThisData
-    #                 to send 'Was This You?' notifications via email and/or SMS
-    #   - name      (Optional: String)  the user's name, used in notifications
-    #  - session   (Optional: Hash) details about the user's session
-    #   - td_cookie_expected (Optional: Boolean) whether you expect a JS cookie
-    #                         to be present
-    #   - td_cookie_id       (Optional: String) the value of the JS cookie
+    # A convenience method for tracking Events.
+    #
+    # Parameters:
+    # - event       (Required: Hash) a Hash containing details about the event.
+    #               See http://help.thisdata.com/v1.0/docs/apiv1events for a
+    #               full & current list of available options.
     def track(event)
-      post_event(event)
+      post(ThisData::EVENTS_ENDPOINT, body: JSON.generate(event))
+    end
+
+    # Perform a GET request against the ThisData API, with the API key
+    # prepopulated
+    def get(path, query: {})
+      query = @default_query.merge(query)
+      self.class.get(path, query: query, headers: @headers)
+    end
+
+    # Perform a POST request against the ThisData API, with the API key
+    # prepopulated
+    def post(path, query: {}, body: {})
+      query = @default_query.merge(query)
+      self.class.post(path, query: query, headers: @headers, body: body)
     end
 
     private
@@ -50,11 +54,6 @@ module ThisData
         ThisData.configuration.version
       end
 
-      def post_event(payload_hash)
-        path_with_key = "/events?api_key=#{ThisData.configuration.api_key}"
-        self.class.post(path_with_key, headers: @headers, body: JSON.generate(payload_hash))
-      end
-
       def print_api_key_warning
         $stderr.puts(NO_API_KEY_MESSAGE)
       end

data/lib/this_data/event.rb

@@ -0,0 +1,21 @@
+# A wrapper for the GET /events API
+#
+module ThisData
+  class Event
+
+    # Fetch an array of Events from the ThisData API
+    # Available options can be found at
+    #   http://help.thisdata.com/docs/v1getevents
+    #
+    # Returns: Array of OpenStruct Event objects
+    def self.all(options={})
+      response = ThisData::Client.new.get(ThisData::EVENTS_ENDPOINT, query: options)
+      # Use NestedStruct to turn this Array of deep Hashes into an array of
+      # OpenStructs
+      response.parsed_response["results"].collect do |event_hash|
+        NestedStruct.new(event_hash)
+      end
+    end
+
+  end
+end

data/lib/this_data/track_request.rb

@@ -2,12 +2,15 @@
 # track method which looks at the request and current_user variables to
 # generate an event.
 #
+# This module will also provide access to the verify API.
+#
 # If you include this in a non-ActionController instance, you must respond to
 # `request` and `ThisData.configuration.user_method`
 #
 module ThisData
   module TrackRequest
     class ThisDataTrackError < StandardError; end
+    class NoUserSpecifiedError < ArgumentError; end
 
     # Will pull request and user details from the controller, and send an event
     # to ThisData.
@@ -61,6 +64,51 @@ module ThisData
       false
     end
 
+    # Will pull request and user details from the controller, and use
+    # ThisData's verify API to determine how likely it is that the person who
+    # is currently logged in has had their account compromised.
+    #
+    # Arguments:
+    #   user: (Object, Required). If you want to override the user record
+    #     that we would usually fetch, you can pass it here.
+    #     Unless a user is specified here we'll attempt to get the user record
+    #       as specified in the ThisData gem configuration. This defaults to
+    #       `current_user`.
+    #     The object must respond to at least
+    #       `ThisData.configuration.user_id_method`, which defaults to `id`.
+    #
+    #
+    # Returns a Hash with risk information.
+    # See http://help.thisdata.com/docs/apiv1verify for details
+    def thisdata_verify(user: nil)
+      # Fetch the user unless it's been overridden
+      if user.nil?
+        user = send(ThisData.configuration.user_method)
+      end
+      # If it's still nil, raise an error
+      raise NoUserSpecifiedError, "A user must be provided for verification" if user.nil?
+
+      # Get a Hash of details for the user
+      user_details = user_details(user)
+
+      event = {
+        ip:         request.remote_ip,
+        user_agent: request.user_agent,
+        user:       user_details,
+        session: {
+          td_cookie_expected: ThisData.configuration.expect_js_cookie,
+          td_cookie_id:       td_cookie_value,
+        }
+      }
+
+      ThisData.verify(event)
+    rescue => e
+      ThisData.error "Could not verify current user:"
+      ThisData.error e
+      ThisData.error e.backtrace[0..5].join("\n")
+      nil
+    end
+
     private
 
       # Will return a Hash of details for a user using the methods specified

data/lib/this_data/version.rb

@@ -1,3 +1,3 @@
 module ThisData
-  VERSION = "0.1.6"
+  VERSION = "0.2.0"
 end

data/lib/util/nested_struct.rb

@@ -0,0 +1,27 @@
+# Public: turns JSON into a deeply nested OpenStruct. Will find Hashes
+# with Hashes and within Arrays.
+class NestedStruct < OpenStruct
+  def initialize(json=Hash.new)
+    @table = {}
+
+    json.each do |key, value|
+      @table[key.to_sym] =  if value.is_a? Hash
+                              self.class.new(value)
+                            elsif value.is_a? Array
+                              # Turn all the jsons in the array into DeepStructs
+                              value.collect do |i|
+                                i.is_a?(Hash) ? self.class.new(i) : i
+                              end
+                            else
+                              value
+                            end
+
+      new_ostruct_member(key)
+    end
+  end
+
+  def as_json(*args)
+    json = super
+    json["table"]
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: thisdata
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.2.0
 platform: ruby
 authors:
 - ThisData Ltd
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-10-25 00:00:00.000000000 Z
+date: 2016-10-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
@@ -131,9 +131,11 @@ files:
 - lib/this_data.rb
 - lib/this_data/client.rb
 - lib/this_data/configuration.rb
+- lib/this_data/event.rb
 - lib/this_data/track_request.rb
 - lib/this_data/verbs.rb
 - lib/this_data/version.rb
+- lib/util/nested_struct.rb
 - thisdata.gemspec
 homepage: https://github.com/thisdata/thisdata-ruby
 licenses: