@ledgerhq/live-common 24.0.0 → 24.1.0-next.0

package/src/hw/extractOnboardingState.ts

@@ -0,0 +1,97 @@
+import { DeviceExtractOnboardingStateError } from "@ledgerhq/errors";
+import { SeedPhraseType } from "../types/manager";
+
+const onboardingFlagsBytesLength = 4;
+
+const onboardedMask = 0x04;
+const inRecoveryModeMask = 0x01;
+const seedPhraseTypeMask = 0x60;
+const seedPhraseTypeFlagOffset = 5;
+const currentSeedWordIndexMask = 0x1f;
+
+const fromBitsToSeedPhraseType = new Map<number, SeedPhraseType>([
+  [0, SeedPhraseType.TwentyFour],
+  [1, SeedPhraseType.Eighteen],
+  [2, SeedPhraseType.Twelve],
+]);
+
+export enum OnboardingStep {
+  WelcomeScreen = "WELCOME_SCREEN",
+  SetupChoice = "SETUP_CHOICE",
+  Pin = "PIN",
+  NewDevice = "NEW_DEVICE", // path "new device" & currentSeedWordIndex available
+  NewDeviceConfirming = "NEW_DEVICE_CONFIRMING", // path "new device" & currentSeedWordIndex available
+  RestoreSeed = "RESTORE_SEED", // path "restore seed" & currentSeedWordIndex available
+  SafetyWarning = "SAFETY WARNING",
+  Ready = "READY",
+}
+
+const fromBitsToOnboardingStep = new Map<number, OnboardingStep>([
+  [0, OnboardingStep.WelcomeScreen],
+  [1, OnboardingStep.SetupChoice],
+  [2, OnboardingStep.Pin],
+  [3, OnboardingStep.NewDevice],
+  [4, OnboardingStep.NewDeviceConfirming],
+  [5, OnboardingStep.RestoreSeed],
+  [6, OnboardingStep.SafetyWarning],
+  [7, OnboardingStep.Ready],
+]);
+
+export type OnboardingState = {
+  // Device not yet onboarded otherwise
+  isOnboarded: boolean;
+  // In normal mode otherwise
+  isInRecoveryMode: boolean;
+
+  seedPhraseType: SeedPhraseType;
+
+  currentOnboardingStep: OnboardingStep;
+  currentSeedWordIndex: number;
+};
+
+/**
+ * Extracts the onboarding state of the device
+ * @param flagsBytes Buffer of bytes of length onboardingFlagsBytesLength reprensenting the device state flags
+ * @returns An OnboardingState
+ */
+export const extractOnboardingState = (flagsBytes: Buffer): OnboardingState => {
+  if (!flagsBytes || flagsBytes.length < onboardingFlagsBytesLength) {
+    throw new DeviceExtractOnboardingStateError(
+      "Incorrect onboarding flags bytes"
+    );
+  }
+
+  const isOnboarded = Boolean(flagsBytes[0] & onboardedMask);
+  const isInRecoveryMode = Boolean(flagsBytes[0] & inRecoveryModeMask);
+
+  const seedPhraseTypeBits =
+    (flagsBytes[2] & seedPhraseTypeMask) >> seedPhraseTypeFlagOffset;
+  const seedPhraseType = fromBitsToSeedPhraseType.get(seedPhraseTypeBits);
+
+  if (!seedPhraseType) {
+    throw new DeviceExtractOnboardingStateError(
+      "Incorrect onboarding bits for the seed phrase type"
+    );
+  }
+
+  const currentOnboardingStepBits = flagsBytes[3];
+  const currentOnboardingStep = fromBitsToOnboardingStep.get(
+    currentOnboardingStepBits
+  );
+
+  if (!currentOnboardingStep) {
+    throw new DeviceExtractOnboardingStateError(
+      "Incorrect onboarding bits for the current onboarding step"
+    );
+  }
+
+  const currentSeedWordIndex = flagsBytes[2] & currentSeedWordIndexMask;
+
+  return {
+    isOnboarded,
+    isInRecoveryMode,
+    seedPhraseType,
+    currentOnboardingStep,
+    currentSeedWordIndex,
+  };
+};

package/src/hw/getOnboardingStatePolling.test.ts

@@ -0,0 +1,247 @@
+import { getOnboardingStatePolling } from "./getOnboardingStatePolling";
+import { from, Subscription, TimeoutError } from "rxjs";
+import * as rxjsOperators from "rxjs/operators";
+import { DeviceModelId } from "@ledgerhq/devices";
+import Transport from "@ledgerhq/hw-transport";
+import {
+  DeviceExtractOnboardingStateError,
+  DisconnectedDevice,
+} from "@ledgerhq/errors";
+import { withDevice } from "./deviceAccess";
+import getVersion from "./getVersion";
+import {
+  extractOnboardingState,
+  OnboardingState,
+  OnboardingStep,
+} from "./extractOnboardingState";
+import { SeedPhraseType } from "../types/manager";
+
+jest.mock("./deviceAccess");
+jest.mock("./getVersion");
+jest.mock("./extractOnboardingState");
+jest.mock("@ledgerhq/hw-transport");
+jest.useFakeTimers();
+
+const aDevice = {
+  deviceId: "DEVICE_ID_A",
+  deviceName: "DEVICE_NAME_A",
+  modelId: DeviceModelId.nanoFTS,
+  wired: false,
+};
+
+// As extractOnboardingState is mocked, the firmwareInfo
+// returned by getVersion does not matter
+const aFirmwareInfo = {
+  isBootloader: false,
+  rawVersion: "",
+  targetId: 0,
+  mcuVersion: "",
+  flags: Buffer.from([]),
+};
+
+const pollingPeriodMs = 1000;
+
+const mockedGetVersion = jest.mocked(getVersion);
+
+const mockedWithDevice = jest.mocked(withDevice);
+mockedWithDevice.mockReturnValue((job) => from(job(new Transport())));
+
+const mockedExtractOnboardingState = jest.mocked(extractOnboardingState);
+
+describe("getOnboardingStatePolling", () => {
+  let anOnboardingState: OnboardingState;
+  let onboardingStatePollingSubscription: Subscription | null;
+
+  beforeEach(() => {
+    anOnboardingState = {
+      isOnboarded: false,
+      isInRecoveryMode: false,
+      seedPhraseType: SeedPhraseType.TwentyFour,
+      currentSeedWordIndex: 0,
+      currentOnboardingStep: OnboardingStep.NewDevice,
+    };
+  });
+
+  afterEach(() => {
+    mockedGetVersion.mockClear();
+    mockedExtractOnboardingState.mockClear();
+    jest.clearAllTimers();
+    onboardingStatePollingSubscription?.unsubscribe();
+  });
+
+  describe("When a communication error occurs while fetching the device state", () => {
+    describe("and when the error is allowed and thrown before the defined timeout", () => {
+      it("should update the onboarding state to null and keep track of the allowed error", (done) => {
+        mockedGetVersion.mockRejectedValue(
+          new DisconnectedDevice("An allowed error")
+        );
+        mockedExtractOnboardingState.mockReturnValue(anOnboardingState);
+
+        const device = aDevice;
+
+        getOnboardingStatePolling({
+          deviceId: device.deviceId,
+          pollingPeriodMs,
+        }).subscribe({
+          next: (value) => {
+            expect(value.onboardingState).toBeNull();
+            expect(value.allowedError).toBeInstanceOf(DisconnectedDevice);
+            done();
+          },
+        });
+
+        // The timeout is equal to pollingPeriodMs by default
+        jest.advanceTimersByTime(pollingPeriodMs - 1);
+      });
+    });
+
+    describe("and when a timeout occurred before the error (or the fetch took too long)", () => {
+      it("should update the allowed error value to notify the consumer - default value for the timeout", (done) => {
+        mockedGetVersion.mockResolvedValue(aFirmwareInfo);
+        mockedExtractOnboardingState.mockReturnValue(anOnboardingState);
+
+        const device = aDevice;
+
+        getOnboardingStatePolling({
+          deviceId: device.deviceId,
+          pollingPeriodMs,
+        }).subscribe({
+          next: (value) => {
+            expect(value.onboardingState).toBeNull();
+            expect(value.allowedError).toBeInstanceOf(TimeoutError);
+            done();
+          },
+        });
+
+        // Waits more than the timeout
+        jest.advanceTimersByTime(pollingPeriodMs + 1);
+      });
+
+      it("should update the allowed error value to notify the consumer - timeout value set by the consumer", (done) => {
+        const fetchingTimeoutMs = pollingPeriodMs + 500;
+        mockedGetVersion.mockResolvedValue(aFirmwareInfo);
+        mockedExtractOnboardingState.mockReturnValue(anOnboardingState);
+
+        const device = aDevice;
+
+        getOnboardingStatePolling({
+          deviceId: device.deviceId,
+          pollingPeriodMs,
+          fetchingTimeoutMs,
+        }).subscribe({
+          next: (value) => {
+            expect(value.onboardingState).toBeNull();
+            expect(value.allowedError).toBeInstanceOf(TimeoutError);
+            done();
+          },
+        });
+
+        // Waits more than the timeout
+        jest.advanceTimersByTime(fetchingTimeoutMs + 1);
+      });
+    });
+
+    describe("and when the error is fatal and thrown before the defined timeout", () => {
+      it("should notify the consumer that a unallowed error occurred", (done) => {
+        mockedGetVersion.mockRejectedValue(new Error("Unknown error"));
+
+        const device = aDevice;
+
+        getOnboardingStatePolling({
+          deviceId: device.deviceId,
+          pollingPeriodMs,
+        }).subscribe({
+          error: (error) => {
+            expect(error).toBeInstanceOf(Error);
+            expect(error?.message).toBe("Unknown error");
+            done();
+          },
+        });
+
+        jest.advanceTimersByTime(pollingPeriodMs - 1);
+      });
+    });
+  });
+
+  describe("When the fetched device state is incorrect", () => {
+    it("should return a null onboarding state, and keep track of the extract error", (done) => {
+      mockedGetVersion.mockResolvedValue(aFirmwareInfo);
+      mockedExtractOnboardingState.mockImplementation(() => {
+        throw new DeviceExtractOnboardingStateError(
+          "Some incorrect device info"
+        );
+      });
+
+      const device = aDevice;
+
+      onboardingStatePollingSubscription = getOnboardingStatePolling({
+        deviceId: device.deviceId,
+        pollingPeriodMs,
+      }).subscribe({
+        next: (value) => {
+          expect(value.onboardingState).toBeNull();
+          expect(value.allowedError).toBeInstanceOf(
+            DeviceExtractOnboardingStateError
+          );
+          done();
+        },
+      });
+
+      jest.advanceTimersByTime(pollingPeriodMs - 1);
+    });
+  });
+
+  describe("When polling returns a correct device state", () => {
+    it("should return a correct onboarding state", (done) => {
+      mockedGetVersion.mockResolvedValue(aFirmwareInfo);
+      mockedExtractOnboardingState.mockReturnValue(anOnboardingState);
+
+      const device = aDevice;
+
+      onboardingStatePollingSubscription = getOnboardingStatePolling({
+        deviceId: device.deviceId,
+        pollingPeriodMs,
+      }).subscribe({
+        next: (value) => {
+          expect(value.allowedError).toBeNull();
+          expect(value.onboardingState).toEqual(anOnboardingState);
+          done();
+        },
+        error: (error) => {
+          done(error);
+        },
+      });
+
+      jest.advanceTimersByTime(pollingPeriodMs - 1);
+    });
+
+    it("should poll a new onboarding state after the defined period of time", (done) => {
+      mockedGetVersion.mockResolvedValue(aFirmwareInfo);
+      mockedExtractOnboardingState.mockReturnValue(anOnboardingState);
+
+      const device = aDevice;
+
+      // Did not manage to test that the polling is repeated by using jest's fake timer
+      // and advanceTimersByTime method or equivalent.
+      // Hacky test: spy on the repeat operator to see if it has been called.
+      const spiedRepeat = jest.spyOn(rxjsOperators, "repeat");
+
+      onboardingStatePollingSubscription = getOnboardingStatePolling({
+        deviceId: device.deviceId,
+        pollingPeriodMs,
+      }).subscribe({
+        next: (value) => {
+          expect(value.onboardingState).toEqual(anOnboardingState);
+          expect(value.allowedError).toBeNull();
+          expect(spiedRepeat).toHaveBeenCalledTimes(1);
+          done();
+        },
+        error: (error) => {
+          done(error);
+        },
+      });
+
+      jest.runOnlyPendingTimers();
+    });
+  });
+});

package/src/hw/getOnboardingStatePolling.ts

@@ -0,0 +1,153 @@
+import {
+  from,
+  merge,
+  partition,
+  of,
+  throwError,
+  Observable,
+  TimeoutError,
+} from "rxjs";
+import { map, catchError, repeat, first, timeout } from "rxjs/operators";
+import getVersion from "./getVersion";
+import { withDevice } from "./deviceAccess";
+import {
+  TransportStatusError,
+  DeviceOnboardingStatePollingError,
+  DeviceExtractOnboardingStateError,
+  DisconnectedDevice,
+  CantOpenDevice,
+} from "@ledgerhq/errors";
+import { FirmwareInfo } from "../types/manager";
+import {
+  extractOnboardingState,
+  OnboardingState,
+} from "./extractOnboardingState";
+
+export type OnboardingStatePollingResult = {
+  onboardingState: OnboardingState | null;
+  allowedError: Error | null;
+};
+
+/**
+ * Polls the device onboarding state at a given frequency
+ * @param deviceId A device id
+ * @param pollingPeriodMs The period in ms after which the device onboarding state is fetched again
+ * @param fetchingTimeoutMs The time to wait while fetching for the device onboarding state before throwing an error, in ms
+ * @returns An Observable that polls the device onboarding state
+ */
+export const getOnboardingStatePolling = ({
+  deviceId,
+  pollingPeriodMs,
+  fetchingTimeoutMs = pollingPeriodMs,
+}: {
+  deviceId: string;
+  pollingPeriodMs: number;
+  fetchingTimeoutMs?: number;
+}): Observable<OnboardingStatePollingResult> => {
+  let firstRun = true;
+
+  const delayedOnceOnboardingStateObservable: Observable<OnboardingStatePollingResult> =
+    new Observable((subscriber) => {
+      const delayMs = firstRun ? 0 : pollingPeriodMs;
+      firstRun = false;
+
+      const getOnboardingStateOnce = () => {
+        const firmwareInfoOrAllowedErrorObservable = withDevice(deviceId)((t) =>
+          from(getVersion(t))
+        ).pipe(
+          timeout(fetchingTimeoutMs), // Throws a TimeoutError
+          first(),
+          catchError((error: any) => {
+            if (isAllowedOnboardingStatePollingError(error)) {
+              // Pushes the error to the next step to be processed (no retry from the beginning)
+              return of(error);
+            }
+
+            return throwError(error);
+          })
+        );
+
+        // If an error is catched previously, and this error is "allowed",
+        // the value from the observable is not a FirmwareInfo but an Error
+        const [firmwareInfoObservable, allowedErrorObservable] = partition(
+          firmwareInfoOrAllowedErrorObservable,
+          // TS cannot infer correctly the value given to RxJS partition
+          (value: any) => Boolean(value?.flags)
+        );
+
+        const onboardingStateFromFirmwareInfoObservable =
+          firmwareInfoObservable.pipe(
+            map((firmwareInfo: FirmwareInfo) => {
+              let onboardingState: OnboardingState | null = null;
+
+              try {
+                onboardingState = extractOnboardingState(firmwareInfo.flags);
+              } catch (error: any) {
+                if (error instanceof DeviceExtractOnboardingStateError) {
+                  return {
+                    onboardingState: null,
+                    allowedError: error,
+                  };
+                } else {
+                  return {
+                    onboardingState: null,
+                    allowedError: new DeviceOnboardingStatePollingError(
+                      `SyncOnboarding: Unknown error while extracting the onboarding state ${
+                        error?.name ?? error
+                      } ${error?.message}`
+                    ),
+                  };
+                }
+              }
+              return { onboardingState, allowedError: null };
+            })
+          );
+
+        // Handles the case of an (allowed) Error value
+        const onboardingStateFromAllowedErrorObservable =
+          allowedErrorObservable.pipe(
+            map((allowedError: Error) => {
+              return {
+                onboardingState: null,
+                allowedError: allowedError,
+              };
+            })
+          );
+
+        return merge(
+          onboardingStateFromFirmwareInfoObservable,
+          onboardingStateFromAllowedErrorObservable
+        );
+      };
+
+      // Delays the fetch of the onboarding state
+      setTimeout(() => {
+        getOnboardingStateOnce().subscribe({
+          next: (value: OnboardingStatePollingResult) => {
+            subscriber.next(value);
+          },
+          error: (error: any) => {
+            subscriber.error(error);
+          },
+          complete: () => subscriber.complete(),
+        });
+      }, delayMs);
+    });
+
+  return delayedOnceOnboardingStateObservable.pipe(repeat());
+};
+
+export const isAllowedOnboardingStatePollingError = (error: Error): boolean => {
+  if (
+    error &&
+    // Timeout error is thrown by rxjs's timeout
+    (error instanceof TimeoutError ||
+      error instanceof DisconnectedDevice ||
+      error instanceof CantOpenDevice ||
+      error instanceof TransportStatusError)
+  ) {
+    return true;
+  }
+
+  return false;
+};