tozny-auth 0.1.6 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: cfe8301a7185fc15b5db4e783ef36c19c148d3aa
-  data.tar.gz: e3ee082717e5820b05944c7bbb5fbbf667416eb2
+  metadata.gz: e41382cfb8a2420e58e304d53d9750c71b7046de
+  data.tar.gz: b6dc52cfddc4209c57202ccaa3110548fbb8e560
 SHA512:
-  metadata.gz: a7f9300e08f52fd63a83b19ccfebfbcf84fdf0b0e3bd8335781043fa3da6b3b857e4d64a17d4bf04b2651edc1ed0ea66ce33ef3b252ed718f75a241efa17e4eb
-  data.tar.gz: 3dfef0a874d67a6415b564ddee401995176e5b2a2cc48b2fdf706ced4eb7a9fd13b99d64679957050fbfe22833f7c67352a453120a02fa2f79f52080e9dd1c04
+  metadata.gz: 3efa4daf484e74ad5a7fe404b134e804025f8cc481973b42ce174848d9b6854b46f22682fa3583b1a3f65732b72d5d82219ea908d702ce0e2298f1beae21d610
+  data.tar.gz: ba7dbf7c62dcfddb841bfa0c71b1b7224a083e0b392fc3c744b558907c0d1c51f472b927e280a372154734c31feaf28e9deb1a44aa55aff77c6d723cc20e27bd

data/.rubocop.yml

@@ -1,8 +1,8 @@
-Metrics/LineLength:
-  Enabled: false
-Metrics/MethodLength:
-  Enabled: false
-Rails:
-  Enabled: false
-Style/SpaceInsideHashLiteralBraces:
+Metrics/LineLength:
+  Enabled: false
+Metrics/MethodLength:
+  Enabled: false
+Rails:
+  Enabled: false
+Style/SpaceInsideHashLiteralBraces:
   Enabled: false

data/bin/console

@@ -1,14 +1,14 @@
-#!/usr/bin/env ruby
-
-require "bundler/setup"
-require "tozny/auth"
-
-# 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
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "tozny/auth"
+
+# 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

data/bin/setup

@@ -1,8 +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
+#!/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/lib/tozny/auth/common.rb

@@ -1,64 +1,64 @@
-require 'openssl'
-require 'base64'
-require 'json'
-require 'securerandom'
-
-module Tozny
-  # utility class for tozny-specific cryptography and encoding
-  class Core
-
-    # encodes a string according to the base64url specification, including removing padding
-    # @param [String] str the string to encode
-    # @return [String] the base64url-encoded string
-    def self.base64url_encode(str)
-      Base64::strict_encode64(
-          str
-        )
-        .tr('+/', '-_')
-        .tr('=', '')
-    end
-
-    # decodes a padding-stripped base64url string
-    # @param [String] str the base64url-encoded string
-    # @return [String] the decoded plaintext string
-    def self.base64url_decode(str)
-      Base64::strict_decode64(
-        str.tr('-_', '+/')
-        .ljust(str.length+(str.length % 4), '='))
-        # replace - with + and _ with /
-        # then add padding
-    end
-
-    # checks the HMAC/SHA256 signature of a string
-    # @param [String] signature the signature to check against
-    # @param [String] str the signed data to check the signature against
-    # @param [String] secret the secret to check the signature against
-    # @return [TrueClass, FalseClass] whether the signature matched
-    def self.check_signature(signature, str, secret)
-      expected_sig = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), secret, str)
-      expected_sig == signature
-    end
-
-    # base64url encodes and signs some data
-    # * yields a base64url-encoded data object AND base64url-encoded signature
-    # * the signature signs the base64-encoded data, NOT the raw data
-    # @param [String] data the raw data to be encoded
-    # @param [String] secret the secret to sign the encoded data with
-    # @return [Hash] a hash including the signed_data and a signature
-    def self.encode_and_sign(data, secret)
-      encoded_data = base64url_encode(data)
-      sig = OpenSSL::HMAC.digest(OpenSSL::Digest.new('sha256'), secret, encoded_data)
-      encoded_sig = base64url_encode(sig)
-      {
-        signed_data: encoded_data,
-        signature: encoded_sig
-      }
-    end
-
-    # generates a nonce (number used once)
-    # @return [String] a hexadecimal nonce
-    def self.generate_nonce
-      OpenSSL::Digest::SHA256.hexdigest SecureRandom.random_bytes(8)
-    end
-  end
-end
+require 'openssl'
+require 'base64'
+require 'json'
+require 'securerandom'
+
+module Tozny
+  # utility class for tozny-specific cryptography and encoding
+  class Core
+
+    # encodes a string according to the base64url specification, including removing padding
+    # @param [String] str the string to encode
+    # @return [String] the base64url-encoded string
+    def self.base64url_encode(str)
+      Base64::strict_encode64(
+          str
+        )
+        .tr('+/', '-_')
+        .tr('=', '')
+    end
+
+    # decodes a padding-stripped base64url string
+    # @param [String] str the base64url-encoded string
+    # @return [String] the decoded plaintext string
+    def self.base64url_decode(str)
+      Base64::strict_decode64(
+        str.tr('-_', '+/')
+        .ljust(str.length+(str.length % 4), '='))
+        # replace - with + and _ with /
+        # then add padding
+    end
+
+    # checks the HMAC/SHA256 signature of a string
+    # @param [String] signature the signature to check against
+    # @param [String] str the signed data to check the signature against
+    # @param [String] secret the secret to check the signature against
+    # @return [TrueClass, FalseClass] whether the signature matched
+    def self.check_signature(signature, str, secret)
+      expected_sig = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), secret, str)
+      expected_sig == signature
+    end
+
+    # base64url encodes and signs some data
+    # * yields a base64url-encoded data object AND base64url-encoded signature
+    # * the signature signs the base64-encoded data, NOT the raw data
+    # @param [String] data the raw data to be encoded
+    # @param [String] secret the secret to sign the encoded data with
+    # @return [Hash] a hash including the signed_data and a signature
+    def self.encode_and_sign(data, secret)
+      encoded_data = base64url_encode(data)
+      sig = OpenSSL::HMAC.digest(OpenSSL::Digest.new('sha256'), secret, encoded_data)
+      encoded_sig = base64url_encode(sig)
+      {
+        signed_data: encoded_data,
+        signature: encoded_sig
+      }
+    end
+
+    # generates a nonce (number used once)
+    # @return [String] a hexadecimal nonce
+    def self.generate_nonce
+      OpenSSL::Digest::SHA256.hexdigest SecureRandom.random_bytes(8)
+    end
+  end
+end

data/lib/tozny/auth/version.rb

@@ -1,5 +1,5 @@
 module Tozny
   module Auth
-    VERSION = '0.1.6'
+    VERSION = '0.1.7'
   end
 end

data/lib/tozny/realm.rb

@@ -1,274 +1,303 @@
-require 'tozny/user'
-require 'json'
-require 'net/http'
-require 'uri'
-
-# rubocop:disable Metrics/PerceivedComplexity
-
-module Tozny
-  class Realm
-    attr_accessor :realm_key_id, :realm_secret, :api_url, :user_api
-
-    def initialize(realm_key_id, realm_secret, api_url = nil)
-      # set the API URL
-      if !api_url.nil?
-        self.api_url = api_url
-      elsif !(ENV['API_URL'].nil?)
-        self.api_url = ENV['API_URL']
-      else
-        self.api_url = 'https://api.tozny.com/index.php'
-      end
-      unless self.api_url.is_a? URI # don't try to parse a URI instance into a URI, as this will break
-        self.api_url = URI.parse(self.api_url)
-      end
-
-      set_new_realm(realm_key_id, realm_secret)
-
-    end
-
-    # use a new realm_key_id and realm_secret. updates the user_api handle to reflect this change as well.
-    # @param [String] realm_key_id
-    # @param [String] realm_secret
-    # @return [TrueClass] will always return true
-    def set_new_realm(realm_key_id, realm_secret)
-      self.realm_key_id = realm_key_id
-      self.realm_secret = realm_secret
-      if user_api.is_a? ::Tozny::User
-        user_api.set_new_realm(realm_key_id)
-      else
-        self.user_api = ::Tozny::User.new(realm_key_id, api_url)
-      end
-      true
-    end
-
-    # verify a login and extract user information from a signed packet forwarded to the server
-    # @param [String] signed_data the base64URL data to validate
-    # @param [String] signature the string representation of the signature to check the login with
-    # @return [Hash, FalseClass] the login information or false if the login did not check out
-    def check_login_locally(signed_data, signature)
-      if check_signature(signed_data, signature)
-        login_info = JSON.parse(::Tozny::Core.base64url_decode(signed_data))
-        return false if login_info[:expires_at] < Time.now.to_i
-        login_info
-      else
-        false
-      end
-    end
-
-    # verify a login from a user and session id. Does not return complete login information.
-    # @param [String] user_id the user_id of the login to check
-    # @param [String] session_id the session_id of the login to check
-    # @return [Hash] the return from the API
-    def check_login_via_api(user_id, session_id) # NOTE: this only returns true/false. You need to parse the data locally. See Tozny::Core.base64url_decode
-      raw_call(
-        method: 'realm.check_valid_login',
-        user_id: user_id,
-        session_id: session_id
-      )[:return] == 'true'
-    end
-
-    # Add a user to a closed realm
-    # @param [String] defer 'true' or 'false', defines whether the user should be deferred to later be completed by the app
-    # @param [Hash] meta any metadata to be added to the user (eg, favorite color or mother's home address). All meta will be stored as strings
-    # @param [String, OpenSSL::PKey::RSA] pub_key the public key of the user to be added. Only necessary
-    # @return [Hash, FalseClass] the user in its current (incomplete if defer is 'true' state)
-    # @raise ArgumentError if there is no pubkey when there should be one
-    def user_add(defer = 'false', meta = nil, pub_key)
-      unless pub_key.nil?
-        pub_key = OpenSSL::PKey::RSA.new pub_key if pub_key.is_a? String
-        pub_key = pub_key.public_key if pub_key.private?
-      end
-
-      request_obj = {
-        method: 'realm.user_add',
-        defer: defer
-      }
-      if defer == 'false'
-        raise ArgumentError, 'Must provide a public key if not using deferred enrollment' if pub_key.nil?
-        request_obj[:pub_key] = pub_key
-      end
-
-      unless meta.nil?
-        request_obj[:extra_fields] = Tozny::Core.base64url_encode(meta.to_json)
-      end
-
-      user = raw_call request_obj
-      return false unless user[:return] == 'ok'
-      user
-    end
-
-    # update a user's meta fields
-    # * Note: all meta fields are stored as strings
-    # @param [String] user_id
-    # @param [Hash{Symbol,String=>Object}] meta the metadata fields to update, along with their new values
-    # @return [Hash] the updated user
-    def user_update(user_id, meta)
-      raw_call(
-        method: 'realm.user_update',
-        user_id: user_id,
-        extra_fields: Tozny::Core.base64url_encode(meta.to_json)
-      )
-    end
-
-    # @param [String] user_id
-    # @return [Hash] the result of the request to the API
-    def user_delete(user_id)
-      raw_call(
-        method: 'realm.user_delete',
-        user_id: user_id
-      )
-    end
-
-    # retrieve a user's information
-    # * Note: all meta fields are stored as strings
-    # @param [String] user_id the id or email (if is_id = false) of the user to get
-    # @param [TrueClass, FalseClass] is_id true if looking up the user by id, false if looking up by email. defaults to true
-    # @return [Hash] the user's information
-    # @raise ArgumentError on failed lookup
-    def user_get(user_id, is_id = true)
-      request_obj = {
-        method: 'realm.user_get'
-      }
-      if is_id
-        request_obj[:user_id] = user_id
-      else
-        request_obj[:tozny_email] = user_id
-      end
-
-      user = raw_call(request_obj)
-      if user.nil? || user[:results].nil?
-        raise ArgumentError, ('No user was found for ' + (is_id ? 'id' : 'email') + ': ' + user_id + '.')
-      end
-      user[:results]
-    end
-
-    # performs a device add call
-    # @param [String] user_id
-    # @return [Hash] the result of the call: keys include  :user_id, :temp_key, :secret_enrollment_url, and :key_id
-    def user_device_add(user_id)
-      raw_call(
-        method: 'realm.user_device_add',
-        user_id: user_id
-      )
-    end
-
-    # create an OOB challenge question session
-    # @param [Hash<Symbol, String>, String] question either a question hash, as specified by the options, or the text of a question to be presented to the user. Required.
-    # @option question [String] :question The text of the question to be presented to the user
-    # @option question [String] :success The URL the user's browser should be redirected to after successful authentication
-    # @option question [String] :error The URL the user's browser should be redirected to after unsuccessful authentication
-    # @param [String] success_url The URL the user's browser should be redirected to after successful authentication if not specified in the question object
-    # @param [String] error_url The URL the user's browser should be redirected to after unsuccessful authentication if not specified in the question object
-    # @param [String] user_id optional. The user who should answer the question.
-    # @raise ArgumentError on invalid question type
-    # TODO: support URI objects instead of strings for success and error
-    # @return [Hash] the result of the API call
-    def question_challenge(question, success_url, error_url, user_id)
-      raise ArgumentError, 'question must either be a string or an options hash as specified' unless (question.is_a?String) || (question.is_a?Hash)
-      final_question = nil # scope final_question and prevent linting errors
-      if question.is_a?Hash
-        final_question = question
-        final_question[:type] = 'callback'
-      elsif (success_url.is_a?String) || (error_url.is_a?String)
-        final_question = {
-          type: 'callback',
-          question: question
-        }
-        final_question[:success] = success_url if success_url.is_a?String
-        final_question[:error] = error_url if error_url.is_a?String
-      else
-        final_question = {
-          type: 'question',
-          question: question
-        }
-      end
-      request_obj = {
-        method: 'realm.question_challenge',
-        question: final_question
-      }
-      request_obj[:user_id] = user_id if user_id.is_a?String
-      raw_call request_obj
-    end
-
-    # Create an OTP challenge session
-    # @return [Hash] a hash [session_id, presence] containing an OTP session id and an OTP presence (an alias for a type-destination combination)
-    # @param [String] type one of 'sms-otp-6', 'sms-otp-8': the type of the OTP to send
-    # @param [String] destination the destination for the OTP. For an SMS OTP, this should be a phone number
-    # @param [String] presence can be used instead of 'type' and 'destination': an OTP presence provided by the TOZNY API
-    # @param [Object] data optional passthru data to be added to the signed response on a successful request
-    # @raise ArgumentError when not enough information to submit an OTP request
-    # @raise ArgumentError on invalid request type
-    def otp_challenge(type = nil, destination = nil, presence = nil, data = nil)
-      raise ArgumentError, 'must provide either a presence or a type and destination' if (type.nil? || destination.nil?) && presence.nil?
-      request_obj = {
-        method: 'realm.otp_challenge'
-      }
-      unless data.nil?
-        data = data.to_json unless data.is_a?String
-        request_obj[:data] = data
-      end
-
-      if presence.nil?
-        raise ArgumentError, "request type must one of 'sms-otp-6' or 'sms-otp-8'" unless %w(sms-otp-6 sms-otp-8).include? type
-        request_obj[:type] = type
-        # TODO: consider validating that 'destination' is a valid phone number when 'type' is sms-otp-*
-        request_obj[:destination] = destination
-      else
-        request_obj[:presence] = presence
-      end
-      raw_call request_obj
-    end
-
-    # Shorthand method to send an 6-digit OTP via SMS without a presence token
-    # @param destination @see(otp_challenge)
-    # @param data @see(otp_challenge)
-    # @return @see(otp_challenge)
-    def sms_otp(destination, data = nil)
-      # TODO: validate that 'destination' is a phone number
-      otp_challenge('sms-otp-6', destination, nil, data)
-    end
-
-    # push to a user's device based off of their id, email, or username
-    # @raise ArgumentError when not enough information is provided to find the user
-    # @param [String] session_id optional a valid Tozny session_id
-    # @param [String] user_id optional a Tozny user_id
-    # @param [String] email optional an email for a field associated with tozny_email
-    # @param [String] username optional a username for a field associated with tozny_username
-    # @return [Hash {Symbol => String, Integer, Array<TrueClass, FalseClass>}] the result of the push attempt. Will be true if any device owned by the user is successfully sent a push.
-    def user_push(session_id = nil, user_id = nil, email = nil, username = nil)
-      raise ArgumentError, 'must provide either a Tozny user id, a tozny_email, or a tozny_username in order to find the user to push to' if
-          user_id.nil? && email.nil? && username.nil?
-      session_id ||= user_api.login_challenge[:session_id]
-      request_obj = {
-        method: 'realm.user_push',
-        session_id: session_id
-      }
-      if !user_id.nil?
-        request_obj[:user_id] = user_id
-      elsif !email.nil?
-        request_obj[:tozny_email] = email
-      elsif !username.nil?
-        request_obj[:tozny_username] = username
-      end
-      raw_call request_obj
-    end
-
-    # perform a raw(ish) API call
-    # @param [Hash{Symbol, String => Object}] request_obj The request to conduct. Should include a :method at the least. Prefer symbol keys to string keys
-    # @return [Object] The parsed result of the request. NOTE: most types will be stringified for most requests
-    def raw_call(request_obj)
-      request_obj[:nonce] = Tozny::Core.generate_nonce # generate the nonce
-      request_obj[:expires_at] = Time.now.to_i + 5 * 60 # UNIX timestamp for now +5 min TODO: does this work with check_login_via_api, or should it default to a passed in expires_at?
-      unless request_obj.key?('realm_key_id') || request_obj.key?(:realm_key_id) # check for both string and symbol
-        # TODO: how should we handle conflicts of symbol and string keys?
-        request_obj[:realm_key_id] = realm_key_id
-      end
-      encoded_params = Tozny::Core.encode_and_sign(request_obj.to_json, realm_secret) # make a proper request of it.
-      request_url = api_url # copy the URL to a local variable so that we can add the query params
-      request_url.query = URI.encode_www_form encoded_params # encode signed_data and signature as query params
-      # p request_url
-      http_result = Net::HTTP.get(request_url)
-      JSON.parse(http_result, symbolize_names: true) # TODO: handle errors
-    end
-  end
-end
+require 'tozny/user'
+require 'json'
+require 'net/http'
+require 'uri'
+
+# rubocop:disable Metrics/PerceivedComplexity
+
+module Tozny
+  class Realm
+    attr_accessor :realm_key_id, :realm_secret, :api_url, :user_api
+
+    def initialize(realm_key_id, realm_secret, api_url = nil)
+      # set the API URL
+      if !api_url.nil?
+        self.api_url = api_url
+      elsif !(ENV['API_URL'].nil?)
+        self.api_url = ENV['API_URL']
+      else
+        self.api_url = 'https://api.tozny.com/index.php'
+      end
+      unless self.api_url.is_a? URI # don't try to parse a URI instance into a URI, as this will break
+        self.api_url = URI.parse(self.api_url)
+      end
+
+      set_new_realm(realm_key_id, realm_secret)
+
+    end
+
+    # use a new realm_key_id and realm_secret. updates the user_api handle to reflect this change as well.
+    # @param [String] realm_key_id
+    # @param [String] realm_secret
+    # @return [TrueClass] will always return true
+    def set_new_realm(realm_key_id, realm_secret)
+      self.realm_key_id = realm_key_id
+      self.realm_secret = realm_secret
+      if user_api.is_a? ::Tozny::User
+        user_api.set_new_realm(realm_key_id)
+      else
+        self.user_api = ::Tozny::User.new(realm_key_id, api_url)
+      end
+      true
+    end
+
+    # verify a login and extract user information from a signed packet forwarded to the server
+    # @param [String] signed_data the base64URL data to validate
+    # @param [String] signature the string representation of the signature to check the login with
+    # @return [Hash, FalseClass] the login information or false if the login did not check out
+    def check_login_locally(signed_data, signature)
+      if check_signature(signed_data, signature)
+        login_info = JSON.parse(::Tozny::Core.base64url_decode(signed_data))
+        return false if login_info[:expires_at] < Time.now.to_i
+        login_info
+      else
+        false
+      end
+    end
+
+    # verify a login from a user and session id. Does not return complete login information.
+    # @param [String] user_id the user_id of the login to check
+    # @param [String] session_id the session_id of the login to check
+    # @return [Hash] the return from the API
+    def check_login_via_api(user_id, session_id) # NOTE: this only returns true/false. You need to parse the data locally. See Tozny::Core.base64url_decode
+      raw_call(
+        method: 'realm.check_valid_login',
+        user_id: user_id,
+        session_id: session_id
+      )[:return] == 'true'
+    end
+
+    # Add a user to a closed realm
+    # @param [String] defer 'true' or 'false', defines whether the user should be deferred to later be completed by the app
+    # @param [Hash] meta any metadata to be added to the user (eg, favorite color or mother's home address). All meta will be stored as strings
+    # @param [String, OpenSSL::PKey::RSA] pub_key the public key of the user to be added. Only necessary
+    # @return [Hash, FalseClass] the user in its current (incomplete if defer is 'true' state)
+    # @raise ArgumentError if there is no pubkey when there should be one
+    def user_add(defer = 'false', meta = nil, pub_key)
+      unless pub_key.nil?
+        pub_key = OpenSSL::PKey::RSA.new pub_key if pub_key.is_a? String
+        pub_key = pub_key.public_key if pub_key.private?
+      end
+
+      request_obj = {
+        method: 'realm.user_add',
+        defer: defer
+      }
+      if defer == 'false'
+        raise ArgumentError, 'Must provide a public key if not using deferred enrollment' if pub_key.nil?
+        request_obj[:pub_key] = pub_key
+      end
+
+      unless meta.nil?
+        request_obj[:extra_fields] = Tozny::Core.base64url_encode(meta.to_json)
+      end
+
+      user = raw_call request_obj
+      return false unless user[:return] == 'ok'
+      user
+    end
+
+    # update a user's meta fields
+    # * Note: all meta fields are stored as strings
+    # @param [String] user_id
+    # @param [Hash{Symbol,String=>Object}] meta the metadata fields to update, along with their new values
+    # @return [Hash] the updated user
+    def user_update(user_id, meta)
+      raw_call(
+        method: 'realm.user_update',
+        user_id: user_id,
+        extra_fields: Tozny::Core.base64url_encode(meta.to_json)
+      )
+    end
+
+    # @param [String] user_id
+    # @return [Hash] the result of the request to the API
+    def user_delete(user_id)
+      raw_call(
+        method: 'realm.user_delete',
+        user_id: user_id
+      )
+    end
+
+    # retrieve a user's information
+    # * Note: all meta fields are stored as strings
+    # @param [String] user_id the id or email (if is_id = false) of the user to get
+    # @param [TrueClass, FalseClass] is_id true if looking up the user by id, false if looking up by email. defaults to true
+    # @return [Hash] the user's information
+    # @raise ArgumentError on failed lookup
+    def user_get(user_id, is_id = true)
+      request_obj = {
+        method: 'realm.user_get'
+      }
+      if is_id
+        request_obj[:user_id] = user_id
+      else
+        request_obj[:tozny_email] = user_id
+      end
+
+      user = raw_call(request_obj)
+      if user.nil? || user[:results].nil?
+        raise ArgumentError, ('No user was found for ' + (is_id ? 'id' : 'email') + ': ' + user_id + '.')
+      end
+      user[:results]
+    end
+
+    # performs a device add call
+    # @param [String] user_id
+    # @return [Hash] the result of the call: keys include  :user_id, :temp_key, :secret_enrollment_url, and :key_id
+    def user_device_add(user_id)
+      raw_call(
+        method: 'realm.user_device_add',
+        user_id: user_id
+      )
+    end
+
+    # create an OOB challenge question session
+    # @param [Hash<Symbol, String>, String] question either a question hash, as specified by the options, or the text of a question to be presented to the user. Required.
+    # @option question [String] :question The text of the question to be presented to the user
+    # @option question [String] :success The URL the user's browser should be redirected to after successful authentication
+    # @option question [String] :error The URL the user's browser should be redirected to after unsuccessful authentication
+    # @param [String] success_url The URL the user's browser should be redirected to after successful authentication if not specified in the question object
+    # @param [String] error_url The URL the user's browser should be redirected to after unsuccessful authentication if not specified in the question object
+    # @param [String] user_id optional. The user who should answer the question.
+    # @raise ArgumentError on invalid question type
+    # TODO: support URI objects instead of strings for success and error
+    # @return [Hash] the result of the API call
+    def question_challenge(question, success_url, error_url, user_id)
+      raise ArgumentError, 'question must either be a string or an options hash as specified' unless (question.is_a?String) || (question.is_a?Hash)
+      final_question = nil # scope final_question and prevent linting errors
+      if question.is_a?Hash
+        final_question = question
+        final_question[:type] = 'callback'
+      elsif (success_url.is_a?String) || (error_url.is_a?String)
+        final_question = {
+          type: 'callback',
+          question: question
+        }
+        final_question[:success] = success_url if success_url.is_a?String
+        final_question[:error] = error_url if error_url.is_a?String
+      else
+        final_question = {
+          type: 'question',
+          question: question
+        }
+      end
+      request_obj = {
+        method: 'realm.question_challenge',
+        question: final_question
+      }
+      request_obj[:user_id] = user_id if user_id.is_a?String
+      raw_call request_obj
+    end
+
+    # Create an OTP challenge session
+    # @return [Hash] a hash [session_id, presence] containing an OTP session id and an OTP presence (an alias for a type-destination combination)
+    # @param [String] type one of 'sms-otp-6', 'sms-otp-8': the type of the OTP to send
+    # @param [String] destination the destination for the OTP. For an SMS OTP, this should be a phone number
+    # @param [String] presence can be used instead of 'type' and 'destination': an OTP presence provided by the TOZNY API
+    # @param [Object] data optional passthru data to be added to the signed response on a successful request
+    # @param [String] context One of "verify," "authenticate," or "enroll"
+    # @raise ArgumentError when not enough information to submit an OTP request
+    # @raise ArgumentError on invalid request type
+    def otp_challenge(type = nil, destination = nil, presence = nil, data = nil, context = nil)
+      raise ArgumentError, 'must provide either a presence or a type and destination' if (type.nil? || destination.nil?) && presence.nil?
+      request_obj = {
+        method: 'realm.otp_challenge'
+      }
+      unless data.nil?
+        data = data.to_json unless data.is_a?String
+        request_obj[:data] = data
+      end
+
+      if presence.nil?
+        raise ArgumentError, "request type must one of 'sms-otp-6' or 'sms-otp-8'" unless %w(sms-otp-6 sms-otp-8).include? type
+        request_obj[:type] = type
+        # TODO: consider validating that 'destination' is a valid phone number when 'type' is sms-otp-*
+        request_obj[:destination] = destination
+      else
+        request_obj[:presence] = presence
+      end
+
+      request_obj[:context] = context unless context.nil?
+
+      raw_call request_obj
+    end
+
+    # Create a magic link challenge session
+    #
+    # @param [String]  destination The email address or phone number to which we will send a challenge
+    # @param [String]  endpoint    URL endpoint to use as a base for the challenge URL
+    # @param [Integer] lifespan    Number of seconds for which the challenge URL is valid
+    # @param [String]  context     One of "verify," "authenticate," or "enroll"
+    # @param [Bool]    send        Flag whether or not to send the email (if false will return the OTP URL instead)
+    # @param [String]  data        JSON-encoded string of data to be signed along with the request
+    #
+    # @return [Hash] a hash of the session and presence for the challenge
+    #
+    def link_challenge(destination, endpoint, lifespan = nil, context = nil, send = true, data = nil)
+      request_obj = {
+          method: 'realm.link_challenge',
+          destination: destination,
+          endpoint: endpoint,
+          send: !! send ? 'yes' : 'no' # Hacky double-bang to convert nil to false and anything else into a boolean
+      }
+      request_obj['lifespan'] = lifespan unless lifespan.nil?
+      request_obj['context'] = context unless context.nil?
+      request_obj['data'] = data unless data.nil?
+
+      raw_call request_obj
+    end
+
+    # Shorthand method to send an 6-digit OTP via SMS without a presence token
+    # @param destination @see(otp_challenge)
+    # @param data @see(otp_challenge)
+    # @return @see(otp_challenge)
+    def sms_otp(destination, data = nil)
+      # TODO: validate that 'destination' is a phone number
+      otp_challenge('sms-otp-6', destination, nil, data)
+    end
+
+    # push to a user's device based off of their id, email, or username
+    # @raise ArgumentError when not enough information is provided to find the user
+    # @param [String] session_id optional a valid Tozny session_id
+    # @param [String] user_id optional a Tozny user_id
+    # @param [String] email optional an email for a field associated with tozny_email
+    # @param [String] username optional a username for a field associated with tozny_username
+    # @return [Hash {Symbol => String, Integer, Array<TrueClass, FalseClass>}] the result of the push attempt. Will be true if any device owned by the user is successfully sent a push.
+    def user_push(session_id = nil, user_id = nil, email = nil, username = nil)
+      raise ArgumentError, 'must provide either a Tozny user id, a tozny_email, or a tozny_username in order to find the user to push to' if
+          user_id.nil? && email.nil? && username.nil?
+      session_id ||= user_api.login_challenge[:session_id]
+      request_obj = {
+        method: 'realm.user_push',
+        session_id: session_id
+      }
+      if !user_id.nil?
+        request_obj[:user_id] = user_id
+      elsif !email.nil?
+        request_obj[:tozny_email] = email
+      elsif !username.nil?
+        request_obj[:tozny_username] = username
+      end
+      raw_call request_obj
+    end
+
+    # perform a raw(ish) API call
+    # @param [Hash{Symbol, String => Object}] request_obj The request to conduct. Should include a :method at the least. Prefer symbol keys to string keys
+    # @return [Object] The parsed result of the request. NOTE: most types will be stringified for most requests
+    def raw_call(request_obj)
+      request_obj[:nonce] = Tozny::Core.generate_nonce # generate the nonce
+      request_obj[:expires_at] = Time.now.to_i + 5 * 60 # UNIX timestamp for now +5 min TODO: does this work with check_login_via_api, or should it default to a passed in expires_at?
+      unless request_obj.key?('realm_key_id') || request_obj.key?(:realm_key_id) # check for both string and symbol
+        # TODO: how should we handle conflicts of symbol and string keys?
+        request_obj[:realm_key_id] = realm_key_id
+      end
+      encoded_params = Tozny::Core.encode_and_sign(request_obj.to_json, realm_secret) # make a proper request of it.
+      request_url = api_url # copy the URL to a local variable so that we can add the query params
+      request_url.query = URI.encode_www_form encoded_params # encode signed_data and signature as query params
+      # p request_url
+      http_result = Net::HTTP.get(request_url)
+      JSON.parse(http_result, symbolize_names: true) # TODO: handle errors
+    end
+  end
+end

data/lib/tozny/user.rb

@@ -1,93 +1,153 @@
-require 'tozny/auth/common'
-
-module Tozny
-  class User
-    attr_accessor :realm_key_id, :api_url
-    def initialize(realm_key_id, api_url = nil)
-      if !api_url.nil?
-        self.api_url = api_url
-      elsif !(ENV['API_URL'].nil?) # rubocop:disable all
-        self.api_url = ENV['API_URL']
-      else
-        self.api_url = 'https://api.tozny.com/index.php'
-      end
-
-      self.api_url = URI.parse(self.api_url) unless self.api_url.is_a? URI
-
-      set_new_realm(realm_key_id)
-    end
-
-    # check the status of a session
-    # @param [String] session_id the session to check
-    # @return [TrueClass, FalseClass] 'true' if the use has logged in with the session, false otherwise
-    def check_session_status(session_id)
-      raw_call(
-        method: 'user.check_session_status',
-        session_id: session_id
-      ).key?(:signed_data)
-    end
-
-    # use a new realm_key_id
-    # @param [String] realm_key_id
-    # @return [TrueClass] will always return true
-    def set_new_realm(realm_key_id) # rubocop:disable Style/AccessorMethodName
-      self.realm_key_id = realm_key_id
-      true
-    end
-
-    # Generate a new login challenge session
-    # @param [TrueClass, FalseClass] user_add optional: whether or not to create an enrollment challenge rather than an authentication challenge
-    # @return [Hash] a challenge session (:challenge, :realm_key_id, :session_id, :qr_url, :mobile_url, :created_at, :presence = "")
-    def login_challenge(user_add = nil)
-      request_obj = {
-        method: 'user.login_challenge'
-      }
-      request_obj[:user_add] = user_add if user_add
-      raw_call request_obj
-    end
-
-    # Create an OTP challenge session
-    # @return [Hash] a hash [session_id, presence] containing an OTP session id and an OTP presence (an alias for a type-destination combination)
-    # @param [String] type one of 'sms-otp-6', 'sms-otp-8': the type of the OTP to send
-    # @param [String] destination the destination for the OTP. For an SMS OTP, this should be a phone number
-    # @param [String] presence can be used instead of 'type' and 'destination': an OTP presence provided by the TOZNY API
-    # @raise ArgumentError when not enough information to submit an OTP request
-    # @raise ArgumentError on invalid request type
-    def otp_challenge(type = nil, destination = nil, presence = nil)
-      raise ArgumentError, 'must provide either a presence or a type and destination' if (type.nil? || destination.nil?) && presence.nil?
-      request_obj = {
-        method: 'user.otp_challenge'
-      }
-      if presence.nil?
-        raise ArgumentError, "request type must one of 'sms-otp-6' or 'sms-otp-8'" unless %w(sms-otp-6 sms-otp-8).include? type
-        request_obj[:type] = type
-        # TODO: consider validating that 'destination' is a valid phone number when 'type' is sms-otp-*
-        request_obj[:destination] = destination
-      else
-        request_obj[:presence] = presence
-      end
-      raw_call request_obj
-    end
-
-    # Check an OTP against an OTP session
-    # @param [String] session_id the OTP session to validate
-    # @param [String, Integer] otp the OTP to check
-    # @return [Hash] The signed_data and signature containing a session ID and metadata, if any, on success. Otherwise, error[s].
-    def otp_result(session_id, otp)
-      raw_call(method: 'user.otp_result', session_id: session_id, otp: otp)
-    end
-
-    # Perform a raw(ish) API call
-    # @param [Hash{Symbol, String => Object}] request_obj The request to conduct. Should include a :method at the least. Prefer symbol keys to string keys
-    # @return [Object] The parsed result of the request. NOTE: most types will be stringified for most requests
-    def raw_call(request_obj)
-      unless request_obj.key?('realm_key_id') || request_obj.key?(:realm_key_id) # check for both string and symbol
-        # TODO: how should we handle conflicts of symbol and string keys?
-        request_obj[:realm_key_id] = realm_key_id
-      end
-      request_url = api_url # copy the URL to a local variable so that we can add the query params
-      request_url.query = URI.encode_www_form request_obj # encode request as query params
-      JSON.parse(Net::HTTP.get(request_url), symbolize_names: true)
-    end
-  end
-end
+require 'tozny/auth/common'
+
+module Tozny
+  class User
+    attr_accessor :realm_key_id, :api_url
+    def initialize(realm_key_id, api_url = nil)
+      if !api_url.nil?
+        self.api_url = api_url
+      elsif !(ENV['API_URL'].nil?) # rubocop:disable all
+        self.api_url = ENV['API_URL']
+      else
+        self.api_url = 'https://api.tozny.com/index.php'
+      end
+
+      self.api_url = URI.parse(self.api_url) unless self.api_url.is_a? URI
+
+      set_new_realm(realm_key_id)
+    end
+
+    # check the status of a session
+    # @param [String] session_id the session to check
+    # @return [TrueClass, FalseClass] 'true' if the use has logged in with the session, false otherwise
+    def check_session_status(session_id)
+      raw_call(
+        method: 'user.check_session_status',
+        session_id: session_id
+      ).key?(:signed_data)
+    end
+
+    # use a new realm_key_id
+    # @param [String] realm_key_id
+    # @return [TrueClass] will always return true
+    def set_new_realm(realm_key_id) # rubocop:disable Style/AccessorMethodName
+      self.realm_key_id = realm_key_id
+      true
+    end
+
+    # Generate a new login challenge session
+    # @param [TrueClass, FalseClass] user_add optional: whether or not to create an enrollment challenge rather than an authentication challenge
+    # @return [Hash] a challenge session (:challenge, :realm_key_id, :session_id, :qr_url, :mobile_url, :created_at, :presence = "")
+    def login_challenge(user_add = nil)
+      request_obj = {
+        method: 'user.login_challenge'
+      }
+      request_obj[:user_add] = user_add if user_add
+      raw_call request_obj
+    end
+
+    # Create an OTP challenge session
+    # @return [Hash] a hash [session_id, presence] containing an OTP session id and an OTP presence (an alias for a type-destination combination)
+    # @param [String] type one of 'sms-otp-6', 'sms-otp-8': the type of the OTP to send
+    # @param [String] destination the destination for the OTP. For an SMS OTP, this should be a phone number
+    # @param [String] presence can be used instead of 'type' and 'destination': an OTP presence provided by the TOZNY API
+    # @param [String] context One of "verify," "authenticate," or "enroll"
+    # @raise ArgumentError when not enough information to submit an OTP request
+    # @raise ArgumentError on invalid request type
+    def otp_challenge(type = nil, destination = nil, presence = nil, context = nil)
+      raise ArgumentError, 'must provide either a presence or a type and destination' if (type.nil? || destination.nil?) && presence.nil?
+      request_obj = {
+        method: 'user.otp_challenge'
+      }
+      if presence.nil?
+        raise ArgumentError, "request type must one of 'sms-otp-6' or 'sms-otp-8'" unless %w(sms-otp-6 sms-otp-8).include? type
+        request_obj[:type] = type
+        # TODO: consider validating that 'destination' is a valid phone number when 'type' is sms-otp-*
+        request_obj[:destination] = destination
+      else
+        request_obj[:presence] = presence
+      end
+
+      request_obj[:context] = context unless context.nil?
+
+      raw_call request_obj
+    end
+
+    # Create a magic link challenge session
+    #
+    # @param [String] destination The email address or phone number to which we will send a challenge
+    # @param [String] endpoint    URL endpoint to use as a base for the challenge URL
+    # @param [String] context     One of "verify," "authenticate," or "enroll"
+    #
+    # @return [Hash] a hash of the session and presence for the challenge
+    #
+    def link_challenge(destination, endpoint, context = nil)
+      request_obj = {
+          method: 'user.link_challenge',
+          destination: destination,
+          endpoint: endpoint
+      }
+      request_obj['context'] = context unless context.nil?
+
+      raw_call request_obj
+    end
+
+    # Check an OTP against an OTP session
+    # @param [String] session_id the OTP session to validate
+    # @param [String, Integer] otp the OTP to check
+    # @return [Hash] The signed_data and signature containing a session ID and metadata, if any, on success. Otherwise, error[s].
+    def otp_result(session_id, otp)
+      raw_call(method: 'user.otp_result', session_id: session_id, otp: otp)
+    end
+
+    # Verify a magic link OTP
+    #
+    # @param [String] otp The OTP (usually embedded in a magic link)to validate
+    #
+    # @return [Hash]
+    #
+    def link_result(otp)
+      params = {
+          method: 'user.link_result',
+          realm_key_id: realm_key_id,
+          otp: otp
+      }
+      raw_call(params)
+    end
+
+    # Exchange a signed OTP challenge (from user.link_result or user.otp_result) for either an
+    # enrollment challenge (if the original context was "enroll") or a signed user payload (if
+    # the original context was "authenticate").
+    #
+    # @param [String] signed_data Signed data payload
+    # @param [String] signature   Realm-signed signature of the payload
+    # @param [String] session_id  If this was an authentication challenge, provide the session ID to close the session
+    #
+    # @return [Hash]
+    #
+    def challenge_exchange(signed_data, signature, session_id = nil)
+      params = {
+          method: 'user.challenge_exchange',
+          realm_key_id: realm_key_id,
+          signed_data: signed_data,
+          signature: signature
+      }
+      params['session_id'] = session_id unless session_id.nil?
+
+      raw_call(params)
+    end
+
+    # Perform a raw(ish) API call
+    # @param [Hash{Symbol, String => Object}] request_obj The request to conduct. Should include a :method at the least. Prefer symbol keys to string keys
+    # @return [Object] The parsed result of the request. NOTE: most types will be stringified for most requests
+    def raw_call(request_obj)
+      unless request_obj.key?('realm_key_id') || request_obj.key?(:realm_key_id) # check for both string and symbol
+        # TODO: how should we handle conflicts of symbol and string keys?
+        request_obj[:realm_key_id] = realm_key_id
+      end
+      request_url = api_url # copy the URL to a local variable so that we can add the query params
+      request_url.query = URI.encode_www_form request_obj # encode request as query params
+      JSON.parse(Net::HTTP.get(request_url), symbolize_names: true)
+    end
+  end
+end

metadata

@@ -1,69 +1,69 @@
 --- !ruby/object:Gem::Specification
 name: tozny-auth
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.1.7
 platform: ruby
 authors:
 - Ethan Bell / emanb29
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-06-28 00:00:00.000000000 Z
+date: 2016-08-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '1.12'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '1.12'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '10.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '10.0'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '5.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '5.0'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: 0.41.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: 0.41.1
 description: A set of methods to more conveniently access the Tozny authentication
@@ -74,9 +74,9 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".gitignore"
-- ".rubocop.yml"
-- ".travis.yml"
+- .gitignore
+- .rubocop.yml
+- .travis.yml
 - Gemfile
 - LICENSE
 - README.md
@@ -100,17 +100,17 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - "~>"
+  - - ~>
     - !ruby/object:Gem::Version
       version: '2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.5.1
+rubygems_version: 2.6.6
 signing_key: 
 specification_version: 4
 summary: Tozny Ruby SDK