clearance 1.10.1 → 1.17.0

data/README.md

@@ -2,6 +2,8 @@
 
 [![Build Status](https://secure.travis-ci.org/thoughtbot/clearance.svg)](http://travis-ci.org/thoughtbot/clearance?branch=master)
 [![Code Climate](https://codeclimate.com/github/thoughtbot/clearance.svg)](https://codeclimate.com/github/thoughtbot/clearance)
+[![Documentation Quality](https://inch-ci.org/github/thoughtbot/clearance.svg?branch=master)](https://inch-ci.org/github/thoughtbot/clearance)
+[![Reviewed by Hound](https://img.shields.io/badge/Reviewed_by-Hound-8E64B0.svg)](https://houndci.com)
 
 Rails authentication with email & password.
 
@@ -15,22 +17,30 @@ monitored by contributors.
 [GitHub Issues]: https://github.com/thoughtbot/clearance/issues
 [Stack Overflow]: http://stackoverflow.com/questions/tagged/clearance
 
-## Install
+## Getting Started
 
 Clearance is a Rails engine tested against Rails `>= 3.2` and Ruby `>= 1.9.3`.
-To get started, add Clearance to your `Gemfile`, `bundle install`, and run the
-`install generator`:
+
+You can add it to your Gemfile with:
+
+```sh
+gem "clearance"
+```
+
+Run the bundle command to install it.
+
+After you install Clearance, you need to run the generator:
 
 ```sh
 $ rails generate clearance:install
 ```
 
-The generator:
+The Clearance install generator:
 
 * Inserts `Clearance::User` into your `User` model
 * Inserts `Clearance::Controller` into your `ApplicationController`
-* Creates an initializer to allow further configuration.
-* Creates a migration that either creates a users table or adds any necessary
+* Creates an initializer file to allow further configuration.
+* Creates a migration file that either create a users table or adds any necessary
   columns to the existing table.
 
 ## Configure
@@ -40,21 +50,26 @@ Override any of these defaults in `config/initializers/clearance.rb`:
 ```ruby
 Clearance.configure do |config|
   config.allow_sign_up = true
-  config.cookie_domain = '.example.com'
+  config.cookie_domain = ".example.com"
   config.cookie_expiration = lambda { |cookies| 1.year.from_now.utc }
-  config.cookie_name = 'remember_token'
-  config.cookie_path = '/'
+  config.cookie_name = "remember_token"
+  config.cookie_path = "/"
   config.routes = true
   config.httponly = false
-  config.mailer_sender = 'reply@example.com'
+  config.mailer_sender = "reply@example.com"
   config.password_strategy = Clearance::PasswordStrategies::BCrypt
-  config.redirect_url = '/'
+  config.redirect_url = "/"
+  config.rotate_csrf_on_sign_in = false
   config.secure_cookie = false
   config.sign_in_guards = []
   config.user_model = User
 end
 ```
 
+The install generator will set `rotate_csrf_on_sign_in` to `true`, so new
+installations will get this behavior from the start. This helps avoid session
+fixation attacks, and will become the default in Clearance 2.0.
+
 ## Use
 
 ### Access Control
@@ -77,15 +92,15 @@ at the routing layer:
 ```ruby
 Blog::Application.routes.draw do
   constraints Clearance::Constraints::SignedIn.new { |user| user.admin? } do
-    root to: 'admin/dashboards#show', as: :admin_root
+    root to: "admin/dashboards#show", as: :admin_root
   end
 
   constraints Clearance::Constraints::SignedIn.new do
-    root to: 'dashboards#show', as: :signed_in_root
+    root to: "dashboards#show", as: :signed_in_root
   end
 
   constraints Clearance::Constraints::SignedOut.new do
-    root to: 'marketing#index'
+    root to: "marketing#index"
   end
 end
 ```
@@ -111,7 +126,7 @@ should change the `mailer_sender` default, used in the email's "from" header:
 
 ```ruby
 Clearance.configure do |config|
-  config.mailer_sender = 'reply@example.com'
+  config.mailer_sender = "reply@example.com"
 end
 ```
 
@@ -143,10 +158,17 @@ end
 See [config/routes.rb](/config/routes.rb) for the default set of routes.
 
 As of Clearance 1.5 it is recommended that you disable Clearance routes and take
-full control over routing and URL design.
+full control over routing and URL design. This ensures that your app's URL design
+won't be affected if the gem's routes and URL design are changed.
 
-To disable the routes, set `config.routes = false`. You can optionally run
-`rails generate clearance:routes` to dump a copy of the default routes into your
+To disable the routes, change the `routes` configuration option to false: 
+
+```ruby
+Clearance.configure do |config|
+  config.routes = false
+end
+```
+You can optionally run `rails generate clearance:routes` to dump a copy of the default routes into your
 application for modification.
 
 ### Controllers
@@ -165,7 +187,9 @@ class UsersController < Clearance::UsersController
 ```
 
 ### Redirects
-All of these controller methods redirect to `'/'` by default:
+
+All of these controller methods redirect to
+`Clearance.configuration.redirect_url` (which is `/` by default):
 
 ```
 passwords#url_after_update
@@ -173,10 +197,13 @@ sessions#url_after_create
 sessions#url_for_signed_in_users
 users#url_after_create
 application#url_after_denied_access_when_signed_in
-application#url_after_denied_access_when_signed_out
 ```
 
 To override them all at once, change the global configuration of `redirect_url`.
+To change individual URLs, override the appropriate method.
+
+`application#url_after_denied_access_when_signed_out` defaults to `sign_in_url`.
+Override this method to change this.
 
 ### Views
 
@@ -206,23 +233,26 @@ $ rails generate clearance:views
 
 By default, Clearance uses your application's default layout. If you would like
 to change the layout that Clearance uses when rendering its views, simply
-specify the layout in an initializer.
+specify the layout in the `config/application.rb`
 
 ```ruby
-Clearance::PasswordsController.layout 'my_passwords_layout'
-Clearance::SessionsController.layout 'my_sessions_layout'
-Clearance::UsersController.layout 'my_admin_layout'
+config.to_prepare do
+  Clearance::PasswordsController.layout "my_passwords_layout"
+  Clearance::SessionsController.layout "my_sessions_layout"
+  Clearance::UsersController.layout "my_admin_layout"
+end
 ```
 
 ### Translations
 
-All flash messages and email subject lines are stored in [i18n translations]
-(http://guides.rubyonrails.org/i18n.html). Override them like any other
+All flash messages and email subject lines are stored in [i18n translations](http://guides.rubyonrails.org/i18n.html). Override them like any other
 translation.
 
 See [config/locales/clearance.en.yml](/config/locales/clearance.en.yml) for the
 default behavior.
 
+You can also install [clearance-i18n](https://github.com/thoughtbot/clearance-i18n)
+for access to additional, user-contributed translations.
 
 ### User Model
 
@@ -324,11 +354,25 @@ Usage:
 visit root_path(as: user)
 ```
 
+Additionally, if `User#to_param` is overridden, you can pass a block in
+order to override the default behavior:
+
+```ruby
+# config/environments/test.rb
+MyRailsApp::Application.configure do
+  # ...
+  config.middleware.use Clearance::BackDoor do |username|
+    Clearance.configuration.user_model.find_by(username: username)
+  end
+  # ...
+end
+```
+
 ### Ready Made Feature Specs
 
 If you're using RSpec, you can generate feature specs to help prevent
 regressions in Clearance's integration with your Rails app over time. These
-feature specs, will also require `factory_girl_rails`.
+feature specs, will also require `factory_bot_rails`.
 
 To Generate the clearance specs, run:
 
@@ -338,22 +382,26 @@ $ rails generate clearance:specs
 
 ### Controller Test Helpers
 
-To test controller actions that are protected by `before_filter :require_login`,
+To test controller actions that are protected by `before_action :require_login`,
 require Clearance's test helpers in your test suite.
 
 For `rspec`, add the following line to your `spec/rails_helper.rb` or
 `spec/spec_helper` if `rails_helper` does not exist:
 
 ```ruby
-require 'clearance/rspec'
+require "clearance/rspec"
 ```
 
 For `test-unit`, add this line to your `test/test_helper.rb`:
 
 ```ruby
-require 'clearance/test_unit'
+require "clearance/test_unit"
 ```
 
+**Note for Rails 5:** the default generated controller tests are now
+integration tests. You will need to use the
+[backdoor middleware](#fast-feature-specs) instead.
+
 This will make `Clearance::Controller` methods work in your controllers
 during functional tests and provide access to helper methods like:
 
@@ -363,6 +411,23 @@ sign_in_as(user)
 sign_out
 ```
 
+### View and Helper Spec Helpers
+
+Does the view or helper you're testing reference `signed_in?`, `signed_out?` or
+`current_user`? If you `require 'clearance/rspec'`, you will have the following
+helpers available in your view specs:
+
+```ruby
+sign_in
+sign_in_as(user)
+```
+
+These will make the clearance view helpers work as expected by signing in either
+a new instance of your user model (`sign_in`) or the object you pass to
+`sign_in_as`. If you do not call one of these sign in helpers or otherwise set
+`current_user` in your view specs, your view will behave as if there is no
+current user: `signed_in?` will be false and `signed_out?` will be true.
+
 ## Contributing
 
 Please see [CONTRIBUTING.md].
@@ -371,31 +436,23 @@ Thank you, [contributors]!
 [CONTRIBUTING.md]: /CONTRIBUTING.md
 [contributors]: https://github.com/thoughtbot/clearance/graphs/contributors
 
-## Need Help?
-
-We offer 1-on-1 coaching. We can help you set up Clearance, write authentication
-and authorization extensions for your application, and work out a permission and
-role model which works for you. [Get in touch][coaching].
-
 ## License
 
-Clearance is copyright © 2009 thoughtbot. It is free software, and may be
+Clearance is copyright © 2009-2019 thoughtbot. It is free software, and may be
 redistributed under the terms specified in the [`LICENSE`] file.
 
 [`LICENSE`]: /LICENSE
 
 ## About thoughtbot
 
-![thoughtbot](https://thoughtbot.com/logo.png)
+![thoughtbot](http://presskit.thoughtbot.com/images/thoughtbot-logo-for-readmes.svg)
 
 Clearance is maintained and funded by thoughtbot, inc.
 The names and logos for thoughtbot are trademarks of thoughtbot, inc.
 
 We love open source software!
-See [our other projects][community],
-[hire us][hire] to design, develop, and grow your product,
-or get in touch about [1-on-1 coaching][coaching].
+See [our other projects][community] or
+[hire us][hire] to design, develop, and grow your product.
 
 [community]: https://thoughtbot.com/community?utm_source=github
 [hire]: https://thoughtbot.com/hire-us?utm_source=github
-[coaching]: http://coaching.thoughtbot.com/rails/?utm_source=github

data/app/controllers/clearance/passwords_controller.rb

@@ -1,10 +1,23 @@
 require 'active_support/deprecation'
 
 class Clearance::PasswordsController < Clearance::BaseController
-  skip_before_filter :require_login, only: [:create, :edit, :new, :update]
-  skip_before_filter :authorize, only: [:create, :edit, :new, :update]
-  before_filter :forbid_missing_token, only: [:edit, :update]
-  before_filter :forbid_non_existent_user, only: [:edit, :update]
+  if respond_to?(:before_action)
+    skip_before_action :require_login,
+      only: [:create, :edit, :new, :update],
+      raise: false
+    skip_before_action :authorize,
+      only: [:create, :edit, :new, :update],
+      raise: false
+    before_action :ensure_existing_user, only: [:edit, :update]
+  else
+    skip_before_filter :require_login,
+      only: [:create, :edit, :new, :update],
+      raise: false
+    skip_before_filter :authorize,
+      only: [:create, :edit, :new, :update],
+      raise: false
+    before_filter :ensure_existing_user, only: [:edit, :update]
+  end
 
   def create
     if user = find_user_for_create
@@ -16,7 +29,13 @@ class Clearance::PasswordsController < Clearance::BaseController
 
   def edit
     @user = find_user_for_edit
-    render template: 'passwords/edit'
+
+    if params[:token]
+      session[:password_reset_token] = params[:token]
+      redirect_to url_for
+    else
+      render template: 'passwords/edit'
+    end
   end
 
   def new
@@ -29,6 +48,7 @@ class Clearance::PasswordsController < Clearance::BaseController
     if @user.update_password password_reset_params
       sign_in @user
       redirect_to url_after_update
+      session[:password_reset_token] = nil
     else
       flash_failure_after_update
       render template: 'passwords/edit'
@@ -40,7 +60,7 @@ class Clearance::PasswordsController < Clearance::BaseController
   def deliver_email(user)
     mail = ::ClearanceMailer.change_password(user)
 
-    if Gem::Version.new(Rails::VERSION::STRING) >= Gem::Version.new("4.2.0")
+    if mail.respond_to?(:deliver_later)
       mail.deliver_later
     else
       mail.deliver
@@ -58,9 +78,10 @@ class Clearance::PasswordsController < Clearance::BaseController
 
   def find_user_by_id_and_confirmation_token
     user_param = Clearance.configuration.user_id_parameter
+    token = params[:token] || session[:password_reset_token]
 
     Clearance.configuration.user_model.
-      find_by_id_and_confirmation_token params[user_param], params[:token].to_s
+      find_by_id_and_confirmation_token params[user_param], token.to_s
   end
 
   def find_user_for_create
@@ -76,6 +97,13 @@ class Clearance::PasswordsController < Clearance::BaseController
     find_user_by_id_and_confirmation_token
   end
 
+  def ensure_existing_user
+    unless find_user_by_id_and_confirmation_token
+      flash_failure_when_forbidden
+      render template: "passwords/new"
+    end
+  end
+
   def flash_failure_when_forbidden
     flash.now[:notice] = translate(:forbidden,
       scope: [:clearance, :controllers, :passwords],
@@ -88,20 +116,6 @@ class Clearance::PasswordsController < Clearance::BaseController
       default: t('flashes.failure_after_update'))
   end
 
-  def forbid_missing_token
-    if params[:token].to_s.blank?
-      flash_failure_when_forbidden
-      render template: 'passwords/new'
-    end
-  end
-
-  def forbid_non_existent_user
-    unless find_user_by_id_and_confirmation_token
-      flash_failure_when_forbidden
-      render template: 'passwords/new'
-    end
-  end
-
   def url_after_create
     sign_in_url
   end

data/app/controllers/clearance/sessions_controller.rb

@@ -1,7 +1,21 @@
 class Clearance::SessionsController < Clearance::BaseController
-  before_filter :redirect_signed_in_users, only: [:new]
-  skip_before_filter :require_login, only: [:create, :new, :destroy]
-  skip_before_filter :authorize, only: [:create, :new, :destroy]
+  if respond_to?(:before_action)
+    before_action :redirect_signed_in_users, only: [:new]
+    skip_before_action :require_login,
+      only: [:create, :new, :destroy],
+      raise: false
+    skip_before_action :authorize,
+      only: [:create, :new, :destroy],
+      raise: false
+  else
+    before_filter :redirect_signed_in_users, only: [:new]
+    skip_before_filter :require_login,
+      only: [:create, :new, :destroy],
+      raise: false
+    skip_before_filter :authorize,
+      only: [:create, :new, :destroy],
+      raise: false
+  end
 
   def create
     @user = authenticate(params)

data/app/controllers/clearance/users_controller.rb

@@ -1,7 +1,13 @@
 class Clearance::UsersController < Clearance::BaseController
-  before_filter :redirect_signed_in_users, only: [:create, :new]
-  skip_before_filter :require_login, only: [:create, :new]
-  skip_before_filter :authorize, only: [:create, :new]
+  if respond_to?(:before_action)
+    before_action :redirect_signed_in_users, only: [:create, :new]
+    skip_before_action :require_login, only: [:create, :new], raise: false
+    skip_before_action :authorize, only: [:create, :new], raise: false
+  else
+    before_filter :redirect_signed_in_users, only: [:create, :new]
+    skip_before_filter :require_login, only: [:create, :new], raise: false
+    skip_before_filter :authorize, only: [:create, :new], raise: false
+  end
 
   def new
     @user = user_from_params
@@ -50,6 +56,6 @@ class Clearance::UsersController < Clearance::BaseController
   end
 
   def user_params
-    params[:user] || Hash.new
+    params[Clearance.configuration.user_parameter] || Hash.new
   end
 end

data/app/mailers/clearance_mailer.rb

@@ -6,9 +6,8 @@ class ClearanceMailer < ActionMailer::Base
       to: @user.email,
       subject: I18n.t(
         :change_password,
-        scope: [:clearance, :models, :clearance_mailer],
-        default: "Change your password"
-      )
+        scope: [:clearance, :models, :clearance_mailer]
+      ),
     )
   end
 end

data/app/views/clearance_mailer/change_password.text.erb

@@ -1,4 +1,4 @@
-<%= t(".opening") %></p>
+<%= t(".opening") %>
 
 <%= edit_user_password_url(@user, token: @user.confirmation_token.html_safe) %>
 

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

@@ -1,7 +1,6 @@
 <!DOCTYPE html>
 <html>
 <head>
-  <%= javascript_include_tag 'application' %>
   <%= csrf_meta_tag %>
 </head>
 <body>

data/bin/setup

@@ -4,8 +4,12 @@ set -e
 
 # Install required gems, including Appraisal, which helps us test against
 # multiple Rails versions
-bundle install
-bundle exec appraisal install
+gem install bundler --conservative
+bundle check || bundle install
+
+if [ -z "$CI" ]; then
+  bundle exec appraisal install
+fi
 
 # Set up database for the application that Clearance tests against
 RAILS_ENV=test bundle exec rake dummy:db:reset

data/clearance.gemspec

@@ -5,7 +5,10 @@ require 'date'
 Gem::Specification.new do |s|
   s.add_dependency 'bcrypt'
   s.add_dependency 'email_validator', '~> 1.4'
-  s.add_dependency 'rails', '>= 3.1'
+  s.add_dependency 'railties', '>= 3.1'
+  s.add_dependency 'activemodel', '>= 3.1'
+  s.add_dependency 'activerecord', '>= 3.1'
+  s.add_dependency 'actionmailer', '>= 3.1'
   s.authors = [
     'Dan Croak',
     'Eugene Bolshakov',
@@ -30,7 +33,7 @@ Gem::Specification.new do |s|
   s.email = 'support@thoughtbot.com'
   s.extra_rdoc_files = %w(LICENSE README.md)
   s.files = `git ls-files`.split("\n")
-  s.homepage = 'http://github.com/thoughtbot/clearance'
+  s.homepage = 'https://github.com/thoughtbot/clearance'
   s.license = 'MIT'
   s.name = %q{clearance}
   s.rdoc_options = ['--charset=UTF-8']

data/config/locales/clearance.en.yml

@@ -1,5 +1,9 @@
 ---
 en:
+  clearance:
+    models:
+      clearance_mailer:
+        change_password: Change your password
   clearance_mailer:
     change_password:
       closing: If you didn't request this, ignore this email. Your password has
@@ -12,12 +16,17 @@ en:
     failure_after_update: Password can't be blank.
     failure_when_forbidden: Please double check the URL or try submitting
       the form again.
+    failure_when_not_signed_in: Please sign in to continue.
   helpers:
     label:
       password:
         email: Email address
       password_reset:
         password: Choose password
+      session:
+        password: Password
+      user:
+        password: Password
     submit:
       password:
         submit: Reset password

data/gemfiles/rails_4.2.gemfile

@@ -0,0 +1,20 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "addressable", "~> 2.6.0"
+gem "appraisal"
+gem "ammeter"
+gem "bundler", "~> 1.3"
+gem "capybara", ">= 2.6.2"
+gem "database_cleaner", "~> 1.0"
+gem "factory_bot_rails", "~> 5.0"
+gem "nokogiri", "~> 1.10.0"
+gem "rspec-rails", "~> 3.1"
+gem "shoulda-matchers", "~> 4.0"
+gem "sqlite3", "~> 1.3.13"
+gem "timecop", "~> 0.6"
+gem "pry", require: false
+gem "railties", "~> 4.2.0"
+
+gemspec path: "../"

data/gemfiles/rails_5.0.gemfile

@@ -0,0 +1,21 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "addressable", "~> 2.6.0"
+gem "appraisal"
+gem "ammeter"
+gem "bundler", "~> 1.3"
+gem "capybara", ">= 2.6.2"
+gem "database_cleaner", "~> 1.0"
+gem "factory_bot_rails", "~> 5.0"
+gem "nokogiri", "~> 1.10.0"
+gem "rspec-rails", "~> 3.1"
+gem "shoulda-matchers", "~> 4.0"
+gem "sqlite3", "~> 1.3.13"
+gem "timecop", "~> 0.6"
+gem "pry", require: false
+gem "railties", "~> 5.0.0"
+gem "rails-controller-testing"
+
+gemspec path: "../"

data/gemfiles/rails_5.1.gemfile

@@ -0,0 +1,21 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "addressable", "~> 2.6.0"
+gem "appraisal"
+gem "ammeter"
+gem "bundler", "~> 1.3"
+gem "capybara", ">= 2.6.2"
+gem "database_cleaner", "~> 1.0"
+gem "factory_bot_rails", "~> 5.0"
+gem "nokogiri", "~> 1.10.0"
+gem "rspec-rails", "~> 3.1"
+gem "shoulda-matchers", "~> 4.0"
+gem "sqlite3", "~> 1.3.13"
+gem "timecop", "~> 0.6"
+gem "pry", require: false
+gem "railties", "~> 5.1.0"
+gem "rails-controller-testing"
+
+gemspec path: "../"

data/gemfiles/rails_5.2.gemfile

@@ -0,0 +1,21 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "addressable", "~> 2.6.0"
+gem "appraisal"
+gem "ammeter"
+gem "bundler", "~> 1.3"
+gem "capybara", ">= 2.6.2"
+gem "database_cleaner", "~> 1.0"
+gem "factory_bot_rails", "~> 5.0"
+gem "nokogiri", "~> 1.10.0"
+gem "rspec-rails", "~> 3.1"
+gem "shoulda-matchers", "~> 4.0"
+gem "sqlite3", "~> 1.3.13"
+gem "timecop", "~> 0.6"
+gem "pry", require: false
+gem "railties", "~> 5.2.0"
+gem "rails-controller-testing"
+
+gemspec path: "../"