chore: versioning alignment

.gitignore

@@ -5,15 +5,19 @@
 *.pem
 *.key
 
+# Claude
+.claude/
+CLAUDE.md
+
 # Dependencies
 dependencies
 node_modules
 .pnp
 .pnp.js
 .claude/
+yarn.lock
 # Generated dependency attributions
 ATTRIBUTION.md
-.gitlab-ci.yml
 
 # Testing
 coverage

README.md

@@ -8,7 +8,6 @@
   Recover Fireblocks assets and keys in a disaster, verify a Recovery Kit, or generate keys to set up a new Recovery Kit.
   <br />
   <br />
-  <br />
   <a href="#" target="_blank">
     <img  src="docs/img/splash.png" alt="Screenshot" />
   </a>
@@ -18,7 +17,7 @@
 
 ## 🆕 Coming from [fireblocks-key-recovery-tool](https://github.com/fireblocks/fireblocks-key-recovery-tool)?
 
-[Recovery Utility](apps/recovery-utility) offers a UI for your entire workspace backup and recovery lifecycle.
+[Recovery Utility](apps/recovery-utility) offers a simple UI for your entire workspace backup and recovery lifecycle.
 
 - Generate and verify keys for a new Recovery Kit.
 - Verify your recovery procedure (sanity test).

apps/recovery-relay/package.json

@@ -4,7 +4,7 @@
   "author": "Fireblocks (https://www.fireblocks.com)",
   "repository": "https://github.com/fireblocks/recovery/tree/main/apps/recovery-relay",
   "license": "GPL-3.0-or-later",
-  "version": "1.8.4",
+  "version": "1.8.6",
   "private": true,
   "scripts": {
     "dev": "next dev",

apps/recovery-utility/README.md

@@ -8,11 +8,6 @@
   Recover Fireblocks assets and keys in a disaster, verify a Recovery Kit, or generate keys to set up a new Recovery Kit.
   <br />
   <br />
-  <a href="https://github.com/fireblocks/recovery/releases">
-    ⬇️ Download for macOS / Linux
-  </a>
-  <br />
-  <br />
   <a href="#" target="_blank">
     <img src="../../docs/img/splash.png" alt="Screenshot" />
   </a>
@@ -28,8 +23,8 @@
    - Protected with a very strong password
    - Encrypted on all partitions
    - Stored in a safe box when not in use
-2. [Install the latest release of Recovery Utility](https://github.com/fireblocks/recovery/releases) on the offline recovery machine.
-3. **(Optional)** [Install the latest release of Recovery Relay](https://github.com/fireblocks/recovery/releases) on a web server. [Recovery Relay](../recovery-relay/) is a companion web app that gets wallet balances and sends transactions without revealing your private keys.
+2. Install the latest release of Recovery Utility on the offline recovery machine.
+3. **(Optional)** Install the latest release of Recovery Relay on a web server. [Recovery Relay](../recovery-relay/) is a companion web app that gets wallet balances and sends transactions without revealing your private keys.
 4. Open Recovery Utility to use one of the following tools...
 
 ### 🧰 Tools

apps/recovery-utility/package.json

@@ -4,7 +4,7 @@
   "author": "Fireblocks (https://www.fireblocks.com)",
   "repository": "https://github.com/fireblocks/recovery/tree/main/apps/recovery-utility",
   "homepage": "https://www.fireblocks.com",
-  "version": "1.8.3",
+  "version": "1.8.6",
   "license": "GPL-3.0-or-later",
   "private": true,
   "main": "app/background.js",

apps/recovery-utility/renderer/components/RecoveryForm/index.tsx

@@ -98,8 +98,11 @@ export const RecoveryForm = ({ verifyOnly }: Props) => {
       const maskedExtendedKeys: UtilityExtendedKeys = {};
 
       Object.entries(recoveredKeys).forEach(([keysetId, value]) => {
-        if (keysetId === 'ncwMaster' && !verifyOnly) {
-          maskedExtendedKeys.ncwMaster = value as WalletMaster | undefined;
+        // recoverKeys returns the NCW master under `ncwWalletMaster`, not as a keyset entry
+        if (keysetId === 'ncwWalletMaster') {
+          if (!verifyOnly) {
+            maskedExtendedKeys.ncwMaster = value as WalletMaster | undefined;
+          }
           return;
         }
 

apps/recovery-utility/renderer/lib/recoverExtendedKeys.ts

@@ -37,7 +37,11 @@ export const recoverExtendedKeys = async (args: Args) => {
     } as KeyRecoveryConfig;
   }
 
-  config = { ...config, recoverOnlyNCW: args.recoverOnlyNCW };
+  config = {
+    ...config,
+    recoverOnlyNCW: args.recoverOnlyNCW,
+    onLog: (msg: string) => logger.info(msg),
+  };
 
   const response = recoverKeys(config);
   return response;

apps/recovery-utility/renderer/pages/ncw.tsx

@@ -87,7 +87,18 @@ const NCW = () => {
 
         const walletId = data['Wallet Id'];
         try {
-          setDerivedWalletKeys((prev) => ({ ...prev, [walletId]: euWallet.derivePrivateKey(walletId, 'MPC_ECDSA_SECP256K1') }));
+          const ecdsa = euWallet.derivePrivateKey(walletId, 'MPC_ECDSA_SECP256K1');
+          const eddsa = euWallet.derivePrivateKey(walletId, 'MPC_EDDSA_ED25519');
+
+          const mergedShares = ecdsa.shares.map((ecdsaShare) => {
+            const eddsaShare = eddsa.shares.find((s) => s.cosigner === ecdsaShare.cosigner);
+            return { ...ecdsaShare, ...eddsaShare };
+          });
+
+          setDerivedWalletKeys((prev) => ({
+            ...prev,
+            [walletId]: { chainCode: ecdsa.chainCode, shares: mergedShares },
+          }));
         } catch (e) {
           logger.error('Failed to derive wallet for wallet id:', walletId, e);
           throw e;

docs/CODEOWNERS

@@ -1,16 +1,16 @@
 * @fireblocks-solutions-engineering
 
 # Recovery Utility
-packages/recovery-utility/ @fireblocks-solutions-engineering @Burry @gburry-fireblocks
+packages/recovery-utility/ @fireblocks-solutions-engineering @slava23 @nadav14 @costyb
 
 # Recovery Relay
-packages/recovery-relay/ @fireblocks-solutions-engineering @Burry @gburry-fireblocks
+packages/recovery-relay/ @fireblocks-solutions-engineering @slava23 @nadav14 @costyb
 
 # Shared frontend components and utilities
-packages/shared/ @fireblocks-solutions-engineering @Burry @gburry-fireblocks
+packages/shared/ @fireblocks-solutions-engineering @slava23 @nadav14 @costyb
 
 # Extended Key Recovery module
-packages/extended-key-recovery/ @fireblocks-solutions-engineering @agoltzman
+packages/extended-key-recovery/ @fireblocks-solutions-engineering @slava23 @nadav14 @costyb
 
 # Wallet Derivation helpers
-packages/wallet-derivation/ @fireblocks-solutions-engineering @Burry @gburry-fireblocks
+packages/wallet-derivation/ @fireblocks-solutions-engineering @slava23 @nadav14 @costyb

packages/extended-key-recovery/src/decrypt.ts

@@ -1,4 +1,5 @@
 import * as forge from 'node-forge';
+import { pbkdf2Sync, createDecipheriv } from 'crypto';
 
 const _unpad = (text: Buffer, k = 16): Buffer => {
   const nl = text.length;
@@ -13,6 +14,20 @@ const _unpad = (text: Buffer, k = 16): Buffer => {
   return text.subarray(0, l_idx);
 };
 
+export const decryptMobilePrivateKeyV2 = (
+  pass: string,
+  userId: string,
+  encryptedKey: Buffer,
+  iv: string,
+  kdfHash: string,
+  kdfIterations: number,
+): Buffer => {
+  const digest = kdfHash.toUpperCase() === 'SHA256' ? 'sha256' : 'sha1';
+  const wrappedKey = pbkdf2Sync(pass, userId, kdfIterations, 32, digest);
+  const decipher = createDecipheriv('aes-256-cbc', wrappedKey, Buffer.from(iv, 'hex'));
+  return Buffer.concat([decipher.update(encryptedKey), decipher.final()]);
+};
+
 export const decryptMobilePrivateKey = (pass: string, userId: string, encryptedKey: Buffer): Buffer => {
   const wrappedKey = forge.pkcs5.pbkdf2(pass, userId, 10000, 32, 'sha1');
   const decipher = forge.cipher.createDecipher(

packages/extended-key-recovery/src/mobileKey.ts

@@ -1,4 +1,4 @@
-import { decryptMobilePrivateKey } from './decrypt';
+import { decryptMobilePrivateKey, decryptMobilePrivateKeyV2 } from './decrypt';
 import { getPlayerId } from './players';
 import { DecryptMobileKeyError, KeyIdNotInMetadata, MobileKeyShare, SigningKeyMetadata, UnknownAlgorithmError } from './types';
 
@@ -13,6 +13,7 @@ export const recoverMobileKeyShare = (
   signingKeys: { [key: string]: SigningKeyMetadata },
   keyShareStr: string,
   mobilePass: string,
+  onLog?: (message: string) => void,
 ) => {
   const keyShare = JSON.parse(keyShareStr) as MobileKeyShare;
   const { keyId } = keyShare;
@@ -22,7 +23,21 @@ export const recoverMobileKeyShare = (
   }
 
   try {
-    decryptedKey = decryptMobilePrivateKey(mobilePass, keyShare.userId, Buffer.from(keyShare.encryptedKey, 'hex'));
+    const meta = keyShare.encryptionMetaData;
+    if (meta?.version === 2 && meta.iv && meta.kdfHash && meta.kdfIterations) {
+      onLog?.(`[mobileKey] Decrypting share with V2 (kdfHash=${meta.kdfHash}, kdfIterations=${meta.kdfIterations})`);
+      decryptedKey = decryptMobilePrivateKeyV2(
+        mobilePass,
+        keyShare.userId,
+        Buffer.from(keyShare.encryptedKey, 'hex'),
+        meta.iv,
+        meta.kdfHash,
+        meta.kdfIterations,
+      );
+    } else {
+      onLog?.(`[mobileKey] Decrypting share with V1 (metaVersion=${meta?.version ?? 'none'})`);
+      decryptedKey = decryptMobilePrivateKey(mobilePass, keyShare.userId, Buffer.from(keyShare.encryptedKey, 'hex'));
+    }
   } catch (e) {
     throw new DecryptMobileKeyError();
   }

packages/extended-key-recovery/src/recover.ts

@@ -37,11 +37,12 @@ const recoverKeysShares = (
   mobilePass: string,
   rsaFileData: string,
   rsaPass: string,
+  onLog?: (message: string) => void,
 ): PlayerData => {
   const players: PlayerData = {};
   for (const file of zipFiles) {
     if (file.entryName.startsWith('MOBILE')) {
-      const { keyId, playerId, value } = recoverMobileKeyShare(signingKeys, file.getData().toString(), mobilePass);
+      const { keyId, playerId, value } = recoverMobileKeyShare(signingKeys, file.getData().toString(), mobilePass, onLog);
       if (players[keyId] === undefined) {
         players[keyId] = {};
       }
@@ -174,7 +175,7 @@ export const recoverKeys = (params: KeyRecoveryConfig): RecoveredKeys => {
     return { ncwWalletMaster: walletMaster };
   }
 
-  const players: PlayerData = recoverKeysShares(zipFiles, signingKeys, mobilePass, rsaFileData, params.rsaPass);
+  const players: PlayerData = recoverKeysShares(zipFiles, signingKeys, mobilePass, rsaFileData, params.rsaPass, params.onLog);
 
   for (const keyId in signingKeys) {
     if (!Object.keys(players).includes(keyId)) {

packages/extended-key-recovery/src/types.ts

@@ -127,12 +127,20 @@ export class InvalidMasterKey extends Error {
 
 export type PlayerData = { [keyId: string]: { [playerId: string]: bigint } };
 
+export type MobileKeyShareEncryptionMetaData = {
+  iv?: string;
+  kdfHash?: string;
+  kdfIterations?: number;
+  version?: number;
+};
+
 export type MobileKeyShare = {
   encryptedKey: string;
   keyId: string;
   deviceId: string;
   userId: string;
   encryptionAlgorithm: string;
+  encryptionMetaData?: MobileKeyShareEncryptionMetaData;
 };
 
 export type RecoveredKey = {
@@ -178,6 +186,12 @@ export type KeyRecoveryConfig = {
    * Should only recover NCW wallet
    */
   recoverOnlyNCW: boolean;
+
+  /**
+   * Optional logger callback. Used to surface non-sensitive flow info
+   * (e.g. v1 vs v2 mobile-key decryption dispatch) to the host app's logger.
+   */
+  onLog?: (message: string) => void;
 } & (
   | {
       /**

packages/shared/hooks/useBaseWorkspace/index.ts

@@ -116,10 +116,7 @@ export const useBaseWorkspace = <App extends 'utility' | 'relay', Derivation ext
       if (app === 'utility') {
         const keys = extendedKeys as UtilityExtendedKeys;
         const newExtendedKeys: KeysetMap = { ...prev.extendedKeys };
-        const newWorkspace = {
-          ...prev,
-          ncwMaster: keys.ncwMaster,
-        };
+        const newWorkspace = { ...prev };
         Object.entries(keys).forEach(([keysetId, value]) => {
           if (keysetId === 'ncwMaster') {
             return;
@@ -131,7 +128,12 @@ export const useBaseWorkspace = <App extends 'utility' | 'relay', Derivation ext
           };
         });
 
-        newWorkspace.extendedKeys = { ...newExtendedKeys };
+        // ncwMaster lives alongside the keyset entries on extendedKeys - every consumer
+        // (Layout, /ncw, wallet derivation) reads it from there.
+        newWorkspace.extendedKeys = {
+          ...newExtendedKeys,
+          ncwMaster: keys.ncwMaster ?? (newExtendedKeys as UtilityExtendedKeys).ncwMaster,
+        } as typeof newWorkspace.extendedKeys;
 
         return newWorkspace;
       }

packages/shared/hooks/useBaseWorkspace/reduceDerivations.ts

@@ -84,7 +84,7 @@ export const reduceDerivations = <App extends 'utility' | 'relay', T extends Bas
 
   // Mock derivation
   if (address) {
-    wallet.derivations.set(address, {
+    wallet.derivations.set(getDerivationMapKey(assetId, address), {
       assetId,
       path,
       pathParts: [44, path.coinType, path.account, path.changeIndex, path.addressIndex],
@@ -159,7 +159,8 @@ export const reduceDerivations = <App extends 'utility' | 'relay', T extends Bas
 
   const missingWalletKey = (hasXpub && !publicKey) || (hasXprv && !privateKey);
 
-  const shouldDerive = canDerive && (missingWalletKey || !address || !wallet.derivations.has(address));
+  const shouldDerive =
+    canDerive && (missingWalletKey || !address || !wallet.derivations.has(getDerivationMapKey(assetId, address)));
 
   // Derive wallet
   if (shouldDerive) {
@@ -169,7 +170,7 @@ export const reduceDerivations = <App extends 'utility' | 'relay', T extends Bas
     if (address && derivation.address !== address) {
       // TODO: Show notice in UI when this happens. For now just remove the erroneous imported address
       logger.warn(`Address mismatch, dropping import. Imported ${address}, derived ${derivation.address}`);
-      wallet.derivations.delete(address);
+      wallet.derivations.delete(getDerivationMapKey(assetId, address));
     }
 
     wallet.derivations.set(getDerivationMapKey(derivation.assetId, derivation.address), derivation);

packages/wallet-derivation/types.ts

@@ -31,7 +31,7 @@ export type KeyDerivation = Readonly<{
 
 export type NCWalletShare = {
   chainCode: string;
-  shares: { cosigner: string; MPC_CMP_ECDSA_SECP256K1: string }[];
+  shares: { cosigner: string; MPC_CMP_ECDSA_SECP256K1?: string; MPC_CMP_EDDSA_ED25519?: string }[];
 };
 
 export interface Derivation {