cpaas-sdk 1.0.0

data/lib/cpaas-sdk/resources/notification.rb

@@ -0,0 +1,62 @@
+require 'cpaas-sdk/util'
+
+module Cpaas
+  #
+  # CPaaS notification helper methods
+  #
+  class Notification
+    #
+    # Parse inbound sms notification received in webhook. It parses the notification and returns
+    # simplified version of the response.
+    #
+    # @param notification [Hash] JSON received in the subscription webhook.
+    #
+    def self.parse(notification)
+      parsed_notification = convert_hash_keys(notification)
+      top_level_key = parsed_notification.keys.first
+      notification_obj = parsed_notification[top_level_key]
+
+      case top_level_key
+      when :outbound_sms_message_notification, :inbound_sms_message_notification
+        message = notification_obj.dig(:outbound_sms_message).nil? ? notification_obj.dig(:inbound_sms_message) : notification_obj.dig(:outbound_sms_message)
+
+        {
+          notification_id: notification_obj.dig(:id),
+          notification_date_time: notification_obj.dig(:date_time),
+          type: types[top_level_key]
+        }.merge(message)
+      when :sms_subscription_cancellation_notification
+        {
+          subscription_id: id_from(notification_obj.dig(:link, 0, :href)),
+          notification_id: notification_obj.dig(:id),
+          notification_date_time: notification_obj.dig(:date_time),
+          type: types[top_level_key]
+        }
+      when :sms_event_notification
+        {
+          notification_id: notification_obj.dig(:id),
+          notification_date_time: notification_obj.dig(:date_time),
+          message_id: id_from(notification_obj.dig(:link, 0, :href)),
+          type: types[top_level_key],
+          event_details: {
+            description: notification_obj.dig(:event_description),
+            type: notification_obj.dig(:event_type)
+          }
+        }
+      else
+        notification_obj
+      end
+    end
+
+    private
+
+    def self.types
+      {
+        outbound_sms_message_notification: 'outbound',
+        inbound_sms_message_notification: 'inbound',
+        sms_subscription_cancellation_notification: 'subscriptionCancel',
+        sms_event_notification: 'event'
+      }
+    end
+  end
+end

data/lib/cpaas-sdk/resources/notification_channel.rb

@@ -0,0 +1,39 @@
+require 'cpaas-sdk/util'
+
+module Cpaas
+  # @private
+
+  class NotificationChannel
+    def self.create_channel(params)
+      options = {
+        body: {
+          notificationChannel: {
+            channelData: {
+              'x-webhookURL': params[:webhook_url]
+            },
+            channelType: 'webhooks',
+            clientCorrelator: Cpaas.api.client_correlator
+          }
+        }
+      }
+
+      response = Cpaas.api.send_request("#{base_url}/channels", options, :post)
+
+      process_response(response) do |res|
+        channel = res.dig(:notification_channel)
+
+        {
+          channel_id: channel[:callback_url],
+          webhook_url: channel[:channel_data][:x_webhook_url],
+          channel_type: channel[:channel_type]
+        }
+      end
+    end
+
+    private
+
+    def self.base_url
+      "/cpaas/notificationchannel/v1/#{Cpaas.api.user_id}"
+    end
+  end
+end

data/lib/cpaas-sdk/resources/twofactor.rb

@@ -0,0 +1,136 @@
+require 'cpaas-sdk/util'
+
+module Cpaas
+  ##
+  # CPaaS provides Authentication API where a two-factor authentication (2FA) flow can be implemented by using that.
+  # Sections below describe two sample use cases, two-factor authentication via SMS and two-factor authentication via e-mail
+  #
+
+  class Twofactor
+    #
+    # Create a new authentication code.
+    #
+    # @param params [Hash]
+    # @option params [String|Array[string]] :destination_address Destination address of the authentication code being sent. For sms type authentication codes, it should contain a E164 phone number. For e-mail type authentication codes, it should contain a valid e-mail address.
+    # @option params [String] :message Message text sent to the destination, containing the placeholder for the code within the text. CPaaS requires to have *{code}* string within the text in order to generate a code and inject into the text. For email type code, one usage is to have the *{code}* string located within the link in order to get a unique link.
+    # @option params [String] :method ('sms') +optional+ Type of the authentication code delivery method, sms and email are supported types. Possible values: sms, email
+    # @option params [Number] :expiry (120) +optional+ Lifetime duration of the code sent in seconds. This can contain values between 30 and 3600 seconds.
+    # @option params [Number] :length (6) +optional+ Length of the authentication code tha CPaaS should generate for this request. It can contain values between 4 and 10.
+    # @option params [String] :type ('numeric') +optional+ Type of the code that is generated. If not provided, default value is numeric. Possible values: numeric, alphanumeric, alphabetic
+    #
+    def self.send_code(params = {})
+      address = (params[:destination_address].is_a? String) ? [ params[:destination_address] ] : params[:destination_address]
+
+      options = {
+        body: {
+          code: {
+            address: address,
+            method: params[:method] || 'sms',
+            format: {
+              length: params[:length] || 6,
+              type: params[:type] || 'numeric'
+            },
+            expiry: params[:expiry] || 120,
+            message: params[:message]
+          }
+        }
+      }
+
+      response = Cpaas.api.send_request("#{base_url}/codes", options, :post)
+
+      process_response(response) do |res|
+        {
+          code_id: id_from(res.dig(:code, :resource_url))
+        }
+      end
+    end
+
+    #
+    # Verifying authentication code
+    #
+    # @param params [Hash]
+    # @option params [String] :code_id ID of the authentication code.
+    # @option params [String] :verification_code Code that is being verified
+    #
+    def self.verify_code(params = {})
+      options = {
+        body: {
+          code: {
+            verify: params[:verification_code]
+          }
+        }
+      }
+
+      response = Cpaas.api.send_request("#{base_url}/codes/#{params[:code_id]}/verify", options, :put)
+
+      process_response(response) do |res|
+        if res[:status_code] == 204
+          {
+            verified: true,
+            message: 'Success'
+          }
+        else
+          {
+            verified: false,
+            message: 'Code invalid or expired'
+          }
+        end
+      end
+    end
+
+    ##
+    # Resending the authentication code via same code resource, invalidating the previously sent code.
+    #
+    # @param params [Hash]
+    # @option params [String|Array[string]] :destination_address Destination address of the authentication code being sent. For sms type authentication codes, it should contain a E164 phone number. For e-mail type authentication codes, it should contain a valid e-mail address.
+    # @option params [String] :message Message text sent to the destination, containing the placeholder for the code within the text. CPaaS requires to have *{code}* string within the text in order to generate a code and inject into the text. For email type code, one usage is to have the *{code}* string located within the link in order to get a unique link.
+    # @option params [String] :code_id ID of the authentication code.
+    # @option params [String] :method ('sms') +optional+ Type of the authentication code delivery method, sms and email are supported types. Possible values: sms, email
+    # @option params [Number] :expiry (120) +optional+ Lifetime duration of the code sent in seconds. This can contain values between 30 and 3600 seconds.
+    # @option params [Number] :length (6) +optional+ Length of the authentication code tha CPaaS should generate for this request. It can contain values between 4 and 10.
+    # @option params [String] :type ('numeric') +optional+ Type of the code that is generated. If not provided, default value is numeric. Possible values: numeric, alphanumeric, alphabetic
+    #
+    def self.resend_code(params = {})
+      address = (params[:destination_address].is_a? String) ? [ params[:destination_address] ] : params[:destination_address]
+
+      options = {
+        body: {
+          code: {
+            address: address,
+            method: params[:method] || 'sms',
+            format: {
+              length: params[:length] || 6,
+              type: params[:type] || 'numeric'
+            },
+            expiry: params[:expiry] || 120,
+            message: params[:message]
+          }
+        }
+      }
+
+      response = Cpaas.api.send_request("#{base_url}/codes/#{params[:code_id]}", options, :put)
+
+      process_response(response) do |res|
+        {
+          code_id: id_from(res.dig(:code, :resource_url))
+        }
+      end
+    end
+
+    #
+    # Delete authentication code resource.
+    #
+    # @param [Hash] params
+    # @option params [String] :code_id ID of the authentication code.
+    #
+    def self.delete_code(params = {})
+      Cpaas.api.send_request("#{base_url}/codes/#{params[:code_id]}", {}, :delete)
+    end
+
+    private
+
+    def self.base_url
+      "/cpaas/auth/v1/#{Cpaas.api.user_id}"
+    end
+  end
+end

data/lib/cpaas-sdk/util.rb

@@ -0,0 +1,93 @@
+def process_response(res, remove_outer_key = true)
+  if res.key? :exception_id
+    response = res
+  elsif res && res.dig(:__for_test__)
+    custom_body = res.dig(:custom_body)
+    reject(res, :custom_body)
+
+    if !res.dig(:custom_body).nil? && block_given?
+      custom_body = yield res[:custom_body]
+    end
+
+    response = custom_body.nil? ? res : res.merge(custom_body)
+  elsif block_given?
+    response = yield res
+  elsif remove_outer_key
+    topLevelKey = res.keys.first
+    response = res[topLevelKey].as_json
+  else
+    response = res
+  end
+
+  response
+end
+
+def compose_error_from(err_response)
+  error_obj = deep_find(err_response, :message_id)
+
+  if (error_obj)
+    message = error_obj[:text]
+
+    error_obj[:variables].each_with_index { |variable, index| message.gsub!("%#{index + 1}", variable) }
+
+    response = {
+      name: error_obj[:name],
+      exception_id: error_obj[:message_id],
+      message: message
+    }
+  else
+    response = {
+      name: err_response.keys.first,
+      exception_id: 'Unknown',
+      message: err_response[:message]
+    }
+  end
+end
+
+def id_from (url)
+  url.split('/').last
+end
+
+def deep_find(object, key, parentKey = '')
+  result = nil
+
+  if object.respond_to?(:key?) && object.key?(key)
+    object[:name] = parentKey
+    return object
+  elsif object.is_a? Enumerable
+    object.each do |k, v|
+      result = deep_find(v, key, k)
+
+      return result if !result.nil?
+    end
+  end
+
+  return result
+end
+
+def convert_hash_keys(value)
+  case value
+    when Array
+      value.map { |v| convert_hash_keys(v) }
+    when Hash
+      Hash[value.map { |k, v| [underscore_key(k), convert_hash_keys(v)] }]
+    else
+      value
+   end
+end
+
+def underscore_key(k)
+  underscore(k.to_s).to_sym
+end
+
+def underscore(str)
+  str.gsub(/::/, '/').
+  gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+  gsub(/([a-z\d])([A-Z])/,'\1_\2').
+  tr("-", "_").
+  downcase
+end
+
+def reject(obj, key)
+  obj.reject { |k,v| k == key }
+end

data/lib/cpaas-sdk/version.rb

@@ -0,0 +1,3 @@
+module Cpaas
+  VERSION = '1.0.0'
+end

data/tutorials/2FA.md

@@ -0,0 +1,109 @@
+# Two-Factor Authentication
+$KANDY$ provides [Authentication API](/developer/references/ruby/1.0.0#twofactor-send-code) using which a two-factor authentication (2FA) flow can be implemented.
+
+Sections below describe two sample use cases, two-factor authentication via SMS and two-factor authentication via e-mail.
+
+## Two-Factor Authentication via SMS
+The following diagram explains a sample use case and its logical flow for two-factor authentication via SMS:
+
+![2FA via SMS flow](2fa-flow.png)
+
+1. User opens the MyApp web page, enters credentials, and clicks login
+2. MyApp web server initiates two-factor authentication via SMS flow, sends request to $KANDY$ to send validation code
+3. User receives the code via SMS
+4. User enters the code on MyApp web page
+5. User submits the code
+6. MyApp web server sends validation request to $KANDY$ with the code user entered and receives the result
+7. MyApp web page takes the action based on the result
+
+Your $KANDY$ admin can purchase SMS DID and assign to the MyApp project, so that the two-factor authentication SMS sent to app users always has the same originating number seen on the phone. Otherwise, the number seen on app users' phones may differ per transaction.
+
+First, MyApp web server sends request to send a two-factor authentication code:
+
+```ruby
+Cpaas::Twofactor.send_code({
+  destination_address: '+12292990344',
+  method: 'sms',
+  expiry: 360,
+  message: 'Your code is {code}',
+  length: 6,
+  type: 'alphanumeric'
+})
+```
+The response contains `code_id` which is a unique ID needed for `verify_code`. The response object can look something like this:
+```ruby
+{
+  code_id: '1fc8907-d336-4707-ad3c'
+}
+```
+
+Walking through the method parameters:
+
++ `destination_address` is required with a routable destination number in E.164 format, either with tel schema or not. For v1, only one address is supported.
++ `method` is mandatory and must have `sms` for verification via SMS flow.
++ `expiry` indicates the desired period of time in seconds that the code will be valid on $KANDY$. It is optional having default value as 120 seconds, while application can ask for values between 30 and 3600 seconds.
++ `message` is required with a `{code}` string within the text so that $KANDY$ can replace that with the real code generated, and send it as the SMS content.
++ `length` indicates the desired length of the code, default value is 6 and application can request for values between 4 and 10.
++ `type` indicates the desired type of the code from the set `numeric`, `alphanumeric`, `alphabetic`. Default is `numeric`.
+
+The `code_id` in the `response` object should be used for verifying the user’s verification code or resending a new verification code to the user.
+
+To verify the code, here is an example:
+
+```ruby
+Cpaas::Twofactor.verify_code({
+  code_id: '1fc8907-d336-4707-ad3c',
+  verification_code: '123456'
+})
+```
+In the response, `verified: true` means code is verified and removed from $KANDY$, while `verified: false` indicates the code is not valid.
+
+A successful verification will have the following response:
+```ruby
+{
+  verified: true,
+  message: 'Success'
+}
+```
+An invalid/failed verification will have the following response:
+```ruby
+{
+  verified: false,
+  message: 'Code expired or invalid'
+}
+```
+
+## Two-Factor Authentication via E-mail
+A similar flow with the SMS section above can be implemented for e-mail verification.
+
+The following email code request example, requires insertion of the generated code within the link that the user is supposed to click and navigate to the application's web service:
+
+```ruby
+Cpaas::Twofactor.send_code({
+  destination_address: 'johndev@someemail.com',
+  method: 'email',
+  length: 10,
+  type: 'alphanumeric',
+  expiry: 3600,
+  message: 'Here is your code: {code}'
+})
+```
+The response contains `code_id` which is a unique ID needed for `verify_code`. The response object can look something like this:
+```ruby
+  {
+    code_id: '1fc8907-d336-4707-ad3c'
+  }
+```
+
+As can be seen within the example, `method` parameter has `email` value, while `destination_address` field includes a destination e-mail address. For v1, only plain text is supported.
+
+Verification procedure for two-factor authentication via e-mail is same with two-factor authentication via SMS as described in previous section.
+
+## Additional Operations
+The `code` can be:
+
++ Resend using the same resource, which "invalidates" the previously sent code and triggers a new SMS or email containing a new code.
++ Deleted explicitly if desired (deletion operation does not block the previously started send operation)
+
+## References
+For all two factor authentication related method details, refer to [Two Factor Authentication](/developer/references/ruby/1.0.0#twofactor-send-code).