Skip to content

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

Closed

Description

@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.

Activity

  1. added
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Aug 6, 2026
  2. bokelley commented on Aug 6, 2026

    @bokelley
    Contributor

    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

  3. added and removed
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Aug 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions