cdp-edge 2.3.1 → 2.3.6

package/server-edge-tracker/modules/utils.ts

@@ -184,3 +184,126 @@ export function metaSignalBucket(score: number | null | undefined): MetaSignalBu
   if (score >= 0.6) return 'warm';
   return 'cold';
 }
+
+// ── Input Validation & Sanitization — Segurança contra XSS/Injection ────────
+
+/**
+ * Valida formato de email (basic RFC-compliant)
+ */
+export function isValidEmail(email: string | null | undefined): boolean {
+  if (!email || typeof email !== 'string') return false;
+  const trimmed = email.trim();
+  if (trimmed.length > 256) return false; // Limite razoável
+  const emailRegex = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;
+  return emailRegex.test(trimmed);
+}
+
+/**
+ * Sanitiza string contra XSS/HTML injection
+ * Remove tags HTML, scripts, e caracteres perigosos
+ */
+export function sanitizeString(input: string | null | undefined, maxLength: number = 512): string | null {
+  if (!input || typeof input !== 'string') return null;
+  let sanitized = String(input).trim();
+
+  // Remove HTML tags
+  sanitized = sanitized.replace(/<[^>]*>/g, '');
+
+  // Remove JavaScript event handlers
+  sanitized = sanitized.replace(/on\w+\s*=/gi, '');
+
+  // Remove javascript: protocol
+  sanitized = sanitized.replace(/javascript:/gi, '');
+
+  // Remove caracteres perigosos
+  sanitized = sanitized.replace(/[<>\"'`]/g, '');
+
+  // Remove caracteres Unicode perigosos
+  sanitized = sanitized.replace(/[\x00-\x1F\x7F]/g, '');
+
+  // Limita comprimento
+  if (sanitized.length > maxLength) {
+    sanitized = sanitized.substring(0, maxLength);
+  }
+
+  return sanitized.length > 0 ? sanitized : null;
+}
+
+/**
+ * Valida e sanitiza URL (para pageUrl)
+ */
+export function isValidUrl(url: string | null | undefined): boolean {
+  if (!url || typeof url !== 'string') return false;
+  const trimmed = url.trim();
+  if (trimmed.length > 2048) return false; // Limite razoável
+  try {
+    const parsed = new URL(trimmed);
+    return ['http:', 'https:'].includes(parsed.protocol);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Valida formato de CPF (11 dígitos)
+ */
+export function isValidCPF(cpf: string | null | undefined): boolean {
+  if (!cpf || typeof cpf !== 'string') return false;
+  const cleaned = cpf.replace(/\D/g, '');
+  return cleaned.length === 11 && /^\d+$/.test(cleaned);
+}
+
+/**
+ * Valida formato de CNPJ (14 dígitos)
+ */
+export function isValidCNPJ(cnpj: string | null | undefined): boolean {
+  if (!cnpj || typeof cnpj !== 'string') return false;
+  const cleaned = cnpj.replace(/\D/g, '');
+  return cleaned.length === 14 && /^\d+$/.test(cleaned);
+}
+
+/**
+ * Valida formato de valor numérico (para value em Purchase)
+ */
+export function isValidValue(value: number | null | undefined): boolean {
+  if (value === null || value === undefined) return true; // Valor opcional
+  const num = Number(value);
+  return !isNaN(num) && num >= 0 && num <= 9_999_999;
+}
+
+/**
+ * Valida moeda (currency field)
+ */
+export function isValidCurrency(currency: string | null | undefined): boolean {
+  if (!currency || typeof currency !== 'string') return true; // Opcional
+  const trimmed = currency.trim().toUpperCase();
+  const validCurrencies = ['BRL', 'USD', 'EUR', 'GBP', 'CAD', 'AUD', 'JPY', 'CHF'];
+  return trimmed.length === 3 && validCurrencies.includes(trimmed);
+}
+
+/**
+ * Sanitiza array de strings (para contentIds, etc.)
+ */
+export function sanitizeStringArray(input: string[] | null | undefined, maxLength: number = 512): string[] | null {
+  if (!input || !Array.isArray(input)) return null;
+  const sanitized = input
+    .map(item => sanitizeString(item, maxLength))
+    .filter(item => item !== null) as string[];
+  return sanitized.length > 0 ? sanitized : null;
+}
+
+/**
+ * Valida UTM parameters (utmSource, utmMedium, utmCampaign, utmContent, utmTerm)
+ */
+export function isValidUTM(param: string | null | undefined, paramType: string): boolean {
+  if (!param || typeof param !== 'string') return true; // Opcional
+  const trimmed = param.trim();
+  const maxLength = paramType === 'utm_source' ? 100 : 200;
+
+  if (trimmed.length > maxLength) return false;
+
+  // Verifica caracteres perigosos
+  const dangerousPatterns = ['<script', 'javascript:', 'onload=', 'onerror=', 'onclick='];
+  const lowerCase = trimmed.toLowerCase();
+  return !dangerousPatterns.some(pattern => lowerCase.includes(pattern));
+}

package/server-edge-tracker/modules/utm/utm-enricher.ts

@@ -0,0 +1,231 @@
+/**
+ * UTM Enricher Module
+ * Obfusca/desobfusca UTMs sensíveis (valores de produto)
+ * Integração com Agente UTM
+ */
+
+// ============================================================================
+// Constants & Config
+// ============================================================================
+
+const UTM_SALT = 'CDP_EDGE_UTM_SALT';
+const HASH_TRUNCATE_LENGTH = 8;
+
+// Obfuscação: SHA256(original + salt) → truncate(8)
+// Isso garante: mesmo valor → mesmo hash, mas irreversível sem o mapeamento
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface UTMMapping {
+  obfuscated: string;        // Hash truncado (ex: "8a3f1d2b")
+  original: string;          // Valor real (ex: "700k-1M")
+  category: string;          // "imovel", "automotivo", etc
+  pixel_audience?: string;   // ID da custom audience Meta
+  platform_specific?: {
+    meta?: { custom_audience_id?: string };
+    tiktok?: { pixel_id?: string };
+    ga4?: { event_parameter?: string };
+  };
+}
+
+export interface UTMMappingConfig {
+  method: 'sha256';
+  salt: string;
+  truncated_length: number;
+  mappings: UTMMapping[];
+}
+
+export interface EnrichedUTM {
+  source?: string;
+  medium?: string;
+  campaign?: string;
+  content?: string;
+  faixa_obfuscada?: string;    // Hash da faixa de valor
+  faixa_real?: string;         // Valor real (de-obfuscado)
+  faixa_category?: string;    // Categoria do produto
+  product_id_obfuscated?: string;
+  product_id_real?: string;
+}
+
+// ============================================================================
+// Core Functions
+// ============================================================================
+
+/**
+ * Obfusca um valor sensível usando SHA256 + truncate
+ * @param value - Valor a ser obfuscado (ex: "700k-1M")
+ * @returns Hash truncado de 8 caracteres
+ */
+export function obfuscateValue(value: string): string {
+  // sha256(value + salt) → truncate(8)
+  const hash = sha256(`${value}${UTM_SALT}`);
+  return hash.substring(0, HASH_TRUNCATE_LENGTH);
+}
+
+/**
+ * Verifica se um hash é válido (8 chars hex)
+ */
+export function isValidObfuscatedHash(hash: string): boolean {
+  return /^[a-f0-9]{8}$/.test(hash);
+}
+
+/**
+ * Desobfusca um valor usando o mapeamento
+ * @param obfuscated - Hash obfuscado
+ * @param mappings - Mapeamento de UTM (do config/utm-mapping.json)
+ * @returns UTM com valor real ou undefined se não encontrado
+ */
+export function deobfuscateValue(
+  obfuscated: string,
+  mappings: UTMMapping[]
+): UTMMapping | undefined {
+  return mappings.find(m => m.obfuscated === obfuscated);
+}
+
+/**
+ * Enrich payload com UTMs, desobfuscando valores sensíveis
+ */
+export function enrichPayloadWithUTM(
+  payload: any,
+  utms: Record<string, string>,
+  mappings: UTMMapping[]
+): { enriched: any; faixa?: UTMMapping } {
+  const enriched = { ...payload };
+  let faixa: UTMMapping | undefined;
+
+  // Desobfuscar faixa de valor
+  if (utms.faixa_obfuscada || utms.utm_faixa) {
+    const faixaHash = utms.faixa_obfuscada || utms.utm_faixa;
+    if (isValidObfuscatedHash(faixaHash)) {
+      faixa = deobfuscateValue(faixaHash, mappings);
+      if (faixa) {
+        enriched.faixa_real = faixa.original;
+        enriched.faixa_category = faixa.category;
+        enriched.pixel_audience = faixa.pixel_audience;
+      }
+    }
+  }
+
+  // Extrair UTMs padrão
+  enriched.utm_source = utms.utm_source || utms.source;
+  enriched.utm_medium = utms.utm_medium || utms.medium;
+  enriched.utm_campaign = utms.utm_campaign || utms.campaign;
+  enriched.utm_content = utms.utm_content || utms.content;
+
+  return { enriched, faixa };
+}
+
+/**
+ * Gera UTM obfuscada para uma faixa de valor
+ * @param range - Faixa real (ex: "700k-1M")
+ * @param category - Categoria (ex: "imovel")
+ * @returns Object com hash obfuscado
+ */
+export function generateObfuscatedUTM(range: string, category: string) {
+  const obfuscated = obfuscateValue(range);
+  return {
+    utm_faixa: obfuscated,
+    utm_campaign: `${category}_${obfuscated}`,
+    original_range: range,
+    hash: obfuscated
+  };
+}
+
+/**
+ * Cria um novo mapeamento de UTM
+ */
+export function createUTMMapping(
+  original: string,
+  category: string,
+  platform_specific?: any
+): UTMMapping {
+  return {
+    obfuscated: obfuscateValue(original),
+    original,
+    category,
+    platform_specific
+  };
+}
+
+// ============================================================================
+// Integration Functions (para uso no Worker)
+// ============================================================================
+
+/**
+ * Verifica se payload tem UTMs de segmentação
+ */
+export function hasSegmentationUTM(utms: Record<string, string>): boolean {
+  return !!(
+    utms.faixa_obfuscada ||
+    utms.utm_faixa ||
+    (utms.utm_campaign && isValidObfuscatedHash(
+      utms.utm_campaign.split('_').pop() || ''
+    ))
+  );
+}
+
+/**
+ * Extrai faixa de valor do utm_campaign (pattern: category_hash)
+ */
+export function extractFaixaFromCampaign(
+  campaign: string
+): string | null {
+  const parts = campaign.split('_');
+  const hash = parts.pop();
+  if (hash && isValidObfuscatedHash(hash)) {
+    return hash;
+  }
+  return null;
+}
+
+/**
+ * Para Meta CAPI: adiciona segmentação ao external_id
+ */
+export function addSegmentationToExternalId(
+  cdp_uid: string,
+  faixa: UTMMapping
+): string {
+  return `${cdp_uid}_${faixa.obfuscated}`;
+}
+
+/**
+ * Para GA4: cria custom parameter segmentado
+ */
+export function createSegmentationCustomParameter(faixa: UTMMapping) {
+  return {
+    'custom_faixa_categoria': faixa.category,
+    'custom_faixa_obfuscada': faixa.obfuscated,
+    'custom_faixa_audience': faixa.pixel_audience || 'UNKNOWN'
+  };
+}
+
+// ============================================================================
+// Import de sha256 (reutilizar de utils.ts)
+// ============================================================================
+
+function sha256(message: string): string {
+  // Importado de utils.ts - implementação real do SHA256
+  // Aqui simulamos para o exemplo:
+  const crypto = require('crypto');
+  return crypto.createHash('sha256').update(message).digest('hex');
+}
+
+// ============================================================================
+// Export
+// ============================================================================
+
+export const UTM_ENRICHER_VERSION = '1.0.0';
+
+export default {
+  obfuscateValue,
+  deobfuscateValue,
+  enrichPayloadWithUTM,
+  generateObfuscatedUTM,
+  createUTMMapping,
+  hasSegmentationUTM,
+  extractFaixaFromCampaign,
+  addSegmentationToExternalId,
+  createSegmentationCustomParameter
+};

package/server-edge-tracker/schema-utm.sql

@@ -0,0 +1,80 @@
+-- ============================================================================
+-- SCHEMA UTM OBFUSCATION — Fase de Segmentação de Valor
+-- ============================================================================
+-- Este schema estende o schema.sql existente com colunas para UTMs obfuscadas
+-- e uma tabela de mapeamento para de-obfuscação no runtime.
+--
+-- Como funciona:
+-- 1. utm_mappings: mapeia hash obfuscado → valor real (configuração)
+-- 2. leads: adiciona colunas faixa_real, faixa_category (segmentação)
+-- 3. dispatch: payload enriquecido com faixa de-obfuscada para Meta CAPI
+--
+-- ============================================================================
+-- TABELA: utm_mappings (configuração de segmentação)
+-- ============================================================================
+CREATE TABLE IF NOT EXISTS utm_mappings (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  obfuscated_hash TEXT NOT NULL UNIQUE,           -- ex: "8a3f1d2b" (hash truncado de 8 chars)
+  original_value TEXT NOT NULL,                    -- ex: "700k-1M" (valor real)
+  category TEXT NOT NULL,                         -- ex: "imovel", "automotivo", "curso"
+  pixel_audience TEXT,                            -- ex: "AUDIENCE_MID" (Meta custom audience)
+  platform_specific TEXT,                          -- JSON com IDs específicos por plataforma
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+
+-- ============================================================================
+-- ÍNDICES: utm_mappings
+-- ============================================================================
+CREATE INDEX IF NOT EXISTS idx_utm_obfuscated ON utm_mappings(obfuscated_hash);
+CREATE INDEX IF NOT EXISTS idx_utm_category ON utm_mappings(category);
+
+-- ============================================================================
+-- ALTER: leads (adicionar colunas de segmentação)
+-- ============================================================================
+ALTER TABLE leads ADD COLUMN IF NOT EXISTS faixa_obfuscada TEXT;       -- Hash da faixa de valor (vem da URL)
+ALTER TABLE leads ADD COLUMN IF NOT EXISTS faixa_real TEXT;            -- Valor real de-obfuscado (ex: "700k-1M")
+ALTER TABLE leads ADD COLUMN IF NOT EXISTS faixa_category TEXT;         -- Categoria do produto (ex: "imovel")
+
+-- ============================================================================
+-- ÍNDICES: leads (novas colunas para segmentação)
+-- ============================================================================
+CREATE INDEX IF NOT EXISTS idx_leads_faixa_real ON leads(faixa_real);
+CREATE INDEX IF NOT EXISTS idx_leads_faixa_category ON leads(faixa_category);
+CREATE INDEX IF NOT EXISTS idx_leads_faixa_obfuscada ON leads(faixa_obfuscada);
+
+-- ============================================================================
+-- VIEW: leads_segmented (para queries de segmentação)
+-- ============================================================================
+CREATE VIEW IF NOT EXISTS leads_segmented AS
+SELECT
+  l.id,
+  l.user_id,
+  l.event,
+  l.event_id,
+  l.email,
+  l.phone,
+  l.city,
+  l.state,
+  l.faixa_obfuscada,
+  l.faixa_real,
+  l.faixa_category,
+  l.created_at,
+  l.value,
+  l.intent_score,
+  l.ltv_class,
+  -- Meta CAPI: custom audience de-obfuscada
+  u.pixel_audience AS meta_custom_audience
+FROM leads l
+LEFT JOIN utm_mappings u ON l.faixa_obfuscada = u.obfuscated_hash;
+
+-- ============================================================================
+-- EXEMPLO: Query para exportar leads por faixa de valor (para Meta Custom Audience)
+-- ============================================================================
+-- SELECT email, phone, city, state, faixa_real, meta_custom_audience
+-- FROM leads_segmented
+-- WHERE faixa_category = 'imovel' AND faixa_real = '700k-1M'
+--   AND created_at >= datetime('now', '-30 days');
+--
+-- Isso gera um CSV pronto para upload como Custom Audience na Meta.
+-- ============================================================================

package/server-edge-tracker/types.ts

@@ -3,7 +3,7 @@
  * Tipos para o Cloudflare Worker e bindings
  */
 
-import { D1Database, KVNamespace, R2Bucket } from '@cloudflare/workers-types';
+import { D1Database, KVNamespace, Queue, R2Bucket } from '@cloudflare/workers-types';
 
 // ── Environment Bindings ─────────────────────────────────────────────────────
 export interface Env {
@@ -22,6 +22,9 @@ export interface Env {
   // Rate Limiter
   RATE_LIMITER?: any;
 
+  // Queue — Retry de eventos com falha de rede
+  RETRY_QUEUE?: Queue<QueueMessage>;
+
   // Public Variables
   META_PIXEL_ID?: string;
   GA4_MEASUREMENT_ID?: string;