DartStream Magic Authentication Provider #

A DartStream authentication provider implementing Magic Authentication services.

Features #

• Passwordless authentication via Magic DID tokens
• Token management
• Session handling
• Error mapping
• Event system integration
• Lifecycle management

Installation #

1. Add to your pubspec.yaml:

dependencies:
  # Magic Authentication provider for DartStream
  ds_magic_auth_provider: ^0.0.3

  # Base authentication package
  ds_auth_base: ^0.0.1

  # Framework features
  ds_standard_features: ^0.0.8

Usage #

Basic Setup #

import 'package:ds_auth_base/ds_auth_base_export.dart';
import 'package:ds_magic_auth_provider/ds_magic_auth_provider.dart';

// Initialize Magic Provider with your keys
final magicProvider = DSMagicAuthProvider(
  publishableKey: 'your-magic-publishable-key',
  secretKey: 'your-magic-secret-key',
);
await magicProvider.initialize({
  'publishableKey': 'your-magic-publishable-key',
  'secretKey': 'your-magic-secret-key',
});

// Register with DartStream Auth Manager
DSAuthManager.registerProvider('magic', magicProvider);

Architecture #

Components #

1. Provider (ds_magic_auth_provider.dart)

   • Implements the DSAuthProvider interface
   • Integrates with Magic’s DID token API

2. Token Manager (ds_token_manager.dart)

   • Handles DID token storage, validation, expiration

3. Session Manager (ds_session_manager.dart)

   • Manages user sessions in memory

4. Error Mapper (ds_error_mapper.dart)

   • Maps Magic API errors to DSAuthError

5. Event Handlers (ds_event_handlers.dart)

   • Hooks for login/logout events

Implementation Status #

Completed Features #

• ✅ Initialization (initialize)
• ✅ Passwordless sign-in (signIn using DID token)
• ✅ Sign-out (signOut)
• ✅ Current user retrieval (getCurrentUser)
• ✅ Token verification (verifyToken)
• ✅ Session management via DSSessionManager
• ✅ Error mapping with DSMagicErrorMapper
• ✅ Lifecycle hooks (onLoginSuccess, onLogout)

Limitations & Notes #

• No getUser support: Magic API doesn’t provide direct user lookup; store user info after sign-in if needed.
• No refreshToken: DID tokens are short-lived; re-authentication required.
• No MFA/Groups/Audit Logs: Not offered by Magic’s API.

Enhanced Usage Examples #

// Magic link flow: front-end obtains DID token and sends it to backend
final didToken = await magicSdk.loginWithMagicLink('user@example.com');
await magicProvider.signIn('user@example.com', didToken);

// Listen to login success event
magicProvider.onLoginSuccess((user) {
  print('User signed in: ${user.uid}');
});

// Validate token
final valid = await magicProvider.verifyToken(didToken);
print('Token valid: $valid');

Testing #

Running Tests #

# Run all tests for Magic provider
cd packages/standard/standard_extensions/auth/providers/magic
dart test

Test Coverage #

• Passwordless Authentication flows
• Token management edge cases
• Session creation/removal
• Error handling scenarios
• Lifecycle event triggers

Production Setup #

1. Obtain Magic Keys

   • Create a Magic account and get publishable & secret keys

2. Secure Storage

   • Store keys in environment variables or Secret Manager

3. Configure Provider

   export MAGIC_PUBLISHABLE_KEY="your-key"
   export MAGIC_SECRET_KEY="your-secret"
   

Framework Integration #

DartStream Backend #

// In your main.dart or bootstrap
configureLogging(Tier.enterprise);
await magicProvider.initialize(...);
DSAuthManager.registerProvider('magic', magicProvider);

Flutter Integration #

import 'package:ds_flutter_mobile/ds_flutter_mobile.dart';
await DSFlutterMobileCore.initialize(
  defaultAuthProvider: 'magic',
  enableLogging: true,
);

Security Features #

• No passwords stored or transmitted
• DID token verification via Magic API
• In-memory session handling
• Standardized error reporting

Troubleshooting #

• Uninitialized provider: Ensure initialize is called before use.
• Invalid DID token: Verify token with verifyToken method.
• Missing hooks: Check that event handlers are registered.

Performance Considerations #

• Lightweight in-memory session manager
• No heavy Crypto operations on every request
• Single HTTP call to Magic API for token verification

Status: Production Ready 🚀 #

The Magic authentication provider is complete and production-ready with passwordless login, robust session management, and comprehensive testing.