Fraud detection for leaderboard & token abuse

[QuarkOS]

What & why

The ingest routes already enforce hard bounds (per-event duration caps, a rolling 24h active-time/visit ceiling, a domain allowlist, per-record token caps, freshness windows). Those stop the crudest inflation, but a patient scripted extension can sit just under every cap and climb the board on fabricated activity, and a client can backfill impossible token totals onto the Burn Board.

This PR adds the missing detection layer: it runs over what actually landed in the database, looks for the behavioural signatures the hard caps can't express, raises deduped flags, alerts staff, and gives staff a review queue to confirm (optionally suspending) or dismiss.

How it works

Detection engine — src/lib/fraudDetection.ts (pure, deterministic)
Seven evidence-based detectors, biased for precision (each carries the raw numbers it fired on, for audit):

Signal	Surface	Catches
activity_ceiling_pinning	activity	Banking >=90% of the 16h/day active ceiling day after day
impossible_concurrency	activity	Verified active time far exceeding the day's wall-clock span (parallel forged streams)
visit_flooding	activity	Near-ceiling visits with negligible active time (flat 40-pt visit padding)
uniform_duration_padding	activity	One duration value dominating a large heartbeat sample (scripted client)
token_impossible_rate	token	Sustained billions of tokens/day — not a real agent workload
token_spike	token	A single day dwarfing the user's own median (backfilled dump)
token_cost_mismatch	token	Huge token totals with implausible cost/token (gaming the cost-ordered Burn Board)

assessUserFraud rolls signals up per category into a capped 0–100 risk score, a level band, and a stable dedupe fingerprint.

Persistence & orchestration — src/lib/fraudDetectionServer.ts + migration 061

• fraud_flags table (service-role only): one row per (user, category), deduped by fingerprint, with open/confirmed/dismissed triage state and an audit-friendly signal snapshot.
• The service layer fetches a user's recent activity + token history, assesses it, upserts flags (a recurring pattern refreshes the row and bumps detection_count without resurrecting a staff decision), and alerts every staff member once per newly-opened flag. Everything is best-effort and never throws.
• sweepFraudSignals scans the competitive-board candidate set (top scorers + Burn Board opt-ins) and piggybacks the existing leaderboard-integrity cron (same Vercel cron-budget reason as the sponsor sweep).

Staff surface

• abuse.review staff action at the moderator floor.
• GET /api/admin/abuse — worst-first queue with per-status counts and the flagged account's identity.
• POST /api/admin/abuse/[id]/review — confirm/dismiss (audit-first, target-guarded, status-guarded, reason required), with optional suspend on confirm via the shared moderation path.
• /admin/abuse review-queue page (mirrors the Teams queue) + a nav entry under Review.

Testing

• 31 new unit tests (engine + server layer with a mock Supabase client). Full suite: 990 passing (was 959).
• typecheck, lint, audit:prod (0 vulns), and next build all green; new routes compile (/admin/abuse, /api/admin/abuse, /api/admin/abuse/[id]/review).
• Ran the real engine over synthetic histories — a heavy-but-human user is CLEAN (no false positives), while an activity cheater and a token cheater both hit critical risk with the expected signals:

=== Clean heavy-but-human user ===
  verdict: CLEAN — no signals fired

=== Activity cheater (scripted extension) ===
  [activity] level=critical risk=100/100
     - (high, +58) activity_ceiling_pinning: Banked >=90% of the 16h/day active-time ceiling on 6 day(s)
     - (high, +55) impossible_concurrency: Active time exceeded the wall-clock window 2.50x — parallel activity streams

=== Token cheater (fabricated Burn Board) ===
  [token] level=critical risk=100/100
     - (high, +50) token_impossible_rate: Reported >=2,000,000,000 tokens/day on 2 day(s)
     - (high, +35) token_spike: One day reported 2609x the median token day — backfilled spike
     - (medium, +20) token_cost_mismatch: Reported 5,804,200,000 tokens for $12.00 — implausible cost/token

A screenshot of the review-queue UI (rendered with the real admin component kit) is attached to the companion PR on the fork. Live admin-panel interaction needs an authenticated staff session against a real Supabase, so the queue was rendered via a temporary preview route (removed before commit). The detection engine — the novel, high-risk part — is proven end-to-end by unit tests and the runtime demo above.

Deploy notes

• Apply migrations/061_fraud_flags.sql (creates the table; ends with NOTIFY pgrst). Thresholds live in DEFAULT_FRAUD_POLICY and can be tuned without schema changes.
• No new cron entry needed — the sweep rides the existing /api/cron/leaderboard-integrity schedule.

Possible follow-ups (not in this PR)

• Cross-account device-sharing detection (multiple accounts on one device_uuid).
• A fraud-flag panel on the per-user admin dossier.
• Auto-exclusion of confirmed accounts from the canonical leaderboard ranker.

---

_{Opened from fork QuarkOS/Cribble (branch cursor/fraud-detection-leaderboard-e229).}

[vercel]

@cursoragent is attempting to deploy a commit to the BIRDABO Team on Vercel.

A member of the Team first needs to authorize it.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.