From 4b5d6b44c1eda8bec10725446cc9324f612d6bed Mon Sep 17 00:00:00 2001 From: Bernd Schoolmann Date: Thu, 17 Jul 2025 13:03:50 +0200 Subject: [PATCH] Clean up comments --- .../master-password.service.abstraction.ts | 18 ++++++++++ .../services/master-password.service.ts | 36 ------------------- libs/key-management/src/key.service.ts | 6 ++-- 3 files changed, 21 insertions(+), 39 deletions(-) diff --git a/libs/common/src/key-management/master-password/abstractions/master-password.service.abstraction.ts b/libs/common/src/key-management/master-password/abstractions/master-password.service.abstraction.ts index dc9f1a7daee..a5783c74f08 100644 --- a/libs/common/src/key-management/master-password/abstractions/master-password.service.abstraction.ts +++ b/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; /** * 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; /** * 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; /** * 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; + /** + * 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; + /** + * 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; + /** + * 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; + /** + * 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, diff --git a/libs/common/src/key-management/master-password/services/master-password.service.ts b/libs/common/src/key-management/master-password/services/master-password.service.ts index 199919eae27..727ef44628c 100644 --- a/libs/common/src/key-management/master-password/services/master-password.service.ts +++ b/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 { 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 { 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 { 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 { 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 { 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 { 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, diff --git a/libs/key-management/src/key.service.ts b/libs/key-management/src/key.service.ts index 967cf4a9ec5..8478c42cb90 100644 --- a/libs/key-management/src/key.service.ts +++ b/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,