halo_auth #

A Flutter plugin for multi-platform authentication with support for Android, iOS, Windows, and Linux. Provides device-specific authentication flows with clean architecture.

Features #

• ✅ Multi-Platform Support: Android, iOS, Windows, and Linux
• ✅ Platform-Specific Authentication:
  • Android: Mobile devices use Android ID, TV devices use Content Provider
  • iOS: MDM configuration support with CERT_ID
  • Windows: Registry-based device identification
  • Linux: Environment file-based configuration
• ✅ Clean Architecture: Domain, Data, and Presentation layers
• ✅ Automatic Retry Logic: Handles device enrollment with retry mechanisms
• ✅ Error Handling: Comprehensive error handling with user-friendly UI feedback
• ✅ Token Management: Returns authentication tokens with device ID

Supported Platforms #

• ✅ Android (Mobile & TV)
• ✅ iOS
• ✅ Windows
• ✅ Linux

Installation #

Add this to your package's pubspec.yaml file:

dependencies:
  halo_auth: ^0.0.1

Then run:

flutter pub get

Usage #

Basic Usage #

import 'package:halo_auth/halo_auth.dart';

final haloAuth = HaloAuth();

// Authenticate with baseUrl and optional context
final tokens = await haloAuth.authenticate(
  'https://portal.qa.halofort.com',
  context: context, // Optional: for showing UI dialogs
);

// Access tokens
print('Token: ${tokens.token}');
print('Refresh Token: ${tokens.refreshToken}');
print('Device ID: ${tokens.deviceId}');

With Error Handling #

try {
  final tokens = await haloAuth.authenticate(
    'https://portal.qa.halofort.com',
    context: context,
  );
  
  // Use tokens
  setState(() {
    _token = tokens.token;
    _refreshToken = tokens.refreshToken;
    _deviceId = tokens.deviceId;
  });
} catch (e) {
  // Handle authentication errors
  print('Authentication failed: $e');
}

Optional: Initialize First #

You can also initialize the plugin separately if needed:

await haloAuth.initialize(
  'https://portal.qa.halofort.com',
  context: context,
);

// Later, authenticate
final tokens = await haloAuth.authenticate(
  'https://portal.qa.halofort.com',
  context: context,
);

Platform-Specific Configuration #

Android #

Mobile Devices:

• Uses Settings.Secure.ANDROID_ID as device identifier
• Requires internet permission (already included)

TV Devices:

• Reads tokens from Content Provider: content://com.example.providerapp.provider/data
• Returns tokens directly without API calls

Permissions (AndroidManifest.xml):

<uses-permission android:name="android.permission.INTERNET" />

iOS #

• Reads MDM configuration from UserDefaults (com.apple.configuration.managed)
• Uses CERT_ID from MDM config as device identifier
• Falls back to identifierForVendor if MDM config is unavailable

Windows #

• Reads device ID from registry: HKEY_USERS\.DEFAULT\Software\HaloAgent\DEVICE_ID
• Reads API URL from registry: HKEY_USERS\.DEFAULT\Software\HaloAgent\API_URL (Base64 encoded)
• Automatically decodes API URL

Linux #

• Reads configuration from: /etc/haloagent/app.env
• Required environment variables:
  • DEVICE_ID
  • API_URL
  • WS_URL (optional)
  • REPORTING_URL (optional)

API Endpoints #

The plugin uses the following endpoints:

• Android: GET /android/v1/devicefeedback/{deviceId}
• iOS: GET /ios/v1/devices/feedback/{deviceId}
• Windows: GET /win/v1/feedback/{deviceId}
• Linux: GET /linux/v1/feedback/{deviceId}
• Login: POST /idm/v1/auth/feedback/login

Error Handling #

The plugin includes comprehensive error handling:

• Device Not Found (400):

  • Android: Reports feedback natively and retries
  • All platforms: Retries up to 10 times with 10-second intervals
  • Shows "Device Not Enrolled" screen if all retries fail

• Network Errors: Logged via interceptor for debugging

Architecture #

The plugin follows Clean Architecture principles:

lib/
├── domain/          # Business logic
│   ├── entities/    # Domain models
│   ├── repositories/ # Repository interfaces
│   └── usecases/    # Business use cases
├── data/            # Data layer
│   ├── datasources/ # Remote, local, platform data sources
│   ├── models/      # Data models
│   └── repositories/ # Repository implementations
├── presentation/    # UI layer
│   └── screens/     # Flutter screens
└── core/            # Core utilities
    ├── di/          # Dependency injection
    └── interceptors/ # Dio interceptors

Dependencies #

• dio: ^5.4.0 - HTTP client
• ffi: ^2.1.0 - Foreign Function Interface (Windows)
• win32: ^5.5.0 - Windows API bindings

Example #

See the example/ directory for a complete example.

Contributing #

Contributions are welcome! Please feel free to submit a Pull Request.

License #

[Add your license here]

Support #

For issues and feature requests, please use the GitHub issue tracker.