@ledgerhq/ledger-key-ring-protocol 0.5.1-nightly.0

package/tests/scenarios/success.ts

@@ -0,0 +1,94 @@
+import { ScenarioOptions } from "../test-helpers/types";
+
+/**
+ * a complete scenario with 3 members and various sdk successful interactions.
+ */
+export async function scenario(deviceId: string, { sdkForName }: ScenarioOptions) {
+  // first member initializes itself
+  const name1 = "Member 1";
+  const sdk1 = sdkForName(name1);
+  const member1creds = await sdk1.initMemberCredentials();
+
+  // auth with the device and init the first trustchain
+  const { trustchain } = await sdk1.getOrCreateTrustchain(deviceId, member1creds);
+
+  // verify we have member 1 in the trustchain
+  const members = await sdk1.getMembers(trustchain, member1creds);
+  expect(members).toEqual([
+    {
+      id: member1creds.pubkey,
+      name: name1,
+      permissions: 0xffffffff,
+    },
+  ]);
+
+  // second member initializes itself
+  const name2 = "Member 2";
+  const sdk2 = sdkForName(name2);
+  const member2creds = await sdk2.initMemberCredentials();
+
+  // member 1 adds member 2 (= qr code flow)
+  await sdk1.addMember(trustchain, member1creds, {
+    name: name2,
+    id: member2creds.pubkey,
+    permissions: 0xffffffff,
+  });
+
+  // member2 list members and verify it's correct
+  const members2 = await sdk2.getMembers(trustchain, member2creds);
+  const expectedMembers = [
+    {
+      id: member1creds.pubkey,
+      name: name1,
+      permissions: 0xffffffff,
+    },
+    {
+      id: member2creds.pubkey,
+      name: name2,
+      permissions: 0xffffffff,
+    },
+  ];
+  expect(members2).toEqual(expectedMembers);
+
+  // third member initializes itself
+  const name3 = "Member 3";
+  const sdk3 = sdkForName(name3);
+  const member3creds = await sdk3.initMemberCredentials();
+
+  // member 2 adds member 3
+  await sdk2.addMember(trustchain, member2creds, {
+    name: name3,
+    id: member3creds.pubkey,
+    permissions: 0xffffffff,
+  });
+  expectedMembers.push({
+    id: member3creds.pubkey,
+    name: name3,
+    permissions: 0xffffffff,
+  });
+
+  // member1 can also list members and see third member
+  const members1 = await sdk1.getMembers(trustchain, member1creds);
+  expect(members1).toEqual(expectedMembers);
+
+  // as well as member3 itself
+  expect(await sdk3.getMembers(trustchain, member3creds)).toEqual(expectedMembers);
+
+  // member1 removes member2
+  const newTrustchain = await sdk1.removeMember(deviceId, trustchain, member1creds, members2[1]);
+  expectedMembers.splice(1, 1);
+
+  // verify the trustchain has rotated
+  expect(newTrustchain.walletSyncEncryptionKey).not.toBe(trustchain.walletSyncEncryptionKey);
+  expect(newTrustchain.applicationPath).not.toBe(trustchain.applicationPath);
+
+  // member1 can still list members
+  expect(await sdk1.getMembers(newTrustchain, member1creds)).toEqual(expectedMembers);
+
+  // member3 that may not have refreshed yet, can now restore the trustchain
+  const restored = await sdk3.restoreTrustchain(trustchain, member3creds);
+  expect(restored).toEqual(newTrustchain);
+
+  // member2 destroy the trustchain
+  await sdk2.destroyTrustchain(trustchain, member2creds);
+}

package/tests/scenarios/tokenExpires.ts

@@ -0,0 +1,20 @@
+import { ScenarioOptions } from "../test-helpers/types";
+import { HWDeviceProvider } from "../../src/HWDeviceProvider";
+import { SDK } from "../../src/sdk";
+import { getEnv } from "@ledgerhq/live-env";
+
+export async function scenario(deviceId: string, { withDevice, pauseRecorder }: ScenarioOptions) {
+  const apiBaseUrl = getEnv("TRUSTCHAIN_API_STAGING");
+  const hwDeviceProvider = new HWDeviceProvider(apiBaseUrl, withDevice);
+  const applicationId = 16;
+  const sdk = new SDK({ applicationId, name: "Foo", apiBaseUrl }, hwDeviceProvider);
+  const creds = await sdk.initMemberCredentials();
+
+  const jwt1 = await hwDeviceProvider.withJwt(deviceId, jwt => Promise.resolve(jwt));
+  await pauseRecorder(6 * 60 * 1000);
+  const { trustchain } = await sdk.getOrCreateTrustchain(deviceId, creds);
+  const jwt2 = await hwDeviceProvider.withJwt(deviceId, jwt2 => Promise.resolve(jwt2));
+  // assert that jwt was refreshed (due to the expiration)
+  expect(jwt1).not.toEqual(jwt2);
+  await sdk.destroyTrustchain(trustchain, creds);
+}

package/tests/scenarios/twoAddMembersFollowedByDeviceAdd.ts

@@ -0,0 +1,49 @@
+import { ScenarioOptions } from "../test-helpers/types";
+
+/**
+ * a complete scenario with 3 members and various sdk successful interactions.
+ */
+export async function scenario(deviceId: string, { sdkForName }: ScenarioOptions) {
+  // members
+  const name1 = "Member 1";
+  const sdk1 = sdkForName(name1);
+  const member1creds = await sdk1.initMemberCredentials();
+
+  const name2 = "Member 2";
+  const sdk2 = sdkForName(name2);
+  const member2creds = await sdk2.initMemberCredentials();
+  const member2 = { name: name2, id: member2creds.pubkey, permissions: 0xffffffff };
+
+  const name3 = "Member 3";
+  const sdk3 = sdkForName(name3);
+  const member3creds = await sdk3.initMemberCredentials();
+  const member3 = { name: name3, id: member3creds.pubkey, permissions: 0xffffffff };
+
+  const name4 = "Member 4";
+  const sdk4 = sdkForName(name4);
+  const member4creds = await sdk4.initMemberCredentials();
+
+  // auth with the device and init the first trustchain
+  const { trustchain } = await sdk1.getOrCreateTrustchain(deviceId, member1creds);
+
+  // member 1 adds member 2
+  await sdk1.addMember(trustchain, member1creds, member2);
+
+  // member 1 adds member 3
+  await sdk1.addMember(trustchain, member1creds, member3);
+
+  // member 4 implicits add itself with device auth
+  const { trustchain: trustchain4 } = await sdk4.getOrCreateTrustchain(deviceId, member4creds);
+  expect(trustchain).toEqual(trustchain4);
+
+  // list members
+  const members = await sdk3.getMembers(trustchain, member3creds);
+  expect(members.map(m => m.id)).toEqual([
+    member1creds.pubkey,
+    member2creds.pubkey,
+    member3creds.pubkey,
+    member4creds.pubkey,
+  ]);
+
+  await sdk2.destroyTrustchain(trustchain, member2creds);
+}

package/tests/scenarios/userRefusesAuth.ts

@@ -0,0 +1,28 @@
+import { UserRefusedOnDevice } from "@ledgerhq/errors";
+import { RecorderConfig, ScenarioOptions, recorderConfigDefaults } from "../test-helpers/types";
+
+export async function scenario(deviceId: string, { sdkForName }: ScenarioOptions) {
+  const sdk1 = sdkForName("Foo");
+  const memberCredentials = await sdk1.initMemberCredentials();
+  let interactionCounter = 0;
+  let totalInteractionCounter = 0;
+  const callbacks = {
+    onStartRequestUserInteraction: () => {
+      totalInteractionCounter++;
+      interactionCounter++;
+    },
+    onEndRequestUserInteraction: () => {
+      interactionCounter--;
+    },
+  };
+  await expect(sdk1.getOrCreateTrustchain(deviceId, memberCredentials, callbacks)).rejects.toThrow(
+    UserRefusedOnDevice,
+  );
+  expect(interactionCounter).toBe(0);
+  expect(totalInteractionCounter).toBe(1);
+}
+
+export const recorderConfig: RecorderConfig = {
+  goNextOnText: recorderConfigDefaults.goNextOnText.concat(["Log in to"]),
+  approveOnText: ["Cancel login"],
+};

package/tests/scenarios/userRefusesRemoveMember.ts

@@ -0,0 +1,66 @@
+import { UserRefusedOnDevice } from "@ledgerhq/errors";
+import { RecorderConfig, ScenarioOptions } from "../test-helpers/types";
+
+export async function scenario(deviceId: string, { sdkForName }: ScenarioOptions) {
+  // first member initializes itself
+  const name1 = "Member 1";
+  const sdk1 = sdkForName(name1);
+  const member1creds = await sdk1.initMemberCredentials();
+  const member1 = { id: member1creds.pubkey, name: name1, permissions: 0xffffffff };
+
+  // auth with the device and init the first trustchain
+  const { trustchain } = await sdk1.getOrCreateTrustchain(deviceId, member1creds);
+
+  // second member initializes itself
+  const name2 = "Member 2";
+  const sdk2 = sdkForName(name2);
+  const member2creds = await sdk2.initMemberCredentials();
+  const member2 = { id: member2creds.pubkey, name: name2, permissions: 0xffffffff };
+
+  // member1 adds member2 (= qr code flow)
+  await sdk1.addMember(trustchain, member1creds, member2);
+
+  // list members and verify it's correct
+  expect(await sdk2.getMembers(trustchain, member2creds)).toEqual([member1, member2]);
+
+  // member1 refuses to remove member2
+  let interactionCounter = 0;
+  let totalInteractionCounter = 0;
+  const callbacks = {
+    onStartRequestUserInteraction: () => {
+      totalInteractionCounter++;
+      interactionCounter++;
+    },
+    onEndRequestUserInteraction: () => {
+      interactionCounter--;
+    },
+  };
+  await expect(
+    sdk1.removeMember(deviceId, trustchain, member1creds, member2, callbacks),
+  ).rejects.toThrow(UserRefusedOnDevice);
+  expect(interactionCounter).toBe(0);
+  expect(totalInteractionCounter).toBe(3);
+
+  // make sure the member2 is still there
+  expect(await sdk2.getMembers(trustchain, member2creds)).toEqual([member1, member2]);
+}
+
+export const recorderConfig: RecorderConfig = {
+  approveOnceOnText: ["Enable", "Confirm"], // Approve the first interaction (After login)
+  approveOnText: ["Log in to", "Don't enable"],
+
+  goNextOnText: [
+    // Login:
+    ...[
+      "Login request",
+      "Identify with your",
+      "request",
+      "Ensure you trust the",
+      "update request",
+      "keep",
+    ],
+
+    // Refuse the second interaction (remove member):
+    "Enable",
+  ],
+};

package/tests/test-helpers/recordTrustchainSdkTests.ts

@@ -0,0 +1,178 @@
+import fsPromises from "fs/promises";
+import { setupServer } from "msw/node";
+import { RecordStore } from "@ledgerhq/hw-transport-mocker";
+import { createSpeculosDevice, releaseSpeculosDevice } from "@ledgerhq/speculos-transport";
+import { DeviceModelId } from "@ledgerhq/types-devices";
+import { crypto, TRUSTCHAIN_APP_NAME } from "@ledgerhq/hw-ledger-key-ring-protocol";
+import { getEnv, setEnv } from "@ledgerhq/live-env";
+import { RecorderConfig, ScenarioOptions, genSeed, recorderConfigDefaults } from "./types";
+import { getSdk } from "../../src";
+import { WithDevice } from "../../src/types";
+
+setEnv("GET_CALLS_RETRY", 0);
+
+export async function recordTestTrustchainSdk(
+  file: string | null,
+  scenario: (deviceId: string, scenarioOptions: ScenarioOptions) => Promise<void>,
+  config: RecorderConfig,
+) {
+  const seed = config.seed || genSeed();
+  const coinapps = config.coinapps;
+  if (!coinapps) throw new Error("coinapps is required"); // it's completed by e2e script
+
+  const goNextOnText = config.goNextOnText || recorderConfigDefaults.goNextOnText;
+  const approveOnceOnText = config.approveOnceOnText || [];
+  const approveOnText = config.approveOnText || recorderConfigDefaults.approveOnText;
+
+  const buttonClicksPromises: Array<Promise<void>> = [];
+  const recordStore = new RecordStore();
+
+  const createDeviceWithSeed = async (seed: string) => {
+    const device = await createSpeculosDevice({
+      model: DeviceModelId.nanoSP,
+      firmware: "1.1.2",
+      appName: TRUSTCHAIN_APP_NAME,
+      appVersion: "1.0.1",
+      seed,
+      coinapps, // folder where there is the Ledger Sync coin app
+    });
+
+    // passthrough all success cases for the Ledger Sync coin app to accept all.
+    const sub = device.transport.automationEvents.subscribe(event => {
+      const approveOnceIndex = approveOnceOnText.findIndex(t => event.text.trim() == t);
+      if (approveOnceIndex > -1) {
+        approveOnceOnText.splice(approveOnceIndex, 1);
+        buttonClicksPromises.push(device.transport.button("both"));
+      } else if (goNextOnText.some(t => event.text.trim() == t)) {
+        buttonClicksPromises.push(device.transport.button("right"));
+      } else if (approveOnText.some(t => event.text.trim() == t)) {
+        buttonClicksPromises.push(device.transport.button("both"));
+      }
+    });
+
+    // monkey patch the transport to record all device APDU exchanges
+    const transport = device.transport;
+    const originalExchange = transport.exchange;
+    transport.exchange = async function (apdu: Buffer) {
+      const out = await originalExchange.call(transport, apdu);
+      recordStore.recordExchange(apdu, out);
+      return out;
+    };
+
+    return { device, sub };
+  };
+
+  // listen to network with msw to be able to replay in our future tests
+  const transactions: Transaction[] = [];
+  const server = setupServer();
+  server.events.on("response:bypass", ({ response, request }) => {
+    if (request.url.startsWith("http://localhost")) return; // ignore speculos requests
+    const transaction: Transaction = {
+      request: {
+        url: request.url,
+        method: request.method,
+        headers: headersToJson(request.headers),
+      },
+      response: {
+        status: response.status,
+        headers: headersToJson(response.headers),
+      },
+    };
+    transactions.push(transaction);
+    if (request.body) {
+      request.text().then(body => {
+        transaction.request.body = body;
+      });
+    }
+    if (response.body) {
+      response.text().then(body => {
+        transaction.response.body = body;
+      });
+    }
+  });
+
+  // Monkey patches the `crypto.randomBytes` method to log generated random bytes in hexadecimal format in order to deterministically replay them in unit tests.
+  const randomBytesOutputs: string[] = [];
+  const originalRandomBytes = crypto.randomBytes;
+  crypto.randomBytes = async (size: number) => {
+    const bytes = await originalRandomBytes.call(crypto, size);
+    randomBytesOutputs.push(crypto.to_hex(bytes));
+    return bytes;
+  };
+
+  // Monkey patches the `crypto.randomKeypair` method to log generated random keypairs in hexadecimal format in order to deterministically replay them in unit tests.
+  const randomKeypairOutputs: string[] = [];
+  const originalRandomKeypair = crypto.randomKeypair;
+  crypto.randomKeypair = async () => {
+    const keypair = await originalRandomKeypair.call(crypto);
+    randomKeypairOutputs.push(crypto.to_hex(keypair.privateKey));
+    return keypair;
+  };
+
+  let { device, sub } = await createDeviceWithSeed(seed);
+  const withDevice: WithDevice = () => fn => fn(device.transport);
+  const options: ScenarioOptions = {
+    withDevice,
+    sdkForName: name =>
+      getSdk(
+        !!getEnv("MOCK"),
+        { applicationId: 16, name, apiBaseUrl: getEnv("TRUSTCHAIN_API_STAGING") },
+        withDevice,
+      ),
+    pauseRecorder: async (milliseconds: number) => {
+      await new Promise(resolve => setTimeout(resolve, milliseconds));
+    },
+    switchDeviceSeed: async (newSeed?: string) => {
+      // release and replace previous device
+      await releaseSpeculosDevice(device.id);
+      const res = await createDeviceWithSeed(newSeed || genSeed());
+      device = res.device;
+      sub = res.sub;
+      return device;
+    },
+  };
+
+  // Run the scenario with speculos simulator and with all networking recorded.
+  server.listen({ onUnhandledRequest: "bypass" });
+  try {
+    await scenario(device.id, options);
+  } finally {
+    sub.unsubscribe();
+    await Promise.all(buttonClicksPromises);
+    await releaseSpeculosDevice(device.id);
+  }
+  server.close();
+
+  if (file) {
+    const json = {
+      apdus: recordStore.toString(),
+      crypto: { randomBytesOutputs, randomKeypairOutputs },
+      http: { transactions },
+    };
+
+    // Write the transactions to the disk.
+    await fsPromises.writeFile(file, JSON.stringify(json, null, 2));
+  }
+}
+
+function headersToJson(headers) {
+  const obj: Record<string, string> = {};
+  for (const [key, value] of headers.entries()) {
+    obj[key] = value;
+  }
+  return obj;
+}
+
+type Transaction = {
+  request: {
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+  };
+  response: {
+    status: number;
+    headers: Record<string, string>;
+    body?: string;
+  };
+};

package/tests/test-helpers/replayTrustchainSdkTests.ts

@@ -0,0 +1,141 @@
+import { http, HttpResponse } from "msw";
+import { setupServer } from "msw/node";
+import { crypto } from "@ledgerhq/hw-ledger-key-ring-protocol";
+import { openTransportReplayer, RecordStore } from "@ledgerhq/hw-transport-mocker";
+import { getEnv, setEnv } from "@ledgerhq/live-env";
+import { ScenarioOptions } from "./types";
+import { getSdk } from "../../src";
+import { WithDevice } from "../../src/types";
+
+setEnv("GET_CALLS_RETRY", 0);
+
+export async function replayTrustchainSdkTests<Json extends JsonShape>(
+  json: Json,
+  scenario: (deviceId: string, scenarioOptions: ScenarioOptions) => Promise<void>,
+) {
+  // This replays, in order, all HTTP queries we have saved in json records
+  let httpTransactionIndex = 0;
+  const mockServer = setupServer(
+    http.all("*", async ({ request }) => {
+      const id = "http(" + httpTransactionIndex + "): ";
+      const expected = json.http.transactions[httpTransactionIndex++];
+      if (!expected) {
+        throw new Error("unexpected HTTP request has occured: " + request.url.toString());
+      }
+      expect(id + request.method + " " + request.url.toString()).toEqual(
+        id + expected.request.method + " " + expected.request.url,
+      );
+
+      expect({
+        url: request.url.toString(),
+        method: request.method,
+        body: request.body ? await request.text() : undefined,
+        headers: headersToJson(request.headers),
+      }).toEqual({
+        url: expected.request.url,
+        method: expected.request.method,
+        body: expected.request.body,
+        headers: expected.request.headers,
+      });
+
+      const response = new HttpResponse(expected.response.body, {
+        status: expected.response.status,
+        headers: expected.response.headers as Record<string, string>,
+      });
+      HttpResponse.json;
+      return response;
+    }),
+  );
+
+  // This replays, in order, all crypto randomKeypair we have saved in json records
+  let randomKeypairIndex = 0;
+  jest.spyOn(crypto, "randomKeypair").mockImplementation(() => {
+    const emits = json.crypto.randomKeypairOutputs[randomKeypairIndex++];
+    if (!emits) {
+      throw new Error("unexpected randomKeypair call");
+    }
+    const privateKey = crypto.from_hex(emits);
+    return crypto.keypairFromSecretKey(privateKey);
+  });
+
+  // This replays, in order, all crypto randomBytes we have saved in json records
+  let randomBytesIndex = 0;
+  jest.spyOn(crypto, "randomBytes").mockImplementation((size: number) => {
+    const emits = json.crypto.randomBytesOutputs[randomBytesIndex++];
+    if (!emits) {
+      throw new Error("unexpected randomBytes call");
+    }
+    const bytes = crypto.from_hex(emits);
+    if (bytes.length !== size) {
+      throw new Error("unexpected randomBytes size. Expected " + size + " but got " + bytes.length);
+    }
+    return Promise.resolve(bytes);
+  });
+
+  const recordStore = RecordStore.fromString(json.apdus);
+
+  mockServer.listen();
+  mockServer.resetHandlers();
+  try {
+    // This replays, in order, all APDUs we have saved in json records
+    const transport = await openTransportReplayer(recordStore);
+    const device = { id: "", transport };
+    const withDevice: WithDevice = () => fn => fn(device.transport);
+    const options: ScenarioOptions = {
+      withDevice,
+      sdkForName: name =>
+        getSdk(
+          !!getEnv("MOCK"),
+          { applicationId: 16, name, apiBaseUrl: getEnv("TRUSTCHAIN_API_STAGING") },
+          withDevice,
+        ),
+      pauseRecorder: () => Promise.resolve(), // replayer don't need to pause
+      switchDeviceSeed: async () => device, // nothing to actually do, we will continue replaying
+    };
+    await scenario(device.id, options);
+  } finally {
+    mockServer.close();
+  }
+
+  // verify we have consumed all the expected calls
+  expect({
+    httpCalls: httpTransactionIndex,
+    randomKeypairCalls: randomKeypairIndex,
+    randomBytesCalls: randomBytesIndex,
+  }).toEqual({
+    httpCalls: json.http.transactions.length,
+    randomKeypairCalls: json.crypto.randomKeypairOutputs.length,
+    randomBytesCalls: json.crypto.randomBytesOutputs.length,
+  });
+}
+
+type JsonShape = {
+  apdus: string;
+  http: {
+    transactions: {
+      request: {
+        url: string;
+        method: string;
+        body?: string;
+        headers: unknown;
+      };
+      response: {
+        status: number;
+        headers: unknown;
+        body?: string;
+      };
+    }[];
+  };
+  crypto: {
+    randomKeypairOutputs: string[];
+    randomBytesOutputs: string[];
+  };
+};
+
+function headersToJson(headers) {
+  const obj: Record<string, string> = {};
+  for (const [key, value] of headers) {
+    obj[key] = value;
+  }
+  return obj;
+}

package/tests/test-helpers/types.ts

@@ -0,0 +1,45 @@
+import { generateMnemonic } from "bip39";
+import Transport from "@ledgerhq/hw-transport";
+import { TrustchainSDK, WithDevice } from "../../src/types";
+
+export type ScenarioOptions = {
+  /**
+   * easily create a sdk for a given member name
+   */
+  sdkForName: (name: string) => TrustchainSDK;
+  /**
+   * pause the recorder (e2e) part for a given amount of time
+   */
+  pauseRecorder: (milliseconds: number) => Promise<void>;
+  /**
+   * switch to the another device seed
+   */
+  switchDeviceSeed: (newSeed?: string) => Promise<{ id: string; transport: Transport }>;
+  /**
+   * withDevice function to pass to HWDeviceProvider
+   */
+  withDevice: WithDevice;
+};
+
+export type RecorderConfig = {
+  seed?: string;
+  coinapps?: string;
+  overridesAppPath?: string;
+  goNextOnText?: string[];
+  approveOnText?: string[];
+  approveOnceOnText?: string[];
+};
+
+export const recorderConfigDefaults = {
+  goNextOnText: [
+    "Login request",
+    "Identify with your",
+    "request",
+    "Ensure you trust the",
+    "keep",
+    "update request",
+  ],
+  approveOnText: ["Log in to", "Enable", "Confirm"],
+};
+
+export const genSeed = () => generateMnemonic(256);

package/tests/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "compilerOptions": {
+      "noEmit": true,
+      "esModuleInterop": true,
+      "lib": ["es2020"],
+      "types": ["jest"]
+  }
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../tsconfig.base",
+  "compilerOptions": {
+    "declaration": true,
+    "declarationMap": true,
+    "noImplicitAny": false,
+    "noImplicitThis": false,
+    "downlevelIteration": true,
+    "module": "commonjs",
+    "lib": ["es2020", "dom"],
+    "outDir": "lib"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["src/__tests__/**/*"]
+}