Authentication

Fluxy's Official Authentication Module (fluxy_auth) provides a secure and reactive way to manage user identity, session tokens, and access control under the unified platform layer.

Installation

Add the authentication module to your project:

fluxy module add auth

Initialization

In the "Platform Era", use Fluxy.autoRegister() to initialize the authentication module along with other platform services.

void main() async {
  await Fluxy.init();
  Fluxy.autoRegister(); // Automatically boots auth and session tracking
  
  runApp(MyApp());
}

Core Functionality

1. User Login

The login method handles credential verification and automatically populates the reactive user signal via the unified platform API.

final success = await Fx.platform.auth.login("user@email.com", "password123");

if (success) {
  print("Welcome, ${Fx.platform.auth.user.value?['name']}");
}

2. Reactive Auth State (Session Tracking)

Everything in fluxy_auth is reactive. You can rebuild your UI automatically using the isAuthenticated signal.

Fx(() {
  if (Fx.platform.auth.isAuthenticated.value) {
    return DashboardView();
  }
  return LoginView();
});

Security & Session Management

Secure Persistence

By default, session tokens are securely encrypted and persisted using the standard Fluxy Platform Storage abstraction. You don't need to manually check for a "logged in" state in onInit.

Session Termination

Terminate a session instantly across all framework layers:

void logout() {
  Fx.platform.auth.logout();
  Fluxy.offAll('/login');
}

In-Depth: User Data

The Fx.platform.auth.user signal is a Map<String, dynamic>? that contains the identity payload returned by your backend. It remains synchronized across the entire application.

// Accessing profile data anywhere
final avatar = Fx.platform.auth.user.value?['avatar_url'];
final role = Fx.platform.auth.user.value?['role'];

Why Use FluxAuth? (Production Benefits)

Using the managed fluxy_auth module provides several industrial-grade advantages over manual implementation:

1. Global Reactive Synchronicity: A single call to logout() instantly updates every widget and service across the entire platform.
2. Zero-Config Interceptors: The networking layer (Fx.http) automatically communicates with the auth module to inject security tokens into headers.
3. Encrypted Session Management: Tokens are safely stored in the managed "Security Sandbox," protected from common persistence leaks.
4. Perspective-Based Routing: Use Fx.cond to define your app's top-level structure based on the auth state, ensuring users never see inconsistent UI states.

Comparison Table

1. Always use reactive builders: Wrap your auth-dependent UI in Fx() to ensure instant updates.
2. Combine with Biometrics: For high-security apps, use Fx.platform.auth alongside Fx.platform.biometric to gate sensitive actions.
3. Use Interceptors: Fluxy's networking layer automatically picks up your auth token for authenticated requests.

The Master Auth Implementation

In a professional application, authentication is orchestrated within FluxController to manage session transitions and secure hardware gates. Here is a complex "Secure Vault Login" implementation.

class VaultController extends FluxController {
  final isLoading = flux(false);
  
  // 1. Reactive Auth State Monitoring
  @override
  void onInit() {
    super.onInit();
    fluxEffect(() {
        if (!Fx.platform.auth.isAuthenticated.value) {
            Fx.toNamed('/login');
        }
    });
  }

  Future<void> openVault() async {
    // 2. Secondary Biometric Gate for sensitive data
    final isHuman = await Fx.platform.biometric.authenticate(
      reason: 'Please scan fingerprint to unlock vault',
    );

    if (isHuman) {
        isLoading.value = true;
        try {
            // 3. Authenticated Data Fetching
            final data = await Fx.http.get('/api/vault/secrets');
            Fx.toast.success("Vault Unlocked");
        } catch (e) {
            Fx.log.fatal("Vault Error", error: e);
        } finally {
            isLoading.value = false;
        }
    }
  }

  void onLogout() {
    // 4. Atomic Session Termination
    Fx.platform.auth.logout();
    Fx.toNamed('/login');
  }
}

By centralizing all hardware knowledge under the Fx.platform.auth helper, you ensure that your diagnostics and analytics are consistent and easy to maintain across all target platforms.