koala 1.2.0 → 1.3.0

data/lib/koala/oauth.rb

@@ -1,65 +1,165 @@
+# OpenSSL and Base64 are required to support signed_request
+require 'openssl'
+require 'base64'
+
 module Koala
   module Facebook
+    
+    DIALOG_HOST = "www.facebook.com"
+    
     class OAuth
       attr_reader :app_id, :app_secret, :oauth_callback_url
+      
+      # Creates a new OAuth client.
+      #
+      # @param app_id [String, Integer] a Facebook application ID
+      # @param app_secret a Facebook application secret
+      # @param oauth_callback_url the URL in your app to which users authenticating with OAuth will be sent
       def initialize(app_id, app_secret, oauth_callback_url = nil)
         @app_id = app_id
         @app_secret = app_secret
         @oauth_callback_url = oauth_callback_url
       end
-
-      def get_user_info_from_cookie(cookie_hash)
-        # Parses the cookie set Facebook's JavaScript SDK.
-        # You can pass Rack/Rails/Sinatra's cookie hash directly to this method.
-        #
-        # If the user is logged in via Facebook, we return a dictionary with the
-        # keys "uid" and "access_token". The former is the user's Facebook ID,
-        # and the latter can be used to make authenticated requests to the Graph API.
-        # If the user is not logged in, we return None.
-
+      
+      # Parses the cookie set Facebook's JavaScript SDK.
+      #
+      # @note in parsing Facebook's new signed cookie format this method has to make a request to Facebook.
+      #       We recommend storing authenticated user info in your Rails session (or equivalent) and only
+      #       calling this when needed.
+      #
+      # @param cookie_hash a set of cookies that includes the Facebook cookie.  
+      #                     You can pass Rack/Rails/Sinatra's cookie hash directly to this method.
+      #
+      # @return the authenticated user's information as a hash, or nil.
+      def get_user_info_from_cookies(cookie_hash)
         if signed_cookie = cookie_hash["fbsr_#{@app_id}"]
           parse_signed_cookie(signed_cookie)
         elsif unsigned_cookie = cookie_hash["fbs_#{@app_id}"]
           parse_unsigned_cookie(unsigned_cookie)
         end
       end
-      alias_method :get_user_info_from_cookies, :get_user_info_from_cookie
+      alias_method :get_user_info_from_cookie, :get_user_info_from_cookies
 
-      def get_user_from_cookie(cookies)
-        if info = get_user_info_from_cookies(cookies)
-          string = info["uid"]
+      # Parses the cookie set Facebook's JavaScript SDK and returns only the user ID.
+      #
+      # @note (see #get_user_info_from_cookie)
+      #
+      # @param (see #get_user_info_from_cookie)
+      #
+      # @return the authenticated user's Facebook ID, or nil.
+      def get_user_from_cookies(cookies)
+        if signed_cookie = cookies["fbsr_#{@app_id}"]
+          if components = parse_signed_request(signed_cookie)
+            components["user_id"]
+          end
+        elsif info = get_user_info_from_cookies(cookies)
+          # Parsing unsigned cookie
+          info["uid"]
         end
       end
-      alias_method :get_user_from_cookies, :get_user_from_cookie
+      alias_method :get_user_from_cookie, :get_user_from_cookies
 
       # URLs
-
+      
+      # Builds an OAuth URL, where users will be prompted to log in and for any desired permissions.
+      # When the users log in, you receive a callback with their   
+      # See http://developers.facebook.com/docs/authentication/.
+      #
+      # @see #url_for_access_token
+      #
+      # @note The server-side authentication and dialog methods should only be used 
+      #       if your application can't use the Facebook Javascript SDK,
+      #       which provides a much better user experience.
+      #       See http://developers.facebook.com/docs/reference/javascript/.
+      #
+      # @param options any query values to add to the URL, as well as any special/required values listed below.
+      # @option options permissions an array or comma-separated string of desired permissions
+      # 
+      # @raise ArgumentError if no OAuth callback was specified in OAuth#new or in options as :redirect_uri
+      #
+      # @return an OAuth URL you can send your users to
       def url_for_oauth_code(options = {})
         # for permissions, see http://developers.facebook.com/docs/authentication/permissions
-        permissions = options[:permissions]
-        scope = permissions ? "&scope=#{permissions.is_a?(Array) ? permissions.join(",") : permissions}" : ""
-        display = options.has_key?(:display) ? "&display=#{options[:display]}" : ""
-
-        callback = options[:callback] || @oauth_callback_url
-        raise ArgumentError, "url_for_oauth_code must get a callback either from the OAuth object or in the options!" unless callback
-
+        if permissions = options.delete(:permissions)
+          options[:scope] = permissions.is_a?(Array) ? permissions.join(",") : permissions
+        end
+        url_options = {:client_id => @app_id}.merge(options)
+        
         # Creates the URL for oauth authorization for a given callback and optional set of permissions
-        "https://#{GRAPH_SERVER}/oauth/authorize?client_id=#{@app_id}&redirect_uri=#{callback}#{scope}#{display}"
+        build_url("https://#{GRAPH_SERVER}/oauth/authorize", true, url_options)
       end
 
+      # Once you receive an OAuth code, you need to redeem it from Facebook using an appropriate URL.
+      # (This is done by your server behind the scenes.)
+      # See http://developers.facebook.com/docs/authentication/.
+      # 
+      # @see #url_for_oauth_code
+      # 
+      # @note (see #url_for_oauth_code)
+      #
+      # @param code an OAuth code received from Facebook
+      # @param options any additional query parameters to add to the URL
+      #
+      # @raise (see #url_for_oauth_code)
+      #
+      # @return an URL your server can query for the user's access token
       def url_for_access_token(code, options = {})
         # Creates the URL for the token corresponding to a given code generated by Facebook
-        callback = options[:callback] || @oauth_callback_url
-        raise ArgumentError, "url_for_access_token must get a callback either from the OAuth object or in the parameters!" unless callback
-        "https://#{GRAPH_SERVER}/oauth/access_token?client_id=#{@app_id}&redirect_uri=#{callback}&client_secret=#{@app_secret}&code=#{code}"
+        url_options = {
+          :client_id => @app_id, 
+          :code => code,
+          :client_secret => @app_secret
+        }.merge(options)
+        build_url("https://#{GRAPH_SERVER}/oauth/access_token", true, url_options)
       end
 
+      # Builds a URL for a given dialog (feed, friends, OAuth, pay, send, etc.)
+      # See http://developers.facebook.com/docs/reference/dialogs/.
+      # 
+      # @note (see #url_for_oauth_code)
+      #
+      # @param dialog_type the kind of Facebook dialog you want to show
+      # @param options any additional query parameters to add to the URL
+      #
+      # @return an URL your server can query for the user's access token
+      def url_for_dialog(dialog_type, options = {})
+        # some endpoints require app_id, some client_id, supply both doesn't seem to hurt
+        url_options = {:app_id => @app_id, :client_id => @app_id}.merge(options)        
+        build_url("http://#{DIALOG_HOST}/dialog/#{dialog_type}", true, url_options)
+      end
+      
+      # access tokens
+      
+      # Fetches an access token, token expiration, and other info from Facebook.
+      # Useful when you've received an OAuth code using the server-side authentication process.
+      # @see url_for_oauth_code
+      #
+      # @note (see #url_for_oauth_code)
+      # 
+      # @param code (see #url_for_access_token)
+      # @param options any additional parameters to send to Facebook when redeeming the token
+      # 
+      # @raise Koala::Facebook::APIError if Facebook returns an error response 
+      # 
+      # @return a hash of the access token info returned by Facebook (token, expiration, etc.) 
       def get_access_token_info(code, options = {})
         # convenience method to get a parsed token from Facebook for a given code
         # should this require an OAuth callback URL?
         get_token_from_server({:code => code, :redirect_uri => options[:redirect_uri] || @oauth_callback_url}, false, options)
       end
 
+      
+      # Fetches the access token (ignoring expiration and other info) from Facebook.
+      # Useful when you've received an OAuth code using the server-side authentication process.
+      # @see get_access_token_info
+      # 
+      # @note (see #url_for_oauth_code)
+      # 
+      # @param (see #get_access_token_info)
+      #
+      # @raise (see #get_access_token_info)
+      #
+      # @return the access token
       def get_access_token(code, options = {})
         # upstream methods will throw errors if needed
         if info = get_access_token_info(code, options)
@@ -67,24 +167,40 @@ module Koala
         end
       end
 
+      # Fetches the application's access token, along with any other information provided by Facebook.
+      # See http://developers.facebook.com/docs/authentication/ (search for App Login).
+      # 
+      # @param options any additional parameters to send to Facebook when redeeming the token
+      #
+      # @return the application access token and other information (expiration, etc.)
       def get_app_access_token_info(options = {})
         # convenience method to get a the application's sessionless access token
         get_token_from_server({:type => 'client_cred'}, true, options)
       end
 
+      # Fetches the application's access token (ignoring expiration and other info).
+      # @see get_app_access_token_info
+      # 
+      # @param (see #get_app_access_token_info)
+      #
+      # @return the application access token
       def get_app_access_token(options = {})
         if info = get_app_access_token_info(options)
           string = info["access_token"]
         end
       end
 
-      # Originally provided directly by Facebook, however this has changed
-      # as their concept of crypto changed. For historic purposes, this is their proposal:
-      # https://developers.facebook.com/docs/authentication/canvas/encryption_proposal/
-      # Currently see https://github.com/facebook/php-sdk/blob/master/src/facebook.php#L758
-      # for a more accurate reference implementation strategy.
+      # Parses a signed request string provided by Facebook to canvas apps or in a secure cookie.
+      #
+      # @param input the signed request from Facebook
+      # 
+      # @raise RuntimeError if the signature is incomplete, invalid, or using an unsupported algorithm
+      # 
+      # @return a hash of the validated request information 
       def parse_signed_request(input)
         encoded_sig, encoded_envelope = input.split('.', 2)
+        raise 'SignedRequest: Invalid (incomplete) signature data' unless encoded_sig && encoded_envelope
+
         signature = base64_url_decode(encoded_sig).unpack("H*").first
         envelope = MultiJson.decode(base64_url_decode(encoded_envelope))
 
@@ -94,11 +210,15 @@ module Koala
         hmac = OpenSSL::HMAC.hexdigest(OpenSSL::Digest::SHA256.new, @app_secret, encoded_envelope)
         raise 'SignedRequest: Invalid signature' if (signature != hmac)
 
-        return envelope
+        envelope
       end
 
-      # from session keys
+      # Old session key code
+      
+      # @deprecated Facebook no longer provides session keys.
       def get_token_info_from_session_keys(sessions, options = {})
+        Koala::Utils.deprecate("Facebook no longer provides session keys. The relevant OAuth methods will be removed in the next release.")
+
         # fetch the OAuth tokens from Facebook
         response = fetch_token_string({
           :type => 'client_cred',
@@ -116,6 +236,7 @@ module Koala
         MultiJson.decode(response)
       end
 
+      # @deprecated (see #get_token_info_from_session_keys)
       def get_tokens_from_session_keys(sessions, options = {})
         # get the original hash results
         results = get_token_info_from_session_keys(sessions, options)
@@ -123,6 +244,7 @@ module Koala
         results.collect { |r| r ? r["access_token"] : nil }
       end
 
+      # @deprecated (see #get_token_info_from_session_keys)
       def get_token_from_session_key(session, options = {})
         # convenience method for a single key
         # gets the overlaoded strings automatically
@@ -166,8 +288,15 @@ module Koala
       
       def parse_signed_cookie(fb_cookie)
         components = parse_signed_request(fb_cookie)
-        if (code = components["code"]) && token_info = get_access_token_info(code, :redirect_uri => '')
-          components.merge(token_info)
+        if code = components["code"]
+          begin
+            token_info = get_access_token_info(code, :redirect_uri => '')
+          rescue Koala::Facebook::APIError => err
+            return nil if err.message =~ /Code was invalid or expired/
+            raise
+          end
+
+          components.merge(token_info) if token_info
         else
           nil
         end
@@ -186,6 +315,14 @@ module Koala
         str += '=' * (4 - str.length.modulo(4))
         Base64.decode64(str.tr('-_', '+/'))
       end
+      
+      def build_url(base, require_redirect_uri = false, url_options = {})
+        if require_redirect_uri && !(url_options[:redirect_uri] ||= url_options.delete(:callback) || @oauth_callback_url)          
+          raise ArgumentError, "url_for_dialog must get a callback either from the OAuth object or in the parameters!"
+        end
+        
+        "#{base}?#{Koala::HTTPService.encode_params(url_options)}"
+      end
     end
   end
 end

data/lib/koala/realtime_updates.rb

@@ -1,36 +1,27 @@
 module Koala
   module Facebook
-    module RealtimeUpdateMethods
-      # note: to subscribe to real-time updates, you must have an application access token
+    class RealtimeUpdates
+      # Manage realtime callbacks for changes to users' information.
+      # See http://developers.facebook.com/docs/reference/api/realtime.
+      #
+      # @note: to subscribe to real-time updates, you must have an application access token
+      #        or provide the app secret when initializing your RealtimeUpdates object.
 
-      def self.included(base)
-        # make the attributes readable
-        base.class_eval do
-          attr_reader :api, :app_id, :app_access_token, :secret
-
-          # parses the challenge params and makes sure the call is legitimate
-          # returns the challenge string to be sent back to facebook if true
-          # returns false otherwise
-          # this is a class method, since you don't need to know anything about the app
-          # saves a potential trip fetching the app access token
-          def self.meet_challenge(params, verify_token = nil, &verification_block)
-            if params["hub.mode"] == "subscribe" &&
-                # you can make sure this is legitimate through two ways
-                # if your store the token across the calls, you can pass in the token value
-                # and we'll make sure it matches
-                (verify_token && params["hub.verify_token"] == verify_token) ||
-                # alternately, if you sent a specially-constructed value (such as a hash of various secret values)
-                # you can pass in a block, which we'll call with the verify_token sent by Facebook
-                # if it's legit, return anything that evaluates to true; otherwise, return nil or false
-                (verification_block && yield(params["hub.verify_token"]))
-              params["hub.challenge"]
-            else
-              false
-            end
-          end
-        end
-      end
+      # The application API interface used to communicate with Facebook. 
+      # @return [Koala::Facebook::API] 
+      attr_reader :api
+      attr_reader :app_id, :app_access_token, :secret
 
+      # Create a new RealtimeUpdates instance.  
+      # If you don't have your app's access token, provide the app's secret and 
+      # Koala will make a request to Facebook for the appropriate token.
+      # 
+      # @param options initialization options.
+      # @option options :app_id the application's ID.
+      # @option options :app_access_token an application access token, if known.
+      # @option options :secret the application's secret.  
+      #
+      # @raise ArgumentError if the application ID and one of the app access token or the secret are not provided.
       def initialize(options = {})
         @app_id = options[:app_id]
         @app_access_token = options[:app_access_token]
@@ -45,45 +36,92 @@ module Koala
           @app_access_token = oauth.get_app_access_token
         end
 
-        @graph_api = API.new(@app_access_token)
+        @api = API.new(@app_access_token)
       end
 
-      # subscribes for realtime updates
-      # your callback_url must be set up to handle the verification request or the subscription will not be set up
-      # http://developers.facebook.com/docs/api/realtime
-      def subscribe(object, fields, callback_url, verify_token)
+      # Subscribe to realtime updates for certain fields on a given object (user, page, etc.).  
+      # See {http://developers.facebook.com/docs/reference/api/realtime the realtime updates documentation}
+      # for more information on what objects and fields you can register for.
+      #
+      # @note Your callback_url must be set up to handle the verification request or the subscription will not be set up.
+      #
+      # @param object a Facebook ID (name or number)
+      # @param fields the fields you want your app to be updated about
+      # @param callback_url the URL Facebook should ping when an update is available
+      # @param verify_token a token included in the verification request, allowing you to ensure the call is genuine 
+      #                     (see the docs for more information)
+      # @param options (see Koala::HTTPService.make_request)
+      #
+      # @return true if successful, false (or an APIError) otherwise.
+      def subscribe(object, fields, callback_url, verify_token, options = {})
         args = {
           :object => object,
           :fields => fields,
           :callback_url => callback_url,
-          :verify_token => verify_token
-        }
+        }.merge(verify_token ? {:verify_token => verify_token} : {})
         # a subscription is a success if Facebook returns a 200 (after hitting your server for verification)
-        @graph_api.graph_call(subscription_path, args, 'post', :http_component => :status) == 200
+        @api.graph_call(subscription_path, args, 'post', options.merge(:http_component => :status)) == 200
       end
 
-      # removes subscription for object
-      # if object is nil, it will remove all subscriptions
-      def unsubscribe(object = nil)
-        args = {}
-        args[:object] = object if object
-        @graph_api.graph_call(subscription_path, args, 'delete', :http_component => :status) == 200
+      # Unsubscribe from updates for a particular object or from updates. 
+      #
+      # @param object the object whose subscriptions to delete. 
+      #               If no object is provided, all subscriptions will be removed.
+      # @param options (see Koala::HTTPService.make_request)
+      #
+      # @return true if the unsubscription is successful, false (or an APIError) otherwise.
+      def unsubscribe(object = nil, options = {})
+        @api.graph_call(subscription_path, object ? {:object => object} : {}, "delete", options.merge(:http_component => :status)) == 200
       end
 
-      def list_subscriptions
-        @graph_api.graph_call(subscription_path)
+      # List all active subscriptions for this application.
+      # 
+      # @param options (see Koala::HTTPService.make_request) 
+      #
+      # @return [Array] a list of active subscriptions
+      def list_subscriptions(options = {})
+        @api.graph_call(subscription_path, {}, "get", options)
       end
 
-      def graph_api
-        Koala::Utils.deprecate("the TestUsers.graph_api accessor is deprecated and will be removed in a future version; please use .api instead.")
-        @api
+      # As a security measure (to prevent DDoS attacks), Facebook sends a verification request to your server
+      # after you request a subscription.
+      # This method parses the challenge params and makes sure the call is legitimate.
+      #
+      # @param params the request parameters sent by Facebook.  (You can pass in a Rails params hash.)
+      # @param verify_token the verify token sent in the {#subscribe subscription request}, if you provided one
+      # 
+      # @yield verify_token if you need to compute the verification token
+      #                     (for instance, if your callback URL includes a record ID, which you look up
+      #                     and use to calculate a hash), you can pass meet_challenge a block, which 
+      #                     will receive the verify_token received back from Facebook.
+      # 
+      # @return the challenge string to be sent back to Facebook, or false if the request is invalid.
+      def self.meet_challenge(params, verify_token = nil, &verification_block)
+        if params["hub.mode"] == "subscribe" &&
+            # you can make sure this is legitimate through two ways
+            # if your store the token across the calls, you can pass in the token value
+            # and we'll make sure it matches
+            (verify_token && params["hub.verify_token"] == verify_token) ||
+            # alternately, if you sent a specially-constructed value (such as a hash of various secret values)
+            # you can pass in a block, which we'll call with the verify_token sent by Facebook
+            # if it's legit, return anything that evaluates to true; otherwise, return nil or false
+            (verification_block && yield(params["hub.verify_token"]))
+          params["hub.challenge"]
+        else
+          false
+        end
       end
-
-      protected
-
+      
+      # The Facebook subscription management URL for your application.
       def subscription_path
         @subscription_path ||= "#{@app_id}/subscriptions"
       end
+      
+      # @private
+      def graph_api
+        Koala::Utils.deprecate("the TestUsers.graph_api accessor is deprecated and will be removed in a future version; please use .api instead.")
+        @api
+      end
     end
   end
 end