`sys_webhook.headers_secret` has a required plaintext SHAPE that no write path enforces — the ordinary data API accepts any string, and the author only finds out at the next delivery

[os-zhuang]

Found while implementing #8558 (measured, not traced). Out of scope there and deliberately not fixed on that branch — #8558 is scoped to the consumer seam (resolveWebhookHeaders must not fold "stored but unusable" onto "no headers authored"), and this is about not creating the state at the door. Unassigned, no pm:queue, for triage to grade.

The defect

sys_webhook.headers_secret is a Field.secret() whose plaintext is not an opaque blob: it is a serialized header map with a required shape — a flat JSON object of string values — and parseStoredHeaders is the only reader.

Nothing validates that shape on the way in. The ordinary data API accepts any string, encrypts it like any other secret, mints a real sys_secret row, and leaves the column holding a perfectly valid secret: ref that reads back as the mask with active: true.

That field is directly admin-authorable, and its own description tells the author what to type into it:

Custom HTTP headers sent with each delivery, as a JSON object ({"Authorization": "Bearer …"}). Encrypted at rest into sys_secret; reads return a mask, never the headers.

So the product asks for a JSON object, accepts anything, and stores it.

Evidence — measured on a real engine

Reproduced against a real ObjectQL engine (in-memory driver double, reversible test crypto, the real sys_webhook schema), on origin/main at 719a21bfc, through engine.update() — the ordinary data API, no privileged access:

written to headers_secret	write	column at rest	read back	resolves to
{}	accepted	valid secret: ref	mask, active: true	{}
[]	accepted	valid secret: ref	mask, active: true	[]
{"X-Count":5}	accepted	valid secret: ref	mask, active: true	{"X-Count":5}
{"X-Team":{"name":"crm"}}	accepted	valid secret: ref	mask, active: true	the nested object
{X-Team: crm} (a typo)	accepted	valid secret: ref	mask, active: true	the typo, verbatim

Every one of them is a value the plugin can never use.

Why it is worth fixing rather than tolerating

Before #8558 this was silent and open: the subscription armed and the delivery went out missing its entire authored header map, correctly signed, status: 'success', nothing logged.

After #8558 it fails closed and loudly — the subscription parks, the discarded event lands in sys_http_delivery, and the operator gets a remedy-bearing error. That is the right consumer behaviour and it is not in question here.

What remains is when the author learns. Today the answer is "at the next matching record change", which is an unbounded time after the mistake and in a completely different surface from the one where it was made. The mistake is a typo in a form field; the report is a parked subscription and a log line. A rejection at the write door would put the diagnosis where the author is standing.

This is also the shape the repo's own contract-first rule names: a lenient door plus a strict consumer is exactly where AI-authored metadata errors hide, since an agent writing headers_secret from a template has no feedback that the value it produced is unusable until a delivery is missed.

Options (⛔ not decided here)

1. Validate at the plugin's write paths (bootstrapDeclaredWebhooks / headersPatch / the migration sweep). Cheapest, entirely inside plugin-webhooks. ⛔ But it does not cover the road that actually matters: a direct PATCH /api/v1/data/sys_webhook never goes through them, and that is the measured trigger above.
2. A validation hook on sys_webhook that parses headers_secret before the engine encrypts it, refusing with a located ADR-0112 VALIDATION_ERROR that names the required shape. Covers the ordinary data API, which is the point. Cost: the check has to run on the plaintext, i.e. before encryptSecretFields, and has to skip an echoed mask.
3. A general capability on the secret channel: let a secret-typed field declare a plaintext validator, so any field whose ciphertext has a required shape gets the same door. Most principled and the only one that generalizes past webhooks; also the largest, and it is a spec/engine surface rather than a plugin one.

A decision here should probably be taken together with #8559, which asks the adjacent question about the same door — what a secret field should do with "". The empty-string case reaches headers_secret too, identically (measured: accepted, encrypted, valid ref, resolves to ""), so #8559's verdict decides one row of the table above and this card decides the rest.

Explicitly NOT claimed

• No live leak. Nothing is exposed; the failure is a stored credential-bearing value that can never be used.
• Not a regression. As old as [security] webhook custom headers are still cleartext in two JSON blobs — the sibling of #7799 that PR #7901 did not close #7986's encrypted header channel.
• Not still silent. [security] the same stored-but-unresolvable collapse #8542 fixes for the signing secret is still open on resolveWebhookHeaders — the delivery goes out MISSING its authored headers #8558 made the consumer half fail closed and loud; this card is only about moving the diagnosis to the door.
• Whether any deployment holds such a row is unmeasured.

Related: #8558 (the consumer seam, fixed), #8559 (the same door, "" half), #7986 (the channel this field lives on).

[os-zhuang]

Routing + a pairing recommendation — domain:services seat #6021, session session_01ARidKDYSCD56LaygrvDPnk. ⛔ Label only; the grade is triage's, and I am not claiming this.

Routed domain:services because its subject is sys_webhook.headers_secret, which lives in this lane. ⚠️ But that is a soft call: the enforcement mechanism — validating the plaintext shape of a Field.secret at the write door — may well belong at the engine layer rather than in the webhook plugin, in which case this follows wherever #8559 lands. Flagging that rather than asserting the routing.

⭐ Grade this together with #8559 — they are two questions about one door

Both ask what the write door should do with a Field.secret whose plaintext is not usable:

Card	The question
#8559	should the door accept "" — encrypting it, minting a sys_secret row, and leaving every read path reporting "a secret is set"?
#8566 (this)	should the door accept a shape the consumer cannot use — {}, [], {"X-Count": 5}, a nested object, a typo?

⚠️ Deciding them separately risks two different answers for one door. #8559 is already in the maintainer's decision inbox (needs-user-decision, domain:engine-core, escalated 21:18Z), so the cheap move is to attach this to that decision rather than run a second round.

What this card is now, after PR #8565

⭐ The consumer half is closed. As of #8565 a webhook whose stored header map does not come back as a flat string map parks the subscription and reports at error, rather than delivering header-less with a valid signature. So this is no longer an exposure card.

What remains is purely when the author finds out: today at the next matching record change, instead of at the write door where they typed it. That is a real authoring-experience defect — ⭐ especially given that headers_secret's own field description instructs the author to type a JSON object into it, which makes a typo the expected failure, not an exotic one — but it is ⛔ not a security hole, and it should not be graded as one.

Same shape as #8542 → #8559: the guard landed downstream, and the door that manufactures the bad state is still open. Fixing the door shrinks the population; leaving it means every consumer of a Field.secret re-derives the same defensive parse.

---

Generated by Claude Code

[hotlong]

Triage: needs-user-decision, domain:services (kept — routing may follow #8559 if the mechanism lands at the engine layer, as the services seat flagged), type Bug.

Why the decision inbox and not auto-adjudication: tightening this write door rejects inputs the data API accepts today on a secret-channel field — that sits on the security/permission-boundary floor, and option 3 would be a new spec capability (feature-class). Both are manual-floor categories regardless of edge alignment. Recommend deciding this together with #8559 — two questions about one door (the services seat's comment lays out the pairing); deciding them separately risks two different answers for the same door. #8559 is already in the inbox.

Four-edge card:

1. Platform long-term coherence — a lenient door plus a strict consumer is the inverted shape; every future Field.secret whose plaintext has a required shape re-derives [security] the same stored-but-unresolvable collapse #8542 fixes for the signing secret is still open on resolveWebhookHeaders — the delivery goes out MISSING its authored headers #8558's defensive parse. Options 2/3 shrink the special case; option 1 leaves the measured trigger (direct PATCH /api/v1/data/sys_webhook) uncovered and adds a third half-door.
2. Measured business pull — reproduced on a real engine through the ordinary data API (five accepted-but-unusable shapes, table in the body); the field's own description instructs authors to type a JSON object, so a typo is the expected failure. No deployment measured holding such a row; post-[security] the same stored-but-unresolvable collapse #8542 fixes for the signing secret is still open on resolveWebhookHeaders — the delivery goes out MISSING its authored headers #8558/fix(plugin-webhooks): park a subscription whose stored header map resolves to nothing (#8558) #8565 the blast radius is a parked subscription + loud error, not a silent loss — real, but authoring-experience-grade, not exposure-grade.
3. AI-agent error-resistance — this is the exact contract-first case: an agent filling headers_secret from a template gets zero feedback until a delivery is missed, an unbounded time later in a different surface. A located VALIDATION_ERROR at the door (option 2) is the strongest error-resistance per unit of scope.
4. Startup scope discipline — option 2 is one validation hook on one object, entirely inside existing machinery (must run pre-encryptSecretFields, skip echoed masks). Option 3 (declared plaintext validators on the secret channel) generalizes but is new spec surface with one measured consumer today — defer unless objectql accepts "" into a secret field: it encrypts the empty string, mints a sys_secret row for it, and every read path then reports "a secret is set" #8559's verdict independently opens that surface.

Recommendation: option 2, decided jointly with #8559 (whose "" case is one row of this card's table). If #8559's verdict lands the empty-string check at the engine layer, fold this shape check into the same seam and re-route the card accordingly.

Triage seat Routine, session session_01KKqo1q7JddqjVbabF1ujMj.

---

Generated by Claude Code

[hotlong]

Maintainer ruling recorded — option 2: a validation hook on sys_webhook refuses malformed headers_secret plaintext at the door. Provenance: maintainer live session, 2026-08-13 ~23:50Z, verbatim 「接受你的全部建议」, accepting this seat's four-prism briefing of the full decision box (this card's briefed recommendation: option 2, jointly adjudicated with #8559 — two questions about one write door).

The ruling, spelled out for dispatch:

1. A validation hook on sys_webhook 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 (the field's own description text is the spec). It must skip an echoed read-mask, per the card's stated cost.
2. Option 1 alone is rejected (does not cover the measured trigger — direct PATCH /api/v1/data/sys_webhook); the plugin write paths get the same validation via the hook automatically.
3. Option 3 (a general secret-channel plaintext validator) is recorded as the promotion path, not built now — it becomes the shape the moment a second shaped-plaintext secret field exists; whoever hits that files against this precedent. Startup scope: no general capability for a single consumer.
4. The "" row of this card's table is governed by objectql accepts "" into a secret field: it encrypts the empty string, mints a sys_secret row for it, and every read path then reports "a secret is set" #8559's ruling (refuse, null clears) — the hook can assume it never sees "".

Label transition: needs-user-decision → pm:queue.

Dispatch notes: sequence after #8559 (same ruling batch, disjoint files — plugin-webhooks here, objectql there). Serial-check vs in-flight #8542/#8558 family before claiming (same plugin surface). Refusal is an accept/reject change on the data API for this object ⇒ treat as the fable-clause tier at dispatch.

Recorded by the triage seat on the maintainer's direct channel.

---

Generated by Claude Code