Clear account tokens when an account change is made

Previously, the only account change that cleared all account tokens
was closing the account. If you reset your password, only the reset
password token was cleared, if you verified a login change, only the
verify login change token was cleared, etc. This changes the default
behavior to clear most account tokens when an account change is made.

The following account changes trigger clearing of tokens:

* change login
* close account
* reset password
* unlock account
* verify account

The following account tokens are cleared upon such actions:

* active sessions (other than logged in session)
* email auth
* jwt refresh (if not logged in)
* lockout (updates token if it exists)
* remember (creates and uses new remember token if logged in via remember token)
* reset password
* single session (if not logged in)
* verify account
* verify login change

This provides more secure behavior in some cases. Let's say you
notice something funny with your email. You request a password
change. However, then you realize someone has access to your email,
so you change your login. Previously, the password reset link for
the account is still valid after the email change, so an attacker
can still change the password on the account post login change.
With this commit, once the login has been changed, the reset
password token is no longer valid. Similarly, once the password has
been reset, the verify login change token is no longer valid.

While I think this makes for a more secure and more appropriate
default, it's possible that this behavior is not desirable for all
Rodauth installations. To allow for customization, a clear_tokens
configuration method is available. This takes a block that is
passed a symbol for the change being made. The user can override
the behavior for specific symbols. They can also call super with
the reason to get the default behavior of clearing all related
tokens.

This unfortunately requires a number of special cases so that it
does not break expected behavior. For active_sessions and
single_session, you don't want to clear a token used for the
current session, because otherwise changing your login would result
in a logout.  For lockout, you cannot clear the token, because that
would result in an account unlock, so instead the token is updated.
Remember is a mix between active_sessions/single_session and lockout,
where you want to clear the token if the session is not logged in
via remember, if the session is logged in via remember, you want
to update the session value, so that the current session stays
remembered.

For jwt_refresh, this does not clear refresh tokens if the session
is logged in, as we don't know which refresh token is for the
current session. Potentially that ability could be added in the
future, but this issue is simple to address by using the
active_sessions feature, so recommend that approach.

Author: jeremyevans

CHANGELOG

@@ -1,3 +1,7 @@
+=== master
+
+* Clear account tokens when an account change is made (jeremyevans)
+
 === 2.40.0 (2025-08-22)
 
 * Use HTTP header instead of meta tag for otp unlock not yet available page (jeremyevans)

doc/base.rdoc

@@ -35,6 +35,7 @@ cache_templates :: Whether to cache templates. True by default. It may be worth
 check_csrf? :: Whether Rodauth should use Roda's +check_csrf!+ method for checking CSRF tokens before dispatching to Rodauth routes, true by default.
 check_csrf_opts :: Options to pass to Roda's +check_csrf!+ if Rodauth calls it before dispatching.
 check_csrf_block :: Proc for block to pass to Roda's +check_csrf!+ if Rodauth calls it before dispatching.
+clear_tokens(reason) :: Called when there is an account change, clears tokens for the account. By examining the reason symbol you can get different behavior per action, but the default behavior is clear all tokens whenever there is an account. Clearing actions/reasons are +:reset_password+, +:verify_account+, +:change_login+, +:unlock_account+, and +close_account+. Tokens are cleared for the following features +reset_password+, +verify_account+, +verify_login_change+, +jwt_refresh+, +remember+, +email_auth+, +single_session+, and +active_sessions+.
 convert_token_id_to_integer? :: Whether token ids should be converted to a valid 64-bit integer value.  If not set, defaults to true if +account_id_column+ uses an integer type, and false otherwise.
 default_field_attributes :: The default attributes to use for input field tags, if field_attributes returns nil for the field.
 default_redirect :: Where to redirect after most successful actions.

doc/jwt_refresh.rdoc

@@ -25,6 +25,14 @@ If you change the +allow_refresh_with_expired_jwt_access_token?+ setting to +tru
 an expired but otherwise valid access token will be accepted, and Rodauth will check
 that the access token was issued in the same session as the refresh token.
 
+When an account change is made made during a logged in session (such as a login change),
+refresh tokens are not automatically invalidated, as Rodauth does not know which refresh
+token is being used for the current session. It is recommended that you use the
+active_sessions feature if you would like an account change during a logged in session
+to invalidate refresh tokens. Technically, this invalides the account tokens for other
+sessions and not the refresh tokens, but you need a valid access token to use the
+refresh token, so it has the same effect.
+
 This feature depends on the jwt feature.
 
 == Auth Value Methods

lib/rodauth/features/active_sessions.rb

@@ -125,6 +125,11 @@ def update_session
       add_active_session
     end
 
+    def clear_tokens(reason)
+      super
+      remove_all_active_sessions_except_current
+    end
+
     private
 
     def after_refresh_token

lib/rodauth/features/base.rb

@@ -93,6 +93,7 @@ module Rodauth
       :autocomplete_for_field?,
       :check_csrf,
       :clear_session,
+      :clear_tokens,
       :csrf_tag,
       :function_name,
       :hook_action,
@@ -330,6 +331,9 @@ def clear_session
       end
     end
 
+    def clear_tokens(reason)
+    end
+
     def login_required
       set_redirect_error_status(login_required_error_status)
       set_error_reason :login_required

lib/rodauth/features/change_login.rb

@@ -86,7 +86,9 @@ def _update_login(login)
       if raised
         set_login_requirement_error_message(:already_an_account_with_this_login, already_an_account_with_this_login_message)
       end
-      updated && !raised
+      change_made = updated && !raised
+      clear_tokens(:change_login) if change_made
+      change_made
     end
   end
 end

lib/rodauth/features/close_account.rb

@@ -45,11 +45,12 @@ module Rodauth
             before_close_account
             close_account
             after_close_account
+            clear_session
+            clear_tokens(:close_account)
             if delete_account_on_close?
               delete_account
             end
           end
-          clear_session
 
           close_account_response
         end

lib/rodauth/features/email_auth.rb

@@ -167,6 +167,11 @@ def email_auth_email_recently_sent?
       (email_last_sent = get_email_auth_email_last_sent) && (Time.now - email_last_sent < email_auth_skip_resend_email_within)
     end
 
+    def clear_tokens(reason)
+      super
+      remove_email_auth_key
+    end
+
     private
 
     def _multi_phase_login_forms
@@ -210,11 +215,6 @@ def after_login
       super
     end
 
-    def after_close_account
-      remove_email_auth_key
-      super if defined?(super)
-    end
-
     def generate_email_auth_key_value
       @email_auth_key_value = random_key
     end

lib/rodauth/features/jwt_refresh.rb

@@ -89,6 +89,11 @@ def account_from_refresh_token(token)
       @account = _account_from_refresh_token(token)
     end
 
+    def clear_tokens(reason)
+      super
+      jwt_refresh_token_account_ds(account_id).delete unless logged_in?
+    end
+
     private
 
     def rescue_jwt_payload(e)

lib/rodauth/features/lockout.rb

@@ -126,6 +126,7 @@ module Rodauth
           transaction do
             before_unlock_account
             unlock_account
+            clear_tokens(:unlock_account)
             after_unlock_account
             if unlock_account_autologin?
               autologin_session('unlock_account')
@@ -241,6 +242,11 @@ def unlock_account_email_recently_sent?
       (email_last_sent = get_unlock_account_email_last_sent) && (Time.now - email_last_sent < unlock_account_skip_resend_email_within)
     end
 
+    def clear_tokens(reason)
+      super
+      account_lockouts_ds.update(account_lockouts_key_column => generate_unlock_account_key)
+    end
+
     private
 
     attr_reader :unlock_account_key_value