Merge pull request #8339 from BitGo/aloe/fixHmacStrategyInit

bitgoAaron · web-flow · commit 826061a12407 · 2026-03-25T08:37:01.000-07:00
fix: sdk hmac strategy init &amp; clear
diff --git a/modules/sdk-api/src/bitgoAPI.ts b/modules/sdk-api/src/bitgoAPI.ts
@@ -1046,6 +1046,14 @@ export class BitGoAPI implements BitGoBase {
         response.body.access_token = this._token;
       }
 
+      // Sync the token into the strategy so that strategies which manage their
+      // own key material (e.g. WebCryptoHmacStrategy) can sign the subsequent
+      // ensureUserEcdhKeychainIsCreated requests.  Must be awaited — the call
+      // may perform async key derivation (crypto.subtle.importKey).
+      if (this._token) {
+        await this._hmacAuthStrategy.setToken?.(this._token);
+      }
+
       const userSettings = params.ensureEcdhKeychain ? await this.ensureUserEcdhKeychainIsCreated(password) : undefined;
       if (userSettings?.ecdhKeychain) {
         response.body.user.ecdhKeychain = userSettings.ecdhKeychain;
@@ -1089,6 +1097,7 @@ export class BitGoAPI implements BitGoBase {
       if (body.access_token) {
         this._token = body.access_token;
         response.body.access_token = body.access_token;
+        await this._hmacAuthStrategy.setToken?.(body.access_token);
       } else {
         throw new Error('Failed to login. Please contact support@bitgo.com');
       }
@@ -1194,6 +1203,11 @@ export class BitGoAPI implements BitGoBase {
     this._ecdhXprv = undefined;
   }
 
+  async clearAsync(): Promise<void> {
+    this.clear();
+    await this._hmacAuthStrategy.clearToken?.();
+  }
+
   /**
    * Use refresh token to get new access token.
    * If the refresh token is null/defined, then we use the stored token from auth
@@ -1221,6 +1235,7 @@ export class BitGoAPI implements BitGoBase {
       .result();
     this._token = body.access_token;
     this._refreshToken = body.refresh_token;
+    await this._hmacAuthStrategy?.setToken?.(body.access_token);
     return body;
   }
 
@@ -1945,6 +1960,9 @@ export class BitGoAPI implements BitGoBase {
 
     this._token = body.access_token;
     this._refreshToken = body.refresh_token;
+
+    await this._hmacAuthStrategy?.setToken?.(body.access_token);
+
     this._user = await this.me();
     return body;
   }
diff --git a/modules/sdk-api/test/unit/bitgoAPI.ts b/modules/sdk-api/test/unit/bitgoAPI.ts
@@ -3,6 +3,7 @@ import { BitGoAPI } from '../../src/bitgoAPI';
 import { ProxyAgent } from 'proxy-agent';
 import * as sinon from 'sinon';
 import nock from 'nock';
+import type { IHmacAuthStrategy } from '@bitgo/sdk-hmac';
 
 describe('Constructor', function () {
   describe('cookiesPropagationEnabled argument', function () {
@@ -481,6 +482,221 @@ describe('Constructor', function () {
     });
   });
 
+  describe('hmacAuthStrategy token lifecycle', function () {
+    const ROOT = 'https://app.example.local';
+
+    // Builds a mock strategy whose setToken / clearToken are sinon stubs.
+    function makeStrategy(overrides: Partial<IHmacAuthStrategy> = {}): {
+      strategy: IHmacAuthStrategy;
+      setTokenStub: sinon.SinonStub;
+      clearTokenStub: sinon.SinonStub;
+    } {
+      const setTokenStub = sinon.stub().resolves();
+      const clearTokenStub = sinon.stub().resolves();
+      const strategy: IHmacAuthStrategy = {
+        calculateRequestHeaders: sinon.stub().resolves({ hmac: 'hmac', timestamp: 1, tokenHash: 'hash' }),
+        verifyResponse: sinon.stub().resolves({
+          isValid: true,
+          expectedHmac: 'hmac',
+          signatureSubject: '',
+          isInResponseValidityWindow: true,
+          verificationTime: Date.now(),
+        }),
+        calculateHMAC: sinon.stub().resolves('hashed-pw'),
+        setToken: setTokenStub,
+        clearToken: clearTokenStub,
+        ...overrides,
+      };
+      return { strategy, setTokenStub, clearTokenStub };
+    }
+
+    afterEach(function () {
+      nock.cleanAll();
+      sinon.restore();
+    });
+
+    describe('authenticate()', function () {
+      it('calls setToken with the access_token received from the server', async function () {
+        const { strategy, setTokenStub } = makeStrategy();
+        const bitgo = new BitGoAPI({ env: 'custom', customRootURI: ROOT, hmacAuthStrategy: strategy });
+
+        nock(ROOT)
+          .post('/api/auth/v1/session')
+          .reply(200, {
+            user: { username: 'test@example.com' },
+            access_token: 'v2xmyaccesstoken',
+          });
+
+        await bitgo.authenticate({ username: 'test@example.com', password: 'hunter2' });
+
+        setTokenStub.calledOnce.should.be.true();
+        setTokenStub.firstCall.args[0].should.equal('v2xmyaccesstoken');
+      });
+
+      it('awaits setToken before making ensureEcdhKeychain requests', async function () {
+        // This is the core regression test: if setToken is not awaited, the
+        // strategy's key material won't be ready before calculateRequestHeaders
+        // is called for the GET /user/settings request, and it would throw.
+        let keyReady = false;
+        const { strategy } = makeStrategy({
+          setToken: sinon.stub().callsFake(async () => {
+            // Simulate non-trivial async key derivation (like crypto.subtle.importKey).
+            await new Promise<void>((resolve) => setImmediate(resolve));
+            keyReady = true;
+          }),
+          calculateRequestHeaders: sinon.stub().callsFake(async () => {
+            if (!keyReady) {
+              throw new Error('No token available. Call setToken() or restoreToken() first.');
+            }
+            return { hmac: 'hmac', timestamp: Date.now(), tokenHash: 'hash' };
+          }),
+        });
+        const bitgo = new BitGoAPI({ env: 'custom', customRootURI: ROOT, hmacAuthStrategy: strategy });
+
+        nock(ROOT)
+          .post('/api/auth/v1/session')
+          .reply(200, {
+            user: { username: 'test@example.com' },
+            access_token: 'v2xmytoken',
+          });
+        // The GET /user/settings request made by ensureUserEcdhKeychainIsCreated
+        // must succeed — it would throw if setToken wasn't awaited first.
+        nock(ROOT)
+          .get('/api/v1/user/settings')
+          .reply(200, {
+            settings: { ecdhKeychain: 'xpub123' },
+          });
+
+        await bitgo.authenticate({
+          username: 'test@example.com',
+          password: 'hunter2',
+          ensureEcdhKeychain: true,
+        });
+
+        keyReady.should.be.true();
+      });
+    });
+
+    describe('authenticateWithPasskey()', function () {
+      const validPasskey = JSON.stringify({
+        id: 'credential-id',
+        rawId: 'raw-id',
+        type: 'public-key',
+        response: {
+          authenticatorData: 'auth-data',
+          clientDataJSON: 'client-data',
+          signature: 'sig',
+          userHandle: 'user-handle-123',
+        },
+      });
+
+      it('calls setToken with the access_token received from the server', async function () {
+        const { strategy, setTokenStub } = makeStrategy();
+        const bitgo = new BitGoAPI({ env: 'custom', customRootURI: ROOT, hmacAuthStrategy: strategy });
+
+        nock(ROOT)
+          .post('/api/auth/v1/session')
+          .reply(200, {
+            user: { username: 'test@example.com' },
+            access_token: 'v2xpasskeytoken',
+          });
+
+        await bitgo.authenticateWithPasskey(validPasskey);
+
+        setTokenStub.calledOnce.should.be.true();
+        setTokenStub.firstCall.args[0].should.equal('v2xpasskeytoken');
+      });
+    });
+
+    describe('clearAsync()', function () {
+      it('clears _token and calls clearToken on the strategy', async function () {
+        const { strategy, clearTokenStub } = makeStrategy();
+        const bitgo = new BitGoAPI({ env: 'custom', customRootURI: ROOT, hmacAuthStrategy: strategy });
+
+        bitgo.authenticateWithAccessToken({ accessToken: 'v2xsometoken' });
+        (bitgo as any)._token.should.equal('v2xsometoken');
+
+        await bitgo.clearAsync();
+
+        ((bitgo as any)._token === undefined).should.be.true();
+        clearTokenStub.calledOnce.should.be.true();
+      });
+    });
+
+    describe('refreshToken()', function () {
+      it('calls setToken with the new access_token from the OAuth response', async function () {
+        const { strategy, setTokenStub } = makeStrategy();
+        const bitgo = new BitGoAPI({
+          env: 'custom',
+          customRootURI: ROOT,
+          hmacAuthStrategy: strategy,
+          clientId: 'client-id',
+          clientSecret: 'client-secret',
+        });
+        (bitgo as any)._refreshToken = 'old-refresh-token';
+
+        nock(ROOT).post('/oauth/token').reply(200, {
+          access_token: 'v2xnewtoken',
+          refresh_token: 'new-refresh-token',
+        });
+
+        await bitgo.refreshToken();
+
+        setTokenStub.calledOnce.should.be.true();
+        setTokenStub.firstCall.args[0].should.equal('v2xnewtoken');
+      });
+    });
+
+    describe('authenticateWithAuthCode()', function () {
+      it('calls setToken with the access_token from the OAuth response', async function () {
+        const { strategy, setTokenStub } = makeStrategy();
+        const bitgo = new BitGoAPI({
+          env: 'custom',
+          customRootURI: ROOT,
+          hmacAuthStrategy: strategy,
+          clientId: 'client-id',
+          clientSecret: 'client-secret',
+        });
+
+        nock(ROOT).post('/oauth/token').reply(200, {
+          access_token: 'v2xauthcodetoken',
+          refresh_token: 'refresh-token',
+        });
+        // authenticateWithAuthCode calls this.me() after setting the token
+        nock(ROOT)
+          .get('/api/v1/user/me')
+          .reply(200, {
+            user: { username: 'test@example.com' },
+          });
+
+        await bitgo.authenticateWithAuthCode({ authCode: 'my-auth-code' });
+
+        setTokenStub.calledOnce.should.be.true();
+        setTokenStub.firstCall.args[0].should.equal('v2xauthcodetoken');
+      });
+    });
+
+    describe('sync token-setting methods', function () {
+      it('authenticateWithAccessToken does not call setToken (synchronous — caller must invoke setToken on the strategy manually)', function () {
+        const { strategy, setTokenStub } = makeStrategy();
+        const bitgo = new BitGoAPI({ env: 'custom', customRootURI: ROOT, hmacAuthStrategy: strategy });
+
+        bitgo.authenticateWithAccessToken({ accessToken: 'v2xsynctoken' });
+
+        setTokenStub.called.should.be.false();
+      });
+
+      it('fromJSON does not call setToken (synchronous — caller must invoke setToken on the strategy manually)', function () {
+        const { strategy, setTokenStub } = makeStrategy();
+        const bitgo = new BitGoAPI({ env: 'custom', customRootURI: ROOT, hmacAuthStrategy: strategy });
+
+        (bitgo as any).fromJSON({ user: { username: 'test@example.com' }, token: 'v2xjsontoken' });
+
+        setTokenStub.called.should.be.false();
+      });
+    });
+  });
+
   describe('constants parameter', function () {
     it('should allow passing constants via options and expose via fetchConstants', async function () {
       const bitgo = new BitGoAPI({
diff --git a/modules/sdk-hmac/src/types.ts b/modules/sdk-hmac/src/types.ts
@@ -140,6 +140,17 @@ export interface IHmacAuthStrategy {
    * to the strategy even if no raw token string is available.
    */
   isAuthenticated?(): boolean;
+
+  /**
+   * Optional token initialization & destruction methods.
+   *
+   * Strategies that read the token directly from request params
+   * (e.g. DefaultHmacAuthStrategy) may leave this unimplemented.
+   *
+   * Must be awaited — implementations may perform async key derivation.
+   */
+  setToken?(token: string): Promise<void>;
+  clearToken?(): Promise<void>;
 }
 
 /**
diff --git a/modules/web-demo/src/components/WebCryptoAuth/index.tsx b/modules/web-demo/src/components/WebCryptoAuth/index.tsx
@@ -237,6 +237,7 @@ const WebCryptoAuth = () => {
         username,
         password,
         otp,
+        ensureEcdhKeychain: true,
       });
       log('Authentication successful.');
 
