oauthenticator 0.1.4 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: dce07a7cd57f37e9644bbcfa1d9463af0bb3aaaf
-  data.tar.gz: e6e8c3fba86aca134288dfe1bb2a1644a8a543e9
+  metadata.gz: 7006ebe89c4cd63acc4c40c404a81cd1d435c671
+  data.tar.gz: 54399c9d2d96645797f5bf0c179a46ac3aa0e47d
 SHA512:
-  metadata.gz: 05375a2021880cc799ac90c4ce03c03bb0b39968841bb1922244e749da54199ba65a7893ae550e330ce1a139841ab2a77d236f26cb4c91d48f5824873a631095
-  data.tar.gz: 8bfedffd4be1a4a3231f65421699eb1f8baee29587ced7d537a0606c85ae34d79445adfd157c7677cc6be854510abc7ca3803bca6d9b515a40822e51462114e9
+  metadata.gz: 85859997c9cba4592b097443e643528c6ccc479542eb0410e64a57611c6226a0988314d0b8adb3a17e3e0ae08b823d45a6bbeb75f0f15ca6c298c4b5581859ab
+  data.tar.gz: b1776d367f14799e6fcf5da5e09ed4c6c97cc932d86969c19c06bdcb99ac81827396c8d227fd445a64cbb8ae71f561a9ae4d7da9d65c6dfef67b3b788ce2c142

data/.simplecov

@@ -0,0 +1 @@
+SimpleCov.start

data/README.md

@@ -1,9 +1,89 @@
 # OAuthenticator
 
-OAuthenticator authenticates OAuth 1.0 signed requests, primarily as a middleware, and forms useful error 
-messages when authentication fails. 
+OAuthenticator signs outgoing requests with OAuth 1.0. 
 
-## Config Methods module
+OAuthenticator authenticates incoming OAuth 1.0 signed requests, primarily as a middleware, and forms useful 
+error messages when authentication fails. 
+
+Note: The canonical location of this README is on [RubyDoc](http://rubydoc.info/gems/oauthenticator/). When 
+viewed on [Github](https://github.com/notEthan/oauthenticator/), it may be inconsistent with the latest 
+released gem, and Yardoc links will not work.
+
+## Signing outgoing requests
+
+### Faraday
+
+OAuthenticator provides Faraday middleware for easy signing of outgoing requests. This request middleware is 
+registered with faraday named `:oauthenticator_signer`.
+
+The middleware should be in the stack immediately before the adapter. Any other middleware that modifies the 
+request between OAuthenticator signing it and the request actually being made may render the signature 
+invalid. 
+
+See the documentation for {OAuthenticator::FaradaySigner} for more detailed information.
+
+An example:
+
+```ruby
+require 'oauthenticator'
+
+signing_options = {
+  :signature_method => 'HMAC-SHA1',
+  :consumer_key => 'a consumer',
+  :consumer_secret => 'a consumer secret',
+  :token => 'a token',
+  :token_secret => 'a token secret',
+  :realm => 'The Realm',
+}
+
+connection = Faraday.new('http://example.com/') do |faraday|
+  faraday.request :url_encoded
+  faraday.request :oauthenticator_signer, signing_options
+  faraday.adapter Faraday.default_adapter
+end
+
+connection.get '/path'
+```
+
+Note that `:url_encoded` is only included to illustrate that other middleware should all go before 
+`:oauthenticator_signer`; the use of `:url_encoded` is not related to OAuthenticator. 
+
+### Any other HTTP library
+
+Generating an Authorization header to apply to an outgoing request is a relatively straightforward affair:
+
+```ruby
+oauthenticator_signable_request = OAuthenticator::SignableRequest.new(
+  :request_method => my_request_method,
+  :uri => my_request_uri,
+  :media_type => my_request_media_type,
+  :body => my_request_body,
+  :signature_method => my_oauth_signature_method,
+  :consumer_key => my_oauth_consumer_key,
+  :consumer_secret => my_oauth_consumer_secret,
+  :token => my_oauth_token,
+  :token_secret => my_oauth_token_secret,
+  :realm => my_authorization_realm,
+  :hash_body? => my_body_hashing_requirement
+)
+my_http_request.headers['Authorization'] = oauthenticator_signable_request.authorization
+```
+
+See the documentation for {OAuthenticator::SignableRequest} for more detailed information.
+
+### OAuth Request Body Hash
+
+The [OAuth Request Body Hash](https://oauth.googlecode.com/svn/spec/ext/body_hash/1.0/oauth-bodyhash.html)
+specification is supported. By default all signing of outgoing does include the body hash. This can be 
+disabled by setting the `:hash_body?` / `'hash_body?'` attribute to false when instantiating an 
+OAuthenticator::SignableRequest. 
+
+For info on when to include the body hash, see 
+[When to Include the Body Hash](https://oauth.googlecode.com/svn/spec/ext/body_hash/1.0/oauth-bodyhash.html#when_to_include). 
+
+## Authenticating incoming requests
+
+### Config Methods module
 
 There are many ways (infinite, really) in which certain parts of the OAuth spec may be implemented. In order 
 to flexibly accomodate the general case of OAuth authentication, OAuthenticator leaves certain parts of the 
@@ -11,11 +91,11 @@ implementation up to the user. The user configures this by creating a module imp
 which will be passed to OAuthenticator.
 
 For more information on the details of the methods which must or may be implemented, please see the 
-documentation for the module `OAuthenticator::ConfigMethods`, which defines stub methods for 
+documentation for the module {OAuthenticator::ConfigMethods}, which defines stub methods for 
 each recognized method, with method documentation relating to your implementation.
 
 A simple, contrived example follows, which approximately resembles what you might implement. It is not useful 
-on its own but will be used in following examples for usage of Middleware and SignedRequest. 
+on its own but will be used in following examples for usage of RackAuthenticator and SignedRequest. 
 
 ```ruby
 require 'oauthenticator'
@@ -29,7 +109,7 @@ require 'oauthenticator'
 # - OAuthConsumer
 #   - key
 #   - secret
-# - OAuthAccessToken
+# - OAuthToken
 #   - token
 #   - secret
 #   - consumer_key
@@ -62,60 +142,63 @@ module AwesomeOAuthConfig
     OAuthConsumer.where(:key => consumer_key).first.try(:secret)
   end
 
-  # access token secret, looked up by access token 
-  def access_token_secret
-    OAuthAccessToken.where(:token => token).first.try(:secret)
+  # token secret, looked up by token 
+  def token_secret
+    OAuthToken.where(:token => token).first.try(:secret)
   end
 
-  # whether the access token belongs to the consumer 
-  def access_token_belongs_to_consumer?
-    OAuthAccessToken.where(:token => token).first.try(:consumer_key) == consumer_key
+  # whether the token belongs to the consumer 
+  def token_belongs_to_consumer?
+    OAuthToken.where(:token => token).first.try(:consumer_key) == consumer_key
     # alternately:
-    # OAuthAccessToken.where(:token => token, :consumer_key => consumer_key).any?
+    # OAuthToken.where(:token => token, :consumer_key => consumer_key).any?
+  end
+
+  # whether oauth_body_hash_is_required (this method defaults to false and may be omitted)
+  def body_hash_required?
+    false
   end
 end
 ```
 
-You may also find it enlightening to peruse `test/oauthenticator_test.rb`. About the first thing it does is 
-set up some very simple storage in memory, and define a module of config methods which are used through the 
-tests. 
+You may also find it enlightening to peruse `test/test_config_methods.rb`, which sets up some very simple 
+storage in memory, and defines a module of config methods which are used through the tests. 
 
-## OAuthenticator::Middleware
+### OAuthenticator::RackAuthenticator
 
-The middleware is used by passing the above-mentioned module on the `:config_methods` key to  initialize the 
-middleware:
+The RackAuthenticator middleware is used by passing the above-mentioned module on the `:config_methods` key to 
+initialize the middleware:
 
 ```ruby
 # config.ru
 
-use OAuthenticator::Middleware, :config_methods => AwesomeOAuthConfig
+use OAuthenticator::RackAuthenticator, :config_methods => AwesomeOAuthConfig
 run proc { |env| [200, {'Content-Type' => 'text/plain'}, ['access granted!']] }
 ```
 
 The authentication can also be bypassed with a proc on the `:bypass` key; see the documentation for 
-`OAuthenticator::Middleware` for the details of that. 
+{OAuthenticator::RackAuthenticator} for the details of that. 
 
-## OAuthenticator::SignedRequest
+### OAuthenticator::SignedRequest
 
-The OAuthenticator::SignedRequest class may be used independently of the middleware, though it must also be 
-passed your module of config methods to include. It is used like:
+The OAuthenticator::SignedRequest class may be used independently of the RackAuthenticator middleware, though 
+it must also be passed your module of config methods to include. It is used like:
 
 ```ruby
 OAuthenticator::SignedRequest.including_config(AwesomeOAuthConfig).new(request_attrs)
 ```
 
-See the documentation of OAuthenticator::SignedRequest for how the class is used, once it includes the methods 
-it needs to function. 
+See the documentation of {OAuthenticator::SignedRequest} for how the class is used, once it includes the 
+methods it needs to function. 
 
-# Other
+### OAuth Request Body Hash
 
-## SimpleOAuth
+The [OAuth Request Body Hash](https://oauth.googlecode.com/svn/spec/ext/body_hash/1.0/oauth-bodyhash.html)
+specification is supported. Requests which include the oauth_body_hash parameter are authenticated according 
+to the spec. 
 
-OAuthenticator uses [SimpleOAuth](https://github.com/laserlemon/simple_oauth) underneath. There is a 
-fork with some improvements that have not yet made it into the main SimpleOAuth repo, and it is recommended 
-to use these for more robust and safe parsing of the Authorization header. This is not published in rubygems, 
-but if you use Bundler, you can use this by using the following line in your `Gemfile`;
+Requests which may include the oauth_body_hash parameter but do not are accepted or rejected based on the 
+config method `#body_hash_required?` - if the implementation indicates that oauth_body_hash is required, then 
+the request is rejected as inauthentic; if it is not required then the request is allowed (assuming all other 
+aspects of the OAuth signature are authentic.) 
 
-```ruby
-gem 'simple_oauth', :git => 'https://github.com/notEthan/simple_oauth.git', :tag => 'ethan-v0.2.0.2'
-```

data/Rakefile.rb

@@ -0,0 +1,11 @@
+require 'rake/testtask'
+Rake::TestTask.new do |t|
+  t.name = 'test'
+  t.test_files = FileList['test/**/*_test.rb']
+  t.verbose = true
+end
+task 'default' => 'test'
+
+require 'yard'
+YARD::Rake::YardocTask.new do |t|
+end

data/lib/oauthenticator.rb

@@ -1,6 +1,5 @@
-require "oauthenticator/version"
-
-module OAuthenticator
-  autoload :Middleware, 'oauthenticator/middleware'
-  autoload :SignedRequest, 'oauthenticator/signed_request'
-end
+require 'oauthenticator/version'
+require 'oauthenticator/signed_request'
+require 'oauthenticator/signable_request'
+require 'oauthenticator/rack_authenticator'
+require 'oauthenticator/faraday_signer'

data/lib/oauthenticator/config_methods.rb

@@ -1,14 +1,19 @@
 module OAuthenticator
-  # This module contains stubs, or in some cases default values, for implementations of particulars of the OAuth protocol. Applications must implement some of these, and are likely to want to override the default values of others. certain methods will need to use methods of the {OAuthenticator::SignedRequest} class.
+  # This module contains stubs, or in some cases default values, for implementations of particulars of the 
+  # OAuth protocol. Applications must implement some of these, and are likely to want to override the default 
+  # values of others. certain methods will need to use methods of the {OAuthenticator::SignedRequest} class.
   #
-  # the methods your implementation will need to be used are primarily those from the parsed OAuth Authorization header. these are methods your implementation WILL need to use to implement the required functionality:
+  # the methods your implementation will need to be used are primarily those from the parsed OAuth 
+  # Authorization header. these are methods your implementation WILL need to use to implement the required 
+  # functionality:
   #
   # - `#consumer_key`
   # - `#token`
   # - `#nonce`
   # - `#timestamp`
   #
-  # the following are the other parts of the Authorization, but your implementation will probably NOT need to use these (OAuthenticator does everything that is needed to validate these parts):
+  # the following are the other parts of the Authorization, but your implementation will probably NOT need to 
+  # use these (OAuthenticator does everything that is needed to validate these parts):
   #
   # - `#version`
   # - `#signature_method`
@@ -16,9 +21,12 @@ module OAuthenticator
   module ConfigMethods
     # the number of seconds (integer) in both the past and future for which the request is considered valid. 
     #
-    # if it is desired to have a different period considered valid in the past than in the future, then the methods {#timestamp_valid_past} and {#timestamp_valid_future} may be implemented instead, and this method may remain unimplemented. 
+    # if it is desired to have a different period considered valid in the past than in the future, then the 
+    # methods {#timestamp_valid_past} and {#timestamp_valid_future} may be implemented instead, and this 
+    # method may remain unimplemented. 
     #
-    # see the documentation for {#timestamp_valid_past} and {#timestamp_valid_future} for other considerations of the valid period. 
+    # see the documentation for {#timestamp_valid_past} and {#timestamp_valid_future} for other considerations 
+    # of the valid period. 
     #
     # @return [Integer] period in seconds
     def timestamp_valid_period
@@ -27,9 +35,11 @@ module OAuthenticator
 
     # the number of seconds (integer) in the past for which the request is considered valid. 
     #
-    # if the timestamp is more than this number of seconds less than the current clock time, then the request is considered invalid and the response is an error. 
+    # if the timestamp is more than this number of seconds less than the current clock time, then the request 
+    # is considered invalid and the response is an error. 
     #
-    # this should be large enough to allow for clock skew between your application's server and the requester's clock. 
+    # this should be large enough to allow for clock skew between your application's server and the 
+    # requester's clock. 
     #
     # nonces older than Time.now - timestamp_valid_past may be discarded.
     #
@@ -42,9 +52,11 @@ module OAuthenticator
 
     # the number of seconds (integer) in the future for which the request is considered valid. 
     #
-    # if the timestamp is more than this number of seconds greater than the current clock time, then the request is considered invalid and the response is an error. 
+    # if the timestamp is more than this number of seconds greater than the current clock time, then the 
+    # request is considered invalid and the response is an error. 
     #
-    # this should be large enough to allow for clock skew between your application's server and the requester's clock. 
+    # this should be large enough to allow for clock skew between your application's server and the 
+    # requester's clock. 
     #
     # this method may remain unimplemented if {#timestamp_valid_period} is implemented. 
     #
@@ -53,48 +65,77 @@ module OAuthenticator
       timestamp_valid_period
     end
 
-    # the signature methods which the application will accept. this MUST be a subset of the signature methods defined in the OAuth 1.0 protocol: `%w(HMAC-SHA1 RSA-SHA1 PLAINTEXT)`. the default value for this is all allowed signature methods, and may remain unimplemented if you wish to allow all defined signature methods. 
+    # the signature methods which the application will accept. this MUST be a subset of the signature methods 
+    # defined in the OAuth 1.0 protocol: `%w(HMAC-SHA1 RSA-SHA1 PLAINTEXT)`. the default value for this is all 
+    # allowed signature methods, and may remain unimplemented if you wish to allow all defined signature 
+    # methods. 
     #
     # @return [Array<String>]
     def allowed_signature_methods
-      OAuthenticator::SignedRequest::VALID_SIGNATURE_METHODS
+      SignableRequest::SIGNATURE_METHODS.keys
     end
 
-    # this should look up the consumer secret in your application's storage corresponding to the request's consumer key, which is available via the `#consumer_key` method. see the README for an example implementation.
+    # this should look up the consumer secret in your application's storage corresponding to the request's 
+    # consumer key, which is available via the `#consumer_key` method. see the README for an example 
+    # implementation.
     #
     # @return [String] the consumer secret for the request's consumer key
     def consumer_secret
       config_method_not_implemented
     end
 
-    # this should look up the access token secret in your application's storage corresponding to the request's access token, which is available via the `#token` method. see the README for an example implementation.
+    # this should look up the token secret in your application's storage corresponding to the request's 
+    # token, which is available via the `#token` method. see the README for an example implementation.
     #
-    # @return [String] the access token secret for the request's access token
-    def access_token_secret
+    # @return [String] the token secret for the request's token
+    def token_secret
       config_method_not_implemented
     end
 
-    # whether the nonce, available via the `#nonce` method, has already been used. you may wish to use this in conjunction with the timestamp (`#timestamp`), per the OAuth 1.0 spec.
+    # whether the nonce, available via the `#nonce` method, has already been used. you may wish to use this in 
+    # conjunction with the timestamp (`#timestamp`), per the OAuth 1.0 spec.
     #
-    # it's worth noting that if this ever returns true, it may indicate a replay attack under way against your application. the replay attack will fail due to OAuth, but you may wish to log the event.
+    # it's worth noting that if this ever returns true, it may indicate a replay attack under way against your 
+    # application. the replay attack will fail due to OAuth, but you may wish to log the event.
     #
     # @return [Boolean] whether the request's nonce has already been used.
     def nonce_used?
       config_method_not_implemented
     end
 
-    # cause the nonce, available via the `#nonce` method, to be marked as used. you may wish to use this in conjunction with the timestamp (`#timestamp`).
+    # cause the nonce, available via the `#nonce` method, to be marked as used. you may wish to use this in 
+    # conjunction with the timestamp (`#timestamp`).
     #
     # @return [Void] (return value is ignored / unused)
     def use_nonce!
       config_method_not_implemented
     end
 
-    # whether the access token indicated by the request (via `#token`) belongs to the consumer indicated by the request (via `#consumer_key`). 
+    # whether the token indicated by the request (via `#token`) belongs to the consumer indicated by 
+    # the request (via `#consumer_key`). 
     #
-    # @return [Boolean] whether the request's access token belongs to the request's consumer 
-    def access_token_belongs_to_consumer?
+    # this method may simply return true if the implementation does not care to restrict tokens by 
+    # consumer. 
+    #
+    # @return [Boolean] whether the request's token belongs to the request's consumer 
+    def token_belongs_to_consumer?
       config_method_not_implemented
     end
+
+    # whether the request will be considered valid if it is missing the oauth_body_hash parameter, when that 
+    # parameter is allowed. if you require requests to include the oauth_body_hash parameter, return true 
+    # here. 
+    #
+    # the default for this method is false, since the oauth body hash is not widely implemented. 
+    #
+    # this only applies to requests which are NOT form encoded - requests which are form-encoded must never 
+    # have the oauth_body_hash parameter regardless of this setting and will be rejected as inauthentic, per 
+    # the OAuth Request Body Hash spec. this also does not apply to requests with a signature method which 
+    # does not have a corresponding body hash method - i.e., the PLAINTEXT signature method.
+    #
+    # @return [Boolean] whether body hash is required
+    def body_hash_required?
+      false
+    end
   end
 end

data/lib/oauthenticator/faraday_signer.rb

@@ -0,0 +1,66 @@
+require 'faraday'
+
+if Faraday.respond_to?(:register_middleware)
+  Faraday.register_middleware(:request, :oauthenticator_signer => proc { OAuthenticator::FaradaySigner })
+end
+if Faraday::Request.respond_to?(:register_middleware)
+  Faraday::Request.register_middleware(:oauthenticator_signer => proc { OAuthenticator::FaradaySigner })
+end
+
+module OAuthenticator
+  # OAuthenticator Faraday middleware to sign outgoing requests.
+  #
+  # The middleware should be in the stack immediately before the adapter. Any other middleware that modifies 
+  # the request between OAuthenticator signing it and the request actually being made may render the signature 
+  # invalid. 
+  #
+  # This request middleware is registered as `:oauthenticator_signer`. It should be used like
+  #
+  #     connection = Faraday.new('http://example.com/') do |faraday|
+  #       faraday.request :url_encoded
+  #       faraday.request :oauthenticator_signer, signing_options
+  #       faraday.adapter Faraday.default_adapter
+  #     end
+  #
+  # Note that `:url_encoded` is only included to illustrate that other middleware should all go before 
+  # `:oauthenticator_signer`; the use of `:url_encoded` is not related to OAuthenticator. 
+  #
+  # See {#initialize} for details of what the `signing_options` hash should include. 
+  class FaradaySigner
+    # options are passed to {OAuthenticator::SignableRequest}. 
+    #
+    # attributes of the request are added by the middleware, so you should not provide those as optiosn 
+    # (it would not make sense to do so on the connection level). 
+    #
+    # These are the options you should or may provide (see {OAuthenticator::SignableRequest} for details of 
+    # what options are required, what options have default or generated values, and what may be omitted):
+    #
+    # - signature_method
+    # - consumer_key
+    # - consumer_secret
+    # - token
+    # - token_secret
+    # - version
+    # - realm
+    # - hash_body?
+    def initialize(app, options)
+      @app = app
+      @options = options
+    end
+
+    # do the thing
+    def call(request_env)
+      request_attributes = {
+        :request_method => request_env[:method],
+        :uri => request_env[:url],
+        :media_type => request_env[:request_headers]['Content-Type'],
+        :body => request_env[:body]
+      }
+      oauthenticator_signable_request = OAuthenticator::SignableRequest.new(@options.merge(request_attributes))
+      authorization = oauthenticator_signable_request.authorization
+      signed_request_headers = request_env[:request_headers].merge('Authorization' => authorization)
+      signed_request_env = request_env.merge(:request_headers => signed_request_headers)
+      @app.call(signed_request_env)
+    end
+  end
+end