Merge remote-tracking branch 'origin/main' into hiroshi/microphone-mute-mode

Author: hiroshihorie

.changes/add-certificate-pinning

@@ -0,0 +1 @@
+minor type="added" "Add native certificate pinning for SDK-owned connections"

.changes/single-disconnect-event

@@ -0,0 +1 @@
+patch type="fixed" "Emit a single disconnected event when connecting fails"

README.md

@@ -197,6 +197,107 @@ try {
 await room.localParticipant.setMicrophoneEnabled(true);
 ```
 
+### Certificate pinning
+
+Certificate pinning is available for native platforms through `RoomOptions.networkOptions`. It applies to SDK-owned WSS signaling and internal HTTPS requests. It does not apply to WebRTC media, TURN, or application-owned token endpoints.
+
+Certificate pinning is not supported on Flutter web because browsers do not expose certificate material to application code. Configuring it on web is treated as a misconfiguration and fails fast: `Room.connect` throws `UnsupportedError` instead of silently connecting without pinning. Only enable `certificatePinning` on web builds if you want that behavior, otherwise leave it unset when targeting web.
+
+On native platforms, validation runs during TLS connection setup after the peer certificate is available and before the SDK writes HTTP or WSS request bytes. If validation fails, request headers and bodies are not sent.
+
+Rules are selected by host. Exact hosts like `project.livekit.cloud`, single-label wildcards like `*.livekit.cloud`, multi-label wildcards like `**.livekit.cloud`, and `*` are supported. `*.livekit.cloud` matches `project.livekit.cloud`, but not `a.b.livekit.cloud`. `**.livekit.cloud` matches both. Rules with empty `hosts` apply to every SDK-owned TLS connection.
+
+Hosts that match no rule are connected with platform trust only, and the SDK logs a warning. Keep in mind the SDK also connects to hosts you did not write yourself: LiveKit Cloud region failover uses server-provided regional hostnames like `project.region.production.livekit.cloud`, which carry more labels than your project URL. Use `**.livekit.cloud` so pinning also covers those hosts, and make sure the pin set includes the keys the regional endpoints serve.
+
+All rules that match the connection host are applied. Within one check type, any configured value may match. Across check types, each configured type must pass. For example, two matching SPKI rules are treated as one accepted pin set, while SPKI pins plus exact leaf certificates require both the SPKI check and the exact leaf certificate check to pass.
+
+Use SPKI SHA-256 pins when possible. `primaryPins` and `backupPins` are both accepted. Backup pins are useful for certificate rotation because the SDK accepts either set.
+
+SPKI pins are matched against the leaf certificate's public key only. Unlike OkHttp or HPKP, the rest of the chain is not checked because Dart does not expose it, so pinning an intermediate or root CA key never matches and fails every connection. Pin leaf keys, and use backup pins for the future leaf keys you plan to rotate to.
+
+```dart
+final roomOptions = RoomOptions(
+  networkOptions: NetworkOptions(
+    certificatePinning: CertificatePinningOptions(
+      rules: [
+        CertificatePinningRule(
+          hosts: ['**.livekit.cloud'],
+          primaryPins: ['sha256/current-public-key-pin'],
+          backupPins: [
+            'sha256/next-public-key-pin-1',
+            'sha256/next-public-key-pin-2',
+          ],
+        ),
+      ],
+    ),
+  ),
+);
+
+final room = Room(roomOptions: roomOptions);
+await room.connect(url, token);
+```
+
+To generate an SPKI pin:
+
+```bash
+openssl s_client -connect your-host:443 -servername your-host </dev/null 2>/dev/null \
+  | openssl x509 -pubkey -noout \
+  | openssl pkey -pubin -outform der \
+  | openssl dgst -sha256 -binary \
+  | openssl base64
+```
+
+Prefix the output with `sha256/` before passing it to `primaryPins` or `backupPins`.
+
+Certificate rules can also enforce exact leaf certificates or a custom TLS trust store.
+
+Use `pinnedLeafCertificates` to require an exact peer leaf certificate after TLS trust validation succeeds. Renewing or changing the leaf certificate requires shipping updated pinned certificates.
+
+By itself, `pinnedLeafCertificates` does not trust private or self-signed certificates. For private PKI, also configure `trustedCertificates` with the leaf, intermediate, or root certificate that should anchor TLS validation.
+
+```dart
+final certificate = await CertificateBytes.fromAsset(
+  'assets/livekit_leaf_cert.pem',
+);
+
+final roomOptions = RoomOptions(
+  networkOptions: NetworkOptions(
+    certificatePinning: CertificatePinningOptions(
+      rules: [
+        CertificatePinningRule(
+          hosts: ['my-project.livekit.cloud'],
+          pinnedLeafCertificates: [certificate],
+          trustedCertificates: [certificate],
+        ),
+      ],
+    ),
+  ),
+);
+```
+
+Use `trustedCertificates` to validate TLS against a custom trust store, similar to `SecurityContext.setTrustedCertificatesBytes`. The SDK builds a per-connection trust store from these certificates and does not include the platform trusted roots for that host. The bytes can contain a leaf, intermediate, or root certificate.
+
+```dart
+final certificate = await CertificateBytes.fromAsset(
+  'assets/livekit_intermediate_ca.pem',
+);
+
+final roomOptions = RoomOptions(
+  networkOptions: NetworkOptions(
+    certificatePinning: CertificatePinningOptions(
+      rules: [
+        CertificatePinningRule(
+          hosts: ['**.livekit.cloud'],
+          trustedCertificates: [certificate],
+        ),
+      ],
+    ),
+  ),
+);
+```
+
+When a pinning rule matches a host, the SDK owns TLS setup for that connection and `HttpOverrides.global` or `HttpClient.badCertificateCallback` are not consulted. An app that relies on a bad certificate callback to accept a self-signed server certificate will see a `HandshakeException` once pinning is enabled for that host. Use `trustedCertificates` to trust the self-signed or private CA certificate instead.
+
 ### Screen sharing
 
 Screen sharing is supported across all platforms. You can enable it with:

lib/src/core/engine.dart

@@ -268,9 +268,16 @@ class Engine extends Disposable with EventsEmittable<EngineEvent> {
     } catch (error) {
       logger.fine('Connect Error $error');
 
-      events.emit(EngineDisconnectedEvent(
-        reason: DisconnectReason.joinFailure,
-      ));
+      // during a reconnect this connect() runs inside restartConnection and
+      // attemptReconnect owns disconnect emission, emitting here as well
+      // would produce two events for one failure
+      if (!_isReconnecting && !_attemptingReconnect) {
+        events.emit(EngineDisconnectedEvent(
+          reason: error is CertificatePinningException
+              ? DisconnectReason.signalingConnectionFailure
+              : DisconnectReason.joinFailure,
+        ));
+      }
       rethrow;
     }
   }
@@ -1096,18 +1103,25 @@ class Engine extends Disposable with EventsEmittable<EngineEvent> {
         fullReconnectOnNext = true;
       }
 
-      if (e is UnexpectedConnectionState) {
+      if (e is UnexpectedConnectionState || e is CertificatePinningException) {
+        // certificate pinning failures are deterministic, retrying would only
+        // repeat TLS handshakes against an untrusted endpoint
         recoverable = false;
       }
 
       if (recoverable) {
         unawaited(handleReconnect(ClientDisconnectReason.reconnectRetry));
       } else {
         logger.fine('attemptReconnect: disconnecting...');
+        // clean up before emitting, room's EngineDisconnectedEvent handler
+        // drops the event while fullReconnectOnNext is still true and
+        // cleanUp() is what resets it
+        await cleanUp();
         events.emit(EngineDisconnectedEvent(
-          reason: DisconnectReason.disconnected,
+          reason: e is CertificatePinningException
+              ? DisconnectReason.signalingConnectionFailure
+              : DisconnectReason.disconnected,
         ));
-        await cleanUp();
       }
     } finally {
       _attemptingReconnect = false;
@@ -1216,6 +1230,15 @@ class Engine extends Disposable with EventsEmittable<EngineEvent> {
       _regionUrlProvider?.resetAttempts();
       events.emit(const EngineRestartedEvent());
     } catch (error) {
+      // Certificate pinning failures skip region failover. The pin set is
+      // client-wide config, so every region would be validated against the
+      // same pins and each attempt is another TLS handshake with an endpoint
+      // that already failed validation. Initial connect behaves the same way,
+      // room.connect only fails over on WebSocketException/ConnectException.
+      if (error is CertificatePinningException) {
+        _regionUrlProvider?.resetAttempts();
+        rethrow;
+      }
       final nextRegionUrl = await _regionUrlProvider?.getNextBestRegionUrl();
       if (nextRegionUrl != null) {
         await restartConnection(regionUrl: nextRegionUrl);
@@ -1351,11 +1374,12 @@ class Engine extends Disposable with EventsEmittable<EngineEvent> {
       if (event.reason == DisconnectReason.disconnected && !_isClosed) {
         await handleReconnect(ClientDisconnectReason.signal,
             reconnectReason: lk_models.ReconnectReason.RR_SIGNAL_DISCONNECTED);
-      } else if (event.reason == DisconnectReason.signalingConnectionFailure) {
-        events.emit(EngineDisconnectedEvent(
-          reason: event.reason,
-        ));
       }
+      // signalingConnectionFailure is intentionally not relayed as
+      // EngineDisconnectedEvent here. The signal client emits it while the
+      // connect() call is failing, so connect()'s own catch (initial connect)
+      // or attemptReconnect (reconnect) already emits the engine event, and
+      // relaying here produced a duplicate disconnect per failure.
     })
     ..on<SignalOfferEvent>((event) async {
       if (subscriber == null) {

lib/src/core/room.dart

@@ -16,7 +16,6 @@ import 'dart:async';
 import 'dart:typed_data' show Uint8List;
 
 import 'package:collection/collection.dart';
-import 'package:http/http.dart' as http;
 import 'package:meta/meta.dart';
 
 import '../audio/audio_manager.dart';
@@ -42,6 +41,7 @@ import '../proto/livekit_rtc.pb.dart' as lk_rtc;
 import '../rpc/rpc_client_manager.dart';
 import '../rpc/rpc_server_manager.dart';
 import '../support/disposable.dart';
+import '../support/http_client.dart';
 import '../support/platform.dart';
 import '../support/region_url_provider.dart';
 import '../support/websocket.dart' show WebSocketException;
@@ -237,20 +237,20 @@ class Room extends DisposableChangeNotifier with EventsEmittable<RoomEvent> {
     logger.info('prepareConnection to $url');
     try {
       if (isCloudUrl(Uri.parse(url)) && token != null) {
-        _regionUrlProvider = RegionUrlProvider(token: token, url: url);
+        _regionUrlProvider = RegionUrlProvider(token: token, url: url, networkOptions: roomOptions.networkOptions);
         final regionUrl = await _regionUrlProvider!.getNextBestRegionUrl();
         // we will not replace the regionUrl if an attempt had already started
         // to avoid overriding regionUrl after a new connection attempt had started
         if (regionUrl != null && connectionState == ConnectionState.disconnected) {
           _regionUrl = regionUrl;
-          await http.head(Uri.parse(toHttpUrl(regionUrl)));
+          await sdkHttpHead(Uri.parse(toHttpUrl(regionUrl)), networkOptions: roomOptions.networkOptions);
           logger.fine('prepared connection to ${regionUrl}');
         }
       } else {
-        await http.head(Uri.parse(toHttpUrl(url)));
+        await sdkHttpHead(Uri.parse(toHttpUrl(url)), networkOptions: roomOptions.networkOptions);
       }
     } catch (e) {
-      logger.warning('could not prepare connection');
+      logger.warning('could not prepare connection: $e');
     }
   }
 
@@ -262,6 +262,10 @@ class Room extends DisposableChangeNotifier with EventsEmittable<RoomEvent> {
     FastConnectOptions? fastConnectOptions,
   }) async {
     var roomOptions = this.roomOptions;
+    if (lkPlatformIs(PlatformType.web) && (roomOptions.networkOptions.certificatePinning?.isEnabled ?? false)) {
+      throw UnsupportedError('Certificate pinning is not supported on Flutter web, '
+          'remove certificatePinning from NetworkOptions when targeting web');
+    }
     connectOptions ??= ConnectOptions();
     _pendingTrackQueue.updateTtl(connectOptions.timeouts.subscribe);
     // ignore: deprecated_member_use_from_same_package
@@ -293,7 +297,7 @@ class Room extends DisposableChangeNotifier with EventsEmittable<RoomEvent> {
     }
     if (isCloudUrl(Uri.parse(url))) {
       if (_regionUrlProvider == null) {
-        _regionUrlProvider = RegionUrlProvider(url: url, token: token);
+        _regionUrlProvider = RegionUrlProvider(url: url, token: token, networkOptions: roomOptions.networkOptions);
       } else {
         _regionUrlProvider?.updateToken(token);
       }

lib/src/core/signal_client.dart

@@ -20,7 +20,6 @@ import 'package:flutter/foundation.dart' show kIsWeb;
 import 'package:connectivity_plus/connectivity_plus.dart';
 import 'package:fixnum/fixnum.dart';
 import 'package:flutter_webrtc/flutter_webrtc.dart' as rtc;
-import 'package:http/http.dart' as http;
 import 'package:meta/meta.dart';
 
 import '../events.dart';
@@ -33,6 +32,7 @@ import '../options.dart';
 import '../proto/livekit_models.pb.dart' as lk_models;
 import '../proto/livekit_rtc.pb.dart' as lk_rtc;
 import '../support/disposable.dart';
+import '../support/http_client.dart';
 import '../support/platform.dart';
 import '../support/websocket.dart';
 import '../types/other.dart';
@@ -163,13 +163,24 @@ class SignalClient extends Disposable with EventsEmittable<SignalEvent> {
         headers: {
           'Authorization': 'Bearer $token',
         },
+        networkOptions: roomOptions.networkOptions,
       );
       future = future.timeout(connectOptions.timeouts.connection);
       _ws = await future;
       // Successful connection
       _connectionState = ConnectionState.connected;
       events.emit(const SignalConnectedEvent());
     } catch (socketError) {
+      if (socketError is CertificatePinningException) {
+        // In reconnect mode the engine owns state and event emission,
+        // emitting here would race its reconnect handling.
+        if (!reconnect) {
+          _connectionState = ConnectionState.disconnected;
+          events.emit(SignalDisconnectedEvent(reason: DisconnectReason.signalingConnectionFailure));
+        }
+        rethrow;
+      }
+
       // Skip validation if reconnect mode
       if (reconnect) rethrow;
 
@@ -186,11 +197,12 @@ class SignalClient extends Disposable with EventsEmittable<SignalEvent> {
           forceSecure: rtcUri.isSecureScheme,
         );
 
-        final validateResponse = await http.get(
+        final validateResponse = await sdkHttpGet(
           validateUri,
           headers: {
             'Authorization': 'Bearer $token',
           },
+          networkOptions: roomOptions.networkOptions,
         );
         if (validateResponse.statusCode != 200) {
           finalError = ConnectException(validateResponse.body,

lib/src/exceptions.dart

@@ -51,6 +51,18 @@ class MediaConnectException extends LiveKitException {
   MediaConnectException([String msg = 'Ice connection failed']) : super._(msg);
 }
 
+/// Certificate pinning validation failed for an SDK-owned TLS connection.
+class CertificatePinningException extends LiveKitException {
+  final String host;
+  final String? presentedPin;
+
+  CertificatePinningException(
+    String msg, {
+    required this.host,
+    this.presentedPin,
+  }) : super._(msg);
+}
+
 /// An internal state of the SDK is not correct and can not continue to execute.
 /// This should not occur frequently.
 class UnexpectedStateException extends LiveKitException {