feat: add encryptAsync to encrypt.ts

[bdesoky]

Ticket: WCN-715

This pull request introduces an asynchronous encryption function, encryptAsync, that supports both v1 (SJCL) and v2 (Argon2id + AES-256-GCM) encryption methods, and updates the BitGoAPI and tests to use this new function. The main goal is to unify and modernize encryption handling, allowing for async operations and easier support for multiple encryption versions.

Key changes:

Encryption Enhancements

• Added a new encryptAsync function in encrypt.ts that dispatches to v1 or v2 encryption based on the encryptionVersion parameter, supporting both legacy and modern encryption methods.
• Updated the BitGoAPI's encrypt method to use encryptAsync, ensuring all encryption now supports asynchronous operation and both encryption versions.
• Updated imports across files to include encryptAsync, and removed unused encryptV2 import from bitgoAPI.ts. [1] [2]

Testing Improvements

• Added comprehensive unit tests for encryptAsync in encrypt.ts, covering dispatch logic, option forwarding (e.g., adata, salt, iv), deterministic output, and error handling for invalid parameters.
• Updated test imports to include encryptAsync and ensure all encryption/decryption methods are consistently tested.

[linear-code]

WCN-715

[bdesoky]

@claude

[github-actions]

Claude finished @bdesoky's task —— View job

---

Code Review for PR #8921: feat: add encryptAsync to encrypt.ts

Todo List:

• Read and analyze the changed files
• Review the encryptAsync implementation
• Check BitGoAPI integration
• Examine test coverage and quality
• Provide comprehensive review feedback

Summary

This PR successfully introduces encryptAsync, a unified asynchronous encryption function that supports both v1 (SJCL) and v2 (Argon2id + AES-256-GCM) encryption methods. The implementation is clean, well-tested, and maintains backward compatibility while preparing for future encryption improvements.

✅ Positive Aspects

Excellent API Design

• Clean dispatch pattern: encryptAsync elegantly routes to v1 or v2 based on encryptionVersion parameter
• Backward compatibility: Defaults to v1 encryption, matching existing encrypt() behavior
• Future-ready: Provides migration path to v2 encryption without breaking changes

Implementation Quality

• Consistent error handling: Properly validates salt (8 bytes) and iv (16 bytes) lengths
• Option forwarding: Correctly passes through adata, salt, and iv options to underlying functions
• Import cleanup: Removes unused encryptV2 import from bitgoAPI.ts and adds encryptAsync

Comprehensive Testing

• Thorough coverage: Tests dispatch logic, option forwarding, error handling, and deterministic output
• Edge cases: Validates salt/iv length requirements and various encryption version scenarios
• Integration tests: Includes BitGoAPI-level tests ensuring proper API integration

Code Organization

• Logical placement: encryptAsync positioned appropriately in encrypt.ts after the v1 encrypt function
• Clear documentation: Function comments clearly explain purpose and default behavior
• Clean integration: BitGoAPI properly updated to use the new async function

🔍 Areas for Improvement

Minor Technical Considerations

1. Error Message Consistency: encrypt.ts:54-55

   • Current: Routes to encryptV2 without passing salt/iv options that are valid for v1
   • Consider: Document or validate that v2 doesn't use these options, or pass them if supported

2. Type Safety Enhancement: encrypt.ts:52

   // Consider making encryptionVersion required when salt/iv provided
   // to prevent confusion about which encryption method will be used
   options?: { 
     salt?: Buffer; 
     iv?: Buffer; 
     adata?: string; 
     encryptionVersion?: 1 | 2 
   }

3. BitGoAPI Integration: bitgoAPI.ts:855-858

   • The API now uses encryptAsync internally, which is good
   • Consider updating the JSDoc comment to mention async behavior

Documentation Suggestions

1. Migration Guide: Consider adding examples in comments showing how to migrate from sync to async encryption
2. Performance Notes: Document that v2 encryption is computationally more expensive (Argon2id)
3. Security Context: Brief mention of why v2 is preferred for new implementations

📊 Test Coverage Assessment

Excellent test coverage with comprehensive scenarios:

• ✅ Default v1 dispatch behavior
• ✅ Explicit v1/v2 routing via encryptionVersion
• ✅ Option forwarding (adata, salt, iv)
• ✅ Error handling (invalid salt/iv lengths)
• ✅ Deterministic output with fixed salt/iv
• ✅ BitGoAPI integration tests
• ✅ Round-trip compatibility with existing decrypt functions

🏗️ Architecture Impact

This change represents a well-designed evolutionary step:

• Non-breaking: Existing code continues to work unchanged
• Extensible: Easy to add new encryption versions in the future
• Unified Interface: Reduces complexity for consumers who need async encryption
• Migration Ready: Provides clear path for moving to stronger v2 encryption

🔒 Security Considerations

• Maintains Security: No reduction in security strength
• Future-Proofs: Enables adoption of stronger Argon2id-based v2 encryption
• Proper Validation: Maintains input validation for cryptographic parameters

Overall Assessment: APPROVED ✅

This is a high-quality implementation that:

1. ✅ Maintains backward compatibility
2. ✅ Provides clean async encryption interface
3. ✅ Includes comprehensive test coverage
4. ✅ Uses appropriate error handling
5. ✅ Follows existing code patterns and conventions
6. ✅ Prepares codebase for stronger encryption migration

The code is ready for merge with only minor documentation suggestions for future consideration.

---

CI Status: 🟡 2 workflows in progress (BitGo SDK | Audit API Spec)

Job run link | Branch: WCN-715

[vinhkhangtieu]

use encrypt async