janus 0.5.0 → 0.6.0

data/README.rdoc

@@ -2,48 +2,86 @@
 
 Janus is an authentication engine for Ruby on Rails 3 and is an alternative
 to the Warden + Devise combo, without the Rack middleware. The whole project
-is inspired by the Warden and Devise API but shall eventually be quite
-different since everything happens within ActionDispatch and not at the Rack
-level.
-
-The main difference for now is the cross domain authentication --which allows
-a user to single sign in and out across top level domains-- which required
-a finer grained control over setting and unsetting a user than Warden provides.
-Janus uses +login+ and +logout+ to actually sign the user in and out, while
-+set_user+ and +unset_user+ will manually set the session, without dispatching
-the +after_login+ and +after_logout+ hooks.
+is inspired by the Warden and Devise API (in order to somehow compatible)
+but is quite different since everything happens within ActionDispatch and not
+at the Rack level.
+
+This Rails instead of Rack difference, allows to actually have the main logic
+within plain Rails controllers. For instance the database authentication is
+called from SessionsController, and it's not just another strategy operating
+at the Rack level within Warden (which requires to check that it's being
+called from the correct URL). There ain't no factory to add strategy modules
+to your models too. You must manually include the necessary ones.
+
+Another difference is that you must actually create the necessary controllers,
+models, mailers and views within your project (extending the default ones).
+You will eventually need to have those controllers anyway, and having those
+from the beginning allows to skip some configuration. The burdensome of
+manually creating all those classes should eventually be leveraged by using
+some rails generators.
+
+Janus also provides a finer control over setting and unsetting a user than
+Warden provides. Janus uses +login+ and +logout+ to actually sign the user
+in and out, just like Warden, but actually uses +set_user+ and +unset_user+
+to manually set the session, without dispatching the +after_login+ and
++after_logout+ hooks, of course.
+
+Emails are also sent from the controllers, not from the models, because I
+believe this is actually the job of controllers, not models.
 
 == Features
 
+The main feature is of course having a framework for authenticating users
+painleslly. Yet a very usefull feature is the cross domain authentication
+--which allows a user to single sign in and out across top level domains.
+
+How is the cross domain authentication strategy usefull? Let's imagine you
+host of blogging website where users may host their blogs on other domains.
+Since you don't rely on subdomains, it will be a pain to keep the user
+authentified, because you can't rely on '.' domain cookie trick.
+
+This is where RemoteAuthentication comes in, and allows you to painlessly
+keep your users connected across the main website and their blogs. This
+without actually tracking connections since this strategy takes advantage
+of the +set_user+ and +unset_user+ methods, because they're not really
+signing in, they just stay authentified across domains.
+
+So, Janus provides the following API:
+
+- full authentication system with strategies and hooks
+- scoped authentications with parallel authentication (like `users`, `admin_users`, etc.)
+- database authentication with password encryption (bcrypt) and validation
+- remote authentication for cross domain single sign in / sign out
+- abstract controllers for session management, registration, email confirmation and password reset
+- route generation for the above controllers
+
+And for the strategies and hooks:
+
 - DatabaseAuthenticatable
 - RemoteAuthenticatable
 - Confirmable
 - Rememberable
-- Trackable
-
-Note: login through Janus::Manager#set_user won't track the user.
-
-- authentication system with strategies and hooks
-- scoped authentications with parallel authentication
-- database authentication with password encryption, validation and remember me strategy
-- remote authentication for cross domain sign in / sign out
-- controllers: sessions, registrations, confirmations, passwords and their routes
-- route generation for above controllers
-- trackable hook
+- Trackable (note that login through Janus::Manager#set_user won't track the user).
 
 == TODO
 
-- generators (janus:install, janus)
-- rename RemoteAuthenticatable to something like CrossDomainAuthenticatable(?)
+- Simple configuration to use scrypt instead of bcrypt for password encryption.
+- Reconfirmable when email changes.
+- TokenAuthenticatable.
+- Remember me on remote authenticated domains.
+- Differenciate mailers per resource, by looking for Users::Mailer class.
+- Generators: `janus:install` and `janus <scope>`.
+- Integrate OmniAuth, or shall we let the user do it himself?
+- Providing an OAuth 2.0 server whould be cool.
 
 == Install
 
-There is no automated way to install Janus yet, since generators are missing.
-Please remember that Janus is only compatible with Rails 3.
+There is no automated way to install Janus yet, because generators are missing.
+Also remember that Janus is only compatible with Rails 3+.
 
 First add the gem to your Gemfile:
 
-  $ gem 'janus', :git => git://github.com/ysbaddaden/janus.git
+  $ gem 'janus'
 
 Configure your user models by including all or a selection of the Janus::Models
 modules:
@@ -60,7 +98,6 @@ modules:
   class Admin < ActiveRecord::Base
     include Janus::Models::Base
     include Janus::Models::DatabaseAuthenticatable
-    include Janus::Models::RemoteAuthenticatable
   end
 
 Configure your routes:
@@ -68,7 +105,6 @@ Configure your routes:
   Name::Application.routes.map do
     janus :users,  :session => true, :registration => true, :password => true, :confirmation => true
     janus :admins, :session => true
-    
     root :to => "home#index"
   end
 
@@ -86,7 +122,7 @@ Create the required controllers:
     respond_to :html
   end
 
-  class Users::ConfirmationssController < Janus::ConfirmationssController
+  class Users::ConfirmationsController < Janus::ConfirmationsController
     respond_to :html
   end
 

data/lib/janus.rb

@@ -1,8 +1,8 @@
+require 'active_support/core_ext/class'
 require 'janus/config'
 require 'janus/hooks'
 require 'janus/strategies'
 require 'janus/manager'
-require 'janus/routes'
 
 autoload :JanusHelper, 'janus/helper'
 
@@ -16,18 +16,6 @@ module Janus
     end
   end
 
-  autoload :Mailer,                    'janus/mailer'
-  autoload :TestHelper,                'janus/test_helper'
-
-  autoload :Helpers,                   'janus/controllers/helpers'
-  autoload :UrlHelpers,                'janus/controllers/url_helpers'
-  autoload :InternalHelpers,           'janus/controllers/internal_helpers'
-
-  autoload :SessionsController,        'janus/controllers/sessions_controller'
-  autoload :RegistrationsController,   'janus/controllers/registrations_controller'
-  autoload :ConfirmationsController,   'janus/controllers/confirmations_controller'
-  autoload :PasswordsController,       'janus/controllers/passwords_controller'
-
   module Models
     autoload :Base,                    'janus/models/base'
     autoload :DatabaseAuthenticatable, 'janus/models/database_authenticatable'

data/lib/janus/config.rb

@@ -5,17 +5,21 @@ module Janus
     mattr_accessor :contact_email
     
     # DatabaseAuthenticatable
-    mattr_accessor :authentication_keys, :stretches, :pepper
-    self.authentication_keys = [:email]
+    mattr_accessor :authentication_keys, :encryptor, :stretches, :pepper, :scrypt_options
+    self.authentication_keys = [ :email ]
+    self.encryptor = :bcrypt
     self.stretches = 10
+    self.pepper = nil
+    self.scrypt_options = { :max_time => 0.25 }
     
     # Confirmable
-    mattr_accessor :confirmation_key
+    mattr_accessor :confirmation_key #,reconfirmable
     self.confirmation_key = :confirm_token
+#    self.reconfirmable = true
     
     # Rememberable
-    mattr_accessor :remember_for, :extend_remember_period, :remember_across_browsers
-    self.remember_for = 2.weeks
+    mattr_accessor :remember_for, :extend_remember_period #, :remember_across_browsers
+    self.remember_for = 1.year
     self.extend_remember_period = false
 #    self.remember_across_browsers = false
     

data/lib/janus/controllers/confirmations_controller.rb

@@ -1,3 +1,5 @@
+# This controller is responsible for confirming any user email. It's also
+# responsible for resending the confirmation email on demand by the user.
 class Janus::ConfirmationsController < ApplicationController
   include Janus::InternalHelpers
 

data/lib/janus/controllers/helpers.rb

@@ -13,19 +13,36 @@ module Janus
       end
     end
 
+    # Returns the current instance of Janus::Manager.
     def janus
       @janus ||= Janus::Manager.new(request, cookies)
     end
 
+    # Signs the current user out (from all scopes at once) in case of a CSRF attack.
+    # See ActionController::RequestForgeryProtection for documentation.
     def handle_unverified_requests
       janus.logout
+      super
     end
 
+    # Returns true if a scope user is currently authenticated.
     def signed_in?(scope)
       janus.authenticate?(scope)
     end
 
     module ClassMethods
+      # Aliases some Janus methods for convenience. For instance calling
+      # `janus(:user, :admin)` will generate the following methods:
+      #
+      #   authenticate_user!   # => janus.authenticate!(:user)
+      #   current_user         # => janus.authenticate(:user)
+      #   user_signed_in?      # => janus.authenticate?(:user)
+      #   user_session         # => janus.sesssion(:user)
+      #
+      #   authenticate_admin!  # => janus.authenticate!(:admin)
+      #   current_admin        # => janus.authenticate(:admin)
+      #   admin_signed_in?     # => janus.authenticate?(:admin)
+      #   admin_session        # => janus.sesssion(:admin)
       def janus(*scopes)
         scopes.each do |scope|
           class_eval <<-EOV

data/lib/janus/controllers/internal_helpers.rb

@@ -1,4 +1,7 @@
 module Janus
+  # A collection of abstraction helper methods used in Janus controllers and views.
+  # This should be of no particular outside of abstract controllers for Janus that
+  # must be working for all scopes at once.
   module InternalHelpers
     extend ActiveSupport::Concern
 
@@ -6,26 +9,35 @@ module Janus
       helper_method :janus_scope, :resource, :resource_class, :resource_name
     end
 
+    # Abstract method for the authenticate_scope! before filter, with scope
+    # as detected by janus_scope.
     def authenticate!
       send("authenticate_#{janus_scope}!")
     end
 
+    # Detects the scope from the controller name.
     def janus_scope
       @janus_scope ||= self.class.name.split('::', 2).first.underscore.singularize
     end
 
+    # Returns the `@user` instance variable (or `@admin` or whatever),
+    # as detected by janus_scope.
     def resource
       instance_variable_get(:"@#{janus_scope}")
     end
 
+    # Sets the `@user` instance variable (or `@admin` or whatever),
+    # as detected by janus_scope.
     def resource=(value)
       instance_variable_set(:"@#{janus_scope}", value)
     end
 
+    # Returns the `User` class (or `Admin` or whatever) as detected by janus_scope.
     def resource_class
       @resource_class ||= janus_scope.camelize.constantize
     end
 
+    # Alias for janus_scope.
     def resource_name
       janus_scope
     end

data/lib/janus/controllers/passwords_controller.rb

@@ -1,3 +1,6 @@
+# This controller is responsible for resetting a lost password. It sends an
+# email with an unique token, on demand by the user. Then allows the user to
+# change its password (as long as the token is valid).
 class Janus::PasswordsController < ApplicationController
   include Janus::InternalHelpers
 

data/lib/janus/controllers/sessions_controller.rb

@@ -1,5 +1,13 @@
 require 'addressable/uri'
 
+# This controller is responsible for creating and destroying
+# authenticated user sessions.
+#
+# The creation uses the DatabaseAuthenticatable strategy, while the destruction
+# simply destroys any session, whatever strategy it was created with. Janus
+# hooks will be called, of course, allowing to destroy any Rememberable cookies
+# for instance, as well as any user defined behavior.
+#
 class Janus::SessionsController < ApplicationController
   include Janus::InternalHelpers
 #  include Janus::UrlHelpers
@@ -34,7 +42,6 @@ class Janus::SessionsController < ApplicationController
           self.resource ||= resource_class.new(params[resource_name])
           resource.clean_up_passwords
           resource.errors.add(:base, :not_found)
-          
           render "new", :status => :unauthorized
         end
         format.any { head :unauthorized }
@@ -51,41 +58,71 @@ class Janus::SessionsController < ApplicationController
     end
   end
 
+  # An overridable method that returns the default path to return the just
+  # signed in user to. Defaults to return the user object, which will be
+  # interpreted by rails as `user_path(user)`.
   def after_sign_in_url(user)
     user
   end
 
+  # An overridable method that returns the default path to return the just
+  # signed out user to. Defaults to `root_url`.
   def after_sign_out_url(scope)
     root_url
   end
 
-  # Returns true if remote host is known and redirect with an auth_token should
-  # be allowed or not. It must be overwritten by child class since it always
-  # returns true by default.
+  # Returns true if host is known and that we allow to redirect the user
+  # with an auth_token.
+  #
+  # Warning: must be overwritten by child classes because it always
+  # returns false by default!
   def valid_remote_host?(host)
-    true
+    false
+  end
+
+  # Returns an Array of URL that we shouldn't automatically return to. It
+  # actually returns URL to prevent infinite loops. We must for instance
+  # never return to new_sesssion_path.
+  #
+  # If you ever needd to override this method, don't forget to call `super`.
+  # For instance:
+  #
+  #   def never_return_to(scope)
+  #     super + [ my_peculiar_path, another_path ]
+  #   end
+  #
+  def never_return_to(scope)
+    scope = Janus.scope_for(scope)
+    [
+      new_session_path(scope),
+      new_password_path(scope),
+      edit_password_path(scope)
+    ]
   end
 
-  # Either redirects the user to after_sign_in_url or to
-  # <tt>params[:return_to]</tt>. If return_to is an absolute URL, and not just
-  # a path, valid_remote_host? will be invoked to check if we should redirect
-  # to this URL or not --which is moslty of use for RemoteAuthenticatable to
-  # securize auth tokens from unknown domains.
+  # Either redirects the user to after_sign_in_url or to <tt>params[:return_to]</tt>.
+  #
+  # If <tt>params[:return_to] is an absolute URL, and not just a path,
+  # valid_remote_host? will be invoked to check wether we should redirect
+  # to this URL or not, in order to secure auth tokens for
+  # RemoteAuthenticatable to leak into the wild.
   def redirect_after_sign_in(user)
     unless params[:return_to].blank?
       return_to = Addressable::URI.parse(params[:return_to])
-      
-      if return_to.host.nil? || return_to.host == request.host
-        redirect_to params[:return_to]
-        return
-      elsif valid_remote_host?(return_to.host)
-        if user.class.include?(Janus::Models::RemoteAuthenticatable)
-          query = return_to.query_values || {}
-          return_to.query_values = query.merge(user.class.remote_authentication_key => user.generate_remote_token!)
+
+      unless never_return_to(user).include?(return_to.path)
+        if return_to.host.nil? || return_to.host == request.host
+          redirect_to params[:return_to]
+          return
+        elsif valid_remote_host?(return_to.host)
+          if user.class.include?(Janus::Models::RemoteAuthenticatable)
+            query = return_to.query_values || {}
+            return_to.query_values = query.merge(user.class.remote_authentication_key => user.generate_remote_token!)
+          end
+          
+          redirect_to return_to.to_s
+          return
         end
-        
-        redirect_to return_to.to_s
-        return
       end
     end
     

data/lib/janus/manager.rb

@@ -34,7 +34,7 @@ module Janus
 
     # Logs a user in.
     # 
-    # FIXME: what should happen when a user signs in but a user is already signed in?!
+    # FIXME: what should happen when a user signs in but a user is already signed in for the same scope?!
     def login(user, options = {})
       options[:scope] ||= Janus.scope_for(user)
       set_user(user, options)
@@ -76,8 +76,13 @@ module Janus
       
       if authenticated?(scope)
         if @users[scope].nil?
+          begin
           @users[scope] = session(scope)[:user_class].find(session(scope)[:user_id])
-          Janus::Manager.run_callbacks(:fetch, @users[scope], self, :scope => scope)
+          rescue ActiveRecord::RecordNotFound
+            unset_user(scope)
+          else
+            Janus::Manager.run_callbacks(:fetch, @users[scope], self, :scope => scope)
+          end
         end
         
         @users[scope]

data/lib/janus/models/database_authenticatable.rb

@@ -1,4 +1,5 @@
 require 'bcrypt'
+require 'scrypt'
 
 module Janus
   module Models
@@ -24,13 +25,13 @@ module Janus
 
       included do
         attr_protected :encrypted_password, :reset_password_token, :reset_password_sent_at
-        attr_reader   :password
-        attr_accessor :current_password
+        attr_reader    :password
+        attr_accessor  :current_password
         
         validates :password, :presence => true, :confirmation => true, :if => :password_required?
         validate :validate_current_password, :on => :update, :if => :current_password
         
-        janus_config(:authentication_keys, :stretches, :pepper)
+        janus_config(:authentication_keys, :encryptor, :stretches, :pepper, :scrypt_options)
       end
 
       def password=(password)
@@ -38,13 +39,28 @@ module Janus
         self.encrypted_password = digest_password(@password) unless @password.blank?
       end
 
-      # Checks if a given password matches this user password.
+      # Checks if a given password matches this user's password.
       def valid_password?(password)
-        ::BCrypt::Password.new(encrypted_password) == "#{password}#{self.class.pepper}"
+        case self.class.encryptor
+        when :bcrypt
+          ::BCrypt::Password.new(encrypted_password) == salted_password(password)
+        when :scrypt
+          ::SCrypt::Password.new(encrypted_password) == salted_password(password)
+        end
       end
 
+      # Digests a password using either bcrypt or scrypt (as configured by `config.encryptor`).
       def digest_password(password)
-        ::BCrypt::Password.create("#{password}#{self.class.pepper}", :cost => self.class.stretches).to_s
+        case self.class.encryptor
+        when :bcrypt
+          ::BCrypt::Password.create(salted_password(password), :cost => self.class.stretches).to_s
+        when :scrypt
+          ::SCrypt::Password.create(salted_password(password), self.class.scrypt_options).to_s
+        end
+      end
+
+      def salted_password(password)
+        "#{password}#{self.class.pepper}"
       end
 
       def clean_up_passwords