[PM-23809] Add simplified interface to MP service (#15631)

* Add new mp service api * Fix tests * Add test coverage * Add newline * Fix type * Rename to "unwrapUserKeyFromMasterPasswordUnlockData" * Fix build * Fix build on cli * Fix linting * Re-sort spec * Add tests * Fix test and build issues * Fix build * Clean up * Remove introduced function * Clean up comments * Fix abstract class types * Fix comments * Cleanup * Cleanup * Update libs/common/src/key-management/master-password/types/master-password.types.ts Co-authored-by: Thomas Avery <43214426+Thomas-Avery@users.noreply.github.com> * Update libs/common/src/key-management/master-password/services/master-password.service.ts Co-authored-by: Thomas Avery <43214426+Thomas-Avery@users.noreply.github.com> * Update libs/common/src/key-management/master-password/abstractions/master-password.service.abstraction.ts Co-authored-by: Thomas Avery <43214426+Thomas-Avery@users.noreply.github.com> * Update libs/common/src/key-management/master-password/types/master-password.types.ts Co-authored-by: Thomas Avery <43214426+Thomas-Avery@users.noreply.github.com> * Update libs/common/src/key-management/master-password/abstractions/master-password.service.abstraction.ts Co-authored-by: Thomas Avery <43214426+Thomas-Avery@users.noreply.github.com> * Add comments * Fix build * Add arg null check * Cleanup * Fix build * Fix build on browser * Update libs/common/src/key-management/master-password/abstractions/master-password.service.abstraction.ts Co-authored-by: Thomas Avery <43214426+Thomas-Avery@users.noreply.github.com> * Update libs/common/src/key-management/master-password/abstractions/master-password.service.abstraction.ts Co-authored-by: Thomas Avery <43214426+Thomas-Avery@users.noreply.github.com> * Update libs/common/src/key-management/master-password/abstractions/master-password.service.abstraction.ts Co-authored-by: Thomas Avery <43214426+Thomas-Avery@users.noreply.github.com> * Add tests for null params * Cleanup and deprecate more functions * Fix formatting * Prettier * Clean up * Update libs/key-management/src/abstractions/key.service.ts Co-authored-by: Thomas Avery <43214426+Thomas-Avery@users.noreply.github.com> * Make emailToSalt private and expose abstract saltForUser * Add tests * Add docs * Update libs/common/src/key-management/master-password/abstractions/master-password.service.abstraction.ts Co-authored-by: Thomas Avery <43214426+Thomas-Avery@users.noreply.github.com> * Update libs/common/src/key-management/master-password/abstractions/master-password.service.abstraction.ts Co-authored-by: Thomas Avery <43214426+Thomas-Avery@users.noreply.github.com> --------- Co-authored-by: Thomas Avery <43214426+Thomas-Avery@users.noreply.github.com>
2025-12-06 00:13:28 +00:00 · 2025-07-29 18:53:17 +02:00
parent 95f037390e
commit a7d3c0f5c2
11 changed files with 418 additions and 6 deletions
--- a/libs/key-management/src/abstractions/key.service.ts
+++ b/libs/key-management/src/abstractions/key.service.ts
@@ -150,11 +150,18 @@ export abstract class KeyService {

  /**
   * Generates a new user key
+   * @deprecated Interacting with the master key directly is prohibited. Use {@link makeUserKeyV1} instead.
   * @throws Error when master key is null and there is no active user
   * @param masterKey The user's master key. When null, grabs master key from active user.
   * @returns A new user key and the master key protected version of it
   */
  abstract makeUserKey(masterKey: MasterKey | null): Promise<[UserKey, EncString]>;
+  /**
+   * Generates a new user key for a V1 user
+   * Note: This will be replaced by a higher level function to initialize a whole users cryptographic state in the near future.
+   * @returns A new user key
+   */
+  abstract makeUserKeyV1(): Promise<UserKey>;
  /**
   * Clears the user's stored version of the user key
   * @param keySuffix The desired version of the key to clear
@@ -166,6 +173,7 @@ export abstract class KeyService {
   * Retrieves the user's master key if it is in state, or derives it from the provided password
   * @param password The user's master password that will be used to derive a master key if one isn't found
   * @param userId The desired user
+   * @deprecated Interacting with the master key directly is prohibited. Use a high level function from MasterPasswordService instead.
   * @throws Error when userId is null/undefined.
   * @throws Error when email or Kdf configuration cannot be found for the user.
   * @returns The user's master key if it exists, or a newly derived master key.
@@ -173,6 +181,7 @@ export abstract class KeyService {
  abstract getOrDeriveMasterKey(password: string, userId: UserId): Promise<MasterKey>;
  /**
   * Generates a master key from the provided password
+   * @deprecated Interacting with the master key directly is prohibited.
   * @param password The user's master password
   * @param email The user's email
   * @param KdfConfig The user's key derivation function configuration
@@ -182,6 +191,7 @@ export abstract class KeyService {
  /**
   * Encrypts the existing (or provided) user key with the
   * provided master key
+   * @deprecated Interacting with the master key directly is prohibited. Use a high level function from MasterPasswordService instead.
   * @param masterKey The user's master key
   * @param userKey The user key
   * @returns The user key and the master key protected version of it
@@ -194,6 +204,7 @@ export abstract class KeyService {
   * Creates a master password hash from the user's master password. Can
   * be used for local authentication or for server authentication depending
   * on the hashPurpose provided.
+   * @deprecated Interacting with the master key directly is prohibited. Use a high level function from MasterPasswordService instead.
   * @param password The user's master password
   * @param key The user's master key or active's user master key.
   * @param hashPurpose The iterations to use for the hash. Defaults to {@link HashPurpose.ServerAuthorization}.
@@ -207,6 +218,7 @@ export abstract class KeyService {
  ): Promise<string>;
  /**
   * Compares the provided master password to the stored password hash.
+   * @deprecated Interacting with the master key directly is prohibited. Use a high level function from MasterPasswordService instead.
   * @param masterPassword The user's master password
   * @param masterKey The user's master key
   * @param userId The id of the user to do the operation for.
--- a/libs/key-management/src/key.service.ts
+++ b/libs/key-management/src/key.service.ts
@@ -232,6 +232,11 @@ export class DefaultKeyService implements KeyServiceAbstraction {
    return this.buildProtectedSymmetricKey(masterKey, newUserKey);
  }

+  async makeUserKeyV1(): Promise<UserKey> {
+    const newUserKey = await this.keyGenerationService.createKey(512);
+    return newUserKey as UserKey;
+  }
+
  /**
   * Clears the user key. Clears all stored versions of the user keys as well, such as the biometrics key
   * @param userId The desired user
@@ -259,6 +264,9 @@ export class DefaultKeyService implements KeyServiceAbstraction {
    }
  }

+  /**
+   * @deprecated Please use `makeMasterPasswordAuthenticationData`, `unwrapUserKeyFromMasterPasswordUnlockData` or `makeMasterPasswordUnlockData` in @link MasterPasswordService instead.
+   */
  async getOrDeriveMasterKey(password: string, userId: UserId): Promise<MasterKey> {
    if (userId == null) {
      throw new Error("User ID is required.");
@@ -287,6 +295,8 @@ export class DefaultKeyService implements KeyServiceAbstraction {
  /**
   * Derive a master key from a password and email.
   *
+   * @deprecated Please use `makeMasterPasswordAuthenticationData`, `makeMasterPasswordAuthenticationData`, `unwrapUserKeyFromMasterPasswordUnlockData` in @link MasterPasswordService instead.
+   *
   * @remarks
   * Does not validate the kdf config to ensure it satisfies the minimum requirements for the given kdf type.
   */
@@ -304,6 +314,9 @@ export class DefaultKeyService implements KeyServiceAbstraction {
    return masterKey;
  }

+  /**
+   * @deprecated Please use `makeMasterPasswordUnlockData` in {@link MasterPasswordService} instead.
+   */
  async encryptUserKeyWithMasterKey(
    masterKey: MasterKey,
    userKey?: UserKey,
@@ -312,6 +325,9 @@ export class DefaultKeyService implements KeyServiceAbstraction {
    return await this.buildProtectedSymmetricKey(masterKey, userKey);
  }

+  /**
+   * @deprecated Please use `makeMasterPasswordAuthenticationData` in {@link MasterPasswordService} instead.
+   */
  async hashMasterKey(
    password: string,
    key: MasterKey,