[meta] Coordinate RFC 9421 webhook signing migration — adoption telemetry + threshold + ownership

[EvgenyAndroid]

Context

The AdCP 3.0 release notes specify migrating from HMAC-SHA256 to RFC 9421
webhook signing, with HMAC deprecated and removed in 4.0. Two downstream
artifacts exist — PR #3064 (docs, @benminer) and #3360 (grade tooling,
@bokelley) — but there is no explicit coordination point for the migration
itself: no adoption telemetry, no "migration complete enough" threshold, and
no DRI for cross-cutting decisions.

This issue proposes establishing that coordination point before 4.0 removes
the HMAC opt-in.

Three concrete asks

1. Adoption telemetry
Directory-wide tracking of JWKS publication with adcp_use: "webhook-signing"
purpose keys. Today's data is anecdotal. Needs instrumentation — either in the
AdCP directory itself or as a contributed probe (see companion issue for a
concrete offer).

2. Adoption threshold
What fraction of active agents constitutes "migration complete enough" before
HMAC opt-in is removed in 4.0? Without a number on record, the deprecation
deadline is ad hoc. Suggested starting point: ≥80% of directory-listed agents
publishing valid JWKS with webhook-signing keys (webhook migration affects all
agent-to-agent comms, so coverage needs to be broad before removal).

Note: this threshold may differ from domain-specific work like Track A.0
(see companion issue). The webhook migration affects all agent-to-agent comms;
domain-scoped work like signals payments can ship into smaller subsets. WG
should set both numbers, not assume one threshold serves both.

3. Explicit coordination owner
PR #3064 and #3360 are downstream artifacts, not a coordination point. The
migration needs a DRI for decisions that cross docs, tooling, and schema
(algorithm choice, key publication format, deprecation timeline). @benminer —
flagging you as closest current owner; happy to discuss whether you want this
role or want to delegate.

Related

• PR docs: add RFC 9421 request signing guide #3064 — RFC 9421 request signing docs (@benminer)
• Grade tools: add OAuth and request signing setup evaluation #3360 — Grade tooling for signing setup evaluation (@bokelley)
• Companion issue: JWKS adoption baseline gates signal-payment chain-of-custody
  work (Track A.0) — shares adoption telemetry concerns; domain-specific
  threshold (≥30%) is separate from the migration-wide threshold proposed here

[bokelley]

Thanks for filing!

Triage

Classification: Tracking/meta — coordination proposal
Bucket(s): governance, rfc
Status: ready-for-human

What the experts said:
No expert consultation — the three asks are WG/org governance decisions, not technical questions where a protocol or product expert changes the outcome. The signing profile migration is explicitly version-level per the playbook ("signing profile changes are never patch-eligible"), so all three asks require a human decision before any code can land.

My take: This is a well-scoped coordination gap — RFC 9421 migration has two downstream artifacts (PR #3064, #3360) but no agreed threshold, telemetry plan, or DRI — and it legitimately needs WG input before 4.0 removes the HMAC opt-in. The three asks split across different decision owners: telemetry lives nearest to #3360 (grade tooling, @bokelley), threshold requires a WG vote, and DRI is a leadership call.

@bokelley, your call on two questions before this can advance:

1. Fold vs. standalone tracker? Should asks 1 (telemetry) and 2 (threshold) be folded into Grade tools: add OAuth and request signing setup evaluation #3360 (grade tooling, already milestoned 3.1.0) and Mandatory request signing for mutating calls (RFC 9421 HTTP Signatures or JWS) #2307 (RFC signing, active), or does the cross-cutting coordination scope warrant keeping this as a standalone meta tracker?
2. DRI + threshold process: If this moves forward, someone needs to own the migration-wide threshold vote at WG. @benminer is flagged in the issue — does that land with them, or should it route differently?

---

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

---

Generated by Claude Code

[bokelley]

Stepping back on the framing: the installed base of live buyer agents is ~empty right now, which changes what this issue is actually solving.

A migration threshold and adoption telemetry assume there's a population to migrate. There mostly isn't. What we have is an on-ramp problem, not a migration problem — the risk isn't that existing HMAC implementers won't rotate, it's that someone starting a new integration in May 2026 reads the docs, implements HMAC because it's the easier path, and is on a deprecation clock the day they ship.

That reshapes the asks:

• Telemetry — narrower than directory-wide. We need to know which named integrations are HMAC-only (probably countable on one hand), not survey a directory of mostly-dormant agents. Folds into Grade tools: add OAuth and request signing setup evaluation #3360.
• Threshold — premature. With ~zero installed base, "80% migrated" is meaningless. The real bar is "zero new HMAC implementers after date X," which is a docs/SDK question, not a WG vote.
• DRI — what's actually needed is owners for the on-ramp surfaces, which already exist: @benminer on docs: add RFC 9421 request signing guide #3064 (docs), me on Grade tools: add OAuth and request signing setup evaluation #3360 (grade tooling), plus SDK/scaffolding defaults. No new cross-cutting role.

The strongest version of this issue, in my view, is: make HMAC un-discoverable for new builds before 4.0. Concretely —

1. Docs default to RFC 9421; HMAC demoted to a "legacy, removed in 4.0" footnote, not presented as an alternative.
2. Grade tooling fails (not warns) any agent publishing only HMAC config.
3. SDK/scaffolding generates RFC 9421 keys by default; no HMAC flag.
4. Storyboard / getting-started paths use RFC 9421 end-to-end.

That's all docs + tooling, no governance ceremony. The migration "completes" when the on-ramp stops producing HMAC implementers, verified by inspection of those surfaces and a short named-partner check.

Keeping this open as the place to track that on-ramp work — but I'd reframe the body around "don't let new builders get this wrong" rather than directory-wide migration mechanics. Happy to edit the issue or have someone else take a pass.

[bokelley]

Following up on point 3 from my last comment — I checked, and the SDK already does this right. @adcp/client's signing module (src/lib/signing/) and its signing guide / build-seller-agent skill have zero HMAC references. Anyone scaffolding a new agent off the SDK gets RFC 9421 / JWKS by default, no opt-in needed.

That further narrows the on-ramp surface to docs (#3064) and grade tooling (#3360). The SDK side is already where we want it.

[bokelley]

Triage update

Classification: Tracking/meta
Bucket(s): governance
Status: deferred — blocked on #3064, #3360

@bokelley's comments settle both questions from the prior triage:

• Fold vs. standalone: telemetry and threshold fold into Grade tools: add OAuth and request signing setup evaluation #3360; no standalone coordination needed.
• DRI: existing surface owners (docs: add RFC 9421 request signing guide #3064 / @benminer, Grade tools: add OAuth and request signing setup evaluation #3360 / @bokelley) cover the work; no new cross-cutting role.

Revised on-ramp checklist per the updated framing:

Surface	Owner	Status
Docs default to RFC 9421; HMAC as legacy footnote	#3064 / @benminer	open
Grade tooling fails (not warns) on HMAC-only config	#3360 / @bokelley	open
SDK generates RFC 9421 keys by default	@adcp/client signing module	✓ done
Storyboard / getting-started paths — RFC 9421 end-to-end	untracked	needs a home

The storyboard item (4) doesn't appear in #3064 or #3360 scope as written — worth adding to one of those or leaving here as the remaining tracker item for this issue.

Removing needs-wg-review — per @bokelley's note, the on-ramp plan is all docs + tooling, no WG vote needed.

Blocked on #3064, #3360 — resurfaces on merge.

---

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

---

Generated by Claude Code

[EvgenyAndroid]

@bokelley — your reframe is correct and sharper than my original. Acknowledging the three corrections explicitly so they don't get lost on resurface:

1. Migration vs. on-ramp framing. I assumed an installed base when filing this. There isn't one. The 80% threshold I proposed is meaningless against ~zero — right metric is the one you stated: "no new HMAC implementers after date X." That's a docs/SDK/tooling enforcement question, not a WG vote.

2. DRI ask redundant. You + @benminer on #3360 + #3064 already cover the cross-cutting work. Adding a coordination role would be ceremony without function. Striking that ask.

3. Telemetry narrower than directory-wide. Surveying mostly-dormant agents is the wrong instrumentation. Folding into #3360's grade-tooling scope (named-partner check + on-ramp surface inspection) is the right cut.

The four-row checklist you proposed is the on-ramp scope as it should be:

Surface	Owner	Status
Docs default to RFC 9421; HMAC as legacy footnote	#3064 / @benminer	open
Grade tooling fails on HMAC-only config	#3360 / @bokelley	open
SDK generates RFC 9421 by default	@adcp/client signing module	✓ done
Storyboard / getting-started paths use RFC 9421 end-to-end	untracked	needs a home

Confirming the SDK side from my own scaffolding work — @adcp/client 5.25.1's signing module path is RFC 9421 / JWKS by default; I haven't seen an HMAC code path emerge in any new agent I've built off it.

On the storyboard item (4) — needs a home. I can take a pass at the AdCP storyboard / getting-started paths to inventory which currently reference HMAC vs RFC 9421 and file a follow-up issue against whichever surfaces still have HMAC-leaning examples. Happy to do that pre-emptively if it would help unstick the resurface trigger here. Otherwise leaving it under this issue's tracking until #3064 + #3360 land.

Folding companion issue #4206 (Track A.0 JWKS adoption baseline) under the same on-ramp framing — its 30% threshold has the same "premature against an empty installed base" problem. I'll update its body to reflect the on-ramp lens; the empirical adoption data is still useful as a baseline number for #3360's named-partner inventory, just not as a WG vote target.

Thanks for the substantive read.

— Ev (adcp.signal-stack.io)