@freshjuice/zest 1.0.0 → 2.0.0

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

@@ -4,6 +4,10 @@
 
 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;
@@ -70,7 +74,7 @@ function createStorageProxy(storage, queue, storageName) {
 
           if (checkConsent(category)) {
             target.setItem(key, value);
-          } else {
+          } else if (queue.length < MAX_QUEUE_SIZE) {
             queue.push({
               key,
               value,

package/src/core-lifecycle.js

@@ -0,0 +1,192 @@
+/**
+ * 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.
+ */
+
+import { interceptCookies, setConsentChecker as setCookieChecker, replayCookies } from './core/cookie-interceptor.js';
+import { interceptStorage, setConsentChecker as setStorageChecker, replayStorage } from './core/storage-interceptor.js';
+import { startScriptBlocking, setConsentChecker as setScriptChecker, replayScripts } from './core/script-blocker.js';
+import { setPatterns } from './core/pattern-matcher.js';
+import { getCategoryIds } from './core/categories.js';
+import { isDoNotTrackEnabled } from './core/dnt.js';
+import { safeInvoke } from './core/security.js';
+
+import { applyConsentSignals } from './integrations/consent-signals.js';
+
+import { setConfig } from './config/parser.js';
+
+import {
+  loadConsent,
+  hasConsent,
+  updateConsent,
+  acceptAll as storeAcceptAll,
+  rejectAll as storeRejectAll,
+  resetConsent,
+  hasConsentDecision
+} from './storage/consent-store.js';
+import { emitReady, emitConsent, emitReject, emitChange } from './storage/events.js';
+
+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.
+ */
+export 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(
+    { essential: true, functional: false, analytics: false, marketing: false },
+    currentConfig,
+    true
+  );
+
+  if (currentConfig.patterns) {
+    setPatterns(currentConfig.patterns);
+  }
+
+  setCookieChecker(checkConsent);
+  setStorageChecker(checkConsent);
+  setScriptChecker(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 = storeRejectAll(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.
+ */
+export function coreAcceptAll() {
+  if (!initialized) return null;
+  const result = storeAcceptAll(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.
+ */
+export function coreRejectAll() {
+  if (!initialized) return null;
+  const result = storeRejectAll(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.
+ */
+export 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.
+ */
+export function coreReset() {
+  resetConsent();
+}
+
+export function isInitialized() {
+  return initialized;
+}
+
+export function getActiveConfig() {
+  return currentConfig;
+}

package/src/headless.js

@@ -0,0 +1,133 @@
+/**
+ * Zest Headless - consent logic only, zero UI.
+ *
+ * Use this entry when you want to bring your own banner / modal / settings
+ * markup and style it with your own CSS. No Shadow DOM is mounted, no
+ * inline stylesheet is injected, and nothing is attached to `window`.
+ *
+ * Everything you need to wire a custom UI is here:
+ *
+ *   import Zest from '@freshjuice/zest/headless';
+ *
+ *   Zest.init({ mode: 'safe', respectDNT: true });
+ *
+ *   if (!Zest.hasConsentDecision()) {
+ *     myBanner.show();
+ *   }
+ *
+ *   myAcceptBtn.addEventListener('click', () => Zest.acceptAll());
+ *   myRejectBtn.addEventListener('click', () => Zest.rejectAll());
+ *   mySaveBtn.addEventListener('click', () => {
+ *     Zest.updateConsent({ analytics: true, marketing: false });
+ *   });
+ *
+ *   Zest.on(Zest.EVENTS.CHANGE, (e) => console.log(e.detail.consent));
+ *
+ * The headless build does NOT auto-initialize. You must call `init()`
+ * yourself, so you control exactly when interceptors come online.
+ */
+
+import {
+  coreInit,
+  coreAcceptAll,
+  coreRejectAll,
+  coreUpdateConsent,
+  coreReset,
+  isInitialized,
+  getActiveConfig
+} from './core-lifecycle.js';
+
+import {
+  getConsent,
+  hasConsent,
+  hasConsentDecision,
+  getConsentProof
+} from './storage/consent-store.js';
+
+import { isDoNotTrackEnabled, getDNTDetails } from './core/dnt.js';
+
+import { EVENTS, on, once } from './storage/events.js';
+
+function init(userConfig = {}) {
+  const snapshot = coreInit(userConfig);
+  // Headless returns the snapshot so callers can decide whether to
+  // render their banner / settings UI based on hasDecision / dntApplied.
+  return snapshot;
+}
+
+function acceptAll() {
+  if (!isInitialized()) {
+    console.warn('[Zest] Not initialized. Call Zest.init() first.');
+    return null;
+  }
+  return coreAcceptAll();
+}
+
+function rejectAll() {
+  if (!isInitialized()) {
+    console.warn('[Zest] Not initialized. Call Zest.init() first.');
+    return null;
+  }
+  return coreRejectAll();
+}
+
+function updateConsent(selections) {
+  if (!isInitialized()) {
+    console.warn('[Zest] Not initialized. Call Zest.init() first.');
+    return null;
+  }
+  return coreUpdateConsent(selections);
+}
+
+function reset() {
+  coreReset();
+}
+
+const Zest = {
+  init,
+
+  // Consent state
+  getConsent,
+  hasConsent,
+  hasConsentDecision,
+  getConsentProof,
+
+  // Actions
+  acceptAll,
+  rejectAll,
+  updateConsent,
+  reset,
+
+  // DNT introspection
+  isDoNotTrackEnabled,
+  getDNTDetails,
+
+  // Events
+  on,
+  once,
+  EVENTS,
+
+  // Config introspection
+  getConfig: getActiveConfig
+};
+
+export default Zest;
+
+// Named exports for tree-shake friendly consumers who only need a slice.
+export {
+  init,
+  acceptAll,
+  rejectAll,
+  updateConsent,
+  reset,
+  getConsent,
+  hasConsent,
+  hasConsentDecision,
+  getConsentProof,
+  isDoNotTrackEnabled,
+  getDNTDetails,
+  on,
+  once,
+  EVENTS,
+  getActiveConfig as getConfig
+};