nagybence-clearance 0.4.1

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2008 thoughtbot, inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.textile

@@ -0,0 +1,205 @@
+h1. Clearance
+
+Rails authentication for developers who write tests.
+
+"We have clearance, Clarence.":http://www.youtube.com/v/mNRXJEE3Nz8
+
+h2. Integration with Suspenders
+
+Clearance is based on the same conventions and tools as "Suspenders":http://github.com/thoughtbot/suspenders Thus if you use it, you may already have some configuration mentioned below in place.
+
+h2. Gem installation (Rails 2.1+)
+
+In config/environment.rb:
+
+    config.gem 'mocha'
+    config.gem 'thoughtbot-shoulda',
+      :lib     => 'shoulda',
+      :source  => "http://gems.github.com", 
+      :version => '>= 2.0.6'
+    config.gem 'thoughtbot-factory_girl',
+      :lib     => 'factory_girl',
+      :source  => "http://gems.github.com", 
+      :version => '>= 1.1.5'
+    config.gem "thoughtbot-clearance", 
+      :lib     => 'clearance', 
+      :source  => 'http://gems.github.com', 
+      :version => '>= 0.3.9'
+
+Then:
+
+    rake gems:install
+    rake gems:unpack
+
+h2. The generator
+
+Make sure the development database exists and run the generator:
+
+    script/generate clearance
+
+A number of files will be created and instructions will be printed.
+
+You may already have some of these files. Don't worry. You'll be asked if you want to overwrite them.
+
+h2. Modules
+
+Clearance works by mixing behavior into tests, controllers, and models. For any file that you do not want to overwrite, include the corresponding Clearance module. They are namespaced exactly like the directory structure of a Rails app.
+
+Application controller example:
+
+    class ApplicationController < ActionController::Base
+      include Clearance::App::Controllers::ApplicationController
+    end
+
+User model example:
+
+    class User < ActiveRecord::Base
+      include Clearance::App::Models::User
+    end
+
+User test example:
+
+    class UserTest < Test::Unit::TestCase
+      include Clearance::Test::Unit::UserTest
+    end
+
+h2. The migration    
+    
+The generator will also create a migration to add a "users" table and run it. If the table already exists in the database, the migration will just add fields and indexes that are missing and required by Clearance. If the migration fails, the generator will revert all changes back.
+
+h2. Routes
+
+Clearance will add these routes to your routes.rb:
+
+    map.resources :users, :has_one => [:password, :confirmation]
+    map.resource  :session
+    map.resources :passwords
+    
+Please note that Clearance depends on root_url, so please make sure that it is defined to *something* in your config/routes.rb:
+
+    map.root :controller => 'home'
+    
+h2. Environments
+
+You need to define HOST constant in your environments files. In config/environments/test.rb and config/environments/development.rb it can be:
+
+    HOST = "localhost"
+
+While in config/environments/production.rb it must be the actual host your application is deployed to because the constant is used by mailers to generate URLs in emails.
+
+In config/environment.rb:
+
+    DO_NOT_REPLY = "donotreply@example.com"
+
+h2. Tests
+
+The tests use "Shoulda":http://thoughtbot.com/projects/shoulda >= 2.0.6 and "Factory Girl":http://thoughtbot.com/projects/factory_girl >= 1.1.5. There needs to be a Clearance module in your test/test_helper.rb:
+
+    class Test::Unit::TestCase
+      self.use_transactional_fixtures = true
+      self.use_instantiated_fixtures  = false
+      include Clearance::Test::TestHelper
+    end
+
+The generator will create a user factory in test/factories/clearance.rb unless
+you have it defined somewhere else.
+
+h2. Usage: basic workflow
+
+Rails authentication with Clearance uses the standard approach thoughtbot and our clients have agreed upon. 
+
+Users register (UsersController) using an email address and a password (User model). They get an email (ClearanceMailer) with a confirmation link to confirm their registration (ConfirmationController).
+
+Registered users can sign in and out (SessionsController). If they forget their password, they request an email (ClearanceMailer) containing a link to change it (PasswordsController). 
+
+h2. Usage: actions which require an authenticated user
+
+To protect your controllers with authentication add:
+
+    class ProtectedController < ApplicationController
+      before_filter :authenticate
+
+The filter will ensure that only authenticated users can access the controller. If someone who's not signed in tries to access a protected action: 
+
+* the URL is stored in the session, 
+* the user is redirected to sign in page, and
+* after successful authentication will be be redirected back to that URL.
+
+h2. Usage: signed_in?, current_user
+
+Clearance provides two methods that can be used in controllers, helpers, and views to check if current user is authenticated and get the actual user: 
+
+* signed_in?
+* current_user
+   
+    <% if signed_in? -%>
+      Hello, <%= current_user.name %>!
+    <% else -%>
+      Please <%= link_to 'Sign in', new_session_path %>
+    <% end -%>
+    
+h2. Usage: mass assignment
+
+Please note that all User attributes except email, password and password_confirmation are protected from mass assignment by default. Use attr_accessible to enable it for your custom attributes.
+    
+    class User < ActiveRecord::Base
+      include Clearance::App::Models::User
+      attr_accessible :first_name, :last_name
+    end
+
+h2. Hooks: return_to parameter
+
+To specify where to redirect a user (say you want to have a sign in form on every page and redirect the user to the same page) after he/she signs in, you can add a "return_to" parameter to the request (thanks to "Phillippe":http://www.sivarg.com/2009/01/clearance-coming-from-where-your-were.html for the tip):
+
+    <% form_for :session, :url => session_path(:return_to => request.request_uri) do |form| %>
+
+h2. Hooks: url_after_create, url_after_update, url_after_destroy
+    
+Actions that redirect (create, update, and destroy) in Clearance controllers are customizable. If you want to redirect a user to a specific route after signing in, overwrite the "url_after_create" method in the SessionsController:
+
+    class SessionsController < ApplicationController
+      include Clearance::App::Controllers::SessionsController
+      
+      private
+      
+        def url_after_create
+          new_blog_post_path
+        end
+    end
+
+There are similar methods in other controllers as well:
+
+    UsersController#url_after_create (register)
+    SessionsController#url_after_create (sign in)
+    SessionsController#url_after_destroy (sign out)
+    PasswordsController#url_after_create (password request)
+    PasswordsController#url_after_update (password)
+    ConfirmationsController#url_after_create (confirmation)
+
+h2. Hooks: sign_user_in
+
+Say you want to add a last_signed_in_at attribute to your User model. You would want to update it when the User signs in.
+
+Clearance has a method named sign_user_in that you can overwrite with that logic. Be sure to call sign_in(user) at the end (and write tests!).
+
+    class ApplicationController < ActionController::Base
+      include Clearance::App::Controllers::ApplicationController
+      
+      private
+        
+        def sign_user_in(user)
+          # store current time to display "last signed in at" message
+          user.update_attribute(:last_signed_in_at, Time.now)
+          sign_in(user)
+        end
+    end 
+
+h2. Authors
+
+* thoughtbot, inc.
+* Dan Croak
+* Mike Burns
+* Jason Morrison
+* Eugene Bolshakov
+* Josh Nichols
+* Mike Breen

data/Rakefile

@@ -0,0 +1,53 @@
+require 'rake'
+require 'rake/testtask'
+ 
+test_files_pattern = 'test/rails_root/test/{unit,functional,other}/**/*_test.rb'
+namespace :test do
+  Rake::TestTask.new(:all => ['generator:cleanup', 'generator:generate']) do |task|
+    task.libs << 'lib'
+    task.pattern = test_files_pattern
+    task.verbose = false
+  end
+end
+
+namespace :generator do
+  desc "Cleans up the test app before running the generator"
+  task :cleanup do
+    FileList["generators/clearance/templates/**/*.*"].each do |each|
+      file = "test/rails_root/#{each.gsub("generators/clearance/templates/",'')}"
+      File.delete(file) if File.exists?(file)
+    end
+    
+    FileUtils.rm_rf("test/rails_root/db/migrate")
+    FileUtils.rm_rf("test/rails_root/vendor/plugins/clearance")
+    system "mkdir -p test/rails_root/vendor/plugins/clearance"
+    system "cp -R generators test/rails_root/vendor/plugins/clearance"  
+  end
+
+  desc "Run the generator on the tests"
+  task :generate do
+    system "cd test/rails_root && ./script/generate clearance"
+  end
+end
+
+desc "Run the test suite"
+task :default => 'test:all'
+
+gem_spec = Gem::Specification.new do |gem_spec|
+  gem_spec.name        = "clearance"
+  gem_spec.version     = "0.4.1"
+  gem_spec.summary     = "Rails authentication for developers who write tests."
+  gem_spec.email       = "support@thoughtbot.com"
+  gem_spec.homepage    = "http://github.com/thoughtbot/clearance"
+  gem_spec.description = "Simple, complete Rails authentication scheme."
+  gem_spec.authors     = ["thoughtbot, inc.", "Dan Croak", "Mike Burns", "Jason Morrison",
+                          "Eugene Bolshakov", "Josh Nichols", "Mike Breen"]
+  gem_spec.files       = FileList["[A-Z]*", "{generators,lib,shoulda_macros,rails}/**/*"]
+end
+
+desc "Generate a gemspec file"
+task :gemspec do
+  File.open("#{gem_spec.name}.gemspec", 'w') do |f|
+    f.write gem_spec.to_yaml
+  end
+end

data/TODO.textile

@@ -0,0 +1,8 @@
+(highest priority first)
+
+# refactor password controller test
+# existing_user? methods ... if salt is wrong, user may not be found b/c of invalid credentials. is :not_found the correct code to return in that use case? if not, method probably needs to be split into another conditional.
+# document shoulda macros
+# will SHA512 hashes fit in all the places they are being used? (db columns - fit now, sessions) 128 characters
+
+http://adam.speaksoutofturn.com/post/57615195/entication-vs-orization

data/generators/clearance/USAGE

@@ -0,0 +1 @@
+script/generate clearance

data/generators/clearance/clearance_generator.rb

@@ -0,0 +1,92 @@
+require File.expand_path(File.dirname(__FILE__) + "/lib/insert_commands.rb")
+require File.expand_path(File.dirname(__FILE__) + "/lib/rake_commands.rb")
+require 'factory_girl'
+
+class ClearanceGenerator < Rails::Generator::Base
+  
+  def manifest
+    record do |m|
+      m.directory File.join("app", "controllers")
+      file = "app/controllers/application.rb"
+      if File.exists?(file)
+        m.insert_into file, "include Clearance::App::Controllers::ApplicationController"
+      else
+        m.file file, file 
+      end
+     
+      ["app/controllers/confirmations_controller.rb",
+       "app/controllers/passwords_controller.rb", 
+       "app/controllers/sessions_controller.rb", 
+       "app/controllers/users_controller.rb"].each do |file|
+        m.file file, file
+      end
+      
+      m.directory File.join("app", "models")
+      ["app/models/user.rb", "app/models/clearance_mailer.rb"].each do |file|
+        m.file file, file
+      end
+      
+      m.directory File.join("app", "views")
+      
+      m.directory File.join("app", "views", "passwords")
+      ["app/views/passwords/new.html.erb",
+       "app/views/passwords/edit.html.erb"].each do |file|
+        m.file file, file
+      end
+      
+      m.directory File.join("app", "views", "sessions")
+      ["app/views/sessions/new.html.erb"].each do |file|
+        m.file file, file
+      end
+      
+      m.directory File.join("app", "views", "clearance_mailer")
+      ["app/views/clearance_mailer/change_password.html.erb",
+       "app/views/clearance_mailer/confirmation.html.erb"].each do |file|
+        m.file file, file
+      end
+      
+      m.directory File.join("app", "views", "users")
+      ["app/views/users/_form.html.erb",
+       "app/views/users/edit.html.erb",
+       "app/views/users/new.html.erb"].each do |file|
+        m.file file, file
+      end
+      
+      m.directory File.join("test", "functional")
+      ["test/functional/confirmations_controller_test.rb",
+       "test/functional/passwords_controller_test.rb",
+       "test/functional/sessions_controller_test.rb",
+       "test/functional/users_controller_test.rb"].each do |file|
+        m.file file, file
+      end
+      
+      m.directory File.join("test", "unit")
+      ["test/unit/clearance_mailer_test.rb",
+       "test/unit/user_test.rb"].each do |file|
+        m.file file, file
+      end
+      
+      m.directory File.join("test", "factories")
+      ["test/factories/clearance.rb"].each do |file|
+        m.file file, file
+      end
+      
+      m.route_resources ':passwords'      
+      m.route_resource  ':session'      
+      m.route_resources ':users, :has_one => [:password, :confirmation]'      
+      
+      if ActiveRecord::Base.connection.table_exists?(:users)      
+        m.migration_template 'db/migrate/update_users_with_clearance_columns.rb', 
+          'db/migrate', :migration_file_name => 'create_or_update_users_with_clearance_columns'
+      else
+        m.migration_template 'db/migrate/create_users_with_clearance_columns.rb', 
+          'db/migrate', :migration_file_name => 'create_or_update_users_with_clearance_columns'
+      end
+            
+      m.rake_db_migrate
+      
+      m.readme "README"
+    end
+  end
+  
+end

data/generators/clearance/lib/insert_commands.rb

@@ -0,0 +1,103 @@
+# Mostly pinched from http://github.com/ryanb/nifty-generators/tree/master
+
+Rails::Generator::Commands::Base.class_eval do
+  def file_contains?(relative_destination, line)
+    File.read(destination_path(relative_destination)).include?(line)
+  end
+end
+
+Rails::Generator::Commands::Create.class_eval do
+
+  def route_resources(resource_list)
+    sentinel = 'ActionController::Routing::Routes.draw do |map|'
+    
+    logger.route "map.resources #{resource_list}"
+    unless options[:pretend] || file_contains?('config/routes.rb', resource_list)
+      gsub_file 'config/routes.rb', /(#{Regexp.escape(sentinel)})/mi do |match|
+        "#{match}\n  map.resources #{resource_list}"
+      end
+    end
+  end
+
+  def route_resource(resource_list)
+    sentinel = 'ActionController::Routing::Routes.draw do |map|'
+    
+    logger.route "map.resource #{resource_list}"
+    unless options[:pretend] || file_contains?('config/routes.rb', resource_list)
+      gsub_file 'config/routes.rb', /(#{Regexp.escape(sentinel)})/mi do |match|
+        "#{match}\n  map.resource #{resource_list}"
+      end
+    end
+  end
+  
+  def route_name(name, path, route_options = {})
+    sentinel = 'ActionController::Routing::Routes.draw do |map|'
+    
+    logger.route "map.#{name} '#{path}', :controller => '#{route_options[:controller]}', :action => '#{route_options[:action]}'"
+    unless options[:pretend] 
+      gsub_file_once 'config/routes.rb', /(#{Regexp.escape(sentinel)})/mi do |match|
+        "#{match}\n  map.#{name} '#{path}', :controller => '#{route_options[:controller]}', :action => '#{route_options[:action]}'"
+      end
+    end
+  end
+  
+  def insert_into(file, line)
+    logger.insert "#{line} into #{file}"
+    unless options[:pretend] || file_contains?(file, line)
+      gsub_file file, /^(class|module) .+$/ do |match|
+        "#{match}\n  #{line}"
+      end
+    end
+  end
+end
+
+Rails::Generator::Commands::Destroy.class_eval do
+  def route_resource(resource_list)
+    look_for = "  map.resource #{resource_list}\n".gsub(/[\[\]]/, '\\\\\0')
+    logger.route "map.resource #{resource_list} #{look_for}"
+    unless options[:pretend]
+      gsub_file 'config/routes.rb', /(#{look_for})/mi, ''
+    end
+  end
+  
+  def route_resources(resource_list)
+    look_for = "  map.resources #{resource_list}\n".gsub(/[\[\]]/, '\\\\\0')
+    logger.route "map.resources #{resource_list} #{look_for}"
+    unless options[:pretend]
+      gsub_file 'config/routes.rb', /(#{look_for})/mi, ''
+    end
+  end  
+  
+  def route_name(name, path, route_options = {})
+    look_for =   "\n  map.#{name} '#{path}', :controller => '#{route_options[:controller]}', :action => '#{route_options[:action]}'"
+    logger.route "map.#{name} '#{path}',     :controller => '#{route_options[:controller]}', :action => '#{route_options[:action]}'"
+    unless options[:pretend]
+      gsub_file    'config/routes.rb', /(#{look_for})/mi, ''
+    end
+  end
+  
+  def insert_into(file, line)
+    logger.remove "#{line} from #{file}"
+    unless options[:pretend]
+      gsub_file file, "\n  #{line}", ''
+    end
+  end
+end
+
+Rails::Generator::Commands::List.class_eval do
+  def route_resource(resources_list)
+    logger.route "map.resource #{resource_list}"
+  end
+  
+  def route_resources(resources_list)
+    logger.route "map.resource #{resource_list}"
+  end  
+  
+  def route_name(name, path, options = {})
+    logger.route "map.#{name} '#{path}', :controller => '{options[:controller]}', :action => '#{options[:action]}'"
+  end
+  
+  def insert_into(file, line)
+    logger.insert "#{line} into #{file}"
+  end
+end

data/generators/clearance/lib/rake_commands.rb

@@ -0,0 +1,22 @@
+Rails::Generator::Commands::Create.class_eval do
+  def rake_db_migrate
+    logger.rake "db:migrate"
+    unless system("rake db:migrate")
+      logger.rake "db:migrate failed. Rolling back"      
+      command(:destroy).invoke!
+    end
+  end
+end
+
+Rails::Generator::Commands::Destroy.class_eval do
+  def rake_db_migrate
+    logger.rake "db:rollback"  
+    system "rake db:rollback"  
+  end
+end
+
+Rails::Generator::Commands::List.class_eval do
+  def rake_db_migrate
+    logger.rake "db:migrate"    
+  end
+end

data/generators/clearance/templates/README

@@ -0,0 +1,54 @@
+
+*******************************************************************************
+
+Ok, enough fancy automatic stuff. Time for some old school monkey copy-pasting.
+
+1. For any other file(s) that you already had and didn't want to overwrite, add 
+the corresponding Clearance module. They are namespaced exactly like the 
+directory structure of a Rails app.
+
+Application controller example:
+
+    class ApplicationController < ActionController::Base
+      include Clearance::App::Controllers::ApplicationController
+    end
+
+User model example:
+
+    class User < ActiveRecord::Base
+      include Clearance::App::Models::User
+    end
+
+User test example:
+
+    class UserTest < Test::Unit::TestCase
+      include Clearance::Test::Unit::UserTest
+    end
+
+2. You need to define HOST constant in your environments files. 
+In config/environments/test.rb and config/environments/development.rb it can be:
+
+    HOST = "localhost"
+
+In production.rb it must be the actual host your application is deployed to. 
+The constant is used by mailers to generate URLs in emails.
+
+In config/environment.rb:
+
+    DO_NOT_REPLY = "donotreply@example.com"
+    
+3. Clearance depends on root_url, so please make sure that it is defined to
+*something* your config/routes.rb:
+
+    map.root :controller => 'home'
+    
+4. To run tests you need to add the Clearance module to your 
+test/test_helper.rb:
+
+    class Test::Unit::TestCase
+      self.use_transactional_fixtures = true
+      self.use_instantiated_fixtures  = false
+      include Clearance::Test::TestHelper
+    end
+
+*******************************************************************************    

data/generators/clearance/templates/app/controllers/application.rb

@@ -0,0 +1,5 @@
+class ApplicationController < ActionController::Base
+  helper :all
+  protect_from_forgery
+  include Clearance::App::Controllers::ApplicationController
+end

data/generators/clearance/templates/app/controllers/confirmations_controller.rb

@@ -0,0 +1,3 @@
+class ConfirmationsController < ApplicationController
+  include Clearance::App::Controllers::ConfirmationsController
+end

data/generators/clearance/templates/app/controllers/passwords_controller.rb

@@ -0,0 +1,3 @@
+class PasswordsController < ApplicationController
+  include Clearance::App::Controllers::PasswordsController
+end

data/generators/clearance/templates/app/controllers/sessions_controller.rb

@@ -0,0 +1,3 @@
+class SessionsController < ApplicationController
+  include Clearance::App::Controllers::SessionsController
+end

data/generators/clearance/templates/app/controllers/users_controller.rb

@@ -0,0 +1,3 @@
+class UsersController < ApplicationController
+  include Clearance::App::Controllers::UsersController
+end

data/generators/clearance/templates/app/models/clearance_mailer.rb

@@ -0,0 +1,5 @@
+class ClearanceMailer < ActionMailer::Base
+  default_url_options[:host] = HOST
+  
+  include Clearance::App::Models::ClearanceMailer
+end

data/generators/clearance/templates/app/models/user.rb

@@ -0,0 +1,3 @@
+class User < ActiveRecord::Base
+  include Clearance::App::Models::User
+end

data/generators/clearance/templates/app/views/clearance_mailer/change_password.html.erb

@@ -0,0 +1,10 @@
+Someone, hopefully you, has requested that we send you a link to change your password.
+
+Here's the link:
+
+<%= edit_user_password_url(@user, 
+      :email    => @user.email, 
+      :password => @user.encrypted_password,
+      :escape   => false) %>
+
+If you didn't request this, don't worry: your password hasn't been changed. You can just ignore this email.

data/generators/clearance/templates/app/views/clearance_mailer/confirmation.html.erb

@@ -0,0 +1 @@
+<%= new_user_confirmation_url :user_id => @user, :salt => @user.salt %>

data/generators/clearance/templates/app/views/passwords/edit.html.erb

@@ -0,0 +1,25 @@
+<h2>Change your password</h2>
+
+<p>
+  Your password has been reset. Choose a new password below.
+</p>
+
+<%= error_messages_for :user %>
+
+<% form_for(:user,
+            :url => user_password_path(@user,
+                      :email    => @user.email,
+                      :password => @user.encrypted_password),
+            :html => { :method => :put }) do |form| %>
+  <div class="password_field">
+    <%= form.label :password, "Choose password" %>
+    <%= form.password_field :password %>
+  </div>
+  <div class="password_field">
+    <%= form.label :password_confirmation, "Verify password" %>
+    <%= form.password_field :password_confirmation %>
+  </div>
+  <div class="submit_field">
+    <%= form.submit "Save this password", :disable_with => "Please wait..." %>
+  </div>
+<% end %>

data/generators/clearance/templates/app/views/passwords/new.html.erb

@@ -0,0 +1,15 @@
+<h2>Change your password</h2>
+
+<p>
+  We will email you a link to change your password.
+</p>
+
+<% form_for :password, :url => passwords_path do |form| %>
+  <div class="text_field">
+    <%= form.label :email, "Email address" %>
+    <%= form.text_field :email %>
+  </div>
+  <div class="submit_field">
+    <%= form.submit "Reset password", :disable_with => "Please wait..." %>
+  </div>
+<% end %>