@objectstack/plugin-webhooks 17.0.0 → 17.1.0

package/dist/index.d.cts

@@ -572,6 +572,71 @@ declare const WEBHOOK_SECRET_FIELD = "signing_secret";
 /** Column on `sys_webhook` holding the encrypted custom-header map. */
 declare const WEBHOOK_HEADERS_FIELD = "headers_secret";
 
+/**
+ * ADR-0112 envelope for this refusal. `VALIDATION_ERROR`/400 is the standard
+ * catalog member for "the payload is not acceptable" — the SAME pair #8559's
+ * `EmptyCredentialWriteError` carries at the same door for the same class of
+ * verdict, so a client branching on `code`/`status` handles both malformed
+ * credential writes identically. A standard-catalog code needs no ledger entry.
+ */
+declare const WEBHOOK_HEADERS_SHAPE_REFUSAL_CODE = "VALIDATION_ERROR";
+declare const WEBHOOK_HEADERS_SHAPE_REFUSAL_STATUS = 400;
+/**
+ * [#8566] Refusal to persist a `headers_secret` plaintext that is not a flat
+ * JSON object of string values.
+ *
+ * Carries the ADR-0112 pair plus the LOCATION (`object`/`field`) as fields, so
+ * a consumer branches on `code`/`status` rather than on message text — the same
+ * discipline {@link WebhookHeadersUnresolvableError} follows on the read side
+ * of this seam, and `EmptyCredentialWriteError` follows on the write side.
+ */
+declare class WebhookHeadersShapeError extends Error {
+    readonly code = "VALIDATION_ERROR";
+    readonly status = 400;
+    readonly object: string;
+    readonly field: string;
+    constructor(object: string, field: string, diagnosis: string);
+}
+/**
+ * The verdict, as a pure function of the write payload — exported so the gate
+ * can be reasoned about and tested without booting an engine, and so any future
+ * caller uses the same one rule rather than restating it.
+ *
+ * Mutates nothing and returns nothing: it either passes or throws
+ * {@link WebhookHeadersShapeError}.
+ */
+declare function assertWritableWebhookHeaders(data: Record<string, unknown> | null | undefined, object?: string, field?: string): void;
+/** Minimal engine surface this binding needs — mirrors `webhook-provenance.ts`. */
+interface MinimalEngine {
+    registerHook(event: string, handler: (ctx: any) => any, options?: Record<string, any>): void;
+    unregisterHooksByPackage(packageId: string): number;
+}
+interface MinimalLogger {
+    info?: (msg: string, meta?: Record<string, any>) => void;
+}
+/**
+ * Bind the shape gate to both write events on `sys_webhook`.
+ *
+ * ## Deliberately NOT exempt for `isSystem`
+ * The provenance stamp next door skips system writes because it is detecting an
+ * ADMIN edit; this is a validity verdict on a payload, and a malformed header
+ * map is exactly as unusable when a seeder writes it. Ruling item 2 says the
+ * plugin's own write paths inherit this validation through the hook, which is
+ * only true if system writes are covered. They pass by construction —
+ * `bootstrapDeclaredWebhooks` and the migration sweep both write
+ * `serializeHeaders(...)` of an already `isHeaderMap`-filtered map — so
+ * covering them costs nothing and closes the door for a future write path that
+ * is less careful.
+ *
+ * Registered in CODE rather than from metadata, which also means
+ * `session.skipAutomations` (an import run with automations unchecked) cannot
+ * suppress it: the engine only skips metadata-bound entries. A validation door
+ * that an import could switch off would not be a door.
+ */
+declare function bindWebhookHeadersShapeGate(engine: MinimalEngine, logger?: MinimalLogger): void;
+/** Remove the gate — mirrors `unbindWebhookProvenanceStamp`, for `dispose()`. */
+declare function unbindWebhookHeadersShapeGate(engine: MinimalEngine): void;
+
 /**
  * [#7799] One-shot boot sweep that moves already-persisted cleartext signing
  * secrets out of `sys_webhook.definition_json` and into the encrypted
@@ -625,4 +690,4 @@ interface MigrateWebhookSecretsResult {
  */
 declare function migrateLegacyWebhookSecrets(engine: IDataEngine, logger?: Logger, subscriptionsObject?: string): Promise<MigrateWebhookSecretsResult>;
 
-export { AutoEnqueuer, type AutoEnqueuerOptions, type HttpEnqueueFn, type MigrateWebhookSecretsResult, WEBHOOK_HEADERS_FIELD, WEBHOOK_SECRET_FIELD, WebhookOutboxPlugin, type WebhookOutboxPluginOptions, migrateLegacyWebhookSecrets };
+export { AutoEnqueuer, type AutoEnqueuerOptions, type HttpEnqueueFn, type MigrateWebhookSecretsResult, WEBHOOK_HEADERS_FIELD, WEBHOOK_HEADERS_SHAPE_REFUSAL_CODE, WEBHOOK_HEADERS_SHAPE_REFUSAL_STATUS, WEBHOOK_SECRET_FIELD, WebhookHeadersShapeError, WebhookOutboxPlugin, type WebhookOutboxPluginOptions, assertWritableWebhookHeaders, bindWebhookHeadersShapeGate, migrateLegacyWebhookSecrets, unbindWebhookHeadersShapeGate };

package/dist/index.d.ts

@@ -572,6 +572,71 @@ declare const WEBHOOK_SECRET_FIELD = "signing_secret";
 /** Column on `sys_webhook` holding the encrypted custom-header map. */
 declare const WEBHOOK_HEADERS_FIELD = "headers_secret";
 
+/**
+ * ADR-0112 envelope for this refusal. `VALIDATION_ERROR`/400 is the standard
+ * catalog member for "the payload is not acceptable" — the SAME pair #8559's
+ * `EmptyCredentialWriteError` carries at the same door for the same class of
+ * verdict, so a client branching on `code`/`status` handles both malformed
+ * credential writes identically. A standard-catalog code needs no ledger entry.
+ */
+declare const WEBHOOK_HEADERS_SHAPE_REFUSAL_CODE = "VALIDATION_ERROR";
+declare const WEBHOOK_HEADERS_SHAPE_REFUSAL_STATUS = 400;
+/**
+ * [#8566] Refusal to persist a `headers_secret` plaintext that is not a flat
+ * JSON object of string values.
+ *
+ * Carries the ADR-0112 pair plus the LOCATION (`object`/`field`) as fields, so
+ * a consumer branches on `code`/`status` rather than on message text — the same
+ * discipline {@link WebhookHeadersUnresolvableError} follows on the read side
+ * of this seam, and `EmptyCredentialWriteError` follows on the write side.
+ */
+declare class WebhookHeadersShapeError extends Error {
+    readonly code = "VALIDATION_ERROR";
+    readonly status = 400;
+    readonly object: string;
+    readonly field: string;
+    constructor(object: string, field: string, diagnosis: string);
+}
+/**
+ * The verdict, as a pure function of the write payload — exported so the gate
+ * can be reasoned about and tested without booting an engine, and so any future
+ * caller uses the same one rule rather than restating it.
+ *
+ * Mutates nothing and returns nothing: it either passes or throws
+ * {@link WebhookHeadersShapeError}.
+ */
+declare function assertWritableWebhookHeaders(data: Record<string, unknown> | null | undefined, object?: string, field?: string): void;
+/** Minimal engine surface this binding needs — mirrors `webhook-provenance.ts`. */
+interface MinimalEngine {
+    registerHook(event: string, handler: (ctx: any) => any, options?: Record<string, any>): void;
+    unregisterHooksByPackage(packageId: string): number;
+}
+interface MinimalLogger {
+    info?: (msg: string, meta?: Record<string, any>) => void;
+}
+/**
+ * Bind the shape gate to both write events on `sys_webhook`.
+ *
+ * ## Deliberately NOT exempt for `isSystem`
+ * The provenance stamp next door skips system writes because it is detecting an
+ * ADMIN edit; this is a validity verdict on a payload, and a malformed header
+ * map is exactly as unusable when a seeder writes it. Ruling item 2 says the
+ * plugin's own write paths inherit this validation through the hook, which is
+ * only true if system writes are covered. They pass by construction —
+ * `bootstrapDeclaredWebhooks` and the migration sweep both write
+ * `serializeHeaders(...)` of an already `isHeaderMap`-filtered map — so
+ * covering them costs nothing and closes the door for a future write path that
+ * is less careful.
+ *
+ * Registered in CODE rather than from metadata, which also means
+ * `session.skipAutomations` (an import run with automations unchecked) cannot
+ * suppress it: the engine only skips metadata-bound entries. A validation door
+ * that an import could switch off would not be a door.
+ */
+declare function bindWebhookHeadersShapeGate(engine: MinimalEngine, logger?: MinimalLogger): void;
+/** Remove the gate — mirrors `unbindWebhookProvenanceStamp`, for `dispose()`. */
+declare function unbindWebhookHeadersShapeGate(engine: MinimalEngine): void;
+
 /**
  * [#7799] One-shot boot sweep that moves already-persisted cleartext signing
  * secrets out of `sys_webhook.definition_json` and into the encrypted
@@ -625,4 +690,4 @@ interface MigrateWebhookSecretsResult {
  */
 declare function migrateLegacyWebhookSecrets(engine: IDataEngine, logger?: Logger, subscriptionsObject?: string): Promise<MigrateWebhookSecretsResult>;
 
-export { AutoEnqueuer, type AutoEnqueuerOptions, type HttpEnqueueFn, type MigrateWebhookSecretsResult, WEBHOOK_HEADERS_FIELD, WEBHOOK_SECRET_FIELD, WebhookOutboxPlugin, type WebhookOutboxPluginOptions, migrateLegacyWebhookSecrets };
+export { AutoEnqueuer, type AutoEnqueuerOptions, type HttpEnqueueFn, type MigrateWebhookSecretsResult, WEBHOOK_HEADERS_FIELD, WEBHOOK_HEADERS_SHAPE_REFUSAL_CODE, WEBHOOK_HEADERS_SHAPE_REFUSAL_STATUS, WEBHOOK_SECRET_FIELD, WebhookHeadersShapeError, WebhookOutboxPlugin, type WebhookOutboxPluginOptions, assertWritableWebhookHeaders, bindWebhookHeadersShapeGate, migrateLegacyWebhookSecrets, unbindWebhookHeadersShapeGate };

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";
@@ -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);
             }
@@ -1143,6 +1235,10 @@ var WebhookOutboxPlugin = class {
         unbindWebhookProvenanceStamp(this.boundEngine);
       } catch {
       }
+      try {
+        unbindWebhookHeadersShapeGate(this.boundEngine);
+      } catch {
+      }
       this.boundEngine = void 0;
     }
   }
@@ -1170,6 +1266,7 @@ var WebhookOutboxPlugin = class {
     }
     this.boundEngine = engine;
     bindWebhookProvenanceStamp(engine, ctx.logger);
+    bindWebhookHeadersShapeGate(engine, ctx.logger);
     let metadataService;
     try {
       metadataService = ctx.getService("metadata");
@@ -1331,8 +1428,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