[PM-40673] Two Factor Remember Token Updates (Part 3)

src/Admin/Auth/Jobs/DeleteExpiredTwoFactorRememberTokensJob.cs

@@ -6,7 +6,7 @@
 namespace Bit.Admin.Auth.Jobs;
 
 /// <summary>
-/// Clears out remember-token rows whose expiry has passed. Hygiene rather than correctness — an
+/// Clears out `TwoFactorRememberToken` rows whose expiry has passed. Hygiene rather than correctness — an
 /// expired row is refused at validation time regardless, the row count is bounded by the number of
 /// devices, and the expiry index makes the sweep cheap. Weekly is sufficient.
 /// </summary>

src/Core/Auth/Entities/TwoFactorRememberToken.cs

@@ -5,7 +5,7 @@
 namespace Bit.Core.Auth.Entities;
 
 /// <summary>
-/// Server-side state backing a single remembered device's two-factor "remember me" token.
+/// Server-side state backing the 2FA remember token issued to a single device.
 /// One row per (<see cref="UserId"/>, <see cref="DeviceId"/>).
 /// </summary>
 /// <remarks>
@@ -19,12 +19,12 @@ public class TwoFactorRememberToken : ITableObject<Guid>
 
     /// <summary>
     /// The owning user. Derivable through <see cref="DeviceId"/>, but stored directly so that
-    /// revoking every remembered device for one user is an index seek.
+    /// revoking every 2FA remember token for one user is an index seek.
     /// </summary>
     public Guid UserId { get; set; }
 
     /// <summary>
-    /// The remembered device. Note this is <c>Device.Id</c>, not the client-supplied device identifier.
+    /// The device the 2FA remember token was issued to. Note this is <c>Device.Id</c>, not the client-supplied device identifier.
     /// </summary>
     public Guid DeviceId { get; set; }
 
@@ -35,7 +35,7 @@ public class TwoFactorRememberToken : ITableObject<Guid>
     public string Stamp { get; set; } = null!;
 
     /// <summary>
-    /// When this device was first remembered. Preserved when the row is re-issued.
+    /// When a 2FA remember token was first issued for this device. Preserved when the row is re-issued.
     /// </summary>
     public DateTime CreationDate { get; set; } = DateTime.UtcNow;
 

src/Core/Auth/Models/Business/Tokenables/TwoFactorRememberTokenable.cs

@@ -51,7 +51,7 @@ public class TwoFactorRememberTokenable : ExpiringTokenable
     public string Stamp { get; internal set; } = null!;
 
     // TODO: PM-44171 - Consider removing SecurityStamp from this token. The row's Stamp already
-    // covers the same ground more precisely, and carrying the user stamp ties remember-me lifetime
+    // covers the same ground more precisely, and carrying the user stamp ties 2FA remember token lifetime
     // to every user stamp rotation. Any removal has to stay backwards compatible: tokens already
     // issued carry this field, so treat it as optional on read before dropping it.
     /// <summary>

src/Core/Auth/Repositories/ITwoFactorRememberTokenRepository.cs

@@ -9,7 +9,7 @@ namespace Bit.Core.Auth.Repositories;
 public interface ITwoFactorRememberTokenRepository
 {
     /// <summary>
-    /// Reads the row for one remembered device, or null if the device has never been remembered.
+    /// Reads the row for the 2FA remember token issued to one device, or null if none has ever been issued for it.
     /// </summary>
     Task<TwoFactorRememberToken?> GetByUserIdDeviceIdAsync(Guid userId, Guid deviceId);
 
@@ -21,7 +21,7 @@ public interface ITwoFactorRememberTokenRepository
     Task<TwoFactorRememberToken> UpsertAsync(TwoFactorRememberToken token);
 
     /// <summary>
-    /// Rotates the <c>Stamp</c> on every row for this user, invalidating all of their remember
+    /// Rotates the <c>Stamp</c> on every row for this user, invalidating all of their 2FA remember
     /// tokens at once. Rows are kept.
     /// </summary>
     /// <remarks>

src/Core/Auth/UserFeatures/EmergencyAccess/EmergencyAccessService.cs

@@ -9,6 +9,7 @@
 using Bit.Core.Auth.Enums;
 using Bit.Core.Auth.Models.Business.Tokenables;
 using Bit.Core.Auth.Models.Data;
+using Bit.Core.Auth.UserFeatures.TwoFactorAuth;
 using Bit.Core.Auth.UserFeatures.UserMasterPassword.Data;
 using Bit.Core.Auth.UserFeatures.UserMasterPassword.Interfaces;
 using Bit.Core.Entities;
@@ -41,6 +42,7 @@ public class EmergencyAccessService : IEmergencyAccessService
     private readonly IDataProtectorTokenFactory<EmergencyAccessInviteTokenable> _dataProtectorTokenizer;
     private readonly IRemoveOrganizationUserCommand _removeOrganizationUserCommand;
     private readonly IPolicyRequirementQuery _policyRequirementQuery;
+    private readonly IRevokeTwoFactorRememberTokensCommand _revokeTwoFactorRememberTokensCommand;
 
     public EmergencyAccessService(
         IEmergencyAccessRepository emergencyAccessRepository,
@@ -55,7 +57,8 @@ public EmergencyAccessService(
         GlobalSettings globalSettings,
         IDataProtectorTokenFactory<EmergencyAccessInviteTokenable> dataProtectorTokenizer,
         IRemoveOrganizationUserCommand removeOrganizationUserCommand,
-        IPolicyRequirementQuery policyRequirementQuery)
+        IPolicyRequirementQuery policyRequirementQuery,
+        IRevokeTwoFactorRememberTokensCommand revokeTwoFactorRememberTokensCommand)
     {
         _emergencyAccessRepository = emergencyAccessRepository;
         _organizationUserRepository = organizationUserRepository;
@@ -70,6 +73,7 @@ public EmergencyAccessService(
         _dataProtectorTokenizer = dataProtectorTokenizer;
         _removeOrganizationUserCommand = removeOrganizationUserCommand;
         _policyRequirementQuery = policyRequirementQuery;
+        _revokeTwoFactorRememberTokensCommand = revokeTwoFactorRememberTokensCommand;
     }
 
     public async Task<Entities.EmergencyAccess> InviteAsync(User grantorUser, string emergencyContactEmail, EmergencyAccessType accessType, int waitTime)
@@ -402,6 +406,11 @@ public async Task<IdentityResult> FinishRecoveryTakeoverAsync(
         // Disable New Device Verification since it will otherwise block logins
         grantor.VerifyDevices = false;
 
+        // Takeover removes the grantor's 2FA, so their 2FA remember tokens must stop being honored too.
+        // The changes above are only in memory until the save below. Revoking first means a failed revoke
+        // persists nothing, so the stored grantor (including their 2FA) is unchanged and the takeover can be retried.
+        await _revokeTwoFactorRememberTokensCommand.RevokeAllForUserAsync(grantor.Id);
+
         await _userRepository.ReplaceAsync(grantor);
 
         // Remove grantor from all organizations unless Owner
@@ -437,6 +446,12 @@ public async Task PasswordAsync(Guid emergencyAccessId, User granteeUser, string
         grantor.SetTwoFactorProviders([]);
         // Disable New Device Verification since it will otherwise block logins
         grantor.VerifyDevices = false;
+
+        // Takeover removes the grantor's 2FA, so their 2FA remember tokens must stop being honored too.
+        // The changes above are only in memory until the save below. Revoking first means a failed revoke
+        // persists nothing, so the stored grantor (including their 2FA) is unchanged and the takeover can be retried.
+        await _revokeTwoFactorRememberTokensCommand.RevokeAllForUserAsync(grantor.Id);
+
         await _userRepository.ReplaceAsync(grantor);
 
         // Remove grantor from all organizations unless Owner

src/Core/Auth/UserFeatures/TwoFactorAuth/IIssueTwoFactorRememberTokenCommand.cs

@@ -5,12 +5,12 @@ namespace Bit.Core.Auth.UserFeatures.TwoFactorAuth;
 public interface IIssueTwoFactorRememberTokenCommand
 {
     /// <summary>
-    /// Records that this device is remembered and mints the token the client presents to skip the
+    /// Records a 2FA remember token for this device and mints the token the client presents to skip the
     /// two-factor challenge on its next login.
     /// </summary>
     /// <remarks>
     /// Writing the row assigns it a fresh stamp, so any token previously issued for this device
-    /// stops being honored — one live remember token per device, newest wins.
+    /// stops being honored — one live 2FA remember token per device, newest wins.
     /// </remarks>
     /// <returns>The protected token string, to be returned to the client verbatim.</returns>
     Task<string> IssueAsync(User user, Device device);

src/Core/Auth/UserFeatures/TwoFactorAuth/IRevokeTwoFactorRememberTokensCommand.cs

@@ -3,12 +3,7 @@
 public interface IRevokeTwoFactorRememberTokensCommand
 {
     /// <summary>
-    /// Stops every remember token this user holds from being honored, on all of their devices.
+    /// Stops every 2FA remember token recorded for this user from being honored, on all of their devices.
     /// </summary>
-    /// <remarks>
-    /// Scoped to remember-me only: access tokens, refresh tokens, and live sessions are unaffected,
-    /// so this does not log the user out anywhere. Devices stay remembered as rows — they simply
-    /// require a two-factor challenge again on next login.
-    /// </remarks>
     Task RevokeAllForUserAsync(Guid userId);
 }

src/Core/Auth/UserFeatures/TwoFactorAuth/IValidateTwoFactorRememberTokenQuery.cs

@@ -5,15 +5,15 @@ namespace Bit.Core.Auth.UserFeatures.TwoFactorAuth;
 public interface IValidateTwoFactorRememberTokenQuery
 {
     /// <summary>
-    /// Decides whether a presented remember token entitles this request to skip the two-factor
+    /// Decides whether a presented 2FA remember token entitles this request to skip the two-factor
     /// challenge.
     /// </summary>
     /// <remarks>
     /// A pure read: nothing here writes. If a last-used timestamp is ever wanted, it belongs in its
     /// own command rather than folded in here.
     /// <para>
     /// This validates the token only. Whether the user is required to complete two-factor at all is
-    /// the caller's decision, made before a remember token is considered.
+    /// the caller's decision, made before a 2FA remember token is considered.
     /// </para>
     /// </remarks>
     /// <param name="user">The authenticating user.</param>

src/Core/Auth/UserFeatures/TwoFactorAuth/Implementations/ResetUserTwoFactorCommand.cs

@@ -5,10 +5,14 @@ namespace Bit.Core.Auth.UserFeatures.TwoFactorAuth.Implementations;
 
 public class ResetUserTwoFactorCommand(
     IUserRepository userRepository,
+    IRevokeTwoFactorRememberTokensCommand revokeTwoFactorRememberTokensCommand,
     TimeProvider timeProvider) : IResetUserTwoFactorCommand
 {
     public async Task ResetAsync(User user)
     {
+        // Sits before ReplaceAsync so a failure here leaves 2FA intact and a retry re-runs both steps.
+        await revokeTwoFactorRememberTokensCommand.RevokeAllForUserAsync(user.Id);
+
         user.TwoFactorProviders = null;
         user.TwoFactorRecoveryCode = null;
         user.RevisionDate = user.AccountRevisionDate = timeProvider.GetUtcNow().UtcDateTime;

src/Core/Auth/UserFeatures/TwoFactorAuth/readme.md

@@ -2,6 +2,35 @@
 
 This area of the codebase covers enrollment and management of the multi-factor authentication providers Bitwarden supports — Authenticator (TOTP), YubiKey OTP, Duo (personal and organization), WebAuthn, and Email — plus supporting flows such as recovery codes, login-time challenges, and administrative resets. The sections below document specific aspects of the 2FA domain.
 
+## 2FA remember tokens
+
+### Issuance
+
+When a user completes 2FA, they can optionally select the "Don't ask again on this device for 30 days" checkbox on the `/2fa` screen. When this box is checked, the server records a row in the `TwoFactorRememberToken` table — one row per `(UserId, DeviceId)` — and issues a 2FA remember token (see `TwoFactorRememberTokenable`) carrying a copy of that row's `Stamp`. On a later login the client presents the token as `TwoFactorProviderType.Remember` and skips the 2FA challenge.
+
+### Revocation
+
+A 2FA remember token is only honored while the `Stamp` it carries still matches its corresponding `TwoFactorRememberToken` row. `IRevokeTwoFactorRememberTokensCommand.RevokeAllForUserAsync` writes a new `Stamp` to every row for a user, which stops every 2FA remember token issued against these rows from being honored at once. The rows are kept, so `CreationDate` still records when each device was first issued a 2FA remember token and `RevisionDate` records when it was cut off.
+
+Four flows revoke, all of them teardowns that leave the account with no effective second factor:
+
+| Flow                                                     | Where                                                                                 |
+| -------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| An administrator resets a member's 2FA                   | `ResetUserTwoFactorCommand.ResetAsync`                                                |
+| A user disables 2FA with a recovery code                 | `UserService.RecoverTwoFactorAsync`                                                   |
+| A user removes a provider and 2FA is no longer enabled   | `UserService.DisableTwoFactorProviderAsync`                                           |
+| A grantee takes over an account through emergency access | `EmergencyAccessService.FinishRecoveryTakeoverAsync` and the obsolete `PasswordAsync` |
+
+Removing a provider does **not** revoke if the user still has working 2FA, so their 2FA remember tokens stay valid. A provider that requires premium does not count when the user has no premium access, so removing the only non-premium provider revokes even though a premium-only provider remains.
+
+A password change or account key rotation also stops every 2FA remember token from being honored, without a call to `RevokeAllForUserAsync`. Each `TwoFactorRememberTokenable` carries a copy of `User.SecurityStamp` from the time it was issued. The server compares that copy with the current `User.SecurityStamp` on every use. Both events rotate `User.SecurityStamp`, so no existing 2FA remember token matches.
+
+Untrusting a device (Trusted Device Encryption) does not revoke 2FA remember tokens — that is a separate mechanism.
+
+### Cleanup
+
+Revoked `TwoFactorRememberToken` rows stay until their `ExpirationDate` passes. `DeleteExpiredTwoFactorRememberTokensJob` then deletes them.
+
 ## User Verification
 
 When a user manages their own 2FA enrollment (configuring a new provider, updating an existing one, removing one), the server requires proof that the human at the keyboard is the account owner. This section covers how that proof is established and replayed across the read → write step of a per-provider management flow.
@@ -59,14 +88,14 @@ Replays of a still-valid token against the same `(UserId, ProviderType)` are int
 
 Every per-provider 2FA management endpoint follows the same shape:
 
-| Provider       | GET (mints)                                   | Chain (replays)                            | PUT (replays)                                                                     | DELETE (replays)                                                                         |
-| -------------- | --------------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
-| Authenticator  | `POST /two-factor/get-authenticator`          | —                                          | `PUT /two-factor/authenticator`                                                   | `DELETE /two-factor/authenticator`                                                       |
-| YubiKey        | `POST /two-factor/get-yubikey`                | —                                          | `PUT /two-factor/yubikey`                                                         | `DELETE /two-factor/yubikey`                                                             |
-| Duo (personal) | `POST /two-factor/get-duo`                    | —                                          | `PUT /two-factor/duo`                                                             | `DELETE /two-factor/duo`                                                                 |
-| Duo (org)      | `POST /organizations/{id}/two-factor/get-duo` | —                                          | `PUT /organizations/{id}/two-factor/duo`                                          | `DELETE /organizations/{id}/two-factor/duo`                                              |
-| WebAuthn       | `POST /two-factor/get-webauthn`               | `POST /two-factor/get-webauthn-challenge`  | `PUT /two-factor/webauthn`                                                        | `DELETE /two-factor/webauthn` (per-credential), `DELETE /two-factor/webauthn/all` (bulk) |
-| Email          | `POST /two-factor/get-email`                  | `POST /two-factor/send-email`              | `PUT /two-factor/email`                                                           | `DELETE /two-factor/email`                                                               |
+| Provider       | GET (mints)                                   | Chain (replays)                           | PUT (replays)                            | DELETE (replays)                                                                         |
+| -------------- | --------------------------------------------- | ----------------------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------- |
+| Authenticator  | `POST /two-factor/get-authenticator`          | —                                         | `PUT /two-factor/authenticator`          | `DELETE /two-factor/authenticator`                                                       |
+| YubiKey        | `POST /two-factor/get-yubikey`                | —                                         | `PUT /two-factor/yubikey`                | `DELETE /two-factor/yubikey`                                                             |
+| Duo (personal) | `POST /two-factor/get-duo`                    | —                                         | `PUT /two-factor/duo`                    | `DELETE /two-factor/duo`                                                                 |
+| Duo (org)      | `POST /organizations/{id}/two-factor/get-duo` | —                                         | `PUT /organizations/{id}/two-factor/duo` | `DELETE /organizations/{id}/two-factor/duo`                                              |
+| WebAuthn       | `POST /two-factor/get-webauthn`               | `POST /two-factor/get-webauthn-challenge` | `PUT /two-factor/webauthn`               | `DELETE /two-factor/webauthn` (per-credential), `DELETE /two-factor/webauthn/all` (bulk) |
+| Email          | `POST /two-factor/get-email`                  | `POST /two-factor/send-email`             | `PUT /two-factor/email`                  | `DELETE /two-factor/email`                                                               |
 
 The Chain column captures interior steps that replay an existing UV token and return data the next call needs — for WebAuthn, `get-webauthn-challenge` replays the `get-webauthn` token and returns FIDO2 registration options for the PUT; for Email, `send-email` replays the `get-email` token and ships an OTP to the user's inbox that the PUT then carries back alongside the same UV token. No new UV token is minted at the chain step; the original one stays valid through the PUT.