sorcery 0.1.4 → 0.3.0

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

@@ -1,30 +1,118 @@
 = sorcery
-Magical Authentication for Rails 3.
+Magical Authentication for Rails 3 and Sinatra.
 
 Inspired by restful_authentication, Authlogic and Devise.
 Crypto code taken almost unchanged from Authlogic.
+OAuth code inspired by OmniAuth and Ryan Bates's railscasts about it.
 
-== Example app using sorcery:
 
-https://github.com/NoamB/sorcery-example-app
+== Summary
+
+
+Sorcery is a stripped-down, bare-bones authentication library, with which you can write your own authentication flow.
+It was built with a few goals in mind:
+
+* Less is more - less than 20 public methods to remember for the entire feature-set make the lib easy to 'get'.
+* No built-in or generated code - use the library's methods 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 Rails 3 app using sorcery: https://github.com/NoamB/sorcery-example-app
+
+Example Sinatra app using sorcery: https://github.com/NoamB/sorcery-example-app-sinatra
+
+Documentation: http://rubydoc.info/gems/sorcery/0.3.0/frames
+
+Check out the tutorials in the github wiki!
+
+
+== Installation:
+
+
+If using bundler, first add 'sorcery' to your Gemfile:
+
+	gem "sorcery"
+
+And run 
+	
+	bundle install
+
+Otherwise simply
+
+	gem install sorcery
+
+
+== Configuration:
+
+
+1. config/application.rb
+
+	config.sorcery.submodules = [:user_activation, :remember_me] # add the submodules you want to use
+	# You can also configure here any controller and any controller-submodule option here. For example:
+	config.sorcery.session_timeout = 10.minutes
+
+2. app/models/user.rb (or another model of your choice, but a User class is assumed by default)
+
+	activate_sorcery! do |config|
+  	  config.user_activation_mailer = MyMailer
+	  config.username_attribute_name = :email
+	end
+
+3. app/controllers/application_controller.rb (OPTIONAL: this is actually needed only in some cases)
+
+	activate_sorcery! do |config|
+  	  config.session_timeout = 10.minutes
+	end
+
+The configuration options vary with the submodules you've chosen to use, so check the documentation or the wiki tutorials regarding the specific submodule.
+
+For your convenience, Sorcery includes a migrations generator for Rails, which can be used like so:
+
+  rails g sorcery_migration [list of submodules]
+
+For example, for only the core functionality use:
+
+  rails g sorcery_migration core
+
+To generate migrations for both the core AND 'remember_me' submodule:
+
+  rails g sorcery_migration core remember_me
+
+These migrations use the default fields. You can choose to use these migrations or make your own tables and fields. Sorcery tries not to impose a database structure and naming scheme on your application.
+
+
+== Usage
+
+
+Please see 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.
+
+Core (see lib/sorcery/model.rb and lib/sorcery/controller.rb): 
+* 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,82 +137,24 @@ 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):
+* Scoping logins (to a subdomain or another arbitrary field)
+* Simple auth (no user)
+* Switching authentication mode at runtime (Maintenance mode)
+* 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),
-
-Or simply (stable):
-
-	gem install sorcery
-
-== Configuration:
-
-First add 'sorcery' to your Gemfile:
-
-	gem "sorcery"
-
-And run 
-	
-	bundle install
-
-There are 2 required places to configure the plugin, and an optional one:
-1. config/application.rb
-
-	config.sorcery.submodules = [:user_activation, :remember_me] # add the modules you want to use
-
-You can also configure here any controller and any controller-submodule option here.
-For example:
-
-	config.sorcery.session_timeout = 10.minutes
-
-
-2. app/models/user.rb (or another model of your choice)
-
-	activate_sorcery! do |config|
-  	  config.user_activation_mailer = MyMailer
-	  config.username_attribute_name = :email
-	end
-
-3. app/controllers/application_controller.rb (OPTIONAL: this is actually needed only in some cases)
-
-	activate_sorcery! do |config|
-  	  config.session_timeout = 10.minutes
-	end
-
-Also check the migrations in the example app to see what database fields are expected.
-
-The configuration options vary with the modules you've chosen to use.
-
 
 == Contributing to sorcery
 
@@ -134,19 +164,22 @@ For this:
 
 * Fork the project.
 * Make your feature addition or bug fix.
-* Add tests for it. This is important so I don’t break it in a future version unintentionally.
+* Add tests for it. I've used RSpec so far, please remain consistent with it.
 * Commit, do not mess with Rakefiles, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
 * Send me a pull request. Bonus points for topic branches.
 
 If you feel my work has made your life easier, and you would like to thank me through a donation, my paypal email is in the contact details.
 
+
 == Contact
 
+Feel free to ask questions using these contact details:
+	
 	email: nbenari@gmail.com ( also for paypal )
 	twitter: @nbenari
 	
+	
 == Copyright
 
-Copyright (c) 2010 Noam Ben Ari (nbenari@gmail.com). See LICENSE.txt for further details.
-Released with permission from Kontera (http://www.kontera.com), where I work.
 
+Copyright (c) 2010 Noam Ben Ari (nbenari@gmail.com). See LICENSE.txt for further details.

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.3.0

data/lib/generators/sorcery_migration/sorcery_migration_generator.rb

@@ -0,0 +1,24 @@
+require 'rails/generators'
+require 'rails/generators/migration'
+
+class SorceryMigrationGenerator < Rails::Generators::Base
+  include Rails::Generators::Migration
+  
+  source_root File.join(File.dirname(__FILE__), 'templates')
+  argument :submodules, :type => :array, :required => true
+  
+  def self.next_migration_number(dirname)
+    if ActiveRecord::Base.timestamped_migrations
+      Time.new.utc.strftime("%Y%m%d%H%M%S")
+    else
+      "%.3d" % (current_migration_number(dirname) + 1)
+    end
+  end
+  
+  def create_migration_file
+    self.submodules.each do |submodule|
+      migration_template "#{submodule}.rb", "db/migrate/sorcery_#{submodule}.rb"
+      sleep 1 # for the timestamp to change
+    end
+  end
+end

data/lib/generators/sorcery_migration/templates/activity_logging.rb

@@ -0,0 +1,17 @@
+class SorceryActivityLogging < ActiveRecord::Migration
+  def self.up
+    add_column :users, :last_login_at,     :datetime, :default => nil
+    add_column :users, :last_logout_at,    :datetime, :default => nil
+    add_column :users, :last_activity_at,  :datetime, :default => nil
+    
+    add_index :users, [:last_logout_at, :last_activity_at]
+  end
+
+  def self.down
+    remove_index :users, [:last_logout_at, :last_activity_at]
+    
+    remove_column :users, :last_activity_at
+    remove_column :users, :last_logout_at
+    remove_column :users, :last_login_at
+  end
+end

data/lib/generators/sorcery_migration/templates/brute_force_protection.rb

@@ -0,0 +1,11 @@
+class SorceryBruteForceProtection < ActiveRecord::Migration
+  def self.up
+    add_column :users, :failed_logins_count, :integer, :default => 0
+    add_column :users, :lock_expires_at, :datetime, :default => nil
+  end
+
+  def self.down
+    remove_column :users, :lock_expires_at
+    remove_column :users, :failed_logins_count
+  end
+end

data/lib/generators/sorcery_migration/templates/core.rb

@@ -0,0 +1,16 @@
+class SorceryCore < ActiveRecord::Migration
+  def self.up
+    create_table :users do |t|
+      t.string :username,         :null => false
+      t.string :email,            :default => nil
+      t.string :crypted_password, :default => nil
+      t.string :salt,             :default => nil
+
+      t.timestamps
+    end
+  end
+
+  def self.down
+    drop_table :users
+  end
+end

data/lib/generators/sorcery_migration/templates/oauth.rb

@@ -0,0 +1,14 @@
+class SorceryOauth < ActiveRecord::Migration
+  def self.up
+    create_table :authentications do |t|
+      t.integer :user_id, :null => false
+      t.string :provider, :uid, :null => false
+
+      t.timestamps
+    end
+  end
+
+  def self.down
+    drop_table :authentications
+  end
+end

data/lib/generators/sorcery_migration/templates/remember_me.rb

@@ -0,0 +1,15 @@
+class SorceryRememberMe < ActiveRecord::Migration
+  def self.up
+    add_column :users, :remember_me_token, :string, :default => nil
+    add_column :users, :remember_me_token_expires_at, :datetime, :default => nil
+    
+    add_index :users, :remember_me_token
+  end
+
+  def self.down
+    remove_index :users, :remember_me_token
+    
+    remove_column :users, :remember_me_token_expires_at
+    remove_column :users, :remember_me_token
+  end
+end

data/lib/generators/sorcery_migration/templates/reset_password.rb

@@ -0,0 +1,13 @@
+class SorceryResetPassword < ActiveRecord::Migration
+  def self.up
+    add_column :users, :reset_password_token, :string, :default => nil
+    add_column :users, :reset_password_token_expires_at, :datetime, :default => nil
+    add_column :users, :reset_password_email_sent_at, :datetime, :default => nil
+  end
+
+  def self.down
+    remove_column :users, :reset_password_email_sent_at
+    remove_column :users, :reset_password_token_expires_at
+    remove_column :users, :reset_password_token
+  end
+end

data/lib/generators/sorcery_migration/templates/user_activation.rb

@@ -0,0 +1,17 @@
+class SorceryUserActivation < ActiveRecord::Migration
+  def self.up
+    add_column :users, :activation_state, :string, :default => nil
+    add_column :users, :activation_token, :string, :default => nil
+    add_column :users, :activation_token_expires_at, :datetime, :default => nil
+    
+    add_index :users, :activation_token
+  end
+
+  def self.down
+    remove_index :users, :activation_token
+    
+    remove_column :users, :activation_token_expires_at
+    remove_column :users, :activation_token
+    remove_column :users, :activation_state
+  end
+end

data/lib/sorcery/controller/adapters/sinatra.rb

@@ -0,0 +1,97 @@
+module Sorcery
+  module Controller
+    module Adapters
+      # This module does the magic of translating Rails commands to Sinatra.
+      # This way the Rails code doesn't change, but it actually now calls Sinatra calls.
+      module Sinatra
+        def self.included(base)
+          base.class_eval do
+            class << self
+              # prepend a filter
+              def prepend_filter(type, path = nil, options = {}, &block)
+                return filters[type].unshift block unless path
+                path, options = //, path if path.respond_to?(:each_pair)
+                block, *arguments = compile!(type, path, block, options)
+                prepend_filter(type) do
+                  process_route(*arguments) { instance_eval(&block) }
+                end
+              end
+              
+              def after_filter(filter)
+                after do
+                  send(filter)
+                end
+              end
+            end
+          end
+          
+          ::Sinatra::Request.class_eval do
+            def authorization
+              env['HTTP_AUTHORIZATION']   ||
+              env['X-HTTP_AUTHORIZATION'] ||
+              env['X_HTTP_AUTHORIZATION'] ||
+              env['REDIRECT_X_HTTP_AUTHORIZATION'] || nil
+            end
+          end
+          
+          base.send(:include, InstanceMethods)
+          base.extend(ClassMethods)
+        end
+        
+        module InstanceMethods
+          def reset_session
+            session.clear
+          end
+        
+          def redirect_to(*args)
+            args.pop if args.last.is_a?(Hash)
+            redirect(*args)
+          end
+        
+          def root_path
+            '/'
+          end
+          
+          helpers do
+            def request_http_basic_authentication(realm)
+              response.header['WWW-Authenticate'] = %(Basic realm="#{realm}")
+              response.status = 401
+            end
+            
+            def authenticate_with_http_basic(&blk)
+              @auth ||=  Rack::Auth::Basic::Request.new(request.env)
+              yield @auth.credentials if ( @auth.provided? && @auth.basic? && @auth.credentials )
+            end
+          end
+          
+          def cookies
+            @cookie_proxy ||= CookieProxy.new(request,response)
+          end
+        end
+        
+        class CookieProxy
+          def initialize(request,response)
+            @request = request
+            @response = response
+          end
+          
+          def [](key)
+            @request.cookies[key.to_s]
+          end
+          
+          def []=(key, value)
+            @response.set_cookie(key, value)
+          end
+        end
+        
+        module ClassMethods
+          def prepend_before_filter(filter)
+            prepend_filter(:before) do
+              send(filter)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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