uri_signer 0.0.1

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.rvmrc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rvmrc.sample

@@ -0,0 +1 @@
+rvm use --install --create 1.9.3@km-uri_signer

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in uri_signer.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Nate Klaiber
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,65 @@
+# UriSigner
+
+The KISSmetrics API provides an authentication realm of a digital
+signature of the request. This gem helps to put the pieces together and
+construct the URL with the signature.
+
+This is used within the core KISSmetrics Ruby API Wrapper to help
+abstract the building of the requests. 
+
+Using this without a wrapper will require you to manually provide your
+*client_secret*. 
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'uri_signer'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install uri_signer
+
+## Usage
+
+At any point, you can use the `reload_yard` command to view the
+documentation of the provided code. The basic usage is:
+
+```ruby
+
+http_method = "get"
+uri         = "https://api.example.com/core/people.json?page=5&per_page=25&order=name:desc&select=id,name"
+secret      = "my_secret"
+
+signer = UriSigner::UriSigner.new(http_method, uri, secret)
+
+signer.http_method
+# => "GET"
+
+signer.uri
+# => "https://api.example.com/core/people.json?page=5&per_page=25&order=name:desc&select=id,name"
+
+signer.signature
+# => "1AaJvChjz%2BZYJKxWsUQWNK1a%2BeGjpCs6uwQKwPw1%2FV8%3D"
+
+signer.uri_with_signature
+# => "https://api.example.com/core/people.json?_signature=6G4xiABih7FGvjwB1JsYXoeETtBCOdshIu93X1hltzk%3D"
+
+signer.valid?("1AaJvChjz%2BZYJKxWsUQWNK1a%2BeGjpCs6uwQKwPw1%2FV8%3D")
+# => true
+
+signer.valid?('1234')
+# => false
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/uri_signer.rb

@@ -0,0 +1,26 @@
+root = File.expand_path(File.dirname(__FILE__))
+
+# Utilities
+require 'rack/utils'
+require 'active_support/core_ext/object/blank.rb'
+
+# Version
+require File.join(root, 'uri_signer', 'version')
+
+# Errors
+require File.join(root, 'uri_signer', 'errors')
+
+# Core Extension Helpers
+require File.join(root, 'uri_signer', 'helpers')
+require File.join(root, 'uri_signer', 'helpers', 'string')
+require File.join(root, 'uri_signer', 'helpers', 'hash')
+
+# Parsers and Signers
+require File.join(root, 'uri_signer', 'query_hash_parser')
+require File.join(root, 'uri_signer', 'request_parser')
+require File.join(root, 'uri_signer', 'request_signature')
+require File.join(root, 'uri_signer', 'uri_signature')
+require File.join(root, 'uri_signer', 'signer')
+
+module UriSigner
+end

data/lib/uri_signer/errors.rb

@@ -0,0 +1,10 @@
+module UriSigner
+  module Errors
+    autoload :MissingQueryHashError,            File.join(File.dirname(__FILE__), 'errors/missing_query_hash_error')
+    autoload :MissingHttpMethodError,           File.join(File.dirname(__FILE__), 'errors/missing_http_method_error')
+    autoload :MissingBaseUriError,              File.join(File.dirname(__FILE__), 'errors/missing_base_uri_error')
+    autoload :MissingSignatureStringError,      File.join(File.dirname(__FILE__), 'errors/missing_signature_string_error')
+    autoload :MissingSecretError,               File.join(File.dirname(__FILE__), 'errors/missing_secret_error')
+    autoload :MissingUriError,                  File.join(File.dirname(__FILE__), 'errors/missing_uri_error')
+  end
+end

data/lib/uri_signer/errors/missing_base_uri_error.rb

@@ -0,0 +1,6 @@
+module UriSigner
+  module Errors
+    class MissingBaseUriError < StandardError
+    end
+  end
+end

data/lib/uri_signer/errors/missing_http_method_error.rb

@@ -0,0 +1,6 @@
+module UriSigner
+  module Errors
+    class MissingHttpMethodError < StandardError
+    end
+  end
+end

data/lib/uri_signer/errors/missing_query_hash_error.rb

@@ -0,0 +1,7 @@
+module UriSigner
+  module Errors
+    class MissingQueryHashError < StandardError
+    end
+  end
+end
+

data/lib/uri_signer/errors/missing_secret_error.rb

@@ -0,0 +1,6 @@
+module UriSigner
+  module Errors
+    class MissingSecretError < StandardError
+    end
+  end
+end

data/lib/uri_signer/errors/missing_signature_string_error.rb

@@ -0,0 +1,6 @@
+module UriSigner
+  module Errors
+    class MissingSignatureStringError < StandardError
+    end
+  end
+end

data/lib/uri_signer/errors/missing_uri_error.rb

@@ -0,0 +1,6 @@
+module UriSigner
+  module Errors
+    class MissingUriError < StandardError
+    end
+  end
+end

data/lib/uri_signer/helpers.rb

@@ -0,0 +1,4 @@
+module UriSigner
+  module Helpers
+  end
+end

data/lib/uri_signer/helpers/hash.rb

@@ -0,0 +1,12 @@
+module UriSigner
+  module Helpers
+    module Hash
+      def stringify_keys
+        self.inject({}) do |options, (key, value)|
+          options[key.to_s] = value
+          options
+        end
+      end
+    end
+  end
+end

data/lib/uri_signer/helpers/string.rb

@@ -0,0 +1,59 @@
+require 'uri'
+require 'cgi'
+require 'rack/utils'
+require 'base64'
+require 'hmac'
+require 'hmac-sha2'
+require 'addressable/uri'
+
+module UriSigner
+  module Helpers
+    module String
+      # Returns the string with newlines replaced with <br>
+      #
+      # @return [String] HTML version
+      def nl2br
+        self.gsub(/\n/, '<br>')
+      end
+
+      # This returns the string Base64 encoded with the newlines removed
+      #
+      # @return [String] encoded
+      def base64_encoded
+        Base64.encode64(self).chomp
+      end
+
+      # This delegates the call to Rack::Utils to escape a string
+      #
+      # @return [String] escaped
+      def escaped
+        return '' if self.nil?
+        unescaped = URI.unescape(self) # This will fix the percent encoding issue
+        Rack::Utils.escape(unescaped)
+      end
+
+      # This delegates the call to Rack::Utils to unescape a string
+      #
+      # @return [String] unescaped
+      def unescaped
+        Rack::Utils.unescape(self)
+      end
+
+      # Digitally sign a string with a secret and get the digest
+      #
+      # @return [String]
+      def hmac_signed_with(secret)
+        hmac = HMAC::SHA256.new(secret)
+        hmac << self
+        hmac.digest
+      end
+
+      # Take a URL string and convert it to a URI Parsed object
+      #
+      # @return [Addressable]
+      def to_parsed_uri
+        Addressable::URI.parse(CGI.unescapeHTML(self))
+      end
+    end
+  end
+end

data/lib/uri_signer/query_hash_parser.rb

@@ -0,0 +1,47 @@
+module UriSigner
+  # This object takes in a hash, most likely from Rack::Utils.parse_query, and transforms it into
+  # a query string that's used for signing requests. It takes a hash, transforms the hash into a
+  # query string that has it's parts ordered accordingly.
+  #
+  # @example
+  #   parser = UriSigner::QueryHashParser.new({"order"=>["name:desc", "id:desc"], "where"=>["name:nate", "id:123"]})
+  #
+  #   parser.to_s
+  #   # => "order=name:desc&order=id:desc&where=name:nate&where=id:123"
+  #
+  class QueryHashParser
+    # Creates a new QueryHashParser instance
+    #
+    # @param query_hash [Hash] A hash of key/values to turn into a query stringo
+    #
+    # @return [void]
+    def initialize(query_hash)
+      @query_hash = query_hash
+
+      raise UriSigner::Errors::MissingQueryHashError.new('Please provide a query string hash') unless query_hash?
+    end
+
+    # Returns the hash (key/values) as an ordered query string. This joins the keys and values, and then
+    # joins it all with the ampersand. This is not escaped
+    #
+    # @return [String]
+    def to_s
+      parts = @query_hash.sort.inject([]) do |arr, (key,value)|
+        if value.kind_of?(Array)
+          value.each do |nested|
+            arr << "%s=%s" % [key, nested]
+          end
+        else
+          arr << "%s=%s" % [key, value]
+        end
+        arr
+      end
+      parts.join('&')
+    end
+
+    private
+    def query_hash?
+      @query_hash.kind_of?(Hash) && !@query_hash.blank?
+    end
+  end
+end

data/lib/uri_signer/request_parser.rb

@@ -0,0 +1,143 @@
+module UriSigner
+  # This object takes the raw request from the inbound API call. It takes the http method
+  # used to make the request, and the full #raw_uri of the request. This object extracts the 
+  # pieces necessary to pass it to the signing class. The key components are #http_method, #base_uri, 
+  # and #query_params. #query_params has the core params extracted (any param starting with
+  # an underscore)
+  #
+  # @example
+  #   parser = UriSigner::RequestParser.new('get', 'https://api.example.com/core/people.json?_signature=1234&page=5&per_page=25')
+  #
+  #   parser.http_method
+  #   # => "GET"
+  #
+  #   parser.https?
+  #   # => true
+  #
+  #   parser.http?
+  #   # => false
+  #
+  #   parser.raw_uri
+  #   # => "https://api.example.com/core/people.json?_signature=1234&page=5&per_page=25
+  #
+  #   parser.query_params
+  #   # => {"page"=>"5", "per_page"=>"25"}
+  #
+  #   parser.query_params?
+  #   # => true
+  #
+  #   parser.signature
+  #   # => '1234'
+  #
+  #   parser.signature?
+  #   # => true
+  #
+  #   parser.base_uri
+  #   # => "https://api.example.com/core/people.json"
+  #
+  class RequestParser
+    # Create a new RequestParser instance
+    #
+    # @param http_method [String] The HTTP method used to make the request (GET, POST, PUT, or DELETE)
+    # @param raw_uri [String] The raw URI from the request
+    #
+    # @return [void]
+    def initialize(http_method, raw_uri)
+      @http_method = http_method
+      @raw_uri     = raw_uri
+
+      raise UriSigner::Errors::MissingHttpMethodError.new("Please provide an HTTP method") unless http_method?
+      raise UriSigner::Errors::MissingUriError.new("Please provide a URI") unless raw_uri?
+
+      extract_core_params!
+    end
+
+    # Returns the uppercased HTTP Method
+    #
+    # @return [String]
+    def http_method
+      @http_method.upcase
+    end
+
+    # Returns true if the scheme/protocol used was HTTPS
+    #
+    # @return [Bool]
+    def https?
+      'https' == self.parsed_uri.scheme.downcase
+    end
+
+    # Returns true if the scheme/protocol used was HTTP
+    #
+    # @return [Bool]
+    def http?
+      !self.https?
+    end
+
+    # Returns the raw_uri that was provided in the constructor
+    #
+    # @return [String]
+    def raw_uri
+      @raw_uri
+    end
+
+    # Returns an instance of Addressable::URI that has been parsed.
+    # This allows us to extract the core parts of the raw_uri
+    #
+    # @return [Addressable]
+    def parsed_uri
+      @parsed_uri ||= self.raw_uri.extend(UriSigner::Helpers::String).to_parsed_uri
+    end
+
+    # Returns the query params with the core params removed
+    #
+    # @return [Hash]
+    def query_params
+      @query_params ||= raw_query_params
+    end
+
+    # Returns true if query params were given
+    #
+    # @return [Bool]
+    def query_params?
+      !self.query_params.blank?
+    end
+
+    # Returns the base_uri of the request. This is the protocol, host with port, and the path.
+    #
+    # @return [String]
+    def base_uri
+      [self.parsed_uri.normalized_site, self.parsed_uri.normalized_path].join('')
+    end
+
+    # This returns the signature that was provided in the query params
+    #
+    # @return [String]
+    def signature
+      @_signature.extend(UriSigner::Helpers::String).escaped
+    end
+
+    # Returns true if a signature was provided in the raw_uri
+    #
+    # @return [Bool]
+    def signature?
+      !@_signature.blank?
+    end
+
+    private
+    def http_method?
+      !@http_method.blank?
+    end
+
+    def raw_uri?
+      !@raw_uri.blank?
+    end
+
+    def raw_query_params
+      @raw_query_params ||= Rack::Utils.parse_query(self.parsed_uri.query)
+    end
+
+    def extract_core_params!
+      @_signature = raw_query_params.delete('_signature')
+    end
+  end
+end