From 60388a689208e7c5bb0084cee4b701a32068c0eb Mon Sep 17 00:00:00 2001 From: Zahin Mohammad Date: Mon, 26 Oct 2026 15:45:58 -0400 Subject: [PATCH] fix(sdk-core): type optional ECDH keychain results (Refs: WCN-3735) --- modules/sdk-api/src/bitgoAPI.ts | 22 +++++++++++++++++-- modules/sdk-api/test/unit/bitgoAPI.ts | 20 +++++++++++++++++ modules/sdk-core/src/bitgo/bitgoBase.ts | 18 +++++++++++++-- modules/sdk-core/src/bitgo/v1Wallets.ts | 10 ++++++++- modules/sdk-core/src/bitgo/wallet/iWallets.ts | 4 ++++ modules/sdk-core/src/bitgo/wallet/wallets.ts | 14 ++++++------ .../bitgo/wallet/walletsEncryptionVersion.ts | 2 +- 7 files changed, 77 insertions(+), 13 deletions(-) diff --git a/modules/sdk-api/src/bitgoAPI.ts b/modules/sdk-api/src/bitgoAPI.ts index 504868e629a..a3e4f9ada48 100644 --- a/modules/sdk-api/src/bitgoAPI.ts +++ b/modules/sdk-api/src/bitgoAPI.ts @@ -11,12 +11,14 @@ import { DecryptOptions, defaultConstants, EcdhDerivedKeypair, + EcdhKeychain, EncryptionVersion, EncryptOptions, EnvironmentName, generateRandomPassword, getAddressP2PKH, getSharedSecret, + GetEcdhKeychainOptions, GetSharingKeyOptions, GetSigningKeyApi, GlobalCoinFactory, @@ -1876,9 +1878,22 @@ export class BitGoAPI implements BitGoBase { } /** - * Gets the user's private ECDH keychain + * Gets the user's private ECDH keychain. + * Returns undefined only when allowMissing is true and the user has no ECDH keychain. */ - async getECDHKeychain(ecdhKeychainPub?: string, options: { allowMissing?: boolean } = {}): Promise { + async getECDHKeychain(ecdhKeychainPub?: string, options?: { allowMissing?: false }): Promise; + async getECDHKeychain( + ecdhKeychainPub: string | undefined, + options: { allowMissing: true } + ): Promise; + async getECDHKeychain( + ecdhKeychainPub: string | undefined, + options: GetEcdhKeychainOptions + ): Promise; + async getECDHKeychain( + ecdhKeychainPub?: string, + options: GetEcdhKeychainOptions = {} + ): Promise { if (!ecdhKeychainPub) { const result = await this.get(this.url('/user/settings')).result(); if (!result.settings.ecdhKeychain) { @@ -1906,6 +1921,9 @@ export class BitGoAPI implements BitGoBase { throw new Error('Something went wrong with the user keychain. Please contact support@bitgo.com.'); } const userEcdhKeychain = await this.getECDHKeychain(userSigningKey.ecdhKeychain); + if (!userEcdhKeychain.encryptedXprv) { + throw new Error('Something went wrong with the user keychain. Please contact support@bitgo.com.'); + } let xprv; try { xprv = await this.decrypt({ diff --git a/modules/sdk-api/test/unit/bitgoAPI.ts b/modules/sdk-api/test/unit/bitgoAPI.ts index b6da41d55ba..2e776f7de4a 100644 --- a/modules/sdk-api/test/unit/bitgoAPI.ts +++ b/modules/sdk-api/test/unit/bitgoAPI.ts @@ -1593,4 +1593,24 @@ describe('getECDHKeychain', function () { assert.strictEqual(keychain, undefined); }); + + it('rejects signing-key derivation when the ECDH keychain has no encrypted private key', async function () { + const bitgo = new BitGoAPI({ env: 'custom', customRootURI: ROOT }); + sinon.stub(bitgo, 'getSigningKeyForUser').resolves({ + userId: 'user-id', + userEmail: 'user@example.com', + derivedPubkey: 'derived-pubkey', + derivationPath: 'm/0', + ecdhKeychain: 'xpub', + }); + sinon.stub(bitgo, 'getECDHKeychain').resolves({ xpub: 'xpub' }); + const decrypt = sinon.spy(bitgo, 'decrypt'); + + await assert.rejects( + bitgo.getEcdhKeypairPrivate('password', 'enterprise-id'), + /Something went wrong with the user keychain/ + ); + + assert.strictEqual(decrypt.called, false); + }); }); diff --git a/modules/sdk-core/src/bitgo/bitgoBase.ts b/modules/sdk-core/src/bitgo/bitgoBase.ts index 698e4846fd4..f5ba5abf1d1 100644 --- a/modules/sdk-core/src/bitgo/bitgoBase.ts +++ b/modules/sdk-core/src/bitgo/bitgoBase.ts @@ -12,7 +12,12 @@ import { IBaseCoin } from './baseCoin'; import { CoinConstructor } from './coinFactory'; import { EnvironmentName } from './environments'; import { EcdhDerivedKeypair, GetSigningKeyApi } from './keychain'; -import type { BitGoApiV1Wallets } from './v1Wallets'; +import type { BitGoApiV1Wallets, EcdhKeychain } from './v1Wallets'; + +export interface GetEcdhKeychainOptions { + /** Return undefined instead of throwing when the user has no ECDH keychain. */ + allowMissing?: boolean; +} export type { BitGoApiV1AddWalletParams, @@ -20,6 +25,7 @@ export type { BitGoApiV1Callback, BitGoApiV1CreateForwardWalletParams, BitGoApiV1CreateWalletWithKeychainsParams, + EcdhKeychain, BitGoApiV1GetWalletParams, BitGoApiV1Keychains, BitGoApiV1ListWalletsParams, @@ -48,7 +54,15 @@ export interface BitGoBase { readonly env: EnvironmentName; fetchConstants(): Promise; get(url: string): BitGoRequest; - getECDHKeychain(ecdhKeychainPub?: string, options?: { allowMissing?: boolean }): Promise; + getECDHKeychain(ecdhKeychainPub?: string, options?: { allowMissing?: false }): Promise; + getECDHKeychain( + ecdhKeychainPub: string | undefined, + options: { allowMissing: true } + ): Promise; + getECDHKeychain( + ecdhKeychainPub: string | undefined, + options: GetEcdhKeychainOptions + ): Promise; getEcdhKeypairPrivate(password: string, entId?: string): Promise; getEnv(): EnvironmentName; getSharingKey({ email }: GetSharingKeyOptions): Promise; diff --git a/modules/sdk-core/src/bitgo/v1Wallets.ts b/modules/sdk-core/src/bitgo/v1Wallets.ts index 84187fe76c5..d20fc1fd4ce 100644 --- a/modules/sdk-core/src/bitgo/v1Wallets.ts +++ b/modules/sdk-core/src/bitgo/v1Wallets.ts @@ -1,5 +1,13 @@ import type { BitGoRequest, DecryptOptions, EncryptionVersion, EncryptOptions } from '../api'; +/** User-level Elliptic Curve Diffie-Hellman (ECDH) sharing key returned by the legacy keychain API. */ +export type EcdhKeychain = { + encryptedXprv?: string; + xprv?: string; + xpub?: string; + [key: string]: unknown; +}; + /** * Minimal BitGo client surface used by the **v1** Wallets facade * (`modules/sdk-api/src/v1/wallets.ts`). @@ -18,7 +26,7 @@ export type BitGoApiV1BitGo = { url(path: string, version?: number): string; encrypt(params: EncryptOptions): Promise; decrypt(params: DecryptOptions): Promise; - getECDHKeychain(): Promise<{ encryptedXprv?: string; xprv?: string }>; + getECDHKeychain(): Promise; keychains(): BitGoApiV1Keychains; }; diff --git a/modules/sdk-core/src/bitgo/wallet/iWallets.ts b/modules/sdk-core/src/bitgo/wallet/iWallets.ts index d33e4efae43..62598ac7d5d 100644 --- a/modules/sdk-core/src/bitgo/wallet/iWallets.ts +++ b/modules/sdk-core/src/bitgo/wallet/iWallets.ts @@ -367,6 +367,10 @@ export interface AcceptShareOptions { export interface BulkAcceptShareOptions { walletShareIds: string[]; + /** + * Decrypts an existing ECDH sharing key. For a passkey account accepting only user multi-key rotation shares, + * no login password or ECDH key exists; `newWalletPassphrase` or this value encrypts the fresh wallet key. + */ userLoginPassword: string; newWalletPassphrase?: string; webauthnInfo?: WebauthnKeyEncryptionInfo; diff --git a/modules/sdk-core/src/bitgo/wallet/wallets.ts b/modules/sdk-core/src/bitgo/wallet/wallets.ts index 772482dbf3f..2226ab68f23 100644 --- a/modules/sdk-core/src/bitgo/wallet/wallets.ts +++ b/modules/sdk-core/src/bitgo/wallet/wallets.ts @@ -1322,13 +1322,13 @@ export class Wallets implements IWallets { /** * Bulk Accept wallet shares, adding the wallets to the user's list - * Needs a user's password to decrypt the shared key + * Decrypts conventional shared keys or creates fresh user keys for multi-key rotation shares. * * @param params BulkAcceptShareOptions - * @param params.walletShareId - array of the wallet shares to accept - * @param params.userPassword - user's password to decrypt the shared wallet key + * @param params.walletShareIds - wallet shares to accept + * @param params.userLoginPassword - password used to decrypt an existing ECDH sharing key * @param params.newWalletPassphrase - new wallet passphrase for saving the shared wallet prv. - * If left blank then the user's login password is used. + * If left blank then userLoginPassword is used. * *@returns {Promise} */ @@ -1361,9 +1361,9 @@ export class Wallets implements IWallets { const hasSharesRequiringDecryption = walletShares.some( (walletShare) => !walletShare.userMultiKeyRotationRequired && walletShare.keychain ); - const sharingKeychain = await this.bitgo.getECDHKeychain(undefined, { - allowMissing: !hasSharesRequiringDecryption, - }); + const sharingKeychain = hasSharesRequiringDecryption + ? await this.bitgo.getECDHKeychain(undefined, { allowMissing: false }) + : await this.bitgo.getECDHKeychain(undefined, { allowMissing: true }); let sharingKeychainPrv: string | undefined; if (sharingKeychain) { if (_.isUndefined(sharingKeychain.encryptedXprv)) { diff --git a/modules/sdk-core/test/unit/bitgo/wallet/walletsEncryptionVersion.ts b/modules/sdk-core/test/unit/bitgo/wallet/walletsEncryptionVersion.ts index d9b81fb247e..1b7e33b48b2 100644 --- a/modules/sdk-core/test/unit/bitgo/wallet/walletsEncryptionVersion.ts +++ b/modules/sdk-core/test/unit/bitgo/wallet/walletsEncryptionVersion.ts @@ -145,7 +145,7 @@ describe('Wallets - encryptionVersion threading', function () { assert.strictEqual(call.args[1], undefined); }); - it('accepts a UMKR-only batch when the user has no ECDH keychain', async function () { + it('accepts a multi-key rotation-only batch for a passkey account without an ECDH keychain', async function () { mockBitGo.getECDHKeychain.resolves(undefined); await wallets.bulkAcceptShare({