Clean up comments

libs/common/src/key-management/master-password/abstractions/master-password.service.abstraction.ts

@@ -22,12 +22,14 @@ export abstract class MasterPasswordServiceAbstraction {
   abstract forceSetPasswordReason$: (userId: UserId) => Observable<ForceSetPasswordReason>;
   /**
    * An observable that emits the master key for the user.
+   * @deprecated Interacting with the master-key directly is deprecated. Please use {@link makeMasterPasswordUnlockData} and {@link makeMasterPasswordAuthenticationData}, {@link unwrapUserKeyFromMasterPasswordUnlockData}, or {@link makeMasterKeyWrappedUserKey} instead.
    * @param userId The user ID.
    * @throws If the user ID is missing.
    */
   abstract masterKey$: (userId: UserId) => Observable<MasterKey>;
   /**
    * An observable that emits the master key hash for the user.
+   * @deprecated Interacting with the master-key directly is deprecated. Please use {@link makeMasterPasswordAuthenticationData}.
    * @param userId The user ID.
    * @throws If the user ID is missing.
    */
@@ -40,6 +42,7 @@ export abstract class MasterPasswordServiceAbstraction {
   abstract getMasterKeyEncryptedUserKey: (userId: UserId) => Promise<EncString>;
   /**
    * Decrypts the user key with the provided master key
+   * @deprecated Interacting with the master-key directly is deprecated. Please use {@link unwrapUserKeyFromMasterPasswordUnlockData} instead.
    * @param masterKey The user's master key
    *    * @param userId The desired user
    * @param userKey The user's encrypted symmetric key
@@ -53,6 +56,9 @@ export abstract class MasterPasswordServiceAbstraction {
     userKey?: EncString,
   ) => Promise<UserKey | null>;
 
+  /**
+   * Makes the authentication hash for authenticating to the server with the master password.
+   */
   abstract makeMasterPasswordAuthenticationData: (
     password: string,
     kdf: KdfConfig,
@@ -60,6 +66,10 @@ export abstract class MasterPasswordServiceAbstraction {
     userId: UserId,
   ) => Promise<MasterPasswordAuthenticationData>;
 
+  /**
+   * Creates a MasterPasswordUnlockData bundle that encrypts the user-key with a key derived from the password. The
+   * bundle also contains the KDF settings and salt used to derive the key, which are required to decrypt the user-key later.
+   */
   abstract makeMasterPasswordUnlockData: (
     password: string,
     kdf: KdfConfig,
@@ -67,6 +77,9 @@ export abstract class MasterPasswordServiceAbstraction {
     userKey: UserKey,
   ) => Promise<MasterPasswordUnlockData>;
 
+  /**
+   * Wraps a user-key with a password provided KDF settings. The same KDF settings and salt must be provided to unwrap the user-key, otherwise it will fail to decrypt.
+   */
   abstract makeMasterKeyWrappedUserKey: (
     password: string,
     kdf: KdfConfig,
@@ -74,6 +87,11 @@ export abstract class MasterPasswordServiceAbstraction {
     userKey: UserKey,
   ) => Promise<MasterKeyWrappedUserKey>;
 
+  /**
+   * Unwraps a user-key that was wrapped with a password provided KDF settings. The same KDF settings and salt must be provided to unwrap the user-key, otherwise it will fail to decrypt.
+   * @throws If the encryption type is not supported.
+   * @throws If the password, KDF, or salt don't match the original wrapping parameters.
+   */
   abstract unwrapUserKeyFromMasterPasswordUnlockData: (
     password: string,
     masterPasswordUnlockData: MasterPasswordUnlockData,

libs/common/src/key-management/master-password/services/master-password.service.ts

@@ -79,9 +79,6 @@ export class MasterPasswordService implements InternalMasterPasswordServiceAbstr
     private accountService: AccountService,
   ) {}
 
-  /**
-   * @deprecated This will be made private
-   */
   masterKey$(userId: UserId): Observable<MasterKey> {
     if (userId == null) {
       throw new Error("User ID is required.");
@@ -89,9 +86,6 @@ export class MasterPasswordService implements InternalMasterPasswordServiceAbstr
     return this.stateProvider.getUser(userId, MASTER_KEY).state$;
   }
 
-  /**
-   * @deprecated
-   */
   masterKeyHash$(userId: UserId): Observable<string> {
     if (userId == null) {
       throw new Error("User ID is required.");
@@ -123,9 +117,6 @@ export class MasterPasswordService implements InternalMasterPasswordServiceAbstr
     return email.toLowerCase().trim() as MasterPasswordSalt;
   }
 
-  /**
-   * @deprecated
-   */
   async setMasterKey(masterKey: MasterKey, userId: UserId): Promise<void> {
     if (masterKey == null) {
       throw new Error("Master key is required.");
@@ -136,9 +127,6 @@ export class MasterPasswordService implements InternalMasterPasswordServiceAbstr
     await this.stateProvider.getUser(userId, MASTER_KEY).update((_) => masterKey);
   }
 
-  /**
-   * @deprecated
-   */
   async clearMasterKey(userId: UserId): Promise<void> {
     if (userId == null) {
       throw new Error("User ID is required.");
@@ -146,9 +134,6 @@ export class MasterPasswordService implements InternalMasterPasswordServiceAbstr
     await this.stateProvider.getUser(userId, MASTER_KEY).update((_) => null);
   }
 
-  /**
-   * @deprecated
-   */
   async setMasterKeyHash(masterKeyHash: string, userId: UserId): Promise<void> {
     if (masterKeyHash == null) {
       throw new Error("Master key hash is required.");
@@ -159,9 +144,6 @@ export class MasterPasswordService implements InternalMasterPasswordServiceAbstr
     await this.stateProvider.getUser(userId, MASTER_KEY_HASH).update((_) => masterKeyHash);
   }
 
-  /**
-   * @deprecated
-   */
   async clearMasterKeyHash(userId: UserId): Promise<void> {
     if (userId == null) {
       throw new Error("User ID is required.");
@@ -202,9 +184,6 @@ export class MasterPasswordService implements InternalMasterPasswordServiceAbstr
     await this.stateProvider.getUser(userId, FORCE_SET_PASSWORD_REASON).update((_) => reason);
   }
 
-  /**
-   * @deprecated Please use `unwrapMasterKeyWrappedUserKey` instead.
-   */
   async decryptUserKeyWithMasterKey(
     masterKey: MasterKey,
     userId: UserId,
@@ -246,9 +225,6 @@ export class MasterPasswordService implements InternalMasterPasswordServiceAbstr
     return decUserKey as UserKey;
   }
 
-  /**
-   * Makes the authentication hash for authenticating to the server with the master password.
-   */
   async makeMasterPasswordAuthenticationData(
     password: string,
     kdf: KdfConfig,
@@ -278,10 +254,6 @@ export class MasterPasswordService implements InternalMasterPasswordServiceAbstr
     } as MasterPasswordAuthenticationData;
   }
 
-  /**
-   * Creates a MasterPasswordUnlockData bundle that encrypts the user-key with a key derived from the password. The
-   * bundle also contains the KDF settings and salt used to derive the key, which are required to decrypt the user-key later.
-   */
   async makeMasterPasswordUnlockData(
     password: string,
     kdf: KdfConfig,
@@ -295,9 +267,6 @@ export class MasterPasswordService implements InternalMasterPasswordServiceAbstr
     };
   }
 
-  /**
-   * Wraps a user-key with a password provided KDF settings. The same KDF settings and salt must be provided to unwrap the user-key, otherwise it will fail to decrypt.
-   */
   async makeMasterKeyWrappedUserKey(
     password: string,
     kdf: KdfConfig,
@@ -315,11 +284,6 @@ export class MasterPasswordService implements InternalMasterPasswordServiceAbstr
     ) as MasterKeyWrappedUserKey;
   }
 
-  /**
-   * Unwraps a user-key that was wrapped with a password provided KDF settings. The same KDF settings and salt must be provided to unwrap the user-key, otherwise it will fail to decrypt.
-   * @throws If the encryption type is not supported.
-   * @throws If the password, KDF, or salt don't match the original wrapping parameters.
-   */
   async unwrapUserKeyFromMasterPasswordUnlockData(
     password: string,
     masterPasswordUnlockData: MasterPasswordUnlockData,

libs/key-management/src/key.service.ts

@@ -210,7 +210,7 @@ export class DefaultKeyService implements KeyServiceAbstraction {
   }
 
   /**
-   * @deprecated Please use `makeMasterKeyWrappedUserKey` in @link MasterPasswordService instead.
+   * @deprecated Please use `makeMasterKeyWrappedUserKey` in {@link MasterPasswordService} instead.
    */
   async makeUserKey(masterKey: MasterKey | null): Promise<[UserKey, EncString]> {
     if (masterKey == null) {
@@ -307,7 +307,7 @@ export class DefaultKeyService implements KeyServiceAbstraction {
   }
 
   /**
-   * @deprecated Please use `makeMasterKeyWrappedUserKey` in @link MasterPasswordService instead.
+   * @deprecated Please use `makeMasterKeyWrappedUserKey` in {@link MasterPasswordService} instead.
    */
   async encryptUserKeyWithMasterKey(
     masterKey: MasterKey,
@@ -319,7 +319,7 @@ export class DefaultKeyService implements KeyServiceAbstraction {
 
   // TODO: move to MasterPasswordService
   /**
-   * @deprecated Please use `makeMasterPasswordAuthenticationData` in @link MasterPasswordService instead.
+   * @deprecated Please use `makeMasterPasswordAuthenticationData` in {@link MasterPasswordService} instead.
    */
   async hashMasterKey(
     password: string,