You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Webhook verifier's expected_adcp_use pin accepts only the deprecated 'webhook-signing' JWK purpose, rejecting the spec-mandated 'request-signing' #1018
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:
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:
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.
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.
Activity
bokelley commentedon Aug 6, 2026
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:
{"request-signing", "webhook-signing"}; replay-surface separation is already enforced by the independenttagcheck (adcp/webhook-signing/v1vsadcp/request-signing/v1), so wideningadcp_useacceptance is safe and spec-required.accepted_adcp_uses: frozenset[str] = frozenset()toVerifyOptions(additive, kw_only default — zero behavior change for all existing callers); updating_check_key_purposeto use set-membership when the frozenset is non-empty; and passingfrozenset({ADCP_USE_REQUEST, ADCP_USE_WEBHOOK})fromwebhook_verifier.pyinstead 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_tagcheck, notadcp_use.Implementation scope:
src/adcp/signing/verifier.pyaccepted_adcp_uses: frozenset[str] = frozenset()toVerifyOptionsafter line 148._check_key_purposecall at line 290 to passaccepted_adcp_uses=options.accepted_adcp_uses._check_key_purpose(line 643): replace the!= expected_adcp_useequality check withallowed = 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 tof"JWK.adcp_use {val!r} not in {sorted(allowed)}"(deterministic string, no set-repr churn).src/adcp/signing/webhook_verifier.pyADCP_USE_REQUESTfromadcp.signing.constants.expected_adcp_use=ADCP_USE_WEBHOOKat line 152 withaccepted_adcp_uses=frozenset({ADCP_USE_REQUEST, ADCP_USE_WEBHOOK}).tests/conformance/signing/test_webhook_signer.py:89—test_rejects_request_signing_keycurrently assertsWEBHOOK_SIGNATURE_KEY_PURPOSE_INVALIDwhen 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 (thetest_rejects_request_signing_tagtest at line 118 remains — wrong-tag rejection is still correct).tests/conformance/signing/test_webhook_receiver.py— Addtest_accepts_request_signing_jwk_purpose(positive:adcp_use="request-signing"key accepted end-to-end) and a negative test confirming a thirdadcp_usevalue (outside the two-value accept-set) is still rejected.frozenset()default on akw_onlyfrozen dataclass field means every existing caller that doesn't passaccepted_adcp_usesgets identical behavior via thefrozenset({expected_adcp_use})fallback. No public symbol is removed, renamed, or type-narrowed.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
feat: widen the conformant-receiver key-purpose accept-set and grade …