flutter_lan_sync 0.1.0

Production-grade offline LAN sync for Flutter apps. Peer-to-peer transfer of any JSON-serialisable data over Wi-Fi using X25519 ECDH + AES-256-GCM encryption, HMAC app-identity verification, UDP broad [...]

flutter_lan_sync

Offline peer-to-peer data exchange for Flutter apps on the same local network. The package supports explicit, user-approved item transfers and an optional CRDT-based background sync flow without requiring internet connectivity.

Features

• UDP broadcast discovery on local Wi-Fi networks.
• Authenticated device handshakes with application, facility, and instance scoping.
• X25519 key exchange, HKDF-SHA256 key derivation, and AES-256-GCM payload encryption.
• Explicit item transfer with recipient approval.
• Optional field-level CRDT synchronization with a hybrid logical clock.
• Persistent transfer history and device approval/revocation.
• Ready-made device, approval, history, and incoming-transfer widgets.

Quick Start

import 'package:flutter_lan_sync/flutter_lan_sync.dart';

await LanSync.initialize(
  LanSyncConfig(
    appSecret: 'app-specific-secret',
    packageName: 'com.example.app',
    deviceName: 'Clinic Tablet',
    facilityId: 'facility-123',
    instanceType: 'production',
    requireScopedPeers: true,
    onReceive: (items) async {
      // Validate and persist received items in the host application.
    },
  ),
);

LanSyncScreen(
  items: records
      .map((record) => LanSyncItem(
            id: record.id,
            displayName: record.name,
            data: record.toJson(),
          ))
      .toList(),
);

For incoming transfers displayed outside LanSyncScreen, wrap the app with LanTransferListener and provide a navigator key as shown in the API docs.

Security Responsibilities

The package encrypts transfer payloads and scopes peers by the configured application identity and facility/instance values. The host application must:

• Keep appSecret out of source control and supply it through a protected release mechanism.
• Validate received records before writing them to application storage.
• Use a distinct scope for each facility and deployment instance.
• Provide an explicit user approval flow for incoming data.

LAN traffic is local-network traffic, not a replacement for server-side authorization, audit, or backup controls.

Architecture

See LAN_SYNC.md for the protocol, storage model, transfer flow, CRDT behavior, and security design.

Development

flutter pub get
flutter analyze
flutter test

The package is currently published from the ViVA Mobile monorepo at packages/flutter_lan_sync.