@patchstack/connect 0.3.20 → 0.3.21

package/dist/protect.d.ts

@@ -23,7 +23,12 @@ 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;
 }
 
@@ -46,6 +51,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

@@ -1665,9 +1665,189 @@ 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) {
+  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: {} };
+}
+
+// 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";
@@ -1743,7 +1923,8 @@ 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 requestRules;
   let responseRules;
   let egressRules;
@@ -2059,30 +2240,35 @@ 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-XBOGN446.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);
+    applyBundle(await resolveRules(options, store));
+  };
+  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;
 }
@@ -2324,115 +2510,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 };