feat: capture raw body bytes for v4 hmac calculation

TICKET: CAAS-659

Author: MohammedRyaan786

modules/express/src/clientRoutes.ts

@@ -1192,6 +1192,23 @@ async function handleNetworkV1EnterpriseClientConnections(
   return handleProxyReq(req, res, next);
 }
 
+/**
+ * Helper to send request body, using raw bytes when available.
+ * For v4 HMAC authentication, we need to send the exact bytes that were
+ * received from the client to ensure the HMAC signature matches.
+ *
+ * @param request - The superagent request object
+ * @param req - The Express request containing body and rawBodyBuffer
+ * @returns The request with body attached
+ */
+function sendRequestBody(request: ReturnType<BitGo['post']>, req: express.Request) {
+  if (req.rawBodyBuffer && req.rawBodyBuffer.length > 0) {
+    return request.set('Content-Type', 'application/json').send(req.rawBodyBuffer);
+  }
+  // Fall back to parsed body for backward compatibility
+  return request.send(req.body);
+}
+
 /**
  * Redirect a request using the bitgo request functions.
  * @param bitgo
@@ -1214,19 +1231,19 @@ export function redirectRequest(
       request = bitgo.get(url);
       break;
     case 'POST':
-      request = bitgo.post(url).send(req.body);
+      request = sendRequestBody(bitgo.post(url), req);
       break;
     case 'PUT':
-      request = bitgo.put(url).send(req.body);
+      request = sendRequestBody(bitgo.put(url), req);
       break;
     case 'PATCH':
-      request = bitgo.patch(url).send(req.body);
+      request = sendRequestBody(bitgo.patch(url), req);
       break;
     case 'OPTIONS':
-      request = bitgo.options(url).send(req.body);
+      request = sendRequestBody(bitgo.options(url), req);
       break;
     case 'DELETE':
-      request = bitgo.del(url).send(req.body);
+      request = sendRequestBody(bitgo.del(url), req);
       break;
   }
 

modules/express/src/expressApp.ts

@@ -302,7 +302,18 @@ export function app(cfg: Config): express.Application {
   checkPreconditions(cfg);
   debug('preconditions satisfied');
 
-  app.use(bodyParser.json({ limit: '20mb' }));
+  app.use(
+    bodyParser.json({
+      limit: '20mb',
+      verify: (req, res, buf) => {
+        // Store the raw body buffer on the request object.
+        // This preserves the exact bytes before JSON parsing,
+        // which may alter whitespace, key ordering, etc.
+        // Required for v4 HMAC authentication.
+        (req as express.Request).rawBodyBuffer = buf;
+      },
+    })
+  );
 
   // Be more robust about accepting URLs with double slashes
   app.use(function replaceUrlSlashes(req, res, next) {

modules/express/test/unit/clientRoutes/rawBodyBuffer.ts

@@ -0,0 +1,153 @@
+/**
+ * Tests for raw body buffer capture functionality
+ * This ensures exact bytes are preserved for v4 HMAC authentication
+ * @prettier
+ */
+import 'should';
+import 'should-http';
+import 'should-sinon';
+import '../../lib/asserts';
+import * as sinon from 'sinon';
+import * as express from 'express';
+import { agent as supertest, Response } from 'supertest';
+import { app as expressApp } from '../../../src/expressApp';
+
+describe('Raw Body Buffer Capture', () => {
+  const sandbox = sinon.createSandbox();
+
+  afterEach(() => {
+    sandbox.verifyAndRestore();
+  });
+
+  describe('body-parser verify callback', () => {
+    let agent: ReturnType<typeof supertest>;
+
+    beforeEach(() => {
+      const app = expressApp({
+        env: 'test',
+        disableProxy: true,
+      } as any);
+
+      // Add a test route that returns the rawBodyBuffer info
+      app.post('/test/rawbody', (req: express.Request, res: express.Response) => {
+        res.json({
+          hasRawBodyBuffer: !!req.rawBodyBuffer,
+          rawBodyBufferLength: req.rawBodyBuffer?.length || 0,
+          rawBodyBufferContent: req.rawBodyBuffer?.toString('utf-8') || null,
+          parsedBody: req.body,
+          bodyKeysCount: Object.keys(req.body || {}).length,
+        });
+      });
+
+      // Add a test route for HMAC verification
+      app.post('/test/hmac-check', (req: express.Request, res: express.Response) => {
+        const rawBytes = req.rawBodyBuffer;
+        const reSerializedBytes = Buffer.from(JSON.stringify(req.body));
+
+        res.json({
+          rawBytesHex: rawBytes?.toString('hex') || null,
+          reSerializedBytesHex: reSerializedBytes.toString('hex'),
+          bytesMatch: rawBytes?.toString('hex') === reSerializedBytes.toString('hex'),
+          rawLength: rawBytes?.length || 0,
+          reSerializedLength: reSerializedBytes.length,
+        });
+      });
+
+      // Add a test route for HMAC chain simulation
+      app.post('/test/hmac-chain', (req: express.Request, res: express.Response) => {
+        const clientBytes = req.rawBodyBuffer;
+        const parsedAndSerialized = Buffer.from(JSON.stringify(req.body));
+
+        res.json({
+          clientBytesPreserved: !!clientBytes,
+          wouldHmacMatch: clientBytes?.toString('hex') === parsedAndSerialized.toString('hex'),
+          recommendation: clientBytes ? 'Use rawBodyBuffer for HMAC' : 'Missing rawBodyBuffer',
+        });
+      });
+
+      agent = supertest(app);
+    });
+
+    it('should capture raw body buffer on POST requests', async () => {
+      const testBody = { address: 'tb1qtest', amount: 100000 };
+
+      const res: Response = await agent.post('/test/rawbody').set('Content-Type', 'application/json').send(testBody);
+
+      res.status.should.equal(200);
+      res.body.hasRawBodyBuffer.should.equal(true);
+      res.body.rawBodyBufferLength.should.be.greaterThan(0);
+      res.body.parsedBody.should.deepEqual(testBody);
+    });
+
+    it('should preserve exact bytes including whitespace', async () => {
+      // JSON with extra whitespace that would be lost during parse/re-serialize
+      const bodyWithWhitespace = '{"address":  "tb1qtest",   "amount":100000}';
+
+      const res: Response = await agent
+        .post('/test/rawbody')
+        .set('Content-Type', 'application/json')
+        .send(bodyWithWhitespace);
+
+      res.status.should.equal(200);
+      // Raw buffer should preserve the exact whitespace
+      res.body.rawBodyBufferContent.should.equal(bodyWithWhitespace);
+      // Parsed body should have the correct values
+      res.body.parsedBody.address.should.equal('tb1qtest');
+      res.body.parsedBody.amount.should.equal(100000);
+    });
+
+    it('should preserve exact key ordering', async () => {
+      // JSON with specific key ordering
+      const bodyWithOrdering = '{"z_last":"last","a_first":"first","m_middle":"middle"}';
+
+      const res: Response = await agent
+        .post('/test/rawbody')
+        .set('Content-Type', 'application/json')
+        .send(bodyWithOrdering);
+
+      res.status.should.equal(200);
+      // Raw buffer should preserve exact key ordering
+      res.body.rawBodyBufferContent.should.equal(bodyWithOrdering);
+    });
+
+    it('should handle empty body', async () => {
+      const res: Response = await agent.post('/test/rawbody').set('Content-Type', 'application/json').send({});
+
+      res.status.should.equal(200);
+      res.body.hasRawBodyBuffer.should.equal(true);
+      res.body.rawBodyBufferLength.should.equal(2); // "{}"
+    });
+
+    it('should handle nested JSON objects', async () => {
+      const nestedBody = {
+        level1: {
+          level2: {
+            level3: {
+              value: 'deep',
+            },
+          },
+        },
+      };
+
+      const res: Response = await agent.post('/test/rawbody').set('Content-Type', 'application/json').send(nestedBody);
+
+      res.status.should.equal(200);
+      res.body.hasRawBodyBuffer.should.equal(true);
+      res.body.parsedBody.level1.level2.level3.value.should.equal('deep');
+    });
+
+    it('should preserve raw bytes for HMAC calculation across the request chain', async () => {
+      const walletSendBody =
+        '{"address":"bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh","amount":1000000,"walletPassphrase":"test"}';
+
+      const res: Response = await agent
+        .post('/test/hmac-chain')
+        .set('Content-Type', 'application/json')
+        .send(walletSendBody);
+
+      res.status.should.equal(200);
+      res.body.clientBytesPreserved.should.equal(true);
+      res.body.recommendation.should.equal('Use rawBodyBuffer for HMAC');
+    });
+  });
+});

modules/express/types/express/index.d.ts

@@ -6,5 +6,11 @@ declare module 'express-serve-static-core' {
     isProxy: boolean;
     bitgo: BitGo;
     config: Config;
+    /**
+     * Raw body buffer captured before JSON parsing.
+     * Used for v4 HMAC authentication to ensure the exact bytes
+     * sent by the client are used for signature calculation.
+     */
+    rawBodyBuffer?: Buffer;
   }
 }