@freshjuice/zest 1.0.0 → 2.1.0

package/README.md

@@ -7,11 +7,12 @@
 
 A lightweight cookie consent toolkit for GDPR/CCPA compliance.
 
-- **Lightweight** - ~9KB gzipped (single language) / ~14KB (all 12 languages)
-- **Zero dependencies** - Vanilla JavaScript
-- **Shadow DOM** - Styles isolated from your site
-- **Modern browsers** - No IE11 polyfills needed
-- **Privacy-first** - Respects Do Not Track / Global Privacy Control
+- **Lightweight** — ~9KB gzipped (single language) / ~16KB (all 12 languages) / ~11KB (headless)
+- **Zero dependencies** — Vanilla JavaScript
+- **Shadow DOM** — Styles isolated from your site
+- **Headless mode** — Bring your own UI & CSS, use only the consent engine
+- **Privacy-first** — Respects Do Not Track / Global Privacy Control
+- **Security-hardened** — XSS-safe templating, URL/color/regex validation, locked interceptors
 
 ## Quick Start
 
@@ -23,7 +24,7 @@ A lightweight cookie consent toolkit for GDPR/CCPA compliance.
 <script src="https://cdn.jsdelivr.net/npm/@freshjuice/zest"></script>
 ```
 
-Or with configuration:
+With configuration:
 
 ```html
 <script>
@@ -37,6 +38,23 @@ Or with configuration:
 <script src="https://unpkg.com/@freshjuice/zest"></script>
 ```
 
+As an npm dependency:
+
+```js
+import Zest from '@freshjuice/zest';
+
+Zest.init({ mode: 'safe', policyUrl: '/privacy' });
+```
+
+## Two build flavors
+
+| Entry | What you get | Min / Gzip |
+|---|---|---|
+| `@freshjuice/zest` | Consent engine **+ Shadow DOM UI** (banner, modal, widget) | ~50 KB / **~16 KB** |
+| `@freshjuice/zest/headless` | Consent engine only, **no UI / no CSS** — you build the UI | ~31 KB / **~11 KB** |
+
+Use **headless** when you want full control over markup and styling.
+
 ## Configuration
 
 ### Via `window.ZestConfig`
@@ -49,10 +67,10 @@ window.ZestConfig = {
   // Theme: 'light' | 'dark' | 'auto' (default: 'auto' follows system)
   theme: 'auto',
 
-  // Accent color for buttons
+  // Accent color — must be a valid CSS color (hex, named, rgb/rgba, hsl/hsla)
   accentColor: '#0071e3',
 
-  // Link to privacy policy
+  // Link to privacy policy — only http:/https:/mailto:/tel:/relative allowed
   policyUrl: '/privacy',
 
   // Show floating widget after consent
@@ -61,7 +79,7 @@ window.ZestConfig = {
   // Consent expiration in days
   expiration: 365,
 
-  // Callbacks
+  // Callbacks — wrapped in try/catch internally, safe to throw
   callbacks: {
     onAccept: (consent) => {},
     onReject: () => {},
@@ -86,26 +104,85 @@ window.ZestConfig = {
 ## API
 
 ```javascript
-// Show/hide UI
-Zest.show()           // Show banner
-Zest.hide()           // Hide banner
-Zest.showSettings()   // Show settings modal
-Zest.reset()          // Clear consent, show banner
-
-// Consent management
-Zest.getConsent()     // Get current consent state
-Zest.hasConsent('analytics')  // Check specific category
-Zest.acceptAll()      // Accept all categories
-Zest.rejectAll()      // Reject all (except essential)
+// Show/hide UI (full build only)
+Zest.show()            // Show banner
+Zest.hide()            // Hide banner
+Zest.showSettings()    // Show settings modal
+Zest.hideSettings()    // Close settings modal
+Zest.reset()           // Clear consent + reshow banner
+
+// Consent state
+Zest.getConsent()              // { essential, functional, analytics, marketing }
+Zest.hasConsent('analytics')   // boolean
+Zest.hasConsentDecision()      // boolean — has the user made a choice yet?
+Zest.getConsentProof()         // full consent cookie payload (compliance audit)
+
+// Programmatic actions
+Zest.acceptAll()
+Zest.rejectAll()
+Zest.updateConsent({ analytics: true, marketing: false })  // headless only
+
+// DNT / GPC
+Zest.isDoNotTrackEnabled()
+Zest.getDNTDetails()           // { enabled, source: 'dnt'|'gpc'|null }
+
+// Events — subscribe helpers (also work with addEventListener)
+Zest.on('zest:change', (e) => {})
+Zest.once('zest:ready', (e) => {})
+Zest.EVENTS                    // { READY, CONSENT, REJECT, CHANGE, SHOW, HIDE }
+```
+
+## Headless mode — bring your own UI
+
+Full control over markup and styling, no Shadow DOM, no inline CSS.
+
+```js
+import Zest from '@freshjuice/zest/headless';
+
+Zest.init({
+  mode: 'safe',
+  respectDNT: true,
+  consentModeGoogle: true
+});
+
+// Decide when to show YOUR banner
+if (!Zest.hasConsentDecision()) {
+  document.querySelector('#my-banner').classList.add('open');
+}
+
+// Wire your buttons
+document.querySelector('#accept').onclick = () => Zest.acceptAll();
+document.querySelector('#reject').onclick = () => Zest.rejectAll();
+
+document.querySelector('#save').onclick = () => {
+  Zest.updateConsent({
+    analytics: analyticsCheckbox.checked,
+    marketing: marketingCheckbox.checked,
+    functional: functionalCheckbox.checked
+  });
+};
+
+// Listen for changes
+Zest.on(Zest.EVENTS.CHANGE, (e) => {
+  console.log('consent changed', e.detail.consent);
+});
 ```
 
+What headless gives you:
+- All interceptors (cookies, storage, scripts) still work — just skip the built-in UI
+- Same config surface (`mode`, `respectDNT`, `consentModeGoogle`, `blockedDomains`, `patterns`, etc.)
+- **Does NOT auto-init** — you call `Zest.init()` when ready
+- **Does NOT set `window.Zest`** — you import and use the module directly
+
+See `examples/headless.html` for a complete working example.
+
 ## Do Not Track (DNT) / Global Privacy Control (GPC)
 
 Zest respects browser privacy signals by default:
 
 ```javascript
 window.ZestConfig = {
-  respectDNT: true,    // Respect DNT/GPC signals (default: true)
+  respectDNT: true,     // Respect DNT/GPC signals (default: true)
   dntBehavior: 'reject' // What to do when DNT is enabled
 };
 ```
@@ -116,10 +193,9 @@ window.ZestConfig = {
 | `preselect` | Show banner with non-essential options unchecked |
 | `ignore` | Ignore DNT/GPC signals completely |
 
-**API methods:**
 ```javascript
-Zest.isDoNotTrackEnabled()  // Returns true if DNT or GPC is enabled
-Zest.getDNTDetails()        // Returns { enabled: boolean, source: 'dnt' | 'gpc' | null }
+Zest.isDoNotTrackEnabled()  // true if DNT or GPC is enabled
+Zest.getDNTDetails()        // { enabled: boolean, source: 'dnt' | 'gpc' | null }
 ```
 
 ## Blocking Modes
@@ -141,8 +217,6 @@ window.ZestConfig = {
 
 ### Custom Blocked Domains
 
-Add your own domains to block:
-
 ```javascript
 window.ZestConfig = {
   mode: 'safe',
@@ -155,8 +229,6 @@ window.ZestConfig = {
 
 ### Manual Script Tagging
 
-For any mode, you can explicitly tag scripts:
-
 ```html
 <script data-consent-category="analytics" src="https://..."></script>
 <script data-consent-category="marketing">
@@ -164,9 +236,11 @@ For any mode, you can explicitly tag scripts:
 </script>
 ```
 
-### Allow Specific Scripts
+> **Note:** `data-consent-category="essential"` on third-party scripts is
+> ignored — self-labeling as essential is a known bypass. Only
+> `functional`, `analytics`, and `marketing` self-labels are honored.
 
-Prevent a script from being blocked (useful in strict/doomsday modes):
+### Allow Specific Scripts
 
 ```html
 <script data-zest-allow src="https://cdn.example.com/library.js"></script>
@@ -190,18 +264,22 @@ document.addEventListener('zest:change', (e) => {
 document.addEventListener('zest:ready', (e) => {
   console.log('Zest initialized:', e.detail.consent);
 });
+
+// Or via the helpers
+Zest.on(Zest.EVENTS.CHANGE, (e) => { /* ... */ });
+Zest.once(Zest.EVENTS.READY, (e) => { /* ... */ });
 ```
 
 ## Google Consent Mode v2 / Microsoft UET Consent Mode
 
-Zest can optionally push consent signals to Google and Microsoft advertising APIs. Both are **disabled by default**.
+Optional — push consent state to Google and Microsoft advertising APIs.
 
 ### Enable via JavaScript
 
 ```javascript
 window.ZestConfig = {
-  consentModeGoogle: true,    // Google Consent Mode v2
-  consentModeMicrosoft: true  // Microsoft UET Consent Mode
+  consentModeGoogle: true,
+  consentModeMicrosoft: true
 };
 ```
 
@@ -215,12 +293,10 @@ window.ZestConfig = {
 ></script>
 ```
 
-### How it works
-
 When enabled, Zest automatically:
 
 1. Pushes a `'default'` denied state on page load (before any tracking scripts fire)
-2. Pushes an `'update'` with the correct consent state whenever the user makes a choice
+2. Pushes an `'update'` whenever the user makes a choice
 
 ### Category mapping
 
@@ -231,11 +307,9 @@ When enabled, Zest automatically:
 | `analytics` | `analytics_storage` | — |
 | `marketing` | `ad_storage`, `ad_user_data`, `ad_personalization` | `ad_storage` |
 
-No additional setup is needed — just include your Google Analytics/GTM or Microsoft UET tags as usual and Zest will handle the consent signaling.
-
 ## Localization
 
-Zest has **built-in translations** with auto-detection.
+Built-in translations with auto-detection.
 
 **Supported languages:** `en`, `de`, `es`, `fr`, `it`, `pt`, `nl`, `pl`, `uk`, `ru`, `ja`, `zh`
 
@@ -243,8 +317,9 @@ Zest has **built-in translations** with auto-detection.
 
 | Bundle | Size (gzip) | Description |
 |--------|-------------|-------------|
-| `zest.min.js` | ~14KB | All 12 languages, auto-detects |
-| `zest.{lang}.min.js` | ~9KB | Single language (e.g., `zest.de.min.js`) |
+| `zest.min.js` | ~16 KB | All 12 languages, auto-detects |
+| `zest.{lang}.min.js` | ~9 KB | Single language (e.g. `zest.de.min.js`) |
+| `zest.headless.esm.min.js` | ~11 KB | Logic only, no UI / no translations (ESM import) |
 
 ```html
 <!-- Full bundle - auto-detects language -->
@@ -257,61 +332,40 @@ Zest has **built-in translations** with auto-detection.
 ### Language Detection
 
 ```javascript
-window.ZestConfig = {
-  lang: 'auto' // Auto-detect (default)
-};
+window.ZestConfig = { lang: 'auto' };  // default
 ```
 
-**Detection priority:**
-1. `lang` config option (if not 'auto')
-2. `<html lang="de">` attribute
-3. Browser language (`navigator.language`)
-4. Fallback to English
+Priority: `lang` config → `<html lang="...">` → `navigator.language` → English.
 
 ### Force Specific Language
 
 ```javascript
-window.ZestConfig = {
-  lang: 'de' // Force German
-};
+window.ZestConfig = { lang: 'de' };
 ```
 
 ### Override Labels
 
 ```javascript
 window.ZestConfig = {
-  lang: 'de', // Use German as base
+  lang: 'de',
   labels: {
     banner: {
-      title: 'Custom German Title' // Override just this
+      title: 'Custom German Title'
     }
   }
 };
 ```
 
-Standalone JSON translation files also available in `/locales/` for external loading.
+Standalone JSON translation files are in `/locales/`.
 
-## Custom Styling
+## Styling the UI (full build)
 
-Override default styles by passing custom CSS:
+The UI is rendered inside a Shadow DOM with `mode: 'open'`, so your global
+CSS can't reach inside the component. You have three options:
 
-```javascript
-window.ZestConfig = {
-  customStyles: `
-    .zest-banner {
-      max-width: 600px;
-    }
-    .zest-btn--primary {
-      border-radius: 20px;
-    }
-    .zest-modal {
-      max-width: 600px;
-    }
-  `
-};
-```
+### 1. CSS custom properties (inheritable through Shadow DOM)
 
-Available CSS custom properties (can also be set via parent CSS):
+The following custom properties are exposed on the host elements:
 
 ```css
 zest-banner, zest-modal, zest-widget {
@@ -326,6 +380,32 @@ zest-banner, zest-modal, zest-widget {
 }
 ```
 
+### 2. `customStyles` config option
+
+```javascript
+window.ZestConfig = {
+  customStyles: `
+    .zest-banner { max-width: 600px; }
+    .zest-btn--primary { border-radius: 20px; }
+    .zest-modal { max-width: 600px; }
+  `
+};
+```
+
+> **Security note:** `customStyles` is sanitized — `@import`, `expression()`,
+> external `url()` values, and selectors targeting the accept/reject
+> buttons are stripped. This prevents clickjacking via invisible-button
+> CSS attacks. Payloads over 20 KB are dropped entirely.
+
+### 3. Style the host elements directly
+
+The custom elements `zest-banner`, `zest-modal`, `zest-widget` live in the
+light DOM — you can position, hide, or z-index them from your global CSS.
+
+### Want full CSS control?
+
+Use the **headless** entry and style your own markup however you like.
+
 ## Categories
 
 | Category | ID | Default | Description |
@@ -335,18 +415,38 @@ zest-banner, zest-modal, zest-widget {
 | Analytics | `analytics` | OFF | Usage tracking |
 | Marketing | `marketing` | OFF | Advertising cookies |
 
+Unknown cookies default to `marketing` (strictest).
+
+## Security
+
+Zest takes a defense-in-depth approach to security.
+
+Highlights:
+
+- All config-driven HTML is escaped via an internal `escapeHTML` pass
+- `policyUrl` is validated against an allowlist (`http:`, `https:`,
+  `mailto:`, `tel:`, relative)
+- `accentColor` must pass a strict color validator
+- `customStyles` is sanitized (see above)
+- Consent cookie JSON is schema-validated on read (prototype pollution safe)
+- On HTTPS, the consent cookie is written with the `Secure` flag
+- `window.Zest` is frozen and non-configurable once installed
+- User callbacks are wrapped in try/catch so a throwing handler can't
+  break the consent flow
+- Cookie / storage / script queues are size-capped (DoS prevention)
+
+To report a vulnerability, open a private security advisory on GitHub.
+
 ## Config Schema
 
-JSON Schema available for IDE autocompletion: `zest.config.schema.json`
+JSON Schema for IDE autocompletion: [`zest.config.schema.json`](zest.config.schema.json)
 
 ## Contributing
 
-Contributions are welcome! Please feel free to submit a Pull Request.
-
 1. Fork the repository
 2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
+3. Commit your changes
+4. Push to the branch
 5. Open a Pull Request
 
 ## Credits

package/dist/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;
+  }
+}