@freshjuice/zest 1.0.0 → 2.1.0

package/dist/zest.esm.js

@@ -1,7 +1,213 @@
+/**
+ * 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
  */
@@ -50,16 +256,29 @@ const DEFAULT_PATTERNS = {
 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;
   }
 }
 
@@ -96,6 +315,11 @@ function parseCookieName(cookieString) {
 // 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 = [];
 
@@ -165,8 +389,8 @@ function interceptCookies() {
       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,
@@ -175,7 +399,9 @@ function interceptCookies() {
         });
       }
     },
-    configurable: true
+    // configurable: false prevents a later-loaded script from
+    // overriding our descriptor and bypassing the interceptor.
+    configurable: false
   });
 
   return true;
@@ -186,6 +412,10 @@ function interceptCookies() {
  */
 
 
+// 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;
@@ -216,7 +446,7 @@ function createStorageProxy(storage, queue, storageName) {
 
           if (checkConsent$2(category)) {
             target.setItem(key, value);
-          } else {
+          } else if (queue.length < MAX_QUEUE_SIZE$1) {
             queue.push({
               key,
               value,
@@ -401,29 +631,56 @@ const STRICT_TRACKERS = {
 };
 
 /**
- * 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;
 }
 
@@ -470,7 +727,17 @@ function isThirdParty(url) {
  */
 
 
-// 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
@@ -517,55 +784,61 @@ function matchesCustomDomains(url) {
 }
 
 /**
- * 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;
 }
 
 /**
@@ -590,14 +863,17 @@ function blockScript(script) {
     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()
   };
 
@@ -608,77 +884,61 @@ function blockScript(script) {
   // 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);
-    }
-  });
 }
 
 /**
@@ -1692,18 +1952,18 @@ function getConfig() {
 /**
  * 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;
 }
 
 /**
@@ -1714,6 +1974,20 @@ function getCurrentConfig() {
 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;
 
@@ -1742,7 +2016,12 @@ function getRawCookie() {
 }
 
 /**
- * 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 {
@@ -1750,9 +2029,12 @@ function loadConsent() {
     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
@@ -1777,7 +2059,7 @@ function saveConsent(expirationDays = 365) {
   };
 
   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);
 }
@@ -1846,7 +2128,7 @@ function rejectAll(expirationDays = 365) {
  * 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;
 }
 
@@ -1871,7 +2153,8 @@ function getConsentProof() {
     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
@@ -1950,15 +2233,207 @@ function emitHide(type = 'banner') {
   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 {
@@ -2428,15 +2903,29 @@ function generateStyles(config) {
 .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));
@@ -2457,26 +2946,29 @@ const COOKIE_ICON = `<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"
 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>
@@ -2586,22 +3078,24 @@ let currentSelections = {};
 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>
@@ -2625,29 +3119,30 @@ function createModalHTML(config, consent) {
     ))
     .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>
@@ -2779,10 +3274,11 @@ let shadowRoot = null;
  */
 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>
@@ -2861,114 +3357,59 @@ function removeWidget() {
 
 /**
  * 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();
@@ -2985,17 +3426,17 @@ function handleShowSettings() {
 }
 
 /**
- * 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,
@@ -3005,103 +3446,37 @@ function handleCloseModal() {
 }
 
 /**
- * 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;
     }
@@ -3122,7 +3497,7 @@ const Zest = {
 
   // Settings modal
   showSettings() {
-    if (!initialized) {
+    if (!isInitialized()) {
       console.warn('[Zest] Not initialized. Call Zest.init() first.');
       return;
     }
@@ -3134,19 +3509,19 @@ const Zest = {
     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;
     }
@@ -3154,20 +3529,19 @@ const Zest = {
   },
 
   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,
@@ -3177,17 +3551,30 @@ const Zest = {
     }
   },
 
-  // 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();