clearance 1.11.0 → 1.12.0

data/lib/clearance/back_door.rb

@@ -29,6 +29,7 @@ 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']

data/lib/clearance/configuration.rb

@@ -138,7 +138,8 @@ 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

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/constraints/signed_in.rb

@@ -29,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

@@ -18,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/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 < ApplicationController
+  #       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

@@ -2,6 +2,22 @@ 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|
       app.config.filter_parameters += [:password, :token]

data/lib/clearance/password_strategies/bcrypt.rb

@@ -9,8 +9,6 @@ module Clearance
     module BCrypt
       require 'bcrypt'
 
-      extend ActiveSupport::Concern
-
       def authenticated?(password)
         if encrypted_password.present?
           ::BCrypt::Password.new(encrypted_password) == password
@@ -27,10 +25,12 @@ module Clearance
 
       private
 
+      # @api private
       def encrypt(password)
         ::BCrypt::Password.create(password, cost: cost)
       end
 
+      # @api private
       def cost
         if test_environment?
           ::BCrypt::Engine::MIN_COST
@@ -39,6 +39,7 @@ module Clearance
         end
       end
 
+      # @api private
       def test_environment?
         defined?(::Rails) && ::Rails.env.test?
       end

data/lib/clearance/password_strategies/bcrypt_migration_from_sha1.rb

@@ -9,6 +9,7 @@ module Clearance
         "strategy, add clearance-deprecated_password_strategies to your " \
         "Gemfile."
 
+      # @api private
       class BCryptUser
         include Clearance::PasswordStrategies::BCrypt
 
@@ -19,6 +20,7 @@ module Clearance
         delegate :encrypted_password, :encrypted_password=, to: :@user
       end
 
+      # @api private
       class SHA1User
         include Clearance::PasswordStrategies::SHA1
 
@@ -29,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
@@ -42,6 +48,7 @@ module Clearance
 
       private
 
+      # @api private
       def authenticated_with_bcrypt?(password)
         begin
           BCryptUser.new(self).authenticated? password
@@ -50,6 +57,7 @@ module Clearance
         end
       end
 
+      # @api private
       def authenticated_with_sha1?(password)
         if sha1_password?
           if SHA1User.new(self).authenticated? password
@@ -60,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

@@ -11,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
@@ -28,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)
@@ -39,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

@@ -12,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
@@ -29,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/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/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 ||= 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,