Skip to content

fix(schema,skill): align HMAC framing to RFC 9421 default in reporting-webhook, auth-scheme, call-adcp-agent SKILL.md#4271

Merged
bokelley merged 2 commits into3.0.xfrom
claude/issue-4270-hmac-framing-skill-fix
May 9, 2026
Merged

fix(schema,skill): align HMAC framing to RFC 9421 default in reporting-webhook, auth-scheme, call-adcp-agent SKILL.md#4271
bokelley merged 2 commits into3.0.xfrom
claude/issue-4270-hmac-framing-skill-fix

Conversation

@bokelley
Copy link
Copy Markdown
Contributor

@bokelley bokelley commented May 8, 2026

Refs #4270

Summary

Closes the on-ramp framing gap identified in #4270 — surface 4 of the HMAC→RFC 9421 migration checklist (@bokelley's four-surface plan from #4205):

  • reporting-webhook.json: authentication.schemes description called HMAC-SHA256 "recommended for production" and authentication description had no deprecation signal. Fixed to match push-notification-config.json framing: both schemes are deprecated, RFC 9421 is the preferred profile. Since authentication remains in required[] in 3.x, the description now says explicitly "This field is required in AdCP 3.x; the requirement is removed in AdCP 4.0."
  • auth-scheme.json: Enum description was silent on deprecation. Updated to label both values as legacy, note that RFC 9421 is the default when authentication is optional, and that both are removed in 4.0.
  • skills/call-adcp-agent/SKILL.md: Added "Webhook signing — omit authentication for new integrations" section under "Non-obvious rules every buyer must follow." Closes the silent-default trap: a buyer agent reading only the SKILL.md previously had no guidance that omitting authentication selects the RFC 9421 default; reaching for the visible field in the schema would opt the seller into the deprecated HMAC path.

Non-breaking justification

Description-only changes. No field added or removed, no required arrays changed, no enum values added or removed, no wire behavior change. authentication remains required in reporting-webhook.json in 3.x — the schema structure is unchanged. Changeset: patch.

What is NOT in this PR (flagged for human review)

Two items from #4270 require human/WG decisions before landing:

  1. Making authentication optional in reporting-webhook.json — removing from required[] is a signing-profile change (playbook: "never patch-eligible: signing profile changes"). Needs minor bump and security doc update to explicitly cover reporting_webhook signing-mode selection. Routed to 3.1.x. The open question (per protocol-expert review): does the webhook_mode_mismatch downgrade-resistance rule already apply to reporting webhook registrations, or does the security doc need to be extended?

  2. artifact_webhook in create-media-buy-request.json — protocol-expert found the same stale "recommended for production" framing on the authentication.schemes description there. Not in scope of this PR to keep the change bounded; should be a follow-up.

Pre-PR review

  • code-reviewer: approved — all blockers resolved (dead link reverted, required-constraint contradiction fixed, adagents.jsonbrand.json corrected per security.mdx §webhook-callbacks); two nits noted (link wraps across two lines in SKILL.md, changeset description updated)
  • ad-tech-protocol-expert: approved — non-breaking per spec; description-only; brand.json is correct for buyer JWKS discovery (security.mdx line 1176, 1201-1206); authentication required constraint intact; changeset patch correct

Milestone note: gh CLI unavailable in this run environment — could not confirm the open 3.0.x patch milestone. Please set milestone to the active patch target before merge.

Triage-managed PR. This bot does not currently iterate on
review comments or PR conversation threads (only on the source
issue). To unblock:

  • Push fixup commits directly: gh pr checkout <num>
    fix → push.
  • Or re-trigger: comment /triage execute on the source
    issue.

See #3121
for context.

Session: https://claude.ai/code/session_01WczUEAGjbrADfTVX2MWEn6


Generated by Claude Code

…-webhook, auth-scheme, call-adcp-agent SKILL.md

Description-only fixes closing the on-ramp framing gap identified in #4270.
reporting-webhook.json called HMAC-SHA256 "recommended for production"; auth-scheme.json
had no deprecation signal. Both now align with push-notification-config.json's framing.
call-adcp-agent/SKILL.md gains a "Webhook signing" section so buyer agents learn to omit
authentication (selecting RFC 9421 default) rather than reaching for the visible legacy field.

No wire format changes; authentication remains required in 3.x per the existing schema.
The optionality change (making authentication optional + defining 9421 default on
reporting-webhook) is a signing-profile change routed to 3.1.x — see #4270.

https://claude.ai/code/session_01WczUEAGjbrADfTVX2MWEn6
Same description-only fix applied to artifact_webhook in
create-media-buy-request.json — drops "recommended for production" on
HMAC-SHA256, labels the authentication block as legacy, points new
integrations at the RFC 9421 webhook signing profile. Mirrors the
push-notification-config.json and reporting-webhook.json framing.

Closes the last on-ramp surface from #4270.
@bokelley bokelley marked this pull request as ready for review May 9, 2026 13:36
@bokelley bokelley merged commit 5d2e7be into 3.0.x May 9, 2026
9 checks passed
@bokelley bokelley deleted the claude/issue-4270-hmac-framing-skill-fix branch May 9, 2026 13:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

claude-triaged Issue has been triaged by the Claude Code triage routine. Remove to re-triage.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants