Geo Integrity Score Plugin #

Overview #

Geo Integrity Score is a Flutter plugin that validates the trustworthiness of live GPS coordinates by combining operating system APIs, motion sensors, and environment hardening checks on Android and iOS. The plugin exposes a real-time detection stream and configurable monitoring policies to balance accuracy, responsiveness, and power consumption.

Key Features #

• Multi-layer fraud scoring (OS mock location APIs, sensor consistency, environment hardening).
• Real-time detection stream via EventChannel with immediate fraud callbacks.
• Configurable monitoring modes to tune sampling intervals and sensor warm-up behavior.
• Unified fraud score schema across Android and iOS for consistent downstream handling.
• Extensible architecture that keeps detection logic isolated from Flutter channel wiring.

Detection Pipeline #

1. Acquire the most recent location fix through LocationManager (Android) or CLLocationManager (iOS).
2. Execute OS-level mock location checks (Android) before sensor warm-up to quickly flag obvious spoofing.
3. Register accelerometer and barometer listeners based on the active MonitoringPolicy warm-up interval.
4. Evaluate motion and altitude consistency once sufficient sensor samples are collected.
5. Run environment hardening heuristics (emulator, root, jailbreak) to surface tampered runtimes.
6. Aggregate triggered checks into a fraud score and emit the normalized payload over the Flutter channel.

Platform Requirements #

Android #

• Minimum API level: 21.
• Manifest permissions: ACCESS_FINE_LOCATION, ACCESS_COARSE_LOCATION.
• Optional: ACCESS_BACKGROUND_LOCATION if background monitoring is required.
• Services used: LocationManager, SensorManager, AppOpsManager.

iOS #

• Minimum deployment target: iOS 13.
• Info.plist keys: NSLocationWhenInUseUsageDescription (and optionally NSLocationAlwaysAndWhenInUseUsageDescription).
• Frameworks: CoreLocation, CoreMotion, CoreBluetooth (optional for future enhancements).

Flutter API Surface #

class GeoIntegrityScore {
  /// Emits detection events with the latest fraud score and detail map.
  static Stream<DetectionResult> get detectionStream;

  /// Starts the native monitoring pipeline with the provided policy.
  static Future<void> startMonitoring({
    MonitoringPolicy policy = MonitoringPolicy.balanced(),
  });

  /// Stops the native monitoring pipeline and releases sensors.
  static Future<void> stopMonitoring();

  /// Performs a single burst detection and returns the result once complete.
  static Future<DetectionResult> detectOnce({
    MonitoringPolicy? policyOverride,
  });
}

class DetectionResult {
  final DateTime timestamp;
  final int fraudScore;
  final Map<String, int> details;
  final String platform; // "android" or "ios"
}

MonitoringPolicy #

class MonitoringPolicy {
  final MonitoringMode mode;
  final Duration evaluationInterval;
  final Duration sensorWarmup;
  final bool autoStopOnIdle;
  final double speedThresholdOverride;

  const MonitoringPolicy._({
    required this.mode,
    required this.evaluationInterval,
    required this.sensorWarmup,
    required this.autoStopOnIdle,
    required this.speedThresholdOverride,
  });

  factory MonitoringPolicy.aggressive() => MonitoringPolicy._(
        mode: MonitoringMode.aggressive,
        evaluationInterval: const Duration(seconds: 1),
        sensorWarmup: const Duration(milliseconds: 300),
        autoStopOnIdle: false,
        speedThresholdOverride: 120.0,
      );

  factory MonitoringPolicy.balanced() => MonitoringPolicy._(
        mode: MonitoringMode.balanced,
        evaluationInterval: const Duration(seconds: 3),
        sensorWarmup: const Duration(milliseconds: 500),
        autoStopOnIdle: true,
        speedThresholdOverride: 100.0,
      );

  factory MonitoringPolicy.lowPower() => MonitoringPolicy._(
        mode: MonitoringMode.lowPower,
        evaluationInterval: const Duration(seconds: 8),
        sensorWarmup: const Duration(milliseconds: 800),
        autoStopOnIdle: true,
        speedThresholdOverride: 90.0,
      );

  factory MonitoringPolicy.onDemand() => MonitoringPolicy._(
        mode: MonitoringMode.onDemand,
        evaluationInterval: const Duration(seconds: 2),
        sensorWarmup: const Duration(milliseconds: 400),
        autoStopOnIdle: true,
        speedThresholdOverride: 100.0,
      );
}

enum MonitoringMode { aggressive, balanced, lowPower, onDemand }

Monitoring Policies & Evaluation Timing #

• Each native detector evaluates fraud once the configured evaluationInterval (Dart) / evaluationIntervalMillis (native) elapses.
• A rolling buffer of up to six recent locations is maintained to compute displacement and speed deltas.
• sensorWarmup values drive accelerometer sampling frequency before sensor inconsistency rules execute.
• When autoStopOnIdle is true and no checks fire for a cycle, monitoring stops to conserve resources.

Usage Example #

final subscription = GeoIntegrityScore.detectionStream.listen((event) {
  if (event.fraudScore >= 50) {
    // Notify user, trigger remediation, or block high-risk flows.
  }
});

await GeoIntegrityScore.startMonitoring(
  policy: MonitoringPolicy.balanced(),
);

// Later, when monitoring is no longer required.
await GeoIntegrityScore.stopMonitoring();
await subscription.cancel();

Layered Fraud Checks #

Android Detection Layers #

iOS Detection Layers #

The final fraudScore is the sum of all triggered detail scores. Application logic should define remediation thresholds.

Detection Result Payload #

• fraudScore (int): Aggregated sum of all triggered checks.
• details (Map<String, int> / [String: Int]): Individual check keys and their contribution.
• platform (String): Either "android" or "ios", mirroring the native emitter.
• location (optional map): Latest latitude/longitude plus accuracy, altitude, and speed when available.

Both native detectors publish identical schemas so downstream consumers can apply shared policies.

Native Architecture Summary #

Android (Kotlin) #

• AndroidGpsDetector orchestrates location acquisition, sensor sampling, and scoring.
• Components:
  1. LocationProvider: Retrieves latest GPS fix, validates permissions.
  2. MockApiInspector: Evaluates mock location APIs (isFromMockProvider, AppOpsManager, legacy settings).
  3. SensorInconsistencyAnalyzer: Uses SensorManager for accelerometer/barometer sampling and computes deltas.
  4. EnvironmentHardeningInspector: Checks emulator fingerprints and root traces.
• Results are emitted through an EventChannel sink; coroutine scopes ensure non-blocking evaluations.

iOS (Swift) #

• IosGpsDetector coordinates CLLocationManager, CMMotionManager, and CMAltimeter.
• Components:
  1. LocationService: Maintains delegate callbacks and buffers at least three recent locations.
  2. MotionSampler: Streams accelerometer/gyroscope data with configurable warm-up.
  3. SensorInconsistencyAnalyzer: Calculates speed, motion correlation, and pressure alignment.
  4. EnvironmentHardeningInspector: Detects simulators and jailbreak indicators.
• Native results are serialized to dictionaries and pushed through the same EventChannel schema.

Performance & Power Considerations #

• Adaptive Sampling: Each MonitoringPolicy defines evaluation intervals and sensor warm-up windows to reduce continuous high-frequency sampling.
• Idle Auto-stop: When no significant movement is detected for a policy-defined grace period, the native layer pauses sensor listeners until motion resumes.
• Burst Detection: detectOnce triggers a focused evaluation without keeping sensors active, ideal for check-in flows.
• Lifecycle Awareness: Native modules release resources on app pause/background; Flutter side should restart monitoring when resumes if required.
• Data Smoothing: Rolling averages and hysteresis thresholds mitigate noise-induced false positives before raising the fraud score.

Error Handling #

• NO_PERMISSION: Location permission missing or revoked mid-session.
• LOCATION_UNAVAILABLE: GPS fix cannot be acquired within the policy timeout.
• SENSOR_TIMEOUT: Motion sensor data not delivered within the expected warm-up window.
• STREAM_CLOSED: Event channel subscription was cancelled while monitoring is active.

Callers should handle these errors by prompting for permissions, retrying with relaxed policies, or aborting sensitive operations.

Testing Strategy #

• Dart: Use MethodChannel and EventChannel mocks to validate serialization, streaming behavior, and error propagation. Focus on stream subscription lifecycle tests and mapping to DetectionResult models.
• Android: Unit-test scoring functions with synthetic location/sensor inputs. Instrumented tests can verify integration with LocationManager and SensorManager using dependency injection.
• iOS: Unit-test speed and motion calculations in isolation. UI tests are not required; integration tests focus on verifying native-to-Flutter serialization.

Roadmap #

1. Implement Dart API contracts and mock-based tests.
2. Deliver Android native module with dependency injection-friendly structure.
3. Deliver iOS native module mirroring Android scoring schema.
4. Add optional background monitoring support once compliance considerations are addressed.