@patchstack/connect 0.3.27 → 0.3.29

package/dist/protect.d.ts

@@ -68,6 +68,23 @@ export interface CreateProtectionOptions {
    * Also disabled when `PATCHSTACK_TELEMETRY=off` or when no apiKey is available.
    */
   reportFirewallLog?: boolean;
+  /**
+   * Report EVERY rule that fired — including one in `dry-run` that did not block — to the Pulse
+   * detections endpoint. Off unless explicitly `true`.
+   *
+   * Why it exists: a rule that blocks nothing reports nothing, so a rule that is quietly wrong and a
+   * rule that is protecting look identical from the outside.
+   *
+   * What it sends, per detection: the rule id, the request PATH with the query string removed, the
+   * parameters the rule reads, the phase, whether it was enforced, the rule-bundle ETag, and a
+   * timestamp. It does NOT send the matched value, the request body, headers, or query-string values —
+   * this is a counting channel, not a copy of your traffic.
+   *
+   * Off by default because switching it on adds an outbound request to every guard with a site UUID.
+   */
+  reportDetections?: boolean;
+  /** How long to buffer detections before posting a batch. Default 5000ms. */
+  detectionFlushMs?: number;
   /** Optional Source-Host header for connector hostname checks. */
   sourceHost?: string;
   /** Optional fetch override (tests). */

package/dist/protect.edge.js

@@ -512,6 +512,35 @@ var RequestResolver = class {
   }
 };
 
+// src/protect/notify.js
+var reported = /* @__PURE__ */ new Set();
+function notify(fn, arg, label) {
+  if (typeof fn !== "function") return false;
+  try {
+    const result = fn(arg);
+    if (result !== null && typeof result === "object" && typeof result.then === "function") {
+      try {
+        result.then(void 0, (err) => warnOnce2(label, err));
+      } catch {
+      }
+    }
+    return true;
+  } catch (err) {
+    warnOnce2(label, err);
+    return false;
+  }
+}
+function warnOnce2(label, err) {
+  if (reported.has(label)) return;
+  reported.add(label);
+  try {
+    console.warn(
+      `Patchstack: the ${label} callback passed to createProtection failed and was ignored. Protection is unaffected; this is reported once per process. Cause: ${err && err.message ? err.message : String(err)}`
+    );
+  } catch {
+  }
+}
+
 // src/protect/engine/normalizer.js
 var HTML_ENTITIES = {
   "&": "&",
@@ -796,7 +825,7 @@ function collectLeafValues(root, nodeCap = 2e4, maxDepth = 1e3) {
   return out;
 }
 var warnedKeys = /* @__PURE__ */ new Set();
-function warnOnce2(key, message) {
+function warnOnce3(key, message) {
   if (warnedKeys.has(key)) return;
   warnedKeys.add(key);
   console.warn(message);
@@ -1138,21 +1167,20 @@ var RuleEngine = class {
     this.#whitelistKeys = whitelist_keys;
     this.#onError = onError;
     if (Array.isArray(whitelists) && whitelists.some((w) => w && Array.isArray(w.rule_v2) && !w.rule_id)) {
-      warnOnce2(
+      warnOnce3(
         "whitelist-no-rule-id",
         "[patchstack] a whitelist has no `rule_id` \u2014 it suppresses ALL rules when it matches. Scope each whitelist to a specific rule_id, and key it only on values an attacker cannot set."
       );
     }
     if (whitelist_keys && typeof whitelist_keys === "object" && Object.keys(whitelist_keys).length > 0) {
-      warnOnce2("whitelist-keys-unimplemented", "[patchstack] `whitelist_keys` is not implemented and has no effect.");
+      warnOnce3("whitelist-keys-unimplemented", "[patchstack] `whitelist_keys` is not implemented and has no effect.");
     }
   }
   // A mitigation engine must never take down the app it protects: any error while
   // evaluating a rule is reported and the request is allowed through (fail open). A
   // malformed rule is skipped without aborting the rest of the ruleset.
   #reportError(err) {
-    if (this.#onError) {
-      this.#onError(err);
+    if (notify(this.#onError, err, "onError")) {
       return;
     }
     const key = err && err.message ? err.message : String(err);
@@ -1360,13 +1388,15 @@ var PulseRuleClient = class {
   #ttlEffective = 0;
   #etag;
   #pulseAuth;
-  constructor({ siteUuid, baseUrl, cacheTtl, etag, timeoutMs, pulseAuth } = {}) {
+  #reportsDetections;
+  constructor({ siteUuid, baseUrl, cacheTtl, etag, timeoutMs, pulseAuth, reportsDetections } = {}) {
     this.#timeoutMs = Number(timeoutMs) > 0 ? Number(timeoutMs) : 3e4;
     this.#siteUuid = siteUuid ?? process.env.PATCHSTACK_SITE_UUID;
     this.#baseUrl = safeBaseUrl(baseUrl ?? process.env.PATCHSTACK_PULSE_RULES_URL, DEFAULT_BASE_URL2, "rule endpoint");
     this.#cacheTtl = Number.isFinite(cacheTtl) && cacheTtl > 0 ? cacheTtl : DEFAULT_CACHE_TTL2;
     this.#etag = etag ?? null;
     this.#pulseAuth = pulseAuth ?? null;
+    this.#reportsDetections = reportsDetections === true;
     if (!this.#siteUuid) {
       throw new Error("Patchstack site UUID is required. Pass { siteUuid } or set PATCHSTACK_SITE_UUID.");
     }
@@ -1378,13 +1408,14 @@ var PulseRuleClient = class {
     }
     const url = `${this.#baseUrl}/rules/${encodeURIComponent(this.#siteUuid)}`;
     try {
-      const headers = {
-        Accept: "application/json",
-        ...await pulseAuthHeader(
-          { pulseAuth: this.#pulseAuth, endpoint: this.#baseUrl, timeoutMs: this.#timeoutMs },
-          fetch
-        )
-      };
+      const auth = await pulseAuthHeader(
+        { pulseAuth: this.#pulseAuth, endpoint: this.#baseUrl, timeoutMs: this.#timeoutMs },
+        fetch
+      );
+      const headers = { Accept: "application/json", ...auth };
+      if (this.#reportsDetections && typeof auth.Authorization === "string") {
+        headers["X-Patchstack-Detections"] = "enabled";
+      }
       if (this.#etag) headers["If-None-Match"] = this.#etag;
       const response = await fetch(url, { method: "GET", headers, signal: AbortSignal.timeout(this.#timeoutMs) });
       if (response.status === 304) {
@@ -1666,7 +1697,7 @@ async function installEgressGuard({ shouldBlock, onBlock, onSkip, dnsScreen = tr
   const exempt = new Set((allowHosts ?? []).map((h) => String(h).toLowerCase()));
   const block = (url, host, method) => {
     if (!shouldBlock(url, host, method)) return false;
-    onBlock?.({ url, host, method });
+    notify(onBlock, { url, host, method }, "onEgressBlock");
     return true;
   };
   let screen = null;
@@ -1681,12 +1712,7 @@ async function installEgressGuard({ shouldBlock, onBlock, onSkip, dnsScreen = tr
       screen = null;
     }
   }
-  const skip = (reason, detail) => {
-    try {
-      onSkip?.({ phase: "egress", reason, detail });
-    } catch {
-    }
-  };
+  const skip = (reason, detail) => notify(onSkip, { phase: "egress", reason, detail }, "onSkip");
   const resolvesToDisallowed = (url, host, method) => new Promise((resolve) => {
     if (!screen) {
       if (host && dnsScreen) skip("resolver-unavailable", { host });
@@ -2272,22 +2298,19 @@ function reportRejections(rejected, options, label) {
   const report = options.onRuleRejected;
   for (const r of rejected) {
     if (typeof report === "function") {
-      try {
-        report({ ...r, accepted: false });
-      } catch {
-      }
+      notify(report, { ...r, accepted: false }, "onRuleRejected");
     }
   }
   const sample = rejected.slice(0, 3).map((r) => `${r.id} (${r.reason})`).join("; ");
-  options.onError?.(new Error(
+  notify(options.onError, new Error(
     `${label}: rejected the entire update because ${rejected.length} rule(s) failed validation \u2014 keeping the previous ruleset and NOT caching this response: ${sample}${rejected.length > 3 ? ", \u2026" : ""}`
-  ));
+  ), "onError");
 }
 async function resolveRules(options, store, ctx = {}) {
   const timeoutMs = ctx.timeoutMs;
   if (options.siteUuid) {
     const prior = await store.read();
-    const client = new PulseRuleClient({ siteUuid: options.siteUuid, baseUrl: options.pulseRulesUrl, etag: prior?.etag, timeoutMs, pulseAuth: ctx.pulseAuth });
+    const client = new PulseRuleClient({ siteUuid: options.siteUuid, baseUrl: options.pulseRulesUrl, etag: prior?.etag, timeoutMs, pulseAuth: ctx.pulseAuth, reportsDetections: options.reportDetections === true });
     const res = await client.getRules();
     if (res.success && res.notModified && prior?.bundle) return normalizeBundle(prior.bundle, options);
     if (res.success && !res.notModified) {
@@ -2303,14 +2326,14 @@ async function resolveRules(options, store, ctx = {}) {
       return bundle;
     }
     if (prior?.bundle) {
-      options.onError?.(new Error(`pulse rule fetch failed (${res.error ?? "no usable response"}); using cached bundle`));
+      notify(options.onError, new Error(`pulse rule fetch failed (${res.error ?? "no usable response"}); using cached bundle`), "onError");
       return normalizeBundle(prior.bundle, options);
     }
     if (options.rules) {
-      options.onError?.(new Error(`pulse rule fetch failed (${res.error ?? "no usable response"}); using bundled fallback`));
+      notify(options.onError, new Error(`pulse rule fetch failed (${res.error ?? "no usable response"}); using bundled fallback`), "onError");
       return normalizeBundle(options.rules, options);
     }
-    options.onError?.(new Error(`pulse rule fetch failed (${res.error ?? "no usable response"}); no cache \u2014 running with no rules`));
+    notify(options.onError, new Error(`pulse rule fetch failed (${res.error ?? "no usable response"}); no cache \u2014 running with no rules`), "onError");
     return emptyBundle();
   }
   if (options.token) {
@@ -2331,10 +2354,10 @@ async function resolveRules(options, store, ctx = {}) {
       return bundle;
     }
     if (prior?.bundle) {
-      options.onError?.(new Error(`rule fetch failed (${res.error ?? "no usable response"}); using cached bundle`));
+      notify(options.onError, new Error(`rule fetch failed (${res.error ?? "no usable response"}); using cached bundle`), "onError");
       return normalizeBundle(prior.bundle, options);
     }
-    options.onError?.(new Error(`rule fetch failed (${res.error ?? "no usable response"}); no cache \u2014 running with no rules`));
+    notify(options.onError, new Error(`rule fetch failed (${res.error ?? "no usable response"}); no cache \u2014 running with no rules`), "onError");
     return emptyBundle();
   }
   if (options.rules) {
@@ -2355,10 +2378,7 @@ function normalizeBundle(b, options = {}) {
     const report = options.onRuleRejected;
     if (typeof report === "function") {
       for (const r of rejected) {
-        try {
-          report(r);
-        } catch {
-        }
+        notify(report, r, "onRuleRejected");
       }
     } else {
       const sample = rejected.slice(0, 3).map((r) => `${r.id} (${r.reason})`).join("; ");
@@ -2400,7 +2420,7 @@ function startRefresh(tick, { refreshMs, onError } = {}) {
       failures = 0;
     } catch (err) {
       failures++;
-      onError?.(err);
+      notify(onError, err, "onError");
     }
     schedule();
   };
@@ -2432,10 +2452,124 @@ function makeRefreshHandler(tick, secret) {
   };
 }
 
+// src/protect/detections.js
+var DEFAULT_BASE_URL3 = "https://api.patchstack.com/monitor/pulse";
+var DEFAULT_FLUSH_MS = 5e3;
+var MAX_BATCH = 50;
+var MAX_QUEUE = 500;
+function ruleParameters(rule) {
+  const out = /* @__PURE__ */ new Set();
+  const walk = (conditions) => {
+    if (!Array.isArray(conditions)) return;
+    for (const condition of conditions) {
+      if (!condition || typeof condition !== "object") continue;
+      if (typeof condition.parameter === "string" && condition.parameter !== "rules") {
+        out.add(condition.parameter);
+      }
+      if (Array.isArray(condition.rules)) walk(condition.rules);
+    }
+  };
+  walk(rule?.rule_v2);
+  return [...out];
+}
+function routeOf(path) {
+  if (typeof path !== "string" || path === "") return null;
+  const cut = path.search(/[?#]/);
+  return cut === -1 ? path : path.slice(0, cut);
+}
+function createDetectionReporter(opts) {
+  const siteUuid = opts.siteUuid ?? process.env?.PATCHSTACK_SITE_UUID;
+  if (!siteUuid) {
+    return { record() {
+    }, flush() {
+    }, stop() {
+    }, dropped: () => 0 };
+  }
+  const configured = opts.baseUrl ?? process.env?.PATCHSTACK_PULSE_RULES_URL;
+  const baseUrl = typeof configured === "string" && isSafeOrigin(configured) ? configured.replace(/\/$/, "") : DEFAULT_BASE_URL3;
+  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+  const flushMs = Number.isFinite(opts.flushMs) && opts.flushMs > 0 ? opts.flushMs : DEFAULT_FLUSH_MS;
+  const maxQueue = Number.isFinite(opts.maxQueue) && opts.maxQueue > 0 ? opts.maxQueue : MAX_QUEUE;
+  let queue = [];
+  let timer = null;
+  let stopped = false;
+  let dropped = 0;
+  const flush = () => {
+    if (timer) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    if (queue.length === 0 || typeof fetchImpl !== "function") return;
+    const batch = queue.splice(0, MAX_BATCH);
+    const droppedWith = dropped;
+    dropped = 0;
+    void (async () => {
+      try {
+        const res = await fetchImpl(`${baseUrl}/detections/${encodeURIComponent(siteUuid)}`, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            Accept: "application/json",
+            "User-Agent": "@patchstack/connect",
+            // Same credential path as the rules fetch, and unauthenticated when none resolves: the
+            // server accepts the UUID, and reporting must never hinge on getting a token.
+            ...await pulseAuthHeader({ pulseAuth: opts.pulseAuth, endpoint: baseUrl }, fetchImpl)
+          },
+          body: JSON.stringify({ detections: batch, dropped: droppedWith })
+        });
+        if (res && typeof res.then === "function") res.catch(() => {
+        });
+      } catch {
+      }
+    })();
+  };
+  return {
+    /**
+     * @param {{
+     *   rule?: { id?: string, rule_v2?: unknown },
+     *   phase?: string,
+     *   mode?: string,
+     *   path?: string,
+     * }} detection
+     */
+    record(detection) {
+      if (stopped) return;
+      const ruleId = detection?.rule?.id;
+      if (ruleId === void 0 || ruleId === null || ruleId === "") return;
+      if (queue.length >= maxQueue) {
+        queue.shift();
+        dropped++;
+      }
+      queue.push({
+        rule_id: ruleId,
+        route: routeOf(detection.path),
+        parameters: ruleParameters(detection.rule),
+        phase: detection.phase ?? null,
+        // The state this detection was handled under, which is the whole point: `false` is a rule that
+        // saw traffic it would have stopped.
+        enforced: detection.mode === "block",
+        rules_etag: opts.rulesEtag ?? null,
+        detected_at: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      if (queue.length >= MAX_BATCH) {
+        flush();
+        return;
+      }
+      if (!timer) timer = setTimeout(flush, flushMs);
+    },
+    flush,
+    stop() {
+      stopped = true;
+      flush();
+    },
+    dropped: () => dropped
+  };
+}
+
 // src/protect/firewall-log.js
 var DEFAULT_API_BASE = "https://api.patchstack.com";
-var DEFAULT_FLUSH_MS = 1e3;
-var MAX_BATCH = 50;
+var DEFAULT_FLUSH_MS2 = 1e3;
+var MAX_BATCH2 = 50;
 var TOKEN_SKEW_MS2 = 6e4;
 function parseApiKey(apiKey) {
   if (typeof apiKey !== "string" || apiKey.length === 0) return null;
@@ -2480,7 +2614,7 @@ function createFirewallLogReporter(opts) {
   }
   const apiBase = (opts.apiBase ?? DEFAULT_API_BASE).replace(/\/$/, "");
   const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
-  const flushMs = Number.isFinite(opts.flushMs) ? opts.flushMs : DEFAULT_FLUSH_MS;
+  const flushMs = Number.isFinite(opts.flushMs) ? opts.flushMs : DEFAULT_FLUSH_MS2;
   const sourceHost = typeof opts.sourceHost === "string" ? opts.sourceHost : "";
   let queue = [];
   let timer = null;
@@ -2529,7 +2663,7 @@ function createFirewallLogReporter(opts) {
       timer = null;
     }
     if (queue.length === 0 || typeof fetchImpl !== "function") return;
-    const batch = queue.splice(0, MAX_BATCH);
+    const batch = queue.splice(0, MAX_BATCH2);
     void (async () => {
       const token = await fetchAccessToken();
       if (!token) return;
@@ -2576,7 +2710,7 @@ function createFirewallLogReporter(opts) {
         user_agent: event.userAgent ?? null,
         log_date: (/* @__PURE__ */ new Date()).toISOString()
       });
-      if (queue.length >= MAX_BATCH) {
+      if (queue.length >= MAX_BATCH2) {
         flush();
         return;
       }
@@ -2675,8 +2809,10 @@ async function createProtection(options = {}) {
     sourceHost: options.sourceHost,
     fetchImpl: options.fetchImpl
   }) : null;
+  let detections = null;
   const onDetect = (detection) => {
-    userOnDetect(detection);
+    notify(userOnDetect, detection, "onDetect");
+    if (detections) detections.record(detection);
     if (firewallLog && detection?.mode === "block") {
       firewallLog.record({
         rule: detection.rule,
@@ -2690,7 +2826,24 @@ async function createProtection(options = {}) {
   const store = makeStore(options);
   const bootTimeoutMs = Number(options.bootTimeoutMs) > 0 ? Number(options.bootTimeoutMs) : 5e3;
   const pulseAuth = await resolvePulseAuth(options);
+  if (options.siteUuid && !pulseAuth) {
+    const message = "Patchstack: no API credential resolved for site " + options.siteUuid + ". Rule updates may be rejected and this guard would keep running on its cached rules. Set PATCHSTACK_API_KEY (or pass { pulseAuth }) \u2014 required on runtimes without a filesystem.";
+    notify(onError, new Error(message), "onError");
+    console.warn(message);
+  }
   const bundle = await resolveRules(options, store, { timeoutMs: bootTimeoutMs, pulseAuth });
+  if (options.reportDetections === true && options.siteUuid && telemetryEnabled()) {
+    detections = createDetectionReporter({
+      siteUuid: options.siteUuid,
+      baseUrl: options.pulseRulesUrl,
+      pulseAuth,
+      // The bundle the guard is actually running, so a hit can be attributed to the rules that produced
+      // it rather than to whatever is current when the report is read.
+      rulesEtag: (await store.read())?.etag ?? null,
+      fetchImpl: options.fetchImpl,
+      flushMs: options.detectionFlushMs
+    });
+  }
   let mode = resolveMode(options, bundle);
   let requestRules;
   let responseRules;
@@ -2733,12 +2886,7 @@ async function createProtection(options = {}) {
   const recordSkip = (phase, reason, detail) => {
     const key = `${phase}:${reason}`;
     skipCounts[key] = (skipCounts[key] ?? 0) + 1;
-    if (onSkip) {
-      try {
-        onSkip({ phase, reason, detail, count: skipCounts[key] });
-      } catch {
-      }
-    }
+    notify(onSkip, { phase, reason, detail, count: skipCounts[key] }, "onSkip");
   };
   const maskFn = typeof options.maskWith === "function" ? options.maskWith : () => typeof options.maskWith === "string" ? options.maskWith : "[REDACTED]";
   const ruleMode = (rule) => rule?.enforcement === "dry-run" ? "dry-run" : mode;
@@ -2774,7 +2922,7 @@ async function createProtection(options = {}) {
       try {
         result = re.evaluate({ ...reqCtx || {}, _response: { ...meta, body: text } });
       } catch (err) {
-        onError?.(err);
+        notify(onError, err, "onError");
         continue;
       }
       if (!result.blocked) continue;
@@ -2896,7 +3044,7 @@ async function createProtection(options = {}) {
       try {
         r = screenText(text, { status: res.statusCode, headers: res.getHeaders ? res.getHeaders() : {} }, reqCtx);
       } catch (err) {
-        onError?.(err);
+        notify(onError, err, "onError");
         for (const c of chunks) origWrite(c);
         return origEnd(cb);
       }
@@ -2948,7 +3096,7 @@ async function createProtection(options = {}) {
     try {
       result = egressEngine.evaluate({ _egress: { url, host, method } });
     } catch (err) {
-      onError?.(err);
+      notify(onError, err, "onError");
       return false;
     }
     if (!result.blocked) return false;
@@ -2982,7 +3130,7 @@ async function createProtection(options = {}) {
         try {
           result = engine.evaluate(await fromFetchRequest(request));
         } catch (err) {
-          onError?.(err);
+          notify(onError, err, "onError");
           return null;
         }
         return decide("request", result, () => blockResponse(result, request), () => null, fetchRequestMeta(request));
@@ -3006,7 +3154,7 @@ async function createProtection(options = {}) {
         try {
           result = engine.evaluate(req);
         } catch (err) {
-          onError?.(err);
+          notify(onError, err, "onError");
           if (exprOptions.screenResponses) wrapNodeResponse(res, reqContextFromNode(req));
           return next();
         }
@@ -3045,7 +3193,7 @@ async function createProtection(options = {}) {
           chunks.push(chunk);
         });
         req.on("error", (err) => {
-          onError?.(err);
+          notify(onError, err, "onError");
           next();
         });
         req.on("end", () => {
@@ -3057,7 +3205,7 @@ async function createProtection(options = {}) {
             shaped = fromNodeRequest(req, rawBody);
             result = engine.evaluate(shaped);
           } catch (err) {
-            onError?.(err);
+            notify(onError, err, "onError");
             return next();
           }
           decide(
@@ -3104,7 +3252,7 @@ async function createProtection(options = {}) {
     try {
       ({ reportManifest: reporter } = await Promise.resolve().then(() => __toESM(require_ps_edge_stub(), 1)));
     } catch (err) {
-      onError?.(err);
+      notify(onError, err, "onError");
     }
   }
   const runRefreshTick = async () => {
@@ -3112,7 +3260,7 @@ async function createProtection(options = {}) {
       try {
         await reporter(cwd);
       } catch (err) {
-        onError?.(err);
+        notify(onError, err, "onError");
       }
     }
     const next = await resolveRules(options, store, { timeoutMs: options.refreshTimeoutMs, pulseAuth });
@@ -3128,9 +3276,13 @@ async function createProtection(options = {}) {
     protection.stopRefresh = () => {
       loop.stop();
       firewallLog?.stop();
+      detections?.stop();
     };
   } else if (firewallLog) {
-    protection.stopRefresh = () => firewallLog.stop();
+    protection.stopRefresh = () => {
+      firewallLog.stop();
+      detections?.stop();
+    };
   }
   return protection;
 }