[PM-5537] Biometric State Service (#7761)

* Create state for biometric client key halves

* Move enc string util to central utils

* Provide biometric state through service

* Use biometric state to track client key half

* Create migration for client key half

* Ensure client key half is removed on logout

* Remove account data for client key half

* Remove unnecessary key definition likes

* Remove moved state from account

* Fix null-conditional operator failure

* Simplify migration

* Remove lame test

* Fix test type

* Add migrator

* Prefer userKey when legacy not needed

* Fix tests

libs/angular/src/services/jslib-services.module.ts

@@ -95,6 +95,10 @@ import { PlatformUtilsService as PlatformUtilsServiceAbstraction } from "@bitwar
 import { StateService as StateServiceAbstraction } from "@bitwarden/common/platform/abstractions/state.service";
 import { AbstractStorageService } from "@bitwarden/common/platform/abstractions/storage.service";
 import { ValidationService as ValidationServiceAbstraction } from "@bitwarden/common/platform/abstractions/validation.service";
+import {
+  BiometricStateService,
+  DefaultBiometricStateService,
+} from "@bitwarden/common/platform/biometrics/biometric-state.service";
 import { StateFactory } from "@bitwarden/common/platform/factories/state-factory";
 import { devFlagEnabled, flagEnabled } from "@bitwarden/common/platform/misc/flags";
 import { Account } from "@bitwarden/common/platform/models/domain/account";
@@ -876,6 +880,11 @@ import { ModalService } from "./modal.service";
         OrganizationApiServiceAbstraction,
       ],
     },
+    {
+      provide: BiometricStateService,
+      useClass: DefaultBiometricStateService,
+      deps: [StateProvider],
+    },
   ],
 })
 export class JslibServicesModule {}

libs/common/spec/utils.ts

@@ -3,6 +3,9 @@ import { Observable } from "rxjs";
 
 import { EncString } from "@bitwarden/common/platform/models/domain/enc-string";
 
+import { EncryptionType } from "../src/platform/enums";
+import { Utils } from "../src/platform/misc/utils";
+
 function newGuid() {
   return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
     const r = (Math.random() * 16) | 0;
@@ -29,6 +32,11 @@ export function mockEnc(s: string): MockProxy<EncString> {
   return mocked;
 }
 
+export function makeEncString(data?: string) {
+  data ??= Utils.newGuid();
+  return new EncString(EncryptionType.AesCbc256_HmacSha256_B64, data, "test", "test");
+}
+
 export function makeStaticByteArray(length: number, start = 0) {
   const arr = new Uint8Array(length);
   for (let i = 0; i < length; i++) {

libs/common/src/platform/biometrics/biometric-state.service.spec.ts

@@ -0,0 +1,61 @@
+import { firstValueFrom } from "rxjs";
+
+import { makeEncString } from "../../../spec";
+import { mockAccountServiceWith } from "../../../spec/fake-account-service";
+import { FakeStateProvider } from "../../../spec/fake-state-provider";
+import { UserId } from "../../types/guid";
+
+import { BiometricStateService, DefaultBiometricStateService } from "./biometric-state.service";
+import { ENCRYPTED_CLIENT_KEY_HALF } from "./biometric.state";
+
+describe("BiometricStateService", () => {
+  let sut: BiometricStateService;
+  const userId = "userId" as UserId;
+  const encClientKeyHalf = makeEncString();
+  const encryptedClientKeyHalf = encClientKeyHalf.encryptedString;
+  const accountService = mockAccountServiceWith(userId);
+  let stateProvider: FakeStateProvider;
+
+  beforeEach(() => {
+    stateProvider = new FakeStateProvider(accountService);
+
+    sut = new DefaultBiometricStateService(stateProvider);
+  });
+
+  afterEach(() => {
+    jest.resetAllMocks();
+  });
+
+  describe("requirePasswordOnStart$", () => {
+    it("should be false when encryptedClientKeyHalf is undefined", async () => {
+      stateProvider.activeUser.getFake(ENCRYPTED_CLIENT_KEY_HALF).nextState(undefined);
+      expect(await firstValueFrom(sut.requirePasswordOnStart$)).toBe(false);
+    });
+
+    it("should be true when encryptedClientKeyHalf is defined", async () => {
+      stateProvider.activeUser.getFake(ENCRYPTED_CLIENT_KEY_HALF).nextState(encryptedClientKeyHalf);
+      expect(await firstValueFrom(sut.requirePasswordOnStart$)).toBe(true);
+    });
+  });
+
+  describe("encryptedClientKeyHalf$", () => {
+    it("should track the encryptedClientKeyHalf state", async () => {
+      const state = stateProvider.activeUser.getFake(ENCRYPTED_CLIENT_KEY_HALF);
+      state.nextState(undefined);
+
+      expect(await firstValueFrom(sut.encryptedClientKeyHalf$)).toBe(null);
+
+      state.nextState(encryptedClientKeyHalf);
+
+      expect(await firstValueFrom(sut.encryptedClientKeyHalf$)).toEqual(encClientKeyHalf);
+    });
+  });
+
+  describe("setEncryptedClientKeyHalf", () => {
+    it("should update the encryptedClientKeyHalf$", async () => {
+      await sut.setEncryptedClientKeyHalf(encClientKeyHalf);
+
+      expect(await firstValueFrom(sut.encryptedClientKeyHalf$)).toEqual(encClientKeyHalf);
+    });
+  });
+});

libs/common/src/platform/biometrics/biometric-state.service.ts

@@ -0,0 +1,75 @@
+import { Observable, firstValueFrom, map } from "rxjs";
+
+import { UserId } from "../../types/guid";
+import { EncryptedString, EncString } from "../models/domain/enc-string";
+import { ActiveUserState, StateProvider } from "../state";
+
+import { ENCRYPTED_CLIENT_KEY_HALF } from "./biometric.state";
+
+export abstract class BiometricStateService {
+  /**
+   * If the user has elected to require a password on first unlock of an application instance, this key will store the
+   * encrypted client key half used to unlock the vault.
+   *
+   * Tracks the currently active user
+   */
+  encryptedClientKeyHalf$: Observable<EncString | undefined>;
+  /**
+   * whether or not a password is required on first unlock after opening the application
+   *
+   * tracks the currently active user
+   */
+  requirePasswordOnStart$: Observable<boolean>;
+
+  abstract setEncryptedClientKeyHalf(encryptedKeyHalf: EncString): Promise<void>;
+  abstract getEncryptedClientKeyHalf(userId: UserId): Promise<EncString>;
+  abstract getRequirePasswordOnStart(userId: UserId): Promise<boolean>;
+  abstract removeEncryptedClientKeyHalf(userId: UserId): Promise<void>;
+}
+
+export class DefaultBiometricStateService implements BiometricStateService {
+  private encryptedClientKeyHalfState: ActiveUserState<EncryptedString | undefined>;
+  encryptedClientKeyHalf$: Observable<EncString | undefined>;
+  requirePasswordOnStart$: Observable<boolean>;
+
+  constructor(private stateProvider: StateProvider) {
+    this.encryptedClientKeyHalfState = this.stateProvider.getActive(ENCRYPTED_CLIENT_KEY_HALF);
+    this.encryptedClientKeyHalf$ = this.encryptedClientKeyHalfState.state$.pipe(
+      map(encryptedClientKeyHalfToEncString),
+    );
+    this.requirePasswordOnStart$ = this.encryptedClientKeyHalf$.pipe(map((keyHalf) => !!keyHalf));
+  }
+
+  async setEncryptedClientKeyHalf(encryptedKeyHalf: EncString): Promise<void> {
+    await this.encryptedClientKeyHalfState.update(() => encryptedKeyHalf?.encryptedString ?? null);
+  }
+
+  async removeEncryptedClientKeyHalf(userId: UserId): Promise<void> {
+    await this.stateProvider.getUser(userId, ENCRYPTED_CLIENT_KEY_HALF).update(() => null);
+  }
+
+  async getRequirePasswordOnStart(userId: UserId): Promise<boolean> {
+    if (userId == null) {
+      return false;
+    }
+    return !!(await this.getEncryptedClientKeyHalf(userId));
+  }
+
+  async getEncryptedClientKeyHalf(userId: UserId): Promise<EncString> {
+    return await firstValueFrom(
+      this.stateProvider
+        .getUser(userId, ENCRYPTED_CLIENT_KEY_HALF)
+        .state$.pipe(map(encryptedClientKeyHalfToEncString)),
+    );
+  }
+
+  async logout(userId: UserId): Promise<void> {
+    await this.stateProvider.getUser(userId, ENCRYPTED_CLIENT_KEY_HALF).update(() => null);
+  }
+}
+
+function encryptedClientKeyHalfToEncString(
+  encryptedKeyHalf: EncryptedString | undefined,
+): EncString {
+  return encryptedKeyHalf == null ? null : new EncString(encryptedKeyHalf);
+}

libs/common/src/platform/biometrics/biometric.state.spec.ts

@@ -0,0 +1,13 @@
+import { ENCRYPTED_CLIENT_KEY_HALF } from "./biometric.state";
+
+describe("encrypted client key half", () => {
+  const sut = ENCRYPTED_CLIENT_KEY_HALF;
+
+  it("should deserialize encrypted client key half state", () => {
+    const encryptedClientKeyHalf = "encryptedClientKeyHalf";
+
+    const result = sut.deserializer(JSON.parse(JSON.stringify(encryptedClientKeyHalf)));
+
+    expect(result).toEqual(encryptedClientKeyHalf);
+  });
+});

libs/common/src/platform/biometrics/biometric.state.ts

@@ -0,0 +1,17 @@
+import { EncryptedString } from "../models/domain/enc-string";
+import { KeyDefinition, BIOMETRIC_SETTINGS_DISK } from "../state";
+
+/**
+ * If the user has elected to require a password on first unlock of an application instance, this key will store the
+ * encrypted client key half used to unlock the vault.
+ *
+ * For operating systems without application-level key storage, this key half is concatenated with a signature
+ * provided by the OS and used to encrypt the biometric key prior to storage.
+ */
+export const ENCRYPTED_CLIENT_KEY_HALF = new KeyDefinition<EncryptedString>(
+  BIOMETRIC_SETTINGS_DISK,
+  "clientKeyHalf",
+  {
+    deserializer: (obj) => obj,
+  },
+);

libs/common/src/platform/services/key-state/org-keys.state.spec.ts

@@ -1,22 +1,12 @@
 import { mock } from "jest-mock-extended";
 
-import { makeStaticByteArray } from "../../../../spec";
-import { ProviderEncryptedOrganizationKey } from "../../../admin-console/models/domain/encrypted-organization-key";
+import { makeEncString, makeStaticByteArray } from "../../../../spec";
 import { OrgKey } from "../../../types/key";
 import { CryptoService } from "../../abstractions/crypto.service";
-import { EncryptionType } from "../../enums";
-import { Utils } from "../../misc/utils";
-import { EncString } from "../../models/domain/enc-string";
 import { SymmetricCryptoKey } from "../../models/domain/symmetric-crypto-key";
 
 import { USER_ENCRYPTED_ORGANIZATION_KEYS, USER_ORGANIZATION_KEYS } from "./org-keys.state";
 
-function makeEncString(data?: string) {
-  data ??= Utils.newGuid();
-  return new EncString(EncryptionType.AesCbc256_HmacSha256_B64, data, "test", "test");
-}
-ProviderEncryptedOrganizationKey;
-
 describe("encrypted org keys", () => {
   const sut = USER_ENCRYPTED_ORGANIZATION_KEYS;
 

libs/common/src/platform/services/key-state/provider-keys.state.spec.ts

@@ -1,22 +1,15 @@
 import { mock } from "jest-mock-extended";
 
-import { makeStaticByteArray } from "../../../../spec";
+import { makeEncString, makeStaticByteArray } from "../../../../spec";
 import { ProviderId } from "../../../types/guid";
 import { ProviderKey, UserPrivateKey } from "../../../types/key";
 import { EncryptService } from "../../abstractions/encrypt.service";
-import { EncryptionType } from "../../enums";
-import { Utils } from "../../misc/utils";
-import { EncString, EncryptedString } from "../../models/domain/enc-string";
+import { EncryptedString } from "../../models/domain/enc-string";
 import { SymmetricCryptoKey } from "../../models/domain/symmetric-crypto-key";
 import { CryptoService } from "../crypto.service";
 
 import { USER_ENCRYPTED_PROVIDER_KEYS, USER_PROVIDER_KEYS } from "./provider-keys.state";
 
-function makeEncString(data?: string) {
-  data ??= Utils.newGuid();
-  return new EncString(EncryptionType.AesCbc256_HmacSha256_B64, data, "test", "test");
-}
-
 describe("encrypted provider keys", () => {
   const sut = USER_ENCRYPTED_PROVIDER_KEYS;
 

libs/common/src/platform/state/state-definitions.ts

@@ -22,14 +22,16 @@ export const ACCOUNT_MEMORY = new StateDefinition("account", "memory");
 export const BILLING_BANNERS_DISK = new StateDefinition("billingBanners", "disk");
 
 export const CRYPTO_DISK = new StateDefinition("crypto", "disk");
+
 export const ENVIRONMENT_DISK = new StateDefinition("environment", "disk");
 
 export const GENERATOR_DISK = new StateDefinition("generator", "disk");
 export const GENERATOR_MEMORY = new StateDefinition("generator", "memory");
 
+export const BIOMETRIC_SETTINGS_DISK = new StateDefinition("biometricSettings", "disk");
+
 // Admin Console
 export const ORGANIZATIONS_DISK = new StateDefinition("organizations", "disk");
 export const POLICIES_DISK = new StateDefinition("policies", "disk");
 export const POLICIES_MEMORY = new StateDefinition("policies", "memory");
 export const PROVIDERS_DISK = new StateDefinition("providers", "disk");
-//

libs/common/src/state-migrations/migrate.ts

@@ -9,6 +9,7 @@ import { EverHadUserKeyMigrator } from "./migrations/10-move-ever-had-user-key-t
 import { OrganizationKeyMigrator } from "./migrations/11-move-org-keys-to-state-providers";
 import { MoveEnvironmentStateToProviders } from "./migrations/12-move-environment-state-to-providers";
 import { ProviderKeyMigrator } from "./migrations/13-move-provider-keys-to-state-providers";
+import { MoveBiometricClientKeyHalfToStateProviders } from "./migrations/14-move-biometric-client-key-half-state-to-providers";
 import { FixPremiumMigrator } from "./migrations/3-fix-premium";
 import { RemoveEverBeenUnlockedMigrator } from "./migrations/4-remove-ever-been-unlocked";
 import { AddKeyTypeToOrgKeysMigrator } from "./migrations/5-add-key-type-to-org-keys";
@@ -19,7 +20,7 @@ import { MoveBrowserSettingsToGlobal } from "./migrations/9-move-browser-setting
 import { MinVersionMigrator } from "./migrations/min-version";
 
 export const MIN_VERSION = 2;
-export const CURRENT_VERSION = 13;
+export const CURRENT_VERSION = 14;
 export type MinVersion = typeof MIN_VERSION;
 
 export async function migrate(
@@ -36,7 +37,6 @@ export async function migrate(
     await storageService.save("stateVersion", CURRENT_VERSION);
     return;
   }
-
   await MigrationBuilder.create()
     .with(MinVersionMigrator)
     .with(FixPremiumMigrator, 2, 3)
@@ -49,7 +49,8 @@ export async function migrate(
     .with(EverHadUserKeyMigrator, 9, 10)
     .with(OrganizationKeyMigrator, 10, 11)
     .with(MoveEnvironmentStateToProviders, 11, 12)
-    .with(ProviderKeyMigrator, 12, CURRENT_VERSION)
+    .with(ProviderKeyMigrator, 12, 13)
+    .with(MoveBiometricClientKeyHalfToStateProviders, 13, CURRENT_VERSION)
 
     .migrate(migrationHelper);
 }

libs/common/src/state-migrations/migrations/14-move-biometric-client-key-half-state-to-providers.spec.ts

@@ -0,0 +1,123 @@
+import { MockProxy, any } from "jest-mock-extended";
+
+import { MigrationHelper } from "../migration-helper";
+import { mockMigrationHelper } from "../migration-helper.spec";
+
+import {
+  MoveBiometricClientKeyHalfToStateProviders,
+  CLIENT_KEY_HALF,
+} from "./14-move-biometric-client-key-half-state-to-providers";
+
+function exampleJSON() {
+  return {
+    global: {
+      otherStuff: "otherStuff1",
+    },
+    authenticatedAccounts: ["user-1", "user-2", "user-3"],
+    "user-1": {
+      keys: {
+        biometricEncryptionClientKeyHalf: "user1-key-half",
+        otherStuff: "overStuff2",
+      },
+      otherStuff: "otherStuff3",
+    },
+    "user-2": {
+      keys: {
+        otherStuff: "otherStuff4",
+      },
+      otherStuff: "otherStuff5",
+    },
+  };
+}
+
+function rollbackJSON() {
+  return {
+    "user_user-1_biometricSettings_clientKeyHalf": "user1-key-half",
+    global: {
+      otherStuff: "otherStuff1",
+    },
+    authenticatedAccounts: ["user-1", "user-2", "user-3"],
+    "user-1": {
+      keys: {
+        otherStuff: "overStuff2",
+      },
+      otherStuff: "otherStuff3",
+    },
+    "user-2": {
+      keys: {
+        otherStuff: "otherStuff4",
+      },
+      otherStuff: "otherStuff5",
+    },
+  };
+}
+
+describe("DesktopBiometricState migrator", () => {
+  let helper: MockProxy<MigrationHelper>;
+  let sut: MoveBiometricClientKeyHalfToStateProviders;
+
+  describe("migrate", () => {
+    beforeEach(() => {
+      helper = mockMigrationHelper(exampleJSON(), 13);
+      sut = new MoveBiometricClientKeyHalfToStateProviders(13, 14);
+    });
+
+    it("should remove biometricEncryptionClientKeyHalf from all accounts", async () => {
+      await sut.migrate(helper);
+      expect(helper.set).toHaveBeenCalledTimes(1);
+      expect(helper.set).toHaveBeenCalledWith("user-1", {
+        keys: {
+          otherStuff: "overStuff2",
+        },
+        otherStuff: "otherStuff3",
+      });
+    });
+
+    it("should set biometricEncryptionClientKeyHalf value for account that have it", async () => {
+      await sut.migrate(helper);
+
+      expect(helper.setToUser).toHaveBeenCalledWith("user-1", CLIENT_KEY_HALF, "user1-key-half");
+    });
+
+    it("should not call extra setToUser", async () => {
+      await sut.migrate(helper);
+
+      expect(helper.setToUser).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("rollback", () => {
+    beforeEach(() => {
+      helper = mockMigrationHelper(rollbackJSON(), 14);
+      sut = new MoveBiometricClientKeyHalfToStateProviders(13, 14);
+    });
+
+    it("should null out new values", async () => {
+      await sut.rollback(helper);
+
+      expect(helper.setToUser).toHaveBeenCalledWith("user-1", CLIENT_KEY_HALF, null);
+    });
+
+    it("should add explicit value back to accounts", async () => {
+      await sut.rollback(helper);
+
+      expect(helper.set).toHaveBeenCalledTimes(1);
+      expect(helper.set).toHaveBeenCalledWith("user-1", {
+        keys: {
+          biometricEncryptionClientKeyHalf: "user1-key-half",
+          otherStuff: "overStuff2",
+        },
+        otherStuff: "otherStuff3",
+      });
+    });
+
+    it.each(["user-2", "user-3"])(
+      "should not try to restore values to missing accounts",
+      async (userId) => {
+        await sut.rollback(helper);
+
+        expect(helper.set).not.toHaveBeenCalledWith(userId, any());
+      },
+    );
+  });
+});

libs/common/src/state-migrations/migrations/14-move-biometric-client-key-half-state-to-providers.ts

@@ -0,0 +1,65 @@
+import { KeyDefinitionLike, MigrationHelper } from "../migration-helper";
+import { Migrator } from "../migrator";
+
+type ExpectedAccountType = {
+  settings?: {
+    disableAutoBiometricsPrompt?: boolean;
+    biometricUnlock?: boolean;
+    dismissedBiometricRequirePasswordOnStartCallout?: boolean;
+  };
+  keys?: { biometricEncryptionClientKeyHalf?: string };
+};
+
+// Biometric text, no auto prompt text, fingerprint validated, and prompt cancelled are refreshed on every app start, so we don't need to migrate them
+export const CLIENT_KEY_HALF: KeyDefinitionLike = {
+  key: "clientKeyHalf",
+  stateDefinition: { name: "biometricSettings" },
+};
+
+export class MoveBiometricClientKeyHalfToStateProviders extends Migrator<13, 14> {
+  async migrate(helper: MigrationHelper): Promise<void> {
+    const legacyAccounts = await helper.getAccounts<ExpectedAccountType>();
+
+    await Promise.all(
+      legacyAccounts.map(async ({ userId, account }) => {
+        // Move account data
+        if (account?.keys?.biometricEncryptionClientKeyHalf != null) {
+          await helper.setToUser(
+            userId,
+            CLIENT_KEY_HALF,
+            account.keys.biometricEncryptionClientKeyHalf,
+          );
+
+          // Delete old account data
+          delete account?.keys?.biometricEncryptionClientKeyHalf;
+          await helper.set(userId, account);
+        }
+      }),
+    );
+  }
+
+  async rollback(helper: MigrationHelper): Promise<void> {
+    async function rollbackUser(userId: string, account: ExpectedAccountType) {
+      let updatedAccount = false;
+
+      const userKeyHalf = await helper.getFromUser<string>(userId, CLIENT_KEY_HALF);
+
+      if (userKeyHalf) {
+        account ??= {};
+        account.keys ??= {};
+
+        updatedAccount = true;
+        account.keys.biometricEncryptionClientKeyHalf = userKeyHalf;
+        await helper.setToUser(userId, CLIENT_KEY_HALF, null);
+      }
+
+      if (updatedAccount) {
+        await helper.set(userId, account);
+      }
+    }
+
+    const accounts = await helper.getAccounts<ExpectedAccountType>();
+
+    await Promise.all(accounts.map(({ userId, account }) => rollbackUser(userId, account)));
+  }
+}