feat: Centralize platform credential handling in CredentialConfig (#300)

## What this changes

Platform credential variance moves into the per-platform
`CredentialConfig`, the same way the per-platform path templates already
absorb endpoint differences. The consumers lose their inline
credential-type switches:

- **`baseHeaders(credential, userAgent)`** — io sends the user agent
under `user-agent` and carries the credential in the `authorization`
header; web sends the user agent under `x-launchdarkly-user-agent` and
carries no authorization header. A browser only delivers the
authorization header when the target service's CORS pre-flight response
lists it as allowed, so a missed allow-list entry on any endpoint
silently breaks authentication; web therefore authenticates with the
`auth` query parameter, which is not subject to that allow-list (FDv1
client-side authentication is already URL-based). `_makeHttpProperties`
becomes a single `addAll`.
- **`environmentIdFallback(credential)`** — a client-side ID identifies
the environment directly, so it serves as the environment ID when a
connection exposes no response headers; a mobile key does not. Both the
FDv1 streaming data source and the polling requestor consume this
instead of checking the credential type inline.
- **`authQueryParameters(credential)`** — authentication for every data
acquisition request in the browser: `auth=<credential>` on web, empty on
io (every io transport authenticates via the base headers). No consumer
yet; the FDv2 sources (a later PR) use it for both streaming and
polling, since the FDv2 endpoint paths do not embed the credential the
way the FDv1 client-side paths do.

The unconsumed `common_client` copy of `NetworkConfig` is removed: the
restricted-header filter that actually executes reads the
`launchdarkly_dart_common` configuration, and keeping a dead duplicate
invites divergence.

Behavior is unchanged on every platform: io requests carry the same
headers as before, web requests carry the same headers as before, and
the environment ID fallback produces the same values.

## Testing

New tests cover the `CredentialConfig` methods for both platform
variants directly (header construction, auth query parameters,
environment ID fallback), and the streaming data source's environment ID
selection: taken from the `x-ld-envid` response header when present, and
from the platform fallback when the connection exposes no headers. The
streaming test harness now forwards the environment ID to the event
handler the way the production pipeline does. The remaining paths are
covered by the existing suite, which passes unchanged.

SDK-2188

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Touches authentication headers and environment ID resolution on every
HTTP/SSE path; behavior is intended to be unchanged but mistakes would
break SDK connectivity.
> 
> **Overview**
> Platform-specific credential behavior moves into per-platform
**`CredentialConfig`** (io, js, stub), replacing scattered
`CredentialType` switches in the client and data sources.
> 
> **`baseHeaders`**, **`authQueryParameters`**, and
**`environmentIdFallback`** encode how each platform sends user agent,
authenticates (header vs `auth` query on web), and resolves environment
ID when response headers are missing.
**`LDCommonClient._makeHttpProperties`**, **`Requestor`**, and
**`StreamingDataSource`** now call these APIs instead of inline
credential-type checks.
> 
> The unused **`NetworkConfig`** / `restrictedHeaders` duplicate in
`common_client` is removed. **`authQueryParameters`** is defined for
upcoming FDv2 consumers; FDv1 paths are unchanged in behavior.
> 
> Tests add direct **`CredentialConfig`** coverage for io and web, plus
streaming tests for environment ID from `x-ld-envid` vs platform
fallback.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
5a4c9b4. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: kinyoklion

packages/common_client/lib/src/config/defaults/io_config.dart

@@ -31,10 +31,6 @@ class DefaultEventPaths {
   }
 }
 
-class NetworkConfig {
-  Set<String> get restrictedHeaders => {};
-}
-
 final class DefaultEndpoints {
   final String polling = 'https://clientsdk.launchdarkly.com';
   final String streaming = 'https://clientstream.launchdarkly.com';
@@ -43,6 +39,19 @@ final class DefaultEndpoints {
 
 final class CredentialConfig {
   CredentialType get credentialType => CredentialType.mobileKey;
+
+  /// Headers applied to every request. Every service on this platform
+  /// authenticates with the authorization header.
+  Map<String, String> baseHeaders(String credential, String userAgent) =>
+      {'user-agent': userAgent, 'authorization': credential};
+
+  /// Every transport on this platform supports custom headers, so no
+  /// query parameter authentication is needed.
+  Map<String, String> authQueryParameters(String credential) => const {};
+
+  /// A mobile key does not identify an environment; the environment ID
+  /// comes only from response headers.
+  String? environmentIdFallback(String credential) => null;
 }
 
 final class DefaultDataSourceConfig {

packages/common_client/lib/src/config/defaults/js_config.dart

@@ -31,10 +31,6 @@ class DefaultEventPaths {
   }
 }
 
-class NetworkConfig {
-  Set<String> get restrictedHeaders => {'user-agent', 'authorization'};
-}
-
 final class DefaultEndpoints {
   final String polling = 'https://clientsdk.launchdarkly.com';
   final String streaming = 'https://clientstream.launchdarkly.com';
@@ -43,6 +39,28 @@ final class DefaultEndpoints {
 
 final class CredentialConfig {
   CredentialType get credentialType => CredentialType.clientSideId;
+
+  /// Headers applied to every request. The user agent is sent under a
+  /// vendor header because browsers forbid setting `user-agent`. The
+  /// authorization header is intentionally absent: a browser only
+  /// delivers it when the service's CORS pre-flight response lists it
+  /// as an allowed header, so authentication uses the `auth` query
+  /// parameter instead, which is not subject to that allow-list.
+  Map<String, String> baseHeaders(String credential, String userAgent) =>
+      {'x-launchdarkly-user-agent': userAgent};
+
+  /// Authentication for every data acquisition request in the browser.
+  /// The `auth` query parameter is used at all times rather than the
+  /// authorization header: the header depends on each service's CORS
+  /// pre-flight allowing it (a missed allow-list entry silently breaks
+  /// authentication), and the browser's native EventSource cannot send
+  /// custom headers at all.
+  Map<String, String> authQueryParameters(String credential) =>
+      {'auth': credential};
+
+  /// A client-side ID identifies the environment directly, so it serves
+  /// as the environment ID when response headers are unavailable.
+  String? environmentIdFallback(String credential) => credential;
 }
 
 final class DefaultDataSourceConfig {

packages/common_client/lib/src/config/defaults/stub_config.dart

@@ -31,10 +31,6 @@ class DefaultEventPaths {
   }
 }
 
-class NetworkConfig {
-  Set<String> get restrictedHeaders => throw Exception('Stub implementation');
-}
-
 final class DefaultEndpoints {
   DefaultEndpoints() {
     throw Exception('Stub implementation');
@@ -47,6 +43,15 @@ final class DefaultEndpoints {
 
 final class CredentialConfig {
   CredentialType get credentialType => throw Exception('Stub implementation');
+
+  Map<String, String> baseHeaders(String credential, String userAgent) =>
+      throw Exception('Stub implementation');
+
+  Map<String, String> authQueryParameters(String credential) =>
+      throw Exception('Stub implementation');
+
+  String? environmentIdFallback(String credential) =>
+      throw Exception('Stub implementation');
 }
 
 final class DefaultDataSourceConfig {

packages/common_client/lib/src/data_sources/requestor.dart

@@ -4,7 +4,6 @@ import 'package:http/http.dart' as http;
 import 'package:launchdarkly_dart_common/launchdarkly_dart_common.dart';
 
 import '../config/data_source_config.dart';
-import '../config/defaults/credential_type.dart';
 import '../config/defaults/default_config.dart';
 import 'data_source.dart';
 import 'data_source_status.dart';
@@ -96,15 +95,8 @@ final class Requestor {
         _lastEtag = etag;
       }
 
-      var environmentId = getEnvironmentId(res.headers);
-
-      if (environmentId == null &&
-          DefaultConfig.credentialConfig.credentialType ==
-              CredentialType.clientSideId) {
-        // When using a client-side ID we can use it to represent the
-        // environment.
-        environmentId = _credential;
-      }
+      final environmentId = getEnvironmentId(res.headers) ??
+          DefaultConfig.credentialConfig.environmentIdFallback(_credential);
 
       return DataEvent('put', res.body, environmentId: environmentId);
     }

packages/common_client/lib/src/data_sources/streaming_data_source.dart

@@ -5,7 +5,6 @@ import 'package:launchdarkly_dart_common/launchdarkly_dart_common.dart';
 import 'package:launchdarkly_event_source_client/launchdarkly_event_source_client.dart';
 
 import '../config/data_source_config.dart';
-import '../config/defaults/credential_type.dart';
 import '../config/defaults/default_config.dart';
 import 'data_source.dart';
 import 'data_source_status.dart';
@@ -184,11 +183,9 @@ final class StreamingDataSource implements DataSource {
           _logger.debug('Received connect event, data: ${event.headers}');
           if (event.headers != null) {
             _environmentId = getEnvironmentId(event.headers);
-          } else if (DefaultConfig.credentialConfig.credentialType ==
-              CredentialType.clientSideId) {
-            // When using a client-side ID we can use it to represent the
-            // environment.
-            _environmentId = _credential;
+          } else {
+            _environmentId = DefaultConfig.credentialConfig
+                .environmentIdFallback(_credential);
           }
       }
     })

packages/common_client/lib/src/ld_common_client.dart

@@ -314,15 +314,8 @@ final class LDCommonClient {
 
     final userAgentString = '${_sdkData.name}/${_sdkData.version}';
 
-    switch (DefaultConfig.credentialConfig.credentialType) {
-      case CredentialType.mobileKey:
-        additionalHeaders['user-agent'] = userAgentString;
-        // When using a mobile key the credential appears in the headers. For
-        // a client-side ID the credential is in the URL.
-        additionalHeaders['authorization'] = _config.sdkCredential;
-      case CredentialType.clientSideId:
-        additionalHeaders['x-launchdarkly-user-agent'] = userAgentString;
-    }
+    additionalHeaders.addAll(DefaultConfig.credentialConfig
+        .baseHeaders(_config.sdkCredential, userAgentString));
 
     return _config.httpProperties.withHeaders(additionalHeaders);
   }

packages/common_client/test/config/credential_config_test.dart

@@ -0,0 +1,57 @@
+import 'package:launchdarkly_common_client/src/config/defaults/io_config.dart'
+    as io;
+import 'package:launchdarkly_common_client/src/config/defaults/js_config.dart'
+    as js;
+import 'package:test/test.dart';
+
+void main() {
+  group('io CredentialConfig', () {
+    final config = io.CredentialConfig();
+
+    test('base headers carry the user agent and the credential', () {
+      expect(
+          config.baseHeaders('the-mobile-key', 'Sdk/1.0'),
+          equals({
+            'user-agent': 'Sdk/1.0',
+            'authorization': 'the-mobile-key',
+          }));
+    });
+
+    test('no auth query parameters; every transport supports headers', () {
+      expect(config.authQueryParameters('the-mobile-key'), isEmpty);
+    });
+
+    test(
+        'no environment ID fallback; a mobile key does not identify an '
+        'environment', () {
+      expect(config.environmentIdFallback('the-mobile-key'), isNull);
+    });
+  });
+
+  group('web CredentialConfig', () {
+    final config = js.CredentialConfig();
+
+    test(
+        'base headers carry the vendor user agent and no authorization '
+        'header', () {
+      expect(
+          config.baseHeaders('the-client-side-id', 'Sdk/1.0'),
+          equals({
+            'x-launchdarkly-user-agent': 'Sdk/1.0',
+          }),
+          reason: 'browsers only deliver the authorization header when the '
+              'service CORS pre-flight allows it, so web requests '
+              'authenticate with the auth query parameter instead');
+    });
+
+    test('the auth query parameter authenticates browser requests', () {
+      expect(config.authQueryParameters('the-client-side-id'),
+          equals({'auth': 'the-client-side-id'}));
+    });
+
+    test('the client-side ID serves as the environment ID fallback', () {
+      expect(config.environmentIdFallback('the-client-side-id'),
+          equals('the-client-side-id'));
+    });
+  });
+}

packages/common_client/test/data_sources/streaming_data_source_test.dart

@@ -1,6 +1,7 @@
 // ignore_for_file: close_sinks
 
 import 'dart:async';
+import 'dart:collection';
 
 import 'package:http/testing.dart';
 import 'package:launchdarkly_common_client/launchdarkly_common_client.dart';
@@ -18,7 +19,7 @@ import 'package:http/http.dart' as http;
 import 'package:test/test.dart';
 
 class MockSseClient implements SSEClient {
-  final Stream<MessageEvent> mockStream;
+  final Stream<Event> mockStream;
 
   MockSseClient(this.mockStream);
 
@@ -29,7 +30,7 @@ class MockSseClient implements SSEClient {
   void restart() {}
 
   @override
-  Stream<MessageEvent> get stream => mockStream;
+  Stream<Event> get stream => mockStream;
 
   @override
   bool hasCapability(SSECapability capability) => true;
@@ -39,7 +40,7 @@ class MockSseClient implements SSEClient {
   StreamingDataSource,
   FlagManager,
   DataSourceStatusManager
-) makeDataSourceForTest(Stream<MessageEvent> mockStream,
+) makeDataSourceForTest(Stream<Event> mockStream,
     {LDContext? inContext,
     HttpProperties? inProperties,
     bool useReport = false,
@@ -85,7 +86,8 @@ class MockSseClient implements SSEClient {
   streaming.events.asyncMap((event) async {
     switch (event) {
       case DataEvent():
-        return eventHandler.handleMessage(context, event.type, event.data);
+        return eventHandler.handleMessage(context, event.type, event.data,
+            environmentId: event.environmentId);
       case StatusEvent():
         if (event.statusCode != null) {
           statusManager.setErrorResponse(event.statusCode!, event.message,
@@ -498,4 +500,49 @@ void main() {
       expect(actualMethod, 'REPORT');
     });
   });
+
+  group('environment ID from the stream connection', () {
+    test('it uses the environment ID response header', () async {
+      final controller = StreamController<Event>();
+      final (dataSource, flagManager, _) =
+          makeDataSourceForTest(controller.stream);
+      dataSource.start();
+
+      controller.sink.add(OpenEvent(
+          headers: UnmodifiableMapView({'x-ld-envid': 'env-from-header'})));
+      controller.sink.add(MessageEvent(
+          'put',
+          '{"my-boolean-flag": '
+              '{"version":11,"value":true,"variation":0,"trackEvents":false}}',
+          null));
+      for (var i = 0; i < 5; i++) {
+        await Future<void>.delayed(Duration.zero);
+      }
+
+      expect(flagManager.environmentId, 'env-from-header');
+    });
+
+    test(
+        'it uses the platform environment ID fallback when the connection '
+        'provides no headers', () async {
+      final controller = StreamController<Event>();
+      final (dataSource, flagManager, _) =
+          makeDataSourceForTest(controller.stream);
+      dataSource.start();
+
+      controller.sink.add(OpenEvent(headers: null));
+      controller.sink.add(MessageEvent(
+          'put',
+          '{"my-boolean-flag": '
+              '{"version":11,"value":true,"variation":0,"trackEvents":false}}',
+          null));
+      for (var i = 0; i < 5; i++) {
+        await Future<void>.delayed(Duration.zero);
+      }
+
+      // A mobile key does not identify an environment, so the fallback
+      // is null on this platform.
+      expect(flagManager.environmentId, isNull);
+    });
+  });
 }