Merge pull request #198 from BitGo/WCN-397

pranishnepal · web-flow · commit ade43bec1f0e · 2026-05-05T11:58:47.000-04:00
chore: add SigningMode config and refactor KeyProviderClient HTTP layer
diff --git a/README.md b/README.md
@@ -169,6 +169,7 @@ curl -X POST http://localhost:3081/ping/advancedWalletManager
 | ------------------------------ | ---------------------------------- | ------- | -------- |
 | `ADVANCED_WALLET_MANAGER_PORT` | Port to listen on                  | `3080`  | ❌       |
 | `KEY_PROVIDER_URL`             | URL to your key provider API implementation | -       | ✅       |
+| `SIGNING_MODE`                 | Signing mode (`local` or `external`). Use `external` to delegate key generation and signing to your key provider — the private key never leaves the HSM. | `local` | ❌       |
 
 > **Note:** The `KEY_PROVIDER_URL` points to your implementation of the key provider API interface. You must implement this interface to connect your KMS/HSM. See [Prerequisites](#prerequisites) for the specification and examples.
 
diff --git a/docker-compose.yml b/docker-compose.yml
@@ -43,6 +43,7 @@ services:
       # Logging and debug
       - HTTP_LOGFILE=logs/http-access.log
       - RECOVERY_MODE=true
+      # Default to local signing mode 
       - NODE_ENV=production
       - LOG_LEVEL=info
     restart: always
diff --git a/src/__tests__/api/advancedWalletManager/keyProviderClient.test.ts b/src/__tests__/api/advancedWalletManager/keyProviderClient.test.ts
@@ -1,4 +1,4 @@
-import { AppMode, AdvancedWalletManagerConfig, TlsMode } from '../../../initConfig';
+import { AppMode, AdvancedWalletManagerConfig, TlsMode, SigningMode } from '../../../initConfig';
 import { app as expressApp } from '../../../advancedWalletManagerApp';
 
 import express from 'express';
@@ -24,6 +24,7 @@ describe('postMpcV2Key', () => {
     // app config
     cfg = {
       appMode: AppMode.ADVANCED_WALLET_MANAGER,
+      signingMode: SigningMode.LOCAL,
       port: 0, // Let OS assign a free port
       bind: 'localhost',
       timeout: 60000,
diff --git a/src/__tests__/api/advancedWalletManager/mpcFinalize.test.ts b/src/__tests__/api/advancedWalletManager/mpcFinalize.test.ts
@@ -3,7 +3,7 @@ import 'should';
 import * as sinon from 'sinon';
 import * as express from 'express';
 import * as request from 'supertest';
-import { AppMode, AdvancedWalletManagerConfig, TlsMode } from '../../../shared/types';
+import { AppMode, AdvancedWalletManagerConfig, TlsMode, SigningMode } from '../../../shared/types';
 import { app as enclavedApp } from '../../../advancedWalletManagerApp';
 import { BitGoAPI } from '@bitgo-beta/sdk-api';
 import * as middleware from '../../../shared/middleware';
@@ -23,6 +23,7 @@ describe('MPC Finalize', () => {
     // app config
     cfg = {
       appMode: AppMode.ADVANCED_WALLET_MANAGER,
+      signingMode: SigningMode.LOCAL,
       port: 0, // Let OS assign a free port
       bind: 'localhost',
       timeout: 60000,
diff --git a/src/__tests__/api/advancedWalletManager/mpcInitialize.test.ts b/src/__tests__/api/advancedWalletManager/mpcInitialize.test.ts
@@ -3,7 +3,7 @@ import 'should';
 import * as sinon from 'sinon';
 import * as express from 'express';
 import * as request from 'supertest';
-import { AppMode, AdvancedWalletManagerConfig, TlsMode } from '../../../shared/types';
+import { AppMode, AdvancedWalletManagerConfig, TlsMode, SigningMode } from '../../../shared/types';
 import { app as enclavedApp } from '../../../advancedWalletManagerApp';
 
 describe('MPC Initialize', () => {
@@ -24,6 +24,7 @@ describe('MPC Initialize', () => {
     // app config
     cfg = {
       appMode: AppMode.ADVANCED_WALLET_MANAGER,
+      signingMode: SigningMode.LOCAL,
       port: 0, // Let OS assign a free port
       bind: 'localhost',
       timeout: 60000,
diff --git a/src/__tests__/api/advancedWalletManager/nonRecovery.test.ts b/src/__tests__/api/advancedWalletManager/nonRecovery.test.ts
@@ -2,7 +2,7 @@ import 'should';
 import * as request from 'supertest';
 import nock from 'nock';
 import { app as expressApp } from '../../../advancedWalletManagerApp';
-import { AppMode, AdvancedWalletManagerConfig, TlsMode } from '../../../shared/types';
+import { AppMode, AdvancedWalletManagerConfig, TlsMode, SigningMode } from '../../../shared/types';
 import sinon from 'sinon';
 import * as middleware from '../../../shared/middleware';
 import { BitGoRequest } from '../../../types/request';
@@ -13,6 +13,7 @@ describe('Non Recovery', () => {
   const coin = 'tbtc';
   const config: AdvancedWalletManagerConfig = {
     appMode: AppMode.ADVANCED_WALLET_MANAGER,
+    signingMode: SigningMode.LOCAL,
     port: 0,
     bind: 'localhost',
     timeout: 60000,
diff --git a/src/__tests__/api/advancedWalletManager/postIndependentKey.test.ts b/src/__tests__/api/advancedWalletManager/postIndependentKey.test.ts
@@ -3,7 +3,7 @@ import 'should';
 import * as request from 'supertest';
 import nock from 'nock';
 import { app as advancedWalletManagerApp } from '../../../advancedWalletManagerApp';
-import { AppMode, AdvancedWalletManagerConfig, TlsMode } from '../../../shared/types';
+import { AppMode, AdvancedWalletManagerConfig, TlsMode, SigningMode } from '../../../shared/types';
 import express from 'express';
 
 import * as sinon from 'sinon';
@@ -30,6 +30,7 @@ describe('postIndependentKey', () => {
     // app config
     cfg = {
       appMode: AppMode.ADVANCED_WALLET_MANAGER,
+      signingMode: SigningMode.LOCAL,
       port: 0, // Let OS assign a free port
       bind: 'localhost',
       timeout: 60000,
diff --git a/src/__tests__/api/advancedWalletManager/postMpcV2Key.test.ts b/src/__tests__/api/advancedWalletManager/postMpcV2Key.test.ts
@@ -1,4 +1,4 @@
-import { AppMode, AdvancedWalletManagerConfig, TlsMode } from '../../../initConfig';
+import { AppMode, AdvancedWalletManagerConfig, TlsMode, SigningMode } from '../../../initConfig';
 import { app as advancedWalletManagerApp } from '../../../advancedWalletManagerApp';
 
 import express from 'express';
@@ -32,6 +32,7 @@ describe('postMpcV2Key', () => {
     // app config
     cfg = {
       appMode: AppMode.ADVANCED_WALLET_MANAGER,
+      signingMode: SigningMode.LOCAL,
       port: 0, // Let OS assign a free port
       bind: 'localhost',
       timeout: 60000,
diff --git a/src/__tests__/api/advancedWalletManager/recoveryMpc.test.ts b/src/__tests__/api/advancedWalletManager/recoveryMpc.test.ts
@@ -2,7 +2,7 @@ import 'should';
 import * as request from 'supertest';
 import nock from 'nock';
 import { app as expressApp } from '../../../advancedWalletManagerApp';
-import { AdvancedWalletManagerConfig, AppMode, TlsMode } from '../../../shared/types';
+import { AdvancedWalletManagerConfig, AppMode, TlsMode, SigningMode } from '../../../shared/types';
 
 describe('recoveryMpc', () => {
   let agent: request.SuperAgentTest;
@@ -19,6 +19,7 @@ describe('recoveryMpc', () => {
 
     const config: AdvancedWalletManagerConfig = {
       appMode: AppMode.ADVANCED_WALLET_MANAGER,
+      signingMode: SigningMode.LOCAL,
       port: 0, // Let OS assign a free port
       bind: 'localhost',
       timeout: 60000,
diff --git a/src/__tests__/api/advancedWalletManager/recoveryMpcV2.test.ts b/src/__tests__/api/advancedWalletManager/recoveryMpcV2.test.ts
@@ -1,4 +1,4 @@
-import { AppMode, AdvancedWalletManagerConfig, TlsMode } from '../../../initConfig';
+import { AppMode, AdvancedWalletManagerConfig, TlsMode, SigningMode } from '../../../initConfig';
 import { app as advancedWalletManagerApp } from '../../../advancedWalletManagerApp';
 
 import express from 'express';
@@ -56,6 +56,7 @@ describe('recoveryMpcV2', async () => {
     // app config
     cfg = {
       appMode: AppMode.ADVANCED_WALLET_MANAGER,
+      signingMode: SigningMode.LOCAL,
       port: 0, // Let OS assign a free port
       bind: 'localhost',
       timeout: 60000,
diff --git a/src/__tests__/api/advancedWalletManager/recoveryMultisigTransaction.test.ts b/src/__tests__/api/advancedWalletManager/recoveryMultisigTransaction.test.ts
@@ -2,7 +2,7 @@ import 'should';
 import * as request from 'supertest';
 import nock from 'nock';
 import { app as expressApp } from '../../../advancedWalletManagerApp';
-import { AppMode, AdvancedWalletManagerConfig, TlsMode } from '../../../shared/types';
+import { AppMode, AdvancedWalletManagerConfig, TlsMode, SigningMode } from '../../../shared/types';
 import sinon from 'sinon';
 import * as middleware from '../../../shared/middleware';
 import { BitGoRequest } from '../../../types/request';
@@ -15,6 +15,7 @@ describe('UTXO recovery', () => {
   const coin = 'tbtc';
   const config: AdvancedWalletManagerConfig = {
     appMode: AppMode.ADVANCED_WALLET_MANAGER,
+    signingMode: SigningMode.LOCAL,
     port: 0,
     bind: 'localhost',
     timeout: 60000,
diff --git a/src/__tests__/api/advancedWalletManager/recoveryMusigEth.test.ts b/src/__tests__/api/advancedWalletManager/recoveryMusigEth.test.ts
@@ -4,7 +4,7 @@ import express from 'express';
 import nock from 'nock';
 import * as request from 'supertest';
 import { app as advancedWalletManagerApp } from '../../../advancedWalletManagerApp';
-import { AppMode, AdvancedWalletManagerConfig, TlsMode } from '../../../shared/types';
+import { AppMode, AdvancedWalletManagerConfig, TlsMode, SigningMode } from '../../../shared/types';
 
 import * as sinon from 'sinon';
 import * as configModule from '../../../initConfig';
@@ -33,6 +33,7 @@ describe('recoveryMultisigTransaction', () => {
     // app config
     cfg = {
       appMode: AppMode.ADVANCED_WALLET_MANAGER,
+      signingMode: SigningMode.LOCAL,
       port: 0, // Let OS assign a free port
       bind: 'localhost',
       timeout: 60000,
diff --git a/src/__tests__/api/advancedWalletManager/signMpcRecoveryTransaction.test.ts b/src/__tests__/api/advancedWalletManager/signMpcRecoveryTransaction.test.ts
@@ -5,13 +5,14 @@ import supertest from 'supertest';
 import { Utils } from '@bitgo-beta/sdk-coin-sol';
 import * as keyProviderUtils from '../../../advancedWalletManager/handlers/utils/utils';
 import { app as expressApp } from '../../../advancedWalletManagerApp';
-import { AppMode, AdvancedWalletManagerConfig, TlsMode } from '../../../shared/types';
+import { AppMode, AdvancedWalletManagerConfig, TlsMode, SigningMode } from '../../../shared/types';
 
 describe('EdDSA Recovery Signing', () => {
   let agent: supertest.SuperTest<supertest.Test>;
   const config: AdvancedWalletManagerConfig = {
     keyProviderUrl: 'http://localhost:3000',
     appMode: AppMode.ADVANCED_WALLET_MANAGER,
+    signingMode: SigningMode.LOCAL,
     port: 0,
     bind: 'localhost',
     timeout: 60000,
diff --git a/src/__tests__/api/advancedWalletManager/signMpcTransaction.test.ts b/src/__tests__/api/advancedWalletManager/signMpcTransaction.test.ts
@@ -3,7 +3,7 @@ import 'should';
 import * as request from 'supertest';
 import nock from 'nock';
 import { app as advancedWalletManagerApp } from '../../../advancedWalletManagerApp';
-import { AppMode, AdvancedWalletManagerConfig, TlsMode } from '../../../shared/types';
+import { AppMode, AdvancedWalletManagerConfig, TlsMode, SigningMode } from '../../../shared/types';
 import express from 'express';
 import * as sinon from 'sinon';
 import * as configModule from '../../../initConfig';
@@ -37,6 +37,7 @@ describe('signMpcTransaction', () => {
     // app config
     cfg = {
       appMode: AppMode.ADVANCED_WALLET_MANAGER,
+      signingMode: SigningMode.LOCAL,
       port: 0, // Let OS assign a free port
       bind: 'localhost',
       timeout: 60000,
diff --git a/src/__tests__/api/advancedWalletManager/signMultisigTransaction.test.ts b/src/__tests__/api/advancedWalletManager/signMultisigTransaction.test.ts
@@ -3,7 +3,7 @@ import 'should';
 import * as request from 'supertest';
 import nock from 'nock';
 import { app as advancedWalletManagerApp } from '../../../advancedWalletManagerApp';
-import { AppMode, AdvancedWalletManagerConfig, TlsMode } from '../../../shared/types';
+import { AppMode, AdvancedWalletManagerConfig, TlsMode, SigningMode } from '../../../shared/types';
 import express from 'express';
 
 import * as sinon from 'sinon';
@@ -30,6 +30,7 @@ describe('signMultisigTransaction', () => {
     // app config
     cfg = {
       appMode: AppMode.ADVANCED_WALLET_MANAGER,
+      signingMode: SigningMode.LOCAL,
       port: 0, // Let OS assign a free port
       bind: 'localhost',
       timeout: 60000,
diff --git a/src/__tests__/config.test.ts b/src/__tests__/config.test.ts
@@ -4,6 +4,7 @@ import {
   isAdvancedWalletManagerConfig,
   isMasterExpressConfig,
   TlsMode,
+  SigningMode,
 } from '../initConfig';
 import path from 'path';
 
@@ -185,6 +186,35 @@ describe('Configuration', () => {
       }
     });
 
+    it('should read SIGNING_MODE from environment variables', () => {
+      process.env.KEY_PROVIDER_URL = 'http://localhost:3000';
+      process.env.TLS_MODE = 'disabled';
+
+      // unset defaults to LOCAL
+      delete process.env.SIGNING_MODE;
+      let cfg = initConfig();
+      isAdvancedWalletManagerConfig(cfg).should.be.true();
+      if (isAdvancedWalletManagerConfig(cfg)) {
+        cfg.should.have.property('signingMode', SigningMode.LOCAL);
+      }
+
+      // explicit external
+      process.env.SIGNING_MODE = 'external';
+      cfg = initConfig();
+      isAdvancedWalletManagerConfig(cfg).should.be.true();
+      if (isAdvancedWalletManagerConfig(cfg)) {
+        cfg.should.have.property('signingMode', SigningMode.EXTERNAL);
+      }
+
+      // invalid value throws
+      process.env.SIGNING_MODE = 'invalid';
+      (() => initConfig()).should.throw(
+        'Invalid SIGNING_MODE: invalid. Must be one of: local, external',
+      );
+
+      delete process.env.SIGNING_MODE;
+    });
+
     it('should read mTLS settings from environment variables', () => {
       process.env.KEY_PROVIDER_URL = 'http://localhost:3000';
       process.env.SERVER_TLS_KEY = mockTlsKey;
diff --git a/src/__tests__/routes.test.ts b/src/__tests__/routes.test.ts
@@ -2,7 +2,7 @@ import 'should';
 
 import request from 'supertest';
 import express from 'express';
-import { AppMode, TlsMode } from '../shared/types';
+import { AppMode, TlsMode, SigningMode } from '../shared/types';
 import { setupRoutes } from '../advancedWalletManager/routers/advancedWalletManager';
 
 describe('Routes', () => {
@@ -12,6 +12,7 @@ describe('Routes', () => {
     app = express();
     setupRoutes(app, {
       appMode: AppMode.ADVANCED_WALLET_MANAGER,
+      signingMode: SigningMode.LOCAL,
       httpLoggerFile: '',
       clientCertAllowSelfSigned: true,
       tlsMode: TlsMode.DISABLED,
diff --git a/src/advancedWalletManager/keyProviderClient/keyProviderClient.ts b/src/advancedWalletManager/keyProviderClient/keyProviderClient.ts
diff --git a/src/initConfig.ts b/src/initConfig.ts
diff --git a/src/shared/types/index.ts b/src/shared/types/index.ts
