clearance 1.10.1 → 1.17.0

data/lib/clearance/password_strategies/bcrypt_migration_from_sha1.rb

@@ -1,5 +1,6 @@
 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 " \
@@ -8,6 +9,7 @@ module Clearance
         "strategy, add clearance-deprecated_password_strategies to your " \
         "Gemfile."
 
+      # @api private
       class BCryptUser
         include Clearance::PasswordStrategies::BCrypt
 
@@ -18,6 +20,7 @@ module Clearance
         delegate :encrypted_password, :encrypted_password=, to: :@user
       end
 
+      # @api private
       class SHA1User
         include Clearance::PasswordStrategies::SHA1
 
@@ -28,11 +31,15 @@ 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
@@ -41,6 +48,7 @@ module Clearance
 
       private
 
+      # @api private
       def authenticated_with_bcrypt?(password)
         begin
           BCryptUser.new(self).authenticated? password
@@ -49,6 +57,7 @@ module Clearance
         end
       end
 
+      # @api private
       def authenticated_with_sha1?(password)
         if sha1_password?
           if SHA1User.new(self).authenticated? password
@@ -59,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,6 +3,7 @@ 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 " \
@@ -10,11 +11,15 @@ module Clearance
         "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
@@ -27,23 +32,27 @@ 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)
+        cipher.key = Digest::SHA256.digest(salt).first(16)
         hash = cipher.update(string) << cipher.final
         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,5 +1,6 @@
 module Clearance
   module PasswordStrategies
+    # @deprecated Use {BCrypt} or `clearance-deprecated_password_strategies` gem
     module SHA1
       require 'digest/sha1'
 
@@ -11,11 +12,15 @@ module Clearance
 
       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
@@ -28,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

data/lib/clearance/password_strategies.rb

@@ -1,4 +1,17 @@
 module Clearance
+  # Control how users are authenticated and how passwords are stored.
+  #
+  # The default password strategy is {Clearance::PasswordStrategies::BCrypt},
+  # but this can be overridden in {Clearance::Configuration}.
+  #
+  # You can supply your own password strategy by implementing a module that
+  # responds to the proper interface methods. Once this module is configured as
+  # your password strategy, Clearance will mix it into your Clearance User
+  # class. Thus, your module can access any methods or attributes on User.
+  #
+  # Password strategies need to respond to `authenticated?(password)` and
+  # `password=(new_password)`. For an example of how to implement these methods,
+  # see {Clearance::PasswordStrategies::BCrypt}.
   module PasswordStrategies
     autoload :BCrypt, 'clearance/password_strategies/bcrypt'
     autoload :BCryptMigrationFromSHA1,

data/lib/clearance/rack_session.rb

@@ -1,9 +1,22 @@
 module Clearance
+  # Rack middleware that manages the Clearance {Session}. This middleware is
+  # automatically mounted by the Clearance {Engine}.
+  #
+  # * maintains the session cookie specified by your {Configuration}.
+  # * exposes previously cookied sessions to Clearance and your app at
+  #   `request.env[:clearance]`, which {Authentication#current_user} pulls the
+  #   user from.
+  #
+  # @see Session
+  # @see Configuration#cookie_name
+  #
   class RackSession
     def initialize(app)
       @app = app
     end
 
+    # Reads previously existing sessions from a cookie and maintains the cookie
+    # on each response.
     def call(env)
       session = Clearance::Session.new(env)
       env[:clearance] = session

data/lib/clearance/rspec.rb

@@ -1,8 +1,19 @@
-require 'rspec/rails'
-require 'clearance/testing/deny_access_matcher'
-require 'clearance/testing/helpers'
+require "rspec/rails"
+require "clearance/testing/deny_access_matcher"
+require "clearance/testing/controller_helpers"
+require "clearance/testing/view_helpers"
 
 RSpec.configure do |config|
   config.include Clearance::Testing::Matchers, type: :controller
-  config.include Clearance::Testing::Helpers, type: :controller
+  config.include Clearance::Testing::ControllerHelpers, type: :controller
+  config.include Clearance::Testing::ViewHelpers, type: :view
+  config.include Clearance::Testing::ViewHelpers, type: :helper
+
+  config.before(:each, type: :view) do
+    view.extend Clearance::Testing::ViewHelpers::CurrentUser
+  end
+
+  config.before(:each, type: :helper) do
+    view.extend Clearance::Testing::ViewHelpers::CurrentUser
+  end
 end

data/lib/clearance/session.rb

@@ -1,23 +1,34 @@
 require 'clearance/default_sign_in_guard'
 
 module Clearance
+  # Represents a clearance session, ultimately persisted in
+  # `request.env[:clearance]` by {RackSession}.
   class Session
+    # @param env The current rack environment
     def initialize(env)
       @env = env
       @current_user = nil
       @cookies = nil
     end
 
+    # Called by {RackSession} to add the Clearance session cookie to a response.
+    #
+    # @return [void]
     def add_cookie_to_headers(headers)
-      if cookie_value[:value].present?
+      if signed_in_with_remember_token?
         Rack::Utils.set_cookie_header!(
           headers,
           remember_token_cookie,
-          cookie_value
+          cookie_options.merge(
+            value: current_user.remember_token,
+          ),
         )
       end
     end
 
+    # The current user represented by this session.
+    #
+    # @return [User, nil]
     def current_user
       if remember_token.present?
         @current_user ||= user_from_remember_token(remember_token)
@@ -26,12 +37,28 @@ module Clearance
       @current_user
     end
 
+    # Sign the provided user in, if approved by the configured sign in guards.
+    # If the sign in guard stack returns {SuccessStatus}, the {#current_user}
+    # will be set and then remember token cookie will be set to the user's
+    # remember token. If the stack returns {FailureStatus}, {#current_user} will
+    # be nil.
+    #
+    # In either event, the resulting status will be yielded to a provided block,
+    # if provided. See {SessionsController#create} for an example of how this
+    # can be used.
+    #
+    # @param [User] user
+    # @yieldparam [SuccessStatus,FailureStatus] status Result of the sign in
+    #   operation.
+    # @return [void]
     def sign_in(user, &block)
       @current_user = user
       status = run_sign_in_stack
 
       if status.success?
-        cookies[remember_token_cookie] = user && user.remember_token
+        # Sign in succeeded, and when {RackSession} is run and calls
+        # {#add_cookie_to_headers} it will set the cookie with the
+        # remember_token for the current_user
       else
         @current_user = nil
       end
@@ -41,6 +68,13 @@ module Clearance
       end
     end
 
+    # Invalidates the users remember token and removes the remember token cookie
+    # from the store. The invalidation of the remember token causes any other
+    # sessions that are signed in from other locations to also be invalidated on
+    # their next request. This is because all Clearance sessions for a given
+    # user share a remember token.
+    #
+    # @return [void]
     def sign_out
       if signed_in?
         current_user.reset_remember_token!
@@ -50,24 +84,33 @@ module Clearance
       cookies.delete remember_token_cookie
     end
 
+    # True if {#current_user} is set.
+    #
+    # @return [Boolean]
     def signed_in?
       current_user.present?
     end
 
+    # True if {#current_user} is not set
+    #
+    # @return [Boolean]
     def signed_out?
       ! signed_in?
     end
 
     private
 
+    # @api private
     def cookies
-      @cookies ||= @env['action_dispatch.cookies'] || Rack::Request.new(@env).cookies
+      @cookies ||= ActionDispatch::Request.new(@env).cookie_jar
     end
 
+    # @api private
     def remember_token
       cookies[remember_token_cookie]
     end
 
+    # @api private
     def remember_token_expires
       if expires_configuration.arity == 1
         expires_configuration.call(cookies)
@@ -80,23 +123,33 @@ module Clearance
       end
     end
 
+    # @api private
+    def signed_in_with_remember_token?
+      current_user&.remember_token
+    end
+
+    # @api private
     def remember_token_cookie
       Clearance.configuration.cookie_name.freeze
     end
 
+    # @api private
     def expires_configuration
       Clearance.configuration.cookie_expiration
     end
 
+    # @api private
     def user_from_remember_token(token)
       Clearance.configuration.user_model.where(remember_token: token).first
     end
 
+    # @api private
     def run_sign_in_stack
       @stack ||= initialize_sign_in_guard_stack
       @stack.call
     end
 
+    # @api private
     def initialize_sign_in_guard_stack
       default_guard = DefaultSignInGuard.new(self)
       guards = Clearance.configuration.sign_in_guards
@@ -106,20 +159,16 @@ module Clearance
       end
     end
 
-    def cookie_value
-      value = {
+    # @api private
+    def cookie_options
+      {
+        domain: Clearance.configuration.cookie_domain,
         expires: remember_token_expires,
         httponly: Clearance.configuration.httponly,
         path: Clearance.configuration.cookie_path,
         secure: Clearance.configuration.secure_cookie,
-        value: remember_token
+        value: remember_token,
       }
-
-      if Clearance.configuration.cookie_domain.present?
-        value[:domain] = Clearance.configuration.cookie_domain
-      end
-
-      value
     end
   end
 end

data/lib/clearance/session_status.rb

@@ -1,17 +1,24 @@
 module Clearance
+  # Indicates a user was successfully signed in, passing all {SignInGuard}s.
   class SuccessStatus
+    # Is true, indicating that the sign in was successful.
     def success?
       true
     end
   end
 
+  # Indicates a failure in the {SignInGuard} stack which prevented successful
+  # sign in.
   class FailureStatus
+    # The reason the sign in failed.
     attr_reader :failure_message
 
+    # @param [String] failure_message The reason the sign in failed.
     def initialize(failure_message)
       @failure_message = failure_message
     end
 
+    # Is false, indicating that the sign in was unsuccessful.
     def success?
       false
     end

data/lib/clearance/sign_in_guard.rb

@@ -1,20 +1,83 @@
 require 'clearance/session_status'
 
 module Clearance
+  # The base class for {DefaultSignInGuard} and all custom sign in guards.
+  #
+  # Sign in guards provide you with fine-grained control over the process of
+  # signing in a user. Each guard is run in order and can do one of the
+  # following:
+  #
+  # * Fail the sign in process
+  # * Call the next guard in the stack
+  # * Short circuit all remaining guards, declaring sign in successfull.
+  #
+  # Sign In Guards could be used, for instance, to require that a user confirm
+  # their email address before being allowed to sign in.
+  #
+  #     # in config/initializers/clearance.rb
+  #     Clearance.configure do |config|
+  #       config.sign_in_guards = [ConfirmationGuard]
+  #     end
+  #
+  #     # in lib/guards/confirmation_guard.rb
+  #     class ConfirmationGuard < Clearance::SignInGuard
+  #       def call
+  #         if signed_in? && current_user.email_confirmed?
+  #           next_guard
+  #         else
+  #           failure("You must confirm your email address.")
+  #         end
+  #       end
+  #     end
+  #
+  # Calling `success` or `failure` in any guard short circuits all of the
+  # remaining guards in the stack. In most cases, you will want to either call
+  # `failure` or `next_guard`. The {DefaultSignInGuard} will always be the final
+  # guard called and will handle calling `success` if appropriate.
+  #
+  # The stack is designed such that calling `call` will eventually return
+  # {SuccessStatus} or {FailureStatus}, thus halting the chain.
   class SignInGuard
+    # Creates an instance of a sign in guard.
+    #
+    # This is called by {Session} automatically using the array of guards
+    # configured in {Configuration#sign_in_guards} and the {DefaultSignInGuard}.
+    # There is no reason for users of Clearance to concern themselves with the
+    # initialization of each guard or the stack as a whole.
+    #
+    # @param [Session] session The current clearance session
+    # @param [[SignInGuard]] stack The sign in guards that come after this
+    #   guard in the stack
     def initialize(session, stack = [])
       @session = session
       @stack = stack
     end
 
+    # Indicates the entire sign in operation is successful and that no further
+    # guards should be run.
+    #
+    # In most cases your guards will want to delegate this responsibility to the
+    # {DefaultSignInGuard}, allowing the entire stack to execute. In that case,
+    # your custom guard would likely want to call `next_guard` instead.
+    #
+    # @return [SuccessStatus]
     def success
       SuccessStatus.new
     end
 
+    # Indicates this guard failed, and the entire sign in process should fail as
+    # a result.
+    #
+    # @param [String] message The reason the guard failed.
+    # @return [FailureStatus]
     def failure(message)
       FailureStatus.new(message)
     end
 
+    # Passes off responsibility for determining success or failure to the next
+    # guard in the stack.
+    #
+    # @return [SuccessStatus, FailureStatus]
     def next_guard
       stack.call
     end
@@ -23,10 +86,12 @@ module Clearance
 
     attr_reader :stack, :session
 
+    # True if there is a currently a user stored in the clearance environment.
     def signed_in?
       session.signed_in?
     end
 
+    # The user currently stored in the clearance environment.
     def current_user
       session.current_user
     end

data/lib/clearance/test_unit.rb

@@ -1,8 +1,8 @@
-require 'clearance/testing/deny_access_matcher'
-require 'clearance/testing/helpers'
+require "clearance/testing/deny_access_matcher"
+require "clearance/testing/controller_helpers"
 
 ActionController::TestCase.extend Clearance::Testing::Matchers
 
 class ActionController::TestCase
-  include Clearance::Testing::Helpers
+  include Clearance::Testing::ControllerHelpers
 end

data/lib/clearance/testing/controller_helpers.rb

@@ -0,0 +1,57 @@
+module Clearance
+  module Testing
+    # Provides helpers to your controller specs.
+    # These are typically used in tests by requiring `clearance/rspec` or
+    # `clearance/test_unit` as appropriate in your `rails_helper.rb` or
+    # `test_helper.rb` files.
+    module ControllerHelpers
+      # @api private
+      def setup_controller_request_and_response
+        super
+        @request.env[:clearance] = Clearance::Session.new(@request.env)
+      end
+
+      # Signs in a user that is created using FactoryGirl.
+      # The factory name is derrived from your `user_class` Clearance
+      # configuration.
+      #
+      # @raise [RuntimeError] if FactoryGirl is not defined.
+      def sign_in
+        constructor = factory_module("sign_in")
+
+        factory = Clearance.configuration.user_model.to_s.underscore.to_sym
+        sign_in_as constructor.create(factory)
+      end
+
+      # Signs in the provided user.
+      #
+      # @return user
+      def sign_in_as(user)
+        @request.env[:clearance].sign_in(user)
+        user
+      end
+
+      # Signs out a user that may be signed in.
+      #
+      # @return [void]
+      def sign_out
+        @request.env[:clearance].sign_out
+      end
+
+      # Determines the appropriate factory library
+      #
+      # @api private
+      # @raise [RuntimeError] if both FactoryGirl and FactoryBot are not
+      #   defined.
+      def factory_module(provider)
+        if defined?(FactoryBot)
+          FactoryBot
+        elsif defined?(FactoryGirl)
+          FactoryGirl
+        else
+          raise("Clearance's `#{provider}` helper requires factory_bot")
+        end
+      end
+    end
+  end
+end

data/lib/clearance/testing/deny_access_matcher.rb

@@ -1,10 +1,40 @@
 module Clearance
   module Testing
+    # Provides matchers to be used in your controller specs.
+    # These are typically exposed to your controller specs by
+    # requiring `clearance/rspec` or `clearance/test_unit` as
+    # appropriate in your `rails_helper.rb` or `test_helper.rb`
+    # files.
     module Matchers
+      # The `deny_access` matcher is used to assert that a
+      #   request is denied access by clearance.
+      # @option opts [String] :flash The expected flash notice message. Defaults
+      #   to nil, which means the flash will not be checked.
+      # @option opts [String] :redirect The expected redirect url. Defaults to
+      #   `'/'` if signed in or the `sign_in_url` if signed out.
+      #
+      #       class PostsController < ActionController::Base
+      #         before_action :require_login
+      #
+      #         def index
+      #           @posts = Post.all
+      #         end
+      #       end
+      #
+      #       describe PostsController do
+      #         describe "#index" do
+      #           it "denies access to users not signed in" do
+      #             get :index
+      #
+      #             expect(controller).to deny_access
+      #           end
+      #         end
+      #       end
       def deny_access(opts = {})
         DenyAccessMatcher.new(self, opts)
       end
 
+      # @api private
       class DenyAccessMatcher
         attr_reader :failure_message, :failure_message_when_negated
 
@@ -37,13 +67,17 @@ module Clearance
         private
 
         def denied_access_url
-          if @controller.signed_in?
-            '/'
+          if clearance_session.signed_in?
+            Clearance.configuration.redirect_url
           else
             @controller.sign_in_url
           end
         end
 
+        def clearance_session
+          @controller.request.env[:clearance]
+        end
+
         def flash_notice
           @controller.flash[:notice]
         end