@freshjuice/zest 1.0.0 → 2.1.0

package/src/types/zest.headless.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Type definitions for `@freshjuice/zest/headless`.
+ *
+ * The headless build ships the consent engine without any UI: no Shadow
+ * DOM, no styles, no DOM mounting. You bring your own banner / modal /
+ * settings markup and call into Zest for the consent state.
+ *
+ * @example
+ * ```ts
+ * import Zest from '@freshjuice/zest/headless';
+ *
+ * Zest.init({ respectDNT: true, expiration: 365 });
+ *
+ * if (!Zest.hasConsentDecision()) myBanner.show();
+ *
+ * acceptBtn.addEventListener('click', () => Zest.acceptAll());
+ * rejectBtn.addEventListener('click', () => Zest.rejectAll());
+ * ```
+ */
+
+/** 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';
+
+/**
+ * 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()`. */
+export interface InitOptions {
+  /** Respect Do Not Track / Global Privacy Control. Default `true`. */
+  respectDNT?: boolean;
+  /** What to do when DNT/GPC is on. Default `'reject'`. */
+  dntBehavior?: DNTBehavior;
+  /** Cookie expiration in days. Default `365`. */
+  expiration?: number;
+  /** Consumer callbacks. */
+  callbacks?: ZestCallbacks;
+  /** Anything else — Zest tolerates unknown keys at runtime. */
+  [key: string]: unknown;
+}
+
+/** Event names emitted on the `window` `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 the consent-change event. */
+export interface ZestEventDetail {
+  consent: ConsentState;
+  previous?: ConsentState;
+}
+
+declare const Zest: {
+  /** Initialise the consent engine. Must be called before any other API. */
+  init(options?: InitOptions): InitSnapshot;
+
+  /** 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 (accept, reject, or
+   * partial)? */
+  hasConsentDecision(): boolean;
+
+  /** Tamper-evident snapshot of the last consent decision. */
+  getConsentProof(): ConsentProof | null;
+
+  /** Grant consent for every category. */
+  acceptAll(): ConsentState | null;
+
+  /** Revoke consent for every non-essential category. */
+  rejectAll(): ConsentState | null;
+
+  /** Set per-category consent. Missing keys are left untouched. */
+  updateConsent(
+    selections: Partial<Record<ConsentCategory, boolean>>
+  ): ConsentState | null;
+
+  /** Wipe all consent state. Useful for "I changed my mind" flows. */
+  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;
+
+// Named tree-shake-friendly exports.
+export const init: typeof Zest.init;
+export const acceptAll: typeof Zest.acceptAll;
+export const rejectAll: typeof Zest.rejectAll;
+export const updateConsent: typeof Zest.updateConsent;
+export const reset: typeof Zest.reset;
+export const getConsent: typeof Zest.getConsent;
+export const hasConsent: typeof Zest.hasConsent;
+export const hasConsentDecision: typeof Zest.hasConsentDecision;
+export const getConsentProof: typeof Zest.getConsentProof;
+export const isDoNotTrackEnabled: typeof Zest.isDoNotTrackEnabled;
+export const getDNTDetails: typeof Zest.getDNTDetails;
+export const on: typeof Zest.on;
+export const once: typeof Zest.once;
+export const EVENTS: ZestEvents;
+export const getConfig: typeof Zest.getConfig;

package/src/ui/banner.js

@@ -4,30 +4,34 @@
 
 import { generateStyles } from './styles.js';
 import { getCurrentConfig } from '../config/parser.js';
+import { escapeHTML } from '../core/security.js';
 
 let bannerElement = null;
 let shadowRoot = 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>

package/src/ui/modal.js

@@ -5,6 +5,7 @@
 import { generateStyles } from './styles.js';
 import { getCurrentConfig } from '../config/parser.js';
 import { DEFAULT_CATEGORIES } from '../core/categories.js';
+import { escapeHTML, safeUrl } from '../core/security.js';
 
 let modalElement = null;
 let shadowRoot = null;
@@ -16,22 +17,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>
@@ -55,29 +58,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>

package/src/ui/styles.js

@@ -2,11 +2,18 @@
  * Styles - Shadow DOM encapsulated CSS with theming
  */
 
+import { safeColor, sanitizeCustomStyles } from '../core/security.js';
+
+const DEFAULT_ACCENT = '#4F46E5';
+
 /**
  * Generate CSS with custom properties
  */
 export 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 {
@@ -476,15 +483,29 @@ export 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));

package/src/ui/widget.js

@@ -4,6 +4,7 @@
 
 import { generateStyles, COOKIE_ICON } from './styles.js';
 import { getCurrentConfig } from '../config/parser.js';
+import { escapeHTML } from '../core/security.js';
 
 let widgetElement = null;
 let shadowRoot = null;
@@ -13,10 +14,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>