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

package/src/types.ts

@@ -0,0 +1,242 @@
+import { Observable } from "rxjs";
+import Transport from "@ledgerhq/hw-transport";
+import { TrustchainsResponse } from "./api";
+
+/**
+ * The JWT is a JSON Web Token that is used to authenticate the user.
+ */
+export type JWT = {
+  accessToken: string;
+  permissions: {
+    [trustchainId: string]: {
+      [path: string]: string[];
+    };
+  };
+};
+
+/**
+ * A function which allow all interactions with the hardware device.
+ */
+export type WithDevice = (
+  deviceId: string,
+  options?: { openTimeoutMs?: number },
+) => <T>(fn: (transport: Transport) => Observable<T>) => Observable<T>;
+
+/**
+ * A Trustchain contains the identifier and the contextual data we need to manage members and encrypt/decrypt data.
+ */
+export type Trustchain = {
+  /**
+   * The immutable id of the trustchain root
+   */
+  rootId: string;
+  /**
+   * The secret used to encrypt/decrypt the wallet sync data
+   */
+  walletSyncEncryptionKey: string;
+  /**
+   * The derivation path on which the current walletSyncEncryptionKey value is stored
+   */
+  applicationPath: string;
+};
+
+/**
+ * The Trustchain member credentials are stored on each client, with the privatekey only known by the current client.
+ */
+export type MemberCredentials = {
+  /**
+   * The public key of the member (in hexadecimal)
+   */
+  pubkey: string;
+  /**
+   * The private key of the member (in hexadecimal)
+   */
+  privatekey: string;
+};
+
+/**
+ * A member of the trustchain
+ */
+export type TrustchainMember = {
+  /**
+   * The id of the member. It corresponds to the MemberCredentials.pubkey
+   */
+  id: string;
+  /**
+   * The name of the member as displayed in the UI
+   */
+  name: string;
+  /**
+   * a technical permissions of the member. it will often just be Permissions.OWNER
+   */
+  permissions: number;
+};
+
+/**
+ * The TrustchainSDKContext is a context that is used to initialize the TrustchainSDK.
+ */
+export type TrustchainSDKContext = {
+  applicationId: number;
+  name: string;
+  apiBaseUrl: string;
+};
+
+/**
+ * provide global callbacks for specific lifecycles.
+ * this allows us to decouple trustchain with the rest of Ledger Live.
+ * For now, we only introduce very specific hooks we need.
+ */
+export type TrustchainLifecycle = {
+  /**
+   * called when a trustchain rotation is occuring
+   * the first function is called when the rotation is starting
+   * the second function is called when the rotation is done.
+   *
+   * in that case, we typically want to delete all other resources depending on it.
+   * we do this with the existing jwt token before refreshing it.
+   */
+  onTrustchainRotation: (
+    trustchainSdk: TrustchainSDK,
+    oldTrustchain: Trustchain,
+    memberCredentials: MemberCredentials,
+  ) => Promise<(newTrustchain: Trustchain) => Promise<void>>;
+};
+
+export enum TrustchainResultType {
+  created = "created",
+  updated = "updated",
+  restored = "restored",
+}
+
+/**
+ * the trustchain with a result type indicating what happened during getOrCreateTrustchain
+ */
+export type TrustchainResult =
+  | {
+      // the trustchain didn't exist and was created
+      type: TrustchainResultType.created;
+      trustchain: Trustchain;
+    }
+  | {
+      // the trustchain already existed and was updated (typically the current member was added)
+      type: TrustchainResultType.updated;
+      trustchain: Trustchain;
+    }
+  | {
+      // the trustchain existed and was just retrieved (no need to update it)
+      type: TrustchainResultType.restored;
+      trustchain: Trustchain;
+    };
+
+/**
+ * cache (default): the SDK will use the cached JWT if it's still valid, otherwise it will refresh it.
+ * refresh: the SDK will always refresh the JWT if possible.
+ * no-cache: the SDK will always request a new JWT.
+ */
+export type AuthCachePolicy = "no-cache" | "refresh" | "cache";
+
+/**
+ * The main interface for the UI to interact with the trustchain protocol.
+ *
+ * @example
+ *
+ * import { sdk } from "@ledgerhq/ledger-key-ring-protocol";
+ *
+ * sdk.getOrCreateTrustchain(deviceId, memberCredentials).then(trustchain => console.log(trustchain));
+ */
+export interface TrustchainSDK {
+  /**
+   * Generate the live credentials that represents a Live instance, member of the trustchain.
+   * This method is expected to be used the first time Ledger Live is opened (if Live never generated them before) and then persisted over the future user sessions of Ledger Live in order for the member to be able to authenticate and manage the trustchain.
+   */
+  initMemberCredentials(): Promise<MemberCredentials>;
+
+  /**
+   * Access a JWT from the TrustchainSDK. manage the reauthentication if needed.
+   * A trustchain must have been created and the Live instance must have been added as a member.
+   * The returned token will typically be used for regular operations like wallet sync.
+   */
+  withAuth<T>(
+    trustchain: Trustchain,
+    memberCredentials: MemberCredentials,
+    f: (jwt: JWT) => Promise<T>,
+    policy?: AuthCachePolicy,
+    ignorePermissionsChecks?: boolean,
+  ): Promise<T>;
+
+  /**
+   * This method will either create the required trustchains (root and application) or restore them.
+   * The returned trustchain will be initialized on the root level and also will have the branch derivation corresponding to the contextual applicationId.
+   * It will also have the wallet sync encryption key initialized.
+   * The latest jwt is also returned because it was potentially updated during the process.
+   */
+  getOrCreateTrustchain(
+    deviceId: string,
+    memberCredentials: MemberCredentials,
+    callbacks?: GetOrCreateTrustchainCallbacks,
+    topic?: Uint8Array,
+    currentTrustchain?: Trustchain,
+  ): Promise<TrustchainResult>;
+
+  /**
+   * Restore the current trustchain encryption key, typically due to a key rotation.
+   */
+  restoreTrustchain(
+    trustchain: Trustchain,
+    memberCredentials: MemberCredentials,
+  ): Promise<Trustchain>;
+
+  /**
+   * list the current members of the application trustchain
+   */
+  getMembers(
+    trustchain: Trustchain,
+    memberCredentials: MemberCredentials,
+  ): Promise<TrustchainMember[]>;
+
+  /**
+   * remove a member from the application trustchain
+   */
+  removeMember(
+    deviceId: string,
+    trustchain: Trustchain,
+    memberCredentials: MemberCredentials,
+    member: TrustchainMember,
+    callbacks?: TrustchainDeviceCallbacks,
+  ): Promise<Trustchain>;
+
+  /**
+   * add a member to the application trustchain
+   */
+  addMember(
+    trustchain: Trustchain,
+    memberCredentials: MemberCredentials,
+    member: TrustchainMember,
+  ): Promise<void>;
+
+  /**
+   * destroy the trustchain
+   */
+  destroyTrustchain(trustchain: Trustchain, memberCredentials: MemberCredentials): Promise<void>;
+
+  /**
+   * encrypt data with the trustchain encryption key
+   */
+  encryptUserData(trustchain: Trustchain, obj: object): Promise<Uint8Array>;
+
+  /**
+   * decrypt data with the trustchain encryption key
+   */
+  decryptUserData(trustchain: Trustchain, data: Uint8Array): Promise<Uint8Array>;
+
+  invalidateJwt(): void;
+}
+
+export interface TrustchainDeviceCallbacks {
+  onStartRequestUserInteraction?: () => void;
+  onEndRequestUserInteraction?: () => void;
+}
+
+export interface GetOrCreateTrustchainCallbacks extends TrustchainDeviceCallbacks {
+  onInitialResponse?: (trustchains: TrustchainsResponse) => void;
+}

package/tests/scenarios/_template.ts

@@ -0,0 +1,18 @@
+import { ScenarioOptions } from "../test-helpers/types";
+
+export async function scenario(deviceId: string, { sdkForName }: ScenarioOptions) {
+  /**
+   * Edit this code to the test you want.
+   * This script will be used both as a end-to-end tests and unit tests.
+   * The end-to-end tests are used to generate mock for the same unit tests.
+   */
+  const name1 = "cli-member1";
+  const sdk1 = sdkForName(name1);
+  const memberCredentials = await sdk1.initMemberCredentials();
+  const { trustchain } = await sdk1.getOrCreateTrustchain(deviceId, memberCredentials);
+
+  await sdk1.destroyTrustchain(trustchain, memberCredentials);
+}
+
+// this can overrides the default config used by the recorder
+export const recorderConfig = {};

package/tests/scenarios/addSameMemberMultipleTimes.ts

@@ -0,0 +1,20 @@
+import { ScenarioOptions } from "../test-helpers/types";
+
+export async function scenario(deviceId: string, { sdkForName }: ScenarioOptions) {
+  const name1 = "Member 1";
+  const sdk = sdkForName(name1);
+  const member1creds = await sdk.initMemberCredentials();
+  const { trustchain } = await sdk.getOrCreateTrustchain(deviceId, member1creds);
+
+  const name2 = "Member 2";
+  const member2creds = await sdk.initMemberCredentials();
+  const member2 = { name: name2, id: member2creds.pubkey, permissions: 0xffffffff };
+
+  await sdk.addMember(trustchain, member1creds, member2);
+  await sdk.addMember(trustchain, member1creds, member2);
+
+  const members = await sdk.getMembers(trustchain, member1creds);
+  await sdk.destroyTrustchain(trustchain, member1creds);
+
+  expect(members.length).toBe(2);
+}

package/tests/scenarios/create2trustchainInARow.ts

@@ -0,0 +1,14 @@
+import { ScenarioOptions } from "../test-helpers/types";
+
+export async function scenario(deviceId: string, { sdkForName }: ScenarioOptions) {
+  const sdk = sdkForName("Foo");
+  const creds = await sdk.initMemberCredentials();
+
+  const t1 = await sdk.getOrCreateTrustchain(deviceId, creds);
+  await sdk.destroyTrustchain(t1.trustchain, creds);
+  expect(t1.type).toBe("created");
+
+  const t2 = await sdk.getOrCreateTrustchain(deviceId, creds);
+  await sdk.destroyTrustchain(t2.trustchain, creds);
+  expect(t2.type).toBe("created");
+}

package/tests/scenarios/getOrCreateTransactionCases.ts

@@ -0,0 +1,74 @@
+import { ScenarioOptions } from "../test-helpers/types";
+
+export async function scenario(deviceId: string, { sdkForName }: ScenarioOptions) {
+  const name1 = "Member 1";
+  const sdk1 = sdkForName(name1);
+  const member1creds = await sdk1.initMemberCredentials();
+
+  let interactionCounter = 0;
+  let totalInteractionCounter = 0;
+  const callbacks = {
+    onStartRequestUserInteraction: () => {
+      totalInteractionCounter++;
+      interactionCounter++;
+    },
+    onEndRequestUserInteraction: () => {
+      interactionCounter--;
+    },
+  };
+
+  // verify that getOrCreateTrustchain is idempotent
+  const { trustchain: t1, type: type1 } = await sdk1.getOrCreateTrustchain(
+    deviceId,
+    member1creds,
+    callbacks,
+  );
+  expect(type1).toBe("created");
+  expect(totalInteractionCounter).toBe(2); // there are two interaction: one for device auth, one for trustchain addition
+  const { trustchain: t2, type: type2 } = await sdk1.getOrCreateTrustchain(
+    deviceId,
+    member1creds,
+    callbacks,
+  );
+  expect(type2).toBe("restored");
+  expect(totalInteractionCounter).toBe(3); // one more device auth interaction happened
+  expect(t1).toEqual(t2);
+
+  // verify that a second member can join the trustchain and get the same trustchain
+  const name2 = "Member 2";
+  const sdk2 = sdkForName(name2);
+  const member2creds = await sdk2.initMemberCredentials();
+  const { trustchain: t3, type: type3 } = await sdk2.getOrCreateTrustchain(
+    deviceId,
+    member2creds,
+    callbacks,
+  );
+  expect(type3).toBe("updated");
+  expect(t1).toEqual(t3);
+
+  // check there are indeed our two members in the trustchain
+  const members = await sdk1.getMembers(t1, member1creds);
+  expect(members).toEqual([
+    {
+      id: member1creds.pubkey,
+      name: name1,
+      permissions: 0xffffffff,
+    },
+    {
+      id: member2creds.pubkey,
+      name: name2,
+      permissions: 0xffffffff,
+    },
+  ]);
+
+  // destroy
+  await sdk1.destroyTrustchain(t1, member1creds);
+
+  expect({
+    interactionCounter,
+    totalInteractionCounter,
+  }).toEqual({
+    interactionCounter: 0, // total of interaction+- is back at 0
+    totalInteractionCounter: 5,
+  });
+}

package/tests/scenarios/member3implicitlyAdded.ts

@@ -0,0 +1,51 @@
+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 name3 = "Member 3";
+  const sdk3 = sdkForName(name3);
+  const member3creds = await sdk3.initMemberCredentials();
+
+  // auth with the device and init the first trustchain
+  const { trustchain } = await sdk1.getOrCreateTrustchain(deviceId, member1creds);
+
+  // member 1 adds member 2
+  const member2 = { name: name2, id: member2creds.pubkey, permissions: 0xffffffff };
+  await sdk1.addMember(trustchain, member1creds, member2);
+
+  // member 3 do a getOrCreateTrustchain that should add itself implicitly
+  const { trustchain: trustchain3 } = await sdk3.getOrCreateTrustchain(deviceId, member3creds);
+
+  // list members
+  const members = await sdk3.getMembers(trustchain3, member3creds);
+  expect(members).toEqual([
+    {
+      id: member1creds.pubkey,
+      name: name1,
+      permissions: 0xffffffff,
+    },
+    {
+      id: member2creds.pubkey,
+      name: name2,
+      permissions: 0xffffffff,
+    },
+    {
+      id: member3creds.pubkey,
+      name: name3,
+      permissions: 0xffffffff,
+    },
+  ]);
+
+  await sdk2.destroyTrustchain(trustchain, member2creds);
+}

package/tests/scenarios/membersManySelfAdd.ts

@@ -0,0 +1,18 @@
+import { ScenarioOptions } from "../test-helpers/types";
+
+export async function scenario(deviceId: string, { sdkForName }: ScenarioOptions) {
+  let trustchainId;
+  const n = 10;
+  for (let i = 1; i < n; i++) {
+    const name = "Member " + i;
+    const sdk = sdkForName(name);
+    const creds = await sdk.initMemberCredentials();
+    const { trustchain } = await sdk.getOrCreateTrustchain(deviceId, creds);
+    if (!trustchainId) trustchainId = trustchain.rootId;
+    expect(trustchain.rootId).toBe(trustchainId);
+    if (i === n - 1) {
+      // cleanup
+      await sdk.destroyTrustchain(trustchain, creds);
+    }
+  }
+}

package/tests/scenarios/randomMemberTryToDestroy.ts

@@ -0,0 +1,23 @@
+import { TrustchainEjected } from "../../src/errors";
+import { 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();
+
+  // second member initializes itself
+  const name2 = "Member 2";
+  const sdk2 = sdkForName(name2);
+  const member2creds = await sdk2.initMemberCredentials();
+
+  // auth with the device and init the first trustchain
+  const { trustchain } = await sdk1.getOrCreateTrustchain(deviceId, member1creds);
+
+  // now member2 will get an ejected error when trying to destroy the trustchain
+  await expect(sdk2.destroyTrustchain(trustchain, member2creds)).rejects.toThrow(TrustchainEjected);
+
+  // member1 can destroy the trustchain
+  await sdk1.destroyTrustchain(trustchain, member1creds);
+}

package/tests/scenarios/removeMemberWithTheWrongSeed.ts

@@ -0,0 +1,28 @@
+import { ScenarioOptions } from "../test-helpers/types";
+import { TrustchainNotAllowed } from "../../src/errors";
+
+export async function scenario(
+  deviceId: string,
+  { sdkForName, switchDeviceSeed }: ScenarioOptions,
+) {
+  const name1 = "Member 1";
+  const sdk1 = sdkForName(name1);
+  const member1creds = await sdk1.initMemberCredentials();
+  const member1 = { name: name1, id: member1creds.pubkey, permissions: 0xffffffff };
+
+  const name2 = "Member 2";
+  const sdk2 = sdkForName(name2);
+  const member2creds = await sdk2.initMemberCredentials();
+  const member2 = { name: name2, id: member2creds.pubkey, permissions: 0xffffffff };
+
+  const { trustchain } = await sdk1.getOrCreateTrustchain(deviceId, member1creds);
+  await sdk1.addMember(trustchain, member1creds, member2);
+
+  const device = await switchDeviceSeed();
+
+  await expect(sdk1.removeMember(device.id, trustchain, member2creds, member1)).rejects.toThrow(
+    TrustchainNotAllowed,
+  );
+
+  await sdk2.destroyTrustchain(trustchain, member2creds);
+}

package/tests/scenarios/removedMemberEjectedOnDeletedTrustchain.ts

@@ -0,0 +1,31 @@
+import { 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();
+  // second member initializes itself
+  const name2 = "Member 2";
+  const sdk2 = sdkForName(name2);
+  const member2creds = await sdk2.initMemberCredentials();
+  const member2 = { name: name2, id: member2creds.pubkey, permissions: 0xffffffff };
+
+  // auth with the device and init the first trustchain
+  const { trustchain } = await sdk1.getOrCreateTrustchain(deviceId, member1creds);
+
+  // member 1 adds member 2 (= qr code flow)
+  await sdk1.addMember(trustchain, member1creds, member2);
+
+  // member2 can get the members
+  await sdk2.getMembers(trustchain, member2creds);
+
+  // member1 removes trustchain
+  await sdk1.destroyTrustchain(trustchain, member1creds);
+
+  // force a refresh to happen (which normally happen after some time)
+  await sdk2.withAuth(trustchain, member2creds, jwt => Promise.resolve(jwt), "refresh", true);
+
+  // member2 is no longer a member so is not authorized to get the members
+  await expect(sdk2.getMembers(trustchain, member2creds)).rejects.toThrow();
+}

package/tests/scenarios/removedMemberEjectedOnGetMembers.ts

@@ -0,0 +1,29 @@
+import { TrustchainEjected } from "../../src/errors";
+import { 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();
+  // second member initializes itself
+  const name2 = "Member 2";
+  const sdk2 = sdkForName(name2);
+  const member2creds = await sdk2.initMemberCredentials();
+  const member2 = { name: name2, id: member2creds.pubkey, permissions: 0xffffffff };
+
+  // auth with the device and init the first trustchain
+  const { trustchain } = await sdk1.getOrCreateTrustchain(deviceId, member1creds);
+
+  // member 1 adds member 2 (= qr code flow)
+  await sdk1.addMember(trustchain, member1creds, member2);
+
+  // member1 removes member2
+  const newTrustchain = await sdk1.removeMember(deviceId, trustchain, member1creds, member2);
+
+  // member2 is no longer a member so is not authorized to get the members
+  await expect(sdk2.getMembers(trustchain, member2creds)).rejects.toThrow(TrustchainEjected);
+
+  // member3 destroy the trustchain
+  await sdk1.destroyTrustchain(newTrustchain, member1creds);
+}

package/tests/scenarios/removedMemberEjectedOnRestore.ts

@@ -0,0 +1,31 @@
+import { TrustchainEjected } from "../../src/errors";
+import { 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();
+
+  // 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();
+
+  // member 1 adds member 2 (= qr code flow)
+  const member2 = { name: name2, id: member2creds.pubkey, permissions: 0xffffffff };
+  await sdk1.addMember(trustchain, member1creds, member2);
+
+  // member1 removes member2
+  const newTrustchain = await sdk1.removeMember(deviceId, trustchain, member1creds, member2);
+
+  // now member2 will get an ejected error when trying to restore the trustchain
+  // NB: restoreTrustchain is typically what we would call when member2 see that the encryptionKey no longer work after the rotation
+  await expect(sdk2.restoreTrustchain(trustchain, member2creds)).rejects.toThrow(TrustchainEjected);
+
+  // member3 destroy the trustchain
+  await sdk1.destroyTrustchain(newTrustchain, member1creds);
+}

package/tests/scenarios/removingAMemberCreatesAnInteraction.ts

@@ -0,0 +1,42 @@
+import { ScenarioOptions } from "../test-helpers/types";
+
+export async function scenario(deviceId: string, { sdkForName }: ScenarioOptions) {
+  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 };
+
+  let interactionCounter = 0;
+  let totalInteractionCounter = 0;
+  const callbacks = {
+    onStartRequestUserInteraction: () => {
+      totalInteractionCounter++;
+      interactionCounter++;
+    },
+    onEndRequestUserInteraction: () => {
+      interactionCounter--;
+    },
+  };
+
+  const { trustchain } = await sdk1.getOrCreateTrustchain(deviceId, member1creds, callbacks);
+  expect(totalInteractionCounter).toBe(2); // there are two interaction: one for device auth, one for trustchain addition
+
+  await sdk1.addMember(trustchain, member1creds, member2);
+
+  const newTrustchain = await sdk1.removeMember(
+    deviceId,
+    trustchain,
+    member1creds,
+    member2,
+    callbacks,
+  );
+  expect(totalInteractionCounter).toBe(5); // there are 2 interactions for trustchain addition
+
+  // destroy the trustchain
+  await sdk1.destroyTrustchain(newTrustchain, member1creds);
+  expect(interactionCounter).toBe(0); // the start/stop is coherent
+}

package/tests/scenarios/removingYourselfIsForbidden.ts

@@ -0,0 +1,11 @@
+import { ScenarioOptions } from "../test-helpers/types";
+
+export async function scenario(deviceId: string, { sdkForName }: ScenarioOptions) {
+  const name1 = "Member 1";
+  const sdk1 = sdkForName(name1);
+  const member1creds = await sdk1.initMemberCredentials();
+  const { trustchain } = await sdk1.getOrCreateTrustchain(deviceId, member1creds);
+  const members = await sdk1.getMembers(trustchain, member1creds);
+  await expect(sdk1.removeMember(deviceId, trustchain, member1creds, members[0])).rejects.toThrow();
+  await sdk1.destroyTrustchain(trustchain, member1creds);
+}