dreamwords-oauth2 0.8.1

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,35 @@
+.rvmrc
+/live
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+doc
+rdoc
+log
+
+## BUNDLER
+*.gem
+.bundle
+pkg
+Gemfile.lock
+
+## RCOV
+coverage.data
+
+## PROJECT::SPECIFIC
+.svn
+
+## Rubinius
+*.rbc

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--order random

data/.travis.yml

@@ -0,0 +1,13 @@
+language: ruby
+matrix:
+  allow_failures:
+    - rvm: jruby-18mode
+rvm:
+  - rbx-18mode
+  - rbx-19mode
+  - jruby-18mode
+  - jruby-19mode
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3
+  - ruby-head

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE.md

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Intridea, Inc. and Michael Bleigh
+
+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,135 @@
+# OAuth2 [![Build Status](https://secure.travis-ci.org/intridea/oauth2.png?branch=master)][travis] [![Dependency Status](https://gemnasium.com/intridea/oauth2.png?travis)][gemnasium]
+A Ruby wrapper for the OAuth 2.0 specification. This is a work in progress,
+being built first to solve the pragmatic process of connecting to existing
+OAuth 2.0 endpoints (a.k.a. Facebook) with the goal of building it up to meet
+the entire specification over time.
+
+[travis]: http://travis-ci.org/intridea/oauth2
+[gemnasium]: https://gemnasium.com/intridea/oauth2
+
+## Installation
+    gem install oauth2
+
+## Resources
+* [View Source on GitHub][code]
+* [Report Issues on GitHub][issues]
+* [Read More at the Wiki][wiki]
+
+[code]: https://github.com/intridea/oauth2
+[issues]: https://github.com/intridea/oauth2/issues
+[wiki]: https://wiki.github.com/intridea/oauth2
+
+## Usage Examples
+    require 'oauth2'
+    client = OAuth2::Client.new('client_id', 'client_secret', :site => 'https://example.org')
+
+    client.auth_code.authorize_url(:redirect_uri => 'http://localhost:8080/oauth2/callback')
+    # => "https://example.org/oauth/authorization?response_type=code&client_id=client_id&redirect_uri=http://localhost:8080/oauth2/callback"
+
+    token = client.auth_code.get_token('authorization_code_value', :redirect_uri => 'http://localhost:8080/oauth2/callback', :headers => {'Authorization' => 'Basic some_password'})
+    response = token.get('/api/resource', :params => { 'query_foo' => 'bar' })
+    response.class.name
+    # => OAuth2::Response
+
+## OAuth2::Response
+The AccessToken methods #get, #post, #put and #delete and the generic #request
+will return an instance of the #OAuth2::Response class.
+
+This instance contains a #parsed method that will parse the response body and
+return a Hash if the Content-Type is application/x-www-form-urlencoded or if
+the body is a JSON object.  It will return an Array if the body is a JSON
+array.  Otherwise, it will return the original body string.
+
+The original response body, headers, and status can be accessed via their
+respective methods.
+
+## OAuth2::AccessToken
+If you have an existing Access Token for a user, you can initialize an instance
+using various class methods including the standard new, from_hash (if you have
+a hash of the values), or from_kvform (if you have an
+application/x-www-form-urlencoded encoded string of the values).
+
+## OAuth2::Error
+On 400+ status code responses, an OAuth2::Error will be raised.  If it is a
+standard OAuth2 error response, the body will be parsed and #code and #description will contain the values provided from the error and
+error_description parameters.  The #response property of OAuth2::Error will
+always contain the OAuth2::Response instance.
+
+If you do not want an error to be raised, you may use :raise_errors => false
+option on initialization of the client.  In this case the OAuth2::Response
+instance will be returned as usual and on 400+ status code responses, the
+Response instance will contain the OAuth2::Error instance.
+
+## Authorization Grants
+Currently the Authorization Code, Implicit, Resource Owner Password Credentials, Client Credentials, and Assertion
+authentication grant types have helper strategy classes that simplify client
+use.  They are available via the #auth_code, #implicit, #password, #client_credentials, and #assertion methods respectively.
+
+    auth_url = client.auth_code.authorize_url(:redirect_uri => 'http://localhost:8080/oauth/callback')
+    token = client.auth_code.get_token('code_value', :redirect_uri => 'http://localhost:8080/oauth/callback')
+
+    auth_url = client.implicit.authorize_url(:redirect_uri => 'http://localhost:8080/oauth/callback')
+    # get the token params in the callback and
+    token = OAuth2::AccessToken.from_kvform(client, query_string)
+
+    token = client.password.get_token('username', 'password')
+
+    token = client.client_credentials.get_token
+
+    token = client.assertion.get_token(assertion_params)
+
+If you want to specify additional headers to be sent out with the
+request, add a 'headers' hash under 'params':
+
+    token = client.auth_code.get_token('code_value', :redirect_uri => 'http://localhost:8080/oauth/callback', :headers => {'Some' => 'Header'})
+
+You can always use the #request method on the OAuth2::Client instance to make
+requests for tokens for any Authentication grant type.
+
+## Submitting a Pull Request
+1. [Fork the repository.][fork]
+2. [Create a topic branch.][branch]
+3. Add specs for your unimplemented feature or bug fix.
+4. Run `bundle exec rake spec`. If your specs pass, return to step 3.
+5. Implement your feature or bug fix.
+6. Run `bundle exec rake spec`. If your specs fail, return to step 5.
+7. Run `open coverage/index.html`. If your changes are not completely covered
+   by your tests, return to step 3.
+8. Add, commit, and push your changes.
+9. [Submit a pull request.][pr]
+
+[fork]: http://help.github.com/fork-a-repo/
+[branch]: http://learn.github.com/p/branching.html
+[pr]: http://help.github.com/send-pull-requests/
+
+## Supported Ruby Versions
+This library aims to support and is [tested against][travis] the following Ruby
+implementations:
+
+* Ruby 1.8.7
+* Ruby 1.9.2
+* Ruby 1.9.3
+* [JRuby][]
+* [Rubinius][]
+
+[jruby]: http://www.jruby.org/
+[rubinius]: http://rubini.us/
+
+If something doesn't work on one of these interpreters, it should be considered
+a bug.
+
+This library may inadvertently work (or seem to work) on other Ruby
+implementations, however support will only be provided for the versions listed
+above.
+
+If you would like this library to support another Ruby version, you may
+volunteer to be a maintainer. Being a maintainer entails making sure all tests
+run and pass on that implementation. When something breaks on your
+implementation, you will be personally responsible for providing patches in a
+timely fashion. If critical issues for a particular implementation exist at the
+time of a major release, support for that Ruby version may be dropped.
+
+## Copyright
+Copyright (c) 2011 Intridea, Inc. and Michael Bleigh.
+See [LICENSE][] for details.
+[license]: https://github.com/intridea/oauth2/blob/master/LICENSE.md

data/Rakefile

@@ -0,0 +1,19 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+task :test => :spec
+
+namespace :doc do
+  require 'rdoc/task'
+  require File.expand_path('../lib/oauth2/version', __FILE__)
+  RDoc::Task.new do |rdoc|
+    rdoc.rdoc_dir = 'rdoc'
+    rdoc.title = "oauth2 #{OAuth2::Version}"
+    rdoc.main = 'README.md'
+    rdoc.rdoc_files.include('README.md', 'LICENSE.md', 'lib/**/*.rb')
+  end
+end

data/lib/oauth2.rb

@@ -0,0 +1,10 @@
+require 'oauth2/error'
+require 'oauth2/client'
+require 'oauth2/strategy/base'
+require 'oauth2/strategy/auth_code'
+require 'oauth2/strategy/implicit'
+require 'oauth2/strategy/password'
+require 'oauth2/strategy/client_credentials'
+require 'oauth2/strategy/assertion'
+require 'oauth2/access_token'
+require 'oauth2/response'

data/lib/oauth2/access_token.rb

@@ -0,0 +1,157 @@
+module OAuth2
+  class AccessToken
+    attr_reader :client, :token, :refresh_token, :expires_in, :expires_at, :params
+    attr_accessor :options
+
+    class << self
+      # Initializes an AccessToken from a Hash
+      #
+      # @param [Client] the OAuth2::Client instance
+      # @param [Hash] a hash of AccessToken property values
+      # @return [AccessToken] the initalized AccessToken
+      def from_hash(client, hash)
+        self.new(client, hash.delete('access_token') || hash.delete(:access_token), hash)
+      end
+
+      # Initializes an AccessToken from a key/value application/x-www-form-urlencoded string
+      #
+      # @param [Client] client the OAuth2::Client instance
+      # @param [String] kvform the application/x-www-form-urlencoded string
+      # @return [AccessToken] the initalized AccessToken
+      def from_kvform(client, kvform)
+        from_hash(client, Rack::Utils.parse_query(kvform))
+      end
+    end
+
+    # Initalize an AccessToken
+    #
+    # @param [Client] client the OAuth2::Client instance
+    # @param [String] token the Access Token value
+    # @param [Hash] opts the options to create the Access Token with
+    # @option opts [String] :refresh_token (nil) the refresh_token value
+    # @option opts [FixNum, String] :expires_in (nil) the number of seconds in which the AccessToken will expire
+    # @option opts [FixNum, String] :expires_at (nil) the epoch time in seconds in which AccessToken will expire
+    # @option opts [Symbol] :mode (:header) the transmission mode of the Access Token parameter value
+    #    one of :header, :body or :query
+    # @option opts [String] :header_format ('Bearer %s') the string format to use for the Authorization header
+    # @option opts [String] :param_name ('bearer_token') the parameter name to use for transmission of the
+    #    Access Token value in :body or :query transmission mode
+    def initialize(client, token, opts={})
+      @client = client
+      @token = token.to_s
+      [:refresh_token, :expires_in, :expires_at].each do |arg|
+        instance_variable_set("@#{arg}", opts.delete(arg) || opts.delete(arg.to_s))
+      end
+      @expires_in ||= opts.delete('expires')
+      @expires_in &&= @expires_in.to_i
+      @expires_at &&= @expires_at.to_i
+      @expires_at ||= Time.now.to_i + @expires_in if @expires_in
+      @options = {:mode          => opts.delete(:mode) || :header,
+                  :header_format => opts.delete(:header_format) || 'Bearer %s',
+                  :param_name    => opts.delete(:param_name) || 'bearer_token'}
+      @params = opts
+    end
+
+    # Indexer to additional params present in token response
+    #
+    # @param [String] key entry key to Hash
+    def [](key)
+      @params[key]
+    end
+
+    # Whether or not the token expires
+    #
+    # @return [Boolean]
+    def expires?
+      !!@expires_at
+    end
+
+    # Whether or not the token is expired
+    #
+    # @return [Boolean]
+    def expired?
+      expires? && (expires_at < Time.now.to_i)
+    end
+
+    # Refreshes the current Access Token
+    #
+    # @return [AccessToken] a new AccessToken
+    # @note options should be carried over to the new AccessToken
+    def refresh!(params={})
+      raise "A refresh_token is not available" unless refresh_token
+      params.merge!(:client_id      => @client.id,
+                    :client_secret  => @client.secret,
+                    :grant_type     => 'refresh_token',
+                    :refresh_token  => refresh_token)
+      new_token = @client.get_token(params)
+      new_token.options = options
+      new_token
+    end
+
+    # Make a request with the Access Token
+    #
+    # @param [Symbol] verb the HTTP request method
+    # @param [String] path the HTTP URL path of the request
+    # @param [Hash] opts the options to make the request with
+    # @see Client#request
+    def request(verb, path, opts={}, &block)
+      set_token(opts)
+      @client.request(verb, path, opts, &block)
+    end
+
+    # Make a GET request with the Access Token
+    #
+    # @see AccessToken#request
+    def get(path, opts={}, &block)
+      request(:get, path, opts, &block)
+    end
+
+    # Make a POST request with the Access Token
+    #
+    # @see AccessToken#request
+    def post(path, opts={}, &block)
+      request(:post, path, opts, &block)
+    end
+
+    # Make a PUT request with the Access Token
+    #
+    # @see AccessToken#request
+    def put(path, opts={}, &block)
+      request(:put, path, opts, &block)
+    end
+
+    # Make a DELETE request with the Access Token
+    #
+    # @see AccessToken#request
+    def delete(path, opts={}, &block)
+      request(:delete, path, opts, &block)
+    end
+
+    # Get the headers hash (includes Authorization token)
+    def headers
+      { 'Authorization' => options[:header_format] % token }
+    end
+
+  private
+    def set_token(opts)
+      case options[:mode]
+      when :header
+        opts[:headers] ||= {}
+        opts[:headers].merge!(headers)
+      when :query
+        opts[:params] ||= {}
+        opts[:params][options[:param_name]] = token
+      when :body
+        opts[:body] ||= {}
+        if opts[:body].is_a?(Hash)
+          opts[:body][options[:param_name]] = token
+        else
+          opts[:body] << "&#{options[:param_name]}=#{token}"
+        end
+        # @todo support for multi-part (file uploads)
+      else
+        raise "invalid :mode option of #{options[:mode]}"
+      end
+    end
+  end
+end

data/lib/oauth2/client.rb

@@ -0,0 +1,168 @@
+require 'faraday'
+
+module OAuth2
+  # The OAuth2::Client class
+  class Client
+    attr_reader :id, :secret
+    attr_accessor :site, :connection, :options
+
+    # Instantiate a new OAuth 2.0 client using the
+    # Client ID and Client Secret registered to your
+    # application.
+    #
+    # @param [String] client_id the client_id value
+    # @param [String] client_secret the client_secret value
+    # @param [Hash] opts the options to create the client with
+    # @option opts [String] :site the OAuth2 provider site host
+    # @option opts [String] :authorize_url ('/oauth/authorize') absolute or relative URL path to the Authorization endpoint
+    # @option opts [String] :token_url ('/oauth/token') absolute or relative URL path to the Token endpoint
+    # @option opts [Symbol] :token_method (:post) HTTP method to use to request token (:get or :post)
+    # @option opts [Hash] :connection_opts ({}) Hash of connection options to pass to initialize Faraday with
+    # @option opts [FixNum] :max_redirects (5) maximum number of redirects to follow
+    # @option opts [Boolean] :raise_errors (true) whether or not to raise an OAuth2::Error
+    #  on responses with 400+ status codes
+    # @yield [builder] The Faraday connection builder
+    def initialize(client_id, client_secret, opts={}, &block)
+      @id = client_id
+      @secret = client_secret
+      @site = opts.delete(:site)
+      ssl = opts.delete(:ssl)
+      @options = {:authorize_url    => '/oauth/authorize',
+                  :token_url        => '/oauth/token',
+                  :token_method     => :post,
+                  :connection_opts  => {},
+                  :connection_build => block,
+                  :max_redirects    => 5,
+                  :raise_errors     => true}.merge(opts)
+      @options[:connection_opts][:ssl] = ssl if ssl
+    end
+
+    # Set the site host
+    #
+    # @param [String] the OAuth2 provider site host
+    def site=(value)
+      @connection = nil
+      @site = value
+    end
+
+    # The Faraday connection object
+    def connection
+      @connection ||= begin
+        conn = Faraday.new(site, options[:connection_opts])
+        conn.build do |b|
+          options[:connection_build].call(b)
+        end if options[:connection_build]
+        conn
+      end
+    end
+
+    # The authorize endpoint URL of the OAuth2 provider
+    #
+    # @param [Hash] params additional query parameters
+    def authorize_url(params=nil)
+      connection.build_url(options[:authorize_url], params).to_s
+    end
+
+    # The token endpoint URL of the OAuth2 provider
+    #
+    # @param [Hash] params additional query parameters
+    def token_url(params=nil)
+      connection.build_url(options[:token_url], params).to_s
+    end
+
+    # Makes a request relative to the specified site root.
+    #
+    # @param [Symbol] verb one of :get, :post, :put, :delete
+    # @param [String] url URL path of request
+    # @param [Hash] opts the options to make the request with
+    # @option opts [Hash] :params additional query parameters for the URL of the request
+    # @option opts [Hash, String] :body the body of the request
+    # @option opts [Hash] :headers http request headers
+    # @option opts [Boolean] :raise_errors whether or not to raise an OAuth2::Error on 400+ status
+    #   code response for this request.  Will default to client option
+    # @option opts [Symbol] :parse @see Response::initialize
+    # @yield [req] The Faraday request
+    def request(verb, url, opts={})
+      url = self.connection.build_url(url, opts[:params]).to_s
+
+      response = connection.run_request(verb, url, opts[:body], opts[:headers]) do |req|
+        yield(req) if block_given?
+      end
+      response = Response.new(response, :parse => opts[:parse])
+
+      case response.status
+      when 301, 302, 303, 307
+        opts[:redirect_count] ||= 0
+        opts[:redirect_count] += 1
+        return response if opts[:redirect_count] > options[:max_redirects]
+        if response.status == 303
+          verb = :get
+          opts.delete(:body)
+        end
+        request(verb, response.headers['location'], opts)
+      when 200..299, 300..399
+        # on non-redirecting 3xx statuses, just return the response
+        response
+      when 400..599
+        e = Error.new(response)
+        raise e if opts[:raise_errors] || options[:raise_errors]
+        response.error = e
+        response
+      else
+        raise Error.new(response), "Unhandled status code value of #{response.status}"
+      end
+    end
+
+    # Initializes an AccessToken by making a request to the token endpoint
+    #
+    # @param [Hash] params a Hash of params for the token endpoint
+    # @param [Hash] access token options, to pass to the AccessToken object
+    # @return [AccessToken] the initalized AccessToken
+    def get_token(params, access_token_opts={})
+      opts = {:raise_errors => options[:raise_errors], :parse => params.delete(:parse)}
+      if options[:token_method] == :post
+        headers = params.delete(:headers)
+        opts[:body] = params
+        opts[:headers] =  {'Content-Type' => 'application/x-www-form-urlencoded'}
+        opts[:headers].merge!(headers) if headers
+      else
+        opts[:params] = params
+      end
+      response = request(options[:token_method], token_url, opts)
+      raise Error.new(response) if options[:raise_errors] && !(response.parsed.is_a?(Hash) && response.parsed['access_token'])
+      AccessToken.from_hash(self, response.parsed.merge(access_token_opts))
+    end
+
+    # The Authorization Code strategy
+    #
+    # @see http://tools.ietf.org/html/draft-ietf-oauth-v2-15#section-4.1
+    def auth_code
+      @auth_code ||= OAuth2::Strategy::AuthCode.new(self)
+    end
+
+    # The Implicit strategy
+    #
+    # @see http://tools.ietf.org/html/draft-ietf-oauth-v2-26#section-4.2
+    def implicit
+      @implicit ||= OAuth2::Strategy::Implicit.new(self)
+    end
+
+    # The Resource Owner Password Credentials strategy
+    #
+    # @see http://tools.ietf.org/html/draft-ietf-oauth-v2-15#section-4.3
+    def password
+      @password ||= OAuth2::Strategy::Password.new(self)
+    end
+
+    # The Client Credentials strategy
+    #
+    # @see http://tools.ietf.org/html/draft-ietf-oauth-v2-15#section-4.4
+    def client_credentials
+      @client_credentials ||= OAuth2::Strategy::ClientCredentials.new(self)
+    end
+
+    def assertion
+      @assertion ||= OAuth2::Strategy::Assertion.new(self)
+    end
+  end
+end