@freshjuice/zest 1.0.0 → 2.0.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