clearance 1.8.0 → 1.16.0

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,13 +1,19 @@
 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?
         Rack::Utils.set_cookie_header!(
@@ -18,6 +24,9 @@ module Clearance
       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,6 +35,20 @@ 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
@@ -41,6 +64,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 +80,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 +119,28 @@ module Clearance
       end
     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,6 +150,7 @@ module Clearance
       end
     end
 
+    # @api private
     def cookie_value
       value = {
         expires: remember_token_expires,

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,44 @@
+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
+        unless defined?(FactoryGirl)
+          raise("Clearance's `sign_in` helper requires factory_girl")
+        end
+
+        factory = Clearance.configuration.user_model.to_s.underscore.to_sym
+        sign_in_as FactoryGirl.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
+    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

data/lib/clearance/testing/helpers.rb

@@ -1,31 +1,15 @@
+require "clerance/testing/controller_helpers"
+
 module Clearance
   module Testing
+    # @deprecated Use Clearance::Testing::ControllerHelpers
     module Helpers
-      def setup_controller_request_and_response
-        super
-        @request.env[:clearance] = Clearance::Session.new(@request.env)
-      end
-
-      def sign_in
-        unless defined?(FactoryGirl)
-          raise(
-            RuntimeError,
-            "Clearance's `sign_in` helper requires factory_girl"
-          )
-        end
-
-        factory = Clearance.configuration.user_model.to_s.underscore.to_sym
-        sign_in_as FactoryGirl.create(factory)
-      end
-
-      def sign_in_as(user)
-        @controller.sign_in user
-        user
-      end
-
-      def sign_out
-        @controller.sign_out
-      end
+      warn(
+        "#{Kernel.caller.first} [DEPRECATION] Clearance::Testing::Helpers is "\
+        "deprecated and has been replaced with " \
+        "Clearance::Testing::ControllerHelpers. Require " \
+        "clearance/testing/controller_helpers instead."
+      )
     end
   end
 end

data/lib/clearance/testing/view_helpers.rb

@@ -0,0 +1,32 @@
+module Clearance
+  module Testing
+    # Provides helpers to your view and helper specs.
+    # Using these helpers makes `current_user`, `signed_in?` and `signed_out?`
+    # behave properly in view and helper specs.
+    module ViewHelpers
+      # Sets current_user on the view under test to a new instance of your user
+      # model.
+      def sign_in
+        view.current_user = Clearance.configuration.user_model.new
+      end
+
+      # Sets current_user on the view under test to the supplied user.
+      def sign_in_as(user)
+        view.current_user = user
+      end
+
+      # @api private
+      module CurrentUser
+        attr_accessor :current_user
+
+        def signed_in?
+          current_user.present?
+        end
+
+        def signed_out?
+          !signed_in?
+        end
+      end
+    end
+  end
+end

data/lib/clearance/token.rb

@@ -1,5 +1,12 @@
 module Clearance
+  # Random token used for password reset and remember tokens.
+  # Clearance tokens are also public API and are inteded to be used anywhere you
+  # need a random token to correspond to a given user (e.g. you added an email
+  # confirmation token).
   class Token
+    # Generate a new random, 20 byte hex token.
+    #
+    # @return [String]
     def self.new
       SecureRandom.hex(20).encode('UTF-8')
     end