@patchstack/connect 0.3.21 → 0.3.23

package/dist/protect.d.ts

@@ -5,6 +5,8 @@ export interface RuleBundle {
   firewall: unknown[];
   whitelists: unknown[];
   whitelist_keys: Record<string, unknown>;
+  /** From the Pulse rules API when present (`block` = enforce, `dry-run` = detect only). */
+  enforcement?: "block" | "dry-run";
 }
 
 export type Phase = "request" | "response" | "egress";
@@ -33,7 +35,11 @@ export interface Protection {
 }
 
 export interface CreateProtectionOptions {
-  /** Default "dry-run". The scaffolded guard sets "block". */
+  /**
+   * Fallback when the Pulse rules API does not send `enforcement`.
+   * Overridden by `PATCHSTACK_MODE` when set, otherwise by API `enforcement`.
+   * Default "dry-run". Scaffolded guards pass "block" when env is unset.
+   */
   mode?: "block" | "dry-run";
   /** Explicit rule bundle (used as the token-less fallback). */
   rules?: unknown;
@@ -42,8 +48,23 @@ export interface CreateProtectionOptions {
   baseUrl?: string;
   /** Pulse site UUID — pull live per-site rules from the Pulse rules API (cached). */
   siteUuid?: string;
+  /**
+   * WP-format site API key (`{secret}-{oauth.id}`) for authenticated block logs
+   * via connector `POST /api/logs/log`. Falls back to `PATCHSTACK_API_KEY`, then
+   * `.patchstackrc.json` `apiKey`. Never put this in the public widget.
+   */
+  apiKey?: string;
   /** Override the Pulse rules API base URL. */
   pulseRulesUrl?: string;
+  /**
+   * When false, skip posting block events to connector `/api/logs/log`.
+   * Also disabled when `PATCHSTACK_TELEMETRY=off` or when no apiKey is available.
+   */
+  reportFirewallLog?: boolean;
+  /** Optional Source-Host header for connector hostname checks. */
+  sourceHost?: string;
+  /** Optional fetch override (tests). */
+  fetchImpl?: typeof fetch;
   /**
    * Re-fetch and hot-swap the live rules every N ms. For long-lived runtimes that aren't restarted
    * on change (an AI builder's sandbox/preview) so a rule that becomes relevant after boot still
@@ -98,8 +119,12 @@ export interface CreateProtectionOptions {
     phase?: Phase;
     mode: string;
     category?: string;
-    rule?: { id?: string; category?: string };
+    rule?: { id?: string | number; category?: string };
     message?: string;
+    method?: string | null;
+    path?: string | null;
+    ip?: string | null;
+    userAgent?: string | null;
   }) => void;
 }
 

package/dist/protect.js

@@ -1032,7 +1032,8 @@ var PulseRuleClient = class {
         etag: response.headers?.get?.("etag") ?? null,
         firewall: data.firewall,
         whitelists: Array.isArray(data.whitelists) ? data.whitelists : [],
-        whitelist_keys: data.whitelist_keys ?? {}
+        whitelist_keys: data.whitelist_keys ?? {},
+        ...enforcementField(data)
       };
       this.#cache = result;
       this.#etag = result.etag;
@@ -1058,6 +1059,11 @@ var PulseRuleClient = class {
     this.#etag = null;
   }
 };
+function enforcementField(data) {
+  if (!data || typeof data !== "object") return {};
+  const v = data.enforcement ?? data.mode;
+  return v === "block" || v === "dry-run" ? { enforcement: v } : {};
+}
 
 // src/protect/engine/fetch.js
 var MAX_BODY_BYTES = 1024 * 1024;
@@ -1785,10 +1791,12 @@ async function resolveRules(options, store) {
   return emptyBundle();
 }
 function normalizeBundle(b) {
+  const enforcement = b?.enforcement ?? b?.mode;
   return {
     firewall: Array.isArray(b.firewall) ? b.firewall : [],
     whitelists: Array.isArray(b.whitelists) ? b.whitelists : [],
-    whitelist_keys: b.whitelist_keys ?? {}
+    whitelist_keys: b.whitelist_keys ?? {},
+    ...enforcement === "block" || enforcement === "dry-run" ? { enforcement } : {}
   };
 }
 function emptyBundle() {
@@ -1849,6 +1857,169 @@ function makeRefreshHandler(tick, secret) {
   };
 }
 
+// src/protect/firewall-log.js
+var DEFAULT_API_BASE = "https://api.patchstack.com";
+var DEFAULT_FLUSH_MS = 1e3;
+var MAX_BATCH = 50;
+var TOKEN_SKEW_MS = 6e4;
+function parseApiKey(apiKey) {
+  if (typeof apiKey !== "string" || apiKey.length === 0) return null;
+  const idx = apiKey.lastIndexOf("-");
+  if (idx <= 0 || idx === apiKey.length - 1) return null;
+  const clientSecret = apiKey.slice(0, idx);
+  const clientId = apiKey.slice(idx + 1);
+  if (!/^\d+$/.test(clientId) || clientSecret.length === 0) return null;
+  return { clientId, clientSecret };
+}
+function resolveApiBase(pulseOrManifestUrl) {
+  const fromEnv = typeof process !== "undefined" ? process.env?.PATCHSTACK_API_BASE : void 0;
+  if (typeof fromEnv === "string" && fromEnv.length > 0) {
+    return fromEnv.replace(/\/$/, "");
+  }
+  if (typeof pulseOrManifestUrl === "string" && pulseOrManifestUrl.length > 0) {
+    try {
+      return new URL(pulseOrManifestUrl).origin;
+    } catch {
+    }
+  }
+  const endpoint = typeof process !== "undefined" ? process.env?.PATCHSTACK_ENDPOINT : void 0;
+  if (typeof endpoint === "string" && endpoint.length > 0) {
+    try {
+      return new URL(endpoint).origin;
+    } catch {
+    }
+  }
+  return DEFAULT_API_BASE;
+}
+function createFirewallLogReporter(opts) {
+  const creds = parseApiKey(opts.apiKey);
+  if (!creds) {
+    return { record() {
+    }, flush() {
+    }, stop() {
+    } };
+  }
+  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 sourceHost = typeof opts.sourceHost === "string" ? opts.sourceHost : "";
+  let queue = [];
+  let timer = null;
+  let stopped = false;
+  let cachedToken = null;
+  let tokenInflight = null;
+  const fetchAccessToken = async () => {
+    if (cachedToken && Date.now() < cachedToken.expiresAt - TOKEN_SKEW_MS) {
+      return cachedToken.token;
+    }
+    if (tokenInflight) return tokenInflight;
+    tokenInflight = (async () => {
+      try {
+        const res = await fetchImpl(`${apiBase}/oauth/token`, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            Accept: "application/json",
+            "User-Agent": "@patchstack/connect"
+          },
+          body: JSON.stringify({
+            grant_type: "client_credentials",
+            client_id: creds.clientId,
+            client_secret: creds.clientSecret
+          })
+        });
+        if (!res || !res.ok) return null;
+        const body = await res.json();
+        const token = body?.access_token;
+        if (typeof token !== "string" || token.length === 0) return null;
+        const expiresIn = Number(body?.expires_in);
+        const ttlMs = Number.isFinite(expiresIn) && expiresIn > 0 ? expiresIn * 1e3 : 36e5;
+        cachedToken = { token, expiresAt: Date.now() + ttlMs };
+        return token;
+      } catch {
+        return null;
+      } finally {
+        tokenInflight = null;
+      }
+    })();
+    return tokenInflight;
+  };
+  const flush = () => {
+    if (timer) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    if (queue.length === 0 || typeof fetchImpl !== "function") return;
+    const batch = queue.splice(0, MAX_BATCH);
+    void (async () => {
+      const token = await fetchAccessToken();
+      if (!token) return;
+      const body = new URLSearchParams();
+      body.set("type", "firewall");
+      body.set("logs", JSON.stringify(batch));
+      try {
+        const p = fetchImpl(`${apiBase}/api/logs/log`, {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${token}`,
+            Accept: "application/json",
+            "Content-Type": "application/x-www-form-urlencoded",
+            "User-Agent": "@patchstack/connect",
+            ...sourceHost ? { "Source-Host": sourceHost } : {}
+          },
+          body
+        });
+        if (p && typeof p.then === "function") p.catch(() => {
+        });
+      } catch {
+      }
+    })();
+  };
+  return {
+    /**
+     * @param {{
+     *   rule?: { id?: string | number },
+     *   method?: string | null,
+     *   path?: string | null,
+     *   ip?: string | null,
+     *   userAgent?: string | null,
+     * }} event
+     */
+    record(event) {
+      if (stopped) return;
+      const fid = event?.rule?.id;
+      if (fid === void 0 || fid === null || fid === "") return;
+      queue.push({
+        fid,
+        method: event.method ?? null,
+        request_uri: event.path ?? null,
+        ip: event.ip ?? null,
+        user_agent: event.userAgent ?? null,
+        log_date: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      if (queue.length >= MAX_BATCH) {
+        flush();
+        return;
+      }
+      if (!timer) timer = setTimeout(flush, flushMs);
+    },
+    flush,
+    stop() {
+      stopped = true;
+      flush();
+    }
+  };
+}
+function telemetryEnabled() {
+  const v = typeof process !== "undefined" ? process.env?.PATCHSTACK_TELEMETRY : void 0;
+  if (v === void 0 || v === "") return true;
+  return !/^(0|false|off|no)$/i.test(String(v));
+}
+
+// src/protect/runtime.js
+import { readFileSync as readFileSync2 } from "fs";
+import { join as join2 } from "path";
+
 // src/protect/supabase-guard.js
 var GUARD_PATH = "/_patchstack/guard";
 var HOP_BY_HOP = /* @__PURE__ */ new Set(["content-encoding", "content-length", "transfer-encoding", "connection"]);
@@ -1920,11 +2091,30 @@ function createServerFnGuard({ protection }) {
   };
 }
 async function createProtection(options = {}) {
-  const mode = options.mode === "block" ? "block" : "dry-run";
   const onError = options.onError;
-  const onDetect = options.onDetect ?? defaultOnDetect;
+  const userOnDetect = options.onDetect ?? defaultOnDetect;
+  const apiKey = resolveApiKey(options);
+  const firewallLog = apiKey && telemetryEnabled() && options.reportFirewallLog !== false ? createFirewallLogReporter({
+    apiKey,
+    apiBase: resolveApiBase(options.pulseRulesUrl ?? options.baseUrl),
+    sourceHost: options.sourceHost,
+    fetchImpl: options.fetchImpl
+  }) : null;
+  const onDetect = (detection) => {
+    userOnDetect(detection);
+    if (firewallLog && detection?.mode === "block") {
+      firewallLog.record({
+        rule: detection.rule,
+        method: detection.method,
+        path: detection.path,
+        ip: detection.ip,
+        userAgent: detection.userAgent
+      });
+    }
+  };
   const store = makeStore(options);
   const bundle = await resolveRules(options, store);
+  let mode = resolveMode(options, bundle);
   let requestRules;
   let responseRules;
   let egressRules;
@@ -1953,9 +2143,19 @@ async function createProtection(options = {}) {
   };
   applyBundle(bundle);
   const maskFn = typeof options.maskWith === "function" ? options.maskWith : () => typeof options.maskWith === "string" ? options.maskWith : "[REDACTED]";
-  const decide = (phase, result, block, allow2) => {
+  const decide = (phase, result, block, allow2, ctx = {}) => {
     if (!result || !result.blocked) return allow2();
-    onDetect({ phase, mode, category: result.rule?.category, rule: result.rule, message: result.message });
+    onDetect({
+      phase,
+      mode,
+      category: result.rule?.category,
+      rule: result.rule,
+      message: result.message,
+      method: ctx.method,
+      path: ctx.path,
+      ip: ctx.ip,
+      userAgent: ctx.userAgent
+    });
     return mode === "block" ? block() : allow2();
   };
   const isTextCT = (ct) => {
@@ -2119,7 +2319,9 @@ async function createProtection(options = {}) {
     return mode === "block";
   };
   const protection = {
-    mode,
+    get mode() {
+      return mode;
+    },
     get rules() {
       return { request: requestRules, response: responseRules, egress: egressRules };
     },
@@ -2136,7 +2338,7 @@ async function createProtection(options = {}) {
           onError?.(err);
           return null;
         }
-        return decide("request", result, () => blockResponse(result, request), () => null);
+        return decide("request", result, () => blockResponse(result, request), () => null, fetchRequestMeta(request));
       };
     },
     // Wrap a fetch handler: screens the request, then the response (redact/block).
@@ -2174,7 +2376,8 @@ async function createProtection(options = {}) {
           () => {
             if (exprOptions.screenResponses) wrapNodeResponse(res);
             next();
-          }
+          },
+          nodeRequestMeta(req)
         );
       };
     },
@@ -2226,7 +2429,8 @@ async function createProtection(options = {}) {
               if (req.body === void 0) req.body = shaped.body;
               if (nodeOptions.screenResponses) wrapNodeResponse(res);
               next();
-            }
+            },
+            nodeRequestMeta(req)
           );
         });
       };
@@ -2247,7 +2451,7 @@ async function createProtection(options = {}) {
   let reporter = null;
   if (refreshable && options.siteUuid && options.reportManifest !== false && cwd) {
     try {
-      ({ reportManifest: reporter } = await import("./refresh-manifest-XBOGN446.js"));
+      ({ reportManifest: reporter } = await import("./refresh-manifest-ZIFRZF25.js"));
     } catch (err) {
       onError?.(err);
     }
@@ -2260,7 +2464,9 @@ async function createProtection(options = {}) {
         onError?.(err);
       }
     }
-    applyBundle(await resolveRules(options, store));
+    const next = await resolveRules(options, store);
+    mode = resolveMode(options, next);
+    applyBundle(next);
   };
   if (live) {
     protection.refresh = () => runRefreshTick();
@@ -2268,10 +2474,39 @@ async function createProtection(options = {}) {
   }
   if (options.refreshMs > 0 && live) {
     const loop = startRefresh(runRefreshTick, { refreshMs: options.refreshMs, onError });
-    protection.stopRefresh = loop.stop;
+    protection.stopRefresh = () => {
+      loop.stop();
+      firewallLog?.stop();
+    };
+  } else if (firewallLog) {
+    protection.stopRefresh = () => firewallLog.stop();
   }
   return protection;
 }
+function resolveMode(options, bundle) {
+  const env = typeof process !== "undefined" ? process.env?.PATCHSTACK_MODE : void 0;
+  if (env === "block" || env === "dry-run") return env;
+  if (bundle?.enforcement === "block" || bundle?.enforcement === "dry-run") return bundle.enforcement;
+  if (options?.mode === "block") return "block";
+  if (options?.mode === "dry-run") return "dry-run";
+  return "dry-run";
+}
+function resolveApiKey(options) {
+  if (typeof options?.apiKey === "string" && options.apiKey.length > 0) return options.apiKey;
+  if (typeof process !== "undefined") {
+    const fromEnv = process.env?.PATCHSTACK_API_KEY;
+    if (typeof fromEnv === "string" && fromEnv.length > 0) return fromEnv;
+  }
+  try {
+    if (typeof process === "undefined" || typeof process.cwd !== "function") return void 0;
+    const cwd = options?.cwd ?? process.cwd();
+    const raw = readFileSync2(join2(cwd, ".patchstackrc.json"), "utf8");
+    const key = JSON.parse(raw)?.apiKey;
+    if (typeof key === "string" && key.length > 0) return key;
+  } catch {
+  }
+  return void 0;
+}
 function byPhase(rules, phase) {
   return (rules ?? []).filter((r) => (r.phase ?? "request") === phase);
 }
@@ -2535,6 +2770,33 @@ function defaultOnDetect({ phase, mode, category, rule, message }) {
   const tag = mode === "block" ? "BLOCK" : "DETECT (dry-run)";
   console.warn(`[patchstack] ${tag} phase=${phase ?? "request"} category=${category ?? "?"} rule=${rule?.id ?? "?"} ${message ?? ""}`.trim());
 }
+function fetchRequestMeta(request) {
+  if (!request) return {};
+  let path = null;
+  try {
+    path = new URL(request.url).pathname;
+  } catch {
+    path = typeof request.url === "string" ? request.url : null;
+  }
+  return {
+    method: request.method ?? null,
+    path,
+    ip: request.headers?.get?.("x-forwarded-for") ?? null,
+    userAgent: request.headers?.get?.("user-agent") ?? null
+  };
+}
+function nodeRequestMeta(req) {
+  if (!req) return {};
+  const headers = req.headers ?? {};
+  const ua = headers["user-agent"] ?? headers["User-Agent"];
+  const fwd = headers["x-forwarded-for"] ?? headers["X-Forwarded-For"];
+  return {
+    method: req.method ?? null,
+    path: req.originalUrl || req.url || null,
+    ip: req.ip ?? (typeof fwd === "string" ? fwd : null),
+    userAgent: typeof ua === "string" ? ua : Array.isArray(ua) ? ua[0] : null
+  };
+}
 export {
   GUARD_PATH,
   PulseRuleClient,