quo_vadis 0.0.1 → 1.0.0

data/.gitignore

@@ -1,3 +1,5 @@
 pkg/*
 *.gem
 .bundle
+test/dummy/log/*
+test/dummy/tmp/*

data/Gemfile.lock

@@ -0,0 +1,114 @@
+PATH
+  remote: .
+  specs:
+    quo_vadis (1.0.0)
+      bcrypt-ruby (~> 2.1.4)
+      rails (~> 3.0)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    abstract (1.0.0)
+    actionmailer (3.0.3)
+      actionpack (= 3.0.3)
+      mail (~> 2.2.9)
+    actionpack (3.0.3)
+      activemodel (= 3.0.3)
+      activesupport (= 3.0.3)
+      builder (~> 2.1.2)
+      erubis (~> 2.6.6)
+      i18n (~> 0.4)
+      rack (~> 1.2.1)
+      rack-mount (~> 0.6.13)
+      rack-test (~> 0.5.6)
+      tzinfo (~> 0.3.23)
+    activemodel (3.0.3)
+      activesupport (= 3.0.3)
+      builder (~> 2.1.2)
+      i18n (~> 0.4)
+    activerecord (3.0.3)
+      activemodel (= 3.0.3)
+      activesupport (= 3.0.3)
+      arel (~> 2.0.2)
+      tzinfo (~> 0.3.23)
+    activeresource (3.0.3)
+      activemodel (= 3.0.3)
+      activesupport (= 3.0.3)
+    activesupport (3.0.3)
+    arel (2.0.4)
+    bcrypt-ruby (2.1.4)
+    builder (2.1.2)
+    capybara (0.4.1.1)
+      celerity (>= 0.7.9)
+      culerity (>= 0.2.4)
+      mime-types (>= 1.16)
+      nokogiri (>= 1.3.3)
+      rack (>= 1.0.0)
+      rack-test (>= 0.5.4)
+      selenium-webdriver (>= 0.0.27)
+      xpath (~> 0.1.3)
+    celerity (0.8.7)
+    childprocess (0.1.6)
+      ffi (~> 0.6.3)
+    configuration (1.2.0)
+    culerity (0.2.15)
+    erubis (2.6.6)
+      abstract (>= 1.0.0)
+    ffi (0.6.3)
+      rake (>= 0.8.7)
+    i18n (0.4.1)
+    json_pure (1.5.0)
+    launchy (0.3.7)
+      configuration (>= 0.0.5)
+      rake (>= 0.8.1)
+    mail (2.2.10)
+      activesupport (>= 2.3.6)
+      i18n (~> 0.4.1)
+      mime-types (~> 1.16)
+      treetop (~> 1.4.8)
+    mime-types (1.16)
+    nokogiri (1.4.4)
+    polyglot (0.3.1)
+    rack (1.2.1)
+    rack-mount (0.6.13)
+      rack (>= 1.0.0)
+    rack-test (0.5.6)
+      rack (>= 1.0)
+    rails (3.0.3)
+      actionmailer (= 3.0.3)
+      actionpack (= 3.0.3)
+      activerecord (= 3.0.3)
+      activeresource (= 3.0.3)
+      activesupport (= 3.0.3)
+      bundler (~> 1.0)
+      railties (= 3.0.3)
+    railties (3.0.3)
+      actionpack (= 3.0.3)
+      activesupport (= 3.0.3)
+      rake (>= 0.8.7)
+      thor (~> 0.14.4)
+    rake (0.8.7)
+    rubyzip (0.9.4)
+    selenium-webdriver (0.1.2)
+      childprocess (~> 0.1.5)
+      ffi (~> 0.6.3)
+      json_pure
+      rubyzip
+    sqlite3-ruby (1.2.5)
+    thor (0.14.6)
+    treetop (1.4.8)
+      polyglot (>= 0.3.1)
+    tzinfo (0.3.23)
+    xpath (0.1.3)
+      nokogiri (~> 1.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bcrypt-ruby (~> 2.1.4)
+  capybara (>= 0.4.0)
+  launchy
+  quo_vadis!
+  rails (~> 3.0)
+  sqlite3-ruby

data/README.md

@@ -0,0 +1,79 @@
+# Quo Vadis?
+
+Quo Vadis adds simple username/password authentication to Rails 3 applications.
+
+Features:
+
+* Minimal effort to add authentication to your app: get up and running in 5 minutes.
+* No surprises: it does what you expect.
+* Easy to customise.
+* Uses BCrypt to encrypt passwords.
+* Sign in, sign out, authenticate actions.
+
+Forthcoming features:
+
+* Handle forgotten-details.
+* 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.
+
+What it doesn't and won't do:
+
+* Authorisation.
+* Sign up; that's user management, not authentication.
+* Work outside Rails 3.
+* OpenID, OAuth, LDAP, CAS, etc.
+* Separate identity from authentication services (cf OmniAuth).
+* Allow you to have multiple models/scope signed in simultaneously (cf Devise).
+* Offer so much flexibility that it takes more than 10 minutes to wrap your head around it (cf Devise, Authlogic).
+
+
+## Quick Start
+
+Install and run the generator: add `gem 'quo_vadis'` to your Gemfile and run `rails generate quo_vadis:install`.
+
+Edit and run the generated migration to add authentication columns: `rake db:migrate`.  Note the migration (currently) assumes you already have a `User` model.
+
+In your `User` model, add `authenticates`:
+
+    class User < ActiveRecord::Base
+      authenticates
+    end
+
+Note Quo Vadis validates the presence of the password, but it's up to you to add any other validations you want.
+
+Use `:authenticate` in a `before_filter` to protect your controllers' actions.  For example:
+
+    class ArticleController < ActionController::Base
+      before_filter :authenticate, :except => [:index, :show]
+    end
+
+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`
+
+In your layout, use `current_user` to retrieve the signed-in user, and `sign_in_path` and `sign_out_path` as appropriate.
+
+
+## Customisation
+
+You can customise the flash messages 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.
+
+
+## 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.
+* [RailsCast 250: Authentication from Scratch](http://railscasts.com/episodes/250-authentication-from-scratch).
+
+
+## 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.

data/Rakefile

@@ -1,2 +1,13 @@
 require 'bundler'
 Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+task :default => :test

data/app/controllers/controller_mixin.rb

@@ -0,0 +1,20 @@
+module ControllerMixin
+  def self.included(base)
+    base.helper_method :current_user
+  end
+
+  private  # TODO: does this mark them as private once mixed in?
+
+  def current_user=(user)
+    session[:current_user_id] = user ? user.id : nil
+  end
+
+  def current_user
+    @current_user ||= User.find(session[:current_user_id]) if session[:current_user_id]
+  end
+
+  def authenticate
+    session[:quo_vadis_original_url] = request.fullpath
+    redirect_to sign_in_url, :notice => t('quo_vadis.flash.before_sign_in') unless current_user
+  end
+end

data/app/controllers/quo_vadis/sessions_controller.rb

@@ -0,0 +1,36 @@
+class QuoVadis::SessionsController < ApplicationController
+
+  # sign in
+  def new
+    render 'sessions/new'
+  end
+
+  # sign in
+  def create
+    if user = User.authenticate(params[:username], params[:password])
+      self.current_user = user
+      QuoVadis.signed_in_hook user, request
+      redirect_to QuoVadis.signed_in_url(user, original_url), :notice => t('quo_vadis.flash.after_sign_in')
+    else
+      QuoVadis.failed_sign_in_hook request
+      flash.now[:alert] = t('quo_vadis.flash.failed_sign_in')
+      render 'sessions/new'
+    end
+  end
+
+  # sign out
+  def destroy
+    QuoVadis.signed_out_hook current_user, request
+    self.current_user = nil
+    redirect_to QuoVadis.signed_out_url, :notice => t('quo_vadis.flash.sign_out')
+  end
+
+  private
+
+  def original_url
+    url = session[:quo_vadis_original_url]
+    session[:quo_vadis_original_url] = nil
+    url
+  end
+
+end

data/app/models/model_mixin.rb

@@ -0,0 +1,44 @@
+require 'bcrypt'
+
+module ModelMixin
+
+  def self.included(base)
+    base.send :extend, ClassMethods
+  end
+
+  module ClassMethods
+    def authenticates
+      send :include, InstanceMethodsOnActivation
+
+      attr_reader    :password
+      attr_protected :password_digest
+
+      validates      :username,        :presence => true, :uniqueness => true
+      validates      :password,        :on => :create, :presence => true
+      validates      :password_digest, :presence => true
+
+      instance_eval <<-END
+        def authenticate(username, plain_text_password)
+          user = where(:username => username).first
+          if user && user.has_matching_password?(plain_text_password)
+            user
+          else
+            nil
+          end
+        end
+      END
+    end
+  end
+
+  module InstanceMethodsOnActivation
+    def password=(plain_text_password)
+      @password = plain_text_password
+      self.password_digest = BCrypt::Password.create plain_text_password
+    end
+
+    def has_matching_password?(plain_text_password)
+      BCrypt::Password.new(password_digest) == plain_text_password
+    end
+  end
+
+end

data/config/initializers/quo_vadis.rb

@@ -0,0 +1,50 @@
+QuoVadis.configure do |config|
+
+  #
+  # Redirection URLs
+  #
+
+  # The URL to redirect the user to after s/he signs in.
+  # Use a proc if the URL depends on the user.  E.g.:
+  #
+  # config.signed_in_url = Proc.new do |user|
+  #   user.admin? ? :admin : :root
+  # end
+  #
+  # See also `:override_original_url`.
+  config.signed_in_url = :root
+
+  # Whether the `:signed_in_url` should override the URL the user was trying
+  # 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, request|
+  #   user.increment! :sign_in_count  # assuming this attribute exists
+  # end
+  config.signed_in_hook = nil
+
+  # Code to run when someone has tried but failed to sign in.  E.g.:
+  #
+  # config.failed_sign_in_hook = Proc.new do |request|
+  #   logger.info "Failed sign in from #{request.remote_ip}"
+  # end
+  config.failed_sign_in_hook = nil
+
+  # Code to run just before the user has signed out.  E.g.:
+  #
+  # config.signed_out_hook = Proc.new do |user, request|
+  #   session.reset
+  # end
+  config.signed_out_hook = nil
+
+end

data/config/locales/quo_vadis.en.yml

@@ -0,0 +1,7 @@
+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_out: 'You have successfully signed out.'

data/config/routes.rb

@@ -0,0 +1,7 @@
+Rails.application.routes.draw do |map|
+  scope :module => 'quo_vadis' do
+    get  'sign-in'  => 'sessions#new',     :as => 'sign_in'
+    post 'sign-in'  => 'sessions#create',  :as => 'sign_in'
+    get  'sign-out' => 'sessions#destroy', :as => 'sign_out'
+  end
+end

data/lib/generators/quo_vadis/install_generator.rb

@@ -0,0 +1,28 @@
+require 'rails/generators'
+require 'rails/generators/migration'
+require 'rails/generators/active_record/migration'
+
+module QuoVadis
+  class InstallGenerator < Rails::Generators::Base
+    include Rails::Generators::Migration
+    extend ActiveRecord::Generators::Migration
+
+    source_root File.expand_path('../templates', __FILE__)
+
+    desc 'Copies an initializer, a locale file, and a migration to your application.'
+
+
+    def copy_locale_file
+      copy_file '../../../../config/locales/quo_vadis.en.yml', 'config/locales/quo_vadis.en.yml'
+    end
+
+    def copy_initializer_file
+      copy_file '../../../../config/initializers/quo_vadis.rb', 'config/initializers/quo_vadis.rb'
+    end
+
+    def create_migration_file
+      migration_template 'migration.rb', 'db/migrate/add_authentication_to_users.rb'
+    end
+
+  end
+end

data/lib/generators/quo_vadis/templates/migration.rb

@@ -0,0 +1,11 @@
+class AddAuthenticationToUsers < ActiveRecord::Migration
+  def self.up
+    add_column :users, :username,        :string  # for user identification
+    add_column :users, :password_digest, :string
+  end
+
+  def self.down
+    remove_column :users, :username
+    remove_column :users, :password_digest
+  end
+end

data/lib/quo_vadis/engine.rb

@@ -0,0 +1,15 @@
+module QuoVadis
+  class Engine < ::Rails::Engine
+    initializer 'quo_vadis.model' do |app|
+      ActiveSupport.on_load(:active_record) do
+        include ModelMixin
+      end
+    end
+
+    initializer 'quo_vadis.controller' do |app|
+      ActiveSupport.on_load(:action_controller) do
+        include ControllerMixin
+      end
+    end
+  end
+end

data/lib/quo_vadis/version.rb

@@ -1,3 +1,3 @@
 module QuoVadis
-  VERSION = "0.0.1"
+  VERSION = '1.0.0'
 end

data/lib/quo_vadis.rb

@@ -1,3 +1,65 @@
+require 'quo_vadis/engine'
+
 module QuoVadis
-  # Your code goes here...
+
+  #
+  # Redirection URLs
+  #
+
+  # The URL to redirect the user to after s/he signs in.
+  mattr_accessor :signed_in_url
+  @@signed_in_url = :root
+
+  # Whether the `:signed_in_url` should override the URL the user was trying
+  # to reach when they were made to authenticate.
+  mattr_accessor :override_original_url
+  @@override_original_url = false
+
+  def self.signed_in_url(user, original_url)
+    if original_url && !@@override_original_url
+      original_url
+    else
+      @@signed_in_url.respond_to?(:call) ?  @@signed_in_url.call(user) : @@signed_in_url
+    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, request)
+    @@signed_in_hook.call(user, request) if @@signed_in_hook
+  end
+
+  # Code to run when someone has tried but failed to sign in.
+  mattr_accessor :failed_sign_in_hook
+  @@failed_sign_in_hook = nil
+
+  def self.failed_sign_in_hook(request)
+    @@failed_sign_in_hook.call(request) if @@failed_sign_in_hook
+  end
+
+  # 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, request)
+    @@signed_out_hook.call(user, request) if @@signed_out_hook
+  end
+
+
+  # Configure from the initializer.
+  def self.configure
+    yield self
+  end
+
 end

data/quo_vadis.gemspec

@@ -9,7 +9,7 @@ Gem::Specification.new do |s|
   s.authors     = ['Andy Stewart']
   s.email       = ['boss@airbladesoftware.com']
   s.homepage    = ''
-  s.summary     = %q{Simple authentication for Rails 3.}
+  s.summary     = 'Simple authentication for Rails 3.'
   s.description = s.summary
 
   s.rubyforge_project = 'quo_vadis'
@@ -18,4 +18,11 @@ Gem::Specification.new do |s|
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ['lib']
+
+  s.add_dependency 'rails',       '~>3.0'
+  s.add_dependency 'bcrypt-ruby', '~>2.1.4'
+
+  s.add_development_dependency 'sqlite3-ruby'
+  s.add_development_dependency 'capybara', '>= 0.4.0'
+  s.add_development_dependency 'launchy'
 end

data/test/dummy/.gitignore

@@ -0,0 +1 @@
+db/*.sqlite3

data/test/dummy/app/controllers/application_controller.rb

@@ -0,0 +1,3 @@
+class ApplicationController < ActionController::Base
+  protect_from_forgery
+end

data/test/dummy/app/controllers/articles_controller.rb

@@ -0,0 +1,11 @@
+class ArticlesController < ApplicationController
+  before_filter :authenticate, :except => [:index, :show]
+
+  def index
+    @articles = Article.all
+  end
+
+  def new
+    @article = Article.new
+  end
+end

data/test/dummy/app/helpers/application_helper.rb

@@ -0,0 +1,2 @@
+module ApplicationHelper
+end

data/test/dummy/app/helpers/articles_helper.rb

@@ -0,0 +1,2 @@
+module ArticlesHelper
+end

data/test/dummy/app/models/article.rb

@@ -0,0 +1,2 @@
+class Article < ActiveRecord::Base
+end

data/test/dummy/app/models/user.rb

@@ -0,0 +1,3 @@
+class User < ActiveRecord::Base
+  authenticates
+end

data/test/dummy/app/views/articles/index.html.erb

@@ -0,0 +1 @@
+<h1>Articles</h1>

data/test/dummy/app/views/articles/new.html.erb

@@ -0,0 +1 @@
+<h1>New Article</h1>

data/test/dummy/app/views/layouts/application.html.erb

@@ -0,0 +1,27 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Dummy</title>
+  <%= stylesheet_link_tag :all %>
+  <%= javascript_include_tag :defaults %>
+  <%= csrf_meta_tag %>
+</head>
+<body>
+
+  <div id='topnav'>
+    <% if current_user %>
+      You are signed in as <%= current_user.name %>.
+      <%= link_to 'Sign out', sign_out_path %>
+    <% else %>
+      <%= link_to 'Sign in', sign_in_path %>
+    <% end %>
+  </div>
+
+  <% flash.each do |key, value| %>
+    <div class='flash <%= key %>'><%= value %></div>
+  <% end %>
+
+<%= yield %>
+
+</body>
+</html>

data/test/dummy/app/views/sessions/new.html.erb

@@ -0,0 +1,15 @@
+<h1>Sign in</h1>
+
+<%= form_tag sign_in_path do %>
+  <p>
+    <%= label_tag :username %>
+    <%= text_field_tag :username %>
+  </p>
+  <p>
+    <%= label_tag :password %>
+    <%= password_field_tag :password %>
+  </p>
+  <p>
+    <%= submit_tag 'Sign in' %>
+  </p>
+<% end %>

data/test/dummy/config/application.rb

@@ -0,0 +1,21 @@
+require File.expand_path('../boot', __FILE__)
+
+require "active_model/railtie"
+require "active_record/railtie"
+require "action_controller/railtie"
+require "action_view/railtie"
+require "action_mailer/railtie"
+
+Bundler.require
+require 'quo_vadis'
+
+module Dummy
+  class Application < Rails::Application
+    # Configure the default encoding used in templates for Ruby 1.9.
+    config.encoding = "utf-8"
+
+    # Configure sensitive parameters which will be filtered from the log file.
+    config.filter_parameters += [:password]
+  end
+end
+

data/test/dummy/config/boot.rb

@@ -0,0 +1,10 @@
+require 'rubygems'
+gemfile = File.expand_path('../../../../Gemfile', __FILE__)
+
+if File.exist?(gemfile)
+  ENV['BUNDLE_GEMFILE'] = gemfile
+  require 'bundler'
+  Bundler.setup
+end
+
+$:.unshift File.expand_path('../../../../lib', __FILE__)