Registry change feed: webhook anti-replay (timestamp + delivery sequence in HMAC)

[bokelley]

Problem

The webhook envelope spec in `specs/registry-change-feed.md` signs only the request body with HMAC. There's no timestamp and no delivery sequence in the signed material. A captured webhook can be replayed indefinitely (same body, same signature, same `latest_event_id`).

Surfaced during security review of the catalog change feed — same gap exists upstream. The catalog feed spec already adopts the fix (see commit 3f32784); this issue tracks porting it to the registry feed.

Proposed fix

Mirror the catalog-feed shape from PR #4767:

```
POST https://buyer.example.com/hooks/registry
X-Registry-Signature: sha256={hmac}
X-Registry-Event: property.created
X-Registry-Timestamp: 2026-05-19T11:00:00Z
X-Registry-Delivery-Seq: 4421
```

• HMAC is computed over the canonical string `{timestamp}\n{delivery_seq}\n{body}` (newline-separated).
• Receivers MUST reject signatures whose timestamp is more than 5 minutes skewed from receive time.
• `delivery_seq` is strictly monotonic per subscription. Receivers de-dupe on `(subscription_id, delivery_seq)`.
• Retried deliveries reuse the original `delivery_seq` — receivers dedupe on the sequence, not the signature.

Scope

• Update `specs/registry-change-feed.md` §Webhook Delivery with the new envelope
• Update the receiver-side validation guidance
• Open a follow-up to land the matching signer changes in the central registry implementation
• Cross-reference the catalog feed's anti-replay text once landed

Compatibility

Adding new signed headers is breaking for existing subscribers (the signature they verify is over a different string). Two paths:

1. Versioned signer: ship a new `X-Registry-Signer-Version: 2` header; v1 signers continue to compute over body-only for a deprecation window. Subscribers honor whichever they receive.
2. Coordinated cut: announce date, switch all subscribers in one window. Easier for the central registry where there's a single operator.

Lean toward (1) for safety. The registry feed has external subscribers (TMP routers, RegistrySync clients) that can't all be coordinated.

Related

• PR feat(catalog-sync): v3.1 catalog sync cluster (#4761, #4762, #4763) #4767 — catalog change feed spec where this gap was first identified
• Catalog-feed anti-replay text: `specs/catalog-change-feed.md` §Anti-replay (commit 3f32784)

[bokelley]

Triage

Classification: Feature request (security gap)
Bucket(s): spec / protocol, security-sensitive
Status: ready-for-human

What the experts said:

• security-reviewer: Gap is real and breaking — body-only HMAC is indefinitely replayable; authorization.granted replay is the critical attack path. Option A needs subscription_id in the signed canonical string and a published v1 deprecation end-date; without a hard deadline the original gap persists indefinitely for non-migrated subscribers.
• ad-tech-protocol-expert: AdCP 3.x already has RFC 9421 as the webhook signing baseline (created/expires + nonce cache already covers anti-replay). A new bespoke HMAC scheme creates a third signing profile that will also need a 4.0 sunset — and the same concern applies to PR feat(catalog-sync): v3.1 catalog sync cluster (#4761, #4762, #4763) #4767's catalog feed anti-replay design.

My take: Both experts agree: real gap, breaking change, Flag is right. They split on the fix — bespoke HMAC versioning (Option A, mirrors PR #4767) vs. aligning to the existing RFC 9421 profile already live on 3.x mutating calls (Option B). The answer also determines whether #4767's catalog feed anti-replay design needs revisiting before that PR merges. @bokelley, your call: A or B?

Option A — Versioned HMAC (mirrors catalog-feed from PR #4767):

- X-Registry-Signature: sha256={hmac-over-body}
+ X-Registry-Signature:    sha256={hmac-over-canonical}
+ X-Registry-Signer-Version: 2
+ X-Registry-Timestamp:    2026-05-19T11:00:00Z
+ X-Registry-Delivery-Seq: 4421
// canonical: {subscription_id}\n{timestamp}\n{delivery_seq}\n{body} (UTF-8 bytes)
// experts flag: needs published v1 end-date; subscription_id required in signed material

Option B — RFC 9421 (align to existing 3.x webhook signing profile):

Content-Digest: sha-256=:base64...:
Signature-Input: sig1=("content-digest" "@path");keyid="...";nonce="abc";created=1747648800;expires=1747649100
Signature: sig1=:base64...:
// Anti-replay via nonce cache + expires. Same profile as mutating AdCP calls.
// Eliminates a third bespoke scheme; TMP router RFC 9421 support needs confirming.

---

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

---

Generated by Claude Code