wix-apps 0.0.3 → 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a314236e1cdbd6379c6bf7b4a9731508f1f29751
+  data.tar.gz: a8e6f86a69f82c7c36deef8aa4efb8d2a923d4d8
+SHA512:
+  metadata.gz: 222b61a2e958fecd8e2e0eb685a4a17e15601b476c067311f436251292aa876ba5f134eab6509f1ef015e2b45bb3008f5612d18419a5bebfe1f8c18ec4a7ed88
+  data.tar.gz: 585213545bda5d1786852813c2a55d8c9758effbcb7f91210d84c9ee413eba214ca1be50d0ea277a2b3c667cb3bcac35d395c5c6e9635a73d213ee38ae81d80a

data/.rspec

@@ -1,2 +1,2 @@
 --color
---format documentation
+--format documentation

data/.ruby-gemset

@@ -0,0 +1 @@
+wix-apps

data/.ruby-version

@@ -0,0 +1 @@
+2.0.0

data/.travis.yml

@@ -1,12 +1,16 @@
+before_script:
+  - uname -a
+before_install:
+  - gem install bundler
 language: ruby
 rvm:
-  - 1.9.3
-  - 1.9.2
-  - jruby-19mode
-  - rbx-19mode
+  - 2.0
+  - 2.1
+  - 2.2
+  - 2.3
   - ruby-head
   - jruby-head
-bundler_args: --without development
 notifications:
   email:
-    - gregory@wix.com
+    - gregory@wix.com
+    - niklas@bichinger.de

data/Gemfile

@@ -1,11 +1,9 @@
 source 'https://rubygems.org'
 
 gemspec
-gemspec :development_group => :gem_dev
 
 group :development do
   gem 'ruby-debug', :platforms => :mri_18
   gem 'debugger', :platforms => :mri_19
   gem 'guard-rspec'
 end
-

data/Guardfile

@@ -1,5 +1,5 @@
 guard 'rspec' do
   watch(%r{^spec/.+_spec\.rb$})
   watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
-  watch('spec/spec_helper.rb')  { "spec" }
+  watch('spec/spec_helper.rb')  { 'spec' }
 end

data/README.md

@@ -1,14 +1,16 @@
 # Wix::Apps
 [![Build Status](https://secure.travis-ci.org/wix/wix-apps-ruby.png?branch=master)](http://travis-ci.org/wix/wix-apps-ruby)
 
-Rack middleware use with "Third Party Applications".
-It checks signature and passes the parsed_instance param to you application
+Rack middleware for use with "Third Party Applications" on the Wix platform.
+It handles the instance param passed by Wix requests for configurable paths. It checks the signature, parses the contents and passes a convenient Object to your application via env.
 
 ## Installation
 
+Important note: if you're using a pre-1.0.0-version of this gem, please be aware the API changed significantly. You will have to update some of your code. However, in versions >= 1.0.0 should be a corresponding method for anything from version 0.0.x.
+
 Add this line to your application's Gemfile:
 
-    gem 'wix-apps'
+    gem 'wix-apps', '~> 1.0.0'
 
 And then execute:
 
@@ -21,17 +23,71 @@ Or install it yourself as:
 ## Usage
 
 ### Any Rack Application
-Add Wix::Apps::SignedInstanceMiddleware as any other middleware.
+Add `Wix::Apps::SignedInstanceMiddleware` like any other middleware.
 ```ruby
-use Wix::Apps::SignedInstanceMiddleware, secured_paths: ['/yours', '/paths'], secret_key: 'secret_key'
+use Wix::Apps::SignedInstanceMiddleware, secret_key: 'secret_key',
+  secured_paths: ['/your', '/paths', %r{\A/wix/(auth|update)\z}]
 ```
 ### Rails
-In application.rb, add:
+In `application.rb`, add:
+```ruby
+config.middleware.use Wix::Apps::SignedInstanceMiddleware, secret_key: 'your-secret-key',
+  secured_paths: ['/wix']
+```
+
+In your controller handling a configured secured path, access the signed instance:
 ```ruby
-config.middleware.use Wix::Apps::SignedInstanceMiddleware,
-  secured_paths: ['/yours', '/paths'], secret_key: 'your-secret-key'
+class WixController < ApplicationController
+    def index
+        # retrieve Wix::Apps::SignedInstance object
+        instance = request.env['wix.instance']
+        
+        if instance.owner_permissions? 
+        ...
 ```
 
+### env['wix.instance']
+This WixApps middleware passes on a `Wix::Apps::SignedInstance` object through env['wix.instance']. The object has the following methods:
+
+Object method | Type | Description
+------------- | ---- | -----------
+instance_id | String | Required Wix instance property `instanceId`
+sign_date | DateTime | Required Wix instance property `signDate`
+uid | String | Optional Wix instance property `uid`
+permissions | String | Required Wix instance property `permissions`
+ip_and_port | String | Required Wix instance property `ipAndPort`
+vendor_product_id | String | Required Wix instance property `vendorProductId`
+aid | String | Required Wix instance property `aid`
+origin_instance_id | String | Optional Wix instance property `originInstanceId`
+site_owner_id | String | Required Wix instance property `siteOwnerId`
+owner_permissions? | Boolean | Indicates if instance user has owner (includes site administrators) permissions
+owner_logged_in? | Boolean | Indicates if instance user is the single owner of the site
+
+### Options
+
+#### secured_paths
+An Array of String- and Regexp-objects describing the paths to be secured by checking the Wix signed instance. On request, the path will be checked against every entry in this list. Strings are checked for equality, Regexps are matched (without additional conditions, so use \A and \z for start and end markers if you need them!). Keep in mind rack's paths always begin with a '/'.
+
+Example (secures '/auth_path', every path containing the string 'wix' and every path starting with '/wox/'):
+
+    secured_paths: ['/auth_path', /wix/, %r{\A/wox/}]
+ 
+#### paths
+Just like secured_paths, except these paths may or may not receive a Wix signed instance. If it does, the instance has to be valid. Calling `request.env('wix.instance')` in the controller may return nil (although the env key `'wix.instance'` exists) if there was no instance passed.
+ 
+#### secret_key
+A String containing your Wix app's secret key.
+
+Example:
+
+    secret_key: 'd245bbf8-57eb-49d6-aeff-beff6d82cd39'
+
+#### (optional) strict_properties
+A Boolean indicating if the instance properties of the Wix signed instance should be checked for completeness (true, default) or not (false). You should never need to set it to false and it's meant for debugging purposes only. 
+
+Example:
+
+    strict_properties: true
 
 ## Contributing
 

data/Rakefile

@@ -1,9 +1,13 @@
 #!/usr/bin/env rake
-require "bundler/gem_tasks"
+require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
 
 desc 'Default: run specs.'
 task :default => :spec
 
-desc "Run specs"
-RSpec::Core::RakeTask.new
+desc 'Run specs'
+RSpec::Core::RakeTask.new
+
+task :console do
+  exec 'irb -r wix-apps.rb -I ./lib'
+end

data/lib/wix-apps.rb

@@ -1,9 +1,8 @@
-require "wix-apps/version"
+require 'wix-apps/version'
 require 'wix-apps/signed_instance'
 require 'wix-apps/signed_instance_middleware'
 
 module Wix
   module Apps
-
   end
 end

data/lib/wix-apps/signed_instance.rb

@@ -4,62 +4,113 @@ require 'openssl'
 
 module Wix
   module Apps
-    class SignedInstanceParseError < Exception;end
-    class SignedInstanceNoSecretKey < Exception;end
-    # This class deal with Wix Signed Instance
-    # (http://dev.wix.com/display/wixdevelopersapi/The+Signed+Instance)
+
+    class SignedInstanceParseError < Exception
+    end
+
+    class SignedInstanceNoSecretKey < Exception
+    end
+
+    # This class deals with Wix Signed Instance
+    # (http://dev.wix.com/docs/display/DRAF/Using+the+Signed+App+Instance)
     #
     # Example:
     # si = SignedInstance.new('vrinSv2HB9tqbnJ....')
     class SignedInstance
-      attr_reader :raw_signed_instance, :instance_id, :sign_date, :uid,
-                  :permissions
 
-      def initialize(raw_signed_instance, options = {})
-        @raw_signed_instance = raw_signed_instance
-        @secret = options[:secret]
+      # maps required instance properties to object attributes
+      REQUIRED_PROPERTIES = {
+          'instanceId' => :instance_id,
+          'signDate' => :sign_date,
+          'permissions' => :permissions,
+          'ipAndPort' => :ip_and_port,
+          'vendorProductId' => :vendor_product_id,
+          'aid' => :aid,
+          'siteOwnerId' => :site_owner_id,
+      }
 
-        parse_signed_instance_data
-      end
+      # maps optional instance properties to object attributes
+      OPTIONAL_PROPERTIES = {
+          'uid' => :uid,
+          'originInstanceId' => :origin_instance_id,
+      }
 
-      # validates signature
-      def valid?
-        raise SignedInstanceNoSecretKey.new('Please provide secret key') if @secret.nil?
-        digest  = OpenSSL::Digest::Digest.new('sha256')
-        hmac_digest = OpenSSL::HMAC.digest(digest, @secret, @encoded_json)
-        my_signature = Base64.urlsafe_encode64(hmac_digest).gsub('=','')
+      PERMISSIONS_OWNER = 'OWNER'
+
+      attr_reader :raw_signed_instance, :strict_properties
+      attr_reader *(REQUIRED_PROPERTIES.values + OPTIONAL_PROPERTIES.values)
+
+      # @param [String] raw_signed_instance The "instance" parameter Wix sends with the request
+      # @param [Hash] options Options for
+      def initialize(raw_signed_instance, options={})
+        self.strict_properties = options[:strict_properties].nil? ? true : !!options[:strict_properties]
+        self.secret_key = options[:secret_key] || options[:secret] # :secret for backwards compatibility
+        raise SignedInstanceNoSecretKey.new('secret key must be provided') if secret_key.nil?
+        self.raw_signed_instance = raw_signed_instance
+        raise SignedInstanceParseError.new('invalid instance signature') unless instance_signature_valid?
 
-        return my_signature == @signature
+        initialize_from_signed_instance
       end
 
-      #Owner mode on?
-      def owner?
-        permissions == 'OWNER'
+      # owner or site collaborator visiting?
+      def owner_permissions?
+        permissions == PERMISSIONS_OWNER
+      end
+
+      # did the one single site owner log in?
+      def owner_logged_in?
+        # note: site owner id is required so we wouldn't have to check for nil,
+        # but this method's output can be very important and I'm paranoid. ;)
+        !site_owner_id.nil? && site_owner_id == uid
       end
 
       private
-      def parse_signed_instance_data
-        @signature, @encoded_json = raw_signed_instance.split('.', 2)
-        raise SignedInstanceParseError if @signature.nil? || @encoded_json.nil?
+
+      attr_accessor :secret_key
+      attr_writer :raw_signed_instance, :strict_properties
+      attr_writer *(REQUIRED_PROPERTIES.values + OPTIONAL_PROPERTIES.values)
+
+      # validates signature
+      def instance_signature_valid?
+        signature, encoded_json = (raw_signed_instance || '').split('.', 2)
+        return false if signature.nil? || encoded_json.nil?
+
+        digest = OpenSSL::Digest.new('sha256')
+        hmac_digest = OpenSSL::HMAC.digest(digest, secret_key, encoded_json)
+        my_signature = Base64.urlsafe_encode64(hmac_digest).gsub('=', '')
+
+        my_signature == signature
+      end
+
+      # initializes object attributes from parsed instance
+      def initialize_from_signed_instance
+        encoded_json = raw_signed_instance.split('.', 2).last
 
         # Need to add Base64 padding.
         # (http://stackoverflow.com/questions/4987772/decoding-facebooks-signed-request-in-ruby-sinatra)
-        padded_json = @encoded_json
-        padded_json += ('=' * (4 - @encoded_json.length % 4)) if padded_json.length % 4 != 0
+        padded_json = encoded_json
+        padded_json += ('=' * (4 - encoded_json.length % 4)) if padded_json.length % 4 != 0
 
         begin
-          @json = Base64.urlsafe_decode64(padded_json)
-          signed_instance = MultiJson.load(@json)
-        rescue ArgumentError, MultiJson::DecodeError => e
+          json = Base64.urlsafe_decode64(padded_json)
+          signed_instance = MultiJson.load(json)
+        rescue ArgumentError, MultiJson::ParseError => e
           raise SignedInstanceParseError.new(e.message)
         end
 
-        @instance_id = signed_instance['instanceId']
-        @sign_date = DateTime.parse(signed_instance['signDate'])
-        raise SignedInstanceParseError if @instance_id.nil? || @sign_date.nil?
+        # set all required instance properties
+        REQUIRED_PROPERTIES.each { |instance_key, attribute|
+          instance_value = signed_instance[instance_key]
+          raise SignedInstanceParseError.new("missing instance property: #{instance_key}") if strict_properties && instance_value.nil?
+          send "#{attribute}=", instance_value
+        }
+        # overwrite sign date with real DateTime object
+        self.sign_date = DateTime.parse(sign_date) if strict_properties || sign_date
 
-        @uid = signed_instance['uid']
-        @permissions = signed_instance['permissions']
+        # set all optional instance properties (if set)
+        OPTIONAL_PROPERTIES.each { |instance_key, attribute|
+          send "#{attribute}=", signed_instance[instance_key] if signed_instance.has_key? instance_key
+        }
       end
     end
   end

data/lib/wix-apps/signed_instance_middleware.rb

@@ -1,65 +1,71 @@
 module Wix
   module Apps
-    class SignedInstanceMiddleware < Struct.new :app, :options
+    class SignedInstanceMiddleware < Struct.new :app, :secret_key, :secured_paths, :paths
+
+      # Initializes the middleware to secure a given set of paths.
+      # Options:
+      # :secret_key - the Wix secret key as String
+      # :secured_paths (optional) - an Array of String and Regexp objects which every request's path is matched against. Matching paths are required to pass a Wix signed instance.
       def initialize(app, options={})
-        @app = app
-        initialize_options options
+        self.app = app
+        self.secret_key = options[:secret_key]
+        self.secured_paths = options[:secured_paths] || []
+        self.paths = options[:paths] || []
       end
 
+      # Checks current URL path for Wix instance requirement, parses given signed instance and adds GET param 'parsed_instance' with the instance's parsed properties.
+      # @param [Hash] env The current environment hash
+      # @return [Array] The typical [<code>, <headers>, <body>] rack response Array
       def call(env)
-        @env = env
+        path = env['PATH_INFO']
 
-        if secured_path?
-          @request = Rack::Request.new(env)
-          if have_instance?
-            begin
-              @instance = Wix::Apps::SignedInstance.new(@request.params['instance'],
-                          secret: options[:secret_key])
-            rescue Wix::Apps::SignedInstanceParseError => e
-              return [403, {}, ['Invalid wix instance']]
-            end
+        secured_path = secured_path? path
+        if secured_path || path?(path)
+          # path must be handled (instance is either required or optional)
+          request = Rack::Request.new(env)
 
-            if @instance.valid?
-              parse_instance!
-              @app.call(env)
-            else
-              [403, {}, ['Invalid wix instance']]
+          env['wix.instance'] = nil
+          if request.params.has_key? 'instance'
+            # Wix' "instance" parameter was supplied so it must be parseable. parse and set it into env.
+            begin
+              env['wix.instance'] = Wix::Apps::SignedInstance.new(request.params['instance'], secret: secret_key)
+            rescue Wix::Apps::SignedInstanceParseError
+              # 403 Forbidden
+              return [403, {}, ['Invalid Wix instance']]
             end
-          else
-            [401, {}, ['Unauthorized']]
+          elsif secured_path
+            # instance is required but Wix' "instance" parameter is missing
+            # 401 Unauthorized
+            return [401, {}, ['Unauthorized']]
           end
-        else
-          @app.call(env)
         end
-
+        app.call(env)
       end
 
       private
-      def initialize_options(options={})
-        self.options = {
-          :secret_key => nil,
-          :secured_paths => []
-        }.merge(options)
-      end
 
-      def secured_path?
-        options[:secured_paths].include? @env['PATH_INFO']
+      # Check if a request URL's path should be required to pass a Wix signed instance or not. Checks the path against the secured_paths option.
+      # @param [String] path URL path (=directory part) to check
+      # @return [Boolean] Indicates if given path should be secured or not
+      def secured_path?(path)
+        path_match? secured_paths, path
       end
 
-      def have_instance?
-        @request.params.keys.include? 'instance'
+      # Check if a request URL's path should be checked for a Wix signed instance or not. Checks the path against the paths option.
+      # @param [String] path URL path (=directory part) to check
+      # @return [Boolean] Indicates if given path should be checked or not
+      def path?(path)
+        path_match? paths, path
       end
 
-      def parse_instance!
-        parsed_instance = {
-          'instance_id' => @instance.instance_id,
-          'sign_date' => @instance.sign_date,
-          'user_id' => @instance.uid,
-          'permissions' => @instance.permissions
+      # @param [Array<String,Regexp>] match_paths List of Strings (match exact path) amd Regexps (match whatever the regexp says)
+      # @param [String] path The path to match against
+      def path_match?(match_paths, path)
+        match_paths.any? { |match_path|
+          match_path === path
         }
-        @request.GET['parsed_instance'] = parsed_instance
-
       end
+
     end
   end
-end
+end