[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

[os-zhuang]

Found while implementing #8542 (the signing-secret half). Out of scope there and deliberately not fixed on that branch — that card is scoped to the #7799 signing invariant on signing_secret, and this is the sibling credential. Unassigned, no pm:queue, for triage to grade.

The defect

resolveWebhookHeaders (packages/plugins/plugin-webhooks/src/webhook-headers.ts) ends the same way resolveWebhookSecret used to:

const plain = await resolver.resolveSecretField(object, String(row.id), WEBHOOK_HEADERS_FIELD);
return parseStoredHeaders(plain);

parseStoredHeaders returns undefined for null, for the empty string, and for anything that does not parse as a flat string map — deliberately, and correctly, for its own job. But that undefined is then the same value the function returns three lines earlier for "this webhook stores no headers at all", and AutoEnqueuer.attachHeaders acts on that second reading: it returns true, the subscription arms, and the delivery goes out without the header map the author declared.

That contradicts the file's own stated intent, in its header comment:

It does not deliver partially. A row whose stored headers cannot be resolved DROPS the subscription rather than delivering it with the headers missing — see resolveWebhookHeaders.

It does not, today. Only a throwing resolver reaches attachHeaders's catch; a resolver that answers null does not.

Why this matters, in this seam's own words

The reasoning is already written down in attachHeaders, and it is why this is not merely cosmetic:

a missing Authorization looks self-announcing, since the receiver answers 401 … But that is only the AUTHENTICATED case. Against an endpoint that does not require the header — a routing X-Tenant-Id, an X-Environment: staging — the delivery SUCCEEDS while quietly deviating from the configuration the author wrote, and nothing anywhere records that it went out incomplete.

So the failure direction is the same one #8542 is about: silent and open, on a row that keeps reading active: true with headers_secret masked, i.e. still reporting "custom headers are configured".

Evidence and its limits

⚠️ Traced by reading the call path, not exercised. The three null-producing states were measured for the signing-secret field on #8542's branch against a real ObjectQL engine, and resolveSecretField is field-agnostic — the same three apply here by construction:

1. the sys_webhook row is deleted between the enqueuer's cache read and the per-row dereference (resolveSecretField opens if (!row) return null);
2. the column holds something that is not a secret: ref. Measured as reachable only through a write that BYPASSES the engine (a column edited in SQL, a dump restored without its sys_secret rows, a seed script writing at driver level) — the engine's own write path drops an echoed read-mask and re-encrypts cleartext;
3. the stored value decrypts to the empty string. For signing_secret this was measured reachable through the ORDINARY data API, which accepts "", encrypts it, and leaves a valid ref behind (filed separately as the objectql half).

⛔ What is not measured here: that an unresolvable headers_secret actually produces a header-less delivery end to end. That is the first thing whoever takes this card should do, exactly as #8542's dispatch required — the webhook-secret-at-rest.test.ts harness (real engine, real write path, production enqueue wiring) already has everything needed, and #8542's a stored signing secret that resolves to nothing (#8542) block is a working template.

Shape of a fix (⛔ not decided here)

The precedent is now in the tree: #8542 made resolveWebhookSecret raise WebhookSecretUnresolvableError when presence is established (the masked read proves a value is stored) and the dereference answers nothing, so it reaches attachSecret the way a throwing resolver already did — park the subscription, durable record (#8069), say-once remedy-bearing error (#8043) carrying the ADR-0112 pair. The same asymmetry holds here: headersPatch and attachHeaders both already decide presence from row[WEBHOOK_HEADERS_FIELD] != null.

⚠️ One thing that is genuinely different and needs a decision rather than a copy: parseStoredHeaders also returns undefined for a stored value that decrypts fine but is not a flat string map. That is a resolvable value the plugin is refusing to use, not an unresolvable one, and it may deserve a different report than "the credential could not be recovered".

Relationship to the neighbouring cards

• Not a duplicate of [security] webhook custom headers are still cleartext in two JSON blobs — the sibling of #7799 that PR #7901 did not close #7986, which is about the headers being cleartext at rest; the sys_webhook.definition_json half of that has landed (headers_secret exists, the boot sweep migrates it) and its remaining surface is sys_http_delivery.headers_json in service-messaging. This card is about what happens when the encrypted channel it created cannot be read back.
• Sibling of [security] a stored webhook signing secret that resolves to null is treated as "authored unsigned" — the subscription arms and delivers UNSIGNED #8542, same mechanism, different credential. Independent of it: [security] a stored webhook signing secret that resolves to null is treated as "authored unsigned" — the subscription arms and delivers UNSIGNED #8542's fix is on webhook-secret.ts and does not touch this path.

[hotlong]

Triage: lands in packages/plugins/plugin-webhooks/src/webhook-headers.ts (resolveWebhookHeaders) plus the attachHeaders seam ⇒ domain:services confirmed; queued pm:queue, type Bug — the file's own header comment declares "does not deliver partially / DROPS the subscription", and the current code delivers header-less on a null-answering resolver: declared ≠ enforced, so this is an invariant-restoring fix with an in-tree precedent (#8542's WebhookSecretUnresolvableError shape), not a design question.

Dispatch notes for the services seat:

• First deliverable is the end-to-end measurement the card itself names (the card is honest that this path is traced, not exercised): drive an unresolvable headers_secret through the webhook-secret-at-rest.test.ts harness before writing the fix; [security] a stored webhook signing secret that resolves to null is treated as "authored unsigned" — the subscription arms and delivers UNSIGNED #8542's "resolves to nothing" block is a working template. premise_still_valid: false is a legitimate outcome.
• The parse-failure case (parseStoredHeaders returning undefined for a value that decrypts fine but is not a flat string map) is a genuinely distinct condition — resolvable-but-refused, not unresolvable. Distinct wording is fine; the fail-closed disposition (park, durable record, say-once error) should be shared. If the dev finds this fork contract-shaped rather than wording-shaped, report needs_decision instead of choosing silently.
• Serial constraint: same package and same enqueuer seam as in-flight [security] a stored webhook signing secret that resolves to null is treated as "authored unsigned" — the subscription arms and delivers UNSIGNED #8542 (pm:dispatched). The card claims file-disjointness ([security] a stored webhook signing secret that resolves to null is treated as "authored unsigned" — the subscription arms and delivers UNSIGNED #8542 is on webhook-secret.ts), but attachHeaders/attachSecret live in the same enqueuer surface — clear [security] a stored webhook signing secret that resolves to null is treated as "authored unsigned" — the subscription arms and delivers UNSIGNED #8542's PR first or verify disjoint file surface at claim time.

Size/model suggestion: M, opus.

---

Generated by Claude Code

[os-zhuang]

Claim: PM loop round 17 — services seat #6021
Session: session_01ARidKDYSCD56LaygrvDPnk
Branch: claude/issue-8558-headers-unresolvable-collapse
Worktree: objectstack-issue-8558
File surface: packages/plugins/plugin-webhooks/src (webhook-secret.ts's header path, auto-enqueuer.ts) + tests + changeset
Container & model: M, mode:subagent, model: claude-opus-5
Serial constraints cleared — PR #8560 merged 21:24Z, so this package has no PR in flight.

⭐ This is the sibling of #8542, and its fix has just landed next door

#8542 closed the identical collapse on the secret path 4 minutes ago. That PR is the template, and it is worth reading before writing anything:

• The seam raises WebhookSecretUnresolvableError once presence is established and the dereference answers nothing.
• ⭐ AutoEnqueuer.attachSecret needed no new branch — the refusal lands in the catch that already parks the subscription, so [security] a dropped webhook subscription leaves no durable record — and the naive fix hands an operator a redeliver button that sends UNSIGNED #8069's parking, the durable sys_http_delivery record and the say-once error all applied unchanged.
• The control pins that a webhook authored without the credential still arms and delivers.

⛔ But do not assume the header path is symmetric. #8542's own measurement is the reason: its card listed three triggers and got the ranking inverted — the one filed as an obscure provider edge case turned out to be the only one reachable from the ordinary data API, while two of another trigger's three sub-causes were falsified outright. A fix written from that card's prose would have hardened the narrow paths and left the wide one open.

⚠️ Measure these — the card says its own evidence is a construction argument

The filer states the three triggers apply "by construction (resolveSecretField is field-agnostic)" and that the header path was NOT exercised. ⛔ Do not carry that forward.

1. Reproduce on the header path directly. parseStoredHeaders(null) returning the same undefined used for "no headers stored" is the claim — verify it, at file:line, on today's main.
2. Does the presence asymmetry hold for headers? [security] a stored webhook signing secret that resolves to null is treated as "authored unsigned" — the subscription arms and delivers UNSIGNED #8542's fix stands entirely on it: a set secret reads back as the engine's mask, an unset one as null. ⚠️ headers_secret is a map, not a scalar — confirm the masked read gives the same decidable presence signal, or the whole fix shape changes.
3. Is the empty-value trigger reachable here too? That was the widest one for secrets ("" accepted by the ordinary data API, encrypted, valid ref minted). An empty map may or may not travel the same road.
4. ⚠️ Grade the consequence honestly. A missing signature means deliveries stop being authenticated. A missing header map means the receiver may reject outright, or may accept unauthenticated — and it is not obvious which is worse. The card says this contradicts the file's own documented intent; establish what actually reaches the wire before deciding how loud the failure should be.

⛔ Non-relitigable

• Fix at the seam, one rule in one place — ⛔ not per-caller. Same reasoning as [security] a stored webhook signing secret that resolves to null is treated as "authored unsigned" — the subscription arms and delivers UNSIGNED #8542.
• ⛔ Do not regress [security] a stored webhook signing secret that resolves to null is treated as "authored unsigned" — the subscription arms and delivers UNSIGNED #8542's fix or PR fix(service-messaging,plugin-webhooks): a dropped webhook subscription leaves a durable record that can never be redelivered unsigned #8541's RedeliverGuard. Both pin behaviour on this file. The guard converts this seam's error only; "could not check" must never read as "allowed".
• ⛔ Do not widen into [security] webhook custom headers are still cleartext in two JSON blobs — the sibling of #7799 that PR #7901 did not close #7986's territory — sys_http_delivery.headers_json cleartext-at-rest is a different question, carried by [security] sys_http_delivery.headers_json still stores webhook credentials in cleartext — and every services-lane shape for fixing it is structurally wrong #8118 / [security] sys_email.headers_json stores custom headers cleartext — same shape as sys_http_delivery; adopt whatever remedy #8118 lands, do not decide it twice #8149. This card is about a header map that cannot be resolved, not one stored in the clear.
• Fixes #8558 is correct.

Requirements

Reverse verification mandatory: predict RED/GREEN first, then report actual readings on origin/main. ⚠️ Vacuity trap: a pin whose webhook was never given headers exercises only the legitimate-no-headers arm and passes against a completely unfixed tree — every pin must have headers genuinely stored and unresolvable, and should assert its own precondition the way #8560's pins do. Control required: a webhook authored with no headers must still arm and deliver. Derive gates with dispatch-gates.mjs; ⚠️ convention-scoped ones are not path-derivable — check:durability-log-level, check:error-code-casing, check:nul-bytes, check:engine-double-contract, and note check:i18n fires here because this package owns an i18n-extract.config.ts. Changeset required; ⛔ never touch content/docs/releases/. Draft PR; ⛔ do not flip it yourself.

---

Generated by Claude Code