Simplify enabling E2EE with Session API

.changes/simplify-session-e2ee

@@ -0,0 +1 @@
+minor type="added" "Simplify enabling E2EE with Session API"

lib/src/agent/session.dart

@@ -20,6 +20,8 @@ import 'package:uuid/uuid.dart';
 
 import '../core/room.dart';
 import '../core/room_preconnect.dart';
+import '../e2ee/key_provider.dart';
+import '../e2ee/options.dart';
 import '../events.dart';
 import '../logger.dart';
 import '../managers/event.dart';
@@ -150,6 +152,7 @@ class Session extends DisposableChangeNotifier {
   final _TokenSourceConfiguration _tokenSourceConfiguration;
 
   final Agent _agent = Agent();
+  bool _isStarting = false;
   Agent get agent => _agent;
 
   SessionError? get error => _error;
@@ -175,12 +178,19 @@ class Session extends DisposableChangeNotifier {
   EventsListener<RoomEvent>? _roomListener;
   Timer? _agentTimeoutTimer;
 
+  /// Enables or disables end-to-end encryption for the session.
+  ///
+  /// Requires that encryption was configured via [SessionOptions.encryption]
+  /// or that the [Room] was created with [E2EEOptions].
+  Future<void> setEncryptionEnabled(bool enabled) => room.setE2EEEnabled(enabled);
+
   /// Starts the session by fetching credentials and connecting to the room.
   Future<void> start() async {
-    if (room.connectionState != ConnectionState.disconnected) {
+    if (_isStarting || room.connectionState != ConnectionState.disconnected) {
       logger.info('Session.start() ignored: room already connecting or connected.');
       return;
     }
+    _isStarting = true;
 
     _setError(null);
     _agentTimeoutTimer?.cancel();
@@ -197,6 +207,29 @@ class Session extends DisposableChangeNotifier {
     }
 
     try {
+      // Configure E2EE on the room before connecting if encryption options
+      // are set. Skipped when a custom room was provided, since the user is
+      // responsible for configuring E2EE on the room directly.
+      final encryption = _options.encryption;
+      if (encryption != null && !_options.isRoomProvided) {
+        if (room.e2eeManager != null) {
+          // Restart: the E2EE manager already exists from a previous session.
+          // Re-enable in case it was toggled off, before connect publishes
+          // any tracks.
+          await room.setE2EEEnabled(true);
+        } else {
+          // First start: create the key provider and configure room options.
+          // The E2EE manager will be created during connect() with encryption
+          // enabled by default.
+          final BaseKeyProvider keyProvider = switch (encryption.key) {
+            SharedKeyEncryption(:final sharedKey) => await _createSharedKeyProvider(sharedKey),
+            KeyProviderEncryption(:final keyProvider) => keyProvider,
+          };
+          room.engine.roomOptions = room.engine.roomOptions.copyWith(
+            encryption: E2EEOptions(keyProvider: keyProvider),
+          );
+        }
+      }
       final bool dispatchesAgent;
       if (_options.preConnectAudio) {
         dispatchesAgent = await room.withPreConnectAudio(
@@ -229,6 +262,8 @@ class Session extends DisposableChangeNotifier {
       _setError(SessionError.connection(error));
       _setConnectionState(ConnectionState.disconnected);
       _agent.disconnected();
+    } finally {
+      _isStarting = false;
     }
   }
 
@@ -380,6 +415,12 @@ class Session extends DisposableChangeNotifier {
     _error = newError;
     notifyListeners();
   }
+
+  static Future<BaseKeyProvider> _createSharedKeyProvider(String sharedKey) async {
+    final keyProvider = await BaseKeyProvider.create();
+    await keyProvider.setSharedKey(sharedKey);
+    return keyProvider;
+  }
 }
 
 enum SessionErrorKind {

lib/src/agent/session_options.dart

@@ -13,12 +13,59 @@
 // limitations under the License.
 
 import '../core/room.dart';
+import '../e2ee/key_provider.dart';
+
+/// Encryption key configuration for a [Session].
+///
+/// Use one of the named constructors to specify either a shared passphrase
+/// or a pre-configured [BaseKeyProvider].
+sealed class SessionEncryptionKey {
+  const SessionEncryptionKey();
+
+  /// Use a shared passphrase string.
+  ///
+  /// A [BaseKeyProvider] is created internally using the string as a shared
+  /// key (recommended for maximum compatibility across SDKs).
+  const factory SessionEncryptionKey.sharedKey(String key) = SharedKeyEncryption;
+
+  /// Use a pre-configured [BaseKeyProvider] for custom key management.
+  const factory SessionEncryptionKey.keyProvider(BaseKeyProvider provider) = KeyProviderEncryption;
+}
+
+/// A shared passphrase used to derive encryption keys.
+class SharedKeyEncryption extends SessionEncryptionKey {
+  final String sharedKey;
+  const SharedKeyEncryption(this.sharedKey);
+}
+
+/// A pre-configured [BaseKeyProvider] instance.
+class KeyProviderEncryption extends SessionEncryptionKey {
+  final BaseKeyProvider keyProvider;
+  const KeyProviderEncryption(this.keyProvider);
+}
+
+/// Encryption configuration for a [Session].
+class SessionEncryptionOptions {
+  /// The encryption key, either a shared passphrase or a custom key provider.
+  final SessionEncryptionKey key;
+
+  const SessionEncryptionOptions({required this.key});
+
+  /// Creates encryption options with a shared passphrase string.
+  SessionEncryptionOptions.sharedKey(String key) : key = SharedKeyEncryption(key);
+
+  /// Creates encryption options with a pre-configured [BaseKeyProvider].
+  SessionEncryptionOptions.keyProvider(BaseKeyProvider provider) : key = KeyProviderEncryption(provider);
+}
 
 /// Options for creating a [Session].
 class SessionOptions {
   /// The underlying [Room] used by the session.
   final Room room;
 
+  /// Whether a custom [Room] was explicitly provided.
+  final bool isRoomProvided;
+
   /// Whether to enable audio pre-connect with [PreConnectAudioBuffer].
   ///
   /// If enabled, the microphone is activated before connecting to the room.
@@ -30,21 +77,55 @@ class SessionOptions {
   /// to a failed state.
   final Duration agentConnectTimeout;
 
+  /// Optional encryption configuration for end-to-end encryption.
+  ///
+  /// When provided, the session will configure E2EE on the room before
+  /// connecting. Use [Session.setEncryptionEnabled] to toggle encryption
+  /// after the session has started.
+  final SessionEncryptionOptions? encryption;
+
   SessionOptions({
     Room? room,
     this.preConnectAudio = true,
     this.agentConnectTimeout = const Duration(seconds: 20),
-  }) : room = room ?? Room();
+    this.encryption,
+  })  : isRoomProvided = room != null,
+        room = room ?? Room() {
+    _validateEncryptionConfiguration();
+  }
+
+  SessionOptions._({
+    required this.room,
+    required this.isRoomProvided,
+    required this.preConnectAudio,
+    required this.agentConnectTimeout,
+    this.encryption,
+  }) {
+    _validateEncryptionConfiguration();
+  }
 
   SessionOptions copyWith({
     Room? room,
     bool? preConnectAudio,
     Duration? agentConnectTimeout,
+    SessionEncryptionOptions? encryption,
   }) {
-    return SessionOptions(
+    return SessionOptions._(
       room: room ?? this.room,
+      isRoomProvided: room != null ? true : isRoomProvided,
       preConnectAudio: preConnectAudio ?? this.preConnectAudio,
       agentConnectTimeout: agentConnectTimeout ?? this.agentConnectTimeout,
+      encryption: encryption ?? this.encryption,
     );
   }
+
+  void _validateEncryptionConfiguration() {
+    if (isRoomProvided && encryption != null) {
+      throw ArgumentError.value(
+        encryption,
+        'encryption',
+        'Cannot be provided when room is also provided. Configure E2EE on the Room directly.',
+      );
+    }
+  }
 }