trust_me 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b27c6d276f92c43d1c327c45d95b3508639ef0fa
+  data.tar.gz: be8f2eb7a3910b92adeb1fbb3fab9403776357b6
+SHA512:
+  metadata.gz: 08eb5e47d9fd3b79c0b644a018250fa46d6bd6e4070ce14b680e75a0b2217b714f09fe013104adab143b44e94e15813e5fcac38937e7883241731a66764aef8e
+  data.tar.gz: b02fa2bb5f7572097f3ce55a75daa365422b634c6a8fedae4508833a40e25b5962efa1d3a3dca4617669e179bc6eb244a4349d02abc5852665c4f48fe39c8f89

data/README.markdown

@@ -0,0 +1,82 @@
+# TrustMe
+
+This library is a wrapper for the TeleSign REST API. Currently the Verify Call
+and Verify SMS web services are supported. The Verify Call web service sends a
+verification code to a user in a voice message with a phone call. The Verify
+SMS web service sends a verification code to a user in a text message via SMS.
+The user enters this code in a web application to verify their identity.
+
+See also:
+  - <http://docs.telesign.com/rest/content/verify-call.html>
+  - <http://docs.telesign.com/rest/content/verify-sms.html>
+
+## Configuration
+
+Set global credentials:
+
+```ruby
+TrustMe.config do |c|
+  c.customer_id = "1234"
+  c.secret_key  = "secret"
+end
+```
+
+If you need different credentials per-instance:
+
+```ruby
+trust_me = TrustMe.new "5678", "secret2"
+```
+
+## Usage
+
+Send a verification call to a customer and save the verification code:
+
+```ruby
+class VerifyController < ApplicationController
+  def create
+    trust_me = TrustMe.new
+    call     = trust_me.send_verification_call! current_user.phone
+
+    current_user.update_attribute! :verification_code, call[:code]
+  end
+end
+```
+
+Or send a verification SMS to a customer:
+
+```ruby
+class VerifyController < ApplicationController
+  def create
+    trust_me = TrustMe.new
+    sms     = trust_me.send_verification_sms! current_user.phone
+
+    current_user.update_attribute! :verification_code, sms[:code]
+  end
+end
+```
+
+The customer verifies the code:
+
+```ruby
+class VerifyController < ApplicationController
+  def update
+    if params[:code] == current_user.verification_code
+      current_user.set_verified!
+    end
+  end
+end
+```
+
+## Note on Patches/Pull Requests
+
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so we don't break it in a future version
+  unintentionally.
+* Commit, do not bump version. (If you want to have your own version, that is
+  fine but bump version in a commit by itself we can ignore when we pull).
+* Send us a pull request. Bonus points for topic branches.
+
+## Copyright
+
+Copyright (c) 2014 WWWH, LLC. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,12 @@
+$:.unshift "lib"
+
+begin
+  require "rspec/core/rake_task"
+  require "bundler/gem_tasks"
+  require "rake-tomdoc"
+rescue LoadError
+  abort "Please run `bundle install`"
+end
+
+RSpec::Core::RakeTask.new :spec
+task :default => :spec

data/lib/trust_me/version.rb

@@ -0,0 +1,3 @@
+class TrustMe
+  VERSION = Version = "0.1.1"
+end

data/lib/trust_me.rb

@@ -0,0 +1,220 @@
+require "trust_me/version"
+require "json"
+require "uri"
+require "net/http"
+require "base64"
+require "openssl"
+
+class TrustMe
+  # Public: URL to the TeleSign REST API.
+  #
+  # Returns a URI::HTTPS instance.
+  API_URL = URI.parse("https://rest.telesign.com")
+
+  # Public: Gets/sets configuration info to connect to the TeleSign API.
+  #
+  # Example
+  #
+  #   TrustMe.config do |c|
+  #     c.customer_id = "1234"
+  #     c.secret_key  = "secret"
+  #   end
+  #
+  # Returns a Struct.
+  def self.config
+    @config ||= Struct.new(:customer_id, :secret_key).new
+    yield @config if block_given?
+    @config
+  end
+
+  # Public: Creates a new TrustMe instance.
+  #
+  # customer_id - TeleSign customer ID
+  # secret_key  - TeleSign secret key
+  #
+  # Raises RuntimeError if credentials aren't setup.
+  #
+  # Returns nothing.
+  def initialize(customer_id = nil, secret_key = nil)
+    @customer_id = customer_id || self.class.config.customer_id
+    @secret_key  = secret_key  || self.class.config.secret_key
+
+    unless @customer_id && @secret_key
+      raise "You must supply API credentials. Try `TrustMe.new " \
+        '"customer_id", "secret_key"` or `TrustMe.config`'
+    end
+  end
+
+  # Public: Send a verification call to the given phone number.
+  #
+  # number  - The phone number to call
+  # options - Hash of options
+  #           :verify_code - Code to send the user, if not supplied a 5-digit
+  #                          code is automatically generated
+  #           :language    - Language to use on the call, defaults to "en-US"
+  #           :ucid        - Use case ID, defaults to "TRVF"
+  #                          (Transaction Verification)
+  #
+  # See: http://docs.telesign.com/rest/content/verify-call.html#index-5
+  #
+  # Returns a Hash.
+  def send_verification_call!(number, options = {})
+    verify_code = options.fetch(:verify_code, generate_code)
+
+    output = api_request(
+      :resource => "/v1/verify/call",
+      :params   => encode_hash(
+        :ucid         => options.fetch(:ucid, "TRVF"),
+        :phone_number => number,
+        :language     => options.fetch(:language, "en-US"),
+        :verify_code  => verify_code
+      )
+    )
+
+    { :data => output, :code => verify_code }
+  end
+
+  # Public: Send a verification SMS to the given phone number.
+  #
+  # number  - The phone number to message
+  # options - Hash of options
+  #           :verify_code - Code to send the user, if not supplied a 5-digit
+  #                          code is automatically generated
+  #           :language    - Language to use on the call, defaults to "en-US"
+  #           :ucid        - Use case ID, defaults to "TRVF"
+  #                          (Transaction Verification)
+  #           :template    - Optional text template, must include "$$CODE$$"
+  #
+  # See: http://docs.telesign.com/rest/content/verify-sms.html#index-5
+  #
+  # Returns a Hash.
+  def send_verification_sms!(number, options = {})
+    verify_code = options.fetch(:verify_code, generate_code)
+
+    output = api_request(
+      :resource => "/v1/verify/sms",
+      :params   => encode_hash(
+        :ucid         => options.fetch(:ucid, "TRVF"),
+        :phone_number => number,
+        :language     => options.fetch(:language, "en-US"),
+        :verify_code  => verify_code,
+        :template     => options[:template]
+      )
+    )
+
+    { :data => output, :code => verify_code }
+  end
+
+  # Public: Generates headers used to authenticate with the API.
+  #
+  # options - Hash of options
+  #           :resource - API resource (required)
+  #           :params   - Params to send (required)
+  #
+  # Raises KeyError if any required keys are missing.
+  #
+  # See: http://docs.telesign.com/rest/content/rest-auth.html
+  #
+  # Returns a Hash.
+  def generate_headers(options = {})
+    content_type = "application/x-www-form-urlencoded"
+    date         = Time.now.gmtime.strftime("%a, %d %b %Y %H:%M:%S GMT")
+    nonce        = `uuidgen`.chomp
+
+    content = [
+      "POST",
+      content_type,
+      "", # Blank spot for "Date" header, which is overridden by x-ts-date
+      "x-ts-auth-method:HMAC-SHA256",
+      "x-ts-date:#{date}",
+      "x-ts-nonce:#{nonce}",
+      options.fetch(:params),
+      options.fetch(:resource)
+    ].join("\n")
+
+    hash   = OpenSSL::Digest::SHA256.new rand.to_s
+    key    = Base64.decode64(@secret_key)
+    digest = OpenSSL::HMAC.digest(hash, key, content)
+    auth   = Base64.encode64(digest)
+
+    {
+      "Authorization"    => "TSA #{@customer_id}:#{auth}",
+      "Content-Type"     => content_type,
+      "x-ts-date"        => date,
+      "x-ts-auth-method" => "HMAC-SHA256",
+      "x-ts-nonce"       => nonce
+    }
+  end
+
+  private
+
+  # Private: Generates a random 5 digit code.
+  #
+  # Returns a String.
+  def generate_code
+    (0..4).map { (48 + rand(10)).chr }.join
+  end
+
+  # Private: URL-encodes a hash to a string for submission via HTTP.
+  #
+  # hash - A Hash to encode
+  #
+  # Returns a String.
+  def encode_hash(hash)
+    URI.encode_www_form hash
+  end
+
+  # Private: CA certificate file to verify SSL connection with `API_URL`
+  #
+  # Returns an OpenSSL::X509::Certificate instance.
+  def cacert
+    @cacert ||= OpenSSL::X509::Certificate.new \
+      File.read(File.expand_path("../../vendor/cacert.pem", __FILE__))
+  end
+
+  # Private: Parse the given JSON string.
+  #
+  # string - Raw JSON string
+  #
+  # Returns a Hash.
+  def parse_json(string)
+    JSON.parse string
+  end
+
+  # Private: Submits an API request via POST.
+  #
+  # options - Hash of options
+  #           :resource - API resource (required)
+  #           :params   - Params to send (required)
+  #
+  # Raises KeyError if any required keys are missing.
+  # Raises a Net::HTTP exception if the request is not successful.
+  #
+  # Returns a Hash.
+  def api_request(options = {})
+    http         = Net::HTTP.new(API_URL.host, API_URL.port)
+    http.use_ssl = API_URL.scheme == "https"
+
+    if http.use_ssl?
+      http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+      http.cert_store  = OpenSSL::X509::Store.new
+      http.cert_store.add_cert cacert
+    end
+
+    headers  = generate_headers(options)
+    body     = options.fetch(:params)
+    resource = options.fetch(:resource)
+    response = http.request_post resource, body, headers
+    output   = parse_json(response.body)
+
+    if response.is_a? Net::HTTPSuccess
+      output
+    else
+      raise response.error_type.new(
+        "#{response.code} #{response.message.dump}\n" \
+        "Response body: #{output.inspect}",
+        response
+      )
+    end
+  end
+end

data/spec/fixtures/verify-call-success.json

@@ -0,0 +1,19 @@
+{
+   "reference_id" : "ABCDEF0123456789ABCDEF0123456789",
+   "resource_uri" : "/v1/verify/ABCDEF0123456789ABCDEF0123456789",
+   "sub_resource" : "call",
+   "errors": [],
+   "status" : {
+      "updated_on" : "2012-04-17T22:26:43.784963Z",
+      "code" : 103,
+      "description" : "Call in progress"
+   },
+   "call_forwarding": {
+      "mode": "FLAG",
+      "status": "FORWARDED"
+   },
+   "verify" : {
+      "code_state" : "UNKNOWN",
+      "code_entered" : ""
+   }
+}

data/spec/fixtures/verify-sms-success.json

@@ -0,0 +1,15 @@
+{
+   "reference_id" : "ABCDEF0123456789ABCDEF0123456789",
+   "resource_uri" : "/v1/verify/ABCDEF0123456789ABCDEF0123456789",
+   "sub_resource" : "sms",
+   "errors": [],
+   "status" : {
+      "updated_on" : "2012-04-17T22:26:43.784963Z",
+      "code" : 290,
+      "description" : "Message in progress"
+   },
+   "verify" : {
+      "code_state" : "UNKNOWN",
+      "code_entered" : ""
+   }
+}

data/spec/spec_helper.rb

@@ -0,0 +1,14 @@
+require "rspec"
+require "webmock/rspec"
+require "trust_me"
+
+RSpec.configure do |config|
+  config.color     = true
+  config.order     = "rand"
+  config.formatter = "progress"
+end
+
+TrustMe.config do |c|
+  c.customer_id = "custid"
+  c.secret_key  = Base64.encode64("secret")
+end

data/spec/trust_me_spec.rb

@@ -0,0 +1,141 @@
+require "spec_helper"
+
+describe TrustMe do
+  let :trust_me do
+    TrustMe.new
+  end
+
+  let :now do
+    Time.utc 2014, 11, 13, 12, 20, 00
+  end
+
+  let :now_rfc1123 do
+    "Thu, 13 Nov 2014 12:20:00 GMT"
+  end
+
+  let :uuid do
+    "3846B06C-C3C1-4C36-9426-2317B5C96C78"
+  end
+
+  before do
+    allow(Time).to receive(:now) { now }
+    allow(trust_me).to receive(:`).with("uuidgen") { uuid }
+  end
+
+  shared_examples_for "api_call" do |method, extra_request_params = {}|
+    let :response_body do
+      File.read("spec/fixtures/verify-#{method}-success.json")
+    end
+
+    let :request_headers do
+      {
+        "Authorization"    => /TSA custid:.*/,
+        "x-ts-date"        => now_rfc1123,
+        "x-ts-auth-method" => "HMAC-SHA256",
+        "x-ts-nonce"       => uuid,
+        "Content-Type"     => "application/x-www-form-urlencoded",
+
+        # Set automatically by Net::HTTP
+        "Accept"           => "*/*",
+        "Accept-Encoding"  => "gzip;q=1.0,deflate;q=0.6,identity;q=0.3",
+        "User-Agent"       => "Ruby"
+      }
+    end
+
+    let :request_body do
+      {
+        "language"     => "en-US",
+        "phone_number" => "15554443333",
+        "ucid"         => "TRVF",
+        "verify_code"  => "12345"
+      }.merge(extra_request_params)
+    end
+
+    before do
+      allow(trust_me).to receive(:generate_code) { "12345" }
+    end
+
+    let! :stub do
+      stub_request(:post, "#{TrustMe::API_URL}/v1/verify/#{method}")
+        .with(:headers => request_headers, :body => request_body)
+        .to_return(:body => response_body)
+    end
+  end
+
+  describe "#send_verification_call!" do
+    it_behaves_like "api_call", "call" do
+      it "submits the request" do
+        trust_me.send_verification_call! "15554443333"
+
+        expect(stub).to have_been_made
+      end
+
+      it "returns the the data and code" do
+        response = trust_me.send_verification_call! "15554443333"
+
+        expect(response[:code]).to eq("12345")
+        expect(response[:data]).to eq(JSON.parse(response_body))
+      end
+    end
+  end
+
+  describe "#send_verification_sms!" do
+    it_behaves_like "api_call", "sms", { :template => "CODE: $$CODE$$" } do
+      it "submits the request" do
+        trust_me.send_verification_sms! "15554443333", :template => "CODE: $$CODE$$"
+
+        expect(stub).to have_been_made
+      end
+
+      it "returns the the data and code" do
+        response = trust_me.send_verification_sms! "15554443333", :template => "CODE: $$CODE$$"
+
+        expect(response[:code]).to eq("12345")
+        expect(response[:data]).to eq(JSON.parse(response_body))
+      end
+    end
+  end
+
+  describe "#generate_headers" do
+    let :hash do
+      OpenSSL::Digest.new("sha256", "abc")
+    end
+
+    let :params do
+      "a=1&b=2"
+    end
+
+    let :resource do
+      "/some/resource"
+    end
+
+    before do
+      allow(OpenSSL::Digest::SHA256).to receive(:digest) { hash }
+    end
+
+    let :auth do
+      content = [
+        "POST",
+        "application/x-www-form-urlencoded",
+        "",
+        "x-ts-auth-method:HMAC-SHA256",
+        "x-ts-date:#{now_rfc1123}",
+        "x-ts-nonce:#{uuid}",
+        params,
+        resource
+      ].join("\n")
+
+      Base64.encode64 OpenSSL::HMAC.digest(hash, "secret", content)
+    end
+
+    it "returns proper headers" do
+      headers = trust_me.generate_headers(:params => params, :resource => resource)
+
+      expect(headers["Authorization"]).to eq "TSA custid:#{auth}"
+      expect(headers["Content-Type"]).to eq "application/x-www-form-urlencoded"
+      expect(headers["x-ts-date"]).to eq now_rfc1123
+      expect(headers["x-ts-auth-method"]).to eq "HMAC-SHA256"
+      expect(headers["x-ts-nonce"]).to eq uuid
+    end
+  end
+end

data/vendor/cacert.pem

@@ -0,0 +1,22 @@
+# https://www.thawte.com/roots/thawte_Premium_Server_CA.pem
+
+-----BEGIN CERTIFICATE-----
+MIIDNjCCAp+gAwIBAgIQNhIilsXjOKUgodJfTNcJVDANBgkqhkiG9w0BAQUFADCB
+zjELMAkGA1UEBhMCWkExFTATBgNVBAgTDFdlc3Rlcm4gQ2FwZTESMBAGA1UEBxMJ
+Q2FwZSBUb3duMR0wGwYDVQQKExRUaGF3dGUgQ29uc3VsdGluZyBjYzEoMCYGA1UE
+CxMfQ2VydGlmaWNhdGlvbiBTZXJ2aWNlcyBEaXZpc2lvbjEhMB8GA1UEAxMYVGhh
+d3RlIFByZW1pdW0gU2VydmVyIENBMSgwJgYJKoZIhvcNAQkBFhlwcmVtaXVtLXNl
+cnZlckB0aGF3dGUuY29tMB4XDTk2MDgwMTAwMDAwMFoXDTIxMDEwMTIzNTk1OVow
+gc4xCzAJBgNVBAYTAlpBMRUwEwYDVQQIEwxXZXN0ZXJuIENhcGUxEjAQBgNVBAcT
+CUNhcGUgVG93bjEdMBsGA1UEChMUVGhhd3RlIENvbnN1bHRpbmcgY2MxKDAmBgNV
+BAsTH0NlcnRpZmljYXRpb24gU2VydmljZXMgRGl2aXNpb24xITAfBgNVBAMTGFRo
+YXd0ZSBQcmVtaXVtIFNlcnZlciBDQTEoMCYGCSqGSIb3DQEJARYZcHJlbWl1bS1z
+ZXJ2ZXJAdGhhd3RlLmNvbTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEA0jY2
+aovXwlue2oFBYo847kkEVdbQ7xwblRZH7xhINTpS9CtqBo87L+pW46+GjZ4X9560
+ZXUCTe/LCaIhUdib0GfQug2SBhRz1JPLlyoAnFxODLz6FVL88kRu2hFKbgifLy3j
++ao6hnO2RlNYyIkFvYMRuHM/qgeN9EJN50CdHDcCAwEAAaMTMBEwDwYDVR0TAQH/
+BAUwAwEB/zANBgkqhkiG9w0BAQUFAAOBgQBlkKyID1bZ5jA01CbH0FDxkt5r1DmI
+CSLGpmODA/eZd9iy5Ri4XWPz1HP7bJyZePFLeH0ZJMMrAoT4vCLZiiLXoPxx7JGH
+IPG47LHlVYCsPVLIOQ7C8MAFT9aCdYy9X9LcdpoFEsmvcsPcJX6kTY4XpeCHf+Ga
+WuFg3GQjPEIuTQ==
+-----END CERTIFICATE-----

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification
+name: trust_me
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Joshua Priddle
+- Justin Mazzi
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-11-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.20.4
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.20.4
+- !ruby/object:Gem::Dependency
+  name: rake-tomdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.0.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.0.2
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email:
+- jpriddle@site5.com
+- jmazzi@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.markdown
+- Rakefile
+- lib/trust_me.rb
+- lib/trust_me/version.rb
+- spec/fixtures/verify-call-success.json
+- spec/fixtures/verify-sms-success.json
+- spec/spec_helper.rb
+- spec/trust_me_spec.rb
+- vendor/cacert.pem
+homepage: https://github.com/site5/trust_me
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: 'TrustMe: Wrapper for the TeleSign REST API'
+test_files: []
+has_rdoc: