sorcery 0.1.4 → 0.3.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

@@ -1,30 +1,152 @@
 = 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
+== Philosophy
+
+
+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.1/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.
+
+
+== API Summary
+
+Below is a summary of the library methods. Most method names are self explaining and the rest are commented:
+
+  # core
+  require_login # this is a before filter
+  login(username,password,remember_me = false)
+  logout
+  logged_in?
+  current_user
+  redirect_back_or_to # used when a user tries to access a page while logged out, is asked to login, and we want to return him back to the page he originally wanted.
+  @user.external? # external users, such as facebook/twitter etc.
+
+  # activity logging
+  current_users
+
+  # http basic auth
+  require_login_from_http_basic # this is a before filter
+
+  # external
+  login_at(provider) # sends the user to an external service (twitter etc.) to authenticate.
+  login_from(provider) # tries to login from the external provider's callback.
+  create_from(provider) # create the user in the local app db.
+
+  # remember me
+  remember_me!
+  forget_me!
+
+  # reset password
+  User.load_from_reset_password_token(token)
+  @user.deliver_reset_password_instructions!
+  @user.reset_password!(params)
+
+  # user activation
+  User.load_from_activation_token(token)
+  @user.activate!
+
+Please see the tutorials in the github wiki for detailed usage information.
+
 
 == 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,104 +171,53 @@ 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.
+External (see lib/sorcery/controller/submodules/external.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:
-* Configurable Auto login on registration/activation
+
+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
 * 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.
+Other stuff:
+* Improve documentation
+* Tty to reduce the number of library methods, and find better names to some
 
 
 == Contributing to sorcery
 
+
 Your feedback is very welcome and will make this gem much much better for you, me and everyone else.
 Besides feedback on code, features, suggestions and bug reports, you may want to actually make an impact on the code.
 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.1

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/external.rb

@@ -0,0 +1,14 @@
+class SorceryExternal < 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