Tachiban

Tachiban (立ち番 - standing watch) provides simple authentication system for Hanami web applications by using bcrypt for password hashing and offers the following functionalities (with methods listed below under Methods by features):

• Signup
• Login
• Authentication
• Session handling

The Tachiban logic and code were extracted from a Hanami based web app using Hanami::Model and was also used in a Camping based web app using Active Record.

Installation

Add this line to your application's Gemfile:

gem 'tachiban'

And then execute:

$ bundle

Or install it yourself as:

$ gem install tachiban

Tachiban is already setup to be included by your Hanami application:

::Hanami::Controller.configure do
  prepare do
    include Hanami::Tachiban
  end
end

Usage

Prerequisites

The entity for which authentication is used must have the attribute hashed_pass to hold the generated hashed password.

Prior to authenticating or logging in the user, retrieve them from the database and assign them to the instance variable of @user.

Usage by features

Signup

To create a user with a hashed password use the hashed_password(password) method for the password and store it as the user's attribute hashed_pass.

Example

# Create action for an entity
def call(params)
  password = params[:newuser][:password]
  hashed_pass = hashed_password(password)
  repository = UserRepository.new

  @user = repository.create(name: name, surname: surname, email: email,
  hashed_pass: hashed_pass))
end

Login

To authenticate a user use the authenticated?(input_password) method and log them in with the login method. Authentication is successful if the user exists and passwords match.

The user is logged in by setting the user object as the session[:current_user]. After the user is logged in the session start time is defined as session[:session_start_time] = Time.now. A flash message is also assigned as flash[:success_notice] = flash_message.

The session[:session_start_time] is then used by the session_expired? method to determine whether the session has expired or not.

Example

# Create action for an entity session
email = params[:entity_session][:email]
password = params[:entity_session][:password]

@user = EntityRepository.new.find_by_email(email)
login("You have been successfully logged in.") if authenticated?(password)

Authentication

To check whether the user is logged in use the check_for_logged_in_user method.

Session handling

Tachiban handles session expiration by checking if a session has expired and then restarts the session start time if the session is still valid or proceeds with the following if the session has expired:

• setting the session[:current_user] to nil
• a flash message is set: flash[:failed_notice] = "Your session has expired"
• redirects to the routes.root_path which can be overwritten by assigning a different url to @redirect_url

The session_expired? method compares the session start time increased for the defined @validity_time (set to 10 minutes by default, but can be overwritten) with the current time.

handle_session method:

  def handle_session
    if session_expired?
      @redirect_url ||= routes.root_path
      session[:current_user] = nil
      flash[:failed_notice] = "Your session has expired"
      redirect_to @redirect_url
    else
      restart_session_counter
    end
  end

Example of session handling in a share code module

module Web
  module HandleSession

     def self.included(action)
       action.class_eval do
         before :handle_session
       end
     end

  end
end

ToDo

1. Add support for password reset and update.
2. Add support for level based authorizations.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/sebastjan-hribar/tachiban. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.