clearance 1.8.0 → 1.13.0

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
@@ -40,7 +53,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
@@ -76,6 +89,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 +108,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,8 +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]
-  protect_from_forgery except: :create
+  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.html.erb

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

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

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

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

@@ -7,9 +7,9 @@
 <body>
   <div id="header">
     <% if signed_in? -%>
-      <%= button_to t('.sign_out'), sign_out_path, method: :delete %>
+      <%= button_to t(".sign_out"), sign_out_path, method: :delete %>
     <% else -%>
-      <%= link_to t('.sign_in'), sign_in_path %>
+      <%= link_to t(".sign_in"), sign_in_path %>
     <% end -%>
   </div>
 

data/app/views/passwords/create.html.erb

@@ -1,3 +1,3 @@
 <div id="clearance" class="password-reset">
-  <p><%= t '.description' %></p>
+  <p><%= t(".description") %></p>
 </div>

data/app/views/passwords/edit.html.erb

@@ -1,7 +1,7 @@
 <div id="clearance" class="password-reset">
-  <h2><%= t '.title' %></h2>
+  <h2><%= t(".title") %></h2>
 
-  <p><%= t '.description' %></p>
+  <p><%= t(".description") %></p>
 
   <%= form_for :password_reset,
         url: user_password_path(@user, token: @user.confirmation_token),

data/app/views/passwords/new.html.erb

@@ -1,7 +1,7 @@
 <div id="clearance" class="password-reset">
-  <h2><%= t '.title' %></h2>
+  <h2><%= t(".title") %></h2>
 
-  <p><%= t '.description' %></p>
+  <p><%= t(".description") %></p>
 
   <%= form_for :password, url: passwords_path do |form| %>
     <div class="text-field">

data/app/views/sessions/_form.html.erb

@@ -15,8 +15,8 @@
 
   <div class="other-links">
     <% if Clearance.configuration.allow_sign_up? %>
-      <%= link_to t('.sign_up'), sign_up_path %>
+      <%= link_to t(".sign_up"), sign_up_path %>
     <% end %>
-    <%= link_to t('.forgot_password'), new_password_path %>
+    <%= link_to t(".forgot_password"), new_password_path %>
   </div>
 <% end %>

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

@@ -1,5 +1,5 @@
 <div id="clearance" class="sign-in">
-  <h2><%= t '.title' %></h2>
+  <h2><%= t(".title") %></h2>
 
   <%= render partial: '/sessions/form' %>
 

data/app/views/users/new.html.erb

@@ -1,5 +1,5 @@
 <div id="clearance" class="sign-up">
-  <h2><%= t('.title') %></h2>
+  <h2><%= t(".title") %></h2>
 
   <%= form_for @user do |form| %>
     <%= render partial: '/users/form', object: form %>
@@ -9,7 +9,7 @@
     </div>
 
     <div class="other-links">
-      <%= link_to t('.sign_in'), sign_in_path %>
+      <%= link_to t(".sign_in"), sign_in_path %>
     </div>
   <% end %>
 </div>

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/config/locales/clearance.en.yml

@@ -1,9 +1,14 @@
 ---
 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
         not been changed.
+      link_text: Change my password
       opening: "Someone, hopefully you, requested we send you a link to change
         your password:"
   flashes:
@@ -11,6 +16,7 @@ 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:

data/db/migrate/20110111224543_create_clearance_users.rb

@@ -1,6 +1,6 @@
 class CreateClearanceUsers < ActiveRecord::Migration
   def self.up
-    create_table :users  do |t|
+    create_table :users do |t|
       t.timestamps null: false
       t.string :email, null: false
       t.string :encrypted_password, limit: 128, null: false

data/gemfiles/{rails3.2.gemfile → rails32.gemfile}

@@ -9,7 +9,7 @@ gem "capybara", ">= 2.3"
 gem "database_cleaner", "~> 1.0"
 gem "factory_girl_rails", "~> 4.2"
 gem "rspec-rails", "~> 3.1"
-gem "shoulda-matchers", "~> 2.4"
+gem "shoulda-matchers", "~> 2.8"
 gem "sqlite3", "~> 1.3"
 gem "timecop", "~> 0.6"
 gem "pry", :require => false

data/gemfiles/{rails4.0.gemfile → rails40.gemfile}

@@ -5,11 +5,11 @@ source "https://rubygems.org"
 gem "appraisal", "~> 1.0"
 gem "ammeter"
 gem "bundler", "~> 1.3"
-gem "capybara", ">= 2.3"
+gem "capybara", ">= 2.6.2"
 gem "database_cleaner", "~> 1.0"
 gem "factory_girl_rails", "~> 4.2"
 gem "rspec-rails", "~> 3.1"
-gem "shoulda-matchers", "~> 2.4"
+gem "shoulda-matchers", "~> 2.8"
 gem "sqlite3", "~> 1.3"
 gem "timecop", "~> 0.6"
 gem "pry", :require => false

data/gemfiles/{rails4.1.gemfile → rails41.gemfile}

@@ -5,11 +5,11 @@ source "https://rubygems.org"
 gem "appraisal", "~> 1.0"
 gem "ammeter"
 gem "bundler", "~> 1.3"
-gem "capybara", ">= 2.3"
+gem "capybara", ">= 2.6.2"
 gem "database_cleaner", "~> 1.0"
 gem "factory_girl_rails", "~> 4.2"
 gem "rspec-rails", "~> 3.1"
-gem "shoulda-matchers", "~> 2.4"
+gem "shoulda-matchers", "~> 2.8"
 gem "sqlite3", "~> 1.3"
 gem "timecop", "~> 0.6"
 gem "pry", :require => false

data/gemfiles/{rails4.2.gemfile → rails42.gemfile}

@@ -5,11 +5,11 @@ source "https://rubygems.org"
 gem "appraisal", "~> 1.0"
 gem "ammeter"
 gem "bundler", "~> 1.3"
-gem "capybara", ">= 2.3"
+gem "capybara", ">= 2.6.2"
 gem "database_cleaner", "~> 1.0"
 gem "factory_girl_rails", "~> 4.2"
 gem "rspec-rails", "~> 3.1"
-gem "shoulda-matchers", "~> 2.4"
+gem "shoulda-matchers", "~> 2.8"
 gem "sqlite3", "~> 1.3"
 gem "timecop", "~> 0.6"
 gem "pry", :require => false

data/gemfiles/rails50.gemfile

@@ -0,0 +1,19 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "appraisal", "~> 1.0"
+gem "ammeter"
+gem "bundler", "~> 1.3"
+gem "capybara", ">= 2.6.2"
+gem "database_cleaner", "~> 1.0"
+gem "factory_girl_rails", "~> 4.2"
+gem "rspec-rails", "~> 3.5.0.beta1"
+gem "shoulda-matchers", "~> 2.8"
+gem "sqlite3", "~> 1.3"
+gem "timecop", "~> 0.6"
+gem "pry", :require => false
+gem "rails", "~> 5.0.0.beta3"
+gem "rails-controller-testing"
+
+gemspec :path => "../"

data/lib/clearance/authentication.rb

@@ -4,9 +4,11 @@ module Clearance
 
     included do
       helper_method :current_user, :signed_in?, :signed_out?
-      hide_action(
+      private(
+        :authenticate,
         :current_user,
         :current_user=,
+        :handle_unverified_request,
         :sign_in,
         :sign_out,
         :signed_in?,
@@ -14,40 +16,88 @@ module Clearance
       )
     end
 
+    # Authenticate a user with a provided email and password
+    # @param [ActionController::Parameters] params The parameters from the
+    #   sign in form. `params[:session][:email]` and
+    #   `params[:session][:password]` are required.
+    # @return [User, nil] The user or nil if authentication fails.
     def authenticate(params)
       Clearance.configuration.user_model.authenticate(
         params[:session][:email], params[:session][:password]
       )
     end
 
+    # Get the user from the current clearance session. Exposed as a
+    # `helper_method`, making it visible to views. Prefer {#signed_in?} or
+    # {#signed_out?} if you only want to check for the presence of a current
+    # user rather than access the actual user.
+    #
+    # @return [User, nil] The user if one is signed in or nil otherwise.
     def current_user
       clearance_session.current_user
     end
 
+    # @deprecated Use the {#sign_in} method instead.
     def current_user=(user)
       warn "#{Kernel.caller.first}: [DEPRECATION] " +
         'Assigning the current_user has been deprecated. Use the sign_in method instead.'
       clearance_session.sign_in user
     end
 
+    # Sign in the provided user.
+    # @param [User] user
+    #
+    # Signing in will run the stack of {Configuration#sign_in_guards}.
+    #
+    # You can provide a block to this method to handle the result of that stack.
+    # Your block will receive either a {SuccessStatus} or {FailureStatus}
+    #
+    #     sign_in(user) do |status|
+    #       if status.success?
+    #         # ...
+    #       else
+    #         # ...
+    #       end
+    #     end
+    #
+    # For an example of how clearance uses this internally, see
+    # {SessionsController#create}.
     def sign_in(user, &block)
       clearance_session.sign_in user, &block
     end
 
+    # Destroy the current user's Clearance session.
+    # See {Session#sign_out} for specifics.
     def sign_out
       clearance_session.sign_out
     end
 
+    # True if there is a currently-signed-in user. Exposed as a `helper_method`,
+    # making it available to views.
+    #
+    # Using `signed_in?` is preferable to checking {#current_user} against nil
+    # as it will allow you to introduce a null user object more simply at a
+    # later date.
+    #
+    # @return [Boolean]
     def signed_in?
       clearance_session.signed_in?
     end
 
+    # True if there is no currently-signed-in user. Exposed as a
+    # `helper_method`, making it available to views.
+    #
+    # Usings `signed_out?` is preferable to checking for presence of
+    # {#current_user} as it will allow you to introduce a null user object more
+    # simply at a later date.
     def signed_out?
       !signed_in?
     end
 
     # CSRF protection in Rails >= 3.0.4
+    #
     # http://weblog.rubyonrails.org/2011/2/8/csrf-protection-bypass-in-ruby-on-rails
+    # @private
     def handle_unverified_request
       super
       sign_out
@@ -55,6 +105,7 @@ module Clearance
 
     protected
 
+    # @api private
     def clearance_session
       request.env[:clearance]
     end

data/lib/clearance/authorization.rb

@@ -3,23 +3,52 @@ module Clearance
     extend ActiveSupport::Concern
 
     included do
-      hide_action :authorize, :deny_access, :require_login
+      private :authorize, :deny_access, :require_login
     end
 
+    # Use as a `before_action` to require a user be signed in to proceed.
+    # {Authentication#signed_in?} is used to determine if there is a signed in
+    # user or not.
+    #
+    #     class PostsController < ApplicationController
+    #       before_action :require_login
+    #
+    #       def index
+    #         # ...
+    #       end
+    #     end
     def require_login
       unless signed_in?
-        deny_access
+        deny_access(I18n.t("flashes.failure_when_not_signed_in"))
       end
     end
 
+    # @deprecated use {#require_login}
     def authorize
-      warn "[DEPRECATION] Clearance's `authorize` before_filter is " +
+      warn "[DEPRECATION] Clearance's `authorize` before_action is " +
         "deprecated. Use `require_login` instead. Be sure to update any " +
-        "instances of `skip_before_filter :authorize` or " +
+        "instances of `skip_before_action :authorize` or " +
         "`skip_before_action :authorize` as well"
       require_login
     end
 
+    # Responds to unauthorized requests in a manner fitting the request format.
+    # `js`, `json`, and `xml` requests will receive a 401 with no body. All
+    # other formats will be redirected appropriately and can optionally have the
+    # flash message set.
+    #
+    # When redirecting, the originally requested url will be stored in the
+    # session (`session[:return_to]`), allowing it to be used as a redirect url
+    # once the user has successfully signed in.
+    #
+    # If there is a signed in user, the request will be redirected according to
+    # the value returned from {#url_after_denied_access_when_signed_in}.
+    #
+    # If there is no signed in user, the request will be redirected according to
+    # the value returned from {#url_after_denied_access_when_signed_out}.
+    # For the exact redirect behavior, see {#redirect_request}.
+    #
+    # @param [String] flash_message
     def deny_access(flash_message = nil)
       respond_to do |format|
         format.any(:js, :json, :xml) { head :unauthorized }
@@ -29,6 +58,7 @@ module Clearance
 
     protected
 
+    # @api private
     def redirect_request(flash_message)
       store_location
 
@@ -43,21 +73,25 @@ module Clearance
       end
     end
 
+    # @api private
     def clear_return_to
       session[:return_to] = nil
     end
 
+    # @api private
     def store_location
       if request.get?
         session[:return_to] = request.original_fullpath
       end
     end
 
+    # @api private
     def redirect_back_or(default)
       redirect_to(return_to || default)
       clear_return_to
     end
 
+    # @api private
     def return_to
       if return_to_url
         uri = URI.parse(return_to_url)
@@ -65,14 +99,23 @@ module Clearance
       end
     end
 
+    # @api private
     def return_to_url
       session[:return_to]
     end
 
+    # Used as the redirect location when {#deny_access} is called and there is a
+    # currently signed in user.
+    #
+    # @return [String]
     def url_after_denied_access_when_signed_in
       Clearance.configuration.redirect_url
     end
 
+    # Used as the redirect location when {#deny_access} is called and there is
+    # no currently signed in user.
+    #
+    # @return [String]
     def url_after_denied_access_when_signed_out
       sign_in_url
     end

data/lib/clearance/back_door.rb

@@ -29,6 +29,7 @@ module Clearance
 
     private
 
+    # @api private
     def sign_in_through_the_back_door(env)
       params = Rack::Utils.parse_query(env['QUERY_STRING'])
       user_id = params['as']