@objectstack/plugin-webhooks 17.3.0 → 17.4.0

package/dist/index.d.ts

@@ -72,6 +72,15 @@ interface CachedSubscription {
      * when the row itself carries no organization (a `single`-posture install):
      * the delivery then lands NULL, which is honest for a subscription that
      * belongs to no organization. Threaded, never fabricated (#11303's rule).
+     *
+     * [#13566] ALSO the subscription half of the organization MATCH — compared
+     * against the organization the producer stamps on the event
+     * (`DataEvent.organizationId`, #14970; `BulkDataEvent.organizationId`,
+     * #15225 / #15813) before anything is enqueued. See
+     * {@link AutoEnqueuer.admitsOrganization} for the matrix; the short form
+     * is that a subscription with no organization ownership does not receive
+     * an organization-walled event, and a subscription with one receives only
+     * its own organization's.
      */
     organizationId?: string;
     /**
@@ -116,11 +125,17 @@ interface AutoEnqueuerOptions {
  * The handler:
  *   1. Looks up matching subscriptions in an in-memory `Map<object, sub[]>`
  *      — O(1) per event, no DB hit on the write path.
- *   2. Calls `outbox.enqueue()` fire-and-forget for each match. The
+ *   2. [#13566] Compares each candidate's own organization with the one the
+ *      producer stamped on the event — one equality per candidate, no
+ *      lookup (see {@link admitsOrganization}). On a walled deployment this
+ *      is what keeps organization A's record events out of organization B's
+ *      webhook endpoints.
+ *   3. Calls `outbox.enqueue()` fire-and-forget for each match. The
  *      enqueue itself is a single INSERT, which runs *after* the user's
  *      request has already returned.
  *
- * Net cost on the write path: one synchronous Map lookup (~microseconds).
+ * Net cost on the write path: one synchronous Map lookup (~microseconds)
+ * plus one string comparison per candidate subscription.
  *
  * ## Cache freshness
  * The cache is rebuilt:
@@ -187,6 +202,17 @@ declare class AutoEnqueuer {
      * refresh, forever.
      */
     private readonly droppedForSecret;
+    /**
+     * [#13566] Webhook ids whose FIRST organization-dimension refusal has been
+     * said out loud (see {@link admitsOrganization}). Same say-once shape as
+     * {@link droppedForSecret}, for the same reason: a subscription that
+     * cannot receive a class of events must be reported once, with the
+     * remedy, and not once per event forever — an org-less `'*'` subscription
+     * on a walled deployment would otherwise warn on every write of every
+     * organization. Pruned on refresh to the rows still live, so a row that
+     * is deleted and re-created reports again.
+     */
+    private readonly organizationRefusalReported;
     constructor(engine: IDataEngine, realtime: IRealtimeService, enqueue: HttpEnqueueFn, opts?: AutoEnqueuerOptions);
     /**
      * Load the subscription cache and start listening for events.
@@ -380,6 +406,68 @@ declare class AutoEnqueuer {
      * webhook opts in with `bulk_update` / `bulk_delete`.
      */
     private handleBulkEvent;
+    /**
+     * [#13566] The organization dimension of the match — ONE comparison
+     * between the subscription's own organization (cached off its
+     * `sys_webhook` row, #13546) and the organization the producer stamped on
+     * the event (#14970 per record; #15225 / #15813 per batch). ⛔ No lookup:
+     * the enqueuer exists to keep this path O(1), and both halves are already
+     * in hand — the filter is a comparison, never a resolution.
+     *
+     * The cells, and why each falls where it does:
+     *
+     *  | subscription | event  | verdict                                        |
+     *  |--------------|--------|------------------------------------------------|
+     *  | org A        | org A  | deliver                                        |
+     *  | org A        | org B  | not a match — the routine outcome of the new   |
+     *  |              |        | term, silent like an object-name mismatch      |
+     *  | org A        | absent | REFUSE (fail-closed), said once per sub        |
+     *  | none         | org A  | REFUSE, said once per sub — the ruling's case  |
+     *  | none         | absent | deliver — no wall on either side               |
+     *
+     * **`none` × `org A` — the ruling.** A `sys_webhook` row with no
+     * organization on a walled deployment (a package-declared row bootstrapped
+     * under `isSystem`, a row authored before the column was provisioned)
+     * would otherwise receive EVERY organization's records at its URL, signed
+     * with its secret — the leak this card is. Maintainer's ruling
+     * (2026-09-07), verbatim: *a subscription with no organisation ownership
+     * does not fan out — loud refusal, never a silent cross-organisation
+     * delivery.* ADR-0131 D1 is why there is no third reading — NULL is not a
+     * state, so "no organization" is never "every organization".
+     *
+     * **`org A` × `absent` — fail-closed, on BOTH paths.** The two event
+     * families spell absence with the same key and mean different things by
+     * it (`packages/spec/src/api/events.zod.ts`, both members' docs). On a
+     * `DataEvent` it is "this record belongs to no organization" — an
+     * environment-wide row, an object outside the wall, or (the per-record
+     * producer's own docblock, `eventOrganizationId` in
+     * `packages/objectql/src/engine.ts`) no row in hand at the publish site,
+     * published absent rather than substituting the caller's organization.
+     * On a `BulkDataEvent` it is "the producer did not assert one
+     * organization for this batch" — a system or cross-membership predicate
+     * write — and the contract says outright that a tenant-scoped consumer
+     * must not deliver it inside an organization wall. Neither reading names
+     * organization A, so a subscription that belongs to A delivers on
+     * neither. ⛔ Absent is never "no tenancy concern": delivering on it
+     * would turn each of those cases into a cross-organization delivery. The
+     * cost is an environment-wide record not reaching an organization's
+     * webhook — accepted, and said once so the subscription is not dead while
+     * looking armed.
+     *
+     * **`none` × `absent` — deliver.** A `single`-posture deployment stamps
+     * nothing on either side (`postureStampsOrganization` is false there), so
+     * this cell is every event on every non-walled install; on a walled one
+     * it is an environment-wide subscription taking an environment-wide
+     * event. No organization is named anywhere, so there is no wall to cross.
+     *
+     * Both refusals are said ONCE per subscription (the #8022 say-once rule,
+     * ledger {@link organizationRefusalReported}): the first refused event is
+     * a `warn` naming the consequence and the remedy, later ones are
+     * debug-level. Without that a refused subscription reads active:true in
+     * Setup with nothing ever arriving — the "dead while looking armed" shape
+     * ADR-0078 refuses.
+     */
+    private admitsOrganization;
     private handleSelfHealEvent;
     /** Test / admin accessor. */
     snapshot(): ReadonlyMap<string, ReadonlyArray<CachedSubscription>>;

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   SysWebhook
-} from "./chunk-XERWWQKN.js";
+} from "./chunk-MEX2VC7T.js";
 
 // src/webhook-secret.ts
 var WEBHOOK_SECRET_FIELD = "signing_secret";
@@ -192,6 +192,17 @@ var AutoEnqueuer = class {
      * refresh, forever.
      */
     this.droppedForSecret = /* @__PURE__ */ new Set();
+    /**
+     * [#13566] Webhook ids whose FIRST organization-dimension refusal has been
+     * said out loud (see {@link admitsOrganization}). Same say-once shape as
+     * {@link droppedForSecret}, for the same reason: a subscription that
+     * cannot receive a class of events must be reported once, with the
+     * remedy, and not once per event forever — an org-less `'*'` subscription
+     * on a walled deployment would otherwise warn on every write of every
+     * organization. Pruned on refresh to the rows still live, so a row that
+     * is deleted and re-created reports again.
+     */
+    this.organizationRefusalReported = /* @__PURE__ */ new Set();
     this.subscriptionsObject = opts.subscriptionsObject ?? "sys_webhook";
     this.refreshIntervalMs = opts.refreshIntervalMs ?? 6e4;
     this.logger = opts.logger;
@@ -294,11 +305,14 @@ var AutoEnqueuer = class {
     }
     this.subscriptions.clear();
     for (const [k, v] of next) this.subscriptions.set(k, v);
-    if (this.droppedForSecret.size > 0) {
+    if (this.droppedForSecret.size > 0 || this.organizationRefusalReported.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);
       }
+      for (const id of this.organizationRefusalReported) {
+        if (!live.has(id)) this.organizationRefusalReported.delete(id);
+      }
     }
     this.logger?.debug?.("[webhook-auto-enqueuer] cache refreshed", {
       objects: this.subscriptions.size,
@@ -635,9 +649,18 @@ var AutoEnqueuer = class {
       );
       return;
     }
+    const organization = readEventOrganizationId(payload);
+    if (!organization) {
+      this.logger?.warn?.(
+        '[webhook-auto-enqueuer] dropping off-contract data event: `organizationId` is present but not a non-empty string (DataEventSchema refuses that at the publish site) \u2014 fix the producer; never coerced and never read as "no organization"',
+        { type: event.type, object: event.object }
+      );
+      return;
+    }
     const eventId = `${event.object}:${recordId}:${action}:${event.timestamp}`;
     for (const sub of subs) {
       if (!sub.triggers.has(trigger)) continue;
+      if (!this.admitsOrganization(sub, organization.organizationId, event)) continue;
       void this.enqueue({
         source: "webhook",
         refId: sub.id,
@@ -719,8 +742,17 @@ var AutoEnqueuer = class {
       return;
     }
     const eventId = `${event.object}:${event.type}:${eventUuid}`;
+    const organization = readEventOrganizationId(payload);
+    if (!organization) {
+      this.logger?.warn?.(
+        '[webhook-auto-enqueuer] dropping off-contract bulk data event: `organizationId` is present but not a non-empty string (BulkDataEventSchema refuses that at the publish site) \u2014 fix the producer; never coerced and never read as "not asserted"',
+        { type: event.type, object: event.object }
+      );
+      return;
+    }
     for (const sub of subs) {
       if (!sub.triggers.has(trigger)) continue;
+      if (!this.admitsOrganization(sub, organization.organizationId, event)) continue;
       void this.enqueue({
         source: "webhook",
         refId: sub.id,
@@ -748,6 +780,91 @@ var AutoEnqueuer = class {
       }).catch((err) => this.reportWriteFailure(sub, eventId, err, "bulk enqueue"));
     }
   }
+  /**
+   * [#13566] The organization dimension of the match — ONE comparison
+   * between the subscription's own organization (cached off its
+   * `sys_webhook` row, #13546) and the organization the producer stamped on
+   * the event (#14970 per record; #15225 / #15813 per batch). ⛔ No lookup:
+   * the enqueuer exists to keep this path O(1), and both halves are already
+   * in hand — the filter is a comparison, never a resolution.
+   *
+   * The cells, and why each falls where it does:
+   *
+   *  | subscription | event  | verdict                                        |
+   *  |--------------|--------|------------------------------------------------|
+   *  | org A        | org A  | deliver                                        |
+   *  | org A        | org B  | not a match — the routine outcome of the new   |
+   *  |              |        | term, silent like an object-name mismatch      |
+   *  | org A        | absent | REFUSE (fail-closed), said once per sub        |
+   *  | none         | org A  | REFUSE, said once per sub — the ruling's case  |
+   *  | none         | absent | deliver — no wall on either side               |
+   *
+   * **`none` × `org A` — the ruling.** A `sys_webhook` row with no
+   * organization on a walled deployment (a package-declared row bootstrapped
+   * under `isSystem`, a row authored before the column was provisioned)
+   * would otherwise receive EVERY organization's records at its URL, signed
+   * with its secret — the leak this card is. Maintainer's ruling
+   * (2026-09-07), verbatim: *a subscription with no organisation ownership
+   * does not fan out — loud refusal, never a silent cross-organisation
+   * delivery.* ADR-0131 D1 is why there is no third reading — NULL is not a
+   * state, so "no organization" is never "every organization".
+   *
+   * **`org A` × `absent` — fail-closed, on BOTH paths.** The two event
+   * families spell absence with the same key and mean different things by
+   * it (`packages/spec/src/api/events.zod.ts`, both members' docs). On a
+   * `DataEvent` it is "this record belongs to no organization" — an
+   * environment-wide row, an object outside the wall, or (the per-record
+   * producer's own docblock, `eventOrganizationId` in
+   * `packages/objectql/src/engine.ts`) no row in hand at the publish site,
+   * published absent rather than substituting the caller's organization.
+   * On a `BulkDataEvent` it is "the producer did not assert one
+   * organization for this batch" — a system or cross-membership predicate
+   * write — and the contract says outright that a tenant-scoped consumer
+   * must not deliver it inside an organization wall. Neither reading names
+   * organization A, so a subscription that belongs to A delivers on
+   * neither. ⛔ Absent is never "no tenancy concern": delivering on it
+   * would turn each of those cases into a cross-organization delivery. The
+   * cost is an environment-wide record not reaching an organization's
+   * webhook — accepted, and said once so the subscription is not dead while
+   * looking armed.
+   *
+   * **`none` × `absent` — deliver.** A `single`-posture deployment stamps
+   * nothing on either side (`postureStampsOrganization` is false there), so
+   * this cell is every event on every non-walled install; on a walled one
+   * it is an environment-wide subscription taking an environment-wide
+   * event. No organization is named anywhere, so there is no wall to cross.
+   *
+   * Both refusals are said ONCE per subscription (the #8022 say-once rule,
+   * ledger {@link organizationRefusalReported}): the first refused event is
+   * a `warn` naming the consequence and the remedy, later ones are
+   * debug-level. Without that a refused subscription reads active:true in
+   * Setup with nothing ever arriving — the "dead while looking armed" shape
+   * ADR-0078 refuses.
+   */
+  admitsOrganization(sub, eventOrganizationId, event) {
+    if (sub.organizationId === eventOrganizationId) return true;
+    if (sub.organizationId !== void 0 && eventOrganizationId !== void 0) return false;
+    const orgless = sub.organizationId === void 0;
+    const meta = {
+      id: sub.id,
+      webhook: sub.name,
+      type: event.type,
+      object: event.object,
+      subscriptionOrganizationId: sub.organizationId,
+      eventNamesOrganization: eventOrganizationId !== void 0
+    };
+    if (this.organizationRefusalReported.has(sub.id)) {
+      this.logger?.debug?.(
+        `[webhook-auto-enqueuer] webhook '${sub.name}' still refused on the organization dimension`,
+        meta
+      );
+      return false;
+    }
+    this.organizationRefusalReported.add(sub.id);
+    const message = orgless ? `[webhook-auto-enqueuer] webhook '${sub.name}' belongs to NO organization, but this ${event.type} event on '${event.object}' is organization-walled (the producer stamped organizationId) \u2014 refusing to fan out: a subscription with no organization ownership does not receive an organization's records. It will receive NO organization-walled event while reading active:true in Setup; author the webhook inside the organization that should receive these events. Said once per subscription.` : `[webhook-auto-enqueuer] webhook '${sub.name}' belongs to organization '${sub.organizationId}', but this ${event.type} event on '${event.object}' names no organization \u2014 refusing to deliver it inside an organization wall: on the per-record path an absent organizationId is an environment-wide row or an object outside the wall; on the bulk path it is a batch the producer could not attribute to one organization (a system or cross-membership predicate write). A tenant-scoped subscription receives only events attributable to its own organization. Said once per subscription.`;
+    this.logger?.warn?.(message, meta);
+    return false;
+  }
   handleSelfHealEvent(event) {
     if (event.object !== this.subscriptionsObject) return;
     if (!event.type?.startsWith("data.record.") && !event.type?.startsWith("data.records.")) return;
@@ -772,6 +889,12 @@ function mapActionToTrigger(action) {
       return null;
   }
 }
+function readEventOrganizationId(payload) {
+  const value = payload.organizationId;
+  if (value === void 0) return { organizationId: void 0 };
+  if (typeof value !== "string" || value === "") return void 0;
+  return { organizationId: value };
+}
 function mapBulkActionToTrigger(action) {
   switch (action) {
     case "updated":
@@ -1035,34 +1158,18 @@ function createWebhookRedeliverGuard(engine, subscriptionsObject = WEBHOOK_OBJEC
 
 // src/webhook-provenance.ts
 var WEBHOOK_PROVENANCE_PACKAGE = "plugin-webhooks:provenance";
-var SYSTEM_CTX3 = { isSystem: true, positions: [], permissions: [] };
 function bindWebhookProvenanceStamp(engine, logger) {
   if (typeof engine?.registerHook !== "function") return;
   engine.registerHook(
     "beforeUpdate",
     async (ctx) => {
       if (ctx?.session?.isSystem) return;
-      const id = ctx?.input?.id ?? ctx?.input?.data?.id;
-      if (!id) return;
       const data = ctx?.input?.data;
       if (!data || typeof data !== "object") return;
-      try {
-        const rows = await engine.find("sys_webhook", {
-          where: { id },
-          fields: ["id", "managed_by", "customized"],
-          limit: 1,
-          context: SYSTEM_CTX3
-        });
-        const row = Array.isArray(rows) ? rows[0] : void 0;
-        if (!row) return;
-        if ((row.managed_by === "package" || row.managed_by === "platform") && row.customized !== true) {
-          data.customized = true;
-        }
-      } catch (err) {
-        logger?.warn?.("[webhook] provenance stamp failed (edit proceeds unstamped)", {
-          id,
-          error: err?.message
-        });
+      const previous = ctx?.previous;
+      if (!previous || typeof previous !== "object") return;
+      if ((previous.managed_by === "package" || previous.managed_by === "platform") && previous.customized !== true) {
+        data.customized = true;
       }
     },
     { object: "sys_webhook", packageId: WEBHOOK_PROVENANCE_PACKAGE, priority: 150 }
@@ -1220,7 +1327,7 @@ var WebhookOutboxPlugin = class {
         try {
           const i18n = ctx.getService("i18n");
           if (i18n && typeof i18n.loadTranslations === "function") {
-            const { WebhooksTranslations } = await import("./translations-CPXQB2NM.js");
+            const { WebhooksTranslations } = await import("./translations-MNRJO53N.js");
             for (const [locale, data] of Object.entries(WebhooksTranslations)) {
               i18n.loadTranslations(locale, data);
             }