rodauth 2.35.0 → 2.36.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f2b961b8668976f18f46df1c499c1c8f101e75a76527feef460419ad71d7d15b
-  data.tar.gz: 446184720914538cd207b90cb0d6b9e484eadb12559be84f117532aed5d1cf87
+  metadata.gz: 4daf43beb9b2af129683b299f1e455e5b38fa925b1cc020ec79ae951f56f292b
+  data.tar.gz: a694fe203f76512691004d1138ad03cab7699d317a0a658ae6ac51732ff22b36
 SHA512:
-  metadata.gz: 548c5f50659441297116a0343d2cf2160a8f54ec7c0f7b87867e6377bf9165a53db9b69802f2573343031a26c073ef3e4d0e4358163a97686511b32448f05f5f
-  data.tar.gz: bf33b84dcb33a6f5cb54f4df2f4561d57d74cc91040032d3eee58e72dbdedad618b726daff2341e91f4350a451b816f719c836f6211acfe20ffaecb879e736d5
+  metadata.gz: aef00a1d31a310ea0061f54ebcb4044ccdcc7106d2f07074f4585ac5406776784bef9c698befa050b374d4dd37dd2495d3a3e4dcd6854e387fc8442901f3f227
+  data.tar.gz: 85d9837f21b320f2bec1241f07e22ff150b49192017cb1ea20d2863fce93b547d5271cafe30b08baeaa582fd4f40b715ce488d9fb19bd7fe2cc43a2f565b5266

data/CHANGELOG

@@ -1,4 +1,20 @@
-=== 2.35.0 (2025-05-28)
+=== 2.36.0 (2024-07-23)
+
+* Add webauthn_modify_email feature for emailing when a WebAuthn authenticator is added or removed (jeremyevans)
+
+* Add account_from_id method for retrieving an account using the account id and optional status id (janko) (#431)
+
+* Add otp_modify_email feature for emailing when TOTP authentication is setup or disabled (jeremyevans)
+
+* Add otp_lockout_email feature for emailing when TOTP authentication is locked out or unlocked (jeremyevans)
+
+* Add strftime_format configuration method for configuring display of Time values to users (jeremyevans)
+
+* Add otp_unlock feature for unlocking TOTP authentication after it has been locked out (jeremyevans)
+
+* Make internal_request feature work with Roda path_rewriter plugin (jeremyevans) (#425)
+
+=== 2.35.0 (2024-05-28)
 
 * Handle internal_request_configuration blocks in superclasses (jeremyevans, bjeanes)
 

data/README.rdoc

@@ -38,7 +38,11 @@ HTML and JSON API for all supported features.
 * WebAuthn Login (Passwordless login via WebAuthn)
 * WebAuthn Verify Account (Passwordless WebAuthn Setup)
 * WebAuthn Autofill (Autofill WebAuthn credentials on login)
+* WebAuthn Modify Email (Email when WebAuthn authenticator aded or removed)
 * OTP (Multifactor authentication via TOTP)
+* OTP Modify Email (Email when TOTP authentication setup or disabled)
+* OTP Unlock (Unlock TOTP authentication after lockout)
+* OTP Lockout Email (Email when TOTP authentication locked out or unlocked)
 * Recovery Codes (Multifactor authentication via backup codes)
 * SMS Codes (Multifactor authentication via SMS)
 * Verify Login Change (Verify new login before changing login)
@@ -328,7 +332,7 @@ PostgreSQL 15 changed default database security so that only the database
 owner has writable access to the public schema.  Rodauth expects the
 +ph+ account to have writable access to the public schema when setting
 things up.  Temporarily grant that access (it will be revoked after the
-migation has run)
+migration has run)
 
   psql -U postgres -c "GRANT CREATE ON SCHEMA public TO ${DATABASE_NAME}_password" ${DATABASE_NAME}
 
@@ -587,6 +591,13 @@ Note that these migrations require Sequel 4.35.0+.
         Time :last_use, null: false, default: Sequel::CURRENT_TIMESTAMP
       end
 
+      # Used by the otp_unlock feature
+      create_table(:account_otp_unlocks) do
+        foreign_key :id, :accounts, primary_key: true, type: :Bignum
+        Integer :num_successes, null: false, default: 1
+        Time :next_auth_attempt_after, null: false, default: Sequel::CURRENT_TIMESTAMP
+      end
+
       # Used by the recovery codes feature
       create_table(:account_recovery_codes) do
         foreign_key :id, :accounts, type: :Bignum
@@ -631,6 +642,7 @@ Note that these migrations require Sequel 4.35.0+.
         run "GRANT SELECT, INSERT, UPDATE, DELETE ON account_webauthn_user_ids TO #{user}"
         run "GRANT SELECT, INSERT, UPDATE, DELETE ON account_webauthn_keys TO #{user}"
         run "GRANT SELECT, INSERT, UPDATE, DELETE ON account_otp_keys TO #{user}"
+        run "GRANT SELECT, INSERT, UPDATE, DELETE ON account_otp_unlocks TO #{user}"
         run "GRANT SELECT, INSERT, UPDATE, DELETE ON account_recovery_codes TO #{user}"
         run "GRANT SELECT, INSERT, UPDATE, DELETE ON account_sms_codes TO #{user}"
       end
@@ -639,6 +651,7 @@ Note that these migrations require Sequel 4.35.0+.
     down do
       drop_table(:account_sms_codes,
                  :account_recovery_codes,
+                 :account_otp_unlocks,
                  :account_otp_keys,
                  :account_webauthn_keys,
                  :account_webauthn_user_ids,
@@ -920,6 +933,9 @@ view the appropriate file in the doc directory.
 * {Login}[rdoc-ref:doc/login.rdoc]
 * {Logout}[rdoc-ref:doc/logout.rdoc]
 * {OTP}[rdoc-ref:doc/otp.rdoc]
+* {OTP Lockout Email}[rdoc-ref:doc/otp_lockout_email.rdoc]
+* {OTP Modify Email}[rdoc-ref:doc/otp_modify_email.rdoc]
+* {OTP Unlock}[rdoc-ref:doc/otp_unlock.rdoc]
 * {Password Complexity}[rdoc-ref:doc/password_complexity.rdoc]
 * {Password Expiration}[rdoc-ref:doc/password_expiration.rdoc]
 * {Password Grace Period}[rdoc-ref:doc/password_grace_period.rdoc]
@@ -939,6 +955,7 @@ view the appropriate file in the doc directory.
 * {WebAuthn}[rdoc-ref:doc/webauthn.rdoc]
 * {WebAuthn Autofill}[rdoc-ref:doc/webauthn_autofill.rdoc]
 * {WebAuthn Login}[rdoc-ref:doc/webauthn_login.rdoc]
+* {WebAuthn Modify Email}[rdoc-ref:doc/webauthn_modify_email.rdoc]
 * {WebAuthn Verify Account}[rdoc-ref:doc/webauthn_verify_account.rdoc]
 
 === Calling Rodauth in the Routing Tree

data/doc/base.rdoc

@@ -74,6 +74,7 @@ password_param :: The parameter name to use for passwords.
 require_login_error_flash :: The flash error to display when accessing a page that requires a login, when you are not logged in.
 require_login_redirect :: A redirect to the login page.
 set_deadline_values? :: Whether deadline values should be set.  True by default on MySQL, as that doesn't support default values that are not constant.  Can be set to true on other databases if you want to vary the value based on a request parameter.
+strftime_format :: The format to pass to Time#strftime when formatting timestamps to display to the user, '%F %T' by default.
 template_opts :: Any template options to pass to view/render.  This can be used to set a custom layout, for example.
 token_separator :: The string used to separate account id from the random key in links.
 unmatched_field_error_status :: The response status to use when two field values should match but do not, 422 by default.
@@ -84,6 +85,7 @@ use_request_specific_csrf_tokens? :: Whether to use request-specific CSRF tokens
 
 == Auth Methods
 
+account_from_id(id, status_id=nil) :: Retrieve the account hash for the given account id and status.
 account_from_login(login) :: Retrieve the account hash related to the given login or nil if no login matches.
 account_from_session :: Retrieve the account hash related to the currently logged in session.
 account_id :: The primary key value of the current account.

data/doc/otp_lockout_email.rdoc

@@ -0,0 +1,30 @@
+= Documentation for OTP Lockout Email Feature
+
+The otp_lockout_email feature emails users when:
+
+* TOTP authentication is locked out
+* TOTP authentication is unlocked
+* A TOTP unlock attempt has failed
+
+The otp_unlock_email feature depends on the otp_lockout and email_base features.
+
+== Auth Value Methods
+
+otp_locked_out_email_body :: Body to use for the email notifying user that TOTP authentication has been locked out.
+otp_locked_out_email_subject :: Subject to use for the email notifying user that TOTP authentication has been locked out.
+otp_unlock_failed_email_body :: Body to use for the email notifying user that there has been an unsuccessful attempt to unlock TOTP authentication.
+otp_unlock_failed_email_subject :: Subject to use for the email notifying user that there has been an unsuccessful attempt to unlock TOTP authentication.
+otp_unlocked_email_body :: Body to use for the email notifying user that TOTP authentication has been unlocked.
+otp_unlocked_email_subject :: Subject to use for the email notifying user that TOTP authentication has been unlocked.
+send_otp_locked_out_email? :: Whether to send an email when TOTP authentication is locked out.
+send_otp_unlock_failed_email? :: Whether to send an email when there has been an unsuccessful attempt to unlock TOTP authentication.
+send_otp_unlocked_email? :: Whether to send an email when TOTP authentication is unlocked.
+
+== Auth Methods
+
+create_otp_locked_out_email :: A Mail::Message for the email notifying user that TOTP authentication has been locked out.
+create_otp_unlock_failed_email :: A Mail::Message for the email notifying user that there has been an unsuccessful attempt to unlock TOTP authentication.
+create_otp_unlocked_email :: A Mail::Message for the email notifying user that TOTP authentication has been unlocked.
+send_otp_locked_out_email :: Send the email notifying user that TOTP authentication has been locked out.
+send_otp_unlock_failed_email :: Send the email notifying user that there has been an unsuccessful attempt to unlock TOTP authentication.
+send_otp_unlocked_email :: Send the email notifying user that TOTP authentication has been unlocked.

data/doc/otp_modify_email.rdoc

@@ -0,0 +1,19 @@
+= Documentation for OTP Modify Email Feature
+
+The otp_modify_email feature emails users when TOTP authentication is setup or disabled.
+
+The otp_modify_email feature depends on the otp and email_base features.
+
+== Auth Value Methods
+
+otp_disabled_email_body :: Body to use for the email notifying user that TOTP authentication has been disabled.
+otp_disabled_email_subject :: Subject to use for the email notifying user that TOTP authentication has been disabled.
+otp_setup_email_body :: Body to use for the email notifying user that TOTP authentication has been setup.
+otp_setup_email_subject :: Subject to use for the email notifying user that TOTP authentication has been setup.
+
+== Auth Methods
+
+create_otp_disabled_email :: A Mail::Message for the email notifying user that TOTP authentication has been disabled.
+create_otp_setup_email :: A Mail::Message for the email notifying user that TOTP authentication has been setup.
+send_otp_disabled_email :: Send the email notifying user that TOTP authentication has been disabled.
+send_otp_setup_email :: Send the email notifying user that TOTP authentication has been setup.

data/doc/otp_unlock.rdoc

@@ -0,0 +1,58 @@
+= Documentation for OTP Unlock Feature
+
+The otp_unlock feature implements unlocking of TOTP authentication after
+TOTP authentication.  The user must consecutively successfully authenticate
+with TOTP multiple times (default: 3) within a given time period (15 minutes
+per attempt) in order to unlock TOTP authentication.  By requiring
+consecutive successful unlocks, with a delay after failure, it is infeasible
+to brute force the TOTP unlock process.
+
+The otp_unlock feature depends on the otp feature.
+
+== Auth Value Methods
+
+otp_unlock_additional_form_tags :: HTML fragment containing additional form tags to use on the OTP unlock form.
+otp_unlock_auth_deadline_passed_error_flash :: The flash error to show if attempting to unlock OTP after the deadline for submittal has passed.
+otp_unlock_auth_deadline_passed_error_status :: The response status to use if attempting to unlock OTP after the deadline for submittal has passed, 403 by default.
+otp_unlock_auth_failure_cooldown_seconds :: The number of seconds the user must wait to attempt OTP unlock again after a failed OTP unlock attempt.
+otp_unlock_auth_failure_error_flash :: The flash error to show if attempting to unlock OTP using an incorrect authentication code.
+otp_unlock_auth_failure_error_status :: The response status to use if attempting to unlock OTP using an incorrect authentication code, 403 by default.
+otp_unlock_auth_not_yet_available_error_flash :: The flash error to show if attempting to unlock OTP when doing so is not yet available due to a recent attempt.
+otp_unlock_auth_not_yet_available_error_status :: The response status to use if attempting to unlock OTP when doing so is not yet available due to a recent attempt, 403 by default.
+otp_unlock_auth_success_notice_flash :: The flash notice to show upon successful unlock authentication, when additional unlock authentication is still needed.
+otp_unlock_auths_required :: The number of consecutive successful authentication attempts needed to unlock OTP authentication, 3 by default.
+otp_unlock_button :: Text to use for button on OTP unlock form.
+otp_unlock_consecutive_successes_label :: Text to show next to the number of consecutive successful authentication attempts the user has already made.
+otp_unlock_deadline_seconds :: The number of seconds between a previously successful authentication attempt and the next successful authentication attempt. This defaults to twice the amount of time of the OTP interval (30 seconds) plus twice the amount of allowed drift (30 seconds), for a total of 120 seconds.  This is to make sure the same OTP code cannot be used more than one when unlocking.
+otp_unlock_form_footer :: A footer to display at the bottom of the OTP unlock form.
+otp_unlock_id_column :: The column in the +otp_unlock_table+ containing the account id.
+otp_unlock_next_auth_attempt_after_column :: The column in the +otp_unlock_table+ containing a timestamp for when the user can next try an authentication attempt.
+otp_unlock_next_auth_attempt_label :: Text to show next to the time when the next unlock authentication attempt will be allowed.
+otp_unlock_next_auth_attempt_refresh_label :: Text to show explaining that the page will refresh when the next unlock authentication attempt will be allowed.
+otp_unlock_next_auth_deadline_label :: Text to show next to the deadline for unlock authentication.
+otp_unlock_not_available_page_title :: The page title to use on the page letting users know they need to wait to unlock OTP authentication.
+otp_unlock_not_locked_out_error_flash :: The flash error to show if attempting to access the OTP unlock page when OTP authentication is not locked out.
+otp_unlock_not_locked_out_error_status :: The response status to use if attempting to access the OTP unlock page when OTP authentication is not locked out, 403 by default.
+otp_unlock_not_locked_out_redirect :: Where to redirect if attempting to access the OTP unlock page when OTP authentication is not locked out.
+otp_unlock_num_successes_column :: The column in the +otp_unlock_table+ containing the number of consecutive successful authentications.
+otp_unlock_page_title :: The page title to use on the OTP unlock form.
+otp_unlock_refresh_tag :: The meta refresh tag HTML to use to force a refresh of the page.  This can be overridden to use a different refresh approach.
+otp_unlock_required_consecutive_successes_label :: Text to show next to the number of consecutive successful authentication attempts the user is required to make to unlock OTP authentication.
+otp_unlock_route :: The route to the OTP unlock action. Defaults to +otp-unlock+.
+otp_unlock_table :: The table name containing the OTP unlock information.
+otp_unlocked_notice_flash :: The flash notice to show when OTP authentication is successfully fully unlocked.
+otp_unlocked_redirect :: Where to redirect when OTP authentication is successfully fully unlocked.
+
+== Auth Methods
+
+after_otp_unlock_auth_failure :: Run arbitrary code after OTP unlock authentication failure.
+after_otp_unlock_auth_success :: Run arbitrary code after OTP unlock authentication success.
+after_otp_unlock_not_yet_available :: Run arbitrary code when attempting OTP unlock when it is not yet available.
+before_otp_unlock_attempt :: Run arbitrary code before checking whether OTP unlock authentication code is valid.
+before_otp_unlock_route :: Run arbitrary code before handling an OTP unlock route.
+otp_unlock_auth_failure :: Handle a authentication failure when trying to unlock.  By default, this sets the number of consecutive successful authentication attempts to 0, and forces a significant delay before the next unlock authentication attempt can be made.
+otp_unlock_auth_success :: Handle a authentication failure when trying to unlock.  By default, this increments the number of consecutive successful authentication attempts, and imposes a short delay before the next unlock authentication attempt can be made (to ensure the code cannot be reused).
+otp_unlock_available? :: Returns whether it is possible to unlock OTP authentication. This assumes that OTP is already locked out.
+otp_unlock_deadline_passed? :: Returns whether the deadline to submit an OTP unlock authentication code has passed.
+otp_unlock_not_available_view :: The HTML to use for the page when the OTP unlock form is not yet available due to a recent unlock authentication attempt.
+otp_unlock_view :: The HTML to use for the OTP unlock form.

data/doc/release_notes/2.36.0.txt

@@ -0,0 +1,35 @@
+= New Features
+
+* An otp_unlock feature has been added, allowing a user to unlock
+  TOTP authentication with 3 consecutive successful TOTP
+  authentications.  Previously, once TOTP authentication was locked
+  out, there was no way for the user to unlock it.
+
+  Any unsuccessful TOTP authentication during the unlock process
+  prevents unlocks attempts for a configurable amount of time (15
+  minutes by default).  By default, this limits brute force attempts
+  to unlock TOTP authentication to less than 10^2 per day, with the
+  odds of a successful unlock in each attempt being 1 in 10^18.
+
+* An otp_lockout_email feature has been added for emailing the user
+  when their TOTP authentication has been locked out or unlocked, and
+  when there has been a failed unlock attempt.
+
+* An otp_modify_email feature has been added for emailing the user
+  when TOTP authentication has been setup or disabled for their
+  account.
+
+* A webauthn_modify_email feature has been added for emailing the
+  user when a WebAuthn authenticator has been added or removed from
+  their account.
+
+* An account_from_id configuration method has been added for loading
+  the account with the given account id.
+
+* A strftime_format configuration method has been added for
+  configuring how Time values are formatted for display to the user.
+
+= Improvements
+
+* The internal_request feature now works with Roda's path_rewriter
+  plugin.

data/doc/webauthn_modify_email.rdoc

@@ -0,0 +1,19 @@
+= Documentation for WebAuthn Modify Email Feature
+
+The webauthn_modify_email feature emails users when a WebAuthn authenticator is added to or removed from their account.
+
+The webauthn_modify_email feature depends on the webauthn and email_base features.
+
+== Auth Value Methods
+
+webauthn_authenticator_added_email_body :: Body to use for the email notifying user that a WebAuthn authenticator has been added to their account.
+webauthn_authenticator_added_email_subject :: Subject to use for the email notifying user that a WebAuthn authenticator has been added to their account.
+webauthn_authenticator_removed_email_body :: Body to use for the email notifying user that a WebAuthn authenticator has been removed from their account.
+webauthn_authenticator_removed_email_subject :: Subject to use for the email notifying user that a WebAuthn authenticator has been removed from their account.
+
+== Auth Methods
+
+create_webauthn_authenticator_added_email :: A Mail::Message for the email notifying user that a WebAuthn authenticator has been added to their account.
+create_webauthn_authenticator_removed_email :: A Mail::Message for the email notifying user that a WebAuthn authenticator has been removed from their account.
+send_webauthn_authenticator_added_email :: Send the email notifying user that a WebAuthn authenticator has been added to their account.
+send_webauthn_authenticator_removed_email :: Send the email notifying user that a WebAuthn authenticator has been removed from their account.

data/lib/rodauth/features/base.rb

@@ -59,6 +59,7 @@ module Rodauth
     auth_value_method :mark_input_fields_with_autocomplete?, true
     auth_value_method :mark_input_fields_with_inputmode?, true
     auth_value_method :skip_status_checks?, true
+    translatable_method :strftime_format, '%F %T'
     auth_value_method :template_opts, {}.freeze
     auth_value_method :title_instance_variable, nil 
     auth_value_method :token_separator, "_"
@@ -115,6 +116,7 @@ module Rodauth
     )
 
     auth_private_methods(
+      :account_from_id,
       :account_from_login,
       :account_from_session,
       :convert_token_id,
@@ -384,6 +386,10 @@ module Rodauth
       @account = _account_from_session
     end
 
+    def account_from_id(id, status_id=nil)
+      @account = _account_from_id(id, status_id)
+    end
+
     def check_csrf
       scope.check_csrf!(check_csrf_opts, &check_csrf_block)
     end
@@ -739,6 +745,12 @@ module Rodauth
       ds.first
     end
 
+    def _account_from_id(id, status_id=nil)
+      ds = account_ds(id)
+      ds = ds.where(account_status_column=>status_id) if status_id && !skip_status_checks?
+      ds.first
+    end
+
     def hmac_secret_rotation?
       hmac_secret && hmac_old_secret && hmac_secret != hmac_old_secret
     end

data/lib/rodauth/features/email_base.rb

@@ -74,9 +74,7 @@ module Rodauth
          ((!hmac_secret || allow_raw_email_token?) && timing_safe_eql?(key, actual))
         return
       end
-      ds = account_ds(id)
-      ds = ds.where(account_status_column=>status_id) if status_id && !skip_status_checks?
-      ds.first
+      _account_from_id(id, status_id)
     end
   end
 end

data/lib/rodauth/features/internal_request.rb

@@ -183,9 +183,7 @@ module Rodauth
     def account_from_key(token, status_id=nil)
       return super unless session_value
       return unless yield session_value
-      ds = account_ds(session_value)
-      ds = ds.where(account_status_column=>status_id) if status_id && !skip_status_checks?
-      ds.first
+      _account_from_id(session_value, status_id)
     end
 
     def _set_internal_request_return_value(value)
@@ -210,7 +208,7 @@ module Rodauth
     end
 
     def _set_login_param_from_account
-      if session_value && !params[login_param] && (account = account_ds(session_value).first)
+      if session_value && !params[login_param] && (account = _account_from_id(session_value))
         params[login_param] = account[login_column]
       end
     end
@@ -311,7 +309,7 @@ module Rodauth
       
       env = {
          'REQUEST_METHOD'=>'POST',
-         'PATH_INFO'=>'/',
+         'PATH_INFO'=>'/'.dup,
          "SCRIPT_NAME" => "",
          "HTTP_HOST" => INVALID_DOMAIN,
          "SERVER_NAME" => INVALID_DOMAIN,

data/lib/rodauth/features/json.rb

@@ -72,6 +72,32 @@ module Rodauth
 
     private
 
+    def _set_otp_unlock_info
+      if use_json?
+        json_response[:num_successes] = otp_unlock_num_successes
+        json_response[:required_successes] = otp_unlock_auths_required
+        json_response[:next_attempt_after] = otp_unlock_next_auth_attempt_after.to_i
+      end
+    end
+
+    def after_otp_unlock_auth_success
+      super if defined?(super)
+      if otp_locked_out?
+        _set_otp_unlock_info
+        json_response[:deadline] = otp_unlock_deadline.to_i
+      end
+    end
+
+    def after_otp_unlock_auth_failure
+      super if defined?(super)
+      _set_otp_unlock_info
+    end
+
+    def after_otp_unlock_not_yet_available
+      super if defined?(super)
+      _set_otp_unlock_info
+    end
+
     def before_two_factor_manage_route
       super if defined?(super)
       if use_json?

data/lib/rodauth/features/otp.rb

@@ -287,7 +287,7 @@ module Rodauth
 
     def otp_update_last_use
       otp_key_ds.
-        where(Sequel.date_add(otp_keys_last_use_column, :seconds=>(otp_interval||30)) < Sequel::CURRENT_TIMESTAMP).
+        where(Sequel.date_add(otp_keys_last_use_column, :seconds=>_otp_interval) < Sequel::CURRENT_TIMESTAMP).
         update(otp_keys_last_use_column=>Sequel::CURRENT_TIMESTAMP) == 1
     end
 
@@ -346,7 +346,7 @@ module Rodauth
 
     def _two_factor_auth_links
       links = super
-      links << [20, otp_auth_path, otp_auth_link_text] if otp_available?
+      links << [20, otp_auth_path, otp_auth_link_text] if show_otp_auth_link?
       links
     end
 
@@ -420,6 +420,10 @@ module Rodauth
       @otp_key = secret
     end
 
+    def _otp_interval
+      otp_interval || 30
+    end
+
     # Called for valid OTP codes for old secrets
     def _otp_valid_code_for_old_secret
     end
@@ -447,6 +451,10 @@ module Rodauth
       db[otp_keys_table].where(otp_keys_id_column=>session_value)
     end
 
+    def show_otp_auth_link?
+      otp_available?
+    end
+
     def use_date_arithmetic?
       true
     end

data/lib/rodauth/features/otp_lockout_email.rb

@@ -0,0 +1,42 @@
+# frozen-string-literal: true
+
+module Rodauth
+  Feature.define(:otp_lockout_email, :OtpLockoutEmail) do
+    depends :otp_unlock, :email_base
+
+    loaded_templates %w'otp-locked-out-email otp-unlocked-email otp-unlock-failed-email'
+    email :otp_locked_out, 'TOTP Authentication Locked Out', :translatable=>true
+    email :otp_unlocked, 'TOTP Authentication Unlocked', :translatable=>true
+    email :otp_unlock_failed, 'TOTP Authentication Unlocking Failed', :translatable=>true
+
+    auth_value_method :send_otp_locked_out_email?, true
+    auth_value_method :send_otp_unlocked_email?, true
+    auth_value_method :send_otp_unlock_failed_email?, true
+
+    private
+
+    def after_otp_authentication_failure
+      super
+
+      if otp_locked_out? && send_otp_locked_out_email?
+        send_otp_locked_out_email
+      end
+    end
+
+    def after_otp_unlock_auth_success
+      super
+
+      if !otp_locked_out? && send_otp_unlocked_email?
+        send_otp_unlocked_email
+      end
+    end
+
+    def after_otp_unlock_auth_failure
+      super
+
+      if send_otp_unlock_failed_email?
+        send_otp_unlock_failed_email
+      end
+    end
+  end
+end

data/lib/rodauth/features/otp_modify_email.rb

@@ -0,0 +1,23 @@
+# frozen-string-literal: true
+
+module Rodauth
+  Feature.define(:otp_modify_email, :OtpModifyEmail) do
+    depends :otp, :email_base
+
+    loaded_templates %w'otp-setup-email otp-disabled-email'
+    email :otp_setup, 'TOTP Authentication Setup', :translatable=>true
+    email :otp_disabled, 'TOTP Authentication Disabled', :translatable=>true
+
+    private
+
+    def after_otp_setup
+      super
+      send_otp_setup_email
+    end
+
+    def after_otp_disable
+      super
+      send_otp_disabled_email
+    end
+  end
+end

data/lib/rodauth/features/otp_unlock.rb

@@ -0,0 +1,250 @@
+# frozen-string-literal: true
+
+module Rodauth
+  Feature.define(:otp_unlock, :OtpUnlock) do
+    depends :otp
+
+    before 'otp_unlock_attempt'
+    after 'otp_unlock_auth_success'
+    after 'otp_unlock_auth_failure'
+    after 'otp_unlock_not_yet_available'
+
+    error_flash "TOTP authentication is not currently locked out", 'otp_unlock_not_locked_out'
+    error_flash "TOTP invalid authentication", 'otp_unlock_auth_failure'
+    error_flash "Deadline past for unlocking TOTP authentication", 'otp_unlock_auth_deadline_passed'
+    error_flash "TOTP unlock attempt not yet available", 'otp_unlock_auth_not_yet_available'
+
+    notice_flash "TOTP authentication unlocked", 'otp_unlocked'
+    notice_flash "TOTP successful authentication, more successful authentication needed to unlock", 'otp_unlock_auth_success'
+
+    redirect :otp_unlock_not_locked_out
+    redirect :otp_unlocked
+
+    additional_form_tags
+
+    button 'Authenticate Using TOTP to Unlock', 'otp_unlock'
+
+    auth_value_method :otp_unlock_auth_deadline_passed_error_status, 403
+    auth_value_method :otp_unlock_auth_failure_cooldown_seconds, 900
+    auth_value_method :otp_unlock_auth_failure_error_status, 403
+    auth_value_method :otp_unlock_auth_not_yet_available_error_status, 403
+    auth_value_method :otp_unlock_auths_required, 3
+    auth_value_method :otp_unlock_deadline_seconds, 900
+    auth_value_method :otp_unlock_id_column, :id
+    auth_value_method :otp_unlock_next_auth_attempt_after_column, :next_auth_attempt_after
+    auth_value_method :otp_unlock_not_locked_out_error_status, 403
+    auth_value_method :otp_unlock_num_successes_column, :num_successes
+    auth_value_method :otp_unlock_table, :account_otp_unlocks
+
+    translatable_method :otp_unlock_consecutive_successes_label, 'Consecutive successful authentications'
+    translatable_method :otp_unlock_form_footer, ''
+    translatable_method :otp_unlock_next_auth_attempt_label, 'Can attempt next authentication after'
+    translatable_method :otp_unlock_next_auth_attempt_refresh_label, 'Page will automatically refresh when authentication is possible.'
+    translatable_method :otp_unlock_next_auth_deadline_label, 'Deadline for next authentication'
+    translatable_method :otp_unlock_required_consecutive_successes_label, 'Required consecutive successful authentications to unlock'
+
+    loaded_templates %w'otp-unlock otp-unlock-not-available'
+    view 'otp-unlock', 'Unlock TOTP Authentication', 'otp_unlock'
+    view 'otp-unlock-not-available', 'Must Wait to Unlock TOTP Authentication', 'otp_unlock_not_available'
+
+    auth_methods(
+      :otp_unlock_auth_failure,
+      :otp_unlock_auth_success,
+      :otp_unlock_available?,
+      :otp_unlock_deadline_passed?,
+      :otp_unlock_refresh_tag,
+    )
+
+    route(:otp_unlock) do |r|
+      require_login
+      require_account_session
+      require_otp_setup
+
+      unless otp_locked_out?
+        set_response_error_reason_status(:otp_not_locked_out, otp_unlock_not_locked_out_error_status)
+        set_redirect_error_flash otp_unlock_not_locked_out_error_flash
+        redirect otp_unlock_not_locked_out_redirect
+      end
+
+      before_otp_unlock_route
+
+      r.get do
+        if otp_unlock_available?
+          otp_unlock_view
+        else
+          otp_unlock_not_available_view
+        end
+      end
+
+      r.post do
+        db.transaction do
+          if otp_unlock_deadline_passed?
+            set_response_error_reason_status(:otp_unlock_deadline_passed, otp_unlock_auth_deadline_passed_error_status)
+            set_redirect_error_flash otp_unlock_auth_deadline_passed_error_flash
+          elsif !otp_unlock_available?
+            after_otp_unlock_not_yet_available
+            set_response_error_reason_status(:otp_unlock_not_yet_available, otp_unlock_auth_not_yet_available_error_status)
+            set_redirect_error_flash otp_unlock_auth_not_yet_available_error_flash
+          else
+            before_otp_unlock_attempt
+            if otp_valid_code?(param(otp_auth_param))
+              otp_unlock_auth_success
+              after_otp_unlock_auth_success
+
+              unless otp_locked_out?
+                set_notice_flash otp_unlocked_notice_flash
+                redirect otp_unlocked_redirect
+              end
+
+              set_notice_flash otp_unlock_auth_success_notice_flash
+            else
+              otp_unlock_auth_failure
+              after_otp_unlock_auth_failure
+              set_response_error_reason_status(:otp_unlock_auth_failure, otp_unlock_auth_failure_error_status)
+              set_redirect_error_flash otp_unlock_auth_failure_error_flash
+            end
+          end
+        end
+
+        redirect request.path
+      end
+    end
+
+    def otp_unlock_available?
+      if otp_unlock_data
+        next_auth_attempt_after = otp_unlock_next_auth_attempt_after
+        current_timestamp = Time.now
+
+        if (next_auth_attempt_after < current_timestamp - otp_unlock_deadline_seconds)
+          # Unlock process not fully completed within deadline, reset process
+          otp_unlock_reset
+          true
+        else
+          if next_auth_attempt_after > current_timestamp
+            # If next auth attempt after timestamp is in the future, that means the next
+            # unlock attempt cannot happen until then.
+            false 
+          else
+            if otp_unlock_num_successes == 0
+              # 0 value indicates previous attempt was a failure. Since failure cooldown
+              # period has passed, reset process so user gets full deadline period
+              otp_unlock_reset
+            end
+            true
+          end
+        end
+      else
+        # No row means no unlock attempts yet (or previous attempt was more than the
+        # deadline account, so unlocking is available
+        true
+      end
+    end
+
+    def otp_unlock_auth_failure
+      h = {
+        otp_unlock_num_successes_column=>0,
+        otp_unlock_next_auth_attempt_after_column=>Sequel.date_add(Sequel::CURRENT_TIMESTAMP, :seconds=>otp_unlock_auth_failure_cooldown_seconds)
+      }
+
+      if otp_unlock_ds.update(h) == 0
+        h[otp_unlock_id_column] = session_value
+
+        # If row already exists when inserting, no need to do anything
+        raises_uniqueness_violation?{otp_unlock_ds.insert(h)}
+      end
+    end
+
+    def otp_unlock_auth_success
+      deadline = Sequel.date_add(Sequel::CURRENT_TIMESTAMP, :seconds=>otp_unlock_success_cooldown_seconds)
+
+      # Add WHERE to avoid possible race condition when multiple unlock auth requests
+      # are sent at the same time (only the first should increment num successes).
+      if otp_unlock_ds.
+          where(Sequel[otp_unlock_next_auth_attempt_after_column] < Sequel::CURRENT_TIMESTAMP).
+          update(
+            otp_unlock_num_successes_column=>Sequel[otp_unlock_num_successes_column]+1,
+            otp_unlock_next_auth_attempt_after_column=>deadline
+          ) == 0
+
+        # Ignore uniqueness errors when inserting after a failed update, 
+        # which could be caused due to the race condition mentioned above.
+        raises_uniqueness_violation? do
+          otp_unlock_ds.insert(
+            otp_unlock_id_column=>session_value,
+            otp_unlock_next_auth_attempt_after_column=>deadline
+          )
+        end
+      end
+
+      @otp_unlock_data = nil
+      # :nocov:
+      if otp_unlock_data
+      # :nocov:
+        if otp_unlock_num_successes >= otp_unlock_auths_required
+          # At least the requisite number of consecutive successful unlock
+          # authentications. Unlock OTP authentication.
+          otp_key_ds.update(otp_keys_failures_column => 0)
+
+          # Remove OTP unlock metadata when unlocking OTP authentication
+          otp_unlock_reset
+        # else
+        #  # Still need additional consecutive successful unlock attempts.
+        end
+      # else
+      #  # if row isn't available, probably the process was reset during this,
+      #  # and it's safe to do nothing in that case.
+      end
+    end
+
+    def otp_unlock_deadline_passed?
+      otp_unlock_data ? (otp_unlock_next_auth_attempt_after < Time.now - otp_unlock_deadline_seconds) : false
+    end
+
+    def otp_unlock_refresh_tag
+      "<meta http-equiv=\"refresh\" content=\"#{(otp_unlock_next_auth_attempt_after - Time.now).to_i + 1}\">"
+    end
+
+    def otp_lockout_redirect
+      otp_unlock_path
+    end
+
+    def otp_unlock_next_auth_attempt_after
+      if otp_unlock_data
+        convert_timestamp(otp_unlock_data[otp_unlock_next_auth_attempt_after_column])
+      else
+        Time.now
+      end
+    end
+
+    def otp_unlock_deadline
+      otp_unlock_next_auth_attempt_after + otp_unlock_deadline_seconds
+    end
+
+    def otp_unlock_num_successes
+      otp_unlock_data ? otp_unlock_data[otp_unlock_num_successes_column] : 0
+    end
+
+    private
+
+    def show_otp_auth_link?
+      super || (otp_exists? && otp_locked_out?)
+    end
+
+    def otp_unlock_data
+      @otp_unlock_data ||= otp_unlock_ds.first
+    end
+
+    def otp_unlock_success_cooldown_seconds
+      (_otp_interval+(otp_drift||0))*2
+    end
+
+    def otp_unlock_reset
+      otp_unlock_ds.delete
+      @otp_unlock_data = nil
+    end
+
+    def otp_unlock_ds
+      db[otp_unlock_table].where(otp_unlock_id_column=>session_value)
+    end
+  end
+end

data/lib/rodauth/features/webauthn_autofill.rb

@@ -53,7 +53,7 @@ module Rodauth
         throw_error_reason(:invalid_webauthn_id, invalid_field_error_status, webauthn_auth_param, webauthn_invalid_webauthn_id_message)
       end
 
-      @account = account_ds(account_id).first
+      account_from_id(account_id)
     end
 
     def webauthn_login_options?

data/lib/rodauth/features/webauthn_modify_email.rb

@@ -0,0 +1,23 @@
+# frozen-string-literal: true
+
+module Rodauth
+  Feature.define(:webauthn_modify_email, :WebauthnModifyEmail) do
+    depends :webauthn, :email_base
+
+    loaded_templates %w'webauthn-authenticator-added-email webauthn-authenticator-removed-email'
+    email :webauthn_authenticator_added, 'WebAuthn Authenticator Added', :translatable=>true
+    email :webauthn_authenticator_removed, 'WebAuthn Authenticator Removed', :translatable=>true
+
+    private
+
+    def after_webauthn_setup
+      super
+      send_webauthn_authenticator_added_email
+    end
+
+    def after_webauthn_remove
+      super
+      send_webauthn_authenticator_removed_email
+    end
+  end
+end

data/lib/rodauth/version.rb

@@ -6,7 +6,7 @@ module Rodauth
   MAJOR = 2
 
   # The minor version of Rodauth, updated for new feature releases of Rodauth.
-  MINOR = 35
+  MINOR = 36
 
   # The patch version of Rodauth, updated only for bug fixes from the last
   # feature release.

data/templates/otp-disabled-email.str

@@ -0,0 +1,2 @@
+Someone (hopefully you) has disabled TOTP authentication for the account
+associated to this email address.

data/templates/otp-locked-out-email.str

@@ -0,0 +1,9 @@
+TOTP authentication has been locked out on your account due to too many
+consecutive authentication failures. You can attempt to unlock TOTP
+authentication for your account by consecutively authenticating via
+TOTP multiple times.
+
+If you did not initiate the TOTP authentication failures that
+caused TOTP authentication to be locked out, that means someone already
+has partial access to your account, but is unable to use TOTP
+authentication to fully authenticate themselves.

data/templates/otp-setup-email.str

@@ -0,0 +1,2 @@
+Someone (hopefully you) has setup TOTP authentication for the account
+associated to this email address.

data/templates/otp-unlock-failed-email.str

@@ -0,0 +1,8 @@
+Someone (hopefully you) attempted to unlock TOTP authentication for the
+account associated to this email address, but failed as the
+authentication code submitted was not correct.
+
+If you did not initiate the TOTP authentication failure that generated
+this email, that means someone already has partial access to your
+account, but is unable to use TOTP authentication to fully authenticate
+themselves.

data/templates/otp-unlock-not-available.str

@@ -0,0 +1,5 @@
+<p>#{rodauth.otp_unlock_consecutive_successes_label}: #{rodauth.otp_unlock_num_successes}</p>
+<p>#{rodauth.otp_unlock_required_consecutive_successes_label}: #{rodauth.otp_unlock_auths_required}</p>
+<p>#{rodauth.otp_unlock_next_auth_attempt_label}: #{rodauth.otp_unlock_next_auth_attempt_after.strftime(rodauth.strftime_format)}</p>
+<p>#{rodauth.otp_unlock_next_auth_attempt_refresh_label}</p>
+#{rodauth.otp_unlock_refresh_tag}

data/templates/otp-unlock.str

@@ -0,0 +1,11 @@
+<form method="post" class="rodauth" role="form" id="otp-unlock-form">
+  #{rodauth.otp_unlock_additional_form_tags}
+  #{rodauth.csrf_tag}
+  <p>#{rodauth.otp_unlock_consecutive_successes_label}: #{rodauth.otp_unlock_num_successes}</p>
+  <p>#{rodauth.otp_unlock_required_consecutive_successes_label}: #{rodauth.otp_unlock_auths_required}</p>
+  <p>#{rodauth.otp_unlock_next_auth_deadline_label}: #{rodauth.otp_unlock_deadline.strftime(rodauth.strftime_format)}</p>
+  #{rodauth.render('otp-auth-code-field')}
+  #{rodauth.button(rodauth.otp_unlock_button)}
+</form>
+
+#{rodauth.otp_unlock_form_footer}

data/templates/otp-unlocked-email.str

@@ -0,0 +1,2 @@
+Someone (hopefully you) has unlocked TOTP authentication for the account
+associated to this email address.

data/templates/webauthn-authenticator-added-email.str

@@ -0,0 +1,3 @@
+Someone (hopefully you) has added a WebAuthn authenticator to the
+account associated to this email address. There are now #{rodauth.account_webauthn_ids.length} WebAuthn
+authenticator(s) with access to the account.

data/templates/webauthn-authenticator-removed-email.str

@@ -0,0 +1,3 @@
+Someone (hopefully you) has removed a WebAuthn authenticator from the
+account associated to this email address. There are now #{rodauth.account_webauthn_ids.length} WebAuthn
+authenticator(s) with access to the account.

data/templates/webauthn-remove.str

@@ -4,7 +4,7 @@
   #{rodauth.render('password-field') if rodauth.two_factor_modifications_require_password?}
   <fieldset class="form-group mb-3">
     #{(usage = rodauth.account_webauthn_usage; last_id = usage.keys.last; usage;).map do |id, last_use|
-      last_use = last_use.strftime("%F %T") if last_use.is_a?(Time)
+      last_use = last_use.strftime(rodauth.strftime_format) if last_use.is_a?(Time)
       input = rodauth.input_field_string(rodauth.webauthn_remove_param, "webauthn-remove-#{h id}", :type=>'radio', :class=>"form-check-input", :skip_error_message=>true, :value=>id, :required=>false)
       label = "<label class=\"rodauth-webauthn-id form-check-label\" for=\"webauthn-remove-#{h id}\">Last Use: #{last_use}</label>"
       error = rodauth.formatted_field_error(rodauth.webauthn_remove_param) if id == last_id

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rodauth
 version: !ruby/object:Gem::Version
-  version: 2.35.0
+  version: 2.36.0
 platform: ruby
 authors:
 - Jeremy Evans
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-05-28 00:00:00.000000000 Z
+date: 2024-07-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sequel
@@ -278,6 +278,9 @@ extra_rdoc_files:
 - doc/login_password_requirements_base.rdoc
 - doc/logout.rdoc
 - doc/otp.rdoc
+- doc/otp_lockout_email.rdoc
+- doc/otp_modify_email.rdoc
+- doc/otp_unlock.rdoc
 - doc/password_complexity.rdoc
 - doc/password_expiration.rdoc
 - doc/password_grace_period.rdoc
@@ -298,6 +301,7 @@ extra_rdoc_files:
 - doc/webauthn.rdoc
 - doc/webauthn_autofill.rdoc
 - doc/webauthn_login.rdoc
+- doc/webauthn_modify_email.rdoc
 - doc/webauthn_verify_account.rdoc
 - doc/release_notes/1.0.0.txt
 - doc/release_notes/1.1.0.txt
@@ -353,6 +357,7 @@ extra_rdoc_files:
 - doc/release_notes/2.33.0.txt
 - doc/release_notes/2.34.0.txt
 - doc/release_notes/2.35.0.txt
+- doc/release_notes/2.36.0.txt
 - doc/release_notes/2.4.0.txt
 - doc/release_notes/2.5.0.txt
 - doc/release_notes/2.6.0.txt
@@ -416,6 +421,9 @@ files:
 - doc/login_password_requirements_base.rdoc
 - doc/logout.rdoc
 - doc/otp.rdoc
+- doc/otp_lockout_email.rdoc
+- doc/otp_modify_email.rdoc
+- doc/otp_unlock.rdoc
 - doc/password_complexity.rdoc
 - doc/password_expiration.rdoc
 - doc/password_grace_period.rdoc
@@ -476,6 +484,7 @@ files:
 - doc/release_notes/2.33.0.txt
 - doc/release_notes/2.34.0.txt
 - doc/release_notes/2.35.0.txt
+- doc/release_notes/2.36.0.txt
 - doc/release_notes/2.4.0.txt
 - doc/release_notes/2.5.0.txt
 - doc/release_notes/2.6.0.txt
@@ -496,6 +505,7 @@ files:
 - doc/webauthn.rdoc
 - doc/webauthn_autofill.rdoc
 - doc/webauthn_login.rdoc
+- doc/webauthn_modify_email.rdoc
 - doc/webauthn_verify_account.rdoc
 - javascript/webauthn_auth.js
 - javascript/webauthn_autofill.js
@@ -528,6 +538,9 @@ files:
 - lib/rodauth/features/login_password_requirements_base.rb
 - lib/rodauth/features/logout.rb
 - lib/rodauth/features/otp.rb
+- lib/rodauth/features/otp_lockout_email.rb
+- lib/rodauth/features/otp_modify_email.rb
+- lib/rodauth/features/otp_unlock.rb
 - lib/rodauth/features/password_complexity.rb
 - lib/rodauth/features/password_expiration.rb
 - lib/rodauth/features/password_grace_period.rb
@@ -548,6 +561,7 @@ files:
 - lib/rodauth/features/webauthn.rb
 - lib/rodauth/features/webauthn_autofill.rb
 - lib/rodauth/features/webauthn_login.rb
+- lib/rodauth/features/webauthn_modify_email.rb
 - lib/rodauth/features/webauthn_verify_account.rb
 - lib/rodauth/migrations.rb
 - lib/rodauth/version.rb
@@ -573,7 +587,14 @@ files:
 - templates/otp-auth-code-field.str
 - templates/otp-auth.str
 - templates/otp-disable.str
+- templates/otp-disabled-email.str
+- templates/otp-locked-out-email.str
+- templates/otp-setup-email.str
 - templates/otp-setup.str
+- templates/otp-unlock-failed-email.str
+- templates/otp-unlock-not-available.str
+- templates/otp-unlock.str
+- templates/otp-unlocked-email.str
 - templates/password-changed-email.str
 - templates/password-confirm-field.str
 - templates/password-field.str
@@ -602,6 +623,8 @@ files:
 - templates/verify-login-change-email.str
 - templates/verify-login-change.str
 - templates/webauthn-auth.str
+- templates/webauthn-authenticator-added-email.str
+- templates/webauthn-authenticator-removed-email.str
 - templates/webauthn-autofill.str
 - templates/webauthn-remove.str
 - templates/webauthn-setup.str
@@ -636,7 +659,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.9
+rubygems_version: 3.5.11
 signing_key:
 specification_version: 4
 summary: Authentication and Account Management Framework for Rack Applications