fix(plugin-webhooks): re-arm an encrypted-secret webhook when the CryptoProvider registers (#8022)

[huangyiirene]

Fixes#8022

What was wrong

For ~60s after every restart, a webhook whose signing_secret is encrypted — the population #7799 created — was not subscribed. A record change in that window produced no delivery and no sys_http_delivery row at all: no dead letter, no retry, no durable trace, while GET /api/v1/data/sys_webhook/ kept reading active: true. It self-healed at the next periodic refresh, so it was invisible to anyone not watching the window.

The fail-closed behaviour is unchanged

Dropping a subscription whose stored key cannot be recovered — rather than delivering it unsigned — is #7799's whole point and still holds. No unsigned delivery, no cleartext fallback, no weakened refusal. What was wrong is that a fail-closed drop outlived its own cause.

Root cause: an ordering, not a race

The filer read it off two log lines ~1.3s apart. It is stronger than that — it is deterministic. Plugins run inside kernel:ready, which runtime.start() completes (packages/core/src/kernel.ts Phase 3); the composition root calls engine.setCryptoProvider(...) only afterruntime.start() returns, unconditionally and on every host (packages/cli/src/commands/serve.ts, packages/verify/src/harness.ts). So AutoEnqueuer's first cache build always precedes the capability it needs, drops every secret-bearing row on what it could see, and nothing re-reads until the periodic refresh up to 60s later.

The shape landed

ObjectQL.onCryptoProviderChange(listener) reports the registration, fired after the provider is in place. AutoEnqueuer subscribes before its first build — the registration can land at any moment from start() onward, including mid-refresh — and rebuilds the cache when it fires.

Event-driven, not a shorter poll. Chosen over the alternatives because it fixes every host rather than one: moving the wiring earlier in serve.ts leaves apps/cloud, packages/verify, and every embedder with the same window, and a retry ladder only shrinks the hole. The engine is the sole party that knows the moment the provider arrives.

The re-arm deliberately does not join an in-flight refresh(): the build most likely running at that instant is the pre-registration one, so joining it would report success having re-armed nothing.

The channel is feature-detected, exactly as resolveSecretField already was — this plugin takes no dependency on @objectstack/objectql. An engine without it keeps today's behaviour with the periodic refresh as backstop.

The drop is no longer quiet

A subscription dropped for an unresolvable key now reports at error with the consequence and the fix in the message, carrying an ADR-0112 code/status pair (INTERNAL_ERROR/500) in its metadata — the same pair the seeder's refusal for the same cause already carried. Per AGENTS.md "Degradation log levels" it is said once per outage per webhook rather than every refresh cycle; a webhook that recovers and breaks again is loud again.

Half (b) — durability — is NOT closed here

A drop that leaves a sys_http_delivery row would need IHttpOutbox to admit a row that is durable but never sendable, and today it cannot: enqueue() only mints pending, and redeliver() resets any terminal row back to pending for a byte-for-byte replay. A row parked for a missing key has no signature, so the existing admin redeliver endpoint would send it unsigned — re-opening #7799 through a new door. That wants a design decision (a new column on the sys_http_delivery platform object, plus a redeliver refusal), not a rider on this fix. Recommending its own card; reasoning in full in the issue report.

Verification

• Reverse-verified: the window test is red on origin/main (2 failed / 10 passed of 12 — expected [] to have a length of 1) and green after (12/12). It runs with refreshIntervalMs: 0, so it cannot pass by waiting — the only thing that can re-arm the cache is the registration itself.
• Asserted on the durable record (the sys_http_delivery row and the receiver's HMAC), never on cache internals or call counts.
• [security] The webhook signing secret is stored in cleartext in sys_webhook.definition_json #7799/[security] Webhook HMAC signing secrets are persisted in cleartext on every sys_http_delivery row #7722 invariants re-asserted in the same tests: the delivery is signed from a key that exists only as ciphertext, the row carries signature and not the key, and while the key stays unresolvable nothing is delivered at all.

---

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 12, 2026 1:28pm

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/objectql, @objectstack/plugin-webhooks.

16 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/concepts/metadata-lifecycle.mdx(via @objectstack/objectql)
• content/docs/data-modeling/formulas.mdx(via packages/objectql)
• content/docs/deployment/migration-from-objectql.mdx(via @objectstack/objectql)
• content/docs/deployment/vercel.mdx(via @objectstack/objectql)
• content/docs/kernel/contracts/data-engine.mdx(via @objectstack/objectql)
• content/docs/kernel/runtime-services/examples.mdx(via packages/objectql)
• content/docs/kernel/services-checklist.mdx(via @objectstack/objectql)
• content/docs/kernel/services.mdx(via @objectstack/objectql)
• content/docs/permissions/authentication.mdx(via @objectstack/objectql)
• content/docs/permissions/system-context.mdx(via packages/objectql)
• content/docs/plugins/index.mdx(via @objectstack/objectql)
• content/docs/plugins/packages.mdx(via @objectstack/objectql, @objectstack/plugin-webhooks)
• content/docs/protocol/kernel/index.mdx(via @objectstack/objectql)
• content/docs/protocol/objectql/query-syntax.mdx(via packages/objectql)
• content/docs/protocol/objectql/state-machine.mdx(via @objectstack/objectql)

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

• content/docs/releases/implementation-status.mdx(via @objectstack/objectql, @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.