@el7ven/cookie-kit 0.3.1 → 0.3.2

package/src/trackers/TrackerDetector.js

@@ -0,0 +1,488 @@
+/**
+ * TrackerDetector — automatically detects trackers on the page
+ * @module TrackerDetector
+ */
+
+import { getAllTrackerPatterns } from './TrackerPatterns.js'
+
+export class TrackerDetector {
+  constructor(config = {}) {
+    this.config = {
+      detectOnInit: true,
+      detectFromScripts: true,
+      detectFromGlobals: true,
+      detectFromDataLayer: true,
+      detectFromCookies: false, // Optional: can be privacy-invasive
+      detectFromNetwork: false, // Advanced: intercept fetch/XHR
+      observeDOM: true, // MutationObserver for dynamic trackers
+      confidenceScoring: true, // Calculate confidence scores
+      debug: false,
+      ...config
+    }
+    
+    this.detectedTrackers = new Map() // id -> tracker info
+    this.observer = null
+    this.networkInterceptors = []
+    this.detectTimer = null // Debounce timer
+  }
+
+  /**
+   * Run full detection
+   * @returns {Array} Detected trackers
+   */
+  /**
+   * Initialize detector with observers and interceptors
+   */
+  initialize() {
+    // Start DOM observation
+    if (this.config.observeDOM) {
+      this._startDOMObserver()
+    }
+
+    // Setup network interception
+    if (this.config.detectFromNetwork) {
+      this._setupNetworkInterception()
+    }
+
+    // Initial detection
+    this.detect()
+  }
+
+  /**
+   * Run full detection
+   * @returns {Array} Detected trackers
+   */
+  detect() {
+    this._debug('Starting tracker detection...')
+    
+    const detectionResults = new Map() // id -> { sources: [], confidence: 0 }
+
+    // 1. Detect from script sources
+    if (this.config.detectFromScripts) {
+      const scriptTrackers = this._detectFromScripts()
+      scriptTrackers.forEach(({ id, confidence }) => {
+        this._addDetectionResult(detectionResults, id, 'script', confidence)
+      })
+    }
+
+    // 2. Detect from global variables
+    if (this.config.detectFromGlobals) {
+      const globalTrackers = this._detectFromGlobals()
+      globalTrackers.forEach(({ id, confidence }) => {
+        this._addDetectionResult(detectionResults, id, 'global', confidence)
+      })
+    }
+
+    // 3. Detect from dataLayer
+    if (this.config.detectFromDataLayer) {
+      const dataLayerTrackers = this._detectFromDataLayer()
+      dataLayerTrackers.forEach(({ id, confidence }) => {
+        this._addDetectionResult(detectionResults, id, 'dataLayer', confidence)
+      })
+    }
+
+    // 4. Detect from cookies (optional)
+    if (this.config.detectFromCookies) {
+      const cookieTrackers = this._detectFromCookies()
+      cookieTrackers.forEach(({ id, confidence }) => {
+        this._addDetectionResult(detectionResults, id, 'cookie', confidence)
+      })
+    }
+
+    // Store detected trackers with confidence scores
+    const patterns = getAllTrackerPatterns()
+    detectionResults.forEach((result, id) => {
+      const pattern = patterns.find(p => p.id === id)
+      if (pattern) {
+        const confidence = this.config.confidenceScoring 
+          ? this._calculateConfidence(result.sources)
+          : 1.0
+
+        // Update or add tracker (prevent duplicates, update confidence)
+        if (this.detectedTrackers.has(id)) {
+          const existing = this.detectedTrackers.get(id)
+          // Update confidence to maximum
+          existing.confidence = Math.max(existing.confidence, confidence)
+          // Merge detection sources
+          existing.detectedBy = [...new Set([...existing.detectedBy, ...result.sources])]
+        } else {
+          this.detectedTrackers.set(id, {
+            ...pattern,
+            detectedAt: new Date().toISOString(),
+            detectedBy: result.sources,
+            confidence
+          })
+        }
+      }
+    })
+
+    const trackers = Array.from(this.detectedTrackers.values())
+    this._debug(`Detected ${trackers.length} trackers:`, trackers.map(t => `${t.name} (${(t.confidence * 100).toFixed(0)}%)`))
+    
+    return trackers
+  }
+
+  /**
+   * Detect trackers from script sources
+   * @private
+   */
+  _detectFromScripts() {
+    const detected = []
+    const scripts = document.querySelectorAll('script[src]')
+    const patterns = getAllTrackerPatterns()
+
+    scripts.forEach(script => {
+      const src = script.getAttribute('src') || ''
+      
+      patterns.forEach(pattern => {
+        pattern.scripts.forEach(scriptPattern => {
+          if (src.includes(scriptPattern)) {
+            detected.push({ id: pattern.id, confidence: 0.9 })
+            this._debug(`Detected ${pattern.name} from script:`, src)
+          }
+        })
+      })
+    })
+
+    return detected
+  }
+
+  /**
+   * Detect trackers from global variables
+   * @private
+   */
+  _detectFromGlobals() {
+    const detected = []
+    const patterns = getAllTrackerPatterns()
+
+    patterns.forEach(pattern => {
+      pattern.globals.forEach(globalVar => {
+        if (typeof window !== 'undefined' && window[globalVar] !== undefined) {
+          detected.push({ id: pattern.id, confidence: 1.0 })
+          this._debug(`Detected ${pattern.name} from global:`, globalVar)
+        }
+      })
+    })
+
+    return detected
+  }
+
+  /**
+   * Detect trackers from dataLayer
+   * @private
+   */
+  _detectFromDataLayer() {
+    const detected = []
+
+    if (typeof window === 'undefined' || !window.dataLayer) {
+      return detected
+    }
+
+    const patterns = getAllTrackerPatterns()
+    patterns.forEach(pattern => {
+      if (pattern.dataLayer.length === 0) return
+
+      pattern.dataLayer.forEach(key => {
+        const hasKey = window.dataLayer.some(item => {
+          if (typeof item === 'object') {
+            return key in item || JSON.stringify(item).includes(key)
+          }
+          return false
+        })
+
+        if (hasKey) {
+          detected.push({ id: pattern.id, confidence: 0.8 })
+          this._debug(`Detected ${pattern.name} from dataLayer:`, key)
+        }
+      })
+    })
+
+    return detected
+  }
+
+  /**
+   * Detect trackers from cookies
+   * @private
+   */
+  _detectFromCookies() {
+    const detected = []
+
+    if (typeof document === 'undefined') {
+      return detected
+    }
+
+    const cookies = document.cookie
+    const patterns = getAllTrackerPatterns()
+
+    patterns.forEach(pattern => {
+      pattern.cookies.forEach(cookiePattern => {
+        if (cookies.includes(cookiePattern)) {
+          detected.push({ id: pattern.id, confidence: 0.7 })
+          this._debug(`Detected ${pattern.name} from cookie:`, cookiePattern)
+        }
+      })
+    })
+
+    return detected
+  }
+
+  /**
+   * Get detected trackers
+   * @returns {Array}
+   */
+  getDetected() {
+    return Array.from(this.detectedTrackers.values())
+  }
+
+  /**
+   * Get detected trackers by category
+   * @param {string} category - Category name
+   * @returns {Array}
+   */
+  getDetectedByCategory(category) {
+    return this.getDetected().filter(tracker => tracker.category === category)
+  }
+
+  /**
+   * Check if specific tracker is detected
+   * @param {string} id - Tracker ID
+   * @returns {boolean}
+   */
+  isDetected(id) {
+    return this.detectedTrackers.has(id)
+  }
+
+  /**
+   * Get detection stats
+   * @returns {Object}
+   */
+  getStats() {
+    const trackers = this.getDetected()
+    const byCategory = {}
+
+    trackers.forEach(tracker => {
+      if (!byCategory[tracker.category]) {
+        byCategory[tracker.category] = []
+      }
+      byCategory[tracker.category].push(tracker.name)
+    })
+
+    return {
+      total: trackers.length,
+      byCategory,
+      trackers: trackers.map(t => ({
+        id: t.id,
+        name: t.name,
+        category: t.category
+      }))
+    }
+  }
+
+  /**
+   * Clear detected trackers
+   */
+  clear() {
+    this.detectedTrackers.clear()
+  }
+
+  /**
+   * Re-run detection
+   * @returns {Array}
+   */
+  refresh() {
+    this.clear()
+    return this.detect()
+  }
+
+  /**
+   * Destroy detector and cleanup
+   */
+  destroy() {
+    if (this.observer) {
+      this.observer.disconnect()
+      this.observer = null
+    }
+
+    this._removeNetworkInterception()
+    this.clear()
+  }
+
+  // --- Advanced Detection Methods ---
+
+  /**
+   * Start MutationObserver for dynamic trackers
+   * @private
+   */
+  _startDOMObserver() {
+    if (typeof MutationObserver === 'undefined') {
+      return
+    }
+
+    this.observer = new MutationObserver((mutations) => {
+      let hasNewScripts = false
+
+      mutations.forEach((mutation) => {
+        mutation.addedNodes.forEach((node) => {
+          if (node.nodeType === 1) {
+            if (node.tagName === 'SCRIPT' || node.querySelector?.('script')) {
+              hasNewScripts = true
+            }
+          }
+        })
+      })
+
+      if (hasNewScripts) {
+        this._debug('New scripts detected, scheduling re-scan...')
+        this._scheduleDetect() // Debounced
+      }
+    })
+
+    this.observer.observe(document.documentElement, {
+      childList: true,
+      subtree: true
+    })
+
+    this._debug('DOM observer started')
+  }
+
+  /**
+   * Setup network interception (fetch/XHR)
+   * SAFE: preserves original context and bindings
+   * @private
+   */
+  _setupNetworkInterception() {
+    if (typeof window === 'undefined') return
+
+    const patterns = getAllTrackerPatterns()
+
+    // Intercept fetch (SAFE: bind original context)
+    if (window.fetch) {
+      const originalFetch = window.fetch.bind(window)
+      window.fetch = async (...args) => {
+        const url = args[0]?.toString() || ''
+        this._checkNetworkRequest(url, patterns)
+        return originalFetch(...args)
+      }
+      this.networkInterceptors.push({ type: 'fetch', original: originalFetch })
+    }
+
+    // Intercept XMLHttpRequest (SAFE: preserve prototype)
+    if (window.XMLHttpRequest) {
+      const originalOpen = XMLHttpRequest.prototype.open
+      const self = this
+      XMLHttpRequest.prototype.open = function(...args) {
+        const url = args[1]?.toString() || ''
+        self._checkNetworkRequest(url, patterns)
+        return originalOpen.apply(this, args)
+      }
+      this.networkInterceptors.push({ type: 'xhr', original: originalOpen })
+    }
+
+    this._debug('Network interception enabled (safe mode)')
+  }
+
+  /**
+   * Check network request against patterns
+   * @private
+   */
+  _checkNetworkRequest(url, patterns) {
+    patterns.forEach(pattern => {
+      pattern.network?.forEach(networkPattern => {
+        if (url.includes(networkPattern)) {
+          this._debug(`Detected ${pattern.name} from network:`, url)
+          
+          // Update or add tracker
+          if (this.detectedTrackers.has(pattern.id)) {
+            const existing = this.detectedTrackers.get(pattern.id)
+            existing.confidence = Math.max(existing.confidence, 0.85)
+            if (!existing.detectedBy.includes('network')) {
+              existing.detectedBy.push('network')
+            }
+          } else {
+            this.detectedTrackers.set(pattern.id, {
+              ...pattern,
+              detectedAt: new Date().toISOString(),
+              detectedBy: ['network'],
+              confidence: 0.85
+            })
+          }
+        }
+      })
+    })
+  }
+
+  /**
+   * Remove network interception
+   * @private
+   */
+  _removeNetworkInterception() {
+    this.networkInterceptors.forEach(({ type, original }) => {
+      if (type === 'fetch' && window.fetch) {
+        window.fetch = original
+      } else if (type === 'xhr' && XMLHttpRequest.prototype.open) {
+        XMLHttpRequest.prototype.open = original
+      }
+    })
+    this.networkInterceptors = []
+  }
+
+  /**
+   * Add detection result
+   * @private
+   */
+  _addDetectionResult(results, id, source, confidence) {
+    if (!results.has(id)) {
+      results.set(id, { sources: [], confidences: [] })
+    }
+    const result = results.get(id)
+    result.sources.push(source)
+    result.confidences.push(confidence)
+  }
+
+  /**
+   * Calculate overall confidence score
+   * @private
+   */
+  _calculateConfidence(sources) {
+    if (sources.length === 0) return 0
+
+    // Weight different sources
+    const weights = {
+      script: 0.9,
+      global: 1.0,
+      dataLayer: 0.8,
+      cookie: 0.7,
+      network: 0.85
+    }
+
+    let totalWeight = 0
+    let weightedSum = 0
+
+    sources.forEach(source => {
+      const weight = weights[source] || 0.5
+      weightedSum += weight
+      totalWeight += 1
+    })
+
+    return totalWeight > 0 ? weightedSum / totalWeight : 0
+  }
+
+  /**
+   * Schedule detection with debounce
+   * Prevents excessive detect() calls from MutationObserver
+   * @private
+   */
+  _scheduleDetect() {
+    clearTimeout(this.detectTimer)
+    
+    this.detectTimer = setTimeout(() => {
+      this.detect()
+    }, 200) // 200ms debounce
+  }
+
+  _debug(...args) {
+    if (this.config.debug) {
+      console.log('[TrackerDetector]', ...args)
+    }
+  }
+}