@freshjuice/zest 1.0.0 → 2.1.0

package/dist/zest.js

@@ -1,10 +1,216 @@
 var Zest = (function () {
   'use strict';
 
+  /**
+   * 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 -> ''.
+   */
+  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.
+   */
+  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'
+  ]);
+
+  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
+  ];
+
+  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']);
+
+  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.
+   */
+  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).
+   */
+  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;
+  }
+
   /**
    * Pattern Matcher - Categorizes cookies and storage keys by pattern
    */
 
+
   /**
    * Default patterns for each category
    */
@@ -53,16 +259,29 @@ var Zest = (function () {
   let patterns = { ...DEFAULT_PATTERNS };
 
   /**
-   * Set custom 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.
    */
   function setPatterns(customPatterns) {
     patterns = { ...DEFAULT_PATTERNS };
+    if (!customPatterns || typeof customPatterns !== 'object') return;
+
     for (const [category, regexList] of Object.entries(customPatterns)) {
-      if (Array.isArray(regexList)) {
-        patterns[category] = regexList.map(p =>
-          p instanceof RegExp ? p : new RegExp(p)
-        );
+      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;
     }
   }
 
@@ -99,6 +318,11 @@ var Zest = (function () {
   // 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$2 = 100;
+
   // Queue for blocked cookies
   const cookieQueue = [];
 
@@ -168,8 +392,8 @@ var Zest = (function () {
         if (checkConsent$3(category)) {
           // Consent given - set cookie
           originalCookieDescriptor.set.call(document, value);
-        } else {
-          // No consent - queue for later
+        } else if (cookieQueue.length < MAX_QUEUE_SIZE$2) {
+          // No consent - queue for later (capped to prevent DoS)
           cookieQueue.push({
             value,
             name,
@@ -178,7 +402,9 @@ var Zest = (function () {
           });
         }
       },
-      configurable: true
+      // configurable: false prevents a later-loaded script from
+      // overriding our descriptor and bypassing the interceptor.
+      configurable: false
     });
 
     return true;
@@ -189,6 +415,10 @@ var Zest = (function () {
    */
 
 
+  // Upper bound on queued operations awaiting consent replay — unbounded
+  // growth would be a memory-exhaustion DoS vector.
+  const MAX_QUEUE_SIZE$1 = 200;
+
   // Store originals
   let originalLocalStorage = null;
   let originalSessionStorage = null;
@@ -219,7 +449,7 @@ var Zest = (function () {
 
             if (checkConsent$2(category)) {
               target.setItem(key, value);
-            } else {
+            } else if (queue.length < MAX_QUEUE_SIZE$1) {
               queue.push({
                 key,
                 value,
@@ -404,29 +634,56 @@ var Zest = (function () {
   };
 
   /**
-   * Check if a URL matches any tracker in the list
+   * 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
    */
   function matchesTrackerList(url, trackerList) {
+    let urlObj;
     try {
-      const urlObj = new URL(url);
-      const hostname = urlObj.hostname.toLowerCase();
-      const fullUrl = url.toLowerCase();
-
-      for (const domain of trackerList) {
-        // Support partial matches (e.g., "matomo." matches "analytics.matomo.cloud")
-        if (domain.endsWith('.')) {
-          if (hostname.includes(domain.slice(0, -1))) {
-            return true;
-          }
-        } else if (hostname === domain || hostname.endsWith('.' + domain)) {
+      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;
-        } else if (fullUrl.includes(domain)) {
+        }
+        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;
       }
-    } catch (e) {
-      // Invalid URL
     }
+
     return false;
   }
 
@@ -473,7 +730,17 @@ var Zest = (function () {
    */
 
 
-  // Queue for blocked scripts
+  // 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
@@ -520,55 +787,61 @@ var Zest = (function () {
   }
 
   /**
-   * Determine if a script should be blocked and get its category
+   * 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) {
-    // 1. Check for explicit data-consent-category attribute (always respected)
-    const explicitCategory = script.getAttribute('data-consent-category');
-    if (explicitCategory) {
-      return explicitCategory;
-    }
-
-    // 2. Skip if script has data-zest-allow attribute
+    // 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
+    // No src = inline script, only block if explicitly tagged (blockable only)
     if (!src) {
-      return null;
+      return explicitBlockable;
     }
 
-    // 3. Check custom blocked domains
+    // 2. Check custom blocked domains
     const customCategory = matchesCustomDomains(src);
-    if (customCategory) {
-      return customCategory;
-    }
 
-    // 4. Mode-based blocking
+    // 3. Mode-based blocking
+    let modeCategory = null;
     switch (blockingMode) {
       case 'manual':
-        // Only explicit tags, already checked above
-        return null;
+        break;
 
       case 'safe':
       case 'strict':
-        // Check against known tracker lists
-        return getCategoryForScript(src, blockingMode);
+        modeCategory = getCategoryForScript(src, blockingMode);
+        break;
 
       case 'doomsday':
-        // Block all third-party scripts
         if (isThirdParty(src)) {
-          // Try to categorize, default to marketing
-          return getCategoryForScript(src, 'strict') || 'marketing';
+          modeCategory = getCategoryForScript(src, 'strict') || 'marketing';
         }
-        return null;
-
-      default:
-        return null;
+        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;
   }
 
   /**
@@ -593,14 +866,17 @@ var Zest = (function () {
       return false;
     }
 
-    // Store script info for later execution
+    // 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,
+      src: script.src || '',
       inline: script.textContent,
       type: script.type,
       async: script.async,
       defer: script.defer,
+      element: script,
       timestamp: Date.now()
     };
 
@@ -611,77 +887,61 @@ var Zest = (function () {
     // Disable the script
     script.type = 'text/plain';
 
-    // If it has a src, also remove it to prevent loading
+    // 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.setAttribute('data-blocked-src', script.src);
       script.removeAttribute('src');
     }
 
-    scriptQueue.push(scriptInfo);
-    return true;
-  }
-
-  /**
-   * Execute a queued script
-   */
-  function executeScript(scriptInfo) {
-    const script = document.createElement('script');
-
-    if (scriptInfo.src) {
-      script.src = scriptInfo.src;
-    } else if (scriptInfo.inline) {
-      script.textContent = scriptInfo.inline;
+    if (scriptQueue.length < MAX_QUEUE_SIZE) {
+      scriptQueue.push(scriptInfo);
     }
-
-    if (scriptInfo.async) script.async = true;
-    if (scriptInfo.defer) script.defer = true;
-
-    script.setAttribute('data-zest-processed', 'executed');
-    script.setAttribute('data-consent-executed', 'true');
-
-    document.head.appendChild(script);
+    return true;
   }
 
   /**
-   * Replay queued scripts for allowed categories
+   * 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).
    */
   function replayScripts(allowedCategories) {
     const remaining = [];
 
     for (const scriptInfo of scriptQueue) {
-      if (allowedCategories.includes(scriptInfo.category)) {
-        executeScript(scriptInfo);
-      } else {
+      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);
-
-    // Also re-enable any blocked scripts in the DOM
-    const blockedScripts = document.querySelectorAll('script[data-zest-processed="blocked"]');
-    blockedScripts.forEach(script => {
-      const category = script.getAttribute('data-consent-category');
-      if (allowedCategories.includes(category)) {
-        // Clone and replace to execute
-        const newScript = document.createElement('script');
-
-        const blockedSrc = script.getAttribute('data-blocked-src');
-        if (blockedSrc) {
-          newScript.src = blockedSrc;
-        } else {
-          newScript.textContent = script.textContent;
-        }
-
-        if (script.async) newScript.async = true;
-        if (script.defer) newScript.defer = true;
-
-        newScript.setAttribute('data-zest-processed', 'executed');
-        newScript.setAttribute('data-consent-executed', 'true');
-        script.parentNode?.replaceChild(newScript, script);
-      }
-    });
   }
 
   /**
@@ -1695,18 +1955,18 @@ var Zest = (function () {
   /**
    * Update configuration at runtime
    */
-  let currentConfig = null;
+  let currentConfig$1 = null;
 
   function setConfig(config) {
-    currentConfig = mergeConfig(config);
-    return currentConfig;
+    currentConfig$1 = mergeConfig(config);
+    return currentConfig$1;
   }
 
   function getCurrentConfig() {
-    if (!currentConfig) {
-      currentConfig = getConfig();
+    if (!currentConfig$1) {
+      currentConfig$1 = getConfig();
     }
-    return currentConfig;
+    return currentConfig$1;
   }
 
   /**
@@ -1717,6 +1977,20 @@ var Zest = (function () {
   const COOKIE_NAME = 'zest_consent';
   const CONSENT_VERSION = '1.0';
 
+  /**
+   * Return the Secure flag fragment when running over HTTPS, empty otherwise.
+   * On HTTPS sites, omitting Secure lets the cookie leak over plain HTTP.
+   */
+  function secureAttribute() {
+    try {
+      return typeof location !== 'undefined' && location.protocol === 'https:'
+        ? '; Secure'
+        : '';
+    } catch (_) {
+      return '';
+    }
+  }
+
   // Current consent state
   let consent = null;
 
@@ -1745,7 +2019,12 @@ var Zest = (function () {
   }
 
   /**
-   * Load consent from cookie
+   * Load consent from cookie.
+   *
+   * The parsed cookie is validated against the expected schema via
+   * sanitizeConsentPayload — only known category keys with boolean values
+   * survive, so a tampered cookie can't inject prototype-polluting props
+   * or unexpected category shapes.
    */
   function loadConsent() {
     try {
@@ -1753,9 +2032,12 @@ var Zest = (function () {
       const match = cookies.match(new RegExp(`${COOKIE_NAME}=([^;]+)`));
 
       if (match) {
-        const data = JSON.parse(decodeURIComponent(match[1]));
-        consent = data.categories || getDefaultConsent();
-        return { ...consent };
+        const raw = JSON.parse(decodeURIComponent(match[1]));
+        const clean = sanitizeConsentPayload(raw, getCategoryIds());
+        if (clean && clean.categories) {
+          consent = { ...getDefaultConsent(), ...clean.categories };
+          return { ...consent };
+        }
       }
     } catch (e) {
       // Invalid or missing cookie
@@ -1780,7 +2062,7 @@ var Zest = (function () {
     };
 
     const expires = new Date(Date.now() + expirationDays * 24 * 60 * 60 * 1000).toUTCString();
-    const cookieValue = `${COOKIE_NAME}=${encodeURIComponent(JSON.stringify(data))}; expires=${expires}; path=/; SameSite=Lax`;
+    const cookieValue = `${COOKIE_NAME}=${encodeURIComponent(JSON.stringify(data))}; expires=${expires}; path=/; SameSite=Lax${secureAttribute()}`;
 
     setRawCookie(cookieValue);
   }
@@ -1849,7 +2131,7 @@ var Zest = (function () {
    * Reset consent (clear cookie)
    */
   function resetConsent() {
-    setRawCookie(`${COOKIE_NAME}=; expires=Thu, 01 Jan 1970 00:00:00 GMT; path=/`);
+    setRawCookie(`${COOKIE_NAME}=; expires=Thu, 01 Jan 1970 00:00:00 GMT; path=/; SameSite=Lax${secureAttribute()}`);
     consent = null;
   }
 
@@ -1874,7 +2156,8 @@ var Zest = (function () {
       const match = cookies.match(new RegExp(`${COOKIE_NAME}=([^;]+)`));
 
       if (match) {
-        return JSON.parse(decodeURIComponent(match[1]));
+        const raw = JSON.parse(decodeURIComponent(match[1]));
+        return sanitizeConsentPayload(raw, getCategoryIds());
       }
     } catch (e) {
       // Invalid cookie
@@ -1953,15 +2236,207 @@ var Zest = (function () {
     return emit(EVENTS.HIDE, { type });
   }
 
+  /**
+   * Subscribe to an event
+   */
+  function on(eventName, callback) {
+    document.addEventListener(eventName, callback);
+    return () => document.removeEventListener(eventName, callback);
+  }
+
+  /**
+   * Subscribe to an event once
+   */
+  function once(eventName, callback) {
+    document.addEventListener(eventName, callback, { once: true });
+  }
+
+  /**
+   * Core lifecycle - UI-agnostic initialization and consent actions.
+   *
+   * This module contains everything the main entry (with UI) and the
+   * headless entry (no UI) share: interceptor setup, consent load/save,
+   * replay, DNT handling, and the events/callbacks fan-out. It intentionally
+   * does NOT import anything from `./ui/*` so tree-shakers can drop the UI
+   * bundle entirely when only the headless API is used.
+   */
+
+
+  let initialized = false;
+  let currentConfig = null;
+
+  function checkConsent(category) {
+    return hasConsent(category);
+  }
+
+  function replayAll(categories) {
+    replayCookies(categories);
+    replayStorage(categories);
+    replayScripts(categories);
+  }
+
+  /**
+   * Run the non-UI half of init. Returns a snapshot the caller (UI or
+   * headless) can use to decide what to do next.
+   */
+  function coreInit(userConfig = {}) {
+    if (initialized) {
+      return {
+        alreadyInitialized: true,
+        config: currentConfig,
+        consent: loadConsent(),
+        hasDecision: hasConsentDecision(),
+        dntApplied: false
+      };
+    }
+
+    currentConfig = setConfig(userConfig);
+
+    // Push default-denied state to vendor consent mode APIs BEFORE any
+    // third-party script has a chance to fire.
+    applyConsentSignals(
+      { functional: false, analytics: false, marketing: false },
+      currentConfig,
+      true
+    );
+
+    if (currentConfig.patterns) {
+      setPatterns(currentConfig.patterns);
+    }
+
+    setConsentChecker$2(checkConsent);
+    setConsentChecker$1(checkConsent);
+    setConsentChecker(checkConsent);
+
+    interceptCookies();
+    interceptStorage();
+    startScriptBlocking(currentConfig.mode, currentConfig.blockedDomains);
+
+    const consent = loadConsent();
+    initialized = true;
+
+    if (hasConsentDecision()) {
+      applyConsentSignals(consent, currentConfig, false);
+    }
+
+    // DNT / GPC handling — if the user signalled opt-out at the browser
+    // level and the site opts to respect it, auto-reject before the UI
+    // layer ever runs.
+    const dntEnabled = isDoNotTrackEnabled();
+    let dntApplied = false;
+
+    if (dntEnabled && currentConfig.respectDNT && currentConfig.dntBehavior !== 'ignore') {
+      if (currentConfig.dntBehavior === 'reject' && !hasConsentDecision()) {
+        const result = rejectAll(currentConfig.expiration);
+        dntApplied = true;
+        applyConsentSignals(result.current, currentConfig, false);
+        emitReject(result.current);
+        emitChange(result.current, result.previous);
+        safeInvoke(currentConfig.callbacks?.onReject);
+        safeInvoke(currentConfig.callbacks?.onChange, result.current);
+      }
+    }
+
+    emitReady(consent);
+    safeInvoke(currentConfig.callbacks?.onReady, consent);
+
+    return {
+      alreadyInitialized: false,
+      config: currentConfig,
+      consent,
+      hasDecision: hasConsentDecision(),
+      dntApplied
+    };
+  }
+
+  /**
+   * Accept all categories, replay queued items, fire events + callbacks.
+   * Returns { current, previous } or null if not yet initialized.
+   */
+  function coreAcceptAll() {
+    if (!initialized) return null;
+    const result = acceptAll(currentConfig.expiration);
+    applyConsentSignals(result.current, currentConfig, false);
+    replayAll(getCategoryIds());
+    emitConsent(result.current, result.previous);
+    emitChange(result.current, result.previous);
+    safeInvoke(currentConfig.callbacks?.onAccept, result.current);
+    safeInvoke(currentConfig.callbacks?.onChange, result.current);
+    return result;
+  }
+
+  /**
+   * Reject all non-essential categories, fire events + callbacks.
+   */
+  function coreRejectAll() {
+    if (!initialized) return null;
+    const result = rejectAll(currentConfig.expiration);
+    applyConsentSignals(result.current, currentConfig, false);
+    emitReject(result.current);
+    emitChange(result.current, result.previous);
+    safeInvoke(currentConfig.callbacks?.onReject);
+    safeInvoke(currentConfig.callbacks?.onChange, result.current);
+    return result;
+  }
+
+  /**
+   * Save custom selections and replay only the newly-allowed categories.
+   */
+  function coreUpdateConsent(selections) {
+    if (!initialized) return null;
+    const result = updateConsent(selections, currentConfig.expiration);
+    applyConsentSignals(result.current, currentConfig, false);
+
+    const newlyAllowed = Object.keys(result.current).filter(
+      (cat) => result.current[cat] && !result.previous[cat]
+    );
+    if (newlyAllowed.length > 0) {
+      replayAll(newlyAllowed);
+    }
+
+    const hasNonEssential = Object.entries(selections || {}).some(
+      ([cat, val]) => cat !== 'essential' && val
+    );
+    if (hasNonEssential) {
+      emitConsent(result.current, result.previous);
+    } else {
+      emitReject(result.current);
+    }
+    emitChange(result.current, result.previous);
+    safeInvoke(currentConfig.callbacks?.onChange, result.current);
+    return result;
+  }
+
+  /**
+   * Clear the consent cookie. The caller is responsible for any UI reset.
+   */
+  function coreReset() {
+    resetConsent();
+  }
+
+  function isInitialized() {
+    return initialized;
+  }
+
+  function getActiveConfig() {
+    return currentConfig;
+  }
+
   /**
    * Styles - Shadow DOM encapsulated CSS with theming
    */
 
+
+  const DEFAULT_ACCENT = '#4F46E5';
+
   /**
    * Generate CSS with custom properties
    */
   function generateStyles(config) {
-    const accentColor = config.accentColor || '#4F46E5';
+    // Only accept colors that pass strict validation — an unvalidated
+    // value is a CSS-injection vector (e.g. `red; } * { display:none; /*`).
+    const accentColor = safeColor(config.accentColor) || DEFAULT_ACCENT;
+    const customCss = sanitizeCustomStyles(config.customStyles);
 
     return `
 :host {
@@ -2431,15 +2906,29 @@ var Zest = (function () {
 .zest-hidden {
   display: none !important;
 }
-${config.customStyles || ''}
+${customCss}
 `;
   }
 
   /**
-   * Adjust color brightness
+   * Adjust color brightness. Falls back to the default accent if the input
+   * cannot be parsed as a hex color (non-hex inputs pass safeColor but
+   * can't be brightness-shifted mathematically).
    */
   function adjustColor(hex, percent) {
-    const num = parseInt(hex.replace('#', ''), 16);
+    if (typeof hex !== 'string' || !/^#[0-9a-fA-F]{3,8}$/.test(hex.trim())) {
+      hex = DEFAULT_ACCENT;
+    }
+    let clean = hex.trim().replace('#', '');
+    // Expand 3-digit form to 6
+    if (clean.length === 3) {
+      clean = clean.split('').map(c => c + c).join('');
+    }
+    // Strip alpha if present
+    if (clean.length === 8) clean = clean.slice(0, 6);
+    if (clean.length !== 6) clean = DEFAULT_ACCENT.slice(1);
+
+    const num = parseInt(clean, 16);
     const amt = Math.round(2.55 * percent);
     const R = Math.min(255, Math.max(0, (num >> 16) + amt));
     const G = Math.min(255, Math.max(0, ((num >> 8) & 0x00ff) + amt));
@@ -2460,26 +2949,29 @@ ${config.customStyles || ''}
   let bannerElement = null;
   let shadowRoot$2 = null;
 
+  const SAFE_POSITIONS = new Set(['bottom', 'bottom-left', 'bottom-right', 'top']);
+
   /**
    * Create the banner HTML
    */
   function createBannerHTML(config) {
     const labels = config.labels.banner;
-    const position = config.position || 'bottom';
+    const rawPosition = config.position || 'bottom';
+    const position = SAFE_POSITIONS.has(rawPosition) ? rawPosition : 'bottom';
 
     return `
-    <div class="zest-banner zest-banner--${position}" role="dialog" aria-modal="false" aria-label="${labels.title}">
-      <h2 class="zest-banner__title">${labels.title}</h2>
-      <p class="zest-banner__description">${labels.description}</p>
+    <div class="zest-banner zest-banner--${position}" role="dialog" aria-modal="false" aria-label="${escapeHTML(labels.title)}">
+      <h2 class="zest-banner__title">${escapeHTML(labels.title)}</h2>
+      <p class="zest-banner__description">${escapeHTML(labels.description)}</p>
       <div class="zest-banner__buttons">
         <button type="button" class="zest-btn zest-btn--primary" data-action="accept-all">
-          ${labels.acceptAll}
+          ${escapeHTML(labels.acceptAll)}
         </button>
         <button type="button" class="zest-btn zest-btn--secondary" data-action="reject-all">
-          ${labels.rejectAll}
+          ${escapeHTML(labels.rejectAll)}
         </button>
         <button type="button" class="zest-btn zest-btn--ghost" data-action="settings">
-          ${labels.settings}
+          ${escapeHTML(labels.settings)}
         </button>
       </div>
     </div>
@@ -2589,22 +3081,24 @@ ${config.customStyles || ''}
   function createCategoryHTML(category, isChecked, isRequired) {
     const disabled = isRequired ? 'disabled' : '';
     const checked = isChecked ? 'checked' : '';
+    const safeId = escapeHTML(category.id);
+    const safeLabel = escapeHTML(category.label);
 
     return `
     <div class="zest-category">
       <div class="zest-category__header">
         <div class="zest-category__info">
-          <span class="zest-category__label">${category.label}</span>
-          <p class="zest-category__description">${category.description}</p>
+          <span class="zest-category__label">${safeLabel}</span>
+          <p class="zest-category__description">${escapeHTML(category.description)}</p>
         </div>
         <label class="zest-toggle">
           <input
             type="checkbox"
             class="zest-toggle__input"
-            data-category="${category.id}"
+            data-category="${safeId}"
             ${checked}
             ${disabled}
-            aria-label="${category.label}"
+            aria-label="${safeLabel}"
           >
           <span class="zest-toggle__slider"></span>
         </label>
@@ -2628,29 +3122,30 @@ ${config.customStyles || ''}
       ))
       .join('');
 
-    const policyLink = config.policyUrl
-      ? `<a href="${config.policyUrl}" class="zest-link" target="_blank" rel="noopener">Privacy Policy</a>`
+    const validatedPolicyUrl = config.policyUrl ? safeUrl(config.policyUrl) : null;
+    const policyLink = validatedPolicyUrl
+      ? `<a href="${escapeHTML(validatedPolicyUrl)}" class="zest-link" target="_blank" rel="noopener noreferrer">Privacy Policy</a>`
       : '';
 
     return `
-    <div class="zest-modal-overlay" role="dialog" aria-modal="true" aria-label="${labels.title}">
+    <div class="zest-modal-overlay" role="dialog" aria-modal="true" aria-label="${escapeHTML(labels.title)}">
       <div class="zest-modal">
         <div class="zest-modal__header">
-          <h2 class="zest-modal__title">${labels.title}</h2>
-          <p class="zest-modal__description">${labels.description} ${policyLink}</p>
+          <h2 class="zest-modal__title">${escapeHTML(labels.title)}</h2>
+          <p class="zest-modal__description">${escapeHTML(labels.description)} ${policyLink}</p>
         </div>
         <div class="zest-modal__body">
           ${categoriesHTML}
         </div>
         <div class="zest-modal__footer">
           <button type="button" class="zest-btn zest-btn--primary" data-action="save">
-            ${labels.save}
+            ${escapeHTML(labels.save)}
           </button>
           <button type="button" class="zest-btn zest-btn--secondary" data-action="accept-all">
-            ${labels.acceptAll}
+            ${escapeHTML(labels.acceptAll)}
           </button>
           <button type="button" class="zest-btn zest-btn--ghost" data-action="reject-all">
-            ${labels.rejectAll}
+            ${escapeHTML(labels.rejectAll)}
           </button>
         </div>
       </div>
@@ -2782,10 +3277,11 @@ ${config.customStyles || ''}
    */
   function createWidgetHTML(config) {
     const labels = config.labels.widget;
+    const safeLabel = escapeHTML(labels.label);
 
     return `
     <div class="zest-widget">
-      <button type="button" class="zest-widget__btn" aria-label="${labels.label}" title="${labels.label}">
+      <button type="button" class="zest-widget__btn" aria-label="${safeLabel}" title="${safeLabel}">
         <span class="zest-widget__icon">${COOKIE_ICON}</span>
       </button>
     </div>
@@ -2864,114 +3360,59 @@ ${config.customStyles || ''}
 
   /**
    * Zest - Lightweight Cookie Consent Toolkit
-   * Main entry point
+   * Main entry (full build: logic + UI).
+   *
+   * For a logic-only build without any CSS / Shadow DOM mounting, import
+   * from `@freshjuice/zest/headless` instead.
    */
 
 
-  // State
-  let initialized = false;
-  let config = null;
-
   /**
-   * Consent checker function shared across interceptors
-   */
-  function checkConsent(category) {
-    return hasConsent(category);
-  }
-
-  /**
-   * Replay all queued items for newly allowed categories
-   */
-  function replayAll(allowedCategories) {
-    replayCookies(allowedCategories);
-    replayStorage(allowedCategories);
-    replayScripts(allowedCategories);
-  }
-
-  /**
-   * Handle accept all
+   * Handle accept all — delegates consent logic to core, handles UI swap.
    */
   function handleAcceptAll() {
-    const result = acceptAll(config.expiration);
-    const categories = getCategoryIds();
-
-    applyConsentSignals(result.current, config, false);
+    coreAcceptAll();
+    const config = getActiveConfig();
 
     hideBanner();
     hideModal();
 
-    replayAll(categories);
-
-    if (config.showWidget) {
+    if (config?.showWidget) {
       showWidget({ onClick: handleShowSettings });
     }
-
-    emitConsent(result.current, result.previous);
-    emitChange(result.current, result.previous);
-    config.callbacks?.onAccept?.(result.current);
-    config.callbacks?.onChange?.(result.current);
   }
 
   /**
-   * Handle reject all
+   * Handle reject all.
    */
   function handleRejectAll() {
-    const result = rejectAll(config.expiration);
-
-    applyConsentSignals(result.current, config, false);
+    coreRejectAll();
+    const config = getActiveConfig();
 
     hideBanner();
     hideModal();
 
-    if (config.showWidget) {
+    if (config?.showWidget) {
       showWidget({ onClick: handleShowSettings });
     }
-
-    emitReject(result.current);
-    emitChange(result.current, result.previous);
-    config.callbacks?.onReject?.();
-    config.callbacks?.onChange?.(result.current);
   }
 
   /**
-   * Handle save preferences from modal
+   * Handle save preferences from modal.
    */
   function handleSavePreferences(selections) {
-    const result = updateConsent(selections, config.expiration);
-
-    applyConsentSignals(result.current, config, false);
-
-    // Find newly allowed categories
-    const newlyAllowed = Object.keys(result.current).filter(
-      cat => result.current[cat] && !result.previous[cat]
-    );
-
-    if (newlyAllowed.length > 0) {
-      replayAll(newlyAllowed);
-    }
+    coreUpdateConsent(selections);
+    const config = getActiveConfig();
 
     hideModal();
 
-    if (config.showWidget) {
+    if (config?.showWidget) {
       showWidget({ onClick: handleShowSettings });
     }
-
-    // Determine if this was acceptance or rejection based on selections
-    const hasNonEssential = Object.entries(selections)
-      .some(([cat, val]) => cat !== 'essential' && val);
-
-    if (hasNonEssential) {
-      emitConsent(result.current, result.previous);
-    } else {
-      emitReject(result.current);
-    }
-
-    emitChange(result.current, result.previous);
-    config.callbacks?.onChange?.(result.current);
   }
 
   /**
-   * Handle show settings
+   * Open the settings modal.
    */
   function handleShowSettings() {
     hideBanner();
@@ -2988,17 +3429,17 @@ ${config.customStyles || ''}
   }
 
   /**
-   * Handle close modal
+   * Close the modal — either bring the widget back (decision made) or
+   * fall back to the banner (no decision yet).
    */
   function handleCloseModal() {
     hideModal();
     emitHide('modal');
 
-    // Show widget if consent was already given
-    if (hasConsentDecision() && config.showWidget) {
+    const config = getActiveConfig();
+    if (hasConsentDecision() && config?.showWidget) {
       showWidget({ onClick: handleShowSettings });
     } else {
-      // Show banner again if no decision made
       showBanner({
         onAcceptAll: handleAcceptAll,
         onRejectAll: handleRejectAll,
@@ -3008,103 +3449,37 @@ ${config.customStyles || ''}
   }
 
   /**
-   * Initialize Zest
+   * Initialize Zest with UI.
    */
   function init(userConfig = {}) {
-    if (initialized) {
+    const { alreadyInitialized, consent, hasDecision, dntApplied } = coreInit(userConfig);
+    if (alreadyInitialized) {
       console.warn('[Zest] Already initialized');
       return Zest;
     }
 
-    // Merge config
-    config = setConfig(userConfig);
-
-    // Push default denied state to vendor consent mode APIs (must happen before scripts load)
-    applyConsentSignals(
-      { functional: false, analytics: false, marketing: false },
-      config,
-      true
-    );
-
-    // Set patterns if provided
-    if (config.patterns) {
-      setPatterns(config.patterns);
-    }
-
-    // Set up consent checkers
-    setConsentChecker$2(checkConsent);
-    setConsentChecker$1(checkConsent);
-    setConsentChecker(checkConsent);
-
-    // Start interception
-    interceptCookies();
-    interceptStorage();
-    startScriptBlocking(config.mode, config.blockedDomains);
-
-    // Load saved consent
-    const consent = loadConsent();
-
-    initialized = true;
-
-    // Push update for returning visitors with saved consent
-    if (hasConsentDecision()) {
-      applyConsentSignals(consent, config, false);
-    }
-
-    // Check Do Not Track / Global Privacy Control
-    const dntEnabled = isDoNotTrackEnabled();
-    let dntApplied = false;
-
-    if (dntEnabled && config.respectDNT && config.dntBehavior !== 'ignore') {
-      if (config.dntBehavior === 'reject' && !hasConsentDecision()) {
-        // Auto-reject non-essential cookies silently
-        const result = rejectAll(config.expiration);
-        dntApplied = true;
-
-        applyConsentSignals(result.current, config, false);
-
-        // Emit events
-        emitReject(result.current);
-        emitChange(result.current, result.previous);
-        config.callbacks?.onReject?.();
-        config.callbacks?.onChange?.(result.current);
-      }
-      // 'preselect' behavior is handled by default (banner shows with defaults off)
-    }
-
-    // Emit ready event
-    emitReady(consent);
-    config.callbacks?.onReady?.(consent);
+    const config = getActiveConfig();
 
-    // Show UI based on consent state
-    if (!hasConsentDecision() && !dntApplied) {
-      // No consent decision yet - show banner
+    if (!hasDecision && !dntApplied) {
       showBanner({
         onAcceptAll: handleAcceptAll,
         onRejectAll: handleRejectAll,
         onSettings: handleShowSettings
       });
       emitShow('banner');
-    } else {
-      // Consent already given (or DNT auto-rejected) - show widget for reopening settings
-      if (config.showWidget) {
-        showWidget({ onClick: handleShowSettings });
-      }
+    } else if (config?.showWidget) {
+      showWidget({ onClick: handleShowSettings });
     }
 
     return Zest;
   }
 
-  /**
-   * Public API
-   */
   const Zest = {
-    // Initialization
     init,
 
     // Banner control
     show() {
-      if (!initialized) {
+      if (!isInitialized()) {
         console.warn('[Zest] Not initialized. Call Zest.init() first.');
         return;
       }
@@ -3125,7 +3500,7 @@ ${config.customStyles || ''}
 
     // Settings modal
     showSettings() {
-      if (!initialized) {
+      if (!isInitialized()) {
         console.warn('[Zest] Not initialized. Call Zest.init() first.');
         return;
       }
@@ -3137,19 +3512,19 @@ ${config.customStyles || ''}
       emitHide('modal');
     },
 
-    // Consent management
+    // Consent state
     getConsent,
     hasConsent,
     hasConsentDecision,
     getConsentProof,
 
-    // DNT detection
+    // DNT
     isDoNotTrackEnabled,
     getDNTDetails,
 
-    // Accept/Reject programmatically
+    // Programmatic accept / reject
     acceptAll() {
-      if (!initialized) {
+      if (!isInitialized()) {
         console.warn('[Zest] Not initialized. Call Zest.init() first.');
         return;
       }
@@ -3157,20 +3532,19 @@ ${config.customStyles || ''}
     },
 
     rejectAll() {
-      if (!initialized) {
+      if (!isInitialized()) {
         console.warn('[Zest] Not initialized. Call Zest.init() first.');
         return;
       }
       handleRejectAll();
     },
 
-    // Reset and show banner again
+    // Reset everything and reshow the banner
     reset() {
-      resetConsent();
+      coreReset();
       hideModal();
       removeWidget();
-
-      if (initialized) {
+      if (isInitialized()) {
         showBanner({
           onAcceptAll: handleAcceptAll,
           onRejectAll: handleRejectAll,
@@ -3180,17 +3554,30 @@ ${config.customStyles || ''}
       }
     },
 
-    // Config
+    // Config introspection
     getConfig: getCurrentConfig,
 
     // Events
+    on,
+    once,
     EVENTS
   };
 
   // Auto-init if config present
   if (typeof window !== 'undefined') {
-    // Make Zest available globally
-    window.Zest = Zest;
+    // Make Zest available globally. defineProperty with writable:false +
+    // configurable:false stops a later-loaded script from replacing the
+    // global with a trojanned stand-in.
+    try {
+      Object.defineProperty(window, 'Zest', {
+        value: Object.freeze(Zest),
+        writable: false,
+        configurable: false,
+        enumerable: true
+      });
+    } catch (e) {
+      window.Zest = Zest;
+    }
 
     const autoInit = () => {
       const cfg = getConfig();