feat(sdk-api): implement V4 token issuance flow

Ticket: CAAS-783

Author: arvind-bg

modules/sdk-api/src/bitgoAPI.ts

@@ -123,6 +123,7 @@ export class BitGoAPI implements BitGoBase {
   protected _extensionKey?: ECPairInterface;
   protected _reqId?: IRequestTracer;
   protected _token?: string;
+  protected _tokenId?: string; // V4: separate token identifier
   protected _version = pjson.version;
   protected _userAgent?: string;
   protected _ecdhXprv?: string;
@@ -735,6 +736,7 @@ export class BitGoAPI implements BitGoBase {
     return {
       user: this._user,
       token: this._token,
+      tokenId: this._tokenId,
       extensionKey: this._extensionKey ? this._extensionKey.toWIF() : undefined,
       ecdhXprv: this._ecdhXprv,
     };
@@ -758,6 +760,7 @@ export class BitGoAPI implements BitGoBase {
   fromJSON(json: BitGoJson): void {
     this._user = json.user;
     this._token = json.token;
+    this._tokenId = json.tokenId;
     this._ecdhXprv = json.ecdhXprv;
     if (json.extensionKey) {
       const network = common.Environments[this.getEnv()].network;
@@ -980,6 +983,11 @@ export class BitGoAPI implements BitGoBase {
         this._token = responseDetails.token;
         this._ecdhXprv = responseDetails.ecdhXprv;
 
+        // V4: store separate token identifier
+        if (this._authVersion === 4 && body.id) {
+          this._tokenId = body.id;
+        }
+
         // verify the response's authenticity
         verifyResponse(this, responseDetails.token, 'post', request, response, this._authVersion);
 
@@ -1131,6 +1139,7 @@ export class BitGoAPI implements BitGoBase {
     // TODO: are there any other fields which should be cleared?
     this._user = undefined;
     this._token = undefined;
+    this._tokenId = undefined;
     this._refreshToken = undefined;
     this._ecdhXprv = undefined;
   }
@@ -1271,9 +1280,18 @@ export class BitGoAPI implements BitGoBase {
       // verify the authenticity of the server's response before proceeding any further
       verifyResponse(this, this._token, 'post', request, response, this._authVersion);
 
+      // Decrypt token using ECDH (same for V2/V3/V4)
       const responseDetails = this.handleTokenIssuance(response.body);
       response.body.token = responseDetails.token;
 
+      // V4: Store separate tokenId alongside signing key
+      if (this._authVersion === 4) {
+        if (!response.body.id) {
+          throw new Error('Invalid V4 token issuance response: missing id field');
+        }
+        response.body.tokenId = response.body.id;
+      }
+
       return handleResponseResult<AddAccessTokenResponse>()(response);
     } catch (e) {
       handleResponseError(e);

modules/sdk-api/src/types.ts

@@ -24,7 +24,7 @@ export {
 } from '@bitgo/sdk-hmac';
 export interface BitGoAPIOptions {
   accessToken?: string;
-  authVersion?: 2 | 3;
+  authVersion?: 2 | 3 | 4;
   clientConstants?:
     | Record<string, any>
     | {
@@ -137,6 +137,7 @@ export interface User {
 export interface BitGoJson {
   user?: User;
   token?: string;
+  tokenId?: string; // V4: separate token identifier
   extensionKey?: string;
   ecdhXprv?: string;
 }
@@ -149,6 +150,7 @@ export interface TokenIssuanceResponse {
   derivationPath: string;
   encryptedToken: string;
   encryptedECDHXprv?: string;
+  id?: string; // V4: token identifier
 }
 
 export interface TokenIssuance {
@@ -189,6 +191,7 @@ export interface AddAccessTokenResponse {
   encryptedToken: string;
   derivationPath: string;
   token: string;
+  tokenId?: string; // V4: separate token identifier
   enterprise?: string;
   extensionAddress?: string;
 }