oath 1.1.0

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/oath.rb

@@ -0,0 +1,132 @@
+require 'warden'
+require "oath/version"
+require "oath/configuration"
+require "oath/services"
+require "oath/controller_helpers"
+require "oath/railtie"
+require "oath/failure_app"
+require "oath/back_door"
+require "oath/warden_setup"
+require "oath/field_map"
+require "oath/param_transformer"
+require "oath/strategies/password_strategy"
+require "active_support/core_ext/module/attribute_accessors"
+
+# Oath is an authentication toolkit designed to allow developers to create their own
+# authentication solutions. If you're interested in a default implementation try
+# {http://github.com/halogenandtoast/oath-generators Oath Generators}
+# @since 0.0.15
+module Oath
+  mattr_accessor :warden_config
+  mattr_accessor :config
+
+  module Test
+    autoload :Helpers, "oath/test/helpers"
+    autoload :ControllerHelpers, "oath/test/controller_helpers"
+  end
+
+  # initialize Oath. Sets up warden and the default configuration.
+  #
+  # @note This is used in {Oath::Railtie} in order to bootstrap Oath
+  # @param warden_config [Warden::Config] the configuration from warden
+  # @see Oath::Railtie
+  # @see Oath::Configuration
+  def self.initialize warden_config
+    setup_config
+    setup_warden_config(warden_config)
+  end
+
+  # compares the token (undigested password) to a digested password
+  #
+  # @param digest [String] A digested password
+  # @param token [String] An undigested password
+  # @see Oath::Configuration#default_token_comparison
+  # @return [Boolean] whether the token and digest match
+  def self.compare_token(digest, token)
+    config.token_comparison.call(digest, token)
+  end
+
+  # hashes a token
+  #
+  # @param token [String] the password in undigested form
+  # @see Oath::Configuration#default_hashing_method
+  # @return [String] a digest of the token
+  def self.hash_token(token)
+    config.hashing_method.call(token)
+  end
+
+  # performs transformations on params for signing up and
+  # signing in
+  #
+  # @param params [Hash] hash of parameters to transform
+  # @see Oath::Configuration#param_transofmrations
+  # @return [Hash] hash with transformed parameters
+  def self.transform_params(params)
+    ParamTransformer.new(params, config.param_transformations).to_h
+  end
+
+  # the user class
+  #
+  # @see Oath::Configuration#setup_class_defaults
+  # @deprecated Use Oath.config.user_class instead
+  # @return [Class] the User class
+  def self.user_class
+    warn "#{Kernel.caller.first}: [DEPRECATION] " +
+      'Accessing the user class through the Oath module is deprecated. Use Oath.config.user_class instead.'
+    config.user_class
+  end
+
+  # finds a user based on their credentials
+  #
+  # @param params [Hash] a hash of user parameters
+  # @param field_map [FieldMap] a field map in order to allow multiple lookup fields
+  # @see Oath::Configuration#default_find_method
+  # @return [User] if user is found
+  # @return [nil] if no user is found
+  def self.lookup(params, field_map)
+    if params.present?
+      fields = FieldMap.new(params, field_map).to_fields
+      self.config.find_method.call(fields)
+    end
+  end
+
+  # Puts oath into test mode. This will disable hashing passwords
+  # @note You must call this if you want to use oath in your tests
+  def self.test_mode!
+    Warden.test_mode!
+    self.config ||= Oath::Configuration.new
+    config.hashing_method = ->(password) { password }
+    config.token_comparison = ->(digest, undigested_password) do
+      digest == undigested_password
+    end
+  end
+
+  # Configures oath
+  #
+  # @yield [configuration] Yield the current configuration
+  # @example A custom configuration
+  #   Oath.configure do |config|
+  #     config.user_lookup_field = :username
+  #     config.user_token_store_field = :hashed_password
+  #   end
+  def self.configure(&block)
+    self.config ||= Oath::Configuration.new
+    yield self.config
+  end
+
+  # Resets oath in between tests.
+  # @note You must call this between tests
+  def self.test_reset!
+    Warden.test_reset!
+  end
+
+  private
+
+  def self.setup_config
+    self.config ||= Oath::Configuration.new
+  end
+
+  def self.setup_warden_config(warden_config)
+    self.warden_config = WardenSetup.new(warden_config).call
+  end
+end

data/lib/oath/back_door.rb

@@ -0,0 +1,53 @@
+module Oath
+  # Middleware used in tests to allow users to be signed in directly, without
+  # having to load and submit the sign in form. The user should be provided by
+  # using the key :as in a hash passed to the path.
+  #
+  # @note This should only be used for testing purposes
+  # @since 0.0.15
+  # @example Using the backdoor in an rspec feature spec
+  #   feature "User dashboard" do
+  #     scenario "user visits dashboard" do
+  #       user = create(:user)
+  #       visit dashboard_path(as: user)
+  #       expect(page).to have_css("#dashboard")
+  #     end
+  #   end
+  class BackDoor
+    # Create the a new BackDoor middleware for test purposes
+    # @return [BackDoor]
+    def initialize(app, &block)
+      @app = app
+
+      if block
+        @sign_in_block = block
+      end
+    end
+
+    # Execute the BackDoor middleware signing in the user specified with :as
+    def call(env)
+      sign_in_through_the_back_door(env)
+      @app.call(env)
+    end
+
+    private
+
+    def sign_in_through_the_back_door(env)
+      params = Rack::Utils.parse_query(env['QUERY_STRING'])
+      user_id = params['as']
+
+      if user_id.present?
+        user = find_user(user_id)
+        env["warden"].set_user(user)
+      end
+    end
+
+    def find_user(user_id)
+      if @sign_in_block
+        @sign_in_block.call(user_id)
+      else
+        Oath.config.user_class.find(user_id)
+      end
+    end
+  end
+end

data/lib/oath/configuration.rb

@@ -0,0 +1,149 @@
+module Oath
+  # Configuration options for Oath
+  # @since 0.0.15
+  class Configuration
+    attr_accessor :user_token_field, :user_token_store_field
+    attr_accessor :hashing_method, :token_comparison, :user_lookup_field
+    attr_accessor :sign_in_notice
+    attr_accessor :sign_in_service, :sign_up_service, :sign_out_service
+    attr_accessor :authentication_service, :password_reset_service
+    attr_accessor :failure_app
+    attr_accessor :creation_method, :find_method
+    attr_accessor :no_login_handler, :no_login_redirect
+    attr_accessor :authentication_strategy
+    attr_accessor :warden_serialize_into_session, :warden_serialize_from_session
+    attr_accessor :param_transformations
+
+    attr_writer :user_class
+
+    def initialize
+      setup_class_defaults
+      setup_token_hashing
+      setup_notices
+      setup_services
+      setup_warden
+      setup_param_transformations
+    end
+
+    # Default creation method. Can be overriden via {Oath.configure}
+    #
+    # @see #creation_method=
+    def default_creation_method
+      ->(params) do
+        updated_params = Oath.transform_params(params)
+        Oath.config.user_class.create(updated_params)
+      end
+    end
+
+    # Default hashing method. Can be overriden via {Oath.configure}
+    #
+    # @see #hashing_method=
+    def default_hashing_method
+      ->(token) do
+        if token.present?
+          BCrypt::Password.create(token)
+        else
+          token
+        end
+      end
+    end
+
+    # Default find method. Can be overriden via {Oath.configure}
+    #
+    # @see #find_method=
+    # @see Oath.config.user_class
+    def default_find_method
+      ->(params) do
+        updated_params = Oath.transform_params(params)
+        Oath.config.user_class.find_by(updated_params)
+      end
+    end
+
+    # Default token comparison method. Can be overriden via {Oath.configure}
+    #
+    # @see #token_comparison=
+    def default_token_comparison
+      ->(digest, undigested_token) do
+        BCrypt::Password.new(digest) == undigested_token
+      end
+    end
+
+    # Default handler when user is not logged in. Can be overriden via {Oath.configure}
+    #
+    # @see #no_login_handler=
+    # @see #sign_in_notice
+    # @see #no_login_redirect
+    def default_no_login_handler
+      ->(controller) do
+        notice = Oath.config.sign_in_notice
+
+        if notice.respond_to?(:call)
+          controller.flash.notice = notice.call
+        else
+          warn "[DEPRECATION] `Oath.config.sign_in_notice` should be a lambda instead of a string"
+          controller.flash.notice = notice
+        end
+
+        controller.redirect_to Oath.config.no_login_redirect
+      end
+    end
+
+    # User class. Can be overriden via {Oath.configure}
+    #
+    # @see #user_class=
+    def user_class
+      @user_class.constantize
+    end
+
+    private
+
+    def setup_token_hashing
+      @hashing_method = default_hashing_method
+      @token_comparison = default_token_comparison
+    end
+
+    def setup_notices
+      @sign_in_notice = -> { 'You must be signed in' }
+    end
+
+    def setup_class_defaults
+      @user_class = 'User'
+      @user_token_field = :password
+      @user_token_store_field = :password_digest
+      @user_lookup_field = :email
+      @creation_method = default_creation_method
+      @find_method = default_find_method
+      @no_login_redirect = { controller: '/sessions', action: 'new' }
+      @no_login_handler = default_no_login_handler
+    end
+
+    def setup_services
+      @authentication_service = Oath::Services::Authentication
+      @sign_in_service = Oath::Services::SignIn
+      @sign_up_service = Oath::Services::SignUp
+      @sign_out_service = Oath::Services::SignOut
+      @password_reset_service = Oath::Services::PasswordReset
+    end
+
+    def setup_warden
+      setup_warden_requirements
+      setup_warden_serialization
+    end
+
+    def setup_warden_requirements
+      @failure_app = Oath::FailureApp
+      @authentication_strategy = Oath::Strategies::PasswordStrategy
+    end
+
+    def setup_warden_serialization
+      @warden_serialize_into_session = -> (user) { user.id }
+      @warden_serialize_from_session = -> (id) { Oath.config.user_class.find_by(id: id) }
+    end
+
+    def setup_param_transformations
+      @param_transformations = {
+        "email" => ->(value) { value.downcase }
+      }
+    end
+  end
+end

data/lib/oath/constraints/signed_in.rb

@@ -0,0 +1,14 @@
+module Oath
+  module Constraints
+    # Rails route constraint for signed in users
+    class SignedIn
+      # Checks to see if the constraint is matched by having a user signed in
+      #
+      # @param request [Rack::Request] A rack request
+      def matches?(request)
+        warden = request.env["warden"]
+        warden && warden.authenticated?
+      end
+    end
+  end
+end

data/lib/oath/constraints/signed_out.rb

@@ -0,0 +1,14 @@
+module Oath
+  module Constraints
+    # Rails route constraint for signed out users
+    class SignedOut
+      # Checks to see if the constraint is matched by not having a user signed in
+      #
+      # @param request [Rack::Request] A rack request
+      def matches?(request)
+        warden = request.env["warden"]
+        warden && warden.unauthenticated?
+      end
+    end
+  end
+end

data/lib/oath/controller_helpers.rb

@@ -0,0 +1,161 @@
+require 'bcrypt'
+require 'active_support/concern'
+
+module Oath
+  # Mixin to be included in Rails controllers.
+  # @since 0.0.15
+  module ControllerHelpers
+    extend ActiveSupport::Concern
+    included do
+      if respond_to?(:helper_method)
+        helper_method :current_user, :signed_in?
+      end
+    end
+
+    # Sign in a user
+    #
+    # @note Uses the {Oath::Services::SignIn} service to create a session
+    #
+    # @param user [User] the user object to sign in
+    # @yield Yields to the block if the user is successfully signed in
+    # @return [Object] returns the value from calling perform on the {Oath::Services::SignIn} service
+    def sign_in user
+      Oath.config.sign_in_service.new(user, warden).perform.tap do |status|
+        if status && block_given?
+          yield
+        end
+      end
+    end
+
+    # Sign out the current session
+    #
+    # @note Uses the {Oath::Services::SignOut} service to destroy the session
+    #
+    # @return [Object] returns the value from calling perform on the {Oath::Services::SignOut} service
+    def sign_out
+      Oath.config.sign_out_service.new(warden).perform
+    end
+
+    # Sign up a user
+    #
+    # @note Uses the {Oath::Services::SignUp} service to create a user
+    #
+    # @param user_params [Hash] params containing lookup and token fields
+    # @yield Yields to the block if the user is signed up successfully
+    # @return [Object] returns the value from calling perform on the {Oath::Services::SignUp} service
+    def sign_up user_params
+      Oath.config.sign_up_service.new(user_params).perform.tap do |status|
+        if status && block_given?
+          yield
+        end
+      end
+    end
+
+    # Authenticates a session.
+    #
+    # @note Uses the {Oath::Services::Authentication} service to verify the user's details
+    #
+    # @param session_params [Hash] params containing lookup and token fields
+    # @param field_map [Hash] Field map used for allowing users to sign in with multiple fields e.g. email and username
+    # @return [User] if authentication succeeded
+    # @return [nil] if authentication failed
+    # @example Basic usage
+    #   class SessionsController < ApplicationController
+    #     def create
+    #       user = authenticate_session(session_params)
+    #
+    #        if sign_in(user)
+    #          redirect_to(root_path)
+    #        else
+    #          render :new
+    #        end
+    #      end
+    #
+    #      private
+    #
+    #      def session_params
+    #        params.require(:session).permit(:email, :password)
+    #      end
+    #
+    #    end
+    # @example Using the field map to authenticate using multiple lookup fields
+    #   class SessionsController < ApplicationController
+    #     def create
+    #       user = authenticate_session(session_params, email_or_username: [:email, :username])
+    #
+    #        if sign_in(user)
+    #          redirect_to(root_path)
+    #        else
+    #          render :new
+    #        end
+    #      end
+    #
+    #      private
+    #
+    #      def session_params
+    #        params.require(:session).permit(:email_or_username, :password)
+    #      end
+    #
+    #    end
+
+    def authenticate_session session_params, field_map = nil
+      token_field = Oath.config.user_token_field
+      params_hash = Oath.transform_params(session_params).symbolize_keys
+      password = params_hash.fetch(token_field)
+      user = Oath.lookup(params_hash.except(token_field), field_map)
+      authenticate(user, password)
+    end
+
+    # Authenticates a user given a password
+    #
+    # @note Uses the {Oath::Services::Authentication} service to verify the user's credentials
+    #
+    # @param user [User] the user
+    # @param password [String] the password
+    # @return [User] if authentication succeeded
+    # @return [nil] if authentication failed
+    def authenticate user, password
+      Oath.config.authentication_service.new(user, password).perform
+    end
+
+    # Resets a user's password
+    #
+    # @note Uses the {Oath::Services::PasswordReset} service to change a user's password
+    #
+    # @param user [User] the user
+    # @param password [String] the password
+    def reset_password user, password
+      Oath.config.password_reset_service.new(user, password).perform
+    end
+
+    # @api private
+    def warden
+      request.env['warden']
+    end
+
+    # helper_method that returns the current user
+    #
+    # @return [User] if user is signed in
+    # @return [nil] if user is not signed in
+    def current_user
+      @current_user ||= warden.user
+    end
+
+    # helper_method that checks if there is a user signed in
+    #
+    # @return [User] if user is signed in
+    # @return [nil] if user is not signed in
+    def signed_in?
+      warden.user
+    end
+
+    # before_action that determines what to do when the user is not signed in
+    #
+    # @note Uses the no login handler
+    def require_login
+      unless signed_in?
+        Oath.config.no_login_handler.call(self)
+      end
+    end
+  end
+end