@freshjuice/zest 2.1.0 → 2.3.0

package/src/core/network-interceptor.js

@@ -0,0 +1,289 @@
+/**
+ * Network Interceptor - Intercepts fetch / XHR / sendBeacon calls
+ *
+ * Why this exists separately from the script blocker:
+ *
+ * Modern CMSes (HubSpot, Cloudflare Zaraz, server-side GTM, Shopify,
+ * Webflow) increasingly proxy their tracker code through the site's own
+ * origin to defeat ad-blockers. The <script> tag itself is first-party
+ * (e.g. /hs/scriptloader/{id}.js) so a hostname-based script blocker
+ * cannot match it. But at RUNTIME that script still phones home to the
+ * vendor's analytics endpoint via fetch / XHR / sendBeacon — and THAT
+ * URL is third-party.
+ *
+ * This interceptor sits on the network layer and uses the same
+ * customBlockedDomains + mode-based tracker list as the script blocker.
+ * Whatever the user told Zest to block (typically generated by an AI
+ * audit) gets blocked regardless of which API the tracker uses.
+ *
+ * No replay: network calls are one-shot and time-sensitive. Replaying a
+ * stale beacon after consent would create confusing / duplicated data,
+ * so blocked requests are dropped, not queued.
+ */
+
+import { getCategoryForScript, isThirdParty } from './known-trackers.js';
+
+// Originals captured at install time. Stored for restoration tests and
+// for any internal Zest network calls we may add later.
+let originalFetch = null;
+let originalXhrOpen = null;
+let originalXhrSend = null;
+let originalSendBeacon = null;
+
+let blockingMode = 'safe';
+let customBlockedDomains = [];
+let installed = false;
+
+let checkConsent = () => false;
+
+const BLOCKABLE_CATEGORIES = new Set(['functional', 'analytics', 'marketing']);
+
+export function setConsentChecker(fn) {
+  checkConsent = fn;
+}
+
+export function setBlockingMode(mode) {
+  blockingMode = mode;
+}
+
+export function setCustomBlockedDomains(domains) {
+  customBlockedDomains = Array.isArray(domains) ? domains : [];
+}
+
+/**
+ * Resolve a Request | URL | string to an absolute URL string. Returns
+ * null if the input cannot be parsed — callers treat null as "do not
+ * block" (we'd rather let an opaque request through than crash the page).
+ */
+function resolveUrl(input) {
+  try {
+    if (typeof input === 'string') {
+      return new URL(input, location.href).href;
+    }
+    if (input && typeof input === 'object') {
+      if (typeof input.url === 'string') {
+        // Request object
+        return new URL(input.url, location.href).href;
+      }
+      if (typeof input.href === 'string') {
+        // URL object
+        return input.href;
+      }
+    }
+  } catch (e) {
+    // fallthrough
+  }
+  return null;
+}
+
+/**
+ * Match a URL against the user's customBlockedDomains list. Mirrors
+ * matchesCustomDomains() in script-blocker.js — kept inline rather than
+ * shared so each interceptor can be lifted independently.
+ */
+function matchesCustomDomains(hostname) {
+  if (!hostname || customBlockedDomains.length === 0) return null;
+  const host = hostname.toLowerCase();
+  for (const entry of customBlockedDomains) {
+    const domain = (typeof entry === 'string' ? entry : entry?.domain || '').toLowerCase();
+    if (!domain) continue;
+    const category = typeof entry === 'string'
+      ? 'marketing'
+      : (BLOCKABLE_CATEGORIES.has(entry?.category) ? entry.category : 'marketing');
+    if (host === domain || host.endsWith('.' + domain)) {
+      return category;
+    }
+  }
+  return null;
+}
+
+/**
+ * Decide whether a URL should be blocked and return its category, or
+ * null if it should pass through. Priority: customBlockedDomains >
+ * mode-based tracker list (matching script-blocker priority).
+ */
+function getBlockCategory(url) {
+  if (!url) return null;
+  let hostname;
+  try {
+    hostname = new URL(url, location.href).hostname;
+  } catch (e) {
+    return null;
+  }
+
+  const customCategory = matchesCustomDomains(hostname);
+  if (customCategory) return customCategory;
+
+  switch (blockingMode) {
+    case 'manual':
+      return null;
+    case 'safe':
+    case 'strict':
+      return getCategoryForScript(url, blockingMode);
+    case 'doomsday':
+      if (isThirdParty(url)) {
+        return getCategoryForScript(url, 'strict') || 'marketing';
+      }
+      return null;
+    default:
+      return null;
+  }
+}
+
+/**
+ * Should the request be blocked right now? Returns the category that
+ * caused the block (for logging / callbacks later) or null.
+ */
+function shouldBlock(url) {
+  const category = getBlockCategory(url);
+  if (!category) return null;
+  if (checkConsent(category)) return null;
+  return category;
+}
+
+/**
+ * Construct an empty, successful-looking Response for a blocked fetch.
+ * Status 204 (No Content) is the most honest "we deliberately returned
+ * nothing" signal. Trackers that .then(r => r.json()) will get an empty
+ * body and typically silently move on.
+ */
+function blockedResponse() {
+  // Some environments (older browsers, strict CSP) may not have Response
+  // — fall back to a thenable shape the most common tracker code expects.
+  if (typeof Response === 'function') {
+    return new Response(null, { status: 204, statusText: 'Blocked by Zest' });
+  }
+  const fake = {
+    ok: false,
+    status: 204,
+    statusText: 'Blocked by Zest',
+    json: () => Promise.resolve({}),
+    text: () => Promise.resolve(''),
+    arrayBuffer: () => Promise.resolve(new ArrayBuffer(0))
+  };
+  return fake;
+}
+
+/**
+ * Install fetch hook. Captures the original so we can both restore it
+ * later and use it for any internal Zest network calls.
+ */
+function patchFetch() {
+  if (typeof window === 'undefined' || typeof window.fetch !== 'function') return;
+  originalFetch = window.fetch.bind(window);
+
+  window.fetch = function zestPatchedFetch(input, init) {
+    const url = resolveUrl(input);
+    if (shouldBlock(url)) {
+      return Promise.resolve(blockedResponse());
+    }
+    return originalFetch(input, init);
+  };
+}
+
+/**
+ * Install XMLHttpRequest hook. We patch .open() to capture the URL on
+ * the instance, then .send() to decide whether to abort. Using a hidden
+ * symbol on the instance avoids leaking state and survives any wrapping
+ * code that reassigns request properties.
+ */
+const URL_KEY = Symbol('zestUrl');
+
+function patchXhr() {
+  if (typeof XMLHttpRequest === 'undefined') return;
+  const proto = XMLHttpRequest.prototype;
+  originalXhrOpen = proto.open;
+  originalXhrSend = proto.send;
+
+  proto.open = function (method, url, ...rest) {
+    this[URL_KEY] = typeof url === 'string' ? url : (url && url.href) || '';
+    return originalXhrOpen.call(this, method, url, ...rest);
+  };
+
+  proto.send = function (body) {
+    const url = this[URL_KEY];
+    if (shouldBlock(url)) {
+      // Mimic the failure mode of a network error: queueMicrotask is
+      // used so consumers that synchronously attach handlers after
+      // .send() still receive the events.
+      const xhr = this;
+      queueMicrotask(() => {
+        try {
+          // Best-effort — readonly props in some environments
+          Object.defineProperty(xhr, 'readyState', { value: 4, configurable: true });
+          Object.defineProperty(xhr, 'status', { value: 0, configurable: true });
+        } catch (e) {
+          // ignore
+        }
+        try {
+          xhr.dispatchEvent(new Event('error'));
+          xhr.dispatchEvent(new Event('loadend'));
+        } catch (e) {
+          // ignore
+        }
+      });
+      return;
+    }
+    return originalXhrSend.call(this, body);
+  };
+}
+
+/**
+ * Install navigator.sendBeacon hook. Returning false matches the spec's
+ * "data was not queued" semantics; trackers that check the return value
+ * fall back to fetch (which we also block) or give up.
+ */
+function patchSendBeacon() {
+  if (typeof navigator === 'undefined' || typeof navigator.sendBeacon !== 'function') return;
+  originalSendBeacon = navigator.sendBeacon.bind(navigator);
+
+  navigator.sendBeacon = function zestPatchedSendBeacon(url, data) {
+    if (shouldBlock(typeof url === 'string' ? url : (url && url.href) || '')) {
+      return false;
+    }
+    return originalSendBeacon(url, data);
+  };
+}
+
+/**
+ * Install all network hooks. Safe to call multiple times — subsequent
+ * calls just refresh mode + custom domain config without re-wrapping.
+ */
+export function interceptNetwork(mode = 'safe', customDomains = []) {
+  blockingMode = mode;
+  customBlockedDomains = Array.isArray(customDomains) ? customDomains : [];
+
+  if (installed) return true;
+  patchFetch();
+  patchXhr();
+  patchSendBeacon();
+  installed = true;
+  return true;
+}
+
+/**
+ * Test helper / opt-out. Restores the original APIs. Not called by
+ * coreInit — exposed for unit tests and headless consumers that need
+ * to tear down their environment between consent flows.
+ */
+export function restoreNetwork() {
+  if (!installed) return;
+  if (originalFetch && typeof window !== 'undefined') window.fetch = originalFetch;
+  if (originalXhrOpen && typeof XMLHttpRequest !== 'undefined') {
+    XMLHttpRequest.prototype.open = originalXhrOpen;
+  }
+  if (originalXhrSend && typeof XMLHttpRequest !== 'undefined') {
+    XMLHttpRequest.prototype.send = originalXhrSend;
+  }
+  if (originalSendBeacon && typeof navigator !== 'undefined') {
+    navigator.sendBeacon = originalSendBeacon;
+  }
+  installed = false;
+}
+
+/**
+ * For tests: query install state.
+ */
+export function isInstalled() {
+  return installed;
+}

package/src/core/pattern-matcher.js

@@ -51,10 +51,47 @@ export const DEFAULT_PATTERNS = {
 
 let patterns = { ...DEFAULT_PATTERNS };
 
+/** Escape a string so it can be embedded in a regex literal verbatim. */
+function escapeRegex(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Append patterns to a single category without replacing what's already
+ * there. Used by `essentialKeys` and `essentialPatterns` config to extend
+ * the strictly-necessary category with consumer-specific entries while
+ * keeping the built-in defaults (zest_*, csrf*, xsrf*, etc.).
+ *
+ * `keys` is an array of exact storage/cookie names; each one is
+ * compiled as a fully-anchored regex via `escapeRegex`.
+ * `patternStrings` is an array of regex source strings, each validated
+ * via `safeRegExp`. Invalid entries are dropped silently.
+ */
+export function appendPatternsToCategory(category, { keys = [], patternStrings = [] } = {}) {
+  if (!patterns[category]) patterns[category] = [];
+
+  for (const key of keys) {
+    if (typeof key !== 'string' || !key) continue;
+    const re = safeRegExp(`^${escapeRegex(key)}$`);
+    if (re) patterns[category].push(re);
+  }
+
+  for (const p of patternStrings) {
+    if (typeof p !== 'string' || !p) continue;
+    const re = safeRegExp(p);
+    if (re) patterns[category].push(re);
+  }
+}
+
 /**
  * Set custom patterns. User-supplied strings are validated with safeRegExp,
  * which rejects catastrophic-backtracking shapes and syntax errors.
  * Invalid patterns are silently dropped with a console warning.
+ *
+ * Note: this REPLACES the patterns for any category present in
+ * `customPatterns`. To extend the essential category without losing the
+ * built-in defaults, use `appendPatternsToCategory()` (or pass
+ * `essentialKeys` / `essentialPatterns` to `Zest.init()`).
  */
 export function setPatterns(customPatterns) {
   patterns = { ...DEFAULT_PATTERNS };

package/src/core-lifecycle.js

@@ -11,7 +11,9 @@
 import { interceptCookies, setConsentChecker as setCookieChecker, replayCookies } from './core/cookie-interceptor.js';
 import { interceptStorage, setConsentChecker as setStorageChecker, replayStorage } from './core/storage-interceptor.js';
 import { startScriptBlocking, setConsentChecker as setScriptChecker, replayScripts } from './core/script-blocker.js';
-import { setPatterns } from './core/pattern-matcher.js';
+import { interceptNetwork, setConsentChecker as setNetworkChecker } from './core/network-interceptor.js';
+import { interceptElements, setConsentChecker as setElementChecker, replayElements } from './core/element-interceptor.js';
+import { setPatterns, appendPatternsToCategory } from './core/pattern-matcher.js';
 import { getCategoryIds } from './core/categories.js';
 import { isDoNotTrackEnabled } from './core/dnt.js';
 import { safeInvoke } from './core/security.js';
@@ -42,6 +44,11 @@ function replayAll(categories) {
   replayCookies(categories);
   replayStorage(categories);
   replayScripts(categories);
+  // Element-level replays (script/link/img/iframe URLs that were
+  // dropped at the prototype-setter / setAttribute layer). Network
+  // interceptor (fetch/XHR/sendBeacon) intentionally has no replay
+  // — beacons are one-shot and resending would duplicate analytics.
+  replayElements(categories);
 }
 
 /**
@@ -73,13 +80,44 @@ export function coreInit(userConfig = {}) {
     setPatterns(currentConfig.patterns);
   }
 
+  // Append consumer-declared strictly-necessary entries on top of
+  // whatever's already in the essential category. This is the friendly
+  // alternative to overriding via `patterns.essential` directly.
+  if (
+    (Array.isArray(currentConfig.essentialKeys) && currentConfig.essentialKeys.length > 0) ||
+    (Array.isArray(currentConfig.essentialPatterns) && currentConfig.essentialPatterns.length > 0)
+  ) {
+    appendPatternsToCategory('essential', {
+      keys: currentConfig.essentialKeys,
+      patternStrings: currentConfig.essentialPatterns
+    });
+  }
+
   setCookieChecker(checkConsent);
   setStorageChecker(checkConsent);
   setScriptChecker(checkConsent);
-
-  interceptCookies();
-  interceptStorage();
-  startScriptBlocking(currentConfig.mode, currentConfig.blockedDomains);
+  setNetworkChecker(checkConsent);
+  setElementChecker(checkConsent);
+
+  // Interceptor toggles. By default everything is intercepted (back-compat
+  // with v2.0 / v2.1). Consumers that gate scripts and storage themselves
+  // can opt out per channel via `intercept: { storage: false, … }`.
+  const intercept = currentConfig.intercept || { cookies: true, storage: true, scripts: true, network: true };
+  if (intercept.cookies !== false) interceptCookies();
+  if (intercept.storage !== false) interceptStorage();
+  if (intercept.scripts !== false) {
+    // Element-level synchronous interception (prototype setters +
+    // setAttribute) installs BEFORE startScriptBlocking so that the
+    // moment any later script does `el.src = "https://tracker..."`,
+    // we drop the URL before the browser fetches. The MutationObserver
+    // inside startScriptBlocking remains as a defence-in-depth net for
+    // anything that slips past (e.g. nodes constructed via cloneNode).
+    interceptElements(currentConfig.mode, currentConfig.blockedDomains);
+    startScriptBlocking(currentConfig.mode, currentConfig.blockedDomains);
+  }
+  if (intercept.network !== false) {
+    interceptNetwork(currentConfig.mode, currentConfig.blockedDomains);
+  }
 
   const consent = loadConsent();
   initialized = true;

package/src/index.js

@@ -119,18 +119,29 @@ function handleCloseModal() {
 }
 
 /**
- * Initialize Zest with UI.
+ * UI mount guard. We split UI mounting (which needs `<body>` and a parsed
+ * DOM) from interceptor installation (which must happen on script eval to
+ * gate any later `defer` / `async` tracker scripts). `coreInit()` is
+ * idempotent so calling init() before the DOM is ready is safe — the UI
+ * portion just gets queued.
  */
-function init(userConfig = {}) {
-  const { alreadyInitialized, consent, hasDecision, dntApplied } = coreInit(userConfig);
-  if (alreadyInitialized) {
-    console.warn('[Zest] Already initialized');
-    return Zest;
+let uiMounted = false;
+
+function mountUI() {
+  if (uiMounted) return;
+
+  // Banner needs document.body to mount its host element. If body isn't
+  // there yet, requeue on DOMContentLoaded.
+  if (!document || !document.body) {
+    document.addEventListener('DOMContentLoaded', mountUI, { once: true });
+    return;
   }
 
+  uiMounted = true;
   const config = getActiveConfig();
+  const decision = hasConsentDecision();
 
-  if (!hasDecision && !dntApplied) {
+  if (!decision) {
     showBanner({
       onAcceptAll: handleAcceptAll,
       onRejectAll: handleRejectAll,
@@ -140,7 +151,27 @@ function init(userConfig = {}) {
   } else if (config?.showWidget) {
     showWidget({ onClick: handleShowSettings });
   }
+}
 
+/**
+ * Initialize Zest with UI.
+ *
+ * Splits into two phases:
+ *
+ *   1. `coreInit()` runs synchronously: interceptors install on the
+ *      cookie / storage / script / network channels immediately so any
+ *      `defer` or `async` script that fires later is already gated.
+ *      Critical — DOMContentLoaded fires AFTER `defer` scripts execute,
+ *      so deferring interceptor install means trackers fire first.
+ *
+ *   2. UI mount (banner / widget) is queued until `<body>` exists. If
+ *      this script runs in `<head>` while the document is still
+ *      parsing, that means waiting for DOMContentLoaded; if it runs
+ *      after, mount happens immediately.
+ */
+function init(userConfig = {}) {
+  coreInit(userConfig);
+  mountUI();
   return Zest;
 }
 
@@ -249,17 +280,14 @@ if (typeof window !== 'undefined') {
     window.Zest = Zest;
   }
 
-  const autoInit = () => {
-    const cfg = getConfig();
-    if (cfg.autoInit !== false) {
-      init(window.ZestConfig);
-    }
-  };
-
-  if (document.readyState === 'loading') {
-    document.addEventListener('DOMContentLoaded', autoInit);
-  } else {
-    autoInit();
+  // Run init() synchronously on script eval. init() itself splits the
+  // work — interceptors install now, UI mount waits for <body> if
+  // needed. No DOMContentLoaded wait at this layer: deferring init()
+  // would let any `defer` / `async` tracker script fire its network
+  // calls before our interceptors are in place.
+  const cfg = getConfig();
+  if (cfg.autoInit !== false) {
+    init(window.ZestConfig);
   }
 }
 

package/src/types/zest.d.ts

@@ -83,6 +83,27 @@ export interface ZestCallbacks {
   onReady?: (consent: ConsentState) => void;
 }
 
+/**
+ * Granular toggles for Zest's interceptor layer. Default is `true` on
+ * every channel — back-compat with previous versions.
+ *
+ * Consumers that gate optional scripts and storage themselves can
+ * disable interception per channel and use Zest as a pure consent-state
+ * engine.
+ */
+export interface InterceptToggles {
+  cookies?: boolean;
+  storage?: boolean;
+  scripts?: boolean;
+  /**
+   * fetch / XMLHttpRequest / navigator.sendBeacon interception. Catches
+   * trackers that ship via CMS first-party proxies (HubSpot, Cloudflare
+   * Zaraz, server-side GTM) where the <script> tag is same-origin but
+   * the runtime beacon is third-party.
+   */
+  network?: boolean;
+}
+
 /** Configuration accepted by `init()` and `window.ZestConfig`. */
 export interface InitOptions {
   /** Display language. `'auto'` detects from `<html lang>` / browser. */
@@ -110,6 +131,25 @@ export interface InitOptions {
   respectDNT?: boolean;
   /** What to do when DNT/GPC is on. Default `'reject'`. */
   dntBehavior?: DNTBehavior;
+  /** Disable individual interceptors. Default: all on. */
+  intercept?: InterceptToggles;
+  /**
+   * Exact storage / cookie names to treat as strictly-necessary. Each
+   * is appended to the essential category as a fully-anchored regex,
+   * so the built-in essential patterns (zest_*, csrf*, …) stay intact.
+   */
+  essentialKeys?: string[];
+  /**
+   * Regex source strings to treat as strictly-necessary. Validated via
+   * safeRegExp, appended (not replaced) to the essential category.
+   */
+  essentialPatterns?: string[];
+  /**
+   * Override patterns per category. Note: this REPLACES the category's
+   * built-in patterns. Prefer `essentialKeys` / `essentialPatterns` if
+   * you only want to add to the essential category.
+   */
+  patterns?: Partial<Record<ConsentCategory, string[]>>;
   /** Consumer callbacks. */
   callbacks?: ZestCallbacks;
   /** Anything else — Zest tolerates unknown keys at runtime. */

package/src/types/zest.headless.d.ts

@@ -70,6 +70,27 @@ export interface ZestCallbacks {
   onReady?: (consent: ConsentState) => void;
 }
 
+/**
+ * Granular toggles for Zest's interceptor layer. Default is `true` on
+ * every channel — back-compat with previous versions.
+ *
+ * Consumers that gate optional scripts and storage themselves (typical
+ * for headless integrations) can disable interception per channel and
+ * use Zest as a pure consent-state engine.
+ */
+export interface InterceptToggles {
+  cookies?: boolean;
+  storage?: boolean;
+  scripts?: boolean;
+  /**
+   * fetch / XMLHttpRequest / navigator.sendBeacon interception. Catches
+   * trackers that ship via CMS first-party proxies (HubSpot, Cloudflare
+   * Zaraz, server-side GTM) where the <script> tag is same-origin but
+   * the runtime beacon is third-party.
+   */
+  network?: boolean;
+}
+
 /** Configuration accepted by `init()`. */
 export interface InitOptions {
   /** Respect Do Not Track / Global Privacy Control. Default `true`. */
@@ -78,6 +99,25 @@ export interface InitOptions {
   dntBehavior?: DNTBehavior;
   /** Cookie expiration in days. Default `365`. */
   expiration?: number;
+  /** Disable individual interceptors. Default: all on. */
+  intercept?: InterceptToggles;
+  /**
+   * Exact storage / cookie names to treat as strictly-necessary. Each
+   * is appended to the essential category as a fully-anchored regex,
+   * so the built-in essential patterns (zest_*, csrf*, …) stay intact.
+   */
+  essentialKeys?: string[];
+  /**
+   * Regex source strings to treat as strictly-necessary. Validated via
+   * safeRegExp, appended (not replaced) to the essential category.
+   */
+  essentialPatterns?: string[];
+  /**
+   * Override patterns per category. Note: this REPLACES the category's
+   * built-in patterns. Prefer `essentialKeys` / `essentialPatterns` if
+   * you only want to add to the essential category.
+   */
+  patterns?: Partial<Record<ConsentCategory, string[]>>;
   /** Consumer callbacks. */
   callbacks?: ZestCallbacks;
   /** Anything else — Zest tolerates unknown keys at runtime. */

package/zest.config.schema.json

@@ -212,6 +212,32 @@
         }
       }
     },
+    "intercept": {
+      "type": "object",
+      "description": "Granular toggles for Zest's interceptor layer. Default is true on every channel.",
+      "properties": {
+        "cookies": {
+          "type": "boolean",
+          "default": true,
+          "description": "Intercept document.cookie writes"
+        },
+        "storage": {
+          "type": "boolean",
+          "default": true,
+          "description": "Intercept localStorage / sessionStorage writes"
+        },
+        "scripts": {
+          "type": "boolean",
+          "default": true,
+          "description": "Block third-party tracker <script> tags before they execute"
+        },
+        "network": {
+          "type": "boolean",
+          "default": true,
+          "description": "Intercept fetch / XMLHttpRequest / navigator.sendBeacon calls. Catches trackers that ship via CMS first-party proxies (HubSpot, Cloudflare Zaraz, server-side GTM) where the <script> tag is same-origin but the runtime beacon is third-party."
+        }
+      }
+    },
     "callbacks": {
       "type": "object",
       "description": "Callback functions for consent events",