feat: add verification flow for v4

[MohammedRyaan786]

TICKET: CAAS-819

This pull request introduces significant improvements to authentication version handling and response verification in the BitGo Express and SDK-API modules. The main focus is on normalizing and enforcing the authVersion configuration, adding stricter validation and error handling for v4 authentication, and refactoring response HMAC verification logic to be more robust and version-aware. Comprehensive tests have also been added to ensure correct behavior.

Authentication version handling and enforcement:

• Added a parseAuthVersion function to normalize authVersion values to 2, 3, or 4, defaulting or clamping invalid values to 2, and updated config parsing to use this function. The Config interface now strictly types authVersion as 2 | 3 | 4. [1] [2] [3] [4]
• Updated the BitGo Express middleware (prepareBitGo) to enforce v4 authentication requirements: if authVersion=4 and an access token is present, the Access-Key-Id header must be provided, otherwise the request is rejected with a clear error message. The middleware now passes authVersion and tokenId to the SDK. [1] [2] [3]
• The SDK-API's BitGoAPI class now stores the tokenId (MongoDB ObjectId) for v4 tokens, enabling correct v4 authentication. [1] [2]

Response HMAC verification improvements:

• Refactored the verifyResponse function in the SDK-API to cleanly separate v2/v3 and v4 logic, using new helpers verifyV4ResponseHeaders and verifyV2V3ResponseHeaders. The v4 logic now strictly requires signature headers on successful responses and provides detailed error context.
• Added and updated imports and types to support the new verification logic, including new interfaces for v4 verification and HMAC error details. [1] [2] [3] [4] [5]

Testing and validation:

• Added comprehensive unit tests for authVersion parsing, covering correct values, clamping of invalid values, precedence of command-line arguments over environment variables, and defaulting behavior.

These changes improve security, reliability, and clarity around authentication and response verification for all supported authentication versions.

---

Authentication version normalization and enforcement

• Added parseAuthVersion to strictly normalize and clamp authVersion to 2, 3, or 4, and updated config parsing and typing to enforce this. [1] [2] [3] [4]
• BitGo Express middleware now enforces that v4 requests must include the Access-Key-Id header when an access token is present, rejecting non-compliant requests with a clear error. [1] [2] [3]
• SDK-API's BitGoAPI class now stores the tokenId for v4 tokens, enabling correct v4 authentication. [1] [2]

Response verification refactor

• Refactored verifyResponse in SDK-API to use version-specific helpers for v2/v3 and v4, with stricter enforcement and detailed error context for v4 HMAC verification.
• Updated and added relevant imports and types to support the new verification logic. [1] [2] [3] [4] [5]

Testing

• Added comprehensive unit tests to verify correct parsing and precedence of authVersion configuration.

[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.

[arvind-bg]

Will there be any impact on the express API responses?

[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 7 out of 8 changed files in this pull request and generated 1 comment.

---

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

[Copilot]

Pull request overview

Copilot reviewed 7 out of 8 changed files in this pull request and generated 5 comments.

Comments suppressed due to low confidence (1)

modules/sdk-api/src/types.ts:40

• For v4, requestPatch enforces that accessToken and tokenId are both present, but the public option types still make tokenId optional (BitGoAPIOptions.tokenId? and AccessTokenOptions.tokenId?). This mismatch means v4 callers can compile successfully and only fail at runtime. Consider making the types enforce this via a discriminated union on authVersion (e.g., when authVersion: 4, require both accessToken and tokenId).

export interface BitGoAPIOptions {
  accessToken?: string;
  /** MongoDB _id of the access token. Required for v4 authentication (used as the Bearer value). */
  tokenId?: string;
  authVersion?: 2 | 3 | 4;
  clientConstants?:
    | Record<string, any>
    | {
        constants: Record<string, any>;

---

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

[Copilot]

Pull request overview

Copilot reviewed 7 out of 8 changed files in this pull request and generated 4 comments.

---

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

[Copilot]

Pull request overview

Copilot reviewed 8 out of 9 changed files in this pull request and generated 1 comment.

---

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

[Copilot]

Pull request overview

Copilot reviewed 8 out of 9 changed files in this pull request and generated 3 comments.

---

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

[CapnMigraine]

are we using v2x to identify v4 tokens instead of v4?

[MohammedRyaan786]

No. We are not using v2x'to identify v4 tokens. The logic is:

1 If authVersion === 4, we skip the above entire v1 fallback check.
2. The v2x check only applies to v2/v3 tokens to decide whether to fall back to v1.