@objectstack/plugin-webhooks 17.0.0-rc.5 → 17.0.0

package/dist/index.js

@@ -1,8 +1,178 @@
 import {
   SysWebhook
-} from "./chunk-3QGZLM3T.js";
+} from "./chunk-GDCWDVDT.js";
+
+// src/webhook-secret.ts
+var WEBHOOK_SECRET_FIELD = "signing_secret";
+var WEBHOOK_OBJECT = "sys_webhook";
+var WEBHOOK_SECRET_REFUSAL_CODE = "INTERNAL_ERROR";
+var WEBHOOK_SECRET_REFUSAL_STATUS = 500;
+function isSecretProtectionFailure(err) {
+  const msg = String(err?.message ?? err ?? "");
+  return /Cannot persist secret field/i.test(msg);
+}
+var WebhookSecretUnresolvableError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.code = WEBHOOK_SECRET_REFUSAL_CODE;
+    this.status = WEBHOOK_SECRET_REFUSAL_STATUS;
+    this.name = "WebhookSecretUnresolvableError";
+  }
+};
+function isWebhookSecretUnresolvable(err) {
+  return err instanceof WebhookSecretUnresolvableError;
+}
+function splitWebhookSecret(wh) {
+  const { secret, ...envelope } = wh;
+  const value = typeof secret === "string" && secret.length > 0 ? secret : void 0;
+  return { envelope, secret: value };
+}
+function readLegacySecret(definitionJson) {
+  if (typeof definitionJson !== "string" || definitionJson.length === 0) return void 0;
+  try {
+    const parsed = JSON.parse(definitionJson);
+    const secret = parsed?.secret;
+    return typeof secret === "string" && secret.length > 0 ? secret : void 0;
+  } catch {
+    return void 0;
+  }
+}
+var OBJECTQL_SECRET_MASK = "\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022";
+var OBJECTQL_SECRET_REF_PREFIX = "secret:";
+function isOpaqueSecretForm(value) {
+  return typeof value === "string" && (value === OBJECTQL_SECRET_MASK || value.startsWith(OBJECTQL_SECRET_REF_PREFIX));
+}
+function canResolveSecrets(engine) {
+  return typeof engine?.resolveSecretField === "function";
+}
+function onCryptoProviderChange(engine, listener) {
+  const observable = engine;
+  if (typeof observable?.onCryptoProviderChange !== "function") return void 0;
+  return observable.onCryptoProviderChange(listener);
+}
+async function resolveWebhookSecret(engine, row, object = WEBHOOK_OBJECT) {
+  const stored = row[WEBHOOK_SECRET_FIELD];
+  if (stored == null || stored === "") return void 0;
+  const resolver = engine;
+  if (typeof resolver.resolveSecretField !== "function") {
+    if (!isOpaqueSecretForm(stored)) return String(stored);
+    throw new WebhookSecretUnresolvableError(
+      `Webhook "${String(row.name ?? row.id)}" stores an encrypted signing secret, but this data engine does not implement resolveSecretField() \u2014 the key cannot be recovered, so the subscription is dropped rather than delivered unsigned (#7799).`
+    );
+  }
+  const plain = await resolver.resolveSecretField(object, String(row.id), WEBHOOK_SECRET_FIELD);
+  if (typeof plain === "string" && plain.length > 0) return plain;
+  throw new WebhookSecretUnresolvableError(
+    `Webhook "${String(row.name ?? row.id)}" stores a signing secret in ${object}.${WEBHOOK_SECRET_FIELD} that resolved to nothing. A value IS stored \u2014 the read path returns the engine mask for it \u2014 so this is NOT an unsigned webhook, and delivering it unsigned would strip the receiver of its only proof of origin (#7799, #8542). Causes, in the order worth checking: the row was deleted while this refresh was reading it; the column holds something that is not a secret: ref (a hand-edited column, or a dump restored without its sys_secret rows); or the stored value decrypts to an empty string. Fix: re-save the webhook secret so the column holds a fresh ref, or CLEAR the field to null if this webhook is meant to be unsigned \u2014 an empty secret is not the same thing as no secret.`
+  );
+}
+
+// src/webhook-headers.ts
+var WEBHOOK_HEADERS_FIELD = "headers_secret";
+function isHeaderMap(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const entries = Object.entries(value);
+  if (entries.length === 0) return false;
+  return entries.every(([, v]) => typeof v === "string");
+}
+function splitWebhookHeaders(wh) {
+  const { headers, ...envelope } = wh;
+  return {
+    envelope,
+    headers: isHeaderMap(headers) ? headers : void 0
+  };
+}
+function serializeHeaders(headers) {
+  return JSON.stringify(headers);
+}
+function parseStoredHeaders(stored) {
+  if (typeof stored !== "string" || stored.length === 0) return void 0;
+  try {
+    const parsed = JSON.parse(stored);
+    return isHeaderMap(parsed) ? parsed : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function readLegacyHeaders(definitionJson) {
+  if (typeof definitionJson !== "string" || definitionJson.length === 0) return void 0;
+  try {
+    const parsed = JSON.parse(definitionJson);
+    return isHeaderMap(parsed?.headers) ? parsed.headers : void 0;
+  } catch {
+    return void 0;
+  }
+}
+var WebhookHeadersUnresolvableError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.code = WEBHOOK_SECRET_REFUSAL_CODE;
+    this.status = WEBHOOK_SECRET_REFUSAL_STATUS;
+    this.name = "WebhookHeadersUnresolvableError";
+  }
+};
+var HEADERS_REMEDY = 'Fix: re-save the webhook headers as a flat JSON object of string values so the column holds a fresh ref, or CLEAR the field to null if this webhook is meant to send no custom headers \u2014 an empty or unparseable header map is not the same thing as no header map, and only the second one means "send nothing extra".';
+function requireHeaderMap(recovered, row, where) {
+  const parsed = parseStoredHeaders(recovered);
+  if (parsed) return parsed;
+  throw new WebhookHeadersUnresolvableError(
+    `Webhook "${String(row.name ?? row.id)}" stores custom headers in ${where} that came back but are not a flat JSON object of string values, so there is no header map to send. A value IS stored \u2014 the read path returns the engine mask for it \u2014 so this is NOT a webhook authored without headers, and delivering it without them would silently drop whatever the author put in that map, including an Authorization credential, on a delivery that is otherwise correctly signed and therefore looks genuine to the receiver (#7986, #8558). Causes, in the order worth checking: the value was typed into the Custom Headers field and is not valid JSON; it parses but is an array, an empty object, or has a non-string value ({"X-Count": 5}); or it is a nested object where the wire format allows only strings. ${HEADERS_REMEDY}`
+  );
+}
+async function resolveWebhookHeaders(engine, row, object) {
+  const stored = row[WEBHOOK_HEADERS_FIELD];
+  if (stored == null || stored === "") return void 0;
+  const resolver = engine;
+  if (typeof resolver.resolveSecretField !== "function") {
+    if (!isOpaqueSecretForm(stored)) {
+      return requireHeaderMap(stored, row, `${object}.${WEBHOOK_HEADERS_FIELD}`);
+    }
+    throw new WebhookHeadersUnresolvableError(
+      `Webhook "${String(row.name ?? row.id)}" stores encrypted custom headers, but this data engine does not implement resolveSecretField() \u2014 they cannot be recovered, so the subscription is dropped rather than delivered without the headers it was authored with (#7986).`
+    );
+  }
+  const plain = await resolver.resolveSecretField(object, String(row.id), WEBHOOK_HEADERS_FIELD);
+  if (plain == null || plain === "") {
+    throw new WebhookHeadersUnresolvableError(
+      `Webhook "${String(row.name ?? row.id)}" stores custom headers in ${object}.${WEBHOOK_HEADERS_FIELD} that resolved to nothing. A value IS stored \u2014 the read path returns the engine mask for it \u2014 so this is NOT a webhook authored without headers, and delivering it without them would silently drop whatever the author put in that map, including an Authorization credential, on a delivery that is otherwise correctly signed and therefore looks genuine to the receiver (#7986, #8558). Causes, in the order worth checking: the row was deleted while this refresh was reading it; the column holds something that is not a secret: ref (a hand-edited column, or a dump restored without its sys_secret rows); or the stored value decrypts to an empty string. ${HEADERS_REMEDY}`
+    );
+  }
+  return requireHeaderMap(plain, row, `${object}.${WEBHOOK_HEADERS_FIELD}`);
+}
+async function headersPatch(engine, declared, row, object) {
+  const hasStored = row?.[WEBHOOK_HEADERS_FIELD] != null && row[WEBHOOK_HEADERS_FIELD] !== "";
+  if (!declared) return hasStored ? { [WEBHOOK_HEADERS_FIELD]: null } : {};
+  const serialized = serializeHeaders(declared);
+  const resolver = engine;
+  if (!hasStored || typeof resolver.resolveSecretField !== "function") {
+    return { [WEBHOOK_HEADERS_FIELD]: serialized };
+  }
+  try {
+    const current = await resolver.resolveSecretField(object, String(row.id), WEBHOOK_HEADERS_FIELD);
+    const stored = parseStoredHeaders(current);
+    return stored && serializeHeaders(stored) === serialized ? {} : { [WEBHOOK_HEADERS_FIELD]: serialized };
+  } catch {
+    return { [WEBHOOK_HEADERS_FIELD]: serialized };
+  }
+}
 
 // src/auto-enqueuer.ts
+var SIGNING_SECRET_CREDENTIAL = {
+  field: WEBHOOK_SECRET_FIELD,
+  noun: "signing secret",
+  article: "an encrypted signing secret",
+  ratherThan: "delivered unsigned",
+  issue: "#7799",
+  issues: "#7799/#8022"
+};
+var CUSTOM_HEADERS_CREDENTIAL = {
+  field: WEBHOOK_HEADERS_FIELD,
+  noun: "custom header map",
+  article: "encrypted custom headers",
+  ratherThan: "delivered without the headers it was authored with",
+  issue: "#7986",
+  issues: "#7986/#8022"
+};
 var AutoEnqueuer = class {
   constructor(engine, realtime, enqueue, opts = {}) {
     this.engine = engine;
@@ -10,6 +180,18 @@ var AutoEnqueuer = class {
     this.enqueue = enqueue;
     this.subscriptions = /* @__PURE__ */ new Map();
     this.running = false;
+    /**
+     * [#8022] Webhook ids currently dropped for an unresolvable credential —
+     * the signing key (#7799) or, since #7986, the custom header map. ONE set
+     * for both on purpose: a subscription is either armed or dropped, so a
+     * per-credential ledger would let a row already silenced for its key report
+     * loudly again for its headers on the very next refresh.
+     * Held so the loud first report is said ONCE per outage (AGENTS.md
+     * "Degradation log levels": *say it once, at the first degradation*) and
+     * again if the same webhook breaks after recovering — not once per row per
+     * refresh, forever.
+     */
+    this.droppedForSecret = /* @__PURE__ */ new Set();
     this.subscriptionsObject = opts.subscriptionsObject ?? "sys_webhook";
     this.refreshIntervalMs = opts.refreshIntervalMs ?? 6e4;
     this.logger = opts.logger ?? {};
@@ -20,6 +202,10 @@ var AutoEnqueuer = class {
   async start() {
     if (this.running) return;
     this.running = true;
+    this.unbindCryptoListener = onCryptoProviderChange(
+      this.engine,
+      () => this.rearmAfterCryptoRegistered()
+    );
     await this.refresh();
     this.subId = await this.realtime.subscribe(
       "webhook-auto-enqueuer",
@@ -45,9 +231,32 @@ var AutoEnqueuer = class {
     if (this.subId) await this.realtime.unsubscribe(this.subId);
     if (this.subIdSelfHeal) await this.realtime.unsubscribe(this.subIdSelfHeal);
     if (this.refreshTimer) clearInterval(this.refreshTimer);
+    this.unbindCryptoListener?.();
     this.subId = void 0;
     this.subIdSelfHeal = void 0;
     this.refreshTimer = void 0;
+    this.unbindCryptoListener = void 0;
+  }
+  /**
+   * [#8022] The engine just gained a CryptoProvider — rebuild the cache so
+   * subscriptions dropped for an unresolvable signing key re-arm now, instead
+   * of at the next periodic refresh up to {@link refreshIntervalMs} away.
+   *
+   * It deliberately does NOT call {@link refresh} directly. `refresh()`
+   * coalesces onto an in-flight build, and the build most likely to be in
+   * flight right now is the one from `start()` — the very build whose rows
+   * were read while there was no provider. Joining it would return "refreshed"
+   * having re-armed nothing, which is this issue with an extra step. So: let
+   * whatever is running finish, then read again.
+   */
+  rearmAfterCryptoRegistered() {
+    const inFlight = this.refreshing ?? Promise.resolve();
+    void inFlight.catch(() => void 0).then(() => this.running ? this.refresh() : void 0).catch(
+      (err) => this.logger.warn?.(
+        "[webhook-auto-enqueuer] re-arm after CryptoProvider registration failed",
+        err
+      )
+    );
   }
   /**
    * Force-refresh the subscription cache from storage. Concurrent
@@ -77,6 +286,7 @@ var AutoEnqueuer = class {
     for (const row of rows) {
       const sub = this.parseRow(row);
       if (!sub) continue;
+      await this.attachCredentials(sub, row);
       const key = sub.objectName ?? "*";
       const arr = next.get(key) ?? [];
       arr.push(sub);
@@ -84,11 +294,249 @@ var AutoEnqueuer = class {
     }
     this.subscriptions.clear();
     for (const [k, v] of next) this.subscriptions.set(k, v);
+    if (this.droppedForSecret.size > 0) {
+      const live = new Set(rows.map((r) => String(r?.id)));
+      for (const id of this.droppedForSecret) {
+        if (!live.has(id)) this.droppedForSecret.delete(id);
+      }
+    }
     this.logger.debug?.("[webhook-auto-enqueuer] cache refreshed", {
       objects: this.subscriptions.size,
       rows: rows.length
     });
   }
+  /**
+   * [#7799, #7986] Resolve BOTH encrypted credentials for one cached
+   * subscription. Returns `false` when the subscription must be dropped from
+   * the cache.
+   *
+   * The two halves are deliberately resolved on the SAME build rather than on
+   * separate schedules. #8022's re-arm rebuilds the whole cache when a
+   * CryptoProvider registers; a header map recovered on any other cadence
+   * would let the enqueuer re-arm into a delivery that is correctly signed and
+   * silently missing its `Authorization`, which is the failure mode of both
+   * cards at once.
+   *
+   * The drop ledger is cleared only when BOTH succeed — otherwise a row whose
+   * secret resolves and whose headers do not would clear its own "already
+   * reported" mark on every refresh and shout the same `error` every 60s,
+   * which is precisely the unreadable-error-channel failure #8022's say-once
+   * rule exists to prevent.
+   *
+   * Cost: up to two point reads + two decrypts per credential-bearing row per
+   * refresh (default 60s), off the write path entirely. Deliberately NOT
+   * memoised across refreshes — the only cheap cache key would be
+   * `updated_at`, which nothing guarantees is stamped when a credential is
+   * rotated, and a stale key signs every delivery with a signature the
+   * receiver rejects.
+   */
+  async attachCredentials(sub, row) {
+    if (!await this.attachSecret(sub, row)) return false;
+    if (!await this.attachHeaders(sub, row)) return false;
+    this.droppedForSecret.delete(sub.id);
+    return true;
+  }
+  /**
+   * [#8069] Mark a subscription parked and strip anything sendable off it.
+   *
+   * Called from the two `attachX` failure paths, which each already reported
+   * the drop at `error` (say-once, #8022). The credentials are cleared rather
+   * than merely "not set": `attachSecret` can succeed and `attachHeaders`
+   * fail, and a parked row must not carry the header map — that map is the
+   * ordinary place an `Authorization: Bearer …` goes (#7986), and copying it
+   * onto a row that will sit in `sys_http_delivery` for the full 30d
+   * retention window without ever being sent is a credential copy bought for
+   * nothing.
+   */
+  /**
+   * [#8069] Report a failed outbox write off the hot path, at the level the
+   * loss actually deserves.
+   *
+   * AGENTS.md decides that with one question — *does the system still look
+   * normal from the outside while something it claims is persisted has not
+   * landed?* For a PARKED subscription the answer is unambiguously yes, and
+   * worse than for an ordinary enqueue failure: the durable record is the
+   * only trace this event ever existed, so losing the write puts us back
+   * exactly where this issue started, silently. So `error` there, and the
+   * pre-existing `warn` for an ordinary enqueue, where the delivery itself is
+   * the thing that did not happen and the subscription is otherwise healthy.
+   *
+   * The realistic cause of the parked branch is a host that wired
+   * {@link HttpEnqueueFn} straight to `IHttpOutbox.enqueue` instead of
+   * `MessagingService.enqueueHttp`: only the messaging seam routes a parked
+   * input to `recordUndeliverable()`, and the raw delivery door refuses the
+   * discriminator rather than minting a `pending` unsigned row from it. The
+   * message names that, because it is not guessable from "enqueue failed".
+   */
+  reportWriteFailure(sub, eventId, err, verb) {
+    const meta = { webhook: sub.name, eventId, err: err?.message ?? err };
+    if (!sub.parkedReason) {
+      this.logger.warn?.(`[webhook-auto-enqueuer] ${verb} failed`, meta);
+      return;
+    }
+    const message = `[webhook-auto-enqueuer] could not record the undeliverable event for webhook '${sub.name}' \u2014 the subscription is parked for an unresolvable credential, and this event is now DISCARDED WITH NO TRACE in sys_http_delivery, which is the durability gap #8069 closes. Most likely cause: the enqueue callback was wired directly to IHttpOutbox.enqueue instead of MessagingService.enqueueHttp \u2014 only the messaging seam routes a parked event to recordUndeliverable(), and the delivery door refuses it rather than minting a pending row that would be sent UNSIGNED.`;
+    if (typeof this.logger.error === "function") {
+      this.logger.error(message, err, meta);
+    } else {
+      this.logger.warn?.(message, meta);
+    }
+  }
+  park(sub, err, credential) {
+    sub.secret = void 0;
+    sub.headers = void 0;
+    sub.parkedReason = `[${WEBHOOK_SECRET_REFUSAL_CODE}/${WEBHOOK_SECRET_REFUSAL_STATUS}] webhook '${sub.name}' holds ${credential.article} that could not be decrypted, so this event was NOT delivered \u2014 recording it here rather than ${credential.ratherThan} (${credential.issue}, #8069). This row was never sent and cannot be redelivered: it carries no HMAC signature, because the ${credential.noun} that would have produced one is exactly what is missing. Fix: register a CryptoProvider (engine.setCryptoProvider \u2014 LocalCryptoProvider in dev, KMS/Vault in production) with the same key the ${credential.noun} was written under, and make sure the sys_secret row is reachable; the subscription re-arms on registration (#8022) and at the next periodic refresh, and later events are delivered normally. Cause: ${err?.message ?? String(err)}`;
+  }
+  /**
+   * [#7799] Resolve `sub.secret`. Returns `false` when the subscription must
+   * be dropped.
+   *
+   * Three sources, in order:
+   *  1. `sys_webhook.signing_secret` — the encrypted column. The read path
+   *     returns a mask, so presence is decidable here but the value is not;
+   *     `resolveWebhookSecret` dereferences it server-side.
+   *  2. `definition_json.secret` — a row not yet swept by
+   *     `migrateLegacyWebhookSecrets` (or hand-edited back in). Still honoured
+   *     so an un-migrated deployment keeps signing, and warned about once per
+   *     refresh so the exposure is visible rather than silently permanent.
+   *  3. Neither — an unsigned webhook, which is a legitimate authored choice
+   *     (`secret` is optional on the envelope).
+   *
+   * A stored-but-unresolvable key DROPS the subscription instead of
+   * delivering unsigned. The signature is the receiver's only proof of
+   * origin (#7722, #7799): a webhook that stops arriving is visible and gets
+   * investigated, while one that keeps arriving unsigned is invisible and
+   * teaches the receiver to accept unauthenticated traffic.
+   *
+   * [#8542] Case 3 means what it says only because the seam was fixed to say
+   * it. `resolveWebhookSecret` used to answer `undefined` for BOTH "no key is
+   * stored" and "a key is stored and did not come back", so this method read
+   * the second as the third and armed the subscription — the invariant above
+   * failing OPEN, silently, on the producer path. Nothing here changed: the
+   * seam now raises for that case, so it lands in the `catch` below exactly
+   * the way a throwing resolver already did, and the drop, the say-once
+   * `error` and the #8069 park all apply to it unchanged.
+   */
+  async attachSecret(sub, row) {
+    try {
+      const stored = await resolveWebhookSecret(this.engine, row, this.subscriptionsObject);
+      if (stored) {
+        sub.secret = stored;
+        return true;
+      }
+    } catch (err) {
+      this.reportDrop(sub, err, SIGNING_SECRET_CREDENTIAL);
+      this.park(sub, err, SIGNING_SECRET_CREDENTIAL);
+      return false;
+    }
+    const legacy = readLegacySecret(row?.definition_json);
+    if (legacy) {
+      this.logger.warn?.(
+        `[webhook-auto-enqueuer] webhook '${sub.name}' still carries its signing secret as CLEARTEXT in definition_json, readable over the data API (#7799). Signing continues from it; run the boot sweep (migrateLegacyWebhookSecrets) with a CryptoProvider wired to move it into sys_secret.`,
+        { id: sub.id }
+      );
+      sub.secret = legacy;
+    }
+    return true;
+  }
+  /**
+   * [#7986] Resolve `sub.headers` from the encrypted column, with the same
+   * three-source shape as {@link attachSecret} and for the same reasons.
+   *
+   * A stored-but-unresolvable header map DROPS the subscription rather than
+   * delivering without it. That is the identical trade #7799 made for the
+   * signature, and it needs restating because the intuition runs the other
+   * way: a missing `Authorization` looks self-announcing, since the receiver
+   * answers 401 and the attempt lands in `sys_http_delivery` for anyone to
+   * find. 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. A subscription that stops is visible; a
+   * delivery that arrives subtly wrong is not.
+   *
+   * [#8558] And that is what this method used to do, for the same reason its
+   * signing sibling did (#8542): `resolveWebhookHeaders` answered `undefined`
+   * for BOTH "no headers are stored" and "a map is stored and did not come
+   * back as one", so this method read the second as the first and armed the
+   * subscription — the paragraph above failing OPEN. Measured, the delivery
+   * then went out SUCCESSFULLY and correctly SIGNED with the whole authored
+   * map missing, which is the worst available combination: the signature
+   * tells the receiver the request is genuinely ours. Nothing here changed:
+   * the seam now raises, so it lands in the `catch` below exactly the way a
+   * throwing resolver already did, and the drop, the say-once `error` and the
+   * #8069 park all apply to it unchanged.
+   */
+  async attachHeaders(sub, row) {
+    try {
+      const stored = await resolveWebhookHeaders(this.engine, row, this.subscriptionsObject);
+      if (stored) {
+        sub.headers = stored;
+        return true;
+      }
+    } catch (err) {
+      this.reportDrop(sub, err, CUSTOM_HEADERS_CREDENTIAL);
+      this.park(sub, err, CUSTOM_HEADERS_CREDENTIAL);
+      return false;
+    }
+    const legacy = readLegacyHeaders(row?.definition_json);
+    if (legacy) {
+      this.logger.warn?.(
+        `[webhook-auto-enqueuer] webhook '${sub.name}' still carries its custom headers as CLEARTEXT in definition_json, readable over the data API (#7986) \u2014 that map is the ordinary place an Authorization header goes. Delivery continues from it; run the boot sweep (migrateLegacyWebhookSecrets) with a CryptoProvider wired to move them into sys_secret.`,
+        { id: sub.id }
+      );
+      sub.headers = legacy;
+    }
+    return true;
+  }
+  /**
+   * [#8022] Report a subscription dropped for an unresolvable signing key.
+   *
+   * ## Why `error`, and why only the first time
+   * AGENTS.md decides the level with one question: *after the degradation,
+   * does the system still look normal from the outside while something the
+   * system claims is happening is not?* Here the answer is yes, and it is the
+   * whole defect — `GET /api/v1/data/sys_webhook` keeps reading
+   * `active: true`, Setup keeps showing the webhook armed, and every matching
+   * record change is discarded with no delivery and no `sys_http_delivery`
+   * row to find afterwards. That is a durability degradation wearing a
+   * functional degradation's clothes, so it owes the two things an `error`
+   * owes: the consequence, concretely, and the fix.
+   *
+   * Said ONCE per outage per webhook, per the same section. The cache is
+   * rebuilt every {@link refreshIntervalMs}; an unfixed misconfiguration would
+   * otherwise print this line every 60s forever, which is how an `error`
+   * channel becomes unreadable — the failure mode that made the founding
+   * incident's `warn` invisible. Repeats drop to `debug`; a recovery clears
+   * the id, so a re-break is loud again.
+   *
+   * ADR-0112: `code` + `status` travel in the meta so a consumer branches on
+   * the pair, not on message text. Same pair the seeder's refusal carries for
+   * the same underlying cause.
+   */
+  reportDrop(sub, err, credential = SIGNING_SECRET_CREDENTIAL) {
+    const meta = {
+      id: sub.id,
+      webhook: sub.name,
+      field: credential.field,
+      code: WEBHOOK_SECRET_REFUSAL_CODE,
+      status: WEBHOOK_SECRET_REFUSAL_STATUS,
+      err: err?.message ?? err
+    };
+    if (this.droppedForSecret.has(sub.id)) {
+      this.logger.debug?.(
+        `[webhook-auto-enqueuer] webhook '${sub.name}' is still dropped for an unresolvable ${credential.noun} (${credential.issues})`,
+        meta
+      );
+      return;
+    }
+    this.droppedForSecret.add(sub.id);
+    const message = `[webhook-auto-enqueuer] webhook '${sub.name}' holds ${credential.article} that could not be decrypted \u2014 the subscription is PARKED rather than ${credential.ratherThan} (${credential.issue}), so every matching record change is discarded with NO delivery, while the row keeps reading active:true in Setup. Each discarded event IS recorded in sys_http_delivery as a dead row with 0 attempts carrying this cause (#8069) \u2014 look there for the backlog; those rows can never be sent or redelivered, because a parked row has no HMAC signature. Fix: register a CryptoProvider (engine.setCryptoProvider \u2014 LocalCryptoProvider in dev, KMS/Vault in production) with the same key the ${credential.noun} was written under, and make sure the sys_secret row is reachable; the subscription re-arms on registration (#8022) and at the next periodic refresh.`;
+    if (typeof this.logger.error === "function") {
+      this.logger.error(message, err, meta);
+    } else {
+      this.logger.warn?.(message, meta);
+    }
+  }
   parseRow(row) {
     if (!row?.id || !row?.url) return null;
     const rawTriggers = row.triggers;
@@ -145,8 +593,9 @@ var AutoEnqueuer = class {
       // method regardless of whether the row was authored before or after
       // the select change (legacy rows stored 'POST').
       method: String(row.method ?? defn.method ?? "POST").toUpperCase(),
-      headers: defn.headers,
-      secret: defn.secret,
+      // `headers` and `secret` are both filled by attachCredentials()
+      // from their encrypted columns, NOT read off the row — see #7799
+      // (secret) and #7986 (headers).
       timeoutMs: defn.timeoutMs
     };
   }
@@ -194,6 +643,12 @@ var AutoEnqueuer = class {
         method: sub.method,
         headers: sub.headers,
         signingSecret: sub.secret,
+        // [#8069] Set only for a PARKED subscription, and then this is
+        // not an enqueue at all: the messaging seam routes it to
+        // `recordUndeliverable()`, which writes a terminal `dead` row
+        // with this reason and no signature. Undefined for every healthy
+        // subscription, so the delivery path is byte-identical to before.
+        undeliverableReason: sub.parkedReason,
         timeoutMs: sub.timeoutMs,
         // [#3946] Envelope keys are written LAST so the event payload
         // cannot rewrite them. Behaviour-neutral for the engine's own
@@ -212,13 +667,7 @@ var AutoEnqueuer = class {
           action,
           timestamp: event.timestamp
         }
-      }).catch(
-        (err) => this.logger.warn?.("[webhook-auto-enqueuer] enqueue failed", {
-          webhook: sub.name,
-          eventId,
-          err: err?.message ?? err
-        })
-      );
+      }).catch((err) => this.reportWriteFailure(sub, eventId, err, "enqueue"));
     }
   }
   /**
@@ -271,6 +720,9 @@ var AutoEnqueuer = class {
         method: sub.method,
         headers: sub.headers,
         signingSecret: sub.secret,
+        // [#8069] See the per-record path — parked subscriptions record
+        // an undeliverable row instead of enqueuing a delivery.
+        undeliverableReason: sub.parkedReason,
         timeoutMs: sub.timeoutMs,
         // [#3946] Envelope keys last so the payload cannot rewrite them.
         payload: {
@@ -280,13 +732,7 @@ var AutoEnqueuer = class {
           action,
           timestamp: event.timestamp
         }
-      }).catch(
-        (err) => this.logger.warn?.("[webhook-auto-enqueuer] bulk enqueue failed", {
-          webhook: sub.name,
-          eventId,
-          err: err?.message ?? err
-        })
-      );
+      }).catch((err) => this.reportWriteFailure(sub, eventId, err, "bulk enqueue"));
     }
   }
   handleSelfHealEvent(event) {
@@ -343,7 +789,7 @@ function readDeclared(engine, metadataService, type) {
   try {
     const reg = engine?._registry;
     if (reg?.listItems) {
-      const items = (reg.listItems(type) ?? []).map((i) => i?.content ?? i).filter(Boolean);
+      const items = (reg.listItems(type) ?? []).filter(Boolean);
       if (items.length > 0) return items;
     }
   } catch {
@@ -351,7 +797,7 @@ function readDeclared(engine, metadataService, type) {
   try {
     const listed = metadataService?.list?.(type);
     const arr = typeof listed?.then === "function" ? [] : listed ?? [];
-    return Array.isArray(arr) ? arr.map((i) => i?.content ?? i).filter(Boolean) : [];
+    return Array.isArray(arr) ? arr.filter(Boolean) : [];
   } catch {
     return [];
   }
@@ -396,6 +842,13 @@ async function bootstrapDeclaredWebhooks(engine, metadataService, logger, subscr
         const patch = {
           id: row.id,
           ...mapWebhookToRow(wh),
+          ...await secretPatch(engine, wh, row, subscriptionsObject),
+          ...await headersPatch(
+            engine,
+            splitWebhookHeaders(wh).headers,
+            row,
+            subscriptionsObject
+          ),
           // Adopt pristine/legacy (pre-provenance) rows so future boots
           // recognize them as package-managed.
           managed_by: "package",
@@ -405,9 +858,20 @@ async function bootstrapDeclaredWebhooks(engine, metadataService, logger, subscr
         seeded += 1;
         continue;
       }
+      const { secret } = splitWebhookSecret(wh);
+      const { headers } = splitWebhookHeaders(wh);
       const newRow = {
         id: uid("whk"),
         ...mapWebhookToRow(wh),
+        // Cleartext goes in exactly once, into the `secret`-typed column; the
+        // engine's write path wraps it into `sys_secret` and leaves an opaque
+        // ref behind. Omitted entirely when unauthored, so a webhook with no
+        // secret costs no crypto and needs no CryptoProvider.
+        ...secret ? { [WEBHOOK_SECRET_FIELD]: secret } : {},
+        // [#7986] Same channel, same rule, for the header map — omitted when
+        // unauthored so a header-less webhook still seeds on a host with no
+        // CryptoProvider wired.
+        ...headers ? { [WEBHOOK_HEADERS_FIELD]: serializeHeaders(headers) } : {},
         managed_by: "package",
         customized: false,
         created_at: now,
@@ -416,10 +880,15 @@ async function bootstrapDeclaredWebhooks(engine, metadataService, logger, subscr
       await engine.insert(subscriptionsObject, newRow, { context: SYSTEM_CTX });
       seeded += 1;
     } catch (err) {
-      logger?.warn?.("[webhook] declared webhook seed failed", {
-        name: wh.name,
-        error: err?.message ?? String(err)
-      });
+      const protection = isSecretProtectionFailure(err);
+      logger?.warn?.(
+        protection ? "[webhook] declared webhook NOT seeded \u2014 its signing secret cannot be stored encrypted (#7799)" : "[webhook] declared webhook seed failed",
+        {
+          name: wh.name,
+          ...protection ? { code: WEBHOOK_SECRET_REFUSAL_CODE, status: WEBHOOK_SECRET_REFUSAL_STATUS } : {},
+          error: err?.message ?? String(err)
+        }
+      );
       skipped += 1;
     }
   }
@@ -430,7 +899,25 @@ async function bootstrapDeclaredWebhooks(engine, metadataService, logger, subscr
   });
   return { seeded, skipped };
 }
+async function secretPatch(engine, wh, row, subscriptionsObject) {
+  const { secret } = splitWebhookSecret(wh);
+  const hasStored = row?.[WEBHOOK_SECRET_FIELD] != null && row[WEBHOOK_SECRET_FIELD] !== "";
+  if (!secret) return hasStored ? { [WEBHOOK_SECRET_FIELD]: null } : {};
+  if (!hasStored || !canResolveSecrets(engine)) return { [WEBHOOK_SECRET_FIELD]: secret };
+  try {
+    const current = await engine.resolveSecretField(
+      subscriptionsObject,
+      String(row.id),
+      WEBHOOK_SECRET_FIELD
+    );
+    return current === secret ? {} : { [WEBHOOK_SECRET_FIELD]: secret };
+  } catch {
+    return { [WEBHOOK_SECRET_FIELD]: secret };
+  }
+}
 function mapWebhookToRow(wh) {
+  const { envelope: withoutSecret } = splitWebhookSecret(wh);
+  const { envelope } = splitWebhookHeaders(withoutSecret);
   return {
     name: wh.name,
     label: wh.label ?? wh.name,
@@ -442,13 +929,100 @@ function mapWebhookToRow(wh) {
     method: String(wh.method ?? "POST").toLowerCase(),
     description: wh.description ?? null,
     active: wh.isActive !== false,
-    definition_json: JSON.stringify(wh)
+    definition_json: JSON.stringify(envelope)
+  };
+}
+
+// src/migrate-webhook-secrets.ts
+var SYSTEM_CTX2 = { isSystem: true, positions: [], permissions: [] };
+var SYSTEM_QUERY = {
+  context: { isSystem: true, positions: [], permissions: [] }
+};
+async function migrateLegacyWebhookSecrets(engine, logger, subscriptionsObject = WEBHOOK_OBJECT) {
+  const out = { found: 0, migrated: 0, failed: 0 };
+  let rows;
+  try {
+    const found = await engine.find(subscriptionsObject, SYSTEM_QUERY);
+    rows = Array.isArray(found) ? found : found?.data ?? [];
+  } catch (err) {
+    logger?.warn?.("[webhook] legacy secret sweep skipped \u2014 could not read subscriptions", {
+      object: subscriptionsObject,
+      error: err?.message ?? String(err)
+    });
+    return out;
+  }
+  for (const row of rows) {
+    if (!row?.id) continue;
+    const legacySecret = readLegacySecret(row.definition_json);
+    const legacyHeaders = readLegacyHeaders(row.definition_json);
+    if (!legacySecret && !legacyHeaders) continue;
+    out.found += 1;
+    try {
+      await engine.update(
+        subscriptionsObject,
+        {
+          id: row.id,
+          ...legacySecret ? { [WEBHOOK_SECRET_FIELD]: legacySecret } : {},
+          ...legacyHeaders ? { [WEBHOOK_HEADERS_FIELD]: serializeHeaders(legacyHeaders) } : {},
+          definition_json: stripCredentialsFromDefinition(row.definition_json)
+        },
+        { context: SYSTEM_CTX2 }
+      );
+      out.migrated += 1;
+    } catch (err) {
+      out.failed += 1;
+      const protection = isSecretProtectionFailure(err);
+      const what = legacySecret && legacyHeaders ? "signing secret and custom headers" : legacySecret ? "signing secret" : "custom headers";
+      logger?.warn?.(
+        protection ? `[webhook] ${what} STILL CLEARTEXT in definition_json \u2014 no CryptoProvider to encrypt them (#7799/#7986)` : `[webhook] ${what} migration failed \u2014 row left unchanged (#7799/#7986)`,
+        {
+          name: row.name ?? row.id,
+          id: row.id,
+          code: WEBHOOK_SECRET_REFUSAL_CODE,
+          status: WEBHOOK_SECRET_REFUSAL_STATUS,
+          error: err?.message ?? String(err)
+        }
+      );
+    }
+  }
+  if (out.found > 0) {
+    logger?.info?.("[webhook] legacy cleartext credentials swept into sys_secret", { ...out });
+  }
+  return out;
+}
+function stripCredentialsFromDefinition(definitionJson) {
+  const parsed = JSON.parse(definitionJson);
+  const { envelope: withoutSecret } = splitWebhookSecret(parsed);
+  const { envelope } = splitWebhookHeaders(withoutSecret);
+  return JSON.stringify(envelope);
+}
+
+// src/redeliver-guard.ts
+function createWebhookRedeliverGuard(engine, subscriptionsObject = WEBHOOK_OBJECT) {
+  return async (row) => {
+    if (row.source !== "webhook") return void 0;
+    const subscription = await engine.findOne(subscriptionsObject, {
+      where: { id: row.refId }
+    });
+    if (!subscription) {
+      return `the ${subscriptionsObject} subscription '${row.refId}' this delivery belongs to no longer exists, so there is nothing left to say whether it may still be signed and sent (#8069). Recreate the webhook if the endpoint should keep receiving events; new events are then delivered signed.`;
+    }
+    const storesSecret = subscription[WEBHOOK_SECRET_FIELD] != null && subscription[WEBHOOK_SECRET_FIELD] !== "";
+    if (!storesSecret) return void 0;
+    let plaintext;
+    try {
+      plaintext = await resolveWebhookSecret(engine, subscription, subscriptionsObject);
+    } catch (err) {
+      if (!isWebhookSecretUnresolvable(err)) throw err;
+    }
+    if (plaintext) return void 0;
+    return `webhook '${String(subscription.name ?? row.refId)}' stores a signing secret that cannot be recovered, so this delivery cannot be authenticated as coming from us \u2014 refusing rather than sending (#7799, #8069). Fix: register a CryptoProvider with the same key the secret was written under and make sure the sys_secret row is reachable.`;
   };
 }
 
 // src/webhook-provenance.ts
 var WEBHOOK_PROVENANCE_PACKAGE = "plugin-webhooks:provenance";
-var SYSTEM_CTX2 = { isSystem: true, positions: [], permissions: [] };
+var SYSTEM_CTX3 = { isSystem: true, positions: [], permissions: [] };
 function bindWebhookProvenanceStamp(engine, logger) {
   if (typeof engine?.registerHook !== "function") return;
   engine.registerHook(
@@ -464,7 +1038,7 @@ function bindWebhookProvenanceStamp(engine, logger) {
           where: { id },
           fields: ["id", "managed_by", "customized"],
           limit: 1,
-          context: SYSTEM_CTX2
+          context: SYSTEM_CTX3
         });
         const row = Array.isArray(rows) ? rows[0] : void 0;
         if (!row) return;
@@ -541,7 +1115,7 @@ var WebhookOutboxPlugin = class {
         try {
           const i18n = ctx.getService("i18n");
           if (i18n && typeof i18n.loadTranslations === "function") {
-            const { WebhooksTranslations } = await import("./translations-2VGD4XRF.js");
+            const { WebhooksTranslations } = await import("./translations-U32QIEPB.js");
             for (const [locale, data] of Object.entries(WebhooksTranslations)) {
               i18n.loadTranslations(locale, data);
             }
@@ -608,6 +1182,13 @@ var WebhookOutboxPlugin = class {
         error: err?.message ?? String(err)
       });
     }
+    try {
+      await migrateLegacyWebhookSecrets(engine, ctx.logger);
+    } catch (err) {
+      ctx.logger.warn?.("[webhook] legacy signing-secret sweep failed (rows left unchanged)", {
+        error: err?.message ?? String(err)
+      });
+    }
   }
   async bootAutoEnqueue(ctx, opt) {
     if (opt === false) return;
@@ -627,6 +1208,7 @@ var WebhookOutboxPlugin = class {
       );
     }
     const enqOpts = typeof opt === "object" ? opt : {};
+    this.installRedeliverGuard(ctx, messaging, engine, enqOpts.subscriptionsObject);
     this.autoEnqueuer = new AutoEnqueuer(
       engine,
       realtime,
@@ -637,6 +1219,31 @@ var WebhookOutboxPlugin = class {
     ctx.registerService("webhook.autoEnqueuer", this.autoEnqueuer);
     ctx.logger.info?.("[webhook-auto-enqueuer] started (enqueues source=webhook onto sys_http_delivery)");
   }
+  /**
+   * [#8069] Register {@link createWebhookRedeliverGuard} with messaging, so
+   * `redeliver()` refuses a webhook row whose signing configuration is no
+   * longer available — for EVERY caller, not just the
+   * `POST /api/v1/webhooks/redeliver` route.
+   *
+   * Absence is loud, and `error` is the right level by AGENTS.md's one
+   * question: with no guard installed the endpoint still answers 200 and the
+   * dispatcher still reports a delivery, while the fail-closed signing
+   * guarantee the system claims (#7799) is not actually being kept. That is a
+   * durability/consistency degradation wearing a functional one's clothes.
+   */
+  installRedeliverGuard(ctx, messaging, engine, subscriptionsObject) {
+    if (typeof messaging.registerRedeliverGuard !== "function") {
+      ctx.logger.error?.(
+        "[webhook-outbox] messaging service exposes no registerRedeliverGuard() \u2014 redelivery of a webhook whose signing configuration is gone CANNOT be refused, so an operator pressing redeliver may send a delivery that can no longer be authenticated (#7799, #8069). The POST /api/v1/webhooks/redeliver endpoint is reachable by any authenticated user. Fix: upgrade @objectstack/service-messaging to a build that implements registerRedeliverGuard."
+      );
+      return;
+    }
+    messaging.registerRedeliverGuard(
+      "webhook",
+      createWebhookRedeliverGuard(engine, subscriptionsObject)
+    );
+    ctx.logger.debug?.("[webhook-outbox] redeliver guard installed for source=webhook");
+  }
   tryGetService(ctx, names) {
     for (const n of names) {
       try {
@@ -691,7 +1298,7 @@ var WebhookOutboxPlugin = class {
         if (code === "RESOURCE_NOT_FOUND") {
           return c.json({ success: false, error: { code, message: err.message } }, 404);
         }
-        if (code === "DELIVERY_NOT_ELIGIBLE") {
+        if (code === "DELIVERY_NOT_ELIGIBLE" || code === "DELIVERY_NEVER_SENT") {
           return c.json({ success: false, error: { code, message: err.message } }, 409);
         }
         ctx.logger.error?.("[webhook-outbox] redeliver failed", err);
@@ -723,6 +1330,9 @@ var WebhookOutboxPlugin = class {
 export {
   AutoEnqueuer,
   SysWebhook,
-  WebhookOutboxPlugin
+  WEBHOOK_HEADERS_FIELD,
+  WEBHOOK_SECRET_FIELD,
+  WebhookOutboxPlugin,
+  migrateLegacyWebhookSecrets
 };
 //# sourceMappingURL=index.js.map