Merge pull request #314 from adcontextprotocol/EmmaLouise2018/fix-issue-313

fix: use raw body bytes for webhook HMAC verification

Author: EmmaLouise2018

.changeset/raw-body-webhook-hmac.md

@@ -0,0 +1,5 @@
+---
+"@adcp/client": patch
+---
+
+Fix webhook HMAC signature verification to use raw HTTP body bytes instead of re-serialized JSON. `verifyWebhookSignature()` now accepts a raw body string (preferred) or parsed object (backward compat). This fixes cross-language interop where different JSON serializers produce different byte representations.

src/lib/core/ADCPMultiAgentClient.ts

@@ -933,7 +933,8 @@ export class ADCPMultiAgentClient {
     taskType: string,
     operationId: string,
     signature?: string,
-    timestamp?: string | number
+    timestamp?: string | number,
+    rawBody?: string
   ): Promise<boolean> {
     // Extract agent ID from payload
     // Webhook payloads include agent_id or we can infer from operation_id pattern
@@ -944,7 +945,7 @@ export class ADCPMultiAgentClient {
     }
 
     const agent = this.getAgent(agentId);
-    return agent.handleWebhook(payload, taskType, operationId, signature, timestamp);
+    return agent.handleWebhook(payload, taskType, operationId, signature, timestamp, rawBody);
   }
 
   /**

src/lib/core/AgentClient.ts

@@ -87,9 +87,10 @@ export class AgentClient {
     taskType: string,
     operationId: string,
     signature?: string,
-    timestamp?: string | number
+    timestamp?: string | number,
+    rawBody?: string
   ): Promise<boolean> {
-    return this.client.handleWebhook(payload, taskType, operationId, signature, timestamp);
+    return this.client.handleWebhook(payload, taskType, operationId, signature, timestamp, rawBody);
   }
 
   /**
@@ -104,15 +105,19 @@ export class AgentClient {
   }
 
   /**
-   * Verify webhook signature using HMAC-SHA256 per AdCP PR #86 spec
+   * Verify webhook signature using HMAC-SHA256 per AdCP spec.
    *
-   * @param payload - Webhook payload object
+   * Prefer passing the raw HTTP body string for correct cross-language interop.
+   * Passing a parsed object still works but re-serializes with JSON.stringify,
+   * which may not match the sender's byte representation.
+   *
+   * @param rawBodyOrPayload - Raw HTTP body string (preferred) or parsed payload object (deprecated)
    * @param signature - X-ADCP-Signature header value (format: "sha256=...")
    * @param timestamp - X-ADCP-Timestamp header value (Unix timestamp)
    * @returns true if signature is valid
    */
-  verifyWebhookSignature(payload: any, signature: string, timestamp: string | number): boolean {
-    return this.client.verifyWebhookSignature(payload, signature, timestamp);
+  verifyWebhookSignature(rawBodyOrPayload: string | any, signature: string, timestamp: string | number): boolean {
+    return this.client.verifyWebhookSignature(rawBodyOrPayload, signature, timestamp);
   }
 
   // ====== MEDIA BUY TASKS ======

src/lib/core/SingleAgentClient.ts

@@ -566,15 +566,16 @@ export class SingleAgentClient {
     taskType: string,
     operationId: string,
     signature?: string,
-    timestamp?: string | number
+    timestamp?: string | number,
+    rawBody?: string
   ): Promise<boolean> {
     // Verify signature if secret is configured
     if (this.config.webhookSecret) {
       if (!signature || !timestamp) {
         throw new Error('Webhook signature and timestamp required but not provided');
       }
 
-      const isValid = this.verifyWebhookSignature(payload, signature, timestamp);
+      const isValid = this.verifyWebhookSignature(rawBody ?? payload, signature, timestamp);
       if (!isValid) {
         throw new Error('Invalid webhook signature or timestamp too old');
       }
@@ -783,11 +784,16 @@ export class SingleAgentClient {
         const signature = req.headers['x-adcp-signature'] || req.headers['X-ADCP-Signature'];
         const timestamp = req.headers['x-adcp-timestamp'] || req.headers['X-ADCP-Timestamp'];
 
-        // Parse body if needed
+        // Capture raw body for signature verification, then parse
+        const rawBody = typeof req.body === 'string' ? req.body : JSON.stringify(req.body);
         const payload = typeof req.body === 'string' ? JSON.parse(req.body) : req.body;
 
-        // Handle webhook with automatic verification
-        const handled = await this.handleWebhook(payload, signature, timestamp);
+        // Extract routing params if available (e.g., Express route params)
+        const taskType = req.params?.task_type || req.params?.taskType || 'unknown';
+        const operationId = req.params?.operation_id || req.params?.operationId || 'unknown';
+
+        // Handle webhook with automatic verification using raw body bytes
+        const handled = await this.handleWebhook(payload, taskType, operationId, signature, timestamp, rawBody);
 
         // Return success
         if (res.json) {
@@ -811,17 +817,26 @@ export class SingleAgentClient {
   }
 
   /**
-   * Verify webhook signature using HMAC-SHA256 per AdCP PR #86 spec
+   * Verify webhook signature using HMAC-SHA256 per AdCP spec.
+   *
+   * HMAC is computed over the **raw HTTP body bytes** — the exact bytes received
+   * on the wire, before JSON parsing. This ensures cross-language interop since
+   * different JSON serializers may produce different byte representations of the
+   * same logical payload.
+   *
+   * For backward compatibility, a parsed object is still accepted but will be
+   * re-serialized with JSON.stringify, which may not match the sender's bytes.
+   * Always prefer passing the raw body string.
    *
    * Signature format: sha256={hex_signature}
-   * Message format: {timestamp}.{json_payload}
+   * Message format: {timestamp}.{raw_body}
    *
-   * @param payload - Webhook payload object
+   * @param rawBodyOrPayload - Raw HTTP body string (preferred) or parsed payload object (deprecated)
    * @param signature - X-ADCP-Signature header value (format: "sha256=...")
    * @param timestamp - X-ADCP-Timestamp header value (Unix timestamp)
    * @returns true if signature is valid
    */
-  verifyWebhookSignature(payload: any, signature: string, timestamp: string | number): boolean {
+  verifyWebhookSignature(rawBodyOrPayload: string | any, signature: string, timestamp: string | number): boolean {
     if (!this.config.webhookSecret) {
       return false;
     }
@@ -834,8 +849,11 @@ export class SingleAgentClient {
       return false; // Request too old or from future
     }
 
-    // Build message per AdCP spec: {timestamp}.{json_payload}
-    const message = `${ts}.${JSON.stringify(payload)}`;
+    // Use raw body bytes when available; fall back to JSON.stringify for backward compat
+    const body = typeof rawBodyOrPayload === 'string' ? rawBodyOrPayload : JSON.stringify(rawBodyOrPayload);
+
+    // Build message per AdCP spec: {timestamp}.{raw_body}
+    const message = `${ts}.${body}`;
 
     // Calculate expected signature
     const hmac = crypto.createHmac('sha256', this.config.webhookSecret);

src/server/server.ts

@@ -3,6 +3,7 @@ import Fastify, { FastifyInstance } from 'fastify';
 import fastifyStatic from '@fastify/static';
 import fastifyCors from '@fastify/cors';
 import path from 'path';
+import { Readable } from 'stream';
 import {
   ADCPMultiAgentClient,
   ConfigurationManager,
@@ -61,6 +62,23 @@ const app: FastifyInstance = Fastify({
   },
 });
 
+// Capture raw body on webhook routes for HMAC signature verification.
+// The raw bytes must be used (not re-serialized JSON) for cross-language interop.
+app.addHook('preParsing', async (request, _reply, payload) => {
+  if (request.url.startsWith('/webhook/')) {
+    const chunks: Buffer[] = [];
+    for await (const chunk of payload) {
+      chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+    }
+    const rawBody = Buffer.concat(chunks).toString('utf8');
+    (request as any).rawBody = rawBody;
+
+    // Return a new readable stream so Fastify can still parse the body
+    return Readable.from([rawBody]);
+  }
+  return payload;
+});
+
 // Initialize ADCP client with configured agents
 const configuredAgents = ConfigurationManager.loadAgentsFromEnv();
 
@@ -2033,6 +2051,9 @@ app.post<{
     const signature = request.headers['x-adcp-signature'] as string | undefined;
     const timestamp = request.headers['x-adcp-timestamp'] as string | undefined;
 
+    // Use raw body for HMAC verification when available, fall back to re-serialized payload
+    const rawBody = (request as any).rawBody as string | undefined;
+
     app.log.info(`Webhook received: ${taskType} for operation ${operationId}`);
 
     // TODO: Validate payload against JSON schema for task_type
@@ -2052,7 +2073,7 @@ app.post<{
     // The webhook URL was generated with this agent_id during operation setup
     // We use it to look up the correct agent configuration (auth, protocol, etc)
     const agent = adcpClient.agent(agentId);
-    const handled = await agent.handleWebhook(payload, taskType, operationId, signature, timestamp);
+    const handled = await agent.handleWebhook(payload, taskType, operationId, signature, timestamp, rawBody);
 
     if (!handled) {
       app.log.warn(`Webhook not handled - no handlers configured`);