tachiban 1.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2b2e100df48cb7de260705114b0c7d282bf2e67f8073442d987cb0295e985d48
-  data.tar.gz: 810a6b68cef7fd9177ef3083b05b0cc083eaecbc26e02b0621194c7f8c582db3
+  metadata.gz: 7608a00958bd0996ebd4d9f0aee635a3d99a2f997bce0be1fcf25672aeba9d59
+  data.tar.gz: 9ba708be4e0d7b9686ef2b00483d695151ccdffa4e39f6ceaabcc6c341bcf9b3
 SHA512:
-  metadata.gz: b884dd3638bc74fb54ccd11a1957d5fa6d4b32bf5a20aff39cfc300ce794069d4812b1decef520a2f31db2b91e2c4d41424e1747b4892b8321b67c0680dbe4e5
-  data.tar.gz: 64b5a67347b6cfc4c62ef3df0afb8e21305ef140807334ebbf3748fba2d8d9445d014b385735434fa238fb1b441df00b4e341156e78e9650b3df16e962779a91
+  metadata.gz: 05f96fc3be6acf310936d127f258c59a4adf152828c9269a26b6429e1e5a2db7f2fa91de9981ad9e1959bcfe68eab7328e769330a88a7204a9ab62cc1656b396
+  data.tar.gz: dc769a77a390224cf2f76abc28a3a9e1fa132908a049165e3f164fdb9320433e1bddcd6340780d7f42568fb6bdc9890e398e53ba4361fa971de29b1eef2b0dab

data/.gitignore

@@ -7,4 +7,5 @@
 /pkg/
 /spec/reports/
 /tmp/
-*.gem
+*.gem
+Makefile

data/README.md

@@ -1,8 +1,8 @@
 # Tachiban
 
-[![Join the chat at https://gitter.im/sebastjan-hribar/tachiban](https://badges.gitter.im/sebastjan-hribar/tachiban.svg)](https://gitter.im/sebastjan-hribar/tachiban?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [![Gem Version](https://badge.fury.io/rb/tachiban.svg)](https://badge.fury.io/rb/tachiban) [![Build Status](https://travis-ci.org/sebastjan-hribar/tachiban.svg?branch=master)](https://travis-ci.org/sebastjan-hribar/tachiban)
+[![Join the chat at https://gitter.im/sebastjan-hribar/tachiban](https://badges.gitter.im/sebastjan-hribar/tachiban.svg)](https://gitter.im/sebastjan-hribar/tachiban?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [![Gem Version](https://badge.fury.io/rb/tachiban.svg?kill_cache=1)](https://badge.fury.io/rb/tachiban)
 
-Tachiban (立ち番 - standing watch) provides simple authentication system for [Hanami web applications](http://hanamirb.org/) by using Argon2 for password hashing and
+Tachiban (立ち番 - standing watch) provides simple authentication system for [Hanami 2.x web applications](http://hanamirb.org/) by using Argon2 for password hashing and
 offers the following functionalities (with methods listed below
   under Methods by features):
 - Signup
@@ -12,7 +12,10 @@ offers the following functionalities (with methods listed below
 - Password reset
 - Authorization has been moved to [Rokku](https://github.com/sebastjan-hribar/rokku) 
 
-## Installation
+**Note:** For Hanami 1.3 support, see the [1.0.0 branch](https://github.com/sebastjan-hribar/tachiban/tree/1.0.0) or install Tachiban 1.0.
+
+
+## 1. Installation
 
  Add this line to your application's Gemfile:
 
@@ -28,21 +31,43 @@ Or install it yourself as:
 
     $ gem install tachiban
 
-Tachiban is already setup to be included by your Hanami application:
+
+Tachiban needs to be included in the action:
 
 ```ruby
-::Hanami::Controller.configure do
-  prepare do
+# app/action.rb
+# auto_register: false
+# frozen_string_literal: true
+
+require "hanami/action"
+require "dry/monads"
+require "tachiban"
+
+module MyApplication
+  class Action < Hanami::Action
+    # Provide `Success` and `Failure` for pattern matching on operation results
+    include Dry::Monads[:result]
     include Hanami::Tachiban
+
+    handle_exception "ROM::TupleCountMismatchError" => :handle_not_found
+
+    private
+
+    def handle_not_found(request, response, exception)
+      response.status = 404
+      response.format = :html
+      response.body = "Not found"
+    end
   end
 end
 ```
 
-## Usage
+## 2. Usage
 
-### Prerequisites
+### 2.1 Prerequisites
 Prior to logging in or authenticating the user, retrieve the entity from the
-database and assign it to the instance variable of `@user`.
+database and assign it to a variable (e.g. `user`), which you then pass to
+the methods as required.
 
 In addition to that, the user entity must have the following attributes:
 
@@ -51,136 +76,365 @@ In addition to that, the user entity must have the following attributes:
 * **hashed_pass** (to hold the generated hashed password)
 
 
-### Usage
+### 2.2 Usage
 
-#### Signup
+#### 2.2.3 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*
 
 ```ruby
-# Create action for an entity
-def call(params)
-  password = params[:newuser][:password]
+# Create action for the user
+def handle(request, response)
+  password = request.params[:newuser][:password]
   hashed_pass = hashed_password(password)
-  repository = UserRepository.new
 
-  @user = repository.create(name: name, surname: surname, email: email,
-  hashed_pass: hashed_pass))
+  user = user_repo.create(name: name, surname: surname, email: email,
+  hashed_pass: hashed_pass)
 end
 ```
 
-#### Authentication and 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.
+#### 2.2.4 Authentication and login
+To authenticate a user use the `authenticated?(input_password, user)` method and log
+them in with the `login(request, response, user_id, flash_message: nil, login_redirect_url: nil)` method.
+
+Authentication is successful if the user exists and passwords match. It's possible to provide your own flash message and / or redirect url. Otherwise, the **default values** will be used (see the table below).
 
-The user is logged in by setting the user object ID 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 default flash message is also
+The user is logged in by setting the user object ID as the `request.session[:current_user]`.
+After the user is logged in, the session start time is defined as
+`request.session[:session_start_time] = Time.now`. A default flash message is also
 assigned as 'You have been successfully logged in.'.
 
-The `session[:session_start_time]` is then used by the `session_expired?`
-method to determine whether the session has expired or not.
+The `request.session[:session_start_time]` is then used by the `session_expired?(request, response)` method to determine whether the session has expired or not.
 
-*Example of session creation for an entity*
+**_Example of session creation for an entity_**
 
 ```ruby
-# Create action for an entity session
-email = params[:entity_session][:email]
-password = params[:entity_session][:password]
+# Create action for the user session
+email = request.params[:entity_session][:email]
+password = request.params[:entity_session][:password]
 
-@user = EntityRepository.new.find_by_email(email)
-login if authenticated?(password)
+user = user_repo.find_by_email(email) #required by login
+login(request, response, user.id) if authenticated?(password, user)
 ```
 
-To check whether the user is logged in use the `check_for_logged_in_user` method.
-If the user is not logged in the `logout` method takes over.
+To check whether a user is logged in, use the `check_for_logged_in_user(request, response)` method. If the user is not logged in, the `logout(request, response, logout_redirect_url: nil)` method takes over.
 
+The `authenticated?` method now performs the same amount of work whether or not the email matches a
+user, so response time does not reveal whether an account exists. It returns false for
+a nil password or a user record with no stored hash.
 
-#### Session handling
+
+#### 2.2.5 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.
+- setting the `request.session[:current_user]` to `nil`,
+- a flash message is set: `response.flash[:failed_notice] = "Your session has expired"`,
+- redirects to the root path `/`, which can be overridden.
+
 
+The `session_expired?(request, validity_time: nil)` method compares the session start time
+increased for the defined `validity_time` (set to 10 minutes
+by default, but can be overridden) with the current time.
 
-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.
+On expiry, `handle_session` clears the current user, sets
+`response.flash[:failed_notice]` and redirects. The flash and the redirect url
+are configurable — see section 3.
+
+
+#### 2.2.6 Session handling in a share code module
+It is possible to enable session handling in a share code module as provided by Hanami.
+To do this, create an authentication module in **app/actions/authentication.rb**.
+The example below shows also how to custom values to replace default values in
+actions.
 
-`handle_session` method:
 ```ruby
-  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
+module MyApplication
+  module Actions
+    module Authentication
+      def self.included(action_class)
+        action_class.class_eval do
+          before :check_for_logged_in_user
+          before :handle_session
+        end
+      end
+
+      private
+
+      def custom_handle_session_redirect_url
+        '/login'
+      end
+
+      def custom_logout_redirect_url
+        '/login'
+      end
+
+      def custom_login_redirect_url
+        '/'
+      end
+
+      def custom_session_validity_time
+        if ENV['HANAMI_ENV'] == 'test'
+          600
+        else
+          1800
+        end
+      end
     end
   end
+end
+```
+We can then simply include the `Authentication` module in actions, where required.
+
+However, if we include this in the base action class, it will be available in all
+actions and there is no need for separate includes in actions:
+
+```ruby
+#
+#
+module MyApplication
+  class Action < Hanami::Action
+    # Provide `Success` and `Failure` for pattern matching on operation results
+    include Dry::Monads[:result]
+    include Hanami::Tachiban
+    include MyApplication::Actions::Authentication
+
+    handle_exception "ROM::TupleCountMismatchError" => :handle_not_found
+
+    private
+#
+#
 ```
 
-*Example of session handling in a share code module*
+
+**_Disabling the authentication shared module methods in specific actions_**
+
+Any action a logged-out user must be able to reach, should disable the
+authentication. One such example would be the `login` action. If we check
+for an authenticated user there, it will cause an infinite loop. So we
+have to disable the authentication module methods by overriding
+the desired methods in the action. Below is a concrete example for the
+new action for `UserSessions`, which renders the login form when a user
+visits the '/login' url:
 
 ```ruby
-module Web
-  module HandleSession
+# frozen_string_literal: true
+
+module Myapplication
+  module Actions
+    module UserSessions
+      class New < Myapplication::Action
+
+        def handle(request, response)
+          request.session[:current_user] = nil
+        end
 
-     def self.included(action)
-       action.class_eval do
-         before :handle_session
-       end
-     end
+        private
 
+        def check_for_logged_in_user; end
+        def handle_session; end
+      end
+    end
   end
 end
 ```
 
+#### 2.2.7 Password reset
+The password reset feature provides methods to:
+* generate a token, build email subject and body (text and html part),
+* verify the reset link and
+* invalidate a used token.
+
+The link validity must me specified in seconds. The method compares the
+current time with the time when the password reset link was sent increased
+by the link validity: `Time.now > user.password_reset_sent_at + link_validity`.
+
 
-#### Password reset
-The password reset feature provides a few simple methods to generate a
-token, email subject and body. It is also possible to specify and
-check the validity of the password reset url.
+**Generating a reset link**
 
 ```ruby
-token # => "YbRucc8YUlFJrYYp04eQKQ"
+reset_token = token # => 43-character URL-safe string
+user_repo.update(user.id, token: reset_token, password_reset_sent_at: Time.now)
 ```
 
 ```ruby
-email_subject(SomeApp) # => "SomeApp -- password reset request"
+email_subject("SomeApp") # => "SomeApp -- password reset request"
+```
+
+Provide the reset url, user's name, link validity, time unit and optionally the
+application name when building the body:
+
+```ruby
+html_body = email_body_html(
+  reset_url: reset_url,
+  user_name: "#{user.name} #{user.surname}",
+  link_validity: 2,
+  time_unit: "hour",
+  app_name: nil
+)
+```
+
+`app_name` falls back to the `APP_NAME` environment variable, then to your Hanami
+app's namespace, then to "Application".
+
+
+**Verifying a reset link**
+
+Use `verify_reset_token`. It takes the token from the params and a block that looks
+the user up, and returns the user only if the token is present, a user matches, and
+the link is still inside its validity window. Any failure returns nil, so one check
+covers every case:
+
+```ruby
+def handle(request, response)
+  user = verify_reset_token(request.params[:token]) { |t| user_repo.find_by_token(t) }
+
+  unless user
+    response.flash[:failed_notice] = "This link is invalid or has expired."
+    response.redirect_to "/passwordreset/new"
+    return
+  end
+
+end
 ```
 
+The block must return nil when no user matches. With ROM, use `.one` rather than
+`.one!` — `.one!` raises on no match and the exception escapes before
+`verify_reset_token` can return nil.
+
+Validity defaults to 3600 seconds. Override per call with
+`link_validity_seconds:`, or globally with a `custom_link_validity_seconds` method.
+
+`password_reset_url_valid?(link_validity, user)` remains available for direct use
+to support backward compatibility, but `verify_reset_token` is preferred because
+it performs the checks in the correct order.
+
+
+**Invalidating the token after a reset — required**
 
-Provide the base url, the token and the number and type of the time units
- for the validity of the link.
+Tachiban does not clear tokens after use. It's best you clear them in
+the same update as the new password and you can use the `reset_token_attributes` for that.
+Otherwise the token is valid until its window expires and can be reused.
 
 ```ruby
-body = email_body(base_url, url_token, 2, "hour")
-# => "Visit this url to reset your password: http://localhost:2300/passwordupdate/asdasdasdaerwrw.
-#     The url will be valid for 2 hour(s).")
+user_repo.update(
+  user.id,
+  hashed_pass: hashed_password(new_password),
+  **reset_token_attributes
+)
 ```
 
-The link validity must me specified in seconds. The method compares the
-current time with the time when the password reset link was sent increased
-by the link validity: `Time.now > @user.password_reset_sent_at + link_validity`
+
+## 3. Default values and custom overrides
+There are a few default values set which can be overridden in two ways: by passing an argument at the call site,
+or by defining a private custom method on your action. See the table below.
+
+Precedence: **explicit argument → custom method → built-in default.**
+
+|Method            |Argument            |Custom method                     |Default                                |
+|---               |---                 |---                               |---                                    |
+|`login`           |`flash_message:`    |`custom_login_flash_message`      |'You have been successfully logged in.'|
+|`login`           |`login_redirect_url:`|`custom_login_redirect_url`      |'/'                                    |
+|`logout`          |`logout_redirect_url:`|`custom_logout_redirect_url`    |'/login'                               |
+|`session_expired?`|`validity_time:`    |`custom_session_validity_time`    |600                                    |
+|`handle_session`  |`redirect_url:`     |`custom_handle_session_redirect_url`|'/'                                  |
+|`handle_session`  |—                   |`custom_session_expired_message`  |'Your session has expired.'            |
+|`verify_reset_token`|`link_validity_seconds:`|`custom_link_validity_seconds`|3600                               |
+
+
+**All time values are in seconds.** `validity_time` and `custom_session_validity_time`
+are the same value under different names — 600 means ten minutes in both.
+
+Custom methods can be private — Tachiban looks up private methods too, so you don't
+need to expose them on your action's public interface.
+
+Define them on your base action to apply everywhere, or on a single action to
+override just that one:
 
 ```ruby
-password_reset_url_valid?(link_validity)
+# app/action.rb — applies to every action
+module MyApplication
+  class Action < Hanami::Action
+    include Hanami::Tachiban
+
+    private
+
+    def custom_session_validity_time
+      1800
+    end
+  end
+end
+
+# app/actions/admin/dashboard.rb — tighter window for this action only
+module MyApplication
+  module Actions
+    module Admin
+      class Dashboard < MyApplication::Action
+        private
+
+        def custom_session_validity_time
+          300
+        end
+      end
+    end
+  end
+end
 ```
 
-### Example of use in an application
-[Using Tachiban with a Hanami app](https://sebastjan-hribar.github.io/programming/2021/09/03/tachiban-with-hanami.html)
 
 
-### Changelog
+
+## 4. Changelog
+
+#### 2.1.0
+Backward compatible with 2.0.0. All existing method signatures are unchanged.
+
+**Security fixes:**
+- `authenticated?` no longer returns early when no user is found. It verifies the
+  submitted password against a precomputed dummy hash instead, so existing and
+  non-existing accounts take the same time to respond. This closes an account
+  enumeration vulnerability where a valid email could be identified
+  by a slower response.
+- `authenticated?` also handles a user record with a nil `hashed_pass`, and returns
+  false for a nil password instead of raising.
+- `password_reset_url_valid?` now fails closed. It returns false for a nil user or a
+  user with no `password_reset_sent_at`, where it previously raised NoMethodError.
+- `session_expired?` now returns true when `session_start_time` is missing, rather
+  than raising. An undateable session is treated as expired.
+- Reset tokens are now 32 bytes (`SecureRandom.urlsafe_base64(32)`).
+
+**New methods:**
+- `verify_reset_token(token, link_validity_seconds: nil)` — performs the
+  blank-token check, the user lookup and the expiry check in the correct order and
+  returns the user or nil. Recommended over calling `password_reset_url_valid?`
+  directly.
+- `reset_token_attributes` — returns `{token: nil, password_reset_sent_at: nil}` for
+  passing to the repo's update method after a successful reset. **Tachiban does not
+  invalidate tokens by itself.** Failing to clear them leaves reset links replayable
+  indefinitely.
+
+**New feature — custom method hooks:**
+Default values can now be overridden by defining private methods on your action
+instead of passing arguments. This makes defaults configurable for `before` callbacks
+like `handle_session`, which Hanami calls with a fixed argument list. See section 3.
+
+**Other:**
+- Requires for `hanami-controller` and `hanami-action` were dropped.
+
+#### 2.0.0
+
+**Breaking Changes:**
+- Supports Hanami ~> 2.0 applications only.
+- Method signatures updated: `login`, `logout`, `check_for_logged_in_user`, and `handle_session` now require `(request, response)` parameters.
+- Methods `session_expired?` and `restart_session_counter` now require `(request)` parameter.
+- Tachiban must be explicitly included in the base action: `include Hanami::Tachiban`.
+- Tachiban 2.0.0 doesn't rely on instance variable like `@user` anymore. Instead, a `user` variable must be passed as an argument to a method.
+
+For Hanami 1.3 support, use Tachiban 1.0.
 
 #### 1.0.0
 

data/Rakefile

@@ -1,7 +1,5 @@
 require "bundler/gem_tasks"
 require "rake/testtask"
-require "hanami/controller"
-require 'hanami/action/session'
 
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"

data/lib/tachiban/version.rb

@@ -1,3 +1,3 @@
 module Tachiban
-  VERSION = "1.0.0"
+  VERSION = "2.1.0"
 end

data/lib/tachiban.rb

@@ -1,148 +1,298 @@
 require 'tachiban/version'
-require 'hanami/controller'
-require 'hanami/action/session'
 require 'argon2'
+require 'securerandom'
 
 module Hanami
   module Tachiban
-private
 
+    # ### Account Enumeration Vulnerability Mitigation ###
 
-  # ### Signup ###
+    # To close the account enumeration vulnerability via response timing,
+    #   a dummy hash is computed once when Tachiban loads. When no user is found,
+    #   the provided password is verified against that dummy hash instead of
+    #   returning immediately. Both the existing-account and missing-account paths
+    #   then perform one Argon2 verification, so the response time no longer tells
+    #   an attacker whether an account exists.
+    #
+    #   The dummy hash is precomputed rather than generated per request on purpose:
+    #   Argon2 hash creation is more expensive than verification, so generating one
+    #   per miss would make the missing-account path measurably slower and reopen
+    #   the leak in the other direction.
 
-  # The hashed_password method generates a hashed version of the user's
-  # password. Password hashing is provided by Argon2. Hashed password
-  # by default includes a salt and the default cost factorr.
-  #
-  # Hashed password should be stored in the database as an user's
-  # attribute so it can be retrieved during the login process.
+    DUMMY_HASH = Argon2::Password.create(SecureRandom.hex(32)).freeze
 
-    def hashed_password(password)
-      Argon2::Password.create(password)
+    private
+
+    # The `tachiban_custom` helper looks up an optional customization method
+    #   on the including action. If the action defines `name`, calls it and
+    #   returns its result; otherwise returns `fallback`.
+    #   The second argument to `respond_to?` includes private methods, so actions
+    #   can keep their overrides private.
+    #
+    #   Custom methods can be used in the base action, a specific action or both.
+    #
+    #   # app/action.rb
+    #   module MyApp
+    #     class Action < Hanami::Action
+    #       include Hanami::Tachiban
+    #
+    #       private
+    #
+    #       def custom_session_validity_time
+    #         1800
+    #       end
+    #
+    #       def custom_handle_session_redirect_url
+    #         "/login"
+    #       end
+    #     end
+    #   end
+    #
+    #   # app/actions/admin/dashboard.rb
+    #   module MyApp
+    #     module Actions
+    #       module Admin
+    #         class Dashboard < MyApp::Action
+    #           private
+    #
+    #           def custom_session_validity_time
+    #             300
+    #           end
+    #         end
+    #       end
+    #     end
+    #   end
+    def tachiban_custom(name, fallback)
+      respond_to?(name, true) ? send(name) : fallback
     end
 
-  # ### Login ###
 
-  # The authenticated? method returns true if the the following criteria
-  # are true:
-  # - a user exists
-  # - a user's hashed password from the database matches the input password
+    # ### Signup ###
 
-    def authenticated?(input_pass)
-      @user && Argon2::Password.verify_password(input_pass, @user.hashed_pass)
+    # The `hashed_password` method generates a hashed version of the user's
+    #   password. Password hashing is provided by Argon2. Hashed password
+    #   by default includes a salt and the default cost factor.
+    #
+    #   Hashed password should be stored in the database as a user's
+    #   attribute so it can be retrieved during the login process.
+    def hashed_password(password)
+      Argon2::Password.create(password)
     end
 
-  # The login method can be used in combination with the authenticated? method to
-  # log the user in if the authenticated? method returns true. The user is
-  # logged in by setting the user object id as the session[:current_user].
-  # After the user is logged in the session start time is defined, which is then used
-  # by the session_expired? method to determine whether the session has
-  # expired or not.
-
-  # There are two defualt values set: one for flash message and
-  # the other for redirect url. Both can be overwritten by assigning
-  # new values for @flash_message and @login_redirect_url.
+    # ### Login ###
 
-  # Example:
-  # login if authenticated?(input_pass)
+    # The `authenticated?` method returns true if the following criteria
+    #   are true:
+    #   - a user exists
+    #   - a user's hashed password from the database matches the input password
+    #
+    #   The Account Enumeration Vulnerability Mitigation is in place.
+    def authenticated?(input_pass, user)
+      return false if input_pass.nil?
 
-    def login
-      session[:current_user] = @user.id
-      session[:session_start_time] = Time.now
-      @flash_message ||= 'You have been successfully logged in.'
-      flash[:success_notice] = @flash_message
-      @login_redirect_url ||= routes.root_path
-      redirect_to @login_redirect_url
-    end
+      if user.nil? || user.hashed_pass.nil?
+        Argon2::Password.verify_password(input_pass, DUMMY_HASH)
+        return false
+      end
 
-  # The logout method sets the current user in the session to nil
-  # and performs a redirect to the redirect_url which is set to
-  # /login, but can be overwritten as needed with a specific url
-  # by setting a new value for @logout_redirect_url.
+      Argon2::Password.verify_password(input_pass, user.hashed_pass)
 
-    def logout
-      session[:current_user] = nil
-      session.clear
-      @logout_redirect_url ||= '/login'
-      redirect_to @logout_redirect_url
+    rescue Argon2::ArgonHashFail
+      false
     end
 
-  # ### Authentication ###
+    # The `login` method can be used in combination with the `authenticated?` method to
+    #   log the user in if the `authenticated?` method returns true. The user is
+    #   logged in by setting the user object id as the `session[:current_user]`.
+    #   After the user is logged in the session start time is defined, which is then used
+    #   by the `session_expired?` method to determine whether the session has
+    #   expired or not.
 
-  # The check_for_logged_in_user method can be used to check for each
-  # request whether the user is logged in. If the user is not logged in
-  # the logout method takes over.
+    #   There are two default values set: one for flash message and
+    #   the other for redirect url. Both can be overwritten by using
+    #   custom method helper.
 
-    def check_for_logged_in_user
-      logout unless session[:current_user]
+    #   Example:
+    #   login(request, response, user.id) if authenticated?(input_pass)
+    def login(request, response, user_id, flash_message: nil, login_redirect_url: nil)
+      request.session[:current_user] = user_id
+      request.session[:session_start_time] = Time.now
+      response.flash[:success_notice] = flash_message || tachiban_custom(:custom_login_flash_message,
+                                        'You have been successfully logged in.')
+      response.redirect_to(login_redirect_url || tachiban_custom(:custom_login_redirect_url, '/'))
     end
 
-  # ### Session handling ###
-
-  # Session handling  includes methods session_expired?,
-  # restart_session_counter and handle session.
+    # The `logout` method sets the current user in the session to nil
+    #   and performs a redirect to the `logout_redirect_url` which is set to
+    #   `'/login'`, but can be overwritten as needed with a specific url
+    #   by using custom method helper.
+    def logout(request, response, logout_redirect_url: nil)
+      request.session[:current_user] = nil
+      request.session.clear
+      response.redirect_to(logout_redirect_url || tachiban_custom(:custom_logout_redirect_url, "/login"))
+    end
 
-  # The session_expired? method compares the session start time
-  # increased for the defined validity time (set to 10 minutes
-  # by default and can be overwritten) with the current time.
+    # ### Authentication ###
 
-    def session_expired?
-      if session[:current_user]
-        @validity_time ||= 600
-        session[:session_start_time] + @validity_time.to_i < Time.now
-      end
+    # The `check_for_logged_in_user` method can be used to check for each
+    #   request whether the user is logged in. If the user is not logged in
+    #   the logout method takes over.
+    def check_for_logged_in_user(request, response)
+      logout(request, response) unless request.session[:current_user]
     end
 
-  # The restart_session_counter method resets the session start time to
-  # Time.now. It's used in the handle  session method.
+    # ### Session handling ###
 
-    def restart_session_counter
-      session[:session_start_time] = Time.now
-    end
+    # Session handling includes methods `session_expired?`,
+    #   `restart_session_counter` and `handle_session`.
+    #
+    #   The `session_expired?` method compares the session start time
+    #   increased for the defined validity time in seconds with the current time.
+    #   The default validity of 600 seconds (10 minutes) can be overwritten by using the
+    #   custom method helper.
+    def session_expired?(request, validity_time: nil)
+      return false unless request.session[:current_user]
+      return true unless request.session[:session_start_time]
 
-    # The handle_session method is used to handle the incoming requests
-    # based on the the session expiration. If the session has expired the
-    # session user is set to nil, a flash message of "Your session has expired"
-    # is provided and a redirect to a default url of routes.root_path
-    # is triggered.
+      validity_time ||= tachiban_custom(:custom_session_validity_time, 600)
+      request.session[:session_start_time] + validity_time.to_i < Time.now
+    end
 
-    # If the session hasn't expired the restart_session_counter method is
-    # called to reset the session start time.
+    # The `restart_session_counter` method resets the session start time to
+    #   `Time.now`. It's used in the `handle_session` method.
+    def restart_session_counter(request)
+      request.session[:session_start_time] = Time.now
+    end
 
-    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
+    # The `handle_session` method is used to handle the incoming requests
+    #   based on the session expiration. If the session has expired the
+    #   session user is set to nil, a flash message of "Your session has expired"
+    #   is provided and a redirect to a default url of "/" is triggered.
+    #
+    #   Both default values can be overwritten by using the custom method helper.
+    #
+    #   If the session hasn't expired the `restart_session_counter` method is
+    #   called to reset the session start time.
+    def handle_session(request, response, redirect_url: nil)
+      if session_expired?(request)
+        redirect_url ||= tachiban_custom(:custom_handle_session_redirect_url, "/")
+        request.session[:current_user] = nil
+        response.flash[:failed_notice] = tachiban_custom(:custom_session_expired_message,
+                                                           'Your session has expired.')
+        response.redirect_to redirect_url
       else
-        restart_session_counter
+        restart_session_counter(request)
       end
     end
 
-  # ### Password reset ###
+    # ### Password reset ###
+    # The password reset functionalities include token generation, token invalidation,
+    #   email subject, email body in the text as well as in the html format,
+    #   checking the reset link validity and getting the app name.
     def token
-      SecureRandom.urlsafe_base64
+      SecureRandom.urlsafe_base64(32)
+    end
+
+    # After a successful reset the token and the timestamp of the password reset link
+    #   must be reset. The attributes are prepared to be passed to the update repo method.
+    #
+    #   Usage:
+    #   user_repo.update(user.id, hashed_pass: hashed_password(new_password), **reset_token_attributes)
+    def reset_token_attributes
+      {token: nil, password_reset_sent_at: nil}
     end
 
     def email_subject(app_name)
+      app_name ||= default_app_name
       "#{app_name} -- password reset request"
     end
 
-    def email_body(url, token, link_validity, time_unit)
-      "Visit this url to reset your password: #{url}#{token}. \n
-      The url will be valid for #{link_validity} #{time_unit}(s)."
+    def email_body_text(reset_url:, user_name:, link_validity:, time_unit:, app_name: nil)
+      app_name ||= default_app_name
+
+      <<~TEXT
+        Hello #{user_name},
+
+        Click the link below to reset your password:
+
+        #{reset_url}
+
+        This link will expire in #{link_validity} #{time_unit}(s).
+
+        Kind regards,
+        The #{app_name} Team
+      TEXT
     end
 
-    # State the link_validity in seconds.
-    def password_reset_url_valid?(link_validity)
-      Time.now < @user.password_reset_sent_at + link_validity
+    def email_body_html(reset_url:, user_name:, link_validity:, time_unit:, app_name: nil)
+      app_name ||= default_app_name
+
+      <<~HTML
+        <!DOCTYPE html>
+          <html>
+            <body style="font-family: Arial, sans-serif;">
+              <h2>Password reset request</h2>
+              <br>
+              <p>Hello #{user_name},</p>
+              <br>
+              <p>Click the button below to reset your password:</p>
+              <p>
+                <a href="#{reset_url}" style="background: #007bff; color: white; padding: 10px 20px; text-decoration: none; border-radius: 4px;">
+                  Reset Password
+                </a>
+              </p>
+              <br>
+              <p>Or copy this link: #{reset_url}</p>
+              <p style="color: #666; font-size: 12px;">This link expires in #{link_validity} #{time_unit}(s).</p>
+            </body>
+          </html>
+      HTML
     end
-  end
-end
 
-::Hanami::Controller.configure do
-  prepare do
-    include Hanami::Tachiban
+    # The `password_reset_url_valid?` method checks whether a user's password
+    #   reset link is still within its validity window.
+    #   State the link validity in seconds. The method returns false
+    #   for a nil user or a user with no reset timestamp, so it fails closed.
+    #
+    #   This method can still be called directly, but it is advised to use the
+    #   `verify_reset_token` method to cover all link and token validity
+    #   checks at the same time.
+    def password_reset_url_valid?(link_validity, user)
+      return false unless user
+      return false unless user.password_reset_sent_at
+
+      Time.now < user.password_reset_sent_at + link_validity.to_i
+    end
+
+    # Verifies the validity of a password reset token by checking:
+    #   - presence of the token,
+    #   - finding the matching user if token is present and
+    #   - checking the link validity in seconds.
+    #
+    #   If all checks pass, it returns a valid matching user, otherwise it returns nil.
+    #   The token is passed to the block when the method is called.
+    #
+    #   The block must return nil when no user matches — use ROM's `.one`
+    #   rather than `.one!`, since `.one!` raises and the exception would
+    #   escape before this method can return nil.
+    #
+    #   In a handle method it can be used like:
+    #
+    #   user = verify_reset_token(request.params[:token]) { |t| user_repo.find_by_token(t) }
+    def verify_reset_token(token, link_validity_seconds: nil)
+      return nil if token.nil? || token.to_s.strip.empty?
+
+      user = yield(token)
+      link_validity_seconds ||= tachiban_custom(:custom_link_validity_seconds, 3600)
+      password_reset_url_valid?(link_validity_seconds, user) ? user : nil
+    end
+
+    def default_app_name
+      ENV.fetch("APP_NAME") do
+        Hanami.respond_to?(:app) ? Hanami.app.namespace.to_s : "Application"
+      end
+    rescue StandardError
+      "Application"
+    end
   end
-end
+end

data/tachiban.gemspec

@@ -17,16 +17,11 @@ Gem::Specification.new do |spec|
   spec.executables = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 2.0"
-  spec.add_development_dependency "rake", "~> 12.3", ">= 12.3.3"
+  spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "minitest", "~> 5.0"
-  spec.add_development_dependency "hanami-model", "~> 1.0"
-  spec.add_development_dependency "timecop", "0.8.1"
-  spec.add_development_dependency 'hanami-controller', "~> 1.0"
-  spec.add_development_dependency 'hanami-router', "~> 1.0"
-  spec.add_development_dependency 'pry', "~> 0"
+  spec.add_development_dependency "timecop", "~> 0.9.0"
+  spec.add_development_dependency 'pry', "~> 0.16.0"
 
   spec.add_runtime_dependency "argon2", "~> 2.3"
-  spec.add_runtime_dependency 'hanami-controller', "~> 1.0"
-  spec.add_runtime_dependency 'hanami-router', "~> 1.0"
-end
+  spec.required_ruby_version = ">= 3.0.0"
+end

metadata

@@ -1,49 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: tachiban
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Sebastjan Hribar
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-10-09 00:00:00.000000000 Z
+date: 2026-09-17 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '12.3'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 12.3.3
+        version: '13.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '12.3'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 12.3.3
+        version: '13.0'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -58,76 +38,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '5.0'
-- !ruby/object:Gem::Dependency
-  name: hanami-model
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: timecop
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - '='
-      - !ruby/object:Gem::Version
-        version: 0.8.1
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - '='
-      - !ruby/object:Gem::Version
-        version: 0.8.1
-- !ruby/object:Gem::Dependency
-  name: hanami-controller
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: 0.9.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
-- !ruby/object:Gem::Dependency
-  name: hanami-router
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
+        version: 0.9.0
 - !ruby/object:Gem::Dependency
   name: pry
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.16.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.16.0
 - !ruby/object:Gem::Dependency
   name: argon2
   requirement: !ruby/object:Gem::Requirement
@@ -142,35 +80,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.3'
-- !ruby/object:Gem::Dependency
-  name: hanami-controller
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
-- !ruby/object:Gem::Dependency
-  name: hanami-router
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
-description: 
+description:
 email:
 - sebastjan.hribar@gmail.com
 executables:
@@ -197,7 +107,7 @@ homepage: https://github.com/sebastjan-hribar/tachiban
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -205,15 +115,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 3.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
-signing_key: 
+rubygems_version: 3.5.9
+signing_key:
 specification_version: 4
 summary: Tachiban provides simple password hashing for user authentication with Argon2
   for Hanami web applications.