lockbox_middleware 1.2.0

data/LICENSE

@@ -0,0 +1,24 @@
+Copyright (c) 2010, Democratic National Committee
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+    * Neither the name of the Democratic National Committee nor the
+      names of its contributors may be used to endorse or promote products
+      derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.rdoc

@@ -0,0 +1,48 @@
+= LockBox
+
+LockBox is a centralized API authentication service written by the DNC Innovation Lab. It lets your API 
+users share a single identity across multiple services.  
+It is licensed under the New BSD License (see the LICENSE file for details).
+
+It is a Ruby on Rails application on the server side, and Rack middleware on the client side
+(which means it integrates nicely with any modern Ruby web framework). As of v1.2.0, there is an
+unfortunate Rails dependency in the middleware gem. Hopefully we'll get rid of that soon.
+
+Lockbox handles things like rate limiting, API key signup and management, and supports HMAC
+authentication as well as plain-text key exchange. We are working on replacing HMAC with OAuth 2.0.
+
+== Configuration
+
+LockBox needs a configuration file named "lockbox.yml" in order to work. In a Rack app (incl. Rails),
+this file should be placed in app_root/config/lockbox.yml.
+
+You should define (for each of your environments), the base_uri of your app and the relative paths you want
+to protect with LockBox.
+
+Here's an example lockbox.yml:
+
+  production: 
+    base_uri: http://lockbox.foo.org
+  development: 
+    base_uri: http://localhost:3001
+  cucumber: 
+    base_uri: http://localhost:3001
+  test: 
+    base_uri: http://localhost:3001
+  all:
+    protect_paths: 
+      - ^/api/
+
+== Download
+
+Github: http://github.com/dnclabs/lockbox/tree/master
+
+== Authors
+
+- Nathan Woodhull
+- Chris Gill
+- Brian Cardarella
+- Wes Morgan
+
+Copyright 2010 Democratic National Committee,
+All Rights Reserved.

data/lib/lockbox_cache.rb

@@ -0,0 +1,48 @@
+require 'forwardable'
+
+module LockBoxCache
+  class Cache
+    extend Forwardable
+    def_delegators :@cache, :write, :read, :delete
+    
+    class RailsCache
+      def write(key, value)
+        Rails.cache.write(key, value)
+      end
+
+      def read(key)
+        Rails.cache.read(key)
+      end
+
+      def delete(key)
+        Rails.cache.delete(key)
+      end
+    end
+
+    class HashCache
+      def initialize
+        @store = Hash.new
+      end
+
+      def write(key, value)
+        @store[key] = value
+      end
+
+      def read(key)
+        @store[key]
+      end
+
+      def delete(key)
+        @store.delete(key)
+      end
+    end
+    
+    def initialize
+      if defined?(Rails)
+        @cache = RailsCache.new
+      else
+        @cache = HashCache.new
+      end
+    end
+  end
+end

data/lib/lockbox_middleware.rb

@@ -0,0 +1,156 @@
+require 'httparty'
+require 'lockbox_cache'
+require 'auth-hmac'
+
+class LockBox
+  include HTTParty
+  include LockBoxCache
+
+  def self.config
+    if defined?(Rails)
+      root_dir = Rails.root
+    else
+      root_dir = '.'
+    end
+    yaml_config = YAML.load_file(File.join(root_dir,'config','lockbox.yml'))
+    return_config = {}
+    environment = Rails.env if defined? Rails
+    environment ||= ENV['RACK_ENV']
+    environment ||= 'test'
+    if !environment.nil?
+      if !yaml_config['all'].nil?
+        return_config = yaml_config['all']
+        return_config.merge!(yaml_config[environment])
+      else
+        return_config = yaml_config[environment]
+      end
+    end
+    return_config
+  end
+
+  base_uri config['base_uri']
+
+  def initialize(app)
+    @app = app
+    @cache = LockBoxCache::Cache.new
+  end
+
+  def call(env)
+    dup.call!(env)
+  end
+  
+  def protected_paths
+    self.class.config['protect_paths'].map do |path|
+      Regexp.new(path)
+    end
+  end
+
+  def call!(env)
+    #attempt to authenticate any requests to /api
+    request = Rack::Request.new(env)
+    path_protected = false
+    protected_paths.each do |path|
+      if env['PATH_INFO'] =~ path
+        path_protected = true
+        authorized = false
+        key = request['key']
+        if key.blank?
+          key = 'hmac'
+        end
+      
+        auth = auth_response(key,env)
+        authorized = auth[:authorized]
+        auth_headers = auth[:headers]
+      
+        if authorized
+          app_response = @app.call(env)
+          app_headers = app_response[1]
+          response_headers = app_headers.merge(auth_headers)
+          return [app_response[0], response_headers, app_response[2]]
+        else
+          message = "Access Denied"
+          return [401, {'Content-Type' => 'text/plain', 'Content-Length' => "#{message.length}"}, message]
+        end
+      end
+    end
+    unless path_protected
+      #pass everything else straight through to app
+      return @app.call(env)
+    end
+  end
+
+  def auth_response(api_key, env={})
+    if api_key != 'hmac'
+      cached_auth = auth_cache(api_key)
+      if !cached_auth.nil?
+        # currently we don't cache forward headers
+        return {:authorized => cached_auth, :headers => {}}
+      end
+    end
+    auth_response = self.class.get("/authentication/#{api_key}", {:headers => auth_headers(env)})
+    authorized = (auth_response.code == 200)
+    cache_response_if_allowed(api_key, auth_response) if authorized
+    {:authorized => authorized, :headers => response_headers(auth_response)}
+  end
+  
+  private
+  
+  def cache_response_if_allowed(api_key, auth_response)
+    cache_control = auth_response.headers['Cache-Control'].split(/,\s*/)
+    cache_max_age = 0
+    cache_public = false
+    cache_control.each do |c|
+      if c =~ /^max-age=\s*(\d+)$/
+        cache_max_age = $1.to_i
+      elsif c == 'public'
+        cache_public = true
+      end
+    end
+    caching_allowed = (cache_max_age > 0 && cache_public)
+    expiration = cache_max_age.seconds.since(Time.now)
+    cache_auth(api_key,expiration) if caching_allowed
+  end
+
+  def response_headers(auth_response)
+    headers = {}
+    auth_response.headers.each_pair do |h,v|
+      if h =~ /^X-RateLimit-/
+        headers[h] = v
+      elsif h =~ /^X-LockBox-/
+        headers[h] = v
+      end
+    end
+    headers
+  end
+
+  def auth_headers(env)
+    headers = {}
+    headers['Referer'] = "#{env['rack.url_scheme']}://#{env['SERVER_NAME']}#{env['PATH_INFO']}"
+    headers['Referer'] << "?#{env['QUERY_STRING']}" unless env['QUERY_STRING'].blank?
+    {'Content-Type' => 'Content-Type', 'Content-MD5' => 'Content-MD5', 'Date' => 'HTTP_DATE', 'Method' => 'REQUEST_METHOD', 'Authorization' => 'HTTP_AUTHORIZATION'}.each_pair do |h,e|
+      headers["X-Referer-#{h}"] = env[e] unless env[e].blank?
+    end
+    headers
+  end
+  
+  def cache_key(api_key)
+    "lockbox_#{api_key}"
+  end
+
+  def auth_cache(api_key)
+    expiration = @cache.read(cache_key(api_key))
+    return nil if expiration.nil?
+    expiration = Time.at(expiration)
+    if expiration <= Time.now
+      @cache.delete(cache_key(api_key))
+      nil
+    elsif expiration > Time.now
+      true
+    end
+  end
+
+  def cache_auth(api_key,expiration)
+    @cache.write(cache_key(api_key),expiration.to_i)
+  end
+
+end

data/spec/lib/lockbox_middleware_spec.rb

@@ -0,0 +1,229 @@
+require 'spec_helper'
+require 'rack/test'
+require 'lockbox_middleware'
+
+describe 'LockBox' do
+  include Rack::Test::Methods
+
+  def app
+    # Initialize our LockBox middleware with an "app" that just always returns 200, if it gets .called
+    LockBox.new(Proc.new {|env| [200,{},"successfully hit rails app"]})
+  end
+  
+  def safely_edit_config_file(settings, env=nil)
+    env ||= Rails.env if defined?(Rails)
+    env ||= ENV['RACK_ENV']
+    env ||= 'test'
+    @config_file = File.join(File.dirname(__FILE__),'..','..','config','lockbox.yml')
+    @tmp_config_file = "#{@config_file}.testing"
+    FileUtils.cp(@config_file, @tmp_config_file)
+    config = YAML.load_file(@config_file)
+    settings.each_pair do |setting,value|
+      config[env][setting.to_s] = value
+    end
+    File.open( @config_file, 'w' ) do |out|
+      YAML.dump( config, out )
+    end
+  end
+  
+  context "setting the base_uri" do
+    let(:base_uri) { "http://localhost:3001" }
+    
+    it "should use the base_uri specified in the config" do
+      safely_edit_config_file({:base_uri => base_uri})
+      LockBox.base_uri.should == base_uri
+    end
+    
+    after :each do
+      if @tmp_config_file && @config_file
+        FileUtils.mv(@tmp_config_file, @config_file)
+      end
+    end
+  end
+  
+  context "setting the protected paths" do
+    let(:path1) { "^/api/" }
+    let(:path2) { "^/foo/bar/" }
+    let(:path3) { "/lookup/?$" }
+    
+    before :each do
+      safely_edit_config_file({:protect_paths => [path1, path2, path3]}, 'all')
+      successful_response = mock("MockResponse")
+      successful_response.stubs(:code).returns(200)
+      successful_response.stubs(:headers).returns({'Cache-Control' => 'public,no-cache'})
+      LockBox.stubs(:get).with("/authentication/123456", any_parameters).returns(successful_response)
+      bad_response = mock("MockResponse")
+      bad_response.stubs(:code).returns(401)
+      bad_response.stubs(:headers).returns({'Cache-Control' => 'public,no-cache'})
+      LockBox.stubs(:get).with("/authentication/invalid", any_parameters).returns(bad_response)
+    end
+    
+    it "should protect path1" do
+      get "/api/foo?key=invalid"
+      last_response.status.should == 401
+      get "/api/foo?key=123456"
+      last_response.status.should == 200
+    end
+    
+    it "should protect path2" do
+      get "/foo/bar/baz?key=invalid"
+      last_response.status.should == 401
+      get "/foo/bar/baz?key=123456"
+      last_response.status.should == 200
+    end
+    
+    it "should protect path3" do
+      get "/polling_place/lookup?key=invalid"
+      last_response.status.should == 401
+      get "/polling_place/lookup?key=123456"
+      last_response.status.should == 200
+    end
+    
+    it "should not protect other paths" do
+      get "/bar/baz"
+      last_response.status.should == 200
+      last_response.body.should == "successfully hit rails app"
+    end
+    
+    after :each do
+      if @tmp_config_file && @config_file
+        FileUtils.mv(@tmp_config_file, @config_file)
+      end
+    end
+  end
+  
+  context "hitting API actions" do
+    before :each do
+      @max_age = 3600
+      successful_response = mock("MockResponse")
+      successful_response.stubs(:code).returns(200)
+      successful_response.stubs(:headers).returns({'Cache-Control' => "public,max-age=#{@max_age},must-revalidate"})
+      LockBox.stubs(:get).with("/authentication/123456", any_parameters).returns(successful_response)
+      bad_response = mock("MockResponse")
+      bad_response.stubs(:code).returns(401)
+      bad_response.stubs(:headers).returns({'Cache-Control' => 'public,no-cache'})
+      LockBox.stubs(:get).with("/authentication/blah", any_parameters).returns(bad_response)
+    end
+  
+    it "should return 401 for a request that starts with /api with invalid api key" do
+      get "/api/some_controller/some_action?key=blah"
+      last_response.status.should == 401
+    end
+      
+    it "should return 200 for a request that starts with /api and has api key" do
+      get "/api/some_controller/some_action?key=123456"
+      last_response.status.should == 200
+    end
+    
+    it "should cache lockbox responses for max-age when Cache-Control allows it" do
+      get "/api/some_controller/some_action?key=123456"
+      last_response.status.should == 200
+      bad_response = mock("MockResponse")
+      bad_response.stubs(:headers).returns({'Cache-Control' => 'public,no-cache'})
+      bad_response.stubs(:code).returns(401)
+      LockBox.stubs(:get).with("/authentication/123456", any_parameters).returns(bad_response)
+      get "/api/some_controller/some_action?key=123456"
+      last_response.status.should == 200
+    end
+    
+    it "should expire cached lockbox responses when max-age seconds have passed" do
+      get "/api/some_controller/some_action?key=123456"
+      last_response.status.should == 200
+      bad_response = mock("MockResponse")
+      bad_response.stubs(:headers).returns({'Cache-Control' => 'public,no-cache'})
+      bad_response.stubs(:code).returns(401)
+      LockBox.stubs(:get).with("/authentication/123456", any_parameters).returns(bad_response)
+      expired_time = @max_age.seconds.since(Time.now)
+      Time.stubs(:now).returns(expired_time)
+      get "/api/some_controller/some_action?key=123456"
+      last_response.status.should == 401
+    end
+    
+    it "should not cache lockbox responses when Cache-Control does not allow it" do
+      successful_response = mock("MockResponse")
+      successful_response.stubs(:code).returns(200)
+      successful_response.stubs(:headers).returns({'Cache-Control' => 'public,no-cache'})
+      LockBox.stubs(:get).with("/authentication/123456", any_parameters).returns(successful_response)
+      get "/api/some_controller/some_action?key=123456"
+      last_response.status.should == 200
+      bad_response = mock("MockResponse")
+      bad_response.stubs(:code).returns(401)
+      bad_response.stubs(:headers).returns({'Cache-Control' => 'public,no-cache'})
+      LockBox.stubs(:get).with("/authentication/123456", any_parameters).returns(bad_response)
+      get "/api/some_controller/some_action?key=123456"
+      last_response.status.should == 401
+    end
+    
+    it "should pass along the rate limit headers to the client if they exist" do
+      successful_response = mock("MockResponse")
+      successful_response.stubs(:code).returns(200)
+      headers = {
+        'X-RateLimit-Limit' => '100',
+        'X-RateLimit-Remaining' => '99',
+        'X-RateLimit-Reset' => 1.hour.from_now.to_i.to_s
+      }
+      successful_response.stubs(:headers).returns(headers.merge({'Cache-Control' => 'public,no-cache'}))
+      LockBox.stubs(:get).with("/authentication/123456", any_parameters).returns(successful_response)
+      get "/api/some_controller/some_action?key=123456"
+      headers.each_pair do |header,value|
+        # just tests that the headers are present; the stubs above ensure the values are what we expect
+        last_response.headers[header].should == value
+      end
+    end
+  
+  end
+  
+  context "hitting API actions with HMAC auth" do
+    before :each do
+      successful_response = mock("MockResponse")
+      successful_response.stubs(:code).returns(200)
+      successful_response.stubs(:headers).returns({'Cache-Control' => 'public, no-cache'})
+      Time.stubs(:now).returns(Time.parse("2010-05-10 16:30:00 EDT"))
+      valid_headers = {'X-Referer-Method' => 'GET', 'X-Referer-Date' => [Time.now.httpdate], 'X-Referer-Authorization' => ['AuthHMAC key-id:uxx+EgyzWBKBgS+Y8MzpcWcfy7k='], 'Referer' => 'http://example.org/api/some_controller/some_action'}
+      LockBox.stubs(:get).with("/authentication/hmac", {:headers => valid_headers}).returns(successful_response)
+      
+      bad_response = mock("MockResponse")
+      bad_response.stubs(:code).returns(401)
+      bad_response.stubs(:headers).returns({'Cache-Control' => 'public, no-cache'})
+      invalid_headers = {'X-Referer-Method' => 'GET', 'X-Referer-Date' => [Time.now.httpdate], 'X-Referer-Authorization' => 'foo', 'Referer' => 'http://example.org/api/some_controller/some_action'}
+      LockBox.stubs(:get).with("/authentication/hmac", {:headers => invalid_headers}).returns(bad_response)
+      
+      @path = "/api/some_controller/some_action"
+      
+      hmac_request = Net::HTTP::Get.new(@path, {'Date' => Time.now.httpdate})
+      store = mock("MockStore")
+      store.stubs(:[]).with('key-id').returns("123456")
+      authhmac = AuthHMAC.new(store)
+      authhmac.sign!(hmac_request, 'key-id')
+      @hmac_headers = hmac_request.to_hash
+    end
+    
+    it "should return 200 for an HMAC request with a valid auth header" do
+      @hmac_headers.each_pair do |key,value|
+        header key, value
+      end
+      get @path
+      last_response.status.should == 200
+    end
+    
+    it "should return 401 for an HMAC request with an invalid auth header" do
+      @hmac_headers['authorization'] = 'foo'
+      @hmac_headers.each_pair do |key,value|
+        header key, value
+      end
+      get @path
+      last_response.status.should == 401
+    end
+  end
+  
+  context "hitting actions without API" do
+  
+    it "should not try to authenticate a request that doesn't start with /api" do
+      get "/"
+      last_response.status.should == 200
+      last_response.body.should == "successfully hit rails app"
+    end
+  
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,27 @@
+# This file is copied to ~/spec when you run 'ruby script/generate rspec'
+# from the project root directory.
+ENV["RAILS_ENV"] ||= 'test'
+env_file = File.expand_path(File.join(File.dirname(__FILE__),'..','config','environment'))
+if File.exists?("#{env_file}.rb")
+  require env_file
+  require 'spec/autorun'
+  require 'spec/rails'
+  require 'authlogic/test_case'
+else
+  require 'rubygems'
+  require 'mocha' # gem install jferris-mocha, not regular mocha
+end
+
+# Requires supporting files with custom matchers and macros, etc,
+# in ./support/ and its subdirectories.
+Dir[File.expand_path(File.join(File.dirname(__FILE__),'support','**','*.rb'))].each {|f| require f}
+
+Spec::Runner.configure do |config|
+  if defined?(Rails)
+    config.use_transactional_fixtures = true
+    config.use_instantiated_fixtures  = false
+    config.fixture_path = RAILS_ROOT + '/spec/fixtures/'
+    config.include(Authlogic::TestCase)
+  end
+  config.mock_with Mocha::API
+end

data/spec/support/mocha.rb

@@ -0,0 +1,13 @@
+module Mocha
+  module API
+    def setup_mocks_for_rspec
+      mocha_setup
+    end
+    def verify_mocks_for_rspec
+      mocha_verify
+    end
+    def teardown_mocks_for_rspec
+      mocha_teardown
+    end 
+  end
+end

metadata

@@ -0,0 +1,110 @@
+--- !ruby/object:Gem::Specification 
+name: lockbox_middleware
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 1
+  - 2
+  - 0
+  version: 1.2.0
+platform: ruby
+authors: 
+- Chris Gill
+- Brian Cardarella
+- Nathan Woodhull
+- Wes Morgan
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-06-15 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: httparty
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 5
+        - 2
+        version: 0.5.2
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: auth-hmac
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rack
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - "="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 1
+        - 0
+        version: 1.1.0
+  type: :runtime
+  version_requirements: *id003
+description: Rack middleware for the Lockbox centralized API authorization service. Brought to you by the DNC Innovation Lab.
+email: innovationlab@dnc.org
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+files: 
+- lib/lockbox_cache.rb
+- lib/lockbox_middleware.rb
+- LICENSE
+- README.rdoc
+has_rdoc: true
+homepage: 
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: Centralized API authorization
+test_files: 
+- spec/lib/lockbox_middleware_spec.rb
+- spec/spec_helper.rb
+- spec/support/mocha.rb