@objectstack/plugin-webhooks 17.0.0 → 17.2.0

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   SysWebhook
-} from "./chunk-GDCWDVDT.js";
+} from "./chunk-XERWWQKN.js";
 
 // src/webhook-secret.ts
 var WEBHOOK_SECRET_FIELD = "signing_secret";
@@ -194,7 +194,7 @@ var AutoEnqueuer = class {
     this.droppedForSecret = /* @__PURE__ */ new Set();
     this.subscriptionsObject = opts.subscriptionsObject ?? "sys_webhook";
     this.refreshIntervalMs = opts.refreshIntervalMs ?? 6e4;
-    this.logger = opts.logger ?? {};
+    this.logger = opts.logger;
   }
   /**
    * Load the subscription cache and start listening for events.
@@ -219,7 +219,7 @@ var AutoEnqueuer = class {
     if (this.refreshIntervalMs > 0) {
       this.refreshTimer = setInterval(() => {
         this.refresh().catch(
-          (err) => this.logger.warn?.("[webhook-auto-enqueuer] periodic refresh failed", err)
+          (err) => this.logger?.warn?.("[webhook-auto-enqueuer] periodic refresh failed", err)
         );
       }, this.refreshIntervalMs);
       this.refreshTimer.unref?.();
@@ -252,7 +252,7 @@ var AutoEnqueuer = class {
   rearmAfterCryptoRegistered() {
     const inFlight = this.refreshing ?? Promise.resolve();
     void inFlight.catch(() => void 0).then(() => this.running ? this.refresh() : void 0).catch(
-      (err) => this.logger.warn?.(
+      (err) => this.logger?.warn?.(
         "[webhook-auto-enqueuer] re-arm after CryptoProvider registration failed",
         err
       )
@@ -276,7 +276,7 @@ var AutoEnqueuer = class {
         where: { active: true }
       });
     } catch (err) {
-      this.logger.warn?.(
+      this.logger?.warn?.(
         `[webhook-auto-enqueuer] failed to load ${this.subscriptionsObject}`,
         err
       );
@@ -300,7 +300,7 @@ var AutoEnqueuer = class {
         if (!live.has(id)) this.droppedForSecret.delete(id);
       }
     }
-    this.logger.debug?.("[webhook-auto-enqueuer] cache refreshed", {
+    this.logger?.debug?.("[webhook-auto-enqueuer] cache refreshed", {
       objects: this.subscriptions.size,
       rows: rows.length
     });
@@ -371,14 +371,14 @@ var AutoEnqueuer = class {
   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);
+      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);
+    if (typeof this.logger?.error === "function") {
+      this.logger?.error(message, err, meta);
     } else {
-      this.logger.warn?.(message, meta);
+      this.logger?.warn?.(message, meta);
     }
   }
   park(sub, err, credential) {
@@ -430,7 +430,7 @@ var AutoEnqueuer = class {
     }
     const legacy = readLegacySecret(row?.definition_json);
     if (legacy) {
-      this.logger.warn?.(
+      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 }
       );
@@ -480,7 +480,7 @@ var AutoEnqueuer = class {
     }
     const legacy = readLegacyHeaders(row?.definition_json);
     if (legacy) {
-      this.logger.warn?.(
+      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 }
       );
@@ -523,7 +523,7 @@ var AutoEnqueuer = class {
       err: err?.message ?? err
     };
     if (this.droppedForSecret.has(sub.id)) {
-      this.logger.debug?.(
+      this.logger?.debug?.(
         `[webhook-auto-enqueuer] webhook '${sub.name}' is still dropped for an unresolvable ${credential.noun} (${credential.issues})`,
         meta
       );
@@ -531,10 +531,10 @@ var AutoEnqueuer = class {
     }
     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);
+    if (typeof this.logger?.error === "function") {
+      this.logger?.error(message, err, meta);
     } else {
-      this.logger.warn?.(message, meta);
+      this.logger?.warn?.(message, meta);
     }
   }
   parseRow(row) {
@@ -559,7 +559,7 @@ var AutoEnqueuer = class {
     const normalized = triggerList.map((t) => t.trim().toLowerCase()).filter(Boolean);
     const unknown = normalized.filter((t) => !DISPATCHABLE_WEBHOOK_TRIGGERS.has(t));
     if (unknown.length > 0) {
-      this.logger.warn?.(
+      this.logger?.warn?.(
         `[webhook-auto-enqueuer] webhook '${row.name ?? row.id}' declares trigger(s) the engine never emits: ${unknown.join(", ")} \u2014 ignored. Dispatchable triggers: ${[...DISPATCHABLE_WEBHOOK_TRIGGERS].join(", ")}.`,
         { id: row.id, unknown }
       );
@@ -568,7 +568,7 @@ var AutoEnqueuer = class {
       normalized.filter((t) => DISPATCHABLE_WEBHOOK_TRIGGERS.has(t))
     );
     if (triggers.size === 0) {
-      this.logger.warn?.(
+      this.logger?.warn?.(
         `[webhook-auto-enqueuer] webhook '${row.name ?? row.id}' has no dispatchable triggers \u2014 it will NEVER fire (rule webhook/without-triggers): there is no manual fire path (#3196), so this row is dead while looking armed in Setup. Declare one of: ${[...DISPATCHABLE_WEBHOOK_TRIGGERS].join(", ")}, or set it inactive if it should be off.`,
         { id: row.id }
       );
@@ -625,7 +625,7 @@ var AutoEnqueuer = class {
     const payload = event.payload ?? {};
     const recordId = payload.recordId;
     if (typeof recordId !== "string" || recordId === "") {
-      this.logger.warn?.(
+      this.logger?.warn?.(
         "[webhook-auto-enqueuer] dropping off-contract data event: payload is not a DataEvent (no top-level string `recordId`) \u2014 fix the producer",
         { type: event.type, object: event.object }
       );
@@ -694,7 +694,7 @@ var AutoEnqueuer = class {
     const payload = event.payload ?? {};
     const matched = payload.matched;
     if (typeof matched !== "number" || !Number.isInteger(matched) || matched < 0) {
-      this.logger.warn?.(
+      this.logger?.warn?.(
         "[webhook-auto-enqueuer] dropping off-contract bulk data event: payload is not a BulkDataEvent (no top-level non-negative integer `matched`) \u2014 fix the producer",
         { type: event.type, object: event.object }
       );
@@ -702,7 +702,7 @@ var AutoEnqueuer = class {
     }
     const eventUuid = payload.id;
     if (typeof eventUuid !== "string" || eventUuid === "") {
-      this.logger.warn?.(
+      this.logger?.warn?.(
         "[webhook-auto-enqueuer] dropping off-contract bulk data event: payload has no top-level string `id` to dedup on \u2014 fix the producer",
         { type: event.type, object: event.object }
       );
@@ -739,7 +739,7 @@ var AutoEnqueuer = class {
     if (event.object !== this.subscriptionsObject) return;
     if (!event.type?.startsWith("data.record.") && !event.type?.startsWith("data.records.")) return;
     this.refresh().catch(
-      (err) => this.logger.warn?.("[webhook-auto-enqueuer] self-heal refresh failed", err)
+      (err) => this.logger?.warn?.("[webhook-auto-enqueuer] self-heal refresh failed", err)
     );
   }
   /** Test / admin accessor. */
@@ -1062,6 +1062,98 @@ function unbindWebhookProvenanceStamp(engine) {
   }
 }
 
+// src/webhook-headers-gate.ts
+var WEBHOOK_HEADERS_SHAPE_REFUSAL_CODE = "VALIDATION_ERROR";
+var WEBHOOK_HEADERS_SHAPE_REFUSAL_STATUS = 400;
+var DECLARED_SHAPE = 'Custom HTTP headers sent with each delivery, as a JSON object ({"Authorization": "Bearer ..."})';
+var WebhookHeadersShapeError = class extends Error {
+  constructor(object, field, diagnosis) {
+    super(
+      `Custom headers refused for "${object}.${field}": ${diagnosis}. The required shape is a FLAT JSON object of string values, which is what the field itself asks for \u2014 its description reads: "${DECLARED_SHAPE}". This is checked at the write door because one step later there is nothing left to check: the engine encrypts this value into sys_secret and every read path returns only the mask, so a stored value that can never be used is indistinguishable from one that works until the next delivery tries to send it \u2014 at which point the subscription parks and the report arrives an unbounded time later, in a different surface from the one it was typed into (#7986, #8558, #8566). ${HEADERS_REMEDY}`
+    );
+    this.code = WEBHOOK_HEADERS_SHAPE_REFUSAL_CODE;
+    this.status = WEBHOOK_HEADERS_SHAPE_REFUSAL_STATUS;
+    this.name = "WebhookHeadersShapeError";
+    this.object = object;
+    this.field = field;
+  }
+};
+function describeParsed(parsed) {
+  if (parsed === null) return "null";
+  if (Array.isArray(parsed)) return "a JSON array";
+  if (typeof parsed !== "object") return `a JSON ${typeof parsed}`;
+  const entries = Object.entries(parsed);
+  if (entries.length === 0) {
+    return 'an EMPTY JSON object, which is not the same thing as "send no custom headers"';
+  }
+  const bad = entries.filter(([, v]) => typeof v !== "string");
+  if (bad.length > 0) {
+    const named = bad.map(([k, v]) => `${JSON.stringify(k)} (${Array.isArray(v) ? "array" : v === null ? "null" : typeof v})`).join(", ");
+    return `a JSON object, but the wire carries only strings and ${bad.length === 1 ? "this value is" : "these values are"} not a string: ${named}`;
+  }
+  return "a JSON object the header seam does not accept";
+}
+function describeRejected(value) {
+  if (typeof value === "string") {
+    let parsed;
+    try {
+      parsed = JSON.parse(value);
+    } catch {
+      return "the value is a string that is not valid JSON at all \u2014 check for unquoted keys or values ({X-Team: crm}), single quotes instead of double, or a trailing comma";
+    }
+    return `the value parses as JSON but is ${describeParsed(parsed)}`;
+  }
+  return `the value is ${describeParsed(value)}`;
+}
+function assertWritableWebhookHeaders(data, object = WEBHOOK_OBJECT, field = WEBHOOK_HEADERS_FIELD) {
+  if (!data || typeof data !== "object") return;
+  if (!Object.prototype.hasOwnProperty.call(data, field)) return;
+  const value = data[field];
+  if (value === null || typeof value === "undefined") return;
+  if (value === "") return;
+  if (isOpaqueSecretForm(value)) return;
+  let serialized;
+  if (typeof value === "string") {
+    serialized = value;
+  } else {
+    try {
+      serialized = JSON.stringify(value);
+    } catch {
+      throw new WebhookHeadersShapeError(
+        object,
+        field,
+        "the value cannot be serialized to JSON at all (it contains a circular reference)"
+      );
+    }
+    if (typeof serialized !== "string") {
+      throw new WebhookHeadersShapeError(object, field, `the value is a ${typeof value}`);
+    }
+  }
+  if (parseStoredHeaders(serialized)) return;
+  throw new WebhookHeadersShapeError(object, field, describeRejected(value));
+}
+var WEBHOOK_HEADERS_GATE_PACKAGE = "plugin-webhooks:headers-shape-gate";
+var GATE_PRIORITY = 50;
+function bindWebhookHeadersShapeGate(engine, logger) {
+  if (typeof engine?.registerHook !== "function") return;
+  const handler = (ctx) => {
+    assertWritableWebhookHeaders(ctx?.input?.data);
+  };
+  for (const event of ["beforeInsert", "beforeUpdate"]) {
+    engine.registerHook(event, handler, {
+      object: WEBHOOK_OBJECT,
+      packageId: WEBHOOK_HEADERS_GATE_PACKAGE,
+      priority: GATE_PRIORITY
+    });
+  }
+  logger?.info?.("[webhook] headers_secret shape gate bound (refuses non-flat-string-map plaintext)");
+}
+function unbindWebhookHeadersShapeGate(engine) {
+  if (typeof engine?.unregisterHooksByPackage === "function") {
+    engine.unregisterHooksByPackage(WEBHOOK_HEADERS_GATE_PACKAGE);
+  }
+}
+
 // src/webhook-outbox-plugin.ts
 var WebhookOutboxPlugin = class {
   constructor(options = {}) {
@@ -1115,7 +1207,7 @@ var WebhookOutboxPlugin = class {
         try {
           const i18n = ctx.getService("i18n");
           if (i18n && typeof i18n.loadTranslations === "function") {
-            const { WebhooksTranslations } = await import("./translations-U32QIEPB.js");
+            const { WebhooksTranslations } = await import("./translations-IAKF6NAP.js");
             for (const [locale, data] of Object.entries(WebhooksTranslations)) {
               i18n.loadTranslations(locale, data);
             }
@@ -1136,16 +1228,44 @@ var WebhookOutboxPlugin = class {
       autoEnqueue: autoEnqueueOpt !== false
     });
   }
-  async dispose() {
+  /**
+   * Teardown — the kernel's ONLY teardown hook.
+   *
+   * [#10772] This body used to be spelled `dispose()`. `Plugin`
+   * (`@objectstack/core`'s `types.ts`) declares `init()`, `start?(ctx)` and
+   * `destroy?()` and no `dispose()`, and `ObjectKernel.performShutdown()` /
+   * `LiteKernel.destroy()` walk the plugins in reverse calling
+   * `plugin.destroy()` — so after `await kernel.shutdown()` had RESOLVED the
+   * auto-enqueuer was still running and both engine hooks were still bound.
+   * Measured on the same revision: `dispose()` had ZERO callers anywhere in
+   * the repo, so this teardown had never run in any process at all.
+   *
+   * Idempotent: `boundEngine` is cleared as it is unbound, so a second
+   * teardown is a no-op rather than a second unbind.
+   */
+  async destroy() {
     await this.autoEnqueuer?.stop();
     if (this.boundEngine) {
       try {
         unbindWebhookProvenanceStamp(this.boundEngine);
       } catch {
       }
+      try {
+        unbindWebhookHeadersShapeGate(this.boundEngine);
+      } catch {
+      }
       this.boundEngine = void 0;
     }
   }
+  /**
+   * Retained alias for {@link destroy}. Kept because it is public API of an
+   * exported class: an embedder may have learned to call it directly
+   * precisely BECAUSE the kernel never did, and deleting it would break them.
+   * Same signature, same return type — a direct caller sees no change.
+   */
+  async dispose() {
+    await this.destroy();
+  }
   getMessaging(ctx) {
     const svc = this.tryGetService(ctx, ["messaging"]);
     return svc && typeof svc.enqueueHttp === "function" ? svc : void 0;
@@ -1170,6 +1290,7 @@ var WebhookOutboxPlugin = class {
     }
     this.boundEngine = engine;
     bindWebhookProvenanceStamp(engine, ctx.logger);
+    bindWebhookHeadersShapeGate(engine, ctx.logger);
     let metadataService;
     try {
       metadataService = ctx.getService("metadata");
@@ -1256,8 +1377,21 @@ var WebhookOutboxPlugin = class {
   }
   /**
    * Mount POST /api/v1/webhooks/redeliver on the host Hono app, if one is
-   * available. Delegates to `messaging.redeliverHttp(deliveryId)`. Auth is the
-   * better-auth session cookie — every authenticated user counts.
+   * available. Delegates to `messaging.redeliverHttp(deliveryId, …)`. Auth is
+   * the better-auth session cookie — every authenticated user counts.
+   *
+   * [#10740] Which is precisely why the caller's ACTIVE ORGANIZATION is
+   * resolved here and threaded into the call. `sys_http_delivery` is
+   * tenant-scoped, and this is the one door on it a request can reach: an
+   * unscoped replay from here is an authenticated user reaching another
+   * organization's delivery row on a walled deployment. With the tenant
+   * threaded, a row outside the caller's organization is simply not found.
+   *
+   * ⚠️ A session with no active organization threads `undefined`, and the
+   * driver's tenant-audit line then fires for that write. That is deliberate:
+   * the deployment could not tell us who is asking, and reporting the gap is
+   * the correct outcome. ⛔ It is never repaired with `bypassTenantAudit`,
+   * which would silence the report without closing anything.
    */
   registerAdminRoutes(ctx) {
     const http = this.tryGetService(ctx, ["http-server"]);
@@ -1269,8 +1403,9 @@ var WebhookOutboxPlugin = class {
     const messaging = this.getMessaging(ctx);
     if (!rawApp || !messaging) return;
     rawApp.post("/api/v1/webhooks/redeliver", async (c) => {
-      const userId = await this.resolveSessionUserId(ctx, c);
-      if (!userId) {
+      const session = await this.resolveSession(ctx, c);
+      const userId = session?.user?.id;
+      if (typeof userId !== "string" || userId.length === 0) {
         return c.json(
           { success: false, error: { code: "UNAUTHENTICATED", message: "Sign in to redeliver webhook deliveries." } },
           401
@@ -1290,8 +1425,10 @@ var WebhookOutboxPlugin = class {
         );
       }
       try {
-        const row = await messaging.redeliverHttp(deliveryId);
-        ctx.logger.info?.("[webhook-outbox] redelivered", { deliveryId, requestedBy: userId });
+        const activeOrg = session?.session?.activeOrganizationId;
+        const tenantId = typeof activeOrg === "string" && activeOrg.length > 0 ? activeOrg : void 0;
+        const row = await messaging.redeliverHttp(deliveryId, { tenantId });
+        ctx.logger.info?.("[webhook-outbox] redelivered", { deliveryId, requestedBy: userId, tenantId });
         return c.json({ success: true, data: { id: row.id, status: row.status } });
       } catch (err) {
         const code = err?.code;
@@ -1310,7 +1447,18 @@ var WebhookOutboxPlugin = class {
     });
     ctx.logger.info?.("[webhook-outbox] redeliver endpoint mounted at POST /api/v1/webhooks/redeliver");
   }
-  async resolveSessionUserId(ctx, c) {
+  /**
+   * [#10740] The better-auth session envelope (`{ user, session }`) for this
+   * request, or `undefined`.
+   *
+   * Widened from the previous `resolveSessionUserId` because the route now
+   * needs two facts from ONE lookup: who is asking (`user.id`, the
+   * authentication gate) and which organization they are asking as
+   * (`session.activeOrganizationId`, the tenant threaded into the write).
+   * Resolving them separately would mean two `getSession` calls that can
+   * disagree.
+   */
+  async resolveSession(ctx, c) {
     try {
       const authService = this.tryGetService(ctx, ["auth"]);
       if (!authService) return void 0;
@@ -1319,9 +1467,7 @@ var WebhookOutboxPlugin = class {
         api = await authService.getApi();
       }
       if (!api?.getSession) return void 0;
-      const session = await api.getSession({ headers: c.req.raw.headers });
-      const uid2 = session?.user?.id;
-      return typeof uid2 === "string" && uid2.length > 0 ? uid2 : void 0;
+      return await api.getSession({ headers: c.req.raw.headers });
     } catch {
       return void 0;
     }
@@ -1331,8 +1477,14 @@ export {
   AutoEnqueuer,
   SysWebhook,
   WEBHOOK_HEADERS_FIELD,
+  WEBHOOK_HEADERS_SHAPE_REFUSAL_CODE,
+  WEBHOOK_HEADERS_SHAPE_REFUSAL_STATUS,
   WEBHOOK_SECRET_FIELD,
+  WebhookHeadersShapeError,
   WebhookOutboxPlugin,
-  migrateLegacyWebhookSecrets
+  assertWritableWebhookHeaders,
+  bindWebhookHeadersShapeGate,
+  migrateLegacyWebhookSecrets,
+  unbindWebhookHeadersShapeGate
 };
 //# sourceMappingURL=index.js.map