Webhook verifier's expected_adcp_use pin accepts only the deprecated 'webhook-signing' JWK purpose, rejecting the spec-mandated 'request-signing'

[KonstantinMirin]

Found while widening our own conformant-receiver test shim to match the AdCP 3.1.1 accept-set for #1291 (salesagent-z6nr.31).

Problem

signing/webhook_verifier.py hard-codes expected_adcp_use=ADCP_USE_WEBHOOK (i.e. the string "webhook-signing") when building VerifyOptions for webhook verification:

# webhook_verifier.py:152
options = VerifyOptions(
    ...,
    expected_adcp_use=ADCP_USE_WEBHOOK,
)

verifier.py's _check_key_purpose (:607-621) then rejects any JWK whose adcp_use isn't byte-equal to that one pinned value, raising REQUEST_SIGNATURE_KEY_PURPOSE_INVALID:

# verifier.py:621
if jwk.get("adcp_use") != expected_adcp_use:
    raise SignatureVerificationError(REQUEST_SIGNATURE_KEY_PURPOSE_INVALID, step=8, ...)

Per AdCP 3.1.1 security.mdx, this is backwards. Step 8 of the verifier checklist reads:

Verify the JWK's use is "sig", key_ops includes "verify", and adcp_use is "request-signing" ... the deprecated "webhook-signing" value MUST also be accepted for backward compatibility. Reject on any other outcome with webhook_signature_key_purpose_invalid.

And :1438 states plainly: "webhook-signing" is DEPRECATED; verifiers MUST still accept it, but new signers SHOULD publish and sign with "request-signing" keys only.

So the accept-set for a webhook verifier is {"request-signing", "webhook-signing"} — never a single value in either direction. As currently written, webhook_verifier.py accepts only the deprecated value and rejects the one the spec directs new signers to use, which is the exact inverse of the intended backward-compatibility behavior.

Suggested direction

Widen the webhook verifier's key-purpose check to accept either ADCP_USE_REQUEST or ADCP_USE_WEBHOOK, matching the request-signing verifier's own (correct) handling, rather than pinning VerifyOptions.expected_adcp_use to a single value. Since expected_adcp_use on VerifyOptions is a single string compared with !=, this likely needs either a small accept-set parameter on VerifyOptions/_check_key_purpose, or the webhook verifier trying both purposes itself.

Workaround in our own tests

We widen our own test-side conformant-receiver shim to attempt "request-signing" first and retry once with "webhook-signing" only on REQUEST_SIGNATURE_KEY_PURPOSE_INVALID, so our own signing keys are graded correctly while this is open.

[bokelley]

Triage

Classification: Bug
Bucket(s): signing (no matching label exists in this repo — noted for label gap)
Status: ready-to-implement

What the experts said:

• ad-tech-protocol-expert: Bug confirmed — AdCP 3.1.1 step 8 mandates the webhook verifier accept {"request-signing", "webhook-signing"}; replay-surface separation is already enforced by the independent tag check (adcp/webhook-signing/v1 vs adcp/request-signing/v1), so widening adcp_use acceptance is safe and spec-required.
• code-reviewer: Recommends adding accepted_adcp_uses: frozenset[str] = frozenset() to VerifyOptions (additive, kw_only default — zero behavior change for all existing callers); updating _check_key_purpose to use set-membership when the frozenset is non-empty; and passing frozenset({ADCP_USE_REQUEST, ADCP_USE_WEBHOOK}) from webhook_verifier.py instead of the current single-value pin.

My take: Both experts converge cleanly. The current code is the exact inverse of the spec's intent — it accepts only the deprecated value and rejects the one new signers are directed to use. The fix is additive at both the API and the runtime level; cross-surface replay protection is unaffected because it rests on the expected_tag check, not adcp_use.

Implementation scope:

• src/adcp/signing/verifier.py
  • Add accepted_adcp_uses: frozenset[str] = frozenset() to VerifyOptions after line 148.
  • Update the _check_key_purpose call at line 290 to pass accepted_adcp_uses=options.accepted_adcp_uses.
  • Update _check_key_purpose (line 643): replace the != expected_adcp_use equality check with allowed = accepted_adcp_uses if accepted_adcp_uses else frozenset({expected_adcp_use}); if jwk.get("adcp_use") not in allowed: raise ...; fix the error message to f"JWK.adcp_use {val!r} not in {sorted(allowed)}" (deterministic string, no set-repr churn).
• src/adcp/signing/webhook_verifier.py
  • Import ADCP_USE_REQUEST from adcp.signing.constants.
  • Replace expected_adcp_use=ADCP_USE_WEBHOOK at line 152 with accepted_adcp_uses=frozenset({ADCP_USE_REQUEST, ADCP_USE_WEBHOOK}).
• tests/conformance/signing/test_webhook_signer.py:89 — test_rejects_request_signing_key currently asserts WEBHOOK_SIGNATURE_KEY_PURPOSE_INVALID when a "request-signing" JWK is presented with the webhook tag. Under 3.1.1 this scenario MUST succeed; invert to a positive round-trip assertion (the test_rejects_request_signing_tag test at line 118 remains — wrong-tag rejection is still correct).
• tests/conformance/signing/test_webhook_receiver.py — Add test_accepts_request_signing_jwk_purpose (positive: adcp_use="request-signing" key accepted end-to-end) and a negative test confirming a third adcp_use value (outside the two-value accept-set) is still rejected.
• Non-breaking rationale: frozenset() default on a kw_only frozen dataclass field means every existing caller that doesn't pass accepted_adcp_uses gets identical behavior via the frozenset({expected_adcp_use}) fallback. No public symbol is removed, renamed, or type-narrowed.
• Required checks: pytest tests/conformance/signing/, mypy src/adcp/signing/verifier.py, ruff check . / black --check ..

---

Triaged by Claude Code. Session: https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID}

---

Generated by Claude Code