clearance 1.10.1 → 1.17.0

data/lib/clearance/authentication.rb

@@ -3,8 +3,11 @@ module Clearance
     extend ActiveSupport::Concern
 
     included do
-      helper_method :current_user, :signed_in?, :signed_out?
-      hide_action(
+      if respond_to?(:helper_method)
+        helper_method :current_user, :signed_in?, :signed_out?
+      end
+
+      private(
         :authenticate,
         :current_user,
         :current_user=,
@@ -16,40 +19,96 @@ 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}.
+    #
+    # Signing in will also regenerate the CSRF token for the current session,
+    # provided {Configuration#rotate_csrf_token_on_sign_in} is set.
     def sign_in(user, &block)
-      clearance_session.sign_in user, &block
+      clearance_session.sign_in(user, &block)
+
+      if signed_in? && Clearance.configuration.rotate_csrf_on_sign_in?
+        session.delete(:_csrf_token)
+        form_authenticity_token
+      end
     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
@@ -57,6 +116,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,36 +73,49 @@ 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)
-        "#{uri.path}?#{uri.query}".chomp('?')
+        "#{uri.path}?#{uri.query}".chomp("?") + "##{uri.fragment}".chomp("#")
       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

@@ -1,6 +1,7 @@
 module Clearance
   # Middleware which allows signing in by passing as=USER_ID in a query
-  # parameter.
+  # parameter. If `User#to_param` is overriden you may pass a block to
+  # override the default user lookup behaviour
   #
   # Designed to eliminate time in integration tests wasted by visiting and
   # submitting the sign in form.
@@ -14,12 +15,28 @@ module Clearance
   #     # ...
   #   end
   #
+  #   # or if `User#to_param` is overridden (to `username` for example):
+  #
+  #   # config/environments/test.rb
+  #   MyRailsApp::Application.configure do
+  #     # ...
+  #     config.middleware.use Clearance::BackDoor do |username|
+  #       User.find_by(username: username)
+  #     end
+  #     # ...
+  #   end
+  #
   # Usage:
   #
   #   visit new_feedback_path(as: user)
   class BackDoor
-    def initialize(app)
+    def initialize(app, &block)
+      unless environment_is_allowed?
+        raise error_message
+      end
+
       @app = app
+      @block = block
     end
 
     def call(env)
@@ -29,14 +46,46 @@ 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']
+      params = Rack::Utils.parse_query(env["QUERY_STRING"])
+      user_param = params["as"]
 
-      if user_id.present?
-        user = Clearance.configuration.user_model.find(user_id)
+      if user_param.present?
+        user = find_user(user_param)
         env[:clearance].sign_in(user)
       end
     end
+
+    # @api private
+    def find_user(user_param)
+      if @block
+        @block.call(user_param)
+      else
+        Clearance.configuration.user_model.find(user_param)
+      end
+    end
+
+    # @api private
+    def environment_is_allowed?
+      allowed_environments.include? ENV["RAILS_ENV"]
+    end
+
+    # @api private
+    def allowed_environments
+      Clearance.configuration.allowed_backdoor_environments || []
+    end
+
+    # @api private
+    def error_message
+      unless allowed_environments.empty?
+        <<-EOS.squish
+          Can't use auth backdoor outside of
+          configured environments (#{allowed_environments.join(", ")}).
+        EOS
+      else
+        "BackDoor auth is disabled."
+      end
+    end
   end
 end

data/lib/clearance/configuration.rb

@@ -35,8 +35,8 @@ module Clearance
     # @return [String]
     attr_accessor :cookie_path
 
-    # Controls whether the  HttpOnly flag should be set on the remember token
-    # cookie. Defaults to `false`. If `true`, the cookie will not be made
+    # Controls whether the HttpOnly flag should be set on the remember token
+    # cookie. Defaults to `true`, which prevents the cookie from being made
     # available to JavaScript. For more see
     # [RFC6265](http://tools.ietf.org/html/rfc6265#section-5.2.6).
     # @return [Boolean]
@@ -48,8 +48,8 @@ module Clearance
     attr_accessor :mailer_sender
 
     # The password strategy to use when authenticating and setting passwords.
-    # Defaults to `Clearance::PasswordStrategies::BCrypt`.
-    # @return [Class #authenticated? #password=]
+    # Defaults to {Clearance::PasswordStrategies::BCrypt}.
+    # @return [Module #authenticated? #password=]
     attr_accessor :password_strategy
 
     # The default path Clearance will redirect signed in users to.
@@ -58,6 +58,11 @@ module Clearance
     # @return [String]
     attr_accessor :redirect_url
 
+    # Controls whether Clearance will rotate the CSRF token on sign in.
+    # Defaults to `nil` which generates a warning. Will default to true in
+    # Clearance 2.0.
+    attr_accessor :rotate_csrf_on_sign_in
+
     # Set to `false` to disable Clearance's built-in routes.
     # Defaults to `true`. When set to false, your app is responsible for all
     # routes. You can dump a copy of Clearance's default routes with
@@ -81,19 +86,26 @@ module Clearance
     attr_accessor :sign_in_guards
 
     # The ActiveRecord class that represents users in your application.
-    # Defualts to `::User`.
+    # Defaults to `::User`.
     # @return [ActiveRecord::Base]
     attr_accessor :user_model
 
+    # The array of allowed environments where `Clearance::BackDoor` is enabled.
+    # Defaults to ["test", "ci", "development"]
+    # @return [Array<String>]
+    attr_accessor :allowed_backdoor_environments
+
     def initialize
       @allow_sign_up = true
-      @cookie_expiration = ->(cookies) { 1.year.from_now.utc }
+      @allowed_backdoor_environments = ["test", "ci", "development"]
       @cookie_domain = nil
-      @cookie_path = '/'
+      @cookie_expiration = ->(cookies) { 1.year.from_now.utc }
       @cookie_name = "remember_token"
-      @httponly = false
+      @cookie_path = '/'
+      @httponly = true
       @mailer_sender = 'reply@example.com'
       @redirect_url = '/'
+      @rotate_csrf_on_sign_in = nil
       @routes = true
       @secure_cookie = false
       @sign_in_guards = []
@@ -121,12 +133,20 @@ module Clearance
       end
     end
 
+    # The name of user parameter for the configured user model.
+    # This is derived from the `model_name` of the `user_model` setting.
+    # In the default configuration, this is `user`.
+    # @return [Symbol]
+    def user_parameter
+      user_model.model_name.singular.to_sym
+    end
+
     # The name of foreign key parameter for the configured user model.
     # This is derived from the `model_name` of the `user_model` setting.
     # In the default configuration, this is `user_id`.
     # @return [Symbol]
     def user_id_parameter
-      "#{user_model.model_name.singular}_id".to_sym
+      "#{user_parameter}_id".to_sym
     end
 
     # @return [Boolean] are Clearance's built-in routes enabled?
@@ -138,12 +158,32 @@ module Clearance
     # This is called from the Clearance engine to reload the configured
     # user class during each request while in development mode, but only once
     # in production.
-    # @private
+    #
+    # @api private
     def reload_user_model
       if @user_model.present?
         @user_model = @user_model.to_s.constantize
       end
     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
+    end
   end
 
   # @return [Clearance::Configuration] Clearance's current configuration

data/lib/clearance/constraints/signed_in.rb

@@ -1,5 +1,22 @@
 module Clearance
   module Constraints
+    # Can be applied to make a set of routes visible only to users that are
+    # signed in.
+    #
+    #     # config/routes.rb
+    #     constraints Clearance::Constraints::SignedIn.new do
+    #       resources :posts
+    #     end
+    #
+    # In the example above, requests to `/posts` from users that are not signed
+    # in will result in a 404. You can make additional assertions about the user
+    # by passing a block. For instance, if you want to require that the
+    # signed-in user be an admin:
+    #
+    #     # config/routes.rb
+    #     constraints Clearance::Constraints::SignedIn.new { |user| user.admin? } do
+    #       resources :posts
+    #     end
     class SignedIn
       def initialize(&block)
         @block = block || lambda { |user| true }
@@ -12,18 +29,22 @@ module Clearance
 
       private
 
+      # @api private
       def clearance_session
         @request.env[:clearance]
       end
 
+      # @api private
       def current_user
         clearance_session.current_user
       end
 
+      # @api private
       def current_user_fulfills_additional_requirements?
         @block.call current_user
       end
 
+      # @api private
       def signed_in?
         clearance_session.present? && clearance_session.signed_in?
       end

data/lib/clearance/constraints/signed_out.rb

@@ -1,5 +1,15 @@
 module Clearance
   module Constraints
+    # Can be applied to make a set of routes visible only to users that are
+    # signed out.
+    #
+    #     # config/routes.rb
+    #     constraints Clearance::Constraints::SignedOut.new do
+    #       resources :registrations, only: [:new, :create]
+    #     end
+    #
+    # In the example above, requests to `/registrations/new` from users that are
+    # signed in will result in a 404.
     class SignedOut
       def matches?(request)
         @request = request
@@ -8,10 +18,12 @@ module Clearance
 
       private
 
+      # @api private
       def clearance_session
         @request.env[:clearance]
       end
 
+      # @api private
       def missing_session?
         clearance_session.nil?
       end

data/lib/clearance/constraints.rb

@@ -1,2 +1,14 @@
 require 'clearance/constraints/signed_in'
 require 'clearance/constraints/signed_out'
+
+module Clearance
+  # Clearance provides Rails routing constraints that can control access and the
+  # visibility of routes at the routing layer. The {Constraints::SignedIn}
+  # constraint can be used to make routes visible only to signed in users. The
+  # {Constraints::SignedOut} constraint can be used to make routes visible only
+  # to signed out users.
+  #
+  # @see http://guides.rubyonrails.org/routing.html#advanced-constraints
+  module Constraints
+  end
+end

data/lib/clearance/controller.rb

@@ -2,6 +2,19 @@ require 'clearance/authentication'
 require 'clearance/authorization'
 
 module Clearance
+  # Adds clearance controller helpers to the controller it is mixed into.
+  #
+  # This exposes clearance controller and helper methods such as `current_user`.
+  # See {Authentication} and {Authorization} documentation for complete
+  # documentation on the methods.
+  #
+  # The `clearance:install` generator automatically adds this mixin to
+  # `ApplicationController`, which is the recommended configuration.
+  #
+  #     class ApplicationController < ActionController::Base
+  #       include Clearance::Controller
+  #     end
+  #
   module Controller
     extend ActiveSupport::Concern
 

data/lib/clearance/default_sign_in_guard.rb

@@ -1,5 +1,14 @@
 module Clearance
+  # Runs as the base {SignInGuard} for all requests, regardless of configured
+  # {Configuration#sign_in_guards}.
   class DefaultSignInGuard < SignInGuard
+    # Runs the default sign in guard.
+    #
+    # If there is a value set in the clearance session object, then the guard
+    # returns {SuccessStatus}. Otherwise, it returns {FailureStatus} with the
+    # message returned by {#default_failure_message}.
+    #
+    # @return [SuccessStatus, FailureStatus]
     def call
       if session.signed_in?
         success
@@ -8,6 +17,14 @@ module Clearance
       end
     end
 
+    # The default failure message pulled from the i18n framework.
+    #
+    # Will use the value returned from the following i18n keys, in this order:
+    #
+    # * `clearance.controllers.sessions.bad_email_or_password`
+    # * `flashes.failure_after_create`
+    #
+    # @return [String]
     def default_failure_message
       I18n.t(
         :bad_email_or_password,

data/lib/clearance/engine.rb

@@ -1,16 +1,29 @@
 require "clearance"
-require "rails"
+require "rails/engine"
 
 module Clearance
+  # Makes Clearance behavior available to Rails apps on initialization. By using
+  # a Rails Engine rather than a Railtie, Clearance can automatically expose its
+  # own routes and views to the hosting application.
+  #
+  # Requiring `clearance` (likely by having it in your `Gemfile`) will
+  # automatically require the engine. You can opt-out of Clearance's internal
+  # routes by using {Configuration#routes=}. You can override the Clearance
+  # views by running `rails generate clearance:views`.
+  #
+  # In addition to providing routes and views, the Clearance engine:
+  #
+  # * Ensures `password` and `token` parameters are filtered out of Rails logs.
+  # * Mounts the {RackSession} middleware in the appropriate location
+  # * Reloads classes referenced in your {Configuration} on every request in
+  #   development mode.
+  #
   class Engine < Rails::Engine
     initializer "clearance.filter" do |app|
       app.config.filter_parameters += [:password, :token]
     end
 
-    config.app_middleware.insert_after(
-      ActionDispatch::ParamsParser,
-      Clearance::RackSession
-    )
+    config.app_middleware.use(Clearance::RackSession)
 
     config.to_prepare do
       Clearance.configuration.reload_user_model

data/lib/clearance/password_strategies/bcrypt.rb

@@ -1,10 +1,14 @@
 module Clearance
   module PasswordStrategies
+    # Uses BCrypt to authenticate users and store encrypted passwords.
+    #
+    # The BCrypt cost (the measure of how many key expansion iterations BCrypt
+    # will perform) is automatically set to the minimum allowed value when
+    # Rails is operating in the test environment and the default cost in all
+    # other envionments. This provides a speed boost in tests.
     module BCrypt
       require 'bcrypt'
 
-      extend ActiveSupport::Concern
-
       def authenticated?(password)
         if encrypted_password.present?
           ::BCrypt::Password.new(encrypted_password) == password
@@ -15,27 +19,18 @@ module Clearance
         @password = new_password
 
         if new_password.present?
-          self.encrypted_password = encrypt(new_password)
+          cost = if defined?(::Rails) && ::Rails.env.test?
+                   ::BCrypt::Engine::MIN_COST
+                 else
+                   ::BCrypt::Engine::DEFAULT_COST
+                 end
+
+          self.encrypted_password = ::BCrypt::Password.create(
+            new_password,
+            cost: cost,
+          )
         end
       end
-
-      private
-
-      def encrypt(password)
-        ::BCrypt::Password.create(password, cost: cost)
-      end
-
-      def cost
-        if test_environment?
-          ::BCrypt::Engine::MIN_COST
-        else
-          ::BCrypt::Engine::DEFAULT_COST
-        end
-      end
-
-      def test_environment?
-        defined?(::Rails) && ::Rails.env.test?
-      end
     end
   end
 end