deploy: 339548b

Author: bokelley

client.html

@@ -3045,27 +3045,55 @@ <h2 class="section-title" id="header-classes">Classes</h2>
         Verify HMAC-SHA256 signature of webhook payload.
 
         The verification algorithm matches get_adcp_signed_headers_for_webhook:
-        1. Constructs message as &#34;{timestamp}.{json_payload}&#34;
-        2. Uses raw HTTP body bytes when available (preserves sender&#39;s serialization)
-        3. Falls back to json.dumps() if raw_body not provided
-        4. HMAC-SHA256 signs with the shared secret
-        5. Compares against the provided signature (with &#34;sha256=&#34; prefix stripped)
+        1. Constructs message as &#34;{timestamp}.{raw_http_body_bytes}&#34;
+        2. HMAC-SHA256 signs with the shared secret
+        3. Compares against the provided signature (with &#34;sha256=&#34; prefix stripped)
+           using constant-time comparison.
+
+        Per AdCP spec (adcontextprotocol/adcp#2478): verifiers MUST use the raw
+        HTTP body bytes captured before any JSON parse; they SHOULD NOT
+        re-serialize a parsed payload to reconstruct the signed bytes, because
+        re-serialization silently fails against signers whose output differs in
+        separator choice, key order, unicode escapes, or number formatting —
+        masking signer bugs the verifier should surface. Callers that genuinely
+        cannot capture raw bytes MUST fail closed.
+
+        This implementation therefore rejects verification attempts that don&#39;t
+        supply ``raw_body``. Capture it from your framework&#39;s pre-parse hook
+        (FastAPI ``Request.body()``, Flask ``request.get_data(cache=True)``,
+        aiohttp ``Request.read()``, Express ``express.raw()``).
 
         Args:
-            payload: Webhook payload dict (used as fallback if raw_body not provided)
+            payload: Parsed webhook payload dict (not used for signing; kept
+                for signature parity with callers, but verification derives
+                solely from ``raw_body``).
             signature: Signature to verify (with or without &#34;sha256=&#34; prefix)
             timestamp: Unix timestamp in seconds from X-AdCP-Timestamp header
-            raw_body: Raw HTTP request body bytes. When provided, used directly
-                for signature verification to avoid cross-language serialization
-                mismatches. Strongly recommended for production use.
+            raw_body: Raw HTTP request body bytes as received on the wire,
+                captured before any JSON parse. Required.
 
         Returns:
-            True if signature is valid, False otherwise
+            True if signature is valid, False otherwise (including when
+            ``raw_body`` is missing — fails closed per spec).
         &#34;&#34;&#34;
         if not self.webhook_secret:
             logger.warning(&#34;Webhook signature verification skipped: no webhook_secret configured&#34;)
             return True
 
+        # Fail closed per adcontextprotocol/adcp#2478: verifiers that cannot
+        # capture raw bytes MUST reject, surfacing the infrastructure gap
+        # rather than silently reconstructing a signed body that may diverge
+        # from the bytes the signer actually hashed.
+        if raw_body is None:
+            logger.error(
+                &#34;Webhook signature verification failed: raw_body is required. &#34;
+                &#34;Capture the raw HTTP body pre-parse and pass it to &#34;
+                &#34;handle_webhook(raw_body=...). See &#34;
+                &#34;https://adcontextprotocol.org/docs/building/implementation/security&#34;
+                &#34;#legacy-hmac-sha256-fallback-deprecated-removed-in-40&#34;
+            )
+            return False
+
         # Reject stale or future timestamps to prevent replay attacks
         try:
             ts = int(timestamp)
@@ -3079,12 +3107,7 @@ <h2 class="section-title" id="header-classes">Classes</h2>
         if signature.startswith(&#34;sha256=&#34;):
             signature = signature[7:]
 
-        # Use raw body if available (avoids cross-language serialization mismatches),
-        # otherwise fall back to json.dumps() for backward compatibility
-        if raw_body is not None:
-            payload_str = raw_body.decode(&#34;utf-8&#34;) if isinstance(raw_body, bytes) else raw_body
-        else:
-            payload_str = json.dumps(payload)
+        payload_str = raw_body.decode(&#34;utf-8&#34;) if isinstance(raw_body, bytes) else raw_body
 
         # Construct signed message: timestamp.payload
         signed_message = f&#34;{timestamp}.{payload_str}&#34;