@@ -0,0 +1,55 @@
+---
+'@objectstack/plugin-webhooks': minor
+---
+
+fix(plugin-webhooks): a webhook credential stored as cleartext inside `sys_webhook.definition_json` is refused, at the delivery path and at the write door (#10164)
+
+Clause-②: no (narrowing)
+
+**BREAKING** — shipped as `minor` under the launch-window convention
+(`check-changeset-no-major` refuses `major` until GA; breaking-ness is carried by
+this banner and the ADR-0087 disposition below, never by the level).
+
+**Webhooks that still carry the legacy cleartext shape STOP DELIVERING.** A
+`sys_webhook` row whose signing secret or custom header map exists only as a
+`secret` / `headers` key inside `definition_json` — with nothing stored in the
+encrypted `signing_secret` / `headers_secret` column — used to be delivered from
+that cleartext with a `warn`. It is now refused, dated `2026-09-23`:
+
+- **Delivery path.** The subscription is PARKED, the same fail-closed shape as an
+  encrypted credential that cannot be recovered: nothing is sent, and every
+  matching record change is recorded in `sys_http_delivery` as a `dead` row with
+  0 attempts, no signature and no headers. Its `error` names the refusal as
+  `[VALIDATION_ERROR/400]`, and the drop is reported once at `error`, with
+  `code: 'VALIDATION_ERROR'`, `status: 400`, `field: 'definition_json'` and the
+  refused `keys` in the log meta.
+- **Write door** (when `WebhookOutboxPlugin` is mounted, the standard mount). A
+  `sys_webhook` insert or update whose `definition_json` carries a `secret` or
+  `headers` key, whatever its value, is refused before anything is stored
+  (`VALIDATION_ERROR` / `400`, with `object`, `field` and `keys` on the error).
+  That covers a raw `PATCH /api/v1/data/sys_webhook`. It also covers a Setup-form
+  save that echoes back a legacy blob unchanged. Omitting `definition_json`, or
+  writing one without those keys, is unaffected. The plugin binds this refusal
+  itself, and it is not exported from the package entry: a host that composes
+  `AutoEnqueuer` on its own still gets the delivery-path refusal above, but not
+  this write-door refusal.
+
+**Fix.** Both remedies need a registered `CryptoProvider`
+(`engine.setCryptoProvider` — `LocalCryptoProvider` in dev, KMS/Vault in
+production), because writing a `secret`-typed column is itself refused without
+one. With a provider registered, either:
+
+- restart, and the boot sweep `migrateLegacyWebhookSecrets` moves both values into
+  their encrypted columns and strips them from `definition_json` in one update. The
+  subscription re-arms at the next refresh.
+- or re-author the webhook yourself. Write the key into `signing_secret` and the
+  header map into `headers_secret` (a JSON object of string values), then remove
+  both keys from `definition_json`.
+
+There is no transition path for a deployment that runs with no `CryptoProvider`.
+
+Unchanged: authoring. `defineWebhook({ secret, headers })` is written exactly as
+before, and the boot materializer still routes each value to its encrypted column.
+A row whose encrypted columns are set delivers exactly as before.
+
+<!-- adr-0087: not-required (no-migration-prescription) Nothing authored moves: `packages/spec` is untouched, `WebhookSchema` still declares `secret` and `headers`, and the materializer still routes them to their encrypted columns, so `objectstack migrate meta` has nothing to rewrite and the ledger has no row to gain. What is refused is a stored DATA-row shape on `sys_webhook`, and its converter already ships and runs at every boot: `migrateLegacyWebhookSecrets`, named in the refusal and in the Fix paragraph above. The other categories are closed on facts: the package publishes (not `unpublished`); no ADR-0087 id covers a data-row sweep (not `registered` / `already-registered`); and the change is runtime behaviour, not a TypeScript declaration (not `runtime-interface-only` / `type-surface-only`). -->
@@ -153,9 +153,12 @@ own column.
 
 A row the sweep has not converted — for example a pre-v17 row on a runtime with
 no `CryptoProvider` wired, where the encrypted write is refused and the row is
-deliberately left intact — is still delivered from the blob, with a `warn`
-naming those headers as cleartext. That fallback exists for rows written before
-the move; it is **not** a supported place to author. Never type a token into
+deliberately left intact — is **not** delivered: the subscription is parked and
+each event is recorded in `sys_http_delivery` as a dead row carrying a dated
+refusal, and a write that puts `secret` or `headers` into `definition_json` is
+refused (`VALIDATION_ERROR` / `400`). Both remedies need a registered
+`CryptoProvider`. With one registered, either restart so the sweep converts the
+row, or move the values into their encrypted columns yourself. Never type a token into
 `definition_json`: it is returned in full by the generic data API, and nothing
 ages it out.
 </Callout>
 
@@ -16,6 +16,10 @@ import {
     readLegacyHeaders,
     resolveWebhookHeaders,
 } from './webhook-headers.js';
+import {
+    WebhookLegacyCleartextError,
+    type LegacyDefinitionCredentialKey,
+} from './webhook-legacy-cleartext.js';
 
 /**
  * The authored trigger vocabulary, taken from the spec rather than restated
@@ -555,9 +559,10 @@ export class AutoEnqueuer {
      *     returns a mask, so presence is decidable here but the value is not;
      *     `resolveWebhookSecret` dereferences it server-side.
      *  2. `definition_json.secret` — a row not yet swept by
-     *     `migrateLegacyWebhookSecrets` (or hand-edited back in). Still honoured
-     *     so an un-migrated deployment keeps signing, and warned about once per
-     *     refresh so the exposure is visible rather than silently permanent.
+     *     `migrateLegacyWebhookSecrets` (or hand-edited back in). No longer
+     *     honoured: the subscription is PARKED with a dated refusal
+     *     ({@link refuseLegacyCleartext}). It used to sign from the cleartext
+     *     with a warning, which kept the exposure alive indefinitely.
      *  3. Neither — an unsigned webhook, which is a legitimate authored choice
      *     (`secret` is optional on the envelope).
      *
@@ -589,16 +594,11 @@ export class AutoEnqueuer {
             return false;
         }
 
-        const legacy = readLegacySecret(row?.definition_json);
-        if (legacy) {
-            this.logger?.warn?.(
-                `[webhook-auto-enqueuer] webhook '${sub.name}' still carries its signing secret as ` +
-                    `CLEARTEXT in definition_json, readable over the data API (#7799). Signing continues ` +
-                    `from it; run the boot sweep (migrateLegacyWebhookSecrets) with a CryptoProvider wired ` +
-                    `to move it into sys_secret.`,
-                { id: sub.id },
-            );
-            sub.secret = legacy;
+        // A key that exists ONLY as legacy cleartext in the blob is refused,
+        // not honoured — see `webhook-legacy-cleartext.ts`.
+        if (readLegacySecret(row?.definition_json)) {
+            this.refuseLegacyCleartext(sub, 'secret');
+            return false;
         }
         return true;
     }
@@ -644,21 +644,66 @@ export class AutoEnqueuer {
             return false;
         }
 
-        const legacy = readLegacyHeaders(row?.definition_json);
-        if (legacy) {
-            this.logger?.warn?.(
-                `[webhook-auto-enqueuer] webhook '${sub.name}' still carries its custom headers as ` +
-                    `CLEARTEXT in definition_json, readable over the data API (#7986) — that map is the ` +
-                    `ordinary place an Authorization header goes. Delivery continues from it; run the boot ` +
-                    `sweep (migrateLegacyWebhookSecrets) with a CryptoProvider wired to move them into ` +
-                    `sys_secret.`,
-                { id: sub.id },
-            );
-            sub.headers = legacy;
+        // Same refusal as the signing secret's, in the same stroke: refusing
+        // one passenger while honouring the other would leave half the retired
+        // location alive.
+        if (readLegacyHeaders(row?.definition_json)) {
+            this.refuseLegacyCleartext(sub, 'headers');
+            return false;
         }
         return true;
     }
 
+    /**
+     * Refuse a credential whose ONLY copy is the retired cleartext key in
+     * `definition_json` — PARK the subscription, the same fail-closed shape as
+     * an unrecoverable encrypted credential: nothing is sent, and every matching
+     * event is recorded as a dead `sys_http_delivery` row carrying the refusal.
+     *
+     * This replaced warn-and-accept. The warning said the right thing and
+     * changed nothing: the delivery still went out with a credential that
+     * `GET /api/v1/data/sys_webhook` hands to every persona that can read the
+     * object, and a warning nobody acts on is declared-but-not-enforced.
+     *
+     * Why `error`, said once: after the refusal `sys_webhook` still reads
+     * `active: true` while every matching record change goes undelivered — the
+     * AGENTS.md "Degradation log levels" question answers yes. The say-once
+     * ledger is the one {@link reportDrop} uses, on purpose: a subscription is
+     * either armed or parked, whichever credential parked it.
+     */
+    private refuseLegacyCleartext(sub: CachedSubscription, key: LegacyDefinitionCredentialKey): void {
+        const refusal = new WebhookLegacyCleartextError('delivery', [key], {
+            object: this.subscriptionsObject,
+            webhook: sub.name,
+        });
+        const meta = {
+            id: sub.id,
+            webhook: sub.name,
+            field: refusal.field,
+            keys: refusal.keys,
+            code: refusal.code,
+            status: refusal.status,
+        };
+        if (this.droppedForSecret.has(sub.id)) {
+            this.logger?.debug?.(
+                `[webhook-auto-enqueuer] webhook '${sub.name}' is still parked: its ${key} exists only as `
+                    + 'retired cleartext in definition_json',
+                meta,
+            );
+        } else {
+            this.droppedForSecret.add(sub.id);
+            const message = `[webhook-auto-enqueuer] ${refusal.message}`;
+            if (typeof this.logger?.error === 'function') {
+                this.logger?.error(message, refusal, meta);
+            } else {
+                this.logger?.warn?.(message, meta);
+            }
+        }
+        sub.secret = undefined;
+        sub.headers = undefined;
+        sub.parkedReason = `[${refusal.code}/${refusal.status}] ${refusal.message}`;
+    }
+
     /**
      * [#8022] Report a subscription dropped for an unresolvable signing key.
      *
 
@@ -103,7 +103,8 @@ describe('#9756 — sys_webhook declares its data-API exposure explicitly', () =
 
   it('leaves the reachable-cleartext fields reachable — the card is not closed by this', () => {
     // `url` (#8025, won't-fix on masking) and a legacy row's un-migrated
-    // `definition_json.headers` (#7986, still read by `readLegacyHeaders`) are
+    // `definition_json.headers` (#7986; no longer delivered from, but still held
+    // by a row the boot sweep could not convert) are
     // served by `get`/`list`, which the console requires. Stated as an
     // assertion so nobody reads the new `enable` block as having removed them.
     expect(apiExposureDenialReason(ENABLE, 'get')).toBeNull();
 
@@ -354,8 +354,10 @@ export const SysWebhook = ObjectSchema.create({
    * on this object was reduced. It was not, and `apiMethods` is the wrong
    * instrument for it: `url` (#8025 — won't-fix on masking, because the URL is
    * the routing key an operator must be able to see, search, sort and edit) and
-   * a legacy row's un-migrated `definition_json.headers` (#7986 —
-   * `readLegacyHeaders` in `auto-enqueuer.ts` still reads them and warns) are
+   * a legacy row's un-migrated `definition_json.headers` (#7986 — no longer
+   * delivered from, and refused at the write door, since
+   * `webhook-legacy-cleartext.ts`; a row the boot sweep could not convert
+   * still holds them until it does) are
    * both served by `get`/`list`, which is exactly what the console requires.
    * Any set that removes them removes the admin surface with them. A survey
    * that greps this file for `enable:` and stops is measuring the wrong thing;