feat(sdk-core): update wallet share acceptance for multi-user-key

TICKET: WP-6769

Author: zahin-mohammad

modules/bitgo/test/v2/unit/wallets.ts

@@ -1728,6 +1728,198 @@ describe('V2 Wallets:', function () {
       });
     });
 
+    describe('Wallet share where userMultiKeyRotationRequired is set true', () => {
+      const sandbox = sinon.createSandbox();
+
+      afterEach(function () {
+        sandbox.verifyAndRestore();
+      });
+
+      it('should throw error when password not provided', async function () {
+        const shareId = 'test_multi_key_1';
+
+        const walletShareNock = nock(bgUrl)
+          .get(`/api/v2/tbtc/walletshare/${shareId}`)
+          .reply(200, {
+            userMultiKeyRotationRequired: true,
+            permissions: ['admin', 'spend', 'view'],
+          });
+
+        await wallets
+          .acceptShare({ walletShareId: shareId })
+          .should.be.rejectedWith('userPassword param must be provided to generate user keychain');
+        walletShareNock.done();
+      });
+
+      it('should successfully accept share with userMultiKeyRotationRequired and send pub and encryptedPrv', async function () {
+        const shareId = 'test_multi_key_2';
+        const userPassword = 'test_password_123';
+        const walletId = 'test_wallet_123';
+
+        // Mock wallet share response
+        const walletShareNock = nock(bgUrl)
+          .get(`/api/v2/tbtc/walletshare/${shareId}`)
+          .reply(200, {
+            userMultiKeyRotationRequired: true,
+            permissions: ['admin', 'spend', 'view'],
+            wallet: walletId,
+          });
+
+        // Mock keychain creation - baseCoin.keychains().create() returns { prv, pub }
+        // We need to create a proper keychain object with prv property
+        const testKeychain = bitgo.keychains().create();
+        const keychain = {
+          prv: testKeychain.xprv, // baseCoin.keychains().create() returns prv (not xprv), but for BTC it's the same
+          pub: testKeychain.xpub,
+        };
+        const encryptedPrv = bitgo.encrypt({ input: keychain.prv, password: userPassword });
+
+        // Mock the updateShare API call
+        const acceptShareNock = nock(bgUrl)
+          .post(`/api/v2/tbtc/walletshare/${shareId}`, (body: any) => {
+            // Verify that pub and encryptedPrv are included
+            if (body.walletShareId !== shareId || body.state !== 'accepted' || !body.pub || !body.encryptedPrv) {
+              return false;
+            }
+            // Verify pub is a valid format (xpub for BTC)
+            if (!body.pub.startsWith('xpub')) {
+              return false;
+            }
+            return true;
+          })
+          .reply(200, { changed: true, state: 'accepted' });
+
+        // Stub keychains().create() to return our test keychain
+        const keychainsStub = sandbox.stub(wallets.baseCoin.keychains(), 'create').resolves(keychain);
+
+        // Stub bitgo.encrypt to return our encrypted value
+        const encryptStub = sandbox.stub(bitgo, 'encrypt').returns(encryptedPrv);
+
+        const res = await wallets.acceptShare({ walletShareId: shareId, userPassword });
+        should.equal(res.changed, true);
+        should.equal(res.state, 'accepted');
+
+        // Verify keychain creation was called
+        should.equal(keychainsStub.calledOnce, true);
+        // Verify encrypt was called with the correct parameters
+        should.equal(encryptStub.calledWith({ input: keychain.prv, password: userPassword }), true);
+
+        walletShareNock.done();
+        acceptShareNock.done();
+      });
+
+      it('should NOT trigger reshare when userMultiKeyRotationRequired is true', async function () {
+        const shareId = 'test_multi_key_3';
+        const userPassword = 'test_password_123';
+        const walletId = 'test_wallet_123';
+
+        const walletShareNock = nock(bgUrl)
+          .get(`/api/v2/tbtc/walletshare/${shareId}`)
+          .reply(200, {
+            userMultiKeyRotationRequired: true,
+            permissions: ['admin', 'spend', 'view'],
+            wallet: walletId,
+          });
+
+        const testKeychain = bitgo.keychains().create();
+        const keychain = {
+          prv: testKeychain.xprv,
+          pub: testKeychain.xpub,
+        };
+        const encryptedPrv = bitgo.encrypt({ input: keychain.prv, password: userPassword });
+
+        const acceptShareNock = nock(bgUrl)
+          .post(`/api/v2/tbtc/walletshare/${shareId}`)
+          .reply(200, { changed: true, state: 'accepted' });
+
+        sandbox.stub(wallets.baseCoin.keychains(), 'create').resolves(keychain);
+        sandbox.stub(bitgo, 'encrypt').returns(encryptedPrv);
+
+        // Stub reshareWalletWithSpenders to verify it's NOT called
+        const reshareStub = sandbox.stub(Wallets.prototype, 'reshareWalletWithSpenders');
+
+        const res = await wallets.acceptShare({ walletShareId: shareId, userPassword });
+        should.equal(res.changed, true);
+        should.equal(res.state, 'accepted');
+
+        // Verify reshare was NOT called (unlike keychainOverrideRequired case)
+        should.equal(reshareStub.called, false);
+
+        walletShareNock.done();
+        acceptShareNock.done();
+      });
+
+      it('should handle bulk accept share with userMultiKeyRotationRequired', async function () {
+        const shareId = 'test_multi_key_bulk_1';
+        const userPassword = 'test_password_123';
+
+        // Mock listSharesV2 to return a share with userMultiKeyRotationRequired
+        // Note: userMultiKeyRotationRequired shares don't have a keychain, so they won't be filtered
+        // by the bulkAcceptShare filter, but processAcceptShare will handle them
+        sinon.stub(Wallets.prototype, 'listSharesV2').resolves({
+          incoming: [
+            {
+              id: shareId,
+              coin: 'tbtc',
+              walletLabel: 'test wallet',
+              fromUser: 'fromUser',
+              toUser: 'toUser',
+              wallet: 'wallet123',
+              permissions: ['admin', 'spend', 'view'],
+              state: 'active',
+              userMultiKeyRotationRequired: true,
+              // No keychain - this is the key difference for multi-user-key shares
+            },
+          ],
+          outgoing: [],
+        });
+
+        const testKeychain = bitgo.keychains().create();
+        const keychain = {
+          prv: testKeychain.xprv,
+          pub: testKeychain.xpub,
+        };
+        const encryptedPrv = bitgo.encrypt({ input: keychain.prv, password: userPassword });
+
+        // Mock bulk update API - this is called via bulkUpdateWalletShare
+        nock(bgUrl)
+          .put('/api/v2/walletshares/update', (body: any) => {
+            if (!body.shares || body.shares.length !== 1) {
+              return false;
+            }
+            const share = body.shares[0];
+            return (
+              share.walletShareId === shareId &&
+              share.status === 'accept' &&
+              share.pub === keychain.pub &&
+              share.encryptedPrv === encryptedPrv
+            );
+          })
+          .reply(200, {
+            acceptedWalletShares: [{ walletShareId: shareId }],
+            rejectedWalletShares: [],
+            walletShareUpdateErrors: [],
+          });
+
+        const keychainsStub = sandbox.stub(wallets.baseCoin.keychains(), 'create').resolves(keychain);
+        const encryptStub = sandbox.stub(bitgo, 'encrypt').returns(encryptedPrv);
+
+        // Note: bulkAcceptShare filters for shares WITH keychains, but userMultiKeyRotationRequired
+        // shares don't have keychains, so they go through a different path
+        // We need to stub the processAcceptShare path or use bulkUpdateWalletShare directly
+        // For this test, we'll use bulkUpdateWalletShare which calls processAcceptShare internally
+        const result = await wallets.bulkUpdateWalletShare({
+          shares: [{ walletShareId: shareId, status: 'accept' }],
+          userLoginPassword: userPassword,
+        });
+
+        should.equal(result.acceptedWalletShares.length, 1);
+        should.deepEqual(result.acceptedWalletShares[0], { walletShareId: 'test_multi_key_bulk_1' });
+        should.equal(keychainsStub.calledOnce, true);
+        should.equal(encryptStub.calledWith({ input: keychain.prv, password: userPassword }), true);
+      });
+    });
+
     it('should share a wallet to viewer', async function () {
       const shareId = '12311';
 

modules/sdk-core/src/bitgo/wallet/iWallet.ts

@@ -658,6 +658,7 @@ export interface WalletShare {
   message?: string;
   pendingApprovalId?: string;
   keychainOverrideRequired?: boolean;
+  userMultiKeyRotationRequired?: boolean;
   isUMSInitiated?: boolean;
   keychain?: BulkWalletShareKeychain;
 }

modules/sdk-core/src/bitgo/wallet/iWallets.ts

@@ -120,6 +120,7 @@ export interface UpdateShareOptions {
   keyId?: string;
   signature?: string;
   payload?: string;
+  pub?: string;
 }
 
 export interface AcceptShareOptions {
@@ -156,6 +157,7 @@ export interface BulkUpdateWalletShareOptionsRequest {
   keyId?: string;
   signature?: string;
   payload?: string;
+  pub?: string;
 }
 
 export interface BulkUpdateWalletShareResponse {

modules/sdk-core/src/bitgo/wallet/wallets.ts

@@ -927,6 +927,29 @@ export class Wallets implements IWallets {
       }
       return response;
     }
+    // Multi-user-key case: requires user to provide their own public key in addition to the encrypted private key
+    if (walletShare.userMultiKeyRotationRequired) {
+      if (_.isUndefined(params.userPassword)) {
+        throw new Error('userPassword param must be provided to generate user keychain');
+      }
+
+      const walletKeychain = await this.baseCoin.keychains().create();
+      const encryptedPrv = this.bitgo.encrypt({
+        password: params.userPassword,
+        input: walletKeychain.prv,
+      });
+
+      const updateParams: UpdateShareOptions = {
+        walletShareId: params.walletShareId,
+        state: 'accepted',
+        encryptedPrv: encryptedPrv,
+        pub: walletKeychain.pub,
+      };
+
+      // Note: Unlike keychainOverrideRequired, we do NOT reshare the wallet with spenders
+      // This is a key difference - multi-user-key wallets don't require reshare
+      return this.updateShare(updateParams);
+    }
     // Return right away if there is no keychain to decrypt, or if explicit encryptedPrv was provided
     if (!walletShare.keychain || !walletShare.keychain.encryptedPrv || encryptedPrv) {
       return this.updateShare({
@@ -1292,6 +1315,28 @@ export class Wallets implements IWallets {
       ];
     }
 
+    // Multi-user-key case: requires user to provide their own public key
+    if (walletShare.userMultiKeyRotationRequired) {
+      if (!userLoginPassword) {
+        throw new Error('userLoginPassword param must be provided to generate user keychain');
+      }
+
+      const walletKeychain = await this.baseCoin.keychains().create();
+      const encryptedPrv = this.bitgo.encrypt({
+        password: userLoginPassword,
+        input: walletKeychain.prv,
+      });
+
+      return [
+        {
+          walletShareId,
+          status: 'accept' as const,
+          encryptedPrv: encryptedPrv,
+          pub: walletKeychain.pub,
+        },
+      ];
+    }
+
     // Return right away if there is no keychain to decrypt
     if (!walletShare.keychain || !walletShare.keychain.encryptedPrv) {
       return [