fix(webhooks): refuse malformed sys_webhook.headers_secret at the write door (#8566)

[qq9340100]

Fixes #8566

Implements the maintainer ruling of 2026-08-13 (comment 5287713447), option 2: a validation hook on sys_webhook that parses headers_secret before encryptSecretFields and refuses anything that is not a flat JSON object of string values, with a located ADR-0112 VALIDATION_ERROR naming the required shape, skipping an echoed read-mask.

What was wrong

headers_secret is a Field.secret() whose plaintext is not an opaque blob — it is a serialized header map with a required shape, and parseStoredHeaders is its only reader. Nothing validated that shape on the way in: the ordinary data API accepted any string, encrypted it, minted a real sys_secret row, and left a valid secret: ref that read back as the mask with active: true. All five spellings from the card's table were accepted and are unusable — {}, [], {"X-Count": 5}, a nested object, and {X-Team: crm}.

Not an exposure fix, and not graded as one. #8558/#8565 already closed the consumer half. What changes is when the author finds out: at the write door instead of at the next delivery.

The mechanism, and the one thing it turns on

A beforeInsert / beforeUpdate hook on sys_webhook, bound by WebhookOutboxPlugin before its first seeded write — the same shape as the bindWebhookProvenanceStamp hook next door.

Order is load-bearing and was measured, not assumed: before* hooks are dispatched before encryptSecretFields on every write path (insert engine.ts:8031 vs :8070; update :8817 vs :8998/:9206). One step later the plaintext is gone. The suite pins this rather than asserting it — every refusal asserts no sys_secret cipher row was minted, which is only true if the gate ran first.

The verdict reuses parseStoredHeaders, the consumer's own reader, so the door refuses exactly what the consumer cannot use and the two cannot drift into a second shape rule.

What stays accepted

Valid flat string maps (as JSON text, or as an authored object the engine serializes into the same form); null to clear; an omitted key; an echoed read-mask, so the ordinary Setup-form round-trip is untouched; and an existing secret: ref.

"" is deliberately passed through to #8559's EmptyCredentialWriteError rather than re-refused here — one door, one owner, one message.

The refusal never echoes the value

This column carries credentials. A message quoting the input would print an Authorization: Bearer … into logs and error bodies, re-opening in the diagnostic exactly what #7986 moved this field onto the encrypted channel to close. The diagnostic names header keys and value types only — pinned by a test that plants a token and asserts it is absent from the message while the key is present.

⛔ Option 3 (a general secret-channel plaintext validator) is not built — recorded as the promotion path for when a second shaped-plaintext secret field exists. ⛔ No second check on the plugin's own write paths; they inherit the hook.

Verification — all at HEAD 89685159e

• pnpm --filter @objectstack/plugin-webhooks test — 112 passed (8 files), 19 new
• pnpm --filter @objectstack/plugin-webhooks typecheck — clean
• Reverse verification, direction predicted before running and matched exactly: neutering the verdict function turns 15 tests red — the 10 table refusals, the object-valued refusal, the 3 message pins, and the unbind pin — while the "" test, every accept test, and the gate-unbound counterfactual stay green. Restored from the commit; tree verified clean.
• Gates: check:nul-bytes, check:error-code-casing, check:test-source-alias, check:type-source-resolution, check:i18n (plugin-webhooks in sync), check:engine-double-contract, check:query-options-erasure, check:type-check-coverage, check:type-check-debt --re-measure, check:empty-changeset, check:adr-0087-registration — all green.
• ⚠️ check:i18n first reported "Nothing was checked" because @objectstack/cli was unbuilt; re-run after building it, and it is that second run reported above.

Changeset: .changeset/webhook-headers-secret-shape-gate.md (@objectstack/plugin-webhooks: patch).

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 14, 2026 5:44pm

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/plugin-webhooks.

2 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/automation/webhooks.mdx (via packages/plugins/plugin-webhooks)
• content/docs/plugins/packages.mdx (via @objectstack/plugin-webhooks)

⛔ 1 release-owned page(s) also reference the affected code. These are read-only:

• content/docs/releases/implementation-status.mdx (via @objectstack/plugin-webhooks)

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.