quo_vadis 1.0.2 → 1.0.3

data/.gitignore

@@ -3,3 +3,4 @@ pkg/*
 .bundle
 test/dummy/log/*
 test/dummy/tmp/*
+rdoc/*

data/README.md

@@ -8,14 +8,13 @@ Features:
 * No surprises: it does what you expect.
 * Easy to customise.
 * Uses BCrypt to encrypt passwords.
-* Sign in, sign out, forgotten password, authenticate actions.
+* Sign in, sign out, forgotten password, authenticate actions, remember user between browser sessions.
 
 Forthcoming features:
 
-* Generate the views for you.
+* Generate the views for you (for now, copy the examples given below).
 * Let you choose which model(s) to authenticate (currently `User`).
 * Let you choose the identification field (currently `username`).
-* Remember authenticated user across browser sessions.
 * HTTP basic/digest authentication (probably).
 * Generate (User) model plus migration if it doesn't exist.
 * Detect presence of `has_secure_password` (see below) and adapt appropriately.
@@ -58,7 +57,7 @@ Write the sign-in view.  Your sign-in form must:
 * be in `app/views/sessions/new.html.:format`
 * POST the parameters `:username` and `:password` to `sign_in_url`
 
-You have to write the view yourself because you'd inevitably want to change whatever markup I generated for you.
+You have to write the view yourself because you'd inevitably want to change whatever markup I generated for you.  You can find an example in the [test app](https://github.com/airblade/quo_vadis/blob/master/test/dummy/app/views/sessions/new.html.erb).
 
 Remember to serve your sign in form over HTTPS -- to avoid [the credentials being stolen](http://blog.jgc.org/2011/01/code-injected-to-steal-passwords-in.html).
 
@@ -80,12 +79,12 @@ It'll take you about 5 minutes to implement this.
 
 On your sign-in page, link to the forgotten-password view at `forgotten_sign_in_url`.
 
-Write the forgotten-password view.  The form must:
+Write the forgotten-password view ([example](https://github.com/airblade/quo_vadis/blob/master/test/dummy/app/views/sessions/forgotten.html.erb)).  The form must:
 
 * be in `app/views/sessions/forgotten.html.:format`
 * POST the parameter `:username` to `forgotten_sign_in_url`
 
-Now write the mailer view, i.e. the email which will be sent to your forgetful users.  The view must:
+Now write the mailer view, i.e. the email which will be sent to your forgetful users ([example](https://github.com/airblade/quo_vadis/blob/master/test/dummy/app/views/quo_vadis/notifier/change_password.text.erb)).  The view must:
 
 * be at `app/views/quo_vadis/notifier/change_password.text.erb`
 * render `@url` somewhere (this is the link the user clicks to go to the change-password page)
@@ -98,7 +97,7 @@ Configure the default host so ActionMailer can generate the URL.  In `config/env
 
     config.action_mailer.default_url_options = {:host => 'yourdomain.com'}
 
-Finally, write the change-password page.  The form must:
+Finally, write the change-password page ([example](https://github.com/airblade/quo_vadis/blob/master/test/dummy/app/views/sessions/edit.html.erb)).  The form must:
 
 * be in `app/views/sessions/edit.html.:format`
 * PUT the parameter `:password` to `change_password_url(params[:token])`
@@ -106,13 +105,34 @@ Finally, write the change-password page.  The form must:
 
 ## Customisation
 
-You can customise the flash messages in `config/locales/quo_vadis.en.yml`.
+You can customise the flash messages and mailer from/subject in `config/locales/quo_vadis.en.yml`.
 
 You can customise the sign-in and sign-out redirects in `config/initializers/quo_vadis.rb`; they both default to the root route.  You can also hook into the sign-in and sign-out process if you need to run any other code.
 
 If you want to add other session management type features, go right ahead: create a `SessionsController` as normal and carry on.
 
 
+## Sign up / user registration
+
+Quo Vadis doesn't offer sign-up because that's user management, not authentication.
+
+However if you have implemented user sign-up yourself, you need to be able to sign in a newly created user.  Do this by calling `sign_in(user)` in your controller.  For example:
+
+    # In your app
+    class UsersController < ApplicationController
+      def create
+        @user = User.new params[:user]
+        if @user.save
+          sign_in @user    # <-- NOTE: sign in your user here
+        else
+          render 'new'
+        end
+      end
+    end
+
+The `sign_in(user)` method will redirect the user appropriately (you can configure this in `config/initializers/quo_vadis.rb`), as well as running any sign-in hook you may have defined in the initializer.
+
+
 ## See also
 
 * Rails 3 edge's [ActiveModel::SecurePassword](https://github.com/rails/rails/blob/master/activemodel/lib/active_model/secure_password.rb).  It's `has_secure_password` class method is similar to Quo Vadis's `authenticates` class method.
@@ -122,3 +142,15 @@ If you want to add other session management type features, go right ahead: creat
 ## What's up with the name?
 
 Roman sentries used to challenge intruders with, "Halt!  Who goes there?"; quo vadis is Latin for "Who goes there?".  At least that's what my Latin teacher told us, but I was 8 years old then so I may not be remembering this entirely accurately.
+
+
+## Questions, Problems, Feedback
+
+Please use the GitHub [issue tracker](https://github.com/airblade/quo_vadis/issues) or email me.
+
+
+## Intellectual property
+
+Copyright 2011 Andy Stewart (boss@airbladesoftware.com).
+
+Released under the MIT licence.

data/Rakefile

@@ -2,6 +2,7 @@ require 'bundler'
 Bundler::GemHelper.install_tasks
 
 require 'rake/testtask'
+require 'rake/rdoctask'
 
 Rake::TestTask.new(:test) do |t|
   t.libs << 'lib'
@@ -10,4 +11,12 @@ Rake::TestTask.new(:test) do |t|
   t.verbose = false
 end
 
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Quo Vadis'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('app/**/*.rb')
+end
+
 task :default => :test

data/app/controllers/controller_mixin.rb

@@ -5,14 +5,22 @@ module ControllerMixin
 
   private
 
+  # Remembers the authenticated <tt>user</tt> (in this session and future sessions).
+  #
+  # If you want to sign in a <tt>user</tt>, call <tt>QuoVadis::SessionsController#sign_in</tt>
+  # instead.
   def current_user=(user)
-    session[:current_user_id] = user ? user.id : nil
+    remember_user_in_session user
+    remember_user_between_sessions user
   end
 
+  # Returns the authenticated user.
   def current_user
-    @current_user ||= User.find(session[:current_user_id]) if session[:current_user_id]
+    @current_user ||= find_authenticated_user
   end
 
+  # Does nothing if we already have an authenticated user.  If we don't have an
+  # authenticated user, it stores the desired URL and redirects to the sign in URL.
   def authenticate
     unless current_user
       session[:quo_vadis_original_url] = request.fullpath
@@ -20,4 +28,32 @@ module ControllerMixin
       redirect_to sign_in_url
     end
   end
+
+  def remember_user_in_session(user) # :nodoc:
+    session[:current_user_id] = user ? user.id : nil
+  end
+
+  def remember_user_between_sessions(user) # :nodoc:
+    if user && QuoVadis.remember_for
+      cookies.signed[:remember_me] = {
+        :value    => [user.id, user.password_salt],
+        :expires  => QuoVadis.remember_for.from_now,
+        :httponly => true
+      }
+    else
+      cookies.delete :remember_me
+    end
+  end
+
+  def find_authenticated_user # :nodoc:
+    find_user_by_session || find_user_by_cookie
+  end
+
+  def find_user_by_cookie # :nodoc:
+    User.find_by_salt(*cookies.signed[:remember_me]) if cookies.signed[:remember_me]
+  end
+
+  def find_user_by_session # :nodoc:
+    User.find(session[:current_user_id]) if session[:current_user_id]
+  end
 end

data/app/controllers/quo_vadis/sessions_controller.rb

@@ -74,26 +74,35 @@ class QuoVadis::SessionsController < ApplicationController
     end
   end
 
-  private
+  protected
 
+  # Signs in a user, i.e. remembers them in the session, runs the sign-in hook,
+  # and redirects appropriately.
+  #
+  # This method should be called when you have just authenticated <tt>user</tt>
+  # and you need to sign them in.  For example, if a new user has just signed up,
+  # you should call this method to sign them in.
   def sign_in(user)
     self.current_user = user
     QuoVadis.signed_in_hook user, self
     redirect_to QuoVadis.signed_in_url(user, original_url)
   end
 
+  private
+
+  # Returns the URL if any which the user tried to visit before being forced to authenticate.
   def original_url
     url = session[:quo_vadis_original_url]
     session[:quo_vadis_original_url] = nil
     url
   end
 
-  def invalid_token
+  def invalid_token # :nodoc:
     flash[:alert] = t('quo_vadis.flash.forgotten.invalid_token') unless t('quo_vadis.flash.forgotten.invalid_token').blank?
     redirect_to forgotten_sign_in_url
   end
 
-  def quo_vadis_layout
+  def quo_vadis_layout # :nodoc:
     QuoVadis.layout
   end
 

data/app/mailers/quo_vadis/notifier.rb

@@ -1,6 +1,8 @@
 module QuoVadis
   class Notifier < ActionMailer::Base
 
+    # Sends an email to <tt>user</tt> with a link to a page where they
+    # can change their password.
     def change_password(user)
       @username = user.username
       @url = change_password_url user.token

data/app/models/model_mixin.rb

@@ -7,6 +7,9 @@ module ModelMixin
   end
 
   module ClassMethods
+    # Adds methods to set and authenticate against a password stored encrypted by BCrypt.
+    # Also adds methods to generate and clear a token, used to retrieve the record of a
+    # user who has forgotten their password.
     def authenticates
       send :include, InstanceMethodsOnActivation
 
@@ -20,6 +23,8 @@ module ModelMixin
       scope :valid_token, lambda { |token| where("token = ? AND token_created_at > ?", token, 3.hours.ago) }
 
       instance_eval <<-END
+        # Returns the user with the given <tt>username</tt> if the given password is
+        # correct, and <tt>nil</tt> otherwise.
         def authenticate(username, plain_text_password)
           user = where(:username => username).first
           if user && user.has_matching_password?(plain_text_password)
@@ -28,17 +33,28 @@ module ModelMixin
             nil
           end
         end
+
+        def find_by_salt(id, salt) # :nodoc:
+          user = User.find_by_id id
+          if user && user.has_matching_salt?(salt)
+            user
+          else
+            nil
+          end
+        end
       END
     end
   end
 
   module InstanceMethodsOnActivation
-    def password=(plain_text_password)
+    def password=(plain_text_password) # :nodoc:
       @password = plain_text_password
       self.password_digest = BCrypt::Password.create plain_text_password
     end
 
-    def generate_token
+    # Generates a unique, timestamped token which can be used in URLs, and
+    # saves the record.  This is part of the forgotten-password workflow.
+    def generate_token # :nodoc:
       begin
         self.token = url_friendly_token
       end while self.class.exists?(:token => token)
@@ -46,17 +62,31 @@ module ModelMixin
       save
     end
 
-    def clear_token
+    # Clears the user's timestamped token and saves the record.
+    # This is part of the forgotten-password workflow.
+    def clear_token # :nodoc:
       update_attributes :token => nil, :token_created_at => nil
     end
 
-    def has_matching_password?(plain_text_password)
+    # Returns true if the given <tt>plain_text_password</tt> is the user's
+    # password, and false otherwise.
+    def has_matching_password?(plain_text_password) # :nodoc:
       BCrypt::Password.new(password_digest) == plain_text_password
     end
 
+    # Returns true if the given <tt>salt</tt> is the user's salt,
+    # and false otherwise.
+    def has_matching_salt?(salt) # :nodoc:
+      password_salt == salt
+    end
+
+    def password_salt # :nodoc:
+      BCrypt::Password.new(password_digest).salt
+    end
+
     private
 
-    def url_friendly_token
+    def url_friendly_token # :nodoc:
       ActiveSupport::SecureRandom.base64(10).tr('+/=', 'xyz')
     end
   end

data/config/initializers/quo_vadis.rb

@@ -1,7 +1,7 @@
 QuoVadis.configure do |config|
 
   #
-  # Redirection URLs
+  # Sign in
   #
 
   # The URL to redirect the user to after s/he signs in.
@@ -18,14 +18,6 @@ QuoVadis.configure do |config|
   # to reach when they were made to authenticate.
   config.override_original_url = false
 
-  # The URL to redirect the user to after s/he signs out.
-  config.signed_out_url = :root
-
-
-  #
-  # Hooks
-  #
-
   # Code to run when the user has signed in.  E.g.:
   #
   # config.signed_in_hook = Proc.new do |user, controller|
@@ -40,6 +32,18 @@ QuoVadis.configure do |config|
   # end
   config.failed_sign_in_hook = nil
 
+  # How long to remember user across browser sessions.
+  # Set to <tt>nil</tt> to never remember user.
+  config.remember_for = 2.weeks
+
+
+  #
+  # Sign out
+  #
+
+  # The URL to redirect the user to after s/he signs out.
+  config.signed_out_url = :root
+
   # Code to run just before the user has signed out.  E.g.:
   #
   # config.signed_out_hook = Proc.new do |user, controller|

data/lib/quo_vadis/version.rb

@@ -1,3 +1,3 @@
 module QuoVadis
-  VERSION = '1.0.2'
+  VERSION = '1.0.3'
 end

data/lib/quo_vadis.rb

@@ -1,9 +1,10 @@
 require 'quo_vadis/engine'
+require 'active_support/core_ext/numeric/time'
 
 module QuoVadis
 
   #
-  # Redirection URLs
+  # Sign in
   #
 
   # The URL to redirect the user to after s/he signs in.
@@ -15,7 +16,7 @@ module QuoVadis
   mattr_accessor :override_original_url
   @@override_original_url = false
 
-  def self.signed_in_url(user, original_url)
+  def self.signed_in_url(user, original_url) # :nodoc:
     if original_url && !@@override_original_url
       original_url
     else
@@ -23,20 +24,11 @@ module QuoVadis
     end
   end
 
-  # The URL to redirect the user to after s/he signs out.
-  mattr_accessor :signed_out_url
-  @@signed_in_url = :root
-
-
-  #
-  # Hooks
-  #
-
   # Code to run when the user has signed in.
   mattr_accessor :signed_in_hook
   @@signed_in_hook = nil
 
-  def self.signed_in_hook(user, controller)
+  def self.signed_in_hook(user, controller) # :nodoc:
     @@signed_in_hook.call(user, controller) if @@signed_in_hook
   end
 
@@ -44,15 +36,29 @@ module QuoVadis
   mattr_accessor :failed_sign_in_hook
   @@failed_sign_in_hook = nil
 
-  def self.failed_sign_in_hook(controller)
+  def self.failed_sign_in_hook(controller) # :nodoc:
     @@failed_sign_in_hook.call(controller) if @@failed_sign_in_hook
   end
 
+  # How long to remember user across browser sessions.
+  mattr_accessor :remember_for
+  @@remember_for = 2.weeks
+
+
+  #
+  # Sign out
+  #
+
+  # The URL to redirect the user to after s/he signs out.
+  mattr_accessor :signed_out_url
+  @@signed_in_url = :root
+
+
   # Code to run just before the user has signed out.
   mattr_accessor :signed_out_hook
   @@signed_out_hook = nil
 
-  def self.signed_out_hook(user, controller)
+  def self.signed_out_hook(user, controller) # :nodoc:
     @@signed_out_hook.call(user, controller) if @@signed_out_hook
   end
 
@@ -70,6 +76,7 @@ module QuoVadis
   @@subject = 'Change your password.'
 
 
+
   #
   # Miscellaneous
   #

data/test/dummy/config/locales/quo_vadis.en.yml

@@ -1,7 +1,8 @@
 en:
   quo_vadis:
     flash:
-      before_sign_in: 'Please sign in first.'
-      after_sign_in: 'You have successfully signed in.'
-      failed_sign_in: 'Sorry, we did not recognise you.'
+      sign_in:
+        before: 'Please sign in first.'
+        after: 'You have successfully signed in.'
+        failed: 'Sorry, we did not recognise you.'
       sign_out: 'You have successfully signed out.'

data/test/integration/cookie_test.rb

@@ -0,0 +1,97 @@
+require 'test_helper'
+
+class CookieTest < ActiveSupport::IntegrationCase
+
+  teardown do
+    Capybara.reset_sessions!
+    reset_quo_vadis_configuration
+  end
+
+  test 'authenticated user is remembered between browser sessions' do
+    user_factory 'Bob', 'bob', 'secret'
+    sign_in_as 'bob', 'secret'
+    close_browser
+    visit root_path
+    within '#topnav' do
+      assert page.has_content?('You are signed in as Bob.')
+    end
+    assert page.has_no_css?('div.flash')
+  end
+
+  test "signing in updates the remember-me cookie's expiry time" do
+    user_factory 'Bob', 'bob', 'secret'
+    sign_in_as 'bob', 'secret'
+    cookie_a = get_cookie('remember_me')
+    assert_equal 2.weeks.from_now.httpdate, cookie_a.expires.httpdate
+    close_browser
+    sleep 1  # cookie expiry times are accurate to 1 second.
+
+    sign_in_as 'bob', 'secret'
+    cookie_b = get_cookie('remember_me')
+    assert cookie_b.expires > cookie_a.expires
+    assert_equal cookie_a.value, cookie_b.value
+  end
+
+  test 'signing out prevents the user being remembered in the next browser session' do
+    user_factory 'Bob', 'bob', 'secret'
+    sign_in_as 'bob', 'secret'
+    visit sign_out_path
+    close_browser
+    visit new_article_path
+    assert_equal sign_in_path, current_path
+  end
+
+  test "changing user's password prevents user being remembered in the next browser session" do
+    user_factory 'Bob', 'bob', 'secret'
+    sign_in_as 'bob', 'secret'
+    cookie = get_cookie('remember_me')
+    User.last.update_attributes! :password => 'topsecret'
+    close_browser
+    visit new_article_path
+    assert_equal sign_in_path, current_path
+  end
+
+  test 'length of time user is remembered can be configured' do
+    QuoVadis.remember_for = 1.second
+    user_factory 'Bob', 'bob', 'secret'
+    sign_in_as 'bob', 'secret'
+    close_browser
+    sleep 2
+    visit new_article_path
+    assert_equal sign_in_path, current_path
+  end
+
+  test 'remembering user between sessions can be turned off' do
+    QuoVadis.remember_for = nil
+    user_factory 'Bob', 'bob', 'secret'
+    sign_in_as 'bob', 'secret'
+    close_browser
+    visit new_article_path
+    assert_equal sign_in_path, current_path
+  end
+
+
+  #
+  # Code below from https://github.com/nruth/show_me_the_cookies
+  #
+
+  def delete_cookie(cookie_name)
+    cookie_jar.instance_variable_get(:@cookies).reject! do |existing_cookie|
+      existing_cookie.name.downcase == cookie_name
+    end
+  end
+
+  def get_cookie(cookie_name)
+    cookie_jar.instance_variable_get(:@cookies).select do |existing_cookie|
+      existing_cookie.name.downcase == cookie_name
+    end.first
+  end
+
+  def cookie_jar
+    Capybara.current_session.driver.current_session.instance_variable_get(:@rack_mock_session).cookie_jar
+  end
+
+  def close_browser
+    delete_cookie Rails.application.config.session_options[:key]
+  end
+end

data/test/test_helper.rb

@@ -52,4 +52,5 @@ def reset_quo_vadis_configuration
   QuoVadis.layout                = 'application'
   QuoVadis.from                  = 'noreply@example.com'
   QuoVadis.subject               = 'Change your password'
+  QuoVadis.remember_for          = 2.weeks
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: quo_vadis
 version: !ruby/object:Gem::Version 
-  hash: 19
+  hash: 17
   prerelease: false
   segments: 
   - 1
   - 0
-  - 2
-  version: 1.0.2
+  - 3
+  version: 1.0.3
 platform: ruby
 authors: 
 - Andy Stewart
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-01-27 00:00:00 +00:00
+date: 2011-02-07 00:00:00 +00:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -177,6 +177,7 @@ files:
 - test/dummy/tmp/capybara/capybara-20110124135435.html
 - test/integration/authenticate_test.rb
 - test/integration/config_test.rb
+- test/integration/cookie_test.rb
 - test/integration/forgotten_test.rb
 - test/integration/helper_test.rb
 - test/integration/locale_test.rb
@@ -278,6 +279,7 @@ test_files:
 - test/dummy/tmp/capybara/capybara-20110124135435.html
 - test/integration/authenticate_test.rb
 - test/integration/config_test.rb
+- test/integration/cookie_test.rb
 - test/integration/forgotten_test.rb
 - test/integration/helper_test.rb
 - test/integration/locale_test.rb