feat(mp-service) [PM-35392] Add master password service (#7530)

* feat(mp-service): Add MasterPasswordService foundation.

* docs(mp-service): Resolve incoming comments, document contract.

* feat(mp-service): Add KDF-setting helper and DI.

* test(mp-service): Add tests.

* feat(mp-service): Add enforecement in Build delegate for stamp/validate pw flags, tag data update ticket.

* refactor(mp-service): Align validate/hash/compose/execute pattern.

* test(mp-service): Tighten test assertions.

* refactor(mp-service) chants: unlock and authenticate.

* docs(mp-service): Re-fit some XML doc comment tags for general support.

* docs(mp-service): Address review comment feedback.

* refactor(mp-service): Apply result.Tx handling to all OneOf returns.

* docs(mp-service): Refine unlock vs authentication data comments.

* refactor(mp-service): Rename for saveExistingData (too much existing).

* docs(mp-service): Restore PM-34905 userrepository TODOs.

* refactor(mp-service): Apply test naming clarification.

* refactor(mp-service): Make service internal to Core.

* docs(mp-service): Update method comment formats: what, use when, constraints.

* docs(mp-service): Update interface docs for consistency.

* refactor(mp-service): Rename internal helpers to Apply, add documentation.

* docs(mp-service): Add summary and use-when annotations to data models.

* docs(mp-service): Add annotation preferring non-Build API verbs where possible.

* test(mp-service): Refactor data model tests into discrete files.

* test(mp-service): Address additional coverage cases.

* docs(mp-service): Spelling.

* refactor(mp-service): Extract user security stamp rotation to its own helper.

* docs(mp-service): Clarify authentication hash documentation.

Author: enmande

src/Core/Auth/UserFeatures/UserMasterPassword/Data/SetInitialOrUpdateExistingPasswordData.cs

@@ -0,0 +1,54 @@
+using Bit.Core.KeyManagement.Models.Data;
+
+namespace Bit.Core.Auth.UserFeatures.UserMasterPassword.Data;
+
+/// <summary>
+/// Combined input data covering both the set-initial and update-existing paths. Converts to
+/// <see cref="SetInitialPasswordData"/> or <see cref="UpdateExistingPasswordData"/> via
+/// <see cref="ToSetInitialData"/> or <see cref="ToUpdateExistingData"/>.
+///
+/// <para>
+/// Use when: constructing a call to
+/// <see cref="Interfaces.IMasterPasswordService.PrepareSetInitialOrUpdateExistingMasterPasswordAsync"/>,
+/// where the caller does not need to select the set-initial or update-existing path explicitly.
+/// </para>
+/// </summary>
+public class SetInitialOrUpdateExistingPasswordData
+{
+    public required MasterPasswordUnlockData MasterPasswordUnlock { get; set; }
+    public required MasterPasswordAuthenticationData MasterPasswordAuthentication { get; set; }
+
+    /// <summary>
+    /// When <c>true</c>, runs the new password hash through the registered
+    /// <see cref="Microsoft.AspNetCore.Identity.IPasswordValidator{TUser}"/> pipeline before hashing.
+    /// Set to <c>false</c> only in flows where password policy validation has already been enforced
+    /// (e.g. admin-initiated recovery). Defaults to <c>true</c>.
+    /// </summary>
+    public bool ValidatePassword { get; set; } = true;
+    /// <summary>
+    /// When <c>true</c>, rotates <see cref="Bit.Core.Entities.User.SecurityStamp"/>, which invalidates
+    /// all active sessions and authentication tokens for the user. Set to <c>false</c> only when
+    /// intentionally preserving existing sessions. Defaults to <c>true</c>.
+    /// </summary>
+    public bool RefreshStamp { get; set; } = true;
+
+    public string? MasterPasswordHint { get; set; } = null;
+
+    public SetInitialPasswordData ToSetInitialData() => new()
+    {
+        MasterPasswordUnlock = MasterPasswordUnlock,
+        MasterPasswordAuthentication = MasterPasswordAuthentication,
+        ValidatePassword = ValidatePassword,
+        RefreshStamp = RefreshStamp,
+        MasterPasswordHint = MasterPasswordHint
+    };
+
+    public UpdateExistingPasswordData ToUpdateExistingData() => new()
+    {
+        MasterPasswordUnlock = MasterPasswordUnlock,
+        MasterPasswordAuthentication = MasterPasswordAuthentication,
+        ValidatePassword = ValidatePassword,
+        RefreshStamp = RefreshStamp,
+        MasterPasswordHint = MasterPasswordHint
+    };
+}

src/Core/Auth/UserFeatures/UserMasterPassword/Data/SetInitialPasswordData.cs

@@ -0,0 +1,79 @@
+using Bit.Core.Entities;
+using Bit.Core.Exceptions;
+using Bit.Core.KeyManagement.Models.Data;
+
+namespace Bit.Core.Auth.UserFeatures.UserMasterPassword.Data;
+
+/// <summary>
+/// Input data for setting an initial master password on a user who has none. Carries the
+/// cryptographic material, authentication credential, and control flags consumed by
+/// <see cref="Interfaces.IMasterPasswordService"/>.
+///
+/// <para>
+/// Use when: constructing a call to
+/// <see cref="Interfaces.IMasterPasswordService.PrepareSetInitialMasterPasswordAsync"/>,
+/// <see cref="Interfaces.IMasterPasswordService.SaveSetInitialMasterPasswordAsync"/>, or
+/// <see cref="Interfaces.IMasterPasswordService.BuildUpdateUserDelegateSetInitialMasterPassword"/>.
+/// </para>
+/// </summary>
+public class SetInitialPasswordData
+{
+    public required MasterPasswordUnlockData MasterPasswordUnlock { get; set; }
+    public required MasterPasswordAuthenticationData MasterPasswordAuthentication { get; set; }
+
+    /// <summary>
+    /// When <c>true</c>, runs the new password hash through the registered
+    /// <see cref="Microsoft.AspNetCore.Identity.IPasswordValidator{TUser}"/> pipeline before hashing.
+    /// Set to <c>false</c> only in flows where password policy validation has already been enforced
+    /// (e.g. admin-initiated recovery). Defaults to <c>true</c>.
+    /// </summary>
+    public bool ValidatePassword { get; set; } = true;
+    /// <summary>
+    /// When <c>true</c>, rotates <see cref="Bit.Core.Entities.User.SecurityStamp"/>, which invalidates
+    /// all active sessions and authentication tokens for the user. Set to <c>false</c> only when
+    /// intentionally preserving existing sessions. Defaults to <c>true</c>.
+    /// </summary>
+    public bool RefreshStamp { get; set; } = true;
+
+    public string? MasterPasswordHint { get; set; } = null;
+
+    public void ValidateDataForUser(User user)
+    {
+        // Validate that the user does not have a master password set.
+        if (user.HasMasterPassword())
+        {
+            throw new BadRequestException("User already has a master password set.");
+        }
+
+        // Validate that there is no key set since there is no master password. The key
+        // and MasterPassword property are siblings in that they should either both be
+        // present or both be null, even for all TDE/KeyConnector users.
+        if (user.Key != null)
+        {
+            throw new BadRequestException("User already has a key set.");
+        }
+
+        // Validate that there is no salt set.
+        if (user.MasterPasswordSalt != null)
+        {
+            throw new BadRequestException("User already has a master password set.");
+        }
+
+        // Once a user is in the KeyConnector state they cannot become a master password
+        // user ever again so we can check here to make sure that they shouldn't ever be
+        // setting a password
+        if (user.UsesKeyConnector)
+        {
+            throw new BadRequestException("Cannot set an initial password of a user with Key Connector.");
+        }
+
+        // Compatibility-window invariant: during Stage 1 of email-salt separation (PM-27044),
+        // the client MUST send salt == email.lower.trim on initial SET. The server cannot yet
+        // handle divergent salts; GetMasterPasswordSalt() falls back to email when MasterPasswordSalt
+        // is null, and a mismatch here would make the user un-decryptable on next login. Centralized
+        // here so both TDE and SSO JIT initial-SET flows enforce the same rule. This check is
+        // removed in Stage 3 when PM-28143 feature flag clears and independent salts are safe.
+        MasterPasswordUnlock.ValidateSaltUnchangedForUser(user);
+        MasterPasswordAuthentication.ValidateSaltUnchangedForUser(user);
+    }
+}

src/Core/Auth/UserFeatures/UserMasterPassword/Data/UpdateExistingPasswordAndKdfData.cs

@@ -0,0 +1,65 @@
+using Bit.Core.Entities;
+using Bit.Core.Exceptions;
+using Bit.Core.KeyManagement.Models.Data;
+
+namespace Bit.Core.Auth.UserFeatures.UserMasterPassword.Data;
+
+/// <summary>
+/// Input data for updating a user's existing master password hash together with new KDF parameters.
+/// Salt is validated as unchanged; KDF validation is intentionally skipped since KDF is being replaced.
+///
+/// <para>
+/// Use when: constructing a call to
+/// <see cref="Interfaces.IMasterPasswordService.SaveUpdateExistingMasterPasswordAndKdfAsync"/>
+/// (KDF rotation flows). For hash-only updates, use <see cref="UpdateExistingPasswordData"/> instead.
+/// </para>
+/// </summary>
+public class UpdateExistingPasswordAndKdfData
+{
+    public required MasterPasswordUnlockData MasterPasswordUnlock { get; set; }
+    public required MasterPasswordAuthenticationData MasterPasswordAuthentication { get; set; }
+
+    /// <summary>
+    /// When <c>true</c>, runs the new password hash through the registered
+    /// <see cref="Microsoft.AspNetCore.Identity.IPasswordValidator{TUser}"/> pipeline before hashing.
+    /// Set to <c>false</c> only in flows where password policy validation has already been enforced
+    /// (e.g. admin-initiated recovery). Defaults to <c>true</c>.
+    /// </summary>
+    public bool ValidatePassword { get; set; } = true;
+    /// <summary>
+    /// When <c>true</c>, rotates <see cref="Bit.Core.Entities.User.SecurityStamp"/>, which invalidates
+    /// all active sessions and authentication tokens for the user. Set to <c>false</c> only when
+    /// intentionally preserving existing sessions. Defaults to <c>true</c>.
+    /// </summary>
+    public bool RefreshStamp { get; set; } = true;
+
+    public string? MasterPasswordHint { get; set; } = null;
+
+    public void ValidateDataForUser(User user)
+    {
+        // Validate that the user has a master password already, if not then they shouldn't be updating they should
+        // be setting initial.
+        if (!user.HasMasterPassword())
+        {
+            throw new BadRequestException("User does not have an existing master password to update.");
+        }
+
+        // KDF parameters govern how the master password is stretched into the encryption key.
+        // Key Connector replaces the master password entirely — the encryption key is managed
+        // by an external service — so KDF rotation has no meaningful target. The existing
+        // ChangeKdfCommand blocks this implicitly (CheckPasswordAsync fails against a null
+        // master password), but this guard makes the categorical inapplicability explicit.
+        // Note: org owners/admins cannot be KC users (enforced at conversion time in
+        // UserService.CheckCanUseKeyConnector), so no role-based edge case exists.
+        if (user.UsesKeyConnector)
+        {
+            throw new BadRequestException("Cannot update password of a user with Key Connector.");
+        }
+
+        // Do not validate if kdf is the same here on the user because we are changing it.
+
+        // Validate Salt is unchanged for user
+        MasterPasswordUnlock.ValidateSaltUnchangedForUser(user);
+        MasterPasswordAuthentication.ValidateSaltUnchangedForUser(user);
+    }
+}

src/Core/Auth/UserFeatures/UserMasterPassword/Data/UpdateExistingPasswordData.cs

@@ -0,0 +1,69 @@
+using Bit.Core.Entities;
+using Bit.Core.Exceptions;
+using Bit.Core.KeyManagement.Models.Data;
+
+namespace Bit.Core.Auth.UserFeatures.UserMasterPassword.Data;
+
+/// <summary>
+/// Input data for updating a user's existing master password hash without changing KDF parameters.
+/// Carries the cryptographic material, authentication credential, and control flags consumed by
+/// <see cref="Interfaces.IMasterPasswordService"/>. KDF and salt are validated as unchanged.
+///
+/// <para>
+/// Use when: constructing a call to
+/// <see cref="Interfaces.IMasterPasswordService.PrepareUpdateExistingMasterPasswordAsync"/> or
+/// <see cref="Interfaces.IMasterPasswordService.SaveUpdateExistingMasterPasswordAsync"/>.
+/// For KDF rotation, use <see cref="UpdateExistingPasswordAndKdfData"/> instead.
+/// </para>
+/// </summary>
+public class UpdateExistingPasswordData
+{
+    public required MasterPasswordUnlockData MasterPasswordUnlock { get; set; }
+    public required MasterPasswordAuthenticationData MasterPasswordAuthentication { get; set; }
+
+    /// <summary>
+    /// When <c>true</c>, runs the new password hash through the registered
+    /// <see cref="Microsoft.AspNetCore.Identity.IPasswordValidator{TUser}"/> pipeline before hashing.
+    /// Set to <c>false</c> only in flows where password policy validation has already been enforced
+    /// (e.g. admin-initiated recovery). Defaults to <c>true</c>.
+    /// </summary>
+    public bool ValidatePassword { get; set; } = true;
+    /// <summary>
+    /// When <c>true</c>, rotates <see cref="Bit.Core.Entities.User.SecurityStamp"/>, which invalidates
+    /// all active sessions and authentication tokens for the user. Set to <c>false</c> only when
+    /// intentionally preserving existing sessions. Defaults to <c>true</c>.
+    /// </summary>
+    public bool RefreshStamp { get; set; } = true;
+
+    public string? MasterPasswordHint { get; set; } = null;
+
+    public void ValidateDataForUser(User user)
+    {
+        // Validate that the user has a master password already, if not then they shouldn't be updating they should
+        // be setting initial.
+        if (!user.HasMasterPassword())
+        {
+            throw new BadRequestException("User does not have an existing master password to update.");
+        }
+
+        // Key Connector users' encryption keys are managed by an external service, replacing the
+        // master password entirely (MasterPassword is set to null on conversion). Master password
+        // operations are categorically inapplicable to these users. This guard is defense-in-depth:
+        // the HasMasterPassword() check above would also catch KC users, but this makes the
+        // rejection reason explicit. Note: org owners/admins are structurally prohibited from
+        // using Key Connector (enforced at conversion time in UserService.CheckCanUseKeyConnector),
+        // so there is no owner/admin edge case to handle here.
+        if (user.UsesKeyConnector)
+        {
+            throw new BadRequestException("Cannot update password of a user with Key Connector.");
+        }
+
+        // Validate KDF is unchanged for user
+        MasterPasswordUnlock.Kdf.ValidateUnchangedForUser(user);
+        MasterPasswordAuthentication.Kdf.ValidateUnchangedForUser(user);
+
+        // Validate Salt is unchanged for user
+        MasterPasswordUnlock.ValidateSaltUnchangedForUser(user);
+        MasterPasswordAuthentication.ValidateSaltUnchangedForUser(user);
+    }
+}