locorda_solid_auth_worker

Solid authentication integration for Locorda's worker architecture.

Overview

This package bridges Solid authentication between main thread and worker isolate/thread. It synchronizes authentication state and credentials from the main thread's SolidAuth to the worker, where they're used for authenticated HTTP requests.

Architecture

Main Thread: SolidAuthConnector

The SolidAuthConnector runs on the main thread and:

Listens to SolidAuth.isAuthenticatedNotifier for state changes
Extracts DPoP credentials and WebID when authenticated
Sends UpdateAuthMessage to worker via WorkerChannel
Clears credentials in worker when logged out

Worker Thread: WorkerSolidAuthProvider

The WorkerSolidAuthProvider runs in the worker and:

Receives authentication updates via WorkerChannel
Implements SolidAuthProvider interface for SolidBackend
Generates DPoP tokens locally using transmitted credentials
Provides isAuthenticatedNotifier to trigger backend initialization

Usage

Main Thread Setup

import 'package:solid_oidc_auth/solid_oidc_auth.dart';
import 'package:locorda/locorda.dart';
import 'package:locorda_solid_auth_worker/locorda_solid_auth_worker.dart';

// Initialize SolidAuth
final solidAuth = SolidAuth(...);
await solidAuth.init();

// Setup Locorda with worker and SolidAuthConnector plugin
final sync = await Locorda.createWithWorker(
  engineParamsFactory: createEngineParams,
  jsScript: 'worker.dart.js',
  plugins: [
    SolidAuthConnector.sender(solidAuth),
  ],
  // ... other config
);

Worker Thread Setup

import 'package:locorda_worker/locorda_worker.dart';
import 'package:locorda_solid_auth_worker/locorda_solid_auth_worker.dart';
import 'package:locorda_solid/locorda_solid.dart';

Future<EngineParams> createEngineParams(
  SyncEngineConfig config,
  WorkerContext context,
) async {
  // Create auth provider from worker context
  final authProvider = SolidAuthConnector.receiver(context);
  
  // Use in SolidBackend
  final backend = SolidBackend(auth: authProvider);
  
  // Backend automatically initializes remotes when authenticated
  
  // ... create storage and return EngineParams
  return EngineParams(
    storage: storage,
    backends: [backend],
  );
}

How It Works

Login on Main Thread: User logs in via SolidAuth.login()
State Change Detected: SolidAuthConnector receives notification via isAuthenticatedNotifier
Credentials Extracted: DPoP credentials and WebID extracted from SolidAuth
Message Sent: UpdateAuthMessage sent to worker via channel
Worker Updated: WorkerSolidAuthProvider updates internal state
Listeners Notified: isAuthenticatedNotifier in worker notifies SolidBackend
Backend Initializes: SolidBackend creates SolidRemoteStorage with WebID

Key Features

Automatic Synchronization: Auth state changes propagate automatically from main to worker
Reactive Token Refresh: On-demand token refresh when worker detects expiry
Mobile-Friendly: No background timers, purely event-driven architecture
Local DPoP Generation: DPoP tokens generated in worker where HTTP requests happen
Minimal Serialization: Only credentials transmitted when needed
Clean Lifecycle: Proper setup/teardown via WorkerPlugin interface
Type-Safe Messages: Structured messages for auth updates and token refresh
Automatic Recovery: Worker requests fresh tokens and retries on failures

Token Refresh

Access tokens have limited lifetime (typically 1 hour). This package implements reactive token refresh to ensure uninterrupted operation:

Reactive Refresh (Primary Strategy)

SolidBackend detects 401 Unauthorized responses from Pod server
Calls authProvider.refreshToken() to request fresh credentials
Worker sends RequestTokenRefresh to main thread
Main thread calls solid_auth.exportDpopCredentials() (automatic refresh)
Worker receives fresh credentials via TokenRefreshResponse
SolidBackend retries HTTP request with fresh token
Mobile-friendly: No background timers, purely event-driven

Future: Event-Driven Proactive Refresh

Once our solid_auth fork exposes onTokenChanged stream:

Listen to token refresh events from solid_auth
Push updates immediately when tokens refreshed
Zero latency, no polling, no timers