@freshjuice/zest 0.1.0 → 2.0.0

package/src/core/cookie-interceptor.js

@@ -0,0 +1,131 @@
+/**
+ * Cookie Interceptor - Intercepts document.cookie operations
+ */
+
+import { getCategoryForName, parseCookieName } from './pattern-matcher.js';
+
+// Store original descriptor
+let originalCookieDescriptor = null;
+
+// Upper bound on the number of queued cookies awaiting consent replay.
+// An unbounded queue is a memory-exhaustion DoS vector — a hostile
+// script could flood it with document.cookie writes.
+const MAX_QUEUE_SIZE = 100;
+
+// Queue for blocked cookies
+const cookieQueue = [];
+
+// Reference to consent checker function
+let checkConsent = () => false;
+
+/**
+ * Set the consent checker function
+ */
+export function setConsentChecker(fn) {
+  checkConsent = fn;
+}
+
+/**
+ * Get the original cookie descriptor
+ */
+export function getOriginalCookieDescriptor() {
+  return originalCookieDescriptor;
+}
+
+/**
+ * Get queued cookies
+ */
+export function getCookieQueue() {
+  return [...cookieQueue];
+}
+
+/**
+ * Clear the cookie queue
+ */
+export function clearCookieQueue() {
+  cookieQueue.length = 0;
+}
+
+/**
+ * Replay queued cookies for allowed categories
+ */
+export function replayCookies(allowedCategories) {
+  const remaining = [];
+
+  for (const item of cookieQueue) {
+    if (allowedCategories.includes(item.category)) {
+      // Set the cookie using original setter
+      if (originalCookieDescriptor?.set) {
+        originalCookieDescriptor.set.call(document, item.value);
+      }
+    } else {
+      remaining.push(item);
+    }
+  }
+
+  cookieQueue.length = 0;
+  cookieQueue.push(...remaining);
+}
+
+/**
+ * Start intercepting cookies
+ */
+export function interceptCookies() {
+  // Store original
+  originalCookieDescriptor = Object.getOwnPropertyDescriptor(Document.prototype, 'cookie');
+
+  if (!originalCookieDescriptor) {
+    console.warn('[Zest] Could not get cookie descriptor');
+    return false;
+  }
+
+  Object.defineProperty(document, 'cookie', {
+    get() {
+      // Always allow reading
+      return originalCookieDescriptor.get.call(document);
+    },
+    set(value) {
+      const name = parseCookieName(value);
+      if (!name) {
+        return;
+      }
+
+      const category = getCategoryForName(name);
+
+      if (checkConsent(category)) {
+        // Consent given - set cookie
+        originalCookieDescriptor.set.call(document, value);
+      } else if (cookieQueue.length < MAX_QUEUE_SIZE) {
+        // No consent - queue for later (capped to prevent DoS)
+        cookieQueue.push({
+          value,
+          name,
+          category,
+          timestamp: Date.now()
+        });
+      }
+    },
+    // configurable: false prevents a later-loaded script from
+    // overriding our descriptor and bypassing the interceptor.
+    configurable: false
+  });
+
+  return true;
+}
+
+/**
+ * Restore original cookie behavior.
+ *
+ * Note: after interceptCookies() has locked the descriptor with
+ * configurable:false, this call will throw. The lock is intentional —
+ * it stops a later-loaded script from unwinding the interceptor. If you
+ * need a reset, call this before the first interceptCookies() call.
+ */
+export function restoreCookies() {
+  if (!originalCookieDescriptor) return;
+  try {
+    Object.defineProperty(document, 'cookie', originalCookieDescriptor);
+  } catch (_) {
+    // Descriptor is locked; nothing we can do.
+  }
+}

package/src/core/dnt.js

@@ -0,0 +1,56 @@
+/**
+ * Do Not Track (DNT) Detection
+ *
+ * Detects browser DNT/GPC signals for privacy compliance
+ */
+
+/**
+ * Check if Do Not Track is enabled
+ * Checks both DNT header and Global Privacy Control (GPC)
+ */
+export function isDoNotTrackEnabled() {
+  if (typeof navigator === 'undefined') {
+    return false;
+  }
+
+  // Check DNT (Do Not Track)
+  // Values: "1" = enabled, "0" = disabled, null/undefined = not set
+  const dnt = navigator.doNotTrack ||
+              window.doNotTrack ||
+              navigator.msDoNotTrack;
+
+  if (dnt === '1' || dnt === 'yes' || dnt === true) {
+    return true;
+  }
+
+  // Check GPC (Global Privacy Control) - newer standard
+  // https://globalprivacycontrol.org/
+  if (navigator.globalPrivacyControl === true) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Get DNT signal details for logging/debugging
+ */
+export function getDNTDetails() {
+  if (typeof navigator === 'undefined') {
+    return { enabled: false, source: null };
+  }
+
+  const dnt = navigator.doNotTrack ||
+              window.doNotTrack ||
+              navigator.msDoNotTrack;
+
+  if (dnt === '1' || dnt === 'yes' || dnt === true) {
+    return { enabled: true, source: 'dnt' };
+  }
+
+  if (navigator.globalPrivacyControl === true) {
+    return { enabled: true, source: 'gpc' };
+  }
+
+  return { enabled: false, source: null };
+}

package/src/core/known-trackers.js

@@ -0,0 +1,195 @@
+/**
+ * Known Trackers - Lists of known tracking script domains by category
+ */
+
+/**
+ * Safe mode - Major, well-known trackers only
+ */
+export const SAFE_TRACKERS = {
+  analytics: [
+    'google-analytics.com',
+    'www.google-analytics.com',
+    'analytics.google.com',
+    'googletagmanager.com',
+    'www.googletagmanager.com',
+    'plausible.io',
+    'cloudflareinsights.com',
+    'static.cloudflareinsights.com'
+  ],
+  marketing: [
+    'connect.facebook.net',
+    'www.facebook.com/tr',
+    'ads.google.com',
+    'www.googleadservices.com',
+    'googleads.g.doubleclick.net',
+    'pagead2.googlesyndication.com'
+  ]
+};
+
+/**
+ * Strict mode - Extended list including less common trackers
+ */
+export const STRICT_TRACKERS = {
+  analytics: [
+    ...SAFE_TRACKERS.analytics,
+    'analytics.tiktok.com',
+    'matomo.', // partial match
+    'hotjar.com',
+    'static.hotjar.com',
+    'script.hotjar.com',
+    'clarity.ms',
+    'www.clarity.ms',
+    'heapanalytics.com',
+    'cdn.heapanalytics.com',
+    'mixpanel.com',
+    'cdn.mxpnl.com',
+    'segment.com',
+    'cdn.segment.com',
+    'api.segment.io',
+    'fullstory.com',
+    'rs.fullstory.com',
+    'amplitude.com',
+    'cdn.amplitude.com',
+    'mouseflow.com',
+    'cdn.mouseflow.com',
+    'luckyorange.com',
+    'cdn.luckyorange.net',
+    'crazyegg.com',
+    'script.crazyegg.com'
+  ],
+  marketing: [
+    ...SAFE_TRACKERS.marketing,
+    'snap.licdn.com',
+    'px.ads.linkedin.com',
+    'ads.linkedin.com',
+    'analytics.twitter.com',
+    'static.ads-twitter.com',
+    't.co',
+    'analytics.tiktok.com',
+    'ads.tiktok.com',
+    'sc-static.net', // Snapchat
+    'tr.snapchat.com',
+    'ct.pinterest.com',
+    'pintrk.com',
+    's.pinimg.com',
+    'widgets.pinterest.com',
+    'bat.bing.com',
+    'ads.yahoo.com',
+    'sp.analytics.yahoo.com',
+    'amazon-adsystem.com',
+    'z-na.amazon-adsystem.com',
+    'criteo.com',
+    'static.criteo.net',
+    'dis.criteo.com',
+    'taboola.com',
+    'cdn.taboola.com',
+    'trc.taboola.com',
+    'outbrain.com',
+    'widgets.outbrain.com',
+    'adroll.com',
+    's.adroll.com'
+  ],
+  functional: [
+    'cdn.onesignal.com',
+    'onesignal.com',
+    'pusher.com',
+    'js.pusher.com',
+    'intercom.io',
+    'widget.intercom.io',
+    'js.intercomcdn.com',
+    'crisp.chat',
+    'client.crisp.chat',
+    'cdn.livechatinc.com',
+    'livechatinc.com',
+    'tawk.to',
+    'embed.tawk.to',
+    'zendesk.com',
+    'static.zdassets.com'
+  ]
+};
+
+/**
+ * Check if a URL matches any tracker in the list.
+ *
+ * Matching is restricted to hostname (and, when the list entry contains
+ * a path, the URL path prefix). A naive `fullUrl.includes(domain)` was
+ * previously used, which would false-positive on e.g.
+ *   https://mysite.com/page?ref=google-analytics.com
+ */
+export function matchesTrackerList(url, trackerList) {
+  let urlObj;
+  try {
+    urlObj = new URL(url);
+  } catch (e) {
+    return false;
+  }
+  const hostname = urlObj.hostname.toLowerCase();
+  const path = urlObj.pathname.toLowerCase();
+
+  for (const rawEntry of trackerList) {
+    if (typeof rawEntry !== 'string') continue;
+    const entry = rawEntry.toLowerCase();
+
+    // Partial-prefix match on hostname (entry ends with a dot),
+    // e.g. "matomo." matches "analytics.matomo.cloud"
+    if (entry.endsWith('.')) {
+      const needle = entry.slice(0, -1);
+      const segments = hostname.split('.');
+      if (segments.some(seg => seg === needle) || hostname.startsWith(entry)) {
+        return true;
+      }
+      continue;
+    }
+
+    // Entries containing a slash specify hostname + path prefix
+    const slashIdx = entry.indexOf('/');
+    if (slashIdx !== -1) {
+      const entryHost = entry.slice(0, slashIdx);
+      const entryPath = entry.slice(slashIdx);
+      if ((hostname === entryHost || hostname.endsWith('.' + entryHost)) &&
+          path.startsWith(entryPath)) {
+        return true;
+      }
+      continue;
+    }
+
+    // Plain hostname: exact or subdomain match only
+    if (hostname === entry || hostname.endsWith('.' + entry)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Get category for a script URL based on tracker lists
+ */
+export function getCategoryForScript(url, mode = 'safe') {
+  const trackers = mode === 'strict' ? STRICT_TRACKERS : SAFE_TRACKERS;
+
+  for (const [category, domains] of Object.entries(trackers)) {
+    if (matchesTrackerList(url, domains)) {
+      return category;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Check if URL is third-party (different domain)
+ */
+export function isThirdParty(url) {
+  try {
+    const scriptHost = new URL(url).hostname;
+    const pageHost = window.location.hostname;
+
+    // Remove www. for comparison
+    const normalizeHost = (h) => h.replace(/^www\./, '');
+
+    return normalizeHost(scriptHost) !== normalizeHost(pageHost);
+  } catch (e) {
+    return false;
+  }
+}

package/src/core/pattern-matcher.js

@@ -0,0 +1,111 @@
+/**
+ * Pattern Matcher - Categorizes cookies and storage keys by pattern
+ */
+
+import { safeRegExp } from './security.js';
+
+/**
+ * Default patterns for each category
+ */
+export const DEFAULT_PATTERNS = {
+  essential: [
+    /^zest_/,
+    /^csrf/i,
+    /^xsrf/i,
+    /^session/i,
+    /^__host-/i,
+    /^__secure-/i
+  ],
+  functional: [
+    /^lang/i,
+    /^locale/i,
+    /^theme/i,
+    /^preferences/i,
+    /^ui_/i
+  ],
+  analytics: [
+    /^_ga/,
+    /^_gid/,
+    /^_gat/,
+    /^_utm/,
+    /^__utm/,
+    /^plausible/i,
+    /^_pk_/,
+    /^matomo/i,
+    /^_hj/,
+    /^ajs_/
+  ],
+  marketing: [
+    /^_fbp/,
+    /^_fbc/,
+    /^_gcl/,
+    /^_ttp/,
+    /^ads/i,
+    /^doubleclick/i,
+    /^__gads/,
+    /^__gpi/,
+    /^_pin_/,
+    /^li_/
+  ]
+};
+
+let patterns = { ...DEFAULT_PATTERNS };
+
+/**
+ * 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.
+ */
+export function setPatterns(customPatterns) {
+  patterns = { ...DEFAULT_PATTERNS };
+  if (!customPatterns || typeof customPatterns !== 'object') return;
+
+  for (const [category, regexList] of Object.entries(customPatterns)) {
+    if (!Array.isArray(regexList)) continue;
+
+    const compiled = [];
+    for (const p of regexList) {
+      const re = safeRegExp(p);
+      if (re) {
+        compiled.push(re);
+      } else {
+        try {
+          console.warn('[Zest] Rejected unsafe pattern:', p);
+        } catch (_) { /* no-op */ }
+      }
+    }
+    patterns[category] = compiled;
+  }
+}
+
+/**
+ * Get current patterns
+ */
+export function getPatterns() {
+  return { ...patterns };
+}
+
+/**
+ * Determine category for a cookie/storage key name
+ * @param {string} name - Cookie or storage key name
+ * @returns {string} Category ID (defaults to 'marketing' for unknown)
+ */
+export function getCategoryForName(name) {
+  for (const [category, regexList] of Object.entries(patterns)) {
+    if (regexList.some(regex => regex.test(name))) {
+      return category;
+    }
+  }
+  // Unknown items default to marketing (strictest)
+  return 'marketing';
+}
+
+/**
+ * Parse cookie string to extract name
+ * @param {string} cookieString - Full cookie string (e.g., "name=value; path=/")
+ * @returns {string|null} Cookie name or null
+ */
+export function parseCookieName(cookieString) {
+  const match = cookieString.match(/^([^=]+)/);
+  return match ? match[1].trim() : null;
+}