# Fraud Detection Agent — CDP Edge Quantum Tier

## Identidade

**Agente:** Fraud Detection Agent
**Papel:** Detecção e Bloqueio Automático de Tráfego Fraudulento na Borda
**Nível:** Deus (Quantum Tier) — Enterprise-Level Fase 4
**Versão:** 1.0.0 — 9 de Abril de 2026

---

## Missão

Identificar, classificar e bloquear tráfego fraudulento (click fraud, bots, ataques de velocidade,
tráfego inválido) **antes que ele contamine o D1, os pixels de anúncio e as predições de LTV** —
protegendo o budget de ads e a qualidade dos dados de ML.

---

## Posição no Fluxo do Master Orchestrator

```
Request chega em /track
      ↓
[FASE 4 — PRÉ-PROCESSAMENTO]
checkFraudGate(env, request, payload)
  ├── KV blocklist check (IP / fingerprint)     → ~0ms — bloqueia na borda
  ├── Velocity counter KV (eventos por IP/hora) → ~1ms — detecta bursts
  └── Score de fraude heurístico                → ~0ms — sem AI, pura lógica
      ↓ [se score ≥ 80]
  Evento DESCARTADO — returns 200 (silent drop) — não alimenta D1 nem pixels
      ↓ [se score < 80]
  Evento processado normalmente (LTV + CAPI + GA4 + TikTok)
      ↓ [background]
  logFraudSignal(env, ...) → D1: fraud_signals + fraud_alerts
```

**Implementação:** `modules/ml/fraud.ts` — `checkFraudGate(env: Env, request: Request, payload: TrackPayload)` (TypeScript)

**Integração automática com fluxo `/track`:**
- Executa ANTES do LTV, fingerprinting e CAPI
- Silent drop (retorna 200 ao browser para não vazar a detecção)
- Regime de falha seguro: se o fraud gate falhar → deixa o evento passar

**Downstream (quem se beneficia):**
- `ltv-predictor-agent.md` → LTV score calculado apenas sobre tráfego limpo
- `ml-clustering-agent.md` → Segmentos ML sem contaminação de bots
- `bidding-agent.md` → Bids baseados em conversões reais

---

## Sinais de Fraude Detectados

### 1. Blocklist (KV) — Bloqueio Imediato
| Sinal | Critério | Ação |
|-------|----------|------|
| IP bloqueado | `KV: fraud_block:ip:{ip}` existe | Silent drop 200 |
| Fingerprint bloqueado | `KV: fraud_block:fp:{fingerprint}` existe | Silent drop 200 |

### 2. Velocity Attacks (KV Rate Counter)
| Sinal | Critério | Score |
|-------|----------|-------|
| IP velocity alta | > 20 eventos/hora do mesmo IP | +50 pts |
| IP velocity média | > 10 eventos/hora do mesmo IP | +25 pts |
| Burst de eventos | > 5 eventos em 60 segundos | +30 pts |

### 3. Sinais Heurísticos (sem AI)
| Sinal | Critério | Score |
|-------|----------|-------|
| Bot score alto | `bot_score >= 3` (já calculado no Worker) | +60 pts |
| Bot score médio | `bot_score == 2` | +30 pts |
| User-Agent suspeito | Contém headless, curl, bot, scrapy, python | +40 pts |
| IP de datacenter | ASN = AWS, GCP, Azure, DigitalOcean, Linode | +35 pts |
| Sem headers de browser | Accept-Language ausente | +20 pts |
| Geo impossível | IP country ≠ país esperado (BR fora da LATAM) | +10 pts |

### 4. Threshold de Ação
```
score < 40   → Limpo (processar normalmente)
score 40-79  → Suspeito (processar + logar em fraud_signals)
score ≥ 80   → Fraude confirmada (silent drop + logar + considerar blocklist)
```

---

## Endpoints Expostos

| Método | Rota | Função |
|--------|------|--------|
| `GET`  | `/api/fraud/alerts` | Lista alertas recentes com score e motivos |
| `GET`  | `/api/fraud/blocklist` | Visualiza IPs/fingerprints bloqueados |
| `POST` | `/api/fraud/blocklist/add` | Bloqueia IP ou fingerprint manualmente |
| `DELETE` | `/api/fraud/blocklist/remove` | Remove IP/fingerprint do blocklist |
| `GET`  | `/api/fraud/stats` | Estatísticas de fraude (taxa, economia de events) |

---

## Schema D1

```sql
fraud_signals    -- Registro por evento (IP, score, motivos, ação tomada)
fraud_alerts     -- Alertas agregados por IP/fingerprint (quando threshold atingido)
```

**KV Namespace (GEO_CACHE):**
```
fraud_block:ip:{ip}           → TTL configurável (default: 24h)
fraud_block:fp:{fingerprint}  → TTL configurável (default: 24h)
fraud_velocity:{ip}:h         → Contador de eventos por hora (TTL: 1h)
fraud_velocity:{ip}:m         → Contador de eventos por minuto (TTL: 1min)
```

---

## Regras de Negócio

```
✅ SEMPRE usar silent drop (200) — não vazar que detectamos fraude
✅ SEMPRE logar fraud_signals mesmo em modo 'suspeito' (score 40-79)
✅ SEMPRE deixar evento passar se o fraud gate jogar qualquer erro
✅ SEMPRE verificar KV blocklist antes de D1 (latência zero)
✅ SEMPRE incluir motivos detalhados em fraud_signals.reasons (JSON array)

❌ NUNCA retornar 403/429 ao browser (vaza a detecção, bots adaptativos)
❌ NUNCA bloquear IPs por mais de 7 dias sem confirmação manual
❌ NUNCA usar Workers AI no fraud gate — latência do /track é crítica
❌ NUNCA bloquear sem logar no D1 — auditoria é obrigatória
```

---

## Variáveis de Ambiente Requeridas

| Variável | Binding | Descrição |
|----------|---------|-----------|
| `DB` | D1 | fraud_signals, fraud_alerts |
| `GEO_CACHE` | KV | Blocklist + velocity counters (TTL por chave) |

*(Nenhum AI necessário — detecção heurística pura para latência zero)*

---

*Agente criado em conformidade com a arquitetura Quantum Tier CDP Edge — 9 de Abril de 2026*