@patchstack/connect 0.3.20 → 0.3.22

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";
@@ -23,12 +25,21 @@ export interface Protection {
   node(options?: { maxBodyBytes?: number; screenResponses?: boolean }): (req: unknown, res: unknown, next: () => void) => void;
   /** Present when `egress: true` — restores the original global fetch. */
   uninstallEgress?: () => void;
-  /** Present when `refreshMs > 0` — stops the live rule-refresh interval. */
+  /** Present with a live source — re-fetch + hot-swap the rules once (used by the loop + push). */
+  refresh?: () => Promise<void>;
+  /** Present with a live source — a fetch handler that runs `refresh()` when the request carries
+   *  the configured refresh secret (a push/zero-day trigger). No secret set → the handler 404s. */
+  refreshHandler?: () => (request: Request) => Promise<Response>;
+  /** Present when `refreshMs > 0` — stops the live rule-refresh loop. */
   stopRefresh?: () => void;
 }
 
 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;
@@ -46,6 +57,12 @@ export interface CreateProtectionOptions {
    * meaningful with a live source (`siteUuid`/`token`).
    */
   refreshMs?: number;
+  /**
+   * Shared secret gating the push refresh endpoint (`refreshHandler()`): the platform/SaaS hits the
+   * endpoint with this secret to trigger an immediate refresh. Falls back to `PATCHSTACK_REFRESH_SECRET`.
+   * Unset → the endpoint 404s (never an open refresh trigger).
+   */
+  refreshSecret?: string;
   /**
    * During a refresh, also re-post the dependency manifest (the runtime counterpart to `scan`) so a
    * dependency added after boot — e.g. via `npm install <pkg>`, which fires no npm lifecycle hook —

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;
@@ -1665,9 +1671,191 @@ function renderBlockPage({ url = "", code = "patchstack" } = {}) {
 </html>`;
 }
 
-// src/protect/runtime.js
+// src/protect/rules/store.js
 import { readFileSync, writeFileSync, mkdirSync } from "fs";
 import { join } from "path";
+function makeStore(options = {}) {
+  let mem = null;
+  const durable = durableTier(options);
+  return {
+    async read() {
+      if (mem) return mem;
+      const env = await durable.read();
+      if (env) mem = env;
+      return env;
+    },
+    async write(env) {
+      if (env) mem = env;
+      await durable.write(env);
+    }
+  };
+}
+function durableTier(options) {
+  const adapter = options.ruleCache;
+  if (adapter && typeof adapter.read === "function" && typeof adapter.write === "function") {
+    return {
+      read: async () => {
+        try {
+          return toEnvelope(await adapter.read());
+        } catch {
+          return null;
+        }
+      },
+      write: async (env) => {
+        try {
+          await adapter.write(env);
+        } catch {
+        }
+      }
+    };
+  }
+  const dir = options.cacheDir;
+  return {
+    read: async () => cacheRead(dir),
+    write: async (env) => cacheWrite(dir, env)
+  };
+}
+function cachePath(dir) {
+  return join(dir, "patchstack-rules.json");
+}
+function cacheWrite(dir, env) {
+  if (!dir) return;
+  try {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(cachePath(dir), JSON.stringify(env));
+  } catch {
+  }
+}
+function cacheRead(dir) {
+  if (!dir) return null;
+  try {
+    return toEnvelope(JSON.parse(readFileSync(cachePath(dir), "utf8")));
+  } catch {
+    return null;
+  }
+}
+function toEnvelope(value) {
+  if (!value || typeof value !== "object") return null;
+  if (value.bundle && typeof value.bundle === "object") {
+    return { bundle: value.bundle, etag: value.etag ?? null };
+  }
+  if (Array.isArray(value.firewall) || Array.isArray(value.whitelists)) {
+    return { bundle: value, etag: null };
+  }
+  return null;
+}
+
+// src/protect/rules/source.js
+async function resolveRules(options, store) {
+  if (options.siteUuid) {
+    const prior = await store.read();
+    const client = new PulseRuleClient({ siteUuid: options.siteUuid, baseUrl: options.pulseRulesUrl, etag: prior?.etag });
+    const res = await client.getRules();
+    if (res.success && res.notModified && prior?.bundle) return normalizeBundle(prior.bundle);
+    if (res.success && !res.notModified) {
+      const bundle = normalizeBundle(res);
+      await store.write({ bundle, etag: res.etag ?? null });
+      return bundle;
+    }
+    if (prior?.bundle) {
+      options.onError?.(new Error(`pulse rule fetch failed (${res.error ?? "no usable response"}); using cached bundle`));
+      return normalizeBundle(prior.bundle);
+    }
+    if (options.rules) {
+      options.onError?.(new Error(`pulse rule fetch failed (${res.error ?? "no usable response"}); using bundled fallback`));
+      return normalizeBundle(options.rules);
+    }
+    options.onError?.(new Error(`pulse rule fetch failed (${res.error ?? "no usable response"}); no cache \u2014 running with no rules`));
+    return emptyBundle();
+  }
+  if (options.token) {
+    const prior = await store.read();
+    const client = new PatchstackRuleClient({ token: options.token, baseUrl: options.baseUrl, etag: prior?.etag });
+    const res = await client.getRules();
+    if (res.success && res.notModified && prior?.bundle) return normalizeBundle(prior.bundle);
+    if (res.success && !res.notModified) {
+      const bundle = normalizeBundle(res);
+      await store.write({ bundle, etag: res.etag ?? null });
+      return bundle;
+    }
+    if (prior?.bundle) {
+      options.onError?.(new Error(`rule fetch failed (${res.error ?? "no usable response"}); using cached bundle`));
+      return normalizeBundle(prior.bundle);
+    }
+    options.onError?.(new Error(`rule fetch failed (${res.error ?? "no usable response"}); no cache \u2014 running with no rules`));
+    return emptyBundle();
+  }
+  if (options.rules) {
+    return normalizeBundle(options.rules);
+  }
+  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 ?? {},
+    ...enforcement === "block" || enforcement === "dry-run" ? { enforcement } : {}
+  };
+}
+function emptyBundle() {
+  return { firewall: [], whitelists: [], whitelist_keys: {} };
+}
+
+// src/protect/rules/refresh.js
+var JITTER_FRACTION3 = 0.1;
+var MAX_BACKOFF_MULTIPLIER = 8;
+function startRefresh(tick, { refreshMs, onError } = {}) {
+  let stopped = false;
+  let failures = 0;
+  let timer = null;
+  const schedule = () => {
+    if (stopped) return;
+    const backoff = Math.min(2 ** failures, MAX_BACKOFF_MULTIPLIER);
+    const jitter = 1 - Math.random() * JITTER_FRACTION3;
+    const delay = refreshMs * backoff * jitter;
+    timer = setTimeout(run, delay);
+    timer?.unref?.();
+  };
+  const run = async () => {
+    if (stopped) return;
+    try {
+      await tick();
+      failures = 0;
+    } catch (err) {
+      failures++;
+      onError?.(err);
+    }
+    schedule();
+  };
+  schedule();
+  return {
+    stop() {
+      stopped = true;
+      if (timer) clearTimeout(timer);
+    }
+  };
+}
+function makeRefreshHandler(tick, secret) {
+  return async (request) => {
+    if (!secret) return new Response("not found", { status: 404 });
+    let provided = null;
+    try {
+      provided = request?.headers?.get?.("x-patchstack-refresh") ?? new URL(request.url).searchParams.get("token");
+    } catch {
+      provided = null;
+    }
+    if (provided !== secret) return new Response("forbidden", { status: 403 });
+    let refreshed = true;
+    try {
+      await tick();
+    } catch {
+      refreshed = false;
+    }
+    return new Response(JSON.stringify({ refreshed }), { status: 200, headers: { "content-type": "application/json" } });
+  };
+}
 
 // src/protect/supabase-guard.js
 var GUARD_PATH = "/_patchstack/guard";
@@ -1740,10 +1928,11 @@ 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 bundle = await resolveRules(options);
+  const store = makeStore(options);
+  const bundle = await resolveRules(options, store);
+  let mode = resolveMode(options, bundle);
   let requestRules;
   let responseRules;
   let egressRules;
@@ -1938,7 +2127,9 @@ async function createProtection(options = {}) {
     return mode === "block";
   };
   const protection = {
-    mode,
+    get mode() {
+      return mode;
+    },
     get rules() {
       return { request: requestRules, response: responseRules, egress: egressRules };
     },
@@ -2059,33 +2250,48 @@ async function createProtection(options = {}) {
       allowHosts: options.allowHosts
     });
   }
-  if (options.refreshMs > 0 && (options.siteUuid || options.token)) {
-    const cwd = options.cwd ?? (typeof process !== "undefined" ? process.cwd() : void 0);
-    let reportManifest = null;
-    if (options.siteUuid && options.reportManifest !== false && cwd) {
+  const cwd = options.cwd ?? (typeof process !== "undefined" ? process.cwd() : void 0);
+  const live = Boolean(options.siteUuid || options.token);
+  const refreshSecret = options.refreshSecret ?? (typeof process !== "undefined" ? process.env.PATCHSTACK_REFRESH_SECRET : void 0);
+  const refreshable = live && (options.refreshMs > 0 || Boolean(refreshSecret));
+  let reporter = null;
+  if (refreshable && options.siteUuid && options.reportManifest !== false && cwd) {
+    try {
+      ({ reportManifest: reporter } = await import("./refresh-manifest-OW7WT5A6.js"));
+    } catch (err) {
+      onError?.(err);
+    }
+  }
+  const runRefreshTick = async () => {
+    if (reporter) {
       try {
-        ({ reportManifest } = await import("./refresh-manifest-XBOGN446.js"));
+        await reporter(cwd);
       } catch (err) {
         onError?.(err);
       }
     }
-    const timer = setInterval(() => {
-      (async () => {
-        if (reportManifest) {
-          try {
-            await reportManifest(cwd);
-          } catch (err) {
-            onError?.(err);
-          }
-        }
-        applyBundle(await resolveRules(options));
-      })().catch((err) => onError?.(err));
-    }, options.refreshMs);
-    timer.unref?.();
-    protection.stopRefresh = () => clearInterval(timer);
+    const next = await resolveRules(options, store);
+    mode = resolveMode(options, next);
+    applyBundle(next);
+  };
+  if (live) {
+    protection.refresh = () => runRefreshTick();
+    protection.refreshHandler = () => makeRefreshHandler(runRefreshTick, refreshSecret);
+  }
+  if (options.refreshMs > 0 && live) {
+    const loop = startRefresh(runRefreshTick, { refreshMs: options.refreshMs, onError });
+    protection.stopRefresh = loop.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 byPhase(rules, phase) {
   return (rules ?? []).filter((r) => (r.phase ?? "request") === phase);
 }
@@ -2324,115 +2530,6 @@ function leakResponse() {
     headers: { "content-type": "application/json" }
   });
 }
-async function resolveRules(options) {
-  const cache = makeCache(options);
-  if (options.siteUuid) {
-    const prior = await cache.read();
-    const client = new PulseRuleClient({ siteUuid: options.siteUuid, baseUrl: options.pulseRulesUrl, etag: prior?.etag });
-    const res = await client.getRules();
-    if (res.success && res.notModified && prior?.bundle) return normalizeBundle(prior.bundle);
-    if (res.success && !res.notModified) {
-      const bundle = normalizeBundle(res);
-      await cache.write({ bundle, etag: res.etag ?? null });
-      return bundle;
-    }
-    if (prior?.bundle) {
-      options.onError?.(new Error(`pulse rule fetch failed (${res.error ?? "no usable response"}); using cached bundle`));
-      return normalizeBundle(prior.bundle);
-    }
-    if (options.rules) {
-      options.onError?.(new Error(`pulse rule fetch failed (${res.error ?? "no usable response"}); using bundled fallback`));
-      return normalizeBundle(options.rules);
-    }
-    options.onError?.(new Error(`pulse rule fetch failed (${res.error ?? "no usable response"}); no cache \u2014 running with no rules`));
-    return emptyBundle();
-  }
-  if (options.token) {
-    const prior = await cache.read();
-    const client = new PatchstackRuleClient({ token: options.token, baseUrl: options.baseUrl, etag: prior?.etag });
-    const res = await client.getRules();
-    if (res.success && res.notModified && prior?.bundle) return normalizeBundle(prior.bundle);
-    if (res.success && !res.notModified) {
-      const bundle = normalizeBundle(res);
-      await cache.write({ bundle, etag: res.etag ?? null });
-      return bundle;
-    }
-    if (prior?.bundle) {
-      options.onError?.(new Error(`rule fetch failed (${res.error ?? "no usable response"}); using cached bundle`));
-      return normalizeBundle(prior.bundle);
-    }
-    options.onError?.(new Error(`rule fetch failed (${res.error ?? "no usable response"}); no cache \u2014 running with no rules`));
-    return emptyBundle();
-  }
-  if (options.rules) {
-    return normalizeBundle(options.rules);
-  }
-  return emptyBundle();
-}
-function normalizeBundle(b) {
-  return {
-    firewall: Array.isArray(b.firewall) ? b.firewall : [],
-    whitelists: Array.isArray(b.whitelists) ? b.whitelists : [],
-    whitelist_keys: b.whitelist_keys ?? {}
-  };
-}
-function emptyBundle() {
-  return { firewall: [], whitelists: [], whitelist_keys: {} };
-}
-function makeCache(options) {
-  const adapter = options.ruleCache;
-  if (adapter && typeof adapter.read === "function" && typeof adapter.write === "function") {
-    return {
-      read: async () => {
-        try {
-          return toEnvelope(await adapter.read());
-        } catch {
-          return null;
-        }
-      },
-      write: async (env) => {
-        try {
-          await adapter.write(env);
-        } catch {
-        }
-      }
-    };
-  }
-  const dir = options.cacheDir;
-  return {
-    read: async () => cacheRead(dir),
-    write: async (env) => cacheWrite(dir, env)
-  };
-}
-function cachePath(dir) {
-  return join(dir, "patchstack-rules.json");
-}
-function cacheWrite(dir, env) {
-  if (!dir) return;
-  try {
-    mkdirSync(dir, { recursive: true });
-    writeFileSync(cachePath(dir), JSON.stringify(env));
-  } catch {
-  }
-}
-function cacheRead(dir) {
-  if (!dir) return null;
-  try {
-    return toEnvelope(JSON.parse(readFileSync(cachePath(dir), "utf8")));
-  } catch {
-    return null;
-  }
-}
-function toEnvelope(value) {
-  if (!value || typeof value !== "object") return null;
-  if (value.bundle && typeof value.bundle === "object") {
-    return { bundle: value.bundle, etag: value.etag ?? null };
-  }
-  if (Array.isArray(value.firewall) || Array.isArray(value.whitelists)) {
-    return { bundle: value, etag: null };
-  }
-  return null;
-}
 var BLOCK_MESSAGE = "This request has been blocked by Patchstack.";
 function blockBody(result) {
   return { error: BLOCK_MESSAGE, message: BLOCK_MESSAGE, rule: result?.rule?.id };