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

package/src/api.ts

@@ -0,0 +1,202 @@
+import network from "@ledgerhq/live-network";
+import { JWT } from "./types";
+
+export type StatusAPIResponse = {
+  name: string;
+  version: string;
+};
+
+export type APIJWT = {
+  access_token: string;
+  permissions: {
+    [trustchainId: string]: {
+      [path: string]: string[];
+    };
+  };
+};
+
+export type Challenge = {
+  version: number;
+  challenge: {
+    data: string;
+    expiry: string;
+  };
+  host: string;
+  rp: {
+    credential: {
+      version: number;
+      curveId: number;
+      signAlgorithm: number;
+      publicKey: string;
+    };
+    signature: string;
+  }[];
+  protocolVersion: {
+    major: number;
+    minor: number;
+    patch: number;
+  };
+};
+
+export type ChallengeSignature = {
+  credential: {
+    version: number;
+    curveId: number;
+    signAlgorithm: number;
+    publicKey: string;
+  };
+  signature: string;
+  attestation: string;
+};
+
+export type TrustchainsResponse = {
+  [trustchainId: string]: {
+    [path: string]: string[]; // list of permissions
+  };
+};
+
+export type TrustchainResponse = {
+  [key: string]: string;
+};
+
+export type PutCommandsRequest = {
+  path: string;
+  blocks: string[];
+};
+
+const getApi = (apiBaseURL: string) => {
+  async function getAuthenticationChallenge(): Promise<{ json: Challenge; tlv: string }> {
+    const { data } = await network<{ json: Challenge; tlv: string }>({
+      url: `${apiBaseURL}/v1/challenge`,
+      method: "GET",
+    });
+    return data;
+  }
+
+  async function postChallengeResponse(request: {
+    challenge: Challenge;
+    signature: ChallengeSignature;
+  }): Promise<JWT> {
+    const { data } = await network<APIJWT>({
+      url: `${apiBaseURL}/v1/authenticate`,
+      method: "POST",
+      data: request,
+    });
+    return {
+      accessToken: data.access_token,
+      permissions: data.permissions,
+    };
+  }
+
+  async function refreshAuth(jwt: JWT): Promise<JWT> {
+    const { data } = await network<APIJWT>({
+      url: `${apiBaseURL}/v1/refresh`,
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${jwt.accessToken}`,
+      },
+    });
+    return {
+      accessToken: data.access_token,
+      permissions: data.permissions,
+    };
+  }
+
+  async function getTrustchains(jwt: JWT): Promise<TrustchainsResponse> {
+    const { data } = await network<TrustchainsResponse>({
+      url: `${apiBaseURL}/v1/trustchains`,
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${jwt.accessToken}`,
+      },
+    });
+    return data;
+  }
+
+  async function getTrustchain(jwt: JWT, trustchain_id: string): Promise<TrustchainResponse> {
+    const { data } = await network<TrustchainResponse>({
+      url: `${apiBaseURL}/v1/trustchain/${trustchain_id}`,
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${jwt.accessToken}`,
+      },
+    });
+    return data;
+  }
+
+  async function postDerivation(
+    jwt: JWT,
+    trustchain_id: string,
+    commandStream: string,
+  ): Promise<void> {
+    await network<void>({
+      url: `${apiBaseURL}/v1/trustchain/${trustchain_id}/derivation`,
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${jwt.accessToken}`,
+        "Content-Type": "application/json",
+      },
+      data: commandStream,
+    });
+  }
+
+  async function postSeed(jwt: JWT, commandStream: string): Promise<void> {
+    await network<void>({
+      url: `${apiBaseURL}/v1/seed`,
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${jwt.accessToken}`,
+      },
+      data: commandStream,
+    });
+  }
+
+  async function putCommands(
+    jwt: JWT,
+    trustchain_id: string,
+    request: PutCommandsRequest,
+  ): Promise<void> {
+    await network<void>({
+      url: `${apiBaseURL}/v1/trustchain/${trustchain_id}/commands`,
+      method: "PUT",
+      headers: {
+        Authorization: `Bearer ${jwt.accessToken}`,
+      },
+      data: request,
+    });
+  }
+
+  async function deleteTrustchain(jwt: JWT, trustchain_id: string): Promise<void> {
+    await network<void>({
+      url: `${apiBaseURL}/v1/trustchain/${trustchain_id}`,
+      method: "DELETE",
+      headers: {
+        Authorization: `Bearer ${jwt.accessToken}`,
+      },
+    });
+  }
+
+  async function fetchStatus(): Promise<StatusAPIResponse> {
+    const { data } = await network<StatusAPIResponse>({
+      url: `${apiBaseURL}/_info`,
+      method: "GET",
+    });
+    return data;
+  }
+
+  return {
+    getAuthenticationChallenge,
+    postChallengeResponse,
+    refreshAuth,
+    getTrustchains,
+    getTrustchain,
+    postDerivation,
+    postSeed,
+    putCommands,
+    deleteTrustchain,
+    fetchStatus,
+  };
+};
+
+export default getApi;

package/src/auth.ts

@@ -0,0 +1,81 @@
+import { LedgerAPI4xx } from "@ledgerhq/errors";
+import { log } from "@ledgerhq/logs";
+import { AuthCachePolicy, JWT } from "./types";
+import { TrustchainNotAllowed, TrustchainOutdated } from "./errors";
+
+export async function genericWithJWT<T>(
+  job: (jwt: JWT) => Promise<T>,
+  initialJWT: JWT | undefined,
+  auth: () => Promise<JWT>,
+  refreshAuth: (jw: JWT) => Promise<JWT>,
+  policy: AuthCachePolicy = "cache",
+): Promise<T> {
+  function refresh(jwt: JWT) {
+    return refreshAuth(jwt).catch(e => {
+      log("trustchain", "JWT refresh failed, reauthenticating", e);
+      const { hasExpired, isNotPermitted, isTrustchainOutdated } = networkCheckJwtExpiration(e);
+      if (isNotPermitted) {
+        throw new TrustchainNotAllowed();
+      }
+      if (isTrustchainOutdated) {
+        throw new TrustchainOutdated();
+      }
+      if (hasExpired) {
+        return auth();
+      }
+      throw e;
+    });
+  }
+
+  // initial jwt depending on the policy
+  let jwt =
+    policy === "no-cache" || !initialJWT
+      ? await auth()
+      : policy === "refresh"
+        ? await refresh(initialJWT)
+        : initialJWT;
+
+  return job(jwt).catch(async e => {
+    // JWT expiration handling: if the function fails, we will recover a valid jwt accordingly to spec. https://ledgerhq.atlassian.net/wiki/spaces/BE/pages/4207083687/TCH+Usage+documentation#JWT-expiration-handling
+    const { hasExpired, canBeRefreshed, isNotPermitted, isTrustchainOutdated } =
+      networkCheckJwtExpiration(e);
+    if (isNotPermitted) {
+      throw new TrustchainNotAllowed();
+    }
+    if (isTrustchainOutdated) {
+      throw new TrustchainOutdated();
+    }
+    if (hasExpired) {
+      log("trustchain", "JWT expired -> " + (canBeRefreshed ? "refreshing" : "reauthenticating"));
+      jwt = await (jwt && canBeRefreshed ? refresh(jwt) : auth());
+      return job(jwt);
+    }
+    throw e;
+  });
+}
+
+type JwtExpirationCheck = {
+  hasExpired: boolean;
+  canBeRefreshed: boolean;
+  isNotPermitted: boolean;
+  isTrustchainOutdated: boolean;
+};
+
+function networkCheckJwtExpiration(error: unknown): JwtExpirationCheck {
+  let hasExpired = false;
+  let canBeRefreshed = false;
+  let isNotPermitted = false;
+  let isTrustchainOutdated = false;
+  // this assume live-network is used and we adapt to its error's format
+  if (error instanceof LedgerAPI4xx) {
+    if (error.message.includes("JWT is expired")) {
+      hasExpired = true;
+      canBeRefreshed = error.message.includes("/refresh");
+    } else if (error.message.includes("JWT contains no permission")) {
+      isNotPermitted = true;
+    } else if (error.message.includes("path does not match")) {
+      isTrustchainOutdated = true;
+    }
+  }
+  return { hasExpired, canBeRefreshed, isNotPermitted, isTrustchainOutdated };
+}

package/src/errors.ts

@@ -0,0 +1,18 @@
+import { createCustomErrorClass } from "@ledgerhq/errors";
+
+export const ScannedOldImportQrCode = createCustomErrorClass("ScannedOldImportQrCode");
+export const ScannedNewImportQrCode = createCustomErrorClass("ScannedNewImportQrCode");
+export const ScannedInvalidQrCode = createCustomErrorClass("ScannedInvalidQrCode");
+export const InvalidDigitsError = createCustomErrorClass("InvalidDigitsError");
+export const InvalidEncryptionKeyError = createCustomErrorClass("InvalidEncryptionKeyError");
+export const TrustchainEjected = createCustomErrorClass("TrustchainEjected");
+export const TrustchainNotAllowed = createCustomErrorClass("TrustchainNotAllowed");
+export const TrustchainOutdated = createCustomErrorClass("TrustchainOutdated");
+export const TrustchainNotFound = createCustomErrorClass("TrustchainNotFound");
+export const NoTrustchainInitialized = createCustomErrorClass("NoTrustchainInitialized");
+export const TrustchainAlreadyInitialized = createCustomErrorClass("TrustchainAlreadyInitialized");
+export const TrustchainAlreadyInitializedWithOtherSeed = createCustomErrorClass(
+  "TrustchainAlreadyInitializedWithOtherSeed",
+);
+
+export const QRCodeWSClosed = createCustomErrorClass<{ time: number }>("QRCodeWSClosed");

package/src/index.ts

@@ -0,0 +1,20 @@
+import { HWDeviceProvider } from "./HWDeviceProvider";
+import { SDK } from "./sdk";
+import { MockSDK } from "./mockSdk";
+import { TrustchainSDKContext, TrustchainSDK, TrustchainLifecycle, WithDevice } from "./types";
+
+/**
+ * Get an implementation of a TrustchainSDK
+ */
+export const getSdk = (
+  isMockEnv: boolean,
+  context: TrustchainSDKContext,
+  withDevice: WithDevice,
+  lifecycle?: TrustchainLifecycle,
+): TrustchainSDK => {
+  if (isMockEnv) {
+    return new MockSDK(context, lifecycle);
+  }
+
+  return new SDK(context, new HWDeviceProvider(context.apiBaseUrl, withDevice), lifecycle);
+};

package/src/mockSdk.ts

@@ -0,0 +1,253 @@
+import {
+  JWT,
+  MemberCredentials,
+  Trustchain,
+  TrustchainDeviceCallbacks,
+  TrustchainLifecycle,
+  TrustchainMember,
+  TrustchainResult,
+  TrustchainResultType,
+  TrustchainSDK,
+  TrustchainSDKContext,
+} from "./types";
+import { Permissions } from "@ledgerhq/hw-ledger-key-ring-protocol";
+import { TrustchainEjected } from "./errors";
+import getApi from "./api";
+
+const mockedLiveCredentialsPrivateKey = "mock-private-key";
+
+function assertTrustchain(trustchain: Trustchain) {
+  if (!trustchain.rootId.startsWith("mock-root-id")) {
+    throw new Error("in mock context, trustchain must be the mocked trustchain");
+  }
+}
+
+function assertLiveCredentials(memberCredentials: MemberCredentials) {
+  if (!memberCredentials.privatekey.startsWith(mockedLiveCredentialsPrivateKey)) {
+    throw new Error("in mock context, memberCredentials must be the mocked memberCredentials");
+  }
+}
+
+function assertAllowedPermissions(trustchainId: string, memberId: string) {
+  const members = trustchainMembers.get(trustchainId) || [];
+  const member = members.find(m => m.id === memberId);
+  if (!member) {
+    throw new TrustchainEjected();
+  }
+}
+
+const mockedLiveJWT = {
+  accessToken: "mock-live-jwt",
+  permissions: {},
+};
+
+// global states in memory
+const trustchains = new Map<string, Trustchain>();
+const trustchainMembers = new Map<string, TrustchainMember[]>();
+
+/**
+ * to mock the encryption/decryption, we just xor the data with 0xff
+ */
+const applyXor = (a: Uint8Array) => {
+  const b = new Uint8Array(a.length);
+  for (let i = 0; i < a.length; i++) {
+    b[i] = a[i] ^ 0xff;
+  }
+  return b;
+};
+
+export class MockSDK implements TrustchainSDK {
+  private context: TrustchainSDKContext;
+  private lifecyle?: TrustchainLifecycle;
+  private api: ReturnType<typeof getApi>;
+
+  constructor(context: TrustchainSDKContext, lifecyle?: TrustchainLifecycle) {
+    this.context = context;
+    this.lifecyle = lifecyle;
+    this.api = getApi(context.apiBaseUrl);
+  }
+
+  private deviceJwtAcquired = false;
+
+  private _id = 1;
+  initMemberCredentials(): Promise<MemberCredentials> {
+    const id = this._id++;
+    return Promise.resolve({
+      privatekey: "mock-private-key-" + this.context.name + "-" + id,
+      pubkey: "mock-pub-key-" + this.context.name + "-" + id,
+    });
+  }
+
+  withAuth<T>(
+    trustchain: Trustchain,
+    memberCredentials: MemberCredentials,
+    job: (jwt: JWT) => Promise<T>,
+  ): Promise<T> {
+    assertTrustchain(trustchain);
+    assertLiveCredentials(memberCredentials);
+    return job(mockedLiveJWT);
+  }
+
+  async getOrCreateTrustchain(
+    deviceId: string,
+    memberCredentials: MemberCredentials,
+    callbacks?: TrustchainDeviceCallbacks,
+  ): Promise<TrustchainResult> {
+    this.invalidateJwt();
+    assertLiveCredentials(memberCredentials);
+    let type = trustchains.has("mock-root-id")
+      ? TrustchainResultType.restored
+      : TrustchainResultType.created;
+
+    const trustchain: Trustchain = trustchains.get("mock-root-id") || {
+      rootId: "mock-root-id",
+      walletSyncEncryptionKey: "mock-wallet-sync-encryption-key",
+      applicationPath: "m/0'/16'/0'",
+    };
+    trustchains.set(trustchain.rootId, trustchain);
+
+    if (!this.deviceJwtAcquired) {
+      callbacks?.onStartRequestUserInteraction?.();
+      this.deviceJwtAcquired = true; // simulate device auth interaction
+      callbacks?.onEndRequestUserInteraction?.();
+    }
+
+    const currentMembers = trustchainMembers.get(trustchain.rootId) || [];
+    // add itself if not yet here
+    if (!currentMembers.some(m => m.id === memberCredentials.pubkey)) {
+      if (type === TrustchainResultType.restored) type = TrustchainResultType.updated;
+      callbacks?.onStartRequestUserInteraction?.();
+      // simulate device add interaction
+      callbacks?.onEndRequestUserInteraction?.();
+      currentMembers.push({
+        id: memberCredentials.pubkey,
+        name: this.context.name,
+        permissions: Permissions.OWNER,
+      });
+      trustchainMembers.set(trustchain.rootId, currentMembers);
+    }
+    return Promise.resolve({ type, trustchain });
+  }
+
+  async refreshAuth(jwt: JWT): Promise<JWT> {
+    return jwt;
+  }
+
+  async restoreTrustchain(
+    trustchain: Trustchain,
+    memberCredentials: MemberCredentials,
+  ): Promise<Trustchain> {
+    assertTrustchain(trustchain);
+    assertLiveCredentials(memberCredentials);
+    assertAllowedPermissions(trustchain.rootId, memberCredentials.pubkey);
+    const latest = trustchains.get(trustchain.rootId);
+    if (!latest) {
+      throw new Error("trustchain not found");
+    }
+    return Promise.resolve(latest);
+  }
+
+  async getMembers(
+    trustchain: Trustchain,
+    memberCredentials: MemberCredentials,
+  ): Promise<TrustchainMember[]> {
+    assertTrustchain(trustchain);
+    assertLiveCredentials(memberCredentials);
+    assertAllowedPermissions(trustchain.rootId, memberCredentials.pubkey);
+    const currentMembers = trustchainMembers.get(trustchain.rootId) || [];
+    return Promise.resolve([...currentMembers]);
+  }
+
+  async removeMember(
+    deviceId: string,
+    trustchain: Trustchain,
+    memberCredentials: MemberCredentials,
+    member: TrustchainMember,
+    callbacks?: TrustchainDeviceCallbacks,
+  ): Promise<Trustchain> {
+    this.invalidateJwt();
+    assertTrustchain(trustchain);
+    assertLiveCredentials(memberCredentials);
+    assertAllowedPermissions(trustchain.rootId, memberCredentials.pubkey);
+    if (member.id === memberCredentials.pubkey) {
+      throw new Error("cannot remove self");
+    }
+    const afterRotation = await this.lifecyle?.onTrustchainRotation(
+      this,
+      trustchain,
+      memberCredentials,
+    );
+
+    if (!this.deviceJwtAcquired) {
+      callbacks?.onStartRequestUserInteraction?.();
+      this.deviceJwtAcquired = true; // simulate device auth interaction
+      callbacks?.onEndRequestUserInteraction?.();
+    }
+
+    callbacks?.onStartRequestUserInteraction?.();
+    // simulate device interaction
+    callbacks?.onEndRequestUserInteraction?.();
+
+    callbacks?.onStartRequestUserInteraction?.();
+    // simulate device interaction
+    callbacks?.onEndRequestUserInteraction?.();
+
+    const currentMembers = (trustchainMembers.get(trustchain.rootId) || []).filter(
+      m => m.id !== member.id,
+    );
+    trustchainMembers.set(trustchain.rootId, currentMembers);
+    // we extract the index part to increment it and recreate a path
+    const index = 1 + parseInt(trustchain.applicationPath.split("/")[3].split("'")[0]);
+    const newTrustchain = {
+      rootId: trustchain.rootId,
+      walletSyncEncryptionKey: "mock-wallet-sync-encryption-key-" + index,
+      applicationPath: "m/0'/16'/" + index + "'",
+    };
+    trustchains.set(newTrustchain.rootId, newTrustchain);
+
+    if (afterRotation) await afterRotation(newTrustchain);
+
+    return Promise.resolve(newTrustchain);
+  }
+
+  async destroyTrustchain(
+    trustchain: Trustchain,
+    memberCredentials: MemberCredentials,
+  ): Promise<void> {
+    assertTrustchain(trustchain);
+    assertLiveCredentials(memberCredentials);
+    trustchains.delete(trustchain.rootId);
+    trustchainMembers.delete(trustchain.rootId);
+    return;
+  }
+
+  addMember(
+    trustchain: Trustchain,
+    memberCredentials: MemberCredentials,
+    member: TrustchainMember,
+  ): Promise<void> {
+    assertTrustchain(trustchain);
+    assertLiveCredentials(memberCredentials);
+    const currentMembers = trustchainMembers.get(trustchain.rootId) || [];
+    if (currentMembers.find(m => m.id === member.id)) {
+      return Promise.resolve();
+    }
+    currentMembers.push(member);
+    trustchainMembers.set(trustchain.rootId, currentMembers);
+    return Promise.resolve();
+  }
+
+  encryptUserData(trustchain: Trustchain, input: Uint8Array): Promise<Uint8Array> {
+    assertTrustchain(trustchain);
+    return Promise.resolve(applyXor(input));
+  }
+
+  decryptUserData(trustchain: Trustchain, data: Uint8Array): Promise<Uint8Array> {
+    assertTrustchain(trustchain);
+    return Promise.resolve(applyXor(data));
+  }
+
+  invalidateJwt(): void {
+    this.deviceJwtAcquired = false;
+  }
+}

package/src/qrcode/cipher.test.ts

@@ -0,0 +1,30 @@
+import { crypto } from "@ledgerhq/hw-ledger-key-ring-protocol";
+import { makeCipher } from "./cipher";
+import { InvalidEncryptionKeyError } from "../errors";
+
+describe("makeCipher", () => {
+  it("should encrypt and decrypt correctly", async () => {
+    const ephemeralKey = await crypto.randomKeypair();
+    const candidate = await crypto.randomKeypair();
+    const sessionEncryptionKey = await crypto.ecdh(ephemeralKey, candidate.publicKey);
+    const cipher = makeCipher(sessionEncryptionKey);
+    const plaintext = { message: "Hello, World!" };
+    const encrypted = await cipher.encrypt(plaintext);
+    expect(typeof encrypted).toBe("string");
+    const decrypted = await cipher.decrypt(encrypted);
+    expect(decrypted).toEqual(plaintext);
+  });
+
+  it("should throw InvalidEncryptionKeyError if key changes", async () => {
+    const ephemeralKey = await crypto.randomKeypair();
+    const candidate = await crypto.randomKeypair();
+    const sessionEncryptionKey = await crypto.ecdh(ephemeralKey, candidate.publicKey);
+    const cipher = makeCipher(sessionEncryptionKey);
+    const plaintext = { message: "Hello, World!" };
+    const encrypted = await cipher.encrypt(plaintext);
+    const ephemeralKey2 = await crypto.randomKeypair();
+    const otherSessionEncryptionKey = await crypto.ecdh(ephemeralKey2, candidate.publicKey);
+    const cipher2 = makeCipher(otherSessionEncryptionKey);
+    expect(cipher2.decrypt(encrypted)).rejects.toThrow(InvalidEncryptionKeyError);
+  });
+});

package/src/qrcode/cipher.ts

@@ -0,0 +1,63 @@
+import Base64 from "base64-js";
+import { crypto } from "@ledgerhq/hw-ledger-key-ring-protocol";
+import { DecryptedPayload, Encrypted, ExtractEncryptedPayloads, Message } from "./types";
+import { InvalidEncryptionKeyError } from "../errors";
+
+export type Cipher = {
+  encrypt: (obj: object) => Promise<string>;
+  decrypt: (data: string) => Promise<object>;
+};
+
+export type MessageCipher = {
+  encryptMessagePayload: <P extends ExtractEncryptedPayloads<Message>>(
+    payload: P,
+  ) => Promise<Encrypted<P>>;
+  decryptMessage: <M extends Message>(message: M) => Promise<DecryptedPayload<M>>;
+};
+
+export function makeCipher(sessionEncryptionKey: Uint8Array): Cipher {
+  async function encrypt(obj: object): Promise<string> {
+    const plaintext = JSON.stringify(obj);
+    const data = new TextEncoder().encode(plaintext);
+    const nonce = await crypto.randomBytes(16);
+    const ciphertext = await crypto.encrypt(sessionEncryptionKey, nonce, data);
+    const blob = new Uint8Array(nonce.length + ciphertext.length);
+    blob.set(nonce);
+    blob.set(ciphertext, nonce.length);
+    return Base64.fromByteArray(blob);
+  }
+
+  async function decrypt(data: string): Promise<object> {
+    const blob = Base64.toByteArray(data);
+    const nonce = blob.slice(0, 16);
+    const ciphertext = blob.slice(16);
+    try {
+      const plaintext = await crypto.decrypt(sessionEncryptionKey, nonce, ciphertext);
+      const text = new TextDecoder().decode(plaintext);
+      return JSON.parse(text);
+    } catch (e) {
+      throw new InvalidEncryptionKeyError("data can't be decrypted");
+    }
+  }
+
+  return { encrypt, decrypt };
+}
+
+export function makeMessageCipher(cipher: Cipher): MessageCipher {
+  async function encryptMessagePayload<P extends ExtractEncryptedPayloads<Message>>(
+    payload: P,
+  ): Promise<Encrypted<P>> {
+    const encrypted = await cipher.encrypt(payload);
+    return { encrypted };
+  }
+
+  async function decryptMessage<M extends Message>(message: M): Promise<DecryptedPayload<M>> {
+    if (message.message === "InitiateHandshake" || message.message === "Failure") {
+      throw new Error(message.message + " is not encrypted");
+    }
+    const decrypted = (await cipher.decrypt(message.payload.encrypted)) as DecryptedPayload<M>;
+    return decrypted;
+  }
+
+  return { encryptMessagePayload, decryptMessage };
+}