feat(webhooks): HMAC/bearer/Docker/Standard Webhooks delivery modes

Closes #478. Three additive features on the existing WebhookSender stack:

- WebhookSender.from_bearer_token / from_adcp_legacy_hmac /
  from_standard_webhooks_secret — alt-auth modes for buyers who
  authenticate at the gateway, run AdCP-3.x HMAC, or run Svix/Resend.
  from_adcp_legacy_hmac emits a one-shot DeprecationWarning mirroring
  the receiver-side warn-once so sender-only operators see the AdCP 4.0
  cutover signal at runtime.

- TransportHook Protocol + DockerLocalhostRewrite — opt-in URL rewrite
  before SSRF for senders running inside Docker. Hooks run pre-SSRF;
  SSRF stays authoritative on the rewritten URL. DockerLocalhostRewrite
  raises at sender construction unless allow_private_destinations=True
  so the rewrite isn't a silent no-op. apply_hooks rejects scheme/port
  changes so a hook cannot widen authority beyond hostname rewrite.

- adcp.signing.standard_webhooks — pure-Python standardwebhooks.com v1
  primitives with svix-Python interop tested both directions. Public
  SECRET_PREFIX constant lets test fixtures construct the canonical
  whsec_<base64> form via import (rather than embedding the literal
  pattern, which trips high-entropy-secret detectors on test data).
  decode_secret error path elides the underlying binascii exception
  message — that string can echo a fragment of the offending secret
  into operator logs.

Internal: extracted WebhookAuthStrategy Protocol + 4 strategies (JWK /
AdCP-legacy HMAC / Standard Webhooks / bearer). _send_bytes calls
self._auth.build_auth_headers per request — HMAC modes naturally
re-sign on resend() with a fresh timestamp, satisfying the receiver-
side 300s skew window. Strategies use field(repr=False) on secret-
bearing fields so the auto-generated dataclass repr cannot leak
credentials via tracebacks / vars() / faulthandler.

51 new tests (49 in-process + 2 env-gated Svix sandbox). Migration
doc at docs/webhooks/migration-from-fragmented-senders.md translates
common legacy sender patterns to the consolidated API.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: bokelley

docs/webhooks/migration-from-fragmented-senders.md

@@ -0,0 +1,274 @@
+# Migrating from fragmented webhook senders
+
+If your operator stack has multiple legacy webhook-sending paths — `requests.post`-and-handroll-the-headers in one service, a homemade HMAC helper in another, ad-hoc retries in a third — `WebhookSender` consolidates them. Same one-call delivery API across every authentication mode supported by AdCP and by common buyer ecosystems (Svix/Resend/operator-bearer).
+
+This guide is a translation table. Find your legacy pattern on the left; the right column is the equivalent on `WebhookSender`.
+
+The killer property: in every row, the bytes the sender signs are byte-for-byte the bytes that hit the wire. The classic "I signed `json.dumps(payload, separators=(',',':'))` but `requests` re-serialized with whitespace before POST" bug is impossible by construction.
+
+---
+
+## Auth modes
+
+`WebhookSender` exposes one classmethod per auth mode. Pick one per sender; if you need two modes (bearer-at-gateway plus end-to-end signature), construct two senders.
+
+### RFC 9421 JWK signing — the AdCP-conformant default
+
+```python
+from adcp.webhooks import WebhookSender
+
+sender = WebhookSender.from_jwk(webhook_signing_jwk_with_private_d)
+async with sender:
+    result = await sender.send_mcp(
+        url="https://buyer.example.com/webhooks/adcp/create_media_buy/op_abc",
+        task_id="task_456",
+        task_type="create_media_buy",
+        status="completed",
+        result={"media_buy_id": "mb_1"},
+    )
+```
+
+Use this for every AdCP-conformant buyer. JWK signing is the spec baseline.
+
+### `Authorization: Bearer <token>` — for buyers who authenticate at the gateway
+
+```python
+sender = WebhookSender.from_bearer_token("super-secret-token")
+async with sender:
+    result = await sender.send_mcp(url=..., task_id=..., status=...)
+```
+
+The body still goes through the same byte-exact marshaling, and `idempotency_key` still ends up inside the JSON for receiver dedup. There is no body signature; a buyer treating the bearer as the sole authenticity signal must enforce TLS pinning or mTLS at the transport layer to make a stolen token unusable.
+
+### AdCP-legacy HMAC-SHA256 — back-compat for AdCP 3.x receivers
+
+```python
+sender = WebhookSender.from_adcp_legacy_hmac(
+    secret=b"shared-secret-bytes",
+    key_id="kid_buyer_42",
+)
+async with sender:
+    result = await sender.send_mcp(url=..., task_id=..., status=...)
+```
+
+Wire format matches `verify_webhook_hmac` in `adcp.signing.webhook_hmac`: `X-AdCP-Signature: sha256=<hex>` over `f"{timestamp}.{body}"`, with `X-AdCP-Timestamp` set fresh on every delivery (resends produce a new signature over the same body bytes — receivers enforcing a 300s skew window won't reject the retry).
+
+Plan to migrate to JWK signing before AdCP 4.0; the legacy `authentication` field is removed in 4.0.
+
+### Standard Webhooks v1 — Svix / Resend / standardwebhooks.com interop
+
+```python
+sender = WebhookSender.from_standard_webhooks_secret(
+    "whsec_<base64-distributed-by-buyer>",
+    key_id="kid_svix_42",
+)
+async with sender:
+    result = await sender.send_mcp(url=..., task_id=..., status=...)
+```
+
+The constructor takes the canonical `whsec_<base64>` form Svix and Resend distribute and base64-decodes it internally. **Do not pass the literal `whsec_…` string to `from_adcp_legacy_hmac`** — the AdCP-legacy scheme HMACs against raw bytes, so you'd silently produce signatures Svix would reject. The two constructors enforce different secret-encoding contracts at the type level so this swap can't happen.
+
+Wire format per spec: `webhook-id` / `webhook-timestamp` / `webhook-signature: v1,<base64>` over `f"{webhook_id}.{webhook_timestamp}.{body}"`. Each delivery gets a fresh `webhook-id` so a Svix-style receiver caching ids for replay defense doesn't false-positive on a legitimate retry.
+
+---
+
+## Translation table
+
+### Pattern: hand-built bearer POST
+
+```python
+# Legacy
+import requests, json
+requests.post(
+    url,
+    data=json.dumps(payload),
+    headers={
+        "Authorization": f"Bearer {token}",
+        "Content-Type": "application/json",
+    },
+)
+```
+
+```python
+# Equivalent
+sender = WebhookSender.from_bearer_token(token)
+async with sender:
+    await sender.send_raw(
+        url=url,
+        idempotency_key=payload["idempotency_key"],
+        payload=payload,
+    )
+```
+
+`send_raw` requires `idempotency_key` as a kwarg — it's injected into the payload before serialization. Pass the same value you used to use; if your legacy code generated it ad hoc, call `generate_webhook_idempotency_key()` once and pass it in.
+
+### Pattern: hand-built HMAC POST with the sign-vs-body bug
+
+```python
+# Legacy — note the lurking serialization mismatch
+import hmac, hashlib, json, requests
+body_str = json.dumps(payload, separators=(",", ":"))
+sig = hmac.new(secret, body_str.encode(), hashlib.sha256).hexdigest()
+requests.post(
+    url,
+    json=payload,  # ← reserializes with default separators; signature mismatches
+    headers={"X-AdCP-Signature": f"sha256={sig}", ...},
+)
+```
+
+```python
+# Equivalent — sender signs and sends the same bytes
+sender = WebhookSender.from_adcp_legacy_hmac(secret, key_id="kid_buyer_42")
+async with sender:
+    await sender.send_raw(
+        url=url,
+        idempotency_key=payload["idempotency_key"],
+        payload=payload,
+    )
+```
+
+The "sign one byte sequence, POST a different one via `json=`" bug is one of the most common HMAC-webhook integration failures in the field. `WebhookSender` serializes once with `json.dumps(...)` and POSTs the same bytes via `httpx.AsyncClient.post(content=body)` — the bug class is impossible.
+
+### Pattern: hand-built Standard-Webhooks (Svix-style) POST
+
+```python
+# Legacy
+import base64, hmac, hashlib, json, time, requests, uuid
+secret_bytes = base64.b64decode(secret_str.removeprefix("whsec_") + "==")
+msg_id = f"msg_{uuid.uuid4().hex}"
+ts = str(int(time.time()))
+body = json.dumps(payload, separators=(",", ":")).encode()
+mac = hmac.new(secret_bytes, f"{msg_id}.{ts}.".encode() + body, hashlib.sha256).digest()
+requests.post(
+    url,
+    data=body,
+    headers={
+        "webhook-id": msg_id,
+        "webhook-timestamp": ts,
+        "webhook-signature": f"v1,{base64.b64encode(mac).decode()}",
+        "Content-Type": "application/json",
+    },
+)
+```
+
+```python
+# Equivalent
+sender = WebhookSender.from_standard_webhooks_secret(secret_str, key_id="kid")
+async with sender:
+    await sender.send_raw(
+        url=url,
+        idempotency_key=payload["idempotency_key"],
+        payload=payload,
+    )
+```
+
+### Pattern: custom Docker localhost rewrite
+
+```python
+# Legacy — homemade rewrite for "deliver from Docker container to host webhook"
+url = url.replace("localhost", "host.docker.internal")
+url = url.replace("127.0.0.1", "host.docker.internal")
+```
+
+```python
+# Equivalent — TransportHook composes with everything else
+from adcp.webhook_sender import WebhookSender
+from adcp.webhook_transport_hooks import DockerLocalhostRewrite
+
+sender = WebhookSender.from_jwk(
+    jwk,
+    transport_hooks=(DockerLocalhostRewrite(),),
+    allow_private_destinations=True,  # required — see note below
+)
+```
+
+`DockerLocalhostRewrite` requires `allow_private_destinations=True` at sender construction — the rewrite produces a private-IP destination, and SSRF would reject the rewritten URL otherwise. The flag is the operator's explicit opt-in; it raises at construction time if forgotten so the misconfiguration doesn't bite at first delivery.
+
+For Linux containers without `--add-host=host.docker.internal:host-gateway`, pass `DockerLocalhostRewrite(rewrite_to="172.17.0.1")` (Docker's default bridge gateway).
+
+### Pattern: per-call retry loop with backoff
+
+```python
+# Legacy
+import time
+for attempt in range(5):
+    try:
+        response = requests.post(url, ...)
+        if response.status_code < 500:
+            break
+    except requests.RequestException:
+        pass
+    time.sleep(2 ** attempt)
+```
+
+```python
+# Equivalent — WebhookDeliverySupervisor owns retry + circuit breaker + dedup
+from adcp.webhooks import (
+    InMemoryWebhookDeliverySupervisor,
+    WebhookDeliveryRequest,
+)
+
+supervisor = InMemoryWebhookDeliverySupervisor(
+    sender=sender,
+    # tune retry policy / circuit-breaker thresholds at construction
+)
+await supervisor.deliver(WebhookDeliveryRequest(url=..., payload=..., ...))
+```
+
+The supervisor handles retry policy, circuit-breaker state per buyer, and durable queueing. For Postgres-backed deployments, swap in `PgWebhookDeliverySupervisor` with the same Protocol — the calling code doesn't change.
+
+### Pattern: per-call SSRF check
+
+```python
+# Legacy
+host = urlparse(url).hostname
+ip = socket.gethostbyname(host)
+if ipaddress.ip_address(ip).is_private:
+    raise ValueError("private IP not allowed")
+requests.post(url, ...)  # ← TOCTOU: DNS may rebind between check and connect
+```
+
+```python
+# Equivalent — automatic. WebhookSender pins the validated IP into the
+# transport so DNS rebinding cannot swap the connect target between
+# validation and POST.
+sender = WebhookSender.from_jwk(jwk)  # SSRF runs on every send
+```
+
+The owned-client path rebuilds an `AsyncIpPinnedTransport` per request, runs the full SSRF range check (loopback / RFC 1918 / link-local / CGNAT / IPv6 ULA / multicast / cloud metadata), enforces an optional port allowlist, and pins the connection to the validated IP. There is no "remembered to call the SSRF helper" failure mode.
+
+If your infrastructure uses a vetted egress proxy with mTLS to a fixed buyer set, pass your own `client=httpx.AsyncClient(...)` and the sender will trust the operator's transport instead.
+
+### Pattern: ad-hoc retry that re-signs with the original timestamp
+
+```python
+# Legacy — replays the original signature, which receivers reject after
+# the 300s skew window.
+saved = (signed_headers, body_bytes)
+time.sleep(60)
+requests.post(url, data=saved[1], headers=saved[0])
+```
+
+```python
+# Equivalent — WebhookSender.resend re-signs the same bytes with a
+# fresh signature on every retry, preserving idempotency_key for dedup.
+result = await sender.send_mcp(url=..., task_id=..., status=...)
+if not result.ok:
+    retry = await sender.resend(result)
+```
+
+`resend` works in every auth mode. JWK regenerates the 9421 Signature/Signature-Input headers; HMAC modes generate a new timestamp + signature over the same body; bearer mode is a no-op (the auth header is timestamp-independent).
+
+---
+
+## Failure modes the new API closes
+
+* **Sign-vs-body divergence** — the sender owns marshaling; signed bytes equal sent bytes.
+* **Retry stales out the signature** — `resend` re-signs.
+* **Forgotten `idempotency_key`** — required kwarg on `send_raw`; receivers dedupe on it.
+* **DNS rebinding between SSRF check and POST** — automatic IP-pin on the owned-client path.
+* **Standard Webhooks secret encoding mistake** — typed split between `from_adcp_legacy_hmac(bytes)` and `from_standard_webhooks_secret(str)`.
+* **Docker rewrite without operator opt-in** — `DockerLocalhostRewrite` raises at construction unless `allow_private_destinations=True`.
+* **Hooks bypassing SSRF** — hooks run before SSRF, but SSRF validates the post-rewrite URL; the boundary holds.
+
+If your current sender doesn't have one of these properties, this is what you're trading up to.

src/adcp/signing/__init__.py

@@ -239,6 +239,14 @@
     async_sign_request,
     sign_request,
 )
+from adcp.signing.standard_webhooks import (
+    StandardWebhookError,
+    sign_standard_webhook,
+    verify_standard_webhook,
+)
+from adcp.signing.standard_webhooks import (
+    decode_secret as decode_standard_webhook_secret,
+)
 from adcp.signing.verifier import (
     VerifiedSigner,
     VerifierCapability,
@@ -343,6 +351,7 @@ def __init__(self, *args: object, **kwargs: object) -> None:
     "SignatureInputLabel",
     "SignatureVerificationError",
     "SignedHeaders",
+    "StandardWebhookError",
     "SigningAlgorithm",
     "SigningConfig",
     "SigningDecision",
@@ -371,6 +380,7 @@ def __init__(self, *args: object, **kwargs: object) -> None:
     "canonicalize_target_uri",
     "compute_content_digest_sha256",
     "content_digest_matches",
+    "decode_standard_webhook_secret",
     "default_capability_cache",
     "default_jwks_fetcher",
     "default_revocation_list_fetcher",
@@ -389,6 +399,7 @@ def __init__(self, *args: object, **kwargs: object) -> None:
     "resolve_and_validate_host",
     "sign_request",
     "sign_signature_base",
+    "sign_standard_webhook",
     "signing_operation",
     "unauthorized_response_headers",
     "validate_jwks_uri",
@@ -398,5 +409,6 @@ def __init__(self, *args: object, **kwargs: object) -> None:
     "verify_jws_document",
     "verify_request_signature",
     "verify_signature",
+    "verify_standard_webhook",
     "verify_starlette_request",
 ]