schemas(reporting-webhook, auth-scheme): deprecate HMAC-SHA256 recommendation, point at RFC 9421

.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.

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

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