io.github.dgtalquantumleap-ai/vigil-fraud-alert

Add a travel plan to a card. In travel mode, any transaction in a matching destination_country within [start_date, end_date] is approved without GPS check. Multiple overlapping plans are supported (e.g. US + MX for a road trip).

Run Claude Haiku analysis on a transaction or pending authorization. Returns: risk_score 0–100 integer (100 = certain fraud) risk_factors Array of plain-English factors (location mismatch, late hour, etc.) recommended_action "block" | "confirm" | "allow" alert_message Ready-to-send SMS copy (160 chars, ends with YES=confirm NO=block) explanation 1–2 sentence plain-English reasoning Use this AFTER vigil_authorize to enrich the decision with AI context, or call it independently before authorizing to pre-score a transaction. Falls back to rules-based scoring if Anthropic API is unreachable.

Core fraud detection entry point. Runs a transaction through Vigil's proximity engine and returns an approve/decline decision. Decision priority: 1. Inactive card → CARD_INACTIVE (decline) 2. LOCKDOWN mode → LOCKDOWN (decline) 3. TRAVEL + plan match → TRAVEL_MATCH (approve) 4. No GPS on file → NO_GPS_ON_FILE (decline) 5. Spoofed/rooted → SPOOFED_DEVICE (decline) 6. GPS 5–15 min old → GPS_STALE_SOFT (decline) 7. GPS >15 min old → GPS_STALE_HARD (decline) 8. Within radius → IN_RADIUS (approve) 9. Outside radius → OUTSIDE_RADIUS (decline) Auto-creates a FraudAlert for OUTSIDE_RADIUS, SPOOFED_DEVICE, and LOCKDOWN declines. Returns transaction_id and optionally alert_id.

Immediately lock a card (set mode=lockdown) and escalate any open alerts. Use when: - User confirmed fraud via "Was this you? NO" response - AI analysis returns recommended_action="block" - Analyst manually confirms suspicious activity What this does: 1. Sets card.mode = 'lockdown' (all future transactions declined instantly) 2. Escalates all open alerts for this card to status='investigating' 3. Returns summary of actions taken NOTE: Final blocking authority rests with the user or analyst — this tool executes the block but should only be called after confirmation. Stripe/Lithic card cancellation must be called separately in production.

Record user response to "Was this you?" push notification. confirmed="yes" — user made this transaction (marks a blocked txn as false positive) confirmed="no" — user did NOT make this transaction (escalates alert to investigating) This data feeds directly into risk score calculation and fraud analytics.

Generate a professional AML/fraud compliance report for a card using Claude Sonnet. Produces a structured report with: - Executive Summary - Incident Timeline (all declined transactions in period) - Risk Assessment with score breakdown - Recommended Actions - Compliance Notes (for bank/regulator submission) Use for: - Monthly fraud review submission to Stripe/Lithic - AML regulatory filing - Internal fraud review Returns report_id, summary (200 chars), and full_report (full text).

Get a card's current config: mode, radius, home location, travel plans. Also returns gps_age_minutes so you can assess GPS freshness before authorizing.

Get the risk profile for a card. Recalculates live from transaction history. risk_score 0.0–1.0 weighted: 40% block rate | 20% false-positive rate | 30% outside-radius count | 10% lockdown usage anomaly_reason: plain-English explanation set by the async AI analyser (Claude Haiku).

List fraud alerts. Filter by card_id, status, or severity. Auto-created for OUTSIDE_RADIUS, SPOOFED_DEVICE, and LOCKDOWN declines. Severity: critical (SPOOFED/LOCKDOWN), high (distance >5000km), medium (distance ≤5000km). Statuses: open → investigating → resolved | false_positive

List transaction decisions. Filter by card_id and/or approval outcome. Returns full records: merchant, amount, reason_code, distance_km, GPS coords, processing_ms. Ordered most-recent first. Max 100 per call.

Advance a fraud alert through the investigation workflow and append notes. Typical flow: open → investigating (analyst picks it up) investigating → resolved (confirmed fraud, card actioned) investigating → false_positive (user confirmed it was them) Notes are appended with a timestamp — not replaced.

Switch card operating mode: home | travel | lockdown. home — proximity-based auth against GPS + configured radius travel — country-match auth using active travel plans; falls back to proximity lockdown — all transactions declined, no exceptions, instant effect

Push a fresh GPS snapshot for a card. Called by the mobile app on significant-change events (>100m move) and every 60s while foregrounded. GPS freshness is critical to authorization: >5 min old → GPS_STALE_SOFT decline >15 min old → GPS_STALE_HARD decline Set is_mock_location=true or is_jailbroken=true to test spoofing detection.