sorcery 0.1.4 → 0.3.1

data/lib/sorcery/controller/submodules/activity_logging.rb

@@ -1,6 +1,13 @@
 module Sorcery
   module Controller
     module Submodules
+      # This submodule keeps track of events such as login, logout, and last activity time, per user.
+      # It helps in estimating which users are active now in the site.
+      # This cannot be determined absolutely because a user might be reading a page without clicking anything for a while.
+      
+      # This is the controller part of the submodule, which adds hooks to register user events, 
+      # and methods to collect active users data for use in the app.
+      # see Socery::Model::Submodules::ActivityLogging for configuration options.
       module ActivityLogging
         def self.included(base)
           base.send(:include, InstanceMethods)
@@ -10,33 +17,39 @@ module Sorcery
         end
         
         module InstanceMethods
-          def logged_in_users
-            Config.user_class.logged_in_users
+          # Returns an array of the active users.
+          def current_users
+            Config.user_class.current_users
             # A possible patch here:
-            # we'll add the logged_in_user to the users list if he's not in it (can happen when he was inactive for more than activity timeout):
+            # we'll add the current_user to the users list if he's not in it (can happen when he was inactive for more than activity timeout):
             #
-            #   users.unshift!(logged_in_user) if logged_in? && users.find {|u| u.id == logged_in_user.id}.nil?
+            #   users.unshift!(current_user) if logged_in? && users.find {|u| u.id == current_user.id}.nil?
             #
             # disadvantages: can hurt performance.
           end
           
           protected
           
+          # registers last login time on every login.
+          # This runs as a hook just after a successful login.
           def register_login_time_to_db(user, credentials)
             user.send(:"#{user.sorcery_config.last_login_at_attribute_name}=", Time.now.utc.to_s(:db))
             user.save!(:validate => false)
           end
           
+          # registers last logout time on every logout.
+          # This runs as a hook just before a logout.
           def register_logout_time_to_db(user)
             user.send(:"#{user.sorcery_config.last_logout_at_attribute_name}=", Time.now.utc.to_s(:db))
             user.save!(:validate => false)
           end
           
-          # we do not update activity on logout
+          # Updates last activity time on every request.
+          # The only exception is logout - we do not update activity on logout
           def register_last_activity_time_to_db
             return if !logged_in?
-            logged_in_user.send(:"#{logged_in_user.sorcery_config.last_activity_at_attribute_name}=", Time.now.utc.to_s(:db))
-            logged_in_user.save!(:validate => false)
+            current_user.send(:"#{current_user.sorcery_config.last_activity_at_attribute_name}=", Time.now.utc.to_s(:db))
+            current_user.save!(:validate => false)
           end
         end
       end

data/lib/sorcery/controller/submodules/brute_force_protection.rb

@@ -1,6 +1,9 @@
 module Sorcery
   module Controller
     module Submodules
+      # This module helps protect user accounts by locking them down after too many failed attemps to login were detected.
+      # This is the controller part of the submodule which takes care of updating the failed logins and resetting them.
+      # See Sorcery::Model::Submodules::BruteForceProtection for configuration options.
       module BruteForceProtection
         def self.included(base)
           base.send(:include, InstanceMethods)
@@ -13,13 +16,17 @@ module Sorcery
           
           protected
           
+          # Increments the failed logins counter on every failed login.
+          # Runs as a hook after a failed login.
           def update_failed_logins_count!(credentials)
-            user = User.where("#{User.sorcery_config.username_attribute_name} = ?", credentials[0]).first
+            user = Config.user_class.where("#{Config.user_class.sorcery_config.username_attribute_name} = ?", credentials[0]).first
             user.register_failed_login! if user
           end
           
+          # Resets the failed logins counter.
+          # Runs as a hook after a successful login.
           def reset_failed_logins_count!(user, credentials)
-            user.update_attributes!(User.sorcery_config.failed_logins_count_attribute_name => 0)
+            user.update_attributes!(Config.user_class.sorcery_config.failed_logins_count_attribute_name => 0)
           end
         end
       end

data/lib/sorcery/controller/submodules/email.rb

@@ -0,0 +1,44 @@
+# module Sorcery
+#   module Controller
+#     module Submodules
+#       # This module allows you to authenticate to the site using a mail server.
+#       # Let's say your organization is called blup, and everyone has someklutz@blup.com,
+#       # Instead of registering a new username and password for an internal web application,
+#       # why not simply reuse your email credentials?
+#       # Of course this means that if the mail server is down, nobody can authenticate to your app.
+#       # I might add a fallback for that in the future.
+#       module Email
+#         def self.included(base)
+#           base.send(:include, InstanceMethods)
+#           Config.module_eval do
+#             class << self
+#               attr_reader :email_protocols                           # email protocols like pop3, IMAP etc.
+#                                           
+#               def merge_mail_defaults!
+#                 @defaults.merge!(:@email_protocols => [])
+#               end
+#               
+#               def email_protocols=(protocols)
+#                 protocols.each do |protocol|
+#                   include Protocols.const_get(protocol.to_s.split("_").map {|p| p.capitalize}.join(""))
+#                 end
+#               end
+#             end
+#             merge_mail_defaults!
+#           end
+#         end
+# 
+#         module InstanceMethods
+#           protected
+#           
+#           # sends user to authenticate at the provider's website.
+#           # after authentication the user is redirected to the callback defined in the provider config
+#           def login_at(protocol)
+# 
+#           end
+# 
+#         end
+#       end
+#     end
+#   end
+# end

data/lib/sorcery/controller/submodules/external/protocols/oauth1.rb

@@ -0,0 +1,35 @@
+require 'oauth'
+module Sorcery
+  module Controller
+    module Submodules
+      module External
+        module Protocols
+          module Oauth1
+            def oauth_version
+              "1.0"
+            end
+          
+            def get_request_token(token=nil,secret=nil)
+              return ::OAuth::RequestToken.new(get_consumer,token,secret) if token && secret
+              get_consumer.get_request_token(:oauth_callback => @callback_url)
+            end
+          
+            def authorize_url(args)
+              get_request_token(args[:request_token],args[:request_token_secret]).authorize_url(:oauth_callback => @callback_url)
+            end
+          
+            def get_access_token(args)
+              get_request_token(args[:request_token],args[:request_token_secret]).get_access_token(:oauth_verifier => args[:oauth_verifier])
+            end
+          
+            protected
+          
+            def get_consumer
+              ::OAuth::Consumer.new(@key, @secret, :site => @site)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sorcery/controller/submodules/external/protocols/oauth2.rb

@@ -0,0 +1,26 @@
+require 'oauth2'
+module Sorcery
+  module Controller
+    module Submodules
+      module External
+        module Protocols
+          module Oauth2
+            def oauth_version
+              "2.0"
+            end
+          
+            def authorize_url(*args)
+              client = ::OAuth2::Client.new(@key, @secret, :site => @site)
+              client.web_server.authorize_url(:redirect_uri => @callback_url, :scope => @scope)
+            end
+          
+            def get_access_token(args)
+              client = ::OAuth2::Client.new(@key, @secret, :site => @site)
+              client.web_server.get_access_token(args[:code], :redirect_uri => @callback_url)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sorcery/controller/submodules/external/providers/facebook.rb

@@ -0,0 +1,82 @@
+module Sorcery
+  module Controller
+    module Submodules
+      module External
+        module Providers
+          # This module adds support for OAuth with facebook.com.
+          # When included in the 'config.providers' option, it adds a new option, 'config.facebook'.
+          # Via this new option you can configure Facebook specific settings like your app's key and secret.
+          #
+          #   config.facebook.key = <key>
+          #   config.facebook.secret = <secret>
+          #   ...
+          #
+          module Facebook
+            def self.included(base)
+              base.module_eval do
+                class << self
+                  attr_reader :facebook                           # access to facebook_client.
+                  
+                  def merge_facebook_defaults!
+                    @defaults.merge!(:@facebook => FacebookClient)
+                  end
+                end
+                merge_facebook_defaults!
+                update!
+              end
+            end
+          
+            module FacebookClient
+              class << self
+                attr_accessor :key,
+                              :secret,
+                              :callback_url,
+                              :site,
+                              :user_info_path,
+                              :scope,
+                              :user_info_mapping
+                            
+                include Protocols::Oauth2
+            
+                def init
+                  @site           = "https://graph.facebook.com"
+                  @user_info_path = "/me"
+                  @scope          = "email,offline_access"
+                  @user_info_mapping = {}
+                end
+                
+                def get_user_hash
+                  user_hash = {}
+                  response = @access_token.get(@user_info_path)
+                  user_hash[:user_info] = JSON.parse(response)
+                  user_hash[:uid] = user_hash[:user_info]['id']
+                  user_hash
+                end
+                
+                def has_callback?
+                  true
+                end
+                
+                # calculates and returns the url to which the user should be redirected,
+                # to get authenticated at the external provider's site.
+                def login_url(params,session)
+                  self.authorize_url
+                end
+                
+                # tries to login the user from access token
+                def process_callback(params,session)
+                  args = {}
+                  args.merge!({:code => params[:code]}) if params[:code]
+                  @access_token = self.get_access_token(args)
+                end
+                
+              end
+              init
+            end
+            
+          end
+        end    
+      end
+    end
+  end
+end

data/lib/sorcery/controller/submodules/external/providers/twitter.rb

@@ -0,0 +1,86 @@
+module Sorcery
+  module Controller
+    module Submodules
+      module External
+        module Providers
+          # This module adds support for OAuth with Twitter.com.
+          # When included in the 'config.providers' option, it adds a new option, 'config.twitter'.
+          # Via this new option you can configure Twitter specific settings like your app's key and secret.
+          #
+          #   config.twitter.key = <key>
+          #   config.twitter.secret = <secret>
+          #   ...
+          #
+          module Twitter
+            def self.included(base)
+              base.module_eval do
+                class << self
+                  attr_reader :twitter
+                  # def twitter(&blk) # allows block syntax.
+                  #   yield @twitter
+                  # end                           
+
+                  def merge_twitter_defaults!
+                    @defaults.merge!(:@twitter => TwitterClient)
+                  end
+                end
+                merge_twitter_defaults!
+                update!
+              end
+            end
+            
+            module TwitterClient
+              class << self
+                attr_accessor :key,
+                              :secret,
+                              :callback_url,
+                              :site,
+                              :user_info_path,
+                              :user_info_mapping
+                
+                include Protocols::Oauth1
+                
+                def init
+                  @site           = "https://api.twitter.com"
+                  @user_info_path = "/1/account/verify_credentials.json"
+                  @user_info_mapping = {}
+                end
+                
+                def get_user_hash
+                  user_hash = {}
+                  response = @access_token.get(@user_info_path)
+                  user_hash[:user_info] = JSON.parse(response.body)
+                  user_hash[:uid] = user_hash[:user_info]['id']
+                  user_hash
+                end
+                
+                def has_callback?
+                  true
+                end
+                
+                # calculates and returns the url to which the user should be redirected,
+                # to get authenticated at the external provider's site.
+                def login_url(params,session)
+                  req_token = self.get_request_token
+                  session[:request_token]         = req_token.token
+                  session[:request_token_secret]  = req_token.secret
+                  self.authorize_url({:request_token => req_token.token, :request_token_secret => req_token.secret})
+                end
+                
+                # tries to login the user from access token
+                def process_callback(params,session)
+                  args = {}
+                  args.merge!({:oauth_verifier => params[:oauth_verifier], :request_token => session[:request_token], :request_token_secret => session[:request_token_secret]})
+                  args.merge!({:code => params[:code]}) if params[:code]
+                  @access_token = self.get_access_token(args)
+                end
+
+              end  
+              init
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sorcery/controller/submodules/external.rb

@@ -0,0 +1,83 @@
+module Sorcery
+  module Controller
+    module Submodules
+      # This submodule helps you login users from external auth providers such as Twitter.
+      # This is the controller part which handles the http requests and tokens passed between the app and the provider.
+      module External
+        def self.included(base)
+          base.send(:include, InstanceMethods)
+          Config.module_eval do
+            class << self
+              attr_reader :external_providers                           # external providers like twitter.
+                                          
+              def merge_external_defaults!
+                @defaults.merge!(:@external_providers => [])
+              end
+              
+              def external_providers=(providers)
+                providers.each do |provider|
+                  include Providers.const_get(provider.to_s.split("_").map {|p| p.capitalize}.join(""))
+                end
+              end
+            end
+            merge_external_defaults!
+          end
+        end
+
+        module InstanceMethods
+          protected
+          
+          # sends user to authenticate at the provider's website.
+          # after authentication the user is redirected to the callback defined in the provider config
+          def login_at(provider, args = {})
+            @provider = Config.send(provider)
+            if @provider.has_callback?
+              redirect_to @provider.login_url(params,session)
+            else
+              #@provider.login(args)
+            end
+          end
+          
+          # tries to login the user from provider's callback
+          def login_from(provider)
+            @provider = Config.send(provider)
+            @provider.process_callback(params,session)
+            @user_hash = @provider.get_user_hash
+            if user = Config.user_class.load_from_provider(provider,@user_hash[:uid])
+              reset_session
+              login_user(user)
+              user
+            end
+          end
+          
+          # this method automatically creates a new user from the data in the external user hash.
+          # The mappings from user hash fields to user db fields are set at controller config.
+          # If the hash field you would like to map is nested, use slashes. For example, Given a hash like:
+          #
+          #   "user" => {"name"=>"moishe"}
+          #
+          # You will set the mapping:
+          #
+          #   {:username => "user/name"}
+          #
+          # And this will cause 'moishe' to be set as the value of :username field.
+          def create_from(provider)
+            provider = provider.to_sym
+            @provider = Config.send(provider)
+            @user_hash = @provider.get_user_hash
+            config = Config.user_class.sorcery_config
+            attrs = {}
+            @provider.user_info_mapping.each do |k,v|
+              (varr = v.split("/")).size > 1 ? attrs.merge!(k => varr.inject(@user_hash[:user_info]) {|hsh,v| hsh[v] }) : attrs.merge!(k => @user_hash[:user_info][v])
+            end
+            Config.user_class.transaction do
+              @user = Config.user_class.create!(attrs)
+              Config.user_class.sorcery_config.authentications_class.create!({config.authentications_user_id_attribute_name => @user.id, config.provider_attribute_name => provider, config.provider_uid_attribute_name => @user_hash[:uid]})
+            end
+            @user
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sorcery/controller/submodules/http_basic_auth.rb

@@ -1,6 +1,9 @@
 module Sorcery
   module Controller
     module Submodules
+      # This submodule integrates HTTP Basic authentication into sorcery.
+      # You are provided with a before filter, require_login_from_http_basic, which requests the browser for authentication.
+      # Then the rest of the submodule takes care of logging the user in into the session, so that the next requests will keep him logged in.
       module HttpBasicAuth
         def self.included(base)
           base.send(:include, InstanceMethods)
@@ -31,25 +34,31 @@ module Sorcery
           def require_login_from_http_basic
             (request_http_basic_authentication(realm_name_by_controller) and (session[:http_authentication_used] = true) and return) if (request.authorization.nil? || session[:http_authentication_used].nil?)
             require_login
+            session[:http_authentication_used] = nil unless logged_in?
           end
           
           # given to main controller module as a login source callback
           def login_from_basic_auth
             authenticate_with_http_basic do |username, password|
-              @logged_in_user = (Config.user_class.authenticate(username, password) if session[:http_authentication_used]) || false
-              login_user(@logged_in_user) if @logged_in_user
-              @logged_in_user
+              @current_user = (Config.user_class.authenticate(username, password) if session[:http_authentication_used]) || false
+              login_user(@current_user) if @current_user
+              @current_user
             end
           end
           
+          # Sets the realm name by searching the controller name in the hash given at configuration time.
           def realm_name_by_controller
-            current_controller = self.class
-            while current_controller != ActionController::Base
-              result = Config.controller_to_realm_map[current_controller.controller_name]
-              return result if result
-              current_controller = self.class.superclass
+            if defined?(ActionController::Base)
+              current_controller = self.class
+              while current_controller != ActionController::Base
+                result = Config.controller_to_realm_map[current_controller.controller_name]
+                return result if result
+                current_controller = self.class.superclass
+              end
+              nil
+            else
+              Config.controller_to_realm_map["application"]
             end
-            nil
           end
           
         end

data/lib/sorcery/controller/submodules/oauth.rb

@@ -0,0 +1,95 @@
+module Sorcery
+  module Controller
+    module Submodules
+      # This submodule helps you login users from OAuth providers such as Twitter.
+      # This is the controller part which handles the http requests and tokens passed between the app and the provider.
+      # For more configuration options see Sorcery::Model::Oauth.
+      module Oauth
+        def self.included(base)
+          base.send(:include, InstanceMethods)
+          Config.module_eval do
+            class << self
+              attr_reader :oauth_providers                           # oauth providers like twitter.
+                                          
+              def merge_oauth_defaults!
+                @defaults.merge!(:@oauth_providers => [])
+              end
+              
+              def oauth_providers=(providers)
+                providers.each do |provider|
+                  include Providers.const_get(provider.to_s.split("_").map {|p| p.capitalize}.join(""))
+                end
+              end
+            end
+            merge_oauth_defaults!
+          end
+        end
+
+        module InstanceMethods
+          protected
+          
+          # sends user to authenticate at the provider's website.
+          # after authentication the user is redirected to the callback defined in the provider config
+          def auth_at_provider(provider)
+            @provider = Config.send(provider)
+            args = {}
+            if @provider.respond_to?(:get_request_token)
+              req_token = @provider.get_request_token
+              session[:request_token]         = req_token.token
+              session[:request_token_secret]  = req_token.secret
+              args.merge!({:request_token => req_token.token, :request_token_secret => req_token.secret})
+            end
+            redirect_to @provider.authorize_url(args)
+          end
+          
+          # tries to login the user from access token
+          def login_from_access_token(provider)
+            @provider = Config.send(provider)
+            args = {}
+            args.merge!({:oauth_verifier => params[:oauth_verifier], :request_token => session[:request_token], :request_token_secret => session[:request_token_secret]}) if @provider.respond_to?(:get_request_token)
+            args.merge!({:code => params[:code]}) if params[:code]
+            @access_token = @provider.get_access_token(args)
+            @user_hash = @provider.get_user_hash(@access_token)
+            if user = Config.user_class.load_from_provider(provider,@user_hash[:uid])
+              reset_session
+              login_user(user)
+              user
+            end
+          end
+          
+          def get_user_hash(provider)
+            @provider = Config.send(provider)
+            @provider.get_user_hash(@access_token)
+          end
+          
+          # this method automatically creates a new user from the data in the external user hash.
+          # The mappings from user hash fields to user db fields are set at controller config.
+          # If the hash field you would like to map is nested, use slashes. For example, Given a hash like:
+          #
+          #   "user" => {"name"=>"moishe"}
+          #
+          # You will set the mapping:
+          #
+          #   {:username => "user/name"}
+          #
+          # And this will cause 'moishe' to be set as the value of :username field.
+          def create_from_provider!(provider)
+            provider = provider.to_sym
+            @provider = Config.send(provider)
+            @user_hash = get_user_hash(provider)
+            config = Config.user_class.sorcery_config
+            attrs = {}
+            @provider.user_info_mapping.each do |k,v|
+              (varr = v.split("/")).size > 1 ? attrs.merge!(k => varr.inject(@user_hash[:user_info]) {|hsh,v| hsh[v] }) : attrs.merge!(k => @user_hash[:user_info][v])
+            end
+            Config.user_class.transaction do
+              @user = Config.user_class.create!(attrs)
+              Config.user_class.sorcery_config.authentications_class.create!({config.authentications_user_id_attribute_name => @user.id, config.provider_attribute_name => provider, config.provider_uid_attribute_name => @user_hash[:uid]})
+            end
+            @user
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sorcery/controller/submodules/remember_me.rb

@@ -1,6 +1,9 @@
 module Sorcery
   module Controller
     module Submodules
+      # The Remember Me submodule takes care of setting the user's cookie so that he will be automatically logged in to the site on every visit,
+      # until the cookie expires.
+      # See Sorcery::Model::Submodules::RememberMe for configuration options.
       module RememberMe
         def self.included(base)
           base.send(:include, InstanceMethods)
@@ -10,29 +13,35 @@ module Sorcery
         end
         
         module InstanceMethods
+          # This method sets the cookie and calls the user to save the token and the expiration to db.
           def remember_me!
-            logged_in_user.remember_me!
-            cookies[:remember_me_token] = { :value => logged_in_user.remember_me_token, :expires => logged_in_user.remember_me_token_expires_at }        
+            current_user.remember_me!
+            cookies[:remember_me_token] = { :value => current_user.remember_me_token, :expires => current_user.remember_me_token_expires_at }        
           end
 
+          # Clears the cookie and clears the token from the db.
           def forget_me!
-            logged_in_user.forget_me!
+            current_user.forget_me!
             cookies[:remember_me_token] = nil
           end
           
           protected
           
+          # calls remember_me! if a third credential was passed to the login method.
+          # Runs as a hook after login.
           def remember_me_if_asked_to(user, credentials)
             remember_me! if credentials.size == 3 && credentials[2]
           end
           
+          # Checks the cookie for a remember me token, tried to find a user with that token and logs the user in if found.
+          # Runs as a login source. See 'current_user' method for how it is used.
           def login_from_cookie
             user = cookies[:remember_me_token] && Config.user_class.find_by_remember_me_token(cookies[:remember_me_token])
             if user && user.remember_me_token?
               cookies[:remember_me_token] = { :value => user.remember_me_token, :expires => user.remember_me_token_expires_at }
-              @logged_in_user = user
+              @current_user = user
             else
-              @logged_in_user = false
+              @current_user = false
             end
           end
         end