@freshjuice/zest 0.1.0 → 2.0.0

package/src/core/script-blocker.js

@@ -0,0 +1,314 @@
+/**
+ * Script Blocker - Blocks and manages consent-gated scripts
+ *
+ * Modes:
+ * - manual: Only blocks scripts with data-consent-category attribute
+ * - safe: Manual + known major trackers (Google, Facebook, etc.)
+ * - strict: Safe + extended tracker list (Hotjar, Mixpanel, etc.)
+ * - doomsday: Block ALL third-party scripts
+ */
+
+import { getCategoryForScript, isThirdParty } from './known-trackers.js';
+
+// Categories the author has declared blockable. A script can self-label
+// into one of these, but not into 'essential' (a common bypass).
+const BLOCKABLE_CATEGORIES = new Set(['functional', 'analytics', 'marketing']);
+
+// Upper bound on queued scripts awaiting consent replay — prevents a
+// hostile page from flooding the queue with <script> nodes.
+const MAX_QUEUE_SIZE = 500;
+
+// Queue for blocked scripts — the authoritative source for replay,
+// snapshotting src/inline BEFORE any DOM mutation so later tampering
+// cannot hijack what gets executed.
+const scriptQueue = [];
+
+// MutationObserver instance
+let observer = null;
+
+// Current blocking mode
+let blockingMode = 'safe';
+
+// Custom blocked domains (user-defined)
+let customBlockedDomains = [];
+
+// Reference to consent checker function
+let checkConsent = () => false;
+
+/**
+ * Set the consent checker function
+ */
+export function setConsentChecker(fn) {
+  checkConsent = fn;
+}
+
+/**
+ * Set blocking mode
+ */
+export function setBlockingMode(mode) {
+  blockingMode = mode;
+}
+
+/**
+ * Set custom blocked domains
+ */
+export function setCustomBlockedDomains(domains) {
+  customBlockedDomains = domains || [];
+}
+
+/**
+ * Get queued scripts
+ */
+export function getScriptQueue() {
+  return [...scriptQueue];
+}
+
+/**
+ * Clear the script queue
+ */
+export function clearScriptQueue() {
+  scriptQueue.length = 0;
+}
+
+/**
+ * Check if script URL matches custom blocked domains
+ */
+function matchesCustomDomains(url) {
+  if (!url || customBlockedDomains.length === 0) return null;
+
+  try {
+    const hostname = new URL(url).hostname.toLowerCase();
+
+    for (const entry of customBlockedDomains) {
+      const domain = typeof entry === 'string' ? entry : entry.domain;
+      const category = typeof entry === 'string' ? 'marketing' : (entry.category || 'marketing');
+
+      if (hostname === domain || hostname.endsWith('.' + domain)) {
+        return category;
+      }
+    }
+  } catch (e) {
+    // Invalid URL
+  }
+
+  return null;
+}
+
+/**
+ * Determine if a script should be blocked and get its category.
+ *
+ * A self-applied 'essential' label is ignored — only explicit blockable
+ * categories are accepted. That prevents a third-party script from
+ * stamping itself with data-consent-category="essential" to slip past
+ * mode-based blocking.
+ */
+function getScriptBlockCategory(script) {
+  // Skip if script has data-zest-allow attribute (opt-out)
+  if (script.hasAttribute('data-zest-allow')) {
+    return null;
+  }
+
+  // 1. Check for explicit data-consent-category attribute.
+  // Only honor values from the blockable set; 'essential' and unknown
+  // values fall through to the other checks.
+  const explicitCategory = script.getAttribute('data-consent-category');
+  const explicitBlockable = explicitCategory && BLOCKABLE_CATEGORIES.has(explicitCategory)
+    ? explicitCategory
+    : null;
+
+  const src = script.src;
+
+  // No src = inline script, only block if explicitly tagged (blockable only)
+  if (!src) {
+    return explicitBlockable;
+  }
+
+  // 2. Check custom blocked domains
+  const customCategory = matchesCustomDomains(src);
+
+  // 3. Mode-based blocking
+  let modeCategory = null;
+  switch (blockingMode) {
+    case 'manual':
+      break;
+
+    case 'safe':
+    case 'strict':
+      modeCategory = getCategoryForScript(src, blockingMode);
+      break;
+
+    case 'doomsday':
+      if (isThirdParty(src)) {
+        modeCategory = getCategoryForScript(src, 'strict') || 'marketing';
+      }
+      break;
+
+    default:
+      break;
+  }
+
+  // Use the strictest category among explicit/custom/mode decisions.
+  // We collect all categories the script matches and pick the first
+  // that appears in the blockable set (any match wins — but we prefer
+  // the mode-assigned one since it's authoritative for third-party
+  // trackers that try to self-label as 'functional').
+  return modeCategory || customCategory || explicitBlockable;
+}
+
+/**
+ * Block a script element
+ */
+function blockScript(script) {
+  // Skip already processed scripts
+  if (script.hasAttribute('data-zest-processed')) {
+    return false;
+  }
+
+  const category = getScriptBlockCategory(script);
+
+  if (!category) {
+    script.setAttribute('data-zest-processed', 'allowed');
+    return false;
+  }
+
+  if (checkConsent(category)) {
+    // Consent already given - allow script
+    script.setAttribute('data-zest-processed', 'allowed');
+    return false;
+  }
+
+  // Store script info for later execution. Snapshot the src/text BEFORE
+  // mutating the DOM — this snapshot is the authoritative replay source
+  // so later DOM tampering cannot hijack the replayed script URL.
+  const scriptInfo = {
+    category,
+    src: script.src || '',
+    inline: script.textContent,
+    type: script.type,
+    async: script.async,
+    defer: script.defer,
+    element: script,
+    timestamp: Date.now()
+  };
+
+  // Mark as processed
+  script.setAttribute('data-zest-processed', 'blocked');
+  script.setAttribute('data-consent-category', category);
+
+  // Disable the script
+  script.type = 'text/plain';
+
+  // Remove src to prevent loading. We no longer stash it on the element
+  // (data-blocked-src was a tampering vector); scriptQueue is the single
+  // source of truth for replay.
+  if (script.src) {
+    script.removeAttribute('src');
+  }
+
+  if (scriptQueue.length < MAX_QUEUE_SIZE) {
+    scriptQueue.push(scriptInfo);
+  }
+  return true;
+}
+
+/**
+ * Replay queued scripts for allowed categories.
+ *
+ * scriptQueue is the single source of truth for src and inline body —
+ * we never re-read data-* attributes from the DOM (which an attacker
+ * could have rewritten in the intervening time).
+ */
+export function replayScripts(allowedCategories) {
+  const remaining = [];
+
+  for (const scriptInfo of scriptQueue) {
+    if (!allowedCategories.includes(scriptInfo.category)) {
+      remaining.push(scriptInfo);
+      continue;
+    }
+
+    const newScript = document.createElement('script');
+    if (scriptInfo.src) {
+      newScript.src = scriptInfo.src;
+    } else if (scriptInfo.inline) {
+      newScript.textContent = scriptInfo.inline;
+    }
+    if (scriptInfo.async) newScript.async = true;
+    if (scriptInfo.defer) newScript.defer = true;
+    if (scriptInfo.type && scriptInfo.type !== 'text/plain') {
+      newScript.type = scriptInfo.type;
+    }
+    newScript.setAttribute('data-zest-processed', 'executed');
+    newScript.setAttribute('data-consent-executed', 'true');
+
+    // If the original element is still in the DOM, replace it in place
+    // so execution order is preserved. Otherwise append to <head>.
+    const original = scriptInfo.element;
+    if (original && original.isConnected && original.parentNode) {
+      original.parentNode.replaceChild(newScript, original);
+    } else {
+      document.head.appendChild(newScript);
+    }
+  }
+
+  scriptQueue.length = 0;
+  scriptQueue.push(...remaining);
+}
+
+/**
+ * Process existing scripts in the DOM
+ */
+function processExistingScripts() {
+  const scripts = document.querySelectorAll('script:not([data-zest-processed])');
+  scripts.forEach(blockScript);
+}
+
+/**
+ * Handle mutations (new scripts added to DOM)
+ */
+function handleMutations(mutations) {
+  for (const mutation of mutations) {
+    for (const node of mutation.addedNodes) {
+      if (node.nodeName === 'SCRIPT' && !node.hasAttribute('data-zest-processed')) {
+        blockScript(node);
+      }
+
+      // Check child scripts
+      if (node.querySelectorAll) {
+        const scripts = node.querySelectorAll('script:not([data-zest-processed])');
+        scripts.forEach(blockScript);
+      }
+    }
+  }
+}
+
+/**
+ * Start observing for new scripts
+ */
+export function startScriptBlocking(mode = 'safe', customDomains = []) {
+  blockingMode = mode;
+  customBlockedDomains = customDomains;
+
+  // Process existing scripts
+  processExistingScripts();
+
+  // Watch for new scripts
+  observer = new MutationObserver(handleMutations);
+
+  observer.observe(document.documentElement, {
+    childList: true,
+    subtree: true
+  });
+
+  return true;
+}
+
+/**
+ * Stop observing for new scripts
+ */
+export function stopScriptBlocking() {
+  if (observer) {
+    observer.disconnect();
+    observer = null;
+  }
+}

package/src/core/security.js

@@ -0,0 +1,204 @@
+/**
+ * Security utilities - escaping, validation, and safe parsing helpers
+ *
+ * These helpers are used across UI components, URL/CSS validation, and
+ * consent-cookie parsing to provide defense-in-depth against untrusted
+ * config (CMS-driven, i18n-loaded, or attacker-supplied).
+ */
+
+const HTML_ESCAPE_MAP = {
+  '&': '&',
+  '<': '&lt;',
+  '>': '&gt;',
+  '"': '&quot;',
+  "'": '&#39;',
+  '`': '&#96;'
+};
+
+/**
+ * Escape a value for safe embedding in HTML text nodes and attribute values.
+ * Accepts any value — non-strings are stringified first. null/undefined -> ''.
+ */
+export function escapeHTML(value) {
+  if (value === null || value === undefined) return '';
+  const str = typeof value === 'string' ? value : String(value);
+  return str.replace(/[&<>"'`]/g, (ch) => HTML_ESCAPE_MAP[ch]);
+}
+
+/**
+ * Validate a URL — return the URL if it uses http:/https:/mailto:/tel:,
+ * otherwise return null. Blocks javascript:, data:, vbscript:, file:, etc.
+ */
+export function safeUrl(url) {
+  if (typeof url !== 'string' || url.length === 0) return null;
+  const trimmed = url.trim();
+  if (trimmed.length === 0) return null;
+
+  // Relative URLs (no protocol) are safe — treat as same-origin path
+  if (/^[/?#]/.test(trimmed)) return trimmed;
+
+  // Check protocol explicitly, do NOT rely on URL parsing alone —
+  // attackers may use whitespace/control characters to confuse parsers.
+  const match = trimmed.match(/^([a-z][a-z0-9+.-]*):/i);
+  if (!match) {
+    // No protocol — treat as relative
+    return trimmed;
+  }
+
+  const protocol = match[1].toLowerCase();
+  if (protocol === 'http' || protocol === 'https' || protocol === 'mailto' || protocol === 'tel') {
+    return trimmed;
+  }
+  return null;
+}
+
+/**
+ * Validate a CSS color value. Accepts #rgb/#rrggbb/#rrggbbaa and a
+ * small allowlist of CSS named colors and rgb()/rgba()/hsl()/hsla()
+ * functional forms with numeric-only arguments.
+ */
+const NAMED_COLORS = new Set([
+  'transparent', 'black', 'white', 'red', 'green', 'blue', 'yellow',
+  'orange', 'purple', 'pink', 'gray', 'grey', 'brown', 'cyan', 'magenta',
+  'silver', 'gold', 'navy', 'teal', 'maroon', 'olive', 'lime', 'aqua',
+  'fuchsia', 'indigo', 'violet', 'crimson', 'coral', 'salmon', 'tomato'
+]);
+
+export function safeColor(color) {
+  if (typeof color !== 'string') return null;
+  const trimmed = color.trim();
+
+  if (/^#[0-9a-fA-F]{3,8}$/.test(trimmed)) return trimmed;
+  if (NAMED_COLORS.has(trimmed.toLowerCase())) return trimmed;
+
+  // Functional notations: only digits, dots, commas, %, whitespace between parens
+  if (/^(rgb|rgba|hsl|hsla)\(\s*[\d.,%\s/]+\s*\)$/i.test(trimmed)) return trimmed;
+
+  return null;
+}
+
+/**
+ * Validate a regex pattern string. Rejects patterns that contain known
+ * catastrophic-backtracking shapes (nested quantifiers). Compiles with
+ * try/catch.
+ *
+ * Returns a RegExp on success, null on failure.
+ */
+const REDOS_PATTERNS = [
+  /(\([^)]*[+*][^)]*\)|\[[^\]]*\]|\\w|\\d|\\s)\s*[+*]/, // nested quantifier
+  /\(\?[=!][^)]*[+*][^)]*\)[+*]/, // lookahead with quantifier, then quantifier
+];
+
+export function safeRegExp(pattern, flags) {
+  if (pattern instanceof RegExp) return pattern;
+  if (typeof pattern !== 'string') return null;
+
+  // Cap pattern length to limit compiled-regex state
+  if (pattern.length > 500) return null;
+
+  // Heuristic: reject obviously dangerous patterns
+  for (const bad of REDOS_PATTERNS) {
+    if (bad.test(pattern)) return null;
+  }
+
+  try {
+    return new RegExp(pattern, flags);
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * Sanitize a consent-cookie payload. Only known category keys with
+ * boolean values survive; prototype-polluting keys are stripped.
+ */
+const FORBIDDEN_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
+export function sanitizeConsentPayload(raw, knownCategoryIds) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+
+  const result = {
+    version: typeof raw.version === 'string' ? raw.version : null,
+    timestamp: typeof raw.timestamp === 'number' && Number.isFinite(raw.timestamp) ? raw.timestamp : null,
+    categories: {}
+  };
+
+  const cats = raw.categories;
+  if (!cats || typeof cats !== 'object' || Array.isArray(cats)) return null;
+
+  for (const key of knownCategoryIds) {
+    if (FORBIDDEN_KEYS.has(key)) continue;
+    if (Object.prototype.hasOwnProperty.call(cats, key)) {
+      result.categories[key] = cats[key] === true;
+    }
+  }
+
+  // essential is always true regardless of stored value
+  if (knownCategoryIds.includes('essential')) {
+    result.categories.essential = true;
+  }
+
+  return result;
+}
+
+/**
+ * Invoke a user-supplied callback, swallowing and logging exceptions so
+ * a misbehaving callback can't break the consent flow.
+ */
+export function safeInvoke(fn, ...args) {
+  if (typeof fn !== 'function') return undefined;
+  try {
+    return fn(...args);
+  } catch (e) {
+    try {
+      console.error('[Zest] User callback threw:', e);
+    } catch (_) {
+      /* no-op */
+    }
+    return undefined;
+  }
+}
+
+/**
+ * Strip comments and selector-level content from a customStyles string
+ * while still allowing property/value declarations scoped under the
+ * component selectors the author is targeting. We cannot fully sandbox
+ * CSS without a parser, but we can at least neutralise the most
+ * dangerous clickjacking vector (rules targeting Zest's own buttons).
+ *
+ * Returns the sanitized CSS string (possibly empty).
+ */
+export function sanitizeCustomStyles(css) {
+  if (typeof css !== 'string' || css.length === 0) return '';
+
+  // Hard cap on size to avoid runaway payloads
+  if (css.length > 20000) return '';
+
+  // Remove CSS comments (can hide payloads)
+  let out = css.replace(/\/\*[\s\S]*?\*\//g, '');
+
+  // Block at-rules that can load external resources or alter behavior
+  out = out.replace(/@import\s+[^;]+;?/gi, '');
+  out = out.replace(/@charset\s+[^;]+;?/gi, '');
+
+  // Block url() values pointing outside of data: or https:
+  out = out.replace(/url\(\s*(['"]?)([^)'"]+)\1\s*\)/gi, (match, quote, value) => {
+    const v = value.trim().toLowerCase();
+    if (v.startsWith('https:') || v.startsWith('data:image/') || v.startsWith('/') || v.startsWith('#')) {
+      return match;
+    }
+    return 'url(#)';
+  });
+
+  // Block selectors that target the built-in reject button, which could
+  // be used to hide it for clickjacking consent bypass.
+  out = out.replace(/\.zest-btn--secondary\s*\{[^}]*\}/gi, '');
+  out = out.replace(/\[data-action\s*=\s*["']reject-all["']\]\s*\{[^}]*\}/gi, '');
+  out = out.replace(/\[data-action\s*=\s*["']accept-all["']\]\s*\{[^}]*\}/gi, '');
+
+  // Block expression() (ancient IE) and -moz-binding (ancient FF)
+  out = out.replace(/expression\s*\([^)]*\)/gi, '');
+  out = out.replace(/-moz-binding\s*:[^;}]*/gi, '');
+
+  return out;
+}

package/src/core/storage-interceptor.js

@@ -0,0 +1,173 @@
+/**
+ * Storage Interceptor - Intercepts localStorage and sessionStorage operations
+ */
+
+import { getCategoryForName } from './pattern-matcher.js';
+
+// Upper bound on queued operations awaiting consent replay — unbounded
+// growth would be a memory-exhaustion DoS vector.
+const MAX_QUEUE_SIZE = 200;
+
+// Store originals
+let originalLocalStorage = null;
+let originalSessionStorage = null;
+
+// Queues for blocked operations
+const localStorageQueue = [];
+const sessionStorageQueue = [];
+
+// Reference to consent checker function
+let checkConsent = () => false;
+
+/**
+ * Set the consent checker function
+ */
+export function setConsentChecker(fn) {
+  checkConsent = fn;
+}
+
+/**
+ * Get original localStorage
+ */
+export function getOriginalLocalStorage() {
+  return originalLocalStorage;
+}
+
+/**
+ * Get original sessionStorage
+ */
+export function getOriginalSessionStorage() {
+  return originalSessionStorage;
+}
+
+/**
+ * Get queued localStorage operations
+ */
+export function getLocalStorageQueue() {
+  return [...localStorageQueue];
+}
+
+/**
+ * Get queued sessionStorage operations
+ */
+export function getSessionStorageQueue() {
+  return [...sessionStorageQueue];
+}
+
+/**
+ * Clear storage queues
+ */
+export function clearStorageQueues() {
+  localStorageQueue.length = 0;
+  sessionStorageQueue.length = 0;
+}
+
+/**
+ * Create a proxy for storage API
+ */
+function createStorageProxy(storage, queue, storageName) {
+  return new Proxy(storage, {
+    get(target, prop) {
+      if (prop === 'setItem') {
+        return (key, value) => {
+          const category = getCategoryForName(key);
+
+          if (checkConsent(category)) {
+            target.setItem(key, value);
+          } else if (queue.length < MAX_QUEUE_SIZE) {
+            queue.push({
+              key,
+              value,
+              category,
+              timestamp: Date.now()
+            });
+          }
+        };
+      }
+
+      // Allow all other operations
+      const val = target[prop];
+      return typeof val === 'function' ? val.bind(target) : val;
+    }
+  });
+}
+
+/**
+ * Replay queued storage operations for allowed categories
+ */
+export function replayStorage(allowedCategories) {
+  // Replay localStorage
+  const remainingLocal = [];
+  for (const item of localStorageQueue) {
+    if (allowedCategories.includes(item.category)) {
+      originalLocalStorage?.setItem(item.key, item.value);
+    } else {
+      remainingLocal.push(item);
+    }
+  }
+  localStorageQueue.length = 0;
+  localStorageQueue.push(...remainingLocal);
+
+  // Replay sessionStorage
+  const remainingSession = [];
+  for (const item of sessionStorageQueue) {
+    if (allowedCategories.includes(item.category)) {
+      originalSessionStorage?.setItem(item.key, item.value);
+    } else {
+      remainingSession.push(item);
+    }
+  }
+  sessionStorageQueue.length = 0;
+  sessionStorageQueue.push(...remainingSession);
+}
+
+/**
+ * Start intercepting storage APIs
+ */
+export function interceptStorage() {
+  try {
+    originalLocalStorage = window.localStorage;
+    originalSessionStorage = window.sessionStorage;
+
+    Object.defineProperty(window, 'localStorage', {
+      value: createStorageProxy(originalLocalStorage, localStorageQueue, 'localStorage'),
+      configurable: true,
+      writable: false
+    });
+
+    Object.defineProperty(window, 'sessionStorage', {
+      value: createStorageProxy(originalSessionStorage, sessionStorageQueue, 'sessionStorage'),
+      configurable: true,
+      writable: false
+    });
+
+    return true;
+  } catch (e) {
+    console.warn('[Zest] Could not intercept storage APIs:', e);
+    return false;
+  }
+}
+
+/**
+ * Restore original storage APIs
+ */
+export function restoreStorage() {
+  try {
+    if (originalLocalStorage) {
+      Object.defineProperty(window, 'localStorage', {
+        value: originalLocalStorage,
+        configurable: true,
+        writable: false
+      });
+    }
+    if (originalSessionStorage) {
+      Object.defineProperty(window, 'sessionStorage', {
+        value: originalSessionStorage,
+        configurable: true,
+        writable: false
+      });
+    }
+  } catch (e) {
+    console.warn('[Zest] Could not restore storage APIs:', e);
+  }
+}