@freshjuice/zest 1.0.0 → 2.1.0

package/src/index.js

@@ -1,145 +1,88 @@
 /**
  * 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.
  */
 
-// Core
-import { interceptCookies, setConsentChecker as setCookieChecker, replayCookies, getOriginalCookieDescriptor } 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, getDNTDetails } from './core/dnt.js';
-
-// Integrations
-import { applyConsentSignals } from './integrations/consent-signals.js';
-
-// Config
-import { getConfig, setConfig, getCurrentConfig } from './config/parser.js';
-
-// Storage
+// Core lifecycle (UI-agnostic)
+import {
+  coreInit,
+  coreAcceptAll,
+  coreRejectAll,
+  coreUpdateConsent,
+  coreReset,
+  isInitialized,
+  getActiveConfig
+} from './core-lifecycle.js';
+
+// Consent store + events
 import {
-  loadConsent,
   getConsent,
   hasConsent,
-  updateConsent,
-  acceptAll as storeAcceptAll,
-  rejectAll as storeRejectAll,
-  resetConsent,
   hasConsentDecision,
   getConsentProof
 } from './storage/consent-store.js';
-import { emitReady, emitConsent, emitReject, emitChange, emitShow, emitHide, EVENTS } from './storage/events.js';
+import { emitShow, emitHide, EVENTS, on, once } from './storage/events.js';
+
+// DNT introspection
+import { isDoNotTrackEnabled, getDNTDetails } from './core/dnt.js';
+
+// Config getters
+import { getConfig, getCurrentConfig } from './config/parser.js';
 
 // UI
 import { showBanner, hideBanner, isBannerVisible } from './ui/banner.js';
 import { showModal, hideModal, isModalVisible } from './ui/modal.js';
 import { showWidget, hideWidget, removeWidget, isWidgetVisible } from './ui/widget.js';
 
-// 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 = storeAcceptAll(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 = storeRejectAll(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();
@@ -156,17 +99,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,
@@ -176,103 +119,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(
-    { essential: true, functional: false, analytics: false, marketing: false },
-    config,
-    true
-  );
-
-  // Set patterns if provided
-  if (config.patterns) {
-    setPatterns(config.patterns);
-  }
-
-  // Set up consent checkers
-  setCookieChecker(checkConsent);
-  setStorageChecker(checkConsent);
-  setScriptChecker(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 = storeRejectAll(config.expiration);
-      dntApplied = true;
+  const config = getActiveConfig();
 
-      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);
-
-  // 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;
     }
@@ -293,7 +170,7 @@ const Zest = {
 
   // Settings modal
   showSettings() {
-    if (!initialized) {
+    if (!isInitialized()) {
       console.warn('[Zest] Not initialized. Call Zest.init() first.');
       return;
     }
@@ -305,19 +182,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;
     }
@@ -325,20 +202,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,
@@ -348,17 +224,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();

package/src/storage/consent-store.js

@@ -2,12 +2,27 @@
  * Consent Store - Manages consent state persistence
  */
 
-import { getDefaultConsent } from '../core/categories.js';
+import { getDefaultConsent, getCategoryIds } from '../core/categories.js';
 import { getOriginalCookieDescriptor } from '../core/cookie-interceptor.js';
+import { sanitizeConsentPayload } from '../core/security.js';
 
 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;
 
@@ -36,7 +51,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.
  */
 export function loadConsent() {
   try {
@@ -44,9 +64,12 @@ export 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
@@ -71,7 +94,7 @@ export 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);
 }
@@ -142,7 +165,7 @@ export function rejectAll(expirationDays = 365) {
  * Reset consent (clear cookie)
  */
 export 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;
 }
 
@@ -167,7 +190,8 @@ export 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

package/src/types/zest.d.ts

@@ -0,0 +1,214 @@
+/**
+ * Type definitions for `@freshjuice/zest` (full build with UI).
+ *
+ * The full build ships the consent engine plus a Shadow-DOM banner,
+ * settings modal, and floating widget. It auto-initialises on script
+ * load when included via `<script>`, or you can drive it manually via
+ * `Zest.init()`.
+ *
+ * For a logic-only build without UI, import from
+ * `@freshjuice/zest/headless` instead.
+ *
+ * @example
+ * ```ts
+ * import Zest from '@freshjuice/zest';
+ *
+ * Zest.init({
+ *   position: 'bottom-right',
+ *   theme: 'auto',
+ *   accentColor: '#0071e3',
+ *   policyUrl: '/privacy'
+ * });
+ * ```
+ */
+
+/** Built-in consent categories. */
+export type ConsentCategory =
+  | 'essential'
+  | 'functional'
+  | 'analytics'
+  | 'marketing';
+
+/**
+ * Per-category boolean consent state. `essential` is always `true` —
+ * consent for it cannot be revoked because it covers strictly-necessary
+ * processing.
+ */
+export type ConsentState =
+  & Partial<Record<ConsentCategory, boolean>>
+  & { essential: true };
+
+/** Snapshot returned by `init()`. */
+export interface InitSnapshot {
+  consent: ConsentState;
+  hasDecision: boolean;
+  dntApplied: boolean;
+}
+
+/** Tamper-evident proof of the user's last consent decision. */
+export interface ConsentProof {
+  version: string;
+  timestamp: number;
+  categories: ConsentState;
+}
+
+/** Output of `getDNTDetails()`. */
+export interface DNTDetails {
+  dnt: boolean;
+  gpc: boolean;
+  doNotTrack: string | null;
+  globalPrivacyControl: boolean;
+}
+
+/** Behaviour when DNT / GPC is detected at init time. */
+export type DNTBehavior = 'reject' | 'preselect' | 'ignore';
+
+/** Banner position on the page. */
+export type BannerPosition = 'bottom' | 'bottom-left' | 'bottom-right' | 'top';
+
+/** UI theme. `auto` follows `prefers-color-scheme`. */
+export type ZestTheme = 'light' | 'dark' | 'auto';
+
+/** Script-blocking strictness. */
+export type ZestMode = 'manual' | 'safe' | 'strict' | 'doomsday';
+
+/**
+ * Optional consumer callbacks. Each is wrapped in a try/catch internally
+ * so a thrown error never breaks the consent pipeline.
+ */
+export interface ZestCallbacks {
+  onAccept?: (consent: ConsentState) => void;
+  onReject?: (consent: ConsentState) => void;
+  onChange?: (consent: ConsentState) => void;
+  onReady?: (consent: ConsentState) => void;
+}
+
+/** Configuration accepted by `init()` and `window.ZestConfig`. */
+export interface InitOptions {
+  /** Display language. `'auto'` detects from `<html lang>` / browser. */
+  lang?:
+    | 'auto'
+    | 'en' | 'de' | 'es' | 'fr' | 'it' | 'pt'
+    | 'nl' | 'pl' | 'uk' | 'ru' | 'ja' | 'zh';
+  /** Banner position. Default `'bottom'`. */
+  position?: BannerPosition;
+  /** UI theme. Default `'auto'`. */
+  theme?: ZestTheme;
+  /** Hex accent color for buttons (e.g. `'#0071e3'`). */
+  accentColor?: string;
+  /** Link to the host site's privacy policy. */
+  policyUrl?: string;
+  /** Show floating "manage cookies" widget after a decision. Default `true`. */
+  showWidget?: boolean;
+  /** Cookie expiration in days. Default `365`. */
+  expiration?: number;
+  /** Script-blocking mode. Default `'safe'`. */
+  mode?: ZestMode;
+  /** Auto-initialise on script load. Default `true` for the UI build. */
+  autoInit?: boolean;
+  /** Respect Do Not Track / Global Privacy Control. Default `true`. */
+  respectDNT?: boolean;
+  /** What to do when DNT/GPC is on. Default `'reject'`. */
+  dntBehavior?: DNTBehavior;
+  /** Consumer callbacks. */
+  callbacks?: ZestCallbacks;
+  /** Anything else — Zest tolerates unknown keys at runtime. */
+  [key: string]: unknown;
+}
+
+/** Event names emitted on `document.documentElement`. */
+export interface ZestEvents {
+  READY: 'zest:ready';
+  CONSENT: 'zest:consent';
+  REJECT: 'zest:reject';
+  CHANGE: 'zest:change';
+  SHOW: 'zest:show';
+  HIDE: 'zest:hide';
+}
+
+export type ZestEventName = ZestEvents[keyof ZestEvents];
+
+/** Detail payload of consent events. */
+export interface ZestEventDetail {
+  consent: ConsentState;
+  previous?: ConsentState;
+}
+
+declare const Zest: {
+  /** Initialise. Auto-called when the script loads unless `autoInit: false`. */
+  init(options?: InitOptions): InitSnapshot;
+
+  /** Show the consent banner. */
+  show(): void;
+
+  /** Hide the consent banner. */
+  hide(): void;
+
+  /** Open the per-category settings modal. */
+  showSettings(): void;
+
+  /** Close the settings modal. */
+  hideSettings(): void;
+
+  /** Show the persistent "manage cookies" widget. */
+  showWidget(): void;
+
+  /** Hide the widget without removing it. */
+  hideWidget(): void;
+
+  /** Current consent state (clone, safe to mutate). */
+  getConsent(): ConsentState;
+
+  /** Has the user granted consent for `category`? */
+  hasConsent(category: ConsentCategory): boolean;
+
+  /** Has the user made any consent decision yet? */
+  hasConsentDecision(): boolean;
+
+  /** Tamper-evident snapshot of the last consent decision. */
+  getConsentProof(): ConsentProof | null;
+
+  /** Grant consent for every category and run accept callbacks. */
+  acceptAll(): void;
+
+  /** Revoke consent for every non-essential category and run reject callbacks. */
+  rejectAll(): void;
+
+  /** Wipe all consent state and reshow the banner. */
+  reset(): void;
+
+  /** True if the browser is sending DNT or GPC. */
+  isDoNotTrackEnabled(): boolean;
+
+  /** Why `isDoNotTrackEnabled()` returned what it did. */
+  getDNTDetails(): DNTDetails;
+
+  /** Subscribe to a consent event. Returns an unsubscribe function. */
+  on(
+    eventName: ZestEventName,
+    handler: (event: CustomEvent<ZestEventDetail>) => void
+  ): () => void;
+
+  /** Subscribe once; auto-unsubscribes after the first call. */
+  once(
+    eventName: ZestEventName,
+    handler: (event: CustomEvent<ZestEventDetail>) => void
+  ): () => void;
+
+  /** Constants for `on()` / `once()`. */
+  EVENTS: ZestEvents;
+
+  /** Active configuration after `init()`. */
+  getConfig(): InitOptions | null;
+};
+
+export default Zest;
+
+declare global {
+  interface Window {
+    /** Set before loading `zest.min.js` to configure auto-initialisation. */
+    ZestConfig?: InitOptions;
+    /** The Zest singleton, attached after auto-init. */
+    Zest?: typeof Zest;
+  }
+}