sorcery 0.1.4 → 0.2.1

data/Gemfile

@@ -2,11 +2,13 @@ source "http://rubygems.org"
 # Add dependencies required to use your gem here.
 # Example:
 #   gem "activesupport", ">= 2.3.5"
-
+gem "rails", ">= 3.0.0"
+gem 'json', ">= 1.5.1"
+gem 'oauth', ">= 0.4.4"
+gem 'oauth2', ">= 0.1.1"
 # Add dependencies to develop your gem here.
 # Include everything needed to run rake, tests, features, etc.
 group :development do
-  gem "rails", ">= 3.0.0"
   gem "rspec", "~> 2.3.0"
   gem 'rspec-rails'
   gem 'ruby-debug19'

data/Gemfile.lock

@@ -28,29 +28,25 @@ GEM
       activemodel (= 3.0.3)
       activesupport (= 3.0.3)
     activesupport (3.0.3)
+    addressable (2.2.4)
     archive-tar-minitar (0.5.2)
     arel (2.0.6)
     builder (2.1.2)
     columnize (0.3.2)
-    cucumber (0.10.0)
-      builder (>= 2.1.2)
-      diff-lcs (~> 1.1.2)
-      gherkin (~> 2.3.2)
-      json (~> 1.4.6)
-      term-ansicolor (~> 1.0.5)
     diff-lcs (1.1.2)
     erubis (2.6.6)
       abstract (>= 1.0.0)
-    gherkin (2.3.2)
-      json (~> 1.4.6)
-      term-ansicolor (~> 1.0.5)
+    faraday (0.5.5)
+      addressable (~> 2.2.4)
+      multipart-post (~> 1.1.0)
+      rack (< 2, >= 1.1.0)
     git (1.2.5)
     i18n (0.5.0)
     jeweler (1.5.2)
       bundler (~> 1.0.0)
       git (>= 1.2.5)
       rake
-    json (1.4.6)
+    json (1.5.1)
     linecache19 (0.5.11)
       ruby_core_source (>= 0.1.4)
     mail (2.2.13)
@@ -59,6 +55,12 @@ GEM
       mime-types (~> 1.16)
       treetop (~> 1.4.8)
     mime-types (1.16)
+    multi_json (0.0.5)
+    multipart-post (1.1.0)
+    oauth (0.4.4)
+    oauth2 (0.1.1)
+      faraday (~> 0.5.0)
+      multi_json (~> 0.0.4)
     polyglot (0.3.1)
     rack (1.2.1)
     rack-mount (0.6.13)
@@ -106,7 +108,6 @@ GEM
       simplecov-html (>= 0.3.7)
     simplecov-html (0.3.9)
     sqlite3-ruby (1.3.2)
-    term-ansicolor (1.0.5)
     thor (0.14.6)
     treetop (1.4.9)
       polyglot (>= 0.3.1)
@@ -118,9 +119,11 @@ PLATFORMS
 
 DEPENDENCIES
   bundler (~> 1.0.0)
-  cucumber
   jeweler (~> 1.5.2)
-  rails (= 3.0.3)
+  json (>= 1.5.1)
+  oauth (>= 0.4.4)
+  oauth2 (>= 0.1.1)
+  rails (>= 3.0.0)
   rspec (~> 2.3.0)
   rspec-rails
   ruby-debug19

data/README.rdoc

@@ -3,28 +3,47 @@ Magical Authentication for Rails 3.
 
 Inspired by restful_authentication, Authlogic and Devise.
 Crypto code taken almost unchanged from Authlogic.
+OAuth code inspired by OmniAuth.
 
-== Example app using sorcery:
+== Summary
 
-https://github.com/NoamB/sorcery-example-app
+Sorcery aims to make your life easier by giving you an easy API to write your own user authentication flow with.
+It does this with a few goals in mind:
+
+* Less is more - less than 20 simple methods to remember for the entire feature-set make the lib easy to 'get'.
+* No built-in or generated code - use the API inside *your own* MVC structures, and don't fight to fix someone else's.
+* Magic yes, Voodoo no - the lib should be easy to hack for most developers.
+* Configuration over Confusion - Simple & short configuration as possible, not drowning in syntactic sugar.
+* Keep MVC cleanly separated - DB is for models, sessions are for controllers. Models stay unaware of sessions.
+
+Hopefully, I've achieved this. If not, let me know.
+
+== Useful Links:
+
+Example app using sorcery: https://github.com/NoamB/sorcery-example-app
+
+Documentation: http://rubydoc.info/gems/sorcery/0.2.0/frames
+
+Check out the tutorials in the github wiki!
 
 == Full Features List by module:
 
 Core (see lib/sorcery/model/model.rb and lib/sorcery/controller/controller.rb): 
-* login/logout, optional redirect on login to where the user tried to reach before, configurable redirect for non-logged-in users.
+* login/logout, optional return user to requested url on login, configurable redirect for non-logged-in users.
 * password encryption, algorithms: bcrypt(default), md5, sha1, sha256, sha512, aes256, custom(yours!), none. Configurable stretches and salt.
 * configurable attribute names for username, password and email.
 
 User Activation (see lib/sorcery/model/submodules/user_activation.rb):
 * User activation by email with optional success email.
 * configurable attribute names.
-* configurable mailer.
+* configurable mailer, method name, and attribute name.
+* configurable temporary token expiration.
 * Optionally prevent non-active users to login.
 
 Reset Password (see lib/sorcery/model/submodules/reset_password.rb):
 * Reset password with email verification.
 * configurable mailer, method name, and attribute name.
-* configurable expiration.
+* configurable temporary token expiration.
 * configurable time between emails (hammering protection).
 
 Remember Me (see lib/sorcery/model/submodules/remember_me.rb):
@@ -49,36 +68,20 @@ Activity Logging (see lib/sorcery/model/submodules/activity_logging.rb):
 * an easy method of collecting the list of currently logged in users.
 * configurable timeout by which to decide whether to include a user in the list of logged in users.
 
-Other:
-* Modular design, load only the modules you need.
-* 100% TDD'd code, 100% test coverage.
+Oauth (see lib/sorcery/controller/submodules/oauth.rb):
+* OAuth1 and OAuth2 support (currently twitter & facebook)
+* configurable db field names and authentications table.
 
 == Next Planned Features:
 
-I've got many plans which include:
+I've got many plans which include (by priority):
+* Sinatra support
+* Mongoid support
 * Configurable Auto login on registration/activation
 * Other reset password strategies (security questions?)
 * Other brute force protection strategies (captcha)
-* Sinatra support
-* Mongoid support
-* OAuth1 and OAuth2 support
 * Have an idea? Let me know, and it might get into the gem!
 
-== Project Goals:
-
-This gem plugin was started out of a few personal goals which are not related to the problem solved by it at all:
-* I wanted to write something 100% TDD from start to finish.
-* I wanted to learn how to write an engine for Rails 3.
-
-In addition to the above goals, when I decided this will be an authentication plugin, and while looking at existing solutions, these goals came up:
-* Simple & short configuration as possible, not drowning in syntactic sugar.
-* Keep MVC cleanly separated - DB is for models, sessions are for controllers. Models stay unaware of sessions.
-* Magic yes, Voodoo no.
-* No generated code polluting the application's code.
-* No built-in controllers, models, mailers, migrations or templates; Real apps will need all of these custom made.
-
-Hopefully, I've achieved this. If not, let me know.
-
 == Installation:
 
 You can either git clone and then 'rake install' to live on the edge (unstable),

data/Rakefile

@@ -1,4 +1,5 @@
 # require 'bundler'
+# -- Commented because it's slow
 # begin
 #   Bundler.setup(:default, :development)
 # rescue Bundler::BundlerError => e
@@ -6,6 +7,8 @@
 #   $stderr.puts "Run `bundle install` to install missing gems"
 #   exit e.status_code
 # end
+# --
+
 require 'rake'
 
 require 'jeweler'
@@ -23,6 +26,8 @@ Jeweler::Tasks.new do |gem|
   #  gem.add_runtime_dependency 'jabber4r', '> 0.1'
   #  gem.add_development_dependency 'rspec', '> 1.2.3'
   gem.add_runtime_dependency 'bcrypt-ruby', '~> 2.1.4'
+  gem.add_runtime_dependency 'oauth', '>= 0.4.4'
+  gem.add_runtime_dependency 'oauth2', '>= 0.1.1'
 end
 Jeweler::RubygemsDotOrgTasks.new
 

data/VERSION

@@ -1 +1 @@
-0.1.4
+0.2.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/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,17 +34,19 @@ 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

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

@@ -0,0 +1,26 @@
+require 'oauth'
+module Sorcery
+  module Controller
+    module Submodules
+      module Oauth
+        module Oauth1
+          def oauth_version
+            "1.0"
+          end
+          
+          def get_request_token
+            ::OAuth::Consumer.new(@key, @secret, :site => @site).get_request_token(:oauth_callback => @callback_url)
+          end
+          
+          def authorize_url(args)
+            args[:request_token].authorize_url(:oauth_callback => @callback_url)
+          end
+          
+          def get_access_token(args)
+            args[:request_token].get_access_token(:oauth_verifier => args[:oauth_verifier])
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+require 'oauth2'
+module Sorcery
+  module Controller
+    module Submodules
+      module Oauth
+        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

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

@@ -0,0 +1,64 @@
+module Sorcery
+  module Controller
+    module Submodules
+      module Oauth
+        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 Oauth2
+            
+                def init
+                  @site           = "https://graph.facebook.com"
+                  @user_info_path = "/me"
+                  @scope          = "email,offline_access"
+                  @user_info_mapping = {}
+                end
+                
+                def get_user_hash(access_token)
+                  user_hash = {}
+                  response = access_token.get(@user_info_path)
+                  user_hash[:user_info] = JSON.parse(response)
+                  user_hash[:uid] = user_hash[:user_info]['id'].to_i
+                  user_hash
+                end
+              end
+              init
+            end
+            
+          end
+        end    
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+module Sorcery
+  module Controller
+    module Submodules
+      module Oauth
+        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                           # access to twitter_client.
+
+                  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 Oauth1
+                
+                def init
+                  @site           = "https://api.twitter.com"
+                  @user_info_path = "/1/account/verify_credentials.json"
+                  @user_info_mapping = {}
+                end
+                
+                def get_user_hash(access_token)
+                  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
+              end  
+              init
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,92 @@
+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)
+            if @provider.respond_to?(:get_request_token)
+              args = {:request_token => @provider.get_request_token} 
+              session[:request_token] = args[:request_token]
+            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]}) 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