feat(client)!: complete JavaScript v13 parity hardening

BREAKING CHANGE: ADCPClient.handle_webhook now rejects unsigned MCP callbacks unless the isolated-receiver compatibility escape is explicitly enabled.

Author: bokelley

MIGRATION_v6_to_v7.md

@@ -32,10 +32,10 @@ SDK 7 continues to interoperate with AdCP 3.0 and 3.1 agents.
    waiting for a duplicate completion webhook.
 8. Exercise callback validation and multi-tenant isolation in staging before
    production rollout.
-9. Configure `webhook_secret` on every public MCP callback receiver. If an
-   endpoint is isolated from untrusted networks and must temporarily accept
-   unsigned callbacks, opt in explicitly with
-   `allow_unauthenticated_webhooks=True`.
+9. Use `WebhookReceiver` for public MCP callback endpoints so RFC 9421
+   verification and delivery deduplication happen before application code.
+   Configure `webhook_secret` on `ADCPClient` only for registrations that
+   explicitly select the deprecated `HMAC-SHA256` fallback.
 
 ## Canonical creatives are the primary API
 
@@ -201,11 +201,11 @@ DNS pinning must provide a custom sender and enforce resolution at connection
 time. A push-configured handoff with no available delivery transport is now
 rejected before task creation instead of being accepted and silently dropped.
 
-`ADCPClient.handle_webhook()` also fails closed for unsigned MCP callbacks when
-the client has no `webhook_secret`. The previous fail-open behavior is
-available only through the explicit `allow_unauthenticated_webhooks=True`
-compatibility escape. Do not enable that option on an Internet-reachable
-receiver.
+Public MCP callbacks should enter through `WebhookReceiver`, which verifies the
+AdCP RFC 9421 profile, deduplicates delivery, and parses the authenticated raw
+body. `ADCPClient.handle_webhook()` is the legacy HMAC convenience path; use it
+only when the callback registration explicitly selects `HMAC-SHA256` and the
+client is configured with the same `webhook_secret`.
 
 Account registries, sessions, proposals, notification stores, and reference
 seller state now enforce tenant ownership. Test fixtures or application code

MIGRATION_v7_to_v8.md

@@ -0,0 +1,27 @@
+# Migrating from Python SDK 7 to 8
+
+SDK 8 makes the legacy `ADCPClient.handle_webhook()` convenience path fail
+closed. Calls without a configured `webhook_secret` no longer accept unsigned
+MCP callbacks.
+
+For AdCP-conformant public endpoints, migrate delivery to `WebhookReceiver`.
+It verifies RFC 9421 signatures, deduplicates retries, and parses the
+authenticated raw body:
+
+```python
+from adcp.webhooks import WebhookReceiver
+
+outcome = await receiver.receive(
+    method=request.method,
+    url=str(request.url),
+    headers=dict(request.headers),
+    body=await request.body(),
+)
+```
+
+If a 3.x registration explicitly selects the deprecated `HMAC-SHA256`
+fallback, configure the same shared secret on `ADCPClient` and pass the raw
+request body to `handle_webhook()`. An endpoint that is isolated from untrusted
+networks may temporarily retain unsigned legacy callbacks with
+`allow_unauthenticated_webhooks=True`; multi-agent clients must scope this
+escape by agent ID.

README.md

@@ -494,41 +494,53 @@ for result in results:
         print(f"Async: webhook to {result.submitted.webhook_url}")
 ```
 
-### Webhook Handling
-Single endpoint handles all webhooks:
+### Legacy HMAC webhook handling
+
+For registrations that explicitly select `HMAC-SHA256`, a single endpoint can
+route callbacks through the client helper. Capture the raw body before parsing;
+those exact bytes are what the signature authenticates:
 
 ```python
+import json
 from fastapi import FastAPI, Request
 
 app = FastAPI()
 
 @app.post("/webhook/{task_type}/{agent_id}/{operation_id}")
 async def webhook(task_type: str, agent_id: str, operation_id: str, request: Request):
-    payload = await request.json()
-    payload["task_type"] = task_type
-    payload["operation_id"] = operation_id
+    raw_body = await request.body()
+    payload = json.loads(raw_body)
 
     # Route to agent client - handlers fire automatically
     agent = client.agent(agent_id)
     await agent.handle_webhook(
-        payload,
-        request.headers.get("x-adcp-signature")
+        payload=payload,
+        task_type=task_type,
+        operation_id=operation_id,
+        signature=request.headers.get("x-adcp-signature"),
+        timestamp=request.headers.get("x-adcp-timestamp"),
+        raw_body=raw_body,
     )
 
     return {"received": True}
 ```
 
-### Security
-Webhook signature verification built-in:
+### Legacy HMAC callback verification
+
+For AdCP 3.x registrations that explicitly select the deprecated
+`HMAC-SHA256` authentication mode, shared-secret verification is available on
+the client helper:
 
 ```python
 client = ADCPMultiAgentClient(
     agents=agents,
     webhook_secret=os.getenv("WEBHOOK_SECRET")
 )
-# Signatures verified automatically on handle_webhook()
+# Legacy HMAC signatures are verified on handle_webhook().
 ```
 
+For the protocol-default RFC 9421 mode, use `WebhookReceiver` as shown below.
+
 ### Signed webhooks (AdCP 3.0): receiver quickstart
 
 AdCP 3.0 webhooks are signed under the RFC 9421 profile

src/adcp/__init__.py

@@ -208,15 +208,30 @@ def _resolve_version() -> str:
         "ArtifactWebhookPayload",
         "AssetContentType",
         "AssetInstance",
+        "AssetInstanceType",
         "AssetVariant",
+        "AudioContent",
         "AudienceSource",
+        "CssContent",
+        "DaastAsset",
+        "HtmlContent",
+        "ImageContent",
+        "JavascriptContent",
+        "MarkdownAsset",
+        "TextContent",
+        "UrlContent",
+        "VastAsset",
+        "VideoContent",
+        "WebhookContent",
         "AuthorizationRequiredDetails",
         "BrandReference",
         "BrandSource",
+        "BriefAsset",
         "BuyingMode",
         "CardAsset",
         "Catalog",
         "CatalogAction",
+        "CatalogAsset",
         "CatalogFieldBinding",
         "CatalogFieldMapping",
         "CatalogGroupBinding",
@@ -1023,12 +1038,27 @@ def get_adcp_version() -> str:
     "FormatOptionReference",
     "AssetContentType",
     "AssetInstance",
+    "AssetInstanceType",
     "AssetVariant",
+    "AudioContent",
+    "BriefAsset",
     "CardAsset",
+    "CatalogAsset",
+    "CssContent",
+    "DaastAsset",
     "DaastTrackerAsset",
+    "HtmlContent",
+    "ImageContent",
+    "JavascriptContent",
+    "MarkdownAsset",
     "PixelTrackerAsset",
     "PublishedPostAsset",
+    "TextContent",
+    "UrlContent",
+    "VastAsset",
     "VastTrackerAsset",
+    "VideoContent",
+    "WebhookContent",
     "ZipAsset",
     "Product",
     "ProductFormatDeclaration",
@@ -1474,18 +1504,22 @@ def get_adcp_version() -> str:
         ArtifactWebhookPayload,
         AssetContentType,
         AssetInstance,
+        AssetInstanceType,
         AssetVariant,
         AudienceSource,
+        AudioContent,
         AuthorizationRequiredDetails,
         # Core domain types
         BrandReference,
         BrandSource,
         # Creative Operations
+        BriefAsset,
         BuyingMode,
         CardAsset,
         # Catalog types
         Catalog,
         CatalogAction,
+        CatalogAsset,
         CatalogFieldBinding,
         CatalogFieldMapping,
         CatalogGroupBinding,
@@ -1521,6 +1555,8 @@ def get_adcp_version() -> str:
         # Status enums (for control flow)
         CreativeStatus,
         CreativeVariant,
+        CssContent,
+        DaastAsset,
         DaastTrackerAsset,
         DateRange,
         DatetimeRange,
@@ -1563,9 +1599,12 @@ def get_adcp_version() -> str:
         GetTaskStatusRequest,
         GetTaskStatusResponse,
         Gtin,
+        HtmlContent,
         IdentityMatchRequest,
         IdentityMatchResponse,
         IdentityMatchTmpxMacro,
+        ImageContent,
+        JavascriptContent,
         KellerType,
         LegacyBuildCreativeErrorResponse,
         LegacyBuildCreativeRequest,
@@ -1622,6 +1661,7 @@ def get_adcp_version() -> str:
         # Event Operations
         LogEventRequest,
         LogEventResponse,
+        MarkdownAsset,
         McpWebhookPayload,
         MediaBuy,
         MediaBuyDeliveryStatus,
@@ -1696,14 +1736,17 @@ def get_adcp_version() -> str:
         SyncPlansRequest,
         SyncPlansResponse,
         TargetingOverlay,
+        TextContent,
         TimeBasedPricingOption,
         TimeUnit,
         Transform,
         UpdateFrequency,
         UpdateMediaBuyRequest,
         UpdateMediaBuyResponse,
+        UrlContent,
         ValidateInputRequest,
         ValidateInputResponse,
+        VastAsset,
         VastTrackerAsset,
         VcpmAuctionPricingOption,
         VcpmFixedRatePricingOption,
@@ -1721,9 +1764,11 @@ def get_adcp_version() -> str:
         VerifyBrandClaimsResponseBulk,
         VerifyBrandClaimsSignedResponse,
         VerifyBrandClaimsSignedSuccessPayload,
+        VideoContent,
         WcagLevel,
         WebhookChallenge,
         WebhookChallengeResponse,
+        WebhookContent,
         WholesaleFeedEvent,
         WholesaleFeedWebhook,
         ZipAsset,

src/adcp/client.py

@@ -10,7 +10,7 @@
 import os
 import time
 import warnings
-from collections.abc import Callable, Iterator
+from collections.abc import Callable, Iterator, Mapping
 from datetime import datetime, timezone
 from typing import TYPE_CHECKING, Any, TypedDict, cast
 from uuid import uuid4
@@ -578,6 +578,9 @@ def __init__(
         """
         self._adcp_version: str = resolve_adcp_version(adcp_version)
         self._server_version: str | None = _resolve_server_version(server_version)
+        if type(allow_unauthenticated_webhooks) is not bool:
+            raise TypeError("allow_unauthenticated_webhooks must be a bool")
+
         self.agent_config = agent_config
         self.webhook_url_template = webhook_url_template
         self.webhook_secret = webhook_secret
@@ -5087,7 +5090,18 @@ async def _handle_mcp_webhook(
                     f"Webhook signature verification failed for agent {self.agent_config.id}"
                 )
                 raise ADCPWebhookSignatureError("Invalid webhook signature")
-        elif not self.allow_unauthenticated_webhooks:
+            if raw_body is None:  # Defensive type narrowing; verifier rejects this above.
+                raise ADCPWebhookSignatureError("Signed webhook raw body is required")
+            try:
+                authenticated_payload = json.loads(raw_body)
+            except (TypeError, ValueError, UnicodeDecodeError) as exc:
+                raise ADCPWebhookSignatureError("Invalid signed webhook body") from exc
+            if not isinstance(authenticated_payload, dict):
+                raise ADCPWebhookSignatureError("Signed webhook body must be a JSON object")
+            # Process the bytes that were authenticated, not a separately
+            # supplied parsed object that middleware could have transformed.
+            payload = cast(dict[str, Any], authenticated_payload)
+        elif self.allow_unauthenticated_webhooks is not True:
             raise ADCPWebhookSignatureError(
                 "MCP webhook cannot be authenticated because webhook_secret is not configured; "
                 "configure a secret or explicitly set allow_unauthenticated_webhooks=True only "
@@ -5106,11 +5120,8 @@ async def _handle_mcp_webhook(
                 task_type=task_type,
                 timestamp=datetime.now(timezone.utc).isoformat(),
                 metadata={
-                    "payload": (
-                        payload
-                        if preserve_legacy_identity
-                        else strip_legacy_creative_identity(payload)
-                    ),
+                    "task_id": webhook.task_id,
+                    "status": webhook.status.value,
                     "protocol": "mcp",
                 },
             )
@@ -5479,7 +5490,7 @@ def __init__(
         adcp_version: str | dict[str, str] | None = None,
         legacy_format_converter: LegacyFormatConverter | None = None,
         canonical_format_legacy_resolver: CanonicalFormatLegacyResolver | None = None,
-        allow_unauthenticated_webhooks: bool = False,
+        allow_unauthenticated_webhooks: bool | Mapping[str, bool] = False,
     ):
         """
         Initialize multi-agent client.
@@ -5493,8 +5504,10 @@ def __init__(
             signing: Optional RFC 9421 signing config forwarded to every
                 per-agent ADCPClient. The same identity signs traffic to
                 all agents. See ADCPClient.__init__ for details.
-            allow_unauthenticated_webhooks: Explicit compatibility escape
-                forwarded to each client. Defaults to False.
+            allow_unauthenticated_webhooks: Explicit compatibility escape.
+                A mapping scopes the opt-in by agent ID; omitted IDs remain
+                protected. A uniform True is accepted only for a single-agent
+                collection. Defaults to False.
             adcp_version: AdCP protocol release pin. Three forms:
 
                 - ``None`` (default): every per-agent ADCPClient resolves
@@ -5510,6 +5523,31 @@ def __init__(
                 See ADCPClient.__init__ for per-instance semantics.
                 Cross-major pins raise ConfigurationError at construction.
         """
+        agent_ids = {agent.id for agent in agents}
+        if isinstance(allow_unauthenticated_webhooks, Mapping):
+            unknown_ids = set(allow_unauthenticated_webhooks) - agent_ids
+            if unknown_ids:
+                unknown = ", ".join(sorted(unknown_ids))
+                raise ValueError(
+                    "allow_unauthenticated_webhooks contains unknown agent IDs: " + unknown
+                )
+            if any(type(value) is not bool for value in allow_unauthenticated_webhooks.values()):
+                raise TypeError("allow_unauthenticated_webhooks mapping values must be bools")
+            per_agent_unauthenticated = dict(allow_unauthenticated_webhooks)
+        else:
+            if type(allow_unauthenticated_webhooks) is not bool:
+                raise TypeError(
+                    "allow_unauthenticated_webhooks must be a bool or mapping of agent IDs to bools"
+                )
+            if allow_unauthenticated_webhooks is True and len(agents) > 1:
+                raise ValueError(
+                    "allow_unauthenticated_webhooks=True cannot be applied to multiple agents; "
+                    "pass a mapping keyed by the isolated agent IDs"
+                )
+            per_agent_unauthenticated = {
+                agent.id: allow_unauthenticated_webhooks for agent in agents
+            }
+
         # Per-agent map → resolve each pin individually for the dict form;
         # otherwise use the uniform pin for all agents.
         if isinstance(adcp_version, dict):
@@ -5528,7 +5566,7 @@ def __init__(
                     adcp_version=self._per_agent_versions.get(agent.id, default_pin),
                     legacy_format_converter=legacy_format_converter,
                     canonical_format_legacy_resolver=canonical_format_legacy_resolver,
-                    allow_unauthenticated_webhooks=allow_unauthenticated_webhooks,
+                    allow_unauthenticated_webhooks=per_agent_unauthenticated.get(agent.id, False),
                 )
                 for agent in agents
             }
@@ -5545,7 +5583,7 @@ def __init__(
                     adcp_version=self._adcp_version,
                     legacy_format_converter=legacy_format_converter,
                     canonical_format_legacy_resolver=canonical_format_legacy_resolver,
-                    allow_unauthenticated_webhooks=allow_unauthenticated_webhooks,
+                    allow_unauthenticated_webhooks=per_agent_unauthenticated.get(agent.id, False),
                 )
                 for agent in agents
             }