feat(express): support optional passphrase in handleV2OFCSignPayload

When no walletPassphrase is present in the request body or environment,
pass undefined to tradingAccount.signPayload() instead of throwing.
The SDK routes passphrase-less signing through KMS internally.

Ticket: WCN-215-1

Author: mrdanish26

modules/express/src/clientRoutes.ts

@@ -403,6 +403,15 @@ function getWalletPwFromEnv(walletId: string): string {
   return walletPw;
 }
 
+/**
+ * Returns the wallet passphrase from the environment, or undefined if not set.
+ * Unlike getWalletPwFromEnv, this does not throw when the env variable is absent.
+ * Use this when the passphrase is optional (e.g. KMS-backed wallets).
+ */
+function findWalletPwFromEnv(walletId: string): string | undefined {
+  return process.env[`WALLET_${walletId}_PASSPHRASE`];
+}
+
 async function getEncryptedPrivKey(path: string, walletId: string): Promise<string> {
   const privKeyFile = await fs.readFile(path, { encoding: 'utf8' });
   const encryptedPrivKey = JSON.parse(privKeyFile);
@@ -629,7 +638,9 @@ export async function handleV2OFCSignPayload(
     throw new ApiResponseError(`Could not find OFC wallet ${walletId}`, 404);
   }
 
-  const walletPassphrase = bodyWalletPassphrase || getWalletPwFromEnv(wallet.id());
+  // Prefer the passphrase from the request body; fall back to the env var.
+  // If neither is present, pass undefined — signPayload() routes to KMS internally.
+  const walletPassphrase = bodyWalletPassphrase ?? findWalletPwFromEnv(wallet.id());
   const tradingAccount = wallet.toTradingAccount();
   const stringifiedPayload = typeof payload === 'string' ? payload : JSON.stringify(payload);
   const signature = await tradingAccount.signPayload({

modules/express/test/unit/typedRoutes/ofcSignPayload.ts

@@ -223,10 +223,103 @@ describe('OfcSignPayload codec tests', function () {
       const decodedResponse = assertDecode(OfcSignPayloadResponse200, result.body);
       assert.strictEqual(decodedResponse.signature, mockSignPayloadResponse.signature);
 
+      // Verify env passphrase was forwarded to signPayload
+      const signCall = mockTradingAccount.signPayload.getCall(0);
+      assert.ok(signCall, 'tradingAccount.signPayload should have been called');
+      assert.strictEqual(signCall.args[0].walletPassphrase, 'env_passphrase', 'env passphrase should be forwarded');
+
       // Cleanup environment variable
       delete process.env['WALLET_ofc-wallet-id-123_PASSPHRASE'];
     });
 
+    it('should pass undefined walletPassphrase to signPayload when no passphrase in body or env (KMS path)', async function () {
+      const requestBody = {
+        walletId: 'ofc-wallet-id-no-passphrase',
+        payload: { amount: '1000000', currency: 'USD' },
+        // no walletPassphrase
+      };
+
+      // Ensure no env var is set for this wallet
+      delete process.env['WALLET_ofc-wallet-id-no-passphrase_PASSPHRASE'];
+
+      const mockTradingAccount = {
+        signPayload: sinon.stub().resolves(mockSignPayloadResponse.signature),
+      };
+
+      const mockWallet = {
+        id: () => requestBody.walletId,
+        toTradingAccount: sinon.stub().returns(mockTradingAccount),
+      };
+
+      const walletsGetStub = sinon.stub().resolves(mockWallet);
+      const mockWallets = { get: walletsGetStub };
+      const mockCoin = { wallets: sinon.stub().returns(mockWallets) };
+      sinon.stub(BitGo.prototype, 'coin').returns(mockCoin as any);
+
+      const result = await agent
+        .post('/api/v2/ofc/signPayload')
+        .set('Authorization', 'Bearer test_access_token_12345')
+        .set('Content-Type', 'application/json')
+        .send(requestBody);
+
+      assert.strictEqual(result.status, 200);
+      const decodedResponse = assertDecode(OfcSignPayloadResponse200, result.body);
+      assert.strictEqual(decodedResponse.signature, mockSignPayloadResponse.signature);
+
+      // signPayload must be called with walletPassphrase=undefined so the SDK routes to KMS
+      const signCall = mockTradingAccount.signPayload.getCall(0);
+      assert.ok(signCall, 'tradingAccount.signPayload should have been called');
+      assert.strictEqual(
+        signCall.args[0].walletPassphrase,
+        undefined,
+        'walletPassphrase should be undefined to trigger KMS signing'
+      );
+    });
+
+    it('should prefer body walletPassphrase over env passphrase', async function () {
+      const requestBody = {
+        walletId: 'ofc-wallet-id-123',
+        payload: { amount: '500' },
+        walletPassphrase: 'body_passphrase',
+      };
+
+      // Set a different env passphrase — body should win
+      process.env['WALLET_ofc-wallet-id-123_PASSPHRASE'] = 'env_passphrase';
+
+      const mockTradingAccount = {
+        signPayload: sinon.stub().resolves(mockSignPayloadResponse.signature),
+      };
+
+      const mockWallet = {
+        id: () => requestBody.walletId,
+        toTradingAccount: sinon.stub().returns(mockTradingAccount),
+      };
+
+      const walletsGetStub = sinon.stub().resolves(mockWallet);
+      const mockWallets = { get: walletsGetStub };
+      const mockCoin = { wallets: sinon.stub().returns(mockWallets) };
+      sinon.stub(BitGo.prototype, 'coin').returns(mockCoin as any);
+
+      const result = await agent
+        .post('/api/v2/ofc/signPayload')
+        .set('Authorization', 'Bearer test_access_token_12345')
+        .set('Content-Type', 'application/json')
+        .send(requestBody);
+
+      assert.strictEqual(result.status, 200);
+
+      // body passphrase should take precedence
+      const signCall = mockTradingAccount.signPayload.getCall(0);
+      assert.ok(signCall, 'tradingAccount.signPayload should have been called');
+      assert.strictEqual(
+        signCall.args[0].walletPassphrase,
+        'body_passphrase',
+        'body passphrase should take precedence over env'
+      );
+
+      delete process.env['WALLET_ofc-wallet-id-123_PASSPHRASE'];
+    });
+
     it('should successfully sign complex nested JSON payload', async function () {
       const requestBody = {
         walletId: 'ofc-wallet-id-123',