@el7ven/cookie-kit 0.3.1 → 0.3.3

package/src/core/ConsentManager.js

@@ -0,0 +1,710 @@
+/**
+ * Core Consent Manager — handles consent state, persistence, and events
+ * @module ConsentManager
+ */
+
+import { StorageAdapter } from './StorageAdapter.js'
+
+const DEFAULT_CONFIG = {
+  consentLevel: 'standard', // 'lite' | 'standard' | 'enterprise'
+  configVersion: '1.0.0', // Config version for consent invalidation
+  schemaVersion: 1, // Consent data schema version (will be overridden by COOKIE_CONSENT_CONFIG)
+  policyVersion: null, // Privacy policy version (e.g., '2026-03')
+  storageKey: 'cookie_consent',
+  storageType: 'localStorage', // 'localStorage' | 'cookie' | 'both'
+  consentExpireDays: 365, // GDPR: consent expiration in days
+  mode: 'gdpr', // 'gdpr' | 'ccpa' | 'lgpd' | 'essential'
+  debug: false,
+  categories: {},
+  enableHash: true, // Enable consent hash for integrity verification (enterprise only)
+  enableHistory: false, // Enable consent history tracking (enterprise only)
+  enableIpHash: false, // Enable IP hash for proof of consent (enterprise only)
+  auditLog: false, // Enable audit logging for GDPR compliance (enterprise only)
+  domain: null, // Domain for meta tracking
+  language: null, // Language for meta tracking
+  tenant: null // Multi-tenant support (domain identifier)
+}
+
+const DEFAULT_CONSENT_STATE = {
+  consentId: null, // UUID for proof of consent (GDPR)
+  timestamp: null, // ISO 8601 format
+  expiresAt: null, // ISO 8601 format
+  status: null, // 'accepted' | 'rejected' | 'custom'
+  source: 'banner', // 'banner' | 'settings' | 'api' | 'migration'
+  configVersion: null, // Config version at time of consent
+  policyVersion: null, // Privacy policy version at time of consent
+  schemaVersion: 1, // Schema version for migration support
+  region: 'ROW', // EU, EEA, UK, US, CA, ROW (Rest of World)
+  categories: {},
+  hash: null, // Integrity hash (SHA-256)
+  meta: {
+    userAgent: null,
+    language: null,
+    domain: null,
+    ipHash: null // SHA-256 hash of IP (never store raw IP)
+  },
+  history: [] // Array of previous consent states with actions
+}
+
+export class ConsentManager {
+  constructor(config = {}) {
+    this.config = { ...DEFAULT_CONFIG, ...config }
+    this.listeners = new Map()
+    this.storage = new StorageAdapter(this.config)
+
+    // Auto-fix null/undefined data in storage
+    this._fixCorruptedStorage()
+
+    this._normalizeCategories()
+    this._initializePublicAPI()
+    this._debug('ConsentManager initialized', this.config)
+    this._debug('Storage type:', this.storage.getActiveStorageType())
+  }
+
+  // --- Category Normalization ---
+
+  _normalizeCategories() {
+    const raw = this.config.categories
+    if (Array.isArray(raw)) {
+      this.config.categories = raw.reduce((acc, cat) => {
+        acc[cat.id] = cat
+        return acc
+      }, {})
+    }
+  }
+
+  getCategories() {
+    return { ...this.config.categories }
+  }
+
+  getRequiredCategories() {
+    return Object.keys(this.config.categories).filter(
+      id => this.config.categories[id].required
+    )
+  }
+
+  getOptionalCategories() {
+    return Object.keys(this.config.categories).filter(
+      id => !this.config.categories[id].required
+    )
+  }
+
+  // --- Consent State ---
+
+  getConsent() {
+    if (typeof window === 'undefined') return null
+
+    try {
+      const stored = this._read()
+      if (!stored || stored === 'null' || stored === 'undefined') return null
+
+      const consent = JSON.parse(stored)
+      if (!consent || typeof consent !== 'object') return null
+
+      // Config version mismatch — re-consent needed
+      if (consent.configVersion !== this.config.configVersion) {
+        this._debug('Config version mismatch, clearing consent')
+        return null
+      }
+
+      // Hash verification (if enabled) - CRITICAL for tamper detection
+      if (this.config.enableHash && consent.hash) {
+        if (!this._verifyHashSync(consent)) {
+          this._debug('Hash verification failed, consent may be tampered')
+          this._logAudit('consent_hash_mismatch', { consentId: consent.consentId })
+          this._emitEvent('consent:integrity-failed', { consentId: consent.consentId })
+          return null
+        }
+      }
+
+      // Expiry check (GDPR compliance) - using expiresAt
+      if (consent.expiresAt) {
+        const expiresDate = new Date(consent.expiresAt)
+        if (Date.now() > expiresDate.getTime()) {
+          this._debug('Consent expired at', consent.expiresAt)
+          this._logAudit('consent_expired', { consentId: consent.consentId })
+          return null
+        }
+      }
+
+      // Fallback: check timestamp if expiresAt is missing (backward compatibility)
+      if (!consent.expiresAt && consent.timestamp) {
+        const timestampDate = new Date(consent.timestamp)
+        const maxAge = this.config.consentExpireDays * 24 * 60 * 60 * 1000
+        if (Date.now() - timestampDate.getTime() > maxAge) {
+          this._debug('Consent expired after', this.config.consentExpireDays, 'days')
+          this._logAudit('consent_expired', { consentId: consent.consentId })
+          return null
+        }
+      }
+
+      // Return consent with computed fields
+      return {
+        ...consent,
+        hasConsented: consent.status === 'accepted' || consent.status === 'rejected' || consent.status === 'custom'
+      }
+    } catch (e) {
+      this._debug('Error reading consent', e)
+      return null
+    }
+  }
+
+  async saveConsent(categories, options = {}) {
+    const { source = 'banner', ipAddress = null } = options
+    if (typeof window === 'undefined') return null
+
+    // Ensure required categories are always true
+    const finalCategories = { ...categories }
+    this.getRequiredCategories().forEach(id => {
+      finalCategories[id] = true
+    })
+
+    // Get previous consent for history
+    const previousConsent = this.getConsent()
+
+    // Calculate expiration date
+    const now = new Date()
+    const expiresAt = new Date(now.getTime() + this.config.consentExpireDays * 24 * 60 * 60 * 1000)
+
+    // Determine consent status based on enabled categories only
+    let status = 'custom'
+    const enabledCategories = Object.keys(this.config.categories).filter(id => this.config.categories[id].enabled)
+    const requiredCategories = this.getRequiredCategories().filter(id => this.config.categories[id].enabled)
+    const optionalCategories = enabledCategories.filter(id => !requiredCategories.includes(id))
+    
+    // For essential mode with only required categories, status should be 'accepted'
+    if (optionalCategories.length === 0) {
+      // No optional categories - user accepted required categories only
+      status = 'accepted'
+    } else {
+      // Has optional categories - check user's choice
+      const allOptionalAccepted = optionalCategories.every(id => finalCategories[id] === true)
+      const allOptionalRejected = optionalCategories.every(id => finalCategories[id] === false)
+      status = allOptionalAccepted ? 'accepted' : (allOptionalRejected ? 'rejected' : 'custom')
+    }
+
+    // Build consent object based on tier level
+    const consentLevel = this.config.consentLevel || 'standard'
+
+    // Tier 1: Lite - minimal consent (120 bytes)
+    let consent = {
+      status,
+      categories: finalCategories,
+      configVersion: this.config.configVersion,
+      timestamp: now.toISOString(),
+      expiresAt: expiresAt.toISOString(),
+      consentId: this._generateConsentId()
+    }
+
+    // Tier 2: Standard - GDPR compliance (300 bytes)
+    if (consentLevel !== 'lite') {
+      consent.source = source
+      consent.policyVersion = this.config.policyVersion
+      consent.region = this._detectRegion()
+      consent.hasConsented = true
+    }
+
+    // Tier 3: Enterprise - full compliance (700 bytes)
+    if (consentLevel === 'enterprise') {
+      consent.schemaVersion = this.config.schemaVersion
+      consent.meta = {
+        userAgent: typeof navigator !== 'undefined' ? navigator.userAgent : null,
+        language: this.config.language || (typeof navigator !== 'undefined' ? navigator.language : null),
+        domain: this.config.domain || (typeof window !== 'undefined' ? window.location.hostname : null),
+        ipHash: null // Will be set if enableIpHash is true
+      }
+      consent.history = []
+      consent.hash = null // Will be set below
+    }
+
+    // Add to history if enabled (enterprise only)
+    if (consentLevel === 'enterprise' && this.config.enableHistory && previousConsent) {
+      consent.history = [
+        ...(previousConsent.history || []),
+        {
+          timestamp: previousConsent.timestamp,
+          action: previousConsent.status || 'unknown',
+          categories: previousConsent.categories
+        }
+      ].slice(-10) // Keep last 10 changes
+    }
+
+    // Generate IP hash if enabled (enterprise only)
+    if (consentLevel === 'enterprise' && this.config.enableIpHash && ipAddress && consent.meta) {
+      consent.meta.ipHash = await this._generateIpHash(ipAddress)
+    }
+
+    // Generate hash for integrity (enterprise only)
+    if (consentLevel === 'enterprise' && this.config.enableHash) {
+      consent.hash = await this._generateHash(consent)
+    }
+
+    try {
+      // Validate consent before saving
+      if (!consent || typeof consent !== 'object') {
+        this._debug('Invalid consent object, not saving', consent)
+        return null
+      }
+
+      const jsonString = JSON.stringify(consent)
+
+      // Double-check we're not saving null or undefined
+      if (jsonString === 'null' || jsonString === 'undefined') {
+        this._debug('Invalid JSON string detected, not saving', jsonString)
+        return null
+      }
+
+      this._write(jsonString)
+      this._debug('Consent saved', consent)
+      this._logAudit('consent_saved', { consentId: consent.consentId, categories: finalCategories })
+      this._emit('consentChanged', { consent, categories: finalCategories })
+
+      // Emit per-category events
+      Object.keys(finalCategories).forEach(catId => {
+        this._emit('categoryChanged', {
+          category: catId,
+          granted: finalCategories[catId]
+        })
+      })
+
+      return consent
+    } catch (e) {
+      this._debug('Error saving consent', e)
+      return null
+    }
+  }
+
+  hasConsent() {
+    const consent = this.getConsent()
+    // For lite level, check if consent exists and has status
+    // For standard/enterprise, check hasConsented flag
+    return consent && (consent.hasConsented === true || consent.status)
+  }
+
+  hasCategoryConsent(categoryId) {
+    const consent = this.getConsent()
+    return consent?.categories?.[categoryId] === true
+  }
+
+  async acceptAll(source = 'banner', ipAddress = null) {
+    const categories = {}
+    Object.keys(this.config.categories).forEach(id => {
+      // Only save enabled categories
+      // For essential mode: only necessary will be enabled
+      // For GDPR mode: all enabled categories will be saved
+      if (this.config.categories[id].enabled) {
+        categories[id] = true
+      }
+    })
+    this._debug('Accept all')
+    const consent = await this.saveConsent(categories, { source, ipAddress })
+    return consent
+  }
+
+  async rejectAll(source = 'banner', ipAddress = null) {
+    const categories = {}
+    Object.keys(this.config.categories).forEach(id => {
+      // Only save enabled categories
+      // Required categories get true, optional enabled categories get false
+      if (this.config.categories[id].enabled) {
+        categories[id] = this.config.categories[id].required || false
+      }
+    })
+    this._debug('Reject all')
+    const consent = await this.saveConsent(categories, { source, ipAddress })
+    return consent
+  }
+
+  async acceptSelected(selectedIds, source = 'settings', ipAddress = null) {
+    const categories = {}
+    Object.keys(this.config.categories).forEach(id => {
+      // Only save enabled categories
+      // Selected or required categories get true, others get false
+      if (this.config.categories[id].enabled) {
+        categories[id] = selectedIds.includes(id) || this.config.categories[id].required
+      }
+    })
+    this._debug('Accept selected', selectedIds)
+    const consent = await this.saveConsent(categories, { source, ipAddress })
+    return consent
+  }
+
+  clearConsent() {
+    try {
+      this._remove()
+      this._debug('Consent cleared')
+      this._emit('consentCleared', {})
+      return true
+    } catch (e) {
+      return false
+    }
+  }
+
+  getDefaultCategoriesState() {
+    const categories = {}
+    Object.keys(this.config.categories).forEach(id => {
+      categories[id] = this.config.categories[id].required || false
+    })
+    return categories
+  }
+
+  // --- Storage Abstraction (Safe Storage Adapter) ---
+
+  _read() {
+    return this.storage.get()
+  }
+
+  _write(value) {
+    return this.storage.set(this.config.storageKey || 'cookie_consent', value)
+  }
+
+  _remove() {
+    return this.storage.remove(this.config.storageKey || 'cookie_consent')
+  }
+
+  // --- GDPR Compliance Helpers ---
+
+  _generateConsentId() {
+    // Use crypto.randomUUID if available (modern browsers)
+    if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+      return crypto.randomUUID()
+    }
+
+    // Fallback: cryptographically secure UUID v4 generator
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+      const r = crypto.getRandomValues(new Uint8Array(1))[0] % 16
+      const v = c === 'x' ? r : (r & 0x3 | 0x8)
+      return v.toString(16)
+    })
+  }
+
+  async _generateHash(consent) {
+    // SHA-256 hash for integrity verification
+    const data = JSON.stringify({
+      consentId: consent.consentId,
+      timestamp: consent.timestamp,
+      categories: consent.categories,
+      configVersion: consent.configVersion,
+      policyVersion: consent.policyVersion,
+      region: consent.region,
+      schemaVersion: consent.schemaVersion
+    })
+
+    // Use Web Crypto API for SHA-256 (modern browsers)
+    if (typeof crypto !== 'undefined' && crypto.subtle) {
+      try {
+        const encoder = new TextEncoder()
+        const dataBuffer = encoder.encode(data)
+        const hashBuffer = await crypto.subtle.digest('SHA-256', dataBuffer)
+        const hashArray = Array.from(new Uint8Array(hashBuffer))
+        return hashArray.map(b => b.toString(16).padStart(2, '0')).join('')
+      } catch (e) {
+        this._debug('Crypto API not available, using fallback hash')
+      }
+    }
+
+    // Fallback: simple hash function for older browsers
+    return this._generateHashFallback(data)
+  }
+
+  _verifyHashSync(consent) {
+    // Synchronous hash verification for getConsent()
+    const data = JSON.stringify({
+      consentId: consent.consentId,
+      timestamp: consent.timestamp,
+      categories: consent.categories,
+      configVersion: consent.configVersion,
+      policyVersion: consent.policyVersion,
+      region: consent.region,
+      schemaVersion: consent.schemaVersion
+    })
+
+    const expectedHash = this._generateHashFallback(data)
+    return expectedHash === consent.hash
+  }
+
+  _generateHashFallback(data) {
+    // Simple hash function for sync verification
+    let hash = 0
+    for (let i = 0; i < data.length; i++) {
+      const char = data.charCodeAt(i)
+      hash = ((hash << 5) - hash) + char
+      hash = hash & hash // Convert to 32bit integer
+    }
+    return Math.abs(hash).toString(16)
+  }
+
+  async _generateIpHash(ip) {
+    // SHA-256 hash of IP address (NEVER store raw IP)
+    if (!ip) return null
+
+    if (typeof crypto !== 'undefined' && crypto.subtle) {
+      try {
+        const encoder = new TextEncoder()
+        const dataBuffer = encoder.encode(ip)
+        const hashBuffer = await crypto.subtle.digest('SHA-256', dataBuffer)
+        const hashArray = Array.from(new Uint8Array(hashBuffer))
+        return hashArray.map(b => b.toString(16).padStart(2, '0')).join('')
+      } catch (e) {
+        this._debug('Crypto API not available for IP hash')
+        return null
+      }
+    }
+
+    return null
+  }
+
+  _fixCorruptedStorage() {
+    try {
+      const stored = this._read()
+
+      // Check for null/undefined/literal null string
+      if (!stored || stored === 'null' || stored === 'undefined') {
+        this._debug('Detected corrupted storage data, removing...')
+        this._remove()
+        return
+      }
+
+      // Try to parse and validate
+      try {
+        const consent = JSON.parse(stored)
+
+        if (!consent || typeof consent !== 'object') {
+          this._debug('Invalid consent object detected, removing...')
+          this._remove()
+          return
+        }
+
+        // Check for required fields
+        const requiredFields = ['consentId', 'timestamp', 'categories']
+        const missingFields = requiredFields.filter(field => !consent[field])
+
+        if (missingFields.length > 0) {
+          this._debug('Missing required fields, removing corrupted data:', missingFields)
+          this._remove()
+          return
+        }
+
+        // Check categories object integrity
+        if (!consent.categories || typeof consent.categories !== 'object') {
+          this._debug('Invalid categories object, removing corrupted data')
+          this._remove()
+          return
+        }
+
+        this._debug('Storage data is valid')
+
+      } catch (parseError) {
+        this._debug('JSON parse error, removing corrupted data:', parseError.message)
+        this._remove()
+      }
+
+    } catch (e) {
+      this._debug('Error checking storage integrity:', e)
+    }
+  }
+
+  _detectRegion() {
+    // Try to detect region from config or timezone
+    if (this.config.region) return this.config.region
+
+    if (typeof Intl === 'undefined') return 'ROW'
+
+    try {
+      const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone
+
+      // EU timezones
+      const euTimezones = [
+        'Europe/London', 'Europe/Paris', 'Europe/Berlin', 'Europe/Madrid',
+        'Europe/Rome', 'Europe/Amsterdam', 'Europe/Brussels', 'Europe/Vienna',
+        'Europe/Stockholm', 'Europe/Copenhagen', 'Europe/Helsinki', 'Europe/Athens',
+        'Europe/Prague', 'Europe/Warsaw', 'Europe/Budapest', 'Europe/Bucharest'
+      ]
+
+      if (euTimezones.some(tz => timezone.includes(tz.split('/')[1]))) {
+        return 'EU'
+      }
+
+      if (timezone.startsWith('America/New_York') || timezone.startsWith('America/Los_Angeles')) {
+        return 'US'
+      }
+
+      if (timezone.startsWith('America/Toronto')) {
+        return 'CA'
+      }
+
+      return 'ROW'
+    } catch (e) {
+      return 'ROW'
+    }
+  }
+
+  _logAudit(action, data) {
+    if (!this.config.auditLog) return
+
+    const auditEntry = {
+      timestamp: Date.now(),
+      action,
+      ...data
+    }
+
+    this._debug('Audit log:', auditEntry)
+    this._emit('auditLog', auditEntry)
+  }
+
+  resetConsent() {
+    this._debug('Resetting consent')
+    this._logAudit('consent_reset', {})
+    return this.clearConsent()
+  }
+
+  getConsentProof() {
+    const consent = this.getConsent()
+    if (!consent) return null
+
+    return {
+      consentId: consent.consentId,
+      timestamp: consent.timestamp,
+      expiresAt: consent.expiresAt,
+      configVersion: consent.configVersion,
+      region: consent.region,
+      categories: consent.categories,
+      hash: consent.hash,
+      meta: consent.meta
+    }
+  }
+
+  // Get consent history
+  getConsentHistory() {
+    const consent = this.getConsent()
+    return consent?.history || []
+  }
+
+  // --- Event System ---
+
+  on(event, callback) {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, [])
+    }
+    this.listeners.get(event).push(callback)
+    return () => this.off(event, callback)
+  }
+
+  off(event, callback) {
+    if (!this.listeners.has(event)) return
+    const list = this.listeners.get(event).filter(cb => cb !== callback)
+    this.listeners.set(event, list)
+  }
+
+  _emit(event, data) {
+    this._debug(`Event: ${event}`, data)
+
+    // Internal listeners
+    if (this.listeners.has(event)) {
+      this.listeners.get(event).forEach(cb => cb(data))
+    }
+
+    // Emit DOM CustomEvent (old format for backward compatibility)
+    this._emitEvent(event, data)
+  }
+
+  _emitEvent(eventName, detail) {
+    // Enterprise event system - dispatches CustomEvents to window
+    if (typeof window === 'undefined') return
+
+    // New format: cookie-consent:event-name
+    window.dispatchEvent(new CustomEvent(`cookie-consent:${eventName}`, { detail }))
+
+    // Legacy format: cookieConsent:eventName (backward compatibility)
+    window.dispatchEvent(new CustomEvent(`cookieConsent:${eventName}`, { detail }))
+  }
+
+  // --- Public API (window.CookieConsent) ---
+
+  _initializePublicAPI() {
+    if (typeof window === 'undefined') return
+
+    // Public API for external scripts
+    window.CookieConsent = {
+      has: (category) => this.hasCategoryConsent(category),
+      get: () => this.getConsent(),
+      getProof: () => this.getConsentProof(),
+      region: () => this._detectRegion(),
+      categories: () => this.config.categories,
+      acceptAll: (source) => this.acceptAll(source),
+      rejectAll: (source) => this.rejectAll(source),
+      acceptSelected: (categories, source) => this.acceptSelected(categories, source),
+      reset: () => this.resetConsent(),
+      on: (event, callback) => this.on(event, callback),
+      off: (event, callback) => this.off(event, callback),
+      // Internal access for CMP Platform
+      consentManager: this
+    }
+
+    // Debug mode API
+    if (this.config.debug) {
+      window.__COOKIE_CONSENT__ = {
+        tier: () => {
+          const tierInfo = `
+ConsentKit v${this.config.configVersion}
+Tier: ${this.config.consentLevel || 'standard'}
+Region: ${this._detectRegion()}
+Storage: ${this.storage.getActiveStorageType()}
+          `.trim()
+          console.log(tierInfo)
+          return {
+            version: this.config.configVersion,
+            tier: this.config.consentLevel || 'standard',
+            region: this._detectRegion(),
+            storage: this.storage.getActiveStorageType()
+          }
+        },
+        show: () => {
+          this._emitEvent('show-banner', {})
+          return 'Banner shown'
+        },
+        reset: () => {
+          this.resetConsent()
+          return 'Consent reset'
+        },
+        state: () => {
+          const consent = this.getConsent()
+          console.table(consent?.categories || {})
+          return consent
+        },
+        proof: () => {
+          const proof = this.getConsentProof()
+          console.log('Consent Proof:', proof)
+          return proof
+        },
+        history: () => {
+          const history = this.getConsentHistory()
+          console.table(history)
+          return history
+        },
+        storage: () => {
+          return {
+            type: this.storage.getActiveStorageType(),
+            available: this.storage.isAvailable()
+          }
+        },
+        config: () => {
+          console.log('Config:', this.config)
+          return this.config
+        }
+      }
+
+      this._debug('Debug mode enabled. Use window.__COOKIE_CONSENT__ in console')
+    }
+  }
+
+  // --- Debug ---
+
+  _debug(...args) {
+    if (this.config.debug) {
+      console.log('[CookieConsent]', ...args)
+    }
+  }
+}
+
+export { DEFAULT_CONFIG, DEFAULT_CONSENT_STATE }