[security] The webhook signing secret is stored in cleartext in `sys_webhook.definition_json`

[huangyiirene]

Filed unassigned as an out-of-scope finding from #7722 / PR #7798. Not a delivery/outbox row, so it is outside that issue's acceptance criteria — recording it rather than folding it into that PR.

What

A webhook subscriber's HMAC signing secret is persisted verbatim inside the definition_json textarea on sys_webhook:

• packages/plugins/plugin-webhooks/src/bootstrap-declared-webhooks.ts:203 stores the entire validated Webhook envelope — secret included (packages/spec/src/automation/webhook.zod.ts:201) — as definition_json: JSON.stringify(wh).
• auto-enqueuer.ts:parseRow reads it back out (defn.secret) to sign deliveries.

sys_webhook is an admin-authorable object with no restrictive enable.apiMethods, so the column comes back on an ordinary GET /api/v1/data/sys_webhook read, secret and all. Same class of exposure as #7722 — same blast radius, since the signature is the receiver's only proof of origin — but on the subscriber row rather than the per-attempt delivery row.

#7722 removed the per-attempt copies (every sys_http_delivery row held one); this is the remaining cleartext location, and unlike the delivery table it is not covered by a retention window.

Why it is a separate card

The delivery-row fix could be made without a secret store at all: a delivery's body is fixed at enqueue, so the outbox signs once and keeps only the signature. The subscriber row cannot use that trick — it holds the secret because future deliveries need to be signed with it, so fixing this one means actually binding the value into the sys_secret cipher store (the Field.secret() channel, or the datasource-binder shape) and resolving it server-side at enqueue.

That reaches further than #7722's surface: the sys_webhook schema, the boot seeder, the Studio authoring form, and a migration path for existing rows.

Suggested shape (not prescriptive)

Move secret out of the definition_json blob into its own Field.secret() column on sys_webhook, so the engine encrypts on write into sys_secret and masks on read, and have the auto-enqueuer's cache resolve it through engine.resolveSecret() when it builds an enqueue input. Worth checking in the same pass whether any other config object stores an authored credential inside a JSON blob, where the secret field type cannot reach it.

Acceptance criteria

• The signing secret is not recoverable from sys_webhook over the data API, for any persona.
• Signing still works end-to-end: a delivered payload's x-objectstack-signature verifies by recomputing HMAC-SHA256 over the raw body (not by asserting "no error").
• A regression guard reads the table directly after authoring a subscriber and asserts the secret's bytes are absent — the byte-level scan shape [security] Webhook HMAC signing secrets are persisted in cleartext on every sys_http_delivery row #7722's at-rest test and the datasource path both use.

[os-zhuang]

Triage: pm:queue + domain:services + target:v17.

• Classification: concrete defect with named landing sites — a signing credential recoverable over the ordinary data API is not observation-class.
• Routing anchor (read on origin/main @ 098b629, not from the card): packages/plugins/plugin-webhooks/src/bootstrap-declared-webhooks.ts persists definition_json: JSON.stringify(wh) with secret included (spec webhook.zod.ts:201), and auto-enqueuer.ts:309 reads secret: defn.secret back out of the parsed blob. plugin-webhooks ⇒ domain:services per the lanes table. The suggested Field.secret() re-binding may add a packages/spec sub-change later — if so that piece transfers to the spec seat at dispatch time (contract-first), but the principal landing site is the plugin.
• target:v17 rationale (binary test): class ① — a published-surface security hole a user hits today: any persona with read access to admin-authorable sys_webhook retrieves the receiver's HMAC secret, and the signature is the receiver's only proof of origin. Same class as [security] Webhook HMAC signing secrets are persisted in cleartext on every sys_http_delivery row #7722 (whose delivery-row half is already in flight via PR fix(service-messaging): store the delivery signature, not the signing secret (#7722) #7798); this is the remaining cleartext location, with no retention window bounding it.
• Dedup: distinct from [security] Webhook HMAC signing secrets are persisted in cleartext on every sys_http_delivery row #7722 by design (subscriber row vs per-attempt rows; the filer recorded the split rationale at filing). No other open card or PR covers sys_webhook.definition_json. Not Blocked-by: fix(service-messaging): store the delivery signature, not the signing secret (#7722) #7798 — different files, independently landable; the shared byte-scan test shape is a convenience, not a dependency.

本评论来自分诊座位 Routine（#5474 试点），不构成认领。

---

Generated by Claude Code

[huangyiirene]

Claim: PM loop round 4
Session: session_01JVfWSQN9RDDGwdVSmMc29x
Branch: claude/issue-7799-webhook-subscriber-secret
Worktree: cloud session's own clone (mode:cloud)
Domain: domain:services
File surface: packages/plugins/plugin-webhooks/src/** (bootstrap-declared-webhooks.ts:203 writes the envelope into definition_json; sys-webhook.object.ts for the column; auto-enqueuer.ts parseRow/cache for the read side). ⚠️ If the fix forces a change to the authoring envelope in packages/spec/src/automation/webhook.zod.ts (rather than only to how the plugin PERSISTS it), that is the spec seat's — STOP and report; the dispatch carries that fork.
Container & model: M (security, storage-shape change with a migration story), mode:cloud, model: opus
Priority: target:v17 release-board item + security — takes precedence over the other queue card this round (板上项优先, selection rule).
Serial constraints cleared: #7722/PR #7798 (the sibling delivery-row fix) is MERGED; this card is its explicitly-scoped-out remainder, so no overlap. No in-flight PR touches plugin-webhooks.

---

Generated by Claude Code

[huangyiirene]

PR: #7901 (draft) · Branch: claude/issue-7799-webhook-subscriber-secret

What I measured

• bootstrap-declared-webhooks.ts:203 — definition_json: JSON.stringify(wh), envelope with secret. Premise confirmed verbatim.
• auto-enqueuer.ts:309 — secret: defn.secret → signingSecret at :388/:483. Confirmed.
• packages/spec/src/automation/webhook.zod.ts:201 — secret: z.string().optional(). Untouched. No packages/spec/src/** file is modified, so the os-regen 驱动指示的 gen:schema 在 merge 未 commit 时运行,会把 authorable-surface 锚点倒退回旧 merge-base —— 生成器写入、门全绿、静默撤销 main 的锚点推进 #5370/gen:schema rmSync 整个 json-schema/ 会顺手抹掉 gen:openapi 的产物,rest 的 openapi 路由测试随后 503 假红——check:generated 原地跑 build-schemas 也触发 #5371 regen traps never armed.
• packages/objectql/src/secret-fields.ts + engine.ts:4640-4838 — the secret FieldType channel: encrypt-on-write into sys_secret, secret:<id> ref on the row, maskSecretFields on read, resolveSecret(ref) for privileged consumers.
• packages/services/service-datasource/src/datasource-secret-binder.ts — the alternative "binder + plain ref column" shape.
• packages/cli/src/commands/serve.ts:2691-2712 — where the ICryptoProvider actually lives.

What I falsified — both halves of §3

Your hypothesis was that the fix belongs entirely at the persistence seam inside the plugin. It cannot. Two measurements, and each independently rules out the plugin-local shapes you listed:

1. The datasource-binder shape is not reachable from this plugin. createDatasourceSecretBinder needs an ICryptoProvider. The provider is constructed by the host in serve.ts and handed to the engine via engine.setCryptoProvider(...); it is never registered as a kernel service, and ObjectQL.cryptoProvider is private. ctx.getService() cannot reach it, so the plugin cannot encrypt anything itself. That leaves exactly one door: write cleartext into a secret-typed column once and let the engine's own write path wrap it.

2. The Field.secret() channel had no reader. maskSecretFields (engine.ts:4744) replaces the ref with SECRET_MASK on every find/findOne, unconditionally and after hooks — deliberately, and unlike the __search strip next door it has no isSystem carve-out. So resolveSecret's own docstring ("privileged consumers use resolveSecret() against the stored ref") described a path no consumer could enter: there was no supported way to obtain the ref. That is precisely why the datasource subsystem keeps its handle in a plain unmasked column instead of using the field type — and why the webhook secret was sitting in a JSON blob.

So the fix is plugin-local plus one additive engine accessor: ObjectQL.resolveSecretField(object, recordId, field) (driver-level row read + the existing decrypt, refusing any field not declared type: 'secret' so it cannot become a mask bypass over a password field, which is plaintext at rest per ADR-0100). ~30 lines in objectql, no contract/spec change, feature-detected from the plugin. Flagging it plainly since it is outside the seam you scoped.

§4 STOP FORK did not trigger. The authoring envelope is unchanged — defineWebhook({ secret }) is written exactly as before. The only file under packages/spec/ is liveness/webhook.json, whose secret evidence prose pointed at the cleartext path being removed (status stays live); that is a ledger, not a schema, so no gen:schema/gen:docs/gen:openapi products are implicated.

The shape I landed

sys_webhook gains signing_secret: Field.secret(); the seeder writes the authored key there and serializes the envelope minus secret into definition_json; the enqueuer recovers the plaintext through resolveSecretField() on each cache refresh and hands it to the outbox unchanged, so the wire signature is byte-identical and no receiver moves. A boot sweep (migrateLegacyWebhookSecrets) heals rows the seeder deliberately never rewrites — managed_by: 'admin' and customized: true — writing the encrypted copy in the same update that strips the blob, under system context so it does not freeze a package row. Re-seeding compares the declared key against the stored plaintext before writing, otherwise every boot would mint an orphan sys_secret row per webhook. Fail-closed throughout: with no CryptoProvider the engine refuses the write, so the webhook is skipped and the legacy row left intact rather than the hole being re-opened in a new column.

Against your acceptance criteria

1. Byte-level scan ✅ — substring assertion on the whole serialized row from the normal read path and on the bytes at rest, plus definition_json specifically. Driven against a real ObjectQL engine with the real SysWebhook schema (only the driver is a double), because an engine fake would echo back whatever it was handed and pass while the product stayed broken.
2. HMAC recompute ✅ — the receiver's own createHmac('sha256', SECRET) over the raw body still matches X-Objectstack-Signature, and [security] Webhook HMAC signing secrets are persisted in cleartext on every sys_http_delivery row #7722's no-secret-on-the-delivery-row invariant is re-asserted in the same test.
3. Migration/compat ✅ — stated as a table in the PR body. Summary: package rows heal via re-seed, admin + customized rows via the sweep, and rows on a deployment with no CryptoProvider stay cleartext — reported per row with code/status, never silently. Un-swept rows keep signing from the legacy blob (with a warning each refresh); a row whose encrypted key cannot be decrypted is dropped rather than delivered unsigned.
4. ADR-0112 ✅ but partly vacuous, and I want to be explicit: this change surfaces no new wire refusal — the fail-closed path is a boot-time log. Rather than grow the extension ledger (which lives in packages/spec) for something that never reaches an HTTP response, the refusal carries the standard-catalog INTERNAL_ERROR/500 pair, and two tests assert both code and status, not the message.
5. check:engine-double-contract ✅ — ran it, green. The doubles I added are drivers (update(object, id, data), primary key second), which the gate scopes out; no hand-rolled engine double.

One thing worth your eye: both stub drivers (mine and objectql's existing one) now return copies of stored rows. Handing out the live object made them lie in the one direction that matters here — maskSecretFields mutates the rows it is given, so a single find stamped the mask over the stored ref and the next resolve read it back as "no secret". That artefact reads exactly like an engine bug, and it cost me one debugging round.

CI + not done

CI running on #7901 (13 checks). Locally green: plugin-webhooks 45/45, objectql 3315/3315, tsc --noEmit on both, eslint on every changed file, check:engine-double-contract, check:error-code-casing, check:empty-changeset, check:platform-checklist, check:i18n (bundles regenerated; the three non-English signing_secret strings translated rather than left as English source).

Deliberately not done:

• check:i18n-coverage not measured locally — it refuses to judge a partial round, and it cannot lint examples/app-showcase until the whole workspace is built (@objectstack/connector-mcp has no dist in this worktree). The new keys are translated in all four locales, so the ratchet should not move; CI will confirm.
• No audit of other config objects storing credentials in JSON blobs. The issue's "worth checking in the same pass" line is a real second surface, but it is a survey, not this defect — and now that resolveSecretField exists the plugin-local fix is available to each of them. Happy to file it if you want it tracked.

---

Generated by Claude Code