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",