From c8b242d5ab4336a24abd286319b9f658b1afd18a Mon Sep 17 00:00:00 2001 From: evgen Date: Fri, 8 May 2026 19:01:33 -0400 Subject: [PATCH] schemas(reporting-webhook, auth-scheme): deprecate HMAC-SHA256 recommendation, point at RFC 9421 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two schema-description-only edits, no normative change. Surfaces existing push-notification-config.json framing at adjacent schemas where SDK authors actually read them. reporting-webhook.json — the authentication.schemes description previously said HMAC-SHA256 was "recommended for production", contradicting push-notification-config.json's framing (both Bearer + HMAC-SHA256 are deprecated legacy fallback, removed in AdCP 4.0). New buyers reading the schema in isolation were being steered toward the legacy on-ramp. Description now mirrors push-notification-config — both schemes deprecated, removed in 4.0, see push-notification-config for the precedence model. auth-scheme.json — the enum's description was silent about deprecation. SDK authors loading the enum in isolation had no signal these were legacy options. Description now states the values are scoped to the legacy authentication block and points readers at the RFC 9421 default. Out of scope (surfaced for maintainer triage in #4270): reporting-webhook still has authentication in `required`, which means reporting webhooks have no opt-in path to RFC 9421 today. Mirroring push-notification-config's structural shape (auth block optional, omitted = 9421 default) is a separate normative question. Closes the schema-description sub-item of #4270. Co-Authored-By: Claude Opus 4.7 (1M context) --- ...0-deprecate-hmac-recommendation-in-schemas.md | 16 ++++++++++++++++ .../schemas/source/core/reporting-webhook.json | 2 +- static/schemas/source/enums/auth-scheme.json | 2 +- 3 files changed, 18 insertions(+), 2 deletions(-) create mode 100644 .changeset/4270-deprecate-hmac-recommendation-in-schemas.md diff --git a/.changeset/4270-deprecate-hmac-recommendation-in-schemas.md b/.changeset/4270-deprecate-hmac-recommendation-in-schemas.md new file mode 100644 index 0000000000..a1575e41ea --- /dev/null +++ b/.changeset/4270-deprecate-hmac-recommendation-in-schemas.md @@ -0,0 +1,16 @@ +--- +--- + +schemas(reporting-webhook, auth-scheme): deprecate HMAC-SHA256 recommendation, point at RFC 9421 webhook profile + +Two schema-description-only edits, both surgical, no normative change. Surfaces existing `push-notification-config.json` framing at adjacent schemas where SDK authors actually read them. + +`reporting-webhook.json` — the `authentication.schemes` description previously said HMAC-SHA256 was "recommended for production". This contradicts `push-notification-config.json` (which marks both Bearer and HMAC-SHA256 as the deprecated legacy fallback, removed in AdCP 4.0). New buyers reading the schema in isolation were being steered toward the legacy on-ramp. Description now mirrors push-notification-config's framing — both schemes deprecated, removed in 4.0, see push-notification-config for the precedence model. + +`auth-scheme.json` — the enum's top-level description was silent about deprecation. SDK authors loading the enum in isolation had no signal these were legacy options. Description now states the values are scoped to the legacy `authentication` block and points readers at the RFC 9421 default. + +Out of scope (surfaced for maintainer triage): + +- `reporting-webhook.json` still has `authentication` in `required: [...]`, which means reporting webhooks have no opt-in path to RFC 9421 today. Mirroring `push-notification-config.json`'s structural shape (auth block optional, omitted = 9421 default) is a separate normative question — filed at #4270 as the broader on-ramp inventory. + +Closes the schema-description sub-item of #4270. diff --git a/static/schemas/source/core/reporting-webhook.json b/static/schemas/source/core/reporting-webhook.json index cb9a295533..d620af4277 100644 --- a/static/schemas/source/core/reporting-webhook.json +++ b/static/schemas/source/core/reporting-webhook.json @@ -21,7 +21,7 @@ "properties": { "schemes": { "type": "array", - "description": "Array of authentication schemes. Supported: ['Bearer'] for simple token auth, ['HMAC-SHA256'] for signature verification (recommended for production)", + "description": "Array of authentication schemes. Supported: ['Bearer'] for simple token auth, ['HMAC-SHA256'] for legacy shared-secret signing. Both are deprecated and will be removed in AdCP 4.0; new integrations SHOULD use the RFC 9421 webhook profile (see push-notification-config.json's `authentication` description for the precedence model).", "items": { "$ref": "/schemas/enums/auth-scheme.json" }, diff --git a/static/schemas/source/enums/auth-scheme.json b/static/schemas/source/enums/auth-scheme.json index 1ae1063f76..ad5b84e390 100644 --- a/static/schemas/source/enums/auth-scheme.json +++ b/static/schemas/source/enums/auth-scheme.json @@ -2,7 +2,7 @@ "$schema": "http://json-schema.org/draft-07/schema#", "$id": "/schemas/enums/auth-scheme.json", "title": "Authentication Scheme", - "description": "Authentication schemes for push notification endpoints", + "description": "Authentication schemes for the legacy push-notification `authentication` block. Both values are deprecated and will be removed in AdCP 4.0; new integrations SHOULD omit the `authentication` block and use the RFC 9421 webhook profile (see push-notification-config.json).", "type": "string", "enum": [ "Bearer",