sorcery 0.2.1 → 0.3.0

data/README.rdoc

@@ -1,34 +1,103 @@
 = 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.
+OAuth code inspired by OmniAuth and Ryan Bates's railscasts about it.
+
 
 == Summary
 
-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.
+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 app using sorcery: https://github.com/NoamB/sorcery-example-app
 
-Documentation: http://rubydoc.info/gems/sorcery/0.2.0/frames
+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): 
+
+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.
@@ -72,62 +141,20 @@ 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 (by priority):
-* Sinatra support
+* 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)
 * Have an idea? Let me know, and it might get into the gem!
 
-== 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
 
@@ -137,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/VERSION

@@ -1 +1 @@
-0.2.1
+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.rb

@@ -29,6 +29,9 @@ module Sorcery
         end
       end
     end
+    module Adapters
+      autoload :Sinatra, 'sorcery/controller/adapters/sinatra'
+    end
   end
   module CryptoProviders
     autoload :AES256, 'sorcery/crypto_providers/aes256'
@@ -39,6 +42,11 @@ module Sorcery
     autoload :SHA512, 'sorcery/crypto_providers/sha512'
   end
   autoload :TestHelpers, 'sorcery/test_helpers'
+  module TestHelpers
+    autoload :Rails, 'sorcery/test_helpers/rails'
+    autoload :Sinatra, 'sorcery/test_helpers/sinatra'
+  end
   
   require 'sorcery/engine' if defined?(Rails) && Rails::VERSION::MAJOR == 3
+  require 'sorcery/sinatra' if defined?(Sinatra)
 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