clearance 1.8.0 → 1.13.0

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?
             '/'
           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

data/lib/clearance/user.rb

@@ -3,6 +3,102 @@ require 'email_validator'
 require 'clearance/token'
 
 module Clearance
+  # Required to be included in your configued user class, which is `User` by
+  # default, but can be changed with {Configuration#user_model=}.
+  #
+  #     class User
+  #       include Clearance::User
+  #
+  #       # ...
+  #     end
+  #
+  # This will also include methods exposed by your password strategy, which can
+  # be configured with {Configuration#password_strategy=}. By default, this is
+  # {PasswordStrategies::BCrypt}.
+  #
+  # ## Validations
+  #
+  # These validations are added to the class that the {User} module is mixed
+  # into.
+  #
+  # * If {#email_optional?} is false, {#email} is validated for presence,
+  #   uniqueness and email format (using the `email_validator` gem in strict
+  #   mode).
+  # * If {#skip_password_validation?} is false, {#password} is validated
+  #   for presence.
+  #
+  # ## Callbacks
+  #
+  # * {#normalize_email} will be called on `before_validation`
+  # * {#generate_remember_token} will be called on `before_create`
+  #
+  # @!attribute email
+  #   @return [String] The user's email.
+  #
+  # @!attribute encrypted_password
+  #   @return [String] The user's encrypted password.
+  #
+  # @!attribute remember_token
+  #   @return [String] The value used to identify this user in their {Session}
+  #     cookie.
+  #
+  # @!attribute confirmation_token
+  #   @return [String] The value used to identify this user in the password
+  #     reset link.
+  #
+  # @!attribute password_changing
+  #   @return [String] Transient (non-persisted) attribute that is set to
+  #     `true` when {#update_password} is called. This value is read by
+  #     {#skip_password_validation?} to determine if password validations need
+  #     to be run.
+  #
+  # @!attribute [r] password
+  #   @return [String] Transient (non-persisted) attribute that is set when
+  #     updating a user's password. Only the {#encrypted_password} is persisted.
+  #
+  # @!method password=
+  #   Sets the user's encrypted_password by using the configured Password
+  #   Strategy's `password=` method. By default, this will be
+  #   {PasswordStrategies::BCrypt#password=}, but can be changed with
+  #   {Configuration#password_strategy}.
+  #
+  #   @see PasswordStrategies
+  #   @return [void]
+  #
+  # @!method authenticated?
+  #   Check's the provided password against the user's encrypted password using
+  #   the configured password strategy. By default, this will be
+  #   {PasswordStrategies::BCrypt#authenticated?}, but can be changed with
+  #   {Configuration#password_strategy}.
+  #
+  #   @see PasswordStrategies
+  #   @param [String] password
+  #     The password to check.
+  #   @return [Boolean]
+  #     True if the password provided is correct for the user.
+  #
+  # @!method self.authenticate
+  #   Finds the user with the given email and authenticates them with the
+  #   provided password. If the email corresponds to a user and the provided
+  #   password is correct for that user, this method will return that user.
+  #   Otherwise it will return nil.
+  #
+  #   @return [User, nil]
+  #
+  # @!method self.find_by_normalized_email
+  #   Finds the user with the given email. The email with be normalized via
+  #   {#normalize_email}.
+  #
+  #   @return [User, nil]
+  #
+  # @!method self.normalize_email
+  #   Normalizes the provided email by downcasing and removing all spaces.
+  #   This is used by {find_by_normalized_email} and is also called when
+  #   validating a user to ensure only normalized emails are stored in the
+  #   database.
+  #
+  #   @return [String]
+  #
   module User
     extend ActiveSupport::Concern
 
@@ -15,6 +111,7 @@ module Clearance
       include password_strategy
     end
 
+    # @api private
     module ClassMethods
       def authenticate(email, password)
         if user = find_by_normalized_email(email)
@@ -39,6 +136,7 @@ module Clearance
       end
     end
 
+    # @api private
     module Validations
       extend ActiveSupport::Concern
 
@@ -53,6 +151,7 @@ module Clearance
       end
     end
 
+    # @api private
     module Callbacks
       extend ActiveSupport::Concern
 
@@ -62,16 +161,47 @@ module Clearance
       end
     end
 
+    # Generates a {#confirmation_token} for the user, which allows them to reset
+    # their password via an email link.
+    #
+    # Calling `forgot_password!` will cause the user model to be saved without
+    # validations. Any other changes you made to this user instance will also
+    # be persisted, without validation. It is inteded to be called on an
+    # instance with no changes (`dirty? == false`).
+    #
+    # @return [Boolean] Was the save successful?
     def forgot_password!
       generate_confirmation_token
       save validate: false
     end
 
+    # Generates a new {#remember_token} for the user, which will have the effect
+    # of signing all of the user's current sessions out. This is called
+    # internally by {Session#sign_out}.
+    #
+    # Calling `reset_remember_token!` will cause the user model to be saved
+    # without validations. Any other changes you made to this user instance will
+    # also be persisted, without validation. It is inteded to be called on an
+    # instance with no changes (`dirty? == false`).
+    #
+    # @return [Boolean] Was the save successful?
     def reset_remember_token!
       generate_remember_token
       save validate: false
     end
 
+    # Sets the user's password to the new value, using the `password=` method on
+    # the configured password strategy. By default, this is
+    # {PasswordStrategies::BCrypt#password=}.
+    #
+    # This also has the side-effect of blanking the {#confirmation_token} and
+    # rotating the `#remember_token`.
+    #
+    # Validations will be run as part of this update. If the user instance is
+    # not valid, the password change will not be persisted, and this method will
+    # return `false`.
+    #
+    # @return [Boolean] Was the save successful?
     def update_password(new_password)
       self.password_changing = true
       self.password = new_password
@@ -86,28 +216,57 @@ module Clearance
 
     private
 
+    # Sets the email on this instance to the value returned by
+    # {.normalize_email}
+    #
+    # @return [String]
     def normalize_email
       self.email = self.class.normalize_email(email)
     end
 
+    # Always false. Override this method in your user model to allow for other
+    # forms of user authentication (username, Facebook, etc).
+    #
+    # @return [false]
     def email_optional?
       false
     end
 
+    # Always false. Override this method in your user model to allow for other
+    # forms of user authentication (username, Facebook, etc).
+    #
+    # @return [false]
     def password_optional?
       false
     end
 
+    # True if {#password_optional?} is true or if the user already has an
+    # {#encrypted_password} that is not changing.
+    #
+    # @return [Boolean]
     def skip_password_validation?
       password_optional? || (encrypted_password.present? && !password_changing)
     end
 
+    # Sets the {#confirmation_token} on the instance to a new value generated by
+    # {Token.new}. The change is not automatically persisted. If you would like
+    # to generate and save in a single method call, use {#forgot_password!}.
+    #
+    # @return [String] The new confirmation token
     def generate_confirmation_token
       self.confirmation_token = Clearance::Token.new
     end
 
+    # Sets the {#remember_token} on the instance to a new value generated by
+    # {Token.new}. The change is not automatically persisted. If you would like
+    # to generate and sace in a single method call, use
+    # {#reset_remember_token!}.
+    #
+    # @return [String] The new remember token
     def generate_remember_token
       self.remember_token = Clearance::Token.new
     end
+
+    private_constant :Callbacks, :ClassMethods, :Validations
   end
 end

data/lib/clearance/version.rb

@@ -1,3 +1,3 @@
 module Clearance
-  VERSION = "1.8.0"
+  VERSION = "1.13.0".freeze
 end