Signature requirement is triggered by a nested payload field, contradicting 3.2's "policy before body parsing" rule

[KonstantinMirin]

Summary

The requirement to sign a request is triggered by the presence of a nested field inside the request payload. This makes a transport-security decision a function of application-payload semantics at arbitrary depth, and it is the one remaining place where verifier policy cannot be selected before the body is parsed.

AdCP 3.2 established the opposite principle elsewhere in the same document, and the spec already documents the better design for this specific case — so this is a request to finish a migration that is mostly already built, not a new design.

The rule today

docs/building/by-layer/L1/security.mdx (at dc4a454b3):

• :69 — a buyer opts into the legacy HMAC-SHA256 webhook scheme by populating authentication.credentials at any of four nested locations: push_notification_config, accounts[].notification_configs[], sync_principal.configuration.notification_configs[], sync_agent_notification_configs.notification_configs[].
• :1537 — the error taxonomy makes a signature mandatory when "request payload carries a field that triggers signing regardless of required_for membership".

So a verifier must read nested payload fields to learn whether the request it is reading was required to be signed.

Note the surface has grown: at v3.1.1 there were two trigger locations; there are now four.

Why this is worth changing

1. It contradicts the principle 3.2 just established. :1469 states that "the endpoint's trusted configuration and negotiated capability select this policy before body parsing or dispatch", and that an operation name or JSON-RPC method inside an unbound body must not drive verifier policy. That reasoning is correct and the webhook-credential escalation is the remaining exception to it.

2. The spec already recommends the replacement. :1631 — "Buyers SHOULD negotiate HMAC-mode out-of-band at onboarding … Durable per-counterparty mode selection in operator records is not MITM-mutable the way a per-request field is."

3. The negotiation surface now exists. 3.2 added legacy_hmac_fallback (:1583) with false documented as the recommended posture. The capability channel this rule needs is already shipped.

The escalation rule at :1537 exists to contain a threat created by expressing the preference in the body in the first place (:1630 — an on-path mutator can strip or inject the block). Removing the per-request trigger removes the threat rather than containing it.

Proposal

Make webhook-signing mode a negotiated, per-counterparty property rather than a per-request payload field:

1. legacy_hmac_fallback plus the seller's onboarding record become the authoritative selector for HMAC vs 9421 webhook signing.
2. Deprecate the per-request authentication block as a mode trigger on the 3.x timeline it already has (removed in 4.0).
3. Once mode no longer comes from the payload, drop the signature escalation at :1537 entirely — it has nothing left to protect.

This is backwards-compatible as a 3.x deprecation: sellers that already set legacy_hmac_fallback: false are unaffected.

Alternative

If the per-request trigger must stay, it would help implementers to state explicitly that a conforming verifier is required to parse the request body before it can determine whether a signature was required, and to say how that interacts with the :1469 "policy before body parsing" rule. Right now the two read as incompatible and implementers have to guess which governs.

---

Found while implementing a 3.1.1 verifier; re-verified against main at dc4a454b3 before filing.

[bokelley]

Triage

Classification: Feature request (security-architecture spec change)
Bucket(s): spec / protocol, security-sensitive
Status: ready-for-human
Milestone: Spec Backlog (#9)

What the experts said:

• ad-tech-protocol-expert: Contradiction confirmed and implementation-blocking; out-of-band mode selection has universal industry support (RFC 9421 §7.2, OpenRTB, GAM — none use a body-field signing trigger); legacy_hmac_fallback scaffolding already shipped; 3.x deprecation + 4.0 removal is the correct staged path; migration requires explicit precedence language for the transition window.
• security-reviewer: Both attack paths are exploitable by any body-modifying on-path intermediary (TLS-terminating proxy, WAF — common topologies): inject forces request_signature_required on non-9421 buyers (targeted DoS on webhook registration); strip corrupts signing mode and triggers webhook_mode_mismatch outage; :1537 condition (b) also conflates two structurally distinct triggers into one error code, preventing incident root-cause classification.
• security-reviewer-deep: The alternative path introduces a TOCTOU vulnerability — verifiers must parse unauthenticated bytes to determine whether those bytes required authentication — and cannot be safely specified away; the WG disposition should explicitly record the rejection; correct ordering is legacy_hmac_fallback-authoritative first, then deprecate condition (b), then 4.0 removal.

My take: All three experts converge on the proposal; no expert found a reason to prefer the alternative. @bokelley, the needed call is: ratify Option A and authorize the normative language changes for the next minor release, or hold for a different release vehicle. The experts recommend the WG record explicitly why Option B was rejected.

---

Option A — legacy_hmac_fallback becomes the sole authority (proposal):

// security.mdx :1469 — add precedence statement
+ For webhook-signing mode selection, `legacy_hmac_fallback` in the seller's
+ capability advertisement is the sole authority. When `legacy_hmac_fallback: false`,
+ sellers MUST reject requests carrying authentication.credentials with
+ `webhook_hmac_not_supported` (HTTP 400) — not `request_signature_required`.

// security.mdx :1537 — deprecate condition (b)
- (b) request payload carries a field that triggers signing regardless of
-     required_for membership (e.g., push_notification_config.authentication)
+ [Deprecated in 3.x: superseded by legacy_hmac_fallback. Removed in 4.0.]

// New error code added to transport taxonomy (minor bump)
+ webhook_hmac_not_supported  — no retry; HMAC not supported at this seller endpoint

Sellers already at legacy_hmac_fallback: false are unaffected. Implementations that used the body-field trigger for mode selection (not credential delivery) must migrate to the capability-advertisement selector. authentication.credentials still delivers the HMAC key when legacy mode is in effect; only its role as a mode-selection signal is removed.

Option B — document condition (b) as a defined exception to :1469 (alternative; experts recommend rejecting):

// security.mdx :1537 — add ordering note
+ NOTE: Condition (b) is a defined exception to the policy-before-body rule at :1469.
+ Verifiers evaluating (b) MUST capture whether a Signature-Input header was present
+ before body parsing; (b) then applies to the already-parsed body.

Deep security analysis concludes this introduces a TOCTOU vulnerability that cannot be safely specified away: the verifier parses unauthenticated bytes to determine whether those bytes required authentication, and an attacker who can modify those bytes controls whether the escalation fires. Documenting the exception makes the vulnerability normative and weakens the :1469 invariant for future spec evolution.

---

Triaged by Claude Code. Session: https://claude.ai/code/session_01MCrmo4e7XukWJR7VoLowky

---

Generated by Claude Code