cubits 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3e681c887f584d39661aeadad10c1e297abad0ab
-  data.tar.gz: 1cc90230a6bfae073d6ec6ba23a314fcf518f4f6
+  metadata.gz: d337170a2395378547f050001109b90f2387bb58
+  data.tar.gz: 8b505f0edeb55b9a5c1a518f8dad387a9e167f42
 SHA512:
-  metadata.gz: ef1a5b930c12ab8dc276eeb8a56552c2a616fd88f773b1d0711cb2318d1a4ff496d1ea4b9a8d63c759a7241a61b582b2354c184f13305b40181ebb4d2b53323d
-  data.tar.gz: acc7922ad9ed67ccba6a1c5525cc0459525dc75a8c7531a07b62032d4893063bfcba361e3f4c38b862ab396b14a39bb609eb966fcccb39f665015d3ebb7cd75b
+  metadata.gz: b2c5625fe8ae836a0fb521e2b423eed6af3eca3c95d44988b8497bb2710201ea0a176ef81cabd2155c3ff04deda7f164d11fab2dc4d8f81b6a9b41de373dbc88
+  data.tar.gz: 9327d05bb549d9478ea3d03112fc98d4dfa9cde73c3f1dc83e9fab0e054e15bea76bc098f21cc9c3291330645ab5cb3b45b99884586418b164f900d96088d31b

data/CHANGES.md

@@ -1,3 +1,13 @@
+# 0.5.0
+
+* Added Cubits::Channel::Tx collection implementation.
+Use `channel.txs.all` to retrieve all channel transactions,
+`channel.txs.find()` to find a single transaction.
+
+* Added Cubits::Callback module for callback signature verification
+and resource instantiation.
+Cubits::Invoice, Cubits::Channel, Cubits::Channel::Tx expose .from_callback() method.
+
 # 0.4.0
 
 Enforcing strict server SSL certificate checks, to prevent MitM attacks

data/README.md

@@ -145,6 +145,49 @@ channel.update(reference: "CHAN_192357")
 channel.reference # => "CHAN_192357"
 ```
 
+#### #txs
+
+Returns channel transactions as a collection of `Cubits::Channel::Tx` objects.
+
+The collection exposes methods `.all` and `.find()`:
+
+Listing all channel transactions:
+```ruby
+channel = Cubits::Channel.find("d17ad6c96f83162a2764ecd4739d7ab2")
+
+channel.txs.all # => [{"tx_ref_code"=>"YYWZN", ...}, ...]
+```
+
+Retrieving a channel transaction with given *tx_ref_code*:
+```ruby
+channel = Cubits::Channel.find("d17ad6c96f83162a2764ecd4739d7ab2")
+tx = channel.txs.find("YYWZN")
+tx.class # => Cubits::Channel::Tx
+
+tx # => {"tx_ref_code"=>"YYWZN", "state"=>"pending", ... }
+```
+
+### Cubits::Channel::Tx
+
+This resource represents a merchant channel transaction. An instance of `Cubits::Channel::Tx` should be obtained from a `channel.txs` collection or instantiated
+from a callback.
+
+#### #channel
+
+Returns the `Cubits::Channel` object, owning this transaction:
+
+```ruby
+tx = Cubits::Channel::Tx.from_callback(
+  cubits_callback_id: 'ABCDEFGH',
+  cubits_key: '7287ba0902...',
+  cubits_signature: '7d89c35c2...',
+  body: '{"tx_ref_code": "YYWZN", "state": "pending", ...}'
+)
+
+tx.channel # => {"receiver_currency"=>"EUR", "name"=>nil, ...}
+tx.channel.class # => Cubits::Channel
+```
+
 ## Accounts
 
 Your Cubits accounts are represented by the `Cubits::Account` class, which is a descendant of [Hashie::Mash](https://github.com/intridea/hashie#mash), so it's a Hash with a method-like access to its elements:
@@ -256,5 +299,98 @@ Cubits.send_money amount: '1.5000000', address: '3BnYBqPnGtRz2cfcnhxFKy3JswU3biM
 
 On success `.send_money` creates a transaction and returns its reference code.
 
+## Callbacks
+
+Cubits Merchant API provides an authentication mechanism for callback requests it posts to the merchant specified URL's. That way merchants can be sure, that the data posted within a callback comes from a trusted source.
+
+The callback authentication is described in detail in the [Cubits Help Center](https://cubits.com/help) Developer's section.
+
+The `cubits` ruby gem provides a `Cubits::Callback` class for easy and straightforward callback verification and parsing.
+
+### .from_params()
+
+Provided all relevant headers and body are extracted from the callback request, `from_params()` method validates the signature, parses request body and returns passed data wrapped in a given `Cubits::Resource`-based class object.
+
+Signature of the callback is verified using key+secret pair, passed to `Cubits.configure(...)` beforehand.
+
+#### Parameters
+name                 | type    | description
+---------------------|---------|---------------------
+cubits_callback_id   | String  | Value of the CUBITS_CALLBACK_ID header
+cubits_key           | String  | Value of the CUBITS_KEY header
+cubits_signature     | String  | Value of the CUBITS_SIGNATURE header
+body                 | String  | Callback request body as a String
+resource_class       | Resource, nil | (optional) subclass of `Cubits::Resource` (e.g. `Cubits::Invoice`). If specified, an object of that class is instantiated and initialized with the parsed request body. (default: nil)
+allow_insecure       | Boolean | (optional) Allow insecure, unsigned callbacks (default: false)
+
+#### Returns
+
+An instance of a given `resource_class` or a `Hash`.
+
+#### Errors
+
+`Cubits::InvalidSignature` is raised if either `cubits_key` passed with the callback
+does not match the preconfigured API key, or the `cubits_signature` does not match
+the signature calculated from a preconfigured API key+secret pair.
+
+`Cubits::InsecureCallback` is raised if the callback is unsigned, and `allow_insecure` option is *false*.
+
+#### Examples
+
+Validate and parse callback into a plain `Hash`:
+```ruby
+data = Cubits::Callback.from_params(
+  cubits_callback_id: 'ABCDEFGH',
+  cubits_key: '7287ba0902...',
+  cubits_signature: '7d89c35c2...',
+  body: '{"attr1": 123, "attr2": "hello"}'
+)
+
+data # => { 'attr1' => 123, 'attr2' => 'hello' }
+data.class # => Hash
+```
+
+Validate and parse callback into a `Cubits::Invoice` object:
+```ruby
+invoice = Cubits::Callback.from_params(
+  cubits_callback_id: 'ABCDEFGH',
+  cubits_key: '7287ba0902...',
+  cubits_signature: '7d89c35c2...',
+  body: '{"attr1": 123, "attr2": "hello"}',
+  resource_class: Cubits::Invoice
+)
+
+invoice # => { 'attr1' => 123, 'attr2' => 'hello' }
+invoice.class # => Cubits::Invoice
+```
+
+Process an insecure, unsigned callback:
+```ruby
+data = Cubits::Callback.from_params(
+  cubits_callback_id: 'ABCDEFGH',
+  body: '{"attr1": 123, "attr2": "hello"}',
+  allow_insecure: true
+)
+
+data # => { 'attr1' => 123, 'attr2' => 'hello' }
+```
+
+### Cubits::Resource.from_callback()
+
+`Cubits::Invoice`, `Cubits::Channel` and `Cubits::Channel::Tx` expose
+a helper method: `.from_callback()` which can be used to validate callback and instantiate a resource object in one go:
+
+```ruby
+invoice = Cubits::Invoice.from_callback(
+  cubits_callback_id: 'ABCDEFGH',
+  cubits_key: '7287ba0902...',
+  cubits_signature: '7d89c35c2...',
+  body: '{"attr1": 123, "attr2": "hello"}'
+)
+
+invoice # => { 'attr1' => 123, 'attr2' => 'hello' }
+invoice.class # => Cubits::Invoice
+```
+
 ----
 

data/lib/cubits.rb

@@ -5,10 +5,12 @@ require 'cubits/connection'
 require 'cubits/errors'
 require 'cubits/helpers'
 require 'cubits/resource'
+require 'cubits/resource_collection'
 require 'cubits/invoice'
 require 'cubits/account'
 require 'cubits/quote'
 require 'cubits/channel'
+require 'cubits/callback'
 
 module Cubits
   extend Cubits::Helpers
@@ -23,14 +25,24 @@ module Cubits
   # @param params[:secret] [String] API secret obtained from Cubits
   #
   def self.configure(params = {})
-    @connection = Connection.new(params)
+    @connections ||= {}
+    @connections[params[:key]] = Connection.new(params)
   end
 
-  #
   # Returns configured Connection object
   #
-  def self.connection
-    @connection || fail('Cubits connection is not configured')
+  # @param key [String] (optional) Cubits API key of the configured connection
+  #
+  # @return [Connection] Connection object matching the requested Cubits API key or first
+  #                      configured connection
+  #
+  def self.connection(key = nil)
+    @connections ||= {}
+    c = key ? @connections[key] : @connections.values.first
+    unless c
+      fail ConnectionError, "Cubits connection is not configured for key #{key || '(default)'}"
+    end
+    c
   end
 
   # Returns current Logger object
@@ -60,10 +72,11 @@ module Cubits
     fail ArgumentError, 'URI is expected as new_base_url' unless new_base_url.is_a?(URI)
     @base_url = new_base_url
   end
+
   # Resets all internal states
   #
   def self.reset
-    @connection = nil
+    @connections = {}
     @logger = nil
   end
 end # module Cubits

data/lib/cubits/callback.rb

@@ -0,0 +1,68 @@
+module Cubits
+  class Callback
+    #
+    # Processes callback request parsed into separate params
+    # and instantiates a resource object on success.
+    #
+    # @param params [Hash]
+    # @param params[:cubits_callback_id] [String] Value of the CUBITS_CALLBACK_ID header
+    # @param params[:cubits_key] [String] Value of the CUBITS_KEY header
+    # @param params[:cubits_signature] [String] Value of the CUBITS_SIGNATURE header
+    # @param params[:body] [String] Request body
+    # @param params[:resource_class] [Resource,nil] (optional) Instantiate a Resource based object (default: nil)
+    #   and initialize it with parsed request body. If not specified, returns parsed body as a plain Hash
+    # @param params[:allow_insecure] [Boolean] (optional) Allow insecure, unsigned callbacks (default: false)
+    #
+    # @return [Resource,Hash]
+    #
+    # @raise [InvalidSignature]
+    # @raise [InsecureCallback]
+    #
+    def self.from_params(params = {})
+      result = from_params_to_hash(params)
+      params[:resource_class] ? params[:resource_class].new(result) : result
+    end
+
+    private
+
+    def self.from_params_to_hash(params)
+      validate_params!(params)
+      if params[:cubits_signature] && !params[:cubits_signature].empty?
+        validate_signature!(params)
+      elsif !params[:allow_insecure]
+        fail InsecureCallback, 'Refusing to process an unsigned callback for security reasons'
+      end
+      JSON.parse(params[:body])
+    end
+
+    def self.validate_params!(params)
+      unless params[:cubits_callback_id].is_a?(String)
+        fail ArgumentError, 'String is expected as :cubits_callback_id'
+      end
+      if params[:cubits_key] && !params[:cubits_key].is_a?(String)
+        fail ArgumentError, 'String is expected as :cubits_key'
+      end
+      if params[:cubits_signature] && !params[:cubits_signature].is_a?(String)
+        fail ArgumentError, 'String is expected as :cubits_signature'
+      end
+      fail ArgumentError, 'String is expected as :body' unless params[:body].is_a?(String)
+      if params[:resource_class]
+        unless params[:resource_class].is_a?(Class) && params[:resource_class] < Resource
+          fail ArgumentError, 'Resource based class is expected as :resource_class'
+        end
+      end
+      true
+    end
+
+    def self.validate_signature!(params)
+      connection = Cubits.connection(params[:cubits_key])
+      msg = params[:cubits_callback_id] + OpenSSL::Digest::SHA256.hexdigest(params[:body])
+      unless connection.sign_message(msg) == params[:cubits_signature]
+        fail InvalidSignature, 'Callback signature is invalid'
+      end
+      true
+    rescue ConnectionError => e
+      raise InvalidSignature, e.message
+    end
+  end # class Callback
+end

data/lib/cubits/channel.rb

@@ -1,6 +1,13 @@
 module Cubits
   class Channel < Resource
     path '/api/v1/channels'
-    expose_methods :create, :find, :reload, :update
+    expose_methods :create, :find, :reload, :update, :from_callback
+
+    has_many :txs, class_name: 'Channel::Tx'
+
+    class Tx < Resource
+      expose_methods :from_callback
+      belongs_to :channel
+    end
   end # class Channel
 end

data/lib/cubits/connection.rb

@@ -38,6 +38,16 @@ module Cubits
       request(:post, path, encoded_data)
     end
 
+    # Signs the message with preconfigured secret
+    #
+    # @param msg [String]
+    #
+    # @return [String] Calculated signature
+    #
+    def sign_message(msg)
+      OpenSSL::HMAC.hexdigest('sha512', @secret, msg)
+    end
+
     private
 
     # Sends a request to the API
@@ -119,7 +129,7 @@ module Cubits
     #
     def sign_request(path, nonce, request_data)
       msg = path + nonce.to_s + OpenSSL::Digest::SHA256.hexdigest(request_data)
-      signature = OpenSSL::HMAC.hexdigest('sha512', @secret, msg)
+      signature = sign_message(msg)
       Cubits.logger.debug 'sign_request: ' \
         "path=#{path} nonce=#{nonce} request_data=#{request_data} msg=#{msg} signature=#{signature}"
       signature

data/lib/cubits/errors.rb

@@ -24,4 +24,11 @@ module Cubits
 
   class InternalServerError < ServerError
   end
+
+  # Cubits client errors
+  class InvalidSignature < StandardError
+  end
+
+  class InsecureCallback < StandardError
+  end
 end # module Cubits

data/lib/cubits/invoice.rb

@@ -1,6 +1,6 @@
 module Cubits
   class Invoice < Resource
     path '/api/v1/invoices'
-    expose_methods :create, :find, :reload
+    expose_methods :create, :find, :reload, :from_callback
   end # class Invoice
 end

data/lib/cubits/resource.rb

@@ -30,7 +30,7 @@ module Cubits
     # Returns API path to resource
     #
     def self.path_to(resource_or_id = nil)
-      fail ArgumentError, "Resource path is not set for #{self.class.name}" unless @path
+      fail ArgumentError, "Resource path is not set for #{name}" unless @path
       if resource_or_id.is_a?(Resource)
         "#{@path}/#{resource_or_id.id}"
       elsif resource_or_id
@@ -40,6 +40,35 @@ module Cubits
       end
     end
 
+    # Associations
+    def self.has_many(association_name, params = {})
+      define_method(association_name) do
+        association = instance_variable_get("@#{association_name}")
+        return association if association
+        class_name = params[:class_name] || association_name.to_s.capitalize.sub(/s$/, '')
+        resource = Cubits.const_get(class_name) || fail("Failed to find class #{class_name}")
+        association = ResourceCollection.new(
+          path: self.class.path_to(id) + '/' + association_name.to_s,
+          resource: resource,
+          expose_methods: params[:expose_methods] || [:find, :all]
+        )
+        instance_variable_set("@#{association_name}", association)
+        association
+      end
+    end
+
+    def self.belongs_to(association_name, params = {})
+      define_method(association_name) do
+        association_id = send :"#{association_name}_id"
+        unless association_id
+          fail ArgumentError, "No #{association_name}_id attribute is defined for #{self}"
+        end
+        class_name = params[:class_name] || association_name.to_s.capitalize
+        resource = Cubits.const_get(class_name) || fail("Failed to find class #{class_name}")
+        resource.find(association_id)
+      end
+    end
+
     # Loads collection of resources
     #
     # @return [Array<Resource>]
@@ -64,6 +93,28 @@ module Cubits
       nil
     end
 
+    # Processes callback request parsed into separate params
+    # and instantiates a resource object on success.
+    #
+    # @param params [Hash]
+    # @param params[:cubits_callback_id] [String] Value of the CUBITS_CALLBACK_ID header
+    # @param params[:cubits_key] [String] Value of the CUBITS_KEY header
+    # @param params[:cubits_signature] [String] Value of the CUBITS_SIGNATURE header
+    # @param params[:body] [String] Request body
+    # @param params[:allow_insecure] [Boolean] (optional) Allow insecure, unsigned callbacks (default: false)
+    #
+    # @return [Resource,Hash]
+    #
+    # @raise [InvalidSignature]
+    # @raise [InsecureCallback]
+    #
+    def self.from_callback(params)
+      unless exposed_method?(:from_callback)
+        fail NoMethodError, "Resource #{name} does not expose .from_callback"
+      end
+      Cubits::Callback.from_params(params.merge(resource_class: self))
+    end
+
     # Reloads resource
     #
     def reload

data/lib/cubits/resource_collection.rb

@@ -0,0 +1,69 @@
+module Cubits
+  class ResourceCollection
+    attr_reader :path, :resource
+
+    def initialize(params = {})
+      @path = params[:path]
+      @resource = params[:resource]
+      @exposed_methods = params[:expose_methods]
+    end
+
+    # By convention collection name for the resource is the last part of the path
+    #
+    def collection_name
+      path.split('/').last
+    end
+
+    # @return true if the method is exposed by this resource
+    #
+    def exposed_method?(method_name)
+      (@exposed_methods || []).include?(method_name)
+    end
+
+
+    # Loads collection of resources
+    #
+    # @return [Array<Resource>]
+    #
+    def all
+      fail NoMethodError, "Resource #{name} does not expose .all" unless exposed_method?(:all)
+      Cubits.connection.get(path_to, per_page: 1000)[collection_name].map { |r| resource.new r }
+    rescue NotFound
+      nil
+    end
+
+    # Loads resource
+    #
+    # @param id [String]
+    #
+    # @return nil if resource is not found
+    #
+    def find(id)
+      fail NoMethodError, "Resource #{name} does not expose .find" unless exposed_method?(:find)
+      resource.new Cubits.connection.get(path_to(id))
+    rescue NotFound
+      nil
+    end
+
+    # Returns API path to resource
+    #
+    def path_to(resource_or_id = nil)
+      fail ArgumentError, "Resource path is not set for #{self}" unless path
+      if resource_or_id.is_a?(Resource)
+        "#{path}/#{resource_or_id.id}"
+      elsif resource_or_id
+        "#{path}/#{resource_or_id}"
+      else
+        path
+      end
+    end
+
+    def name
+      "Collection of #{resource.name}"
+    end
+
+    def to_s
+      "<#{self.class.name}:<#{resource.name}>:#{path}>"
+    end
+  end # class ResourceCollection
+end # module Cubits

data/lib/cubits/version.rb

@@ -1,3 +1,3 @@
 module Cubits
-  VERSION = '0.4.0'
+  VERSION = '0.5.0'
 end

data/spec/lib/cubits/callback_spec.rb

@@ -0,0 +1,82 @@
+require 'spec_helper'
+
+describe Cubits::Callback do
+  let(:key) { '7287ba0902461025b01d5b99e4679018' }
+  let(:secret) { '93yJJ8LBDe3zNSewHBdX1XIQDjCMDIn0EKNnXrd3kfzL72fvLz99uKnXFLYuCfkt' }
+  let!(:configured_connection) do
+    Cubits.configure(key: key, secret: secret)
+  end
+
+  let(:cubits_key) { '7287ba0902461025b01d5b99e4679018' }
+  let(:cubits_callback_id) { 'ABCDEFGH' }
+  let(:cubits_signature) { '7d89c35c2e0840867f63b77ea575050db21a134b674d4a38f1e255518efb5b81383442cd9a888dca86dfe3e43a0769525088aac3efed3102a6b14bd1446f14a1' }
+  let(:body) { '{"attr1": 123, "attr2": "hello"}' }
+  let(:resource_class) { Cubits::Invoice }
+  let(:allow_insecure) { nil }
+
+  context '.from_params(),' do
+    let(:params) do
+      {
+        cubits_key: cubits_key,
+        cubits_callback_id: cubits_callback_id,
+        cubits_signature: cubits_signature,
+        body: body,
+        resource_class: resource_class,
+        allow_insecure: allow_insecure
+      }
+    end
+
+    subject { described_class.from_params(params) }
+
+    it 'raises no errors for valid params' do
+      expect { subject }.to_not raise_error
+    end
+
+    it 'returns a Resource instance' do
+      expect(subject).to be_a Cubits::Resource
+    end
+
+    it 'uses the request body to initialize the Resource instance' do
+      expect(subject.attr1).to eq 123
+      expect(subject.attr2).to eq 'hello'
+    end
+
+    context 'when callback is NOT signed,' do
+      let(:cubits_key) { nil }
+      let(:cubits_signature) { nil }
+
+      it 'refuses to process callback' do
+        expect { subject }.to raise_error(Cubits::InsecureCallback)
+      end
+
+      context 'and insecure callbacks are explicitly allowed,' do
+        let(:allow_insecure) { true }
+        it 'processes the unsigned callback' do
+          expect { subject }.to_not raise_error
+        end
+      end # and insecure callbacks are explicitly allowed
+    end # when callback is NOT signed
+
+    context 'when callback has an invalid signature,' do
+      let(:cubits_signature) { 'blablabla' }
+      it 'refuses to process callback' do
+        expect { subject }.to raise_error(Cubits::InvalidSignature)
+      end
+    end # when callback has an invalid signature
+
+    context 'when callback has an invalid API key,' do
+      let(:cubits_key) { 'blablabla' }
+      it 'refuses to process callback' do
+        expect { subject }.to raise_error(Cubits::InvalidSignature)
+      end
+    end # when callback has an invalid API key
+
+    context 'when no :resource_class is specified,' do
+      let(:resource_class) { nil }
+      it 'returns a Hash' do
+        expect(subject).to be_a Hash
+        expect(subject).to eq({ 'attr1' => 123, 'attr2' => 'hello' })
+      end
+    end # when no :resource_class is specified
+  end # .from_params()
+end # describe Cubits::Connection

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cubits
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Alex Kukushkin
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-03-25 00:00:00.000000000 Z
+date: 2015-04-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: http
@@ -116,6 +116,7 @@ files:
 - cubits.gemspec
 - lib/cubits.rb
 - lib/cubits/account.rb
+- lib/cubits/callback.rb
 - lib/cubits/channel.rb
 - lib/cubits/connection.rb
 - lib/cubits/errors.rb
@@ -123,8 +124,10 @@ files:
 - lib/cubits/invoice.rb
 - lib/cubits/quote.rb
 - lib/cubits/resource.rb
+- lib/cubits/resource_collection.rb
 - lib/cubits/version.rb
 - spec/lib/cubits/account_spec.rb
+- spec/lib/cubits/callback_spec.rb
 - spec/lib/cubits/channel_spec.rb
 - spec/lib/cubits/connection_spec.rb
 - spec/lib/cubits/helpers_spec.rb
@@ -158,6 +161,7 @@ specification_version: 4
 summary: Ruby client for Cubits Merchant API
 test_files:
 - spec/lib/cubits/account_spec.rb
+- spec/lib/cubits/callback_spec.rb
 - spec/lib/cubits/channel_spec.rb
 - spec/lib/cubits/connection_spec.rb
 - spec/lib/cubits/helpers_spec.rb