dropbox-sdk 1.5.1 → 1.6

data/CHANGELOG

@@ -1,3 +1,7 @@
+1.6 (2013-07-07)
+* Added OAuth 2 support (DropboxOAuth2Flow).  OAuth 1 still works.
+* Fixed many minor bugs.
+
 1.5.1 (2012-8-20)
 * Fixed packaging.
 

data/README

@@ -1,7 +1,52 @@
-Getting started with the Dropbox Ruby SDK:
-1.  Install json and oauth ruby gems with:
-    gem install json oauth
-2.  Edit cli_example.rb to to include your APP_KEY and APP_SECRET
-3.  Try running the example app: 'ruby cli_example.rb'.
-4.  See dropbox_controller.rb for an example Ruby on Rails controller.  It needs an APP_KEY and APP_SECRET set too.
-5.  Check out the dropbox website for reference and help! http://dropbox.com/developers_beta
+Dropbox Core SDK for Ruby
+
+A Ruby library that for Dropbox's HTTP-based Core API.
+
+   https://www.dropbox.com/developers/core/docs
+
+----------------------------------
+Setup
+
+You can install this package using 'pip':
+
+   # pip install dropbox
+
+----------------------------------
+Getting a Dropbox API key
+
+You need a Dropbox API key to make API requests.
+- Go to: https://dropbox.com/developers/apps
+- If you've already registered an app, click on the "Options" link to see the
+  app's API key and secret.
+- Otherwise, click "Create an app" to register an app.  Choose "Full Dropbox" or
+  "App Folder" depending on your needs.
+  See: https://www.dropbox.com/developers/reference#permissions
+
+----------------------------------
+Using the Dropbox API
+
+Full documentation: https://www.dropbox.com/developers/core/
+
+Before your app can access a Dropbox user's files, the user must authorize your
+application using OAuth 2.  Successfully completing this authorization flow
+gives you an "access token" for the user's Dropbox account, which grants you the
+ability to make Dropbox API calls to access their files.
+
+- Authorization example for a web app: web_file_browser.rb
+- Authorization example for a command-line tool:
+  https://www.dropbox.com/developers/core/start/ruby
+
+Once you have an access token, create a DropboxClient instance and start making
+API calls.
+
+You only need to perform the authorization process once per user.  Once you have
+an access token for a user, save it somewhere persistent, like in a database.
+The next time that user visits your app, you can skip the authorization process
+and go straight to making API calls.
+
+----------------------------------
+Running the Examples
+
+There are example programs included in the tarball.  Before you can run an
+example, you need to edit the ".rb" file and put your Dropbox API app key and
+secret in the "APP_KEY" and "APP_SECRET" constants.

data/cli_example.rb

@@ -12,10 +12,6 @@ require 'pp'
 # Find this at https://www.dropbox.com/developers
 APP_KEY = ''
 APP_SECRET = ''
-ACCESS_TYPE = :app_folder #The two valid values here are :app_folder and :dropbox
-                          #The default is :app_folder, but your application might be
-                          #set to have full :dropbox access.  Check your app at
-                          #https://www.dropbox.com/developers/apps
 
 class DropboxCLI
     LOGIN_REQUIRED = %w{put get cp mv rm ls mkdir info logout search thumbnail}
@@ -27,37 +23,28 @@ class DropboxCLI
             exit
         end
 
-        @session = DropboxSession.new(APP_KEY, APP_SECRET)
         @client = nil
     end
 
     def login
-        ########
-        # Instead of going to a authorize URL, you can set a access token key and secret
-        # from a previous session
-        ########
-        # @session.set_access_token('key', 'secret')
-
-        if @session.authorized?
-           puts "already logged in!"
+        if not @client.nil?
+            puts "already logged in!"
         else
+            web_auth = DropboxOAuth2FlowNoRedirect.new(APP_KEY, APP_SECRET)
+            authorize_url = web_auth.start()
+            puts "1. Go to: #{authorize_url}"
+            puts "2. Click \"Allow\" (you might have to log in first)."
+            puts "3. Copy the authorization code."
 
-            # grab the request token for session
-            @session.get_request_token
+            print "Enter the authorization code here: "
+            STDOUT.flush
+            auth_code = STDIN.gets.strip
 
-            authorize_url = @session.get_authorize_url
-            puts "Got a request token.  Your request token key is #{@session.request_token.key} and your token secret is #{@session.request_token.secret}"
-
-            # make the user log in and authorize this token
-            puts "AUTHORIZING", authorize_url, "Please visit that web page and hit 'Allow', then hit Enter here."
-            gets
-
-            # get the access token from the server. Its then stored in the session.
-            @session.get_access_token
+            access_token, user_id = web_auth.finish(auth_code)
 
+            @client = DropboxClient.new(access_token)
+            puts "You are logged in.  Your access token is #{access_token}."
         end
-        puts "You are logged in.  Your access token key is #{@session.access_token.key} your secret is #{@session.access_token.secret}"
-        @client = DropboxClient.new(@session, ACCESS_TYPE)
     end
 
     def command_loop
@@ -96,9 +83,8 @@ class DropboxCLI
     end
 
     def logout(command)
-        @session.clear_access_token
-        puts "You are logged out."
         @client = nil
+        puts "You are logged out."
     end
 
     def put(command)

data/dropbox_controller.rb

@@ -1,57 +1,107 @@
-require 'dropbox_sdk'
+# ---------------------------------------------------------------------------------------
+# A Rails 3 controller that:
+# - Runs the through Dropbox's OAuth 2 flow, yielding a Dropbox API access token.
+# - Makes a Dropbox API call to upload a file.
+#
+# To run:
+# 1. You need a Rails 3 project (to create one, run: rails new <folder-name>)
+# 2. Copy this file into <folder-name>/app/controllers/
+# 3. Add the following lines to <folder-name>/config/routes.rb
+#        get  "dropbox/main"
+#        post "dropbox/upload"
+#        get  "dropbox/auth_start"
+#        get  "dropbox/auth_finish"
+# 4. Run: rails server
+# 5. Point your browser at: https://localhost:3000/dropbox/main
 
-# This is an example of a Rails 3 controller that authorizes an application
-# and then uploads a file to the user's Dropbox.
+require '../lib/dropbox_sdk'
+require 'securerandom'
 
-# You must set these
 APP_KEY = ""
 APP_SECRET = ""
-ACCESS_TYPE = :app_folder #The two valid values here are :app_folder and :dropbox
-                          #The default is :app_folder, but your application might be
-                          #set to have full :dropbox access.  Check your app at
-                          #https://www.dropbox.com/developers/apps
 
+class DropboxController < ApplicationController
 
-# Examples routes for config/routes.rb  (Rails 3)
-#match 'db/authorize', :controller => 'db', :action => 'authorize'
-#match 'db/upload', :controller => 'db', :action => 'upload'
+    def main
+        client = get_dropbox_client
+        unless client
+            redirect_to(:action => 'auth_start') and return
+        end
 
-class DbController < ApplicationController
-    def authorize
-        if not params[:oauth_token] then
-            dbsession = DropboxSession.new(APP_KEY, APP_SECRET)
+        account_info = client.account_info
 
-            session[:dropbox_session] = dbsession.serialize #serialize and save this DropboxSession
+        # Show a file upload page
+        render :inline =>
+            "#{account_info['email']} <br/><%= form_tag({:action => :upload}, :multipart => true) do %><%= file_field_tag 'file' %><%= submit_tag 'Upload' %><% end %>"
+    end
 
-            #pass to get_authorize_url a callback url that will return the user here
-            redirect_to dbsession.get_authorize_url url_for(:action => 'authorize')
-        else
-            # the user has returned from Dropbox
-            dbsession = DropboxSession.deserialize(session[:dropbox_session])
-            dbsession.get_access_token  #we've been authorized, so now request an access_token
-            session[:dropbox_session] = dbsession.serialize
+    def upload
+        client = get_dropbox_client
+        unless client
+            redirect_to(:action => 'auth_start') and return
+        end
 
-            redirect_to :action => 'upload'
+        begin
+            # Upload the POST'd file to Dropbox, keeping the same name
+            resp = client.put_file(params[:file].original_filename, params[:file].read)
+            render :text => "Upload successful.  File now at #{resp['path']}"
+        rescue DropboxAuthError => e
+            session.delete(:access_token)  # An auth error means the access token is probably bad
+            logger.info "Dropbox auth error: #{e}"
+            render :text => "Dropbox auth error"
+        rescue DropboxError => e
+            logger.info "Dropbox API error: #{e}"
+            render :text => "Dropbox API error"
         end
     end
 
-    def upload
-        # Check if user has no dropbox session...re-direct them to authorize
-        return redirect_to(:action => 'authorize') unless session[:dropbox_session]
-
-        dbsession = DropboxSession.deserialize(session[:dropbox_session])
-        client = DropboxClient.new(dbsession, ACCESS_TYPE) #raise an exception if session not authorized
-        info = client.account_info # look up account information
-
-        if request.method != "POST"
-            # show a file upload page
-            render :inline =>
-                "#{info['email']} <br/><%= form_tag({:action => :upload}, :multipart => true) do %><%= file_field_tag 'file' %><%= submit_tag %><% end %>"
-            return
-        else
-            # upload the posted file to dropbox keeping the same name
-            resp = client.put_file(params[:file].original_filename, params[:file].read)
-            render :text => "Upload successful! File now at #{resp['path']}"
+    def get_dropbox_client
+        if session[:access_token]
+            begin
+                access_token = session[:access_token]
+                DropboxClient.new(access_token)
+            rescue
+                # Maybe something's wrong with the access token?
+                session.delete(:access_token)
+                raise
+            end
+        end
+    end
+
+    def get_web_auth()
+        redirect_uri = url_for(:action => 'auth_finish')
+        DropboxOAuth2Flow.new(APP_KEY, APP_SECRET, redirect_uri, session, :dropbox_auth_csrf_token)
+    end
+
+    def auth_start
+        authorize_url = get_web_auth().start()
+
+        # Send the user to the Dropbox website so they can authorize our app.  After the user
+        # authorizes our app, Dropbox will redirect them here with a 'code' parameter.
+        redirect_to authorize_url
+    end
+
+    def auth_finish
+        begin
+            access_token, user_id, url_state = get_web_auth.finish(params)
+            session[:access_token] = access_token
+            redirect_to :action => 'main'
+        rescue DropboxOAuth2Flow::BadRequestError => e
+            render :text => "Error in OAuth 2 flow: Bad request: #{e}"
+        rescue DropboxOAuth2Flow::BadStateError => e
+            logger.info("Error in OAuth 2 flow: No CSRF token in session: #{e}")
+            redirect_to(:action => 'auth_start')
+        rescue DropboxOAuth2Flow::CsrfError => e
+            logger.info("Error in OAuth 2 flow: CSRF mismatch: #{e}")
+            render :text => "CSRF error"
+        rescue DropboxOAuth2Flow::NotApprovedError => e
+            render :text => "Not approved?  Why not, bro?"
+        rescue DropboxOAuth2Flow::ProviderError => e
+            logger.info "Error in OAuth 2 flow: Error redirect from Dropbox: #{e}"
+            render :text => "Strange error."
+        rescue DropboxError => e
+            logger.info "Error getting OAuth 2 access token: #{e}"
+            render :text => "Error communicating with Dropbox servers."
         end
     end
 end

data/lib/dropbox_sdk.rb

@@ -4,6 +4,9 @@ require 'net/https'
 require 'cgi'
 require 'json'
 require 'yaml'
+require 'base64'
+require 'securerandom'
+require 'pp'
 
 module Dropbox # :nodoc:
     API_SERVER = "api.dropbox.com"
@@ -11,36 +14,17 @@ module Dropbox # :nodoc:
     WEB_SERVER = "www.dropbox.com"
     
     API_VERSION = 1
-    SDK_VERSION = "1.5.1"
+    SDK_VERSION = "1.6"
 
     TRUSTED_CERT_FILE = File.join(File.dirname(__FILE__), 'trusted-certs.crt')
-end
-
-# DropboxSession is responsible for holding OAuth information.  It knows how to take your consumer key and secret
-# and request an access token, an authorize url, and get an access token.  You just need to pass it to
-# DropboxClient after its been authorized.
-class DropboxSession
-
-    # * consumer_key - Your Dropbox application's "app key".
-    # * consumer_secret - Your Dropbox application's "app secret".
-    def initialize(consumer_key, consumer_secret)
-        @consumer_key = consumer_key
-        @consumer_secret = consumer_secret
-        @request_token = nil
-        @access_token = nil
-    end
-
-    private
 
-    def do_http(uri, auth_token, request) # :nodoc:
+    def self.do_http(uri, request) # :nodoc:
         http = Net::HTTP.new(uri.host, uri.port)
 
         http.use_ssl = true
-        enable_cert_checking(http)
+        http.verify_mode = OpenSSL::SSL::VERIFY_PEER
         http.ca_file = Dropbox::TRUSTED_CERT_FILE
 
-        request.add_field('Authorization', build_auth_header(auth_token))
-
         #We use this to better understand how developers are using our SDKs.
         request['User-Agent'] =  "OfficialDropboxRubySDK/#{Dropbox::SDK_VERSION}"
 
@@ -48,38 +32,69 @@ class DropboxSession
             http.request(request)
         rescue OpenSSL::SSL::SSLError => e
             raise DropboxError.new("SSL error connecting to Dropbox.  " +
-                                   "There may be a problem with the set of certificates in \"#{Dropbox::TRUSTED_CERT_FILE}\".  " +
-                                   e)
+                                   "There may be a problem with the set of certificates in \"#{Dropbox::TRUSTED_CERT_FILE}\".  #{e}")
         end
     end
 
-    def enable_cert_checking(http)
-        http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+    # Parse response. You probably shouldn't be calling this directly.  This takes responses from the server
+    # and parses them.  It also checks for errors and raises exceptions with the appropriate messages.
+    def self.parse_response(response, raw=false) # :nodoc:
+        if response.kind_of?(Net::HTTPServerError)
+            raise DropboxError.new("Dropbox Server Error: #{response} - #{response.body}", response)
+        elsif response.kind_of?(Net::HTTPUnauthorized)
+            raise DropboxAuthError.new("User is not authenticated.", response)
+        elsif not response.kind_of?(Net::HTTPSuccess)
+            begin
+                d = JSON.parse(response.body)
+            rescue
+                raise DropboxError.new("Dropbox Server Error: body=#{response.body}", response)
+            end
+            if d['user_error'] and d['error']
+                raise DropboxError.new(d['error'], response, d['user_error'])  #user_error is translated
+            elsif d['error']
+                raise DropboxError.new(d['error'], response)
+            else
+                raise DropboxError.new(response.body, response)
+            end
+        end
+
+        return response.body if raw
+
+        begin
+            return JSON.parse(response.body)
+        rescue JSON::ParserError
+            raise DropboxError.new("Unable to parse JSON response: #{response.body}", response)
+        end
     end
 
-    def build_auth_header(token) # :nodoc:
-        header = "OAuth oauth_version=\"1.0\", oauth_signature_method=\"PLAINTEXT\", " +
-            "oauth_consumer_key=\"#{URI.escape(@consumer_key)}\", "
-        if token
-            key = URI.escape(token.key)
-            secret = URI.escape(token.secret)
-            header += "oauth_token=\"#{key}\", oauth_signature=\"#{URI.escape(@consumer_secret)}&#{secret}\""
+    # A string comparison function that is resistant to timing attacks.  If you're comparing a
+    # string you got from the outside world with a string that is supposed to be a secret, use
+    # this function to check equality.
+    def self.safe_string_equals(a, b)
+        if a.length != b.length
+            false
         else
-            header += "oauth_signature=\"#{URI.escape(@consumer_secret)}&\""
+            a.chars.zip(b.chars).map {|ac,bc| ac == bc}.all?
         end
-        header
     end
+end
 
-    def do_get_with_token(url, token, headers=nil) # :nodoc:
-        uri = URI.parse(url)
-        do_http(uri, token, Net::HTTP::Get.new(uri.request_uri))
+class DropboxSessionBase # :nodoc:
+
+    protected
+
+    def do_http(uri, request) # :nodoc:
+        sign_request(request)
+        Dropbox::do_http(uri, request)
     end
 
     public
 
     def do_get(url, headers=nil)  # :nodoc:
         assert_authorized
-        do_get_with_token(url, @access_token)
+        uri = URI.parse(url)
+        request = Net::HTTP::Get.new(uri.request_uri)
+        do_http(uri, request)
     end
 
     def do_http_with_body(uri, request, body)
@@ -103,7 +118,7 @@ class DropboxSession
                 request.body = s
             end
         end
-        do_http(uri, @access_token, request)
+        do_http(uri, request)
     end
 
     def do_post(url, headers=nil, body=nil)  # :nodoc:
@@ -117,7 +132,51 @@ class DropboxSession
         uri = URI.parse(url)
         do_http_with_body(uri, Net::HTTP::Put.new(uri.request_uri, headers), body)
     end
+end
 
+# DropboxSession is responsible for holding OAuth 1 information.  It knows how to take your consumer key and secret
+# and request an access token, an authorize url, and get an access token.  You just need to pass it to
+# DropboxClient after its been authorized.
+class DropboxSession < DropboxSessionBase  # :nodoc:
+
+    # * consumer_key - Your Dropbox application's "app key".
+    # * consumer_secret - Your Dropbox application's "app secret".
+    def initialize(consumer_key, consumer_secret)
+        @consumer_key = consumer_key
+        @consumer_secret = consumer_secret
+        @request_token = nil
+        @access_token = nil
+    end
+
+    private
+
+    def build_auth_header(token) # :nodoc:
+        header = "OAuth oauth_version=\"1.0\", oauth_signature_method=\"PLAINTEXT\", " +
+            "oauth_consumer_key=\"#{URI.escape(@consumer_key)}\", "
+        if token
+            key = URI.escape(token.key)
+            secret = URI.escape(token.secret)
+            header += "oauth_token=\"#{key}\", oauth_signature=\"#{URI.escape(@consumer_secret)}&#{secret}\""
+        else
+            header += "oauth_signature=\"#{URI.escape(@consumer_secret)}&\""
+        end
+        header
+    end
+
+    def do_get_with_token(url, token, headers=nil) # :nodoc:
+        uri = URI.parse(url)
+        request = Net::HTTP::Get.new(uri.request_uri)
+        request.add_field('Authorization', build_auth_header(token))
+        Dropbox::do_http(uri, request)
+    end
+
+    protected
+
+    def sign_request(request)  # :nodoc:
+        request.add_field('Authorization', build_auth_header(@access_token))
+    end
+
+    public
 
     def get_token(url_end, input_token, error_message_prefix) #: nodoc:
         response = do_get_with_token("https://#{Dropbox::API_SERVER}:443/#{Dropbox::API_VERSION}/oauth#{url_end}", input_token)
@@ -193,7 +252,7 @@ class DropboxSession
         return @access_token if authorized?
 
         if @request_token.nil?
-            raise DropboxAuthError.new("No request token. You must set this or get an authorize url first.")
+            raise RuntimeError.new("No request token. You must set this or get an authorize url first.")
         end
 
         @access_token = get_token("/access_token", @request_token,  "Couldn't get access token.")
@@ -244,6 +303,302 @@ class DropboxSession
 end
 
 
+class DropboxOAuth2Session < DropboxSessionBase  # :nodoc:
+    def initialize(oauth2_access_token)
+        if not oauth2_access_token.is_a?(String)
+            raise "bad type for oauth2_access_token (expecting String)"
+        end
+        @access_token = oauth2_access_token
+    end
+
+    def assert_authorized
+        true
+    end
+
+    protected
+
+    def sign_request(request)  # :nodoc:
+        request.add_field('Authorization', 'Bearer ' + @access_token)
+    end
+end
+
+# Base class for the two OAuth 2 authorization helpers.
+class DropboxOAuth2FlowBase  # :nodoc:
+    def initialize(consumer_key, consumer_secret, locale=nil)
+        if not consumer_key.is_a?(String)
+            raise ArgumentError, "consumer_key must be a String, got #{consumer_key.inspect}"
+        end
+        if not consumer_secret.is_a?(String)
+            raise ArgumentError, "consumer_secret must be a String, got #{consumer_secret.inspect}"
+        end
+        if not (locale.nil? or locale.is_a?(String))
+            raise ArgumentError, "locale must be a String or nil, got #{locale.inspect}"
+        end
+        @consumer_key = consumer_key
+        @consumer_secret = consumer_secret
+        @locale = locale
+    end
+
+    def _get_authorize_url(redirect_uri, state)
+        params = {"client_id" => @consumer_key, "response_type" => "code"}
+        if not redirect_uri.nil?
+            params["redirect_uri"] = redirect_uri
+        end
+        if not state.nil?
+            params["state"] = state
+        end
+        if not @locale.nil?
+            params['locale'] = @locale
+        end
+
+        host = Dropbox::WEB_SERVER
+        path = "/#{Dropbox::API_VERSION}/oauth2/authorize"
+
+        target = URI::Generic.new("https", nil, host, nil, nil, path, nil, nil, nil)
+
+        target.query = params.collect {|k,v|
+            CGI.escape(k) + "=" + CGI.escape(v)
+        }.join("&")
+
+        target.to_s
+    end
+
+    # Finish the OAuth 2 authorization process.  If you used a redirect_uri, pass that in.
+    # Will return an access token string that you can use with DropboxClient.
+    def _finish(code, original_redirect_uri)
+        if not code.is_a?(String)
+            raise ArgumentError, "code must be a String"
+        end
+
+        uri = URI.parse("https://#{Dropbox::API_SERVER}/1/oauth2/token")
+        request = Net::HTTP::Post.new(uri.request_uri)
+        client_credentials = @consumer_key + ':' + @consumer_secret
+        request.add_field('Authorization', 'Basic ' + Base64.encode64(client_credentials).chomp("\n"))
+
+        params = {
+            "grant_type" => "authorization_code",
+            "code" => code,
+        }
+
+        if not @locale.nil?
+            params['locale'] = @locale
+        end
+        if not original_redirect_uri.nil?
+            params['redirect_uri'] = original_redirect_uri
+        end
+
+        form_data = {}
+        params.each {|k,v| form_data[k.to_s] = v if !v.nil?}
+        request.set_form_data(form_data)
+
+        response = Dropbox::do_http(uri, request)
+
+        j = Dropbox::parse_response(response)
+        ["token_type", "access_token", "uid"].each { |k|
+            if not j.has_key?(k)
+                raise DropboxError.new("Bad response from /token: missing \"#{k}\".")
+            end
+            if not j[k].is_a?(String)
+                raise DropboxError.new("Bad response from /token: field \"#{k}\" is not a string.")
+            end
+        }
+        if j["token_type"] != "bearer" and j["token_type"] != "Bearer":
+            raise DropboxError.new("Bad response from /token: \"token_type\" is \"#{token_type}\".")
+        end
+
+        return j['access_token'], j['uid']
+    end
+end
+
+# OAuth 2 authorization helper for apps that can't provide a redirect URI
+# (such as the command line example apps).
+class DropboxOAuth2FlowNoRedirect < DropboxOAuth2FlowBase
+
+    # * consumer_key: Your Dropbox API app's "app key"
+    # * consumer_secret: Your Dropbox API app's "app secret"
+    # * locale: The locale of the user currently using your app.
+    def initialize(consumer_key, consumer_secret, locale=nil)
+        super(consumer_key, consumer_secret, locale)
+    end
+
+    # Returns a authorization_url, which is a page on Dropbox's website.  Have the user
+    # visit this URL and approve your app.
+    def start()
+        _get_authorize_url(nil, nil)
+    end
+
+    # If the user approves your app, they will be presented with an "authorization code".
+    # Have the user copy/paste that authorization code into your app and then call this
+    # method to get an access token.
+    #
+    # Returns a two-entry list (access_token, user_id)
+    # * access_token is an access token string that can be passed to DropboxClient.
+    # * user_id is the Dropbox user ID of the user that just approved your app.
+    def finish(code)
+        _finish(code, nil)
+    end
+end
+
+# The standard OAuth 2 authorization helper.  Use this if you're writing a web app.
+class DropboxOAuth2Flow < DropboxOAuth2FlowBase
+
+    # * consumer_key: Your Dropbox API app's "app key"
+    # * consumer_secret: Your Dropbox API app's "app secret"
+    # * redirect_uri: The URI that the Dropbox server will redirect the user to after the user
+    #   finishes authorizing your app.  This URI  must be HTTPs-based and pre-registered with
+    #   the Dropbox servers, though localhost URIs are allowed without pre-registration and can
+    #   be either HTTP or HTTPS.
+    # * session: A hash that represents the current web app session (will be used to save the CSRF
+    #   token)
+    # * csrf_token_key: The key to use when storing the CSRF token in the session (for example,
+    #   :dropbox_auth_csrf_token)
+    # * locale: The locale of the user currently using your app (ex: "en" or "en_US").
+    def initialize(consumer_key, consumer_secret, redirect_uri, session, csrf_token_session_key, locale=nil)
+        super(consumer_key, consumer_secret, locale)
+        if not redirect_uri.is_a?(String)
+            raise ArgumentError, "redirect_uri must be a String, got #{consumer_secret.inspect}"
+        end
+        @redirect_uri = redirect_uri
+        @session = session
+        @csrf_token_session_key = csrf_token_session_key
+    end
+
+    # Starts the OAuth 2 authorizaton process, which involves redirecting the user to
+    # the returned "authorization URL" (a URL on the Dropbox website).  When the user then
+    # either approves or denies your app access, Dropbox will redirect them to the
+    # redirect_uri you provided to the constructor, at which point you should call finish()
+    # to complete the process.
+    #
+    # This function will also save a CSRF token to the session and csrf_token_session_key
+    # you provided to the constructor.  This CSRF token will be checked on finish() to prevent
+    # request forgery.
+    #
+    # * url_state: Any data you would like to keep in the URL through the authorization
+    #   process.  This exact value will be returned to you by finish().
+    #
+    # Returns the URL to redirect the user to.
+    def start(url_state=nil)
+        unless url_state.nil? or url_state.is_a?(String)
+            raise ArgumentError, "url_state must be a String"
+        end
+
+        csrf_token = SecureRandom.base64(16)
+        state = csrf_token
+        unless url_state.nil?
+            state += "|" + url_state
+        end
+        @session[@csrf_token_session_key] = csrf_token
+
+        return _get_authorize_url(@redirect_uri, state)
+    end
+
+    # Call this after the user has visited the authorize URL (see: start()), approved your app,
+    # and was redirected to your redirect URI.
+    #
+    # * query_params: The query params on the GET request to your redirect URI.
+    #
+    # Returns a tuple of (access_token, user_id, url_state).  access_token can be used to
+    # construct a DropboxClient.  user_id is the Dropbox user ID of the user that jsut approved
+    # your app.  url_state is the value you originally passed in to start().
+    #
+    # Can throw BadRequestError, BadStateError, CsrfError, NotApprovedError,
+    # ProviderError, and the standard DropboxError.
+    def finish(query_params)
+        csrf_token_from_session = @session[@csrf_token_session_key]
+
+        # Check well-formedness of request.
+
+        state = query_params['state']
+        if state.nil?
+            raise BadRequestError.new("Missing query parameter 'state'.")
+        end
+
+        error = query_params['error']
+        error_description = query_params['error_description']
+        code = query_params['code']
+
+        if not error.nil? and not code.nil?
+            raise BadRequestError.new("Query parameters 'code' and 'error' are both set;" +
+                                      " only one must be set.")
+        end
+        if error.nil? and code.nil?
+            raise BadRequestError.new("Neither query parameter 'code' or 'error' is set.")
+        end
+
+        # Check CSRF token
+        
+        if csrf_token_from_session.nil?
+            raise BadStateError.new("Missing CSRF token in session.");
+        end
+        unless csrf_token_from_session.length > 20
+            raise RuntimeError.new("CSRF token unexpectedly short: #{csrf_token_from_session.inspect}")
+        end
+
+        split_pos = state.index('|')
+        if split_pos.nil?
+            given_csrf_token = state
+            url_state = nil
+        else
+            given_csrf_token, url_state = state.split('|', 2)
+        end
+        if not Dropbox::safe_string_equals(csrf_token_from_session, given_csrf_token)
+            raise CsrfError.new("Expected #{csrf_token_from_session.inspect}, " +
+                                    "got #{given_csrf_token.inspect}.")
+        end
+        @session.delete(@csrf_token_session_key)
+
+        # Check for error identifier
+        
+        if not error.nil?
+            if error == 'access_denied'
+                # The user clicked "Deny"
+                if error_description.nil?
+                    raise NotApprovedError.new("No additional description from Dropbox.")
+                else
+                    raise NotApprovedError.new("Additional description from Dropbox: #{error_description}")
+                end
+            else
+                # All other errors.
+                full_message = error
+                if not error_description.nil?
+                    full_message += ": " + error_description
+                end
+                raise ProviderError.new(full_message)
+            end
+        end
+
+        # If everything went ok, make the network call to get an access token.
+
+        access_token, user_id = _finish(code, @redirect_uri)
+        return access_token, user_id, url_state
+    end
+
+    # Thrown if the redirect URL was missing parameters or if the given parameters were not valid.
+    #
+    # The recommended action is to show an HTTP 400 error page.
+    class BadRequestError < Exception; end
+
+    # Thrown if all the parameters are correct, but there's no CSRF token in the session.  This
+    # probably means that the session expired.
+    #
+    # The recommended action is to redirect the user's browser to try the approval process again.
+    class BadStateError < Exception; end
+
+    # Thrown if the given 'state' parameter doesn't contain the CSRF token from the user's session.
+    # This is blocked to prevent CSRF attacks.
+    #
+    # The recommended action is to respond with an HTTP 403 error page.
+    class CsrfError < Exception; end
+
+    # The user chose not to approve your app.
+    class NotApprovedError < Exception; end
+
+    # Dropbox redirected to your redirect URI with some unexpected error identifier and error
+    # message.
+    class ProviderError < Exception; end
+end
+
+
 # A class that represents either an OAuth request token or an OAuth access token.
 class OAuthToken # :nodoc:
     def initialize(key, secret)
@@ -289,19 +644,27 @@ end
 class DropboxNotModified < DropboxError
 end
 
-# This is the Dropbox Client API you'll be working with most often.  You need to give it
-# a DropboxSession which has already been authorized, or which it can authorize.
+# Use this class to make Dropbox API calls.  You'll need to obtain an OAuth 2 access token
+# first; you can get one using either DropboxOAuth2Flow or DropboxOAuth2FlowNoRedirect.
 class DropboxClient
 
-    # Initialize a new DropboxClient.  You need to give it a session which has been authorized. See
-    # documentation on DropboxSession for how to authorize it.
-    def initialize(session, root="app_folder", locale=nil)
-        session.get_access_token
+    # Args:
+    # * +oauth2_access_token+: Obtained via DropboxOAuth2Flow or DropboxOAuth2FlowNoRedirect.
+    # * +locale+: The user's current locale (used to localize error messages).
+    def initialize(oauth2_access_token, root="auto", locale=nil)
+        if oauth2_access_token.is_a?(String)
+            @session = DropboxOAuth2Session.new(oauth2_access_token)
+        elsif oauth2_access_token.is_a?(DropboxSession)
+            @session = oauth2_access_token
+            @session.get_access_token
+        else
+            raise ArgumentError.new("oauth2_access_token doesn't have a valid type")
+        end
 
         @root = root.to_s  # If they passed in a symbol, make it a string
 
-        if not ["dropbox","app_folder"].include?(@root)
-            raise DropboxError.new("root must be :dropbox or :app_folder")
+        if not ["dropbox","app_folder","auto"].include?(@root)
+            raise ArgumentError.new("root must be :dropbox, :app_folder, or :auto")
         end
         if @root == "app_folder"
             #App Folder is the name of the access type, but for historical reasons
@@ -310,63 +673,32 @@ class DropboxClient
         end
 
         @locale = locale
-        @session = session
-    end
-
-    # Parse response. You probably shouldn't be calling this directly.  This takes responses from the server
-    # and parses them.  It also checks for errors and raises exceptions with the appropriate messages.
-    def parse_response(response, raw=false) # :nodoc:
-        if response.kind_of?(Net::HTTPServerError)
-            raise DropboxError.new("Dropbox Server Error: #{response} - #{response.body}", response)
-        elsif response.kind_of?(Net::HTTPUnauthorized)
-            raise DropboxAuthError.new(response, "User is not authenticated.")
-        elsif not response.kind_of?(Net::HTTPSuccess)
-            begin
-                d = JSON.parse(response.body)
-            rescue
-                raise DropboxError.new("Dropbox Server Error: body=#{response.body}", response)
-            end
-            if d['user_error'] and d['error']
-                raise DropboxError.new(d['error'], response, d['user_error'])  #user_error is translated
-            elsif d['error']
-                raise DropboxError.new(d['error'], response)
-            else
-                raise DropboxError.new(response.body, response)
-            end
-        end
-
-        return response.body if raw
-
-        begin
-            return JSON.parse(response.body)
-        rescue JSON::ParserError
-            raise DropboxError.new("Unable to parse JSON response: #{response.body}", response)
-        end
     end
 
-    # Returns account info in a Hash object
+    # Returns some information about the current user's Dropbox account (the "current user"
+    # is the user associated with the access token you're using).
     #
     # For a detailed description of what this call returns, visit:
     # https://www.dropbox.com/developers/reference/api#account-info
     def account_info()
         response = @session.do_get build_url("/account/info")
-        parse_response(response)
+        Dropbox::parse_response(response)
     end
 
     # Uploads a file to a server.  This uses the HTTP PUT upload method for simplicity
     #
-    # Arguments:
-    # * to_path: The directory path to upload the file to. If the destination
+    # Args:
+    # * +to_path+: The directory path to upload the file to. If the destination
     #   directory does not yet exist, it will be created.
-    # * file_obj: A file-like object to upload. If you would like, you can
+    # * +file_obj+: A file-like object to upload. If you would like, you can
     #   pass a string as file_obj.
-    # * overwrite: Whether to overwrite an existing file at the given path. [default is False]
+    # * +overwrite+: Whether to overwrite an existing file at the given path. [default is False]
     #   If overwrite is False and a file already exists there, Dropbox
     #   will rename the upload to make sure it doesn't overwrite anything.
     #   You must check the returned metadata to know what this new name is.
     #   This field should only be True if your intent is to potentially
     #   clobber changes to a file that you don't know about.
-    # * parent_rev: The rev field from the 'parent' of this upload. [optional]
+    # * +parent_rev+: The rev field from the 'parent' of this upload. [optional]
     #   If your intent is to update the file at the given path, you should
     #   pass the parent_rev parameter set to the rev value from the most recent
     #   metadata you have of the existing file at that path. If the server
@@ -376,10 +708,11 @@ class DropboxClient
     #   The file will always be overwritten if you send the most-recent parent_rev,
     #   and it will never be overwritten you send a less-recent one.
     # Returns:
-    # * a Hash containing the metadata of the newly uploaded file.  The file may have a different name if it conflicted.
+    # * a Hash containing the metadata of the newly uploaded file.  The file may have a different
+    #   name if it conflicted.
     #
     # Simple Example
-    #  client = DropboxClient(session, :app_folder)
+    #  client = DropboxClient(oauth2_access_token)
     #  #session is a DropboxSession I've already authorized
     #  client.put_file('/test_file_on_dropbox', open('/tmp/test_file'))
     # This will upload the "/tmp/test_file" from my computer into the root of my App's app folder
@@ -398,14 +731,14 @@ class DropboxClient
                                    {"Content-Type" => "application/octet-stream"},
                                    file_obj)
 
-        parse_response(response)
+        Dropbox::parse_response(response)
     end
 
     # Returns a ChunkedUploader object.
     #
     # Args:
-    # * file_obj: The file-like object to be uploaded.  Must support .read()
-    # * total_size: The total size of file_obj
+    # * +file_obj+: The file-like object to be uploaded.  Must support .read()
+    # * +total_size+: The total size of file_obj
     def get_chunked_uploader(file_obj, total_size)
         ChunkedUploader.new(self, file_obj, total_size)
     end
@@ -428,7 +761,7 @@ class DropboxClient
         # be called again to resume the upload.
         #
         # Args:
-        # * chunk_size: The chunk size for each individual upload.  Defaults to 4MB.
+        # * +chunk_size+: The chunk size for each individual upload.  Defaults to 4MB.
         def upload(chunk_size=4*1024*1024)
             last_chunk = nil
 
@@ -439,7 +772,7 @@ class DropboxClient
 
                 resp = {}
                 begin
-                    resp = @client.parse_response(@client.partial_chunked_upload(last_chunk, @upload_id, @offset))
+                    resp = Dropbox::parse_response(@client.partial_chunked_upload(last_chunk, @upload_id, @offset))
                     last_chunk = nil
                 rescue DropboxError => e
                     resp = JSON.parse(e.http_response.body)
@@ -457,9 +790,9 @@ class DropboxClient
         # Completes a file upload
         #
         # Args:
-        # * to_path: The directory path to upload the file to. If the destination
+        # * +to_path+: The directory path to upload the file to. If the destination
         #   directory does not yet exist, it will be created.
-        # * overwrite: Whether to overwrite an existing file at the given path. [default is False]
+        # * +overwrite+: Whether to overwrite an existing file at the given path. [default is False]
         #   If overwrite is False and a file already exists there, Dropbox
         #   will rename the upload to make sure it doesn't overwrite anything.
         #   You must check the returned metadata to know what this new name is.
@@ -481,7 +814,7 @@ class DropboxClient
         #    https://www.dropbox.com/developers/reference/api#metadata
         def finish(to_path, overwrite=false, parent_rev=nil)
             response = @client.commit_chunked_upload(to_path, @upload_id, overwrite, parent_rev)
-            @client.parse_response(response)
+            Dropbox::parse_response(response)
         end
     end
 
@@ -505,28 +838,28 @@ class DropboxClient
     # Download a file
     #
     # Args:
-    # * from_path: The path to the file to be downloaded
-    # * rev: A previous revision value of the file to be downloaded
+    # * +from_path+: The path to the file to be downloaded
+    # * +rev+: A previous revision value of the file to be downloaded
     #
     # Returns:
     # * The file contents.
     def get_file(from_path, rev=nil)
         response = get_file_impl(from_path, rev)
-        parse_response(response, raw=true)
+        Dropbox::parse_response(response, raw=true)
     end
 
     # Download a file and get its metadata.
     #
     # Args:
-    # * from_path: The path to the file to be downloaded
-    # * rev: A previous revision value of the file to be downloaded
+    # * +from_path+: The path to the file to be downloaded
+    # * +rev+: A previous revision value of the file to be downloaded
     #
     # Returns:
     # * The file contents.
     # * The file metadata as a hash.
     def get_file_and_metadata(from_path, rev=nil)
         response = get_file_impl(from_path, rev)
-        parsed_response = parse_response(response, raw=true)
+        parsed_response = Dropbox::parse_response(response, raw=true)
         metadata = parse_metadata(response)
         return parsed_response, metadata
     end
@@ -534,8 +867,8 @@ class DropboxClient
     # Download a file (helper method - don't call this directly).
     #
     # Args:
-    # * from_path: The path to the file to be downloaded
-    # * rev: A previous revision value of the file to be downloaded
+    # * +from_path+: The path to the file to be downloaded
+    # * +rev+: A previous revision value of the file to be downloaded
     #
     # Returns:
     # * The HTTPResponse for the file download request.
@@ -551,7 +884,7 @@ class DropboxClient
     # Parses out file metadata from a raw dropbox HTTP response.
     #
     # Args:
-    # * dropbox_raw_response: The raw, unparsed HTTPResponse from Dropbox.
+    # * +dropbox_raw_response+: The raw, unparsed HTTPResponse from Dropbox.
     #
     # Returns:
     # * The metadata of the file as a hash.
@@ -569,9 +902,9 @@ class DropboxClient
 
     # Copy a file or folder to a new location.
     #
-    # Arguments:
-    # * from_path: The path to the file or folder to be copied.
-    # * to_path: The destination path of the file or folder to be copied.
+    # Args:
+    # * +from_path+: The path to the file or folder to be copied.
+    # * +to_path+: The destination path of the file or folder to be copied.
     #   This parameter should include the destination filename (e.g.
     #   from_path: '/test.txt', to_path: '/dir/test.txt'). If there's
     #   already a file at the to_path, this copy will be renamed to
@@ -588,13 +921,13 @@ class DropboxClient
             "to_path" => format_path(to_path, false),
         }
         response = @session.do_post build_url("/fileops/copy", params)
-        parse_response(response)
+        Dropbox::parse_response(response)
     end
 
     # Create a folder.
     #
     # Arguments:
-    # * path: The path of the new folder.
+    # * +path+: The path of the new folder.
     #
     # Returns:
     # *  A hash with the metadata of the newly created folder.
@@ -607,13 +940,13 @@ class DropboxClient
         }
         response = @session.do_post build_url("/fileops/create_folder", params)
 
-        parse_response(response)
+        Dropbox::parse_response(response)
     end
 
     # Deletes a file
     #
     # Arguments:
-    # * path: The path of the file to delete
+    # * +path+: The path of the file to delete
     #
     # Returns:
     # *  A Hash with the metadata of file just deleted.
@@ -625,14 +958,14 @@ class DropboxClient
             "path" => format_path(path, false),
         }
         response = @session.do_post build_url("/fileops/delete", params)
-        parse_response(response)
+        Dropbox::parse_response(response)
     end
 
     # Moves a file
     #
     # Arguments:
-    # * from_path: The path of the file to be moved
-    # * to_path: The destination path of the file or folder to be moved
+    # * +from_path+: The path of the file to be moved
+    # * +to_path+: The destination path of the file or folder to be moved
     #   If the file or folder already exists, it will be renamed to be unique.
     #
     # Returns:
@@ -646,7 +979,7 @@ class DropboxClient
             "to_path" => format_path(to_path, false),
         }
         response = @session.do_post build_url("/fileops/move", params)
-        parse_response(response)
+        Dropbox::parse_response(response)
     end
 
     # Retrives metadata for a file or folder
@@ -686,7 +1019,7 @@ class DropboxClient
         if response.kind_of? Net::HTTPRedirection
                 raise DropboxNotModified.new("metadata not modified")
         end
-        parse_response(response)
+        Dropbox::parse_response(response)
     end
 
     # Search directory for filenames matching query
@@ -711,7 +1044,7 @@ class DropboxClient
         }
 
         response = @session.do_get build_url("/search/#{@root}#{format_path(path)}", params)
-        parse_response(response)
+        Dropbox::parse_response(response)
     end
 
     # Retrive revisions of a file
@@ -734,7 +1067,7 @@ class DropboxClient
         }
 
         response = @session.do_get build_url("/revisions/#{@root}#{format_path(path)}", params)
-        parse_response(response)
+        Dropbox::parse_response(response)
 
     end
 
@@ -754,7 +1087,7 @@ class DropboxClient
         }
 
         response = @session.do_post build_url("/restore/#{@root}#{format_path(path)}", params)
-        parse_response(response)
+        Dropbox::parse_response(response)
     end
 
     # Returns a direct link to a media file
@@ -771,7 +1104,7 @@ class DropboxClient
     #      {'url': 'https://dl.dropbox.com/0/view/wvxv1fw6on24qw7/file.mov', 'expires': 'Thu, 16 Sep 2011 01:01:25 +0000'}
     def media(path)
         response = @session.do_get build_url("/media/#{@root}#{format_path(path)}")
-        parse_response(response)
+        Dropbox::parse_response(response)
     end
 
     # Get a URL to share a media file
@@ -790,7 +1123,7 @@ class DropboxClient
     #    https://www.dropbox.com/developers/reference/api#shares
     def shares(path)
         response = @session.do_get build_url("/shares/#{@root}#{format_path(path)}")
-        parse_response(response)
+        Dropbox::parse_response(response)
     end
 
     # Download a thumbnail for an image.
@@ -806,7 +1139,7 @@ class DropboxClient
     # * The thumbnail data
     def thumbnail(from_path, size='large')
         response = thumbnail_impl(from_path, size)
-        parse_response(response, raw=true)
+        Dropbox::parse_response(response, raw=true)
     end
 
     # Download a thumbnail for an image along with the image's metadata.
@@ -820,7 +1153,7 @@ class DropboxClient
     # * The metadata for the image as a hash
     def thumbnail_and_metadata(from_path, size='large')
         response = thumbnail_impl(from_path, size)
-        parsed_response = parse_response(response, raw=true)
+        parsed_response = Dropbox::parse_response(response, raw=true)
         metadata = parse_metadata(response)
         return parsed_response, metadata
     end
@@ -876,14 +1209,14 @@ class DropboxClient
         end
 
         response = @session.do_post build_url("/delta", params)
-        parse_response(response)
+        Dropbox::parse_response(response)
     end
 
     # Download a thumbnail (helper method - don't call this directly).
     #
     # Args:
-    # * from_path: The path to the file to be thumbnailed.
-    # * size: A string describing the desired thumbnail size. See thumbnail()
+    # * +from_path+: The path to the file to be thumbnailed.
+    # * +size+: A string describing the desired thumbnail size. See thumbnail()
     #   for details.
     #
     # Returns:
@@ -906,7 +1239,7 @@ class DropboxClient
     # used to instantly copy that file to the Dropbox of another account.
     #
     # Args:
-    # * path: The path to the file for a copy ref to be created on.
+    # * +path+: The path to the file for a copy ref to be created on.
     #
     # Returns:
     # * A Hash object that looks like the following example:
@@ -916,15 +1249,15 @@ class DropboxClient
 
         response = @session.do_get(build_url(path, {}))
 
-        parse_response(response)
+        Dropbox::parse_response(response)
     end
 
     # Adds the file referenced by the copy ref to the specified path
     #
     # Args:
-    # * copy_ref: A copy ref string that was returned from a create_copy_ref call.
+    # * +copy_ref+: A copy ref string that was returned from a create_copy_ref call.
     #   The copy_ref can be created from any other Dropbox account, or from the same account.
-    # * to_path: The path to where the file will be created.
+    # * +to_path+: The path to where the file will be created.
     #
     # Returns:
     # * A hash with the metadata of the new file.
@@ -937,7 +1270,7 @@ class DropboxClient
 
         response = @session.do_post(build_url(path, params))
 
-        parse_response(response)
+        Dropbox::parse_response(response)
     end
 
     def build_url(url, params=nil, content_server=false) # :nodoc:
@@ -963,7 +1296,7 @@ class DropboxClient
     end
 
     #From the oauth spec plus "/".  Slash should not be ecsaped
-    RESERVED_CHARACTERS = /[^a-zA-Z0-9\-\.\_\~\/]/
+    RESERVED_CHARACTERS = /[^a-zA-Z0-9\-\.\_\~\/]/  # :nodoc:
 
     def format_path(path, escape=true) # :nodoc:
         path = path.gsub(/\/+/,"/")