clearance 1.8.0 → 1.16.0

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,24 @@ 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)
       @app = app
+      @block = block
     end
 
     def call(env)
@@ -29,14 +42,24 @@ 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
   end
 end

data/lib/clearance/configuration.rb

@@ -1,29 +1,106 @@
 module Clearance
   class Configuration
-    attr_writer :allow_sign_up, :routes
-
-    attr_accessor \
-      :cookie_domain,
-      :cookie_expiration,
-      :cookie_name,
-      :cookie_path,
-      :httponly,
-      :mailer_sender,
-      :password_strategy,
-      :redirect_url,
-      :secure_cookie,
-      :sign_in_guards,
-      :user_model
+    # Controls whether the sign up route is enabled.
+    # Defaults to `true`. Set to `false` to disable user creation routes.
+    # The setting is ignored if routes are disabled.
+    # @param [Boolean] value
+    # @return [Boolean]
+    attr_writer :allow_sign_up
+
+    # The domain to use for the clearance remember token cookie.
+    # Defaults to `nil`, which causes the cookie domain to default to the
+    # domain of the request. For more, see
+    # [RFC6265](http://tools.ietf.org/html/rfc6265#section-5.2.3).
+    # @return [String]
+    attr_accessor :cookie_domain
+
+    # A lambda called to set the remember token cookie expires attribute.
+    # The lambda accepts the collection of cookies as an argument which
+    # allows for changing the expiration according to those cookies.
+    # This could be used, for example, to set a session cookie unless
+    # a `remember_me` cookie was also present. By default, cookie expiration
+    # is one year. For more on cookie expiration see
+    # [RFC6265](http://tools.ietf.org/html/rfc6265#section-5.2.1).
+    # @return [Lambda]
+    attr_accessor :cookie_expiration
+
+    # The name of Clearance's remember token cookie.
+    # Defaults to `remember_token`.
+    # @return [String]
+    attr_accessor :cookie_name
+
+    # Controls which paths the remember token cookie is valid for.
+    # Defaults to `"/"` for the entire domain. For more, see
+    # [RFC6265](http://tools.ietf.org/html/rfc6265#section-5.1.4).
+    # @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
+    # available to JavaScript. For more see
+    # [RFC6265](http://tools.ietf.org/html/rfc6265#section-5.2.6).
+    # @return [Boolean]
+    attr_accessor :httponly
+
+    # Controls the address the password reset email is sent from.
+    # Defaults to reply@example.com.
+    # @return [String]
+    attr_accessor :mailer_sender
+
+    # The password strategy to use when authenticating and setting passwords.
+    # Defaults to {Clearance::PasswordStrategies::BCrypt}.
+    # @return [Module #authenticated? #password=]
+    attr_accessor :password_strategy
+
+    # The default path Clearance will redirect signed in users to.
+    # Defaults to `"/"`. This can often be overridden for specific scenarios by
+    # overriding controller methods that rely on it.
+    # @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
+    # `rails generate clearance:routes`.
+    # @return [Boolean]
+    attr_writer :routes
+
+    # Controls the secure setting on the remember token cookie.
+    # Defaults to `false`. When set, the browser will only send the
+    # cookie to the server over HTTPS. You should set this value to true in
+    # live environments to prevent session hijacking. For more, see
+    # [RFC6265](http://tools.ietf.org/html/rfc6265#section-5.2.5).
+    # @return [Boolean]
+    attr_accessor :secure_cookie
+
+    # The array of sign in guards to run when signing a user in.
+    # Defaults to an empty array. Sign in guards respond to `call` and are
+    # initialized with a session and the current stack. Each guard can decide
+    # to fail the sign in, yield to the next guard, or allow the sign in.
+    # @return [Array<#call>]
+    attr_accessor :sign_in_guards
+
+    # The ActiveRecord class that represents users in your application.
+    # Defualts to `::User`.
+    # @return [ActiveRecord::Base]
+    attr_accessor :user_model
 
     def initialize
       @allow_sign_up = true
       @cookie_expiration = ->(cookies) { 1.year.from_now.utc }
+      @cookie_domain = nil
       @cookie_path = '/'
       @cookie_name = "remember_token"
       @httponly = false
       @mailer_sender = 'reply@example.com'
       @redirect_url = '/'
       @routes = true
+      @rotate_csrf_on_sign_in = nil
       @secure_cookie = false
       @sign_in_guards = []
     end
@@ -32,10 +109,16 @@ module Clearance
       @user_model ||= ::User
     end
 
+    # Is the user sign up route enabled?
+    # @return [Boolean]
     def allow_sign_up?
       @allow_sign_up
     end
 
+    # Specifies which controller actions are allowed for user resources.
+    # This will be `[:create]` is `allow_sign_up` is true (the default), and
+    # empty otherwise.
+    # @return [Array<Symbol>]
     def  user_actions
       if allow_sign_up?
         [:create]
@@ -44,23 +127,77 @@ 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?
     def routes_enabled?
       @routes
     end
+
+    # Reloads the clearance user model class.
+    # 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.
+    #
+    # @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` configration 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
+          inializer.
+
+          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
   def self.configuration
     @configuration ||= Configuration.new
   end
 
+  # Set Clearance's configuration
+  # @param config [Clearance::Configuration]
   def self.configuration=(config)
     @configuration = config
   end
 
+  # Modify Clearance's current configuration
+  # @yieldparam [Clearance::Configuration] config current Clearance config
+  # ```
+  # Clearance.configure do |config|
+  #   config.routes = false
+  # end
+  # ```
   def self.configure
     yield configuration
   end

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,12 +1,32 @@
-require 'clearance'
-require 'rails'
+require "clearance"
+require "rails"
 
 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|
+    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
+    end
   end
 end

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

data/lib/clearance/password_strategies/bcrypt_migration_from_sha1.rb

@@ -1,6 +1,15 @@
 module Clearance
   module PasswordStrategies
+    # @deprecated Use {BCrypt} or `clearance-deprecated_password_strategies` gem
     module BCryptMigrationFromSHA1
+      DEPRECATION_MESSAGE = "[DEPRECATION] The BCryptMigrationFromSha1 " \
+        "password strategy has been deprecated and will be removed from " \
+        "Clearance 2.0. BCrypt is the only officially supported strategy, " \
+        "though you are free to provide your own. To continue using this " \
+        "strategy, add clearance-deprecated_password_strategies to your " \
+        "Gemfile."
+
+      # @api private
       class BCryptUser
         include Clearance::PasswordStrategies::BCrypt
 
@@ -11,6 +20,7 @@ module Clearance
         delegate :encrypted_password, :encrypted_password=, to: :@user
       end
 
+      # @api private
       class SHA1User
         include Clearance::PasswordStrategies::SHA1
 
@@ -21,17 +31,24 @@ module Clearance
         delegate :salt, :salt=, :encrypted_password, :encrypted_password=, to: :@user
       end
 
+      # @deprecated Use {BCrypt} or `clearance-deprecated_password_strategies`
+      #   gem
       def authenticated?(password)
+        warn "#{Kernel.caller.first}: #{DEPRECATION_MESSAGE}"
         authenticated_with_sha1?(password) || authenticated_with_bcrypt?(password)
       end
 
+      # @deprecated Use {BCrypt} or `clearance-deprecated_password_strategies`
+      #   gem
       def password=(new_password)
+        warn "#{Kernel.caller.first}: #{DEPRECATION_MESSAGE}"
         @password = new_password
         BCryptUser.new(self).password = new_password
       end
 
       private
 
+      # @api private
       def authenticated_with_bcrypt?(password)
         begin
           BCryptUser.new(self).authenticated? password
@@ -40,6 +57,7 @@ module Clearance
         end
       end
 
+      # @api private
       def authenticated_with_sha1?(password)
         if sha1_password?
           if SHA1User.new(self).authenticated? password
@@ -50,6 +68,7 @@ module Clearance
         end
       end
 
+      # @api private
       def sha1_password?
         self.encrypted_password =~ /^[a-f0-9]{40}$/
       end

data/lib/clearance/password_strategies/blowfish.rb

@@ -3,12 +3,25 @@ require 'base64'
 
 module Clearance
   module PasswordStrategies
+    # @deprecated Use {BCrypt} or `clearance-deprecated_password_strategies` gem
     module Blowfish
+      DEPRECATION_MESSAGE = "[DEPRECATION] The Blowfish password strategy " \
+        "has been deprecated and will be removed from Clearance 2.0. BCrypt " \
+        "is the only officially supported strategy, though you are free to " \
+        "provide your own. To continue using this strategy add " \
+        "clearance-deprecated_password_strategies to your Gemfile."
+
+      # @deprecated Use {BCrypt} or `clearance-deprecated_password_strategies`
+      #   gem
       def authenticated?(password)
+        warn "#{Kernel.caller.first}: #{DEPRECATION_MESSAGE}"
         encrypted_password == encrypt(password)
       end
 
+      # @deprecated Use {BCrypt} or `clearance-deprecated_password_strategies`
+      #   gem
       def password=(new_password)
+        warn "#{Kernel.caller.first}: #{DEPRECATION_MESSAGE}"
         @password = new_password
         initialize_salt_if_necessary
 
@@ -19,10 +32,12 @@ module Clearance
 
       protected
 
+      # @api private
       def encrypt(string)
         generate_hash("--#{salt}--#{string}--")
       end
 
+      # @api private
       def generate_hash(string)
         cipher = OpenSSL::Cipher::Cipher.new('bf-cbc').encrypt
         cipher.key = Digest::SHA256.digest(salt)
@@ -30,12 +45,14 @@ module Clearance
         Base64.encode64(hash).encode('utf-8')
       end
 
+      # @api private
       def initialize_salt_if_necessary
         if salt.blank?
           self.salt = generate_salt
         end
       end
 
+      # @api private
       def generate_salt
         Base64.encode64(SecureRandom.hex(20)).encode('utf-8')
       end

data/lib/clearance/password_strategies/sha1.rb

@@ -1,15 +1,28 @@
 module Clearance
   module PasswordStrategies
+    # @deprecated Use {BCrypt} or `clearance-deprecated_password_strategies` gem
     module SHA1
       require 'digest/sha1'
 
+      DEPRECATION_MESSAGE = "[DEPRECATION] The SHA1 password strategy " \
+        "has been deprecated and will be removed from Clearance 2.0. BCrypt " \
+        "is the only officially supported strategy, though you are free to " \
+        "provide your own. To continue using this strategy add " \
+        "clearance-deprecated_password_strategies to your Gemfile."
+
       extend ActiveSupport::Concern
 
+      # @deprecated Use {BCrypt} or `clearance-deprecated_password_strategies`
+      #   gem
       def authenticated?(password)
+        warn "#{Kernel.caller.first}: #{DEPRECATION_MESSAGE}"
         encrypted_password == encrypt(password)
       end
 
+      # @deprecated Use {BCrypt} or `clearance-deprecated_password_strategies`
+      #   gem
       def password=(new_password)
+        warn "#{Kernel.caller.first}: #{DEPRECATION_MESSAGE}"
         @password = new_password
         initialize_salt_if_necessary
 
@@ -20,20 +33,24 @@ module Clearance
 
       private
 
+      # @api private
       def encrypt(string)
         generate_hash "--#{salt}--#{string}--"
       end
 
+      # @api private
       def generate_hash(string)
         Digest::SHA1.hexdigest(string).encode 'UTF-8'
       end
 
+      # @api private
       def initialize_salt_if_necessary
         if salt.blank?
           self.salt = generate_salt
         end
       end
 
+      # @api private
       def generate_salt
         SecureRandom.hex(20).encode('UTF-8')
       end