@ledgerhq/live-common 34.38.1 → 34.39.0-nightly.0

package/src/hw/extractOnboardingState.ts

@@ -1,6 +1,8 @@
 import { DeviceExtractOnboardingStateError } from "@ledgerhq/errors";
 import { SeedPhraseType } from "@ledgerhq/types-live";
 
+const CHARON_STEP_BIT_MASK = 0x1000;
+
 const onboardingFlagsBytesLength = 4;
 
 const onboardedMask = 0x04;
@@ -38,25 +40,34 @@ export enum OnboardingStep {
   RecoverRestore = "RECOVER_RESTORE", // path "restore with Recover"
   SafetyWarning = "SAFETY WARNING",
   Ready = "READY",
+  BackupCharon = "BACKUP_CHARON",
+  RestoreCharon = "RESTORE_CHARON",
 }
 
 const fromBitsToOnboardingStep = new Map<number, OnboardingStep>([
-  [0, OnboardingStep.WelcomeScreen1],
-  [1, OnboardingStep.WelcomeScreen2],
-  [2, OnboardingStep.WelcomeScreen3],
-  [3, OnboardingStep.WelcomeScreen4],
-  [4, OnboardingStep.WelcomeScreenReminder],
-  [5, OnboardingStep.SetupChoice],
-  [6, OnboardingStep.Pin],
-  [7, OnboardingStep.NewDevice],
-  [8, OnboardingStep.NewDeviceConfirming],
-  [9, OnboardingStep.RestoreSeed],
-  [10, OnboardingStep.SafetyWarning],
-  [11, OnboardingStep.Ready],
-  [12, OnboardingStep.ChooseName],
-  [13, OnboardingStep.RecoverRestore],
-  [14, OnboardingStep.SetupChoiceRestore],
-  [15, OnboardingStep.OnboardingEarlyCheck],
+  [0x0, OnboardingStep.WelcomeScreen1],
+  [0x1, OnboardingStep.WelcomeScreen2],
+  [0x2, OnboardingStep.WelcomeScreen3],
+  [0x3, OnboardingStep.WelcomeScreen4],
+  [0x4, OnboardingStep.WelcomeScreenReminder],
+  [0x5, OnboardingStep.SetupChoice],
+  [0x6, OnboardingStep.Pin],
+  [0x7, OnboardingStep.NewDevice],
+  [0x8, OnboardingStep.NewDeviceConfirming],
+  [0x9, OnboardingStep.RestoreSeed],
+  [0xa, OnboardingStep.SafetyWarning],
+  [0xb, OnboardingStep.Ready],
+  [0xc, OnboardingStep.ChooseName],
+  [0xd, OnboardingStep.RecoverRestore],
+  [0xe, OnboardingStep.SetupChoiceRestore],
+  [0xf, OnboardingStep.OnboardingEarlyCheck],
+  [0x10, OnboardingStep.RestoreCharon],
+  [CHARON_STEP_BIT_MASK + 0x0, OnboardingStep.Ready], // default state, after boot, if no backup was pending, this is also the state right after the device is seeded (if it was seeded with Charon)
+  [CHARON_STEP_BIT_MASK + 0x1, OnboardingStep.Ready], // backup fully refused
+  [CHARON_STEP_BIT_MASK + 0x2, OnboardingStep.BackupCharon], // backup not started or fully refused, this is the state right after the device is seeded (unless it was seeded with Charon)
+  [CHARON_STEP_BIT_MASK + 0x3, OnboardingStep.BackupCharon], // backup process started but not finished
+  [CHARON_STEP_BIT_MASK + 0x4, OnboardingStep.BackupCharon], // backup done on RK and naming not finished
+  [CHARON_STEP_BIT_MASK + 0x5, OnboardingStep.Ready], // backup done on RK and backup-process exited
 ]);
 
 export type OnboardingState = {
@@ -69,14 +80,36 @@ export type OnboardingState = {
 
   currentOnboardingStep: OnboardingStep;
   currentSeedWordIndex: number;
+  charonSupported: boolean;
+  charonStatus: CharonStatus | null;
 };
 
+export enum CharonStatus {
+  Rejected = 1,
+  Choice,
+  Running,
+  Naming,
+  Ready,
+}
+
+export const fromBitsToCharonStatusMap = new Map<number, CharonStatus>([
+  [0x1, CharonStatus.Rejected],
+  [0x2, CharonStatus.Choice],
+  [0x3, CharonStatus.Running],
+  [0x4, CharonStatus.Naming],
+  [0x5, CharonStatus.Ready],
+]);
+
 /**
  * Extracts the onboarding state of the device
  * @param flagsBytes Buffer of bytes of length onboardingFlagsBytesLength representing the device state flags
+ * @param charonStatusFlags Buffer of bytes of length charonStatusFlagsLength representing the charon status flags
  * @returns An OnboardingState
  */
-export const extractOnboardingState = (flagsBytes: Buffer): OnboardingState => {
+export const extractOnboardingState = (
+  flagsBytes: Buffer,
+  charonState?: Buffer,
+): OnboardingState => {
   if (!flagsBytes || flagsBytes.length < onboardingFlagsBytesLength) {
     throw new DeviceExtractOnboardingStateError("Incorrect onboarding flags bytes");
   }
@@ -94,7 +127,7 @@ export const extractOnboardingState = (flagsBytes: Buffer): OnboardingState => {
   }
 
   const currentOnboardingStepBits = flagsBytes[3];
-  const currentOnboardingStep = fromBitsToOnboardingStep.get(currentOnboardingStepBits);
+  let currentOnboardingStep = fromBitsToOnboardingStep.get(currentOnboardingStepBits);
 
   if (!currentOnboardingStep) {
     throw new DeviceExtractOnboardingStateError(
@@ -104,11 +137,41 @@ export const extractOnboardingState = (flagsBytes: Buffer): OnboardingState => {
 
   const currentSeedWordIndex = flagsBytes[2] & currentSeedWordIndexMask;
 
+  /*
+   * Once the device is seeded, there are some additional states for backing up with Charon (for devices that support it)
+   * There are 2 scenarios:
+   *  - After the seeding of the device, the user goes through the safety warnings screens (step SafetyWarning), and then, compatible devices will display the backup screens.
+   *    Then, the value of "currentOnboardingStep" is "Ready", and the additional information about the status of the backup is in the "charonState" buffer.
+   *  - If the device is rebooted while the backup screens are displayed on the device, it will still display the backup screens when it is turned back on.
+   *    Then, the value of "currentOnboardingStep" is "WelcomeScreen1", and the additional information about the status of the backup is in the "charonState" buffer.
+   */
+  if (
+    isOnboarded &&
+    [OnboardingStep.Ready, OnboardingStep.WelcomeScreen1].includes(currentOnboardingStep) &&
+    charonState !== undefined
+  ) {
+    currentOnboardingStep = fromBitsToOnboardingStep.get(charonState[0] + CHARON_STEP_BIT_MASK);
+
+    if (!currentOnboardingStep) {
+      throw new DeviceExtractOnboardingStateError(
+        "Incorrect onboarding bits for the current charon step",
+      );
+    }
+  }
+
+  const charonSupported = charonState !== undefined && charonState.length > 0;
+  const charonStatus =
+    charonSupported && fromBitsToCharonStatusMap.has(charonState[0])
+      ? fromBitsToCharonStatusMap.get(charonState[0])!
+      : null;
+
   return {
     isOnboarded,
     isInRecoveryMode,
     seedPhraseType,
     currentOnboardingStep,
     currentSeedWordIndex,
+    charonSupported,
+    charonStatus,
   };
 };

package/src/hw/getDeviceInfo.ts

@@ -61,10 +61,11 @@ export default async function (transport: Transport): Promise<DeviceInfo> {
     mcuBlVersion,
     mcuVersion,
     mcuTargetId,
-    flags,
     bootloaderVersion,
     hardwareVersion,
     languageId,
+    charonState,
+    flags,
   } = res;
   const isOSU = rawVersion.includes("-osu");
   const version = rawVersion.replace("-osu", "");
@@ -114,5 +115,7 @@ export default async function (transport: Transport): Promise<DeviceInfo> {
     bootloaderVersion,
     hardwareVersion,
     languageId,
+    charonState,
+    seFlags: flags,
   };
 }

package/src/hw/getGenuineCheckFromDeviceId.test.ts

@@ -41,7 +41,7 @@ jest.mock("./genuineCheck");
 const mockedGetDeviceInfo = jest.mocked(getDeviceInfo);
 const mockedGenuineCheck = jest.mocked(genuineCheck);
 
-const aDeviceInfo = {
+const aDeviceInfo: DeviceInfo = {
   mcuVersion: "A_MCU_VERSION",
   version: "A_VERSION",
   majMin: "A_MAJ_MIN",
@@ -51,6 +51,7 @@ const aDeviceInfo = {
   providerName: undefined,
   managerAllowed: false,
   pinValidated: true,
+  seFlags: Buffer.alloc(0),
 };
 
 describe("getGenuineCheckFromDeviceId", () => {

package/src/hw/getOnboardingStatePolling.test.ts

@@ -56,6 +56,8 @@ describe("getOnboardingStatePolling", () => {
       seedPhraseType: SeedPhraseType.TwentyFour,
       currentSeedWordIndex: 0,
       currentOnboardingStep: OnboardingStep.NewDevice,
+      charonSupported: false,
+      charonStatus: null,
     };
   });
 

package/src/hw/getOnboardingStatePolling.ts

@@ -83,7 +83,7 @@ export const getOnboardingStatePolling = ({
           }
 
           try {
-            onboardingState = extractOnboardingState(firmwareInfo.flags);
+            onboardingState = extractOnboardingState(firmwareInfo.flags, firmwareInfo.charonState);
           } catch (error: unknown) {
             if (error instanceof DeviceExtractOnboardingStateError) {
               return {

package/src/hw/isFirmwareUpdateVersionSupported.test.ts

@@ -1,4 +1,5 @@
 import { DeviceModelId } from "@ledgerhq/devices";
+import { DeviceInfo } from "@ledgerhq/types-live";
 import isFirmwareUpdateVersionSupported from "./isFirmwareUpdateVersionSupported";
 import { setEnv } from "@ledgerhq/live-env";
 
@@ -17,7 +18,7 @@ const badDataset: { [key in DeviceModelId]?: string[] } = {
 };
 
 describe("Firmware update version availability checks", () => {
-  const getDeviceInfo = version => ({
+  const getDeviceInfo = (version): DeviceInfo => ({
     version,
     mcuVersion: "0.0",
     majMin: "0.0",
@@ -27,6 +28,7 @@ describe("Firmware update version availability checks", () => {
     isBootloader: false,
     managerAllowed: false,
     pinValidated: false,
+    seFlags: Buffer.alloc(0),
   });
 
   describe("Fails with bad values", () => {

package/src/mock/fixtures/aDeviceInfo.ts

@@ -11,6 +11,7 @@ export const aDeviceInfoBuilder = (props?: Partial<DeviceInfo>): DeviceInfo => {
     providerName: undefined,
     managerAllowed: false,
     pinValidated: true,
+    seFlags: Buffer.alloc(0),
     ...props,
   };
 };

package/src/onboarding/hooks/useOnboardingStatePolling.test.ts

@@ -36,6 +36,8 @@ describe("useOnboardingStatePolling", () => {
       seedPhraseType: SeedPhraseType.TwentyFour,
       currentSeedWordIndex: 0,
       currentOnboardingStep: OnboardingStep.NewDevice,
+      charonSupported: false,
+      charonStatus: null,
     };
 
     aSecondOnboardingState = {