@patchstack/connect 0.4.2 → 0.5.1

package/dist/protect/templates/generic-guard.cjs

@@ -1,7 +1,17 @@
 // Patchstack runtime protection — GENERIC guard (CommonJS). Managed by `patchstack-connect protect`.
 // Wire whichever helper fits your server into your request path, then run `protect --check`.
 const { createProtection } = require("@patchstack/connect/protect");
-const fallbackRules = require("./rules.json");
+// The fallback bundle is optional at RUNTIME. This file is imported on the app's own module path, so a
+// throw here is the app failing to boot rather than protection failing open — and a rules file can be
+// absent for ordinary reasons: a bundler that copied no JSON, a partial deploy, a half-written edit.
+// Without it the guard holds no local bundle, and says so. Its other two rule sources are untouched:
+// live rules for a configured site, and the engine's own compiled response/egress policy.
+let fallbackRules;
+try {
+  fallbackRules = require("./rules.json");
+} catch (err) {
+  console.warn("[patchstack] ./rules.json was not read (" + err.message + "); the guard holds no local rules");
+}
 
 const PS_SITE_UUID = "__PATCHSTACK_SITE_UUID__";
 let protection;
@@ -34,9 +44,32 @@ async function buildProtection() {
   );
 }
 
+
+// A protection that could not be built must not become an app that cannot answer. Each seam below asks
+// for one, steps aside when it cannot have one, and leaves the app to carry on unscreened.
+// `getProtection` clears its slot on a failed build, so the next request builds again — one bad start
+// does not switch protection off for the life of the process.
+//
+// Only the FIRST failure is reported: enough to know the guard is not screening, without a line per
+// request. A later failure is not reported, including one with a different cause.
+let psUnavailable = false;
+function psStepAside(err) {
+  if (!psUnavailable) {
+    psUnavailable = true;
+    console.warn(
+      "[patchstack] protection is unavailable; traffic may pass through unscreened until a later attempt succeeds. Reported once per process. Cause: " +
+        (err instanceof Error ? err.message : String(err)),
+    );
+  }
+
+  return null;
+}
 function protectFetch(handler) {
   return async (request, ...rest) => {
-    const active = await getProtection();
+    const active = await getProtection().catch(psStepAside);
+    // The handler, and nothing around it: an exception the app throws is the app's, not a protection
+    // failure, and must not be read as one or answered twice.
+    if (!active) return handler(request, ...rest);
     const blocked = await active.fetchGuard()(request);
     if (blocked) return blocked;
     // Response rules can be scoped to a route or a method, and the engine can only apply that scope if it is
@@ -49,9 +82,29 @@ function protectFetch(handler) {
 // Node / Connect: app.use(patchstackMiddleware) — before any body parser. This guard reads the request
 // stream itself and exposes what it read as req.body, so a parser is not also needed.
 function patchstackMiddleware(req, res, next) {
-  getProtection()
-    .then((active) => active.node()(req, res, next))
-    .catch(() => next()); // fail open
+  // `next` is wrapped so it can run at most once, whatever happens. That is what makes the two
+  // handlers below safe: a rejection handler passed to `then` sees only a failed build, the trailing
+  // one sees whatever the guard or the app's own chain threw and reports it — and neither can pass a
+  // request on that was already passed on, nor leave one that never was.
+  let passedOn = false;
+  const carryOn = (err) => {
+    if (passedOn) return;
+    passedOn = true;
+    next(err);
+  };
+  getProtection().then(
+    (active) => active.node()(req, res, carryOn),
+    (err) => {
+      psStepAside(err);
+      carryOn();
+    },
+  ).catch((err) => {
+    // Not a failed build: the guard, or the app's own chain, threw after this point. Reported, and the
+    // request is carried on only if it never was — an error here must not take the process down and
+    // must not answer twice.
+    psStepAside(err);
+    carryOn();
+  });
 }
 
 module.exports = { getProtection, protectFetch, patchstackMiddleware };

package/dist/protect/templates/generic-guard.js

@@ -3,7 +3,17 @@
 import { readFileSync } from "node:fs";
 import { createProtection } from "@patchstack/connect/protect";
 
-const fallbackRules = JSON.parse(readFileSync(new URL("./rules.json", import.meta.url), "utf8"));
+// The fallback bundle is optional at RUNTIME. This file is imported on the app's own module path, so a
+// throw here is the app failing to boot rather than protection failing open — and a rules file can be
+// absent for ordinary reasons: a bundler that copied no JSON, a partial deploy, a half-written edit.
+// Without it the guard holds no local bundle, and says so. Its other two rule sources are untouched:
+// live rules for a configured site, and the engine's own compiled response/egress policy.
+let fallbackRules;
+try {
+  fallbackRules = JSON.parse(readFileSync(new URL("./rules.json", import.meta.url), "utf8"));
+} catch (err) {
+  console.warn("[patchstack] ./rules.json was not read (" + err.message + "); the guard holds no local rules");
+}
 const PS_SITE_UUID = "__PATCHSTACK_SITE_UUID__";
 let protection;
 
@@ -35,10 +45,33 @@ async function buildProtection() {
   );
 }
 
+
+// A protection that could not be built must not become an app that cannot answer. Each seam below asks
+// for one, steps aside when it cannot have one, and leaves the app to carry on unscreened.
+// `getProtection` clears its slot on a failed build, so the next request builds again — one bad start
+// does not switch protection off for the life of the process.
+//
+// Only the FIRST failure is reported: enough to know the guard is not screening, without a line per
+// request. A later failure is not reported, including one with a different cause.
+let psUnavailable = false;
+function psStepAside(err) {
+  if (!psUnavailable) {
+    psUnavailable = true;
+    console.warn(
+      "[patchstack] protection is unavailable; traffic may pass through unscreened until a later attempt succeeds. Reported once per process. Cause: " +
+        (err instanceof Error ? err.message : String(err)),
+    );
+  }
+
+  return null;
+}
 // Web-Fetch: export default { fetch: protectFetch(originalFetch) }
 export function protectFetch(handler) {
   return async (request, ...rest) => {
-    const active = await getProtection();
+    const active = await getProtection().catch(psStepAside);
+    // The handler, and nothing around it: an exception the app throws is the app's, not a protection
+    // failure, and must not be read as one or answered twice.
+    if (!active) return handler(request, ...rest);
     const blocked = await active.fetchGuard()(request);
     if (blocked) return blocked;
     // Response rules can be scoped to a route or a method, and the engine can only apply that scope if it is
@@ -51,7 +84,27 @@ export function protectFetch(handler) {
 // Node / Connect: app.use(patchstackMiddleware) — before any body parser. This guard reads the request
 // stream itself and exposes what it read as req.body, so a parser is not also needed.
 export function patchstackMiddleware(req, res, next) {
-  getProtection()
-    .then((active) => active.node()(req, res, next))
-    .catch(() => next()); // fail open
+  // `next` is wrapped so it can run at most once, whatever happens. That is what makes the two
+  // handlers below safe: a rejection handler passed to `then` sees only a failed build, the trailing
+  // one sees whatever the guard or the app's own chain threw and reports it — and neither can pass a
+  // request on that was already passed on, nor leave one that never was.
+  let passedOn = false;
+  const carryOn = (err) => {
+    if (passedOn) return;
+    passedOn = true;
+    next(err);
+  };
+  getProtection().then(
+    (active) => active.node()(req, res, carryOn),
+    (err) => {
+      psStepAside(err);
+      carryOn();
+    },
+  ).catch((err) => {
+    // Not a failed build: the guard, or the app's own chain, threw after this point. Reported, and the
+    // request is carried on only if it never was — an error here must not take the process down and
+    // must not answer twice.
+    psStepAside(err);
+    carryOn();
+  });
 }

package/dist/protect/templates/generic-guard.ts

@@ -52,11 +52,34 @@ async function buildProtection() {
   );
 }
 
+
+// A protection that could not be built must not become an app that cannot answer. Each seam below asks
+// for one, steps aside when it cannot have one, and leaves the app to carry on unscreened.
+// `getProtection` clears its slot on a failed build, so the next request builds again — one bad start
+// does not switch protection off for the life of the process.
+//
+// Only the FIRST failure is reported: enough to know the guard is not screening, without a line per
+// request. A later failure is not reported, including one with a different cause.
+let psUnavailable = false;
+function psStepAside(err: unknown) {
+  if (!psUnavailable) {
+    psUnavailable = true;
+    console.warn(
+      "[patchstack] protection is unavailable; traffic may pass through unscreened until a later attempt succeeds. Reported once per process. Cause: " +
+        (err instanceof Error ? err.message : String(err)),
+    );
+  }
+
+  return null;
+}
 // --- Web Fetch (Cloudflare Workers, Bun, Deno, Hono, Next edge, TanStack server.ts) ---------
 // Wrap your fetch handler:  export default { fetch: protectFetch(originalFetch) }
 export function protectFetch<H extends (request: Request, ...rest: unknown[]) => unknown>(handler: H): H {
   return (async (request: Request, ...rest: unknown[]) => {
-    const protection = await getProtection();
+    const protection = await getProtection().catch(psStepAside);
+    // The handler, and nothing around it: an exception the app throws is the app's, not a protection
+    // failure, and must not be read as one or answered twice.
+    if (!protection) return handler(request, ...rest);
     const blocked = await protection.fetchGuard()(request);
     if (blocked) return blocked;
     // Response rules can be scoped to a route or a method, and the engine can only apply that scope if it is
@@ -70,7 +93,27 @@ export function protectFetch<H extends (request: Request, ...rest: unknown[]) =>
 // app.use(patchstackMiddleware) — register it before any body parser and before your routes. This guard
 // reads the request stream itself and exposes what it read as req.body, so a parser is not also needed.
 export function patchstackMiddleware(req: unknown, res: unknown, next: (err?: unknown) => void) {
-  getProtection()
-    .then((protection) => (protection.node() as (a: unknown, b: unknown, c: (e?: unknown) => void) => void)(req, res, next))
-    .catch(() => next()); // fail open
+  // `next` is wrapped so it can run at most once, whatever happens. That is what makes the two
+  // handlers below safe: a rejection handler passed to `then` sees only a failed build, the trailing
+  // one sees whatever the guard or the app's own chain threw and reports it — and neither can pass a
+  // request on that was already passed on, nor leave one that never was.
+  let passedOn = false;
+  const carryOn = (err?: unknown) => {
+    if (passedOn) return;
+    passedOn = true;
+    next(err);
+  };
+  getProtection().then(
+    (protection) => (protection.node() as (a: unknown, b: unknown, c: (e?: unknown) => void) => void)(req, res, carryOn),
+    (err) => {
+      psStepAside(err);
+      carryOn();
+    },
+  ).catch((err) => {
+    // Not a failed build: the guard, or the app's own chain, threw after this point. Reported, and the
+    // request is carried on only if it never was — an error here must not take the process down and
+    // must not answer twice.
+    psStepAside(err);
+    carryOn();
+  });
 }

package/dist/protect/templates/guard.ts

@@ -74,6 +74,26 @@ async function buildProtection() {
   );
 }
 
+
+// A protection that could not be built must not become an app that cannot answer. Each seam below asks
+// for one, steps aside when it cannot have one, and leaves the app to carry on unscreened.
+// `getProtection` clears its slot on a failed build, so the next request builds again — one bad start
+// does not switch protection off for the life of the process.
+//
+// Only the FIRST failure is reported: enough to know the guard is not screening, without a line per
+// request. A later failure is not reported, including one with a different cause.
+let psUnavailable = false;
+function psStepAside(err: unknown) {
+  if (!psUnavailable) {
+    psUnavailable = true;
+    console.warn(
+      "[patchstack] protection is unavailable; traffic may pass through unscreened until a later attempt succeeds. Reported once per process. Cause: " +
+        (err instanceof Error ? err.message : String(err)),
+    );
+  }
+
+  return null;
+}
 // Request-middleware path: the browser tunnels its direct Supabase calls here.
 let _handle: ((request: Request) => Promise<Response>) | undefined;
 export async function handleGuardRequest(request: Request): Promise<Response> {
@@ -91,7 +111,10 @@ export async function handleGuardRequest(request: Request): Promise<Response> {
 let _inspect: ((data: unknown) => Promise<{ rule?: string; message: string } | null>) | undefined;
 export async function inspectServerFn(data: unknown): Promise<{ rule?: string; message: string } | null> {
   if (!_inspect) {
-    _inspect = createServerFnGuard({ protection: await getProtection() });
+    const protection = await getProtection().catch(psStepAside);
+    // Null is "allow" here, which is what the two paths below already answer when they cannot screen.
+    if (!protection) return null;
+    _inspect = createServerFnGuard({ protection });
   }
   return _inspect(data);
 }
@@ -105,12 +128,17 @@ export async function inspectServerFn(data: unknown): Promise<{ rule?: string; m
 // route or a method, and the engine can only apply that scope if it is given the request the response
 // belongs to. Without it a scoped response rule is delivered, counted as protection, and matches nothing.
 export async function screenResponse<T>(response: T, request?: Request): Promise<T> {
+  if (!(response instanceof Response)) return response;
+  const protection = await getProtection().catch(psStepAside);
+  if (!protection) return response;
   try {
-    if (!(response instanceof Response)) return response;
-    const protection = await getProtection();
     return (protection.screenResponse ? await protection.screenResponse(response, request) : response) as T;
-  } catch {
-    return response; // fail open
+  } catch (err) {
+    // Reported, then the response goes out as it is. A response that was never screened and a response
+    // that had nothing to redact look identical from here, so silence would make them one.
+    psStepAside(err);
+
+    return response;
   }
 }
 
@@ -120,10 +148,16 @@ export async function screenResponse<T>(response: T, request?: Request): Promise
 // WAF false-positive surface, so it is opt-in. `request.clone()` so the app can still read the body.
 let _reqGuard: ((request: Request) => Promise<Response | null>) | undefined;
 export async function guardRequest(request: Request): Promise<Response | null> {
+  if (!_reqGuard) {
+    const protection = await getProtection().catch(psStepAside);
+    if (!protection) return null; // null is "allow" here
+    _reqGuard = protection.fetchGuard();
+  }
   try {
-    if (!_reqGuard) _reqGuard = (await getProtection()).fetchGuard();
     return await _reqGuard(request.clone());
-  } catch {
-    return null; // fail open
+  } catch (err) {
+    psStepAside(err);
+
+    return null;
   }
 }

package/dist/protect/templates/next-middleware.ts

@@ -42,9 +42,30 @@ async function buildProtection() {
   );
 }
 
+
+// A protection that could not be built must not become an app that cannot answer. Each seam below asks
+// for one, steps aside when it cannot have one, and leaves the app to carry on unscreened.
+// `getProtection` clears its slot on a failed build, so the next request builds again — one bad start
+// does not switch protection off for the life of the process.
+//
+// Only the FIRST failure is reported: enough to know the guard is not screening, without a line per
+// request. A later failure is not reported, including one with a different cause.
+let psUnavailable = false;
+function psStepAside(err: unknown) {
+  if (!psUnavailable) {
+    psUnavailable = true;
+    console.warn(
+      "[patchstack] protection is unavailable; traffic may pass through unscreened until a later attempt succeeds. Reported once per process. Cause: " +
+        (err instanceof Error ? err.message : String(err)),
+    );
+  }
+
+  return null;
+}
 // #region patchstack-next (managed by patchstack-connect protect — do not edit)
 export async function middleware(request: Request) {
-  const protection = await getProtection();
+  const protection = await getProtection().catch(psStepAside);
+  if (!protection) return; // Next continues to the route
   const blocked = await protection.fetchGuard()(request);
   if (blocked) return blocked; // 403 — blocked before it reaches your route
   // otherwise fall through (Next continues to the route)

package/dist/protect/templates/nuxt-middleware.ts

@@ -42,9 +42,30 @@ async function buildProtection() {
   );
 }
 
+
+// A protection that could not be built must not become an app that cannot answer. Each seam below asks
+// for one, steps aside when it cannot have one, and leaves the app to carry on unscreened.
+// `getProtection` clears its slot on a failed build, so the next request builds again — one bad start
+// does not switch protection off for the life of the process.
+//
+// Only the FIRST failure is reported: enough to know the guard is not screening, without a line per
+// request. A later failure is not reported, including one with a different cause.
+let psUnavailable = false;
+function psStepAside(err: unknown) {
+  if (!psUnavailable) {
+    psUnavailable = true;
+    console.warn(
+      "[patchstack] protection is unavailable; traffic may pass through unscreened until a later attempt succeeds. Reported once per process. Cause: " +
+        (err instanceof Error ? err.message : String(err)),
+    );
+  }
+
+  return null;
+}
 // #region patchstack-nuxt (managed by patchstack-connect protect — do not edit)
 export default defineEventHandler(async (event) => {
-  const protection = await getProtection();
+  const protection = await getProtection().catch(psStepAside);
+  if (!protection) return; // Nitro continues to the route
   const method = event.method ?? "GET";
   // readRawBody caches on the event, so your route handlers can still read the body.
   const body = method !== "GET" && method !== "HEAD" ? await readRawBody(event) : undefined;

package/dist/protect/templates/sveltekit-hooks.ts

@@ -42,9 +42,30 @@ async function buildProtection() {
   );
 }
 
+
+// A protection that could not be built must not become an app that cannot answer. Each seam below asks
+// for one, steps aside when it cannot have one, and leaves the app to carry on unscreened.
+// `getProtection` clears its slot on a failed build, so the next request builds again — one bad start
+// does not switch protection off for the life of the process.
+//
+// Only the FIRST failure is reported: enough to know the guard is not screening, without a line per
+// request. A later failure is not reported, including one with a different cause.
+let psUnavailable = false;
+function psStepAside(err: unknown) {
+  if (!psUnavailable) {
+    psUnavailable = true;
+    console.warn(
+      "[patchstack] protection is unavailable; traffic may pass through unscreened until a later attempt succeeds. Reported once per process. Cause: " +
+        (err instanceof Error ? err.message : String(err)),
+    );
+  }
+
+  return null;
+}
 // #region patchstack-sveltekit (managed by patchstack-connect protect — do not edit)
 export const handle: Handle = async ({ event, resolve }) => {
-  const protection = await getProtection();
+  const protection = await getProtection().catch(psStepAside);
+  if (!protection) return resolve(event);
   const blocked = await protection.fetchGuard()(event.request);
   if (blocked) return blocked; // 403 — blocked before it reaches your route
   // Response rules can be scoped to a route or a method, and the engine can only apply that scope if it is