[PM-39455] Set Upgrade Tokens for Organizations

[mzieniukbw]

🎟️ Tracking

https://bitwarden.atlassian.net/browse/PM-39455

📔 Objective

Add OrganizationUser.V2UpgradeToken and write it during a V1 to V2 upgrade rotation, so an organization admin can unwrap the V2 user key through account recovery and update the account recovery key without prompting the member (tackled separately in later PRs).

A manual rotation always logs the user out, so it never persists a token and clears any token left over from an earlier upgrade.

📸 Screenshots

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 67.53%. Comparing base (73ed2f6) to head (5bbd357).
⚠️ Report is 4 commits behind head on main.

Additional details and impacted files

@@             Coverage Diff             @@
##             main    #8158       +/-   ##
===========================================
+ Coverage   15.10%   67.53%   +52.42%     
===========================================
  Files        1417     2315      +898     
  Lines       61422   100520    +39098     
  Branches     4901     9044     +4143     
===========================================
+ Hits         9279    67885    +58606     
+ Misses      51978    30350    -21628     
- Partials      165     2285     +2120     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

🤖 Bitwarden Claude Code Review

Overall Assessment: APPROVE

Reviewed the addition of OrganizationUser.V2UpgradeToken across the entity, the rotation command, both ORM tracks, and the MSSQL/EF migrations. Dual-ORM parity is intact: the Dapper OrganizationUser_UpdateDataForKeyRotation path and the EF UpdateForKeyRotation path both write the new column, the SSDT table and stored procedures match the dated migration, and the migration guards the column add with COL_LENGTH and refreshes the five dependent views. The new optional @V2UpgradeToken parameters default to NULL, so the procedures stay backwards compatible during a rolling deployment, and no view or response model exposes the column (OrganizationUserUserDetailsView uses an explicit column list). Unit and integration tests were updated to match the new "manual rotation always logs out and never persists a token" behavior.

Code Review Details

• ❓ : V1→V2 upgrade is reachable on the password-change endpoint; unclear how the org account recovery key is fixed up now that the token is dropped there
  • src/Api/KeyManagement/Controllers/AccountsKeyManagementController.cs:131
• ❓ : Documented "NULL at all other times" invariant does not hold after a member withdraws from account recovery
  • src/Core/AdminConsole/Entities/OrganizationUser.cs:54

[JimmyVo16]

I understand the V2 prefix is for versioning, but database columns are much harder to change than application code. Are there plans to rename this column after the migration is complete? If so, can we look into a strategy to avoid having to rename it?

[mzieniukbw]

When user rotates their keys (as part of forced user encryption v2 rollout), we fill in this column with value, where later organization (admin/owner) would upgrade the user's account recovery to new keys.
V2 in this context means that for a user with encryption v2 (v2 user keys), there is an upgrade token, that can be used to grab the v1 user key and migrate the organization member account recovery to use v2 user key - since account recovery holds sealed user key.
Once migrated, we NULL the value.
After ~1 year we will drop the column out of existence with it's value - this will be after we rollout forced user encryption v2), so likely this column will be gone in 2027-28

[mzieniukbw]

Note, we already have the same on User table, https://github.com/bitwarden/server/blob/main/src/Sql/dbo/Tables/User.sql#L49 but it have different use and lifecycle, hence have to be duplicated into OrganizationUser table.

[JimmyVo16]

Just one question about the database column naming. DBOps will probably have a stronger opinion on the topic, but other than that, it looks good from the AC side.

[mkincaid-bw]

LGTM