uri_signer 0.0.1

data/lib/uri_signer/request_signature.rb

@@ -0,0 +1,123 @@
+module UriSigner
+  # This is responsible for preparing the raw request in the format necessary for signing. API URI signatures come in a few different flavors. This one
+  # will take HTTP_METHOD & ESCAPED_BASE_URI & SORTED_AND_ESCAPED_QUERY_PARAMS
+  #
+  # @example
+  #
+  #   request_signature = UriSigner::RequestSignature.new('get', 'https://api.example.com/core/people.json', { 'page' => 5, 'per_page' => 25 })
+  #
+  #   request_signature.http_method
+  #   # => 'GET'
+  #
+  #   request_signature.base_uri
+  #   # => 'https://api.example.com/core/people.json'
+  #
+  #   request_signature.query_params
+  #   # => { 'page' => 5, 'per_page' => 25' }
+  #
+  #   request_signature.query_params?
+  #   # => true
+  #
+  #   request_signature.encoded_base_uri
+  #   # => "https%3A%2F%2Fapi.example.com%2Fcore%2Fpeople.json"
+  #
+  #   request_signature.encoded_query_params
+  #   # => "page%3D5%26per_page%3D25"
+  #
+  #   request_signature.signature
+  #   # => "GET&https%3A%2F%2Fapi.example.com%2Fcore%2Fpeople.json&page%3D5%26per_page%3D25"
+  #
+  class RequestSignature
+
+    # The default separator used to join the http_method, encoded_base_uri, and encoded_query_params
+    attr_reader :separator
+
+    # Create a new RequestSignature instance
+    #
+    # @param http_method [String] The HTTP method from the request (GET, POST, PUT, or DELETE)
+    # @param base_uri [String] The base URI of the request. This is everything except the query string params
+    # @param query_params [Hash] A hash of the provided query string params
+    #
+    # It's required that you provide at least the http_method and base_uri. Params are optional
+    #
+    # @return [void]
+    def initialize(http_method, base_uri, query_params = {})
+      @http_method  = http_method
+      @base_uri     = base_uri
+      @query_params = query_params
+      @separator    = '&'
+
+      raise UriSigner::Errors::MissingHttpMethodError.new("Please provide an HTTP method") unless http_method?
+      raise UriSigner::Errors::MissingBaseUriError.new("Please provide a Base URI") unless base_uri?
+    end
+
+    # Returns the full signature string
+    #
+    # @return [String]
+    def signature
+      core_signature = [self.http_method, self.encoded_base_uri]
+      core_signature << self.encoded_query_params if self.query_params?
+      core_signature.join(self.separator)
+    end
+    alias :to_s :signature
+
+    # Returns the uppercased HTTP Method
+    #
+    # @return [String]
+    def http_method
+      @http_method.upcase
+    end
+
+    # Returns the base URI
+    #
+    # @return [String]
+    def base_uri
+      @base_uri
+    end
+
+    # Returns the encoded base_uri
+    #
+    # This can be used for comparison to ensure the escaping is what you want
+    #
+    # @return [String] Escaped string of the base_uri
+    def encoded_base_uri
+      self.base_uri.extend(UriSigner::Helpers::String).escaped
+    end
+
+    # Returns the Query String parameters
+    #
+    # @return [Hash] The keys are stringified
+    def query_params
+      @query_params.extend(UriSigner::Helpers::Hash).stringify_keys
+    end
+
+    # Returns true if query params were provided
+    #
+    # @return [Bool]
+    def query_params?
+      !@query_params.blank?
+    end
+
+    # Returns the encoded query params as a string
+    #
+    # This joins the keys and values in one string, then joins them. Then it will escape the final contents.
+    #
+    # @return [String] Escaped string of the query params
+    def encoded_query_params
+      query_params_string.extend(UriSigner::Helpers::String).escaped
+    end
+
+    private
+    def http_method?
+      !@http_method.blank?
+    end
+
+    def base_uri?
+      !@base_uri.blank?
+    end
+
+    def query_params_string
+      @query_params_string ||= UriSigner::QueryHashParser.new(self.query_params).to_s
+    end
+  end
+end

data/lib/uri_signer/signer.rb

@@ -0,0 +1,108 @@
+module UriSigner
+  # This is the object that wraps the other building blocks and can be used to sign requests. 
+  #
+  # @example
+  #   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
+  #
+  class Signer
+    # Create a new UriSigner instance
+    #
+    # @param http_method [String] The HTTP method used to make the request (GET, POST, PUT, and DELETE)
+    # @param uri [String] The requested URI
+    # @param secret [String] The secret that is used to sign the request
+    #
+    # @return [void]
+    def initialize(http_method, uri, secret)
+      @http_method = http_method
+      @uri         = uri
+      @secret      = secret
+
+      raise UriSigner::Errors::MissingHttpMethodError.new("Please provide an HTTP method") unless http_method?
+      raise UriSigner::Errors::MissingUriError.new("Please provide a URI") unless uri?
+      raise UriSigner::Errors::MissingSecretError.new("Please provide a secret to sign the string") unless secret?
+    end
+
+    # Returns the URI passed into the constructor
+    #
+    # @return [String]
+    def uri
+      @uri
+    end
+
+    # Returns the URI with the signature appended to the query string
+    #
+    # return [String]
+    def uri_with_signature
+      separator = if request_parser.query_params? then '&' else '?' end
+      "%s%s_signature=%s" % [self.uri, separator, self.signature]
+    end
+
+    # Returns the uppercased HTTP Method
+    #
+    # @return [String]
+    def http_method
+      @http_method.to_s.upcase
+    end
+
+    # Returns the signature
+    #
+    # @return [String]
+    def signature
+      uri_signature.signature
+    end
+
+    # Returns true if +other+ matches the proper signature
+    #
+    # @return [Bool]
+    def valid?(other)
+      self.signature === other
+    end
+
+    private
+    def uri?
+      !@uri.blank?
+    end
+
+    def http_method?
+      !@http_method.blank?
+    end
+
+    def secret?
+      !@secret.blank?
+    end
+
+    def request_parser
+      @request_parser ||= UriSigner::RequestParser.new(self.http_method, self.uri)
+    end
+
+    def request_signature
+      @request_signature ||= UriSigner::RequestSignature.new(request_parser.http_method, request_parser.base_uri, request_parser.query_params)
+    end
+
+    def uri_signature
+      @uri_signature ||= UriSigner::UriSignature.new(request_signature.signature, @secret)
+    end
+  end
+end

data/lib/uri_signer/uri_signature.rb

@@ -0,0 +1,79 @@
+module UriSigner
+  # This is the object that will be used to verify properly signed API URI requests
+  # The #secret is stored in the persistence layer for comparison. There is an API Key
+  # and a shared secret. All requests will be signed with the shared secret. The URI
+  # will also include a _signature param, where the client will sign the request and
+  # store it in the URI.
+  #
+  # The signing algorithm looks like this:
+  #
+  # @example
+  #   secret = "my_secret"
+  #   string_to_sign = "http://api.example.com/url/to_sign.json"
+  #
+  #   hmac = HMAC::SHA256.new(secret)
+  #
+  #   hmac.digest
+  #   # => "??B\230????șo\271$'\256A?d?\223L\244\225\231\exR\270U"
+  #
+  #   hmac << string_to_sign
+  #
+  #   hmac.digest
+  #   # => "?m?j\2761\031\235\206\260?A?\f\263\216\221\fBH?fC\215Ļ\204\233\202@/e"
+  #
+  #   encoded = Base64.encode64(hmac.digest).chomp
+  #   # => "8W3xar4xGZ2GsOJBmAyzjpEMQkg/ZkONxLuEm4JAL2U="
+  #
+  #   escaped = Rack::Utils.escape(encoded)
+  #   # => "8W3xar4xGZ2GsOJBmAyzjpEMQkg%2FZkONxLuEm4JAL2U%3D"
+  #
+  #   # The final signed string is "8W3xar4xGZ2GsOJBmAyzjpEMQkg%2FZkONxLuEm4JAL2U%3D"
+  #
+  class UriSignature
+    # Create a new UriSignature instance
+    #
+    # @param signature_string [String] the string that needs to be signed
+    # @param secret [String] the secret to use for the signature
+    #
+    # @return [void]
+    def initialize(signature_string, secret)
+      @signature_string = signature_string
+      @secret           = secret
+
+      raise UriSigner::Errors::MissingSignatureStringError.new("Please provide a string to sign") unless signature_string?
+      raise UriSigner::Errors::MissingSecretError.new("Please provide a secret to sign the string") unless secret?
+    end
+
+    # Return the signature string that was provided in the constructor
+    #
+    # @return [String]
+    def signature_string
+      @signature_string
+    end
+
+    # Return the signature_string after being signed with the secret
+    #
+    # @return [String]
+    def signature
+      @signature ||= sign!
+    end
+    alias :to_s :signature
+
+    private
+    def signature_string?
+      !@signature_string.blank?
+    end
+
+    def secret?
+      !@secret.blank?
+    end
+
+    def sign!
+      extension = UriSigner::Helpers::String
+
+      hmac    = self.signature_string.extend(extension).hmac_signed_with(@secret)
+      encoded = hmac.extend(extension).base64_encoded
+      escaped = encoded.extend(extension).escaped
+    end
+  end
+end

data/lib/uri_signer/version.rb

@@ -0,0 +1,3 @@
+module UriSigner
+  VERSION = "0.0.1"
+end

data/reload_yard

@@ -0,0 +1,3 @@
+#!/usr/bin/env sh
+
+yardoc "lib/uri_signer/**/*.rb" && yard server

data/spec/query_hash_parser_spec.rb

@@ -0,0 +1,79 @@
+require File.expand_path(File.join(File.dirname(__FILE__), '../lib/uri_signer'))
+
+class CustomHash < Hash; end
+
+describe UriSigner::QueryHashParser do
+  before do
+    @query_hash = { "name" => "bob", "id" => "2344" }
+  end
+
+  subject { described_class.new(@query_hash) }
+
+  it "converts the hash to a string" do
+    subject.to_s.should == "id=2344&name=bob"
+  end
+
+  it "raises a MissingQueryHashError if no hash is provided" do
+    lambda { described_class.new('') }.should raise_error(UriSigner::Errors::MissingQueryHashError)
+  end
+
+  it "raises a MissingQueryHashError if nil is provided" do
+    lambda { described_class.new(nil) }.should raise_error(UriSigner::Errors::MissingQueryHashError)
+  end
+
+  it "raises a MissingQueryHashError if a string is provided" do
+    lambda { described_class.new('name=bob') }.should raise_error(UriSigner::Errors::MissingQueryHashError)
+  end
+
+  it "allows a custom hash to be provided" do
+    hash = CustomHash.new
+    hash['name'] = 'bob'
+    lambda { described_class.new(hash) }.should_not raise_error
+  end
+
+  context "one param" do
+    before do
+      @query_hash = {"order"=>["name:desc", "id:desc"]}
+    end
+
+    subject { described_class.new(query_hash) }
+
+    it "converts a single key with multiple values to a string" do
+      query_hash = {"order"=>["name:desc", "id:desc"]}
+      parser = described_class.new(query_hash)
+
+      parser.to_s.should == "order=name:desc&order=id:desc"
+    end
+
+    it "converts a single key value to a string" do
+      query_hash = {"order"=>["name:desc"]}
+      parser = described_class.new(query_hash)
+
+      parser.to_s.should == "order=name:desc"
+    end
+  end
+
+  context "Parsing multiple params with different values" do
+    before do
+      @query_hash = {"order"=>["name:desc", "id:desc"], "_signature"=>"1234", "where"=>["name:nate", "id:123"]}
+    end
+
+    subject { described_class.new(@query_hash) }
+
+    it "converts the hash to a string" do
+      subject.to_s.should == "_signature=1234&order=name:desc&order=id:desc&where=name:nate&where=id:123"
+    end
+  end
+
+  context "Parsing multiple params with duplicate values" do
+    before do
+    @query_hash = {"order"=>["name:desc", "name:desc"], "_signature"=>"1234", "where"=>["name:nate", "name:nate"]}
+    end
+
+    subject { described_class.new(@query_hash) }
+
+    it "converts the hash to a string" do
+      subject.to_s.should == "_signature=1234&order=name:desc&order=name:desc&where=name:nate&where=name:nate"
+    end
+  end
+end

data/spec/request_parser_spec.rb

@@ -0,0 +1,250 @@
+require File.expand_path(File.join(File.dirname(__FILE__), '../lib/uri_signer'))
+
+describe UriSigner::RequestParser do
+  before do
+    @method = 'GET'
+    @raw_uri = "https://api.example.com/core/people.json?_signature=1234&page=12&per_page=34&order=name:desc&select=id&select=guid"
+  end
+
+  subject { described_class.new(@method, @raw_uri) }
+
+  it "responds to #http_method" do
+    subject.should respond_to(:http_method)
+  end
+
+  it "responds to #https?" do
+    subject.should respond_to(:https?)
+  end
+
+  it "responds to #http?" do
+    subject.should respond_to(:http?)
+  end
+
+  it "responds to #raw_uri" do
+    subject.should respond_to(:raw_uri)
+  end
+
+  it "responds to #base_uri" do
+    subject.should respond_to(:base_uri)
+  end
+
+  it "responds to #parsed_uri" do
+    subject.should respond_to(:parsed_uri)
+  end
+
+  it "responds to #query_params" do
+    subject.should respond_to(:query_params)
+  end
+
+  it "responds to #query_params?" do
+    subject.should respond_to(:query_params?)
+  end
+
+  it "responds to #signature" do
+    subject.should respond_to(:signature)
+  end
+
+  it "responds to #signature?" do
+    subject.should respond_to(:signature?)
+  end
+
+  context "With HTML encoded URI String" do
+    before do
+      @raw_uri = "https://api.kissmetrics.dev/v1/accounts?page=2&per_page=2&_signature=lertaejeT%252BN3M1pCjBZo8gCRK%252BAfTmOquNvMZjmAfGw%253D"
+    end
+
+    subject { described_class.new(@method, @raw_uri) }
+
+    it "returns the #http_method" do
+      subject.http_method.should == "GET"
+    end
+
+    it "returns true for #https?" do
+      subject.https?.should be_true
+    end
+
+    it "returns the #base_uri" do
+      subject.base_uri.should == "https://api.kissmetrics.dev/v1/accounts"
+    end
+
+    it "returns the query values" do
+      subject.query_params.size.should eql(2)
+    end
+
+    it "does not return the signature in the query values" do
+      subject.query_params.should_not have_key('_signature')
+    end
+
+    it "returns true for #query_params?" do
+      subject.query_params?.should be_true
+    end
+
+    it "includes the proper keys in the query value" do
+      subject.query_params.should include('page', 'per_page')
+    end
+
+    it "returns the signature from the url" do
+      subject.signature.should == "lertaejeT%2BN3M1pCjBZo8gCRK%2BAfTmOquNvMZjmAfGw%3D"
+    end
+
+    it "returns true for #signature?" do
+      subject.signature?.should be_true
+    end
+  end
+
+  context "With valid values" do
+    it "returns the #http_method" do
+      subject.http_method.should == "GET"
+    end
+
+    it "returns true for #https?" do
+      subject.https?.should be_true
+    end
+
+    it "returns false for #http?" do
+      subject.http?.should be_false
+    end
+
+    it "returns the #base_uri" do
+      subject.base_uri.should == "https://api.example.com/core/people.json"
+    end
+
+    it "returns the #raw_uri" do
+      subject.raw_uri.should == "https://api.example.com/core/people.json?_signature=1234&page=12&per_page=34&order=name:desc&select=id&select=guid"
+    end
+
+    it "returns the query values" do
+      subject.query_params.size.should eql(4)
+    end
+
+    it "does not return the signature in the query values" do
+      subject.query_params.should_not have_key('_signature')
+    end
+
+    it "returns true for #query_params?" do
+      subject.query_params?.should be_true
+    end
+
+    it "includes the proper keys in the query value" do
+      subject.query_params.should include('page','per_page','order')
+    end
+
+    it "returns multiple values for query param key" do
+      subject.query_params['select'].should eql ['id', 'guid']
+    end
+
+    it "returns the parsed_uri as an Addressable::URI object" do
+      subject.parsed_uri.should be_a_kind_of(Addressable::URI)
+    end
+
+    it "returns the signature from the url" do
+      subject.signature.should == "1234"
+    end
+
+    it "returns true for #signature?" do
+      subject.signature?.should be_true
+    end
+  end
+
+  context "without query params" do
+    before do
+      @raw_uri = "https://api.example.com/core/people.json"
+    end
+
+    subject { described_class.new(@method, @raw_uri) }
+
+    it "returns empty query values" do
+      subject.query_params.size.should eql(0)
+    end
+
+    it "returns false for #signature?" do
+      subject.signature?.should be_false
+    end
+
+    it "returns false for #query_params?" do
+      subject.query_params?.should be_false
+    end
+  end
+
+  context "Determining the scheme" do
+    before do
+      @raw_uri = "http://api.example.com"
+    end
+
+    subject { described_class.new(@method, @raw_uri) }
+
+    it "returns false for #https?" do
+      subject.https?.should be_false
+    end
+
+    it "returns true for #http?" do
+      subject.http?.should be_true
+    end
+  end
+
+  context "With a signature and other query string values in the URI" do
+    before do
+      @raw_uri = "https://api.example.com/test?page=3&per_page=23&order=name:desc&_signature=3434343434gh="
+    end
+
+    subject { described_class.new(@method, @raw_uri) }
+
+    it "returns true for #signature?" do
+      subject.signature?.should be_true
+    end
+
+    it "escapes the signature" do
+      subject.signature.should == "3434343434gh%3D"
+    end
+  end
+
+  context "With a signature and no other query string values in the URI" do
+    before do
+      @raw_uri = "https://api.example.com/test?_signature=3434343434gh="
+    end
+
+    subject { described_class.new(@method, @raw_uri) }
+
+    it "returns true for #signature?" do
+      subject.signature?.should be_true
+    end
+
+    it "escapes the signature" do
+      subject.signature.should == "3434343434gh%3D"
+    end
+
+    it "returns empty query values" do
+      subject.query_params.size.should eql(0)
+    end
+
+    it "returns false for #query_params?" do
+      subject.query_params?.should be_false
+    end
+  end
+
+  context "Without a signature in the URI" do
+    before do
+      @raw_uri = "https://api.example.com"
+    end
+
+    subject { described_class.new(@method, @raw_uri) }
+
+    it "returns an empty string for #signature" do
+      subject.signature.should be_empty
+    end
+
+    it "returns false for #signature?" do
+      subject.signature?.should be_false
+    end
+  end
+
+  context "Validations" do
+    it "raises a UriSigner:MissingHttpMethodError if an empty string is provided" do
+      lambda { described_class.new('', @raw_uri)}.should raise_error(UriSigner::Errors::MissingHttpMethodError)
+    end
+
+    it "raises a UriSigner::MissingHttpMethodError if nil is provided" do
+      lambda { described_class.new(nil, @raw_uri)}.should raise_error(UriSigner::Errors::MissingHttpMethodError)
+    end
+  end
+end