clearance 2.0.0.beta2 → 2.3.0

data/README.md

@@ -19,7 +19,7 @@ monitored by contributors.
 
 ## Getting Started
 
-Clearance is a Rails engine tested against Rails `>= 3.2` and Ruby `>= 1.9.3`.
+Clearance is a Rails engine tested against Rails `>= 5.0` and Ruby `>= 2.4.0`.
 
 You can add it to your Gemfile with:
 
@@ -59,17 +59,15 @@ Clearance.configure do |config|
   config.mailer_sender = "reply@example.com"
   config.password_strategy = Clearance::PasswordStrategies::BCrypt
   config.redirect_url = "/"
-  config.rotate_csrf_on_sign_in = false
+  config.rotate_csrf_on_sign_in = true
+  config.same_site = nil
   config.secure_cookie = false
   config.sign_in_guards = []
   config.user_model = "User"
+  config.parent_controller = "ApplicationController"
 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
@@ -281,23 +279,12 @@ for access to additional, user-contributed translations.
 See [lib/clearance/user.rb](/lib/clearance/user.rb) for the default behavior.
 You can override those methods as needed.
 
-### Deliver Email in Background Job
-
-Clearance has a password reset mailer. If you are using Rails 4.2 and Clearance
-1.6 or greater, Clearance will use ActiveJob's `deliver_later` method to
-automatically take advantage of your configured queue.
-
-If you are using an earlier version of Rails, you can override the
-`Clearance::Passwords` controller and define the behavior you need in the
-`deliver_email` method.
-
-```ruby
-class PasswordsController < Clearance::PasswordsController
-  def deliver_email(user)
-    ClearanceMailer.delay.change_password(user)
-  end
-end
-```
+Note that there are some model-level validations (see above link for detail)
+which the `Clearance::User` module will add to the configured model class and
+which may conflict with or duplicate already present validations on the `email`
+and `password` attributes. Over-riding the `email_optional?` or
+`skip_password_validation?` methods to return `true` will disable those
+validations from being added.
 
 ## Extending Sign In
 
@@ -329,7 +316,7 @@ Here's an example custom guard to handle email confirmation:
 
 ```ruby
 Clearance.configure do |config|
-  config.sign_in_guards = [EmailConfirmationGuard]
+  config.sign_in_guards = ["EmailConfirmationGuard"]
 end
 ```
 

data/RELEASING.md

@@ -0,0 +1,25 @@
+# Releasing
+
+1. Update version file accordingly.
+1. Run `bundle install` to update Gemfile.lock
+1. Update `NEWS.md` to reflect the changes since last release.
+1. Commit changes.
+   There shouldn't be code changes,
+   and thus CI doesn't need to run,
+   you can then add "[ci skip]" to the commit message.
+1. Push the new commit
+1. Tag the release: `git tag -s vVERSION`
+    - We recommend the [_quick guide on how to sign a commit_] from GitHub.
+1. Push changes: `git push --tags`
+1. Build and publish:
+    ```bash
+    gem build clearance.gemspec
+    gem push clearance-*.gem
+    ```
+1. Add a new GitHub release using the recent `NEWS.md` as the content. Sample
+   URL: https://github.com/thoughtbot/clearance/releases/new?tag=vVERSION
+1. Announce the new release,
+   making sure to say "thank you" to the contributors
+   who helped shape this version!
+
+[_quick guide on how to sign a commit_]: https://docs.github.com/en/github/authenticating-to-github/signing-commits

data/Rakefile

@@ -22,5 +22,10 @@ RSpec::Core::RakeTask.new("spec:acceptance") do |task|
   task.verbose = false
 end
 
+desc "Lint ERB templates"
+task :erb_lint do
+  sh("bundle", "exec", "erblint", "app/views/**/*.erb")
+end
+
 desc "Run the specs and acceptance tests"
-task default: %w(spec spec:acceptance)
+task default: %w(spec spec:acceptance erb_lint)

data/app/controllers/clearance/base_controller.rb

@@ -1,2 +1,9 @@
-class Clearance::BaseController < ApplicationController
+module Clearance
+  # Top-level base class that all Clearance controllers inherit from.
+  # Inherits from `ApplicationController` by default and can be overridden by
+  # setting a new value with {Configuration#parent_controller=}.
+  # @!parse
+  #   class BaseController < ApplicationController; end
+  class BaseController < Clearance.configuration.parent_controller
+  end
 end

data/app/controllers/clearance/passwords_controller.rb

@@ -2,6 +2,7 @@ require 'active_support/deprecation'
 
 class Clearance::PasswordsController < Clearance::BaseController
   before_action :ensure_existing_user, only: [:edit, :update]
+  before_action :ensure_email_present, only: [:create]
   skip_before_action :require_login, only: [:create, :edit, :new, :update], raise: false
 
   def new
@@ -31,7 +32,7 @@ class Clearance::PasswordsController < Clearance::BaseController
   def update
     @user = find_user_for_update
 
-    if @user.update_password password_reset_params
+    if @user.update_password(password_from_password_reset_params)
       sign_in @user
       redirect_to url_after_update
       session[:password_reset_token] = nil
@@ -44,12 +45,11 @@ class Clearance::PasswordsController < Clearance::BaseController
   private
 
   def deliver_email(user)
-    mail = ::ClearanceMailer.change_password(user)
-    mail.deliver_later
+    ::ClearanceMailer.change_password(user).deliver_now
   end
 
-  def password_reset_params
-    params[:password_reset][:password]
+  def password_from_password_reset_params
+    params.dig(:password_reset, :password)
   end
 
   def find_user_by_id_and_confirmation_token
@@ -57,12 +57,16 @@ class Clearance::PasswordsController < Clearance::BaseController
     token = params[:token] || session[:password_reset_token]
 
     Clearance.configuration.user_model.
-      find_by_id_and_confirmation_token params[user_param], token.to_s
+      find_by(id: params[user_param], confirmation_token: token.to_s)
+  end
+
+  def email_from_password_params
+    params.dig(:password, :email)
   end
 
   def find_user_for_create
     Clearance.configuration.user_model.
-      find_by_normalized_email params[:password][:email]
+      find_by_normalized_email(email_from_password_params)
   end
 
   def find_user_for_edit
@@ -73,6 +77,13 @@ class Clearance::PasswordsController < Clearance::BaseController
     find_user_by_id_and_confirmation_token
   end
 
+  def ensure_email_present
+    if email_from_password_params.blank?
+      flash_failure_when_missing_email
+      render template: "passwords/new"
+    end
+  end
+
   def ensure_existing_user
     unless find_user_by_id_and_confirmation_token
       flash_failure_when_forbidden
@@ -92,6 +103,12 @@ class Clearance::PasswordsController < Clearance::BaseController
       default: t("flashes.failure_after_update"))
   end
 
+  def flash_failure_when_missing_email
+    flash.now[:alert] = translate(:missing_email,
+      scope: [:clearance, :controllers, :passwords],
+      default: t("flashes.failure_when_missing_email"))
+  end
+
   def url_after_update
     Clearance.configuration.redirect_url
   end

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

@@ -2,7 +2,7 @@
 
 <p>
   <%= link_to t(".link_text", default: "Change my password"),
-    edit_user_password_url(@user, token: @user.confirmation_token.html_safe) %>
+    edit_user_password_url(@user, token: @user.confirmation_token) %>
 </p>
 
-<p><%= raw t(".closing") %></p>
+<p><%= t(".closing") %></p>

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

@@ -1,5 +1,5 @@
 <%= t(".opening") %>
 
-<%= edit_user_password_url(@user, token: @user.confirmation_token.html_safe) %>
+<%= edit_user_password_url(@user, token: @user.confirmation_token) %>
 
-<%= raw t(".closing") %>
+<%= t(".closing") %>

data/clearance.gemspec

@@ -2,8 +2,9 @@ $LOAD_PATH.push File.expand_path('../lib', __FILE__)
 require 'clearance/version'
 
 Gem::Specification.new do |s|
-  s.add_dependency 'bcrypt'
-  s.add_dependency 'email_validator', '~> 1.4'
+  s.add_dependency 'bcrypt', '>= 3.1.1'
+  s.add_dependency 'argon2', '~> 2.0', '>= 2.0.2'
+  s.add_dependency 'email_validator', '~> 2.0'
   s.add_dependency 'railties', '>= 5.0'
   s.add_dependency 'activemodel', '>= 5.0'
   s.add_dependency 'activerecord', '>= 5.0'
@@ -28,7 +29,13 @@ Gem::Specification.new do |s|
     'Galen Frechette',
     'Josh Steiner'
   ]
-  s.description = 'Rails authentication & authorization with email & password.'
+  s.description = <<-DESCRIPTION
+    Clearance is built to support authentication and authorization via an
+    email/password sign-in mechanism in applications.
+
+    It provides some core classes commonly used for these features, along with
+    some opinionated defaults - but is intended to be easy to override.
+  DESCRIPTION
   s.email = 'support@thoughtbot.com'
   s.extra_rdoc_files = %w(LICENSE README.md)
   s.files = `git ls-files`.split("\n")

data/config/locales/clearance.en.yml

@@ -17,6 +17,7 @@ en:
     failure_when_forbidden: Please double check the URL or try submitting
       the form again.
     failure_when_not_signed_in: Please sign in to continue.
+    failure_when_missing_email: Email can't be blank.
   helpers:
     label:
       password:

data/config/routes.rb

@@ -13,7 +13,7 @@ if Clearance.configuration.routes_enabled?
       only: Clearance.configuration.user_actions do
         resource :password,
           controller: 'clearance/passwords',
-          only: [:create, :edit, :update]
+          only: [:edit, :update]
       end
 
     get '/sign_in' => 'clearance/sessions#new', as: 'sign_in'

data/gemfiles/rails_5.0.gemfile

@@ -2,19 +2,20 @@
 
 source "https://rubygems.org"
 
-gem "addressable", "~> 2.6.0"
+gem "addressable"
 gem "ammeter"
 gem "appraisal"
-gem "capybara", ">= 2.6.2"
-gem "database_cleaner", "~> 1.0"
-gem "factory_bot_rails", "~> 5.0"
-gem "nokogiri", "~> 1.10.0"
+gem "capybara", ">= 2.6.2", "< 3.33.0"
+gem "database_cleaner"
+gem "erb_lint", require: false
+gem "factory_bot_rails"
+gem "nokogiri"
 gem "pry", require: false
-gem "shoulda-matchers", "~> 4.1"
-gem "timecop", "~> 0.6"
-gem "railties", "~> 5.0.0"
 gem "rails-controller-testing"
-gem "sqlite3", "~> 1.3.13"
 gem "rspec-rails", "~> 3.1"
+gem "shoulda-matchers"
+gem "sqlite3", "~> 1.3.13"
+gem "timecop"
+gem "railties", "~> 5.0"
 
 gemspec path: "../"

data/gemfiles/rails_5.1.gemfile

@@ -2,19 +2,20 @@
 
 source "https://rubygems.org"
 
-gem "addressable", "~> 2.6.0"
+gem "addressable"
 gem "ammeter"
 gem "appraisal"
-gem "capybara", ">= 2.6.2"
-gem "database_cleaner", "~> 1.0"
-gem "factory_bot_rails", "~> 5.0"
-gem "nokogiri", "~> 1.10.0"
+gem "capybara"
+gem "database_cleaner"
+gem "erb_lint", require: false
+gem "factory_bot_rails"
+gem "nokogiri"
 gem "pry", require: false
-gem "shoulda-matchers", "~> 4.1"
-gem "timecop", "~> 0.6"
-gem "railties", "~> 5.1.0"
 gem "rails-controller-testing"
-gem "sqlite3", "~> 1.3.13"
-gem "rspec-rails", "~> 3.1"
+gem "rspec-rails"
+gem "shoulda-matchers"
+gem "sqlite3"
+gem "timecop"
+gem "railties", "~> 5.1"
 
 gemspec path: "../"

data/gemfiles/rails_5.2.gemfile

@@ -2,19 +2,20 @@
 
 source "https://rubygems.org"
 
-gem "addressable", "~> 2.6.0"
+gem "addressable"
 gem "ammeter"
 gem "appraisal"
-gem "capybara", ">= 2.6.2"
-gem "database_cleaner", "~> 1.0"
-gem "factory_bot_rails", "~> 5.0"
-gem "nokogiri", "~> 1.10.0"
+gem "capybara"
+gem "database_cleaner"
+gem "erb_lint", require: false
+gem "factory_bot_rails"
+gem "nokogiri"
 gem "pry", require: false
-gem "shoulda-matchers", "~> 4.1"
-gem "timecop", "~> 0.6"
-gem "railties", "~> 5.2.0"
 gem "rails-controller-testing"
-gem "sqlite3", "~> 1.3.13"
-gem "rspec-rails", "~> 3.1"
+gem "rspec-rails"
+gem "shoulda-matchers"
+gem "sqlite3"
+gem "timecop"
+gem "railties", "~> 5.2"
 
 gemspec path: "../"

data/gemfiles/rails_6.0.gemfile

@@ -2,19 +2,20 @@
 
 source "https://rubygems.org"
 
-gem "addressable", "~> 2.6.0"
+gem "addressable"
 gem "ammeter"
 gem "appraisal"
-gem "capybara", ">= 2.6.2"
-gem "database_cleaner", "~> 1.0"
-gem "factory_bot_rails", "~> 5.0"
-gem "nokogiri", "~> 1.10.0"
+gem "capybara"
+gem "database_cleaner"
+gem "erb_lint", require: false
+gem "factory_bot_rails"
+gem "nokogiri"
 gem "pry", require: false
-gem "shoulda-matchers", "~> 4.1"
-gem "timecop", "~> 0.6"
-gem "railties", "~> 6.0.0"
 gem "rails-controller-testing"
-gem "rspec-rails", "~> 4.0.0.beta2"
-gem "sqlite3", "~> 1.4.0"
+gem "rspec-rails"
+gem "shoulda-matchers"
+gem "sqlite3"
+gem "timecop"
+gem "railties", "~> 6.0"
 
 gemspec path: "../"

data/lib/clearance/authentication.rb

@@ -59,7 +59,7 @@ module Clearance
     # {SessionsController#create}.
     #
     # Signing in will also regenerate the CSRF token for the current session,
-    # provided {Configuration#rotate_csrf_token_on_sign_in} is set.
+    # provided {Configuration#rotate_csrf_on_sign_in?} is set.
     def sign_in(user, &block)
       clearance_session.sign_in(user, &block)
 

data/lib/clearance/back_door.rb

@@ -49,7 +49,8 @@ module Clearance
     # @api private
     def sign_in_through_the_back_door(env)
       params = Rack::Utils.parse_query(env["QUERY_STRING"])
-      user_param = params["as"]
+      user_param = params.delete("as")
+      env["QUERY_STRING"] = Rack::Utils.build_query(params)
 
       if user_param.present?
         user = find_user(user_param)

data/lib/clearance/configuration.rb

@@ -42,6 +42,16 @@ module Clearance
     # @return [Boolean]
     attr_accessor :httponly
 
+    # Same-site cookies ("First-Party-Only" or "First-Party") allow servers to
+    # mitigate the risk of CSRF and information leakage attacks by asserting
+    # that a particular cookie should only be sent with requests initiated from
+    # the same registrable domain.
+    # Defaults to `nil`. For more, see
+    # [RFC6265](https://tools.ietf.org/html/draft-west-first-party-cookies-06#section-4.1.1).
+    # and https://github.com/rack/rack/blob/6eda04886e3a57918ca2d6a482fda02a678fef0a/lib/rack/utils.rb#L232-L244
+    # @return [String]
+    attr_accessor :same_site
+
     # Controls the address the password reset email is sent from.
     # Defaults to reply@example.com.
     # @return [String]
@@ -88,7 +98,12 @@ module Clearance
     # The ActiveRecord class that represents users in your application.
     # Defaults to `::User`.
     # @return [ActiveRecord::Base]
-    attr_accessor :user_model
+    attr_writer :user_model
+
+    # The controller class that all Clearance controllers will inherit from.
+    # Defaults to `::ApplicationController`.
+    # @return [ActionController::Base]
+    attr_writer :parent_controller
 
     # The array of allowed environments where `Clearance::BackDoor` is enabled.
     # Defaults to ["test", "ci", "development"]
@@ -103,18 +118,29 @@ module Clearance
       @cookie_name = "remember_token"
       @cookie_path = '/'
       @httponly = true
+      @same_site = nil
       @mailer_sender = 'reply@example.com'
       @redirect_url = '/'
-      @rotate_csrf_on_sign_in = nil
+      @rotate_csrf_on_sign_in = true
       @routes = true
       @secure_cookie = false
       @sign_in_guards = []
     end
 
+    # The class representing the configured user model.
+    # In the default configuration, this is the `User` class.
+    # @return [Class]
     def user_model
       (@user_model || "User").to_s.constantize
     end
 
+    # The class representing the configured base controller.
+    # In the default configuration, this is the `ApplicationController` class.
+    # @return [Class]
+    def parent_controller
+      (@parent_controller || "ApplicationController").to_s.constantize
+    end
+
     # Is the user sign up route enabled?
     # @return [Boolean]
     def allow_sign_up?
@@ -167,22 +193,7 @@ module Clearance
     end
 
     def rotate_csrf_on_sign_in?
-      if rotate_csrf_on_sign_in.nil?
-        warn <<-EOM.squish
-          Clearance's `rotate_csrf_on_sign_in` configuration setting is unset and
-          will be treated as `false`. Setting this value to `true` is
-          recommended to avoid session fixation attacks and will be the default
-          in Clearance 2.0. It is recommended that you opt-in to this setting
-          now and test your application. To silence this warning, set
-          `rotate_csrf_on_sign_in` to `true` or `false` in Clearance's
-          initializer.
-
-          For more information on session fixation, see:
-            https://www.owasp.org/index.php/Session_fixation
-        EOM
-      end
-
-      rotate_csrf_on_sign_in
+      !!rotate_csrf_on_sign_in
     end
   end