feat: add verification flow for v4

[MohammedRyaan786]

TICKET: CAAS-819

This pull request introduces support for API authentication version 4 (v4) in the BitGo SDK, focusing on robust HMAC request/response signing and verification. It adds new logic for handling v4-specific authentication tokens, headers, and HMAC validation, while maintaining compatibility with previous authentication versions. The changes also modularize and expose several new v4 HMAC utilities for debugging and testing.

v4 Authentication and HMAC Handling:

• Added support for v4 authentication, including new request headers (X-Request-Timestamp, X-Auth-Request-Id, X-Content-SHA256, X-Signature) and logic to use a separate tokenId (MongoDB _id) as the bearer token, distinct from the HMAC key. The SDK now requires both accessToken and accessTokenId for v4, and stores/returns both where appropriate. [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13] [14] [15]

• Updated the HMAC verification logic to branch for v4: constructs the v4 preimage, hashes the body as raw bytes, and verifies the response using new v4-specific SDK HMAC methods. Error handling and debug logging were improved to provide detailed context on HMAC mismatches and response validity window violations. [1] [2]

New v4 HMAC Utility Methods:

• Exposed new methods on BitGoAPI for v4 HMAC operations: calculateBodyHash, calculateV4Preimage, calculateV4RequestHmac, calculateV4RequestHeaders, and calculateV4ResponsePreimage, all delegated to the underlying @bitgo/sdk-hmac module.

Type and Import Updates:

• Added new v4-related types and imports throughout the codebase for strong typing and clarity, including V4RequestHeaders, VerifyV4ResponseInfo, and related options. [1] [2] [3] [4]

Logging and Compatibility Improvements:

• Improved debug logging for all authentication versions, ensuring that only safe prefixes of tokens are logged and updating string slicing to avoid deprecated methods. [1] [2] [3]

These changes collectively enable secure, standards-compliant v4 HMAC authentication and response verification in the SDK, while maintaining backward compatibility with existing API versions.

[Copilot]

Pull request overview

This PR adds v4 authentication support to the BitGo SDK, implementing a new HMAC-based authentication scheme that uses newline-separated preimages with body hashing and UUID-based request tracking.

Changes:

• Added v4 authentication support with new HMAC scheme using newline-separated preimage format, seconds-based timestamps, SHA256 body hashing, and UUID request IDs
• Extended type system to support v4 auth including new request/response types, accessTokenId field, and v4-specific request metadata
• Implemented comprehensive test coverage (1000+ lines) covering token lifecycle, request/response verification, backward compatibility, and security edge cases

Reviewed changes

Copilot reviewed 5 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
types/superagent/index.d.ts	Added v4 auth metadata fields (v4AuthRequestId, v4Method, v4PathWithQuery) to superagent Request interface
modules/sdk-hmac/src/types.ts	Extended AuthVersion type to include version 4
modules/sdk-api/src/types.ts	Exported v4-specific types and added accessTokenId field to BitGoAPIOptions, AccessTokenOptions, and BitGoJson
modules/sdk-api/test/unit/v4auth.ts	Comprehensive test suite covering v4 auth lifecycle, request/response verification, HMAC calculation, and backward compatibility
modules/sdk-api/src/bitgoAPI.ts	Implemented v4 auth flow including tokenId management, v4 request header generation, and v4 helper methods
modules/sdk-api/src/api.ts	Updated response verification to handle v4 auth with proper HMAC and timestamp validation

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 6 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 6 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.