antifraud_sdk 1.0.0

Flutter SDK for Antifraud.id integration.

Antifraud Flutter SDK

A native fraud detection and device fingerprinting SDK for Flutter mobile applications. The SDK collects hardware specifications, OS attributes, carrier metadata, location signals, and deep security diagnostics (root/jailbreak, emulator, debugger, mock location, and tampering hooks), encrypts the payload using hybrid RSA-OAEP + AES-GCM cryptography, and exchanges it for a stable session_id via the Antifraud API.

This plugin is designed to be highly secure and lightweight, utilizing platform-native APIs (Kotlin for Android, Swift for iOS) with zero third-party Dart dependencies.

---

Architecture Flow

┌────────────────────────────────────────────────────────────────────────┐
│  Merchant Flutter App                                                  │
│                                                                        │
│  ┌──────────────┐   ┌──────────────┐   ┌─────────────┐   ┌───────────┐ │
│  │  Security    │   │  Device      │   │  Hybrid     │   │  HTTP     │ │
│  │  Collector   │   │  Collector   │   │  Encryptor  │   │  Client   │ │
│  │  (root/emul/ │   │  (hardware/  │   │  (RSA OAEP  │   │  (POST    │ │
│  │   mock/debug)│   │   GPS/net)   │   │  + AES GCM) │   │  /session)│ │
│  └──────┬───────┘   └──────┬───────┘   └──────┬──────┘   └─────┬─────┘ │
│         │                  │                  │                │       │
│         └──────────────────┴──────────────────┴────────────────┘       │
│                                                     │                  │
└─────────────────────────────────────────────────────┼──────────────────┘
                                                      │
                                                      v
                                            ┌──────────────────┐
                                            │ Antifraud API    │
                                            │ POST /v1/session │
                                            │  → session_id    │
                                            └──────────────────┘

---

Features & Signals

• Stable Device Identity: UUID stored in platform-encrypted secure containers (EncryptedSharedPreferences on Android, Keychain with device-only attributes on iOS) to survive application uninstalls and reinstalls.
• Network Diagnostics: Cellular carrier name, active VPN detection, network interfaces scan, and connection type (WIFI/4G/5G/etc).
• Hardware Profile: CPU architecture, physical memory size, available storage space, screen resolution, and battery capacity/charging state.
• Security & Tamper Protections:
  • Multi-layer Root (Android) and Jailbreak (iOS) binary, path, and package detectors.
  • Emulator detection.
  • Active debugger attachment checks (via kernel ptrace sysctl flags, /proc/self/status TracerPid, and Frida maps/dyld memory scans).
  • Code hooks and framework injection detection (Frida, Xposed, Substitute/Substrate).
  • Application binary signature verification.
• Location Harvest: Coordinates and horizontal accuracy (graceful degradation to 0.0 values when permissions are absent).

---

Installation

Add the dependency to your app:

dependencies:
  antifraud_sdk: ^1.0.0

Then run flutter pub get, or use flutter pub add antifraud_sdk.

---

Platform Setup

Android Configuration

Ensure that your android/app/src/main/AndroidManifest.xml includes internet and location permissions:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <!-- Required to dispatch encrypted fingerprint payloads to the API -->
    <uses-permission android:name="android.permission.INTERNET" />
    
    <!-- Optional: Add location permissions if location signal profiling is desired -->
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
</manifest>

iOS Configuration

Declare the usage descriptions in ios/Runner/Info.plist:

<key>NSLocationWhenInUseUsageDescription</key>
<string>We collect location signals to analyze and prevent fraudulent transaction rings.</string>

---

Usage Example

1. Initialize the SDK

Initialize the SDK once, ideally at the start of your application (main() function):

import 'package:flutter/material.dart';
import 'package:antifraud_sdk/antifraud_sdk.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await Antifraud.initialize(
    AntifraudConfig(
      projectId: "your-project-uuid-here",
      publicKey: """-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAv62K/N9g5P8i...
-----END PUBLIC KEY-----""",
      apiUrl: "https://api.antifraud.id", // Optional: defaults to https://api.antifraud.id
      timeoutMs: 5000,                    // Optional: defaults to 5000ms
    ),
  );

  runApp(const MyApp());
}

2. Generate a Session ID

Call createSession() before sensitive user events like registrations, logins, or checkout checkouts. Always implement a fail-open strategy to ensure users can proceed even if a network interruption occurs:

Future<void> handleCheckout(double amount) async {
  String? sessionId;
  
  try {
    // Collect signals, encrypt, and retrieve session_id
    final SessionResult result = await Antifraud.createSession();
    sessionId = result.sessionId;
  } catch (e) {
    // Fail-open: log error but allow transaction scoring flow to degrade gracefully
    print("Antifraud session generation failed: $e");
  }

  // Forward the sessionId (which may be null) to your backend
  await myBackendApi.processOrder(
    amount: amount,
    antifraudSessionId: sessionId,
  );
}