@bitgo-beta/key-card 0.0.1-beta.6 → 0.0.1-beta.60

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+## [0.1.1](https://github.com/BitGo/BitGoJS/compare/@bitgo/key-card@0.1.0...@bitgo/key-card@0.1.1) (2023-02-17)
+
+**Note:** Version bump only for package @bitgo/key-card
+
+
+
+
+
+# 0.1.0 (2023-02-16)
+
+
+### Bug Fixes
+
+* **key-card:** fix errors in key-card drawing code ([092bc0a](https://github.com/BitGo/BitGoJS/commit/092bc0a4b851d6cf9d396e8eb5af476b4c52954d))
+* **key-card:** reduce size of QR codes ([c8e08b8](https://github.com/BitGo/BitGoJS/commit/c8e08b8ca007bd45cb0628c5a06a80b81f5a308e))
+* **root:** manually fix up incorrect versions ([3b1d28a](https://github.com/BitGo/BitGoJS/commit/3b1d28a8a4925e6dc1d89bb7482ea3b2f52b7b95))
+
+
+### Features
+
+* **key-card:** add basic code to generate key cards ([83b01fc](https://github.com/BitGo/BitGoJS/commit/83b01fc5c31801e4f8db1166b06f2b8e7de3183f))
+* **key-card:** add code to select qrData ([8b0e814](https://github.com/BitGo/BitGoJS/commit/8b0e814e54d9e33c41e5459d4fc69dac7b7d7737))
+* **key-card:** add function to generate key card faqs ([749798d](https://github.com/BitGo/BitGoJS/commit/749798d184153e8257a7926f62e6c72420c31bc8))
+* **key-card:** add support for qrcodes ([d79b9f7](https://github.com/BitGo/BitGoJS/commit/d79b9f7192dcabe9a7a1d5c261b799b5cbedb6f7))
+* **key-card:** add utils function to split keys ([3547b19](https://github.com/BitGo/BitGoJS/commit/3547b194b49a50da8901b8d76c5f9a96c2f9c994))
+* **key-card:** change contents of Boxes B & C for SMHA wallets ([2c27cd0](https://github.com/BitGo/BitGoJS/commit/2c27cd055bcdeb1a1a444d204298a8adb1d7a1c8))
+* **key-card:** support BitGo Trust holding TSS backup key ([6cb8f94](https://github.com/BitGo/BitGoJS/commit/6cb8f94a4916a211f73c774ee9d94f6fdf6e6650))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitgo-beta/key-card",
-  "version": "0.0.1-beta.6",
+  "version": "0.0.1-beta.60",
   "description": "key card generator for BitGo wallets",
   "main": "./dist/src/index.js",
   "types": "./dist/src/index.d.ts",
@@ -33,9 +33,14 @@
     ]
   },
   "dependencies": {
-    "@bitgo-beta/sdk-api": "1.1.1-beta.131",
-    "@bitgo-beta/sdk-core": "1.1.1-beta.131",
-    "@bitgo-beta/statics": "7.0.1-beta.131"
+    "@bitgo-beta/sdk-api": "1.1.1-beta.185",
+    "@bitgo-beta/sdk-core": "1.1.1-beta.185",
+    "@bitgo-beta/statics": "7.0.1-beta.185",
+    "jspdf": "^2.5.1",
+    "qrcode": "^1.5.1"
   },
-  "gitHead": "d1e39fe74d0554eb596a47d3f3e32b7dc5094113"
+  "devDependencies": {
+    "@types/qrcode": "1.5.0"
+  },
+  "gitHead": "fcd74261f04b23b14532a5031db203b5252bacad"
 }

package/src/drawKeycard.ts

@@ -0,0 +1,240 @@
+import { jsPDF } from 'jspdf';
+import * as QRCode from 'qrcode';
+import { FAQ } from './faq';
+import { QrData } from './generateQrData';
+import { splitKeys } from './utils';
+
+// Max for Binary/Byte Data https://github.com/soldair/node-qrcode#qr-code-capacity
+// the largest theoretically possible value is actually 2953 but the QR codes get so dense that scanning them with a
+// phone (off of a printed page) doesn't work anymore
+// this limitation was chosen by trial and error
+export const QRBinaryMaxLength = 1500;
+
+const font = {
+  header: 24,
+  subheader: 15,
+  body: 12,
+};
+
+const color = {
+  black: '#000000',
+  darkgray: '#4c4c4c',
+  gray: '#9b9b9b',
+  red: '#e21e1e',
+};
+
+const margin = 30;
+
+// Helpers for data formatting / positioning on the paper
+function left(x: number): number {
+  return margin + x;
+}
+function moveDown(y: number, ydelta: number): number {
+  return y + ydelta;
+}
+
+function drawOnePageOfQrCodes(qrImages: HTMLCanvasElement[], doc: jsPDF, y: number, qrSize: number, startIndex): number {
+  doc.setFont('helvetica');
+  let qrIndex: number = startIndex;
+  for (; qrIndex < qrImages.length; qrIndex++) {
+    const image = qrImages[qrIndex];
+    const textBuffer = 15;
+    if (y + qrSize + textBuffer >= doc.internal.pageSize.getHeight()) {
+      return qrIndex;
+    }
+
+    doc.addImage(image, left(0), y, qrSize, qrSize);
+
+    if (qrImages.length === 1) {
+      return qrIndex + 1;
+    }
+
+    y = moveDown(y, qrSize + textBuffer);
+    doc.setFontSize(font.body).setTextColor(color.black);
+    doc.text('Part ' + (qrIndex + 1).toString(), left(0), y);
+    y = moveDown(y, 20);
+  }
+  return qrIndex + 1;
+}
+
+export async function drawKeycard({ activationCode, questions, keyCardImage, qrData, walletLabel }: {
+  activationCode?: string;
+  keyCardImage?: HTMLImageElement;
+  qrData: QrData;
+  questions: FAQ[];
+  walletLabel: string;
+}): Promise<jsPDF> {
+  // document details
+  const width = 8.5 * 72;
+  let y = 0;
+
+  // Create the PDF instance
+  const doc = new jsPDF('portrait', 'pt', 'letter'); // jshint ignore:line
+  doc.setFont('helvetica');
+
+  // PDF Header Area - includes the logo and company name
+  // This is data for the BitGo logo in the top left of the PDF
+  y = moveDown(y, 30);
+
+  if (keyCardImage) {
+    doc.addImage(keyCardImage, left(0), y, 303, 40);
+  }
+
+  // Activation Code
+  if (activationCode) {
+    y = moveDown(y, 8);
+    doc.setFontSize(font.body).setTextColor(color.gray);
+    doc.text('Activation Code', left(460), y);
+  }
+  doc.setFontSize(font.header).setTextColor(color.black);
+  y = moveDown(y, 25);
+  doc.text('KeyCard', left(325), y - 1);
+  if (activationCode) {
+    doc.setFontSize(font.header).setTextColor(color.gray);
+    doc.text(activationCode, left(460), y);
+  }
+
+  // Subheader
+  // titles
+  const date = new Date().toDateString();
+  y = moveDown(y, margin);
+  doc.setFontSize(font.body).setTextColor(color.gray);
+  doc.text('Created on ' + date + ' for wallet named:', left(0), y);
+  // copy
+  y = moveDown(y, 25);
+  doc.setFontSize(font.subheader).setTextColor(color.black);
+  doc.text(walletLabel, left(0), y);
+  // Red Bar
+  y = moveDown(y, 20);
+  doc.setFillColor(255, 230, 230);
+  doc.rect(left(0), y, width - 2 * margin, 32, 'F');
+
+  // warning message
+  y = moveDown(y, 20);
+  doc.setFontSize(font.body).setTextColor(color.red);
+  doc.text('Print this document, or keep it securely offline. See below for FAQ.', left(75), y);
+
+  // Generate the first page's data for the backup PDF
+  y = moveDown(y, 35);
+  const qrSize = 130;
+
+  const qrKeys = ['user', 'passcode', 'backup', 'bitgo'];
+  for (let index = 0; index < qrKeys.length; index++) {
+    const name = qrKeys[index];
+    if (index === 2) {
+      // Add 2nd Page
+      doc.addPage();
+
+      // 2nd page title
+      y = 30;
+    }
+
+    const qr = qrData[name];
+    let topY = y;
+    const textLeft = left(qrSize + 15);
+    let textHeight = 0;
+
+    const qrImages: HTMLCanvasElement[] = [];
+    const keys = splitKeys(qr.data, QRBinaryMaxLength);
+    for (const key of keys) {
+      qrImages.push(await QRCode.toCanvas(key, { errorCorrectionLevel: 'L' }));
+    }
+
+    let nextQrIndex = drawOnePageOfQrCodes(qrImages, doc, y, qrSize, 0);
+
+    doc.setFontSize(font.subheader).setTextColor(color.black);
+    y = moveDown(y, 10);
+    textHeight += 10;
+    doc.text(qr.title, textLeft, y);
+    textHeight += doc.getLineHeight();
+    y = moveDown(y, 15);
+    textHeight += 15;
+    doc.setFontSize(font.body).setTextColor(color.darkgray);
+    doc.text(qr.description, textLeft, y);
+    textHeight += doc.getLineHeight();
+    doc.setFontSize(font.body - 2);
+    if (qr?.data?.length > QRBinaryMaxLength) {
+      y = moveDown(y, 30);
+      textHeight += 30;
+      doc.text('Note: you will need to put all Parts together for the full key', textLeft, y);
+    }
+    y = moveDown(y, 30);
+    textHeight += 30;
+    doc.text('Data:', textLeft, y);
+    textHeight += doc.getLineHeight();
+    y = moveDown(y, 15);
+    textHeight += 15;
+    const width = 72 * 8.5 - textLeft - 30;
+    doc.setFont('courier').setFontSize(9).setTextColor(color.black);
+    const lines = doc.splitTextToSize(qr.data, width);
+    const buffer = 10;
+    for (let line = 0; line < lines.length; line++) {
+      // add new page if data does not fit on one page
+      if (y + buffer >= doc.internal.pageSize.getHeight()) {
+        doc.addPage();
+        textHeight = 0;
+        y = 30;
+        topY = y;
+        nextQrIndex = drawOnePageOfQrCodes(qrImages, doc, y, qrSize, nextQrIndex);
+        doc.setFont('courier').setFontSize(9).setTextColor(color.black);
+      }
+      doc.text(lines[line], textLeft, y);
+      if (line !== lines.length - 1) {
+        y = moveDown(y, buffer);
+        textHeight += buffer;
+      }
+    }
+
+    // Add public key if exists
+    if (qr.publicMasterKey) {
+      const text = 'Key Id: ' + qr.publicMasterKey;
+
+      // Gray bar
+      y = moveDown(y, 20);
+      textHeight += 20;
+      doc.setFillColor(247, 249, 249); // Gray background
+      doc.setDrawColor(0, 0, 0); // Border
+
+      // Leave a bit of space for the side of the rectangle.
+      const splitKeyId = doc.splitTextToSize(text, width - 10);
+
+      // The height of the box must be at least 15 px (for single line case), or
+      // a multiple of 13 for each line.  This allows for proper padding.
+      doc.rect(textLeft, y, width, Math.max(12 * splitKeyId.length, 15), 'FD');
+      textHeight += splitKeyId.length * doc.getLineHeight();
+      doc.text(splitKeyId, textLeft + 5, y + 10);
+    }
+
+    doc.setFont('helvetica');
+    // Move down the size of the QR code minus accumulated height on the right side, plus margin
+    // if we have a key that spans multiple pages, then exclude QR code size
+    const rowHeight = Math.max(qr.data.length > QRBinaryMaxLength ? qrSize + 20 : qrSize, textHeight);
+    const marginBottom = 15;
+    y = moveDown(y, rowHeight - (y - topY) + marginBottom);
+  }
+
+  // Add next Page
+  doc.addPage();
+
+  // next pages title
+  y = 0;
+  y = moveDown(y, 55);
+  doc.setFontSize(font.header).setTextColor(color.black);
+  doc.text('BitGo KeyCard FAQ', left(0), y);
+
+  // Generate the second page's data for the backup PDF
+  y = moveDown(y, 30);
+  questions.forEach(function (q) {
+    doc.setFontSize(font.subheader).setTextColor(color.black);
+    doc.text(q.question, left(0), y);
+    y = moveDown(y, 20);
+    doc.setFontSize(font.body).setTextColor(color.darkgray);
+    q.answer.forEach(function (line) {
+      doc.text(line, left(0), y);
+      y = moveDown(y, font.body + 3);
+    });
+    y = moveDown(y, 22);
+  });
+
+  return doc;
+}

package/src/generateQrData.ts

@@ -6,7 +6,7 @@ import * as assert from 'assert';
 export interface GenerateQrDataParams {
   // The backup keychain as it is returned from the BitGo API upon creation
   backupKeychain: Keychain,
-  // The 3rd party provider of the backup key if neither the user nor BitGo stores it
+  // The name of the 3rd party provider of the backup key if neither the user nor BitGo stores it
   backupKeyProvider?: string;
   // The key id of the backup key, only used for cold keys
   backupMasterKey?: string;
@@ -31,7 +31,6 @@ export interface GenerateQrDataParams {
 interface QrDataEntry {
   data: string;
   description: string;
-  image: string;
   title: string;
   publicMasterKey?: string;
 }
@@ -58,7 +57,6 @@ function generateUserQrData(userKeychain: Keychain, userMasterKey?: string): QrD
   if (userKeychain.encryptedPrv) {
     return {
       title: 'A: User Key',
-      image: '.qrEncryptedUserKey',
       description: 'This is your private key, encrypted with your wallet password.',
       data: userKeychain.encryptedPrv,
     };
@@ -69,7 +67,6 @@ function generateUserQrData(userKeychain: Keychain, userMasterKey?: string): QrD
 
   return {
     title: 'A: Provided User Key',
-    image: '.qrPublicUserKey',
     description: 'This is the public key you provided for your wallet.',
     data: pub,
     publicMasterKey: userMasterKey,
@@ -87,19 +84,28 @@ function generateBackupQrData(coin: Readonly<BaseCoin>, backupKeychain: Keychain
   if (backupKeychain.encryptedPrv) {
     return {
       title,
-      image: '.qrEncryptedBackupKey',
       description: 'This is your backup private key, encrypted with your wallet password.',
       data: backupKeychain.encryptedPrv,
     };
   }
 
+  if (backupKeyProvider === 'BitGo Trust' && backupKeychain.type === 'tss') {
+    const keyShares = backupKeychain.keyShares?.filter((keyShare) => keyShare.to === 'backup');
+    assert(keyShares?.length === 2);
+    return {
+      title: 'B: Backup Key Shares',
+      description: `These are the key shares for ${backupKeyProvider}. If BitGo Inc. goes out of business,\r\n` +
+        `contact ${backupKeyProvider} and they will help you recover your funds.`,
+      data: JSON.stringify(keyShares),
+    };
+  }
+
   const pub = getPubFromKey(backupKeychain);
   assert(pub);
 
   if (backupKeyProvider) {
     return {
       title: 'B: Backup Key',
-      image: '.qrPublicBackupKey',
       description: `This is the public key held at ${backupKeyProvider}, an ${coin.name} recovery service. ` +
         `If you lose\r\nyour key, ${backupKeyProvider} will be able to sign transactions to recover funds.`,
       data: pub,
@@ -108,7 +114,6 @@ function generateBackupQrData(coin: Readonly<BaseCoin>, backupKeychain: Keychain
 
   return {
     title: 'B: Provided Backup Key',
-    image: '.qrEncryptedUserProvidedXpub',
     description: 'This is the public key you provided for your wallet.',
     data: pub,
     publicMasterKey: backupMasterKey,
@@ -121,7 +126,6 @@ function generateBitGoQrData(bitgoKeychain: Keychain): QrDataEntry {
 
   return {
     title: 'C: BitGo Public Key',
-    image: '.qrBitgoKey',
     description:
       'This is the public part of the key that BitGo will use to ' +
       'co-sign transactions\r\nwith you on your wallet.',
@@ -154,8 +158,7 @@ export function generateQrData({
 
     qrData.passcode = {
       title: 'D: Encrypted wallet Password',
-      image: '.qrEncryptedWalletPasscode',
-      description: 'This is the wallet password, encrypted client-side with a key held by\r\nBitGo.',
+      description: 'This is the wallet password, encrypted client-side with a key held by BitGo.',
       data: encryptedWalletPasscode,
     };
   }

package/src/index.ts

@@ -1 +1,22 @@
+import { generateQrData, GenerateQrDataParams } from './generateQrData';
+import { generateFaq } from './faq';
+import { drawKeycard } from './drawKeycard';
+
+export * from './drawKeycard';
+export * from './faq';
+export * from './generateQrData';
 export * from './utils';
+
+export interface GenerateKeycardParams extends GenerateQrDataParams {
+  activationCode?: string;
+  keyCardImage?: HTMLImageElement;
+  walletLabel: string;
+}
+
+export async function generateKeycard(params: GenerateKeycardParams): Promise<void> {
+  const questions = generateFaq(params.coin.fullName);
+  const qrData = generateQrData(params);
+  const keycard = await drawKeycard({ ...params, questions, qrData });
+  // Save the PDF on the user's browser
+  keycard.save(`BitGo Keycard for ${params.walletLabel}.pdf`);
+}

package/test/unit/generateQrData.ts

@@ -2,19 +2,23 @@ import * as assert from 'assert';
 import * as should from 'should';
 import { generateQrData } from '../../src/generateQrData';
 import { decrypt } from '@bitgo-beta/sdk-api';
-import { Keychain, KeyType } from '@bitgo-beta/sdk-core';
+import { ApiKeyShare, Keychain, KeyType } from '@bitgo-beta/sdk-core';
 import { coins } from '@bitgo-beta/statics';
 
 function createKeychain({
   commonKeychain,
   commonPub,
   encryptedPrv,
+  keyShares,
+  provider,
   pub,
   type,
 }: {
   commonKeychain?: string;
   commonPub?: string;
   encryptedPrv?: string;
+  keyShares?: ApiKeyShare[];
+  provider?: string;
   pub?: string;
   type?: KeyType;
 }): Keychain {
@@ -23,6 +27,8 @@ function createKeychain({
     commonPub,
     encryptedPrv,
     id: 'id',
+    keyShares,
+    provider,
     pub: pub ?? 'pub',
     type: type ?? 'independent',
   };
@@ -51,27 +57,23 @@ describe('generateQrData', function () {
     });
 
     qrData.user.title.should.equal('A: User Key');
-    qrData.user.image.should.equal('.qrEncryptedUserKey');
     qrData.user.description.should.equal('This is your private key, encrypted with your wallet password.');
     qrData.user.data.should.equal(userEncryptedPrv);
 
     assert(qrData.backup);
     qrData.backup.title.should.equal('B: Backup Key');
-    qrData.backup.image.should.equal('.qrEncryptedBackupKey');
     qrData.backup.description.should.equal('This is your backup private key, encrypted with your wallet password.');
     qrData.backup.data.should.equal(backupEncryptedPrv);
 
     assert(qrData.bitgo);
     qrData.bitgo.title.should.equal('C: BitGo Public Key');
-    qrData.bitgo.image.should.equal('.qrBitgoKey');
     qrData.bitgo.description.should.equal('This is the public part of the key that BitGo will use to ' +
       'co-sign transactions\r\nwith you on your wallet.');
     qrData.bitgo.data.should.equal(bitgoPub);
 
     assert(qrData.passcode);
     qrData.passcode.title.should.equal('D: Encrypted wallet Password');
-    qrData.passcode.image.should.equal('.qrEncryptedWalletPasscode');
-    qrData.passcode.description.should.equal('This is the wallet password, encrypted client-side with a key held by\r\nBitGo.');
+    qrData.passcode.description.should.equal('This is the wallet password, encrypted client-side with a key held by BitGo.');
     const decryptedData = decrypt(passcodeEncryptionCode, qrData.passcode.data);
     decryptedData.should.equal(passphrase);
   });
@@ -114,14 +116,12 @@ describe('generateQrData', function () {
         });
 
         qrData.user.title.should.equal('A: Provided User Key');
-        qrData.user.image.should.equal('.qrPublicUserKey');
         qrData.user.description.should.equal('This is the public key you provided for your wallet.');
         qrData.user.data.should.equal(userPub);
         should.equal(qrData.user.publicMasterKey, userMasterKey);
 
         assert(qrData.backup);
         qrData.backup.title.should.equal('B: Provided Backup Key');
-        qrData.backup.image.should.equal('.qrEncryptedUserProvidedXpub');
         qrData.backup.description.should.equal('This is the public key you provided for your wallet.');
         qrData.backup.data.should.equal(backupPub);
         should.equal(qrData.backup?.publicMasterKey, backupMasterKey);
@@ -138,13 +138,14 @@ describe('generateQrData', function () {
     const coin = coins.get('btc');
     const userEncryptedPrv = 'prv123encrypted';
     const backupPub = 'pub673backup';
-    const backupKeyProvider = '3rd Party Provider';
+    const provider = '3rd Party Provider';
     const bitgoPub = 'pub789bitgo';
     const qrData = generateQrData({
       backupKeychain: createKeychain({
         pub: backupPub,
+        provider,
       }),
-      backupKeyProvider,
+      backupKeyProvider: provider,
       bitgoKeychain: createKeychain({
         pub: bitgoPub,
       }),
@@ -158,17 +159,55 @@ describe('generateQrData', function () {
 
     assert(qrData.backup);
     qrData.backup.title.should.equal('B: Backup Key');
-    qrData.backup.image.should.equal('.qrPublicBackupKey');
     qrData.backup.description.should.equal('This is the public key held at ' +
-      backupKeyProvider +
+      provider +
       ', an ' +
       coin.name +
       ' recovery service. If you lose\r\nyour key, ' +
-      backupKeyProvider +
+      provider +
       ' will be able to sign transactions to recover funds.');
     qrData.backup.data.should.equal(backupPub);
 
     assert(qrData.bitgo);
     qrData.bitgo.data.should.equal(bitgoPub);
   });
+
+  it('tss backup key held at BitGo Trust', function () {
+    const coin = coins.get('btc');
+    const userEncryptedPrv = 'prv123encrypted';
+    const provider = 'BitGoTrustAsKRS';
+    const backupKeyProvider = 'BitGo Trust';
+    const userToBackupKeyShare: ApiKeyShare = { from: 'user', to: 'backup', publicShare: 'userToBackupPublic', privateShare: 'userToBackupPrivate' };
+    const bitgoToBackupKeyShare: ApiKeyShare = { from: 'bitgo', to: 'backup', publicShare: 'bitgoToBackupPublic', privateShare: 'bitgoToBackupPrivate' };
+    const bitgoCommonKeychain = 'commonCommonBitGo';
+    const qrData = generateQrData({
+      backupKeychain: createKeychain({
+        provider,
+        keyShares: [userToBackupKeyShare, bitgoToBackupKeyShare],
+        type: 'tss',
+      }),
+      backupKeyProvider,
+      bitgoKeychain: createKeychain({
+        type: 'tss',
+        commonKeychain: bitgoCommonKeychain,
+      }),
+      coin,
+      userKeychain: createKeychain({
+        encryptedPrv: userEncryptedPrv,
+        type: 'tss',
+      }),
+    });
+
+    qrData.user.data.should.equal(userEncryptedPrv);
+
+    assert(qrData.backup);
+    qrData.backup.title.should.equal('B: Backup Key Shares');
+    qrData.backup.description.should.equal(`These are the key shares for ${backupKeyProvider}. If BitGo Inc. goes out of business,\r\ncontact ${backupKeyProvider} and they will help you recover your funds.`);
+    qrData.backup.data.should.equal(JSON.stringify([userToBackupKeyShare, bitgoToBackupKeyShare]));
+
+    assert(qrData.bitgo);
+    qrData.bitgo.title.should.equal('C: BitGo Public Key');
+    qrData.bitgo.description.should.equal('This is the public part of the key that BitGo will use to co-sign transactions\r\nwith you on your wallet.');
+    qrData.bitgo.data.should.equal(bitgoCommonKeychain);
+  });
 });